geneseed 5.2.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +2 -2
  3. package/SHIPPED.md +1 -1
  4. package/adapters/opencode/plugins/geneseed-context.js +56 -10
  5. package/adapters/opencode/plugins/geneseed-guard.js +6 -1
  6. package/bin/geneseed-cli.mjs +61 -16
  7. package/bin/geneseed-hook.mjs +37 -3
  8. package/docs/concepts/factories.md +40 -6
  9. package/docs/concepts/footprint.md +1 -1
  10. package/docs/concepts/foreman-mode.md +2 -2
  11. package/docs/concepts/loop-gates.md +1 -1
  12. package/docs/concepts/loops.md +2 -2
  13. package/docs/concepts/shared-tier.md +1 -1
  14. package/docs/design-history.md +140 -0
  15. package/docs/extending.md +54 -162
  16. package/docs/guides/run-a-factory.md +15 -2
  17. package/docs/guides/upgrade.md +2 -2
  18. package/docs/reference/factory-actions.md +6 -5
  19. package/docs/reference/troubleshoot-update.md +1 -1
  20. package/docs/web-ui.md +16 -3
  21. package/harness.config.json +1 -1
  22. package/js/README.md +4 -3
  23. package/js/build/args.mjs +3 -3
  24. package/js/build/render.mjs +44 -24
  25. package/js/cli-table.json +135 -59
  26. package/js/factory/cli.mjs +24 -5
  27. package/js/factory/graph.mjs +13 -9
  28. package/js/factory/metrics.mjs +93 -0
  29. package/js/factory/registry.mjs +37 -12
  30. package/js/factory/state.mjs +25 -6
  31. package/js/hosts/hooks-context.mjs +26 -1
  32. package/js/hosts/hooks-prims.mjs +52 -3
  33. package/js/hosts/hooks.mjs +50 -29
  34. package/js/hosts/loss.mjs +6 -1
  35. package/js/inspect/diff.mjs +16 -1
  36. package/js/inspect/doctor.mjs +7 -3
  37. package/js/inspect/excludes.mjs +18 -6
  38. package/js/inspect/status.mjs +35 -7
  39. package/js/inspect/validate.mjs +44 -21
  40. package/js/maintain/uninstall.mjs +28 -1
  41. package/js/maintain/update.mjs +31 -7
  42. package/js/ui/cli.mjs +34 -4
  43. package/js/ui/menu.mjs +1 -1
  44. package/js/ui/tui.mjs +11 -14
  45. package/js/web/actions.mjs +2 -0
  46. package/js/web/api.mjs +28 -10
  47. package/js/web/daemon.mjs +0 -1
  48. package/js/web/server.mjs +1 -0
  49. package/js/web/state.mjs +37 -16
  50. package/package.json +1 -1
  51. package/src/AGENT.md.tmpl +23 -17
  52. package/src/agents/_template.md +1 -1
  53. package/src/agents/advocate.md +1 -1
  54. package/src/agents/developer.md +12 -3
  55. package/src/agents/empiricist.md +1 -1
  56. package/src/agents/framer.md +1 -1
  57. package/src/agents/historian.md +1 -1
  58. package/src/agents/operator.md +1 -1
  59. package/src/agents/pragmatist.md +1 -1
  60. package/src/agents/researcher.md +1 -1
  61. package/src/agents/skeptic.md +1 -1
  62. package/src/agents/steward.md +1 -1
  63. package/src/agents/user-advocate.md +1 -1
  64. package/src/agents/visionary.md +1 -1
  65. package/src/bricks/intake.md +10 -3
  66. package/src/bricks/retro.md +13 -3
  67. package/src/doctrines/comms.md +1 -1
  68. package/src/doctrines/ops.md +1 -1
  69. package/src/doctrines/process.md +7 -5
  70. package/src/factories/analysis-to-build.json +1 -0
  71. package/src/factories/bug-report-to-fix.json +1 -0
  72. package/src/factories/issue-to-pr.json +1 -0
  73. package/src/laws/universal.md +2 -2
  74. package/src/modes/foreman.md +8 -14
  75. package/src/skills/commit.md +7 -2
  76. package/src/skills/debug.md +1 -1
  77. package/src/skills/diagram-design/SKILL.md +1 -1
  78. package/src/skills/diagram-design/VENDOR.md +3 -1
  79. package/src/skills/factory-forge.md +5 -3
  80. package/src/skills/factory.md +22 -1
  81. package/src/skills/geneseed.md +1 -1
  82. package/src/skills/handoff.md +1 -1
  83. package/src/skills/parallel-agents.md +1 -1
  84. package/src/skills/pipeline.md +6 -6
  85. package/src/skills/plan.md +7 -3
  86. package/src/skills/spring-testing.md +1 -1
  87. package/themes/biker.json +78 -78
  88. package/themes/commentator.json +81 -81
  89. package/themes/cyberpunk.json +79 -79
  90. package/themes/gamer.json +77 -77
  91. package/themes/imperial.json +82 -82
  92. package/themes/joker.json +79 -79
  93. package/themes/marvin.json +82 -82
  94. package/themes/mean.json +82 -82
  95. package/themes/military.json +78 -78
  96. package/themes/neutral.json +78 -78
  97. package/themes/pirate.json +79 -79
  98. package/themes/sports.json +79 -79
  99. package/themes/verstappen.json +78 -78
  100. package/themes/wizard.json +79 -79
  101. package/web/dist/assets/ActiveLoops-BJJN3P-V.js +1 -0
  102. package/web/dist/assets/Activity-CqJiquEq.js +1 -0
  103. package/web/dist/assets/ActivityDetail-BSzevynX.js +1 -0
  104. package/web/dist/assets/{Bonsai-DSwUbavu.js → Bonsai-Bfpb6W-1.js} +1 -1
  105. package/web/dist/assets/{CopyButton-BzRQz7k2.js → CopyButton-ByIntFtB.js} +1 -1
  106. package/web/dist/assets/Dashboard-DBOEi9lQ.js +2 -0
  107. package/web/dist/assets/Docs-DvlMJhpu.js +5 -0
  108. package/web/dist/assets/Factories-Bpvv7L2H.js +1 -0
  109. package/web/dist/assets/{GreenhouseView-y9WAfcc_.js → GreenhouseView-GpBsYn50.js} +1 -1
  110. package/web/dist/assets/Installs-BlGmVrFK.js +3 -0
  111. package/web/dist/assets/{JournalView-DeBLRNGc.js → JournalView-iLuLrOxE.js} +1 -1
  112. package/web/dist/assets/Kits-DRwpxC-J.js +1 -0
  113. package/web/dist/assets/Laws-CZkiNOWQ.js +4 -0
  114. package/web/dist/assets/LibRows-DEHjIoD-.js +1 -0
  115. package/web/dist/assets/Library-B4K-1iNF.js +3 -0
  116. package/web/dist/assets/Loops-BWSzaW8E.js +2 -0
  117. package/web/dist/assets/{OperatorHudView-2ujVMjq1.js → OperatorHudView-BAXwCEvY.js} +1 -1
  118. package/web/dist/assets/Personal-Bp9nV4GR.js +2 -0
  119. package/web/dist/assets/Settings-CWWuaIp-.js +1 -0
  120. package/web/dist/assets/Tabs-CWeQTADL.js +1 -0
  121. package/web/dist/assets/index-CsAZq0BQ.css +1 -0
  122. package/web/dist/assets/index-How7SzDZ.js +6 -0
  123. package/web/dist/assets/usePoll-D5c_qIFZ.js +1 -0
  124. package/web/dist/index.html +2 -2
  125. package/web/dist/assets/ActiveLoops-BTHIaRhn.js +0 -1
  126. package/web/dist/assets/Activity-DlQ30znB.js +0 -1
  127. package/web/dist/assets/ActivityDetail-CG0mn5fW.js +0 -1
  128. package/web/dist/assets/Dashboard-Ce3UOsxJ.js +0 -2
  129. package/web/dist/assets/Docs-CisVnYqv.js +0 -5
  130. package/web/dist/assets/Factories-Dq5oW4CU.js +0 -1
  131. package/web/dist/assets/Installs-m4GElwFW.js +0 -3
  132. package/web/dist/assets/Kits-DJYVAnyE.js +0 -1
  133. package/web/dist/assets/Laws-CNpc_8ZV.js +0 -4
  134. package/web/dist/assets/LibRows-RO5bvXth.js +0 -1
  135. package/web/dist/assets/Library-Dg0ScciC.js +0 -3
  136. package/web/dist/assets/Loops-CjEdo-NG.js +0 -2
  137. package/web/dist/assets/Personal-D0yS7ahT.js +0 -2
  138. package/web/dist/assets/Settings-DEN0U8QI.js +0 -1
  139. package/web/dist/assets/Tabs-But5R6_r.js +0 -1
  140. package/web/dist/assets/index-Ck42AbRX.js +0 -6
  141. package/web/dist/assets/index-PG_ukkh6.css +0 -1
  142. package/web/dist/assets/usePoll-o8ul-Sog.js +0 -1
