@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,6 +1,5 @@
1
1
  import {
2
2
  existsSync,
3
- lstatSync,
4
3
  readdirSync,
5
4
  readFileSync,
6
5
  readlinkSync,
@@ -14,28 +13,23 @@ import {
14
13
  AgentGuardKinds,
15
14
  AgentRenderers,
16
15
  AgentScopes,
17
- readAgentTable,
16
+ AgentTable,
18
17
  RemoveOutcomes,
19
- removeCodexBlock,
20
- removeCodexHooks,
21
- removeGuardHook,
22
- removeMcpEntry,
18
+ McpConfig,
19
+ CodexHooks,
20
+ GuardHook,
23
21
  } from '../agents/index.ts';
24
22
  import type { TAgentEntry } from '../agents/index.ts';
25
- import { isTracked } from './agent-files.ts';
26
- import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
27
- import { SyncConstants, SyncStatuses } from './common/index.ts';
23
+ import { AgentFiles } from './agent-files.ts';
24
+ import { BASE_DIRECTORY, BaseDirectory } from '../common/index.ts';
25
+ import { SyncConstants, SyncLinks, SyncStatuses } from './common/index.ts';
28
26
  import type { ISyncAction, TSettings } from './common/index.ts';
29
- import { isSettingsObject, removeManagedSettings } from './settings.ts';
27
+ import { isSettingsObject, ProjectSettings } from './settings.ts';
30
28
 
31
29
  const NO_CHANGE = (): void => {};
32
- const CLAUDE_SKILLS = join(SyncConstants.CLAUDE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
33
30
  /** Parents sync may delete once empty: its own agent folders, never `.agents` or the project. */
34
31
  const OWN_FOLDERS = new Set(['.cursor', '.codex', '.pi', '.omp', '.vscode', '.claude']);
35
32
 
36
- const isSymlink = (opts: { path: string }): boolean =>
37
- lstatSync(opts.path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
38
-
39
33
  const removeIfEmpty = (opts: { path: string }): void => {
40
34
  try {
41
35
  if (existsSync(opts.path) && readdirSync(opts.path).length === 0) {
@@ -58,13 +52,13 @@ const readJsonObject = (opts: { path: string }): TSettings | undefined => {
58
52
 
59
53
  /** A skill link sync made: a symlink into the shipped skills, stable or in the package, or into `.agents/skills`. */
60
54
  const isSkillLink = (opts: { root: string; path: string }): boolean => {
61
- if (!isSymlink({ path: opts.path })) {
55
+ if (!SyncLinks.isSymlink({ path: opts.path })) {
62
56
  return false;
63
57
  }
64
58
 
65
59
  const target = readlinkSync(opts.path);
66
60
  const shipped = [
67
- join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY),
61
+ join(BaseDirectory.stableOf(opts), SyncConstants.SKILLS_DIRECTORY),
68
62
  join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),
69
63
  join(opts.root, '.agents', SyncConstants.SKILLS_DIRECTORY),
70
64
  ];
@@ -97,7 +91,7 @@ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
97
91
  return [];
98
92
  }
99
93
 
100
- const removed = removeMcpEntry({ text: readFileSync(path, 'utf8'), key: 'mcpServers' });
94
+ const removed = McpConfig.removeEntry({ text: readFileSync(path, 'utf8'), key: 'mcpServers' });
101
95
 
102
96
  if (!removed.ok) {
103
97
  return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
@@ -107,7 +101,7 @@ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
107
101
  return [];
108
102
  }
109
103
 
110
- if (isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE })) {
104
+ if (AgentFiles.isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE })) {
111
105
  return [
112
106
  {
113
107
  path,
@@ -144,8 +138,8 @@ const planGuardHookRemoval = (opts: {
144
138
  const text = readFileSync(opts.path, 'utf8');
145
139
  const removed =
146
140
  opts.kind === AgentGuardKinds.CODEX_HOOKS
147
- ? removeCodexHooks({ text })
148
- : removeGuardHook({ text });
141
+ ? CodexHooks.remove({ text })
142
+ : GuardHook.remove({ text });
149
143
  const folder = dirname(opts.path);
150
144
  const parent = OWN_FOLDERS.has(basename(folder)) ? folder : undefined;
151
145
 
@@ -159,7 +153,7 @@ const planGuardHookRemoval = (opts: {
159
153
  return [];
160
154
  }
161
155
 
162
- if (isTracked({ root: opts.root, path: opts.relative })) {
156
+ if (AgentFiles.isTracked({ root: opts.root, path: opts.relative })) {
163
157
  return [
164
158
  {
165
159
  path: opts.path,
@@ -209,7 +203,7 @@ const planGuardsRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAct
209
203
  return [];
210
204
  }
211
205
 
212
- if (isTracked({ root: opts.root, path: opts.entry.guards.path })) {
206
+ if (AgentFiles.isTracked({ root: opts.root, path: opts.entry.guards.path })) {
213
207
  return [
214
208
  { path, status: SyncStatuses.SKIPPED, note: 'tracked by git - left alone', apply: NO_CHANGE },
215
209
  ];
@@ -255,7 +249,7 @@ const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction
255
249
  const parent = OWN_FOLDERS.has(folder) ? join(opts.root, folder) : undefined;
256
250
 
257
251
  if (opts.entry.mcp.renderer === AgentRenderers.CODEX_TOML) {
258
- const removed = removeCodexBlock({ text });
252
+ const removed = McpConfig.removeCodexBlock({ text });
259
253
 
260
254
  if (!removed.changed) {
261
255
  return [];
@@ -274,7 +268,7 @@ const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction
274
268
  }
275
269
 
276
270
  const key = opts.entry.mcp.renderer === AgentRenderers.SERVERS ? 'servers' : 'mcpServers';
277
- const removed = removeMcpEntry({ text, key });
271
+ const removed = McpConfig.removeEntry({ text, key });
278
272
 
279
273
  if (!removed.ok) {
280
274
  return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
@@ -299,7 +293,7 @@ const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction
299
293
  const planSkillLinkRemoval = (opts: { root: string; directory: string }): ISyncAction[] => {
300
294
  const target = join(opts.root, opts.directory);
301
295
 
302
- if (!existsSync(target) || isSymlink({ path: target })) {
296
+ if (!existsSync(target) || SyncLinks.isSymlink({ path: target })) {
303
297
  return [];
304
298
  }
305
299
 
@@ -338,7 +332,7 @@ const planClaudeRemoval = (opts: { root: string }): ISyncAction[] => {
338
332
  const managed = readJsonObject({ path: managedPath });
339
333
 
340
334
  if (settings !== undefined && managed !== undefined) {
341
- const remaining = removeManagedSettings({ settings, managed });
335
+ const remaining = ProjectSettings.removeManaged({ settings, managed });
342
336
 
343
337
  actions.push(
344
338
  Object.keys(remaining).length === 0
@@ -356,55 +350,55 @@ const planClaudeRemoval = (opts: { root: string }): ISyncAction[] => {
356
350
  actions.push(removeFile({ path: managedPath }));
357
351
  }
358
352
 
359
- actions.push(...planSkillLinkRemoval({ root: opts.root, directory: CLAUDE_SKILLS }));
353
+ actions.push(
354
+ ...planSkillLinkRemoval({ root: opts.root, directory: SyncConstants.CLAUDE_SKILLS }),
355
+ );
360
356
 
361
357
  return actions;
362
358
  };
363
359
 
364
- /**
365
- * What sync created for the agents that are no longer chosen, taken back: the Claude shim and managed
366
- * settings, a file sync wrote whole, the atlas key it merged into a file that holds more, the Codex
367
- * block, and the skill links no remaining agent still reads. A file the user changed so the entry is
368
- * no longer sync's is left and reported.
369
- */
370
- export const planAgentRemoval = (opts: {
371
- root: string;
372
- removed: string[];
373
- remaining: string[];
374
- }): ISyncAction[] => {
375
- const table = readAgentTable();
376
- const kept = new Set(
377
- table.filter((entry) => opts.remaining.includes(entry.id)).map((entry) => entry.skills.dir),
378
- );
379
- const cleaned = new Set<string>();
380
- const actions: ISyncAction[] = [];
381
- const stillReadsShared = table.some(
382
- (entry) => opts.remaining.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
383
- );
384
- let sharedDone = false;
360
+ export class AgentRemoval {
361
+ /**
362
+ * What sync created for the agents that are no longer chosen, taken back: the Claude shim and managed
363
+ * settings, a file sync wrote whole, the atlas key it merged into a file that holds more, the Codex
364
+ * block, and the skill links no remaining agent still reads. A file the user changed so the entry is
365
+ * no longer sync's is left and reported.
366
+ */
367
+ static plan(opts: { root: string; removed: string[]; remaining: string[] }): ISyncAction[] {
368
+ const table = AgentTable.read();
369
+ const kept = new Set(
370
+ table.filter((entry) => opts.remaining.includes(entry.id)).map((entry) => entry.skills.dir),
371
+ );
372
+ const cleaned = new Set<string>();
373
+ const actions: ISyncAction[] = [];
374
+ const stillReadsShared = table.some(
375
+ (entry) => opts.remaining.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
376
+ );
377
+ let sharedDone = false;
385
378
 
386
- for (const entry of table.filter((item) => opts.removed.includes(item.id))) {
387
- if (entry.id === AgentConstants.DEFAULT_AGENT) {
388
- actions.push(...planClaudeRemoval({ root: opts.root }));
389
- }
379
+ for (const entry of table.filter((item) => opts.removed.includes(item.id))) {
380
+ if (entry.id === AgentConstants.DEFAULT_AGENT) {
381
+ actions.push(...planClaudeRemoval({ root: opts.root }));
382
+ }
390
383
 
391
- actions.push(...planMcpRemoval({ root: opts.root, entry }));
392
- actions.push(...planGuardsRemoval({ root: opts.root, entry }));
384
+ actions.push(...planMcpRemoval({ root: opts.root, entry }));
385
+ actions.push(...planGuardsRemoval({ root: opts.root, entry }));
393
386
 
394
- if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
395
- sharedDone = true;
396
- actions.push(...planSharedMcpRemoval({ root: opts.root }));
397
- }
387
+ if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
388
+ sharedDone = true;
389
+ actions.push(...planSharedMcpRemoval({ root: opts.root }));
390
+ }
398
391
 
399
- if (
400
- entry.skills.dir !== CLAUDE_SKILLS &&
401
- !kept.has(entry.skills.dir) &&
402
- !cleaned.has(entry.skills.dir)
403
- ) {
404
- cleaned.add(entry.skills.dir);
405
- actions.push(...planSkillLinkRemoval({ root: opts.root, directory: entry.skills.dir }));
392
+ if (
393
+ entry.skills.dir !== SyncConstants.CLAUDE_SKILLS &&
394
+ !kept.has(entry.skills.dir) &&
395
+ !cleaned.has(entry.skills.dir)
396
+ ) {
397
+ cleaned.add(entry.skills.dir);
398
+ actions.push(...planSkillLinkRemoval({ root: opts.root, directory: entry.skills.dir }));
399
+ }
406
400
  }
407
- }
408
401
 
409
- return actions;
410
- };
402
+ return actions;
403
+ }
404
+ }
@@ -1,54 +1,56 @@
1
1
  import { existsSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import { mergeAtlasBlock, renderAtlasBlock } from '../agents/index.ts';
3
+ import { AtlasBlock } from '../agents/index.ts';
4
4
  import type { TResolvedConfig } from '../config/index.ts';
5
- import { projectNameOf } from '../manifest/index.ts';
5
+ import { ProjectManifest } from '../manifest/index.ts';
6
6
  import { SyncStatuses } from './common/index.ts';
7
7
  import type { ISyncAction } from './common/index.ts';
8
8
 
9
9
  const NO_CHANGE = (): void => {};
10
10
 
11
- /**
12
- * The block's text for this project, or undefined when AGENTS.md is absent. Every project has the
13
- * atlas server, and the block is what an agent that does not show the server's own text reads, so it
14
- * does not wait for a per-machine MCP file to exist.
15
- */
16
- export const mergedAtlasBlock = (opts: {
17
- root: string;
18
- config: TResolvedConfig;
19
- }): { path: string; changed: boolean; text: string } | undefined => {
20
- const path = join(opts.root, 'AGENTS.md');
21
-
22
- if (!existsSync(path)) {
23
- return undefined;
11
+ export class AtlasBlockPlan {
12
+ /**
13
+ * The block's text for this project, or undefined when AGENTS.md is absent. Every project has the
14
+ * atlas server, and the block is what an agent that does not show the server's own text reads, so it
15
+ * does not wait for a per-machine MCP file to exist.
16
+ */
17
+ static merged(opts: {
18
+ root: string;
19
+ config: TResolvedConfig;
20
+ }): { path: string; changed: boolean; text: string } | undefined {
21
+ const path = join(opts.root, 'AGENTS.md');
22
+
23
+ if (!existsSync(path)) {
24
+ return undefined;
25
+ }
26
+
27
+ const block = AtlasBlock.render({
28
+ project: ProjectManifest.projectNameOf(opts),
29
+ sources: opts.config.atlas.sources.map((source) => source.name),
30
+ });
31
+
32
+ return { path, ...AtlasBlock.merge({ text: readFileSync(path, 'utf8'), block }) };
24
33
  }
25
34
 
26
- const block = renderAtlasBlock({
27
- project: projectNameOf(opts),
28
- sources: opts.config.atlas.sources.map((source) => source.name),
29
- });
30
-
31
- return { path, ...mergeAtlasBlock({ text: readFileSync(path, 'utf8'), block }) };
32
- };
33
-
34
- /** The committed AGENTS.md carries the block for every agent, Claude included. */
35
- export const planAtlasBlock = (opts: { root: string; config: TResolvedConfig }): ISyncAction[] => {
36
- const merged = mergedAtlasBlock(opts);
37
-
38
- if (merged === undefined) {
39
- return [];
35
+ /** The committed AGENTS.md carries the block for every agent, Claude included. */
36
+ static plan(opts: { root: string; config: TResolvedConfig }): ISyncAction[] {
37
+ const merged = AtlasBlockPlan.merged(opts);
38
+
39
+ if (merged === undefined) {
40
+ return [];
41
+ }
42
+
43
+ if (!merged.changed) {
44
+ return [{ path: merged.path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
45
+ }
46
+
47
+ return [
48
+ {
49
+ path: merged.path,
50
+ status: SyncStatuses.REPLACED,
51
+ note: 'Atlas block',
52
+ apply: () => writeFileSync(merged.path, merged.text),
53
+ },
54
+ ];
40
55
  }
41
-
42
- if (!merged.changed) {
43
- return [{ path: merged.path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
44
- }
45
-
46
- return [
47
- {
48
- path: merged.path,
49
- status: SyncStatuses.REPLACED,
50
- note: 'Atlas block',
51
- apply: () => writeFileSync(merged.path, merged.text),
52
- },
53
- ];
54
- };
56
+ }
@@ -1,7 +1,7 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import { buildBaseRuleHashes, ManifestConstants } from '../manifest/index.ts';
4
- import { readBaseRules, readRetiredRuleIds } from '../rules/index.ts';
3
+ import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
4
+ import { BaseRules } from '../rules/index.ts';
5
5
  import { BaseRuleChanges } from './common/index.ts';
6
6
  import type { IBaseRuleChange } from './common/index.ts';
7
7
 
@@ -35,38 +35,40 @@ const readSyncedHashes = (opts: { root: string }): Record<string, unknown> => {
35
35
  }
36
36
  };
37
37
 
38
- /** V3: each base rule added, changed or removed since the committed manifest's last sync. */
39
- export const diffBaseRules = (opts: { root: string }): IBaseRuleChange[] => {
40
- const synced = readSyncedHashes(opts);
38
+ export class BaseRulesDiff {
39
+ /** V3: each base rule added, changed or removed since the committed manifest's last sync. */
40
+ static diff(opts: { root: string }): IBaseRuleChange[] {
41
+ const synced = readSyncedHashes(opts);
41
42
 
42
- if (Object.keys(synced).length === 0) {
43
- return [];
44
- }
43
+ if (Object.keys(synced).length === 0) {
44
+ return [];
45
+ }
45
46
 
46
- const installed = buildBaseRuleHashes();
47
- const rows = readBaseRules();
48
- const retired = new Set(readRetiredRuleIds());
49
- const changes: IBaseRuleChange[] = [];
47
+ const installed = ProjectManifest.buildBaseRuleHashes();
48
+ const rows = BaseRules.read();
49
+ const retired = new Set(BaseRules.readRetiredIds());
50
+ const changes: IBaseRuleChange[] = [];
50
51
 
51
- for (const [id, hash] of Object.entries(installed)) {
52
- if (synced[id] === hash) {
53
- continue;
52
+ for (const [id, hash] of Object.entries(installed)) {
53
+ if (synced[id] === hash) {
54
+ continue;
55
+ }
56
+
57
+ changes.push({
58
+ id,
59
+ change: synced[id] === undefined ? BaseRuleChanges.ADDED : BaseRuleChanges.CHANGED,
60
+ text: toRuleText({ row: rows[id] }),
61
+ });
54
62
  }
55
63
 
56
- changes.push({
57
- id,
58
- change: synced[id] === undefined ? BaseRuleChanges.ADDED : BaseRuleChanges.CHANGED,
59
- text: toRuleText({ row: rows[id] }),
60
- });
61
- }
64
+ for (const id of Object.keys(synced).filter((syncedId) => installed[syncedId] === undefined)) {
65
+ changes.push({
66
+ id,
67
+ change: BaseRuleChanges.REMOVED,
68
+ text: retired.has(id) ? '(retired)' : '',
69
+ });
70
+ }
62
71
 
63
- for (const id of Object.keys(synced).filter((syncedId) => installed[syncedId] === undefined)) {
64
- changes.push({
65
- id,
66
- change: BaseRuleChanges.REMOVED,
67
- text: retired.has(id) ? '(retired)' : '',
68
- });
72
+ return changes;
69
73
  }
70
-
71
- return changes;
72
- };
74
+ }
@@ -1,48 +1,85 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
- import { dirname, join } from 'node:path';
2
+ import { dirname, isAbsolute, join, relative } from 'node:path';
3
3
  import { ProjectLayout } from '../common/index.ts';
4
- import { projectTmpOf } from '../hooks/project-tmp.ts';
4
+ import { ProjectTmp } from '../hooks/project-tmp.ts';
5
5
  import { SyncStatuses } from './common/index.ts';
6
6
  import type { ISyncAction } from './common/index.ts';
7
7
 
8
8
  /** Beside the other personal files of the developer, gitignored with them. */
9
9
  export const CLAUDE_LAUNCH_FILE = `${ProjectLayout.LOCAL_DIRECTORY}/claude.launch.settings.json`;
10
10
 
11
- /**
12
- * What `claude --settings <this file>` adds to a session: `TMPDIR` and `CLAUDE_CODE_TMPDIR` in the project.
13
- * Claude Code applies an `env` block given this way (and the variables in the launch environment, and the
14
- * user settings file), but not the same block in the project's own settings, so this is the route that
15
- * moves its own task-output files and its MCP servers into the project. Absolute paths: the file belongs
16
- * to one checkout of one developer.
17
- */
18
- export const renderClaudeLaunch = (opts: { root: string }): string => {
19
- const folder = projectTmpOf({ root: opts.root });
20
-
21
- return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
22
- };
23
-
24
- /** The launch file when it is missing or written for another folder; nothing to do when it is current. */
25
- export const planClaudeLaunch = (opts: { root: string }): ISyncAction[] => {
26
- const path = join(opts.root, CLAUDE_LAUNCH_FILE);
27
- const text = renderClaudeLaunch({ root: opts.root });
28
- const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
29
-
30
- if (before === text) {
31
- return [];
11
+ export class LaunchSettings {
12
+ /**
13
+ * What `claude --settings <this file>` adds to a session: `TMPDIR` and `CLAUDE_CODE_TMPDIR` in the project.
14
+ * Claude Code applies an `env` block given this way (and the variables in the launch environment, and the
15
+ * user settings file), but not the same block in the project's own settings, so this is the route that
16
+ * moves its own task-output files and its MCP servers into the project. Absolute paths: the file belongs
17
+ * to one checkout of one developer.
18
+ */
19
+ static renderClaude(opts: { root: string }): string {
20
+ const folder = ProjectTmp.projectOf({ root: opts.root });
21
+
22
+ return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
32
23
  }
33
24
 
34
- return [
35
- {
36
- path,
37
- status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
38
- note:
39
- before === undefined
40
- ? 'the Claude Code launch file is missing'
41
- : 'the Claude Code launch file names another folder',
42
- apply: () => {
43
- mkdirSync(dirname(path), { recursive: true });
44
- writeFileSync(path, text);
25
+ /** The launch file when it is missing or written for another folder; nothing to do when it is current. */
26
+ static planClaude(opts: { root: string }): ISyncAction[] {
27
+ const path = join(opts.root, CLAUDE_LAUNCH_FILE);
28
+ const text = LaunchSettings.renderClaude({ root: opts.root });
29
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
30
+
31
+ if (before === text) {
32
+ return [];
33
+ }
34
+
35
+ return [
36
+ {
37
+ path,
38
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
39
+ note:
40
+ before === undefined
41
+ ? 'the Claude Code launch file is missing'
42
+ : 'the Claude Code launch file names another folder',
43
+ apply: () => {
44
+ mkdirSync(dirname(path), { recursive: true });
45
+ writeFileSync(path, text);
46
+ },
45
47
  },
46
- },
47
- ];
48
- };
48
+ ];
49
+ }
50
+ }
51
+
52
+ export class ClaudeLaunch {
53
+ /** The one line that starts Claude Code in this project; the docs and the warning print this string. */
54
+ static readonly COMMAND = `claude --settings ${CLAUDE_LAUNCH_FILE}`;
55
+
56
+ /**
57
+ * What to tell the owner when a Claude Code session runs without the launch file: `CLAUDE_CODE_TMPDIR` is unset
58
+ * or points outside the project, so Claude Code's own scratchpad and task output land outside it and writes
59
+ * there need approval. Undefined for any other agent, for a project without the file, and for a session
60
+ * that already uses a folder inside the project.
61
+ */
62
+ static missWarning(opts: {
63
+ root: string;
64
+ env: Record<string, string | undefined>;
65
+ }): string | undefined {
66
+ if (
67
+ opts.env.CLAUDE_PROJECT_DIR === undefined ||
68
+ !existsSync(join(opts.root, CLAUDE_LAUNCH_FILE))
69
+ ) {
70
+ return undefined;
71
+ }
72
+
73
+ const folder = opts.env.CLAUDE_CODE_TMPDIR;
74
+ const fromRoot =
75
+ folder === undefined || folder === '' ? undefined : relative(opts.root, folder);
76
+
77
+ if (fromRoot !== undefined && !isAbsolute(fromRoot) && !fromRoot.startsWith('..')) {
78
+ return undefined;
79
+ }
80
+
81
+ return `Claude Code was started without the project's launch file: CLAUDE_CODE_TMPDIR is ${
82
+ fromRoot === undefined ? 'not set' : `${folder}, outside the project`
83
+ }, so its scratchpad and task output are written outside the project and the owner will be asked to approve each write there. Say so in your first reply. To fix it, quit and start Claude Code with: ${ClaudeLaunch.COMMAND}`;
84
+ }
85
+ }
@@ -1,3 +1,5 @@
1
+ import { join } from 'node:path';
2
+
1
3
  export class SyncStatuses {
2
4
  static readonly CREATED = 'created';
3
5
  static readonly REPLACED = 'replaced';
@@ -31,6 +33,8 @@ export class SyncConstants {
31
33
  /** What sync applied last time, so a later sync can take back what the project no longer asks for. */
32
34
  static readonly MANAGED_FILE = 'vulcan-managed.json';
33
35
  static readonly SKILLS_DIRECTORY = 'skills';
36
+ /** The Claude skills folder, relative to the project root. */
37
+ static readonly CLAUDE_SKILLS = join(this.CLAUDE_DIRECTORY, this.SKILLS_DIRECTORY);
34
38
  static readonly SKILL_FILE = 'SKILL.md';
35
39
  /** The settings key of hook entries: sync takes a managed hook back by its command, not its whole entry. */
36
40
  static readonly HOOKS_KEY = 'hooks';
@@ -1,2 +1,3 @@
1
1
  export * from './constants.ts';
2
+ export * from './symlink.ts';
2
3
  export * from './types.ts';
@@ -0,0 +1,9 @@
1
+ import { lstatSync } from 'node:fs';
2
+
3
+ /** Reading a path without following it: the link itself is what sync keeps or replaces. */
4
+ export class SyncLinks {
5
+ /** Whether `path` is a symlink, a dangling one included; a missing path is not. */
6
+ static isSymlink(opts: { path: string }): boolean {
7
+ return lstatSync(opts.path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
8
+ }
9
+ }
@@ -1,7 +1,7 @@
1
1
  import type { TConstValue } from '../../common/index.ts';
2
2
  import type { BaseRuleChanges, SyncStatuses } from './constants.ts';
3
3
 
4
- export type TSyncStatus = TConstValue<typeof SyncStatuses>;
4
+ type TSyncStatus = TConstValue<typeof SyncStatuses>;
5
5
 
6
6
  export type TSettings = Record<string, unknown>;
7
7
 
@@ -13,7 +13,7 @@ export interface ISyncAction {
13
13
  apply: () => void;
14
14
  }
15
15
 
16
- export type TBaseRuleChange = TConstValue<typeof BaseRuleChanges>;
16
+ type TBaseRuleChange = TConstValue<typeof BaseRuleChanges>;
17
17
 
18
18
  /** One base rule that moved since the last sync; `text` is its new text, or `(retired)` when the base retired it. */
19
19
  export interface IBaseRuleChange {