@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
package/README.md CHANGED
@@ -50,10 +50,10 @@ An unknown key is an error; every error names the file and the field.
50
50
 
51
51
  ## What ships (`base/`)
52
52
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (38 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
53
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (39 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
54
54
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
55
  - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
- - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
56
+ - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
57
57
  - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
58
58
 
59
59
  A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
@@ -0,0 +1,232 @@
1
+ [
2
+ {
3
+ "id": "claude",
4
+ "name": "Claude Code",
5
+ "detect": {
6
+ "binaries": [
7
+ "claude"
8
+ ],
9
+ "homeDirs": [
10
+ "~/.claude"
11
+ ],
12
+ "projectDirs": [
13
+ ".claude"
14
+ ]
15
+ },
16
+ "instructions": {
17
+ "nativeAgentsMd": false,
18
+ "shim": {
19
+ "path": "CLAUDE.md",
20
+ "content": "@AGENTS.md"
21
+ }
22
+ },
23
+ "mcp": {
24
+ "scope": "shared",
25
+ "path": ".mcp.json",
26
+ "renderer": "mcpServers"
27
+ },
28
+ "skills": {
29
+ "dir": ".claude/skills"
30
+ },
31
+ "instructionsSurfaced": true,
32
+ "notes": []
33
+ },
34
+ {
35
+ "id": "omp",
36
+ "name": "omp (oh-my-pi)",
37
+ "detect": {
38
+ "binaries": [
39
+ "omp"
40
+ ],
41
+ "homeDirs": [
42
+ "~/.omp"
43
+ ],
44
+ "projectDirs": [
45
+ ".omp"
46
+ ]
47
+ },
48
+ "instructions": {
49
+ "nativeAgentsMd": true,
50
+ "shim": null
51
+ },
52
+ "mcp": {
53
+ "scope": "shared",
54
+ "path": ".mcp.json",
55
+ "renderer": "mcpServers"
56
+ },
57
+ "skills": {
58
+ "dir": ".agents/skills"
59
+ },
60
+ "instructionsSurfaced": true,
61
+ "notes": []
62
+ },
63
+ {
64
+ "id": "codex",
65
+ "name": "Codex",
66
+ "detect": {
67
+ "binaries": [
68
+ "codex"
69
+ ],
70
+ "homeDirs": [
71
+ "~/.codex"
72
+ ],
73
+ "projectDirs": [
74
+ ".codex"
75
+ ]
76
+ },
77
+ "instructions": {
78
+ "nativeAgentsMd": true,
79
+ "shim": null
80
+ },
81
+ "mcp": {
82
+ "scope": "project",
83
+ "path": ".codex/config.toml",
84
+ "renderer": "codex-toml"
85
+ },
86
+ "skills": {
87
+ "dir": ".agents/skills"
88
+ },
89
+ "instructionsSurfaced": true,
90
+ "notes": [
91
+ "Codex loads .codex/config.toml only for trusted projects: trust this project in Codex."
92
+ ]
93
+ },
94
+ {
95
+ "id": "cursor",
96
+ "name": "Cursor",
97
+ "detect": {
98
+ "binaries": [
99
+ "cursor",
100
+ "cursor-agent"
101
+ ],
102
+ "homeDirs": [
103
+ "~/.cursor"
104
+ ],
105
+ "projectDirs": [
106
+ ".cursor"
107
+ ]
108
+ },
109
+ "instructions": {
110
+ "nativeAgentsMd": true,
111
+ "shim": null
112
+ },
113
+ "mcp": {
114
+ "scope": "project",
115
+ "path": ".cursor/mcp.json",
116
+ "renderer": "mcpServers"
117
+ },
118
+ "skills": {
119
+ "dir": ".agents/skills"
120
+ },
121
+ "instructionsSurfaced": null,
122
+ "notes": []
123
+ },
124
+ {
125
+ "id": "copilot-cli",
126
+ "name": "Copilot CLI",
127
+ "detect": {
128
+ "binaries": [
129
+ "copilot"
130
+ ],
131
+ "homeDirs": [],
132
+ "projectDirs": []
133
+ },
134
+ "instructions": {
135
+ "nativeAgentsMd": true,
136
+ "shim": null
137
+ },
138
+ "mcp": {
139
+ "scope": "shared",
140
+ "path": ".mcp.json",
141
+ "renderer": "mcpServers"
142
+ },
143
+ "skills": {
144
+ "dir": ".agents/skills"
145
+ },
146
+ "instructionsSurfaced": null,
147
+ "notes": []
148
+ },
149
+ {
150
+ "id": "copilot-vscode",
151
+ "name": "Copilot in VS Code",
152
+ "detect": {
153
+ "binaries": [],
154
+ "homeDirs": [
155
+ "~/.vscode/extensions/github.copilot-chat-*"
156
+ ],
157
+ "projectDirs": []
158
+ },
159
+ "instructions": {
160
+ "nativeAgentsMd": true,
161
+ "shim": null
162
+ },
163
+ "mcp": {
164
+ "scope": "project",
165
+ "path": ".vscode/mcp.json",
166
+ "renderer": "servers"
167
+ },
168
+ "skills": {
169
+ "dir": ".agents/skills"
170
+ },
171
+ "instructionsSurfaced": null,
172
+ "notes": []
173
+ },
174
+ {
175
+ "id": "antigravity",
176
+ "name": "Antigravity CLI",
177
+ "detect": {
178
+ "binaries": [
179
+ "agy"
180
+ ],
181
+ "homeDirs": [
182
+ "~/.gemini/antigravity-cli"
183
+ ],
184
+ "projectDirs": []
185
+ },
186
+ "instructions": {
187
+ "nativeAgentsMd": true,
188
+ "shim": null
189
+ },
190
+ "mcp": {
191
+ "scope": "project",
192
+ "path": ".agents/mcp_config.json",
193
+ "renderer": "mcpServers"
194
+ },
195
+ "skills": {
196
+ "dir": ".agents/skills"
197
+ },
198
+ "instructionsSurfaced": false,
199
+ "notes": []
200
+ },
201
+ {
202
+ "id": "pi",
203
+ "name": "Pi",
204
+ "detect": {
205
+ "binaries": [
206
+ "pi"
207
+ ],
208
+ "homeDirs": [
209
+ "~/.pi/agent"
210
+ ],
211
+ "projectDirs": [
212
+ ".pi"
213
+ ]
214
+ },
215
+ "instructions": {
216
+ "nativeAgentsMd": true,
217
+ "shim": null
218
+ },
219
+ "mcp": {
220
+ "scope": "project",
221
+ "path": ".pi/mcp.json",
222
+ "renderer": "mcpServers"
223
+ },
224
+ "skills": {
225
+ "dir": ".agents/skills"
226
+ },
227
+ "instructionsSurfaced": "partial",
228
+ "notes": [
229
+ "Pi loads .pi/mcp.json and .agents/skills only after you trust this project: start pi here and answer the trust prompt."
230
+ ]
231
+ }
232
+ ]
@@ -1,5 +1,8 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
+ "enabledMcpjsonServers": [
4
+ "atlas"
5
+ ],
3
6
  "hooks": {
4
7
  "SessionStart": [
5
8
  {
@@ -30,6 +33,15 @@
30
33
  "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-manifest.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-manifest hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-manifest hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
31
34
  }
32
35
  ]
36
+ },
37
+ {
38
+ "matcher": "Write",
39
+ "hooks": [
40
+ {
41
+ "type": "command",
42
+ "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-package.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-package hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-package hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
43
+ }
44
+ ]
33
45
  }
34
46
  ]
35
47
  }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * PreToolUse hook on Write: a new package.json inside a backend, frontend or shared folder is the
