@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
@@ -2,27 +2,21 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import type { TConstValue } from '../common/index.ts';
4
4
  import { ExitCodes } from '../common/index.ts';
5
- import { layoutFoldersOf } from '../common/layout-folder.ts';
5
+ import { LayoutFolder } from '../common/layout-folder.ts';
6
6
  import type { ILayout } from '../common/layout-folder.ts';
7
- import { LibraryKinds, loadConfig, PackageKinds, resolvePackages } from '../config/index.ts';
7
+ import { ConfigLoader, LibraryKinds, PackageKinds, ProjectPackages } from '../config/index.ts';
8
8
  import type { IProjectPackage, TLibraryKind } from '../config/index.ts';
9
- import { locate, resolveApiUrl } from './add-app.ts';
9
+ import { AppScaffold } from './add-app.ts';
10
10
  import { AppSides, CreateConstants, CreateFlags, PresetDiffStatuses } from './common/index.ts';
11
11
  import type { ILocatedPreset, IRecordedPreset, IPresetSpec, TAppSide } from './common/index.ts';
12
- import { diffLines } from './diff.ts';
12
+ import { LineDiff } from './diff.ts';
13
13
  import type { ILineDiff } from './diff.ts';
14
- import { readLibPreset } from './lib-preset.ts';
15
- import { readFlag } from './names.ts';
16
- import {
17
- decodeText,
18
- locatePreset,
19
- parsePresetSpec,
20
- readJson,
21
- renderPresetFiles,
22
- } from './preset.ts';
14
+ import { LibPreset } from './lib-preset.ts';
15
+ import { ProjectNames } from './names.ts';
16
+ import { Preset } from './preset.ts';
23
17
  import type { IRenderedPresetFile } from './preset.ts';
24
- import { withScratch } from './scratch.ts';
25
- import { readPort } from './workspace.ts';
18
+ import { PresetScratch } from './scratch.ts';
19
+ import { PortRegistry } from './workspace.ts';
26
20
 
27
21
  const SUBCOMMAND = 'diff';
28
22
  const USAGE = `usage: vulcan preset ${SUBCOMMAND} <package> [--preset <name|file:path>] [--api <backend app> | --no-api] [--full] [--check]`;
@@ -44,116 +38,30 @@ const sideOf = (opts: { layout: ILayout; path: string }): TAppSide | undefined =
44
38
  const isIn = (side: { folders: string[] }): boolean =>
45
39
  side.folders.some((folder) => opts.path.startsWith(`${folder}/`));
46
40
 
47
- if (isIn({ folders: layoutFoldersOf({ value: opts.layout.backend }) })) {
41
+ if (isIn({ folders: LayoutFolder.layoutFoldersOf({ value: opts.layout.backend }) })) {
48
42
  return AppSides.BACKEND;
49
43
  }
50
44
 
51
- return isIn({ folders: layoutFoldersOf({ value: opts.layout.frontend }) })
45
+ return isIn({ folders: LayoutFolder.layoutFoldersOf({ value: opts.layout.frontend }) })
52
46
  ? AppSides.FRONTEND
53
47
  : undefined;
54
48
  };
55
49
 
56
50
  /** The npm package a preset spec stands for: the name in it, or the name inside the folder of a `file:` spec. */
