geneseed 4.31.0 → 5.0.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 (272) hide show
  1. package/CHANGELOG.md +107 -0
  2. package/DESIGN.md +2 -2
  3. package/README.md +6 -5
  4. package/SHIPPED.md +4 -3
  5. package/adapters/bob/README.md +6 -5
  6. package/adapters/claude-code/README.md +4 -3
  7. package/adapters/claude-code/skills/geneseed/SKILL.md +1 -1
  8. package/adapters/openclaude/README.md +4 -3
  9. package/adapters/opencode/GLOBAL-HARNESS-SPEC.md +3 -1
  10. package/adapters/opencode/HOW-OPENCODE-LOADS.md +2 -1
  11. package/adapters/opencode/README.md +18 -18
  12. package/adapters/opencode/plugins/geneseed-activity.js +57 -1
  13. package/adapters/opencode/plugins/geneseed-context.js +220 -18
  14. package/adapters/opencode/plugins/geneseed-guard.js +578 -74
  15. package/adapters/opencode/plugins/geneseed-learn.js +97 -23
  16. package/bin/geneseed-cli.mjs +17 -25
  17. package/bin/geneseed-hook.mjs +23 -8
  18. package/docs/DESIGN.md +175 -0
  19. package/docs/PRD.md +111 -0
  20. package/docs/README.md +3 -2
  21. package/docs/architecture.md +145 -0
  22. package/docs/concepts/agents.md +1 -1
  23. package/docs/concepts/collaboration.md +1 -1
  24. package/docs/concepts/enforcement-table.md +1 -1
  25. package/docs/concepts/exclusions.md +6 -6
  26. package/docs/concepts/footprint.md +1 -1
  27. package/docs/concepts/foreman-mode.md +2 -2
  28. package/docs/concepts/hook-gates.md +1 -1
  29. package/docs/concepts/hooks.md +27 -11
  30. package/docs/concepts/host-matrix.md +3 -3
  31. package/docs/concepts/hosts.md +1 -1
  32. package/docs/concepts/kits.md +3 -1
  33. package/docs/concepts/loop-bricks.md +1 -1
  34. package/docs/concepts/loop-notes.md +4 -2
  35. package/docs/concepts/loop-templates.md +7 -4
  36. package/docs/concepts/loops.md +3 -0
  37. package/docs/concepts/ownership.md +2 -2
  38. package/docs/concepts/rules.md +15 -2
  39. package/docs/concepts/shared-tier.md +73 -0
  40. package/docs/concepts/skills.md +2 -2
  41. package/docs/concepts/themes.md +1 -1
  42. package/docs/extending.md +13 -12
  43. package/docs/guides/install-claude-code.md +1 -1
  44. package/docs/guides/install-opencode.md +1 -1
  45. package/docs/guides/migrate.md +4 -2
  46. package/docs/guides/project-context.md +2 -2
  47. package/docs/guides/run-a-loop.md +1 -1
  48. package/docs/guides/set-up-ownership.md +1 -1
  49. package/docs/guides/setup-footprint.md +1 -1
  50. package/docs/guides/uninstall.md +2 -1
  51. package/docs/guides/upgrade-to-5.md +116 -0
  52. package/docs/guides/upgrade.md +21 -9
  53. package/docs/guides/wiki.md +3 -3
  54. package/docs/reference/env-context.md +5 -3
  55. package/docs/reference/environment.md +1 -1
  56. package/docs/reference/glossary.md +2 -0
  57. package/docs/reference/loop-actions.md +1 -1
  58. package/docs/reference/opencode-plugins.md +3 -3
  59. package/docs/reference/plugin-activity.md +1 -1
  60. package/docs/reference/plugin-context.md +5 -0
  61. package/docs/reference/plugin-guard.md +14 -6
  62. package/docs/reference/plugin-learn.md +13 -6
  63. package/docs/reference/troubleshoot-hooks.md +3 -3
  64. package/docs/reference/troubleshoot-update.md +14 -0
  65. package/docs/token-footprint.md +4 -3
  66. package/docs/understand/a-day.md +2 -2
  67. package/docs/understand/design-choices-install.md +2 -1
  68. package/docs/understand/enforced-vs-asked.md +4 -3
  69. package/docs/understand/machine-bob.md +3 -1
  70. package/docs/understand/machine-claude.md +7 -5
  71. package/docs/understand/machine-opencode.md +7 -5
  72. package/docs/understand/on-your-machine.md +4 -0
  73. package/docs/understand/take-it-out.md +1 -1
  74. package/docs/web-ui.md +141 -73
  75. package/harness.config.json +1 -1
  76. package/js/README.md +10 -6
  77. package/js/build/args.mjs +10 -8
  78. package/js/build/bundle.mjs +11 -13
  79. package/js/build/driver.mjs +66 -65
  80. package/js/build/emit-claude.mjs +22 -16
  81. package/js/build/emit-common.mjs +4 -5
  82. package/js/build/emit-opencode.mjs +22 -22
  83. package/js/build/fold.mjs +515 -0
  84. package/js/build/generate.mjs +41 -52
  85. package/js/build/render.mjs +115 -29
  86. package/js/build/source.mjs +4 -1
  87. package/js/build/stubs.mjs +70 -9
  88. package/js/build/version.mjs +10 -10
  89. package/js/cli-table.json +23 -83
  90. package/js/hosts/activity.mjs +2 -2
  91. package/js/hosts/geneseed-dir.mjs +1 -1
  92. package/js/hosts/hooks-context.mjs +410 -99
  93. package/js/hosts/hooks-done.mjs +97 -31
  94. package/js/hosts/hooks-learn.mjs +38 -7
  95. package/js/hosts/hooks-prims.mjs +69 -2
  96. package/js/hosts/hooks.mjs +300 -64
  97. package/js/hosts/hosts.mjs +150 -51
  98. package/js/hosts/installs.mjs +55 -167
  99. package/js/hosts/link.mjs +3 -5
  100. package/js/hosts/mcp.mjs +1 -1
  101. package/js/hosts/memory-files.mjs +219 -17
  102. package/js/hosts/ownership-gate.mjs +1 -1
  103. package/js/hosts/settings.mjs +18 -13
  104. package/js/hosts/shim.mjs +4 -33
  105. package/js/hosts/store-watch.mjs +189 -0
  106. package/js/inspect/checks-authoring.mjs +3 -3
  107. package/js/inspect/checks-build.mjs +45 -18
  108. package/js/inspect/checks-counts.mjs +4 -4
  109. package/js/inspect/checks-repo.mjs +13 -14
  110. package/js/inspect/cost.mjs +24 -2
  111. package/js/inspect/diff.mjs +123 -123
  112. package/js/inspect/doctor.mjs +22 -27
  113. package/js/inspect/excludes.mjs +181 -62
  114. package/js/inspect/inventory.mjs +22 -27
  115. package/js/inspect/registry.mjs +106 -30
  116. package/js/inspect/scan.mjs +5 -5
  117. package/js/inspect/status.mjs +141 -119
  118. package/js/inspect/validate.mjs +22 -24
  119. package/js/lib/fs.mjs +47 -50
  120. package/js/lib/json.mjs +10 -17
  121. package/js/lib/machine-dir.mjs +73 -0
  122. package/js/lib/paths.mjs +22 -33
  123. package/js/lib/proc.mjs +1 -1
  124. package/js/lib/prompt.mjs +19 -27
  125. package/js/lib/text.mjs +8 -12
  126. package/js/lib/udiff.mjs +11 -15
  127. package/js/loop/catalog.mjs +2 -3
  128. package/js/loop/state.mjs +15 -5
  129. package/js/maintain/memory.mjs +17 -17
  130. package/js/maintain/migrate.mjs +79 -89
  131. package/js/maintain/setup.mjs +43 -32
  132. package/js/maintain/uninstall.mjs +43 -61
  133. package/js/maintain/update.mjs +200 -93
  134. package/js/ui/anim.mjs +21 -35
  135. package/js/ui/cli.mjs +36 -58
  136. package/js/ui/menu.mjs +22 -45
  137. package/js/ui/tui.mjs +27 -67
  138. package/js/web/actions.mjs +38 -38
  139. package/js/web/api.mjs +132 -76
  140. package/js/web/catalog.mjs +175 -46
  141. package/js/web/docs.mjs +33 -12
  142. package/js/web/doctor-worker.mjs +14 -0
  143. package/js/web/handler.mjs +14 -5
  144. package/js/web/routes.mjs +17 -19
  145. package/js/web/state.mjs +78 -19
  146. package/js/web/update-check.mjs +25 -10
  147. package/js/web/user-files.mjs +50 -105
  148. package/package.json +7 -4
  149. package/registry.json +48 -55
  150. package/src/AGENT.md.tmpl +13 -14
  151. package/src/agents/_self-improvement.md +1 -1
  152. package/src/agents/_template.md +4 -1
  153. package/src/agents/advocate.md +1 -1
  154. package/src/agents/architect.md +1 -1
  155. package/src/agents/developer.md +6 -3
  156. package/src/agents/devops-engineer.md +1 -1
  157. package/src/agents/docker-expert.md +1 -1
  158. package/src/agents/docs.md +1 -1
  159. package/src/agents/empiricist.md +1 -1
  160. package/src/agents/explorer.md +1 -1
  161. package/src/agents/framer.md +1 -1
  162. package/src/agents/historian.md +1 -1
  163. package/src/agents/kubernetes-specialist.md +1 -1
  164. package/src/agents/memory-curator.md +2 -2
  165. package/src/agents/operator.md +1 -1
  166. package/src/agents/performance.md +1 -1
  167. package/src/agents/pragmatist.md +1 -1
  168. package/src/agents/react-engineer.md +1 -1
  169. package/src/agents/react-reviewer.md +1 -1
  170. package/src/agents/researcher.md +1 -1
  171. package/src/agents/reviewer.md +1 -1
  172. package/src/agents/security.md +1 -1
  173. package/src/agents/skeptic.md +1 -1
  174. package/src/agents/spring-boot-engineer.md +1 -1
  175. package/src/agents/spring-reviewer.md +1 -1
  176. package/src/agents/spring-security.md +1 -1
  177. package/src/agents/steward.md +1 -1
  178. package/src/agents/tester.md +5 -2
  179. package/src/agents/user-advocate.md +1 -1
  180. package/src/agents/visionary.md +1 -1
  181. package/src/bricks/apply.md +3 -0
  182. package/src/bricks/test.md +6 -4
  183. package/src/loops/bugfix.json +11 -5
  184. package/src/loops/feature.json +7 -4
  185. package/src/memory/README.md +1 -1
  186. package/src/skills/_self-improvement.md +2 -2
  187. package/src/skills/daydream/SKILL.md +2 -2
  188. package/src/skills/daydream/instructions.md +1 -1
  189. package/src/skills/geneseed.md +1 -1
  190. package/src/skills/learn-mode.md +1 -2
  191. package/src/skills/loop.md +1 -0
  192. package/src/skills/profile.md +2 -2
  193. package/src/skills/rule/approve.md +69 -0
  194. package/src/skills/rule/consolidate.md +3 -3
  195. package/src/skills/rule.md +13 -5
  196. package/src/skills/ship.md +9 -1
  197. package/src/skills/skill-forge.md +1 -1
  198. package/src/skills/teach.md +29 -12
  199. package/src/skills/wiki.md +1 -1
  200. package/themes/_TEMPLATE.json +1 -2
  201. package/themes/biker.json +1 -2
  202. package/themes/commentator.json +1 -2
  203. package/themes/cyberpunk.json +1 -2
  204. package/themes/gamer.json +1 -2
  205. package/themes/imperial.json +1 -2
  206. package/themes/joker.json +1 -2
  207. package/themes/marvin.json +1 -2
  208. package/themes/mean.json +1 -2
  209. package/themes/military.json +1 -2
  210. package/themes/neutral.json +1 -2
  211. package/themes/pirate.json +1 -2
  212. package/themes/sports.json +1 -2
  213. package/themes/verstappen.json +1 -2
  214. package/themes/wizard.json +1 -2
  215. package/web/dist/assets/Activity-D8G4eClY.js +1 -0
  216. package/web/dist/assets/ActivityDetail-BtOBYk3M.js +1 -0
  217. package/web/dist/assets/AgentGlyph-k6o3gCM1.js +1 -0
  218. package/web/dist/assets/Bonsai-B_y20b3i.js +1 -0
  219. package/web/dist/assets/{CopyButton-IXnXzH4Y.js → CopyButton-CHQte7Ap.js} +1 -1
  220. package/web/dist/assets/Dashboard-B8uXeJZ_.js +2 -0
  221. package/web/dist/assets/{DataTable-BWbUx4bY.js → DataTable-b9zTShqJ.js} +1 -1
  222. package/web/dist/assets/Docs-Dgv_MWfT.js +5 -0
  223. package/web/dist/assets/{EmptyState-1sPNleqv.js → EmptyState-CY5Pm2xy.js} +1 -1
  224. package/web/dist/assets/FilterInput-qGKNSlxv.js +1 -0
  225. package/web/dist/assets/GreenhouseView-CSzTMSl_.js +1 -0
  226. package/web/dist/assets/Installs-BDk9lqBI.js +3 -0
  227. package/web/dist/assets/JournalView-CvRk1-m5.js +1 -0
  228. package/web/dist/assets/Kits-CoITzxWM.js +1 -0
  229. package/web/dist/assets/Laws-Ctf5r9rE.js +3 -0
  230. package/web/dist/assets/Library-DNwHYVXt.js +3 -0
  231. package/web/dist/assets/{Loops-C5u7fQOR.js → Loops-S85PMQ8m.js} +2 -2
  232. package/web/dist/assets/Markdown-0ORz7tAc.js +69 -0
  233. package/web/dist/assets/OperatorHudView-DuGz_sTk.js +1 -0
  234. package/web/dist/assets/Personal-afJNwvRS.js +2 -0
  235. package/web/dist/assets/RailCats-AW92uhsX.js +1 -0
  236. package/web/dist/assets/Settings-CGDFz-6j.js +1 -0
  237. package/web/dist/assets/Tabs-1qLrnqmn.js +1 -0
  238. package/web/dist/assets/api-C46vAuqp.js +1 -0
  239. package/web/dist/assets/controls-D4wmg_pl.js +1 -0
  240. package/web/dist/assets/index-COTd4TRZ.js +3 -0
  241. package/web/dist/assets/index-CtorA7uK.css +1 -0
  242. package/web/dist/assets/motion-RlUl1osO.js +1 -0
  243. package/web/dist/assets/react-C1iE8mnY.js +9 -0
  244. package/web/dist/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  245. package/web/dist/assets/{sections-ChwaobfW.js → sections-CtFz7HFH.js} +1 -1
  246. package/web/dist/assets/{usePoll-bDFN-Hr6.js → usePoll-o8ul-Sog.js} +1 -1
  247. package/web/dist/index.html +7 -7
  248. package/src/skills/quiz.md +0 -44
  249. package/web/dist/assets/Activity-B7cFtS00.js +0 -1
  250. package/web/dist/assets/ActivityDetail-C-GbMmuW.js +0 -1
  251. package/web/dist/assets/Bonsai-_YyexVC5.js +0 -1
  252. package/web/dist/assets/Dashboard-sCfEjowQ.js +0 -2
  253. package/web/dist/assets/Docs-w3Y7M5Ts.js +0 -5
  254. package/web/dist/assets/FilterInput-CZREvrjX.js +0 -1
  255. package/web/dist/assets/GreenhouseView-BWWbMKmg.js +0 -1
  256. package/web/dist/assets/Installs-CnkdJ-VA.js +0 -3
  257. package/web/dist/assets/JournalView-C7bPD3fZ.js +0 -1
  258. package/web/dist/assets/KitApply-CQQbnThf.js +0 -1
  259. package/web/dist/assets/Kits-aj07N7mT.js +0 -1
  260. package/web/dist/assets/Laws-DZ38nl_H.js +0 -3
  261. package/web/dist/assets/Library-QCGXPV5h.js +0 -2
  262. package/web/dist/assets/Markdown-DpmmtW2Y.js +0 -65
  263. package/web/dist/assets/OperatorHudView-Blu1lqiZ.js +0 -1
  264. package/web/dist/assets/Personal-ox_MktWO.js +0 -2
  265. package/web/dist/assets/RailCats-BuJD4Jou.js +0 -1
  266. package/web/dist/assets/Tabs-CIPyMAX-.js +0 -1
  267. package/web/dist/assets/api-BxjLd7Qd.js +0 -1
  268. package/web/dist/assets/index-0GCxkY7m.css +0 -1
  269. package/web/dist/assets/index-CzDi9JpF.js +0 -3
  270. package/web/dist/assets/motion-CXaUMNkg.js +0 -1
  271. package/web/dist/assets/react-DlYQp10C.js +0 -9
  272. package/web/dist/assets/rolldown-runtime-hePW80VL.js +0 -1
