@venizia/vulcan 0.3.1 → 0.3.3

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 CHANGED
@@ -53,7 +53,7 @@ An unknown key is an error; every error names the file and the field.
53
53
  - `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).
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) 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`) 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
@@ -21,6 +21,15 @@
21
21
  "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.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-writes 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-writes 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"
22
22
  }
23
23
  ]
24
+ },
25
+ {
26
+ "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
27
+ "hooks": [
28
+ {
29
+ "type": "command",
30
+ "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
+ }
32
+ ]
24
33
  }
25
34
  ]
26
35
  }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * PreToolUse hook on Write, Edit, MultiEdit, NotebookEdit and Bash: refuses a write to
3
+ * .agents/vulcan.manifest.json. The file is rendered from the config by `vulcan sync`, so a hand
4
+ * edit is either lost on the next sync or hides a config change from the doctor.
5
+ *
6
+ * Unlike guard-writes it denies rather than asks, and it fails closed for the same reason: Claude
7
+ * Code blocks a PreToolUse call only on exit 2, so a hook that throws would let every write through.
8
+ * The modules load inside the try for that reason.
9
+ */
10
+
11
+ // A module, so the awaits below are top-level; it has no static import, by design.
12
+ export {};
13
+
14
+ try {
15
+ const { buildManifestDecision, inspectManifestWrite, parseManifestHookInput } =
16
+ await import('../../src/hooks/index.ts');
17
+ const input = parseManifestHookInput({ text: await Bun.stdin.text() });
18
+
19
+ if (input && inspectManifestWrite({ input })) {
20
+ console.log(JSON.stringify(buildManifestDecision()));
21
+ }
22
+ } catch (error) {
23
+ console.error(
24
+ `vulcan: the guard-manifest hook failed (${error instanceof Error ? error.message : String(error)}) - blocked; run bun install`,
25
+ );
26
+ process.exit(2);
27
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.1",
3
+ "version": "0.3.3",
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.1",
48
- "@venizia/vulcan-okf": "0.3.1",
47
+ "@venizia/vulcan-atlas": "0.3.3",
48
+ "@venizia/vulcan-okf": "0.3.3",
49
49
  "zod": "^4.5.4"
50
50
  },
