@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,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
+ }
@@ -1,33 +1,13 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
- import { LOCAL_AGENTS_FILE, renderLocalChoice } from '../agents/index.ts';
3
+ import { LOCAL_AGENTS_FILE, LocalChoice } from '../agents/index.ts';
4
4
  import { ProjectLayout } from '../common/index.ts';
5
- import { planClaudeLaunch } from './claude-launch.ts';
5
+ import { LaunchSettings } from './claude-launch.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
- /** The developer's stored agents: written when the machine just chose, reported unchanged when it was read. */
12
- export const planLocalChoice = (opts: { root: string; agents: string[] }): ISyncAction => {
13
- const path = join(opts.root, LOCAL_AGENTS_FILE);
14
- const text = renderLocalChoice({ agents: opts.agents });
15
- const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
16
-
17
- if (before === text) {
18
- return { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE };
19
- }
20
-
21
- return {
22
- path,
23
- status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
24
- apply: () => {
25
- mkdirSync(dirname(path), { recursive: true });
26
- writeFileSync(path, text);
27
- },
28
- };
29
- };
30
-
31
11
  /** One line sync adds to a committed `.gitignore`; a project without one is left alone. */
32
12
  const planIgnoreLine = (opts: { root: string; line: string }): ISyncAction[] => {
33
13
  const path = join(opts.root, '.gitignore');
@@ -56,32 +36,55 @@ const planIgnoreLine = (opts: { root: string; line: string }): ISyncAction[] =>
56
36
  ];
57
37
  };
58
38
 