package/js/lib/fs.mjs CHANGED
@@ -1,22 +1,17 @@
1
1
  /**
2
2
  * Reading and writing — files on disk, and the two process streams.
3
3
  *
4
- * These are definitions, not an adaptation of somebody else's. Every rule below was
5
- * originally MEASURED against CPython, because the generator these functions serve had to
6
- * emit bytes indistinguishable from a Python one; that second party is gone and the rules
7
- * are not. The recorded corpora that compared this module's output byte for byte went with
8
- * the former Python suite; what holds the rules now is `tests/unit/lib_primitives.test.mjs`
9
- * (`isFile`/`isDir`), `tests/unit/hook_cli.test.mjs`'s platform-newline count (the stream
10
- * funnels), and for the rest only the per-function provenance below. A rule here is still a
11
- * frozen fact about what this tool emits, and changing one is a product change.
4
+ * These are definitions, not an adaptation of somebody else's. What holds the rules is
5
+ * `tests/unit/lib_primitives.test.mjs` (`isFile`/`isDir`),
6
+ * `tests/unit/hook_cli.test.mjs`'s platform-newline count (the stream funnels), and for the
7
+ * rest only the per-function notes below. A rule here is a frozen fact about what this tool
8
+ * emits, and changing one is a product change.
12
9
  *
13
10
  * ⚠ NONE OF THESE IS THE NODE DEFAULT, AND THAT IS THE ONE THING TO KNOW BEFORE EDITING ONE.
14
11
  * Each is a deliberate divergence from the obvious one-liner, and the obvious one-liner is
15
- * wrong here in a way no test in this repository would tell you about pleasantly. These names
16
- * carried a `py` prefix until the prefix was retired, precisely to say so; the warning now
17
- * lives where it belongs, in the per-function comment naming WHAT WAS MEASURED and against
18
- * what. That provenance is the only surviving record of why a rule has the shape it has, and
19
- * it is the first thing to read before touching one.
12
+ * wrong here in a way no test in this repository would tell you about pleasantly. The
13
+ * per-function comment says what the rule is and why it has that shape; it is the first thing
14
+ * to read before touching one.
20
15
  *
21
16
  * In this module the divergence is `os.linesep`: every write translates `\n` to the platform's
22
17
  * separator, and `printOut`/`printErr` do the same on the way to the console.
@@ -29,7 +24,7 @@
29
24
  */
