@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
@@ -26,6 +26,10 @@ const MARK =
26
26
 
27
27
  /** A figure is drawn at most this much larger than its natural width, so a short flow does not turn into a poster. */
28
28
  const FIGURE_MAX = 1.25;
29
+ /** The page becomes one column at and below this viewport width. */
30
+ const STACKED_AT = 860;
31
+ /** The widest a figure can be drawn: the content column is 1208 px at most. */
32
+ const CONTENT_WIDTH = 1208;
29
33
 
30
34
  const sha256 = (opts: { text: string }): string =>
31
35
  `'sha256-${createHash('sha256').update(opts.text).digest('base64')}'`;
@@ -39,19 +43,39 @@ const BANNER_STATE: Record<string, string> = {
39
43
  };
40
44
 
41
45
  /**
42
- * For each figure width: the size it may take (never under FIGURE_FIT of its natural width, never past a quarter more),
46
+ * For each figure: the size it may take (never under FIGURE_FIT of its natural width, never past a quarter more),
43
47
  * and the rule that swaps the figure for its list below the viewport width at which it would shrink under FIGURE_FIT
44
- * of its natural size (text under 12 px). The 66 is the page and frame padding.
48
+ * of its natural size (text under 12 px). The 66 is the page and frame padding. A key is the width, or the width and
49
+ * the inset: the space a figure shares with something beside it (the numeral of an explainer step) while the page
50
+ * is wide enough for the two columns; at and below 860 px the page is one column and the inset is gone.
45
51
  */
46
- const figureFitCss = (opts: { widths: Set<number> }): string =>
47
- [...opts.widths]
48
- .sort((a, b) => a - b)
49
- .map((width) => {
50
- const at = Math.ceil(width * FIGURE_FIT) + 66;
52
+ const figureFitCss = (opts: { keys: Set<string> }): string =>
53
+ [...opts.keys]
54
+ .sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10))
55
+ .map((key) => {
56
+ const [widthText = '0', insetText = '0', frameText = '0'] = key.split(':');
57
+ const width = Number(widthText);
58
+ const inset = Number(insetText);
59
+ const frame = Number(frameText);
60
+ const name = FigureLayout.fitName({ key });
51
61
  const least = Math.ceil(width * FIGURE_FIT);
52
62
  const most = Math.ceil(width * FIGURE_MAX);
63
+ const swap = `.fig.${name}{display:none}.fig.${name}~.path,.fig.${name}~.path-detail{display:block}.fig.${name}~.say,.fig.${name}~.legend{display:none}.fig.${name}~.steps .explain{display:block}.fig.${name}~.steps button{pointer-events:none}`;
64
+ const narrow = least + 66 + frame;
65
+ const wide = narrow + inset;
66
+ const rules =
67
+ least > CONTENT_WIDTH - inset - frame
68
+ ? [swap]
69
+ : inset === 0
70
+ ? [`@media (max-width:${narrow}px){${swap}}`]
71
+ : [
72
+ `@media (max-width:${Math.min(narrow, STACKED_AT)}px){${swap}}`,
73
+ ...(wide > STACKED_AT
74
+ ? [`@media (min-width:${STACKED_AT + 1}px) and (max-width:${wide}px){${swap}}`]
75
+ : []),
76
+ ];
53
77
 
54
- return `.fig.f${width} svg{min-width:${least}px;max-width:${most}px}\n@media (max-width:${at}px){.fig.f${width}{display:none}.fig.f${width}~.path,.fig.f${width}~.path-detail{display:block}.fig.f${width}~.say,.fig.f${width}~.legend{display:none}.fig.f${width}~.steps .explain{display:block}.fig.f${width}~.steps button{pointer-events:none}}`;
78
+ return `.fig.${name} svg{min-width:${least}px;max-width:${most}px}\n${rules.join('\n')}`;
55
79
  })
56
80
  .join('\n');
57
81
 
