@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
@@ -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
+ }