@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.
Files changed (50) hide show
  1. package/README.md +19 -14
  2. package/base/hooks/guard-outside.ts +6 -17
  3. package/base/hooks/guard-writes.ts +3 -24
  4. package/base/rules.md +3 -3
  5. package/base/skills/visualize-work/SKILL.md +1 -1
  6. package/base/skills/visualize-work/references/spec.md +1 -1
  7. package/package.json +3 -3
  8. package/src/agents/resolve.ts +1 -0
  9. package/src/board/common/types.ts +2 -2
  10. package/src/board/schema.ts +4 -1
  11. package/src/board/settings.ts +1 -1
  12. package/src/commands/help.command.ts +2 -63
  13. package/src/commands/table.ts +315 -0
  14. package/src/commit/check.ts +1 -0
  15. package/src/commit/common/constants.ts +2 -0
  16. package/src/commit/hook.ts +44 -4
  17. package/src/common/constants.ts +6 -3
  18. package/src/common/env-variables.ts +37 -0
  19. package/src/common/index.ts +1 -0
  20. package/src/config/loader.ts +22 -0
  21. package/src/config/schema.ts +121 -4
  22. package/src/create/add-app.ts +5 -0
  23. package/src/create/common/constants.ts +5 -3
  24. package/src/create/preset.ts +1 -0
  25. package/src/doctor/checks.ts +10 -0
  26. package/src/doctor/common/constants.ts +26 -0
  27. package/src/doctor/runner.ts +1 -0
  28. package/src/doctor/schema.ts +4 -0
  29. package/src/hooks/owner-reply.ts +5 -0
  30. package/src/hooks/project-guards.ts +25 -4
  31. package/src/hooks/session-digest.ts +9 -0
  32. package/src/init/scaffold.ts +1 -0
  33. package/src/local/auto-clean.ts +2 -1
  34. package/src/local/clean.ts +1 -0
  35. package/src/manifest/render.ts +48 -6
  36. package/src/owner/constants.ts +3 -1
  37. package/src/owner/profile.ts +1 -0
  38. package/src/owner/schema.ts +37 -6
  39. package/src/router.ts +4 -130
  40. package/src/rules/base.ts +1 -0
  41. package/src/signals/loop.ts +1 -0
  42. package/src/skills/frontmatter.ts +1 -0
  43. package/src/sync/planner.ts +1 -0
  44. package/src/theme/index.ts +1 -0
  45. package/src/theme/tokens.ts +305 -0
  46. package/src/ui/prompt.ts +1 -0
  47. package/src/visualize/page.ts +4 -4
  48. package/src/visualize/render.ts +2 -1
  49. package/src/visualize/theme.ts +27 -10
  50. package/src/wiki/anchors.ts +1 -0
@@ -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
- accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #8a5a20'),
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(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #dead6a')
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(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #01579b')
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. `outside` is what `guard-outside` does with a
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). */
@@ -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 = 'VULCAN_NO_INSTALL';
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 = 'VULCAN_BUN';
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 = 'VULCAN_GIT';
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';
@@ -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: {
@@ -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
 
@@ -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[]> {
@@ -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: [] }),
@@ -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 = { commands: [], askPush: [] };
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: (Array.isArray(targets) ? targets : []).filter(
144
- (target): target is string => typeof target === 'string' && target !== '',
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
  }