geneseed 3.1.0 → 3.1.2

package/js/lib/fs.mjs

@@ -1,32 +1,34 @@
 /**
- * The primitives — how this tool reads, writes, quotes, compares and prints.
+ * Reading and writing — files on disk, and the two process streams.
  *
- * These are the definitions, not an adaptation of somebody else's. Every rule below was
+ * These are definitions, not an adaptation of somebody else's. Every rule below was
  * originally MEASURED against CPython, because the generator these functions serve had to
  * emit bytes indistinguishable from a Python one; that second party is gone and the rules
  * are not. What holds them now is the recorded corpora under `tests/__snapshots__/`, which
  * compare this module's output byte for byte and can never be re-recorded — so a rule here
  * is a frozen fact about what this tool emits, and changing one is a product change.
  *
- * The `py`-prefixed export names are kept on purpose. Each marks a function whose contract
- * is a language primitive's exact behaviour rather than a convenience wrapper, and that mark
- * is what stops a later reader "simplifying" one back to the Node default it deliberately is
- * not. For the same reason the per-function comments still name what was measured: that
- * provenance is the only surviving record of WHY a rule is the shape it is, and it is the
- * first thing to read before touching one.
+ * ⚠ NONE OF THESE IS THE NODE DEFAULT, AND THAT IS THE ONE THING TO KNOW BEFORE EDITING ONE.
+ * Each is a deliberate divergence from the obvious one-liner, and the obvious one-liner is
+ * wrong here in a way no test in this repository would tell you about pleasantly. These names
+ * carried a `py` prefix until the prefix was retired, precisely to say so; the warning now
+ * lives where it belongs, in the per-function comment naming WHAT WAS MEASURED and against
+ * what. That provenance is the only surviving record of why a rule has the shape it has, and
+ * it is the first thing to read before touching one.
+ *
+ * In this module the divergence is `os.linesep`: every write translates `\n` to the platform's
+ * separator, and `printOut`/`printErr` do the same on the way to the console.
+ *
+ * The rest of the old single `fs.mjs` lives beside this file: `json.mjs` (quoting and the
+ * parsed-value model), `paths.mjs` (comparing and locating), `text.mjs` (string primitives).
  *
  * Everything here is stdlib-only, ESM, and deliberately tiny — it is imported on hook paths,
  * where load time is a per-tool-call cost.
  */
 import {
-  accessSync, appendFileSync, constants, writeFileSync, readFileSync, copyFileSync, statSync,
-  utimesSync,
+  appendFileSync, writeFileSync, readFileSync, copyFileSync, statSync, utimesSync,
 } from 'node:fs';
 import { EOL } from 'node:os';
