@venizia/vulcan 0.3.8 → 0.3.10
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/base/skills/docs-writing/SKILL.md +3 -1
- package/package.json +13 -11
- package/src/agents/atlas-block.ts +1 -0
- package/src/agents/exclude.ts +5 -0
- package/src/agents/prompt.ts +64 -2
- package/src/agents/render.ts +16 -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/bunfig.ts +11 -0
- package/src/create/common/types.ts +16 -2
- package/src/create/init-monorepo.ts +37 -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/preset.ts +25 -5
- package/src/create/workspace.ts +41 -1
- package/src/doctor/checks.ts +42 -13
- package/src/doctor/runner.ts +2 -1
- package/src/doctor/skills.ts +1 -42
- package/src/init/scaffold.ts +3 -41
- package/src/skills/frontmatter.ts +43 -0
- package/src/skills/index.ts +1 -0
- 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/keyboard.ts +39 -0
- package/src/ui/prompt.ts +94 -0
- package/base/templates/mcp.json +0 -8
package/src/create/add-lib.ts
CHANGED
|
@@ -9,7 +9,8 @@ import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts'
|
|
|
9
9
|
import { today, writeFile } from './files.ts';
|
|
10
10
|
import { readLibPreset } from './lib-preset.ts';
|
|
11
11
|
import type { TLibPreset } from './lib-preset.ts';
|
|
12
|
-
import {
|
|
12
|
+
import { ABORTED, confirmWrite, planLines } from './plan.ts';
|
|
13
|
+
import { askInTerminal, readFlag } from './names.ts';
|
|
13
14
|
import { copyPresetFiles } from './preset.ts';
|
|
14
15
|
import { runBun } from './process.ts';
|
|
15
16
|
import {
|
|
@@ -48,13 +49,13 @@ const rootScope = (opts: { manifest: Record<string, unknown> }): string =>
|
|
|
48
49
|
typeof opts.manifest.name === 'string' ? scopeOf({ name: opts.manifest.name }) : '';
|
|
49
50
|
|
|
50
51
|
/** Where the new library goes: `--dir`, the layout's shared folder, or the one folder the existing libraries share. */
|
|
51
|
-
const folderOf = (opts: {
|
|
52
|
+
const folderOf = async (opts: {
|
|
52
53
|
args: string[];
|
|
53
54
|
interactive: boolean;
|
|
54
55
|
lib: string;
|
|
55
56
|
config: TResolvedConfig;
|
|
56
57
|
packages: IProjectPackage[];
|
|
57
|
-
}): { ok: true; folder: string } | { ok: false; error: string } => {
|
|
58
|
+
}): Promise<{ ok: true; folder: string } | { ok: false; error: string }> => {
|
|
58
59
|
const given = readFlag({ args: opts.args, flag: CreateFlags.DIR });
|
|
59
60
|
const libFolders = [
|
|
60
61
|
...new Set(
|
|
@@ -69,8 +70,15 @@ const folderOf = (opts: {
|
|
|
69
70
|
|
|
70
71
|
if (chosen === undefined) {
|
|
71
72
|
if (opts.interactive) {
|
|
72
|
-
|
|
73
|
-
const answer =
|
|
73
|
+
// The folders the project's libraries already live in are picked; a new one is typed.
|
|
74
|
+
const answer =
|
|
75
|
+
(
|
|
76
|
+
await askInTerminal({
|
|
77
|
+
question: 'Folder',
|
|
78
|
+
previous: fallback,
|
|
79
|
+
choices: [...new Set([...(fallback === undefined ? [] : [fallback]), ...libFolders])],
|
|
80
|
+
})
|
|
81
|
+
)?.trim() ?? '';
|
|
74
82
|
|
|
75
83
|
chosen = answer === '' ? fallback : answer;
|
|
76
84
|
} else {
|
|
@@ -153,7 +161,7 @@ export const addLibrary = async (opts: {
|
|
|
153
161
|
}
|
|
154
162
|
|
|
155
163
|
const lib: TLibPreset = read.lib;
|
|
156
|
-
const placed = folderOf({
|
|
164
|
+
const placed = await folderOf({
|
|
157
165
|
args: opts.args,
|
|
158
166
|
interactive: opts.interactive,
|
|
159
167
|
lib: libName,
|
|
@@ -226,6 +234,21 @@ export const addLibrary = async (opts: {
|
|
|
226
234
|
process.stderr.write(`${warning}\n`);
|
|
227
235
|
}
|
|
228
236
|
|
|
237
|
+
const confirmed = await confirmWrite({
|
|
238
|
+
title: `Add ${libName}`,
|
|
239
|
+
lines: planLines({
|
|
240
|
+
rows: [
|
|
241
|
+
['library', path],
|
|
242
|
+
['package', named.name],
|
|
243
|
+
['preset', `${located.packageName} ${located.packageVersion}`],
|
|
244
|
+
],
|
|
245
|
+
}),
|
|
246
|
+
});
|
|
247
|
+
|
|
248
|
+
if (!confirmed) {
|
|
249
|
+
return fail({ message: ABORTED });
|
|
250
|
+
}
|
|
251
|
+
|
|
229
252
|
const written = copyPresetFiles({
|
|
230
253
|
located,
|
|
231
254
|
files: lib.files,
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The root `bunfig.toml` `init` writes: Bun's telemetry off. No `minimumReleaseAge`: a gate of a few
|
|
3
|
+
* days fails a fresh install whose version floors are the latest releases (measured on a real project: ten
|
|
4
|
+
* packages), so it stays out; Phat's rule is floors at the latest.
|
|
5
|
+
*/
|
|
6
|
+
export const renderBunfig = (): string =>
|
|
7
|
+
[
|
|
8
|
+
'# Bun reads this file only from the directory a command runs in, so it sits at the root.',
|
|
9
|
+
'telemetry = false',
|
|
10
|
+
'',
|
|
11
|
+
].join('\n');
|
|
@@ -12,9 +12,23 @@ export interface INameField {
|
|
|
12
12
|
optional?: boolean;
|
|
13
13
|
/** A folder the user chose before, offered as the answer; never a name VULCAN made up. */
|
|
14
14
|
previous?: string;
|
|
15
|
+
/** Folders that already exist and fit this field: a menu lists them, then offers a new one. */
|
|
16
|
+
choices?: string[];
|
|
17
|
+
/** The only valid answer is `previous` (one folder per side): a menu never asks, a flag still wins. */
|
|
18
|
+
fixed?: boolean;
|
|
15
19
|
}
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
/** What a question carries: the text, the earlier choice, the existing folders, the check a menu runs while typing. */
|
|
22
|
+
export interface IAskOptions {
|
|
23
|
+
question: string;
|
|
24
|
+
previous?: string;
|
|
25
|
+
choices?: string[];
|
|
26
|
+
/** The message to show, or nothing when the text is fine. */
|
|
27
|
+
validate?: (value: string) => string | undefined;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** `null` is end of input or a cancelled menu; a menu answers later, so the answer may be a promise. */
|
|
31
|
+
export type TAsk = (opts: IAskOptions) => string | null | Promise<string | null>;
|
|
18
32
|
|
|
19
33
|
/** Reads at most one byte into `buffer` and returns how many were read; 0 is end of input. */
|
|
20
34
|
export type TByteReader = (opts: { descriptor: number; buffer: Buffer }) => number;
|
|
@@ -58,7 +72,7 @@ export interface IPresetSpec {
|
|
|
58
72
|
|
|
59
73
|
export interface ILocatedPreset {
|
|
60
74
|
preset: IPreset;
|
|
61
|
-
/** The lib preset file (`vulcan.lib`), absolute and inside the package; absent when the preset makes apps only. */
|
|
75
|
+
/** The lib preset file (`vulcan.presets.lib`), absolute and inside the package; absent when the preset makes apps only. */
|
|
62
76
|
libFile?: string;
|
|
63
77
|
/** The preset package's root directory. */
|
|
64
78
|
packageRoot: string;
|
|
@@ -13,8 +13,12 @@ import type {
|
|
|
13
13
|
} from './common/index.ts';
|
|
14
14
|
import { today, writeFile } from './files.ts';
|
|
15
15
|
import { recordedPresetOf } from './lib-preset.ts';
|
|
16
|
+
import { renderBunfig } from './bunfig.ts';
|
|
16
17
|
import { renderDockerignore } from './dockerignore.ts';
|
|
17
|
-
import {
|
|
18
|
+
import { menusAvailable } from '../ui/index.ts';
|
|
19
|
+
import { askPresetSpec } from './preset-menu.ts';
|
|
20
|
+
import { ABORTED, confirmWrite, planLines } from './plan.ts';
|
|
21
|
+
import { askInTerminal, findFolderClash, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
|
|
18
22
|
import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
|
|
19
23
|
import { renderNext } from './next.ts';
|
|
20
24
|
import { isInstallSkipped, runBun, runGitInit } from './process.ts';
|
|
@@ -34,7 +38,6 @@ import {
|
|
|
34
38
|
const LAYER_FILES = [
|
|
35
39
|
{ path: 'AGENTS.md', template: 'AGENTS.md' },
|
|
36
40
|
{ path: '.agents/rules.md', template: 'rules.md' },
|
|
37
|
-
{ path: '.mcp.json', template: 'mcp.json' },
|
|
38
41
|
{ path: 'Makefile', template: 'Makefile' },
|
|
39
42
|
];
|
|
40
43
|
|
|
@@ -106,6 +109,7 @@ const writeMonorepo = (opts: {
|
|
|
106
109
|
});
|
|
107
110
|
writeFile({ root, path: 'README.md', content: `# ${project}\n` });
|
|
108
111
|
writeFile({ root, path: '.dockerignore', content: renderDockerignore() });
|
|
112
|
+
writeFile({ root, path: 'bunfig.toml', content: renderBunfig() });
|
|
109
113
|
|
|
110
114
|
if (shared !== '') {
|
|
111
115
|
writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
|
|
@@ -195,21 +199,28 @@ const runCreate = async (opts: {
|
|
|
195
199
|
args: string[];
|
|
196
200
|
scratch: string;
|
|
197
201
|
}): Promise<number> => {
|
|
198
|
-
const
|
|
202
|
+
const flagged = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
|
|
199
203
|
|
|
200
|
-
if (
|
|
204
|
+
if (flagged === undefined && !menusAvailable()) {
|
|
205
|
+
return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
// A new project has no config to list presets from: the official ones, or one typed.
|
|
209
|
+
const presetValue = flagged ?? (await askPresetSpec({ recorded: [] }))?.trim();
|
|
210
|
+
|
|
211
|
+
if (presetValue === undefined || presetValue === '') {
|
|
201
212
|
return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
|
|
202
213
|
}
|
|
203
214
|
|
|
204
215
|
const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
|
|
205
216
|
const interactive = process.stdin.isTTY === true;
|
|
206
|
-
const first = resolveNames({
|
|
217
|
+
const first = await resolveNames({
|
|
207
218
|
fields: [
|
|
208
219
|
{ key: 'project', flag: CreateFlags.PROJECT, question: 'Project name (the monorepo folder)' },
|
|
209
220
|
],
|
|
210
221
|
args: opts.args,
|
|
211
222
|
interactive,
|
|
212
|
-
ask:
|
|
223
|
+
ask: askInTerminal,
|
|
213
224
|
});
|
|
214
225
|
|
|
215
226
|
if (!first.ok) {
|
|
@@ -237,11 +248,11 @@ const runCreate = async (opts: {
|
|
|
237
248
|
if (isNpm) {
|
|
238
249
|
// Without a terminal nothing is asked, so a missing flag is refused before the network is used.
|
|
239
250
|
if (!interactive) {
|
|
240
|
-
const early = resolveNames({
|
|
251
|
+
const early = await resolveNames({
|
|
241
252
|
fields: appFields({}),
|
|
242
253
|
args: opts.args,
|
|
243
254
|
interactive,
|
|
244
|
-
ask:
|
|
255
|
+
ask: askInTerminal,
|
|
245
256
|
});
|
|
246
257
|
|
|
247
258
|
if (!early.ok) {
|
|
@@ -273,11 +284,11 @@ const runCreate = async (opts: {
|
|
|
273
284
|
located = result.located;
|
|
274
285
|
}
|
|
275
286
|
|
|
276
|
-
const rest = resolveNames({
|
|
287
|
+
const rest = await resolveNames({
|
|
277
288
|
fields: appFields({ side: located.preset.side }),
|
|
278
289
|
args: opts.args,
|
|
279
290
|
interactive,
|
|
280
|
-
ask:
|
|
291
|
+
ask: askInTerminal,
|
|
281
292
|
});
|
|
282
293
|
|
|
283
294
|
if (!rest.ok) {
|
|
@@ -311,6 +322,22 @@ const runCreate = async (opts: {
|
|
|
311
322
|
process.stderr.write(`${warning}\n`);
|
|
312
323
|
}
|
|
313
324
|
|
|
325
|
+
const confirmed = await confirmWrite({
|
|
326
|
+
title: `Create ${project}`,
|
|
327
|
+
lines: planLines({
|
|
328
|
+
rows: [
|
|
329
|
+
['project', project],
|
|
330
|
+
['preset', `${located.packageName} ${located.packageVersion}`],
|
|
331
|
+
[`${side} app`, `${folder}/${app}`],
|
|
332
|
+
['shared', shared === '' ? '(none)' : shared],
|
|
333
|
+
],
|
|
334
|
+
}),
|
|
335
|
+
});
|
|
336
|
+
|
|
337
|
+
if (!confirmed) {
|
|
338
|
+
return fail({ message: ABORTED });
|
|
339
|
+
}
|
|
340
|
+
|
|
314
341
|
writeMonorepo({ root, project, spec, presetValue, located, folder, app, shared });
|
|
315
342
|
|
|
316
343
|
for (const step of [
|
package/src/create/names.ts
CHANGED
|
@@ -1,7 +1,15 @@
|
|
|
1
1
|
import { readSync } from 'node:fs';
|
|
2
2
|
|
|
3
|
+
import { menusAvailable, promptSelect, promptText } from '../ui/index.ts';
|
|
3
4
|
import { AppSides, CreateConstants, CreateFlags } from './common/index.ts';
|
|
4
|
-
import type {
|
|
5
|
+
import type {
|
|
6
|
+
IAskOptions,
|
|
7
|
+
INameField,
|
|
8
|
+
TAppSide,
|
|
9
|
+
TAsk,
|
|
10
|
+
TByteReader,
|
|
11
|
+
TNamesResult,
|
|
12
|
+
} from './common/index.ts';
|
|
5
13
|
|
|
6
14
|
/** The folder holding every app of one side; `add` offers the one the config already holds. */
|
|
7
15
|
export const SIDE_FIELDS: Record<TAppSide, INameField> = {
|
|
@@ -26,6 +34,12 @@ export const readFlag = (opts: { args: string[]; flag: string }): string | undef
|
|
|
26
34
|
const isValidName = (opts: { name: string }): boolean =>
|
|
27
35
|
CreateConstants.NAME_PATTERN.test(opts.name);
|
|
28
36
|
|
|
37
|
+
/** The message a menu shows under a typed name that is not one; nothing when it is fine. */
|
|
38
|
+
export const nameProblem = (opts: { name: string }): string | undefined =>
|
|
39
|
+
isValidName({ name: opts.name })
|
|
40
|
+
? undefined
|
|
41
|
+
: `'${opts.name}' is not a name: lowercase letters, digits and '-', starting with a letter or digit`;
|
|
42
|
+
|
|
29
43
|
const NEWLINE = 0x0a;
|
|
30
44
|
const CARRIAGE_RETURN = 0x0d;
|
|
31
45
|
const RETRY_PAUSE_MILLISECONDS = 5;
|
|
@@ -91,7 +105,7 @@ export const readLine = (opts: {
|
|
|
91
105
|
};
|
|
92
106
|
|
|
93
107
|
/** The shown default is the user's own earlier choice, never one VULCAN made up. */
|
|
94
|
-
export const askWithPrompt
|
|
108
|
+
export const askWithPrompt = (opts: IAskOptions): string | null => {
|
|
95
109
|
process.stdout.write(
|
|
96
110
|
opts.previous === undefined
|
|
97
111
|
? `? ${opts.question} > `
|
|
@@ -101,9 +115,55 @@ export const askWithPrompt: TAsk = opts => {
|
|
|
101
115
|
return readLine({ descriptor: CreateConstants.STDIN_DESCRIPTOR });
|
|
102
116
|
};
|
|
103
117
|
|
|
104
|
-
const
|
|
118
|
+
const NEW_FOLDER = ':new-folder';
|
|
119
|
+
|
|
120
|
+
/** A menu, not a line: existing folders are picked, a new name is typed with its default shown. */
|
|
121
|
+
const askWithMenus: TAsk = async opts => {
|
|
122
|
+
if (opts.choices !== undefined && opts.choices.length > 0) {
|
|
123
|
+
const picked = await promptSelect({
|
|
124
|
+
message: opts.question,
|
|
125
|
+
choices: [
|
|
126
|
+
...opts.choices.map(value => ({ value, label: value })),
|
|
127
|
+
{ value: NEW_FOLDER, label: 'New folder...' },
|
|
128
|
+
],
|
|
129
|
+
initial: opts.previous,
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
if (picked !== NEW_FOLDER) {
|
|
133
|
+
return picked;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
return promptText({
|
|
138
|
+
message: opts.question,
|
|
139
|
+
defaultValue: opts.previous,
|
|
140
|
+
validate: opts.validate,
|
|
141
|
+
});
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
/** Menus in a terminal that can draw them, the plain question everywhere else. */
|
|
145
|
+
export const askInTerminal: TAsk = opts =>
|
|
146
|
+
menusAvailable() ? askWithMenus(opts) : askWithPrompt(opts);
|
|
147
|
+
|
|
148
|
+
const askUntilValid = async (opts: { field: INameField; ask: TAsk }): Promise<string | null> => {
|
|
149
|
+
const { field } = opts;
|
|
150
|
+
const validate = (value: string): string | undefined => {
|
|
151
|
+
const name = value.trim() === '' ? (field.previous ?? '') : value.trim();
|
|
152
|
+
|
|
153
|
+
if (name === '' && field.optional === true) {
|
|
154
|
+
return undefined;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
return nameProblem({ name });
|
|
158
|
+
};
|
|
159
|
+
|
|
105
160
|
for (;;) {
|
|
106
|
-
const answer = opts.ask({
|
|
161
|
+
const answer = await opts.ask({
|
|
162
|
+
question: field.question,
|
|
163
|
+
previous: field.previous,
|
|
164
|
+
choices: field.choices,
|
|
165
|
+
validate,
|
|
166
|
+
});
|
|
107
167
|
|
|
108
168
|
if (answer === null) {
|
|
109
169
|
return null;
|
|
@@ -126,12 +186,12 @@ const askUntilValid = (opts: { field: INameField; ask: TAsk }): string | null =>
|
|
|
126
186
|
};
|
|
127
187
|
|
|
128
188
|
/** Every name from its flag; a missing one is asked in a TTY and an error otherwise. */
|
|
129
|
-
export const resolveNames = (opts: {
|
|
189
|
+
export const resolveNames = async (opts: {
|
|
130
190
|
fields: INameField[];
|
|
131
191
|
args: string[];
|
|
132
192
|
interactive: boolean;
|
|
133
193
|
ask: TAsk;
|
|
134
|
-
}): TNamesResult => {
|
|
194
|
+
}): Promise<TNamesResult> => {
|
|
135
195
|
const names: Record<string, string> = {};
|
|
136
196
|
|
|
137
197
|
for (const field of opts.fields) {
|
|
@@ -166,7 +226,12 @@ export const resolveNames = (opts: {
|
|
|
166
226
|
};
|
|
167
227
|
}
|
|
168
228
|
|
|
169
|
-
|
|
229
|
+
if (field.fixed === true && field.previous !== undefined) {
|
|
230
|
+
names[field.key] = field.previous;
|
|
231
|
+
continue;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
const answer = await askUntilValid({ field, ask: opts.ask });
|
|
170
235
|
|
|
171
236
|
if (answer === null) {
|
|
172
237
|
return { ok: false, error: 'aborted' };
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { menusAvailable, promptPlan } from '../ui/index.ts';
|
|
2
|
+
|
|
3
|
+
/** `label value` lines with the values in one column. */
|
|
4
|
+
export const planLines = (opts: { rows: [label: string, value: string][] }): string[] => {
|
|
5
|
+
const width = Math.max(...opts.rows.map(([label]) => label.length));
|
|
6
|
+
|
|
7
|
+
return opts.rows.map(([label, value]) => `${label.padEnd(width)} ${value}`);
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Before anything is written, a terminal that can draw menus shows what will be written and asks.
|
|
12
|
+
* Without one nothing is asked: flags and pipes keep writing as they always did.
|
|
13
|
+
*/
|
|
14
|
+
export const confirmWrite = async (opts: { title: string; lines: string[] }): Promise<boolean> =>
|
|
15
|
+
menusAvailable() ? promptPlan(opts) : true;
|
|
16
|
+
|
|
17
|
+
export const ABORTED = 'aborted: nothing was written';
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { OFFICIAL_PRESETS, officialIdOf } from '@venizia/vulcan-atlas';
|
|
2
|
+
import { promptSelect, promptText } from '../ui/index.ts';
|
|
3
|
+
|
|
4
|
+
const ANOTHER_PRESET = ':another-preset';
|
|
5
|
+
|
|
6
|
+
/** A preset a project recorded: what `--preset` takes back, the side it builds, what it is. */
|
|
7
|
+
export interface IKnownPreset {
|
|
8
|
+
spec: string;
|
|
9
|
+
side: string;
|
|
10
|
+
summary: string;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* What a menu offers for `--preset`: the presets the project recorded, then the official ones it has
|
|
15
|
+
* not used yet (the one list atlas answers `presets` from), then a text input for any other package
|
|
16
|
+
* or `file:` path. null when the user cancelled.
|
|
17
|
+
*/
|
|
18
|
+
export const askPresetSpec = async (opts: { recorded: IKnownPreset[] }): Promise<string | null> => {
|
|
19
|
+
const used = new Set(opts.recorded.map(entry => officialIdOf({ spec: entry.spec })));
|
|
20
|
+
const picked = await promptSelect({
|
|
21
|
+
message: 'Which preset?',
|
|
22
|
+
choices: [
|
|
23
|
+
...opts.recorded.map(entry => ({
|
|
24
|
+
value: entry.spec,
|
|
25
|
+
label: entry.spec,
|
|
26
|
+
hint: `${entry.side}: ${entry.summary}`,
|
|
27
|
+
})),
|
|
28
|
+
...OFFICIAL_PRESETS.filter(entry => !used.has(entry.id)).map(entry => ({
|
|
29
|
+
value: entry.id,
|
|
30
|
+
label: entry.id,
|
|
31
|
+
hint: `official, ${entry.side} (app or lib)`,
|
|
32
|
+
})),
|
|
33
|
+
{ value: ANOTHER_PRESET, label: 'Another preset...', hint: 'a package name or file:<path>' },
|
|
34
|
+
],
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
if (picked !== ANOTHER_PRESET) {
|
|
38
|
+
return picked;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
return promptText({
|
|
42
|
+
message: 'Preset (a package name, or file:<path>)',
|
|
43
|
+
validate: value => (value.trim() === '' ? 'a package name, or file:<path>' : undefined),
|
|
44
|
+
});
|
|
45
|
+
};
|
package/src/create/preset.ts
CHANGED
|
@@ -146,12 +146,30 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
|
|
|
146
146
|
const packageName = String(manifest.name);
|
|
147
147
|
const packageVersion = String(manifest.version);
|
|
148
148
|
const shown = `${packageName}@${packageVersion}`;
|
|
149
|
-
const
|
|
149
|
+
const vulcan = manifest[CreateConstants.PRESET_FIELD];
|
|
150
|
+
const oldKeys = ['preset', 'lib'].filter(
|
|
151
|
+
key => readProperty({ value: vulcan, key }) !== undefined,
|
|
152
|
+
);
|
|
153
|
+
|
|
154
|
+
// No fallback to the keys before `presets`: say what the contract is now.
|
|
155
|
+
if (oldKeys.length > 0) {
|
|
156
|
+
return {
|
|
157
|
+
ok: false,
|
|
158
|
+
error: `${shown} uses the old keys "vulcan": { ${oldKeys.map(key => `"${key}"`).join(', ')} }; the contract is now "vulcan": { "presets": { "app": "./path/preset.json", "lib": "./path/lib.json" } }`,
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
const presets = readProperty({ value: vulcan, key: 'presets' });
|
|
163
|
+
const field = readProperty({ value: presets, key: 'app' });
|
|
164
|
+
const libField = readProperty({ value: presets, key: 'lib' });
|
|
150
165
|
|
|
151
166
|
if (typeof field !== 'string') {
|
|
152
167
|
return {
|
|
153
168
|
ok: false,
|
|
154
|
-
error:
|
|
169
|
+
error:
|
|
170
|
+
typeof libField === 'string'
|
|
171
|
+
? `${shown}: vulcan.presets.lib needs vulcan.presets.app: a lib-only package is not supported`
|
|
172
|
+
: `${shown} ships no VULCAN preset (no "vulcan": { "presets": { "app" } } in its package.json)`,
|
|
155
173
|
};
|
|
156
174
|
}
|
|
157
175
|
|
|
@@ -160,7 +178,7 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
|
|
|
160
178
|
if (presetFile === undefined) {
|
|
161
179
|
return {
|
|
162
180
|
ok: false,
|
|
163
|
-
error: `${shown}: vulcan.
|
|
181
|
+
error: `${shown}: vulcan.presets.app ${field} points outside the package`,
|
|
164
182
|
};
|
|
165
183
|
}
|
|
166
184
|
|
|
@@ -201,14 +219,16 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
|
|
|
201
219
|
}
|
|
202
220
|
|
|
203
221
|
const preset = { ...parsed.data, files: filesFolder };
|
|
204
|
-
const libField = readProperty({ value: manifest[CreateConstants.PRESET_FIELD], key: 'lib' });
|
|
205
222
|
const libFile =
|
|
206
223
|
typeof libField === 'string'
|
|
207
224
|
? resolveInside({ root: packageRoot, from: packageRoot, path: libField })
|
|
208
225
|
: undefined;
|
|
209
226
|
|
|
210
227
|
if (typeof libField === 'string' && libFile === undefined) {
|
|
211
|
-
return {
|
|
228
|
+
return {
|
|
229
|
+
ok: false,
|
|
230
|
+
error: `${shown}: vulcan.presets.lib ${libField} points outside the package`,
|
|
231
|
+
};
|
|
212
232
|
}
|
|
213
233
|
|
|
214
234
|
const located: ILocatedPreset = {
|
package/src/create/workspace.ts
CHANGED
|
@@ -1,7 +1,14 @@
|
|
|
1
1
|
import { relative, resolve } from 'node:path';
|
|
2
2
|
import { coversFolder } from '../init/index.ts';
|
|
3
3
|
import { CreateConstants } from './common/index.ts';
|
|
4
|
-
import type {
|
|
4
|
+
import type {
|
|
5
|
+
IApp,
|
|
6
|
+
IAppsBlock,
|
|
7
|
+
IPreset,
|
|
8
|
+
IPresetSpec,
|
|
9
|
+
IRecordedPreset,
|
|
10
|
+
TAppSide,
|
|
11
|
+
} from './common/index.ts';
|
|
5
12
|
|
|
6
13
|
const ENV_PORT = /^[A-Z0-9_]*PORT=(\d+)\s*$/m;
|
|
7
14
|
|
|
@@ -202,6 +209,37 @@ export const renderLibManifest = (opts: {
|
|
|
202
209
|
});
|
|
203
210
|
};
|
|
204
211
|
|
|
212
|
+
/** The atlas lookups a package of one kind depends on: what a summary page cannot hold. */
|
|
213
|
+
const ATLAS_LOOKUPS: Record<TAppSide | 'lib', [string, string][]> = {
|
|
214
|
+
backend: [
|
|
215
|
+
['How a route and its controller are written', '`search` "controller routes", then `get`'],
|
|
216
|
+
[
|
|
217
|
+
'How a service, a repository and a datasource fit together',
|
|
218
|
+
'`search` "service repository datasource"',
|
|
219
|
+
],
|
|
220
|
+
],
|
|
221
|
+
frontend: [
|
|
222
|
+
['How a page or a resource is added', '`search` "page resource", then `get`'],
|
|
223
|
+
['How the app reads data from its backend', '`search` "data provider"'],
|
|
224
|
+
],
|
|
225
|
+
lib: [['How a shared package exposes its API', '`search` "shared package exports", then `get`']],
|
|
226
|
+
};
|
|
227
|
+
|
|
228
|
+
/** The note and the table that turn a package page into a pointer at atlas, for its kind. */
|
|
229
|
+
const renderAtlasLookups = (opts: { kind: TAppSide | 'lib' }): string[] => [
|
|
230
|
+
'> This page is a summary, not a spec: it says what the package is. How code is written here lives',
|
|
231
|
+
'> in atlas; look it up before you explain or write code.',
|
|
232
|
+
'',
|
|
233
|
+
'## How things are done here',
|
|
234
|
+
'',
|
|
235
|
+
'| You need | Ask atlas |',
|
|
236
|
+
'|---|---|',
|
|
237
|
+
...ATLAS_LOOKUPS[opts.kind].map(([need, call]) => `| ${need} | ${call} |`),
|
|
238
|
+
'| The signature and import path of an export, before you import it | `symbol` with its name |',
|
|
239
|
+
'| A new app or package | `presets`, then the `vulcan add` command it returns |',
|
|
240
|
+
'',
|
|
241
|
+
];
|
|
242
|
+
|
|
205
243
|
export const renderLibConcept = (opts: {
|
|
206
244
|
name: string;
|
|
207
245
|
path: string;
|
|
@@ -221,6 +259,7 @@ export const renderLibConcept = (opts: {
|
|
|
221
259
|
'',
|
|
222
260
|
`The shared package at \`${opts.path}\`, created from the ${opts.presetPackage} preset (lib kind). ${oneLine({ text: opts.summary })}`,
|
|
223
261
|
'',
|
|
262
|
+
...renderAtlasLookups({ kind: 'lib' }),
|
|
224
263
|
].join('\n');
|
|
225
264
|
|
|
226
265
|
export const renderAppsBlock = (opts: { block: IAppsBlock }): string =>
|
|
@@ -445,6 +484,7 @@ export const renderAppConcept = (opts: {
|
|
|
445
484
|
'',
|
|
446
485
|
`The ${opts.app.side} app at \`${opts.app.folder}/${opts.app.name}\`, created from the ${opts.presetPackage} preset. ${oneLine({ text: opts.summary })}`,
|
|
447
486
|
'',
|
|
487
|
+
...renderAtlasLookups({ kind: opts.app.side }),
|
|
448
488
|
].join('\n');
|
|
449
489
|
|
|
450
490
|
export const renderLogEntry = (opts: { date: string; text: string }): string =>
|
package/src/doctor/checks.ts
CHANGED
|
@@ -23,14 +23,21 @@ import {
|
|
|
23
23
|
projectNameOf,
|
|
24
24
|
renderManifest,
|
|
25
25
|
} from '../manifest/index.ts';
|
|
26
|
-
import { readLocalChoice, resolveAgentsQuietly } from '../agents/index.ts';
|
|
27
26
|
import {
|
|
27
|
+
AgentScopes,
|
|
28
|
+
readAgentTable,
|
|
29
|
+
readLocalChoice,
|
|
30
|
+
resolveAgentsQuietly,
|
|
31
|
+
} from '../agents/index.ts';
|
|
32
|
+
import {
|
|
33
|
+
isTracked,
|
|
28
34
|
mergedAtlasBlock,
|
|
29
35
|
planManifest,
|
|
30
36
|
planPrune,
|
|
31
37
|
planSync,
|
|
32
38
|
SyncStatuses,
|
|
33
39
|
} from '../sync/index.ts';
|
|
40
|
+
import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
|
|
34
41
|
import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
|
|
35
42
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
36
43
|
import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
|
|
@@ -620,23 +627,33 @@ const mcpWarning = (opts: { file: string; message: string }): IViolation =>
|
|
|
620
627
|
createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
|
|
621
628
|
|
|
622
629
|
/**
|
|
623
|
-
* The atlas server is registered the one way every project does: the
|
|
624
|
-
* `
|
|
625
|
-
* enable `atlas` by that name. A server under
|
|
626
|
-
* never enabled automatically or serves the wrong
|
|
630
|
+
* The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
|
|
631
|
+
* file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
|
|
632
|
+
* atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
|
|
633
|
+
* another name, or one that serves another folder, is never enabled automatically or serves the wrong
|
|
634
|
+
* knowledge. A `.mcp.json` git still tracks is told how to hand over to `sync`. Warnings, not violations.
|
|
627
635
|
*/
|
|
628
636
|
export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
|
|
629
637
|
const warnings: IViolation[] = [];
|
|
630
638
|
const file = join(opts.root, MCP_FILE);
|
|
639
|
+
const chosen = resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents });
|
|
640
|
+
const readsMcpFile = readAgentTable().some(
|
|
641
|
+
entry => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
|
|
642
|
+
);
|
|
643
|
+
|
|
644
|
+
// The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
|
|
645
|
+
// `adapters` check's (not synced yet), so only an existing file is looked at.
|
|
646
|
+
if (readsMcpFile && existsSync(file)) {
|
|
647
|
+
if (isTracked({ root: opts.root, path: MCP_FILE })) {
|
|
648
|
+
warnings.push(
|
|
649
|
+
mcpWarning({
|
|
650
|
+
file: MCP_FILE,
|
|
651
|
+
message:
|
|
652
|
+
'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
|
|
653
|
+
}),
|
|
654
|
+
);
|
|
655
|
+
}
|
|
631
656
|
|
|
632
|
-
if (!existsSync(file)) {
|
|
633
|
-
warnings.push(
|
|
634
|
-
mcpWarning({
|
|
635
|
-
file: MCP_FILE,
|
|
636
|
-
message: `missing: atlas is not registered for Claude Code, omp and Copilot CLI - add ${MCP_SERVER_HINT} under mcpServers`,
|
|
637
|
-
}),
|
|
638
|
-
);
|
|
639
|
-
} else {
|
|
640
657
|
const parsed = readJsonObject({ file });
|
|
641
658
|
|
|
642
659
|
if (parsed === undefined) {
|
|
@@ -790,3 +807,15 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
|
|
|
790
807
|
}),
|
|
791
808
|
];
|
|
792
809
|
};
|
|
810
|
+
|
|
811
|
+
/** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
|
|
812
|
+
export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
|
|
813
|
+
skillCatalogOf({ root: opts.root })
|
|
814
|
+
.filter(entry => !triggerOf({ description: entry.description }).hasUseWhen)
|
|
815
|
+
.map(entry =>
|
|
816
|
+
createViolation({
|
|
817
|
+
check: DoctorChecks.SKILLS,
|
|
818
|
+
file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
|
|
819
|
+
message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
|
|
820
|
+
}),
|
|
821
|
+
);
|
package/src/doctor/runner.ts
CHANGED
|
@@ -5,6 +5,7 @@ import {
|
|
|
5
5
|
checkAgents,
|
|
6
6
|
checkAppScripts,
|
|
7
7
|
checkAtlasBlock,
|
|
8
|
+
checkSkillTriggers,
|
|
8
9
|
checkDockerignore,
|
|
9
10
|
checkMcpAtlas,
|
|
10
11
|
checkApps,
|
|
@@ -94,5 +95,5 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
|
|
|
94
95
|
configFile: relative(opts.root, loaded.file),
|
|
95
96
|
};
|
|
96
97
|
|
|
97
|
-
return [...checkMcpAtlas(context), ...checkDockerignore(context)];
|
|
98
|
+
return [...checkMcpAtlas(context), ...checkDockerignore(context), ...checkSkillTriggers(context)];
|
|
98
99
|
};
|