geneseed 3.12.0 → 3.14.0

package/js/loop/cli.mjs

@@ -5,7 +5,9 @@
  *
  * NO SPAWN. The CLI's closure may not start processes, so git is the model's job: it pipes
  * `git diff --cached --numstat` into `score --diff` and `git status --porcelain` into `record`.
- * stdin is read only when it is not a TTY — a hand-run `geneseed loop record` must not hang.
+ * stdin is read only when it is not a TTY — a hand-run `geneseed loop record` must not hang —
+ * and a TTY reads as `null`, "no porcelain given", never as `''`: an empty pipe is a CLEAN
+ * tree, and a clean tree is exactly the snapshot a read brick's check must compare against.
  *
  * NO `--file`. `state.mjs`'s `LOOP_FILE` constant is the ROOT-RELATIVE path the engine filters
  * out of every diff and porcelain check, so LOOP.md has to live at the git root of the worktree
@@ -22,11 +24,12 @@ import { parseNumstat, DEFAULT_PRESET } from './score.mjs';
 import { gitRootOf, gitDirOf, currentBranch } from '../hosts/gitref.mjs';
 import {
   initState, nextStep, scoreDeclared, scoreDiff, recordOutcome, decideAwaiting,
-  renderLoopFile, parseLoopFile, LOOP_FILE,
+  writeLoopFile, parseLoopFile, LOOP_FILE,
 } from './state.mjs';
+import { recordLoop } from './registry.mjs';
 
 const emit = (obj) => { printOut(`${JSON.stringify(obj)}\n`); return obj.error || obj.ok === false ? 1 : 0; };
