@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -0,0 +1,362 @@
1
+ import { AgentConstants } from '../agents/index.ts';
2
+ import { BoardFlags } from '../board/common/index.ts';
3
+ import { CommitCheckFlags } from '../commit/common/index.ts';
4
+ import { ExitCodes, UpgradeFlags, VULCAN_VERSION, VulcanCommands } from '../common/index.ts';
5
+ import { CreateFlags } from '../create/common/index.ts';
6
+ import { EventFlags } from '../events/common/index.ts';
7
+
8
+ /** What the router lets through for a command: the flags that stand alone, the flags that take the next argument, and how many plain arguments. */
9
+ export interface IAcceptedArgs {
10
+ flags: string[];
11
+ /** The exit code for an argument the command does not take; `1` when absent. */
12
+ unknownExit?: number;
13
+ values: string[];
14
+ positionals: number;
15
+ }
16
+
17
+ /** One command: what `vulcan help` prints for it, what its flags do, and what its exit codes mean. */
18
+ export interface ICommandSpec {
19
+ /** The block `vulcan help` prints for the command: its usage lines, then what it does. */
20
+ help: string;
21
+ /** Flags that stand alone, each with what it does. */
22
+ flags?: Record<string, string>;
23
+ /** Flags that take the next argument, each with what it does. */
24
+ values?: Record<string, string>;
25
+ /** Flags the router lets through and the command does not read. */
26
+ ignored?: { flags: string[]; values: string[] };
27
+ /** How many arguments without a flag the command takes. */
28
+ positionals?: number;
29
+ /** The exit code for an argument the command does not take; `1` when absent. */
30
+ unknownExit?: number;
31
+ /** What the exit codes mean. */
32
+ exits: string;
33
+ /** The arguments are not checked by the router: `x` hands them to its tool, `help` and `version` take none. */
34
+ passthrough?: true;
35
+ }
36
+
37
+ /** Every command in one table: `vulcan help` prints its blocks and the router takes its accepted arguments from it; the generated command reference is to read the flag descriptions and exit codes. */
38
+ export class CommandTable {
39
+ static readonly COMMANDS: Record<string, ICommandSpec> = {
40
+ [VulcanCommands.INIT]: {
41
+ help: ` init [--key <KEY>] Scaffold the project layer (never overwrites); --key is the project's flow key
42
+ (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name)
43
+ init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
44
+ [--shared-dir <path>] [--scope <@scope>] [--key <KEY>]
45
+ Create a monorepo with its first app, from a framework preset
46
+ (a name missing from the flags is asked in a terminal)`,
47
+ values: {
48
+ [CreateFlags.PRESET]: 'The preset package; its presence selects the monorepo mode',
49
+ [CreateFlags.PROJECT]: 'The project name and the folder to create',
50
+ [CreateFlags.BACKEND_DIR]: 'The folder that holds backend apps, 1 to 4 segments',
51
+ [CreateFlags.FRONTEND_DIR]: 'The folder that holds frontend apps, 1 to 4 segments',
52
+ [CreateFlags.SHARED_DIR]: 'A folder for code shared between apps; optional',
53
+ [CreateFlags.APP]: 'The name of the first app',
54
+ [CreateFlags.SCOPE]: "The npm scope of the first app's package, such as @acme",
55
+ [CreateFlags.KEY]: "The project's flow key, 2 to 8 uppercase letters or digits",
56
+ },
57
+ ignored: { flags: [CreateFlags.NO_API], values: [CreateFlags.API] },
58
+ exits:
59
+ '0 on success; 1 when it refuses before writing (not a project, bad or missing name, folder not empty) or bun add fails.',
60
+ },
61
+ [VulcanCommands.ADD]: {
62
+ help: ` add --preset <name|file:path> (--app <name> | --lib <name> | --shared <name>) [--dir <folder>]
63
+ [--scope <@scope>] [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
64
+ Add an app, a library other apps import (--lib) or a side-neutral package
65
+ other apps import (--shared) to the monorepo (a frontend says which
66
+ backend to proxy to; --dir is for a library or a shared package;
67
+ --scope names the package @scope/<name>; a terminal asks for the kind
68
+ and every name the flags leave out)`,
69
+ flags: {
70
+ [CreateFlags.NO_API]: 'A frontend only: proxy to nothing',
71
+ },
72
+ values: {
73
+ [CreateFlags.PRESET]: 'The preset package; a bare name means @venizia/<name>',
74
+ [CreateFlags.BACKEND_DIR]: 'The folder for backend apps, used when the preset is a backend',
75
+ [CreateFlags.FRONTEND_DIR]:
76
+ 'The folder for frontend apps, used when the preset is a frontend',
77
+ [CreateFlags.APP]: 'The name of the new app',
78
+ [CreateFlags.API]: 'A frontend only: the backend app to proxy /api to',
79
+ [CreateFlags.LIB]: 'Create a library other apps import, instead of an app',
80
+ [CreateFlags.SHARED]: 'Create a side-neutral package that apps of either side import',
81
+ [CreateFlags.DIR]: 'A library or shared package only: the folder it goes in',
82
+ [CreateFlags.SCOPE]: 'The npm scope of the package name, such as @acme',
83
+ },
84
+ exits: '0 on success; 1 on any refusal, which happens before the first write.',
85
+ },
86
+ [VulcanCommands.PRESET]: {
87
+ help: ` preset diff <package> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
88
+ Read-only: set each file the preset makes now (for an app, a library or
89
+ a shared package) against the file the package has (same, differs,
90
+ missing); --full prints the unified diffs, --check exits 1 when
91
+ anything differs or is missing`,
92
+ flags: {
93
+ [CreateFlags.NO_API]: 'A frontend app only: proxy to nothing',
94
+ [CreateFlags.FULL]: 'Print the unified diff under each file that differs',
95
+ [CreateFlags.CHECK]: 'Exit 1 when a file differs or is missing, for CI',
96
+ },
97
+ values: {
98
+ [CreateFlags.PRESET]: 'The preset to render, when it cannot be found from the package',
99
+ [CreateFlags.API]: 'A frontend app only: the backend app to proxy /api to',
100
+ },
101
+ positionals: 2,
102
+ exits:
103
+ '0 when a report is printed (with --check, and nothing differs); 1 on --check with a difference or missing file, or any refusal.',
104
+ },
105
+ [VulcanCommands.SYNC]: {
106
+ help: ` sync [--agents <list>|list] [--dry-run]
107
+ Write the adapters of the agents you chose (--agents claude,omp or none,
108
+ stored in .agents/vulcan.local.json; --agents list shows the table)`,
109
+ flags: {
110
+ '--dry-run': 'Print planned changes without writing to disk',
111
+ },
112
+ values: {
113
+ [AgentConstants.FLAG]: 'The agents to write adapters for, comma-separated, none, or list',
114
+ },
115
+ exits:
116
+ '0 on success; 1 when .claude/settings.json cannot be written, or the configuration fails to load.',
117
+ },
118
+ [VulcanCommands.AGENTS]: {
119
+ help: ` agents [list|add <ids>|remove <ids>|setup] [--dry-run]
120
+ See, add, remove or re-choose the coding agents you use on this machine`,
121
+ flags: {
122
+ '--dry-run': 'Print what would change and write nothing',
123
+ },
124
+ positionals: 2,
125
+ exits:
126
+ '0 on success, including an agent already chosen or not chosen; 1 on an unknown id, a bad argument or a failed write.',
127
+ },
128
+ [VulcanCommands.DOCTOR]: {
129
+ help: ` doctor Check the project follows VULCAN; exit 1 on any violation`,
130
+ exits: '0 for a conformant project; 1 on one or more contract violations.',
131
+ },
132
+ [VulcanCommands.COMMIT_CHECK]: {
133
+ help: ` commit-check <message-file> | --range <revs> | --text <message>
134
+ Check a commit message against the commit.message checks of the config (an
135
+ agent in a trailer or a "generated with" line, the project's subject shape);
136
+ sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input`,
137
+ values: {
138
+ [CommitCheckFlags.RANGE]: 'Check every commit of a git range, such as origin/develop..HEAD',
139
+ [CommitCheckFlags.TEXT]: 'Check the message text you give',
140
+ },
141
+ positionals: 2,
142
+ unknownExit: ExitCodes.USAGE,
143
+ exits:
144
+ '0 when nothing is wrong or no check is configured; 1 when a message has a problem; 2 on bad input.',
145
+ },
146
+ [VulcanCommands.BOARD]: {
147
+ help: ` board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
148
+ Fold the event log (and GitHub or GitLab pull requests, checks and reviews
149
+ when gh or glab can read them) into flows and write one HTML file, by default
150
+ .agents/local/reports/board.html; read-only; exit 2 on bad input
151
+ board serve [--port <n>] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
152
+ Serve the same page on 127.0.0.1 (default port 4317) and push the new events to the open page, with no reload`,
153
+ flags: {
154
+ [BoardFlags.OPEN]: 'Open the file in your browser when it is written',
155
+ [BoardFlags.NO_GITHUB]: 'Do not read GitHub',
156
+ },
157
+ values: {
158
+ [BoardFlags.OUT]: 'The file to write; default .agents/local/reports/board.html',
159
+ [BoardFlags.PORT]: 'serve only: the port to listen on; default 4317',
160
+ [BoardFlags.SINCE]: 'Read events and pull requests changed at or after this date',
161
+ [BoardFlags.DIR]: 'The events folder; default events.dir, else .agents/local/events',
162
+ [BoardFlags.REPO]: 'A GitHub repository, owner/name; repeat it to read several',
163
+ },
164
+ positionals: 1,
165
+ unknownExit: ExitCodes.USAGE,
166
+ exits:
167
+ '0 on written or serve stopped; 1 when the file cannot be written or serve cannot start; 2 on bad input.',
168
+ },
169
+ [VulcanCommands.EVENT]: {
170
+ help: ` event add --kind <k> --summary <text> [--flow <flow id>] [--ref <r>] [--status approve|park|reject] [--actor <name>] | add --kind flow [--flow <flow id>] --title <text> [--why <text>] [--context <text>] [--next <text>] [--step|--step-done <text>]... [--check|--check-done <text>]... [--app <name>]... [--due YYYY-MM-DD] | tail [--since <time>] [--json] [--dir <folder>]
171
+ Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
172
+ read it; with events.log on, sync installs the Claude Code hooks that
173
+ write it; exit 2 on bad input`,
174
+ flags: {
175
+ [EventFlags.JSON]: 'Print each line as written (tail)',
176
+ },
177
+ values: {
178
+ [EventFlags.KIND]: 'One of the twelve event kinds',
179
+ [EventFlags.SUMMARY]: 'A short label, cut to one line of 200 characters',
180
+ [EventFlags.FLOW]: 'The id of a flow the log already has',
181
+ [EventFlags.STEP]: 'Flow only, repeatable: a step still to do',
182
+ [EventFlags.STEP_DONE]: 'Flow only, repeatable: a step done',
183
+ [EventFlags.CHECK]: 'Flow only, repeatable: an acceptance check still open',
184
+ [EventFlags.CHECK_DONE]: 'Flow only, repeatable: an acceptance check done',
185
+ [EventFlags.APP]: 'Flow only, repeatable: an app or module the flow touches',
186
+ [EventFlags.DUE]: 'Flow only: the day it is due, YYYY-MM-DD',
187
+ [EventFlags.REF]: 'A commit, a PR number, a recipient, or a tracker id',
188
+ [EventFlags.STATUS]: 'approve, park or reject; required on a decision',
189
+ [EventFlags.TITLE]: 'Flow only, required: the title of the flow',
190
+ [EventFlags.WHY]: 'Flow only: one line on why the flow exists',
191
+ [EventFlags.CONTEXT]: 'Flow only: two to four sentences on what the flow is',
192
+ [EventFlags.NEXT]: 'Flow only: the next step and who does it',
193
+ [EventFlags.ACTOR]: 'Who wrote the event; else VULCAN_ACTOR or the session name',
194
+ [EventFlags.DIR]: 'The events folder for this call, over events.dir',
195
+ [EventFlags.SINCE]: 'tail only: print events at or after this time; default 24 hours',
196
+ },
197
+ positionals: 1,
198
+ unknownExit: ExitCodes.USAGE,
199
+ exits: '0 written; 1 when the folder cannot be written; 2 on bad input.',
200
+ },
201
+ [VulcanCommands.VISUALIZE]: {
202
+ help: ` visualize <spec.json> [--out <name>] | --schema
203
+ Make one small static HTML page (a flow, a status, a before and after) from
204
+ a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema`,
205
+ flags: {
206
+ '--schema': 'Print the schema of the spec',
207
+ },
208
+ values: {
209
+ [BoardFlags.OUT]: 'The name of the page written in .agents/local/prototypes/',
210
+ },
211
+ positionals: 1,
212
+ exits:
213
+ '0 on success; 1 when the spec is missing or not renderable, or .agents/local/ is missing or outside the project.',
214
+ },
215
+ [VulcanCommands.PROFILE]: {
216
+ help: ` profile [show|edit|reset [--yes]]
217
+ Tell VULCAN how you like to work (reply language, how to address you,
218
+ tone, habits) in .agents/local/profile.json; no argument runs the form,
219
+ show prints it, reset deletes it`,
220
+ flags: {
221
+ '--yes': 'With reset: delete .agents/local/profile.json',
222
+ },
223
+ positionals: 1,
224
+ exits:
225
+ '0 on saved, shown, reset or nothing to reset; 1 on cancelled, unreadable profile, .agents/local/ not gitignored, or unknown argument.',
226
+ },
227
+ [VulcanCommands.CLEAN]: {
228
+ help: ` clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--events|--release-candidates|--profile] [--include-fresh] [--yes]
229
+ List what an agent left under .agents/local/ (a dry run) and, with
230
+ --yes, remove it; --tmp is the default and takes stale items only (--include-fresh
231
+ adds the rest), --worktrees takes merged or gone branches only, --all never touches reports, prototypes, events, release candidates or the profile`,
232
+ flags: {
233
+ '--tmp': 'Remove the stale items of tmp/ (older than a day); the default',
234
+ '--include-fresh':
235
+ 'Also remove items of tmp/ and clones/ that are not stale yet; a live session may be using them',
236
+ '--worktrees': 'Remove worktrees whose branch is merged or gone and that are clean',
237
+ '--clones': 'Remove stale clones of other repositories (older than two weeks)',
238
+ '--cache': 'Remove what atlas fetched; it rebuilds',
239
+ '--reports': 'Remove reports/; kept unless named',
240
+ '--prototypes': 'Remove prototypes/; kept unless named',
241
+ '--profile': 'Remove profile.json; kept unless named',
242
+ '--events': 'Remove event day files past the events limits; only when named',
243
+ '--release-candidates':
244
+ 'Remove release-candidate folders whose version tag exists; only when named',
245
+ '--all':
246
+ 'Select tmp, worktrees, clones and cache; never reports, prototypes, events, candidates or profile',
247
+ '--yes': 'Remove what the dry run listed',
248
+ },
249
+ exits:
250
+ '0 on a dry run, a removal or nothing to remove; 1 when an item cannot be removed, or on an unknown flag.',
251
+ },
252
+ [VulcanCommands.UPGRADE]: {
253
+ help: ` upgrade [--stable | --nightly] [<version|tag>]
254
+ Bump the pinned @venizia/vulcan, then sync; --stable (default)
255
+ takes the latest tag, --nightly the newest of latest and next`,
256
+ flags: {
257
+ [UpgradeFlags.STABLE]: 'Install the latest stable release; the default',
258
+ [UpgradeFlags.NIGHTLY]: 'Install the higher of latest and next',
259
+ },
260
+ positionals: 1,
261
+ exits:
262
+ '0 on success; 1 when --stable and --nightly are both given, the dist-tags cannot be read, or the install or sync fails.',
263
+ },
264
+ [VulcanCommands.RUNNERS]: {
265
+ help: ` runners check List every tracked file that runs an unscoped package through bunx, pnpx,
266
+ bun x, npx, npm exec, pnpm dlx or yarn dlx, whether or not it says no-install
267
+ (a name npm gives to someone else would be fetched and run). A scoped package
268
+ and the names of guard.runners.allow pass; tests, lockfiles, build output and
269
+ frozen history (dated entries, released version folders) are not read`,
270
+ positionals: 1,
271
+ unknownExit: ExitCodes.USAGE,
272
+ exits:
273
+ '0 when no file runs one; 1 when one does (file:line, the command and the safe forms); 2 for any other argument or a folder git cannot list.',
274
+ },
275
+ [VulcanCommands.CHANGELOG]: {
276
+ help: ` changelog check [--history --base <ref>]
277
+ Check the changelog: a version folder changelogs/<X.Y.Z>/{log.md, migration.yaml}
278
+ has a block for every Breaking and Deprecated item; a dated Breaking Change entry
279
+ on or after a date cutover carries one. --history also fails a released folder that
280
+ changed since the base, a stable with no folder, and a dated file, dated after
281
+ knowledge.datedUntil, that was added or edited.
282
+ changelog notes --version <X.Y.Z> [--migration]
283
+ The release notes of a version folder: the body of its log.md, then the packages.
284
+ --migration prints the path of its migration.yaml when that file holds a block,
285
+ and nothing when it does not (what a workflow attaches to the Release)`,
286
+ flags: {
287
+ '--history':
288
+ 'Also run the checks that read git: frozen released folders, stables without a folder, new dated files',
289
+ '--migration':
290
+ 'With notes: print the path of migration.yaml when it holds a block, not the notes',
291
+ },
292
+ values: {
293
+ '--base':
294
+ 'With --history: the commit or branch the change is measured from, e.g. origin/develop',
295
+ '--version': 'With notes: the version folder to read, e.g. 0.4.8',
296
+ },
297
+ positionals: 1,
298
+ unknownExit: ExitCodes.USAGE,
299
+ exits:
300
+ '0 when every entry conforms (notes: printed); 1 when an entry does not, a folder is missing, the tool is missing or the configuration is invalid; 2 for a subcommand other than check or notes.',
301
+ },
302
+ [VulcanCommands.MIGRATE]: {
303
+ help: ` migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json] [--verbose]
304
+ What an app must change to move a package between two releases, newer or
305
+ older: the steps in order, the places in your code they touch (file:line),
306
+ codemods and data warnings; read only
307
+ migrate apply [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--force]
308
+ Run the codemods the plan links, once each in order (reversed for a
309
+ rollback), then print the steps that stay manual; refuses an app with
310
+ uncommitted changes or outside git unless --force`,
311
+ values: {
312
+ '--package': 'The package to move; absent, every installed package the sources know',
313
+ '--from': 'The version the app runs now; default the installed one',
314
+ '--to':
315
+ 'A version, latest (newest stable) or next (newest release) of the atlas release table',
316
+ '--app': 'The app directory to scan; default the current directory',
317
+ '--format': 'md (default) or json (plan only)',
318
+ },
319
+ flags: {
320
+ '--force': 'apply: run on an app with uncommitted changes, or outside git',
321
+ '--verbose': 'plan: list every place that imports a module a step is about, not a count',
322
+ },
323
+ positionals: 1,
324
+ unknownExit: ExitCodes.USAGE,
325
+ exits:
326
+ '0 when a plan is printed or apply ran; 1 when the plan cannot be made (an unknown package or version, nothing installed), apply is refused (uncommitted changes, no git, no devz) or a codemod fails, or the tool is missing; 2 for a subcommand other than plan or apply, or a missing --to.',
327
+ },
328
+ [VulcanCommands.X]: {
329
+ help: ` x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas`,
330
+ passthrough: true,
331
+ exits:
332
+ 'the exit code of the tool; 1 on a missing or unknown tool, an unresolvable package or an invalid configuration',
333
+ },
334
+ [VulcanCommands.HELP]: { help: '', passthrough: true, exits: '0' },
335
+ [VulcanCommands.VERSION]: { help: '', passthrough: true, exits: '0' },
336
+ };
337
+
338
+ /** The arguments the router lets `name` take; undefined when it checks none. */
339
+ static accepted(opts: { name: string }): IAcceptedArgs | undefined {
340
+ const spec = CommandTable.COMMANDS[opts.name];
341
+
342
+ if (spec === undefined || spec.passthrough === true) {
343
+ return undefined;
344
+ }
345
+
346
+ return {
347
+ flags: [...Object.keys(spec.flags ?? {}), ...(spec.ignored?.flags ?? [])],
348
+ values: [...Object.keys(spec.values ?? {}), ...(spec.ignored?.values ?? [])],
349
+ positionals: spec.positionals ?? 0,
350
+ ...(spec.unknownExit === undefined ? {} : { unknownExit: spec.unknownExit }),
351
+ };
352
+ }
353
+
354
+ /** What `vulcan help` prints. */
355
+ static helpText(): string {
356
+ const blocks = Object.values(CommandTable.COMMANDS).flatMap((spec) =>
357
+ spec.help === '' ? [] : [spec.help],
358
+ );
359
+
360
+ return `vulcan ${VULCAN_VERSION} - one setup, one workflow for every project\n\nUsage: bun node_modules/.bin/vulcan <command>\n\n${blocks.join('\n')}\n help · version\n`;
361
+ }
362
+ }
@@ -23,6 +23,7 @@ type TSource =
23
23
 
