@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,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
+ }
@@ -61,6 +61,7 @@ export class CreateFlags {
61
61
  static readonly API = '--api';
62
62
  static readonly NO_API = '--no-api';
63
63
  static readonly LIB = '--lib';
64
+ static readonly SHARED = '--shared';
64
65
  static readonly DIR = '--dir';
65
66
  static readonly SCOPE = '--scope';
66
67
  static readonly FULL = '--full';
@@ -0,0 +1,10 @@
1
+ import { ExitCodes } from '../../common/index.ts';
2
+
3
+ /** How `vulcan add` (an app or a library) reports a refusal: one line on stderr and the failure exit code. */
4
+ export class AddFailure {
5
+ static fail(opts: { message: string }): number {
6
+ process.stderr.write(`vulcan add: ${opts.message}\n`);
7
+
8
+ return ExitCodes.FAILURE;
9
+ }
10
+ }
@@ -1,2 +1,4 @@
1
1
  export * from './constants.ts';
2
+ export * from './failure.ts';
3
+ export * from './preset-path.ts';
2
4
  export * from './types.ts';
@@ -0,0 +1,11 @@
1
+ import { isAbsolute, relative, sep } from 'node:path';
2
+
3
+ /** Where a path a preset names may point: inside the preset's own package. */
4
+ export class PresetPath {
5
+ /** Whether `path` lies outside `root`, by its relative form. */
6
+ static escapes(opts: { root: string; path: string }): boolean {
7
+ const relativePath = relative(opts.root, opts.path);
8
+
9
+ return isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith(`..${sep}`);
10
+ }
11
+ }
@@ -1,5 +1,6 @@
1
1
  import type { ILayout } from '../../common/layout-folder.ts';
2
2
  import type { TConstValue } from '../../common/index.ts';
3
+ import type { TLibraryKind } from '../../config/common/index.ts';
3
4
  import type { AppSides, AppsBlockProblems } from './constants.ts';
4
5
 
5
6
  export type TAppSide = TConstValue<typeof AppSides>;
@@ -41,7 +42,7 @@ export type TNamesResult =
41
42
  | { ok: true; names: Record<string, string> }
42
43
  | { ok: false; error: string };
43
44
 
44
- export interface IPresetAtlasSource {
45
+ interface IPresetAtlasSource {
45
46
  name: string;
46
47
  repo: string;
47
48
  ref: string;
@@ -78,6 +79,8 @@ export interface ILocatedPreset {
78
79
  preset: IPreset;
79
80
  /** The lib preset file (`vulcan.presets.lib`), absolute and inside the package; absent when the preset makes apps only. */
80
81
  libFile?: string;
82
+ /** The shared preset file (`vulcan.presets.shared`), absolute and inside the package; absent when the preset has no shared kind. */
83
+ sharedFile?: string;
81
84
  /** The preset package's root directory. */
82
85
  packageRoot: string;
83
86
  packageName: string;
@@ -102,12 +105,14 @@ export interface IRecordedPreset {
102
105
  summary: string;
103
106
  /** The summary of the preset's lib kind; present when the preset can make a library. */
104
107
  lib?: string;
108
+ /** The summary of the preset's shared kind; present when the preset can make a shared package. */
109
+ shared?: string;
105
110
  }
106
111
 
107
112
  /** What `init` and `add` own in the config: the layout, the package list, the presets and the atlas sources. */
108
113
  export interface IAppsBlock {
109
114
  layout: ILayout;
110
- packages: { dir: string; name: string; path: string; kind?: 'lib' }[];
115
+ packages: { dir: string; name: string; path: string; kind?: 'lib'; presetKind?: TLibraryKind }[];
111
116
  /** Absent in a block written before presets were recorded. */
112
117
  presets?: IRecordedPreset[];
113
118
  sources: { name: string; repo: string; ref: string }[];
@@ -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,28 +192,30 @@ 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 presetValue = flagged ?? (await askPresetSpec({ recorded: [] }))?.trim();
202
+ const askingSpec = flagged === undefined ? PresetMenu.askSpec({ recorded: [] }) : undefined;
203
+ const typedSpec = await askingSpec;
204
+ const presetValue = flagged ?? typedSpec?.trim();
216
205
 
217
206
  if (presetValue === undefined || presetValue === '') {
218
207
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
219
208
  }
220
209
 
221
- const flaggedScope = readScope({ args: opts.args });
210
+ const flaggedScope = ProjectNames.readScope({ args: opts.args });
222
211
 
223
212
  if (!flaggedScope.ok) {
224
213
  return fail({ message: flaggedScope.error });
225
214
  }
226
215
 
227
- const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
216
+ const spec = Preset.parseSpec({ value: presetValue, cwd: opts.cwd });
228
217
  const interactive = process.stdin.isTTY === true;
229
- const first = await resolveNames({
218
+ const first = await ProjectNames.resolve({
230
219
  fields: [
231
220
  { key: 'project', flag: CreateFlags.PROJECT, question: 'Project name (the monorepo folder)' },
232
221
  ],
@@ -251,7 +240,7 @@ const runCreate = async (opts: {
251
240
 
252
241
  const isNpm = spec.packageName !== undefined;
253
242
 
254
- if (isNpm && isInstallSkipped()) {
243
+ if (isNpm && SubProcess.isInstallSkipped()) {
255
244
  return fail({ message: 'an npm preset needs an install - use file: in tests' });
256
245
  }
257
246
 
@@ -260,7 +249,7 @@ const runCreate = async (opts: {
260
249
  if (isNpm) {
261
250
  // Without a terminal nothing is asked, so a missing flag is refused before the network is used.
262
251
  if (!interactive) {
263
- const early = await resolveNames({
252
+ const early = await ProjectNames.resolve({
264
253
  fields: appFields({}),
265
254
  args: opts.args,
266
255
  interactive,
@@ -273,13 +262,13 @@ const runCreate = async (opts: {
273
262
  }
274
263
 
275
264
  // The side is known only once the package is read, so the preset is fetched before the rest is asked.
276
- const installed = await installNpmPreset({ scratch: opts.scratch, spec });
265
+ const installed = await PresetScratch.installNpm({ scratch: opts.scratch, spec });
277
266
 
278
267
  if (installed !== ExitCodes.OK) {
279
268
  return installed;
280
269
  }
281
270
 
282
- const result = locatePreset({ spec, root: opts.scratch });
271
+ const result = Preset.locate({ spec, root: opts.scratch });
283
272
 
284
273
  if (!result.ok) {
285
274
  return fail({ message: result.error });
@@ -287,7 +276,7 @@ const runCreate = async (opts: {
287
276
 
288
277
  located = result.located;
289
278
  } else {
290
- const result = locatePreset({ spec, root });
279
+ const result = Preset.locate({ spec, root });
291
280
 
292
281
  if (!result.ok) {
293
282
  return fail({ message: result.error });
@@ -296,7 +285,7 @@ const runCreate = async (opts: {
296
285
  located = result.located;
297
286
  }
298
287
 
299
- const rest = await resolveNames({
288
+ const rest = await ProjectNames.resolve({
300
289
  fields: appFields({ side: located.preset.side }),
301
290
  args: opts.args,
302
291
  interactive,
@@ -312,8 +301,8 @@ const runCreate = async (opts: {
312
301
  // The flag of the side this preset does not build still counts when given: it names a folder too.
313
302
  const otherFlag =
314
303
  SIDE_FIELDS[side === AppSides.BACKEND ? AppSides.FRONTEND : AppSides.BACKEND].flag;
315
- const otherFolder = readFlag({ args: opts.args, flag: otherFlag });
316
- const clash = findFolderClash({
304
+ const otherFolder = ProjectNames.readFlag({ args: opts.args, flag: otherFlag });
305
+ const clash = ProjectNames.findFolderClash({
317
306
  folders: [
318
307
  { flag: SIDE_FIELDS[side].flag, value: folder },
319
308
  ...(otherFolder === undefined ? [] : [{ flag: otherFlag, value: otherFolder }]),
@@ -325,7 +314,7 @@ const runCreate = async (opts: {
325
314
  return fail({ message: clash });
326
315
  }
327
316
 
328
- const overlaps = layoutOverlapProblems({
317
+ const overlaps = LayoutFolder.layoutOverlapProblems({
329
318
  layout: {
330
319
  [side]: folder,
331
320
  ...(shared === '' ? {} : { shared }),
@@ -341,13 +330,16 @@ const runCreate = async (opts: {
341
330
  }
342
331
 
343
332
  // Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
344
- const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
333
+ const askingScope =
334
+ flaggedScope.scope ??
335
+ (TerminalCapability.menusAvailable() ? ProjectNames.askScope() : undefined);
336
+ const scope = await askingScope;
345
337
 
346
338
  if (scope === null) {
347
339
  return fail({ message: ABORTED });
348
340
  }
349
341
 
350
- const warning = filePresetWarning({
342
+ const warning = WorkspaceDocs.filePresetWarning({
351
343
  spec,
352
344
  packageName: located.packageName,
353
345
  });
@@ -356,9 +348,9 @@ const runCreate = async (opts: {
356
348
  process.stderr.write(`${warning}\n`);
357
349
  }
358
350
 
359
- const confirmed = await confirmWrite({
351
+ const confirmed = await WritePlan.confirm({
360
352
  title: `Create ${project}`,
361
- lines: planLines({
353
+ lines: WritePlan.planLines({
362
354
  rows: [
363
355
  ['project', project],
364
356
  ['preset', `${located.packageName} ${located.packageVersion}`],
@@ -376,17 +368,17 @@ const runCreate = async (opts: {
376
368
  writeMonorepo({ root, project, spec, presetValue, located, folder, app, scope, shared });
377
369
 
378
370
  for (const step of [
379
- () => runBun({ cwd: root, args: ['install'], label: 'bun install' }),
380
- () => runGitInit({ cwd: root }),
371
+ () => SubProcess.runBun({ cwd: root, args: ['install'], label: 'bun install' }),
372
+ () => SubProcess.runGitInit({ cwd: root }),
381
373
  // The installed CLI syncs, so the project is wired to the version it pins.
382
374
  () =>
383
- runBun({
375
+ SubProcess.runBun({
384
376
  cwd: root,
385
377
  args: [join(root, 'node_modules', '.bin', 'vulcan'), 'sync'],
386
378
  label: 'vulcan sync',
387
379
  }),
388
380
  () =>
389
- runAppChecks({
381
+ AppChecks.run({
390
382
  root,
391
383
  appDirectory: join(root, folder, app),
392
384
  checks: located.preset.checks,
@@ -401,16 +393,22 @@ const runCreate = async (opts: {
401
393
 
402
394
  // The preset's own port: nothing else is in this project yet, so it is the one the app listens on.
403
395
  process.stderr.write(
404
- renderNext({
396
+ NextStep.render({
405
397
  done: 'Done.',
406
398
  command: `cd ${project} && make dev`,
407
399
  apps: [{ port: located.preset.devPort, urls: located.preset.urls }],
408
400
  }),
409
401
  );
410
- await offerProfile({ root });
402
+ await ProfilePrompt.offer({ root });
411
403
 
412
404
  return ExitCodes.OK;
413
405
  };
414
406
 
415
- export const createMonorepo = async (opts: { cwd: string; args: string[] }): Promise<number> =>
416
- 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
+ }