geneseed 3.14.0 → 3.16.0

package/js/ui/cli.mjs

@@ -10,7 +10,7 @@
  * copy in it.
  *
  * P10c's answer was to make the metadata DATA — generated into `cli.json` at the repo root by
- * `tests/gen_cli_reference.py` and read by both sides. P2 finishes the thought: the table is
+ * a since-deleted Python script and read by both sides. P2 finishes the thought: the table is
  * no longer GENERATED from anything, it is the OWNED document, and it lives here on a product
  * path because that is where a document npm ships belongs. `package.json`'s `files[]` already
  * carries `js/`, so it needs no row of its own, and nothing has to import out of `tests/`.
@@ -31,13 +31,9 @@
  * a file filtered for the page breaks the CLI, and a file in `cliSpec`'s shape cannot render
  * the docs. It stays exactly what the argparse walk produced.
  *
- * WHAT USED TO GUARD IT, AND WHAT DOES NOW. While the parser existed, `cliReferenceProblems()`
- * hashed `rituals/harness.py` and doctor reported drift on both binaries. That digest was over
- * a file this migration deletes, so it is gone; `tests/test_cli_reference.py` holds the
- * argparse-vs-table comparison, and it can only ever cover the rows argparse HAS: `catalog`,
- * `mcp` and `memory` never had a subparser and are outside it by construction. The successor
- * that checks the WHOLE table, and outlives the parser, is `tests/unit/cli_table.test.mjs`;
- * after that the table is simply the source of truth and is edited directly.
+ * WHAT GUARDS IT. The Python parser it was walked from is gone, and with it every comparison
+ * against argparse; the table is now simply the source of truth and is edited directly.
+ * `tests/unit/cli_table.test.mjs` checks the WHOLE table.
  *
  * THE COST, NAMED: this entry cannot parse anything without this file. `js/build/source.mjs`
  * already reads `harness.config.json` at import for every render, so a tracked data document
@@ -48,6 +44,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { ROOT } from '../build/source.mjs';
+import { printOut } from '../lib/fs.mjs';
 import { parseIntStrict, stripWhitespace } from '../lib/text.mjs';
 
 const CLI_JSON = path.join(ROOT, 'js', 'cli-table.json');
