moshcode 0.59.0 → 0.61.0

package/src/herd-eval.mjs

@@ -0,0 +1,301 @@
+// `moshcode herd eval` — which engine is best at *this* repo (PRD 0011 R13).
+//
+// "Which engine should I use" is answered on the internet with benchmarks run
+// against engines nobody deploys, on repos nobody has. The herd can answer it
+// the only way that means anything: run your dataset through the engines you
+// actually have, on the machine you actually work on, and count.
+//
+// Nothing here is new machinery. A row is fanned across the named engines with
+// the verbs that already exist — start a session, prompt it, wait, read what
+// came back out of the ledger — and scored either by a pattern the dataset
+// carries or by an engine acting as judge (the `ai()` verb, which is the same
+// headless invocation moshscript uses). The exit code follows `wait`'s
+// discipline, because a CI job needs to tell "the agent got worse" apart from
+// "the harness fell over", and a single non-zero code cannot.
+//
+// The DO Gradient ADK ships `gradient agent evaluate --dataset-file --categories
+// --success-threshold` for deployed agents. This is that idea pointed at
+// interactive engines, which is the comparison nobody else is placed to run.
+import fs from "node:fs";
+import path from "node:path";
+
+import { runAi } from "./cli.mjs";
+import { ENGINES, resolveEngine, resolveExecutable } from "./engines.mjs";
+import { capture, killSession, listSessions, sendPrompt, startSession } from "./herd.mjs";
+import { endTask, screenDelta, startTask } from "./herd-tasks.mjs";
+
+export const DEFAULT_THRESHOLD = 0.8;
+
+/* --------------------------------------------------------------- datasets */
+
+/**
+ * A minimal CSV reader: quoted fields, doubled quotes, embedded newlines.
+ *
+ * Deliberately not a dependency. A dataset is a file someone wrote by hand or
+ * exported from a spreadsheet, and those two shapes are the whole requirement.
+ */
+export function parseCsv(text) {
+  const rows = [];
+  let row = [], field = "", quoted = false;
+  const src = String(text ?? "").replace(/\r\n/g, "\n");
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (quoted) {
+      if (c === '"') {
+        if (src[i + 1] === '"') { field += '"'; i++; }
+        else quoted = false;
+      } else field += c;
+      continue;
+    }
+    if (c === '"') { quoted = true; continue; }
+    if (c === ",") { row.push(field); field = ""; continue; }
+    if (c === "\n") { row.push(field); rows.push(row); row = []; field = ""; continue; }
+    field += c;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((r) => r.some((cell) => String(cell).trim()));
+}
+
+/**
+ * Read a dataset. `.jsonl` is one object per line, `.json` an array, `.csv` a
+ * header row plus rows. Every shape ends up as the same list of cases.
+ *
+ * A case is { id, prompt, expect?, rubric? }: the prompt to submit, an optional
+ * pattern the answer must match (the `rules` judge), and an optional rubric for
+ * an engine judge to score against.
+ */
+export function loadDataset(file) {
+  let text;
+  try { text = fs.readFileSync(file, "utf8"); }
+  catch (error) { return { ok: false, error }; }
+
+  const ext = path.extname(file).toLowerCase();
+  let raw;
+  try {
+    if (ext === ".csv") {
+      const rows = parseCsv(text);
+      if (!rows.length) return { ok: false, error: new Error(`${file} is empty`) };
+      const header = rows[0].map((h) => String(h).trim().toLowerCase());
+      raw = rows.slice(1).map((cells) => Object.fromEntries(header.map((h, i) => [h, cells[i] ?? ""])));
+    } else if (ext === ".json") {
+      const parsed = JSON.parse(text);
+      raw = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.cases) ? parsed.cases : null;
+      if (!raw) return { ok: false, error: new Error(`${file} must hold an array of cases`) };
+    } else {
+      raw = text.split("\n").filter((l) => l.trim()).map((line, i) => {
+        try { return JSON.parse(line); }
+        catch (error) { throw new Error(`${file}:${i + 1} is not valid JSON (${error.message})`); }
+      });
+    }
+  } catch (error) { return { ok: false, error }; }
+
+  const cases = [];
+  for (const [i, entry] of raw.entries()) {
+    const prompt = String(entry?.prompt ?? entry?.input ?? "").trim();
+    if (!prompt) return { ok: false, error: new Error(`${file}: case ${i + 1} has no prompt`) };
+    cases.push({
+      id: String(entry.id ?? `case-${i + 1}`),
+      prompt,
+      expect: entry.expect ? String(entry.expect) : null,
+      rubric: entry.rubric ? String(entry.rubric) : null,
+    });
+  }
+  if (!cases.length) return { ok: false, error: new Error(`${file} holds no cases`) };
+  return { ok: true, cases };
+}
+
+/* ---------------------------------------------------------------- scoring */
+
+/**
+ * The `rules` judge: does the answer match what the dataset expected?
+ *
+ * The pattern is a regex, case-insensitive, because a dataset written by hand
+ * says `expect: "3 tests passed"` and means it loosely. A case with no
+ * expectation cannot be scored by rules, and says so rather than scoring zero —
+ * a missing expectation is the dataset's bug, not the engine's.
+ */
+export function scoreByRules(testCase, answer) {
+  if (!testCase.expect) {
+    return { ok: false, score: 0, why: "no `expect` pattern — this case needs a judge, or an expectation" };
+  }
+  let re;
+  try { re = new RegExp(testCase.expect, "i"); }
+  catch { re = null; }
+  const hit = re ? re.test(String(answer ?? "")) : String(answer ?? "").toLowerCase().includes(testCase.expect.toLowerCase());
+  return { ok: true, score: hit ? 1 : 0, why: hit ? "matched the expectation" : "did not match the expectation" };
+}
+
+/** Pull the first JSON object out of an engine's answer. */
+export function extractVerdict(text) {
+  const raw = String(text ?? "");
+  const start = raw.indexOf("{");
+  if (start < 0) return null;
+  for (let end = raw.lastIndexOf("}"); end > start; end = raw.lastIndexOf("}", end - 1)) {
+    try {
+      const parsed = JSON.parse(raw.slice(start, end + 1));
+      if (parsed && typeof parsed === "object") return parsed;
+    } catch { /* keep shrinking */ }
+  }
+  return null;
+}
+
+export function judgePrompt(testCase, answer) {
+  return [
+    "You are grading one answer produced by a coding agent. Reply with JSON only.",
+    "",
+    `TASK: ${testCase.prompt}`,
+    testCase.rubric ? `RUBRIC: ${testCase.rubric}` : "RUBRIC: is this a correct, complete, and directly responsive answer to the task?",
+    "",
+    "ANSWER:",
+    String(answer ?? "").slice(-6000),
+    "",
+    'Reply with exactly: {"score": <0 to 1>, "why": "<one sentence>"}',
+  ].join("\n");
+}
+
+/** The engine judge. Returns { ok, score, why } and never throws. */
+export function scoreByJudge(testCase, answer, { engine, run = runAi, out = () => {} } = {}) {
+  let text;
+  try { text = run({ out, dryRun: false }, judgePrompt(testCase, answer), { engine }); }
+  catch (error) { return { ok: false, score: 0, why: `judge failed: ${String(error.message || error)}` }; }
+  const verdict = extractVerdict(text);
+  if (!verdict || typeof verdict.score !== "number" || !Number.isFinite(verdict.score)) {
+    return { ok: false, score: 0, why: `judge did not answer with a score (${String(text).trim().slice(0, 120)})` };
+  }
+  return { ok: true, score: Math.max(0, Math.min(1, verdict.score)), why: String(verdict.why || "").slice(0, 200) };
+}
+
+/* ----------------------------------------------------------------- running */
+
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+
+/**
+ * Run every case against one engine, in its own session.
+ *
+ * Sequential within an engine because a terminal is a terminal: two prompts
+ * typed into one session at once interleave into one prompt neither of them
+ * asked. Engines run against each other in parallel, which is the fan-out.
+ */
+export async function runEngine(engineKey, cases, {
+  waitFor,
+  cwd = process.cwd(),
+  timeoutMs = 10 * 60 * 1000,
+  session = `eval-${engineKey}`,
+  keep = false,
+  out = () => {},
+  now = () => Date.now(),
+} = {}) {
+  const engine = ENGINES[engineKey];
+  if (!engine) return { engine: engineKey, ok: false, error: `unknown engine ${engineKey}`, results: [] };
+
+  const already = listSessions().some((s) => s.name === session && s.alive);
+  if (!already) {
+    const bin = resolveExecutable(engine.bin, engine.binDirs || []) || engine.bin;
+    const started = startSession({ name: session, engine: engineKey, bin, args: engine.agentArgs || [], stripEnv: engine.stripEnv || [], cwd });
+    if (!started.ok) {
+      // Infrastructure, not quality. Reported as such so a missing engine never
+      // reads as an engine that failed the dataset.
+      return { engine: engineKey, ok: false, error: String(started.error?.message || started.error), results: [] };
+    }
+    // An engine needs a moment to draw its first screen; prompting into a
+    // terminal that has not finished starting types into nothing.
+    await sleep(4000);
+  }
+
+  const results = [];
+  for (const testCase of cases) {
+    const at = now();
+    const baseline = capture(session, { lines: 60 });
+    const taskId = startTask(session, testCase.prompt, { screen: baseline, now: at });
+    const sent = sendPrompt(session, testCase.prompt);
+    if (!sent.ok) {
+      endTask(session, taskId, { state: "done", artifact: "", ts: now() });
+      results.push({ ...testCase, engine: engineKey, taskId, ok: false, answer: "", error: String(sent.error?.message || sent.error) });
+      continue;
+    }
+    await waitFor(session, ["working"], { timeoutMs: 8000, intervalMs: 500 });
+    const outcome = await waitFor(session, ["blocked", "done", "idle"], { timeoutMs });
+    const answer = screenDelta(baseline, capture(session, { lines: 400 }));
+    endTask(session, taskId, { state: outcome.state, artifact: answer, ts: now() });
+    out(`  ${engineKey} · ${testCase.id} · ${outcome.outcome} (${outcome.state})`);
+    results.push({ ...testCase, engine: engineKey, taskId, ok: outcome.outcome === "matched", answer, outcome: outcome.outcome, state: outcome.state });
+  }
+
+  if (!already && !keep) killSession(session);
+  return { engine: engineKey, ok: true, session, results };
+}
+
+/**
+ * The whole run: fan the dataset across the engines, score, and total up.
+ *
+ * `waitFor` is injected rather than imported so the runner can be exercised
+ * without a herd — the alternative is a test that starts real engines, which is
+ * not a test anyone will run.
+ */
+export async function runEval({
+  cases,
+  engines,
+  judge = "rules",
+  threshold = DEFAULT_THRESHOLD,
+  waitFor,
+  cwd = process.cwd(),
+  timeoutMs = 10 * 60 * 1000,
+  keep = false,
+  out = () => {},
+  judgeRun = runAi,
+  // Injected so the scoring and aggregation — the parts with the decisions in
+  // them — can be tested without starting an engine. A test that needs Claude
+  // installed is a test nobody runs.
+  run = runEngine,
+} = {}) {
+  const runs = await Promise.all(engines.map((engineKey) =>
+    run(engineKey, cases, { waitFor, cwd, timeoutMs, keep, out })));
+
+  const engineResults = runs.map((run) => {
+    if (!run.ok) return { engine: run.engine, ok: false, error: run.error, score: 0, cases: [] };
+    const scored = run.results.map((result) => {
+      const verdict = judge === "rules"
+        ? scoreByRules(result, result.answer)
+        : scoreByJudge(result, result.answer, { engine: judge, run: judgeRun, out });
+      return {
+        id: result.id, prompt: result.prompt, taskId: result.taskId,
+        answer: result.answer, state: result.state ?? null,
+        score: verdict.score, why: verdict.why, scored: verdict.ok,
+        ...(result.error ? { error: result.error } : {}),
+      };
+    });
+    const total = scored.reduce((sum, c) => sum + c.score, 0);
+    return {
+      engine: run.engine,
+      ok: true,
+      score: scored.length ? total / scored.length : 0,
+      passed: scored.filter((c) => c.score >= 1).length,
+      unscorable: scored.filter((c) => !c.scored).length,
+      cases: scored,
+    };
+  });
+
+  const infrastructure = engineResults.filter((e) => !e.ok);
+  const below = engineResults.filter((e) => e.ok && e.score < threshold);
+  return {
+    judge, threshold,
+    engines: engineResults,
+    // The three outcomes CI needs to tell apart, decided here rather than at
+    // the exit-code site, so `--json` and the exit code cannot disagree.
+    outcome: infrastructure.length ? "infrastructure" : below.length ? "below" : "pass",
+    below: below.map((e) => e.engine),
+    broken: infrastructure.map((e) => ({ engine: e.engine, error: e.error })),
+  };
+}
+
+/** Resolve `--engines a,b` to canonical keys, naming anything it cannot. */
+export function resolveEngines(list) {
+  const wanted = String(list || "").split(",").map((s) => s.trim()).filter(Boolean);
+  const keys = [], unknown = [];
+  for (const name of wanted) {
+    const resolved = resolveEngine(name);
+    if (resolved) keys.push(resolved[0]);
+    else unknown.push(name);
+  }
+  return { keys: [...new Set(keys)], unknown };
+}

