@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.
@@ -3,6 +3,7 @@ import { dirname, join, relative, resolve } from 'node:path';
3
3
  import type { ICheckContext } from './checks.ts';
4
4
  import { DoctorChecks } from './common/index.ts';
5
5
  import type { IViolation } from './common/index.ts';
6
+ import { frontmatterOf } from '../skills/index.ts';
6
7
 
7
8
  /**
8
9
  * Anthropic's skill-authoring rules (platform.claude.com, Agent Skills best practices), as checks:
@@ -33,48 +34,6 @@ const filesOf = (opts: { directory: string }): string[] =>
33
34
  const lineCountOf = (opts: { text: string }): number =>
34
35
  opts.text.replace(/\n$/, '').split('\n').length;
35
36
 
36
- const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
37
- try {
38
- return { value: Bun.YAML.parse(opts.text) };
39
- } catch (error) {
40
- return { error: error instanceof Error ? error.message : String(error) };
41
- }
42
- };
43
-
44
- /**
45
- * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
46
- * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
47
- */
48
- const frontmatterOf = (opts: {
49
- text: string;
50
- }): { data: Record<string, unknown>; error?: string } => {
51
- const block = FRONTMATTER.exec(opts.text)?.[1];
52
-
53
- if (block === undefined) {
54
- return { data: {} };
55
- }
56
-
57
- const parsed = parseYaml({ text: block });
58
-
59
- if (parsed.error !== undefined) {
60
- const blockLines = block.split('\n');
61
- const failsAt = blockLines.findIndex(
62
- (_line, index) =>
63
- parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
64
- );
65
- const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
66
-
67
- return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
68
- }
69
-
70
- return {
71
- data:
72
- typeof parsed.value === 'object' && parsed.value !== null
73
- ? Object.fromEntries(Object.entries(parsed.value))
74
- : {},
75
- };
76
- };
77
-
78
37
  /** Every rule one skill directory breaks, each a message naming the file. */