@@ -102,6 +126,47 @@ const stateOf = (opts: {
102
126
  return { state, tone: NodeStates.toneOf(state), word };
103
127
  };
104
128
 
129
+ /** The group each part belongs to: the small amber label above its heading. */
130
+ const KICKS: Record<string, keyof TChrome> = {
131
+ flow: 'kickOverview',
132
+ minimap: 'kickOverview',
133
+ next: 'kickOverview',
134
+ architecture: 'kickStructure',
135
+ compare: 'kickStructure',
136
+ sequence: 'kickStructure',
137
+ lifecycle: 'kickStructure',
138
+ tree: 'kickStructure',
139
+ 'idea-map': 'kickStructure',
140
+ comparison: 'kickDecision',
141
+ 'decision-record': 'kickDecision',
142
+ decisions: 'kickDecision',
143
+ findings: 'kickEvidence',
144
+ grades: 'kickEvidence',
145
+ metrics: 'kickEvidence',
146
+ evidence: 'kickEvidence',
147
+ explainer: 'kickPlan',
148
+ timeline: 'kickPlan',
149
+ 'before-after': 'kickPlan',
150
+ risks: 'kickReference',
151
+ log: 'kickReference',
152
+ terms: 'kickReference',
153
+ sources: 'kickReference',
154
+ links: 'kickReference',
155
+ };
156
+
157
+ /** Puts the label above the heading of every part that has a group. */
158
+ const withKickers = (opts: { html: string; chrome: TChrome }): string =>
159
+ opts.html.replace(
160
+ /(<section class="[^"]*" id="([a-z-]+)" data-slide><div class="wrap">)(<h2 class="sh">)/g,
161
+ (match, open: string, id: string, heading: string) => {
162
+ const key = KICKS[id];
163
+
164
+ return key === undefined
165
+ ? match
166
+ : `${open}<p class="kick">${escaped(String(opts.chrome[key]))}</p>${heading}`;
167
+ },
168
+ );
169
+
105
170
  /** The always-dark hero: the state, the title, the verdict, the caption, and the flow when the spec has one. */
106
171
  const heroHtml = (opts: { ctx: ISectionContext }): string => {
107
172
  const { spec, chrome } = opts.ctx;
@@ -111,7 +176,7 @@ const heroHtml = (opts: { ctx: ISectionContext }): string => {
111
176
  spec.scope === undefined ? '' : `<span>${escaped(chrome.scope)}: ${escaped(spec.scope)}</span>`,
112
177
  ].join('');
113
178
 
114
- return `<div class="banner slab c-${tone}" data-slide data-hero><div class="wrap hero"><p class="state">${SpecCharts.stateIcon({ state, size: 22 })}<span class="word">${escaped(word)}</span></p><h1>${escaped(spec.title)}</h1><p class="lede">${escaped(spec.verdict)}</p>${spec.caption === undefined ? '' : `<p class="cap">${escaped(spec.caption)}</p>`}${meta === '' ? '' : `<p class="meta">${meta}</p>`}${SpecSections.flow({ ctx: opts.ctx })}</div></div>`;
179
+ return `<div class="banner slab c-${tone}" data-slide data-hero><div class="wrap hero"><p class="state">${SpecCharts.stateIcon({ state, size: 22 })}<span class="word">${escaped(word)}</span></p><h1>${escaped(spec.title)}${spec.titleMuted === undefined ? '' : ` <span class="mute">${escaped(spec.titleMuted)}</span>`}</h1><p class="lede">${escaped(spec.verdict)}</p>${spec.caption === undefined ? '' : `<p class="cap">${escaped(spec.caption)}</p>`}${meta === '' ? '' : `<p class="meta">${meta}</p>`}${SpecSections.flow({ ctx: opts.ctx })}</div></div>`;
115
180
  };
116
181
 
117
182
  /** The minimap as a track: a stripe, a shape and a word for every task. */
@@ -152,13 +217,13 @@ const ownerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
152
217
  return `<section class="two" id="next" data-slide><div class="wrap"><div class="own"><div class="nx"><p class="lab">${escaped(chrome.next)}</p><h2>${escaped(spec.strip.next)}</h2>${actions}${jump}</div><div class="stop"><p class="lab">${escaped(chrome.blockedBy)}</p><p>${escaped(spec.strip.blockedBy)}</p></div></div><div class="facts"><p class="fact">${IconSet.iconSvg({ name: 'done', size: 18 })}<span><b>${escaped(chrome.healthy)}</b> ${escaped(spec.strip.healthy)}</span></p><p class="fact">${IconSet.iconSvg({ name: 'info', size: 18 })}<span><b>${escaped(chrome.changed)}</b> ${escaped(spec.strip.changed)}</span></p></div></div></section>`;
153
218
  };
154
219
 
