simt-dev 0.6.2 → 0.7.0

package/src/commands/hooks.mjs

@@ -12,10 +12,11 @@
 // DEFAULT location, which core.hooksPath being unset does not reveal, so a
 // foreign hook is found by asking git rather than by reading config.
 
-import { execFile } from 'node:child_process';
-import { chmod, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath } from 'node:fs/promises';
+import { commitJournal, journaledGitConfig, journaledRemoveFile, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { invalidateCheckCache } from '../status.mjs';
 import { isAbsolute, join, relative } from 'node:path';
-import { promisify } from 'node:util';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { MANIFEST, readManifest } from '../projection/manifest.mjs';
@@ -23,13 +24,11 @@ import { EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedS
 import { GATE_KEY, gateCount, readHooksPath, readHooksState, wantsShim } from '../compare/hooksstate.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { knownGates } from '../hooks/resolve.mjs';
-import { runGates } from '../hooks/dispatcher.mjs';
+import { renderGateReport, runGates } from '../hooks/dispatcher.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
 
-const exec = promisify(execFile);
-
 export async function hooksCommand(sub, args, flags) {
   const root = flags.root ?? args[0] ?? process.cwd();
   if (sub === 'install') return installHooks(root, flags);
@@ -51,7 +50,12 @@ async function runHook(args, flags) {
     return fail(`${root} has no ${MANIFEST_FILE}; the hook cannot know its gate list`, EXIT.CONFIG, `run: ${CLI} init --root ${root}`);
   }
 
-  const result = await runGates(event, { root, manifest });
+  // git feeds pre-push its ref list on stdin, and the docs-only skip (ADR-113)
+  // needs it. A manual run from a terminal has a TTY and reads empty, which the
+  // dispatcher treats as "no push to classify" and answers with the full suite.
+  const pushed = event === 'pre-push' ? await readStdin() : undefined;
+
+  const result = await runGates(event, { root, manifest, pushed });
   if (result.error) return fail(result.error, EXIT.USAGE);
 
   if (isJson(flags)) {
@@ -60,17 +64,33 @@ async function runHook(args, flags) {
   }
 
   for (const n of result.notes ?? []) note(`note     ${n}`);
-  const lines = [`hooks    ${event}`, `gates    ${(manifest.gates[GATE_KEY[event]] ?? []).join(', ') || '(none declared)'}`];
-  for (const g of result.gates) {
-    lines.push(`${g.status.toUpperCase().padEnd(8)} ${g.name.padEnd(20)} ${g.detail}${g.adr ? `  [${g.adr}]` : ''}`);
-    if (g.remedy) lines.push(`        remedy: ${g.remedy}`);
-    if (g.output) lines.push(...g.output.split('\n').map((l) => `        ${l}`));
-  }
-  lines.push(result.failed ? 'BLOCKED  at least one gate failed' : 'PASSED');
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(renderGateReport(event, manifest.gates[GATE_KEY[event]] ?? [], result).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
   return result.failed ? EXIT.FAIL : EXIT.OK;
 }
 
+/**
+ * Read all of stdin, or '' when there is none to read.
+ *
+ * The pre-push shim execs this command, so git's ref list arrives on the
+ * dispatcher's stdin. A TTY (a manual run from a terminal) has no ref list and
+ * reads empty - and empty is the fail-closed answer: the dispatcher cannot
+ * classify a push it was never told about, so the suite runs.
+ *
+ * @returns {Promise<string>}
+ */
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve('');
+      return;
+    }
+    const chunks = [];
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.resume();
+  });
+}
+
 /**
  * The path to write into a chained shim: relative to the repository's top level
  * wherever the hook lives inside it.
@@ -101,33 +121,48 @@ async function relativeTarget(root, target) {
   return rel === '' || rel.startsWith('..') ? resolved : rel;
 }
 
-async function installHooks(root, flags) {
-  const { manifest, exists, error } = await readManifest(root);
-  if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG);
-  if (!exists) {
-    return fail(`${root} has no ${MANIFEST_FILE}; gates must be declared before hooks can run them`, EXIT.CONFIG, `run: ${CLI} init --root ${root}`);
-  }
-
+/**
+ * What `hooks install` would write, computed without writing or reporting (plan 0003 R47).
+ *
+ * `installHooks` and `doctor --fix` share this rather than each deriving the write
+ * set: the set nothing else here touches (obsolete shims, chained foreign hooks)
+ * is exactly the set a second derivation gets wrong, and a fix that writes bytes
+ * the command would not is a fix that lies about what it did. Reporting stays
+ * with the callers — the plan table belongs to the command, the finding line to
+ * the doctor — so this returns facts, never text.
+ *
+ * @returns the install inputs `applyHooksInstall` needs, plus the guards each
+ *   caller enforces in its own voice (`takeover`, and the `wanted`/`obsolete`
+ *   emptiness the command refuses on)
+ */
+export async function planHooksInstall(root, { manifest, exists }) {
   const declaresGate = (event) => wantsShim(manifest, exists, event);
   const state = await readHooksState(root, { declaresGate });
   const current = state.current;
   const wants = HOOKS_DIR;
 
-  // Read through `writeMode` like every other writer, and only now: this command
-  // used to consult `flags.yes` and `flags.dryRun` directly and write when neither
-  // said otherwise, which made it the last writer still writing by default after
-  // ADR-035 and ADR-036 had settled that none of them may. Review 0002's S24
-  // listed it among the writers that "all preview first"; that was wrong, and the
-  // migration script in the same review tells an operator to run `hooks install`
-  // for a plan and then `--yes` - advice that printed a plan and wrote anyway.
-  const mode = writeMode(flags);
-
   // The release this install renders, and the kind of repository it installs into: the
   // remedy a shim prints when it cannot find the binary must name the install that
   // actually works here — a devDependency where package.json exists, a pinned global
   // install where there is no node_modules to pin in.
   const version = packageVersion();
   const npm = await hasNpm(root);
+  // Q31: installed shims name the repo's own installer in their remedy.
+  // Lockfile first, `packageManager` next, npm default — the one resolver.
+  let manager = null;
+  if (npm) {
+    const { resolveNodeRunner } = await import('../ecosystem/node-runner.mjs');
+    let packageManager = null;
+    try {
+      const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+      if (typeof pkg.packageManager === 'string') packageManager = pkg.packageManager;
+    } catch {
+      // Unreadable here leaves the npm default; the manifest path reports it.
+    }
+    const { fingerprint } = await import('../resolve/fingerprint.mjs');
+    const detected = await fingerprint(root);
+    manager = resolveNodeRunner({ facts: detected.facts, packageManager }).id;
+  }
 
   // Only install a shim for an event that declares at least one gate. A shim with
   // an empty gate list enforces nothing, yet merely existing it REPLACES whatever
@@ -229,7 +264,7 @@ async function installHooks(root, flags) {
   const evidenceDeclared = manifest?.gates?.evidence === 'warn' || manifest?.gates?.evidence === 'block';
   const evidenceFile = fileFor('commit-msg');
   const evidenceExisting = await readIfExists(join(root, evidenceFile));
-  const evidenceSource = evidenceDeclared ? renderEvidenceShim({ npm, version }) : null;
+  const evidenceSource = evidenceDeclared ? renderEvidenceShim({ npm, manager, version }) : null;
   const evidenceOurs = evidenceExisting !== null && evidenceExisting.includes(SHIM_MARKER);
   if (!evidenceDeclared && evidenceOurs) obsolete.push({ event: 'commit-msg' });
   // A foreign commit-msg would otherwise be chained onto the same path. The chain
@@ -240,6 +275,151 @@ async function installHooks(root, flags) {
     if (at !== -1) chained.splice(at, 1);
   }
 
+  const routed = wanted.length > 0 || chained.length > 0 || evidenceDeclared;
+  const takeover = (current !== null && current !== wants) || state.foreign.length > 0;
+  return {
+    manifest,
+    state,
+    current,
+    wants,
+    npm,
+    manager,
+    version,
+    wanted,
+    chained,
+    leftRunning,
+    obsolete,
+    evidenceDeclared,
+    evidenceSource,
+    evidenceFile,
+    // Returned so a caller can tell a current claim check from a stale one
+    // without re-reading the file: the evidence shim is not one of EVENTS, so
+    // neither the problems list nor the obsolete set names its staleness.
+    evidenceExisting,
+    routed,
+    takeover,
+  };
+}
+
+/**
+ * Write a planned install: shims, chains, removals, and the git routing (plan 0003 R47).
+ *
+ * The caller's journal records the file writes, and the caller commits it under
+ * its own command name — `hooks install` here, `doctor --fix` there — so `undo`
+ * names the run that actually changed something. Reporting stays with the
+ * caller for the same reason it does in `planHooksInstall`.
+ *
+ * @returns {{wrote: string[]}} the shim paths written, removed, or refreshed
+ */
+export async function applyHooksInstall(root, planned, journal) {
+  const { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version, routed, wants, current } =
+    planned;
+  // Shim and evidence bytes are journaled so `undo` restores them (R49), with
+  // the executable bit they are written with: a shim the run chmodded is one
+  // change, and `undo` must restore the mode it found, not just the bytes.
+  // The `core.hooksPath` routing below is journaled as a `git-config` entry
+  // for the same reason — unwinding the shims while the config still points
+  // at their directory silently stops the repository's own hooks (review 0003
+  // Q22).
+  const wrote = [];
+  await mkdir(join(root, HOOKS_DIR), { recursive: true });
+  for (const event of wanted) {
+    const path = join(root, fileFor(event));
+    await journaledWriteFile(root, journal, path, renderShim(event, { npm, manager, version }), { mode: 0o755 });
+    wrote.push(fileFor(event));
+  }
+  for (const c of chained) {
+    const path = join(root, fileFor(c.event));
+    await journaledWriteFile(root, journal, path, renderChainedShim(c.event, c.target), { mode: 0o755 });
+    wrote.push(fileFor(c.event));
+  }
+  for (const h of obsolete) {
+    await journaledRemoveFile(root, journal, join(root, fileFor(h.event)));
+    wrote.push(fileFor(h.event));
+  }
+  // After the chain loop, so a chained commit-msg cannot replace the claim check.
+  if (evidenceSource) {
+    const path = join(root, evidenceFile);
+    await journaledWriteFile(root, journal, path, evidenceSource, { mode: 0o755 });
+    wrote.push(evidenceFile);
+  }
+  // `core.hooksPath` tells git to read ONE directory for EVERY event, so leaving it
+  // pointing at a directory of no shims stops the repository's own hooks - the ones in
+  // `.git/hooks` that predate this tool - from running, silently. Unsetting it is the
+  // only way back, and this is the only place that knows the last shim just left.
+  if (routed) {
+    await journaledGitConfig(root, journal, HOOKS_PATH_KEY, wants);
+  } else if (current === wants) {
+    await journaledGitConfig(root, journal, HOOKS_PATH_KEY, null);
+  }
+  return { wrote };
+}
+
+/**
+ * The `--diff` pairs for a planned install: current disk against what the
+ * install would write, re-rendered from the same inputs `applyHooksInstall`
+ * writes (plan 0003 R50). Read-only, so preview and apply share it, and
+ * `doctor --fix` reuses it rather than deriving a second answer.
+ */
+export async function plannedDiffs(root, planned) {
+  const { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version } = planned;
+  const pairs = [];
+  for (const event of wanted) {
+    const path = fileFor(event);
+    pairs.push({ path, before: await readBefore(join(root, path)), after: renderShim(event, { npm, manager, version }) });
+  }
+  for (const c of chained) {
+    const path = fileFor(c.event);
+    pairs.push({ path, before: await readBefore(join(root, path)), after: renderChainedShim(c.event, c.target) });
+  }
+  for (const h of obsolete) {
+    const path = fileFor(h.event);
+    pairs.push({ path, before: await readBefore(join(root, path)), after: null });
+  }
+  if (evidenceSource) {
+    pairs.push({ path: evidenceFile, before: await readBefore(join(root, evidenceFile)), after: evidenceSource });
+  }
+  return pairs;
+}
+
+async function installHooks(root, flags) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG);
+  if (!exists) {
+    return fail(`${root} has no ${MANIFEST_FILE}; gates must be declared before hooks can run them`, EXIT.CONFIG, `run: ${CLI} init --root ${root}`);
+  }
+
+  // One computation, two callers (R47): the write set is derived once in
+  // `planHooksInstall` and shared with `doctor --fix`, so a fix applies exactly
+  // the bytes this command would write. Reporting stays here.
+  const {
+    state,
+    current,
+    wants,
+    npm,
+    manager,
+    version,
+    wanted,
+    chained,
+    leftRunning,
+    obsolete,
+    evidenceDeclared,
+    evidenceSource,
+    evidenceFile,
+    evidenceExisting,
+    routed,
+    takeover,
+  } = await planHooksInstall(root, { manifest, exists });
+
+  // Read through `writeMode` like every other writer, and only now: this command
+  // used to consult `flags.yes` and `flags.dryRun` directly and write when neither
+  // said otherwise, which made it the last writer still writing by default after
+  // ADR-035 and ADR-036 had settled that none of them may. Review 0002's S24
+  // listed it among the writers that "all preview first"; that was wrong, and the
+  // migration script in the same review tells an operator to run `hooks install`
+  // for a plan and then `--yes` - advice that printed a plan and wrote anyway.
+  const mode = writeMode(flags);
+
   // Nothing to write and nothing to take away is the only refusal. It sits after
   // `obsolete` because a repository whose last gate just left the manifest has
   // something to take away, and blocking that one left no way out except undoing