51
51
  "devDependencies": {
@@ -215,21 +215,23 @@ const runCreate = async (opts: {
215
215
  }
216
216
 
217
217
  let located: ILocatedPreset;
218
- let names: Record<string, string>;
219
218
 
220
219
  if (isNpm) {
221
- // The side is known only once the package is read, so its folder is asked after the install.
222
- const early = resolveNames({
223
- fields: appFields({}),
224
- args: opts.args,
225
- interactive,
226
- ask: askWithPrompt,
227
- });
228
-
229
- if (!early.ok) {
230
- return fail({ message: early.error });
220
+ // Without a terminal nothing is asked, so a missing flag is refused before the network is used.
221
+ if (!interactive) {
222
+ const early = resolveNames({
223
+ fields: appFields({}),
224
+ args: opts.args,
225
+ interactive,
226
+ ask: askWithPrompt,
227
+ });
228
+
229
+ if (!early.ok) {
230
+ return fail({ message: early.error });
231
+ }
231
232
  }
232
233
 
234
+ // The side is known only once the package is read, so the preset is fetched before the rest is asked.
233
235
  const installed = await installNpmPreset({ scratch: opts.scratch, spec });
234
236
 
235
237
  if (installed !== ExitCodes.OK) {
@@ -243,19 +245,6 @@ const runCreate = async (opts: {
243
245
  }
244
246
 
245
247
  located = result.located;
246
-
247
- const folder = resolveNames({
248
- fields: [SIDE_FIELDS[located.preset.side]],
249
- args: opts.args,
250
- interactive,
251
- ask: askWithPrompt,
252
- });
253
-
254
- if (!folder.ok) {
255
- return fail({ message: folder.error });
256
- }
257
-
258
- names = { ...early.names, ...folder.names };
259
248
  } else {
260
249
  const result = locatePreset({ spec, root });
261
250
 
@@ -264,22 +253,20 @@ const runCreate = async (opts: {
264
253
  }
265
254
 
266
255
  located = result.located;
256
+ }
267
257
 
268
- const rest = resolveNames({
269
- fields: appFields({ side: located.preset.side }),
270
- args: opts.args,
271
- interactive,
272
- ask: askWithPrompt,
273
- });
274
-
275
- if (!rest.ok) {
276
- return fail({ message: rest.error });
277
- }
258
+ const rest = resolveNames({
259
+ fields: appFields({ side: located.preset.side }),
260
+ args: opts.args,
261
+ interactive,
262
+ ask: askWithPrompt,
263
+ });
278
264
 
279
- names = rest.names;
265
+ if (!rest.ok) {
266
+ return fail({ message: rest.error });
280
267
  }
281
268
 
282
- const { folder, app, shared } = names;
269
+ const { folder, app, shared } = rest.names;
283
270
  const side = located.preset.side;
284
271
  // The flag of the side this preset does not build still counts when given: it names a folder too.
285
272
  const otherFlag =
@@ -7,11 +7,15 @@ export const isInstallSkipped = (): boolean => process.env[CreateConstants.NO_IN
7
7
  /** The `bun` this process runs, unless a test replaced it. */
8
8
  export const bunExecutable = (): string => process.env[CreateConstants.BUN_ENV] ?? process.execPath;
9
9
 
10
- /** Any command, under the same skip rule as `runBun`; a skipped one counts as done. */
10
+ /**
11
+ * Any command, under the same skip rule as `runBun`; a skipped one counts as done. A quiet command
12
+ * prints nothing while it runs: its output is kept and written only when it fails.
13
+ */
11
14
  export const runCommand = async (opts: {
12
15
  cwd: string;
13
16
  command: string[];
14
17
  label: string;
18
+ quiet?: boolean;
15
19
  }): Promise<number> => {
16
20
  if (isInstallSkipped()) {
17
21
  process.stderr.write(` skipped ${opts.label} (VULCAN_NO_INSTALL)\n`);
@@ -19,20 +23,46 @@ export const runCommand = async (opts: {
19
23
  return ExitCodes.OK;
20
24
  }
21
25
 
26
+ if (opts.quiet !== true) {
27
+ const child = Bun.spawn(opts.command, {
28
+ cwd: opts.cwd,
29
+ stdio: ['inherit', 'inherit', 'inherit'],
30
+ });
31
+
32
+ return child.exited;
33
+ }
34
+
22
35
  const child = Bun.spawn(opts.command, {
23
36
  cwd: opts.cwd,
24
- stdio: ['inherit', 'inherit', 'inherit'],
37
+ stdin: 'ignore',
38
+ stdout: 'pipe',
39
+ stderr: 'pipe',
25
40
  });
41
+ const [stdout, stderr, code] = await Promise.all([
42
+ new Response(child.stdout).text(),
43
+ new Response(child.stderr).text(),
44
+ child.exited,
45
+ ]);
46
+
47
+ if (code !== ExitCodes.OK) {
48
+ process.stderr.write(`${stdout}${stderr}`);
49
+ }
26
50
 
27
- return child.exited;
51
+ return code;
28
52
  };
29
53
 
30
54
  export const runBun = async (opts: {
31
55
  cwd: string;
32
56
  args: string[];
33
57
  label: string;
58
+ quiet?: boolean;
34
59
  }): Promise<number> =>
35
- runCommand({ cwd: opts.cwd, command: [bunExecutable(), ...opts.args], label: opts.label });
60
+ runCommand({
61
+ cwd: opts.cwd,
62
+ command: [bunExecutable(), ...opts.args],
63
+ label: opts.label,
64
+ quiet: opts.quiet,
65
+ });
36
66
 
37
67
  /**
38
68
  * `git init` on the new project. A machine without git (or with one too old for `-b`) still gets a
@@ -7,6 +7,8 @@ import { runBun } from './process.ts';
7
7
  /**
8
8
  * An npm preset is read from node_modules, so it is installed into a scratch folder outside the
9
9
  * project: every refusal that depends on what the package says happens before anything is written.
10
+ * One line says what is fetched; bun's own output would land between the questions, so it is kept
11
+ * and shown only when the install fails.
10
12
  */
11
13
  export const installNpmPreset = async (opts: {
12
14
  scratch: string;
@@ -17,10 +19,15 @@ export const installNpmPreset = async (opts: {
17
19
  `${JSON.stringify({ name: 'vulcan-preset-scratch', private: true })}\n`,
18
20
  );
19
21
 
22
+ const preset = `${opts.spec.packageName}@${opts.spec.range}`;
23
+
24
+ process.stderr.write(`Fetching preset ${preset} ...\n`);
25
+
20
26
  return runBun({
21
27
  cwd: opts.scratch,
22
- args: ['add', `${opts.spec.packageName}@${opts.spec.range}`],
23
- label: `bun add ${opts.spec.packageName}@${opts.spec.range}`,
28
+ args: ['add', preset],
29
+ label: `bun add ${preset}`,
30
+ quiet: true,
24
31
  });
25
32
  };
26
33
 
@@ -12,7 +12,12 @@ import {
12
12
  readSlots,
13
13
  RuleConstants,
14
14
  } from '../rules/index.ts';
15
- import { ManifestConstants, projectNameOf } from '../manifest/index.ts';
15
+ import {
16
+ isManifestCurrent,
17
+ ManifestConstants,
18
+ projectNameOf,
19
+ renderManifest,
20
+ } from '../manifest/index.ts';
16
21
  import { planManifest, planPrune, planSync, SyncStatuses } from '../sync/index.ts';
17
22
  import { DoctorChecks, DoctorConstants } from './common/index.ts';
18
23
  import type { IViolation, TDoctorCheck } from './common/index.ts';
@@ -259,19 +264,36 @@ export const checkPrune = (opts: ICheckContext): IViolation[] =>
259
264
  }),
260
265
  );
261
266
 
262
- /** C1: the committed manifest is what the config renders - atlas reads the file, never the config. */
267
+ /**
268
+ * C1: the committed manifest is what the config renders - atlas reads the file, never the config.
269
+ * A file written before the `$generated` note existed is current; a hand-edited one is not.
270
+ */
263
271
  export const checkManifest = (opts: ICheckContext): IViolation[] => {
264
272
  const action = planManifest({ root: opts.root, config: opts.config });
265
273
 
266
- return action.status === SyncStatuses.UNCHANGED
267
- ? []
268
- : [
269
- createViolation({
270
- check: DoctorChecks.MANIFEST,
271
- file: ManifestConstants.FILE,
272
- message: `${action.status === SyncStatuses.CREATED ? 'missing' : 'stale against the config'} - run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`,
273
- }),
274
- ];
274
+ if (
275
+ action.status === SyncStatuses.UNCHANGED ||
276
+ (action.status === SyncStatuses.REPLACED &&
277
+ isManifestCurrent({
278
+ committed: readFileSync(join(opts.root, ManifestConstants.FILE), 'utf8'),
279
+ rendered: renderManifest({ root: opts.root, config: opts.config }),
280
+ }))
281
+ ) {
282
+ return [];
283
+ }
284
+
285
+ const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' and commit it`;
286
+
287
+ return [
288
+ createViolation({
289
+ check: DoctorChecks.MANIFEST,
290
+ file: ManifestConstants.FILE,
291
+ message:
292
+ action.status === SyncStatuses.CREATED
293
+ ? `missing - ${fix}`
294
+ : `stale against the config, or edited by hand - the manifest is generated, never edit it: edit .configs/vulcan.config.* and ${fix}`,
295
+ }),
296
+ ];
275
297
  };
276
298
 
277
299
  const hasStylePackage = (opts: { directory: string }): boolean => {
@@ -19,3 +19,11 @@ export interface IHookCommand {
19
19
  command: string;
20
20
  cwd: string | undefined;
21
21
  }
22
+
23
+ /** What the manifest guard reads of any tool call: the tool, the file it names, or the Bash command. */
24
+ export interface IManifestHookInput {
25
+ tool: string;
26
+ filePath: string | undefined;
27
+ command: string | undefined;
28
+ cwd: string | undefined;
29
+ }
@@ -0,0 +1,92 @@
1
+ import { isAbsolute, join, normalize } from 'node:path';
2
+ import { GuardDecisions, HookConstants } from './common/index.ts';
3
+ import type { IManifestHookInput } from './common/index.ts';
4
+
5
+ export const MANIFEST_BLOCK_MESSAGE =
6
+ 'vulcan.manifest.json is generated - edit .configs/vulcan.config.* and run `vulcan sync`';
7
+
8
+ const MANIFEST_SUFFIX = '/.agents/vulcan.manifest.json';
9
+ const BASH_TOOL = 'Bash';
10
+ /** A path word that ends in the manifest's name. */
11
+ const TARGET = String.raw`[^\s;|&<>"']*vulcan\.manifest\.json`;
12
+
13
+ /** The shell forms that write, replace or delete a file; reading it (cat, jq, git diff) is not among them. */
14
+ const WRITE_PATTERNS: RegExp[] = [
15
+ // `> file`, `>> file`, `2> file`, `&> file`, `>| file`
16
+ new RegExp(String.raw`(?:^|[^<>])\d?>>?\|?\s*["']?${TARGET}`),
17
+ new RegExp(String.raw`\btee\b[^;|&]*${TARGET}`),
18
+ new RegExp(
19
+ String.raw`\b(?:sed|perl|ruby)\b[^;|&]*\s(?:-[A-Za-z]*i\b|--in-place)[^;|&]*${TARGET}`,
20
+ ),
21
+ // the manifest as the destination: the last argument
22
+ new RegExp(String.raw`\b(?:cp|mv|install|ln)\b[^;|&]*\s["']?${TARGET}["']?\s*(?:$|[;|&])`),
23
+ new RegExp(String.raw`\bof=["']?${TARGET}`),
24
+ new RegExp(String.raw`\b(?:rm|truncate|shred|unlink)\b[^;|&]*${TARGET}`),
25
+ ];
26
+
27
+ const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
28
+ typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
29
+
30
+ const toText = (opts: { value: unknown }): string | undefined =>
31
+ typeof opts.value === 'string' && opts.value !== '' ? opts.value : undefined;
32
+
33
+ /** The tool call from the hook's JSON; `undefined` when it is not what Claude Code sends. */
34
+ export const parseManifestHookInput = (opts: { text: string }): IManifestHookInput | undefined => {
35
+ let payload: unknown;
36
+
37
+ try {
38
+ payload = JSON.parse(opts.text);
39
+ } catch (error) {
40
+ console.error(
41
+ `[parseManifestHookInput] unreadable hook input - letting the call through | ${error instanceof Error ? error.message : String(error)}`,
42
+ );
43
+
44
+ return undefined;
45
+ }
46
+
47
+ const holder = { value: payload };
48
+
49
+ if (!isRecord(holder)) {
50
+ return undefined;
51
+ }
52
+
53
+ // The wire names are snake_case; they stay behind string-literal access here, at the boundary (V-C-14).
54
+ const toolInput = { value: holder.value['tool_input'] };
55
+ const input = isRecord(toolInput) ? toolInput.value : {};
56
+ const tool = toText({ value: holder.value['tool_name'] });
57
+
58
+ return tool === undefined
59
+ ? undefined
60
+ : {
61
+ tool,
62
+ filePath:
63
+ toText({ value: input['file_path'] }) ?? toText({ value: input['notebook_path'] }),
64
+ command: toText({ value: input['command'] }),
65
+ cwd: toText({ value: holder.value['cwd'] }),
66
+ };
67
+ };
68
+
69
+ /** Whether this tool call writes `.agents/vulcan.manifest.json` - which only `vulcan sync` may do. */
70
+ export const inspectManifestWrite = (opts: { input: IManifestHookInput }): boolean => {
71
+ const { tool, filePath, command, cwd } = opts.input;
72
+
73
+ if (tool === BASH_TOOL) {
74
+ return command !== undefined && WRITE_PATTERNS.some(pattern => pattern.test(command));
75
+ }
76
+
77
+ if (filePath === undefined) {
78
+ return false;
79
+ }
80
+
81
+ const absolute = isAbsolute(filePath) ? filePath : join(cwd ?? process.cwd(), filePath);
82
+
83
+ return normalize(absolute).endsWith(MANIFEST_SUFFIX);
84
+ };
85
+
86
+ export const buildManifestDecision = () => ({
87
+ hookSpecificOutput: {
88
+ hookEventName: HookConstants.PRE_TOOL_USE,
89
+ permissionDecision: GuardDecisions.DENY,
90
+ permissionDecisionReason: MANIFEST_BLOCK_MESSAGE,
91
+ },
92
+ });
@@ -1,4 +1,5 @@
1
1
  export * from './common/index.ts';
2
+ export * from './guard-manifest.ts';
2
3
  export * from './guard-writes.ts';
3
4
  export * from './session-digest.ts';
4
5
  export * from './remote-hosts.ts';
@@ -10,6 +10,9 @@ export class ManifestConstants {
10
10
  static readonly SCHEMA_VERSION = 1;
11
11
  static readonly PROJECT_RULES = '.agents/rules.md';
12
12
  static readonly ENV = 'VULCAN_MANIFEST';
13
+ /** The first key: a reader sees at once that the file is generated. Readers ignore it; absent in older files. */
14
+ static readonly GENERATED_KEY = '$generated';
15
+ static readonly GENERATED_NOTE = 'by vulcan sync from .configs/vulcan.config.* - do not edit';
13
16
  }
14
17
 
15
18
  const HASH_LENGTH = 8;
@@ -51,6 +54,7 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
51
54
  const { wiki, changelogs, syncAreas } = config.knowledge;
52
55
 
53
56
  const manifest = {
57
+ [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
54
58
  schemaVersion: ManifestConstants.SCHEMA_VERSION,
55
59
  name: projectNameOf(opts),
56
60
  packages: resolvePackages({ config }).map(entry => ({
@@ -79,3 +83,27 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
79
83
 
80
84
  return `${JSON.stringify(manifest, null, 2)}\n`;
81
85
  };
86
+
87
+ /**
88
+ * Whether a committed manifest holds what the config renders, apart from the `$generated` note: a
89
+ * file written before the note existed is current, a hand-edited one is not.
90
+ */
91
+ export const isManifestCurrent = (opts: { committed: string; rendered: string }): boolean => {
92
+ try {
93
+ const strip = (text: string): string => {
94
+ const record: Record<string, unknown> = JSON.parse(text);
95
+
96
+ delete record[ManifestConstants.GENERATED_KEY];
97
+
98
+ return JSON.stringify(record);
99
+ };
100
+
101
+ return strip(opts.committed) === strip(opts.rendered);
102
+ } catch (error) {
103
+ console.error(
104
+ `[isManifestCurrent] unreadable manifest | ${error instanceof Error ? error.message : String(error)}`,
105
+ );
106
+
107
+ return false;
108
+ }
109
+ };