57
51
  const packageNameOf = (opts: { spec: string; root: string }): string | undefined => {
58
- const parsed = parsePresetSpec({ value: opts.spec, cwd: opts.root });
52
+ const parsed = Preset.parseSpec({ value: opts.spec, cwd: opts.root });
59
53
 
60
54
  if (parsed.packageName !== undefined) {
61
55
  return parsed.packageName;
62
56
  }
63
57
 
64
- const name = readJson({
58
+ const name = Preset.readJson({
65
59
  file: join(parsed.range.slice(CreateConstants.PRESET_FILE_PREFIX.length), 'package.json'),
66
60
  })?.['name'];
67
61
 
68
62
  return typeof name === 'string' ? name : undefined;
69
63
  };
70
64
 
71
- /**
72
- * The recorded preset an app came from: `add` writes the preset's package into the app's dependencies,
73
- * and the config records the presets of the project, so the one of the app's side whose package the app
74
- * depends on is it. Records of one package under two specs (`api`, then `api@2`) are one preset.
75
- * Nothing else is guessed: no match, or two packages, asks for `--preset`.
76
- */
77
- export const detectPreset = (opts: {
78
- root: string;
79
- recorded: IRecordedPreset[];
80
- dependencies: string[];
81
- side: TAppSide;
82
- }): { ok: true; spec: string } | { ok: false; error: string } => {
83
- const matching = new Map<string, string>();
84
-
85
- for (const preset of opts.recorded) {
86
- const name = packageNameOf({ spec: preset.spec, root: opts.root });
87
-
88
- if (preset.side === opts.side && name !== undefined && opts.dependencies.includes(name)) {
89
- // The last record of a package wins: it is the newest spec `add` wrote.
90
- matching.set(name, preset.spec);
91
- }
92
- }
93
-
94
- const [only] = [...matching.values()];
95
-
96
- if (matching.size === 1 && only !== undefined) {
97
- return { ok: true, spec: only };
98
- }
99
-
100
- const known =
101
- opts.recorded.length === 0
102
- ? 'the config records no preset'
103
- : `recorded: ${opts.recorded.map((preset) => preset.spec).join(', ')}`;
104
-
105
- return {
106
- ok: false,
107
- error: `${matching.size === 0 ? "no recorded preset of the app's side is a dependency of the app" : 'more than one recorded preset fits the app'} (${known}) - say which with ${CreateFlags.PRESET} <name|file:path>`,
108
- };
109
- };
110
-
111
- interface IPresetFileReport {
112
- path: string;
113
- status: TConstValue<typeof PresetDiffStatuses>;
114
- diff?: ILineDiff;
115
- /** Both files are not text, so there is a status and no diff. */
116
- isBinary?: boolean;
117
- /** The app has a folder where the preset has a file. */
118
- isFolder?: boolean;
119
- }
120
-
121
- /** Each file the preset makes, set against the file the app has at the same path. Reads only. */
122
- export const comparePresetFiles = (opts: {
123
- rendered: IRenderedPresetFile[];
124
- appDirectory: string;
125
- }): IPresetFileReport[] =>
126
- [...opts.rendered]
127
- .sort((first, second) => first.path.localeCompare(second.path))
128
- .map((file): IPresetFileReport => {
129
- const target = join(opts.appDirectory, file.path);
130
-
131
- if (!existsSync(target)) {
132
- return { path: file.path, status: PresetDiffStatuses.MISSING };
133
- }
134
-
135
- if (statSync(target).isDirectory()) {
136
- return { path: file.path, status: PresetDiffStatuses.DIFFERS, isFolder: true };
137
- }
138
-
139
- const current = readFileSync(target);
140
-
141
- if (current.equals(file.content)) {
142
- return { path: file.path, status: PresetDiffStatuses.SAME };
143
- }
144
-
145
- const currentText = decodeText({ content: current });
146
- const presetText = decodeText({ content: file.content });
147
-
148
- return currentText === undefined || presetText === undefined
149
- ? { path: file.path, status: PresetDiffStatuses.DIFFERS, isBinary: true }
150
- : {
151
- path: file.path,
152
- status: PresetDiffStatuses.DIFFERS,
153
- diff: diffLines({ current: currentText, preset: presetText }),
154
- };
155
- });
156
-
157
65
  const describeDifference = (opts: { report: IPresetFileReport; subject: string }): string => {
158
66
  const { diff, isBinary, isFolder } = opts.report;
159
67
 
@@ -228,7 +136,7 @@ const readValue = (opts: {
228
136
  return { ok: true, value: undefined };
229
137
  }
230
138
 
231
- const value = readFlag({ args: opts.args, flag: opts.flag });
139
+ const value = ProjectNames.readFlag({ args: opts.args, flag: opts.flag });
232
140
 
233
141
  if (count > 1) {
234
142
  return { ok: false, error: `${opts.flag} is given more than once` };
@@ -241,9 +149,9 @@ const readValue = (opts: {
241
149
 
242
150
  /** The installed copy of an npm preset: in the app's own `node_modules` (bun's isolated linker) or the monorepo root's. */
243
151
  const locateInstalled = (opts: { spec: IPresetSpec; appDirectory: string; root: string }) => {
244
- const inApp = locatePreset({ spec: opts.spec, root: opts.appDirectory });
152
+ const inApp = Preset.locate({ spec: opts.spec, root: opts.appDirectory });
245
153
 
246
- return inApp.ok ? inApp : locatePreset({ spec: opts.spec, root: opts.root });
154
+ return inApp.ok ? inApp : Preset.locate({ spec: opts.spec, root: opts.root });
247
155
  };
248
156
 
249
157
  /** Finds the preset (the `--preset` value, else the detected spec) where it lives and hands it to `compare`. */
@@ -257,15 +165,15 @@ const locateAndCompare = async (opts: {
257
165
  }): Promise<number> => {
258
166
  const { cwd, compare } = opts;
259
167
  const value = opts.flagValue ?? opts.detectedSpec ?? '';
260
- const spec = parsePresetSpec({ value, cwd });
168
+ const spec = Preset.parseSpec({ value, cwd });
261
169
  // `name@range` is fetched; a bare name, a detected spec or a `file:` folder is read where it already is.
262
170
  const isFetched = opts.flagValue !== undefined && opts.flagValue.lastIndexOf('@') > 0;
263
171
 
264
172
  if (isFetched) {
265
- return withScratch({
173
+ return PresetScratch.withScratch({
266
174
  root: cwd,
267
175
  run: async (scratch) => {
268
- const located = await locate({ cwd, scratch, spec });
176
+ const located = await AppScaffold.locate({ cwd, scratch, spec });
269
177
 
270
178
  return located.ok
271
179
  ? compare({
@@ -279,7 +187,7 @@ const locateAndCompare = async (opts: {
279
187
 
280
188
  const located =
281
189
  spec.packageName === undefined
282
- ? locatePreset({ spec, root: cwd })
190
+ ? Preset.locate({ spec, root: cwd })
283
191
  : locateInstalled({ spec, appDirectory: opts.packageDirectory, root: cwd });
284
192
 
285
193
  if (!located.ok) {
@@ -298,11 +206,12 @@ const locateAndCompare = async (opts: {
298
206
  };
299
207
 
300
208
  const PRESET_HINT = `say which with ${CreateFlags.PRESET} <name|file:path>`;
209
+
301
210
  const MANIFEST_FILE = 'package.json';
302
211
 
303
212
  /**
304
213
  * 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
214
+ * once, as `PresetDiff.detect` does) whose record ships the package's kind. A package made by the shared kind
306
215
  * never takes a lib kind and the reverse, so nothing falls back to the other kind.
307
216
  */
308
217
  const detectLibraryPreset = (opts: {
@@ -341,81 +250,6 @@ const detectLibraryPreset = (opts: {
341
250
  };
342
251
  };
343
252
 
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
253
  /** The refusal for a name that is no package of the config: it lists the apps and the libraries there are. */
420
254
  const reportNotFound = (opts: { packages: IProjectPackage[]; packageName: string }): number => {
421
255
  const namesOf = (query: { isLibrary: boolean }): string[] =>
@@ -434,150 +268,314 @@ const reportNotFound = (opts: { packages: IProjectPackage[]; packageName: string
434
268
  });
435
269
  };
436
270
 
437
- export const runPresetDiff = async (opts: { cwd: string; args: string[] }): Promise<number> => {
438
- const { cwd, args } = opts;
439
- const positionals = args.filter(
440
- (arg, index) => !arg.startsWith('-') && !VALUE_FLAGS.includes(args[index - 1] ?? ''),
441
- );
442
- const [subcommand, packageName] = positionals;
271
+ export class PresetDiff {
272
+ /**
273
+ * `preset diff` of a package whose config entry has `kind: 'lib'`: the files of the preset kind that made it
274
+ * (`presetKind`, absent means `lib`), rendered with that kind's tokens, set against the package's folder.
275
+ */
276
+ private static async diffLibrary(opts: {
277
+ cwd: string;
278
+ args: string[];
279
+ library: IProjectPackage;
280
+ kind: TLibraryKind;
281
+ recorded: IRecordedPreset[];
282
+ configName: string | undefined;
283
+ presetValue: string | undefined;
284
+ }): Promise<number> {
285
+ const { cwd, args, library, kind } = opts;
286
+ const noun = kind === LibraryKinds.SHARED ? 'shared package' : 'library';
287
+
288
+ for (const flag of [CreateFlags.API, CreateFlags.NO_API]) {
289
+ if (args.includes(flag)) {
290
+ return fail({
291
+ message: `${library.dir} is a ${noun}: it has no proxy target, so ${flag} does not apply`,
292
+ });
293
+ }
294
+ }
443
295
 
444
- if (subcommand !== SUBCOMMAND || packageName === undefined) {
445
- return fail({ message: USAGE });
446
- }
296
+ const detected =
297
+ opts.presetValue === undefined
298
+ ? detectLibraryPreset({ root: cwd, recorded: opts.recorded, kind })
299
+ : undefined;
447
300
 
448
- const presetFlag = readValue({ args, flag: CreateFlags.PRESET });
449
- const apiFlag = readValue({ args, flag: CreateFlags.API });
301
+ if (detected !== undefined && !detected.ok) {
302
+ return fail({ message: detected.error });
303
+ }
450
304
 
451
- if (!presetFlag.ok || !apiFlag.ok) {
452
- return fail({ message: !presetFlag.ok ? presetFlag.error : apiFlag.ok ? '' : apiFlag.error });
453
- }
305
+ const rootManifest = Preset.readJson({ file: join(cwd, MANIFEST_FILE) });
306
+ const rootName = rootManifest?.['name'];
307
+ const project = opts.configName ?? (typeof rootName === 'string' ? rootName : library.dir);
308
+ const directory = join(cwd, library.path);
454
309
 
455
- const loaded = await loadConfig({ root: cwd });
310
+ return locateAndCompare({
311
+ cwd,
312
+ flagValue: opts.presetValue,
313
+ detectedSpec: detected?.ok === true ? detected.spec : undefined,
314
+ packageDirectory: directory,
315
+ compare: async ({ located, source }) => {
316
+ const read = LibPreset.read({ located, kind });
317
+
318
+ if (!read.ok) {
319
+ return fail({ message: `${read.error} (${library.dir} is a ${noun})` });
320
+ }
321
+
322
+ // A package.json among the files is skipped: add replaces it with a generated one.
323
+ const rendered = Preset.renderFiles({
324
+ located,
325
+ files: read.lib.files,
326
+ tokens: { project, [kind]: library.dir, package: library.name },
327
+ }).filter((file) => file.path !== MANIFEST_FILE);
328
+ const reports = PresetDiff.compareFiles({ rendered, appDirectory: directory });
329
+
330
+ printReport({
331
+ appPath: library.path,
332
+ subject: PACKAGE_SUBJECT,
333
+ located,
334
+ source,
335
+ reports,
336
+ isFull: args.includes(CreateFlags.FULL),
337
+ });
456
338
 
457
- if (!loaded.ok) {
458
- return fail({
459
- message:
460
- loaded.file === undefined
461
- ? 'run it at the root of a monorepo vulcan init created (no .configs/vulcan.config.*)'
462
- : loaded.error,
339
+ return args.includes(CreateFlags.CHECK) &&
340
+ reports.some((report) => report.status !== PresetDiffStatuses.SAME)
341
+ ? ExitCodes.FAILURE
342
+ : ExitCodes.OK;
343
+ },
463
344
  });
464
345
  }
465
346
 
466
- const { config } = loaded;
467
- const packages = resolvePackages({ config });
468
- const app = packages.find((entry) => entry.dir === packageName || entry.path === packageName);
347
+ /**
348
+ * The recorded preset an app came from: `add` writes the preset's package into the app's dependencies,
349
+ * and the config records the presets of the project, so the one of the app's side whose package the app
350
+ * depends on is it. Records of one package under two specs (`api`, then `api@2`) are one preset.
351
+ * Nothing else is guessed: no match, or two packages, asks for `--preset`.
352
+ */
353
+ static detect(opts: {
354
+ root: string;
355
+ recorded: IRecordedPreset[];
356
+ dependencies: string[];
357
+ side: TAppSide;
358
+ }): { ok: true; spec: string } | { ok: false; error: string } {
359
+ const matching = new Map<string, string>();
360
+
361
+ for (const preset of opts.recorded) {
362
+ const name = packageNameOf({ spec: preset.spec, root: opts.root });
363
+
364
+ if (preset.side === opts.side && name !== undefined && opts.dependencies.includes(name)) {
365
+ // The last record of a package wins: it is the newest spec `add` wrote.
366
+ matching.set(name, preset.spec);
367
+ }
368
+ }
469
369
 
470
- if (app === undefined) {
471
- return reportNotFound({ packages, packageName });
472
- }
370
+ const [only] = [...matching.values()];
473
371
 
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,
483
- });
372
+ if (matching.size === 1 && only !== undefined) {
373
+ return { ok: true, spec: only };
374
+ }
375
+
376
+ const known =
377
+ opts.recorded.length === 0
378
+ ? 'the config records no preset'
379
+ : `recorded: ${opts.recorded.map((preset) => preset.spec).join(', ')}`;
380
+
381
+ return {
382
+ ok: false,
383
+ error: `${matching.size === 0 ? "no recorded preset of the app's side is a dependency of the app" : 'more than one recorded preset fits the app'} (${known}) - say which with ${CreateFlags.PRESET} <name|file:path>`,
384
+ };
484
385
  }
485
386
 
486
- if (config.layout === undefined) {
487
- return reportNotFound({ packages, packageName });
387
+ /** Each file the preset makes, set against the file the app has at the same path. Reads only. */
388
+ static compareFiles(opts: {
389
+ rendered: IRenderedPresetFile[];
390
+ appDirectory: string;
391
+ }): IPresetFileReport[] {
392
+ return [...opts.rendered]
393
+ .sort((first, second) => first.path.localeCompare(second.path))
394
+ .map((file): IPresetFileReport => {
395
+ const target = join(opts.appDirectory, file.path);
396
+
397
+ if (!existsSync(target)) {
398
+ return { path: file.path, status: PresetDiffStatuses.MISSING };
399
+ }
400
+
401
+ if (statSync(target).isDirectory()) {
402
+ return { path: file.path, status: PresetDiffStatuses.DIFFERS, isFolder: true };
403
+ }
404
+
405
+ const current = readFileSync(target);
406
+
407
+ if (current.equals(file.content)) {
408
+ return { path: file.path, status: PresetDiffStatuses.SAME };
409
+ }
410
+
411
+ const currentText = Preset.decodeText({ content: current });
412
+ const presetText = Preset.decodeText({ content: file.content });
413
+
414
+ return currentText === undefined || presetText === undefined
415
+ ? { path: file.path, status: PresetDiffStatuses.DIFFERS, isBinary: true }
416
+ : {
417
+ path: file.path,
418
+ status: PresetDiffStatuses.DIFFERS,
419
+ diff: LineDiff.diff({ current: currentText, preset: presetText }),
420
+ };
421
+ });
488
422
  }
489
423
 
490
- const side = sideOf({ layout: config.layout, path: app.path });
424
+ static async run(opts: { cwd: string; args: string[] }): Promise<number> {
425
+ const { cwd, args } = opts;
426
+ const positionals = args.filter(
427
+ (arg, index) => !arg.startsWith('-') && !VALUE_FLAGS.includes(args[index - 1] ?? ''),
428
+ );
429
+ const [subcommand, packageName] = positionals;
491
430
 
492
- if (side === undefined) {
493
- return fail({ message: `${app.path} is not in a backend or frontend folder of the layout` });
494
- }
431
+ if (subcommand !== SUBCOMMAND || packageName === undefined) {
432
+ return fail({ message: USAGE });
433
+ }
495
434
 
496
- const appDirectory = join(cwd, app.path);
497
- const appManifest = readJson({ file: join(appDirectory, 'package.json') });
435
+ const presetFlag = readValue({ args, flag: CreateFlags.PRESET });
436
+ const apiFlag = readValue({ args, flag: CreateFlags.API });
498
437
 
499
- if (appManifest === undefined) {
500
- return fail({ message: `${app.path}/package.json is missing or not JSON` });
501
- }
438
+ if (!presetFlag.ok || !apiFlag.ok) {
439
+ return fail({ message: !presetFlag.ok ? presetFlag.error : apiFlag.ok ? '' : apiFlag.error });
440
+ }
502
441
 
503
- const dependencies = appManifest['dependencies'];
504
- const detected =
505
- presetFlag.value === undefined
506
- ? detectPreset({
507
- root: cwd,
508
- recorded: config.presets ?? [],
509
- dependencies: Object.keys(
510
- typeof dependencies === 'object' && dependencies !== null ? dependencies : {},
511
- ),
512
- side,
513
- })
514
- : undefined;
442
+ const loaded = await ConfigLoader.load({ root: cwd });
515
443
 
516
- if (detected !== undefined && !detected.ok) {
517
- return fail({ message: detected.error });
518
- }
444
+ if (!loaded.ok) {
445
+ return fail({
446
+ message:
447
+ loaded.file === undefined
448
+ ? 'run it at the root of a monorepo vulcan init created (no .configs/vulcan.config.*)'
449
+ : loaded.error,
450
+ });
451
+ }
519
452
 
520
- const rootManifest = readJson({ file: join(cwd, 'package.json') });
521
- const project =
522
- config.name ?? (typeof rootManifest?.['name'] === 'string' ? rootManifest['name'] : app.dir);
523
- const envFile = join(appDirectory, '.env.example');
524
- const ownPort = existsSync(envFile)
525
- ? readPort({ envExample: readFileSync(envFile, 'utf8') })
526
- : undefined;
453
+ const { config } = loaded;
454
+ const packages = ProjectPackages.resolve({ config });
455
+ const app = packages.find((entry) => entry.dir === packageName || entry.path === packageName);
527
456
 
528
- const compare = async (found: { located: ILocatedPreset; source: string }): Promise<number> => {
529
- const { located } = found;
530
- const tokens: Record<string, string> = {
531
- project,
532
- app: app.dir,
533
- appPath: app.path,
534
- devPort: String(ownPort ?? located.preset.devPort),
535
- };
536
- let rendered = renderPresetFiles({ located, tokens });
537
- const usesApiUrl = rendered.some((file) =>
538
- (decodeText({ content: file.content }) ?? '').includes(API_URL_TOKEN),
539
- );
457
+ if (app === undefined) {
458
+ return reportNotFound({ packages, packageName });
459
+ }
540
460
 
541
- if (usesApiUrl) {
542
- const api = await resolveApiUrl({
543
- root: cwd,
461
+ if (app.kind === PackageKinds.LIB) {
462
+ return PresetDiff.diffLibrary({
463
+ cwd,
544
464
  args,
545
- interactive: false,
546
- backendFolders: layoutFoldersOf({ value: config.layout?.backend }),
547
- packages,
465
+ library: app,
466
+ kind: app.presetKind ?? LibraryKinds.LIB,
467
+ recorded: config.presets ?? [],
468
+ configName: config.name,
469
+ presetValue: presetFlag.value,
548
470
  });
471
+ }
549
472
 
550
- if (!api.ok) {
551
- return fail({
552
- message: `${api.error} (the files of this preset use the proxy target, as they did when add made the app)`,
473
+ if (config.layout === undefined) {
474
+ return reportNotFound({ packages, packageName });
475
+ }
476
+
477
+ const side = sideOf({ layout: config.layout, path: app.path });
478
+
479
+ if (side === undefined) {
480
+ return fail({ message: `${app.path} is not in a backend or frontend folder of the layout` });
481
+ }
482
+
483
+ const appDirectory = join(cwd, app.path);
484
+ const appManifest = Preset.readJson({ file: join(appDirectory, 'package.json') });
485
+
486
+ if (appManifest === undefined) {
487
+ return fail({ message: `${app.path}/package.json is missing or not JSON` });
488
+ }
489
+
490
+ const dependencies = appManifest['dependencies'];
491
+ const detected =
492
+ presetFlag.value === undefined
493
+ ? PresetDiff.detect({
494
+ root: cwd,
495
+ recorded: config.presets ?? [],
496
+ dependencies: Object.keys(
497
+ typeof dependencies === 'object' && dependencies !== null ? dependencies : {},
498
+ ),
499
+ side,
500
+ })
501
+ : undefined;
502
+
503
+ if (detected !== undefined && !detected.ok) {
504
+ return fail({ message: detected.error });
505
+ }
506
+
507
+ const rootManifest = Preset.readJson({ file: join(cwd, 'package.json') });
508
+ const project =
509
+ config.name ?? (typeof rootManifest?.['name'] === 'string' ? rootManifest['name'] : app.dir);
510
+ const envFile = join(appDirectory, '.env.example');
511
+ const ownPort = existsSync(envFile)
512
+ ? PortRegistry.read({ envExample: readFileSync(envFile, 'utf8') })
513
+ : undefined;
514
+
515
+ const compare = async (found: { located: ILocatedPreset; source: string }): Promise<number> => {
516
+ const { located } = found;
517
+ const tokens: Record<string, string> = {
518
+ project,
519
+ app: app.dir,
520
+ appPath: app.path,
521
+ devPort: String(ownPort ?? located.preset.devPort),
522
+ };
523
+ let rendered = Preset.renderFiles({ located, tokens });
524
+ const usesApiUrl = rendered.some((file) =>
525
+ (Preset.decodeText({ content: file.content }) ?? '').includes(API_URL_TOKEN),
526
+ );
527
+
528
+ if (usesApiUrl) {
529
+ const api = await AppScaffold.resolveApiUrl({
530
+ root: cwd,
531
+ args,
532
+ interactive: false,
533
+ backendFolders: LayoutFolder.layoutFoldersOf({ value: config.layout?.backend }),
534
+ packages,
553
535
  });
536
+
537
+ if (!api.ok) {
538
+ return fail({
539
+ message: `${api.error} (the files of this preset use the proxy target, as they did when add made the app)`,
540
+ });
541
+ }
542
+
543
+ rendered = Preset.renderFiles({ located, tokens: { ...tokens, apiUrl: api.apiUrl } });
554
544
  }
555
545
 
556
- rendered = renderPresetFiles({ located, tokens: { ...tokens, apiUrl: api.apiUrl } });
557
- }
546
+ const reports = PresetDiff.compareFiles({ rendered, appDirectory });
558
547
 
559
- const reports = comparePresetFiles({ rendered, appDirectory });
548
+ printReport({
549
+ appPath: app.path,
550
+ subject: APP_SUBJECT,
551
+ located,
552
+ source: found.source,
553
+ reports,
554
+ isFull: args.includes(CreateFlags.FULL),
555
+ });
560
556
 
561
- printReport({
562
- appPath: app.path,
563
- subject: APP_SUBJECT,
564
- located,
565
- source: found.source,
566
- reports,
567
- isFull: args.includes(CreateFlags.FULL),
568
- });
557
+ return args.includes(CreateFlags.CHECK) &&
558
+ reports.some((report) => report.status !== PresetDiffStatuses.SAME)
559
+ ? ExitCodes.FAILURE
560
+ : ExitCodes.OK;
561
+ };
569
562
 
570
- return args.includes(CreateFlags.CHECK) &&
571
- reports.some((report) => report.status !== PresetDiffStatuses.SAME)
572
- ? ExitCodes.FAILURE
573
- : ExitCodes.OK;
574
- };
563
+ return locateAndCompare({
564
+ cwd,
565
+ flagValue: presetFlag.value,
566
+ detectedSpec: detected?.ok === true ? detected.spec : undefined,
567
+ packageDirectory: appDirectory,
568
+ compare,
569
+ });
570
+ }
571
+ }
575
572
 
576
- return locateAndCompare({
577
- cwd,
578
- flagValue: presetFlag.value,
579
- detectedSpec: detected?.ok === true ? detected.spec : undefined,
580
- packageDirectory: appDirectory,
581
- compare,
582
- });
583
- };
573
+ interface IPresetFileReport {
574
+ path: string;
575
+ status: TConstValue<typeof PresetDiffStatuses>;
576
+ diff?: ILineDiff;
577
+ /** Both files are not text, so there is a status and no diff. */
578
+ isBinary?: boolean;
579
+ /** The app has a folder where the preset has a file. */
580
+ isFolder?: boolean;
581
+ }