geneseed 3.1.1 → 3.1.3

package/js/web/api.mjs

@@ -14,7 +14,7 @@
  * `apiOverview` compute anything of their own, and most of what `apiOverview` computes is
  * counting.
  *
- * THE ONE PARAMETER: `doctorCollect({groups})`. `js/doctor.mjs` carried a `ran(check,
+ * THE ONE PARAMETER: `doctorCollect({groups})`. `js/inspect/doctor.mjs` carried a `ran(check,
  * label, probs)` that returned its third argument and threw the first two away, with a
  * docblock saying the label stays "because it is the one place each check is NAMED, and
  * what P6's accumulator will key on". This is that phase. `on_progress=` — the TUI's — is
@@ -26,15 +26,15 @@
  * `state.inventory` and the badges and taxonomy classes belonged to a phase that had not
  * arrived. `api_catalog` consumes exactly those fields, so this is the phase that would
  * have made the counting half and the reading half two classifiers. It did not:
- * `tuiInventory` in `js/inventory.mjs` is the one walk, `js/status.mjs`'s `inventoryCounts`
+ * `tuiInventory` in `js/inspect/inventory.mjs` is the one walk, `js/inspect/status.mjs`'s `inventoryCounts`
  * is three `length`s off it, and `specEntries` grew out of `specNames` by adding the READ
  * rather than by being written beside it.
  *
  * THE TAXONOMY WAS ALREADY PORTED, which the measurement found and the handoff did not.
- * `js/status.mjs` said flatly that "the ~111 LOC of TUI taxonomy" was P7's; `LAW_CLASS`,
+ * `js/inspect/status.mjs` said flatly that "the ~111 LOC of TUI taxonomy" was P7's; `LAW_CLASS`,
  * `SKILL_CLASS`, `LAW_CLASSES` and `ENTITY_STATUSES` had in fact crossed in P5g inside
- * `js/doctor.mjs`, because doctor's authoring gates are what validate them. P6c moved the
- * four to `js/inventory.mjs` — where Python keeps them — rather than copying them, and
+ * `js/inspect/checks-authoring.mjs`, because doctor's authoring gates are what validate them. P6c moved the
+ * four to `js/inspect/inventory.mjs` — where Python keeps them — rather than copying them, and
  * doctor imports them back. Only `parse_laws`, `load_registry` and `entity_status` were
  * genuinely new.
  *
@@ -46,7 +46,7 @@
  * carries the key, which is why its replay harness erases it before comparing.
  *
  * P6c's ROUTES ARE THE FIRST THAT PARSE A PATH, which brings three things no earlier
- * endpoint could reach: `pyUnquote` (NOT `decodeURIComponent`, which throws where the
+ * endpoint could reach: `percentDecode` (NOT `decodeURIComponent`, which throws where the
  * reference leaves a stray `%` alone), the `NotFound` → 404 convention, and `flatName`'s
  * traversal refusal — a GET carries no token, so before that check the item route was an
  * arbitrary-file read.
@@ -55,27 +55,28 @@ import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { ROOT, THEMES, discoverNames } from '../checkout.mjs';
-import { diffCollect } from '../diff.mjs';
-import { doctorCollect } from '../doctor.mjs';
-import { excludesSnapshot } from '../excludes.mjs';
-import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir, pyResolve } from '../hosts.mjs';
+import { CONFIG, ROOT, THEMES, discoverNames } from '../build/source.mjs';
+import { sourceReleaseVersion } from '../hosts/opencode.mjs';
+import { diffCollect } from '../inspect/diff.mjs';
+import { doctorCollect } from '../inspect/doctor.mjs';
+import { excludesSnapshot } from '../inspect/excludes.mjs';
+import { GLOBAL_MANIFEST, HOSTS, opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   doctrinesForBuild, excludedRulesOfDir, footprintOfDir, installState, installTargets,
   installedDefaults, modeOfDir,
   postureOfDir, readJsonMaybe, readMaybe, themeOfDir,
-} from '../installs.mjs';
-import { frontmatter } from '../hooks.mjs';
+} from '../hosts/installs.mjs';
+import { frontmatter } from '../hosts/hooks.mjs';
 import {
   SKILL_CLASS, entityStatus, loadRegistry, tuiInventory,
-} from '../inventory.mjs';
-import { firstBlockquote } from '../native.mjs';
-import { EMIT_OPTIONS, themeOptions } from '../setup.mjs';
-import { accentFor, statusData } from '../status.mjs';
-import {
-  comparePaths, normcase, pyStripSpace, pyUnquote, readText, withDiscardableStderr, within,
-} from '../lib/fs.mjs';
-import { readJsonc } from '../settings.mjs';
+} from '../inspect/inventory.mjs';
+import { firstBlockquote } from '../hosts/native.mjs';
+import { EMIT_OPTIONS, themeOptions } from '../maintain/setup.mjs';
+import { accentFor, statusData } from '../inspect/status.mjs';
+import { readText, withDiscardableStderr } from '../lib/fs.mjs';
+import { comparePaths, normcase, within } from '../lib/paths.mjs';
+import { stripWhitespace, percentDecode } from '../lib/text.mjs';
+import { readJsonc } from '../hosts/settings.mjs';
 import { apiActivity, apiActivityDetail } from './activity.mjs';
 import { apiMcp, apiRules } from './actions.mjs';
 import { apiGraph } from './graph.mjs';
@@ -87,7 +88,7 @@ const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return
 const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
 
 /** Two resolved paths, compared as `PurePath.__eq__` does — case-folded on Windows. */
-const samePath = (a, b) => normcase(pyResolve(a)) === normcase(pyResolve(b));
+const samePath = (a, b) => normcase(resolvePath(a)) === normcase(resolvePath(b));
 
 /** `dict.get(key, default)` — `??` would also swallow an explicit null the file declared. */
 const dget = (obj, key, dflt) => (Object.hasOwn(obj, key) ? obj[key] : dflt);
@@ -177,7 +178,7 @@ export function webState(theme = null, target = null) {
       try {
         const em = path.join(d, '.geneseed-emit');
         if (isFile(em)) {
-          const v = pyStripSpace(readText(em));
+          const v = stripWhitespace(readText(em));
           if (v) return v;
         }
       } catch { /* as the Python's `except OSError: pass` */ }
@@ -264,7 +265,7 @@ export function specEntries(root, nested) {
     if (!isFile(p)) continue;
     const [fm, body] = frontmatter(readMaybe(p) ?? '');
     const name = nested ? path.basename(path.dirname(p)) : path.basename(p, '.md');
-    out.push({ name, desc: specDesc(fm, body), body, source: pyResolve(p) });
+    out.push({ name, desc: specDesc(fm, body), body, source: resolvePath(p) });
   }
   out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   return out;
@@ -353,7 +354,7 @@ export function memoryItems(state) {
       name: stem,
       title: fm.has('name') ? fm.get('name') : stem,
       desc: fm.has('description') ? fm.get('description') : '',
-      source: pyResolve(p),
+      source: resolvePath(p),
     };
   });
 }
@@ -363,7 +364,7 @@ export function notebookItems(state) {
   const d = notebookDir(state);
   if (!isDir(d)) return [];
   return globMd(d).map((n) => ({
-    name: stemOf(n), title: stemOf(n), desc: '', source: pyResolve(path.join(d, n)),
+    name: stemOf(n), title: stemOf(n), desc: '', source: resolvePath(path.join(d, n)),
   }));
 }
 
@@ -381,7 +382,7 @@ export function configItems(state) {
     if (!isFile(p)) continue;
     const [title, desc] = CONFIG_META[fname] ?? [fname, ''];
     out.push({ name: fname, title, desc, type: 'config', kind: 'manifest',
-      source: pyResolve(p) });
+      source: resolvePath(p) });
   }
   return out;
 }
@@ -389,13 +390,14 @@ export function configItems(state) {
 export const WIKI_FILE_CAP = 5000;
 
 /**
- * `pyResolve` for a path that came out of a HAND-MAINTAINED manifest — `null`, never a throw.
+ * `resolvePath` for a path that came out of a HAND-MAINTAINED manifest — `null`, never a throw.
  *
- * The three wiki sites below are the only request-path callers of `expanduser`, and it now
- * REFUSES a `~user` form by printing and throwing (`js/hosts.mjs`'s docblock). None of them
- * may let that escape: `js/web/server.mjs` wraps the whole GET in a blanket `catch` → a JSON
+ * The three wiki sites below, and `apiDeployCmd` in `js/web/actions.mjs`, are the
+ * request-path callers of `expanduser`, and it REFUSES a `~user` form by printing and throwing
+ * (`js/hosts/hosts.mjs`'s docblock). None of them may let that escape: `js/web/handler.mjs`
+ * wraps the whole GET in a blanket `catch` → a JSON
  * 500, so an unguarded refusal would turn ONE bad line in a file the user hand-edits into a
- * dead Knowledge section. That is the same argument `sovereignBypass` makes in `js/hooks.mjs`
+ * dead Knowledge section. That is the same argument `sovereignBypass` makes in `js/hosts/hooks.mjs`
  * — contain the refusal per entry and take the site's OWN degrade — and each of the three
  * already has one: `[]`, `continue`, `continue`-into-404. The reference reaches those same
  * three degrades for a `~user` path, from the other direction: `ntpath.expanduser` expands
@@ -413,7 +415,7 @@ export const WIKI_FILE_CAP = 5000;
  */
 function wikiPath(p) {
   try {
-    return withDiscardableStderr(() => pyResolve(p));
+    return withDiscardableStderr(() => resolvePath(p));
   } catch {
     return null;
   }
@@ -423,7 +425,7 @@ function wikiPath(p) {
  * `_web_catalog._wiki_manifest` — `$GENESEED_WIKI` first, else `wiki.jsonc` beside the
  * deployed bundle, read with the harness's generic JSONC loader.
  *
- * `pyResolve` where the reference only `expanduser()`s. NOT OBSERVABLE, so it stays: `p` is
+ * `resolvePath` where the reference only `expanduser()`s. NOT OBSERVABLE, so it stays: `p` is
  * consumed by `isFile` and `mcpLoad` and never reaches a response body, and both of those
  * follow symlinks and resolve a relative path against the same cwd anyway.
  */
@@ -476,7 +478,7 @@ export function wikiItems(state) {
     if (!w || typeof w !== 'object' || Array.isArray(w)) continue;
     const wname = String(dget(w, 'name', null) || 'wiki');
     // PER ENTRY, and the loop continues — one unusable `path` in the manifest must not blank
-    // every OTHER vault in it. `pyResolve` where the reference only `expanduser()`s is again
+    // every OTHER vault in it. `resolvePath` where the reference only `expanduser()`s is again
     // unobservable: `root` is only ever joined against or used as the base of a `relative()`
     // whose other operand was built FROM it, and `source` is `.resolve()`d on both sides.
     const root = wikiPath(String(dget(w, 'path', null) || ''));
@@ -504,7 +506,7 @@ export function wikiItems(state) {
         seen.add(key);
         items.push({ name: key, title: path.basename(md, '.md'),
           desc: mds.length === 1 ? desc : r, type: 'wiki', kind: 'page', group: wname,
-          source: pyResolve(md) });
+          source: resolvePath(md) });
       }
     }
   }
@@ -525,7 +527,7 @@ export function apiWikiItem(state, name) {
     // where the reference lands when the expanded root turns out not to exist.
     const root = wikiPath(String(dget(w, 'path', null) || ''));
     if (!root) continue;
-    const p = pyResolve(path.join(root, rel));
+    const p = resolvePath(path.join(root, rel));
     if (rel && path.extname(p) === '.md' && within(p, root) && isFile(p)) {
       const body = readMaybe(p) ?? '';
       return { type: 'wiki', name, title: path.basename(p, '.md'), desc: '',
@@ -536,10 +538,13 @@ export function apiWikiItem(state, name) {
 }
 
 /**
- * `harness._within` — re-exported from `js/lib/fs.mjs`, where P6i moved it.
+ * `harness._within` — re-exported from `js/lib/paths.mjs`, where the lib split put it.
+ *
+ * ⚠ A SECOND, INDEPENDENT COPY lives in `js/inspect/scan.mjs`, written for the doctor's tree
+ * walks. A change to the containment rule has to land on both, and nothing compares them.
  *
  * It lived here from P6b (the restore's containment check) until `_install_move_list` needed
- * the same predicate from `js/uninstall.mjs`, which must not import the web tree. The
+ * the same predicate from `js/maintain/uninstall.mjs`, which must not import the web tree. The
  * re-export keeps `js/web/actions.mjs`'s import path unchanged.
  */
 export { within };
@@ -577,9 +582,9 @@ export function resolveLinks(state, body) {
   const links = [];
   const seen = new Set();
   for (const m of body.matchAll(WIKILINK_RE)) {
-    // `pyStripSpace`, not `trim()` — P6d measured the two whitespace classes apart and P6e
+    // `stripWhitespace`, not `trim()` — P6d measured the two whitespace classes apart and P6e
     // gave this regex a second reader, so the two call sites answer with one rule.
-    const label = pyStripSpace(m[1]);
+    const label = stripWhitespace(m[1]);
     if (known.has(label) && !seen.has(label)) {
       seen.add(label);
       links.push({ label, type: known.get(label), name: label });
@@ -715,7 +720,7 @@ export function apiItem(state, type, name) {
     if (!isFile(p)) throw new NotFound(name);
     const body = readMaybe(p) ?? '';
     return { type, name, title: name, desc: '', body,
-      links: resolveLinks(state, body), source: pyResolve(p) };
+      links: resolveLinks(state, body), source: resolvePath(p) };
   }
   if (type === 'wiki') return apiWikiItem(state, name);
   if (type === 'config') {
@@ -725,7 +730,7 @@ export function apiItem(state, type, name) {
     const raw = readMaybe(p) ?? '';
     const [title, desc] = CONFIG_META[name] ?? [name, ''];
     return { type, name, title, desc, manifest: configManifest(name, p),
-      body: `\`\`\`json\n${raw}\n\`\`\``, links: [], source: pyResolve(p) };
+      body: `\`\`\`json\n${raw}\n\`\`\``, links: [], source: resolvePath(p) };
   }
   throw new NotFound(type);
 }
