simt-dev 0.7.1 → 0.8.0

package/src/output/index.mjs

@@ -4,9 +4,49 @@
 // Same data, different rendering. Nothing here emits ANSI, prompts, spinners or
 // boxes, because a prompt is a hang for an agent and a spinner is noise in a log.
 //
-// See docs/plans/0002-simt-dev-cli.md section 6.
+// See docs/research/0002-simt-dev-cli.md section 6.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 import { CLI } from '../name.mjs';
+
+/**
+ * One call's presentation state (review 0003 Q63, Q65).
+ *
+ * This was seven module-level `let`s - the JSON failure mode, the indent default, the byte
+ * ceiling, the accumulated notices, the canonical command, the capture, the sink - and a
+ * process could hold only one of each. `dispatch` and the tests both run more than one
+ * command in a process, and an MCP server runs them concurrently: the second run's ceiling,
+ * notices and command path landed in the first run's document, which is a document
+ * describing an invocation that did not produce it.
+ *
+ * Async-local rather than threaded through a parameter: `emit` is called by seventy command
+ * modules that have no context to pass, and changing every signature is the rewrite that
+ * never lands. A store is per call and inherited by everything that call awaits.
+ */
+const stores = new AsyncLocalStorage();
+
+/** What a run that never opened a store gets: the process defaults before any flag. */
+const processState = () => ({
+  jsonFailure: false,
+  pretty: process.stdout.isTTY === true,
+  maxBytes: 0,
+  warnings: [],
+  command: null,
+  captured: null,
+  sink: null,
+});
+
+const fallback = processState();
+
+function state() {
+  return stores.getStore() ?? fallback;
+}
+
+/** Give `body` its own presentation state, so two calls in one process cannot collide. */
+export function withOutputState(body) {
+  return stores.run(processState(), body);
+}
 /** Stable machine codes. A non-zero exit always carries one of these. */
 export const EXIT = {
   OK: 0,
@@ -40,10 +80,8 @@ const REMEDY = {
  * The default answers "plain text" because that is what every run before the flags
  * were parsed is, and those runs happen before anybody could have asked.
  */
-let jsonFailure = false;
-
 export function jsonFailMode(on = false) {
-  jsonFailure = on;
+  state().jsonFailure = on;
 }
 
 /**
@@ -56,7 +94,12 @@ export function fail(message, code = EXIT.FAIL, remedy) {
   // a reader in a consumer repo got a remedy naming a file that does not exist
   // where they are. Every remedy here is something the reader can run.
   const resolved = remedy ?? REMEDY[code] ?? `run: ${CLI} --help`;
-  if (jsonFailure) {
+  // A library caller asked for a result, not a line on a terminal it does not own.
+  if (state().sink !== null) {
+    state().sink.error = { message, remedy: resolved, exitCode: code };
+    return code;
+  }
+  if (state().jsonFailure) {
     emitJson({ ok: false, error: message, remedy: resolved, exitCode: code });
     return code;
   }
@@ -112,8 +155,12 @@ export function present(payload, renderText, flags) {
   return 'text';
 }
 
-export function emit(text, { maxBytes = maxBytesDefault, stream = process.stdout } = {}) {
+export function emit(text, { maxBytes = state().maxBytes, stream = process.stdout } = {}) {
   const body = text.endsWith('\n') ? text : `${text}\n`;
+  if (state().sink !== null) {
+    state().sink.text.push(fitText(body, maxBytes));
+    return true;
+  }
   const bytes = Buffer.byteLength(body);
   if (maxBytes > 0 && bytes > maxBytes) {
     const slice = Buffer.from(body).subarray(0, maxBytes).toString('utf8');
@@ -149,23 +196,19 @@ export const SCHEMA_VERSION = 1;
  * important. The default answers "is a person reading", which is the right answer
  * before anybody sets it.
  */
-let prettyDefault = process.stdout.isTTY === true;
-
 // The byte ceiling is one flag with one reader: the envelope. Commands used to pass
 // `flags.maxBytes ?? 0` at seventy-eight call sites, which is seventy-eight chances to pass
 // a different number, or to forget and answer past the ceiling the caller set (review 0003
 // Q65). A ceiling of zero or a value that is not a number is no ceiling, the same way the
 // flag itself is read.
-let maxBytesDefault = 0;
-
 /** Set the byte ceiling every emit and every document inherits, from `--max-bytes`. */
 export function maxBytesLimit(bytes) {
   const value = Number(bytes);
-  maxBytesDefault = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+  state().maxBytes = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }
 
 export function jsonIndentDefault(pretty = process.stdout.isTTY === true) {
-  prettyDefault = pretty;
+  state().pretty = pretty;
 }
 
 /**
@@ -244,39 +287,79 @@ function fitJsonArrays(payload, maxBytes, pretty) {
  * has to succeed or fail the same way, so the note belongs IN the result, and the text
  * mode keeps the stderr line it already had (review 0003 Q62).
  */
-let accumulated = [];
+/**
+ * The output sink for a library call, or null for a process (review 0003 Q63).
+ *
+ * `run(command, input)` answers with the text, the documents, the notes and the failure a
+ * command produced instead of writing them. The alternative - threading a `result` return
+ * through seventy command modules - is the rewrite that never finishes, and the printing
+ * commands have no return value to thread: they `return EXIT.OK` after calling `emit`.
+ *
+ * A sink is per call and never nested. The dispatcher keeps its own JSON capture below and
+ * is not this: a sink answers "what did the command produce", the capture answers "hold the
+ * document until the exit code exists".
+ */
+/** Collect a command's output instead of writing it, and answer with what it produced. */
+export async function withSink(body) {
+  if (state().sink !== null) throw new Error('an output sink is already open');
+  const collecting = { text: [], documents: [], notes: [], error: null };
+  state().sink = collecting;
+  try {
+    const code = await body();
+    return {
+      code: code ?? EXIT.OK,
+      text: collecting.text.join(''),
+      documents: collecting.documents,
+      notes: collecting.notes,
+      error: collecting.error,
+    };
+  } finally {
+    state().sink = null;
+  }
+}
+
+/**
+ * The same cut `emit` makes on a stream, applied to a string: the ceiling is a promise
+ * whichever surface reads it, and a library caller that got bytes past the limit it asked
+ * for would be paying for what the flag exists to refuse.
+ */
+function fitText(body, maxBytes) {
+  const bytes = Buffer.byteLength(body);
+  if (maxBytes <= 0 || bytes <= maxBytes) return body;
+  const slice = Buffer.from(body).subarray(0, maxBytes).toString('utf8');
+  const cut = slice.lastIndexOf('\n');
+  return cut > 0
+    ? `${slice.slice(0, cut)}\nTRUNCATED ${bytes - maxBytes} bytes omitted, rerun with --max-bytes 0\n`
+    : `${slice}TRUNCATED ${bytes - maxBytes} bytes omitted, rerun with --max-bytes 0\n`;
+}
 
 // The path the dispatcher resolved. A command should not restate it: the ones that did
 // restated it wrongly (`plugin` printed `plugin claude`, `sync` printed `sync --check`),
 // and a document whose `command` disagrees with the argv that produced it is worse than
 // one with no `command` at all (review 0003 Q65).
-let canonicalCommand = null;
-
 /** Set the command path every JSON document will carry, or clear it with null. */
 export function jsonCommand(path) {
-  canonicalCommand = path ?? null;
+  state().command = path ?? null;
 }
 
 // A document cannot name the exit code before the command has returned one. The
 // dispatcher captures what a command emits, then writes it once with the code attached;
 // writing first is how `ok: false` shipped alongside exit 0 (review 0003 Q65).
-let captured = null;
-
 /** Collect documents instead of writing them, so the dispatcher can add the exit code. */
 export function jsonCaptureStart() {
-  captured = [];
+  state().captured = [];
 }
 
 /** The captured documents and a reset, or an empty list when nothing was captured. */
 export function jsonCaptureTake() {
-  const docs = captured;
-  captured = null;
+  const docs = state().captured;
+  state().captured = null;
   return docs;
 }
 
 /** Record a warning for the document this run prints. */
 export function warn(message) {
-  accumulated = [...accumulated, message];
+  state().warnings.push(message);
 }
 
 /**
@@ -288,28 +371,32 @@ export function warn(message) {
  * Q62).
  */
 export function clearWarnings() {
-  accumulated = [];
+  state().warnings = [];
 }
 
 /** The warnings this run has recorded, in order. */
 export function warnings() {
-  return accumulated;
+  return state().warnings;
 }
 
-export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = maxBytesDefault } = {}) {
+export function emitJson(value, { stream = process.stdout, pretty = state().pretty, maxBytes = state().maxBytes } = {}) {
   // `notices`, not `warnings`: `status` already reports a warning COUNT under that key,
   // and a document cannot mean two things by one name. The collision is named here
   // rather than bent into either shape (review 0003 Q62).
   const carried =
-    accumulated.length > 0 && value !== null && typeof value === 'object' && !Array.isArray(value) && value.notices === undefined
-      ? { ...value, notices: accumulated }
+    state().warnings.length > 0 && value !== null && typeof value === 'object' && !Array.isArray(value) && value.notices === undefined
+      ? { ...value, notices: state().warnings }
       : value;
   const stamped =
-    canonicalCommand !== null && carried !== null && typeof carried === 'object' && !Array.isArray(carried)
-      ? { ...carried, command: canonicalCommand }
+    state().command !== null && carried !== null && typeof carried === 'object' && !Array.isArray(carried)
+      ? { ...carried, command: state().command }
       : carried;
-  if (captured !== null) {
-    captured.push({ value: stamped });
+  if (state().sink !== null) {
+    state().sink.documents.push(withSchemaVersion(stamped));
+    return true;
+  }
+  if (state().captured !== null) {
+    state().captured.push({ value: stamped });
     return true;
   }
   const payload = withSchemaVersion(stamped);
@@ -347,5 +434,9 @@ export function emitJson(value, { stream = process.stdout, pretty = prettyDefaul
  * diagnostics that accompany a real result, never for the result itself.
  */
 export function note(message, { stream = process.stderr } = {}) {
+  if (state().sink !== null) {
+    state().sink.notes.push(message);
+    return;
+  }
   stream.write(`${message}\n`);
 }

package/src/packs/manage.mjs

@@ -15,7 +15,8 @@
 
 import { execFile } from 'node:child_process';
 import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
+import { readBefore } from '../diff.mjs';
 import { createHash } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
 import { promisify } from 'node:util';
@@ -23,6 +24,7 @@ import { promisify } from 'node:util';
 import { PACK_DIR, packDigest, packNameProblem } from '../packs.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { parseFrontmatter } from '../text/frontmatter.mjs';
 
 const exec = promisify(execFile);
 
@@ -311,10 +313,10 @@ export async function lintPack(dir, { requireMeasured = false, declared = null }
       fail(rel, 'pack-rule-unreadable', 'the file cannot be read', 'restore it or remove it from the pack');
       continue;
     }
-    const frontmatter = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+    const { front } = parseFrontmatter(text);
     // Multiline: the id sits on its own line inside the frontmatter block, and
     // without `m` the anchors hold the whole block instead of the line.
-    const id = frontmatter === null ? null : /^simt-id:\s*(.+?)\s*$/m.exec(frontmatter[1])?.[1] ?? null;
+    const id = front === null ? null : /^simt-id:\s*(.+?)\s*$/m.exec(front)?.[1] ?? null;
     if (id === null) {
       fail(rel, 'pack-rule-without-id', 'the rule has no `simt-id`: without one nothing selects it and nothing explains it', 'give the rule a `simt-id` in its frontmatter');
     }
@@ -577,10 +579,14 @@ export async function writeScaffold(dir, files, root = dirname(dir)) {
     if (error?.message?.startsWith('refusing to scaffold')) throw error;
   }
   const journal = [];
-  for (const file of files) {
-    const abs = join(dir, file.path);
-    await mkdir(dirname(abs), { recursive: true });
-    await journaledWriteFile(root, journal, abs, file.text);
-  }
-  await commitJournal(root, 'pack new', journal);
+  await applyPlan(
+    root,
+    await Promise.all(
+      files.map(async (file) => {
+        const abs = join(dir, file.path);
+        return change({ path: abs, before: await readBefore(abs), after: file.text, owner: 'pack new', reason: 'the pack is being created' });
+      }),
+    ),
+    { mode: { apply: true }, label: 'pack new' },
+  );
 }

package/src/plan/index.mjs

@@ -3,7 +3,7 @@
 // An agent resuming a long plan should read one slice, not the document. Which
 // directories are read, which columns count, and which words count as done are
 // the repository's template (src/plan/template.mjs). The tracker template
-// delivered with the tool reads docs/plans and docs/reviews and treats `done`
+// delivered with the tool reads docs/plans, docs/research and docs/reviews and treats `done`
 // as complete.
 // A dependency may name another document (`review 0002 S41`) or one of its
 // waves (`review 0002 Wave 0`). Ids that follow a document prefix stay in that

package/src/plugins.mjs

@@ -29,10 +29,16 @@ import { fileURLToPath } from 'node:url';
 import { readBefore } from './diff.mjs';
 import { hookDocument } from './agenthooks/render.mjs';
 import { desiredRegion } from './projection/rules.mjs';
+import { harnessPlugins } from './harness/records.mjs';
 import { PACKAGE_NAME, BIN_REL } from './name.mjs';
 
+// The plugin layouts, as records (Q71): where each kind's runtime, entry point and hooks
+// document land. A new kind is a new record, not a branch in each helper below.
+const PLUGINS = harnessPlugins();
+const pluginOf = (kind) => PLUGINS.find((r) => r.id === kind);
+
 /** The kinds `simt plugin` builds, in the order the help line names them. */
-export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor', 'opencode'];
+export const PLUGIN_KINDS = PLUGINS.map((r) => r.id);
 
 /**
  * The package this code ships in: the runtime a generated package copies. Resolved
@@ -45,37 +51,37 @@ function packageRoot() {
 
 /** Where the runtime copy lands inside a package, relative to the package root. */
 function runtimeDir(kind) {
-  return kind === 'cursor' ? join('.cursor', 'simt') : '.';
+  return pluginOf(kind).runtimeDir;
 }
 
 /** The entry point a package's config names: its own copy of the runtime, not PATH. */
 function entryPoint(kind) {
-  const bin = join(runtimeDir(kind), BIN_REL);
+  const { runtimeDir: dir, rootVar } = pluginOf(kind);
+  const bin = join(dir, BIN_REL);
   // The vendor's own variables must survive as literal text in the generated config, so
   // they are escaped here: an unescaped ${...} would interpolate a JS binding that does
   // not exist and ship the string "undefined" into the package.
-  if (kind === 'claude') return `node "\${CLAUDE_PLUGIN_ROOT}/${bin}"`;
-  if (kind === 'gemini') return `node "\${extensionPath}/${bin}"`;
+  if (rootVar) return `node "\${${rootVar}}/${bin}"`;
   // Cursor runs from the repository root, so a relative path is the honest one.
   return `node ${bin}`;
 }
 
 /** The project root a package's hook resolves against, from the vendor's env var. */
 function rootFlag(kind) {
-  if (kind === 'claude') return ` --root "$CLAUDE_PROJECT_DIR"`;
-  if (kind === 'cursor') return ` --root "$CURSOR_PROJECT_DIR"`;
-  // Gemini documents no project-dir env var, but its base input carries cwd, which the
-  // adapter reads; passing a flag the vendor never sets would only expand to "".
-  return '';
+  const { projectVar } = pluginOf(kind);
+  if (!projectVar) {
+    // Gemini documents no project-dir env var, but its base input carries cwd, which the
+    // adapter reads; passing a flag the vendor never sets would only expand to "".
+    return '';
+  }
+  return ` --root "$${projectVar}"`;
 }
 
-/** Where the hooks document lands inside a package, relative to the package root. */
+/** Where the hooks document lands inside a package, relative to the package root.
+ *  OpenCode is the one whose document is a file the tool loads whole (its root
+ *  `server` file) rather than a hooks config to merge. */
 function hooksPath(kind) {
-  if (kind === 'cursor') return join('.cursor', 'hooks.json');
-  // OpenCode loads a local plugin directory's root `server` file as the plugin, so the
-  // generated document is that file at the root rather than a hooks config to merge.
-  if (kind === 'opencode') return 'server.js';
-  return join('hooks', 'hooks.json');
+  return pluginOf(kind).hooksPath;
 }
 
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;

package/src/prbody.mjs

@@ -12,18 +12,15 @@
 // falls back to the working-tree diff against HEAD: a report that refused
 // without a base would be useless on a repository with a single branch.
 
-import { execFile } from 'node:child_process';
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
 
 import { readLedger, treeId } from './ledger/index.mjs';
 import { readCheckCache } from './status.mjs';
 import { readManifest } from './projection/manifest.mjs';
-import { splitFrontmatter } from './memory/decide.mjs';
+import { parseFrontmatter } from './text/frontmatter.mjs';
 import { decisionsDir } from './decisions/dir.mjs';
-
-const exec = promisify(execFile);
+import { git, gitText } from './sys/git.mjs';
 
 /**
  * The ref the body diffs against: the override when given, else the first
@@ -33,7 +30,7 @@ const exec = promisify(execFile);
 async function resolveBase(root, override = null) {
   if (override !== null && override !== undefined && String(override) !== '') {
     try {
-      await exec('git', ['rev-parse', '--verify', '--quiet', `${override}^{commit}`], { cwd: root });
+      await git(root, ['rev-parse', '--verify', '--quiet', `${override}^{commit}`]);
       return { base: String(override), error: null };
     } catch {
       return { base: null, error: `unknown base ${override}` };
@@ -41,7 +38,7 @@ async function resolveBase(root, override = null) {
   }
   for (const candidate of ['origin/main', 'main', 'origin/master', 'master']) {
     try {
-      await exec('git', ['merge-base', 'HEAD', candidate], { cwd: root });
+      await git(root, ['merge-base', 'HEAD', candidate]);
       return { base: candidate, error: null };
     } catch {
       // Not present or shares no history; the next candidate may.
@@ -66,8 +63,7 @@ async function changedPaths(root, base) {
   };
   if (base !== null) {
     try {
-      const { stdout } = await exec('git', ['diff', '--name-only', `${base}...HEAD`], {
-        cwd: root,
+      const stdout = await gitText(root, ['diff', '--name-only', `${base}...HEAD`], {
         maxBuffer: 16 << 20,
       });
       add(stdout);
@@ -81,7 +77,7 @@ async function changedPaths(root, base) {
     ['ls-files', '--others', '--exclude-standard'],
   ]) {
     try {
-      const { stdout } = await exec('git', args, { cwd: root, maxBuffer: 16 << 20 });
+      const stdout = await gitText(root, args, { maxBuffer: 16 << 20 });
       add(stdout);
     } catch {
       // Not a repository, or no commit yet: the body reports the absence.
@@ -113,7 +109,7 @@ async function changedDecisions(root, paths) {
     let status = 'unknown';
     try {
       const text = await readFile(join(root, name), 'utf8');
-      const { body } = splitFrontmatter(text);
+      const { body } = parseFrontmatter(text);
       const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? id;
       title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim() || id;
       status = /^Status:\s*(.+)$/im.exec(body)?.[1].trim() ?? 'unknown';