geneseed 3.1.3 → 3.2.0

package/js/web/activity.mjs

@@ -7,78 +7,64 @@
  * directory self-cleans), and returns what is left. Writer and reader share only that
  * directory: no RPC, crash-isolated, and cross-tool by construction.
  *
- * BOTH VERBS CROSS. `/api/activity` answers a GET through `apiActivity` and a POST through
- * `apiActivityToggle` at the bottom of this file; `NOT_PORTED_POST` is empty and still
- * declared. It is also the one POST route whose result is sent at 200 whatever `ok` says,
- * which is why `POST_ROUTES` in `js/web/routes.mjs` carries a 409 COLUMN rather than a rule —
- * and giving this row the 409 treatment is mutation M22.
+ * `/api/activity` answers a GET through `apiActivity` and a POST through `apiActivityToggle`
+ * at the bottom of this file. It is the one POST route whose result is sent at 200 whatever
+ * `ok` says, which is why `POST_ROUTES` in `js/web/routes.mjs` carries a 409 COLUMN rather
+ * than a rule — and giving this row the 409 treatment is mutation M22.
  *
- * THE PLAN GUESSED `tasklist` AND THE SOURCE SAYS OTHERWISE. `_win_pid_alive` shells
- * nothing: it goes through `ctypes` to `OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION)` and
- * `GetExitCodeProcess`. So there is no sixth `_ALLOWED_SPAWNS` row to argue — not because
- * the Node twin avoids a spawn, but because the REFERENCE never had one. `process.kill(pid,
- * 0)` is the twin here; it is a core `process` API and not `child_process`, so the ban that
- * P4a's source check enforces is untouched. libuv's `uv_kill` opens the process for query
- * and answers `ESRCH` when the pid is free and `EPERM` when it cannot tell, which is
- * exactly the reference's "no such process" / "err toward alive" pair.
+ * `process.kill(pid, 0)` PROBES LIVENESS WITHOUT A SPAWN — it is a core `process` API, not
+ * `child_process`, so it stays clear of the spawn ban. libuv's `uv_kill` opens the process
+ * for query and answers `ESRCH` when the pid is free and `EPERM` when it cannot tell —
+ * "no such process" vs "err toward alive".
  *
- * THE DIVERGENCE THAT LEAVES, DECLARED RATHER THAN HIDDEN. The reference also reads the
- * exit code and calls a process that has EXITED but whose handle is still held dead;
- * `process.kill` reports it alive, and the staleness backstop is what prunes it thirty
- * minutes later. Reproducing the exit-code read would mean a native binding, which this
- * port will not add for a best-effort liveness probe whose own docstring says any
- * inconclusive answer errs toward alive.
+ * `process.kill` alone cannot tell a truly-dead pid from one that EXITED but whose handle is
+ * still held: it reports the latter alive too. The staleness backstop (below) is what prunes
+ * it, thirty minutes later — reproducing an exit-code read would need a native binding, not
+ * worth it for a best-effort probe that already errs toward "alive" on any inconclusive
+ * answer.
  *
- * `parseJson` AND NOT `JSON.parse`, WHICH IS NOT A STYLE CHOICE. These files are written by
- * a third party and carry `cost` — a float. Python's `json.loads` types `1.0` a float and
- * `json.dumps` writes it back `1.0`; `JSON.parse` gives a bare `1` that `bareInts` then
- * renders `1`. `parseJson`'s wrapper is the only thing that survives the round trip, and
- * `s-live`'s `"cost": 1.0` is the cell that says so. Its companion is `isTruthy`: an
- * `entry.get("cost") or 0` over a wrapper object is TRUE for a wrapped zero, where Python's
- * `0.0 or 0` is the int `0` — so `s-older`'s `"cost": 0.0` must come back `0` and not `0.0`.
+ * `parseJson`, NOT `JSON.parse` — NOT a style choice. These files are written by a third
+ * party and carry `cost` as a float. `JSON.parse` collapses `1.0` to the bare integer `1`,
+ * which `bareInts` then renders back as `1`, losing the distinction the source file made;
+ * `parseJson`'s wrapper is what survives the round trip.
+ *
+ * Its companion is `isTruthy`: a naive `entry.cost || 0` fallback is TRUE for a wrapped zero
+ * (the wrapper is an object, never falsy on its own), which would echo back the wrapper's
+ * `0.0` instead of collapsing to the fallback `0`. `isTruthy` is what makes a wrapped zero
+ * read as falsy, so a `"cost": 0.0` entry correctly comes back `0`.
  */
