@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
|
@@ -8,15 +8,61 @@ export class GuardDecisions {
|
|
|
8
8
|
}
|
|
9
9
|
}
|
|
10
10
|
|
|
11
|
+
/** What the package guard says about a hand-made package: refuse where a `vulcan add` command exists, else warn. */
|
|
12
|
+
export class PackageVerdictKinds {
|
|
13
|
+
static readonly DENY = GuardDecisions.DENY;
|
|
14
|
+
static readonly WARN = 'warn';
|
|
15
|
+
|
|
16
|
+
static readonly SCHEME_SET = new Set<string>([this.DENY, this.WARN]);
|
|
17
|
+
|
|
18
|
+
static isValid(value: string): boolean {
|
|
19
|
+
return this.SCHEME_SET.has(value);
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** What git says about a script a project trusts: only `TRUSTED` skips the script checks of guard-writes. */
|
|
24
|
+
export class TrustStates {
|
|
25
|
+
static readonly TRUSTED = 'trusted';
|
|
26
|
+
static readonly MISSING = 'missing';
|
|
27
|
+
static readonly UNTRACKED = 'untracked';
|
|
28
|
+
static readonly UNCOMMITTED = 'uncommitted';
|
|
29
|
+
static readonly MODIFIED = 'modified';
|
|
30
|
+
static readonly SYMLINK = 'symlink';
|
|
31
|
+
static readonly UNKNOWN = 'unknown';
|
|
32
|
+
|
|
33
|
+
static readonly SCHEME_SET = new Set<string>([
|
|
34
|
+
this.TRUSTED,
|
|
35
|
+
this.MISSING,
|
|
36
|
+
this.UNTRACKED,
|
|
37
|
+
this.UNCOMMITTED,
|
|
38
|
+
this.MODIFIED,
|
|
39
|
+
this.SYMLINK,
|
|
40
|
+
this.UNKNOWN,
|
|
41
|
+
]);
|
|
42
|
+
|
|
43
|
+
static isValid(value: string): boolean {
|
|
44
|
+
return this.SCHEME_SET.has(value);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
11
48
|
export class HookConstants {
|
|
12
49
|
/** `ask` until the transcript shows the guard does not over-fire; a false positive costs one keystroke. */
|
|
13
50
|
static readonly GUARD_DECISION = GuardDecisions.ASK;
|
|
14
51
|
static readonly PRE_TOOL_USE = 'PreToolUse';
|
|
52
|
+
/** Cursor sets it for every hook it runs, including the Claude hooks it imports; Claude Code never does. */
|
|
53
|
+
static readonly CURSOR_PROJECT_DIR_ENV = 'CURSOR_PROJECT_DIR';
|
|
15
54
|
static readonly SUBAGENT_START = 'SubagentStart';
|
|
16
55
|
/** `git` and `gh` queries the guards make; a slow one is dropped and the command passes. */
|
|
17
56
|
static readonly QUERY_TIMEOUT_MS = 5000;
|
|
57
|
+
/** The `git` and `gh` queries one command line may make; past it the guard asks instead of querying on. */
|
|
58
|
+
static readonly MAX_QUERIES = 4;
|
|
18
59
|
/** Branches no agent deletes or force-pushes (V-W-06). */
|
|
19
60
|
static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
|
|
61
|
+
/**
|
|
62
|
+
* Where a session's temporary files go, from the project root: `ProjectLayout.LOCAL_DIRECTORY` and `tmp`.
|
|
63
|
+
* Spelt out here because the blocking hooks import nothing that reads the package (a test holds the two equal).
|
|
64
|
+
*/
|
|
65
|
+
static readonly PROJECT_TMP = '.agents/local/tmp';
|
|
20
66
|
/** Set to `off` to switch the guards off for a session; the hooks then pass every call. */
|
|
21
67
|
static readonly KILL_SWITCH_ENV = 'VULCAN_GUARDS';
|
|
22
68
|
static readonly KILL_SWITCH_OFF = 'off';
|
|
@@ -1,7 +1,15 @@
|
|
|
1
1
|
import type { TConstValue } from '../../common/index.ts';
|
|
2
|
-
import type { GuardDecisions } from './constants.ts';
|
|
2
|
+
import type { GuardDecisions, PackageVerdictKinds, TrustStates } from './constants.ts';
|
|
3
3
|
|
|
4
4
|
export type TGuardDecision = TConstValue<typeof GuardDecisions>;
|
|
5
|
+
export type TPackageVerdictKind = TConstValue<typeof PackageVerdictKinds>;
|
|
6
|
+
export type TTrustState = TConstValue<typeof TrustStates>;
|
|
7
|
+
|
|
8
|
+
/** Whether a listed trusted script may skip the script checks, and if not, why - in words an ask can show. */
|
|
9
|
+
export interface IScriptTrust {
|
|
10
|
+
state: TTrustState;
|
|
11
|
+
reason: string;
|
|
12
|
+
}
|
|
5
13
|
|
|
6
14
|
export interface IWriteCheck {
|
|
7
15
|
rule: string;
|
package/src/hooks/decision.ts
CHANGED
|
@@ -1,14 +1,56 @@
|
|
|
1
|
-
import { HookConstants } from './common/index.ts';
|
|
1
|
+
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
2
2
|
import type { TGuardDecision } from './common/index.ts';
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
export const buildToolDecision = (opts: { decision: TGuardDecision; reason: string[] }) => ({
|
|
4
|
+
export interface IDecisionOutput {
|
|
6
5
|
hookSpecificOutput: {
|
|
7
|
-
hookEventName:
|
|
8
|
-
permissionDecision:
|
|
9
|
-
permissionDecisionReason:
|
|
10
|
-
}
|
|
11
|
-
}
|
|
6
|
+
hookEventName: string;
|
|
7
|
+
permissionDecision: string;
|
|
8
|
+
permissionDecisionReason: string;
|
|
9
|
+
};
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The decision as every host that reads our hooks understands it. Claude Code and Cursor read
|
|
14
|
+
* \`hookSpecificOutput\`; Copilot documents the same two fields at the top level, so they are written there
|
|
15
|
+
* too (Claude Code ignores them: checked). Cursor does not enforce an \`ask\` on a tool call, so where it
|
|
16
|
+
* says it is running the hook (\`CURSOR_PROJECT_DIR\`) an ask is a deny that says why.
|
|
17
|
+
*/
|
|
18
|
+
export const forHost = (opts: {
|
|
19
|
+
output: IDecisionOutput;
|
|
20
|
+
env?: Record<string, string | undefined>;
|
|
21
|
+
}) => {
|
|
22
|
+
const specific = opts.output.hookSpecificOutput;
|
|
23
|
+
const env = opts.env ?? process.env;
|
|
24
|
+
const isCursorAsk =
|
|
25
|
+
specific.permissionDecision === GuardDecisions.ASK &&
|
|
26
|
+
env[HookConstants.CURSOR_PROJECT_DIR_ENV] !== undefined;
|
|
27
|
+
const decision = isCursorAsk ? GuardDecisions.DENY : specific.permissionDecision;
|
|
28
|
+
const reason = isCursorAsk
|
|
29
|
+
? `${specific.permissionDecisionReason}\n(Cursor cannot ask about a tool call: hand this to the owner)`
|
|
30
|
+
: specific.permissionDecisionReason;
|
|
31
|
+
|
|
32
|
+
return {
|
|
33
|
+
hookSpecificOutput: {
|
|
34
|
+
...specific,
|
|
35
|
+
permissionDecision: decision,
|
|
36
|
+
permissionDecisionReason: reason,
|
|
37
|
+
},
|
|
38
|
+
permissionDecision: decision,
|
|
39
|
+
permissionDecisionReason: reason,
|
|
40
|
+
};
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
/** The PreToolUse answer Claude Code reads from stdout: the decision and why, shown to the human or to the model. */
|
|
44
|
+
export const buildToolDecision = (opts: { decision: TGuardDecision; reason: string[] }) =>
|
|
45
|
+
forHost({
|
|
46
|
+
output: {
|
|
47
|
+
hookSpecificOutput: {
|
|
48
|
+
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
49
|
+
permissionDecision: opts.decision,
|
|
50
|
+
permissionDecisionReason: opts.reason.join('\n'),
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
});
|
|
12
54
|
|
|
13
55
|
/** Whether the session switched the guards off (`VULCAN_GUARDS=off`): every call then passes. */
|
|
14
56
|
export const guardsAreOff = (opts: { env?: Record<string, string | undefined> } = {}): boolean =>
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { spawnSync } from 'node:child_process';
|
|
2
|
-
import { basenameOf,
|
|
2
|
+
import { basenameOf, parseShellChecked, programOf } from './shell.ts';
|
|
3
3
|
import type { ISimpleCommand } from './shell.ts';
|
|
4
4
|
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
5
5
|
import type { IGitHit, IGitRunner } from './common/index.ts';
|
|
6
|
+
import { matchesBranch } from './project-guards.ts';
|
|
6
7
|
|
|
7
8
|
/** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
|
|
8
9
|
export const runQuery: IGitRunner = (opts) => {
|
|
@@ -57,6 +58,7 @@ const inspectPush = (opts: {
|
|
|
57
58
|
rest: string[];
|
|
58
59
|
cwd: string | undefined;
|
|
59
60
|
run: IGitRunner;
|
|
61
|
+
askPush: string[];
|
|
60
62
|
}): IGitHit[] => {
|
|
61
63
|
const flags = opts.rest.filter((word) => word.startsWith('-') && word !== '-');
|
|
62
64
|
const positional = opts.rest.filter((word) => !word.startsWith('-'));
|
|
@@ -97,6 +99,21 @@ const inspectPush = (opts: {
|
|
|
97
99
|
}
|
|
98
100
|
}
|
|
99
101
|
|
|
102
|
+
// A target the project lists asks even for a plain push; a hit already made says the push needs a human.
|
|
103
|
+
if (hits.length === 0 && !deleting) {
|
|
104
|
+
for (const name of targets) {
|
|
105
|
+
const branch = name.replace(/^\+/, '').replace(/^refs\/heads\//, '');
|
|
106
|
+
|
|
107
|
+
if (matchesBranch({ name: branch, patterns: opts.askPush })) {
|
|
108
|
+
hits.push({
|
|
109
|
+
decision: GuardDecisions.ASK,
|
|
110
|
+
rule: 'V-W-06',
|
|
111
|
+
message: `pushing to '${branch}', a target this project lists in guard.git.askPush`,
|
|
112
|
+
});
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
100
117
|
if (flags.includes('--mirror')) {
|
|
101
118
|
hits.push({
|
|
102
119
|
decision: GuardDecisions.ASK,
|
|
@@ -229,6 +246,7 @@ const inspectOne = (opts: {
|
|
|
229
246
|
command: ISimpleCommand;
|
|
230
247
|
cwd: string | undefined;
|
|
231
248
|
run: IGitRunner;
|
|
249
|
+
askPush: string[];
|
|
232
250
|
}): IGitHit[] => {
|
|
233
251
|
const program = programOf({ command: opts.command });
|
|
234
252
|
const name = basenameOf({ word: program.name });
|
|
@@ -245,7 +263,7 @@ const inspectOne = (opts: {
|
|
|
245
263
|
const cwd = call.dir ?? opts.cwd;
|
|
246
264
|
|
|
247
265
|
if (call.sub === 'push') {
|
|
248
|
-
return inspectPush({ rest: call.rest, cwd, run: opts.run });
|
|
266
|
+
return inspectPush({ rest: call.rest, cwd, run: opts.run, askPush: opts.askPush });
|
|
249
267
|
}
|
|
250
268
|
|
|
251
269
|
if (call.sub === 'branch') {
|
|
@@ -282,7 +300,48 @@ export const inspectGit = (opts: {
|
|
|
282
300
|
command: string;
|
|
283
301
|
cwd: string | undefined;
|
|
284
302
|
run?: IGitRunner;
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
303
|
+
/** Branches (names, `*` allowed) a plain `git push` asks about: `guard.git.askPush`. */
|
|
304
|
+
askPush?: string[];
|
|
305
|
+
}): IGitHit[] => {
|
|
306
|
+
const parsed = parseShellChecked({ command: opts.command });
|
|
307
|
+
const run = opts.run ?? runQuery;
|
|
308
|
+
let queries = 0;
|
|
309
|
+
let isCapped = false;
|
|
310
|
+
|
|
311
|
+
// Every query is a process and can take seconds: a line may make a few, and asks past them.
|
|
312
|
+
const limited: IGitRunner = (call) => {
|
|
313
|
+
queries += 1;
|
|
314
|
+
|
|
315
|
+
if (queries > HookConstants.MAX_QUERIES) {
|
|
316
|
+
isCapped = true;
|
|
317
|
+
|
|
318
|
+
return undefined;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
return run(call);
|
|
322
|
+
};
|
|
323
|
+
const hits = parsed.commands.flatMap((command) =>
|
|
324
|
+
inspectOne({ command, cwd: opts.cwd, run: limited, askPush: opts.askPush ?? [] }),
|
|
288
325
|
);
|
|
326
|
+
|
|
327
|
+
// Part of the line was not read: never an allow.
|
|
328
|
+
if (parsed.isOverBudget) {
|
|
329
|
+
hits.push({
|
|
330
|
+
decision: GuardDecisions.ASK,
|
|
331
|
+
rule: 'V-W-06',
|
|
332
|
+
message:
|
|
333
|
+
'this command line is larger, or nests deeper, than the guard reads, so it could not be checked',
|
|
334
|
+
});
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
if (isCapped) {
|
|
338
|
+
hits.push({
|
|
339
|
+
decision: GuardDecisions.ASK,
|
|
340
|
+
rule: 'V-W-06',
|
|
341
|
+
message:
|
|
342
|
+
'this command line needs more git or gh queries than the guard runs, so part of it could not be checked',
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
return hits;
|
|
347
|
+
};
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
import { isAbsolute, join, normalize } from 'node:path';
|
|
2
2
|
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
3
3
|
import type { IManifestHookInput } from './common/index.ts';
|
|
4
|
+
import { forHost } from './decision.ts';
|
|
5
|
+
|
|
6
|
+
/** The shell tool under the names the hosts give it: Cursor's `Shell`, and a lower-case `bash`. */
|
|
7
|
+
const SHELL_NAMES = new Set(['Shell', 'shell', 'bash']);
|
|
4
8
|
|
|
5
9
|
export const MANIFEST_BLOCK_MESSAGE =
|
|
6
10
|
'vulcan.manifest.json is generated - edit .configs/vulcan.config.* and run `vulcan sync`';
|
|
@@ -30,6 +34,13 @@ const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unk
|
|
|
30
34
|
const toText = (opts: { value: unknown }): string | undefined =>
|
|
31
35
|
typeof opts.value === 'string' && opts.value !== '' ? opts.value : undefined;
|
|
32
36
|
|
|
37
|
+
/** The tool name, with the shell tool of another host read as Claude's `Bash`. */
|
|
38
|
+
const toolOf = (opts: { value: unknown }): string | undefined => {
|
|
39
|
+
const name = toText(opts);
|
|
40
|
+
|
|
41
|
+
return name !== undefined && SHELL_NAMES.has(name) ? BASH_TOOL : name;
|
|
42
|
+
};
|
|
43
|
+
|
|
33
44
|
/** The tool call from the hook's JSON; `undefined` when it is not what Claude Code sends. */
|
|
34
45
|
export const parseManifestHookInput = (opts: { text: string }): IManifestHookInput | undefined => {
|
|
35
46
|
let payload: unknown;
|
|
@@ -53,7 +64,7 @@ export const parseManifestHookInput = (opts: { text: string }): IManifestHookInp
|
|
|
53
64
|
// The wire names are snake_case; they stay behind string-literal access here, at the boundary (V-C-14).
|
|
54
65
|
const toolInput = { value: holder.value['tool_input'] };
|
|
55
66
|
const input = isRecord(toolInput) ? toolInput.value : {};
|
|
56
|
-
const tool =
|
|
67
|
+
const tool = toolOf({ value: holder.value['tool_name'] });
|
|
57
68
|
|
|
58
69
|
return tool === undefined
|
|
59
70
|
? undefined
|
|
@@ -83,10 +94,13 @@ export const inspectManifestWrite = (opts: { input: IManifestHookInput }): boole
|
|
|
83
94
|
return normalize(absolute).endsWith(MANIFEST_SUFFIX);
|
|
84
95
|
};
|
|
85
96
|
|
|
86
|
-
export const buildManifestDecision = () =>
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
97
|
+
export const buildManifestDecision = () =>
|
|
98
|
+
forHost({
|
|
99
|
+
output: {
|
|
100
|
+
hookSpecificOutput: {
|
|
101
|
+
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
102
|
+
permissionDecision: GuardDecisions.DENY,
|
|
103
|
+
permissionDecisionReason: MANIFEST_BLOCK_MESSAGE,
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
});
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { lstatSync, readlinkSync, realpathSync } from 'node:fs';
|
|
2
2
|
import { tmpdir } from 'node:os';
|
|
3
3
|
import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
|
|
4
|
-
import { basenameOf,
|
|
4
|
+
import { basenameOf, parseShellChecked, programOf } from './shell.ts';
|
|
5
5
|
import type { ISimpleCommand } from './shell.ts';
|
|
6
6
|
import { HookConstants } from './common/index.ts';
|
|
7
|
+
import { projectTmpOf } from './project-tmp.ts';
|
|
7
8
|
import type { IManifestHookInput, IOutsideHit } from './common/index.ts';
|
|
8
9
|
|
|
9
10
|
const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
|
|
@@ -238,7 +239,7 @@ const gitTargets = (opts: { rest: string[]; base: string; dir: string | undefine
|
|
|
238
239
|
};
|
|
239
240
|
|
|
240
241
|
/** The words a simple command would create or write, with a name for what writes them. */
|
|
241
|
-
const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] => {
|
|
242
|
+
const targetsOf = (opts: { command: ISimpleCommand; base: string; tmp: string }): ITarget[] => {
|
|
242
243
|
const program = programOf({ command: opts.command });
|
|
243
244
|
const name = basenameOf({ word: program.name });
|
|
244
245
|
const { args } = program;
|
|
@@ -314,7 +315,7 @@ const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] =
|
|
|
314
315
|
if (directory !== undefined) {
|
|
315
316
|
add(directory, 'mktemp creates a temporary file');
|
|
316
317
|
} else if (inTmpdir || template === undefined) {
|
|
317
|
-
add(
|
|
318
|
+
add(opts.tmp, 'mktemp creates a file in the system temp directory');
|
|
318
319
|
} else {
|
|
319
320
|
add(template, 'mktemp creates a temporary file');
|
|
320
321
|
}
|
|
@@ -327,6 +328,21 @@ const targetsOf = (opts: { command: ISimpleCommand; base: string }): ITarget[] =
|
|
|
327
328
|
return targets;
|
|
328
329
|
};
|
|
329
330
|
|
|
331
|
+
/**
|
|
332
|
+
* The folder a bare `mktemp` uses in the command: the `TMPDIR` this hook runs with (Claude Code started
|
|
333
|
+
* with the launch file or the variables), else the project's own folder when Claude Code's session-start
|
|
334
|
+
* hook exports it (`CLAUDE_PROJECT_DIR` is set only by Claude Code), else the system temp directory.
|
|
335
|
+
*/
|
|
336
|
+
const commandTmpdirOf = (opts: { env: TEnvironment; projectRoot: string }): string => {
|
|
337
|
+
if (opts.env.TMPDIR !== undefined && opts.env.TMPDIR !== '') {
|
|
338
|
+
return opts.env.TMPDIR;
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
return opts.env.CLAUDE_PROJECT_DIR === undefined
|
|
342
|
+
? tmpdir()
|
|
343
|
+
: projectTmpOf({ root: opts.projectRoot });
|
|
344
|
+
};
|
|
345
|
+
|
|
330
346
|
/**
|
|
331
347
|
* Every file, worktree, clone or temp file `input` would create outside the project. Files a package
|
|
332
348
|
* manager, a runtime or the agent tool manage themselves are allowed (`toolOwnedPaths`, extending the
|
|
@@ -350,6 +366,7 @@ export const inspectOutside = (opts: {
|
|
|
350
366
|
env,
|
|
351
367
|
});
|
|
352
368
|
const start = opts.input.cwd ?? opts.projectRoot;
|
|
369
|
+
const tmp = commandTmpdirOf({ env, projectRoot: opts.projectRoot });
|
|
353
370
|
const targets: ITarget[] = [];
|
|
354
371
|
|
|
355
372
|
if (FILE_TOOLS.has(opts.input.tool) && opts.input.filePath !== undefined) {
|
|
@@ -360,10 +377,16 @@ export const inspectOutside = (opts: {
|
|
|
360
377
|
});
|
|
361
378
|
}
|
|
362
379
|
|
|
380
|
+
let isUnread = false;
|
|
381
|
+
|
|
363
382
|
if (opts.input.command !== undefined) {
|
|
364
383
|
let base = start;
|
|
365
384
|
|
|
366
|
-
|
|
385
|
+
const parsed = parseShellChecked({ command: opts.input.command });
|
|
386
|
+
|
|
387
|
+
isUnread = parsed.isOverBudget;
|
|
388
|
+
|
|
389
|
+
for (const command of parsed.commands) {
|
|
367
390
|
const program = programOf({ command });
|
|
368
391
|
|
|
369
392
|
if (basenameOf({ word: program.name }) === 'cd') {
|
|
@@ -375,11 +398,20 @@ export const inspectOutside = (opts: {
|
|
|
375
398
|
continue;
|
|
376
399
|
}
|
|
377
400
|
|
|
378
|
-
targets.push(...targetsOf({ command, base }));
|
|
401
|
+
targets.push(...targetsOf({ command, base, tmp }));
|
|
379
402
|
}
|
|
380
403
|
}
|
|
381
404
|
|
|
382
|
-
|
|
405
|
+
// Part of the line was not read: never an allow.
|
|
406
|
+
const hits: IOutsideHit[] = isUnread
|
|
407
|
+
? [
|
|
408
|
+
{
|
|
409
|
+
path: '(the command line)',
|
|
410
|
+
message:
|
|
411
|
+
'this command line is larger, or nests deeper, than the guard reads, so it could not be checked',
|
|
412
|
+
},
|
|
413
|
+
]
|
|
414
|
+
: [];
|
|
383
415
|
|
|
384
416
|
for (const target of targets) {
|
|
385
417
|
const expanded = expandPath({ word: target.word, home, env });
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { basename, dirname, isAbsolute, join, normalize, relative, sep } from 'node:path';
|
|
3
|
-
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
4
|
-
import type { IManifestHookInput } from './common/index.ts';
|
|
3
|
+
import { GuardDecisions, HookConstants, PackageVerdictKinds } from './common/index.ts';
|
|
4
|
+
import type { IManifestHookInput, TPackageVerdictKind } from './common/index.ts';
|
|
5
|
+
import { forHost } from './decision.ts';
|
|
5
6
|
import { LayoutKeys, validLayoutFolders } from '../common/layout-folder.ts';
|
|
6
7
|
|
|
7
8
|
const MANIFEST_FILE = '.agents/vulcan.manifest.json';
|
|
@@ -12,7 +13,7 @@ const NO_HAND_WRITING = 'do not hand-write package.json, tsconfig or scripts';
|
|
|
12
13
|
|
|
13
14
|
export interface IPackageVerdict {
|
|
14
15
|
/** `deny` only when a real `vulcan add` command exists for the folder; otherwise `warn`. */
|
|
15
|
-
kind:
|
|
16
|
+
kind: TPackageVerdictKind;
|
|
16
17
|
message: string;
|
|
17
18
|
}
|
|
18
19
|
|
|
@@ -183,13 +184,13 @@ export const inspectPackageWrite = (opts: {
|
|
|
183
184
|
|
|
184
185
|
if (commands.length > 0) {
|
|
185
186
|
return {
|
|
186
|
-
kind:
|
|
187
|
+
kind: PackageVerdictKinds.DENY,
|
|
187
188
|
message: `${created.folder}/${created.name} is a new ${what}: create it with a preset, not by hand - run ${commands.join(' or ')} (ask atlas \`presets\` for the choice); ${NO_HAND_WRITING}`,
|
|
188
189
|
};
|
|
189
190
|
}
|
|
190
191
|
|
|
191
192
|
return {
|
|
192
|
-
kind:
|
|
193
|
+
kind: PackageVerdictKinds.WARN,
|
|
193
194
|
message:
|
|
194
195
|
project.presets.length === 0
|
|
195
196
|
? `${created.folder}/${created.name} looks like a new ${what} and this project recorded no preset: ask the user which preset to use (\`vulcan add --preset <name|file:path> --app <name>\`, --lib <name> for a shared package); ${NO_HAND_WRITING}`
|
|
@@ -198,14 +199,16 @@ export const inspectPackageWrite = (opts: {
|
|
|
198
199
|
};
|
|
199
200
|
|
|
200
201
|
export const buildPackageDecision = (opts: { verdict: IPackageVerdict }) =>
|
|
201
|
-
opts.verdict.kind ===
|
|
202
|
-
? {
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
202
|
+
opts.verdict.kind === PackageVerdictKinds.DENY
|
|
203
|
+
? forHost({
|
|
204
|
+
output: {
|
|
205
|
+
hookSpecificOutput: {
|
|
206
|
+
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
207
|
+
permissionDecision: GuardDecisions.DENY,
|
|
208
|
+
permissionDecisionReason: opts.verdict.message,
|
|
209
|
+
},
|
|
207
210
|
},
|
|
208
|
-
}
|
|
211
|
+
})
|
|
209
212
|
: {
|
|
210
213
|
hookSpecificOutput: {
|
|
211
214
|
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { isAbsolute, join } from 'node:path';
|
|
3
3
|
import { HookConstants } from './common/index.ts';
|
|
4
|
+
import { TrustStates } from './common/index.ts';
|
|
4
5
|
import type { IHookCommand, IWriteCheck, IWriteHit } from './common/index.ts';
|
|
6
|
+
import { commandTextsOf } from './command-view.ts';
|
|
7
|
+
import { forHost } from './decision.ts';
|
|
8
|
+
import type { IProjectCommandCheck } from './project-guards.ts';
|
|
9
|
+
import { listedScriptOf, trustOf } from './trusted-scripts.ts';
|
|
5
10
|
|
|
6
11
|
const MUTATING_VERB = '(?:POST|PUT|PATCH|DELETE)';
|
|
7
12
|
|
|
@@ -73,24 +78,67 @@ const readScript = (opts: { target: string; cwd: string }): string | undefined =
|
|
|
73
78
|
return existsSync(path) ? readFileSync(path, 'utf8') : undefined;
|
|
74
79
|
};
|
|
75
80
|
|
|
76
|
-
/**
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
81
|
+
/**
|
|
82
|
+
* Every reason `command` looks like a write the base rules reserve for a human (V-W-02, V-W-03).
|
|
83
|
+
* `trust` lists the scripts the project vouches for (`guard.writes.trustedScripts`, repo-relative, under
|
|
84
|
+
* `root`): a listed script that is tracked and identical to HEAD skips the script checks only. The checks
|
|
85
|
+
* on the command line itself always run, and a listed script that git says changed is checked like any other.
|
|
86
|
+
*/
|
|
87
|
+
export const inspectCommand = (opts: {
|
|
88
|
+
command: string;
|
|
89
|
+
cwd: string;
|
|
90
|
+
trust?: { root: string; scripts: string[] };
|
|
91
|
+
/** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
|
|
92
|
+
extra?: IProjectCommandCheck[];
|
|
93
|
+
}): IWriteHit[] => {
|
|
94
|
+
// The patterns run on what the command runs, not on its text: a heredoc written to a file, the pattern
|
|
95
|
+
// of an `rg` and a commit message are data.
|
|
96
|
+
const texts = commandTextsOf({ command: opts.command, withMessages: true });
|
|
97
|
+
const checks: IWriteCheck[] = [
|
|
98
|
+
...COMMAND_CHECKS,
|
|
99
|
+
...(opts.extra ?? []).map((check) => ({
|
|
100
|
+
rule: check.rule,
|
|
101
|
+
what: `${check.what} (this project's pattern)`,
|
|
102
|
+
pattern: check.pattern,
|
|
103
|
+
})),
|
|
104
|
+
];
|
|
105
|
+
const hits: IWriteHit[] = checks
|
|
106
|
+
.filter((check) => texts.some((text) => check.pattern.test(text)))
|
|
107
|
+
.map((check) => ({
|
|
80
108
|
rule: check.rule,
|
|
81
109
|
message: check.what,
|
|
82
|
-
})
|
|
83
|
-
);
|
|
110
|
+
}));
|
|
84
111
|
|
|
85
|
-
for (const target of extractScriptTargets({ command:
|
|
112
|
+
for (const target of extractScriptTargets({ command: texts.join('\n') })) {
|
|
86
113
|
const source = readScript({ target, cwd: opts.cwd });
|
|
87
114
|
|
|
88
115
|
if (source === undefined) {
|
|
89
116
|
continue;
|
|
90
117
|
}
|
|
91
118
|
|
|
119
|
+
const listed =
|
|
120
|
+
opts.trust === undefined
|
|
121
|
+
? undefined
|
|
122
|
+
: listedScriptOf({
|
|
123
|
+
target,
|
|
124
|
+
cwd: opts.cwd,
|
|
125
|
+
root: opts.trust.root,
|
|
126
|
+
scripts: opts.trust.scripts,
|
|
127
|
+
});
|
|
128
|
+
const trust =
|
|
129
|
+
listed === undefined || opts.trust === undefined
|
|
130
|
+
? undefined
|
|
131
|
+
: trustOf({ root: opts.trust.root, script: listed });
|
|
132
|
+
|
|
133
|
+
if (trust?.state === TrustStates.TRUSTED) {
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
|
|
92
137
|
for (const check of SCRIPT_CHECKS.filter((scriptCheck) => scriptCheck.pattern.test(source))) {
|
|
93
|
-
hits.push({
|
|
138
|
+
hits.push({
|
|
139
|
+
rule: check.rule,
|
|
140
|
+
message: `${target} looks like it is ${check.what}${trust === undefined ? '' : ` (listed in guard.writes.trustedScripts, but not trusted: ${trust.reason})`}`,
|
|
141
|
+
});
|
|
94
142
|
}
|
|
95
143
|
}
|
|
96
144
|
|
|
@@ -130,16 +178,19 @@ export const parseHookCommand = (opts: { text: string }): IHookCommand | undefin
|
|
|
130
178
|
: undefined;
|
|
131
179
|
};
|
|
132
180
|
|
|
133
|
-
export const buildGuardDecision = (opts: { hits: IWriteHit[] }) =>
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
181
|
+
export const buildGuardDecision = (opts: { hits: IWriteHit[] }) =>
|
|
182
|
+
forHost({
|
|
183
|
+
output: {
|
|
184
|
+
hookSpecificOutput: {
|
|
185
|
+
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
186
|
+
permissionDecision: HookConstants.GUARD_DECISION,
|
|
187
|
+
permissionDecisionReason: [
|
|
188
|
+
`This command looks like ${opts.hits.length === 1 ? 'an action' : 'actions'} the base rules reserve for a human:`,
|
|
189
|
+
...opts.hits.map((hit) => ` - ${hit.rule}: ${hit.message}`),
|
|
190
|
+
'',
|
|
191
|
+
'The rules reject "it is only dev", "it is only a test row" and "it is reversible".',
|
|
192
|
+
'Produce the script, the SQL or the manifest and hand it over instead of running it.',
|
|
193
|
+
].join('\n'),
|
|
194
|
+
},
|
|
195
|
+
},
|
|
196
|
+
});
|
package/src/hooks/index.ts
CHANGED
|
@@ -6,8 +6,13 @@ export * from './guard-outside.ts';
|
|
|
6
6
|
export * from './guard-package.ts';
|
|
7
7
|
export * from './guard-scripting.ts';
|
|
8
8
|
export * from './guard-writes.ts';
|
|
9
|
+
export * from './trusted-scripts.ts';
|
|
9
10
|
export * from './session-digest.ts';
|
|
10
11
|
export * from './subagent-card.ts';
|
|
11
12
|
export * from './owner-reply.ts';
|
|
13
|
+
export * from './project-tmp.ts';
|
|
14
|
+
export * from './project-guards.ts';
|
|
12
15
|
export * from './remote-hosts.ts';
|
|
16
|
+
export * from './codex-patch.ts';
|
|
13
17
|
export * from './shell.ts';
|
|
18
|
+
export * from './command-view.ts';
|