simt-dev 0.7.0 → 0.8.0

package/src/run.mjs

@@ -0,0 +1,98 @@
+// `run(command, input)` - one command, as a result (review 0003 Q63).
+//
+// The CLI prints and returns an exit code; that is right for a terminal and useless for a
+// library, an MCP tool or a harness that wants the answer. Rather than rewrite seventy
+// command modules to return values they do not currently compute, this runs the same
+// handler through the output sink: the handler is unchanged, and what it would have
+// written comes back as data.
+//
+// That is a boundary, not a second implementation. `dispatch` and `run` resolve the same
+// registry, apply the same flag guard rails and call the same function, so a command
+// cannot work in one and not the other - the failure would be invisible in the CLI, which
+// is why `test/run.test.mjs` drives both surfaces.
+//
+// What a caller gets is not a rendering decision made for them: `text` and `documents` are
+// both there when the command produced both, and `renderText`/`renderJson` are the two
+// answers the CLI had. A caller that wants neither reads the fields a command exported
+// (`src/api.mjs`).
+
+import { EXIT, clearWarnings, jsonCommand, jsonFailMode, jsonIndentDefault, maxBytesLimit, warnings, withOutputState, withSink } from './output/index.mjs';
+import { CLI } from './name.mjs';
+import { GLOBAL_FLAGS, resolveCommand } from './commands/index.mjs';
+
+/** `--some-flag` for a flag key the parser handed back as `someFlag`. */
+function spelled(key) {
+  return key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+function failure(command, code, message, remedy) {
+  return {
+    command,
+    ok: false,
+    code,
+    text: '',
+    documents: [],
+    notes: [],
+    warnings: [],
+    error: { message, remedy: remedy ?? `run: ${CLI} --help`, exitCode: code },
+  };
+}
+
+/**
+ * Run one command path and answer with what it produced.
+ *
+ * @param {string} command the dispatch key: `status`, `plan next`, `hooks install`
+ * @param {{args?: string[], flags?: object, root?: string}} [input]
+ */
+export async function run(command, { args = [], flags = {}, root } = {}) {
+  const resolved = await resolveCommand(command);
+  if (resolved === null) return failure(command, EXIT.USAGE, `unknown command \`${command}\``);
+
+  // The guard rails the dispatcher applies, applied here for the same reason: a library
+  // caller that passes `--frozen` to `status` must be told, not quietly served a default.
+  for (const key of Object.keys(flags)) {
+    if (GLOBAL_FLAGS.has(key) || resolved.declared.has(spelled(key))) continue;
+    return failure(command, EXIT.USAGE, `--${spelled(key)} is not a flag of \`${command}\``);
+  }
+  for (const [flag, allowed] of Object.entries(resolved.values)) {
+    const value = flags[flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase())];
+    if (value !== undefined && !allowed.includes(value)) {
+      return failure(command, EXIT.USAGE, `--${flag} takes ${allowed.join(', ')}; received ${value}`);
+    }
+  }
+
+  clearWarnings();
+  jsonCommand(command);
+  jsonIndentDefault(flags.pretty === true);
+  maxBytesLimit(flags.maxBytes);
+  jsonFailMode(flags.json === true);
+
+  const effective = root === undefined ? flags : { root, ...flags };
+  const produced = await withOutputState(() => withSink(() => resolved.run(args, effective)));
+  return {
+    command,
+    ok: produced.code === EXIT.OK,
+    code: produced.code,
+    text: produced.text,
+    documents: produced.documents,
+    notes: produced.notes,
+    warnings: warnings(),
+    error: produced.error,
+  };
+}
+
+/** The text the command printed, as one string. Empty when it answered in JSON. */
+export function renderText(result) {
+  return result.text;
+}
+
+/**
+ * The document the command emitted, or null when it answered as text.
+ *
+ * A command that emits a stream (NDJSON) has more than one document and gets an array:
+ * collapsing a stream to its first element is how a caller silently loses rows.
+ */
+export function renderJson(result) {
+  if (result.documents.length === 0) return null;
+  return result.documents.length === 1 ? result.documents[0] : result.documents;
+}

