geneseed 3.2.0 → 3.4.0

package/js/web/docs.mjs

@@ -7,11 +7,9 @@
  * the same file, so there is exactly one description of the CLI surface, not a second
  * transcription of it.
  *
- * 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 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.
+ * `tests/unit/web_server.test.mjs` holds `KINDS` against a written-out list of the five
+ * kinds this daemon dispatches on — same declaration-vs-dispatch shape as the route table,
+ * which is why it is a table here too and not five `if`s.
  *
  * 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
@@ -430,22 +428,6 @@ function about(state) {
   };
 }
 
-/**
- * EMPTY, AND KEPT DECLARED — the third partition in this codebase to reach that state,
- * after `NOT_PORTED_POST` and `NOT_PORTED_ACTIONS`.
- *
- * `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.
- *
- * 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();
-
 export function apiDocs(state, harnessName = null) {
   const hn = normHarness(harnessName, state);
   const groups = visibleGroups(hn).map((g) => ({
@@ -466,20 +448,16 @@ export function apiDocsPage(state, pageId, harnessName = null) {
   const hn = normHarness(harnessName, state);
   const render = KIND_ROUTES[page.kind];
   if (render !== undefined) return render(state, pageId, page, hn);
-  if (NOT_PORTED_KINDS.has(page.kind)) {
-    const e = new Error(`not ported yet: docs kind '${page.kind}'`);
-    e.notPorted = true;
-    throw e;
-  }
   throw new NotFound(pageId);
 }
 
 /**
- * The three kinds that cross, as a TABLE and not three `if`s.
+ * The five kinds, as a TABLE and not five `if`s.
  *
- * `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.
+ * `tests/unit/web_server.test.mjs` holds `Object.keys(KIND_ROUTES)` against a written-out
+ * list of the kinds `apiDocsPage` must dispatch 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) => {
@@ -514,4 +492,4 @@ const KIND_ROUTES = {
   }),
 };
 
-export const PORTED_KINDS = Object.keys(KIND_ROUTES);
+export const KINDS = Object.keys(KIND_ROUTES);

package/js/web/handler.mjs

@@ -19,10 +19,10 @@ import { apiDeployCmd, apiInstallCmd, apiPickFolder, apiRestore, buildOverride,
 import { NotFound, PREFIX_ROUTES, STATE_ROUTES } from './api.mjs';
 import { openUrl, requestRestart } from './daemon.mjs';
 import { apiDocs, apiDocsPage } from './docs.mjs';
-import { NOT_PORTED_ACTIONS, actionCommands } from './jobs.mjs';
-import { POST_ROUTES, notPorted, notPortedPost, readJsonBody } from './routes.mjs';
+import { actionCommands } from './jobs.mjs';
+import { POST_ROUTES, readJsonBody } from './routes.mjs';
 import { isFile } from '../lib/fs.mjs';
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 import { basename, dirname, extname, join, sep } from 'node:path';
 import { gzipSync } from 'node:zlib';
 
@@ -57,13 +57,17 @@ const CTYPES = {
 // ---- the request handler ---------------------------------------------------
 
 export function makeHandler(state, jm, token, dist, holder = null) {
+  // fp -> { mtime, data, gz }. Keyed by path but VALIDATED by mtime on every hit, so a
+  // rebuilt web/dist serves fresh bytes without `web restart` — the re-stat costs one
+  // syscall against the readFileSync + gzipSync it saves. `gz` is the gzipped body,
+  // computed once on the first gzip-accepting request instead of per request.
   const staticCache = new Map();
 
-  function sendBytes(res, body, ctype, code = 200, extra = null, acceptEncoding = '') {
+  function sendBytes(res, body, ctype, code = 200, extra = null, acceptEncoding = '', gzStore = null) {
     const headers = { ...(extra || {}) };
     if (body.length >= GZIP_MIN && GZIP_TYPES.some((t) => ctype.startsWith(t))
         && (acceptEncoding || '').includes('gzip')) {
-      body = gzipSync(body, { level: 6 });
+      body = gzStore ? (gzStore.gz ??= gzipSync(body, { level: 6 })) : gzipSync(body, { level: 6 });
       headers['Content-Encoding'] = 'gzip';
       headers.Vary = 'Accept-Encoding';
     }
@@ -91,21 +95,25 @@ export function makeHandler(state, jm, token, dist, holder = null) {
     if (!isFile(fp)) {
       return sendJson(res, { error: 'web/dist missing — run the UI build' }, 500, acceptEncoding);
     }
-    let data = staticCache.get(fp);
-    if (data === undefined) {
-      data = readFileSync(fp);
-      staticCache.set(fp, data);
+    const mtime = statSync(fp).mtimeMs;
+    let entry = staticCache.get(fp);
+    if (entry === undefined || entry.mtime !== mtime) {
+      entry = { mtime, data: readFileSync(fp), gz: null };
+      staticCache.set(fp, entry);
     }
+    let data = entry.data;
     let extra = null;
     if (basename(fp) === 'index.html') {
       const inject = Buffer.from(`<script>window.__GENESEED_TOKEN__="${token}";</script>`, 'utf-8');
       data = replaceOnce(data, Buffer.from('</head>'), Buffer.concat([inject, Buffer.from('</head>')]));
       extra = { 'Cache-Control': 'no-store' };
+      // The injected bytes differ from `entry.data`, so the gz cache must not serve them.
+      entry = null;
     } else if (path.includes('/assets/')) {
       extra = { 'Cache-Control': 'public, max-age=31536000, immutable' };
     }
     return sendBytes(res, data, CTYPES[extname(fp)] || 'application/octet-stream',
-      200, extra, acceptEncoding);
+      200, extra, acceptEncoding, entry);
   }
 
   function doGet(req, res, path, ae) {
@@ -120,14 +128,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
     }
     if (path.startsWith('/api/docs/page/')) {
       const pid = percentDecode(path.slice('/api/docs/page/'.length));
-      try {
-        return sendJson(res, apiDocsPage(state, pid, harnessParam(req.url)), 200, ae);
-      } catch (e) {
-        // An unimplemented doc kind says so explicitly (501), rather than falling through
-        // to the `NotFound` at the bottom of `apiDocsPage` and claiming the page is missing.
-        if (e && e.notPorted) return sendJson(res, { error: e.message }, 501, ae);
-        throw e;
-      }
+      return sendJson(res, apiDocsPage(state, pid, harnessParam(req.url)), 200, ae);
     }
     if (path === '/api/jobs') return sendJson(res, { jobs: jm.recent() }, 200, ae);
     if (path.startsWith('/api/jobs/')) {
@@ -137,9 +138,6 @@ export function makeHandler(state, jm, token, dist, holder = null) {
       return j ? sendJson(res, j, 200, ae)
         : sendJson(res, { error: 'no such job' }, 404, ae);
     }
-    if (notPorted(path)) {
-      return sendJson(res, { error: `not ported yet: ${path}` }, 501, ae);
-    }
     return serveStatic(res, path, ae);
   }
 
@@ -230,9 +228,6 @@ export function makeHandler(state, jm, token, dist, holder = null) {
     if (path.startsWith('/api/actions/')) {
       return doAction(res, path.slice(path.lastIndexOf('/') + 1), readJsonBody(body), ae);
     }
-    if (notPortedPost(path)) {
-      return sendJson(res, { error: `not ported yet: ${path}` }, 501, ae);
-    }
     return sendJson(res, { error: 'not found' }, 404, ae);
   }
 
@@ -253,9 +248,7 @@ export function makeHandler(state, jm, token, dist, holder = null) {
    * it succeeded: a failed update changed nothing worth reloading and bouncing would disconnect
    * the PWA for no reason.
    *
-   * THEN the unported rows, and only then the table. Order matters: `link`/`unlink` are REAL
-   * actions whose verb has not crossed, and letting them fall through to `actionCommands` would
-   * answer `{"error": "unknown action link"}` — the same thing a typo gets.
+   * THEN the table, which answers a 404 for any action it does not name.
    */
   function doAction(res, action, body, ae) {
     if (action === 'restore') {
@@ -284,9 +277,6 @@ export function makeHandler(state, jm, token, dist, holder = null) {
       if (jid === null) return sendJson(res, { error: 'busy' }, 409, ae);
       return sendJson(res, { job_id: jid }, 202, ae);
     }
-    if (NOT_PORTED_ACTIONS.has(action)) {
-      return sendJson(res, { error: `not ported yet: /api/actions/${action}` }, 501, ae);
-    }
     // Build can be re-themed/re-targeted from the UI picker; the other actions self-resolve
     // the deployed theme downstream. Footprint, posture and mode always follow the current
     // install, so a re-theme preserves lean/full, the register and the operating mode.

package/js/web/jobs.mjs

@@ -44,14 +44,10 @@
  * `taskkill /T` is a machine primitive here, not this program.
  *
  * ---------------------------------------------------------------------------------------
- * THE PARTITION — all eight action rows cross, and the declaration outlives them.
- *
- * `doctor`, `build`, `build-all`, `export`, `uninstall`, `update`, `link` and `unlink` each
- * name a verb `bin/geneseed-cli.mjs` runs.
- *
- * `NOT_PORTED_ACTIONS` IS EMPTY AND STILL DECLARED, which is the point of it: a ninth action
- * added later cannot quietly answer "unknown action", because `tests/unit/web_jobs.test.mjs`
- * holds the two sets against `actionCommands`' own keys.
+ * THE ACTION SURFACE — `doctor`, `build`, `build-all`, `export`, `uninstall`, `update`,
+ * `link` and `unlink` each name a verb `bin/geneseed-cli.mjs` runs, plus the three
+ * `INLINE_ACTIONS` the dispatcher answers without the table. `tests/unit/web_jobs.test.mjs`
+ * holds the union against a written-out list, so a ninth action cannot appear unchecked.
  *
  * ---------------------------------------------------------------------------------------
  * THREE DETAILS OF `_run`, EACH A COMMENT EXPLAINING A BUG IT ALREADY FIXED.
@@ -381,27 +377,10 @@ const NODE = () => process.execPath;
 const CLI = () => path.join(ROOT, 'bin', 'geneseed-cli.mjs');
 const GEN = () => path.join(ROOT, 'bin', 'build-driver.mjs');
 
-/**
- * The rows whose VERB has not crossed. EMPTY, AND STILL DECLARED.
- *
- * WHY AN EMPTY SET RATHER THAN A DELETED ONE. This set is cross-checked against
- * `actionCommands`' own keys, and an empty set is the strongest form that check ever takes:
- * it asserts that EVERY action this daemon knows how to dispatch on is answered by the
- * runner. Deleting the declaration would delete that assertion, and the next unported
- * action would come back as a silent 404 — the thing the 501 exists to prevent.
- *
- * A 501 AND NOT THE 404 THE TABLE WOULD PRODUCE. `actionCommands` returns `null` for an
- * unknown action, mapped to `{"error": "unknown action <x>"}` at 404 — so a
- * real-but-unported action falling through would answer the same thing a typo gets. With
- * this set empty the 501 branch is UNREACHABLE by construction: every real action answers
- * 202 and only an invented one answers 404.
- */
-export const NOT_PORTED_ACTIONS = new Set();
-
 /**
  * The three actions the dispatcher answers INLINE, without consulting the table above:
  * `restore` is synchronous and returns a result rather than a job id, and `install`/`deploy`
- * resolve their argv from the request body first. Declared so the partition covers every
+ * resolve their argv from the request body first. Declared so the surface check covers every
  * action the dispatcher answers, not only the table's keys.
  */
 export const INLINE_ACTIONS = ['restore', 'install', 'deploy'];

package/js/web/routes.mjs

@@ -1,10 +1,15 @@
 /**
  * WHAT THE WEB API ANSWERS — as a declaration, separate from the dispatcher that honours it.
  *
- * Eight exported sets and one map. They are not documentation: `tests/unit/web_server.mjs` reads
- * them as a TWO-SIDED PARTITION and probes the real handler against them, because a declaration is
- * not a dispatcher — a route can be declared in one and missing from the other, and nothing but
- * a probe notices.
+ * Two tables and two inline lists. They are not documentation: `tests/unit/web_server.test.mjs`
+ * holds their union against a surface list written out in the test, and probes the real handler,
+ * because a declaration is not a dispatcher — a route can be declared here and missing from the
+ * dispatch, and nothing but a probe notices.
+ *
+ * This file used to also carry the Python→Node port's NOT_PORTED / DECLINED partition — five
+ * sets, all empty once the port finished. They were deleted when the port bookkeeping retired
+ * (see git history); an unmatched GET falls through to `serveStatic`'s SPA fallback and an
+ * unmatched POST answers 404, which is what the empty sets already produced.
  *
  * Split out of `server.mjs` because it is the half a reader consults to answer "does the console
  * expose X?", which has nothing to do with sockets, daemons or gzip.
@@ -13,43 +18,6 @@ import { formatValue, isTruthy, parseJson } from '../lib/json.mjs';
 import { apiExcludesMutate, apiInstallToggle, apiMcpToggle, apiMemoryDelete, apiProfileSave, apiRulesMutate, apiRulesPromote, apiSelectView } from './actions.mjs';
 import { apiActivityToggle } from './activity.mjs';
 
-/**
- * The API paths this daemon does not answer — currently empty, but the DECLARATION STAYS:
- * without it, an unmatched GET falls through to `serveStatic`'s SPA fallback (200 +
- * index.html) instead of a clear failure. Half of a partition test, so an empty set still
- * asserts there is nothing left to declare.
- *
- * Declared separately from the POST sets below because five paths — `/api/mcp`,
- * `/api/excludes`, `/api/rules`, `/api/profile`, `/api/activity` — answer both verbs with
- * different bodies, so one set keyed on path alone could not track GET and POST status
- * independently.
- */
-export const NOT_PORTED = new Set([]);
-export const NOT_PORTED_PREFIXES = [];
-
-/**
- * The POSTs that have not crossed yet — currently empty, for the same reason the GET pair
- * above stays declared: deleting it would let an unrouted POST fall through to a
- * plausible-looking 404 instead of the 501 this set exists to produce.
- */
-export const NOT_PORTED_POST = new Set([]);
-export const NOT_PORTED_POST_PREFIXES = [];
-
-/**
- * The POSTs that will NEVER cross, which is a different claim from the set above — currently
- * EMPTY. `/api/pick-folder` was its one member (an OS-native folder chooser, "declined rather
- * than deferred" because there was no Node twin that was not a new GUI dependency) until the
- * user overrode that decision 2026-08-27; it now dispatches inline from `js/web/handler.mjs`'s
- * `doPost` — see `apiPickFolder` in `js/web/actions.mjs`.
- *
- * KEPT DECLARED AND EMPTY FOR THE SAME REASON `NOT_PORTED_POST` STAYS DECLARED WHEN IT EMPTIES
- * (see that set, just above): an empty set here is the partition asserting there is nothing
- * PERMANENTLY refused, not an omission a later reader has to double-check. `notPortedPost`
- * below still consults it, so a genuinely permanent decline — if one is ever added again —
- * needs no dispatcher change, only a member here.
- */
-export const DECLINED_POST = new Set([]);
-
 /**
  * The POSTs this daemon answers — and this table IS the dispatch, not a declaration beside
  * it: `doPost` looks routes up HERE, so a hand-kept declaration and the running dispatcher
@@ -79,8 +47,6 @@ export const POST_ROUTES = new Map([
   ['/api/profile', [apiProfileSave, true]],
 ]);
 
-export const PORTED_POST = [...POST_ROUTES.keys()];
-
 /**
  * The 409 column, exported so a test can assert it directly. Giving `/api/activity` the 409
  * treatment is the invisible mutation: nothing in normal use can force the `ok: false` arm
@@ -92,59 +58,27 @@ export const POST_ROUTES_CONVENTION = Object.fromEntries(
 );
 
 /**
- * The GET paths answered OUTSIDE the two tables, declared so the partition cross-check can
+ * The GET paths answered OUTSIDE the two tables, declared so the surface cross-check can
  * see them: `/api/ping` is the shell's own, and the two Docs routes take the `?harness=`
  * query param, which a `(state)` table entry has no way to receive. A probe checks all
  * three against the running handler too, not merely against this list.
  */
-export const PORTED_INLINE = ['/api/ping', '/api/docs', '/api/docs/page/',
+export const GET_INLINE = ['/api/ping', '/api/docs', '/api/docs/page/',
   '/api/jobs', '/api/jobs/'];
 
 /**
  * The POSTs that answer outside `POST_ROUTES`, because they don't fit its shape:
  * `/api/jobs/<id>/cancel` answers 200 or 404 on a lookup, not an `ok` field, and
- * `/api/actions/<x>` spans six statuses (202, 409, 404, 501, 400, 200) over one prefix, none
+ * `/api/actions/<x>` spans five statuses (202, 409, 404, 400, 200) over one prefix, none
  * read off `ok`. Bending the 409 column to fit either would make it lie about the routes it
- * already describes correctly.
- *
- * `/api/pick-folder` joined 2026-08-27 for a THIRD reason: `POST_ROUTES`'s `fn(state, body)
- * -> object` shape answers the instant `fn` returns, and this endpoint cannot — it spawns a
- * native folder dialog and answers only once a human (or a timeout) closes it. See
+ * already describes correctly. `/api/reveal` answers 200/404 on an allowlist lookup, and
+ * `/api/pick-folder` cannot fit the table's `fn(state, body) -> object` shape at all: it
+ * spawns a native folder dialog and answers only once a human (or a timeout) closes it. See
  * `apiPickFolder` in `js/web/actions.mjs`, dispatched inline from `js/web/handler.mjs`'s
- * `doPost` the same way the other three rows here are.
- */
-export const PORTED_POST_INLINE = ['/api/shutdown', '/api/restart', '/api/jobs/',
-  '/api/actions/', '/api/pick-folder'];
-
-/**
- * POST routes added after the ported reference surface was frozen. Kept separate from
- * `NOT_PORTED_POST` so that frozen record stays honest, while a new route is still
- * enumerated rather than appearing unchecked. Belongs here only once dispatched below — a
- * probe, not just this declaration, is what keeps that true.
+ * `doPost` the same way the other rows here are.
  */
-export const POST_BEYOND_REF = new Set([
-  '/api/reveal',
-]);
-
-/**
- * GET routes added after the ported reference surface was frozen — the same reason
- * `POST_BEYOND_REF` above exists, one verb over. `/api/recent` is a genuine gap: no catalog
- * row carries a date and a browser cannot stat the `source` path it is handed, so "what
- * changed lately" needed a server that looks. See `apiRecent` in `api.mjs` for what it will
- * and will not date.
- */
-export const GET_BEYOND_REF = new Set([
-  '/api/recent',
-]);
-
-export function notPorted(path) {
-  return NOT_PORTED.has(path) || NOT_PORTED_PREFIXES.some((p) => path.startsWith(p));
-}
-
-export function notPortedPost(path) {
-  return NOT_PORTED_POST.has(path) || DECLINED_POST.has(path)
-    || NOT_PORTED_POST_PREFIXES.some((p) => path.startsWith(p));
-}
+export const POST_INLINE = ['/api/shutdown', '/api/restart', '/api/jobs/',
+  '/api/actions/', '/api/pick-folder', '/api/reveal'];
 
 /**
  * The drained request body as a plain object, `{}` for ANYTHING else — never a raise, so a

package/js/web/server.mjs

@@ -18,9 +18,9 @@
  * WHAT WAS STILL NOT HERE, SINCE P6i UNTIL 2026-08-27: `/api/pick-folder`, DECLINED rather
  * than deferred — an OS-native folder chooser had no Node twin that was not a new GUI
  * dependency. The user overrode that decline; the endpoint now dispatches inline from
- * `js/web/handler.mjs`'s `doPost` (see `apiPickFolder` in `js/web/actions.mjs`). Both
- * `NOT_PORTED_POST` and `DECLINED_POST` are empty now and stay declared regardless, because an
- * empty half of a partition is the partition asserting there is nothing left, not an omission.
+ * `js/web/handler.mjs`'s `doPost` (see `apiPickFolder` in `js/web/actions.mjs`). With it, the
+ * port's NOT_PORTED / DECLINED partition emptied for good and was retired — the declared
+ * surface now lives in `js/web/routes.mjs` and `tests/unit/web_server.test.mjs`.
  */
 import { GLOBAL_MANIFEST, resolvePath } from '../hosts/hosts.mjs';
 import { printOut } from '../lib/fs.mjs';

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",