@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
@@ -10,12 +10,14 @@ import {
10
10
  withLayoutFolder,
11
11
  } from '../common/layout-folder.ts';
12
12
  import type { ILayout } from '../common/layout-folder.ts';
13
- import { loadConfig, resolvePackages } from '../config/index.ts';
14
- import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
13
+ import { OFFICIAL_PRESETS, OfficialPresets } from '@venizia/vulcan-atlas';
14
+ import type { IOfficialPreset } from '@venizia/vulcan-atlas';
15
+ import { LibraryKinds, loadConfig, PackageKinds, resolvePackages } from '../config/index.ts';
16
+ import type { IProjectPackage, TLibraryKind, TResolvedConfig } from '../config/index.ts';
15
17
  import { readWorkspaceGlobs } from '../init/index.ts';
16
18
  import { addLibrary } from './add-lib.ts';
17
19
  import { runAppChecks } from './checks.ts';
18
- import { AppSides, AppsBlockProblems, CreateFlags } from './common/index.ts';
20
+ import { AddFailure, AppSides, AppsBlockProblems, CreateFlags } from './common/index.ts';
19
21
  import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
20
22
  import { writeFile } from './files.ts';
21
23
  import { recordedPresetOf } from './lib-preset.ts';
@@ -62,12 +64,6 @@ const ROOT_HINT =
62
64
 
63
65
  const MISSING_API = `missing ${CreateFlags.API} <app> or ${CreateFlags.NO_API}`;
64
66
 
65
- const fail = (opts: { message: string }): number => {
66
- process.stderr.write(`vulcan add: ${opts.message}\n`);
67
-
68
- return ExitCodes.FAILURE;
69
- };
70
-
71
67
  /** The side the flags give away: a frontend flag, or only the backend folder; undefined when they do not say. */
