geneseed 3.1.1 → 3.1.2

package/js/{settings.mjs → hosts/settings.mjs}

@@ -7,16 +7,20 @@
  * last is that it is also the unit the RUNTIME drives: eleven of its names have a consumer
  * outside the emit tree, ten of them in `rituals/_harness_mcp.py` (remerge, deactivate,
  * reactivate, uninstall), two in `rituals/_harness_exclude.py`, one in
- * `rituals/_harness_build.py`. Nothing imports this module yet — P3a proves the unit,
- * P3b flips the call sites.
+ * Every emit and every lifecycle verb goes through this module:
+ * `js/build/emit-opencode.mjs` and `js/build/emit-claude.mjs` wire the host config,
+ * `js/maintain/uninstall.mjs` and `js/maintain/migrate.mjs` drive the unwire and the shim
+ * migration, `js/inspect/checks-repo.mjs` reads `shimDeadPaths` for the doctor, and
+ * `js/web/api.mjs` borrows the same readers for the console.
  *
  * THE STDOUT RULE BINDS HARDEST HERE. The hooks this module writes signal their verdict as
  * a JSON object on stdout and return 0 on EVERY path (`|| exit 0` is not what it looks
  * like — see the shim comment below), so a stray byte printed on a hook path does not make
  * noise, it silently disables a gate. Everything printed here is a generator-time message;
- * the streams are compared byte for byte by `tests/test_settings_parity.py`, and the
- * asymmetry between the two (`_warn_commented_jsonc` prints to STDOUT, every other message
- * to stderr) is the Python's own and is reproduced, not tidied.
+ * the split between them is asserted absolutely by `tests/unit/settings_jsonc.test.mjs` and
+ * `tests/unit/settings_integrity.test.mjs`. The asymmetry (`_warn_commented_jsonc` prints to
+ * STDOUT, every other message to stderr) is inherited from `_build_settings.py` and kept
+ * deliberately rather than tidied.
  *
  * HOOKS ARE APPEND-ONLY AND FAIL-CLOSED. Nothing here rewrites a hook group in place:
  * `mergeClaudeSettings` appends what is missing and removes only groups the manifest
@@ -38,10 +42,11 @@ import {
 } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { printErr, readText, writeText } from '../lib/fs.mjs';
 import {
-  jsonDumps, jsonDumpsCompact, jsonDumpsIndent, parseJson, pyEq, pyRepr, indexOfEq,
-  pyPrintErr, readText, writeText,
-} from './lib/fs.mjs';
+  jsonDumps, jsonDumpsCompact, jsonDumpsIndent, parseJson, deepEquals, formatRepr,
+  indexOfDeepEqual,
+} from '../lib/json.mjs';
 
 export const OPENCODE_SCHEMA = 'https://opencode.ai/config.json';
 
@@ -49,7 +54,7 @@ export const OPENCODE_SCHEMA = 'https://opencode.ai/config.json';
  *
  * `loaded[event]` where `event` came out of a manifest hands back `Object.prototype`'s
  * member for `constructor`, `toString` or `valueOf`, where Python's `.get` returns None.
- * The same hazard `js/native.mjs` hit with `overrides[stem]`, on a dict the USER edits. */
+ * The same hazard `js/hosts/native.mjs` hit with `overrides[stem]`, on a dict the USER edits. */
 function get(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
 }