@@ -156,8 +153,8 @@ function actionInvocation(a, positional) {
 // hyphenated word into two chunks, so it can break a line inside `back-compat` where a
 // space-only wrap cannot. Measured before deciding: every help string then in the table disagreed
 // with a greedy wrap at some width, the widest at 175 — so "the branch is dead" was simply
-// false, and `test_the_ports_line_breaker_is_textwrap_at_every_width` said so on the run that
-// first asserted it. The rules are transcribed instead.
+// false, and the former Python suite's every-width comparison against `textwrap` said so on
+// the run that first asserted it. The rules are transcribed instead.
 //
 // Python's classes, spelled for a `u`-flagged JavaScript regex: `\w` is letters, numbers and
 // underscore; `[^\d\W]` is that minus the DECIMAL digits, which leaves the letter-ish half
@@ -181,9 +178,8 @@ const WORDSEP = new RegExp(
  * `drop_whitespace`, `break_long_words` and `break_on_hyphens` all on, and the text already
  * whitespace-collapsed and stripped by the caller.
  *
- * ponytail: lives here rather than in `js/lib/` because `formatHelp` is its only consumer.
- * `rituals/_harness_tui*.py` calls `textwrap.wrap` in seven places and is declared unported;
- * move this when that changes, not before.
+ * ponytail: lives here rather than in `js/lib/` because `formatHelp` is its only consumer;
+ * move it when a second one appears, not before.
  */
 export function wrapText(text, width) {
   const chunks = text.split(WORDSEP).filter(Boolean).reverse();
@@ -310,7 +306,7 @@ function formatAction(a, positional, helpPosition, width) {
  * `parser.format_help()` for one subcommand, byte for byte with argparse.
  *
  * WHY THE PORT RENDERS THIS AT ALL. Task 10 compared the two implementations' `--help` for the
- * first time — `tests/harness_golden.py` has zero `--help` cells — and found the port answering
+ * first time — the former Python CLI matrix had zero `--help` cells — and found the port answering
  * `geneseed: error: unrecognized arguments: --help`, exit 2, on all 26 verbs. That is not the
  * declared wording divergence `parse`'s docblock reserves for argparse's ERROR text: it is the
  * absence of the surface, on the binary that survives the reference's deletion.
@@ -318,19 +314,19 @@ function formatAction(a, positional, helpPosition, width) {
  * `prog` IS AN ARGUMENT AND THAT IS THE ONE DELIBERATE DIVERGENCE. The reference names itself
  * `harness`, after the Python file this migration deletes; a user who typed `geneseed status
  * --help` is shown `usage: geneseed status`, which is also how every error this entry prints
- * already spells itself (`die`). `tests/__snapshots__/help/` freezes the reference's answers
- * and `tests/snapshot/cli_help.test.mjs` replays them through here with `prog` set to the reference's
- * own — so the layout is gated byte for byte and the rename is the only thing that moves.
+ * already spells itself (`die`). The former Python suite replayed the reference's recorded
+ * answers through here with `prog` set to the reference's own, so the layout was gated byte for
+ * byte and the rename was the only thing that moved. That corpus is gone; the layout is now
+ * pinned by the written-out `formatHelp` rows in `tests/unit/text_layout.test.mjs`.
  *
- * NOT EVERY VERB HAS A RECORDED ANSWER, AND THREE NEVER CAN. `catalog`, `mcp` and `memory` had
- * no subparser for the recorder to render from, so the corpus covers the verbs argparse
- * answered to and those three are held ABSOLUTELY instead — `tests/snapshot/cli_help.test.mjs` names
- * both populations (`RECORDED`, `NATIVE`) and fails a verb that falls into neither, which is
- * what keeps "no recorded text" from meaning "no gate".
+ * NOT EVERY VERB HAD A RECORDED ANSWER, AND THREE NEVER COULD. `catalog`, `mcp` and `memory` had
+ * no subparser for the recorder to render from, so they were held ABSOLUTELY instead — and
+ * `tests/unit/hook_cli.test.mjs`'s `NATIVE` list still names that population and fails a verb
+ * that falls into neither, which is what keeps "no recorded text" from meaning "no gate".
  *
  * The alias rides on the same argument: argparse gives `update` the parser object it built for
- * `upgrade`, so `harness.py update --help` prints `usage: harness upgrade`. The recorded prog
- * map reproduces that; the shipped call passes `geneseed update`, which is what the user typed.
+ * `upgrade`, so `harness.py update --help` printed `usage: harness upgrade`. The recorded prog
+ * map reproduced that; the shipped call passes `geneseed update`, which is what the user typed.
  *
  * `width` is argparse's `shutil.get_terminal_size().columns - 2`, passed in rather than read,
  * because a recorded help text whose wrap column came from the recorder's terminal is a corpus
@@ -407,12 +403,13 @@ export function formatHelp(cmd, prog, width) {
  *
  * `parseIntStrict`, NOT `Number.parseInt`, and the tree already owned it. `get_terminal_size` spells
  * this `int(os.environ['COLUMNS'])` inside `except (KeyError, ValueError)`, and `int` is not
- * `parseInt`. Measured against the reference over a corpus of `$COLUMNS` values
- * (`test_the_ports_help_width_is_shutil_get_terminal_size`): `COLUMNS=1_0` is 10 to Python and
+ * `parseInt`. Measured against the reference over a corpus of `$COLUMNS` values in the former
+ * Python suite (`tests/unit/cli_table.test.mjs`'s 'the help width is the terminal width less
+ * two, and COLUMNS wins' keeps a written-out part of it): `COLUMNS=1_0` is 10 to Python and
  * 1 to `parseInt`, `COLUMNS=٣` is 3 and NaN, `COLUMNS=' 80 '` is 80 and NaN. `COLUMNS=80abc`
  * is a ValueError to Python and 80 to `parseInt` — the same answer down a PIPE, where the
  * fallback is 80 either way, and a different one on any terminal that is not 80 wide, which is
- * why the corpus is the gate rather than a cell. A non-positive value falls through on both
+ * why a unit test is the gate rather than a cell. A non-positive value falls through on both
  * sides, which is Python's `if columns <= 0` and was already right here.
  *
  * `stripWhitespace` because THIS is the caller `parseIntStrict`'s docblock did not have: its other two
@@ -443,8 +440,7 @@ export function printVerbList(prog, verbs, extra = {}) {
     `A bare \`${prog}\` runs \`home\`. \`${prog} <command> --help\` describes one command.`, '',
     'commands:'];
   for (const n of names) lines.push(`  ${n.padEnd(pad)}${helpOf.get(n) || ''}`.trimEnd());
-  const text = `${lines.join('\n')}\n`;
-  process.stdout.write(process.platform === 'win32' ? text.replaceAll('\n', '\r\n') : text);
+  printOut(`${lines.join('\n')}\n`);
   return 0;
 }
 
@@ -453,18 +449,16 @@ export function printVerbList(prog, verbs, extra = {}) {
  * describe — the caller already owns that refusal and its message.
  *
  * ONE OWNER FOR TWO ENTRIES. `bin/geneseed-hook.mjs` carries the four hook verbs and
- * `bin/geneseed-cli.mjs` the rest of the table, and
- * `test_the_two_entry_points_carry_disjoint_verb_sets` keeps them from learning each other's
+ * `bin/geneseed-cli.mjs` the rest of the table, and `tests/unit/hook_cli.test.mjs`'s
+ * "the two entry points carry disjoint verb sets" keeps them from learning each other's
  * tables — so the help each prints has to come from here rather than from a copy in each.
  *
- * CRLF ON WINDOWS for `die`'s reason: argparse writes through a Python text stream, which
- * translates, and this text lands in the same terminals and the same pipes as that one.
+ * CRLF ON WINDOWS through `printOut`, the one funnel every CLI print takes.
  */
 export function printHelp(prog, verb) {
   const cmd = cliCommand(verb);
   if (cmd === null) return null;
-  const text = formatHelp(cmd, `${prog} ${verb}`, helpWidth());
-  process.stdout.write(process.platform === 'win32' ? text.replaceAll('\n', '\r\n') : text);
+  printOut(formatHelp(cmd, `${prog} ${verb}`, helpWidth()));
   return 0;
 }
 

package/js/ui/menu.mjs

@@ -22,8 +22,8 @@
  * still the right shape; only its explanation moved. The alternative that was considered and
  * refused: building a numbered line-menu out of `js/maintain/setup.mjs`'s `askChoice`. That is not a
  * port of `_main_menu` — it is a THIRD user interface, differing from the reference on every
- * screen, unreachable from every cell (no cell has a TTY), and it would have to be deleted
- * the day P7c lands the real panel. The fallback is the reference's own contract for "no
+ * screen, unreachable from every cell (no cell has a TTY), for a panel that was rejected
+ * outright rather than deferred. The fallback is the reference's own contract for "no
  * full-screen menu available here"; a new UI would not be.
  *
  * `cmd_home` is the default for a bare `geneseed`, and it crosses WHOLE. Its two arms are
@@ -32,10 +32,9 @@
  *
  * `_web_first_ok`'s FIVE REFUSALS ARE THE PAYLOAD, and only two of them are reachable from a
  * cell: a cell's stdin is a pipe, so `isTTY` is false and everything past it is dead. The
- * other three (SSH, the Linux display server, the browser) are gated by the corpus in
- * `tests/test_pure_function_parity.py`, which drives this function with `isTTY` FAKED — the
- * one input no cell can vary. See that file's P7a section for what it reaches and what it
- * declares.
+ * other three (SSH, the Linux display server, the browser) are gated by
+ * `tests/unit/web_first.test.mjs`, which drives this function through
+ * `tests/fixtures/pure_probe.mjs` with `isTTY` FAKED — the one input no cell can vary.
  */
 import { printOut, printErr } from '../lib/fs.mjs';
 import { which } from '../lib/paths.mjs';
@@ -93,13 +92,8 @@ export function cmdMenu() {
   // The reference's own `except Exception` arm, with a reason that is permanent here rather
   // than machine-dependent. stderr, and CRLF on Windows, because `sys.stderr.write` does.
   //
-  // P7b CORRECTED THE REASON RATHER THAN THE ARM. This module's header said the fallback was
-  // reached because "`import curses` fails on stock Windows Python", and P7b measured that
-  // to be false where it matters: `rituals/_harness_core.py` installs `rituals/_winterm.py`
-  // as `sys.modules["curses"]` when the stdlib module is missing, so the reference opens its
-  // panel on this machine and `tests/test_tui_boundary.py` drives it doing so. What is
-  // missing is on THIS side — there is no window implementation in the port — and that is
-  // what the message now says.
+  // The reason is on THIS side: there is no window implementation, by decision, and that is
+  // what the message says (`tests/unit/no_panel.test.mjs` keeps it so).
   // NOTHING TO POINT AT ANY MORE. The message used to end by sending the reader at the
   // Python panel, and P2 took the pointer out rather than re-aiming it: the panel it named
   // is the Python this migration deletes, and a refusal that sends a user to a file which

package/js/ui/tui.mjs

@@ -21,13 +21,11 @@
  * deleted the day the real one crossed, would be a second user interface and not a port.
  *
  * WHAT DOES CROSS is the alignment contract — the functions below that decide what a row
- * looks like before any curses call is made. They have no caller in this file yet, and that
- * is deliberate and dated: **P7c is the due date**, when `_tui_loop` and the eighteen
- * screens of `_harness_tui_views.py` arrive and consume them. They are here now because they
- * are the half that can be gated exhaustively, and `tests/test_pure_function_parity.py`
- * gates every one of them in both glyph modes. Deleting any of them turns that gate red —
- * this port has shipped code before whose absence nothing would have noticed, and these are
- * not that.
+ * looks like: display width, fitting, glyph tiers, the catalogue's entries and detail lines.
+ * Each has a caller outside this file (the catalogue, the status panel, the web console).
+ * The panel itself was REJECTED, not deferred, so the helpers that existed only for it —
+ * the spinner, the wordmark, scroll clamping, the progress bar and the theme preview/flair
+ * readers — were deleted rather than kept waiting for a screen that will not come.
  *
  * WHAT IS DELIBERATELY NOT HERE: `_bx` (its non-ASCII arm returned `curses.ACS_*` chtype
  * ints, which belonged with the window) and every `(stdscr, curses, pal)` drawing helper.
@@ -37,14 +35,10 @@
  * **DO NOT WRITE A SECOND LINE BREAKER.** This block used to argue that `textwrap.wrap` was
  * "a second `difflib` — a stdlib payload with no Node twin". It has one since P1:
  * `wrapText` in `js/ui/cli.mjs`, written because `--help` was the caller that finally
- * required it, frozen at `tests/__snapshots__/textwrap.json` at every width from 11 to 198.
+ * required it, pinned by the written-out rows in `tests/unit/text_layout.test.mjs`.
  * Anything that needs wrapping wraps THAT. `_parse_laws`, `load_registry`, `entity_status` and
  * `_tui_inventory` crossed in P6c and live in `js/inspect/inventory.mjs`.
  */
-import path from 'node:path';
-
-import { THEMES } from '../build/source.mjs';
-import { readJsonMaybe } from '../hosts/installs.mjs';
 import { splitLines } from '../lib/udiff.mjs';
 import { printOut } from '../lib/fs.mjs';
 
@@ -58,7 +52,6 @@ import { printOut } from '../lib/fs.mjs';
 const TUI_ASCII = !!process.env.GENESEED_TUI_ASCII;
 const TUI_PLAIN = !!process.env.GENESEED_TUI_PLAIN;
 const TUI_EMOJI = !(TUI_ASCII || TUI_PLAIN);
-const TUI_ANIM = TUI_EMOJI;
 
 /** `_glyphs` — the one glyph table for the whole TUI, unicode or ASCII stand-ins. */
 export function glyphs(asciiMode) {
@@ -269,119 +262,18 @@ export function mark(kind) {
   return TUI_ASCII ? asc : (TUI_EMOJI ? emoji : sym);
 }
 
-const SPIN = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
-
-/** `_spin` — one spinner frame for tick `i`; a static dot in the non-animated tiers. */
-export function spin(i) {
-  if (!TUI_ANIM) return TUI_ASCII ? '-' : '·';
-  const frames = TUI_ASCII ? '|/-\\' : SPIN;
-  // `frames[i % len]` on the reference indexes CODE POINTS; the braille frames are BMP so
-  // UTF-16 indexing agrees, but spelling it through `[...frames]` keeps that an argument
-  // about the data rather than a coincidence. Python's `%` on a negative `i` returns a
-  // non-negative remainder and JavaScript's does not, so the modulo is corrected.
-  const f = [...frames];
-  return f[((i % f.length) + f.length) % f.length];
-}
-
-const LOGO_FONT = {
-  G: [' ### ', '#    ', '# ## ', '#  # ', ' ### '],
-  E: ['#### ', '#    ', '###  ', '#    ', '#### '],
-  N: ['#   #', '##  #', '# # #', '#  ##', '#   #'],
-  S: [' ####', '#    ', ' ### ', '    #', '#### '],
-  D: ['###  ', '#  # ', '#   #', '#  # ', '###  '],
-};
-
-/** `_logo_lines` — the GENESEED wordmark as 5 text rows. */
-export function logoLines() {
-  const ink = TUI_ASCII ? '#' : '█';
-  const rows = [];
-  for (let r = 0; r < 5; r += 1) {
-    rows.push([...'GENESEED'].map((c) => LOGO_FONT[c][r].replaceAll('#', ink)).join(' '));
-  }
-  return rows;
-}
-
-// ---- layout maths --------------------------------------------------------------------
-
-/** `_clamp` — clamp a scroll offset so [top, top+viewH) stays inside `total`. */
-export function clamp(top, total, viewH) {
-  return Math.max(0, Math.min(top, Math.max(0, total - viewH)));
-}
-
-const BAR_EIGHTHS = ' ▏▎▍▌▋▊▉█';
-
-/** `_progress_bar` — a determinate bar exactly `width` display columns wide. */
-export function progressBar(frac, width = 24) {
-  const f = Math.max(0.0, Math.min(1.0, frac));
-  if (TUI_ASCII) {
-    const filled = roundHalfEven(f * width);
-    return '#'.repeat(filled) + '-'.repeat(width - filled);
-  }
-  const eighths = roundHalfEven(f * width * 8);
-  const full = Math.floor(eighths / 8);
-  const rem = eighths % 8;
-  if (full >= width) return '█'.repeat(width);
-  return '█'.repeat(full) + [...BAR_EIGHTHS][rem] + ' '.repeat(width - full - 1);
-}
-
-/**
- * `round()` — Python rounds HALF TO EVEN and `Math.round` rounds half UP, and this is the
- * one place in the file where that shows: a bar at exactly 0.5 of a cell is the frontier
- * case the eighths resolution exists to draw, and `round(0.5)` is 0 there and 1 here.
- */
-function roundHalfEven(x) {
-  const f = Math.floor(x);
-  const d = x - f;
-  if (d > 0.5) return f + 1;
-  if (d < 0.5) return f;
-  return f % 2 === 0 ? f : f + 1;
-}
-
-// ---- theme reads ---------------------------------------------------------------------
-
-/** `_theme_preview` — right-panel preview rows for a theme, as (kind, text) pairs. */
-export function themePreview(key) {
-  const data = readJsonMaybe(path.join(THEMES, `${key}.json`));
-  if (!data || typeof data !== 'object') return [['dim', '(no preview available)']];
-  const lines = [['title', key], ['', '']];
-  if (data.TAGLINE) lines.push(['dim', data.TAGLINE], ['', '']);
-  if (data.LOADED_SIGIL) lines.push(['ok', data.LOADED_SIGIL], ['', '']);
-  if (data.VOICE) lines.push(['', `Voice — ${data.VOICE}`], ['', '']);
-  if (data.LEX_SEALED_SECRETS) lines.push(['', `e.g.  Rule I — ${data.LEX_SEALED_SECRETS}`]);
-  if (data.BENEDICTION) lines.push(['', ''], ['dim', data.BENEDICTION]);
-  return lines;
-}
-
-/** `_theme_flair` — the voice elements the setup chrome speaks in once a theme is chosen. */
-export function themeFlair(theme) {
-  const data = readJsonMaybe(path.join(THEMES, `${theme}.json`)) || {};
-  const banner = data.BANNER ?? '';
-  return {
-    accent: data.ACCENT ?? 'cyan',
-    tagline: data.TAGLINE ?? '',
-    sigil: data.LOADED_SIGIL ?? '',
-    // `str.splitlines()` — `js/lib/udiff.mjs`' twin, already gated. It answers `[]` for
-    // the empty string where `''.split('\n')` answers `['']`, which would put a blank row
-    // in the banner of every theme that omits one; and its boundary set is Python's rather
-    // than `\s`, which P6d measured apart.
-    banner: splitLines(banner),
-    benediction: data.BENEDICTION ?? '',
-  };
-}
-
 // ---- the inventory's two consumers ----------------------------------------------------
 
 /**
  * `_tui_entries` — the ordered (kind, label, data) rows for the left list. `head` is a
  * section divider and is not selectable.
  *
- * ⚠ THE TWO NEW TIERS ARE GUARDED, AND THE GUARD IS NOT DEFENSIVENESS. This function has two
- * recorded cases per platform in `tests/__snapshots__/primitives/`, replayed under
- * `deepStrictEqual`, and their argument is a synthetic inventory carrying exactly
- * `{agents, skills, laws, theme}` — no recorder survives to re-bless them. Reading
- * `inv.doctrines.length` there THROWS; emitting a head unconditionally changes the recorded
- * result array. Keyed on presence, the recording renders byte-identical and a real inventory
- * gets all three tiers.
+ * ⚠ THE TWO NEW TIERS ARE GUARDED, AND THE GUARD IS NOT DEFENSIVENESS. When they landed, this
+ * function had two recorded cases per platform in the former Python suite's corpus, and their
+ * argument was a synthetic inventory carrying exactly `{agents, skills, laws, theme}`. Reading
+ * `inv.doctrines.length` on such an inventory THROWS; emitting a head unconditionally changes
+ * the result array. Keyed on presence, an inventory without the tiers renders as it always did
+ * and a real inventory gets all three tiers.
  *
  * The order is CONSTITUTIONAL and not alphabetical: ontology, then invariants, then doctrines
  * — the order they are read in, the order AGENT.md renders them, and the order the console's
@@ -435,12 +327,11 @@ export function tuiEntries(inv) {
  * because line 554 moves `sel` onto the first SELECTABLE row — but line 555 is
  * `if not selectable: sel = 0`, and row 0 is always the AGENTS header. So an inventory with
  * no agents, no skills AND no laws crashes the panel on its first frame instead of drawing
- * an empty state. `_TUI_INV_EMPTY` in `tests/test_pure_function_parity.py` is the corpus
+ * an empty state. `_TUI_INV_EMPTY` in the former Python parity suite is the corpus
  * entry that surfaced it. **P7c must not reproduce the crash when it ports `_tui_loop`** —
  * the fix is one `or []` at the call site, and it belongs in the same change as the port.
  *
- * Its only consumer with direct assertions is `tests/unit/setup.test.mjs`; tests/fixtures/pure_probe.mjs
- * also dispatches it to exercise wizard/web_first test scenarios.
+ * Its only consumer with direct assertions is `tests/unit/setup.test.mjs`.
  */
 export function detailLines(kind, label, data) {
   // The three constitutional tiers share one treatment — the label, a blank, then the body —