@venizia/vulcan 0.4.8 → 0.4.9-0

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 (126) hide show
  1. package/base/hooks/antigravity-guards.ts +2 -1
  2. package/base/hooks/codex-guards.ts +2 -1
  3. package/base/hooks/guard-manifest.ts +2 -1
  4. package/base/hooks/guard-package.ts +2 -1
  5. package/base/hooks/guard-remote-hosts.ts +9 -3
  6. package/base/hooks/guard-scripting.ts +2 -1
  7. package/base/hooks/guard-writes.ts +14 -4
  8. package/base/hooks/post-tool.ts +2 -1
  9. package/base/hooks/prompt-submit.ts +2 -1
  10. package/base/hooks/session-start.ts +3 -1
  11. package/base/hooks/stop.ts +2 -1
  12. package/base/make/vulcan.mk +1 -4
  13. package/base/skills/build-a-feature/SKILL.md +1 -1
  14. package/base/skills/docs-update/SKILL.md +11 -5
  15. package/base/skills/docs-update/evals/evals.json +1 -1
  16. package/base/skills/docs-writing/SKILL.md +1 -1
  17. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +20 -6
  20. package/base/skills/visualize-work/references/spec.md +16 -5
  21. package/package.json +5 -6
  22. package/src/agents/codex-hooks.ts +11 -10
  23. package/src/agents/common/types.ts +1 -1
  24. package/src/agents/exclude.ts +1 -1
  25. package/src/agents/hooks-json.ts +4 -8
  26. package/src/agents/prompt.ts +2 -2
  27. package/src/agents/render.ts +8 -12
  28. package/src/cli.ts +3 -1
  29. package/src/commands/doctor.command.ts +3 -1
  30. package/src/commands/help.command.ts +11 -9
  31. package/src/commands/init.command.ts +3 -1
  32. package/src/commands/profile.command.ts +1 -1
  33. package/src/commands/upgrade.command.ts +5 -3
  34. package/src/commands/visualize.command.ts +23 -2
  35. package/src/common/index.ts +2 -0
  36. package/src/common/layout-folder.ts +2 -20
  37. package/src/common/record.ts +7 -0
  38. package/src/common/text.ts +7 -0
  39. package/src/config/common/constants.ts +13 -1
  40. package/src/config/common/types.ts +8 -1
  41. package/src/config/loader.ts +4 -2
  42. package/src/config/packages.ts +4 -1
  43. package/src/config/schema.ts +51 -4
  44. package/src/create/add-app.ts +170 -69
  45. package/src/create/add-lib.ts +41 -31
  46. package/src/create/common/constants.ts +1 -0
  47. package/src/create/common/failure.ts +10 -0
  48. package/src/create/common/index.ts +2 -0
  49. package/src/create/common/preset-path.ts +11 -0
  50. package/src/create/common/types.ts +7 -2
  51. package/src/create/init-monorepo.ts +5 -2
  52. package/src/create/lib-preset.ts +22 -17
  53. package/src/create/names.ts +1 -1
  54. package/src/create/next.ts +1 -1
  55. package/src/create/preset-diff.ts +232 -55
  56. package/src/create/preset-menu.ts +3 -3
  57. package/src/create/preset.ts +18 -10
  58. package/src/create/process.ts +4 -2
  59. package/src/create/scratch.ts +3 -1
  60. package/src/create/workspace.ts +37 -20
  61. package/src/doctor/checks.ts +74 -16
  62. package/src/doctor/runner.ts +2 -0
  63. package/src/doctor/tags.ts +2 -4
  64. package/src/hooks/codex-patch.ts +2 -2
  65. package/src/hooks/common/constants.ts +0 -3
  66. package/src/hooks/common/types.ts +15 -1
  67. package/src/hooks/decision.ts +1 -5
  68. package/src/hooks/guard-git.ts +1 -1
  69. package/src/hooks/guard-outside.ts +28 -9
  70. package/src/hooks/guard-package.ts +13 -7
  71. package/src/hooks/guard-scripting.ts +1 -1
  72. package/src/hooks/guard-writes.ts +73 -20
  73. package/src/hooks/owner-reply.ts +1 -1
  74. package/src/hooks/project-guards.ts +39 -4
  75. package/src/hooks/remote-hosts.ts +5 -20
  76. package/src/hooks/session-digest.ts +7 -0
  77. package/src/hooks/shell.ts +13 -4
  78. package/src/hooks/trusted-scripts.ts +80 -4
  79. package/src/init/common/types.ts +1 -1
  80. package/src/init/scaffold.ts +2 -2
  81. package/src/local/clean.ts +1 -1
  82. package/src/local/scan.ts +2 -2
  83. package/src/manifest/render.ts +20 -11
  84. package/src/owner/profile.ts +1 -3
  85. package/src/owner/shape.ts +1 -1
  86. package/src/owner/survey.ts +27 -18
  87. package/src/router.ts +4 -1
  88. package/src/rules/common/types.ts +1 -1
  89. package/src/signals/state.ts +1 -4
  90. package/src/sync/agent-removal.ts +7 -10
  91. package/src/sync/claude-launch.ts +36 -1
  92. package/src/sync/common/constants.ts +4 -0
  93. package/src/sync/common/index.ts +1 -0
  94. package/src/sync/common/symlink.ts +9 -0
  95. package/src/sync/common/types.ts +2 -2
  96. package/src/sync/planner.ts +10 -12
  97. package/src/sync/settings.ts +1 -1
  98. package/src/ui/keyboard.ts +3 -1
  99. package/src/ui/prompt.ts +4 -2
  100. package/src/visualize/assets.ts +370 -195
  101. package/src/visualize/charts.ts +11 -2
  102. package/src/visualize/compare-css.ts +30 -0
  103. package/src/visualize/compare-render.ts +194 -0
  104. package/src/visualize/compare-schema.ts +81 -0
  105. package/src/visualize/compare-validate.ts +126 -0
  106. package/src/visualize/constants.ts +29 -3
  107. package/src/visualize/diagrams.ts +1 -1
  108. package/src/visualize/gate.ts +136 -0
  109. package/src/visualize/icons.ts +5 -2
  110. package/src/visualize/index.ts +2 -0
  111. package/src/visualize/kinds-css.ts +54 -0
  112. package/src/visualize/kinds-render.ts +693 -0
  113. package/src/visualize/kinds-schema.ts +148 -0
  114. package/src/visualize/kinds-validate.ts +184 -0
  115. package/src/visualize/labels-vi.ts +109 -0
  116. package/src/visualize/labels.ts +49 -0
  117. package/src/visualize/layout.ts +10 -5
  118. package/src/visualize/page.ts +99 -61
  119. package/src/visualize/render.ts +48 -7
  120. package/src/visualize/schema.ts +21 -1
  121. package/src/visualize/sections.ts +115 -34
  122. package/src/visualize/sources.ts +270 -0
  123. package/src/visualize/theme.ts +472 -0
  124. package/src/visualize/validate.ts +6 -0
  125. package/src/wiki/anchors.ts +1 -1
  126. package/src/wiki/source-links.ts +3 -5