30
25
  import {
31
26
  appendFileSync, writeFileSync, readFileSync, copyFileSync, statSync, utimesSync,
32
- openSync, fstatSync, readSync, closeSync,
27
+ openSync, fstatSync, readSync, closeSync, renameSync,
33
28
  } from 'node:fs';
34
29
  import { EOL } from 'node:os';
35
30
  import { resolve } from 'node:path';
@@ -58,17 +53,14 @@ export function withWriteRecord(fn) {
58
53
  /**
59
54
  * `Path.write_text(text, encoding="utf-8")`.
60
55
  *
61
- * Python opens that file in TEXT mode with `newline=None`, so every `\n` is translated
62
- * to `os.linesep` on the way out — a freshly emitted AGENT.md is 504 CRLF and 0 bare LF
63
- * on Windows. `fs.writeFileSync` translates nothing. Without this wrapper *every* text
64
- * file the port emits differs from Python's on Windows, and the byte-identity gate that
65
- * is the whole acceptance test of the port yields exactly zero signal: it reports 100%
66
- * failure whether the render is right or wrong.
56
+ * Text mode: every `\n` is translated to `os.linesep` on the way out — a freshly emitted
57
+ * AGENT.md is 504 CRLF and 0 bare LF on Windows. `fs.writeFileSync` translates nothing, so
58
+ * without this wrapper *every* text file the tool emits would be LF on Windows.
67
59
  *
68
60
  * Two categories must NOT go through here, and they are the reason this is a named
69
61
  * function rather than a blanket rule:
70
- * - the hook shim, which Python writes with `newline=""` (raw);
71
- * - anything Python copies with `shutil.copy2` (the OpenCode `plugins/*.js` and the
62
+ * - the hook shim, which is written raw;
63
+ * - anything copied with `copyFile` (the OpenCode `plugins/*.js` and the
72
64
  * vendored skill folders), which is a byte copy and keeps its LF.
73
65
  * The same vendored skill folder can contain files from both categories.
74
66
  */
@@ -81,6 +73,18 @@ export function writeText(path, text) {
81
73
  }
82
74
  }
