@venizia/vulcan 0.3.13 → 0.4.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/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +75 -3
- package/base/hooks/guard-git.ts +55 -0
- package/base/hooks/guard-manifest.ts +1 -1
- package/base/hooks/guard-outside.ts +66 -0
- package/base/hooks/guard-package.ts +3 -2
- package/base/hooks/guard-remote-hosts.ts +3 -2
- package/base/hooks/guard-writes.ts +1 -1
- package/base/hooks/post-tool.ts +36 -0
- package/base/hooks/prompt-submit.ts +52 -0
- package/base/hooks/stop.ts +38 -0
- package/base/hooks/subagent-start.ts +18 -0
- package/base/references/delegation-brief.md +63 -0
- package/base/references/design-pass.md +39 -0
- package/base/references/evidence.md +36 -0
- package/base/references/phase-boundaries.md +20 -0
- package/base/references/testing.md +89 -0
- package/base/rules.md +11 -2
- package/base/skills/build-a-feature/SKILL.md +49 -23
- package/base/skills/docs-update/SKILL.md +12 -1
- package/base/skills/docs-writing/SKILL.md +2 -2
- package/base/skills/docs-writing/references/agent-documents.md +53 -0
- package/base/skills/fix-a-bug/SKILL.md +84 -0
- package/base/skills/fix-a-bug/evals/evals.json +17 -0
- package/base/skills/knowledge-sync/SKILL.md +4 -1
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
- package/base/skills/plan-a-change/SKILL.md +95 -0
- package/base/skills/plan-a-change/evals/evals.json +23 -0
- package/base/skills/plan-a-change/references/spec-card.md +39 -0
- package/base/skills/report-back/SKILL.md +112 -0
- package/base/skills/report-back/evals/evals.json +23 -0
- package/base/skills/research/SKILL.md +64 -0
- package/base/skills/research/evals/evals.json +17 -0
- package/base/skills/retro/SKILL.md +69 -0
- package/base/skills/retro/evals/evals.json +17 -0
- package/base/skills/review-a-change/SKILL.md +90 -0
- package/base/skills/review-a-change/evals/evals.json +17 -0
- package/base/skills/ship/SKILL.md +82 -0
- package/base/skills/ship/evals/evals.json +23 -0
- package/base/skills/visualize-work/SKILL.md +87 -0
- package/base/skills/visualize-work/evals/evals.json +17 -0
- package/base/skills/visualize-work/references/spec.md +65 -0
- package/package.json +4 -4
- package/src/agents/common/schema.ts +2 -2
- package/src/agents/detect.ts +5 -5
- package/src/agents/exclude.ts +3 -3
- package/src/agents/local.ts +1 -1
- package/src/agents/prompt.ts +2 -2
- package/src/agents/render.ts +2 -2
- package/src/agents/resolve.ts +6 -6
- package/src/agents/table.ts +1 -1
- package/src/commands/agents.command.ts +4 -4
- package/src/commands/clean.command.ts +72 -0
- package/src/commands/help.command.ts +11 -0
- package/src/commands/index.ts +6 -0
- package/src/commands/init.command.ts +4 -1
- package/src/commands/profile.command.ts +255 -0
- package/src/commands/sync.command.ts +6 -4
- package/src/commands/upgrade.command.ts +1 -1
- package/src/commands/visualize.command.ts +107 -0
- package/src/common/constants.ts +23 -0
- package/src/config/common/constants.ts +2 -0
- package/src/config/loader.ts +4 -4
- package/src/config/packages.ts +1 -1
- package/src/config/schema.ts +16 -5
- package/src/create/add-app.ts +15 -15
- package/src/create/add-lib.ts +7 -7
- package/src/create/bunfig.ts +1 -1
- package/src/create/dockerignore.ts +4 -4
- package/src/create/init-monorepo.ts +3 -1
- package/src/create/lib-preset.ts +1 -1
- package/src/create/names.ts +7 -6
- package/src/create/next.ts +4 -4
- package/src/create/preset-menu.ts +4 -4
- package/src/create/preset.ts +3 -3
- package/src/create/scratch.ts +27 -6
- package/src/create/workspace.ts +11 -11
- package/src/doctor/checks.ts +231 -45
- package/src/doctor/common/constants.ts +4 -0
- package/src/doctor/makefile.ts +3 -3
- package/src/doctor/runner.ts +16 -1
- package/src/doctor/skills.ts +8 -8
- package/src/doctor/tags.ts +5 -5
- package/src/hooks/common/constants.ts +29 -0
- package/src/hooks/common/types.ts +20 -0
- package/src/hooks/decision.ts +15 -0
- package/src/hooks/guard-git.ts +288 -0
- package/src/hooks/guard-manifest.ts +1 -1
- package/src/hooks/guard-outside.ts +399 -0
- package/src/hooks/guard-package.ts +4 -4
- package/src/hooks/guard-writes.ts +5 -5
- package/src/hooks/index.ts +6 -0
- package/src/hooks/owner-reply.ts +148 -0
- package/src/hooks/post-tool.ts +137 -0
- package/src/hooks/remote-hosts.ts +25 -23
- package/src/hooks/session-digest.ts +24 -4
- package/src/hooks/shell.ts +325 -0
- package/src/hooks/subagent-card.ts +32 -0
- package/src/init/scaffold.ts +6 -6
- package/src/local/clean.ts +88 -0
- package/src/local/constants.ts +50 -0
- package/src/local/format.ts +25 -0
- package/src/local/index.ts +4 -0
- package/src/local/scan.ts +368 -0
- package/src/manifest/render.ts +1 -1
- package/src/owner/card.ts +85 -0
- package/src/owner/constants.ts +105 -0
- package/src/owner/index.ts +8 -0
- package/src/owner/profile.ts +123 -0
- package/src/owner/schema.ts +147 -0
- package/src/owner/shape.ts +380 -0
- package/src/owner/survey.ts +289 -0
- package/src/owner/view.ts +76 -0
- package/src/owner/violations.ts +202 -0
- package/src/router.ts +18 -1
- package/src/rules/base.ts +1 -1
- package/src/rules/parser.ts +5 -5
- package/src/signals/claims.ts +71 -0
- package/src/signals/classify.ts +132 -0
- package/src/signals/constants.ts +88 -0
- package/src/signals/index.ts +5 -0
- package/src/signals/loop.ts +46 -0
- package/src/signals/state.ts +276 -0
- package/src/sync/agent-files.ts +4 -4
- package/src/sync/agent-removal.ts +6 -6
- package/src/sync/atlas-block.ts +1 -1
- package/src/sync/base-rules.ts +1 -1
- package/src/sync/exclude.ts +9 -9
- package/src/sync/local-choice.ts +35 -5
- package/src/sync/planner.ts +16 -16
- package/src/sync/prune.ts +3 -3
- package/src/sync/settings.ts +15 -15
- package/src/ui/prompt.ts +3 -3
- package/src/visualize/assets.ts +80 -0
- package/src/visualize/constants.ts +126 -0
- package/src/visualize/index.ts +6 -0
- package/src/visualize/layout.ts +107 -0
- package/src/visualize/page.ts +211 -0
- package/src/visualize/render.ts +161 -0
- package/src/visualize/schema.ts +178 -0
- package/src/visualize/validate.ts +127 -0
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
import { existsSync, lstatSync, rmSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { ExitCodes } from '../common/index.ts';
|
|
4
|
+
import type { ICommandContext } from '../common/index.ts';
|
|
5
|
+
import { askWithPrompt } from '../create/names.ts';
|
|
6
|
+
import {
|
|
7
|
+
linkedAt,
|
|
8
|
+
OwnerConstants,
|
|
9
|
+
profileIsIgnored,
|
|
10
|
+
readProfile,
|
|
11
|
+
renderProfile,
|
|
12
|
+
runSurvey,
|
|
13
|
+
systemLanguageOf,
|
|
14
|
+
writeProfile,
|
|
15
|
+
} from '../owner/index.ts';
|
|
16
|
+
import type { ISurveyIo } from '../owner/index.ts';
|
|
17
|
+
import { menusAvailable, promptConfirm, promptSelect, promptText } from '../ui/index.ts';
|
|
18
|
+
|
|
19
|
+
const YES_FLAG = '--yes';
|
|
20
|
+
|
|
21
|
+
/** The form in a terminal that can draw menus. */
|
|
22
|
+
const menuIo: ISurveyIo = {
|
|
23
|
+
// An empty entry takes the default, so only what was typed is checked.
|
|
24
|
+
text: (opts) =>
|
|
25
|
+
promptText({
|
|
26
|
+
...opts,
|
|
27
|
+
validate: (value) => (value === '' ? undefined : opts.validate?.(value)),
|
|
28
|
+
}),
|
|
29
|
+
select: (opts) => promptSelect(opts),
|
|
30
|
+
confirm: (opts) => promptConfirm(opts),
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
/** The same questions as plain lines, for a pipe, a log or `TERM=dumb`: an empty line takes the default, the end of the input cancels. */
|
|
34
|
+
const lineIo: ISurveyIo = {
|
|
35
|
+
text: async (opts) => {
|
|
36
|
+
const answer = askWithPrompt({
|
|
37
|
+
question: opts.message,
|
|
38
|
+
...(opts.defaultValue === '' ? {} : { previous: opts.defaultValue }),
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
if (answer === null) {
|
|
42
|
+
return null;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const value = answer.trim() === '' ? opts.defaultValue : answer.trim();
|
|
46
|
+
const problem = opts.validate?.(value);
|
|
47
|
+
|
|
48
|
+
if (problem !== undefined) {
|
|
49
|
+
process.stderr.write(` ${problem}\n`);
|
|
50
|
+
|
|
51
|
+
return lineIo.text(opts);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
return value;
|
|
55
|
+
},
|
|
56
|
+
select: async (opts) => {
|
|
57
|
+
const answer = askWithPrompt({
|
|
58
|
+
question: `${opts.message} [${opts.choices.map((choice) => choice.value).join('/')}]`,
|
|
59
|
+
previous: opts.initial,
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
if (answer === null) {
|
|
63
|
+
return null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
const value = answer.trim() === '' ? opts.initial : answer.trim();
|
|
67
|
+
|
|
68
|
+
if (opts.choices.some((choice) => choice.value === value)) {
|
|
69
|
+
return value;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
process.stderr.write(` one of: ${opts.choices.map((choice) => choice.value).join(', ')}\n`);
|
|
73
|
+
|
|
74
|
+
return lineIo.select(opts);
|
|
75
|
+
},
|
|
76
|
+
confirm: async (opts) => {
|
|
77
|
+
const answer = askWithPrompt({
|
|
78
|
+
question: `${opts.message} [y/n]`,
|
|
79
|
+
previous: opts.initial ? 'y' : 'n',
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
if (answer === null) {
|
|
83
|
+
return null;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const value = answer.trim().toLowerCase();
|
|
87
|
+
|
|
88
|
+
if (value === '') {
|
|
89
|
+
return opts.initial;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
if (['y', 'yes', 'n', 'no'].includes(value)) {
|
|
93
|
+
return value.startsWith('y');
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
process.stderr.write(' answer y or n\n');
|
|
97
|
+
|
|
98
|
+
return lineIo.confirm(opts);
|
|
99
|
+
},
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
/** Runs the form and saves the profile; the exit code of the command. */
|
|
103
|
+
export const fillInProfile = async (opts: { root: string }): Promise<number> => {
|
|
104
|
+
const current = readProfile({ root: opts.root });
|
|
105
|
+
|
|
106
|
+
if (!current.ok) {
|
|
107
|
+
process.stderr.write(
|
|
108
|
+
`vulcan profile: ${current.error} - delete it with 'vulcan profile reset --yes' and run again\n`,
|
|
109
|
+
);
|
|
110
|
+
|
|
111
|
+
return ExitCodes.FAILURE;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// Before the questions, not after: an answer that cannot be saved is an answer typed for nothing.
|
|
115
|
+
if (!profileIsIgnored({ root: opts.root })) {
|
|
116
|
+
process.stderr.write(
|
|
117
|
+
'vulcan profile: .gitignore does not list .agents/local/ - run vulcan sync (or add the line) first; a personal file must not be committable\n',
|
|
118
|
+
);
|
|
119
|
+
|
|
120
|
+
return ExitCodes.FAILURE;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const profile = await runSurvey({
|
|
124
|
+
io: menusAvailable() ? menuIo : lineIo,
|
|
125
|
+
existing: current.profile,
|
|
126
|
+
systemLanguage: systemLanguageOf({ env: process.env }),
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
if (profile === null) {
|
|
130
|
+
process.stderr.write('vulcan profile: cancelled, nothing written\n');
|
|
131
|
+
|
|
132
|
+
return ExitCodes.FAILURE;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const saved = writeProfile({ root: opts.root, profile });
|
|
136
|
+
|
|
137
|
+
if (!saved.ok) {
|
|
138
|
+
process.stderr.write(`vulcan profile: ${saved.error}\n`);
|
|
139
|
+
|
|
140
|
+
return ExitCodes.FAILURE;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
process.stderr.write(
|
|
144
|
+
`vulcan profile: saved ${OwnerConstants.PROFILE_FILE} - it stays in this project, gitignored; edit it by hand or run 'vulcan profile' again\n`,
|
|
145
|
+
);
|
|
146
|
+
|
|
147
|
+
return ExitCodes.OK;
|
|
148
|
+
};
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* After `init`: in a terminal that can draw menus, a project with no profile is offered the form once;
|
|
152
|
+
* anywhere else (a pipe, CI) it only says how to run it. A profile that already exists is left alone.
|
|
153
|
+
*/
|
|
154
|
+
export const offerProfile = async (opts: { root: string }): Promise<void> => {
|
|
155
|
+
if (existsSync(join(opts.root, OwnerConstants.PROFILE_FILE))) {
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
if (!menusAvailable()) {
|
|
160
|
+
process.stderr.write(
|
|
161
|
+
"tell VULCAN how you like to work (language, how to address you, tone): run 'bun x --no-install vulcan profile'\n",
|
|
162
|
+
);
|
|
163
|
+
|
|
164
|
+
return;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
const now = await promptConfirm({
|
|
168
|
+
message:
|
|
169
|
+
"Tell VULCAN how you like to work (language, how to address you, tone)? Every question can be skipped; 'vulcan profile' does it later.",
|
|
170
|
+
initial: true,
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
if (now === true) {
|
|
174
|
+
await fillInProfile({ root: opts.root });
|
|
175
|
+
}
|
|
176
|
+
};
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* `vulcan profile`: the form (also `edit`), `show` prints the file, `reset` removes it. The file is
|
|
180
|
+
* `.agents/local/profile.json` in this project; nothing is written outside it.
|
|
181
|
+
*/
|
|
182
|
+
export const runProfileCommand = async (opts: ICommandContext): Promise<number> => {
|
|
183
|
+
const [sub, ...rest] = opts.args.filter((arg) => arg !== YES_FLAG);
|
|
184
|
+
|
|
185
|
+
if (sub === undefined || sub === 'edit') {
|
|
186
|
+
return fillInProfile({ root: opts.cwd });
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
if (rest.length > 0 || !['show', 'reset'].includes(sub)) {
|
|
190
|
+
process.stderr.write(
|
|
191
|
+
`vulcan profile: unknown argument '${rest[0] ?? sub}' - use show, edit or reset\n`,
|
|
192
|
+
);
|
|
193
|
+
|
|
194
|
+
return ExitCodes.FAILURE;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
const file = join(opts.cwd, OwnerConstants.PROFILE_FILE);
|
|
198
|
+
|
|
199
|
+
if (sub === 'show') {
|
|
200
|
+
const read = readProfile({ root: opts.cwd });
|
|
201
|
+
|
|
202
|
+
if (!read.ok) {
|
|
203
|
+
process.stderr.write(`vulcan profile: ${read.error}\n`);
|
|
204
|
+
|
|
205
|
+
return ExitCodes.FAILURE;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
if (read.profile === undefined) {
|
|
209
|
+
process.stderr.write(`vulcan profile: none yet - run 'vulcan profile' to make one\n`);
|
|
210
|
+
|
|
211
|
+
return ExitCodes.OK;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
process.stdout.write(renderProfile({ profile: read.profile }));
|
|
215
|
+
|
|
216
|
+
return ExitCodes.OK;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// The same refusal as read and write: a link at the file's place or at `.agents/local` must never
|
|
220
|
+
// turn a reset into a delete outside the project.
|
|
221
|
+
if (linkedAt({ root: opts.cwd }) !== undefined) {
|
|
222
|
+
process.stderr.write(
|
|
223
|
+
`vulcan profile: ${OwnerConstants.PROFILE_FILE} (or .agents/local) is a symlink - remove the link yourself; nothing was deleted\n`,
|
|
224
|
+
);
|
|
225
|
+
|
|
226
|
+
return ExitCodes.FAILURE;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
if (!existsSync(file)) {
|
|
230
|
+
process.stderr.write('vulcan profile: nothing to reset\n');
|
|
231
|
+
|
|
232
|
+
return ExitCodes.OK;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
if (!lstatSync(file).isFile()) {
|
|
236
|
+
process.stderr.write(
|
|
237
|
+
`vulcan profile: ${OwnerConstants.PROFILE_FILE} is not a file - nothing was deleted\n`,
|
|
238
|
+
);
|
|
239
|
+
|
|
240
|
+
return ExitCodes.FAILURE;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
if (!opts.args.includes(YES_FLAG)) {
|
|
244
|
+
process.stderr.write(
|
|
245
|
+
`vulcan profile: would delete ${OwnerConstants.PROFILE_FILE} (add --yes)\n`,
|
|
246
|
+
);
|
|
247
|
+
|
|
248
|
+
return ExitCodes.OK;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
rmSync(file);
|
|
252
|
+
process.stderr.write(`vulcan profile: deleted ${OwnerConstants.PROFILE_FILE}\n`);
|
|
253
|
+
|
|
254
|
+
return ExitCodes.OK;
|
|
255
|
+
};
|
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
planExclude,
|
|
19
19
|
planLocalChoice,
|
|
20
20
|
planLocalIgnore,
|
|
21
|
+
planLocalWorkspace,
|
|
21
22
|
planPrune,
|
|
22
23
|
planSync,
|
|
23
24
|
SyncConstants,
|
|
@@ -34,7 +35,7 @@ const DRY_RUN_LABELS: Record<string, string> = {
|
|
|
34
35
|
[SyncStatuses.REPLACED]: 'would replace',
|
|
35
36
|
[SyncStatuses.REMOVED]: 'would remove',
|
|
36
37
|
};
|
|
37
|
-
const DRY_RUN_LABEL_WIDTH = Math.max(...Object.values(DRY_RUN_LABELS).map(label => label.length));
|
|
38
|
+
const DRY_RUN_LABEL_WIDTH = Math.max(...Object.values(DRY_RUN_LABELS).map((label) => label.length));
|
|
38
39
|
|
|
39
40
|
/** `--agents` is undefined when absent and '' when it has no value after it. */
|
|
40
41
|
const readAgentsFlag = (opts: { args: string[] }): string | undefined => {
|
|
@@ -102,10 +103,10 @@ export const runSyncFlow = async (
|
|
|
102
103
|
const previous = readLocalChoice({ root: opts.cwd });
|
|
103
104
|
const dropped =
|
|
104
105
|
resolved.source === 'flag' || resolved.source === 'asked'
|
|
105
|
-
? (previous.ok ? (previous.agents ?? []) : []).filter(id => !resolved.agents.includes(id))
|
|
106
|
+
? (previous.ok ? (previous.agents ?? []) : []).filter((id) => !resolved.agents.includes(id))
|
|
106
107
|
: [];
|
|
107
108
|
const removed = [...new Set([...(opts.cleanup ?? []), ...dropped])].filter(
|
|
108
|
-
id => !resolved.agents.includes(id),
|
|
109
|
+
(id) => !resolved.agents.includes(id),
|
|
109
110
|
);
|
|
110
111
|
const dryRun = opts.args.includes(DRY_RUN_FLAG);
|
|
111
112
|
// Planned before anything is written: prune reads the managed record of the previous sync.
|
|
@@ -123,6 +124,7 @@ export const runSyncFlow = async (
|
|
|
123
124
|
...planSync({ root: opts.cwd, config: loaded.config, agents: resolved.agents }),
|
|
124
125
|
...planAtlasBlock({ root: opts.cwd, config: loaded.config }),
|
|
125
126
|
...stored,
|
|
127
|
+
...planLocalWorkspace({ root: opts.cwd }),
|
|
126
128
|
...planExclude({ root: opts.cwd, agents: resolved.agents }),
|
|
127
129
|
...pruned,
|
|
128
130
|
];
|
|
@@ -154,7 +156,7 @@ export const runSyncFlow = async (
|
|
|
154
156
|
}
|
|
155
157
|
|
|
156
158
|
const settingsBroken = actions.some(
|
|
157
|
-
action =>
|
|
159
|
+
(action) =>
|
|
158
160
|
action.status === SyncStatuses.SKIPPED && action.path.endsWith(SyncConstants.SETTINGS_FILE),
|
|
159
161
|
);
|
|
160
162
|
|
|
@@ -116,7 +116,7 @@ const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
|
|
|
116
116
|
* cannot be resolved.
|
|
117
117
|
*/
|
|
118
118
|
export const resolveUpgradeTarget = async (opts: ICommandContext): Promise<string | undefined> => {
|
|
119
|
-
const explicit = opts.args.find(arg => !arg.startsWith('-'));
|
|
119
|
+
const explicit = opts.args.find((arg) => !arg.startsWith('-'));
|
|
120
120
|
|
|
121
121
|
if (explicit !== undefined) {
|
|
122
122
|
return explicit;
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { readFileSync, statSync } from 'node:fs';
|
|
2
|
+
import { basename, resolve } from 'node:path';
|
|
3
|
+
import { ExitCodes } from '../common/index.ts';
|
|
4
|
+
import type { ICommandContext } from '../common/index.ts';
|
|
5
|
+
import { pageNameOf, renderSpecText, specSchemaText, writePage } from '../visualize/index.ts';
|
|
6
|
+
|
|
7
|
+
const SCHEMA_FLAG = '--schema';
|
|
8
|
+
const OUT_FLAG = '--out';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* `vulcan visualize <spec.json> [--out <name>]`: one small static HTML page from a JSON spec, written to
|
|
12
|
+
* `.agents/local/prototypes/` (gitignored). `--schema` prints the spec's JSON Schema. The page needs no
|
|
13
|
+
* network and nothing is published; the command says which of its own checks ran, and that the browser
|
|
14
|
+
* check is the caller's.
|
|
15
|
+
*/
|
|
16
|
+
export const runVisualizeCommand = async (opts: ICommandContext): Promise<number> => {
|
|
17
|
+
const outAt = opts.args.indexOf(OUT_FLAG);
|
|
18
|
+
const out = outAt === -1 ? undefined : opts.args[outAt + 1];
|
|
19
|
+
|
|
20
|
+
if (
|
|
21
|
+
outAt !== -1 &&
|
|
22
|
+
(out === undefined || out.startsWith('-') || opts.args.lastIndexOf(OUT_FLAG) !== outAt)
|
|
23
|
+
) {
|
|
24
|
+
process.stderr.write(`vulcan visualize: ${OUT_FLAG} takes one page name\n`);
|
|
25
|
+
|
|
26
|
+
return ExitCodes.FAILURE;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
if (opts.args.includes(SCHEMA_FLAG)) {
|
|
30
|
+
process.stdout.write(specSchemaText());
|
|
31
|
+
|
|
32
|
+
return ExitCodes.OK;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const specArgument = opts.args.find(
|
|
36
|
+
(arg, index) => !arg.startsWith('-') && (outAt === -1 || index !== outAt + 1),
|
|
37
|
+
);
|
|
38
|
+
|
|
39
|
+
if (specArgument === undefined) {
|
|
40
|
+
process.stderr.write(
|
|
41
|
+
'vulcan visualize: name the spec file - vulcan visualize <spec.json> [--out <name>], or --schema\n',
|
|
42
|
+
);
|
|
43
|
+
|
|
44
|
+
return ExitCodes.FAILURE;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const specFile = resolve(opts.cwd, specArgument);
|
|
48
|
+
|
|
49
|
+
if (!statSync(specFile, { throwIfNoEntry: false })?.isFile()) {
|
|
50
|
+
process.stderr.write(`vulcan visualize: ${specArgument} is not a file\n`);
|
|
51
|
+
|
|
52
|
+
return ExitCodes.FAILURE;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
const source = out ?? basename(specFile);
|
|
56
|
+
const name = pageNameOf({ name: source });
|
|
57
|
+
|
|
58
|
+
if (name === undefined) {
|
|
59
|
+
process.stderr.write(
|
|
60
|
+
`vulcan visualize: '${source}' does not give a page name (lowercase letters, digits and dashes) - use ${OUT_FLAG}\n`,
|
|
61
|
+
);
|
|
62
|
+
|
|
63
|
+
return ExitCodes.FAILURE;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
let text: string;
|
|
67
|
+
|
|
68
|
+
try {
|
|
69
|
+
text = readFileSync(specFile, 'utf8');
|
|
70
|
+
} catch (error) {
|
|
71
|
+
process.stderr.write(
|
|
72
|
+
`vulcan visualize: cannot read ${specArgument}: ${error instanceof Error ? error.message : String(error)}\n`,
|
|
73
|
+
);
|
|
74
|
+
|
|
75
|
+
return ExitCodes.FAILURE;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const rendered = renderSpecText({ text });
|
|
79
|
+
|
|
80
|
+
if (!rendered.ok) {
|
|
81
|
+
process.stderr.write(
|
|
82
|
+
`vulcan visualize: the spec is not renderable, nothing was written:\n${rendered.problems.map((problem) => ` ${problem}`).join('\n')}\n`,
|
|
83
|
+
);
|
|
84
|
+
|
|
85
|
+
return ExitCodes.FAILURE;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const written = writePage({ root: opts.cwd, name, html: rendered.page.html });
|
|
89
|
+
|
|
90
|
+
if (!written.ok) {
|
|
91
|
+
process.stderr.write(`vulcan visualize: ${written.error}\n`);
|
|
92
|
+
|
|
93
|
+
return ExitCodes.FAILURE;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
process.stdout.write(`${written.path}\n`);
|
|
97
|
+
|
|
98
|
+
for (const warning of rendered.page.warnings) {
|
|
99
|
+
process.stderr.write(`warning: ${warning}\n`);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
process.stderr.write(
|
|
103
|
+
`vulcan visualize: wrote ${written.path} (${(rendered.page.bytes / 1024).toFixed(1)} KB)\nchecks that ran: ${rendered.page.checks.join('; ')}\nnot run here: a browser check at 390 and 1280 px - open the page and look, or say it was not browser-checked\n`,
|
|
104
|
+
);
|
|
105
|
+
|
|
106
|
+
return ExitCodes.OK;
|
|
107
|
+
};
|
package/src/common/constants.ts
CHANGED
|
@@ -5,6 +5,9 @@ export class VulcanCommands {
|
|
|
5
5
|
static readonly AGENTS = 'agents';
|
|
6
6
|
static readonly DOCTOR = 'doctor';
|
|
7
7
|
static readonly UPGRADE = 'upgrade';
|
|
8
|
+
static readonly CLEAN = 'clean';
|
|
9
|
+
static readonly PROFILE = 'profile';
|
|
10
|
+
static readonly VISUALIZE = 'visualize';
|
|
8
11
|
static readonly X = 'x';
|
|
9
12
|
static readonly HELP = 'help';
|
|
10
13
|
static readonly VERSION = 'version';
|
|
@@ -15,6 +18,9 @@ export class VulcanCommands {
|
|
|
15
18
|
this.AGENTS,
|
|
16
19
|
this.DOCTOR,
|
|
17
20
|
this.UPGRADE,
|
|
21
|
+
this.CLEAN,
|
|
22
|
+
this.PROFILE,
|
|
23
|
+
this.VISUALIZE,
|
|
18
24
|
this.X,
|
|
19
25
|
this.HELP,
|
|
20
26
|
this.VERSION,
|
|
@@ -68,7 +74,24 @@ export class ProjectLayout {
|
|
|
68
74
|
'.claude/',
|
|
69
75
|
'.agents/plans',
|
|
70
76
|
'.agents/vulcan.local.json',
|
|
77
|
+
'.agents/local/',
|
|
71
78
|
];
|
|
79
|
+
/** Everything an agent creates while it works lives under here, gitignored: nothing goes outside the project. */
|
|
80
|
+
static readonly LOCAL_DIRECTORY = '.agents/local';
|
|
81
|
+
/** Each directory under it, with when it goes: the one list `sync`, `doctor` and `clean` read. */
|
|
82
|
+
static readonly LOCAL_LAYOUT = [
|
|
83
|
+
{ name: 'tmp', lifetime: 'task', removedWhen: 'the task ends', staleAfterDays: 1 },
|
|
84
|
+
{ name: 'worktrees', lifetime: 'branch', removedWhen: 'its branch is merged or abandoned' },
|
|
85
|
+
{
|
|
86
|
+
name: 'clones',
|
|
87
|
+
lifetime: 'research',
|
|
88
|
+
removedWhen: 'the research that needed them is reported',
|
|
89
|
+
staleAfterDays: 14,
|
|
90
|
+
},
|
|
91
|
+
{ name: 'cache', lifetime: 'kept', removedWhen: 'the user asks; it rebuilds' },
|
|
92
|
+
{ name: 'reports', lifetime: 'kept', removedWhen: 'the user deletes it' },
|
|
93
|
+
{ name: 'prototypes', lifetime: 'kept', removedWhen: 'the user deletes it' },
|
|
94
|
+
] as const;
|
|
72
95
|
/** What the scaffolded lint configs run; optional peers of dev-configs, so bun never installs them alone. */
|
|
73
96
|
static readonly LINT_TOOLS = ['oxlint', 'oxlint-tsgolint', 'eslint'];
|
|
74
97
|
/** Written into a scaffolded file the project must fill in; doctor fails the file while it holds this. */
|
package/src/config/loader.ts
CHANGED
|
@@ -14,9 +14,9 @@ const describeError = (opts: { error: unknown }): string =>
|
|
|
14
14
|
|
|
15
15
|
/** Every `.configs/vulcan.config.<ext>` present, in lookup order. */
|
|
16
16
|
export const findConfigFiles = (opts: { root: string }): string[] =>
|
|
17
|
-
ConfigExtensions.LOOKUP_ORDER.map(extension =>
|
|
17
|
+
ConfigExtensions.LOOKUP_ORDER.map((extension) =>
|
|
18
18
|
join(opts.root, ConfigConstants.DIRECTORY, `${ConfigConstants.BASENAME}.${extension}`),
|
|
19
|
-
).filter(file => existsSync(file));
|
|
19
|
+
).filter((file) => existsSync(file));
|
|
20
20
|
|
|
21
21
|
export const loadConfig = async (opts: { root: string }): Promise<TLoadResult> => {
|
|
22
22
|
const files = findConfigFiles({ root: opts.root });
|
|
@@ -29,7 +29,7 @@ export const loadConfig = async (opts: { root: string }): Promise<TLoadResult> =
|
|
|
29
29
|
}
|
|
30
30
|
|
|
31
31
|
if (files.length > 1) {
|
|
32
|
-
const names = files.map(file => relative(opts.root, file)).join(', ');
|
|
32
|
+
const names = files.map((file) => relative(opts.root, file)).join(', ');
|
|
33
33
|
|
|
34
34
|
return { ok: false, error: `more than one config - keep exactly one of: ${names}` };
|
|
35
35
|
}
|
|
@@ -57,7 +57,7 @@ export const loadConfig = async (opts: { root: string }): Promise<TLoadResult> =
|
|
|
57
57
|
|
|
58
58
|
if (!parsed.success) {
|
|
59
59
|
const issues = parsed.error.issues
|
|
60
|
-
.map(issue => {
|
|
60
|
+
.map((issue) => {
|
|
61
61
|
const path =
|
|
62
62
|
issue.code === 'unrecognized_keys'
|
|
63
63
|
? issue.keys.join(', ')
|
package/src/config/packages.ts
CHANGED
|
@@ -14,7 +14,7 @@ export interface IProjectPackage {
|
|
|
14
14
|
|
|
15
15
|
/** The project's packages in release order. */
|
|
16
16
|
export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPackage[] =>
|
|
17
|
-
opts.config.packages.map(entry => ({
|
|
17
|
+
opts.config.packages.map((entry) => ({
|
|
18
18
|
dir: entry.dir,
|
|
19
19
|
name: entry.name,
|
|
20
20
|
path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
|
package/src/config/schema.ts
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
+
import { OWNER_SCHEMA } from '../owner/schema.ts';
|
|
2
3
|
import { CodingAgents, ConfigConstants, HookEvents } from './common/index.ts';
|
|
3
4
|
|
|
4
|
-
const CODING_AGENT = z.string().refine(value => CodingAgents.isValid(value), {
|
|
5
|
+
const CODING_AGENT = z.string().refine((value) => CodingAgents.isValid(value), {
|
|
5
6
|
message: `one of: ${[...CodingAgents.SCHEME_SET].join(', ')}`,
|
|
6
7
|
});
|
|
7
|
-
const HOOK_EVENT = z.string().refine(value => HookEvents.isValid(value), {
|
|
8
|
+
const HOOK_EVENT = z.string().refine((value) => HookEvents.isValid(value), {
|
|
8
9
|
message: `one of: ${[...HookEvents.SCHEME_SET].join(', ')}`,
|
|
9
10
|
});
|
|
10
11
|
|
|
@@ -68,7 +69,7 @@ const checkPackagesUnique = (
|
|
|
68
69
|
* leading `[#<issue>] ` is optional and a trailing ` [<mode>]` is tolerated. A release train that
|
|
69
70
|
* tags once leaves `<dir>` out (`v<version>`).
|
|
70
71
|
*/
|
|
71
|
-
const RELEASE_TEMPLATE = z.string().refine(value => value.includes('<version>'), {
|
|
72
|
+
const RELEASE_TEMPLATE = z.string().refine((value) => value.includes('<version>'), {
|
|
72
73
|
message: 'a template with <version> (and <dir> or <package> for per-package releases)',
|
|
73
74
|
});
|
|
74
75
|
|
|
@@ -82,7 +83,7 @@ const removedAtlasKey = (opts: { key: string }) =>
|
|
|
82
83
|
|
|
83
84
|
/** A renderer by id: a built-in, or a project module (`module`); a bare string is the id alone. */
|
|
84
85
|
const OKF_RENDERER = z.union([
|
|
85
|
-
z.string().transform(id => ({ id, options: {} })),
|
|
86
|
+
z.string().transform((id) => ({ id, options: {} })),
|
|
86
87
|
z.strictObject({
|
|
87
88
|
id: z.string(),
|
|
88
89
|
module: z.string().optional(),
|
|
@@ -97,7 +98,7 @@ const REMOTE_HOST = z
|
|
|
97
98
|
/^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/,
|
|
98
99
|
'a host name or a pattern with *, not a user, a path or a port',
|
|
99
100
|
)
|
|
100
|
-
.refine(value => value.replaceAll('*', '').replaceAll('.', '') !== '', {
|
|
101
|
+
.refine((value) => value.replaceAll('*', '').replaceAll('.', '') !== '', {
|
|
101
102
|
message: 'a pattern needs at least one literal character beyond * and .',
|
|
102
103
|
});
|
|
103
104
|
|
|
@@ -251,6 +252,16 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
251
252
|
.default(ConfigConstants.DEFAULT_OFTEN_DROPPED),
|
|
252
253
|
})
|
|
253
254
|
.default({ oftenDropped: ConfigConstants.DEFAULT_OFTEN_DROPPED }),
|
|
255
|
+
/** The report contract for answers to the project's owners; English and `advise` by default. */
|
|
256
|
+
owner: OWNER_SCHEMA,
|
|
257
|
+
/**
|
|
258
|
+
* The hooks that guard writes. `toolOwnedPaths` extends the defaults (package manager caches, the
|
|
259
|
+
* runtime dir for locks, git config, the agent tool's memory) with stores a tool in this project
|
|
260
|
+
* manages itself: absolute globs, `~` and `$NAME` allowed.
|
|
261
|
+
*/
|
|
262
|
+
guard: z
|
|
263
|
+
.strictObject({ toolOwnedPaths: z.array(z.string().min(1)).default([]) })
|
|
264
|
+
.default({ toolOwnedPaths: [] }),
|
|
254
265
|
});
|
|
255
266
|
|
|
256
267
|
export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
|
package/src/create/add-app.ts
CHANGED
|
@@ -61,7 +61,7 @@ const fail = (opts: { message: string }): number => {
|
|
|
61
61
|
|
|
62
62
|
/** The side the flags give away: a frontend flag, or only the backend folder; undefined when they do not say. */
|
|
63
63
|
const sideNamedBy = (opts: { args: string[] }): TAppSide | undefined => {
|
|
64
|
-
const frontend = [CreateFlags.FRONTEND_DIR, CreateFlags.API, CreateFlags.NO_API].some(flag =>
|
|
64
|
+
const frontend = [CreateFlags.FRONTEND_DIR, CreateFlags.API, CreateFlags.NO_API].some((flag) =>
|
|
65
65
|
opts.args.includes(flag),
|
|
66
66
|
);
|
|
67
67
|
const backend = opts.args.includes(CreateFlags.BACKEND_DIR);
|
|
@@ -125,7 +125,7 @@ const askKind = async (opts: { offered: string[] }): Promise<string | undefined>
|
|
|
125
125
|
if (menusAvailable()) {
|
|
126
126
|
const picked = await promptSelect({
|
|
127
127
|
message: 'What do you want to create?',
|
|
128
|
-
choices: opts.offered.map(kind => ({ value: kind, label: kind, hint: KIND_HINTS[kind] })),
|
|
128
|
+
choices: opts.offered.map((kind) => ({ value: kind, label: kind, hint: KIND_HINTS[kind] })),
|
|
129
129
|
});
|
|
130
130
|
|
|
131
131
|
return picked ?? undefined;
|
|
@@ -174,7 +174,7 @@ const literal = (opts: {
|
|
|
174
174
|
` layout: { ${opts.side}: '${opts.folder}' },`,
|
|
175
175
|
` packages: { dir: '${opts.app.dir}', name: '${opts.app.name}', path: '${opts.app.path}' },`,
|
|
176
176
|
...opts.sources.map(
|
|
177
|
-
source =>
|
|
177
|
+
(source) =>
|
|
178
178
|
` sources: { name: '${source.name}', repo: '${source.repo}', ref: '${source.ref}' },`,
|
|
179
179
|
),
|
|
180
180
|
];
|
|
@@ -200,7 +200,7 @@ const resolveApiUrl = async (opts: {
|
|
|
200
200
|
|
|
201
201
|
if (menusAvailable()) {
|
|
202
202
|
const backends = opts.packages.filter(
|
|
203
|
-
entry =>
|
|
203
|
+
(entry) =>
|
|
204
204
|
opts.backendFolder !== undefined && entry.path.startsWith(`${opts.backendFolder}/`),
|
|
205
205
|
);
|
|
206
206
|
|
|
@@ -212,7 +212,7 @@ const resolveApiUrl = async (opts: {
|
|
|
212
212
|
const picked = await promptSelect({
|
|
213
213
|
message: 'Backend app to proxy /api to',
|
|
214
214
|
choices: [
|
|
215
|
-
...backends.map(entry => ({ value: entry.dir, label: entry.dir, hint: entry.path })),
|
|
215
|
+
...backends.map((entry) => ({ value: entry.dir, label: entry.dir, hint: entry.path })),
|
|
216
216
|
{ value: NO_BACKEND, label: 'none', hint: 'no proxy' },
|
|
217
217
|
],
|
|
218
218
|
});
|
|
@@ -233,7 +233,7 @@ const resolveApiUrl = async (opts: {
|
|
|
233
233
|
}
|
|
234
234
|
|
|
235
235
|
const backend = opts.packages.find(
|
|
236
|
-
entry =>
|
|
236
|
+
(entry) =>
|
|
237
237
|
entry.dir === chosen &&
|
|
238
238
|
opts.backendFolder !== undefined &&
|
|
239
239
|
entry.path.startsWith(`${opts.backendFolder}/`),
|
|
@@ -262,8 +262,8 @@ const resolveApiUrl = async (opts: {
|
|
|
262
262
|
};
|
|
263
263
|
|
|
264
264
|
const usedPorts = (opts: { root: string; packages: IProjectPackage[] }): number[] =>
|
|
265
|
-
readExistingApps({ root: opts.root, paths: opts.packages.map(entry => entry.path) }).map(
|
|
266
|
-
app => app.port,
|
|
265
|
+
readExistingApps({ root: opts.root, paths: opts.packages.map((entry) => entry.path) }).map(
|
|
266
|
+
(app) => app.port,
|
|
267
267
|
);
|
|
268
268
|
|
|
269
269
|
const locate = async (opts: {
|
|
@@ -383,7 +383,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
383
383
|
(
|
|
384
384
|
await askInTerminal({
|
|
385
385
|
question: 'Name of this library',
|
|
386
|
-
validate: value =>
|
|
386
|
+
validate: (value) =>
|
|
387
387
|
value.trim() === '' ? undefined : nameProblem({ name: value.trim() }),
|
|
388
388
|
})
|
|
389
389
|
)?.trim();
|
|
@@ -472,7 +472,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
472
472
|
|
|
473
473
|
if (
|
|
474
474
|
existsSync(join(cwd, folder, app)) ||
|
|
475
|
-
packages.some(entry => entry.dir === app || entry.name === packageOfApp)
|
|
475
|
+
packages.some((entry) => entry.dir === app || entry.name === packageOfApp)
|
|
476
476
|
) {
|
|
477
477
|
return fail({ message: `${folder}/${app} already exists` });
|
|
478
478
|
}
|
|
@@ -498,8 +498,8 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
498
498
|
|
|
499
499
|
const source = readFileSync(loaded.file, 'utf8');
|
|
500
500
|
const entry = { dir: app, name: packageOfApp, path: `${folder}/${app}` };
|
|
501
|
-
const knownSources = new Set(config.atlas.sources.map(known => known.name));
|
|
502
|
-
const newSources = preset.atlas.filter(candidate => !knownSources.has(candidate.name));
|
|
501
|
+
const knownSources = new Set(config.atlas.sources.map((known) => known.name));
|
|
502
|
+
const newSources = preset.atlas.filter((candidate) => !knownSources.has(candidate.name));
|
|
503
503
|
const parsed = parseAppsBlock({ source });
|
|
504
504
|
|
|
505
505
|
// The user's config is theirs: with the block gone or no longer JSON it is never rewritten, only described.
|
|
@@ -522,7 +522,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
522
522
|
sources: [
|
|
523
523
|
...parsed.block.sources,
|
|
524
524
|
...newSources.filter(
|
|
525
|
-
candidate => !parsed.block.sources.some(existing => existing.name === candidate.name),
|
|
525
|
+
(candidate) => !parsed.block.sources.some((existing) => existing.name === candidate.name),
|
|
526
526
|
),
|
|
527
527
|
],
|
|
528
528
|
};
|
|
@@ -651,7 +651,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
651
651
|
done: `Done. ${folder}/${app} is added.`,
|
|
652
652
|
command: 'make dev',
|
|
653
653
|
apps: [
|
|
654
|
-
...readExistingApps({ root: cwd, paths: packages.map(existing => existing.path) }),
|
|
654
|
+
...readExistingApps({ root: cwd, paths: packages.map((existing) => existing.path) }),
|
|
655
655
|
{ port: devPort, urls: preset.urls },
|
|
656
656
|
],
|
|
657
657
|
}),
|
|
@@ -661,4 +661,4 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
661
661
|
};
|
|
662
662
|
|
|
663
663
|
export const addApp = async (opts: { cwd: string; args: string[] }): Promise<number> =>
|
|
664
|
-
withScratch({ run: scratch => runAdd({ ...opts, scratch }) });
|
|
664
|
+
withScratch({ root: opts.cwd, run: (scratch) => runAdd({ ...opts, scratch }) });
|