72
68
  const sideNamedBy = (opts: { args: string[] }): TAppSide | undefined => {
73
69
  const frontend = [CreateFlags.FRONTEND_DIR, CreateFlags.API, CreateFlags.NO_API].some((flag) =>
@@ -115,26 +111,93 @@ const missingFlag = (opts: { args: string[]; layout: ILayout }): string | undefi
115
111
  return side === AppSides.FRONTEND && !hasApi ? MISSING_API : undefined;
116
112
  };
117
113
 
118
- /** The two commands a project can run for this preset: what `add` prints when it is not told what to create. */
119
- const kindCommands = (opts: { presetValue: string }): string[] => [
120
- `bun x --no-install vulcan add --preset ${opts.presetValue} ${CreateFlags.APP} <name>`,
121
- `bun x --no-install vulcan add --preset ${opts.presetValue} ${CreateFlags.LIB} <name>`,
122
- ];
114
+ /** What `add` makes: an app, or one of the library kinds. */
115
+ type TAddKind = typeof PackageKinds.APP | TLibraryKind;
116
+
117
+ /** Per kind: the flag that names it and the words a menu and a message describe it with. */
118
+ const ADD_KINDS: Record<TAddKind, { flag: string; hint: string }> = {
119
+ [PackageKinds.APP]: { flag: CreateFlags.APP, hint: 'a runnable app' },
120
+ [LibraryKinds.LIB]: { flag: CreateFlags.LIB, hint: 'a library other apps import' },
121
+ [LibraryKinds.SHARED]: {
122
+ flag: CreateFlags.SHARED,
123
+ hint: 'a side-neutral package other apps import',
124
+ },
125
+ };
126
+
127
+ const ADD_KIND_ORDER: TAddKind[] = [PackageKinds.APP, LibraryKinds.LIB, LibraryKinds.SHARED];
128
+
129
+ /** The commands a project can run for this preset: what `add` prints when it is not told what to create. */
130
+ const kindCommands = (opts: { presetValue: string }): string[] =>
131
+ ADD_KIND_ORDER.map(
132
+ (kind) =>
133
+ `bun x --no-install vulcan add --preset ${opts.presetValue} ${ADD_KINDS[kind].flag} <name>`,
134
+ );
123
135
 
124
136
  const NO_BACKEND = ':none';
125
- const KIND_HINTS: Record<string, string> = { app: 'a runnable app', lib: 'a shared package' };
126
137
 
127
- const SAY_WHAT = `say what to create - \`${CreateFlags.APP} <name>\` (a runnable app) or \`${CreateFlags.LIB} <name>\` (a shared package)`;
138
+ const DESCRIBED_KINDS = ADD_KIND_ORDER.map(
139
+ (kind) => `\`${ADD_KINDS[kind].flag} <name>\` (${ADD_KINDS[kind].hint})`,
140
+ );
141
+
142
+ const SAY_WHAT = `say what to create - ${DESCRIBED_KINDS.slice(0, -1).join(', ')} or ${DESCRIBED_KINDS.at(-1)}`;
143
+
144
+ /** The kinds a located preset makes: always an app, a library kind only when its file is there. */
145
+ const kindsOffered = (opts: { located: ILocatedPreset }): TAddKind[] => {
146
+ const hasFile: Record<TAddKind, boolean> = {
147
+ [PackageKinds.APP]: true,
148
+ [LibraryKinds.LIB]: opts.located.libFile !== undefined,
149
+ [LibraryKinds.SHARED]: opts.located.sharedFile !== undefined,
150
+ };
151
+
152
+ return ADD_KIND_ORDER.filter((kind) => hasFile[kind]);
153
+ };
154
+
155
+ /**
156
+ * Why a preset cannot make a shared package, and where one can be had: the presets this project recorded with a
157
+ * shared kind, then the official ones that have it. Nothing is invented: with none known it says so.
158
+ */
159
+ const noSharedKindMessage = (opts: {
160
+ located: ILocatedPreset;
161
+ recorded: TResolvedConfig['presets'];
162
+ name: string;
163
+ official?: IOfficialPreset[];
164
+ }): string => {
165
+ const { official = OFFICIAL_PRESETS } = opts;
166
+ const recorded = (opts.recorded ?? []).filter((preset) => preset.shared !== undefined);
167
+ const known = [
168
+ ...recorded.map((preset) => preset.spec),
169
+ ...official
170
+ .filter((preset) => preset.shared !== undefined)
171
+ .map((preset) => preset.id)
172
+ .filter(
173
+ (id) => !recorded.some((preset) => OfficialPresets.idOf({ spec: preset.spec }) === id),
174
+ ),
175
+ ];
176
+ const commands = known.map(
177
+ (spec) =>
178
+ `bun x --no-install vulcan add --preset ${spec} ${ADD_KINDS[LibraryKinds.SHARED].flag} ${opts.name}`,
179
+ );
180
+
181
+ return `preset ${opts.located.packageName} has no shared kind (it makes: ${kindsOffered({ located: opts.located }).join(' and ')}); ${
182
+ commands.length === 0
183
+ ? 'no preset known to this project or to the official list has one'
184
+ : `a preset with one: run ${commands.join(' or ')}`
185
+ }`;
186
+ };
128
187
 
129
188
  /** The terminal asks which kind, listing only what the preset offers; end of input stops the command. */
130
- const askKind = async (opts: { offered: string[] }): Promise<string | undefined> => {
189
+ const askKind = async (opts: { offered: TAddKind[] }): Promise<TAddKind | undefined> => {
131
190
  if (menusAvailable()) {
132
191
  const picked = await promptSelect({
133
192
  message: 'What do you want to create?',
134
- choices: opts.offered.map((kind) => ({ value: kind, label: kind, hint: KIND_HINTS[kind] })),
193
+ choices: opts.offered.map((kind) => ({
194
+ value: kind,
195
+ label: kind,
196
+ hint: ADD_KINDS[kind].hint,
197
+ })),
135
198
  });
136
199
 
137
- return picked ?? undefined;
200
+ return opts.offered.find((kind) => kind === picked);
138
201
  }
139
202
 
140
203
  for (;;) {
@@ -146,10 +209,10 @@ const askKind = async (opts: { offered: string[] }): Promise<string | undefined>
146
209
  return undefined;
147
210
  }
148
211
 
149
- const kind = answer.trim();
212
+ const chosen = opts.offered.find((kind) => kind === answer.trim());
150
213
 
151
- if (opts.offered.includes(kind)) {
152
- return kind;
214
+ if (chosen !== undefined) {
215
+ return chosen;
153
216
  }
154
217
  }
155
218
  };
@@ -298,24 +361,31 @@ const askPreset = async (opts: { cwd: string }): Promise<string | null> => {
298
361
  return askPresetSpec({ recorded: loaded.ok ? (loaded.config.presets ?? []) : [] });
299
362
  };
300
363
 
301
- const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): Promise<number> => {
364
+ const runAdd = async (opts: {
365
+ cwd: string;
366
+ args: string[];
367
+ scratch: string;
368
+ official?: IOfficialPreset[];
369
+ }): Promise<number> => {
302
370
  const { cwd } = opts;
303
371
  const flagged = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
304
372
 
305
373
  if (flagged === undefined && !menusAvailable()) {
306
- return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
374
+ return AddFailure.fail({ message: '--preset needs a value (a package name, or file:<path>)' });
307
375
  }
308
376
 
309
- const presetValue = flagged ?? (await askPreset({ cwd }))?.trim();
377
+ const askingPreset = flagged === undefined ? askPreset({ cwd }) : undefined;
378
+ const typedPreset = await askingPreset;
379
+ const presetValue = flagged ?? typedPreset?.trim();
310
380
 
311
381
  if (presetValue === undefined || presetValue === '') {
312
- return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
382
+ return AddFailure.fail({ message: '--preset needs a value (a package name, or file:<path>)' });
313
383
  }
314
384
 
315
385
  const loaded = await loadConfig({ root: cwd });
316
386
 
317
387
  if (!loaded.ok) {
318
- return fail({ message: loaded.file === undefined ? ROOT_HINT : loaded.error });
388
+ return AddFailure.fail({ message: loaded.file === undefined ? ROOT_HINT : loaded.error });
319
389
  }
320
390
 
321
391
  const config: TResolvedConfig = loaded.config;
@@ -324,77 +394,100 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
324
394
  const manifest = readRootManifest({ path: manifestPath });
325
395
 
326
396
  if (config.layout === undefined || manifest === undefined) {
327
- return fail({ message: ROOT_HINT });
397
+ return AddFailure.fail({ message: ROOT_HINT });
328
398
  }
329
399
 
330
400
  const interactive = process.stdin.isTTY === true;
331
- const libFlag = opts.args.includes(CreateFlags.LIB);
332
- const libName = readFlag({ args: opts.args, flag: CreateFlags.LIB });
333
- const appFlag = opts.args.includes(CreateFlags.APP);
401
+ const flaggedKinds = ADD_KIND_ORDER.filter((candidate) =>
402
+ opts.args.includes(ADD_KINDS[candidate].flag),
403
+ );
334
404
 
335
- if (libFlag && appFlag) {
336
- return fail({ message: `${CreateFlags.APP} and ${CreateFlags.LIB} cannot be used together` });
405
+ if (flaggedKinds.length > 1) {
406
+ return AddFailure.fail({
407
+ message: `${CreateFlags.APP}, ${CreateFlags.LIB} and ${CreateFlags.SHARED} cannot be used together`,
408
+ });
337
409
  }
338
410
 
411
+ const [flaggedKind] = flaggedKinds;
412
+ const flagsLibrary = flaggedKind !== undefined && flaggedKind !== PackageKinds.APP;
339
413
  const flaggedScope = readScope({ args: opts.args });
340
414
 
341
415
  if (!flaggedScope.ok) {
342
- return fail({ message: flaggedScope.error });
416
+ return AddFailure.fail({ message: flaggedScope.error });
343
417
  }
344
418
 
345
- if (libFlag && libName === undefined) {
346
- return fail({ message: `${CreateFlags.LIB} needs a name` });
419
+ if (
420
+ flagsLibrary &&
421
+ readFlag({ args: opts.args, flag: ADD_KINDS[flaggedKind].flag }) === undefined
422
+ ) {
423
+ return AddFailure.fail({ message: `${ADD_KINDS[flaggedKind].flag} needs a name` });
347
424
  }
348
425
 
349
426
  // Never a default kind: without a terminal to ask, nothing is fetched or written until the flag says which.
350
- if (!interactive && !libFlag && !appFlag) {
351
- return fail({
427
+ if (!interactive && flaggedKind === undefined) {
428
+ return AddFailure.fail({
352
429
  message: `${SAY_WHAT}\n ${kindCommands({ presetValue }).join('\n ')}`,
353
430
  });
354
431
  }
355
432
 
356
433
  const early =
357
- interactive || libFlag ? undefined : missingFlag({ args: opts.args, layout: config.layout });
434
+ interactive || flagsLibrary
435
+ ? undefined
436
+ : missingFlag({ args: opts.args, layout: config.layout });
358
437
 
359
438
  if (early !== undefined) {
360
- return fail({ message: early });
439
+ return AddFailure.fail({ message: early });
361
440
  }
362
441
 
363
442
  const spec = parsePresetSpec({ value: presetValue, cwd });
364
443
  const located = await locate({ cwd, scratch: opts.scratch, spec });
365
444
 
366
445
  if (!located.ok) {
367
- return fail({ message: located.error });
446
+ return AddFailure.fail({ message: located.error });
368
447
  }
369
448
 
370
449
  const { preset, packageName, packageVersion } = located.located;
371
450
  const recordedSpec = presetSpecOf({ value: presetValue, root: cwd, cwd });
372
- let kind = libFlag ? 'lib' : 'app';
451
+ let kind: TAddKind = flaggedKind ?? PackageKinds.APP;
452
+
453
+ if (flaggedKind === LibraryKinds.SHARED && located.located.sharedFile === undefined) {
454
+ return AddFailure.fail({
455
+ message: noSharedKindMessage({
456
+ located: located.located,
457
+ recorded: config.presets,
458
+ name: readFlag({ args: opts.args, flag: ADD_KINDS[flaggedKind].flag }) ?? '<name>',
459
+ official: opts.official,
460
+ }),
461
+ });
462
+ }
373
463
 
374
- if (!libFlag && !appFlag) {
375
- const offered = ['app', ...(located.located.libFile === undefined ? [] : ['lib'])];
376
- const chosen = offered.length === 1 ? 'app' : await askKind({ offered });
464
+ if (flaggedKind === undefined) {
465
+ const offered = kindsOffered({ located: located.located });
466
+ const askingKind = offered.length === 1 ? PackageKinds.APP : askKind({ offered });
467
+ const chosen = await askingKind;
377
468
 
378
469
  if (chosen === undefined) {
379
- return fail({ message: SAY_WHAT });
470
+ return AddFailure.fail({ message: SAY_WHAT });
380
471
  }
381
472
 
382
473
  kind = chosen;
383
474
  }
384
475
 
385
- if (kind === 'lib') {
386
- const name =
387
- libName ??
388
- (
389
- await askInTerminal({
390
- question: 'Name of this library',
391
- validate: (value) =>
392
- value.trim() === '' ? undefined : nameProblem({ name: value.trim() }),
393
- })
394
- )?.trim();
476
+ if (kind !== PackageKinds.APP) {
477
+ const flaggedName = readFlag({ args: opts.args, flag: ADD_KINDS[kind].flag });
478
+ const askingName =
479
+ flaggedName === undefined
480
+ ? askInTerminal({
481
+ question: 'Name of this library',
482
+ validate: (value) =>
483
+ value.trim() === '' ? undefined : nameProblem({ name: value.trim() }),
484
+ })
485
+ : undefined;
486
+ const typedName = await askingName;
487
+ const name = flaggedName ?? typedName?.trim();
395
488
 
396
489
  if (name === undefined || name === '') {
397
- return fail({ message: `${CreateFlags.LIB} needs a name` });
490
+ return AddFailure.fail({ message: `${ADD_KINDS[kind].flag} needs a name` });
398
491
  }
399
492
 
400
493
  return addLibrary({
@@ -410,6 +503,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
410
503
  manifest,
411
504
  packages: resolvePackages({ config }),
412
505
  libName: name,
506
+ kind,
413
507
  recorded: ({ block }) =>
414
508
  recordPreset({
415
509
  block,
@@ -422,10 +516,11 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
422
516
  const peerProblem = checkPeers({
423
517
  catalog: readCatalog({ manifest }),
424
518
  peers: preset.peers,
519
+ presetVersions: preset,
425
520
  });
426
521
 
427
522
  if (peerProblem !== undefined) {
428
- return fail({ message: peerProblem });
523
+ return AddFailure.fail({ message: peerProblem });
429
524
  }
430
525
 
431
526
  const side = preset.side;
@@ -448,7 +543,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
448
543
  });
449
544
 
450
545
  if (!names.ok) {
451
- return fail({ message: names.error });
546
+ return AddFailure.fail({ message: names.error });
452
547
  }
453
548
 
454
549
  const { folder, app } = names.names;
@@ -459,7 +554,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
459
554
 
460
555
  // One folder holds one kind of code: a folder another key already owns would mix them.
461
556
  if (otherSide !== undefined) {
462
- return fail({
557
+ return AddFailure.fail({
463
558
  message:
464
559
  otherSide[0] === LayoutKeys.OTHER
465
560
  ? `the ${side} folder '${folder}' is listed under layout.other in ${configPath}: folders the layout leaves alone are not app targets`
@@ -472,7 +567,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
472
567
 
473
568
  // A folder inside another (or around one) would give a package path two owners.
474
569
  if (overlaps.length > 0) {
475
- return fail({
570
+ return AddFailure.fail({
476
571
  message: `the ${side} folder '${folder}' does not fit the layout of ${configPath}: ${overlaps.join('; ')}`,
477
572
  });
478
573
  }
@@ -480,10 +575,11 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
480
575
  const isNewFolder = !listed.includes(folder);
481
576
 
482
577
  // Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
483
- const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
578
+ const askingScope = flaggedScope.scope ?? (menusAvailable() ? askScope() : undefined);
579
+ const scope = await askingScope;
484
580
 
485
581
  if (scope === null) {
486
- return fail({ message: ABORTED });
582
+ return AddFailure.fail({ message: ABORTED });
487
583
  }
488
584
 
489
585
  const packageOfApp = scope === undefined ? app : `${scope}/${app}`;
@@ -493,7 +589,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
493
589
  existsSync(join(cwd, folder, app)) ||
494
590
  packages.some((entry) => entry.dir === app || entry.name === packageOfApp)
495
591
  ) {
496
- return fail({ message: `${folder}/${app} already exists` });
592
+ return AddFailure.fail({ message: `${folder}/${app} already exists` });
497
593
  }
498
594
 
499
595
  const devPort = pickPort({ preferred: preset.devPort, used: usedPorts({ root: cwd, packages }) });
@@ -509,7 +605,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
509
605
  });
510
606
 
511
607
  if (!api.ok) {
512
- return fail({ message: api.error });
608
+ return AddFailure.fail({ message: api.error });
513
609
  }
514
610
 
515
611
  apiUrl = api.apiUrl;
@@ -523,7 +619,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
523
619
 
524
620
  // The user's config is theirs: with the block gone or no longer JSON it is never rewritten, only described.
525
621
  if (!parsed.ok) {
526
- return fail({
622
+ return AddFailure.fail({
527
623
  message: [
528
624
  parsed.reason === AppsBlockProblems.MISSING
529
625
  ? `the vulcan:apps block is gone from ${configPath} - add by hand:`
@@ -563,7 +659,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
563
659
  );
564
660
 
565
661
  if (nextConfig === undefined) {
566
- return fail({ message: ROOT_HINT });
662
+ return AddFailure.fail({ message: ROOT_HINT });
567
663
  }
568
664
 
569
665
  const project = config.name ?? (typeof manifest.name === 'string' ? manifest.name : app);
@@ -600,7 +696,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
600
696
  const confirmed = await confirmWrite({ title: `Add ${app}`, lines: planLines({ rows }) });
601
697
 
602
698
  if (!confirmed) {
603
- return fail({ message: ABORTED });
699
+ return AddFailure.fail({ message: ABORTED });
604
700
  }
605
701
 
606
702
  copyPresetFiles({
@@ -691,5 +787,10 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
691
787
  return ExitCodes.OK;
692
788
  };
693
789
 
694
- export const addApp = async (opts: { cwd: string; args: string[] }): Promise<number> =>
790
+ export const addApp = async (opts: {
791
+ cwd: string;
792
+ args: string[];
793
+ /** The official presets a refusal names; the published list by default. */
794
+ official?: IOfficialPreset[];
795
+ }): Promise<number> =>
695
796
  withScratch({ root: opts.cwd, run: (scratch) => runAdd({ ...opts, scratch }) });
@@ -9,11 +9,11 @@ import {
9
9
  listedFoldersNote,
10
10
  withLayoutFolder,
11
11
  } from '../common/layout-folder.ts';
12
- import { PackageKinds } from '../config/index.ts';
13
- import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
12
+ import { LibraryKinds, PackageKinds } from '../config/index.ts';
13
+ import type { IProjectPackage, TLibraryKind, TResolvedConfig } from '../config/index.ts';
14
14
  import { readWorkspaceGlobs } from '../init/index.ts';
15
15
  import { runAppChecks } from './checks.ts';
16
- import { AppsBlockProblems, CreateConstants, CreateFlags } from './common/index.ts';
16
+ import { AddFailure, AppsBlockProblems, CreateConstants, CreateFlags } from './common/index.ts';
17
17
  import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts';
18
18
  import { writeFile } from './files.ts';
19
19
  import { readLibPreset } from './lib-preset.ts';
@@ -37,12 +37,6 @@ import {
37
37
  const KNOWLEDGE_DIRECTORY = '.agents/knowledge';
38
38
  const DIRECTORY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
39
39
 
40
- const fail = (opts: { message: string }): number => {
41
- process.stderr.write(`vulcan add: ${opts.message}\n`);
42
-
43
- return ExitCodes.FAILURE;
44
- };
45
-
46
40
  /** A folder from the root, written with slashes, never climbing out or absolute. */
47
41
  const isProjectFolder = (opts: { folder: string }): boolean =>
48
42
  opts.folder
@@ -85,16 +79,14 @@ const folderOf = async (opts: {
85
79
  if (chosen === undefined) {
86
80
  if (opts.interactive) {
87
81
  // The folders the project's libraries already live in are picked; a new one is typed.
88
- const answer =
89
- (
90
- await askInTerminal({
91
- question: 'Folder',
92
- previous: fallback,
93
- choices: [
94
- ...new Set([...shared, ...(fallback === undefined ? [] : [fallback]), ...libFolders]),
95
- ],
96
- })
97
- )?.trim() ?? '';
82
+ const typedFolder = await askInTerminal({
83
+ question: 'Folder',
84
+ previous: fallback,
85
+ choices: [
86
+ ...new Set([...shared, ...(fallback === undefined ? [] : [fallback]), ...libFolders]),
87
+ ],
88
+ });
89
+ const answer = typedFolder?.trim() ?? '';
98
90
 
99
91
  chosen = answer === '' ? fallback : answer;
100
92
  } else {
@@ -163,20 +155,23 @@ export const addLibrary = async (opts: {
163
155
  manifest: Record<string, unknown>;
164
156
  packages: IProjectPackage[];
165
157
  libName: string;
158
+ /** Which preset kind makes the package: `lib` (the default) or the side-neutral `shared`. */
159
+ kind?: TLibraryKind;
166
160
  recorded: (opts: { block: IAppsBlock }) => IAppsBlock;
167
161
  }): Promise<number> => {
168
162
  const { cwd, config, located, libName } = opts;
163
+ const kind = opts.kind ?? LibraryKinds.LIB;
169
164
 
170
165
  if (!CreateConstants.NAME_PATTERN.test(libName)) {
171
- return fail({
166
+ return AddFailure.fail({
172
167
  message: `'${libName}' is not a name - lowercase letters, digits and -, starting with a letter or digit`,
173
168
  });
174
169
  }
175
170
 
176
- const read = readLibPreset({ located });
171
+ const read = readLibPreset({ located, kind });
177
172
 
178
173
  if (!read.ok) {
179
- return fail({ message: read.error });
174
+ return AddFailure.fail({ message: read.error });
180
175
  }
181
176
 
182
177
  const lib: TLibPreset = read.lib;
@@ -189,7 +184,7 @@ export const addLibrary = async (opts: {
189
184
  });
190
185
 
191
186
  if (!placed.ok) {
192
- return fail({ message: placed.error });
187
+ return AddFailure.fail({ message: placed.error });
193
188
  }
194
189
 
195
190
  const { folder } = placed;
@@ -202,7 +197,7 @@ export const addLibrary = async (opts: {
202
197
  });
203
198
 
204
199
  if (!named.ok) {
205
- return fail({ message: named.error });
200
+ return AddFailure.fail({ message: named.error });
206
201
  }
207
202
 
208
203
  const path = `${folder}/${libName}`;
@@ -211,14 +206,14 @@ export const addLibrary = async (opts: {
211
206
  existsSync(join(cwd, path)) ||
212
207
  opts.packages.some((entry) => entry.dir === libName || entry.name === named.name)
213
208
  ) {
214
- return fail({ message: `${path} already exists` });
209
+ return AddFailure.fail({ message: `${path} already exists` });
215
210
  }
216
211
 
217
212
  const source = readFileSync(opts.configFile, 'utf8');
218
213
  const parsed = parseAppsBlock({ source });
219
214
 
220
215
  if (!parsed.ok) {
221
- return fail({
216
+ return AddFailure.fail({
222
217
  message:
223
218
  parsed.reason === AppsBlockProblems.MISSING
224
219
  ? `the vulcan:apps block is gone from ${opts.configPath} - add the package by hand: { dir: '${libName}', name: '${named.name}', path: '${path}', kind: 'lib' }`
@@ -241,7 +236,13 @@ export const addLibrary = async (opts: {
241
236
  layout: isNewFolder ? { ...parsed.block.layout, shared: grown } : parsed.block.layout,
242
237
  packages: [
243
238
  ...parsed.block.packages,
244
- { dir: libName, name: named.name, path, kind: PackageKinds.LIB },
239
+ {
240
+ dir: libName,
241
+ name: named.name,
242
+ path,
243
+ kind: PackageKinds.LIB,
244
+ ...(kind === LibraryKinds.SHARED ? { presetKind: LibraryKinds.SHARED } : {}),
245
+ },
245
246
  ],
246
247
  },
247
248
  });
@@ -255,7 +256,9 @@ export const addLibrary = async (opts: {
255
256
  );
256
257
 
257
258
  if (nextConfig === undefined) {
258
- return fail({ message: `the vulcan:apps block of ${opts.configPath} cannot be rewritten` });
259
+ return AddFailure.fail({
260
+ message: `the vulcan:apps block of ${opts.configPath} cannot be rewritten`,
261
+ });
259
262
  }
260
263
 
261
264
  const project =
@@ -273,7 +276,9 @@ export const addLibrary = async (opts: {
273
276
  );
274
277
  }
275
278
 
276
- const rows: [string, string][] = [['library', path]];
279
+ const rows: [string, string][] = [
280
+ [kind === LibraryKinds.SHARED ? 'shared package' : 'library', path],
281
+ ];
277
282
 
278
283
  if (isNewFolder) {
279
284
  rows.push([
@@ -290,14 +295,18 @@ export const addLibrary = async (opts: {
290
295
  const confirmed = await confirmWrite({ title: `Add ${libName}`, lines: planLines({ rows }) });
291
296
 
292
297
  if (!confirmed) {
293
- return fail({ message: ABORTED });
298
+ return AddFailure.fail({ message: ABORTED });
294
299
  }
295
300
 
296
301
  const written = copyPresetFiles({
297
302
  located,
298
303
  files: lib.files,
299
304
  target: join(cwd, path),
300
- tokens: { project, lib: libName, package: named.name },
305
+ tokens: {
306
+ project,
307
+ [kind === LibraryKinds.SHARED ? 'shared' : 'lib']: libName,
308
+ package: named.name,
309
+ },
301
310
  });
302
311
 
303
312
  for (const file of written) {
@@ -331,6 +340,7 @@ export const addLibrary = async (opts: {
331
340
  path,
332
341
  summary: lib.summary,
333
342
  presetPackage: located.packageName,
343
+ kind,
334
344
  }),
335
345
  });
336
346
 
@@ -61,6 +61,7 @@ export class CreateFlags {
61
61
  static readonly API = '--api';
62
62
  static readonly NO_API = '--no-api';
63
63
  static readonly LIB = '--lib';
64
+ static readonly SHARED = '--shared';
64
65
  static readonly DIR = '--dir';
65
66
  static readonly SCOPE = '--scope';
66
67
  static readonly FULL = '--full';
@@ -0,0 +1,10 @@
1
+ import { ExitCodes } from '../../common/index.ts';
2
+
3
+ /** How `vulcan add` (an app or a library) reports a refusal: one line on stderr and the failure exit code. */
4
+ export class AddFailure {
5
+ static fail(opts: { message: string }): number {
6
+ process.stderr.write(`vulcan add: ${opts.message}\n`);
7
+
8
+ return ExitCodes.FAILURE;
9
+ }
10
+ }
@@ -1,2 +1,4 @@
1
1
  export * from './constants.ts';
2
+ export * from './failure.ts';
3
+ export * from './preset-path.ts';
2
4
  export * from './types.ts';
@@ -0,0 +1,11 @@
1
+ import { isAbsolute, relative, sep } from 'node:path';
2
+
3
+ /** Where a path a preset names may point: inside the preset's own package. */
4
+ export class PresetPath {
5
+ /** Whether `path` lies outside `root`, by its relative form. */
6
+ static escapes(opts: { root: string; path: string }): boolean {
7
+ const relativePath = relative(opts.root, opts.path);
8
+
9
+ return isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith(`..${sep}`);
10
+ }
11
+ }