@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.
Files changed (66) hide show
  1. package/README.md +26 -18
  2. package/base/hooks/guard-outside.ts +10 -19
  3. package/base/hooks/guard-writes.ts +3 -24
  4. package/base/make/vulcan.mk +1 -4
  5. package/base/rules.md +4 -4
  6. package/base/skills/visualize-work/SKILL.md +1 -1
  7. package/base/skills/visualize-work/references/spec.md +1 -1
  8. package/base/templates/board.html +10 -110
  9. package/package.json +3 -3
  10. package/src/agents/resolve.ts +1 -0
  11. package/src/board/command.ts +16 -1
  12. package/src/board/common/constants.ts +2 -0
  13. package/src/board/common/types.ts +2 -2
  14. package/src/board/page.ts +57 -5
  15. package/src/board/schema.ts +4 -1
  16. package/src/board/server.ts +13 -2
  17. package/src/board/settings.ts +1 -1
  18. package/src/commands/graph.command.ts +6 -0
  19. package/src/commands/help.command.ts +2 -63
  20. package/src/commands/index.ts +2 -0
  21. package/src/commands/sync.command.ts +5 -1
  22. package/src/commands/table.ts +327 -0
  23. package/src/commit/check.ts +1 -0
  24. package/src/commit/common/constants.ts +2 -0
  25. package/src/commit/hook.ts +44 -4
  26. package/src/common/constants.ts +7 -3
  27. package/src/common/env-variables.ts +37 -0
  28. package/src/common/index.ts +1 -0
  29. package/src/config/loader.ts +22 -0
  30. package/src/config/schema.ts +162 -20
  31. package/src/create/add-app.ts +5 -0
  32. package/src/create/common/constants.ts +5 -3
  33. package/src/create/preset.ts +1 -0
  34. package/src/create/scratch.ts +2 -1
  35. package/src/doctor/checks.ts +106 -4
  36. package/src/doctor/common/constants.ts +26 -0
  37. package/src/doctor/runner.ts +3 -0
  38. package/src/doctor/schema.ts +4 -0
  39. package/src/hooks/owner-reply.ts +5 -0
  40. package/src/hooks/project-guards.ts +28 -4
  41. package/src/hooks/project-tmp.ts +39 -4
  42. package/src/hooks/session-digest.ts +9 -0
  43. package/src/init/scaffold.ts +1 -0
  44. package/src/local/auto-clean.ts +2 -1
  45. package/src/local/browser-socket.ts +33 -0
  46. package/src/local/clean.ts +1 -0
  47. package/src/local/index.ts +1 -0
  48. package/src/local/scan.ts +33 -9
  49. package/src/manifest/render.ts +70 -9
  50. package/src/owner/constants.ts +3 -1
  51. package/src/owner/profile.ts +1 -0
  52. package/src/owner/schema.ts +37 -6
  53. package/src/router.ts +4 -130
  54. package/src/rules/base.ts +1 -0
  55. package/src/signals/loop.ts +1 -0
  56. package/src/skills/frontmatter.ts +1 -0
  57. package/src/sync/claude-launch.ts +12 -12
  58. package/src/sync/local-choice.ts +32 -3
  59. package/src/sync/planner.ts +1 -0
  60. package/src/theme/index.ts +1 -0
  61. package/src/theme/tokens.ts +410 -0
  62. package/src/ui/prompt.ts +1 -0
  63. package/src/visualize/page.ts +4 -4
  64. package/src/visualize/render.ts +2 -1
  65. package/src/visualize/theme.ts +43 -12
  66. 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
 
@@ -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
- const VIZ_OUTPUT = '.agents/knowledge/viz.html';
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
- viz: z
298
- .strictObject({
299
- outputs: z.array(z.string()).default([VIZ_OUTPUT]),
300
- brand: z.string().optional(),
301
- copy: z.record(z.string(), z.unknown()).optional(),
302
- })
303
- .default({ outputs: [VIZ_OUTPUT] }),
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
- accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #8a5a20'),
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(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #dead6a')
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(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #01579b')
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. `outside` is what `guard-outside` does with a
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). */
@@ -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: {
@@ -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 = join(local, 'tmp');
51
+ const parent = ProjectTmp.projectOf({ root: opts.root });
51
52
 
52
53
  mkdirSync(parent, { recursive: true });
53
54