@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,45 +1,47 @@
1
1
  import { join } from 'node:path';
2
2
  import { ExitCodes, ProjectLayout } from '../common/index.ts';
3
- import { runBun } from './process.ts';
3
+ import { SubProcess } from './process.ts';
4
4
 
5
- /** The preset's own checks in the app, then the contract at the root; the first failure stops. */
6
- export const runAppChecks = async (opts: {
7
- root: string;
8
- appDirectory: string;
9
- checks: string[];
10
- }): Promise<number> => {
11
- for (const check of opts.checks) {
12
- const code = await runBun({
13
- cwd: opts.appDirectory,
14
- args: ['run', check],
15
- label: `bun run ${check} (${opts.appDirectory})`,
16
- });
5
+ export class AppChecks {
6
+ /** The preset's own checks in the app, then the contract at the root; the first failure stops. */
7
+ static async run(opts: {
8
+ root: string;
9
+ appDirectory: string;
10
+ checks: string[];
11
+ }): Promise<number> {
12
+ for (const check of opts.checks) {
13
+ const code = await SubProcess.runBun({
14
+ cwd: opts.appDirectory,
15
+ args: ['run', check],
16
+ label: `bun run ${check} (${opts.appDirectory})`,
17
+ });
17
18
 
18
- if (code !== ExitCodes.OK) {
19
- process.stderr.write(
20
- `vulcan: 'bun run ${check}' failed in ${opts.appDirectory} - the project is left as is for you to inspect\n`,
21
- );
19
+ if (code !== ExitCodes.OK) {
20
+ process.stderr.write(
21
+ `vulcan: 'bun run ${check}' failed in ${opts.appDirectory} - the project is left as is for you to inspect\n`,
22
+ );
22
23
 
23
- return code;
24
+ return code;
25
+ }
24
26
  }
25
- }
26
27
 
27
- const bin = join(opts.root, 'node_modules', '.bin', 'vulcan');
28
+ const bin = join(opts.root, 'node_modules', '.bin', 'vulcan');
28
29
 
29
- for (const args of [
30
- [bin, 'doctor'],
31
- [bin, 'x', 'okf', 'check', '--strict'],
32
- ]) {
33
- const code = await runBun({
34
- cwd: opts.root,
35
- args,
36
- label: `${ProjectLayout.VULCAN_COMMAND} ${args.slice(1).join(' ')}`,
37
- });
30
+ for (const args of [
31
+ [bin, 'doctor'],
32
+ [bin, 'x', 'okf', 'check', '--strict'],
33
+ ]) {
34
+ const code = await SubProcess.runBun({
35
+ cwd: opts.root,
36
+ args,
37
+ label: `${ProjectLayout.VULCAN_COMMAND} ${args.slice(1).join(' ')}`,
38
+ });
38
39
 
39
- if (code !== ExitCodes.OK) {
40
- return code;
40
+ if (code !== ExitCodes.OK) {
41
+ return code;
42
+ }
41
43
  }
42
- }
43
44
 
44
- return ExitCodes.OK;
45
- };
45
+ return ExitCodes.OK;
46
+ }
47
+ }
@@ -114,28 +114,26 @@ const hunksOf = (opts: { edits: IEdit[]; context: number }): string[] => {
114
114
  return hunks;
115
115
  };
116
116
 
117
- /**
118
- * What differs between the file an app has and the file its preset makes: the counts and the unified
119
- * diff (`-` is the app's line, `+` the preset's). Two texts that hold the same lines but differ in line
120
- * endings or in the final newline have no hunks and 0 and 0.
121
- */
122
- export const diffLines = (opts: {
123
- current: string;
124
- preset: string;
125
- context?: number;
126
- }): ILineDiff => {
127
- const current = linesOf({ text: opts.current });
128
- const preset = linesOf({ text: opts.preset });
129
-
130
- if ((current.length + 1) * (preset.length + 1) > MAX_TABLE_CELLS) {
131
- return { added: 0, removed: 0, hunks: undefined };
132
- }
117
+ export class LineDiff {
118
+ /**
119
+ * What differs between the file an app has and the file its preset makes: the counts and the unified
120
+ * diff (`-` is the app's line, `+` the preset's). Two texts that hold the same lines but differ in line
121
+ * endings or in the final newline have no hunks and 0 and 0.
122
+ */
123
+ static diff(opts: { current: string; preset: string; context?: number }): ILineDiff {
124
+ const current = linesOf({ text: opts.current });
125
+ const preset = linesOf({ text: opts.preset });
126
+
127
+ if ((current.length + 1) * (preset.length + 1) > MAX_TABLE_CELLS) {
128
+ return { added: 0, removed: 0, hunks: undefined };
129
+ }
133
130
 
134
- const edits = editsOf({ current, preset });
131
+ const edits = editsOf({ current, preset });
135
132
 
136
- return {
137
- added: edits.filter((edit) => edit.kind === DiffEditKinds.ADD).length,
138
- removed: edits.filter((edit) => edit.kind === DiffEditKinds.REMOVE).length,
139
- hunks: hunksOf({ edits, context: opts.context ?? DEFAULT_CONTEXT_LINES }),
140
- };
141
- };
133
+ return {
134
+ added: edits.filter((edit) => edit.kind === DiffEditKinds.ADD).length,
135
+ removed: edits.filter((edit) => edit.kind === DiffEditKinds.REMOVE).length,
136
+ hunks: hunksOf({ edits, context: opts.context ?? DEFAULT_CONTEXT_LINES }),
137
+ };
138
+ }
139
+ }
@@ -1,5 +1,5 @@
1
- import { excludePathsOf, readAgentTable } from '../agents/index.ts';
2
- import { shippedSkillNames } from '../sync/exclude.ts';
1
+ import { AgentExclude, AgentTable } from '../agents/index.ts';
2
+ import { ExcludePlan } from '../sync/exclude.ts';
3
3
 
4
4
  /** What no image needs: dependencies, build output, git history and the agents' own folders. */
5
5
  const BASE_PATTERNS = [
@@ -22,26 +22,28 @@ const SECRET_PATTERNS = ['**/.env', '**/.env.*', '!**/.env.example'];
22
22
  const SECRET_COMMENT =
23
23
  '# .env files hold secrets: keep them out of every image layer; the example stays.';
24
24
 
25
- /**
26
- * The root `.dockerignore` of a new project: a Dockerfile is built from the project root, so the
27
- * context must not carry dependencies, build output or git. Beside the base patterns it lists the
28
- * per-machine files of every agent, the ones `sync` keeps in `.git/info/exclude`, so a build
29
- * never depends on which agents a developer chose.
30
- */
31
- export const renderDockerignore = (): string => {
32
- const agentPaths = excludePathsOf({
33
- agents: readAgentTable().map((entry) => entry.id),
34
- skillNames: shippedSkillNames(),
35
- })
36
- .flatMap((group) => group.paths)
37
- .map((path) => path.replace(/^\//, '').replace(/\/$/, ''));
38
- const patterns = [...new Set([...BASE_PATTERNS, ...SECRET_PATTERNS, ...agentPaths])];
25
+ export class Dockerignore {
26
+ /**
27
+ * The root `.dockerignore` of a new project: a Dockerfile is built from the project root, so the
28
+ * context must not carry dependencies, build output or git. Beside the base patterns it lists the
29
+ * per-machine files of every agent, the ones `sync` keeps in `.git/info/exclude`, so a build
30
+ * never depends on which agents a developer chose.
31
+ */
32
+ static render(): string {
33
+ const agentPaths = AgentExclude.excludePathsOf({
34
+ agents: AgentTable.read().map((entry) => entry.id),
35
+ skillNames: ExcludePlan.shippedSkillNames(),
36
+ })
37
+ .flatMap((group) => group.paths)
38
+ .map((path) => path.replace(/^\//, '').replace(/\/$/, ''));
39
+ const patterns = [...new Set([...BASE_PATTERNS, ...SECRET_PATTERNS, ...agentPaths])];
39
40
 
40
- return [
41
- '# Written by vulcan init; edit it freely, vulcan never overwrites it. .git is excluded, so pass the commit: docker build --build-arg APP_BUILD_COMMIT="$(git rev-parse HEAD)" ...',
42
- ...patterns.flatMap((pattern) =>
43
- pattern === SECRET_PATTERNS[0] ? [SECRET_COMMENT, pattern] : [pattern],
44
- ),
45
- '',
46
- ].join('\n');
47
- };
41
+ return [
42
+ '# Written by vulcan init; edit it freely, vulcan never overwrites it. .git is excluded, so pass the commit: docker build --build-arg APP_BUILD_COMMIT="$(git rev-parse HEAD)" ...',
43
+ ...patterns.flatMap((pattern) =>
44
+ pattern === SECRET_PATTERNS[0] ? [SECRET_COMMENT, pattern] : [pattern],
45
+ ),
46
+ '',
47
+ ].join('\n');
48
+ }
49
+ }
@@ -1,8 +1,10 @@
1
1
  import { mkdirSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
 
4
- export const writeFile = (opts: { root: string; path: string; content: string }): void => {
5
- mkdirSync(dirname(join(opts.root, opts.path)), { recursive: true });
6
- writeFileSync(join(opts.root, opts.path), opts.content);
7
- process.stderr.write(` created ${opts.path}\n`);
8
- };
4
+ export class ProjectFile {
5
+ static write(opts: { root: string; path: string; content: string }): void {
6
+ mkdirSync(dirname(join(opts.root, opts.path)), { recursive: true });
7
+ writeFileSync(join(opts.root, opts.path), opts.content);
8
+ process.stderr.write(` created ${opts.path}\n`);
9
+ }
10
+ }
@@ -1,9 +1,9 @@
1
1
  import { existsSync, readdirSync, statSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { ExitCodes, ProjectLayout, VULCAN_VERSION } from '../common/index.ts';
4
- import { layoutOverlapProblems } from '../common/layout-folder.ts';
5
- import { renderTemplate } from '../init/index.ts';
6
- import { runAppChecks } from './checks.ts';
4
+ import { LayoutFolder } from '../common/layout-folder.ts';
5
+ import { ProjectScaffold } from '../init/index.ts';
6
+ import { AppChecks } from './checks.ts';
7
7
  import { AppSides, CreateFlags } from './common/index.ts';
8
8
  import type {
9
9
  IAppsBlock,
@@ -12,36 +12,20 @@ import type {
12
12
  IPresetSpec,
13
13
  TAppSide,
14
14
  } from './common/index.ts';
15
- import { writeFile } from './files.ts';
16
- import { recordedPresetOf } from './lib-preset.ts';
17
- import { renderBunfig } from './bunfig.ts';
18
- import { renderDockerignore } from './dockerignore.ts';
19
- import { menusAvailable } from '../ui/index.ts';
20
- import { askPresetSpec } from './preset-menu.ts';
21
- import { ABORTED, confirmWrite, planLines } from './plan.ts';
22
- import {
23
- askInTerminal,
24
- askScope,
25
- findFolderClash,
26
- readFlag,
27
- readScope,
28
- resolveNames,
29
- SIDE_FIELDS,
30
- } from './names.ts';
31
- import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
32
- import { renderNext } from './next.ts';
33
- import { isInstallSkipped, runBun, runGitInit } from './process.ts';
34
- import { offerProfile } from '../commands/profile.command.ts';
35
- import { installNpmPreset, withScratch } from './scratch.ts';
36
- import {
37
- filePresetWarning,
38
- renderAppConcept,
39
- renderAppManifest,
40
- renderKnowledgeIndex,
41
- renderRootManifest,
42
- presetSpecOf,
43
- renderVulcanConfig,
44
- } from './workspace.ts';
15
+ import { ProjectFile } from './files.ts';
16
+ import { LibPreset } from './lib-preset.ts';
17
+ import { Bunfig } from './bunfig.ts';
18
+ import { Dockerignore } from './dockerignore.ts';
19
+ import { TerminalCapability } from '../ui/index.ts';
20
+ import { PresetMenu } from './preset-menu.ts';
21
+ import { ABORTED, WritePlan } from './plan.ts';
22
+ import { askInTerminal, ProjectNames, SIDE_FIELDS } from './names.ts';
23
+ import { Preset } from './preset.ts';
24
+ import { NextStep } from './next.ts';
25
+ import { SubProcess } from './process.ts';
26
+ import { ProfilePrompt } from '../commands/profile.command.ts';
27
+ import { PresetScratch } from './scratch.ts';
28
+ import { WorkspaceDocs, WorkspaceManifest, PresetRecord } from './workspace.ts';
45
29
 
46
30
  /** The VULCAN layer files; the knowledge index is rendered from the apps, not copied. */
47
31
  const LAYER_FILES = [
@@ -105,32 +89,32 @@ const writeMonorepo = (opts: {
105
89
  [packageName]: spec.packageName === undefined ? spec.range : packageVersion,
106
90
  };
107
91
 
108
- writeFile({
92
+ ProjectFile.write({
109
93
  root,
110
94
  path: 'package.json',
111
- content: renderRootManifest({
95
+ content: WorkspaceManifest.renderRoot({
112
96
  project,
113
97
  workspaces: [`${folder}/*`, ...(shared === '' ? [] : [`${shared}/*`])],
114
98
  catalog,
115
99
  vulcanVersion: VULCAN_VERSION,
116
100
  }),
117
101
  });
118
- writeFile({
102
+ ProjectFile.write({
119
103
  root,
120
104
  path: '.gitignore',
121
105
  content: `${[...BASE_IGNORES, ...ProjectLayout.GITIGNORE_ENTRIES].join('\n')}\n`,
122
106
  });
123
- writeFile({ root, path: 'README.md', content: `# ${project}\n` });
124
- writeFile({ root, path: '.dockerignore', content: renderDockerignore() });
125
- writeFile({ root, path: 'bunfig.toml', content: renderBunfig() });
107
+ ProjectFile.write({ root, path: 'README.md', content: `# ${project}\n` });
108
+ ProjectFile.write({ root, path: '.dockerignore', content: Dockerignore.render() });
109
+ ProjectFile.write({ root, path: 'bunfig.toml', content: Bunfig.render() });
126
110
 
127
111
  if (shared !== '') {
128
- writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
112
+ ProjectFile.write({ root, path: `${shared}/.gitkeep`, content: '' });
129
113
  }
130
114
 
131
115
  // The first app: nothing uses a port yet, and a frontend has no backend to proxy to.
132
116
  const appDirectory = join(root, folder, app);
133
- const written = copyPresetFiles({
117
+ const written = Preset.copyFiles({
134
118
  located,
135
119
  target: appDirectory,
136
120
  tokens: {
@@ -146,10 +130,10 @@ const writeMonorepo = (opts: {
146
130
  process.stderr.write(` created ${folder}/${app}/${path}\n`);
147
131
  }
148
132
 
149
- writeFile({
133
+ ProjectFile.write({
150
134
  root,
151
135
  path: `${folder}/${app}/package.json`,
152
- content: renderAppManifest({
136
+ content: WorkspaceManifest.renderApp({
153
137
  app,
154
138
  name: packageOfApp,
155
139
  preset,
@@ -158,9 +142,9 @@ const writeMonorepo = (opts: {
158
142
  });
159
143
 
160
144
  for (const file of LAYER_FILES) {
161
- const content = renderTemplate({ template: file.template, name: project });
145
+ const content = ProjectScaffold.renderTemplate({ template: file.template, name: project });
162
146
 
163
- writeFile({
147
+ ProjectFile.write({
164
148
  root,
165
149
  path: file.path,
166
150
  content: file.path === 'Makefile' ? `${content}${DEV_TARGET}` : content,
@@ -171,28 +155,31 @@ const writeMonorepo = (opts: {
171
155
  layout: { [side]: folder, ...(shared === '' ? {} : { shared }) },
172
156
  packages: [{ dir: app, name: packageOfApp, path: `${folder}/${app}` }],
173
157
  presets: [
174
- recordedPresetOf({
175
- spec: presetSpecOf({ value: presetValue, root, cwd: dirname(root) }),
158
+ LibPreset.recordedOf({
159
+ spec: PresetRecord.presetSpecOf({ value: presetValue, root, cwd: dirname(root) }),
176
160
  located,
177
161
  }),
178
162
  ],
179
163
  sources: preset.atlas,
180
164
  };
181
165
 
182
- writeFile({
166
+ ProjectFile.write({
183
167
  root,
184
168
  path: '.configs/vulcan.config.mts',
185
- content: renderVulcanConfig({ project, block }),
169
+ content: WorkspaceDocs.renderVulcanConfig({ project, block }),
186
170
  });
187
- writeFile({
171
+ ProjectFile.write({
188
172
  root,
189
173
  path: '.agents/knowledge/index.md',
190
- content: renderKnowledgeIndex({ project, apps: [{ name: app, summary: preset.summary }] }),
174
+ content: WorkspaceDocs.renderKnowledgeIndex({
175
+ project,
176
+ apps: [{ name: app, summary: preset.summary }],
177
+ }),
191
178
  });
192
- writeFile({
179
+ ProjectFile.write({
193
180
  root,
194
181
  path: `.agents/knowledge/packages/${app}.md`,
195
- content: renderAppConcept({
182
+ content: WorkspaceDocs.renderAppConcept({
196
183
  app: { name: app, side, folder },
197
184
  summary: preset.summary,
198
185
  presetPackage: packageName,
@@ -205,14 +192,14 @@ const runCreate = async (opts: {
205
192
  args: string[];
206
193
  scratch: string;
207
194
  }): Promise<number> => {
208
- const flagged = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
195
+ const flagged = ProjectNames.readFlag({ args: opts.args, flag: CreateFlags.PRESET });
209
196
 
210
- if (flagged === undefined && !menusAvailable()) {
197
+ if (flagged === undefined && !TerminalCapability.menusAvailable()) {
211
198
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
212
199
  }
213
200
 
214
201
  // A new project has no config to list presets from: the official ones, or one typed.
215
- const askingSpec = flagged === undefined ? askPresetSpec({ recorded: [] }) : undefined;
202
+ const askingSpec = flagged === undefined ? PresetMenu.askSpec({ recorded: [] }) : undefined;
216
203
  const typedSpec = await askingSpec;
217
204
  const presetValue = flagged ?? typedSpec?.trim();
218
205
 
@@ -220,15 +207,15 @@ const runCreate = async (opts: {
220
207
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
221
208
  }
222
209
 
223
- const flaggedScope = readScope({ args: opts.args });
210
+ const flaggedScope = ProjectNames.readScope({ args: opts.args });
224
211
 
225
212
  if (!flaggedScope.ok) {
226
213
  return fail({ message: flaggedScope.error });
227
214
  }
228
215
 
229
- const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
216
+ const spec = Preset.parseSpec({ value: presetValue, cwd: opts.cwd });
230
217
  const interactive = process.stdin.isTTY === true;
231
- const first = await resolveNames({
218
+ const first = await ProjectNames.resolve({
232
219
  fields: [
233
220
  { key: 'project', flag: CreateFlags.PROJECT, question: 'Project name (the monorepo folder)' },
234
221
  ],
@@ -253,7 +240,7 @@ const runCreate = async (opts: {
253
240
 
254
241
  const isNpm = spec.packageName !== undefined;
255
242
 
256
- if (isNpm && isInstallSkipped()) {
243
+ if (isNpm && SubProcess.isInstallSkipped()) {
257
244
  return fail({ message: 'an npm preset needs an install - use file: in tests' });
258
245
  }
259
246
 
@@ -262,7 +249,7 @@ const runCreate = async (opts: {
262
249
  if (isNpm) {
263
250
  // Without a terminal nothing is asked, so a missing flag is refused before the network is used.
264
251
  if (!interactive) {
265
- const early = await resolveNames({
252
+ const early = await ProjectNames.resolve({
266
253
  fields: appFields({}),
267
254
  args: opts.args,
268
255
  interactive,
@@ -275,13 +262,13 @@ const runCreate = async (opts: {
275
262
  }
276
263
 
277
264
  // The side is known only once the package is read, so the preset is fetched before the rest is asked.
278
- const installed = await installNpmPreset({ scratch: opts.scratch, spec });
265
+ const installed = await PresetScratch.installNpm({ scratch: opts.scratch, spec });
279
266
 
280
267
  if (installed !== ExitCodes.OK) {
281
268
  return installed;
282
269
  }
283
270
 
284
- const result = locatePreset({ spec, root: opts.scratch });
271
+ const result = Preset.locate({ spec, root: opts.scratch });
285
272
 
286
273
  if (!result.ok) {
287
274
  return fail({ message: result.error });
@@ -289,7 +276,7 @@ const runCreate = async (opts: {
289
276
 
290
277
  located = result.located;
291
278
  } else {
292
- const result = locatePreset({ spec, root });
279
+ const result = Preset.locate({ spec, root });
293
280
 
294
281
  if (!result.ok) {
295
282
  return fail({ message: result.error });
@@ -298,7 +285,7 @@ const runCreate = async (opts: {
298
285
  located = result.located;
299
286
  }
300
287
 
301
- const rest = await resolveNames({
288
+ const rest = await ProjectNames.resolve({
302
289
  fields: appFields({ side: located.preset.side }),
303
290
  args: opts.args,
304
291
  interactive,
@@ -314,8 +301,8 @@ const runCreate = async (opts: {
314
301
  // The flag of the side this preset does not build still counts when given: it names a folder too.
315
302
  const otherFlag =
316
303
  SIDE_FIELDS[side === AppSides.BACKEND ? AppSides.FRONTEND : AppSides.BACKEND].flag;
317
- const otherFolder = readFlag({ args: opts.args, flag: otherFlag });
318
- const clash = findFolderClash({
304
+ const otherFolder = ProjectNames.readFlag({ args: opts.args, flag: otherFlag });
305
+ const clash = ProjectNames.findFolderClash({
319
306
  folders: [
320
307
  { flag: SIDE_FIELDS[side].flag, value: folder },
321
308
  ...(otherFolder === undefined ? [] : [{ flag: otherFlag, value: otherFolder }]),
@@ -327,7 +314,7 @@ const runCreate = async (opts: {
327
314
  return fail({ message: clash });
328
315
  }
329
316
 
330
- const overlaps = layoutOverlapProblems({
317
+ const overlaps = LayoutFolder.layoutOverlapProblems({
331
318
  layout: {
332
319
  [side]: folder,
333
320
  ...(shared === '' ? {} : { shared }),
@@ -343,14 +330,16 @@ const runCreate = async (opts: {
343
330
  }
344
331
 
345
332
  // Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
346
- const askingScope = flaggedScope.scope ?? (menusAvailable() ? askScope() : undefined);
333
+ const askingScope =
334
+ flaggedScope.scope ??
335
+ (TerminalCapability.menusAvailable() ? ProjectNames.askScope() : undefined);
347
336
  const scope = await askingScope;
348
337
 
349
338
  if (scope === null) {
350
339
  return fail({ message: ABORTED });
351
340
  }
352
341
 
353
- const warning = filePresetWarning({
342
+ const warning = WorkspaceDocs.filePresetWarning({
354
343
  spec,
355
344
  packageName: located.packageName,
356
345
  });
@@ -359,9 +348,9 @@ const runCreate = async (opts: {
359
348
  process.stderr.write(`${warning}\n`);
360
349
  }
361
350
 
362
- const confirmed = await confirmWrite({
351
+ const confirmed = await WritePlan.confirm({
363
352
  title: `Create ${project}`,
364
- lines: planLines({
353
+ lines: WritePlan.planLines({
365
354
  rows: [
366
355
  ['project', project],
367
356
  ['preset', `${located.packageName} ${located.packageVersion}`],
@@ -379,17 +368,17 @@ const runCreate = async (opts: {
379
368
  writeMonorepo({ root, project, spec, presetValue, located, folder, app, scope, shared });
380
369
 
381
370
  for (const step of [
382
- () => runBun({ cwd: root, args: ['install'], label: 'bun install' }),
383
- () => runGitInit({ cwd: root }),
371
+ () => SubProcess.runBun({ cwd: root, args: ['install'], label: 'bun install' }),
372
+ () => SubProcess.runGitInit({ cwd: root }),
384
373
  // The installed CLI syncs, so the project is wired to the version it pins.
385
374
  () =>
386
- runBun({
375
+ SubProcess.runBun({
387
376
  cwd: root,
388
377
  args: [join(root, 'node_modules', '.bin', 'vulcan'), 'sync'],
389
378
  label: 'vulcan sync',
390
379
  }),
391
380
  () =>
392
- runAppChecks({
381
+ AppChecks.run({
393
382
  root,
394
383
  appDirectory: join(root, folder, app),
395
384
  checks: located.preset.checks,
@@ -404,16 +393,22 @@ const runCreate = async (opts: {
404
393
 
405
394
  // The preset's own port: nothing else is in this project yet, so it is the one the app listens on.
406
395
  process.stderr.write(
407
- renderNext({
396
+ NextStep.render({
408
397
  done: 'Done.',
409
398
  command: `cd ${project} && make dev`,
410
399
  apps: [{ port: located.preset.devPort, urls: located.preset.urls }],
411
400
  }),
412
401
  );
413
- await offerProfile({ root });
402
+ await ProfilePrompt.offer({ root });
414
403
 
415
404
  return ExitCodes.OK;
416
405
  };
417
406
 
418
- export const createMonorepo = async (opts: { cwd: string; args: string[] }): Promise<number> =>
419
- withScratch({ root: opts.cwd, run: (scratch) => runCreate({ ...opts, scratch }) });
407
+ export class Monorepo {
408
+ static async create(opts: { cwd: string; args: string[] }): Promise<number> {
409
+ return PresetScratch.withScratch({
410
+ root: opts.cwd,
411
+ run: (scratch) => runCreate({ ...opts, scratch }),
412
+ });
413
+ }
414
+ }