79
38
  export const lintSkill = (opts: { directory: string }): string[] => {
80
39
  const skillFile = join(opts.directory, 'SKILL.md');
@@ -4,35 +4,11 @@ import { BASE_DIRECTORY, ProjectLayout, readProperty } from '../common/index.ts'
4
4
  import { ConfigConstants, findConfigFiles } from '../config/index.ts';
5
5
  import type { TConfigExtension } from '../config/index.ts';
6
6
  import { InitConstants, InitStatuses } from './common/index.ts';
7
+ import { renderBunfig } from '../create/bunfig.ts';
7
8
  import { renderDockerignore } from '../create/dockerignore.ts';
8
9
  import type { IInitEntry, IScaffoldFile } from './common/index.ts';
9
10
 
10
- /**
11
- * Whether a `.mcp.json` already serves atlas: a server named `atlas`, or any server whose arguments run
12
- * `atlas mcp` under another name, as separate arguments or inside a `sh -c` string. A file that is not JSON falls back to looking for the name.
13
- */
14
- export const runsAtlas = (opts: { text: string }): boolean => {
15
- try {
16
- const parsed: { mcpServers?: Record<string, { args?: unknown }> } = JSON.parse(opts.text);
17
- const servers = parsed.mcpServers ?? {};
18
-
19
- return (
20
- 'atlas' in servers ||
21
- Object.values(servers).some(server => {
22
- const args = Array.isArray(server.args)
23
- ? server.args.flatMap(arg => String(arg).split(/\s+/))
24
- : [];
25
- const atlas = args.indexOf('atlas');
26
-
27
- return atlas !== -1 && args[atlas + 1] === 'mcp';
28
- })
29
- );
30
- } catch {
31
- return opts.text.includes('"atlas"');
32
- }
33
- };
34
-
35
- /** The entry for a `.mcp.json` that exists already: atlas serves the knowledge bundle alone, and the wiki when there is one. */
11
+ /** The atlas entry of the root `.mcp.json`, as `sync` writes it and `doctor` shows it. */
36
12
  export const MCP_SERVER_HINT =
37
13
  '"atlas": { "command": "bun", "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."] }';
38
14
 
@@ -41,7 +17,6 @@ const SCAFFOLD_FILES: IScaffoldFile[] = [
41
17
  { path: 'AGENTS.md', template: 'AGENTS.md' },
42
18
  { path: '.agents/rules.md', template: 'rules.md' },
43
19
  { path: '.agents/knowledge/index.md', template: 'knowledge-index.md' },
44
- { path: '.mcp.json', template: 'mcp.json' },
45
20
  ];
46
21
 
47
22
  /** The lint configs of a single-package project. A workspaces project keeps them in each app. */
@@ -190,6 +165,7 @@ export const scaffoldProject = (opts: {
190
165
  }
191
166
 
192
167
  entries.push(writeIfAbsent({ root, path: '.dockerignore', content: renderDockerignore() }));
168
+ entries.push(writeIfAbsent({ root, path: 'bunfig.toml', content: renderBunfig() }));
193
169
 
194
170
  const makefile = join(root, 'Makefile');
195
171
 
@@ -208,20 +184,6 @@ export const scaffoldProject = (opts: {
208
184
  });
209
185
  }
210
186
 
211
- // A `.mcp.json` that was already there is the project's: it gets the atlas entry as a hint, never an edit.
212
- if (
213
- !entries.some(entry => entry.subject === '.mcp.json' && entry.status === InitStatuses.CREATED)
214
- ) {
215
- const servers = readFileSync(join(root, '.mcp.json'), 'utf8');
216
-
217
- if (!runsAtlas({ text: servers })) {
218
- entries.push({
219
- status: InitStatuses.ADD,
220
- subject: `.mcp.json: the atlas server, for the knowledge bundle (and the wiki, when there is one; --root pins the project): ${MCP_SERVER_HINT}`,
221
- });
222
- }
223
- }
224
-
225
187
  const gitignore = join(root, '.gitignore');
226
188
  const existing = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : '';
227
189
  const lines = existing.split('\n');
@@ -0,0 +1,43 @@
1
+ const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
2
+
3
+ const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
4
+ try {
5
+ return { value: Bun.YAML.parse(opts.text) };
6
+ } catch (error) {
7
+ return { error: error instanceof Error ? error.message : String(error) };
8
+ }
9
+ };
10
+
11
+ /**
12
+ * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
13
+ * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
14
+ */
15
+ export const frontmatterOf = (opts: {
16
+ text: string;
17
+ }): { data: Record<string, unknown>; error?: string } => {
18
+ const block = FRONTMATTER.exec(opts.text)?.[1];
19
+
20
+ if (block === undefined) {
21
+ return { data: {} };
22
+ }
23
+
24
+ const parsed = parseYaml({ text: block });
25
+
26
+ if (parsed.error !== undefined) {
27
+ const blockLines = block.split('\n');
28
+ const failsAt = blockLines.findIndex(
29
+ (_line, index) =>
30
+ parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
31
+ );
32
+ const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
33
+
34
+ return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
35
+ }
36
+
37
+ return {
38
+ data:
39
+ typeof parsed.value === 'object' && parsed.value !== null
40
+ ? Object.fromEntries(Object.entries(parsed.value))
41
+ : {},
42
+ };
43
+ };
@@ -0,0 +1 @@
1
+ export * from './frontmatter.ts';
@@ -1,9 +1,11 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import {
4
+ AgentConstants,
4
5
  AgentRenderers,
5
6
  AgentScopes,
6
7
  atlasServerEntry,
8
+ canonicalAtlasEntry,
7
9
  mergeCodexToml,
8
10
  mergeMcpServers,
9
11
  readAgentTable,
@@ -15,7 +17,7 @@ import type { ISyncAction } from './common/index.ts';
15
17
  const NO_CHANGE = (): void => {};
16
18
 
17
19
  /** A file git tracks cannot be hidden by an exclude entry, and a per-developer edit would show as a diff. */
18
- const isTracked = (opts: { root: string; path: string }): boolean => {
20
+ export const isTracked = (opts: { root: string; path: string }): boolean => {
19
21
  try {
20
22
  return (
21
23
  Bun.spawnSync(['git', 'ls-files', '--error-unmatch', opts.path], {
@@ -99,11 +101,63 @@ const planAgentMcp = (opts: { root: string; entry: TAgentEntry }): ISyncAction[]
99
101
  ];
100
102
  };
101
103
 
102
- /** The MCP files of every chosen agent, in table order. */
103
- export const planAgentFiles = (opts: { root: string; agents: string[] }): ISyncAction[] =>
104
- readAgentTable()
104
+ /**
105
+ * The root `.mcp.json` the chosen agents of the shared scope read: the canonical atlas entry, merged
106
+ * into what is there. A file git tracks belongs to the project, not to this machine: it is never
107
+ * rewritten (the doctor says how to hand it over).
108
+ */
109
+ const planSharedMcp = (opts: { root: string }): ISyncAction[] => {
110
+ const path = join(opts.root, AgentConstants.SHARED_MCP_FILE);
111
+ const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
112
+ const merged = mergeMcpServers({ text, key: 'mcpServers', entry: canonicalAtlasEntry() });
113
+
114
+ if (!merged.ok) {
115
+ return [
116
+ {
117
+ path,
118
+ status: SyncStatuses.SKIPPED,
119
+ note: `${merged.reason} - left untouched; fix it, then re-run sync`,
120
+ apply: NO_CHANGE,
121
+ },
122
+ ];
123
+ }
124
+
125
+ if (
126
+ !merged.changed ||
127
+ (text !== undefined && isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE }))
128
+ ) {
129
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }];
130
+ }
131
+
132
+ return [
133
+ {
134
+ path,
135
+ status: text === undefined ? SyncStatuses.CREATED : SyncStatuses.REPLACED,
136
+ apply: () => writeFileSync(path, merged.text),
137
+ },
138
+ ];
139
+ };
140
+
141
+ /** The MCP files of every chosen agent, in table order; the shared `.mcp.json` once, at its first reader. */
142
+ export const planAgentFiles = (opts: { root: string; agents: string[] }): ISyncAction[] => {
143
+ let sharedPlanned = false;
144
+
145
+ return readAgentTable()
105
146
  .filter(entry => opts.agents.includes(entry.id))
106
- .flatMap(entry => planAgentMcp({ root: opts.root, entry }));
147
+ .flatMap(entry => {
148
+ if (entry.mcp.scope === AgentScopes.PROJECT) {
149
+ return planAgentMcp({ root: opts.root, entry });
150
+ }
151
+
152
+ if (sharedPlanned) {
153
+ return [];
154
+ }
155
+
156
+ sharedPlanned = true;
157
+
158
+ return planSharedMcp({ root: opts.root });
159
+ });
160
+ };
107
161
 
108
162
  /** One line per note of a chosen agent (a trust prompt only the user can answer). */
109
163
  export const agentNotes = (opts: { agents: string[] }): { agent: string; note: string }[] =>
@@ -18,6 +18,7 @@ import {
18
18
  removeMcpEntry,
19
19
  } from '../agents/index.ts';
20
20
  import type { TAgentEntry } from '../agents/index.ts';
21
+ import { isTracked } from './agent-files.ts';
21
22
  import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
22
23
  import { SyncConstants, SyncStatuses } from './common/index.ts';
23
24
  import type { ISyncAction, TSettings } from './common/index.ts';
@@ -80,6 +81,51 @@ const removeFile = (opts: { path: string; note?: string; parent?: string }): ISy
80
81
  },
