@venizia/vulcan 0.3.5 → 0.3.6

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 (55) hide show
  1. package/README.md +2 -2
  2. package/base/agents.json +232 -0
  3. package/base/claude/settings.json +12 -0
  4. package/base/hooks/guard-package.ts +29 -0
  5. package/base/rules.md +1 -0
  6. package/base/templates/AGENTS.md +4 -3
  7. package/package.json +3 -3
  8. package/src/agents/atlas-block.ts +54 -0
  9. package/src/agents/common/constants.ts +38 -0
  10. package/src/agents/common/index.ts +3 -0
  11. package/src/agents/common/schema.ts +42 -0
  12. package/src/agents/common/types.ts +30 -0
  13. package/src/agents/detect.ts +36 -0
  14. package/src/agents/exclude.ts +87 -0
  15. package/src/agents/index.ts +9 -0
  16. package/src/agents/local.ts +65 -0
  17. package/src/agents/prompt.ts +22 -0
  18. package/src/agents/render.ts +229 -0
  19. package/src/agents/resolve.ts +145 -0
  20. package/src/agents/table.ts +35 -0
  21. package/src/commands/agents.command.ts +154 -0
  22. package/src/commands/doctor.command.ts +5 -1
  23. package/src/commands/help.command.ts +5 -1
  24. package/src/commands/index.ts +2 -0
  25. package/src/commands/sync.command.ts +112 -3
  26. package/src/common/constants.ts +9 -1
  27. package/src/config/common/constants.ts +11 -1
  28. package/src/config/packages.ts +2 -0
  29. package/src/config/schema.ts +16 -1
  30. package/src/create/add-app.ts +110 -4
  31. package/src/create/add-lib.ts +317 -0
  32. package/src/create/common/constants.ts +3 -0
  33. package/src/create/common/types.ts +18 -2
  34. package/src/create/dockerignore.ts +36 -0
  35. package/src/create/init-monorepo.ts +22 -4
  36. package/src/create/lib-preset.ts +154 -0
  37. package/src/create/preset.ts +22 -3
  38. package/src/create/workspace.ts +94 -3
  39. package/src/doctor/checks.ts +183 -12
  40. package/src/doctor/common/constants.ts +26 -0
  41. package/src/doctor/runner.ts +22 -0
  42. package/src/hooks/guard-package.ts +211 -0
  43. package/src/hooks/index.ts +1 -0
  44. package/src/init/scaffold.ts +8 -5
  45. package/src/manifest/render.ts +4 -0
  46. package/src/router.ts +10 -1
  47. package/src/sync/agent-files.ts +112 -0
  48. package/src/sync/agent-removal.ts +241 -0
  49. package/src/sync/atlas-block.ts +55 -0
  50. package/src/sync/common/constants.ts +2 -0
  51. package/src/sync/exclude.ts +89 -0
  52. package/src/sync/index.ts +5 -0
  53. package/src/sync/local-choice.ts +55 -0
  54. package/src/sync/planner.ts +55 -19
  55. package/src/sync/settings.ts +26 -0
@@ -1,6 +1,7 @@
1
1
  import { VulcanCommands } from '../common/index.ts';
2
2
  import type { TCommandHandler } from '../common/index.ts';
3
3
  import { runAddCommand } from './add.command.ts';
4
+ import { runAgentsCommand } from './agents.command.ts';
4
5
  import { runDoctorCommand } from './doctor.command.ts';
5
6
  import { runHelpCommand, runVersionCommand } from './help.command.ts';
6
7
  import { runInitCommand } from './init.command.ts';
@@ -11,6 +12,7 @@ import { runXCommand } from './x.command.ts';
11
12
  /** The handler of every implemented command. */
