@venizia/vulcan 0.4.10-2 → 0.4.10-4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -18
- package/base/hooks/guard-outside.ts +10 -19
- package/base/hooks/guard-writes.ts +3 -24
- package/base/make/vulcan.mk +1 -4
- package/base/rules.md +4 -4
- package/base/skills/visualize-work/SKILL.md +1 -1
- package/base/skills/visualize-work/references/spec.md +1 -1
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/resolve.ts +1 -0
- package/src/board/command.ts +16 -1
- package/src/board/common/constants.ts +2 -0
- package/src/board/common/types.ts +2 -2
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +13 -2
- package/src/board/settings.ts +1 -1
- package/src/commands/graph.command.ts +6 -0
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +2 -0
- package/src/commands/sync.command.ts +5 -1
- package/src/commands/table.ts +327 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +2 -0
- package/src/commit/hook.ts +44 -4
- package/src/common/constants.ts +7 -3
- package/src/common/env-variables.ts +37 -0
- package/src/common/index.ts +1 -0
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +162 -20
- package/src/create/add-app.ts +5 -0
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +106 -4
- package/src/doctor/common/constants.ts +26 -0
- package/src/doctor/runner.ts +3 -0
- package/src/doctor/schema.ts +4 -0
- package/src/hooks/owner-reply.ts +5 -0
- package/src/hooks/project-guards.ts +28 -4
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/session-digest.ts +9 -0
- package/src/init/scaffold.ts +1 -0
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +1 -0
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +33 -9
- package/src/manifest/render.ts +70 -9
- package/src/owner/constants.ts +3 -1
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +37 -6
- package/src/router.ts +4 -130
- package/src/rules/base.ts +1 -0
- package/src/signals/loop.ts +1 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +1 -0
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/page.ts +4 -4
- package/src/visualize/render.ts +2 -1
- package/src/visualize/theme.ts +43 -12
- package/src/wiki/anchors.ts +1 -0
package/src/config/schema.ts
CHANGED
|
@@ -11,6 +11,8 @@ import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
|
|
|
11
11
|
import { SubjectShape } from '../commit/subject.ts';
|
|
12
12
|
import { BoardServe } from '../board/common/constants.ts';
|
|
13
13
|
import { ProjectKey } from '../events/project-key.ts';
|
|
14
|
+
import { ThemeTokens } from '../theme/index.ts';
|
|
15
|
+
import { ProjectTheme } from '../visualize/theme.ts';
|
|
14
16
|
import { BOARD_AGENTS } from '../board/schema.ts';
|
|
15
17
|
import { EventRetention } from '../events/retention.ts';
|
|
16
18
|
import { EventSettings } from '../events/settings.ts';
|
|
@@ -49,13 +51,17 @@ const compiles = (value: string): boolean => {
|
|
|
49
51
|
|
|
50
52
|
/** A command the project says is a database write (V-W-02) or a deploy (V-W-03): guard-writes asks when its pattern matches. */
|
|
51
53
|
const GUARD_COMMAND = z.strictObject({
|
|
54
|
+
/** Which rule the command falls under: `V-W-02` for a database write, `V-W-03` for a deploy. */
|
|
52
55
|
rule: z.enum(['V-W-02', 'V-W-03']),
|
|
56
|
+
/** Short name of the action, shown when guard-writes asks; 1 to 120 characters. */
|
|
53
57
|
what: z.string().min(1).max(120),
|
|
58
|
+
/** JavaScript regular expression, 1 to 500 characters, matched against a shell command; guard-writes asks when it matches. */
|
|
54
59
|
pattern: z
|
|
55
60
|
.string()
|
|
56
61
|
.min(1)
|
|
57
62
|
.max(500)
|
|
58
63
|
.refine(compiles, { message: 'a regular expression (JavaScript syntax)' }),
|
|
64
|
+
/** `true` matches `pattern` without regard to case; default: case-sensitive. */
|
|
59
65
|
ignoreCase: z.boolean().optional(),
|
|
60
66
|
});
|
|
61
67
|
|
|
@@ -64,6 +70,27 @@ const PUSH_TARGET = z
|
|
|
64
70
|
.string()
|
|
65
71
|
.regex(/^[A-Za-z0-9._/*-]+$/, { message: 'a branch name, with * for any run of characters' });
|
|
66
72
|
|
|
73
|
+
/** An import prefix: the start of a specifier, ending in a slash (`@/`, `~/`). */
|
|
74
|
+
const GRAPH_ALIAS_PREFIX = z
|
|
75
|
+
.string()
|
|
76
|
+
.regex(/^[^\s]+\/$/, 'an alias prefix ends with a slash, for example "@/"');
|
|
77
|
+
/** The folder an alias leads to, from the importing package: relative to the package, never climbing. */
|
|
78
|
+
const GRAPH_ALIAS_FOLDER = z
|
|
79
|
+
.string()
|
|
80
|
+
.refine(
|
|
81
|
+
(value) => !value.startsWith('/') && !value.split('/').includes('..'),
|
|
82
|
+
'a folder of the package, from its root',
|
|
83
|
+
);
|
|
84
|
+
|
|
85
|
+
/** A key that was removed: optional, and refused when present with the key and what to do, instead of a bare "unrecognized key". */
|
|
86
|
+
const REMOVED_OKF_KEY = (opts: { fix: string }) =>
|
|
87
|
+
z
|
|
88
|
+
.unknown()
|
|
89
|
+
.superRefine((_value, context) => {
|
|
90
|
+
context.addIssue({ code: 'custom', message: `removed: ${opts.fix}` });
|
|
91
|
+
})
|
|
92
|
+
.optional();
|
|
93
|
+
|
|
67
94
|
/** A layout folder: 1 to 4 plain segments, never climbing, never absolute (the validator `guard-package` shares). */
|
|
68
95
|
const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
|
|
69
96
|
const problem = LayoutFolder.layoutFolderProblem({ folder: value });
|
|
@@ -128,11 +155,15 @@ const AGENT_NAME = z
|
|
|
128
155
|
.regex(/[\p{L}\p{N}]/u, { message: 'a name with at least one letter or digit' });
|
|
129
156
|
|
|
130
157
|
const PROJECT_PACKAGE = z.strictObject({
|
|
158
|
+
/** Unique key of the package, not necessarily its folder name; lower case letters, digits, `.` and `-`, starting with a letter or digit. */
|
|
131
159
|
dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
|
|
160
|
+
/** The npm package name: lower case, optional `@scope/`, at most 214 characters. */
|
|
132
161
|
name: NPM_PACKAGE_NAME,
|
|
133
162
|
/** Where the package lives, from the root; default `packages/<dir>`. */
|
|
134
163
|
path: z.string().optional(),
|
|
164
|
+
/** Extra names accepted as the `<dir>` of a release tag; default `[]`. */
|
|
135
165
|
aliases: z.array(z.string()).default([]),
|
|
166
|
+
/** `true` marks a package that is gone but whose releases stay readable; its path may be reused. Default `false`. */
|
|
136
167
|
retired: z.boolean().default(false),
|
|
137
168
|
/** A library a preset made lives anywhere a workspace glob covers; absent means an app or a plain package. */
|
|
138
169
|
kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
|
|
@@ -195,8 +226,11 @@ const RELEASE_TEMPLATE = z.string().refine((value) => value.includes('<version>'
|
|
|
195
226
|
const OKF_RENDERER = z.union([
|
|
196
227
|
z.string().transform((id) => ({ id, options: {} })),
|
|
197
228
|
z.strictObject({
|
|
229
|
+
/** Name of the renderer: a built-in, or the identifier a project module registers. */
|
|
198
230
|
id: z.string(),
|
|
231
|
+
/** Path of the project module that exports the renderer; absent means a built-in. */
|
|
199
232
|
module: z.string().optional(),
|
|
233
|
+
/** Options passed to the renderer; default `{}`. */
|
|
200
234
|
options: z.record(z.string(), z.unknown()).default({}),
|
|
201
235
|
}),
|
|
202
236
|
]);
|
|
@@ -209,7 +243,8 @@ const REMOTE_HOST = z
|
|
|
209
243
|
message: 'a pattern needs at least one letter or digit, not only * . - or _',
|
|
210
244
|
});
|
|
211
245
|
|
|
212
|
-
|
|
246
|
+
/** A colour of a design token: six-digit hex, or eight-digit with an alpha channel for lines and soft text. */
|
|
247
|
+
const TOKEN_COLOUR = z.string().regex(ThemeTokens.COLOUR, 'a hex colour like #8a5a20');
|
|
213
248
|
|
|
214
249
|
/** `.configs/vulcan.config.*` - strict: an unknown key is a typo, and a typo is an error. */
|
|
215
250
|
export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
@@ -224,12 +259,16 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
224
259
|
.optional(),
|
|
225
260
|
/** The project's suggested agents; each developer's own choice lives in `.agents/vulcan.local.json`. */
|
|
226
261
|
agents: z.array(CODING_AGENT).optional(),
|
|
262
|
+
/** Choice of each base rule slot, keyed by rule ID (for example `V-W-01`) to the option picked; default `{}`. */
|
|
227
263
|
rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
|
|
228
264
|
/** The folders `vulcan init` and `add` put apps in, as the user named them. */
|
|
229
265
|
layout: z
|
|
230
266
|
.strictObject({
|
|
267
|
+
/** Folder, or list of folders, for backend apps. */
|
|
231
268
|
backend: LAYOUT_VALUE.optional(),
|
|
269
|
+
/** Folder, or list of folders, for frontend apps. */
|
|
232
270
|
frontend: LAYOUT_VALUE.optional(),
|
|
271
|
+
/** Folder, or list of folders, for code shared between apps. */
|
|
233
272
|
shared: LAYOUT_VALUE.optional(),
|
|
234
273
|
/** Folders the layout does not manage (docs, third-party code, tests): packages there are allowed, never targeted by `add`, never guarded. */
|
|
235
274
|
other: LAYOUT_VALUE.optional(),
|
|
@@ -244,8 +283,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
244
283
|
presets: z
|
|
245
284
|
.array(
|
|
246
285
|
z.strictObject({
|
|
286
|
+
/** What was given to `--preset`. */
|
|
247
287
|
spec: z.string().min(1),
|
|
288
|
+
/** Side of the preset's app kind: `backend` or `frontend`. */
|
|
248
289
|
side: z.enum(['backend', 'frontend']),
|
|
290
|
+
/** The app kind's one-sentence summary. */
|
|
249
291
|
summary: z.string(),
|
|
250
292
|
/** The summary of the preset's lib kind, when it ships one. */
|
|
251
293
|
lib: z.string().optional(),
|
|
@@ -256,34 +298,39 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
256
298
|
.optional(),
|
|
257
299
|
/** The project's packages in release order; okf, atlas, make and release read this one list. */
|
|
258
300
|
packages: z.array(PROJECT_PACKAGE).superRefine(checkPackagesUnique).default([]),
|
|
301
|
+
/** Where the project keeps its knowledge bundle, wiki, changelogs and sync map; read by okf, doctor and the knowledge-sync skill. */
|
|
259
302
|
knowledge: z
|
|
260
303
|
.strictObject({
|
|
304
|
+
/** Folder of the knowledge bundle (the OKF concepts); default `.agents/knowledge`. */
|
|
261
305
|
bundle: z.string().default(ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE),
|
|
306
|
+
/** Folder of the wiki content; absent means the project has none. */
|
|
262
307
|
wiki: z.string().optional(),
|
|
308
|
+
/** Folder of the changelog files; absent means the project has none. */
|
|
263
309
|
changelogs: z.string().optional(),
|
|
264
310
|
/** The knowledge-sync skill's map of code areas to concepts. */
|
|
265
311
|
syncAreas: z.string().optional(),
|
|
266
312
|
})
|
|
267
313
|
.default({ bundle: ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE }),
|
|
314
|
+
/** Settings of okf, the knowledge bundle tool: renderers, regions, coverage axes and the brand. */
|
|
268
315
|
okf: z
|
|
269
316
|
.strictObject({
|
|
317
|
+
/** Renderers the project uses, each a built-in id or an object with a module; default `[]`. */
|
|
270
318
|
renderers: z.array(OKF_RENDERER).default([]),
|
|
319
|
+
/** Generated blocks in markdown files, each binding a region `id` and `file` to a `renderer`; default `[]`. */
|
|
271
320
|
regions: z
|
|
272
321
|
.array(z.strictObject({ id: z.string(), file: z.string(), renderer: z.string() }))
|
|
273
322
|
.default([]),
|
|
274
|
-
sections: z
|
|
275
|
-
.strictObject({
|
|
276
|
-
order: z.array(z.string()).default([]),
|
|
277
|
-
labels: z.record(z.string(), z.string()).default({}),
|
|
278
|
-
})
|
|
279
|
-
.default({ order: [], labels: {} }),
|
|
280
323
|
/** `exclude`: globs from the root dropped from this axis; `denylist`: directory names dropped from this axis only. */
|
|
281
324
|
coverage: z
|
|
282
325
|
.array(
|
|
283
326
|
z.strictObject({
|
|
327
|
+
/** Unique name of the coverage axis. */
|
|
284
328
|
name: z.string(),
|
|
329
|
+
/** Directory or pattern the axis scans. */
|
|
285
330
|
path: z.string(),
|
|
331
|
+
/** Globs from the root dropped from this axis; default `[]`. */
|
|
286
332
|
exclude: z.array(z.string()).default([]),
|
|
333
|
+
/** Directory names dropped from this axis only; default `[]`. */
|
|
287
334
|
denylist: z.array(z.string()).default([]),
|
|
288
335
|
}),
|
|
289
336
|
)
|
|
@@ -294,25 +341,26 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
294
341
|
contents: z
|
|
295
342
|
.strictObject({ files: z.array(z.string()).default(['AGENTS.md', '.agents/rules.md']) })
|
|
296
343
|
.default({ files: ['AGENTS.md', '.agents/rules.md'] }),
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
344
|
+
/** How the project's name is written in prose, for the brand rule of `okf check`; absent means the root package name without scope, upper-cased. */
|
|
345
|
+
brand: z.string().optional(),
|
|
346
|
+
/** Removed with `vulcan x okf viz`: the key is refused with what to do. */
|
|
347
|
+
viz: REMOVED_OKF_KEY({
|
|
348
|
+
fix: 'delete this key; `vulcan x okf viz` and `make okf-viz` are gone with no replacement, and the brand it carried is now `okf.brand`',
|
|
349
|
+
}),
|
|
350
|
+
/** Removed with the explorer, the only thing that read it. */
|
|
351
|
+
sections: REMOVED_OKF_KEY({ fix: 'delete this key; only the removed explorer read it' }),
|
|
304
352
|
})
|
|
305
353
|
.default({
|
|
306
354
|
renderers: [],
|
|
307
355
|
regions: [],
|
|
308
|
-
sections: { order: [], labels: {} },
|
|
309
356
|
coverage: [],
|
|
310
357
|
denylist: [],
|
|
311
358
|
contents: { files: ['AGENTS.md', '.agents/rules.md'] },
|
|
312
|
-
viz: { outputs: [VIZ_OUTPUT] },
|
|
313
359
|
}),
|
|
360
|
+
/** Settings of atlas: release tag layout, the sources it indexes, ignored tags, the signing keys of the published index and prebuilt downloads. */
|
|
314
361
|
atlas: z
|
|
315
362
|
.strictObject({
|
|
363
|
+
/** Template of a release tag; must hold `<version>`, and `<dir>` for per-package tags. Default `<dir>-v<version>`. */
|
|
316
364
|
tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
|
|
317
365
|
/**
|
|
318
366
|
* Templates of an earlier tag layout that are still releases: atlas and the changelog check read a tag
|
|
@@ -320,11 +368,15 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
320
368
|
* releases. Unlike `ignoreTags`, a tag matched here counts as a release.
|
|
321
369
|
*/
|
|
322
370
|
legacyTagPatterns: z.array(RELEASE_TEMPLATE).optional(),
|
|
371
|
+
/** Repositories atlas indexes besides this one, each with a `name`, a `repo` and a `ref`; default `[]`. */
|
|
323
372
|
sources: z
|
|
324
373
|
.array(
|
|
325
374
|
z.strictObject({
|
|
375
|
+
/** Identifier of the source in atlas results. */
|
|
326
376
|
name: z.string(),
|
|
377
|
+
/** GitHub repository of the source, as `owner/repo`. */
|
|
327
378
|
repo: z.string(),
|
|
379
|
+
/** Branch, tag or commit the source is indexed at; default `develop`. */
|
|
328
380
|
ref: z.string().default('develop'),
|
|
329
381
|
/** `installed` (default): the docs are read at the tag of the newest installed package; `ref`: at `ref`. */
|
|
330
382
|
pin: z.enum(['installed', 'ref']).optional(),
|
|
@@ -355,8 +407,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
355
407
|
*/
|
|
356
408
|
remoteHosts: z
|
|
357
409
|
.strictObject({
|
|
410
|
+
/** Hosts or `*` patterns a Bash command may reach without asking; default `[]`. */
|
|
358
411
|
trusted: z.array(REMOTE_HOST).default([]),
|
|
412
|
+
/** Hosts or `*` patterns that pass only the strict read-only command forms; default `[]`. */
|
|
359
413
|
readOnly: z.array(REMOTE_HOST).default([]),
|
|
414
|
+
/** Gitignored file of personal hosts, one per line (`readonly: <host>` for read-only); default `.agents/hooks/trusted-hosts.local`. */
|
|
360
415
|
localFile: z.string().default(ProjectLayout.TRUSTED_HOSTS_FILE),
|
|
361
416
|
})
|
|
362
417
|
.optional(),
|
|
@@ -368,15 +423,50 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
368
423
|
*/
|
|
369
424
|
theme: z
|
|
370
425
|
.strictObject({
|
|
371
|
-
|
|
426
|
+
/** The preset the tokens start from: `venizia` (default) or `slate`; a preset fixes every token and the project changes only what it names. */
|
|
427
|
+
preset: z
|
|
428
|
+
.string()
|
|
429
|
+
.refine((name) => Object.hasOwn(ThemeTokens.PRESETS, name), {
|
|
430
|
+
message: `one of ${Object.keys(ThemeTokens.PRESETS).join(', ')}`,
|
|
431
|
+
})
|
|
432
|
+
.optional(),
|
|
433
|
+
/** Colour for marks and fills, as a six-digit hex such as `#8a5a20`; absent means the preset's accent. */
|
|
434
|
+
accent: z.string().regex(ProjectTheme.HEX, 'a six-digit hex colour like #8a5a20').optional(),
|
|
435
|
+
/** Accent for dark grounds, a six-digit hex such as `#dead6a`; derived from `accent` when absent. */
|
|
372
436
|
accentDark: z
|
|
373
437
|
.string()
|
|
374
|
-
.regex(
|
|
438
|
+
.regex(ProjectTheme.HEX, 'a six-digit hex colour like #dead6a')
|
|
375
439
|
.optional(),
|
|
440
|
+
/** Darker accent for text, a six-digit hex such as `#01579b`; absent means `accent` is used for text too. */
|
|
376
441
|
accentText: z
|
|
377
442
|
.string()
|
|
378
|
-
.regex(
|
|
443
|
+
.regex(ProjectTheme.HEX, 'a six-digit hex colour like #01579b')
|
|
444
|
+
.optional(),
|
|
445
|
+
/** Per-token colours over the preset, keyed by token name: one hex for both modes, or `{ light, dark }`; each pair is checked against WCAG AA. */
|
|
446
|
+
tokens: z
|
|
447
|
+
.record(
|
|
448
|
+
z.string(),
|
|
449
|
+
z.union([
|
|
450
|
+
TOKEN_COLOUR,
|
|
451
|
+
z.strictObject({ light: TOKEN_COLOUR.optional(), dark: TOKEN_COLOUR.optional() }),
|
|
452
|
+
]),
|
|
453
|
+
)
|
|
379
454
|
.optional(),
|
|
455
|
+
/** The sans font stack for the board, the wiki and the pages; default the preset's. */
|
|
456
|
+
font: z.string().min(1).optional(),
|
|
457
|
+
/** The monospace font stack; default the preset's. */
|
|
458
|
+
mono: z.string().min(1).optional(),
|
|
459
|
+
/** The corner radius: `0`, or a number with `px`, `rem` or `em` such as `4px`; anything else is refused. Default the preset's. */
|
|
460
|
+
radius: z.string().min(1).optional(),
|
|
461
|
+
})
|
|
462
|
+
.superRefine((theme, context) => {
|
|
463
|
+
const resolved = ThemeTokens.resolve({ theme });
|
|
464
|
+
|
|
465
|
+
if (!resolved.ok) {
|
|
466
|
+
for (const message of resolved.problems) {
|
|
467
|
+
context.addIssue({ code: 'custom', message, path: [] });
|
|
468
|
+
}
|
|
469
|
+
}
|
|
380
470
|
})
|
|
381
471
|
.optional(),
|
|
382
472
|
/**
|
|
@@ -387,8 +477,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
387
477
|
*/
|
|
388
478
|
board: z
|
|
389
479
|
.strictObject({
|
|
480
|
+
/** Who an ask waits on; default: `git config user.name`, else `Owner`. */
|
|
390
481
|
owner: z.string().min(1).optional(),
|
|
482
|
+
/** Name on the board page and tab; default: the project name and `Board`. */
|
|
391
483
|
title: z.string().min(1).optional(),
|
|
484
|
+
/** Name in the address of `vulcan board serve`: lowercase, ending in `.localhost`; default `vulz-board.venizia.ai.localhost`. */
|
|
392
485
|
hostname: z
|
|
393
486
|
.string()
|
|
394
487
|
.regex(
|
|
@@ -396,6 +489,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
396
489
|
'a lowercase name that ends in .localhost, such as board.localhost',
|
|
397
490
|
)
|
|
398
491
|
.optional(),
|
|
492
|
+
/** Path inside the project to an `.svg` file shown on the board page, with no leading `/` and no `..` segment; default none. */
|
|
399
493
|
logo: z
|
|
400
494
|
.string()
|
|
401
495
|
.min(1)
|
|
@@ -410,6 +504,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
410
504
|
},
|
|
411
505
|
)
|
|
412
506
|
.optional(),
|
|
507
|
+
/** Faces and roles of the board's agents, keyed by agent name; default `{}`. */
|
|
413
508
|
agents: BOARD_AGENTS.default({}),
|
|
414
509
|
})
|
|
415
510
|
.default({ agents: {} }),
|
|
@@ -419,6 +514,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
419
514
|
claude: z
|
|
420
515
|
.strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
|
|
421
516
|
.default({ settings: {} }),
|
|
517
|
+
/** Project hooks, each an `event`, an optional `matcher` and a `command`; `vulcan sync` merges them into the agent settings. Default `[]`. */
|
|
422
518
|
hooks: z
|
|
423
519
|
.array(
|
|
424
520
|
z.strictObject({ event: HOOK_EVENT, matcher: z.string().optional(), command: z.string() }),
|
|
@@ -427,6 +523,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
427
523
|
/** The session-start digest: the rule IDs it repeats as "the rules sessions drop most" - base or the project's own. */
|
|
428
524
|
digest: z
|
|
429
525
|
.strictObject({
|
|
526
|
+
/** Rule IDs the digest repeats as dropped most, each matching the rule ID pattern; default the shipped list of base rules. */
|
|
430
527
|
oftenDropped: z
|
|
431
528
|
.array(z.string().regex(ConfigConstants.RULE_ID_PATTERN))
|
|
432
529
|
.default(ConfigConstants.DEFAULT_OFTEN_DROPPED),
|
|
@@ -444,20 +541,28 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
444
541
|
* read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
|
|
445
542
|
* project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
|
|
446
543
|
* compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
|
|
447
|
-
* writes both to the manifest, where the hooks read them
|
|
544
|
+
* writes both to the manifest, where the hooks read them, and writes `outside` (when it is `deny`),
|
|
545
|
+
* `toolOwnedPaths` and the path entries of `writes.trustedScripts` there too, so a config this VULCAN cannot
|
|
546
|
+
* parse changes no guard. `outside` is what `guard-outside` does with a
|
|
448
547
|
* write outside the project: `ask` (the default) or `deny`. Where the agent runs in an auto mode an ask can be
|
|
449
548
|
* approved without the owner seeing it, so a project that wants the line held sets `deny`.
|
|
450
549
|
*/
|
|
451
550
|
guard: z
|
|
452
551
|
.strictObject({
|
|
552
|
+
/** Absolute globs (`~` and `$NAME` allowed) of tool-managed stores, added to the built-in list; default `[]`. */
|
|
453
553
|
toolOwnedPaths: z.array(z.string().min(1)).default([]),
|
|
554
|
+
/** What guard-outside does with a write outside the project: `ask` or `deny`; default `ask`. */
|
|
454
555
|
outside: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
|
|
556
|
+
/** Write guard lists: scripts guard-writes trusts and the project's own deploy and migrate commands; both default to `[]`. */
|
|
455
557
|
writes: z
|
|
456
558
|
.strictObject({
|
|
559
|
+
/** Repo-relative `.ts` scripts guard-writes does not read for mutating calls; a path or `{ script, readOnly }`. Default `[]`. */
|
|
457
560
|
trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
|
|
561
|
+
/** The project's own deploy and migrate commands guard-writes asks about; default `[]`. */
|
|
458
562
|
commands: z.array(GUARD_COMMAND).default([]),
|
|
459
563
|
})
|
|
460
564
|
.default({ trustedScripts: [], commands: [] }),
|
|
565
|
+
/** Git guard settings; `askPush` lists the branches a plain `git push` asks about, `*` for any run of characters. Default `[]`. */
|
|
461
566
|
git: z.strictObject({ askPush: z.array(PUSH_TARGET).default([]) }).default({ askPush: [] }),
|
|
462
567
|
})
|
|
463
568
|
.default({
|
|
@@ -476,22 +581,29 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
476
581
|
*/
|
|
477
582
|
commit: z
|
|
478
583
|
.strictObject({
|
|
584
|
+
/** Checks on the text of a commit message: the agent signature policy and the subject shape. */
|
|
479
585
|
message: z
|
|
480
586
|
.strictObject({
|
|
587
|
+
/** Rules about agent names in a commit message: signature policy, extra names and allowed names. */
|
|
481
588
|
agent: z
|
|
482
589
|
.strictObject({
|
|
590
|
+
/** Policy for an agent trailer or "generated with" line in a commit message: `allow` or `deny`; default `allow`. */
|
|
483
591
|
signature: z
|
|
484
592
|
.custom<TAgentSignaturePolicy>(
|
|
485
593
|
(value) => typeof value === 'string' && AgentSignaturePolicies.isValid(value),
|
|
486
594
|
{ message: `one of ${[...AgentSignaturePolicies.SCHEME_SET].join(', ')}` },
|
|
487
595
|
)
|
|
488
596
|
.default(AgentSignaturePolicies.ALLOW),
|
|
597
|
+
/** Agent names added to the shipped list; a co-author or `Generated with` line naming one is flagged under `deny`. Default `[]`. */
|
|
489
598
|
names: z.array(AGENT_NAME).default([]),
|
|
599
|
+
/** Whole co-author names never flagged, for a person who shares a name with an agent; default `[]`. */
|
|
490
600
|
allow: z.array(AGENT_NAME).default([]),
|
|
491
601
|
})
|
|
492
602
|
.default({ signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] }),
|
|
603
|
+
/** The project's own shape for the commit subject line; absent means no subject check. */
|
|
493
604
|
subject: z
|
|
494
605
|
.strictObject({
|
|
606
|
+
/** Regular expression the commit subject must match, 1 or more characters; an invalid expression is rejected. */
|
|
495
607
|
pattern: z
|
|
496
608
|
.string()
|
|
497
609
|
.min(1)
|
|
@@ -502,6 +614,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
502
614
|
context.addIssue({ code: 'custom', message: error });
|
|
503
615
|
}
|
|
504
616
|
}),
|
|
617
|
+
/** Text shown with the error when a subject does not match `pattern`; absent means none. */
|
|
505
618
|
hint: z.string().min(1).optional(),
|
|
506
619
|
})
|
|
507
620
|
.optional(),
|
|
@@ -518,8 +631,10 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
518
631
|
*/
|
|
519
632
|
ci: z
|
|
520
633
|
.strictObject({
|
|
634
|
+
/** Which changed files make `vulcan ci affected` treat every package as affected. */
|
|
521
635
|
affected: z
|
|
522
636
|
.strictObject({
|
|
637
|
+
/** Root-relative globs, no leading `/` and no `..` segment, added to the shipped list of files that touch every package; default `[]`. */
|
|
523
638
|
global: z
|
|
524
639
|
.array(
|
|
525
640
|
z
|
|
@@ -545,7 +660,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
545
660
|
*/
|
|
546
661
|
events: z
|
|
547
662
|
.strictObject({
|
|
663
|
+
/** `true` makes `vulcan sync` install the hooks that write the event log; default `false`. */
|
|
548
664
|
log: z.boolean().default(false),
|
|
665
|
+
/** Absolute folder that takes the event log instead of the project's own; absent means the project's `.agents/local/events`. */
|
|
549
666
|
dir: z
|
|
550
667
|
.string()
|
|
551
668
|
.min(1)
|
|
@@ -568,10 +685,25 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
568
685
|
message: 'a size such as 50MB, 200MB or 1GB',
|
|
569
686
|
})
|
|
570
687
|
.optional(),
|
|
688
|
+
/** Most day files kept in the log; at least 1, default 30 when `log` is on. */
|
|
571
689
|
maxFiles: z.number().int().min(1).optional(),
|
|
690
|
+
/** Oldest age, in days, a day file may reach; at least 1, default 30 when `log` is on. */
|
|
572
691
|
maxAgeDays: z.number().int().min(1).optional(),
|
|
573
692
|
})
|
|
574
693
|
.default({ log: false }),
|
|
694
|
+
/**
|
|
695
|
+
* How `vulcan x atlas graph build` reads the code. `exclude` is globs of tracked files left out; `aliases` maps an import
|
|
696
|
+
* prefix to a folder of the importing package (`{ '@/': 'src/' }`), so `@/x` in `packages/a/src/y.ts` leads to
|
|
697
|
+
* `packages/a/src/x`. An alias not listed is counted as an external import.
|
|
698
|
+
*/
|
|
699
|
+
graph: z
|
|
700
|
+
.strictObject({
|
|
701
|
+
/** Globs of tracked files, from the project root, the graph leaves out. */
|
|
702
|
+
exclude: z.array(z.string().min(1)).default([]),
|
|
703
|
+
/** An import prefix ending in a slash, mapped to a folder of the importing package. */
|
|
704
|
+
aliases: z.record(GRAPH_ALIAS_PREFIX, GRAPH_ALIAS_FOLDER).default({}),
|
|
705
|
+
})
|
|
706
|
+
.default({ exclude: [], aliases: {} }),
|
|
575
707
|
/**
|
|
576
708
|
* What `vulcan` keeps tidy in `.agents/local/` by itself. `autoClean` (default true) lets the session-start hook, at
|
|
577
709
|
* most once a day, remove the safe part: stale `tmp/`, browser leftovers older than an hour, event files past their
|
|
@@ -579,12 +711,22 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
579
711
|
*/
|
|
580
712
|
local: z
|
|
581
713
|
.strictObject({
|
|
714
|
+
/** `true` lets the session-start hook clean the safe part of `.agents/local/` at most once a day; default `true`. */
|
|
582
715
|
autoClean: z.boolean().default(true),
|
|
716
|
+
/**
|
|
717
|
+
* A folder of the project, from its root, for the temporary files of a session (default `.agents/local/tmp`). A
|
|
718
|
+
* browser puts a socket below it and fails past 107 characters of path, so a deep checkout can name a short one (`t`).
|
|
719
|
+
* Written like a layout folder: 1 to 4 plain lower-case segments, never absolute, never climbing. `vulcan sync`
|
|
720
|
+
* creates it, gitignores it and points the launch file at it.
|
|
721
|
+
*/
|
|
722
|
+
tmp: LAYOUT_FOLDER.optional(),
|
|
583
723
|
})
|
|
584
724
|
.default({ autoClean: true }),
|
|
585
725
|
});
|
|
586
726
|
|
|
727
|
+
/** What a project writes in `.configs/vulcan.config.mts`: every key optional or defaulted, unknown keys refused. */
|
|
587
728
|
export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
|
|
729
|
+
/** The config as the CLI reads it: every default filled in. */
|
|
588
730
|
export type TResolvedConfig = z.output<typeof VULCAN_CONFIG_SCHEMA>;
|
|
589
731
|
|
|
590
732
|
/** Identity at run time; gives TS and JS configs their types. The parameter is the options object (V-C-02). */
|
package/src/create/add-app.ts
CHANGED
|
@@ -236,6 +236,11 @@ const usedPorts = (opts: { root: string; packages: IProjectPackage[] }): number[
|
|
|
236
236
|
/** A terminal picks one of the presets the project recorded or an official one, or types another; null when cancelled. */
|
|
237
237
|
const askPreset = async (opts: { cwd: string }): Promise<string | null> => {
|
|
238
238
|
const loaded = await ConfigLoader.load({ root: opts.cwd });
|
|
239
|
+
const note = ConfigLoader.unreadableNote({ loaded });
|
|
240
|
+
|
|
241
|
+
if (note !== undefined) {
|
|
242
|
+
process.stderr.write(`vulcan add: ${note}\n`);
|
|
243
|
+
}
|
|
239
244
|
|
|
240
245
|
return PresetMenu.askSpec({ recorded: loaded.ok ? (loaded.config.presets ?? []) : [] });
|
|
241
246
|
};
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { EnvVariables } from '../../common/env-variables.ts';
|
|
2
|
+
|
|
1
3
|
export class AppSides {
|
|
2
4
|
static readonly BACKEND = 'backend';
|
|
3
5
|
static readonly FRONTEND = 'frontend';
|
|
@@ -35,11 +37,11 @@ export class CreateConstants {
|
|
|
35
37
|
];
|
|
36
38
|
static readonly STDIN_DESCRIPTOR = 0;
|
|
37
39
|
/** Tests only: set to `1`, every install, git and check command is printed as skipped instead of run. */
|
|
38
|
-
static readonly NO_INSTALL_ENV =
|
|
40
|
+
static readonly NO_INSTALL_ENV = EnvVariables.VULCAN_NO_INSTALL;
|
|
39
41
|
/** Tests only: a path that stands in for the `bun` executable, so a test fakes success or failure. */
|
|
40
|
-
static readonly BUN_ENV =
|
|
42
|
+
static readonly BUN_ENV = EnvVariables.VULCAN_BUN;
|
|
41
43
|
/** Tests only: a path that stands in for the `git` executable. */
|
|
42
|
-
static readonly GIT_ENV =
|
|
44
|
+
static readonly GIT_ENV = EnvVariables.VULCAN_GIT;
|
|
43
45
|
static readonly APPS_BLOCK_START =
|
|
44
46
|
'// vulcan:apps:start - written by vulcan init and add; edit outside this block';
|
|
45
47
|
static readonly APPS_BLOCK_END = '// vulcan:apps:end';
|
package/src/create/preset.ts
CHANGED
|
@@ -79,6 +79,7 @@ const resolveInside = (opts: { root: string; from: string; path: string }): stri
|
|
|
79
79
|
return resolved;
|
|
80
80
|
};
|
|
81
81
|
|
|
82
|
+
/** Locates a preset (name, path or spec), reads its files and copies them with names filled in; used by `vulcan init` and `vulcan add`. */
|
|
82
83
|
export class Preset {
|
|
83
84
|
/** Text gets its tokens replaced; anything else is copied as it is. */
|
|
84
85
|
private static substituteTokens(opts: {
|
package/src/create/scratch.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { ProjectTmp } from '../hooks/project-tmp.ts';
|
|
1
2
|
import { mkdirSync, mkdtempSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
3
|
import { join } from 'node:path';
|
|
3
4
|
import { ProjectLayout } from '../common/index.ts';
|
|
@@ -47,7 +48,7 @@ export class PresetScratch {
|
|
|
47
48
|
run: (scratch: string) => Promise<TResult>;
|
|
48
49
|
}): Promise<TResult> {
|
|
49
50
|
const local = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
|
|
50
|
-
const parent =
|
|
51
|
+
const parent = ProjectTmp.projectOf({ root: opts.root });
|
|
51
52
|
|
|
52
53
|
mkdirSync(parent, { recursive: true });
|
|
53
54
|
|