83
75
 
76
+ /**
77
+ * `writeText` through a temp file and a rename, for a file two processes may rewrite at once (the
78
+ * memory index, which two hosts can rebuild together). A reader sees the old file or the new one,
79
+ * never half of one. A crash leaves a `.tmp` beside it, which no `*.md` glob lists and the next
80
+ * write by the same pid overwrites.
81
+ */
82
+ export function writeTextAtomic(path, text) {
83
+ const tmp = `${path}.${process.pid}.tmp`;
84
+ writeText(tmp, text);
85
+ renameSync(tmp, path);
86
+ }
87
+
84
88
  /**
85
89
  * `path.open("a", encoding="utf-8").write(text)` — the APPEND half of the rule above.
86
90
  *
@@ -98,7 +102,7 @@ export function appendText(path, text) {
98
102
  /**
99
103
  * `Path.read_text(encoding="utf-8")`.
100
104
  *
101
- * Python decodes text files in universal-newlines mode: `\r\n` and a lone `\r` both
105
+ * Text files are decoded in universal-newlines mode: `\r\n` and a lone `\r` both
102
106
  * become `\n` before any regex ever sees them. Node hands back the bytes as-is. The
103
107
  * repo's `.gitattributes` normalises `src/` to LF so today this is a no-op, but a
104
108
  * checkout with `core.autocrlf=true`, a copied tree, or an editor that rewrote one file
@@ -161,7 +165,7 @@ export function readTail(path, bytes) {
161
165
  * Deliberate deviation: `copy2` copies the permission bits too (`copymode`), which on
162
166
  * Windows means the read-only attribute. Reproducing that would make a second emit fail
163
167
  * to overwrite its own output if a source file were ever marked read-only — a failure
164
- * mode the Python side has and nothing depends on. Mode is not copied here.
168
+ * mode and nothing depends on it. Mode is not copied here.
165
169
  */
