Add the Changes tab: changes.mjs and a diff block for the sign-off page

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-14 18:33:03 -08:00
1 parent cb64a8d15e
commit 7021ff9a48
10 files changed
+741 -14

No files matched your search

+1 -1
View File
@@ -27,7 +27,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `console-docs.md` | the topic file for `docs` in a patch (tabs of blocks), named by the console at the first patch that carries `docs`; not read up front. Byte-budgeted with the card and the notes in `scripts/test-console-wire-budgets.mjs` |
| `pointers.mjs` | which topic file the console names and when: once per session per topic, remembered in the session folder (`pointers.json`), reset by a resume |
| `metrics-pattern.json` | the PLAN-DRAFT scrape shapes the bait scanner in `patches.mjs` reads (`METRICS_BAIT`); one of three copies with the skill scripts' `SCRAPE` and `plan2code-metrics/src/metrics-pattern.json`, which `test-web-console-hardening.mjs` keeps in step |
| `patches.mjs` | checking and merging an agent's patch into the session state: `validate()` (the house rules; allows `templates` only as `"idea"` on a `text` item, anything else exits 3; the `lessons` kind, the approval card `lessons.mjs list` prints, is checked by `lessonsProblems()` against `LESSON_ROW_TYPES`, only one may be open at a time, and it is the one card the dashboard accepts, drawn there in a dialog for Review from the Learning banner; its `rows` and its `firstAsk.lesson` are the project's own words, which Keep saves as noted, so the wording scan leaves them out and checks only the card's own title, body, opening and first-ask sentences), the patch merge, `resolveDocFiles()` and `applyPatch()` |
| `patches.mjs` | checking and merging an agent's patch into the session state: `validate()` (the house rules; allows `templates` only as `"idea"` on a `text` item, anything else exits 3; the `lessons` kind, the approval card `lessons.mjs list` prints, is checked by `lessonsProblems()` against `LESSON_ROW_TYPES`, only one may be open at a time, and it is the one card the dashboard accepts, drawn there in a dialog for Review from the Learning banner; its `rows` and its `firstAsk.lesson` are the project's own words, which Keep saves as noted, so the wording scan leaves them out and checks only the card's own title, body, opening and first-ask sentences), the patch merge, `resolveDocFiles()` (`file` blocks and the refresh of `file` and `diff` blocks), `resolveDocImages()` (`image` blocks, and `diff` blocks: `{ id, diff: "changes.diff" }` names a `.diff` file directly in the session folder, read with `fs.realpathSync.native` confined to that folder and cut at `DOC_FILE_MAX` with the too-large line; stored as `diff` plus `text`, left out of the wording scan) and `applyPatch()` |
| `routes.mjs` | every URL the page can call, in one ordered list (`ROUTES`, walked by `handle()`); `server.mjs` hands each request to it. Learning's three: `POST /learning/pause` (origin-checked; `{ paused: boolean }`, `400 bad-request` otherwise, `409 not-on` unless Learning is on or paused) writes the personal pause through `writePause()` (`pause.json` under `~/.plan2code/learning/<key>/`, the server's only write for Learning, never into the project), patches `scan.learning` in `state.json` in place and pushes it, so the row repaints with no agent; `GET /learning/state` returns `learningScan()` worked out now (`{}` when the settings format is unknown; the Loop's stop card, a page after a pause); `GET /learning/lessons` returns `{ files: [{ name, title, text }] }` for Open the lessons, read-only: `general.md` first, then every other `.md` directly in the project's `.plan2code/lessons/` in name order, plain files only (no link, no sub-folder, at most 100 files of 512 KB each). Both `GET`s send `cache-control: no-store` |
| `scan.mjs` | what the dashboard knows about the repo: `scanProject()`, `classifySpec()` (a folder's files to a spec state; a `DIAGNOSIS-*.md` gives `diagnosed` or `fixed`, an `UPGRADE-*.md` brief from Update dependencies `upgrade` ("Upgrade ready") or, once its `**Status:**` reads `Done`, `upgraded` ("Upgrade done"), and a plan conversation or pathfinder map wins over either), `TASK_LINE_RE` (re-exported from `spec-files.mjs`) and `removeSpec()`. `open` (`cmd-open.mjs`) adds three fields that live outside the repo's specs, so `specs.mjs list` never sees them: `handoffs`, `handoffsDir` and `learning` (`learningScan()`: `{ state, pausedSince, waiting, oldestDays }`, `state` one of `not-set-up`, `off`, `on`, `paused`; left out when the settings format is unknown or the read fails, so the page draws no Learning row) |
| `sessions.mjs` | a session's roots and handle files (`repoRoots()`, `healthOk()`, `attachmentName()`: the kept-file name `<slug>-<id8>.<ext>`, the same upload always gets the same name, `readOverview()`) and the console folder's housekeeping: the three sweeps `open` runs fire-and-forget after it prints (`sweepUploads()`, `staleSessions()` / `removeSessions()`, `staleScratch()` / `removeScratch()`) and `cleanupFindings()` / `removeCleanup()` for User Preferences → System → Cleanup. `KEPT_PLAN2CODE_ENTRIES` names the entries at the top of `~/.plan2code/` that Cleanup never offers (`console`, `bin`, `launcher.json`, `install.json`, `models.json`, `handoffs`, `notepads`, `app`, `app.json`, `agents.json`, `prototypes`, `learning`); a new top-level entry joins it and the Cleanup test in `scripts/test-web-console-server.mjs` |
@@ -30,6 +30,8 @@ A rule stated in six files is read six times and still skipped. The console sees
Documents are read from `file` blocks rather than pasted so the page and the disk cannot disagree, and a progress post only has to ask for `refresh`. `assumed` and `draft` exist so a half-finished doc is not read as decisions. A doc `version` never goes back because the page keys its "new version" marker on it.
A `diff` block follows the same rule: the agent writes a change set to a `.diff` file with `changes.mjs diff` and names it, so the agent never carries a patch through its own context and a large change costs a few typed tokens, not thousands. The server only reads it (read-only, the one file named, directly inside the session folder, so a block can never point the page at a project or system file) and caps it at the file block's 512 KB. Its text is code the repository holds, so the wording scan leaves it out as it does a `file` block.
## Noted questions
A person's note on an open question may change what it asks, and the agent's reply in the thread does not say what happens to the question. The server therefore records the fact (`noted`) when the note lands, and `validate()` refuses a new open required question until each noted one is reworded, deleted or confirmed with `stands: true`. A thread cannot answer this: it stays true forever after one reply. The page shows the same flag as a tag, and keeps the arrival notice and a New mark until the new question is opened, since eight seconds is easy to miss mid-sentence.
+3 -3
View File
@@ -208,7 +208,7 @@ const SOURCE_PROMPTS = [
// ui-prototype.md rides along (with its references, shell and scripts) for the
// offer of a UI prototype, which runs in the same conversation; every carried
// name starts with ui-prototype so none collides with this skill's own files.
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs'],
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'changes.mjs', 'ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs'],
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
@@ -280,7 +280,7 @@ const SOURCE_PROMPTS = [
description: 'Execute implementation phase by phase',
// review.md rides along for the web console's review offer on the sign-off
// card, which runs the review in the same session before the phase is approved.
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs'],
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'changes.mjs'],
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
@@ -298,7 +298,7 @@ const SOURCE_PROMPTS = [
name: 'implement-review',
displayName: 'Implementation + Review Mode',
description: 'Implement one phase, review it, then request sign-off',
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs'],
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'changes.mjs'],
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'plan2code-3-implement.md', target: 'implement.md' },
+1 -1
View File
@@ -13,7 +13,7 @@
"play": "node scripts/play.mjs",
"pretest": "node scripts/fix-line-endings.mjs",
"test:fast": "node scripts/test-fast.mjs",
"test": "node scripts/check-test-lanes.mjs && node scripts/validate-char-count.js && node install.js --build-skills && node scripts/check-versions.mjs && node scripts/check-doc-size.mjs && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node scripts/check-prompt-wording.mjs && node scripts/check-console-openings.mjs && node scripts/node-test.mjs scripts/test-line-endings.mjs scripts/test-us-english.mjs scripts/test-script-git.mjs scripts/test-git-repo.mjs scripts/test-skill-scripts.mjs scripts/test-script-test-map.mjs scripts/test-script-lessons.mjs scripts/test-script-test-match.mjs scripts/test-script-test-commands.mjs scripts/test-script-run-check.mjs scripts/test-script-pr-prep.mjs scripts/test-script-dead-code.mjs scripts/test-script-deps.mjs scripts/test-script-ui-prototype.mjs scripts/test-script-coverage.mjs scripts/test-script-changelog.mjs scripts/test-web-console-git.mjs scripts/test-web-console-git-board.mjs scripts/test-web-console-chat.mjs scripts/test-web-console-subagents.mjs scripts/test-web-console-pointers.mjs scripts/test-web-console-learning.mjs scripts/test-console-wire-budgets.mjs scripts/test-web-console-speed.mjs scripts/test-web-console-qa.mjs scripts/test-web-console-concurrency.mjs scripts/test-web-console-workspace.mjs scripts/test-web-console-lifecycle.mjs scripts/test-web-console-chat-stress.mjs scripts/test-web-console-server.mjs scripts/test-web-console-session.mjs scripts/test-web-console-logic.mjs scripts/test-web-console-agents-doc.mjs scripts/test-web-console-prototypes.mjs scripts/test-web-console-activities.mjs scripts/test-web-console-activities-rapids.mjs scripts/test-web-console-activities-flock.mjs scripts/test-web-console-activities-bounce.mjs scripts/test-web-console-activities-bounce-game.mjs scripts/test-web-console-activities-ghoul.mjs scripts/test-web-console-activities-ghoul-graveyard.mjs scripts/test-web-console-activities-ghoul-grounds.mjs scripts/test-web-console-activities-ghoul-chapel.mjs scripts/test-web-console-activities-ghoul-sanatorium.mjs scripts/test-web-console-activities-ghoul-village.mjs scripts/test-web-console-activities-ghoul-mine.mjs scripts/test-web-console-activities-ghoul-carnival.mjs scripts/test-web-console-activities-ghoul-frozen.mjs scripts/test-web-console-activities-ghoul-bog.mjs scripts/test-web-console-activities-ghoul-lantern.mjs scripts/test-web-console-activities-ghoul-marrow.mjs scripts/test-web-console-activities-ghoul-mat.mjs scripts/test-web-console-activities-ghoul-eye.mjs scripts/test-web-console-activities-ghoul-bonestair.mjs scripts/test-web-console-activities-ghoul-heart.mjs scripts/test-web-console-activities-ghoul-ending.mjs scripts/test-web-console-activities-ghoul-ride.mjs scripts/test-web-console-activities-ghoul-cart.mjs scripts/test-web-console-activities-ghoul-sled.mjs scripts/test-web-console-activities-ghoul-banister.mjs scripts/test-web-console-activities-ghoul-gurney.mjs scripts/test-web-console-activities-ghoul-hearse.mjs scripts/test-web-console-activities-ghoul-wagon.mjs scripts/test-web-console-activities-ghoul-pew.mjs scripts/test-web-console-activities-ghoul-mower.mjs scripts/test-web-console-activities-ghoul-tray.mjs scripts/test-web-console-activities-ghoul-arms.mjs scripts/test-web-console-activities-ghoul-dice.mjs scripts/test-web-console-activities-ghoul-gameover.mjs scripts/test-web-console-activities-ghoul-intro.mjs scripts/test-web-console-activities-ghoul-bossintro.mjs scripts/test-web-console-activities-ghoul-story.mjs scripts/test-web-console-activities-ghoul-bones.mjs scripts/test-web-console-activities-ghoul-retry.mjs scripts/test-web-console-activities-bounce-cars.mjs scripts/test-web-console-activities-bounce-arcade.mjs scripts/test-web-console-tones.mjs scripts/test-web-console-skills.mjs scripts/test-web-console-spec-states.mjs scripts/test-web-console-card-rows.mjs scripts/test-spec-carry.mjs scripts/test-spec-carry-page.mjs scripts/test-web-console-state.mjs scripts/test-web-console-send-state.mjs scripts/test-web-console-strengths.mjs scripts/test-web-console-shape.mjs scripts/test-script-pathfinder.mjs scripts/test-skill-test-runs.mjs scripts/test-launcher.mjs scripts/test-agents-file.mjs scripts/test-agent-lookup.mjs scripts/test-web-console-source.mjs scripts/test-web-console-hardening.mjs scripts/test-web-console-embed.mjs scripts/test-web-console-in-app.mjs scripts/test-web-console-loop.mjs scripts/test-web-console-handoffs.mjs scripts/test-web-console-notepad.mjs scripts/test-script-xray.mjs scripts/test-script-finalize.mjs scripts/test-getting-started.mjs scripts/test-install-update.mjs scripts/test-browser-helper.mjs scripts/test-web-console-page-cards.mjs scripts/test-web-console-page-dashboard.mjs scripts/test-web-console-page-learning.mjs scripts/test-web-console-page-session.mjs scripts/test-web-console-page-ask.mjs scripts/test-web-console-page-workspace.mjs scripts/test-web-console-page-help.mjs scripts/test-web-console-page-prefs.mjs scriLine truncated
"test": "node scripts/check-test-lanes.mjs && node scripts/validate-char-count.js && node install.js --build-skills && node scripts/check-versions.mjs && node scripts/check-doc-size.mjs && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node scripts/check-prompt-wording.mjs && node scripts/check-console-openings.mjs && node scripts/node-test.mjs scripts/test-line-endings.mjs scripts/test-us-english.mjs scripts/test-script-git.mjs scripts/test-git-repo.mjs scripts/test-skill-scripts.mjs scripts/test-script-test-map.mjs scripts/test-script-lessons.mjs scripts/test-script-test-match.mjs scripts/test-script-test-commands.mjs scripts/test-script-run-check.mjs scripts/test-script-pr-prep.mjs scripts/test-script-dead-code.mjs scripts/test-script-deps.mjs scripts/test-script-ui-prototype.mjs scripts/test-script-coverage.mjs scripts/test-script-changelog.mjs scripts/test-script-changes.mjs scripts/test-web-console-git.mjs scripts/test-web-console-git-board.mjs scripts/test-web-console-chat.mjs scripts/test-web-console-subagents.mjs scripts/test-web-console-pointers.mjs scripts/test-web-console-learning.mjs scripts/test-console-wire-budgets.mjs scripts/test-web-console-speed.mjs scripts/test-web-console-qa.mjs scripts/test-web-console-concurrency.mjs scripts/test-web-console-workspace.mjs scripts/test-web-console-lifecycle.mjs scripts/test-web-console-chat-stress.mjs scripts/test-web-console-server.mjs scripts/test-web-console-session.mjs scripts/test-web-console-logic.mjs scripts/test-web-console-agents-doc.mjs scripts/test-web-console-prototypes.mjs scripts/test-web-console-activities.mjs scripts/test-web-console-activities-rapids.mjs scripts/test-web-console-activities-flock.mjs scripts/test-web-console-activities-bounce.mjs scripts/test-web-console-activities-bounce-game.mjs scripts/test-web-console-activities-ghoul.mjs scripts/test-web-console-activities-ghoul-graveyard.mjs scripts/test-web-console-activities-ghoul-grounds.mjs scripts/test-web-console-activities-ghoul-chapel.mjs scripts/test-web-console-activities-ghoul-sanatorium.mjs scripts/test-web-console-activities-ghoul-village.mjs scripts/test-web-console-activities-ghoul-mine.mjs scripts/test-web-console-activities-ghoul-carnival.mjs scripts/test-web-console-activities-ghoul-frozen.mjs scripts/test-web-console-activities-ghoul-bog.mjs scripts/test-web-console-activities-ghoul-lantern.mjs scripts/test-web-console-activities-ghoul-marrow.mjs scripts/test-web-console-activities-ghoul-mat.mjs scripts/test-web-console-activities-ghoul-eye.mjs scripts/test-web-console-activities-ghoul-bonestair.mjs scripts/test-web-console-activities-ghoul-heart.mjs scripts/test-web-console-activities-ghoul-ending.mjs scripts/test-web-console-activities-ghoul-ride.mjs scripts/test-web-console-activities-ghoul-cart.mjs scripts/test-web-console-activities-ghoul-sled.mjs scripts/test-web-console-activities-ghoul-banister.mjs scripts/test-web-console-activities-ghoul-gurney.mjs scripts/test-web-console-activities-ghoul-hearse.mjs scripts/test-web-console-activities-ghoul-wagon.mjs scripts/test-web-console-activities-ghoul-pew.mjs scripts/test-web-console-activities-ghoul-mower.mjs scripts/test-web-console-activities-ghoul-tray.mjs scripts/test-web-console-activities-ghoul-arms.mjs scripts/test-web-console-activities-ghoul-dice.mjs scripts/test-web-console-activities-ghoul-gameover.mjs scripts/test-web-console-activities-ghoul-intro.mjs scripts/test-web-console-activities-ghoul-bossintro.mjs scripts/test-web-console-activities-ghoul-story.mjs scripts/test-web-console-activities-ghoul-bones.mjs scripts/test-web-console-activities-ghoul-retry.mjs scripts/test-web-console-activities-bounce-cars.mjs scripts/test-web-console-activities-bounce-arcade.mjs scripts/test-web-console-tones.mjs scripts/test-web-console-skills.mjs scripts/test-web-console-spec-states.mjs scripts/test-web-console-card-rows.mjs scripts/test-spec-carry.mjs scripts/test-spec-carry-page.mjs scripts/test-web-console-state.mjs scripts/test-web-console-send-state.mjs scripts/test-web-console-strengths.mjs scripts/test-web-console-shape.mjs scripts/test-script-pathfinder.mjs scripts/test-skill-test-runs.mjs scripts/test-launcher.mjs scripts/test-agents-file.mjs scripts/test-agent-lookup.mjs scripts/test-web-console-source.mjs scripts/test-web-console-hardening.mjs scripts/test-web-console-embed.mjs scripts/test-web-console-in-app.mjs scripts/test-web-console-loop.mjs scripts/test-web-console-handoffs.mjs scripts/test-web-console-notepad.mjs scripts/test-script-xray.mjs scripts/test-script-finalize.mjs scripts/test-getting-started.mjs scripts/test-install-update.mjs scripts/test-browser-helper.mjs scripts/test-web-console-page-cards.mjs scripts/test-web-console-page-dashboard.mjs scripts/test-web-console-page-learning.mjs scripts/test-web-console-page-session.mjs scripts/test-web-console-page-ask.mjs scripts/test-web-console-page-workspace.mjs scripts/test-web-console-page-help.mjs scripts/testLine truncated
},
"devDependencies": {
"gpt-tokenizer": "2.9.0",
+1
View File
@@ -14,6 +14,7 @@
"test-install-update.mjs",
"test-line-endings.mjs",
"test-script-changelog.mjs",
"test-script-changes.mjs",
"test-script-coverage.mjs",
"test-script-dead-code.mjs",
"test-script-deps.mjs",
+215
View File
@@ -0,0 +1,215 @@
// Tests for the skills' scripts/changes.mjs: `start` snapshots the working tree
// through a temporary index and `diff` writes what changed since.
//
// See skill-script-helpers.mjs for how these run.
import { test } from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { SKILLS, runScript, tmp, write, read, gitInit } from "./skill-script-helpers.mjs";
const SKILL = "plan2code-3-implement";
const run = (root, session, ...a) => runScript(SKILL, "changes.mjs", [...a, "--session", session, "--root", root]);
// A repository with a few committed files and a session folder beside it.
function fixture(name) {
const root = tmp(name);
const session = tmp(`${name}-session`);
const g = gitInit(root);
write(root, "a.txt", "one\ntwo\nthree\n");
write(root, "gone.txt", "bye\nbye\n");
write(root, "old-name.txt", "keep this\nand this\nand more of it\nand a fourth line\n");
write(root, "src/b.js", "export const b = 1;\n");
write(root, ".gitignore", "ignored/\n");
g("add", "-A");
g("commit", "-q", "-m", "init");
return { root, session, g };
}
const state = (g) => ({ status: g("status", "--porcelain"), head: g("rev-parse", "HEAD"), branch: g("branch", "--show-current"), staged: g("diff", "--cached", "--name-only") });
const names = (diff) => [...diff.matchAll(/^diff --git a\/(.+) b\/(.+)$/gm)].map((m) => m[2]);
test("changes: start then diff lists exactly what changed since, and leaves the repository alone", () => {
const { root, session, g } = fixture("changes-basic");
// Work done before start must never show up.
write(root, "before.txt", "earlier work\n");
fs.appendFileSync(path.join(root, "a.txt"), "before\n");
const before = state(g);
const s = run(root, session, "start");
assert.equal(s.code, 0, s.stderr);
assert.match(s.json.tree, /^[0-9a-f]{40,64}$/);
const startFile = JSON.parse(read(session, "changes-start.json"));
assert.equal(startFile.tree, s.json.tree);
assert.ok(!Number.isNaN(Date.parse(startFile.at)));
assert.deepEqual(state(g), before, "start leaves status, HEAD, branch and the real index as they were");
// The run's own work: modify, add, delete, rename, ignored file.
fs.appendFileSync(path.join(root, "a.txt"), "four\n");
write(root, "new.txt", "fresh\nfile\n");
fs.rmSync(path.join(root, "gone.txt"));
fs.renameSync(path.join(root, "old-name.txt"), path.join(root, "new-name.txt"));
write(root, "ignored/x.txt", "never shown\n");
const mid = state(g);
const d = run(root, session, "diff");
assert.equal(d.code, 0, d.stderr);
assert.deepEqual(state(g), mid, "diff leaves the repository alone too");
assert.equal(d.json.file, "changes.diff");
assert.equal(d.json.files, 4);
assert.equal(d.json.added, 3, "four, two new lines");
assert.equal(d.json.removed, 2, "the two lines of gone.txt");
assert.equal(d.json.truncated, false);
assert.deepEqual(d.json.hidden, []);
const diff = read(session, "changes.diff");
assert.deepEqual(names(diff).sort(), ["a.txt", "gone.txt", "new-name.txt", "new.txt"]);
assert.ok(!diff.includes("before.txt") && !/^[+-]before$/m.test(diff), "work done before start never appears as a change");
assert.ok(!diff.includes("ignored"), ".gitignore'd files never appear");
assert.match(diff, /^rename from old-name\.txt$/m);
assert.match(diff, /^rename to new-name\.txt$/m);
assert.match(diff, /^similarity index 100%$/m);
});
test("changes: a pure rename counts as one file, a binary file is listed with no lines", () => {
const { root, session } = fixture("changes-binary");
run(root, session, "start");
fs.renameSync(path.join(root, "src", "b.js"), path.join(root, "src", "c.js"));
fs.writeFileSync(path.join(root, "pic.bin"), Buffer.from([0, 1, 2, 3, 0, 255, 254, 0]));
const d = run(root, session, "diff");
assert.equal(d.code, 0, d.stderr);
assert.equal(d.json.files, 2);
assert.equal(d.json.added, 0, "binary adds nothing and a pure rename adds nothing");
assert.equal(d.json.removed, 0);
assert.ok(Number.isFinite(d.json.added) && Number.isFinite(d.json.removed), "never NaN");
const diff = read(session, "changes.diff");
assert.match(diff, /^Binary files .*pic\.bin differ$/m);
assert.ok(!/^@@/m.test(diff), "no hunks at all");
assert.match(diff, /^rename from src\/b\.js$/m);
});
test("changes: no changes is an empty file, not an error", () => {
const { root, session } = fixture("changes-empty");
run(root, session, "start");
const d = run(root, session, "diff");
assert.equal(d.code, 0, d.stderr);
assert.deepEqual({ files: d.json.files, added: d.json.added, removed: d.json.removed, truncated: d.json.truncated }, { files: 0, added: 0, removed: 0, truncated: false });
assert.equal(read(session, "changes.diff"), "");
});
test("changes: a patch over the cap is cut at a file boundary, every file still named", () => {
const { root, session } = fixture("changes-cap");
run(root, session, "start");
for (const n of ["f1", "f2", "f3"]) write(root, `${n}.txt`, `${n} line\n`.repeat(200));
const d = run(root, session, "diff", "--cap", "1000");
assert.equal(d.code, 0, d.stderr);
assert.equal(d.json.truncated, true);
assert.equal(d.json.files, 3);
assert.equal(d.json.added, 600, "counts cover the whole change, not the cut patch");
const diff = read(session, "changes.diff");
assert.deepEqual(names(diff).sort(), ["f1.txt", "f2.txt", "f3.txt"]);
assert.match(diff, /^\\ No more lines shown: this change is too large to show in full\.$/m);
assert.match(diff, /^# truncated: true$/m);
assert.ok(diff.length < 1500, "the big first file shows no lines of itself");
assert.ok(!diff.includes("f1 line"));
const bad = run(root, session, "diff", "--cap", "0");
assert.equal(bad.code, 2);
});
test("changes: capPatch keeps whole files that fit and cuts the rest to their headers", async () => {
const { capPatch } = await import(pathToFileURL(path.join(SKILLS, SKILL, "scripts", "changes.mjs")).href);
const small = "diff --git a/s b/s\n--- a/s\n+++ b/s\n@@ -1 +1 @@\n-a\n+b\n";
const big = "diff --git a/big b/big\nrename from x\nrename to big\n--- a/x\n+++ b/big\n@@ -1 +1 @@\n" + "+line\n".repeat(500);
const patch = small + big;
const fit = capPatch(patch, patch.length);
assert.deepEqual(fit, { patch, truncated: false });
const cut = capPatch(patch, 600);
assert.equal(cut.truncated, true);
assert.ok(cut.patch.startsWith(small), "the first file stays whole");
assert.ok(cut.patch.endsWith("diff --git a/big b/big\nrename from x\nrename to big\n"), "the cut file keeps its name and rename lines");
assert.ok(!cut.patch.includes("+line"));
assert.ok(cut.patch.includes("No more lines shown"));
const first = capPatch(patch, 100);
assert.ok(!first.patch.includes("@@"), "a first file over the cap shows no lines");
assert.ok(first.patch.includes("diff --git a/s b/s") && first.patch.includes("diff --git a/big b/big"));
});
test("changes: a sensitive file shows its name and counts but no lines", () => {
const { root, session } = fixture("changes-secret");
run(root, session, "start");
write(root, ".env", "API_KEY=hunter2\nOTHER=1\n");
write(root, "ok.txt", "fine\n");
const d = run(root, session, "diff");
assert.equal(d.code, 0, d.stderr);
assert.equal(d.json.files, 2);
assert.equal(d.json.added, 3, "the hidden file's lines still count");
assert.deepEqual(d.json.hidden, [".env"]);
const diff = read(session, "changes.diff");
assert.ok(!diff.includes("hunter2") && !diff.includes("OTHER=1"));
assert.match(diff, /^diff --git a\/\.env b\/\.env$/m);
assert.match(diff, /^Lines hidden: this file may hold a secret\.$/m);
assert.match(diff, /^# hidden: \.env$/m);
assert.match(diff, /^\+fine$/m, "other files keep their lines");
});
test("changes: failures are plain exit 3s, bad arguments exit 2", () => {
const { root, session } = fixture("changes-fail");
const noStart = run(root, session, "diff");
assert.equal(noStart.code, 3);
assert.equal(noStart.json.error, "no-start");
assert.ok(noStart.json.message && noStart.json.next);
const notRepo = tmp("changes-norepo");
const sess2 = tmp("changes-norepo-session");
for (const cmd of ["start", "diff"]) {
if (cmd === "diff") write(sess2, "changes-start.json", JSON.stringify({ tree: "a".repeat(40), at: "x" }));
const r = run(notRepo, sess2, cmd);
assert.equal(r.code, 3, `${cmd}: ${r.stderr}`);
assert.equal(r.json.error, "not-a-repo");
assert.ok(r.json.next);
}
write(session, "changes-start.json", JSON.stringify({ tree: "b".repeat(40), at: "x" }));
const gone = run(root, session, "diff");
assert.equal(gone.code, 3);
assert.equal(gone.json.error, "start-missing");
const usage = runScript(SKILL, "changes.mjs", ["start", "--root", root]);
assert.equal(usage.code, 2, "--session is required");
assert.equal(runScript(SKILL, "changes.mjs", ["nope", "--session", session]).code, 2);
});
test("changes: start twice overwrites the snapshot", () => {
const { root, session } = fixture("changes-twice");
const a = run(root, session, "start");
fs.appendFileSync(path.join(root, "a.txt"), "first run work\n");
const b = run(root, session, "start");
assert.notEqual(a.json.tree, b.json.tree);
assert.equal(JSON.parse(read(session, "changes-start.json")).tree, b.json.tree);
fs.appendFileSync(path.join(root, "a.txt"), "second run work\n");
const d = run(root, session, "diff");
const diff = read(session, "changes.diff");
assert.equal(d.json.files, 1);
assert.match(diff, /^[+]second run work$/m);
assert.ok(!/^[+-]first run work$/m.test(diff), "work before the second start is context at most, never a change");
});
test("changes: hiding holds for a spaced name, a sensitive rename, diff.noprefix and a cap", () => {
const { root, session, g } = fixture("changes-secret-hard");
write(root, "old.pem", "OLDSECRET1\nOLDSECRET2\nOLDSECRET3\nOLDSECRET4\n");
g("add", "-A");
g("commit", "-q", "-m", "pem");
g("config", "diff.noprefix", "true");
run(root, session, "start");
write(root, "my cert.pem", "SPACEDSECRET\n");
fs.renameSync(path.join(root, "old.pem"), path.join(root, "renamed.txt"));
write(root, "plain.txt", "visible\n".repeat(800));
const d = run(root, session, "diff", "--cap", "3000");
assert.equal(d.code, 0, d.stderr);
const diff = read(session, "changes.diff");
for (const secret of ["SPACEDSECRET", "OLDSECRET"]) assert.ok(!diff.includes(secret), `${secret} must not appear`);
assert.ok(d.json.hidden.includes("my cert.pem"), JSON.stringify(d.json.hidden));
assert.ok(d.json.hidden.includes("old.pem"), "a rename out of a sensitive name is hidden");
assert.equal(d.json.files, 3);
assert.equal(d.json.truncated, true, "the visible file is cut by the cap");
assert.match(diff, /^# hidden: my cert\.pem$/m);
});
+128
View File
@@ -992,6 +992,134 @@ test("an image block under the session's shots folder round-trips, and /shots/ s
}
});
// The Changes tab: a `diff` block names a .diff file saved directly in the
// session folder (changes.mjs diff). The server reads it like a file block,
// keeps the name and the text on the block and never lets it reach outside.
test("a diff block reads a .diff file in the session folder, refreshes and turns back into text", () => {
const res = cli(["open", "--workflow", "implement", "--no-open"]);
const sid = res.json.sid;
const dir = res.json.session;
const post = (name, patch, opts) => cli(["post", "--session", sid, "--file", payload(name, patch)], opts);
const doc = () => readState(dir).docs.find((d) => d.id === "changes");
try {
const first = "diff --git a/a.txt b/a.txt\n--- a/a.txt\n+++ b/a.txt\n@@ -1 +1 @@\n-old\n+new TASK_COMPLETE\n";
fs.writeFileSync(path.join(dir, "changes.diff"), first);
post("diff-ok.json", { docs: [{ id: "changes", title: "Changes", blocks: [{ id: "c1", diff: "changes.diff" }] }] });
const block = doc().blocks[0];
assert.equal(block.diff, "changes.diff");
assert.equal(block.text, first, "the file's text, loop markers in a diff are not the agent's words");
assert.equal(block.md, undefined, "a diff block holds no markdown");
assert.equal(block.state, "settled");
// The same file again is not a new version; a changed one is, re-sent or refreshed.
const v1 = doc().version;
post("diff-same.json", { docs: [{ id: "changes", blocks: [{ id: "c1", diff: "changes.diff" }] }] });
assert.equal(doc().version, v1);
const second = first + "+more\n";
fs.writeFileSync(path.join(dir, "changes.diff"), second);
post("diff-resend.json", { docs: [{ id: "changes", blocks: [{ id: "c1", diff: "changes.diff" }] }] });
assert.equal(doc().blocks[0].text, second);
assert.equal(doc().version, v1 + 1);
const third = second + "+again\n";
fs.writeFileSync(path.join(dir, "changes.diff"), third);
post("diff-refresh.json", { docs: [{ id: "changes", refresh: true }] });
assert.equal(doc().blocks[0].text, third);
assert.equal(doc().version, v1 + 2);
// An empty file is the page's empty state, not an error.
fs.writeFileSync(path.join(dir, "changes.diff"), "");
post("diff-empty.json", { docs: [{ id: "changes", refresh: true }] });
assert.equal(doc().blocks[0].text, "");
// A diff block cannot carry other content.
const both = post("diff-md.json", { docs: [{ id: "changes", blocks: [{ id: "c2", diff: "changes.diff", md: "text" }] }] }, { expectFail: true });
assert.equal(both.status, 3);
assert.match(both.stderr, /cannot also carry "md", "file" or "image"/);
// Text over it: the block stops being a diff and a refresh no longer reads it.
post("diff-to-md.json", { docs: [{ id: "changes", blocks: [{ id: "c1", md: "Plain words." }] }] });
assert.equal(doc().blocks[0].diff, undefined);
assert.equal(doc().blocks[0].text, undefined);
assert.equal(doc().blocks[0].md, "Plain words.");
const none = post("diff-none.json", { docs: [{ id: "changes", refresh: true }] }, { expectFail: true });
assert.match(none.stderr, /found no file or diff blocks to re-read/);
} finally {
cli(["stop", "--session", sid, "--force"]);
}
});
test("a diff block refuses a path, a wrong extension, a missing file and a link out of the session folder", () => {
const res = cli(["open", "--workflow", "implement", "--no-open"]);
const sid = res.json.sid;
const dir = res.json.session;
const outside = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-diff-outside-"));
const post = (name, diff) => cli(["post", "--session", sid, "--file", payload(name, { docs: [{ id: "changes", blocks: [{ id: "c1", diff }] }] })], { expectFail: true });
try {
fs.mkdirSync(path.join(dir, "sub"), { recursive: true });
fs.writeFileSync(path.join(dir, "sub", "changes.diff"), "x\n");
fs.writeFileSync(path.join(dir, "notes.txt"), "x\n");
fs.writeFileSync(path.join(outside, "secret.diff"), "x\n");
const cases = [
["sub/changes.diff", /needs a plain name/],
["sub\\changes.diff", /needs a plain name/],
["../changes.diff", /needs a plain name/],
[path.join(outside, "secret.diff"), /needs a plain name/],
["notes.txt", /needs a plain name/],
["missing.diff", /does not exist in the session folder. Run changes.mjs diff first/],
];
for (const [name, message] of cases) {
const r = post("diff-bad.json", name);
assert.equal(r.status, 3, name);
assert.match(r.stderr, message, name);
}
try {
fs.symlinkSync(path.join(outside, "secret.diff"), path.join(dir, "link.diff"), "file");
} catch {
console.log("skipped the link case: this platform cannot create a symbolic link here");
return;
}
const linked = post("diff-link.json", "link.diff");
assert.equal(linked.status, 3);
assert.match(linked.stderr, /is outside the session folder/);
} finally {
cli(["stop", "--session", sid, "--force"]);
fs.rmSync(outside, { recursive: true, force: true });
}
});
test("a diff file over 512 KB is cut at a whole line with the too-large line, never an error", () => {
const res = cli(["open", "--workflow", "implement", "--no-open"]);
const sid = res.json.sid;
const dir = res.json.session;
try {
const line = "+" + "x".repeat(99) + "\n";
fs.writeFileSync(path.join(dir, "big.diff"), line.repeat(Math.ceil((600 * 1024) / line.length)));
cli(["post", "--session", sid, "--file", payload("diff-big.json", { docs: [{ id: "changes", blocks: [{ id: "c1", diff: "big.diff" }] }] })]);
const text = readState(dir).docs.find((d) => d.id === "changes").blocks[0].text;
const notice = "\\ No more lines shown: this change is too large to show in full.\n";
assert.ok(text.endsWith(notice), "ends with the plain line");
const kept = text.slice(0, -notice.length);
assert.ok(Buffer.byteLength(kept) <= 512 * 1024, "within the cap");
assert.ok(kept.endsWith("\n") && kept.split("\n").every((l) => l === "" || l === line.trimEnd()), "only whole lines");
// A file changes.mjs already cut, and that carries the line, does not get a second one.
fs.writeFileSync(path.join(dir, "cut.diff"), "diff --git a/a b/a\n" + notice);
cli(["post", "--session", sid, "--file", payload("diff-cut.json", { docs: [{ id: "changes", blocks: [{ id: "c1", diff: "cut.diff" }] }] })]);
assert.equal(readState(dir).docs.find((d) => d.id === "changes").blocks[0].text.split(notice).length, 2);
} finally {
cli(["stop", "--session", sid, "--force"]);
}
});
// The server and changes.mjs each spell the too-large line: they must match.
test("the too-large line the server adds is the one changes.mjs adds", async () => {
const { capPatch } = await import("../src/skill-scripts/changes.mjs");
const { DIFF_TOO_LARGE } = await import("../src/web-console/patches.mjs");
const patch = "diff --git a/a b/a\n" + "+x\n".repeat(50) + "diff --git a/b b/b\n" + "+y\n".repeat(50);
const cut = capPatch(patch, 200);
assert.equal(cut.truncated, true);
assert.ok(cut.patch.includes(DIFF_TOO_LARGE + "\n"));
});
// /app.css is the files under public/styles/ joined in CSS_ORDER (one newline
// after each), then the accent rules. The files themselves are never served.
test("/app.css is the style files joined in CSS_ORDER with the accent rules last", async () => {
+326
View File
@@ -0,0 +1,326 @@
#!/usr/bin/env node
// changes.mjs: what this run changed, for the sign-off page's Changes tab.
//
// `start` snapshots the working tree into a git tree object (through a
// temporary index, so the real index, HEAD, branches and working tree stay
// exactly as they were) and remembers its id in the session folder. `diff`
// snapshots the tree as it is now, compares the two and writes the unified diff
// to <session>/changes.diff, with counts on stdout. Work done before `start`
// never shows up, and nothing has to be committed.
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { execFileSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import { EXIT, fail, gitRepo, out, parseArgs, run } from "./common.mjs";
const USAGE = `
changes.mjs: snapshot the working tree, then diff against the snapshot. JSON on stdout.
node changes.mjs start --session <folder> [--root <dir>]
node changes.mjs diff --session <folder> [--root <dir>] [--cap 524288]
start Snapshots the working tree (tracked, modified and new files, never
.gitignore'd ones) into a git tree object and writes
<session>/changes-start.json. The real index, HEAD and branches are
not touched. Run it again to take a new snapshot.
diff Compares the snapshot with the tree now and writes
<session>/changes.diff plus the counts:
{ ok, files, added, removed, truncated, hidden, file }.
--cap Largest patch to keep, in bytes (default 524288). A bigger one is cut
at a file boundary with a plain notice; every file stays named.
Lines of files that may hold a secret are hidden (name and counts stay).
Exit: 0 ok · 2 bad arguments · 3 not a git repository, no snapshot, or the
snapshot is gone · 4 git could not snapshot the working tree.
`;
const DEFAULT_CAP = 524288;
const START_FILE = "changes-start.json";
const DIFF_FILE = "changes.diff";
const TOO_LARGE = "\\ No more lines shown: this change is too large to show in full.";
const HIDDEN_LINE = "Lines hidden: this file may hold a secret.";
/* ------------------------------------------------------------------ git */
function git(root, args, { env, allowFail = false } = {}) {
try {
// core.quotePath=false: a non-ASCII path comes back as itself, not as an escaped, quoted string.
return execFileSync("git", ["-c", "core.quotePath=false", ...args], {
cwd: root,
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
maxBuffer: 64 * 1024 * 1024,
env: env || process.env,
});
} catch (err) {
if (allowFail) return null;
throw err;
}
}
function notARepo(root) {
fail(EXIT.NOT_FOUND, "not-a-repo", `${root} is not inside a git repository, so there is no way to tell what changed.`, "Tell the person the Changes tab has no starting point in a folder without git.");
}
/** The top of the working tree `root` is in, or a not-a-repo failure. */
function topLevel(root) {
const top = git(root, ["rev-parse", "--show-toplevel"], { allowFail: true });
if (top === null || !top.trim()) notARepo(root);
return top.trim();
}
/**
* The tree id of the working tree as it is now, built in a temporary index:
* seeded with a copy of the real one so `git add -A` only re-hashes what
* changed. The real index is never written.
*/
export function snapshotTree(root) {
const top = topLevel(root);
const real = git(top, ["rev-parse", "--git-path", "index"], { allowFail: true });
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-changes-"));
try {
const indexFile = path.join(dir, "index");
if (real && real.trim()) {
const source = path.resolve(top, real.trim());
if (fs.existsSync(source)) fs.copyFileSync(source, indexFile);
}
const env = { ...process.env, GIT_INDEX_FILE: indexFile };
try {
git(top, ["add", "-A"], { env });
return git(top, ["write-tree"], { env }).trim();
} catch (err) {
fail(EXIT.INVALID, "snapshot-failed", `Git could not snapshot the working tree: ${String((err && err.stderr) || err.message).trim().split("\n")[0]}`, "Check that the repository is healthy (git status), then run again.");
}
} finally {
fs.rmSync(dir, { recursive: true, force: true });
}
}
/** `<session>/changes-start.json` as an object with a hex `tree`, or null. */
export function readStart(session) {
try {
const data = JSON.parse(fs.readFileSync(path.join(session, START_FILE), "utf8"));
if (data && typeof data === "object" && typeof data.tree === "string" && /^([0-9a-f]{40}|[0-9a-f]{64})$/.test(data.tree)) return data;
} catch {}
return null;
}
/* ---------------------------------------------------------------- patch */
/** Split a patch into one string per file, each starting at its `diff --git` line. */
function splitSections(patch) {
if (!patch) return [];
return patch.split(/^(?=diff --git )/m).filter((s) => s.startsWith("diff --git "));
}
/** Old and new paths of a file's section (a rename has two). */
function sectionPaths(section) {
const paths = new Set();
for (const line of section.split("\n")) {
if (line.startsWith("@@")) break;
let m = line.match(/^rename (?:from|to) (.+)$/);
if (m) paths.add(unquote(m[1]));
// Git adds a trailing tab after a name that holds a space.
m = line.match(/^(?:--- a|\+\+\+ b)\/(.+?)\t?$/) || line.match(/^(?:--- |\+\+\+ )"[ab]\/(.+)"\t?$/);
if (m) paths.add(unquote(m[1]));
}
if (!paths.size) {
const m = section.split("\n", 1)[0].match(/^diff --git "?a\/(.+?)"? "?b\/(.+?)"?$/);
if (m) {
paths.add(unquote(m[1]));
paths.add(unquote(m[2]));
}
}
return [...paths];
}
/** Undo git's C-style quoting of an odd name (backslash-t, -n, -quote, -backslash). */
function unquote(p) {
return p.replace(/\\(["\\tn])/g, (_, c) => (c === "t" ? "\t" : c === "n" ? "\n" : c));
}
/** Old and new paths per changed file, from `git diff --name-status -z`, in patch order. */
function nameEntries(text) {
const tok = (text || "").split("\0");
const entries = [];
for (let i = 0; i < tok.length && tok[i]; ) {
const n = /^[RC]/.test(tok[i]) ? 2 : 1;
entries.push(tok.slice(i + 1, i + 1 + n));
i += 1 + n;
}
return entries;
}
/** The lines of a section that name the file and how it moved, no content. */
function headerOnly(section) {
const keep = /^(diff --git |rename (from|to) |similarity index |new file mode |deleted file mode |old mode |new mode )/;
return (
section
.split("\n")
.filter((l) => keep.test(l))
.join("\n") + "\n"
);
}
/** Only the `diff --git` line and any rename lines: what a cut file keeps. */
function nameOnly(section) {
return (
section
.split("\n")
.filter((l) => /^(diff --git |rename (from|to) )/.test(l))
.join("\n") + "\n"
);
}
const bytes = (s) => Buffer.byteLength(s, "utf8");
/**
* Cut `patch` to at most `cap` bytes at a file boundary, never mid-line: the
* files that fit stay whole, the rest shrink to their header lines under one
* plain notice, so the file list stays complete. `headerOf` says what a cut
* file keeps (default: its `diff --git` line and any rename lines). A patch
* within the cap comes back unchanged. The result's size can pass the cap only
* when the headers alone do.
*/
export function capPatch(patch, cap, headerOf = nameOnly) {
if (bytes(patch) <= cap) return { patch, truncated: false };
const sections = splitSections(patch);
const sizes = sections.map(bytes);
const heads = sections.map((s) => headerOf(s));
const headSizes = heads.map(bytes);
const notice = TOO_LARGE + "\n";
let kept = 0;
let total = 0;
let cutSize = headSizes.reduce((a, b) => a + b, 0);
// Largest k whose whole sections plus the cut ones' headers fit.
let best = 0;
for (let k = 0; k <= sections.length; k++) {
if (k > 0) {
total += sizes[k - 1];
cutSize -= headSizes[k - 1];
}
if (total + (k < sections.length ? bytes(notice) + cutSize : 0) <= cap) best = k;
else if (k > 0) break;
}
kept = best;
let text = sections.slice(0, kept).join("");
if (kept < sections.length) {
if (text && !text.endsWith("\n")) text += "\n";
text += notice + heads.slice(kept).join("");
}
return { patch: text, truncated: kept < sections.length };
}
/** Replace the lines of every sensitive file's section; returns the paths hidden. */
function hideSensitive(patch, isSensitive, entries) {
const hidden = [];
const split = splitSections(patch);
// The NUL-delimited name list is exact and comes in patch order. A count
// mismatch falls back to the patch text, and a section whose name cannot be
// read at all is hidden: never show lines of a file that cannot be named.
const exact = entries && entries.length === split.length;
const sections = split.map((section, i) => {
const paths = exact ? entries[i] : sectionPaths(section);
const secret = paths.filter((p) => isSensitive(p));
if (!secret.length && paths.length) return section;
for (const p of paths) if (!hidden.includes(p) && isSensitive(p)) hidden.push(p);
return headerOnly(section) + HIDDEN_LINE + "\n";
});
return { patch: sections.join(""), hidden };
}
function sumNumstat(text) {
let added = 0;
let removed = 0;
for (const line of (text || "").split("\n")) {
if (!line.trim()) continue;
const [a, d] = line.split("\t");
// A binary file prints "-" for both counts: it adds nothing.
if (/^\d+$/.test(a)) added += Number(a);
if (/^\d+$/.test(d)) removed += Number(d);
}
return { added, removed };
}
/* ------------------------------------------------------------- commands */
function sessionFolder(args) {
if (!args.session) fail(EXIT.USAGE, "missing-session", "--session <folder> is required.", "Pass the console session folder (the `session` path `console.mjs open` printed).");
return path.resolve(args.session);
}
function startCommand(args) {
const session = sessionFolder(args);
const root = path.resolve(args.root || process.cwd());
const tree = snapshotTree(root);
fs.mkdirSync(session, { recursive: true });
fs.writeFileSync(path.join(session, START_FILE), JSON.stringify({ tree, at: new Date().toISOString() }) + "\n");
out({ ok: true, tree });
}
async function diffCommand(args) {
const session = sessionFolder(args);
const root = path.resolve(args.root || process.cwd());
let cap = DEFAULT_CAP;
if (args.cap !== undefined) {
if (!/^[1-9]\d*$/.test(String(args.cap))) fail(EXIT.USAGE, "bad-cap", `--cap must be a positive whole number of bytes, not "${args.cap}".`, "Pass --cap 524288, or leave it out.");
cap = Number(args.cap);
}
const start = readStart(session);
if (!start) fail(EXIT.NOT_FOUND, "no-start", "No snapshot was taken at the start of this run.", "Run changes.mjs start first, or tell the person the Changes tab has no starting point.");
const top = topLevel(root);
if (git(top, ["cat-file", "-e", `${start.tree}^{tree}`], { allowFail: true }) === null) {
fail(EXIT.NOT_FOUND, "start-missing", "The snapshot taken at the start of this run is gone from the repository (git cleaned it up).", "Tell the person the Changes tab has no starting point, or run changes.mjs start and redo the comparison from there.");
}
const now = snapshotTree(root);
// Fixed prefixes: a user's diff.noprefix or diff.mnemonicPrefix must not change the headers.
const diffArgs = ["diff", "--no-color", "-M", "--no-ext-diff", "--src-prefix=a/", "--dst-prefix=b/"];
const entries = nameEntries(git(top, ["diff", "--name-status", "-z", "-M", "--no-ext-diff", start.tree, now]));
const numstat = git(top, ["diff", "--numstat", "-M", "--no-ext-diff", start.tree, now]);
const { added, removed } = sumNumstat(numstat);
let patch;
let oversize = false;
try {
patch = git(top, [...diffArgs, start.tree, now]);
} catch (err) {
if (!(err && (err.code === "ENOBUFS" || err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"))) throw err;
// Too big to even read: keep only the names, so the file list stays complete.
oversize = true;
patch = entries.map((e) => `diff --git a/${e[0]} b/${e[e.length - 1]}\n${e.length > 1 ? `rename from ${e[0]}\nrename to ${e[1]}\n` : ""}`).join("");
}
const files = (patch.match(/^diff --git /gm) || []).length;
const { isSensitive } = await gitRepo();
const shown = hideSensitive(patch, isSensitive, entries);
const capped = oversize ? { patch: shown.patch + TOO_LARGE + "\n", truncated: true } : capPatch(shown.patch, cap);
let text = capped.patch;
const trailer = [];
if (capped.truncated) trailer.push("# truncated: true");
for (const p of shown.hidden) trailer.push(`# hidden: ${p}`);
if (trailer.length) text += (text && !text.endsWith("\n") ? "\n" : "") + trailer.join("\n") + "\n";
fs.mkdirSync(session, { recursive: true });
fs.writeFileSync(path.join(session, DIFF_FILE), text);
out({ ok: true, files, added, removed, truncated: capped.truncated, hidden: shown.hidden, file: DIFF_FILE });
}
// Run only as a script: the tests import capPatch without starting it.
const isMain = (() => {
try {
return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
} catch {
return false;
}
})();
if (isMain) {
run(USAGE, async (argv) => {
const args = parseArgs(argv, { values: ["session", "root", "cap"] });
const [command] = args._;
if (command === "start") return startCommand(args);
if (command === "diff") return diffCommand(args);
fail(EXIT.USAGE, "unknown-command", command ? `Unknown command "${command}".` : "No command given.", "Use `start` or `diff` (changes.mjs --help).");
});
}
+2 -1
View File
@@ -9,11 +9,12 @@ Docs and their blocks merge by `id`; a new id is added at the end. Patch blocks
- `{"id":"b2","state":"settled"}` settles b2 and keeps its text; blocks you leave out stay.
- `{"id":"b3","_delete":true}` removes a block; a doc entry with `"_delete":true` removes the tab.
## Block content: one of three
## Block content: one of four
- `md`: markdown you write.
- `file`: the console reads the text from that project file (inside the project, 512 KB at most). Re-send the block, or the doc with `"refresh":true`, after the file changes. `"select":"tasks"` keeps only its `- [ ] **Task N.M:**` lines. Never paste a file you can name.
- `image`: `{"id":"s1","image":"shots/run.png","alt":"..."}`: a PNG, JPEG or WebP (5 MB at most) saved directly in the session's `shots/` folder (the `session` path `open` printed), named with letters, digits, `.`, `_` or `-`. Anything else is exit 3.
- `diff`: `{"id":"changes","diff":"changes.diff"}`: a unified diff `changes.mjs diff` wrote, saved directly in the session folder (a name ending `.diff`, 512 KB at most, longer text is cut). The page draws it as the Changes tab. Never paste a diff you can name; re-send the block after running `changes.mjs diff` again.
## State
+62 -8
View File
@@ -262,7 +262,7 @@ function mergeDocs(current, patchList) {
// version: the agent no longer has to track what the page holds, and a
// repost of unchanged content is not a new version.
if (prev && typeof entry.version !== "number" && typeof prev.version === "number") {
const text = (blocks) => JSON.stringify((blocks || []).map((b) => [b.id, b.md, b.state, b.image, b.alt]));
const text = (blocks) => JSON.stringify((blocks || []).map((b) => [b.id, b.md, b.state, b.image, b.alt, b.diff, b.text]));
if (text(prev.blocks) !== text(doc.blocks)) doc.version = prev.version + 1;
}
}
@@ -403,9 +403,9 @@ export function resolveDocFiles(patch, state, worktree) {
const prev = (state.docs || []).find((d) => d && d.id === entry.id);
const named = new Set((blocks || []).map((b) => b && b.id));
const again = ((prev && prev.blocks) || [])
.filter((b) => b && typeof b.file === "string" && !named.has(b.id))
.map((b) => ({ id: b.id, file: b.file, ...(b.select ? { select: b.select } : {}) }));
if (!again.length && !blocks) throw new Error(rule(`doc "${entry.id}"`, "refresh", "found no file blocks to re-read", { id: entry.id, blocks: [FILE_RIGHT] }));
.filter((b) => b && (typeof b.file === "string" || typeof b.diff === "string") && !named.has(b.id))
.map((b) => (typeof b.diff === "string" ? { id: b.id, diff: b.diff } : { id: b.id, file: b.file, ...(b.select ? { select: b.select } : {}) }));
if (!again.length && !blocks) throw new Error(rule(`doc "${entry.id}"`, "refresh", "found no file or diff blocks to re-read", { id: entry.id, blocks: [FILE_RIGHT] }));
blocks = [...(blocks || []), ...again];
} else if (refresh !== undefined) throw new Error(rule(`doc "${entry.id}"`, "refresh", "must be true", { id: entry.id, refresh: true }));
if (!blocks) return rest;
@@ -452,6 +452,9 @@ export function shotType(buf) {
return null;
}
export const DIFF_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\.diff$/;
export const DIFF_TOO_LARGE = "\\ No more lines shown: this change is too large to show in full.";
export function resolveDocImages(patch, state, dir) {
if (!isPlainObject(patch) || !Array.isArray(patch.docs)) return patch;
const fold = (p) => (process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p);
@@ -486,6 +489,47 @@ export function resolveDocImages(patch, state, dir) {
if (shotType(fs.readFileSync(real)) !== want) throw bad(`is not a ${want.toUpperCase()} image (its bytes say otherwise)`);
return `${SHOTS_DIR_NAME}/${name}`;
};
// Diff blocks: `{ "id": "changes", "diff": "changes.diff" }` names a unified
// diff the agent saved directly in the session folder (changes.mjs diff). The
// server reads it like a file block, with the same 512 KB cap, and stores the
// name beside the text so the page can tell a diff from markdown.
const DIFF_RIGHT = { id: "d1", diff: "changes.diff" };
const readDiff = (name, docId, blockId) => {
const at = `doc "${docId}" block "${blockId}"`;
if (typeof name !== "string" || !name.trim()) throw new Error(rule(at, "diff", "must be a file name", DIFF_RIGHT));
const bad = (wrong) => new Error(rule(at, "diff", `${name} ${wrong}`, DIFF_RIGHT));
if (!DIFF_NAME.test(name)) throw bad("needs a plain name saved directly in the session folder: letters, digits, dots, dashes or underscores, ending .diff");
let real;
try {
real = fs.realpathSync.native(path.resolve(dir, name));
} catch {
throw bad("does not exist in the session folder. Run changes.mjs diff first");
}
let realDir;
try {
realDir = fs.realpathSync.native(path.resolve(dir));
} catch {
realDir = path.resolve(dir);
}
if (fold(path.dirname(real)) !== fold(realDir)) throw bad(`is outside the session folder (${path.resolve(dir)}); only a diff saved there can be shown`);
const stat = fs.statSync(real);
if (!stat.isFile()) throw bad("is not a file");
const fd = fs.openSync(real, "r");
let raw;
try {
// One byte past the cap tells a file that fits from one that does not.
const buf = Buffer.alloc(Math.min(stat.size, DOC_FILE_MAX + 1));
raw = buf.subarray(0, fs.readSync(fd, buf, 0, buf.length, 0));
} finally {
fs.closeSync(fd);
}
if (raw.length <= DOC_FILE_MAX) return raw.toString("utf8").replace(/\r\n/g, "\n");
// Over the cap is not an error (changes.mjs cuts there itself): keep whole
// lines and say so, so a hand-made big file still degrades.
const head = raw.subarray(0, DOC_FILE_MAX);
const text = head.subarray(0, head.lastIndexOf(0x0a) + 1).toString("utf8").replace(/\r\n/g, "\n");
return text.includes(DIFF_TOO_LARGE) ? text : `${text}${DIFF_TOO_LARGE}\n`;
};
const docs = patch.docs.map((entry) => {
if (!isPlainObject(entry) || !Array.isArray(entry.blocks)) return entry;
const prevBlocks = (state.docs || []).find((d) => d && d.id === entry.id)?.blocks || [];
@@ -494,15 +538,24 @@ export function resolveDocImages(patch, state, dir) {
blocks: entry.blocks.map((b) => {
if (!isPlainObject(b)) return b;
const prevBlock = prevBlocks.find((x) => x && x.id === b.id);
if (b.diff !== undefined && b.diff !== null) {
if (["md", "file", "image"].some((k) => k in b && b[k] != null)) {
throw new Error(rule(`doc "${entry.id}" block "${b.id}"`, "diff", 'a diff block cannot also carry "md", "file" or "image"', DIFF_RIGHT));
}
return { state: prevBlock?.state || "settled", ...b, diff: b.diff, text: readDiff(b.diff, entry.id, b.id), md: null, file: null, image: null };
}
// Text, a file or an image over what was a diff: it stops being one.
const wasDiff = prevBlock && typeof prevBlock.diff === "string";
const notDiff = wasDiff && ("md" in b || "file" in b || "image" in b) ? { diff: null, text: null } : {};
if (b.image === undefined || b.image === null) {
// Text or a file over what was an image: it stops being one.
return ("md" in b || "file" in b) && prevBlock && typeof prevBlock.image === "string" ? { ...b, image: null, alt: null } : b;
return ("md" in b || "file" in b) && prevBlock && typeof prevBlock.image === "string" ? { ...b, ...notDiff, image: null, alt: null } : { ...b, ...notDiff };
}
if (("md" in b && b.md != null) || ("file" in b && b.file != null)) {
throw new Error(rule(`doc "${entry.id}" block "${b.id}"`, "image", 'an image block cannot also carry "md" or "file"', IMAGE_RIGHT));
}
if (b.alt != null && typeof b.alt !== "string") throw new Error(rule(`doc "${entry.id}" block "${b.id}"`, "alt", "must be text", IMAGE_RIGHT));
return { state: prevBlock?.state || "settled", ...b, image: check(b.image, entry.id, b.id), md: null, file: null };
return { state: prevBlock?.state || "settled", ...b, ...notDiff, image: check(b.image, entry.id, b.id), md: null, file: null };
}),
};
});
@@ -1293,10 +1346,11 @@ export function validate(state) {
}
// A doc block read from a file (`file`) is the file's own words, already on
// disk: the agent cannot reword it, and refusing it would wedge every post
// that refreshes it. Only what the agent typed is scanned.
// that refreshes it. A diff block is code the repository holds, never prose
// the agent wrote: its text may name any word. Only what the agent typed is scanned.
for (const d of state.docs || []) {
if (!isPlainObject(d)) continue;
const typed = Array.isArray(d.blocks) ? { ...d, blocks: d.blocks.filter((b) => !(isPlainObject(b) && typeof b.file === "string")) } : d;
const typed = Array.isArray(d.blocks) ? { ...d, blocks: d.blocks.filter((b) => !(isPlainObject(b) && (typeof b.file === "string" || typeof b.diff === "string"))) } : d;
scan(typed, `doc "${d.id}"`);
}
scan(state.finish || {}, "finish");