@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
@@ -13,19 +13,18 @@ import {
13
13
  AgentGuardKinds,
14
14
  AgentRenderers,
15
15
  AgentScopes,
16
- readAgentTable,
16
+ AgentTable,
17
17
  RemoveOutcomes,
18
- removeCodexBlock,
19
- removeCodexHooks,
20
- removeGuardHook,
21
- removeMcpEntry,
18
+ McpConfig,
19
+ CodexHooks,
20
+ GuardHook,
22
21
  } from '../agents/index.ts';
23
22
  import type { TAgentEntry } from '../agents/index.ts';
24
- import { isTracked } from './agent-files.ts';
25
- import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
23
+ import { AgentFiles } from './agent-files.ts';
24
+ import { BASE_DIRECTORY, BaseDirectory } from '../common/index.ts';
26
25
  import { SyncConstants, SyncLinks, SyncStatuses } from './common/index.ts';
27
26
  import type { ISyncAction, TSettings } from './common/index.ts';
28
- import { isSettingsObject, removeManagedSettings } from './settings.ts';
27
+ import { isSettingsObject, ProjectSettings } from './settings.ts';
29
28
 
30
29
  const NO_CHANGE = (): void => {};
31
30
  /** Parents sync may delete once empty: its own agent folders, never `.agents` or the project. */
@@ -59,7 +58,7 @@ const isSkillLink = (opts: { root: string; path: string }): boolean => {
59
58
 
60
59
  const target = readlinkSync(opts.path);
61
60
  const shipped = [
62
- join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY),
61
+ join(BaseDirectory.stableOf(opts), SyncConstants.SKILLS_DIRECTORY),
63
62
  join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),
64
63
  join(opts.root, '.agents', SyncConstants.SKILLS_DIRECTORY),
65
64
  ];
@@ -92,7 +91,7 @@ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
92
91
  return [];
93
92
  }
94
93
 
95
- const removed = removeMcpEntry({ text: readFileSync(path, 'utf8'), key: 'mcpServers' });
94
+ const removed = McpConfig.removeEntry({ text: readFileSync(path, 'utf8'), key: 'mcpServers' });
96
95
 
97
96
  if (!removed.ok) {
98
97
  return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
@@ -102,7 +101,7 @@ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
102
101
  return [];
103
102
  }
104
103
 