24
24
  type TMessages = { ok: true; messages: ICheckedMessage[] } | { ok: false; error: string };
25
25
 
26
+ /** Checks commit messages against the project commit-message rules and returns an exit code; used by `vulcan commit-check`, which the commit-msg hook calls. */
26
27
  export class CommitCheck {
27
28
  static async run(opts: ICommandContext): Promise<number> {
28
29
  const source = CommitCheck.sourceOf({ args: opts.args });
@@ -23,6 +23,10 @@ export class CommitHookStates {
23
23
  static readonly STALE = 'stale';
24
24
  /** A hook that is not ours and does not call the check: the developer adds the line. */
25
25
  static readonly UNWIRED = 'unwired';
26
+ /** A hook of the developer's that still runs `vulcan` by name through bunx or `bun x`: stale, and not ours to rewrite. */
27
+ static readonly LEGACY = 'legacy';
28
+ /** A hook that another project of the repository wrote: this project's check is not installed, and the hook is not touched. */
29
+ static readonly OTHER_PROJECT = 'other-project';
26
30
  /** Our hook, and the project turned every check off: sync takes it back. */
27
31
  static readonly LEFTOVER = 'leftover';
28
32
  }
@@ -8,8 +8,21 @@ import type { ICommitHookStatus } from './common/index.ts';
8
8
 
9
9
  const HOOK_NAME = 'commit-msg';
10
10
  const MARKER = '# vulcan:commit-msg';
11
- const CALL = /vulcan\s+commit-check/;
12
- const COMMAND = 'bun x --no-install vulcan commit-check "$1"';
11
+ /** The marker line, then the folder of the project that wrote it in brackets; a hook of an earlier release has no brackets. */
12
+ const OWNER = new RegExp(`^${MARKER}(?: \\[([^\\]]*)\\])?`);
13
+ /** A hook that calls the check: the old text (`vulcan commit-check`) and the one sync writes now (`vulcan" commit-check`). */
14
+ const CALL = /vulcan["']?\s+commit-check/;
15
+ /** The call sync wrote before V-S-08, and the `bunx` forms of it: they can run a copy bunx cached, so a hook that has one is stale. */
16
+ const LEGACY_CALL = /\bbun(?:x|\s+x)\s+(?:--?[\w-]+\s+)*vulcan\s+commit-check/;
17
+ /** A line break, or any other control character: a folder name that holds one cannot be written into the hook text. */
18
+ const CONTROL_CHARACTER = /\p{Cc}/u;
19
+ const CONTROL_CHARACTERS = /\p{Cc}/gu;
20
+ /** The escapes the marker line holds: `%` and `]`, and a control character as two hex digits. */
21
+ const ESCAPE = /%(25|5D|[01][0-9A-F]|7F|[89][0-9A-F])/g;
22
+ /** The linked bin of the folder the loop above found, by path: nothing is fetched and no `$PATH` is searched (V-S-08). */
23
+ const COMMAND = 'bun "$dir/node_modules/.bin/vulcan" commit-check "$1"';
24
+ /** What a developer adds to a hook of their own, run from the project folder. */
25
+ const ADVICE_COMMAND = 'bun node_modules/.bin/vulcan commit-check "$1"';
13
26
 
14
27
  const git = (opts: { root: string; args: string[] }): string | undefined => {
15
28
  try {
@@ -39,11 +52,15 @@ export class CommitHook {
39
52
  * no `commit-check` command (an older branch).
40
53
  */
41
54
  static template(opts: { prefix: string }): string {
42
- const folder = opts.prefix.replace(/\/$/, '');
55
+ if (!CommitHook.isWritable({ prefix: opts.prefix })) {
56
+ throw new Error(CommitHook.REFUSAL);
57
+ }
58
+
59
+ const folder = CommitHook.folderOf({ prefix: opts.prefix });
43
60
  const enter = folder === '' ? '' : `cd ${CommitHook.quote({ text: folder })} || exit 0\n`;
44
61
 
45
62
  return `#!/bin/sh
46
- ${MARKER} - written by vulcan sync from commit.message in .configs/vulcan.config.mts; do not edit
63
+ ${MARKER} [${CommitHook.encode({ folder })}] - written by vulcan sync from commit.message in .configs/vulcan.config.mts; do not edit
47
64
  message="$1"
48
65
  case "$message" in /*) ;; *) message="$PWD/$message" ;; esac
49
66
  top="$(git rev-parse --show-toplevel)"
@@ -71,6 +88,54 @@ exit "$status"
71
88
  `;
72
89
  }
73
90
 
91
+ /** Why a project folder is refused: its name could end a line of the hook text and start another. */
92
+ static readonly REFUSAL =
93
+ 'the project folder name holds a line break or another control character, so the commit-msg hook is not written';
94
+
95
+ /** Whether the hook text can name the folder: its name holds no line break and no other control character. */
96
+ static isWritable(opts: { prefix: string }): boolean {
97
+ return !CONTROL_CHARACTER.test(opts.prefix);
98
+ }
99
+
100
+ /**
101
+ * A folder as the marker line spells it: `%` and `]` are escaped, so a name that holds a bracket cannot end the
102
+ * field, and so is a control character, so the field stays on its line.
103
+ */
104
+ private static encode(opts: { folder: string }): string {
105
+ return opts.folder
106
+ .replaceAll('%', '%25')
107
+ .replaceAll(']', '%5D')
108
+ .replace(
109
+ CONTROL_CHARACTERS,
110
+ (char) => `%${(char.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(2, '0')}`,
111
+ );
112
+ }
113
+
114
+ private static decode(opts: { field: string }): string {
115
+ return opts.field.replace(ESCAPE, (_, code: string) =>
116
+ String.fromCodePoint(Number.parseInt(code, 16)),
117
+ );
118
+ }
119
+
120
+ /**
121
+ * The project folder inside the repository, without the trailing slash; empty for the top level. A folder that
122
+ * `isWritable` refuses is still named here, so a hook of another project is told apart from this one's.
123
+ */
124
+ private static folderOf(opts: { prefix: string }): string {
125
+ return opts.prefix.replace(/\/$/, '');
126
+ }
127
+
128
+ /**
129
+ * The project folder a hook of ours was written for (empty: the repository's top level), or `undefined` when
130
+ * the file is not ours. A hook of an earlier release carries no folder and is the top level's: it is the only
131
+ * kind there was, and a project below the top level that wrote one is not told apart from it.
132
+ */
133
+ static ownerOf(opts: { text: string }): string | undefined {
134
+ const matched = OWNER.exec(opts.text.split('\n')[1] ?? '');
135
+
136
+ return matched === null ? undefined : CommitHook.decode({ field: matched[1] ?? '' });
137
+ }
138
+
74
139
  private static quote(opts: { text: string }): string {
75
140
  return `'${opts.text.replaceAll("'", "'\\''")}'`;
76
141
  }
@@ -92,15 +157,29 @@ exit "$status"
92
157
  const hooksPath = git({ root: opts.root, args: ['config', '--get', 'core.hooksPath'] });
93
158
  const entry = lstatSync(path, { throwIfNoEntry: false });
94
159
  const text = entry?.isFile() === true ? readFileSync(path, 'utf8') : undefined;
95
- const isOurs = hooksPath === undefined && text?.split('\n')[1]?.startsWith(MARKER) === true;
160
+ const folder = CommitHook.folderOf({ prefix });
161
+ const owner = text === undefined ? undefined : CommitHook.ownerOf({ text });
162
+ // Ours is a hook this project wrote. One another project of the repository wrote is neither removed nor replaced.
163
+ const isOurs = hooksPath === undefined && owner === folder;
164
+ const isOtherProjects = hooksPath === undefined && owner !== undefined && owner !== folder;
96
165
 
97
166
  if (!isWanted) {
98
167
  return { state: isOurs ? CommitHookStates.LEFTOVER : CommitHookStates.OFF, path };
99
168
  }
100
169
 
101
- const addLine = `add '${COMMAND}' to its ${HOOK_NAME} hook`;
170
+ const addLine = `add '${ADVICE_COMMAND}' to its ${HOOK_NAME} hook`;
171
+
172
+ const legacyNote = `it runs vulcan by name through bunx or \`bun x\`, which can run a copy bunx cached: change the line to '${ADVICE_COMMAND}'`;
102
173
 
103
174
  if (hooksPath !== undefined) {
175
+ if (text !== undefined && LEGACY_CALL.test(text)) {
176
+ return {
177
+ state: CommitHookStates.LEGACY,
178
+ path,
179
+ note: `core.hooksPath is ${hooksPath}: ${legacyNote}`,
180
+ };
181
+ }
182
+
104
183
  return text !== undefined && CALL.test(text)
105
184
  ? { state: CommitHookStates.WIRED, path }
106
185
  : {
@@ -110,6 +189,11 @@ exit "$status"
110
189
  };
111
190
  }
112
191
 
192
+ // Nothing is written for such a folder, whatever is there: the plan skips it and says why.
193
+ if (!CommitHook.isWritable({ prefix })) {
194
+ return { state: CommitHookStates.UNWIRED, path, note: CommitHook.REFUSAL };
195
+ }
196
+
113
197
  if (entry === undefined) {
114
198
  return { state: CommitHookStates.MISSING, path };
115
199
  }
@@ -122,12 +206,28 @@ exit "$status"
122
206
  };
123
207
  }
124
208
 
209
+ if (isOtherProjects) {
210
+ return {
211
+ state: CommitHookStates.OTHER_PROJECT,
212
+ path,
213
+ note: `the hook belongs to ${owner === '' ? 'the project at the top of the repository' : `the project in ${owner}`}, not touched: a repository has one ${HOOK_NAME} hook`,
214
+ };
215
+ }
216
+
125
217
  if (isOurs) {
126
218
  const isCurrent = text === CommitHook.template({ prefix }) && (entry.mode & 0o111) !== 0;
127
219
 
128
220
  return { state: isCurrent ? CommitHookStates.WIRED : CommitHookStates.STALE, path };
129
221
  }
130
222
 
223
+ if (LEGACY_CALL.test(text)) {
224
+ return {
225
+ state: CommitHookStates.LEGACY,
226
+ path,
227
+ note: `a hook of yours is there, not touched: ${legacyNote}`,
228
+ };
229
+ }
230
+
131
231
  return CALL.test(text)
132
232
  ? { state: CommitHookStates.WIRED, path }
133
233
  : {
@@ -138,8 +238,10 @@ exit "$status"
138
238
  }
139
239
 
140
240
  static write(opts: { path: string; prefix: string }): void {
241
+ const text = CommitHook.template({ prefix: opts.prefix });
242
+
141
243
  mkdirSync(dirname(opts.path), { recursive: true });
142
- writeFileSync(opts.path, CommitHook.template({ prefix: opts.prefix }));
244
+ writeFileSync(opts.path, text);
143
245
  chmodSync(opts.path, 0o755);
144
246
  }
145
247
  }
@@ -164,7 +266,9 @@ export class CommitHookPlan {
164
266
  return [{ path, status: SyncStatuses.UNCHANGED, apply: () => {} }];
165
267
  }
166
268
 
167
- case CommitHookStates.UNWIRED: {
269
+ case CommitHookStates.UNWIRED:
270
+ case CommitHookStates.LEGACY:
271
+ case CommitHookStates.OTHER_PROJECT: {
168
272
  return [{ path, status: SyncStatuses.SKIPPED, note: status.note, apply: () => {} }];
169
273
  }
170
274
 
@@ -1,3 +1,6 @@
1
+ import { EnvVariables } from './env-variables.ts';
2
+
3
+ /** The names of the `vulcan` subcommands, shared by the router, the command registry and the help output. */
1
4
  export class VulcanCommands {
2
5
  static readonly INIT = 'init';
3
6
  static readonly ADD = 'add';
@@ -10,9 +13,11 @@ export class VulcanCommands {
10
13
  static readonly PRESET = 'preset';
11
14
  static readonly VISUALIZE = 'visualize';
12
15
  static readonly COMMIT_CHECK = 'commit-check';
13
- static readonly CI = 'ci';
14
16
  static readonly BOARD = 'board';
15
17
  static readonly EVENT = 'event';
18
+ static readonly CHANGELOG = 'changelog';
19
+ static readonly RUNNERS = 'runners';
20
+ static readonly MIGRATE = 'migrate';
16
21
  static readonly X = 'x';
17
22
  static readonly HELP = 'help';
18
23
  static readonly VERSION = 'version';
@@ -23,7 +28,7 @@ export class UpgradeFlags {
23
28
  static readonly STABLE = '--stable';
24
29
  static readonly NIGHTLY = '--nightly';
25
30
  /** Tests only: a JSON object of dist-tags that stands in for the registry read. */
26
- static readonly DIST_TAGS_ENV = 'VULCAN_DIST_TAGS';
31
+ static readonly DIST_TAGS_ENV = EnvVariables.VULCAN_DIST_TAGS;
27
32
  }
28
33
 
29
34
  export class ExitCodes {
@@ -45,19 +50,17 @@ export class VulcanTools {
45
50
 
46
51
  /** What a VULCAN project carries; shared by `init`, which writes it, and `doctor`, which checks it. */
47
52
  export class ProjectLayout {
48
- /** How everything unattended runs vulcan: `--no-install` never fetches the unrelated npm package named `vulcan`. */
49
- static readonly VULCAN_COMMAND = 'bun x --no-install vulcan';
53
+ /** How everything unattended runs vulcan: the linked bin of this project, never a package fetched by the name `vulcan` (V-S-08). */
54
+ static readonly VULCAN_COMMAND = 'bun node_modules/.bin/vulcan';
50
55
 
51
56
  /** `vulcan x` hands the resolved project config to the tool in these variables; the tools read nothing else. */
52
- static readonly CONFIG_ENV = 'VULCAN_CONFIG';
53
- static readonly ROOT_ENV = 'VULCAN_PROJECT_ROOT';
57
+ static readonly CONFIG_ENV = EnvVariables.VULCAN_CONFIG;
58
+ static readonly ROOT_ENV = EnvVariables.VULCAN_PROJECT_ROOT;
54
59
  /** `-include`: a fresh clone runs `make install` before node_modules exists. */
55
60
  static readonly MAKE_INCLUDE_LINE = '-include node_modules/@venizia/vulcan/base/make/vulcan.mk';
56
61
  static readonly STYLE_PACKAGE = '@venizia/dev-configs';
57
62
  /** The one list of secret files, for `.gitignore` and for `.dockerignore`: the `.env` files stay out of git and out of every image, the example stays in. */
58
63
  static readonly SECRET_PATTERNS = ['**/.env', '**/.env.*', '!**/.env.example'];
59
- /** The default `remoteHosts.localFile`: a person's own hosts, ignored by git. */
60
- static readonly TRUSTED_HOSTS_FILE = '.agents/hooks/trusted-hosts.local';
61
64
  static readonly GITIGNORE_ENTRIES = [
62
65
  'CLAUDE.md',
63
66
  'CLAUDE.*.md',
@@ -66,7 +69,6 @@ export class ProjectLayout {
66
69
  '.agents/vulcan.local.json',
67
70
  '.agents/local/',
68
71
  ...ProjectLayout.SECRET_PATTERNS,
69
- ProjectLayout.TRUSTED_HOSTS_FILE,
70
72
  ];
71
73
  /** Everything an agent creates while it works lives under here, gitignored: nothing goes outside the project. */
72
74
  static readonly LOCAL_DIRECTORY = '.agents/local';