@@ -55,21 +55,33 @@ function worktreeNote(host, cfg, repo) {
55
55
  + `to the repo's ${marker}/settings.json: "claudeMdExcludes": ["${claudeMdEntry(cfg)}"]`;
56
56
  }
57
57
 
58
- /** `_global_installs` — every host whose GLOBAL config dir carries a Geneseed manifest. */
59
- function globalInstalls() {
58
+ /**
59
+ * `[host, configDir]` for each host whose GLOBAL config dir `has` accepts, in `HOSTS` order —
60
+ * THE one walk over the hosts' global dirs. `exclude` tests for the manifest; `uninstall`,
61
+ * `version` and `diff` pass their own test to pick a no-`--target` default.
62
+ *
63
+ * HERE, not in `maintain/uninstall.mjs`: every global emit runs the fold, the fold reaches this
64
+ * module, and `tests/unit/hook_cli.test.mjs` keeps js/maintain out of the fold's import graph.
65
+ */
66
+ export function hostGlobalInstalls(has) {
60
67
  const out = [];
61
68
  for (const { host, configDir } of HOSTS) {
62
- let cfg;
63
69
  try {
64
- cfg = configDir();
70
+ const dir = configDir();
71
+ if (has(host, dir)) out.push([host, dir]);
65
72
  } catch {
66
- continue; // a broken resolver must not kill the CLI
73
+ continue; // a broken resolver, or an unreadable dir, must not kill the CLI
67
74
  }
68
- if (isFile(path.join(cfg, GLOBAL_MANIFEST))) out.push({ host, cfg });
69
75
  }
70
76
  return out;
71
77
  }
72
78
 
79
+ /** `_global_installs` — every host whose GLOBAL config dir carries a Geneseed manifest. */
80
+ function globalInstalls() {
81
+ return hostGlobalInstalls((_host, cfg) => isFile(path.join(cfg, GLOBAL_MANIFEST)))
82
+ .map(([host, cfg]) => ({ host, cfg }));
83
+ }
84
+
73
85
  /** `_read_excludes` — the file, or the seeded stub's shape when it is absent or unusable. */
74
86
  function readExcludes(cfg) {
75
87
  try {
@@ -57,7 +57,8 @@ import { pendingDrafts } from '../hosts/hooks-context.mjs';
57
57
  import { factCount } from '../hosts/memory-files.mjs';
58
58
  import { lastStoreReport } from '../hosts/store-watch.mjs';
59
59
  import { hookShimPath, shimDead } from '../hosts/shim.mjs';
60
- import { printOut } from '../lib/fs.mjs';
60
+ import { printErr, printOut } from '../lib/fs.mjs';
61
+ import { hostGlobalInstalls as globalInstalls } from './excludes.mjs';
61
62
  import { readDefaultInstall, sharedPaths } from '../lib/machine-dir.mjs';
62
63
  import { normcase } from '../lib/paths.mjs';
63
64
  import { renamedFilesIn } from '../build/stubs.mjs';
@@ -79,7 +80,14 @@ export function cmdVersion(args) {
79
80
  const current = sourceFingerprint(cfg);
80
81
  // `Path(args.target).expanduser().resolve()` — `resolvePath` already expands, so the tilde
81
82
  // is handled once rather than twice.
82
- let target = args.target ? resolvePath(args.target) : opencodeConfigDir();
83
+ let target = args.target ? resolvePath(args.target) : null;
84
+ // No `--target`: the global install the user picked as the default leads, as it leads
85
+ // `status`'s version row (`statusData`), so the two verbs name the same install.
86
+ if (!target) {
87
+ const picked = pickedInstall();
88
+ if (picked && picked[1] === 'global' && readVersion(picked[2]) !== null) target = picked[2];
89
+ }
90
+ target ??= opencodeConfigDir();
83
91
  let installed = readVersion(target);
84
92
  if (installed === null) {
85
93
  // A claude/bob/openclaude-only machine must not report "no install detected". The bundle
@@ -90,6 +98,15 @@ export function cmdVersion(args) {
90
98
  if (v) { installed = v; target = base; break; }
91
99
  }
92
100
  }
101
+ // The walk above already finds a Claude-only machine's install; with several, it shows the
102
+ // first, and says so rather than letting the reader take it for the only one.
103
+ if (!args.target) {
104
+ const globals = globalInstalls((_h, d) => readVersion(d) !== null);
105
+ if (globals.length > 1) {
106
+ printErr(`[version] ${globals.length} global installs found; showing ${target}. `
107
+ + 'Pass --target for another.\n');
108
+ }
109
+ }
93
110
  printOut(`[version] source: ${current} (${ROOT})\n`);
94
111
  printOut(`[version] installed: ${installed || '(none found)'}`
95
112
  + (installed ? ` (${target})` : '') + '\n');
@@ -306,8 +323,10 @@ export function statusData() {
306
323
  try { otherCfg.push(fn()); } catch { /* a missing host dir must not sink status */ }
307
324
  }
308
325
  const hostDirs = [...(cfgDir ? [cfgDir] : []), ...otherCfg, path.join(process.cwd(), 'Harness')];
309
- // Same walk as `cmdVersion`'s fallback, and cwd-relative for the same reason.
310
- for (const base of [...hostDirs, process.cwd()]) {
326
+ // Same walk as `cmdVersion`'s fallback, and cwd-relative for the same reason — led by the
327
+ // global install the `install` row names, so the `version` row describes that install.
328
+ const lead = picked && picked[1] === 'global' ? [picked[2]] : [];
329
+ for (const base of [...lead, ...hostDirs, process.cwd()]) {
311
330
  const v = readVersion(base);
312
331
  if (v) { installedFp = v; verTarget = base; break; }
313
332
  }
@@ -391,8 +410,12 @@ function colorEnabled() {
391
410
  * `_TUI_ASCII` is read from the environment at CALL time, not import time. Same value for a
392
411
  * process that runs one verb and exits; spelled this way because a module-level constant in
393
412
  * a file the tests import would freeze at whatever the test runner's environment was.
413
+ *
414
+ * `boxed` false is the face off a terminal: the title, the rows and the verdict, with no frame
415
+ * and no padding to the widest row. A long `installs` row made every boxed line ~210 columns,
416
+ * which a pipe, a log or an agent reads as 4–5 kB of spaces.
394
417
  */
395
- export function statusLines(d, color = false) {
418
+ export function statusLines(d, color = false, boxed = true) {
396
419
  const asc = Boolean(process.env.GENESEED_TUI_ASCII);
397
420
  const [H, V] = asc ? ['-', '|'] : ['─', '│'];
398
421
  const [TL, TR, BL, BR, LT, RT] = asc
@@ -429,7 +452,10 @@ export function statusLines(d, color = false) {
429
452
  + `doctrine rules in ${d.packs}/${d.packs_total} packs`]);
430
453
  }
431
454
  if (d.agent_md) {
432
- rows.push(['AGENT.md',
455
+ // The row is the OpenCode global's health, shown whichever install the `install` row names;
456
+ // under another host's install it says whose AGENT.md it is, so the two rows cannot be read
457
+ // as one install.
458
+ rows.push([d.emit === 'opencode-global' ? 'AGENT.md' : 'opencode AGENT.md',
433
459
  `${d.agent_md} (${d.agent_md_present ? 'present' : 'MISSING'})`]);
434
460
  }
435
461
  // Conditional for the same recording reason as `constitution` above: the 30 recorded
@@ -496,6 +522,7 @@ export function statusLines(d, color = false) {
496
522
  const body = rows.map(([k, v]) => ` ${padEndToWidth(k, labelW)} ${v}`);
497
523
  const verdict = ` ${mark} ${d.version_verdict}`;
498
524
  const title = ` ${badge} Geneseed ${emdash} status `;
525
+ if (!boxed) return [title.trim(), ...body, verdict];
499
526
  const width = Math.max(...body.map(codePointLength), codePointLength(verdict), codePointLength(title) + 2);
500
527
 
501
528
  const ac = ANSI_CODES[d.accent] ?? '36';
@@ -524,6 +551,7 @@ export function cmdStatus(args) {
524
551
  printOut(`${JSON.stringify(d, null, 2)}\n`);
525
552
  return 0;
526
553
  }
527
- for (const line of statusLines(d, colorEnabled())) printOut(`${line}\n`);
554
+ // The box only on a terminal; NO_COLOR on a terminal still gets it, so this is not `color`.
555
+ for (const line of statusLines(d, colorEnabled(), Boolean(process.stdout.isTTY))) printOut(`${line}\n`);
528
556
  return 0;
529
557
  }
@@ -7,6 +7,7 @@
7
7
  * reached — see its row in `tests/ported.json`.
8
8
  */
9
9
  import path from 'node:path';
10
+ import { FLAGS, VALUED } from '../build/args.mjs';
10
11
  import { buildInto, emitGlobalInto, emitProjectInto } from '../build/driver.mjs';
11
12
  import { GATE_SWITCHES } from '../build/source.mjs';
12
13
  import { resolvePath } from '../hosts/hosts.mjs';
@@ -17,6 +18,7 @@ import { validateIsVendored } from '../hosts/native.mjs';
17
18
  import { printOut, printErr } from '../lib/fs.mjs';
18
19
  import { comparePaths } from '../lib/paths.mjs';
19
20
  import { stripWhitespace } from '../lib/text.mjs';
21
+ import { cliCommand, formatHelp, helpWidth } from '../ui/cli.mjs';
20
22
  import { checkBuild } from './checks-build.mjs';
21
23
  import { cmdDoctor } from './doctor.mjs';
22
24
  import { isDir, isFile, rglob, withTempDir, within } from './scan.mjs';
@@ -25,23 +27,45 @@ import { isDir, isFile, rglob, withTempDir, within } from './scan.mjs';
25
27
  // validate — the generator's `--validate-only`, on this binary because it runs the doctor
26
28
  // --------------------------------------------------------------------------------------
27
29
 
30
+ /** The generator flags `validate` refuses (`cmdValidate`) or has no use for. */
31
+ const NOT_VALIDATE = ['--sync-themes', '--config-dir', '--validate-only'];
32
+
28
33
  /**
29
- * `validate --help`. Its own text, because the parser it borrows is the generator's and that
30
- * parser's `-h` prints `usage: geneseed-build …` — naming `--sync-themes`/`--config-dir`, which
31
- * this verb refuses, under a program name the user did not type.
34
+ * `validate --help`. Not the borrowed parser's own `-h`, which prints `usage: geneseed-build …`
35
+ * under a program name the user did not type.
36
+ *
37
+ * DERIVED FROM THE GENERATOR'S FLAG TABLES (`VALUED`, `FLAGS`), never typed out: the hand-kept
38
+ * copy it replaces had already lost `--no-ownership-gate`, `--prune-gates` and `--force`. Each
39
+ * flag's help and choices are `geneseed build`'s (`cliCommand`), so the two verbs say one thing.
32
40
  */
33
- export const VALIDATE_USAGE = [
34
- 'usage: geneseed validate [-h] [--theme THEME] [--emit EMIT] [--out OUT] [--root ROOT]',
35
- ' [--footprint {lean,full}] [--posture POSTURE] [--mode MODE]',
36
- ' [--trust TRUST] [--doctrines DOCTRINES] [--exclude-rules RULES]',
37
- ' [--exclude-skills SKILLS] [--kits KITS] [--shared-tier on|off] [--no-secrets-gate]',
38
- ' [--no-done-gate] [--no-deletion-gate] [--no-external-gate] [--no-test-note] [-v]',
39
- '',
40
- "Render and emit into a throwaway sandbox, run the doctor's checks, and write nothing real.",
41
- "Takes the generator's render flags (see geneseed-build --help) except --sync-themes and",
42
- '--config-dir.',
43
- '',
44
- ].join('\n');
41
+ export function validateUsage(width = helpWidth()) {
42
+ const build = new Map(cliCommand('build').options.map((o) => [o.names[0], o]));
43
+ const byDest = new Map();
44
+ for (const [table, isFlag] of [[VALUED, false], [FLAGS, true]]) {
45
+ for (const [flag, dest] of Object.entries(table)) {
46
+ if (NOT_VALIDATE.includes(flag)) continue;
47
+ if (byDest.has(dest)) { byDest.get(dest).names.push(flag); continue; }
48
+ const row = build.get(flag);
49
+ const choices = row?.choices ?? null;
50
+ // argparse's metavar is the dest upper-cased; the driver's dests are camelCase, so the
51
+ // flag spells it (`EXCLUDE_RULES`, as `build --help` shows), unless choices stand in.
52
+ const metavar = row?.metavar ?? (isFlag || choices ? null
53
+ : flag.slice(2).toUpperCase().replace(/-/g, '_'));
54
+ byDest.set(dest, {
55
+ names: [flag], dest, metavar, help: row?.help ?? '',
56
+ choices, required: false, nargs: isFlag ? '0' : null, is_flag: isFlag,
57
+ });
58
+ }
59
+ }
60
+ // `-v`/`--verbose` is the one flag `build` does not forward, so the table has no help for it.
61
+ const verbose = byDest.get('verbose');
62
+ if (verbose && !verbose.help) verbose.help = 'list every file the dry run would write';
63
+ return formatHelp({
64
+ options: [...byDest.values()],
65
+ description: "Render and emit into a throwaway sandbox, run the doctor's checks, and write "
66
+ + `nothing real. Takes the generator's render flags except ${NOT_VALIDATE.slice(0, 2).join(' and ')}.`,
67
+ }, 'geneseed validate', width);
68
+ }
45
69
 
46
70
  /**
47
71
  * Capture the streams of an IN-PROCESS call.
@@ -149,13 +173,12 @@ export function cmdValidate(args) {
149
173
  } catch (e) {
150
174
  // A DELIBERATE refusal from the render (an unknown theme, an incomplete source).
151
175
  //
152
- // THE EXIT CODE AND NOT THE MESSAGE: every refusal that crosses the seam arrives
153
- // here as an INTEGER exit code, not the sentence `loadTheme` wrote on stderr on the
154
- // way out, and the printed line is part of the verb's output. Printing `e.message`
155
- // would say `unknown theme 'x'` where the output says `1`.
176
+ // The refusal already explained itself on stderr (`loadTheme`'s sentence) on the way out;
177
+ // what crosses the seam is only its exit code. So this line names what failed and adds
178
+ // nothing after it: it used to end in that bare code (`: 1`), which read as a message
179
+ // cut short. The code is the process's exit status, where it belongs.
156
180
  if (e && e.exitCode !== undefined) {
157
- printOut(`[validate-only] render/emit FAILED for theme '${args.theme}' `
158
- + `emit '${emit}': ${e.exitCode}\n`);
181
+ printOut(`[validate-only] render/emit FAILED for theme '${args.theme}' emit '${emit}'\n`);
159
182
  return null;
160
183
  }
161
184
  throw e;
@@ -72,6 +72,7 @@ import { printOut, printErr, readText, writeText, isFile, isDir, isOsError } fro
72
72
  import { indexOfDeepEqual, isDict, jsonDumps, deepEquals } from '../lib/json.mjs';
73
73
  import { sharedPaths } from '../lib/machine-dir.mjs';
74
74
  import { archiveStore } from '../hosts/memory-files.mjs';
75
+ import { hostGlobalInstalls } from '../inspect/excludes.mjs';
75
76
  import { comparePaths, isAbsolutePath } from '../lib/paths.mjs';
76
77
 
77
78
  const hostSpec = (host) => HOSTS.find((h) => h.host === host);
@@ -720,7 +721,8 @@ export function projectQualifies(root, host) {
720
721
  * 2. `--target` IS a project marker dir itself (…/.claude) — root is its parent.
721
722
  * 3. `--target` (as a root) carries a Geneseed project install.
722
723
  * 4. `--target` given and unrecognised — null, and the caller reports it.
723
- * 5. No `--target`: the cwd, then the OpenCode global config dir.
724
+ * 5. No `--target`: the cwd, then the one global install on the machine, else the OpenCode
725
+ * global config dir (`cmdUninstall` refuses when there are several).
724
726
  */
725
727
  export function uninstallResolve(targetArg) {
726
728
  const globalHit = (p) => {
@@ -754,9 +756,23 @@ export function uninstallResolve(targetArg) {
754
756
  // would otherwise return a root that LOOKS different from the identical directory.
755
757
  const hit = projectHit(resolvePath(process.cwd()));
756
758
  if (hit) return hit;
759
+ // The one global install on this machine, whatever its host: a Claude-only machine used to
760
+ // resolve to the empty OpenCode dir. With none, or several, the OpenCode dir stays the
761
+ // answer; `cmdUninstall` refuses the several case before it acts on it.
762
+ const globals = globalInstalls();
763
+ if (globals.length === 1) return [globals[0][0], 'global', globals[0][1]];
757
764
  return ['opencode', 'global', opencodeConfigDir()];
758
765
  }
759
766
 
767
+ /**
768
+ * `[host, configDir]` for each host's global dir that holds an install (`installState` not
769
+ * absent) — the candidates a bare `uninstall` chooses from. The walk is `hostGlobalInstalls`
770
+ * (`inspect/excludes.mjs`), its one owner; `version` and `diff` call it with their own marker.
771
+ */
772
+ export function globalInstalls() {
773
+ return hostGlobalInstalls((host, dir) => installState(dir, host, 'global') !== 'absent');
774
+ }
775
+
760
776
  /**
761
777
  * The PROJECT installs still on record.
762
778
  *
@@ -831,6 +847,17 @@ export function cmdUninstall(args) {
831
847
  return 1;
832
848
  }
833
849
  const [host, scope, root] = hit;
850
+ // No `--target` and more than one global install: which one is meant is a guess, and this
851
+ // verb deletes. Refused before anything is printed as a target, `--yes` or not.
852
+ if (!args.target && scope === 'global') {
853
+ const globals = globalInstalls();
854
+ if (globals.length > 1) {
855
+ printErr(`[uninstall] ${globals.length} global installs found, and no --target names one. `
856
+ + 'Run one of:\n'
857
+ + globals.map(([h, d]) => ` geneseed uninstall --target "${d}" (${h}:global)\n`).join(''));
858
+ return 2;
859
+ }
860
+ }
834
861
  if (installState(root, host, scope) === 'absent') {
835
862
  const where = scope === 'project' && host !== 'opencode'
836
863
  ? ` under ${hostSpec(host).projectMarker}/` : '';
@@ -936,7 +936,17 @@ export async function upgrade(themeArg = null) {
936
936
  * captured against the PRE-refresh source. Anything it throws is a warning on stderr and the
937
937
  * upgrade continues — a failed export is a lost note, a blocked upgrade is a broken install.
938
938
  */
939
- export async function cmdUpgrade(args) {
939
+ export async function cmdUpgrade(args, { handoff = reexec } = {}) {
940
+ // `--theme NAME` is the positional `[theme]` spelled as every other verb spells it; both kept.
941
+ // Two different answers on one line is a typo, not a choice, so it is refused before anything runs.
942
+ if (args.theme && args.themeOpt && args.theme !== args.themeOpt) {
943
+ printErr(`geneseed: error: argument --theme: '${args.themeOpt}' contradicts the theme `
944
+ + `argument '${args.theme}' — give one.\n`);
945
+ return 2;
946
+ }
947
+ const theme = args.themeOpt || args.theme || null;
948
+ // `--setup`: the update with its step banner, then a FRESH `setup` — what `bootstrap` was.
949
+ if (args.setup) return updateThenSetup(theme, { handoff });
940
950
  try {
941
951
  const [ipath] = exportImprovements();
942
952
  if (ipath) {
@@ -947,7 +957,7 @@ export async function cmdUpgrade(args) {
947
957
  printErr(`[upgrade] ⚠️ could not export local edits (${e && e.message ? e.message : e}) — `
948
958
  + 'run `geneseed diff --out FILE` before upgrading to keep them.\n');
949
959
  }
950
- return upgrade(args.theme);
960
+ return upgrade(theme);
951
961
  }
952
962
 
953
963
  // ---------------------------------------------------------------------------------------
@@ -1037,7 +1047,7 @@ export function diagnoseFailedStep(n, total, title, cmd, rc, output) {
1037
1047
  *
1038
1048
  * Returns true when a step FAILED, so scripted callers get a real exit code.
1039
1049
  */
1040
- async function bootstrapPlain() {
1050
+ async function bootstrapPlain(theme = null) {
1041
1051
  // One `git pull` refreshes launchers + factory together, then rebuilds — a single step.
1042
1052
  //
1043
1053
  // `cmdUpgrade`, NOT `upgrade`. The step the reference runs is the SUBCOMMAND — its argv is
@@ -1048,7 +1058,7 @@ async function bootstrapPlain() {
1048
1058
  // which was written for `_flush_export_notes` and found this instead.
1049
1059
  /** @type {Array<[string, string[], () => Promise<number>]>} */
1050
1060
  const steps = [['Update & rebuild', updateStepCmd('upgrade'),
1051
- () => cmdUpgrade({ theme: null })]];
1061
+ () => cmdUpgrade({ theme })]];
1052
1062
  let failed = false;
1053
1063
  for (let i = 0; i < steps.length; i += 1) {
1054
1064
  const [title, cmd, step] = steps[i];
@@ -1095,16 +1105,19 @@ function reexec(argv) {
1095
1105
  *
1096
1106
  * AN UNCHECKED SOURCE IS THE EXCEPTION: `setup` renders, and no doctor has judged this tree.
1097
1107
  * An npm install has no record to hold, so it is not asked.
1108
+ *
1109
+ * `upgrade --setup` since `bootstrap` was folded into it; `setup: false` is what
1110
+ * `bootstrap --no-setup` still reaches for the one release it stays.
1098
1111
  */
1099
- export async function cmdBootstrap(args, { handoff = reexec } = {}) {
1100
- const failed = await bootstrapPlain();
1112
+ async function updateThenSetup(theme, { handoff = reexec, setup = true } = {}) {
1113
+ const failed = await bootstrapPlain(theme);
1101
1114
  flushExportNotes();
1102
1115
  if (isGitCheckout() && pendingGate()) {
1103
1116
  printOut('[geneseed] setup not started: the source has no doctor verdict yet. '
1104
1117
  + 'Run `geneseed update`, then `geneseed setup`.\n');
1105
1118
  return 1;
1106
1119
  }
1107
- if (!args.noSetup) {
1120
+ if (setup) {
1108
1121
  const rc = handoff([process.execPath,
1109
1122
  path.join(String(ROOT), 'bin', 'geneseed-cli.mjs'), 'setup']);
1110
1123
  return failed ? 1 : rc;
@@ -1112,3 +1125,14 @@ export async function cmdBootstrap(args, { handoff = reexec } = {}) {
1112
1125
  // Scripted `bootstrap --no-setup` must not exit 0 over a failed update.
1113
1126
  return failed ? 1 : 0;
1114
1127
  }
1128
+
1129
+ /**
1130
+ * `bootstrap`, DEPRECATED: folded into `upgrade --setup`. Kept one release as an alias that
1131
+ * says so on stderr and then does exactly what it did; its `--no-setup` is a plain `upgrade`
1132
+ * with the step banner.
1133
+ */
1134
+ export async function cmdBootstrap(args, { handoff = reexec } = {}) {
1135
+ printErr('[geneseed] bootstrap is deprecated: run `geneseed upgrade --setup` '
1136
+ + '(or `geneseed upgrade` for --no-setup).\n');
1137
+ return updateThenSetup(null, { handoff, setup: !args.noSetup });
1138
+ }
package/js/ui/cli.mjs CHANGED
@@ -35,15 +35,19 @@
35
35
  import { readFileSync } from 'node:fs';
36
36
  import path from 'node:path';
37
37
 
38
+ import { choicesFor } from '../build/args.mjs';
38
39
  import { ROOT } from '../build/source.mjs';
39
40
  import { printOut } from '../lib/fs.mjs';
40
41
  import { parseIntStrict, stripWhitespace } from '../lib/text.mjs';
41
42
 
42
43
  const CLI_JSON = path.join(ROOT, 'js', 'cli-table.json');
43
44
 
44
- /** The keys the docs page has always carried, per argument — `type` and `hidden` are ours. */
45
+ /**
46
+ * The keys the docs page carries, per argument — `type` and `hidden` are ours. `description` is
47
+ * an argument's own paragraph, when the table gives one; `null` when it does not.
48
+ */
45
49
  const PAGE_ARG_KEYS = ['names', 'dest', 'metavar', 'help', 'choices', 'default',
46
- 'required', 'nargs', 'is_flag'];
50
+ 'required', 'nargs', 'is_flag', 'description'];
47
51
 
48
52
  /**
49
53
  * `js/cli-table.json`, parsed. An unreadable file is the empty reference; the entry points
@@ -61,6 +65,26 @@ function load() {
61
65
  }
62
66
  }
63
67
 
68
+ /**
69
+ * `build` forwards the generator's flags, and the generator owns their choice lists — two of
70
+ * them (`--posture`, `--mode`) are discovered from the checkout. So the table carries no copy:
71
+ * the readers that SHOW the rows (help, the docs page) lay `choicesFor` over them here. Not in
72
+ * `load`: `cliSpec` never reads an option's choices, and every verb's parse would pay the scan.
73
+ */
74
+ function withDriverChoices(cmd) {
75
+ if (cmd?.name !== 'build') return cmd;
76
+ const choices = choicesFor();
77
+ for (const o of cmd.options ?? []) {
78
+ const list = choices[o.names?.[0]];
79
+ if (!list) continue;
80
+ o.choices = list;
81
+ // A row with its own metavar (`--emit`: nine names do not fit a usage line) names the
82
+ // list in its help instead of in `{…}`.
83
+ if (o.metavar) o.help = `${o.help} (one of: ${list.join(', ')})`;
84
+ }
85
+ return cmd;
86
+ }
87
+
64
88
  const pageArgs = (args) => (args ?? [])
65
89
  .filter((a) => !a.hidden)
66
90
  .map((a) => Object.fromEntries(PAGE_ARG_KEYS.map((k) => [k, a[k] ?? null])));
@@ -77,7 +101,7 @@ export function cliReference() {
77
101
  const data = load();
78
102
  return {
79
103
  prog: data.prog ?? 'geneseed',
80
- commands: (data.commands ?? []).map((c) => ({
104
+ commands: (data.commands ?? []).map(withDriverChoices).map((c) => ({
81
105
  name: c.name ?? '',
82
106
  help: c.help ?? '',
83
107
  description: c.description ?? '',
@@ -364,6 +388,12 @@ export function formatHelp(cmd, prog, width) {
364
388
  maxHelpPosition);
365
389
 
366
390
  const blocks = [`${formatUsage(prog, optParts, posParts, width)}\n`];
391
+ // argparse's `description`, wrapped to the full width after the usage line. It is where a
392
+ // verb's paragraph lives, so the top-level listing can keep each verb to one short line.
393
+ if (cmd.description && cmd.description.trim()) {
394
+ const collapsed = cmd.description.replace(/[ \t\n\v\f\r]+/g, ' ').trim();
395
+ blocks.push(`${wrapText(collapsed, Math.max(width, 11)).join('\n')}\n`);
396
+ }
367
397
  if (positionals.length) {
368
398
  blocks.push(`positional arguments:\n${positionals
369
399
  .map((a) => formatAction(a, true, helpPosition, width)).join('')}`);
@@ -401,7 +431,7 @@ export function helpWidth() {
401
431
 
402
432
  /** One command's raw row — everything the table knows, unlike the page's filtered view. */
403
433
  export function cliCommand(verb) {
404
- return (load().commands ?? []).find((c) => c.name === verb) ?? null;
434
+ return withDriverChoices((load().commands ?? []).find((c) => c.name === verb) ?? null);
405
435
  }
406
436
 
407
437
  /**
package/js/ui/menu.mjs CHANGED
@@ -25,7 +25,7 @@ import { startDaemon } from '../web/daemon.mjs';
25
25
  /** The off-TTY arm, and the fallback both TTY arms end in. */
26
26
  function menuHelp() {
27
27
  printOut('Geneseed — no interactive menu here. Get started with: geneseed setup\n');
28
- printOut('Other commands: bootstrap · update · build · doctor · diff · tui · web\n');
28
+ printOut('Other commands: update · build · doctor · diff · web\n');
29
29
  printOut('`geneseed --help` lists every command.\n');
30
30
  return 0;
31
31
  }
package/js/ui/tui.mjs CHANGED
@@ -1,11 +1,11 @@
1
1
  /**
2
2
  * `tui` — and the TUI's pure half: the layout helpers that have no screen in them.
3
3
  *
4
- * `cmdTui` is an entry with no full-screen panel. Off a TTY it prints one line and returns 1;
5
- * on a TTY it prints a refusal that names the console and returns 1, rather than inventing
6
- * a screen — the same decision `js/ui/menu.mjs` makes. `tests/unit/no_panel.test.mjs` fakes
7
- * `isTTY` true in a child and asserts BOTH arms — the exit code, and that the refusal names
8
- * the console rather than pretending to draw.
4
+ * `cmdTui` is RETIRED: an alias kept one release that prints one line pointing at `geneseed
5
+ * menu` and returns 0, on a TTY or off one — `menu`'s own off-terminal exit. There is no
6
+ * full-screen panel behind it, the same decision `js/ui/menu.mjs` makes.
7
+ * `tests/unit/no_panel.test.mjs` fakes `isTTY` true in a child and asserts the exit code, that
8
+ * the line names only declared verbs, and that nothing is drawn.
9
9
  *
10
10
  * What lives here is the alignment contract — the functions below that decide what a row
11
11
  * looks like: display width, fitting, glyph tiers, the catalogue's entries and detail lines.
@@ -310,15 +310,12 @@ export function detailLines(kind, label, data) {
310
310
  // ---- the verb ------------------------------------------------------------------------
311
311
 
312
312
  /**
313
- * The `tui` verb. Arm one is the reachable one; there is no panel, so the TTY arm
314
- * refuses — see this module's header.
313
+ * The `tui` verb, RETIRED: it refused on every terminal, since there is no panel (see this
314
+ * module's header). Kept one release as an alias that says where to go and exits as `menu`
315
+ * does off a terminal (0), so a script that called it learns the new name without breaking.
316
+ * The same one line on a TTY and off one. The layout helpers above stay: `catalog` uses them.
315
317
  */
316
318
  export function cmdTui() {
317
- if (!process.stdin.isTTY) {
318
- printOut('[tui] not an interactive terminal. Use `geneseed setup`, `geneseed doctor`, or `geneseed build`.\n');
319
- return 1;
320
- }
321
- printOut('[tui] full-screen panel unavailable (this entry carries the TUI\'s layout '
322
- + 'half, not its screens). Use `geneseed setup`, `geneseed doctor`, or `geneseed build`.\n');
323
- return 1;
319
+ printOut('[tui] tui is retired; use `geneseed menu`.\n');
320
+ return 0;
324
321
  }
@@ -234,6 +234,8 @@ export function targetView(base, [host, scope, root]) {
234
234
  v = webState(null, target);
235
235
  v.selectView(target, root, emitOf(host, scope));
236
236
  v.pinned = true;
237
+ // A serving daemon runs no doctor on the event loop, for a named install either (`warmDoctor`).
238
+ Object.defineProperty(v, 'warm', { get: () => base.warm });
237
239
  // The daemon's one memo: a render is keyed on what it read, not on who asked for it.
238
240
  v.renderMemo = (base.renderMemo ??= renderMemo());
239
241
  v.refresh = base.refresh;
package/js/web/api.mjs CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  import { PRESETS } from '../loop/score.mjs';
31
31
  import { loadCatalog, catalogProblems } from '../loop/catalog.mjs';
32
32
  import { activeLoops, runningLoops, sameRoot } from '../loop/registry.mjs';
33
- import { activeFactories } from '../factory/registry.mjs';
33
+ import { listFactories } from '../factory/registry.mjs';
34
34
  import { factoryCatalogProblems, loopOf } from '../factory/graph.mjs';
35
35
  import { EMIT_OPTIONS, themeOptions } from '../maintain/setup.mjs';
36
36
  import { accentFor, keptKitFiles, statusData } from '../inspect/status.mjs';
@@ -40,7 +40,7 @@ import { comparePaths } from '../lib/paths.mjs';
40
40
  import {
41
41
  configItems, deployed, dget, fleetCounts, memoryDir, memoryItems, notebookItems, orSkip, tierOf, wikiItems,
42
42
  } from './catalog.mjs';
43
- import { defaultView, samePath, stampMinute, viewCfg } from './state.mjs';
43
+ import { defaultView, samePath, stampMinute, viewCfg, warmDoctor } from './state.mjs';
44
44
  import { MANUAL_UPDATE, gitBehind, installKind, updateStatus } from './update-check.mjs';
45
45
 
46
46
  /**
@@ -93,22 +93,34 @@ const DOCTOR_COOLDOWN_MS = 3_000;
93
93
  *
94
94
  * A fresh ask within `DOCTOR_COOLDOWN_MS` of the last one THIS PATH ran reuses that run, so a
95
95
  * page looping on `?fresh=1` cannot pin the event loop. `_doctorFreshAt` is written here only: a
96
- * verdict planted any other way still re-runs. No single-flight promise — `runDoctor` is
97
- * synchronous, so two fresh runs cannot overlap; only the warm-up is not (`warmDoctor`).
96
+ * verdict planted any other way still re-runs. On a serving daemon (`state.warm`) the fresh run
97
+ * goes to the warm-up thread (`warmDoctor`, which stops the run it replaces); elsewhere it is
98
+ * the synchronous `runDoctor`.
98
99
  *
99
- * This page needs the groups, so during the warm-up it answers with a promise of the verdict
100
- * rather than a pending one: the request waits, the event loop does not.
100
+ * This page needs the groups, so while a run is out it answers with a promise of the verdict
101
+ * rather than a pending one: the request waits, the event loop does not. A run that a refresh or
102
+ * a newer fresh ask replaced settles with no verdict, so the promise follows the newer run. Only a
103
+ * thread that could not give one (it failed to start or died) leaves the run to this request.
101
104
  */
102
105
  export function apiDoctor(state, fresh = false) {
103
106
  if (fresh && Date.now() - (state._doctorFreshAt ?? 0) >= DOCTOR_COOLDOWN_MS) {
104
- state.runDoctor();
107
+ // A daemon re-runs on the warm-up thread: the page waits on the promise, the loop does not.
108
+ if (state.warm) {
109
+ state._doctor = null;
110
+ state._doctorJob = null;
111
+ } else state.runDoctor();
105
112
  state._doctorFreshAt = Date.now();
106
113
  }
114
+ // `_doctor`, not the `doctor` getter: on a daemon the getter would start a thread and say null.
107
115
  const answer = () => {
108
- const { ok, problems, checked_at } = state.doctor;
116
+ if (state._doctor === null && state._doctorJob !== null) return state._doctorJob.then(answer);
117
+ if (state._doctor === null) state.runDoctor();
118
+ const { ok, problems, checked_at } = state._doctor;
109
119
  return { ...state._doctorRun, ok, problems, checked_at };
110
120
  };
111
- return state._doctorJob === null ? answer() : state._doctorJob.then(answer);
121
+ // A cold cache on a daemon (a view switch dropped it) is filled on the thread, as the overview's is.
122
+ if (state.warm && state._doctor === null) warmDoctor(state);
123
+ return answer();
112
124
  }
113
125
 
114
126
  /**
@@ -646,11 +658,17 @@ export function apiFactoriesCatalog(state) {
646
658
  * `apiLoopsActive`), each with the loop running in its worktree as `loop` (the root is the join
647
659
  * key, `js/factory/registry.mjs`), or null. `runningLoops`, not `activeLoops`: it is read-only,
648
660
  * so this poll never prunes or stamps `loops.json` behind the Loops page's back.
661
+ *
662
+ * It is the board's read too (D7). A live row carries what `FACTORY.md` holds — `status`, `stage`,
663
+ * `awaiting`, `tasks`, `counters` beside the graph's cycles and their `max`, `history` — and
664
+ * `metrics`, `runMetrics` of that state. A `FACTORY.md` that does not parse is a row with status
665
+ * `unreadable`, and a missing one `finished`: identity only, never a throw. `listFactories` is
666
+ * read-only: this poll never writes a run or `factories.json` (D7).
649
667
  */
650
668
  export function apiFactoriesActive() {
651
669
  const loops = runningLoops();
652
670
  return {
653
- factories: activeFactories().map((run) => {
671
+ factories: listFactories().map((run) => {
654
672
  const l = loops.find((x) => sameRoot(x.root, run.root));
655
673
  return { ...run, loop: l ? { title: l.title, status: l.status, node: l.node, iteration: l.iteration, graph: l.graph } : null };
656
674
  }),
package/js/web/daemon.mjs CHANGED
@@ -524,7 +524,6 @@ export async function findConsoles(target, ports) {
524
524
  const all = [...new Set([isTruthy(rec) ? Number(rec.port) : null, ...ports].filter(Number.isInteger))];
525
525
  const found = [];
526
526
  for (const p of all) {
527
- // eslint-disable-next-line no-await-in-loop
528
527
  const c = await identify(p);
529
528
  if (c) found.push({ port: p, url: `http://127.0.0.1:${p}`, pid: c.pid, root: c.root,
530
529
  recorded: isTruthy(rec) && rec.pid === c.pid && Number(rec.port) === p });
package/js/web/server.mjs CHANGED
@@ -188,6 +188,7 @@ export async function serve({ theme = null, port = 4747, openBrowser = true,
188
188
  printOut(daemon ? '[web] daemon ready.\n' : '[web] Ctrl-C to stop.\n');
189
189
  if (openBrowser) openUrl(url);
190
190
  // After the record and the ready line, so `web start`'s wait loop already has its URL.
191
+ state.warm = true;
191
192
  warmDoctor(state);
192
193
  // Node kills on SIGINT by default, which would skip this message and the record
193
194
  // cleanup in `srv.on('close', ...)` below — a foreground `--daemon-internal` server