simt-dev 0.6.2 → 0.7.0

package/src/commands/status.mjs

@@ -0,0 +1,62 @@
+// `simt status --line`
+//
+// One line from the last `check`, for shell prompts, tmux and agent status
+// lines: `simt PASS ✓rules ✓hooks 3/3gates`. The line is the gate state *as
+// of the last check* — it reads only `.simt/check.json` plus one
+// `git rev-parse HEAD`, so it answers in milliseconds while `check` itself
+// takes the time projection takes.
+//
+// Bare `status` is a usage error, the way `plan` without a subcommand is: the
+// only mode this command has is `--line`, and running something else by
+// default would invent a second answer to what the status is.
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { currentHead, readCheckCache, renderStatusLine } from '../status.mjs';
+
+export async function statusCommand(args, flags) {
+  const root = flags.root ?? args[0] ?? process.cwd();
+  if (flags.line !== true) {
+    return fail('status needs --line', EXIT.USAGE, `run: ${CLI} status --line --root ${root}`);
+  }
+
+  const record = await readCheckCache(root);
+  if (record === null) {
+    // Informational, not a failure: a repository that never ran `check` — or
+    // one a writer just invalidated — has no state to report, and a prompt
+    // that errored until the first check would train its reader to ignore it.
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'status', root, line: null, cached: false, stale: false });
+      return EXIT.OK;
+    }
+    emit('simt no cache - run check');
+    return EXIT.OK;
+  }
+
+  const head = await currentHead(root);
+  // Stale when HEAD moved since the check ran. When either side is unknown
+  // there is nothing to compare, so the record stands as written.
+  const stale = head !== null && record.head !== null && head !== record.head;
+  const line = renderStatusLine(record, stale);
+  const code = record.blocking === 0 ? EXIT.OK : EXIT.FAIL;
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: code === EXIT.OK,
+      command: 'status',
+      root,
+      line,
+      cached: true,
+      stale,
+      rulesOk: record.rulesOk,
+      hooksOk: record.hooksOk,
+      gatesRun: record.gatesRun,
+      gatesTotal: record.gatesTotal,
+      blocking: record.blocking,
+      warnings: record.warnings,
+    });
+    return code;
+  }
+  emit(line);
+  return code;
+}

package/src/commands/sync.mjs

@@ -16,21 +16,23 @@
 //     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 { CLI, LOCK_FILE, MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
 import { assertVersionPin, packageVersion } from '../package-version.mjs';
 import { resolvePacks } from '../packs.mjs';
-import { computeLock, readLock, LOCK_FILE } from '../projection/lock.mjs';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { buildCacheRecord, hooksSummary, invalidateCheckCache, writeCheckCache } from '../status.mjs';
+import { computeLock, readLock } from '../projection/lock.mjs';
 import { runDeclaredChecks } from '../kernel/checks.mjs';
