#!/usr/bin/env node
// bodies-check.mjs: accepts a before/after request-body pair only when one logged browser run produced both files.
// Node 18+, no dependencies.
import { createHash } from "node:crypto";
import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { spawnSync } from "node:child_process";
const HELP = `bodies-check.mjs log <run log> start|end <RUN_ID> [rc] append one run-log line around a browser run
bodies-check.mjs <dir> --expect <procs> --before-ports a,b --after-ports c,d --log <run log> [--slack 5]
Reads <dir>/bodies.before.json and <dir>/bodies.after.json, each {"run": "<RUN_ID>", "rows": [{url, proc, body, capturedAt}]}.
Rejects (exit 2) unless all of these hold
1. both files exist, are not byte-identical, and have a non-empty rows array of complete rows
2. before rows are on the before ports and after rows on the after ports (any local host)
3. both files name one RUN_ID, and the run log shows that id with a start and an end with rc 0
4. every capturedAt lies inside the run window plus --slack seconds (default 5)
5. every procedure in --expect (comma list) has rows in both files
The expected list comes from the verifier brief, written from the diff's write lines before the run.
Exit 0 when valid and every procedure's bodies match between before and after. Exit 1 when valid and some
procedure's bodies differ, printed as "DIFF <proc> <before count> <after count>". land.mjs lands a DIFF only when
decisions.tsv (or its --intended file) holds an intended change row naming the surface and that procedure.
Making the two files: serve the base commit's build (a separate worktree) and the run branch's build at the same
time on different ports, then wrap both captures in one logged run:
rc=0; node bodies-check.mjs log runs.log start RUN-7
node capture.mjs --base http://localhost:5183 --kind before ... --run RUN-7 --bodies <dir>/bodies.before.json || rc=1
node capture.mjs --base http://localhost:5173 --kind after ... --run RUN-7 --bodies <dir>/bodies.after.json || rc=1
node bodies-check.mjs log runs.log end RUN-7 $rc
capture.mjs is in build-design-system's scripts. Drive the changed write in both captures with the same --states
step, so both runs send it.
Run log: tab separated, one line per event: <event>\\t<iso time>\\t<slot>\\t<RUN_ID>\\t<rc>
where event is start or end and rc is only read on end. Wrap the browser run with the log subcommand: start before it, end with its exit code after it.
Residual risk that stays: a script can still write a pair inside a real run, and a fixture may not exercise the changed path.
Options: --self-test, --help`;
class Reject extends Error {}
const die = (m) => { throw new Reject(m); };
export function check(dir, o) {
const pb = join(dir, "bodies.before.json");
const pa = join(dir, "bodies.after.json");
for (const p of [pb, pa]) if (!existsSync(p)) die(`missing ${p}`);
if (readFileSync(pb).equals(readFileSync(pa))) die("before and after files are byte-identical");
const load = (p, ports) => {
let f;
try { f = JSON.parse(readFileSync(p, "utf8")); } catch (e) { die(`${p}: not JSON (${e.message})`); }
if (!f || typeof f !== "object" || !("run" in f) || !Array.isArray(f.rows)) die(`${p}: needs {"run", "rows"}`);
if (!f.rows.length) die(`${p}: no rows`);
const groups = new Map();
const times = [];
for (const r of f.rows) {
for (const k of ["url", "proc", "body", "capturedAt"]) if (typeof r?.[k] !== "string") die(`${p}: row without ${k}`);
let u;
try { u = new URL(r.url); } catch { die(`${p}: bad url ${r.url}`); }
if (!/^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/.test(u.hostname)) die(`${p}: url ${r.url} is not on a local host`);
if (!ports.includes(u.port)) die(`${p}: url ${r.url} is not on port ${ports.join("/")}`);
const t = Date.parse(r.capturedAt);
if (Number.isNaN(t)) die(`${p}: bad capturedAt ${r.capturedAt}`);
times.push(t);
if (!groups.has(r.proc)) groups.set(r.proc, new Set());
groups.get(r.proc).add(createHash("sha256").update(r.body).digest("hex"));
}
return { run: f.run, groups, times };
};
const B = load(pb, o.beforePorts);
const A = load(pa, o.afterPorts);
if (B.run !== A.run) die(`runs differ: ${B.run} vs ${A.run}. One browser run must produce both files; merge nothing`);
if (!o.log || !existsSync(o.log)) die(`no run log at ${o.log}`);
let start = null;
let end = null;
for (const line of readFileSync(o.log, "utf8").split("\n")) {
const c = line.split("\t");
if (c.length >= 5 && c[3] === B.run) {
if (c[0] === "start") start = Date.parse(c[1]);
if (c[0] === "end" && c[4].trim() === "0") end = Date.parse(c[1]);
}
}
if (start === null || end === null) die(`run ${B.run} has no start and end rc 0 in ${o.log}`);
const slack = (o.slack ?? 5) * 1000;
if ([...B.times, ...A.times].some((t) => t < start - slack || t > end + slack)) die(`capturedAt outside run ${B.run} window ${new Date(start).toISOString()}..${new Date(end).toISOString()}`);
for (const p of o.expect) {
if (!B.groups.has(p)) die(`expected procedure ${p} has no rows in bodies.before.json`);
if (!A.groups.has(p)) die(`expected procedure ${p} has no rows in bodies.after.json`);
}
const lines = [];
let differ = false;
for (const k of [...new Set([...B.groups.keys(), ...A.groups.keys()])].sort()) {
const b = B.groups.get(k);
const a = A.groups.get(k);
const same = b && a && b.size === a.size && [...b].every((h) => a.has(h));
if (!same) differ = true;
lines.push(`${same ? "same" : "DIFF"} ${k} ${b?.size ?? 0} ${a?.size ?? 0}`);
}
return { lines, differ };
}
function parse(argv) {
const o = { _: [], expect: [], beforePorts: [], afterPorts: [] };
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
const next = () => argv[++i];
if (a === "--expect") o.expect = next().split(",").filter(Boolean);
else if (a === "--before-ports") o.beforePorts = next().split(",");
else if (a === "--after-ports") o.afterPorts = next().split(",");
else if (a === "--log") o.log = next();
else if (a === "--slack") o.slack = Number(next());
else if (a === "--help" || a === "-h") o.help = true;
else if (a === "--self-test") o.selfTest = true;
else if (a.startsWith("--")) { console.error(`bodies-check: unknown flag ${a}. See --help`); process.exit(2); }
else o._.push(a);
}
return o;
}
function selfTest() {
const root = mkdtempSync(join(tmpdir(), "bc-"));
let failed = 0;
const t0 = Date.parse("2026-01-01T10:00:00Z");
const iso = (s) => new Date(t0 + s * 1000).toISOString();
const row = (port, proc, body, s) => ({ url: `http://localhost:${port}/rpc/${proc}`, proc, body, capturedAt: iso(s) });
const log = join(root, "runs.log");
writeFileSync(log, [`start\t${iso(0)}\tslot1\tRUN-A\t`, `end\t${iso(60)}\tslot1\tRUN-A\t0`, `start\t${iso(100)}\tslot1\tRUN-B\t`, `end\t${iso(160)}\tslot1\tRUN-B\t0`, `start\t${iso(200)}\tslot1\tRUN-C\t`, `end\t${iso(210)}\tslot1\tRUN-C\t1`, ""].join("\n"));
const opts = (extra = {}) => ({ beforePorts: ["5183", "5184"], afterPorts: ["5173", "5174"], log, expect: ["items/update"], ...extra });
const mk = (name, before, after) => {
const d = join(root, name);
mkdirSync(d);
if (before) writeFileSync(join(d, "bodies.before.json"), JSON.stringify(before));
if (after) writeFileSync(join(d, "bodies.after.json"), JSON.stringify(after));
return d;
};
const expectReject = (name, dir, o, re) => {
try { check(dir, o); failed++; console.error(`FAIL ${name}: accepted`); } catch (e) {
if (e instanceof Reject && re.test(e.message)) console.log(`ok ${name}`);
else { failed++; console.error(`FAIL ${name}: ${e.message}`); }
}
};
const good = (run) => ({
b: { run, rows: [row(5183, "items/update", '{"count":2}', 10), row(5184, "items/create", '{"a":1}', 12)] },
a: { run, rows: [row(5173, "items/update", '{"count":2}', 11), row(5174, "items/create", '{"a":1}', 13)] },
});
const g = good("RUN-A");
let r = check(mk("good", g.b, g.a), opts());
if (!r.differ && r.lines.every((l) => l.startsWith("same"))) console.log("ok valid pair passes"); else { failed++; console.error("FAIL valid pair"); }
const dif = good("RUN-A");
dif.a.rows[0].body = '{"count":3}';
r = check(mk("diff", dif.b, dif.a), opts());
if (r.differ && r.lines.some((l) => l.startsWith("DIFF items/update"))) console.log("ok differing bodies reported as DIFF"); else { failed++; console.error("FAIL diff"); }
// Two files merged from two different real runs: each run is valid alone, the pair is not.
const m = { b: good("RUN-A").b, a: good("RUN-B").a };
m.a.rows.forEach((x) => (x.capturedAt = iso(105)));
expectReject("merged pair from two runs", mk("merged", m.b, m.a), opts(), /runs differ/);
const inside = good("RUN-A"); inside.b.rows[0].capturedAt = iso(500);
expectReject("capturedAt outside the run window", mk("late", inside.b, inside.a), opts(), /outside run/);
const g2 = good("RUN-A"); g2.b.rows[0].capturedAt = iso(63);
r = check(mk("slack", g2.b, g2.a), opts()); console.log("ok inside slack accepted");
expectReject("slack zero rejects the same row", mk("slack0", g2.b, g2.a), opts({ slack: 0 }), /outside run/);
const bad = good("RUN-C");
expectReject("run that ended rc 1", mk("rc1", bad.b, bad.a), opts(), /no start and end rc 0/);
const unk = good("RUN-Z");
expectReject("run id not in the log", mk("unk", unk.b, unk.a), opts(), /no start and end/);
expectReject("empty rows", mk("empty", { run: "RUN-A", rows: [] }, g.a), opts(), /no rows/);
const gi = good("RUN-A");
expectReject("byte-identical files", mk("ident", gi.b, gi.b), opts(), /byte-identical/);
const swapped = good("RUN-A");
swapped.b.rows[0].url = "http://localhost:5173/rpc/items/update";
expectReject("before row on an after port", mk("ports", swapped.b, swapped.a), opts(), /not on port/);
const remote = good("RUN-A");
remote.a.rows[0].url = "https://app.example.com:5173/rpc/items/update";
expectReject("a row from a non-local host", mk("remote", remote.b, remote.a), opts(), /not on a local host/);
const miss = good("RUN-A");
miss.a.rows = miss.a.rows.filter((x) => x.proc !== "items/update");
expectReject("expected procedure missing in after", mk("miss", miss.b, miss.a), opts(), /expected procedure items\/update has no rows in bodies.after/);
expectReject("expected procedure never run in either file", mk("miss2", g.b, g.a), opts({ expect: ["items/delete"] }), /items\/delete/);
expectReject("missing file", mk("nofile", g.b, null), opts(), /missing/);
// The log subcommand writes lines this checker accepts.
const lg = join(root, "made.log");
const me = fileURLToPath(import.meta.url);
spawnSync(process.execPath, [me, "log", lg, "start", "RUN-L"]);
spawnSync(process.execPath, [me, "log", lg, "end", "RUN-L", "0"]);
const now = Date.now();
const lrow = (port, at) => ({ url: `http://localhost:${port}/rpc/items/update`, proc: "items/update", body: "{}", capturedAt: new Date(at).toISOString() });
const lb = { run: "RUN-L", rows: [lrow(5183, now)] };
const la = { run: "RUN-L", rows: [lrow(5173, now + 1)] };
r = check(mk("logged", lb, la), opts({ log: lg }));
if (!r.differ) console.log("ok run log written by the log subcommand is accepted"); else { failed++; console.error("FAIL log subcommand"); }
rmSync(root, { recursive: true, force: true });
if (failed) { console.error(`${failed} self-test failure(s)`); process.exit(1); }
console.log("all as expected");
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
const o = parse(process.argv.slice(2));
if (o.help) console.log(HELP);
else if (o.selfTest) selfTest();
else if (o._[0] === "log") {
const [, file, event, id, rc = ""] = o._;
if (!file || !["start", "end"].includes(event) || !id) { console.error("usage: bodies-check.mjs log <run log> start|end <RUN_ID> [rc]"); process.exit(2); }
appendFileSync(file, `${event}\t${new Date().toISOString()}\tmain\t${id}\t${event === "end" ? rc : ""}\n`);
} else {
if (!o._[0] || !o.beforePorts.length || !o.afterPorts.length || !o.log) { console.error("needs <dir> --before-ports --after-ports --log (and --expect). See --help"); process.exit(2); }
if (!o.expect.length) { console.error("--expect is required: the verifier brief lists the procedures the diff's write lines call"); process.exit(2); }
try {
const { lines, differ } = check(o._[0], o);
console.log(lines.join("\n"));
process.exit(differ ? 1 : 0);
} catch (e) {
if (e instanceof Reject) { console.log(`REJECT ${e.message}`); process.exit(2); }
throw e;
}
}
}