@venizia/vulcan 0.3.7 → 0.3.8

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.7",
3
+ "version": "0.3.8",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "repository": {
@@ -44,8 +44,8 @@
44
44
  "test": "NODE_ENV=test bun test --env-file=.env.test"
45
45
  },
46
46
  "dependencies": {
47
- "@venizia/vulcan-atlas": "0.3.7",
48
- "@venizia/vulcan-okf": "0.3.7",
47
+ "@venizia/vulcan-atlas": "0.3.8",
48
+ "@venizia/vulcan-okf": "0.3.8",
49
49
  "zod": "^4.5.4"
50
50
  },
51
51
  "devDependencies": {
@@ -3,20 +3,31 @@ import type { IAgentQuestion } from './common/index.ts';
3
3
  import { AgentConstants } from './common/index.ts';
4
4
  import { agentIds } from './table.ts';
5
5
 
6
- /** The terminal question: what was detected, what exists, and the developer's earlier choice as the shown default. */
7
- export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
8
- const lines = [
9
- 'Which coding agents do you use in this project? (comma-separated, Enter accepts)',
6
+ const listOf = (opts: { agents: string[] }): string =>
7
+ opts.agents.length === 0 ? AgentConstants.NONE : opts.agents.join(', ');
8
+
9
+ /**
10
+ * The question as the terminal shows it. It says exactly what an empty answer does: it keeps the
11
+ * choice stored on this machine when there is one, else it takes what was detected.
12
+ */
13
+ export const renderAgentsQuestion = (question: IAgentQuestion): string => {
14
+ const enter =
15
+ question.stored === undefined
16
+ ? `Enter accepts the detected list: ${listOf({ agents: question.detected })}`
17
+ : `Enter keeps your earlier choice: ${listOf({ agents: question.stored })}`;
18
+
19
+ return [
20
+ `Which coding agents do you use in this project? (comma-separated; ${enter})`,
10
21
  ` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
11
22
  ...(question.stored === undefined
12
23
  ? []
13
- : [
14
- ` chosen before: ${question.stored.length === 0 ? AgentConstants.NONE : question.stored.join(', ')}`,
15
- ]),
24
+ : [` chosen before: ${listOf({ agents: question.stored })}`]),
16
25
  ` available: ${[...agentIds(), AgentConstants.NONE].join(', ')}`,
17
- ];
26
+ ].join('\n');
27
+ };
18
28
 
19
- process.stdout.write(`${lines.join('\n')}\n`);
29
+ export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
30
+ process.stdout.write(`${renderAgentsQuestion(question)}\n`);
20
31
 
21
32
  return askWithPrompt({ question: 'Agents' });
22
33
  };
@@ -78,8 +78,15 @@ export const resolveAgents = (opts: {
78
78
  };
79
79
  }
80
80
 
81
+ // Enter keeps what this machine chose before; with no earlier choice it takes what was detected.
81
82
  return answer.trim() === ''
82
- ? { ok: true, agents: opts.detected, source: 'asked', writeLocal: true, hint: undefined }
83
+ ? {
84
+ ok: true,
85
+ agents: stored.agents ?? opts.detected,
86
+ source: 'asked',
87
+ writeLocal: true,
88
+ hint: undefined,
89
+ }
83
90
  : fromList({ value: answer, source: 'asked' });
84
91
  };
85
92
 
@@ -8,8 +8,11 @@ Usage: bun x vulcan <command>
8
8
  init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <name>]
9
9
  [--shared-dir <name>] Create a monorepo with its first app, from a framework preset
10
10
  (a name missing from the flags is asked in a terminal)
11
- add --preset <name|file:path> --app <name> [--backend-dir|--frontend-dir <name>]
12
- [--api <app> | --no-api] Add an app to the monorepo (a frontend says which backend to proxy to)
11
+ add --preset <name|file:path> (--app <name> | --lib <name>) [--dir <folder>] [--scope <@scope>]
12
+ [--backend-dir|--frontend-dir <name>] [--api <app> | --no-api]
13
+ Add an app or a shared library to the monorepo (a frontend says which
14
+ backend to proxy to; --dir and --scope are for a library; a terminal
15
+ asks for the kind and every name the flags leave out)
13
16
  sync [--agents <list>|list] [--dry-run] [--prune]
14
17
  Write the adapters of the agents you chose (--agents claude,omp or none,
15
18
  stored in .agents/vulcan.local.json; --agents list shows the table);
@@ -2,7 +2,12 @@ import { Glob } from 'bun';
2
2
  import { existsSync, readdirSync, readFileSync } from 'node:fs';
3
3
  import { dirname, join, relative } from 'node:path';
4
4
  import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
5
- import { coversFolder, declaresWorkspaces, readWorkspaceGlobs } from '../init/index.ts';
5
+ import {
6
+ coversFolder,
7
+ declaresWorkspaces,
8
+ MCP_SERVER_HINT,
9
+ readWorkspaceGlobs,
10
+ } from '../init/index.ts';
6
11
  import { resolvePackages } from '../config/index.ts';
7
12
  import type { TResolvedConfig } from '../config/index.ts';
8
13
  import {
@@ -591,6 +596,111 @@ export const checkAgents = (opts: ICheckContext): IViolation[] => {
591
596
  };
592
597
 
593
598
  /** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
599
+ const CANONICAL_ATLAS_ARGS = ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'];
600
+ const MCP_FILE = '.mcp.json';
601
+ const CLAUDE_SETTINGS_FILE = '.claude/settings.json';
602
+ const ATLAS_SERVER = 'atlas';
603
+
604
+ const readJsonObject = (opts: { file: string }): Record<string, unknown> | undefined => {
605
+ try {
606
+ const value: unknown = JSON.parse(readFileSync(opts.file, 'utf8'));
607
+
608
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
609
+ ? Object.fromEntries(Object.entries(value))
610
+ : undefined;
611
+ } catch {
612
+ return undefined;
613
+ }
614
+ };
615
+
616
+ const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
617
+ typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
618
+
619
+ const mcpWarning = (opts: { file: string; message: string }): IViolation =>
620
+ createViolation({ check: DoctorChecks.MCP, file: opts.file, message: opts.message });
621
+
622
+ /**
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.
627
+ */
628
+ export const checkMcpAtlas = (opts: ICheckContext): IViolation[] => {
629
+ const warnings: IViolation[] = [];
630
+ const file = join(opts.root, MCP_FILE);
631
+
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
+ const parsed = readJsonObject({ file });
641
+
642
+ if (parsed === undefined) {
643
+ warnings.push(
644
+ mcpWarning({
645
+ file: MCP_FILE,
646
+ message: `not valid JSON - it must hold ${MCP_SERVER_HINT} under mcpServers`,
647
+ }),
648
+ );
649
+ } else {
650
+ const holder = { value: parsed['mcpServers'] };
651
+ const servers = isRecord(holder) ? holder.value : {};
652
+ const entry = { value: servers[ATLAS_SERVER] };
653
+ const args = isRecord(entry) ? entry.value['args'] : undefined;
654
+ const isCanonical =
655
+ isRecord(entry) &&
656
+ entry.value['command'] === 'bun' &&
657
+ Array.isArray(args) &&
658
+ args.length === CANONICAL_ATLAS_ARGS.length &&
659
+ args.every((arg, index) => arg === CANONICAL_ATLAS_ARGS[index]);
660
+
661
+ if (!isRecord(entry)) {
662
+ warnings.push(
663
+ mcpWarning({
664
+ file: MCP_FILE,
665
+ message: `no server named atlas (found: ${Object.keys(servers).join(', ') || 'none'}): a differently named server is not enabled automatically - use ${MCP_SERVER_HINT}`,
666
+ }),
667
+ );
668
+ } else if (!isCanonical) {
669
+ const shown = JSON.stringify(entry.value)
670
+ .replace('{"command":', '{ "command": ')
671
+ .replace(',"args":[', ', "args": [')
672
+ .replaceAll('","', '", "')
673
+ .replace(/\]\}$/, '] }');
674
+
675
+ warnings.push(
676
+ mcpWarning({
677
+ file: MCP_FILE,
678
+ message: `the atlas entry is ${shown}, expected ${MCP_SERVER_HINT}`,
679
+ }),
680
+ );
681
+ }
682
+ }
683
+ }
684
+
685
+ const settings = join(opts.root, CLAUDE_SETTINGS_FILE);
686
+ const enabled = existsSync(settings)
687
+ ? readJsonObject({ file: settings })?.['enabledMcpjsonServers']
688
+ : undefined;
689
+
690
+ if (existsSync(settings) && !(Array.isArray(enabled) && enabled.includes(ATLAS_SERVER))) {
691
+ const has = Array.isArray(enabled) ? enabled.map(String).join(', ') : 'none';
692
+
693
+ warnings.push(
694
+ mcpWarning({
695
+ file: CLAUDE_SETTINGS_FILE,
696
+ message: `enabledMcpjsonServers does not include atlas (has: ${has}): Claude asks before using the server - run vulcan sync`,
697
+ }),
698
+ );
699
+ }
700
+
701
+ return warnings;
702
+ };
703
+
594
704
  const DOCKERFILE = '.configs/builders/Dockerfile';
595
705
 
596
706
  const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
@@ -16,6 +16,7 @@ export class DoctorChecks {
16
16
  static readonly SCRIPTS = 'scripts';
17
17
  static readonly AGENTS = 'agents';
18
18
  static readonly DOCKERIGNORE = 'dockerignore';
19
+ static readonly MCP = 'mcp';
19
20
  static readonly SCHEME_SET = new Set<string>([
20
21
  this.CONFIG,
21
22
  this.LAYOUT,
@@ -34,6 +35,7 @@ export class DoctorChecks {
34
35
  this.SCRIPTS,
35
36
  this.AGENTS,
36
37
  this.DOCKERIGNORE,
38
+ this.MCP,
37
39
  ]);
38
40
  static isValid(value: string): boolean {
39
41
  return this.SCHEME_SET.has(value);
@@ -6,6 +6,7 @@ import {
6
6
  checkAppScripts,
7
7
  checkAtlasBlock,
8
8
  checkDockerignore,
9
+ checkMcpAtlas,
9
10
  checkApps,
10
11
  checkManifest,
11
12
  checkPrune,
@@ -87,9 +88,11 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
87
88
  return [];
88
89
  }
89
90
 
90
- return checkDockerignore({
91
+ const context = {
91
92
  root: opts.root,
92
93
  config: loaded.config,
93
94
  configFile: relative(opts.root, loaded.file),
94
- });
95
+ };
96
+
97
+ return [...checkMcpAtlas(context), ...checkDockerignore(context)];
95
98
  };
@@ -33,7 +33,7 @@ export const runsAtlas = (opts: { text: string }): boolean => {
33
33
  };
34
34
 
35
35
  /** The entry for a `.mcp.json` that exists already: atlas serves the knowledge bundle alone, and the wiki when there is one. */
36
- const MCP_SERVER_HINT =
36
+ export const MCP_SERVER_HINT =
37
37
  '"atlas": { "command": "bun", "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."] }';
38
38
 
39
39
  /** The files every project gets, apart from the config, whose format the user picks. */