simt-dev 0.7.0 → 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;
   }
@@ -92,8 +135,32 @@ export function writeMode(flags) {
  * Truncation is always announced with an explicit line, never a silent ellipsis:
  * an agent that cannot tell a truncated answer from a complete one will guess.
  */
-export function emit(text, { maxBytes = 0, stream = process.stdout } = {}) {
+/**
+ * Answer one command's result on the surface the caller asked for.
+ *
+ * Every command that has both a document and a text report was choosing between them by
+ * hand, in the same five lines, in more than a dozen files - and a command that chose
+ * slightly differently printed a report where a caller had asked for JSON, which is how a
+ * script gets prose (review 0003 Q63).
+ *
+ * The renderer is a thunk because the surface is decided first: a command asked for JSON
+ * must not pay to render text nobody reads, and a caller cannot forget the branch.
+ */
+export function present(payload, renderText, flags) {
+  if (isJson(flags)) {
+    emitJson(payload);
+    return 'json';
+  }
+  emit(renderText());
+  return 'text';
+}
+
+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');
@@ -129,10 +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.
+/** Set the byte ceiling every emit and every document inherits, from `--max-bytes`. */
+export function maxBytesLimit(bytes) {
+  const value = Number(bytes);
+  state().maxBytes = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
 
 export function jsonIndentDefault(pretty = process.stdout.isTTY === true) {
-  prettyDefault = pretty;
+  state().pretty = pretty;
 }
 
 /**
@@ -203,8 +279,127 @@ function fitJsonArrays(payload, maxBytes, pretty) {
   return null;
 }
 
-export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = 0 } = {}) {
-  const payload = withSchemaVersion(value);
+/**
+ * Warnings a run accumulated, carried into the JSON document it prints.
+ *
+ * The same reason stderr is separate from stdout: a caller reading a document cannot
+ * see a note printed beside it. A command that ignored half of what it was asked still
+ * 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).
+ */
+/**
+ * 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).
+/** Set the command path every JSON document will carry, or clear it with null. */
+export function jsonCommand(path) {
+  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).
+/** Collect documents instead of writing them, so the dispatcher can add the exit code. */
+export function jsonCaptureStart() {
+  state().captured = [];
+}
+
+/** The captured documents and a reset, or an empty list when nothing was captured. */
+export function jsonCaptureTake() {
+  const docs = state().captured;
+  state().captured = null;
+  return docs;
+}
+
+/** Record a warning for the document this run prints. */
+export function warn(message) {
+  state().warnings.push(message);
+}
+
+/**
+ * Drop what a previous run in this process recorded.
+ *
+ * The collector is per process and a process can dispatch more than once - the MCP
+ * server and the tests both do. Without this, one command's notice appeared in the
+ * next command's document, which parity between the two surfaces caught (review 0003
+ * Q62).
+ */
+export function clearWarnings() {
+  state().warnings = [];
+}
+
+/** The warnings this run has recorded, in order. */
+export function warnings() {
+  return state().warnings;
+}
+
+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 =
+    state().warnings.length > 0 && value !== null && typeof value === 'object' && !Array.isArray(value) && value.notices === undefined
+      ? { ...value, notices: state().warnings }
+      : value;
+  const stamped =
+    state().command !== null && carried !== null && typeof carried === 'object' && !Array.isArray(carried)
+      ? { ...carried, command: state().command }
+      : carried;
+  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);
   const text = `${stringifyJson(payload, pretty)}\n`;
   // JSON is never byte-truncated: a cut document parses as a lie, and exit 0 calls it
   // true. Arrays shrink with a `truncated` record naming what lost how much, and a
@@ -239,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');
     }
@@ -511,6 +513,23 @@ export async function publishPack(dir, { apply = false } = {}) {
     return { pack: linted.pack, ok: false, published: false, skipped: false, planned: [], findings };
   }
 
+  // A preview is a preview. The registry read below is the one network call in this
+  // command, and running it to print a plan made `pack publish` — a preview by default
+  // — a network operation that failed offline without `--yes` (review 0003 Q58).
+  if (!apply) {
+    return {
+      pack: linted.pack,
+      ok: true,
+      published: false,
+      skipped: false,
+      planned: [
+        `npm view ${pkg}@${pack.version}  (check whether it is already live)`,
+        `npm publish  (in ${dir})`,
+      ],
+      findings,
+    };
+  }
+
   // Idempotent, the way the release twin is: a version that is already live is
   // skipped rather than republished, so a re-run after an interruption continues
   // where it stopped.
@@ -534,9 +553,6 @@ export async function publishPack(dir, { apply = false } = {}) {
   }
 
   const planned = [`npm publish  (in ${dir})`];
-  if (!apply) {
-    return { pack: linted.pack, ok: true, published: false, skipped: false, planned, findings };
-  }
   try {
     await exec('npm', ['publish'], { cwd: dir });
   } catch (error) {
@@ -563,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/packs.mjs

@@ -72,8 +72,26 @@ export async function packDigest(dir, { exclude = [] } = {}) {
     }
     for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
       const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
-      if (entry.isDirectory()) await walk(join(d, entry.name), rel);
-      else if (entry.isFile() && !excluded.has(rel)) files.push(rel);
+      if (entry.isDirectory()) {
+        await walk(join(d, entry.name), rel);
+      } else if (entry.isSymbolicLink()) {
+        // A link is not vendored bytes, and the loader follows it: the old walk skipped
+        // links while the projection read through them, so a rule reached by a link was
+        // projected without being covered by the pin (review 0003 Q58). A link to a
+        // file is hashed through its target, because `readFile` below follows it. A link
+        // to a directory is refused: recursing would let a pack's digest describe a tree
+        // it does not carry.
+        const target = await stat(join(d, entry.name)).catch(() => null);
+        if (target?.isDirectory()) {
+          const error = new Error(
+            `${rel} is a symbolic link to a directory; a pack is vendored bytes, and its digest cannot cover a tree it does not carry`,
+          );
+          error.code = 'PACK_SYMLINK';
+          error.path = rel;
+          throw error;
+        }
+        if (!excluded.has(rel)) files.push(rel);
+      } else if (entry.isFile() && !excluded.has(rel)) files.push(rel);
     }
   };
   await walk(dir);

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';