@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -221,56 +221,59 @@ export interface IVerdict {
221
221
  reason: string;
222
222
  }
223
223
 
224
- /**
225
- * What the guards say about one tool call: `deny` (blocked), `ask` (the owner decides; one reason holds every
226
- * guard that asked) or `allow`. Exported so a host that is not an extension (Antigravity's hook command) can
227
- * use the same policy.
228
- */
229
- export const verdictOf = (opts: {
230
- toolName: string;
231
- input: Record<string, unknown>;
232
- cwd: string;
233
- }): IVerdict => {
234
- const root = rootOf({ cwd: opts.cwd });
235
- const claudeEvent = claudeEventOf({ event: opts, root });
236
- const asks: string[] = [];
237
-
238
- if (claudeEvent === undefined) {
239
- return { kind: Verdicts.ALLOW, reason: '' };
240
- }
241
-
242
- for (const guard of GUARDS.filter((item) => item.tools.includes(opts.toolName))) {
243
- const answer = runGuard({ guard, root, claudeEvent });
244
-
245
- if (answer.kind === Answers.DENY) {
246
- return { kind: Verdicts.DENY, reason: answer.reason };
247
- }
248
-
249
- if (answer.kind === Answers.ASK) {
250
- asks.push(answer.reason);
224
+ export class GuardVerdict {
225
+ /**
226
+ * What the guards say about one tool call: `deny` (blocked), `ask` (the owner decides; one reason holds every
227
+ * guard that asked) or `allow`. Exported so a host that is not an extension (Antigravity's hook command) can
228
+ * use the same policy.
229
+ */
230
+ static verdictOf(opts: {
231
+ toolName: string;
232
+ input: Record<string, unknown>;
233
+ cwd: string;
234
+ }): IVerdict {
235
+ const root = rootOf({ cwd: opts.cwd });
236
+ const claudeEvent = claudeEventOf({ event: opts, root });
237
+ const asks: string[] = [];
238
+
239
+ if (claudeEvent === undefined) {
240
+ return { kind: Verdicts.ALLOW, reason: '' };
251
241
  }
252
242
 
253
- if (answer.kind === Answers.MISSING) {
254
- const isRepair = opts.toolName === Tools.BASH && BUN_INSTALL.test(String(opts.input.command));
243
+ for (const guard of GUARDS.filter((item) => item.tools.includes(opts.toolName))) {
244
+ const answer = runGuard({ guard, root, claudeEvent });
255
245
 
256
- if (guard.onFailure === Failures.BLOCK && !isRepair) {
246
+ if (answer.kind === Answers.DENY) {
257
247
  return { kind: Verdicts.DENY, reason: answer.reason };
258
248
  }
259
- }
260
249
 
261
- if (answer.kind === Answers.FAILED) {
262
- if (guard.onFailure === Failures.BLOCK) {
263
- return { kind: Verdicts.DENY, reason: answer.reason };
250
+ if (answer.kind === Answers.ASK) {
251
+ asks.push(answer.reason);
264
252
  }
265
253
 
266
- asks.push(answer.reason);
254
+ if (answer.kind === Answers.MISSING) {
255
+ const isRepair =
256
+ opts.toolName === Tools.BASH && BUN_INSTALL.test(String(opts.input.command));
257
+
258
+ if (guard.onFailure === Failures.BLOCK && !isRepair) {
259
+ return { kind: Verdicts.DENY, reason: answer.reason };
260
+ }
261
+ }
262
+
263
+ if (answer.kind === Answers.FAILED) {
264
+ if (guard.onFailure === Failures.BLOCK) {
265
+ return { kind: Verdicts.DENY, reason: answer.reason };
266
+ }
267
+
268
+ asks.push(answer.reason);
269
+ }
267
270
  }
268
- }
269
271
 
270
- return asks.length > 0
271
- ? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
272
- : { kind: Verdicts.ALLOW, reason: '' };
273
- };
272
+ return asks.length > 0
273
+ ? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
274
+ : { kind: Verdicts.ALLOW, reason: '' };
275
+ }
276
+ }
274
277
 
275
278
  /** Asks the owner when there is a UI to ask; without one the call is blocked, never let through. */
276
279
  const askOwner = async (opts: {
@@ -288,7 +291,11 @@ const askOwner = async (opts: {
288
291
 
289
292
  export default function vulcanGuards(host: IHost): void {
290
293
  host.on('tool_call', async (event, context) => {
291
- const verdict = verdictOf({ toolName: event.toolName, input: event.input, cwd: context.cwd });
294
+ const verdict = GuardVerdict.verdictOf({
295
+ toolName: event.toolName,
296
+ input: event.input,
297
+ cwd: context.cwd,
298
+ });
292
299
 
293
300
  if (verdict.kind === Verdicts.DENY) {
294
301
  return { block: true, reason: verdict.reason };
@@ -53,10 +53,10 @@ const workspaces =
53
53
  if (tool === undefined || !isRecord(args)) {
54
54
  answer({ decision: 'allow' });
55
55
  } else {
56
- const { verdictOf } = await import('../extensions/vulcan-guards.ts');
56
+ const { GuardVerdict } = await import('../extensions/vulcan-guards.ts');
57
57
  const command = textOf(args.CommandLine);
58
58
  const path = textOf(args.TargetFile);
59
- const verdict = verdictOf({
59
+ const verdict = GuardVerdict.verdictOf({
60
60
  toolName: tool,
61
61
  input: Object.fromEntries([
62
62
  ['command', command],
@@ -37,13 +37,23 @@ const command = isRecord(toolInput) ? textOf(toolInput['command']) : undefined;
37
37
  const cwd = (isRecord(parsed) ? textOf(parsed['cwd']) : undefined) ?? process.cwd();
38
38
 
39
39
  if (command !== undefined && (tool === 'Bash' || tool === 'apply_patch')) {
40
- const { verdictOf } = await import('../extensions/vulcan-guards.ts');
41
- const { patchedFilesOf } = await import('../../src/hooks/codex-patch.ts');
40
+ const { GuardVerdict } = await import('../extensions/vulcan-guards.ts');
41
+ const { CodexPatch } = await import('../../src/hooks/codex-patch.ts');
42
42
  const verdicts =
43
43
  tool === 'Bash'
44
- ? [verdictOf({ toolName: 'bash', input: Object.fromEntries([['command', command]]), cwd })]
45
- : patchedFilesOf({ patch: command, cwd }).map((file) =>
46
- verdictOf({ toolName: file.tool, input: Object.fromEntries([['path', file.path]]), cwd }),
44
+ ? [
45
+ GuardVerdict.verdictOf({
46
+ toolName: 'bash',
47
+ input: Object.fromEntries([['command', command]]),
48
+ cwd,
49
+ }),
50
+ ]
51
+ : CodexPatch.patchedFilesOf({ patch: command, cwd }).map((file) =>
52
+ GuardVerdict.verdictOf({
53
+ toolName: file.tool,
54
+ input: Object.fromEntries([['path', file.path]]),
55
+ cwd,
56
+ }),
47
57
  );
48
58
  const refused = verdicts.find((verdict) => verdict.kind === 'deny');
49
59
  const asked = verdicts.filter((verdict) => verdict.kind === 'ask');
@@ -25,17 +25,17 @@ const text = await Bun.stdin.text();
25
25
 
26
26
  try {
27
27
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
28
- const { buildToolDecision } = await import('../../src/hooks/decision.ts');
29
- const { inspectGit } = await import('../../src/hooks/guard-git.ts');
30
- const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
31
- const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
32
- const hookCommand = parseHookCommand({ text });
28
+ const { HookDecision } = await import('../../src/hooks/decision.ts');
29
+ const { GitGuard } = await import('../../src/hooks/guard-git.ts');
30
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
31
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
32
+ const hookCommand = WriteGuard.parseHookCommand({ text });
33
33
  const cwd = hookCommand?.cwd ?? process.cwd();
34
34
  const hits = hookCommand
35
- ? inspectGit({
35
+ ? GitGuard.inspect({
36
36
  command: hookCommand.command,
37
37
  cwd,
38
- askPush: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
38
+ askPush: ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
39
39
  })
40
40
  : [];
41
41
 
@@ -44,7 +44,7 @@ try {
44
44
 
45
45
  console.log(
46
46
  JSON.stringify(
47
- buildToolDecision({
47
+ HookDecision.buildTool({
48
48
  decision: denied ? GuardDecisions.DENY : GuardDecisions.ASK,
49
49
  reason: [
50
50
  denied
@@ -12,13 +12,12 @@
12
12
  export {};
13
13
 
14
14
  try {
15
- const { buildManifestDecision, inspectManifestWrite, parseManifestHookInput } =
16
- await import('../../src/hooks/guard-manifest.ts');
15
+ const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
17
16
  const stdin = await Bun.stdin.text();
18
- const input = parseManifestHookInput({ text: stdin });
17
+ const input = ManifestGuard.parseHookInput({ text: stdin });
19
18
 
20
- if (input && inspectManifestWrite({ input })) {
21
- console.log(JSON.stringify(buildManifestDecision()));
19
+ if (input && ManifestGuard.inspectWrite({ input })) {
20
+ console.log(JSON.stringify(ManifestGuard.buildDecision()));
22
21
  }
23
22
  } catch (error) {
24
23
  console.error(
@@ -24,18 +24,18 @@ const text = await Bun.stdin.text();
24
24
 
25
25
  try {
26
26
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
27
- const { buildToolDecision } = await import('../../src/hooks/decision.ts');
28
- const { inspectOutside } = await import('../../src/hooks/guard-outside.ts');
29
- const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
30
- const input = parseManifestHookInput({ text });
27
+ const { HookDecision } = await import('../../src/hooks/decision.ts');
28
+ const { OutsideGuard } = await import('../../src/hooks/guard-outside.ts');
29
+ const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
30
+ const input = ManifestGuard.parseHookInput({ text });
31
31
 
32
32
  if (input) {
33
33
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
34
34
  let toolOwnedPaths: string[] = [];
35
35
 
36
36
  try {
37
- const { loadConfig } = await import('../../src/config/index.ts');
38
- const loaded = await loadConfig({ root: projectRoot });
37
+ const { ConfigLoader } = await import('../../src/config/index.ts');
38
+ const loaded = await ConfigLoader.load({ root: projectRoot });
39
39
 
40
40
  toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
41
41
  } catch (error) {
@@ -44,7 +44,7 @@ try {
44
44
  );
45
45
  }
46
46
 
47
- const hits = inspectOutside({ input, projectRoot, toolOwnedPaths });
47
+ const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
48
48
 
49
49
  if (hits.length > 0) {
50
50
  const isScratchpad = hits.some((hit) => hit.isAgentToolScratchpad);
@@ -54,7 +54,7 @@ try {
54
54
 
55
55
  console.log(
56
56
  JSON.stringify(
57
- buildToolDecision({
57
+ HookDecision.buildTool({
58
58
  decision: isScratchpad ? GuardDecisions.DENY : GuardDecisions.ASK,
59
59
  reason: isScratchpad
60
60
  ? [
@@ -13,15 +13,14 @@
13
13
  export {};
14
14
 
15
15
  try {
16
- const { buildPackageDecision, inspectPackageWrite } =
17
- await import('../../src/hooks/guard-package.ts');
18
- const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
16
+ const { PackageGuard } = await import('../../src/hooks/guard-package.ts');
17
+ const { ManifestGuard } = await import('../../src/hooks/guard-manifest.ts');
19
18
  const stdin = await Bun.stdin.text();
20
- const input = parseManifestHookInput({ text: stdin });
21
- const verdict = input && inspectPackageWrite({ input });
19
+ const input = ManifestGuard.parseHookInput({ text: stdin });
20
+ const verdict = input && PackageGuard.inspectWrite({ input });
22
21
 
23
22
  if (verdict) {
24
- console.log(JSON.stringify(buildPackageDecision({ verdict })));
23
+ console.log(JSON.stringify(PackageGuard.buildDecision({ verdict })));
25
24
  }
26
25
  } catch (error) {
27
26
  console.error(
@@ -11,9 +11,8 @@
11
11
  export {};
12
12
 
13
13
  try {
14
- const { buildRemoteDecision, inspectRemoteCommand, parseTrustedList } =
15
- await import('../../src/hooks/remote-hosts.ts');
16
- const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
14
+ const { RemoteHosts } = await import('../../src/hooks/remote-hosts.ts');
15
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
17
16
  const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
18
17
  const manifestFile = Bun.file(`${root}/.agents/vulcan.manifest.json`);
19
18
 
@@ -39,12 +38,12 @@ try {
39
38
  const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
40
39
  const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
41
40
  const stdin = await Bun.stdin.text();
42
- const hookCommand = parseHookCommand({ text: stdin });
41
+ const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
43
42
  const hits = hookCommand
44
- ? inspectRemoteCommand({
43
+ ? RemoteHosts.inspectCommand({
45
44
  command: hookCommand.command,
46
45
  policy: {
47
- trusted: [...trusted, ...parseTrustedList({ text: personal })],
46
+ trusted: [...trusted, ...RemoteHosts.parseTrustedList({ text: personal })],
48
47
  readOnly,
49
48
  ...(localFile === undefined ? {} : { localFile }),
50
49
  },
@@ -52,7 +51,7 @@ try {
52
51
  : [{ rule: 'remote-hosts', message: 'the hook input could not be read' }];
53
52
 
54
53
  if (hits.length > 0) {
55
- console.log(JSON.stringify(buildRemoteDecision({ hits })));
54
+ console.log(JSON.stringify(RemoteHosts.buildDecision({ hits })));
56
55
  }
57
56
  } catch (error) {
58
57
  console.error(
@@ -17,14 +17,13 @@ if (process.env.VULCAN_GUARDS === 'off') {
17
17
  }
18
18
 
19
19
  try {
20
- const { buildScriptingAdvice, inspectScripting } =
21
- await import('../../src/hooks/guard-scripting.ts');
22
- const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
20
+ const { ScriptingGuard } = await import('../../src/hooks/guard-scripting.ts');
21
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
23
22
  const stdin = await Bun.stdin.text();
24
- const hookCommand = parseHookCommand({ text: stdin });
23
+ const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
25
24
 
26
- if (hookCommand && inspectScripting({ command: hookCommand.command }).length > 0) {
27
- console.log(JSON.stringify(buildScriptingAdvice()));
25
+ if (hookCommand && ScriptingGuard.inspect({ command: hookCommand.command }).length > 0) {
26
+ console.log(JSON.stringify(ScriptingGuard.buildAdvice()));
28
27
  }
29
28
  } catch (error) {
30
29
  console.error(
@@ -17,11 +17,10 @@
17
17
  export {};
18
18
 
19
19
  try {
20
- const { buildGuardDecision, inspectCommand, parseHookCommand } =
21
- await import('../../src/hooks/guard-writes.ts');
22
- const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
20
+ const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
21
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
23
22
  const stdin = await Bun.stdin.text();
24
- const hookCommand = parseHookCommand({ text: stdin });
23
+ const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
25
24
  const cwd = hookCommand?.cwd ?? process.cwd();
26
25
  let scripts: string[] = [];
27
26
 
@@ -29,8 +28,8 @@ try {
29
28
  // own, and may fail alone.
30
29
  if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
31
30
  try {
32
- const { loadConfig } = await import('../../src/config/index.ts');
33
- const loaded = await loadConfig({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
31
+ const { ConfigLoader } = await import('../../src/config/index.ts');
32
+ const loaded = await ConfigLoader.load({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
34
33
 
35
34
  // The objects are the read-only entries: the manifest carries them, so only the paths count here.
36
35
  scripts = loaded.ok
@@ -46,9 +45,9 @@ try {
46
45
  }
47
46
 
48
47
  const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
49
- const policy = readGuardPolicy({ root });
48
+ const policy = ProjectGuards.readPolicy({ root });
50
49
  const hits = hookCommand
51
- ? inspectCommand({
50
+ ? WriteGuard.inspectCommand({
52
51
  command: hookCommand.command,
53
52
  cwd,
54
53
  trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
@@ -57,7 +56,7 @@ try {
57
56
  : [];
58
57
 
59
58
  if (hits.length > 0) {
60
- console.log(JSON.stringify(buildGuardDecision({ hits })));
59
+ console.log(JSON.stringify(WriteGuard.buildDecision({ hits })));
61
60
  }
62
61
  } catch (error) {
63
62
  console.error(
@@ -14,9 +14,9 @@ if (process.env.VULCAN_GUARDS === 'off') {
14
14
  }
15
15
 
16
16
  try {
17
- const { buildPostToolOutput } = await import('../../src/hooks/post-tool.ts');
17
+ const { PostToolOutput } = await import('../../src/hooks/post-tool.ts');
18
18
  const stdin = await Bun.stdin.text();
19
- const output = buildPostToolOutput({
19
+ const output = PostToolOutput.build({
20
20
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
21
21
  input: JSON.parse(stdin),
22
22
  });
@@ -14,7 +14,7 @@ if (process.env.VULCAN_GUARDS === 'off') {
14
14
  }
15
15
 
16
16
  try {
17
- const { buildPromptContract } = await import('../../src/hooks/owner-reply.ts');
17
+ const { OwnerReply } = await import('../../src/hooks/owner-reply.ts');
18
18
  let session = '';
19
19
 
20
20
  try {
@@ -33,7 +33,7 @@ try {
33
33
  // No readable event: the turn is noted for no session, and nothing is echoed.
34
34
  }
35
35
 
36
- const line = await buildPromptContract({
36
+ const line = await OwnerReply.buildPromptContract({
37
37
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
38
38
  session,
39
39
  });
@@ -3,17 +3,17 @@
3
3
  * Stdout becomes session context. With `VULCAN_OWNER_REPLY=off` the owner shape and profile cards are left out.
4
4
  * It also exports `TMPDIR` (the project's `.agents/local/tmp`) into the file Claude Code sources before each Bash command.
5
5
  */
6
- import { buildSessionDigest, exportProjectTmp } from '../../src/hooks/index.ts';
6
+ import { ProjectTmp, SessionDigest } from '../../src/hooks/index.ts';
7
7
 
8
8
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
9
9
 
10
- const digest = await buildSessionDigest({ projectRoot });
10
+ const digest = await SessionDigest.build({ projectRoot });
11
11
 
12
12
  process.stdout.write(digest);
13
13
 
14
14
  // Claude Code gives this hook a file it sources before each Bash command: the project's temp folder goes in it.
15
15
  try {
16
- exportProjectTmp({ root: projectRoot, envFile: process.env.CLAUDE_ENV_FILE });
16
+ ProjectTmp.exportProjectTmp({ root: projectRoot, envFile: process.env.CLAUDE_ENV_FILE });
17
17
  } catch (error) {
18
18
  console.error(
19
19
  `vulcan: [session-start] could not make TMPDIR the project's temp folder: ${error}`,
@@ -17,9 +17,9 @@ if (process.env.VULCAN_GUARDS === 'off') {
17
17
  }
18
18
 
19
19
  try {
20
- const { buildStopOutput } = await import('../../src/hooks/owner-reply.ts');
20
+ const { OwnerReply } = await import('../../src/hooks/owner-reply.ts');
21
21
  const stdin = await Bun.stdin.text();
22
- const output = await buildStopOutput({
22
+ const output = await OwnerReply.buildStopOutput({
23
23
  projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
24
24
  input: JSON.parse(stdin),
25
25
  });
@@ -8,9 +8,9 @@
8
8
  export {};
9
9
 
10
10
  try {
11
- const { buildSubagentStartOutput } = await import('../../src/hooks/subagent-card.ts');
11
+ const { SubagentCard } = await import('../../src/hooks/subagent-card.ts');
12
12
 
13
- console.log(JSON.stringify(buildSubagentStartOutput()));
13
+ console.log(JSON.stringify(SubagentCard.buildStartOutput()));
14
14
  } catch (error) {
15
15
  console.error(
16
16
  `vulcan: the subagent-start hook could not build the card (${error instanceof Error ? error.message : String(error)}) - the subagent starts without it`,
@@ -92,9 +92,11 @@ and says so.
92
92
  `packages[].name`, of every package the entry covers: `packages: ['@scope/core']`. An entry that covers
93
93
  no package is internal work, and internal work has no entry. Never leave the list out -
94
94
  `okf check --strict` fails the entry.
95
- 3. **The content.** Short, and in the user's terms: what changed and the benefit, who is affected, how to
95
+ 3. **The title.** A plain sentence that names what changed, with no product name, no version and no
96
+ placeholder (never a literal `X.Y.Z`); the entry's heading repeats it.
97
+ 4. **The content.** Short, and in the user's terms: what changed and the benefit, who is affected, how to
96
98
  migrate. It is not a commit log, and it does not say how the change was built.
97
- 4. **The index.** When the directory's `index.md` lists entries, add a row in its order.
99
+ 5. **The index.** When the directory's `index.md` lists entries, add a row in its order.
98
100
 
99
101
  ## 6. Gates - validate, fix, repeat
100
102
 
@@ -111,6 +111,15 @@ sun and moon switch in the top bar flips them), the page is complete with the sc
111
111
  hover or focus on a box shows its detail, Next steps through the lit boxes, the **Present** button (or
112
112
  `?present=1`) walks the sections as slides with the arrow keys and Escape leaves, and the console is clean.
113
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
+
114
123
  If you could not open it, say "not browser-checked". Never describe a page as checked when only the
115
124
  command ran.
116
125
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.9-0",
3
+ "version": "0.4.9-2",
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,8 +44,8 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.9-0",
48
- "@venizia/vulcan-okf": "0.4.9-0",
47
+ "@venizia/vulcan-atlas": "0.4.9-2",
48
+ "@venizia/vulcan-okf": "0.4.9-2",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
@@ -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
+ }