105
- if (isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE })) {
104
+ if (AgentFiles.isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE })) {
106
105
  return [
107
106
  {
108
107
  path,
@@ -139,8 +138,8 @@ const planGuardHookRemoval = (opts: {
139
138
  const text = readFileSync(opts.path, 'utf8');
140
139
  const removed =
141
140
  opts.kind === AgentGuardKinds.CODEX_HOOKS
142
- ? removeCodexHooks({ text })
143
- : removeGuardHook({ text });
141
+ ? CodexHooks.remove({ text })
142
+ : GuardHook.remove({ text });
144
143
  const folder = dirname(opts.path);
145
144
  const parent = OWN_FOLDERS.has(basename(folder)) ? folder : undefined;
146
145
 
@@ -154,7 +153,7 @@ const planGuardHookRemoval = (opts: {
154
153
  return [];
155
154
  }
156
155
 
157
- if (isTracked({ root: opts.root, path: opts.relative })) {
156
+ if (AgentFiles.isTracked({ root: opts.root, path: opts.relative })) {
158
157
  return [
159
158
  {
160
159
  path: opts.path,
@@ -204,7 +203,7 @@ const planGuardsRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAct
204
203
  return [];
205
204
  }
206
205
 
207
- if (isTracked({ root: opts.root, path: opts.entry.guards.path })) {
206
+ if (AgentFiles.isTracked({ root: opts.root, path: opts.entry.guards.path })) {
208
207
  return [
209
208
  { path, status: SyncStatuses.SKIPPED, note: 'tracked by git - left alone', apply: NO_CHANGE },
210
209
  ];
@@ -250,7 +249,7 @@ const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction
250
249
  const parent = OWN_FOLDERS.has(folder) ? join(opts.root, folder) : undefined;
251
250
 
252
251
  if (opts.entry.mcp.renderer === AgentRenderers.CODEX_TOML) {
253
- const removed = removeCodexBlock({ text });
252
+ const removed = McpConfig.removeCodexBlock({ text });
254
253
 
255
254
  if (!removed.changed) {
256
255
  return [];
@@ -269,7 +268,7 @@ const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction
269
268
  }
270
269
 
271
270
  const key = opts.entry.mcp.renderer === AgentRenderers.SERVERS ? 'servers' : 'mcpServers';
272
- const removed = removeMcpEntry({ text, key });
271
+ const removed = McpConfig.removeEntry({ text, key });
273
272
 
274
273
  if (!removed.ok) {
275
274
  return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
@@ -333,7 +332,7 @@ const planClaudeRemoval = (opts: { root: string }): ISyncAction[] => {
333
332
  const managed = readJsonObject({ path: managedPath });
334
333
 
335
334
  if (settings !== undefined && managed !== undefined) {
336
- const remaining = removeManagedSettings({ settings, managed });
335
+ const remaining = ProjectSettings.removeManaged({ settings, managed });
337
336
 
338
337
  actions.push(
339
338
  Object.keys(remaining).length === 0
@@ -358,50 +357,48 @@ const planClaudeRemoval = (opts: { root: string }): ISyncAction[] => {
358
357
  return actions;
359
358
  };
360
359
 
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
- export const planAgentRemoval = (opts: {
368
- root: string;
369
- removed: string[];
370
- remaining: string[];
371
- }): ISyncAction[] => {
372
- const table = readAgentTable();
373
- const kept = new Set(
374
- table.filter((entry) => opts.remaining.includes(entry.id)).map((entry) => entry.skills.dir),
375
- );
376
- const cleaned = new Set<string>();
377
- const actions: ISyncAction[] = [];
378
- const stillReadsShared = table.some(
379
- (entry) => opts.remaining.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
380
- );
381
- 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;
382
378
 
383
- for (const entry of table.filter((item) => opts.removed.includes(item.id))) {
384
- if (entry.id === AgentConstants.DEFAULT_AGENT) {
385
- actions.push(...planClaudeRemoval({ root: opts.root }));
386
- }
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
+ }
387
383
 
388
- actions.push(...planMcpRemoval({ root: opts.root, entry }));
389
- actions.push(...planGuardsRemoval({ root: opts.root, entry }));
384
+ actions.push(...planMcpRemoval({ root: opts.root, entry }));
385
+ actions.push(...planGuardsRemoval({ root: opts.root, entry }));
390
386
 
391
- if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
392
- sharedDone = true;
393
- actions.push(...planSharedMcpRemoval({ root: opts.root }));
394
- }
387
+ if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
388
+ sharedDone = true;
389
+ actions.push(...planSharedMcpRemoval({ root: opts.root }));
390
+ }
395
391
 
396
- if (
397
- entry.skills.dir !== SyncConstants.CLAUDE_SKILLS &&
398
- !kept.has(entry.skills.dir) &&
399
- !cleaned.has(entry.skills.dir)
400
- ) {
401
- cleaned.add(entry.skills.dir);
402
- 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
+ }
403
400
  }
404
- }
405
401
 
406
- return actions;
407
- };
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,51 +1,53 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
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 });
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 });
20
21
 
21
- return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
22
- };
22
+ return `${JSON.stringify({ env: { TMPDIR: folder, CLAUDE_CODE_TMPDIR: folder } }, null, 2)}\n`;
23
+ }
23
24
 
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;
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;
29
30
 
30
- if (before === text) {
31
- return [];
32
- }
31
+ if (before === text) {
32
+ return [];
33
+ }
33
34
 
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);
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
+ }
49
51
 
50
52
  export class ClaudeLaunch {
51
53
  /** The one line that starts Claude Code in this project; the docs and the warning print this string. */
@@ -1,6 +1,6 @@
1
1
  import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join, resolve } from 'node:path';
3
- import { excludePathsOf, mergeExcludeBlock, renderExcludeBlock } from '../agents/index.ts';
3
+ import { AgentExclude } from '../agents/index.ts';
4
4
  import { BASE_DIRECTORY } from '../common/index.ts';
5
5
  import { SyncConstants, SyncStatuses } from './common/index.ts';
6
6
  import type { ISyncAction } from './common/index.ts';
@@ -21,79 +21,87 @@ const git = (opts: { root: string; args: string[] }): string | undefined => {
21
21
  }
22
22
  };
23
23
 
24
- export const shippedSkillNames = (): string[] => {
25
- const directory = join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
24
+ export class ExcludePlan {
25
+ static shippedSkillNames(): string[] {
26
+ const directory = join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
26
27
 
27
- return existsSync(directory)
28
- ? readdirSync(directory, { withFileTypes: true })
29
- .filter(
30
- (entry) =>
31
- entry.isDirectory() &&
32
- existsSync(join(directory, entry.name, SyncConstants.SKILL_FILE)),
33
- )
34
- .map((entry) => entry.name)
35
- .sort()
36
- : [];
37
- };
28
+ return existsSync(directory)
29
+ ? readdirSync(directory, { withFileTypes: true })
30
+ .filter(
31
+ (entry) =>
32
+ entry.isDirectory() &&
33
+ existsSync(join(directory, entry.name, SyncConstants.SKILL_FILE)),
34
+ )
35
+ .map((entry) => entry.name)
36
+ .sort()
37
+ : [];
38
+ }
38
39
 
39
- /**
40
- * The files sync creates for the chosen agents, listed in this clone's `.git/info/exclude` (D1): the
41
- * choice is per developer, so a committed `.gitignore` would flip-flop. A re-run replaces the block, so
42
- * an agent that is no longer chosen drops out. A project below the git top level keeps its own block,
43
- * so it never replaces the block of the top level. Paths git tracks are not listed; outside a git
44
- * repository nothing is written.
45
- */
46
- export const planExclude = (opts: { root: string; agents: string[] }): ISyncAction[] => {
47
- const location = git({ root: opts.root, args: ['rev-parse', '--git-path', 'info/exclude'] });
40
+ /**
41
+ * The files sync creates for the chosen agents, listed in this clone's `.git/info/exclude` (D1): the
42
+ * choice is per developer, so a committed `.gitignore` would flip-flop. A re-run replaces the block, so
43
+ * an agent that is no longer chosen drops out. A project below the git top level keeps its own block,
44
+ * so it never replaces the block of the top level. Paths git tracks are not listed; outside a git
45
+ * repository nothing is written.
46
+ */
47
+ static plan(opts: { root: string; agents: string[] }): ISyncAction[] {
48
+ const location = git({ root: opts.root, args: ['rev-parse', '--git-path', 'info/exclude'] });
48
49
 
49
- if (location === undefined || location === '') {
50
- return [];
51
- }
50
+ if (location === undefined || location === '') {
51
+ return [];
52
+ }
52
53
 
53
- // A project directory git already ignores (scratch under .agents/local/) needs no entries of its own.
54
- if (git({ root: opts.root, args: ['check-ignore', '-q', '.'] }) !== undefined) {
55
- return [];
56
- }
54
+ // A project directory git already ignores (scratch under .agents/local/) needs no entries of its own.
55
+ if (git({ root: opts.root, args: ['check-ignore', '-q', '.'] }) !== undefined) {
56
+ return [];
57
+ }
57
58
 
58
- const path = resolve(opts.root, location);
59
- const prefix = git({ root: opts.root, args: ['rev-parse', '--show-prefix'] }) ?? '';
60
- const anchored = excludePathsOf({ agents: opts.agents, skillNames: shippedSkillNames() }).map(
61
- (group) => ({ ...group, paths: group.paths.map((item) => `/${prefix}${item.slice(1)}`) }),
62
- );
63
- const candidates = anchored.flatMap((group) => group.paths).filter((item) => !item.endsWith('/'));
64
- const tracked = new Set(
65
- (
66
- git({
67
- root: opts.root,
68
- args: ['ls-files', '--', ...candidates.map((item) => item.slice(`/${prefix}`.length))],
69
- }) ?? ''
70
- )
71
- .split('\n')
72
- .filter((line) => line !== '')
73
- .map((line) => `/${prefix}${line}`),
74
- );
75
- const groups = anchored
76
- .map((group) => ({ ...group, paths: group.paths.filter((item) => !tracked.has(item)) }))
77
- .filter((group) => group.paths.length > 0);
78
- const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
79
- const merged = mergeExcludeBlock({
80
- text: before,
81
- block: renderExcludeBlock({ groups, prefix }),
82
- prefix,
83
- });
59
+ const path = resolve(opts.root, location);
60
+ const prefix = git({ root: opts.root, args: ['rev-parse', '--show-prefix'] }) ?? '';
61
+ const anchored = AgentExclude.excludePathsOf({
62
+ agents: opts.agents,
63
+ skillNames: ExcludePlan.shippedSkillNames(),
64
+ }).map((group) => ({
65
+ ...group,
66
+ paths: group.paths.map((item) => `/${prefix}${item.slice(1)}`),
67
+ }));
68
+ const candidates = anchored
69
+ .flatMap((group) => group.paths)
70
+ .filter((item) => !item.endsWith('/'));
71
+ const tracked = new Set(
72
+ (
73
+ git({
74
+ root: opts.root,
75
+ args: ['ls-files', '--', ...candidates.map((item) => item.slice(`/${prefix}`.length))],
76
+ }) ?? ''
77
+ )
78
+ .split('\n')
79
+ .filter((line) => line !== '')
80
+ .map((line) => `/${prefix}${line}`),
81
+ );
82
+ const groups = anchored
83
+ .map((group) => ({ ...group, paths: group.paths.filter((item) => !tracked.has(item)) }))
84
+ .filter((group) => group.paths.length > 0);
85
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
86
+ const merged = AgentExclude.mergeBlock({
87
+ text: before,
88
+ block: AgentExclude.renderBlock({ groups, prefix }),
89
+ prefix,
90
+ });
84
91
 
85
- if (!merged.changed) {
86
- return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
87
- }
92
+ if (!merged.changed) {
93
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
94
+ }
88
95
 
89
- return [
90
- {
91
- path,
92
- status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
93
- apply: () => {
94
- mkdirSync(dirname(path), { recursive: true });
95
- writeFileSync(path, merged.text);
96
+ return [
97
+ {
98
+ path,
99
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
100
+ apply: () => {
101
+ mkdirSync(dirname(path), { recursive: true });
102
+ writeFileSync(path, merged.text);
103
+ },
96
104
  },
97
- },
98
- ];
99
- };
105
+ ];
106
+ }
107
+ }