geneseed 3.1.3 → 3.2.0

package/js/web/docs.mjs

@@ -1,44 +1,23 @@
 /**
- * The web console's Docs pages — `rituals/_web_docs.py` and the registry
- * `_web_core.py` builds from `docs/web/`.
+ * The web console's Docs pages, and the registry built from `docs/web/`.
  *
- * WHAT CROSSES HERE AND WHAT DOES NOT, measured before the phase was taken rather than
- * discovered inside it. `api_docs_page` dispatches on five KINDS, and 57 of the 59 pages
- * are one of the three that are pure string work: `markdown` (read, slice, strip),
- * `concept` (an inline body with live counts substituted) and `glossary`. Those three
- * crossed in P6d, `about` in P8c (four of five), and `cli` is P10c's. The two deferrals had
- * a reason that is not "it is long":
+ * `cli` docs render via `cliReference()` in `js/ui/cli.mjs`, which reads
+ * `js/cli-table.json` — the CLI's own metadata, since `harness.build_argparser()`'s parser
+ * is not something a Node twin can introspect. `bin/geneseed-cli.mjs`'s `VERBS` table reads
+ * the same file, so there is exactly one description of the CLI surface, not a second
+ * transcription of it.
  *
- *   * `cli` walked `harness.build_argparser()` — **182 lines, 24 subparsers, 43
- *     `add_argument` calls**, every one carrying help text, a metavar, choices and a
- *     default. A Node twin cannot introspect it; reproducing it means transcribing the
- *     whole CLI surface into a second table that would describe verbs `bin/geneseed-cli.mjs`
- *     cannot even run. This port's standing rule is that a copy of a value under test stops
- *     being the value under test, and this would be the largest copy in it. **PAID IN P10c**,
- *     by the fix the deferral named: the parser's metadata became a FILE both implementations
- *     read — `js/cli-table.json` since P2. `js/ui/cli.mjs` is the reader,
- *     `tests/test_cli_reference.py` is what fails when the table and the parser part company
- *     for as long as the parser exists, and `bin/geneseed-cli.mjs`'s `VERBS` table
- *     — which was a SECOND transcription of the same 43 calls — reads it too, so the port
- *     ended with one description of the CLI where it had been heading for three.
- *   * `about` called `_update._origin_display()`, which shells out to `git remote get-url`.
- *     `rituals/_update.py` was P8's whole subject and P6d would have needed an
- *     `_ALLOWED_SPAWNS` row for `git` ahead of the phase that argues for it. **PAID IN P8c**:
- *     P8a made that argument and ported `originDisplay()`, so the deferral was a one-line
- *     removal from `NOT_PORTED_KINDS` and a row in `KIND_ROUTES`.
- *
- * So `NOT_PORTED_KINDS` declares what is left, `api_docs_page` answers 501 for it, and
+ * So `NOT_PORTED_KINDS` declares what is left, `apiDocsPage` answers 501 for it, and
  * `tests/unit/web_server.test.mjs` requires `PORTED_KINDS` ∪ `NOT_PORTED_KINDS` to equal
- * `REF_KINDS` — a FROZEN LITERAL of the five kinds the reference dispatched on, since the
- * reference itself is deleted. Same partition shape as the route table, which is why it is a
- * table here too and not two `if`s.
+ * `REF_KINDS` — a FROZEN LITERAL of the five kinds this daemon has ever needed to dispatch
+ * on. Same partition shape as the route table, which is why it is a table here too and not
+ * two `if`s.
  *
- * THE `?harness=` QUERY PARAM LANDS HERE. P6a skipped it deliberately (no caller); it is
- * the Docs selector, and it is the ONLY input to these endpoints that is not the checkout,
- * so it is also the only thing a cell can vary. Every filtering rule below is gated by
- * sending both values over one page.
+ * THE `?harness=` QUERY PARAM IS the Docs selector, and it is the ONLY input to these
+ * endpoints that is not the checkout itself — the one thing a test can vary. Every
+ * filtering rule below is exercised by sending both values over one page.
  */
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync } from 'node:fs';
 import path from 'node:path';
 
 import { ROOT, THEMES } from '../build/source.mjs';