@@ -837,8 +842,18 @@ export function apiOverview(state) {
     }
   }
   let buildTime = null;
+  // The SAME mtime twice, on purpose. `build_time` is the stamp a person reads; `build_epoch`
+  // is the number a relative label ("20h") is computed from. The console used to have only the
+  // first and had to re-parse it, and `Date.parse` on a space-separated local stamp is
+  // engine-dependent — a plausible-but-wrong "2h" is the exact failure a second field costs
+  // nothing to prevent.
+  let buildEpoch = null;
   const agentMd = path.join(state.target, 'AGENT.md');
-  if (isFile(agentMd)) buildTime = stampMinute(statSync(agentMd).mtimeMs);
+  if (isFile(agentMd)) {
+    const ms = statSync(agentMd).mtimeMs;
+    buildTime = stampMinute(ms);
+    buildEpoch = Math.floor(ms / 1000);
+  }
   // Which detected install the current view points at, so the dashboard's footprint hero
   // can re-emit exactly it. Mirrors `viewCfg`'s rule, spelled out as the reference spells
   // it out — the two are separate code in the Python too.
@@ -898,22 +913,107 @@ export function apiOverview(state) {
     doctor: state.doctor,
     diff,
     build_time: buildTime,
+    build_epoch: buildEpoch,
+    // The RELEASE LABEL OF THE SOURCE THIS CONSOLE IS SERVED FROM, not of the deployed install —
+    // the two differ whenever something has changed since the last emit, which is exactly when
+    // knowing which one you are looking at matters. `.geneseed-version` carries the install's own
+    // label and the fingerprint comparison already reports the drift; this answers the plainer
+    // question the topbar asks, "what is running".
+    //
+    // Degrades to null rather than to a wrong number: `sourceReleaseVersion` answers '0.0.0' for
+    // an unreadable config, and a console confidently displaying 0.0.0 is worse than one that
+    // shows nothing.
+    version: releaseLabel(),
   };
 }
 
