@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -1,16 +1,34 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { PAGE_CSS, PAGE_JS } from './assets.ts';
3
- import { DEFAULT_CHROME } from './constants.ts';
3
+ import { DEFAULT_CHROME, NodeStates } from './constants.ts';
4
4
  import type { TChrome } from './constants.ts';
5
- import { escapeText, renderFigure } from './layout.ts';
5
+ import { iconSvg } from './icons.ts';
6
+ import { stateIcon } from './charts.ts';
7
+ import { escapeText, FIGURE_FIT } from './layout.ts';
6
8
  import type { TVisualizeSpec } from './schema.ts';
9
+ import {
10
+ architectureSection,
11
+ beforeAfterSection,
12
+ chip,
13
+ comparisonSection,
14
+ decisionRecordSection,
15
+ decisionsSection,
16
+ evidenceSection,
17
+ explainerSection,
18
+ findingsSection,
19
+ flowSection,
20
+ ideaMapSection,
21
+ linksSection,
22
+ logSection,
23
+ risksSection,
24
+ stateWord,
25
+ tilesHtml,
26
+ timelineSection,
27
+ } from './sections.ts';
28
+ import type { ISectionContext } from './sections.ts';
7
29
 
8
30
  const escaped = (value: string): string => escapeText({ value });
9
31
 
10
- /** A page word by its key; a key the page does not know shows as itself. */
11
- const wordOf = (opts: { words: Record<string, string>; key: string }): string =>
12
- opts.words[opts.key] ?? opts.key;
13
-
14
32
  const definedOnly = (opts: {
15
33
  value: Record<string, string | undefined> | undefined;
16
34
  }): Record<string, string> =>
