@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 { 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';
@@ -10,116 +10,115 @@ const START_PREFIX = '# vulcan:start';
10
10
  const START_PATTERN = /^# vulcan:start(?: \((.*)\))? - written/;
11
11
  const CLAUDE_SKILLS_DIRECTORY = '.claude/skills';
12
12
 
13
- export interface IExcludeGroup {
13
+ interface IExcludeGroup {
14
14
  title: string;
15
15
  /** Root-relative and anchored with a leading slash; a folder ends with one. */
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
+ }
@@ -1,8 +1,6 @@
1
+ import { RecordValue } from '../common/record.ts';
1
2
  import { RemoveOutcomes } from './common/index.ts';
2
3
 
3
- const isRecord = (value: unknown): value is Record<string, unknown> =>
4
- typeof value === 'object' && value !== null && !Array.isArray(value);
5
-
6
4
  /** The key of VULCAN's entry in Antigravity's hooks file: the file maps a hook name to its events. */
7
5
  export const GUARD_HOOK_NAME = 'vulcan-guards';
8
6
 
@@ -49,7 +47,7 @@ const parseHooks = (opts: { text: string | undefined }): TParsedHooks => {
49
47
  try {
50
48
  const parsed: unknown = JSON.parse(opts.text);
51
49
 
52
- return isRecord(parsed)
50
+ return RecordValue.isRecord(parsed)
53
51
  ? { ok: true, hooks: parsed }
54
52
  : { ok: false, reason: 'the hooks file is not a JSON object' };
55
53
  } catch (error) {
@@ -60,52 +58,52 @@ const parseHooks = (opts: { text: string | undefined }): TParsedHooks => {
60
58
  }
61
59
  };
62
60
 
63
- export type THooksMerge =
64
- | { ok: true; changed: boolean; text: string }
65
- | { ok: false; reason: string };
61
+ type THooksMerge = { ok: true; changed: boolean; text: string } | { ok: false; reason: string };
66
62
 
67
- /** The hooks file with VULCAN's entry in it, every other hook as the user wrote it. */
68
- export const mergeGuardHook = (opts: { text: string | undefined }): THooksMerge => {
69
- 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 });
70
67
 
71
- if (!parsed.ok) {
72
- return parsed;
73
- }
68
+ if (!parsed.ok) {
69
+ return parsed;
70
+ }
74
71
 
75
- const entry = guardEntry();
76
- 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);
77
74
 
78
- return {
79
- ok: true,
80
- changed,
81
- text: `${JSON.stringify({ ...parsed.hooks, [GUARD_HOOK_NAME]: entry }, null, 2)}\n`,
82
- };
83
- };
75
+ return {
76
+ ok: true,
77
+ changed,
78
+ text: `${JSON.stringify({ ...parsed.hooks, [GUARD_HOOK_NAME]: entry }, null, 2)}\n`,
79
+ };
80
+ }
84
81
 
