@venizia/vulcan 0.4.9-0 → 0.4.9-2

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 (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -3,15 +3,15 @@ import { lstatSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs
3
3
  import { basename, join } from 'node:path';
4
4
  import { z } from 'zod';
5
5
  import { ProjectLayout } from '../common/index.ts';
6
- import { localRootOf } from '../local/index.ts';
6
+ import { LocalScan } from '../local/index.ts';
7
7
  import { VisualizeLimits } from './constants.ts';
8
8
  import { PageGate } from './gate.ts';
9
- import { renderPage } from './page.ts';
9
+ import { PageShell } from './page.ts';
10
10
  import { VISUALIZE_SCHEMA } from './schema.ts';
11
11
  import { PageTerms } from './sources.ts';
12
12
  import { ProjectTheme } from './theme.ts';
13
13
  import type { IThemeInput } from './theme.ts';
14
- import { checkSpec } from './validate.ts';
14
+ import { SpecValidation } from './validate.ts';
15
15
 
16
16
  /** What the page takes from the project it is made in: the owner's language and the project's colour. */
17
17
  export interface IRenderContext {
@@ -39,164 +39,167 @@ 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
- /** Spec text to a page: parse, validate, cross-check, render, size gate. Nothing is written here. */
43
- export const renderSpecText = (opts: { text: string; context?: IRenderContext }): TRenderResult => {
44
- let payload: unknown;
42
+ export class SpecPage {
43
+ /** Spec text to a page: parse, validate, cross-check, render, size gate. Nothing is written here. */
44
+ static renderText(opts: { text: string; context?: IRenderContext }): TRenderResult {
45
+ let payload: unknown;
45
46
 
46
- try {
47
- payload = JSON.parse(opts.text);
48
- } catch (error) {
49
- return {
50
- ok: false,
51
- problems: [
52
- `the spec is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
53
- ],
54
- };
55
- }
47
+ try {
48
+ payload = JSON.parse(opts.text);
49
+ } catch (error) {
50
+ return {
51
+ ok: false,
52
+ problems: [
53
+ `the spec is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
54
+ ],
55
+ };
56
+ }
56
57
 
57
- const parsed = VISUALIZE_SCHEMA.safeParse(payload);
58
+ const parsed = VISUALIZE_SCHEMA.safeParse(payload);
58
59
 
59
- if (!parsed.success) {
60
- return {
61
- ok: false,
62
- problems: parsed.error.issues.map(
63
- (issue) => `${issue.path.join('.') || 'spec'}: ${issue.message}`,
64
- ),
65
- };
66
- }
67
-
68
- const problems = checkSpec({ spec: parsed.data });
60
+ if (!parsed.success) {
61
+ return {
62
+ ok: false,
63
+ problems: parsed.error.issues.map(
64
+ (issue) => `${issue.path.join('.') || 'spec'}: ${issue.message}`,
65
+ ),
66
+ };
67
+ }
69
68
 
70
- if (problems.length > 0) {
71
- return { ok: false, problems };
72
- }
69
+ const problems = SpecValidation.check({ spec: parsed.data });
73
70
 
74
- const { accent, accentDark, accentText } = parsed.data;
75
- const themed = ProjectTheme.resolve({
76
- spec:
77
- accent === undefined
78
- ? undefined
79
- : {
80
- accent,
81
- ...(accentDark === undefined ? {} : { accentDark }),
82
- ...(accentText === undefined ? {} : { accentText }),
83
- },
84
- project: opts.context?.project,
85
- });
86
-
87
- if (!themed.ok) {
88
- return { ok: false, problems: themed.problems.map((problem) => `colour: ${problem}`) };
89
- }
71
+ if (problems.length > 0) {
72
+ return { ok: false, problems };
73
+ }
90
74
 
91
- const language = parsed.data.language ?? opts.context?.language ?? 'en';
92
- const html = renderPage({ spec: parsed.data, language, theme: themed.theme });
93
- const bytes = Buffer.byteLength(html, 'utf8');
94
- const gate = PageGate.problems({ html });
75
+ const { accent, accentDark, accentText } = parsed.data;
76
+ const themed = ProjectTheme.resolve({
77
+ spec:
78
+ accent === undefined
79
+ ? undefined
80
+ : {
81
+ accent,
82
+ ...(accentDark === undefined ? {} : { accentDark }),
83
+ ...(accentText === undefined ? {} : { accentText }),
84
+ },
85
+ project: opts.context?.project,
86
+ });
87
+
88
+ if (!themed.ok) {
89
+ return { ok: false, problems: themed.problems.map((problem) => `colour: ${problem}`) };
90
+ }
95
91
 
96
- if (gate.length > 0) {
97
- return { ok: false, problems: gate.map((problem) => `output gate: ${problem}`) };
98
- }
92
+ const language = parsed.data.language ?? opts.context?.language ?? 'en';
93
+ const html = PageShell.render({ spec: parsed.data, language, theme: themed.theme });
94
+ const bytes = Buffer.byteLength(html, 'utf8');
95
+ const gate = PageGate.problems({ html });
99
96
 
100
- if (bytes > VisualizeLimits.FAIL_BYTES) {
101
- return {
102
- ok: false,
103
- problems: [
104
- `the page is ${Math.round(bytes / 1024)} KB; the limit is ${VisualizeLimits.FAIL_BYTES / 1024} KB - a handoff that does not fit is two pages, not one dense page`,
105
- ],
106
- };
107
- }
97
+ if (gate.length > 0) {
98
+ return { ok: false, problems: gate.map((problem) => `output gate: ${problem}`) };
99
+ }
108
100
 
109
- return {
110
- ok: true,
111
- page: {
112
- html,
113
- bytes,
114
- checks: [
115
- ...CHECKS,
116
- PageGate.CHECK,
117
- `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`,
118
- ...themed.theme.notes,
119
- `size ${(bytes / 1024).toFixed(1)} KB, within ${VisualizeLimits.FAIL_BYTES / 1024} KB`,
120
- ],
121
- warnings: [
122
- ...themed.theme.warnings,
123
- ...PageTerms.warnings({ html, terms: parsed.data.terms }),
124
- ...(bytes > VisualizeLimits.WARN_BYTES
125
- ? [
126
- `the page is ${Math.round(bytes / 1024)} KB, past the ${VisualizeLimits.WARN_BYTES / 1024} KB a page should stay under: consider two pages`,
127
- ]
128
- : []),
129
- ],
130
- },
131
- };
132
- };
133
-
134
- /** The spec's JSON Schema, for an agent that wants to check a spec before it runs the renderer. */
135
- export const specSchemaText = (): string =>
136
- `${JSON.stringify(z.toJSONSchema(VISUALIZE_SCHEMA, { io: 'input' }), null, 2)}\n`;
137
-
138
- /** A page name as a file name: lowercase letters, digits and dashes. */
139
- export const pageNameOf = (opts: { name: string }): string | undefined => {
140
- const base = basename(opts.name).replace(/\.[^.]*$/, '');
141
- const cleaned = base
142
- .toLowerCase()
143
- .replace(/[^a-z0-9-]+/g, '-')
144
- .slice(0, 64)
145
- .replace(/^-+|-+$/g, '');
146
-
147
- return cleaned === '' ? undefined : cleaned;
148
- };
149
-
150
- /**
151
- * Writes the page to `.agents/local/prototypes/<name>.html` of the project: beside its place and moved in
152
- * last, so a failed render never replaces the last good page. Only a trusted `.agents/local/` is used.
153
- */
154
- export const writePage = (opts: {
155
- root: string;
156
- name: string;
157
- html: string;
158
- }): { ok: true; path: string } | { ok: false; error: string } => {
159
- const local = localRootOf({ root: opts.root });
101
+ if (bytes > VisualizeLimits.FAIL_BYTES) {
102
+ return {
103
+ ok: false,
104
+ problems: [
105
+ `the page is ${Math.round(bytes / 1024)} KB; the limit is ${VisualizeLimits.FAIL_BYTES / 1024} KB - a handoff that does not fit is two pages, not one dense page`,
106
+ ],
107
+ };
108
+ }
160
109
 
161
- if (local === undefined) {
162
110
  return {
163
- ok: false,
164
- error: `no .agents/local/ in ${opts.root} (or it is a symlink, or resolves outside the project) - run vulcan sync first`,
111
+ ok: true,
112
+ page: {
113
+ html,
114
+ bytes,
115
+ checks: [
116
+ ...CHECKS,
117
+ 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
+ ...themed.theme.notes,
120
+ `size ${(bytes / 1024).toFixed(1)} KB, within ${VisualizeLimits.FAIL_BYTES / 1024} KB`,
121
+ ],
122
+ warnings: [
123
+ ...themed.theme.warnings,
124
+ ...PageTerms.warnings({ html, terms: parsed.data.terms }),
125
+ ...(bytes > VisualizeLimits.WARN_BYTES
126
+ ? [
127
+ `the page is ${Math.round(bytes / 1024)} KB, past the ${VisualizeLimits.WARN_BYTES / 1024} KB a page should stay under: consider two pages`,
128
+ ]
129
+ : []),
130
+ ],
131
+ },
165
132
  };
166
133
  }
167
134
 
168
- const directory = join(local, VisualizeLimits.OUTPUT_DIRECTORY);
135
+ /** The spec's JSON Schema, for an agent that wants to check a spec before it runs the renderer. */
136
+ static specSchemaText(): string {
137
+ return `${JSON.stringify(z.toJSONSchema(VISUALIZE_SCHEMA, { io: 'input' }), null, 2)}\n`;
138
+ }
169
139
 
170
- const refusal = (error: string) => ({ ok: false as const, error });
171
- const place = `${ProjectLayout.LOCAL_DIRECTORY}/${VisualizeLimits.OUTPUT_DIRECTORY}`;
140
+ /** A page name as a file name: lowercase letters, digits and dashes. */
141
+ static pageNameOf(opts: { name: string }): string | undefined {
142
+ const base = basename(opts.name).replace(/\.[^.]*$/, '');
143
+ const cleaned = base
144
+ .toLowerCase()
145
+ .replace(/[^a-z0-9-]+/g, '-')
146
+ .slice(0, 64)
147
+ .replace(/^-+|-+$/g, '');
172
148
 
173
- try {
174
- const kind = lstatSync(directory, { throwIfNoEntry: false });
149
+ return cleaned === '' ? undefined : cleaned;
150
+ }
175
151
 
176
- if (kind?.isSymbolicLink()) {
177
- return refusal(`${place} is a symlink - refusing to write through it`);
152
+ /**
153
+ * Writes the page to `.agents/local/prototypes/<name>.html` of the project: beside its place and moved in
154
+ * last, so a failed render never replaces the last good page. Only a trusted `.agents/local/` is used.
155
+ */
156
+ static write(opts: {
157
+ root: string;
158
+ name: string;
159
+ html: string;
160
+ }): { ok: true; path: string } | { ok: false; error: string } {
161
+ const local = LocalScan.localRootOf({ root: opts.root });
162
+
163
+ if (local === undefined) {
164
+ return {
165
+ ok: false,
166
+ error: `no .agents/local/ in ${opts.root} (or it is a symlink, or resolves outside the project) - run vulcan sync first`,
167
+ };
178
168
  }
179
169
 
180
- if (kind === undefined) {
181
- mkdirSync(directory, { recursive: true });
182
- } else if (!kind.isDirectory()) {
183
- return refusal(`${place} is not a folder`);
184
- }
170
+ const directory = join(local, VisualizeLimits.OUTPUT_DIRECTORY);
185
171
 
186
- const path = join(directory, `${opts.name}.html`);
187
- const partial = `${path}.${randomBytes(6).toString('hex')}.partial`;
172
+ const refusal = (error: string) => ({ ok: false as const, error });
173
+ const place = `${ProjectLayout.LOCAL_DIRECTORY}/${VisualizeLimits.OUTPUT_DIRECTORY}`;
188
174
 
189
175
  try {
190
- writeFileSync(partial, opts.html, { flag: 'wx' });
191
- renameSync(partial, path);
192
- } finally {
193
- rmSync(partial, { force: true });
176
+ const kind = lstatSync(directory, { throwIfNoEntry: false });
177
+
178
+ if (kind?.isSymbolicLink()) {
179
+ return refusal(`${place} is a symlink - refusing to write through it`);
180
+ }
181
+
182
+ if (kind === undefined) {
183
+ mkdirSync(directory, { recursive: true });
184
+ } else if (!kind.isDirectory()) {
185
+ return refusal(`${place} is not a folder`);
186
+ }
187
+
188
+ const path = join(directory, `${opts.name}.html`);
189
+ const partial = `${path}.${randomBytes(6).toString('hex')}.partial`;
190
+
191
+ try {
192
+ writeFileSync(partial, opts.html, { flag: 'wx' });
193
+ renameSync(partial, path);
194
+ } finally {
195
+ rmSync(partial, { force: true });
196
+ }
197
+
198
+ return { ok: true, path };
199
+ } catch (error) {
200
+ return refusal(
201
+ `could not write the page: ${error instanceof Error ? error.message : String(error)}`,
202
+ );
194
203
  }
195
-
196
- return { ok: true, path };
197
- } catch (error) {
198
- return refusal(
199
- `could not write the page: ${error instanceof Error ? error.message : String(error)}`,
200
- );
201
204
  }
202
- };
205
+ }