@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
@@ -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;
@@ -63,11 +56,14 @@ const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | undefine
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(),
@@ -84,17 +80,6 @@ const readDistTags = async (opts: { cwd: string }): Promise<IDistTags | undefine
84
80
  return parseDistTags({ text });
85
81
  };
86
82
 
87
- /** The higher of the two tags by semver, so a stale `next` never pulls a project below the stable release. */
88
- export const pickNightly = (opts: IDistTags): string | undefined => {
89
- const { latest, next } = opts;
90
-
91
- if (latest === undefined || next === undefined) {
92
- return latest ?? next;
93
- }
94
-
95
- return Bun.semver.order(next, latest) === 1 ? next : latest;
96
- };
97
-
98
83
  /** The version of the `@venizia/vulcan` the project has installed, undefined when none is readable. */
99
84
  const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
100
85
  const file = join(opts.cwd, 'node_modules', PACKAGE_NAME, 'package.json');
@@ -104,7 +89,10 @@ const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
104
89
  }
105
90
 
106
91
  try {
107
- 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
+ });
108
96
 
109
97
  return typeof version === 'string' ? version : undefined;
110
98
  } catch {
@@ -112,64 +100,81 @@ const readInstalledVersion = (opts: { cwd: string }): string | undefined => {
112
100
  }
113
101
  };
114
102
 
115
- /**
116
- * What to install: an explicit version or tag wins over the channel; `--nightly` is the newest of the
117
- * `latest` and `next` tags; otherwise `latest`. Undefined, after saying why on stderr, when `--nightly`
118
- * cannot be resolved.
119
- */
120
- export const resolveUpgradeTarget = async (opts: ICommandContext): Promise<string | undefined> => {
121
- const explicit = opts.args.find((arg) => !arg.startsWith('-'));
122
-
123
- if (explicit !== undefined) {
124
- return explicit;
103
+ export class UpgradeTarget {
104
+ static buildArgs(opts: { target?: string }): string[] {
105
+ return ['add', '--dev', '--exact', `${PACKAGE_NAME}@${opts.target ?? DEFAULT_TARGET}`];
125
106
  }
126
107
 
127
- if (!opts.args.includes(UpgradeFlags.NIGHTLY)) {
128
- 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;
129
111
 
130
- if (installed !== undefined && CreateConstants.PRERELEASE_PATTERN.test(installed)) {
131
- process.stderr.write(
132
- `vulcan upgrade: ${installed} is installed, a prerelease; ${UpgradeFlags.STABLE} installs the latest stable release and ${UpgradeFlags.NIGHTLY} keeps the prerelease line\n`,
133
- );
112
+ if (latest === undefined || next === undefined) {
113
+ return latest ?? next;
134
114
  }
135
115
 
136
- return DEFAULT_TARGET;
116
+ return Bun.semver.order(next, latest) === 1 ? next : latest;
137
117
  }
138
118
 
139
- const tags = await readDistTags({ cwd: opts.cwd });
140
- 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('-'));
141
126
 
142
- if (target === undefined) {
143
- process.stderr.write(
144
- `vulcan upgrade: ${UpgradeFlags.NIGHTLY} could not read the dist-tags of ${PACKAGE_NAME} - pass a version instead\n`,
145
- );
146
- }
127
+ if (explicit !== undefined) {
128
+ return explicit;
129
+ }
147
130
 
148
- return target;
149
- };
131
+ if (!opts.args.includes(UpgradeFlags.NIGHTLY)) {
132
+ const installed = readInstalledVersion({ cwd: opts.cwd });
150
133
 
151
- /**
152
- * Runs `sync` from the CLI the install just wrote, as a child: this process still holds the old
153
- * version's code and base, so an in-process sync would write the old adapters.
154
- */
155
- export const runInstalledSync = async (opts: { cwd: string }): Promise<number> => {
156
- 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
+ }
157
139
 
158
- if (!existsSync(bin)) {
159
- process.stderr.write(
160
- `vulcan upgrade: no installed vulcan at ${bin} - the install did not complete\n`,
161
- );
140
+ return DEFAULT_TARGET;
141
+ }
162
142
 
163
- 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;
164
153
  }
165
154
 
166
- const child = Bun.spawn([process.execPath, bin, 'sync'], {
167
- cwd: opts.cwd,
168
- stdio: ['inherit', 'inherit', 'inherit'],
169
- });
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');
170
161
 
171
- return child.exited;
172
- };
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
+ }
173
178
 
