@venizia/vulcan 0.4.0 → 0.4.2

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.
Files changed (141) hide show
  1. package/base/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +3 -3
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +388 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. 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
+ };
@@ -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. */
@@ -71,5 +71,7 @@ export class ConfigConstants {
71
71
  'V-W-04',
72
72
  'V-C-02',
73
73
  'V-C-10',
74
+ 'V-P-08',
75
+ 'V-B-07',
74
76
  ];
75
77
  }
@@ -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(', ')
@@ -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}`,
@@ -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>;
@@ -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 }) });