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

+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");