155
- /** The neutral theme of a page that is given none. */
156
- const NEUTRAL = ((): IResolvedTheme => {
220
+ /** The theme of a page that is given none: the default preset. */
221
+ const DEFAULT_THEME = ((): IResolvedTheme => {
157
222
  const resolved = ProjectTheme.resolve({});
158
223
 
159
224
  if (!resolved.ok) {
160
225
  throw new Error(
161
- `the neutral theme does not pass its own checks: ${resolved.problems.join('; ')}`,
226
+ `the default theme does not pass its own checks: ${resolved.problems.join('; ')}`,
162
227
  );
163
228
  }
164
229
 
@@ -180,7 +245,7 @@ export class PageShell {
180
245
  const ctx: ISectionContext = {
181
246
  spec,
182
247
  chrome,
183
- fits: new Set<number>(),
248
+ fits: new Set<string>(),
184
249
  spans: new Set<number>(),
185
250
  };
186
251
  const { state, tone, word } = stateOf({ spec, chrome });
@@ -204,6 +269,8 @@ export class PageShell {
204
269
  SpecSections.explainer({ ctx }),
205
270
  SpecSections.timeline({ ctx }),
206
271
  SpecSections.findings({ ctx }),
272
+ SpecSections.grades({ ctx }),
273
+ SpecSections.metrics({ ctx }),
207
274
  SpecSections.beforeAfter({ ctx }),
208
275
  SpecSections.decisionRecord({ ctx }),
209
276
  SpecSections.decisions({ ctx }),
@@ -226,7 +293,7 @@ export class PageShell {
226
293
  }),
227
294
  SpecSections.links({ ctx }),
228
295
  ].join('');
229
- const css = `${Assets.pageCss({ tokens: ProjectTheme.tokensCss({ theme: opts.theme ?? NEUTRAL }) })}\n${NEW_KINDS_CSS}\n${COMPARE_CSS}\n${GridSpans.css({ spans: ctx.spans })}\n${figureFitCss({ widths: ctx.fits })}`;
296
+ const css = `${Assets.pageCss({ tokens: ProjectTheme.tokensCss({ theme: opts.theme ?? DEFAULT_THEME }) })}\n${NEW_KINDS_CSS}\n${COMPARE_CSS}\n${GridSpans.css({ spans: ctx.spans })}\n${figureFitCss({ keys: ctx.fits })}`;
230
297
  const policy = `default-src 'none'; style-src ${sha256({ text: css })}; script-src ${sha256({ text: HEAD_JS })} ${sha256({ text: PAGE_JS })}; base-uri 'none'; form-action 'none'`;
231
298
  const links = SpecSections.sectionLinks({ spec, chrome })
232
299
  .map((link) => `<a href="#${link.id}">${escaped(link.title)}</a>`)
@@ -238,6 +305,6 @@ export class PageShell {
238
305
  const bar = `<header class="top slab c-${tone}"><div class="wrap">${MARK}<b class="ttl">${escaped(spec.title)}</b>${SpecSections.chip({ chrome, state, size: 18, label: word })}<nav aria-label="${escaped(chrome.navLabel)}"><span class="links">${links}</span>${stamp}<span class="sep" aria-hidden="true"></span><button class="btn js-only" id="present" type="button" data-on="${escaped(chrome.present)}" data-off="${escaped(chrome.exitPresent)}">${escaped(chrome.present)}</button><button class="theme" id="theme" type="button" aria-label="${escaped(chrome.themeToDark)}" data-to-light="${escaped(chrome.themeToLight)}" data-to-dark="${escaped(chrome.themeToDark)}">${IconSet.iconSvg({ name: 'sun', size: 20, className: 'sun' })}${IconSet.iconSvg({ name: 'moon', size: 20, className: 'moon' })}<span class="tip" aria-hidden="true"></span></button></nav></div></header>`;
239
306
  const deck = `<nav class="deck" aria-label="${escaped(chrome.slide)}"><button class="btn" id="slide-prev" type="button">${escaped(chrome.previous)}</button><span id="slide-count" aria-live="polite"></span><button class="btn" id="slide-next" type="button">${escaped(chrome.following)}</button></nav>`;
240
307
 
241
- return `<!doctype html><html lang="${escaped(language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta http-equiv="Content-Security-Policy" content="${escaped(policy)}"><meta name="generator" content="vulcan visualize"><title>${escaped(spec.title)}</title><script>${HEAD_JS}</script><style>${css}</style></head><body>${bar}<main>${body}</main><footer class="slab foot"><div class="wrap"><p>${escaped(chrome.footer)}</p></div></footer>${deck}<script>${PAGE_JS}</script></body></html>`;
308
+ return `<!doctype html><html lang="${escaped(language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta http-equiv="Content-Security-Policy" content="${escaped(policy)}"><meta name="generator" content="vulcan visualize"><title>${escaped(spec.title)}</title><script>${HEAD_JS}</script><style>${css}</style></head><body>${bar}<main>${withKickers({ html: body, chrome })}</main><footer class="slab foot"><div class="wrap"><p>${escaped(chrome.footer)}</p></div></footer>${deck}<script>${PAGE_JS}</script></body></html>`;
242
309
  }
243
310
  }
@@ -39,6 +39,7 @@ const CHECKS = [
39
39
  "no network, no font, no image, a policy that allows only the page's own style and script",
40
40
  ];
41
41
 
42
+ /** Validates a JSON spec and renders it as one static HTML page; used by `vulcan visualize`. */
42
43
  export class SpecPage {
43
44
  /** Spec text to a page: parse, validate, cross-check, render, size gate. Nothing is written here. */
44
45
  static renderText(opts: { text: string; context?: IRenderContext }): TRenderResult {
@@ -115,7 +116,7 @@ export class SpecPage {
115
116
  checks: [
116
117
  ...CHECKS,
117
118
  PageGate.CHECK,
118
- `colour from the ${themed.theme.source === 'spec' ? "spec's accent" : themed.theme.source === 'project' ? "project's theme" : 'neutral default'}: every text, mark and fill pair checked`,
119
+ `colour from the ${themed.theme.source === 'spec' ? "spec's accent" : themed.theme.source === 'project' ? "project's theme" : 'default preset'}: every text, mark and fill pair checked`,
119
120
  ...themed.theme.notes,
120
121
  `size ${(bytes / 1024).toFixed(1)} KB, within ${VisualizeLimits.FAIL_BYTES / 1024} KB`,
121
122
  ],
@@ -12,7 +12,13 @@ import {
12
12
  } from './constants.ts';
13
13
  import type { TChangeKind } from './constants.ts';
14
14
  import { COMPARE_SCHEMA } from './compare-schema.ts';
15
- import { LIFECYCLE_SCHEMA, SEQUENCE_SCHEMA, TREE_SCHEMA } from './kinds-schema.ts';
15
+ import {
16
+ GRADES_SCHEMA,
17
+ LIFECYCLE_SCHEMA,
18
+ METRICS_SCHEMA,
19
+ SEQUENCE_SCHEMA,
20
+ TREE_SCHEMA,
21
+ } from './kinds-schema.ts';
16
22
  import { SOURCE_SCHEMA, TERMS_SCHEMA } from './sources.ts';
17
23
 
18
24
  /** One line of plain text: no markup is interpreted anywhere, it is all escaped. */
@@ -324,6 +330,24 @@ const CHROME = z
324
330
  guess: text(VisualizeLimits.MAX_LABEL).optional(),
325
331
  })
326
332
  .optional(),
333
+ nodeKinds: z
334
+ .strictObject({
335
+ step: text(VisualizeLimits.MAX_LABEL).optional(),
336
+ service: text(VisualizeLimits.MAX_LABEL).optional(),
337
+ store: text(VisualizeLimits.MAX_LABEL).optional(),
338
+ actor: text(VisualizeLimits.MAX_LABEL).optional(),
339
+ external: text(VisualizeLimits.MAX_LABEL).optional(),
340
+ })
341
+ .optional(),
342
+ edgeVariants: z
343
+ .strictObject({
344
+ main: text(VisualizeLimits.MAX_LABEL).optional(),
345
+ branch: text(VisualizeLimits.MAX_LABEL).optional(),
346
+ return: text(VisualizeLimits.MAX_LABEL).optional(),
347
+ fanout: text(VisualizeLimits.MAX_LABEL).optional(),
348
+ error: text(VisualizeLimits.MAX_LABEL).optional(),
349
+ })
350
+ .optional(),
327
351
  })
328
352
  .optional();
329
353
 
@@ -332,6 +356,8 @@ export const VISUALIZE_SCHEMA = z.strictObject({
332
356
  schemaVersion: z.literal(VisualizeLimits.SCHEMA_VERSION),
333
357
  /** The takeaway, not a topic. */
334
358
  title: text(VisualizeLimits.MAX_TITLE),
359
+ /** The second half of the headline, shown muted after the title. */
360
+ titleMuted: text(VisualizeLimits.MAX_TITLE).optional(),
335
361
  /** The page's language; absent, it is the owner's profile language, else English. */
336
362
  language: z
337
363
  .string()
@@ -398,6 +424,8 @@ export const VISUALIZE_SCHEMA = z.strictObject({
398
424
  explainer: EXPLAINER.optional(),
399
425
  timeline: TIMELINE.optional(),
400
426
  findings: FINDINGS.optional(),
427
+ grades: GRADES_SCHEMA.optional(),
428
+ metrics: METRICS_SCHEMA.optional(),
401
429
  sequence: SEQUENCE_SCHEMA.optional(),
402
430
  lifecycle: LIFECYCLE_SCHEMA.optional(),
403
431
  tree: TREE_SCHEMA.optional(),
@@ -13,13 +13,18 @@ import { SourceRefs } from './sources.ts';
13
13
  export interface ISectionContext {
14
14
  spec: TVisualizeSpec;
15
15
  chrome: TChrome;
16
- fits: Set<number>;
16
+ fits: Set<string>;
17
17
  /** The row spans the page uses (see `GridSpans`). */
18
18
  spans: Set<number>;
19
19
  }
20
20
 
21
21
  const escaped = (value: string): string => FigureLayout.escapeText({ value });
22
22
 
23
+ /** The numeral column and the gap of an explainer step: space a step diagram does not have beside the text. */
24
+ const EXPLAINER_INSET = 128;
25
+ /** The padding of a figure's frame (`.win`) on both sides: space the figure does not have. */
26
+ const WIN_FRAME = 32;
27
+
23
28
  /** JSON for a `<script type="application/json">`: nothing in it can close the tag or start a comment. */
24
29
  const jsonForScript = (opts: { value: unknown }): string =>
25
30
  JSON.stringify(opts.value)
@@ -75,6 +80,8 @@ export class SpecSections {
75
80
  [spec.explainer !== undefined, 'explainer', chrome.explainer],
76
81
  [spec.timeline !== undefined, 'timeline', chrome.timeline],
77
82
  [spec.findings !== undefined, 'findings', chrome.findings],
83
+ [spec.grades !== undefined, 'grades', chrome.grades],
84
+ [spec.metrics !== undefined, 'metrics', chrome.metrics],
78
85
  [spec.beforeAfter !== undefined, 'before-after', `${chrome.before} / ${chrome.after}`],
79
86
  [spec.decisionRecord !== undefined, 'decision-record', chrome.decisionRecord],
80
87
  [spec.decisions !== undefined, 'decisions', chrome.decisions],
@@ -101,7 +108,7 @@ export class SpecSections {
101
108
  return '';
102
109
  }
103
110
 
104
- const width = FigureLayout.figureWidth({ cols: FigureLayout.columnsOf({ flow }) });
111
+ const width = FigureLayout.widthOf({ nodes: flow.nodes, edges: flow.edges });
105
112
  const kinds = [...new Set(flow.nodes.map((node) => node.kind ?? 'step'))];
106
113
  const variants = [...new Set(flow.edges.map((edge) => edge.variant ?? 'main'))];
107
114
  const states = [
@@ -110,10 +117,16 @@ export class SpecSections {
110
117
  const steps = flow.steps;
111
118
  const legend = [
112
119
  ...states.map((state) => `<li>${SpecSections.chip({ chrome, state })}</li>`),
113
- ...(kinds.length > 1 ? kinds.map((kind) => `<li>${escaped(kind)}</li>`) : []),
120
+ ...(kinds.length > 1
121
+ ? kinds.map(
122
+ (kind) =>
123
+ `<li>${escaped(chrome.nodeKinds[kind as keyof TChrome['nodeKinds']] ?? kind)}</li>`,
124
+ )
125
+ : []),
114
126
  ...(variants.length > 1
115
127
  ? variants.map(
116
- (variant) => `<li>${variantSwatch({ variant })}<span>${escaped(variant)}</span></li>`,
128
+ (variant) =>
129
+ `<li>${variantSwatch({ variant })}<span>${escaped(chrome.edgeVariants[variant as keyof TChrome['edgeVariants']] ?? variant)}</span></li>`,
117
130
  )
118
131
  : []),
119
132
  ];
@@ -126,7 +139,7 @@ export class SpecSections {
126
139
  ? `<button class="btn" id="all" type="button" hidden>${escaped(chrome.allSteps)}</button>`
127
140
  : '';
128
141
 
129
- opts.ctx.fits.add(width);
142
+ opts.ctx.fits.add(`${width}`);
130
143
 
131
144
  // A box that has a source says it in its detail line: on hover, and in the phone list.
132
145
  const shown = {
@@ -250,7 +263,7 @@ export class SpecSections {
250
263
  body: `<ol class="ex">${explainer.steps
251
264
  .map(
252
265
  (step, index) =>
253
- `<li class="estep"><span class="no">${index + 1}</span><div class="sb"><h3>${escaped(step.title)}</h3><p>${escaped(step.text)}</p></div>${step.diagram === undefined ? '' : `<div class="dg">${SpecSections.figure({ ctx: opts.ctx, drawing: SpecDiagrams.render({ diagram: step.diagram }) })}</div>`}</li>`,
266
+ `<li class="estep"><span class="no">${index + 1}</span><div class="sb"><h3>${escaped(step.title)}</h3><p>${escaped(step.text)}</p></div>${step.diagram === undefined ? '' : `<div class="dg">${SpecSections.figure({ ctx: opts.ctx, drawing: SpecDiagrams.render({ diagram: step.diagram }), inset: EXPLAINER_INSET })}</div>`}</li>`,
254
267
  )
255
268
  .join('')}</ol>`,
256
269
  });
@@ -304,6 +317,60 @@ export class SpecSections {
304
317
  });
305
318
  }
306
319
 
320
+ /** A grade for each area: a chip whose letter is always shown, so colour is never the only signal. */
321
+ static grades(opts: { ctx: ISectionContext }): string {
322
+ const { grades } = opts.ctx.spec;
323
+ const { chrome } = opts.ctx;
324
+ const tones: Record<string, string> = { A: 'ok', B: 'info', C: 'bad' };
325
+ const words: Record<string, string> = { A: chrome.gradeA, B: chrome.gradeB, C: chrome.gradeC };
326
+
327
+ if (grades === undefined) {
328
+ return '';
329
+ }
330
+
331
+ return SpecSections.section({
332
+ id: 'grades',
333
+ title: chrome.grades,
334
+ body: `<ul class="grades">${grades
335
+ .map(
336
+ (item) =>
337
+ `<li><span class="gn">${escaped(item.label)}</span><span class="gr c-${tones[item.grade]}"><b>${item.grade}</b>${escaped(words[item.grade] ?? '')}</span>${item.note === undefined ? '' : `<span class="gt">${escaped(item.note)}</span>`}</li>`,
338
+ )
339
+ .join('')}</ul>`,
340
+ });
341
+ }
342
+
343
+ /** Numbers as cards: the value, what it is of, and a bar split into its parts with a legend that says each. */
344
+ static metrics(opts: { ctx: ISectionContext }): string {
345
+ const { metrics } = opts.ctx.spec;
346
+ const { chrome } = opts.ctx;
347
+
348
+ if (metrics === undefined) {
349
+ return '';
350
+ }
351
+
352
+ const card = (metric: NonNullable<TVisualizeSpec['metrics']>[number]): string => {
353
+ const total = metric.parts.reduce((sum, part) => sum + part.value, 0);
354
+ let at = 0;
355
+ const rects = metric.parts.map((part) => {
356
+ const width = (part.value / total) * 100;
357
+ const rect = `<rect class="t-${part.tone}" x="${at.toFixed(2)}" width="${width.toFixed(2)}" height="8"/>`;
358
+
359
+ at += width;
360
+
361
+ return rect;
362
+ });
363
+
364
+ return `<li class="mc"><p class="mv">${escaped(metric.value)}${metric.of === undefined ? '' : `<small>/ ${escaped(metric.of)}</small>`}</p><p class="ml">${escaped(metric.label)}</p>${metric.note === undefined ? '' : `<p class="mt">${escaped(metric.note)}</p>`}<svg class="mb" viewBox="0 0 100 8" preserveAspectRatio="none" role="img" aria-label="${escaped(metric.parts.map((part) => `${part.label}: ${part.value}`).join(', '))}">${rects.join('')}</svg><ul class="mlg">${metric.parts.map((part) => `<li><i class="sw t-${part.tone}"></i>${escaped(part.label)}: ${part.value}</li>`).join('')}</ul></li>`;
365
+ };
366
+
367
+ return SpecSections.section({
368
+ id: 'metrics',
369
+ title: chrome.metrics,
370
+ body: `<ul class="metrics">${metrics.map(card).join('')}</ul>`,
371
+ });
372
+ }
373
+
307
374
  static beforeAfter(opts: { ctx: ISectionContext }): string {
308
375
  const { beforeAfter } = opts.ctx.spec;
309
376
  const { chrome } = opts.ctx;
@@ -452,11 +519,13 @@ export class SpecSections {
452
519
  }
453
520
 
454
521
  /** A drawing in a dark window; below the width where its text would pass 12 px the list takes its place. */
455
- static figure(opts: { ctx: ISectionContext; drawing: IDrawing }): string {
522
+ static figure(opts: { ctx: ISectionContext; drawing: IDrawing; inset?: number }): string {
456
523
  const width = Math.round(opts.drawing.width);
524
+ const inset = opts.inset ?? 0;
525
+ const key = `${width}:${inset}:${WIN_FRAME}`;
457
526
 
458
- opts.ctx.fits.add(width);
527
+ opts.ctx.fits.add(key);
459
528
 
460
- return `<div class="win"><div class="fig f${width}">${opts.drawing.svg}</div>${opts.drawing.fallback}</div>`;
529
+ return `<div class="win"><div class="fig ${FigureLayout.fitName({ key })}">${opts.drawing.svg}</div>${opts.drawing.fallback}</div>`;
461
530
  }
462
531
  }
@@ -142,8 +142,8 @@ const ratioText = (value: number): string => `${value.toFixed(2)}:1`;
142
142
 
143
143
  /** The fixed grounds: tinted a little toward the accent, so a page reads as the project's own. */
144
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' },
145
+ light: { bg: '#ffffff', bgSoft: '#f6f6f7', ink: '#0e0e0f', body: '#3a3a3d', muted: '#66666b' },
146
+ dark: { bg: '#1b1b1f', bgSoft: '#202127', ink: '#f6f6f7', body: '#d0d0d4', muted: '#a2a2a8' },
147
147
  slab: {
148
148
  slab: '#151517',
149
149
  slab2: '#202023',
@@ -154,25 +154,28 @@ const GROUNDS = {
154
154
  },
155
155
  slabDark: { slab: '#0b0b0c', slab2: '#19191b', slab3: '#252528' },
156
156
  accentLightSoft: 0.12,
157
- accentDarkSoft: 0.14,
157
+ accentDarkSoft: 0.12,
158
158
  tint: 0.035,
159
159
  };
160
160
 
161
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' };
162
+ /** The colour of a page whose project says nothing: the venizia bronze, the seeds of the default preset. */
163
+ static readonly DEFAULT: IThemeInput = { accent: '#8a5a20', accentDark: '#dead6a' };
164
164
 
165
165
  /** The manifest is read only up to this size: a real one is a few KB. */
166
166
  static readonly MAX_MANIFEST_BYTES = 1024 * 1024;
167
167
 
168
+ /** The six-digit hex colour pattern, the one the config and the tokens check with. */
169
+ static readonly HEX = HEX;
170
+
168
171
  /** Whether `value` is a six-digit hex colour. */
169
172
  static isHex(value: unknown): value is string {
170
173
  return typeof value === 'string' && HEX.test(value);
171
174
  }
172
175
 
173
176
  /**
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
177
+ * The theme of a page: the spec's own accent, else the project's `theme` from the manifest, else the default
178
+ * preset. Every text, mark and fill pair is checked; a failure writes nothing and says the colour, the ground
176
179
  * and the ratio. A colour is never swapped for another.
177
180
  */
178
181
  static resolve(opts: { spec?: IThemeInput; project?: IThemeInput }): TThemeResult {
@@ -393,21 +396,21 @@ export class ProjectTheme {
393
396
  }
394
397
 
395
398
  /**
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.
399
+ * The theme blocks: dark on `:root`, then the system light setting unless the page was set to dark, then an
400
+ * explicit light. The same tokens in each.
398
401
  */
399
402
  static tokensCss(opts: { theme: IResolvedTheme }): string {
400
403
  const light = ProjectTheme.declarations({ palette: opts.theme.light });
401
404
  const dark = ProjectTheme.declarations({ palette: opts.theme.dark });
402
405
 
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}`;
406
+ return `:root{${dark};color-scheme:dark}\n@media (prefers-color-scheme:light){:root:not([data-theme=dark]){${light};color-scheme:light}}\n:root[data-theme=light]{${light};color-scheme:light}`;
404
407
  }
405
408
 
406
409
  /**
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.
410
+ * The `theme` block of the manifest of the folder the command runs in. No config file is loaded and nothing is
411
+ * requested: a missing file, or a manifest with no `theme`, gives no block and no warning.
409
412
  */
410
- static readManifestTheme(opts: { root: string }): { theme?: IThemeInput; warning?: string } {
413
+ static readManifestBlock(opts: { root: string }): { block?: object; warning?: string } {
411
414
  let text: string;
412
415
 
413
416
  try {
@@ -436,7 +439,7 @@ export class ProjectTheme {
436
439
  manifest = JSON.parse(text);
437
440
  } catch {
438
441
  return {
439
- warning: '.agents/vulcan.manifest.json is not valid JSON, so the neutral colour is used',
442
+ warning: '.agents/vulcan.manifest.json is not valid JSON, so the default colour is used',
440
443
  };
441
444
  }
442
445
 
@@ -450,16 +453,44 @@ export class ProjectTheme {
450
453
  }
451
454
 
452
455
  if (typeof theme !== 'object' || theme === null) {
453
- return { warning: 'the manifest theme is not an object, so the neutral colour is used' };
456
+ return { warning: 'the manifest theme is not an object, so the default colour is used' };
457
+ }
458
+
459
+ return { block: theme };
460
+ }
461
+
462
+ /**
463
+ * The accent seeds of the project's `theme` in the manifest, for the pages `vulcan visualize` makes. A missing file, or a
464
+ * manifest with no `theme`, is the default preset.
465
+ */
466
+ static readManifestTheme(opts: { root: string }): { theme?: IThemeInput; warning?: string } {
467
+ const { block: theme, warning } = ProjectTheme.readManifestBlock(opts);
468
+
469
+ if (theme === undefined) {
470
+ return warning === undefined ? {} : { warning };
454
471
  }
455
472
 
456
- const accent: unknown = Reflect.get(theme, 'accent');
457
- const accentDark: unknown = Reflect.get(theme, 'accentDark');
473
+ // A manifest that holds only the resolved tokens (a project that set no accent) gives the accent of its preset.
474
+ const tokens: unknown = Reflect.get(theme, 'tokens');
475
+ const modeOf = (mode: string): unknown =>
476
+ typeof tokens === 'object' && tokens !== null ? Reflect.get(tokens, mode) : undefined;
477
+ const resolvedAccent = (mode: string): unknown => {
478
+ const palette = modeOf(mode);
479
+
480
+ return typeof palette === 'object' && palette !== null
481
+ ? Reflect.get(palette, 'accent')
482
+ : undefined;
483
+ };
484
+ const given: unknown = Reflect.get(theme, 'accent');
485
+ const accent: unknown = given ?? resolvedAccent('light');
486
+ const accentDark: unknown =
487
+ Reflect.get(theme, 'accentDark') ??
488
+ (given === undefined ? resolvedAccent('dark') : undefined);
458
489
  const accentText: unknown = Reflect.get(theme, 'accentText');
459
490
 
460
491
  if (!ProjectTheme.isHex(accent)) {
461
492
  return {
462
- warning: 'the manifest theme has no six-digit hex accent, so the neutral colour is used',
493
+ warning: 'the manifest theme has no six-digit hex accent, so the default colour is used',
463
494
  };
464
495
  }
465
496
 
@@ -76,6 +76,7 @@ const readAnchors = (opts: { dist: string }): Map<string, Set<string>> => {
76
76
  return anchorsByRoute;
77
77
  };
78
78
 
79
+ /** Checks that the heading links in wiki content resolve to a built page anchor; run by `make wiki-anchors-check`. */
79
80
  export class AnchorCheck {
80
81
  /** Checks every `](page#fragment)` link of the markdown under `content` against the ids built in `dist`. */
81
82
  static check(opts: { content: string; dist: string }): {
@@ -1,8 +1,9 @@
1
1
  import { existsSync } from 'node:fs';
2
2
  import { ExitCodes } from '../common/index.ts';
3
+ import type { ILayout } from '../common/layout-folder.ts';
3
4
  import { AnchorCheck } from './anchors.ts';
4
5
  import { WikiDefaults, WikiFlags } from './constants.ts';
5
- import { SourceLinkCheck } from './source-links.ts';
6
+ import { SourceLinkCheck, SourceRoots } from './source-links.ts';
6
7
 
7
8
  /** The value after `--flag`, or the fallback; `undefined` when the flag has no value after it. */
8
9
  const valueOf = (opts: { args: string[]; flag: string; fallback?: string }): string | undefined => {
@@ -25,9 +26,14 @@ const listOf = (opts: { value: string }): string[] =>
25
26
 
26
27
  /**
27
28
  * `wiki-source-links --repo <owner/name>`: every source path the wiki names is tracked by git. Run from the
28
- * repository root; the other flags replace the defaults (comma-separated lists).
29
+ * repository root; the other flags replace the defaults (comma-separated lists). The source folders it checks come
30
+ * from the project's `layout` (`SourceRoots.of`); the caller reads the config and passes the layout.
29
31
  */
30
- export const runSourceLinksCommand = (opts: { args: string[]; root: string }): number => {
32
+ export const runSourceLinksCommand = (opts: {
33
+ args: string[];
34
+ root: string;
35
+ layout?: ILayout;
36
+ }): number => {
31
37
  const { args } = opts;
32
38
  const repo = valueOf({ args, flag: WikiFlags.REPO });
33
39
  const directories = valueOf({
@@ -62,6 +68,7 @@ export const runSourceLinksCommand = (opts: { args: string[]; root: string }): n
62
68
  directories: listOf({ value: directories }),
63
69
  skipProseUnder: listOf({ value: skipProse }),
64
70
  skipFiles: listOf({ value: skip }),
71
+ roots: SourceRoots.of({ layout: opts.layout }),
65
72
  });
66
73
 
67
74
  for (const miss of missing) {