@venizia/vulcan 0.4.8 → 0.4.9-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,13 +1,9 @@
1
1
  import {
2
- appendSignal,
3
- callKeyOf,
4
2
  EntryKinds,
5
- gatesOf,
6
- isPublicProbe,
7
- loopOf,
8
- readSignals,
3
+ SignalClassifier,
9
4
  SignalConstants,
10
- watchedFileOf,
5
+ SignalLoop,
6
+ SignalState,
11
7
  WatchedKinds,
12
8
  } from '../signals/index.ts';
13
9
  import type { ISignalState } from '../signals/index.ts';
@@ -36,102 +32,107 @@ const reportsFailure = (opts: { response: Record<string, unknown> }): boolean =>
36
32
  );
37
33
  };
38
34
 
39
- /**
40
- * What the model is told after a tool call, and the line it adds to the turn's notes: whether the turn
41
- * asked public state, which gate commands ran and passed or failed, the calls themselves, so a loop shows.
42
- * It speaks only to say that the agent seems stuck, or that a skill or rules file was just changed; it
43
- * never blocks. Notes are kept per session, and a loop per agent. Input it cannot read gives no answer.
44
- */
45
- export const buildPostToolOutput = (opts: {
46
- projectRoot: string;
47
- input: unknown;
48
- now?: number;
49
- }): Record<string, unknown> | undefined => {
50
- const input = recordOf({ value: opts.input });
51
- const tool = stringOf({ value: input['tool_name'] });
52
-
53
- if (tool === '') {
54
- return undefined;
55
- }
56
-
57
- const now = opts.now ?? Date.now();
58
- const session = stringOf({ value: input['session_id'] });
59
- const agent = stringOf({ value: input['agent_id'] });
60
- const toolInput = recordOf({ value: input['tool_input'] });
61
- const event = input['hook_event_name'] === FAILURE_EVENT ? FAILURE_EVENT : 'PostToolUse';
62
- const isOk =
63
- event !== FAILURE_EVENT &&
64
- !reportsFailure({ response: recordOf({ value: input['tool_response'] }) });
65
- const command = stringOf({ value: toolInput['command'] });
66
- // A command sent to the background has not finished: its result is not known here.
67
- const isBackground = toolInput['run_in_background'] === true;
68
- const path = stringOf({ value: toolInput['file_path'] });
69
- const gates = tool === 'Bash' && !isBackground ? gatesOf({ command }) : [];
70
-
71
- try {
72
- appendSignal({
73
- root: opts.projectRoot,
74
- entry: {
75
- kind: EntryKinds.CALL,
76
- session,
77
- agent,
78
- at: now,
79
- tool,
80
- key: callKeyOf({ tool, input: toolInput }),
81
- isOk,
82
- isProbe: tool === 'Bash' && isOk && isPublicProbe({ command }),
83
- gates,
84
- isEdit: FILE_TOOLS.has(tool) && isOk,
85
- },
86
- });
87
- } catch {
88
- // The notes are advisory: a failed write costs a hint, never the call.
89
- }
90
-
91
- const state: ISignalState = readSignals({ root: opts.projectRoot, session, agent });
92
- const lines: string[] = [];
93
- const say = (name: string, line: string): void => {
94
- const last = state.notedAt[name];
95
-
96
- if (last !== undefined && now - last < SignalConstants.DEBOUNCE_MS) {
97
- return;
35
+ export class PostToolOutput {
36
+ /**
37
+ * What the model is told after a tool call, and the line it adds to the turn's notes: whether the turn
38
+ * asked public state, which gate commands ran and passed or failed, the calls themselves, so a loop shows.
39
+ * It speaks only to say that the agent seems stuck, or that a skill or rules file was just changed; it
40
+ * never blocks. Notes are kept per session, and a loop per agent. Input it cannot read gives no answer.
41
+ */
42
+ static build(opts: {
43
+ projectRoot: string;
44
+ input: unknown;
45
+ now?: number;
46
+ }): Record<string, unknown> | undefined {
47
+ const input = recordOf({ value: opts.input });
48
+ const tool = stringOf({ value: input['tool_name'] });
49
+
50
+ if (tool === '') {
51
+ return undefined;
98
52
  }
99
53
 
100
- lines.push(line);
54
+ const now = opts.now ?? Date.now();
55
+ const session = stringOf({ value: input['session_id'] });
56
+ const agent = stringOf({ value: input['agent_id'] });
57
+ const toolInput = recordOf({ value: input['tool_input'] });
58
+ const event = input['hook_event_name'] === FAILURE_EVENT ? FAILURE_EVENT : 'PostToolUse';
59
+ const isOk =
60
+ event !== FAILURE_EVENT &&
61
+ !reportsFailure({ response: recordOf({ value: input['tool_response'] }) });
62
+ const command = stringOf({ value: toolInput['command'] });
63
+ // A command sent to the background has not finished: its result is not known here.
64
+ const isBackground = toolInput['run_in_background'] === true;
65
+ const path = stringOf({ value: toolInput['file_path'] });
66
+ const gates = tool === 'Bash' && !isBackground ? SignalClassifier.gatesOf({ command }) : [];
101
67
 
102
68
  try {
103
- appendSignal({ root: opts.projectRoot, entry: { kind: EntryKinds.NOTE, at: now, name } });
69
+ SignalState.append({
70
+ root: opts.projectRoot,
71
+ entry: {
72
+ kind: EntryKinds.CALL,
73
+ session,
74
+ agent,
75
+ at: now,
76
+ tool,
77
+ key: SignalClassifier.callKeyOf({ tool, input: toolInput }),
78
+ isOk,
79
+ isProbe: tool === 'Bash' && isOk && SignalClassifier.isPublicProbe({ command }),
80
+ gates,
81
+ isEdit: FILE_TOOLS.has(tool) && isOk,
82
+ },
83
+ });
104
84
  } catch {
105
- // Without the note the advisory may repeat; nothing worse.
85
+ // The notes are advisory: a failed write costs a hint, never the call.
106
86
  }
107
- };
108
87
 
109
- if (FILE_TOOLS.has(tool) && isOk) {
110
- const watched = watchedFileOf({ path });
88
+ const state: ISignalState = SignalState.read({ root: opts.projectRoot, session, agent });
89
+ const lines: string[] = [];
90
+ const say = (name: string, line: string): void => {
91
+ const last = state.notedAt[name];
92
+
93
+ if (last !== undefined && now - last < SignalConstants.DEBOUNCE_MS) {
94
+ return;
95
+ }
96
+
97
+ lines.push(line);
98
+
99
+ try {
100
+ SignalState.append({
101
+ root: opts.projectRoot,
102
+ entry: { kind: EntryKinds.NOTE, at: now, name },
103
+ });
104
+ } catch {
105
+ // Without the note the advisory may repeat; nothing worse.
106
+ }
107
+ };
108
+
109
+ if (FILE_TOOLS.has(tool) && isOk) {
110
+ const watched = SignalClassifier.watchedFileOf({ path });
111
+
112
+ if (watched?.kind === WatchedKinds.SKILL) {
113
+ say(
114
+ `skill:${watched.name}`,
115
+ `You changed the skill ${watched.name}. Before you rely on it, run its evals (evals/evals.json) and read the transcripts: a skill change that no eval saw is a guess.`,
116
+ );
117
+ } else if (watched?.kind === WatchedKinds.RULES) {
118
+ say(
119
+ `rules:${watched.name}`,
120
+ 'You changed a rules file. A rule needs an observed failure and a named enforcement, and a mechanical check where one is possible (the retro skill states the admission bar).',
121
+ );
122
+ }
123
+ }
111
124
 
112
- if (watched?.kind === WatchedKinds.SKILL) {
113
- say(
114
- `skill:${watched.name}`,
115
- `You changed the skill ${watched.name}. Before you rely on it, run its evals (evals/evals.json) and read the transcripts: a skill change that no eval saw is a guess.`,
116
- );
117
- } else if (watched?.kind === WatchedKinds.RULES) {
125
+ const loop = SignalLoop.loopOf({ events: state.events });
126
+
127
+ if (loop !== undefined) {
118
128
  say(
119
- `rules:${watched.name}`,
120
- 'You changed a rules file. A rule needs an observed failure and a named enforcement, and a mechanical check where one is possible (the retro skill states the admission bar).',
129
+ `loop:${agent}`,
130
+ `Loop check: ${loop}. Stop repeating it: read the error, change the approach (the fix-a-bug skill builds the loop first), or ask the owner.`,
121
131
  );
122
132
  }
123
- }
124
133
 
125
- const loop = loopOf({ events: state.events });
126
-
127
- if (loop !== undefined) {
128
- say(
129
- `loop:${agent}`,
130
- `Loop check: ${loop}. Stop repeating it: read the error, change the approach (the fix-a-bug skill builds the loop first), or ask the owner.`,
131
- );
134
+ return lines.length === 0
135
+ ? undefined
136
+ : { hookSpecificOutput: { hookEventName: event, additionalContext: lines.join(' ') } };
132
137
  }
133
-
134
- return lines.length === 0
135
- ? undefined
136
- : { hookSpecificOutput: { hookEventName: event, additionalContext: lines.join(' ') } };
137
- };
138
+ }
@@ -1,5 +1,6 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
+ import type { IReadOnlyScript } from './common/index.ts';
3
4
 
4
5
  /** A command the project says is a database write or a deploy: guard-writes asks on a match. */
5
6
  export interface IProjectCommandCheck {
@@ -9,13 +10,15 @@ export interface IProjectCommandCheck {
9
10
  }
10
11
 
11
12
  /** What the project adds to the guards: the manifest's `guard` block, compiled. */
12
- export interface IGuardPolicy {
13
+ interface IGuardPolicy {
13
14
  commands: IProjectCommandCheck[];
14
15
  askPush: string[];
16
+ /** `guard.writes.readOnlyScripts`; absent when the manifest lists none. */
17
+ readOnlyScripts?: IReadOnlyScript[];
15
18
  }
16
19
 
17
- /** Spelt out: the blocking hooks import nothing that reads the package (a test holds it equal to the manifest's name). */
18
- export const GUARD_MANIFEST_FILE = '.agents/vulcan.manifest.json';
20
+ /** Spelt out: the blocking hooks import nothing that reads the package. */
21
+ const GUARD_MANIFEST_FILE = '.agents/vulcan.manifest.json';
19
22
 
20
23
  const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
21
24
  typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
@@ -61,63 +64,98 @@ const commandOf = (opts: { value: unknown }): IProjectCommandCheck | undefined =
61
64
  }
62
65
  };
63
66
 
64
- /**
65
- * The commands and push targets a project lists, from the committed manifest (`vulcan sync` renders
66
- * them from the config), so a hook reads them with no config loader and no zod. A project with no
67
- * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
68
- * stderr, and the others stay.
69
- */
70
- export const readGuardPolicy = (opts: { root: string }): IGuardPolicy => {
71
- const path = join(opts.root, GUARD_MANIFEST_FILE);
72
- const empty: IGuardPolicy = { commands: [], askPush: [] };
73
-
74
- if (!existsSync(path)) {
75
- return empty;
76
- }
77
-
78
- let manifest: unknown;
79
-
80
- try {
81
- manifest = JSON.parse(readFileSync(path, 'utf8'));
82
- } catch (error) {
67
+ const readOnlyScriptOf = (opts: { value: unknown }): IReadOnlyScript | undefined => {
68
+ const holder = { value: opts.value };
69
+ const script = isRecord(holder) ? holder.value['script'] : undefined;
70
+ const listed = isRecord(holder) ? holder.value['readOnly'] : undefined;
71
+ const words = Array.isArray(listed)
72
+ ? listed.filter((word): word is string => typeof word === 'string' && word !== '')
73
+ : [];
74
+
75
+ if (
76
+ typeof script !== 'string' ||
77
+ script === '' ||
78
+ !Array.isArray(listed) ||
79
+ words.length !== listed.length
80
+ ) {
83
81
  note({
84
- message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
82
+ message:
83
+ 'ignoring a guard.writes.readOnlyScripts entry that has no script or no readOnly list of words',
85
84
  });
86
85
 
87
- return empty;
86
+ return undefined;
88
87
  }
89
88
 
90
- const top = { value: manifest };
91
- const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
89
+ return { script, readOnly: words };
90
+ };
91
+
92
+ export class ProjectGuards {
93
+ /**
94
+ * The commands, push targets and read-only scripts a project lists, from the committed manifest (`vulcan sync` renders
95
+ * them from the config), so a hook reads them with no config loader and no zod. A project with no
96
+ * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
97
+ * stderr, and the others stay.
98
+ */
99
+ static readPolicy(opts: { root: string }): IGuardPolicy {
100
+ const path = join(opts.root, GUARD_MANIFEST_FILE);
101
+ const empty: IGuardPolicy = { commands: [], askPush: [] };
102
+
103
+ if (!existsSync(path)) {
104
+ return empty;
105
+ }
106
+
107
+ let manifest: unknown;
108
+
109
+ try {
110
+ manifest = JSON.parse(readFileSync(path, 'utf8'));
111
+ } catch (error) {
112
+ note({
113
+ message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
114
+ });
115
+
116
+ return empty;
117
+ }
118
+
119
+ const top = { value: manifest };
120
+ const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
121
+
122
+ if (!isRecord(guard)) {
123
+ return empty;
124
+ }
125
+
126
+ const writes = { value: guard.value['writes'] };
127
+ const git = { value: guard.value['git'] };
128
+ const listed = isRecord(writes) ? writes.value['commands'] : undefined;
129
+ const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
130
+ const targets = isRecord(git) ? git.value['askPush'] : undefined;
131
+ const readOnlyScripts = (Array.isArray(scripts) ? scripts : []).flatMap((entry) => {
132
+ const script = readOnlyScriptOf({ value: entry });
133
+
134
+ return script === undefined ? [] : [script];
135
+ });
92
136
 
93
- if (!isRecord(guard)) {
94
- return empty;
137
+ return {
138
+ commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
139
+ const check = commandOf({ value: entry });
140
+
141
+ return check === undefined ? [] : [check];
142
+ }),
143
+ askPush: (Array.isArray(targets) ? targets : []).filter(
144
+ (target): target is string => typeof target === 'string' && target !== '',
145
+ ),
146
+ ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
147
+ };
95
148
  }
96
149
 
97
- const writes = { value: guard.value['writes'] };
98
- const git = { value: guard.value['git'] };
99
- const listed = isRecord(writes) ? writes.value['commands'] : undefined;
100
- const targets = isRecord(git) ? git.value['askPush'] : undefined;
101
-
102
- return {
103
- commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
104
- const check = commandOf({ value: entry });
105
-
106
- return check === undefined ? [] : [check];
107
- }),
108
- askPush: (Array.isArray(targets) ? targets : []).filter(
109
- (target): target is string => typeof target === 'string' && target !== '',
110
- ),
111
- };
112
- };
113
-
114
- /** Whether a branch name is one of the listed names; `*` stands for any run of characters, nothing else is special. */
115
- export const matchesBranch = (opts: { name: string; patterns: string[] }): boolean =>
116
- opts.patterns.some((pattern) =>
117
- new RegExp(
118
- `^${pattern
119
- .split('*')
120
- .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
121
- .join('.*')}$`,
122
- ).test(opts.name),
123
- );
150
+ /** Whether a branch name is one of the listed names; `*` stands for any run of characters, nothing else is special. */
151
+ static matchesBranch(opts: { name: string; patterns: string[] }): boolean {
152
+ return opts.patterns.some((pattern) =>
153
+ new RegExp(
154
+ `^${pattern
155
+ .split('*')
156
+ .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
157
+ .join('.*')}$`,
158
+ ).test(opts.name),
159
+ );
160
+ }
161
+ }
@@ -2,35 +2,38 @@ import { appendFileSync, mkdirSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { HookConstants } from './common/index.ts';
4
4
 
5
- /** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
6
- export const projectTmpOf = (opts: { root: string }): string =>
7
- join(opts.root, HookConstants.PROJECT_TMP);
8
-
9
5
  /** A word for `sh`, whatever it holds: in single quotes, a quote itself closed, escaped and opened again. */
10
6
  const shellQuote = (opts: { text: string }): string => `'${opts.text.replaceAll("'", "'\\''")}'`;
11
7
 
12
- /**
13
- * Makes every Bash command of a Claude Code session run with `TMPDIR` in the project. Claude Code hands a
14
- * SessionStart hook a file (`CLAUDE_ENV_FILE`) and sources it before each Bash command, so one `export`
15
- * there is enough: `mktemp`, bun, node and every script a command starts then use the project folder. It
16
- * does not move Claude Code's own task-output files or an MCP server (those need the launch file), and
17
- * `TMPDIR` in the project's settings `env` is not applied by Claude Code, which is why this is a hook.
18
- * Returns whether it wrote; with no file (another agent, a run outside Claude Code) it does nothing. A
19
- * path with a line break is refused: a line of shell must never be made from a folder name.
20
- */
21
- export const exportProjectTmp = (opts: { root: string; envFile: string | undefined }): boolean => {
22
- if (opts.envFile === undefined || opts.envFile === '') {
23
- return false;
8
+ export class ProjectTmp {
9
+ /** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
10
+ static projectOf(opts: { root: string }): string {
11
+ return join(opts.root, HookConstants.PROJECT_TMP);
24
12
  }
25
13
 
26
- const folder = projectTmpOf({ root: opts.root });
14
+ /**
15
+ * Makes every Bash command of a Claude Code session run with `TMPDIR` in the project. Claude Code hands a
16
+ * SessionStart hook a file (`CLAUDE_ENV_FILE`) and sources it before each Bash command, so one `export`
17
+ * there is enough: `mktemp`, bun, node and every script a command starts then use the project folder. It
18
+ * does not move Claude Code's own task-output files or an MCP server (those need the launch file), and
19
+ * `TMPDIR` in the project's settings `env` is not applied by Claude Code, which is why this is a hook.
20
+ * Returns whether it wrote; with no file (another agent, a run outside Claude Code) it does nothing. A
21
+ * path with a line break is refused: a line of shell must never be made from a folder name.
22
+ */
23
+ static exportProjectTmp(opts: { root: string; envFile: string | undefined }): boolean {
24
+ if (opts.envFile === undefined || opts.envFile === '') {
25
+ return false;
26
+ }
27
27
 
28
- if (/[\r\n]/.test(folder)) {
29
- return false;
30
- }
28
+ const folder = ProjectTmp.projectOf({ root: opts.root });
31
29
 
32
- mkdirSync(folder, { recursive: true });
33
- appendFileSync(opts.envFile, `export TMPDIR=${shellQuote({ text: folder })}\n`);
30
+ if (/[\r\n]/.test(folder)) {
31
+ return false;
32
+ }
34
33
 
35
- return true;
36
- };
34
+ mkdirSync(folder, { recursive: true });
35
+ appendFileSync(opts.envFile, `export TMPDIR=${shellQuote({ text: folder })}\n`);
36
+
37
+ return true;
38
+ }
39
+ }