@venizia/vulcan 0.4.9-0 → 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 (140) 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/visualize-work/SKILL.md +9 -0
  17. package/package.json +3 -3
  18. package/src/agents/atlas-block.ts +43 -43
  19. package/src/agents/codex-hooks.ts +45 -43
  20. package/src/agents/detect.ts +19 -16
  21. package/src/agents/exclude.ts +96 -97
  22. package/src/agents/hooks-json.ts +38 -36
  23. package/src/agents/local.ts +46 -43
  24. package/src/agents/prompt.ts +45 -42
  25. package/src/agents/render.ts +201 -195
  26. package/src/agents/resolve.ts +133 -134
  27. package/src/agents/table.ts +12 -8
  28. package/src/commands/add.command.ts +2 -2
  29. package/src/commands/agents.command.ts +11 -17
  30. package/src/commands/clean.command.ts +6 -6
  31. package/src/commands/doctor.command.ts +4 -4
  32. package/src/commands/init.command.ts +12 -8
  33. package/src/commands/preset.command.ts +2 -2
  34. package/src/commands/profile.command.ts +42 -49
  35. package/src/commands/sync.command.ts +109 -111
  36. package/src/commands/upgrade.command.ts +80 -75
  37. package/src/commands/visualize.command.ts +7 -13
  38. package/src/commands/x.command.ts +55 -50
  39. package/src/common/format.ts +23 -21
  40. package/src/common/json.ts +8 -5
  41. package/src/common/layout-folder.ts +94 -91
  42. package/src/common/paths.ts +14 -12
  43. package/src/config/loader.ts +52 -49
  44. package/src/config/packages.ts +14 -11
  45. package/src/config/schema.ts +3 -3
  46. package/src/create/add-app.ts +519 -509
  47. package/src/create/add-lib.ts +237 -240
  48. package/src/create/bunfig.ts +26 -23
  49. package/src/create/checks.ts +36 -34
  50. package/src/create/diff.ts +21 -23
  51. package/src/create/dockerignore.ts +26 -24
  52. package/src/create/files.ts +7 -5
  53. package/src/create/init-monorepo.ts +75 -80
  54. package/src/create/lib-preset.ts +59 -63
  55. package/src/create/manifest-json.ts +10 -4
  56. package/src/create/names.ts +217 -210
  57. package/src/create/next.ts +26 -23
  58. package/src/create/plan.ts +15 -12
  59. package/src/create/preset-diff.ts +301 -303
  60. package/src/create/preset-menu.ts +38 -32
  61. package/src/create/preset.ts +202 -197
  62. package/src/create/process.ts +79 -72
  63. package/src/create/scratch.ts +48 -49
  64. package/src/create/workspace.ts +404 -396
  65. package/src/doctor/checks.ts +1027 -1014
  66. package/src/doctor/makefile.ts +17 -13
  67. package/src/doctor/runner.ts +88 -118
  68. package/src/doctor/skills.ts +97 -95
  69. package/src/doctor/tags.ts +42 -37
  70. package/src/hooks/codex-patch.ts +25 -22
  71. package/src/hooks/command-view.ts +44 -39
  72. package/src/hooks/decision.ts +37 -37
  73. package/src/hooks/guard-git.ts +51 -49
  74. package/src/hooks/guard-manifest.ts +58 -55
  75. package/src/hooks/guard-outside.ts +93 -91
  76. package/src/hooks/guard-package.ts +82 -79
  77. package/src/hooks/guard-scripting.ts +19 -14
  78. package/src/hooks/guard-writes.ts +154 -149
  79. package/src/hooks/owner-reply.ts +127 -127
  80. package/src/hooks/post-tool.ts +94 -93
  81. package/src/hooks/project-guards.ts +65 -62
  82. package/src/hooks/project-tmp.ts +27 -24
  83. package/src/hooks/remote-hosts.ts +153 -130
  84. package/src/hooks/session-digest.ts +98 -101
  85. package/src/hooks/shell.ts +509 -499
  86. package/src/hooks/subagent-card.ts +11 -7
  87. package/src/hooks/trusted-scripts.ts +106 -104
  88. package/src/init/scaffold.ts +135 -132
  89. package/src/local/clean.ts +38 -36
  90. package/src/local/format.ts +21 -17
  91. package/src/local/scan.ts +144 -138
  92. package/src/manifest/render.ts +110 -104
  93. package/src/owner/card.ts +51 -46
  94. package/src/owner/profile.ts +99 -93
  95. package/src/owner/reply-switch.ts +9 -6
  96. package/src/owner/shape.ts +71 -69
  97. package/src/owner/survey.ts +173 -171
  98. package/src/owner/view.ts +62 -59
  99. package/src/owner/violations.ts +119 -123
  100. package/src/rules/base.ts +15 -11
  101. package/src/rules/parser.ts +39 -32
  102. package/src/rules/slots.ts +8 -6
  103. package/src/signals/claims.ts +30 -28
  104. package/src/signals/classify.ts +36 -33
  105. package/src/signals/loop.ts +39 -37
  106. package/src/signals/state.ts +79 -81
  107. package/src/skills/frontmatter.ts +28 -28
  108. package/src/sync/agent-files.ts +217 -199
  109. package/src/sync/agent-removal.ts +56 -59
  110. package/src/sync/atlas-block.ts +45 -43
  111. package/src/sync/base-rules.ts +32 -30
  112. package/src/sync/claude-launch.ts +36 -34
  113. package/src/sync/exclude.ts +77 -69
  114. package/src/sync/local-choice.ts +50 -47
  115. package/src/sync/planner.ts +59 -61
  116. package/src/sync/prune.ts +52 -48
  117. package/src/sync/settings.ts +166 -167
  118. package/src/ui/capability.ts +12 -7
  119. package/src/ui/keyboard.ts +38 -38
  120. package/src/ui/prompt.ts +79 -77
  121. package/src/visualize/assets.ts +33 -24
  122. package/src/visualize/charts.ts +179 -176
  123. package/src/visualize/compare-css.ts +3 -2
  124. package/src/visualize/compare-render.ts +9 -7
  125. package/src/visualize/diagrams.ts +189 -174
  126. package/src/visualize/grid-span.ts +34 -0
  127. package/src/visualize/icons.ts +7 -5
  128. package/src/visualize/kinds-render.ts +50 -45
  129. package/src/visualize/kinds-validate.ts +12 -10
  130. package/src/visualize/labels.ts +21 -17
  131. package/src/visualize/layout.ts +112 -97
  132. package/src/visualize/page.ts +92 -104
  133. package/src/visualize/render.ts +143 -140
  134. package/src/visualize/sections.ts +395 -384
  135. package/src/visualize/sources.ts +2 -2
  136. package/src/visualize/theme.ts +12 -10
  137. package/src/visualize/validate.ts +13 -9
  138. package/src/wiki/anchors.ts +38 -36
  139. package/src/wiki/command.ts +4 -4
  140. package/src/wiki/source-links.ts +46 -44