+/**
+ * How many files `apiRecent` will `stat` before it gives up on a section.
+ *
+ * The wiki is the only section with no ceiling — `WIKI_FILE_CAP` lets one vault contribute
+ * 5000 pages — and "the newest N of the first 1200 I looked at" is not the newest N. So a
+ * section over the cap is DROPPED and NAMED in `skipped`, rather than answered from a
+ * truncated pool: the card can then say which shelves it read, which is a fact, where a
+ * silently-biased list would be a wrong one nobody could catch.
+ */
+const RECENT_STAT_CAP = 1200;
+
+/** How many entries `/api/recent` returns — the card shows a handful, not a feed. */
+const RECENT_LIMIT = 8;
+
+/**
+ * THE NEWEST FILE-BACKED ENTRIES ACROSS THE HARNESS — the "freshly grown" card's whole payload.
+ *
+ * A GET BEYOND THE REFERENCE (`GET_BEYOND_REF` in `routes.mjs`), and the first one. It exists
+ * because NOTHING else in this API carries a per-entry date: every catalog row is
+ * `{name, title, desc, source}` and the only two timestamps on the whole surface are
+ * `overview.build_time` and `doctor.checked_at`. A client cannot stat a path, so "what changed
+ * lately" was unanswerable without a server that looks.
+ *
+ * ONLY THE SECTIONS THE USER WRITES BY HAND. Memory, notebook, wiki and config each name a
+ * file someone actually authored, at a moment that means something.
+ *
+ * ⚠ SKILLS AND AGENTS ARE EXCLUDED, AND THEY WERE IN HERE FIRST — a live check is what took
+ * them out. Their `source` is the EMITTED artefact (`~/.config/opencode/skills/<x>/SKILL.md`),
+ * written by the last build, so on a real install all 67 of them carry ONE mtime and it is
+ * `overview.build_epoch` to the second. Sorted newest-first they filled the whole answer with
+ * the alphabetical head of the last rebuild — `advocate, architect, brainstorm, clarify…` —
+ * and pushed out every genuinely recent memory and note. Dating a rendered file dates the
+ * BUILD, which the overview already states once and correctly. (Reading the repo's `src/`
+ * instead would not save it: a fresh clone stamps every file with the checkout.)
+ *
+ * The constitution is out for the same family of reason: its tiers are entries inside shared
+ * law files, so a per-rule mtime would be the file's, repeated — one wrong date on nine rows.
+ */
+export function apiRecent(state) {
+  const sections = [
+    ['memory', 'memory', () => memoryItems(state)],
+    ['notebook', 'notebook', () => notebookItems(state)],
+    ['wiki', 'wiki', () => wikiItems(state)],
+    ['config', 'config', () => configItems(state)],
+  ];
+  const items = [];
+  const skipped = [];
+  for (const [section, type, load] of sections) {
+    let rows;
+    try { rows = load() ?? []; } catch { skipped.push(section); continue; }
+    if (rows.length > RECENT_STAT_CAP) { skipped.push(section); continue; }
+    for (const r of rows) {
+      if (!r.source) continue;
+      let mtime;
+      // A row whose file has been moved or deleted since the inventory was rendered is not an
+      // error — it is simply not among the newest anything. Skipping beats a null date that
+      // would sort somewhere.
+      try { mtime = Math.floor(statSync(r.source).mtimeMs / 1000); } catch { continue; }
+      items.push({ section, type, name: r.name, title: r.title || r.name, mtime });
+    }
+  }
+  // Newest first, ties broken by name so the order is stable between two requests a second
+  // apart — several files written by one rebuild share a second exactly.
+  items.sort((a, b) => (b.mtime - a.mtime) || comparePaths(a.name, b.name));
+  return { items: items.slice(0, RECENT_LIMIT), skipped, limit: RECENT_LIMIT };
+}
+
+/** The source's release label, or null when it cannot be read. */
+function releaseLabel() {
+  const v = sourceReleaseVersion({ config: CONFIG });
+  return v && v !== '0.0.0' ? v : null;
+}
+
 /**
  * `_web_server.Handler.STATE_ROUTES`, the ported half.
  *
  * A literal path to `api_X(state)`, exactly as the reference's table is — and the reason
- * it is a table on this side too is `tests/test_web_server.py`'s cross-check, which reads
- * the reference's table out of `rituals/_web_server.py` with `ast` and requires this one
- * plus `NOT_PORTED` to equal it. On the second instance of anything, the gate becomes a
- * table cross-checked against the source of truth.
+ * it is a table on this side too is `tests/unit/web_server.test.mjs`'s cross-check, which
+ * requires this table plus `PREFIX_ROUTES`, `PORTED_INLINE` and `NOT_PORTED` to equal
+ * `REF_GET` — a FROZEN LITERAL of what the reference daemon answered, since the source it
+ * was once read from with `ast` is deleted. On the second instance of anything, the gate
+ * becomes a table cross-checked against a declaration.
  */
 /**
  * `_web_server.do_GET`'s prefix routes, the ported ones — path in, response out.
  *
- * `pyUnquote` and not `decodeURIComponent`: the JS builtin throws a `URIError` on a `%`
+ * `percentDecode` and not `decodeURIComponent`: the JS builtin throws a `URIError` on a `%`
  * that is not an escape, which the shell would answer as a 500 where the reference answers
  * a 404 naming the literal text.
  */
