@venizia/vulcan 0.3.6 → 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.6",
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.6",
48
- "@venizia/vulcan-okf": "0.3.6",
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
 
@@ -1,6 +1,6 @@
1
1
  import { ExitCodes } from '../common/index.ts';
2
2
  import type { ICommandContext } from '../common/index.ts';
3
- import { runDoctorChecks, runDoctorNotes } from '../doctor/index.ts';
3
+ import { runDoctorChecks, runDoctorNotes, runDoctorWarnings } from '../doctor/index.ts';
4
4
 
5
5
  export const runDoctorCommand = async (opts: ICommandContext): Promise<number> => {
6
6
  const violations = await runDoctorChecks({ root: opts.cwd });
@@ -9,6 +9,12 @@ export const runDoctorCommand = async (opts: ICommandContext): Promise<number> =
9
9
  process.stderr.write(` [${violation.check}] ${violation.file}: ${violation.message}\n`);
10
10
  }
11
11
 
12
+ const warnings = await runDoctorWarnings({ root: opts.cwd });
13
+
14
+ for (const warning of warnings) {
15
+ process.stderr.write(` warning [${warning.check}] ${warning.file}: ${warning.message}\n`);
16
+ }
17
+
12
18
  for (const note of await runDoctorNotes({ root: opts.cwd })) {
13
19
  process.stderr.write(` info [${note.check}] ${note.file}: ${note.message}\n`);
14
20
  }
@@ -19,7 +25,11 @@ export const runDoctorCommand = async (opts: ICommandContext): Promise<number> =
19
25
  return ExitCodes.FAILURE;
20
26
  }
21
27
 
22
- process.stderr.write('vulcan doctor: OK\n');
28
+ process.stderr.write(
29
+ warnings.length === 0
30
+ ? 'vulcan doctor: OK\n'
31
+ : `vulcan doctor: OK with ${warnings.length} warning(s)\n`,
32
+ );
23
33
 
24
34
  return ExitCodes.OK;
25
35
  };
@@ -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);
@@ -13,6 +13,15 @@ const BASE_PATTERNS = [
13
13
  '.agents/plans',
14
14
  ];
15
15
 
