simt-dev 0.6.0 → 0.6.3

package/src/argv.mjs

@@ -10,7 +10,7 @@
 // Anything unrecognised is an error, not a silent ignore: a typo'd gate name
 // that is ignored is worse than a typo'd gate name that fails.
 
-import { EXIT, fail } from './output/index.mjs';
+import { EXIT } from './output/index.mjs';
 
 // `--quiet`, `--semantic` and `--mermaid` were here and were read by nothing (review
 // 0001 filed it; it survived every change to this file since). Each was a plan's
@@ -93,6 +93,18 @@ export const BOOL_FLAGS = new Set([
   // the deterministic outline. Off by default: no model in the default path (P1),
   // and a model that is not asked for should not be opened against (ADR-090).
   'local',
+  // doctor: apply the remedies flagged safe (local, idempotent, journaled) and
+  // list the rest. Off by default because a repair, however safe, is still a
+  // write, and a command whose name is a diagnosis should not write by default.
+  'fix',
+  // status: print the one-line gate summary from the last check. Off by
+  // default because the only mode this command has is the line; bare `status`
+  // is a usage error naming it, the way `plan` without a subcommand is.
+  'line',
+  // every writer: print the plan as unified diffs. Off by default because a
+  // plan report is the compact answer and the diff is the verbose one; --diff
+  // never changes what the run writes or its exit code, only what it shows.
+  'diff',
 ]);
 
 export const VALUE_FLAGS = new Set([
@@ -138,6 +150,15 @@ export const VALUE_FLAGS = new Set([
   // plan done: the test command that proves the slice. Plan 0003 R31.
   'test',
   'state',
+  // slice finish: the Conventional Commits type for the commit it makes. A value,
+  // not a boolean, because a row title cannot say whether the slice was a feat, a
+  // fix or a chore, and deriving it from the words would be a guess no reader of
+  // the message could argue with (plan 0003 R53).
+  'type',
+  // lease: how long the claim lasts, in seconds. A value, because "a lease is short"
+  // is not a number any reader can act on, and an expiry nobody chose is an expiry
+  // nobody can plan around (plan 0003 R54, ADR-101).
+  'ttl',
   // map: outline (paths), names (exported symbols) or signatures (the line).
   // A boolean would not say which of the three the caller wanted.
   'level',
@@ -151,6 +172,10 @@ export const VALUE_FLAGS = new Set([
   // "generate a package" with no destination would have to guess, and a guess about where
   // a directory tree goes is the one failure that leaves files behind.
   'out',
+  // pr-body: the ref the body diffs against. A value, because the fork point is a
+  // name only the author's branch knows, and the default (origin/main, then main)
+  // is a guess the report states out loud rather than a question it asks.
+  'base',
 ]);
 
 /**
@@ -168,9 +193,29 @@ export const VALUE_FLAGS = new Set([
  */
 export const REPEATABLE_FLAGS = new Set(['skill', 'arm', 'compare', 'supersedes']);
 
+/**
+ * Whether a raw argv asks for JSON, read before parsing succeeds.
+ *
+ * A parse failure is still a result the caller may need as JSON (Q11), but the
+ * parsed flags do not exist yet — so the dispatcher reads the spelling straight
+ * off argv. Only the exact `--json` spelling counts, and nothing past `--` does:
+ * a positional that happens to read `--json` is a path, not a flag.
+ */
+export function rawJsonFlag(argv) {
+  for (const arg of argv) {
+    if (arg === '--') break;
+    if (arg === '--json') return true;
+    if (arg === '--no-json') return false;
+  }
+  return false;
+}
+
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
- * @returns {{ok: true, value: object} | {ok: false, code: number}}
+ * @returns {{ok: true, value: object} | {ok: false, error: {message: string, code: number}}}
+ *
+ * A failure is data, never output: reporting it is the caller's job, because only
+ * the caller knows whether `--json` was asked for (Q11). Nothing here prints.
  */
 export function parse(argv) {
   const flags = {};
@@ -196,14 +241,14 @@ export function parse(argv) {
     if (raw.startsWith('no-')) {
       const positive = raw.slice(3);
       if (!BOOL_FLAGS.has(positive)) {
-        return { ok: false, code: usage(`unknown flag --${raw}`) };
+        return { ok: false, error: usage(`unknown flag --${raw}`) };
       }
       flags[camel(positive)] = false;
       continue;
     }
     if (BOOL_FLAGS.has(raw)) {
       if (inlineValue !== undefined) {
-        return { ok: false, code: usage(`--${raw} takes no value`) };
+        return { ok: false, error: usage(`--${raw} takes no value`) };
       }
       flags[camel(raw)] = true;
       continue;
@@ -211,19 +256,19 @@ export function parse(argv) {
     if (VALUE_FLAGS.has(raw)) {
       const value = inlineValue ?? argv[i + 1];
       if (value === undefined || (inlineValue === undefined && value.startsWith('--'))) {
-        return { ok: false, code: usage(`--${raw} requires a value`) };
+        return { ok: false, error: usage(`--${raw} requires a value`) };
       }
       if (inlineValue === undefined) i += 1;
       if (raw === 'budget' || raw === 'max-bytes') {
         const n = Number(value);
         if (!Number.isInteger(n) || n < 0) {
-          return { ok: false, code: usage(`--${raw} must be a non-negative integer, received ${value}`) };
+          return { ok: false, error: usage(`--${raw} must be a non-negative integer, received ${value}`) };
         }
         flags[camel(raw)] = n;
       } else if (raw === 'reps') {
         const n = Number(value);
         if (!Number.isInteger(n) || n < 1) {
-          return { ok: false, code: usage(`--reps must be a positive integer, received ${value}`) };
+          return { ok: false, error: usage(`--reps must be a positive integer, received ${value}`) };
         }
         flags.reps = n;
       } else {
@@ -234,7 +279,7 @@ export function parse(argv) {
       }
       continue;
     }
-    return { ok: false, code: usage(`unknown flag --${raw}`) };
+    return { ok: false, error: usage(`unknown flag --${raw}`) };
   }
 
   return { ok: true, value: { flags, positional } };
@@ -253,5 +298,5 @@ function camel(name) {
 }
 
 function usage(message) {
-  return fail(message, EXIT.USAGE);
+  return { message, code: EXIT.USAGE };
 }

package/src/ci/workflow.mjs

@@ -128,13 +128,15 @@ function header(own) {
  * is the release a reader recognises, and Dependabot's `github-actions` ecosystem
  * rewrites the pair together - which is why the pin needs no maintenance here.
  *
- * The major version is deliberately the one the templates already used rather than the
- * newest available. `checkout` v7 and `setup-node` v7 both carry breaking changes, and
- * a gate whose behaviour changes because somebody re-ran an updater is precisely what
- * pinning exists to prevent. Moving a major is one reviewed line in this table.
+ * The major version moves by review, not by updater. `checkout` stayed on v4 while v7
+ * carried breaking changes a gate should not absorb by re-running Dependabot; it moved
+ * to v7.0.1 when the v7 line had run green in this repository's own workflows (the
+ * checkout steps of the v7 Dependabot run all succeeded — only the template-drift
+ * tests failed, which is the pin doing its job). `setup-node` stays on v4: no run has
+ * yet proven a newer major here, and moving it is the same one reviewed line.
  */
 export const ACTIONS = {
-  checkout: { repo: 'actions/checkout', commit: '11d5960a326750d5838078e36cf38b85af677262', release: 'v4.4.0' },
+  checkout: { repo: 'actions/checkout', commit: '3d3c42e5aac5ba805825da76410c181273ba90b1', release: 'v7.0.1' },
   setupNode: { repo: 'actions/setup-node', commit: '49933ea5288caeca8642d1e84afbd3f7d6820020', release: 'v4.4.0' },
 };
 

package/src/commands/agenthook.mjs

@@ -22,8 +22,10 @@
 // tool call. Failures of this command exit 1, which a harness reports as a failed hook,
 // and that is the right blast radius for a hook that is broken rather than refusing.
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
@@ -185,6 +187,17 @@ async function installHooks(root, flags) {
 
   const refused = plan.filter((p) => p.error);
 
+  // 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 Promise.all(
+        plan
+          .filter((p) => p.action !== 'unchanged')
+          .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text })),
+      )
+      : [];
+
   if (!mode.apply) {
     if (isJson(flags)) {
       emitJson({
@@ -195,6 +208,7 @@ async function installHooks(root, flags) {
         plan: plan.map(({ text, ...rest }) => rest),
         notWritten: others,
         filesWritten: false,
+        ...diffField(diffs, flags),
       });
       return refused.length > 0 ? EXIT.FAIL : EXIT.OK;
     }
@@ -207,10 +221,12 @@ async function installHooks(root, flags) {
         '',
         refused.length > 0
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
-          : `PLAN     nothing written; apply with: ${CLI} agent-hooks install --yes`,
+          :        `PLAN     nothing written; apply with: ${CLI} agent-hooks install --yes`,
       ].join('\n'),
       { maxBytes: flags.maxBytes ?? 0 },
     );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     return refused.length > 0 ? EXIT.FAIL : EXIT.OK;
   }
 
@@ -221,12 +237,15 @@ async function installHooks(root, flags) {
     return fail(`refused to write ${refused.map((p) => `${p.path} (${p.error})`).join('; ')}`, EXIT.FAIL);
   }
 
+  // Journaled so `undo` restores this run (R49).
+  const journal = [];
   const written = [];
   for (const p of plan.filter((x) => x.action !== 'unchanged')) {
     await mkdir(join(root, dirname(p.path)), { recursive: true });
-    await writeFile(join(root, p.path), p.text);
+    await journaledWriteFile(root, journal, join(root, p.path), p.text);
     written.push(p);
   }
+  await commitJournal(root, 'agent-hooks install', journal);
 
   const notes = [];
   for (const p of written) {
@@ -245,6 +264,7 @@ async function installHooks(root, flags) {
       written: written.map((p) => p.path),
       filesWritten: true,
       notes,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
@@ -259,6 +279,8 @@ async function installHooks(root, flags) {
     ].join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   for (const o of others) note(`note     ${o.id}: not written - ${o.note}`);
   for (const n of notes) note(`note     ${n}`);
   note(`note     never committed or pushed (ADR-001); review, then commit yourself`);

package/src/commands/ci.mjs

@@ -18,8 +18,10 @@
 // commands owns which file would be learning about ownership twice to learn nothing
 // new, and the next .github file would arrive with a third command to remember.
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
 import { EXIT, emit, emitJson, isJson, note, writeMode } from '../output/index.mjs';
 import { planWorkflow, renderWorkflow, WORKFLOW_FILE } from '../ci/workflow.mjs';
@@ -121,18 +123,37 @@ export async function ciCommand(positional, 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 renders = new Map(targets().map(({ key, render }) => [key, render]));
+  const diffs =
+    flags.diff === true
+      ? await Promise.all(
+        plans
+          .filter((p) => p.action !== 'unchanged')
+          .map(async (p) => ({ path: p.file, before: await readBefore(p.path), after: renders.get(p.key)(p) })),
+      )
+      : [];
+
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'ci', root, files: todo.map(publicPlan), written: false, dryRun: !mode.apply }, {});
+    emitJson(
+      { ok: true, command: 'ci', root, files: todo.map(publicPlan), written: false, dryRun: !mode.apply, ...diffField(diffs, flags) },
+      {},
+    );
   } else {
     emit(lines.join('\n'));
   }
 
   if (!mode.apply) {
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     note('');
     note(mode.dryRun ? 'dry-run  nothing written' : `dry-run  nothing written; apply with: ${CLI} ci --yes`);
     return EXIT.OK;
   }
 
+  // Journaled so `undo` restores this run (R49).
+  const journal = [];
   for (const { key, plan, render } of targets()) {
     const p = plans.find((x) => x.key === key);
     if (p.action === 'unchanged') continue;
@@ -140,9 +161,10 @@ export async function ciCommand(positional, flags) {
     // The renderer takes the plan because detection-driven content is a function of
     // this repo's facts: a dependabot config rendered without them would watch
     // nothing, which is the same silent-nothing the detection ruling exists to stop.
-    await writeFile(p.path, render(p));
+    await journaledWriteFile(root, journal, p.path, render(p));
     note(`wrote    ${p.file} (${p.action}; the template and this copy now agree)`);
   }
+  await commitJournal(root, 'ci', journal);
   if (isJson(flags)) {
     emitJson(
       {
@@ -151,10 +173,13 @@ export async function ciCommand(positional, flags) {
         root,
         files: plans.map((p) => ({ file: p.file, action: p.action, bytes: p.bytes })),
         written: true,
+        ...diffField(diffs, flags),
       },
       {},
     );
   }
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }
 

package/src/commands/completions.mjs

@@ -0,0 +1,27 @@
+// `simt completions <shell>` — print a completion script (plan 0003 R51).
+//
+// The script goes to stdout and nothing else does, because the install is a
+// redirect: `source <(simt completions bash)`, or the zsh file dropped onto
+// `$fpath`. A report line above it would be a report line in the user's shell
+// config.
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { SHELLS, renderCompletions } from '../completions.mjs';
+
+export async function completionsCommand(args, flags, commands) {
+  const shell = args[0];
+  if (shell === undefined) {
+    return fail('completions needs a shell', EXIT.USAGE, `one of: ${SHELLS.join(', ')}`);
+  }
+  if (!SHELLS.includes(shell)) {
+    return fail(`unknown shell \`${shell}\``, EXIT.USAGE, `one of: ${SHELLS.join(', ')}`);
+  }
+
+  const script = renderCompletions(shell, commands);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'completions', shell, script });
+    return EXIT.OK;
+  }
+  emit(script, { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/decide.mjs

@@ -7,6 +7,8 @@ import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/i
 import { CLI } from '../name.mjs';
 import { DECISIONS_DIR } from '../decisions/index.mjs';
 import { lintDecisions, scaffoldDecision } from '../memory/decide.mjs';
+import { commitJournal } from '../journal.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 import { parsePathList } from '../argv.mjs';
 
 export async function decideCommand(args, flags) {
@@ -49,12 +51,17 @@ export async function decideCommand(args, flags) {
   const parsedPaths = parsePathList(flags.paths);
   const explicitPaths = flags.paths !== undefined ? parsedPaths : undefined;
 
+  // Journaled so `undo` restores the scaffold (R49); committed only when the
+  // run actually wrote, which commitJournal already guarantees.
+  const journal = [];
   const res = await scaffoldDecision(root, {
     title,
     affects: explicitPaths,
     supersedes: flags.supersedes,
     write: mode.apply,
+    journal: mode.apply ? journal : undefined,
   });
+  if (mode.apply && res.ok) await commitJournal(root, 'decide', journal);
 
   if (!res.ok) {
     return fail(
@@ -70,6 +77,10 @@ export async function decideCommand(args, flags) {
     note('dry-run  no files written');
   }
 
+  // A scaffold always creates: the number is free by construction, so the
+  // before side is empty and the pair is the whole file (R50).
+  const diffs = flags.diff === true ? [{ path: res.relPath, before: null, after: res.text }] : [];
+
   if (isJson(flags)) {
     emitJson({
       ok: true,
@@ -84,10 +95,10 @@ export async function decideCommand(args, flags) {
       supersedes: res.supersedes,
       written: res.written,
       dryRun: !mode.apply,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
-
   const supersedesLabel =
     res.supersedes.length > 0
       ? res.supersedes
@@ -112,5 +123,7 @@ export async function decideCommand(args, flags) {
   ];
 
   emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }