geneseed 2.0.0

package/js/status.mjs

@@ -0,0 +1,281 @@
+/**
+ * `harness status` and `harness version` — `rituals/_harness_status.py`, and the parts of
+ * four other modules those two reach.
+ *
+ * WHAT THE CLOSURE ACTUALLY IS, MEASURED. An `ast` walk over `rituals/` puts `status` at 527
+ * LOC across 7 modules with 17 `build.*` names, which is what carried it through two phases
+ * as "the cheap half at 159 LOC". Both numbers are wrong in opposite directions, and the
+ * second one is the interesting one: a closure walk counts what the CALLEE computes, and
+ * `_status_data` consumes a fraction of it.
+ *
+ *   * `_tui_inventory` returns every agent and skill with its one-line purpose, full
+ *     rendered body, source path and lifecycle badge, and every law with its title, body
+ *     and governance class. `_status_data` reads three `len()`s off it. So `SKILL_CLASS`,
+ *     `LAW_CLASS`, `ENTITY_STATUSES`, `load_registry`, `entity_status` and
+ *     `build._first_blockquote` — the taxonomy P7 owns, ~111 LOC — are in the walk and are
+ *     not in this file. `inventoryCounts` is the counting half and says so.
+ *   * `_installed_defaults` detects theme, emit, posture, mode and footprint. The panel
+ *     prints theme and emit. `_posture_of_dir`/`_mode_of_dir` are therefore not part of the
+ *     value it returns, and `status/posture-and-mode-in-the-carrier-change-nothing` is the
+ *     cell that says the omission is invisible rather than assuming it. **P5f ported those
+ *     two detectors and did NOT change this** — `rebuild-all` calls them per install root,
+ *     not through `_installed_defaults`, so the cell above is still a positive control over
+ *     an unchanged omission rather than a claim that has quietly gone stale.
+ *   * `_footprint_of_dir` is reached from here, and it is the exception that names the rule:
+ *     its return value is not consumed by the panel either, but an unrecognised marker makes
+ *     it WARN on stderr, and stderr is a compared column. A closure pruned by what the
+ *     caller consumes drops a function whose whole contribution is a side effect.
+ *   * `_memory_facts` builds a record per fact through `_frontmatter`; the panel counts
+ *     them. `memoryFactCount` is the count, and `frontmatter` stays where it is.
+ *
+ * WHERE THE DETECTORS WENT. `themeOfDir`, `footprintOfDir`, `installedDefaults`,
+ * `manifestIsClaude` and the configured defaults were written here in P5d because `status`
+ * was their only caller. `js/installs.mjs` owns them since P5f, when `diff` and `rebuild-all`
+ * became the second and third. Nothing about them changed in the move — the 166-cell
+ * acceptance matrix is what licensed attempting it, `status`'s own eleven cells among them.
+ *
+ * WHAT NO CELL CAN REACH, and where it is gated instead. `tests/harness_golden.py`'s
+ * status/version section carries the long form; the short form is that ROOT is not
+ * redirectable across a process boundary, so three things here are unreachable from any
+ * cell: `versionVerdict`'s "up to date" (needs a marker holding a fingerprint no cell can
+ * know), `accentFor`'s cyan fallback (an unknown theme is refused upstream by
+ * `effectiveTheme`), and the whole ANSI half of `statusLines` (`_color_enabled` is
+ * `sys.stdout.isatty()`, and every harness captures stdout through a pipe). All three are
+ * PURE FUNCTIONS of their arguments, so all three are gated as a corpus in
+ * `tests/test_pure_function_parity.py` instead — which is a third answer to the colour
+ * question the P5c handoff posed as a choice between shipping it ungated and not shipping
+ * it.
+ *
+ * `manifestIsClaude` was a FOURTH until wave 2 of the P0/P1 review: it is only reached for
+ * a candidate with no known host, and `ROOT/"Harness"` was ordered ahead of the sandbox's
+ * own. Both ROOT-relative bundle candidates are gone from this walk and from
+ * `installedDefaults`, so the only no-known-host candidate left is `cwd/"Harness"`, which
+ * is inside the sandbox. It is reachable now; no cell seeds a manifest without an emit
+ * marker, so it is still gated only by the corpus, and that is a gap rather than a wall.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { THEMES, ROOT, makeCfg } from './checkout.mjs';
+import { tuiInventory } from './inventory.mjs';
+import { readVersion, sourceFingerprint } from './emit.mjs';
+import {
+  claudeConfigDir, bobConfigDir, copilotConfigDir, opencodeConfigDir, pyResolve,
+  resolveMemoryDir,
+} from './hosts.mjs';
+// P5f moved the install DETECTORS out of this file — `diff` renders its expected copy in the
+// deployed theme and footprint, and `rebuild-all` re-emits in the deployed everything, so
+// three verbs now read them. `defaultTheme`, `manifestIsClaude` and `installedDefaults` are
+// re-exported below because `tests/fixtures/pure_probe.mjs` names this module for two of them
+// and a corpus that followed the code to its new file would stop testing the caller's view.
+import {
+  defaultTheme, installedDefaults, manifestIsClaude, readJsonMaybe, readMaybe,
+} from './installs.mjs';
+import { pyLen, pyLjust, pyPrint } from './lib/fs.mjs';
+
+export { defaultTheme, manifestIsClaude };
+
+// ---- version ---------------------------------------------------------------------------
+
+/** `_harness_status._version_verdict`. */
+export function versionVerdict(installed, current) {
+  if (installed === null || installed === undefined) {
+    return 'no Geneseed install detected to compare';
+  }
+  if (installed === current) return 'up to date with this source';
+  return 'installed build differs from the current source — run '
+    + '`./geneseed update` (or rebuild) to apply it';
+}
+
+/** `_harness_status.cmd_version`. */
+export function cmdVersion(args) {
+  const cfg = makeCfg();
+  const current = sourceFingerprint(cfg);
+  // `Path(args.target).expanduser().resolve()` — `pyResolve` already expands, so the tilde
+  // is handled once rather than twice.
+  let target = args.target ? pyResolve(args.target) : opencodeConfigDir();
+  let installed = readVersion(target);
+  if (installed === null) {
+    // A claude/bob/copilot-only machine must not report "no install detected". The bundle
+    // candidates are cwd-relative only — see the Python for why `ROOT / "Harness"` left.
+    for (const base of [claudeConfigDir(), bobConfigDir(), copilotConfigDir(),
+      path.join(process.cwd(), 'Harness'), process.cwd()]) {
+      const v = readVersion(base);
+      if (v) { installed = v; target = base; break; }
+    }
+  }
+  pyPrint(`[version] source:    ${current}   (${ROOT})\n`);
+  pyPrint(`[version] installed: ${installed || '(none found)'}`
+    + (installed ? `   (${target})` : '') + '\n');
+  pyPrint(`[version] ${versionVerdict(installed, current)}\n`);
+  return 0;
+}
+
+// ---- what the panel counts ---------------------------------------------------------------
+
+/**
+ * `_harness_tui._tui_inventory`, reduced to the three counts `_status_data` reads off it.
+ *
+ * THREE `length`s OFF THE REAL WALK SINCE P6c, and the change is the point. P5d shipped a
+ * counting-only twin — the bodies, purposes, source paths and taxonomy classes were P7's,
+ * and porting them to produce three integers would have been absurd — with a docblock
+ * warning that the two must not become two classifiers. `api_catalog` consumes exactly the
+ * fields the count threw away, so P6c is the phase that would have made them two. It did
+ * not: `tuiInventory` in `js/inventory.mjs` is the one walk, this is three `length`s off
+ * it, and the eleven `status` cells and the catalog cells now gate the same classifier
+ * from opposite ends.
+ */
+export function inventoryCounts(themeName) {
+  const inv = tuiInventory(themeName);
+  return { agents: inv.agents.length, skills: inv.skills.length, laws: inv.laws.length };
+}
+
+/**
+ * `_harness_tui_views._memory_facts`, reduced to its length.
+ *
+ * A path `glob("*.md")` matches but `read_text` cannot read — a DIRECTORY called `notes.md`
+ * is the reachable case — is skipped, not counted and not fatal.
+ */
+export function memoryFactCount(mdir) {
+  let names;
+  try { names = readdirSync(mdir); } catch { return 0; }
+  let n = 0;
+  for (const name of names.filter((x) => x.endsWith('.md')).sort()) {
+    const stem = name.slice(0, -3);
+    if (['memory', 'readme'].includes(stem.toLowerCase())) continue;
+    if (readMaybe(path.join(mdir, name)) === null) continue;
+    n += 1;
+  }
+  return n;
+}
+
+/** `_harness_tui_draw._accent_for` — the ACCENT a theme declares, default cyan. */
+export function accentFor(theme) {
+  const doc = readJsonMaybe(path.join(THEMES, `${theme}.json`));
+  if (!doc || typeof doc !== 'object') return 'cyan';
+  return doc.ACCENT ?? 'cyan';
+}
+
+// ---- the panel ----------------------------------------------------------------------------
+
+/** `_harness_status._status_data`. */
+export function statusData() {
+  const inst = installedDefaults();
+  const theme = inst.theme || defaultTheme();
+  const mdir = resolveMemoryDir(null);
+  const inv = inventoryCounts(theme);
+  let cfgDir = null;
+  try { cfgDir = opencodeConfigDir(); } catch { cfgDir = null; }
+  const sourceFp = sourceFingerprint(makeCfg());
+  let installedFp = null;
+  let verTarget = null;
+  const otherCfg = [];
+  for (const fn of [claudeConfigDir, bobConfigDir, copilotConfigDir]) {
+    try { otherCfg.push(fn()); } catch { /* a missing host dir must not sink status */ }
+  }
+  // Same walk as `cmdVersion`'s fallback, and cwd-relative for the same reason.
+  const candidates = [...(cfgDir ? [cfgDir] : []), ...otherCfg,
+    path.join(process.cwd(), 'Harness'), process.cwd()];
+  for (const base of candidates) {
+    const v = readVersion(base);
+    if (v) { installedFp = v; verTarget = base; break; }
+  }
+  const agentMd = (inst.emit === 'opencode-global' && cfgDir)
+    ? path.join(cfgDir, 'AGENT.md') : null;
+  return {
+    theme,
+    accent: accentFor(theme),
+    emit: inst.emit || '—',
+    agents: inv.agents,
+    skills: inv.skills,
+    laws: inv.laws,
+    memory_dir: mdir ? String(mdir) : null,
+    facts: mdir ? memoryFactCount(mdir) : 0,
+    source_fp: sourceFp,
+    installed_fp: installedFp,
+    version_target: verTarget ? String(verTarget) : null,
+    version_verdict: versionVerdict(installedFp, sourceFp),
+    agent_md: agentMd ? String(agentMd) : null,
+    agent_md_present: Boolean(agentMd && existsSync(agentMd)),
+  };
+}
+
+/** `_harness_status._ANSI_CODES`. */
+const ANSI_CODES = {
+  red: '31', green: '32', yellow: '33', blue: '34', magenta: '35', cyan: '36', white: '37',
+};
+
+/**
+ * `_harness_status._color_enabled`.
+ *
+ * `process.stdout.isTTY` is `undefined` rather than `false` off a terminal, so the Boolean
+ * is not optional. The three terms are Python's, in Python's order — and because `and`
+ * short-circuits on the first, NO_COLOR and TERM are never read through a pipe, which is
+ * why `golden.cell_env` clearing them is insurance rather than a fix.
+ */
+export function colorEnabled() {
+  return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined
+    && process.env.TERM !== 'dumb';
+}
+
+/**
+ * `_harness_status._status_lines` — pure, returns the lines.
+ *
+ * `_TUI_ASCII` is read from the environment at CALL time here where Python reads it at
+ * import time (`_harness_tui_draw:12`). Same value for a process that runs one verb and
+ * exits; spelled this way because a module-level constant in a file the corpus gate imports
+ * would freeze at whatever the test runner's environment was.
+ */
+export function statusLines(d, color = false) {
+  const asc = Boolean(process.env.GENESEED_TUI_ASCII);
+  const [H, V] = asc ? ['-', '|'] : ['─', '│'];
+  const [TL, TR, BL, BR, LT, RT] = asc
+    ? ['+', '+', '+', '+', '+', '+'] : ['┌', '┐', '└', '┘', '├', '┤'];
+  const DOT = asc ? '-' : '·';
+  const badge = asc ? '*' : '◆';
+  const emdash = asc ? '-' : '—';
+
+  const up = d.version_verdict.includes('up to date');
+  const noneInst = d.installed_fp === null || d.installed_fp === undefined;
+  const mark = up ? (asc ? 'OK' : '✓') : (noneInst ? (asc ? '-' : '·') : '!');
+  const vcode = up ? '32' : (noneInst ? '2' : '33');
+
+  const rows = [
+    ['theme', `${d.theme}  (accent: ${d.accent})`],
+    ['install', d.emit],
+    ['components', `${d.agents} agents ${DOT} ${d.skills} skills ${DOT} ${d.laws} laws`],
+    ['memory', `${d.memory_dir || '(not found)'}  `
+      + `(${d.facts} fact${d.facts === 1 ? '' : 's'})`],
+    ['version', `${d.installed_fp || '(none)'}  ${DOT}  source ${d.source_fp}`],
+  ];
+  if (d.agent_md) {
+    rows.push(['AGENT.md',
+      `${d.agent_md}  (${d.agent_md_present ? 'present' : 'MISSING'})`]);
+  }
+
+  const labelW = Math.max(...rows.map(([k]) => pyLen(k)));
+  const body = rows.map(([k, v]) => `  ${pyLjust(k, labelW)}   ${v}`);
+  const verdict = `  ${mark} ${d.version_verdict}`;
+  const title = ` ${badge} Geneseed ${emdash} status `;
+  const width = Math.max(...body.map(pyLen), pyLen(verdict), pyLen(title) + 2);
+
+  const ac = ANSI_CODES[d.accent] ?? '36';
+  const c = (s, code) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+
+  const top = color
+    ? c(TL + H, ac) + c(title, `${ac};1`) + c(H.repeat(width - pyLen(title) - 1) + TR, ac)
+    : TL + H + title + H.repeat(width - pyLen(title) - 1) + TR;
+  const edge = c(V, ac);
+  const lines = [top];
+  for (const b of body) lines.push(edge + pyLjust(b, width) + edge);
+  lines.push(c(LT + H.repeat(width) + RT, ac));
+  lines.push(edge + c(pyLjust(verdict, width), vcode) + edge);
+  lines.push(c(BL + H.repeat(width) + BR, ac));
+  return lines;
+}
+
+/** `_harness_status.cmd_status`. */
+export function cmdStatus() {
+  for (const line of statusLines(statusData(), colorEnabled())) pyPrint(`${line}\n`);
+  return 0;
+}

package/js/themes.mjs

@@ -0,0 +1,195 @@
+/**
+ * `_build_render.sync_themes` / `_insert_theme_keys` — the generator's `--sync-themes`, the
+ * maintainer tool that fills every shipped theme with the keys `_TEMPLATE.json` defines.
+ *
+ * IT IS A BYTE-EXACT TEXTUAL EDIT OF COMMITTED FILES, which is what makes it the most
+ * dangerous thing in this phase and why it has its own corpus before it has a port. Every
+ * other tool this port has crossed WRITES A TREE it also renders; this one reaches into
+ * fourteen files a human wrote, inserts a line into each, and leaves the other ~170 lines
+ * untouched. A port that got the insertion right and the newline translation wrong would
+ * rewrite every line of every theme on the first maintainer run, and `git diff` — not a
+ * gate — is where that would be discovered.
+ *
+ * NEITHER `--sync-themes` NOR `--validate-only` IS REACHABLE FROM ANY CELL. `golden.py`'s
+ * `_argv` emits neither flag (argued in situ at `bin/geneseed.mjs`'s dispatch), so the
+ * acceptance matrix that gates all nine emits is structurally blind to both, and the driver
+ * refused them rather than crossing for exactly that reason. The gate is
+ * `tests/test_maintainer_tools_parity.py`: a corpus of hand-made theme directories run
+ * through BOTH implementations, comparing the printed output, the return value, and the
+ * resulting FILE BYTES.
+ *
+ * WHY THIS MODULE IS NOT `js/doctor.mjs`. `--sync-themes` has no doctor dependency, so it
+ * stays on the generator driver where its flag lives — and the driver is under a transitive
+ * ban on starting processes, which this module's imports respect. Its sibling
+ * `--validate-only` needs the doctor and therefore could not stay; see `cmdValidate`.
+ *
+ * THE PRIMITIVES ARE BORROWED, NOT REWRITTEN. `pySplitLines`, `pyStripSpace`/`pyLStripSpace`/
+ * `pyRStripSpace`, `parseJson`, `pyEq`, `jsonDumpsCompact`, `jsonDumpsIndent`, `readText` and
+ * `writeText` all already exist and are all already gated. This file's documented failure
+ * mode is the same primitive existing twice under two names and the two disagreeing, and
+ * `str.strip` and `json.dumps` are precisely the two that would have been re-derived here.
+ */
+import path from 'node:path';
+
+import { THEMES } from './checkout.mjs';
+import { themeFiles } from './installs.mjs';
+import { pySplitLines } from './lib/udiff.mjs';
+import {
+  jsonDumpsCompact, jsonDumpsIndent, parseJson, pyEq, pyLStripSpace, pyRStripSpace,
+  pyStripSpace, readText, writeText,
+} from './lib/fs.mjs';
+
+/**
+ * `_build_render._insert_theme_keys` — insert ONLY the missing keys into the theme's existing
+ * TEXT, each as one new line at its template-order position.
+ *
+ * A full `json.dumps` round-trip cannot reproduce the shipped files byte-for-byte (they mix
+ * raw Unicode with legacy `\\uXXXX` escapes), so re-dumping made a one-key sync a ~170-line
+ * rewrite per theme. Textual insertion keeps the diff to the inserted line plus at most a
+ * comma on its predecessor.
+ *
+ * Returns `null` when the file does not follow the shipped convention (`{` alone on line 1,
+ * one `  "KEY": value` per line) or when the result fails the reparse safety check — the
+ * caller then falls back to a full re-dump.
+ *
+ * FOUR PRIMITIVES CARRY THE WHOLE THING, and each is a place the two languages differ:
+ *   - `pySplitLines` is `str.splitlines()`, which breaks on U+2028/U+2029 where `split('\\n')`
+ *     does not — a theme file that acquired one from a paste would be re-lined by Python and
+ *     not by a naive port, and the insertion index would then point at a different key;
+ *   - the three `strip` spellings are Python's whitespace set, not `String.prototype.trim`'s;
+ *   - `jsonDumpsCompact(v, {ensureAscii: false})` is `json.dumps(v, ensure_ascii=False)`,
+ *     including the `', '`/`': '` separators — which matter for exactly ONE key,
+ *     `AGENT_COLORS`, the only non-string among `_TEMPLATE.json`'s 137 values. `ensureAscii`
+ *     is false because the reference passes `ensure_ascii=False`, and 33 template values
+ *     carry non-ASCII text that would otherwise be escaped into the committed file;
+ *   - `pyEq`, because the safety net compares two `json.loads` results and `===` is identity
+ *     for containers — a `===` here would return `null` every time and silently route every
+ *     theme through the re-dump fallback, i.e. rewrite all 14 files in full.
+ */
+export function insertThemeKeys(raw, theme, tmpl, tmplKeys, missing) {
+  const lines = pySplitLines(raw);
+  if (!lines.length || pyStripSpace(lines[0]) !== '{') return null;
+
+  const lineOf = (key) => {
+    // `f'  "{key}":'` — raw interpolation, NOT a JSON-escaped key. A theme key carrying a
+    // quote would not match on either side, which is the same answer both give.
+    const prefix = `  "${key}":`;
+    for (let i = 0; i < lines.length; i += 1) if (lines[i].startsWith(prefix)) return i;
+    return null;
+  };
+
+  // Every existing key must be locatable as its own line, or the format assumption is wrong
+  // and inserting would corrupt the file.
+  for (const k of Object.keys(theme)) if (lineOf(k) === null) return null;
+
+  for (const k of missing) { // template order, so an earlier insert can anchor a later one
+    const entry = `  "${k}": ${jsonDumpsCompact(tmpl[k], { ensureAscii: false })}`;
+    let pred = null;
+    const earlier = tmplKeys.slice(0, tmplKeys.indexOf(k));
+    for (let i = earlier.length - 1; i >= 0; i -= 1) {
+      const li = lineOf(earlier[i]);
+      if (li !== null) { pred = li; break; }
+    }
+    if (pred === null) {
+      // No earlier template key exists in this theme: insert right after `{`.
+      const follows = lines.slice(1).some((ln) => pyLStripSpace(ln).startsWith('"'));
+      lines.splice(1, 0, entry + (follows ? ',' : ''));
+    } else if (pyRStripSpace(lines[pred]).endsWith(',')) {
+      lines.splice(pred + 1, 0, `${entry},`);
+    } else {
+      // Predecessor was the last entry: it gains the comma, the new line is last.
+      lines[pred] += ',';
+      lines.splice(pred + 1, 0, entry);
+    }
+  }
+
+  const newText = `${lines.join('\n')}\n`;
+  // Safety net: the surgically-edited text must parse back to exactly the merge we meant.
+  let reparsed;
+  try { reparsed = parseJson(newText); } catch { return null; }
+  const want = { ...theme };
+  for (const k of missing) want[k] = tmpl[k];
+  return pyEq(reparsed, want) ? newText : null;
+}
+
+/**
+ * `_build_render.sync_themes` — fill every shipped theme with the template's keys.
+ *
+ * Returns the number of themes actually modified (0 == already in sync); the driver maps that
+ * to the exit code, so CI can run the tool as a drift check.
+ *
+ * `themesDir` is a parameter for the corpus, whose whole subject is what this writes; the
+ * default is the checkout's own `themes/`, which is what the driver passes.
+ *
+ * PRINTS THROUGH A BARE `process.stdout.write`, like the generator's other ~25 print sites and
+ * unlike every CLI verb: `bin/geneseed.mjs`'s `main` wraps the whole run in `withPyNewlines`,
+ * so a `pyPrint` here would translate a second time and put `\r\r\n` on every line.
+ *
+ * ONE DELIBERATE DIVERGENCE FROM THE REFERENCE, changed on BOTH sides in this commit: a
+ * missing or unreadable `_TEMPLATE.json` used to print and `return 0`, which the CLI maps to
+ * exit 0 — "already in sync". That is a false green in the one job the tool exists for, and
+ * the input that produces it is the one that makes the whole run vacuous. It now refuses with
+ * exit 2. Dropping the interpolated exception text is the second half of the same change and
+ * is what makes the branch gateable at all: `json.JSONDecodeError` and V8's parse error
+ * disagree on both wording and offset, so a message carrying `{e}` can never be compared
+ * across the two implementations. The PER-THEME unreadable message below keeps its `{e}` and
+ * therefore keeps that divergence, matching the convention `js/doctor.mjs` already ships at
+ * six sites — a skipped theme is a warning, not the tool's verdict.
+ */
+export function syncThemes(themesDir = THEMES) {
+  const tmplPath = path.join(themesDir, '_TEMPLATE.json');
+  let tmpl;
+  try {
+    tmpl = parseJson(readText(tmplPath));
+  } catch {
+    process.stdout.write(`[sync-themes] ${path.basename(tmplPath)} is missing or unreadable `
+      + '— there is nothing to sync against.\n');
+    const e = new Error('template unreadable');
+    e.exitCode = 2;
+    throw e;
+  }
+  const tmplKeys = Object.keys(tmpl);
+  let changed = 0;
+  for (const p of themeFiles(themesDir)) {
+    const name = path.basename(p);
+    let raw;
+    let theme;
+    try {
+      raw = readText(p);
+      theme = parseJson(raw);
+    } catch (e) {
+      process.stdout.write(`[sync-themes] ${name}: unreadable (${e.message}) — skipped\n`);
+      continue;
+    }
+    // `Object.hasOwn`, never `k in theme`: a theme defining a `constructor` or `toString`
+    // voice token would otherwise be reported as already carrying every key it lacks.
+    const missing = tmplKeys.filter((k) => !Object.hasOwn(theme, k));
+    const extra = Object.keys(theme).filter((k) => !Object.hasOwn(tmpl, k)).sort();
+    if (!missing.length) {
+      if (extra.length) {
+        process.stdout.write(`[sync-themes] ${name}: in sync (extra key(s) not in template, `
+          + `not removed: ${extra.join(', ')})\n`);
+      }
+      continue;
+    }
+    let newText = insertThemeKeys(raw, theme, tmpl, tmplKeys, missing);
+    if (newText === null) {
+      // Unconventional formatting: fall back to a full re-dump — template order, theme-only
+      // extras preserved at the end, real Unicode kept as-is.
+      const merged = {};
+      for (const k of tmplKeys) merged[k] = Object.hasOwn(theme, k) ? theme[k] : tmpl[k];
+      for (const k of Object.keys(theme)) if (!Object.hasOwn(merged, k)) merged[k] = theme[k];
+      newText = `${jsonDumpsIndent(merged, { ensureAscii: false })}\n`;
+    }
+    writeText(p, newText);
+    changed += 1;
+    process.stdout.write(`[sync-themes] ${name}: added ${missing.length} key(s) from the `
+      + `template — RESTYLE these in this theme's voice: ${missing.join(', ')}\n`);
+    if (extra.length) {
+      process.stdout.write(`[sync-themes] ${name}: extra key(s) not in template, not removed: `
+        + `${extra.join(', ')}\n`);
+    }
+  }
+  if (!changed) process.stdout.write('[sync-themes] all themes already carry every template key.\n');
+  return changed;
+}