@venizia/vulcan 0.4.8 → 0.4.9-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -0,0 +1,270 @@
1
+ import { z } from 'zod';
2
+ import type { TChrome } from './constants.ts';
3
+ import { FigureLayout } from './layout.ts';
4
+ import type { TVisualizeSpec } from './schema.ts';
5
+
6
+ /** One line of plain text: no markup is interpreted anywhere, it is all escaped. */
7
+ const text = (max: number) =>
8
+ z
9
+ .string()
10
+ .max(max)
11
+ .regex(/^(?=.*\S)[^\p{Cc}‪-‮⁦-⁩]+$/u, 'one line of text, not blank');
12
+
13
+ /** The limits of the sources and the terms. */
14
+ export class SourceLimits {
15
+ static readonly COMMIT_LENGTH = 40;
16
+ static readonly MAX_TERMS = 12;
17
+ static readonly MAX_TERM = 40;
18
+ static readonly MAX_MEANING = 200;
19
+ }
20
+
21
+ /**
22
+ * Where a claim comes from: a repository, the commit it was read at, a path in it and, when it helps, the lines. The shape
23
+ * is checked by `SourceRefs.check` (a commit is 40 lowercase hex characters, a path is relative), so the refusal says why.
24
+ */
25
+ export const SOURCE_SCHEMA = z.strictObject({
26
+ repo: text(100).describe('the repository, like owner/name'),
27
+ commit: text(64).describe('the full commit: exactly 40 lowercase hex characters'),
28
+ path: text(200).describe('a path inside the repository: relative, without ..'),
29
+ lines: text(16).optional().describe('12 or 12-30, the start not after the end'),
30
+ });
31
+
32
+ /** The words of the page that a reader may not know, each with what it means here. */
33
+ export const TERMS_SCHEMA = z
34
+ .array(
35
+ z.strictObject({
36
+ term: text(SourceLimits.MAX_TERM),
37
+ meaning: text(SourceLimits.MAX_MEANING),
38
+ }),
39
+ )
40
+ .min(1)
41
+ .max(SourceLimits.MAX_TERMS);
42
+
43
+ export type TSource = z.output<typeof SOURCE_SCHEMA>;
44
+ export type TTerms = z.output<typeof TERMS_SCHEMA>;
45
+
46
+ /** A source and every place on the page that points at it. */
47
+ export interface ISourceEntry {
48
+ text: string;
49
+ by: string[];
50
+ }
51
+
52
+ /** What holds a source: a box of the flow, a step of the flow, a box of the compare view. */
53
+ type TSourceHolder = 'flow' | 'step' | 'compare';
54
+
55
+ interface ISourceUse {
56
+ place: string;
57
+ holder: TSourceHolder;
58
+ label: string;
59
+ source: TSource;
60
+ }
61
+
62
+ const escaped = (value: string): string => FigureLayout.escapeText({ value });
63
+
64
+ const REPO = /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
65
+ const COMMIT = /^[0-9a-f]{40}$/;
66
+ const LINES = /^([1-9]\d{0,6})(?:-([1-9]\d{0,6}))?$/;
67
+
68
+ /** Sources: how one is written, checked and listed. */
69
+ export class SourceRefs {
70
+ /** `repo@commit:path:lines`, the commit in full. */
71
+ static textOf(opts: { source: TSource }): string {
72
+ const { repo, commit, path, lines } = opts.source;
73
+
74
+ return `${repo}@${commit}:${path}${lines === undefined ? '' : `:${lines}`}`;
75
+ }
76
+
77
+ /** A line of text with the source after it. */
78
+ static withSource(opts: { text: string | undefined; source: TSource }): string {
79
+ const source = SourceRefs.textOf({ source: opts.source });
80
+
81
+ return opts.text === undefined ? source : `${opts.text} ${source}`;
82
+ }
83
+
84
+ /** The source as markup: its text in a code element, escaped like every other text. */
85
+ static html(opts: { source: TSource }): string {
86
+ return `<code class="src">${escaped(SourceRefs.textOf({ source: opts.source }))}</code>`;
87
+ }
88
+
89
+ /** What is wrong with one source, in words, or nothing. */
90
+ static problemsOf(opts: { place: string; source: TSource }): string[] {
91
+ const { place, source } = opts;
92
+ const problems: string[] = [];
93
+
94
+ if (!REPO.test(source.repo)) {
95
+ problems.push(
96
+ `${place}: repo '${source.repo}' is not owner/name (letters, digits, . _ - and /)`,
97
+ );
98
+ }
99
+
100
+ if (!COMMIT.test(source.commit)) {
101
+ problems.push(
102
+ `${place}: commit '${source.commit}' is not exactly ${SourceLimits.COMMIT_LENGTH} lowercase hex characters - give the full commit, not a short one or a branch`,
103
+ );
104
+ }
105
+
106
+ if (/^([\\/]|[A-Za-z]:)/.test(source.path)) {
107
+ problems.push(
108
+ `${place}: path '${source.path}' is absolute - give it from the repository root`,
109
+ );
110
+ }
111
+
112
+ if (source.path.includes('..')) {
113
+ problems.push(`${place}: path '${source.path}' contains '..'`);
114
+ }
115
+
116
+ // A path is a path in the repository, not an address, a home folder or an escaped path.
117
+ if (/^~|:\/\/|%|[․‥….]/.test(source.path)) {
118
+ problems.push(
119
+ `${place}: path '${source.path}' is not a plain path inside the repository (no address, no ~, no % escapes)`,
120
+ );
121
+ }
122
+
123
+ if (source.lines !== undefined) {
124
+ const found = LINES.exec(source.lines);
125
+
126
+ if (found === null) {
127
+ problems.push(`${place}: lines '${source.lines}' is not 12 or 12-30`);
128
+ } else if (Number(found[1]) > Number(found[2] ?? found[1])) {
129
+ problems.push(`${place}: lines '${source.lines}' starts after it ends`);
130
+ }
131
+ }
132
+
133
+ return problems;
134
+ }
135
+
136
+ /** Every source of the page with the place that holds it, in the order the page shows them. */
137
+ private static uses(opts: { spec: TVisualizeSpec }): ISourceUse[] {
138
+ const { flow, compare } = opts.spec;
139
+ const found: ISourceUse[] = [];
140
+
141
+ for (const [index, node] of (flow?.nodes ?? []).entries()) {
142
+ if (node.source !== undefined) {
143
+ found.push({
144
+ place: `flow.nodes[${index}].source`,
145
+ holder: 'flow',
146
+ label: node.label,
147
+ source: node.source,
148
+ });
149
+ }
150
+ }
151
+
152
+ for (const [index, step] of (flow?.steps ?? []).entries()) {
153
+ if (step.source !== undefined) {
154
+ found.push({
155
+ place: `flow.steps[${index}].source`,
156
+ holder: 'step',
157
+ label: step.title,
158
+ source: step.source,
159
+ });
160
+ }
161
+ }
162
+
163
+ for (const [index, node] of (compare?.nodes ?? []).entries()) {
164
+ if (node.source !== undefined) {
165
+ found.push({
166
+ place: `compare.nodes[${index}].source`,
167
+ holder: 'compare',
168
+ label: node.label,
169
+ source: node.source,
170
+ });
171
+ }
172
+ }
173
+
174
+ return found;
175
+ }
176
+
177
+ /** What a schema cannot say about the sources and the terms. */
178
+ static check(opts: { spec: TVisualizeSpec }): string[] {
179
+ const problems = SourceRefs.uses(opts).flatMap((use) =>
180
+ SourceRefs.problemsOf({ place: use.place, source: use.source }),
181
+ );
182
+ const seen = new Set<string>();
183
+
184
+ for (const item of opts.spec.terms ?? []) {
185
+ const key = item.term.toLowerCase();
186
+
187
+ if (seen.has(key)) {
188
+ problems.push(`terms: '${item.term}' is listed twice`);
189
+ }
190
+
191
+ seen.add(key);
192
+ }
193
+
194
+ return problems;
195
+ }
196
+
197
+ /** Each distinct source once, in order of appearance, with what points at it. */
198
+ static entries(opts: { spec: TVisualizeSpec; chrome: TChrome }): ISourceEntry[] {
199
+ const { chrome } = opts;
200
+ const word: Record<TSourceHolder, string> = {
201
+ flow: chrome.flow,
202
+ step: chrome.step,
203
+ compare: chrome.compareView,
204
+ };
205
+ const byText = new Map<string, ISourceEntry>();
206
+
207
+ for (const use of SourceRefs.uses(opts)) {
208
+ const key = SourceRefs.textOf({ source: use.source });
209
+ const entry = byText.get(key) ?? { text: key, by: [] };
210
+ const by = `${word[use.holder]}: ${use.label}`;
211
+
212
+ if (!entry.by.includes(by)) {
213
+ entry.by.push(by);
214
+ }
215
+
216
+ byText.set(key, entry);
217
+ }
218
+
219
+ return [...byText.values()];
220
+ }
221
+
222
+ /** The body of the `sources` part: a list, each source once with what points at it. */
223
+ static listHtml(opts: { entries: ISourceEntry[] }): string {
224
+ return `<ol class="srcs">${opts.entries
225
+ .map(
226
+ (entry) =>
227
+ `<li><code class="src">${escaped(entry.text)}</code><span class="by">${entry.by.map(escaped).join(', ')}</span></li>`,
228
+ )
229
+ .join('')}</ol>`;
230
+ }
231
+ }
232
+
233
+ /** The terms of the page: shown as a definition list, and each one must show up in the page's other text. */
234
+ export class PageTerms {
235
+ /** The body of the `terms` part: a definition list. */
236
+ static listHtml(opts: { terms: TTerms }): string {
237
+ return `<dl class="terms">${opts.terms
238
+ .map((item) => `<div><dt>${escaped(item.term)}</dt><dd>${escaped(item.meaning)}</dd></div>`)
239
+ .join('')}</dl>`;
240
+ }
241
+
242
+ /** The text of a page: what is in the body, without scripts, styles, markup, and without the terms part itself. */
243
+ static textOf(opts: { html: string }): string {
244
+ const body = opts.html.slice(opts.html.indexOf('<body>'));
245
+
246
+ return body
247
+ .replace(/<section class="part" id="terms"[\s\S]*?<\/section>/, ' ')
248
+ .replace(/<(script|style)[\s\S]*?<\/\1>/g, ' ')
249
+ .replace(/<[^>]*>/g, ' ')
250
+ .replaceAll('&lt;', '<')
251
+ .replaceAll('&gt;', '>')
252
+ .replaceAll('&quot;', '"')
253
+ .replaceAll('&#39;', "'")
254
+ .replaceAll('&amp;', '&')
255
+ .toLowerCase();
256
+ }
257
+
258
+ /** A warning for each term the rest of the page never uses: a word nobody meets needs no definition. */
259
+ static warnings(opts: { html: string; terms: TTerms | undefined }): string[] {
260
+ if (opts.terms === undefined) {
261
+ return [];
262
+ }
263
+
264
+ const page = PageTerms.textOf({ html: opts.html });
265
+
266
+ return opts.terms
267
+ .filter((item) => !page.includes(item.term.toLowerCase()))
268
+ .map((item) => `terms: '${item.term}' never appears in the page text`);
269
+ }
270
+ }