12
13
  export const COMMAND_HANDLERS: Record<string, TCommandHandler> = {
13
14
  [VulcanCommands.ADD]: runAddCommand,
15
+ [VulcanCommands.AGENTS]: runAgentsCommand,
14
16
  [VulcanCommands.DOCTOR]: runDoctorCommand,
15
17
  [VulcanCommands.HELP]: runHelpCommand,
16
18
  [VulcanCommands.INIT]: runInitCommand,
@@ -1,8 +1,29 @@
1
1
  import { relative } from 'node:path';
2
2
  import { ExitCodes } from '../common/index.ts';
3
3
  import type { ICommandContext } from '../common/index.ts';
4
+ import { homedir } from 'node:os';
5
+ import {
6
+ AgentConstants,
7
+ askAgentsInTerminal,
8
+ detectAgents,
9
+ readLocalChoice,
10
+ readAgentTable,
11
+ resolveAgents,
12
+ } from '../agents/index.ts';
4
13
  import { loadConfig } from '../config/index.ts';
5
- import { diffBaseRules, planPrune, planSync, SyncConstants, SyncStatuses } from '../sync/index.ts';
14
+ import {
15
+ agentNotes,
16
+ diffBaseRules,
17
+ planAgentRemoval,
18
+ planAtlasBlock,
19
+ planExclude,
20
+ planLocalChoice,
21
+ planLocalIgnore,
22
+ planPrune,
23
+ planSync,
24
+ SyncConstants,
25
+ SyncStatuses,
26
+ } from '../sync/index.ts';
6
27
 
7
28
  const DRY_RUN_FLAG = '--dry-run';
8
29
  const PRUNE_FLAG = '--prune';
@@ -16,7 +37,43 @@ const DRY_RUN_LABELS: Record<string, string> = {
16
37
  };
17
38
  const DRY_RUN_LABEL_WIDTH = Math.max(...Object.values(DRY_RUN_LABELS).map(label => label.length));
18
39
 
19
- export const runSyncCommand = async (opts: ICommandContext): Promise<number> => {
40
+ /** `--agents` is undefined when absent and '' when it has no value after it. */
41
+ const readAgentsFlag = (opts: { args: string[] }): string | undefined => {
42
+ const index = opts.args.indexOf(AgentConstants.FLAG);
43
+
44
+ if (index === -1) {
45
+ return undefined;
46
+ }
47
+
48
+ const value = opts.args[index + 1];
49
+
50
+ return value === undefined || value.startsWith('--') ? '' : value;
51
+ };
52
+
53
+ export const printAgentTable = (): void => {
54
+ for (const entry of readAgentTable()) {
55
+ process.stdout.write(
56
+ `${entry.id.padEnd(15)} ${entry.name.padEnd(20)} MCP ${entry.mcp.path.padEnd(26)} skills ${entry.skills.dir}\n`,
57
+ );
58
+ }
59
+ };
60
+
61
+ /**
62
+ * The whole sync. `cleanup` names agents whose adapters are taken back even when no stored choice
63
+ * says so (`vulcan agents remove`); an agent stored before and left out of a new explicit list is
64
+ * taken back too.
65
+ */
66
+ export const runSyncFlow = async (
67
+ opts: ICommandContext & { cleanup?: string[] },
68
+ ): Promise<number> => {
69
+ const flag = readAgentsFlag({ args: opts.args });
70
+
71
+ if (flag === AgentConstants.LIST) {
72
+ printAgentTable();
73
+
74
+ return ExitCodes.OK;
75
+ }
76
+
20
77
  const loaded = await loadConfig({ root: opts.cwd });
21
78
 
22
79
  if (!loaded.ok) {
@@ -25,10 +82,52 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
25
82
  return ExitCodes.FAILURE;
26
83
  }
27
84
 
85
+ const resolved = resolveAgents({
86
+ root: opts.cwd,
87
+ flag,
88
+ configAgents: loaded.config.agents,
89
+ interactive: process.stdin.isTTY === true,
90
+ detected: detectAgents({
91
+ root: opts.cwd,
92
+ home: process.env.HOME ?? homedir(),
93
+ path: process.env.PATH ?? '',
94
+ }),
95
+ ask: askAgentsInTerminal,
96
+ });
97
+
98
+ if (!resolved.ok) {
99
+ process.stderr.write(`${resolved.error}\n`);
100
+
101
+ return ExitCodes.FAILURE;
102
+ }
103
+
104
+ const previous = readLocalChoice({ root: opts.cwd });
105
+ const dropped =
106
+ resolved.source === 'flag' || resolved.source === 'asked'
107
+ ? (previous.ok ? (previous.agents ?? []) : []).filter(id => !resolved.agents.includes(id))
108
+ : [];
109
+ const removed = [...new Set([...(opts.cleanup ?? []), ...dropped])].filter(
110
+ id => !resolved.agents.includes(id),
111
+ );
28
112
  const dryRun = opts.args.includes(DRY_RUN_FLAG);
29
113
  // Planned before anything is written: prune reads the managed record of the previous sync.
30
114
  const pruned = opts.args.includes(PRUNE_FLAG) ? planPrune({ root: opts.cwd }) : [];
31
- const actions = [...planSync({ root: opts.cwd, config: loaded.config }), ...pruned];
115
+ // The stored choice is listed whether it was just written or only read; a machine that has not chosen stores nothing.
116
+ const stored =
117
+ resolved.writeLocal || resolved.source === 'local'
118
+ ? [
119
+ planLocalChoice({ root: opts.cwd, agents: resolved.agents }),
120
+ ...(resolved.writeLocal ? planLocalIgnore({ root: opts.cwd }) : []),
121
+ ]
122
+ : [];
123
+ const actions = [
124
+ ...planAgentRemoval({ root: opts.cwd, removed, remaining: resolved.agents }),
125
+ ...planSync({ root: opts.cwd, config: loaded.config, agents: resolved.agents }),
126
+ ...planAtlasBlock({ root: opts.cwd, config: loaded.config }),
127
+ ...stored,
128
+ ...planExclude({ root: opts.cwd, agents: resolved.agents }),
129
+ ...pruned,
130
+ ];
32
131
  // Read before the manifest action rewrites the hashes it compares against.
33
132
  const changes = diffBaseRules({ root: opts.cwd });
34
133
  const width = dryRun ? DRY_RUN_LABEL_WIDTH : LABEL_WIDTH;
@@ -48,6 +147,14 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
48
147
  process.stderr.write(` ${change.padEnd(width)} ${[id, text].filter(Boolean).join(' ')}\n`);
49
148
  }
50
149
 
150
+ for (const { agent, note } of agentNotes({ agents: resolved.agents })) {
151
+ process.stderr.write(` ${'note'.padEnd(width)} ${agent}: ${note}\n`);
152
+ }
153
+
154
+ if (resolved.hint !== undefined) {
155
+ process.stderr.write(`${resolved.hint}\n`);
156
+ }
157
+
51
158
  const settingsBroken = actions.some(
52
159
  action =>
53
160
  action.status === SyncStatuses.SKIPPED && action.path.endsWith(SyncConstants.SETTINGS_FILE),
@@ -55,3 +162,5 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
55
162
 
56
163
  return settingsBroken ? ExitCodes.FAILURE : ExitCodes.OK;
57
164
  };
165
+
166
+ export const runSyncCommand = async (opts: ICommandContext): Promise<number> => runSyncFlow(opts);
@@ -2,6 +2,7 @@ export class VulcanCommands {
2
2
  static readonly INIT = 'init';
3
3
  static readonly ADD = 'add';
4
4
  static readonly SYNC = 'sync';
5
+ static readonly AGENTS = 'agents';
5
6
  static readonly DOCTOR = 'doctor';
6
7
  static readonly UPGRADE = 'upgrade';
7
8
  static readonly X = 'x';
@@ -11,6 +12,7 @@ export class VulcanCommands {
11
12
  this.INIT,
12
13
  this.ADD,
13
14
  this.SYNC,
15
+ this.AGENTS,
14
16
  this.DOCTOR,
15
17
  this.UPGRADE,
16
18
  this.X,
@@ -60,7 +62,13 @@ export class ProjectLayout {
60
62
  /** `-include`: a fresh clone runs `make install` before node_modules exists. */
61
63
  static readonly MAKE_INCLUDE_LINE = '-include node_modules/@venizia/vulcan/base/make/vulcan.mk';
62
64
  static readonly STYLE_PACKAGE = '@venizia/dev-configs';
63
- static readonly GITIGNORE_ENTRIES = ['CLAUDE.md', 'CLAUDE.*.md', '.claude/', '.agents/plans'];
65
+ static readonly GITIGNORE_ENTRIES = [
66
+ 'CLAUDE.md',
67
+ 'CLAUDE.*.md',
68
+ '.claude/',
69
+ '.agents/plans',
70
+ '.agents/vulcan.local.json',
71
+ ];
64
72
  /** What the scaffolded lint configs run; optional peers of dev-configs, so bun never installs them alone. */
65
73
  static readonly LINT_TOOLS = ['oxlint', 'oxlint-tsgolint', 'oxfmt', 'eslint'];
66
74
  /** Written into a scaffolded file the project must fill in; doctor fails the file while it holds this. */
@@ -18,7 +18,17 @@ export class ConfigExtensions {
18
18
  export class CodingAgents {
19
19
  static readonly CLAUDE = 'claude';
20
20
 
21
- static readonly SCHEME_SET = new Set<string>([this.CLAUDE]);
21
+ /** The ids of `base/agents.json`, in its order; a test keeps the two in step. */
22
+ static readonly SCHEME_SET = new Set<string>([
23
+ this.CLAUDE,
24
+ 'omp',
25
+ 'codex',
26
+ 'cursor',
27
+ 'copilot-cli',
28
+ 'copilot-vscode',
29
+ 'antigravity',
30
+ 'pi',
31
+ ]);
22
32
 
23
33
  static isValid(value: string): boolean {
24
34
  return this.SCHEME_SET.has(value);
@@ -9,6 +9,7 @@ export interface IProjectPackage {
9
9
  path: string;
10
10
  aliases: string[];
11
11
  retired: boolean;
12
+ kind?: 'app' | 'lib';
12
13
  }
13
14
 
14
15
  /** The project's packages in release order. */
@@ -19,4 +20,5 @@ export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPack
19
20
  path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
20
21
  aliases: entry.aliases,
21
22
  retired: entry.retired,
23
+ ...(entry.kind === undefined ? {} : { kind: entry.kind }),
22
24
  }));
@@ -17,6 +17,8 @@ const PROJECT_PACKAGE = z.strictObject({
17
17
  path: z.string().optional(),
18
18
  aliases: z.array(z.string()).default([]),
19
19
  retired: z.boolean().default(false),
20
+ /** A shared package a preset's lib kind made lives anywhere a workspace glob covers; absent means an app or a plain package. */
21
+ kind: z.enum(['app', 'lib']).optional(),
20
22
  });
21
23
 
22
24
  /** A path as a key: no leading `./`, no trailing slash. */
@@ -108,7 +110,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
108
110
  .string()
109
111
  .regex(/^[a-z0-9][a-z0-9-]*$/)
110
112
  .optional(),
111
- agents: z.array(CODING_AGENT).default([CodingAgents.CLAUDE]),
113
+ /** The project's suggested agents; each developer's own choice lives in `.agents/vulcan.local.json`. */
114
+ agents: z.array(CODING_AGENT).optional(),
112
115
  rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
113
116
  /** The folders `vulcan init` and `add` put apps in, as the user named them. */
114
117
  layout: z
@@ -118,6 +121,18 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
118
121
  shared: FOLDER_NAME.optional(),
119
122
  })
120
123
  .optional(),
124
+ /** The presets this project's apps came from (`init` and `add` record them), as `--preset` takes them back. */
125
+ presets: z
126
+ .array(
127
+ z.strictObject({
128
+ spec: z.string().min(1),
129
+ side: z.enum(['backend', 'frontend']),
130
+ summary: z.string(),
131
+ /** The summary of the preset's lib kind, when it ships one. */
132
+ lib: z.string().optional(),
133
+ }),
134
+ )
135
+ .optional(),
121
136
  /** The project's packages in release order; okf, atlas, make and release read this one list. */
122
137
  packages: z.array(PROJECT_PACKAGE).superRefine(checkPackagesUnique).default([]),
123
138
  knowledge: z
@@ -4,10 +4,12 @@ import { ExitCodes } from '../common/index.ts';
4
4
  import { loadConfig, resolvePackages } from '../config/index.ts';
5
5
  import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
6
6
  import { readWorkspaceGlobs } from '../init/index.ts';
7
+ import { addLibrary } from './add-lib.ts';
7
8
  import { runAppChecks } from './checks.ts';
8
9
  import { AppSides, CreateFlags } from './common/index.ts';
9
10
  import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
10
11
  import { today, writeFile } from './files.ts';
12
+ import { recordedPresetOf } from './lib-preset.ts';
11
13
  import { askWithPrompt, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
12
14
  import { readExistingApps, renderNext } from './next.ts';
13
15
  import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
@@ -20,8 +22,10 @@ import {
20
22
  parseAppsBlock,
21
23
  pickPort,
22
24
  planRootManifest,
25
+ presetSpecOf,
23
26
  readCatalog,
24
27
  readPort,
28
+ recordPreset,
25
29
  renderAppConcept,
26
30
  renderAppManifest,
27
31
  renderKnowledgeIndex,
@@ -93,6 +97,33 @@ const missingFlag = (opts: {
93
97
  return side === AppSides.FRONTEND && !hasApi ? MISSING_API : undefined;
94
98
  };
95
99
 
100
+ /** The two commands a project can run for this preset: what `add` prints when it is not told what to create. */
101
+ const kindCommands = (opts: { presetValue: string }): string[] => [
102
+ `bun x --no-install vulcan add --preset ${opts.presetValue} ${CreateFlags.APP} <name>`,
103
+ `bun x --no-install vulcan add --preset ${opts.presetValue} ${CreateFlags.LIB} <name>`,
104
+ ];
105
+
106
+ const SAY_WHAT = `say what to create - \`${CreateFlags.APP} <name>\` (a runnable app) or \`${CreateFlags.LIB} <name>\` (a shared package)`;
107
+
108
+ /** The terminal asks which kind, listing only what the preset offers; end of input stops the command. */
109
+ const askKind = (opts: { offered: string[] }): string | undefined => {
110
+ for (;;) {
111
+ const answer = askWithPrompt({
112
+ question: `What do you want to create? (${opts.offered.join(', ')})`,
113
+ });
114
+
115
+ if (answer === null) {
116
+ return undefined;
117
+ }
118
+
119
+ const kind = answer.trim();
120
+
121
+ if (opts.offered.includes(kind)) {
122
+ return kind;
123
+ }
124
+ }
125
+ };
126
+
96
127
  const readRootManifest = (opts: { path: string }): TRootManifest | undefined => {
97
128
  if (!existsSync(opts.path)) {
98
129
  return undefined;
@@ -229,7 +260,27 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
229
260
  }
230
261
 
231
262
  const interactive = process.stdin.isTTY === true;
232
- const early = interactive ? undefined : missingFlag({ args: opts.args, layout: config.layout });
263
+ const libFlag = opts.args.includes(CreateFlags.LIB);
264
+ const libName = readFlag({ args: opts.args, flag: CreateFlags.LIB });
265
+ const appFlag = opts.args.includes(CreateFlags.APP);
266
+
267
+ if (libFlag && appFlag) {
268
+ return fail({ message: `${CreateFlags.APP} and ${CreateFlags.LIB} cannot be used together` });
269
+ }
270
+
271
+ if (libFlag && libName === undefined) {
272
+ return fail({ message: `${CreateFlags.LIB} needs a name` });
273
+ }
274
+
275
+ // Never a default kind: without a terminal to ask, nothing is fetched or written until the flag says which.
276
+ if (!interactive && !libFlag && !appFlag) {
277
+ return fail({
278
+ message: `${SAY_WHAT}\n ${kindCommands({ presetValue }).join('\n ')}`,
279
+ });
280
+ }
281
+
282
+ const early =
283
+ interactive || libFlag ? undefined : missingFlag({ args: opts.args, layout: config.layout });
233
284
 
234
285
  if (early !== undefined) {
235
286
  return fail({ message: early });
@@ -243,6 +294,48 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
243
294
  }
244
295
 
245
296
  const { preset, packageName, packageVersion } = located.located;
297
+ const recordedSpec = presetSpecOf({ value: presetValue, root: cwd, cwd });
298
+ let kind = libFlag ? 'lib' : 'app';
299
+
300
+ if (!libFlag && !appFlag) {
301
+ const offered = ['app', ...(located.located.libFile === undefined ? [] : ['lib'])];
302
+ const chosen = offered.length === 1 ? 'app' : askKind({ offered });
303
+
304
+ if (chosen === undefined) {
305
+ return fail({ message: SAY_WHAT });
306
+ }
307
+
308
+ kind = chosen;
309
+ }
310
+
311
+ if (kind === 'lib') {
312
+ const name = libName ?? askWithPrompt({ question: 'Name of this library' })?.trim();
313
+
314
+ if (name === undefined || name === '') {
315
+ return fail({ message: `${CreateFlags.LIB} needs a name` });
316
+ }
317
+
318
+ return addLibrary({
319
+ cwd,
320
+ args: opts.args,
321
+ interactive,
322
+ presetValue,
323
+ spec,
324
+ located: located.located,
325
+ config,
326
+ configFile: loaded.file,
327
+ configPath,
328
+ manifest,
329
+ packages: resolvePackages({ config }),
330
+ libName: name,
331
+ recorded: ({ block }) =>
332
+ recordPreset({
333
+ block,
334
+ preset: recordedPresetOf({ spec: recordedSpec, located: located.located }),
335
+ }),
336
+ });
337
+ }
338
+
246
339
  // Before any question: a catalog the preset cannot live in is no reason to ask for names.
247
340
  const peerProblem = checkPeers({
248
341
  catalog: readCatalog({ manifest }),
@@ -333,9 +426,10 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
333
426
  }
334
427
 
335
428
  // Extend what the markers hold: the resolved config also carries what the user added outside them.
336
- const block: IAppsBlock = {
429
+ const extended: IAppsBlock = {
337
430
  layout: { ...parsed.block.layout, [side]: folder },
338
431
  packages: [...parsed.block.packages, entry],
432
+ ...(parsed.block.presets === undefined ? {} : { presets: parsed.block.presets }),
339
433
  sources: [
340
434
  ...parsed.block.sources,
341
435
  ...newSources.filter(
@@ -343,7 +437,19 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
343
437
  ),
344
438
  ],
345
439
  };
346
- const nextConfig = replaceAppsBlock({ source, block });
440
+ const block = recordPreset({
441
+ block: extended,
442
+ preset: recordedPresetOf({ spec: recordedSpec, located: located.located }),
443
+ });
444
+ const replaced = replaceAppsBlock({ source, block });
445
+ // A config written before presets were recorded does not read them yet: the line that does goes in.
446
+ const nextConfig =
447
+ replaced === undefined || replaced.includes('apps.presets')
448
+ ? replaced
449
+ : replaced.replace(
450
+ ' packages: apps.packages,\n',
451
+ ' packages: apps.packages,\n presets: apps.presets,\n',
452
+ );
347
453
 
348
454
  if (nextConfig === undefined) {
349
455
  return fail({ message: ROOT_HINT });
@@ -360,7 +466,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
360
466
  copyPresetFiles({
361
467
  located: located.located,
362
468
  target: join(cwd, folder, app),
363
- tokens: { project, app, devPort: String(devPort), apiUrl },
469
+ tokens: { project, app, appPath: `${folder}/${app}`, devPort: String(devPort), apiUrl },
364
470
  });
365
471
  writeFile({
366
472
  root: cwd,