@venizia/vulcan 0.4.9-0 → 0.4.9-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) 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/visualize-work/SKILL.md +9 -0
  17. package/package.json +3 -3
  18. package/src/agents/atlas-block.ts +43 -43
  19. package/src/agents/codex-hooks.ts +45 -43
  20. package/src/agents/detect.ts +19 -16
  21. package/src/agents/exclude.ts +96 -97
  22. package/src/agents/hooks-json.ts +38 -36
  23. package/src/agents/local.ts +46 -43
  24. package/src/agents/prompt.ts +45 -42
  25. package/src/agents/render.ts +201 -195
  26. package/src/agents/resolve.ts +133 -134
  27. package/src/agents/table.ts +12 -8
  28. package/src/commands/add.command.ts +2 -2
  29. package/src/commands/agents.command.ts +11 -17
  30. package/src/commands/clean.command.ts +6 -6
  31. package/src/commands/doctor.command.ts +4 -4
  32. package/src/commands/init.command.ts +12 -8
  33. package/src/commands/preset.command.ts +2 -2
  34. package/src/commands/profile.command.ts +42 -49
  35. package/src/commands/sync.command.ts +109 -111
  36. package/src/commands/upgrade.command.ts +80 -75
  37. package/src/commands/visualize.command.ts +7 -13
  38. package/src/commands/x.command.ts +55 -50
  39. package/src/common/format.ts +23 -21
  40. package/src/common/json.ts +8 -5
  41. package/src/common/layout-folder.ts +94 -91
  42. package/src/common/paths.ts +14 -12
  43. package/src/config/loader.ts +52 -49
  44. package/src/config/packages.ts +14 -11
  45. package/src/config/schema.ts +3 -3
  46. package/src/create/add-app.ts +519 -509
  47. package/src/create/add-lib.ts +237 -240
  48. package/src/create/bunfig.ts +26 -23
  49. package/src/create/checks.ts +36 -34
  50. package/src/create/diff.ts +21 -23
  51. package/src/create/dockerignore.ts +26 -24
  52. package/src/create/files.ts +7 -5
  53. package/src/create/init-monorepo.ts +75 -80
  54. package/src/create/lib-preset.ts +59 -63
  55. package/src/create/manifest-json.ts +10 -4
  56. package/src/create/names.ts +217 -210
  57. package/src/create/next.ts +26 -23
  58. package/src/create/plan.ts +15 -12
  59. package/src/create/preset-diff.ts +301 -303
  60. package/src/create/preset-menu.ts +38 -32
  61. package/src/create/preset.ts +202 -197
  62. package/src/create/process.ts +79 -72
  63. package/src/create/scratch.ts +48 -49
  64. package/src/create/workspace.ts +404 -396
  65. package/src/doctor/checks.ts +1027 -1014
  66. package/src/doctor/makefile.ts +17 -13
  67. package/src/doctor/runner.ts +88 -118
  68. package/src/doctor/skills.ts +97 -95
  69. package/src/doctor/tags.ts +42 -37
  70. package/src/hooks/codex-patch.ts +25 -22
  71. package/src/hooks/command-view.ts +44 -39
  72. package/src/hooks/decision.ts +37 -37
  73. package/src/hooks/guard-git.ts +51 -49
  74. package/src/hooks/guard-manifest.ts +58 -55
  75. package/src/hooks/guard-outside.ts +93 -91
  76. package/src/hooks/guard-package.ts +82 -79
  77. package/src/hooks/guard-scripting.ts +19 -14
  78. package/src/hooks/guard-writes.ts +154 -149
  79. package/src/hooks/owner-reply.ts +127 -127
  80. package/src/hooks/post-tool.ts +94 -93
  81. package/src/hooks/project-guards.ts +65 -62
  82. package/src/hooks/project-tmp.ts +27 -24
  83. package/src/hooks/remote-hosts.ts +153 -130
  84. package/src/hooks/session-digest.ts +98 -101
  85. package/src/hooks/shell.ts +509 -499
  86. package/src/hooks/subagent-card.ts +11 -7
  87. package/src/hooks/trusted-scripts.ts +106 -104
  88. package/src/init/scaffold.ts +135 -132
  89. package/src/local/clean.ts +38 -36
  90. package/src/local/format.ts +21 -17
  91. package/src/local/scan.ts +144 -138
  92. package/src/manifest/render.ts +110 -104
  93. package/src/owner/card.ts +51 -46
  94. package/src/owner/profile.ts +99 -93
  95. package/src/owner/reply-switch.ts +9 -6
  96. package/src/owner/shape.ts +71 -69
  97. package/src/owner/survey.ts +173 -171
  98. package/src/owner/view.ts +62 -59
  99. package/src/owner/violations.ts +119 -123
  100. package/src/rules/base.ts +15 -11
  101. package/src/rules/parser.ts +39 -32
  102. package/src/rules/slots.ts +8 -6
  103. package/src/signals/claims.ts +30 -28
  104. package/src/signals/classify.ts +36 -33
  105. package/src/signals/loop.ts +39 -37
  106. package/src/signals/state.ts +79 -81
  107. package/src/skills/frontmatter.ts +28 -28
  108. package/src/sync/agent-files.ts +217 -199
  109. package/src/sync/agent-removal.ts +56 -59
  110. package/src/sync/atlas-block.ts +45 -43
  111. package/src/sync/base-rules.ts +32 -30
  112. package/src/sync/claude-launch.ts +36 -34
  113. package/src/sync/exclude.ts +77 -69
  114. package/src/sync/local-choice.ts +50 -47
  115. package/src/sync/planner.ts +59 -61
  116. package/src/sync/prune.ts +52 -48
  117. package/src/sync/settings.ts +166 -167
  118. package/src/ui/capability.ts +12 -7
  119. package/src/ui/keyboard.ts +38 -38
  120. package/src/ui/prompt.ts +79 -77
  121. package/src/visualize/assets.ts +33 -24
  122. package/src/visualize/charts.ts +179 -176
  123. package/src/visualize/compare-css.ts +3 -2
  124. package/src/visualize/compare-render.ts +9 -7
  125. package/src/visualize/diagrams.ts +189 -174
  126. package/src/visualize/grid-span.ts +34 -0
  127. package/src/visualize/icons.ts +7 -5
  128. package/src/visualize/kinds-render.ts +50 -45
  129. package/src/visualize/kinds-validate.ts +12 -10
  130. package/src/visualize/labels.ts +21 -17
  131. package/src/visualize/layout.ts +112 -97
  132. package/src/visualize/page.ts +92 -104
  133. package/src/visualize/render.ts +143 -140
  134. package/src/visualize/sections.ts +395 -384
  135. package/src/visualize/sources.ts +2 -2
  136. package/src/visualize/theme.ts +12 -10
  137. package/src/visualize/validate.ts +13 -9
  138. package/src/wiki/anchors.ts +38 -36
  139. package/src/wiki/command.ts +4 -4
  140. 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`,
@@ -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-1",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -44,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-1",
48
+ "@venizia/vulcan-okf": "0.4.9-1",
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
+ }