simt-dev 0.6.0 → 0.6.3

package/src/commands/hooks.mjs

@@ -13,7 +13,10 @@
 // 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 { chmod, mkdir, readFile, realpath } from 'node:fs/promises';
+import { commitJournal, 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';
 
@@ -23,7 +26,7 @@ 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';
@@ -60,14 +63,7 @@ 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;
 }
 
@@ -101,27 +97,26 @@ 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
@@ -240,6 +235,148 @@ 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,
+    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, version, routed, wants, current } =
+    planned;
+  // Shim and evidence bytes are journaled so `undo` restores them (R49). The
+  // `core.hooksPath` config below is deliberately not journaled: it is git
+  // config, not a repo file, and `undo` restores files.
+  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, version }));
+    await chmod(path, 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));
+    await chmod(path, 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);
+    await chmod(path, 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 exec('git', ['config', HOOKS_PATH_KEY, wants], { cwd: root });
+  } else if (current === wants) {
+    await exec('git', ['config', '--unset', HOOKS_PATH_KEY], { cwd: root });
+  }
+  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, 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, 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,
+    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
@@ -307,7 +444,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 +460,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 +483,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, 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 +525,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, 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 +589,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 +614,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;
+}