simt-dev 0.7.1 → 0.8.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);
+}

package/src/{bench/process.mjs → sys/proc.mjs}

@@ -1,13 +1,18 @@
-// One bounded child process, for everything the bench runs (review 0003 Q47).
+// One bounded child process and the environment a child inherits, for everything
+// that runs one (review 0003 Q47, Q72).
 //
-// `child.kill('SIGKILL')` kills the process the bench started and leaves its
+// `child.kill('SIGKILL')` kills the process the caller started and leaves its
 // grandchildren running: an adapter that ran `(sleep 15 &); sleep 60` kept the pipe open
-// and the bench waited 62.6 s against a 2 s timeout, then graded the result. A detached
+// and the caller waited 62.6 s against a 2 s timeout, then graded the result. A detached
 // child is its own process group, so the deadline kills the group, destroys the streams
 // and settles. A run cannot outlive its own deadline, whatever it spawned.
 //
-// Output is bounded so a runaway agent cannot decide the bench's memory: past the cap the
-// oldest chunk is dropped and `truncated` says so, rather than the spawn failing.
+// Output is bounded so a runaway child cannot decide the caller's memory: past the cap
+// the oldest chunk is dropped and `truncated` says so, rather than the spawn failing.
+//
+// This module used to live in `src/bench/` because the bench was its only caller. The
+// bench is not the only thing that runs a child it does not trust, and a second copy of
+// the deadline logic is a second way for a run to outlive its deadline.
 
 import { spawn } from 'node:child_process';
 
@@ -126,3 +131,21 @@ export function spawnBounded(
     child.stdin?.end(input ?? undefined);
   });
 }
+
+/**
+ * What a spawned child is allowed to inherit from the operator's shell.
+ *
+ * Three bench modules grew this identically, and the differences between what a child
+ * needs and what the shell carries are the whole point: `SIMT_DEV_WORKSPACE` is forced
+ * off so a child cannot resolve THIS repository's workspace, and the `NODE_TEST*`
+ * variables are dropped because they steer `node --test` at a test directory the child
+ * does not have. Nothing here names a credential or a state directory: those come from
+ * the caller's own `extra`.
+ */
+export function sanitizedEnv(extra = {}) {
+  const env = { ...process.env, SIMT_DEV_WORKSPACE: 'off', ...extra };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('NODE_TEST')) delete env[key];
+  }
+  return env;
+}