@venizia/vulcan 0.4.10-2 → 0.4.10-21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -23
- package/base/checks/wiki-source-links.ts +17 -1
- package/base/claude/events.json +1 -11
- package/base/claude/settings.json +5 -76
- package/base/extensions/vulcan-guards.ts +81 -18
- package/base/hooks/guard-git.ts +95 -19
- package/base/hooks/guard-outside.ts +163 -43
- package/base/hooks/guard-writes.ts +15 -36
- package/base/hooks/session-start.ts +1 -1
- package/base/make/vulcan.mk +8 -5
- package/base/packs/venizia.md +16 -0
- package/base/references/delegation-brief.md +3 -5
- package/base/references/testing.md +1 -9
- package/base/rules.md +33 -38
- package/base/skills/build-a-feature/SKILL.md +4 -4
- package/base/skills/docs-update/SKILL.md +19 -8
- package/base/skills/fix-a-bug/SKILL.md +4 -2
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/research/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +2 -2
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +3 -3
- package/base/skills/visualize-work/references/spec.md +6 -3
- package/base/templates/AGENTS.md +9 -7
- package/base/templates/board.html +10 -110
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +8 -31
- package/src/agents/codex-hooks.ts +1 -1
- package/src/agents/generated-block.ts +52 -0
- package/src/agents/hooks-json.ts +22 -3
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +15 -2
- package/src/agents/resolve.ts +1 -0
- package/src/agents/rules-block.ts +92 -0
- package/src/board/command.ts +92 -30
- package/src/board/common/constants.ts +26 -0
- package/src/board/common/types.ts +10 -3
- package/src/board/fold.ts +1 -1
- package/src/board/github.ts +1 -2
- package/src/board/gitlab.ts +436 -0
- package/src/board/index.ts +1 -0
- package/src/board/logo.ts +49 -0
- package/src/board/open-file.ts +110 -0
- package/src/board/page.ts +57 -5
- package/src/board/schema.ts +4 -1
- package/src/board/server.ts +87 -3
- package/src/board/settings.ts +21 -24
- package/src/commands/changelog.command.ts +40 -0
- package/src/commands/clean.command.ts +6 -1
- package/src/commands/help.command.ts +2 -63
- package/src/commands/index.ts +6 -1
- package/src/commands/migrate.command.ts +71 -0
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/runners.command.ts +43 -0
- package/src/commands/sync.command.ts +8 -4
- package/src/commands/table.ts +362 -0
- package/src/commit/check.ts +1 -0
- package/src/commit/common/constants.ts +4 -0
- package/src/commit/hook.ts +112 -8
- package/src/common/constants.ts +11 -9
- package/src/common/env-variables.ts +41 -0
- package/src/common/index.ts +1 -0
- package/src/common/layout-folder.ts +3 -4
- package/src/common/record.ts +5 -0
- package/src/config/common/constants.ts +28 -22
- package/src/config/loader.ts +22 -0
- package/src/config/schema.ts +330 -146
- package/src/create/add-app.ts +7 -2
- package/src/create/add-lib.ts +2 -4
- package/src/create/common/constants.ts +5 -3
- package/src/create/preset.ts +1 -0
- package/src/create/scratch.ts +2 -1
- package/src/doctor/checks.ts +277 -448
- package/src/doctor/common/constants.ts +27 -19
- package/src/doctor/private-values.ts +4 -1
- package/src/doctor/runner.ts +5 -12
- package/src/doctor/schema.ts +4 -0
- package/src/events/common/actor-names.ts +12 -0
- package/src/events/common/constants.ts +65 -38
- package/src/events/common/index.ts +1 -0
- package/src/events/hook.ts +5 -56
- package/src/events/text.ts +41 -6
- package/src/hooks/command-view.ts +80 -19
- package/src/hooks/common/constants.ts +26 -17
- package/src/hooks/common/types.ts +13 -24
- package/src/hooks/decision.ts +30 -12
- package/src/hooks/git-queries.ts +113 -0
- package/src/hooks/guard-git.ts +76 -24
- package/src/hooks/guard-outside.ts +334 -311
- package/src/hooks/guard-runner.ts +206 -0
- package/src/hooks/guard-writes.ts +87 -184
- package/src/hooks/hook-input.ts +57 -0
- package/src/hooks/index.ts +3 -6
- package/src/hooks/link-makers.ts +315 -0
- package/src/hooks/package-runners.ts +268 -0
- package/src/hooks/project-guards.ts +81 -44
- package/src/hooks/project-tmp.ts +39 -4
- package/src/hooks/runner-scan.ts +257 -0
- package/src/hooks/script-runners.ts +400 -0
- package/src/hooks/session-digest.ts +27 -117
- package/src/hooks/shell-folders.ts +760 -0
- package/src/hooks/shell-writes.ts +646 -0
- package/src/hooks/shell.ts +1421 -194
- package/src/hooks/subagent-card.ts +2 -2
- package/src/hooks/write-commands.ts +898 -0
- package/src/init/scaffold.ts +2 -3
- package/src/local/auto-clean.ts +2 -1
- package/src/local/browser-socket.ts +33 -0
- package/src/local/clean.ts +37 -6
- package/src/local/constants.ts +15 -1
- package/src/local/index.ts +1 -0
- package/src/local/scan.ts +41 -10
- package/src/manifest/render.ts +84 -30
- package/src/owner/constants.ts +4 -5
- package/src/owner/index.ts +0 -2
- package/src/owner/profile.ts +1 -0
- package/src/owner/schema.ts +51 -27
- package/src/owner/survey.ts +0 -3
- package/src/owner/view.ts +0 -9
- package/src/router.ts +8 -132
- package/src/rules/base.ts +12 -7
- package/src/rules/index.ts +1 -0
- package/src/rules/packs.ts +44 -0
- package/src/runners/check.ts +130 -0
- package/src/skills/frontmatter.ts +1 -0
- package/src/sync/agents-block.ts +104 -0
- package/src/sync/base-rules.ts +3 -3
- package/src/sync/claude-launch.ts +12 -12
- package/src/sync/common/constants.ts +0 -2
- package/src/sync/index.ts +1 -1
- package/src/sync/local-choice.ts +32 -3
- package/src/sync/planner.ts +2 -15
- package/src/sync/settings.ts +0 -17
- package/src/theme/index.ts +1 -0
- package/src/theme/tokens.ts +410 -0
- package/src/ui/prompt.ts +1 -0
- package/src/visualize/architecture.ts +504 -0
- package/src/visualize/assets.ts +41 -30
- package/src/visualize/compare-render.ts +22 -24
- package/src/visualize/constants.ts +27 -0
- package/src/visualize/diagrams.ts +13 -121
- package/src/visualize/kinds-render.ts +2 -2
- package/src/visualize/kinds-schema.ts +49 -0
- package/src/visualize/labels-vi.ts +25 -0
- package/src/visualize/labels.ts +2 -0
- package/src/visualize/layout.ts +415 -66
- package/src/visualize/page.ts +82 -15
- package/src/visualize/render.ts +2 -1
- package/src/visualize/schema.ts +29 -1
- package/src/visualize/sections.ts +78 -9
- package/src/visualize/theme.ts +49 -18
- package/src/wiki/anchors.ts +1 -0
- package/src/wiki/command.ts +10 -3
- package/src/wiki/source-links.ts +57 -18
- package/base/ci-global.json +0 -13
- package/base/claude/remote-hosts.json +0 -15
- package/base/hooks/guard-manifest.ts +0 -27
- package/base/hooks/guard-package.ts +0 -30
- package/base/hooks/guard-remote-hosts.ts +0 -70
- package/base/hooks/guard-scripting.ts +0 -32
- package/base/hooks/post-tool.ts +0 -37
- package/base/hooks/prompt-submit.ts +0 -54
- package/base/hooks/stop.ts +0 -40
- package/base/skills/build-a-feature/evals/evals.json +0 -29
- package/base/skills/docs-update/evals/evals.json +0 -23
- package/base/skills/docs-writing/evals/evals.json +0 -17
- package/base/skills/fix-a-bug/evals/evals.json +0 -17
- package/base/skills/knowledge-sync/SKILL.md +0 -81
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
- package/base/skills/knowledge-sync/references/workflow.md +0 -44
- package/base/skills/plan-a-change/evals/evals.json +0 -47
- package/base/skills/report-back/evals/evals.json +0 -23
- package/base/skills/research/evals/evals.json +0 -17
- package/base/skills/retro/evals/evals.json +0 -17
- package/base/skills/review-a-change/evals/evals.json +0 -17
- package/base/skills/ship/evals/evals.json +0 -23
- package/base/skills/visualize-work/evals/evals.json +0 -17
- package/base/templates/ci/github-actions.yml +0 -75
- package/base/templates/ci/gitlab-ci.yml +0 -52
- package/base/templates/trusted-hosts.local.example +0 -11
- package/src/ci/affected.ts +0 -176
- package/src/ci/command.ts +0 -166
- package/src/ci/common/constants.ts +0 -76
- package/src/ci/common/index.ts +0 -2
- package/src/ci/common/types.ts +0 -37
- package/src/ci/git.ts +0 -72
- package/src/ci/global.ts +0 -48
- package/src/ci/graph.ts +0 -43
- package/src/ci/index.ts +0 -7
- package/src/ci/workspace.ts +0 -119
- package/src/commands/ci.command.ts +0 -4
- package/src/hooks/guard-manifest.ts +0 -109
- package/src/hooks/guard-package.ts +0 -226
- package/src/hooks/guard-scripting.ts +0 -36
- package/src/hooks/host-pattern.ts +0 -17
- package/src/hooks/owner-reply.ts +0 -162
- package/src/hooks/post-tool.ts +0 -138
- package/src/hooks/remote-hosts.ts +0 -1013
- package/src/hooks/trusted-scripts.ts +0 -212
- package/src/owner/shape.ts +0 -496
- package/src/owner/violations.ts +0 -332
- package/src/signals/claims.ts +0 -73
- package/src/signals/classify.ts +0 -137
- package/src/signals/constants.ts +0 -88
- package/src/signals/index.ts +0 -5
- package/src/signals/loop.ts +0 -48
- package/src/signals/state.ts +0 -271
- package/src/sync/atlas-block.ts +0 -56
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ShellParser } from './shell.ts';
|
|
1
|
+
import { ShellParser, ShellPrograms } from './shell.ts';
|
|
2
2
|
import type { ISimpleCommand } from './shell.ts';
|
|
3
3
|
|
|
4
4
|
/** Programs that only read or print what they are given: their arguments are text to find or show, never a command to run. */
|
|
@@ -40,15 +40,18 @@ const GH_REQUESTS = new Set(['api', 'secret', 'variable']);
|
|
|
40
40
|
const GH_REPOSITORY_FLAGS = new Set(['-R', '--repo']);
|
|
41
41
|
|
|
42
42
|
/** `find` runs a command only with these; without them it only lists. */
|
|
43
|
-
const FIND_RUNS = new Set([
|
|
43
|
+
const FIND_RUNS = new Set([...ShellPrograms.FIND_RUN_OPTIONS, '-delete']);
|
|
44
44
|
|
|
45
45
|
/** Programs that read their heredoc as a query or a script: the body is part of what they run. */
|
|
46
46
|
const HEREDOC_READERS = new Set([
|
|
47
47
|
'ssh',
|
|
48
48
|
'psql',
|
|
49
49
|
'mysql',
|
|
50
|
+
'mariadb',
|
|
50
51
|
'mongosh',
|
|
52
|
+
'mongo',
|
|
51
53
|
'sqlite3',
|
|
54
|
+
'redis-cli',
|
|
52
55
|
'python',
|
|
53
56
|
'python3',
|
|
54
57
|
'node',
|
|
@@ -59,9 +62,39 @@ const HEREDOC_READERS = new Set([
|
|
|
59
62
|
'php',
|
|
60
63
|
]);
|
|
61
64
|
|
|
62
|
-
/**
|
|
63
|
-
const
|
|
64
|
-
|
|
65
|
+
/** Programs that run what a pipe feeds them: `echo "kubectl apply -f x" | sh`. */
|
|
66
|
+
const PIPE_RUNNERS = new Set([
|
|
67
|
+
...ShellPrograms.SHELL_NAMES,
|
|
68
|
+
'psql',
|
|
69
|
+
'mysql',
|
|
70
|
+
'mariadb',
|
|
71
|
+
'mongosh',
|
|
72
|
+
'mongo',
|
|
73
|
+
'sqlite3',
|
|
74
|
+
'python',
|
|
75
|
+
'python3',
|
|
76
|
+
'node',
|
|
77
|
+
'bun',
|
|
78
|
+
'ssh',
|
|
79
|
+
]);
|
|
80
|
+
|
|
81
|
+
/** What a command line runs, for a guard that must not let an unread part through. */
|
|
82
|
+
export interface ICommandView {
|
|
83
|
+
/** One text per simple command, as `CommandView.commandTextsOf` gives them. */
|
|
84
|
+
texts: string[];
|
|
85
|
+
/** The simple command behind each of `texts`; `undefined` for a whole line that pipes into a runner. */
|
|
86
|
+
sources: (ISimpleCommand | undefined)[];
|
|
87
|
+
/** The simple commands whose arguments are not data, a reader's heredoc body still on them. */
|
|
88
|
+
commands: ISimpleCommand[];
|
|
89
|
+
/** Every simple command of the line, data too, in the parser's order. */
|
|
90
|
+
parsed: ISimpleCommand[];
|
|
91
|
+
/** Part of the line was not read: the guard asks. */
|
|
92
|
+
isOverBudget: boolean;
|
|
93
|
+
/** Part of the line could not be followed to its end: the guard asks. */
|
|
94
|
+
isUncertain: boolean;
|
|
95
|
+
/** A command's program is a variable or a substitution: the guard asks. */
|
|
96
|
+
hasUnknownProgram: boolean;
|
|
97
|
+
}
|
|
65
98
|
|
|
66
99
|
/** Whether a `gh` command is a request: its subcommand (the first word that is not an option or an option's value) is one of `GH_REQUESTS`. */
|
|
67
100
|
const isGhRequest = (opts: { command: ISimpleCommand }): boolean => {
|
|
@@ -75,25 +108,24 @@ const isGhRequest = (opts: { command: ISimpleCommand }): boolean => {
|
|
|
75
108
|
};
|
|
76
109
|
|
|
77
110
|
export class CommandView {
|
|
78
|
-
/** The
|
|
79
|
-
private static
|
|
80
|
-
|
|
81
|
-
|
|
111
|
+
/** The text of one simple command: the words, a bare name for data, a reader's heredoc body appended. */
|
|
112
|
+
private static textOf(opts: { command: ISimpleCommand; withMessages: boolean }): string {
|
|
113
|
+
const { command } = opts;
|
|
114
|
+
const name = ShellParser.basenameOf({ word: ShellParser.programOf({ command }).name });
|
|
82
115
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
116
|
+
if (CommandView.isDataOnly({ command, withMessages: opts.withMessages })) {
|
|
117
|
+
return name;
|
|
118
|
+
}
|
|
86
119
|
|
|
87
|
-
|
|
88
|
-
|
|
120
|
+
const body =
|
|
121
|
+
command.heredoc !== undefined && HEREDOC_READERS.has(name) ? `\n${command.heredoc}` : '';
|
|
89
122
|
|
|
90
|
-
|
|
91
|
-
});
|
|
123
|
+
return `${command.words.join(' ')}${body}`;
|
|
92
124
|
}
|
|
93
125
|
|
|
94
126
|
/**
|
|
95
127
|
* Whether the arguments of a command are data. `withMessages` adds `git` and `gh` (their arguments are
|
|
96
|
-
* messages to the write guards
|
|
128
|
+
* messages to the write guards).
|
|
97
129
|
*/
|
|
98
130
|
static isDataOnly(opts: { command: ISimpleCommand; withMessages: boolean }): boolean {
|
|
99
131
|
const name = ShellParser.basenameOf({
|
|
@@ -119,8 +151,37 @@ export class CommandView {
|
|
|
119
151
|
* that runs its input (`echo "kubectl apply -f x" | sh`) stands as one text, because what it prints is code.
|
|
120
152
|
*/
|
|
121
153
|
static commandTextsOf(opts: { command: string; withMessages: boolean }): string[] {
|
|
122
|
-
|
|
154
|
+
return CommandView.viewOf(opts).texts;
|
|
155
|
+
}
|
|
123
156
|
|
|
124
|
-
|
|
157
|
+
/** `commandTextsOf`, with the commands behind the texts and whether all of the line was read. */
|
|
158
|
+
static viewOf(opts: { command: string; withMessages: boolean }): ICommandView {
|
|
159
|
+
const { text } = ShellParser.splitHeredocs({ command: opts.command });
|
|
160
|
+
const parsed = ShellParser.parseChecked({ command: opts.command });
|
|
161
|
+
const commands = parsed.commands.filter(
|
|
162
|
+
(command) => !CommandView.isDataOnly({ command, withMessages: opts.withMessages }),
|
|
163
|
+
);
|
|
164
|
+
// Read from the commands, not the text, so a `| sh` in a comment or in quotes feeds nothing.
|
|
165
|
+
const isWholeLine = parsed.commands.some(
|
|
166
|
+
(command) =>
|
|
167
|
+
command.input?.pipedFrom !== undefined &&
|
|
168
|
+
PIPE_RUNNERS.has(ShellParser.basenameOf({ word: ShellParser.programOf({ command }).name })),
|
|
169
|
+
);
|
|
170
|
+
const texts = isWholeLine
|
|
171
|
+
? [text]
|
|
172
|
+
: parsed.commands.map((command) =>
|
|
173
|
+
CommandView.textOf({ command, withMessages: opts.withMessages }),
|
|
174
|
+
);
|
|
175
|
+
const sources = isWholeLine ? [undefined] : parsed.commands;
|
|
176
|
+
|
|
177
|
+
return {
|
|
178
|
+
texts,
|
|
179
|
+
sources,
|
|
180
|
+
commands,
|
|
181
|
+
parsed: parsed.commands,
|
|
182
|
+
isOverBudget: parsed.isOverBudget,
|
|
183
|
+
isUncertain: parsed.isUncertain,
|
|
184
|
+
hasUnknownProgram: parsed.hasUnknownProgram,
|
|
185
|
+
};
|
|
125
186
|
}
|
|
126
187
|
}
|
|
@@ -4,23 +4,6 @@ export class GuardDecisions {
|
|
|
4
4
|
static readonly DENY = 'deny';
|
|
5
5
|
}
|
|
6
6
|
|
|
7
|
-
/** What the package guard says about a hand-made package: refuse where a `vulcan add` command exists, else warn. */
|
|
8
|
-
export class PackageVerdictKinds {
|
|
9
|
-
static readonly DENY = GuardDecisions.DENY;
|
|
10
|
-
static readonly WARN = 'warn';
|
|
11
|
-
}
|
|
12
|
-
|
|
13
|
-
/** What git says about a script a project trusts: only `TRUSTED` skips the script checks of guard-writes. */
|
|
14
|
-
export class TrustStates {
|
|
15
|
-
static readonly TRUSTED = 'trusted';
|
|
16
|
-
static readonly MISSING = 'missing';
|
|
17
|
-
static readonly UNTRACKED = 'untracked';
|
|
18
|
-
static readonly UNCOMMITTED = 'uncommitted';
|
|
19
|
-
static readonly MODIFIED = 'modified';
|
|
20
|
-
static readonly SYMLINK = 'symlink';
|
|
21
|
-
static readonly UNKNOWN = 'unknown';
|
|
22
|
-
}
|
|
23
|
-
|
|
24
7
|
export class HookConstants {
|
|
25
8
|
/** `ask` until the transcript shows the guard does not over-fire; a false positive costs one keystroke. */
|
|
26
9
|
static readonly GUARD_DECISION = GuardDecisions.ASK;
|
|
@@ -37,6 +20,32 @@ export class HookConstants {
|
|
|
37
20
|
* unintended files into one commit; on this repository's develop the median commit touches 7 files and 2.2% touch more than 50.
|
|
38
21
|
*/
|
|
39
22
|
static readonly BLANKET_STAGE_PATHS = 50;
|
|
23
|
+
/** The environment variable that makes every guard refuse what it would ask about; the launch environment sets it, the project cannot loosen it. */
|
|
24
|
+
static readonly ENV_ASKS = 'VULCAN_GUARD_ASKS';
|
|
25
|
+
/** The environment variable that makes guard-outside refuse a write outside the project; as `ENV_ASKS`. */
|
|
26
|
+
static readonly ENV_OUTSIDE = 'VULCAN_GUARD_OUTSIDE';
|
|
27
|
+
/** What an answer says when the project (`guard.asks: 'deny'`) holds every ask. */
|
|
28
|
+
static readonly HELD_ASK =
|
|
29
|
+
'This project denies every call that would need a human to confirm it (guard.asks: deny). Nothing was run: hand this to the owner.';
|
|
30
|
+
/** What an answer says when the launch environment (`VULCAN_GUARD_ASKS=deny`) holds every ask. */
|
|
31
|
+
static readonly HELD_ASK_ENV =
|
|
32
|
+
'This session denies every call that would need a human to confirm it (VULCAN_GUARD_ASKS=deny). Nothing was run: hand this to the owner.';
|
|
33
|
+
/** What an answer says when the manifest exists and cannot be read: the hooks cannot tell what the project asked for, so an ask is a deny. */
|
|
34
|
+
static readonly MANIFEST_UNREADABLE =
|
|
35
|
+
'The manifest .agents/vulcan.manifest.json exists but cannot be read, so every call that would need a human to confirm it is denied. Nothing was run: the owner repairs the file or runs bun node_modules/.bin/vulcan sync.';
|
|
36
|
+
/**
|
|
37
|
+
* The files the guards read their policy from, relative to the project root: the manifest, the config, Claude Code's
|
|
38
|
+
* project settings and the installed package with its hooks. An agent that can write one can switch a guard off, so
|
|
39
|
+
* guard-outside denies a write to any of them; the owner changes them by hand, or through `vulcan sync`.
|
|
40
|
+
*/
|
|
41
|
+
static readonly PROTECTED_FILES = [
|
|
42
|
+
'.agents/vulcan.manifest.json',
|
|
43
|
+
'.configs/vulcan.config.*',
|
|
44
|
+
'.claude/settings.json',
|
|
45
|
+
'.claude/settings.local.json',
|
|
46
|
+
'node_modules/@venizia/vulcan',
|
|
47
|
+
'node_modules/@venizia/vulcan/**',
|
|
48
|
+
];
|
|
40
49
|
/** Branches no agent deletes or force-pushes (V-W-06). */
|
|
41
50
|
static readonly PROTECTED_BRANCHES = new Set(['develop', 'main']);
|
|
42
51
|
/**
|
|
@@ -1,29 +1,7 @@
|
|
|
1
1
|
import type { TConstValue } from '../../common/index.ts';
|
|
2
|
-
import type { GuardDecisions
|
|
2
|
+
import type { GuardDecisions } from './constants.ts';
|
|
3
3
|
|
|
4
4
|
export type TGuardDecision = TConstValue<typeof GuardDecisions>;
|
|
5
|
-
export type TPackageVerdictKind = TConstValue<typeof PackageVerdictKinds>;
|
|
6
|
-
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
|
-
}
|
|
13
|
-
|
|
14
|
-
/** A script the project vouches for on some subcommands only: the first argument after the script is one of `readOnly`. */
|
|
15
|
-
export interface IReadOnlyScript {
|
|
16
|
-
script: string;
|
|
17
|
-
readOnly: string[];
|
|
18
|
-
}
|
|
19
|
-
|
|
20
|
-
/** One `bun x.ts` call as the shell sees it: the script word and the word right after it, if any. */
|
|
21
|
-
export interface IScriptInvocation {
|
|
22
|
-
script: string;
|
|
23
|
-
subcommand: string | undefined;
|
|
24
|
-
/** A `cd`, `pushd` or `popd` came before it in the line, so a relative script word is not from the hook's folder. */
|
|
25
|
-
moved: boolean;
|
|
26
|
-
}
|
|
27
5
|
|
|
28
6
|
export interface IWriteCheck {
|
|
29
7
|
rule: string;
|
|
@@ -42,7 +20,7 @@ export interface IHookCommand {
|
|
|
42
20
|
cwd: string | undefined;
|
|
43
21
|
}
|
|
44
22
|
|
|
45
|
-
/** What
|
|
23
|
+
/** What a guard reads of any tool call: the tool, the file it names, or the Bash command. */
|
|
46
24
|
export interface IManifestHookInput {
|
|
47
25
|
tool: string;
|
|
48
26
|
filePath: string | undefined;
|
|
@@ -55,6 +33,11 @@ export interface IGitHit {
|
|
|
55
33
|
decision: TGuardDecision;
|
|
56
34
|
rule: string;
|
|
57
35
|
message: string;
|
|
36
|
+
/**
|
|
37
|
+
* What the agent does to get past a `deny` by itself (name the files, pass the base, write a literal path). A denial with
|
|
38
|
+
* a `fix` is the agent's to repair and is never handed to a person; one without it needs the owner.
|
|
39
|
+
*/
|
|
40
|
+
fix?: string;
|
|
58
41
|
}
|
|
59
42
|
|
|
60
43
|
/** Runs a read-only `git` or `gh` query for a guard; `undefined` when it cannot answer. */
|
|
@@ -70,4 +53,10 @@ export interface IOutsideHit {
|
|
|
70
53
|
message: string;
|
|
71
54
|
/** Whether the path is under the scratchpad folder an agent tool offers: the hook denies it, it does not ask. */
|
|
72
55
|
isAgentToolScratchpad: boolean;
|
|
56
|
+
/** Whether the check could not read the line or the target, so it does not know that anything is outside: the hook asks, even where the project denies. */
|
|
57
|
+
isUnread: boolean;
|
|
58
|
+
/** Whether the path is what an `ln` of the line links to: a write through the link changes it, so the hook denies and says how to link a path inside. */
|
|
59
|
+
isLink?: boolean;
|
|
60
|
+
/** Whether the path is one of the files the guards read their policy from: the hook denies a write to it, whatever the project sets. */
|
|
61
|
+
isProtected?: boolean;
|
|
73
62
|
}
|
package/src/hooks/decision.ts
CHANGED
|
@@ -12,20 +12,31 @@ interface IDecisionOutput {
|
|
|
12
12
|
export class HookDecision {
|
|
13
13
|
/**
|
|
14
14
|
* The decision as every host that reads our hooks understands it. Claude Code and Cursor read
|
|
15
|
-
*
|
|
16
|
-
* too (Claude Code ignores them: checked). Cursor does not enforce an
|
|
17
|
-
* says it is running the hook (
|
|
15
|
+
* `hookSpecificOutput`; Copilot documents the same two fields at the top level, so they are written there
|
|
16
|
+
* too (Claude Code ignores them: checked). Cursor does not enforce an `ask` on a tool call, so where it
|
|
17
|
+
* says it is running the hook (`CURSOR_PROJECT_DIR`) an ask is a deny that says why. A project that sets `guard.asks: 'deny'`
|
|
18
|
+
* (`asks`) gets every ask as a deny too, because where the agent runs in an auto mode an ask can be approved with no human.
|
|
18
19
|
*/
|
|
19
|
-
static forHost(opts: {
|
|
20
|
+
static forHost(opts: {
|
|
21
|
+
output: IDecisionOutput;
|
|
22
|
+
env?: Record<string, string | undefined>;
|
|
23
|
+
asks?: string;
|
|
24
|
+
/** What the added line says when the ask is held; the project's own wording when it is not given. */
|
|
25
|
+
asksNote?: string;
|
|
26
|
+
}) {
|
|
20
27
|
const specific = opts.output.hookSpecificOutput;
|
|
21
28
|
const env = opts.env ?? process.env;
|
|
22
|
-
const
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
const decision = isCursorAsk ? GuardDecisions.DENY : specific.permissionDecision;
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
+
const isAsk = specific.permissionDecision === GuardDecisions.ASK;
|
|
30
|
+
const isHeld = isAsk && opts.asks === GuardDecisions.DENY;
|
|
31
|
+
const isCursorAsk = isAsk && env[HookConstants.CURSOR_PROJECT_DIR_ENV] !== undefined;
|
|
32
|
+
const decision = isHeld || isCursorAsk ? GuardDecisions.DENY : specific.permissionDecision;
|
|
33
|
+
let reason = specific.permissionDecisionReason;
|
|
34
|
+
|
|
35
|
+
if (isHeld) {
|
|
36
|
+
reason = `${reason}\n\n${opts.asksNote ?? HookConstants.HELD_ASK}`;
|
|
37
|
+
} else if (isCursorAsk) {
|
|
38
|
+
reason = `${reason}\n(Cursor cannot ask about a tool call: hand this to the owner)`;
|
|
39
|
+
}
|
|
29
40
|
|
|
30
41
|
return {
|
|
31
42
|
hookSpecificOutput: {
|
|
@@ -39,8 +50,15 @@ export class HookDecision {
|
|
|
39
50
|
}
|
|
40
51
|
|
|
41
52
|
/** The PreToolUse answer Claude Code reads from stdout: the decision and why, shown to the human or to the model. */
|
|
42
|
-
static buildTool(opts: {
|
|
53
|
+
static buildTool(opts: {
|
|
54
|
+
decision: TGuardDecision;
|
|
55
|
+
reason: string[];
|
|
56
|
+
asks?: string;
|
|
57
|
+
asksNote?: string;
|
|
58
|
+
}) {
|
|
43
59
|
return HookDecision.forHost({
|
|
60
|
+
asks: opts.asks,
|
|
61
|
+
asksNote: opts.asksNote,
|
|
44
62
|
output: {
|
|
45
63
|
hookSpecificOutput: {
|
|
46
64
|
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import { HookConstants } from './common/index.ts';
|
|
3
|
+
|
|
4
|
+
export class GitQueries {
|
|
5
|
+
/** Variables that point git at another repository or index than the one in `cwd`, or add configuration or a program to it. */
|
|
6
|
+
static readonly REDIRECTING_VARIABLES = [
|
|
7
|
+
'GIT_DIR',
|
|
8
|
+
'GIT_WORK_TREE',
|
|
9
|
+
'GIT_INDEX_FILE',
|
|
10
|
+
'GIT_CONFIG_COUNT',
|
|
11
|
+
'GIT_CONFIG_PARAMETERS',
|
|
12
|
+
'GIT_EXEC_PATH',
|
|
13
|
+
'GIT_EXTERNAL_DIFF',
|
|
14
|
+
'GIT_SSH_COMMAND',
|
|
15
|
+
'GIT_ASKPASS',
|
|
16
|
+
'GIT_PAGER',
|
|
17
|
+
];
|
|
18
|
+
/** `GIT_CONFIG_KEY_<n>` and `GIT_CONFIG_VALUE_<n>`: configuration given through the environment. */
|
|
19
|
+
private static readonly CONFIG_PAIR = /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/;
|
|
20
|
+
/** The queries that read the content of tracked files, so git may run a filter on it. */
|
|
21
|
+
private static readonly CONTENT_QUERIES = ['status', 'diff'];
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Configuration keys that make git run a program the repository names. A query is a question, so each is set to
|
|
25
|
+
* a value that names nothing: a file system monitor, a hooks folder, an ssh command and a pager.
|
|
26
|
+
*/
|
|
27
|
+
static readonly INERT_CONFIG = [
|
|
28
|
+
'core.fsmonitor=false',
|
|
29
|
+
'core.hooksPath=/dev/null',
|
|
30
|
+
'core.sshCommand=false',
|
|
31
|
+
'core.pager=cat',
|
|
32
|
+
];
|
|
33
|
+
|
|
34
|
+
/** The words before a `git` subcommand that make the query inert; a query takes no optional lock, so it writes no index. */
|
|
35
|
+
static inertArgs(): string[] {
|
|
36
|
+
return [
|
|
37
|
+
'--no-optional-locks',
|
|
38
|
+
'--no-pager',
|
|
39
|
+
...GitQueries.INERT_CONFIG.flatMap((setting) => ['-c', setting]),
|
|
40
|
+
];
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The environment of a query: the one the hook runs in, without the variables that point git somewhere else. */
|
|
44
|
+
static environment(): Record<string, string | undefined> {
|
|
45
|
+
const env: Record<string, string | undefined> = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
|
|
46
|
+
|
|
47
|
+
for (const name of Object.keys(env)) {
|
|
48
|
+
if (GitQueries.REDIRECTING_VARIABLES.includes(name) || GitQueries.CONFIG_PAIR.test(name)) {
|
|
49
|
+
delete env[name];
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
return env;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Whether the configuration of the repository itself (its `.git/config`, what that includes, the worktree
|
|
58
|
+
* configuration) names a filter program. The user's own configuration is not asked: a program there is the user's.
|
|
59
|
+
* Asking runs nothing.
|
|
60
|
+
*/
|
|
61
|
+
static hasRepositoryFilter(opts: { cwd: string | undefined }): boolean {
|
|
62
|
+
const result = spawnSync(
|
|
63
|
+
'git',
|
|
64
|
+
[
|
|
65
|
+
...GitQueries.inertArgs(),
|
|
66
|
+
'config',
|
|
67
|
+
'--local',
|
|
68
|
+
'--includes',
|
|
69
|
+
'--get-regexp',
|
|
70
|
+
'^filter\\..*\\.(clean|smudge|process)$',
|
|
71
|
+
],
|
|
72
|
+
{
|
|
73
|
+
cwd: opts.cwd,
|
|
74
|
+
encoding: 'utf8',
|
|
75
|
+
timeout: HookConstants.QUERY_TIMEOUT_MS,
|
|
76
|
+
env: GitQueries.environment(),
|
|
77
|
+
},
|
|
78
|
+
);
|
|
79
|
+
|
|
80
|
+
return result.status === 0 && result.stdout.trim() !== '';
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* A read-only query in `cwd`; `undefined` when the program is missing, slow or answers with an error. A `git`
|
|
85
|
+
* query runs inert (`inertArgs`) and is about this checkout; a `gh` one gets the same environment.
|
|
86
|
+
*/
|
|
87
|
+
static run(opts: {
|
|
88
|
+
program?: string;
|
|
89
|
+
args: string[];
|
|
90
|
+
cwd: string | undefined;
|
|
91
|
+
}): string | undefined {
|
|
92
|
+
const program = opts.program ?? 'git';
|
|
93
|
+
|
|
94
|
+
// A query that reads content would run a filter the repository names: it is not asked, and the guard treats the answer as unknown.
|
|
95
|
+
if (
|
|
96
|
+
program === 'git' &&
|
|
97
|
+
GitQueries.CONTENT_QUERIES.includes(opts.args[0] ?? '') &&
|
|
98
|
+
GitQueries.hasRepositoryFilter({ cwd: opts.cwd })
|
|
99
|
+
) {
|
|
100
|
+
return undefined;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const args = program === 'git' ? [...GitQueries.inertArgs(), ...opts.args] : opts.args;
|
|
104
|
+
const result = spawnSync(program, args, {
|
|
105
|
+
cwd: opts.cwd,
|
|
106
|
+
encoding: 'utf8',
|
|
107
|
+
timeout: HookConstants.QUERY_TIMEOUT_MS,
|
|
108
|
+
env: GitQueries.environment(),
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
return result.status === 0 ? result.stdout.trim() : undefined;
|
|
112
|
+
}
|
|
113
|
+
}
|
package/src/hooks/guard-git.ts
CHANGED
|
@@ -1,21 +1,12 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { ShellParser } from './shell.ts';
|
|
1
|
+
import { ShellParser, ShellUnread } from './shell.ts';
|
|
3
2
|
import type { ISimpleCommand } from './shell.ts';
|
|
4
3
|
import { GuardDecisions, HookConstants } from './common/index.ts';
|
|
5
4
|
import type { IGitHit, IGitRunner } from './common/index.ts';
|
|
5
|
+
import { GitQueries } from './git-queries.ts';
|
|
6
6
|
import { ProjectGuards } from './project-guards.ts';
|
|
7
7
|
|
|
8
|
-
/** `git` and `gh` read-only queries the guard makes; `undefined` when the tool is missing, slow or fails. */
|
|
9
|
-
const runQuery: IGitRunner = (opts) =>
|
|
10
|
-
const result = spawnSync(opts.program, opts.args, {
|
|
11
|
-
cwd: opts.cwd,
|
|
12
|
-
encoding: 'utf8',
|
|
13
|
-
timeout: HookConstants.QUERY_TIMEOUT_MS,
|
|
14
|
-
env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
|
|
15
|
-
});
|
|
16
|
-
|
|
17
|
-
return result.status === 0 ? result.stdout.trim() : undefined;
|
|
18
|
-
};
|
|
8
|
+
/** `git` and `gh` read-only queries the guard makes, inert (`GitQueries`); `undefined` when the tool is missing, slow or fails. */
|
|
9
|
+
const runQuery: IGitRunner = (opts) => GitQueries.run(opts);
|
|
19
10
|
|
|
20
11
|
/** Options of `git` before its subcommand, and how many words each takes. */
|
|
21
12
|
const GIT_OPTIONS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace']);
|
|
@@ -177,9 +168,10 @@ const inspectStage = (opts: {
|
|
|
177
168
|
return count > HookConstants.BLANKET_STAGE_PATHS
|
|
178
169
|
? [
|
|
179
170
|
{
|
|
180
|
-
decision: GuardDecisions.
|
|
171
|
+
decision: GuardDecisions.DENY,
|
|
181
172
|
rule: 'V-W-06',
|
|
182
|
-
message: `this stages ${count} changed paths at once (more than ${HookConstants.BLANKET_STAGE_PATHS}), a formatter's or a generator's included
|
|
173
|
+
message: `this stages ${count} changed paths at once (more than ${HookConstants.BLANKET_STAGE_PATHS}), a formatter's or a generator's included`,
|
|
174
|
+
fix: 'name the files you mean (git add <path> ...), or stage a folder you own',
|
|
183
175
|
},
|
|
184
176
|
]
|
|
185
177
|
: [];
|
|
@@ -298,6 +290,45 @@ const ghCall = (opts: { args: string[] }): { group: string; action: string; rest
|
|
|
298
290
|
return { group: names[0] ?? '', action: names[1] ?? '', rest: opts.args.slice(index) };
|
|
299
291
|
};
|
|
300
292
|
|
|
293
|
+
const REF_ENDPOINT = /^repos\/[^/]+\/[^/]+\/git\/refs\/heads\/(.+)$/;
|
|
294
|
+
|
|
295
|
+
/** The path `gh api` calls for a word: without the host, a `?query`, the slashes at its ends, decoded once. */
|
|
296
|
+
const endpointOf = (opts: { word: string }): string => {
|
|
297
|
+
const path = opts.word
|
|
298
|
+
.replace(/^https?:\/\/api\.github\.com/i, '')
|
|
299
|
+
.replace(/[?#].*$/s, '')
|
|
300
|
+
.replace(/^\/+|\/+$/g, '');
|
|
301
|
+
|
|
302
|
+
try {
|
|
303
|
+
return decodeURIComponent(path);
|
|
304
|
+
} catch {
|
|
305
|
+
return path;
|
|
306
|
+
}
|
|
307
|
+
};
|
|
308
|
+
|
|
309
|
+
/** `gh api -X DELETE repos/<owner>/<repo>/git/refs/heads/<branch>` deletes the branch as `git push --delete` does. */
|
|
310
|
+
const inspectGhApi = (opts: { args: string[] }): IGitHit[] => {
|
|
311
|
+
const { args } = opts;
|
|
312
|
+
const isDelete = args.some(
|
|
313
|
+
(word, index) =>
|
|
314
|
+
/^(-X|--method)=?DELETE$/i.test(word) ||
|
|
315
|
+
(/^(-X|--method)$/.test(word) && (args[index + 1] ?? '').toUpperCase() === 'DELETE'),
|
|
316
|
+
);
|
|
317
|
+
|
|
318
|
+
if (ghCall({ args }).group !== 'api' || !isDelete) {
|
|
319
|
+
return [];
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
return args
|
|
323
|
+
.map((word) => REF_ENDPOINT.exec(endpointOf({ word }))?.[1])
|
|
324
|
+
.filter((name): name is string => name !== undefined && isProtected({ name }))
|
|
325
|
+
.map((name) => ({
|
|
326
|
+
decision: GuardDecisions.DENY,
|
|
327
|
+
rule: 'V-W-06',
|
|
328
|
+
message: `deleting the remote branch '${name}'`,
|
|
329
|
+
}));
|
|
330
|
+
};
|
|
331
|
+
|
|
301
332
|
/** `gh pr merge [<pr>] --delete-branch`: the PR's head branch decides, and `gh` is asked for it. */
|
|
302
333
|
const inspectGhMerge = (opts: {
|
|
303
334
|
args: string[];
|
|
@@ -373,10 +404,10 @@ const inspectGhCreate = (opts: { args: string[] }): IGitHit[] => {
|
|
|
373
404
|
? []
|
|
374
405
|
: [
|
|
375
406
|
{
|
|
376
|
-
decision: GuardDecisions.
|
|
407
|
+
decision: GuardDecisions.DENY,
|
|
377
408
|
rule: 'V-W-06',
|
|
378
|
-
message:
|
|
379
|
-
|
|
409
|
+
message: "'gh pr create' names no --base, so the pull request targets the default branch",
|
|
410
|
+
fix: 'pass --base <branch>, the branch the project takes its changes on',
|
|
380
411
|
},
|
|
381
412
|
];
|
|
382
413
|
};
|
|
@@ -394,6 +425,7 @@ const inspectOne = (opts: {
|
|
|
394
425
|
return [
|
|
395
426
|
...inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run }),
|
|
396
427
|
...inspectGhCreate({ args: program.args }),
|
|
428
|
+
...inspectGhApi({ args: program.args }),
|
|
397
429
|
];
|
|
398
430
|
}
|
|
399
431
|
|
|
@@ -432,7 +464,7 @@ const inspectOne = (opts: {
|
|
|
432
464
|
return [
|
|
433
465
|
{
|
|
434
466
|
decision: GuardDecisions.ASK,
|
|
435
|
-
rule: 'V-W-
|
|
467
|
+
rule: 'V-W-06',
|
|
436
468
|
message: 'git reset --hard discards every uncommitted change',
|
|
437
469
|
},
|
|
438
470
|
];
|
|
@@ -471,22 +503,42 @@ export class GitGuard {
|
|
|
471
503
|
inspectOne({ command, cwd: opts.cwd, run: limited, askPush: opts.askPush ?? [] }),
|
|
472
504
|
);
|
|
473
505
|
|
|
506
|
+
// The lines of a heredoc body that never ends are data to bash: what they would do is asked about, not denied.
|
|
507
|
+
for (const command of parsed.unterminatedHeredocCommands) {
|
|
508
|
+
for (const hit of inspectOne({
|
|
509
|
+
command,
|
|
510
|
+
cwd: opts.cwd,
|
|
511
|
+
run: limited,
|
|
512
|
+
askPush: opts.askPush ?? [],
|
|
513
|
+
})) {
|
|
514
|
+
hits.push({
|
|
515
|
+
...hit,
|
|
516
|
+
decision: GuardDecisions.ASK,
|
|
517
|
+
message: `${hit.message} (in a heredoc body whose delimiter never comes)`,
|
|
518
|
+
});
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
|
|
474
522
|
// Part of the line was not read: never an allow.
|
|
475
|
-
|
|
523
|
+
const unread = ShellUnread.reasonOf(parsed);
|
|
524
|
+
|
|
525
|
+
// The agent can write either again, so neither stops a person: a denial that says how.
|
|
526
|
+
if (unread !== undefined) {
|
|
476
527
|
hits.push({
|
|
477
|
-
decision: GuardDecisions.
|
|
528
|
+
decision: GuardDecisions.DENY,
|
|
478
529
|
rule: 'V-W-06',
|
|
479
|
-
message:
|
|
480
|
-
|
|
530
|
+
message: unread,
|
|
531
|
+
fix: 'write the line again with literal program names and paths, and quotes and substitutions that close',
|
|
481
532
|
});
|
|
482
533
|
}
|
|
483
534
|
|
|
484
535
|
if (isCapped) {
|
|
485
536
|
hits.push({
|
|
486
|
-
decision: GuardDecisions.
|
|
537
|
+
decision: GuardDecisions.DENY,
|
|
487
538
|
rule: 'V-W-06',
|
|
488
539
|
message:
|
|
489
540
|
'this command line needs more git or gh queries than the guard runs, so part of it could not be checked',
|
|
541
|
+
fix: 'run the git or gh commands in separate calls',
|
|
490
542
|
});
|
|
491
543
|
}
|
|
492
544
|
|