@@ -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 }[];
@@ -212,7 +212,9 @@ const runCreate = async (opts: {
212
212
  }
213
213
 
214
214
  // A new project has no config to list presets from: the official ones, or one typed.
215
- const presetValue = flagged ?? (await askPresetSpec({ recorded: [] }))?.trim();
215
+ const askingSpec = flagged === undefined ? askPresetSpec({ recorded: [] }) : undefined;
216
+ const typedSpec = await askingSpec;
217
+ const presetValue = flagged ?? typedSpec?.trim();
216
218
 
217
219
  if (presetValue === undefined || presetValue === '') {
218
220
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
@@ -341,7 +343,8 @@ const runCreate = async (opts: {
341
343
  }
342
344
 
343
345
  // Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
344
- const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
346
+ const askingScope = flaggedScope.scope ?? (menusAvailable() ? askScope() : undefined);
347
+ const scope = await askingScope;
345
348
 
346
349
  if (scope === null) {
347
350
  return fail({ message: ABORTED });
@@ -1,7 +1,9 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
- import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
2
+ import { dirname, resolve } from 'node:path';
3
3
  import { z } from 'zod';
4
- import { CreateConstants } from './common/index.ts';
4
+ import { LibraryKinds } from '../config/index.ts';
5
+ import type { TLibraryKind } from '../config/index.ts';
6
+ import { CreateConstants, PresetPath } from './common/index.ts';
5
7
  import type { ILocatedPreset, IRecordedPreset } from './common/index.ts';
6
8
 
7
9
  /** `package.json` fields a lib preset may pass through; anything else it generates itself or does not support. */
@@ -78,22 +80,23 @@ export type TLibPreset = Omit<z.infer<typeof LIB_SCHEMA>, 'files'> & {
78
80
  files: string;
79
81
  };
80
82
 
81
- export type TLibPresetResult = { ok: true; lib: TLibPreset } | { ok: false; error: string };
83
+ type TLibPresetResult = { ok: true; lib: TLibPreset } | { ok: false; error: string };
82
84
 
83
- const escapes = (opts: { root: string; path: string }): boolean => {
84
- const relativePath = relative(opts.root, opts.path);
85
-
86
- return isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith(`..${sep}`);
87
- };
88
-
89
- /** The lib preset of a located preset package, validated; the app side is never touched by an error here. */
90
- export const readLibPreset = (opts: { located: ILocatedPreset }): TLibPresetResult => {
85
+ /**
86
+ * The lib preset of a located preset package, validated; with `kind: 'shared'` it reads the shared kind,
87
+ * which has the same schema. The app side is never touched by an error here.
88
+ */
89
+ export const readLibPreset = (opts: {
90
+ located: ILocatedPreset;
91
+ kind?: TLibraryKind;
92
+ }): TLibPresetResult => {
91
93
  const { located } = opts;
94
+ const kind = opts.kind ?? LibraryKinds.LIB;
92
95
  const shown = `${located.packageName}@${located.packageVersion}`;
93
- const file = located.libFile;
96
+ const file = kind === LibraryKinds.SHARED ? located.sharedFile : located.libFile;
94
97
 
95
98
  if (file === undefined) {
96
- return { ok: false, error: `preset ${located.packageName} has no lib kind` };
99
+ return { ok: false, error: `preset ${located.packageName} has no ${kind} kind` };
97
100
  }
98
101
 
99
102
  let raw: unknown;
@@ -112,7 +115,7 @@ export const readLibPreset = (opts: { located: ILocatedPreset }): TLibPresetResu
112
115
  ) {
113
116
  return {
114
117
  ok: false,
115
- error: `${shown}: the lib preset has preset version ${String(typeof raw === 'object' && raw !== null && 'presetVersion' in raw ? raw.presetVersion : undefined)}; this VULCAN reads version ${CreateConstants.PRESET_VERSION} - upgrade @venizia/vulcan`,
118
+ error: `${shown}: the ${kind} preset has preset version ${String(typeof raw === 'object' && raw !== null && 'presetVersion' in raw ? raw.presetVersion : undefined)}; this VULCAN reads version ${CreateConstants.PRESET_VERSION} - upgrade @venizia/vulcan`,
116
119
  };
117
120
  }
118
121
 
@@ -123,15 +126,15 @@ export const readLibPreset = (opts: { located: ILocatedPreset }): TLibPresetResu
123
126
  .map((issue) => `${issue.path.join('.')} ${issue.message}`)
124
127
  .join('; ');
125
128
 
126
- return { ok: false, error: `${shown}: lib preset: ${issues}` };
129
+ return { ok: false, error: `${shown}: ${kind} preset: ${issues}` };
127
130
  }
128
131
 
129
132
  const files = resolve(dirname(file), parsed.data.files);
130
133
 
131
- if (escapes({ root: located.packageRoot, path: files }) || !existsSync(files)) {
134
+ if (PresetPath.escapes({ root: located.packageRoot, path: files }) || !existsSync(files)) {
132
135
  return {
133
136
  ok: false,
134
- error: `${shown}: lib preset: files ${parsed.data.files} is missing or points outside the package`,
137
+ error: `${shown}: ${kind} preset: files ${parsed.data.files} is missing or points outside the package`,
135
138
  };
136
139
  }
137
140
 
@@ -144,11 +147,13 @@ export const recordedPresetOf = (opts: {
144
147
  located: ILocatedPreset;
145
148
  }): IRecordedPreset => {
146
149
  const lib = readLibPreset({ located: opts.located });
150
+ const shared = readLibPreset({ located: opts.located, kind: LibraryKinds.SHARED });
147
151
 
148
152
  return {
149
153
  spec: opts.spec,
150
154
  side: opts.located.preset.side,
151
155
  summary: opts.located.preset.summary,
152
156
  ...(lib.ok ? { lib: lib.lib.summary } : {}),
157
+ ...(shared.ok ? { shared: shared.lib.summary } : {}),
153
158
  };
154
159
  };
@@ -78,7 +78,7 @@ export const nameProblem = (opts: { name: string }): string | undefined =>
78
78
  : `'${opts.name}' is not a name: lowercase letters, digits and '-', starting with a letter or digit`;
79
79
 
80
80
  /** Why a value is not valid for a field: a folder path for a path field, a name for the rest. Undefined when it is valid. */
81
- export const fieldProblem = (opts: { field: INameField; value: string }): string | undefined =>
81
+ const fieldProblem = (opts: { field: INameField; value: string }): string | undefined =>
82
82
  opts.field.isPath === true
83
83
  ? layoutFolderProblem({ folder: opts.value })
84
84
  : nameProblem({ name: opts.value });
@@ -3,7 +3,7 @@ import { join } from 'node:path';
3
3
  import { readPort } from './workspace.ts';
4
4
 
5
5
  /** One app of the monorepo as `make dev` serves it: its port, and the paths worth opening. */
6
- export interface INextApp {
6
+ interface INextApp {
7
7
  port: number;
8
8
  urls: string[];
9
9
  }
@@ -4,12 +4,14 @@ import type { TConstValue } from '../common/index.ts';
4
4
  import { ExitCodes } from '../common/index.ts';
5
5
  import { layoutFoldersOf } from '../common/layout-folder.ts';
6
6
  import type { ILayout } from '../common/layout-folder.ts';
7
- import { loadConfig, PackageKinds, resolvePackages } from '../config/index.ts';
7
+ import { LibraryKinds, loadConfig, PackageKinds, resolvePackages } from '../config/index.ts';
8
+ import type { IProjectPackage, TLibraryKind } from '../config/index.ts';
8
9
  import { locate, resolveApiUrl } from './add-app.ts';
9
10
  import { AppSides, CreateConstants, CreateFlags, PresetDiffStatuses } from './common/index.ts';
10
11
  import type { ILocatedPreset, IRecordedPreset, IPresetSpec, TAppSide } from './common/index.ts';
11
12
  import { diffLines } from './diff.ts';
12
13
  import type { ILineDiff } from './diff.ts';
14
+ import { readLibPreset } from './lib-preset.ts';
13
15
  import { readFlag } from './names.ts';
14
16
  import {
15
17
  decodeText,
@@ -23,8 +25,11 @@ import { withScratch } from './scratch.ts';
23
25
  import { readPort } from './workspace.ts';
24
26
 
25
27
  const SUBCOMMAND = 'diff';
26
- const USAGE = `usage: vulcan preset ${SUBCOMMAND} <app> [--preset <name|file:path>] [--api <backend app> | --no-api] [--full] [--check]`;
28
+ const USAGE = `usage: vulcan preset ${SUBCOMMAND} <package> [--preset <name|file:path>] [--api <backend app> | --no-api] [--full] [--check]`;
27
29
  const API_URL_TOKEN = '{{apiUrl}}';
30
+ /** What the compared folder is called in the output. */
31
+ const APP_SUBJECT = 'app';
32
+ const PACKAGE_SUBJECT = 'package';
28
33
  /** Flags that take the next word as their value. */
29
34
  const VALUE_FLAGS = [CreateFlags.PRESET, CreateFlags.API];
30
35
 
@@ -103,7 +108,7 @@ export const detectPreset = (opts: {
103
108
  };
104
109
  };
105
110
 
106
- export interface IPresetFileReport {
111
+ interface IPresetFileReport {
107
112
  path: string;
108
113
  status: TConstValue<typeof PresetDiffStatuses>;
109
114
  diff?: ILineDiff;
@@ -149,11 +154,11 @@ export const comparePresetFiles = (opts: {
149
154
  };
150
155
  });
151
156
 
152
- const describeDifference = (opts: { report: IPresetFileReport }): string => {
157
+ const describeDifference = (opts: { report: IPresetFileReport; subject: string }): string => {
153
158
  const { diff, isBinary, isFolder } = opts.report;
154
159
 
155
160
  if (isFolder === true) {
156
- return '(the app has a folder here)';
161
+ return `(the ${opts.subject} has a folder here)`;
157
162
  }
158
163
 
159
164
  if (isBinary === true) {
@@ -175,6 +180,8 @@ const describeDifference = (opts: { report: IPresetFileReport }): string => {
175
180
 
176
181
  const printReport = (opts: {
177
182
  appPath: string;
183
+ /** What the folder is called in the output: `app`, or `package` for a library or a shared package. */
184
+ subject: string;
178
185
  located: ILocatedPreset;
179
186
  source: string;
180
187
  reports: IPresetFileReport[];
@@ -188,13 +195,16 @@ const printReport = (opts: {
188
195
  ];
189
196
 
190
197
  for (const report of reports) {
191
- const note = report.status === PresetDiffStatuses.DIFFERS ? describeDifference({ report }) : '';
198
+ const note =
199
+ report.status === PresetDiffStatuses.DIFFERS
200
+ ? describeDifference({ report, subject: opts.subject })
201
+ : '';
192
202
 
193
203
  lines.push(` ${report.status.padEnd(8)} ${report.path}${note === '' ? '' : ` ${note}`}`);
194
204
 
195
205
  if (opts.isFull && report.diff?.hunks !== undefined && report.diff.hunks.length > 0) {
196
206
  lines.push(
197
- ` --- ${opts.appPath}/${report.path} (the app)`,
207
+ ` --- ${opts.appPath}/${report.path} (the ${opts.subject})`,
198
208
  ` +++ ${report.path} (the preset)`,
199
209
  ...report.diff.hunks.flatMap((hunk) => hunk.split('\n').map((line) => ` ${line}`)),
200
210
  );
@@ -202,7 +212,7 @@ const printReport = (opts: {
202
212
  }
203
213
 
204
214
  lines.push(
205
- `${reports.length} file${reports.length === 1 ? '' : 's'}: ${countOf(PresetDiffStatuses.SAME)} same, ${countOf(PresetDiffStatuses.DIFFERS)} differ, ${countOf(PresetDiffStatuses.MISSING)} missing in the app`,
215
+ `${reports.length} file${reports.length === 1 ? '' : 's'}: ${countOf(PresetDiffStatuses.SAME)} same, ${countOf(PresetDiffStatuses.DIFFERS)} differ, ${countOf(PresetDiffStatuses.MISSING)} missing in the ${opts.subject}`,
206
216
  );
207
217
  process.stdout.write(`${lines.join('\n')}\n`);
208
218
  };
@@ -236,14 +246,202 @@ const locateInstalled = (opts: { spec: IPresetSpec; appDirectory: string; root:
236
246
  return inApp.ok ? inApp : locatePreset({ spec: opts.spec, root: opts.root });
237
247
  };
238
248
 
249
+ /** Finds the preset (the `--preset` value, else the detected spec) where it lives and hands it to `compare`. */
250
+ const locateAndCompare = async (opts: {
251
+ cwd: string;
252
+ flagValue: string | undefined;
253
+ detectedSpec: string | undefined;
254
+ /** The folder of the package being compared: an installed preset is looked for in its own `node_modules` first. */
255
+ packageDirectory: string;
256
+ compare: (found: { located: ILocatedPreset; source: string }) => Promise<number>;
257
+ }): Promise<number> => {
258
+ const { cwd, compare } = opts;
259
+ const value = opts.flagValue ?? opts.detectedSpec ?? '';
260
+ const spec = parsePresetSpec({ value, cwd });
261
+ // `name@range` is fetched; a bare name, a detected spec or a `file:` folder is read where it already is.
262
+ const isFetched = opts.flagValue !== undefined && opts.flagValue.lastIndexOf('@') > 0;
263
+
264
+ if (isFetched) {
265
+ return withScratch({
266
+ root: cwd,
267
+ run: async (scratch) => {
268
+ const located = await locate({ cwd, scratch, spec });
269
+
270
+ return located.ok
271
+ ? compare({
272
+ located: located.located,
273
+ source: `fetched ${spec.packageName}@${spec.range}`,
274
+ })
275
+ : fail({ message: located.error });
276
+ },
277
+ });
278
+ }
279
+
280
+ const located =
281
+ spec.packageName === undefined
282
+ ? locatePreset({ spec, root: cwd })
283
+ : locateInstalled({ spec, appDirectory: opts.packageDirectory, root: cwd });
284
+
285
+ if (!located.ok) {
286
+ return fail({
287
+ message: `${located.error}${spec.packageName === undefined ? '' : ` - run bun install, or give ${CreateFlags.PRESET} ${spec.packageName}@<range> to fetch it`}`,
288
+ });
289
+ }
290
+
291
+ return compare({
292
+ located: located.located,
293
+ source:
294
+ spec.packageName === undefined
295
+ ? `file:${spec.range.slice(CreateConstants.PRESET_FILE_PREFIX.length)}`
296
+ : 'installed in node_modules',
297
+ });
298
+ };
299
+
300
+ const PRESET_HINT = `say which with ${CreateFlags.PRESET} <name|file:path>`;
301
+ const MANIFEST_FILE = 'package.json';
302
+
303
+ /**
304
+ * The recorded preset a library or shared package is set against: the one recorded preset (a package counted
305
+ * once, as `detectPreset` does) whose record ships the package's kind. A package made by the shared kind
306
+ * never takes a lib kind and the reverse, so nothing falls back to the other kind.
307
+ */
308
+ const detectLibraryPreset = (opts: {
309
+ root: string;
310
+ recorded: IRecordedPreset[];
311
+ kind: TLibraryKind;
312
+ }): { ok: true; spec: string } | { ok: false; error: string } => {
313
+ const matching = new Map<string, string>();
314
+
315
+ for (const preset of opts.recorded) {
316
+ const ships = (opts.kind === LibraryKinds.SHARED ? preset.shared : preset.lib) !== undefined;
317
+
318
+ if (ships) {
319
+ // The last record of a package wins: it is the newest spec `add` wrote.
320
+ matching.set(
321
+ packageNameOf({ spec: preset.spec, root: opts.root }) ?? preset.spec,
322
+ preset.spec,
323
+ );
324
+ }
325
+ }
326
+
327
+ const [only] = [...matching.values()];
328
+
329
+ if (matching.size === 1 && only !== undefined) {
330
+ return { ok: true, spec: only };
331
+ }
332
+
333
+ const known =
334
+ opts.recorded.length === 0
335
+ ? 'the config records no preset'
336
+ : `recorded: ${opts.recorded.map((preset) => preset.spec).join(', ')}`;
337
+
338
+ return {
339
+ ok: false,
340
+ error: `${matching.size === 0 ? `no recorded preset ships the ${opts.kind} kind` : `more than one recorded preset ships the ${opts.kind} kind`} (${known}) - ${PRESET_HINT}`,
341
+ };
342
+ };
343
+
344
+ /**
345
+ * `preset diff` of a package whose config entry has `kind: 'lib'`: the files of the preset kind that made it
346
+ * (`presetKind`, absent means `lib`), rendered with that kind's tokens, set against the package's folder.
347
+ */
348
+ const diffLibrary = async (opts: {
349
+ cwd: string;
350
+ args: string[];
351
+ library: IProjectPackage;
352
+ kind: TLibraryKind;
353
+ recorded: IRecordedPreset[];
354
+ configName: string | undefined;
355
+ presetValue: string | undefined;
356
+ }): Promise<number> => {
357
+ const { cwd, args, library, kind } = opts;
358
+ const noun = kind === LibraryKinds.SHARED ? 'shared package' : 'library';
359
+
360
+ for (const flag of [CreateFlags.API, CreateFlags.NO_API]) {
361
+ if (args.includes(flag)) {
362
+ return fail({
363
+ message: `${library.dir} is a ${noun}: it has no proxy target, so ${flag} does not apply`,
364
+ });
365
+ }
366
+ }
367
+
368
+ const detected =
369
+ opts.presetValue === undefined
370
+ ? detectLibraryPreset({ root: cwd, recorded: opts.recorded, kind })
371
+ : undefined;
372
+
373
+ if (detected !== undefined && !detected.ok) {
374
+ return fail({ message: detected.error });
375
+ }
376
+
377
+ const rootManifest = readJson({ file: join(cwd, MANIFEST_FILE) });
378
+ const rootName = rootManifest?.['name'];
379
+ const project = opts.configName ?? (typeof rootName === 'string' ? rootName : library.dir);
380
+ const directory = join(cwd, library.path);
381
+
382
+ return locateAndCompare({
383
+ cwd,
384
+ flagValue: opts.presetValue,
385
+ detectedSpec: detected?.ok === true ? detected.spec : undefined,
386
+ packageDirectory: directory,
387
+ compare: async ({ located, source }) => {
388
+ const read = readLibPreset({ located, kind });
389
+
390
+ if (!read.ok) {
391
+ return fail({ message: `${read.error} (${library.dir} is a ${noun})` });
392
+ }
393
+
394
+ // A package.json among the files is skipped: add replaces it with a generated one.
395
+ const rendered = renderPresetFiles({
396
+ located,
397
+ files: read.lib.files,
398
+ tokens: { project, [kind]: library.dir, package: library.name },
399
+ }).filter((file) => file.path !== MANIFEST_FILE);
400
+ const reports = comparePresetFiles({ rendered, appDirectory: directory });
401
+
402
+ printReport({
403
+ appPath: library.path,
404
+ subject: PACKAGE_SUBJECT,
405
+ located,
406
+ source,
407
+ reports,
408
+ isFull: args.includes(CreateFlags.FULL),
409
+ });
410
+
411
+ return args.includes(CreateFlags.CHECK) &&
412
+ reports.some((report) => report.status !== PresetDiffStatuses.SAME)
413
+ ? ExitCodes.FAILURE
414
+ : ExitCodes.OK;
415
+ },
416
+ });
417
+ };
418
+
419
+ /** The refusal for a name that is no package of the config: it lists the apps and the libraries there are. */
420
+ const reportNotFound = (opts: { packages: IProjectPackage[]; packageName: string }): number => {
421
+ const namesOf = (query: { isLibrary: boolean }): string[] =>
422
+ opts.packages
423
+ .filter((entry) => (entry.kind === PackageKinds.LIB) === query.isLibrary)
424
+ .map((entry) => entry.dir);
425
+ const apps = namesOf({ isLibrary: false });
426
+ const libraries = namesOf({ isLibrary: true });
427
+ const known = [
428
+ ...(apps.length === 0 ? [] : [`apps: ${apps.join(', ')}`]),
429
+ ...(libraries.length === 0 ? [] : [`libraries: ${libraries.join(', ')}`]),
430
+ ];
431
+
432
+ return fail({
433
+ message: `no app '${opts.packageName}' in the config packages${known.length === 0 ? '' : ` (${known.join('; ')})`}`,
434
+ });
435
+ };
436
+
239
437
  export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Promise<number> => {
240
438
  const { cwd, args } = opts;
241
439
  const positionals = args.filter(
242
440
  (arg, index) => !arg.startsWith('-') && !VALUE_FLAGS.includes(args[index - 1] ?? ''),
243
441
  );
244
- const [subcommand, appName] = positionals;
442
+ const [subcommand, packageName] = positionals;
245
443
 
246
- if (subcommand !== SUBCOMMAND || appName === undefined) {
444
+ if (subcommand !== SUBCOMMAND || packageName === undefined) {
247
445
  return fail({ message: USAGE });
248
446
  }
249
447
 
@@ -267,18 +465,28 @@ export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Prom
267
465
 
268
466
  const { config } = loaded;
269
467
  const packages = resolvePackages({ config });
270
- const app = packages.find((entry) => entry.dir === appName || entry.path === appName);
468
+ const app = packages.find((entry) => entry.dir === packageName || entry.path === packageName);
271
469
 
272
- if (config.layout === undefined || app === undefined) {
273
- const known = packages
274
- .filter((entry) => entry.kind !== PackageKinds.LIB)
275
- .map((entry) => entry.dir);
470
+ if (app === undefined) {
471
+ return reportNotFound({ packages, packageName });
472
+ }
276
473
 
277
- return fail({
278
- message: `no app '${appName}' in the config packages${known.length === 0 ? '' : ` (apps: ${known.join(', ')})`}`,
474
+ if (app.kind === PackageKinds.LIB) {
475
+ return diffLibrary({
476
+ cwd,
477
+ args,
478
+ library: app,
479
+ kind: app.presetKind ?? LibraryKinds.LIB,
480
+ recorded: config.presets ?? [],
481
+ configName: config.name,
482
+ presetValue: presetFlag.value,
279
483
  });
280
484
  }
281
485
 
486
+ if (config.layout === undefined) {
487
+ return reportNotFound({ packages, packageName });
488
+ }
489
+
282
490
  const side = sideOf({ layout: config.layout, path: app.path });
283
491
 
284
492
  if (side === undefined) {
@@ -352,6 +560,7 @@ export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Prom
352
560
 
353
561
  printReport({
354
562
  appPath: app.path,
563
+ subject: APP_SUBJECT,
355
564
  located,
356
565
  source: found.source,
357
566
  reports,
@@ -364,43 +573,11 @@ export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Prom
364
573
  : ExitCodes.OK;
365
574
  };
366
575
 
367
- const value = presetFlag.value ?? (detected?.ok === true ? detected.spec : '');
368
- const spec = parsePresetSpec({ value, cwd });
369
- // `name@range` is fetched; a bare name, a detected spec or a `file:` folder is read where it already is.
370
- const isFetched = presetFlag.value !== undefined && presetFlag.value.lastIndexOf('@') > 0;
371
-
372
- if (isFetched) {
373
- return withScratch({
374
- root: cwd,
375
- run: async (scratch) => {
376
- const located = await locate({ cwd, scratch, spec });
377
-
378
- return located.ok
379
- ? compare({
380
- located: located.located,
381
- source: `fetched ${spec.packageName}@${spec.range}`,
382
- })
383
- : fail({ message: located.error });
384
- },
385
- });
386
- }
387
-
388
- const located =
389
- spec.packageName === undefined
390
- ? locatePreset({ spec, root: cwd })
391
- : locateInstalled({ spec, appDirectory, root: cwd });
392
-
393
- if (!located.ok) {
394
- return fail({
395
- message: `${located.error}${spec.packageName === undefined ? '' : ` - run bun install, or give ${CreateFlags.PRESET} ${spec.packageName}@<range> to fetch it`}`,
396
- });
397
- }
398
-
399
- return compare({
400
- located: located.located,
401
- source:
402
- spec.packageName === undefined
403
- ? `file:${spec.range.slice(CreateConstants.PRESET_FILE_PREFIX.length)}`
404
- : 'installed in node_modules',
576
+ return locateAndCompare({
577
+ cwd,
578
+ flagValue: presetFlag.value,
579
+ detectedSpec: detected?.ok === true ? detected.spec : undefined,
580
+ packageDirectory: appDirectory,
581
+ compare,
405
582
  });
406
583
  };
@@ -1,10 +1,10 @@
1
- import { OFFICIAL_PRESETS, officialIdOf } from '@venizia/vulcan-atlas';
1
+ import { OFFICIAL_PRESETS, OfficialPresets } from '@venizia/vulcan-atlas';
2
2
  import { promptSelect, promptText } from '../ui/index.ts';
3
3
 
4
4
  const ANOTHER_PRESET = ':another-preset';
5
5
 
6
6
  /** A preset a project recorded: what `--preset` takes back, the side it builds, what it is. */
7
- export interface IKnownPreset {
7
+ interface IKnownPreset {
8
8
  spec: string;
9
9
  side: string;
10
10
  summary: string;
@@ -16,7 +16,7 @@ export interface IKnownPreset {
16
16
  * or `file:` path. null when the user cancelled.
17
17
  */
18
18
  export const askPresetSpec = async (opts: { recorded: IKnownPreset[] }): Promise<string | null> => {
19
- const used = new Set(opts.recorded.map((entry) => officialIdOf({ spec: entry.spec })));
19
+ const used = new Set(opts.recorded.map((entry) => OfficialPresets.idOf({ spec: entry.spec })));
20
20
  const picked = await promptSelect({
21
21
  message: 'Which preset?',
22
22
  choices: [
@@ -9,10 +9,10 @@ import {
9
9
  statSync,
10
10
  writeFileSync,
11
11
  } from 'node:fs';
12
- import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
12
+ import { basename, dirname, join, resolve } from 'node:path';
13
13
  import { z } from 'zod';
14
14
  import { readProperty } from '../common/index.ts';
15
- import { AppSides, CreateConstants } from './common/index.ts';
15
+ import { AppSides, CreateConstants, PresetPath } from './common/index.ts';
16
16
  import type { ILocatedPreset, IPresetSpec, TAppSide, TPresetResult } from './common/index.ts';
17
17
 
18
18
  const PRESET_SCHEMA = z
@@ -61,23 +61,17 @@ const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
61
61
  const EXECUTABLE_BITS = 0o111;
62
62
  const PERMISSION_BITS = 0o777;
63
63
 
64
- const escapes = (opts: { root: string; path: string }): boolean => {
65
- const relativePath = relative(opts.root, opts.path);
66
-
67
- return isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith(`..${sep}`);
68
- };
69
-
70
64
  /** A path a preset names must stay inside its own package, with symlinks resolved. */
71
65
  const resolveInside = (opts: { root: string; from: string; path: string }): string | undefined => {
72
66
  const resolved = resolve(opts.from, opts.path);
73
67
 
74
- if (escapes({ root: opts.root, path: resolved })) {
68
+ if (PresetPath.escapes({ root: opts.root, path: resolved })) {
75
69
  return undefined;
76
70
  }
77
71
 
78
72
  if (
79
73
  existsSync(resolved) &&
80
- escapes({ root: realpathSync(opts.root), path: realpathSync(resolved) })
74
+ PresetPath.escapes({ root: realpathSync(opts.root), path: realpathSync(resolved) })
81
75
  ) {
82
76
  return undefined;
83
77
  }
@@ -169,6 +163,7 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
169
163
  const presets = readProperty({ value: vulcan, key: 'presets' });
170
164
  const field = readProperty({ value: presets, key: 'app' });
171
165
  const libField = readProperty({ value: presets, key: 'lib' });
166
+ const sharedField = readProperty({ value: presets, key: 'shared' });
172
167
 
173
168
  if (typeof field !== 'string') {
174
169
  return {
@@ -238,9 +233,22 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
238
233
  };
239
234
  }
240
235
 
236
+ const sharedFile =
237
+ typeof sharedField === 'string'
238
+ ? resolveInside({ root: packageRoot, from: packageRoot, path: sharedField })
239
+ : undefined;
240
+
241
+ if (typeof sharedField === 'string' && sharedFile === undefined) {
242
+ return {
243
+ ok: false,
244
+ error: `${shown}: vulcan.presets.shared ${sharedField} points outside the package`,
245
+ };
246
+ }
247
+
241
248
  const located: ILocatedPreset = {
242
249
  preset,
243
250
  ...(libFile === undefined ? {} : { libFile }),
251
+ ...(sharedFile === undefined ? {} : { sharedFile }),
244
252
  packageRoot,
245
253
  packageName,
246
254
  packageVersion,
@@ -11,7 +11,7 @@ export const bunExecutable = (): string => process.env[CreateConstants.BUN_ENV]
11
11
  * Any command, under the same skip rule as `runBun`; a skipped one counts as done. A quiet command
12
12
  * prints nothing while it runs: its output is kept and written only when it fails.
13
13
  */
14
- export const runCommand = async (opts: {
14
+ const runCommand = async (opts: {
15
15
  cwd: string;
16
16
  command: string[];
17
17
  label: string;
@@ -73,11 +73,13 @@ export const runGitInit = async (opts: { cwd: string }): Promise<number> => {
73
73
  let code: number = ExitCodes.FAILURE;
74
74
 
75
75
  try {
76
- code = await runCommand({
76
+ const exitCode = await runCommand({
77
77
  cwd: opts.cwd,
78
78
  command: [git, 'init', '-q', '-b', 'develop'],
79
79
  label: 'git init',
80
80
  });
81
+
82
+ code = exitCode;
81
83
  } catch {
82
84
  // Bun.spawn throws when the executable is not there; the message below says what to do.
83
85
  }