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