-import path from 'node:path';
-
-const { X_OK } = constants;
-
 /**
  * `Path.write_text(text, encoding="utf-8")`.
  *
@@ -52,7 +54,7 @@ export function writeText(path, text) {
  * `path.open("a", encoding="utf-8").write(text)` — the APPEND half of the rule above.
  *
  * Same translation, second mode. It lives here rather than inlined at its one call site
- * (`js/update.mjs`'s install log) because the newline rule has exactly one owner in this
+ * (`js/maintain/update.mjs`'s install log) because the newline rule has exactly one owner in this
  * port and a second copy of it is how the rule rots: an appended line written with
  * `appendFileSync` alone is the only LF-terminated line in an otherwise CRLF file, which is
  * invisible in an editor and a whole-file difference to the gate.
@@ -95,402 +97,6 @@ export function copyFile(src, dest) {
   utimesSync(dest, st.atime, st.mtime);
 }
 
-/**
- * `json.dumps(s)` for a STRING, with Python's default `ensure_ascii=True`.
- *
- * Every emitted `description:` line is built this way, and 44-50 of them per theme carry
- * an em dash today: Python writes `"a — b"`, `JSON.stringify` writes `"a — b"`. The
- * two agree on everything below U+007F — including the control-character table
- * (`\b \t \n \f \r`, then lowercase `\u00xx`) — so escaping the rest is the whole delta.
- * Astral characters fall out correctly without a special case: JS strings are UTF-16, so
- * the surrogate pair is escaped one code unit at a time, which is exactly what Python
- * emits (`😀`).
- *
- * Strings only, and loudly so — a COMPACT container is the one shape that genuinely
- * differs: Python's default separators are `(', ', ': ')`, so it writes `{"a": 1, "b": 2}`
- * where `JSON.stringify` writes `{"a":1,"b":2}`. Indented containers do NOT have that
- * problem (see `jsonDumpsIndent`), which is why the split is compact-vs-indented rather
- * than string-vs-container.
- */
-export function jsonDumps(s) {
-  if (typeof s !== 'string') {
-    throw new TypeError('jsonDumps takes a string; a COMPACT container differs from '
-      + "json.dumps by Python's ', ' / ': ' separators too \u2014 use jsonDumpsIndent or "
-      + 'jsonDumpsCompact');
-  }
-  return escapeNonAscii(JSON.stringify(s));
-}
-
-/**
- * `ensure_ascii=True`: escape everything Python's encoder does and JS's does not.
- *
- * Applied to the SERIALISED text, which is safe because a JSON document can only carry
- * non-ASCII inside string literals. Spelled with \\u escapes, never literals: a JS source
- * file carrying a raw U+2028 or U+2029 terminates the line it sits on, and the parse
- * error points somewhere else entirely.
- */
-function escapeNonAscii(text) {
-  return text.replace(/[\u007f-\uffff]/g,
-    (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
-}
-
-/**
- * `json.dumps(obj, indent=2)` \u2014 and with `{ ensureAscii: false }`, the
- * `ensure_ascii=False` variant. Those are the only two container shapes the generator
- * writes; measured across all 27 `json.dumps` call sites.
- *
- * Indentation is what makes this tractable: passing `indent` switches Python's
- * separators from `(', ', ': ')` to `(',', ': ')`, which is exactly what
- * `JSON.stringify(v, null, 2)` emits. Verified rather than argued \u2014
- * `tests/test_opencode_extras_parity.py` compares both variants against Python over a
- * corpus of container shapes.
- */
-export function jsonDumpsIndent(value, { ensureAscii = true } = {}) {
-  const text = JSON.stringify(value, null, 2);
-  return ensureAscii ? escapeNonAscii(text) : text;
-}
-
-/**
- * `json.dumps(obj)` and `json.dumps(obj, sort_keys=True)` — the COMPACT container form.
- *
- * Deferred through three phases because guessing its signature would have been worse than
- * not having it; `js/settings.mjs` is the code that finally needs it, and the shapes were
- * counted with `ast` rather than assumed: four bare `json.dumps(container)` and two
- * `sort_keys=True`, all inside `_build_settings.py`, none of them `ensure_ascii=False`.
- *
- * It cannot delegate to `JSON.stringify` the way `jsonDumpsIndent` does. Without an indent
- * Python's separators are `(', ', ': ')` — `{"a": 1, "b": [1, 2]}` where `JSON.stringify`
- * writes `{"a":1,"b":[1,2]}` — and patching the separators back into the serialised text
- * would corrupt any string containing `,` or `:`. So the walk is written out.
- *
- * `sortKeys` sorts with JS's default comparator (UTF-16 code units) where Python sorts by
- * code point; the two disagree only above the BMP, which no settings.json key reaches. A
- * non-finite number throws rather than emitting `NaN`/`Infinity`: Python's encoder writes
- * those bare tokens, which is not valid JSON, and no caller here can produce one.
- *
- * `bareInts` admits a BARE JS number, reading it as a Python `int`. `pyStr` refuses one by
- * default and is right to: a value that came out of `json.loads` carries the int/float
- * distinction and a bare double has lost it. But P6's caller is `_send_json`, whose values
- * are COMPUTED here — counts, a port, a pid, a unix second — and Python types every one of
- * them `int`, which both languages render identically. The flag is where that claim is
- * stated; the byte gate over every endpoint body is what would catch a float. A
- * non-integral value still renders through `repr(float)`, which is the honest reading of
- * `0.5`; only an INTEGRAL float (`1.0` against JS's `1`) is unrepresentable, and it is
- * unrepresentable whatever this flag says.
- */
-export function jsonDumpsCompact(value, { sortKeys = false, ensureAscii = true,
-  bareInts = false } = {}) {
-  const text = compactImpl(value, sortKeys, bareInts);
-  return ensureAscii ? escapeNonAscii(text) : text;
-}
-
-function compactImpl(v, sortKeys, bareInts) {
-  if (v === null || v === undefined) return 'null';
-  if (v === true) return 'true';
-  if (v === false) return 'false';
-  if (typeof v === 'string') return JSON.stringify(v);
-  if (v instanceof PyNumber || typeof v === 'number') {
-    const n = v instanceof PyNumber ? v.value : v;
-    if (!Number.isFinite(n)) {
-      throw new TypeError(`jsonDumpsCompact got ${n}; Python's encoder writes a bare `
-        + 'NaN/Infinity token there, which is not JSON, and nothing here can produce one');
-    }
-    if (bareInts && typeof v === 'number') {
-      return Number.isSafeInteger(n) ? String(n) : pyFloat(n);
-    }
-    return pyStr(v);
-  }
-  if (Array.isArray(v)) {
-    return `[${v.map((x) => compactImpl(x, sortKeys, bareInts)).join(', ')}]`;
-  }
-  if (typeof v === 'object') {
-    const keys = sortKeys ? Object.keys(v).sort() : Object.keys(v);
-    return `{${keys.map((k) => `${JSON.stringify(k)}: ${compactImpl(v[k], sortKeys, bareInts)}`)
-      .join(', ')}}`;
-  }
-  throw new TypeError(`jsonDumpsCompact has no rendering for ${typeof v}`);
-}
-
-/**
- * Python's `==` for values that came out of `json.loads` \u2014 the operator behind
- * `group in arr`, `rec in canon_flat` and `arr.remove(group)`.
- *
- * `===` is identity for containers, so a naive port of `if group in arr` never matches and
- * `_merge_claude_settings` re-adds its own hook group on every emit \u2014 the exact defect the
- * prior-claim pruning exists to prevent, reintroduced by a one-word translation.
- *
- * `PyNumber` compares by its VALUE, which is right: Python's `{"a": 1} == {"a": 1.0}` is
- * True even though `repr` renders the two differently. The one gap left is Python's
- * `1 == True`; a settings.json holding a bool where the manifest recorded a number is not
- * a shape any writer here produces.
- */
-export function pyEq(a, b) {
-  const x = a instanceof PyNumber ? a.value : a;
-  const y = b instanceof PyNumber ? b.value : b;
-  if (x === null || y === null || typeof x !== 'object' || typeof y !== 'object') {
-    return x === y;
-  }
-  if (Array.isArray(x) !== Array.isArray(y)) return false;
-  if (Array.isArray(x)) {
-    return x.length === y.length && x.every((v, i) => pyEq(v, y[i]));
-  }
-  const kx = Object.keys(x);
-  const ky = Object.keys(y);
-  return kx.length === ky.length
-    && kx.every((k) => Object.prototype.hasOwnProperty.call(y, k) && pyEq(x[k], y[k]));
-}
-
-/** `value in list` and `list.index(value)` under `pyEq` \u2014 Python's `in`, not `includes`. */
-export function indexOfEq(arr, value) {
-  return arr.findIndex((v) => pyEq(v, value));
-}
-
-/**
- * `PurePath._str_normcase` \u2014 Windows compares and sorts paths case-folded, POSIX does
- * not. This is what makes `sorted(SRC.rglob('*'))` and `sorted(d.glob('*.json'))`
- * platform-dependent, and the order is observable: the prompt emitter embeds items in
- * order, and each emit's written list becomes the ownership manifest the prune diffs.
- *
- * Two residual differences, both unreachable with this repo's ASCII filenames: Python
- * compares by code point where JS compares by UTF-16 code unit (differs only above the
- * BMP), and `str.lower()` is not `toLowerCase()` for a handful of characters.
- *
- * THE SEPARATOR CONVERSION IS NOT OPTIONAL, and it was missing until the byte-bearing
- * corpus in `tests/test_pure_function_parity.py` asked. `ntpath.normcase` is
- * `s.replace('/', '\\').lower()`, and `PurePath._str_normcase` gets the same conversion for
- * free because `Path` has already done it — so BOTH readings of the reference fold slashes
- * and this did not. Every sort call site feeds it `path.join` output or a bare `readdir`
- * name, which is why no emitted byte ever moved; `fnTranslate(normcase(pattern))` in
- * `js/hooks.mjs` is where it was reachable, because an exclude pattern is USER-WRITTEN and
- * `memory/*` never matched a native `memory\x` the way `fnmatch` does.
- */
-export const normcase = process.platform === 'win32'
-  ? (s) => s.replaceAll('/', '\\').toLowerCase()
-  : (s) => s;
-
-/**
- * `sorted()` over paths \u2014 one owner, so two call sites cannot drift apart.
- *
- * COMPONENT-WISE, and that was a flat string compare until P2 measured it. `PurePath.__lt__`
- * compares `_parts_normcase` \u2014 a TUPLE of path components \u2014 so the separator never takes part
- * in the comparison, and the two readings disagree in BOTH directions:
- *
- *     sorted    : skills/geneseed/SKILL.md  <  skills/geneseed-code-review/SKILL.md
- *     flat cmp  : the reverse, because '-' (0x2d) sorts before the separator '\\' (0x5c)
- *     sorted    : x/a/b.md  <  x/a.md          (component 'a' < 'a.md')
- *     flat cmp  : the reverse again
- *
- * Nothing in the emitted tree could see it: `js/render.mjs` sorts a list whose members share
- * a directory depth, and `golden.py` compared CONTENT rather than order. It became visible
- * the first time a full path list was PRINTED \u2014 `geneseed validate -v` \u2014 against a real
- * skills tree that happens to contain both `skills/geneseed/` and `skills/geneseed-code-review/`.
- * `tests/test_maintainer_tools_parity.py` found it and died with the reference it compared
- * against. What HOLDS it now is `tests/unit/maintainer_tools.test.mjs`, and specifically its
- * `theme files are visited in THIS platform's Path collation order` test: it re-derives Python's
- * `sorted(Path)` order for the running platform instead of replaying a recording, so it cannot
- * agree with a drift \u2014 and it is the measured killer of this function's mutation (M3).
- */
-export function comparePaths(a, b) {
-  const A = normcase(a).split(/[\\/]/);
-  const B = normcase(b).split(/[\\/]/);
-  for (let i = 0; i < Math.min(A.length, B.length); i += 1) {
-    if (A[i] !== B[i]) return A[i] < B[i] ? -1 : 1;
-  }
-  return A.length - B.length;
-}
-
-/**
- * `_harness_core._within` \u2014 containment through `normcase`, segment-wise.
- *
- * MOVED HERE IN P6i, from `js/web/api.mjs` where P6b first needed it. The Python is a harness
- * CORE primitive (`child.relative_to(parent)` in a try/except), and its second caller is
- * `_install_move_list` in `js/uninstall.mjs` \u2014 a CLI-level module that must not import the
- * web tree to reach it. Beside `normcase`, which is the thing it is actually about.
- * `js/web/api.mjs` re-exports it so its existing importers are unchanged.
- */
-export function within(child, parent) {
-  const c = normcase(child).split(/[\\/]/);
-  const p = normcase(parent).split(/[\\/]/);
-  return p.length <= c.length && p.every((seg, i) => c[i] === seg);
-}
-
-/**
- * A number as `json.loads` produced it, carrying the literal it was parsed from.
- *
- * `json.loads` yields an `int` for `20` and a `float` for `1.0`, and Python's `str()`
- * renders those as `20` and `1.0`. `JSON.parse` collapses both to the IEEE double `1`,
- * and `String(1.0)` is `"1"` — so an `agent-overrides.json` carrying `"temperature": 1.0`
- * emits `temperature: 1.0` from Python and `temperature: 1` from Node.
- *
- * That divergence is invisible to the golden harness: the emit always writes an EMPTY
- * overrides stub, so no golden cell has ever had an override to render. It is only
- * reachable on a real user's machine, which is the worst place to find it.
- */
-class PyNumber {
-  constructor(value, source) { this.value = value; this.source = source; }
-  valueOf() { return this.value; }
-  toString() { return pyStr(this); }
-
-  /**
-   * Re-serialising parsed JSON must round-trip the way Python's does. Without this,
-   * `JSON.stringify` would walk the wrapper and emit `{"value":1,"source":"1.0"}`.
-   * `JSON.rawJSON` (Node >= 21) writes the text verbatim, and `pyStr` supplies the text
-   * Python would have \u2014 NOT the original literal, because `json.dumps(json.loads('1.50'))`
-   * is `1.5`: Python re-formats through repr rather than echoing the source.
-   */
-  toJSON() { return JSON.rawJSON(pyStr(this)); }
-}
-
-/**
- * `json.loads(text)`, preserving the int/float distinction (see `PyNumber`).
- *
- * Uses the reviver's `context.source` (Node >= 21). Where it is unavailable the numbers
- * come back bare and `pyStr` throws rather than formatting them wrongly — a loud failure
- * on an old runtime beats bytes that differ from Python's only for some values.
- */
-export function parseJson(text) {
-  return JSON.parse(text, function (key, value, context) {
-    return typeof value === 'number' && context && typeof context.source === 'string'
-      ? new PyNumber(value, context.source)
-      : value;
-  });
-}
-
-/** `repr(float)` — the half of `pyStr` where the two languages disagree most. */
-function pyFloat(n) {
-  if (Number.isNaN(n)) return 'nan';
-  if (!Number.isFinite(n)) return n > 0 ? 'inf' : '-inf';
-  const a = Math.abs(n);
-  if (a !== 0 && (a >= 1e16 || a < 1e-4)) {
-    // Python leaves positional notation outside [1e-4, 1e16); JS's own thresholds are
-    // 1e-6 and 1e21, and it writes a one-digit exponent where Python pads to two.
-    const [mantissa, exp] = n.toExponential().split('e');
-    return `${mantissa}e${exp[0] === '-' ? '-' : '+'}${exp.slice(1).padStart(2, '0')}`;
-  }
-  // Both engines print the shortest round-tripping decimal, but JS drops the fractional
-  // part of an integral value: `String(1.0)` is '1' where `repr(1.0)` is '1.0'. And
-  // `String(-0)` is '0' where `repr(-0.0)` keeps the sign.
-  const s = Object.is(n, -0) ? '-0' : String(n);
-  return s.includes('.') || s.includes('e') ? s : `${s}.0`;
-}
-
-/**
- * `str(value)` for a value that came out of `json.loads` — what an f-string interpolates.
- *
- * Only the types the generator actually renders are handled. A list, dict or bool reaching
- * here would print as `[object Object]` / `true` where Python prints `[1, 2]` / `True`, so
- * it throws instead: an override file with a value nobody has decided the semantics for is
- * a question to answer, not a byte to guess at.
- */
-/**
- * Python truthiness — `if value:` — for a value that came out of `json.loads`.
- *
- * `Boolean()` is not it, and the gap is not academic: a `PyNumber` is an OBJECT, so
- * `Boolean(PyNumber(0))` is `true` where Python's `if 0` is false. In the other direction
- * `Number('0')` is `0` where Python's `if "0"` is true. Both spellings appear in the
- * override tests, so neither shortcut is safe.
- */
-export function pyTruthy(value) {
-  if (value === undefined || value === null || value === false) return false;
-  if (typeof value === 'string') return value !== '';
-  if (value instanceof PyNumber) return value.value !== 0;
-  if (Array.isArray(value)) return value.length > 0;
-  if (typeof value === 'object') return Object.keys(value).length > 0;
-  return Boolean(value);
-}
-
-export function pyStr(value) {
-  if (typeof value === 'string') return value;
-  if (value instanceof PyNumber) {
-    // `json.decoder` picks parse_float for any literal carrying a fraction or an exponent
-    // and parse_int otherwise — so the literal, not the resulting double, is what decides.
-    // Ints are exact in Python at any width; BigInt keeps that (and normalises `-0`).
-    return /[.eE]/.test(value.source) ? pyFloat(value.value) : BigInt(value.source).toString();
-  }
-  if (typeof value === 'number') {
-    throw new TypeError(`pyStr got a bare number (${value}); parse JSON with parseJson so `
-      + `int 1 and float 1.0 stay distinguishable, as they are in Python`);
-  }
-  throw new TypeError(`pyStr has no Python-agreeing rendering for ${typeof value}`);
-}
-
-/**
- * `repr(value)` for the values a theme or an override file can hold.
- *
- * Python quotes strings with `'`, switching to `"` only when the string contains a `'`
- * and no `"`, and spells the three singletons with a capital. Anything else is a
- * container, whose repr differs structurally; guessing at a rendering would be worse
- * than failing, so it falls through to `pyStr`.
- *
- * Lives here rather than beside its first caller because `pyAscii` below is the same
- * function with one more escaping rule, and two copies of the quote choice would be two
- * things to keep in agreement.
- *
- * Containers ARE rendered, unlike in `pyStr`, and the difference is not an inconsistency.
- * `pyStr` interpolates into an emitted file, where a shape nobody decided the semantics
- * for must be a question rather than a guessed byte. `repr` renders a value into a WARNING
- * about that very value — a list in `.geneseed-srcdirs.json` is precisely what the warning
- * exists to report, and throwing there would turn "this file is corrupt" into a crash. The
- * value always came from JSON, so the type set is closed and the rendering is exact.
- */
-function pyReprImpl(v, ascii) {
-  if (typeof v === 'string') {
-    let body = '';
-    for (const ch of v) {                 // by CODE POINT: `\U########` is one escape
-      const cp = ch.codePointAt(0);
-      if (ch === '\\') body += '\\\\';
-      else if (ch === '\n') body += '\\n';
-      else if (ch === '\r') body += '\\r';
-      else if (ch === '\t') body += '\\t';
-      else if (cp < 0x20 || cp === 0x7f) body += `\\x${cp.toString(16).padStart(2, '0')}`;
-      else if (cp < 0x7f) body += ch;
-      else if (!ascii) body += ch;        // repr() keeps printable non-ASCII verbatim
-      else if (cp <= 0xff) body += `\\x${cp.toString(16).padStart(2, '0')}`;
-      else if (cp <= 0xffff) body += `\\u${cp.toString(16).padStart(4, '0')}`;
-      else body += `\\U${cp.toString(16).padStart(8, '0')}`;
-    }
-    // The quote choice reads the ESCAPED body, which is safe: no escape sequence above
-    // introduces a quote character, so a `'` or `"` in it came from the input.
-    return body.includes("'") && !body.includes('"')
-      ? `"${body}"`
-      : `'${body.replaceAll("'", "\\'")}'`;
-  }
-  if (v === null) return 'None';
-  if (v === true) return 'True';
-  if (v === false) return 'False';
-  if (Array.isArray(v)) return `[${v.map((x) => pyReprImpl(x, ascii)).join(', ')}]`;
-  if (typeof v === 'object' && !(v instanceof PyNumber)) {
-    // JSON object keys are always strings, so `repr(key)` is the string branch above.
-    return `{${Object.entries(v)
-      .map(([k, x]) => `${pyReprImpl(k, ascii)}: ${pyReprImpl(x, ascii)}`)
-      .join(', ')}}`;
-  }
-  return pyStr(v);
-}
-
-export function pyRepr(v) {
-  return pyReprImpl(v, false);
-}
-
-/**
- * `ascii(value)` — `repr()` with every non-ASCII character escaped as well.
- *
- * Used where a warning quotes a value that came out of a file a user (or another tool)
- * may have written: `build`'s prune guard names the suspicious dir name it refused to
- * delete from `.geneseed-srcdirs.json`. Escaping is the point — a dir name carrying a
- * newline or a right-to-left override must be readable in the warning, not act on the
- * terminal, and Python already made that choice by spelling it `ascii()` rather than an
- * f-string.
- *
- * The two share ONE implementation on purpose. The first draft gave `pyAscii` its own
- * container and quote handling, and a mutation exposed the consequence immediately:
- * `pyRepr`'s container branches became unreachable, so half of the code was dead and
- * neither copy's escaping could drift without the other silently keeping the gate green.
- */
-export function pyAscii(v) {
-  return pyReprImpl(v, true);
-}
-
 /**
  * `print()` — the two output funnels, with Python's newline translation reproduced.
  *
@@ -505,27 +111,27 @@ export function pyAscii(v) {
  * universal newlines on the way back, folding both shapes to `\n` before any cell compares
  * them, the same shape as the shim's exclusion from `golden.py`. So the gate for it is
  * `test_the_two_entry_points_agree_on_stdout_BYTES`, which captures raw bytes. Moved here
- * from `js/hooks.mjs` in P5c, when `js/excludes.mjs` became the second caller: a translation
+ * from `js/hosts/hooks.mjs` in P5c, when `js/inspect/excludes.mjs` became the second caller: a translation
  * that exists twice is a translation that can be fixed once.
  */
 const xlate = (s) => (EOL === '\n' ? s : s.replaceAll('\n', EOL));
-export const pyPrint = (s) => process.stdout.write(xlate(s));
-export const pyPrintErr = (s) => process.stderr.write(xlate(s));
+export const printOut = (s) => process.stdout.write(xlate(s));
+export const printErr = (s) => process.stderr.write(xlate(s));
 
 /**
  * Hold `fn`'s stderr, and emit it only if `fn` RETURNS.
  *
  * The reproduction of `except SystemExit` for a port that writes its refusal at the raise
- * site (`js/generate.mjs`'s `sysExit` docblock states the convention). `sys.exit(msg)`
+ * site (`js/build/generate.mjs`'s `sysExit` docblock states the convention). `sys.exit(msg)`
  * attaches the message to the EXCEPTION and the interpreter prints it on the way out, so a
  * Python caller that catches sees no output at all — which makes write-at-the-raise-site
  * identical for every caller that lets the throw propagate, and wrong for every caller that
  * catches.
  *
- * MOVED HERE beside `pyPrintErr`, whose writes it intercepts, when the hook became the
- * second and third such caller: `js/hosts.mjs`'s `expanduser` refuses a `~user` path by
- * printing and throwing, and `js/hooks.mjs` catches it twice — once per `excludes.json`
- * entry and once around `$GENESEED_ROOT`/`--root`. Its old docblock in `js/doctor.mjs`
+ * MOVED HERE beside `printErr`, whose writes it intercepts, when the hook became the
+ * second and third such caller: `js/hosts/hosts.mjs`'s `expanduser` refuses a `~user` path by
+ * printing and throwing, and `js/hosts/hooks.mjs` catches it twice — once per `excludes.json`
+ * entry and once around `$GENESEED_ROOT`/`--root`. Its old docblock in `js/inspect/doctor.mjs`
  * warned that a general helper "would invite a second caller that wanted silence the
  * noise". That warning stands and is the contract: this is for a message that belonged to
  * an exception NOBODY LET ESCAPE, never for quieting output a call legitimately makes —
@@ -546,18 +152,19 @@ export function withDiscardableStderr(fn) {
 }
 
 /**
- * The same rule applied to a whole CALL rather than to one string — `bin/geneseed.mjs`'s
+ * The same rule applied to a whole CALL rather than to one string — `bin/build-driver.mjs`'s
  * answer to the newline item P5e recorded and could not gate.
  *
- * WHY THE DRIVER NEEDS A FUNNEL WHERE EVERY OTHER CALLER NEEDS `pyPrint`. The generator
- * prints from ~25 sites across `bin/geneseed.mjs`, `js/emit.mjs`, `js/settings.mjs`,
- * `js/opencode.mjs`, `js/native.mjs` and `js/render.mjs`, and those modules are ALSO the
- * body of the `GENESEED_NO_JS` seam child, whose `main` buffers both streams and hands them
- * to a Python parent that re-prints them through `print()`. Converting those sites to
- * `pyPrint` would translate once in Node and again in Python — `\r\r\n` on every line, on the
- * path `tests/golden.py` drives 259 times. So the translation belongs to whichever process
- * OWNS the stream, and the seam child does not own it. This wraps the driver's `main`, and
- * only the driver's `main`.
+ * WHY THE DRIVER NEEDS A FUNNEL WHERE EVERY OTHER CALLER NEEDS `printOut`. The generator
+ * prints from ~25 sites across `bin/build-driver.mjs`, `js/build/bundle.mjs`, `js/hosts/settings.mjs`,
+ * `js/hosts/opencode.mjs`, `js/hosts/native.mjs` and `js/build/render.mjs`, and those modules are ALSO the
+ * body of what used to be a seam child, whose `main` buffered both streams and handed them
+ * to a Python parent that re-printed them through `print()`. Converting those sites to
+ * `printOut` would have translated once in Node and again in Python — `\r\r\n` on every line.
+ * So the translation belongs to whichever process OWNS the stream, and that child did not.
+ * This wraps the driver's `main`, and equally the four render entry points the CLI can reach
+ * WITHOUT `main` on the stack: `parseDriverArgs`, `buildInto`, `emitProjectInto` and
+ * `emitGlobalInto`.
  *
  * The item it closes: a plain `--emit files` handed its caller 104 bytes where `python
  * build.py` handed over 105, and `tests/golden.py`'s `text=True` capture folds both to the
@@ -569,7 +176,7 @@ export function withDiscardableStderr(fn) {
  * path writes binary to a stream, so translating one would be corrupting data rather than
  * reproducing Python.
  */
-export function withPyNewlines(fn) {
+export function withPlatformNewlines(fn) {
   if (EOL === '\n') return fn();
   const outW = process.stdout.write.bind(process.stdout);
   const errW = process.stderr.write.bind(process.stderr);
@@ -586,332 +193,3 @@ export function withPyNewlines(fn) {
   }
 }
 
-/**
- * `len(s)` — CODE POINTS, where `String.length` counts UTF-16 units.
- *
- * They differ on every astral character: `len("𝔊")` is 1 and `"𝔊".length` is 2. Only
- * matters where a length becomes layout, which is exactly what the status panel does with
- * it — a theme name or a memory path outside the BMP would shear the frame by one column
- * per character under `.length`.
- */
-export const pyLen = (s) => [...s].length;
-
-/**
- * `str.ljust(width)` — pad with spaces to `width` CODE POINTS, never truncate.
- *
- * `String.padEnd` counts UTF-16 units, so it is `pyLen`'s difference again, one call later.
- */
-export const pyLjust = (s, width) => s + ' '.repeat(Math.max(0, width - pyLen(s)));
-
-/**
- * `str(PurePath(s))` — separators normalised to the platform's, `.` components dropped,
- * duplicate separators collapsed, a trailing one removed.
- *
- * `path.normalize` is NOT this: it also collapses `a/../b` to `b`, and `PurePath` keeps the
- * `..` because a symlinked `a` makes those two different directories. The distinction is
- * live in `js/excludes.mjs`, where a hand-edited `excludes.json` entry is compared against a
- * RESOLVED repo path — Python never matches a `..` entry there, and a normalising port would
- * match it and unwire a file the reference would have left alone.
- */
-/**
- * `shutil.which(cmd, path=None)` — the first executable named `cmd` on PATH, or null.
- *
- * `doctor` runs `node --check` over the OpenCode plugins and SKIPS the whole check when node
- * is not on PATH. `process.execPath` is not that: it is always set, so a port that used it
- * would run the check in a world where the reference silently declines to — the divergence a
- * PATH-removal refutation is aimed at, and the reason this is a real lookup rather than one
- * line of "we are node, we know where node is".
- *
- * The Windows half is the part with behaviour in it, and three of its four rules were
- * MEASURED against CPython 3.13 rather than assumed. `PATHEXT` supplies the suffixes, and the
- * returned path carries PATHEXT's OWN SPELLING of the extension rather than the file's
- * (`zzcmd.CMD` for a `zzcmd.cmd` on disk). An extension already in that set means the command
- * is spelled in full. An EMPTY PATH entry is not skipped either: `join('', cmd)` is a
- * relative path, and Python answers with one.
- *
- * THE FOURTH RULE IS THE CURRENT DIRECTORY, and it was measured on a machine that could not
- * see it. `shutil.which` prepends `os.curdir` to the search — even to a `path=` given
- * explicitly — when `_winapi.NeedCurrentDirectoryForExePath` says so, and that Win32 call
- * answers TRUE unless `NoDefaultCurrentDirectoryInExePath` is DEFINED in the environment.
- * Git Bash and this repo's developer machine both define it, so the reference answered None
- * there and the first draft's "the current directory is NOT prepended — it was until 3.12"
- * described an environment variable it had mistaken for a version change. GitHub's Windows
- * runner does not define it: the reference answered `.\\geneseed.CMD` for a `geneseed` looked
- * up beside the repo root, this returned null, and the parity corpus said so on the first CI
- * run. The variable is an INPUT, so it is read here rather than baked, and
- * `test_the_curdir_rule_agrees_in_both_environment_states` runs the corpus with it both ways.
- *
- * Gated as a pure function over a seeded directory in `tests/test_pure_function_parity.py`:
- * a cell can only ever observe the one answer this machine's PATH gives.
- */
-export function pyWhich(cmd, searchPath = null) {
-  const win = process.platform === 'win32';
-  const isExec = (p) => {
-    try {
-      if (!statSync(p).isFile()) return false;
-      accessSync(p, X_OK);
-      return true;
-    } catch { return false; }
-  };
-  // A command with a directory separator is not looked up at all — Python checks it as given.
-  if (cmd.includes('/') || (win && cmd.includes('\\'))) return isExec(cmd) ? cmd : null;
-  const exts = win
-    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
-    : [];
-  const spelled = win && exts.some((e) => cmd.toLowerCase().endsWith(e.toLowerCase()));
-  // `os.path.join`, which CONCATENATES where `path.join` NORMALISES. The difference shows the
-  // moment a PATH entry is spelled with the other separator — routine on Windows, where Git
-  // Bash and MSYS put forward-slash entries in it — and the answer is the string a caller
-  // then spawns. Measured: the corpus case with a posix-spelled directory was the one that
-  // differed, and `path.join` had rewritten the whole path rather than appending to it.
-  const joinRaw = (dir, name) => (
-    dir === '' || /[\\/]$/.test(dir) || (win && dir.endsWith(':'))
-      ? dir + name : dir + path.sep + name);
-  const dirs = (searchPath ?? process.env.PATH ?? '').split(path.delimiter);
-  // `NeedCurrentDirectoryForExePath(cmd)`: TRUE — so `.` goes in FRONT — unless the variable
-  // is defined. Only reachable with a separator-free `cmd`, which is the only way execution
-  // gets this far. Inserted before the dedupe, exactly where `shutil.which` inserts it, so a
-  // PATH that already names `.` is searched once.
-  if (win && process.env.NoDefaultCurrentDirectoryInExePath === undefined) dirs.unshift('.');
-  const seen = new Set();
-  for (const dir of dirs) {
-    const key = win ? dir.toLowerCase() : dir;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    for (const ext of (!win || spelled ? [''] : exts)) {
-      const candidate = joinRaw(dir, cmd + ext);
-      if (isExec(candidate)) return candidate;
-    }
-  }
-  return null;
-}
-
-/**
- * `pathlib.Path(s).is_absolute()`, which is NOT `path.isAbsolute(s)` on Windows.
- *
- * MEASURED against CPython 3.13, and the two disagree on exactly one shape: a ROOTLESS
- * absolute path. `/x/AGENT.md` and `\x\AGENT.md` are `True` to `path.isAbsolute` and `False`
- * to Python, which requires a DRIVE (`C:/x`) or a UNC root (`//server/share/x`) before it
- * calls a Windows path absolute. `C:x/AGENT.md` — a drive-RELATIVE path — is False to both.
- * On POSIX the two rules coincide and this is `s.startsWith('/')`.
- *
- * Written in P5h for `installAgentEntry`, which filters an OpenCode config's `instructions`
- * for the entries that are NOT absolute in order to tell a project install's relative
- * `…/AGENT.md` from a global install's absolute one. A hand-edited config naming
- * `/repo/AGENT.md` is the reachable input: Python keeps that entry and Node would have
- * skipped it and fallen through to the literal `AGENT.md`, unwiring nothing.
- *
- * ONE OWNER, and the five pre-existing `path.isAbsolute` calls in `js/` were READ rather than
- * assumed to be copies. Three cannot reach the divergence — `js/doctor.mjs` and
- * `bin/geneseed.mjs` test the output of `path.relative`, which is never rootless-absolute,
- * and `js/emit.mjs`'s `safePriorDirName` is `&&`-guarded by `basename(p) === p` immediately
- * after. The two in `js/hooks.mjs` (a context entry's `path`) DO carry the same hazard and
- * are deliberately not repointed here: that is the hook entry's shipped behaviour, no
- * `context` cell varies it, and changing it in this phase would be an ungated edit to a verb
- * that crossed three phases ago. Recorded in the spec's "Still owed" with this reproduction.
- *
- * Gated by a corpus in `tests/test_pure_function_parity.py`: no cell can vary the shape.
- */
-export function pyIsAbsolute(s) {
-  if (process.platform !== 'win32') return s.startsWith('/');
-  // Python is absolute iff the path has a DRIVE (or UNC share) *and* a root — `C:x` has the
-  // drive and no root, `/x` has the root and no drive, and neither is absolute. In
-  // `path.parse` terms that is exactly "the root is longer than a bare separator AND ends in
-  // one": `C:` for `C:x`, `\` for `\x`, `C:\` for `C:\x`, `\\srv\share\` for a UNC path.
-  // The first draft tested `root !== '\\'`, which called `C:x` absolute; the corpus caught
-  // it on the two drive-relative cases and nothing else would have.
-  const root = path.parse(s).root;
-  return root.length > 1 && /[\\/]$/.test(root);
-}
-
-/**
- * `int(s)` for a base-10 string — the VALUE, or null where Python raises `ValueError`.
- *
- * Null rather than a throw because both call sites branch on the failure rather than
- * propagate it: `askChoice` falls through to matching the answer against the option KEYS,
- * and `javaMajorOk` treats an unparseable major as "not new enough". Python spells the same
- * two branches as `except ValueError`.
- *
- * Three things separate this from `Number(s)` and each one changes an answer:
- *
- *   * `Number('')` is 0 and `int('')` raises. So is `Number(' ')`, and `Number('0x10')` is
- *     16 where `int('0x10')` raises — a wizard answer of `0x2` must fall through to the key
- *     match, not select option 16.
- *   * PEP 515 underscores: `int('1_0')` is 10, `Number('1_0')` is NaN. Leading, trailing and
- *     doubled ones still raise, so the rule is "between digits" and not "strip them".
- *   * `int()` accepts any Unicode decimal digit — `int('٣')` is 3 — and `Number('٣')` is NaN.
- *     Every `Nd` block is exactly ten contiguous code points, so a digit's value is its
- *     offset from the first `Nd` code point at or below it, which is what the walk finds.
- *
- * Surrounding whitespace is Python's to strip and both callers have already done it, so this
- * does NOT strip: `int(' 1')` is 1, but reproducing that here would need Python's
- * `str.isspace()` set, which is a separate standing item.
- *
- * Gated by a corpus in `tests/test_pure_function_parity.py` — a primitive reproduction gets
- * one owner and a corpus, never a cell (P5c).
- */
-export function pyInt(s) {
-  if (typeof s !== 'string' || s === '') return null;
-  let body = s;
-  let sign = 1;
-  if (body[0] === '+' || body[0] === '-') {
-    if (body[0] === '-') sign = -1;
-    body = body.slice(1);
-  }
-  const chars = [...body];
-  if (chars.length === 0) return null;
-  let value = 0n;
-  let prevWasDigit = false;
-  for (const ch of chars) {
-    if (ch === '_') {
-      // Only BETWEEN digits: a leading, trailing or doubled underscore is a ValueError.
-      if (!prevWasDigit) return null;
-      prevWasDigit = false;
-      continue;
-    }
-    if (!/^\p{Nd}$/u.test(ch)) return null;
-    const cp = ch.codePointAt(0);
-    let zero = cp;
-    while (zero > 0 && /^\p{Nd}$/u.test(String.fromCodePoint(zero - 1))) zero -= 1;
-    value = value * 10n + BigInt(cp - zero);
-    prevWasDigit = true;
-  }
-  if (!prevWasDigit) return null;   // a trailing underscore
-  return Number(sign === -1 ? -value : value);
-}
-
-/**
- * `str(Path(x))` — and it is PLATFORM-SHAPED, because `Path` is.
- *
- * `Path` is `WindowsPath` on Windows and `PosixPath` everywhere else, and the two parsers
- * disagree about the two things below. A body that is right on one host is therefore wrong
- * on the other, which is exactly how this one passed a whole Windows suite and failed two
- * cases on the first Linux run of `tests/test_pure_function_parity.py`:
- *
- *   * SEPARATORS. `ntpath` treats `\` and `/` alike; `posixpath` treats `\` as an ordinary
- *     filename character. `str(PurePosixPath('C:\\x\\bin\\'))` is that string VERBATIM —
- *     one component, trailing backslash and all — where splitting on both answered
- *     `C:/x/bin`. A backslash is legal in a Linux filename, so this is not academic.
- *   * THE DOUBLE-SLASH ROOT. POSIX gives EXACTLY two leading slashes an
- *     implementation-defined meaning and `PurePosixPath` preserves them; three or more
- *     collapse to one. `path.posix.parse` reports a one-character root for every case, so
- *     `//server/share` came back as `/server/share`.
- *
- * NOT reproduced, and named here rather than left as a gap nobody wrote down: `//` and
- * `///x` on WINDOWS, where `PureWindowsPath` answers `\\` and `\\\x` and this answers `\`
- * and `\x`. Those are incomplete UNC prefixes and matching them needs ntpath's share-name
- * parsing; both inputs are kept OUT of the corpus in `tests/test_pure_function_parity.py`
- * instead of sitting in it wrong.
- *
- * The root's separators are still rewritten ONE AT A TIME, never `replace(/[\\/]+/g, sep)`:
- * a UNC root's leading pair is part of it, so collapsing runs turns `//server/share/x` into
- * `\server\share\x`.
- */
-export function pyPathStr(s) {
-  const win = path.sep === '\\';
-  let raw = path.parse(s).root;
-  if (!win && raw && /^\/\/(?!\/)/.test(s)) raw = '//';
-  const root = raw.replace(/[\\/]/g, path.sep);
-  const seps = win ? /[\\/]+/ : /\/+/;
-  const parts = s.slice(raw.length).split(seps).filter((p) => p !== '' && p !== '.');
-  const tail = parts.join(path.sep);
-  if (!root) return tail || '.';
-  return root + tail;
-}
-
-/**
- * `urllib.parse.unquote(s)` — percent-decoding as Python does it, which is NOT
- * `decodeURIComponent`.
- *
- * The whole difference is what happens to a sequence that is not an escape.
- * `decodeURIComponent('a%ZZ')` throws a `URIError`, and so does a trailing bare `%`; the
- * web shell would answer both as a 500 where the reference answers a 404 naming the
- * literal text. `unquote` leaves them alone: CPython builds a table of every two-hex-digit
- * pair in both cases and treats a `KeyError` as "this was not an escape", emitting `%` and
- * the rest of the fragment verbatim.
- *
- * The outer split on `([\x00-\x7f]+)` is Python's too, and it is not decoration: only the
- * ASCII runs are candidates for decoding, so a literal non-ASCII character already in the
- * path is passed through rather than mixed into the byte buffer. Consecutive escapes ARE
- * accumulated before decoding, which is what makes `%C3%A9` one `é` and not two
- * replacement characters.
- *
- * `Buffer.toString('utf-8')` substitutes U+FFFD for an undecodable sequence, which is
- * `errors='replace'`. The two decoders can disagree on HOW MANY replacement characters a
- * truncated multi-byte sequence yields — Python's maximal-subpart rule against WHATWG's —
- * and the corpus in `tests/test_pure_function_parity.py` is where that is measured rather
- * than assumed.
- */
-const HEX_PAIR = /^[0-9A-Fa-f]{2}$/;
-
-function unquoteToBytes(run) {
-  const bits = run.split('%');
-  if (bits.length === 1) return Buffer.from(run, 'latin1');
-  const out = [Buffer.from(bits[0], 'latin1')];
-  for (const item of bits.slice(1)) {
-    const pair = item.slice(0, 2);
-    if (HEX_PAIR.test(pair)) {
-      out.push(Buffer.from([parseInt(pair, 16)]), Buffer.from(item.slice(2), 'latin1'));
-    } else {
-      out.push(Buffer.from(`%${item}`, 'latin1'));
-    }
-  }
-  return Buffer.concat(out);
-}
-
-export function pyUnquote(s) {
-  if (!s.includes('%')) return s;
-  // `re.split` with ONE capture group alternates [gap, group, gap, group, …], so the ASCII
-  // runs are the odd indices on both sides.
-  const bits = s.split(/([\x00-\x7f]+)/);
-  let res = bits[0];
-  for (let i = 1; i < bits.length; i += 2) {
-    res += unquoteToBytes(bits[i]).toString('utf-8');
-    res += bits[i + 1] ?? '';
-  }
-  return res;
-}
-
-/**
- * Python's `\s` for a `str` pattern, as a character-class BODY — measured, not recalled.
- *
- * The two languages' whitespace classes are nearly the same and the difference had been
- * carried as a standing item reading "differing from JS `\s` only at U+FEFF". That was
- * incomplete in both directions, and a corpus over `slugifyHeading` is what found it:
- *
- *     python \s = js \s  -  U+FEFF  +  U+001C..U+001F  +  U+0085
- *
- * JavaScript counts the byte-order mark as whitespace and Python does not; Python counts
- * the four C0 information separators and the NEL, and JavaScript does not. Neither shows
- * up in a docs heading anyone has written — which is exactly why it took a corpus rather
- * than a cell, and why it is spelled out here rather than approximated with `\s`.
- */
-export const PY_SPACE = '\t\n\v\f\r \u001c-\u001f\u0085\u00a0\u1680'
-  + '\u2000-\u200a\u2028\u2029\u202f\u205f\u3000';
-
-const PY_STRIP_RE = new RegExp(`^[${PY_SPACE}]+|[${PY_SPACE}]+$`, 'g');
-const PY_LSTRIP_RE = new RegExp(`^[${PY_SPACE}]+`);
-const PY_RSTRIP_RE = new RegExp(`[${PY_SPACE}]+$`);
-
-/** `str.strip()` — Python's whitespace set, which `String.trim()`'s is not. */
-export function pyStripSpace(s) {
-  return s.replace(PY_STRIP_RE, '');
-}
-
-/**
- * `str.lstrip()` / `str.rstrip()` — the ONE-SIDED halves, over the same `PY_SPACE`.
- *
- * P2 added them for `_build_render._insert_theme_keys`, which uses all three spellings within
- * four lines (`lines[0].strip()`, `ln.lstrip().startswith('"')`,
- * `lines[pred].rstrip().endswith(",")`). They are here rather than in `js/themes.mjs` for the
- * reason this file exists at all: `js/settings.mjs` already carries a private second copy of
- * the character class, and a THIRD one — in the module that decides where a comma goes in a
- * committed theme file — is how the three drift apart. One owner of the set, three views of it.
- */
-export function pyLStripSpace(s) {
-  return s.replace(PY_LSTRIP_RE, '');
-}
-
-export function pyRStripSpace(s) {
-  return s.replace(PY_RSTRIP_RE, '');
-}