@@ -35,6 +53,10 @@ export const chromeOf = (opts: { spec: TVisualizeSpec }): TChrome => {
35
53
  ...DEFAULT_CHROME,
36
54
  ...Object.fromEntries(Object.entries(merged).filter(([, value]) => typeof value === 'string')),
37
55
  statusStates: { ...DEFAULT_CHROME.statusStates, ...definedOnly({ value: given.statusStates }) },
56
+ minimapStates: {
57
+ ...DEFAULT_CHROME.minimapStates,
58
+ ...definedOnly({ value: given.minimapStates }),
59
+ },
38
60
  evidenceLabels: {
39
61
  ...DEFAULT_CHROME.evidenceLabels,
40
62
  ...definedOnly({ value: given.evidenceLabels }),
@@ -42,170 +64,154 @@ export const chromeOf = (opts: { spec: TVisualizeSpec }): TChrome => {
42
64
  };
43
65
  };
44
66
 
45
- /** JSON for a `<script type="application/json">`: nothing in it can close the tag or start a comment. */
46
- const jsonForScript = (opts: { value: unknown }): string =>
47
- JSON.stringify(opts.value)
48
- .replaceAll('<', '\\u003c')
49
- .replaceAll('>', '\\u003e')
50
- .replaceAll('&', '\\u0026')
51
- .replaceAll('
', '\\u2028')
52
- .replaceAll('
', '\\u2029');
53
-
54
67
  const sha256 = (opts: { text: string }): string =>
55
68
  `'sha256-${createHash('sha256').update(opts.text).digest('base64')}'`;
56
69
 
57
- const table = (opts: { head: string[]; rows: string[][] }): string =>
58
- `<div class="tw"><table><thead><tr>${opts.head.map((cell) => `<th>${escaped(cell)}</th>`).join('')}</tr></thead><tbody>${opts.rows
59
- .map((row) => `<tr>${row.join('')}</tr>`)
60
- .join('')}</tbody></table></div>`;
70
+ /** The state each status of the spec reads as: a shape, a colour and a word. */
71
+ const BANNER_STATE: Record<string, string> = {
72
+ ok: 'done',
73
+ warn: 'waiting',
74
+ blocked: 'blocked',
75
+ info: 'info',
76
+ };
77
+
78
+ /**
79
+ * For each figure width, the rule that swaps the figure for its list: below the viewport width at which the figure would
80
+ * shrink under FIGURE_FIT of its natural size (text under 12 px). The 66 is the page and frame padding.
81
+ */
82
+ export const figureFitCss = (opts: { widths: Set<number> }): string =>
83
+ [...opts.widths]
84
+ .sort((a, b) => a - b)
85
+ .map((width) => {
86
+ const at = Math.ceil(width * FIGURE_FIT) + 66;
87
+
88
+ return `@media (max-width:${at}px){.fig.f${width}{display:none}.fig.f${width}~.path,.fig.f${width}~.path-detail{display:block}.fig.f${width}~.bar,.fig.f${width}~#detail,.fig.f${width}~.legend{display:none}}`;
89
+ })
90
+ .join('\n');
91
+
92
+ /** Counts of each minimap state, as tiles: how many tasks are done, in progress, waiting and blocked. */
93
+ const countTiles = (opts: {
94
+ spec: TVisualizeSpec;
95
+ chrome: TChrome;
96
+ }): { value: string; label: string; state: string }[] => {
97
+ const rows = opts.spec.minimap ?? [];
98
+ const count = (state: string): number => rows.filter((row) => row.status === state).length;
99
+
100
+ return [
101
+ {
102
+ value: `${count('done')} / ${rows.length}`,
103
+ label: stateWord({ chrome: opts.chrome, state: 'done' }),
104
+ state: 'done',
105
+ },
106
+ {
107
+ value: String(count('in progress')),
108
+ label: stateWord({ chrome: opts.chrome, state: 'in progress' }),
109
+ state: 'in progress',
110
+ },
111
+ {
112
+ value: String(count('waiting')),
113
+ label: stateWord({ chrome: opts.chrome, state: 'waiting' }),
114
+ state: 'waiting',
115
+ },
116
+ {
117
+ value: String(count('blocked')),
118
+ label: stateWord({ chrome: opts.chrome, state: 'blocked' }),
119
+ state: 'blocked',
120
+ },
121
+ ];
122
+ };
61
123
 
62
- const cell = (opts: { value: string; tag?: boolean }): string =>
63
- `<td${opts.tag === true ? ' class="tag"' : ''}>${escaped(opts.value)}</td>`;
124
+ const bannerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
125
+ const { spec, chrome } = opts;
126
+ const state = BANNER_STATE[spec.status.state] ?? 'info';
127
+ const word =
128
+ spec.status.label ??
129
+ chrome.statusStates[spec.status.state as keyof TChrome['statusStates']] ??
130
+ spec.status.state;
131
+ const meta = [
132
+ spec.asOf === undefined ? '' : `<span>${escaped(chrome.asOf)}: ${escaped(spec.asOf)}</span>`,
133
+ spec.scope === undefined ? '' : `<span>${escaped(chrome.scope)}: ${escaped(spec.scope)}</span>`,
134
+ ].join('');
64
135
 
65
- const sectionOf = (opts: { title: string; body: string }): string =>
66
- `<section><h2>${escaped(opts.title)}</h2>${opts.body}</section>`;
136
+ return `<header class="banner c-${NodeStates.toneOf(state)}" data-slide data-hero><div class="b-ic">${stateIcon({ state, size: 52 })}</div><div class="b-tx"><p class="meta">${meta}</p><p class="word">${escaped(word)}</p><h1>${escaped(spec.title)}</h1><p class="verdict">${escaped(spec.verdict)}</p>${spec.caption === undefined ? '' : `<p class="cap">${escaped(spec.caption)}</p>`}</div></header>`;
137
+ };
67
138
 
68
- const figureSection = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
69
- const { flow } = opts.spec;
139
+ const stepperHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
140
+ const { minimap } = opts.spec;
70
141
 
71
- if (flow === undefined) {
142
+ if (minimap === undefined) {
72
143
  return '';
73
144
  }
74
145
 
75
146
  const { chrome } = opts;
76
- const kinds = [...new Set(flow.nodes.map((node) => node.kind ?? 'step'))];
77
- const variants = [...new Set(flow.edges.map((edge) => edge.variant ?? 'main'))];
78
- const steps = flow.steps;
79
- const controls = [
80
- flow.edges.length > 0
81
- ? `<button id="play" type="button" aria-pressed="false" data-play="${escaped(chrome.play)}" data-pause="${escaped(chrome.pause)}">${escaped(chrome.play)}</button>`
82
- : '',
83
- steps.length > 0
84
- ? `<button id="prev" type="button">${escaped(chrome.previous)}</button><button id="next" type="button">${escaped(chrome.following)}</button><button id="all" type="button">${escaped(chrome.allSteps)}</button>`
85
- : '',
86
- ].join('');
87
147
 
88
- return sectionOf({
89
- title: chrome.flow,
90
- body: `<div class="bar">${controls}</div><div class="fig">${renderFigure({ flow })}</div><p id="detail" aria-live="polite">${escaped(chrome.detailHint)}</p>${
91
- steps.length > 0 ? `<p id="stepnote" aria-live="polite"></p>` : ''
92
- }<p class="legend"><span>${escaped(chrome.legend)}:</span>${kinds.map((kind) => `<span>${escaped(kind)}</span>`).join('')}${variants.map((variant) => `<span>${escaped(variant)}</span>`).join('')}</p>${
93
- steps.length > 0
94
- ? `<ol class="steps">${steps.map((step) => `<li><b>${escaped(step.title)}</b> - ${escaped(step.note)}</li>`).join('')}</ol><script type="application/json" id="steps">${jsonForScript({ value: steps })}</script>`
95
- : ''
96
- }`,
97
- });
148
+ return `<section class="sec" id="minimap" data-slide><h2 class="lab">${escaped(chrome.minimap)}</h2><ol class="strip">${minimap
149
+ .map(
150
+ (row) =>
151
+ `<li class="seg c-${NodeStates.toneOf(row.status)}"><span class="bar"></span><span class="nm">${chip({ chrome, state: row.status })}<span class="tn">${escaped(row.task)}</span></span>${row.note === undefined ? '' : `<span class="nt">${escaped(row.note)}</span>`}</li>`,
152
+ )
153
+ .join('')}</ol></section>`;
98
154
  };
99
155
 
100
- const beforeAfterSection = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
101
- const { beforeAfter } = opts.spec;
156
+ /** What the owner has to do and what blocks it: the first thing after the verdict. */
157
+ const ownerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
158
+ const { spec, chrome } = opts;
102
159
 
103
- if (beforeAfter === undefined) {
160
+ if (spec.strip === undefined) {
104
161
  return '';
105
162
  }
106
163
 
107
- const { chrome } = opts;
108
- const side = (given: {
109
- title: string;
110
- items: { text: string; change?: string }[];
111
- kind: 'added' | 'removed';
112
- }): string => {
113
- const { title, items, kind } = given;
114
-
115
- return `<section><h3>${escaped(title)}</h3><ul>${items
116
- .map((item) =>
117
- item.change === kind
118
- ? `<li class="${kind}">${escaped(item.text)} <small>(${escaped(kind === 'added' ? chrome.added : chrome.removed)})</small></li>`
119
- : `<li>${escaped(item.text)}</li>`,
120
- )
121
- .join('')}</ul></section>`;
122
- };
164
+ const jump =
165
+ spec.decisions === undefined
166
+ ? ''
167
+ : `<a class="jump" href="#decisions">${escaped(chrome.decisions)} (${spec.decisions.length})</a>`;
168
+ const actions =
169
+ spec.actions === undefined
170
+ ? ''
171
+ : `<ol class="check">${spec.actions.map((action) => `<li>${escaped(action)}</li>`).join('')}</ol>`;
123
172
 
124
- return sectionOf({
125
- title: `${chrome.before} / ${chrome.after}`,
126
- body: `<div class="ba">${side({ ...beforeAfter.before, kind: 'removed' })}${side({ ...beforeAfter.after, kind: 'added' })}</div>`,
127
- });
173
+ return `<section class="two" data-slide><div class="card action"><p class="lab">${escaped(chrome.next)}</p><h2>${escaped(spec.strip.next)}</h2>${actions}${jump}</div><div class="card blocked"><p class="lab">${escaped(chrome.blockedBy)}</p><p class="bb">${iconSvg({ name: 'waiting', size: 20 })}<span>${escaped(spec.strip.blockedBy)}</span></p><p class="ok-line">${iconSvg({ name: 'done', size: 16 })}<span><b>${escaped(chrome.healthy)}</b> ${escaped(spec.strip.healthy)}</span></p><p class="ok-line">${iconSvg({ name: 'info', size: 16 })}<span><b>${escaped(chrome.changed)}</b> ${escaped(spec.strip.changed)}</span></p></div></section>`;
128
174
  };
129
175
 
130
176
  /** The whole page: one file, no network, a content-security policy that allows only the page's own style and script by hash. */
131
177
  export const renderPage = (opts: { spec: TVisualizeSpec }): string => {
132
178
  const { spec } = opts;
133
179
  const chrome = chromeOf({ spec });
134
- const { state } = spec.status;
135
- const chip = `<span class="chip ${escaped(state)}"><i></i>${escaped(spec.status.label ?? wordOf({ words: chrome.statusStates, key: state }))}</span>`;
136
- const meta = [
137
- spec.asOf === undefined ? '' : `<span>${escaped(chrome.asOf)}: ${escaped(spec.asOf)}</span>`,
138
- spec.scope === undefined ? '' : `<span>${escaped(chrome.scope)}: ${escaped(spec.scope)}</span>`,
139
- ].join('');
140
- const strip =
141
- spec.strip === undefined
142
- ? ''
143
- : `<div class="strip"><div><b>${escaped(chrome.healthy)}</b>${escaped(spec.strip.healthy)}</div><div><b>${escaped(chrome.blockedBy)}</b>${escaped(spec.strip.blockedBy)}</div><div><b>${escaped(chrome.changed)}</b>${escaped(spec.strip.changed)}</div><div><b>${escaped(chrome.next)}</b>${escaped(spec.strip.next)}</div></div>`;
144
- const decisions =
145
- spec.decisions === undefined
146
- ? ''
147
- : sectionOf({
148
- title: chrome.decisions,
149
- body: `<ol class="d">${spec.decisions
150
- .map(
151
- (item) =>
152
- `<li>${escaped(item.question)}<br><b>${escaped(chrome.recommended)}:</b> ${escaped(item.recommended)}<br><small>${escaped(chrome.changesClaim)}: ${escaped(item.changes)}</small></li>`,
153
- )
154
- .join('')}</ol>`,
155
- });
156
- const evidence =
157
- spec.evidence === undefined
180
+ const ctx: ISectionContext = { spec, chrome, fits: new Set<number>() };
181
+ const state = BANNER_STATE[spec.status.state] ?? 'info';
182
+ const word =
183
+ spec.status.label ??
184
+ chrome.statusStates[spec.status.state as keyof TChrome['statusStates']] ??
185
+ spec.status.state;
186
+ const tiles =
187
+ spec.tiles ?? (spec.minimap === undefined ? undefined : countTiles({ spec, chrome }));
188
+ const body = [
189
+ bannerHtml({ spec, chrome }),
190
+ tiles === undefined
158
191
  ? ''
159
- : sectionOf({
160
- title: chrome.evidence,
161
- body: table({
162
- head: [chrome.claim, chrome.probe, chrome.result, chrome.label],
163
- rows: spec.evidence.map((row) => [
164
- cell({ value: row.claim }),
165
- cell({ value: row.probe }),
166
- cell({ value: row.result }),
167
- cell({
168
- value: wordOf({ words: chrome.evidenceLabels, key: row.label }),
169
- tag: true,
170
- }),
171
- ]),
172
- }),
173
- });
174
- const risks =
175
- spec.risks === undefined
176
- ? ''
177
- : sectionOf({
178
- title: chrome.risks,
179
- body: table({
180
- head: [chrome.risk, chrome.impact, chrome.fallback],
181
- rows: spec.risks.map((row) => [
182
- cell({ value: row.risk }),
183
- cell({ value: row.impact }),
184
- cell({ value: row.fallback }),
185
- ]),
186
- }),
187
- });
188
- const log =
189
- spec.log === undefined
190
- ? ''
191
- : sectionOf({
192
- title: chrome.log,
193
- body: table({
194
- head: ['', ''],
195
- rows: spec.log.map((row) => [
196
- cell({ value: row.date, tag: true }),
197
- cell({ value: row.text }),
198
- ]),
199
- }),
200
- });
201
- const links =
202
- spec.links === undefined
203
- ? ''
204
- : sectionOf({
205
- title: chrome.links,
206
- body: `<ul>${spec.links.map((link) => `<li><a href="${escaped(link.href)}" rel="noopener noreferrer">${escaped(link.label)}</a></li>`).join('')}</ul>`,
207
- });
208
- const policy = `default-src 'none'; style-src ${sha256({ text: PAGE_CSS })}; script-src ${sha256({ text: PAGE_JS })}; base-uri 'none'; form-action 'none'`;
192
+ : `<div data-slide class="slide-tiles">${tilesHtml({ tiles, chrome })}</div>`,
193
+ stepperHtml({ spec, chrome }),
194
+ ownerHtml({ spec, chrome }),
195
+ flowSection({ ctx }),
196
+ architectureSection({ ctx }),
197
+ comparisonSection({ ctx }),
198
+ ideaMapSection({ ctx }),
199
+ explainerSection({ ctx }),
200
+ timelineSection({ ctx }),
201
+ findingsSection({ ctx }),
202
+ beforeAfterSection({ ctx }),
203
+ decisionRecordSection({ ctx }),
204
+ decisionsSection({ ctx }),
205
+ evidenceSection({ ctx }),
206
+ risksSection({ ctx }),
207
+ logSection({ ctx }),
208
+ linksSection({ ctx }),
209
+ ].join('');
210
+ const css = `${PAGE_CSS}\n${figureFitCss({ widths: ctx.fits })}`;
211
+ const policy = `default-src 'none'; style-src ${sha256({ text: css })}; script-src ${sha256({ text: PAGE_JS })}; base-uri 'none'; form-action 'none'`;
212
+ const mini = `<div class="mini c-${NodeStates.toneOf(state)}" role="banner">${chip({ chrome, state, size: 18, label: word })}<b>${escaped(spec.title)}</b></div>`;
213
+ const tools = `<div class="tools"><button id="present" type="button" data-on="${escaped(chrome.present)}" data-off="${escaped(chrome.exitPresent)}">${escaped(chrome.present)}</button><button id="theme" type="button">${escaped(chrome.theme)}</button></div>`;
214
+ const deck = `<nav class="deck" aria-label="${escaped(chrome.slide)}"><button id="slide-prev" type="button">${escaped(chrome.previous)}</button><span id="slide-count" aria-live="polite"></span><button id="slide-next" type="button">${escaped(chrome.following)}</button></nav>`;
209
215
 
210
- return `<!doctype html><html lang="${escaped(spec.language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escaped(policy)}"><meta name="generator" content="vulcan visualize"><title>${escaped(spec.title)}</title><style>${PAGE_CSS}</style></head><body><main><header><div><h1>${escaped(spec.title)}</h1><p class="meta">${meta}</p></div>${chip}<button id="theme" type="button">${escaped(chrome.theme)}</button></header><p class="verdict">${escaped(spec.verdict)}</p>${spec.caption === undefined ? '' : `<p class="cap">${escaped(spec.caption)}</p>`}${figureSection({ spec, chrome })}${strip}${beforeAfterSection({ spec, chrome })}${decisions}${evidence}${risks}${log}${links}</main><script>${PAGE_JS}</script></body></html>`;
216
+ return `<!doctype html><html lang="${escaped(spec.language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escaped(policy)}"><meta name="generator" content="vulcan visualize"><title>${escaped(spec.title)}</title><style>${css}</style></head><body>${mini}<main class="wrap">${tools}${body}<footer>${escaped(chrome.footer)}</footer></main>${deck}<script>${PAGE_JS}</script></body></html>`;
211
217
  };
@@ -1,12 +1,16 @@
1
1
  import { z } from 'zod';
2
2
  import {
3
+ ChangeKinds,
3
4
  DEFAULT_CHROME,
4
5
  EdgeVariants,
5
6
  EvidenceLabels,
7
+ MinimapStates,
6
8
  NodeKinds,
9
+ NodeStates,
7
10
  StatusStates,
8
11
  VisualizeLimits,
9
12
  } from './constants.ts';
13
+ import type { TChangeKind } from './constants.ts';
10
14
 
11
15
  /** One line of plain text: no markup is interpreted anywhere, it is all escaped. */
12
16
  const text = (max: number) =>
@@ -35,6 +39,8 @@ const HTTPS = z
35
39
  const rows = <T extends z.ZodType>(item: T) =>
36
40
  z.array(item).min(1).max(VisualizeLimits.MAX_ROWS_PER_TABLE);
37
41
 
42
+ const STATE = choice({ set: NodeStates.SCHEME_SET });
43
+
38
44
  const NODE = z.strictObject({
39
45
  id: ID,
40
46
  label: text(VisualizeLimits.MAX_LABEL),
@@ -43,6 +49,7 @@ const NODE = z.strictObject({
43
49
  row: GRID,
44
50
  col: GRID,
45
51
  kind: choice({ set: NodeKinds.SCHEME_SET }).optional(),
52
+ state: STATE.optional(),
46
53
  });
47
54
 
48
55
  const EDGE = z.strictObject({
@@ -64,7 +71,7 @@ const STEP = z.strictObject({
64
71
  .default([]),
65
72
  });
66
73
 
67
- const SIDE = (changed: 'added' | 'removed') =>
74
+ const SIDE = (changed: TChangeKind) =>
68
75
  z.strictObject({
69
76
  title: text(VisualizeLimits.MAX_LABEL),
70
77
  items: rows(
@@ -75,6 +82,207 @@ const SIDE = (changed: 'added' | 'removed') =>
75
82
  ),
76
83
  });
77
84
 
85
+ const LIST = (max = VisualizeLimits.MAX_LIST) =>
86
+ z.array(text(VisualizeLimits.MAX_SENTENCE)).min(1).max(max);
87
+ const NUMBER = z.number().finite().min(-1_000_000_000).max(1_000_000_000);
88
+
89
+ const COMPARISON = z.strictObject({
90
+ criteria: z.array(text(VisualizeLimits.MAX_LABEL)).min(1).max(VisualizeLimits.MAX_CRITERIA),
91
+ options: z
92
+ .array(
93
+ z.strictObject({
94
+ name: text(VisualizeLimits.MAX_LABEL),
95
+ line: text(VisualizeLimits.MAX_SENTENCE).optional(),
96
+ /** One score from 1 to 5 per criterion, in the order of `criteria`. */
97
+ scores: z.array(z.number().int().min(1).max(5)).min(1).max(VisualizeLimits.MAX_CRITERIA),
98
+ pros: LIST().optional(),
99
+ cons: LIST().optional(),
100
+ recommended: z.boolean().optional(),
101
+ }),
102
+ )
103
+ .min(2)
104
+ .max(VisualizeLimits.MAX_COMPARE_OPTIONS),
105
+ note: text(VisualizeLimits.MAX_SENTENCE).optional(),
106
+ });
107
+
108
+ const IDEA_MAP = z.strictObject({
109
+ center: text(VisualizeLimits.MAX_LABEL),
110
+ branches: z
111
+ .array(
112
+ z.strictObject({
113
+ label: text(VisualizeLimits.MAX_LABEL),
114
+ items: z
115
+ .array(text(VisualizeLimits.MAX_LABEL))
116
+ .min(1)
117
+ .max(VisualizeLimits.MAX_BRANCH_ITEMS),
118
+ note: text(VisualizeLimits.MAX_SENTENCE).optional(),
119
+ }),
120
+ )
121
+ .min(2)
122
+ .max(VisualizeLimits.MAX_BRANCHES),
123
+ });
124
+
125
+ const DIAGRAM = z.discriminatedUnion('type', [
126
+ z.strictObject({
127
+ type: z.literal('row'),
128
+ nodes: z
129
+ .array(
130
+ z.strictObject({
131
+ label: text(VisualizeLimits.MAX_LABEL),
132
+ sub: text(VisualizeLimits.MAX_LABEL).optional(),
133
+ }),
134
+ )
135
+ .min(2)
136
+ .max(5),
137
+ /** Labels of the arrows between consecutive boxes; one fewer than the boxes. */
138
+ arrows: z.array(text(VisualizeLimits.MAX_EDGE_LABEL)).max(4).optional(),
139
+ }),
140
+ z.strictObject({
141
+ type: z.literal('layers'),
142
+ layers: z
143
+ .array(
144
+ z.strictObject({
145
+ label: text(VisualizeLimits.MAX_LABEL),
146
+ items: z.array(text(VisualizeLimits.MAX_LABEL)).min(1).max(5),
147
+ }),
148
+ )
149
+ .min(2)
150
+ .max(VisualizeLimits.MAX_LAYERS),
151
+ }),
152
+ ]);
153
+
154
+ const EXPLAINER = z.strictObject({
155
+ steps: z
156
+ .array(
157
+ z.strictObject({
158
+ title: text(VisualizeLimits.MAX_LABEL),
159
+ text: text(VisualizeLimits.MAX_SENTENCE),
160
+ diagram: DIAGRAM.optional(),
161
+ }),
162
+ )
163
+ .min(1)
164
+ .max(VisualizeLimits.MAX_EXPLAINER_STEPS),
165
+ });
166
+
167
+ const ARCHITECTURE = z.strictObject({
168
+ layers: z
169
+ .array(
170
+ z.strictObject({
171
+ label: text(VisualizeLimits.MAX_LABEL),
172
+ boxes: z
173
+ .array(
174
+ z.strictObject({
175
+ id: ID,
176
+ label: text(VisualizeLimits.MAX_LABEL),
177
+ sub: text(VisualizeLimits.MAX_LABEL).optional(),
178
+ state: STATE.optional(),
179
+ }),
180
+ )
181
+ .min(1)
182
+ .max(VisualizeLimits.MAX_LAYER_BOXES),
183
+ }),
184
+ )
185
+ .min(1)
186
+ .max(VisualizeLimits.MAX_LAYERS),
187
+ links: z
188
+ .array(
189
+ z.strictObject({ from: ID, to: ID, label: text(VisualizeLimits.MAX_EDGE_LABEL).optional() }),
190
+ )
191
+ .max(VisualizeLimits.MAX_LINKS)
192
+ .default([]),
193
+ });
194
+
195
+ const TIMELINE = z.strictObject({
196
+ items: z
197
+ .array(
198
+ z.strictObject({
199
+ date: text(VisualizeLimits.MAX_LABEL),
200
+ title: text(VisualizeLimits.MAX_LABEL),
201
+ text: text(VisualizeLimits.MAX_SENTENCE).optional(),
202
+ state: STATE.optional(),
203
+ }),
204
+ )
205
+ .min(2)
206
+ .max(VisualizeLimits.MAX_TIMELINE),
207
+ });
208
+
209
+ const CHART = z.discriminatedUnion('type', [
210
+ z.strictObject({
211
+ type: z.literal('bar'),
212
+ title: text(VisualizeLimits.MAX_LABEL),
213
+ unit: text(16).optional(),
214
+ labels: z.array(text(VisualizeLimits.MAX_LABEL)).min(2).max(VisualizeLimits.MAX_POINTS),
215
+ /** One value per label, from zero up: a bar starts at the baseline. */
216
+ values: z.array(NUMBER.min(0)).min(2).max(VisualizeLimits.MAX_POINTS),
217
+ }),
218
+ z.strictObject({
219
+ type: z.literal('line'),
220
+ title: text(VisualizeLimits.MAX_LABEL),
221
+ unit: text(16).optional(),
222
+ labels: z.array(text(VisualizeLimits.MAX_LABEL)).min(3).max(VisualizeLimits.MAX_POINTS),
223
+ series: z
224
+ .array(
225
+ z.strictObject({
226
+ name: text(VisualizeLimits.MAX_LABEL),
227
+ values: z.array(NUMBER).min(3).max(VisualizeLimits.MAX_POINTS),
228
+ }),
229
+ )
230
+ .min(1)
231
+ .max(VisualizeLimits.MAX_SERIES),
232
+ }),
233
+ z.strictObject({
234
+ type: z.literal('donut'),
235
+ title: text(VisualizeLimits.MAX_LABEL),
236
+ unit: text(16).optional(),
237
+ parts: z
238
+ .array(
239
+ z.strictObject({
240
+ label: text(VisualizeLimits.MAX_LABEL),
241
+ value: NUMBER.min(0),
242
+ state: STATE.optional(),
243
+ }),
244
+ )
245
+ .min(2)
246
+ .max(VisualizeLimits.MAX_PARTS),
247
+ }),
248
+ ]);
249
+
250
+ const FINDINGS = z.strictObject({
251
+ numbers: z
252
+ .array(
253
+ z.strictObject({
254
+ value: text(16),
255
+ label: text(VisualizeLimits.MAX_LABEL),
256
+ state: STATE.optional(),
257
+ }),
258
+ )
259
+ .min(1)
260
+ .max(VisualizeLimits.MAX_TILES)
261
+ .optional(),
262
+ charts: z.array(CHART).min(1).max(VisualizeLimits.MAX_CHARTS).optional(),
263
+ callouts: z
264
+ .array(z.strictObject({ text: text(VisualizeLimits.MAX_SENTENCE), state: STATE.optional() }))
265
+ .min(1)
266
+ .max(4)
267
+ .optional(),
268
+ });
269
+
270
+ const DECISION_RECORD = z.strictObject({
271
+ context: text(VisualizeLimits.MAX_SENTENCE),
272
+ options: z
273
+ .array(
274
+ z.strictObject({
275
+ name: text(VisualizeLimits.MAX_LABEL),
276
+ summary: text(VisualizeLimits.MAX_SENTENCE),
277
+ chosen: z.boolean().optional(),
278
+ }),
279
+ )
280
+ .min(2)
281
+ .max(5),
282
+ decision: text(VisualizeLimits.MAX_SENTENCE),
283
+ consequences: LIST(),
284
+ });
285
+
78
286
  /** The words of the page, English by default; any of them may be replaced (the owner's language). */
79
287
  const CHROME = z
80
288
  .strictObject({
@@ -91,6 +299,17 @@ const CHROME = z
91
299
  info: text(VisualizeLimits.MAX_LABEL).optional(),
92
300
  })
93
301
  .optional(),
302
+ minimapStates: z
303
+ .strictObject({
304
+ done: text(VisualizeLimits.MAX_LABEL).optional(),
305
+ 'in-progress': text(VisualizeLimits.MAX_LABEL).optional(),
306
+ waiting: text(VisualizeLimits.MAX_LABEL).optional(),
307
+ 'not-started': text(VisualizeLimits.MAX_LABEL).optional(),
308
+ blocked: text(VisualizeLimits.MAX_LABEL).optional(),
309
+ dropped: text(VisualizeLimits.MAX_LABEL).optional(),
310
+ info: text(VisualizeLimits.MAX_LABEL).optional(),
311
+ })
312
+ .optional(),
94
313
  evidenceLabels: z
95
314
  .strictObject({
96
315
  verified: text(VisualizeLimits.MAX_LABEL).optional(),
@@ -130,6 +349,28 @@ export const VISUALIZE_SCHEMA = z.strictObject({
130
349
  next: text(VisualizeLimits.MAX_SENTENCE),
131
350
  })
132
351
  .optional(),
352
+ /** Where each task stands, one row each: the owner's map of the work. */
353
+ minimap: rows(
354
+ z.strictObject({
355
+ task: text(VisualizeLimits.MAX_LABEL),
356
+ status: choice({ set: MinimapStates.SCHEME_SET }),
357
+ note: text(VisualizeLimits.MAX_SENTENCE).optional(),
358
+ }),
359
+ ).optional(),
360
+ /** What the owner has to do, in order: shown as a numbered checklist under `strip.next`. */
361
+ actions: LIST().optional(),
362
+ /** Key numbers; with a `minimap` and no tiles, the page counts the states itself. */
363
+ tiles: z
364
+ .array(
365
+ z.strictObject({
366
+ value: text(16),
367
+ label: text(VisualizeLimits.MAX_LABEL),
368
+ state: STATE.optional(),
369
+ }),
370
+ )
371
+ .min(1)
372
+ .max(VisualizeLimits.MAX_TILES)
373
+ .optional(),
133
374
  flow: z
134
375
  .strictObject({
135
376
  nodes: z.array(NODE).min(1).max(VisualizeLimits.MAX_NODES),
@@ -137,7 +378,16 @@ export const VISUALIZE_SCHEMA = z.strictObject({
137
378
  steps: z.array(STEP).max(VisualizeLimits.MAX_STEPS).default([]),
138
379
  })
139
380
  .optional(),
140
- beforeAfter: z.strictObject({ before: SIDE('removed'), after: SIDE('added') }).optional(),
381
+ architecture: ARCHITECTURE.optional(),
382
+ comparison: COMPARISON.optional(),
383
+ ideaMap: IDEA_MAP.optional(),
384
+ explainer: EXPLAINER.optional(),
385
+ timeline: TIMELINE.optional(),
386
+ findings: FINDINGS.optional(),
387
+ decisionRecord: DECISION_RECORD.optional(),
388
+ beforeAfter: z
389
+ .strictObject({ before: SIDE(ChangeKinds.REMOVED), after: SIDE(ChangeKinds.ADDED) })
390
+ .optional(),
141
391
  decisions: z
142
392
  .array(
143
393
  z.strictObject({