3
+ * start of a hand-made app or library. When the project recorded a preset that makes it, the call
4
+ * is denied with the exact `vulcan add` command; with no preset behind the folder it only adds a
5
+ * note, because a block with no command to offer would leave the agent stuck.
6
+ *
7
+ * Reads only the generated manifest; an existing file, node_modules, or a folder outside the
8
+ * layout passes silently. It fails closed like the other guards: Claude Code blocks a PreToolUse
9
+ * call only on exit 2, so the modules load inside the try.
10
+ */
11
+
12
+ // A module, so the awaits below are top-level; it has no static import, by design.
13
+ export {};
14
+
15
+ try {
16
+ const { buildPackageDecision, inspectPackageWrite, parseManifestHookInput } =
17
+ await import('../../src/hooks/index.ts');
18
+ const input = parseManifestHookInput({ text: await Bun.stdin.text() });
19
+ const verdict = input && inspectPackageWrite({ input });
20
+
21
+ if (verdict) {
22
+ console.log(JSON.stringify(buildPackageDecision({ verdict })));
23
+ }
24
+ } catch (error) {
25
+ console.error(
26
+ `vulcan: the guard-package hook failed (${error instanceof Error ? error.message : String(error)}) - blocked; run bun install`,
27
+ );
28
+ process.exit(2);
29
+ }
package/base/rules.md CHANGED
@@ -57,6 +57,7 @@ Retired IDs are never reused (2026-10-17):
57
57
  | V-B-02 | The project's lint and test gates pass with zero warnings before "done". | SOFT - pre-commit runs `vulcan doctor` and lint |