174
179
  /** Installs the target version, then syncs with it, so the adapters always match the installed base. */
175
180
  export const runUpgradeCommand = async (opts: ICommandContext): Promise<number> => {
@@ -181,24 +186,24 @@ export const runUpgradeCommand = async (opts: ICommandContext): Promise<number>
181
186
  return ExitCodes.FAILURE;
182
187
  }
183
188
 
184
- const target = await resolveUpgradeTarget(opts);
189
+ const target = await UpgradeTarget.resolve(opts);
185
190
 
186
191
  if (target === undefined) {
187
192
  return ExitCodes.FAILURE;
188
193
  }
189
194
 
190
- const args = buildUpgradeArgs({ target });
191
- 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(' ')}` });
192
197
 
193
198
  if (code !== ExitCodes.OK) {
194
199
  return code;
195
200
  }
196
201
 
197
- if (isInstallSkipped()) {
202
+ if (SubProcess.isInstallSkipped()) {
198
203
  process.stderr.write(' skipped vulcan sync (VULCAN_NO_INSTALL)\n');
199
204
 
200
205
  return ExitCodes.OK;
201
206
  }
202
207
 
203
- return runInstalledSync({ cwd: opts.cwd });
208
+ return UpgradeTarget.runInstalledSync({ cwd: opts.cwd });
204
209
  };
@@ -2,14 +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 { readProfile } from '../owner/profile.ts';
6
- import {
7
- pageNameOf,
8
- ProjectTheme,
9
- renderSpecText,
10
- specSchemaText,
11
- writePage,
12
- } from '../visualize/index.ts';
5
+ import { OwnerProfile } from '../owner/profile.ts';
6
+ import { ProjectTheme, SpecPage } from '../visualize/index.ts';
13
7
 
14
8
  const SCHEMA_FLAG = '--schema';
15
9
  const OUT_FLAG = '--out';
@@ -34,7 +28,7 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
34
28
  }
35
29
 
36
30
  if (opts.args.includes(SCHEMA_FLAG)) {
37
- process.stdout.write(specSchemaText());
31
+ process.stdout.write(SpecPage.specSchemaText());
38
32
 
39
33
  return ExitCodes.OK;
40
34
  }
@@ -60,7 +54,7 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
60
54
  }
61
55
 
62
56
  const source = out ?? basename(specFile);
63
- const name = pageNameOf({ name: source });
57
+ const name = SpecPage.pageNameOf({ name: source });
64
58
 
65
59
  if (name === undefined) {
66
60
  process.stderr.write(
@@ -85,8 +79,8 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
85
79
  // The page takes the project's colour from the manifest of the folder it runs in (no config is loaded, nothing
86
80
  // is requested) and its words from the owner's profile; a spec's own `accent` and `language` win.
87
81
  const manifest = ProjectTheme.readManifestTheme({ root: opts.cwd });
88
- const profile = readProfile({ root: opts.cwd });
89
- const rendered = renderSpecText({
82
+ const profile = OwnerProfile.read({ root: opts.cwd });
83
+ const rendered = SpecPage.renderText({
90
84
  text,
91
85
  context: {
92
86
  language: profile.ok ? profile.profile?.language : undefined,
@@ -102,7 +96,7 @@ export const runVisualizeCommand = async (opts: ICommandContext): Promise<number
102
96
  return ExitCodes.FAILURE;
103
97
  }
104
98
 
105
- const written = writePage({ root: opts.cwd, name, html: rendered.page.html });
99
+ const written = SpecPage.write({ root: opts.cwd, name, html: rendered.page.html });
106
100
 
107
101
  if (!written.ok) {
108
102
  process.stderr.write(`vulcan visualize: ${written.error}\n`);
@@ -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
+ }
@@ -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
+ }