@venizia/vulcan 0.4.8 → 0.4.9-0

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