81
82
  });
82
83
 
84
+ /**
85
+ * The root `.mcp.json`, once no remaining agent reads it: sync's own atlas entry is taken out (the file
86
+ * goes when nothing else is in it). A file git tracks is the project's, and an entry the user changed
87
+ * is theirs: both are left, and the line says so.
88
+ */
89
+ const planSharedMcpRemoval = (opts: { root: string }): ISyncAction[] => {
90
+ const path = join(opts.root, AgentConstants.SHARED_MCP_FILE);
91
+
92
+ if (!existsSync(path)) {
93
+ return [];
94
+ }
95
+
96
+ const removed = removeMcpEntry({ text: readFileSync(path, 'utf8'), key: 'mcpServers' });
97
+
98
+ if (!removed.ok) {
99
+ return [{ path, status: SyncStatuses.SKIPPED, note: removed.reason, apply: NO_CHANGE }];
100
+ }
101
+
102
+ if (removed.outcome === 'absent') {
103
+ return [];
104
+ }
105
+
106
+ if (isTracked({ root: opts.root, path: AgentConstants.SHARED_MCP_FILE })) {
107
+ return [
108
+ {
109
+ path,
110
+ status: SyncStatuses.SKIPPED,
111
+ note: 'tracked by git - left alone',
112
+ apply: NO_CHANGE,
113
+ },
114
+ ];
115
+ }
116
+
117
+ return removed.text === undefined
118
+ ? [removeFile({ path })]
119
+ : [
120
+ {
121
+ path,
122
+ status: SyncStatuses.REPLACED,
123
+ note: 'the atlas entry taken out',
124
+ apply: () => writeFileSync(path, removed.text ?? ''),
125
+ },
126
+ ];
127
+ };
128
+
83
129
  const planMcpRemoval = (opts: { root: string; entry: TAgentEntry }): ISyncAction[] => {
84
130
  if (opts.entry.mcp.scope !== AgentScopes.PROJECT) {
85
131
  return [];
@@ -219,6 +265,10 @@ export const planAgentRemoval = (opts: {
219
265
  );
220
266
  const cleaned = new Set<string>();
221
267
  const actions: ISyncAction[] = [];
268
+ const stillReadsShared = table.some(
269
+ entry => opts.remaining.includes(entry.id) && entry.mcp.scope === AgentScopes.SHARED,
270
+ );
271
+ let sharedDone = false;
222
272
 
223
273
  for (const entry of table.filter(item => opts.removed.includes(item.id))) {
224
274
  if (entry.id === AgentConstants.DEFAULT_AGENT) {
@@ -227,6 +277,11 @@ export const planAgentRemoval = (opts: {
227
277
 
228
278
  actions.push(...planMcpRemoval({ root: opts.root, entry }));
229
279
 
280
+ if (entry.mcp.scope === AgentScopes.SHARED && !stillReadsShared && !sharedDone) {
281
+ sharedDone = true;
282
+ actions.push(...planSharedMcpRemoval({ root: opts.root }));
283
+ }
284
+
230
285
  if (
231
286
  entry.skills.dir !== CLAUDE_SKILLS &&
232
287
  !kept.has(entry.skills.dir) &&
@@ -2,7 +2,6 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { mergeAtlasBlock, renderAtlasBlock } from '../agents/index.ts';
4
4
  import type { TResolvedConfig } from '../config/index.ts';
5
- import { runsAtlas } from '../init/scaffold.ts';
6
5
  import { projectNameOf } from '../manifest/index.ts';
7
6
  import { SyncStatuses } from './common/index.ts';
8
7
  import type { ISyncAction } from './common/index.ts';
@@ -10,17 +9,17 @@ import type { ISyncAction } from './common/index.ts';
10
9
  const NO_CHANGE = (): void => {};
11
10
 
12
11
  /**
13
- * The block's text for this project, or undefined when AGENTS.md is absent or the project does not
14
- * run the atlas server (a block that points at a server nobody started is noise).
12
+ * The block's text for this project, or undefined when AGENTS.md is absent. Every project has the
13
+ * atlas server, and the block is what an agent that does not show the server's own text reads, so it
14
+ * does not wait for a per-machine MCP file to exist.
15
15
  */
16
16
  export const mergedAtlasBlock = (opts: {
17
17
  root: string;
18
18
  config: TResolvedConfig;
19
19
  }): { path: string; changed: boolean; text: string } | undefined => {
20
20
  const path = join(opts.root, 'AGENTS.md');
21
- const mcp = join(opts.root, '.mcp.json');
22
21
 
23
- if (!existsSync(path) || !existsSync(mcp) || !runsAtlas({ text: readFileSync(mcp, 'utf8') })) {
22
+ if (!existsSync(path)) {
24
23
  return undefined;
25
24
  }
26
25
 
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Whether the menus can draw: both ends are a terminal and it understands cursor movement. Anything
3
+ * else (a pipe, a redirect, `TERM=dumb`) keeps the plain questions, so what scripts and logs see does
4
+ * not change.
5
+ */
6
+ export const menusAvailable = (): boolean =>
7
+ process.stdin.isTTY === true && process.stdout.isTTY === true && process.env.TERM !== 'dumb';
@@ -0,0 +1,2 @@
1
+ export * from './capability.ts';
2
+ export * from './prompt.ts';
@@ -0,0 +1,39 @@
1
+ const LINE_FEED = 0x0a;
2
+ const SHOW_CURSOR = '\u001b[?25h';
3
+ const REFUSAL = [
4
+ 'vulcan: this menu reads key presses, not lines, and got a line of piped input (LF).',
5
+ 'Pass the flags instead (for example --agents claude,omp; see --help of the command), or set TERM=dumb to keep the plain line questions.',
6
+ ].join('\n');
7
+
8
+ /**
9
+ * A keyboard in raw mode sends CR for Enter, never LF. LF means the answers were piped in (a script
10
+ * feeding a pty), and a menu would wait for a key that never comes. So while a menu is open, the first
11
+ * LF restores the terminal and ends the command with the way out: a refusal, not a hang.
12
+ */
13
+ export const guardAgainstPipedLines = async <TResult>(
14
+ run: () => Promise<TResult>,
15
+ ): Promise<TResult> => {
16
+ const refuse = (chunk: Buffer | string): void => {
17
+ const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
18
+
19
+ if (!bytes.includes(LINE_FEED)) {
20
+ return;
21
+ }
22
+
23
+ if (process.stdin.isTTY === true) {
24
+ process.stdin.setRawMode(false);
25
+ }
26
+
27
+ process.stdout.write(SHOW_CURSOR);
28
+ process.stderr.write(`\n${REFUSAL}\n`);
29
+ process.exit(1);
30
+ };
31
+
32
+ process.stdin.on('data', refuse);
33
+
34
+ try {
35
+ return await run();
36
+ } finally {
37
+ process.stdin.off('data', refuse);
38
+ }
39
+ };
@@ -0,0 +1,94 @@
1
+ import { confirm, isCancel, multiselect, note, select, text } from '@clack/prompts';
2
+ import { guardAgainstPipedLines } from './keyboard.ts';
3
+
4
+ /** One line of a menu: what it is called, and a short note beside it. */
5
+ export interface IChoice {
6
+ value: string;
7
+ label: string;
8
+ hint?: string;
9
+ }
10
+
11
+ /**
12
+ * Free text, only where there is nothing to pick from (a new name). A default, when there is one, is
13
+ * shown and taken on Enter; `validate` returns the message to show, or nothing when the text is fine.
14
+ * Every prompt answers `null` when the user cancelled (Esc, Ctrl-C): the command stops, never picks
15
+ * for them.
16
+ */
17
+ export const promptText = async (opts: {
18
+ message: string;
19
+ defaultValue?: string;
20
+ validate?: (value: string) => string | undefined;
21
+ }): Promise<string | null> => {
22
+ const value = await guardAgainstPipedLines(() =>
23
+ text({
24
+ message: opts.message,
25
+ ...(opts.defaultValue === undefined
26
+ ? {}
27
+ : { placeholder: opts.defaultValue, defaultValue: opts.defaultValue }),
28
+ validate: input => opts.validate?.(input ?? ''),
29
+ }),
30
+ );
31
+
32
+ return isCancel(value) ? null : value;
33
+ };
34
+
35
+ /** Pick one: arrows to move, Enter to choose. */
36
+ export const promptSelect = async (opts: {
37
+ message: string;
38
+ choices: IChoice[];
39
+ initial?: string;
40
+ }): Promise<string | null> => {
41
+ const value = await guardAgainstPipedLines(() =>
42
+ select({
43
+ message: opts.message,
44
+ options: opts.choices.map(choice => ({
45
+ value: choice.value,
46
+ label: choice.label,
47
+ ...(choice.hint === undefined ? {} : { hint: choice.hint }),
48
+ })),
49
+ initialValue: opts.initial,
50
+ }),
51
+ );
52
+
53
+ return isCancel(value) ? null : value;
54
+ };
55
+
56
+ /** Tick any number: arrows to move, space to toggle, `a` for all, Enter to confirm; what is ticked at the start is `initial`. */
57
+ export const promptMultiselect = async (opts: {
58
+ message: string;
59
+ choices: IChoice[];
60
+ initial: string[];
61
+ }): Promise<string[] | null> => {
62
+ const value = await guardAgainstPipedLines(() =>
63
+ multiselect({
64
+ message: opts.message,
65
+ options: opts.choices.map(choice => ({
66
+ value: choice.value,
67
+ label: choice.label,
68
+ ...(choice.hint === undefined ? {} : { hint: choice.hint }),
69
+ })),
70
+ initialValues: opts.initial,
71
+ required: false,
72
+ }),
73
+ );
74
+
75
+ return isCancel(value) ? null : value;
76
+ };
77
+
78
+ export const promptConfirm = async (opts: {
79
+ message: string;
80
+ initial?: boolean;
81
+ }): Promise<boolean | null> => {
82
+ const value = await guardAgainstPipedLines(() =>
83
+ confirm({ message: opts.message, initialValue: opts.initial ?? true }),
84
+ );
85
+
86
+ return isCancel(value) ? null : value;
87
+ };
88
+
89
+ /** The summary of what is about to be written, then the confirm; true only when the user said yes. */
90
+ export const promptPlan = async (opts: { title: string; lines: string[] }): Promise<boolean> => {
91
+ note(opts.lines.join('\n'), opts.title);
92
+
93
+ return (await promptConfirm({ message: 'Write these files?' })) === true;
94
+ };
@@ -1,8 +0,0 @@
1
- {
2
- "mcpServers": {
3
- "atlas": {
4
- "command": "bun",
5
- "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."]
6
- }
7
- }
8
- }