@@ -80,55 +80,57 @@ type TCodexHooksMerge =
80
80
  | { ok: true; changed: boolean; text: string }
81
81
  | { ok: false; reason: string };
82
82
 
83
- /** The hooks file with VULCAN's PreToolUse entry in it, every other entry as the user wrote it. */
84
- export const mergeCodexHooks = (opts: { text: string | undefined }): TCodexHooksMerge => {
85
- const parsed = parseFile({ text: opts.text });
83
+ export class CodexHooks {
84
+ /** The hooks file with VULCAN's PreToolUse entry in it, every other entry as the user wrote it. */
85
+ static merge(opts: { text: string | undefined }): TCodexHooksMerge {
86
+ const parsed = parseFile({ text: opts.text });
86
87
 
87
- if ('reason' in parsed) {
88
- return { ok: false, reason: parsed.reason };
88
+ if ('reason' in parsed) {
89
+ return { ok: false, reason: parsed.reason };
90
+ }
91
+
92
+ const entry = guardEntry();
93
+ const index = parsed.entries.findIndex((item) => isGuardEntry(item));
94
+ const changed = index === -1 || JSON.stringify(parsed.entries[index]) !== JSON.stringify(entry);
95
+ const entries =
96
+ index === -1
97
+ ? [...parsed.entries, entry]
98
+ : parsed.entries.map((item, at) => (at === index ? entry : item));
99
+
100
+ return {
101
+ ok: true,
102
+ changed,
103
+ text: `${JSON.stringify({ ...parsed.file, hooks: { ...parsed.hooks, PreToolUse: entries } }, null, 2)}\n`,
104
+ };
89
105
  }
90
106
 
91
- const entry = guardEntry();
92
- const index = parsed.entries.findIndex((item) => isGuardEntry(item));
93
- const changed = index === -1 || JSON.stringify(parsed.entries[index]) !== JSON.stringify(entry);
94
- const entries =
95
- index === -1
96
- ? [...parsed.entries, entry]
97
- : parsed.entries.map((item, at) => (at === index ? entry : item));
98
-
99
- return {
100
- ok: true,
101
- changed,
102
- text: `${JSON.stringify({ ...parsed.file, hooks: { ...parsed.hooks, PreToolUse: entries } }, null, 2)}\n`,
103
- };
104
- };
107
+ /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
108
+ static remove(opts: { text: string }): TCodexHooksRemoval {
109
+ const parsed = parseFile({ text: opts.text });
105
110
 
106
- type TCodexHooksRemoval =
107
- | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
108
- | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
109
- | { ok: false; reason: string };
111
+ if ('reason' in parsed) {
112
+ return { ok: false, reason: parsed.reason };
113
+ }
110
114
 
111
- /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
112
- export const removeCodexHooks = (opts: { text: string }): TCodexHooksRemoval => {
113
- const parsed = parseFile({ text: opts.text });
115
+ if (!parsed.entries.some((item) => isGuardEntry(item))) {
116
+ return { ok: true, outcome: RemoveOutcomes.ABSENT };
117
+ }
114
118
 
115
- if ('reason' in parsed) {
116
- return { ok: false, reason: parsed.reason };
117
- }
119
+ const kept = parsed.entries.filter((item) => !isGuardEntry(item));
120
+ const { PreToolUse: _removed, ...otherEvents } = parsed.hooks;
121
+ const hooks = kept.length > 0 ? { ...otherEvents, PreToolUse: kept } : otherEvents;
122
+ const { hooks: _hooks, ...otherKeys } = parsed.file;
123
+ const file = Object.keys(hooks).length > 0 ? { ...otherKeys, hooks } : otherKeys;
118
124
 
119
- if (!parsed.entries.some((item) => isGuardEntry(item))) {
120
- return { ok: true, outcome: RemoveOutcomes.ABSENT };
125
+ return {
126
+ ok: true,
127
+ outcome: RemoveOutcomes.REMOVED,
128
+ text: Object.keys(file).length === 0 ? undefined : `${JSON.stringify(file, null, 2)}\n`,
129
+ };
121
130
  }
131
+ }
122
132
 
123
- const kept = parsed.entries.filter((item) => !isGuardEntry(item));
124
- const { PreToolUse: _removed, ...otherEvents } = parsed.hooks;
125
- const hooks = kept.length > 0 ? { ...otherEvents, PreToolUse: kept } : otherEvents;
126
- const { hooks: _hooks, ...otherKeys } = parsed.file;
127
- const file = Object.keys(hooks).length > 0 ? { ...otherKeys, hooks } : otherKeys;
128
-
129
- return {
130
- ok: true,
131
- outcome: RemoveOutcomes.REMOVED,
132
- text: Object.keys(file).length === 0 ? undefined : `${JSON.stringify(file, null, 2)}\n`,
133
- };
134
- };
133
+ type TCodexHooksRemoval =
134
+ | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
135
+ | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
136
+ | { ok: false; reason: string };
@@ -1,7 +1,7 @@
1
1
  import { Glob } from 'bun';
2
2
  import { existsSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
- import { readAgentTable } from './table.ts';
4
+ import { AgentTable } from './table.ts';
5
5
 
6
6
  const HOME_PREFIX = '~/';
7
7
 
@@ -18,19 +18,22 @@ const hasHomeEntry = (opts: { home: string; pattern: string }): boolean => {
18
18
  );
19
19
  };
20
20
 
21
- /**
22
- * The agents this machine seems to have, in table order: a binary on PATH, a folder in the home, a
23
- * folder in the project. It only pre-selects; the developer confirms.
24
- */
25
- export const detectAgents = (opts: { root: string; home: string; path: string }): string[] =>
26
- readAgentTable()
27
- .filter((entry) => {
28
- const { binaries, homeDirs, projectDirs } = entry.detect;
21
+ export class AgentDetection {
22
+ /**
23
+ * The agents this machine seems to have, in table order: a binary on PATH, a folder in the home, a
24
+ * folder in the project. It only pre-selects; the developer confirms.
25
+ */
26
+ static detect(opts: { root: string; home: string; path: string }): string[] {
27
+ return AgentTable.read()
28
+ .filter((entry) => {
29
+ const { binaries, homeDirs, projectDirs } = entry.detect;
29
30
 
30
- return (
31
- binaries.some((name) => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
32
- homeDirs.some((pattern) => hasHomeEntry({ home: opts.home, pattern })) ||
33
- projectDirs.some((directory) => existsSync(join(opts.root, directory)))
34
- );
35
- })
36
- .map((entry) => entry.id);
31
+ return (
32
+ binaries.some((name) => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
33
+ homeDirs.some((pattern) => hasHomeEntry({ home: opts.home, pattern })) ||
34
+ projectDirs.some((directory) => existsSync(join(opts.root, directory)))
35
+ );
36
+ })
37
+ .map((entry) => entry.id);
38
+ }
39
+ }
@@ -1,6 +1,6 @@
1
1
  import { AgentConstants, AgentScopes } from './common/index.ts';
2
2
  import { LOCAL_AGENTS_FILE } from './local.ts';
3
- import { readAgentTable } from './table.ts';
3
+ import { AgentTable } from './table.ts';
4
4
 
5
5
  export const EXCLUDE_BLOCK_START =
6
6
  '# vulcan:start - written by vulcan sync for the agents you chose; do not edit';
@@ -16,110 +16,109 @@ interface IExcludeGroup {
16
16
  paths: string[];
17
17
  }
18
18
 
19
- /**
20
- * What sync creates for the chosen agents and so keeps out of `git status` on this machine: the
21
- * shim and folder of Claude, each agent's own MCP file, the shipped-skill links of the folders the
22
- * agents read (once per folder), and the local choice file.
23
- */
24
- export const excludePathsOf = (opts: {
25
- agents: string[];
26
- skillNames: string[];
27
- }): IExcludeGroup[] => {
28
- const listedSkills = new Set<string>();
29
- let listedShared = false;
30
- const groups: IExcludeGroup[] = [];
31
-
32
- for (const entry of readAgentTable().filter((item) => opts.agents.includes(item.id))) {
33
- const paths: string[] = [];
34
-
35
- if (entry.instructions.shim !== null) {
36
- paths.push(`/${entry.instructions.shim.path}`);
37
- }
38
-
39
- if (entry.id === AgentConstants.DEFAULT_AGENT) {
40
- paths.push('/.claude/');
41
- }
42
-
43
- if (entry.mcp.scope === AgentScopes.PROJECT) {
44
- paths.push(`/${entry.mcp.path}`);
45
- } else if (!listedShared) {
46
- // The root `.mcp.json` several agents read is listed once, under the first of them.
47
- listedShared = true;
48
- paths.push(`/${AgentConstants.SHARED_MCP_FILE}`);
49
- }
50
-
51
- if (entry.guards !== null) {
52
- paths.push(`/${entry.guards.path}`);
53
- }
54
-
55
- if (entry.skills.dir !== CLAUDE_SKILLS_DIRECTORY && !listedSkills.has(entry.skills.dir)) {
56
- listedSkills.add(entry.skills.dir);
57
- paths.push(...opts.skillNames.map((name) => `/${entry.skills.dir}/${name}`));
58
- }
59
-
60
- if (paths.length > 0) {
61
- groups.push({ title: entry.id, paths });
62
- }
63
- }
64
-
65
- return [...groups, { title: 'local', paths: [`/${LOCAL_AGENTS_FILE}`] }];
66
- };
67
-
68
- /**
69
- * One block per project: a project below the git top level (an app in a monorepo, a scratch app
70
- * inside a repo) names its path from the top level in the start line, so syncing it never touches
71
- * the block of the top level or of another project. The top level keeps the plain start line.
72
- */
73
- export const renderExcludeBlock = (opts: { groups: IExcludeGroup[]; prefix?: string }): string =>
74
- [
75
- opts.prefix === undefined || opts.prefix === ''
76
- ? EXCLUDE_BLOCK_START
77
- : EXCLUDE_BLOCK_START.replace(START_PREFIX, `${START_PREFIX} (${opts.prefix})`),
78
- ...opts.groups.flatMap((group) => [`# ${group.title}`, ...group.paths]),
79
- EXCLUDE_BLOCK_END,
80
- '',
81
- ].join('\n');
82
-
83
19
  const blockKeyOf = (line: string): string | undefined => {
84
20
  const match = START_PATTERN.exec(line);
85
21
 
86
22
  return match === null ? undefined : (match[1] ?? '');
87
23
  };
88
24
 
89
- /**
90
- * The block of `opts.prefix` replaces itself between its markers; the user's own lines in the
91
- * file, and the blocks of other projects, are never touched.
92
- */
93
- export const mergeExcludeBlock = (opts: {
94
- text: string | undefined;
95
- block: string;
96
- prefix?: string;
97
- }): { changed: boolean; text: string } => {
98
- if (opts.text === undefined || opts.text === '') {
99
- return { changed: true, text: opts.block };
25
+ export class AgentExclude {
26
+ /**
27
+ * What sync creates for the chosen agents and so keeps out of `git status` on this machine: the
28
+ * shim and folder of Claude, each agent's own MCP file, the shipped-skill links of the folders the
29
+ * agents read (once per folder), and the local choice file.
30
+ */
31
+ static excludePathsOf(opts: { agents: string[]; skillNames: string[] }): IExcludeGroup[] {
32
+ const listedSkills = new Set<string>();
33
+ let listedShared = false;
34
+ const groups: IExcludeGroup[] = [];
35
+
36
+ for (const entry of AgentTable.read().filter((item) => opts.agents.includes(item.id))) {
37
+ const paths: string[] = [];
38
+
39
+ if (entry.instructions.shim !== null) {
40
+ paths.push(`/${entry.instructions.shim.path}`);
41
+ }
42
+
43
+ if (entry.id === AgentConstants.DEFAULT_AGENT) {
44
+ paths.push('/.claude/');
45
+ }
46
+
47
+ if (entry.mcp.scope === AgentScopes.PROJECT) {
48
+ paths.push(`/${entry.mcp.path}`);
49
+ } else if (!listedShared) {
50
+ // The root `.mcp.json` several agents read is listed once, under the first of them.
51
+ listedShared = true;
52
+ paths.push(`/${AgentConstants.SHARED_MCP_FILE}`);
53
+ }
54
+
55
+ if (entry.guards !== null) {
56
+ paths.push(`/${entry.guards.path}`);
57
+ }
58
+
59
+ if (entry.skills.dir !== CLAUDE_SKILLS_DIRECTORY && !listedSkills.has(entry.skills.dir)) {
60
+ listedSkills.add(entry.skills.dir);
61
+ paths.push(...opts.skillNames.map((name) => `/${entry.skills.dir}/${name}`));
62
+ }
63
+
64
+ if (paths.length > 0) {
65
+ groups.push({ title: entry.id, paths });
66
+ }
67
+ }
68
+
69
+ return [...groups, { title: 'local', paths: [`/${LOCAL_AGENTS_FILE}`] }];
100
70
  }
101
71
 
102
- const lines = opts.text.split('\n');
103
- const start = lines.findIndex((line) => blockKeyOf(line) === (opts.prefix ?? ''));
104
- const stop = lines.findIndex(
105
- (line, index) =>
106
- index > start && (line.trimEnd() === EXCLUDE_BLOCK_END || blockKeyOf(line) !== undefined),
107
- );
108
-
109
- // A block with no end marker before the next block starts is left alone: replacing it would
110
- // swallow the next project's block.
111
- if (start !== -1 && stop !== -1 && lines[stop]?.trimEnd() === EXCLUDE_BLOCK_END) {
112
- const text = [
113
- ...lines.slice(0, start),
114
- ...opts.block.trimEnd().split('\n'),
115
- ...lines.slice(stop + 1),
72
+ /**
73
+ * One block per project: a project below the git top level (an app in a monorepo, a scratch app
74
+ * inside a repo) names its path from the top level in the start line, so syncing it never touches
75
+ * the block of the top level or of another project. The top level keeps the plain start line.
76
+ */
77
+ static renderBlock(opts: { groups: IExcludeGroup[]; prefix?: string }): string {
78
+ return [
79
+ opts.prefix === undefined || opts.prefix === ''
80
+ ? EXCLUDE_BLOCK_START
81
+ : EXCLUDE_BLOCK_START.replace(START_PREFIX, `${START_PREFIX} (${opts.prefix})`),
82
+ ...opts.groups.flatMap((group) => [`# ${group.title}`, ...group.paths]),
83
+ EXCLUDE_BLOCK_END,
84
+ '',
116
85
  ].join('\n');
117
-
118
- return { changed: text !== opts.text, text };
119
86
  }
120
87
 
121
- return {
122
- changed: true,
123
- text: `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`,
124
- };
125
- };
88
+ /**
89
+ * The block of `opts.prefix` replaces itself between its markers; the user's own lines in the
90
+ * file, and the blocks of other projects, are never touched.
91
+ */
92
+ static mergeBlock(opts: { text: string | undefined; block: string; prefix?: string }): {
93
+ changed: boolean;
94
+ text: string;
95
+ } {
96
+ if (opts.text === undefined || opts.text === '') {
97
+ return { changed: true, text: opts.block };
98
+ }
99
+
100
+ const lines = opts.text.split('\n');
101
+ const start = lines.findIndex((line) => blockKeyOf(line) === (opts.prefix ?? ''));
102
+ const stop = lines.findIndex(
103
+ (line, index) =>
104
+ index > start && (line.trimEnd() === EXCLUDE_BLOCK_END || blockKeyOf(line) !== undefined),
105
+ );
106
+
107
+ // A block with no end marker before the next block starts is left alone: replacing it would
108
+ // swallow the next project's block.
109
+ if (start !== -1 && stop !== -1 && lines[stop]?.trimEnd() === EXCLUDE_BLOCK_END) {
110
+ const text = [
111
+ ...lines.slice(0, start),
112
+ ...opts.block.trimEnd().split('\n'),
113
+ ...lines.slice(stop + 1),
114
+ ].join('\n');
115
+
116
+ return { changed: text !== opts.text, text };
117
+ }
118
+
119
+ return {
120
+ changed: true,
121
+ text: `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`,
122
+ };
123
+ }
124
+ }
@@ -60,48 +60,50 @@ const parseHooks = (opts: { text: string | undefined }): TParsedHooks => {
60
60
 
61
61
  type THooksMerge = { ok: true; changed: boolean; text: string } | { ok: false; reason: string };
62
62
 
63
- /** The hooks file with VULCAN's entry in it, every other hook as the user wrote it. */
64
- export const mergeGuardHook = (opts: { text: string | undefined }): THooksMerge => {
65
- const parsed = parseHooks({ text: opts.text });
63
+ export class GuardHook {
64
+ /** The hooks file with VULCAN's entry in it, every other hook as the user wrote it. */
65
+ static merge(opts: { text: string | undefined }): THooksMerge {
66
+ const parsed = parseHooks({ text: opts.text });
66
67
 
67
- if (!parsed.ok) {
68
- return parsed;
69
- }
68
+ if (!parsed.ok) {
69
+ return parsed;
70
+ }
70
71
 
71
- const entry = guardEntry();
72
- const changed = JSON.stringify(parsed.hooks[GUARD_HOOK_NAME]) !== JSON.stringify(entry);
72
+ const entry = guardEntry();
73
+ const changed = JSON.stringify(parsed.hooks[GUARD_HOOK_NAME]) !== JSON.stringify(entry);
73
74
 
74
- return {
75
- ok: true,
76
- changed,
77
- text: `${JSON.stringify({ ...parsed.hooks, [GUARD_HOOK_NAME]: entry }, null, 2)}\n`,
78
- };
79
- };
75
+ return {
76
+ ok: true,
77
+ changed,
78
+ text: `${JSON.stringify({ ...parsed.hooks, [GUARD_HOOK_NAME]: entry }, null, 2)}\n`,
79
+ };
80
+ }
80
81
 
81
- type THooksRemoval =
82
- | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
83
- | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
84
- | { ok: false; reason: string };
82
+ /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
83
+ static remove(opts: { text: string }): THooksRemoval {
84
+ const parsed = parseHooks({ text: opts.text });
85
85
 
86
- /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
87
- export const removeGuardHook = (opts: { text: string }): THooksRemoval => {
88
- const parsed = parseHooks({ text: opts.text });
86
+ if (!parsed.ok) {
87
+ return parsed;
88
+ }
89
89
 
90
- if (!parsed.ok) {
91
- return parsed;
92
- }
90
+ if (!Object.hasOwn(parsed.hooks, GUARD_HOOK_NAME)) {
91
+ return { ok: true, outcome: RemoveOutcomes.ABSENT };
92
+ }
93
93
 
94
- if (!Object.hasOwn(parsed.hooks, GUARD_HOOK_NAME)) {
95
- return { ok: true, outcome: RemoveOutcomes.ABSENT };
96
- }
94
+ const others = Object.fromEntries(
95
+ Object.entries(parsed.hooks).filter(([name]) => name !== GUARD_HOOK_NAME),
96
+ );
97
97
 
98
- const others = Object.fromEntries(
99
- Object.entries(parsed.hooks).filter(([name]) => name !== GUARD_HOOK_NAME),
100
- );
98
+ return {
99
+ ok: true,
100
+ outcome: RemoveOutcomes.REMOVED,
101
+ text: Object.keys(others).length === 0 ? undefined : `${JSON.stringify(others, null, 2)}\n`,
102
+ };
103
+ }
104
+ }
101
105
 
102
- return {
103
- ok: true,
104
- outcome: RemoveOutcomes.REMOVED,
105
- text: Object.keys(others).length === 0 ? undefined : `${JSON.stringify(others, null, 2)}\n`,
106
- };
107
- };
106
+ type THooksRemoval =
107
+ | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
108
+ | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
109
+ | { ok: false; reason: string };
@@ -3,7 +3,7 @@ import { join } from 'node:path';
3
3
  import { z } from 'zod';
4
4
  import { AgentConstants } from './common/index.ts';
5
5
  import type { TLocalChoice } from './common/index.ts';
6
- import { agentIds } from './table.ts';
6
+ import { AgentTable } from './table.ts';
7
7
 
8
8
  export const LOCAL_AGENTS_FILE = AgentConstants.LOCAL_FILE;
9
9
 
@@ -12,54 +12,57 @@ const LOCAL_SCHEMA = z.object({
12
12
  agents: z.array(z.string()),
13
13
  });
14
14
 
15
- export const renderLocalChoice = (opts: { agents: string[] }): string =>
16
- `${JSON.stringify(
17
- {
18
- $generated: AgentConstants.LOCAL_NOTE,
19
- schemaVersion: AgentConstants.LOCAL_SCHEMA_VERSION,
20
- agents: opts.agents,
21
- },
22
- null,
23
- 2,
24
- )}\n`;
15
+ export class LocalChoice {
16
+ static render(opts: { agents: string[] }): string {
17
+ return `${JSON.stringify(
18
+ {
19
+ $generated: AgentConstants.LOCAL_NOTE,
20
+ schemaVersion: AgentConstants.LOCAL_SCHEMA_VERSION,
21
+ agents: opts.agents,
22
+ },
23
+ null,
24
+ 2,
25
+ )}\n`;
26
+ }
25
27
 
26
- /** The developer's stored choice: absent is "not chosen yet", a broken file is an error, never a silent default. */
27
- export const readLocalChoice = (opts: { root: string }): TLocalChoice => {
28
- const file = join(opts.root, LOCAL_AGENTS_FILE);
28
+ /** The developer's stored choice: absent is "not chosen yet", a broken file is an error, never a silent default. */
29
+ static read(opts: { root: string }): TLocalChoice {
30
+ const file = join(opts.root, LOCAL_AGENTS_FILE);
29
31
 
30
- if (!existsSync(file)) {
31
- return { ok: true, agents: undefined };
32
- }
32
+ if (!existsSync(file)) {
33
+ return { ok: true, agents: undefined };
34
+ }
33
35
 
34
- let parsed: unknown;
36
+ let parsed: unknown;
35
37
 
36
- try {
37
- parsed = JSON.parse(readFileSync(file, 'utf8'));
38
- } catch {
39
- return {
40
- ok: false,
41
- error: `${LOCAL_AGENTS_FILE} is not valid JSON - delete it and run: vulcan sync --agents <list>`,
42
- };
43
- }
38
+ try {
39
+ parsed = JSON.parse(readFileSync(file, 'utf8'));
40
+ } catch {
41
+ return {
42
+ ok: false,
43
+ error: `${LOCAL_AGENTS_FILE} is not valid JSON - delete it and run: vulcan sync --agents <list>`,
44
+ };
45
+ }
44
46
 
45
- const checked = LOCAL_SCHEMA.safeParse(parsed);
47
+ const checked = LOCAL_SCHEMA.safeParse(parsed);
46
48
 
47
- if (!checked.success) {
48
- return {
49
- ok: false,
50
- error: `${LOCAL_AGENTS_FILE} is not what vulcan sync writes - delete it and run: vulcan sync --agents <list>`,
51
- };
52
- }
49
+ if (!checked.success) {
50
+ return {
51
+ ok: false,
52
+ error: `${LOCAL_AGENTS_FILE} is not what vulcan sync writes - delete it and run: vulcan sync --agents <list>`,
53
+ };
54
+ }
53
55
 
54
- const known = new Set(agentIds());
55
- const unknown = checked.data.agents.find((id) => !known.has(id));
56
+ const known = new Set(AgentTable.agentIds());
57
+ const unknown = checked.data.agents.find((id) => !known.has(id));
56
58
 
57
- if (unknown !== undefined) {
58
- return {
59
- ok: false,
60
- error: `${LOCAL_AGENTS_FILE} names unknown agent '${unknown}' - one of: ${[...known].join(', ')}`,
61
- };
62
- }
59
+ if (unknown !== undefined) {
60
+ return {
61
+ ok: false,
62
+ error: `${LOCAL_AGENTS_FILE} names unknown agent '${unknown}' - one of: ${[...known].join(', ')}`,
63
+ };
64
+ }
63
65
 
64
- return { ok: true, agents: checked.data.agents };
65
- };
66
+ return { ok: true, agents: checked.data.agents };
67
+ }
68
+ }