@venizia/vulcan 0.2.0-7 → 0.2.0-9
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/README.md +3 -3
- package/base/claude/remote-hosts.json +15 -0
- package/base/hooks/guard-remote-hosts.ts +55 -0
- package/base/slots.json +28 -5
- package/base/templates/Makefile +12 -0
- package/base/templates/mcp.json +8 -0
- package/package.json +3 -3
- package/src/config/packages.ts +8 -19
- package/src/config/schema.ts +43 -3
- package/src/doctor/checks.ts +24 -5
- package/src/hooks/index.ts +1 -0
- package/src/hooks/remote-hosts.ts +947 -0
- package/src/init/scaffold.ts +20 -6
- package/src/manifest/render.ts +2 -0
- package/src/sync/common/constants.ts +2 -0
- package/src/sync/planner.ts +9 -0
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
|
|
|
16
16
|
|
|
17
17
|
| Command | What it does |
|
|
18
18
|
|---|---|
|
|
19
|
-
| `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile `-include
|
|
19
|
+
| `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, the atlas `.mcp.json`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
|
|
20
20
|
| `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed, and a hook it wrote is taken back by its command even after you edited its entry), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--prune` also removes what sync proves stale and did not write: an old VULCAN or plugin-era hook command (a shipped hook exactly as an older VULCAN released it, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook, a customised shipped command, a real directory or a symlinked `.claude/skills`. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
|
|
21
21
|
| `doctor` | Check the project follows VULCAN; exit 1 on any violation |
|
|
22
22
|
| `upgrade [<version\|tag>]` | Install the target `@venizia/vulcan` (default: the `next` dist-tag), then run `sync` from the newly installed CLI |
|
|
@@ -49,8 +49,8 @@ An unknown key is an error; every error names the file and the field.
|
|
|
49
49
|
|
|
50
50
|
- `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (37 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
|
|
51
51
|
- `slots.json` - rules a project picks a wording for (V-W-01 today).
|
|
52
|
-
- `skills/` - `knowledge-sync`, `docs-writing`, `docs-update` (project-neutral; a project-specific skill stays in its project).
|
|
53
|
-
- `hooks/` - `session-start.ts` (prints the rules digest)
|
|
52
|
+
- `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.
|
|
53
|
+
- `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) 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).
|
|
54
54
|
- `claude/settings.json`, `make/vulcan.mk`, `templates/`.
|
|
55
55
|
|
|
56
56
|
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,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"hooks": {
|
|
3
|
+
"PreToolUse": [
|
|
4
|
+
{
|
|
5
|
+
"matcher": "Bash",
|
|
6
|
+
"hooks": [
|
|
7
|
+
{
|
|
8
|
+
"type": "command",
|
|
9
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-remote-hosts.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-remote-hosts hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-remote-hosts 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"
|
|
10
|
+
}
|
|
11
|
+
]
|
|
12
|
+
}
|
|
13
|
+
]
|
|
14
|
+
}
|
|
15
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* PreToolUse hook on Bash: asks before a command reaches a host the project has not listed in
|
|
3
|
+
* `remoteHosts` (trusted, or readOnly for the strict read-only forms). The policy is read from the
|
|
4
|
+
* committed manifest, `.agents/vulcan.manifest.json`, plus the personal list `remoteHosts.localFile`.
|
|
5
|
+
*
|
|
6
|
+
* It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so every error here - a missing
|
|
7
|
+
* module, a manifest without the policy - exits 2. The modules load inside the try for that reason.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
// A module, so the awaits below are top-level; it has no static import, by design.
|
|
11
|
+
export {};
|
|
12
|
+
|
|
13
|
+
try {
|
|
14
|
+
const { buildRemoteDecision, inspectRemoteCommand, parseHookCommand, parseTrustedList } =
|
|
15
|
+
await import('../../src/hooks/index.ts');
|
|
16
|
+
const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
17
|
+
const manifestFile = Bun.file(`${root}/.agents/vulcan.manifest.json`);
|
|
18
|
+
|
|
19
|
+
if (!(await manifestFile.exists())) {
|
|
20
|
+
throw new Error('.agents/vulcan.manifest.json is missing - run vulcan sync');
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const manifest = await manifestFile.json();
|
|
24
|
+
const remoteHosts = manifest?.remoteHosts;
|
|
25
|
+
|
|
26
|
+
if (typeof remoteHosts !== 'object' || remoteHosts === null) {
|
|
27
|
+
throw new Error('the manifest has no remoteHosts - run vulcan sync');
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
const localFile = typeof remoteHosts.localFile === 'string' ? remoteHosts.localFile : undefined;
|
|
31
|
+
const local = localFile === undefined ? undefined : Bun.file(`${root}/${localFile}`);
|
|
32
|
+
const personal = local !== undefined && (await local.exists()) ? await local.text() : '';
|
|
33
|
+
const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
|
|
34
|
+
const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
|
|
35
|
+
const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
|
|
36
|
+
const hits = hookCommand
|
|
37
|
+
? inspectRemoteCommand({
|
|
38
|
+
command: hookCommand.command,
|
|
39
|
+
policy: {
|
|
40
|
+
trusted: [...trusted, ...parseTrustedList({ text: personal })],
|
|
41
|
+
readOnly,
|
|
42
|
+
...(localFile === undefined ? {} : { localFile }),
|
|
43
|
+
},
|
|
44
|
+
})
|
|
45
|
+
: [{ rule: 'remote-hosts', message: 'the hook input could not be read' }];
|
|
46
|
+
|
|
47
|
+
if (hits.length > 0) {
|
|
48
|
+
console.log(JSON.stringify(buildRemoteDecision({ hits })));
|
|
49
|
+
}
|
|
50
|
+
} catch (error) {
|
|
51
|
+
console.error(
|
|
52
|
+
`vulcan: the guard-remote-hosts hook failed (${error instanceof Error ? error.message : String(error)}) - blocked`,
|
|
53
|
+
);
|
|
54
|
+
process.exit(2);
|
|
55
|
+
}
|
package/base/slots.json
CHANGED
|
@@ -5,27 +5,50 @@
|
|
|
5
5
|
"text": "Git writes happen only on the user's word, in this conversation."
|
|
6
6
|
},
|
|
7
7
|
"read-only": {
|
|
8
|
-
"text": "Git is read-only for the agent: it edits the working tree, then stops; a human commits.",
|
|
8
|
+
"text": "Git is read-only for the agent: it edits the working tree, then stops; a human commits. Every git verb that writes the index, the history, a ref, the config or the work tree is denied.",
|
|
9
9
|
"settings": {
|
|
10
10
|
"permissions": {
|
|
11
11
|
"deny": [
|
|
12
|
-
"Bash(git add:*)",
|
|
13
12
|
"Bash(git add)",
|
|
14
|
-
"Bash(git
|
|
13
|
+
"Bash(git add:*)",
|
|
14
|
+
"Bash(git rm:*)",
|
|
15
|
+
"Bash(git mv:*)",
|
|
16
|
+
"Bash(git restore:*)",
|
|
15
17
|
"Bash(git commit)",
|
|
16
|
-
"Bash(git
|
|
18
|
+
"Bash(git commit:*)",
|
|
17
19
|
"Bash(git push)",
|
|
20
|
+
"Bash(git push:*)",
|
|
21
|
+
"Bash(git pull)",
|
|
18
22
|
"Bash(git pull:*)",
|
|
23
|
+
"Bash(git merge)",
|
|
19
24
|
"Bash(git merge:*)",
|
|
25
|
+
"Bash(git rebase)",
|
|
20
26
|
"Bash(git rebase:*)",
|
|
27
|
+
"Bash(git reset)",
|
|
21
28
|
"Bash(git reset:*)",
|
|
22
29
|
"Bash(git revert:*)",
|
|
30
|
+
"Bash(git cherry-pick:*)",
|
|
31
|
+
"Bash(git checkout)",
|
|
23
32
|
"Bash(git checkout:*)",
|
|
24
33
|
"Bash(git switch:*)",
|
|
34
|
+
"Bash(git branch)",
|
|
25
35
|
"Bash(git branch:*)",
|
|
36
|
+
"Bash(git tag:*)",
|
|
37
|
+
"Bash(git stash)",
|
|
26
38
|
"Bash(git stash:*)",
|
|
27
39
|
"Bash(git clean:*)",
|
|
28
|
-
"Bash(git
|
|
40
|
+
"Bash(git apply:*)",
|
|
41
|
+
"Bash(git am:*)",
|
|
42
|
+
"Bash(git worktree:*)",
|
|
43
|
+
"Bash(git remote:*)",
|
|
44
|
+
"Bash(git config:*)",
|
|
45
|
+
"Bash(git submodule:*)",
|
|
46
|
+
"Bash(git update-ref:*)",
|
|
47
|
+
"Bash(git filter-branch:*)",
|
|
48
|
+
"Bash(git gc:*)",
|
|
49
|
+
"Bash(git init:*)",
|
|
50
|
+
"Bash(git clone:*)",
|
|
51
|
+
"Bash(git notes:*)"
|
|
29
52
|
]
|
|
30
53
|
}
|
|
31
54
|
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# {{name}}. `make help` lists the targets. VULCAN's shared targets (okf-*, vulcan-*, atlas-*) come from the include.
|
|
2
|
+
|
|
3
|
+
# `-include`: a fresh clone has no node_modules yet, and `make install` must still run.
|
|
4
|
+
-include node_modules/@venizia/vulcan/base/make/vulcan.mk
|
|
5
|
+
|
|
6
|
+
# Without the include no shared target exists, and make would answer "No rule to make target" for each.
|
|
7
|
+
# This says what to do instead. A target the project defines itself (install) is untouched.
|
|
8
|
+
ifeq ($(wildcard node_modules/@venizia/vulcan/base/make/vulcan.mk),)
|
|
9
|
+
node_modules/@venizia/vulcan/base/make/vulcan.mk: ;
|
|
10
|
+
%:
|
|
11
|
+
@echo "vulcan: node_modules/@venizia/vulcan is missing - run 'make install' (bun install) first" >&2; exit 1
|
|
12
|
+
endif
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.2.0-
|
|
3
|
+
"version": "0.2.0-9",
|
|
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.2.0-
|
|
48
|
-
"@venizia/vulcan-okf": "0.2.0-
|
|
47
|
+
"@venizia/vulcan-atlas": "0.2.0-9",
|
|
48
|
+
"@venizia/vulcan-okf": "0.2.0-9",
|
|
49
49
|
"zod": "^4.5.4"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
package/src/config/packages.ts
CHANGED
|
@@ -11,23 +11,12 @@ export interface IProjectPackage {
|
|
|
11
11
|
retired: boolean;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
|
-
/** The project's packages in release order
|
|
15
|
-
export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPackage[] =>
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
retired: entry.retired,
|
|
23
|
-
}));
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
return Object.entries(opts.config.atlas.packages ?? {}).map(([dir, name]) => ({
|
|
27
|
-
dir,
|
|
28
|
-
name,
|
|
29
|
-
path: `${DEFAULT_PACKAGES_DIRECTORY}/${dir}`,
|
|
30
|
-
aliases: [],
|
|
31
|
-
retired: false,
|
|
14
|
+
/** The project's packages in release order. */
|
|
15
|
+
export const resolvePackages = (opts: { config: TResolvedConfig }): IProjectPackage[] =>
|
|
16
|
+
opts.config.packages.map(entry => ({
|
|
17
|
+
dir: entry.dir,
|
|
18
|
+
name: entry.name,
|
|
19
|
+
path: entry.path ?? `${DEFAULT_PACKAGES_DIRECTORY}/${entry.dir}`,
|
|
20
|
+
aliases: entry.aliases,
|
|
21
|
+
retired: entry.retired,
|
|
32
22
|
}));
|
|
33
|
-
};
|
package/src/config/schema.ts
CHANGED
|
@@ -78,6 +78,17 @@ const OKF_RENDERER = z.union([
|
|
|
78
78
|
}),
|
|
79
79
|
]);
|
|
80
80
|
|
|
81
|
+
/** A host name, or a pattern whose only wildcard is `*`; a `$VAR` stands for a host the shell expands. Never a user, a path or a port. */
|
|
82
|
+
const REMOTE_HOST = z
|
|
83
|
+
.string()
|
|
84
|
+
.regex(
|
|
85
|
+
/^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/,
|
|
86
|
+
'a host name or a pattern with *, not a user, a path or a port',
|
|
87
|
+
)
|
|
88
|
+
.refine(value => value.replaceAll('*', '').replaceAll('.', '') !== '', {
|
|
89
|
+
message: 'a pattern needs at least one literal character beyond * and .',
|
|
90
|
+
});
|
|
91
|
+
|
|
81
92
|
const VIZ_OUTPUT = '.agents/knowledge/viz.html';
|
|
82
93
|
|
|
83
94
|
/** `.configs/vulcan.config.*` - strict: an unknown key is a typo, and a typo is an error. */
|
|
@@ -112,7 +123,18 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
112
123
|
labels: z.record(z.string(), z.string()).default({}),
|
|
113
124
|
})
|
|
114
125
|
.default({ order: [], labels: {} }),
|
|
115
|
-
|
|
126
|
+
/** `exclude`: globs from the root dropped from this axis; `denylist`: directory names dropped from this axis only. */
|
|
127
|
+
coverage: z
|
|
128
|
+
.array(
|
|
129
|
+
z.strictObject({
|
|
130
|
+
name: z.string(),
|
|
131
|
+
path: z.string(),
|
|
132
|
+
exclude: z.array(z.string()).default([]),
|
|
133
|
+
denylist: z.array(z.string()).default([]),
|
|
134
|
+
}),
|
|
135
|
+
)
|
|
136
|
+
.default([]),
|
|
137
|
+
/** Directory names no axis counts; an axis's own `denylist` scopes the same idea to one axis. */
|
|
116
138
|
denylist: z.array(z.string()).default([]),
|
|
117
139
|
/** Agent-read files outside the bundle that get a generated contents list when they pass 100 lines. */
|
|
118
140
|
contents: z
|
|
@@ -137,8 +159,13 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
137
159
|
}),
|
|
138
160
|
atlas: z
|
|
139
161
|
.strictObject({
|
|
140
|
-
/**
|
|
141
|
-
packages: z
|
|
162
|
+
/** Removed in 0.2.0-8; present only so the error can name `packages`. */
|
|
163
|
+
packages: z
|
|
164
|
+
.never({
|
|
165
|
+
error:
|
|
166
|
+
'atlas.packages was removed - move the list to the top-level packages: [{ dir, name }] (release order; dir is the old key, name the old value)',
|
|
167
|
+
})
|
|
168
|
+
.optional(),
|
|
142
169
|
releaseCommit: RELEASE_TEMPLATE.default('[#<issue>] chore(<dir>): release v<version>'),
|
|
143
170
|
tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
|
|
144
171
|
sources: z
|
|
@@ -160,6 +187,19 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
160
187
|
tagPattern: '<dir>-v<version>',
|
|
161
188
|
sources: [],
|
|
162
189
|
}),
|
|
190
|
+
/**
|
|
191
|
+
* The remote-host guard (W-04 in a project's own words): with this key set, sync registers a hook that
|
|
192
|
+
* asks before a Bash command reaches a host not listed here. `trusted` hosts are free; `readOnly`
|
|
193
|
+
* hosts pass only the strict read-only forms. Matching is by whole name or `*` pattern, never by substring.
|
|
194
|
+
* `localFile` is a gitignored list of personal trusted hosts, one per line.
|
|
195
|
+
*/
|
|
196
|
+
remoteHosts: z
|
|
197
|
+
.strictObject({
|
|
198
|
+
trusted: z.array(REMOTE_HOST).default([]),
|
|
199
|
+
readOnly: z.array(REMOTE_HOST).default([]),
|
|
200
|
+
localFile: z.string().default('.agents/hooks/trusted-hosts.local'),
|
|
201
|
+
})
|
|
202
|
+
.optional(),
|
|
163
203
|
/** Team-shared Claude settings (permissions, env, enabledPlugins...), merged by sync over personal keys. */
|
|
164
204
|
claude: z
|
|
165
205
|
.strictObject({ settings: z.record(z.string(), z.unknown()).default({}) })
|
package/src/doctor/checks.ts
CHANGED
|
@@ -215,11 +215,28 @@ export const checkHooks = (opts: ICheckContext): IViolation[] =>
|
|
|
215
215
|
}),
|
|
216
216
|
);
|
|
217
217
|
|
|
218
|
-
export const checkAdapters = (opts: ICheckContext): IViolation[] =>
|
|
219
|
-
planSync({ root: opts.root, config: opts.config })
|
|
218
|
+
export const checkAdapters = (opts: ICheckContext): IViolation[] => {
|
|
219
|
+
const pending = planSync({ root: opts.root, config: opts.config })
|
|
220
220
|
.filter(action => action.status !== SyncStatuses.UNCHANGED)
|
|
221
|
-
.filter(action => action.path !== join(opts.root, ManifestConstants.FILE))
|
|
222
|
-
|
|
221
|
+
.filter(action => action.path !== join(opts.root, ManifestConstants.FILE));
|
|
222
|
+
const absent = pending.filter(action => action.status === SyncStatuses.CREATED);
|
|
223
|
+
const differing = pending.filter(action => action.status !== SyncStatuses.CREATED);
|
|
224
|
+
|
|
225
|
+
// A clean checkout has none of the gitignored adapters: say so once, with the fix, not once per file.
|
|
226
|
+
const violations =
|
|
227
|
+
absent.length === 0
|
|
228
|
+
? []
|
|
229
|
+
: [
|
|
230
|
+
createViolation({
|
|
231
|
+
check: DoctorChecks.ADAPTERS,
|
|
232
|
+
file: relative(opts.root, absent[0].path),
|
|
233
|
+
message: `not synced yet - run '${ProjectLayout.VULCAN_COMMAND} sync' (make agent-setup) first`,
|
|
234
|
+
}),
|
|
235
|
+
];
|
|
236
|
+
|
|
237
|
+
return [
|
|
238
|
+
...violations,
|
|
239
|
+
...differing.map(action =>
|
|
223
240
|
createViolation({
|
|
224
241
|
check: DoctorChecks.ADAPTERS,
|
|
225
242
|
file: relative(opts.root, action.path),
|
|
@@ -228,7 +245,9 @@ export const checkAdapters = (opts: ICheckContext): IViolation[] =>
|
|
|
228
245
|
? (action.note ?? 'skipped by sync')
|
|
229
246
|
: `stale (${action.status}) - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
|
|
230
247
|
}),
|
|
231
|
-
)
|
|
248
|
+
),
|
|
249
|
+
];
|
|
250
|
+
};
|
|
232
251
|
|
|
233
252
|
/** What `sync --prune` would remove: an old VULCAN or plugin-era hook command, a dead skill link. */
|
|
234
253
|
export const checkPrune = (opts: ICheckContext): IViolation[] =>
|
package/src/hooks/index.ts
CHANGED