@venizia/vulcan 0.3.8 → 0.3.10

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.
@@ -9,7 +9,8 @@ import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts'
9
9
  import { today, writeFile } from './files.ts';
10
10
  import { readLibPreset } from './lib-preset.ts';
11
11
  import type { TLibPreset } from './lib-preset.ts';
12
- import { askWithPrompt, readFlag } from './names.ts';
12
+ import { ABORTED, confirmWrite, planLines } from './plan.ts';
13
+ import { askInTerminal, readFlag } from './names.ts';
13
14
  import { copyPresetFiles } from './preset.ts';
14
15
  import { runBun } from './process.ts';
15
16
  import {
@@ -48,13 +49,13 @@ const rootScope = (opts: { manifest: Record<string, unknown> }): string =>
48
49
  typeof opts.manifest.name === 'string' ? scopeOf({ name: opts.manifest.name }) : '';
49
50
 
50
51
  /** Where the new library goes: `--dir`, the layout's shared folder, or the one folder the existing libraries share. */
51
- const folderOf = (opts: {
52
+ const folderOf = async (opts: {
52
53
  args: string[];
53
54
  interactive: boolean;
54
55
  lib: string;
55
56
  config: TResolvedConfig;
56
57
  packages: IProjectPackage[];
57
- }): { ok: true; folder: string } | { ok: false; error: string } => {
58
+ }): Promise<{ ok: true; folder: string } | { ok: false; error: string }> => {
58
59
  const given = readFlag({ args: opts.args, flag: CreateFlags.DIR });
59
60
  const libFolders = [
60
61
  ...new Set(
@@ -69,8 +70,15 @@ const folderOf = (opts: {
69
70
 
70
71
  if (chosen === undefined) {
71
72
  if (opts.interactive) {
72
- const question = fallback === undefined ? 'Folder' : `Folder (${fallback})`;
73
- const answer = askWithPrompt({ question })?.trim() ?? '';
73
+ // The folders the project's libraries already live in are picked; a new one is typed.
74
+ const answer =
75
+ (
76
+ await askInTerminal({
77
+ question: 'Folder',
78
+ previous: fallback,
79
+ choices: [...new Set([...(fallback === undefined ? [] : [fallback]), ...libFolders])],
80
+ })
81
+ )?.trim() ?? '';
74
82
 
75
83
  chosen = answer === '' ? fallback : answer;
76
84
  } else {
@@ -153,7 +161,7 @@ export const addLibrary = async (opts: {
153
161
  }
154
162
 
155
163
  const lib: TLibPreset = read.lib;
156
- const placed = folderOf({
164
+ const placed = await folderOf({
157
165
  args: opts.args,
158
166
  interactive: opts.interactive,
159
167
  lib: libName,
@@ -226,6 +234,21 @@ export const addLibrary = async (opts: {
226
234
  process.stderr.write(`${warning}\n`);
227
235
  }
228
236
 
237
+ const confirmed = await confirmWrite({
238
+ title: `Add ${libName}`,
239
+ lines: planLines({
240
+ rows: [
241
+ ['library', path],
242
+ ['package', named.name],
243
+ ['preset', `${located.packageName} ${located.packageVersion}`],
244
+ ],
245
+ }),
246
+ });
247
+
248
+ if (!confirmed) {
249
+ return fail({ message: ABORTED });
250
+ }
251
+
229
252
  const written = copyPresetFiles({
230
253
  located,
231
254
  files: lib.files,
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The root `bunfig.toml` `init` writes: Bun's telemetry off. No `minimumReleaseAge`: a gate of a few
3
+ * days fails a fresh install whose version floors are the latest releases (measured on a real project: ten
4
+ * packages), so it stays out; Phat's rule is floors at the latest.
5
+ */
6
+ export const renderBunfig = (): string =>
7
+ [
8
+ '# Bun reads this file only from the directory a command runs in, so it sits at the root.',
9
+ 'telemetry = false',
10
+ '',
11
+ ].join('\n');
@@ -12,9 +12,23 @@ export interface INameField {
12
12
  optional?: boolean;
13
13
  /** A folder the user chose before, offered as the answer; never a name VULCAN made up. */
14
14
  previous?: string;
15
+ /** Folders that already exist and fit this field: a menu lists them, then offers a new one. */
16
+ choices?: string[];
17
+ /** The only valid answer is `previous` (one folder per side): a menu never asks, a flag still wins. */
18
+ fixed?: boolean;
15
19
  }
16
20
 
17
- export type TAsk = (opts: { question: string; previous?: string }) => string | null;
21
+ /** What a question carries: the text, the earlier choice, the existing folders, the check a menu runs while typing. */
22
+ export interface IAskOptions {
23
+ question: string;
24
+ previous?: string;
25
+ choices?: string[];
26
+ /** The message to show, or nothing when the text is fine. */
27
+ validate?: (value: string) => string | undefined;
28
+ }
29
+
30
+ /** `null` is end of input or a cancelled menu; a menu answers later, so the answer may be a promise. */
31
+ export type TAsk = (opts: IAskOptions) => string | null | Promise<string | null>;
18
32
 
19
33
  /** Reads at most one byte into `buffer` and returns how many were read; 0 is end of input. */
20
34
  export type TByteReader = (opts: { descriptor: number; buffer: Buffer }) => number;
@@ -58,7 +72,7 @@ export interface IPresetSpec {
58
72
 
59
73
  export interface ILocatedPreset {
60
74
  preset: IPreset;
61
- /** The lib preset file (`vulcan.lib`), absolute and inside the package; absent when the preset makes apps only. */
75
+ /** The lib preset file (`vulcan.presets.lib`), absolute and inside the package; absent when the preset makes apps only. */
62
76
  libFile?: string;
63
77
  /** The preset package's root directory. */
64
78
  packageRoot: string;
@@ -13,8 +13,12 @@ import type {
13
13
  } from './common/index.ts';
14
14
  import { today, writeFile } from './files.ts';
15
15
  import { recordedPresetOf } from './lib-preset.ts';
16
+ import { renderBunfig } from './bunfig.ts';
16
17
  import { renderDockerignore } from './dockerignore.ts';
17
- import { askWithPrompt, findFolderClash, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
18
+ import { menusAvailable } from '../ui/index.ts';
19
+ import { askPresetSpec } from './preset-menu.ts';
20
+ import { ABORTED, confirmWrite, planLines } from './plan.ts';
21
+ import { askInTerminal, findFolderClash, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
18
22
  import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
19
23
  import { renderNext } from './next.ts';
20
24
  import { isInstallSkipped, runBun, runGitInit } from './process.ts';
@@ -34,7 +38,6 @@ import {
34
38
  const LAYER_FILES = [
35
39
  { path: 'AGENTS.md', template: 'AGENTS.md' },
36
40
  { path: '.agents/rules.md', template: 'rules.md' },
37
- { path: '.mcp.json', template: 'mcp.json' },
38
41
  { path: 'Makefile', template: 'Makefile' },
39
42
  ];
40
43
 
@@ -106,6 +109,7 @@ const writeMonorepo = (opts: {
106
109
  });
107
110
  writeFile({ root, path: 'README.md', content: `# ${project}\n` });
108
111
  writeFile({ root, path: '.dockerignore', content: renderDockerignore() });
112
+ writeFile({ root, path: 'bunfig.toml', content: renderBunfig() });
109
113
 
110
114
  if (shared !== '') {
111
115
  writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
@@ -195,21 +199,28 @@ const runCreate = async (opts: {
195
199
  args: string[];
196
200
  scratch: string;
197
201
  }): Promise<number> => {
198
- const presetValue = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
202
+ const flagged = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
199
203
 
200
- if (presetValue === undefined) {
204
+ if (flagged === undefined && !menusAvailable()) {
205
+ return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
206
+ }
207
+
208
+ // A new project has no config to list presets from: the official ones, or one typed.
209
+ const presetValue = flagged ?? (await askPresetSpec({ recorded: [] }))?.trim();
210
+
211
+ if (presetValue === undefined || presetValue === '') {
201
212
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
202
213
  }
203
214
 
204
215
  const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
205
216
  const interactive = process.stdin.isTTY === true;
206
- const first = resolveNames({
217
+ const first = await resolveNames({
207
218
  fields: [
208
219
  { key: 'project', flag: CreateFlags.PROJECT, question: 'Project name (the monorepo folder)' },
209
220
  ],
210
221
  args: opts.args,
211
222
  interactive,
212
- ask: askWithPrompt,
223
+ ask: askInTerminal,
213
224
  });
214
225
 
215
226
  if (!first.ok) {
@@ -237,11 +248,11 @@ const runCreate = async (opts: {
237
248
  if (isNpm) {
238
249
  // Without a terminal nothing is asked, so a missing flag is refused before the network is used.
239
250
  if (!interactive) {
240
- const early = resolveNames({
251
+ const early = await resolveNames({
241
252
  fields: appFields({}),
242
253
  args: opts.args,
243
254
  interactive,
244
- ask: askWithPrompt,
255
+ ask: askInTerminal,
245
256
  });
246
257
 
247
258
  if (!early.ok) {
@@ -273,11 +284,11 @@ const runCreate = async (opts: {
273
284
  located = result.located;
274
285
  }
275
286
 
276
- const rest = resolveNames({
287
+ const rest = await resolveNames({
277
288
  fields: appFields({ side: located.preset.side }),
278
289
  args: opts.args,
279
290
  interactive,
280
- ask: askWithPrompt,
291
+ ask: askInTerminal,
281
292
  });
282
293
 
283
294
  if (!rest.ok) {
@@ -311,6 +322,22 @@ const runCreate = async (opts: {
311
322
  process.stderr.write(`${warning}\n`);
312
323
  }
313
324
 
325
+ const confirmed = await confirmWrite({
326
+ title: `Create ${project}`,
327
+ lines: planLines({
328
+ rows: [
329
+ ['project', project],
330
+ ['preset', `${located.packageName} ${located.packageVersion}`],
331
+ [`${side} app`, `${folder}/${app}`],
332
+ ['shared', shared === '' ? '(none)' : shared],
333
+ ],
334
+ }),
335
+ });
336
+
337
+ if (!confirmed) {
338
+ return fail({ message: ABORTED });
339
+ }
340
+
314
341
  writeMonorepo({ root, project, spec, presetValue, located, folder, app, shared });
315
342
 
316
343
  for (const step of [
@@ -1,7 +1,15 @@
1
1
  import { readSync } from 'node:fs';
2
2
 
3
+ import { menusAvailable, promptSelect, promptText } from '../ui/index.ts';
3
4
  import { AppSides, CreateConstants, CreateFlags } from './common/index.ts';
4
- import type { INameField, TAppSide, TAsk, TByteReader, TNamesResult } from './common/index.ts';
5
+ import type {
6
+ IAskOptions,
7
+ INameField,
8
+ TAppSide,
9
+ TAsk,
10
+ TByteReader,
11
+ TNamesResult,
12
+ } from './common/index.ts';
5
13
 
6
14
  /** The folder holding every app of one side; `add` offers the one the config already holds. */
7
15
  export const SIDE_FIELDS: Record<TAppSide, INameField> = {
@@ -26,6 +34,12 @@ export const readFlag = (opts: { args: string[]; flag: string }): string | undef
26
34
  const isValidName = (opts: { name: string }): boolean =>
27
35
  CreateConstants.NAME_PATTERN.test(opts.name);
28
36
 
37
+ /** The message a menu shows under a typed name that is not one; nothing when it is fine. */
38
+ export const nameProblem = (opts: { name: string }): string | undefined =>
39
+ isValidName({ name: opts.name })
40
+ ? undefined
41
+ : `'${opts.name}' is not a name: lowercase letters, digits and '-', starting with a letter or digit`;
42
+
29
43
  const NEWLINE = 0x0a;
30
44
  const CARRIAGE_RETURN = 0x0d;
31
45
  const RETRY_PAUSE_MILLISECONDS = 5;
@@ -91,7 +105,7 @@ export const readLine = (opts: {
91
105
  };
92
106
 
93
107
  /** The shown default is the user's own earlier choice, never one VULCAN made up. */
94
- export const askWithPrompt: TAsk = opts => {
108
+ export const askWithPrompt = (opts: IAskOptions): string | null => {
95
109
  process.stdout.write(
96
110
  opts.previous === undefined
97
111
  ? `? ${opts.question} > `
@@ -101,9 +115,55 @@ export const askWithPrompt: TAsk = opts => {
101
115
  return readLine({ descriptor: CreateConstants.STDIN_DESCRIPTOR });
102
116
  };
103
117
 
104
- const askUntilValid = (opts: { field: INameField; ask: TAsk }): string | null => {
118
+ const NEW_FOLDER = ':new-folder';
119
+
120
+ /** A menu, not a line: existing folders are picked, a new name is typed with its default shown. */
121
+ const askWithMenus: TAsk = async opts => {
122
+ if (opts.choices !== undefined && opts.choices.length > 0) {
123
+ const picked = await promptSelect({
124
+ message: opts.question,
125
+ choices: [
126
+ ...opts.choices.map(value => ({ value, label: value })),
127
+ { value: NEW_FOLDER, label: 'New folder...' },
128
+ ],
129
+ initial: opts.previous,
130
+ });
131
+
132
+ if (picked !== NEW_FOLDER) {
133
+ return picked;
134
+ }
135
+ }
136
+
137
+ return promptText({
138
+ message: opts.question,
139
+ defaultValue: opts.previous,
140
+ validate: opts.validate,
141
+ });
142
+ };
143
+
144
+ /** Menus in a terminal that can draw them, the plain question everywhere else. */
145
+ export const askInTerminal: TAsk = opts =>
146
+ menusAvailable() ? askWithMenus(opts) : askWithPrompt(opts);
147
+
148
+ const askUntilValid = async (opts: { field: INameField; ask: TAsk }): Promise<string | null> => {
149
+ const { field } = opts;
150
+ const validate = (value: string): string | undefined => {
151
+ const name = value.trim() === '' ? (field.previous ?? '') : value.trim();
152
+
153
+ if (name === '' && field.optional === true) {
154
+ return undefined;
155
+ }
156
+
157
+ return nameProblem({ name });
158
+ };
159
+
105
160
  for (;;) {
106
- const answer = opts.ask({ question: opts.field.question, previous: opts.field.previous });
161
+ const answer = await opts.ask({
162
+ question: field.question,
163
+ previous: field.previous,
164
+ choices: field.choices,
165
+ validate,
166
+ });
107
167
 
108
168
  if (answer === null) {
109
169
  return null;
@@ -126,12 +186,12 @@ const askUntilValid = (opts: { field: INameField; ask: TAsk }): string | null =>
126
186
  };
127
187
 
128
188
  /** Every name from its flag; a missing one is asked in a TTY and an error otherwise. */
129
- export const resolveNames = (opts: {
189
+ export const resolveNames = async (opts: {
130
190
  fields: INameField[];
131
191
  args: string[];
132
192
  interactive: boolean;
133
193
  ask: TAsk;
134
- }): TNamesResult => {
194
+ }): Promise<TNamesResult> => {
135
195
  const names: Record<string, string> = {};
136
196
 
137
197
  for (const field of opts.fields) {
@@ -166,7 +226,12 @@ export const resolveNames = (opts: {
166
226
  };
167
227
  }
168
228
 
169
- const answer = askUntilValid({ field, ask: opts.ask });
229
+ if (field.fixed === true && field.previous !== undefined) {
230
+ names[field.key] = field.previous;
231
+ continue;
232
+ }
233
+
234
+ const answer = await askUntilValid({ field, ask: opts.ask });
170
235
 
171
236
  if (answer === null) {
172
237
  return { ok: false, error: 'aborted' };
@@ -0,0 +1,17 @@
1
+ import { menusAvailable, promptPlan } from '../ui/index.ts';
2
+
3
+ /** `label value` lines with the values in one column. */
4
+ export const planLines = (opts: { rows: [label: string, value: string][] }): string[] => {
5
+ const width = Math.max(...opts.rows.map(([label]) => label.length));
6
+
7
+ return opts.rows.map(([label, value]) => `${label.padEnd(width)} ${value}`);
8
+ };
9
+
10
+ /**
11
+ * Before anything is written, a terminal that can draw menus shows what will be written and asks.
12
+ * Without one nothing is asked: flags and pipes keep writing as they always did.
13
+ */
14
+ export const confirmWrite = async (opts: { title: string; lines: string[] }): Promise<boolean> =>
15
+ menusAvailable() ? promptPlan(opts) : true;
16
+
17
+ export const ABORTED = 'aborted: nothing was written';
@@ -0,0 +1,45 @@
1
+ import { OFFICIAL_PRESETS, officialIdOf } from '@venizia/vulcan-atlas';
2
+ import { promptSelect, promptText } from '../ui/index.ts';
3
+
4
+ const ANOTHER_PRESET = ':another-preset';
5
+
6
+ /** A preset a project recorded: what `--preset` takes back, the side it builds, what it is. */
7
+ export interface IKnownPreset {
8
+ spec: string;
9
+ side: string;
10
+ summary: string;
11
+ }
12
+
13
+ /**
14
+ * What a menu offers for `--preset`: the presets the project recorded, then the official ones it has
15
+ * not used yet (the one list atlas answers `presets` from), then a text input for any other package
16
+ * or `file:` path. null when the user cancelled.
17
+ */
18
+ export const askPresetSpec = async (opts: { recorded: IKnownPreset[] }): Promise<string | null> => {
19
+ const used = new Set(opts.recorded.map(entry => officialIdOf({ spec: entry.spec })));
20
+ const picked = await promptSelect({
21
+ message: 'Which preset?',
22
+ choices: [
23
+ ...opts.recorded.map(entry => ({
24
+ value: entry.spec,
25
+ label: entry.spec,
26
+ hint: `${entry.side}: ${entry.summary}`,
27
+ })),
28
+ ...OFFICIAL_PRESETS.filter(entry => !used.has(entry.id)).map(entry => ({
29
+ value: entry.id,
30
+ label: entry.id,
31
+ hint: `official, ${entry.side} (app or lib)`,
32
+ })),
33
+ { value: ANOTHER_PRESET, label: 'Another preset...', hint: 'a package name or file:<path>' },
34
+ ],
35
+ });
36
+
37
+ if (picked !== ANOTHER_PRESET) {
38
+ return picked;
39
+ }
40
+
41
+ return promptText({
42
+ message: 'Preset (a package name, or file:<path>)',
43
+ validate: value => (value.trim() === '' ? 'a package name, or file:<path>' : undefined),
44
+ });
45
+ };
@@ -146,12 +146,30 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
146
146
  const packageName = String(manifest.name);
147
147
  const packageVersion = String(manifest.version);
148
148
  const shown = `${packageName}@${packageVersion}`;
149
- const field = readProperty({ value: manifest[CreateConstants.PRESET_FIELD], key: 'preset' });
149
+ const vulcan = manifest[CreateConstants.PRESET_FIELD];
150
+ const oldKeys = ['preset', 'lib'].filter(
151
+ key => readProperty({ value: vulcan, key }) !== undefined,
152
+ );
153
+
154
+ // No fallback to the keys before `presets`: say what the contract is now.
155
+ if (oldKeys.length > 0) {
156
+ return {
157
+ ok: false,
158
+ error: `${shown} uses the old keys "vulcan": { ${oldKeys.map(key => `"${key}"`).join(', ')} }; the contract is now "vulcan": { "presets": { "app": "./path/preset.json", "lib": "./path/lib.json" } }`,
159
+ };
160
+ }
161
+
162
+ const presets = readProperty({ value: vulcan, key: 'presets' });
163
+ const field = readProperty({ value: presets, key: 'app' });
164
+ const libField = readProperty({ value: presets, key: 'lib' });
150
165
 
151
166
  if (typeof field !== 'string') {
152
167
  return {
153
168
  ok: false,
154
- error: `${shown} ships no VULCAN preset (no "vulcan": { "preset" } in its package.json)`,
169
+ error:
170
+ typeof libField === 'string'
171
+ ? `${shown}: vulcan.presets.lib needs vulcan.presets.app: a lib-only package is not supported`
172
+ : `${shown} ships no VULCAN preset (no "vulcan": { "presets": { "app" } } in its package.json)`,
155
173
  };
156
174
  }
157
175
 
@@ -160,7 +178,7 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
160
178
  if (presetFile === undefined) {
161
179
  return {
162
180
  ok: false,
163
- error: `${shown}: vulcan.preset ${field} points outside the package`,
181
+ error: `${shown}: vulcan.presets.app ${field} points outside the package`,
164
182
  };
165
183
  }
166
184
 
@@ -201,14 +219,16 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
201
219
  }
202
220
 
203
221
  const preset = { ...parsed.data, files: filesFolder };
204
- const libField = readProperty({ value: manifest[CreateConstants.PRESET_FIELD], key: 'lib' });
205
222
  const libFile =
206
223
  typeof libField === 'string'
207
224
  ? resolveInside({ root: packageRoot, from: packageRoot, path: libField })
208
225
  : undefined;
209
226
 
210
227
  if (typeof libField === 'string' && libFile === undefined) {
211
- return { ok: false, error: `${shown}: vulcan.lib ${libField} points outside the package` };
228
+ return {
229
+ ok: false,
230
+ error: `${shown}: vulcan.presets.lib ${libField} points outside the package`,
231
+ };
212
232
  }
213
233
 
214
234
  const located: ILocatedPreset = {
@@ -1,7 +1,14 @@
1
1
  import { relative, resolve } from 'node:path';
2
2
  import { coversFolder } from '../init/index.ts';
3
3
  import { CreateConstants } from './common/index.ts';
4
- import type { IApp, IAppsBlock, IPreset, IPresetSpec, IRecordedPreset } from './common/index.ts';
4
+ import type {
5
+ IApp,
6
+ IAppsBlock,
7
+ IPreset,
8
+ IPresetSpec,
9
+ IRecordedPreset,
10
+ TAppSide,
11
+ } from './common/index.ts';
5
12
 
6
13
  const ENV_PORT = /^[A-Z0-9_]*PORT=(\d+)\s*$/m;
7
14
 
@@ -202,6 +209,37 @@ export const renderLibManifest = (opts: {
202
209
  });
203
210
  };
204
211
 
212
+ /** The atlas lookups a package of one kind depends on: what a summary page cannot hold. */
213
+ const ATLAS_LOOKUPS: Record<TAppSide | 'lib', [string, string][]> = {
214
+ backend: [
215
+ ['How a route and its controller are written', '`search` "controller routes", then `get`'],
216
+ [
217
+ 'How a service, a repository and a datasource fit together',
218
+ '`search` "service repository datasource"',
219
+ ],
220
+ ],
221
+ frontend: [
222
+ ['How a page or a resource is added', '`search` "page resource", then `get`'],
223
+ ['How the app reads data from its backend', '`search` "data provider"'],
224
+ ],
225
+ lib: [['How a shared package exposes its API', '`search` "shared package exports", then `get`']],
226
+ };
227
+
228
+ /** The note and the table that turn a package page into a pointer at atlas, for its kind. */
229
+ const renderAtlasLookups = (opts: { kind: TAppSide | 'lib' }): string[] => [
230
+ '> This page is a summary, not a spec: it says what the package is. How code is written here lives',
231
+ '> in atlas; look it up before you explain or write code.',
232
+ '',
233
+ '## How things are done here',
234
+ '',
235
+ '| You need | Ask atlas |',
236
+ '|---|---|',
237
+ ...ATLAS_LOOKUPS[opts.kind].map(([need, call]) => `| ${need} | ${call} |`),
238
+ '| The signature and import path of an export, before you import it | `symbol` with its name |',
239
+ '| A new app or package | `presets`, then the `vulcan add` command it returns |',
240
+ '',
241
+ ];
242
+
205
243
  export const renderLibConcept = (opts: {
206
244
  name: string;
207
245
  path: string;
@@ -221,6 +259,7 @@ export const renderLibConcept = (opts: {
221
259
  '',
222
260
  `The shared package at \`${opts.path}\`, created from the ${opts.presetPackage} preset (lib kind). ${oneLine({ text: opts.summary })}`,
223
261
  '',
262
+ ...renderAtlasLookups({ kind: 'lib' }),
224
263
  ].join('\n');
225
264
 
226
265
  export const renderAppsBlock = (opts: { block: IAppsBlock }): string =>
@@ -445,6 +484,7 @@ export const renderAppConcept = (opts: {
445
484
  '',
446
485
  `The ${opts.app.side} app at \`${opts.app.folder}/${opts.app.name}\`, created from the ${opts.presetPackage} preset. ${oneLine({ text: opts.summary })}`,
447
486
  '',
487
+ ...renderAtlasLookups({ kind: opts.app.side }),
448
488
  ].join('\n');
449
489
 
450
490
  export const renderLogEntry = (opts: { date: string; text: string }): string =>
@@ -23,14 +23,21 @@ import {
23
23
  projectNameOf,
24
24
  renderManifest,
25
25
  } from '../manifest/index.ts';
26
- import { readLocalChoice, resolveAgentsQuietly } from '../agents/index.ts';
27
26
  import {
27
+ AgentScopes,
28
+ readAgentTable,
29
+ readLocalChoice,
30
+ resolveAgentsQuietly,
31
+ } from '../agents/index.ts';
32
+ import {
33
+ isTracked,
28
34
  mergedAtlasBlock,
29
35
  planManifest,
30
36
  planPrune,
31
37
  planSync,
32
38
  SyncStatuses,
33
39
  } from '../sync/index.ts';
40
+ import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
34
41
  import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
35
42
  import type { IViolation, TDoctorCheck } from './common/index.ts';
36
43
  import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
@@ -620,23 +627,33 @@ const mcpWarning = (opts: { file: string; message: string }): IViolation =>
620
627
  createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
621
628
 
622
629
  /**
623
- * The atlas server is registered the one way every project does: the tracked `.mcp.json` holds an
624
- * `atlas` entry that runs the project's own atlas (`--root .`), and the managed Claude settings
625
- * enable `atlas` by that name. A server under another name, or one that serves another folder, is
626
- * never enabled automatically or serves the wrong knowledge. Warnings, not violations.
630
+ * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
631
+ * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
632
+ * atlas (`--root .`), and the managed Claude settings enable `atlas` by that name. A server under
633
+ * another name, or one that serves another folder, is never enabled automatically or serves the wrong
634
+ * knowledge. A `.mcp.json` git still tracks is told how to hand over to `sync`. Warnings, not violations.
627
635
  */
628
636
  export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
629
637
  const warnings: IViolation[] = [];
630
638
  const file = join(opts.root, MCP_FILE);
639
+ const chosen = resolveAgentsQuietly({ root: opts.root, configAgents: opts.config.agents });
640
+ const readsMcpFile = readAgentTable().some(
641
+ entry => chosen.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
642
+ );
643
+
644
+ // The root `.mcp.json` is a per-machine file of the agents that read it; a missing one is the
645
+ // `adapters` check's (not synced yet), so only an existing file is looked at.
646
+ if (readsMcpFile && existsSync(file)) {
647
+ if (isTracked({ root: opts.root, path: MCP_FILE })) {
648
+ warnings.push(
649
+ mcpWarning({
650
+ file: MCP_FILE,
651
+ message:
652
+ 'tracked by git; VULCAN now writes it per machine. Run `git rm --cached .mcp.json` and let sync manage it.',
653
+ }),
654
+ );
655
+ }
631
656
 
632
- if (!existsSync(file)) {
633
- warnings.push(
634
- mcpWarning({
635
- file: MCP_FILE,
636
- message: `missing: atlas is not registered for Claude Code, omp and Copilot CLI - add ${MCP_SERVER_HINT} under mcpServers`,
637
- }),
638
- );
639
- } else {
640
657
  const parsed = readJsonObject({ file });
641
658
 
642
659
  if (parsed === undefined) {
@@ -790,3 +807,15 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
790
807
  }),
791
808
  ];
792
809
  };
810
+
811
+ /** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
812
+ export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
813
+ skillCatalogOf({ root: opts.root })
814
+ .filter(entry => !triggerOf({ description: entry.description }).hasUseWhen)
815
+ .map(entry =>
816
+ createViolation({
817
+ check: DoctorChecks.SKILLS,
818
+ file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
819
+ message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
820
+ }),
821
+ );
@@ -5,6 +5,7 @@ import {
5
5
  checkAgents,
6
6
  checkAppScripts,
7
7
  checkAtlasBlock,
8
+ checkSkillTriggers,
8
9
  checkDockerignore,
9
10
  checkMcpAtlas,
10
11
  checkApps,
@@ -94,5 +95,5 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
94
95
  configFile: relative(opts.root, loaded.file),
95
96
  };
96
97
 
97
- return [...checkMcpAtlas(context), ...checkDockerignore(context)];
98
+ return [...checkMcpAtlas(context), ...checkDockerignore(context), ...checkSkillTriggers(context)];
98
99
  };