-import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { decisionsCutoff, decisionsDir } from '../decisions/dir.mjs';
 import { lintDecisions } from '../memory/decide.mjs';
 
 /** Findings `sync` reports and does not fail on.
@@ -61,6 +63,12 @@ export const SYNC_NON_BLOCKING = new Set([
   'budget-cut',
   'file-lines-warn',
   'check-unbuilt',
+  // Review 0003 Q28: the tsconfig strictness findings. The base file is repo-owned —
+  // init no longer writes it, so neither can `sync` — and both findings' remedies are
+  // a decision about the repo's own compiler policy, not a missing file. Blocking on
+  // them would fail every fresh TypeScript adoption over a file the tool does not write.
+  'inert',
+  'inconsistent',
 ]);
 
 /**
@@ -98,7 +106,21 @@ export const SYNC_NON_BLOCKING = new Set([
 // (ADR-083). It says the projection was cut to fit a ceiling this repository set, so the
 // remedy is a decision about the number — and a cut the repository asked for by declaring
 // a budget is the tool working, not a repository in need of a file.
-export const CHECK_NON_BLOCKING = new Set(['orphaned', 'pack-unpinned', 'budget', 'budget-cut', 'file-lines-warn', 'check-unbuilt']);
+// `inert` and `inconsistent` are here for review 0003 Q28: the base file is repo-owned,
+// so the gate reports the state of the repo's own compiler policy without failing it.
+// A fresh TypeScript adoption has neither file in a state the tool can repair, and a
+// gate that reddens on a policy decision is one the repo satisfies by choosing, not by
+// running a command.
+export const CHECK_NON_BLOCKING = new Set([
+  'orphaned',
+  'pack-unpinned',
+  'budget',
+  'budget-cut',
+  'file-lines-warn',
+  'check-unbuilt',
+  'inert',
+  'inconsistent',
+]);
 
 export async function syncCommand(positional, flags) {
   const root = flags.root ?? positional[0] ?? process.cwd();
@@ -150,6 +172,10 @@ export async function syncCommand(positional, flags) {
     );
   }
 
+  // A dangling cross-reference does not stop the projection: the region renders, and one
+  // unreachable reference is a defect to report, not a reason to withhold the rest.
+  for (const p of result.crossRefs ?? []) note(`PROBLEM ${p}`);
+
   const broken = result.targets.filter((t) => t.action === 'malformed');
   if (broken.length > 0) {
     const first = broken[0];
@@ -249,6 +275,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 +314,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) {
@@ -278,23 +330,20 @@ export async function syncCommand(positional, flags) {
       // mkdir; `sync` did not, so the first `sync` after a surface was added failed with
       // ENOENT on the second target and had already written the first. The parent is
       // derived from the target, never from the surface table, so a future surface with a
-      // deeper path needs no change here.
+      // deeper path needs no change here. The lock is one of these targets (Q29): it
+      // reaches this loop like every other file, so a deleted lock is a write the plan
+      // shows and the journal records.
       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);
-    const lockText = `${JSON.stringify(lock, null, 2)}\n`;
-    let previousLock = null;
-    try {
-      previousLock = await readFile(join(root, LOCK_FILE), 'utf8');
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-    }
-    if (previousLock !== lockText) {
-      await writeFile(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 +377,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 +410,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 +439,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 +537,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 +560,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 +584,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,20 +607,22 @@ 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);
   const { selected } = select(rules.filter((r) => r.error === null), fp.stack ?? [], fp.facts ?? []);
   findings.push(...(await runDeclaredChecks(root, selected, manifest ?? null)));
 
-  const decisionsDir = join(root, 'docs', 'decisions');
-  const decisionLint = await lintDecisions(decisionsDir, {
-    allowHistorical: resolve(decisionsDir) === DECISIONS_DIR,
+  // Q55: one resolution shared with `decide --check`, so the two commands
+  // cannot disagree about whose records these are or which are historical.
+  const relDecisionsDir = await decisionsDir(root);
+  const decisionLint = await lintDecisions(join(root, relDecisionsDir), {
+    historicalCutoff: await decisionsCutoff(root),
   });
   findings.push(
     ...decisionLint.findings.map((f) => ({
-      file: ['docs', 'decisions', f.file].join('/'),
+      file: [relDecisionsDir, f.file].join('/'),
       status: f.status,
       detail: f.detail,
       remedy: f.remedy,
@@ -547,16 +633,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 +680,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/tests.mjs

@@ -13,7 +13,7 @@ import { promisify } from 'node:util';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { isTestPath } from '../bench/mine.mjs';
-import { blobTexts, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
+import { blobTexts, isIndexStale, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
 import { HISTORY, importsOf, parseCoverage, testEdges, testsFor } from '../index/tests.mjs';
 
 const exec = promisify(execFile);
@@ -84,7 +84,10 @@ function summarise(root, flags, edges) {
 
 async function loadFiles(root) {
   let files = await readFiles(root);
-  if (files.length === 0) {
+  // An empty index has nothing to answer from; a stale one has yesterday's
+  // tree (review 0003 Q42). Either way the refresh is incremental, so a
+  // current repository pays for one `git ls-files -s`, not a rebuild.
+  if (files.length === 0 || (await isIndexStale(root))) {
     try {
       await reindex(root);
     } catch (error) {

package/src/commands/undo.mjs

@@ -0,0 +1,114 @@
+// `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, files the run created
+// are deleted, and git config keys the run set go back to their pre-run
+// values (review 0003 Q22). 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 { beforeText, entryLabel, listJournalSets, readGitValue, 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 labels = set.entries.map(entryLabel);
+  // The `--diff` pairs: what the tree holds now against what the restore
+  // would put back. A null before is a file the run created (or a key it
+  // set from unset), so the restore deletes it — the after side is empty
+  // (R50).
+  const diffs =
+    flags.diff === true
+      ? await Promise.all(
+        set.entries.map(async (e) => {
+          if (e.kind === 'git-config') {
+            return { path: entryLabel(e), before: await readGitValue(root, e.key), after: e.before ?? null };
+          }
+          return { path: e.path, before: await readBefore(join(root, e.path)), after: beforeText(e) };
+        }),
+      )
+      : [];
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'undo', root, set: id, restores: labels, dryRun: true, ...diffField(diffs, flags) });
+      return EXIT.OK;
+    }
+    const files = set.entries.filter((e) => e.kind !== 'git-config').length;
+    const keys = set.entries.length - files;
+    emit(
+      [
+        `last write  ${set.command} (${id})`,
+        ...labels.map((p) => `restore   ${p}`),
+        '',
+        `would restore ${files} file(s)${keys > 0 ? ` and ${keys} git config key(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;
+}