@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
@@ -1,9 +1,9 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import { ExitCodes, PACKAGE_NAME, readProperty, UpgradeFlags } from '../common/index.ts';
3
+ import { ExitCodes, JsonValue, PACKAGE_NAME, UpgradeFlags } from '../common/index.ts';
4
4
  import type { ICommandContext } from '../common/index.ts';
5
5
  import { CreateConstants } from '../create/common/index.ts';
6
- import { bunExecutable, isInstallSkipped, runBun } from '../create/process.ts';
6
+ import { SubProcess } from '../create/process.ts';
7
7
 
8
8
  /** `latest` is the stable channel: never a prerelease. */
9
9
  const DEFAULT_TARGET = 'latest';
@@ -13,16 +13,9 @@ interface IDistTags {
13
13
  next?: string;
14
14
  }
15
15
 
16
- export const buildUpgradeArgs = (opts: { target?: string }): string[] => [
17
- 'add',
18
- '--dev',
19
- '--exact',
20
- `${PACKAGE_NAME}@${opts.target ?? DEFAULT_TARGET}`,
21
- ];
22
-
23
16
  /** A tag that is present must be a plain version; anything else cannot be compared or installed. */
24
17
  const parseTag = (opts: { tags: unknown; key: keyof IDistTags }): string | undefined | null => {
25
- const value = readProperty({ value: opts.tags, key: opts.key });
18
+ const value = JsonValue.readProperty({ value: opts.tags, key: opts.key });
26
19
 
27
20
  if (value === undefined) {
28
21
  return undefined;
@@ -32,7 +25,7 @@ const parseTag = (opts: { tags: unknown; key: keyof IDistTags }): string | undef
32
25
  };
33
26
 
34
27
  /** The `latest` and `next` tags of a registry answer, or undefined when it is not an object of versions. */
35
- export const parseDistTags = (opts: { text: string }): IDistTags | undefined => {
28
+ const parseDistTags = (opts: { text: string }): IDistTags | undefined => {
36
29
  let parsed: unknown;
37
30
 
38
31
  try {
@@ -56,24 +49,29 @@ export const parseDistTags = (opts: { text: string }): IDistTags | undefined =>
56
49
  * auth settings. `VULCAN_DIST_TAGS` replaces it so tests run offline. Undefined when the read fails,
57
50
  * after printing why bun failed.
58
51
  */
59
- export const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | undefined> => {
52
+ const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | undefined> => {
60
53
  const injected = process.env[UpgradeFlags.DIST_TAGS_ENV];
61
54
 
62
55
  if (injected !== undefined) {
63
56
  return parseDistTags({ text: injected });
64
57
  }
65
58
 
66
- const child = Bun.spawn([bunExecutable(), 'pm', 'view', PACKAGE_NAME, 'dist-tags', '--json'], {
67
- cwd: opts.cwd,
68
- stdout: 'pipe',
69
- stderr: 'pipe',
70
- });
59
+ const child = Bun.spawn(
60
+ [SubProcess.bunExecutable(), 'pm', 'view', PACKAGE_NAME, 'dist-tags', '--json'],
61
+ {
62
+ cwd: opts.cwd,
63
+ stdout: 'pipe',
64
+ stderr: 'pipe',
65
+ },
66
+ );
71
67
  const [text, errorText] = await Promise.all([
72
68
  new Response(child.stdout).text(),
73
69
  new Response(child.stderr).text(),
74
70
  ]);
75
71
 
76
- if ((await child.exited) !== ExitCodes.OK) {
72
+ const exitCode = await child.exited;
73
+
74
+ if (exitCode !== ExitCodes.OK) {
77
75
  process.stderr.write(errorText.endsWith('\n') ? errorText : `${errorText}\n`);
78
76
 
79
77
  return undefined;
@@ -82,17 +80,6 @@ export const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | u
82
80
  return parseDistTags({ text });
83
81
  };
84
82
 
85
- /** The higher of the two tags by semver, so a stale `next` never pulls a project below the stable release. */
86
- export const pickNightly = (opts: IDistTags): string | undefined => {
87
- const { latest, next } = opts;
88
-
89
- if (latest === undefined || next === undefined) {
90
- return latest ?? next;
91
- }
92
-
93
- return Bun.semver.order(next, latest) === 1 ? next : latest;
94
- };
95
-
96
83
  /** The version of the `@venizia/vulcan` the project has installed, undefined when none is readable. */
97
84
  const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
98
85
  const file = join(opts.cwd, 'node_modules', PACKAGE_NAME, 'package.json');
@@ -102,7 +89,10 @@ const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
102
89
  }
103
90
 
104
91
  try {
105
- const version = readProperty({ value: JSON.parse(readFileSync(file, 'utf8')), key: 'version' });
92
+ const version = JsonValue.readProperty({
93
+ value: JSON.parse(readFileSync(file, 'utf8')),
94
+ key: 'version',
95
+ });
106
96
 
107
97
  return typeof version === 'string' ? version : undefined;
108
98
  } catch {
@@ -110,64 +100,81 @@ const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
110
100
  }
111
101
  };
112
102
 
113
- /**
114
- * What to install: an explicit version or tag wins over the channel; `--nightly` is the newest of the
115
- * `latest` and `next` tags; otherwise `latest`. Undefined, after saying why on stderr, when `--nightly`
116
- * cannot be resolved.
117
- */
118
- export const resolveUpgradeTarget = async (opts: ICommandContext): Promise<string | undefined> => {
119
- const explicit = opts.args.find((arg) => !arg.startsWith('-'));
120
-
121
- if (explicit !== undefined) {
122
- return explicit;
103
+ export class UpgradeTarget {
104
+ static buildArgs(opts: { target?: string }): string[] {
105
+ return ['add', '--dev', '--exact', `${PACKAGE_NAME}@${opts.target ?? DEFAULT_TARGET}`];
123
106
  }
124
107
 
125
- if (!opts.args.includes(UpgradeFlags.NIGHTLY)) {
126
- const installed = readInstalledVersion({ cwd: opts.cwd });
108
+ /** The higher of the two tags by semver, so a stale `next` never pulls a project below the stable release. */
109
+ static pickNightly(opts: IDistTags): string | undefined {
110
+ const { latest, next } = opts;
127
111
 
128
- if (installed !== undefined && CreateConstants.PRERELEASE_PATTERN.test(installed)) {
129
- process.stderr.write(
130
- `vulcan upgrade: ${installed} is installed, a prerelease; ${UpgradeFlags.STABLE} installs the latest stable release and ${UpgradeFlags.NIGHTLY} keeps the prerelease line\n`,
131
- );
112
+ if (latest === undefined || next === undefined) {
113
+ return latest ?? next;
132
114
  }
133
115
 
134
- return DEFAULT_TARGET;
116
+ return Bun.semver.order(next, latest) === 1 ? next : latest;
135
117
  }
136
118
 
137
- const tags = await readDistTags({ cwd: opts.cwd });
138
- const target = tags === undefined ? undefined : pickNightly(tags);
119
+ /**
120
+ * What to install: an explicit version or tag wins over the channel; `--nightly` is the newest of the
121
+ * `latest` and `next` tags; otherwise `latest`. Undefined, after saying why on stderr, when `--nightly`
122
+ * cannot be resolved.
123
+ */
124
+ static async resolve(opts: ICommandContext): Promise<string | undefined> {
125
+ const explicit = opts.args.find((arg) => !arg.startsWith('-'));
139
126
 
140
- if (target === undefined) {
141
- process.stderr.write(
142
- `vulcan upgrade: ${UpgradeFlags.NIGHTLY} could not read the dist-tags of ${PACKAGE_NAME} - pass a version instead\n`,
143
- );
144
- }
127
+ if (explicit !== undefined) {
128
+ return explicit;
129
+ }
145
130
 
146
- return target;
147
- };
131
+ if (!opts.args.includes(UpgradeFlags.NIGHTLY)) {
132
+ const installed = readInstalledVersion({ cwd: opts.cwd });
148
133
 
149
- /**
150
- * Runs `sync` from the CLI the install just wrote, as a child: this process still holds the old
151
- * version's code and base, so an in-process sync would write the old adapters.
152
- */
153
- export const runInstalledSync = async (opts: { cwd: string }): Promise<number> => {
154
- const bin = join(opts.cwd, 'node_modules', '.bin', 'vulcan');
134
+ if (installed !== undefined && CreateConstants.PRERELEASE_PATTERN.test(installed)) {
135
+ process.stderr.write(
136
+ `vulcan upgrade: ${installed} is installed, a prerelease; ${UpgradeFlags.STABLE} installs the latest stable release and ${UpgradeFlags.NIGHTLY} keeps the prerelease line\n`,
137
+ );
138
+ }
155
139
 
156
- if (!existsSync(bin)) {
157
- process.stderr.write(
158
- `vulcan upgrade: no installed vulcan at ${bin} - the install did not complete\n`,
159
- );
140
+ return DEFAULT_TARGET;
141
+ }
160
142
 
161
- return ExitCodes.FAILURE;
143
+ const tags = await readDistTags({ cwd: opts.cwd });
144
+ const target = tags === undefined ? undefined : UpgradeTarget.pickNightly(tags);
145
+
146
+ if (target === undefined) {
147
+ process.stderr.write(
148
+ `vulcan upgrade: ${UpgradeFlags.NIGHTLY} could not read the dist-tags of ${PACKAGE_NAME} - pass a version instead\n`,
149
+ );
150
+ }
151
+
152
+ return target;
162
153
  }
163
154
 
164
- const child = Bun.spawn([process.execPath, bin, 'sync'], {
165
- cwd: opts.cwd,
166
- stdio: ['inherit', 'inherit', 'inherit'],
167
- });
155
+ /**
156
+ * Runs `sync` from the CLI the install just wrote, as a child: this process still holds the old
157
+ * version's code and base, so an in-process sync would write the old adapters.
158
+ */
159
+ static async runInstalledSync(opts: { cwd: string }): Promise<number> {
160
+ const bin = join(opts.cwd, 'node_modules', '.bin', 'vulcan');
168
161
 
169
- return child.exited;
170
- };
162
+ if (!existsSync(bin)) {
163
+ process.stderr.write(
164
+ `vulcan upgrade: no installed vulcan at ${bin} - the install did not complete\n`,
165
+ );
166
+
167
+ return ExitCodes.FAILURE;
168
+ }
169
+
170
+ const child = Bun.spawn([process.execPath, bin, 'sync'], {
171
+ cwd: opts.cwd,
172
+ stdio: ['inherit', 'inherit', 'inherit'],
173
+ });
174
+
175
+ return child.exited;
176
+ }
177
+ }
171
178
 
172
179
  /** Installs the target version, then syncs with it, so the adapters always match the installed base. */
173
180
  export const runUpgradeCommand = async (opts: ICommandContext): Promise<number> => {
@@ -179,24 +186,24 @@ export const runUpgradeCommand = async (opts: ICommandContext): Promise<number>
179
186
  return ExitCodes.FAILURE;
180
187
  }
181
188
 
182
- const target = await resolveUpgradeTarget(opts);
189
+ const target = await UpgradeTarget.resolve(opts);
183
190
 
184
191
  if (target === undefined) {
185
192
  return ExitCodes.FAILURE;
186
193
  }
187
194
 
188
- const args = buildUpgradeArgs({ target });
189
- const code = await runBun({ cwd: opts.cwd, args, label: `bun ${args.join(' ')}` });
195
+ const args = UpgradeTarget.buildArgs({ target });
196
+ const code = await SubProcess.runBun({ cwd: opts.cwd, args, label: `bun ${args.join(' ')}` });
190
197
 
191
198
  if (code !== ExitCodes.OK) {
192
199
  return code;
193
200
  }
194
201
 
195
- if (isInstallSkipped()) {
202
+ if (SubProcess.isInstallSkipped()) {
196
203
  process.stderr.write(' skipped vulcan sync (VULCAN_NO_INSTALL)\n');
197
204
 
198
205
  return ExitCodes.OK;
199
206
  }
200
207
 
201
- return runInstalledSync({ cwd: opts.cwd });
208
+ return UpgradeTarget.runInstalledSync({ cwd: opts.cwd });
202
209
  };
@@ -2,7 +2,8 @@ import { readFileSync, statSync } from 'node:fs';
2
2
  import { basename, resolve } from 'node:path';
3
3
  import { ExitCodes } from '../common/index.ts';
4
4
  import type { ICommandContext } from '../common/index.ts';
5
- import { pageNameOf, renderSpecText, specSchemaText, writePage } from '../visualize/index.ts';
5
+ import { OwnerProfile } from '../owner/profile.ts';
6
+ import { ProjectTheme, SpecPage } from '../visualize/index.ts';
6
7
 
7
8
  const SCHEMA_FLAG = '--schema';
8
9
  const OUT_FLAG = '--out';
@@ -27,7 +28,7 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
27
28
  }
28
29
 
29
30
  if (opts.args.includes(SCHEMA_FLAG)) {
30
- process.stdout.write(specSchemaText());
31
+ process.stdout.write(SpecPage.specSchemaText());
31
32
 
32
33
  return ExitCodes.OK;
33
34
  }
@@ -53,7 +54,7 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
53
54
  }
54
55
 
55
56
  const source = out ?? basename(specFile);
56
- const name = pageNameOf({ name: source });
57
+ const name = SpecPage.pageNameOf({ name: source });
57
58
 
58
59
  if (name === undefined) {
59
60
  process.stderr.write(
@@ -75,7 +76,17 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
75
76
  return ExitCodes.FAILURE;
76
77
  }
77
78
 
78
- const rendered = renderSpecText({ text });
79
+ // The page takes the project's colour from the manifest of the folder it runs in (no config is loaded, nothing
80
+ // is requested) and its words from the owner's profile; a spec's own `accent` and `language` win.
81
+ const manifest = ProjectTheme.readManifestTheme({ root: opts.cwd });
82
+ const profile = OwnerProfile.read({ root: opts.cwd });
83
+ const rendered = SpecPage.renderText({
84
+ text,
85
+ context: {
86
+ language: profile.ok ? profile.profile?.language : undefined,
87
+ project: manifest.theme,
88
+ },
89
+ });
79
90
 
80
91
  if (!rendered.ok) {
81
92
  process.stderr.write(
@@ -85,7 +96,7 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
85
96
  return ExitCodes.FAILURE;
86
97
  }
87
98
 
88
- const written = writePage({ root: opts.cwd, name, html: rendered.page.html });
99
+ const written = SpecPage.write({ root: opts.cwd, name, html: rendered.page.html });
89
100
 
90
101
  if (!written.ok) {
91
102
  process.stderr.write(`vulcan visualize: ${written.error}\n`);
@@ -95,6 +106,10 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
95
106
 
96
107
  process.stdout.write(`${written.path}\n`);
97
108
 
109
+ if (manifest.warning !== undefined) {
110
+ process.stderr.write(`warning: ${manifest.warning}\n`);
111
+ }
112
+
98
113
  for (const warning of rendered.page.warnings) {
99
114
  process.stderr.write(`warning: ${warning}\n`);
100
115
  }
@@ -1,8 +1,8 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { ExitCodes, PACKAGE_ROOT, ProjectLayout, VulcanTools } from '../common/index.ts';
4
- import { findConfigFiles, loadConfig, resolvePackages } from '../config/index.ts';
5
- import { ManifestConstants, renderManifest } from '../manifest/index.ts';
4
+ import { ConfigLoader, ProjectPackages } from '../config/index.ts';
5
+ import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
6
6
  import type { ICommandContext, IToolPackage } from '../common/index.ts';
7
7
 
8
8
  const TOOL_PACKAGES: Record<string, IToolPackage> = {
@@ -16,61 +16,66 @@ interface IPackageManifest {
16
16
 
17
17
  const listTools = (): string => [...VulcanTools.SCHEME_SET].join(', ');
18
18
 
19
- /** The tool's bin inside its installed package, resolved from @venizia/vulcan; `undefined` when not installed. */
20
- export const resolveToolBin = (opts: { name: string }): string | undefined => {
21
- const tool = TOOL_PACKAGES[opts.name];
19
+ export class ToolRunner {
20
+ /** The tool's bin inside its installed package, resolved from @venizia/vulcan; `undefined` when not installed. */
21
+ static resolveBin(opts: { name: string }): string | undefined {
22
+ const tool = TOOL_PACKAGES[opts.name];
22
23
 
23
- if (tool === undefined) {
24
- return undefined;
25
- }
24
+ if (tool === undefined) {
25
+ return undefined;
26
+ }
26
27
 
27
- let manifestPath: string;
28
+ let manifestPath: string;
28
29
 
29
- try {
30
- manifestPath = Bun.resolveSync(`${tool.packageName}/package.json`, PACKAGE_ROOT);
31
- } catch (error) {
32
- process.stderr.write(
33
- `vulcan x: ${tool.packageName} is not resolvable - ${error instanceof Error ? error.message : String(error)}\n`,
34
- );
35
-
36
- return undefined;
37
- }
30
+ try {
31
+ manifestPath = Bun.resolveSync(`${tool.packageName}/package.json`, PACKAGE_ROOT);
32
+ } catch (error) {
33
+ process.stderr.write(
34
+ `vulcan x: ${tool.packageName} is not resolvable - ${error instanceof Error ? error.message : String(error)}\n`,
35
+ );
38
36
 
39
- const manifest: IPackageManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
40
- const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[tool.binName];
37
+ return undefined;
38
+ }
41
39
 
42
- return bin === undefined ? undefined : join(dirname(manifestPath), bin);
43
- };
40
+ const manifest: IPackageManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
41
+ const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[tool.binName];
44
42
 
45
- /**
46
- * The environment a tool runs with: the project's resolved config, validated once here, when the
47
- * project has one. No config is fine (atlas serves sources without one); an invalid one is an error.
48
- */
49
- export const buildToolEnvironment = async (opts: {
50
- root: string;
51
- }): Promise<{ ok: true; env: Record<string, string> } | { ok: false; error: string }> => {
52
- if (findConfigFiles({ root: opts.root }).length === 0) {
53
- return { ok: true, env: {} };
43
+ return bin === undefined ? undefined : join(dirname(manifestPath), bin);
54
44
  }
55
45
 
56
- const loaded = await loadConfig({ root: opts.root });
57
-
58
- if (!loaded.ok) {
59
- return { ok: false, error: loaded.error };
46
+ /**
47
+ * The environment a tool runs with: the project's resolved config, validated once here, when the
48
+ * project has one. No config is fine (atlas serves sources without one); an invalid one is an error.
49
+ */
50
+ static async buildEnvironment(opts: {
51
+ root: string;
52
+ }): Promise<{ ok: true; env: Record<string, string> } | { ok: false; error: string }> {
53
+ if (ConfigLoader.findFiles({ root: opts.root }).length === 0) {
54
+ return { ok: true, env: {} };
55
+ }
56
+
57
+ const loaded = await ConfigLoader.load({ root: opts.root });
58
+
59
+ if (!loaded.ok) {
60
+ return { ok: false, error: loaded.error };
61
+ }
62
+
63
+ const config = {
64
+ ...loaded.config,
65
+ packages: ProjectPackages.resolve({ config: loaded.config }),
66
+ };
67
+
68
+ return {
69
+ ok: true,
70
+ env: {
71
+ [ProjectLayout.CONFIG_ENV]: JSON.stringify(config),
72
+ [ProjectLayout.ROOT_ENV]: opts.root,
73
+ // Atlas reads the manifest only; rendered fresh, so a run never sees a stale committed one.
74
+ [ManifestConstants.ENV]: ProjectManifest.render({ root: opts.root, config: loaded.config }),
75
+ },
76
+ };
60
77
  }
61
-
62
- const config = { ...loaded.config, packages: resolvePackages({ config: loaded.config }) };
63
-
64
- return {
65
- ok: true,
66
- env: {
67
- [ProjectLayout.CONFIG_ENV]: JSON.stringify(config),
68
- [ProjectLayout.ROOT_ENV]: opts.root,
69
- // Atlas reads the manifest only; rendered fresh, so a run never sees a stale committed one.
70
- [ManifestConstants.ENV]: renderManifest({ root: opts.root, config: loaded.config }),
71
- },
72
- };
73
- };
78
+ }
74
79
 
75
80
  /** Runs the tool as a child on the inherited stdio: vulcan writes nothing to stdout, so MCP stays clean. */
76
81
  export const runXCommand = async (opts: ICommandContext): Promise<number> => {
@@ -84,7 +89,7 @@ export const runXCommand = async (opts: ICommandContext): Promise<number> => {
84
89
  return ExitCodes.FAILURE;
85
90
  }
86
91
 
87
- const bin = resolveToolBin({ name });
92
+ const bin = ToolRunner.resolveBin({ name });
88
93
 
89
94
  if (bin === undefined) {
90
95
  process.stderr.write(
@@ -94,7 +99,7 @@ export const runXCommand = async (opts: ICommandContext): Promise<number> => {
94
99
  return ExitCodes.FAILURE;
95
100
  }
96
101
 
97
- const environment = await buildToolEnvironment({ root: opts.cwd });
102
+ const environment = await ToolRunner.buildEnvironment({ root: opts.cwd });
98
103
 
99
104
  if (!environment.ok) {
100
105
  process.stderr.write(`vulcan x: ${environment.error}\n`);
@@ -1,24 +1,26 @@
1
- /**
2
- * `text` as `bun fmt` formats the file named `opts.file` (only the extension and name matter: the
3
- * text goes in on stdin). A file VULCAN writes this way is what `bun fmt --check` accepts, so a
4
- * regenerate never turns lint red, and no copy of Bun's rules (key order, array layout) lives here.
5
- * `--no-script` keeps a `fmt` script from taking over. Bun is the runtime (`engines`), so
6
- * `process.execPath` is it. When bun fmt fails the text comes back unchanged and the reason is
7
- * printed: `make lint` flags the file.
8
- */
9
- export const formatWithBun = (opts: { text: string; file: string }): string => {
10
- const result = Bun.spawnSync(
11
- [process.execPath, 'fmt', '--no-script', '--stdin-filepath', opts.file],
12
- { stdin: Buffer.from(opts.text), stdout: 'pipe', stderr: 'pipe' },
13
- );
14
-
15
- if (result.exitCode !== 0) {
16
- console.error(
17
- `[formatWithBun] bun fmt exited ${result.exitCode}, ${opts.file} is left as rendered | ${result.stderr.toString().trim()}`,
1
+ export class BunFormatter {
2
+ /**
3
+ * `text` as `bun fmt` formats the file named `opts.file` (only the extension and name matter: the
4
+ * text goes in on stdin). A file VULCAN writes this way is what `bun fmt --check` accepts, so a
5
+ * regenerate never turns lint red, and no copy of Bun's rules (key order, array layout) lives here.
6
+ * `--no-script` keeps a `fmt` script from taking over. Bun is the runtime (`engines`), so
7
+ * `process.execPath` is it. When bun fmt fails the text comes back unchanged and the reason is
8
+ * printed: `make lint` flags the file.
9
+ */
10
+ static format(opts: { text: string; file: string }): string {
11
+ const result = Bun.spawnSync(
12
+ [process.execPath, 'fmt', '--no-script', '--stdin-filepath', opts.file],
13
+ { stdin: Buffer.from(opts.text), stdout: 'pipe', stderr: 'pipe' },
18
14
  );
19
15
 
20
- return opts.text;
21
- }
16
+ if (result.exitCode !== 0) {
17
+ console.error(
18
+ `[BunFormatter.format] bun fmt exited ${result.exitCode}, ${opts.file} is left as rendered | ${result.stderr.toString().trim()}`,
19
+ );
22
20
 
23
- return result.stdout.toString();
24
- };
21
+ return opts.text;
22
+ }
23
+
24
+ return result.stdout.toString();
25
+ }
26
+ }
@@ -3,3 +3,5 @@ export * from './paths.ts';
3
3
  export * from './types.ts';
4
4
  export * from './json.ts';
5
5
  export * from './format.ts';
6
+ export * from './record.ts';
7
+ export * from './text.ts';
@@ -1,5 +1,8 @@
1
- /** The value under `key` of anything that is an object, else undefined: untrusted JSON is read without a cast. */
2
- export const readProperty = (opts: { value: unknown; key: string }): unknown =>
3
- typeof opts.value === 'object' && opts.value !== null
4
- ? Reflect.get(opts.value, opts.key)
5
- : undefined;
1
+ export class JsonValue {
2
+ /** The value under `key` of anything that is an object, else undefined: untrusted JSON is read without a cast. */
3
+ static readProperty(opts: { value: unknown; key: string }): unknown {
4
+ return typeof opts.value === 'object' && opts.value !== null
5
+ ? Reflect.get(opts.value, opts.key)
6
+ : undefined;
7
+ }
8
+ }