@venizia/vulcan 0.3.9 → 0.3.11
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/base/skills/docs-writing/SKILL.md +3 -1
- package/package.json +12 -11
- package/src/commands/help.command.ts +5 -3
- package/src/create/add-app.ts +23 -2
- package/src/create/add-lib.ts +1 -2
- package/src/create/bunfig.ts +11 -0
- package/src/create/common/types.ts +1 -1
- package/src/create/init-monorepo.ts +32 -4
- package/src/create/names.ts +34 -0
- package/src/create/preset.ts +25 -5
- package/src/create/workspace.ts +3 -1
- package/src/doctor/checks.ts +13 -0
- package/src/doctor/runner.ts +2 -1
- package/src/doctor/skills.ts +1 -42
- package/src/init/scaffold.ts +2 -0
- package/src/router.ts +1 -0
- package/src/skills/frontmatter.ts +43 -0
- package/src/skills/index.ts +1 -0
- package/src/ui/keyboard.ts +39 -0
- package/src/ui/prompt.ts +36 -27
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: docs-writing
|
|
3
|
-
description: Reader-first writing method for ALL of the project's documentation. Use
|
|
3
|
+
description: Reader-first writing method for ALL of the project's documentation. Use when you write or edit anything a human will read - wiki pages, READMEs, changelogs, references, guides, the knowledge bundle (.agents/knowledge), or when asked to "document" a feature, even when the request never says "docs", and when reviewing or simplifying existing documentation.
|
|
4
4
|
user-invocable: true
|
|
5
5
|
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Docs Writing - think like a reader, write like a writer
|
|
9
9
|
|
|
10
|
+
**Be extremely concise. Sacrifice grammar for the sake of concision.**
|
|
11
|
+
|
|
10
12
|
One goal: a reader opens the page and knows within seconds what it is about, and can act on it after one read. We never prove that a topic is deep. We make it feel easy.
|
|
11
13
|
|
|
12
14
|
The method has four steps. Do them in order.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.11",
|
|
4
4
|
"description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
|
|
6
6
|
"repository": {
|
|
@@ -34,27 +34,28 @@
|
|
|
34
34
|
"LICENSE.md",
|
|
35
35
|
"src",
|
|
36
36
|
"base",
|
|
37
|
-
"
|
|
37
|
+
"!**/__tests__",
|
|
38
|
+
"!**/*.tsbuildinfo"
|
|
38
39
|
],
|
|
39
40
|
"publishConfig": {
|
|
40
41
|
"access": "public"
|
|
41
42
|
},
|
|
42
43
|
"scripts": {
|
|
43
44
|
"force-update": "sh ../../scripts/force-update.sh",
|
|
44
|
-
"test": "
|
|
45
|
+
"test": "bun test"
|
|
45
46
|
},
|
|
46
47
|
"dependencies": {
|
|
47
48
|
"@clack/prompts": "1.8.1",
|
|
48
|
-
"@venizia/vulcan-atlas": "0.3.
|
|
49
|
-
"@venizia/vulcan-okf": "0.3.
|
|
50
|
-
"zod": "^4.
|
|
49
|
+
"@venizia/vulcan-atlas": "0.3.11",
|
|
50
|
+
"@venizia/vulcan-okf": "0.3.11",
|
|
51
|
+
"zod": "^4.6.7"
|
|
51
52
|
},
|
|
52
53
|
"devDependencies": {
|
|
53
|
-
"@types/bun": "1.4.
|
|
54
|
-
"@venizia/dev-configs": "0.3.
|
|
55
|
-
"eslint": "10.
|
|
56
|
-
"oxfmt": "0.
|
|
57
|
-
"oxlint": "1.
|
|
54
|
+
"@types/bun": "1.4.3",
|
|
55
|
+
"@venizia/dev-configs": "0.3.5",
|
|
56
|
+
"eslint": "10.13.0",
|
|
57
|
+
"oxfmt": "0.74.0",
|
|
58
|
+
"oxlint": "1.89.0",
|
|
58
59
|
"oxlint-tsgolint": "7.0.2004",
|
|
59
60
|
"typescript": "^6.0.3"
|
|
60
61
|
},
|
|
@@ -6,13 +6,15 @@ Usage: bun x vulcan <command>
|
|
|
6
6
|
|
|
7
7
|
init [--config ts|mts|mjs|js] Scaffold the project layer (never overwrites)
|
|
8
8
|
init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <name>]
|
|
9
|
-
[--shared-dir <name>]
|
|
9
|
+
[--shared-dir <name>] [--scope <@scope>]
|
|
10
|
+
Create a monorepo with its first app, from a framework preset
|
|
10
11
|
(a name missing from the flags is asked in a terminal)
|
|
11
12
|
add --preset <name|file:path> (--app <name> | --lib <name>) [--dir <folder>] [--scope <@scope>]
|
|
12
13
|
[--backend-dir|--frontend-dir <name>] [--api <app> | --no-api]
|
|
13
14
|
Add an app or a shared library to the monorepo (a frontend says which
|
|
14
|
-
backend to proxy to; --dir
|
|
15
|
-
|
|
15
|
+
backend to proxy to; --dir is for a library; --scope names the package
|
|
16
|
+
@scope/<name>, for an app or a library; a terminal asks for the kind
|
|
17
|
+
and every name the flags leave out)
|
|
16
18
|
sync [--agents <list>|list] [--dry-run] [--prune]
|
|
17
19
|
Write the adapters of the agents you chose (--agents claude,omp or none,
|
|
18
20
|
stored in .agents/vulcan.local.json; --agents list shows the table);
|
package/src/create/add-app.ts
CHANGED
|
@@ -15,9 +15,11 @@ import { askPresetSpec } from './preset-menu.ts';
|
|
|
15
15
|
import { ABORTED, confirmWrite, planLines } from './plan.ts';
|
|
16
16
|
import {
|
|
17
17
|
askInTerminal,
|
|
18
|
+
askScope,
|
|
18
19
|
askWithPrompt,
|
|
19
20
|
nameProblem,
|
|
20
21
|
readFlag,
|
|
22
|
+
readScope,
|
|
21
23
|
resolveNames,
|
|
22
24
|
SIDE_FIELDS,
|
|
23
25
|
} from './names.ts';
|
|
@@ -329,6 +331,12 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
329
331
|
return fail({ message: `${CreateFlags.APP} and ${CreateFlags.LIB} cannot be used together` });
|
|
330
332
|
}
|
|
331
333
|
|
|
334
|
+
const flaggedScope = readScope({ args: opts.args });
|
|
335
|
+
|
|
336
|
+
if (!flaggedScope.ok) {
|
|
337
|
+
return fail({ message: flaggedScope.error });
|
|
338
|
+
}
|
|
339
|
+
|
|
332
340
|
if (libFlag && libName === undefined) {
|
|
333
341
|
return fail({ message: `${CreateFlags.LIB} needs a name` });
|
|
334
342
|
}
|
|
@@ -452,9 +460,20 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
452
460
|
});
|
|
453
461
|
}
|
|
454
462
|
|
|
463
|
+
// Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
|
|
464
|
+
const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
|
|
465
|
+
|
|
466
|
+
if (scope === null) {
|
|
467
|
+
return fail({ message: ABORTED });
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
const packageOfApp = scope === undefined ? app : `${scope}/${app}`;
|
|
455
471
|
const packages = resolvePackages({ config });
|
|
456
472
|
|
|
457
|
-
if (
|
|
473
|
+
if (
|
|
474
|
+
existsSync(join(cwd, folder, app)) ||
|
|
475
|
+
packages.some(entry => entry.dir === app || entry.name === packageOfApp)
|
|
476
|
+
) {
|
|
458
477
|
return fail({ message: `${folder}/${app} already exists` });
|
|
459
478
|
}
|
|
460
479
|
|
|
@@ -478,7 +497,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
478
497
|
}
|
|
479
498
|
|
|
480
499
|
const source = readFileSync(loaded.file, 'utf8');
|
|
481
|
-
const entry = { dir: app, name:
|
|
500
|
+
const entry = { dir: app, name: packageOfApp, path: `${folder}/${app}` };
|
|
482
501
|
const knownSources = new Set(config.atlas.sources.map(known => known.name));
|
|
483
502
|
const newSources = preset.atlas.filter(candidate => !knownSources.has(candidate.name));
|
|
484
503
|
const parsed = parseAppsBlock({ source });
|
|
@@ -538,6 +557,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
538
557
|
lines: planLines({
|
|
539
558
|
rows: [
|
|
540
559
|
['app', `${folder}/${app}`],
|
|
560
|
+
...(scope === undefined ? [] : [['package', packageOfApp] as [string, string]]),
|
|
541
561
|
['side', side],
|
|
542
562
|
['preset', `${packageName} ${packageVersion}`],
|
|
543
563
|
['port', String(devPort)],
|
|
@@ -562,6 +582,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
562
582
|
path: `${folder}/${app}/package.json`,
|
|
563
583
|
content: renderAppManifest({
|
|
564
584
|
app,
|
|
585
|
+
name: packageOfApp,
|
|
565
586
|
preset,
|
|
566
587
|
presetPackage: { name: packageName, version: packageVersion },
|
|
567
588
|
}),
|
package/src/create/add-lib.ts
CHANGED
|
@@ -10,7 +10,7 @@ import { today, writeFile } from './files.ts';
|
|
|
10
10
|
import { readLibPreset } from './lib-preset.ts';
|
|
11
11
|
import type { TLibPreset } from './lib-preset.ts';
|
|
12
12
|
import { ABORTED, confirmWrite, planLines } from './plan.ts';
|
|
13
|
-
import { askInTerminal, readFlag } from './names.ts';
|
|
13
|
+
import { askInTerminal, readFlag, SCOPE_PATTERN } from './names.ts';
|
|
14
14
|
import { copyPresetFiles } from './preset.ts';
|
|
15
15
|
import { runBun } from './process.ts';
|
|
16
16
|
import {
|
|
@@ -26,7 +26,6 @@ import {
|
|
|
26
26
|
} from './workspace.ts';
|
|
27
27
|
|
|
28
28
|
const KNOWLEDGE_DIRECTORY = '.agents/knowledge';
|
|
29
|
-
const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9-]*$/;
|
|
30
29
|
const DIRECTORY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
|
31
30
|
|
|
32
31
|
const fail = (opts: { message: string }): number => {
|
|
@@ -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');
|
|
@@ -72,7 +72,7 @@ export interface IPresetSpec {
|
|
|
72
72
|
|
|
73
73
|
export interface ILocatedPreset {
|
|
74
74
|
preset: IPreset;
|
|
75
|
-
/** 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. */
|
|
76
76
|
libFile?: string;
|
|
77
77
|
/** The preset package's root directory. */
|
|
78
78
|
packageRoot: string;
|
|
@@ -13,11 +13,20 @@ 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
18
|
import { menusAvailable } from '../ui/index.ts';
|
|
18
19
|
import { askPresetSpec } from './preset-menu.ts';
|
|
19
20
|
import { ABORTED, confirmWrite, planLines } from './plan.ts';
|
|
20
|
-
import {
|
|
21
|
+
import {
|
|
22
|
+
askInTerminal,
|
|
23
|
+
askScope,
|
|
24
|
+
findFolderClash,
|
|
25
|
+
readFlag,
|
|
26
|
+
readScope,
|
|
27
|
+
resolveNames,
|
|
28
|
+
SIDE_FIELDS,
|
|
29
|
+
} from './names.ts';
|
|
21
30
|
import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
|
|
22
31
|
import { renderNext } from './next.ts';
|
|
23
32
|
import { isInstallSkipped, runBun, runGitInit } from './process.ts';
|
|
@@ -80,9 +89,12 @@ const writeMonorepo = (opts: {
|
|
|
80
89
|
located: ILocatedPreset;
|
|
81
90
|
folder: string;
|
|
82
91
|
app: string;
|
|
92
|
+
/** `@scope` for the app's package name; the folder stays bare. */
|
|
93
|
+
scope: string | undefined;
|
|
83
94
|
shared: string;
|
|
84
95
|
}): void => {
|
|
85
|
-
const { root, project, spec, presetValue, located, folder, app, shared } = opts;
|
|
96
|
+
const { root, project, spec, presetValue, located, folder, app, shared, scope } = opts;
|
|
97
|
+
const packageOfApp = scope === undefined ? app : `${scope}/${app}`;
|
|
86
98
|
const { preset, packageName, packageVersion } = located;
|
|
87
99
|
const side = preset.side;
|
|
88
100
|
const catalog = {
|
|
@@ -108,6 +120,7 @@ const writeMonorepo = (opts: {
|
|
|
108
120
|
});
|
|
109
121
|
writeFile({ root, path: 'README.md', content: `# ${project}\n` });
|
|
110
122
|
writeFile({ root, path: '.dockerignore', content: renderDockerignore() });
|
|
123
|
+
writeFile({ root, path: 'bunfig.toml', content: renderBunfig() });
|
|
111
124
|
|
|
112
125
|
if (shared !== '') {
|
|
113
126
|
writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
|
|
@@ -136,6 +149,7 @@ const writeMonorepo = (opts: {
|
|
|
136
149
|
path: `${folder}/${app}/package.json`,
|
|
137
150
|
content: renderAppManifest({
|
|
138
151
|
app,
|
|
152
|
+
name: packageOfApp,
|
|
139
153
|
preset,
|
|
140
154
|
presetPackage: { name: packageName, version: packageVersion },
|
|
141
155
|
}),
|
|
@@ -153,7 +167,7 @@ const writeMonorepo = (opts: {
|
|
|
153
167
|
|
|
154
168
|
const block: IAppsBlock = {
|
|
155
169
|
layout: { [side]: folder, ...(shared === '' ? {} : { shared }) },
|
|
156
|
-
packages: [{ dir: app, name:
|
|
170
|
+
packages: [{ dir: app, name: packageOfApp, path: `${folder}/${app}` }],
|
|
157
171
|
presets: [
|
|
158
172
|
recordedPresetOf({
|
|
159
173
|
spec: presetSpecOf({ value: presetValue, root, cwd: dirname(root) }),
|
|
@@ -210,6 +224,12 @@ const runCreate = async (opts: {
|
|
|
210
224
|
return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
|
|
211
225
|
}
|
|
212
226
|
|
|
227
|
+
const flaggedScope = readScope({ args: opts.args });
|
|
228
|
+
|
|
229
|
+
if (!flaggedScope.ok) {
|
|
230
|
+
return fail({ message: flaggedScope.error });
|
|
231
|
+
}
|
|
232
|
+
|
|
213
233
|
const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
|
|
214
234
|
const interactive = process.stdin.isTTY === true;
|
|
215
235
|
const first = await resolveNames({
|
|
@@ -311,6 +331,13 @@ const runCreate = async (opts: {
|
|
|
311
331
|
return fail({ message: clash });
|
|
312
332
|
}
|
|
313
333
|
|
|
334
|
+
// Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
|
|
335
|
+
const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
|
|
336
|
+
|
|
337
|
+
if (scope === null) {
|
|
338
|
+
return fail({ message: ABORTED });
|
|
339
|
+
}
|
|
340
|
+
|
|
314
341
|
const warning = filePresetWarning({
|
|
315
342
|
spec,
|
|
316
343
|
packageName: located.packageName,
|
|
@@ -327,6 +354,7 @@ const runCreate = async (opts: {
|
|
|
327
354
|
['project', project],
|
|
328
355
|
['preset', `${located.packageName} ${located.packageVersion}`],
|
|
329
356
|
[`${side} app`, `${folder}/${app}`],
|
|
357
|
+
...(scope === undefined ? [] : [['package', `${scope}/${app}`] as [string, string]]),
|
|
330
358
|
['shared', shared === '' ? '(none)' : shared],
|
|
331
359
|
],
|
|
332
360
|
}),
|
|
@@ -336,7 +364,7 @@ const runCreate = async (opts: {
|
|
|
336
364
|
return fail({ message: ABORTED });
|
|
337
365
|
}
|
|
338
366
|
|
|
339
|
-
writeMonorepo({ root, project, spec, presetValue, located, folder, app, shared });
|
|
367
|
+
writeMonorepo({ root, project, spec, presetValue, located, folder, app, scope, shared });
|
|
340
368
|
|
|
341
369
|
for (const step of [
|
|
342
370
|
() => runBun({ cwd: root, args: ['install'], label: 'bun install' }),
|
package/src/create/names.ts
CHANGED
|
@@ -25,12 +25,46 @@ export const SIDE_FIELDS: Record<TAppSide, INameField> = {
|
|
|
25
25
|
},
|
|
26
26
|
};
|
|
27
27
|
|
|
28
|
+
/** `@acme`: what `--scope` takes, for a library and for an app. */
|
|
29
|
+
export const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9-]*$/;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* The optional scope question of a menu: a package scope typed, or nothing for a bare name. Asked only
|
|
33
|
+
* where menus are drawn; a plain terminal and a script give `--scope`. `null` is a cancel.
|
|
34
|
+
*/
|
|
35
|
+
export const askScope = async (): Promise<string | undefined | null> => {
|
|
36
|
+
const answer = await promptText({
|
|
37
|
+
message: 'Package scope (optional, like @acme; empty for none)',
|
|
38
|
+
validate: value =>
|
|
39
|
+
value.trim() === '' || SCOPE_PATTERN.test(value.trim())
|
|
40
|
+
? undefined
|
|
41
|
+
: `'${value.trim()}' is not a scope like @acme`,
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
return answer === null ? null : answer.trim() === '' ? undefined : answer.trim();
|
|
45
|
+
};
|
|
46
|
+
|
|
28
47
|
export const readFlag = (opts: { args: string[]; flag: string }): string | undefined => {
|
|
29
48
|
const index = opts.args.indexOf(opts.flag);
|
|
30
49
|
|
|
31
50
|
return index === -1 ? undefined : opts.args[index + 1];
|
|
32
51
|
};
|
|
33
52
|
|
|
53
|
+
/** The scope the flag names, validated: none when absent, an error that names the flag when it is not `@scope`. */
|
|
54
|
+
export const readScope = (opts: {
|
|
55
|
+
args: string[];
|
|
56
|
+
}): { ok: true; scope: string | undefined } | { ok: false; error: string } => {
|
|
57
|
+
const given = readFlag({ args: opts.args, flag: CreateFlags.SCOPE });
|
|
58
|
+
|
|
59
|
+
if (given === undefined) {
|
|
60
|
+
return { ok: true, scope: undefined };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
return SCOPE_PATTERN.test(given)
|
|
64
|
+
? { ok: true, scope: given }
|
|
65
|
+
: { ok: false, error: `${CreateFlags.SCOPE} '${given}' is not a scope like @acme` };
|
|
66
|
+
};
|
|
67
|
+
|
|
34
68
|
const isValidName = (opts: { name: string }): boolean =>
|
|
35
69
|
CreateConstants.NAME_PATTERN.test(opts.name);
|
|
36
70
|
|
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
|
@@ -153,12 +153,14 @@ const toCatalog = (opts: { dependencies: Record<string, string> }): Record<strin
|
|
|
153
153
|
|
|
154
154
|
export const renderAppManifest = (opts: {
|
|
155
155
|
app: string;
|
|
156
|
+
/** The package name when it is not the app name: `@scope/<app>`. */
|
|
157
|
+
name?: string;
|
|
156
158
|
preset: IPreset;
|
|
157
159
|
presetPackage: { name: string; version: string };
|
|
158
160
|
}): string =>
|
|
159
161
|
json({
|
|
160
162
|
value: {
|
|
161
|
-
name: opts.app,
|
|
163
|
+
name: opts.name ?? opts.app,
|
|
162
164
|
version: '0.0.0',
|
|
163
165
|
private: true,
|
|
164
166
|
// The preset's own text: no token is replaced here, a path pattern has no use for one.
|
package/src/doctor/checks.ts
CHANGED
|
@@ -37,6 +37,7 @@ import {
|
|
|
37
37
|
planSync,
|
|
38
38
|
SyncStatuses,
|
|
39
39
|
} from '../sync/index.ts';
|
|
40
|
+
import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
|
|
40
41
|
import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
|
|
41
42
|
import type { IViolation, TDoctorCheck } from './common/index.ts';
|
|
42
43
|
import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
|
|
@@ -806,3 +807,15 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
|
|
|
806
807
|
}),
|
|
807
808
|
];
|
|
808
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
|
};
|
package/src/doctor/skills.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { dirname, join, relative, resolve } from 'node:path';
|
|
|
3
3
|
import type { ICheckContext } from './checks.ts';
|
|
4
4
|
import { DoctorChecks } from './common/index.ts';
|
|
5
5
|
import type { IViolation } from './common/index.ts';
|
|
6
|
+
import { frontmatterOf } from '../skills/index.ts';
|
|
6
7
|
|
|
7
8
|
/**
|
|
8
9
|
* Anthropic's skill-authoring rules (platform.claude.com, Agent Skills best practices), as checks:
|
|
@@ -33,48 +34,6 @@ const filesOf = (opts: { directory: string }): string[] =>
|
|
|
33
34
|
const lineCountOf = (opts: { text: string }): number =>
|
|
34
35
|
opts.text.replace(/\n$/, '').split('\n').length;
|
|
35
36
|
|
|
36
|
-
const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
|
|
37
|
-
try {
|
|
38
|
-
return { value: Bun.YAML.parse(opts.text) };
|
|
39
|
-
} catch (error) {
|
|
40
|
-
return { error: error instanceof Error ? error.message : String(error) };
|
|
41
|
-
}
|
|
42
|
-
};
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
* The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
|
|
46
|
-
* is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
|
|
47
|
-
*/
|
|
48
|
-
const frontmatterOf = (opts: {
|
|
49
|
-
text: string;
|
|
50
|
-
}): { data: Record<string, unknown>; error?: string } => {
|
|
51
|
-
const block = FRONTMATTER.exec(opts.text)?.[1];
|
|
52
|
-
|
|
53
|
-
if (block === undefined) {
|
|
54
|
-
return { data: {} };
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
const parsed = parseYaml({ text: block });
|
|
58
|
-
|
|
59
|
-
if (parsed.error !== undefined) {
|
|
60
|
-
const blockLines = block.split('\n');
|
|
61
|
-
const failsAt = blockLines.findIndex(
|
|
62
|
-
(_line, index) =>
|
|
63
|
-
parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
|
|
64
|
-
);
|
|
65
|
-
const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
|
|
66
|
-
|
|
67
|
-
return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
return {
|
|
71
|
-
data:
|
|
72
|
-
typeof parsed.value === 'object' && parsed.value !== null
|
|
73
|
-
? Object.fromEntries(Object.entries(parsed.value))
|
|
74
|
-
: {},
|
|
75
|
-
};
|
|
76
|
-
};
|
|
77
|
-
|
|
78
37
|
/** Every rule one skill directory breaks, each a message naming the file. */
|
|
79
38
|
export const lintSkill = (opts: { directory: string }): string[] => {
|
|
80
39
|
const skillFile = join(opts.directory, 'SKILL.md');
|
package/src/init/scaffold.ts
CHANGED
|
@@ -4,6 +4,7 @@ import { BASE_DIRECTORY, ProjectLayout, readProperty } from '../common/index.ts'
|
|
|
4
4
|
import { ConfigConstants, findConfigFiles } from '../config/index.ts';
|
|
5
5
|
import type { TConfigExtension } from '../config/index.ts';
|
|
6
6
|
import { InitConstants, InitStatuses } from './common/index.ts';
|
|
7
|
+
import { renderBunfig } from '../create/bunfig.ts';
|
|
7
8
|
import { renderDockerignore } from '../create/dockerignore.ts';
|
|
8
9
|
import type { IInitEntry, IScaffoldFile } from './common/index.ts';
|
|
9
10
|
|
|
@@ -164,6 +165,7 @@ export const scaffoldProject = (opts: {
|
|
|
164
165
|
}
|
|
165
166
|
|
|
166
167
|
entries.push(writeIfAbsent({ root, path: '.dockerignore', content: renderDockerignore() }));
|
|
168
|
+
entries.push(writeIfAbsent({ root, path: 'bunfig.toml', content: renderBunfig() }));
|
|
167
169
|
|
|
168
170
|
const makefile = join(root, 'Makefile');
|
|
169
171
|
|
package/src/router.ts
CHANGED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
|
|
2
|
+
|
|
3
|
+
const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
|
|
4
|
+
try {
|
|
5
|
+
return { value: Bun.YAML.parse(opts.text) };
|
|
6
|
+
} catch (error) {
|
|
7
|
+
return { error: error instanceof Error ? error.message : String(error) };
|
|
8
|
+
}
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
|
|
13
|
+
* is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
|
|
14
|
+
*/
|
|
15
|
+
export const frontmatterOf = (opts: {
|
|
16
|
+
text: string;
|
|
17
|
+
}): { data: Record<string, unknown>; error?: string } => {
|
|
18
|
+
const block = FRONTMATTER.exec(opts.text)?.[1];
|
|
19
|
+
|
|
20
|
+
if (block === undefined) {
|
|
21
|
+
return { data: {} };
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
const parsed = parseYaml({ text: block });
|
|
25
|
+
|
|
26
|
+
if (parsed.error !== undefined) {
|
|
27
|
+
const blockLines = block.split('\n');
|
|
28
|
+
const failsAt = blockLines.findIndex(
|
|
29
|
+
(_line, index) =>
|
|
30
|
+
parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
|
|
31
|
+
);
|
|
32
|
+
const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
|
|
33
|
+
|
|
34
|
+
return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
return {
|
|
38
|
+
data:
|
|
39
|
+
typeof parsed.value === 'object' && parsed.value !== null
|
|
40
|
+
? Object.fromEntries(Object.entries(parsed.value))
|
|
41
|
+
: {},
|
|
42
|
+
};
|
|
43
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './frontmatter.ts';
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
const LINE_FEED = 0x0a;
|
|
2
|
+
const SHOW_CURSOR = '\u001b[?25h';
|
|
3
|
+
const REFUSAL = [
|
|
4
|
+
'vulcan: this menu reads key presses, not lines, and got a line of piped input (LF).',
|
|
5
|
+
'Pass the flags instead (for example --agents claude,omp; see --help of the command), or set TERM=dumb to keep the plain line questions.',
|
|
6
|
+
].join('\n');
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* A keyboard in raw mode sends CR for Enter, never LF. LF means the answers were piped in (a script
|
|
10
|
+
* feeding a pty), and a menu would wait for a key that never comes. So while a menu is open, the first
|
|
11
|
+
* LF restores the terminal and ends the command with the way out: a refusal, not a hang.
|
|
12
|
+
*/
|
|
13
|
+
export const guardAgainstPipedLines = async <TResult>(
|
|
14
|
+
run: () => Promise<TResult>,
|
|
15
|
+
): Promise<TResult> => {
|
|
16
|
+
const refuse = (chunk: Buffer | string): void => {
|
|
17
|
+
const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
|
|
18
|
+
|
|
19
|
+
if (!bytes.includes(LINE_FEED)) {
|
|
20
|
+
return;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
if (process.stdin.isTTY === true) {
|
|
24
|
+
process.stdin.setRawMode(false);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
process.stdout.write(SHOW_CURSOR);
|
|
28
|
+
process.stderr.write(`\n${REFUSAL}\n`);
|
|
29
|
+
process.exit(1);
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
process.stdin.on('data', refuse);
|
|
33
|
+
|
|
34
|
+
try {
|
|
35
|
+
return await run();
|
|
36
|
+
} finally {
|
|
37
|
+
process.stdin.off('data', refuse);
|
|
38
|
+
}
|
|
39
|
+
};
|
package/src/ui/prompt.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { confirm, isCancel, multiselect, note, select, text } from '@clack/prompts';
|
|
2
|
+
import { guardAgainstPipedLines } from './keyboard.ts';
|
|
2
3
|
|
|
3
4
|
/** One line of a menu: what it is called, and a short note beside it. */
|
|
4
5
|
export interface IChoice {
|
|
@@ -18,13 +19,15 @@ export const promptText = async (opts: {
|
|
|
18
19
|
defaultValue?: string;
|
|
19
20
|
validate?: (value: string) => string | undefined;
|
|
20
21
|
}): Promise<string | null> => {
|
|
21
|
-
const value = await
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
22
|
+
const value = await guardAgainstPipedLines(() =>
|
|
23
|
+
text({
|
|
24
|
+
message: opts.message,
|
|
25
|
+
...(opts.defaultValue === undefined
|
|
26
|
+
? {}
|
|
27
|
+
: { placeholder: opts.defaultValue, defaultValue: opts.defaultValue }),
|
|
28
|
+
validate: input => opts.validate?.(input ?? ''),
|
|
29
|
+
}),
|
|
30
|
+
);
|
|
28
31
|
|
|
29
32
|
return isCancel(value) ? null : value;
|
|
30
33
|
};
|
|
@@ -35,15 +38,17 @@ export const promptSelect = async (opts: {
|
|
|
35
38
|
choices: IChoice[];
|
|
36
39
|
initial?: string;
|
|
37
40
|
}): Promise<string | null> => {
|
|
38
|
-
const value = await
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
41
|
+
const value = await guardAgainstPipedLines(() =>
|
|
42
|
+
select({
|
|
43
|
+
message: opts.message,
|
|
44
|
+
options: opts.choices.map(choice => ({
|
|
45
|
+
value: choice.value,
|
|
46
|
+
label: choice.label,
|
|
47
|
+
...(choice.hint === undefined ? {} : { hint: choice.hint }),
|
|
48
|
+
})),
|
|
49
|
+
initialValue: opts.initial,
|
|
50
|
+
}),
|
|
51
|
+
);
|
|
47
52
|
|
|
48
53
|
return isCancel(value) ? null : value;
|
|
49
54
|
};
|
|
@@ -54,16 +59,18 @@ export const promptMultiselect = async (opts: {
|
|
|
54
59
|
choices: IChoice[];
|
|
55
60
|
initial: string[];
|
|
56
61
|
}): Promise<string[] | null> => {
|
|
57
|
-
const value = await
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
62
|
+
const value = await guardAgainstPipedLines(() =>
|
|
63
|
+
multiselect({
|
|
64
|
+
message: opts.message,
|
|
65
|
+
options: opts.choices.map(choice => ({
|
|
66
|
+
value: choice.value,
|
|
67
|
+
label: choice.label,
|
|
68
|
+
...(choice.hint === undefined ? {} : { hint: choice.hint }),
|
|
69
|
+
})),
|
|
70
|
+
initialValues: opts.initial,
|
|
71
|
+
required: false,
|
|
72
|
+
}),
|
|
73
|
+
);
|
|
67
74
|
|
|
68
75
|
return isCancel(value) ? null : value;
|
|
69
76
|
};
|
|
@@ -72,7 +79,9 @@ export const promptConfirm = async (opts: {
|
|
|
72
79
|
message: string;
|
|
73
80
|
initial?: boolean;
|
|
74
81
|
}): Promise<boolean | null> => {
|
|
75
|
-
const value = await
|
|
82
|
+
const value = await guardAgainstPipedLines(() =>
|
|
83
|
+
confirm({ message: opts.message, initialValue: opts.initial ?? true }),
|
|
84
|
+
);
|
|
76
85
|
|
|
77
86
|
return isCancel(value) ? null : value;
|
|
78
87
|
};
|