geneseed 3.13.0 → 3.15.0

package/js/loop/state.mjs

@@ -43,9 +43,9 @@ import { iterationLoop, ENGINE_MAX_ITERATIONS } from './graph.mjs';
 
 const BEGIN = '<!-- loop-state:begin -->';
 const END = '<!-- loop-state:end -->';
-export const VERIFY_COMMAND = 'git add -A && git diff --cached --numstat | geneseed loop score --diff';
+const VERIFY_COMMAND = 'git add -A && git diff --cached --numstat | geneseed loop score --diff';
 export const LOOP_FILE = 'LOOP.md';
-export const LOOP_FILE_TMP = `${LOOP_FILE}.tmp`;
+const LOOP_FILE_TMP = `${LOOP_FILE}.tmp`;
 const slash = (p) => String(p).replaceAll('\\', '/');
 
 export function renderLoopFile(state) {
@@ -101,7 +101,11 @@ export function parseLoopFile(text) {
 const head = (state) => iterationLoop(state.graph).nodes[0];
 const fmt = (n) => Number(n).toFixed(1);
 
-/** `contracts`: extra globs (`loop init --contracts`), appended after the graph's own. */
+/**
+ * `contracts`: extra globs (`loop init --contracts`), appended after the graph's own. Every
+ * field the engine ever writes is listed here, `gateAmends` included (`decideGate` still reads
+ * it with `?.`, for a LOOP.md written before it was listed).
+ */
 export function initState({ title, requirement, graph, preset = DEFAULT_PRESET, contracts = [] }) {
   if (!Object.hasOwn(PRESETS, preset)) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
   const loop = iterationLoop(graph);
@@ -111,7 +115,7 @@ export function initState({ title, requirement, graph, preset = DEFAULT_PRESET,
     iteration: loop.nodes.includes(graph.start) ? 1 : 0,
     card: null, validated: false, pendingVerify: false, closing: false, counters: {},
     resplit: false, emptyStreak: 0, snapshot: '', visited: [], tests: 'n/a', current: {},
-    notes: [], history: [],
+    notes: [], history: [], gateAmends: {},
   };
   if (preset === 'prudent') { state.status = 'awaiting'; state.awaiting = { kind: 'launch' }; }
   return state;
@@ -127,12 +131,14 @@ function resetUnit(state) {
   state.current = {}; state.tests = 'n/a';
 }
 
+/** The soft-decision iterations of `state.history` — what the end-of-run summary and the
+ * registry's Active-tab row both call `review`, so the two read the same fields. */
+export function reviewOf(state) {
+  return state.history.filter((h) => h.decision === 'soft').map((h) => ({ iteration: h.iteration, intent: h.intent }));
+}
+
 function summary(state) {
-  return {
-    iterations: state.history.length,
-    review: state.history.filter((h) => h.decision === 'soft').map((h) => ({ iteration: h.iteration, intent: h.intent })),
-    notes: state.notes,
-  };
+  return { iterations: state.history.length, review: reviewOf(state), notes: state.notes };
 }
 
 export function trailers(state) {
@@ -296,13 +302,31 @@ function filterPorcelain(porcelain) {
 
 // Setup work (iteration 0, graph.start outside the iteration loop) is its own unit; rejecting
 // it has nowhere to retry back into, so it stops the loop instead of looping to the head.
+// Iteration 0 alone says so: `initState` starts at 0 only when graph.start is outside the
+// iteration loop, and `iteration` only ever counts up from there.
 function isSetupUnit(state) {
-  return state.iteration === 0 && !iterationLoop(state.graph).nodes.includes(state.graph.start);
+  return state.iteration === 0;
+}
+
+const isStringList = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+// A card arrives from the model as JSON (`record --card`), so its shape is checked before
+// anything is stored: a string `writeSet` stored here only throws later, inside `score --diff`,
+// with `pendingVerify` already set — and `score --declared` refuses while that is set, so
+// nothing could get the loop moving again.
+function cardProblem(card) {
+  if (typeof card !== 'object' || Array.isArray(card)) return 'the card must be a JSON object';
+  if (!isStringList(card.actions)) return "the card's actions must be a list of strings";
+  if (!isStringList(card.writeSet)) return "the card's writeSet must be a list of strings";
+  if (card.intent != null && typeof card.intent !== 'string') return "the card's intent must be a string";
+  return null;
 }
 
 export function recordOutcome(state, bricks, outcome, { card = null, porcelain = null, note = '' } = {}) {
   assertRunning(state);
   if (state.pendingVerify) throw new Error('the iteration is closed: run `geneseed loop score --diff` first');
+  const problem = card === null ? null : cardProblem(card);
+  if (problem) throw new Error(problem);
   const from = state.node;
   const brick = bricks.get(from);
   if (!brick) throw new Error(`no brick named ${from} in the catalogue`);
@@ -323,7 +347,7 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
   // `fail` findings) — pushed before the transition below, so it lands in `notes` even when
   // this call closes the unit, re-splits, or stops the loop. `notes` is never reset mid-run
   // (only `exhaust`'s own push and `decideAwaiting` add to it otherwise), so it survives
-  // `resetUnit`/`finishUnit` the same way the research's fact 1 says a card does not.
+  // `resetUnit`/`finishUnit` — which a card does not: `resetUnit` clears it.
   if (note) state.notes.push(`iteration ${state.iteration} (${from}): ${note}`);
   state.visited.push(from);
 

package/js/maintain/memory.mjs

@@ -17,12 +17,11 @@
  *     beside the cwd, then the global config dir — with `--memory` as the explicit override.
  *     `status` prints the answer of that same resolver, so the two agree about which store
  *     is "the" store.
- *   * THE RESERVED-NAME CHECK IS CASE-INSENSITIVE, WHICH THE ENDPOINT'S IS NOT. It compares
- *     `MEMORY` and `README` exactly. On a case-insensitive filesystem — which is every
- *     Windows install and the default macOS one — `rm memory` then resolves to the index
- *     file, passes the guard, and deletes the thing the agent reads at session start. This
- *     is a NARROWING of what the endpoint accepts, on a destructive path, and it is the one
- *     divergence in this file that is not about resolution.
+ *   * THE RESERVED-NAME CHECK IS CASE-INSENSITIVE, and the web endpoints use this one. On a
+ *     case-insensitive filesystem — every Windows install and the default macOS one — an
+ *     exact `MEMORY`/`README` compare let `rm memory` resolve to the index file, pass the
+ *     guard, and delete the thing the agent reads at session start. The endpoint once had
+ *     that exact compare; it now calls `memoryDelete` from here.
  *
  * `memoryDropIndex` is the hook module's, not a copy: writing the fact and unwriting its
  * index line are two halves of one format, and the half that writes lives there.
@@ -30,7 +29,7 @@
 import { readdirSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
-import { memoryDropIndex } from '../hosts/hooks.mjs';
+import { memoryDropIndex } from '../hosts/memory-files.mjs';
 import { resolveMemoryDir } from '../hosts/hosts.mjs';
 import { printOut, printErr, isFile } from '../lib/fs.mjs';
 

package/js/maintain/migrate.mjs

@@ -3,9 +3,10 @@
  *
  * P10d, AND IT IS NOT A PORT. Every other module here reproduces a Python original byte for
  * byte; this verb is new behaviour on both sides, written twice in the same change so that
- * `tests/harness_golden.py` — a CROSS-IMPLEMENTATION gate — has a reference side at all. A
- * Node-only verb would have nothing to compare against, and `test_every_entry_verb_is_a_real_
- * harness_subcommand` plus `test_the_matrix_covers_every_verb_it_claims` would both fail it.
+ * the former Python CLI matrix — a CROSS-IMPLEMENTATION gate — had a reference side at all. A
+ * Node-only verb would have had nothing to compare against, and that suite's `test_every_entry_
+ * verb_is_a_real_harness_subcommand` plus `test_the_matrix_covers_every_verb_it_claims` would
+ * both have failed it.
  *
  * WHAT IT IS NOT: `rebuild-all`. That was the first answer and it was checked before being
  * discarded, because the re-emit really is the same engine and is reused rather than rewritten
@@ -35,17 +36,14 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:
 import path from 'node:path';
 
 import { main as driverMain } from '../build/driver.mjs';
-import { PACK_ORDER, ROOT } from '../build/source.mjs';
+import { ROOT } from '../build/source.mjs';
+import { CLAUDE_STYLE } from '../hosts/hosts.mjs';
+import { EMIT_HOST_SCOPE, installState, installTargets, readMaybe } from '../hosts/installs.mjs';
+import { installProfile } from '../build/generate.mjs';
 import {
-  EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
-  footprintOfDir, installState, installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
-  trustOfDir,
-} from '../hosts/installs.mjs';
-import { DEFAULT_EMIT, setupBuildArgs } from '../build/generate.mjs';
-import { DEFAULT_PRESET } from '../loop/score.mjs';
-import {
-  autostartPaths, autostartStale, hookShimPath, migrateShape, readJsonc, shimHome,
-} from '../hosts/settings.mjs';
+  autostartPaths, autostartStale, hookShimPath, migrateShape, shimHome,
+} from '../hosts/shim.mjs';
+import { loadJsonObject } from '../hosts/settings.mjs';
 import { writeText, printOut, printErr } from '../lib/fs.mjs';
 
 /** Every emit name the generator answers to — the set an unrecognised marker is NOT in. */
@@ -61,21 +59,20 @@ const KNOWN_EMITS = new Set(EMIT_HOST_SCOPE.keys());
  * host-parity rule asks for.
  */
 function hookSettingsFile(root, host, scope) {
-  if (!['claude', 'bob', 'openclaude'].includes(host)) return null;
+  if (!CLAUDE_STYLE.includes(host)) return null;
   const name = scope === 'project' && host !== 'bob' ? 'settings.local.json' : 'settings.json';
   return path.join(root, name);
 }
 
 /** Every hook command string in a settings file, or [] when it cannot be read or parsed. */
 function hookCommandsOf(file) {
-  // `readJsonc`, NOT `JSON.parse`. A hand-edited settings.json with comments and a trailing
-  // comma is the one shape no machine in this project writes, and strict JSON rejects it —
+  // `loadJsonObject` (JSONC), NOT `JSON.parse`. A hand-edited settings.json with comments and a
+  // trailing comma is the one shape no machine in this project writes, and strict JSON rejects it —
   // which would classify a wired install as `none` and make `migrate` skip the machine
   // silently. `mergeClaudeSettings` already reads through comments for exactly this reason.
   // Found by the JSONC corpus fixture; a generated fixture would have hidden it.
-  let loaded;
-  try { [loaded] = readJsonc(readFileSync(file, 'utf8')); } catch { return []; }
-  if (!loaded || typeof loaded !== 'object') return [];
+  const { state, data: loaded } = loadJsonObject(file);
+  if (state !== 'ok') return [];
   const hooks = loaded.hooks;
   if (!hooks || typeof hooks !== 'object') return [];
   const out = [];
@@ -210,21 +207,13 @@ export function cmdMigrate(args = {}) {
     try { rmSync(stash, { recursive: true, force: true }); } catch { /* nothing to undo */ }
   };
 
-  // Step 3 — re-emit, in each install's OWN six values. Same reads as `cmdRebuildAll`, and
-  // the pack selection is the sixth: leaving it out re-emitted a narrowed install at whatever
-  // `harness.config.json` said, which WIDENS a constitution its owner had cut down (and, the
-  // other way, can strip the consent gate). `null` — a pre-marker carrier, which on a MIGRATION
-  // is the common case and not the rare one — resolves to ALL packs through
-  // `doctrinesForBuild`, never to `harness.config.json`, which is what makes it fail-closed.
+  // Step 3 — re-emit, in each install's OWN values: `installProfile`, the one reading
+  // `rebuild-all` and `status` share. This loop hand-copied it once and drifted twice — it
+  // passed the excluded rules as `null` (re-admitting every rule an owner switched off,
+  // `process 5` among them) and dropped `--config-dir`, so a global found through
+  // `CLAUDE_CONFIG_DIR`/`OPENCODE_CONFIG_DIR` re-emitted into the DEFAULT dir instead.
   for (const r of rows) {
-    const marker = r.marker && (EMIT_HOST_SCOPE.get(r.marker) ?? ['', ''])[0] === r.host
-      ? r.marker : '';
-    const emit = marker || DEFAULT_EMIT.get(`${r.host} ${r.scope}`) || 'opencode-global';
-    const theme = themeOfDir(r.root) || defaultTheme();
-    const out = r.scope === 'global' ? null : r.root;
-    const argv = setupBuildArgs(theme, emit, out, out, footprintOfDir(r.root),
-      postureOfDir(r.root) || defaultPosture(), modeOfDir(r.root) || defaultMode(),
-      doctrinesForBuild(r.root), PACK_ORDER, null, trustOfDir(r.root) || DEFAULT_PRESET);
+    const { emit, theme, argv } = installProfile(r.host, r.scope, r.root);
     const label = `${r.host}:${r.scope} (${r.root})`;
     printOut(`[migrate] re-emitting ${label}: theme=${theme} emit=${emit}\n`);
     let rc = 1;

package/js/maintain/setup.mjs

@@ -31,17 +31,17 @@
  * and a cell's stdin is a pipe. So the whole wizard is unreachable from the acceptance
  * matrix in the same way `_confirm` was in P5h — except that here it is not one branch, it
  * is the verb. The `setup/*` cells therefore gate the REFUSAL, absolutely and on both sides,
- * and everything past it is gated as a CORPUS in `tests/test_pure_function_parity.py`.
+ * and everything past it is gated as a CORPUS in `tests/unit/wizard.test.mjs`.
  *
  * The corpus is a new shape and the brief predicted the reason: a corpus over a stdin reader
- * needs a SEEDED FD, not a string. `tests/fixtures/pure_probe.{py,mjs}` are run with stdin
- * redirected from a file of answers and their WHOLE stdout compared — so the prompts, the
+ * needs a SEEDED FD, not a string. `tests/fixtures/pure_probe.mjs` is run with stdin
+ * redirected from a file of answers and its WHOLE stdout compared — so the prompts, the
  * numbered menus, the default markers, the `About to run:` line and the returned selection
  * are all one byte comparison. That is a stricter gate than a cell would have been, because
  * a cell could not have varied the answers at all.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { main as driverMain, resolveOut } from '../build/driver.mjs';
@@ -57,132 +57,10 @@ import {
 } from '../hosts/installs.mjs';
 import { printOut, printErr } from '../lib/fs.mjs';
 import { which } from '../lib/paths.mjs';
+import { ask, askChoice, confirm } from '../lib/prompt.mjs';
 import { parseIntStrict } from '../lib/text.mjs';
 import { NO_WINDOW } from '../lib/proc.mjs';
 
-// --------------------------------------------------------------------------------------
-// the three readers
-// --------------------------------------------------------------------------------------
-
-/**
- * `_harness_setup._ask` — `input(f"{prompt}{suffix}: ").strip()`, or the default at EOF.
- *
- * WHY IT READS A BYTE AT A TIME. Node has no synchronous line read: `readFileSync(0)` blocks
- * until EOF rather than until Enter, so a wizard built on it would hang on a real terminal
- * until the user pressed Ctrl-D. Reading fd 0 one byte at a time to the first `\n` is what
- * `input()` does, and it is the only synchronous shape that stops where Enter stops. The
- * body arrived in P5h inside `js/maintain/uninstall.mjs`'s `confirm`; `setup` is the second caller,
- * so it moved to where the Python's own owner is — `_harness_setup` — and `confirm` is built
- * on it here exactly as `_confirm` is built on `_ask` there.
- *
- * The EOF branch is the one a piped caller sees, and it agrees with Python by two different
- * routes that happen to produce one answer: `input()` RAISES `EOFError` and the `except`
- * returns the default, while a zero-length read here leaves `line` empty and `|| dflt` does
- * the same. A partial line with no trailing newline is not EOF to either — Python returns
- * the characters and so does this.
- *
- * `.trim()` is `str.strip()` in every case but U+FEFF, which JS counts as whitespace and
- * Python does not; that is a standing item of this port and not this function's to settle.
- */
-export function ask(prompt, dflt = '') {
-  const suffix = dflt ? ` [${dflt}]` : '';
-  // `input()` writes its prompt to stdout with no newline — nothing for `printOut` to
-  // translate, and it must NOT gain one.
-  process.stdout.write(`${prompt}${suffix}: `);
-  // `?? ''` because `readLine` reports EOF-with-nothing-read as null since P6h; `_ask`
-  // catches `EOFError` and returns the default, which is what the empty string produces
-  // here through `|| dflt`. The two routes to one answer are the docblock's own point.
-  const ans = (readLine() ?? '').trim();
-  return ans || dflt;
-}
-
-/**
- * `input(prompt)` with EOF told apart from an empty line — `null` where Python RAISES.
- *
- * `ask` above cannot express that difference and does not need to: its EOF and its empty
- * answer both mean "take the default". `_web_server.serve`'s npm prompt is the first
- * caller where they differ, and they differ dangerously — `""` is in its accepted set, so
- * a port that read EOF as an empty line would answer YES to "run npm install now?" on
- * every non-interactive run. The reference catches `(EOFError, KeyboardInterrupt)` and
- * answers "n"; this returns null so the caller can.
- *
- * No `.trim()`: `input()` does not strip, and both callers strip for themselves.
- */
-export function promptLine(prompt) {
-  process.stdout.write(prompt);
-  return readLine();
-}
-
-/**
- * Fd 0 to the first `\n`, dropping a `\r` before it — the CRLF a Windows console sends.
- *
- * THE BYTES ARE COLLECTED AND DECODED ONCE, and that is a fix rather than a style. The
- * version this arrived as decoded EACH BYTE on its own — `buf.toString('utf8', 0, n)` inside
- * the loop — which turns every multi-byte character into two or three U+FFFD. It was
- * invisible for a phase because its only caller was `confirm`, whose answer is `y` or `n`;
- * the wizard's first non-ASCII answer is what exposed it, and the corpus caught it on the
- * first run. Scanning for the terminators a byte at a time is still correct: `\n` and `\r`
- * are ASCII, and no continuation byte of a UTF-8 sequence is below 0x80.
- */
-function readLine() {
-  const buf = Buffer.alloc(1);
-  const bytes = [];
-  let eof = false;
-  for (;;) {
-    let n = 0;
-    try { n = readSync(0, buf, 0, 1, null); } catch { eof = true; break; }
-    if (n === 0) { eof = true; break; }
-    if (buf[0] === 0x0a) break;
-    if (buf[0] !== 0x0d) bytes.push(buf[0]);
-  }
-  // NULL ONLY FOR THE EMPTY EOF, which is the one case `input()` raises on. A partial line
-  // with no trailing newline is not EOF to Python — it returns the characters — and the
-  // `bytes.length` test is what keeps that arm returning a string here too.
-  if (eof && bytes.length === 0) return null;
-  return Buffer.from(bytes).toString('utf8');
-}
-
-/** `_harness_setup._confirm` — `_ask` with a Y/n suffix; the default on an empty answer. */
-export function confirm(prompt, dflt = true) {
-  const ans = ask(`${prompt} (${dflt ? 'Y/n' : 'y/N'})`).toLowerCase();
-  return ans === '' ? dflt : ans[0] === 'y';
-}
-
-/**
- * `_harness_setup._ask_choice` — a numbered menu; the chosen KEY, or the default.
- *
- * THREE THINGS ABOUT THE FALLBACK ORDER, all of them observable and none of them obvious:
- *
- *   * The key match lives in Python's `except ValueError`, so an answer that PARSES as an
- *     integer never reaches it. `99` against a five-option menu returns the default; it does
- *     not go looking for an option literally named `99`.
- *   * An in-range index wins, a parsed out-of-range index falls to the default, and only an
- *     UNPARSEABLE answer is matched against the keys. `parseIntStrict` is what separates the second
- *     case from the third, and it is not `Number()` — see its own docblock.
- *   * The default's index is computed with `next(...)` and no fallback, so a default that is
- *     not in `options` raises `StopIteration` on the reference. That is reachable (a
- *     deployed install can carry a theme this checkout no longer ships) and it is mirrored
- *     as a throw rather than smoothed over: the two implementations must fail in the same
- *     place, and a silent `-1` here would be a divergence dressed as robustness.
- */
-export function askChoice(prompt, options, dflt) {
-  printOut(`\n${prompt}:\n`);
-  options.forEach(([key, desc], i) => {
-    const label = desc ? `${key} — ${desc}` : key;
-    printOut(`  ${i + 1}) ${label}${key === dflt ? '   (default)' : ''}\n`);
-  });
-  const defaultIdx = options.findIndex(([k]) => k === dflt);
-  if (defaultIdx < 0) throw new Error(`StopIteration: no option named ${dflt}`);
-  const raw = ask('Choose', String(defaultIdx + 1));
-  const idx = parseIntStrict(raw);
-  if (idx !== null) {
-    if (idx >= 1 && idx <= options.length) return options[idx - 1][0];
-  } else {
-    for (const [key] of options) if (raw === key) return key;
-  }
-  return dflt;
-}
-
 // --------------------------------------------------------------------------------------
 // the option tables
 // --------------------------------------------------------------------------------------
@@ -372,7 +250,7 @@ export function collectSetupLines() {
   const mode = askChoice('Mode', modeOptions(), inst.mode || defaultMode());
   const doctrines = askDoctrines(inst.doctrines);
   const emit = askChoice('Install mode', EMIT_OPTIONS, inst.emit || 'opencode-global');
-  const footprint = askChoice('Footprint', FOOTPRINT_OPTIONS.map(([k, d]) => [k, d]),
+  const footprint = askChoice('Footprint', FOOTPRINT_OPTIONS,
     inst.footprint || 'lean');
   let out = null;
   let root = null;
@@ -430,8 +308,8 @@ export function javaMajorOk(versionOutput, minimum = 21) {
  * `_harness_setup._lsp_prereqs` — `(label, present, hint)` for what OpenCode cannot install
  * for itself. Today that is a JDK 21+ for `jdtls`; the JS-runtime servers self-download.
  *
- * THE SECOND SPAWN ON THIS ENTRY POINT, and the reason `test_the_cli_reaches_child_process_\
- * only_where_it_is_declared` became a TABLE. `js/inspect/doctor.mjs` was the sole allowed importer
+ * THE SECOND SPAWN ON THIS ENTRY POINT, and the reason `ALLOWED_SPAWNS` in
+ * `tests/unit/hook_cli.test.mjs` became a TABLE. `js/inspect/doctor.mjs` was the sole allowed importer
  * for one binding and one argv; this is the second, and the port's rule is that the second
  * instance of anything turns a special case into a table cross-checked against the source.
  * The argv is asserted literally there, so an allow-list entry cannot be reused to start an
@@ -572,7 +450,7 @@ export function setupSummaryLines(theme, emit, out, root, ok) {
  * command the reader can type, and names one that survives the deletion.
  *
  * `theme_anim.play_line` USED TO BE THE SECOND, and P7c crossed it — `js/ui/anim.mjs`, gated by
- * `_theme_anim_cases()` in `tests/test_pure_function_parity.py`. The bare `catch` around it
+ * the theme-animation jobs in `tests/unit/wizard.test.mjs`. The bare `catch` around it
  * is the reference's own, labelled there "cosmetic only — never block a successful install",
  * and it is kept for the same reason: the animation runs AFTER the build has already
  * succeeded, so nothing it can do may change the exit code.