@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
@@ -6,12 +6,15 @@ const SHAPE = z.custom<string>((value) => typeof value === 'string' && BoardShap
6
6
  message: `one of ${[...BoardShapes.SCHEME_SET].join(', ')}`,
7
7
  });
8
8
 
9
- /** A face, or `{ shape?, lane?, role? }`: the lane rolls the agent into the row of another listed agent; the role is what the card says it is. */
9
+ /** A face, or `{ shape?, lane?, role? }`: the lane labels the agent "under" another listed agent on its own card; the role is what the card says it is. */
10
10
  export const BOARD_AGENT = z.union([
11
11
  SHAPE,
12
12
  z.strictObject({
13
+ /** Face of the agent: `bun`, `flame`, `ember`, `rock` or `banana`. */
13
14
  shape: SHAPE.optional(),
15
+ /** Name of another listed agent this one is shown under on its card; at least one character, and that agent has no lane of its own. */
14
16
  lane: z.string().min(1).optional(),
17
+ /** What the card says the agent is; trimmed, 1 to 60 characters. */
15
18
  role: z.string().trim().min(1).max(BoardConstants.ROLE_MAX).optional(),
16
19
  }),
17
20
  ]);
@@ -1,7 +1,9 @@
1
1
  import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
2
2
  import type { Server } from 'bun';
3
3
  import { BoardRoutes, BoardServe } from './common/index.ts';
4
+ import type { IThemeTokens } from '../theme/index.ts';
4
5
  import type { IBoardData, TBoardRoute } from './common/index.ts';
6
+ import { BoardOpenFile } from './open-file.ts';
5
7
  import { BoardPage } from './page.ts';
6
8
  import { BoardWatch } from './watch.ts';
7
9
 
@@ -13,7 +15,13 @@ interface IBoardServerOptions {
13
15
  dir: string;
14
16
  /** The folded board, as `vulcan board` makes it. */
15
17
  collect: () => IBoardData;
18
+ /** The design tokens of the page; default the default preset. */
19
+ tokens?: IThemeTokens;
16
20
  maxSnapshotBytes?: number;
21
+ /** The folder for the page `openFile` writes: the project's tmp folder. */
22
+ openFolder?: string;
23
+ /** How long that page stays when nothing reads the board; default `BoardServe.OPEN_FILE_TTL_MS`. */
24
+ openFileTtlMs?: number;
17
25
  }
18
26
 
