simt-dev 0.6.0 → 0.6.3

package/src/commands/sync.mjs

@@ -16,18 +16,21 @@
 //     three `.mdc` rules would let a reader believe a repo is fully current when
 //     only the file they happened to open is.
 
-import { mkdir, readFile, stat, symlink, unlink, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat, symlink, unlink } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { plan, checkTargets, checkTarget, provenanceDigest, loadRules, select, pointerTargets, pointerState } from '../projection/project.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { manifestDrift, readManifest, unrunnableGates, buildManifest, writeManifest, withGenerated, manifestText } from '../projection/manifest.mjs';
+import { manifestDrift, readManifest, unrunnableGates, buildManifest, writeManifest, withGenerated, manifestText, manifestPath } from '../projection/manifest.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { readCapability } from '../hooks/capability.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
 import { assertVersionPin, packageVersion } from '../package-version.mjs';
 import { resolvePacks } from '../packs.mjs';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { buildCacheRecord, hooksSummary, invalidateCheckCache, writeCheckCache } from '../status.mjs';
 import { computeLock, readLock, LOCK_FILE } from '../projection/lock.mjs';
 import { runDeclaredChecks } from '../kernel/checks.mjs';
 import { DECISIONS_DIR } from '../decisions/index.mjs';
@@ -249,6 +252,29 @@ export async function syncCommand(positional, flags) {
   }
   const manifestChanged = manifestPlan !== null;
 
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50). Pointers carry no bytes, so the
+  // plan line naming the link target is already the whole story for them.
+  const diffs =
+    flags.diff === true
+      ? await Promise.all([
+        ...changed.map(async (t) => ({
+          path: t.file,
+          before: await readBefore(t.path),
+          after: t.text,
+        })),
+        ...(manifestPlan === null
+          ? []
+          : [
+              {
+                path: manifestPlan.file,
+                before: await readBefore(await manifestPath(root)),
+                after: manifestPlan.text,
+              },
+            ]),
+      ])
+      : [];
+
   // Writes happen BEFORE output in every mode. An earlier build emitted `--json`
   // first and returned, so `upgrade --yes --json` reported a plan and changed
   // nothing — the exact combination automation reaches for.