package/src/herd-hooks.mjs

@@ -0,0 +1,285 @@
+// Engine lifecycle hooks — the herd's tier-1 state, installed (PRD 0011 R1–R2).
+//
+// PRD 0009 built the mechanism and never plugged anything into it. `moshcode
+// herd report` has existed since the herd did; it beats the screen, it is
+// TTL-bounded, and on a default install nothing ever called it. So every
+// session was classified by regex against a screen capture, and every engine
+// release was a chance for the roster to start lying — a weakness
+// src/herd-state.mjs documents about itself in its own header.
+//
+// This is the other end of that socket. `herd hooks install claude` writes
+// Claude Code's own lifecycle hooks so the engine reports its state directly,
+// and the roster starts reading `authority: hook`.
+//
+// THREE RULES, all of them about not being a bad guest in someone's config:
+//
+//   MERGE, NEVER CLOBBER. The file we write is the user's, and it is the file
+//   their other hooks live in. Install extends it; remove takes out only the
+//   entries whose command is ours, and leaves empty structure behind only when
+//   it was already there.
+//
+//   A HOOK MUST NEVER BREAK AN ENGINE. The command is guarded so that outside a
+//   herd session — no MOSHCODE_HERD_NAME — it does nothing and exits 0, and so
+//   that a box without moshcode on PATH gets the same silence rather than a
+//   failing hook on every turn. Degrading to today's screen rules is fine;
+//   degrading below today is not.
+//
+//   THE SCREEN RULES STAY. A hook that a schema change quietly breaks falls back
+//   to exactly what the herd did before it, which is why engines.mjs keeps its
+//   `state` patterns alongside the new `hooks` spec rather than replacing them.
+import fs from "node:fs";
+import path from "node:path";
+
+import { ENGINES } from "./engines.mjs";
+
+/** Engines that ship a hook spec, in table order. */
+export function hookableEngines() {
+  return Object.entries(ENGINES).filter(([, engine]) => engine.hooks).map(([key]) => key);
+}
+
+/**
+ * The shell command one hook runs.
+ *
+ * Every clause is load-bearing:
+ *   `[ -n "$MOSHCODE_HERD_NAME" ]` — outside the herd this hook is a no-op. The
+ *      engine is used by hand far more often than it is used in a herd.
+ *   `command -v moshcode` — a machine where moshcode was uninstalled must not
+ *      get a failing hook on every turn of an engine that still works.
+ *   `>/dev/null 2>&1` — a status report has nothing to say to the operator; its
+ *      whole output belongs in the roster, not in the middle of a session.
+ *   `; exit 0` — whatever happened above, the engine carries on.
+ */
+export function hookCommand(state) {
+  return `[ -n "$MOSHCODE_HERD_NAME" ] && command -v moshcode >/dev/null 2>&1 `
+    + `&& moshcode herd report "$MOSHCODE_HERD_NAME" ${state} >/dev/null 2>&1; exit 0`;
+}
+
+/**
+ * Is this hook entry one of ours?
+ *
+ * Matched on the command text rather than on a marker field we invent, because
+ * the file's schema belongs to the engine: an unknown key is something the
+ * engine is entitled to reject, and a hook config it rejects is worse than no
+ * hook at all. The command is a string we wrote, so it is a marker already.
+ */
+export function isOurs(entry) {
+  return typeof entry?.command === "string" && /\bmoshcode herd report\b/.test(entry.command);
+}
+
+const HOOK_FILE_MODE = 0o600;
+
+function readJsonFile(file) {
+  let text;
+  try { text = fs.readFileSync(file, "utf8"); }
+  catch (error) {
+    if (error.code === "ENOENT") return { ok: true, present: false, data: {} };
+    return { ok: false, present: true, error };
+  }
+  if (!text.trim()) return { ok: true, present: true, data: {} };
+  try { return { ok: true, present: true, data: JSON.parse(text) }; }
+  catch (error) {
+    // Refusing is the whole point. A settings file we cannot parse is one we
+    // cannot merge into, and overwriting it would take every other hook, MCP
+    // server and preference in it with us.
+    return { ok: false, present: true, error: new Error(`${file} is not valid JSON (${error.message}) — fix it and re-run`) };
+  }
+}
+
+function writeJsonFile(file, data, { mode = HOOK_FILE_MODE } = {}) {
+  const body = `${JSON.stringify(data, null, 2)}\n`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  // Write-then-rename: a crash mid-write on the engine's own settings file
+  // would otherwise leave it truncated, which is the one failure that costs
+  // more than the feature is worth.
+  const tmp = `${file}.moshcode-${process.pid}`;
+  fs.writeFileSync(tmp, body, { mode });
+  fs.renameSync(tmp, file);
+}
+
+/** The mode an existing file already has, so an install does not tighten it. */
+function existingMode(file) {
+  try { return fs.statSync(file).mode & 0o777; }
+  catch { return HOOK_FILE_MODE; }
+}
+
+/** Where this engine's hooks live, resolved now (specs hold a function). */
+export function hookFile(engine) {
+  const spec = ENGINES[engine]?.hooks;
+  if (!spec) return null;
+  return typeof spec.file === "function" ? spec.file() : spec.file;
+}
+
+// ---------------------------------------------------------------------------
+// The claude-settings format
+// ---------------------------------------------------------------------------
+//
+// { "hooks": { "<Event>": [ { "hooks": [ { "type": "command", "command": … } ] } ] } }
+//
+// The outer array is matcher groups. Stop, Notification and UserPromptSubmit
+// take no matcher, so ours is a group of one hook with no matcher key — an
+// empty `matcher` would be a claim about tool names for events that have none.
+
+function ensureArray(object, key) {
+  if (!Array.isArray(object[key])) object[key] = [];
+  return object[key];
+}
+
+/**
+ * Add (or refresh) our entry for one event. Returns what changed, so the caller
+ * can tell "installed 3" from "already installed" without diffing twice.
+ */
+function mergeEvent(settings, event, command) {
+  const hooks = (settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks))
+    ? settings.hooks
+    : (settings.hooks = {});
+  const groups = ensureArray(hooks, event);
+
+  for (const group of groups) {
+    const entries = Array.isArray(group?.hooks) ? group.hooks : null;
+    if (!entries) continue;
+    const at = entries.findIndex(isOurs);
+    if (at < 0) continue;
+    if (entries[at].command === command) return "unchanged";
+    // Ours, but not the current text — an upgrade that changed the command, or
+    // a hand-edit. Replacing beats appending a second copy that fires twice.
+    entries[at] = { type: "command", command };
+    return "updated";
+  }
+  groups.push({ hooks: [{ type: "command", command }] });
+  return "added";
+}
+
+/** Take our entries back out, leaving structure we did not create alone. */
+function pruneEvent(settings, event) {
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== "object" || !Array.isArray(hooks[event])) return 0;
+  let removed = 0;
+  const groups = [];
+  for (const group of hooks[event]) {
+    if (!Array.isArray(group?.hooks)) { groups.push(group); continue; }
+    const before = group.hooks.length;
+    const kept = group.hooks.filter((entry) => !isOurs(entry));
+    removed += before - kept.length;
+    // A group that held only our hook goes with it; one that held someone
+    // else's stays, with theirs intact.
+    if (!kept.length && before) continue;
+    groups.push({ ...group, hooks: kept });
+  }
+  if (groups.length) hooks[event] = groups;
+  else delete hooks[event];
+  if (!Object.keys(hooks).length) delete settings.hooks;
+  return removed;
+}
+
+/** What is installed for one engine right now. */
+export function hooksStatus(engine, { file = hookFile(engine) } = {}) {
+  const spec = ENGINES[engine]?.hooks;
+  if (!spec) return { engine, supported: false, file: null, events: [] };
+  const read = readJsonFile(file);
+  if (!read.ok) {
+    return { engine, supported: true, file, readable: false, error: String(read.error?.message || read.error), events: [] };
+  }
+  const settings = read.data || {};
+  const events = spec.events.map(({ event, state, label }) => {
+    const want = hookCommand(state);
+    const groups = Array.isArray(settings.hooks?.[event]) ? settings.hooks[event] : [];
+    const found = groups.flatMap((g) => (Array.isArray(g?.hooks) ? g.hooks : [])).filter(isOurs);
+    if (!found.length) return { event, label: label || event, state, installed: false };
+    // "Installed, but not the command this version writes" is its own answer:
+    // it is how a spec change after an upgrade shows up, and `install` fixes it.
+    return { event, label: label || event, state, installed: true, current: found.some((h) => h.command === want) };
+  });
+  return {
+    engine,
+    supported: true,
+    file,
+    readable: true,
+    present: read.present,
+    installed: events.every((e) => e.installed && e.current),
+    partial: events.some((e) => e.installed) && !events.every((e) => e.installed && e.current),
+    events,
+  };
+}
+
+/**
+ * Write this engine's hooks. `dryRun` computes everything and writes nothing,
+ * returning the file as it would have been so the caller can show a diff.
+ */
+export function installHooks(engine, { file = hookFile(engine), dryRun = false } = {}) {
+  const spec = ENGINES[engine]?.hooks;
+  if (!spec) {
+    return { ok: false, engine, supported: false, error: new Error(`${engine} ships no hook spec — its sessions stay on the screen rules`) };
+  }
+  const read = readJsonFile(file);
+  if (!read.ok) return { ok: false, engine, supported: true, file, error: read.error };
+
+  const before = JSON.stringify(read.data ?? {}, null, 2);
+  const settings = read.data ?? {};
+  const changes = spec.events.map(({ event, state, label }) => ({ event, label: label || event, state, change: mergeEvent(settings, event, hookCommand(state)) }));
+  const after = JSON.stringify(settings, null, 2);
+
+  if (!dryRun) {
+    try { writeJsonFile(file, settings, { mode: read.present ? existingMode(file) : HOOK_FILE_MODE }); }
+    catch (error) { return { ok: false, engine, supported: true, file, error }; }
+  }
+  return {
+    ok: true, engine, supported: true, file, dryRun,
+    changes,
+    written: changes.filter((c) => c.change !== "unchanged").length,
+    before, after,
+  };
+}
+
+/** Take them out again. Only ever removes commands this module wrote. */
+export function removeHooks(engine, { file = hookFile(engine), dryRun = false } = {}) {
+  const spec = ENGINES[engine]?.hooks;
+  if (!spec) return { ok: false, engine, supported: false, error: new Error(`${engine} ships no hook spec`) };
+  const read = readJsonFile(file);
+  if (!read.ok) return { ok: false, engine, supported: true, file, error: read.error };
+  if (!read.present) return { ok: true, engine, supported: true, file, removed: 0, dryRun };
+
+  const settings = read.data ?? {};
+  const before = JSON.stringify(settings, null, 2);
+  let removed = 0;
+  // Every event the spec knows about, plus any event that still carries one of
+  // ours from an older spec — otherwise `remove` after an upgrade would leave
+  // the hook the previous version installed firing forever.
+  const events = new Set([
+    ...spec.events.map((e) => e.event),
+    ...Object.keys(settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {}),
+  ]);
+  for (const event of events) removed += pruneEvent(settings, event);
+  const after = JSON.stringify(settings, null, 2);
+
+  if (!dryRun && removed) {
+    try { writeJsonFile(file, settings, { mode: existingMode(file) }); }
+    catch (error) { return { ok: false, engine, supported: true, file, error }; }
+  }
+  return { ok: true, engine, supported: true, file, removed, dryRun, before, after };
+}
+
+/**
+ * A unified diff of the two JSON snapshots an install/remove produced.
+ *
+ * Hand-rolled and deliberately dumb — a line is context, an addition, or a
+ * removal, decided by whether the other side has it at the same place. What
+ * `--dry-run` needs is "show me what you are about to do to my settings file",
+ * and for a JSON object printed at two-space indent that is what this gives.
+ */
+export function hookDiff(before = "", after = "") {
+  const a = String(before).split("\n");
+  const b = String(after).split("\n");
+  const out = [];
+  let i = 0, j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) { out.push(`  ${a[i]}`); i++; j++; continue; }
+    const laterInB = b.indexOf(a[i] ?? "", j);
+    const laterInA = a.indexOf(b[j] ?? "", i);
+    if (i >= a.length || (laterInB >= 0 && (laterInA < 0 || laterInB - j <= laterInA - i))) {
+      out.push(`+ ${b[j]}`); j++;
+    } else {
+      out.push(`- ${a[i]}`); i++;
+    }
+  }
+  return out.join("\n");
+}