-import { mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { mkdirSync, readdirSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
-import { readText, writeText } from '../lib/fs.mjs';
+import { readText, writeText, isDir, isFile } from '../lib/fs.mjs';
 import { parseJson, isTruthy } from '../lib/json.mjs';
 import { normcase } from '../lib/paths.mjs';
 import { parseIntStrict, stripWhitespace } from '../lib/text.mjs';
-import { NotFound } from './api.mjs';
+import { NotFound, stemOf } from './api.mjs';
 
 /**
- * `_web_activity.ACTIVITY_STALE_SECONDS` — a session whose writer is gone, or that has not
- * been touched in this long, is pruned. pid-liveness is the real signal; the staleness
- * backstop covers a reused pid and a platform where the probe cannot tell. Generous on
- * purpose: streaming bumps `updated_at` constantly, so only a genuinely abandoned
- * (process-still-alive) session ages out.
+ * A session whose writer is gone, or that has not been touched in this long, is pruned.
+ * pid-liveness is the real signal; the staleness backstop covers a reused pid and a
+ * platform where the probe cannot tell. Generous on purpose: streaming bumps `updated_at`
+ * constantly, so only a genuinely abandoned (process-still-alive) session ages out.
  */
 export const ACTIVITY_STALE_SECONDS = 1800;
 
-const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
-const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
-
-/** `time.time()` — unix seconds as a float. */
 const nowSeconds = () => Date.now() / 1000;
 
 /**
- * `_activity_dir` — `<target>/activity`. `state.target` is ALREADY the OpenCode config dir,
- * so this must not append `opencode/` again; that double-join is the classic seam bug.
+ * `<target>/activity`. `state.target` is ALREADY the OpenCode config dir, so this must not
+ * append `opencode/` again; that double-join is the classic seam bug.
  */
 const activityDir = (state) => path.join(state.target, 'activity');
 
-/** `_activity_flag` — the runtime on/off flag, the same path the plugin resolves. */
+/** The runtime on/off flag — the same path the plugin resolves. */
 const activityFlag = (state) => path.join(state.target, '.geneseed-activity');
 
 /**
- * `_activity_enabled` — on unless the flag file explicitly says off. An absent (or
- * unreadable) file is the default every user who has never toggled is in.
- *
- * The one input this cannot mirror is an undecodable flag file: Python's
- * `read_text(encoding="utf-8")` raises a `UnicodeDecodeError`, which is a `ValueError` and
- * not caught, where Node substitutes U+FFFD and reads on. No cell seeds one — it would take
- * a binary file where a four-letter word belongs — and the reference's answer there is a
- * 500, which is not a behaviour worth reproducing.
+ * On unless the flag file explicitly says off. An absent (or unreadable) file is the
+ * default every user who has never toggled is in. An undecodable flag file is not treated
+ * specially: Node substitutes U+FFFD and reads on rather than raising.
  */
 export function activityEnabled(state) {
   let raw;
@@ -91,14 +77,14 @@ export function activityEnabled(state) {
 }
 
 /**
- * `int(value)` as `_pid_alive` calls it — `TypeError` and `ValueError` both mean "not a
- * pid", so both come back null here.
+ * Coerces a raw pid value to an integer, or `null` for anything unusable.
  *
- * The value came out of `parseJson`, so a JSON number arrives inside a wrapper this module
- * cannot import by name. It is recognised by the only thing the wrapper promises, a numeric
- * `valueOf` — a plain object's returns itself and an array is excluded outright, which is
- * what `int({})` and `int([])` raising looks like from here. `int(1.9)` truncates and
- * `int(True)` is 1, both of which a hand-edited snapshot can produce.
+ * The value came out of `parseJson`, so a JSON number may arrive wrapped in `JsonNumber`,
+ * which this module cannot import by name (only `parseJson`/`isTruthy`/etc are exported). It
+ * is recognised by the only thing the wrapper promises: a numeric `valueOf`. A plain
+ * object's `valueOf` returns itself (rejected by the `typeof n !== 'number'` check below)
+ * and an array is excluded outright. Also handles a decimal string, a boolean (`true` → 1),
+ * and a float (truncated) — whatever a hand-edited snapshot can produce.
  */
 function toIntOr(raw) {
   if (raw === true) return 1;
@@ -110,7 +96,7 @@ function toIntOr(raw) {
   return Math.trunc(n);
 }
 
-/** `_pid_alive` — best-effort liveness for the writer process. See this file's header. */
+/** Best-effort liveness for the writer process. See this file's header. */
 export function pidAlive(raw) {
   const pid = toIntOr(raw);
   if (pid === null || pid <= 0) return false;
@@ -118,17 +104,16 @@ export function pidAlive(raw) {
     process.kill(pid, 0);
     return true;
   } catch (e) {
-    // `ProcessLookupError` → dead. Anything else (`EPERM`, and whatever a locked-down host
-    // answers) → alive, and the staleness backstop decides.
+    // ESRCH → dead. Anything else (`EPERM`, and whatever a locked-down host answers) →
+    // alive, and the staleness backstop decides.
     return !(e && e.code === 'ESRCH');
   }
 }
 
 /**
- * `_normalize_entry` — one session snapshot into the stable shape the UI consumes. v1
- * writers omit the enrichment keys, so those default to null/0 and the UI hides what is
- * absent. The KEY ORDER is the reference's dict-literal order, which is what the byte
- * comparison over every response gates.
+ * One session snapshot normalised into the stable shape the UI consumes. v1 writers omit
+ * the enrichment keys, so those default to null/0 and the UI hides what is absent. The KEY
+ * ORDER here is deliberate and stable — do not reshuffle it.
  */
 function normalizeEntry(entry, stem) {
   const g = (k) => (Object.hasOwn(entry, k) ? entry[k] : null);
@@ -152,7 +137,7 @@ function normalizeEntry(entry, stem) {
   };
 }
 
-/** `_read_entry` — null on a missing, garbage or non-dict file. Never throws. */
+/** `null` on a missing, garbage or non-dict file. Never throws. */
 function readEntry(p) {
   let entry;
   try {
@@ -163,7 +148,7 @@ function readEntry(p) {
   return (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) ? entry : null;
 }
 
-/** `_is_live` — the writer's pid is alive AND the snapshot is not stale. */
+/** The writer's pid is alive AND the snapshot is not stale. */
 function isLive(entry, now) {
   const updated = isTruthy(Object.hasOwn(entry, 'updated_at') ? entry.updated_at : null)
     ? entry.updated_at : 0;
@@ -171,13 +156,10 @@ function isLive(entry, now) {
     Object.hasOwn(entry, 'pid') ? entry.pid : null);
 }
 
-/** `Path.stem` — the name without its LAST suffix, so `s-live.detail.json` keeps the dot. */
-const stemOf = (name) => name.slice(0, name.length - path.extname(name).length);
-
 /**
- * `_activity_entries` — every live session, dead and stale ones pruned AND their files
- * removed. Never throws: a missing dir is `[]`, a garbage file is skipped (and kept —
- * only a snapshot that PARSED and failed the liveness test is unlinked), newest first.
+ * Every live session, dead and stale ones pruned AND their files removed. Never throws: a
+ * missing dir is `[]`, a garbage file is skipped (and kept — only a snapshot that PARSED and
+ * failed the liveness test is unlinked), newest first.
  */
 export function activityEntries(state) {
   const d = activityDir(state);
@@ -190,8 +172,9 @@ export function activityEntries(state) {
   } catch {
     return [];
   }
-  // `Path.glob("*.json")` is case-INSENSITIVE on Windows, as pathlib's is; `str.endswith`
-  // on the detail suffix is not, on either platform. Two different rules, deliberately.
+  // Case-INSENSITIVE for the `.json` suffix (matches Windows filesystem behaviour); the
+  // `.detail.json` check below is case-SENSITIVE on both platforms. Two different rules,
+  // deliberately.
   for (const name of names.filter((n) => normcase(n).endsWith('.json')).sort()) {
     if (name.endsWith('.detail.json')) continue;
     const p = path.join(d, name);
@@ -201,34 +184,34 @@ export function activityEntries(state) {
       try {
         unlinkSync(p);                                          // crashed / abandoned writer
         unlinkSync(path.join(d, `${stemOf(name)}.detail.json`));   // its detail file too
-      } catch { /* `contextlib.suppress(OSError)` wraps BOTH unlinks, as this does */ }
+      } catch { /* both unlinks are best-effort; a lingering file next scan is harmless */ }
       continue;
     }
     out.push(normalizeEntry(entry, stemOf(name)));
   }
-  // Stable in both languages, and the tie is the point: `sorted(reverse=True)` preserves the
-  // original order of equal keys, and so does a `b - a` comparator over ES2019's stable sort.
+  // STABLE sort matters when `updated_at` ties: a `b - a` comparator over ES2019's
+  // guaranteed-stable `Array.sort` preserves the original (directory-listing) order for
+  // equal keys.
   out.sort((a, b) => Number(b.updated_at) - Number(a.updated_at));
   return out;
 }
 
-/** `_web_activity.api_activity` (GET). */
 export function apiActivity(state) {
   const enabled = activityEnabled(state);
   return { enabled, activity: enabled ? activityEntries(state) : [] };
 }
 
 /**
- * `_web_activity.api_activity_detail` — one session's snapshot plus its step timeline and
- * its UNCAPPED files/todos. 404 if the session is absent or has aged out; a missing or
- * garbage detail file degrades to an empty timeline rather than a 500.
+ * One session's snapshot plus its step timeline and its UNCAPPED files/todos. 404 if the
+ * session is absent or has aged out; a missing or garbage detail file degrades to an empty
+ * timeline rather than a 500.
  */
 export function apiActivityDetail(state, sid) {
   const d = activityDir(state);
   // Resolve by the writer's safe-name scheme, which is also what keeps the read inside the
   // directory: every separator, `..` and drive colon becomes `_`, so there is no join to
-  // steer. The `u` flag makes an astral character ONE replacement, as Python's code-point
-  // `re.sub` does, rather than one per surrogate.
+  // steer. The `u` flag makes an astral character ONE replacement rather than one per
+  // surrogate half.
   const stem = sid.replace(/[^A-Za-z0-9_.-]/gu, '_');
   const snap = path.join(d, `${stem}.json`);
   const entry = isFile(snap) ? readEntry(snap) : null;
@@ -244,8 +227,6 @@ export function apiActivityDetail(state, sid) {
   }
   const fg = (k) => (Object.hasOwn(full, k) ? full[k] : null);
   // The detail file carries the uncapped lists; fall back to the snapshot's capped ones.
-  // Assigning over an existing key keeps its POSITION in both languages, which is what lets
-  // the response stay byte-comparable.
   session.files = isTruthy(fg('files')) ? fg('files') : session.files;
   session.todos = isTruthy(fg('todos')) ? fg('todos') : session.todos;
   // The compact transcript: an ordered list of {role, text, t} turns. Empty falls back to
@@ -260,16 +241,17 @@ export function apiActivityDetail(state, sid) {
 }
 
 /**
- * `_web_activity.api_activity_toggle` — flip the runtime on/off flag.
+ * Flip the runtime on/off flag.
  *
  * The OpenCode plugin reads this file on every event, so the change takes effect without
  * restarting anything; writing `off` also makes the plugin clear its snapshots on its next
  * event, while the reader gates the surface immediately.
  *
- * `bool(body.get("enabled", True))` DEFAULTS TO ON — an empty body enables, which is the
- * arm a port spelled `body.enabled === true` inverts. And this is the one POST in P6f whose
- * result is sent at 200 whatever `ok` says: the 409 convention is per-route in the
- * reference, not a rule about the shape of the body.
+ * DEFAULTS TO ON: an empty or missing `enabled` field in the body enables. Do not read this
+ * as `body.enabled === true` — that would flip an absent field to "disable" instead.
+ *
+ * This is the one POST route whose result is sent at 200 whatever `ok` says — see this
+ * file's header, and `POST_ROUTES_CONVENTION` in `js/web/routes.mjs`.
  */
 export function apiActivityToggle(state, body) {
   const raw = (body && Object.hasOwn(body, 'enabled')) ? body.enabled : true;