simt-dev 0.6.2 → 0.7.0

package/src/output/index.mjs

@@ -144,20 +144,90 @@ export function jsonIndentDefault(pretty = process.stdout.isTTY === true) {
  * the only consumer is a person: the compact document saves them nothing and costs them
  * the diff they were about to read.
  */
+function withSchemaVersion(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && value.schemaVersion === undefined
+    ? { schemaVersion: SCHEMA_VERSION, ...value }
+    : value;
+}
+
+function stringifyJson(value, pretty) {
+  return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}
+
+/**
+ * Shrink a payload to a byte ceiling by emptying its longest arrays first.
+ *
+ * Byte-cutting JSON produces a document that parses or exits non-zero, never both —
+ * `why --json --max-bytes 120` used to exit 0 with half a token on stdout (Q10). An
+ * importer owns nothing here: the trimmed arrays are named in `truncated`, so a reader
+ * knows exactly which list lost how many items, and the document still parses.
+ *
+ * Returns the fitted payload, or null when no array-trimming fits (the caller then
+ * answers with the `MAX_BYTES` error envelope instead).
+ */
+function fitJsonArrays(payload, maxBytes, pretty) {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  const slots = [];
+  const walk = (node, path) => {
+    if (Array.isArray(node)) {
+      if (node.length > 0) slots.push({ node, path, length: node.length });
+      node.forEach((item, i) => walk(item, `${path}[${i}]`));
+    } else if (node !== null && typeof node === 'object') {
+      for (const key of Object.keys(node)) walk(node[key], path === '' ? key : `${path}.${key}`);
+    }
+  };
+  walk(payload, '');
+  if (slots.length === 0) return null;
+  slots.sort((a, b) => b.length - a.length);
+  const candidate = structuredClone(payload);
+  const trimmed = [];
+  const sizeOf = (extra) =>
+    Buffer.byteLength(stringifyJson(extra ? { ...candidate, truncated: extra } : candidate, pretty));
+  const segmentsOf = (path) =>
+    path.split('.').flatMap((part) => {
+      const m = /^(.*?)\[(\d+)\]$/.exec(part);
+      return m ? [m[1], Number(m[2])] : [part];
+    });
+  for (const slot of slots) {
+    const at = segmentsOf(slot.path);
+    let target = candidate;
+    for (let i = 0; i < at.length - 1; i += 1) target = target[at[i]];
+    if (target === null || typeof target !== 'object') continue;
+    target[at[at.length - 1]] = [];
+    trimmed.push({ field: slot.path, omitted: slot.length });
+    const extra = trimmed.length === 1
+      ? { field: trimmed[0].field, omitted: trimmed[0].omitted, limit: maxBytes }
+      : { fields: trimmed, limit: maxBytes };
+    if (sizeOf(extra) <= maxBytes) return { ...candidate, truncated: extra };
+  }
+  return null;
+}
+
 export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = 0 } = {}) {
-  const payload =
-    value !== null && typeof value === 'object' && !Array.isArray(value) && value.schemaVersion === undefined
-      ? { schemaVersion: SCHEMA_VERSION, ...value }
-      : value;
-  const text = `${pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)}\n`;
-  // The same ceiling and the same announcement `emit` applies: a reader who asked for a
-  // bounded answer gets a bounded answer and is told how much is missing, rather than a
-  // half-parsed document it believes is whole.
+  const payload = withSchemaVersion(value);
+  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
+  // document no trimming can fit becomes a `MAX_BYTES` error envelope (Q10, ADR-105).
   if (maxBytes > 0 && Buffer.byteLength(text) > maxBytes) {
-    const slice = Buffer.from(text).subarray(0, maxBytes).toString('utf8');
-    const cut = slice.lastIndexOf('\n');
-    stream.write(cut > 0 ? `${slice.slice(0, cut)}\n` : slice);
-    stream.write(`TRUNCATED ${Buffer.byteLength(text) - maxBytes} bytes omitted, raise maxBytes\n`);
+    const fitted = fitJsonArrays(payload, maxBytes, pretty);
+    if (fitted !== null) {
+      stream.write(`${stringifyJson(fitted, pretty)}\n`);
+      return false;
+    }
+    const envelope = withSchemaVersion({
+      ...(payload !== null && typeof payload === 'object' && !Array.isArray(payload) && typeof payload.command === 'string'
+        ? { command: payload.command }
+        : {}),
+      ok: false,
+      error: {
+        code: 'MAX_BYTES',
+        message: `output exceeded the --max-bytes ceiling of ${maxBytes} bytes`,
+        remedy: 'rerun with --max-bytes 0 for the whole document',
+      },
+      truncated: { omitted: Buffer.byteLength(text) - maxBytes, limit: maxBytes },
+    });
+    stream.write(`${stringifyJson(envelope, pretty)}\n`);
     return false;
   }
   stream.write(text);

package/src/package-version.mjs

@@ -14,9 +14,11 @@
 //     must match: npm pins the node_modules copy for us, but nothing pins a binary, so
 //     the gate compares the running version against the pin and refuses on a mismatch.
 
+import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { MANIFEST_FILE } from './name.mjs';
 
@@ -38,6 +40,52 @@ export function packageVersion() {
   }
 }
 