59
- /** The one line sync adds to a committed `.gitignore`; a project without one is left alone. */
60
- export const planLocalIgnore = (opts: { root: string }): ISyncAction[] =>
61
- planIgnoreLine({ root: opts.root, line: LOCAL_AGENTS_FILE });
39
+ export class LocalPlan {
40
+ /** The developer's stored agents: written when the machine just chose, reported unchanged when it was read. */
41
+ static planChoice(opts: { root: string; agents: string[] }): ISyncAction {
42
+ const path = join(opts.root, LOCAL_AGENTS_FILE);
43
+ const text = LocalChoice.render({ agents: opts.agents });
44
+ const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
62
45
 
63
- /**
64
- * The project's local workspace: `.agents/local/` is gitignored and holds what an agent creates while
65
- * it works (scratch, worktrees, clones, cache, prototypes), so nothing lands outside the project.
66
- */
67
- export const planLocalWorkspace = (opts: { root: string }): ISyncAction[] => {
68
- const directory = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
69
- const missing = ProjectLayout.LOCAL_LAYOUT.map((entry) => entry.name).filter(
70
- (name) => !existsSync(join(directory, name)),
71
- );
46
+ if (before === text) {
47
+ return { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE };
48
+ }
72
49
 
73
- return [
74
- ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
75
- ...planClaudeLaunch({ root: opts.root }),
76
- {
77
- path: directory,
78
- status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
79
- ...(missing.length === 0 ? {} : { note: `created ${missing.join(', ')}` }),
50
+ return {
51
+ path,
52
+ status: before === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
80
53
  apply: () => {
81
- for (const name of missing) {
82
- mkdirSync(join(directory, name), { recursive: true });
83
- }
54
+ mkdirSync(dirname(path), { recursive: true });
55
+ writeFileSync(path, text);
84
56
  },
85
- },
86
- ];
87
- };
57
+ };
58
+ }
59
+
60
+ /** The one line sync adds to a committed `.gitignore`; a project without one is left alone. */
61
+ static planIgnore(opts: { root: string }): ISyncAction[] {
62
+ return planIgnoreLine({ root: opts.root, line: LOCAL_AGENTS_FILE });
63
+ }
64
+
65
+ /**
66
+ * The project's local workspace: `.agents/local/` is gitignored and holds what an agent creates while
67
+ * it works (scratch, worktrees, clones, cache, prototypes), so nothing lands outside the project.
68
+ */
69
+ static planWorkspace(opts: { root: string }): ISyncAction[] {
70
+ const directory = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
71
+ const missing = ProjectLayout.LOCAL_LAYOUT.map((entry) => entry.name).filter(
72
+ (name) => !existsSync(join(directory, name)),
73
+ );
74
+
75
+ return [
76
+ ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
77
+ ...LaunchSettings.planClaude({ root: opts.root }),
78
+ {
79
+ path: directory,
80
+ status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
81
+ ...(missing.length === 0 ? {} : { note: `created ${missing.join(', ')}` }),
82
+ apply: () => {
83
+ for (const name of missing) {
84
+ mkdirSync(join(directory, name), { recursive: true });
85
+ }
86
+ },
87
+ },
88
+ ];
89
+ }
90
+ }
@@ -1,6 +1,5 @@
1
1
  import {
2
2
  existsSync,
3
- lstatSync,
4
3
  mkdirSync,
5
4
  readdirSync,
6
5
  readFileSync,
@@ -10,34 +9,25 @@ import {
10
9
  writeFileSync,
11
10
  } from 'node:fs';
12
11
  import { basename, dirname, join, resolve } from 'node:path';
13
- import { readAgentTable } from '../agents/index.ts';
14
- import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
12
+ import { AgentTable } from '../agents/index.ts';
13
+ import { BASE_DIRECTORY, BaseDirectory } from '../common/index.ts';
15
14
  import { CodingAgents } from '../config/index.ts';
16
15
  import type { TResolvedConfig } from '../config/index.ts';
17
- import { ManifestConstants, renderManifest } from '../manifest/index.ts';
18
- import { readSlots } from '../rules/index.ts';
19
- import { planAgentFiles } from './agent-files.ts';
20
- import { SyncConstants, SyncStatuses } from './common/index.ts';
16
+ import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
17
+ import { RuleSlots } from '../rules/index.ts';
18
+ import { AgentFiles } from './agent-files.ts';
19
+ import { SyncConstants, SyncLinks, SyncStatuses } from './common/index.ts';
21
20
  import type { ISyncAction, TSettings } from './common/index.ts';
22
- import {
23
- buildProjectHookSettings,
24
- isSettingsObject,
25
- keepKeyOrder,
26
- mergeSettings,
27
- removeManagedSettings,
28
- } from './settings.ts';
21
+ import { isSettingsObject, ProjectSettings } from './settings.ts';
29
22
 
30
23
  const NO_CHANGE = (): void => {};
31
24
 
32
- const isSymlink = (opts: { path: string }): boolean =>
33
- lstatSync(opts.path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
34
-
35
25
  /** `CLAUDE.md` holds only `@AGENTS.md`: an old symlink or bun init's template is replaced, a hand-written file is left alone. */
36
26
  const planClaudeImport = (opts: { root: string }): ISyncAction => {
37
27
  const path = join(opts.root, SyncConstants.CLAUDE_TOOL_FILE);
38
28
  const write = (): void => writeFileSync(path, `${SyncConstants.CLAUDE_IMPORT_LINE}\n`);
39
29
 
40
- if (isSymlink({ path })) {
30
+ if (SyncLinks.isSymlink({ path })) {
41
31
  return {
42
32
  path,
43
33
  status: SyncStatuses.REPLACED,
@@ -95,17 +85,17 @@ const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
95
85
  readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE), 'utf8'),
96
86
  );
97
87
 
98
- for (const [id, slot] of Object.entries(readSlots())) {
88
+ for (const [id, slot] of Object.entries(RuleSlots.read())) {
99
89
  const choice = opts.config.rules[id];
100
90
  const settings = choice === undefined ? undefined : slot.options[choice]?.settings;
101
91
 
102
92
  if (settings !== undefined) {
103
- overlay = mergeSettings({ base: overlay, overlay: settings });
93
+ overlay = ProjectSettings.merge({ base: overlay, overlay: settings });
104
94
  }
105
95
  }
106
96
 
107
97
  if (opts.config.remoteHosts !== undefined) {
108
- overlay = mergeSettings({
98
+ overlay = ProjectSettings.merge({
109
99
  base: overlay,
110
100
  overlay: JSON.parse(
111
101
  readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.REMOTE_HOSTS_FILE), 'utf8'),
@@ -113,12 +103,12 @@ const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
113
103
  });
114
104
  }
115
105
 
116
- overlay = mergeSettings({
106
+ overlay = ProjectSettings.merge({
117
107
  base: overlay,
118
- overlay: buildProjectHookSettings({ hooks: opts.config.hooks }),
108
+ overlay: ProjectSettings.buildHook({ hooks: opts.config.hooks }),
119
109
  });
120
110
 
121
- return mergeSettings({ base: overlay, overlay: opts.config.claude.settings });
111
+ return ProjectSettings.merge({ base: overlay, overlay: opts.config.claude.settings });
122
112
  };
123
113
 
124
114
  /** The previous overlay is taken back before the new one merges in, so removed choices really disappear. */
@@ -139,12 +129,12 @@ const planSettings = (opts: { root: string; config: TResolvedConfig }): ISyncAct
139
129
 
140
130
  const previous = readSettingsFile({ path: managedPath }) ?? {};
141
131
  const overlay = buildManagedOverlay({ config: opts.config });
142
- const merged = mergeSettings({
143
- base: removeManagedSettings({ settings: current, managed: previous }),
132
+ const merged = ProjectSettings.merge({
133
+ base: ProjectSettings.removeManaged({ settings: current, managed: previous }),
144
134
  overlay,
145
135
  });
146
136
 
147
- const wanted = keepKeyOrder({ settings: merged, reference: current });
137
+ const wanted = ProjectSettings.keepKeyOrder({ settings: merged, reference: current });
148
138
 
149
139
  const text = `${JSON.stringify(wanted, null, 2)}\n`;
150
140
  const managedText = `${JSON.stringify(overlay, null, 2)}\n`;
@@ -194,7 +184,7 @@ const planSkillLinks = (opts: {
194
184
  const target = join(opts.root, opts.directory);
195
185
 
196
186
  // A symlinked skills directory points outside the project: writing links through it would land them there.
197
- if (isSymlink({ path: target })) {
187
+ if (SyncLinks.isSymlink({ path: target })) {
198
188
  return [
199
189
  {
200
190
  path: target,
@@ -205,7 +195,7 @@ const planSkillLinks = (opts: {
205
195
  ];
206
196
  }
207
197
 
208
- const stableSkills = join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY);
198
+ const stableSkills = join(BaseDirectory.stableOf(opts), SyncConstants.SKILLS_DIRECTORY);
209
199
  const shipped = findSkillDirectories({
210
200
  directory: join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),
211
201
  }).map((source) => join(stableSkills, basename(source)));
@@ -234,7 +224,7 @@ const planSkillLinks = (opts: {
234
224
  symlinkSync(resolve(source), path);
235
225
  };
236
226
 
237
- if (isSymlink({ path })) {
227
+ if (SyncLinks.isSymlink({ path })) {
238
228
  return readlinkSync(path) === resolve(source)
239
229
  ? { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }
240
230
  : {
@@ -266,7 +256,7 @@ const planSkillLinks = (opts: {
266
256
  const stale = (existsSync(target) ? readdirSync(target) : [])
267
257
  .filter((name) => !linked.has(name))
268
258
  .map((name) => join(target, name))
269
- .filter((path) => isSymlink({ path }) && !existsSync(path))
259
+ .filter((path) => SyncLinks.isSymlink({ path }) && !existsSync(path))
270
260
  .map((path) => ({ path, destination: readlinkSync(path) }))
271
261
  .filter(
272
262
  ({ destination }) =>
@@ -285,48 +275,54 @@ const planSkillLinks = (opts: {
285
275
  return [...links, ...shadowing, ...stale];
286
276
  };
287
277
 
288
- /** The committed project manifest (Project Contract v1, C1), rendered from the config. */
289
- export const planManifest = (opts: { root: string; config: TResolvedConfig }): ISyncAction => {
290
- const path = join(opts.root, ManifestConstants.FILE);
291
- const text = renderManifest(opts);
292
- const write = (): void => {
293
- mkdirSync(dirname(path), { recursive: true });
294
- writeFileSync(path, text);
295
- };
296
-
297
- if (!existsSync(path)) {
298
- return { path, status: SyncStatuses.CREATED, apply: write };
299
- }
300
-
301
- return readFileSync(path, 'utf8') === text
302
- ? { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }
303
- : { path, status: SyncStatuses.REPLACED, apply: write };
304
- };
305
-
306
- const CLAUDE_SKILLS = join(SyncConstants.CLAUDE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
307
-
308
278
  /** The skills folders of the chosen agents, each once, in table order: agents that read one folder share its links. */
309
279
  const skillDirectoriesOf = (opts: { agents: string[] }): string[] => [
310
280
  ...new Set(
311
- readAgentTable()
281
+ AgentTable.read()
312
282
  .filter((entry) => opts.agents.includes(entry.id))
313
283
  .map((entry) => entry.skills.dir),
314
284
  ),
315
285
  ];
316
286
 
317
- /** Every adapter the project's agents need, and the manifest every project carries - planned, not written. */
318
- export const planSync = (opts: {
319
- root: string;
320
- config: TResolvedConfig;
321
- /** The agents this machine chose (`resolveAgents`); only Claude has adapters until the renderers land. */
322
- agents: string[];
323
- }): ISyncAction[] => [
324
- ...(opts.agents.includes(CodingAgents.CLAUDE)
325
- ? [planClaudeImport({ root: opts.root }), planSettings(opts)]
326
- : []),
327
- ...skillDirectoriesOf({ agents: opts.agents }).flatMap((directory) =>
328
- planSkillLinks({ root: opts.root, directory, withProject: directory === CLAUDE_SKILLS }),
329
- ),
330
- ...planAgentFiles({ root: opts.root, agents: opts.agents }),
331
- planManifest(opts),
332
- ];
287
+ export class SyncPlanner {
288
+ /** The committed project manifest (Project Contract v1, C1), rendered from the config. */
289
+ static planManifest(opts: { root: string; config: TResolvedConfig }): ISyncAction {
290
+ const path = join(opts.root, ManifestConstants.FILE);
291
+ const text = ProjectManifest.render(opts);
292
+ const write = (): void => {
293
+ mkdirSync(dirname(path), { recursive: true });
294
+ writeFileSync(path, text);
295
+ };
296
+
297
+ if (!existsSync(path)) {
298
+ return { path, status: SyncStatuses.CREATED, apply: write };
299
+ }
300
+
301
+ return readFileSync(path, 'utf8') === text
302
+ ? { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }
303
+ : { path, status: SyncStatuses.REPLACED, apply: write };
304
+ }
305
+
306
+ /** Every adapter the project's agents need, and the manifest every project carries - planned, not written. */
307
+ static plan(opts: {
308
+ root: string;
309
+ config: TResolvedConfig;
310
+ /** The agents this machine chose (`AgentSelection.resolve`); only Claude has adapters until the renderers land. */
311
+ agents: string[];
312
+ }): ISyncAction[] {
313
+ return [
314
+ ...(opts.agents.includes(CodingAgents.CLAUDE)
315
+ ? [planClaudeImport({ root: opts.root }), planSettings(opts)]
316
+ : []),
317
+ ...skillDirectoriesOf({ agents: opts.agents }).flatMap((directory) =>
318
+ planSkillLinks({
319
+ root: opts.root,
320
+ directory,
321
+ withProject: directory === SyncConstants.CLAUDE_SKILLS,
322
+ }),
323
+ ),
324
+ ...AgentFiles.plan({ root: opts.root, agents: opts.agents }),
325
+ SyncPlanner.planManifest(opts),
326
+ ];
327
+ }
328
+ }
package/src/sync/prune.ts CHANGED
@@ -3,7 +3,7 @@ import { join } from 'node:path';
3
3
  import { BASE_DIRECTORY } from '../common/index.ts';
4
4
  import { SyncConstants, SyncStatuses } from './common/index.ts';
5
5
  import type { ISyncAction, TSettings } from './common/index.ts';
6
- import { extractHookCommands, isSettingsObject, removeHookCommands } from './settings.ts';
6
+ import { isSettingsObject, ProjectSettings } from './settings.ts';
7
7
 
8
8
  /**
9
9
  * The exact hook commands released VULCAN versions shipped (0.1.0-x, then 0.2.0-0). Only these are
@@ -70,7 +70,7 @@ const removeHookCommand = (opts: { path: string; command: string }): void => {
70
70
  continue;
71
71
  }
72
72
 
73
- const kept = removeHookCommands({ entries, commands: new Set([opts.command]) });
73
+ const kept = ProjectSettings.removeHookCommands({ entries, commands: new Set([opts.command]) });
74
74
 
75
75
  if (kept.length > 0) {
76
76
  hooks.value[event] = kept;
@@ -90,49 +90,53 @@ const isDeadLink = (opts: { path: string }): boolean => {
90
90
  }
91
91
  };
92
92
 
93
- /**
94
- * `sync --prune`: what sync can prove is stale and did not write itself - old VULCAN and plugin-era
95
- * hook commands, and skill links whose target is gone. What sync wrote last time it takes back on
96
- * every run; a developer's own hooks and any real directory are never touched.
97
- */
98
- export const planPrune = (opts: { root: string }): ISyncAction[] => {
99
- const directory = join(opts.root, SyncConstants.CLAUDE_DIRECTORY);
100
- const settingsPath = join(directory, SyncConstants.SETTINGS_FILE);
101
- const managed = new Set(
102
- extractHookCommands({
103
- settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }),
104
- }),
105
- );
106
- const shipped = new Set(
107
- extractHookCommands({
108
- settings: readJson({ path: join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE) }),
109
- }),
110
- );
111
- const staleCommands = [
112
- ...new Set(extractHookCommands({ settings: readJson({ path: settingsPath }) })),
113
- ].filter(
114
- (command) => !managed.has(command) && isStaleCommand({ root: opts.root, command, shipped }),
115
- );
116
- const skills = join(directory, SyncConstants.SKILLS_DIRECTORY);
117
- // lstat, not stat: a symlinked skills directory leads out of the project and is never walked.
118
- const deadLinks = lstatSync(skills, { throwIfNoEntry: false })?.isDirectory()
119
- ? readdirSync(skills)
120
- .map((name) => join(skills, name))
121
- .filter((path) => isDeadLink({ path }))
122
- : [];
123
-
124
- return [
125
- ...staleCommands.map((command): ISyncAction => ({
126
- path: settingsPath,
127
- status: SyncStatuses.REMOVED,
128
- note: `stale hook: ${command}`,
129
- apply: () => removeHookCommand({ path: settingsPath, command }),
130
- })),
131
- ...deadLinks.map((path): ISyncAction => ({
132
- path,
133
- status: SyncStatuses.REMOVED,
134
- note: 'dead link',
135
- apply: () => rmSync(path),
136
- })),
137
- ];
138
- };
93
+ export class PrunePlan {
94
+ /**
95
+ * `sync --prune`: what sync can prove is stale and did not write itself - old VULCAN and plugin-era
96
+ * hook commands, and skill links whose target is gone. What sync wrote last time it takes back on
97
+ * every run; a developer's own hooks and any real directory are never touched.
98
+ */
99
+ static plan(opts: { root: string }): ISyncAction[] {
100
+ const directory = join(opts.root, SyncConstants.CLAUDE_DIRECTORY);
101
+ const settingsPath = join(directory, SyncConstants.SETTINGS_FILE);
102
+ const managed = new Set(
103
+ ProjectSettings.extractHookCommands({
104
+ settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }),
105
+ }),
106
+ );
107
+ const shipped = new Set(
108
+ ProjectSettings.extractHookCommands({
109
+ settings: readJson({ path: join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE) }),
110
+ }),
111
+ );
112
+ const staleCommands = [
113
+ ...new Set(
114
+ ProjectSettings.extractHookCommands({ settings: readJson({ path: settingsPath }) }),
115
+ ),
116
+ ].filter(
117
+ (command) => !managed.has(command) && isStaleCommand({ root: opts.root, command, shipped }),
118
+ );
119
+ const skills = join(directory, SyncConstants.SKILLS_DIRECTORY);
120
+ // lstat, not stat: a symlinked skills directory leads out of the project and is never walked.
121
+ const deadLinks = lstatSync(skills, { throwIfNoEntry: false })?.isDirectory()
122
+ ? readdirSync(skills)
123
+ .map((name) => join(skills, name))
124
+ .filter((path) => isDeadLink({ path }))
125
+ : [];
126
+
127
+ return [
128
+ ...staleCommands.map((command): ISyncAction => ({
129
+ path: settingsPath,
130
+ status: SyncStatuses.REMOVED,
131
+ note: `stale hook: ${command}`,
132
+ apply: () => removeHookCommand({ path: settingsPath, command }),
133
+ })),
134
+ ...deadLinks.map((path): ISyncAction => ({
135
+ path,
136
+ status: SyncStatuses.REMOVED,
137
+ note: 'dead link',
138
+ apply: () => rmSync(path),
139
+ })),
140
+ ];
141
+ }
142
+ }