@venizia/vulcan 0.3.7 → 0.3.9
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/skills/build-a-feature/SKILL.md +122 -0
- package/base/skills/build-a-feature/evals/evals.json +29 -0
- package/package.json +4 -3
- package/src/agents/atlas-block.ts +1 -0
- package/src/agents/exclude.ts +5 -0
- package/src/agents/prompt.ts +84 -11
- package/src/agents/render.ts +16 -2
- package/src/agents/resolve.ts +8 -1
- package/src/commands/help.command.ts +5 -2
- package/src/commands/sync.command.ts +2 -4
- package/src/config/schema.ts +2 -0
- package/src/create/add-app.ts +103 -14
- package/src/create/add-lib.ts +29 -6
- package/src/create/common/types.ts +15 -1
- package/src/create/init-monorepo.ts +35 -10
- package/src/create/names.ts +72 -7
- package/src/create/plan.ts +17 -0
- package/src/create/preset-menu.ts +45 -0
- package/src/create/workspace.ts +41 -1
- package/src/doctor/checks.ts +128 -2
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +5 -2
- package/src/init/scaffold.ts +2 -42
- package/src/sync/agent-files.ts +59 -5
- package/src/sync/agent-removal.ts +55 -0
- package/src/sync/atlas-block.ts +4 -5
- package/src/ui/capability.ts +7 -0
- package/src/ui/index.ts +2 -0
- package/src/ui/prompt.ts +85 -0
- package/base/templates/mcp.json +0 -8
package/src/init/scaffold.ts
CHANGED
|
@@ -7,33 +7,8 @@ import { InitConstants, InitStatuses } from './common/index.ts';
|
|
|
7
7
|
import { renderDockerignore } from '../create/dockerignore.ts';
|
|
8
8
|
import type { IInitEntry, IScaffoldFile } from './common/index.ts';
|
|
9
9
|
|
|
10
|
-
/**
|
|
11
|
-
|
|
12
|
-
* `atlas mcp` under another name, as separate arguments or inside a `sh -c` string. A file that is not JSON falls back to looking for the name.
|
|
13
|
-
*/
|
|
14
|
-
export const runsAtlas = (opts: { text: string }): boolean => {
|
|
15
|
-
try {
|
|
16
|
-
const parsed: { mcpServers?: Record<string, { args?: unknown }> } = JSON.parse(opts.text);
|
|
17
|
-
const servers = parsed.mcpServers ?? {};
|
|
18
|
-
|
|
19
|
-
return (
|
|
20
|
-
'atlas' in servers ||
|
|
21
|
-
Object.values(servers).some(server => {
|
|
22
|
-
const args = Array.isArray(server.args)
|
|
23
|
-
? server.args.flatMap(arg => String(arg).split(/\s+/))
|
|
24
|
-
: [];
|
|
25
|
-
const atlas = args.indexOf('atlas');
|
|
26
|
-
|
|
27
|
-
return atlas !== -1 && args[atlas + 1] === 'mcp';
|
|
28
|
-
})
|
|
29
|
-
);
|
|
30
|
-
} catch {
|
|
31
|
-
return opts.text.includes('"atlas"');
|
|
32
|
-
}
|
|
33
|
-
};
|
|
34
|
-
|
|
35
|
-
/** The entry for a `.mcp.json` that exists already: atlas serves the knowledge bundle alone, and the wiki when there is one. */
|
|
36
|
-
const MCP_SERVER_HINT =
|
|
10
|
+
/** The atlas entry of the root `.mcp.json`, as `sync` writes it and `doctor` shows it. */
|
|
11
|
+
export const MCP_SERVER_HINT =
|
|
37
12
|
'"atlas": { "command": "bun", "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."] }';
|
|
38
13
|
|
|
39
14
|
/** The files every project gets, apart from the config, whose format the user picks. */
|
|
@@ -41,7 +16,6 @@ const SCAFFOLD_FILES: IScaffoldFile[] = [
|
|
|
41
16
|
{ path: 'AGENTS.md', template: 'AGENTS.md' },
|
|
42
17
|
{ path: '.agents/rules.md', template: 'rules.md' },
|
|
43
18
|
{ path: '.agents/knowledge/index.md', template: 'knowledge-index.md' },
|
|
44
|
-
{ path: '.mcp.json', template: 'mcp.json' },
|
|
45
19
|
];
|
|
46
20
|
|
|
47
21
|
/** The lint configs of a single-package project. A workspaces project keeps them in each app. */
|
|
@@ -208,20 +182,6 @@ export const scaffoldProject = (opts: {
|
|
|
208
182
|
});
|
|
209
183
|
}
|
|
210
184
|
|
|
211
|
-
// A `.mcp.json` that was already there is the project's: it gets the atlas entry as a hint, never an edit.
|
|
212
|
-
if (
|
|
213
|
-
!entries.some(entry => entry.subject === '.mcp.json' && entry.status === InitStatuses.CREATED)
|
|
214
|
-
) {
|
|
215
|
-
const servers = readFileSync(join(root, '.mcp.json'), 'utf8');
|
|
216
|
-
|
|
217
|
-
if (!runsAtlas({ text: servers })) {
|
|
218
|
-
entries.push({
|
|
219
|
-
status: InitStatuses.ADD,
|
|
220
|
-
subject: `.mcp.json: the atlas server, for the knowledge bundle (and the wiki, when there is one; --root pins the project): ${MCP_SERVER_HINT}`,
|
|
221
|
-
});
|
|
222
|
-
}
|
|
223
|
-
}
|
|
224
|
-
|
|
225
185
|
const gitignore = join(root, '.gitignore');
|
|
226
186
|
const existing = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : '';
|
|
227
187
|
const lines = existing.split('\n');
|
package/src/sync/agent-files.ts
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { dirname, join } from 'node:path';
|
|
3
3
|
import {
|
|
4
|
+
AgentConstants,
|
|
4
5
|
AgentRenderers,
|
|
5
6
|
AgentScopes,
|
|
6
7
|
atlasServerEntry,
|
|
8
|
+
canonicalAtlasEntry,
|
|
7
9
|
mergeCodexToml,
|
|
8
10
|
mergeMcpServers,
|
|
9
11
|
readAgentTable,
|
|
@@ -15,7 +17,7 @@ import type { ISyncAction } from './common/index.ts';
|
|
|
15
17
|
const NO_CHANGE = (): void => {};
|
|
16
18
|
|
|
17
19
|
/** A file git tracks cannot be hidden by an exclude entry, and a per-developer edit would show as a diff. */
|
|
18
|
-
const isTracked = (opts: { root: string; path: string }): boolean => {
|
|
20
|
+
export const isTracked = (opts: { root: string; path: string }): boolean => {
|
|
19
21
|
try {
|
|
20
22
|
return (
|
|
21
23
|
Bun.spawnSync(['git', 'ls-files', '--error-unmatch', opts.path], {
|
|
@@ -99,11 +101,63 @@ const planAgentMcp = (opts: { root: string; entry: TAgentEntry }): ISyncAction[]
|
|
|
99
101
|
];
|
|
100
102
|
};
|
|
101
103
|
|
|
102
|
-
/**
|
|
103
|
-
|
|
104
|
-
|
|
104
|
+
/**
|
|
105
|
+
* The root `.mcp.json` the chosen agents of the shared scope read: the canonical atlas entry, merged
|
|
106
|
+
* into what is there. A file git tracks belongs to the project, not to this machine: it is never
|
|
107
|
+
* rewritten (the doctor says how to hand it over).
|
|
108
|
+
*/
|
|
109
|
+
const planSharedMcp = (opts: { root: string }): ISyncAction[] => {
|
|
110
|
+
const path = join(opts.root, AgentConstants.SHARED_MCP_FILE);
|
|
111
|
+
const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
|
|
112
|
+
const merged = mergeMcpServers({ text, key: 'mcpServers', entry: canonicalAtlasEntry() });
|
|
113
|
+
|
|
114
|
+
if (!merged.ok) {
|
|
115
|
+
return [
|
|
116
|
+
{
|
|
117
|
+
path,
|
|
118
|
+
status: SyncStatuses.SKIPPED,
|
|
119
|
+
note: `${merged.reason} - left untouched; fix it, then re-run sync`,
|
|
120
|
+
apply: NO_CHANGE,
|
|
121
|
+
},
|
|
122
|
+
];
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
if (
|
|
126
|
+
!merged.changed ||
|
|
127
|
+
(text !== undefined && isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE }))
|
|
128
|
+
) {
|
|
129
|
+
return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
return [
|
|
133
|
+
{
|
|
134
|
+
path,
|
|
135
|
+
status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
|
|
136
|
+
apply: () => writeFileSync(path, merged.text),
|
|
137
|
+
},
|
|
138
|
+
];
|
|
139
|
+
};
|
|
140
|
+
|
|
141
|
+
/** The MCP files of every chosen agent, in table order; the shared `.mcp.json` once, at its first reader. */
|
|
142
|
+
export const planAgentFiles = (opts: { root: string; agents: string[] }): ISyncAction[] => {
|
|
143
|
+
let sharedPlanned = false;
|
|
144
|
+
|
|
145
|
+
return readAgentTable()
|
|
105
146
|
.filter(entry => opts.agents.includes(entry.id))
|
|
106
|
-
.flatMap(entry =>
|
|
147
|
+
.flatMap(entry => {
|
|
148
|
+
if (entry.mcp.scope === AgentScopes.PROJECT) {
|
|
149
|
+
return planAgentMcp({ root: opts.root, entry });
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
if (sharedPlanned) {
|
|
153
|
+
return [];
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
sharedPlanned = true;
|
|
157
|
+
|
|
158
|
+
return planSharedMcp({ root: opts.root });
|
|
159
|
+
});
|
|
160
|
+
};
|
|
107
161
|
|
|
108
162
|
/** One line per note of a chosen agent (a trust prompt only the user can answer). */
|
|
109
163
|
export const agentNotes = (opts: { agents: string[] }): { agent: string; note: string }[] =>
|
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
removeMcpEntry,
|
|
19
19
|
} from '../agents/index.ts';
|
|
20
20
|
import type { TAgentEntry } from '../agents/index.ts';
|
|
21
|
+
import { isTracked } from './agent-files.ts';
|
|
21
22
|
import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
|
|
22
23
|
import { SyncConstants, SyncStatuses } from './common/index.ts';
|
|
23
24
|
import type { ISyncAction, TSettings } from './common/index.ts';
|
|
@@ -80,6 +81,51 @@ const removeFile = (opts: { path: string; note?: string; parent?: string }): ISy
|
|
|
80
81
|
},
|
|
81
82
|
});
|
|
82
83
|
|
|
84
|
+
/**
|
|
85
|
+
* The root `.mcp.json`, once no remaining agent reads it: sync's own atlas entry is taken out (the file
|
|
86
|
+
* goes when nothing else is in it). A file git tracks is the project's, and an entry the user changed
|
|
87
|
+
* is theirs: both are left, and the line says so.
|
|
88
|
+
*/
|
|
89
|
+
const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
|
|
90
|
+
const path = join(opts.root, AgentConstants.SHARED_MCP_FILE);
|
|
91
|
+
|
|
92
|
+
if (!existsSync(path)) {
|
|
93
|
+
return [];
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const removed = removeMcpEntry({ text: readFileSync(path, 'utf8'), key: 'mcpServers' });
|
|
97
|
+
|
|
98
|
+
if (!removed.ok) {
|
|
99
|
+
return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (removed.outcome === 'absent') {
|
|
103
|
+
return [];
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
if (isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE })) {
|
|
107
|
+
return [
|
|
108
|
+
{
|
|
109
|
+
path,
|
|
110
|
+
status: SyncStatuses.SKIPPED,
|
|
111
|
+
note: 'tracked by git - left alone',
|
|
112
|
+
apply: NO_CHANGE,
|
|
113
|
+
},
|
|
114
|
+
];
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
return removed.text === undefined
|
|
118
|
+
? [removeFile({ path })]
|
|
119
|
+
: [
|
|
120
|
+
{
|
|
121
|
+
path,
|
|
122
|
+
status: SyncStatuses.REPLACED,
|
|
123
|
+
note: 'the atlas entry taken out',
|
|
124
|
+
apply: () => writeFileSync(path, removed.text ?? ''),
|
|
125
|
+
},
|
|
126
|
+
];
|
|
127
|
+
};
|
|
128
|
+
|
|
83
129
|
const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
|
|
84
130
|
if (opts.entry.mcp.scope !== AgentScopes.PROJECT) {
|
|
85
131
|
return [];
|
|
@@ -219,6 +265,10 @@ export const planAgentRemoval = (opts: {
|
|
|
219
265
|
);
|
|
220
266
|
const cleaned = new Set<string>();
|
|
221
267
|
const actions: ISyncAction[] = [];
|
|
268
|
+
const stillReadsShared = table.some(
|
|
269
|
+
entry => opts.remaining.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
|
|
270
|
+
);
|
|
271
|
+
let sharedDone = false;
|
|
222
272
|
|
|
223
273
|
for (const entry of table.filter(item => opts.removed.includes(item.id))) {
|
|
224
274
|
if (entry.id === AgentConstants.DEFAULT_AGENT) {
|
|
@@ -227,6 +277,11 @@ export const planAgentRemoval = (opts: {
|
|
|
227
277
|
|
|
228
278
|
actions.push(...planMcpRemoval({ root: opts.root, entry }));
|
|
229
279
|
|
|
280
|
+
if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
|
|
281
|
+
sharedDone = true;
|
|
282
|
+
actions.push(...planSharedMcpRemoval({ root: opts.root }));
|
|
283
|
+
}
|
|
284
|
+
|
|
230
285
|
if (
|
|
231
286
|
entry.skills.dir !== CLAUDE_SKILLS &&
|
|
232
287
|
!kept.has(entry.skills.dir) &&
|
package/src/sync/atlas-block.ts
CHANGED
|
@@ -2,7 +2,6 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { mergeAtlasBlock, renderAtlasBlock } from '../agents/index.ts';
|
|
4
4
|
import type { TResolvedConfig } from '../config/index.ts';
|
|
5
|
-
import { runsAtlas } from '../init/scaffold.ts';
|
|
6
5
|
import { projectNameOf } from '../manifest/index.ts';
|
|
7
6
|
import { SyncStatuses } from './common/index.ts';
|
|
8
7
|
import type { ISyncAction } from './common/index.ts';
|
|
@@ -10,17 +9,17 @@ import type { ISyncAction } from './common/index.ts';
|
|
|
10
9
|
const NO_CHANGE = (): void => {};
|
|
11
10
|
|
|
12
11
|
/**
|
|
13
|
-
* The block's text for this project, or undefined when AGENTS.md is absent
|
|
14
|
-
*
|
|
12
|
+
* The block's text for this project, or undefined when AGENTS.md is absent. Every project has the
|
|
13
|
+
* atlas server, and the block is what an agent that does not show the server's own text reads, so it
|
|
14
|
+
* does not wait for a per-machine MCP file to exist.
|
|
15
15
|
*/
|
|
16
16
|
export const mergedAtlasBlock = (opts: {
|
|
17
17
|
root: string;
|
|
18
18
|
config: TResolvedConfig;
|
|
19
19
|
}): { path: string; changed: boolean; text: string } | undefined => {
|
|
20
20
|
const path = join(opts.root, 'AGENTS.md');
|
|
21
|
-
const mcp = join(opts.root, '.mcp.json');
|
|
22
21
|
|
|
23
|
-
if (!existsSync(path)
|
|
22
|
+
if (!existsSync(path)) {
|
|
24
23
|
return undefined;
|
|
25
24
|
}
|
|
26
25
|
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether the menus can draw: both ends are a terminal and it understands cursor movement. Anything
|
|
3
|
+
* else (a pipe, a redirect, `TERM=dumb`) keeps the plain questions, so what scripts and logs see does
|
|
4
|
+
* not change.
|
|
5
|
+
*/
|
|
6
|
+
export const menusAvailable = (): boolean =>
|
|
7
|
+
process.stdin.isTTY === true && process.stdout.isTTY === true && process.env.TERM !== 'dumb';
|
package/src/ui/index.ts
ADDED
package/src/ui/prompt.ts
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { confirm, isCancel, multiselect, note, select, text } from '@clack/prompts';
|
|
2
|
+
|
|
3
|
+
/** One line of a menu: what it is called, and a short note beside it. */
|
|
4
|
+
export interface IChoice {
|
|
5
|
+
value: string;
|
|
6
|
+
label: string;
|
|
7
|
+
hint?: string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Free text, only where there is nothing to pick from (a new name). A default, when there is one, is
|
|
12
|
+
* shown and taken on Enter; `validate` returns the message to show, or nothing when the text is fine.
|
|
13
|
+
* Every prompt answers `null` when the user cancelled (Esc, Ctrl-C): the command stops, never picks
|
|
14
|
+
* for them.
|
|
15
|
+
*/
|
|
16
|
+
export const promptText = async (opts: {
|
|
17
|
+
message: string;
|
|
18
|
+
defaultValue?: string;
|
|
19
|
+
validate?: (value: string) => string | undefined;
|
|
20
|
+
}): Promise<string | null> => {
|
|
21
|
+
const value = await text({
|
|
22
|
+
message: opts.message,
|
|
23
|
+
...(opts.defaultValue === undefined
|
|
24
|
+
? {}
|
|
25
|
+
: { placeholder: opts.defaultValue, defaultValue: opts.defaultValue }),
|
|
26
|
+
validate: input => opts.validate?.(input ?? ''),
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
return isCancel(value) ? null : value;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
/** Pick one: arrows to move, Enter to choose. */
|
|
33
|
+
export const promptSelect = async (opts: {
|
|
34
|
+
message: string;
|
|
35
|
+
choices: IChoice[];
|
|
36
|
+
initial?: string;
|
|
37
|
+
}): Promise<string | null> => {
|
|
38
|
+
const value = await select({
|
|
39
|
+
message: opts.message,
|
|
40
|
+
options: opts.choices.map(choice => ({
|
|
41
|
+
value: choice.value,
|
|
42
|
+
label: choice.label,
|
|
43
|
+
...(choice.hint === undefined ? {} : { hint: choice.hint }),
|
|
44
|
+
})),
|
|
45
|
+
initialValue: opts.initial,
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
return isCancel(value) ? null : value;
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
/** Tick any number: arrows to move, space to toggle, `a` for all, Enter to confirm; what is ticked at the start is `initial`. */
|
|
52
|
+
export const promptMultiselect = async (opts: {
|
|
53
|
+
message: string;
|
|
54
|
+
choices: IChoice[];
|
|
55
|
+
initial: string[];
|
|
56
|
+
}): Promise<string[] | null> => {
|
|
57
|
+
const value = await multiselect({
|
|
58
|
+
message: opts.message,
|
|
59
|
+
options: opts.choices.map(choice => ({
|
|
60
|
+
value: choice.value,
|
|
61
|
+
label: choice.label,
|
|
62
|
+
...(choice.hint === undefined ? {} : { hint: choice.hint }),
|
|
63
|
+
})),
|
|
64
|
+
initialValues: opts.initial,
|
|
65
|
+
required: false,
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
return isCancel(value) ? null : value;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
export const promptConfirm = async (opts: {
|
|
72
|
+
message: string;
|
|
73
|
+
initial?: boolean;
|
|
74
|
+
}): Promise<boolean | null> => {
|
|
75
|
+
const value = await confirm({ message: opts.message, initialValue: opts.initial ?? true });
|
|
76
|
+
|
|
77
|
+
return isCancel(value) ? null : value;
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
/** The summary of what is about to be written, then the confirm; true only when the user said yes. */
|
|
81
|
+
export const promptPlan = async (opts: { title: string; lines: string[] }): Promise<boolean> => {
|
|
82
|
+
note(opts.lines.join('\n'), opts.title);
|
|
83
|
+
|
|
84
|
+
return (await promptConfirm({ message: 'Write these files?' })) === true;
|
|
85
|
+
};
|