@venizia/vulcan 0.4.10-2 → 0.4.10-20
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 +3 -74
- package/base/extensions/vulcan-guards.ts +9 -8
- package/base/hooks/guard-git.ts +39 -11
- package/base/hooks/guard-outside.ts +94 -35
- package/base/hooks/guard-writes.ts +10 -35
- 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/generated-block.ts +52 -0
- 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 +37 -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 +298 -144
- 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 +0 -17
- package/src/hooks/common/types.ts +11 -24
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +282 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +84 -183
- 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 +29 -40
- 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 +574 -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 +83 -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 \"$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,25 +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"
|
|
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; 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"
|
|
41
23
|
}
|
|
42
24
|
]
|
|
43
25
|
},
|
|
@@ -50,15 +32,6 @@
|
|
|
50
32
|
}
|
|
51
33
|
]
|
|
52
34
|
},
|
|
53
|
-
{
|
|
54
|
-
"matcher": "Bash",
|
|
55
|
-
"hooks": [
|
|
56
|
-
{
|
|
57
|
-
"type": "command",
|
|
58
|
-
"command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/guard-scripting.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\" || echo \"vulcan: the guard-scripting hook failed - the call passes\" >&2; exit 0; fi; echo \"vulcan: the guard-scripting hook cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes\" >&2; exit 0"
|
|
59
|
-
}
|
|
60
|
-
]
|
|
61
|
-
},
|
|
62
35
|
{
|
|
63
36
|
"matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
|
|
64
37
|
"hooks": [
|
|
@@ -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 \"$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
|
}
|
|
@@ -5,7 +5,8 @@
|
|
|
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
7
|
// policy as the Claude wrappers: the safety guards block, the others ask, and a missing install passes
|
|
8
|
-
// except for the safety guards, which block - bar a bare `bun install`, the way to repair it.
|
|
8
|
+
// except for the safety guards, which block - bar a bare `bun install`, the way to repair it. A guard that
|
|
9
|
+
// is gone from an installed package passes: there is nothing to run.
|
|
9
10
|
// Only node: modules are imported, so any host that loads TypeScript can load it.
|
|
10
11
|
|
|
11
12
|
import { spawnSync } from 'node:child_process';
|
|
@@ -66,7 +67,8 @@ interface IAnswer {
|
|
|
66
67
|
reason: string;
|
|
67
68
|
}
|
|
68
69
|
|
|
69
|
-
const
|
|
70
|
+
const PACKAGE_DIRECTORY = join('node_modules', '@venizia', 'vulcan');
|
|
71
|
+
const HOOKS_DIRECTORY = join(PACKAGE_DIRECTORY, 'base', 'hooks');
|
|
70
72
|
const TIMEOUT_MS = 30_000;
|
|
71
73
|
/** The one command that passes while the install is missing: it is how the install is repaired. */
|
|
72
74
|
const BUN_INSTALL =
|
|
@@ -75,12 +77,6 @@ const BUN_INSTALL =
|
|
|
75
77
|
/** The guards of `.claude/settings.json`, with the tools each covers and what each does when it cannot answer. */
|
|
76
78
|
const GUARDS: IGuard[] = [
|
|
77
79
|
{ name: 'guard-writes', tools: [Tools.BASH], onFailure: Failures.BLOCK },
|
|
78
|
-
{
|
|
79
|
-
name: 'guard-manifest',
|
|
80
|
-
tools: [Tools.BASH, Tools.WRITE, Tools.EDIT],
|
|
81
|
-
onFailure: Failures.BLOCK,
|
|
82
|
-
},
|
|
83
|
-
{ name: 'guard-package', tools: [Tools.WRITE], onFailure: Failures.BLOCK },
|
|
84
80
|
{ name: 'guard-git', tools: [Tools.BASH], onFailure: Failures.ASK },
|
|
85
81
|
{ name: 'guard-outside', tools: [Tools.BASH, Tools.WRITE, Tools.EDIT], onFailure: Failures.ASK },
|
|
86
82
|
];
|
|
@@ -187,6 +183,11 @@ const runGuard = (opts: {
|
|
|
187
183
|
const script = join(opts.root, HOOKS_DIRECTORY, `${opts.guard.name}.ts`);
|
|
188
184
|
|
|
189
185
|
if (!existsSync(script)) {
|
|
186
|
+
// The package is installed and only this guard is gone from it: nothing to run, the call passes.
|
|
187
|
+
if (existsSync(join(opts.root, PACKAGE_DIRECTORY, 'package.json'))) {
|
|
188
|
+
return { kind: Answers.ALLOW, reason: '' };
|
|
189
|
+
}
|
|
190
|
+
|
|
190
191
|
return { kind: Answers.MISSING, reason: `${opts.guard.name} is missing: run bun install` };
|
|
191
192
|
}
|
|
192
193
|
|
package/base/hooks/guard-git.ts
CHANGED
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
* (ask: the pull request would land on the default branch).
|
|
7
7
|
*
|
|
8
8
|
* It guards against drift, it is not the last line of defence, and a guard that blocks every command when
|
|
9
|
-
* its install is broken costs more than it protects. So
|
|
10
|
-
*
|
|
9
|
+
* its install is broken costs more than it protects. So a missing package or `bun` passes (the settings wrapper
|
|
10
|
+
* says so on stderr); input it cannot read ASKS, because nothing was checked. A guard that started and then failed - a crash
|
|
11
11
|
* or a timeout, here an internal error or an unloadable module - ASKS about a command that names `git` or
|
|
12
12
|
* `gh`, instead of passing it unchecked. `VULCAN_GUARDS=off` switches it off, read before anything is
|
|
13
13
|
* imported. It imports only the modules it needs - no config, no zod. The branches the project lists in
|
|
@@ -27,20 +27,39 @@ try {
|
|
|
27
27
|
const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
|
|
28
28
|
const { HookDecision } = await import('../../src/hooks/decision.ts');
|
|
29
29
|
const { GitGuard } = await import('../../src/hooks/guard-git.ts');
|
|
30
|
+
const { RunnerGuard } = await import('../../src/hooks/guard-runner.ts');
|
|
30
31
|
const { WriteGuard } = await import('../../src/hooks/guard-writes.ts');
|
|
31
32
|
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
32
33
|
const hookCommand = WriteGuard.parseHookCommand({ text });
|
|
33
34
|
const cwd = hookCommand?.cwd ?? process.cwd();
|
|
35
|
+
const policy = ProjectGuards.readPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
|
|
34
36
|
const hits = hookCommand
|
|
35
|
-
?
|
|
36
|
-
command: hookCommand.command,
|
|
37
|
-
cwd,
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
37
|
+
? [
|
|
38
|
+
...GitGuard.inspect({ command: hookCommand.command, cwd, askPush: policy.askPush }),
|
|
39
|
+
...RunnerGuard.inspect({ command: hookCommand.command, cwd, allow: policy.runnersAllow }),
|
|
40
|
+
]
|
|
41
|
+
: [
|
|
42
|
+
{
|
|
43
|
+
rule: 'V-W-01',
|
|
44
|
+
message: 'the hook input could not be read, so the command was not checked',
|
|
45
|
+
decision: GuardDecisions.ASK,
|
|
46
|
+
fix: undefined,
|
|
47
|
+
},
|
|
48
|
+
];
|
|
41
49
|
|
|
42
50
|
if (hits.length > 0) {
|
|
43
51
|
const denied = hits.some((hit) => hit.decision === GuardDecisions.DENY);
|
|
52
|
+
// A denial the agent can repair says how; one that is the owner's to decide is handed to the owner.
|
|
53
|
+
const fixes = [
|
|
54
|
+
...new Set(
|
|
55
|
+
hits.flatMap((hit) =>
|
|
56
|
+
hit.decision === GuardDecisions.DENY && hit.fix !== undefined ? [hit.fix] : [],
|
|
57
|
+
),
|
|
58
|
+
),
|
|
59
|
+
];
|
|
60
|
+
const isOwners = hits.some(
|
|
61
|
+
(hit) => hit.decision === GuardDecisions.DENY && hit.fix === undefined,
|
|
62
|
+
);
|
|
44
63
|
|
|
45
64
|
console.log(
|
|
46
65
|
JSON.stringify(
|
|
@@ -52,9 +71,18 @@ try {
|
|
|
52
71
|
: 'This command needs a human to confirm:',
|
|
53
72
|
...hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
|
|
54
73
|
'',
|
|
55
|
-
denied
|
|
56
|
-
?
|
|
57
|
-
|
|
74
|
+
...(denied
|
|
75
|
+
? [
|
|
76
|
+
...(fixes.length > 0
|
|
77
|
+
? [`Nothing was run. Write it again: ${fixes.join('; ')}.`]
|
|
78
|
+
: []),
|
|
79
|
+
...(isOwners || fixes.length === 0
|
|
80
|
+
? [
|
|
81
|
+
'Hand the exact command to the owner instead (V-W-06); VULCAN_GUARDS=off switches the guards off for a session.',
|
|
82
|
+
]
|
|
83
|
+
: []),
|
|
84
|
+
]
|
|
85
|
+
: ['Confirm only if the owner asked for exactly this.']),
|
|
58
86
|
],
|
|
59
87
|
}),
|
|
60
88
|
),
|
|
@@ -3,16 +3,21 @@
|
|
|
3
3
|
* created outside the project (V-B-08). Stores a package manager, runtime or the agent tool manage
|
|
4
4
|
* themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
|
|
5
5
|
* `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
|
|
6
|
-
*
|
|
7
|
-
* approved unseen. A write into the agent tool scratchpad is always denied.
|
|
6
|
+
* A write outside the project asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents
|
|
7
|
+
* where an ask can be approved unseen. A write into the agent tool scratchpad is always denied. A part of the call it
|
|
8
|
+
* cannot read (a program or a target named by a variable it cannot resolve, a line it cannot follow to its end) is always
|
|
9
|
+
* DENIED, never asked: the agent can write the call again with a literal path, so a person is not stopped for it, and the
|
|
10
|
+
* reason says how. Literal assignments of the same line (`S=dir; ... > $S/a`, `export X=dir`, `for i in 1 2`) are
|
|
11
|
+
* resolved first, so the usual safe forms are read.
|
|
8
12
|
*
|
|
9
13
|
* It guards against drift, not against an attacker, and a guard that blocks every call when its install
|
|
10
|
-
* is broken costs more than it protects. So
|
|
11
|
-
*
|
|
14
|
+
* is broken costs more than it protects. So a missing package or `bun` passes (the settings wrapper says so on
|
|
15
|
+
* stderr); a hook input it cannot read ASKS, because nothing was checked and the agent cannot repair that. A guard that started and then failed - a crash or a
|
|
12
16
|
* timeout, here an internal error or an unloadable module - ASKS instead of passing the call unchecked; a
|
|
13
|
-
*
|
|
14
|
-
* read before anything is imported. It
|
|
15
|
-
*
|
|
17
|
+
* manifest that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
|
|
18
|
+
* read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
|
|
19
|
+
* from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
|
|
20
|
+
* VULCAN cannot parse, then changes nothing here.
|
|
16
21
|
*/
|
|
17
22
|
|
|
18
23
|
// A module, so the awaits below are top-level; it has no static import, by design.
|
|
@@ -28,59 +33,113 @@ try {
|
|
|
28
33
|
const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
|
|
29
34
|
const { HookDecision } = await import('../../src/hooks/decision.ts');
|
|
30
35
|
const { OutsideGuard } = await import('../../src/hooks/guard-outside.ts');
|
|
31
|
-
const {
|
|
32
|
-
const
|
|
36
|
+
const { HookInput } = await import('../../src/hooks/hook-input.ts');
|
|
37
|
+
const { ProjectTmp } = await import('../../src/hooks/project-tmp.ts');
|
|
38
|
+
const { relative } = await import('node:path');
|
|
39
|
+
const input = HookInput.parse({ text });
|
|
33
40
|
|
|
34
|
-
if (input) {
|
|
41
|
+
if (!input) {
|
|
42
|
+
console.log(
|
|
43
|
+
JSON.stringify(
|
|
44
|
+
HookDecision.buildTool({
|
|
45
|
+
decision: GuardDecisions.ASK,
|
|
46
|
+
reason: [
|
|
47
|
+
'The hook input could not be read, so this call was not checked for files outside the project (V-B-08).',
|
|
48
|
+
'Confirm only if the call stays inside the project.',
|
|
49
|
+
],
|
|
50
|
+
}),
|
|
51
|
+
),
|
|
52
|
+
);
|
|
53
|
+
} else {
|
|
35
54
|
const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
try {
|
|
40
|
-
const { ConfigLoader } = await import('../../src/config/index.ts');
|
|
41
|
-
const loaded = await ConfigLoader.load({ root: projectRoot });
|
|
42
|
-
|
|
43
|
-
toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
|
|
44
|
-
outside = loaded.ok ? loaded.config.guard.outside : GuardDecisions.ASK;
|
|
45
|
-
} catch (error) {
|
|
46
|
-
console.error(
|
|
47
|
-
`vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
|
|
48
|
-
);
|
|
49
|
-
}
|
|
55
|
+
const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
|
|
56
|
+
const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
|
|
50
57
|
|
|
51
58
|
const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
|
|
52
59
|
|
|
53
60
|
if (hits.length > 0) {
|
|
54
|
-
const
|
|
55
|
-
const
|
|
56
|
-
const
|
|
57
|
-
|
|
61
|
+
const read = hits.filter((hit) => !hit.isUnread);
|
|
62
|
+
const isScratchpad = read.some((hit) => hit.isAgentToolScratchpad);
|
|
63
|
+
const linesOf = (list: typeof hits) => list.map((hit) => ` - ${hit.message} (${hit.path})`);
|
|
64
|
+
const tmpFolder = relative(projectRoot, ProjectTmp.projectOf({ root: projectRoot }));
|
|
65
|
+
const places = `Scratch files go under ${tmpFolder}/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.`;
|
|
66
|
+
const owned =
|
|
67
|
+
'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.';
|
|
58
68
|
|
|
59
|
-
|
|
69
|
+
// A line the check could not read is denied, whatever the project sets: the agent can write it again so that it is read.
|
|
70
|
+
const unreadHits = hits.filter((hit) => hit.isUnread);
|
|
71
|
+
const unread =
|
|
72
|
+
unreadHits.length === 0
|
|
73
|
+
? []
|
|
74
|
+
: [
|
|
75
|
+
...(read.length > 0 ? [''] : []),
|
|
76
|
+
'Part of this call could not be read, so it was not checked for files outside the project (V-B-08):',
|
|
77
|
+
...linesOf(unreadHits),
|
|
78
|
+
];
|
|
79
|
+
// A link to a path outside the project is a way to write there with a name inside it: denied, as the agent can copy or link inside.
|
|
80
|
+
const linkHits = read.filter((hit) => hit.isLink === true);
|
|
81
|
+
const isDeny =
|
|
82
|
+
isScratchpad ||
|
|
83
|
+
linkHits.length > 0 ||
|
|
84
|
+
unreadHits.length > 0 ||
|
|
85
|
+
(outside === GuardDecisions.DENY && read.length > 0);
|
|
60
86
|
let reason: string[];
|
|
61
87
|
|
|
62
|
-
if (isScratchpad) {
|
|
88
|
+
if (unreadHits.length > 0 && !isScratchpad) {
|
|
89
|
+
reason = [
|
|
90
|
+
'Part of this call could not be read, so it cannot be checked for files outside the project (V-B-08):',
|
|
91
|
+
...linesOf(unreadHits),
|
|
92
|
+
...(read.length > 0
|
|
93
|
+
? [
|
|
94
|
+
'',
|
|
95
|
+
'The part that was read would also create files outside the project:',
|
|
96
|
+
...linesOf(read),
|
|
97
|
+
]
|
|
98
|
+
: []),
|
|
99
|
+
'',
|
|
100
|
+
`Nothing was run. Write it again so the guard can read it: a literal path in every redirect (no $VAR or $(...) in a target; after a cd the guard cannot work out, an absolute path), a cd to a literal folder, the folder assigned on the same line (S=${tmpFolder}/x; ... > "$S/a") or named by a for loop over literal words; or put the script in a file under ${tmpFolder}/<task>/ and run it by that literal path (bun ${tmpFolder}/<task>/step.ts), with literal paths inside the project in its own redirects too: the guard does not read the script. ${places}`,
|
|
101
|
+
owned,
|
|
102
|
+
];
|
|
103
|
+
} else if (isScratchpad) {
|
|
63
104
|
reason = [
|
|
64
105
|
'This would write into the scratchpad folder the agent tool offers (V-B-08):',
|
|
65
|
-
...
|
|
106
|
+
...linesOf(read),
|
|
107
|
+
...unread,
|
|
66
108
|
'',
|
|
67
109
|
`That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
|
|
68
110
|
];
|
|
111
|
+
} else if (linkHits.length > 0) {
|
|
112
|
+
reason = [
|
|
113
|
+
'This would hard-link a path outside the project (V-B-08); a hard link cannot be told from the file, so a write through it changes that path later too:',
|
|
114
|
+
...linesOf(linkHits),
|
|
115
|
+
...(read.length > linkHits.length
|
|
116
|
+
? [
|
|
117
|
+
'',
|
|
118
|
+
'It would also create files outside the project:',
|
|
119
|
+
...linesOf(read.filter((hit) => hit.isLink !== true)),
|
|
120
|
+
]
|
|
121
|
+
: []),
|
|
122
|
+
'',
|
|
123
|
+
`Nothing was run. Copy the file into the project (cp) instead of linking it, link a path inside the project, or make a symbolic link (ln -s), which is read once it exists. ${places}`,
|
|
124
|
+
owned,
|
|
125
|
+
];
|
|
69
126
|
} else if (isDeny) {
|
|
70
127
|
reason = [
|
|
71
128
|
'This would create files outside the project (V-B-08), and this project denies it (guard.outside):',
|
|
72
|
-
...
|
|
129
|
+
...linesOf(read),
|
|
130
|
+
...unread,
|
|
73
131
|
'',
|
|
74
132
|
`Nothing was written. ${places}`,
|
|
75
|
-
|
|
133
|
+
owned,
|
|
76
134
|
];
|
|
77
135
|
} else {
|
|
78
136
|
reason = [
|
|
79
137
|
'This would create files outside the project (V-B-08):',
|
|
80
|
-
...
|
|
138
|
+
...linesOf(read),
|
|
139
|
+
...unread,
|
|
81
140
|
'',
|
|
82
141
|
`${places} Use that place, or confirm only if the owner asked for this exact path.`,
|
|
83
|
-
|
|
142
|
+
owned,
|
|
84
143
|
];
|
|
85
144
|
}
|
|
86
145
|
|