@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -1,33 +1,32 @@
1
- import { isAbsolute } from 'node:path';
2
1
  import { z } from 'zod';
3
- import { ProjectLayout } from '../common/constants.ts';
2
+ import { SiteUrl } from '@venizia/vulcan-atlas';
4
3
  import { LayoutFolder } from '../common/layout-folder.ts';
5
4
  import { DOCTOR_SCHEMA } from '../doctor/schema.ts';
6
5
  import { GuardDecisions } from '../hooks/common/constants.ts';
7
- import { HostPatterns } from '../hooks/host-pattern.ts';
8
6
  import { OWNER_SCHEMA } from '../owner/schema.ts';
7
+ import { RulePacks } from '../rules/packs.ts';
9
8
  import { AgentSignaturePolicies } from '../commit/common/index.ts';
10
9
  import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
11
10
  import { SubjectShape } from '../commit/subject.ts';
12
- import { BoardServe } from '../board/common/constants.ts';
11
+ import { BoardConstants, BoardServe, ProviderTypes } from '../board/common/constants.ts';
13
12
  import { ProjectKey } from '../events/project-key.ts';
13
+ import { ThemeTokens } from '../theme/index.ts';
14
+ import { ProjectTheme } from '../visualize/theme.ts';
15
+ import { BoardLogo } from '../board/logo.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';
17
19
  import {
18
20
  CodingAgents,
19
21
  ConfigConstants,
20
- HookEvents,
21
22
  LibraryKinds,
22
23
  PackageKinds,
24
+ TemplatePlaceholders,
23
25
  } from './common/index.ts';
24
26
 
25
27
  const CODING_AGENT = z.string().refine((value) => CodingAgents.isValid(value), {
26
28
  message: `one of: ${[...CodingAgents.SCHEME_SET].join(', ')}`,
27
29
  });
28
- const HOOK_EVENT = z.string().refine((value) => HookEvents.isValid(value), {
29
- message: `one of: ${[...HookEvents.SCHEME_SET].join(', ')}`,
30
- });
31
30
 
32
31
  /** An ed25519 public key as `atlas index keygen` prints it: the base64 of its 32 raw bytes, nothing else. */
33
32
  const INDEX_PUBLIC_KEY = z.string().refine(
@@ -49,13 +48,17 @@ const compiles = (value: string): boolean => {
49
48
 
50
49
  /** 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
50
  const GUARD_COMMAND = z.strictObject({
51
+ /** Which rule the command falls under: `V-W-02` for a database write, `V-W-03` for a deploy. */
52
52
  rule: z.enum(['V-W-02', 'V-W-03']),
53
+ /** Short name of the action, shown when guard-writes asks; 1 to 120 characters. */
53
54
  what: z.string().min(1).max(120),
55
+ /** JavaScript regular expression, 1 to 500 characters, matched against a shell command; guard-writes asks when it matches. */
54
56
  pattern: z
55
57
  .string()
56
58
  .min(1)
57
59
  .max(500)
58
60
  .refine(compiles, { message: 'a regular expression (JavaScript syntax)' }),
61
+ /** `true` matches `pattern` without regard to case; default: case-sensitive. */
59
62
  ignoreCase: z.boolean().optional(),
60
63
  });
61
64
 
@@ -64,7 +67,16 @@ const PUSH_TARGET = z
64
67
  .string()