@@ -349,7 +354,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null, excluded = [])
       raw = readText(target);
     } catch (e) {
       if (!isOsError(e)) throw e;
-      process.stderr.write(`[geneseed] WARN: could not read ${target} (${pyOsError(e)}) `
+      process.stderr.write(`[geneseed] WARN: could not read ${target} (${asOsError(e)}) `
         + `— NOT touching it. Add ${jsonDumps(agentPath)} to its "instructions" array by `
         + "hand once it's readable again.\n");
       return target;
@@ -367,7 +372,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null, excluded = [])
   if (!has(config, '$schema')) config.$schema = OPENCODE_SCHEMA;
   let instr = get(config, 'instructions');
   if (!Array.isArray(instr)) instr = [];
-  const addInstr = indexOfEq(instr, agentPath) < 0;
+  const addInstr = indexOfDeepEqual(instr, agentPath) < 0;
   if (addInstr) instr.push(agentPath);
   config.instructions = instr;
   // Absent ⇒ write the whole block; present ⇒ reconcile Geneseed's own git keys. Adding is
@@ -428,7 +433,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null, excluded = [])
     atomicWriteJson(target, config);
   } catch (e) {
     if (!isOsError(e)) throw e;
-    process.stderr.write(`[geneseed] WARN: could not write ${target} (${pyOsError(e)}) — `
+    process.stderr.write(`[geneseed] WARN: could not write ${target} (${asOsError(e)}) — `
       + `the harness will NOT auto-load until this is fixed. Add ${jsonDumps(agentPath)} `
       + 'to its "instructions" array by hand.\n');
   }
@@ -444,7 +449,7 @@ export function mergeOpencodeJson(p, agentPath, doctrines = null, excluded = [])
  * with an injectable failure instead and compares everything except the OS's own wording.
  * Named here so the gap is a decision rather than a surprise at GA.
  */
-function pyOsError(e) {
+function asOsError(e) {
   return e.message;
 }
 
@@ -475,7 +480,7 @@ export const SHIM_ARGV = new Set(['$@', '%*']);
  * Every quoted token in a shim body that names a path which is not there — empty is healthy.
  *
  * ONE OWNER, because the rule has two consumers now and a second copy is a second place for the
- * `"$@"` defect above to come back: `js/doctor.mjs` turns this into the `[shim] … does not
+ * `"$@"` defect above to come back: `js/inspect/checks-repo.mjs` turns this into the `[shim] … does not
  * exist` report, and `hookPrefix` reads it to decide whether the shim already on disk is worth
  * protecting from a checkout that will not outlive the emit.
  */
@@ -501,7 +506,7 @@ export function shimHome() {
 }
 
 /**
- * `Path(x).expanduser()` — private twin of `js/hosts.mjs`'s `expanduser`, same guard.
+ * `Path(x).expanduser()` — private twin of `js/hosts/hosts.mjs`'s `expanduser`, same guard.
  *
  * `GENESEED_HOME` is user-set, same as any config-dir env var there, so a `~user` value here
  * has the identical failure mode (a hook shim written under a literal `~user` directory) and
@@ -514,7 +519,7 @@ function expanduser(p) {
   if (p.startsWith('~')) {
     const msg = `refusing '${p}': a '~user' path is not expanded by this port; pass an `
       + 'absolute path, or "~" / "~/…" for your own home directory';
-    pyPrintErr(`${msg}\n`);
+    printErr(`${msg}\n`);
     const e = new Error(msg);
     e.exitCode = 1;
     throw e;
@@ -536,12 +541,12 @@ export function hookShimPath(platform = process.platform) {
  * refuses to compare the emitted shim for that reason (`_SHIM_GLOB`) and asserts
  * `_shim_health` instead.
  *
- * So the parity gate's answer here is NOT "skip it". Taking `runner` and `entry` as
- * arguments makes the BODY a pure function of three inputs, and the gate feeds Node the
- * same two values Python computed — which makes every byte of it comparable: the `@echo
- * off`, the CRLF, `exit /b` vs `exec`, the quoting that keeps `--root "<cfg>"` intact. What
- * the gate does not prove is WHICH values a Node driver will pass, and that is a one-line
- * decision at P3b's call site rather than anything in this body.
+ * So the answer here is NOT "skip it". Taking `runner`, `entry` and `platform` as arguments
+ * makes the BODY a pure function of three inputs, which is what lets
+ * `tests/unit/hook_form.test.mjs` assert BOTH platform shapes absolutely in one run on
+ * whichever host it happens to be on: the `@echo off`, the CRLF, `exit /b` vs `exec`, the
+ * quoting that keeps `--root "<cfg>"` intact. What it does not prove is WHICH values the
+ * driver passes — that is `bin/build-driver.mjs`'s `hookRunnerEntry()`, gated separately.
  */
 export function hookShimBody(runner, entry, platform = process.platform) {
   if (platform === 'win32') {
@@ -757,7 +762,7 @@ export function claudeHookGroups(cfg, hookOpts, doctrines = null, excluded = [])
  *
  * `scope` is accepted and unused, exactly as in the Python.
  */
-export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hookOpts = {},
+export function mergeClaudeSettings(p, _scope = 'global', priorHooks = null, hookOpts = {},
   doctrines = null, excluded = []) {
   const prior = (priorHooks || []).filter(isDict);
   let config = {};
@@ -785,12 +790,12 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
   }
   let pruned = false;
   for (const rec of prior) {
-    if (indexOfEq(canonFlat, rec) >= 0) continue;
+    if (indexOfDeepEqual(canonFlat, rec) >= 0) continue;
     const event = get(rec, 'event');
     const group = get(rec, 'group');
     const arr = get(hooks, event);
     if (Array.isArray(arr)) {
-      const at = indexOfEq(arr, group);
+      const at = indexOfDeepEqual(arr, group);
       if (at >= 0) {
         arr.splice(at, 1);
         pruned = true;
@@ -803,14 +808,14 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
     let arr = get(hooks, event);
     if (!Array.isArray(arr)) arr = [];
     for (const g of newGroups) {
-      if (indexOfEq(arr, g) >= 0) continue;
+      if (indexOfDeepEqual(arr, g) >= 0) continue;
       arr.push(g);
       added.push({ event, group: g });
     }
     hooks[event] = arr;
   }
-  const survivors = prior.filter((r) => indexOfEq(canonFlat, r) >= 0);
-  const managedNow = survivors.concat(added.filter((a) => indexOfEq(survivors, a) < 0));
+  const survivors = prior.filter((r) => indexOfDeepEqual(canonFlat, r) >= 0);
+  const managedNow = survivors.concat(added.filter((a) => indexOfDeepEqual(survivors, a) < 0));
   if (!added.length && !pruned) return [p, managedNow];
   if (hadComments) {
     process.stderr.write(`[geneseed] ${path.basename(p)} has comments — not rewriting it `
@@ -822,8 +827,10 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
   // carries four events, so by the time control reaches here `hooks` is never empty. A
   // mutation keeping the empty block instead of deleting it is the one of thirty-three that
   // stays green, and it stays green because there is nothing to detect — recorded the way
-  // `themed_rel` and `lstripNewlines` are, so "the gate cannot see it" and "there is
-  // nothing to see" keep their distance.
+  // `themed_rel` is, so "the gate cannot see it" and "there is nothing to see" keep their
+  // distance. NOT the way `lstripNewlines` is: that one looked unobservable for two phases
+  // and turned out to be mutation M7, killed by `golden.mjs --idempotent` through
+  // `managedBlockWrite`'s `updated` branch, which only a RE-emit reaches.
   if (Object.keys(hooks).length) config.hooks = hooks;
   else delete config.hooks;
   mkdirSync(path.dirname(p), { recursive: true });
@@ -855,7 +862,7 @@ export function unwireClaudeSettings(p, added) {
     const group = get(rec, 'group');
     let arr = get(hooks, event);
     if (Array.isArray(arr)) {
-      const at = indexOfEq(arr, group);
+      const at = indexOfDeepEqual(arr, group);
       if (at >= 0) arr.splice(at, 1);
     }
     arr = get(hooks, event);
@@ -896,7 +903,7 @@ export function wireClaudeExcludes(p, excludes) {
   }
   let cur = get(config, 'claudeMdExcludes');
   if (!Array.isArray(cur)) cur = [];
-  const added = want.filter((e) => indexOfEq(cur, e) < 0);
+  const added = want.filter((e) => indexOfDeepEqual(cur, e) < 0);
   if (!added.length) return [];
   if (hadComments) {
     process.stderr.write(`[geneseed] ${path.basename(p)} has comments — not rewriting it `
@@ -911,7 +918,7 @@ export function wireClaudeExcludes(p, excludes) {
     atomicWriteJson(p, config);
   } catch (e) {
     if (!isOsError(e)) throw e;
-    process.stderr.write(`[geneseed] WARN: could not write ${p} (${pyOsError(e)}) — `
+    process.stderr.write(`[geneseed] WARN: could not write ${p} (${asOsError(e)}) — `
       + 'claudeMdExcludes were not wired. Add to its "claudeMdExcludes" array by hand: '
       + `${jsonDumpsCompact(added)}\n`);
     return [];
@@ -934,7 +941,7 @@ export function unwireClaudeExcludes(p, excludes) {
   const cur = get(loaded, 'claudeMdExcludes');
   if (!Array.isArray(cur)) return;
   for (const e of excludes) {
-    const at = indexOfEq(cur, e);
+    const at = indexOfDeepEqual(cur, e);
     if (at >= 0) cur.splice(at, 1);
   }
   if (cur.length) loaded.claudeMdExcludes = cur;
@@ -971,8 +978,9 @@ export const SHIM_ENTRY_MARK = 'geneseed-hook.mjs';
 /**
  * `_build_settings._migrate_shape` — 'legacy' | 'current' | 'none'.
  *
- * PURE, so `tests/test_settings_parity.py` runs it over a corpus of real config text no cell
- * can seed. 'none' is not a fault: a Copilot install wires no hooks, and a user's own
+ * PURE — and currently reached only END TO END, by the `migrate/a-node-baked-shim-reads-as-current`
+ * cell. No unit corpus drives it directly, which is worth knowing before trusting it.
+ * 'none' is not a fault: a Copilot install wires no hooks, and a user's own
  * settings.json may carry three hand-written hooks and no Geneseed entry. Both must read as
  * "nothing to migrate" rather than "unrecognised", or `migrate` refuses on the commonest
  * config on any machine.
@@ -1060,7 +1068,7 @@ export function settingsIntegrityCheck(p, managed, expect = 'present') {
     [loaded] = readJsonc(readText(p));
   } catch (e) {
     if (!isOsError(e)) throw e;
-    problems.push(`${p}: could not read the file (${pyOsError(e)})`);
+    problems.push(`${p}: could not read the file (${asOsError(e)})`);
     return flush();
   }
   if (!isDict(loaded)) {
@@ -1077,25 +1085,25 @@ export function settingsIntegrityCheck(p, managed, expect = 'present') {
   for (const rec of recordedHooks) {
     const event = get(rec, 'event');
     const group = get(rec, 'group');
-    const hit = presentGroups.some(([e, g]) => pyEq(e, event) && pyEq(g, group));
+    const hit = presentGroups.some(([e, g]) => deepEquals(e, event) && deepEquals(g, group));
     if (expect === 'present' && !hit) {
-      problems.push(`${p}: recorded hook group missing — event=${pyRepr(event ?? null)} `
+      problems.push(`${p}: recorded hook group missing — event=${formatRepr(event ?? null)} `
         + `group=${jsonDumpsCompact(group ?? null)}`);
     } else if (expect === 'absent' && hit) {
       problems.push(`${p}: recorded hook group still present after unwire — `
-        + `event=${pyRepr(event ?? null)} group=${jsonDumpsCompact(group ?? null)}`);
+        + `event=${formatRepr(event ?? null)} group=${jsonDumpsCompact(group ?? null)}`);
     }
   }
 
   let exclCur = get(loaded, 'claudeMdExcludes');
   exclCur = Array.isArray(exclCur) ? exclCur : [];
   for (const entry of (get(m, 'settings_excludes') || [])) {
-    const hit = indexOfEq(exclCur, entry) >= 0;
+    const hit = indexOfDeepEqual(exclCur, entry) >= 0;
     if (expect === 'present' && !hit) {
-      problems.push(`${p}: recorded claudeMdExcludes entry missing: ${pyRepr(entry)}`);
+      problems.push(`${p}: recorded claudeMdExcludes entry missing: ${formatRepr(entry)}`);
     } else if (expect === 'absent' && hit) {
       problems.push(`${p}: recorded claudeMdExcludes entry still present after unwire: `
-        + `${pyRepr(entry)}`);
+        + `${formatRepr(entry)}`);
     }
   }
 
@@ -1103,17 +1111,17 @@ export function settingsIntegrityCheck(p, managed, expect = 'present') {
   // auto-delete (they may be user-authored, or a claim this run legitimately did not
   // inherit).
   const recordedSet = new Set(recordedHooks.map(
-    (r) => `${pyRepr(get(r, 'event') ?? null)}\u0000`
+    (r) => `${formatRepr(get(r, 'event') ?? null)}\u0000`
       + `${jsonDumpsCompact(get(r, 'group') ?? null, { sortKeys: true })}`));
   for (const [event, group] of presentGroups) {
-    const key = `${pyRepr(event)}\u0000${jsonDumpsCompact(group, { sortKeys: true })}`;
+    const key = `${formatRepr(event)}\u0000${jsonDumpsCompact(group, { sortKeys: true })}`;
     if (recordedSet.has(key)) continue;
     const cmds = (get(group, 'hooks') || []).filter(isDict)
       .map((h) => (has(h, 'command') ? h.command : ''));
     if (cmds.some((c) => typeof c === 'string'
       && GENESEED_HOOK_SNIFF.some((mk) => c.includes(mk)))) {
       problems.push(`${p}: Geneseed-pattern hook present but NOT recorded in the manifest `
-        + `(event=${pyRepr(event)}) — possibly user-authored; left alone`);
+        + `(event=${formatRepr(event)}) — possibly user-authored; left alone`);
     }
   }
 
@@ -1133,7 +1141,7 @@ function delimiters(blockId) {
  */
 export function managedBlockWrite(p, content, blockId = 'GENESEED') {
   const [begin, end] = delimiters(blockId);
-  const block = `${begin}\n${pyRstrip(content)}\n${end}\n`;
+  const block = `${begin}\n${stripEnd(content)}\n${end}\n`;
   if (!existsSync(p)) {
     mkdirSync(path.dirname(p), { recursive: true });
     writeText(p, block);
@@ -1163,7 +1171,7 @@ export function managedBlockRemove(p, blockId = 'GENESEED', whole = false) {
   if (!existing.includes(begin) || !existing.includes(end)) return;
   const pre = existing.split(begin)[0];
   const post = existing.slice(existing.indexOf(end) + end.length);
-  const rest = pyStrip(`${pyRstripNewlines(pre)}\n${lstripNewlines(post)}`);
+  const rest = stripEnds(`${stripTrailingNewlines(pre)}\n${lstripNewlines(post)}`);
   if (rest) writeText(p, `${rest}\n`);
   else unlinkSync(p);
 }
@@ -1183,17 +1191,17 @@ export function managedBlockRead(p, blockId = 'GENESEED') {
 // U+001C–U+001F, which `trim()` leaves. A managed block is user-editable prose in a file
 // Geneseed shares with the user, so the set is spelled out rather than approximated — and
 // spelled with escapes, never literals: a raw U+2028 in a JS source file ends the line.
-const PY_SPACE = '[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a'
+const WHITESPACE = '[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a'
   + '\u2028\u2029\u202f\u205f\u3000]';
 
-const RSTRIP_RE = new RegExp(`${PY_SPACE}+$`);
-const LSTRIP_RE = new RegExp(`^${PY_SPACE}+`);
+const RSTRIP_RE = new RegExp(`${WHITESPACE}+$`);
+const LSTRIP_RE = new RegExp(`^${WHITESPACE}+`);
 
-function pyRstrip(s) {
+function stripEnd(s) {
   return s.replace(RSTRIP_RE, '');
 }
 
-function pyStrip(s) {
+function stripEnds(s) {
   return s.replace(LSTRIP_RE, '').replace(RSTRIP_RE, '');
 }
 
@@ -1201,10 +1209,10 @@ function lstripNewlines(s) {
   return s.replace(/^\n+/, '');
 }
 
-function pyRstripNewlines(s) {
+function stripTrailingNewlines(s) {
   return s.replace(/\n+$/, '');
 }
 
 function stripNewlines(s) {
-  return lstripNewlines(pyRstripNewlines(s));
+  return lstripNewlines(stripTrailingNewlines(s));
 }