simt-dev 0.6.0 → 0.6.3

package/src/commands/skillsinstall.mjs

@@ -20,15 +20,17 @@
 //   3. References come with the skill. A skill whose reference files are missing
 //      is worse than one that was never installed, because it looks installed.
 
-import { cp, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { commitJournal, journaledCopyDir, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { loadRegistry, measureSkill } from '../graph/load.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { readCapability } from '../hooks/capability.mjs';
-import { MANIFEST, buildManifest, readManifest, writeManifest } from '../projection/manifest.mjs';
+import { MANIFEST, buildManifest, manifestPath, manifestText, readManifest, writeManifest } from '../projection/manifest.mjs';
 import { provenanceDigest } from '../projection/project.mjs';
 import { locateSource, sourceHeldLocally } from '../resolve/source.mjs';
 import { nearMatches } from '../resolve/near.mjs';
@@ -161,10 +163,18 @@ export async function installCommand(args, flags) {
   // `--yes --json` a command that reported a plan and changed nothing - the one
   // combination a script writes. The payload is now emitted once, at the end,
   // after the write it describes.
+  const mode = writeMode(flags);
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50). Built before the early returns
+  // below so the shared `report()` can carry the field in every mode.
+  const diffs = flags.diff === true ? await skillDiffs(root, { src, dest, destRel: payload.dest, flat: measured.flat, name, record, repo }) : [];
   const report = () => {
-    if (isJson(flags)) emitJson(payload);
+    // `--json` used to return here, before anything was written, which made
+    // `--yes --json` a command that reported a plan and changed nothing - the one
+    // combination a script writes. The payload is now emitted once, at the end,
+    // after the write it describes.
+    if (isJson(flags)) emitJson({ ...payload, ...diffField(diffs, flags) });
   };
-  const mode = writeMode(flags);
 
   if (!isJson(flags)) {
     emit(
@@ -213,18 +223,22 @@ export async function installCommand(args, flags) {
   // "nothing written" and then wrote. It belongs on the path that does not write.
   if (!mode.apply) {
     note(`note    dry-run  nothing written; apply with: ${CLI} skills install ${name} --yes`);
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     report();
     return EXIT.OK;
   }
 
+  // Every repo write below is journaled, so `undo` restores this run (R49).
+  const journal = [];
   await mkdir(dirname(join(dest, 'SKILL.md')), { recursive: true });
   try {
     if (measured.flat) {
-      await writeFile(join(dest, 'SKILL.md'), await wrapFlat(src, name), 'utf8');
+      await journaledWriteFile(root, journal, join(dest, 'SKILL.md'), await wrapFlat(src, name));
     } else {
       // References come with the skill: a skill whose reference files are missing
       // is worse than one that was never installed, because it looks installed.
-      await cp(src, dest, { recursive: true });
+      await journaledCopyDir(root, journal, src, dest);
     }
   } catch (error) {
     return fail(
@@ -236,12 +250,15 @@ export async function installCommand(args, flags) {
   payload.written = true;
   note(`wrote   ${payload.dest}`);
 
-  const recorded = await recordLocal(root, record, skill.name, repo);
+  const recorded = await recordLocal(root, record, skill.name, repo, journal);
   note(`${recorded.created ? 'created' : 'updated'} ${MANIFEST_FILE} localSkills`);
   if (recorded.created) {
     note(`note    this repo had no manifest; ${CLI} init still needs to run to project the rules`);
   }
   note(`note    ${name} is now repo-local and is excluded from central-drift accounting`);
+  await commitJournal(root, 'skills install', journal);
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   report();
   return EXIT.OK;
 }
@@ -502,29 +519,82 @@ async function fileSha(path) {
  * default gates in it is a promise the repo cannot keep, and a command that installs one
  * skill is not entitled to make it.
  */
-async function recordLocal(root, record, name, repo) {
+/** Every regular file under a directory, absolute paths. Missing dir → []. */
+async function treeFiles(dir) {
+  let st;
+  try {
+    st = await stat(dir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  if (!st.isDirectory()) return [dir];
+  const out = [];
+  for (const name of await readdir(dir)) {
+    out.push(...(await treeFiles(join(dir, name))));
+  }
+  return out;
+}
+
+function rel(root, path) {
+  return relative(root, path).split(sep).join('/');
+}
+
+/**
+ * The `--diff` pairs for an install: the skill files plus the manifest record
+ * (plan 0003 R50). The manifest pair needs the same object the write applies,
+ * so the plan is shared with `recordLocal` rather than derived twice.
+ */
+async function skillDiffs(root, { src, dest, destRel, flat, name, record, repo }) {
+  const pairs = [];
+  if (flat) {
+    pairs.push({
+      path: `${destRel}/SKILL.md`,
+      before: await readBefore(join(dest, 'SKILL.md')),
+      after: await wrapFlat(src, name),
+    });
+  } else {
+    // References come with the skill, so the diff walks the whole tree: only
+    // changed files render, the rest filter out as equal.
+    for (const abs of await treeFiles(src)) {
+      const destAbs = join(dest, relative(src, abs));
+      pairs.push({ path: rel(root, destAbs), before: await readBefore(destAbs), after: await readFile(abs, 'utf8') });
+    }
+  }
+  const planned = await planLocalRecord(root, record, name, repo);
+  if (!planned.error) {
+    pairs.push({
+      path: rel(root, await manifestPath(root)),
+      before: planned.manifest === null ? null : await readBefore(await manifestPath(root)),
+      after: manifestText(planned.next),
+    });
+  }
+  return pairs;
+}
+
+/**
+ * What `recordLocal` will write, computed without writing (plan 0003 R50).
+ * The diff shares this so the pair shows the same object the write applies.
+ */
+async function planLocalRecord(root, record, name, repo) {
   const { manifest, error } = await readManifest(root);
-  if (error) return { written: false, reason: error };
-
-  // A repo with no manifest gets one here, so this function writes a *promise* on that
-  // repo's behalf: it decides which gates the repo claims to run. Without a capability
-  // probe it wrote `format`, `lint`, `test` and `typecheck` into a repository with no
-  // scripts and no formatter, and `check` then reported four UNRUNNABLE gates. The moment
-  // hooks route through the manifest - which is the entire point of a gate - every commit
-  // in that repo is blocked, over gates nobody declared. ADR-017 exists to prevent exactly
-  // that, and a manifest written by a command that installs one skill was the way round it.
-  // `init` probes for the same reason; a second writer that does not is a defect waiting
-  // for the next command that needs a manifest.
-  const base =
-    manifest ??
-    (await buildManifest({
-      root,
-      stack: repo.stack,
-      sha: await provenanceDigest(),
-      capability: await readCapability(root),
-    }));
+  if (error) return { error };
+  const base = manifest ?? (await buildManifest({ root, stack: repo.stack, sha: await provenanceDigest(), capability: await readCapability(root) }));
   const existing = Array.isArray(base.localSkills) ? base.localSkills : [];
   const kept = existing.filter((e) => (typeof e === 'string' ? e : e?.name) !== name);
-  await writeManifest(root, { ...base, localSkills: [...kept, record] });
-  return { written: true, created: manifest === null };
+  return { manifest, next: { ...base, localSkills: [...kept, record] }, created: manifest === null };
+}
+
+async function recordLocal(root, record, name, repo, journal) {
+  // The manifest this writes is `planned.next`, built by `planLocalRecord`:
+  // a repo with no manifest gets one here, which is a promise about which
+  // gates the repo claims to run. Without the capability probe inside the
+  // plan it wrote `format`, `lint`, `test` and `typecheck` into a repository
+  // with no scripts and no formatter, and `check` then reported four
+  // UNRUNNABLE gates that blocked every commit (ADR-017). Deriving the object
+  // a second way here would be a second answer to what the repo promises.
+  const planned = await planLocalRecord(root, record, name, repo);
+  if (planned.error) return { written: false, reason: planned.error };
+  await writeManifest(root, planned.next, journal);
+  return { written: true, created: planned.created };
 }

package/src/commands/slice.mjs

@@ -0,0 +1,353 @@
+// `simt slice start` and `simt slice finish`: one tracker row, one branch.
+//
+// A row in a tracker is a promise, and these are the two moments it is acted on.
+// `start` isolates the work: a linked worktree on a branch named for the row, so the
+// main checkout stays free for whatever else is running, and the task brief already on
+// disk at `.simt/brief.md` — the same path the bench's brief arm writes — where an
+// agent picks it up. `finish` closes the loop the way the repository's own hook would:
+// the declared gates run through the shared dispatcher first, because a command that
+// commits for you may not assume a hook is installed to stop it, then the commit
+// carries a Conventional subject built from the row's own title, and only then does
+// the tracker learn the SHA and the test command that closed it — the R31 row
+// machinery, called, never reimplemented.
+//
+// Two orders here are contracts rather than preferences:
+//
+//   start: worktree, brief, then row. Everything the row would claim exists before it
+//   claims it, so a failed `worktree add` leaves the tracker untouched.
+//
+//   finish: gates, commit, row. The row records a SHA that only exists after the
+//   commit, and if the row write then fails the message says which half happened —
+//   the commit exists, the tracker does not know it — because a silent half-state is
+//   how a tracker starts lying.
+//
+// The tracker itself always lives in the MAIN checkout. `start` flips the row there
+// and `finish` records the evidence there, while the worktree carries only the
+// slice's code: editing the same row in both places would make every merge of a
+// finished slice a conflict on the one line that records it.
+
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { planDone, planNext } from '../plan/index.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+import { renderGateReport, runGates, stagedFiles } from '../hooks/dispatcher.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+import { CLI, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
+
+const exec = promisify(execFile);
+
+/** The state a started slice moves to, spelled the way the tracker template spells it. */
+const STARTED = 'In progress';
+
+/**
+ * A Conventional Commits type: one lower-case word, optionally scoped, optionally
+ * marked breaking. The scope a `finish` builds is the slice id, so this flag is the
+ * subject's only free input — a title cannot say whether a slice was a feat, a fix or
+ * a chore, and deriving it from the words would be a guess no reader could argue with.
+ */
+const TYPE = /^[a-z]+(?:\([a-z0-9][a-z0-9._-]*\))?!?$/;
+
+async function git(root, args) {
+  const { stdout } = await exec('git', ['-C', root, ...args], { maxBuffer: 32 << 20 });
+  return stdout.trim();
+}
+
+/**
+ * The checkout that owns the tracker: the main worktree when `root` is a linked one.
+ *
+ * `--git-common-dir` answers `.git` from the main checkout and `<main>/.git` from a
+ * worktree, so resolving it against `root` and dropping the last component gives the
+ * right answer in both shapes. A directory that is not a git repository at all falls
+ * back to `root`: the plan machinery reads it from wherever it was pointed, and the
+ * git commands below will have their own say about whether this is a repository.
+ */
+async function mainCheckout(root) {
+  try {
+    const common = await git(root, ['rev-parse', '--git-common-dir']);
+    return dirname(resolve(root, common));
+  } catch {
+    return root;
+  }
+}
+
+/** The branch and worktree a slice owns. Both derive from the id: one id, one spelling. */
+function places(main, id) {
+  const slug = id.toLowerCase();
+  return {
+    branch: `slice/${slug}`,
+    worktree: join(main, STATE_DIR, 'worktrees', slug),
+  };
+}
+
+/**
+ * The Conventional subject for a finished slice: `<type>(<id>): <title>`.
+ *
+ * The description is the row's own title, so the message says what the plan said it
+ * would do — whitespace collapsed, a trailing period dropped (slice-commit wants an
+ * imperative subject with no trailing period), and the id itself as the fallback when
+ * a tracker has no title column rather than an empty description after the colon.
+ */
+function subjectFor(type, id, title) {
+  const description = String(title ?? '').replace(/\s+/g, ' ').trim().replace(/\.$/, '') || id;
+  return `${type}(${id.toLowerCase()}): ${description}`;
+}
+
+/** Resolve one named slice through `plan next`, which already knows missing and ambiguous. */
+async function resolveSlice(main, id) {
+  const found = await planNext(main, id);
+  if (found.error) return { error: found.error, remedy: found.remedy ?? `run: ${CLI} plan status` };
+  if (!found.next) return { error: found.reason ?? `${id} has no section`, remedy: `run: ${CLI} plan status` };
+  return { slice: found.next };
+}
+
+export async function sliceCommand(sub, args, flags) {
+  const root = flags.root ?? process.cwd();
+  if (sub === 'start') {
+    const id = args[0];
+    if (!id) return fail(`${CLI} slice start needs a slice id`, EXIT.USAGE, `run: ${CLI} plan next`);
+    return startSlice(root, id, flags);
+  }
+  if (sub === 'finish') {
+    const id = args[0];
+    if (!id) return fail(`${CLI} slice finish needs a slice id`, EXIT.USAGE, `run: ${CLI} plan next`);
+    return finishSlice(root, id, flags);
+  }
+  return fail(`unknown slice subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} slice start <id>  |  ${CLI} slice finish <id>`);
+}
+
+async function startSlice(root, id, flags) {
+  const mode = writeMode(flags);
+  const main = await mainCheckout(root);
+  const resolved = await resolveSlice(main, id);
+  if (resolved.error) return fail(resolved.error, EXIT.USAGE, resolved.remedy);
+  const { title, doc } = resolved.slice;
+  const { branch, worktree } = places(main, id);
+  const briefPath = join(worktree, STATE_DIR, 'brief.md');
+  const task = `${id}: ${String(title ?? '').trim()}`;
+  const apply = `run: ${CLI} slice start ${id} --yes`;
+
+  // The row first, dry, against the main checkout: it is the only part of `start`
+  // that can refuse for a reason about the tracker rather than about git, and a
+  // preview that discovers it late is a preview that half-described the work.
+  const preview = await planDone(main, id, { state: STARTED, dryRun: true });
+  if (preview.error) return fail(preview.error, EXIT.USAGE, preview.remedy ?? `run: ${CLI} plan status`);
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'slice start',
+        root,
+        id,
+        title,
+        dryRun: true,
+        branch,
+        worktree: relative(main, worktree),
+        brief: { path: relative(main, briefPath), bytes: null },
+        state: { from: preview.from, to: preview.to, changed: preview.wouldChange },
+        remedy: apply,
+      });
+      return EXIT.OK;
+    }
+    const lines = [
+      `repo     ${root}`,
+      `slice    ${id}  ${doc}`,
+      `branch   ${branch}`,
+      `worktree ${relative(main, worktree)}`,
+      `brief    ${relative(main, briefPath)} (assembled on apply)`,
+      `state    ${preview.from} -> ${preview.to}`,
+      `apply    ${apply}`,
+    ];
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  // Assemble before anything is created: a packet that cannot be built must leave the
+  // repository exactly as it was, rather than a worktree nobody can brief and a row
+  // still waiting. `build` defaults on — this is a command a person asked for, not a
+  // prompt-submit delivery, so a cold index is built rather than reported.
+  const packet = await assembleBrief({ root: main, task });
+  if (packet.error) {
+    return fail(`the brief for ${id} could not be assembled: ${packet.error}`, EXIT.FAIL, `run: ${CLI} brief ${JSON.stringify(task)}`);
+  }
+  if (packet.cold) {
+    return fail(`the index at ${main} is empty and will not build here`, EXIT.UNSUPPORTED, `run: ${CLI} index`);
+  }
+
+  try {
+    await git(main, ['worktree', 'add', '-b', branch, worktree]);
+  } catch (error) {
+    const detail = String(error.stderr ?? error.message ?? error).trim().split('\n')[0];
+    return fail(`the worktree could not be created: ${detail}`, EXIT.FAIL, `run: git -C ${main} worktree list`);
+  }
+
+  await mkdir(join(worktree, STATE_DIR), { recursive: true });
+  await writeFile(briefPath, packet.packed.text, 'utf8');
+
+  const row = await planDone(main, id, { state: STARTED, dryRun: false });
+  if (row.error) {
+    return fail(`${branch} exists with its brief, but the tracker row was not updated: ${row.error}`, EXIT.FAIL, row.remedy ?? `run: ${CLI} plan status`);
+  }
+
+  const bytes = Buffer.byteLength(packet.packed.text);
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'slice start',
+      root,
+      id,
+      title,
+      branch,
+      worktree: relative(main, worktree),
+      brief: { path: relative(main, briefPath), bytes },
+      state: { from: row.from, to: row.to, changed: row.changed },
+    });
+    return EXIT.OK;
+  }
+  const lines = [
+    `repo     ${root}`,
+    `slice    ${id}  ${doc}`,
+    `branch   ${branch}`,
+    `worktree ${relative(main, worktree)}`,
+    `brief    ${relative(main, briefPath)}  ${bytes} bytes`,
+    `state    ${row.from} -> ${row.to}`,
+  ];
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function finishSlice(root, id, flags) {
+  const mode = writeMode(flags);
+  const main = await mainCheckout(root);
+  const resolved = await resolveSlice(main, id);
+  if (resolved.error) return fail(resolved.error, EXIT.USAGE, resolved.remedy);
+  const { title, doc } = resolved.slice;
+
+  const type = String(flags.type ?? 'feat');
+  if (!TYPE.test(type)) {
+    return fail(`${type} is not a Conventional Commits type`, EXIT.USAGE, `example: run: ${CLI} slice finish ${id} --type fix`);
+  }
+  const subject = subjectFor(type, id, title);
+  const test = flags.test ?? null;
+
+  // A manifest that does not parse fails closed: the gates cannot be read, so nothing
+  // may commit through them. No manifest at all is a valid answer — `runGates` turns
+  // it into a note and an empty pass, the same way the hook does.
+  const manifest = await readManifest(root);
+  if (manifest.error) {
+    return fail(`${MANIFEST_FILE}: ${manifest.error}`, EXIT.CONFIG, `fix ${MANIFEST_FILE}, or run: ${CLI} init`);
+  }
+  const declared = manifest.manifest?.gates?.preCommit ?? [];
+  const apply = `run: ${CLI} slice finish ${id}${test ? ` --test ${JSON.stringify(test)}` : ''} --yes`;
+
+  const staged = await stagedFiles(root);
+
+  if (!mode.apply) {
+    const row = await planDone(main, id, { sha: null, test, dryRun: true });
+    if (row.error) return fail(row.error, EXIT.USAGE, row.remedy ?? `run: ${CLI} plan status`);
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'slice finish',
+        root,
+        id,
+        dryRun: true,
+        subject,
+        staged,
+        gates: { event: 'pre-commit', declared },
+        state: { from: row.from, to: row.to, changed: row.wouldChange },
+        remedy: apply,
+      });
+      return EXIT.OK;
+    }
+    const lines = [
+      `repo     ${root}`,
+      `slice    ${id}  ${doc}`,
+      `gates    pre-commit  ${declared.length > 0 ? declared.join(', ') : '(none declared)'} (run on apply)`,
+      `staged   ${staged.length} file(s)${staged.length === 0 ? '  (finish refuses without one)' : ''}`,
+      `subject  ${subject}`,
+      `state    ${row.from} -> ${row.to}`,
+      `apply    ${apply}`,
+    ];
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  if (staged.length === 0) {
+    return fail(`${root} has nothing staged to commit`, EXIT.USAGE, `stage what the slice changed, then rerun: ${apply}`);
+  }
+
+  // The gates the hook would run, run here. This command is the one place a commit
+  // happens where a hook could not have stopped it, so it runs the same dispatcher
+  // over the same event, in the checkout that holds the staged diff.
+  const gates = await runGates('pre-commit', { root, manifest: manifest.manifest });
+  if (gates.error) return fail(gates.error, EXIT.USAGE);
+
+  if (gates.failed) {
+    const failed = gates.gates.filter((g) => g.status === 'failed').map((g) => g.name).join(', ');
+    if (isJson(flags)) {
+      emitJson({
+        ok: false,
+        command: 'slice finish',
+        root,
+        id,
+        exitCode: EXIT.FAIL,
+        error: `pre-commit gates failed: ${failed}`,
+        remedy: `run: ${CLI} hooks run pre-commit --root ${root}`,
+        gates: gates.gates,
+      });
+      return EXIT.FAIL;
+    }
+    for (const n of gates.notes ?? []) note(`note     ${n}`);
+    emit(renderGateReport('pre-commit', declared, gates).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.FAIL;
+  }
+
+  let sha = null;
+  try {
+    await git(root, ['commit', '-m', subject]);
+    sha = await git(root, ['rev-parse', 'HEAD']);
+  } catch (error) {
+    const detail = String(error.stderr ?? error.message ?? error).trim().split('\n')[0];
+    return fail(`the gates passed but the commit failed: ${detail}`, EXIT.FAIL, `run: git -C ${root} commit -m ${JSON.stringify(subject)}`);
+  }
+
+  const row = await planDone(main, id, { sha, test, dryRun: false });
+  if (row.error) {
+    return fail(`${sha} is committed, but the tracker row could not record it: ${row.error}`, EXIT.FAIL, row.remedy ?? `run: ${CLI} plan status`);
+  }
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'slice finish',
+      root,
+      id,
+      title,
+      commit: { sha, subject },
+      gates: gates.gates,
+      staged,
+      evidence: { recorded: row.evidenceRecorded, sha: row.sha, test: row.test, note: row.evidenceNote },
+      row: { file: relative(main, row.file), line: row.line, from: row.from, to: row.to, changed: row.changed },
+    });
+    return EXIT.OK;
+  }
+
+  for (const n of gates.notes ?? []) note(`note     ${n}`);
+  const lines = [
+    `repo     ${root}`,
+    `slice    ${id}  ${doc}`,
+    ...renderGateReport('pre-commit', declared, gates),
+    `commit   ${sha}  ${subject}`,
+    `state    ${row.from} -> ${row.to}`,
+    `record   ${relative(main, row.file)} line ${row.line}  (edited, not staged: commit it with the merge)`,
+  ];
+  if (row.evidenceRecorded) lines.push(`evidence ${sha}${test ? `  test: ${test}` : ''}`);
+  else if (row.evidenceNote) lines.push(`note     ${row.evidenceNote}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

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;
+}