@@ -46,18 +25,17 @@ import { cliReference } from '../ui/cli.mjs';
 import { readJsonMaybe, readMaybe } from '../hosts/installs.mjs';
 import { resolvePath } from '../hosts/hosts.mjs';
 import { parseJson } from '../lib/json.mjs';
+import { isFile } from '../lib/fs.mjs';
 import { normcase } from '../lib/paths.mjs';
 import { WHITESPACE, stripWhitespace } from '../lib/text.mjs';
 import { statusData } from '../inspect/status.mjs';
 import { originDisplay } from '../maintain/update.mjs';
 import { NotFound, deployed, resolveLinks } from './api.mjs';
 
-const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
-
 const DOC_DIR = path.join(ROOT, 'docs', 'web');
 
 /**
- * `_web_core._doc_frontmatter` — a docs page split into its frontmatter map and its body.
+ * A docs page split into its frontmatter map and its body.
  *
  * Deliberately not YAML: each value is a JSON scalar (or a JSON object for `link`), which
  * covers every key these pages use and parses with the standard library. A value that is
@@ -77,23 +55,22 @@ export function docFrontmatter(text) {
     const key = (colon < 0 ? line : line.slice(0, colon)).trim();
     const raw = (colon < 0 ? '' : line.slice(colon + 1)).trim();
     if (!key || !raw) continue;
-    // `json.loads` first, the raw string on a decode error — and `parseJson`, so a
-    // frontmatter number keeps the int/float distinction the rest of this port protects.
+    // `parseJson`, so a frontmatter number keeps the int/float distinction the rest of
+    // this codebase protects.
     try { meta[key] = parseJson(raw); } catch { meta[key] = raw; }
   }
   return [meta, body];
 }
 
 /**
- * `_web_core._load_doc_groups` — the Docs registry, built from `docs/web/`.
+ * The Docs registry, built from `docs/web/`.
  *
  * A page whose file is missing or malformed is skipped rather than crashing the server; an
  * unreadable registry yields an empty Docs section, which the UI renders as "no pages".
  *
- * NOT cached at module load, where the Python builds `DOC_GROUPS` once at import. The
- * difference is invisible to a request — `docs/web/` cannot change under a running daemon
- * any more than `dist/` can — and a module-level constant would freeze whatever `ROOT` was
- * when the corpus first imported this file.
+ * NOT cached at module load. The difference is invisible to a request — `docs/web/` cannot
+ * change under a running daemon any more than `dist/` can — and a module-level constant
+ * would freeze whatever `ROOT` was when this file was first imported.
  */
 export function docGroups() {
   const groups = readJsonMaybe(path.join(DOC_DIR, '_groups.json'));
@@ -118,7 +95,7 @@ export function docGroups() {
   const out = [];
   for (const g of groups) {
     const entry = byId.get(g.id);
-    // `sorted(key=lambda t: t[0])` is STABLE, so equal orders keep filename order.
+    // STABLE sort: equal orders keep filename order.
     entry.pages = entry.pages
       .map((pair, i) => [pair[0], i, pair[1]])
       .sort((a, b) => (a[0] - b[0]) || (a[1] - b[1]))
@@ -129,8 +106,8 @@ export function docGroups() {
 }
 
 /**
- * `_web_core.GLOSSARY_KEYS` — the neutral term, the theme key whose value renames it, and
- * the one-line description. A key of `null` marks a term no theme renames.
+ * The neutral term, the theme key whose value renames it, and the one-line description. A
+ * key of `null` marks a term no theme renames.
  */
 const GLOSSARY_KEYS = [
   // The three tiers, in constitutional order and before the entities — a reader who does not
@@ -170,11 +147,9 @@ const GLOSSARY_KEYS = [
 // ---- counts substituted into concept bodies -------------------------------------------
 
 /**
- * `_web_docs._doc_counts`.
- *
- * Exported so the tier tokens can be gated on the day they are ADDED rather than on the day a
- * page first spends one. Only one page carries `{N_LAWS}` today; a test that could only reach
- * these through a rendered body would leave four of the seven untested until Task 6.2.
+ * Exported so the tier tokens can be gated on the day they are ADDED rather than on the day
+ * a page first spends one. Only one page carries `{N_LAWS}` today; a test that could only
+ * reach these through a rendered body would leave most of them untested.
  */
 export function docCounts(state) {
   const inv = state.inventory;
@@ -204,7 +179,6 @@ export function docCounts(state) {
   };
 }
 
-/** `_web_docs._sub_counts`. */
 function subCounts(state, body) {
   if (!body.includes('{N_')) return body;
   let out = body;
@@ -226,7 +200,6 @@ const HARNESS_CLOSE_RE = /^\s*<!--\s*\/harness\s*-->\s*$/;
  */
 const HARNESS_HINT_RE = /<!--\s*harness:/;
 
-/** `_web_docs._norm_harness`. */
 export function normHarness(value, state) {
   const v = (value || '').trim().toLowerCase();
   if (HARNESSES.includes(v)) return v;
@@ -234,7 +207,7 @@ export function normHarness(value, state) {
 }
 
 /**
- * `_web_docs._harness_blocks_balanced` — every open has a matching close, with no nesting.
+ * Every open has a matching close, with no nesting.
  *
  * A marker inside a ``` fence is example text, not a marker (the same rule `sliceSection`
  * uses). Its purpose is to FAIL OPEN: an unbalanced marker leaves the body untouched, so a
@@ -262,7 +235,6 @@ export function harnessBlocksBalanced(lines) {
   return !open;
 }
 
-/** `_web_docs._strip_harness_blocks`. */
 export function stripHarnessBlocks(body, harnessName) {
   if (!HARNESS_HINT_RE.test(body)) return body;
   const lines = splitLines(body);
@@ -287,9 +259,9 @@ export function stripHarnessBlocks(body, harnessName) {
 }
 
 /**
- * `str.splitlines()` — which is NOT `split('\n')`: it drops a single trailing newline
- * instead of yielding a final empty string, and that difference reaches the output here
- * because the result is re-joined with `\n`.
+ * NOT a bare `split('\n')`: this drops a single trailing newline instead of yielding a
+ * final empty string, and that difference reaches the output here because the result is
+ * re-joined with `\n`.
  */
 function splitLines(s) {
   const parts = s.split('\n');
@@ -297,7 +269,7 @@ function splitLines(s) {
   return parts;
 }
 
-/** `_web_docs._visible_groups` — pure; the registry is never mutated. */
+/** Pure; the registry is never mutated. */
 function visibleGroups(harnessName) {
   const groups = [];
   for (const g of docGroups()) {
@@ -316,14 +288,11 @@ const SLUG_DASH_RE = /-+/g;
 const HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
 
 /**
- * `_web_docs._slugify_heading` — the same rules the frontend's `slug()` uses, so a
- * registry `anchor` written against a heading matches the id the renderer assigns.
+ * The same rules the frontend's `slug()` uses, so a registry `anchor` written against a
+ * heading matches the id the renderer assigns.
  *
- * `WHITESPACE` and `stripWhitespace` rather than `\s` and `trim()`, and the corpus in
- * `tests/test_pure_function_parity.py` is what made that necessary rather than tidy: the
- * two languages' whitespace classes differ at U+FEFF and at U+001C-U+001F, and a heading
- * carrying one slugs differently on each side. See `WHITESPACE`'s docblock for the measured
- * set.
+ * `WHITESPACE` and `stripWhitespace` rather than `\s` and `trim()` — see `WHITESPACE`'s own
+ * docblock for the measured set of characters where this matters.
  */
 export function slugifyHeading(text) {
   let s = stripWhitespace(text.toLowerCase()).replace(SLUG_STRIP_RE, '');
@@ -332,7 +301,7 @@ export function slugifyHeading(text) {
 }
 
 /**
- * `_web_docs._slice_section` — the body trimmed to one heading's section.
+ * The body trimmed to one heading's section.
  *
  * Returns `[body, ok]`; `ok === false` (with the ORIGINAL body) when the anchor is
  * missing, so the caller falls back to the whole document. An H1 slice stops at the first
@@ -372,7 +341,6 @@ export function sliceSection(body, anchor) {
 
 // ---- the endpoints -----------------------------------------------------------------------
 
-/** `_web_docs._find_doc_page`. */
 function findDocPage(pageId) {
   for (const g of docGroups()) {
     for (const p of g.pages) if (p.id === pageId) return p;
@@ -381,9 +349,9 @@ function findDocPage(pageId) {
 }
 
 /**
- * `_web_docs._read_doc_source` — a markdown file relative to ROOT, guarded against escapes
- * the same way the catalog is. A GET carries no token, so `rel` comes out of the registry
- * but the guard is what makes that safe to say.
+ * A markdown file relative to ROOT, guarded against escapes the same way the catalog is. A
+ * GET carries no token, so `rel` comes out of the registry, but the guard is what makes
+ * that safe to say.
  */
 function readDocSource(rel) {
   const target = resolvePath(path.join(ROOT, rel));
@@ -397,7 +365,7 @@ function within(child, parent) {
   return p.length <= c.length && p.every((seg, i) => c[i] === seg);
 }
 
-/** `_web_docs._glossary` — the deployed theme's words beside the neutral ones. */
+/** The deployed theme's words beside the neutral ones. */
 function glossary(state) {
   const load = (theme) => {
     const doc = readJsonMaybe(path.join(THEMES, `${theme}.json`));
@@ -423,12 +391,11 @@ function glossary(state) {
 }
 
 /**
- * `_web_docs._about` — the About page: a version line, the deployed install, and the links.
+ * The About page: a version line, the deployed install, and the links.
  *
  * `repo` is the install's OWN git origin (where updates come from), and `repo_is_github` is
- * what gates the github-shaped deep links in the UI. Both come from `originDisplay()`, which
- * is the one thing P6d could not have: it shells `git remote get-url`, and P8a is the phase
- * that argued for the `git` row in `_ALLOWED_SPAWNS`.
+ * what gates the github-shaped deep links in the UI. Both come from `originDisplay()`,
+ * which shells out to `git remote get-url` (the `git` row in `ALLOWED_SPAWNS`).
  *
  * `version` IS NOT WHAT IT LOOKS LIKE, and it is the shape this page has always had rather than
  * a shortcut here. It reads a `version` key off the status snapshot and THERE IS NO SUCH KEY —
@@ -436,8 +403,8 @@ function glossary(state) {
  * field is `{}`, always, and `sd.version || {}` reproduces the EXPRESSION rather than the
  * constant: if the key ever appears, the page gains it without another edit.
  *
- * THERE IS NO INTERPRETER FIELD, and the absence is deliberate — see `apiSetup`, which spells
- * the same absence for the same reason.
+ * THERE IS NO INTERPRETER FIELD, and the absence is deliberate — see `apiSetup` in
+ * `api.mjs`, which spells the same absence for the same reason.
  *
  * `statusData()` is called for one dead field, and deliberately: this page has always paid that
  * cost, and skipping it would answer faster in a way no gate measures and no user asked for.
@@ -453,41 +420,32 @@ function about(state) {
     target: String(state.target),
     root: String(ROOT),
     repo: od.url,
-    // `githubSlug`, not `github_slug`. `OriginDisplay`'s JS twin keeps the Python field in
-    // camelCase the way every other ported record does, and the RESPONSE key is snake_case
-    // because it is the wire format — the two spellings meet exactly here. Reading the wire
-    // name off the record gives `undefined`, which is a perfectly plausible `false`: the About
-    // page silently drops every github deep link and nothing else changes. Caught by comparing
-    // the two payloads by hand before a cell existed; `docs/the-about-page-...` is the cell.
+    // `githubSlug`, not `github_slug` — the record itself is camelCase like every other
+    // object in this codebase; the RESPONSE key below is snake_case because that is the
+    // wire format. Reading the wrong spelling off the record gives `undefined`, which is a
+    // perfectly plausible `false`: the About page would silently drop every github deep
+    // link and nothing else would change.
     repo_is_github: Boolean(od.githubSlug),
     license: 'MIT',
   };
 }
 
 /**
- * EMPTY SINCE P10c, AND KEPT DECLARED — the third partition in this port to reach that state,
+ * EMPTY, AND KEPT DECLARED — the third partition in this codebase to reach that state,
  * after `NOT_PORTED_POST` and `NOT_PORTED_ACTIONS`.
  *
- * `tests/test_web_server.py` cross-checks this set against the kinds
- * `_web_docs.api_docs_page` dispatches on by `ast`, and that check is at its STRONGEST when
- * the set is empty: it then says every kind the reference dispatches on is answered here. A
- * sixth kind added to the reference still cannot quietly fall through to the `NotFound` at
- * the bottom, and the next unported kind has a place to be declared rather than reading as a
- * typo'd page id.
+ * `tests/unit/web_server.test.mjs` cross-checks this set against the kinds `apiDocsPage`
+ * dispatches on, and that check is at its STRONGEST when the set is empty: it says every
+ * kind this daemon can dispatch on is answered here. A sixth kind added later still cannot
+ * quietly fall through to the `NotFound` at the bottom, and it has a place to be declared
+ * rather than reading as a typo'd page id.
  *
- * WHAT DIED WITH THE LAST ROW is the 501 arm's only reachable target. `test_web_server.py`'s
- * running probe used to GET `/api/docs/page/cli` and require 501; with the set empty no page
- * has an unported kind and none can be borrowed. That probe is now the positive control for
- * `cli` (200), and the claim that the 501 arm still works rests on the declaration check
- * alone — strictly weaker, discipline #7, and said out loud there as it is here.
- *
- * `about` left in P8c (`_origin_display` and the `git` spawn behind it, not the page).
- * `cli` left in P10c, and its blocker was neither: it was that `harness.build_argparser()`
- * cannot be introspected from Node at all. See `js/ui/cli.mjs`.
+ * THE 501 ARM HAS NO REACHABLE TARGET TODAY: with this set empty, no page names an
+ * unported kind. Its correctness rests on the declaration check above, not on any request
+ * that actually reaches it — worth knowing before "simplifying" it away as dead code.
  */
 export const NOT_PORTED_KINDS = new Set();
 
-/** `_web_docs.api_docs`. */
 export function apiDocs(state, harnessName = null) {
   const hn = normHarness(harnessName, state);
   const groups = visibleGroups(hn).map((g) => ({
@@ -499,8 +457,6 @@ export function apiDocs(state, harnessName = null) {
 }
 
 /**
- * `_web_docs.api_docs_page`.
- *
  * The lookup deliberately ignores a page's own `harness` tag: a deep link to a page the
  * active harness hides still resolves, and the client redirects it out of view.
  */
@@ -521,10 +477,9 @@ export function apiDocsPage(state, pageId, harnessName = null) {
 /**
  * The three kinds that cross, as a TABLE and not three `if`s.
  *
- * `tests/test_web_server.py` requires `Object.keys(KIND_ROUTES) ∪ NOT_PORTED_KINDS` to
- * equal the kinds `_web_docs.api_docs_page` dispatches on, and M23 is why that reads the
- * table the dispatcher actually consults rather than a list beside it: a gate on a
- * declaration cannot see a dispatcher that stopped using it.
+ * `tests/unit/web_server.test.mjs` requires `Object.keys(KIND_ROUTES) ∪ NOT_PORTED_KINDS` to
+ * equal the kinds `apiDocsPage` dispatches on — this table is what the dispatcher actually
+ * consults, so a declaration-only check cannot see a dispatcher that stopped using it.
  */
 const KIND_ROUTES = {
   markdown: (state, pageId, page, hn) => {
@@ -552,8 +507,8 @@ const KIND_ROUTES = {
   about: (state, pageId, page) => ({
     id: pageId, title: page.title, kind: 'about', ...about(state),
   }),
-  // P6d's deferral, paid in P10c. The row is one line because the work was not in the page:
-  // it was in making `harness.build_argparser()`'s metadata a file both implementations read.
+  // The row is one line because the work was not in the page: it was in making the CLI's
+  // metadata (`js/cli-table.json`) a file this reads directly.
   cli: (state, pageId, page) => ({
     id: pageId, title: page.title, kind: 'cli', ...cliReference(),
   }),