@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -0,0 +1,474 @@
1
+ import { lstatSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+
4
+ /** What a project (or one spec) says about its colour: the colour it is known by, and two optional helpers. */
5
+ export interface IThemeInput {
6
+ /** The colour the project is known by: marks, rules and fills. */
7
+ accent: string;
8
+ /** The accent on dark grounds; derived by mixing toward white when absent. */
9
+ accentDark?: string;
10
+ /** The accent as text on light grounds, when `accent` is too light for text. */
11
+ accentText?: string;
12
+ }
13
+
14
+ export type TThemeSource = 'spec' | 'project' | 'default';
15
+
16
+ /** The colours of one theme, each already checked against the grounds it sits on. */
17
+ export interface IThemePalette {
18
+ bg: string;
19
+ bgSoft: string;
20
+ ink: string;
21
+ body: string;
22
+ muted: string;
23
+ /** The accent as text and as a mark on `bg` and `bgSoft`. */
24
+ accent: string;
25
+ /** The text on an accent fill. */
26
+ accentInk: string;
27
+ /** The tint behind an accent. */
28
+ accentSoft: string;
29
+ /** The accent as a mark on the slab. */
30
+ hot: string;
31
+ hotInk: string;
32
+ hotGlow: string;
33
+ slab: string;
34
+ slab2: string;
35
+ slab3: string;
36
+ slabInk: string;
37
+ slabBody: string;
38
+ slabMuted: string;
39
+ slabDot: string;
40
+ }
41
+
42
+ export interface IResolvedTheme {
43
+ source: TThemeSource;
44
+ light: IThemePalette;
45
+ dark: IThemePalette;
46
+ /** What the generator worked out, for the report: nothing is silent. */
47
+ notes: string[];
48
+ warnings: string[];
49
+ }
50
+
51
+ export type TThemeResult = { ok: true; theme: IResolvedTheme } | { ok: false; problems: string[] };
52
+
53
+ const HEX = /^#[0-9a-fA-F]{6}$/;
54
+ /** WCAG: text 4.5 to 1, a mark 3 to 1. */
55
+ const TEXT_RATIO = 4.5;
56
+ const MARK_RATIO = 3;
57
+ const MAX_MIX = 0.6;
58
+ const MIX_STEP = 0.05;
59
+ /** A state hue the accent must keep away from: the blocked red and the done green of the page. */
60
+ const STATE_HUES: { name: string; hue: number }[] = [
61
+ { name: 'blocked', hue: 3 },
62
+ { name: 'done', hue: 141 },
63
+ ];
64
+ const HUE_NEAR = 20;
65
+
66
+ interface IRgb {
67
+ r: number;
68
+ g: number;
69
+ b: number;
70
+ }
71
+
72
+ const parse = (hex: string): IRgb => ({
73
+ r: parseInt(hex.slice(1, 3), 16),
74
+ g: parseInt(hex.slice(3, 5), 16),
75
+ b: parseInt(hex.slice(5, 7), 16),
76
+ });
77
+
78
+ const toHex = (rgb: IRgb): string =>
79
+ `#${[rgb.r, rgb.g, rgb.b]
80
+ .map((value) =>
81
+ Math.round(Math.max(0, Math.min(255, value)))
82
+ .toString(16)
83
+ .padStart(2, '0'),
84
+ )
85
+ .join('')}`;
86
+
87
+ /** `amount` of `toward` mixed into `base`. */
88
+ const mix = (opts: { base: string; toward: string; amount: number }): string => {
89
+ const a = parse(opts.base);
90
+ const b = parse(opts.toward);
91
+
92
+ return toHex({
93
+ r: a.r + (b.r - a.r) * opts.amount,
94
+ g: a.g + (b.g - a.g) * opts.amount,
95
+ b: a.b + (b.b - a.b) * opts.amount,
96
+ });
97
+ };
98
+
99
+ const luminance = (hex: string): number => {
100
+ const { r, g, b } = parse(hex);
101
+ const channel = (value: number): number => {
102
+ const scaled = value / 255;
103
+
104
+ return scaled <= 0.03928 ? scaled / 12.92 : ((scaled + 0.055) / 1.055) ** 2.4;
105
+ };
106
+
107
+ return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
108
+ };
109
+
110
+ export class Theme {
111
+ static contrastOf(opts: { foreground: string; background: string }): number {
112
+ const a = luminance(opts.foreground);
113
+ const b = luminance(opts.background);
114
+
115
+ return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
116
+ }
117
+ }
118
+
119
+ const hueOf = (hex: string): number => {
120
+ const { r, g, b } = parse(hex);
121
+ const max = Math.max(r, g, b);
122
+ const min = Math.min(r, g, b);
123
+
124
+ if (max === min) {
125
+ return 0;
126
+ }
127
+
128
+ const delta = max - min;
129
+ const hue =
130
+ max === r ? ((g - b) / delta) % 6 : max === g ? (b - r) / delta + 2 : (r - g) / delta + 4;
131
+
132
+ return (hue * 60 + 360) % 360;
133
+ };
134
+
135
+ const hueGap = (a: number, b: number): number => {
136
+ const gap = Math.abs(a - b) % 360;
137
+
138
+ return gap > 180 ? 360 - gap : gap;
139
+ };
140
+
141
+ const ratioText = (value: number): string => `${value.toFixed(2)}:1`;
142
+
143
+ /** The fixed grounds: tinted a little toward the accent, so a page reads as the project's own. */
144
+ const GROUNDS = {
145
+ light: { bg: '#ffffff', bgSoft: '#f6f6f5', ink: '#0e0e0f', body: '#3a3a3d', muted: '#66666b' },
146
+ dark: { bg: '#121214', bgSoft: '#1b1b1e', ink: '#f6f6f7', body: '#d0d0d4', muted: '#a2a2a8' },
147
+ slab: {
148
+ slab: '#151517',
149
+ slab2: '#202023',
150
+ slab3: '#2b2b2f',
151
+ ink: '#f5f5f6',
152
+ body: '#d0d0d4',
153
+ muted: '#a2a2a8',
154
+ },
155
+ slabDark: { slab: '#0b0b0c', slab2: '#19191b', slab3: '#252528' },
156
+ accentLightSoft: 0.12,
157
+ accentDarkSoft: 0.14,
158
+ tint: 0.035,
159
+ };
160
+
161
+ export class ProjectTheme {
162
+ /** The colour of a page whose project says nothing: a slate ink. */
163
+ static readonly DEFAULT: IThemeInput = { accent: '#3f5266', accentDark: '#9fb4cc' };
164
+
165
+ /** The manifest is read only up to this size: a real one is a few KB. */
166
+ static readonly MAX_MANIFEST_BYTES = 1024 * 1024;
167
+
168
+ /** Whether `value` is a six-digit hex colour. */
169
+ static isHex(value: unknown): value is string {
170
+ return typeof value === 'string' && HEX.test(value);
171
+ }
172
+
173
+ /**
174
+ * The theme of a page: the spec's own accent, else the project's `theme` from the manifest, else the neutral
175
+ * default. Every text, mark and fill pair is checked; a failure writes nothing and says the colour, the ground
176
+ * and the ratio. A colour is never swapped for another.
177
+ */
178
+ static resolve(opts: { spec?: IThemeInput; project?: IThemeInput }): TThemeResult {
179
+ const source: TThemeSource =
180
+ opts.spec !== undefined ? 'spec' : opts.project !== undefined ? 'project' : 'default';
181
+ const given = opts.spec ?? opts.project ?? ProjectTheme.DEFAULT;
182
+ const problems: string[] = [];
183
+ const notes: string[] = [];
184
+ const warnings: string[] = [];
185
+
186
+ for (const [key, value] of Object.entries(given)) {
187
+ if (value !== undefined && !HEX.test(value)) {
188
+ problems.push(`theme ${key} '${value}' is not a six-digit hex colour like #3f5266`);
189
+ }
190
+ }
191
+
192
+ if (problems.length > 0) {
193
+ return { ok: false, problems };
194
+ }
195
+
196
+ const tint = (base: string, accent: string): string =>
197
+ mix({ base, toward: accent, amount: GROUNDS.tint });
198
+ const lightGrounds = {
199
+ bg: GROUNDS.light.bg,
200
+ bgSoft: tint(GROUNDS.light.bgSoft, given.accent),
201
+ };
202
+ const accentText = given.accentText ?? given.accent;
203
+ const accentSoft = mix({
204
+ base: GROUNDS.light.bg,
205
+ toward: given.accent,
206
+ amount: GROUNDS.accentLightSoft,
207
+ });
208
+
209
+ // Light theme: the accent as a mark, then as text on every ground text sits on.
210
+ for (const [name, ground] of [
211
+ ['the page', lightGrounds.bg],
212
+ ['a soft panel', lightGrounds.bgSoft],
213
+ ] as const) {
214
+ const mark = Theme.contrastOf({ foreground: given.accent, background: ground });
215
+
216
+ if (mark < MARK_RATIO) {
217
+ problems.push(
218
+ `accent ${given.accent} as a mark on ${name} (${ground}) is ${ratioText(mark)}; a mark needs ${MARK_RATIO}:1`,
219
+ );
220
+ }
221
+ }
222
+
223
+ for (const [name, ground] of [
224
+ ['the page', lightGrounds.bg],
225
+ ['a soft panel', lightGrounds.bgSoft],
226
+ ['an accent tint', accentSoft],
227
+ ] as const) {
228
+ const text = Theme.contrastOf({ foreground: accentText, background: ground });
229
+
230
+ if (text < TEXT_RATIO) {
231
+ const which = given.accentText === undefined ? 'accent' : 'accentText';
232
+
233
+ problems.push(
234
+ `${which} ${accentText} as text on ${name} (${ground}) is ${ratioText(text)}; text needs ${TEXT_RATIO}:1${
235
+ given.accentText === undefined ? ' - give a darker accentText' : ''
236
+ }`,
237
+ );
238
+ }
239
+ }
240
+
241
+ // Dark theme and the slab: the dark accent is given, or the accent mixed toward white until it passes.
242
+ const darkGrounds = {
243
+ bg: GROUNDS.dark.bg,
244
+ bgSoft: tint(GROUNDS.dark.bgSoft, given.accent),
245
+ };
246
+ const slabs = [
247
+ GROUNDS.slab.slab,
248
+ GROUNDS.slab.slab2,
249
+ GROUNDS.slab.slab3,
250
+ GROUNDS.slabDark.slab,
251
+ ];
252
+ const darkNeeds = [darkGrounds.bg, darkGrounds.bgSoft, ...slabs];
253
+ const darkPasses = (color: string): boolean =>
254
+ darkNeeds.every(
255
+ (ground) => Theme.contrastOf({ foreground: color, background: ground }) >= TEXT_RATIO,
256
+ );
257
+ let dark = given.accentDark;
258
+
259
+ if (dark === undefined) {
260
+ for (let amount = 0; amount <= MAX_MIX + 1e-9; amount += MIX_STEP) {
261
+ const candidate = mix({ base: given.accent, toward: '#ffffff', amount });
262
+
263
+ if (darkPasses(candidate)) {
264
+ dark = candidate;
265
+ break;
266
+ }
267
+ }
268
+
269
+ if (dark === undefined) {
270
+ problems.push(
271
+ `accent ${given.accent} cannot be made readable on the dark grounds by mixing up to ${Math.round(MAX_MIX * 100)}% white - give an accentDark`,
272
+ );
273
+ } else if (dark !== given.accent) {
274
+ notes.push(
275
+ `accentDark ${dark} derived from ${given.accent} (mixed toward white until it passes ${TEXT_RATIO}:1)`,
276
+ );
277
+ }
278
+ } else {
279
+ for (const ground of darkNeeds) {
280
+ const value = Theme.contrastOf({ foreground: dark, background: ground });
281
+
282
+ if (value < TEXT_RATIO) {
283
+ problems.push(
284
+ `accentDark ${dark} on ${ground} is ${ratioText(value)}; text needs ${TEXT_RATIO}:1`,
285
+ );
286
+ }
287
+ }
288
+ }
289
+
290
+ if (problems.length > 0 || dark === undefined) {
291
+ return { ok: false, problems };
292
+ }
293
+
294
+ const accentInk = ProjectTheme.inkOn({ fill: given.accent });
295
+ const hotInk = ProjectTheme.inkOn({ fill: dark });
296
+
297
+ if (accentInk === undefined) {
298
+ problems.push(
299
+ `no black or white text reads at ${TEXT_RATIO}:1 on an accent fill ${given.accent}`,
300
+ );
301
+ }
302
+
303
+ if (hotInk === undefined) {
304
+ problems.push(`no black or white text reads at ${TEXT_RATIO}:1 on an accent fill ${dark}`);
305
+ }
306
+
307
+ if (problems.length > 0 || accentInk === undefined || hotInk === undefined) {
308
+ return { ok: false, problems };
309
+ }
310
+
311
+ const hue = hueOf(given.accent);
312
+
313
+ for (const state of STATE_HUES) {
314
+ if (hueGap(hue, state.hue) <= HUE_NEAR) {
315
+ warnings.push(
316
+ `accent ${given.accent} is close in hue to the '${state.name}' colour of the page: state is carried by an icon and a word, but check the page reads clearly`,
317
+ );
318
+ }
319
+ }
320
+
321
+ const darkSoft = mix({ base: GROUNDS.dark.bg, toward: dark, amount: GROUNDS.accentDarkSoft });
322
+ const light: IThemePalette = {
323
+ ...GROUNDS.light,
324
+ bgSoft: lightGrounds.bgSoft,
325
+ accent: accentText,
326
+ accentInk,
327
+ accentSoft,
328
+ hot: dark,
329
+ hotInk,
330
+ hotGlow: `${dark}40`,
331
+ slab: tint(GROUNDS.slab.slab, dark),
332
+ slab2: tint(GROUNDS.slab.slab2, dark),
333
+ slab3: tint(GROUNDS.slab.slab3, dark),
334
+ slabInk: GROUNDS.slab.ink,
335
+ slabBody: GROUNDS.slab.body,
336
+ slabMuted: GROUNDS.slab.muted,
337
+ slabDot: '#ffffff14',
338
+ };
339
+ const darkPalette: IThemePalette = {
340
+ ...GROUNDS.dark,
341
+ bgSoft: darkGrounds.bgSoft,
342
+ accent: dark,
343
+ accentInk: hotInk,
344
+ accentSoft: darkSoft,
345
+ hot: dark,
346
+ hotInk,
347
+ hotGlow: `${dark}40`,
348
+ slab: tint(GROUNDS.slabDark.slab, dark),
349
+ slab2: tint(GROUNDS.slabDark.slab2, dark),
350
+ slab3: tint(GROUNDS.slabDark.slab3, dark),
351
+ slabInk: GROUNDS.slab.ink,
352
+ slabBody: GROUNDS.slab.body,
353
+ slabMuted: GROUNDS.slab.muted,
354
+ slabDot: '#ffffff14',
355
+ };
356
+
357
+ return { ok: true, theme: { source, light, dark: darkPalette, notes, warnings } };
358
+ }
359
+
360
+ /** Black or white, whichever reads at 4.5:1 on a fill; white when both do. */
361
+ static inkOn(opts: { fill: string }): string | undefined {
362
+ const candidates = ['#ffffff', '#0e0e0f'];
363
+
364
+ return candidates.find(
365
+ (ink) => Theme.contrastOf({ foreground: ink, background: opts.fill }) >= TEXT_RATIO,
366
+ );
367
+ }
368
+
369
+ /** The custom properties of one palette. */
370
+ private static declarations(opts: { palette: IThemePalette }): string {
371
+ const p = opts.palette;
372
+
373
+ return [
374
+ `--bg:${p.bg}`,
375
+ `--bg-soft:${p.bgSoft}`,
376
+ `--ink:${p.ink}`,
377
+ `--body:${p.body}`,
378
+ `--muted:${p.muted}`,
379
+ `--accent:${p.accent}`,
380
+ `--accent-ink:${p.accentInk}`,
381
+ `--accent-soft:${p.accentSoft}`,
382
+ `--hot:${p.hot}`,
383
+ `--hot-ink:${p.hotInk}`,
384
+ `--hot-glow:${p.hotGlow}`,
385
+ `--slab:${p.slab}`,
386
+ `--slab-2:${p.slab2}`,
387
+ `--slab-3:${p.slab3}`,
388
+ `--slab-ink:${p.slabInk}`,
389
+ `--slab-body:${p.slabBody}`,
390
+ `--slab-muted:${p.slabMuted}`,
391
+ `--slab-dot:${p.slabDot}`,
392
+ ].join(';');
393
+ }
394
+
395
+ /**
396
+ * The theme blocks: light on `:root`, then the system dark setting unless the page was set to light, then an
397
+ * explicit dark. The same tokens in each.
398
+ */
399
+ static tokensCss(opts: { theme: IResolvedTheme }): string {
400
+ const light = ProjectTheme.declarations({ palette: opts.theme.light });
401
+ const dark = ProjectTheme.declarations({ palette: opts.theme.dark });
402
+
403
+ return `:root{${light};color-scheme:light}\n@media (prefers-color-scheme:dark){:root:not([data-theme=light]){${dark};color-scheme:dark}}\n:root[data-theme=dark]{${dark};color-scheme:dark}`;
404
+ }
405
+
406
+ /**
407
+ * The project's `theme` from the manifest of the folder the command runs in. No config file is loaded and nothing
408
+ * is requested: a missing file, or a manifest with no `theme`, is the neutral default.
409
+ */
410
+ static readManifestTheme(opts: { root: string }): { theme?: IThemeInput; warning?: string } {
411
+ let text: string;
412
+
413
+ try {
414
+ const directory = join(opts.root, '.agents');
415
+ const file = join(directory, 'vulcan.manifest.json');
416
+ const folder = lstatSync(directory);
417
+ const entry = lstatSync(file);
418
+
419
+ // A symlink (the folder or the file), a device or a huge file is not read: the manifest is a small file inside the project.
420
+ if (
421
+ !folder.isDirectory() ||
422
+ !entry.isFile() ||
423
+ entry.size > ProjectTheme.MAX_MANIFEST_BYTES
424
+ ) {
425
+ return {};
426
+ }
427
+
428
+ text = readFileSync(file, 'utf8');
429
+ } catch {
430
+ return {};
431
+ }
432
+
433
+ let manifest: unknown;
434
+
435
+ try {
436
+ manifest = JSON.parse(text);
437
+ } catch {
438
+ return {
439
+ warning: '.agents/vulcan.manifest.json is not valid JSON, so the neutral colour is used',
440
+ };
441
+ }
442
+
443
+ const theme: unknown =
444
+ typeof manifest === 'object' && manifest !== null
445
+ ? Reflect.get(manifest, 'theme')
446
+ : undefined;
447
+
448
+ if (theme === undefined) {
449
+ return {};
450
+ }
451
+
452
+ if (typeof theme !== 'object' || theme === null) {
453
+ return { warning: 'the manifest theme is not an object, so the neutral colour is used' };
454
+ }
455
+
456
+ const accent: unknown = Reflect.get(theme, 'accent');
457
+ const accentDark: unknown = Reflect.get(theme, 'accentDark');
458
+ const accentText: unknown = Reflect.get(theme, 'accentText');
459
+
460
+ if (!ProjectTheme.isHex(accent)) {
461
+ return {
462
+ warning: 'the manifest theme has no six-digit hex accent, so the neutral colour is used',
463
+ };
464
+ }
465
+
466
+ return {
467
+ theme: {
468
+ accent,
469
+ ...(ProjectTheme.isHex(accentDark) ? { accentDark } : {}),
470
+ ...(ProjectTheme.isHex(accentText) ? { accentText } : {}),
471
+ },
472
+ };
473
+ }
474
+ }
@@ -1,4 +1,7 @@
1
+ import { CompareChecks } from './compare-validate.ts';
2
+ import { KindsValidate } from './kinds-validate.ts';
1
3
  import type { TVisualizeSpec } from './schema.ts';
4
+ import { SourceRefs } from './sources.ts';
2
5
 
3
6
  interface ICell {
4
7
  row: number;
@@ -213,8 +216,15 @@ const checkKinds = (opts: { spec: TVisualizeSpec }): string[] => {
213
216
  return problems;
214
217
  };
215
218
 
216
- /** What a schema cannot say, for every kind on the page. */
217
- export const checkSpec = (opts: { spec: TVisualizeSpec }): string[] => [
218
- ...(opts.spec.flow === undefined ? [] : checkFlow({ flow: opts.spec.flow })),
219
- ...checkKinds({ spec: opts.spec }),
220
- ];
219
+ export class SpecValidation {
220
+ /** What a schema cannot say, for every kind on the page. */
221
+ static check(opts: { spec: TVisualizeSpec }): string[] {
222
+ return [
223
+ ...(opts.spec.flow === undefined ? [] : checkFlow({ flow: opts.spec.flow })),
224
+ ...checkKinds({ spec: opts.spec }),
225
+ ...KindsValidate.checkNew({ spec: opts.spec }),
226
+ ...CompareChecks.check({ spec: opts.spec }),
227
+ ...SourceRefs.check({ spec: opts.spec }),
228
+ ];
229
+ }
230
+ }
@@ -9,7 +9,7 @@ import type { TAnchorProblem } from './constants.ts';
9
9
  * here), so a reimplemented slugifier reports working links as broken. Reading the emitted `id="..."`
10
10
  * removes the guess; the check needs a build.
11
11
  */
12
- export interface IBrokenAnchor {
12
+ interface IBrokenAnchor {
13
13
  file: string;
14
14
  line: number;
15
15
  target: string;
@@ -76,43 +76,45 @@ const readAnchors = (opts: { dist: string }): Map<string, Set<string>> => {
76
76
  return anchorsByRoute;
77
77
  };
78
78
 
79
- /** Checks every `](page#fragment)` link of the markdown under `content` against the ids built in `dist`. */
80
- export const checkAnchors = (opts: {
81
- content: string;
82
- dist: string;
83
- }): { checked: number; broken: IBrokenAnchor[] } => {
84
- const { content } = opts;
85
- const anchorsByRoute = readAnchors({ dist: opts.dist });
86
- const broken: IBrokenAnchor[] = [];
87
- let checked = 0;
88
-
89
- for (const file of walk({ directory: content, extension: '.md' })) {
90
- // Fenced code carries example links that are not ours to resolve.
91
- const body = readFileSync(file, 'utf8').replace(/```[\s\S]*?```/g, (match) =>
92
- match.replace(/[^\n]/g, ' '),
93
- );
94
-
95
- for (const [index, text] of body.split('\n').entries()) {
96
- for (const match of text.matchAll(/\]\(([^)\s]*?)#([\w.-]+)\)/g)) {
97
- const [, page = '', anchor = ''] = match;
98
-
99
- if (page.startsWith('http')) {
100
- continue;
101
- }
102
-
103
- checked += 1;
104
-
105
- const ids = anchorsByRoute.get(resolveRoute({ file, target: page, content }));
106
- const target = `${page}#${anchor}`;
107
-
108
- if (ids === undefined) {
109
- broken.push({ file, line: index + 1, target, reason: AnchorProblems.MISSING_PAGE });
110
- } else if (!ids.has(anchor)) {
111
- broken.push({ file, line: index + 1, target, reason: AnchorProblems.DEAD_ANCHOR });
79
+ export class AnchorCheck {
80
+ /** Checks every `](page#fragment)` link of the markdown under `content` against the ids built in `dist`. */
81
+ static check(opts: { content: string; dist: string }): {
82
+ checked: number;
83
+ broken: IBrokenAnchor[];
84
+ } {
85
+ const { content } = opts;
86
+ const anchorsByRoute = readAnchors({ dist: opts.dist });
87
+ const broken: IBrokenAnchor[] = [];
88
+ let checked = 0;
89
+
90
+ for (const file of walk({ directory: content, extension: '.md' })) {
91
+ // Fenced code carries example links that are not ours to resolve.
92
+ const body = readFileSync(file, 'utf8').replace(/```[\s\S]*?```/g, (match) =>
93
+ match.replace(/[^\n]/g, ' '),
94
+ );
95
+
96
+ for (const [index, text] of body.split('\n').entries()) {
97
+ for (const match of text.matchAll(/\]\(([^)\s]*?)#([\w.-]+)\)/g)) {
98
+ const [, page = '', anchor = ''] = match;
99
+
100
+ if (page.startsWith('http')) {
101
+ continue;
102
+ }
103
+
104
+ checked += 1;
105
+
106
+ const ids = anchorsByRoute.get(resolveRoute({ file, target: page, content }));
107
+ const target = `${page}#${anchor}`;
108
+
109
+ if (ids === undefined) {
110
+ broken.push({ file, line: index + 1, target, reason: AnchorProblems.MISSING_PAGE });
111
+ } else if (!ids.has(anchor)) {
112
+ broken.push({ file, line: index + 1, target, reason: AnchorProblems.DEAD_ANCHOR });
113
+ }
112
114
  }
113
115
  }
114
116
  }
115
- }
116
117
 
117
- return { checked, broken };
118
- };
118
+ return { checked, broken };
119
+ }
120
+ }
@@ -1,8 +1,8 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import { ExitCodes } from '../common/index.ts';
3
- import { checkAnchors } from './anchors.ts';
3
+ import { AnchorCheck } from './anchors.ts';
4
4
  import { WikiDefaults, WikiFlags } from './constants.ts';
5
- import { checkSourceLinks } from './source-links.ts';
5
+ import { SourceLinkCheck } from './source-links.ts';
6
6
 
7
7
  /** The value after `--flag`, or the fallback; `undefined` when the flag has no value after it. */
8
8
  const valueOf = (opts: { args: string[]; flag: string; fallback?: string }): string | undefined => {
@@ -56,7 +56,7 @@ export const runSourceLinksCommand = (opts: { args: string[]; root: string }): n
56
56
  return ExitCodes.FAILURE;
57
57
  }
58
58
 
59
- const { checked, missing } = checkSourceLinks({
59
+ const { checked, missing } = SourceLinkCheck.check({
60
60
  root: opts.root,
61
61
  repo,
62
62
  directories: listOf({ value: directories }),
@@ -98,7 +98,7 @@ export const runAnchorsCommand = (opts: { args: string[]; root: string }): numbe
98
98
  return ExitCodes.FAILURE;
99
99
  }
100
100
 
101
- const { checked, broken } = checkAnchors({ content, dist });
101
+ const { checked, broken } = AnchorCheck.check({ content, dist });
102
102
 
103
103
  for (const entry of broken) {
104
104
  console.log(`${entry.file}:${entry.line} ${entry.reason}: ${entry.target}`);