@@ -265,11 +291,14 @@ export async function syncCommand(positional, flags) {
   // A comment that enumerates which commands follow a rule is a claim about code
   // this file does not own, and it was one commit out of date before anyone ran it.
   if (mode.apply) {
+    // Every repo-file write below is journaled, so `undo` can restore this run
+    // (R49). Pointer symlinks carry no bytes and are not journaled.
+    const journal = [];
     // The manifest first, with the rest: a gate that refuses on a stale stamp should
     // not be able to read a half-finished write, and the manifest is the file every
     // other write in this run is described by.
     if (manifestPlan) {
-      await writeManifest(root, manifestPlan.manifest);
+      await writeManifest(root, manifestPlan.manifest, journal);
       note(`wrote    ${manifestPlan.file} (generated field(s) ${manifestPlan.stale.join(', ')})`);
     }
     for (const t of changed) {
@@ -280,7 +309,7 @@ export async function syncCommand(positional, flags) {
       // derived from the target, never from the surface table, so a future surface with a
       // deeper path needs no change here.
       await mkdir(dirname(t.path), { recursive: true });
-      await writeFile(t.path, t.text);
+      await journaledWriteFile(root, journal, t.path, t.text);
       note(`wrote    ${t.file}`);
     }
     const lock = await computeLock(root, flags);
@@ -292,9 +321,16 @@ export async function syncCommand(positional, flags) {
       if (error.code !== 'ENOENT') throw error;
     }
     if (previousLock !== lockText) {
-      await writeFile(join(root, LOCK_FILE), lockText);
+      await journaledWriteFile(root, journal, join(root, LOCK_FILE), lockText);
       note(`wrote    ${LOCK_FILE}`);
     }
+    await commitJournal(root, 'sync', journal);
+    // The regions moved, so the last `check` no longer describes this tree.
+    // Invalidated rather than refreshed: `sync` does not run gates, checkers
+    // or decisions lint, so it cannot know what the gate would now say (R48).
+    // Gated on the journal: a no-op apply changed nothing, and the record is
+    // still true.
+    if (journal.length > 0) await invalidateCheckCache(root);
     for (const p of pointerPlan) {
       await mkdir(dirname(p.path), { recursive: true });
       // Only a symlink this tool wrote is replaced, and only because it has no content:
@@ -328,6 +364,7 @@ export async function syncCommand(positional, flags) {
         pointers: pointersAdded,
         written: mode.apply ? changed.length + pointersAdded.length + (manifestChanged ? 1 : 0) : 0,
         dryRun: !mode.apply,
+        ...diffField(diffs, flags),
       },
       {},
     );
@@ -360,6 +397,8 @@ export async function syncCommand(positional, flags) {
       );
     }
     emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
   }
 
   const idle = changed.length === 0 && pointerPlan.length === 0 && !manifestChanged;
@@ -387,7 +426,15 @@ export async function syncCommand(positional, flags) {
  * @returns {Promise<{file: string, manifest: object, text: string,
  *                    stale: string[], previousBytes: number}|null>}
  */
-async function planManifestRepair(root, stack, sha) {
+/**
+ * The manifest-only repair `sync` applies before rewriting regions (plan 0003 R47).
+ *
+ * Exported so `doctor --fix` applies exactly this repair instead of deriving its
+ * own: the generated fields have one author, and a fix that patched them any
+ * other way would be a second answer to what "current" means. Returns null when
+ * there is nothing to repair, under exactly the conditions `sync` writes under.
+ */
+export async function planManifestRepair(root, stack, sha) {
   const drift = await manifestDrift(root, stack, sha);
   if (drift === null) return null;
   // A `reformatted` manifest is repaired only once the repository has declared that no
@@ -477,8 +524,14 @@ async function gateCwdFindings(root, manifest) {
   return findings;
 }
 
-export async function checkCommand(positional, flags) {  const root = flags.root ?? positional[0] ?? process.cwd();
-  const findings = await checkTargets(root, flags);
+// --- core: the gate both the CLI and the MCP `check` tool answer from (Q15) ----
+//
+// The MCP tool rebuilt a smaller gate from `checkTargets` alone: no manifest,
+// no gates, no pin, no lock, no declared checkers — 3 findings where the command
+// reports 77. The command below renders these facts for terminals; the tool
+// returns them as JSON. The CLI keeps its field names; the tool adopts them.
+export async function checkRepo(root, opts = {}) {
+  const findings = await checkTargets(root, opts);
   const rules = await loadRules(root);
 
   // A rule file with no id would be projected without a traceable source, so it
@@ -494,10 +547,21 @@ export async function checkCommand(positional, flags) {  const root = flags.root
     }
   }
 
+  // The rules slot of the `--line` cache, captured before anything else pushes:
+  // regions and rule sources are the projection, and a new blocking status
+  // that arrives here defaults to red rather than needing a second edit.
+  const rulesOk = !findings.some((f) => f.status !== 'current' && !CHECK_NON_BLOCKING.has(f.status));
+
   // A declared gate this repo cannot run fails closed on every commit once hooks are
   // installed. Reported here rather than left to `hooks status`, so the repo is red
   // before anyone installs anything rather than after.
-  const { manifest } = await readManifest(root);
+  const { manifest, exists } = await readManifest(root);
+  // The gates slot, counted — not just reported — so the line can print run/total.
+  // A cwd finding names a declared gate that will not run, so it counts with the
+  // unrunnable; an unknown-gate-cwd names no declared gate, so it does not.
+  let gatesRun = 0;
+  let gatesTotal = 0;
+  let hooksOk = true;
   if (manifest) {
     // The gate runs from whatever binary resolved it. For a repository without npm that
     // is the release binary in `.simt/bin` (ADR-098), and the only thing that knows
@@ -507,8 +571,15 @@ export async function checkCommand(positional, flags) {  const root = flags.root
     if (mismatch) {
       findings.push({ file: MANIFEST_FILE, status: 'version-mismatch', detail: mismatch, remedy: `run: ${CLI} upgrade --yes` });
     }
-    findings.push(...unrunnableGates(manifest, await readCapability(root)));
-    findings.push(...(await gateCwdFindings(root, manifest)));
+    const unrunnable = unrunnableGates(manifest, await readCapability(root));
+    findings.push(...unrunnable);
+    const cwdFindings = await gateCwdFindings(root, manifest);
+    findings.push(...cwdFindings);
+    gatesTotal = (manifest.gates?.preCommit ?? []).length + (manifest.gates?.prePush ?? []).length;
+    const notRun =
+      unrunnable.filter((f) => f.status === 'unrunnable').length + cwdFindings.length;
+    gatesRun = Math.max(0, gatesTotal - notRun);
+    hooksOk = (await hooksSummary(root, manifest, exists)).ok;
     // A pack the repository declares but cannot produce is reported here rather
     // than when a rule happens to be missing, because that is the failure mode
     // this guards: the region still renders, it renders SHORT, and `check` would
@@ -523,7 +594,7 @@ export async function checkCommand(positional, flags) {  const root = flags.root
     const drift = await manifestDrift(root, stack, await provenanceDigest());
     if (drift) findings.push(drift);
   }
-  if (flags.frozen) findings.push(...(await frozenFindings(root, flags)));
+  if (opts.frozen) findings.push(...(await frozenFindings(root, opts)));
   // The checkers a selected rule declared (ADR-088). They read the rule source,
   // not the folded region, so a line that left the prompt is still the line that runs.
   const fp = await fingerprint(root);
@@ -547,16 +618,40 @@ export async function checkCommand(positional, flags) {  const root = flags.root
   // acts on, so a finding it reports and does not fail on is a decision recorded in a
   // set — not one inherited from the writer that shares this file (ADR-051).
   const bad = findings.filter((f) => f.status !== 'current' && !CHECK_NON_BLOCKING.has(f.status));
+  // The `--line` cache is local state, not a write: counts and booleans under
+  // `.simt/`, never repo content, the same standing as the ledger and the
+  // index. Written on every run — red state is state — so a prompt never
+  // reports the tree as it was two checks ago.
+  await writeCheckCache(
+    root,
+    await buildCacheRecord(root, {
+      rulesOk,
+      hooksOk,
+      gatesRun,
+      gatesTotal,
+      blocking: bad.length,
+      warnings: findings.filter((f) => CHECK_NON_BLOCKING.has(f.status)).length,
+    }),
+  );
+  return { ok: bad.length === 0, findings };
+}
+
+export async function checkCommand(positional, flags) {
+  const root = flags.root ?? positional[0] ?? process.cwd();
+  const { ok, findings } = await checkRepo(root, flags);
   const payload = {
-    ok: bad.length === 0,
+    ok,
     command: 'check',
     root,
     findings,
+    // Uniform with every writer's `--json --diff`: the gate carries no file
+    // plan, so its diff is always empty — pinned, not excused (R50).
+    ...diffField([], flags),
   };
 
   if (isJson(flags)) {
     emitJson(payload, {});
-    return bad.length === 0 ? EXIT.OK : EXIT.FAIL;
+    return ok ? EXIT.OK : EXIT.FAIL;
   }
 
   // Every finding that carries a remedy prints it. A finding with a fix the reader
@@ -570,7 +665,7 @@ export async function checkCommand(positional, flags) {  const root = flags.root
       .join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );
-  return bad.length === 0 ? EXIT.OK : EXIT.FAIL;
+  return ok ? EXIT.OK : EXIT.FAIL;
 }
 
 /**

package/src/commands/undo.mjs

@@ -0,0 +1,106 @@
+// `simt undo [--yes] [--json]`
+//
+// Restore the last journaled set of writes (plan 0003 R49): every file the last
+// writing run changed goes back to its pre-run bytes, and files the run created
+// are deleted. A run that wrote nothing leaves no set, so there is nothing to
+// restore and the command says so.
+//
+// The safety is the journal's, not the flag's: when any file in the set no
+// longer matches the bytes the run left, the whole undo is refused — restoring
+// the rest around a hand edit would silently merge two authors' intentions.
+// Like every other writer this command previews without `--yes`.
+
+import { EXIT, emit, emitJson, isJson, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { listJournalSets, readJournalSet, undoLastJournalSet } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { join } from 'node:path';
+import { invalidateCheckCache } from '../status.mjs';
+
+export async function undoCommand(positional, flags) {
+  const root = flags.root ?? positional[0] ?? process.cwd();
+  const mode = writeMode(flags);
+
+  const [id] = await listJournalSets(root);
+  if (!id) {
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'undo', root, set: null, restored: [], dryRun: !mode.apply });
+      return EXIT.OK;
+    }
+    emit('nothing to undo: no journaled writes', { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  const set = await readJournalSet(root, id);
+  const paths = set.entries.map((e) => e.path);
+  // The `--diff` pairs: what the tree holds now against what the restore
+  // would put back. A null beforeBytes is a file the run created, so the
+  // restore deletes it — the after side is empty (R50).
+  const diffs =
+    flags.diff === true
+      ? await Promise.all(
+        set.entries.map(async (e) => ({
+          path: e.path,
+          before: await readBefore(join(root, e.path)),
+          after: e.beforeBytes ?? null,
+        })),
+      )
+      : [];
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'undo', root, set: id, restores: paths, dryRun: true, ...diffField(diffs, flags) });
+      return EXIT.OK;
+    }
+    emit(
+      [`last write  ${set.command} (${id})`, ...paths.map((p) => `restore   ${p}`), '', `would restore ${paths.length} file(s); apply with: ${CLI} undo --yes`].join(
+        '\n',
+      ),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
+    return EXIT.OK;
+  }
+
+  const result = await undoLastJournalSet(root);
+  if (result.empty) {
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'undo', root, set: null, restored: [] });
+      return EXIT.OK;
+    }
+    emit('nothing to undo: no journaled writes', { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  if (result.refused) {
+    if (isJson(flags)) {
+      emitJson({ ok: false, command: 'undo', root, set: result.set, refused: result.refused, restored: [] });
+      return EXIT.FAIL;
+    }
+    emit(
+      [
+        `refused   ${result.set}`,
+        `touched   ${result.refused.path}  ${result.refused.detail}`,
+        '',
+        'nothing was restored; re-run the writing command or merge by hand, then undo again',
+      ].join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.FAIL;
+  }
+  // The tree is back to before the run, so a `check` from after the run no
+  // longer describes it — the line goes back to "no cache" (R48). A restored
+  // set always restored something, so there is nothing to gate on.
+  await invalidateCheckCache(root);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'undo', root, set: result.set, restored: result.restored, ...diffField(diffs, flags) });
+    return EXIT.OK;
+  }
+  emit(
+    [`undone    ${result.set}`, ...result.restored.map((p) => `restored  ${p}`)].join('\n'),
+    { maxBytes: flags.maxBytes ?? 0 },
+  );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
+  return EXIT.OK;
+}

package/src/commands/upgrade.mjs

@@ -22,13 +22,16 @@
 //      silently behind is the failure `compare` exists to surface, and this command must
 //      not be the thing that creates it.
 
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { invalidateCheckCache } from '../status.mjs';
 
 import { basename, dirname, resolve } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { provenanceDigest, plan } from '../projection/project.mjs';
-import { MANIFEST, MANIFEST_COMMENT, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { MANIFEST, MANIFEST_COMMENT, manifestPath, manifestText, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { FAULT_STATES, planUpgrade, summariseUpgrade } from '../upgrade/plan.mjs';
 import { discover } from '../compare/discover.mjs';
 import { resolveWorkspace, targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
@@ -69,13 +72,57 @@ export async function upgradeCommand(positional, flags) {
   const sha = await provenanceDigest();
   const mode = writeMode(flags);
   const plans = [];
+  // The plan inputs, kept because the diff is built from them: `planUpgrade`
+  // keeps the verdict, not the bytes, and the apply path below re-plans per
+  // repo rather than reusing this loop's targets.
+  const inputs = new Map();
   for (const repo of found.repos) {
     const { manifest, exists, error } = await readManifest(repo);
     const result = await plan(repo);
+    inputs.set(repo, { targets: result.targets, manifest });
     plans.push(planUpgrade({ name: basename(repo), path: repo, manifest, manifestExists: exists, manifestError: error, targets: result.targets, sha }));
   }
   const summary = summariseUpgrade(plans);
 
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50). Labels carry the repo name: one
+  // run diffs N repositories, and a bare filename would not say which. The
+  // manifest after-bytes are built the same way the apply path builds them —
+  // chosen keys kept, `$comment` refreshed, pin moved — so the diff shows the
+  // write rather than a second opinion about it.
+  const diffs =
+    flags.diff === true
+      ? (
+          await Promise.all(
+            plans
+              .filter((p) => p.action === 'updated')
+              .map(async (p) => {
+                const input = inputs.get(p.path) ?? { targets: [], manifest: null };
+                const pairs = await Promise.all(
+                  input.targets
+                    .filter((t) => t.action !== 'unchanged' && t.action !== 'malformed')
+                    .map(async (t) => ({
+                      path: `${p.name}/${t.file}`,
+                      before: await readBefore(t.path),
+                      after: t.text,
+                    })),
+                );
+                const { $comment, ...chosen } = input.manifest ?? {};
+                pairs.push({
+                  path: `${p.name}/${MANIFEST_FILE}`,
+                  before: await readBefore(await manifestPath(p.path)),
+                  after: manifestText({
+                    ...MANIFEST_COMMENT,
+                    ...chosen,
+                    projection: { ...(input.manifest?.projection ?? {}), simtDevSha: sha },
+                  }),
+                });
+                return pairs;
+              }),
+          )
+        ).flat()
+      : [];
+
   // Writes happen BEFORE the report, in every output mode. An earlier version emitted
   // the JSON payload and returned, which meant `--yes --json` reported a plan and
   // changed nothing - the exact combination a script uses for automation.
@@ -96,11 +143,14 @@ export async function upgradeCommand(positional, flags) {
         // Every planned target, not just AGENTS.md: a repo can have a current AGENTS.md
         // and three stale `.mdc` rules, and restamping only the first leaves `check` red
         // straight after a successful upgrade.
+        // One journal set per repo: a set belongs to one repository, and an
+        // `undo` in one consumer must never reach into another (R49).
+        const journal = [];
         const { targets } = await plan(p.path);
         for (const t of targets) {
           if (t.action === 'unchanged' || t.action === 'malformed') continue;
           await mkdir(dirname(t.path), { recursive: true });
-          await writeFile(t.path, t.text);
+          await journaledWriteFile(p.path, journal, t.path, t.text);
           writtenFiles.add(t.file);
         }
         const { manifest } = await readManifest(p.path);
@@ -110,11 +160,20 @@ export async function upgradeCommand(positional, flags) {
         // forever, because `sync` does not own the manifest and nothing else rewrites
         // it. An adopted repo would never have corrected it.
         const { $comment, ...chosen } = manifest ?? {};
-        await writeManifest(p.path, {
-          ...MANIFEST_COMMENT,
-          ...chosen,
-          projection: { ...(manifest?.projection ?? {}), simtDevSha: sha },
-        });
+        await writeManifest(
+          p.path,
+          {
+            ...MANIFEST_COMMENT,
+            ...chosen,
+            projection: { ...(manifest?.projection ?? {}), simtDevSha: sha },
+          },
+          journal,
+        );
+        await commitJournal(p.path, 'upgrade', journal);
+        // The pin and regions moved: the last `check` of this repo no longer
+        // describes it (R48). Gated on the journal: an untouched repo keeps
+        // its record.
+        if (journal.length > 0) await invalidateCheckCache(p.path);
         applied.push(p.name);
       } catch (error) {
         // Reported per repo rather than thrown: one unwritable repo must not hide the
@@ -133,6 +192,7 @@ export async function upgradeCommand(positional, flags) {
     source: target.source,
     sha,
     dryRun: !mode.apply,
+    ...diffField(diffs, flags),
     written: applied.length > 0,
     summary: { ...summary, applied, failed },
     plans,
@@ -144,6 +204,8 @@ export async function upgradeCommand(positional, flags) {
   }
 
   emit(render(plans, summary, { root, shape: found.shape, source: target.source, sha, applied, failed }));
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
 
   for (const w of found.worktrees) {
     // The same reasoning as `compare`: a worktree is its parent's HEAD elsewhere, so

package/src/completions.mjs

@@ -0,0 +1,191 @@
+// Shell completions, generated from the command registry (plan 0003 R51).
+//
+// The inputs are the two tables that already exist and are already checked:
+// `COMMANDS` — the same list the dispatcher routes and `--help` is asserted
+// against (review 0002 S15) — and the flag tables in argv.mjs. A command added
+// to `IMPLEMENTED` therefore completes in all three shells with no second
+// edit, which is exactly the property S15 demanded of `--help`.
+//
+// Deterministic by construction: every list is sorted and deduplicated before
+// it is rendered, no timestamp, no host name, no environment is read. The same
+// registry produces byte-identical output on any machine, so the generated
+// script can be committed, diffed and reviewed like any other file.
+//
+// Two boundaries, both deliberate:
+//
+//   - Positional VALUES beyond subcommand words are file completion. The
+//     registry knows words, not the skill catalogue or a path's tree, and a
+//     completion that guesses is worse than one that falls back to files.
+//   - bash's script stays 3.2-compatible: macOS ships /bin/bash 3.2, and a
+//     completion script that fails to parse there is a silent no-op.
+
+import { BOOL_FLAGS, VALUE_FLAGS } from './argv.mjs';
+
+/** The shells this command can render, sorted. */
+export const SHELLS = ['bash', 'fish', 'zsh'];
+
+/** Every flag name, sorted: `--budget`, `--root`, ... Flags are global. */
+const FLAGS = [...new Set([...BOOL_FLAGS, ...VALUE_FLAGS])].sort().map((f) => `--${f}`);
+
+/** The value-flag case pattern (`--root|--task|...`), for the prev-word check. */
+const VALUE_CASE = [...VALUE_FLAGS].sort().map((f) => `--${f}`).join('|');
+
+/**
+ * The registry as completions need it: the first words, and for each group the
+ * subcommands under it. Derived from `commands` rather than hand-listed, so a
+ * new command or subcommand arrives here without an edit.
+ *
+ * @param {string[]} commands sorted dispatchable paths, e.g. `['brief', 'skills index']`
+ * @returns {{top: string[], groups: Array<[string, string[]]>}}
+ */
+export function shape(commands) {
+  const top = new Set();
+  const subs = new Map();
+  for (const path of commands) {
+    const [first, second] = path.split(' ');
+    top.add(first);
+    if (second !== undefined) {
+      if (!subs.has(first)) subs.set(first, new Set());
+      subs.get(first).add(second);
+    }
+  }
+  return {
+    top: [...top].sort(),
+    groups: [...subs.entries()]
+      .map(([group, set]) => [group, [...set].sort()])
+      .sort((a, b) => (a[0] < b[0] ? -1 : 1)),
+  };
+}
+
+/**
+ * The completion script for one shell.
+ *
+ * @param {'bash'|'fish'|'zsh'} shell
+ * @param {string[]} commands the dispatchable command paths (`COMMANDS`)
+ * @returns {string} the script, newline-terminated
+ */
+export function renderCompletions(shell, commands) {
+  const s = shape(commands);
+  if (shell === 'bash') return renderBash(s);
+  if (shell === 'zsh') return renderZsh(s);
+  if (shell === 'fish') return renderFish(s);
+  throw new Error(`unknown shell \`${shell}\`; one of: ${SHELLS.join(', ')}`);
+}
+
+function renderBash({ top, groups }) {
+  const cases = groups
+    .map(([group, subs]) => `      ${group}) subs='${subs.join(' ')}' ;;`)
+    .join('\n');
+  return [
+    '# bash completion for simt. Generated by `simt completions bash`; do not edit.',
+    '# Install: source <(simt completions bash), or drop it in /etc/bash_completion.d/.',
+    '# bash 3.2 compatible: macOS ships /bin/bash 3.2.',
+    '_simt() {',
+    '  local cur prev subs flags top',
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
+    "  subs=''",
+    '',
+    '  # A flag that takes a value takes a word only the shell can name: paths.',
+    '  case "$prev" in',
+    '    --) return 0 ;;',
+    `    ${VALUE_CASE}) return 0 ;;`,
+    '  esac',
+    '',
+    `  flags='${FLAGS.join(' ')}'`,
+    `  top='${top.join(' ')}'`,
+    '',
+    '  case "$cur" in',
+    '    -*) COMPREPLY=( $(compgen -W "$flags" -- "$cur") ); return 0 ;;',
+    '  esac',
+    '  if [ "$COMP_CWORD" -eq 1 ]; then',
+    '    COMPREPLY=( $(compgen -W "$top" -- "$cur") )',
+    '  elif [ "$COMP_CWORD" -eq 2 ]; then',
+    '    case "${COMP_WORDS[1]}" in',
+    cases,
+    '    esac',
+    '    if [ -n "$subs" ]; then',
+    '      COMPREPLY=( $(compgen -W "$subs" -- "$cur") )',
+    '    fi',
+    '  fi',
+    '}',
+    'complete -o bashdefault -o default -F _simt simt',
+    '',
+  ].join('\n');
+}
+
+function renderZsh({ top, groups }) {
+  const cases = groups
+    .map(([group, subs]) => `    ${group}) subs=( ${subs.join(' ')} ) ;;`)
+    .join('\n');
+  return [
+    '#compdef simt',
+    '# zsh completion for simt. Generated by `simt completions zsh`; do not edit.',
+    '# Install: save as `_simt` in a directory on $fpath and run `compinit`, or',
+    '# source this after compinit: `source <(simt completions zsh)`.',
+    '_simt() {',
+    '  local cur prev',
+    '  local -a top flags subs',
+    `  top=( ${top.join(' ')} )`,
+    `  flags=( ${FLAGS.join(' ')} )`,
+    '  subs=()',
+    '',
+    '  # A flag that takes a value takes a word only the shell can name: paths.',
+    '  case "$prev" in',
+    `    --|${VALUE_CASE})`,
+    '      _files',
+    '      return',
+    '      ;;',
+    '  esac',
+    '',
+    '  if [[ "$cur" == -* ]]; then',
+    '    compadd -- ${flags}',
+    '    return',
+    '  fi',
+    '',
+    '  case "${words[2]}" in',
+    cases,
+    '  esac',
+    '',
+    '  if (( CURRENT == 2 )); then',
+    '    compadd -- ${top}',
+    '  elif (( CURRENT == 3 )) && (( ${#subs} )); then',
+    '    compadd -- ${subs}',
+    '  else',
+    '    _files',
+    '  fi',
+    '}',
+    '',
+    'if (( $+functions[compdef] )); then',
+    '  compdef _simt simt',
+    'fi',
+    '',
+  ].join('\n');
+}
+
+function renderFish({ top, groups }) {
+  const level1 = top.map(
+    (word) => `complete -c simt -n '__fish_use_subcommand' -a '${word}'`,
+  );
+  const level2 = groups.flatMap(([group, subs]) =>
+    subs.map(
+      (word) => `complete -c simt -n '__fish_seen_subcommand_from ${group}' -a '${word}'`,
+    ),
+  );
+  const flagLines = FLAGS.map((flag) => {
+    const name = flag.slice(2);
+    return VALUE_FLAGS.has(name)
+      ? `complete -c simt -l ${name} -r`
+      : `complete -c simt -l ${name}`;
+  });
+  return [
+    '# fish completion for simt. Generated by `simt completions fish`; do not edit.',
+    '# Install: simt completions fish > ~/.config/fish/completions/simt.fish',
+    ...level1,
+    '',
+    ...level2,
+    '',
+    ...flagLines,
+    '',
+  ].join('\n');
+}