simt-dev 0.6.3 → 0.7.0

package/src/hooks/dispatcher.mjs

@@ -19,12 +19,14 @@
 //   its reason, so "passed" can never be mistaken for "only some of it passed".
 
 import { execFile } from 'node:child_process';
-import { readFile, stat } from 'node:fs/promises';
-import { basename, join, resolve, sep } from 'node:path';
+import { mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, matchesGlob, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
 import { GATES } from './gates.mjs';
 import { resolveGate } from './resolve.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { assertVersionPin } from '../package-version.mjs';
@@ -36,14 +38,181 @@ const exec = promisify(execFile);
 /** Gates that are known but not required for the event to pass. */
 const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
 
+/** The sha git writes for a ref that does not exist on the remote yet. */
+const ZERO_SHA = '0'.repeat(40);
+
+/**
+ * The lines git feeds a pre-push hook on stdin, one per ref being pushed:
+ * `<local ref> <local sha> <remote ref> <remote sha>`.
+ *
+ * Returns `{ refs, error }`. A line this parser cannot read is an ERROR, not a
+ * dropped line: a push that cannot be read is a push that cannot be classified,
+ * and the classifier's contract is to fail closed to the full suite.
+ *
+ * @param {string} text the raw stdin
+ * @returns {{refs: {ref: string, localSha: string, remoteSha: string}[] | null, error: string | null}}
+ */
+export function parsePushedRefs(text) {
+  const refs = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const parts = trimmed.split(' ');
+    if (parts.length !== 4) return { refs: null, error: `unrecognized pre-push line: ${trimmed}` };
+    const [ref, localSha, , remoteSha] = parts;
+    if (!/^[0-9a-f]{40}$/.test(localSha) || !/^[0-9a-f]{40}$/.test(remoteSha)) {
+      return { refs: null, error: `unrecognized sha in pre-push line: ${trimmed}` };
+    }
+    refs.push({ ref, localSha, remoteSha });
+  }
+  return { refs, error: null };
+}
+
+/**
+ * Confirm a tag's commit is already accounted for, so the tag may ride along in a
+ * docs-only push (ADR-113). A tag carries no commits of its own in the release flow:
+ * it points at commits delivered (and tested) by a branch push. It is acceptable only
+ * when the commit it names is reachable from a remote-tracking ref (already pushed) or
+ * from a branch tip this same push is delivering. Any uncertainty - the tag does not
+ * resolve to a commit, the remote refs cannot be listed, no candidate is known, or the
+ * commit is unreachable from all of them - fails closed to the full suite.
+ *
+ * @param {string} root the repository to ask git
+ * @param {string} tagSha the tag's local sha from the pre-push line
+ * @param {string[]} pushingTips branch tips this same push is delivering
+ * @returns {Promise<{ok: boolean, reason: string | null}>}
+ */
+async function tagCommitAccountedFor(root, tagSha, pushingTips) {
+  let commit;
+  try {
+    ({ stdout: commit } = await exec('git', ['rev-parse', `${tagSha}^{commit}`], { cwd: root }));
+  } catch (error) {
+    return { ok: false, reason: `the tag could not be resolved to a commit: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  commit = commit.trim();
+
+  let remoteRefs;
+  try {
+    ({ stdout: remoteRefs } = await exec('git', ['for-each-ref', 'refs/remotes/', '--format=%(refname)'], { cwd: root }));
+  } catch (error) {
+    return { ok: false, reason: `the remote refs could not be listed: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  const candidates = [
+    ...remoteRefs.split('\n').map((s) => s.trim()).filter((s) => s !== ''),
+    ...pushingTips,
+  ];
+  if (candidates.length === 0) {
+    return { ok: false, reason: 'no remote refs are known and no branch is being pushed, so the tag’s commit cannot be confirmed as already delivered' };
+  }
+  for (const candidate of candidates) {
+    try {
+      await exec('git', ['merge-base', '--is-ancestor', commit, candidate], { cwd: root });
+      return { ok: true, reason: null };
+    } catch {
+      // not reachable from this ref; try the next candidate
+    }
+  }
+  return { ok: false, reason: `the tag’s commit (${commit.slice(0, 7)}) is not reachable from any pushed ref; it may not have been tested` };
+}
+
+/**
+ * Decide whether a push carries only documentation, so the `test` gate may be
+ * skipped for it (ADR-113). Every uncertainty fails closed to `{ docsOnly: false }`
+ * with the reason the full suite runs: an empty ref list, a new branch (no remote
+ * sha to diff against), a tag whose commit is not confirmed already delivered, a
+ * commit count above the ceiling, a file outside the declared paths, or a git error.
+ *
+ * Branch refs are judged on a TREE diff (`remote..local`), so a force push that
+ * drops commits is judged on the trees it replaces, not on the commit count alone.
+ * Tag refs carry no commits of their own; each is accepted only when its commit is
+ * already accounted for (see `tagCommitAccountedFor`). Deletions push nothing.
+ *
+ * @param {string} root the repository to ask git
+ * @param {{ref: string, localSha: string, remoteSha: string}[]} refs
+ * @param {{maxCommits: number, paths: string[]}} config the manifest's `gates.prePushSkipTest`
+ * @returns {Promise<{docsOnly: boolean, reason: string}>}
+ */
+export async function classifyPush(root, refs, { maxCommits, paths }) {
+  if (refs.length === 0) {
+    return { docsOnly: false, reason: 'the push carries no readable ref list; running the full suite' };
+  }
+  const deletions = refs.filter((r) => r.localSha === ZERO_SHA).length;
+  const branches = refs.filter((r) => r.localSha !== ZERO_SHA && !r.ref.startsWith('refs/tags/'));
+  const tags = refs.filter((r) => r.localSha !== ZERO_SHA && r.ref.startsWith('refs/tags/'));
+
+  let commits = 0;
+  const files = new Set();
+  for (const { ref, localSha, remoteSha } of branches) {
+    if (remoteSha === ZERO_SHA) {
+      return { docsOnly: false, reason: `a new branch is being pushed (${ref}); its history cannot be diffed against the remote` };
+    }
+    let count, names;
+    try {
+      ({ stdout: count } = await exec('git', ['rev-list', '--count', `${remoteSha}..${localSha}`], { cwd: root }));
+      ({ stdout: names } = await exec('git', ['diff', '--name-only', `${remoteSha}..${localSha}`], { cwd: root }));
+    } catch (error) {
+      return { docsOnly: false, reason: `the push could not be diffed: ${String(error.stderr ?? error.message).trim()}` };
+    }
+    commits += Number(count.trim());
+    for (const f of names.split('\n')) {
+      const name = f.trim();
+      if (name !== '') files.add(name);
+    }
+  }
+
+  const pushingTips = branches.map((b) => b.localSha);
+  for (const { localSha } of tags) {
+    const verdict = await tagCommitAccountedFor(root, localSha, pushingTips);
+    if (!verdict.ok) return { docsOnly: false, reason: verdict.reason };
+  }
+
+  if (commits > maxCommits) {
+    return { docsOnly: false, reason: `${commits} commits exceed the ${maxCommits}-commit ceiling for a docs-only push` };
+  }
+  const outside = [...files].filter((f) => !paths.some((p) => matchesGlob(f, p)));
+  if (outside.length > 0) {
+    return { docsOnly: false, reason: `${outside.length} file(s) are outside the docs-only paths: ${outside.slice(0, 5).join(', ')}` };
+  }
+
+  const parts = [];
+  if (commits > 0) parts.push(`${commits} commit(s) touching ${files.size} file(s), all inside the docs-only paths`);
+  if (tags.length > 0) parts.push(`${tags.length} tag(s) already delivered`);
+  if (deletions > 0) parts.push(`${deletions} ref deletion(s)`);
+  return { docsOnly: true, reason: parts.length > 0 ? parts.join('; ') : 'no commits carried' };
+}
+
+/**
+ * The pre-push skip decision, from the manifest and the ref list git fed on stdin.
+ *
+ * The skip is OPT-IN: a repository without `gates.prePushSkipTest` runs the full
+ * suite on every push, because a control a repo did not declare is one it did not
+ * review. A misdeclaration (missing fields) also runs the suite - a skip the
+ * manifest cannot state precisely is a skip a reviewer cannot see.
+ *
+ * @returns {Promise<{reason: string} | null>} null runs the suite; a reason skips the `test` gate
+ */
+async function resolveDocsOnlySkip(root, manifest, pushed) {
+  if (pushed === undefined) return null;
+  const config = manifest?.gates?.prePushSkipTest;
+  if (typeof config?.maxCommits !== 'number' || !Array.isArray(config?.paths)) return null;
+  const { refs, error } = parsePushedRefs(pushed);
+  if (error !== null) {
+    return null; // the caller cannot be sure what is being pushed; the suite runs
+  }
+  const verdict = await classifyPush(root, refs, { maxCommits: config.maxCommits, paths: config.paths });
+  return verdict.docsOnly ? { reason: verdict.reason } : null;
+}
+
 /**
  * @param {string} event 'pre-commit' | 'pre-push'
  * @param {object} ctx
  * @param {string} ctx.root
  * @param {object} ctx.manifest parsed simt-dev.json, or null
+ * @param {string} [ctx.pushed] the ref list git feeds pre-push on stdin; undefined when no
+ *   push is being classified (every other event, a manual run with no stdin)
  * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
  */
-export async function runGates(event, { root, manifest }) {
+export async function runGates(event, { root, manifest, pushed }) {
   const key = DEFAULT_EVENTS[event];
   if (key === undefined) {
     return { event, gates: [], failed: true, error: `unknown hook event ${event}` };
@@ -84,7 +253,89 @@ export async function runGates(event, { root, manifest }) {
     };
   }
 
+  // A pre-push gate runs against the COMMITTED tree, not the working one. Uncommitted
+  // work must not block the push of previous commits: a gate that fails on WIP the
+  // author has not committed is blocking a push it does not own. The worktree is
+  // disposable and shares the repository's object store, so `git worktree add` is cheap
+  // and needs no clone. The ledger and the version pin stay at the real root - the
+  // evidence is about this repository, not the throwaway checkout.
+  let runRoot = root;
+  let headWorktree = null;
+  let skipTest = null;
+  if (event === 'pre-push') {
+    // Decided before the worktree exists: a push that carries only documentation
+    // skips the `test` gate (ADR-113), and a push that earns the skip needs no
+    // tree for a gate that will not run.
+    skipTest = await resolveDocsOnlySkip(root, manifest, pushed);
+    if (skipTest === null) {
+      const materialized = await materializeHeadWorktree(root);
+      if (materialized.path === null) {
+        return {
+          event,
+          gates: [
+            {
+              name: 'head',
+              status: 'failed',
+              detail: materialized.error,
+              remedy: 'commit the work, or resolve the git state so HEAD is a valid reference, then push again',
+              adr: null,
+            },
+          ],
+          failed: true,
+        };
+      }
+      runRoot = materialized.path;
+      headWorktree = materialized.path;
+    }
+  }
+
+  try {
+    return await runGatesAt(event, { root: runRoot, ledgerRoot: root, manifest, declared, key, skipTest });
+  } finally {
+    if (headWorktree !== null) await removeHeadWorktree(root, headWorktree);
+  }
+}
+
+/**
+ * Run the declared gates at `root`, recording evidence at `ledgerRoot`.
+ *
+ * For a pre-push run the two differ: the gates execute in a throwaway worktree at
+ * HEAD so uncommitted work cannot block the push, while the ledger line belongs to
+ * the repository the author is standing in. For every other event they are the same
+ * path, which is why this is one function with two names for the root rather than
+ * two functions.
+ *
+ * @param {string} event
+ * @param {object} ctx
+ * @param {string} ctx.root the tree the gates execute in
+ * @param {string} ctx.ledgerRoot the repository the evidence is recorded in
+ * @param {object} ctx.manifest
+ * @param {string[]} ctx.declared the gate names for this event
+ * @param {string} ctx.key the manifest key for this event
+ * @param {{reason: string} | null} [ctx.skipTest] set when a docs-only push skips the
+ *   `test` gate (ADR-113); the reason is what the report prints in its place
+ * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
+ */
+async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, skipTest = null }) {
   const pkg = await readPkg(root);
+  // Q31: the runner is committed evidence (lockfile, then `packageManager`),
+  // resolved once per hook run so every script gate spawns the same manager.
+  let runner = null;
+  if (pkg) {
+    const lockfiles = [];
+    for (const file of ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'package-lock.json']) {
+      try {
+        await stat(join(root, file));
+        lockfiles.push(file);
+      } catch {
+        // Absent is the normal case.
+      }
+    }
+    runner = resolveNodeRunner({
+      lockfiles,
+      packageManager: typeof pkg.packageManager === 'string' ? pkg.packageManager : null,
+    }).id;
+  }
   const staged = event === 'pre-commit' ? await stagedFiles(root) : [];
   const unstaged = event === 'pre-commit' ? await unstagedFiles(root) : new Set();
   const commands = manifest?.gates?.commands;
@@ -111,7 +362,15 @@ export async function runGates(event, { root, manifest }) {
       continue;
     }
 
-    const resolution = await resolveGate(gate, { root, pkg, staged, commands });
+    // The one gate a docs-only push does not run (ADR-113). It is reported, not
+    // dropped: a skip without a printed reason would let "passed" mean "the suite
+    // never ran", which is the exact confusion the report exists to prevent.
+    if (skipTest !== null && name === 'test') {
+      results.push({ name, status: 'skipped', detail: `docs-only push: ${skipTest.reason}`, adr: 'ADR-113', exitCode: null });
+      continue;
+    }
+
+    const resolution = await resolveGate(gate, { root, pkg, staged, commands, runner });
     if (!resolution.ok) {
       results.push({
         name,
@@ -130,13 +389,17 @@ export async function runGates(event, { root, manifest }) {
     // declared command for this name takes the shell path below instead.
     if (resolution.builtin !== undefined) {
       const startedBuiltin = Date.now();
-      const outcome = await runBuiltinGate(resolution.builtin, { root, staged });
+      // The manifest's per-builtin options, where a builtin has any: the secret
+      // scan takes its ignore globs from gates.secretScan (review 0003 Q24).
+      const outcome = await runBuiltinGate(resolution.builtin, { root, staged, options: manifest?.gates?.secretScan });
       try {
-        await recordRun(root, {
+        await recordRun(ledgerRoot, {
           cmd: `builtin:${resolution.builtin}`,
           exit: outcome.ok ? 0 : 1,
           ms: Date.now() - startedBuiltin,
           output: outcome.output,
+          gate: name,
+          kind: 'builtin',
         });
       } catch {
         // Recorded by absence: the next evidence read for this tree has no line.
@@ -219,11 +482,18 @@ export async function runGates(event, { root, manifest }) {
     // claim check then finds nothing, which is the direction that cannot invent a run.
     try {
       const cmd = typeof resolution.command === 'string' ? resolution.command : resolution.argv.join(' ');
-      await recordRun(root, {
+      // The evidence claim needs the gate and its kind: a passing secret-scan is
+      // not a passing test run (review 0003 Q18). Coverage proves tests; anything
+      // else keeps its own kind or the gate name.
+      const kind =
+        name === 'test' || name === 'coverage' ? 'test' : name === 'lint' ? 'lint' : name === 'format' ? 'format' : (gate.kind ?? name);
+      await recordRun(ledgerRoot, {
         cmd,
         exit: outcome.code,
         ms: Date.now() - started,
         output: `${outcome.stdout ?? ''}\n${outcome.stderr ?? ''}`,
+        gate: name,
+        kind,
       });
     } catch {
       // Recorded by absence: the next evidence read for this tree has no line.
@@ -273,6 +543,54 @@ export async function runGates(event, { root, manifest }) {
   return { event, gates: results, failed: results.some((r) => r.status === 'failed') };
 }
 
+/**
+ * Materialize a detached worktree at HEAD so the pre-push gates run against the
+ * committed tree, not the working one. The worktree shares the repository's object
+ * store, so `git worktree add` is cheap and needs no clone. `node_modules` is
+ * symlinked in when the real root has one, because a script gate resolves its runner
+ * and binaries from there and a fresh worktree does not carry it.
+ *
+ * Fails closed: an unborn HEAD (no commits) or a git error returns `{ path: null }`
+ * with the reason, and the caller turns that into a gate failure rather than running
+ * against a tree it cannot name.
+ *
+ * @param {string} root the real repository root
+ * @returns {Promise<{path: string, error?: never}|{path: null, error: string}>}
+ */
+async function materializeHeadWorktree(root) {
+  const path = await mkdtemp(join(tmpdir(), 'head-gate-'));
+  try {
+    await exec('git', ['worktree', 'add', '--detach', path, 'HEAD'], { cwd: root });
+  } catch (error) {
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+    return { path: null, error: `git worktree add failed: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  const nodeModules = join(root, 'node_modules');
+  try {
+    await symlink(nodeModules, join(path, 'node_modules'));
+  } catch {
+    // Absent node_modules is the normal case for a repo with no install step; a
+    // dangling link is harmless, and `npm run` does not need it to exist.
+  }
+  return { path };
+}
+
+/**
+ * Remove a pre-push worktree. `--force` because a gate may have left it dirty (a
+ * formatter, a test that writes fixtures); the worktree is disposable, the real tree
+ * is not. Falls back to `rm -rf` plus a prune when git cannot remove it (a lock, a
+ * path in a state git does not expect), so a cleanup failure never leaks the tree.
+ *
+ * @param {string} root the real repository root
+ * @param {string} path the worktree to remove
+ */
+async function removeHeadWorktree(root, path) {
+  await exec('git', ['worktree', 'remove', '--force', path], { cwd: root }).catch(async () => {
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+    await exec('git', ['worktree', 'prune'], { cwd: root }).catch(() => {});
+  });
+}
+
 /**
  * The lines that report one event's gate run: the event, what was declared, every
  * gate with its disposition, its reason and its remedy, and the verdict.
@@ -298,9 +616,9 @@ export function renderGateReport(event, declared, result) {
   return lines;
 }
 
-async function run(argv, cwd) {
+async function run(argv, cwd, env) {
   try {
-    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, maxBuffer: 8 * 1024 * 1024 });
+    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, env, maxBuffer: 8 * 1024 * 1024 });
     return { code: 0, stdout, stderr };
   } catch (error) {
     return { code: typeof error.code === 'number' ? error.code : 1, stdout: error.stdout ?? '', stderr: error.stderr ?? String(error.message ?? error) };
@@ -320,7 +638,7 @@ const BUILTIN_REPORT_MAX = 12;
  * none of them can degrade into a pass, which is the same fail-closed contract
  * an unresolvable script gate has.
  */
-async function runBuiltinGate(name, { root, staged }) {
+async function runBuiltinGate(name, { root, staged, options }) {
   const scan = BUILTIN_GATES.get(name);
   if (scan === undefined) {
     return {
@@ -333,7 +651,7 @@ async function runBuiltinGate(name, { root, staged }) {
   if (staged.length === 0) {
     return { ok: true, detail: 'nothing staged; no added line to scan', output: '' };
   }
-  const result = await scan(root);
+  const result = await scan(root, options ?? {});
   if (result.error !== null) {
     return {
       ok: false,
@@ -376,9 +694,13 @@ async function runBuiltinGate(name, { root, staged }) {
  * rather than a flag on `run`.
  */
 async function runGate(resolution, cwd) {
+  // The push override is for the push itself, not for the gates the hook runs.
+  // A test that asserts a push is denied sees the override and fails.
+  const env = { ...process.env };
+  delete env.SIMT_ALLOW;
   if (resolution.shell === true && typeof resolution.command === 'string') {
     try {
-      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, maxBuffer: 8 * 1024 * 1024 });
+      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, env, maxBuffer: 8 * 1024 * 1024 });
       return { code: 0, stdout, stderr };
     } catch (error) {
       return {
@@ -388,7 +710,7 @@ async function runGate(resolution, cwd) {
       };
     }
   }
-  return run(resolution.argv, cwd);
+  return run(resolution.argv, cwd, env);
 }
 
 async function readPkg(root) {

package/src/hooks/resolve.mjs

@@ -68,7 +68,7 @@ export function hasScript(pkg, script) {
  * @returns {Promise<{ok: true, argv: string[], kind: string, detail: string}
  *                  | {ok: false, gate: string, kind: string, reason: string, remedy: string}>}
  */
-export async function resolveGate(gate, { root, pkg, staged, commands }) {
+export async function resolveGate(gate, { root, pkg, staged, commands, runner = null }) {
   const name = gate.name;
   const declared = commands?.[name];
 
@@ -172,11 +172,17 @@ export async function resolveGate(gate, { root, pkg, staged, commands }) {
         remedy: `add "${script}" to scripts, or remove "${name}" from ${MANIFEST_FILE} gates`,
       };
     }
+    // Q31: script gates run through the repo's own manager — `pnpm run`, not
+    // `npm run`, in a pnpm checkout. The default stays npm for callers that do
+    // not report one (older capabilities, hand-built contexts).
+    const { runScriptArgv, runScript } = await import('../ecosystem/node-runner.mjs');
+    const manager = runner ?? pkg?.packageManager?.split('@')?.[0] ?? 'npm';
+    const known = ['npm', 'pnpm', 'yarn', 'bun'].includes(manager) ? manager : 'npm';
     return {
       ok: true,
       kind: gate.kind,
-      argv: ['npm', 'run', '--silent', script],
-      detail: `npm run ${script}`,
+      argv: runScriptArgv(known, script),
+      detail: runScript(known, script),
     };
   }
 

package/src/hooks/shim.mjs

@@ -48,14 +48,17 @@ export function fileFor(event) {
 
 /**
  * @param {string} event one of EVENTS
- * @param {{npm?: boolean, version?: string}} [opts]
+ * @param {{npm?: boolean, manager?: string|null, version?: string}} [opts]
  *   `npm` is whether the repository has a package.json: it decides the remedy's install
  *   (a devDependency where one exists, the release binary into the repository where
- *   there is no node_modules to pin in). `version` defaults to the running package's own version,
- *   so a shim generated by 0.2.0 names 0.2.0 in its remedy and CI install.
+ *   there is no node_modules to pin in). `manager` names the Node manager when one
+ *   was resolved (Q31: `pnpm add -D`, not `npm i -D`, in a pnpm checkout); it wins
+ *   over the legacy `npm` boolean so old callers keep their bytes. `version`
+ *   defaults to the running package's own version, so a shim generated by 0.2.0
+ *   names 0.2.0 in its remedy and CI install.
  * @returns {string} POSIX sh source, LF-terminated, executable
  */
-export function renderShim(event, { npm = true, version } = {}) {
+export function renderShim(event, { npm = true, manager = null, version } = {}) {
   if (!EVENTS.includes(event)) {
     throw new Error(`unknown hook event ${event}; known: ${EVENTS.join(', ')}`);
   }
@@ -65,7 +68,8 @@ export function renderShim(event, { npm = true, version } = {}) {
   // installs it there; one without (Gradle, Connect IQ) has no node_modules to pin in,
   // so the remedy downloads the release binary into the repository - the same pinned
   // bytes CI gets, and one that needs no npm and no node on the machine (ADR-098).
-  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v);
+  const addDev = { npm: `npm i -D ${PACKAGE_NAME}@${v}`, pnpm: `pnpm add -D ${PACKAGE_NAME}@${v}`, yarn: `yarn add -D ${PACKAGE_NAME}@${v}`, bun: `bun add -d ${PACKAGE_NAME}@${v}` }[manager ?? (npm ? 'npm' : '')];
+  const install = addDev ?? (npm && !manager ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v));
   const D = '$';
   return `#!/bin/sh
 ${SHIM_MARKER}
@@ -103,11 +107,12 @@ ${renderLocator(`hooks run ${event} --root "${D}ROOT"`, {
  * @param {{npm?: boolean, version?: string}} [opts]
  * @returns {string} POSIX sh source, LF-terminated
  */
-export function renderEvidenceShim({ npm = true, version } = {}) {
+export function renderEvidenceShim({ npm = true, manager = null, version } = {}) {
   const v = version ?? packageVersion();
   // The same split as renderShim: a devDependency where one exists, the release
   // binary into the repository where there is no node_modules to pin in.
-  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v);
+  const addDev = { npm: `npm i -D ${PACKAGE_NAME}@${v}`, pnpm: `pnpm add -D ${PACKAGE_NAME}@${v}`, yarn: `yarn add -D ${PACKAGE_NAME}@${v}`, bun: `bun add -d ${PACKAGE_NAME}@${v}` }[manager ?? (npm ? 'npm' : '')];
+  const install = addDev ?? (npm && !manager ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v));
   const D = '$';
   return `#!/bin/sh
 ${SHIM_MARKER}

package/src/identity.mjs

@@ -25,10 +25,12 @@
 // tracked file is not something an adopting command should do silently.
 
 import { execFile } from 'node:child_process';
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 
+import { journaledGitConfig, journaledWriteFile } from './journal.mjs';
+
 const exec = promisify(execFile);
 
 /** The file, at the repository root. Named for what it is: a git config fragment. */
@@ -166,13 +168,67 @@ export async function includesOwnIdentity(root) {
  * break. Two of the repositories here had exactly that, and both worked only because
  * the sibling checkout happened to exist at the expected relative path.
  *
+ * A caller-supplied journal records the key so `undo` restores the routing (R49);
+ * without one the write stays unrecorded, as `commitJournal` needs it (review 0003
+ * Q30). The journaled path sets through `journaledGitConfig`, which records one
+ * key's before and after - the single-value case, and the only shape this tool
+ * writes.
+ *
  * @param {string} root
+ * @param {Array} [journal]
  * @returns {Promise<void>}
  */
-export async function includeOwnIdentity(root) {
+export async function includeOwnIdentity(root, journal = null) {
+  // A directory that is not a git work tree has no config to route. The lenient
+  // `git()` used to swallow the failure here, and an adoption of a plain directory
+  // must keep working: there is simply nothing to point at.
+  if ((await git(root, ['rev-parse', '--is-inside-work-tree'])) !== 'true') return;
+  if (journal) {
+    await journaledGitConfig(root, journal, INCLUDE_KEY, `../${IDENTITY_FILE}`);
+    return;
+  }
   await git(root, ['config', '--local', '--replace-all', INCLUDE_KEY, `../${IDENTITY_FILE}`]);
 }
 
+/**
+ * Whether .gitignore already names the identity file. The plan needs the answer
+ * before anything is written: a line the run does not print is a write the reader
+ * approves from the diff afterwards (review 0003 Q30).
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>}
+ */
+export async function identityIgnored(root) {
+  let text;
+  try {
+    text = await readFile(join(root, '.gitignore'), 'utf8');
+  } catch {
+    return false;
+  }
+  return text.split('\n').map((l) => l.trim()).includes(IDENTITY_FILE);
+}
+
+/**
+ * The .gitignore bytes with the identity entry appended, or null when it is
+ * already there. One owner for the edit's shape: `ignoreIdentity` writes it and
+ * `init --diff` previews it, so the two cannot disagree about the bytes (review
+ * 0003 Q30).
+ *
+ * @param {string} text the current bytes, '' when the file is absent
+ * @returns {string|null}
+ */
+export function gitignoreWithIdentity(text) {
+  if (text.split('\n').map((l) => l.trim()).includes(IDENTITY_FILE)) return null;
+  const prefix = text === '' || text.endsWith('\n') ? '' : '\n';
+  return (
+    `${text}${prefix}\n` +
+    '# Per-developer git identity, written by `simt init`. Not a file to share:\n' +
+    '# it carries whoever is committing into the tree, and a repository has more than\n' +
+    '# one of those.\n' +
+    `${IDENTITY_FILE}\n`
+  );
+}
+
 /**
  * Add the identity file to .gitignore, if it is not already there.
  *
@@ -181,10 +237,14 @@ export async function includeOwnIdentity(root) {
  * it means nothing, and appending a duplicate of an entry that is already present
  * is how a file ends up listed twice.
  *
+ * A caller-supplied journal records the edit so `undo` restores it (R49); without
+ * one the write stays unrecorded, as `commitJournal` needs it (review 0003 Q30).
+ *
  * @param {string} root
+ * @param {Array} [journal]
  * @returns {Promise<boolean>} whether the file was changed
  */
-export async function ignoreIdentity(root) {
+export async function ignoreIdentity(root, journal = null) {
   const path = join(root, '.gitignore');
   let text;
   try {
@@ -192,16 +252,9 @@ export async function ignoreIdentity(root) {
   } catch {
     text = '';
   }
-  const already = text.split('\n').map((l) => l.trim()).includes(IDENTITY_FILE);
-  if (already) return false;
-  const prefix = text === '' || text.endsWith('\n') ? '' : '\n';
-  const block =
-    `${prefix}\n` +
-    '# Per-developer git identity, written by `simt init`. Not a file to share:\n' +
-    '# it carries whoever is committing into the tree, and a repository has more than\n' +
-    '# one of those.\n' +
-    `${IDENTITY_FILE}\n`;
-  const { writeFile } = await import('node:fs/promises');
-  await writeFile(path, text + block);
+  const next = gitignoreWithIdentity(text);
+  if (next === null) return false;
+  if (journal) await journaledWriteFile(root, journal, path, next);
+  else await writeFile(path, next);
   return true;
 }