@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
@@ -6,13 +6,10 @@ import {
6
6
  AgentGuardKinds,
7
7
  AgentRenderers,
8
8
  AgentScopes,
9
- atlasServerEntry,
10
- canonicalAtlasEntry,
11
- mergeCodexHooks,
12
- mergeCodexToml,
13
- mergeGuardHook,
14
- mergeMcpServers,
15
- readAgentTable,
9
+ AgentTable,
10
+ CodexHooks,
11
+ GuardHook,
12
+ McpConfig,
16
13
  } from '../agents/index.ts';
17
14
  import type { TAgentEntry } from '../agents/index.ts';
18
15
  import { SyncStatuses } from './common/index.ts';
@@ -20,31 +17,16 @@ import type { ISyncAction } from './common/index.ts';
20
17
 
21
18
  const NO_CHANGE = (): void => {};
22
19
 
23
- /** A file git tracks cannot be hidden by an exclude entry, and a per-developer edit would show as a diff. */
24
- export const isTracked = (opts: { root: string; path: string }): boolean => {
25
- try {
26
- return (
27
- Bun.spawnSync(['git', 'ls-files', '--error-unmatch', opts.path], {
28
- cwd: opts.root,
29
- stdout: 'ignore',
30
- stderr: 'ignore',
31
- }).exitCode === 0
32
- );
33
- } catch {
34
- return false;
35
- }
36
- };
37
-
38
20
  const merge = (opts: { entry: TAgentEntry; root: string; text: string | undefined }) => {
39
- const server = atlasServerEntry({ root: opts.root });
21
+ const server = McpConfig.atlasServerEntry({ root: opts.root });
40
22
 
41
23
  switch (opts.entry.mcp.renderer) {
42
24
  case AgentRenderers.CODEX_TOML: {
43
- return mergeCodexToml({ text: opts.text, root: opts.root });
25
+ return McpConfig.mergeCodexToml({ text: opts.text, root: opts.root });
44
26
  }
45
27
 
46
28
  case AgentRenderers.SERVERS: {
47
- return mergeMcpServers({
29
+ return McpConfig.mergeServers({
48
30
  text: opts.text,
49
31
  key: 'servers',
50
32
  entry: { type: 'stdio', ...server },
@@ -52,233 +34,269 @@ const merge = (opts: { entry: TAgentEntry; root: string; text: string | undefine
52
34
  }
53
35
 
54
36
  default: {
55
- return mergeMcpServers({ text: opts.text, key: 'mcpServers', entry: server });
37
+ return McpConfig.mergeServers({ text: opts.text, key: 'mcpServers', entry: server });
56
38
  }
57
39
  }
58
40
  };
59
41
 
60
- /** The atlas entry in the agent's own MCP file; an agent on the shared `.mcp.json` needs no file. */
61
- const planAgentMcp = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
62
- if (opts.entry.mcp.scope !== AgentScopes.PROJECT) {
63
- return [];
64
- }
42
+ export class AgentFiles {
43
+ /** The atlas entry in the agent's own MCP file; an agent on the shared `.mcp.json` needs no file. */
44
+ private static planAgentMcp(opts: { root: string; entry: TAgentEntry }): ISyncAction[] {
45
+ if (opts.entry.mcp.scope !== AgentScopes.PROJECT) {
46
+ return [];
47
+ }
65
48
 
66
- const path = join(opts.root, opts.entry.mcp.path);
67
- const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
68
- const merged = merge({ entry: opts.entry, root: opts.root, text });
49
+ const path = join(opts.root, opts.entry.mcp.path);
50
+ const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
51
+ const merged = merge({ entry: opts.entry, root: opts.root, text });
52
+
53
+ if (!merged.ok) {
54
+ return [
55
+ {
56
+ path,
57
+ status: SyncStatuses.SKIPPED,
58
+ note: `${merged.reason} - left untouched; fix it, then re-run sync`,
59
+ apply: NO_CHANGE,
60
+ },
61
+ ];
62
+ }
69
63
 
70
- if (!merged.ok) {
71
- return [
72
- {
73
- path,
74
- status: SyncStatuses.SKIPPED,
75
- note: `${merged.reason} - left untouched; fix it, then re-run sync`,
76
- apply: NO_CHANGE,
77
- },
78
- ];
79
- }
64
+ if (!merged.changed) {
65
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
66
+ }
80
67
 
81
- if (!merged.changed) {
82
- return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
83
- }
68
+ if (
69
+ text !== undefined &&
70
+ AgentFiles.isTracked({ root: opts.root, path: opts.entry.mcp.path })
71
+ ) {
72
+ return [
73
+ {
74
+ path,
75
+ status: SyncStatuses.SKIPPED,
76
+ note: `tracked by git - left alone; add the atlas server by hand: bun ${join(opts.root, 'node_modules', '.bin', 'vulcan')} x atlas mcp --root ${opts.root}`,
77
+ apply: NO_CHANGE,
78
+ },
79
+ ];
80
+ }
84
81
 
85
- if (text !== undefined && isTracked({ root: opts.root, path: opts.entry.mcp.path })) {
86
82
  return [
87
83
  {
88
84
  path,
89
- status: SyncStatuses.SKIPPED,
90
- note: `tracked by git - left alone; add the atlas server by hand: bun ${join(opts.root, 'node_modules', '.bin', 'vulcan')} x atlas mcp --root ${opts.root}`,
91
- apply: NO_CHANGE,
85
+ status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
86
+ apply: () => {
87
+ mkdirSync(dirname(path), { recursive: true });
88
+ writeFileSync(path, merged.text);
89
+ },
92
90
  },
93
91
  ];
94
92
  }
95
93
 
96
- return [
97
- {
98
- path,
99
- status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
100
- apply: () => {
101
- mkdirSync(dirname(path), { recursive: true });
102
- writeFileSync(path, merged.text);
103
- },
104
- },
105
- ];
106
- };
94
+ /**
95
+ * The root `.mcp.json` the chosen agents of the shared scope read: the canonical atlas entry, merged
96
+ * into what is there. A file git tracks belongs to the project, not to this machine: it is never
97
+ * rewritten (the doctor says how to hand it over).
98
+ */
99
+ private static planSharedMcp(opts: { root: string }): ISyncAction[] {
100
+ const path = join(opts.root, AgentConstants.SHARED_MCP_FILE);
101
+ const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
102
+ const merged = McpConfig.mergeServers({
103
+ text,
104
+ key: 'mcpServers',
105
+ entry: McpConfig.canonicalAtlasEntry(),
106
+ });
107
+
108
+ if (!merged.ok) {
109
+ return [
110
+ {
111
+ path,
112
+ status: SyncStatuses.SKIPPED,
113
+ note: `${merged.reason} - left untouched; fix it, then re-run sync`,
114
+ apply: NO_CHANGE,
115
+ },
116
+ ];
117
+ }
118
+
119
+ if (
120
+ !merged.changed ||
121
+ (text !== undefined &&
122
+ AgentFiles.isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE }))
123
+ ) {
124
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
125
+ }
107
126
 
108
- /**
109
- * The root `.mcp.json` the chosen agents of the shared scope read: the canonical atlas entry, merged
110
- * into what is there. A file git tracks belongs to the project, not to this machine: it is never
111
- * rewritten (the doctor says how to hand it over).
112
- */
113
- const planSharedMcp = (opts: { root: string }): ISyncAction[] => {
114
- const path = join(opts.root, AgentConstants.SHARED_MCP_FILE);
115
- const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
116
- const merged = mergeMcpServers({ text, key: 'mcpServers', entry: canonicalAtlasEntry() });
117
-
118
- if (!merged.ok) {
119
127
  return [
120
128
  {
121
129
  path,
122
- status: SyncStatuses.SKIPPED,
123
- note: `${merged.reason} - left untouched; fix it, then re-run sync`,
124
- apply: NO_CHANGE,
130
+ status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
131
+ apply: () => writeFileSync(path, merged.text),
125
132
  },
126
133
  ];
127
134
  }
128
135
 
129
- if (
130
- !merged.changed ||
131
- (text !== undefined && isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE }))
132
- ) {
133
- return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
134
- }
136
+ /**
137
+ * The guard extension of an agent that takes one (omp, pi): the shipped template, copied into the folder the
138
+ * agent loads extensions from. A file that does not start with sync's marker is the user's own, and a file
139
+ * git tracks belongs to the project: both are left alone and the line says so.
140
+ */
141
+ private static planGuardExtension(opts: { root: string; entry: TAgentEntry }): ISyncAction[] {
142
+ if (opts.entry.guards === null) {
143
+ return [];
144
+ }
135
145
 
136
- return [
137
- {
138
- path,
139
- status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
140
- apply: () => writeFileSync(path, merged.text),
141
- },
142
- ];
143
- };
146
+ const path = join(opts.root, opts.entry.guards.path);
147
+ const text = readFileSync(
148
+ join(BASE_DIRECTORY, AgentConstants.GUARD_EXTENSION_TEMPLATE),
149
+ 'utf8',
150
+ );
151
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
144
152
 
145
- /**
146
- * The guard extension of an agent that takes one (omp, pi): the shipped template, copied into the folder the
147
- * agent loads extensions from. A file that does not start with sync's marker is the user's own, and a file
148
- * git tracks belongs to the project: both are left alone and the line says so.
149
- */
150
- const planGuardExtension = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
151
- if (opts.entry.guards === null) {
152
- return [];
153
- }
153
+ if (before === text) {
154
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
155
+ }
154
156
 
155
- const path = join(opts.root, opts.entry.guards.path);
156
- const text = readFileSync(join(BASE_DIRECTORY, AgentConstants.GUARD_EXTENSION_TEMPLATE), 'utf8');
157
- const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
157
+ if (before !== undefined && !before.startsWith(AgentConstants.GUARD_EXTENSION_MARKER)) {
158
+ return [
159
+ {
160
+ path,
161
+ status: SyncStatuses.SKIPPED,
162
+ note: `a file of your own is there - left alone; copy node_modules/@venizia/vulcan/base/${AgentConstants.GUARD_EXTENSION_TEMPLATE} over it to add the guards`,
163
+ apply: NO_CHANGE,
164
+ },
165
+ ];
166
+ }
158
167
 
159
- if (before === text) {
160
- return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
161
- }
168
+ if (
169
+ before !== undefined &&
170
+ AgentFiles.isTracked({ root: opts.root, path: opts.entry.guards.path })
171
+ ) {
172
+ return [
173
+ {
174
+ path,
175
+ status: SyncStatuses.SKIPPED,
176
+ note: 'tracked by git - left alone; copy the shipped extension over it to update the guards',
177
+ apply: NO_CHANGE,
178
+ },
179
+ ];
180
+ }
162
181
 
163
- if (before !== undefined && !before.startsWith(AgentConstants.GUARD_EXTENSION_MARKER)) {
164
182
  return [
165
183
  {
166
184
  path,
167
- status: SyncStatuses.SKIPPED,
168
- note: `a file of your own is there - left alone; copy node_modules/@venizia/vulcan/base/${AgentConstants.GUARD_EXTENSION_TEMPLATE} over it to add the guards`,
169
- apply: NO_CHANGE,
185
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
186
+ apply: () => {
187
+ mkdirSync(dirname(path), { recursive: true });
188
+ writeFileSync(path, text);
189
+ },
170
190
  },
171
191
  ];
172
192
  }
173
193
 
174
- if (before !== undefined && isTracked({ root: opts.root, path: opts.entry.guards.path })) {
175
- return [
176
- {
177
- path,
178
- status: SyncStatuses.SKIPPED,
179
- note: 'tracked by git - left alone; copy the shipped extension over it to update the guards',
180
- apply: NO_CHANGE,
181
- },
182
- ];
183
- }
194
+ /**
195
+ * The guard hook in an agent's hooks file (Antigravity): one entry under a key of VULCAN's own, merged into
196
+ * what is there, every other hook left as written. A file that is not JSON, or that git tracks, is left alone.
197
+ */
198
+ private static planGuardHooksJson(opts: { root: string; entry: TAgentEntry }): ISyncAction[] {
199
+ if (opts.entry.guards === null) {
200
+ return [];
201
+ }
184
202
 
185
- return [
186
- {
187
- path,
188
- status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
189
- apply: () => {
190
- mkdirSync(dirname(path), { recursive: true });
191
- writeFileSync(path, text);
192
- },
193
- },
194
- ];
195
- };
203
+ const path = join(opts.root, opts.entry.guards.path);
204
+ const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
205
+ const merged =
206
+ opts.entry.guards.kind === AgentGuardKinds.CODEX_HOOKS
207
+ ? CodexHooks.merge({ text })
208
+ : GuardHook.merge({ text });
209
+
210
+ if (!merged.ok) {
211
+ return [
212
+ {
213
+ path,
214
+ status: SyncStatuses.SKIPPED,
215
+ note: `${merged.reason} - left untouched; fix it, then re-run sync`,
216
+ apply: NO_CHANGE,
217
+ },
218
+ ];
219
+ }
196
220
 
197
- /**
198
- * The guard hook in an agent's hooks file (Antigravity): one entry under a key of VULCAN's own, merged into
199
- * what is there, every other hook left as written. A file that is not JSON, or that git tracks, is left alone.
200
- */
201
- const planGuardHooksJson = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
202
- if (opts.entry.guards === null) {
203
- return [];
204
- }
221
+ if (!merged.changed) {
222
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
223
+ }
205
224
 
206
- const path = join(opts.root, opts.entry.guards.path);
207
- const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
208
- const merged =
209
- opts.entry.guards.kind === AgentGuardKinds.CODEX_HOOKS
210
- ? mergeCodexHooks({ text })
211
- : mergeGuardHook({ text });
225
+ if (
226
+ text !== undefined &&
227
+ AgentFiles.isTracked({ root: opts.root, path: opts.entry.guards.path })
228
+ ) {
229
+ return [
230
+ {
231
+ path,
232
+ status: SyncStatuses.SKIPPED,
233
+ note: 'tracked by git - left alone; add the VULCAN guard hook by hand (see the hooks reference)',
234
+ apply: NO_CHANGE,
235
+ },
236
+ ];
237
+ }
212
238
 
213
- if (!merged.ok) {
214
239
  return [
215
240
  {
216
241
  path,
217
- status: SyncStatuses.SKIPPED,
218
- note: `${merged.reason} - left untouched; fix it, then re-run sync`,
219
- apply: NO_CHANGE,
242
+ status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
243
+ apply: () => {
244
+ mkdirSync(dirname(path), { recursive: true });
245
+ writeFileSync(path, merged.text);
246
+ },
220
247
  },
221
248
  ];
222
249
  }
223
250
 
224
- if (!merged.changed) {
225
- return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
251
+ private static planAgentGuards(opts: { root: string; entry: TAgentEntry }): ISyncAction[] {
252
+ return opts.entry.guards?.kind === AgentGuardKinds.HOOKS_JSON ||
253
+ opts.entry.guards?.kind === AgentGuardKinds.CODEX_HOOKS
254
+ ? AgentFiles.planGuardHooksJson(opts)
255
+ : AgentFiles.planGuardExtension(opts);
226
256
  }
227
257
 
228
- if (text !== undefined && isTracked({ root: opts.root, path: opts.entry.guards.path })) {
229
- return [
230
- {
231
- path,
232
- status: SyncStatuses.SKIPPED,
233
- note: 'tracked by git - left alone; add the VULCAN guard hook by hand (see the hooks reference)',
234
- apply: NO_CHANGE,
235
- },
236
- ];
258
+ /** A file git tracks cannot be hidden by an exclude entry, and a per-developer edit would show as a diff. */
259
+ static isTracked(opts: { root: string; path: string }): boolean {
260
+ try {
261
+ return (
262
+ Bun.spawnSync(['git', 'ls-files', '--error-unmatch', opts.path], {
263
+ cwd: opts.root,
264
+ stdout: 'ignore',
265
+ stderr: 'ignore',
266
+ }).exitCode === 0
267
+ );
268
+ } catch {
269
+ return false;
270
+ }
237
271
  }
238
272
 
239
- return [
240
- {
241
- path,
242
- status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
243
- apply: () => {
244
- mkdirSync(dirname(path), { recursive: true });
245
- writeFileSync(path, merged.text);
246
- },
247
- },
248
- ];
249
- };
273
+ /** The MCP files and guard files of every chosen agent, in table order; the shared `.mcp.json` once, at its first reader. */
274
+ static plan(opts: { root: string; agents: string[] }): ISyncAction[] {
275
+ let sharedPlanned = false;
250
276
 
251
- const planAgentGuards = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] =>
252
- opts.entry.guards?.kind === AgentGuardKinds.HOOKS_JSON ||
253
- opts.entry.guards?.kind === AgentGuardKinds.CODEX_HOOKS
254
- ? planGuardHooksJson(opts)
255
- : planGuardExtension(opts);
277
+ return AgentTable.read()
278
+ .filter((entry) => opts.agents.includes(entry.id))
279
+ .flatMap((entry) => {
280
+ const guards = AgentFiles.planAgentGuards({ root: opts.root, entry });
256
281
 
257
- /** The MCP files and guard files of every chosen agent, in table order; the shared `.mcp.json` once, at its first reader. */
258
- export const planAgentFiles = (opts: { root: string; agents: string[] }): ISyncAction[] => {
259
- let sharedPlanned = false;
282
+ if (entry.mcp.scope === AgentScopes.PROJECT) {
283
+ return [...AgentFiles.planAgentMcp({ root: opts.root, entry }), ...guards];
284
+ }
260
285
 
261
- return readAgentTable()
262
- .filter((entry) => opts.agents.includes(entry.id))
263
- .flatMap((entry) => {
264
- const guards = planAgentGuards({ root: opts.root, entry });
286
+ if (sharedPlanned) {
287
+ return guards;
288
+ }
265
289
 
266
- if (entry.mcp.scope === AgentScopes.PROJECT) {
267
- return [...planAgentMcp({ root: opts.root, entry }), ...guards];
268
- }
290
+ sharedPlanned = true;
269
291
 
270
- if (sharedPlanned) {
271
- return guards;
272
- }
273
-
274
- sharedPlanned = true;
275
-
276
- return [...planSharedMcp({ root: opts.root }), ...guards];
277
- });
278
- };
292
+ return [...AgentFiles.planSharedMcp({ root: opts.root }), ...guards];
293
+ });
294
+ }
279
295
 
280
- /** One line per note of a chosen agent (a trust prompt only the user can answer). */
281
- export const agentNotes = (opts: { agents: string[] }): { agent: string; note: string }[] =>
282
- readAgentTable()
283
- .filter((entry) => opts.agents.includes(entry.id))
284
- .flatMap((entry) => entry.notes.map((note) => ({ agent: entry.id, note })));
296
+ /** One line per note of a chosen agent (a trust prompt only the user can answer). */
297
+ static agentNotes(opts: { agents: string[] }): { agent: string; note: string }[] {
298
+ return AgentTable.read()
299
+ .filter((entry) => opts.agents.includes(entry.id))
300
+ .flatMap((entry) => entry.notes.map((note) => ({ agent: entry.id, note })));
301
+ }
302
+ }