166
170
  export function copyFile(src, dest) {
167
171
  textWrites.map?.delete(resolve(dest));
@@ -171,20 +175,18 @@ export function copyFile(src, dest) {
171
175
  }
172
176
 
173
177
  /**
174
- * `print()` — the two output funnels, with Python's newline translation reproduced.
178
+ * The two output funnels, with text-mode newline translation.
175
179
  *
176
180
  * The STREAM twin of `writeText` above, and it lives beside it because it is the same rule:
177
- * `sys.stdout` is a TextIOWrapper with `newline=None`, so on Windows every `\n` a CLI prints
178
- * leaves the process as `\r\n` — and `harness.py`'s `reconfigure(encoding="utf-8")` changes
179
- * the encoding only, not that. `process.stdout` translates nothing, so a Node CLI would hand
180
- * its caller different BYTES than the Python one: measured at 176 vs 171 for one `context`
181
- * run before this existed.
181
+ * on Windows every `\n` a CLI prints leaves the process as `\r\n`. `process.stdout`
182
+ * translates nothing, so without this a Node CLI would hand its caller different BYTES: 171
183
+ * where 176 are expected for one `context` run.
182
184
  *
183
185
  * The CLI matrix structurally cannot see the difference — every cell decodes stdout with
184
186
  * universal newlines, folding both shapes to `\n` before anything compares them. So the gate
185
187
  * for it is `tests/unit/hook_cli.test.mjs`'s `every newline the entry points write is the
186
- * platform's`, which counts raw bytes. Moved here
187
- * from `js/hosts/hooks.mjs` in P5c, when `js/inspect/excludes.mjs` became the second caller: a translation
188
+ * platform's`, which counts raw bytes. It lives here, not in `js/hosts/hooks.mjs`,
189
+ * because `js/inspect/excludes.mjs` is a second caller: a translation
188
190
  * that exists twice is a translation that can be fixed once.
189
191
  */
190
192
  const xlate = (s) => (EOL === '\n' ? s : s.replaceAll('\n', EOL));
@@ -194,15 +196,12 @@ export const printErr = (s) => process.stderr.write(xlate(s));
194
196
  /**
195
197
  * Hold `fn`'s stderr, and emit it only if `fn` RETURNS.
196
198
  *
197
- * The reproduction of `except SystemExit` for a port that writes its refusal at the raise
198
- * site (`js/build/generate.mjs`'s `sysExit` docblock states the convention). `sys.exit(msg)`
199
- * attaches the message to the EXCEPTION and the interpreter prints it on the way out, so a
200
- * Python caller that catches sees no output at all — which makes write-at-the-raise-site
201
- * identical for every caller that lets the throw propagate, and wrong for every caller that
202
- * catches.
199
+ * For code that writes its refusal at the raise site (`js/build/generate.mjs`'s `sysExit`
200
+ * docblock states the convention). That is right for every caller that lets the throw
201
+ * propagate, and wrong for every caller that catches: the message is already out.
203
202
  *
204
- * MOVED HERE beside `printErr`, whose writes it intercepts, when the hook became the
205
- * second and third such caller: `js/hosts/hosts.mjs`'s `expanduser` refuses a `~user` path by
203
+ * It lives beside `printErr`, whose writes it intercepts. `js/hosts/hosts.mjs`'s
204
+ * `expanduser` refuses a `~user` path by
206
205
  * printing and throwing, and `js/hosts/hooks.mjs` catches it twice — once per `excludes.json`
207
206
  * entry and once around `$GENESEED_ROOT`/`--root`. Its old docblock in `js/inspect/doctor.mjs`
208
207
  * warned that a general helper "would invite a second caller that wanted silence the
@@ -226,27 +225,25 @@ export function withDiscardableStderr(fn) {
226
225
 
227
226
  /**
228
227
  * The same rule applied to a whole CALL rather than to one string — `bin/build-driver.mjs`'s
229
- * answer to the newline item P5e recorded and could not gate.
228
+ * answer to newlines it cannot gate cell by cell.
230
229
  *
231
230
  * WHY THE DRIVER NEEDS A FUNNEL WHERE EVERY OTHER CALLER NEEDS `printOut`. The generator
232
231
  * prints from ~25 sites across `bin/build-driver.mjs`, `js/build/bundle.mjs`, `js/hosts/settings.mjs`,
233
- * `js/hosts/opencode.mjs`, `js/hosts/native.mjs` and `js/build/render.mjs`, and those modules are ALSO the
234
- * body of what used to be a seam child, whose `main` buffered both streams and handed them
235
- * to a Python parent that re-printed them through `print()`. Converting those sites to
236
- * `printOut` would have translated once in Node and again in Python — `\r\r\n` on every line.
237
- * So the translation belongs to whichever process OWNS the stream, and that child did not.
232
+ * `js/hosts/opencode.mjs`, `js/hosts/native.mjs` and `js/build/render.mjs`. Converting those
233
+ * sites to `printOut` would translate once per layer that re-prints the output, and a second
234
+ * translation turns `\r\n` into `\r\r\n` on every line. So the translation belongs to
235
+ * whichever process OWNS the stream.
238
236
  * This wraps the driver's `main`, and equally the four render entry points the CLI can reach
239
237
  * WITHOUT `main` on the stack: `parseDriverArgs`, `buildInto`, `emitProjectInto` and
240
238
  * `emitGlobalInto`.
241
239
  *
242
- * The item it closes: a plain `--emit files` handed its caller 104 bytes where `python
243
- * build.py` handed over 105, and a `text=True` capture folds both to the same string.
240
+ * What it closes: a plain `--emit files` handed its caller 104 bytes where 105 are expected,
241
+ * and a text-mode capture folds both to the same string.
244
242
  * `tests/unit/hook_cli.test.mjs`'s newline test carries a `build` row (through `geneseed
245
243
  * build`, which calls this `main` in-process), and that is what can see it.
246
244
  *
247
245
  * A Buffer chunk passes through untouched: `writeText` owns file bytes and nothing on this
248
- * path writes binary to a stream, so translating one would be corrupting data rather than
249
- * reproducing Python.
246
+ * path writes binary to a stream, so translating one would be corrupting data.
250
247
  */
251
248
  export function withPlatformNewlines(fn) {
252
249
  if (EOL === '\n') return fn();
package/js/lib/json.mjs CHANGED
@@ -2,9 +2,8 @@
2
2
  * Quoting and the parsed-value model — `json.dumps`, `json.loads`, and the `str`/`repr`
3
3
  * rules that decide what a parsed number renders as.
4
4
  *
5
- * These are definitions, not an adaptation of somebody else's; see `fs.mjs` for why the
6
- * measurements against CPython are recorded per function, and why NONE of these is the Node
7
- * default — the warning the retired `py` prefix used to carry now lives in each docblock.
5
+ * These are definitions, not an adaptation of somebody else's, and NONE of these is the
6
+ * Node default — each docblock says why.
8
7
  * A rule here is a frozen fact about what this tool emits — the written-out tables in
9
8
  * `tests/unit/lib_primitives.test.mjs` and `tests/unit/settings_jsonc.test.mjs` pin it.
10
9
  *
@@ -20,9 +19,8 @@
20
19
  * and `String(1.0)` is `"1"` — so an `agent-overrides.json` carrying `"temperature": 1.0`
21
20
  * emits `temperature: 1.0` from Python and `temperature: 1` from Node.
22
21
  *
23
- * That divergence WAS invisible to the golden harness — the emit always writes an EMPTY
24
- * overrides stub, so no golden cell ever had an override to render, and mutation M6 stood
25
- * ungated for two phases because of it. What holds it now is
22
+ * That divergence is invisible to the golden harness — the emit always writes an EMPTY
23
+ * overrides stub, so no golden cell has an override to render. What holds it is
26
24
  * `tests/unit/lib_primitives.test.mjs`, which round-trips `{"temperature": 1.0}` and requires
27
25
  * the `1.0` back.
28
26
  */
@@ -304,9 +302,8 @@ function escapeNonAscii(text) {
304
302
  *
305
303
  * Indentation is what makes this tractable: passing `indent` switches Python's
306
304
  * separators from `(', ', ': ')` to `(',', ': ')`, which is exactly what
307
- * `JSON.stringify(v, null, 2)` emits. Verified rather than argued \u2014
308
- * the former Python suite compared both variants against Python over a corpus of container
309
- * shapes; `tests/unit/lib_primitives.test.mjs` now pins only this writer's number spellings.
305
+ * `JSON.stringify(v, null, 2)` emits. `tests/unit/lib_primitives.test.mjs` pins this
306
+ * writer's number spellings.
310
307
  */
311
308
  export function jsonDumpsIndent(value, { ensureAscii = true } = {}) {
312
309
  const text = JSON.stringify(value, null, 2);
@@ -316,10 +313,8 @@ export function jsonDumpsIndent(value, { ensureAscii = true } = {}) {
316
313
  /**
317
314
  * `json.dumps(obj)` and `json.dumps(obj, sort_keys=True)` — the COMPACT container form.
318
315
  *
319
- * Deferred through three phases because guessing its signature would have been worse than
320
- * not having it; `js/hosts/settings.mjs` is the code that finally needs it, and the shapes were
321
- * counted with `ast` rather than assumed: four bare `json.dumps(container)` and two
322
- * `sort_keys=True`, all inside `_build_settings.py`, none of them `ensure_ascii=False`.
316
+ * `js/hosts/settings.mjs` is the code that needs it: bare containers and `sort_keys`
317
+ * output, none of them `ensure_ascii=False`.
323
318
  *
324
319
  * It cannot delegate to `JSON.stringify` the way `jsonDumpsIndent` does. Without an indent
325
320
  * Python's separators are `(', ', ': ')` — `{"a": 1, "b": [1, 2]}` where `JSON.stringify`
@@ -378,10 +373,8 @@ function compactImpl(v, sortKeys, bareInts) {
378
373
  /**
379
374
  * `_build_settings._read_jsonc` — an EXPORTED PRIMITIVE, deliberately.
380
375
  *
381
- * Four runtime call sites use it as a plain JSONC parser rather than as wiring, all four
382
- * in `rituals/_harness_mcp.py` (P1b counted the call sites and named them callers; they
383
- * are one module). Folding it inside a wire entry point would leave those four with
384
- * nothing to call.
376
+ * Four runtime call sites use it as a plain JSONC parser rather than as wiring. Folding it
377
+ * inside a wire entry point would leave them with nothing to call.
385
378
  *
386
379
  * Returns `[data, hadComments]`, with `data === null` for UNPARSEABLE input — distinct
387
380
  * from a legitimately empty `{}`, because writers must refuse to rewrite a file they could
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The machine-wide Geneseed directory: `$XDG_CONFIG_HOME/geneseed`, default `~/.config/geneseed`.
3
+ *
4
+ * ONE WRITER PER VALUE. The install registry, the user loop bricks and the shared tier all live
5
+ * under this directory; each used to spell the XDG computation itself, and a spelling that drifts
6
+ * in one place sends that file to a different directory than its neighbours. This module is the
7
+ * only home of the computation and of the names beneath it.
8
+ *
9
+ * Builtins only and no spawn: the hook and the build driver may import it, and both are under a
10
+ * `child_process` ban. `process.env` is read at CALL time, so a sandbox that sets
11
+ * `XDG_CONFIG_HOME` after import is honoured.
12
+ */
13
+ import { readFileSync } from 'node:fs';
14
+ import os from 'node:os';
15
+ import path from 'node:path';
16
+
17
+ /**
18
+ * The wiki manifest's names, newest first. The last two are earlier seeds', read with no end date:
19
+ * nothing yet tells a user an install missed the rename, so dropping one would lose a wiki in
20
+ * silence. The OpenCode plugins carry a copy (tests/unit/claude.test.mjs holds the context one equal).
21
+ */
22
+ export const WIKI_NAMES = ['geneseed-wiki.jsonc', 'wiki.jsonc', 'wiki.json'];
23
+
24
+ /**
25
+ * SHA-256 of the wiki seed before the `geneseed-` rename, CRLF folded. No stub produces it any
26
+ * more, and the build renames an untouched one byte for byte, so it is still a seed on disk.
27
+ */
28
+ export const LEGACY_WIKI_SEED = 'cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8';
29
+
30
+ /** Where the self-improvement loops write, relative to a notes root. */
31
+ export const NOTES_DIRS = ['skill-notes', 'agent-notes'];
32
+
33
+ export function machineDir() {
34
+ const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
35
+ return path.join(base, 'geneseed');
36
+ }
37
+
38
+ /**
39
+ * The tier's root as a render spells it: `/`-separated on every platform, as a global Bob skill
40
+ * pointer is, so a doctor can compare strings. null when the account has no home directory.
41
+ */
42
+ export function renderedSharedRoot() {
43
+ try { return machineDir().split(path.sep).join('/'); } catch { return null; }
44
+ }
45
+
46
+ /** Every file or directory the machine tier names, resolved under `machineDir()`. */
47
+ export function sharedPaths() {
48
+ const root = machineDir();
49
+ return {
50
+ root,
51
+ memory: path.join(root, 'memory'),
52
+ rules: path.join(root, 'user-rules.md'),
53
+ profile: path.join(root, 'PROFILE.md'),
54
+ wiki: path.join(root, 'geneseed-wiki.jsonc'),
55
+ excludes: path.join(root, 'excludes.json'),
56
+ notes: path.join(root, 'notes'),
57
+ draft: path.join(root, 'user-rules.draft.md'),
58
+ foldState: path.join(root, '.fold-state.json'),
59
+ defaultInstall: path.join(root, 'default-install.json'),
60
+ };
61
+ }
62
+
63
+ /**
64
+ * The install the user chose as the default, `{host, path}`, or null: no pick, or a file that does
65
+ * not read as one. It only says what was chosen; `pickedInstall` (js/inspect/status.mjs) checks it
66
+ * against the installs there are now. A bad file must never break a console or a `status`.
67
+ */
68
+ export function readDefaultInstall() {
69
+ try {
70
+ const { host, path: root } = JSON.parse(readFileSync(sharedPaths().defaultInstall, 'utf8'));
71
+ return typeof host === 'string' && typeof root === 'string' ? { host, path: root } : null;
72
+ } catch { return null; }
73
+ }
package/js/lib/paths.mjs CHANGED
@@ -1,9 +1,8 @@
1
1
  /**
2
2
  * Comparing and locating — how a path is case-folded, ordered, contained, spelled and found.
3
3
  *
4
- * These are definitions, not an adaptation of somebody else's; see `fs.mjs` for why the
5
- * measurements against CPython are recorded per function, and why NONE of these is the Node
6
- * default — the warning the retired `py` prefix used to carry now lives in each docblock.
4
+ * These are definitions, not an adaptation of somebody else's, and NONE of these is the
5
+ * Node default — each docblock says why.
7
6
  * Path semantics are the most PLATFORM-SHAPED rules in the tool — several of these have a
8
7
  * different right answer on Windows and on POSIX, and each says which.
9
8
  */
@@ -21,11 +20,9 @@ const { X_OK } = constants;
21
20
  * compares by code point where JS compares by UTF-16 code unit (differs only above the
22
21
  * BMP), and `str.lower()` is not `toLowerCase()` for a handful of characters.
23
22
  *
24
- * THE SEPARATOR CONVERSION IS NOT OPTIONAL, and it was missing until the byte-bearing
25
- * corpus in the former Python parity suite asked. `ntpath.normcase` is
26
- * `s.replace('/', '\\').lower()`, and `PurePath._str_normcase` gets the same conversion for
27
- * free because `Path` has already done it — so BOTH readings of the reference fold slashes
28
- * and this did not. Every sort call site feeds it `path.join` output or a bare `readdir`
23
+ * THE SEPARATOR CONVERSION IS NOT OPTIONAL. `ntpath.normcase` is
24
+ * `s.replace('/', '\\').lower()`, so slashes fold to the native separator. Every sort call
25
+ * site feeds it `path.join` output or a bare `readdir`
29
26
  * name, which is why no emitted byte ever moved; `fnTranslate(normcase(pattern))` in
30
27
  * `js/hosts/hooks.mjs` is where it was reachable, because an exclude pattern is USER-WRITTEN and
31
28
  * `memory/*` never matched a native `memory\x` the way `fnmatch` does.
@@ -37,7 +34,7 @@ export const normcase = process.platform === 'win32'
37
34
  /**
38
35
  * `sorted()` over paths \u2014 one owner, so two call sites cannot drift apart.
39
36
  *
40
- * COMPONENT-WISE, and that was a flat string compare until P2 measured it. `PurePath.__lt__`
37
+ * COMPONENT-WISE, not a flat string compare. `PurePath.__lt__`
41
38
  * compares `_parts_normcase` \u2014 a TUPLE of path components \u2014 so the separator never takes part
42
39
  * in the comparison, and the two readings disagree in BOTH directions:
43
40
  *
@@ -47,12 +44,11 @@ export const normcase = process.platform === 'win32'
47
44
  * flat cmp : the reverse again
48
45
  *
49
46
  * Nothing in the emitted tree could see it: `js/build/render.mjs` sorts a list whose members share
50
- * a directory depth, and `golden.py` compared CONTENT rather than order. It became visible
51
- * the first time a full path list was PRINTED \u2014 `geneseed validate -v` \u2014 against a real
47
+ * a directory depth, and the golden harness compares CONTENT rather than order. It becomes
48
+ * visible when a full path list is PRINTED \u2014 `geneseed validate -v` \u2014 against a real
52
49
  * skills tree that happens to contain both `skills/geneseed/` and `skills/geneseed-code-review/`.
53
- * The former Python maintainer-tools test found it and died with the reference it compared
54
- * against. What HOLDS it now is `tests/unit/maintainer_tools.test.mjs`, and specifically its
55
- * `theme files are visited in THIS platform's Path collation order` test: it re-derives Python's
50
+ * What HOLDS it is `tests/unit/maintainer_tools.test.mjs`, and specifically its
51
+ * `theme files are visited in THIS platform's Path collation order` test: it re-derives the
56
52
  * `sorted(Path)` order for the running platform instead of replaying a recording, so it cannot
57
53
  * agree with a drift \u2014 and it is the measured killer of this function's mutation (M3).
58
54
  */
@@ -66,12 +62,10 @@ export function comparePaths(a, b) {
66
62
  }
67
63
 
68
64
  /**
69
- * `_harness_core._within` \u2014 containment through `normcase`, segment-wise.
65
+ * Containment through `normcase`, segment-wise.
70
66
  *
71
- * MOVED HERE IN P6i, from `js/web/api.mjs` where P6b first needed it. The Python is a harness
72
- * CORE primitive (`child.relative_to(parent)` in a try/except), and its second caller is
73
- * `_install_move_list` in `js/maintain/uninstall.mjs` \u2014 a CLI-level module that must not import the
74
- * web tree to reach it. Beside `normcase`, which is the thing it is actually about.
67
+ * Its callers include `js/maintain/uninstall.mjs` \u2014 a CLI-level module that must not import the
68
+ * web tree to reach it. It lives beside `normcase`, which is the thing it is actually about.
75
69
  * `js/web/api.mjs` re-exports it so its existing importers are unchanged.
76
70
  *
77
71
  * TRAILING SEPARATORS ARE STRIPPED FROM `parent` FIRST. A root is the one path whose canonical
@@ -90,7 +84,7 @@ export function within(child, parent) {
90
84
  * `Path` is `WindowsPath` on Windows and `PosixPath` everywhere else, and the two parsers
91
85
  * disagree about the two things below. A body that is right on one host is therefore wrong
92
86
  * on the other, which is exactly how this one passed a whole Windows suite and failed two
93
- * cases on the first Linux run of the former Python pure-function parity suite:
87
+ * cases on Linux:
94
88
  *
95
89
  * * SEPARATORS. `ntpath` treats `\` and `/` alike; `posixpath` treats `\` as an ordinary
96
90
  * filename character. `str(PurePosixPath('C:\\x\\bin\\'))` is that string VERBATIM —
@@ -104,8 +98,7 @@ export function within(child, parent) {
104
98
  * NOT reproduced, and named here rather than left as a gap nobody wrote down: `//` and
105
99
  * `///x` on WINDOWS, where `PureWindowsPath` answers `\\` and `\\\x` and this answers `\`
106
100
  * and `\x`. Those are incomplete UNC prefixes and matching them needs ntpath's share-name
107
- * parsing; both inputs were kept OUT of the retired parity corpus instead of sitting in it
108
- * wrong.
101
+ * parsing; both inputs are left alone rather than answered wrong.
109
102
  *
110
103
  * The root's separators are still rewritten ONE AT A TIME, never `replace(/[\\/]+/g, sep)`:
111
104
  * a UNC root's leading pair is part of it, so collapsing runs turns `//server/share/x` into
@@ -126,13 +119,13 @@ export function toPlatformPath(s) {
126
119
  /**
127
120
  * `pathlib.Path(s).is_absolute()`, which is NOT `path.isAbsolute(s)` on Windows.
128
121
  *
129
- * MEASURED against CPython 3.13, and the two disagree on exactly one shape: a ROOTLESS
122
+ * The two disagree on exactly one shape: a ROOTLESS
130
123
  * absolute path. `/x/AGENT.md` and `\x\AGENT.md` are `True` to `path.isAbsolute` and `False`
131
124
  * to Python, which requires a DRIVE (`C:/x`) or a UNC root (`//server/share/x`) before it
132
125
  * calls a Windows path absolute. `C:x/AGENT.md` — a drive-RELATIVE path — is False to both.
133
126
  * On POSIX the two rules coincide and this is `s.startsWith('/')`.
134
127
  *
135
- * Written in P5h for `installAgentEntry`, which filters an OpenCode config's `instructions`
128
+ * Used by `installAgentEntry`, which filters an OpenCode config's `instructions`
136
129
  * for the entries that are NOT absolute in order to tell a project install's relative
137
130
  * `…/AGENT.md` from a global install's absolute one. A hand-edited config naming
138
131
  * `/repo/AGENT.md` is the reachable input: Python keeps that entry and Node would have
@@ -144,11 +137,9 @@ export function toPlatformPath(s) {
144
137
  * and `js/build/bundle.mjs`'s `safePriorDirName` is `&&`-guarded by `basename(p) === p` immediately
145
138
  * after. The two in `js/hosts/hooks.mjs` (a context entry's `path`) DO carry the same hazard and
146
139
  * are deliberately not repointed here: that is the hook entry's shipped behaviour, no
147
- * `context` cell varies it, and changing it in this phase would be an ungated edit to a verb
148
- * that crossed three phases ago. Recorded in the spec's "Still owed" with this reproduction.
140
+ * `context` cell varies it, and changing it would be an ungated edit to a shipped verb.
149
141
  *
150
- * It was gated by a corpus in the retired Python pure-function parity suite; nothing has
151
- * replaced it, and no CLI test can vary the shape.
142
+ * Nothing gates this function directly, and no CLI test can vary the shape.
152
143
  */
153
144
  export function isAbsolutePath(s) {
154
145
  if (process.platform !== 'win32') return s.startsWith('/');
@@ -156,8 +147,7 @@ export function isAbsolutePath(s) {
156
147
  // drive and no root, `/x` has the root and no drive, and neither is absolute. In
157
148
  // `path.parse` terms that is exactly "the root is longer than a bare separator AND ends in
158
149
  // one": `C:` for `C:x`, `\` for `\x`, `C:\` for `C:\x`, `\\srv\share\` for a UNC path.
159
- // The first draft tested `root !== '\\'`, which called `C:x` absolute; the corpus caught
160
- // it on the two drive-relative cases and nothing else would have.
150
+ // Testing `root !== '\\'` alone would call `C:x` absolute.
161
151
  const root = path.parse(s).root;
162
152
  return root.length > 1 && /[\\/]$/.test(root);
163
153
  }
@@ -167,12 +157,11 @@ export function isAbsolutePath(s) {
167
157
  *
168
158
  * `doctor` runs `node --check` over the OpenCode plugins and SKIPS the whole check when node
169
159
  * is not on PATH. `process.execPath` is not that: it is always set, so a port that used it
170
- * would run the check in a world where the reference silently declines to — the divergence a
160
+ * would run the check in a world where it silently declines to — the divergence a
171
161
  * PATH-removal refutation is aimed at, and the reason this is a real lookup rather than one
172
162
  * line of "we are node, we know where node is".
173
163
  *
174
- * The Windows half is the part with behaviour in it, and its suffix rules were MEASURED
175
- * against CPython 3.13 rather than assumed. `PATHEXT` supplies the suffixes, and the
164
+ * The Windows half is the part with behaviour in it. `PATHEXT` supplies the suffixes, and the
176
165
  * returned path carries PATHEXT's OWN SPELLING of the extension rather than the file's
177
166
  * (`zzcmd.CMD` for a `zzcmd.cmd` on disk). An extension already in that set means the command
178
167
  * is spelled in full.
package/js/lib/proc.mjs CHANGED
@@ -20,7 +20,7 @@
20
20
  * CAPTURING SPAWNS ONLY, and the asymmetry is deliberate. The rule was measured on Windows:
21
21
  * a process that sets `STARTF_USESTDHANDLES` only when a stream is redirected gives an
22
22
  * INHERITING child spawned with `CREATE_NO_WINDOW` a fresh hidden console and discards
23
- * everything it prints — `geneseed build > log.txt` wrote an empty file. That was Python's
23
+ * everything it prints — `geneseed build > log.txt` wrote an empty file. That is the
24
24
  * `CREATE_NO_WINDOW` creation flag. Node's `windowsHide` is a different mechanism, and libuv
25
25
  * always passes the handles explicitly, so on an INHERITING spawn it is harmless: the child
26
26
  * writes to the parent's handles. A few inheriting sites set it (`js/hosts/link.mjs`,
package/js/lib/prompt.mjs CHANGED
@@ -1,8 +1,7 @@
1
1
  /**
2
2
  * The line-mode stdin readers — `ask`, `promptLine`, `confirm`, `askChoice` over one `readLine`.
3
3
  *
4
- * MOVED OUT OF `js/maintain/setup.mjs`, which is where the Python's own owner (`_harness_setup`)
5
- * put them, because two callers that are not the wizard need them: `uninstall`'s `confirm` and
4
+ * LIVES HERE rather than in `js/maintain/setup.mjs`, because two callers that are not the wizard need it: `uninstall`'s `confirm` and
6
5
  * the web server's npm prompt. Importing them from `setup.mjs` dragged the whole wizard closure
7
6
  * — the driver, the doctor, the diff exporter — into `uninstall` and `web` for four functions
8
7
  * whose only dependencies are fd 0, `printOut` and `parseIntStrict`.
@@ -16,46 +15,40 @@ import { parseIntStrict } from './text.mjs';
16
15
  const PAUSE = new Int32Array(new SharedArrayBuffer(4));
17
16
 
18
17
  /**
19
- * `_harness_setup._ask` — `input(f"{prompt}{suffix}: ").strip()`, or the default at EOF.
18
+ * `input(f"{prompt}{suffix}: ").strip()`, or the default at EOF.
20
19
  *
21
20
  * WHY IT READS A BYTE AT A TIME. Node has no synchronous line read: `readFileSync(0)` blocks
22
21
  * until EOF rather than until Enter, so a wizard built on it would hang on a real terminal
23
22
  * until the user pressed Ctrl-D. Reading fd 0 one byte at a time to the first `\n` is what
24
- * `input()` does, and it is the only synchronous shape that stops where Enter stops. The
25
- * body arrived in P5h inside `js/maintain/uninstall.mjs`'s `confirm`, moved to `setup` when that
26
- * became the second caller, and lives here now that the callers outnumber the wizard;
27
- * `confirm` is built on it exactly as `_confirm` is built on `_ask` in the Python.
23
+ * a plain line read does, and it is the only synchronous shape that stops where
24
+ * Enter stops. `confirm` is built on it.
28
25
  *
29
- * The EOF branch is the one a piped caller sees, and it agrees with Python by two different
30
- * routes that happen to produce one answer: `input()` RAISES `EOFError` and the `except`
31
- * returns the default, while a zero-length read here leaves `line` empty and `|| dflt` does
32
- * the same. A partial line with no trailing newline is not EOF to either — Python returns
33
- * the characters and so does this.
26
+ * The EOF branch is the one a piped caller sees: a zero-length read leaves `line` empty and
27
+ * `|| dflt` returns the default. A partial line with no trailing newline is not EOF — the
28
+ * characters are returned.
34
29
  *
35
30
  * `.trim()` is `str.strip()` in every case but U+FEFF, which JS counts as whitespace and
36
- * Python does not; that is a standing item of this port and not this function's to settle.
31
+ * `str.strip()` does not; that is a standing item and not this function's to settle.
37
32
  */
38
33
  export function ask(prompt, dflt = '') {
39
34
  const suffix = dflt ? ` [${dflt}]` : '';
40
35
  // `input()` writes its prompt to stdout with no newline — nothing for `printOut` to
41
36
  // translate, and it must NOT gain one.
42
37
  process.stdout.write(`${prompt}${suffix}: `);
43
- // `?? ''` because `readLine` reports EOF-with-nothing-read as null since P6h; `_ask`
44
- // catches `EOFError` and returns the default, which is what the empty string produces
45
- // here through `|| dflt`. The two routes to one answer are the docblock's own point.
38
+ // `?? ''` because `readLine` reports EOF-with-nothing-read as null; the empty string then
39
+ // produces the default through `|| dflt`.
46
40
  const ans = (readLine() ?? '').trim();
47
41
  return ans || dflt;
48
42
  }
49
43
 
50
44
  /**
51
- * `input(prompt)` with EOF told apart from an empty line — `null` where Python RAISES.
45
+ * A prompt with EOF told apart from an empty line — `null` at EOF.
52
46
  *
53
47
  * `ask` above cannot express that difference and does not need to: its EOF and its empty
54
48
  * answer both mean "take the default". `_web_server.serve`'s npm prompt is the first
55
49
  * caller where they differ, and they differ dangerously — `""` is in its accepted set, so
56
50
  * a port that read EOF as an empty line would answer YES to "run npm install now?" on
57
- * every non-interactive run. The reference catches `(EOFError, KeyboardInterrupt)` and
58
- * answers "n"; this returns null so the caller can.
51
+ * every non-interactive run. This returns null so the caller can answer "n".
59
52
  *
60
53
  * No `.trim()`: `input()` does not strip, and both callers strip for themselves.
61
54
  */
@@ -101,34 +94,33 @@ export function readLine(read = readSync) {
101
94
  if (buf[0] !== 0x0d) bytes.push(buf[0]);
102
95
  }
103
96
  // NULL ONLY FOR THE EMPTY EOF, which is the one case `input()` raises on. A partial line
104
- // with no trailing newline is not EOF to Python — it returns the characters — and the
97
+ // with no trailing newline is not EOF — the characters are returned — and the
105
98
  // `bytes.length` test is what keeps that arm returning a string here too.
106
99
  if (eof && bytes.length === 0) return null;
107
100
  return Buffer.from(bytes).toString('utf8');
108
101
  }
109
102
 
110
- /** `_harness_setup._confirm` — `_ask` with a Y/n suffix; the default on an empty answer. */
103
+ /** `_ask` with a Y/n suffix; the default on an empty answer. */
111
104
  export function confirm(prompt, dflt = true) {
112
105
  const ans = ask(`${prompt} (${dflt ? 'Y/n' : 'y/N'})`).toLowerCase();
113
106
  return ans === '' ? dflt : ans[0] === 'y';
114
107
  }
115
108
 
116
109
  /**
117
- * `_harness_setup._ask_choice` — a numbered menu; the chosen KEY, or the default.
110
+ * A numbered menu; the chosen KEY, or the default.
118
111
  *
119
112
  * THREE THINGS ABOUT THE FALLBACK ORDER, all of them observable and none of them obvious:
120
113
  *
121
- * * The key match lives in Python's `except ValueError`, so an answer that PARSES as an
114
+ * * The key match only runs when the answer does not parse, so an answer that PARSES as an
122
115
  * integer never reaches it. `99` against a five-option menu returns the default; it does
123
116
  * not go looking for an option literally named `99`.
124
117
  * * An in-range index wins, a parsed out-of-range index falls to the default, and only an
125
118
  * UNPARSEABLE answer is matched against the keys. `parseIntStrict` is what separates the second
126
119
  * case from the third, and it is not `Number()` — see its own docblock.
127
120
  * * A default that is NOT in `options` falls back to option 1. It is reachable — a deployed
128
- * `.geneseed-theme` can name a theme this checkout no longer ships — and it used to throw,
129
- * mirroring the Python reference's `StopIteration`, which crashed `geneseed setup` before
130
- * its first question. The reference is gone, so there is nothing left to fail in step
131
- * with, and returning a key that is not on the menu would hand the build a stale value.
121
+ * `.geneseed-theme` can name a theme this checkout no longer ships — and throwing would
122
+ * crash `geneseed setup` before its first question. Returning a key that is not on the
123
+ * menu would hand the build a stale value.
132
124
  */
133
125
  export function askChoice(prompt, options, dflt) {
134
126
  if (!options.some(([k]) => k === dflt)) dflt = options[0][0];