+/** The directory this package is installed in, whatever resolved the import. */
+function packageRootDir() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+/**
+ * The short commit this checkout is at, or null outside a git checkout (an
+ * installed tarball or wheel has no `.git`). Read-only and best-effort: a
+ * version string must never fail because the VCS is absent (Q05).
+ */
+export function checkoutSha() {
+  try {
+    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: packageRootDir(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return /^[0-9a-f]+$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What `--version` prints: the package version, plus the checkout SHA when run
+ * from a source tree past its tag. A `main` 26 commits past v0.6.2 reporting
+ * bare `0.6.2` is the drift Q05 closes: the number alone claims a release the
+ * bytes are not (Q05).
+ */
+export function describeVersion() {
+  const version = packageVersion();
+  const sha = checkoutSha();
+  if (!sha) return `simt-dev ${version}`;
+  try {
+    const tag = execFileSync('git', ['describe', '--tags', '--exact-match'], {
+      cwd: packageRootDir(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (tag === `v${version}`) return `simt-dev ${version}`;
+  } catch {
+    // Not exactly on the release tag: fall through to the SHA suffix.
+  }
+  return `simt-dev ${version} (${sha})`;
+}
+
 /**
  * Whether a repository has a package.json, i.e. whether it pins simt-dev as a
  * devDependency (npm) or must download the release binary (ADR-098). Async because the render

package/src/packs/manage.mjs

@@ -14,7 +14,8 @@
 // copied in and pinned by digest, never fetched at render time.
 
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
 import { createHash } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
 import { promisify } from 'node:util';
@@ -545,8 +546,14 @@ export async function publishPack(dir, { apply = false } = {}) {
   return { pack: linted.pack, ok: true, published: true, skipped: false, planned, findings };
 }
 
-/** Write scaffold files into a directory that must not already exist. */
-export async function writeScaffold(dir, files) {
+/**
+ * Write scaffold files into a directory that must not already exist.
+ *
+ * `root` is the repository the journal set belongs to — usually the scaffold's
+ * own parent, so `undo` runs where the files live. Recorded (R49) because a
+ * scaffold is repo files like any other write.
+ */
+export async function writeScaffold(dir, files, root = dirname(dir)) {
   try {
     await stat(dir);
     throw new Error(
@@ -555,9 +562,11 @@ export async function writeScaffold(dir, files) {
   } catch (error) {
     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 writeFile(abs, file.text, 'utf8');
+    await journaledWriteFile(root, journal, abs, file.text);
   }
+  await commitJournal(root, 'pack new', journal);
 }

package/src/plan/index.mjs

@@ -20,10 +20,11 @@
 // the file was read. Status and dependency checks never touch it: a 1 MB
 // section that belongs to a later slice is not copied into the index.
 
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { CLI } from '../name.mjs';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
 import { loadFormat } from './template.mjs';
 
 function clean(cell) {
@@ -100,10 +101,16 @@ function sliceKey(path, id) {
  * empty cell is the pipe that closes it. A further empty cell is real: the
  * evidence column is often blank, and stripping every trailing empty would
  * delete it and shift the state into the wrong column.
+ *
+ * A pipe inside a code span is content, not a separator: an evidence cell may
+ * carry a command line with a pipe in it, and splitting there shifts every
+ * later cell left by one (review 0003 Q25). Backticks toggle the span; a
+ * `\|` escape is content in either mode.
  */
 function splitRow(line) {
   const cells = [];
   let current = '';
+  let inCode = false;
   for (let i = 0; i < line.length; i += 1) {
     const char = line[i];
     if (char === '\\' && i + 1 < line.length) {
@@ -111,7 +118,12 @@ function splitRow(line) {
       i += 1;
       continue;
     }
-    if (char === '|') {
+    if (char === '`') {
+      inCode = !inCode;
+      current += char;
+      continue;
+    }
+    if (char === '|' && !inCode) {
       cells.push(current);
       current = '';
       continue;
@@ -596,9 +608,16 @@ export async function planDone(root, id, { sha = null, test = null, state = null
     return { root, id, error: `${id} is no longer on line ${slice.line} of ${slice.docName}`, remedy: `run: ${CLI} plan status` };
   }
 
-  const cells = splitRow(found.lines[found.index]);
-  const width = Math.max(slice.columnCount, slice.stateIdx + 1, slice.evidenceIdx + 1, cells.length);
-  while (cells.length < width) cells.push('');
+  const original = found.lines[found.index];
+  const cells = splitRow(original);
+  if (cells.length !== slice.columnCount) {
+    return {
+      root,
+      id,
+      error: `the row for ${id} has ${cells.length} cells; the table declares ${slice.columnCount}`,
+      remedy: `fix the row in ${slice.docName} — an unescaped pipe splits it — and retry`,
+    };
+  }
   const from = cells[slice.stateIdx] ?? '';
   cells[slice.stateIdx] = replaceState(from, display);
 
@@ -613,14 +632,18 @@ export async function planDone(root, id, { sha = null, test = null, state = null
     evidenceNote = 'no evidence column in this tracker; the sha was not recorded';
   }
 
-  const rebuilt = `| ${cells.join(' | ')} |`;
-  const original = found.lines[found.index];
+  // The rebuilt line keeps the original's ending: a CRLF file must not gain
+  // one LF-terminated line among its CRLF lines (review 0003 Q25).
+  const eol = original.endsWith('\r') ? '\r' : '';
+  const rebuilt = `| ${cells.join(' | ')} |${eol}`;
   const changedCells = splitRow(original).join('\0') !== cells.join('\0');
   const newLine = changedCells ? rebuilt : original;
   const wouldChange = newLine !== original;
   if (wouldChange && !dryRun) {
     found.lines[found.index] = newLine;
-    await writeFile(slice.docPath, found.lines.join('\n'), 'utf8');
+    const journal = [];
+    await journaledWriteFile(root, journal, slice.docPath, found.lines.join('\n'));
+    await commitJournal(root, 'plan', journal);
   }
 
   const apply = `run: ${CLI} plan done ${id}${sha ? ` ${sha}` : ''}${display === format.doneWrite ? '' : ` --state ${JSON.stringify(display)}`}${test ? ` --test ${JSON.stringify(test)}` : ''} --yes`;
@@ -632,6 +655,12 @@ export async function planDone(root, id, { sha = null, test = null, state = null
     line: found.index + 1,
     from,
     to: cells[slice.stateIdx],
+    // The `--diff` sides for the one changed row (plan 0003 R50). The full file
+    // is not carried: one table row is the whole write, and a context-less hunk
+    // over the row says exactly what changed. Captured pre-write, so the diff
+    // is true in preview and in apply alike.
+    beforeLine: original,
+    afterLine: newLine,
     state: format.readState(display),
     wouldChange,
     changed: wouldChange && !dryRun,

package/src/plan/template.mjs

@@ -23,7 +23,7 @@ const KNOWN = new Set(['$comment', 'name', 'directories', 'id', 'columns', 'stat
 const ID_KEYS = new Set(['pattern', 'headers']);
 const COLUMN_KEYS = new Set(['state', 'depends', 'title', 'evidence']);
 const DIRECTORY_KEYS = new Set(['kind', 'word', 'path']);
-const STATE_KEYS = new Set(['id', 'write', 'read', 'satisfies']);
+const STATE_KEYS = new Set(['id', 'write', 'read', 'satisfies', 'role']);
 const DEPENDENCY_KEYS = new Set(['empty', 'separators', 'notes', 'group']);
 const WAVE_KEYS = new Set(['label', 'members']);
 const SECTION_KEYS = new Set(['depth']);
@@ -148,6 +148,7 @@ function compileStates(source, value) {
   const write = new Map();
   const known = new Set();
   const satisfies = new Set();
+  const roles = new Map();
   const order = [];
   const stateNames = [];
   for (let i = 0; i < value.length; i += 1) {
@@ -162,6 +163,13 @@ function compileStates(source, value) {
     }
     if (!Array.isArray(entry.read) || entry.read.length === 0) return bad(source, `${where}.read must list the words that mean this state`);
     if (known.has(entry.id)) return bad(source, `state ${entry.id} is listed twice`);
+    if (entry.role !== undefined && (typeof entry.role !== 'string' || !/^[a-z][a-z0-9-]*$/.test(entry.role))) {
+      return bad(source, `${where}.role must be a lower-case word`);
+    }
+    if (typeof entry.role === 'string') {
+      if (roles.has(entry.role)) return bad(source, `role ${entry.role} is claimed twice`);
+      roles.set(entry.role, entry.write.trim());
+    }
     const display = entry.write.trim();
     const aliases = new Set([entry.id, display.toLowerCase()]);
     for (const alias of entry.read) {
@@ -182,7 +190,7 @@ function compileStates(source, value) {
     else if (entry.satisfies != null && entry.satisfies !== false) return bad(source, `${where}.satisfies must be true or false`);
   }
   if (satisfies.size === 0) return bad(source, 'one state must have satisfies true, or nothing can ever be ready');
-  return { read, write, known, satisfies, order, stateNames };
+  return { read, write, known, satisfies, roles, order, stateNames };
 }
 
 function compile(body, source, root) {
@@ -262,7 +270,7 @@ function compile(body, source, root) {
 
   const byWord = new Map(directories.directories.map((dir) => [dir.word, dir.kind]));
   const doneWrite = body.states.find((entry) => entry.satisfies === true).write.trim();
-  const { read, write } = states;
+  const { read, write, roles } = states;
 
   return {
     format: {
@@ -273,6 +281,12 @@ function compile(body, source, root) {
       order: states.order,
       ready,
       doneWrite,
+      // The display a command moves a row to when work on it starts: the state
+      // carrying the `started` role, or null when no state claims it (review
+      // 0003 Q23). A null here is not an error — the caller falls back to the
+      // in-progress spelling it can read, and `plan done` fails closed on a
+      // word the template never defined.
+      startedWrite: roles.get('started') ?? null,
       stateNames: states.stateNames,
       satisfies: states.satisfies,
       known: states.known,
@@ -292,9 +306,17 @@ function compile(body, source, root) {
       headingRe: new RegExp(`^(#{1,${depth}})\\s+(.*\\S)\\s*$`),
       readState(raw) {
         const plain = String(raw ?? '').replace(/\*\*/g, '').trim().toLowerCase();
+        if (plain === '') return 'unknown';
         if (read.has(plain)) return read.get(plain);
-        const token = plain.split(/[\s(]/)[0];
-        return read.get(token) ?? (token || 'unknown');
+        // A cell may carry a note after the state — "In progress (since Monday)".
+        // The state is the longest alias that prefixes the text: "in progress"
+        // must win over a shorter alias it starts, and a word no state claims
+        // is unknown, not a state (review 0003 Q25).
+        let best = '';
+        for (const alias of read.keys()) {
+          if (alias.length > best.length && plain.startsWith(alias)) best = alias;
+        }
+        return best !== '' ? read.get(best) : 'unknown';
       },
       canonical(input) {
         return write.get(String(input ?? '').trim().toLowerCase()) ?? null;

package/src/plugins.mjs

@@ -24,13 +24,24 @@
 // leaves the machine it was built on. The command says so rather than pretending.
 
 import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readBefore } from './diff.mjs';
 import { hookDocument } from './agenthooks/render.mjs';
 import { desiredRegion } from './projection/rules.mjs';
 import { PACKAGE_NAME, BIN_REL } from './name.mjs';
 
 /** The kinds `simt plugin` builds, in the order the help line names them. */
-export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor'];
+export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor', 'opencode'];
+
+/**
+ * The package this code ships in: the runtime a generated package copies. Resolved
+ * from the module URL, not from the consumer's cwd, so `plugin` built with
+ * `--root <consumer>` still ships this tool rather than the consumer's files (Q03).
+ */
+function packageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
 
 /** Where the runtime copy lands inside a package, relative to the package root. */
 function runtimeDir(kind) {
@@ -60,7 +71,11 @@ function rootFlag(kind) {
 
 /** Where the hooks document lands inside a package, relative to the package root. */
 function hooksPath(kind) {
-  return kind === 'cursor' ? join('.cursor', 'hooks.json') : join('hooks', 'hooks.json');
+  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');
 }
 
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
@@ -71,7 +86,7 @@ const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
  * it is many files; this returns only the handful that are authored here.
  */
 async function packageFiles(kind, { root = process.cwd(), out } = {}) {
-  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const pkg = JSON.parse(await readFile(join(packageRoot(), 'package.json'), 'utf8'));
   const command = `${entryPoint(kind)} agent-hook pre-tool-use --harness ${kind}${rootFlag(kind)}`;
   const files = [];
 
@@ -128,12 +143,21 @@ export async function buildPackage(kind, { root = process.cwd(), out, apply = fa
     throw new Error(`unknown package kind \`${kind}\`; one of: ${PLUGIN_KINDS.join(', ')}`);
   }
 
-  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const pkg = JSON.parse(await readFile(join(packageRoot(), 'package.json'), 'utf8'));
   const files = await packageFiles(kind, { root, out });
   const notes = [
     'the skill registry is workspace data (ADR-061) and is not shipped; run `simt skills index` in the profile to list what a workspace would offer',
   ];
 
+  // The `--diff` before-sides, read before anything is written so the diff is
+  // true in preview and in apply alike (R50). Always captured: the files are a
+  // handful of small generated configs. The runtime copy below is excluded — it
+  // is a mechanical copy of this tool's own sources, not planned content, and
+  // diffing it would reprint the tool into the review.
+  for (const f of files) {
+    f.before = await readBefore(join(out, f.path));
+  }
+
   if (apply) {
     const runtimeTarget = join(out, runtimeDir(kind));
     await mkdir(runtimeTarget, { recursive: true });
@@ -142,10 +166,11 @@ export async function buildPackage(kind, { root = process.cwd(), out, apply = fa
     // dies on the first MCP call: the server reads templates/ and rules/, which a
     // bin+src-only copy leaves behind. The `files` field is the definition of "a working
     // copy of this tool", so it is the set a package ships.
+    const runtimeRoot = packageRoot();
     for (const part of pkg.files) {
-      await cp(join(root, part), join(runtimeTarget, part), { recursive: true });
+      await cp(join(runtimeRoot, part), join(runtimeTarget, part), { recursive: true });
     }
-    await cp(join(root, 'package.json'), join(runtimeTarget, 'package.json'));
+    await cp(join(runtimeRoot, 'package.json'), join(runtimeTarget, 'package.json'));
     for (const f of files) {
       const target = join(out, f.path);
       await mkdir(join(target, '..'), { recursive: true });
@@ -158,7 +183,7 @@ export async function buildPackage(kind, { root = process.cwd(), out, apply = fa
     out,
     apply,
     runtime: { target: runtimeDir(kind), parts: [...pkg.files, 'package.json'] },
-    files: files.map(({ text, ...rest }) => rest),
+    files,
     notes,
   };
 }