65
68
  .regex(/^[A-Za-z0-9._/*-]+$/, { message: 'a branch name, with * for any run of characters' });
66
69
 
67
- /** A layout folder: 1 to 4 plain segments, never climbing, never absolute (the validator `guard-package` shares). */
70
+ /** A key that was removed: optional, and refused when present with the key and what to do, instead of a bare "unrecognized key". */
71
+ const REMOVED_OKF_KEY = (opts: { fix: string }) =>
72
+ z
73
+ .unknown()
74
+ .superRefine((_value, context) => {
75
+ context.addIssue({ code: 'custom', message: `removed: ${opts.fix}` });
76
+ })
77
+ .optional();
78
+
79
+ /** A layout folder: 1 to 4 plain segments, never climbing, never absolute. */
68
80
  const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
69
81
  const problem = LayoutFolder.layoutFolderProblem({ folder: value });
70
82
 
@@ -73,42 +85,16 @@ const LAYOUT_FOLDER = z.string().superRefine((value, context) => {
73
85
  }
74
86
  });
75
87
 
76
- /** A script `guard-writes` may trust: a repo-relative `.ts` path - no glob, no `~`, never climbing out of the repo. */
77
- const TRUSTED_SCRIPT_PATH = z.string().superRefine((value, context) => {
78
- const problem = /[*?[\]{}!]/.test(value)
79
- ? 'no globs: list each script by its exact path'
80
- : isAbsolute(value) || value.startsWith('~')
81
- ? 'a path relative to the repo root'
82
- : value.split(/[\\/]/).includes('..')
83
- ? 'a path inside the repo, without ..'
84
- : /\.ts$/.test(value)
85
- ? undefined
86
- : 'a .ts file - guard-writes reads only bun scripts ending in .ts';
87
-
88
- if (problem !== undefined) {
89
- context.addIssue({ code: 'custom', message: `${value}: ${problem}` });
90
- }
91
- });
92
-
93
- /**
94
- * A trusted script, whole or by subcommand: a path trusts the whole file; an object trusts only the calls
95
- * whose first argument after the script is one of `readOnly` (one word each, matched exactly).
96
- */
97
- const READ_ONLY_WORD = z
98
- .string()
99
- .regex(
100
- /^[A-Za-z0-9_.:-]+$/,
101
- 'one plain word: letters, digits and _ . : - only, no spaces or globs',
102
- );
103
-
104
- const TRUSTED_SCRIPT = z.union([
105
- TRUSTED_SCRIPT_PATH,
106
- z.strictObject({ script: TRUSTED_SCRIPT_PATH, readOnly: z.array(READ_ONLY_WORD).min(1) }),
107
- ]);
108
-
109
88
  /** One folder, or a list of them: a side whose apps are grouped keeps each group's folder. */
110
89
  const LAYOUT_VALUE = z.union([LAYOUT_FOLDER, z.array(LAYOUT_FOLDER).min(1)]);
111
90
 
91
+ /** The bounds of `atlas.limits.download`: the ones atlas reads the value within; outside them it keeps its default. */
92
+ const MIN_DOWNLOAD_BYTES = 1024 * 1024;
93
+ const MAX_DOWNLOAD_BYTES = 1024 * 1024 * 1024;
94
+
95
+ /** A source repository atlas will not give to git: an `http://` or `git://` URL (clear text), or a `scheme::` remote helper (it runs a command). */
96
+ const SOURCE_TRANSPORT = /^(?:(http|git):\/\/|[a-z][a-z0-9+.-]*::)/i;
97
+
112
98
  /** An npm package name, lower case: the pattern and the length atlas applies to every package name of the manifest. */
113
99
  const NPM_NAME_PATTERN = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
114
100
  const NPM_NAME_MAX_LENGTH = 214;
@@ -128,11 +114,15 @@ const AGENT_NAME = z
128
114
  .regex(/[\p{L}\p{N}]/u, { message: 'a name with at least one letter or digit' });
129
115
 
130
116
  const PROJECT_PACKAGE = z.strictObject({
117
+ /** Unique key of the package, not necessarily its folder name; lower case letters, digits, `.` and `-`, starting with a letter or digit. */
131
118
  dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
119
+ /** The npm package name: lower case, optional `@scope/`, at most 214 characters. */
132
120
  name: NPM_PACKAGE_NAME,
133
121
  /** Where the package lives, from the root; default `packages/<dir>`. */
134
122
  path: z.string().optional(),
123
+ /** Extra names accepted as the `<dir>` of a release tag; default `[]`. */
135
124
  aliases: z.array(z.string()).default([]),
125
+ /** `true` marks a package that is gone but whose releases stay readable; its path may be reused. Default `false`. */
136
126
  retired: z.boolean().default(false),
137
127
  /** A library a preset made lives anywhere a workspace glob covers; absent means an app or a plain package. */
138
128
  kind: z.enum([PackageKinds.APP, PackageKinds.LIB]).optional(),
@@ -187,29 +177,37 @@ const checkPackagesUnique = (
187
177
  * leading `[#<issue>] ` is optional and a trailing ` [<mode>]` is tolerated. A release train that
188
178
  * tags once leaves `<dir>` out (`v<version>`).
189
179
  */
190
- const RELEASE_TEMPLATE = z.string().refine((value) => value.includes('<version>'), {
191
- message: 'a template with <version> (and <dir> for per-package releases)',
192
- });
180
+ const RELEASE_TEMPLATE = z
181
+ .string()
182
+ .refine((value) => value.includes('<version>'), {
183
+ message: 'a template with <version> (and <dir> for per-package releases)',
184
+ })
185
+ .superRefine((value, context) => {
186
+ const unknown = TemplatePlaceholders.unknownIn({ template: value });
187
+
188
+ if (unknown.length > 0) {
189
+ context.addIssue({
190
+ code: 'custom',
191
+ message: TemplatePlaceholders.problemOf({ unknown }),
192
+ });
193
+ }
194
+ });
193
195
 
194
196
  /** A renderer by id: a built-in, or a project module (`module`); a bare string is the id alone. */
195
197
  const OKF_RENDERER = z.union([
196
198
  z.string().transform((id) => ({ id, options: {} })),
197
199
  z.strictObject({
200
+ /** Name of the renderer: a built-in, or the identifier a project module registers. */
198
201
  id: z.string(),
202
+ /** Path of the project module that exports the renderer; absent means a built-in. */
199
203
  module: z.string().optional(),
204
+ /** Options passed to the renderer; default `{}`. */
200
205
  options: z.record(z.string(), z.unknown()).default({}),
201
206
  }),
202
207
  ]);
203
208
 
204
- /** A host name, or a pattern whose only wildcard is `*`; a `$VAR` stands for a host the shell expands. Never a user, a path or a port. */
205
- const REMOTE_HOST = z
206
- .string()
207
- .regex(HostPatterns.SHAPE, 'a host name or a pattern with *, not a user, a path or a port')
208
- .refine((value) => HostPatterns.hasLiteral({ value }), {
209
- message: 'a pattern needs at least one letter or digit, not only * . - or _',
210
- });
211
-
212
- const VIZ_OUTPUT = '.agents/knowledge/viz.html';
209
+ /** A colour of a design token: six-digit hex, or eight-digit with an alpha channel for lines and soft text. */
210
+ const TOKEN_COLOUR = z.string().regex(ThemeTokens.COLOUR, 'a hex colour like #8a5a20');
213
211
 
214
212
  /** `.configs/vulcan.config.*` - strict: an unknown key is a typo, and a typo is an error. */
215
213
  export const VULCAN_CONFIG_SCHEMA = z.strictObject({
@@ -224,12 +222,24 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
224
222
  .optional(),
225
223
  /** The project's suggested agents; each developer's own choice lives in `.agents/vulcan.local.json`. */
226
224
  agents: z.array(CODING_AGENT).optional(),
225
+ /** Choice of each base rule slot, keyed by rule ID (for example `V-W-01`) to the option picked; default `{}`. */
227
226
  rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
227
+ /** The shipped rule packs this project follows, by name (`venizia`): rules for one stack, outside the base rules every project gets. */
228
+ packs: z
229
+ .array(
230
+ z.string().refine((name) => RulePacks.names().includes(name), {
231
+ error: () => `a rule pack VULCAN ships: ${RulePacks.names().join(', ')}`,
232
+ }),
233
+ )
234
+ .default([]),
228
235
  /** The folders `vulcan init` and `add` put apps in, as the user named them. */
229
236
  layout: z
230
237
  .strictObject({
238
+ /** Folder, or list of folders, for backend apps. */
231
239
  backend: LAYOUT_VALUE.optional(),
240
+ /** Folder, or list of folders, for frontend apps. */
232
241
  frontend: LAYOUT_VALUE.optional(),
242
+ /** Folder, or list of folders, for code shared between apps. */
233
243
  shared: LAYOUT_VALUE.optional(),
234
244
  /** Folders the layout does not manage (docs, third-party code, tests): packages there are allowed, never targeted by `add`, never guarded. */
235
245
  other: LAYOUT_VALUE.optional(),
@@ -244,8 +254,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
244
254
  presets: z
245
255
  .array(
246
256
  z.strictObject({
257
+ /** What was given to `--preset`. */
247
258
  spec: z.string().min(1),
259
+ /** Side of the preset's app kind: `backend` or `frontend`. */
248
260
  side: z.enum(['backend', 'frontend']),
261
+ /** The app kind's one-sentence summary. */
249
262
  summary: z.string(),
250
263
  /** The summary of the preset's lib kind, when it ships one. */
251
264
  lib: z.string().optional(),
@@ -256,34 +269,80 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
256
269
  .optional(),
257
270
  /** The project's packages in release order; okf, atlas, make and release read this one list. */
258
271
  packages: z.array(PROJECT_PACKAGE).superRefine(checkPackagesUnique).default([]),
272
+ /** Where the project keeps its knowledge bundle, wiki, changelogs and sync map; read by okf and doctor. */
259
273
  knowledge: z
260
274
  .strictObject({
275
+ /** Folder of the knowledge bundle (the OKF concepts); default `.agents/knowledge`. */
261
276
  bundle: z.string().default(ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE),
277
+ /** Folder of the wiki content; absent means the project has none. */
262
278
  wiki: z.string().optional(),
279
+ /** Folder of the changelog files; absent means the project has none. */
263
280
  changelogs: z.string().optional(),
264
- /** The knowledge-sync skill's map of code areas to concepts. */
265
- syncAreas: z.string().optional(),
281
+ /**
282
+ * The cutover of the migration gate. `YYYY-MM-DD`: a dated entry on or after it owes a `migration` block when it is a
283
+ * Breaking Change. `X.Y.Z`: version folders from that version on are the changelog and dated files are history.
284
+ */
285
+ migrationFrom: z
286
+ .string()
287
+ .regex(/^(?:\d{4}-\d{2}-\d{2}|\d+\.\d+\.\d+)$/)
288
+ .optional(),
289
+ /**
290
+ * The command that runs the codemods of this project's migrations: a bare binary name found in the app's
291
+ * `node_modules/.bin`, then fixed words (`['tool', 'codemod']`); default `['devz', 'codemod']`. A migration names
292
+ * a codemod, never a command: the runner is the source project's, so a changelog cannot run anything.
293
+ */
294
+ codemodCommand: z
295
+ .array(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i))
296
+ .min(1)
297
+ .optional(),
298
+ /** `YYYY-MM-DD`: the last date a dated changelog file may carry; a later one fails the changelog check. */
299
+ datedUntil: z
300
+ .string()
301
+ .regex(/^\d{4}-\d{2}-\d{2}$/)
302
+ .optional(),
303
+ /**
304
+ * The address of the project's wiki (`https://wiki.example.com`): `vulcan migrate plan` prints a link to the
305
+ * upgrade guide of each step on it, `<siteUrl>/changelogs/<version>/upgrade#<id>`. An https address (http only on
306
+ * localhost) with no credentials, query, fragment or control character, kept without its trailing slash; omit it
307
+ * and the plan prints no link.
308
+ */
309
+ siteUrl: z
310
+ .string()
311
+ .transform((value, context) => {
312
+ const parsed = SiteUrl.parse({ value });
313
+
314
+ if ('problem' in parsed) {
315
+ context.addIssue({ code: 'custom', message: parsed.problem });
316
+
317
+ return z.NEVER;
318
+ }
319
+
320
+ return parsed.href;
321
+ })
322
+ .optional(),
323
+ /** A map of code areas to concepts; no shipped skill reads it. */
266
324
  })
267
325
  .default({ bundle: ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE }),
326
+ /** Settings of okf, the knowledge bundle tool: renderers, regions, coverage axes and the brand. */
268
327
  okf: z
269
328
  .strictObject({
329
+ /** Renderers the project uses, each a built-in id or an object with a module; default `[]`. */
270
330
  renderers: z.array(OKF_RENDERER).default([]),
331
+ /** Generated blocks in markdown files, each binding a region `id` and `file` to a `renderer`; default `[]`. */
271
332
  regions: z
272
333
  .array(z.strictObject({ id: z.string(), file: z.string(), renderer: z.string() }))
273
334
  .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
335
  /** `exclude`: globs from the root dropped from this axis; `denylist`: directory names dropped from this axis only. */
281
336
  coverage: z
282
337
  .array(
283
338
  z.strictObject({
339
+ /** Unique name of the coverage axis. */
284
340
  name: z.string(),
341
+ /** Directory or pattern the axis scans. */
285
342
  path: z.string(),
343
+ /** Globs from the root dropped from this axis; default `[]`. */
286
344
  exclude: z.array(z.string()).default([]),
345
+ /** Directory names dropped from this axis only; default `[]`. */
287
346
  denylist: z.array(z.string()).default([]),
288
347
  }),
289
348
  )
@@ -294,25 +353,26 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
294
353
  contents: z
295
354
  .strictObject({ files: z.array(z.string()).default(['AGENTS.md', '.agents/rules.md']) })
296
355
  .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] }),
356
+ /** 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. */
357
+ brand: z.string().optional(),
358
+ /** Removed with `vulcan x okf viz`: the key is refused with what to do. */
359
+ viz: REMOVED_OKF_KEY({
360
+ 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`',
361
+ }),
362
+ /** Removed with the explorer, the only thing that read it. */
363
+ sections: REMOVED_OKF_KEY({ fix: 'delete this key; only the removed explorer read it' }),
304
364
  })
305
365
  .default({
306
366
  renderers: [],
307
367
  regions: [],
308
- sections: { order: [], labels: {} },
309
368
  coverage: [],
310
369
  denylist: [],
311
370
  contents: { files: ['AGENTS.md', '.agents/rules.md'] },
312
- viz: { outputs: [VIZ_OUTPUT] },
313
371
  }),
372
+ /** Settings of atlas: release tag layout, the sources it indexes, ignored tags, the signing keys of the published index and prebuilt downloads. */
314
373
  atlas: z
315
374
  .strictObject({
375
+ /** Template of a release tag; must hold `<version>`, and `<dir>` for per-package tags. Default `<dir>-v<version>`. */
316
376
  tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
317
377
  /**
318
378
  * Templates of an earlier tag layout that are still releases: atlas and the changelog check read a tag
@@ -320,15 +380,43 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
320
380
  * releases. Unlike `ignoreTags`, a tag matched here counts as a release.
321
381
  */
322
382
  legacyTagPatterns: z.array(RELEASE_TEMPLATE).optional(),
383
+ /** Repositories atlas indexes besides this one, each with a `name`, a `repo` and a `ref`; default `[]`. */
323
384
  sources: z
324
385
  .array(
325
- z.strictObject({
326
- name: z.string(),
327
- repo: z.string(),
328
- ref: z.string().default('develop'),
329
- /** `installed` (default): the docs are read at the tag of the newest installed package; `ref`: at `ref`. */
330
- pin: z.enum(['installed', 'ref']).optional(),
331
- }),
386
+ z
387
+ .strictObject({
388
+ /** Identifier of the source in atlas results: letters, digits, `_`, `.` and `-`, starting with a letter or a digit. */
389
+ name: z
390
+ .string()
391
+ .regex(
392
+ /^[A-Za-z0-9][\w.-]*$/,
393
+ 'a name of letters, digits, _ . and -, starting with a letter or a digit',
394
+ ),
395
+ /** GitHub repository of the source, as `owner/repo`. */
396
+ repo: z.string().refine((value) => !value.trimStart().startsWith('-'), {
397
+ message: "a repository, not an option: it must not start with '-'",
398
+ }),
399
+ /** Branch, tag or commit the source is indexed at; default `develop`. */
400
+ ref: z
401
+ .string()
402
+ .refine((value) => !value.trimStart().startsWith('-'), {
403
+ message: "a ref, not an option: it must not start with '-'",
404
+ })
405
+ .default('develop'),
406
+ /** `installed` (default): the docs are read at the tag of the newest installed package; `ref`: at `ref`. */
407
+ pin: z.enum(['installed', 'ref']).optional(),
408
+ })
409
+ .superRefine((source, context) => {
410
+ const refused = SOURCE_TRANSPORT.exec(source.repo.trim());
411
+
412
+ if (refused !== null) {
413
+ context.addIssue({
414
+ code: 'custom',
415
+ path: ['repo'],
416
+ message: `source '${source.name}': the repository uses ${refused[1] === undefined ? 'a remote-helper URL, which runs a command' : `${refused[1].toLowerCase()}://, which is clear text`} - use https or ssh`,
417
+ });
418
+ }
419
+ }),
332
420
  )
333
421
  .default([]),
334
422
  /** Tags neither read nor checked (globs) - an old layout's tags. */
@@ -341,25 +429,22 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
341
429
  index: z.strictObject({ keys: z.array(INDEX_PUBLIC_KEY).default([]) }).optional(),
342
430
  /** `false`: atlas never downloads a prebuilt index for a source this project reads; the default is to. */
343
431
  prebuilt: z.boolean().optional(),
432
+ /** The sizes atlas holds to when it fetches. */
433
+ limits: z
434
+ .strictObject({
435
+ /**
436
+ * The most bytes atlas reads of one tarball it downloads (a source's commit from GitHub, an npm package
437
+ * for its declarations); a larger one is refused and nothing is kept. An integer from 1 MiB to 1 GiB;
438
+ * default 128 MiB.
439
+ */
440
+ download: z.number().int().min(MIN_DOWNLOAD_BYTES).max(MAX_DOWNLOAD_BYTES).optional(),
441
+ })
442
+ .optional(),
344
443
  })
345
444
  .default({
346
445
  tagPattern: '<dir>-v<version>',
347
446
  sources: [],
348
447
  }),
349
- /**
350
- * The remote-host guard (W-04 in a project's own words): with this key set, sync registers a hook that
351
- * asks before a Bash command reaches a host not listed here. `trusted` hosts are free; `readOnly`
352
- * hosts pass only the strict read-only forms. Matching is by whole name or `*` pattern, never by substring.
353
- * `localFile` is a gitignored list of personal hosts, one per line: a host is trusted, `readonly: <host>` is a
354
- * read-only host. Each entry follows the same rule as the lists above; one that does not is skipped.
355
- */
356
- remoteHosts: z
357
- .strictObject({
358
- trusted: z.array(REMOTE_HOST).default([]),
359
- readOnly: z.array(REMOTE_HOST).default([]),
360
- localFile: z.string().default(ProjectLayout.TRUSTED_HOSTS_FILE),
361
- })
362
- .optional(),
363
448
  /**
364
449
  * The colour the project is known by: `vulcan visualize` takes the accent of its pages from here (the spec's own
365
450
  * `accent` wins). `accent` is the colour for marks and fills; `accentDark` is the same on dark grounds (derived
@@ -368,15 +453,50 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
368
453
  */
369
454
  theme: z
370
455
  .strictObject({
371
- accent: z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #8a5a20'),
456
+ /** The preset the tokens start from: `venizia` (default) or `slate`; a preset fixes every token and the project changes only what it names. */
457
+ preset: z
458
+ .string()
459
+ .refine((name) => Object.hasOwn(ThemeTokens.PRESETS, name), {
460
+ message: `one of ${Object.keys(ThemeTokens.PRESETS).join(', ')}`,
461
+ })
462
+ .optional(),
463
+ /** Colour for marks and fills, as a six-digit hex such as `#8a5a20`; absent means the preset's accent. */
464
+ accent: z.string().regex(ProjectTheme.HEX, 'a six-digit hex colour like #8a5a20').optional(),
465
+ /** Accent for dark grounds, a six-digit hex such as `#dead6a`; derived from `accent` when absent. */
372
466
  accentDark: z
373
467
  .string()
374
- .regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #dead6a')
468
+ .regex(ProjectTheme.HEX, 'a six-digit hex colour like #dead6a')
375
469
  .optional(),
470
+ /** Darker accent for text, a six-digit hex such as `#01579b`; absent means `accent` is used for text too. */
376
471
  accentText: z
377
472
  .string()
378
- .regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #01579b')
473
+ .regex(ProjectTheme.HEX, 'a six-digit hex colour like #01579b')
474
+ .optional(),
475
+ /** 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. */
476
+ tokens: z
477
+ .record(
478
+ z.string(),
479
+ z.union([
480
+ TOKEN_COLOUR,
481
+ z.strictObject({ light: TOKEN_COLOUR.optional(), dark: TOKEN_COLOUR.optional() }),
482
+ ]),
483
+ )
379
484
  .optional(),
485
+ /** The sans font stack for the board, the wiki and the pages; default the preset's. */
486
+ font: z.string().min(1).optional(),
487
+ /** The monospace font stack; default the preset's. */
488
+ mono: z.string().min(1).optional(),
489
+ /** The corner radius: `0`, or a number with `px`, `rem` or `em` such as `4px`; anything else is refused. Default the preset's. */
490
+ radius: z.string().min(1).optional(),
491
+ })
492
+ .superRefine((theme, context) => {
493
+ const resolved = ThemeTokens.resolve({ theme });
494
+
495
+ if (!resolved.ok) {
496
+ for (const message of resolved.problems) {
497
+ context.addIssue({ code: 'custom', message, path: [] });
498
+ }
499
+ }
380
500
  })
381
501
  .optional(),
382
502
  /**
@@ -387,8 +507,11 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
387
507
  */
388
508
  board: z
389
509
  .strictObject({
510
+ /** Who an ask waits on; default: `git config user.name`, else `Owner`. */
390
511
  owner: z.string().min(1).optional(),
512
+ /** Name on the board page and tab; default: the project name and `Board`. */
391
513
  title: z.string().min(1).optional(),
514
+ /** Name in the address of `vulcan board serve`: lowercase, ending in `.localhost`; default `vulz-board.venizia.ai.localhost`. */
392
515
  hostname: z
393
516
  .string()
394
517
  .regex(
@@ -396,37 +519,70 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
396
519
  'a lowercase name that ends in .localhost, such as board.localhost',
397
520
  )
398
521
  .optional(),
522
+ /** Path inside the project to an `.svg` file shown on the board page, with no leading `/` and no `..` segment; default none. */
399
523
  logo: z
400
524
  .string()
401
525
  .min(1)
402
- .refine(
403
- (value) =>
404
- value.toLowerCase().endsWith('.svg') &&
405
- !value.startsWith('/') &&
406
- !value.split('/').includes('..'),
407
- {
408
- message:
409
- 'a path inside the project to an .svg file, with no leading / and no .. segment',
410
- },
411
- )
526
+ .refine((value) => BoardLogo.isPath({ path: value }), {
527
+ message: 'a path inside the project to an .svg file, with no leading / and no .. segment',
528
+ })
412
529
  .optional(),
530
+ /** Faces and roles of the board's agents, keyed by agent name; default `{}`. */
413
531
  agents: BOARD_AGENTS.default({}),
414
532
  })
415
533
  .default({ agents: {} }),
534
+ /**
535
+ * The code host `vulcan board` reads pull requests, checks and commits from: `github` through `gh` (the default),
536
+ * or `gitlab` through `glab`. `host` names the GitLab server (default `gitlab.com`): a bare host name with an
537
+ * optional port, never a URL. Written to the manifest only when it is not `github`.
538
+ */
539
+ provider: z
540
+ .strictObject({
541
+ /** `github` or `gitlab`; default `github`. */
542
+ type: z.enum([ProviderTypes.GITHUB, ProviderTypes.GITLAB]).default(ProviderTypes.GITHUB),
543
+ /** The GitLab host name, such as `gitlab.example.com` or `gitlab.example.com:8443`; only with `gitlab`; default `gitlab.com`. */
544
+ host: z
545
+ .string()
546
+ .regex(
547
+ BoardConstants.GITLAB_HOST,
548
+ 'a bare host name such as gitlab.example.com, with an optional :port, no scheme, path or credentials',
549
+ )
550
+ .optional(),
551
+ })
552
+ .refine((provider) => provider.host === undefined || provider.type === ProviderTypes.GITLAB, {
553
+ message: 'host is only for type "gitlab"',
554
+ path: ['host'],
555
+ })
556
+ .default({ type: ProviderTypes.GITHUB }),
416
557
  /** What `vulcan doctor` is told: `privateValues.acknowledged` lists the files that may keep private values, each with a `reason`. */
417
558
  doctor: DOCTOR_SCHEMA.default({ privateValues: { acknowledged: [] } }),
418
559
  /** Team-shared Claude settings (permissions, env, enabledPlugins...), merged by sync over personal keys. */
419
560
  claude: z
420
- .strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
561
+ .strictObject({
562
+ /** The Claude settings merged into `.claude/settings.json`; an `env` that sets a `VULCAN_GUARD*` variable is refused. */
563
+ settings: z
564
+ .record(z.string(), z.unknown())
565
+ .superRefine((settings, context) => {
566
+ const env = settings['env'];
567
+
568
+ if (typeof env !== 'object' || env === null || Array.isArray(env)) {
569
+ return;
570
+ }
571
+
572
+ for (const name of Object.keys(env).filter((key) => /^VULCAN_GUARD/.test(key))) {
573
+ context.addIssue({
574
+ code: 'custom',
575
+ message: `${name} is the owner's choice and belongs in the environment that launches the agent, not in the project's Claude settings, which an agent can edit`,
576
+ });
577
+ }
578
+ })
579
+ .default({}),
580
+ })
421
581
  .default({ settings: {} }),
422
- hooks: z
423
- .array(
424
- z.strictObject({ event: HOOK_EVENT, matcher: z.string().optional(), command: z.string() }),
425
- )
426
- .default([]),
427
582
  /** The session-start digest: the rule IDs it repeats as "the rules sessions drop most" - base or the project's own. */
428
583
  digest: z
429
584
  .strictObject({
585
+ /** Rule IDs the digest repeats as dropped most, each matching the rule ID pattern; default the shipped list of base rules. */
430
586
  oftenDropped: z
431
587
  .array(z.string().regex(ConfigConstants.RULE_ID_PATTERN))
432
588
  .default(ConfigConstants.DEFAULT_OFTEN_DROPPED),
@@ -437,34 +593,64 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
437
593
  /**
438
594
  * The hooks that guard writes. `toolOwnedPaths` extends the defaults (package manager caches, the
439
595
  * runtime dir for locks, git config, the agent tool's memory) with stores a tool in this project
440
- * manages itself: absolute globs, `~` and `$NAME` allowed. `writes.trustedScripts` lists the project's own
441
- * CLIs (repo-relative `.ts` paths, no globs) whose body guard-writes does not read for mutating calls
442
- * while git tracks them and they equal HEAD; the command line is still checked. An entry may instead be
443
- * `{ script, readOnly: ['plan'] }`: only a call whose first argument after the script is listed skips the
444
- * read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
596
+ * manages itself: absolute globs, `~` and `$NAME` allowed. `writes.commands` adds the
445
597
  * project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
446
598
  * 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
448
- * write outside the project: `ask` (the default) or `deny`. Where the agent runs in an auto mode an ask can be
449
- * approved without the owner seeing it, so a project that wants the line held sets `deny`.
599
+ * writes both to the manifest, where the hooks read them, and writes `outside` (when it is `deny`) and
600
+ * `toolOwnedPaths` there too, so a config this VULCAN cannot parse changes no guard. `outside` is what
601
+ * `guard-outside` does with a write outside the project: `ask` (the default) or `deny`. `asks` is the same choice for every guard:
602
+ * `deny` makes each answer that would ask a human (a command of guard-writes, a push target of `git.askPush`, `git push --mirror`,
603
+ * `git reset --hard`, a force-push to a branch that is not protected, a force-delete of an unmerged branch, a write outside the
604
+ * project, a part of a call a guard cannot read, a guard that crashed or timed out) a refusal with the same hint. Where the agent
605
+ * runs in an auto mode an ask can be approved without the owner seeing it, so a project that runs agents there sets `asks: 'deny'`.
606
+ * Both are a drift guard, not a boundary: the owner's choice belongs in the launch environment (`VULCAN_GUARD_ASKS=deny`,
607
+ * `VULCAN_GUARD_OUTSIDE=deny`), where the strictest of the environment and the manifest holds and nothing in the project can
608
+ * loosen it (it also ignores `toolOwnedPaths` and `runners.allow` of the manifest, and every hook runs with `bun --no-env-file
609
+ * --config=/dev/null`). `guard-outside` denies an agent's write to the manifest, `.configs/vulcan.config.*`, `.claude/settings*.json` and
610
+ * `node_modules/@venizia/vulcan`.
450
611
  */
451
612
  guard: z
452
613
  .strictObject({
614
+ /** Absolute globs (`~` and `$NAME` allowed) of tool-managed stores, added to the built-in list; default `[]`. */
453
615
  toolOwnedPaths: z.array(z.string().min(1)).default([]),
616
+ /** What guard-outside does with a write outside the project: `ask` or `deny`; default `ask`. */
454
617
  outside: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
618
+ /** What every guard does with a call that needs a human to confirm it: `ask` or `deny`; default `ask`. Set `deny` where the agent runs in an auto mode; `VULCAN_GUARD_ASKS=deny` in the launch environment holds it where the project cannot. */
619
+ asks: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
620
+ /** Write guard list: the project's own deploy and migrate commands; default `[]`. */
455
621
  writes: z
456
622
  .strictObject({
457
- trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
623
+ /** Removed with the script reading of guard-writes: the key is refused with what to do. */
624
+ trustedScripts: REMOVED_OKF_KEY({
625
+ fix: 'delete this key; guard-writes no longer reads scripts, it asks only for the commands of its table and of guard.writes.commands',
626
+ }),
627
+ /** The project's own deploy and migrate commands guard-writes asks about; default `[]`. */
458
628
  commands: z.array(GUARD_COMMAND).default([]),
459
629
  })
460
- .default({ trustedScripts: [], commands: [] }),
630
+ .default({ commands: [] }),
631
+ /** Git guard settings; `askPush` lists the branches a plain `git push` asks about, `*` for any run of characters. Default `[]`. */
461
632
  git: z.strictObject({ askPush: z.array(PUSH_TARGET).default([]) }).default({ askPush: [] }),
633
+ /**
634
+ * The package names `vulcan runners check` and the runner guard accept besides the scoped packages (`@scope/name`,
635
+ * which always pass), such as `shadcn`: lower-case words, dots and dashes, or a scoped name. Anything else that
636
+ * `bunx`, `bun x`, `npx`, `pnpx` or `pnpm dlx` would fetch by name is refused. Default `[]`.
637
+ */
638
+ runners: z
639
+ .strictObject({
640
+ /** The unscoped names a project may run by name, with a version or a tag after them. */
641
+ allow: z
642
+ .array(z.string().regex(/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/))
643
+ .default([]),
644
+ })
645
+ .default({ allow: [] }),
462
646
  })
463
647
  .default({
464
648
  toolOwnedPaths: [],
465
649
  outside: GuardDecisions.ASK,
466
- writes: { trustedScripts: [], commands: [] },
650
+ asks: GuardDecisions.ASK,
651
+ writes: { commands: [] },
467
652
  git: { askPush: [] },
653
+ runners: { allow: [] },
468
654
  }),
469
655
  /**
470
656
  * What `vulcan commit-check` looks for in a commit message, and what `vulcan sync` installs the
@@ -476,22 +662,29 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
476
662
  */
477
663
  commit: z
478
664
  .strictObject({
665
+ /** Checks on the text of a commit message: the agent signature policy and the subject shape. */
479
666
  message: z
480
667
  .strictObject({
668
+ /** Rules about agent names in a commit message: signature policy, extra names and allowed names. */
481
669
  agent: z
482
670
  .strictObject({
671
+ /** Policy for an agent trailer or "generated with" line in a commit message: `allow` or `deny`; default `allow`. */
483
672
  signature: z
484
673
  .custom<TAgentSignaturePolicy>(
485
674
  (value) => typeof value === 'string' && AgentSignaturePolicies.isValid(value),
486
675
  { message: `one of ${[...AgentSignaturePolicies.SCHEME_SET].join(', ')}` },
487
676
  )
488
677
  .default(AgentSignaturePolicies.ALLOW),
678
+ /** Agent names added to the shipped list; a co-author or `Generated with` line naming one is flagged under `deny`. Default `[]`. */
489
679
  names: z.array(AGENT_NAME).default([]),
680
+ /** Whole co-author names never flagged, for a person who shares a name with an agent; default `[]`. */
490
681
  allow: z.array(AGENT_NAME).default([]),
491
682
  })
492
683
  .default({ signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] }),
684
+ /** The project's own shape for the commit subject line; absent means no subject check. */
493
685
  subject: z
494
686
  .strictObject({
687
+ /** Regular expression the commit subject must match, 1 or more characters; an invalid expression is rejected. */
495
688
  pattern: z
496
689
  .string()
497
690
  .min(1)
@@ -502,6 +695,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
502
695
  context.addIssue({ code: 'custom', message: error });
503
696
  }
504
697
  }),
698
+ /** Text shown with the error when a subject does not match `pattern`; absent means none. */
505
699
  hint: z.string().min(1).optional(),
506
700
  })
507
701
  .optional(),
@@ -511,30 +705,6 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
511
705
  .default({
512
706
  message: { agent: { signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] } },
513
707
  }),
514
- /**
515
- * What `vulcan ci affected` treats as touching every package. `affected.global` adds root-relative globs
516
- * to the shipped list (lockfiles, `bunfig.toml`, root `tsconfig*.json`, `.configs/`, the workflow files);
517
- * a project cannot remove a shipped one. Written to the manifest only when it is not empty.
518
- */
519
- ci: z
520
- .strictObject({
521
- affected: z
522
- .strictObject({
523
- global: z
524
- .array(
525
- z
526
- .string()
527
- .min(1)
528
- .refine((glob) => !glob.startsWith('/') && !glob.split('/').includes('..'), {
529
- message:
530
- 'a glob relative to the project root, with no leading / and no .. segment',
531
- }),
532
- )
533
- .default([]),
534
- })
535
- .default({ global: [] }),
536
- })
537
- .default({ affected: { global: [] } }),
538
708
  /**
539
709
  * The agent event log: one JSON line per thing an agent did (a session started, a message sent, an
540
710
  * owner is needed), summaries only, in `.agents/local/events/<day>.jsonl`. `log: true` makes
@@ -545,7 +715,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
545
715
  */
546
716
  events: z
547
717
  .strictObject({
718
+ /** `true` makes `vulcan sync` install the hooks that write the event log; default `false`. */
548
719
  log: z.boolean().default(false),
720
+ /** Absolute folder that takes the event log instead of the project's own; absent means the project's `.agents/local/events`. */
549
721
  dir: z
550
722
  .string()
551
723
  .min(1)
@@ -568,7 +740,9 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
568
740
  message: 'a size such as 50MB, 200MB or 1GB',
569
741
  })
570
742
  .optional(),
743
+ /** Most day files kept in the log; at least 1, default 30 when `log` is on. */
571
744
  maxFiles: z.number().int().min(1).optional(),
745
+ /** Oldest age, in days, a day file may reach; at least 1, default 30 when `log` is on. */
572
746
  maxAgeDays: z.number().int().min(1).optional(),
573
747
  })
574
748
  .default({ log: false }),
@@ -579,12 +753,22 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
579
753
  */
580
754
  local: z
581
755
  .strictObject({
756
+ /** `true` lets the session-start hook clean the safe part of `.agents/local/` at most once a day; default `true`. */
582
757
  autoClean: z.boolean().default(true),
758
+ /**
759
+ * A folder of the project, from its root, for the temporary files of a session (default `.agents/local/tmp`). A
760
+ * browser puts a socket below it and fails past 107 characters of path, so a deep checkout can name a short one (`t`).
761
+ * Written like a layout folder: 1 to 4 plain lower-case segments, never absolute, never climbing. `vulcan sync`
762
+ * creates it, gitignores it and points the launch file at it.
763
+ */
764
+ tmp: LAYOUT_FOLDER.optional(),
583
765
  })
584
766
  .default({ autoClean: true }),
585
767
  });
586
768
 
769
+ /** What a project writes in `.configs/vulcan.config.mts`: every key optional or defaulted, unknown keys refused. */
587
770
  export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
771
+ /** The config as the CLI reads it: every default filled in. */
588
772
  export type TResolvedConfig = z.output<typeof VULCAN_CONFIG_SCHEMA>;
589
773
 
590
774
  /** Identity at run time; gives TS and JS configs their types. The parameter is the options object (V-C-02). */