@venizia/vulcan 0.4.10-2 → 0.4.10-3
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 +19 -14
- package/base/hooks/guard-outside.ts +6 -17
- package/base/hooks/guard-writes.ts +3 -24
- package/base/rules.md +3 -3
- package/base/skills/visualize-work/SKILL.md +1 -1
- package/base/skills/visualize-work/references/spec.md +1 -1
- package/package.json +3 -3
- package/src/agents/resolve.ts +1 -0
- package/src/board/common/types.ts +2 -2
- package/src/board/schema.ts +4 -1
- package/src/board/settings.ts +1 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/table.ts +315 -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 +6 -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 +121 -4
- 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/doctor/checks.ts +10 -0
- package/src/doctor/common/constants.ts +26 -0
- package/src/doctor/runner.ts +1 -0
- package/src/doctor/schema.ts +4 -0
- package/src/hooks/owner-reply.ts +5 -0
- package/src/hooks/project-guards.ts +25 -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/clean.ts +1 -0
- package/src/manifest/render.ts +48 -6
- 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/planner.ts +1 -0
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +305 -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 +27 -10
- 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
|
|
|
@@ -128,11 +134,15 @@ const AGENT_NAME = z
|
|
|
128
134
|
.regex(/[\p{L}\p{N}]/u, { message: 'a name with at least one letter or digit' });
|
|
129
135
|
|
|
130
136
|
const PROJECT_PACKAGE = z.strictObject({
|
|
137
|
+
/** Unique key of the package, not necessarily its folder name; lower case letters, digits, `.` and `-`, starting with a letter or digit. */
|
|
131
138
|
dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
|
|
139
|
+
/** The npm package name: lower case, optional `@scope/`, at most 214 characters. */
|
|
132
140
|
name: NPM_PACKAGE_NAME,
|
|
133
141
|
/** Where the package lives, from the root; default `packages/<dir>`. */
|
|
134
142
|
path: z.string().optional(),
|
|
143
|
+
/** Extra names accepted as the `<dir>` of a release tag; default `[]`. */
|
|
135
144
|
aliases: z.array(z.string()).default([]),
|
|
145
|
+
/** `true` marks a package that is gone but whose releases stay readable; its path may be reused. Default `false`. */
|
|
136
146
|
retired: z.boolean().default(false),
|
|
137
147
|
/** A library a preset made lives anywhere a workspace glob covers; absent means an app or a plain package. */
|
|
138
148
|
kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
|
|
@@ -195,8 +205,11 @@ const RELEASE_TEMPLATE = z.string().refine((value) => value.includes('<version>'
|
|
|
195
205
|
const OKF_RENDERER = z.union([
|
|
196
206
|
z.string().transform((id) => ({ id, options: {} })),
|
|
197
207
|
z.strictObject({
|
|
208
|
+
/** Name of the renderer: a built-in, or the identifier a project module registers. */
|
|
198
209
|
id: z.string(),
|
|
210
|
+
/** Path of the project module that exports the renderer; absent means a built-in. */
|
|
199
211
|
module: z.string().optional(),
|
|
212
|
+
/** Options passed to the renderer; default `{}`. */
|
|
200
213
|
options: z.record(z.string(), z.unknown()).default({}),
|
|
201
214
|
}),
|
|
202
215
|
]);
|
|
@@ -211,6 +224,9 @@ const REMOTE_HOST = z
|
|
|
211
224
|
|
|
212
225
|
const VIZ_OUTPUT = '.agents/knowledge/viz.html';
|
|
213
226
|
|
|
227
|
+
/** A colour of a design token: six-digit hex, or eight-digit with an alpha channel for lines and soft text. */
|
|
228
|
+
const TOKEN_COLOUR = z.string().regex(ThemeTokens.COLOUR, 'a hex colour like #8a5a20');
|
|
229
|
+
|
|
214
230
|
/** `.configs/vulcan.config.*` - strict: an unknown key is a typo, and a typo is an error. */
|
|
215
231
|
export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
216
232
|
/** The project's name in the manifest and in every atlas result; default: the root package name, unscoped. */
|
|
@@ -224,12 +240,16 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
224
240
|
.optional(),
|
|
225
241
|
/** The project's suggested agents; each developer's own choice lives in `.agents/vulcan.local.json`. */
|
|
226
242
|
agents: z.array(CODING_AGENT).optional(),
|
|
243
|
+
/** Choice of each base rule slot, keyed by rule ID (for example `V-W-01`) to the option picked; default `{}`. */
|
|
227
244
|
rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
|
|
228
245
|
/** The folders `vulcan init` and `add` put apps in, as the user named them. */
|
|
229
246
|
layout: z
|
|
230
247
|
.strictObject({
|
|
248
|
+
/** Folder, or list of folders, for backend apps. */
|
|
231
249
|
backend: LAYOUT_VALUE.optional(),
|
|
250
|
+
/** Folder, or list of folders, for frontend apps. */
|
|
232
251
|
frontend: LAYOUT_VALUE.optional(),
|
|
252
|
+
/** Folder, or list of folders, for code shared between apps. */
|
|
233
253
|
shared: LAYOUT_VALUE.optional(),
|
|
234
254
|
/** Folders the layout does not manage (docs, third-party code, tests): packages there are allowed, never targeted by `add`, never guarded. */
|
|
235
255
|
other: LAYOUT_VALUE.optional(),
|
|
@@ -244,8 +264,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
244
264
|
presets: z
|
|
245
265
|
.array(
|
|
246
266
|
z.strictObject({
|
|
267
|
+
/** What was given to `--preset`. */
|
|
247
268
|
spec: z.string().min(1),
|
|
269
|
+
/** Side of the preset's app kind: `backend` or `frontend`. */
|
|
248
270
|
side: z.enum(['backend', 'frontend']),
|
|
271
|
+
/** The app kind's one-sentence summary. */
|
|
249
272
|
summary: z.string(),
|
|
250
273
|
/** The summary of the preset's lib kind, when it ships one. */
|
|
251
274
|
lib: z.string().optional(),
|
|
@@ -256,24 +279,34 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
256
279
|
.optional(),
|
|
257
280
|
/** The project's packages in release order; okf, atlas, make and release read this one list. */
|
|
258
281
|
packages: z.array(PROJECT_PACKAGE).superRefine(checkPackagesUnique).default([]),
|
|
282
|
+
/** Where the project keeps its knowledge bundle, wiki, changelogs and sync map; read by okf, doctor and the knowledge-sync skill. */
|
|
259
283
|
knowledge: z
|
|
260
284
|
.strictObject({
|
|
285
|
+
/** Folder of the knowledge bundle (the OKF concepts); default `.agents/knowledge`. */
|
|
261
286
|
bundle: z.string().default(ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE),
|
|
287
|
+
/** Folder of the wiki content; absent means the project has none. */
|
|
262
288
|
wiki: z.string().optional(),
|
|
289
|
+
/** Folder of the changelog files; absent means the project has none. */
|
|
263
290
|
changelogs: z.string().optional(),
|
|
264
291
|
/** The knowledge-sync skill's map of code areas to concepts. */
|
|
265
292
|
syncAreas: z.string().optional(),
|
|
266
293
|
})
|
|
267
294
|
.default({ bundle: ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE }),
|
|
295
|
+
/** Settings of okf, the knowledge bundle tool: renderers, regions, index sections, coverage axes and the visualization page. */
|
|
268
296
|
okf: z
|
|
269
297
|
.strictObject({
|
|
298
|
+
/** Renderers the project uses, each a built-in id or an object with a module; default `[]`. */
|
|
270
299
|
renderers: z.array(OKF_RENDERER).default([]),
|
|
300
|
+
/** Generated blocks in markdown files, each binding a region `id` and `file` to a `renderer`; default `[]`. */
|
|
271
301
|
regions: z
|
|
272
302
|
.array(z.strictObject({ id: z.string(), file: z.string(), renderer: z.string() }))
|
|
273
303
|
.default([]),
|
|
304
|
+
/** Order and display labels of the section headings in the generated index tables; default no order and no labels. */
|
|
274
305
|
sections: z
|
|
275
306
|
.strictObject({
|
|
307
|
+
/** Order of the section headings in the index tables; default `[]`. */
|
|
276
308
|
order: z.array(z.string()).default([]),
|
|
309
|
+
/** Display label for each section heading, keyed by heading; default `{}`. */
|
|
277
310
|
labels: z.record(z.string(), z.string()).default({}),
|
|
278
311
|
})
|
|
279
312
|
.default({ order: [], labels: {} }),
|
|
@@ -281,9 +314,13 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
281
314
|
coverage: z
|
|
282
315
|
.array(
|
|
283
316
|
z.strictObject({
|
|
317
|
+
/** Unique name of the coverage axis. */
|
|
284
318
|
name: z.string(),
|
|
319
|
+
/** Directory or pattern the axis scans. */
|
|
285
320
|
path: z.string(),
|
|
321
|
+
/** Globs from the root dropped from this axis; default `[]`. */
|
|
286
322
|
exclude: z.array(z.string()).default([]),
|
|
323
|
+
/** Directory names dropped from this axis only; default `[]`. */
|
|
287
324
|
denylist: z.array(z.string()).default([]),
|
|
288
325
|
}),
|
|
289
326
|
)
|
|
@@ -294,10 +331,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
294
331
|
contents: z
|
|
295
332
|
.strictObject({ files: z.array(z.string()).default(['AGENTS.md', '.agents/rules.md']) })
|
|
296
333
|
.default({ files: ['AGENTS.md', '.agents/rules.md'] }),
|
|
334
|
+
/** The visualization page okf writes: output paths, brand heading and text overrides; read by the okf viz command. */
|
|
297
335
|
viz: z
|
|
298
336
|
.strictObject({
|
|
337
|
+
/** Paths the visualization page is written to; default `['.agents/knowledge/viz.html']`. */
|
|
299
338
|
outputs: z.array(z.string()).default([VIZ_OUTPUT]),
|
|
339
|
+
/** Brand heading shown in the page header; absent means none. */
|
|
300
340
|
brand: z.string().optional(),
|
|
341
|
+
/** Overrides for the page's text labels; absent means the built-in text. */
|
|
301
342
|
copy: z.record(z.string(), z.unknown()).optional(),
|
|
302
343
|
})
|
|
303
344
|
.default({ outputs: [VIZ_OUTPUT] }),
|
|
@@ -311,8 +352,10 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
311
352
|
contents: { files: ['AGENTS.md', '.agents/rules.md'] },
|
|
312
353
|
viz: { outputs: [VIZ_OUTPUT] },
|
|
313
354
|
}),
|
|
355
|
+
/** Settings of atlas: release tag layout, the sources it indexes, ignored tags, the signing keys of the published index and prebuilt downloads. */
|
|
314
356
|
atlas: z
|
|
315
357
|
.strictObject({
|
|
358
|
+
/** Template of a release tag; must hold `<version>`, and `<dir>` for per-package tags. Default `<dir>-v<version>`. */
|
|
316
359
|
tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
|
|
317
360
|
/**
|
|
318
361
|
* Templates of an earlier tag layout that are still releases: atlas and the changelog check read a tag
|
|
@@ -320,11 +363,15 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
320
363
|
* releases. Unlike `ignoreTags`, a tag matched here counts as a release.
|
|
321
364
|
*/
|
|
322
365
|
legacyTagPatterns: z.array(RELEASE_TEMPLATE).optional(),
|
|
366
|
+
/** Repositories atlas indexes besides this one, each with a `name`, a `repo` and a `ref`; default `[]`. */
|
|
323
367
|
sources: z
|
|
324
368
|
.array(
|
|
325
369
|
z.strictObject({
|
|
370
|
+
/** Identifier of the source in atlas results. */
|
|
326
371
|
name: z.string(),
|
|
372
|
+
/** GitHub repository of the source, as `owner/repo`. */
|
|
327
373
|
repo: z.string(),
|
|
374
|
+
/** Branch, tag or commit the source is indexed at; default `develop`. */
|
|
328
375
|
ref: z.string().default('develop'),
|
|
329
376
|
/** `installed` (default): the docs are read at the tag of the newest installed package; `ref`: at `ref`. */
|
|
330
377
|
pin: z.enum(['installed', 'ref']).optional(),
|
|
@@ -355,8 +402,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
355
402
|
*/
|
|
356
403
|
remoteHosts: z
|
|
357
404
|
.strictObject({
|
|
405
|
+
/** Hosts or `*` patterns a Bash command may reach without asking; default `[]`. */
|
|
358
406
|
trusted: z.array(REMOTE_HOST).default([]),
|
|
407
|
+
/** Hosts or `*` patterns that pass only the strict read-only command forms; default `[]`. */
|
|
359
408
|
readOnly: z.array(REMOTE_HOST).default([]),
|
|
409
|
+
/** Gitignored file of personal hosts, one per line (`readonly: <host>` for read-only); default `.agents/hooks/trusted-hosts.local`. */
|
|
360
410
|
localFile: z.string().default(ProjectLayout.TRUSTED_HOSTS_FILE),
|
|
361
411
|
})
|
|
362
412
|
.optional(),
|
|
@@ -368,15 +418,50 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
368
418
|
*/
|
|
369
419
|
theme: z
|
|
370
420
|
.strictObject({
|
|
371
|
-
|
|
421
|
+
/** The preset the tokens start from: `venizia` (default) or `slate`; a preset fixes every token and the project changes only what it names. */
|
|
422
|
+
preset: z
|
|
423
|
+
.string()
|
|
424
|
+
.refine((name) => Object.hasOwn(ThemeTokens.PRESETS, name), {
|
|
425
|
+
message: `one of ${Object.keys(ThemeTokens.PRESETS).join(', ')}`,
|
|
426
|
+
})
|
|
427
|
+
.optional(),
|
|
428
|
+
/** Colour for marks and fills, as a six-digit hex such as `#8a5a20`; absent means the preset's accent. */
|
|
429
|
+
accent: z.string().regex(ProjectTheme.HEX, 'a six-digit hex colour like #8a5a20').optional(),
|
|
430
|
+
/** Accent for dark grounds, a six-digit hex such as `#dead6a`; derived from `accent` when absent. */
|
|
372
431
|
accentDark: z
|
|
373
432
|
.string()
|
|
374
|
-
.regex(
|
|
433
|
+
.regex(ProjectTheme.HEX, 'a six-digit hex colour like #dead6a')
|
|
375
434
|
.optional(),
|
|
435
|
+
/** Darker accent for text, a six-digit hex such as `#01579b`; absent means `accent` is used for text too. */
|
|
376
436
|
accentText: z
|
|
377
437
|
.string()
|
|
378
|
-
.regex(
|
|
438
|
+
.regex(ProjectTheme.HEX, 'a six-digit hex colour like #01579b')
|
|
379
439
|
.optional(),
|
|
440
|
+
/** 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. */
|
|
441
|
+
tokens: z
|
|
442
|
+
.record(
|
|
443
|
+
z.string(),
|
|
444
|
+
z.union([
|
|
445
|
+
TOKEN_COLOUR,
|
|
446
|
+
z.strictObject({ light: TOKEN_COLOUR.optional(), dark: TOKEN_COLOUR.optional() }),
|
|
447
|
+
]),
|
|
448
|
+
)
|
|
449
|
+
.optional(),
|
|
450
|
+
/** The sans font stack for the board, the wiki and the pages; default the preset's. */
|
|
451
|
+
font: z.string().min(1).optional(),
|
|
452
|
+
/** The monospace font stack; default the preset's. */
|
|
453
|
+
mono: z.string().min(1).optional(),
|
|
454
|
+
/** The corner radius as a CSS length such as `4px`; default the preset's. */
|
|
455
|
+
radius: z.string().min(1).optional(),
|
|
456
|
+
})
|
|
457
|
+
.superRefine((theme, context) => {
|
|
458
|
+
const resolved = ThemeTokens.resolve({ theme });
|
|
459
|
+
|
|
460
|
+
if (!resolved.ok) {
|
|
461
|
+
for (const message of resolved.problems) {
|
|
462
|
+
context.addIssue({ code: 'custom', message, path: [] });
|
|
463
|
+
}
|
|
464
|
+
}
|
|
380
465
|
})
|
|
381
466
|
.optional(),
|
|
382
467
|
/**
|
|
@@ -387,8 +472,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
387
472
|
*/
|
|
388
473
|
board: z
|
|
389
474
|
.strictObject({
|
|
475
|
+
/** Who an ask waits on; default: `git config user.name`, else `Owner`. */
|
|
390
476
|
owner: z.string().min(1).optional(),
|
|
477
|
+
/** Name on the board page and tab; default: the project name and `Board`. */
|
|
391
478
|
title: z.string().min(1).optional(),
|
|
479
|
+
/** Name in the address of `vulcan board serve`: lowercase, ending in `.localhost`; default `vulz-board.venizia.ai.localhost`. */
|
|
392
480
|
hostname: z
|
|
393
481
|
.string()
|
|
394
482
|
.regex(
|
|
@@ -396,6 +484,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
396
484
|
'a lowercase name that ends in .localhost, such as board.localhost',
|
|
397
485
|
)
|
|
398
486
|
.optional(),
|
|
487
|
+
/** Path inside the project to an `.svg` file shown on the board page, with no leading `/` and no `..` segment; default none. */
|
|
399
488
|
logo: z
|
|
400
489
|
.string()
|
|
401
490
|
.min(1)
|
|
@@ -410,6 +499,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
410
499
|
},
|
|
411
500
|
)
|
|
412
501
|
.optional(),
|
|
502
|
+
/** Faces and roles of the board's agents, keyed by agent name; default `{}`. */
|
|
413
503
|
agents: BOARD_AGENTS.default({}),
|
|
414
504
|
})
|
|
415
505
|
.default({ agents: {} }),
|
|
@@ -419,6 +509,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
419
509
|
claude: z
|
|
420
510
|
.strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
|
|
421
511
|
.default({ settings: {} }),
|
|
512
|
+
/** Project hooks, each an `event`, an optional `matcher` and a `command`; `vulcan sync` merges them into the agent settings. Default `[]`. */
|
|
422
513
|
hooks: z
|
|
423
514
|
.array(
|
|
424
515
|
z.strictObject({ event: HOOK_EVENT, matcher: z.string().optional(), command: z.string() }),
|
|
@@ -427,6 +518,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
427
518
|
/** The session-start digest: the rule IDs it repeats as "the rules sessions drop most" - base or the project's own. */
|
|
428
519
|
digest: z
|
|
429
520
|
.strictObject({
|
|
521
|
+
/** Rule IDs the digest repeats as dropped most, each matching the rule ID pattern; default the shipped list of base rules. */
|
|
430
522
|
oftenDropped: z
|
|
431
523
|
.array(z.string().regex(ConfigConstants.RULE_ID_PATTERN))
|
|
432
524
|
.default(ConfigConstants.DEFAULT_OFTEN_DROPPED),
|
|
@@ -444,20 +536,28 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
444
536
|
* read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
|
|
445
537
|
* project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
|
|
446
538
|
* 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
|
|
539
|
+
* writes both to the manifest, where the hooks read them, and writes `outside` (when it is `deny`),
|
|
540
|
+
* `toolOwnedPaths` and the path entries of `writes.trustedScripts` there too, so a config this VULCAN cannot
|
|
541
|
+
* parse changes no guard. `outside` is what `guard-outside` does with a
|
|
448
542
|
* write outside the project: `ask` (the default) or `deny`. Where the agent runs in an auto mode an ask can be
|
|
449
543
|
* approved without the owner seeing it, so a project that wants the line held sets `deny`.
|
|
450
544
|
*/
|
|
451
545
|
guard: z
|
|
452
546
|
.strictObject({
|
|
547
|
+
/** Absolute globs (`~` and `$NAME` allowed) of tool-managed stores, added to the built-in list; default `[]`. */
|
|
453
548
|
toolOwnedPaths: z.array(z.string().min(1)).default([]),
|
|
549
|
+
/** What guard-outside does with a write outside the project: `ask` or `deny`; default `ask`. */
|
|
454
550
|
outside: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
|
|
551
|
+
/** Write guard lists: scripts guard-writes trusts and the project's own deploy and migrate commands; both default to `[]`. */
|
|
455
552
|
writes: z
|
|
456
553
|
.strictObject({
|
|
554
|
+
/** Repo-relative `.ts` scripts guard-writes does not read for mutating calls; a path or `{ script, readOnly }`. Default `[]`. */
|
|
457
555
|
trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
|
|
556
|
+
/** The project's own deploy and migrate commands guard-writes asks about; default `[]`. */
|
|
458
557
|
commands: z.array(GUARD_COMMAND).default([]),
|
|
459
558
|
})
|
|
460
559
|
.default({ trustedScripts: [], commands: [] }),
|
|
560
|
+
/** Git guard settings; `askPush` lists the branches a plain `git push` asks about, `*` for any run of characters. Default `[]`. */
|
|
461
561
|
git: z.strictObject({ askPush: z.array(PUSH_TARGET).default([]) }).default({ askPush: [] }),
|
|
462
562
|
})
|
|
463
563
|
.default({
|
|
@@ -476,22 +576,29 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
476
576
|
*/
|
|
477
577
|
commit: z
|
|
478
578
|
.strictObject({
|
|
579
|
+
/** Checks on the text of a commit message: the agent signature policy and the subject shape. */
|
|
479
580
|
message: z
|
|
480
581
|
.strictObject({
|
|
582
|
+
/** Rules about agent names in a commit message: signature policy, extra names and allowed names. */
|
|
481
583
|
agent: z
|
|
482
584
|
.strictObject({
|
|
585
|
+
/** Policy for an agent trailer or "generated with" line in a commit message: `allow` or `deny`; default `allow`. */
|
|
483
586
|
signature: z
|
|
484
587
|
.custom<TAgentSignaturePolicy>(
|
|
485
588
|
(value) => typeof value === 'string' && AgentSignaturePolicies.isValid(value),
|
|
486
589
|
{ message: `one of ${[...AgentSignaturePolicies.SCHEME_SET].join(', ')}` },
|
|
487
590
|
)
|
|
488
591
|
.default(AgentSignaturePolicies.ALLOW),
|
|
592
|
+
/** Agent names added to the shipped list; a co-author or `Generated with` line naming one is flagged under `deny`. Default `[]`. */
|
|
489
593
|
names: z.array(AGENT_NAME).default([]),
|
|
594
|
+
/** Whole co-author names never flagged, for a person who shares a name with an agent; default `[]`. */
|
|
490
595
|
allow: z.array(AGENT_NAME).default([]),
|
|
491
596
|
})
|
|
492
597
|
.default({ signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] }),
|
|
598
|
+
/** The project's own shape for the commit subject line; absent means no subject check. */
|
|
493
599
|
subject: z
|
|
494
600
|
.strictObject({
|
|
601
|
+
/** Regular expression the commit subject must match, 1 or more characters; an invalid expression is rejected. */
|
|
495
602
|
pattern: z
|
|
496
603
|
.string()
|
|
497
604
|
.min(1)
|
|
@@ -502,6 +609,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
502
609
|
context.addIssue({ code: 'custom', message: error });
|
|
503
610
|
}
|
|
504
611
|
}),
|
|
612
|
+
/** Text shown with the error when a subject does not match `pattern`; absent means none. */
|
|
505
613
|
hint: z.string().min(1).optional(),
|
|
506
614
|
})
|
|
507
615
|
.optional(),
|
|
@@ -518,8 +626,10 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
518
626
|
*/
|
|
519
627
|
ci: z
|
|
520
628
|
.strictObject({
|
|
629
|
+
/** Which changed files make `vulcan ci affected` treat every package as affected. */
|
|
521
630
|
affected: z
|
|
522
631
|
.strictObject({
|
|
632
|
+
/** Root-relative globs, no leading `/` and no `..` segment, added to the shipped list of files that touch every package; default `[]`. */
|
|
523
633
|
global: z
|
|
524
634
|
.array(
|
|
525
635
|
z
|
|
@@ -545,7 +655,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
545
655
|
*/
|
|
546
656
|
events: z
|
|
547
657
|
.strictObject({
|
|
658
|
+
/** `true` makes `vulcan sync` install the hooks that write the event log; default `false`. */
|
|
548
659
|
log: z.boolean().default(false),
|
|
660
|
+
/** Absolute folder that takes the event log instead of the project's own; absent means the project's `.agents/local/events`. */
|
|
549
661
|
dir: z
|
|
550
662
|
.string()
|
|
551
663
|
.min(1)
|
|
@@ -568,7 +680,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
568
680
|
message: 'a size such as 50MB, 200MB or 1GB',
|
|
569
681
|
})
|
|
570
682
|
.optional(),
|
|
683
|
+
/** Most day files kept in the log; at least 1, default 30 when `log` is on. */
|
|
571
684
|
maxFiles: z.number().int().min(1).optional(),
|
|
685
|
+
/** Oldest age, in days, a day file may reach; at least 1, default 30 when `log` is on. */
|
|
572
686
|
maxAgeDays: z.number().int().min(1).optional(),
|
|
573
687
|
})
|
|
574
688
|
.default({ log: false }),
|
|
@@ -579,12 +693,15 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
579
693
|
*/
|
|
580
694
|
local: z
|
|
581
695
|
.strictObject({
|
|
696
|
+
/** `true` lets the session-start hook clean the safe part of `.agents/local/` at most once a day; default `true`. */
|
|
582
697
|
autoClean: z.boolean().default(true),
|
|
583
698
|
})
|
|
584
699
|
.default({ autoClean: true }),
|
|
585
700
|
});
|
|
586
701
|
|
|
702
|
+
/** What a project writes in `.configs/vulcan.config.mts`: every key optional or defaulted, unknown keys refused. */
|
|
587
703
|
export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
|
|
704
|
+
/** The config as the CLI reads it: every default filled in. */
|
|
588
705
|
export type TResolvedConfig = z.output<typeof VULCAN_CONFIG_SCHEMA>;
|
|
589
706
|
|
|
590
707
|
/** 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/doctor/checks.ts
CHANGED
|
@@ -727,6 +727,16 @@ export class ProjectContract {
|
|
|
727
727
|
];
|
|
728
728
|
}
|
|
729
729
|
|
|
730
|
+
case CommitHookStates.OTHER_PROJECT: {
|
|
731
|
+
return [
|
|
732
|
+
createViolation({
|
|
733
|
+
check: DoctorChecks.COMMIT_HOOK,
|
|
734
|
+
file,
|
|
735
|
+
message: `this project's commit check is not installed: ${status.note ?? fix}`,
|
|
736
|
+
}),
|
|
737
|
+
];
|
|
738
|
+
}
|
|
739
|
+
|
|
730
740
|
default: {
|
|
731
741
|
return [];
|
|
732
742
|
}
|
|
@@ -1,29 +1,55 @@
|
|
|
1
1
|
export class DoctorChecks {
|
|
2
|
+
/** The config file: missing, unloadable or without a default export is an error, and the only check run then. */
|
|
2
3
|
static readonly CONFIG = 'config';
|
|
4
|
+
/** The required files (AGENTS.md, .agents/rules.md, knowledge bundle root); a missing one is an error. */
|
|
3
5
|
static readonly LAYOUT = 'layout';
|
|
6
|
+
/** Rule references in .agents/rules.md; one to a base rule the base does not carry is an error. */
|
|
4
7
|
static readonly RULE_IDS = 'rule-ids';
|
|
8
|
+
/** The rule slot choices in the config; an unknown option or a key that is not a slot is an error. */
|
|
5
9
|
static readonly RULE_SLOTS = 'rule-slots';
|
|
10
|
+
/** Skill names and lint: an error; a skill description with no "Use when" part is a warning. */
|
|
6
11
|
static readonly SKILLS = 'skills';
|
|
12
|
+
/** The Makefile include of vulcan.mk and clashes with shipped target names; a violation is an error. */
|
|
7
13
|
static readonly MAKE = 'make';
|
|
14
|
+
/** Project hooks in the config; one that registers a shipped hook path is an error. */
|
|
8
15
|
static readonly HOOKS = 'hooks';
|
|
16
|
+
/** Generated tool files, settings and links against the config; a missing or stale one is an error. */
|
|
9
17
|
static readonly ADAPTERS = 'adapters';
|
|
18
|
+
/** Packages declare @venizia/dev-configs and lint configs import the shared style; a miss is an error. */
|
|
10
19
|
static readonly STYLE = 'style';
|
|
20
|
+
/** The committed .agents/vulcan.manifest.json against the config; a missing or outdated one is an error. */
|
|
11
21
|
static readonly MANIFEST = 'manifest';
|
|
22
|
+
/** Git tags matching atlas.tagPattern that name no declared package, alias or ignored tag; an error. */
|
|
12
23
|
static readonly TAGS = 'tags';
|
|
24
|
+
/** Workspaces declare packages and the knowledge index no longer holds scaffold text; a miss is an error. */
|
|
13
25
|
static readonly SCAFFOLD = 'scaffold';
|
|
26
|
+
/** Layout folders are workspaces and every package lives in a listed folder; a miss is an error. */
|
|
14
27
|
static readonly APPS = 'apps';
|
|
28
|
+
/** The standard package.json scripts of each app, and retired names still in use; a note only. */
|
|
15
29
|
static readonly SCRIPTS = 'scripts';
|
|
30
|
+
/** The stored agents file must parse and name known agents (an error); a stale Atlas block in AGENTS.md is a note. */
|
|
16
31
|
static readonly AGENTS = 'agents';
|
|
32
|
+
/** A root .dockerignore that is missing or lacks .env lines while an app has a Dockerfile; a warning. */
|
|
17
33
|
static readonly DOCKERIGNORE = 'dockerignore';
|
|
34
|
+
/** The .mcp.json atlas entry, its git visibility and the Claude settings that enable atlas; a warning. */
|
|
18
35
|
static readonly MCP = 'mcp';
|
|
36
|
+
/** The bunfig.toml [fmt] oxfmt setup, no fmt script and no leftover oxfmt config; a warning. */
|
|
19
37
|
static readonly FORMAT = 'format';
|
|
38
|
+
/** The .agents/local workspace, stray worktrees, leftovers, reply switch, launch file and size: mostly warnings, some notes. */
|
|
20
39
|
static readonly LOCAL = 'local';
|
|
40
|
+
/** The personal profile file: unreadable, not gitignored or tracked by git; a warning. */
|
|
21
41
|
static readonly PROFILE = 'profile';
|
|
42
|
+
/** Guard config: trusted scripts and added patterns are notes; a stale or subcommand-less trusted script is a warning. */
|
|
22
43
|
static readonly GUARDS = 'guards';
|
|
44
|
+
/** The clone commit-msg hook when a commit check is on: missing, stale or not calling commit-check; a warning. */
|
|
23
45
|
static readonly COMMIT_HOOK = 'commit-hook';
|
|
46
|
+
/** The events.dir folder when outside the project: missing, not a folder or not writable; a warning. */
|
|
24
47
|
static readonly EVENTS_DIR = 'events-dir';
|
|
48
|
+
/** Today's event file when it alone is over events.maxSize; a warning. */
|
|
25
49
|
static readonly EVENTS_SIZE = 'events-size';
|
|
50
|
+
/** The event log is on but project.key is unset, so no flow can be created; a warning. */
|
|
26
51
|
static readonly PROJECT_KEY = 'project-key';
|
|
52
|
+
/** Tracked files holding keys, tokens, URL credentials, IPv4 or machine paths: a warning; the count of acknowledged files: a note. */
|
|
27
53
|
static readonly PRIVATE_VALUES = 'private-values';
|
|
28
54
|
}
|
|
29
55
|
|
package/src/doctor/runner.ts
CHANGED
|
@@ -6,6 +6,7 @@ import { TagCheck } from './tags.ts';
|
|
|
6
6
|
import { DoctorChecks } from './common/index.ts';
|
|
7
7
|
import type { IViolation } from './common/index.ts';
|
|
8
8
|
|
|
9
|
+
/** Runs the doctor checks and sorts their findings into violations, notes and warnings; used by `vulcan doctor`. */
|
|
9
10
|
export class DoctorRunner {
|
|
10
11
|
/** Every violation of the VULCAN contract in the project at `root`; empty means conformant. */
|
|
11
12
|
static async runChecks(opts: { root: string }): Promise<IViolation[]> {
|
package/src/doctor/schema.ts
CHANGED
|
@@ -10,17 +10,21 @@ const KIND = z.custom<TPrivateValueKind>(
|
|
|
10
10
|
|
|
11
11
|
/** A decision to keep private values in files: where, which kinds (all when absent), and why. */
|
|
12
12
|
const ACKNOWLEDGEMENT = z.strictObject({
|
|
13
|
+
/** Glob relative to the repo root, with no `..`, of the files that may keep private values. */
|
|
13
14
|
path: z
|
|
14
15
|
.string()
|
|
15
16
|
.min(1)
|
|
16
17
|
.refine((value) => !isAbsolute(value) && !value.split(/[\\/]/).includes('..'), {
|
|
17
18
|
message: 'a glob relative to the repo root, without ..',
|
|
18
19
|
}),
|
|
20
|
+
/** Kinds of private value the decision covers: `private-key`, `token`, `url-credentials`, `ipv4` or `machine-path`; at least one, all kinds when absent. */
|
|
19
21
|
kinds: z.array(KIND).min(1).optional(),
|
|
22
|
+
/** Why the private values may stay in these files; trimmed, at least one character. */
|
|
20
23
|
reason: z.string().trim().min(1),
|
|
21
24
|
});
|
|
22
25
|
|
|
23
26
|
export const DOCTOR_SCHEMA = z.strictObject({
|
|
27
|
+
/** Private values doctor tolerates: `acknowledged` lists files that may keep them, each with a reason; default none. */
|
|
24
28
|
privateValues: z
|
|
25
29
|
.strictObject({ acknowledged: z.array(ACKNOWLEDGEMENT).default([]) })
|
|
26
30
|
.default({ acknowledged: [] }),
|
package/src/hooks/owner-reply.ts
CHANGED
|
@@ -33,6 +33,11 @@ const FIXES: Record<string, string> = {
|
|
|
33
33
|
const loadOwnerView = async (opts: { projectRoot: string }): Promise<IOwnerView> => {
|
|
34
34
|
const loaded = await ConfigLoader.load({ root: opts.projectRoot });
|
|
35
35
|
const profile = OwnerProfile.read({ root: opts.projectRoot });
|
|
36
|
+
const note = ConfigLoader.unreadableNote({ loaded });
|
|
37
|
+
|
|
38
|
+
if (note !== undefined) {
|
|
39
|
+
console.error(`vulcan: the owner-reply hook: ${note}`);
|
|
40
|
+
}
|
|
36
41
|
|
|
37
42
|
return OwnerView.resolve({
|
|
38
43
|
owner: loaded.ok ? loaded.config.owner : OWNER_SCHEMA.parse(undefined),
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
+
import { GuardDecisions } from './common/index.ts';
|
|
3
4
|
import type { IReadOnlyScript } from './common/index.ts';
|
|
4
5
|
|
|
5
6
|
/** A command the project says is a database write or a deploy: guard-writes asks on a match. */
|
|
@@ -15,6 +16,12 @@ interface IGuardPolicy {
|
|
|
15
16
|
askPush: string[];
|
|
16
17
|
/** `guard.writes.readOnlyScripts`; absent when the manifest lists none. */
|
|
17
18
|
readOnlyScripts?: IReadOnlyScript[];
|
|
19
|
+
/** `guard.outside`: what guard-outside does with a write outside the project; `ask` when the manifest says nothing. */
|
|
20
|
+
outside: string;
|
|
21
|
+
/** `guard.toolOwnedPaths`: stores a tool manages itself, which guard-outside lets through. */
|
|
22
|
+
toolOwnedPaths: string[];
|
|
23
|
+
/** The path entries of `guard.writes.trustedScripts`. */
|
|
24
|
+
trustedScripts: string[];
|
|
18
25
|
}
|
|
19
26
|
|
|
20
27
|
/** Spelt out: the blocking hooks import nothing that reads the package. */
|
|
@@ -98,7 +105,13 @@ export class ProjectGuards {
|
|
|
98
105
|
*/
|
|
99
106
|
static readPolicy(opts: { root: string }): IGuardPolicy {
|
|
100
107
|
const path = join(opts.root, GUARD_MANIFEST_FILE);
|
|
101
|
-
const empty: IGuardPolicy = {
|
|
108
|
+
const empty: IGuardPolicy = {
|
|
109
|
+
commands: [],
|
|
110
|
+
askPush: [],
|
|
111
|
+
outside: GuardDecisions.ASK,
|
|
112
|
+
toolOwnedPaths: [],
|
|
113
|
+
trustedScripts: [],
|
|
114
|
+
};
|
|
102
115
|
|
|
103
116
|
if (!existsSync(path)) {
|
|
104
117
|
return empty;
|
|
@@ -128,6 +141,12 @@ export class ProjectGuards {
|
|
|
128
141
|
const listed = isRecord(writes) ? writes.value['commands'] : undefined;
|
|
129
142
|
const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
|
|
130
143
|
const targets = isRecord(git) ? git.value['askPush'] : undefined;
|
|
144
|
+
const owned = guard.value['toolOwnedPaths'];
|
|
145
|
+
const trusted = isRecord(writes) ? writes.value['trustedScripts'] : undefined;
|
|
146
|
+
const words = (value: unknown): string[] =>
|
|
147
|
+
(Array.isArray(value) ? value : []).filter(
|
|
148
|
+
(item): item is string => typeof item === 'string' && item !== '',
|
|
149
|
+
);
|
|
131
150
|
const readOnlyScripts = (Array.isArray(scripts) ? scripts : []).flatMap((entry) => {
|
|
132
151
|
const script = readOnlyScriptOf({ value: entry });
|
|
133
152
|
|
|
@@ -140,9 +159,11 @@ export class ProjectGuards {
|
|
|
140
159
|
|
|
141
160
|
return check === undefined ? [] : [check];
|
|
142
161
|
}),
|
|
143
|
-
askPush: (
|
|
144
|
-
|
|
145
|
-
|
|
162
|
+
askPush: words(targets),
|
|
163
|
+
outside:
|
|
164
|
+
guard.value['outside'] === GuardDecisions.DENY ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
165
|
+
toolOwnedPaths: words(owned),
|
|
166
|
+
trustedScripts: words(trusted),
|
|
146
167
|
...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
|
|
147
168
|
};
|
|
148
169
|
}
|