@@ -266,7 +446,7 @@ async function installHooks(root, flags) {
   const plan = [];
   for (const event of wanted) {
     const path = join(root, fileFor(event));
-    const source = renderShim(event, { npm, version });
+    const source = renderShim(event, { npm, manager, version });
     const existing = await readIfExists(path);
     if (existing === source) {
       plan.push({ file: fileFor(event), action: 'unchanged' });
@@ -307,7 +487,6 @@ async function installHooks(root, flags) {
       note: 'commit-msg checks a verification claim against the ledger',
     });
   }
-  const routed = wanted.length > 0 || chained.length > 0 || evidenceDeclared;
 
   // The routing this install leaves behind, which is not always `wants`. A repository
   // that removed its last gate has no shims to route to, and leaving `core.hooksPath`
@@ -324,7 +503,6 @@ async function installHooks(root, flags) {
   // being unset while a hook sits in the default location (4 KB of real logic in
   // .git/hooks/pre-commit). Reading unset as
   // "no hooks" is what let install replace a working gate with no warning.
-  const takeover = (current !== null && current !== wants) || state.foreign.length > 0;
   if (takeover && !flags.yes) {
     const detail = state.foreign.length > 0
       ? state.foreign.map((f) => `  git runs ${f.event} at ${f.path} (${f.bytes} bytes)`)
@@ -348,12 +526,29 @@ async function installHooks(root, flags) {
     return EXIT.FAIL;
   }
 
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50).
+  const diffs =
+    flags.diff === true
+      ? await plannedDiffs(root, { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version })
+      : [];
+
   if (!mode.apply) {
     if (isJson(flags)) {
       // `leaves`, not `wants`. A plan that would remove the last shim also un-routes
       // git, and a payload promising to set a directory the command is about to unset
       // is the same lie in a shape a machine reads.
-      emitJson({ ok: true, command: 'hooks install', root, dryRun: true, currentHooksPath: current, wouldSet: leaves, plan, filesWritten: false });
+      emitJson({
+        ok: true,
+        command: 'hooks install',
+        root,
+        dryRun: true,
+        currentHooksPath: current,
+        wouldSet: leaves,
+        plan,
+        filesWritten: false,
+        ...diffField(diffs, flags),
+      });
       return EXIT.OK;
     }
     emit(
@@ -373,39 +568,23 @@ async function installHooks(root, flags) {
       ),
       { maxBytes: flags.maxBytes ?? 0 },
     );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     return EXIT.OK;
   }
 
-  await mkdir(join(root, HOOKS_DIR), { recursive: true });
-  for (const event of wanted) {
-    const path = join(root, fileFor(event));
-    await writeFile(path, renderShim(event, { npm, version }));
-    await chmod(path, 0o755);
-  }
-  for (const c of chained) {
-    const path = join(root, fileFor(c.event));
-    await writeFile(path, renderChainedShim(c.event, c.target));
-    await chmod(path, 0o755);
-  }
-  for (const h of obsolete) {
-    await rm(join(root, fileFor(h.event)));
-  }
-  // After the chain loop, so a chained commit-msg cannot replace the claim check.
-  if (evidenceSource) {
-    const path = join(root, evidenceFile);
-    await writeFile(path, evidenceSource);
-    await chmod(path, 0o755);
-  }
-
-  // `core.hooksPath` tells git to read ONE directory for EVERY event, so leaving it
-  // pointing at a directory of no shims stops the repository's own hooks - the ones in
-  // `.git/hooks` that predate this tool - from running, silently. Unsetting it is the
-  // only way back, and this is the only place that knows the last shim just left.
-  if (routed) {
-    await exec('git', ['config', HOOKS_PATH_KEY, wants], { cwd: root });
-  } else if (current === wants) {
-    await exec('git', ['config', '--unset', HOOKS_PATH_KEY], { cwd: root });
-  }
+  // Same bytes, two callers (R47): the write itself lives in `applyHooksInstall`
+  // and is shared with `doctor --fix`, so a fix installs what the command would.
+  const journal = [];
+  await applyHooksInstall(
+    root,
+    { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version, routed, wants, current },
+    journal,
+  );
+  await commitJournal(root, 'hooks install', journal);
+  // Shims and routing changed, so the hooks slot of the last `check` is stale
+  // (R48). Gated on the journal: an already-current install changes nothing.
+  if (journal.length > 0) await invalidateCheckCache(root);
 
   const notes = [];
   const chainedEvents = new Set(chained.map((c) => c.event));
@@ -453,7 +632,17 @@ async function installHooks(root, flags) {
   }
 
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'hooks install', root, hooksPath: leaves, previousHooksPath: current, plan, filesWritten: true, notes });
+    emitJson({
+      ok: true,
+      command: 'hooks install',
+      root,
+      hooksPath: leaves,
+      previousHooksPath: current,
+      plan,
+      filesWritten: true,
+      notes,
+      ...diffField(diffs, flags),
+    });
     return EXIT.OK;
   }
   emit(
@@ -468,6 +657,8 @@ async function installHooks(root, flags) {
     ),
     { maxBytes: flags.maxBytes ?? 0 },
   );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   for (const n of notes) note(`note     ${n}`);
   note(`note     never committed or pushed (ADR-001); review, then commit yourself`);
   return EXIT.OK;