58
58
  | V-B-03 | Run it, read real output, then claim. Evidence before assertions. | SOFT |
59
59
  | V-B-04 | Never green the suite by weakening it: no deleted/skipped tests, loosened asserts, relaxed strictness, `any`. Red test = information. | SOFT |
60
+ | V-B-05 | **One script set for every app**, backend and frontend: `server:dev` (`NODE_ENV=development bun run src/index.ts` for a backend, `vite --config .configs/builders/vite.config.mts` for a frontend), `compile` (`bun .configs/builders/compile.ts` for a backend, `vite build --config .configs/builders/vite.config.mts` for a frontend), `typecheck` (`bun check`), `lint` (`devz lint`), `lint:fix` (`devz lint --fix`), `test` (`bun test`), `clean` (`devz clean`). The logic lives in `.configs/builders/` or in `devz`, never in the `package.json` string. No `dev`, `start`, `build`, `rebuild`, `preview` or `server:prod`. A domain extra such as `migrate:dev` is allowed on top. **An app root holds only `.configs/`, `src/`, `package.json`, `tsconfig.json` and `.env.example`**; every other config lives in `.configs/{lints,formatters,builders}/`. A library package keeps Makefile targets instead: `build`, `typecheck`, `lint`, `lint-fix`, `test`, `clean`. | SOFT - `vulcan doctor` notes an app that lacks one or carries a legacy name (info, never a failure) |
60
61
 
61
62
  ## C - Code and writing
62
63
 
@@ -3,8 +3,8 @@
3
3
  How to work in {{name}}. **This file is routing only** - it holds no rules and no facts, it points
4
4
  to where both live.
5
5
 
6
- Tool files are gitignored pointers to this one - `CLAUDE.md` holds only `@AGENTS.md` - written by
7
- `bun x --no-install vulcan sync`.
6
+ Tool files (`CLAUDE.md`, ...) are per-developer pointers to this one, written by
7
+ `bun x --no-install vulcan sync` for the agents you chose.
8
8
 
9
9
  ## Must read first
10
10
 