@@ -925,13 +1025,13 @@ export const PREFIX_ROUTES = [
   ['/api/item/', (state, p) => {
     const parts = splitN(p, '/', 4);
     if (parts.length < 5 || !parts[4]) throw new NotFound(p);
-    return apiItem(state, parts[3], pyUnquote(parts[4]));
+    return apiItem(state, parts[3], percentDecode(parts[4]));
   }],
   // P6e. The reference's own `path[len("/api/activity/"):]`, unquoted — the sid keeps
   // whatever it carries and `api_activity_detail`'s safe-name scheme is what makes the
   // lookup safe, rather than a check out here.
   ['/api/activity/', (state, p) => apiActivityDetail(
-    state, pyUnquote(p.slice('/api/activity/'.length)))],
+    state, percentDecode(p.slice('/api/activity/'.length)))],
 ];
 
 /** `str.split(sep, maxsplit)` — at most `n` splits, the remainder kept whole. */
@@ -950,6 +1050,9 @@ function splitN(s, sep, n) {
 
 export const STATE_ROUTES = {
   '/api/overview': apiOverview,
+  // Beyond the reference — declared in `GET_BEYOND_REF`, which is what keeps the partition
+  // gate's set equality honest instead of forging `REF_GET`.
+  '/api/recent': apiRecent,
   '/api/themes': apiThemes,
   '/api/setup': apiSetup,
   '/api/doctor': apiDoctor,