-const stdin = () => (process.stdin.isTTY ? '' : readFileSync(0, 'utf8'));
+const stdin = () => (process.stdin.isTTY ? null : readFileSync(0, 'utf8'));
 const list = (s) => (s ? String(s).split(',').map((x) => x.trim()).filter(Boolean) : null);
 
 function requireRoot() {
@@ -57,14 +60,17 @@ function writeCommitMessage(root, gitdir, result) {
   return { ...result, message_file: file.replaceAll('\\', '/') };
 }
 
-function withState(fn) {
+/** `write: false` for a read-only action (`next`): rewriting LOOP.md there would change
+ * nothing, and would race the Active tab's preset picker (`registry.mjs`'s `setLoopPreset`) —
+ * a preset it saved between this read and the rewrite would be silently undone. */
+function withState(fn, { write = true } = {}) {
   const root = requireRoot();
   const file = path.join(root, LOOP_FILE);
   if (!isFile(file)) throw new Error(`${file} does not exist — run \`geneseed loop init\` first`);
   const state = parseLoopFile(readText(file));
   const { bricks } = loadCatalog({ projectRoot: root });
   const result = fn(state, bricks);
-  writeText(file, renderLoopFile(state));
+  if (write) writeLoopFile(file, state);
   return result;
 }
 
@@ -78,26 +84,30 @@ function resolveGraph(spec, catalog) {
 
 const ACTIONS = {
   check(args) {
+    // The project level of the catalogue is `<git root>/.geneseed/`, as for `init` and `next`,
+    // so a check run from a subdirectory sees the same bricks and templates they will.
+    const root = gitRootOf(process.cwd()) ?? process.cwd();
     if (args.brick) {
       const { problems } = parseBrick(readText(path.resolve(args.brick)), 'checked');
       return { ok: !problems.length, problems };
     }
     if (args.graph) {
-      const catalog = loadCatalog({ projectRoot: process.cwd() });
+      const catalog = loadCatalog({ projectRoot: root });
       const problems = checkGraph(resolveGraph(args.graph, catalog), catalog.bricks);
       return { ok: !problems.length, problems };
     }
     // The bare check doubles as the catalogue LISTING the loop skill composes a free graph
     // from — frontmatter only: a brick's body reaches the model through `next`, for the node
     // the engine chose, never as a menu.
-    const problems = catalogProblems({ projectRoot: process.cwd() });
-    const { bricks, templates, overridden } = loadCatalog({ projectRoot: process.cwd() });
+    const catalog = loadCatalog({ projectRoot: root });
+    const problems = catalogProblems({ projectRoot: root }, catalog);
+    const { bricks, templates, overridden } = catalog;
     const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
     return {
       ok: !problems.length, problems,
       templates: [...templates.keys()].sort(byName),
       bricks: [...bricks.values()].sort((a, b) => byName(a.name, b.name))
-        .map(({ body, available, reason, ...b }) => ({ ...b, available, ...(reason ? { reason } : {}) })),
+        .map(({ body, reason, ...b }) => ({ ...b, ...(reason ? { reason } : {}) })),
       overridden,
     };
   },
@@ -110,18 +120,24 @@ const ACTIONS = {
     const graph = resolveGraph(args.graph, catalog);
     const problems = checkGraph(graph, catalog.bricks);
     if (problems.length) return { error: 'the graph does not pass loop check', problems };
-    const state = initState({ title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET });
-    writeText(file, renderLoopFile(state));
+    const state = initState({
+      title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET,
+      contracts: list(args.contracts) ?? [],
+    });
+    writeLoopFile(file, state);
+    // Best-effort: the registry is how the Active tab discovers this loop, but a registry
+    // hiccup must never fail the init the loop itself just succeeded at.
+    recordLoop({ root, branch: currentBranch(root), title: args.title });
     return { file, graph: graph.name, preset: state.preset, status: state.status };
   },
-  next: () => withState((s, b) => nextStep(s, b)),
+  next: () => withState((s, b) => nextStep(s, b), { write: false }),
   score(args) {
     if (args.diff) {
       // X6: resolve (and validate) the gitdir BEFORE withState runs the state change, so a
       // malformed `.git` file errors without advancing the loop.
       const root = requireRoot();
       const gitdir = gitDirOf(root);
-      return writeCommitMessage(root, gitdir, withState((s) => scoreDiff(s, parseNumstat(stdin()))));
+      return writeCommitMessage(root, gitdir, withState((s) => scoreDiff(s, parseNumstat(stdin() ?? ''))));
     }
     if (!args.declared) throw new Error('score needs --declared or --diff');
     return withState((s) => scoreDeclared(s, {
@@ -130,9 +146,29 @@ const ACTIONS = {
   },
   record(args) {
     if (!args.outcome) throw new Error('record needs --outcome');
-    const card = args.card ? JSON.parse(args.card) : null;
-    const raw = stdin();
-    return withState((s, b) => recordOutcome(s, b, args.outcome, { card, porcelain: raw ? raw.replace(/\r\n/g, '\n').trimEnd() : null }));
+    if (args.note && args.noteFile) throw new Error('record takes --note or --note-file, not both');
+    let note = args.note ?? '';
+    if (args.noteFile) {
+      // A note too long for a shell argument, or one that mentions `git … commit`/`push` (and
+      // would otherwise sit inside the command line GIT_GATE_RE matches whole), goes through a
+      // file instead — never through the shell at all. CRLF-folded and trimmed the same way the
+      // porcelain stdin below is, so a Windows-authored file round-trips identically.
+      let raw;
+      try { raw = readText(path.resolve(args.noteFile)); } catch (e) {
+        throw new Error(`cannot read --note-file ${args.noteFile}: ${e.message}`, { cause: e });
+      }
+      note = raw.replace(/\r\n/g, '\n').trimEnd();
+    }
+    let card = null;
+    if (args.card) {
+      try { card = JSON.parse(args.card); } catch (e) {
+        throw new Error(`--card is not valid JSON: ${e.message}`, { cause: e });
+      }
+    }
+    const porcelain = stdin();
+    return withState((s, b) => recordOutcome(s, b, args.outcome, {
+      card, porcelain: porcelain === null ? null : porcelain.replace(/\r\n/g, '\n').trimEnd(), note,
+    }));
   },
   decide(args) {
     // X6: same ordering as `score --diff` above.

package/js/loop/graph.mjs

@@ -21,8 +21,10 @@
  */
 import { WEIGHTS } from './score.mjs';
 
-export const TERMINALS = new Set(['$close', '$stop']);
+const TERMINALS = new Set(['$close', '$stop']);
 export const ENGINE_MAX_ITERATIONS = 20;
+/** A template's optional `category`, in the order the console's Loops list shows them. */
+export const CATEGORIES = ['architecture', 'tests', 'development', 'refactoring', 'day-to-day'];
 
 export function iterationLoop(graph) {
   return (graph.loops ?? []).find((l) => l.iteration === true);
@@ -141,5 +143,21 @@ export function checkGraph(graph, bricks) {
   for (const k of Object.keys(graph.weights ?? {})) {
     if (!Object.hasOwn(WEIGHTS, k)) problems.push(`weights: ${k} is not an action`);
   }
+  // optional glob lists (score.mjs's `globMatch` reads them)
+  for (const k of ['contracts', 'ignoreDeletions']) {
+    const v = graph[k];
+    if (v !== undefined && !(Array.isArray(v) && v.every((g) => typeof g === 'string' && g.trim()))) {
+      problems.push(`${k}: must be a list of non-empty glob strings`);
+    }
+  }
+  // optional instruction list every brick receives through `loop next`
+  const rules = graph.rules;
+  if (rules !== undefined && !(Array.isArray(rules) && rules.every((r) => typeof r === 'string' && r.trim()))) {
+    problems.push('rules: must be a list of non-empty strings');
+  }
+  // optional catalogue shelf: the console groups templates by it, an absent one under OTHER
+  if (graph.category !== undefined && !CATEGORIES.includes(graph.category)) {
+    problems.push(`category: must be one of ${CATEGORIES.join(', ')}`);
+  }
   return problems;
 }

package/js/loop/registry.mjs

@@ -0,0 +1,191 @@
+/**
+ * The loop registry — `<userLoopsDir()>/loops.json` — the list of worktrees `geneseed loop init`
+ * has launched a loop in. `LOOP.md` stays the only source of loop STATE; this file stores
+ * identity only (root, branch, title, started, finishedAt), so the Active tab can discover a
+ * loop without scanning every worktree on the machine.
+ *
+ * WRITER CONVENTIONS, mirrored from `js/inspect/registry.mjs` (`installs.json`'s own registry)
+ * on purpose rather than invented fresh: `jsonDumpsIndent` because these rows are absolute
+ * paths and a username carrying an accent writes one here (ensure_ascii matters); a
+ * `<file>.tmp` + `renameWithRetry` (LOOP.md's own atomic rename, retried on a transient Windows
+ * lock) so a crash mid-write cannot leave `loops.json` half-written where
+ * the NEXT read would see valid-but-truncated JSON instead of either the old file or the new
+ * one; and every public function swallows its own errors — a registry hiccup must never fail
+ * `loop init`, and a corrupt `loops.json` must read back as empty rather than throw. The one
+ * difference from `installs.json`: this file keys rows by object (`{root, branch, title,
+ * started, finishedAt}`), not by a bare path, because identity alone is not enough to render a
+ * card.
+ *
+ * NO `lastSeen`. The Active tab POLLS `activeLoops` on an interval, and a field refreshed on
+ * every read would make every poll a write — fine for `installs.json` (`record` fires once per
+ * emit), wrong here (the page's own `usePoll` fires every few seconds, for as long as the tab
+ * is open, on a machine that may be a laptop on battery). So `activeLoops` saves the registry
+ * back ONLY when the kept set actually differs from what it loaded — a root pruned, a loop
+ * newly seen finished, or a loop seen running again after having been finished — never merely
+ * to record that a poll happened. `finishedAt` replaces `lastSeen` for the one thing a
+ * timestamp was doing here: it is set ONCE, the first time a row is found WITHOUT a LOOP.md
+ * (the loop finished), and the 7-day prune window counts from there — not from a last-poll time
+ * nothing refreshes any more. A loop seen running again afterwards (the same worktree
+ * re-`init`ed) clears it, so a stale finished-window never survives into a loop that is running
+ * again.
+ *
+ * `recordLoop` and `setLoopPreset` resolve the root they are given the same way — `normalize`:
+ * `realpathSync.native`, falling back to `path.resolve` for a root that no longer exists — and
+ * compare it with `normcase`, the same case-folding `js/lib/paths.mjs` uses everywhere a Windows
+ * path is compared, so a loop launched from a differently-cased spelling of the same worktree is
+ * still one row, not two. `activeLoops` compares nothing: it reads each row's root as stored.
+ */
+import { readFileSync, mkdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+
+import { userLoopsDir } from './catalog.mjs';
+import { writeText, readText, isDir, isFile } from '../lib/fs.mjs';
+import { parseJson, jsonDumpsIndent } from '../lib/json.mjs';
+import { normcase } from '../lib/paths.mjs';
+import { parseLoopFile, writeLoopFile, renameWithRetry, reviewOf, LOOP_FILE } from './state.mjs';
+import { PRESETS } from './score.mjs';
+
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function registryPath() {
+  return path.join(userLoopsDir(), 'loops.json');
+}
+
+function load() {
+  try {
+    const data = parseJson(readFileSync(registryPath(), 'utf8'));
+    return Array.isArray(data?.loops) ? data.loops.filter((l) => l && typeof l.root === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function save(loops) {
+  try {
+    const file = registryPath();
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    writeText(tmp, `${jsonDumpsIndent({ loops })}\n`);
+    renameWithRetry(tmp, file);
+  } catch {
+    /* best-effort: a registry hiccup must never fail init or a read */
+  }
+}
+
+function normalize(dir) {
+  try { return realpathSync.native(dir); } catch { return path.resolve(dir); }
+}
+
+const sameRoot = (a, b) => normcase(a) === normcase(b);
+
+function runningRow(entry, state) {
+  return {
+    root: entry.root, branch: entry.branch, title: entry.title, started: entry.started,
+    status: state.status, iteration: state.iteration, node: state.node, preset: state.preset,
+    threshold: PRESETS[state.preset], current: state.current, history: state.history,
+    review: reviewOf(state), reason: state.reason, awaiting: state.awaiting, graph: state.graph,
+  };
+}
+
+/**
+ * Upsert `root`'s identity row. Called by `geneseed loop init` right after `LOOP.md` is
+ * written — `started` is set once, on insert, and never moved by a later call. An update never
+ * touches `finishedAt` either way: `activeLoops` is the only writer of that field, and it will
+ * clear it on the very next poll once it sees LOOP.md present again. Never throws: an `init`
+ * must succeed even when the registry itself cannot be written.
+ */
+export function recordLoop({ root, branch, title, now = new Date() }) {
+  try {
+    const key = normalize(root);
+    const loops = load();
+    const idx = loops.findIndex((l) => sameRoot(l.root, key));
+    if (idx >= 0) {
+      loops[idx] = { ...loops[idx], root: key, branch, title };
+    } else {
+      loops.push({ root: key, branch, title, started: now.toISOString() });
+    }
+    save(loops);
+  } catch {
+    /* a registry hiccup must never fail loop init */
+  }
+}
+
+/**
+ * The rows the Active tab renders, read fresh off every registered worktree's `LOOP.md` —
+ * never off the registry's own stale copy of a loop's state. Four outcomes per row; the
+ * write-back at the end fires ONLY when one of the first three actually changed something
+ * (see the module docblock on why a routine poll must not be a write):
+ *   - the worktree root no longer exists: dropped, silently (a removed clone or worktree);
+ *   - `<root>/LOOP.md` exists but fails to parse (corrupt, or written mid-crash before this
+ *     module's own atomic writer existed): the entry is KEPT exactly as read — dropping it here
+ *     would be indistinguishable from a removed worktree, and a card the user can still see
+ *     beats one that silently vanishes — and the row reports `status: 'unreadable'`;
+ *   - `<root>/LOOP.md` exists and parses: the row carries the state fields the page needs, and
+ *     if the entry still carried a `finishedAt` from a previous finish it is cleared (the loop
+ *     is running again — that counts as a change, and is saved);
+ *   - `LOOP.md` is gone (the loop finished): the first time this is seen, `finishedAt` is set
+ *     to `now` and saved; after that it is read-only here until `now` is more than 7 days past
+ *     that frozen `finishedAt`, at which point the row is dropped (and the drop is saved).
+ */
+export function activeLoops({ now = new Date() } = {}) {
+  const loops = load();
+  const kept = [];
+  const rows = [];
+  let changed = false;
+  for (const entry of loops) {
+    if (!isDir(entry.root)) { changed = true; continue; }
+    const file = path.join(entry.root, LOOP_FILE);
+    const identity = { root: entry.root, branch: entry.branch, title: entry.title, started: entry.started };
+    if (isFile(file)) {
+      let state;
+      try { state = parseLoopFile(readText(file)); } catch {
+        kept.push(entry);
+        rows.push({ ...identity, status: 'unreadable' });
+        continue;
+      }
+      let next = entry;
+      if (entry.finishedAt !== undefined) {
+        next = { ...entry }; delete next.finishedAt; changed = true;
+      }
+      kept.push(next);
+      rows.push(runningRow(next, state));
+      continue;
+    }
+    if (entry.finishedAt === undefined) {
+      const next = { ...entry, finishedAt: now.toISOString() };
+      changed = true;
+      kept.push(next);
+      rows.push({ ...identity, status: 'finished' });
+      continue;
+    }
+    const age = now.getTime() - new Date(entry.finishedAt).getTime();
+    if (age > SEVEN_DAYS_MS) { changed = true; continue; }
+    kept.push(entry);
+    rows.push({ ...identity, status: 'finished' });
+  }
+  if (changed) save(kept);
+  return rows;
+}
+
+/**
+ * Rewrite `root`'s `LOOP.md` `preset` field and nothing else — the per-loop preset picker on
+ * the Active tab. Refuses a `root` the registry does not know about (no arbitrary path
+ * writes — `POST /api/loops/preset`'s whole safety argument) and a `preset` outside `PRESETS`,
+ * each with its own message so the web action can tell the two refusals apart. Unlike
+ * `recordLoop`/`activeLoops`, this one DOES throw: a preset change the caller asked for and did
+ * not happen must be reported, not swallowed. Writes through `writeLoopFile` (atomic, like
+ * every other LOOP.md persist — see `state.mjs`'s docblock).
+ */
+export function setLoopPreset(root, preset) {
+  if (!Object.hasOwn(PRESETS, preset)) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
+  const key = normalize(root);
+  const loops = load();
+  const entry = loops.find((l) => sameRoot(l.root, key));
+  if (!entry || !isDir(entry.root)) throw new Error('unknown loop');
+  const file = path.join(entry.root, LOOP_FILE);
+  if (!isFile(file)) throw new Error('unknown loop');
+  const state = parseLoopFile(readText(file));
+  state.preset = preset;
+  writeLoopFile(file, state);
+  return runningRow(entry, state);
+}

package/js/loop/score.mjs

@@ -29,7 +29,7 @@ export const PRESETS = Object.freeze({
 export const DEFAULT_PRESET = 'balanced';
 
 /** More deleted lines than this in one iteration counts as a code deletion. */
-export const DELETION_LINES = 20;
+const DELETION_LINES = 20;
 
 const RANK = { silent: 0, soft: 1, blocking: 2 };
 
@@ -104,23 +104,60 @@ export function parseNumstat(text) {
 
 const slash = (p) => p.replaceAll('\\', '/');
 
-export function actualRisk(declared, files, { writeSet = [], contracts = [], overrides = {} } = {}) {
+// The one glob dialect of the loop — a template's `contracts` and `ignoreDeletions`, and LOOP.md's
+// own `contracts`. `*` and `?` stay inside a path segment; `**` crosses segments, and `**/` may
+// match no directory at all, so `**/yarn.lock` covers the root one too. Both sides are
+// slash-normalised first, so a backslash is a separator, never an escape. Hand-rolled because
+// this module may import nothing but node builtins (see the docblock above); a plain path is a
+// glob that matches only itself, so exact-path contracts keep working.
+// A leading `./` or `/` is dropped on both sides: every path here is repo-relative.
+// ponytail: runs of `**/` and `*` collapse first, so stacked wildcards cannot compound; what
+// remains is the regex engine's backtracking over several separate `**` (O(n^k) on a near miss).
+// Patterns come from the template author or the user, never from untrusted input — a linear
+// matcher is the upgrade if that ever changes.
+const globPath = (p) => slash(String(p)).replace(/^(?:\.?\/)+/, '');
+
+export function globMatch(pattern, file) {
+  const g = globPath(pattern).replace(/\*{3,}/g, '**').replace(/(?:\*\*\/){2,}/g, '**/');
+  let re = '';
+  for (let i = 0; i < g.length; i += 1) {
+    const c = g[i];
+    if (c === '*' && g[i + 1] === '*') {
+      i += 1;
+      if (g[i + 1] === '/') { i += 1; re += '(?:.*/)?'; } else re += '.*';
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`).test(globPath(file));
+}
+
+const matchesAny = (globs, file) => globs.some((g) => globMatch(g, file));
+
+export function actualRisk(declared, files, {
+  writeSet = [], contracts = [], ignoreDeletions = [], overrides = {},
+} = {}) {
   const w = { ...WEIGHTS, ...overrides };
   let score = declared;
   const reasons = [];
+  // A write-set entry is a glob too (a plain path matches itself): a tool's generated store,
+  // ArchUnit's archunit_store/**, cannot be named file by file before the tool writes it. Only an
+  // entry with a literal segment globs: a wildcard-only one (`**`, `**/*.java`) would declare the
+  // whole repo, so it stays exact-match — matching nothing, the diff fails closed.
   const inSet = new Set(writeSet.map(slash));
-  const outside = files.filter((f) => !inSet.has(slash(f.file)));
+  const globs = writeSet.filter((g) => globPath(g).split('/').some((seg) => seg && !/[*?]/.test(seg)));
+  const outside = files.filter((f) => !inSet.has(slash(f.file)) && !matchesAny(globs, f.file));
   if (outside.length) {
     score = Math.max(score, 0.8);
     reasons.push(`outside the write set: ${outside.map((f) => slash(f.file)).join(', ')}`);
   }
-  const deleted = files.reduce((n, f) => n + f.deleted, 0);
+  // ignoreDeletions only leaves the deletion count: the write-set check above still saw the file.
+  const deleted = files.filter((f) => !matchesAny(ignoreDeletions, f.file)).reduce((n, f) => n + f.deleted, 0);
   if (deleted > DELETION_LINES) {
     score = Math.max(score, w.delete);
     reasons.push(`${deleted} lines deleted`);
   }
-  const contractSet = new Set(contracts.map(slash));
-  const hit = files.filter((f) => contractSet.has(slash(f.file)));
+  const hit = files.filter((f) => matchesAny(contracts, f.file));
   if (hit.length) {
     score = Math.max(score, w.api);
     reasons.push(`contract files: ${hit.map((f) => slash(f.file)).join(', ')}`);
@@ -129,8 +166,10 @@ export function actualRisk(declared, files, { writeSet = [], contracts = [], ove
 }
 
 export function decide(score, preset) {
+  if (!Object.hasOwn(PRESETS, preset)) {
+    throw new Error(`unknown preset ${JSON.stringify(preset)} — one of ${Object.keys(PRESETS).join(', ')}`);
+  }
   const t = PRESETS[preset];
-  if (!t) throw new Error(`unknown preset ${JSON.stringify(preset)} — one of ${Object.keys(PRESETS).join(', ')}`);
   if (score <= t[0]) return 'silent';
   if (score <= t[1]) return 'soft';
   return 'blocking';