@venizia/vulcan 0.4.8 → 0.4.9-1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/base/extensions/vulcan-guards.ts +48 -41
- package/base/hooks/antigravity-guards.ts +4 -3
- package/base/hooks/codex-guards.ts +17 -6
- package/base/hooks/guard-git.ts +8 -8
- package/base/hooks/guard-manifest.ts +5 -5
- package/base/hooks/guard-outside.ts +8 -8
- package/base/hooks/guard-package.ts +6 -6
- package/base/hooks/guard-remote-hosts.ts +14 -9
- package/base/hooks/guard-scripting.ts +6 -6
- package/base/hooks/guard-writes.ts +20 -11
- package/base/hooks/post-tool.ts +4 -3
- package/base/hooks/prompt-submit.ts +4 -3
- package/base/hooks/session-start.ts +5 -3
- package/base/hooks/stop.ts +4 -3
- package/base/hooks/subagent-start.ts +2 -2
- package/base/make/vulcan.mk +1 -4
- package/base/skills/build-a-feature/SKILL.md +1 -1
- package/base/skills/docs-update/SKILL.md +11 -5
- package/base/skills/docs-update/evals/evals.json +1 -1
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/plan-a-change/references/spec-card.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +29 -6
- package/base/skills/visualize-work/references/spec.md +16 -5
- package/package.json +5 -6
- package/src/agents/atlas-block.ts +43 -43
- package/src/agents/codex-hooks.ts +55 -52
- package/src/agents/common/types.ts +1 -1
- package/src/agents/detect.ts +19 -16
- package/src/agents/exclude.ts +97 -98
- package/src/agents/hooks-json.ts +41 -43
- package/src/agents/local.ts +46 -43
- package/src/agents/prompt.ts +45 -42
- package/src/agents/render.ts +203 -201
- package/src/agents/resolve.ts +133 -134
- package/src/agents/table.ts +12 -8
- package/src/cli.ts +3 -1
- package/src/commands/add.command.ts +2 -2
- package/src/commands/agents.command.ts +11 -17
- package/src/commands/clean.command.ts +6 -6
- package/src/commands/doctor.command.ts +6 -4
- package/src/commands/help.command.ts +11 -9
- package/src/commands/init.command.ts +14 -8
- package/src/commands/preset.command.ts +2 -2
- package/src/commands/profile.command.ts +43 -50
- package/src/commands/sync.command.ts +109 -111
- package/src/commands/upgrade.command.ts +85 -78
- package/src/commands/visualize.command.ts +20 -5
- package/src/commands/x.command.ts +55 -50
- package/src/common/format.ts +23 -21
- package/src/common/index.ts +2 -0
- package/src/common/json.ts +8 -5
- package/src/common/layout-folder.ts +96 -111
- package/src/common/paths.ts +14 -12
- package/src/common/record.ts +7 -0
- package/src/common/text.ts +7 -0
- package/src/config/common/constants.ts +13 -1
- package/src/config/common/types.ts +8 -1
- package/src/config/loader.ts +53 -48
- package/src/config/packages.ts +17 -11
- package/src/config/schema.ts +54 -7
- package/src/create/add-app.ts +604 -493
- package/src/create/add-lib.ts +249 -242
- package/src/create/bunfig.ts +26 -23
- package/src/create/checks.ts +36 -34
- package/src/create/common/constants.ts +1 -0
- package/src/create/common/failure.ts +10 -0
- package/src/create/common/index.ts +2 -0
- package/src/create/common/preset-path.ts +11 -0
- package/src/create/common/types.ts +7 -2
- package/src/create/diff.ts +21 -23
- package/src/create/dockerignore.ts +26 -24
- package/src/create/files.ts +7 -5
- package/src/create/init-monorepo.ts +78 -80
- package/src/create/lib-preset.ts +62 -61
- package/src/create/manifest-json.ts +10 -4
- package/src/create/names.ts +217 -210
- package/src/create/next.ts +27 -24
- package/src/create/plan.ts +15 -12
- package/src/create/preset-diff.ts +415 -240
- package/src/create/preset-menu.ts +40 -34
- package/src/create/preset.ts +207 -194
- package/src/create/process.ts +80 -71
- package/src/create/scratch.ts +49 -48
- package/src/create/workspace.ts +423 -398
- package/src/doctor/checks.ts +1069 -998
- package/src/doctor/makefile.ts +17 -13
- package/src/doctor/runner.ts +88 -116
- package/src/doctor/skills.ts +97 -95
- package/src/doctor/tags.ts +44 -41
- package/src/hooks/codex-patch.ts +27 -24
- package/src/hooks/command-view.ts +44 -39
- package/src/hooks/common/constants.ts +0 -3
- package/src/hooks/common/types.ts +15 -1
- package/src/hooks/decision.ts +38 -42
- package/src/hooks/guard-git.ts +52 -50
- package/src/hooks/guard-manifest.ts +58 -55
- package/src/hooks/guard-outside.ts +109 -88
- package/src/hooks/guard-package.ts +86 -77
- package/src/hooks/guard-scripting.ts +20 -15
- package/src/hooks/guard-writes.ts +169 -111
- package/src/hooks/owner-reply.ts +128 -128
- package/src/hooks/post-tool.ts +94 -93
- package/src/hooks/project-guards.ts +93 -55
- package/src/hooks/project-tmp.ts +27 -24
- package/src/hooks/remote-hosts.ts +157 -149
- package/src/hooks/session-digest.ts +99 -95
- package/src/hooks/shell.ts +519 -500
- package/src/hooks/subagent-card.ts +11 -7
- package/src/hooks/trusted-scripts.ts +158 -80
- package/src/init/common/types.ts +1 -1
- package/src/init/scaffold.ts +137 -134
- package/src/local/clean.ts +39 -37
- package/src/local/format.ts +21 -17
- package/src/local/scan.ts +146 -140
- package/src/manifest/render.ts +127 -112
- package/src/owner/card.ts +51 -46
- package/src/owner/profile.ts +100 -96
- package/src/owner/reply-switch.ts +9 -6
- package/src/owner/shape.ts +72 -70
- package/src/owner/survey.ts +175 -164
- package/src/owner/view.ts +62 -59
- package/src/owner/violations.ts +119 -123
- package/src/router.ts +4 -1
- package/src/rules/base.ts +15 -11
- package/src/rules/common/types.ts +1 -1
- package/src/rules/parser.ts +39 -32
- package/src/rules/slots.ts +8 -6
- package/src/signals/claims.ts +30 -28
- package/src/signals/classify.ts +36 -33
- package/src/signals/loop.ts +39 -37
- package/src/signals/state.ts +80 -85
- package/src/skills/frontmatter.ts +28 -28
- package/src/sync/agent-files.ts +217 -199
- package/src/sync/agent-removal.ts +62 -68
- package/src/sync/atlas-block.ts +45 -43
- package/src/sync/base-rules.ts +32 -30
- package/src/sync/claude-launch.ts +74 -37
- package/src/sync/common/constants.ts +4 -0
- package/src/sync/common/index.ts +1 -0
- package/src/sync/common/symlink.ts +9 -0
- package/src/sync/common/types.ts +2 -2
- package/src/sync/exclude.ts +77 -69
- package/src/sync/local-choice.ts +50 -47
- package/src/sync/planner.ts +64 -68
- package/src/sync/prune.ts +52 -48
- package/src/sync/settings.ts +167 -168
- package/src/ui/capability.ts +12 -7
- package/src/ui/keyboard.ts +35 -33
- package/src/ui/prompt.ts +81 -77
- package/src/visualize/assets.ts +379 -195
- package/src/visualize/charts.ts +188 -176
- package/src/visualize/compare-css.ts +31 -0
- package/src/visualize/compare-render.ts +196 -0
- package/src/visualize/compare-schema.ts +81 -0
- package/src/visualize/compare-validate.ts +126 -0
- package/src/visualize/constants.ts +29 -3
- package/src/visualize/diagrams.ts +189 -174
- package/src/visualize/gate.ts +136 -0
- package/src/visualize/grid-span.ts +34 -0
- package/src/visualize/icons.ts +9 -4
- package/src/visualize/index.ts +2 -0
- package/src/visualize/kinds-css.ts +54 -0
- package/src/visualize/kinds-render.ts +698 -0
- package/src/visualize/kinds-schema.ts +148 -0
- package/src/visualize/kinds-validate.ts +186 -0
- package/src/visualize/labels-vi.ts +109 -0
- package/src/visualize/labels.ts +53 -0
- package/src/visualize/layout.ts +112 -92
- package/src/visualize/page.ts +140 -114
- package/src/visualize/render.ts +158 -114
- package/src/visualize/schema.ts +21 -1
- package/src/visualize/sections.ts +401 -309
- package/src/visualize/sources.ts +270 -0
- package/src/visualize/theme.ts +474 -0
- package/src/visualize/validate.ts +15 -5
- package/src/wiki/anchors.ts +39 -37
- package/src/wiki/command.ts +4 -4
- package/src/wiki/source-links.ts +49 -49
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
7
|
/** A folder, or a list of folders, as the layout holds it; a string stays valid. */
|
|
8
|
-
|
|
8
|
+
type TLayoutValue = string | string[];
|
|
9
9
|
|
|
10
10
|
export interface ILayout {
|
|
11
11
|
backend?: TLayoutValue;
|
|
@@ -15,7 +15,7 @@ export interface ILayout {
|
|
|
15
15
|
other?: TLayoutValue;
|
|
16
16
|
}
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
class LayoutFolderLimits {
|
|
19
19
|
/** `auroras/apps` is two segments. */
|
|
20
20
|
static readonly MAX_SEGMENTS = 4;
|
|
21
21
|
/** One segment: the pattern a layout folder had before it could have several. */
|
|
@@ -38,140 +38,125 @@ export class LayoutKeys {
|
|
|
38
38
|
}
|
|
39
39
|
}
|
|
40
40
|
|
|
41
|
-
/**
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
if (typeof folder !== 'string' || folder === '') {
|
|
46
|
-
return 'a folder is a non-empty string';
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
if (folder.includes('\\')) {
|
|
50
|
-
return `'${folder}' has a backslash: a folder is written with '/'`;
|
|
51
|
-
}
|
|
41
|
+
/** Whether `inner` is `outer` or sits below it. */
|
|
42
|
+
const isWithin = (opts: { inner: string; outer: string }): boolean =>
|
|
43
|
+
opts.inner === opts.outer || opts.inner.startsWith(`${opts.outer}/`);
|
|
52
44
|
|
|
53
|
-
|
|
54
|
-
|
|
45
|
+
export class LayoutFolder {
|
|
46
|
+
private static entriesOf(opts: { layout: ILayout }): { key: string; folder: string }[] {
|
|
47
|
+
return LayoutKeys.ALL.flatMap((key) =>
|
|
48
|
+
LayoutFolder.layoutFoldersOf({ value: opts.layout[key] }).map((folder) => ({ key, folder })),
|
|
49
|
+
);
|
|
55
50
|
}
|
|
56
51
|
|
|
57
|
-
|
|
52
|
+
/** Why a layout folder is not one, or undefined when it is: 1 to 4 segments, each a plain lower-case name. */
|
|
53
|
+
static layoutFolderProblem(opts: { folder: unknown }): string | undefined {
|
|
54
|
+
const { folder } = opts;
|
|
58
55
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
for (const segment of segments) {
|
|
64
|
-
if (segment === '') {
|
|
65
|
-
return `'${folder}' has an empty segment`;
|
|
56
|
+
if (typeof folder !== 'string' || folder === '') {
|
|
57
|
+
return 'a folder is a non-empty string';
|
|
66
58
|
}
|
|
67
59
|
|
|
68
|
-
if (
|
|
69
|
-
return `'${folder}'
|
|
60
|
+
if (folder.includes('\\')) {
|
|
61
|
+
return `'${folder}' has a backslash: a folder is written with '/'`;
|
|
70
62
|
}
|
|
71
63
|
|
|
72
|
-
if (
|
|
73
|
-
return `'${folder}'
|
|
64
|
+
if (folder.startsWith('/') || folder.endsWith('/')) {
|
|
65
|
+
return `'${folder}' starts or ends with '/': a folder is a path from the project root`;
|
|
74
66
|
}
|
|
75
67
|
|
|
76
|
-
|
|
77
|
-
|
|
68
|
+
const segments = folder.split('/');
|
|
69
|
+
|
|
70
|
+
if (segments.length > LayoutFolderLimits.MAX_SEGMENTS) {
|
|
71
|
+
return `'${folder}' has more than ${LayoutFolderLimits.MAX_SEGMENTS} segments`;
|
|
78
72
|
}
|
|
79
|
-
}
|
|
80
73
|
|
|
81
|
-
|
|
82
|
-
|
|
74
|
+
for (const segment of segments) {
|
|
75
|
+
if (segment === '') {
|
|
76
|
+
return `'${folder}' has an empty segment`;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (segment === '..' || segment === '.') {
|
|
80
|
+
return `'${folder}' climbs or repeats a folder ('${segment}')`;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
if (LayoutFolderLimits.FORBIDDEN_SEGMENTS.has(segment)) {
|
|
84
|
+
return `'${folder}' goes through '${segment}'`;
|
|
85
|
+
}
|
|
83
86
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
+
if (!LayoutFolderLimits.SEGMENT_PATTERN.test(segment)) {
|
|
88
|
+
return `'${folder}' has the segment '${segment}': lowercase letters, digits and '-', starting with a letter or digit`;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
87
91
|
|
|
88
|
-
|
|
89
|
-
return [value];
|
|
92
|
+
return undefined;
|
|
90
93
|
}
|
|
91
94
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
};
|
|
95
|
+
/** The folders a layout value names, in order: a string is one, a list is its strings. Nothing is validated. */
|
|
96
|
+
static layoutFoldersOf(opts: { value: unknown }): string[] {
|
|
97
|
+
const { value } = opts;
|
|
96
98
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
99
|
+
if (typeof value === 'string') {
|
|
100
|
+
return [value];
|
|
101
|
+
}
|
|
100
102
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
/** A folder listed twice or under two keys, and a folder inside another: a package path must belong to exactly one folder. */
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
103
|
+
return Array.isArray(value)
|
|
104
|
+
? value.filter((entry): entry is string => typeof entry === 'string')
|
|
105
|
+
: [];
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** A folder listed twice or under two keys, and a folder inside another: a package path must belong to exactly one folder. */
|
|
109
|
+
static layoutOverlapProblems(opts: { layout: ILayout }): string[] {
|
|
110
|
+
const entries = LayoutFolder.entriesOf({ layout: opts.layout }).filter(
|
|
111
|
+
(entry) => LayoutFolder.layoutFolderProblem({ folder: entry.folder }) === undefined,
|
|
112
|
+
);
|
|
113
|
+
const problems: string[] = [];
|
|
114
|
+
|
|
115
|
+
for (const [index, entry] of entries.entries()) {
|
|
116
|
+
for (const other of entries.slice(index + 1)) {
|
|
117
|
+
if (entry.folder === other.folder) {
|
|
118
|
+
problems.push(
|
|
119
|
+
`layout.${other.key} names '${other.folder}' again (also layout.${entry.key}): a folder belongs to one kind of code`,
|
|
120
|
+
);
|
|
121
|
+
} else if (
|
|
122
|
+
isWithin({ inner: entry.folder, outer: other.folder }) ||
|
|
123
|
+
isWithin({ inner: other.folder, outer: entry.folder })
|
|
124
|
+
) {
|
|
125
|
+
problems.push(
|
|
126
|
+
`layout.${entry.key} '${entry.folder}' and layout.${other.key} '${other.folder}' are nested: a package path must belong to exactly one folder`,
|
|
127
|
+
);
|
|
128
|
+
}
|
|
126
129
|
}
|
|
127
130
|
}
|
|
131
|
+
|
|
132
|
+
return problems;
|
|
128
133
|
}
|
|
129
134
|
|
|
130
|
-
|
|
131
|
-
}
|
|
135
|
+
/** The layout value with `folder` in it: unchanged when it is there already, a string that grows into a list otherwise. */
|
|
136
|
+
static withLayoutFolder(opts: { value: TLayoutValue | undefined; folder: string }): TLayoutValue {
|
|
137
|
+
const folders = LayoutFolder.layoutFoldersOf({ value: opts.value });
|
|
132
138
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
const problem = layoutFolderProblem({ folder: entry.folder });
|
|
139
|
+
if (folders.includes(opts.folder)) {
|
|
140
|
+
return opts.value ?? opts.folder;
|
|
141
|
+
}
|
|
137
142
|
|
|
138
|
-
return
|
|
139
|
-
}
|
|
140
|
-
...layoutOverlapProblems({ layout: opts.layout }),
|
|
141
|
-
];
|
|
143
|
+
return folders.length === 0 ? opts.folder : [...folders, opts.folder];
|
|
144
|
+
}
|
|
142
145
|
|
|
143
|
-
/** The
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
146
|
+
/** The valid folders of a layout value; a manifest is read through this, never trusted. */
|
|
147
|
+
static valid(opts: { value: unknown }): string[] {
|
|
148
|
+
return LayoutFolder.layoutFoldersOf({ value: opts.value }).filter(
|
|
149
|
+
(folder) => LayoutFolder.layoutFolderProblem({ folder }) === undefined,
|
|
150
|
+
);
|
|
151
|
+
}
|
|
149
152
|
|
|
150
|
-
|
|
151
|
-
|
|
153
|
+
/** The folders as a sentence part: `'a'`, or `'a', 'b'`. */
|
|
154
|
+
static describe(opts: { folders: string[] }): string {
|
|
155
|
+
return opts.folders.map((folder) => `'${folder}'`).join(', ');
|
|
152
156
|
}
|
|
153
157
|
|
|
154
|
-
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
LayoutKeys.ALL.find((key) =>
|
|
160
|
-
layoutFoldersOf({ value: opts.layout[key] }).some(
|
|
161
|
-
(folder) => folder === opts.folder && layoutFolderProblem({ folder }) === undefined,
|
|
162
|
-
),
|
|
163
|
-
);
|
|
164
|
-
|
|
165
|
-
/** The valid folders of a layout value; a manifest is read through this, never trusted. */
|
|
166
|
-
export const validLayoutFolders = (opts: { value: unknown }): string[] =>
|
|
167
|
-
layoutFoldersOf({ value: opts.value }).filter(
|
|
168
|
-
(folder) => layoutFolderProblem({ folder }) === undefined,
|
|
169
|
-
);
|
|
170
|
-
|
|
171
|
-
/** The folders as a sentence part: `'a'`, or `'a', 'b'`. */
|
|
172
|
-
export const describeFolders = (opts: { folders: string[] }): string =>
|
|
173
|
-
opts.folders.map((folder) => `'${folder}'`).join(', ');
|
|
174
|
-
|
|
175
|
-
/** What an error says when a flag must pick among several listed folders. */
|
|
176
|
-
export const listedFoldersNote = (opts: { folders: string[] }): string =>
|
|
177
|
-
`the layout lists ${describeFolders({ folders: opts.folders })}`;
|
|
158
|
+
/** What an error says when a flag must pick among several listed folders. */
|
|
159
|
+
static listedNote(opts: { folders: string[] }): string {
|
|
160
|
+
return `the layout lists ${LayoutFolder.describe({ folders: opts.folders })}`;
|
|
161
|
+
}
|
|
162
|
+
}
|
package/src/common/paths.ts
CHANGED
|
@@ -9,19 +9,21 @@ export const BASE_DIRECTORY = join(PACKAGE_ROOT, 'base');
|
|
|
9
9
|
|
|
10
10
|
export const PACKAGE_NAME = '@venizia/vulcan';
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
12
|
+
export class BaseDirectory {
|
|
13
|
+
/**
|
|
14
|
+
* The base as a project reaches it: through `node_modules/@venizia/vulcan` when that resolves to this
|
|
15
|
+
* package. bun's isolated install keeps the files in a hashed store directory that every upgrade
|
|
16
|
+
* replaces, so a link to the real path dies with the next upgrade; the stable path does not.
|
|
17
|
+
* Anywhere else - no install, or another copy installed - the real directory.
|
|
18
|
+
*/
|
|
19
|
+
static stableOf(opts: { root: string }): string {
|
|
20
|
+
const installed = join(opts.root, 'node_modules', PACKAGE_NAME, 'base');
|
|
20
21
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
}
|
|
22
|
+
return existsSync(installed) && realpathSync(installed) === realpathSync(BASE_DIRECTORY)
|
|
23
|
+
? installed
|
|
24
|
+
: BASE_DIRECTORY;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
25
27
|
|
|
26
28
|
export const VULCAN_VERSION: string = JSON.parse(
|
|
27
29
|
readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'),
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** The one answer to "is this parsed JSON or YAML a plain object": not an array, not null. */
|
|
2
|
+
export class RecordValue {
|
|
3
|
+
/** Takes the value itself, not an options object: a type predicate narrows only a parameter, and callers read `value.key` afterwards. */
|
|
4
|
+
static isRecord(value: unknown): value is Record<string, unknown> {
|
|
5
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
6
|
+
}
|
|
7
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Text helpers that more than one folder of the CLI needs. */
|
|
2
|
+
export class TextValue {
|
|
3
|
+
/** `text` as a regular expression that matches exactly itself. */
|
|
4
|
+
static escapeLiteral(opts: { text: string }): string {
|
|
5
|
+
return opts.text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
6
|
+
}
|
|
7
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/** What a package of the project is: an app, or a
|
|
1
|
+
/** What a package of the project is: an app, or a library other apps import. */
|
|
2
2
|
export class PackageKinds {
|
|
3
3
|
static readonly APP = 'app';
|
|
4
4
|
static readonly LIB = 'lib';
|
|
@@ -10,6 +10,18 @@ export class PackageKinds {
|
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
+
/** Which preset kind made a library: `lib` (may use the project's framework) or `shared` (depends on no framework). */
|
|
14
|
+
export class LibraryKinds {
|
|
15
|
+
static readonly LIB = 'lib';
|
|
16
|
+
static readonly SHARED = 'shared';
|
|
17
|
+
|
|
18
|
+
static readonly SCHEME_SET = new Set<string>([this.LIB, this.SHARED]);
|
|
19
|
+
|
|
20
|
+
static isValid(value: string): boolean {
|
|
21
|
+
return this.SCHEME_SET.has(value);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
13
25
|
/** Config file extensions, in lookup order. */
|
|
14
26
|
export class ConfigExtensions {
|
|
15
27
|
static readonly TS = 'ts';
|
|
@@ -1,7 +1,14 @@
|
|
|
1
1
|
import type { TConstValue } from '../../common/index.ts';
|
|
2
|
-
import type {
|
|
2
|
+
import type {
|
|
3
|
+
CodingAgents,
|
|
4
|
+
ConfigExtensions,
|
|
5
|
+
HookEvents,
|
|
6
|
+
LibraryKinds,
|
|
7
|
+
PackageKinds,
|
|
8
|
+
} from './constants.ts';
|
|
3
9
|
|
|
4
10
|
export type TConfigExtension = TConstValue<typeof ConfigExtensions>;
|
|
5
11
|
export type TCodingAgent = TConstValue<typeof CodingAgents>;
|
|
6
12
|
export type THookEvent = TConstValue<typeof HookEvents>;
|
|
7
13
|
export type TPackageKind = TConstValue<typeof PackageKinds>;
|
|
14
|
+
export type TLibraryKind = TConstValue<typeof LibraryKinds>;
|
package/src/config/loader.ts
CHANGED
|
@@ -5,70 +5,75 @@ import { ConfigConstants, ConfigExtensions } from './common/index.ts';
|
|
|
5
5
|
import { VULCAN_CONFIG_SCHEMA } from './schema.ts';
|
|
6
6
|
import type { TResolvedConfig } from './schema.ts';
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
type TLoadResult =
|
|
9
9
|
| { ok: true; file: string; config: TResolvedConfig }
|
|
10
10
|
| { ok: false; file?: string; error: string };
|
|
11
11
|
|
|
12
12
|
const describeError = (opts: { error: unknown }): string =>
|
|
13
13
|
opts.error instanceof Error ? opts.error.message : String(opts.error);
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
15
|
+
export class ConfigLoader {
|
|
16
|
+
/** Every `.configs/vulcan.config.<ext>` present, in lookup order. */
|
|
17
|
+
static findFiles(opts: { root: string }): string[] {
|
|
18
|
+
return ConfigExtensions.LOOKUP_ORDER.map((extension) =>
|
|
19
|
+
join(opts.root, ConfigConstants.DIRECTORY, `${ConfigConstants.BASENAME}.${extension}`),
|
|
20
|
+
).filter((file) => existsSync(file));
|
|
21
|
+
}
|
|
20
22
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
+
static async load(opts: { root: string }): Promise<TLoadResult> {
|
|
24
|
+
const files = ConfigLoader.findFiles({ root: opts.root });
|
|
23
25
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
if (files.length === 0) {
|
|
27
|
+
return {
|
|
28
|
+
ok: false,
|
|
29
|
+
error: `no ${ConfigConstants.DIRECTORY}/${ConfigConstants.BASENAME}.* found in ${opts.root}`,
|
|
30
|
+
};
|
|
31
|
+
}
|
|
30
32
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
+
if (files.length > 1) {
|
|
34
|
+
const names = files.map((file) => relative(opts.root, file)).join(', ');
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
+
return { ok: false, error: `more than one config - keep exactly one of: ${names}` };
|
|
37
|
+
}
|
|
36
38
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
+
const [file] = files;
|
|
40
|
+
const shown = relative(opts.root, file);
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
let loaded: { default?: unknown };
|
|
41
43
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
} catch (error) {
|
|
45
|
-
return { ok: false, file, error: `${shown}: failed to load - ${describeError({ error })}` };
|
|
46
|
-
}
|
|
44
|
+
try {
|
|
45
|
+
const imported = await import(pathToFileURL(file).href);
|
|
47
46
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
ok: false,
|
|
51
|
-
|
|
52
|
-
error: `${shown}: no default export - write 'export default { ... }'`,
|
|
53
|
-
};
|
|
54
|
-
}
|
|
47
|
+
loaded = imported;
|
|
48
|
+
} catch (error) {
|
|
49
|
+
return { ok: false, file, error: `${shown}: failed to load - ${describeError({ error })}` };
|
|
50
|
+
}
|
|
55
51
|
|
|
56
|
-
|
|
52
|
+
if (loaded.default === undefined) {
|
|
53
|
+
return {
|
|
54
|
+
ok: false,
|
|
55
|
+
file,
|
|
56
|
+
error: `${shown}: no default export - write 'export default { ... }'`,
|
|
57
|
+
};
|
|
58
|
+
}
|
|
57
59
|
|
|
58
|
-
|
|
59
|
-
const issues = parsed.error.issues
|
|
60
|
-
.map((issue) => {
|
|
61
|
-
const path =
|
|
62
|
-
issue.code === 'unrecognized_keys'
|
|
63
|
-
? issue.keys.join(', ')
|
|
64
|
-
: issue.path.join('.') || '(root)';
|
|
60
|
+
const parsed = VULCAN_CONFIG_SCHEMA.safeParse(loaded.default);
|
|
65
61
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
62
|
+
if (!parsed.success) {
|
|
63
|
+
const issues = parsed.error.issues
|
|
64
|
+
.map((issue) => {
|
|
65
|
+
const path =
|
|
66
|
+
issue.code === 'unrecognized_keys'
|
|
67
|
+
? issue.keys.join(', ')
|
|
68
|
+
: issue.path.join('.') || '(root)';
|
|
69
69
|
|
|
70
|
-
|
|
71
|
-
|
|
70
|
+
return ` ${path}: ${issue.message}`;
|
|
71
|
+
})
|
|
72
|
+
.join('\n');
|
|
72
73
|
|
|
73
|
-
|
|
74
|
-
}
|
|
74
|
+
return { ok: false, file, error: `${shown}: invalid config\n${issues}` };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
return { ok: true, file, config: parsed.data };
|
|
78
|
+
}
|
|
79
|
+
}
|
package/src/config/packages.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { TPackageKind } from './common/index.ts';
|
|
1
|
+
import type { TLibraryKind, TPackageKind } from './common/index.ts';
|
|
2
2
|
import type { TResolvedConfig } from './schema.ts';
|
|
3
3
|
|
|
4
4
|
const DEFAULT_PACKAGES_DIRECTORY = 'packages';
|
|
@@ -11,15 +11,21 @@ export interface IProjectPackage {
|
|
|
11
11
|
aliases: string[];
|
|
12
12
|
retired: boolean;
|
|
13
13
|
kind?: TPackageKind;
|
|
14
|
+
/** Which preset kind made a library; absent means `lib`. */
|
|
15
|
+
presetKind?: TLibraryKind;
|
|
14
16
|
}
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
opts
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
18
|
+
export class ProjectPackages {
|
|
19
|
+
/** The project's packages in release order. */
|
|
20
|
+
static resolve(opts: { config: TResolvedConfig }): IProjectPackage[] {
|
|
21
|
+
return opts.config.packages.map((entry) => ({
|
|
22
|
+
dir: entry.dir,
|
|
23
|
+
name: entry.name,
|
|
24
|
+
path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
|
|
25
|
+
aliases: entry.aliases,
|
|
26
|
+
retired: entry.retired,
|
|
27
|
+
...(entry.kind === undefined ? {} : { kind: entry.kind }),
|
|
28
|
+
...(entry.presetKind === undefined ? {} : { presetKind: entry.presetKind }),
|
|
29
|
+
}));
|
|
30
|
+
}
|
|
31
|
+
}
|
package/src/config/schema.ts
CHANGED
|
@@ -1,8 +1,14 @@
|
|
|
1
1
|
import { isAbsolute } from 'node:path';
|
|
2
2
|
import { z } from 'zod';
|
|
3
|
-
import {
|
|
3
|
+
import { LayoutFolder } from '../common/layout-folder.ts';
|
|
4
4
|
import { OWNER_SCHEMA } from '../owner/schema.ts';
|
|
5
|
-
import {
|
|
5
|
+
import {
|
|
6
|
+
CodingAgents,
|
|
7
|
+
ConfigConstants,
|
|
8
|
+
HookEvents,
|
|
9
|
+
LibraryKinds,
|
|
10
|
+
PackageKinds,
|
|
11
|
+
} from './common/index.ts';
|
|
6
12
|
|
|
7
13
|
const CODING_AGENT = z.string().refine((value) => CodingAgents.isValid(value), {
|
|
8
14
|
message: `one of: ${[...CodingAgents.SCHEME_SET].join(', ')}`,
|
|
@@ -48,7 +54,7 @@ const PUSH_TARGET = z
|
|
|
48
54
|
|
|
49
55
|
/** A layout folder: 1 to 4 plain segments, never climbing, never absolute (the validator `guard-package` shares). */
|
|
50
56
|
const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
|
|
51
|
-
const problem = layoutFolderProblem({ folder: value });
|
|
57
|
+
const problem = LayoutFolder.layoutFolderProblem({ folder: value });
|
|
52
58
|
|
|
53
59
|
if (problem !== undefined) {
|
|
54
60
|
context.addIssue({ code: 'custom', message: problem });
|
|
@@ -56,7 +62,7 @@ const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
|
|
|
56
62
|
});
|
|
57
63
|
|
|
58
64
|
/** A script `guard-writes` may trust: a repo-relative `.ts` path - no glob, no `~`, never climbing out of the repo. */
|
|
59
|
-
const
|
|
65
|
+
const TRUSTED_SCRIPT_PATH = z.string().superRefine((value, context) => {
|
|
60
66
|
const problem = /[*?[\]{}!]/.test(value)
|
|
61
67
|
? 'no globs: list each script by its exact path'
|
|
62
68
|
: isAbsolute(value) || value.startsWith('~')
|
|
@@ -72,6 +78,22 @@ const TRUSTED_SCRIPT = z.string().superRefine((value, context) => {
|
|
|
72
78
|
}
|
|
73
79
|
});
|
|
74
80
|
|
|
81
|
+
/**
|
|
82
|
+
* A trusted script, whole or by subcommand: a path trusts the whole file; an object trusts only the calls
|
|
83
|
+
* whose first argument after the script is one of `readOnly` (one word each, matched exactly).
|
|
84
|
+
*/
|
|
85
|
+
const READ_ONLY_WORD = z
|
|
86
|
+
.string()
|
|
87
|
+
.regex(
|
|
88
|
+
/^[A-Za-z0-9_.:-]+$/,
|
|
89
|
+
'one plain word: letters, digits and _ . : - only, no spaces or globs',
|
|
90
|
+
);
|
|
91
|
+
|
|
92
|
+
const TRUSTED_SCRIPT = z.union([
|
|
93
|
+
TRUSTED_SCRIPT_PATH,
|
|
94
|
+
z.strictObject({ script: TRUSTED_SCRIPT_PATH, readOnly: z.array(READ_ONLY_WORD).min(1) }),
|
|
95
|
+
]);
|
|
96
|
+
|
|
75
97
|
/** One folder, or a list of them: a side whose apps are grouped keeps each group's folder. */
|
|
76
98
|
const LAYOUT_VALUE = z.union([LAYOUT_FOLDER, z.array(LAYOUT_FOLDER).min(1)]);
|
|
77
99
|
|
|
@@ -82,8 +104,10 @@ const PROJECT_PACKAGE = z.strictObject({
|
|
|
82
104
|
path: z.string().optional(),
|
|
83
105
|
aliases: z.array(z.string()).default([]),
|
|
84
106
|
retired: z.boolean().default(false),
|
|
85
|
-
/** A
|
|
107
|
+
/** A library a preset made lives anywhere a workspace glob covers; absent means an app or a plain package. */
|
|
86
108
|
kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
|
|
109
|
+
/** Which preset kind made a library; absent means the `lib` kind. */
|
|
110
|
+
presetKind: z.enum([LibraryKinds.LIB, LibraryKinds.SHARED]).optional(),
|
|
87
111
|
});
|
|
88
112
|
|
|
89
113
|
/** A path as a key: no leading `./`, no trailing slash. */
|
|
@@ -188,7 +212,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
188
212
|
other: LAYOUT_VALUE.optional(),
|
|
189
213
|
})
|
|
190
214
|
.superRefine((layout, context) => {
|
|
191
|
-
for (const problem of layoutOverlapProblems({ layout })) {
|
|
215
|
+
for (const problem of LayoutFolder.layoutOverlapProblems({ layout })) {
|
|
192
216
|
context.addIssue({ code: 'custom', message: problem });
|
|
193
217
|
}
|
|
194
218
|
})
|
|
@@ -202,6 +226,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
202
226
|
summary: z.string(),
|
|
203
227
|
/** The summary of the preset's lib kind, when it ships one. */
|
|
204
228
|
lib: z.string().optional(),
|
|
229
|
+
/** The summary of the preset's shared kind, when it ships one. */
|
|
230
|
+
shared: z.string().optional(),
|
|
205
231
|
}),
|
|
206
232
|
)
|
|
207
233
|
.optional(),
|
|
@@ -320,6 +346,25 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
320
346
|
localFile: z.string().default('.agents/hooks/trusted-hosts.local'),
|
|
321
347
|
})
|
|
322
348
|
.optional(),
|
|
349
|
+
/**
|
|
350
|
+
* The colour the project is known by: `vulcan visualize` takes the accent of its pages from here (the spec's own
|
|
351
|
+
* `accent` wins). `accent` is the colour for marks and fills; `accentDark` is the same on dark grounds (derived
|
|
352
|
+
* when absent); `accentText` is a darker accent for text, when `accent` is too light to be read as text.
|
|
353
|
+
* `vulcan sync` copies it to the manifest, where the generator reads it.
|
|
354
|
+
*/
|
|
355
|
+
theme: z
|
|
356
|
+
.strictObject({
|
|
357
|
+
accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #8a5a20'),
|
|
358
|
+
accentDark: z
|
|
359
|
+
.string()
|
|
360
|
+
.regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #dead6a')
|
|
361
|
+
.optional(),
|
|
362
|
+
accentText: z
|
|
363
|
+
.string()
|
|
364
|
+
.regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #01579b')
|
|
365
|
+
.optional(),
|
|
366
|
+
})
|
|
367
|
+
.optional(),
|
|
323
368
|
/** Team-shared Claude settings (permissions, env, enabledPlugins...), merged by sync over personal keys. */
|
|
324
369
|
claude: z
|
|
325
370
|
.strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
|
|
@@ -344,7 +389,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
344
389
|
* runtime dir for locks, git config, the agent tool's memory) with stores a tool in this project
|
|
345
390
|
* manages itself: absolute globs, `~` and `$NAME` allowed. `writes.trustedScripts` lists the project's own
|
|
346
391
|
* CLIs (repo-relative `.ts` paths, no globs) whose body guard-writes does not read for mutating calls
|
|
347
|
-
* while git tracks them and they equal HEAD; the command line is still checked.
|
|
392
|
+
* while git tracks them and they equal HEAD; the command line is still checked. An entry may instead be
|
|
393
|
+
* `{ script, readOnly: ['plan'] }`: only a call whose first argument after the script is listed skips the
|
|
394
|
+
* read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
|
|
348
395
|
* project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
|
|
349
396
|
* compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
|
|
350
397
|
* writes both to the manifest, where the hooks read them.
|