19
27
  interface IBoardServerRun {
@@ -24,6 +32,12 @@ interface IBoardServerRun {
24
32
  max: number;
25
33
  stopWatch: () => void;
26
34
  timers: ReturnType<typeof setInterval>[];
35
+ /** The address with the token, as printed. */
36
+ url: string;
37
+ openFolder?: string;
38
+ openFileTtlMs: number;
39
+ /** The page `openFile` wrote, if it is still there. */
40
+ openFile?: { path: string; directory: string; timer: ReturnType<typeof setTimeout> };
27
41
  }
28
42
 
29
43
  const PAGE_HEADERS = {
@@ -76,6 +90,7 @@ export class BoardServer {
76
90
  }
77
91
 
78
92
  const url = new URL(opts.url);
93
+
79
94
  const given = url.searchParams.get(BoardServe.TOKEN_PARAM);
80
95
 
81
96
  if (given === null || !BoardServer.isToken({ given, token: opts.token })) {
@@ -110,7 +125,14 @@ export class BoardServer {
110
125
  port,
111
126
  development: false,
112
127
  fetch: (request, server) =>
113
- BoardServer.answer({ request, server, token, hostname, collect: opts.collect }),
128
+ BoardServer.answer({
129
+ request,
130
+ server,
131
+ token,
132
+ hostname,
133
+ collect: opts.collect,
134
+ tokens: opts.tokens,
135
+ }),
114
136
  error: (error) => {
115
137
  process.stderr.write(`board: a request failed: ${error.message}\n`);
116
138
 
@@ -144,6 +166,9 @@ export class BoardServer {
144
166
  max,
145
167
  stopWatch: () => undefined,
146
168
  timers: [],
169
+ url: '',
170
+ ...(opts.openFolder === undefined ? {} : { openFolder: opts.openFolder }),
171
+ openFileTtlMs: opts.openFileTtlMs ?? BoardServe.OPEN_FILE_TTL_MS,
147
172
  };
148
173
  const publish = (): void => {
149
174
  const data = BoardServer.snapshotOf({ collect: opts.collect });
@@ -172,13 +197,66 @@ export class BoardServer {
172
197
 
173
198
  const path = BoardServer.pathWithToken({ path: BoardServe.PAGE_PATH, token });
174
199
 
200
+ run.url = `http://${hostname}:${server.port}${path}`;
201
+
175
202
  return {
176
- url: `http://${hostname}:${server.port}${path}`,
203
+ url: run.url,
177
204
  fallback: `http://${BoardServe.HOST}:${server.port}${path}`,
178
205
  ...(note === undefined ? {} : { note }),
179
206
  };
180
207
  }
181
208
 
209
+ /**
210
+ * The page for the program that opens the browser: a file in a folder only its owner can enter, made in `openFolder`, that sends the
211
+ * browser to the address with the token. The path is not a secret, so it may be in an argument list. The file is
212
+ * removed by the first request that carries the token, after `openFileTtlMs` and when the server stops; a new call
213
+ * removes the one before it. `undefined` when no server runs or the file cannot be written.
214
+ */
215
+ static openFile(): string | undefined {
216
+ const { run } = BoardServer;
217
+
218
+ if (run === undefined || run.openFolder === undefined) {
219
+ return undefined;
220
+ }
221
+
222
+ BoardServer.dropOpenFile();
223
+
224
+ try {
225
+ const { path, directory } = BoardOpenFile.write({ folder: run.openFolder, url: run.url });
226
+ const timer = setTimeout(() => BoardServer.dropOpenFile(), run.openFileTtlMs);
227
+
228
+ timer.unref();
229
+ run.openFile = { path, directory, timer };
230
+
231
+ return path;
232
+ } catch (error) {
233
+ process.stderr.write(
234
+ `board: cannot write the page that opens the browser: ${error instanceof Error ? error.message : String(error)}\n`,
235
+ );
236
+
237
+ return undefined;
238
+ }
239
+ }
240
+
241
+ private static dropOpenFile(): void {
242
+ const file = BoardServer.run?.openFile;
243
+
244
+ if (BoardServer.run === undefined || file === undefined) {
245
+ return;
246
+ }
247
+
248
+ BoardServer.run.openFile = undefined;
249
+ clearTimeout(file.timer);
250
+
251
+ try {
252
+ BoardOpenFile.remove({ directory: file.directory });
253
+ } catch (error) {
254
+ process.stderr.write(
255
+ `board: cannot remove ${file.directory}: ${error instanceof Error ? error.message : String(error)}\n`,
256
+ );
257
+ }
258
+ }
259
+
182
260
  /** Stops the server, the watch and the timers, and ends every open stream. */
183
261
  static async stop(): Promise<void> {
184
262
  const { run } = BoardServer;
@@ -187,6 +265,7 @@ export class BoardServer {
187
265
  return;
188
266
  }
189
267
 
268
+ BoardServer.dropOpenFile();
190
269
  BoardServer.run = undefined;
191
270
  run.stopWatch();
192
271
 
@@ -257,6 +336,7 @@ export class BoardServer {
257
336
  token: string;
258
337
  hostname: string;
259
338
  collect: () => IBoardData;
339
+ tokens?: IThemeTokens;
260
340
  }): Response {
261
341
  const { request, server, token } = opts;
262
342
  const verdict = BoardServer.check({
@@ -269,6 +349,10 @@ export class BoardServer {
269
349
  hostname: opts.hostname,
270
350
  });
271
351
 
352
+ if (verdict.route !== undefined) {
353
+ BoardServer.dropOpenFile();
354
+ }
355
+
272
356
  if (verdict.route === BoardRoutes.PAGE) {
273
357
  const data = BoardServer.snapshotOf({ collect: opts.collect });
274
358
 
@@ -278,7 +362,7 @@ export class BoardServer {
278
362
 
279
363
  const live = { stream: BoardServer.pathWithToken({ path: BoardServe.STREAM_PATH, token }) };
280
364
 
281
- return new Response(BoardPage.render({ data: { ...data, live } }), {
365
+ return new Response(BoardPage.render({ data: { ...data, live }, tokens: opts.tokens }), {
282
366
  headers: PAGE_HEADERS,
283
367
  });
284
368
  }
@@ -1,9 +1,11 @@
1
1
  import { spawnSync } from 'node:child_process';
2
- import { existsSync, readFileSync, statSync } from 'node:fs';
2
+ import { readFileSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
4
  import { RecordValue } from '../common/record.ts';
5
- import { BoardConstants, BoardServe } from './common/index.ts';
5
+ import { BoardConstants, BoardServe, ProviderTypes } from './common/index.ts';
6
+ import type { IBoardProvider } from './common/index.ts';
6
7
  import { BoardAgentSetting } from './agent-setting.ts';
8
+ import { BoardLogo } from './logo.ts';
7
9
  import { BOARD_AGENT, BOARD_AGENTS } from './schema.ts';
8
10
  import type { TBoardAgentSetting } from './schema.ts';
9
11
 
@@ -17,10 +19,12 @@ export interface IBoardSettings {
17
19
  hostname: string;
18
20
  /** The listed `board.agents` keys with no lane; empty when none is listed, and then every agent shows. */
19
21
  roster: string[];
20
- /** A helper to the lane it rolls into. */
22
+ /** A helper to the listed name it works under; shown as a label on its own card. */
21
23
  lanes: Record<string, string>;
22
24
  /** What `board.agents` says each agent is. */
23
25
  roles: Record<string, string>;
26
+ /** The code host to read: `provider`, else GitHub. */
27
+ provider: IBoardProvider;
24
28
  /** Why a setting was not used, for the note the command prints. */
25
29
  notes: string[];
26
30
  }
@@ -56,10 +60,22 @@ export class BoardSettings {
56
60
  }
57
61
 
58
62
  if (logoPath !== undefined && logo === undefined) {
59
- notes.push(`board.logo ${logoPath} is missing, over 100 KB or not an SVG: no logo`);
63
+ notes.push(
64
+ `board.logo ${logoPath} is missing, outside the project, over 100 KB or not an SVG: no logo`,
65
+ );
60
66
  }
61
67
 
68
+ const provider = RecordValue.isRecord(manifest.provider) ? manifest.provider : {};
69
+ const host = text(provider.host);
70
+
62
71
  return {
72
+ provider: {
73
+ type: provider.type === ProviderTypes.GITLAB ? ProviderTypes.GITLAB : ProviderTypes.GITHUB,
74
+ host:
75
+ host !== undefined && BoardConstants.GITLAB_HOST.test(host)
76
+ ? host
77
+ : BoardConstants.GITLAB_DEFAULT_HOST,
78
+ },
63
79
  title: text(block.title) ?? `${name} Board`,
64
80
  hostname:
65
81
  typeof block.hostname === 'string' && BoardServe.HOSTNAME.test(block.hostname)
@@ -163,26 +179,7 @@ export class BoardSettings {
163
179
  return BoardSettings.resolve({
164
180
  manifest,
165
181
  gitUser: (opts.readGitUser ?? (() => BoardSettings.gitUserOf({ root: opts.root })))(),
166
- readLogo: (path) => BoardSettings.logoOf({ root: opts.root, path }),
182
+ readLogo: (path) => BoardLogo.read({ root: opts.root, path }),
167
183
  });
168
184
  }
169
-
170
- /** The SVG at `path` in the project as a `data:` URL; a picture in an `img` runs no script, whatever the file holds. */
171
- private static logoOf(opts: { root: string; path: string }): string | undefined {
172
- const file = join(opts.root, opts.path);
173
-
174
- try {
175
- if (!existsSync(file) || statSync(file).size > BoardConstants.LOGO_MAX_BYTES) {
176
- return undefined;
177
- }
178
-
179
- const svg = readFileSync(file);
180
-
181
- return /<svg[\s>]/i.test(svg.toString('utf8', 0, 2000))
182
- ? `data:image/svg+xml;base64,${svg.toString('base64')}`
183
- : undefined;
184
- } catch {
185
- return undefined;
186
- }
187
- }
188
185
  }
@@ -0,0 +1,40 @@
1
+ import { ExitCodes } from '../common/index.ts';
2
+ import type { ICommandContext } from '../common/index.ts';
3
+ import { runXCommand } from './x.command.ts';
4
+
5
+ const SUBCOMMAND = 'check';
6
+ const NOTES = 'notes';
7
+ const USAGE = `usage: vulcan changelog ${SUBCOMMAND} [--history --base <ref>] | ${NOTES} --version <X.Y.Z> [--migration]`;
8
+
9
+ /**
10
+ * `vulcan changelog check` and `vulcan changelog notes`: atlas's `changelogs` command run at the pinned version, over this
11
+ * project's entries.
12
+ */
13
+ export const runChangelogCommand = (opts: ICommandContext): Promise<number> => {
14
+ const rest = opts.args.slice(1);
15
+ const isShape =
16
+ rest.length === 0 || (rest.length === 3 && rest[0] === '--history' && rest[1] === '--base');
17
+
18
+ if (opts.args[0] === NOTES) {
19
+ const isNotes =
20
+ rest[0] === '--version' &&
21
+ rest[1] !== undefined &&
22
+ (rest.length === 2 || (rest.length === 3 && rest[2] === '--migration'));
23
+
24
+ if (!isNotes) {
25
+ process.stderr.write(`${USAGE}\n`);
26
+
27
+ return Promise.resolve(ExitCodes.USAGE);
28
+ }
29
+
30
+ return runXCommand({ ...opts, args: ['atlas', 'changelogs', NOTES, ...rest] });
31
+ }
32
+
33
+ if (opts.args[0] !== SUBCOMMAND || !isShape) {
34
+ process.stderr.write(`${USAGE}\n`);
35
+
36
+ return Promise.resolve(ExitCodes.USAGE);
37
+ }
38
+
39
+ return runXCommand({ ...opts, args: ['atlas', 'changelogs', SUBCOMMAND, ...rest] });
40
+ };
@@ -5,6 +5,7 @@ import type { ILocalEntry } from '../local/index.ts';
5
5
 
6
6
  const YES_FLAG = '--yes';
7
7
  const ALL_FLAG = '--all';
8
+ const INCLUDE_FRESH_FLAG = '--include-fresh';
8
9
 
9
10
  const lineOf = (opts: { entry: ILocalEntry }): string => {
10
11
  const { entry } = opts;
@@ -27,7 +28,11 @@ export const runCleanCommand = async (opts: ICommandContext): Promise<number> =>
27
28
  ? named
28
29
  : [CleanScopes.TMP];
29
30
  const yes = opts.args.includes(YES_FLAG);
30
- const plan = LocalClean.plan({ root: opts.cwd, scopes });
31
+ const plan = LocalClean.plan({
32
+ root: opts.cwd,
33
+ scopes,
34
+ includeFresh: opts.args.includes(INCLUDE_FRESH_FLAG),
35
+ });
31
36
  const total = plan.remove.reduce((sum, entry) => sum + entry.bytes, 0);
32
37
 
33
38
  if (plan.remove.length === 0 && plan.keep.length === 0) {
@@ -1,69 +1,8 @@
1
1
  import { ExitCodes, VULCAN_VERSION } from '../common/index.ts';
2
-
3
- const HELP = `vulcan ${VULCAN_VERSION} - one setup, one workflow for every project
4
-
5
- Usage: bun x vulcan <command>
6
-
7
- init [--key <KEY>] Scaffold the project layer (never overwrites); --key is the project's flow key
8
- (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name)
9
- init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
10
- [--shared-dir <path>] [--scope <@scope>] [--key <KEY>]
11
- Create a monorepo with its first app, from a framework preset
12
- (a name missing from the flags is asked in a terminal)
13
- add --preset <name|file:path> (--app <name> | --lib <name> | --shared <name>) [--dir <folder>]
14
- [--scope <@scope>] [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
15
- Add an app, a library other apps import (--lib) or a side-neutral package
16
- other apps import (--shared) to the monorepo (a frontend says which
17
- backend to proxy to; --dir is for a library or a shared package;
18
- --scope names the package @scope/<name>; a terminal asks for the kind
19
- and every name the flags leave out)
20
- preset diff <package> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
21
- Read-only: set each file the preset makes now (for an app, a library or
22
- a shared package) against the file the package has (same, differs,
23
- missing); --full prints the unified diffs, --check exits 1 when
24
- anything differs or is missing
25
- sync [--agents <list>|list] [--dry-run]
26
- Write the adapters of the agents you chose (--agents claude,omp or none,
27
- stored in .agents/vulcan.local.json; --agents list shows the table)
28
- agents [list|add <ids>|remove <ids>|setup] [--dry-run]
29
- See, add, remove or re-choose the coding agents you use on this machine
30
- doctor Check the project follows VULCAN; exit 1 on any violation
31
- commit-check <message-file> | --range <revs> | --text <message>
32
- Check a commit message against the commit.message checks of the config (an
33
- agent in a trailer or a "generated with" line, the project's subject shape);
34
- sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input
35
- board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
36
- Fold the event log (and GitHub pull requests, checks and reviews when gh
37
- can read them) into flows and write one HTML file, by default
38
- .agents/local/reports/board.html; read-only; exit 2 on bad input
39
- ci affected --base <ref> [--head <ref>] [--check <check>] [--json | --names] | template <github|gitlab>
40
- List the workspace packages a change touches (changed ones and what
41
- depends on them) with the checks each has; template prints a CI file that
42
- runs exactly those; exit 2 on bad input
43
- event add --kind <k> --summary <text> [--flow <flow id>] [--ref <r>] [--status approve|park|reject] | 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>]
44
- Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
45
- read it; with events.log on, sync installs the Claude Code hooks that
46
- write it; exit 2 on bad input
47
- visualize <spec.json> [--out <name>] | --schema
48
- Make one small static HTML page (a flow, a status, a before and after) from
49
- a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema
50
- profile [show|edit|reset [--yes]]
51
- Tell VULCAN how you like to work (reply language, how to address you,
52
- tone, habits) in .agents/local/profile.json; no argument runs the form,
53
- show prints it, reset deletes it
54
- clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--events|--release-candidates|--profile] [--yes]
55
- List what an agent left under .agents/local/ (a dry run) and, with
56
- --yes, remove it; --tmp is the default, --worktrees takes merged or
57
- gone branches only, --all never touches reports, prototypes, events, release candidates or the profile
58
- upgrade [--stable | --nightly] [<version|tag>]
59
- Bump the pinned @venizia/vulcan, then sync; --stable (default)
60
- takes the latest tag, --nightly the newest of latest and next
61
- x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas
62
- help · version
63
- `;
2
+ import { CommandTable } from './table.ts';
64
3
 
65
4
  export const runHelpCommand = async (): Promise<number> => {
66
- process.stdout.write(HELP);
5
+ process.stdout.write(CommandTable.helpText());
67
6
 
68
7
  return ExitCodes.OK;
69
8
  };
@@ -8,7 +8,12 @@ export const COMMAND_LOADERS: Record<string, () => Promise<TCommandHandler>> = {
8
8
  import('./agents.command.ts').then((module) => module.runAgentsCommand),
9
9
  [VulcanCommands.BOARD]: () =>
10
10
  import('./board.command.ts').then((module) => module.runBoardCommand),
11
- [VulcanCommands.CI]: () => import('./ci.command.ts').then((module) => module.runCiCommand),
11
+ [VulcanCommands.RUNNERS]: () =>
12
+ import('./runners.command.ts').then((module) => module.runRunnersCommand),
13
+ [VulcanCommands.CHANGELOG]: () =>
14
+ import('./changelog.command.ts').then((module) => module.runChangelogCommand),
15
+ [VulcanCommands.MIGRATE]: () =>
16
+ import('./migrate.command.ts').then((module) => module.runMigrateCommand),
12
17
  [VulcanCommands.CLEAN]: () =>
13
18
  import('./clean.command.ts').then((module) => module.runCleanCommand),
14
19
  [VulcanCommands.COMMIT_CHECK]: () =>
@@ -0,0 +1,71 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { dirname, join, resolve } from 'node:path';
3
+ import { ExitCodes } from '../common/index.ts';
4
+ import type { ICommandContext } from '../common/index.ts';
5
+ import { ConfigLoader } from '../config/index.ts';
6
+ import { runXCommand } from './x.command.ts';
7
+
8
+ const SUBCOMMANDS = new Set(['plan', 'apply']);
9
+
10
+ /**
11
+ * The project a folder belongs to: the nearest folder at or above `cwd` that has a VULCAN config, never
12
+ * above the git work tree root (a config of an unrelated parent is not this project's). `undefined` when
13
+ * there is none, so the folder is served as it is and atlas says there is nothing to serve.
14
+ */
15
+ const enclosingProjectOf = (opts: { cwd: string }): string | undefined => {
16
+ let directory = opts.cwd;
17
+
18
+ for (;;) {
19
+ if (ConfigLoader.findFile({ root: directory }) !== undefined) {
20
+ return directory;
21
+ }
22
+
23
+ const parent = dirname(directory);
24
+
25
+ if (existsSync(join(directory, '.git')) || parent === directory) {
26
+ return undefined;
27
+ }
28
+
29
+ directory = parent;
30
+ }
31
+ };
32
+
33
+ /** `--app` made absolute against the folder the command was run in, and added (as that folder) when absent. */
34
+ const withApp = (opts: { args: string[]; cwd: string }): string[] => {
35
+ const args = [...opts.args];
36
+ const at = args.findIndex((arg) => arg === '--app' || arg.startsWith('--app='));
37
+
38
+ if (at === -1) {
39
+ return [...args, '--app', opts.cwd];
40
+ }
41
+
42
+ if (args[at] === '--app') {
43
+ args[at + 1] = resolve(opts.cwd, args[at + 1] ?? '');
44
+ } else {
45
+ args[at] = `--app=${resolve(opts.cwd, args[at].slice('--app='.length))}`;
46
+ }
47
+
48
+ return args;
49
+ };
50
+
51
+ /** `vulcan migrate plan|apply`: atlas's `migrate` run at the pinned version, over the sources this project serves. */
52
+ export const runMigrateCommand = (opts: ICommandContext): Promise<number> => {
53
+ if (!SUBCOMMANDS.has(opts.args[0] ?? '')) {
54
+ process.stderr.write(
55
+ 'usage: vulcan migrate plan [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--format md|json] [--verbose]\n vulcan migrate apply [--package <name>] [--from <version>] --to <version|latest|next> [--app <dir>] [--force]\n',
56
+ );
57
+
58
+ return Promise.resolve(ExitCodes.USAGE);
59
+ }
60
+
61
+ const project = enclosingProjectOf({ cwd: opts.cwd });
62
+
63
+ // Run in the project that has the config; the app is the folder the command was run in unless `--app` says otherwise.
64
+ return project === undefined || project === opts.cwd
65
+ ? runXCommand({ ...opts, args: ['atlas', 'migrate', ...opts.args] })
66
+ : runXCommand({
67
+ ...opts,
68
+ cwd: project,
69
+ args: ['atlas', 'migrate', ...withApp({ args: opts.args, cwd: opts.cwd })],
70
+ });
71
+ };
@@ -150,7 +150,7 @@ export class ProfilePrompt {
150
150
 
151
151
  if (!TerminalCapability.menusAvailable()) {
152
152
  process.stderr.write(
153
- "tell VULCAN how you like to work (language, how to address you, tone): run 'bun x --no-install vulcan profile'\n",
153
+ "tell VULCAN how you like to work (language, how to address you, tone): run 'bun node_modules/.bin/vulcan profile'\n",
154
154
  );
155
155
 
156
156
  return;
@@ -0,0 +1,43 @@
1
+ import { ExitCodes } from '../common/index.ts';
2
+ import type { ICommandContext } from '../common/index.ts';
3
+ import { RunnersCheck } from '../runners/check.ts';
4
+
5
+ const USAGE = 'usage: vulcan runners check';
6
+
7
+ /**
8
+ * `vulcan runners check`: lists every tracked file that runs an unscoped package through `bunx`, `bun x`, `npx`, `pnpm dlx`
9
+ * or `yarn dlx`, one `file:line` each, and exits 1; exits 0 when there is none.
10
+ */
11
+ export const runRunnersCommand = (opts: ICommandContext): Promise<number> => {
12
+ if (opts.args[0] !== 'check' || opts.args.length !== 1) {
13
+ process.stderr.write(`${USAGE}\n`);
14
+
15
+ return Promise.resolve(ExitCodes.USAGE);
16
+ }
17
+
18
+ let scan;
19
+
20
+ try {
21
+ scan = RunnersCheck.scan({ root: opts.cwd });
22
+ } catch (error) {
23
+ process.stderr.write(
24
+ `vulcan runners: ${error instanceof Error ? error.message : String(error)}\n`,
25
+ );
26
+
27
+ return Promise.resolve(ExitCodes.USAGE);
28
+ }
29
+
30
+ for (const finding of scan.findings) {
31
+ process.stderr.write(
32
+ `${finding.file}:${finding.line}: ${finding.runner} ${finding.name === '' ? '(no name)' : finding.name} fetches a package by name; run \`bun node_modules/.bin/<bin>\` from the project root, or through a make target (V-S-08)\n`,
33
+ );
34
+ }
35
+
36
+ if (scan.examples > 0) {
37
+ process.stderr.write(
38
+ `${scan.examples} command${scan.examples === 1 ? '' : 's'} in Markdown marked as an example (<!-- runners: example -->) not counted\n`,
39
+ );
40
+ }
41
+
42
+ return Promise.resolve(scan.findings.length === 0 ? ExitCodes.OK : ExitCodes.FAILURE);
43
+ };
@@ -1,3 +1,4 @@
1
+ import { ProjectTmp } from '../hooks/project-tmp.ts';
1
2
  import { relative } from 'node:path';
2
3
  import { ExitCodes } from '../common/index.ts';
3
4
  import type { ICommandContext } from '../common/index.ts';
@@ -13,7 +14,7 @@ import { ConfigLoader } from '../config/index.ts';
13
14
  import {
14
15
  AgentFiles,
15
16
  AgentRemoval,
16
- AtlasBlockPlan,
17
+ AgentsBlockPlan,
17
18
  BaseRulesDiff,
18
19
  ExcludePlan,
19
20
  LocalPlan,
@@ -116,14 +117,17 @@ export class SyncFlow {
116
117
  const actions = [
117
118
  ...AgentRemoval.plan({ root: opts.cwd, removed, remaining: resolved.agents }),
118
119
  ...SyncPlanner.plan({ root: opts.cwd, config: loaded.config, agents: resolved.agents }),
119
- ...AtlasBlockPlan.plan({ root: opts.cwd, config: loaded.config }),
120
+ ...AgentsBlockPlan.plan({ root: opts.cwd, config: loaded.config }),
120
121
  ...stored,
121
- ...LocalPlan.planWorkspace({ root: opts.cwd }),
122
+ ...LocalPlan.planWorkspace({
123
+ root: opts.cwd,
124
+ tmp: ProjectTmp.configuredOf({ tmp: loaded.config.local.tmp }),
125
+ }),
122
126
  ...ExcludePlan.plan({ root: opts.cwd, agents: resolved.agents }),
123
127
  ...CommitHookPlan.plan({ root: opts.cwd, config: loaded.config }),
124
128
  ];
125
129
  // Read before the manifest action rewrites the hashes it compares against.
126
- const changes = BaseRulesDiff.diff({ root: opts.cwd });
130
+ const changes = BaseRulesDiff.diff({ root: opts.cwd, packs: loaded.config.packs });
127
131
  const width = dryRun ? DRY_RUN_LABEL_WIDTH : LABEL_WIDTH;
128
132
 
129
133
  for (const action of actions) {