@@ -18,6 +18,7 @@ Tool files are gitignored pointers to this one - `CLAUDE.md` holds only `@AGENTS
18
18
 
19
19
  | Command | What it does |
20
20
  |---|---|
21
- | `bun x --no-install vulcan sync` | Write CLAUDE.md, `.claude/settings.json` and the skill links |
21
+ | `bun x --no-install vulcan sync` | Write the adapters of the agents you chose (`--agents list` shows them) |
22
+ | `bun x --no-install vulcan agents add\|remove <ids>` | Change the agents you use on this machine |
22
23
  | `bun x --no-install vulcan doctor` | Check this project follows VULCAN |
23
24
  | `bun x --no-install vulcan x okf check` | Check the knowledge bundle against OKF v0.2 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.5",
3
+ "version": "0.3.6",
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.5",
48
- "@venizia/vulcan-okf": "0.3.5",
47
+ "@venizia/vulcan-atlas": "0.3.6",
48
+ "@venizia/vulcan-okf": "0.3.6",
49
49
  "zod": "^4.5.4"
50
50
  },
51
51
  "devDependencies": {
@@ -0,0 +1,54 @@
1
+ export const ATLAS_BLOCK_START =
2
+ '<!-- vulcan:atlas:start - generated by vulcan sync from .configs/vulcan.config.*; do not edit -->';
3
+ export const ATLAS_BLOCK_END = '<!-- vulcan:atlas:end -->';
4
+ const START_PREFIX = '<!-- vulcan:atlas:start';
5
+ const MUST_READ = '## Must read first';
6
+
7
+ /**
8
+ * The guidance every agent that reads AGENTS.md gets, whatever its client drops of the MCP server's
9
+ * own text. Rendered from the config, so it is the same for every developer and safe to commit.
10
+ */
11
+ export const renderAtlasBlock = (opts: { project: string; sources: string[] }): string =>
12
+ [
13
+ ATLAS_BLOCK_START,
14
+ '## Atlas',
15
+ '',
16
+ `The \`atlas\` MCP server holds the real code and docs of: ${[`${opts.project} (this repository)`, ...opts.sources].join(', ')}.`,
17
+ 'Look facts up there before you answer or write from memory (V-P-07):',
18
+ '`symbol` before you use an export (signature, import path, source line); `search`, then `get`, for how something works or which convention applies; `version` or `changes` for a release or an upgrade.',
19
+ 'A new app or package: ask `presets` which preset and which `vulcan add` command, run it, and never hand-write package.json, tsconfig or scripts.',
20
+ ATLAS_BLOCK_END,
21
+ '',
22
+ ].join('\n');
23
+
24
+ /**
25
+ * Puts the block into AGENTS.md: rewritten between its markers when it is there, else inserted
26
+ * before the section that follows "Must read first", else appended. Text outside is never touched.
27
+ */
28
+ export const mergeAtlasBlock = (opts: {
29
+ text: string;
30
+ block: string;
31
+ }): { changed: boolean; text: string } => {
32
+ const start = opts.text.indexOf(START_PREFIX);
33
+ const end = opts.text.indexOf(ATLAS_BLOCK_END);
34
+ let text: string;
35
+
36
+ if (opts.text === '') {
37
+ text = opts.block;
38
+ } else if (start !== -1 && end > start) {
39
+ text = `${opts.text.slice(0, start)}${opts.block.trimEnd()}${opts.text.slice(end + ATLAS_BLOCK_END.length)}`;
40
+ } else {
41
+ const heading = opts.text.indexOf(MUST_READ);
42
+ const next = heading === -1 ? -1 : opts.text.indexOf('\n## ', heading + MUST_READ.length);
43
+
44
+ if (next === -1) {
45
+ text = `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`;
46
+ } else {
47
+ const at = next + 1;
48
+
49
+ text = `${opts.text.slice(0, at)}${opts.block}\n${opts.text.slice(at)}`;
50
+ }
51
+ }
52
+
53
+ return { changed: text !== opts.text, text };
54
+ };
@@ -0,0 +1,38 @@
1
+ /** Where an agent reads the atlas MCP entry: the committed root `.mcp.json`, or a file of its own. */
2
+ export class AgentScopes {
3
+ static readonly PROJECT = 'project';
4
+ static readonly SHARED = 'shared';
5
+
6
+ static readonly SCHEME_SET = new Set<string>([this.PROJECT, this.SHARED]);
7
+
8
+ static isValid(value: string): boolean {
9
+ return this.SCHEME_SET.has(value);
10
+ }
11
+ }
12
+
13
+ /** The file formats an agent's MCP entry is written in. */
14
+ export class AgentRenderers {
15
+ static readonly MCP_SERVERS = 'mcpServers';
16
+ static readonly SERVERS = 'servers';
17
+ static readonly CODEX_TOML = 'codex-toml';
18
+
19
+ static readonly SCHEME_SET = new Set<string>([this.MCP_SERVERS, this.SERVERS, this.CODEX_TOML]);
20
+
21
+ static isValid(value: string): boolean {
22
+ return this.SCHEME_SET.has(value);
23
+ }
24
+ }
25
+
26
+ export class AgentConstants {
27
+ /** The per-developer choice: gitignored, written by sync, never by hand. */
28
+ static readonly LOCAL_FILE = '.agents/vulcan.local.json';
29
+ static readonly LOCAL_SCHEMA_VERSION = 1;
30
+ static readonly LOCAL_NOTE = 'by vulcan sync - your agents on this machine; not committed';
31
+ static readonly FLAG = '--agents';
32
+ static readonly LIST = 'list';
33
+ static readonly NONE = 'none';
34
+ /** The shared MCP file `claude`, `omp` and `copilot-cli` all read. */
35
+ static readonly SHARED_MCP_FILE = '.mcp.json';
36
+ static readonly DEFAULT_AGENT = 'claude';
37
+ static readonly EXAMPLE_LIST = 'claude,omp';
38
+ }
@@ -0,0 +1,3 @@
1
+ export * from './constants.ts';
2
+ export * from './schema.ts';
3
+ export * from './types.ts';
@@ -0,0 +1,42 @@
1
+ import { z } from 'zod';
2
+ import { AgentConstants, AgentRenderers, AgentScopes } from './constants.ts';
3
+
4
+ /** One agent of `base/agents.json`: strict, so a typo in the table is an error, not a silent gap. */
5
+ export const AGENT_ENTRY_SCHEMA = z
6
+ .strictObject({
7
+ id: z.string().regex(/^[a-z][a-z0-9-]*$/),
8
+ name: z.string().min(1),
9
+ detect: z.strictObject({
10
+ binaries: z.array(z.string()),
11
+ homeDirs: z.array(z.string()),
12
+ projectDirs: z.array(z.string()),
13
+ }),
14
+ instructions: z.strictObject({
15
+ nativeAgentsMd: z.boolean(),
16
+ shim: z.strictObject({ path: z.string(), content: z.string() }).nullable(),
17
+ }),
18
+ mcp: z.strictObject({
19
+ scope: z.string().refine(value => AgentScopes.isValid(value), {
20
+ message: `one of: ${[...AgentScopes.SCHEME_SET].join(', ')}`,
21
+ }),
22
+ path: z.string().min(1),
23
+ renderer: z.string().refine(value => AgentRenderers.isValid(value), {
24
+ message: `one of: ${[...AgentRenderers.SCHEME_SET].join(', ')}`,
25
+ }),
26
+ }),
27
+ skills: z.strictObject({ dir: z.string().min(1) }),
28
+ instructionsSurfaced: z.union([z.boolean(), z.literal('partial'), z.null()]),
29
+ notes: z.array(z.string()),
30
+ })
31
+ .superRefine((entry, context) => {
32
+ if (
33
+ entry.mcp.scope === AgentScopes.SHARED &&
34
+ entry.mcp.path !== AgentConstants.SHARED_MCP_FILE
35
+ ) {
36
+ context.addIssue({
37
+ code: 'custom',
38
+ path: ['mcp', 'path'],
39
+ message: `a shared entry points at ${AgentConstants.SHARED_MCP_FILE}`,
40
+ });
41
+ }
42
+ });
@@ -0,0 +1,30 @@
1
+ import type { z } from 'zod';
2
+ import type { AGENT_ENTRY_SCHEMA } from './schema.ts';
3
+
4
+ export type TAgentEntry = z.infer<typeof AGENT_ENTRY_SCHEMA>;
5
+
6
+ /** What the question shows: what was detected on this machine, and what the developer chose before. */
7
+ export interface IAgentQuestion {
8
+ detected: string[];
9
+ stored: string[] | undefined;
10
+ }
11
+
12
+ export type TAskAgents = (question: IAgentQuestion) => string | null;
13
+
14
+ export type TAgentSource = 'flag' | 'local' | 'config' | 'migration' | 'asked' | 'default';
15
+
16
+ export type TAgentResolution =
17
+ | {
18
+ ok: true;
19
+ agents: string[];
20
+ source: TAgentSource;
21
+ /** Whether sync stores the list in the local file. */
22
+ writeLocal: boolean;
23
+ /** One line for stderr when the machine has not chosen. */
24
+ hint: string | undefined;
25
+ }
26
+ | { ok: false; error: string };
27
+
28
+ export type TLocalChoice =
29
+ | { ok: true; agents: string[] | undefined }
30
+ | { ok: false; error: string };
@@ -0,0 +1,36 @@
1
+ import { Glob } from 'bun';
2
+ import { existsSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { readAgentTable } from './table.ts';
5
+
6
+ const HOME_PREFIX = '~/';
7
+
8
+ const hasHomeEntry = (opts: { home: string; pattern: string }): boolean => {
9
+ const relative = opts.pattern.slice(HOME_PREFIX.length);
10
+
11
+ if (!relative.includes('*')) {
12
+ return existsSync(join(opts.home, relative));
13
+ }
14
+
15
+ return (
16
+ existsSync(opts.home) &&
17
+ [...new Glob(relative).scanSync({ cwd: opts.home, onlyFiles: false, dot: true })].length > 0
18
+ );
19
+ };
20
+
21
+ /**
22
+ * The agents this machine seems to have, in table order: a binary on PATH, a folder in the home, a
23
+ * folder in the project. It only pre-selects; the developer confirms.
24
+ */
25
+ export const detectAgents = (opts: { root: string; home: string; path: string }): string[] =>
26
+ readAgentTable()
27
+ .filter(entry => {
28
+ const { binaries, homeDirs, projectDirs } = entry.detect;
29
+
30
+ return (
31
+ binaries.some(name => Bun.which(name, { PATH: opts.path, cwd: opts.root }) !== null) ||
32
+ homeDirs.some(pattern => hasHomeEntry({ home: opts.home, pattern })) ||
33
+ projectDirs.some(directory => existsSync(join(opts.root, directory)))
34
+ );
35
+ })
36
+ .map(entry => entry.id);
@@ -0,0 +1,87 @@
1
+ import { AgentConstants, AgentScopes } from './common/index.ts';
2
+ import { LOCAL_AGENTS_FILE } from './local.ts';
3
+ import { readAgentTable } from './table.ts';
4
+
5
+ export const EXCLUDE_BLOCK_START =
6
+ '# vulcan:start - written by vulcan sync for the agents you chose; do not edit';
7
+ export const EXCLUDE_BLOCK_END = '# vulcan:end';
8
+ const START_PREFIX = '# vulcan:start';
9
+ const CLAUDE_SKILLS_DIRECTORY = '.claude/skills';
10
+
11
+ export interface IExcludeGroup {
12
+ title: string;
13
+ /** Root-relative and anchored with a leading slash; a folder ends with one. */
14
+ paths: string[];
15
+ }
16
+
17
+ /**
18
+ * What sync creates for the chosen agents and so keeps out of `git status` on this machine: the
19
+ * shim and folder of Claude, each agent's own MCP file, the shipped-skill links of the folders the
20
+ * agents read (once per folder), and the local choice file.
21
+ */
22
+ export const excludePathsOf = (opts: {
23
+ agents: string[];
24
+ skillNames: string[];
25
+ }): IExcludeGroup[] => {
26
+ const listedSkills = new Set<string>();
27
+ const groups: IExcludeGroup[] = [];
28
+
29
+ for (const entry of readAgentTable().filter(item => opts.agents.includes(item.id))) {
30
+ const paths: string[] = [];
31
+
32
+ if (entry.instructions.shim !== null) {
33
+ paths.push(`/${entry.instructions.shim.path}`);
34
+ }
35
+
36
+ if (entry.id === AgentConstants.DEFAULT_AGENT) {
37
+ paths.push('/.claude/');
38
+ }
39
+
40
+ if (entry.mcp.scope === AgentScopes.PROJECT) {
41
+ paths.push(`/${entry.mcp.path}`);
42
+ }
43
+
44
+ if (entry.skills.dir !== CLAUDE_SKILLS_DIRECTORY && !listedSkills.has(entry.skills.dir)) {
45
+ listedSkills.add(entry.skills.dir);
46
+ paths.push(...opts.skillNames.map(name => `/${entry.skills.dir}/${name}`));
47
+ }
48
+
49
+ if (paths.length > 0) {
50
+ groups.push({ title: entry.id, paths });
51
+ }
52
+ }
53
+
54
+ return [...groups, { title: 'local', paths: [`/${LOCAL_AGENTS_FILE}`] }];
55
+ };
56
+
57
+ export const renderExcludeBlock = (opts: { groups: IExcludeGroup[] }): string =>
58
+ [
59
+ EXCLUDE_BLOCK_START,
60
+ ...opts.groups.flatMap(group => [`# ${group.title}`, ...group.paths]),
61
+ EXCLUDE_BLOCK_END,
62
+ '',
63
+ ].join('\n');
64
+
65
+ /** The block replaces itself between its markers; the user's own lines in the file are never touched. */
66
+ export const mergeExcludeBlock = (opts: {
67
+ text: string | undefined;
68
+ block: string;
69
+ }): { changed: boolean; text: string } => {
70
+ if (opts.text === undefined || opts.text === '') {
71
+ return { changed: true, text: opts.block };
72
+ }
73
+
74
+ const start = opts.text.indexOf(START_PREFIX);
75
+ const end = opts.text.indexOf(EXCLUDE_BLOCK_END);
76
+
77
+ if (start !== -1 && end > start) {
78
+ const text = `${opts.text.slice(0, start)}${opts.block.trimEnd()}${opts.text.slice(end + EXCLUDE_BLOCK_END.length)}`;
79
+
80
+ return { changed: text !== opts.text, text };
81
+ }
82
+
83
+ return {
84
+ changed: true,
85
+ text: `${opts.text}${opts.text.endsWith('\n') ? '' : '\n'}\n${opts.block}`,
86
+ };
87
+ };
@@ -0,0 +1,9 @@
1
+ export * from './common/index.ts';
2
+ export * from './detect.ts';
3
+ export * from './local.ts';
4
+ export * from './prompt.ts';
5
+ export * from './resolve.ts';
6
+ export * from './table.ts';
7
+ export * from './render.ts';
8
+ export * from './atlas-block.ts';
9
+ export * from './exclude.ts';