geneseed 2.0.0

package/js/excludes.mjs

@@ -0,0 +1,271 @@
+/**
+ * `rituals/_harness_exclude.py` — the sovereign-repo exclusion WRITER.
+ *
+ * THE READER WAS ALREADY HERE. `js/hooks.mjs` has carried `sovereignBypass`, `EXCLUDES_FILE`
+ * and `EXCLUDE_DIRS` since P5a: every hook call reads `excludes.json` and stands down when
+ * cwd is under an excluded folder. This module is the other half — `harness exclude
+ * add|remove|list`, which maintains that file across every global install and wires the
+ * host-native per-repo suppression into the excluded repo.
+ *
+ * THE PYTHON WRITER STAYS, AND THAT IS A DECISION RATHER THAN AN OMISSION.
+ * `rituals/_web_actions.py:371-390` calls `excludes_snapshot()`, `exclude_add` and
+ * `exclude_remove` "verbatim: this endpoint owns no exclusion logic of its own", and the web
+ * server is P6. So until that phase there are two writers for one user-owned file. What
+ * makes that survivable is what makes it survivable for the machine-wide hook shim: the two
+ * implementations are held byte-equal by `tests/harness_golden.py`, which runs every cell
+ * against both and compares stdout, stderr, the exit code and every file left behind. What
+ * it does NOT cover is two processes writing at the same instant — `_write_excludes` is
+ * temp-plus-rename on both sides, so a concurrent pair loses one edit rather than tearing
+ * the file, which is the same guarantee the single-writer version had against itself.
+ *
+ * Every path a hook takes on this file is READ-only, so nothing here is on the PreToolUse
+ * latency budget — which is why it lives beside the CLI and not in `js/hooks.mjs`.
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync, unlinkSync }
+  from 'node:fs';
+import path from 'node:path';
+import { EXCLUDES_FILE, EXCLUDES_STUB, BOB_RULES_STUB } from './emit.mjs';
+import { wireClaudeExcludes, unwireClaudeExcludes } from './settings.mjs';
+import { GLOBAL_MANIFEST, HOSTS, pyResolve } from './hosts.mjs';
+import {
+  readText, writeText, parseJson, jsonDumpsIndent, normcase, pyPathStr, pyPrint, pyPrintErr,
+} from './lib/fs.mjs';
+
+const get = (o, k) => (o && Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined);
+const isDict = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const isOsError = (e) => Boolean(e) && typeof e.code === 'string';
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
+
+/** `_global_installs` — every host whose GLOBAL config dir carries a Geneseed manifest. */
+export function globalInstalls() {
+  const out = [];
+  for (const { host, configDir } of HOSTS) {
+    let cfg;
+    try {
+      cfg = configDir();
+    } catch {
+      continue;   // a broken resolver must not kill the CLI, as the Python's bare `except`
+    }
+    if (isFile(path.join(cfg, GLOBAL_MANIFEST))) out.push({ host, cfg });
+  }
+  return out;
+}
+
+/** `_read_excludes` — the file, or the seeded stub's shape when it is absent or unusable. */
+function readExcludes(cfg) {
+  try {
+    const data = parseJson(readText(path.join(cfg, EXCLUDES_FILE)));
+    if (isDict(data) && Array.isArray(get(data, 'excludes'))) return data;
+  } catch (e) {
+    if (!isOsError(e) && !(e instanceof SyntaxError)) throw e;
+  }
+  return parseJson(EXCLUDES_STUB);   // one source of truth with the seeded stub
+}
+
+/**
+ * `_write_excludes` — atomic (temp + rename), because a torn `excludes.json` would degrade
+ * every hook to "not excluded" until repaired.
+ *
+ * `writeText`, not `writeFileSync`: `Path.write_text` translates the trailing `\n` to CRLF on
+ * Windows, and this file is compared byte-for-byte in every cell that writes one.
+ */
+function writeExcludes(cfg, data) {
+  const dest = path.join(cfg, EXCLUDES_FILE);
+  const tmp = `${dest}.tmp`;
+  writeText(tmp, `${jsonDumpsIndent(data)}\n`);
+  renameSync(tmp, dest);
+}
+
+/** `_canon` — `Path(p).expanduser().resolve()`. */
+const canon = (p) => pyResolve(p);
+
+/**
+ * `_same` — is this stored entry the same folder as `repo`?
+ *
+ * `pyPathStr` and not `path.normalize`: the latter collapses `a/../b` to `b`, and Python's
+ * `Path()` does not, so a hand-edited entry carrying `..` matches here and would not match
+ * there. Getting that backwards makes `exclude remove` unwire a repo the reference left
+ * alone.
+ */
+function same(stored, repo) {
+  if (typeof stored !== 'string' || !stored) return false;
+  return normcase(pyPathStr(stored)) === normcase(repo);
+}
+
+/**
+ * `exclude_add` — add `path` to every global install's list and wire the per-repo
+ * suppression. Idempotent; returns `{ok, path, messages}`.
+ */
+export function excludeAdd(target) {
+  const repo = canon(target);
+  const messages = [];
+  if (!isDir(repo)) messages.push(`warning: ${repo} does not exist (excluded anyway)`);
+  const installs = globalInstalls();
+  if (!installs.length) {
+    return { ok: false, path: repo,
+      messages: ['no global Geneseed install found — nothing to exclude from'] };
+  }
+  for (const { host, cfg } of installs) {
+    const data = readExcludes(cfg);
+    const prior = data.excludes.find((e) => isDict(e) && same(get(e, 'path'), repo));
+    const priorWired = (isDict(prior) ? get(prior, 'wired') : null) || {};
+    const wired = {};
+    if (host === 'claude' && isDir(repo)) {
+      const entry = pyResolve(path.join(cfg, 'CLAUDE.md')).split(path.sep).join('/');
+      const added = wireClaudeExcludes(
+        path.join(repo, '.claude', 'settings.local.json'), [entry]);
+      if (added.length) {
+        wired.claude_md_excludes = added;
+      } else if (get(priorWired, 'claude_md_excludes')) {
+        // Idempotent re-add: OUR own prior excludeAdd call genuinely wired this entry
+        // (confirmed by the manifest record), so ownership carries forward even though
+        // wireClaudeExcludes reports nothing NEW this time.
+        wired.claude_md_excludes = get(priorWired, 'claude_md_excludes');
+      }
+      // else: the entry was already present for some OTHER reason (e.g. a project install's
+      // own project-bypasses-global wiring, or a bailed write) — do NOT fabricate ownership,
+      // or a later excludeRemove would strip wiring we never created.
+      if (!added.length) messages.push(`${host}: claudeMdExcludes already present (kept)`);
+    }
+    if (host === 'bob' && isDir(repo)) {
+      const stub = path.join(repo, '.bob', 'rules', 'geneseed.md');
+      if (existsSync(stub)) {
+        // Ownership is decided by CONTENT, not mere existence — a re-add finds a stub that
+        // already exists because WE wrote it last time; an existence-only check would misread
+        // that as user content and orphan it on the next remove. Exact match means ours.
+        let ours;
+        try {
+          ours = readText(stub) === BOB_RULES_STUB;
+        } catch (e) {
+          if (!isOsError(e)) throw e;
+          ours = false;
+        }
+        wired.bob_rules_stub = ours;
+        if (!ours) messages.push(`${host}: rules/geneseed.md already exists (kept, not ours)`);
+      } else {
+        mkdirSync(path.dirname(stub), { recursive: true });
+        writeText(stub, BOB_RULES_STUB);
+        wired.bob_rules_stub = true;
+      }
+    }
+    if (host === 'copilot') {
+      messages.push('copilot: no native suppression exists — the global '
+        + 'copilot-instructions.md still loads there (documented limitation)');
+    }
+    const entries = data.excludes.filter((e) => !(isDict(e) && same(get(e, 'path'), repo)));
+    entries.push({ path: repo.split(path.sep).join('/'), wired });
+    data.excludes = entries;
+    writeExcludes(cfg, data);
+  }
+  return { ok: true, path: repo, messages };
+}
+
+/**
+ * `exclude_remove` — reverse `excludeAdd`: unwire exactly what `wired` recorded, then drop
+ * the entry from every install's list. Hand-deleted wiring is reported, not fatal.
+ */
+export function excludeRemove(target) {
+  const repo = canon(target);
+  const messages = [];
+  let found = false;
+  for (const { host, cfg } of globalInstalls()) {
+    const data = readExcludes(cfg);
+    const keep = [];
+    let mine = null;
+    for (const e of data.excludes) {
+      if (isDict(e) && same(get(e, 'path'), repo)) mine = e;
+      else keep.push(e);
+    }
+    if (mine === null) continue;
+    found = true;
+    const wired = get(mine, 'wired') || {};
+    if (get(wired, 'claude_md_excludes')) {
+      unwireClaudeExcludes(path.join(repo, '.claude', 'settings.local.json'),
+        get(wired, 'claude_md_excludes'));
+    }
+    if (get(wired, 'bob_rules_stub')) {
+      const stub = path.join(repo, '.bob', 'rules', 'geneseed.md');
+      try {
+        if (isFile(stub)) {
+          unlinkSync(stub);
+          if (!readdirSync(path.dirname(stub)).length) rmdirSync(path.dirname(stub));
+        } else {
+          messages.push(`${host}: shadow stub already gone`);
+        }
+      } catch (e) {
+        if (!isOsError(e)) throw e;
+        // KNOWN DIVERGENCE, deliberately not papered over: Python interpolates
+        // `str(OSError)` — `[Errno 13] Permission denied: '<path>'` — and `e.message` is
+        // Node's own wording. No cell can reach this branch (`unlink` on a file that
+        // `isFile` just confirmed, `rmdir` on a directory just measured empty), so a
+        // translation table here would be an unobservable guess. Same class as P5b's
+        // untested `die()` newline; `js/settings.mjs`'s `pyOsError` is the same stub for
+        // the same reason.
+        messages.push(`${host}: could not remove ${stub} (${e.message})`);
+      }
+    }
+    data.excludes = keep;
+    writeExcludes(cfg, data);
+  }
+  if (!found) messages.push(`${repo} was not excluded`);
+  return { ok: found, path: repo, messages };
+}
+
+/**
+ * `excludes_snapshot` — the union view across installs, shared by the CLI `list` and (on the
+ * Python side) the web endpoint. Also flags installs whose lists diverge: a global emit made
+ * after the exclusions were added starts with an empty stub.
+ */
+export function excludesSnapshot() {
+  const installs = globalInstalls();
+  const byPath = new Map();
+  for (const { host, cfg } of installs) {
+    for (const e of readExcludes(cfg).excludes) {
+      const p = isDict(e) ? get(e, 'path') : e;
+      if (typeof p !== 'string' || !p) continue;
+      const key = normcase(pyPathStr(p));
+      if (!byPath.has(key)) {
+        byPath.set(key, { path: p, hosts: [],
+          wired: (isDict(e) ? get(e, 'wired') : null) || {} });
+      }
+      byPath.get(key).hosts.push(host);
+    }
+  }
+  const excludes = [...byPath.values()].sort(
+    (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { excludes, installs: installs.map(({ host, cfg }) => ({ host, cfg })) };
+}
+
+/** `cmd_exclude`. */
+export function cmdExclude(args) {
+  if (args.action === 'list') {
+    const snap = excludesSnapshot();
+    if (!snap.installs.length) {
+      pyPrint('[geneseed] no global install found.\n');
+      return 1;
+    }
+    if (!snap.excludes.length) {
+      pyPrint('[geneseed] no folders excluded.\n');
+      return 0;
+    }
+    const allHosts = new Set(snap.installs.map((i) => i.host));
+    for (const rec of snap.excludes) {
+      const missing = [...allHosts].filter((h) => !rec.hosts.includes(h)).sort();
+      const flag = missing.length
+        ? `  (MISSING from: ${missing.join(', ')} — re-run \`harness exclude add\`)` : '';
+      pyPrint(`  ${rec.path}  [${rec.hosts.slice().sort().join(', ')}]${flag}\n`);
+    }
+    return 0;
+  }
+  if (!args.path) {
+    pyPrintErr('[geneseed] exclude add/remove needs a folder path.\n');
+    return 2;
+  }
+  const res = args.action === 'add' ? excludeAdd(args.path) : excludeRemove(args.path);
+  for (const m of res.messages) pyPrintErr(`[geneseed] ${m}\n`);
+  const verb = args.action === 'add' ? 'excluded' : 're-included';
+  pyPrint(res.ok ? `[geneseed] ${res.path} ${verb}.\n`
+    : `[geneseed] nothing done for ${res.path}.\n`);
+  return res.ok ? 0 : 1;
+}

package/js/generate.mjs

@@ -0,0 +1,379 @@
+/**
+ * `rituals/_harness_build.py`'s three cheap verbs — `build`, `prompt` and `theme`.
+ *
+ * These are the harness's GENERATOR FACE: the subcommands whose whole job is to drive the
+ * thing `bin/geneseed.mjs` already is. That is why they are the cheapest slice left and why
+ * they are the last one that can be measured by a closure walk alone — `cmd_build`'s body is
+ * three lines because the work is a `subprocess`, and a name walk cannot see through one.
+ *
+ * WHY `build` IMPORTS THE DRIVER RATHER THAN SPAWNING IT. The Python is
+ * `run([sys.executable, BUILD, *extra]).returncode` — a passthrough to a second process.
+ * Reproducing that shape here would mean spawning `node bin/geneseed.mjs`, and
+ * `test_the_cli_reaches_no_child_process_module` forbids it: the ban is transitive over this
+ * entry's imports, and P5c's argument for keeping it is that `web`, `upgrade` and `setup`
+ * will genuinely need to spawn, so the ban should outlive them rather than be dismantled by
+ * a verb that does not. It is also the wrong shape on its own terms. Python needs a second
+ * process because `build.py` is a different PROGRAM; `bin/geneseed.mjs` is a module in this
+ * one, and a Node CLI spawning a Node driver to do work it could do in-process is exactly
+ * the passthrough the whole port has been removing. So the driver's `main` is exported and
+ * called directly, and the observable contract — the tree, the streams, the exit code — is
+ * what `build/*` in `tests/harness_golden.py` compares.
+ *
+ * WHAT NO CELL CAN REACH HERE, stated rather than left implicit. `fenceFor`'s real arm is
+ * unreachable from the matrix: measured over the whole rendered tree, the longest backtick
+ * run in any source text is 3, so `max(4, longest + 1)` picks 4 for all 96 files, and a port
+ * that hardcoded four backticks is byte-identical in every prompt cell. Reaching the other
+ * arm needs a file in `src/`, and `src/` is the tree no fixture can redirect (P5d). It is
+ * therefore gated as a pure function over a corpus in `tests/snapshot/pure_snapshot.test.mjs`, with the
+ * unreachability measured in BOTH directions rather than asserted: one test proves the corpus
+ * leaves the floor, and one re-renders every theme × posture × mode of the live tree and proves
+ * `src/` still does not. The 96 above is one render — the sweep is 13 440 files.
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { main as driverMain } from '../bin/geneseed.mjs';
+import { makeCfg } from './checkout.mjs';
+import { opencodeConfigDir, pyResolve } from './hosts.mjs';
+import {
+  EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, footprintOfDir, installState,
+  installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
+} from './installs.mjs';
+import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from './opencode.mjs';
+import { renderAll } from './render.mjs';
+import {
+  jsonDumpsIndent, parseJson, pyPrint, pyPrintErr, pyRepr, readText, writeText,
+} from './lib/fs.mjs';
+
+/** `_harness_build._HEX_RE`. Anchored at BOTH ends — `#123` and `#1122334` both fail. */
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+/**
+ * `raise SystemExit(msg)` — the message on stderr, exit 1.
+ *
+ * The convention `js/emit.mjs`'s `assertSourceComplete` set and `bin/geneseed-cli.mjs`
+ * honours: write at the raise site, mark the throw as a DELIBERATE refusal with `exitCode`,
+ * and let anything unmarked keep its stack. Python prints a traceback for an unhandled
+ * exception, so dressing a crash as a one-liner would hide a bug.
+ */
+function sysExit(msg) {
+  // `pyPrintErr`, NOT a local newline translation. The first draft inlined the `\n` ->
+  // `\r\n` rule here and every cell passed, because `harness_golden` reads stderr through
+  // `subprocess`'s universal-newline decode and cannot see the difference — the same
+  // transport hole P5b measured. A second copy of a translation is exactly what P5d's
+  // `pyStrPath`/`pyPathStr` split was, and it is ungated in precisely the same way.
+  pyPrintErr(`${msg}\n`);
+  const e = new Error(msg);
+  e.exitCode = 1;
+  throw e;
+}
+
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+// --------------------------------------------------------------------------------------
+// build
+// --------------------------------------------------------------------------------------
+
+/**
+ * `_harness_build.cmd_build` — render `src/` into `./Harness`.
+ *
+ * `--out` defaults to the RELATIVE `"Harness"` in the generator and the Python passes no
+ * `cwd=`, so the bundle lands under the invocation's directory rather than the checkout's.
+ * Calling the driver in-process keeps that: `resolveOut` resolves against `process.cwd()`
+ * the same way. `build/the-bundle-follows-cwd-not-the-checkout` is the cell.
+ *
+ * Every other flag is the generator's own default, read from `harness.config.json` by the
+ * driver — `harness build` forwards `--theme` and nothing else, and its own `--theme`
+ * carries no `choices`, so an unknown one is refused by the generator rather than here.
+ */
+export function cmdBuild(args) {
+  return driverMain(args.theme ? ['--theme', args.theme] : []);
+}
+
+// --------------------------------------------------------------------------------------
+// rebuild-all
+// --------------------------------------------------------------------------------------
+
+/**
+ * `_harness_setup._setup_build_args` — the generator argv for one selection. Pure.
+ *
+ * The elision rules are not symmetric and the Python says why: `footprint` is ALWAYS passed,
+ * because omitting it when it matched the generator's default silently coupled the answer to
+ * whatever that default happened to be — the moment the default moved, picking the old one
+ * produced the new one. `posture` and `mode` still elide at theirs, and neither has moved.
+ */
+export function setupBuildArgs(theme, emit, out = null, root = null, footprint = 'lean',
+  posture = 'peer', mode = 'direct') {
+  const argv = ['--theme', theme, '--emit', emit];
+  if (!['opencode-global', 'claude-global', 'bob-global', 'copilot-global'].includes(emit)) {
+    if (out) argv.push('--out', out);
+    if (root) argv.push('--root', root);
+  }
+  if (footprint) argv.push('--footprint', footprint);
+  if (posture && posture !== 'peer') argv.push('--posture', posture);
+  if (mode && mode !== 'direct') argv.push('--mode', mode);
+  return argv;
+}
+
+/**
+ * `_harness_build._DEFAULT_EMIT` — the emit to use for an install carrying NO marker.
+ *
+ * A pre-marker install still has a (host, scope), which is what the walk found it by, so it
+ * is rebuilt in its own mode rather than defaulted to OpenCode.
+ */
+export const DEFAULT_EMIT = new Map([
+  ['opencode global', 'opencode-global'], ['opencode project', 'opencode'],
+  ['claude global', 'claude-global'], ['claude project', 'claude'],
+  ['bob global', 'bob-global'], ['bob project', 'bob'],
+  ['copilot global', 'copilot-global'], ['copilot project', 'copilot'],
+]);
+
+/**
+ * `_harness_build.cmd_rebuild_all` — re-emit every ACTIVE install in place, best-effort.
+ *
+ * WHY THIS IS THE VERB THAT MADE THE DRIVER'S `die` A THROW. The Python spawns one
+ * `build.py` per install and reads its return code, so "continue past a failure" is what a
+ * subprocess gives you for nothing. Calling `main` in-process — the route P5e established for
+ * `build`, and the only one the `child_process` ban leaves — makes a `process.exit` inside
+ * the generator's flag parser end the whole loop instead of one install. So `die` throws and
+ * `main` converts, and `rebuild-all/one-broken-install-does-not-stop-the-rest` is the cell
+ * that fails if either half is undone.
+ *
+ * FIVE VALUES ARE READ BACK OFF EACH INSTALL, not defaulted. Theme and emit and footprint
+ * come from markers; posture and mode are detected from the `**<Name>**` lead in the
+ * deployed carrier's prose, because they were never markered. A rebuild that defaulted any
+ * of them would silently re-emit an install into something its owner did not choose — which
+ * is the same failure mode `_footprint_of_dir`'s WARN exists to prevent, at a larger scale.
+ *
+ * THE MARKER IS TRUSTED ONLY FOR ITS OWN HOST. There is one `.geneseed-emit` per root and the
+ * last deploy wins, so in a dual-host repo (`.opencode/` and `.claude/` in one cwd) the other
+ * host's row would otherwise rebuild with the WRONG emit — turning a Claude install into an
+ * OpenCode one. `rebuild-all/a-dual-host-repo-rebuilds-each-row-in-its-own-emit` is the cell.
+ */
+export function cmdRebuildAll() {
+  const targets = installTargets().filter(([h, s, r]) => installState(r, h, s) === 'active');
+  if (!targets.length) {
+    pyPrint('[rebuild-all] no active installs detected.\n');
+    return 0;
+  }
+  const failures = [];
+  for (const [host, scope, root] of targets) {
+    const raw = readMaybe(path.join(root, '.geneseed-emit'));
+    let marker = raw === null ? '' : raw.trim();
+    if (marker && (EMIT_HOST_SCOPE.get(marker) ?? ['', ''])[0] !== host) marker = '';
+    const emit = marker || DEFAULT_EMIT.get(`${host} ${scope}`) || 'opencode-global';
+    const theme = themeOfDir(root) || defaultTheme();
+    const footprint = footprintOfDir(root);
+    const posture = postureOfDir(root) || defaultPosture();
+    const mode = modeOfDir(root) || defaultMode();
+    const out = scope === 'global' ? null : root;
+    const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode);
+    const label = `${host}:${scope} (${root})`;
+    pyPrint(`[rebuild-all] ${label}: theme=${theme} emit=${emit} footprint=${footprint} `
+      + `posture=${posture} mode=${mode}\n`);
+    const rc = driverMain(argv);
+    if (rc !== 0) {
+      failures.push(label);
+      pyPrintErr(`[rebuild-all] FAILED ${label} (exit ${rc})\n`);
+    }
+  }
+  if (failures.length) {
+    pyPrintErr(`[rebuild-all] ${failures.length}/${targets.length} install(s) failed: `
+      + `${failures.join(', ')}\n`);
+    return 1;
+  }
+  pyPrint(`[rebuild-all] rebuilt ${targets.length} install(s).\n`);
+  return 0;
+}
+
+// --------------------------------------------------------------------------------------
+// prompt
+// --------------------------------------------------------------------------------------
+
+/**
+ * `_harness_build._fence_for` — a backtick fence longer than the longest run inside `text`,
+ * so an embedded code fence can never close the wrapper. Minimum four.
+ *
+ * Iterates by CODE UNIT deliberately: a backtick is ASCII, so `for...of` over code points
+ * would only cost a surrogate decode per astral character in a 400 KB document, and the
+ * count is identical either way.
+ */
+export function fenceFor(text) {
+  let longest = 0;
+  let run = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    run = text[i] === '`' ? run + 1 : 0;
+    if (run > longest) longest = run;
+  }
+  return '`'.repeat(Math.max(4, longest + 1));
+}
+
+/** `_harness_build.build_prompt` — the whole rendered tree as one install document. */
+export function buildPrompt(cfg, themeName) {
+  const { items } = renderAll(cfg, themeName);
+  const nText = items.filter((it) => it.text !== null).length;
+  const out = [
+    `# Geneseed Harness — install prompt (theme: ${themeName})`,
+    '',
+    'You are an AI agent. Recreate the Geneseed harness file tree below, writing',
+    'every file **verbatim**. No Python or build step is required.',
+    '',
+    '## Target directory',
+    'Write all files under the directory the user specifies. If none was given, ask',
+    'for it, defaulting to the current repository root. Preserve the exact relative',
+    'path shown in each file heading, creating subfolders as needed.',
+    '',
+    '## Rules',
+    "- Copy each file's content exactly — do not summarise, reflow, or edit it.",
+    '- After writing, create an empty context.json at the repo root if absent, and list the repo\'s docs in it.',
+    '- When finished, list every file you created.',
+    '',
+    `## Files (${nText} text files)`,
+  ];
+  for (const { rel, text } of items) {
+    if (text === null) {
+      out.push(`\n### \`${rel}\` (binary — copy it from the Geneseed repo)`);
+      continue;
+    }
+    const fence = fenceFor(text);
+    // `text.rstrip("\n")` — trailing newlines ONLY, so a file ending in spaces keeps them.
+    out.push(`\n### \`${rel}\``, '', fence, text.replace(/\n+$/, ''), fence);
+  }
+  return `${out.join('\n')}\n`;
+}
+
+/**
+ * `_harness_build.cmd_prompt`.
+ *
+ * Both output paths translate newlines: the Python writes the document through
+ * `sys.stdout.write` and `Path.write_text`, and BOTH are `newline=None` translators on
+ * Windows. At ~10,000 newlines in a 400 KB document that is the largest byte difference this
+ * port could ship, and `harness_golden` can only see half of it — the FILE half is compared
+ * directly, the stdout half is folded by `subprocess`'s universal-newline decode, which is
+ * why `test_the_two_entry_points_agree_on_stdout_BYTES` grew a `prompt` row.
+ */
+export function cmdPrompt(args) {
+  // `args.theme or "neutral"` — a literal in the Python, NOT the config's theme, so this
+  // deliberately does not go through `configDefaults()`.
+  const themeName = args.theme || 'neutral';
+  const text = buildPrompt(makeCfg(), themeName);
+  if (args.out) {
+    const dest = path.dirname(args.out);
+    if (dest) mkdirSync(dest, { recursive: true });
+    writeText(args.out, text);
+    // The RAW argument, not the resolved path — `f"[prompt] wrote {args.out}"`.
+    pyPrint(`[prompt] wrote ${args.out} (${themeName})\n`);
+  } else {
+    pyPrint(text);
+  }
+  return 0;
+}
+
+// --------------------------------------------------------------------------------------
+// theme
+// --------------------------------------------------------------------------------------
+
+/** `_harness_build._resolve_themes_dir` — explicit `--dir`, else a repo `.opencode/`, else global. */
+export function resolveThemesDir(args) {
+  // `Path(args.dir).expanduser().resolve()` — `pyResolve` already expands a leading `~`.
+  if (args.dir) return pyResolve(args.dir);
+  const repo = path.join(process.cwd(), '.opencode');
+  if (!args.globalDir && isDir(repo)) return path.join(repo, 'themes');
+  return path.join(opencodeConfigDir(), 'themes');
+}
+
+/**
+ * `_harness_build._load_user_palette` — `--from` seeds, `--palette` overlays, then validate.
+ *
+ * The palette is a **Map** because `pal`'s iteration order is OBSERVABLE: it is the order
+ * of the bad-value list in the refusal message, and JS hoists integer-like keys to the front
+ * of a plain object while Python's dict keeps insertion order (the P3a hazard).
+ *
+ * THE MAP IS NOT A COMPLETE FIX AND SAYING SO IS THE POINT. `JSON.parse` has already
+ * reordered by the time anything here runs — measured, not assumed: its reviver is invoked
+ * in the hoisted order too, so no parse-time hook can recover the text's order. The Map
+ * only preserves what it is handed. A palette carrying an integer-like key AND a second bad
+ * value therefore still diverges:
+ *
+ *     {"zzz": "y", "0": "x"}   python: zzz='y', 0='x'      node: 0='x', zzz='y'
+ *
+ * That is this port's oldest known difference becoming REACHABLE for the first time — every
+ * phase since P3a has carried it as a hazard no cell could reach. It is recorded rather than
+ * fixed: recovering source order means hand-scanning the JSON text, which is a reproduction
+ * of a parser (P5c's rule: those need a corpus, and this one would need one for every
+ * escaping rule) traded for the ORDER OF TWO NAMES in an error message that both
+ * implementations still emit, for the same values, with the same exit code.
+ */
+export function loadUserPalette(args, cfg) {
+  const pal = new Map();
+  if (args.fromTheme) {
+    const src = path.join(cfg.colorThemes, `${args.fromTheme}.json`);
+    if (!existsSync(src) || !statSync(src).isFile()) {
+      // `p.stem` — the filename without its extension, in `color_theme_files()` order.
+      const avail = colorThemeFiles(cfg)
+        .map((p) => path.basename(p, path.extname(p))).join(', ');
+      sysExit(`[theme] no shipped theme '${args.fromTheme}'. available: ${avail}`);
+    }
+    const spec = parseJson(readText(src));
+    for (const [k, v] of Object.entries(spec.palette ?? {})) pal.set(k, v);
+  }
+  if (args.palette) {
+    // `Path(args.palette)` — relative to cwd, with no expanduser and no resolve.
+    const raw = parseJson(readText(args.palette));
+    // `raw.get("palette", raw)` — a document with no "palette" key IS the role map.
+    const map = Object.prototype.hasOwnProperty.call(raw, 'palette') ? raw.palette : raw;
+    for (const [k, v] of Object.entries(map)) pal.set(k, v);
+  }
+  if (pal.size === 0) {
+    sysExit('[theme] need a palette: pass --from <shipped> and/or --palette <file.json>');
+  }
+  const missing = [...PALETTE_ROLES].filter((r) => !pal.has(r)).sort();
+  if (missing.length) {
+    sysExit(`[theme] palette missing role(s): ${missing.join(', ')} `
+      + '(see themes/opencode/README.md; --from seeds them all)');
+  }
+  // `f"{r}={pal[r]!r}"` — Python's repr, so a string is single-quoted and an int is bare.
+  const bad = [...pal].filter(([, v]) => !(typeof v === 'string' && HEX_RE.test(v)))
+    .map(([r, v]) => `${r}=${pyRepr(v)}`);
+  if (bad.length) sysExit(`[theme] non-#rrggbb value(s): ${bad.join(', ')}`);
+  return pal;
+}
+
+/**
+ * `_harness_build.cmd_theme` — a user colour theme in both flavours, into the live dir.
+ *
+ * The palette is validated BEFORE the destination is resolved and before `mkdir`, so a
+ * refusal leaves no directory behind — matching the Python's statement order.
+ *
+ * **THAT ORDER IS NOT OBSERVABLE, and the first draft of this comment claimed it was.**
+ * Swapping the two halves so a refusal creates the directory first is GREEN across all 166
+ * cells (M16), because `golden._snapshot` walks FILES and an empty directory leaves no file
+ * to compare. So the order is preserved because the reference has it, not because anything
+ * checks — INDISTINGUISHABLE rather than unreachable, and closing it would mean a sixth
+ * expectation kind (`expect_absent_files`) for one empty directory.
+ * `theme/an-explicit-dir-is-created` is the positive control that the `mkdir` happens at all.
+ */
+export function cmdTheme(args) {
+  const name = args.name;
+  const full = name.startsWith('geneseed-') ? name : `geneseed-${name}`;
+  const cfg = makeCfg();
+  const pal = loadUserPalette(args, cfg);
+  const destDir = resolveThemesDir(args);
+  mkdirSync(destDir, { recursive: true });
+  const flavours = args.solidOnly ? [['', false]]
+    : args.transparentOnly ? [['-transparent', true]]
+      : [['', false], ['-transparent', true]];
+  const written = [];
+  for (const [suffix, transparent] of flavours) {
+    const dest = path.join(destDir, `${full}${suffix}.json`);
+    // `Object.fromEntries` hoists integer-like keys too — harmless here and nowhere else,
+    // because `colorThemeJson` only LOOKS UP the fixed role names and never iterates the
+    // palette; its own output order comes from `SLOT_ROLE`.
+    writeText(dest, `${jsonDumpsIndent(colorThemeJson(Object.fromEntries(pal), transparent))}\n`);
+    written.push(dest);
+  }
+  pyPrint(`[theme] wrote ${written.map((p) => path.basename(p)).join(', ')} to ${destDir}\n`);
+  pyPrint(`[theme] select in OpenCode with: /theme ${full}`
+    + (args.solidOnly ? '' : `  (or /theme ${full}-transparent)`) + '\n');
+  return 0;
+}