@venizia/vulcan 0.3.4 → 0.3.6
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.
- package/README.md +2 -2
- package/base/agents.json +232 -0
- package/base/claude/settings.json +12 -0
- package/base/hooks/guard-package.ts +29 -0
- package/base/rules.md +2 -0
- package/base/templates/AGENTS.md +4 -3
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +54 -0
- package/src/agents/common/constants.ts +38 -0
- package/src/agents/common/index.ts +3 -0
- package/src/agents/common/schema.ts +42 -0
- package/src/agents/common/types.ts +30 -0
- package/src/agents/detect.ts +36 -0
- package/src/agents/exclude.ts +87 -0
- package/src/agents/index.ts +9 -0
- package/src/agents/local.ts +65 -0
- package/src/agents/prompt.ts +22 -0
- package/src/agents/render.ts +229 -0
- package/src/agents/resolve.ts +145 -0
- package/src/agents/table.ts +35 -0
- package/src/commands/agents.command.ts +154 -0
- package/src/commands/doctor.command.ts +5 -1
- package/src/commands/help.command.ts +5 -1
- package/src/commands/index.ts +2 -0
- package/src/commands/sync.command.ts +112 -3
- package/src/common/constants.ts +9 -1
- package/src/config/common/constants.ts +12 -1
- package/src/config/packages.ts +2 -0
- package/src/config/schema.ts +16 -1
- package/src/create/add-app.ts +110 -4
- package/src/create/add-lib.ts +317 -0
- package/src/create/common/constants.ts +3 -0
- package/src/create/common/types.ts +18 -2
- package/src/create/dockerignore.ts +36 -0
- package/src/create/init-monorepo.ts +22 -4
- package/src/create/lib-preset.ts +154 -0
- package/src/create/preset.ts +22 -3
- package/src/create/workspace.ts +94 -3
- package/src/doctor/checks.ts +183 -12
- package/src/doctor/common/constants.ts +26 -0
- package/src/doctor/runner.ts +22 -0
- package/src/hooks/guard-package.ts +211 -0
- package/src/hooks/index.ts +1 -0
- package/src/hooks/session-digest.ts +27 -1
- package/src/init/scaffold.ts +8 -5
- package/src/manifest/render.ts +4 -0
- package/src/router.ts +10 -1
- package/src/sync/agent-files.ts +112 -0
- package/src/sync/agent-removal.ts +241 -0
- package/src/sync/atlas-block.ts +55 -0
- package/src/sync/common/constants.ts +2 -0
- package/src/sync/exclude.ts +89 -0
- package/src/sync/index.ts +5 -0
- package/src/sync/local-choice.ts +55 -0
- package/src/sync/planner.ts +55 -19
- package/src/sync/settings.ts +26 -0
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { AgentConstants } from './common/index.ts';
|
|
5
|
+
import type { TLocalChoice } from './common/index.ts';
|
|
6
|
+
import { agentIds } from './table.ts';
|
|
7
|
+
|
|
8
|
+
export const LOCAL_AGENTS_FILE = AgentConstants.LOCAL_FILE;
|
|
9
|
+
|
|
10
|
+
const LOCAL_SCHEMA = z.object({
|
|
11
|
+
schemaVersion: z.literal(AgentConstants.LOCAL_SCHEMA_VERSION),
|
|
12
|
+
agents: z.array(z.string()),
|
|
13
|
+
});
|
|
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`;
|
|
25
|
+
|
|
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);
|
|
29
|
+
|
|
30
|
+
if (!existsSync(file)) {
|
|
31
|
+
return { ok: true, agents: undefined };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
let parsed: unknown;
|
|
35
|
+
|
|
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
|
+
}
|
|
44
|
+
|
|
45
|
+
const checked = LOCAL_SCHEMA.safeParse(parsed);
|
|
46
|
+
|
|
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
|
+
}
|
|
53
|
+
|
|
54
|
+
const known = new Set(agentIds());
|
|
55
|
+
const unknown = checked.data.agents.find(id => !known.has(id));
|
|
56
|
+
|
|
57
|
+
if (unknown !== undefined) {
|
|
58
|
+
return {
|
|
59
|
+
ok: false,
|
|
60
|
+
error: `${LOCAL_AGENTS_FILE} names unknown agent '${unknown}' - one of: ${[...known].join(', ')}`,
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
return { ok: true, agents: checked.data.agents };
|
|
65
|
+
};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { askWithPrompt } from '../create/names.ts';
|
|
2
|
+
import type { IAgentQuestion } from './common/index.ts';
|
|
3
|
+
import { AgentConstants } from './common/index.ts';
|
|
4
|
+
import { agentIds } from './table.ts';
|
|
5
|
+
|
|
6
|
+
/** The terminal question: what was detected, what exists, and the developer's earlier choice as the shown default. */
|
|
7
|
+
export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
|
|
8
|
+
const lines = [
|
|
9
|
+
'Which coding agents do you use in this project? (comma-separated, Enter accepts)',
|
|
10
|
+
` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
|
|
11
|
+
...(question.stored === undefined
|
|
12
|
+
? []
|
|
13
|
+
: [
|
|
14
|
+
` chosen before: ${question.stored.length === 0 ? AgentConstants.NONE : question.stored.join(', ')}`,
|
|
15
|
+
]),
|
|
16
|
+
` available: ${[...agentIds(), AgentConstants.NONE].join(', ')}`,
|
|
17
|
+
];
|
|
18
|
+
|
|
19
|
+
process.stdout.write(`${lines.join('\n')}\n`);
|
|
20
|
+
|
|
21
|
+
return askWithPrompt({ question: 'Agents' });
|
|
22
|
+
};
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
import { join } from 'node:path';
|
|
2
|
+
|
|
3
|
+
export const CODEX_BLOCK_START = '# vulcan:atlas:start';
|
|
4
|
+
export const CODEX_BLOCK_END = '# vulcan:atlas:end';
|
|
5
|
+
const CODEX_TABLE = '[mcp_servers.atlas]';
|
|
6
|
+
const SERVER_NAME = 'atlas';
|
|
7
|
+
|
|
8
|
+
export type TMergeResult =
|
|
9
|
+
| { ok: true; changed: boolean; text: string }
|
|
10
|
+
| { ok: false; reason: string };
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The atlas server as a per-machine file starts it: the project's own `vulcan` by absolute path with
|
|
14
|
+
* an absolute `--root`, so it does not matter which directory the agent launches the server from.
|
|
15
|
+
*/
|
|
16
|
+
export const atlasServerEntry = (opts: { root: string }): { command: string; args: string[] } => ({
|
|
17
|
+
command: 'bun',
|
|
18
|
+
args: [
|
|
19
|
+
join(opts.root, 'node_modules', '.bin', 'vulcan'),
|
|
20
|
+
'x',
|
|
21
|
+
'atlas',
|
|
22
|
+
'mcp',
|
|
23
|
+
'--root',
|
|
24
|
+
opts.root,
|
|
25
|
+
],
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
29
|
+
typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Whether an `atlas` entry is the one sync writes, for whatever place: `bun <root>/node_modules/.bin/vulcan
|
|
33
|
+
* x atlas mcp --root <root>` (plus `type: stdio` for VS Code) with the two paths agreeing. Anything else
|
|
34
|
+
* is the user's. A project that moved is recognised this way and rewritten.
|
|
35
|
+
*/
|
|
36
|
+
const isOwnEntry = (opts: { entry: unknown }): boolean => {
|
|
37
|
+
const { entry } = opts;
|
|
38
|
+
|
|
39
|
+
if (!isRecord(entry) || entry.command !== 'bun' || !Array.isArray(entry.args)) {
|
|
40
|
+
return false;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const keys = Object.keys(entry).filter(key => key !== 'type');
|
|
44
|
+
const [bin, ...rest] = entry.args;
|
|
45
|
+
const root = rest[4];
|
|
46
|
+
|
|
47
|
+
return (
|
|
48
|
+
keys.length === 2 &&
|
|
49
|
+
(entry.type === undefined || entry.type === 'stdio') &&
|
|
50
|
+
entry.args.length === 6 &&
|
|
51
|
+
rest.slice(0, 4).join(' ') === 'x atlas mcp --root' &&
|
|
52
|
+
typeof root === 'string' &&
|
|
53
|
+
bin === join(root, 'node_modules', '.bin', 'vulcan')
|
|
54
|
+
);
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Sets the `atlas` server in a JSON file's server map and nothing else: the user's keys, servers and
|
|
59
|
+
* order stay, an `atlas` entry sync wrote for another place is rewritten for this one, and any other
|
|
60
|
+
* `atlas` entry is the user's and is left as it is.
|
|
61
|
+
*/
|
|
62
|
+
export const mergeMcpServers = (opts: {
|
|
63
|
+
text: string | undefined;
|
|
64
|
+
key: string;
|
|
65
|
+
entry: Record<string, unknown>;
|
|
66
|
+
}): TMergeResult => {
|
|
67
|
+
let document: Record<string, unknown> = {};
|
|
68
|
+
|
|
69
|
+
if (opts.text !== undefined) {
|
|
70
|
+
let parsed: unknown;
|
|
71
|
+
|
|
72
|
+
try {
|
|
73
|
+
parsed = JSON.parse(opts.text);
|
|
74
|
+
} catch {
|
|
75
|
+
return { ok: false, reason: 'not valid JSON' };
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
if (!isRecord(parsed)) {
|
|
79
|
+
return { ok: false, reason: 'not a JSON object' };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
document = parsed;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
const servers = document[opts.key] ?? {};
|
|
86
|
+
|
|
87
|
+
if (!isRecord(servers)) {
|
|
88
|
+
return { ok: false, reason: `${opts.key} is not an object` };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
const existing = servers[SERVER_NAME];
|
|
92
|
+
|
|
93
|
+
if (Object.hasOwn(servers, SERVER_NAME) && !isOwnEntry({ entry: existing })) {
|
|
94
|
+
return { ok: true, changed: false, text: opts.text ?? '' };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (
|
|
98
|
+
Object.hasOwn(servers, SERVER_NAME) &&
|
|
99
|
+
JSON.stringify(existing) === JSON.stringify(opts.entry)
|
|
100
|
+
) {
|
|
101
|
+
return { ok: true, changed: false, text: opts.text ?? '' };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
const text = `${JSON.stringify(
|
|
105
|
+
{ ...document, [opts.key]: { ...servers, [SERVER_NAME]: opts.entry } },
|
|
106
|
+
null,
|
|
107
|
+
2,
|
|
108
|
+
)}\n`;
|
|
109
|
+
|
|
110
|
+
return { ok: true, changed: true, text };
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
const codexBlock = (opts: { root: string }): string => {
|
|
114
|
+
const { command, args } = atlasServerEntry({ root: opts.root });
|
|
115
|
+
|
|
116
|
+
return [
|
|
117
|
+
CODEX_BLOCK_START,
|
|
118
|
+
CODEX_TABLE,
|
|
119
|
+
`command = ${JSON.stringify(command)}`,
|
|
120
|
+
`args = [${args.map(arg => JSON.stringify(arg)).join(', ')}]`,
|
|
121
|
+
CODEX_BLOCK_END,
|
|
122
|
+
'',
|
|
123
|
+
].join('\n');
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The atlas entry as a marker-delimited block of `.codex/config.toml`: no TOML writer is needed, and
|
|
128
|
+
* a later sync replaces only what sits between the markers.
|
|
129
|
+
*/
|
|
130
|
+
export const mergeCodexToml = (opts: { text: string | undefined; root: string }): TMergeResult => {
|
|
131
|
+
const block = codexBlock({ root: opts.root });
|
|
132
|
+
|
|
133
|
+
if (opts.text === undefined || opts.text === '') {
|
|
134
|
+
return { ok: true, changed: true, text: block };
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const start = opts.text.indexOf(CODEX_BLOCK_START);
|
|
138
|
+
const end = opts.text.indexOf(CODEX_BLOCK_END);
|
|
139
|
+
|
|
140
|
+
if (start !== -1 && end > start) {
|
|
141
|
+
const after = end + CODEX_BLOCK_END.length;
|
|
142
|
+
const rest = opts.text.slice(after).replace(/^\n/, '');
|
|
143
|
+
const text = `${opts.text.slice(0, start)}${block}${rest}`;
|
|
144
|
+
|
|
145
|
+
return { ok: true, changed: text !== opts.text, text };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
if (opts.text.includes(CODEX_TABLE)) {
|
|
149
|
+
return {
|
|
150
|
+
ok: false,
|
|
151
|
+
reason: 'a [mcp_servers.atlas] table is already there outside the vulcan markers',
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
return {
|
|
156
|
+
ok: true,
|
|
157
|
+
changed: true,
|
|
158
|
+
text: `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${block}`,
|
|
159
|
+
};
|
|
160
|
+
};
|
|
161
|
+
|
|
162
|
+
export type TRemoveResult =
|
|
163
|
+
| { ok: true; outcome: 'absent' }
|
|
164
|
+
| { ok: true; outcome: 'removed'; text: string | undefined }
|
|
165
|
+
| { ok: false; reason: string };
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Takes sync's own atlas entry out of a JSON server map. The file is deleted (`text` undefined) when
|
|
169
|
+
* nothing else is left in it; an entry of another shape is the user's and is reported, not removed.
|
|
170
|
+
*/
|
|
171
|
+
export const removeMcpEntry = (opts: { text: string; key: string }): TRemoveResult => {
|
|
172
|
+
let document: unknown;
|
|
173
|
+
|
|
174
|
+
try {
|
|
175
|
+
document = JSON.parse(opts.text);
|
|
176
|
+
} catch {
|
|
177
|
+
return { ok: false, reason: 'not valid JSON - left untouched' };
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
if (!isRecord(document)) {
|
|
181
|
+
return { ok: false, reason: 'not a JSON object - left untouched' };
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
const servers = document[opts.key];
|
|
185
|
+
|
|
186
|
+
if (!isRecord(servers) || !Object.hasOwn(servers, SERVER_NAME)) {
|
|
187
|
+
return { ok: true, outcome: 'absent' };
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
if (!isOwnEntry({ entry: servers[SERVER_NAME] })) {
|
|
191
|
+
return { ok: false, reason: 'the atlas entry is not the one sync wrote - left alone' };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
const otherServers = Object.fromEntries(
|
|
195
|
+
Object.entries(servers).filter(([name]) => name !== SERVER_NAME),
|
|
196
|
+
);
|
|
197
|
+
const otherKeys = Object.fromEntries(
|
|
198
|
+
Object.entries(document).filter(([key]) => key !== opts.key),
|
|
199
|
+
);
|
|
200
|
+
const remaining =
|
|
201
|
+
Object.keys(otherServers).length === 0 ? otherKeys : { ...document, [opts.key]: otherServers };
|
|
202
|
+
const onlyEmptyInputs = Object.entries(remaining).every(
|
|
203
|
+
([key, value]) => key === 'inputs' && Array.isArray(value) && value.length === 0,
|
|
204
|
+
);
|
|
205
|
+
|
|
206
|
+
return {
|
|
207
|
+
ok: true,
|
|
208
|
+
outcome: 'removed',
|
|
209
|
+
text: onlyEmptyInputs ? undefined : `${JSON.stringify(remaining, null, 2)}\n`,
|
|
210
|
+
};
|
|
211
|
+
};
|
|
212
|
+
|
|
213
|
+
/** Takes the marker block out of `.codex/config.toml`; `text` is undefined when nothing else is left. */
|
|
214
|
+
export const removeCodexBlock = (opts: {
|
|
215
|
+
text: string;
|
|
216
|
+
}): { changed: boolean; text: string | undefined } => {
|
|
217
|
+
const start = opts.text.indexOf(CODEX_BLOCK_START);
|
|
218
|
+
const end = opts.text.indexOf(CODEX_BLOCK_END);
|
|
219
|
+
|
|
220
|
+
if (start === -1 || end < start) {
|
|
221
|
+
return { changed: false, text: opts.text };
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const before = opts.text.slice(0, start).replace(/\n+$/, '\n');
|
|
225
|
+
const after = opts.text.slice(end + CODEX_BLOCK_END.length).replace(/^\n+/, '');
|
|
226
|
+
const text = `${before}${before !== '' && after !== '' ? '\n' : ''}${after}`;
|
|
227
|
+
|
|
228
|
+
return { changed: true, text: text.trim() === '' ? undefined : text };
|
|
229
|
+
};
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { AgentConstants } from './common/index.ts';
|
|
4
|
+
import type { TAgentResolution, TAskAgents } from './common/index.ts';
|
|
5
|
+
import { readLocalChoice } from './local.ts';
|
|
6
|
+
import { agentIds } from './table.ts';
|
|
7
|
+
|
|
8
|
+
const PROJECT_FILES = ['CLAUDE.md', '.claude'];
|
|
9
|
+
|
|
10
|
+
export const NO_TTY_HINT = `vulcan sync: no agents chosen on this machine - wrote the Claude files as before; to choose, run: vulcan sync ${AgentConstants.FLAG} ${AgentConstants.EXAMPLE_LIST} (or ${AgentConstants.NONE})`;
|
|
11
|
+
|
|
12
|
+
type TParsed = { ok: true; agents: string[] } | { ok: false; error: string };
|
|
13
|
+
|
|
14
|
+
/** A comma list or `none`: validated against the table, deduplicated, in table order. */
|
|
15
|
+
export const parseAgentList = (opts: { value: string }): TParsed => {
|
|
16
|
+
const known = agentIds();
|
|
17
|
+
const words = opts.value
|
|
18
|
+
.split(',')
|
|
19
|
+
.map(word => word.trim())
|
|
20
|
+
.filter(word => word !== '');
|
|
21
|
+
|
|
22
|
+
if (words.includes(AgentConstants.NONE)) {
|
|
23
|
+
return words.length === 1
|
|
24
|
+
? { ok: true, agents: [] }
|
|
25
|
+
: {
|
|
26
|
+
ok: false,
|
|
27
|
+
error: `vulcan sync: '${AgentConstants.NONE}' cannot be combined with other agents`,
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const unknown = words.find(word => !known.includes(word));
|
|
32
|
+
|
|
33
|
+
if (unknown !== undefined) {
|
|
34
|
+
return {
|
|
35
|
+
ok: false,
|
|
36
|
+
error: `vulcan sync: unknown agent '${unknown}' - one of: ${[...known, AgentConstants.NONE].join(', ')}`,
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
return { ok: true, agents: known.filter(id => words.includes(id)) };
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
const fromList = (opts: { value: string; source: 'flag' | 'asked' }): TAgentResolution => {
|
|
44
|
+
const parsed = parseAgentList({ value: opts.value });
|
|
45
|
+
|
|
46
|
+
return parsed.ok
|
|
47
|
+
? { ok: true, agents: parsed.agents, source: opts.source, writeLocal: true, hint: undefined }
|
|
48
|
+
: parsed;
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Which agents this machine uses, in order: the flag, the stored choice, the committed config's
|
|
53
|
+
* suggestion, a project that already has Claude files, then ask (terminal) or keep today's Claude
|
|
54
|
+
* default (no terminal, with a hint and nothing stored).
|
|
55
|
+
*/
|
|
56
|
+
export const resolveAgents = (opts: {
|
|
57
|
+
root: string;
|
|
58
|
+
/** `--agents`: undefined when absent, '' when given without a value. */
|
|
59
|
+
flag: string | undefined;
|
|
60
|
+
configAgents: string[] | undefined;
|
|
61
|
+
interactive: boolean;
|
|
62
|
+
detected: string[];
|
|
63
|
+
ask: TAskAgents;
|
|
64
|
+
}): TAgentResolution => {
|
|
65
|
+
const stored = readLocalChoice({ root: opts.root });
|
|
66
|
+
|
|
67
|
+
if (!stored.ok) {
|
|
68
|
+
return { ok: false, error: `vulcan sync: ${stored.error}` };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const askNow = (): TAgentResolution => {
|
|
72
|
+
const answer = opts.ask({ detected: opts.detected, stored: stored.agents });
|
|
73
|
+
|
|
74
|
+
if (answer === null) {
|
|
75
|
+
return {
|
|
76
|
+
ok: false,
|
|
77
|
+
error: `vulcan sync: no answer - run: vulcan sync ${AgentConstants.FLAG} ${AgentConstants.EXAMPLE_LIST} (or ${AgentConstants.NONE})`,
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
return answer.trim() === ''
|
|
82
|
+
? { ok: true, agents: opts.detected, source: 'asked', writeLocal: true, hint: undefined }
|
|
83
|
+
: fromList({ value: answer, source: 'asked' });
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
if (opts.flag === '') {
|
|
87
|
+
return opts.interactive
|
|
88
|
+
? askNow()
|
|
89
|
+
: {
|
|
90
|
+
ok: false,
|
|
91
|
+
error: `vulcan sync: ${AgentConstants.FLAG} needs a list (${AgentConstants.EXAMPLE_LIST}) or ${AgentConstants.NONE}`,
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
if (opts.flag !== undefined) {
|
|
96
|
+
return fromList({ value: opts.flag, source: 'flag' });
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
if (stored.agents !== undefined) {
|
|
100
|
+
return { ok: true, agents: stored.agents, source: 'local', writeLocal: false, hint: undefined };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
if (opts.configAgents !== undefined) {
|
|
104
|
+
return {
|
|
105
|
+
ok: true,
|
|
106
|
+
agents: agentIds().filter(id => opts.configAgents?.includes(id)),
|
|
107
|
+
source: 'config',
|
|
108
|
+
writeLocal: true,
|
|
109
|
+
hint: undefined,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
if (PROJECT_FILES.some(file => existsSync(join(opts.root, file)))) {
|
|
114
|
+
return { ok: true, agents: ['claude'], source: 'migration', writeLocal: true, hint: undefined };
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
if (opts.interactive) {
|
|
118
|
+
return askNow();
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
return {
|
|
122
|
+
ok: true,
|
|
123
|
+
agents: [AgentConstants.DEFAULT_AGENT],
|
|
124
|
+
source: 'default',
|
|
125
|
+
writeLocal: false,
|
|
126
|
+
hint: NO_TTY_HINT,
|
|
127
|
+
};
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
/** The same order without a terminal or a flag: what doctor and every non-interactive reader use. */
|
|
131
|
+
export const resolveAgentsQuietly = (opts: {
|
|
132
|
+
root: string;
|
|
133
|
+
configAgents: string[] | undefined;
|
|
134
|
+
}): string[] => {
|
|
135
|
+
const resolved = resolveAgents({
|
|
136
|
+
root: opts.root,
|
|
137
|
+
flag: undefined,
|
|
138
|
+
configAgents: opts.configAgents,
|
|
139
|
+
interactive: false,
|
|
140
|
+
detected: [],
|
|
141
|
+
ask: () => null,
|
|
142
|
+
});
|
|
143
|
+
|
|
144
|
+
return resolved.ok ? resolved.agents : [AgentConstants.DEFAULT_AGENT];
|
|
145
|
+
};
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { BASE_DIRECTORY } from '../common/index.ts';
|
|
5
|
+
import { AGENT_ENTRY_SCHEMA } from './common/index.ts';
|
|
6
|
+
import type { TAgentEntry } from './common/index.ts';
|
|
7
|
+
|
|
8
|
+
const TABLE_SCHEMA = z.array(AGENT_ENTRY_SCHEMA).superRefine((entries, context) => {
|
|
9
|
+
const seen = new Set<string>();
|
|
10
|
+
|
|
11
|
+
for (const [index, entry] of entries.entries()) {
|
|
12
|
+
if (seen.has(entry.id)) {
|
|
13
|
+
context.addIssue({
|
|
14
|
+
code: 'custom',
|
|
15
|
+
path: [index, 'id'],
|
|
16
|
+
message: `'${entry.id}' is used twice`,
|
|
17
|
+
});
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
seen.add(entry.id);
|
|
21
|
+
}
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
let cached: TAgentEntry[] | undefined;
|
|
25
|
+
|
|
26
|
+
/** The shipped table, in the order the questions and the list show it; a broken table throws. */
|
|
27
|
+
export const readAgentTable = (): TAgentEntry[] => {
|
|
28
|
+
cached ??= TABLE_SCHEMA.parse(
|
|
29
|
+
JSON.parse(readFileSync(join(BASE_DIRECTORY, 'agents.json'), 'utf8')),
|
|
30
|
+
);
|
|
31
|
+
|
|
32
|
+
return cached;
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
export const agentIds = (): string[] => readAgentTable().map(entry => entry.id);
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
import { homedir } from 'node:os';
|
|
2
|
+
import {
|
|
3
|
+
AgentConstants,
|
|
4
|
+
agentIds,
|
|
5
|
+
detectAgents,
|
|
6
|
+
parseAgentList,
|
|
7
|
+
resolveAgents,
|
|
8
|
+
} from '../agents/index.ts';
|
|
9
|
+
import { ExitCodes } from '../common/index.ts';
|
|
10
|
+
import type { ICommandContext } from '../common/index.ts';
|
|
11
|
+
import { loadConfig } from '../config/index.ts';
|
|
12
|
+
import { printAgentTable, runSyncFlow } from './sync.command.ts';
|
|
13
|
+
|
|
14
|
+
const SUBCOMMANDS = ['list', 'add', 'remove', 'setup'];
|
|
15
|
+
const DRY_RUN_FLAG = '--dry-run';
|
|
16
|
+
|
|
17
|
+
const fail = (opts: { message: string }): number => {
|
|
18
|
+
process.stderr.write(`vulcan agents: ${opts.message}\n`);
|
|
19
|
+
|
|
20
|
+
return ExitCodes.FAILURE;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
const detected = (opts: { root: string }): string[] =>
|
|
24
|
+
detectAgents({
|
|
25
|
+
root: opts.root,
|
|
26
|
+
home: process.env.HOME ?? homedir(),
|
|
27
|
+
path: process.env.PATH ?? '',
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
/** What this machine uses now: the stored choice, the migration or the config's suggestion; nothing when it never chose. */
|
|
31
|
+
const currentAgents = async (opts: {
|
|
32
|
+
root: string;
|
|
33
|
+
}): Promise<{ ok: true; agents: string[]; chosen: boolean } | { ok: false; error: string }> => {
|
|
34
|
+
const loaded = await loadConfig({ root: opts.root });
|
|
35
|
+
|
|
36
|
+
if (!loaded.ok) {
|
|
37
|
+
return { ok: false, error: loaded.error };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const resolved = resolveAgents({
|
|
41
|
+
root: opts.root,
|
|
42
|
+
flag: undefined,
|
|
43
|
+
configAgents: loaded.config.agents,
|
|
44
|
+
interactive: false,
|
|
45
|
+
detected: [],
|
|
46
|
+
ask: () => null,
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
if (!resolved.ok) {
|
|
50
|
+
return { ok: false, error: resolved.error };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
return resolved.source === 'default'
|
|
54
|
+
? { ok: true, agents: [], chosen: false }
|
|
55
|
+
: { ok: true, agents: resolved.agents, chosen: true };
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
const runList = async (opts: { root: string }): Promise<number> => {
|
|
59
|
+
const current = await currentAgents(opts);
|
|
60
|
+
|
|
61
|
+
if (!current.ok) {
|
|
62
|
+
return fail({ message: current.error });
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const found = detected(opts);
|
|
66
|
+
|
|
67
|
+
process.stdout.write(
|
|
68
|
+
`chosen on this machine: ${current.chosen ? current.agents.join(', ') || AgentConstants.NONE : '(nothing yet)'}\n`,
|
|
69
|
+
);
|
|
70
|
+
process.stdout.write(`detected: ${found.length === 0 ? '(none)' : found.join(', ')}\n\n`);
|
|
71
|
+
printAgentTable();
|
|
72
|
+
|
|
73
|
+
return ExitCodes.OK;
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
export const runAgentsCommand = async (opts: ICommandContext): Promise<number> => {
|
|
77
|
+
const words = opts.args.filter(arg => !arg.startsWith('--'));
|
|
78
|
+
const dryRun = opts.args.includes(DRY_RUN_FLAG) ? [DRY_RUN_FLAG] : [];
|
|
79
|
+
const [subcommand = 'list', value] = words;
|
|
80
|
+
|
|
81
|
+
if (!SUBCOMMANDS.includes(subcommand)) {
|
|
82
|
+
return fail({
|
|
83
|
+
message: `unknown subcommand '${subcommand}' - one of: ${SUBCOMMANDS.join(', ')}`,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
if (subcommand === 'list') {
|
|
88
|
+
return runList({ root: opts.cwd });
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
if (subcommand === 'setup') {
|
|
92
|
+
if (process.stdin.isTTY !== true) {
|
|
93
|
+
return fail({
|
|
94
|
+
message: `setup asks questions and needs a terminal - without one use 'vulcan agents add|remove <ids>' or 'vulcan sync ${AgentConstants.FLAG} <list>'`,
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
return runSyncFlow({ cwd: opts.cwd, args: [AgentConstants.FLAG, ...dryRun] });
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
if (value === undefined) {
|
|
102
|
+
return fail({
|
|
103
|
+
message: `${subcommand} needs the agents to ${subcommand} (${AgentConstants.EXAMPLE_LIST})`,
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const parsed = parseAgentList({ value });
|
|
108
|
+
|
|
109
|
+
if (!parsed.ok) {
|
|
110
|
+
return fail({ message: parsed.error.replace(/^vulcan sync: /, '') });
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
if (parsed.agents.length === 0) {
|
|
114
|
+
return fail({ message: `${subcommand} needs agents, not '${AgentConstants.NONE}'` });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const current = await currentAgents({ root: opts.cwd });
|
|
118
|
+
|
|
119
|
+
if (!current.ok) {
|
|
120
|
+
return fail({ message: current.error });
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const known = agentIds();
|
|
124
|
+
const already = parsed.agents.filter(id => current.agents.includes(id));
|
|
125
|
+
const absent = parsed.agents.filter(id => !current.agents.includes(id));
|
|
126
|
+
const touched = subcommand === 'add' ? absent : already;
|
|
127
|
+
const skipped = subcommand === 'add' ? already : absent;
|
|
128
|
+
|
|
129
|
+
if (skipped.length > 0) {
|
|
130
|
+
process.stderr.write(
|
|
131
|
+
`vulcan agents: ${subcommand === 'add' ? 'already chosen' : 'not chosen'}: ${skipped.join(', ')}\n`,
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
if (touched.length === 0) {
|
|
136
|
+
return ExitCodes.OK;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
const next = known.filter(id =>
|
|
140
|
+
subcommand === 'add'
|
|
141
|
+
? [...current.agents, ...touched].includes(id)
|
|
142
|
+
: current.agents.includes(id) && !touched.includes(id),
|
|
143
|
+
);
|
|
144
|
+
|
|
145
|
+
return runSyncFlow({
|
|
146
|
+
cwd: opts.cwd,
|
|
147
|
+
args: [
|
|
148
|
+
AgentConstants.FLAG,
|
|
149
|
+
next.length === 0 ? AgentConstants.NONE : next.join(','),
|
|
150
|
+
...dryRun,
|
|
151
|
+
],
|
|
152
|
+
cleanup: subcommand === 'remove' ? touched : [],
|
|
153
|
+
});
|
|
154
|
+
};
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { ExitCodes } from '../common/index.ts';
|
|
2
2
|
import type { ICommandContext } from '../common/index.ts';
|
|
3
|
-
import { runDoctorChecks } from '../doctor/index.ts';
|
|
3
|
+
import { runDoctorChecks, runDoctorNotes } from '../doctor/index.ts';
|
|
4
4
|
|
|
5
5
|
export const runDoctorCommand = async (opts: ICommandContext): Promise<number> => {
|
|
6
6
|
const violations = await runDoctorChecks({ root: opts.cwd });
|
|
@@ -9,6 +9,10 @@ export const runDoctorCommand = async (opts: ICommandContext): Promise<number> =
|
|
|
9
9
|
process.stderr.write(` [${violation.check}] ${violation.file}: ${violation.message}\n`);
|
|
10
10
|
}
|
|
11
11
|
|
|
12
|
+
for (const note of await runDoctorNotes({ root: opts.cwd })) {
|
|
13
|
+
process.stderr.write(` info [${note.check}] ${note.file}: ${note.message}\n`);
|
|
14
|
+
}
|
|
15
|
+
|
|
12
16
|
if (violations.length > 0) {
|
|
13
17
|
process.stderr.write(`vulcan doctor: ${violations.length} violation(s)\n`);
|
|
14
18
|
|
|
@@ -10,8 +10,12 @@ Usage: bun x vulcan <command>
|
|
|
10
10
|
(a name missing from the flags is asked in a terminal)
|
|
11
11
|
add --preset <name|file:path> --app <name> [--backend-dir|--frontend-dir <name>]
|
|
12
12
|
[--api <app> | --no-api] Add an app to the monorepo (a frontend says which backend to proxy to)
|
|
13
|
-
sync [--dry-run] [--prune]
|
|
13
|
+
sync [--agents <list>|list] [--dry-run] [--prune]
|
|
14
|
+
Write the adapters of the agents you chose (--agents claude,omp or none,
|
|
15
|
+
stored in .agents/vulcan.local.json; --agents list shows the table);
|
|
14
16
|
--prune also removes stale hooks and dead skill links
|
|
17
|
+
agents [list|add <ids>|remove <ids>|setup] [--dry-run]
|
|
18
|
+
See, add, remove or re-choose the coding agents you use on this machine
|
|
15
19
|
doctor Check the project follows VULCAN; exit 1 on any violation
|
|
16
20
|
upgrade [--stable | --nightly] [<version|tag>]
|
|
17
21
|
Bump the pinned @venizia/vulcan, then sync; --stable (default)
|