85
- export type THooksRemoval =
86
- | { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
87
- | { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
88
- | { 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 });
89
85
 
90
- /** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
91
- export const removeGuardHook = (opts: { text: string }): THooksRemoval => {
92
- const parsed = parseHooks({ text: opts.text });
86
+ if (!parsed.ok) {
87
+ return parsed;
88
+ }
93
89
 
94
- if (!parsed.ok) {
95
- return parsed;
96
- }
90
+ if (!Object.hasOwn(parsed.hooks, GUARD_HOOK_NAME)) {
91
+ return { ok: true, outcome: RemoveOutcomes.ABSENT };
92
+ }
97
93
 
98
- if (!Object.hasOwn(parsed.hooks, GUARD_HOOK_NAME)) {
99
- return { ok: true, outcome: RemoveOutcomes.ABSENT };
100
- }
94
+ const others = Object.fromEntries(
95
+ Object.entries(parsed.hooks).filter(([name]) => name !== GUARD_HOOK_NAME),
96
+ );
101
97
 
102
- const others = Object.fromEntries(
103
- Object.entries(parsed.hooks).filter(([name]) => name !== GUARD_HOOK_NAME),
104
- );
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
+ }
105
105
 
106
- return {
107
- ok: true,
108
- outcome: RemoveOutcomes.REMOVED,
109
- text: Object.keys(others).length === 0 ? undefined : `${JSON.stringify(others, null, 2)}\n`,
110
- };
111
- };
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
+ }
@@ -1,41 +1,13 @@
1
- import { askWithPrompt } from '../create/names.ts';
2
- import { menusAvailable, promptMultiselect } from '../ui/index.ts';
1
+ import { ProjectNames } from '../create/names.ts';
2
+ import { TerminalCapability, TerminalPrompt } from '../ui/index.ts';
3
3
  import type { IAgentQuestion, TAgentResolution } from './common/index.ts';
4
4
  import { AgentConstants } from './common/index.ts';
5
- import { resolveAgents } from './resolve.ts';
6
- import { agentIds, readAgentTable } from './table.ts';
5
+ import { AgentSelection } from './resolve.ts';
6
+ import { AgentTable } from './table.ts';
7
7
 
8
8
  const listOf = (opts: { agents: string[] }): string =>
9
9
  opts.agents.length === 0 ? AgentConstants.NONE : opts.agents.join(', ');
10
10
 
11
- /**
12
- * The question as the terminal shows it. It says exactly what an empty answer does: it keeps the
13
- * choice stored on this machine when there is one, else it takes what was detected.
14
- */
15
- export const renderAgentsQuestion = (question: IAgentQuestion): string => {
16
- const enter =
17
- question.stored === undefined
18
- ? `Enter accepts the detected list: ${listOf({ agents: question.detected })}`
19
- : `Enter keeps your earlier choice: ${listOf({ agents: question.stored })}`;
20
-
21
- return [
22
- `Which coding agents do you use in this project? (comma-separated; ${enter})`,
23
- ` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
24
- ...(question.stored === undefined
25
- ? []
26
- : [` chosen before: ${listOf({ agents: question.stored })}`]),
27
- ` available: ${[...agentIds(), AgentConstants.NONE].join(', ')}`,
28
- ].join('\n');
29
- };
30
-
31
- export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
32
- process.stdout.write(`${renderAgentsQuestion(question)}\n`);
33
-
34
- return askWithPrompt({ question: 'Agents' });
35
- };
36
-
37
- export type TResolveAgentsInput = Omit<Parameters<typeof resolveAgents>[0], 'ask'>;
38
-
39
11
  const hintOf = (opts: { id: string; question: IAgentQuestion }): string | undefined => {
40
12
  const notes = [
41
13
  ...(opts.question.detected.includes(opts.id) ? ['detected'] : []),
@@ -48,11 +20,11 @@ const hintOf = (opts: { id: string; question: IAgentQuestion }): string | undefi
48
20
  /**
49
21
  * The checkbox menu: what this machine chose before is ticked, else what was detected. The first
50
22
  * pass of the resolution only learns whether it has to ask; the answer then goes back in as a list,
51
- * so the order in which sources are tried stays in `resolveAgents`.
23
+ * so the order in which sources are tried stays in `AgentSelection.resolve`.
52
24
  */
53
25
  const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentResolution> => {
54
26
  const questions: IAgentQuestion[] = [];
55
- const first = resolveAgents({
27
+ const first = AgentSelection.resolve({
56
28
  ...opts,
57
29
  ask: (question) => {
58
30
  questions.push(question);
@@ -66,9 +38,9 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
66
38
  return first;
67
39
  }
68
40
 
69
- const picked = await promptMultiselect({
41
+ const picked = await TerminalPrompt.promptMultiselect({
70
42
  message: 'Which coding agents do you use in this project?',
71
- choices: readAgentTable().map((entry) => ({
43
+ choices: AgentTable.read().map((entry) => ({
72
44
  value: entry.id,
73
45
  label: entry.name,
74
46
  hint: hintOf({ id: entry.id, question }),
@@ -76,7 +48,7 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
76
48
  initial: question.stored ?? question.detected,
77
49
  });
78
50
 
79
- return resolveAgents({
51
+ return AgentSelection.resolve({
80
52
  ...opts,
81
53
  ask: () => {
82
54
  if (picked === null) {
@@ -88,8 +60,39 @@ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentR
88
60
  });
89
61
  };
90
62
 
91
- /** Menus in a terminal that can draw them, the plain question everywhere else. */
92
- export const resolveAgentsInTerminal = (opts: TResolveAgentsInput): Promise<TAgentResolution> =>
93
- menusAvailable()
94
- ? resolveAgentsWithMenu(opts)
95
- : Promise.resolve(resolveAgents({ ...opts, ask: askAgentsInTerminal }));
63
+ export class AgentsPrompt {
64
+ private static askAgentsInTerminal(question: IAgentQuestion): string | null {
65
+ process.stdout.write(`${AgentsPrompt.renderQuestion(question)}\n`);
66
+
67
+ return ProjectNames.askWithPrompt({ question: 'Agents' });
68
+ }
69
+
70
+ /**
71
+ * The question as the terminal shows it. It says exactly what an empty answer does: it keeps the
72
+ * choice stored on this machine when there is one, else it takes what was detected.
73
+ */
74
+ static renderQuestion(question: IAgentQuestion): string {
75
+ const enter =
76
+ question.stored === undefined
77
+ ? `Enter accepts the detected list: ${listOf({ agents: question.detected })}`
78
+ : `Enter keeps your earlier choice: ${listOf({ agents: question.stored })}`;
79
+
80
+ return [
81
+ `Which coding agents do you use in this project? (comma-separated; ${enter})`,
82
+ ` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
83
+ ...(question.stored === undefined
84
+ ? []
85
+ : [` chosen before: ${listOf({ agents: question.stored })}`]),
86
+ ` available: ${[...AgentTable.agentIds(), AgentConstants.NONE].join(', ')}`,
87
+ ].join('\n');
88
+ }
89
+
90
+ /** Menus in a terminal that can draw them, the plain question everywhere else. */
91
+ static resolveInTerminal(opts: TResolveAgentsInput): Promise<TAgentResolution> {
92
+ return TerminalCapability.menusAvailable()
93
+ ? resolveAgentsWithMenu(opts)
94
+ : Promise.resolve(AgentSelection.resolve({ ...opts, ask: AgentsPrompt.askAgentsInTerminal }));
95
+ }
96
+ }
97
+
98
+ type TResolveAgentsInput = Omit<Parameters<typeof AgentSelection.resolve>[0], 'ask'>;