@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,8 +1,10 @@
1
1
  import { relative, resolve } from 'node:path';
2
- import { coversFolder } from '../init/index.ts';
3
- import { PackageKinds } from '../config/index.ts';
2
+ import { RecordValue } from '../common/record.ts';
3
+ import { ProjectScaffold } from '../init/index.ts';
4
+ import { LibraryKinds, PackageKinds } from '../config/index.ts';
5
+ import type { TLibraryKind } from '../config/index.ts';
4
6
  import { AppsBlockProblems, CreateConstants } from './common/index.ts';
5
- import { renderManifestJson } from './manifest-json.ts';
7
+ import { ManifestJson } from './manifest-json.ts';
6
8
  import type {
7
9
  IApp,
8
10
  IAppsBlock,
@@ -18,33 +20,8 @@ const ENV_PORT = /^[A-Z0-9_]*PORT=(\d+)\s*$/m;
18
20
  /** A newline inside a list item or a paragraph would split it. */
19
21
  const oneLine = (opts: { text: string }): string => opts.text.replace(/\s+/g, ' ').trim();
20
22
 
21
- export const renderRootManifest = (opts: {
22
- project: string;
23
- workspaces: string[];
24
- catalog: Record<string, string>;
25
- vulcanVersion: string;
26
- }): string =>
27
- renderManifestJson({
28
- value: {
29
- name: opts.project,
30
- private: true,
31
- workspaces: { packages: opts.workspaces, catalog: opts.catalog },
32
- scripts: { dev: "bun run --filter '*' server:dev" },
33
- devDependencies: { '@venizia/vulcan': opts.vulcanVersion },
34
- },
35
- });
36
-
37
- /** A version the monorepo already pins wins, so every app shares one copy. */
38
- export const mergeCatalog = (opts: {
39
- catalog: Record<string, string>;
40
- additions: Record<string, string>;
41
- }): Record<string, string> => ({ ...opts.additions, ...opts.catalog });
42
-
43
- const isRecord = (value: unknown): value is Record<string, unknown> =>
44
- typeof value === 'object' && value !== null && !Array.isArray(value);
45
-
46
23
  const toStringRecord = (opts: { value: unknown }): Record<string, string> =>
47
- isRecord(opts.value)
24
+ RecordValue.isRecord(opts.value)
48
25
  ? Object.fromEntries(
49
26
  Object.entries(opts.value).filter(
50
27
  (entry): entry is [string, string] => typeof entry[1] === 'string',
@@ -52,165 +29,204 @@ const toStringRecord = (opts: { value: unknown }): Record<string, string> =>
52
29
  )
53
30
  : {};
54
31
 
55
- /** The catalog of a root manifest wherever it lives: top level, or inside object-form workspaces. */
56
- export const readCatalog = (opts: {
57
- manifest: Record<string, unknown>;
58
- }): Record<string, string> => ({
59
- ...(isRecord(opts.manifest.workspaces)
60
- ? toStringRecord({ value: opts.manifest.workspaces.catalog })
61
- : {}),
62
- ...toStringRecord({ value: opts.manifest.catalog }),
63
- });
64
-
65
- /**
66
- * The root manifest with the new folder and the preset's catalog entries added, and nothing else
67
- * changed: an array of workspaces stays an array, and the catalog stays where the project keeps it
68
- * (top level, or inside object-form workspaces; an array has no room for one, so top level).
69
- */
70
- export const planRootManifest = (opts: {
71
- manifest: Record<string, unknown>;
72
- globs: string[];
73
- folder: string;
74
- additions: Record<string, string>;
75
- }): Record<string, unknown> => {
76
- const { manifest, folder } = opts;
77
- const { workspaces } = manifest;
78
- const globs = coversFolder({ globs: opts.globs, folder })
79
- ? opts.globs
80
- : [...opts.globs, `${folder}/*`];
81
- const existing = readCatalog({ manifest });
82
- const fresh = Object.fromEntries(
83
- Object.entries(opts.additions).filter(([name]) => existing[name] === undefined),
32
+ const toCatalog = (opts: { dependencies: Record<string, string> }): Record<string, string> =>
33
+ Object.fromEntries(
34
+ Object.keys(opts.dependencies)
35
+ .sort()
36
+ .map((name) => [name, 'catalog:']),
84
37
  );
85
- const isTopLevel = isRecord(manifest.catalog) || Array.isArray(workspaces);
86
38
 
87
- if (isTopLevel) {
39
+ export class WorkspaceManifest {
40
+ static renderRoot(opts: {
41
+ project: string;
42
+ workspaces: string[];
43
+ catalog: Record<string, string>;
44
+ vulcanVersion: string;
45
+ }): string {
46
+ return ManifestJson.render({
47
+ value: {
48
+ name: opts.project,
49
+ private: true,
50
+ workspaces: { packages: opts.workspaces, catalog: opts.catalog },
51
+ scripts: { dev: "bun run --filter '*' server:dev" },
52
+ devDependencies: { '@venizia/vulcan': opts.vulcanVersion },
53
+ },
54
+ });
55
+ }
56
+
57
+ /** A version the monorepo already pins wins, so every app shares one copy. */
58
+ static mergeCatalog(opts: {
59
+ catalog: Record<string, string>;
60
+ additions: Record<string, string>;
61
+ }): Record<string, string> {
62
+ return { ...opts.additions, ...opts.catalog };
63
+ }
64
+
65
+ /** The catalog of a root manifest wherever it lives: top level, or inside object-form workspaces. */
66
+ static readCatalog(opts: { manifest: Record<string, unknown> }): Record<string, string> {
88
67
  return {
89
- ...manifest,
90
- workspaces: Array.isArray(workspaces)
91
- ? globs
92
- : { ...(isRecord(workspaces) ? workspaces : {}), packages: globs },
93
- catalog: mergeCatalog({
94
- catalog: toStringRecord({ value: manifest.catalog }),
95
- additions: fresh,
96
- }),
68
+ ...(RecordValue.isRecord(opts.manifest.workspaces)
69
+ ? toStringRecord({ value: opts.manifest.workspaces.catalog })
70
+ : {}),
71
+ ...toStringRecord({ value: opts.manifest.catalog }),
97
72
  };
98
73
  }
99
74
 
100
- const inside = isRecord(workspaces) ? workspaces : {};
101
-
102
- return {
103
- ...manifest,
104
- workspaces: {
105
- ...inside,
106
- packages: globs,
107
- catalog: mergeCatalog({
108
- catalog: toStringRecord({ value: inside.catalog }),
109
- additions: fresh,
110
- }),
111
- },
112
- };
113
- };
114
-
115
- /**
116
- * The catalog value is read as the version the install resolves to, compared with the preset's
117
- * range by semver order (what Bun.semver implements). A prerelease sorts before its release, so
118
- * `^0.2.2-5` does not meet `^0.2.2`: it is refused, never rounded up. A value that is not a plain
119
- * version (`workspace:*`, a git URL, a range) cannot be compared, so it is refused as well.
120
- */
121
- export const checkPeers = (opts: {
122
- catalog: Record<string, string>;
123
- peers: Record<string, string>;
124
- }): string | undefined => {
125
- for (const [name, range] of Object.entries(opts.peers)) {
126
- const pinned = opts.catalog[name];
127
-
128
- if (pinned === undefined) {
129
- continue;
75
+ /**
76
+ * The root manifest with the new folder and the preset's catalog entries added, and nothing else
77
+ * changed: an array of workspaces stays an array, and the catalog stays where the project keeps it
78
+ * (top level, or inside object-form workspaces; an array has no room for one, so top level).
79
+ */
80
+ static planRoot(opts: {
81
+ manifest: Record<string, unknown>;
82
+ globs: string[];
83
+ folder: string;
84
+ additions: Record<string, string>;
85
+ }): Record<string, unknown> {
86
+ const { manifest, folder } = opts;
87
+ const { workspaces } = manifest;
88
+ const globs = ProjectScaffold.coversFolder({ globs: opts.globs, folder })
89
+ ? opts.globs
90
+ : [...opts.globs, `${folder}/*`];
91
+ const existing = WorkspaceManifest.readCatalog({ manifest });
92
+ const fresh = Object.fromEntries(
93
+ Object.entries(opts.additions).filter(([name]) => existing[name] === undefined),
94
+ );
95
+ const isTopLevel = RecordValue.isRecord(manifest.catalog) || Array.isArray(workspaces);
96
+
97
+ if (isTopLevel) {
98
+ return {
99
+ ...manifest,
100
+ workspaces: Array.isArray(workspaces)
101
+ ? globs
102
+ : { ...(RecordValue.isRecord(workspaces) ? workspaces : {}), packages: globs },
103
+ catalog: WorkspaceManifest.mergeCatalog({
104
+ catalog: toStringRecord({ value: manifest.catalog }),
105
+ additions: fresh,
106
+ }),
107
+ };
130
108
  }
131
109
 
132
- const version = pinned.replace(/^[\^~]/, '');
110
+ const inside = RecordValue.isRecord(workspaces) ? workspaces : {};
133
111
 
134
- if (!CreateConstants.VERSION_PATTERN.test(version)) {
135
- return `the monorepo pins ${name} ${pinned}, which is not a version vulcan can compare with the preset's ${range} - pin a version in the catalog first`;
136
- }
112
+ return {
113
+ ...manifest,
114
+ workspaces: {
115
+ ...inside,
116
+ packages: globs,
117
+ catalog: WorkspaceManifest.mergeCatalog({
118
+ catalog: toStringRecord({ value: inside.catalog }),
119
+ additions: fresh,
120
+ }),
121
+ },
122
+ };
123
+ }
137
124
 
138
- if (!Bun.semver.satisfies(version, range)) {
139
- return CreateConstants.PRERELEASE_PATTERN.test(version)
140
- ? `the monorepo pins ${name} ${pinned}, a prerelease, which does not meet the preset's ${range} (a prerelease sorts before its release) - pin a release in the catalog first`
141
- : `the monorepo pins ${name} ${pinned}, but the preset needs ${range} - move the catalog first`;
125
+ /**
126
+ * The catalog value is read as the version the install resolves to, compared with the preset's
127
+ * range by semver order (what Bun.semver implements). A prerelease sorts before its release, so
128
+ * `^0.2.2-5` does not meet `^0.2.2`: it is refused, never rounded up. A value that is not a plain
129
+ * version (`workspace:*`, a git URL, a range) cannot be compared, so it is refused as well.
130
+ */
131
+ static checkPeers(opts: {
132
+ catalog: Record<string, string>;
133
+ peers: Record<string, string>;
134
+ /** What the preset itself lists, so the catalog `init` wrote from it is not held to its own range. */
135
+ presetVersions?: Pick<IPreset, 'dependencies' | 'devDependencies'>;
136
+ }): string | undefined {
137
+ for (const [name, range] of Object.entries(opts.peers)) {
138
+ const pinned = opts.catalog[name];
139
+
140
+ if (pinned === undefined) {
141
+ continue;
142
+ }
143
+
144
+ // A pin equal to the version this preset lists is satisfied by construction (`init` wrote it
145
+ // from the preset); only a pin set by something else is compared with the range.
146
+ if (
147
+ pinned === opts.presetVersions?.dependencies[name] ||
148
+ pinned === opts.presetVersions?.devDependencies[name]
149
+ ) {
150
+ continue;
151
+ }
152
+
153
+ const version = pinned.replace(/^[\^~]/, '');
154
+
155
+ if (!CreateConstants.VERSION_PATTERN.test(version)) {
156
+ return `the monorepo pins ${name} ${pinned}, which is not a version vulcan can compare with the preset's ${range} - pin a version in the catalog first`;
157
+ }
158
+
159
+ if (!Bun.semver.satisfies(version, range)) {
160
+ return CreateConstants.PRERELEASE_PATTERN.test(version)
161
+ ? `the monorepo pins ${name} ${pinned}, a prerelease, which does not meet the preset's ${range} (a prerelease sorts before its release) - pin a release in the catalog first`
162
+ : `the monorepo pins ${name} ${pinned}, but the preset needs ${range} - move the catalog first`;
163
+ }
142
164
  }
143
- }
144
165
 
145
- return undefined;
146
- };
166
+ return undefined;
167
+ }
147
168
 
148
- const toCatalog = (opts: { dependencies: Record<string, string> }): Record<string, string> =>
149
- Object.fromEntries(
150
- Object.keys(opts.dependencies)
151
- .sort()
152
- .map((name) => [name, 'catalog:']),
153
- );
169
+ static renderApp(opts: {
170
+ app: string;
171
+ /** The package name when it is not the app name: `@scope/<app>`. */
172
+ name?: string;
173
+ preset: IPreset;
174
+ presetPackage: { name: string; version: string };
175
+ }): string {
176
+ return ManifestJson.render({
177
+ value: {
178
+ name: opts.name ?? opts.app,
179
+ version: '0.0.0',
180
+ private: true,
181
+ // The preset's own text: no token is replaced here, a path pattern has no use for one.
182
+ ...(Object.keys(opts.preset.imports).length === 0 ? {} : { imports: opts.preset.imports }),
183
+ scripts: opts.preset.scripts,
184
+ dependencies: toCatalog({
185
+ dependencies: {
186
+ ...opts.preset.dependencies,
187
+ [opts.presetPackage.name]: opts.presetPackage.version,
188
+ },
189
+ }),
190
+ devDependencies: toCatalog({ dependencies: opts.preset.devDependencies }),
191
+ // What `add` prints later: this app's urls, since the preset is not at hand then.
192
+ ...(opts.preset.urls.length === 0 ? {} : { vulcan: { urls: opts.preset.urls } }),
193
+ },
194
+ });
195
+ }
154
196
 
155
- export const renderAppManifest = (opts: {
156
- app: string;
157
- /** The package name when it is not the app name: `@scope/<app>`. */
158
- name?: string;
159
- preset: IPreset;
160
- presetPackage: { name: string; version: string };
161
- }): string =>
162
- renderManifestJson({
163
- value: {
164
- name: opts.name ?? opts.app,
165
- version: '0.0.0',
166
- private: true,
167
- // The preset's own text: no token is replaced here, a path pattern has no use for one.
168
- ...(Object.keys(opts.preset.imports).length === 0 ? {} : { imports: opts.preset.imports }),
169
- scripts: opts.preset.scripts,
170
- dependencies: toCatalog({
171
- dependencies: {
172
- ...opts.preset.dependencies,
173
- [opts.presetPackage.name]: opts.presetPackage.version,
174
- },
175
- }),
176
- devDependencies: toCatalog({ dependencies: opts.preset.devDependencies }),
177
- // What `add` prints later: this app's urls, since the preset is not at hand then.
178
- ...(opts.preset.urls.length === 0 ? {} : { vulcan: { urls: opts.preset.urls } }),
179
- },
180
- });
181
-
182
- /** A library's package.json: generated fields first, then what the lib preset passes through. */
183
- export const renderLibManifest = (opts: {
184
- name: string;
185
- lib: {
186
- scripts: Record<string, string>;
187
- dependencies: Record<string, string>;
188
- devDependencies: Record<string, string>;
189
- peerDependencies: Record<string, string>;
190
- imports: Record<string, string>;
191
- exports: Record<string, unknown>;
192
- packageFields: Record<string, unknown>;
193
- };
194
- }): string => {
195
- const { lib } = opts;
196
- const section = (value: Record<string, unknown>, key: string): Record<string, unknown> =>
197
- Object.keys(value).length === 0 ? {} : { [key]: value };
198
-
199
- return renderManifestJson({
200
- value: {
201
- name: opts.name,
202
- version: '0.0.0',
203
- private: true,
204
- ...lib.packageFields,
205
- ...section(lib.exports, 'exports'),
206
- ...section(lib.imports, 'imports'),
207
- ...section(lib.scripts, 'scripts'),
208
- ...section(toCatalog({ dependencies: lib.dependencies }), 'dependencies'),
209
- ...section(toCatalog({ dependencies: lib.devDependencies }), 'devDependencies'),
210
- ...section(toCatalog({ dependencies: lib.peerDependencies }), 'peerDependencies'),
211
- },
212
- });
213
- };
197
+ /** A library's package.json: generated fields first, then what the lib preset passes through. */
198
+ static renderLib(opts: {
199
+ name: string;
200
+ lib: {
201
+ scripts: Record<string, string>;
202
+ dependencies: Record<string, string>;
203
+ devDependencies: Record<string, string>;
204
+ peerDependencies: Record<string, string>;
205
+ imports: Record<string, string>;
206
+ exports: Record<string, unknown>;
207
+ packageFields: Record<string, unknown>;
208
+ };
209
+ }): string {
210
+ const { lib } = opts;
211
+ const section = (value: Record<string, unknown>, key: string): Record<string, unknown> =>
212
+ Object.keys(value).length === 0 ? {} : { [key]: value };
213
+
214
+ return ManifestJson.render({
215
+ value: {
216
+ name: opts.name,
217
+ version: '0.0.0',
218
+ private: true,
219
+ ...lib.packageFields,
220
+ ...section(lib.exports, 'exports'),
221
+ ...section(lib.imports, 'imports'),
222
+ ...section(lib.scripts, 'scripts'),
223
+ ...section(toCatalog({ dependencies: lib.dependencies }), 'dependencies'),
224
+ ...section(toCatalog({ dependencies: lib.devDependencies }), 'devDependencies'),
225
+ ...section(toCatalog({ dependencies: lib.peerDependencies }), 'peerDependencies'),
226
+ },
227
+ });
228
+ }
229
+ }
214
230
 
215
231
  /** The atlas lookups a package of one kind depends on: what a summary page cannot hold. */
216
232
  const ATLAS_LOOKUPS: Record<TAppSide | typeof PackageKinds.LIB, [string, string][]> = {
@@ -225,7 +241,7 @@ const ATLAS_LOOKUPS: Record<TAppSide | typeof PackageKinds.LIB, [string, string]
225
241
  ['How a page or a resource is added', '`search` "page resource", then `get`'],
226
242
  ['How the app reads data from its backend', '`search` "data provider"'],
227
243
  ],
228
- lib: [['How a shared package exposes its API', '`search` "shared package exports", then `get`']],
244
+ lib: [['How a library exposes its API', '`search` "library exports", then `get`']],
229
245
  };
230
246
 
231
247
  /** The note and the table that turn a package page into a pointer at atlas, for its kind. */
@@ -243,276 +259,285 @@ const renderAtlasLookups = (opts: { kind: TAppSide | typeof PackageKinds.LIB }):
243
259
  '',
244
260
  ];
245
261
 
246
- export const renderLibConcept = (opts: {
247
- name: string;
248
- path: string;
249
- summary: string;
250
- presetPackage: string;
251
- }): string =>
252
- [
253
- '---',
254
- 'type: Package',
255
- `title: ${opts.name}`,
256
- `description: ${JSON.stringify(opts.summary)}`,
257
- `resource: ${opts.path}`,
258
- 'tags: [packages, library]',
259
- '---',
260
- '',
261
- `# ${opts.name}`,
262
- '',
263
- `The shared package at \`${opts.path}\`, created from the ${opts.presetPackage} preset (lib kind). ${oneLine({ text: opts.summary })}`,
264
- '',
265
- ...renderAtlasLookups({ kind: PackageKinds.LIB }),
266
- ].join('\n');
267
-
268
- /**
269
- * The block is JSON that `add` reads back with `JSON.parse`, so `bun fmt` must not rewrite it
270
- * (it would drop the key quotes): `prettier-ignore` is honoured by both of its flavors.
271
- */
272
- export const renderAppsBlock = (opts: { block: IAppsBlock }): string =>
273
- [
274
- CreateConstants.APPS_BLOCK_START,
275
- '// prettier-ignore',
276
- `const apps = ${JSON.stringify(opts.block, null, 2)};`,
277
- CreateConstants.APPS_BLOCK_END,
278
- ].join('\n');
279
-
280
- export const renderVulcanConfig = (opts: { project: string; block: IAppsBlock }): string =>
281
- [
282
- "import type { VulcanConfig } from '@venizia/vulcan';",
283
- '',
284
- renderAppsBlock({ block: opts.block }),
285
- '',
286
- 'export default {',
287
- ` name: '${opts.project}',`,
288
- " rules: { 'V-W-01': 'on-user-word' },",
289
- ' layout: apps.layout,',
290
- ' packages: apps.packages,',
291
- ' presets: apps.presets,',
292
- ' atlas: { sources: apps.sources },',
293
- '} satisfies VulcanConfig;',
294
- '',
295
- ].join('\n');
296
-
297
- /**
298
- * What `--preset` was given, kept so it can be typed again from the project root: a package spec as
299
- * typed, a `file:` path made relative to the project.
300
- */
301
- export const presetSpecOf = (opts: { value: string; root: string; cwd: string }): string => {
302
- const prefix = CreateConstants.PRESET_FILE_PREFIX;
303
-
304
- if (!opts.value.startsWith(prefix)) {
305
- return opts.value;
306
- }
307
-
308
- const target = resolve(opts.cwd, opts.value.slice(prefix.length));
309
-
310
- return `${prefix}${relative(opts.root, target) || '.'}`;
311
- };
312
-
313
- /** The block with this preset recorded: once per spec, its side and summary refreshed. */
314
- export const recordPreset = (opts: { block: IAppsBlock; preset: IRecordedPreset }): IAppsBlock => {
315
- const others = (opts.block.presets ?? []).filter((item) => item.spec !== opts.preset.spec);
316
- const index = (opts.block.presets ?? []).findIndex((item) => item.spec === opts.preset.spec);
317
- const presets =
318
- index === -1
319
- ? [...others, opts.preset]
320
- : (opts.block.presets ?? []).map((item, at) => (at === index ? opts.preset : item));
321
-
322
- return { ...opts.block, presets };
323
- };
324
-
325
- /** Only the text between the markers is rewritten; undefined when the user edited them away. */
326
- export const replaceAppsBlock = (opts: {
327
- source: string;
328
- block: IAppsBlock;
329
- }): string | undefined => {
330
- const start = opts.source.indexOf(CreateConstants.APPS_BLOCK_START);
331
- const end = opts.source.indexOf(CreateConstants.APPS_BLOCK_END);
332
-
333
- if (start === -1 || end === -1 || end < start) {
334
- return undefined;
335
- }
336
-
337
- const before = opts.source.slice(0, start);
338
- const after = opts.source.slice(end + CreateConstants.APPS_BLOCK_END.length);
339
-
340
- return `${before}${renderAppsBlock({ block: opts.block })}${after}`;
341
- };
262
+ const renderAppBullet = (opts: { app: { name: string; summary: string } }): string =>
263
+ `- [${opts.app.name}](packages/${opts.app.name}.md) - ${oneLine({ text: opts.app.summary })}`;
342
264
 
343
265
  const hasStrings = (opts: { value: unknown; keys: string[] }): boolean => {
344
266
  const { value } = opts;
345
267
 
346
- return isRecord(value) && opts.keys.every((key) => typeof value[key] === 'string');
268
+ return RecordValue.isRecord(value) && opts.keys.every((key) => typeof value[key] === 'string');
347
269
  };
348
270
 
349
271
  const isRecordedPreset = (value: unknown): boolean =>
350
272
  hasStrings({ value, keys: ['spec', 'side', 'summary'] }) &&
351
- isRecord(value) &&
273
+ RecordValue.isRecord(value) &&
352
274
  (value.side === 'backend' || value.side === 'frontend') &&
353
- (value.lib === undefined || typeof value.lib === 'string');
275
+ (value.lib === undefined || typeof value.lib === 'string') &&
276
+ (value.shared === undefined || typeof value.shared === 'string');
354
277
 
355
278
  const isAppsBlock = (value: unknown): value is IAppsBlock =>
356
- isRecord(value) &&
279
+ RecordValue.isRecord(value) &&
357
280
  (value.presets === undefined ||
358
281
  (Array.isArray(value.presets) && value.presets.every((entry) => isRecordedPreset(entry)))) &&
359
- isRecord(value.layout) &&
282
+ RecordValue.isRecord(value.layout) &&
360
283
  Object.values(value.layout).every(
361
284
  (folders) =>
362
285
  typeof folders === 'string' ||
363
286
  (Array.isArray(folders) && folders.every((folder) => typeof folder === 'string')),
364
287
  ) &&
365
288
  Array.isArray(value.packages) &&
366
- value.packages.every((entry) => hasStrings({ value: entry, keys: ['dir', 'name', 'path'] })) &&
289
+ value.packages.every(
290
+ (entry) =>
291
+ hasStrings({ value: entry, keys: ['dir', 'name', 'path'] }) &&
292
+ RecordValue.isRecord(entry) &&
293
+ (entry.presetKind === undefined ||
294
+ (typeof entry.presetKind === 'string' && LibraryKinds.isValid(entry.presetKind))),
295
+ ) &&
367
296
  Array.isArray(value.sources) &&
368
297
  value.sources.every((entry) => hasStrings({ value: entry, keys: ['name', 'repo', 'ref'] }));
369
298
 
370
- export type TAppsBlockResult =
371
- | { ok: true; block: IAppsBlock }
372
- | { ok: false; reason: TAppsBlockProblem };
373
-
374
299
  const APPS_DECLARATION = 'const apps = ';
375
300
 
376
- /** What the markers hold now, so `add` extends it instead of rebuilding it from the resolved config. */
377
- export const parseAppsBlock = (opts: { source: string }): TAppsBlockResult => {
378
- const start = opts.source.indexOf(CreateConstants.APPS_BLOCK_START);
379
- const end = opts.source.indexOf(CreateConstants.APPS_BLOCK_END);
301
+ const APPS_HEADING = /^## Apps\s*$/;
302
+
303
+ const ANY_HEADING = /^#{1,2}\s/;
380
304
 
381
- if (start === -1 || end === -1 || end < start) {
382
- return { ok: false, reason: AppsBlockProblems.MISSING };
305
+ export class AppsBlock {
306
+ /**
307
+ * The block is JSON that `add` reads back with `JSON.parse`, so `bun fmt` must not rewrite it
308
+ * (it would drop the key quotes): `prettier-ignore` is honoured by both of its flavors.
309
+ */
310
+ static render(opts: { block: IAppsBlock }): string {
311
+ return [
312
+ CreateConstants.APPS_BLOCK_START,
313
+ '// prettier-ignore',
314
+ `const apps = ${JSON.stringify(opts.block, null, 2)};`,
315
+ CreateConstants.APPS_BLOCK_END,
316
+ ].join('\n');
383
317
  }
384
318
 
385
- const body = opts.source.slice(start + CreateConstants.APPS_BLOCK_START.length, end);
386
- const declaration = body.indexOf(APPS_DECLARATION);
319
+ /** Only the text between the markers is rewritten; undefined when the user edited them away. */
320
+ static replace(opts: { source: string; block: IAppsBlock }): string | undefined {
321
+ const start = opts.source.indexOf(CreateConstants.APPS_BLOCK_START);
322
+ const end = opts.source.indexOf(CreateConstants.APPS_BLOCK_END);
323
+
324
+ if (start === -1 || end === -1 || end < start) {
325
+ return undefined;
326
+ }
327
+
328
+ const before = opts.source.slice(0, start);
329
+ const after = opts.source.slice(end + CreateConstants.APPS_BLOCK_END.length);
387
330
 
388
- if (declaration === -1) {
389
- return { ok: false, reason: AppsBlockProblems.INVALID };
331
+ return `${before}${AppsBlock.render({ block: opts.block })}${after}`;
390
332
  }
391
333
 
392
- try {
393
- const parsed: unknown = JSON.parse(
394
- body
395
- .slice(declaration + APPS_DECLARATION.length)
396
- .trim()
397
- .replace(/;$/, ''),
398
- );
334
+ /** What the markers hold now, so `add` extends it instead of rebuilding it from the resolved config. */
335
+ static parse(opts: { source: string }): TAppsBlockResult {
336
+ const start = opts.source.indexOf(CreateConstants.APPS_BLOCK_START);
337
+ const end = opts.source.indexOf(CreateConstants.APPS_BLOCK_END);
399
338
 
400
- return isAppsBlock(parsed)
401
- ? { ok: true, block: parsed }
402
- : { ok: false, reason: AppsBlockProblems.INVALID };
403
- } catch (error) {
404
- console.error(
405
- `[parseAppsBlock] the vulcan:apps block is not JSON | ${error instanceof Error ? error.message : String(error)}`,
406
- );
339
+ if (start === -1 || end === -1 || end < start) {
340
+ return { ok: false, reason: AppsBlockProblems.MISSING };
341
+ }
342
+
343
+ const body = opts.source.slice(start + CreateConstants.APPS_BLOCK_START.length, end);
344
+ const declaration = body.indexOf(APPS_DECLARATION);
407
345
 
408
- return { ok: false, reason: AppsBlockProblems.INVALID };
346
+ if (declaration === -1) {
347
+ return { ok: false, reason: AppsBlockProblems.INVALID };
348
+ }
349
+
350
+ try {
351
+ const parsed: unknown = JSON.parse(
352
+ body
353
+ .slice(declaration + APPS_DECLARATION.length)
354
+ .trim()
355
+ .replace(/;$/, ''),
356
+ );
357
+
358
+ return isAppsBlock(parsed)
359
+ ? { ok: true, block: parsed }
360
+ : { ok: false, reason: AppsBlockProblems.INVALID };
361
+ } catch (error) {
362
+ console.error(
363
+ `[AppsBlock.parse] the vulcan:apps block is not JSON | ${error instanceof Error ? error.message : String(error)}`,
364
+ );
365
+
366
+ return { ok: false, reason: AppsBlockProblems.INVALID };
367
+ }
409
368
  }
410
- };
411
369
 
412
- const APPS_HEADING = /^## Apps\s*$/;
413
- const ANY_HEADING = /^#{1,2}\s/;
370
+ /**
371
+ * One bullet for one app, after the last bullet under `## Apps` (a section is added when the index
372
+ * has none). Every other byte of the index is the user's and is returned as it was.
373
+ */
374
+ static addBullet(opts: { source: string; app: { name: string; summary: string } }): string {
375
+ if (opts.source.includes(`](packages/${opts.app.name}.md)`)) {
376
+ return opts.source;
377
+ }
414
378
 
415
- const renderAppBullet = (opts: { app: { name: string; summary: string } }): string =>
416
- `- [${opts.app.name}](packages/${opts.app.name}.md) - ${oneLine({ text: opts.app.summary })}`;
379
+ const eol = opts.source.includes('\r\n') ? '\r\n' : '\n';
380
+ const bullet = renderAppBullet({ app: opts.app });
381
+ const lines = opts.source.split(eol);
382
+ const heading = lines.findIndex((line) => APPS_HEADING.test(line));
383
+
384
+ if (heading === -1) {
385
+ const kept = opts.source.trimEnd();
386
+
387
+ return `${kept === '' ? '' : `${kept}${eol}${eol}`}## Apps${eol}${eol}${bullet}${eol}`;
388
+ }
389
+
390
+ const next = lines.findIndex((line, index) => index > heading && ANY_HEADING.test(line));
391
+ const section = lines.slice(heading + 1, next === -1 ? lines.length : next);
392
+ const last = section.findLastIndex((line) => line.startsWith('- ['));
417
393
 
418
- /**
419
- * One bullet for one app, after the last bullet under `## Apps` (a section is added when the index
420
- * has none). Every other byte of the index is the user's and is returned as it was.
421
- */
422
- export const addAppBullet = (opts: {
423
- source: string;
424
- app: { name: string; summary: string };
425
- }): string => {
426
- if (opts.source.includes(`](packages/${opts.app.name}.md)`)) {
427
- return opts.source;
394
+ if (last === -1) {
395
+ lines.splice(heading, 1, lines[heading] ?? '', '', bullet);
396
+ } else {
397
+ lines.splice(heading + 1 + last + 1, 0, bullet);
398
+ }
399
+
400
+ return lines.join(eol);
401
+ }
402
+ }
403
+
404
+ export class WorkspaceDocs {
405
+ static renderLibConcept(opts: {
406
+ name: string;
407
+ path: string;
408
+ summary: string;
409
+ presetPackage: string;
410
+ /** Which preset kind made the package; `lib` when absent. */
411
+ kind?: TLibraryKind;
412
+ }): string {
413
+ return [
414
+ '---',
415
+ 'type: Package',
416
+ `title: ${opts.name}`,
417
+ `description: ${JSON.stringify(opts.summary)}`,
418
+ `resource: ${opts.path}`,
419
+ 'tags: [packages, library]',
420
+ '---',
421
+ '',
422
+ `# ${opts.name}`,
423
+ '',
424
+ `The ${opts.kind === LibraryKinds.SHARED ? 'side-neutral package' : 'library'} at \`${opts.path}\`, created from the ${opts.presetPackage} preset (${opts.kind ?? LibraryKinds.LIB} kind). ${oneLine({ text: opts.summary })}`,
425
+ '',
426
+ ...renderAtlasLookups({ kind: PackageKinds.LIB }),
427
+ ].join('\n');
428
428
  }
429
429
 
430
- const eol = opts.source.includes('\r\n') ? '\r\n' : '\n';
431
- const bullet = renderAppBullet({ app: opts.app });
432
- const lines = opts.source.split(eol);
433
- const heading = lines.findIndex((line) => APPS_HEADING.test(line));
430
+ static renderVulcanConfig(opts: { project: string; block: IAppsBlock }): string {
431
+ return [
432
+ "import type { VulcanConfig } from '@venizia/vulcan';",
433
+ '',
434
+ AppsBlock.render({ block: opts.block }),
435
+ '',
436
+ 'export default {',
437
+ ` name: '${opts.project}',`,
438
+ " rules: { 'V-W-01': 'on-user-word' },",
439
+ ' layout: apps.layout,',
440
+ ' packages: apps.packages,',
441
+ ' presets: apps.presets,',
442
+ ' atlas: { sources: apps.sources },',
443
+ '} satisfies VulcanConfig;',
444
+ '',
445
+ ].join('\n');
446
+ }
447
+
448
+ /** The catalog entry a `file:` preset writes only works on this machine; say so. */
449
+ static filePresetWarning(opts: { spec: IPresetSpec; packageName: string }): string | undefined {
450
+ return opts.spec.packageName === undefined
451
+ ? `warning: the catalog gets ${opts.packageName} as ${opts.spec.range} - a file: entry is not portable, so a clone elsewhere or CI cannot install it until it names a published version`
452
+ : undefined;
453
+ }
434
454
 
435
- if (heading === -1) {
436
- const kept = opts.source.trimEnd();
455
+ static renderKnowledgeIndex(opts: {
456
+ project: string;
457
+ apps: { name: string; summary: string }[];
458
+ }): string {
459
+ return [
460
+ '---',
461
+ 'okf_version: "0.2"',
462
+ '---',
463
+ '',
464
+ `# ${opts.project} knowledge`,
465
+ '',
466
+ `Facts about ${opts.project}, in the Open Knowledge Format. Rules live in \`../rules.md\`.`,
467
+ '',
468
+ '## Apps',
469
+ '',
470
+ ...opts.apps.map((app) => renderAppBullet({ app })),
471
+ '',
472
+ ].join('\n');
473
+ }
437
474
 
438
- return `${kept === '' ? '' : `${kept}${eol}${eol}`}## Apps${eol}${eol}${bullet}${eol}`;
475
+ static renderAppConcept(opts: { app: IApp; summary: string; presetPackage: string }): string {
476
+ return [
477
+ '---',
478
+ 'type: Package',
479
+ `title: ${opts.app.name}`,
480
+ // JSON string syntax is valid YAML, so a colon, quote or newline in the summary stays one scalar.
481
+ `description: ${JSON.stringify(opts.summary)}`,
482
+ `resource: ${opts.app.folder}/${opts.app.name}`,
483
+ `tags: [packages, ${opts.app.side}]`,
484
+ '---',
485
+ '',
486
+ `# ${opts.app.name}`,
487
+ '',
488
+ `The ${opts.app.side} app at \`${opts.app.folder}/${opts.app.name}\`, created from the ${opts.presetPackage} preset. ${oneLine({ text: opts.summary })}`,
489
+ '',
490
+ ...renderAtlasLookups({ kind: opts.app.side }),
491
+ ].join('\n');
439
492
  }
493
+ }
494
+
495
+ export class PresetRecord {
496
+ /**
497
+ * What `--preset` was given, kept so it can be typed again from the project root: a package spec as
498
+ * typed, a `file:` path made relative to the project.
499
+ */
500
+ static presetSpecOf(opts: { value: string; root: string; cwd: string }): string {
501
+ const prefix = CreateConstants.PRESET_FILE_PREFIX;
502
+
503
+ if (!opts.value.startsWith(prefix)) {
504
+ return opts.value;
505
+ }
440
506
 
441
- const next = lines.findIndex((line, index) => index > heading && ANY_HEADING.test(line));
442
- const section = lines.slice(heading + 1, next === -1 ? lines.length : next);
443
- const last = section.findLastIndex((line) => line.startsWith('- ['));
507
+ const target = resolve(opts.cwd, opts.value.slice(prefix.length));
444
508
 
445
- if (last === -1) {
446
- lines.splice(heading, 1, lines[heading] ?? '', '', bullet);
447
- } else {
448
- lines.splice(heading + 1 + last + 1, 0, bullet);
509
+ return `${prefix}${relative(opts.root, target) || '.'}`;
449
510
  }
450
511
 
451
- return lines.join(eol);
452
- };
512
+ /** The block with this preset recorded: once per spec, its side and summary refreshed. */
513
+ static record(opts: { block: IAppsBlock; preset: IRecordedPreset }): IAppsBlock {
514
+ const others = (opts.block.presets ?? []).filter((item) => item.spec !== opts.preset.spec);
515
+ const index = (opts.block.presets ?? []).findIndex((item) => item.spec === opts.preset.spec);
516
+ const presets =
517
+ index === -1
518
+ ? [...others, opts.preset]
519
+ : (opts.block.presets ?? []).map((item, at) => (at === index ? opts.preset : item));
453
520
 
454
- /** The catalog entry a `file:` preset writes only works on this machine; say so. */
455
- export const filePresetWarning = (opts: {
456
- spec: IPresetSpec;
457
- packageName: string;
458
- }): string | undefined =>
459
- opts.spec.packageName === undefined
460
- ? `warning: the catalog gets ${opts.packageName} as ${opts.spec.range} - a file: entry is not portable, so a clone elsewhere or CI cannot install it until it names a published version`
461
- : undefined;
462
-
463
- export const renderKnowledgeIndex = (opts: {
464
- project: string;
465
- apps: { name: string; summary: string }[];
466
- }): string =>
467
- [
468
- '---',
469
- 'okf_version: "0.2"',
470
- '---',
471
- '',
472
- `# ${opts.project} knowledge`,
473
- '',
474
- `Facts about ${opts.project}, in the Open Knowledge Format. Rules live in \`../rules.md\`.`,
475
- '',
476
- '## Apps',
477
- '',
478
- ...opts.apps.map((app) => renderAppBullet({ app })),
479
- '',
480
- ].join('\n');
481
-
482
- export const renderAppConcept = (opts: {
483
- app: IApp;
484
- summary: string;
485
- presetPackage: string;
486
- }): string =>
487
- [
488
- '---',
489
- 'type: Package',
490
- `title: ${opts.app.name}`,
491
- // JSON string syntax is valid YAML, so a colon, quote or newline in the summary stays one scalar.
492
- `description: ${JSON.stringify(opts.summary)}`,
493
- `resource: ${opts.app.folder}/${opts.app.name}`,
494
- `tags: [packages, ${opts.app.side}]`,
495
- '---',
496
- '',
497
- `# ${opts.app.name}`,
498
- '',
499
- `The ${opts.app.side} app at \`${opts.app.folder}/${opts.app.name}\`, created from the ${opts.presetPackage} preset. ${oneLine({ text: opts.summary })}`,
500
- '',
501
- ...renderAtlasLookups({ kind: opts.app.side }),
502
- ].join('\n');
503
-
504
- export const pickPort = (opts: { preferred: number; used: number[] }): number => {
505
- let port = opts.preferred;
506
-
507
- while (opts.used.includes(port)) {
508
- port++;
521
+ return { ...opts.block, presets };
509
522
  }
523
+ }
510
524
 
511
- return port;
512
- };
525
+ type TAppsBlockResult = { ok: true; block: IAppsBlock } | { ok: false; reason: TAppsBlockProblem };
513
526
 
514
- export const readPort = (opts: { envExample: string }): number | undefined => {
515
- const match = ENV_PORT.exec(opts.envExample);
527
+ export class PortRegistry {
528
+ static pick(opts: { preferred: number; used: number[] }): number {
529
+ let port = opts.preferred;
516
530
 
517
- return match === null ? undefined : Number(match[1]);
518
- };
531
+ while (opts.used.includes(port)) {
532
+ port++;
533
+ }
534
+
535
+ return port;
536
+ }
537
+
538
+ static read(opts: { envExample: string }): number | undefined {
539
+ const match = ENV_PORT.exec(opts.envExample);
540
+
541
+ return match === null ? undefined : Number(match[1]);
542
+ }
543
+ }