package/src/commands/ignore.mjs

@@ -0,0 +1,152 @@
+// `simt ignore` — render the one ignore list into every reader's dialect
+// (plan 0003 R52).
+//
+// Shape copied from `ci`: the plan is printed first, nothing is written
+// without `--yes`, `--diff` shows the same plan as unified diffs and `undo`
+// restores the set (R49). Three of the four targets are generated from the
+// list; `.claude/settings.json` is merged, never replaced — see src/ignore.mjs
+// for why that distinction exists.
+
+import { join } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { CLAUDE_SETTINGS, IGNORE_FILE, parseIgnoreList, planIgnore } from '../ignore.mjs';
+
+export async function ignoreCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+
+  let source;
+  try {
+    source = await readBefore(join(root, IGNORE_FILE));
+  } catch (error) {
+    return fail(`${IGNORE_FILE} could not be read: ${error.message}`, EXIT.FAIL, `fix the file's permissions, then re-run: ${CLI} ignore`);
+  }
+  if (source === null) {
+    // A missing list is a missing input, not an empty one: rendering four empty
+    // files from a file that does not exist would answer the request with
+    // silence the reader has no way to tell from success.
+    return fail(
+      `no ${IGNORE_FILE} in ${root}`,
+      EXIT.FAIL,
+      `create ${IGNORE_FILE} with one path or glob per line (# comments), then: ${CLI} ignore`,
+    );
+  }
+
+  const entries = parseIgnoreList(source);
+  if (entries.length === 0) {
+    return fail(
+      `${IGNORE_FILE} parses to zero entries`,
+      EXIT.FAIL,
+      `add one path or glob per line to ${IGNORE_FILE}, then: ${CLI} ignore`,
+    );
+  }
+
+  const plan = await planIgnore(entries, (path) => readBefore(join(root, path)));
+  if (!plan.ok) {
+    return fail(plan.error, EXIT.FAIL, `repair ${CLAUDE_SETTINGS} by hand, then re-run: ${CLI} ignore`);
+  }
+
+  const mode = writeMode(flags);
+  const changed = plan.targets.filter((t) => t.action !== 'unchanged');
+  const diffs =
+    flags.diff === true
+      ? changed.map((t) => ({ path: t.path, before: t.before, after: t.after }))
+      : [];
+
+  // Nothing to do: the report says so from the same plan the write would have
+  // used, so "unchanged" cannot disagree with what `--yes` would have written.
+  if (changed.length === 0) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'ignore',
+        root,
+        source: IGNORE_FILE,
+        entries: entries.length,
+        files: plan.targets.map((t) => ({ path: t.path, action: t.action, bytes: byteLen(t.after) })),
+        written: false,
+        dryRun: false,
+      });
+    } else {
+      emit(plan.targets.map((t) => `current  ${t.path}  ${byteLen(t.after)} bytes`).join('\n'));
+      note('every target already matches the list; nothing to write');
+    }
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `repo      ${root}`,
+    `source    ${IGNORE_FILE} (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`,
+    '',
+  ];
+  for (const t of plan.targets) {
+    lines.push(`file      ${t.path}`, `action    ${t.action}`);
+    if (t.action === 'update' && t.before !== null) {
+      // An update whose before side has lines the list does not: those lines
+      // are about to stop existing. Named here because a preview that only says
+      // "update" hides the deletion inside the diff the reader has to ask for.
+      const dropped = countDropped(t.before, t.after);
+      if (dropped > 0) lines.push(`replaces  ${dropped} line(s) not in ${IGNORE_FILE} (shown by --diff)`);
+    }
+  }
+
+  // Exactly one JSON document per run, emitted once on whichever path ends it:
+  // a preview and its write are two phases of ONE answer, and a reader that
+  // parses the first document gets "written: false" while the run writes.
+  const payload = (written) => ({
+    ok: true,
+    command: 'ignore',
+    root,
+    source: IGNORE_FILE,
+    entries: entries.length,
+    files: plan.targets.map((t) => ({ path: t.path, action: t.action, bytes: byteLen(t.after) })),
+    written,
+    dryRun: !mode.apply,
+    ...diffField(diffs, flags),
+  });
+
+  if (!isJson(flags)) emit(lines.join('\n'));
+
+  if (!mode.apply) {
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
+    if (isJson(flags)) {
+      emitJson(payload(false));
+    } else {
+      note('');
+      note(mode.dryRun ? 'dry-run  nothing written' : `dry-run  nothing written; apply with: ${CLI} ignore --yes`);
+    }
+    return EXIT.OK;
+  }
+
+  // Journaled so `undo` restores this run (R49). Every note writes to stderr,
+  // so the `--json` document remains the only bytes on stdout.
+  const journal = [];
+  for (const t of changed) {
+    await journaledWriteFile(root, journal, join(root, t.path), t.after);
+    note(`wrote    ${t.path} (${t.action})`);
+  }
+  await commitJournal(root, 'ignore', journal);
+
+  if (isJson(flags)) emitJson(payload(true));
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
+  return EXIT.OK;
+}
+
+function byteLen(text) {
+  return Buffer.byteLength(text, 'utf8');
+}
+
+/**
+ * How many lines the new bytes drop from the old: lines the current file has
+ * that the list does not produce. Used only for the plan's `replaces` note —
+ * the diff is the authoritative statement of what goes.
+ */
+function countDropped(before, after) {
+  const kept = new Set(after.split('\n'));
+  return before.split('\n').filter((line) => line.trim() !== '' && !kept.has(line)).length;
+}

package/src/commands/impact.mjs

@@ -191,8 +191,10 @@ function textExt(file) {
 
 async function tracked(root) {
   try {
-    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
-    return { files: stdout.split('\n').filter(Boolean) };
+    // `-z`: without it git C-quotes a non-ASCII path and the reader's real
+    // filename never matches it (review 0003 Q39).
+    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\0').filter(Boolean) };
   } catch (error) {
     return {
       error: fail(