package/src/secrets.mjs

@@ -23,10 +23,7 @@
 //     is documentation, and a gate that blocks it teaches the exact `--no-verify`
 //     habit the dispatcher's fail-closed rule exists to prevent.
 
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-
-const exec = promisify(execFile);
+import { git } from './sys/git.mjs';
 
 /** The length at which a token is worth measuring, and the entropy it must reach. */
 const ENTROPY_MIN_LENGTH = 32;
@@ -294,24 +291,19 @@ export async function scanStaged(root, options = {}) {
     // program that prints nothing, `-diff` in `.gitattributes` and genuinely binary
     // files make git print no text at all, a textconv rewrites the bytes on the way
     // out, `diff.mnemonicPrefix` renames the header prefixes the attribution below
-    // reads, and C-quoting mangles a non-ASCII name. The scan asks git for the staged
-    // bytes with its own flags and ignores what the repository asked for.
-    ({ stdout } = await exec(
-      'git',
-      [
-        '-c', 'core.quotePath=false',
-        'diff',
-        '--cached',
-        '--no-ext-diff',
-        '--no-textconv',
-        '--text',
-        '--unified=0',
-        '--no-color',
-        '--src-prefix=a/',
-        '--dst-prefix=b/',
-      ],
-      { cwd: root, maxBuffer: 32 * 1024 * 1024 },
-    ));
+    // reads. The scan asks git for the staged bytes with its own flags and ignores
+    // what the repository asked for.
+    stdout = await git(root, [
+      'diff',
+      '--cached',
+      '--no-ext-diff',
+      '--no-textconv',
+      '--text',
+      '--unified=0',
+      '--no-color',
+      '--src-prefix=a/',
+      '--dst-prefix=b/',
+    ]);
   } catch (error) {
     const stderr = String(error.stderr ?? '').trim();
     const reason = (stderr || String(error.message ?? error)).split('\n')[0];

package/src/state/events.mjs

@@ -0,0 +1,129 @@
+// One append-only event log for everything this tool observes about itself (Q73).
+//
+// The stores that record what happened - the evidence ledger, the lessons file, the lease
+// file, the check cache - were five files with three version keys and no shared shape, so
+// nothing could tail them and no UI could show a run. An event is one line with one
+// envelope, appended with `O_APPEND` so two writers never rewrite each other's history.
+//
+// The log is the record; the ledger and the lessons file are projections of it. A reader
+// that still reads the old file gets the same answer, because the projection is written to
+// the same place it always was - but a line lost to rotation is recoverable here, and a
+// consumer that wants to watch a run live has one file to follow.
+//
+// `O_APPEND` matters more than it looks: a lease write and a gate run in two processes can
+// land at the same moment, and a read-modify-write of a shared log would drop one of them.
+// That is the same defect the lease lock exists for, and an append does not need the lock.
+
+import { randomBytes } from 'node:crypto';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { localRel, readStateFile } from '../state.mjs';
+
+/** Where the log lives: machine-local state, so no run changes the tree it describes. */
+export const EVENTS_FILE = localRel('events.jsonl');
+const EVENTS_LEGACY = '.simt/events.jsonl';
+
+/**
+ * The closed set of kinds. A kind that is not here is a typo that would otherwise sit in
+ * the log forever, unread by every consumer and silently meaningless.
+ */
+export const EVENT_KINDS = Object.freeze([
+  'gate.started',
+  'gate.finished',
+  'policy.decided',
+  'lease.acquired',
+  'lease.released',
+  'lease.expired',
+  'slice.transitioned',
+  'write.committed',
+  'write.undone',
+  'lesson.captured',
+]);
+
+/** Crockford base32, the alphabet ULID uses: no I, L, O or U, so a hand-copied id is unambiguous. */
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+/**
+ * A ULID: 48 bits of milliseconds, then 80 bits of randomness.
+ *
+ * Chosen over a UUID because it sorts by time as bytes, which is what makes a log
+ * appendable and a tail read meaningful without parsing timestamps.
+ */
+export function ulid(now = Date.now()) {
+  let time = '';
+  let left = now;
+  for (let i = 0; i < 10; i += 1) {
+    time = CROCKFORD[left % 32] + time;
+    left = Math.floor(left / 32);
+  }
+  const bytes = randomBytes(16);
+  let random = '';
+  for (let i = 0; i < 16; i += 1) random += CROCKFORD[bytes[i] % 32];
+  return `${time}${random}`;
+}
+
+/**
+ * Append one event, or throw.
+ *
+ * A caller that cannot record what it did has to hear about it: a swallowed failure here
+ * is a gate that ran and left no evidence, which is the state the ledger exists to make
+ * impossible.
+ */
+export async function appendEvent(root, { kind, session = null, harness = null, tree = null, subject = null, data = {} }) {
+  if (!EVENT_KINDS.includes(kind)) {
+    throw new Error(`unknown event kind: ${kind}`);
+  }
+  const event = {
+    v: 1,
+    id: ulid(),
+    ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    kind,
+    session,
+    harness,
+    tree,
+    subject,
+    data,
+  };
+  const path = join(root, EVENTS_FILE);
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(event)}\n`);
+  return event;
+}
+
+/**
+ * Best-effort append for a caller whose primary job must not fail on a log write.
+ *
+ * Used by `undo` and by lesson capture: the work those commands do is already done, and
+ * throwing afterwards would report a failure the user cannot act on. The error is returned
+ * rather than swallowed so a caller that wants to surface it can.
+ */
+export async function noteEvent(root, event) {
+  try {
+    return { event: await appendEvent(root, event), error: null };
+  } catch (error) {
+    return { event: null, error: error.message };
+  }
+}
+
+/** Every well-formed event, oldest first; damaged lines are reported, never hidden. */
+export async function readEvents(root, { limit = 0 } = {}) {
+  const { text } = await readStateFile(root, EVENTS_FILE, [EVENTS_LEGACY]);
+  if (text === null) return { events: [], errors: [] };
+  const events = [];
+  const errors = [];
+  for (const [i, raw] of text.split('\n').entries()) {
+    if (raw.trim() === '') continue;
+    try {
+      const event = JSON.parse(raw);
+      if (typeof event?.id !== 'string' || typeof event?.kind !== 'string') {
+        errors.push(`line ${i + 1} has no id or kind`);
+        continue;
+      }
+      events.push(event);
+    } catch (error) {
+      errors.push(`line ${i + 1} does not parse (${error.message})`);
+    }
+  }
+  return { events: limit > 0 ? events.slice(-limit) : events, errors };
+}

package/src/status-snapshot.mjs

@@ -0,0 +1,233 @@
+// The aggregate behind bare `simt status` (review 0003 Q82).
+//
+// `status --line` answers one question in milliseconds: the gate state as of the last
+// check. Bare `status` was a usage error, and its comment justified that by claiming
+// `plan` without a subcommand behaved the same way - `plan` exits 0 and prints its
+// tracker. The question bare `status` was refusing is the one a UI's home view and a
+// harness status line ask: what is the state of this repository.
+//
+// Every slot is read through the module that owns it - the check cache, hook routing,
+// the agent-hook table, the ledger, the lease file, the plan tracker, the journal -
+// because a second implementation of any of them is a second answer to the same
+// question, and the quiet one is the one a reader acts on. A slot that cannot answer
+// carries its error and leaves the rest of the snapshot intact: an unreadable manifest
+// must not blind a caller to the evidence and the leases that did answer.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { adapters, hookPath, installedIn } from './agenthooks/render.mjs';
+import { readHooksState, wantsShim } from './compare/hooksstate.mjs';
+import { repoContext } from './context.mjs';
+import { listJournalSets } from './journal.mjs';
+import { activeLeases, readLeases } from './lease.mjs';
+import { hasTestEvidence, readLedger } from './ledger/index.mjs';
+import { CLI } from './name.mjs';
+import { planStatus } from './plan/index.mjs';
+import { currentHead, readCheckCache, renderStatusLine } from './status.mjs';
+import { gitText } from './sys/git.mjs';
+
+/** One slot's failure is that slot's answer, never the snapshot's. */
+async function slot(compute) {
+  try {
+    return await compute();
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+async function checkSlot(root) {
+  const record = await readCheckCache(root);
+  if (record === null) return null;
+  const head = await currentHead(root);
+  const stale = head !== null && record.head !== null && head !== record.head;
+  return {
+    at: record.at,
+    head: record.head,
+    stale,
+    line: renderStatusLine(record, stale),
+    rulesOk: record.rulesOk,
+    hooksOk: record.hooksOk,
+    gatesRun: record.gatesRun,
+    gatesTotal: record.gatesTotal,
+    blocking: record.blocking,
+    warnings: record.warnings,
+  };
+}
+
+async function gitHooksSlot(root) {
+  const { manifest, exists, error } = await repoContext(root).manifest();
+  if (error) return { error };
+  const state = await readHooksState(root, { declaresGate: (event) => wantsShim(manifest, exists, event) });
+  return {
+    hooksPath: state.current,
+    liveDir: state.liveDir,
+    events: state.installed.map((i) => ({ event: i.event, present: i.present, stale: i.stale })),
+    foreign: state.foreign.length,
+    gates: exists ? { preCommit: manifest?.gates?.preCommit ?? [], prePush: manifest?.gates?.prePush ?? [] } : null,
+  };
+}
+
+/**
+ * Which harnesses will decide a tool call.
+ *
+ * The summary, not the report: `agent-hooks status` owns the detail, including whether a
+ * file drifted from what `install` would write and whether the prompt event is opted
+ * into. What is shared is the definition of "installed" - `installedIn` reads the same
+ * document the hook runs from, so this slot cannot say present about an entry that
+ * `install` did not write.
+ */
+async function agentHooksSlot(root) {
+  const harnesses = [];
+  for (const row of adapters()) {
+    const path = hookPath(row.id);
+    let existing = null;
+    try {
+      existing = await readFile(join(root, path), 'utf8');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (existing === null) {
+      harnesses.push({ id: row.id, path, state: 'absent' });
+      continue;
+    }
+    if (row.file) {
+      harnesses.push({ id: row.id, path, state: 'present' });
+      continue;
+    }
+    let config;
+    try {
+      config = JSON.parse(existing);
+    } catch {
+      harnesses.push({ id: row.id, path, state: 'unreadable' });
+      continue;
+    }
+    if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+      harnesses.push({ id: row.id, path, state: 'unreadable' });
+      continue;
+    }
+    harnesses.push({ id: row.id, path, state: installedIn(row, config).length > 0 ? 'present' : 'absent' });
+  }
+  return {
+    wired: harnesses.filter((h) => h.state === 'present').length,
+    total: harnesses.length,
+    harnesses,
+  };
+}
+
+async function evidenceSlot(root) {
+  const { entries, errors } = await readLedger(root);
+  let tree = null;
+  try {
+    tree = await gitText(root, ['rev-parse', 'HEAD^{tree}']);
+  } catch {
+    // No repository, no commits: there is no tree to have evidence for, and `null`
+    // says that rather than \"no evidence\", which would read as a missing run.
+    tree = null;
+  }
+  return {
+    entries: entries.length,
+    errors: errors.length,
+    headTree: tree,
+    testsRecorded: tree === null ? null : hasTestEvidence(entries, tree),
+  };
+}
+
+async function leasesSlot(root) {
+  const { leases, error } = await readLeases(root);
+  if (error) return { error };
+  const active = activeLeases({ leases });
+  return { active: active.length, paths: active.map((lease) => lease.path) };
+}
+
+async function slicesSlot(root) {
+  const status = await planStatus(root);
+  if (status.error) return { error: status.error };
+  return { ready: status.ready, totals: status.totals };
+}
+
+async function journalSlot(root) {
+  const sets = await listJournalSets(root);
+  return { sets: sets.length, last: sets[0] ?? null };
+}
+
+/**
+ * The repository's state in one document.
+ *
+ * `ok` is the gate's verdict, not the snapshot's: a slot that failed to read is a fact
+ * about this repository (unreadable state is a real condition), and folding it into
+ * `ok` would turn a stale manifest into a failing gate no `sync` can fix.
+ */
+export async function statusSnapshot(root) {
+  const [check, gitHooks, agentHooks, evidence, leases, slices, journal] = await Promise.all([
+    slot(() => checkSlot(root)),
+    slot(() => gitHooksSlot(root)),
+    slot(() => agentHooksSlot(root)),
+    slot(() => evidenceSlot(root)),
+    slot(() => leasesSlot(root)),
+    slot(() => slicesSlot(root)),
+    slot(() => journalSlot(root)),
+  ]);
+  return {
+    ok: (check?.blocking ?? 0) === 0,
+    command: 'status',
+    root,
+    at: Date.now(),
+    head: await currentHead(root),
+    check,
+    gitHooks,
+    agentHooks,
+    evidence,
+    leases,
+    slices,
+    journal,
+  };
+}
+
+function unavailable(label, slot) {
+  return `${label.padEnd(9)}${slot.error}`;
+}
+
+/** The same snapshot, read as a person: one line per slot, and a pointer for the detail. */
+export function renderSnapshot(snapshot) {
+  const lines = [`repo     ${snapshot.root}`];
+  if (snapshot.head !== null) lines.push(`head     ${snapshot.head}`);
+
+  if (snapshot.check === null) lines.push(`check    no cache - run ${CLI} check`);
+  else if (snapshot.check.error) lines.push(unavailable('check', snapshot.check));
+  else lines.push(`check    ${snapshot.check.line}`);
+
+  const hooks = snapshot.gitHooks;
+  if (hooks.error) lines.push(unavailable('githooks', hooks));
+  else {
+    const wired = hooks.events.filter((e) => e.present && !e.stale).length;
+    const foreign = hooks.foreign > 0 ? `, ${hooks.foreign} foreign hook(s)` : '';
+    lines.push(`githooks ${wired}/${hooks.events.length} events wired${foreign}${hooks.hooksPath === null ? ` (git default: ${hooks.liveDir})` : ''}`);
+  }
+
+  const agent = snapshot.agentHooks;
+  if (agent.error) lines.push(unavailable('agenthooks', agent));
+  else lines.push(`agenthooks ${agent.wired}/${agent.total} harnesses wired - ${CLI} agent-hooks status`);
+
+  const evidence = snapshot.evidence;
+  if (evidence.error) lines.push(unavailable('evidence', evidence));
+  else if (evidence.testsRecorded === null) lines.push(`evidence ${evidence.entries} run(s), no head tree to compare`);
+  else lines.push(`evidence ${evidence.entries} run(s), ${evidence.testsRecorded ? 'a test run is recorded for this tree' : 'no test run for this tree'}`);
+
+  const leases = snapshot.leases;
+  if (leases.error) lines.push(unavailable('leases', leases));
+  else lines.push(`leases   ${leases.active} active${leases.paths.length > 0 ? `: ${leases.paths.join(', ')}` : ''}`);
+
+  const slices = snapshot.slices;
+  if (slices.error) lines.push(unavailable('slices', slices));
+  else {
+    const counts = Object.entries(slices.totals).map(([state, count]) => `${count} ${state.toLowerCase()}`);
+    lines.push(`slices   ${slices.ready} ready${counts.length > 0 ? ` - ${counts.join(', ')}` : ''}`);
+  }
+
+  const journal = snapshot.journal;
+  if (journal.error) lines.push(unavailable('journal', journal));
+  else lines.push(`journal  ${journal.sets} set(s)${journal.last === null ? '' : `, last ${journal.last}`}`);
+
+  return lines.join('\n');
+}

package/src/status.mjs

@@ -25,15 +25,12 @@
 //     booleans are stored, never findings, so a huge gate still leaves a
 //     ~200-byte file and a killed `check` never leaves half a document.
 
-import { execFile } from 'node:child_process';
 import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
 
 import { readHooksState, wantsShim } from './compare/hooksstate.mjs';
 import { LOCAL_DIR } from './state.mjs';
-
-const exec = promisify(execFile);
+import { gitText } from './sys/git.mjs';
 
 const CACHE_FILE = join(LOCAL_DIR, 'check.json');
 const CACHE_FILE_LEGACY = '.simt/check.json';
@@ -47,8 +44,7 @@ const CACHE_VERSION = 1;
  */
 export async function currentHead(root) {
   try {
-    const { stdout } = await exec('git', ['rev-parse', 'HEAD'], { cwd: root });
-    return stdout.trim() || null;
+    return await gitText(root, ['rev-parse', 'HEAD']);
   } catch {
     return null;
   }

package/src/sys/git.mjs

@@ -0,0 +1,82 @@
+// The one git runner (Q72).
+//
+// Thirty modules imported `child_process` and grew their own `git()`: some threw, some
+// returned null, some trimmed, some split on NUL, and each of them decided for itself
+// whether `core.quotePath` was the caller's problem. The copies disagreed in ways that
+// only showed up on a path with a non-ASCII byte in it.
+//
+// Three verbs, and the difference between them is the return type, not the flags:
+// `git` answers the raw stdout, `gitText` answers it trimmed or null, and `gitPaths`
+// answers NUL-separated paths. `allowFailure` is explicit because "this repository is not
+// a git repository" is sometimes an answer and sometimes an error, and only the caller
+// knows which.
+
+import { execFile } from 'node:child_process';
+
+/** How much stdout one git call may buffer before the call is refused. */
+const GIT_MAX_BUFFER = 32 << 20;
+
+/** A failed git call, carrying the arguments and git's own stderr.
+ *  `stdout` is kept too: a call that fails part-way (a `diff` in a tree with no HEAD)
+ *  can still have printed, and a caller that salvages the partial output must not lose
+ *  it to the wrap. */
+class GitError extends Error {
+  constructor(args, cause) {
+    const stderr = String(cause?.stderr ?? '').trim();
+    super(`git ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}`);
+    this.name = 'GitError';
+    this.args = args;
+    this.stderr = stderr;
+    this.stdout = cause?.stdout;
+    this.code = cause?.code;
+  }
+}
+
+/**
+ * Run git in `root` and answer stdout.
+ *
+ * `core.quotePath=false` is set on every call so a path with a non-ASCII byte comes back
+ * as itself; the copies that relied on a caller remembering `-z` did not.
+ *
+ * @param {string} root
+ * @param {string[]} args
+ * @param {{allowFailure?: boolean, maxBuffer?: number, input?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {Promise<string|null>} stdout, or null when `allowFailure` and the call failed
+ */
+export function git(
+  root,
+  args,
+  { allowFailure = false, maxBuffer = GIT_MAX_BUFFER, input, env = process.env } = {},
+) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      'git',
+      ['-c', 'core.quotePath=false', ...args],
+      { cwd: root, encoding: 'utf8', maxBuffer, env },
+      (error, stdout, stderr) => {
+        if (error) {
+          if (allowFailure) resolve(null);
+          else reject(new GitError(args, Object.assign(error, { stderr })));
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+    // `execFile` has no `input` option and leaves stdin a pipe: a child like `hash-object
+    // --stdin` waits for an EOF that never comes, so the call hangs rather than fails.
+    if (input !== undefined) child.stdin.end(input);
+  });
+}
+
+/** stdout trimmed, or null when `allowFailure` and the call failed. */
+export async function gitText(root, args, options = {}) {
+  const stdout = await git(root, args, options);
+  return stdout === null ? null : stdout.trim();
+}
+
+/** NUL-separated stdout split into paths. `-z` is added here, so a caller cannot forget it. */
+export async function gitPaths(root, args, options = {}) {
+  const stdout = await git(root, [...args, '-z'], options);
+  if (stdout === null) return null;
+  return stdout.split('\0').filter(Boolean);
+}