@venizia/vulcan 0.4.10-2 → 0.4.10-21
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 +30 -23
- package/base/checks/wiki-source-links.ts +17 -1
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +5 -76
- package/base/extensions/vulcan-guards.ts +81 -18
- package/base/hooks/guard-git.ts +95 -19
- package/base/hooks/guard-outside.ts +163 -43
- package/base/hooks/guard-writes.ts +15 -36
- package/base/hooks/session-start.ts +1 -1
- package/base/make/vulcan.mk +8 -5
- package/base/packs/venizia.md +16 -0
- package/base/references/delegation-brief.md +3 -5
- package/base/references/testing.md +1 -9
- package/base/rules.md +33 -38
- package/base/skills/build-a-feature/SKILL.md +4 -4
- package/base/skills/docs-update/SKILL.md +19 -8
- package/base/skills/fix-a-bug/SKILL.md +4 -2
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/research/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +2 -2
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +3 -3
- package/base/skills/visualize-work/references/spec.md +6 -3
- package/base/templates/AGENTS.md +9 -7
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/hooks-json.ts +22 -3
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +15 -2
- package/src/agents/resolve.ts +1 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/board/command.ts +92 -30
- package/src/board/common/constants.ts +26 -0
- package/src/board/common/types.ts +10 -3
- package/src/board/fold.ts +1 -1
- package/src/board/github.ts +1 -2
- package/src/board/gitlab.ts +436 -0
- package/src/board/index.ts +1 -0
- package/src/board/logo.ts +49 -0
- package/src/board/open-file.ts +110 -0
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +87 -3
- package/src/board/settings.ts +21 -24
- package/src/commands/changelog.command.ts +40 -0
- package/src/commands/clean.command.ts +6 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +6 -1
- package/src/commands/migrate.command.ts +71 -0
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/runners.command.ts +43 -0
- package/src/commands/sync.command.ts +8 -4
- package/src/commands/table.ts +362 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +4 -0
- package/src/commit/hook.ts +112 -8
- package/src/common/constants.ts +11 -9
- package/src/common/env-variables.ts +41 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +3 -4
- package/src/common/record.ts +5 -0
- package/src/config/common/constants.ts +28 -22
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +330 -146
- package/src/create/add-app.ts +7 -2
- package/src/create/add-lib.ts +2 -4
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +277 -448
- package/src/doctor/common/constants.ts +27 -19
- package/src/doctor/private-values.ts +4 -1
- package/src/doctor/runner.ts +5 -12
- package/src/doctor/schema.ts +4 -0
- package/src/events/common/actor-names.ts +12 -0
- package/src/events/common/constants.ts +65 -38
- package/src/events/common/index.ts +1 -0
- package/src/events/hook.ts +5 -56
- package/src/events/text.ts +41 -6
- package/src/hooks/command-view.ts +80 -19
- package/src/hooks/common/constants.ts +26 -17
- package/src/hooks/common/types.ts +13 -24
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +334 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +87 -184
- package/src/hooks/hook-input.ts +57 -0
- package/src/hooks/index.ts +3 -6
- package/src/hooks/link-makers.ts +315 -0
- package/src/hooks/package-runners.ts +268 -0
- package/src/hooks/project-guards.ts +81 -44
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/runner-scan.ts +257 -0
- package/src/hooks/script-runners.ts +400 -0
- package/src/hooks/session-digest.ts +27 -117
- package/src/hooks/shell-folders.ts +760 -0
- package/src/hooks/shell-writes.ts +646 -0
- package/src/hooks/shell.ts +1421 -194
- package/src/hooks/subagent-card.ts +2 -2
- package/src/hooks/write-commands.ts +898 -0
- package/src/init/scaffold.ts +2 -3
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +37 -6
- package/src/local/constants.ts +15 -1
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +41 -10
- package/src/manifest/render.ts +84 -30
- package/src/owner/constants.ts +4 -5
- package/src/owner/index.ts +0 -2
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +51 -27
- package/src/owner/survey.ts +0 -3
- package/src/owner/view.ts +0 -9
- package/src/router.ts +8 -132
- package/src/rules/base.ts +12 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/runners/check.ts +130 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/agents-block.ts +104 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/common/constants.ts +0 -2
- package/src/sync/index.ts +1 -1
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +2 -15
- package/src/sync/settings.ts +0 -17
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +41 -30
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +27 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/kinds-schema.ts +49 -0
- package/src/visualize/labels-vi.ts +25 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +415 -66
- package/src/visualize/page.ts +82 -15
- package/src/visualize/render.ts +2 -1
- package/src/visualize/schema.ts +29 -1
- package/src/visualize/sections.ts +78 -9
- package/src/visualize/theme.ts +49 -18
- package/src/wiki/anchors.ts +1 -0
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
- package/base/ci-global.json +0 -13
- package/base/claude/remote-hosts.json +0 -15
- package/base/hooks/guard-manifest.ts +0 -27
- package/base/hooks/guard-package.ts +0 -30
- package/base/hooks/guard-remote-hosts.ts +0 -70
- package/base/hooks/guard-scripting.ts +0 -32
- package/base/hooks/post-tool.ts +0 -37
- package/base/hooks/prompt-submit.ts +0 -54
- package/base/hooks/stop.ts +0 -40
- package/base/skills/build-a-feature/evals/evals.json +0 -29
- package/base/skills/docs-update/evals/evals.json +0 -23
- package/base/skills/docs-writing/evals/evals.json +0 -17
- package/base/skills/fix-a-bug/evals/evals.json +0 -17
- package/base/skills/knowledge-sync/SKILL.md +0 -81
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
- package/base/skills/knowledge-sync/references/workflow.md +0 -44
- package/base/skills/plan-a-change/evals/evals.json +0 -47
- package/base/skills/report-back/evals/evals.json +0 -23
- package/base/skills/research/evals/evals.json +0 -17
- package/base/skills/retro/evals/evals.json +0 -17
- package/base/skills/review-a-change/evals/evals.json +0 -17
- package/base/skills/ship/evals/evals.json +0 -23
- package/base/skills/visualize-work/evals/evals.json +0 -17
- package/base/templates/ci/github-actions.yml +0 -75
- package/base/templates/ci/gitlab-ci.yml +0 -52
- package/base/templates/trusted-hosts.local.example +0 -11
- package/src/ci/affected.ts +0 -176
- package/src/ci/command.ts +0 -166
- package/src/ci/common/constants.ts +0 -76
- package/src/ci/common/index.ts +0 -2
- package/src/ci/common/types.ts +0 -37
- package/src/ci/git.ts +0 -72
- package/src/ci/global.ts +0 -48
- package/src/ci/graph.ts +0 -43
- package/src/ci/index.ts +0 -7
- package/src/ci/workspace.ts +0 -119
- package/src/commands/ci.command.ts +0 -4
- package/src/hooks/guard-manifest.ts +0 -109
- package/src/hooks/guard-package.ts +0 -226
- package/src/hooks/guard-scripting.ts +0 -36
- package/src/hooks/host-pattern.ts +0 -17
- package/src/hooks/owner-reply.ts +0 -162
- package/src/hooks/post-tool.ts +0 -138
- package/src/hooks/remote-hosts.ts +0 -1013
- package/src/hooks/trusted-scripts.ts +0 -212
- package/src/owner/shape.ts +0 -496
- package/src/owner/violations.ts +0 -332
- package/src/signals/claims.ts +0 -73
- package/src/signals/classify.ts +0 -137
- package/src/signals/constants.ts +0 -88
- package/src/signals/index.ts +0 -5
- package/src/signals/loop.ts +0 -48
- package/src/signals/state.ts +0 -271
- package/src/sync/atlas-block.ts +0 -56
package/README.md
CHANGED
|
@@ -4,11 +4,13 @@ One setup, one workflow and one coding style for every VENIZIA project. Bun-only
|
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
bun add -d --exact @venizia/vulcan @venizia/dev-configs
|
|
7
|
-
bun
|
|
8
|
-
bun
|
|
9
|
-
bun
|
|
7
|
+
bun node_modules/.bin/vulcan init
|
|
8
|
+
bun node_modules/.bin/vulcan sync
|
|
9
|
+
bun node_modules/.bin/vulcan doctor
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
+
`doctor` fails with `[scaffold]` until you describe the project in `.agents/knowledge/index.md` and delete the `vulcan:scaffold` line; it is the first item `init` lists under `left to do`.
|
|
13
|
+
|
|
12
14
|
`--no-install` matters: the unscoped npm name `vulcan` belongs to an unrelated package, and without the
|
|
13
15
|
flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
|
|
14
16
|
|
|
@@ -16,16 +18,28 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
|
|
|
16
18
|
|
|
17
19
|
| Command | What it does |
|
|
18
20
|
|---|---|
|
|
19
|
-
| `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the
|
|
20
|
-
| `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>]` | Create a new monorepo with its first app from a framework preset: the root manifests, the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
|
|
21
|
-
| `add --preset <name\|file:path> --app <name> [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app
|
|
22
|
-
| `sync [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing file is left alone), `.claude/settings.json` (shipped + slot + project hooks
|
|
23
|
-
| `
|
|
21
|
+
| `init [--key <KEY>]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the two lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, `.dockerignore`, `bunfig.toml`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. `--key` is the project's flow key (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name); it counts only while no config exists yet. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
|
|
22
|
+
| `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>] [--scope <@scope>] [--key <KEY>]` | Create a new monorepo with its first app from a framework preset: the root manifests (with `.dockerignore` and `bunfig.toml`), the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. `--scope` names the app's package `@scope/<name>`; `--key` is the flow key, as for `init`. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
|
|
23
|
+
| `add --preset <name\|file:path> (--app <name> \| --lib <name> \| --shared <name>) [--dir <folder>] [--scope <@scope>] [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app, a library other apps import (`--lib`) or a side-neutral shared package (`--shared`) to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. `--dir` is for a library or a shared package; `--scope` names the package `@scope/<name>`. A frontend says which backend app to proxy `/api` to |
|
|
24
|
+
| `sync [--agents <list>\|list] [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing file is left alone), `.claude/settings.json` (shipped + slot + `claude.settings`, project hooks included, 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`. It also writes the adapters of the other agents you chose (`--agents claude,omp` or `none`, kept in `.agents/vulcan.local.json`; `--agents list` prints the table), the Atlas block in `AGENTS.md`, and the clone's `commit-msg` hook when a commit check is on. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
|
|
25
|
+
| `preset diff <package> [--preset <name\|file:path>] [--api <app> \| --no-api] [--full] [--check]` | Read-only: set each file the preset makes now against the file the package has (same, differs, missing); `--preset` names the preset when it cannot be found from the package, `--api` or `--no-api` says what a frontend proxies to, `--full` prints the diffs, `--check` exits 1 on a difference |
|
|
26
|
+
| `agents [list\|add\|remove\|setup]` | See, add, remove or re-choose the coding agents you use on this machine |
|
|
27
|
+
| `doctor` | Check the project follows VULCAN; exit 1 on any violation. The checks are listed in `docs/wiki/content/references/commands/doctor.md` |
|
|
28
|
+
| `commit-check <message-file> \| --range <revs> \| --text <message>` | Check a commit message against the `commit.message` checks of the config; `sync` installs it as the `commit-msg` hook; exit 1 on a problem, 2 on bad input |
|
|
29
|
+
| `board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]` | Fold the event log (and GitHub pull requests, checks and reviews when `gh` can read them) into flows and write one HTML file, by default `.agents/local/reports/board.html`; read-only. `--repo` is repeatable; `--no-github` leaves GitHub out |
|
|
30
|
+
| `board serve [--port <n>] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]` | Serve the same page on 127.0.0.1 (default port 4317) and push new events to the open page with no reload, until Ctrl+C |
|
|
31
|
+
| `event add \| tail` | Write a line to the agent event log (`.agents/local/events/<day>.jsonl`) or read it |
|
|
32
|
+
| `visualize <spec.json> [--out <name>] \| --schema` | Make one small static HTML page from a JSON spec, in `.agents/local/prototypes/` (`--out` names the page); `--schema` prints the spec's schema |
|
|
33
|
+
| `profile [show\|edit\|reset]` | Tell VULCAN how you like to work (reply language, tone, habits) in `.agents/local/profile.json` |
|
|
34
|
+
| `clean [--tmp\|--worktrees\|--clones\|--cache\|--all] [--include-fresh] [--yes]` | List what an agent left under `.agents/local/` (a dry run) and, with `--yes`, remove it |
|
|
24
35
|
| `upgrade [--stable \| --nightly] [<version\|tag>]` | Install the target `@venizia/vulcan`, then run `sync` from the newly installed CLI. `--stable` (default) is the `latest` dist-tag, never a prerelease; `--nightly` is the higher of `latest` and `next`; a named version or tag wins over both. `--nightly` that cannot read the dist-tags exits 1; a stable upgrade from an installed prerelease says that `--nightly` keeps the prerelease line |
|
|
36
|
+
| `changelog check` | Check the changelog entries' `migration` blocks: a Breaking Change entry dated on or after `knowledge.migrationFrom` must carry one, and every block must be valid |
|
|
37
|
+
| `migrate plan --to <version>` | What an app must change to move a package between two releases, newer or older: the steps in order, where its code touches them, codemods and data warnings; read only |
|
|
38
|
+
| `migrate apply --to <version>` | Run the codemods the plan links (`--reverse` for a rollback) and print the steps that stay manual; refuses an app with uncommitted changes unless `--force` |
|
|
25
39
|
| `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas`. `x --help` prints the help; `x <tool> --help` goes to the tool |
|
|
26
|
-
| `help`, `version` | |
|
|
40
|
+
| `help`, `version` | `help` prints the usage; `version` prints the installed version |
|
|
27
41
|
|
|
28
|
-
Diagnostics go to stderr;
|
|
42
|
+
Diagnostics go to stderr; a command that produces a result prints only that on stdout, and `vulcan x atlas mcp` is a
|
|
29
43
|
clean MCP stdio server.
|
|
30
44
|
|
|
31
45
|
## The project config
|
|
@@ -39,36 +53,29 @@ export default {
|
|
|
39
53
|
agents: ['claude'],
|
|
40
54
|
rules: { 'V-W-01': 'on-user-word' }, // slot choice: 'on-user-word' | 'read-only'
|
|
41
55
|
knowledge: { bundle: '.agents/knowledge' },
|
|
42
|
-
hooks: [{ event: 'Stop', command: 'echo done' }],
|
|
43
56
|
claude: { settings: { permissions: { allow: ['Bash(make test)'] } } }, // team-shared, committed
|
|
44
57
|
digest: { oftenDropped: ['V-B-03', 'W-00'] }, // repeated at every session start; base or own IDs
|
|
45
58
|
layout: { backend: 'services', frontend: 'web', shared: 'libs' }, // written by init --preset and add
|
|
46
59
|
} satisfies VulcanConfig;
|
|
47
60
|
```
|
|
48
61
|
|
|
49
|
-
An unknown key is an error; every error names the file and the field.
|
|
62
|
+
An unknown key is an error; every error names the file and the field. The example shows a few keys; each key, with its type and default, is in `docs/wiki/content/references/configuration/index.md`. Three that a new project often wants: `local.tmp` (a short folder for the temporary files of a session, so a browser socket path fits), `theme` (the colours, fonts and radius of the board and the pages VULCAN makes) and `board` (the owner, title, logo and agents of `vulcan board`).
|
|
50
63
|
|
|
51
64
|
## What ships (`base/`)
|
|
52
65
|
|
|
53
|
-
- `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C
|
|
66
|
+
- `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-* (36 rules).
|
|
54
67
|
- `slots.json` - rules a project picks a wording for (V-W-01 today).
|
|
55
|
-
- `skills/` -
|
|
56
|
-
- `hooks/` -
|
|
68
|
+
- `skills/` - 11 project-neutral skills, described in `docs/wiki/content/references/skills.md` (a project-specific skill stays in its project).
|
|
69
|
+
- `hooks/` - 16 hook files, described in `docs/wiki/content/references/hooks/index.md`.
|
|
57
70
|
- `claude/settings.json`, `make/vulcan.mk`, `templates/`.
|
|
71
|
+
- `agents.json` (the coding agents `sync` can write adapters for), `commit-agents.json` (the agent names, addresses and phrases `commit-check` looks for in a message), `checks/` (the wiki link and anchor gates), `extensions/` (the guards for an agent that loads an extension, such as omp or pi) and `references/` (testing, design pass, evidence and the other pages the skills link to).
|
|
58
72
|
|
|
59
73
|
A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
|
|
60
74
|
or shadows a shipped one.
|
|
61
75
|
|
|
62
76
|
## `doctor` checks
|
|
63
77
|
|
|
64
|
-
`
|
|
65
|
-
`V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
|
|
66
|
-
shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
|
|
67
|
-
not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
|
|
68
|
-
`manifest` (`.agents/vulcan.manifest.json` exists and matches the config) · `tags` (every release tag `atlas.tagPattern` reads names a declared package, an alias or an ignored tag) ·
|
|
69
|
-
`apps` (every `layout` folder is a workspace and every package lives in one; skipped without `layout`) ·
|
|
70
|
-
`style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it; the packages are `packages/*` and every configured package `path`) ·
|
|
71
|
-
`scaffold` (the config is filled in: a project whose `package.json` declares `workspaces` lists its `packages`, and `.agents/knowledge/index.md` no longer holds the `vulcan:scaffold` line `init` writes).
|
|
78
|
+
`doctor` runs its checks in order; each is described in `docs/wiki/content/references/commands/doctor.md`.
|
|
72
79
|
|
|
73
80
|
The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
|
|
74
81
|
|
|
@@ -2,7 +2,23 @@
|
|
|
2
2
|
* Gate: every source path the wiki and the knowledge bundle name is tracked by git. Run from the
|
|
3
3
|
* repository root, through `make wiki-links-check WIKI_REPO=<owner/name>` or directly:
|
|
4
4
|
* bun node_modules/@venizia/vulcan/base/checks/wiki-source-links.ts --repo <owner/name>
|
|
5
|
+
* The folders it checks come from the `layout` of `.configs/vulcan.config.mts`; with no layout, the default list.
|
|
5
6
|
*/
|
|
7
|
+
import { ConfigLoader } from '../../src/config/index.ts';
|
|
6
8
|
import { runSourceLinksCommand } from '../../src/wiki/index.ts';
|
|
7
9
|
|
|
8
|
-
|
|
10
|
+
const root = process.cwd();
|
|
11
|
+
const loaded = await ConfigLoader.load({ root });
|
|
12
|
+
const note = ConfigLoader.unreadableNote({ loaded });
|
|
13
|
+
|
|
14
|
+
if (note !== undefined) {
|
|
15
|
+
console.error(`wiki-source-links: ${note}`);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
process.exit(
|
|
19
|
+
runSourceLinksCommand({
|
|
20
|
+
args: process.argv.slice(2),
|
|
21
|
+
root,
|
|
22
|
+
layout: loaded.ok ? loaded.config.layout : undefined,
|
|
23
|
+
}),
|
|
24
|
+
);
|
package/base/claude/events.json
CHANGED
|
@@ -11,17 +11,6 @@
|
|
|
11
11
|
]
|
|
12
12
|
}
|
|
13
13
|
],
|
|
14
|
-
"Stop": [
|
|
15
|
-
{
|
|
16
|
-
"hooks": [
|
|
17
|
-
{
|
|
18
|
-
"type": "command",
|
|
19
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
|
|
20
|
-
"timeout": 5
|
|
21
|
-
}
|
|
22
|
-
]
|
|
23
|
-
}
|
|
24
|
-
],
|
|
25
14
|
"SubagentStop": [
|
|
26
15
|
{
|
|
27
16
|
"hooks": [
|
|
@@ -46,6 +35,7 @@
|
|
|
46
35
|
],
|
|
47
36
|
"PostToolUse": [
|
|
48
37
|
{
|
|
38
|
+
"matcher": "SendMessage",
|
|
49
39
|
"hooks": [
|
|
50
40
|
{
|
|
51
41
|
"type": "command",
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"hooks": [
|
|
9
9
|
{
|
|
10
10
|
"type": "command",
|
|
11
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/session-start.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 session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-start 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"
|
|
11
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the session-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-start 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"
|
|
12
12
|
}
|
|
13
13
|
]
|
|
14
14
|
}
|
|
@@ -19,34 +19,7 @@
|
|
|
19
19
|
"hooks": [
|
|
20
20
|
{
|
|
21
21
|
"type": "command",
|
|
22
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -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"
|
|
23
|
-
}
|
|
24
|
-
]
|
|
25
|
-
},
|
|
26
|
-
{
|
|
27
|
-
"matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
|
|
28
|
-
"hooks": [
|
|
29
|
-
{
|
|
30
|
-
"type": "command",
|
|
31
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-manifest.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -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"
|
|
32
|
-
}
|
|
33
|
-
]
|
|
34
|
-
},
|
|
35
|
-
{
|
|
36
|
-
"matcher": "Write",
|
|
37
|
-
"hooks": [
|
|
38
|
-
{
|
|
39
|
-
"type": "command",
|
|
40
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-package.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; ok && exit 0; [ -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"
|
|
41
|
-
}
|
|
42
|
-
]
|
|
43
|
-
},
|
|
44
|
-
{
|
|
45
|
-
"matcher": "Bash",
|
|
46
|
-
"hooks": [
|
|
47
|
-
{
|
|
48
|
-
"type": "command",
|
|
49
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then in=$(cat); t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_])(git|gh)([^[:alnum:]_]|$)'; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; exit 0; fi; echo \"vulcan: the guard-git hook failed - the call passes\" >&2; exit 0; fi; echo \"vulcan: the guard-git hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes\" >&2; exit 0"
|
|
22
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then printf '%s' \"$in\" | bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; ok && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the guard-writes hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; ok && exit 0; [ -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"
|
|
50
23
|
}
|
|
51
24
|
]
|
|
52
25
|
},
|
|
@@ -55,7 +28,7 @@
|
|
|
55
28
|
"hooks": [
|
|
56
29
|
{
|
|
57
30
|
"type": "command",
|
|
58
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-
|
|
31
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-git.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"tool_name\" *: *\"Bash\"' && printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules/[.]bin/vulcan sync( --?[a-z][a-z-]*( [[:alnum:]_./@-]+)?)*)\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun --no-env-file --config=/dev/null \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_]|\\\\[ntr]|\\\\u00[0-9a-fA-F]{2})(git|gh)([^[:alnum:]_]|$)'; then m=\"${CLAUDE_PROJECT_DIR:-$PWD}/.agents/vulcan.manifest.json\"; [ \"$VULCAN_GUARD_ASKS\" = deny ] || { [ -f \"$m\" ] && ! M=\"$m\" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require(\"node:fs\").readFileSync(process.env.M, \"utf8\")); if (typeof v !== \"object\" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; } || grep -Eq '\"asks\" *: *\"deny\"' \"$m\" 2>/dev/null; if [ $? -eq 0 ]; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: run bun install to repair the install.\"}}'; else printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-git hook crashed or timed out, so this command was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; fi; exit 0; fi; echo \"vulcan: the guard-git hook failed - the call passes\" >&2; exit 0; fi; if printf '%s' \"$in\" | grep -Eq '(^|[^[:alnum:]_]|\\\\[ntr]|\\\\u00[0-9a-fA-F]{2})(git|gh)([^[:alnum:]_]|$)'; then ok && exit 0; echo \"vulcan: VULCAN guards unavailable: the guard-git hook cannot run (node_modules/@venizia/vulcan or bun is missing, or the hook is not in the installed package): finish bun install, or run bun node_modules/.bin/vulcan sync - the commands that pass until then\" >&2; exit 2; fi; echo \"vulcan: the guard-git hook cannot run, and this call names no git or gh - the call passes\" >&2; exit 0"
|
|
59
32
|
}
|
|
60
33
|
]
|
|
61
34
|
},
|
|
@@ -64,7 +37,7 @@
|
|
|
64
37
|
"hooks": [
|
|
65
38
|
{
|
|
66
39
|
"type": "command",
|
|
67
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then
|
|
40
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-outside.ts\"; in=$(cat); ok() { printf '%s' \"$in\" | grep -Eq '\"tool_name\" *: *\"Bash\"' && printf '%s' \"$in\" | grep -Eq '\"command\" *: *\"(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules/[.]bin/vulcan sync( --?[a-z][a-z-]*( [[:alnum:]_./@-]+)?)*)\"'; }; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then t=; command -v timeout >/dev/null 2>&1 && t=\"timeout 30\"; out=$(printf '%s' \"$in\" | $t bun --no-env-file --config=/dev/null \"$f\"); s=$?; [ \"$s\" -eq 0 ] && { printf '%s' \"$out\"; exit 0; }; m=\"${CLAUDE_PROJECT_DIR:-$PWD}/.agents/vulcan.manifest.json\"; [ \"$VULCAN_GUARD_ASKS\" = deny ] || { [ -f \"$m\" ] && ! M=\"$m\" bun --no-env-file --config=/dev/null -e 'const v = JSON.parse(require(\"node:fs\").readFileSync(process.env.M, \"utf8\")); if (typeof v !== \"object\" || v === null || Array.isArray(v)) process.exit(1)' >/dev/null 2>&1; } || grep -Eq '\"asks\" *: *\"deny\"' \"$m\" 2>/dev/null; if [ $? -eq 0 ]; then printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked, and every call that would need a human to confirm it is denied here (VULCAN_GUARD_ASKS=deny, guard.asks: deny, or a manifest that cannot be read). Nothing was run: run bun install to repair the install.\"}}'; else printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"The guard-outside hook crashed or timed out, so this call was not checked. Confirm only if the owner asked for exactly this; VULCAN_GUARDS=off switches the guards off for a session.\"}}'; fi; exit 0; fi; ok && exit 0; echo \"vulcan: VULCAN guards unavailable: the guard-outside hook cannot run (node_modules/@venizia/vulcan or bun is missing, or the hook is not in the installed package): finish bun install, or run bun node_modules/.bin/vulcan sync - the commands that pass until then\" >&2; exit 2"
|
|
68
41
|
}
|
|
69
42
|
]
|
|
70
43
|
}
|
|
@@ -74,51 +47,7 @@
|
|
|
74
47
|
"hooks": [
|
|
75
48
|
{
|
|
76
49
|
"type": "command",
|
|
77
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/subagent-start.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 subagent-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the subagent-start 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"
|
|
78
|
-
}
|
|
79
|
-
]
|
|
80
|
-
}
|
|
81
|
-
],
|
|
82
|
-
"UserPromptSubmit": [
|
|
83
|
-
{
|
|
84
|
-
"hooks": [
|
|
85
|
-
{
|
|
86
|
-
"type": "command",
|
|
87
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/prompt-submit.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the prompt-submit hook failed - the prompt goes through\" >&2; exit 0; fi; echo \"vulcan: the prompt-submit hook cannot run: node_modules/@venizia/vulcan or bun is missing - the prompt goes through\" >&2; exit 0",
|
|
88
|
-
"timeout": 15
|
|
89
|
-
}
|
|
90
|
-
]
|
|
91
|
-
}
|
|
92
|
-
],
|
|
93
|
-
"Stop": [
|
|
94
|
-
{
|
|
95
|
-
"hooks": [
|
|
96
|
-
{
|
|
97
|
-
"type": "command",
|
|
98
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/stop.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the stop hook failed - the reply passes\" >&2; exit 0; fi; echo \"vulcan: the stop hook cannot run: node_modules/@venizia/vulcan or bun is missing - the reply passes\" >&2; exit 0",
|
|
99
|
-
"timeout": 15
|
|
100
|
-
}
|
|
101
|
-
]
|
|
102
|
-
}
|
|
103
|
-
],
|
|
104
|
-
"PostToolUse": [
|
|
105
|
-
{
|
|
106
|
-
"hooks": [
|
|
107
|
-
{
|
|
108
|
-
"type": "command",
|
|
109
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/post-tool.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the post-tool hook failed - the call is unaffected\" >&2; exit 0; fi; echo \"vulcan: the post-tool hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call is unaffected\" >&2; exit 0",
|
|
110
|
-
"timeout": 15
|
|
111
|
-
}
|
|
112
|
-
]
|
|
113
|
-
}
|
|
114
|
-
],
|
|
115
|
-
"PostToolUseFailure": [
|
|
116
|
-
{
|
|
117
|
-
"hooks": [
|
|
118
|
-
{
|
|
119
|
-
"type": "command",
|
|
120
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/post-tool.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the post-tool hook failed - the call is unaffected\" >&2; exit 0; fi; echo \"vulcan: the post-tool hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call is unaffected\" >&2; exit 0",
|
|
121
|
-
"timeout": 15
|
|
50
|
+
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/subagent-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun --no-env-file --config=/dev/null \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if [ ! -f \"$f\" ] && [ -f \"${f%/*/*/*}/package.json\" ]; then echo \"vulcan: the subagent-start hook is not in this node_modules/@venizia/vulcan - the call passes; run bun node_modules/.bin/vulcan sync to drop its entry\" >&2; exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the subagent-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the subagent-start 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"
|
|
122
51
|
}
|
|
123
52
|
]
|
|
124
53
|
}
|
|
@@ -4,12 +4,14 @@
|
|
|
4
4
|
// tool call it runs the same guard scripts Claude Code runs (node_modules/@venizia/vulcan/base/hooks/*.ts),
|
|
5
5
|
// with a Claude-shaped event on stdin, and turns the answer into this agent's: `deny` blocks, `ask` asks
|
|
6
6
|
// the owner (and blocks when there is no UI to ask). A guard that cannot give an answer follows the same
|
|
7
|
-
// policy as the Claude wrappers: the safety guards block, the others ask, and a missing install
|
|
8
|
-
//
|
|
7
|
+
// policy as the Claude wrappers: the safety guards block, the others ask, and a missing install blocks
|
|
8
|
+
// too - bar a bare `bun install` or `vulcan sync`, the way to repair it (guard-git only for a git or gh line).
|
|
9
|
+
// A guard that is gone from an installed package blocks, except guard-writes, which passes: there is nothing
|
|
10
|
+
// to run. A project that sets `guard.asks: 'deny'` has every ask answered as a block.
|
|
9
11
|
// Only node: modules are imported, so any host that loads TypeScript can load it.
|
|
10
12
|
|
|
11
13
|
import { spawnSync } from 'node:child_process';
|
|
12
|
-
import { existsSync } from 'node:fs';
|
|
14
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
13
15
|
import { dirname, join } from 'node:path';
|
|
14
16
|
|
|
15
17
|
class Tools {
|
|
@@ -59,6 +61,10 @@ interface IGuard {
|
|
|
59
61
|
name: string;
|
|
60
62
|
tools: string[];
|
|
61
63
|
onFailure: string;
|
|
64
|
+
/** Whether the call is blocked when the package is installed and only this guard is gone from it. */
|
|
65
|
+
isClosedWhenGone: boolean;
|
|
66
|
+
/** The lines the guard covers when it is missing: a line that does not match passes. Every line when absent. */
|
|
67
|
+
onlyLines?: RegExp;
|
|
62
68
|
}
|
|
63
69
|
|
|
64
70
|
interface IAnswer {
|
|
@@ -66,23 +72,34 @@ interface IAnswer {
|
|
|
66
72
|
reason: string;
|
|
67
73
|
}
|
|
68
74
|
|
|
69
|
-
const
|
|
75
|
+
const PACKAGE_DIRECTORY = join('node_modules', '@venizia', 'vulcan');
|
|
76
|
+
const HOOKS_DIRECTORY = join(PACKAGE_DIRECTORY, 'base', 'hooks');
|
|
70
77
|
const TIMEOUT_MS = 30_000;
|
|
71
|
-
/** The
|
|
72
|
-
const
|
|
73
|
-
/^\s*bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))
|
|
78
|
+
/** The commands that pass while the install is missing or out of step: they are how it is repaired (`bun install`, `vulcan sync`). */
|
|
79
|
+
const REPAIR =
|
|
80
|
+
/^\s*(bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*|bun node_modules\/\.bin\/vulcan sync( --?[a-z][a-z-]*( [\w./@-]+)?)*)\s*$/;
|
|
81
|
+
/** A command line that names git or gh as a word. */
|
|
82
|
+
const GIT_LINE = /(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/;
|
|
83
|
+
const MANIFEST_FILE = join('.agents', 'vulcan.manifest.json');
|
|
84
|
+
const HELD_ASK =
|
|
85
|
+
'Every call that would need a human to confirm it is denied here (guard.asks: deny, VULCAN_GUARD_ASKS=deny, or a manifest that cannot be read). Nothing was run: hand this to the owner.';
|
|
74
86
|
|
|
75
87
|
/** The guards of `.claude/settings.json`, with the tools each covers and what each does when it cannot answer. */
|
|
76
88
|
const GUARDS: IGuard[] = [
|
|
77
|
-
{ name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK },
|
|
89
|
+
{ name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK, isClosedWhenGone: false },
|
|
78
90
|
{
|
|
79
|
-
name: 'guard-
|
|
91
|
+
name: 'guard-git',
|
|
92
|
+
tools: [Tools.BASH],
|
|
93
|
+
onFailure: Failures.ASK,
|
|
94
|
+
isClosedWhenGone: true,
|
|
95
|
+
onlyLines: GIT_LINE,
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
name: 'guard-outside',
|
|
80
99
|
tools: [Tools.BASH, Tools.WRITE, Tools.EDIT],
|
|
81
|
-
onFailure: Failures.
|
|
100
|
+
onFailure: Failures.ASK,
|
|
101
|
+
isClosedWhenGone: true,
|
|
82
102
|
},
|
|
83
|
-
{ name: 'guard-package', tools: [Tools.WRITE], onFailure: Failures.BLOCK },
|
|
84
|
-
{ name: 'guard-git', tools: [Tools.BASH], onFailure: Failures.ASK },
|
|
85
|
-
{ name: 'guard-outside', tools: [Tools.BASH, Tools.WRITE, Tools.EDIT], onFailure: Failures.ASK },
|
|
86
103
|
];
|
|
87
104
|
|
|
88
105
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
@@ -107,6 +124,31 @@ const rootOf = (opts: { cwd: string }): string => {
|
|
|
107
124
|
}
|
|
108
125
|
};
|
|
109
126
|
|
|
127
|
+
/**
|
|
128
|
+
* Whether every ask is a deny in the project at `root`: the launch environment says `VULCAN_GUARD_ASKS=deny`, the manifest sets
|
|
129
|
+
* `guard.asks` to `deny`, or the manifest exists and cannot be read. No manifest means asks stay asks.
|
|
130
|
+
*/
|
|
131
|
+
const isHeldIn = (opts: { root: string }): boolean => {
|
|
132
|
+
if (process.env.VULCAN_GUARD_ASKS === Answers.DENY) {
|
|
133
|
+
return true;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const file = join(opts.root, MANIFEST_FILE);
|
|
137
|
+
|
|
138
|
+
if (!existsSync(file)) {
|
|
139
|
+
return false;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
try {
|
|
143
|
+
const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
|
|
144
|
+
const guard = isRecord(manifest) ? manifest.guard : undefined;
|
|
145
|
+
|
|
146
|
+
return !isRecord(manifest) || (isRecord(guard) && guard.asks === Answers.DENY);
|
|
147
|
+
} catch {
|
|
148
|
+
return true;
|
|
149
|
+
}
|
|
150
|
+
};
|
|
151
|
+
|
|
110
152
|
/** The event Claude Code sends: snake_case keys on the wire, written through string-literal keys. */
|
|
111
153
|
const wireEventOf = (opts: {
|
|
112
154
|
tool: string;
|
|
@@ -187,10 +229,24 @@ const runGuard = (opts: {
|
|
|
187
229
|
const script = join(opts.root, HOOKS_DIRECTORY, `${opts.guard.name}.ts`);
|
|
188
230
|
|
|
189
231
|
if (!existsSync(script)) {
|
|
190
|
-
|
|
232
|
+
// The package is installed and only this guard is gone from it: guard-writes passes (nothing to run), the others block.
|
|
233
|
+
if (existsSync(join(opts.root, PACKAGE_DIRECTORY, 'package.json'))) {
|
|
234
|
+
return opts.guard.isClosedWhenGone
|
|
235
|
+
? {
|
|
236
|
+
kind: Answers.MISSING,
|
|
237
|
+
reason: `VULCAN guards unavailable: ${opts.guard.name} is not in the installed package; run bun node_modules/.bin/vulcan sync`,
|
|
238
|
+
}
|
|
239
|
+
: { kind: Answers.ALLOW, reason: '' };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
return {
|
|
243
|
+
kind: Answers.MISSING,
|
|
244
|
+
reason: `VULCAN guards unavailable: ${opts.guard.name} is missing; finish bun install`,
|
|
245
|
+
};
|
|
191
246
|
}
|
|
192
247
|
|
|
193
|
-
|
|
248
|
+
// bun reads `.env` and `bunfig.toml` from the working directory: a file an agent writes there (a `VULCAN_GUARDS=off`, a preload) must not reach a guard.
|
|
249
|
+
const result = spawnSync('bun', ['--no-env-file', '--config=/dev/null', script], {
|
|
194
250
|
input: JSON.stringify(opts.claudeEvent),
|
|
195
251
|
encoding: 'utf8',
|
|
196
252
|
timeout: TIMEOUT_MS,
|
|
@@ -252,10 +308,13 @@ export class GuardVerdict {
|
|
|
252
308
|
}
|
|
253
309
|
|
|
254
310
|
if (answer.kind === Answers.MISSING) {
|
|
255
|
-
const
|
|
256
|
-
|
|
311
|
+
const command = String(opts.input.command);
|
|
312
|
+
const isRepair = opts.toolName === Tools.BASH && REPAIR.test(command);
|
|
313
|
+
const isCovered =
|
|
314
|
+
guard.onlyLines === undefined ||
|
|
315
|
+
(opts.toolName === Tools.BASH && guard.onlyLines.test(command));
|
|
257
316
|
|
|
258
|
-
if (
|
|
317
|
+
if (!isRepair && isCovered) {
|
|
259
318
|
return { kind: Verdicts.DENY, reason: answer.reason };
|
|
260
319
|
}
|
|
261
320
|
}
|
|
@@ -269,6 +328,10 @@ export class GuardVerdict {
|
|
|
269
328
|
}
|
|
270
329
|
}
|
|
271
330
|
|
|
331
|
+
if (asks.length > 0 && isHeldIn({ root })) {
|
|
332
|
+
return { kind: Verdicts.DENY, reason: `${asks.join('\n\n')}\n\n${HELD_ASK}` };
|
|
333
|
+
}
|
|
334
|
+
|
|
272
335
|
return asks.length > 0
|
|
273
336
|
? { kind: Verdicts.ASK, reason: asks.join('\n\n') }
|
|
274
337
|
: { kind: Verdicts.ALLOW, reason: '' };
|
package/base/hooks/guard-git.ts
CHANGED
|
@@ -5,11 +5,12 @@
|
|
|
5
5
|
* `reset --hard`, other force-pushes, `branch -D` of an unmerged branch and `gh pr create` with no `--base`
|
|
6
6
|
* (ask: the pull request would land on the default branch).
|
|
7
7
|
*
|
|
8
|
-
* It guards against drift, it is not the last line of defence,
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
* `
|
|
8
|
+
* It guards against drift, it is not the last line of defence. A missing package, `bun` or hook file is the settings wrapper's
|
|
9
|
+
* to answer: it blocks a command that names `git` or `gh`, bar `bun install` and `vulcan sync`. Input it cannot read ASKS,
|
|
10
|
+
* because nothing was checked. A guard that started and then failed - a crash or a timeout, here an internal error or an
|
|
11
|
+
* unloadable module - ASKS about a command that names `git` or `gh`, instead of passing it unchecked. Where the project
|
|
12
|
+
* (`guard.asks: 'deny'`) or the launch environment (`VULCAN_GUARD_ASKS=deny`) holds every ask, each ask is a deny, and so is a
|
|
13
|
+
* crash when the manifest exists and cannot be read. `VULCAN_GUARDS=off` switches it off, read before anything is
|
|
13
14
|
* imported. It imports only the modules it needs - no config, no zod. The branches the project lists in
|
|
14
15
|
* `guard.git.askPush` are read from the manifest, and a plain push to one of them asks.
|
|
15
16
|
*/
|
|
@@ -27,34 +28,73 @@ try {
|
|
|
27
28
|
const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
|
|
28
29
|
const { HookDecision } = await import('../../src/hooks/decision.ts');
|
|
29
30
|
const { GitGuard } = await import('../../src/hooks/guard-git.ts');
|
|
31
|
+
const { RunnerGuard } = await import('../../src/hooks/guard-runner.ts');
|
|
30
32
|
const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
|
|
31
33
|
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
32
34
|
const hookCommand = WriteGuard.parseHookCommand({ text });
|
|
33
35
|
const cwd = hookCommand?.cwd ?? process.cwd();
|
|
36
|
+
const policy = ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
|
|
34
37
|
const hits = hookCommand
|
|
35
|
-
?
|
|
36
|
-
command: hookCommand.command,
|
|
37
|
-
cwd,
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
38
|
+
? [
|
|
39
|
+
...GitGuard.inspect({ command: hookCommand.command, cwd, askPush: policy.askPush }),
|
|
40
|
+
...RunnerGuard.inspect({ command: hookCommand.command, cwd, allow: policy.runnersAllow }),
|
|
41
|
+
]
|
|
42
|
+
: [
|
|
43
|
+
{
|
|
44
|
+
rule: 'V-W-01',
|
|
45
|
+
message: 'the hook input could not be read, so the command was not checked',
|
|
46
|
+
decision: GuardDecisions.ASK,
|
|
47
|
+
fix: undefined,
|
|
48
|
+
},
|
|
49
|
+
];
|
|
41
50
|
|
|
42
51
|
if (hits.length > 0) {
|
|
43
52
|
const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
|
|
53
|
+
// A project that sets guard.asks to deny refuses what would ask a human, with the owner to hand it to.
|
|
54
|
+
const isHeld = !denied && policy.asks === GuardDecisions.DENY;
|
|
55
|
+
// A denial the agent can repair says how; one that is the owner's to decide is handed to the owner.
|
|
56
|
+
const fixes = [
|
|
57
|
+
...new Set(
|
|
58
|
+
hits.flatMap((hit) =>
|
|
59
|
+
hit.decision === GuardDecisions.DENY && hit.fix !== undefined ? [hit.fix] : [],
|
|
60
|
+
),
|
|
61
|
+
),
|
|
62
|
+
];
|
|
63
|
+
const isOwners = hits.some(
|
|
64
|
+
(hit) => hit.decision === GuardDecisions.DENY && hit.fix === undefined,
|
|
65
|
+
);
|
|
44
66
|
|
|
45
67
|
console.log(
|
|
46
68
|
JSON.stringify(
|
|
47
69
|
HookDecision.buildTool({
|
|
48
|
-
|
|
70
|
+
asks: policy.asks,
|
|
71
|
+
asksNote: policy.asksNote,
|
|
72
|
+
decision: denied || isHeld ? GuardDecisions.DENY : GuardDecisions.ASK,
|
|
49
73
|
reason: [
|
|
50
74
|
denied
|
|
51
75
|
? 'This command is refused by the base rules:'
|
|
52
|
-
:
|
|
76
|
+
: isHeld
|
|
77
|
+
? 'This command needs a human to confirm, and every ask is denied here:'
|
|
78
|
+
: 'This command needs a human to confirm:',
|
|
53
79
|
...hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
|
|
54
80
|
'',
|
|
55
|
-
denied
|
|
56
|
-
?
|
|
57
|
-
|
|
81
|
+
...(denied
|
|
82
|
+
? [
|
|
83
|
+
...(fixes.length > 0
|
|
84
|
+
? [`Nothing was run. Write it again: ${fixes.join('; ')}.`]
|
|
85
|
+
: []),
|
|
86
|
+
...(isOwners || fixes.length === 0
|
|
87
|
+
? [
|
|
88
|
+
'Hand the exact command to the owner instead (V-W-06); VULCAN_GUARDS=off switches the guards off for a session.',
|
|
89
|
+
]
|
|
90
|
+
: []),
|
|
91
|
+
]
|
|
92
|
+
: isHeld
|
|
93
|
+
? [
|
|
94
|
+
'Nothing was run. Hand the exact command to the owner instead (V-W-06).',
|
|
95
|
+
...(policy.asksNote === undefined ? [] : [policy.asksNote]),
|
|
96
|
+
]
|
|
97
|
+
: ['Confirm only if the owner asked for exactly this.']),
|
|
58
98
|
],
|
|
59
99
|
}),
|
|
60
100
|
),
|
|
@@ -65,18 +105,54 @@ try {
|
|
|
65
105
|
|
|
66
106
|
console.error(`vulcan: the guard-git hook failed (${message}); run bun install`);
|
|
67
107
|
|
|
68
|
-
// The imports may be what failed, so the answer is written by hand
|
|
108
|
+
// The imports may be what failed, so the answer is written by hand, and a project that sets guard.asks to deny is read from the manifest by hand too.
|
|
69
109
|
if (/(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/.test(text)) {
|
|
110
|
+
let isHeldOnCrash = false;
|
|
111
|
+
|
|
112
|
+
try {
|
|
113
|
+
const { existsSync, readFileSync } = await import('node:fs');
|
|
114
|
+
const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
115
|
+
const file = `${root}/.agents/vulcan.manifest.json`;
|
|
116
|
+
|
|
117
|
+
isHeldOnCrash = process.env.VULCAN_GUARD_ASKS === 'deny';
|
|
118
|
+
|
|
119
|
+
if (!isHeldOnCrash && existsSync(file)) {
|
|
120
|
+
try {
|
|
121
|
+
const manifest: unknown = JSON.parse(readFileSync(file, 'utf8'));
|
|
122
|
+
const guard =
|
|
123
|
+
typeof manifest === 'object' && manifest !== null && 'guard' in manifest
|
|
124
|
+
? manifest.guard
|
|
125
|
+
: undefined;
|
|
126
|
+
|
|
127
|
+
isHeldOnCrash =
|
|
128
|
+
typeof manifest !== 'object' ||
|
|
129
|
+
manifest === null ||
|
|
130
|
+
Array.isArray(manifest) ||
|
|
131
|
+
(typeof guard === 'object' &&
|
|
132
|
+
guard !== null &&
|
|
133
|
+
'asks' in guard &&
|
|
134
|
+
guard.asks === 'deny');
|
|
135
|
+
} catch {
|
|
136
|
+
// A manifest that exists and cannot be read holds every ask.
|
|
137
|
+
isHeldOnCrash = true;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
} catch {
|
|
141
|
+
isHeldOnCrash = false;
|
|
142
|
+
}
|
|
143
|
+
|
|
70
144
|
console.log(
|
|
71
145
|
JSON.stringify({
|
|
72
146
|
hookSpecificOutput: {
|
|
73
147
|
hookEventName: 'PreToolUse',
|
|
74
|
-
permissionDecision: 'ask',
|
|
148
|
+
permissionDecision: isHeldOnCrash ? 'deny' : 'ask',
|
|
75
149
|
permissionDecisionReason: [
|
|
76
150
|
'The guard-git hook failed, so this command was not checked:',
|
|
77
151
|
` - ${message}`,
|
|
78
152
|
'',
|
|
79
|
-
|
|
153
|
+
isHeldOnCrash
|
|
154
|
+
? 'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: run bun install to repair the install.'
|
|
155
|
+
: 'Confirm only if the owner asked for exactly this; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
|
|
80
156
|
].join('\n'),
|
|
81
157
|
},
|
|
82
158
|
}),
|