16
+ /**
17
+ * `.env` files hold secrets (database passwords, tokens) and a Dockerfile that copies the project
18
+ * would put them in a layer a CI cache can keep. The example file stays: the negation comes after
19
+ * the excludes, or Docker would not apply it.
20
+ */
21
+ const SECRET_PATTERNS = ['**/.env', '**/.env.*', '!**/.env.example'];
22
+ const SECRET_COMMENT =
23
+ '# .env files hold secrets: keep them out of every image layer; the example stays.';
24
+
16
25
  /**
17
26
  * The root `.dockerignore` of a new project: a Dockerfile is built from the project root, so the
18
27
  * context must not carry dependencies, build output or git. Beside the base patterns it lists the
@@ -26,11 +35,13 @@ export const renderDockerignore = (): string => {
26
35
  })
27
36
  .flatMap(group => group.paths)
28
37
  .map(path => path.replace(/^\//, '').replace(/\/$/, ''));
29
- const patterns = [...new Set([...BASE_PATTERNS, ...agentPaths])];
38
+ const patterns = [...new Set([...BASE_PATTERNS, ...SECRET_PATTERNS, ...agentPaths])];
30
39
 
31
40
  return [
32
41
  '# Written by vulcan init; edit it freely, vulcan never overwrites it. .git is excluded, so pass the commit: docker build --build-arg APP_BUILD_COMMIT="$(git rev-parse HEAD)" ...',
33
- ...patterns,
42
+ ...patterns.flatMap(pattern =>
43
+ pattern === SECRET_PATTERNS[0] ? [SECRET_COMMENT, pattern] : [pattern],
44
+ ),
34
45
  '',
35
46
  ].join('\n');
36
47
  };
@@ -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,11 +596,162 @@ 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
- /** A Dockerfile is built from the project root: without a root `.dockerignore` the context carries node_modules, dist and .git. */
706
+ const SECRET_LINES = ['**/.env', '**/.env.*', '!**/.env.example'];
707
+ const ADD_SECRET_LINES = `add ${SECRET_LINES[0]}, ${SECRET_LINES[1]} and ${SECRET_LINES[2]} (in that order) to the root .dockerignore`;
708
+
709
+ /** Whether a `.dockerignore` pattern, as Docker reads it, names the file `opts.file` at any depth. */
710
+ const patternNames = (opts: { pattern: string; file: string }): boolean => {
711
+ const bare = opts.pattern.replace(/^\*\*\//, '').replace(/^\//, '');
712
+
713
+ return (
714
+ bare === opts.file ||
715
+ (bare.endsWith('*') && opts.file.startsWith(bare.slice(0, -1)) && bare.startsWith('.env'))
716
+ );
717
+ };
718
+
719
+ /** Whether the last pattern that names `opts.file` excludes it: a later `!` line brings it back. */
720
+ const excludes = (opts: { lines: string[]; file: string }): boolean => {
721
+ let excluded = false;
722
+
723
+ for (const line of opts.lines) {
724
+ const negated = line.startsWith('!');
725
+
726
+ if (patternNames({ pattern: negated ? line.slice(1) : line, file: opts.file })) {
727
+ excluded = !negated;
728
+ }
729
+ }
730
+
731
+ return excluded;
732
+ };
733
+
734
+ /**
735
+ * A Dockerfile is built from the project root. Without a root `.dockerignore` the context carries
736
+ * node_modules, dist, .git and every `.env` (secrets that would land in an image layer a CI cache
737
+ * can keep); with one that does not exclude `.env` and `.env.*` the secrets are still copied.
738
+ * A warning, not a violation: the exit code is unchanged, so a project made before this check
739
+ * does not start failing.
740
+ */
597
741
  export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
598
- if (existsSync(join(opts.root, '.dockerignore'))) {
742
+ const file = join(opts.root, '.dockerignore');
743
+ const lines = existsSync(file)
744
+ ? readText({ file })
745
+ .split('\n')
746
+ .map(line => line.trim())
747
+ .filter(line => line !== '' && !line.startsWith('#'))
748
+ : undefined;
749
+
750
+ if (
751
+ lines !== undefined &&
752
+ excludes({ lines, file: '.env' }) &&
753
+ excludes({ lines, file: '.env.production' })
754
+ ) {
599
755
  return [];
600
756
  }
601
757
 
@@ -607,11 +763,16 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
607
763
  return [];
608
764
  }
609
765
 
766
+ const subject = apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`;
767
+
610
768
  return [
611
769
  createViolation({
612
770
  check: DoctorChecks.DOCKERIGNORE,
613
771
  file: '.dockerignore',
614
- message: `${apps.length === 1 ? `app ${apps[0]} has` : `apps ${apps.join(', ')} have`} a Dockerfile and the root has no .dockerignore: the build context would carry node_modules, dist and .git`,
772
+ message:
773
+ lines === undefined
774
+ ? `${subject} a Dockerfile and the root has no .dockerignore: the build context would carry node_modules, dist, .git and every .env file (secrets) - create it, then ${ADD_SECRET_LINES}`
775
+ : `${subject} a Dockerfile and the root .dockerignore does not exclude .env files, which hold secrets and would land in the image layer: ${ADD_SECRET_LINES}`,
615
776
  }),
616
777
  ];
617
778
  };
@@ -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,
@@ -76,5 +77,22 @@ export const runDoctorNotes = async (opts: { root: string }): Promise<IViolation
76
77
  configFile: relative(opts.root, loaded.file),
77
78
  };
78
79
 
79
- return [...checkAppScripts(context), ...checkAtlasBlock(context), ...checkDockerignore(context)];
80
+ return [...checkAppScripts(context), ...checkAtlasBlock(context)];
81
+ };
82
+
83
+ /** Warnings: louder than a note, still never a failure - a security gap a project made earlier may carry. */
84
+ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolation[]> => {
85
+ const loaded = await loadConfig({ root: opts.root });
86
+
87
+ if (!loaded.ok) {
88
+ return [];
89
+ }
90
+
91
+ const context = {
92
+ root: opts.root,
93
+ config: loaded.config,
94
+ configFile: relative(opts.root, loaded.file),
95
+ };
96
+
97
+ return [...checkMcpAtlas(context), ...checkDockerignore(context)];
80
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. */