@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -32,6 +32,10 @@ One page answers one question, and the question picks the kind (the table is in
32
32
  |---|---|
33
33
  | Where does the round stand, what do I do | status or handoff: `strip`, `actions`, `minimap`, `decisions` |
34
34
  | How does it move, how is it built | `flow`, `architecture` |
35
+ | What differs between two ways of doing it | `compare` |
36
+ | Who calls whom, in what order | `sequence` |
37
+ | Which states, and how it moves between them | `lifecycle` |
38
+ | What is inside what | `tree` |
35
39
  | Which option, and why | `comparison` |
36
40
  | What could we do | `ideaMap` |
37
41
  | How does it work | `explainer` |
@@ -40,7 +44,7 @@ One page answers one question, and the question picks the kind (the table is in
40
44
  | What did we decide | `decisionRecord` |
41
45
  | What changes | `beforeAfter` |
42
46
 
43
- A page holds at most 25 boxes and 40 arrows, and stays under 100 KB; what does not fit is two pages, not one
47
+ A page holds at most 25 boxes and 40 arrows, and stays under 80 KB; what does not fit is two pages, not one
44
48
  dense page. A long explanation is a document (see `docs-writing`), not a page.
45
49
 
46
50
  Done when you can say the question in one sentence and name the kind.
@@ -70,9 +74,18 @@ The rules that make a page worth opening:
70
74
  - **A timeline item has a date and a state**, so a roadmap reads as done, in progress and not started.
71
75
  - **Decisions are one to five forks**, each with a recommended default and the claim it changes.
72
76
  - **No secrets, no private data** in any field: the page is a file others may open.
73
- - **The owner's language is a setting**: when the reply language of the profile is not English, set
74
- `language` and translate the words you need into `chrome` (every key is optional); never invent a label
75
- set the owner did not give. Otherwise leave `chrome` out.
77
+ - **The owner's language is a setting**: the page takes the reply language of the owner's profile (English and
78
+ Vietnamese words are bundled; `language` in the spec overrides it). For any other language, translate the
79
+ words you need into `chrome` (every key is optional); never invent a label set the owner did not give.
80
+ - **The colour is the project's, not yours**: leave `accent` out. The page uses the project's `theme` (config key,
81
+ written into the manifest by `vulcan sync`), else a neutral slate. Give `accent` (and `accentDark`, `accentText`)
82
+ only when you draw a page about another project from outside it. A colour that fails the contrast checks is
83
+ refused, never swapped; state colours (done, waiting, blocked) are fixed and always carry an icon and a word.
84
+ - **Say where a claim comes from.** A box or step that states how the code works carries a `source`
85
+ (`repo`, the full 40-character `commit`, `path`, `lines`) you have read in this session; the page refuses a
86
+ short commit. Explain the words the reader may not know in `terms`, and use each in the page.
87
+ - **Tiles only when the numbers are the point.** A flow or a comparison opens the page with its figure, not with
88
+ a row of tiles.
76
89
 
77
90
  Done when each arrow has a verb and each evidence row has a label you can defend.
78
91
 
@@ -84,7 +97,7 @@ bun x --no-install vulcan visualize .agents/local/tmp/<name>.json --out <name>
84
97
 
85
98
  It validates the spec (shape, limits, unique ids, every arrow and step pointing at a box, one box per cell),
86
99
  escapes all text, applies a policy that allows only the page's own style and script, refuses a page over
87
- 100 KB, and writes `.agents/local/prototypes/<name>.html` whole - a failed spec never replaces the last good
100
+ 150 KB (it warns over 80 KB), and writes `.agents/local/prototypes/<name>.html` whole - a failed spec never replaces the last good
88
101
  page. It prints the path and the checks that ran. Fix every problem it lists and run it again.
89
102
 
90
103
  Done when it prints the path.
@@ -93,10 +106,20 @@ Done when it prints the path.
93
106
 
94
107
  The command cannot see the page. Open it in a browser at 390 px and at 1280 px (a browser tool, or ask the
95
108
  owner to open it) and check: the page does not scroll sideways (at 390 px a figure gives way to a list),
96
- no text is smaller than 12 px, nothing overlaps (arrow labels against boxes), the dark theme is readable,
109
+ no text is smaller than 12 px, nothing overlaps (arrow labels against boxes), both themes are readable (the
110
+ sun and moon switch in the top bar flips them), the page is complete with the script off,
97
111
  hover or focus on a box shows its detail, Next steps through the lit boxes, the **Present** button (or
98
112
  `?present=1`) walks the sections as slides with the arrow keys and Escape leaves, and the console is clean.
99
113
 
114
+ **Cards in a row line up.** Where cards stand side by side (the options of a comparison, tiles, the stepper,
115
+ the branches of an idea map, charts, terms), the same part of every card sits at the same height as in its
116
+ neighbours: the big score, the title, each criterion row, each pro and con, the notes. A badge on one card, a
117
+ label that wraps or a longer list must not push a part of that card lower than its neighbours. The generator
118
+ keeps a slot for every part and shares the rows between the cards of a row (CSS grid with `subgrid`), so a page
119
+ that misaligns is a generator defect: say so, do not hide it by padding the text. In the generator, a new kind
120
+ with repeated cards follows the same rule and is added to the alignment test
121
+ (`visualize-alignment.test.ts`), which measures the offsets in a real browser.
122
+
100
123
  If you could not open it, say "not browser-checked". Never describe a page as checked when only the
101
124
  command ran.
102
125
 
@@ -8,15 +8,19 @@ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSO
8
8
  ## The kinds
9
9
 
10
10
  A page is the sections its spec has, in a fixed order: the banner (title, verdict, state), the tiles, the minimap,
11
- what you need to do and what blocks it, then the flow, the architecture, the comparison, the idea map, the
12
- explainer, the timeline, the findings, the before and after, the decision record, the decisions, the evidence,
13
- the risks, the log and the links. Pick the sections the question needs and leave the rest out:
11
+ what you need to do and what blocks it, then the flow (drawn in the top slab, under the verdict, when there is
12
+ one), the architecture, the compare view, the sequence, the lifecycle, the tree, the comparison, the idea map, the explainer, the timeline, the findings, the before and after, the decision record, the decisions, the evidence,
13
+ the risks, the log, the words of the page (`terms`), the sources and the links. Pick the sections the question needs and leave the rest out:
14
14
 
15
15
  | The page is | Use |
16
16
  |---|---|
17
17
  | A status or a handoff for the owner | `strip`, `actions`, `minimap`, `decisions`, `evidence`, `risks`, `log` |
18
18
  | How something moves | `flow` (boxes on a grid, labelled arrows, numbered steps) |
19
19
  | How a system is built | `architecture` (layers of boxes with links) |
20
+ | What differs between two ways of doing it | `compare` (one figure: edges in both, only in A, only in B) |
21
+ | Who calls whom, in what order | `sequence` (lanes for the participants, one arrow per message) |
22
+ | The states of a thing | `lifecycle` (states, with a start and ends, and what moves it between them) |
23
+ | What is inside what | `tree` (a root with children, up to four levels) |
20
24
  | Options compared, with a pick | `comparison` (scores per criterion, pros and cons, a recommended option) |
21
25
  | A brainstorm | `ideaMap` (a centre and clusters of ideas) |
22
26
  | An idea explained | `explainer` (numbered steps, a small diagram for each) |
@@ -34,7 +38,8 @@ Space, Home, End and Escape, one section per slide; print gives one section afte
34
38
  |---|---|
35
39
  | `schemaVersion` | `1` |
36
40
  | `title` | The takeaway, at most 120 characters |
37
- | `language` | A language code (`en`, `pt-BR`); default `en` |
41
+ | `language` | A language code (`en`, `pt-BR`); default: the reply language of the owner's profile, else `en`. The page's own words are bundled for `en` and `vi` (a regional code such as `vi-VN` picks `vi`); any other language takes its words from `chrome` |
42
+ | `accent`, `accentDark`, `accentText` | Optional six-digit hex colours that override the project's page colour (the `theme` config key, written into the manifest by `vulcan sync`; without one, a neutral slate). Give them only for a page about another project. A colour that fails the contrast checks (text 4.5:1, marks 3:1) is refused, never swapped; with no `accentDark` it is derived by mixing toward white |
38
43
  | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; the banner's colour, icon and word |
39
44
  | `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
40
45
  | `verdict`, `caption` | One sentence the reader can stop at; one line under it |
@@ -63,6 +68,12 @@ minimap words, or `info`) adds a colour, an icon and a word, so the figure can s
63
68
  | `ideaMap` | `center`, and 2 to 8 `branches` of `{ label, items (1 to 6), note? }` |
64
69
  | `explainer` | 1 to 8 `steps` of `{ title, text, diagram? }`; a diagram is `{ type: "row", nodes, arrows? }` (2 to 5 boxes, one arrow label fewer than boxes) or `{ type: "layers", layers }` |
65
70
  | `architecture` | `layers` (up to 5) of `{ label, boxes }`, a box `{ id, label, sub?, state? }`, and `links` of `{ from, to, label? }` between box ids |
71
+ | `compare` | `a` and `b` (the names of the two ways, 24 characters each), `nodes` (2 to 25 of `{ id, label, sublabel?, row, col, kind?, state?, source? }`, shared by both ways), `edges` (1 to 40 of `{ from, to, label, in? }`, `in` one of `both` (default), `a`, `b`), optional `caption`. An edge only in B is drawn heavy and solid with `+`, an edge only in A dotted with `-`, and the legend says the words; at least one edge has to differ, or the spec is refused |
72
+ | `terms` | 1 to 12 of `{ term (40 characters), meaning (200) }`, shown as "Words in this page"; a term that never appears in the rest of the page text is a warning |
73
+ | `source` | On a flow node, a flow step or a compare node: `{ repo, commit, path, lines? }`. `repo` is `owner/name`, `commit` is exactly 40 lowercase hex characters, `path` is relative with no `..`, `lines` is `12` or `12-30`. Shown as `repo@commit:path:lines`, and a "Sources" part lists each source once with what points at it |
74
+ | `sequence` | `participants` (2 to 6 of `{ id, label, sublabel? }`), `messages` (1 to 20 of `{ from, to, label, kind?, note? }`, `kind` one of `call`, `reply`, `async`, in the order they happen), optional `caption` |
75
+ | `lifecycle` | `states` (2 to 10 of `{ id, label, sublabel?, kind? }`, `kind` one of `start`, `normal`, `end`; one start, at least one end), `transitions` (up to 20 of `{ from, to, label }`, the label is the trigger), optional `caption` |
76
+ | `tree` | `root`, a node `{ id, label, sublabel?, state?, children? }` nested up to four levels below the root, at most 25 nodes in all; optional `caption` |
66
77
  | `timeline` | 2 to 20 `items` of `{ date, title, text?, state? }` |
67
78
  | `findings` | `numbers` (`{ value, label, state? }`), `charts`, `callouts` (`{ text, state? }`) |
68
79
  | `decisionRecord` | `context`, 2 to 5 `options` of `{ name, summary, chosen? }`, the `decision`, `consequences` |
@@ -76,7 +87,7 @@ only way to tell parts apart: the legend names them and the values are printed.
76
87
 
77
88
  At most 25 boxes, 40 arrows, 12 steps, 5 decisions and 30 rows per table; grid cells 0 to 9; labels 60
78
89
  characters (an arrow label 20), sentences 300, a box detail 600; 6 tiles, 4 charts, 12 points per chart.
79
- The page is refused over 100 KB and warned over 60 KB; a typical page is 20 to 40 KB, most of it the page's own style.
90
+ The page is refused over 150 KB and warned over 80 KB; a typical page is 30 to 60 KB, most of it the page's own style.
80
91
 
81
92
  ## Two worked specs
82
93
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.8",
3
+ "version": "0.4.9-1",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -44,17 +44,16 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.8",
48
- "@venizia/vulcan-okf": "0.4.8",
47
+ "@venizia/vulcan-atlas": "0.4.9-1",
48
+ "@venizia/vulcan-okf": "0.4.9-1",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
52
52
  "@types/bun": "1.4.3",
53
- "@venizia/dev-configs": "0.4.4",
53
+ "@venizia/dev-configs": "0.4.7-0",
54
54
  "eslint": "10.13.0",
55
55
  "oxlint": "1.89.0",
56
- "oxlint-tsgolint": "7.0.2004",
57
- "typescript": "^6.0.3"
56
+ "oxlint-tsgolint": "7.0.2004"
58
57
  },
59
58
  "engines": {
60
59
  "bun": ">=1.4.4"
@@ -4,52 +4,52 @@ export const ATLAS_BLOCK_END = '<!-- vulcan:atlas:end -->';
4
4
  const START_PREFIX = '<!-- vulcan:atlas:start';
5
5
  const MUST_READ = '## Must read first';
6
6
 
7
- /**
8
- * The guidance every agent that reads AGENTS.md gets, whatever its client drops of the MCP server's
9
- * own text. Rendered from the config, so it is the same for every developer and safe to commit.
10
- */
11
- export const renderAtlasBlock = (opts: { project: string; sources: string[] }): string =>
12
- [
13
- ATLAS_BLOCK_START,
14
- '## Atlas',
15
- '',
16
- `The \`atlas\` MCP server holds the real code and docs of: ${[`${opts.project} (this repository)`, ...opts.sources].join(', ')}.`,
17
- 'Look facts up there before you answer or write from memory (V-P-07):',
18
- '`symbol` before you use an export (signature, import path, source line); `search`, then `get`, for how something works or which convention applies; `version` or `changes` for a release or an upgrade.',
19
- 'A new app or package: ask `presets` which preset and which `vulcan add` command, run it, and never hand-write package.json, tsconfig or scripts.',
20
- 'How to build something here (a feature, a controller, a service, a repository): `search` first, then `get`, before you answer; a plan never says "check atlas" for a step you have not done.',
21
- ATLAS_BLOCK_END,
22
- '',
23
- ].join('\n');
24
-
25
- /**
26
- * Puts the block into AGENTS.md: rewritten between its markers when it is there, else inserted
27
- * before the section that follows "Must read first", else appended. Text outside is never touched.
28
- */
29
- export const mergeAtlasBlock = (opts: {
30
- text: string;
31
- block: string;
32
- }): { changed: boolean; text: string } => {
33
- const start = opts.text.indexOf(START_PREFIX);
34
- const end = opts.text.indexOf(ATLAS_BLOCK_END);
35
- let text: string;
7
+ export class AtlasBlock {
8
+ /**
9
+ * The guidance every agent that reads AGENTS.md gets, whatever its client drops of the MCP server's
10
+ * own text. Rendered from the config, so it is the same for every developer and safe to commit.
11
+ */
12
+ static render(opts: { project: string; sources: string[] }): string {
13
+ return [
14
+ ATLAS_BLOCK_START,
15
+ '## Atlas',
16
+ '',
17
+ `The \`atlas\` MCP server holds the real code and docs of: ${[`${opts.project} (this repository)`, ...opts.sources].join(', ')}.`,
18
+ 'Look facts up there before you answer or write from memory (V-P-07):',
19
+ '`symbol` before you use an export (signature, import path, source line); `search`, then `get`, for how something works or which convention applies; `version` or `changes` for a release or an upgrade.',
20
+ 'A new app or package: ask `presets` which preset and which `vulcan add` command, run it, and never hand-write package.json, tsconfig or scripts.',
21
+ 'How to build something here (a feature, a controller, a service, a repository): `search` first, then `get`, before you answer; a plan never says "check atlas" for a step you have not done.',
22
+ ATLAS_BLOCK_END,
23
+ '',
24
+ ].join('\n');
25
+ }
36
26
 
37
- if (opts.text === '') {
38
- text = opts.block;
39
- } else if (start !== -1 && end > start) {
40
- text = `${opts.text.slice(0, start)}${opts.block.trimEnd()}${opts.text.slice(end + ATLAS_BLOCK_END.length)}`;
41
- } else {
42
- const heading = opts.text.indexOf(MUST_READ);
43
- const next = heading === -1 ? -1 : opts.text.indexOf('\n## ', heading + MUST_READ.length);
27
+ /**
28
+ * Puts the block into AGENTS.md: rewritten between its markers when it is there, else inserted
29
+ * before the section that follows "Must read first", else appended. Text outside is never touched.
30
+ */
31
+ static merge(opts: { text: string; block: string }): { changed: boolean; text: string } {
32
+ const start = opts.text.indexOf(START_PREFIX);
33
+ const end = opts.text.indexOf(ATLAS_BLOCK_END);
34
+ let text: string;
44
35
 
45
- if (next === -1) {
46
- text = `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`;
36
+ if (opts.text === '') {
37
+ text = opts.block;
38
+ } else if (start !== -1 && end > start) {
39
+ text = `${opts.text.slice(0, start)}${opts.block.trimEnd()}${opts.text.slice(end + ATLAS_BLOCK_END.length)}`;
47
40
  } else {
48
- const at = next + 1;
41
+ const heading = opts.text.indexOf(MUST_READ);
42
+ const next = heading === -1 ? -1 : opts.text.indexOf('\n## ', heading + MUST_READ.length);
43
+
44
+ if (next === -1) {
45
+ text = `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`;
46
+ } else {
47
+ const at = next + 1;
49
48
 
50
- text = `${opts.text.slice(0, at)}${opts.block}\n${opts.text.slice(at)}`;
49
+ text = `${opts.text.slice(0, at)}${opts.block}\n${opts.text.slice(at)}`;
50
+ }
51
51
  }
52
- }
53
52
 
54
- return { changed: text !== opts.text, text };
55
- };
53
+ return { changed: text !== opts.text, text };
54
+ }
55
+ }
@@ -1,8 +1,6 @@
1
+ import { RecordValue } from '../common/record.ts';
1
2
  import { RemoveOutcomes } from './common/index.ts';
2
3
 
3
- const isRecord = (value: unknown): value is Record<string, unknown> =>
4
- typeof value === 'object' && value !== null && !Array.isArray(value);
5
-
6
4
  /** The script every VULCAN entry runs: it is how an entry of ours is told from a hook of the user's. */
7
5
  const GUARD_SCRIPT = 'codex-guards.ts';
8
6
 
@@ -37,11 +35,13 @@ const guardEntry = (): Record<string, unknown> => ({
37
35
  });
38
36
 
39
37
  const isGuardEntry = (entry: unknown): boolean =>
40
- isRecord(entry) &&
38
+ RecordValue.isRecord(entry) &&
41
39
  Array.isArray(entry.hooks) &&
42
40
  entry.hooks.some(
43
41
  (hook) =>
44
- isRecord(hook) && typeof hook.command === 'string' && hook.command.includes(GUARD_SCRIPT),
42
+ RecordValue.isRecord(hook) &&
43
+ typeof hook.command === 'string' &&
44
+ hook.command.includes(GUARD_SCRIPT),
45
45
  );
46
46
 
47
47
  interface IParsedFile {
@@ -58,14 +58,15 @@ const parseFile = (opts: { text: string | undefined }): IParsedFile | { reason:
58
58
  try {
59
59
  const file: unknown = JSON.parse(opts.text);
60
60
 
61
- if (!isRecord(file)) {
61
+ if (!RecordValue.isRecord(file)) {
62
62
  return { reason: 'the hooks file is not a JSON object' };
63
63
  }
64
64
 
65
65
  const hooks = file.hooks === undefined ? {} : file.hooks;
66
- const entries = isRecord(hooks) && hooks.PreToolUse !== undefined ? hooks.PreToolUse : [];
66
+ const entries =
67
+ RecordValue.isRecord(hooks) && hooks.PreToolUse !== undefined ? hooks.PreToolUse : [];
67
68
 
68
- return isRecord(hooks) && Array.isArray(entries)
69
+ return RecordValue.isRecord(hooks) && Array.isArray(entries)
69
70
  ? { file, hooks, entries }
70
71
  : { reason: 'the hooks file has a hooks or PreToolUse value that is not what Codex reads' };
71
72
  } catch (error) {
@@ -75,59 +76,61 @@ const parseFile = (opts: { text: string | undefined }): IParsedFile | { reason:
75
76
  }
76
77
  };
77
78
 
78
- export type TCodexHooksMerge =
79
+ type TCodexHooksMerge =
79
80
  | { ok: true; changed: boolean; text: string }
80
81
  | { ok: false; reason: string };
81
82
 
82
- /** The hooks file with VULCAN's PreToolUse entry in it, every other entry as the user wrote it. */
83
- export const mergeCodexHooks = (opts: { text: string | undefined }): TCodexHooksMerge => {
84
- const parsed = parseFile({ text: opts.text });
83
+ export class CodexHooks {
84
+ /** The hooks file with VULCAN's PreToolUse entry in it, every other entry as the user wrote it. */
85
+ static merge(opts: { text: string | undefined }): TCodexHooksMerge {
86
+ const parsed = parseFile({ text: opts.text });
87
+
88
+ if ('reason' in parsed) {
89
+ return { ok: false, reason: parsed.reason };
90
+ }
85
91
 
86
- if ('reason' in parsed) {
87
- return { ok: false, reason: parsed.reason };
92
+ const entry = guardEntry();
93
+ const index = parsed.entries.findIndex((item) => isGuardEntry(item));
94
+ const changed = index === -1 || JSON.stringify(parsed.entries[index]) !== JSON.stringify(entry);
95
+ const entries =
96
+ index === -1
97
+ ? [...parsed.entries, entry]
98
+ : parsed.entries.map((item, at) => (at === index ? entry : item));
99
+
100
+ return {
101
+ ok: true,
102
+ changed,
103
+ text: `${JSON.stringify({ ...parsed.file, hooks: { ...parsed.hooks, PreToolUse: entries } }, null, 2)}\n`,
104
+ };
88
105
  }
89
106
 
90
- const entry = guardEntry();
91
- const index = parsed.entries.findIndex((item) => isGuardEntry(item));
92
- const changed = index === -1 || JSON.stringify(parsed.entries[index]) !== JSON.stringify(entry);
93
- const entries =
94
- index === -1
95
- ? [...parsed.entries, entry]
96
- : parsed.entries.map((item, at) => (at === index ? entry : item));
97
-
98
- return {
99
- ok: true,
100
- changed,
101
- text: `${JSON.stringify({ ...parsed.file, hooks: { ...parsed.hooks, PreToolUse: entries } }, null, 2)}\n`,
102
- };
103
- };
107
+ /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
108
+ static remove(opts: { text: string }): TCodexHooksRemoval {
109
+ const parsed = parseFile({ text: opts.text });
104
110
 
105
- export type TCodexHooksRemoval =
106
- | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
107
- | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
108
- | { ok: false; reason: string };
111
+ if ('reason' in parsed) {
112
+ return { ok: false, reason: parsed.reason };
113
+ }
109
114
 
110
- /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
111
- export const removeCodexHooks = (opts: { text: string }): TCodexHooksRemoval => {
112
- const parsed = parseFile({ text: opts.text });
115
+ if (!parsed.entries.some((item) => isGuardEntry(item))) {
116
+ return { ok: true, outcome: RemoveOutcomes.ABSENT };
117
+ }
113
118
 
114
- if ('reason' in parsed) {
115
- return { ok: false, reason: parsed.reason };
116
- }
119
+ const kept = parsed.entries.filter((item) => !isGuardEntry(item));
120
+ const { PreToolUse: _removed, ...otherEvents } = parsed.hooks;
121
+ const hooks = kept.length > 0 ? { ...otherEvents, PreToolUse: kept } : otherEvents;
122
+ const { hooks: _hooks, ...otherKeys } = parsed.file;
123
+ const file = Object.keys(hooks).length > 0 ? { ...otherKeys, hooks } : otherKeys;
117
124
 
118
- if (!parsed.entries.some((item) => isGuardEntry(item))) {
119
- return { ok: true, outcome: RemoveOutcomes.ABSENT };
125
+ return {
126
+ ok: true,
127
+ outcome: RemoveOutcomes.REMOVED,
128
+ text: Object.keys(file).length === 0 ? undefined : `${JSON.stringify(file, null, 2)}\n`,
129
+ };
120
130
  }
131
+ }
121
132
 
122
- const kept = parsed.entries.filter((item) => !isGuardEntry(item));
123
- const { PreToolUse: _removed, ...otherEvents } = parsed.hooks;
124
- const hooks = kept.length > 0 ? { ...otherEvents, PreToolUse: kept } : otherEvents;
125
- const { hooks: _hooks, ...otherKeys } = parsed.file;
126
- const file = Object.keys(hooks).length > 0 ? { ...otherKeys, hooks } : otherKeys;
127
-
128
- return {
129
- ok: true,
130
- outcome: RemoveOutcomes.REMOVED,
131
- text: Object.keys(file).length === 0 ? undefined : `${JSON.stringify(file, null, 2)}\n`,
132
- };
133
- };
133
+ type TCodexHooksRemoval =
134
+ | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
135
+ | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
136
+ | { ok: false; reason: string };
@@ -13,7 +13,7 @@ export interface IAgentQuestion {
13
13
 
14
14
  export type TAskAgents = (question: IAgentQuestion) => string | null;
15
15
 
16
- export type TAgentSource = TConstValue<typeof AgentSources>;
16
+ type TAgentSource = TConstValue<typeof AgentSources>;
17
17
 
18
18
  export type TAgentResolution =
19
19
  | {
@@ -1,7 +1,7 @@
1
1
  import { Glob } from 'bun';
2
2
  import { existsSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
- import { readAgentTable } from './table.ts';
4
+ import { AgentTable } from './table.ts';
5
5
 
6
6
  const HOME_PREFIX = '~/';
7
7
 
@@ -18,19 +18,22 @@ const hasHomeEntry = (opts: { home: string; pattern: string }): boolean => {
18
18
  );
19
19
  };
20
20
 
21
- /**
22
- * The agents this machine seems to have, in table order: a binary on PATH, a folder in the home, a
23
- * folder in the project. It only pre-selects; the developer confirms.
24
- */
25
- export const detectAgents = (opts: { root: string; home: string; path: string }): string[] =>
26
- readAgentTable()
27
- .filter((entry) => {
28
- const { binaries, homeDirs, projectDirs } = entry.detect;
21
+ export class AgentDetection {
22
+ /**
23
+ * The agents this machine seems to have, in table order: a binary on PATH, a folder in the home, a
24
+ * folder in the project. It only pre-selects; the developer confirms.
25
+ */
26
+ static detect(opts: { root: string; home: string; path: string }): string[] {
27
+ return AgentTable.read()
28
+ .filter((entry) => {
29
+ const { binaries, homeDirs, projectDirs } = entry.detect;
29
30
 
30
- return (
31
- binaries.some((name) => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
32
- homeDirs.some((pattern) => hasHomeEntry({ home: opts.home, pattern })) ||
33
- projectDirs.some((directory) => existsSync(join(opts.root, directory)))
34
- );
35
- })
36
- .map((entry) => entry.id);
31
+ return (
32
+ binaries.some((name) => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
33
+ homeDirs.some((pattern) => hasHomeEntry({ home: opts.home, pattern })) ||
34
+ projectDirs.some((directory) => existsSync(join(opts.root, directory)))
35
+ );
36
+ })
37
+ .map((entry) => entry.id);
38
+ }
39
+ }