@venizia/vulcan 0.4.4 → 0.4.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +1 -1
- package/README.md +13 -0
- package/base/agents.json +22 -1
- package/base/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +12 -12
- package/base/extensions/vulcan-guards.ts +301 -0
- package/base/hooks/antigravity-guards.ts +68 -0
- package/base/hooks/codex-guards.ts +66 -0
- package/base/hooks/guard-git.ts +38 -9
- package/base/hooks/guard-outside.ts +29 -9
- package/base/hooks/guard-writes.ts +29 -1
- package/base/hooks/session-start.ts +14 -4
- package/base/make/vulcan.mk +12 -1
- package/base/references/delegation-brief.md +5 -4
- package/base/rules.md +2 -2
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/docs-writing/references/agent-documents.md +1 -1
- package/base/skills/knowledge-sync/SKILL.md +1 -1
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/report-back/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +1 -1
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +33 -11
- package/base/skills/visualize-work/references/spec.md +77 -12
- package/package.json +4 -4
- package/src/agents/codex-hooks.ts +133 -0
- package/src/agents/common/constants.ts +54 -0
- package/src/agents/common/schema.ts +10 -1
- package/src/agents/common/types.ts +3 -1
- package/src/agents/exclude.ts +4 -0
- package/src/agents/hooks-json.ts +111 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +5 -4
- package/src/agents/resolve.ts +24 -9
- package/src/config/common/constants.ts +12 -0
- package/src/config/common/types.ts +2 -1
- package/src/config/packages.ts +2 -1
- package/src/config/schema.ts +84 -5
- package/src/create/add-app.ts +2 -2
- package/src/create/add-lib.ts +21 -8
- package/src/create/common/constants.ts +12 -0
- package/src/create/common/types.ts +2 -1
- package/src/create/preset-diff.ts +4 -2
- package/src/create/workspace.ts +13 -9
- package/src/doctor/checks.ts +71 -1
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +6 -0
- package/src/hooks/codex-patch.ts +47 -0
- package/src/hooks/command-view.ts +97 -0
- package/src/hooks/common/constants.ts +46 -0
- package/src/hooks/common/types.ts +9 -1
- package/src/hooks/decision.ts +50 -8
- package/src/hooks/guard-git.ts +64 -5
- package/src/hooks/guard-manifest.ts +22 -8
- package/src/hooks/guard-outside.ts +38 -6
- package/src/hooks/guard-package.ts +15 -12
- package/src/hooks/guard-writes.ts +72 -21
- package/src/hooks/index.ts +5 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/remote-hosts.ts +38 -14
- package/src/hooks/session-digest.ts +5 -0
- package/src/hooks/shell.ts +665 -35
- package/src/hooks/trusted-scripts.ts +134 -0
- package/src/manifest/render.ts +38 -0
- package/src/sync/agent-files.ts +122 -4
- package/src/sync/agent-removal.ts +118 -4
- package/src/sync/claude-launch.ts +48 -0
- package/src/sync/index.ts +1 -0
- package/src/sync/local-choice.ts +2 -0
- package/src/visualize/assets.ts +195 -54
- package/src/visualize/charts.ts +235 -0
- package/src/visualize/constants.ts +122 -1
- package/src/visualize/diagrams.ts +224 -0
- package/src/visualize/icons.ts +28 -0
- package/src/visualize/layout.ts +58 -8
- package/src/visualize/page.ts +151 -145
- package/src/visualize/schema.ts +252 -2
- package/src/visualize/sections.ts +370 -0
- package/src/visualize/validate.ts +100 -7
- package/src/wiki/anchors.ts +118 -0
- package/src/wiki/command.ts +110 -0
- package/src/wiki/constants.ts +30 -0
- package/src/wiki/index.ts +4 -0
- package/src/wiki/source-links.ts +186 -0
|
@@ -3,7 +3,30 @@
|
|
|
3
3
|
One JSON file. It is strict: an unknown key is an error, and every text is a plain line that is escaped,
|
|
4
4
|
never markup. `bun x --no-install vulcan visualize --schema` prints the full JSON Schema.
|
|
5
5
|
|
|
6
|
-
**Contents**: [Fields](#fields) · [Limits](#limits) · [
|
|
6
|
+
**Contents**: [The kinds](#the-kinds) · [Fields](#fields) · [The other kinds](#the-other-kinds) · [Limits](#limits) · [Two worked specs](#two-worked-specs)
|
|
7
|
+
|
|
8
|
+
## The kinds
|
|
9
|
+
|
|
10
|
+
A page is the sections its spec has, in a fixed order: the banner (title, verdict, state), the tiles, the minimap,
|
|
11
|
+
what you need to do and what blocks it, then the flow, the architecture, the comparison, the idea map, the
|
|
12
|
+
explainer, the timeline, the findings, the before and after, the decision record, the decisions, the evidence,
|
|
13
|
+
the risks, the log and the links. Pick the sections the question needs and leave the rest out:
|
|
14
|
+
|
|
15
|
+
| The page is | Use |
|
|
16
|
+
|---|---|
|
|
17
|
+
| A status or a handoff for the owner | `strip`, `actions`, `minimap`, `decisions`, `evidence`, `risks`, `log` |
|
|
18
|
+
| How something moves | `flow` (boxes on a grid, labelled arrows, numbered steps) |
|
|
19
|
+
| How a system is built | `architecture` (layers of boxes with links) |
|
|
20
|
+
| Options compared, with a pick | `comparison` (scores per criterion, pros and cons, a recommended option) |
|
|
21
|
+
| A brainstorm | `ideaMap` (a centre and clusters of ideas) |
|
|
22
|
+
| An idea explained | `explainer` (numbered steps, a small diagram for each) |
|
|
23
|
+
| A plan or a roadmap | `timeline` (dated items with a state) |
|
|
24
|
+
| Findings | `findings` (key numbers, bar, line and donut charts, callouts) |
|
|
25
|
+
| A choice that was made | `decisionRecord` (context, options, the decision, consequences) |
|
|
26
|
+
| A change | `beforeAfter` |
|
|
27
|
+
|
|
28
|
+
Add `?present=1` to the page address, or press **Present**, to walk through it as slides: arrow keys,
|
|
29
|
+
Space, Home, End and Escape, one section per slide; print gives one section after another.
|
|
7
30
|
|
|
8
31
|
## Fields
|
|
9
32
|
|
|
@@ -12,11 +35,14 @@ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSO
|
|
|
12
35
|
| `schemaVersion` | `1` |
|
|
13
36
|
| `title` | The takeaway, at most 120 characters |
|
|
14
37
|
| `language` | A language code (`en`, `pt-BR`); default `en` |
|
|
15
|
-
| `status` | `{ state: ok \| warn \| blocked \| info, label? }`;
|
|
38
|
+
| `status` | `{ state: ok \| warn \| blocked \| info, label? }`; the banner's colour, icon and word |
|
|
16
39
|
| `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
|
|
17
|
-
| `verdict`, `caption` | One sentence the reader can stop at; one line under
|
|
18
|
-
| `strip` | Four sentences: `healthy`, `blockedBy`, `changed`, `next` |
|
|
19
|
-
| `
|
|
40
|
+
| `verdict`, `caption` | One sentence the reader can stop at; one line under it |
|
|
41
|
+
| `strip` | Four sentences: `healthy`, `blockedBy`, `changed`, `next`; `next` (what the owner has to do) and `blockedBy` open the page, in a card of their own |
|
|
42
|
+
| `actions` | One to six steps, shown as a numbered checklist under `strip.next` |
|
|
43
|
+
| `tiles` | One to six `{ value, label, state? }` key numbers; with a `minimap` and no tiles, the page counts the states itself |
|
|
44
|
+
| `minimap` | Rows of `{ task, status, note? }`, `status` one of `done`, `in progress`, `waiting`, `not started`, `blocked`, `dropped`; drawn as a stepper, one segment per task, with an icon and a word |
|
|
45
|
+
| `flow` | `nodes` (`id`, `label`, `sublabel?`, `detail?`, `row`, `col`, `kind?`, `state?`), `edges` (`from`, `to`, `label`, `variant?`), `steps` (`title`, `note`, `nodes`, `edges`) |
|
|
20
46
|
| `beforeAfter` | `before` and `after`, each a `title` and `items` of `{ text, change? }` (`added` in after, `removed` in before) |
|
|
21
47
|
| `decisions` | One to five of `{ question, recommended, changes }` |
|
|
22
48
|
| `evidence` | Rows of `{ claim, probe, result, label: verified \| inferred \| guess }` |
|
|
@@ -25,17 +51,36 @@ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSO
|
|
|
25
51
|
| `links` | Rows of `{ label, href }`; `href` is https only |
|
|
26
52
|
| `chrome` | Optional replacements for the page's own words, every key optional |
|
|
27
53
|
|
|
28
|
-
Node `kind` is `step`, `service`, `store`, `actor` or `external`: each has its own outline
|
|
29
|
-
|
|
30
|
-
step is named `from>to`.
|
|
54
|
+
Node `kind` is `step`, `service`, `store`, `actor` or `external`: each has its own outline. A node `state` (the six
|
|
55
|
+
minimap words, or `info`) adds a colour, an icon and a word, so the figure can show where the work stands. Edge
|
|
56
|
+
`variant` is `main`, `branch`, `return`, `fanout` or `error`. An edge in a step is named `from>to`.
|
|
57
|
+
|
|
58
|
+
## The other kinds
|
|
59
|
+
|
|
60
|
+
| Field | Content |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `comparison` | `criteria` (up to 8), `options` (2 to 6) of `{ name, line?, scores, pros?, cons?, recommended? }` with one `scores` entry from 1 to 5 per criterion, and an optional `note`; the page totals the scores and draws them as bars |
|
|
63
|
+
| `ideaMap` | `center`, and 2 to 8 `branches` of `{ label, items (1 to 6), note? }` |
|
|
64
|
+
| `explainer` | 1 to 8 `steps` of `{ title, text, diagram? }`; a diagram is `{ type: "row", nodes, arrows? }` (2 to 5 boxes, one arrow label fewer than boxes) or `{ type: "layers", layers }` |
|
|
65
|
+
| `architecture` | `layers` (up to 5) of `{ label, boxes }`, a box `{ id, label, sub?, state? }`, and `links` of `{ from, to, label? }` between box ids |
|
|
66
|
+
| `timeline` | 2 to 20 `items` of `{ date, title, text?, state? }` |
|
|
67
|
+
| `findings` | `numbers` (`{ value, label, state? }`), `charts`, `callouts` (`{ text, state? }`) |
|
|
68
|
+
| `decisionRecord` | `context`, 2 to 5 `options` of `{ name, summary, chosen? }`, the `decision`, `consequences` |
|
|
69
|
+
|
|
70
|
+
A chart is `{ type: "bar", title, unit?, labels, values }` (values from zero up, one per label), `{ type: "line", title,
|
|
71
|
+
unit?, labels, series }` (up to 3 series of `{ name, values }`, one value per label) or `{ type: "donut", title, unit?,
|
|
72
|
+
parts }` (2 to 5 `{ label, value, state? }`). Every chart carries its numbers as a table view, and colour is never the
|
|
73
|
+
only way to tell parts apart: the legend names them and the values are printed.
|
|
31
74
|
|
|
32
75
|
## Limits
|
|
33
76
|
|
|
34
77
|
At most 25 boxes, 40 arrows, 12 steps, 5 decisions and 30 rows per table; grid cells 0 to 9; labels 60
|
|
35
|
-
characters (an arrow label 20), sentences 300, a box detail 600
|
|
36
|
-
a typical page is
|
|
78
|
+
characters (an arrow label 20), sentences 300, a box detail 600; 6 tiles, 4 charts, 12 points per chart.
|
|
79
|
+
The page is refused over 100 KB and warned over 60 KB; a typical page is 20 to 40 KB, most of it the page's own style.
|
|
37
80
|
|
|
38
|
-
##
|
|
81
|
+
## Two worked specs
|
|
82
|
+
|
|
83
|
+
A flow:
|
|
39
84
|
|
|
40
85
|
```json
|
|
41
86
|
{
|
|
@@ -47,7 +92,7 @@ a typical page is 10 to 40 KB.
|
|
|
47
92
|
"flow": {
|
|
48
93
|
"nodes": [
|
|
49
94
|
{ "id": "user", "label": "You", "row": 0, "col": 0, "kind": "actor" },
|
|
50
|
-
{ "id": "form", "label": "The form", "sublabel": "ten questions", "row": 0, "col": 1, "kind": "service" },
|
|
95
|
+
{ "id": "form", "label": "The form", "sublabel": "ten questions", "row": 0, "col": 1, "kind": "service", "state": "done" },
|
|
51
96
|
{ "id": "file", "label": "profile.json", "row": 0, "col": 2, "kind": "store", "detail": "Mode 0600, inside the project." }
|
|
52
97
|
],
|
|
53
98
|
"edges": [
|
|
@@ -63,3 +108,23 @@ a typical page is 10 to 40 KB.
|
|
|
63
108
|
]
|
|
64
109
|
}
|
|
65
110
|
```
|
|
111
|
+
|
|
112
|
+
A comparison with a pick:
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"schemaVersion": 1,
|
|
117
|
+
"title": "A per-session snapshot is the best way to check permissions",
|
|
118
|
+
"status": { "state": "ok", "label": "Recommended" },
|
|
119
|
+
"verdict": "Compute the effective permissions once at sign-in and check against that.",
|
|
120
|
+
"strip": { "healthy": "All three options are workable.", "blockedBy": "Your pick.", "changed": "Option B grew a refresh path.", "next": "Pick B, or say which criterion should weigh more." },
|
|
121
|
+
"comparison": {
|
|
122
|
+
"criteria": ["Security", "Speed", "Simplicity"],
|
|
123
|
+
"options": [
|
|
124
|
+
{ "name": "Central service", "scores": [5, 2, 3], "cons": ["A call on every request"] },
|
|
125
|
+
{ "name": "Snapshot", "scores": [4, 5, 4], "pros": ["No call per request"], "recommended": true },
|
|
126
|
+
{ "name": "Per route", "scores": [3, 4, 5], "cons": ["Rules are scattered"] }
|
|
127
|
+
]
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.6",
|
|
4
4
|
"description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
|
|
5
5
|
"homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
|
|
6
6
|
"bugs": {
|
|
@@ -44,13 +44,13 @@
|
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@clack/prompts": "1.8.1",
|
|
47
|
-
"@venizia/vulcan-atlas": "0.4.
|
|
48
|
-
"@venizia/vulcan-okf": "0.4.
|
|
47
|
+
"@venizia/vulcan-atlas": "0.4.6",
|
|
48
|
+
"@venizia/vulcan-okf": "0.4.6",
|
|
49
49
|
"zod": "^4.6.7"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
52
|
"@types/bun": "1.4.3",
|
|
53
|
-
"@venizia/dev-configs": "0.4.
|
|
53
|
+
"@venizia/dev-configs": "0.4.4",
|
|
54
54
|
"eslint": "10.13.0",
|
|
55
55
|
"oxlint": "1.89.0",
|
|
56
56
|
"oxlint-tsgolint": "7.0.2004",
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
import { RemoveOutcomes } from './common/index.ts';
|
|
2
|
+
|
|
3
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
4
|
+
typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
5
|
+
|
|
6
|
+
/** The script every VULCAN entry runs: it is how an entry of ours is told from a hook of the user's. */
|
|
7
|
+
const GUARD_SCRIPT = 'codex-guards.ts';
|
|
8
|
+
|
|
9
|
+
const DENY_ON_CRASH = JSON.stringify({
|
|
10
|
+
hookSpecificOutput: {
|
|
11
|
+
hookEventName: 'PreToolUse',
|
|
12
|
+
permissionDecision: 'deny',
|
|
13
|
+
permissionDecisionReason:
|
|
14
|
+
'The VULCAN guard crashed, so this call was not checked. Codex cannot ask: a human must confirm it; VULCAN_GUARDS=off switches the guards off for a session.',
|
|
15
|
+
},
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The hook command. Codex runs it from the session's folder, which may be below the project, so the project
|
|
20
|
+
* is the git top level. A missing package or bun passes with a note; a script that started and crashed
|
|
21
|
+
* denies, because Codex cannot ask.
|
|
22
|
+
*/
|
|
23
|
+
const GUARD_COMMAND = [
|
|
24
|
+
'd=$(git rev-parse --show-toplevel 2>/dev/null || pwd);',
|
|
25
|
+
`f="$d/node_modules/@venizia/vulcan/base/hooks/${GUARD_SCRIPT}";`,
|
|
26
|
+
'if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then',
|
|
27
|
+
'in=$(cat); out=$(printf \'%s\' "$in" | bun "$f"); s=$?;',
|
|
28
|
+
`if [ "$s" -eq 0 ]; then printf '%s' "$out"; exit 0; fi;`,
|
|
29
|
+
`printf '%s\\n' '${DENY_ON_CRASH}'; exit 0; fi;`,
|
|
30
|
+
'cat >/dev/null; echo "vulcan: the guards cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes" >&2',
|
|
31
|
+
].join(' ');
|
|
32
|
+
|
|
33
|
+
/** What the entry holds: one hook on the shell and the patch tool. */
|
|
34
|
+
const guardEntry = (): Record<string, unknown> => ({
|
|
35
|
+
matcher: 'Bash|apply_patch',
|
|
36
|
+
hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 60, statusMessage: 'VULCAN guards' }],
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
const isGuardEntry = (entry: unknown): boolean =>
|
|
40
|
+
isRecord(entry) &&
|
|
41
|
+
Array.isArray(entry.hooks) &&
|
|
42
|
+
entry.hooks.some(
|
|
43
|
+
(hook) =>
|
|
44
|
+
isRecord(hook) && typeof hook.command === 'string' && hook.command.includes(GUARD_SCRIPT),
|
|
45
|
+
);
|
|
46
|
+
|
|
47
|
+
interface IParsedFile {
|
|
48
|
+
file: Record<string, unknown>;
|
|
49
|
+
hooks: Record<string, unknown>;
|
|
50
|
+
entries: unknown[];
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const parseFile = (opts: { text: string | undefined }): IParsedFile | { reason: string } => {
|
|
54
|
+
if (opts.text === undefined || opts.text.trim() === '') {
|
|
55
|
+
return { file: {}, hooks: {}, entries: [] };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
try {
|
|
59
|
+
const file: unknown = JSON.parse(opts.text);
|
|
60
|
+
|
|
61
|
+
if (!isRecord(file)) {
|
|
62
|
+
return { reason: 'the hooks file is not a JSON object' };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const hooks = file.hooks === undefined ? {} : file.hooks;
|
|
66
|
+
const entries = isRecord(hooks) && hooks.PreToolUse !== undefined ? hooks.PreToolUse : [];
|
|
67
|
+
|
|
68
|
+
return isRecord(hooks) && Array.isArray(entries)
|
|
69
|
+
? { file, hooks, entries }
|
|
70
|
+
: { reason: 'the hooks file has a hooks or PreToolUse value that is not what Codex reads' };
|
|
71
|
+
} catch (error) {
|
|
72
|
+
return {
|
|
73
|
+
reason: `the hooks file is not JSON (${error instanceof Error ? error.message : String(error)})`,
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
export type TCodexHooksMerge =
|
|
79
|
+
| { ok: true; changed: boolean; text: string }
|
|
80
|
+
| { ok: false; reason: string };
|
|
81
|
+
|
|
82
|
+
/** The hooks file with VULCAN's PreToolUse entry in it, every other entry as the user wrote it. */
|
|
83
|
+
export const mergeCodexHooks = (opts: { text: string | undefined }): TCodexHooksMerge => {
|
|
84
|
+
const parsed = parseFile({ text: opts.text });
|
|
85
|
+
|
|
86
|
+
if ('reason' in parsed) {
|
|
87
|
+
return { ok: false, reason: parsed.reason };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const entry = guardEntry();
|
|
91
|
+
const index = parsed.entries.findIndex((item) => isGuardEntry(item));
|
|
92
|
+
const changed = index === -1 || JSON.stringify(parsed.entries[index]) !== JSON.stringify(entry);
|
|
93
|
+
const entries =
|
|
94
|
+
index === -1
|
|
95
|
+
? [...parsed.entries, entry]
|
|
96
|
+
: parsed.entries.map((item, at) => (at === index ? entry : item));
|
|
97
|
+
|
|
98
|
+
return {
|
|
99
|
+
ok: true,
|
|
100
|
+
changed,
|
|
101
|
+
text: `${JSON.stringify({ ...parsed.file, hooks: { ...parsed.hooks, PreToolUse: entries } }, null, 2)}\n`,
|
|
102
|
+
};
|
|
103
|
+
};
|
|
104
|
+
|
|
105
|
+
export type TCodexHooksRemoval =
|
|
106
|
+
| { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
|
|
107
|
+
| { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
|
|
108
|
+
| { ok: false; reason: string };
|
|
109
|
+
|
|
110
|
+
/** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
|
|
111
|
+
export const removeCodexHooks = (opts: { text: string }): TCodexHooksRemoval => {
|
|
112
|
+
const parsed = parseFile({ text: opts.text });
|
|
113
|
+
|
|
114
|
+
if ('reason' in parsed) {
|
|
115
|
+
return { ok: false, reason: parsed.reason };
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
if (!parsed.entries.some((item) => isGuardEntry(item))) {
|
|
119
|
+
return { ok: true, outcome: RemoveOutcomes.ABSENT };
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
const kept = parsed.entries.filter((item) => !isGuardEntry(item));
|
|
123
|
+
const { PreToolUse: _removed, ...otherEvents } = parsed.hooks;
|
|
124
|
+
const hooks = kept.length > 0 ? { ...otherEvents, PreToolUse: kept } : otherEvents;
|
|
125
|
+
const { hooks: _hooks, ...otherKeys } = parsed.file;
|
|
126
|
+
const file = Object.keys(hooks).length > 0 ? { ...otherKeys, hooks } : otherKeys;
|
|
127
|
+
|
|
128
|
+
return {
|
|
129
|
+
ok: true,
|
|
130
|
+
outcome: RemoveOutcomes.REMOVED,
|
|
131
|
+
text: Object.keys(file).length === 0 ? undefined : `${JSON.stringify(file, null, 2)}\n`,
|
|
132
|
+
};
|
|
133
|
+
};
|
|
@@ -10,6 +10,56 @@ export class AgentScopes {
|
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
+
/** Why an agent's list was chosen: a flag, the local file, the config, a migration, the question, or the default. */
|
|
14
|
+
export class AgentSources {
|
|
15
|
+
static readonly FLAG = 'flag';
|
|
16
|
+
static readonly LOCAL = 'local';
|
|
17
|
+
static readonly CONFIG = 'config';
|
|
18
|
+
static readonly MIGRATION = 'migration';
|
|
19
|
+
static readonly ASKED = 'asked';
|
|
20
|
+
static readonly DEFAULT = 'default';
|
|
21
|
+
|
|
22
|
+
static readonly SCHEME_SET = new Set<string>([
|
|
23
|
+
this.FLAG,
|
|
24
|
+
this.LOCAL,
|
|
25
|
+
this.CONFIG,
|
|
26
|
+
this.MIGRATION,
|
|
27
|
+
this.ASKED,
|
|
28
|
+
this.DEFAULT,
|
|
29
|
+
]);
|
|
30
|
+
|
|
31
|
+
static isValid(value: string): boolean {
|
|
32
|
+
return this.SCHEME_SET.has(value);
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** What taking an entry out of an agent's file found: it was not there, or it was and is gone. */
|
|
37
|
+
export class RemoveOutcomes {
|
|
38
|
+
static readonly ABSENT = 'absent';
|
|
39
|
+
static readonly REMOVED = 'removed';
|
|
40
|
+
|
|
41
|
+
static readonly SCHEME_SET = new Set<string>([this.ABSENT, this.REMOVED]);
|
|
42
|
+
|
|
43
|
+
static isValid(value: string): boolean {
|
|
44
|
+
return this.SCHEME_SET.has(value);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** How a guard reaches an agent that has no Claude-style hook commands: a file the agent loads. */
|
|
49
|
+
export class AgentGuardKinds {
|
|
50
|
+
static readonly EXTENSION = 'extension';
|
|
51
|
+
/** A hooks file that names a command: Antigravity's `.agents/hooks.json`. */
|
|
52
|
+
static readonly HOOKS_JSON = 'hooks-json';
|
|
53
|
+
/** Codex's `.codex/hooks.json`: `hooks.PreToolUse` is a list of matcher entries. */
|
|
54
|
+
static readonly CODEX_HOOKS = 'codex-hooks';
|
|
55
|
+
|
|
56
|
+
static readonly SCHEME_SET = new Set<string>([this.EXTENSION, this.HOOKS_JSON, this.CODEX_HOOKS]);
|
|
57
|
+
|
|
58
|
+
static isValid(value: string): boolean {
|
|
59
|
+
return this.SCHEME_SET.has(value);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
13
63
|
/** The file formats an agent's MCP entry is written in. */
|
|
14
64
|
export class AgentRenderers {
|
|
15
65
|
static readonly MCP_SERVERS = 'mcpServers';
|
|
@@ -35,4 +85,8 @@ export class AgentConstants {
|
|
|
35
85
|
static readonly SHARED_MCP_FILE = '.mcp.json';
|
|
36
86
|
static readonly DEFAULT_AGENT = 'claude';
|
|
37
87
|
static readonly EXAMPLE_LIST = 'claude,omp';
|
|
88
|
+
/** The extension template sync copies for an agent whose `guards` kind is `extension`, under the package's base. */
|
|
89
|
+
static readonly GUARD_EXTENSION_TEMPLATE = 'extensions/vulcan-guards.ts';
|
|
90
|
+
/** The first line of the template: a file that starts with it is sync's, to rewrite or remove. */
|
|
91
|
+
static readonly GUARD_EXTENSION_MARKER = '// Written by `vulcan sync`';
|
|
38
92
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import { AgentConstants, AgentRenderers, AgentScopes } from './constants.ts';
|
|
2
|
+
import { AgentConstants, AgentGuardKinds, AgentRenderers, AgentScopes } from './constants.ts';
|
|
3
3
|
|
|
4
4
|
/** One agent of `base/agents.json`: strict, so a typo in the table is an error, not a silent gap. */
|
|
5
5
|
export const AGENT_ENTRY_SCHEMA = z
|
|
@@ -25,6 +25,15 @@ export const AGENT_ENTRY_SCHEMA = z
|
|
|
25
25
|
}),
|
|
26
26
|
}),
|
|
27
27
|
skills: z.strictObject({ dir: z.string().min(1) }),
|
|
28
|
+
/** How the guards reach this agent; `null` where nothing is wired (Claude has its own hooks in settings.json). */
|
|
29
|
+
guards: z
|
|
30
|
+
.strictObject({
|
|
31
|
+
kind: z.string().refine((value) => AgentGuardKinds.isValid(value), {
|
|
32
|
+
message: `one of: ${[...AgentGuardKinds.SCHEME_SET].join(', ')}`,
|
|
33
|
+
}),
|
|
34
|
+
path: z.string().min(1),
|
|
35
|
+
})
|
|
36
|
+
.nullable(),
|
|
28
37
|
instructionsSurfaced: z.union([z.boolean(), z.literal('partial'), z.null()]),
|
|
29
38
|
notes: z.array(z.string()),
|
|
30
39
|
})
|
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import type { z } from 'zod';
|
|
2
|
+
import type { TConstValue } from '../../common/index.ts';
|
|
3
|
+
import type { AgentSources } from './constants.ts';
|
|
2
4
|
import type { AGENT_ENTRY_SCHEMA } from './schema.ts';
|
|
3
5
|
|
|
4
6
|
export type TAgentEntry = z.infer<typeof AGENT_ENTRY_SCHEMA>;
|
|
@@ -11,7 +13,7 @@ export interface IAgentQuestion {
|
|
|
11
13
|
|
|
12
14
|
export type TAskAgents = (question: IAgentQuestion) => string | null;
|
|
13
15
|
|
|
14
|
-
export type TAgentSource =
|
|
16
|
+
export type TAgentSource = TConstValue<typeof AgentSources>;
|
|
15
17
|
|
|
16
18
|
export type TAgentResolution =
|
|
17
19
|
| {
|
package/src/agents/exclude.ts
CHANGED
|
@@ -48,6 +48,10 @@ export const excludePathsOf = (opts: {
|
|
|
48
48
|
paths.push(`/${AgentConstants.SHARED_MCP_FILE}`);
|
|
49
49
|
}
|
|
50
50
|
|
|
51
|
+
if (entry.guards !== null) {
|
|
52
|
+
paths.push(`/${entry.guards.path}`);
|
|
53
|
+
}
|
|
54
|
+
|
|
51
55
|
if (entry.skills.dir !== CLAUDE_SKILLS_DIRECTORY && !listedSkills.has(entry.skills.dir)) {
|
|
52
56
|
listedSkills.add(entry.skills.dir);
|
|
53
57
|
paths.push(...opts.skillNames.map((name) => `/${entry.skills.dir}/${name}`));
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { RemoveOutcomes } from './common/index.ts';
|
|
2
|
+
|
|
3
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
4
|
+
typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
5
|
+
|
|
6
|
+
/** The key of VULCAN's entry in Antigravity's hooks file: the file maps a hook name to its events. */
|
|
7
|
+
export const GUARD_HOOK_NAME = 'vulcan-guards';
|
|
8
|
+
|
|
9
|
+
/** The Antigravity tools the guards cover, as a matcher (a regular expression over the tool name). */
|
|
10
|
+
const GUARD_MATCHER = 'run_command|write_to_file|replace_file_content|multi_replace_file_content';
|
|
11
|
+
|
|
12
|
+
const ASK_ON_CRASH = JSON.stringify({
|
|
13
|
+
decision: 'ask',
|
|
14
|
+
reason:
|
|
15
|
+
'The VULCAN guard crashed, 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.',
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* The hook command. Antigravity runs it from the folder of the hooks file (`.agents`), so the install is
|
|
20
|
+
* `../node_modules`. A missing package or bun passes with a note; a script that started and crashed asks.
|
|
21
|
+
*/
|
|
22
|
+
const GUARD_COMMAND = [
|
|
23
|
+
'f="$PWD/../node_modules/@venizia/vulcan/base/hooks/antigravity-guards.ts";',
|
|
24
|
+
'if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then',
|
|
25
|
+
'in=$(cat); out=$(printf \'%s\' "$in" | bun "$f"); s=$?;',
|
|
26
|
+
`if [ "$s" -eq 0 ]; then printf '%s' "$out"; exit 0; fi;`,
|
|
27
|
+
`printf '%s\\n' '${ASK_ON_CRASH}'; exit 0; fi;`,
|
|
28
|
+
'cat >/dev/null; echo "vulcan: the guards cannot run: node_modules/@venizia/vulcan or bun is missing - the call passes" >&2;',
|
|
29
|
+
`printf '%s\\n' '{"decision":"allow"}'`,
|
|
30
|
+
].join(' ');
|
|
31
|
+
|
|
32
|
+
/** What the entry holds: one PreToolUse hook on the tools the guards cover. */
|
|
33
|
+
const guardEntry = (): Record<string, unknown> => ({
|
|
34
|
+
PreToolUse: [
|
|
35
|
+
{
|
|
36
|
+
matcher: GUARD_MATCHER,
|
|
37
|
+
hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 60 }],
|
|
38
|
+
},
|
|
39
|
+
],
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
type TParsedHooks = { ok: true; hooks: Record<string, unknown> } | { ok: false; reason: string };
|
|
43
|
+
|
|
44
|
+
const parseHooks = (opts: { text: string | undefined }): TParsedHooks => {
|
|
45
|
+
if (opts.text === undefined || opts.text.trim() === '') {
|
|
46
|
+
return { ok: true, hooks: {} };
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
try {
|
|
50
|
+
const parsed: unknown = JSON.parse(opts.text);
|
|
51
|
+
|
|
52
|
+
return isRecord(parsed)
|
|
53
|
+
? { ok: true, hooks: parsed }
|
|
54
|
+
: { ok: false, reason: 'the hooks file is not a JSON object' };
|
|
55
|
+
} catch (error) {
|
|
56
|
+
return {
|
|
57
|
+
ok: false,
|
|
58
|
+
reason: `the hooks file is not JSON (${error instanceof Error ? error.message : String(error)})`,
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
export type THooksMerge =
|
|
64
|
+
| { ok: true; changed: boolean; text: string }
|
|
65
|
+
| { ok: false; reason: string };
|
|
66
|
+
|
|
67
|
+
/** The hooks file with VULCAN's entry in it, every other hook as the user wrote it. */
|
|
68
|
+
export const mergeGuardHook = (opts: { text: string | undefined }): THooksMerge => {
|
|
69
|
+
const parsed = parseHooks({ text: opts.text });
|
|
70
|
+
|
|
71
|
+
if (!parsed.ok) {
|
|
72
|
+
return parsed;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const entry = guardEntry();
|
|
76
|
+
const changed = JSON.stringify(parsed.hooks[GUARD_HOOK_NAME]) !== JSON.stringify(entry);
|
|
77
|
+
|
|
78
|
+
return {
|
|
79
|
+
ok: true,
|
|
80
|
+
changed,
|
|
81
|
+
text: `${JSON.stringify({ ...parsed.hooks, [GUARD_HOOK_NAME]: entry }, null, 2)}\n`,
|
|
82
|
+
};
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
export type THooksRemoval =
|
|
86
|
+
| { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
|
|
87
|
+
| { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
|
|
88
|
+
| { ok: false; reason: string };
|
|
89
|
+
|
|
90
|
+
/** The hooks file without VULCAN's entry; `text` is undefined when nothing else was in it. */
|
|
91
|
+
export const removeGuardHook = (opts: { text: string }): THooksRemoval => {
|
|
92
|
+
const parsed = parseHooks({ text: opts.text });
|
|
93
|
+
|
|
94
|
+
if (!parsed.ok) {
|
|
95
|
+
return parsed;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
if (!Object.hasOwn(parsed.hooks, GUARD_HOOK_NAME)) {
|
|
99
|
+
return { ok: true, outcome: RemoveOutcomes.ABSENT };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const others = Object.fromEntries(
|
|
103
|
+
Object.entries(parsed.hooks).filter(([name]) => name !== GUARD_HOOK_NAME),
|
|
104
|
+
);
|
|
105
|
+
|
|
106
|
+
return {
|
|
107
|
+
ok: true,
|
|
108
|
+
outcome: RemoveOutcomes.REMOVED,
|
|
109
|
+
text: Object.keys(others).length === 0 ? undefined : `${JSON.stringify(others, null, 2)}\n`,
|
|
110
|
+
};
|
|
111
|
+
};
|
package/src/agents/index.ts
CHANGED
package/src/agents/render.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { join } from 'node:path';
|
|
2
|
+
import { RemoveOutcomes } from './common/index.ts';
|
|
2
3
|
|
|
3
4
|
export const CODEX_BLOCK_START = '# vulcan:atlas:start';
|
|
4
5
|
export const CODEX_BLOCK_END = '# vulcan:atlas:end';
|
|
@@ -174,8 +175,8 @@ export const mergeCodexToml = (opts: { text: string | undefined; root: string })
|
|
|
174
175
|
};
|
|
175
176
|
|
|
176
177
|
export type TRemoveResult =
|
|
177
|
-
| { ok: true; outcome:
|
|
178
|
-
| { ok: true; outcome:
|
|
178
|
+
| { ok: true; outcome: typeof RemoveOutcomes.ABSENT }
|
|
179
|
+
| { ok: true; outcome: typeof RemoveOutcomes.REMOVED; text: string | undefined }
|
|
179
180
|
| { ok: false; reason: string };
|
|
180
181
|
|
|
181
182
|
/**
|
|
@@ -198,7 +199,7 @@ export const removeMcpEntry = (opts: { text: string; key: string }): TRemoveResu
|
|
|
198
199
|
const servers = document[opts.key];
|
|
199
200
|
|
|
200
201
|
if (!isRecord(servers) || !Object.hasOwn(servers, SERVER_NAME)) {
|
|
201
|
-
return { ok: true, outcome:
|
|
202
|
+
return { ok: true, outcome: RemoveOutcomes.ABSENT };
|
|
202
203
|
}
|
|
203
204
|
|
|
204
205
|
if (!isOwnEntry({ entry: servers[SERVER_NAME] })) {
|
|
@@ -219,7 +220,7 @@ export const removeMcpEntry = (opts: { text: string; key: string }): TRemoveResu
|
|
|
219
220
|
|
|
220
221
|
return {
|
|
221
222
|
ok: true,
|
|
222
|
-
outcome:
|
|
223
|
+
outcome: RemoveOutcomes.REMOVED,
|
|
223
224
|
text: onlyEmptyInputs ? undefined : `${JSON.stringify(remaining, null, 2)}\n`,
|
|
224
225
|
};
|
|
225
226
|
};
|
package/src/agents/resolve.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { existsSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
|
-
import { AgentConstants } from './common/index.ts';
|
|
3
|
+
import { AgentConstants, AgentSources } from './common/index.ts';
|
|
4
4
|
import type { TAgentResolution, TAskAgents } from './common/index.ts';
|
|
5
5
|
import { readLocalChoice } from './local.ts';
|
|
6
6
|
import { agentIds } from './table.ts';
|
|
@@ -40,7 +40,10 @@ export const parseAgentList = (opts: { value: string }): TParsed => {
|
|
|
40
40
|
return { ok: true, agents: known.filter((id) => words.includes(id)) };
|
|
41
41
|
};
|
|
42
42
|
|
|
43
|
-
const fromList = (opts: {
|
|
43
|
+
const fromList = (opts: {
|
|
44
|
+
value: string;
|
|
45
|
+
source: typeof AgentSources.FLAG | typeof AgentSources.ASKED;
|
|
46
|
+
}): TAgentResolution => {
|
|
44
47
|
const parsed = parseAgentList({ value: opts.value });
|
|
45
48
|
|
|
46
49
|
return parsed.ok
|
|
@@ -83,11 +86,11 @@ export const resolveAgents = (opts: {
|
|
|
83
86
|
? {
|
|
84
87
|
ok: true,
|
|
85
88
|
agents: stored.agents ?? opts.detected,
|
|
86
|
-
source:
|
|
89
|
+
source: AgentSources.ASKED,
|
|
87
90
|
writeLocal: true,
|
|
88
91
|
hint: undefined,
|
|
89
92
|
}
|
|
90
|
-
: fromList({ value: answer, source:
|
|
93
|
+
: fromList({ value: answer, source: AgentSources.ASKED });
|
|
91
94
|
};
|
|
92
95
|
|
|
93
96
|
if (opts.flag === '') {
|
|
@@ -100,25 +103,37 @@ export const resolveAgents = (opts: {
|
|
|
100
103
|
}
|
|
101
104
|
|
|
102
105
|
if (opts.flag !== undefined) {
|
|
103
|
-
return fromList({ value: opts.flag, source:
|
|
106
|
+
return fromList({ value: opts.flag, source: AgentSources.FLAG });
|
|
104
107
|
}
|
|
105
108
|
|
|
106
109
|
if (stored.agents !== undefined) {
|
|
107
|
-
return {
|
|
110
|
+
return {
|
|
111
|
+
ok: true,
|
|
112
|
+
agents: stored.agents,
|
|
113
|
+
source: AgentSources.LOCAL,
|
|
114
|
+
writeLocal: false,
|
|
115
|
+
hint: undefined,
|
|
116
|
+
};
|
|
108
117
|
}
|
|
109
118
|
|
|
110
119
|
if (opts.configAgents !== undefined) {
|
|
111
120
|
return {
|
|
112
121
|
ok: true,
|
|
113
122
|
agents: agentIds().filter((id) => opts.configAgents?.includes(id)),
|
|
114
|
-
source:
|
|
123
|
+
source: AgentSources.CONFIG,
|
|
115
124
|
writeLocal: true,
|
|
116
125
|
hint: undefined,
|
|
117
126
|
};
|
|
118
127
|
}
|
|
119
128
|
|
|
120
129
|
if (PROJECT_FILES.some((file) => existsSync(join(opts.root, file)))) {
|
|
121
|
-
return {
|
|
130
|
+
return {
|
|
131
|
+
ok: true,
|
|
132
|
+
agents: ['claude'],
|
|
133
|
+
source: AgentSources.MIGRATION,
|
|
134
|
+
writeLocal: true,
|
|
135
|
+
hint: undefined,
|
|
136
|
+
};
|
|
122
137
|
}
|
|
123
138
|
|
|
124
139
|
if (opts.interactive) {
|
|
@@ -128,7 +143,7 @@ export const resolveAgents = (opts: {
|
|
|
128
143
|
return {
|
|
129
144
|
ok: true,
|
|
130
145
|
agents: [AgentConstants.DEFAULT_AGENT],
|
|
131
|
-
source:
|
|
146
|
+
source: AgentSources.DEFAULT,
|
|
132
147
|
writeLocal: false,
|
|
133
148
|
hint: NO_TTY_HINT,
|
|
134
149
|
};
|
|
@@ -1,3 +1,15 @@
|
|
|
1
|
+
/** What a package of the project is: an app, or a shared package (a lib) a preset made. */
|
|
2
|
+
export class PackageKinds {
|
|
3
|
+
static readonly APP = 'app';
|
|
4
|
+
static readonly LIB = 'lib';
|
|
5
|
+
|
|
6
|
+
static readonly SCHEME_SET = new Set<string>([this.APP, this.LIB]);
|
|
7
|
+
|
|
8
|
+
static isValid(value: string): boolean {
|
|
9
|
+
return this.SCHEME_SET.has(value);
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
|
|
1
13
|
/** Config file extensions, in lookup order. */
|
|
2
14
|
export class ConfigExtensions {
|
|
3
15
|
static readonly TS = 'ts';
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { TConstValue } from '../../common/index.ts';
|
|
2
|
-
import type { CodingAgents, ConfigExtensions, HookEvents } from './constants.ts';
|
|
2
|
+
import type { CodingAgents, ConfigExtensions, HookEvents, PackageKinds } from './constants.ts';
|
|
3
3
|
|
|
4
4
|
export type TConfigExtension = TConstValue<typeof ConfigExtensions>;
|
|
5
5
|
export type TCodingAgent = TConstValue<typeof CodingAgents>;
|
|
6
6
|
export type THookEvent = TConstValue<typeof HookEvents>;
|
|
7
|
+
export type TPackageKind = TConstValue<typeof PackageKinds>;
|