@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
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { dirname, join, resolve } from 'node:path';
|
|
3
|
+
import { GuardDecisions } from './common/index.ts';
|
|
4
|
+
import { PackageRunners } from './package-runners.ts';
|
|
5
|
+
import type { IRunnerCall } from './package-runners.ts';
|
|
6
|
+
import { RunnerScan } from './runner-scan.ts';
|
|
7
|
+
import type { IRunnerUse } from './runner-scan.ts';
|
|
8
|
+
import { ShellFolders } from './shell-folders.ts';
|
|
9
|
+
import { ShellParser } from './shell.ts';
|
|
10
|
+
import type { ISimpleCommand } from './shell.ts';
|
|
11
|
+
|
|
12
|
+
/** One reason a command is refused: a package run by name. */
|
|
13
|
+
export interface IRunnerHit {
|
|
14
|
+
rule: 'V-S-08';
|
|
15
|
+
message: string;
|
|
16
|
+
decision: typeof GuardDecisions.DENY;
|
|
17
|
+
/** What the agent does instead; the denial is the agent's to repair, never handed to a person. */
|
|
18
|
+
fix: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* V-S-08 for an agent: a command that runs a package by name (`bunx`, `pnpx`, `bun x`, `npx`, `npm exec`, `pnpm dlx`,
|
|
23
|
+
* `yarn dlx`, also behind `corepack` or `xargs`) is denied. The name may belong to somebody else on npm, and bun runs a
|
|
24
|
+
* copy an earlier bunx saved even under `--no-install`. A scoped package (`@scope/name`) and the names of
|
|
25
|
+
* `guard.runners.allow` pass, and so does the `--no-install` form of `bun x` when `node_modules/.bin/<bin>` exists in the
|
|
26
|
+
* folder the command runs in or above it, with no flag but `--bun`, `--silent` and `--no-install`: that is the one case that
|
|
27
|
+
* cannot reach the cache. It reads the commands the parser found, so a word in a message, a grep or a heredoc is data.
|
|
28
|
+
*/
|
|
29
|
+
export class RunnerGuard {
|
|
30
|
+
/** Programs that run the command after their own options, which the shell parser does not unwrap. */
|
|
31
|
+
private static readonly LAUNCHERS: ReadonlySet<string> = new Set([
|
|
32
|
+
'xargs',
|
|
33
|
+
'nsenter',
|
|
34
|
+
'chroot',
|
|
35
|
+
'setsid',
|
|
36
|
+
'unshare',
|
|
37
|
+
]);
|
|
38
|
+
|
|
39
|
+
/** The runner a simple command is and the words after it, or `undefined` when it runs no package by name. */
|
|
40
|
+
private static runnerOf(opts: { command: ISimpleCommand }): IRunnerCall | undefined {
|
|
41
|
+
const program = ShellParser.programOf({ command: opts.command });
|
|
42
|
+
const name = ShellParser.basenameOf({ word: program.name });
|
|
43
|
+
|
|
44
|
+
if (!RunnerGuard.LAUNCHERS.has(name)) {
|
|
45
|
+
return PackageRunners.find({ program: name, args: program.args });
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
// `xargs bunx` runs the program with a name from its input: read the words after the launcher's own options as a command
|
|
49
|
+
for (let index = 0; index < program.args.length; index += 1) {
|
|
50
|
+
const word = ShellParser.basenameOf({ word: program.args[index] ?? '' });
|
|
51
|
+
|
|
52
|
+
if (PackageRunners.isProgram({ name: word }) || PackageRunners.WRAPPERS.has(word)) {
|
|
53
|
+
return PackageRunners.find({ program: word, args: program.args.slice(index + 1) });
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
return undefined;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Whether a command of the line moves the shell's folder in a way `ShellFolders` does not follow: `env -C <dir>`,
|
|
62
|
+
* `env --chdir=<dir>`, and `eval`, `source` or `.`, whose text is a line of its own. Then no folder is known.
|
|
63
|
+
*/
|
|
64
|
+
private static movesFolder(opts: { command: ISimpleCommand }): boolean {
|
|
65
|
+
const names = opts.command.words.map((word) => ShellParser.basenameOf({ word }));
|
|
66
|
+
const program = ShellParser.basenameOf({
|
|
67
|
+
word: ShellParser.programOf({ command: opts.command }).name,
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
if (
|
|
71
|
+
['eval', 'source', '.'].includes(program) ||
|
|
72
|
+
names.some((name) => ['eval', 'source'].includes(name))
|
|
73
|
+
) {
|
|
74
|
+
return true;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const at = names.indexOf('env');
|
|
78
|
+
const isChdir = (word: string): boolean => /^--chdir(?:=|$)/.test(word);
|
|
79
|
+
|
|
80
|
+
return (
|
|
81
|
+
(at !== -1 &&
|
|
82
|
+
opts.command.words
|
|
83
|
+
.slice(at + 1)
|
|
84
|
+
.some((word) => isChdir(word) || /^-[A-Za-z]*C/.test(word))) ||
|
|
85
|
+
(names.includes('sudo') &&
|
|
86
|
+
opts.command.words.some((word) => isChdir(word) || /^-[A-Za-z]*D/.test(word))) ||
|
|
87
|
+
names.includes('chroot') ||
|
|
88
|
+
(names.includes('nsenter') && opts.command.words.some((word) => /^(?:--wd|-w)/.test(word))) ||
|
|
89
|
+
(names.includes('find') &&
|
|
90
|
+
opts.command.words.some((word) => /^-(?:execdir|okdir)$/.test(word)))
|
|
91
|
+
);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Whether `node_modules/.bin/<name>` exists in `cwd` or a folder above it: bun resolves a linked bin up the tree. */
|
|
95
|
+
private static isLinked(opts: { name: string; cwd: string }): boolean {
|
|
96
|
+
if (!/^[a-z0-9][a-z0-9._-]*$/.test(opts.name)) {
|
|
97
|
+
return false;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
let directory = resolve(opts.cwd);
|
|
101
|
+
|
|
102
|
+
while (true) {
|
|
103
|
+
if (existsSync(join(directory, 'node_modules', '.bin', opts.name))) {
|
|
104
|
+
return true;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const parent = dirname(directory);
|
|
108
|
+
|
|
109
|
+
if (parent === directory) {
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
directory = parent;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
private static hitOf(opts: { use: IRunnerUse; name: string }): IRunnerHit {
|
|
118
|
+
const bin = RunnerScan.bareName({ name: opts.name });
|
|
119
|
+
const what =
|
|
120
|
+
opts.name === ''
|
|
121
|
+
? `\`${opts.use.runner}\` with no package named on its command line fetches whatever its input names`
|
|
122
|
+
: `\`${opts.use.runner} ${opts.name}\` fetches a package by name`;
|
|
123
|
+
|
|
124
|
+
return {
|
|
125
|
+
rule: 'V-S-08',
|
|
126
|
+
decision: GuardDecisions.DENY,
|
|
127
|
+
fix: `run bun node_modules/.bin/${bin === '' ? '<bin>' : bin} from the project root, or through a make target`,
|
|
128
|
+
message: `${what}, and npm may give that name to someone else (bun also runs a copy an earlier bunx saved, even with --no-install). Run \`bun node_modules/.bin/${bin === '' ? '<bin>' : bin}\` from the project root (the folder where the bin is linked), or through a make target; \`bun run ${bin === '' ? '<bin>' : bin}\` only as a fallback, because it falls back to $PATH and to a bun cache when the bin is not linked; the --no-install form is accepted only when node_modules/.bin/${bin === '' ? '<bin>' : bin} exists in the folder the command runs in and it has no other flag than --bun and --silent.`,
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
static inspect(opts: {
|
|
133
|
+
command: string;
|
|
134
|
+
cwd: string | undefined;
|
|
135
|
+
allow: string[];
|
|
136
|
+
env?: Record<string, string | undefined>;
|
|
137
|
+
/** False when `cwd` is only where the session started and not where the line runs (the string of an `npx -c` inside a folder change). */
|
|
138
|
+
isKnown?: boolean;
|
|
139
|
+
}): IRunnerHit[] {
|
|
140
|
+
const hits: IRunnerHit[] = [];
|
|
141
|
+
const parsed = ShellParser.parseChecked({ command: opts.command });
|
|
142
|
+
const commands = [...parsed.commands, ...parsed.unterminatedHeredocCommands];
|
|
143
|
+
const env = opts.env ?? process.env;
|
|
144
|
+
const start = resolve(opts.cwd ?? process.cwd());
|
|
145
|
+
const isFolderUnknown =
|
|
146
|
+
opts.isKnown === false || commands.some((command) => RunnerGuard.movesFolder({ command }));
|
|
147
|
+
const folders = ShellFolders.foldersOf({
|
|
148
|
+
commands,
|
|
149
|
+
cwd: start,
|
|
150
|
+
pwd: start,
|
|
151
|
+
isKnown: opts.isKnown,
|
|
152
|
+
home: env.HOME ?? '',
|
|
153
|
+
env,
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
for (const [index, command] of commands.entries()) {
|
|
157
|
+
const call = RunnerGuard.runnerOf({ command });
|
|
158
|
+
|
|
159
|
+
if (call === undefined) {
|
|
160
|
+
continue;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
const use = RunnerScan.useOf({ call, line: 0, isExample: false });
|
|
164
|
+
const name = RunnerScan.refusedName({ use, allow: opts.allow });
|
|
165
|
+
|
|
166
|
+
const folder = folders[index];
|
|
167
|
+
|
|
168
|
+
// `npx -c '<line>'` runs the line in a shell: it is read as a command line of its own, and passes when that has no runner
|
|
169
|
+
if (RunnerScan.isCommandString({ use })) {
|
|
170
|
+
const line = PackageRunners.commandStringOf({ words: call.words });
|
|
171
|
+
|
|
172
|
+
if (line !== undefined) {
|
|
173
|
+
hits.push(
|
|
174
|
+
...RunnerGuard.inspect({
|
|
175
|
+
command: line,
|
|
176
|
+
cwd: folder?.isKnown === true ? folder.base : start,
|
|
177
|
+
allow: opts.allow,
|
|
178
|
+
env,
|
|
179
|
+
isKnown: folder?.isKnown === true && !isFolderUnknown,
|
|
180
|
+
}),
|
|
181
|
+
);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
if (name === undefined) {
|
|
188
|
+
continue;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
const isLinked =
|
|
192
|
+
use.hasNoInstall &&
|
|
193
|
+
use.packageName === undefined &&
|
|
194
|
+
use.flags.every((flag) => PackageRunners.HARMLESS.has(flag)) &&
|
|
195
|
+
!isFolderUnknown &&
|
|
196
|
+
folder?.isKnown === true &&
|
|
197
|
+
RunnerGuard.isLinked({ name, cwd: folder.base });
|
|
198
|
+
|
|
199
|
+
if (!isLinked) {
|
|
200
|
+
hits.push(RunnerGuard.hitOf({ use, name }));
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
return hits;
|
|
205
|
+
}
|
|
206
|
+
}
|
|
@@ -1,207 +1,101 @@
|
|
|
1
|
-
import { existsSync, readFileSync, statSync } from 'node:fs';
|
|
2
|
-
import { isAbsolute, resolve } from 'node:path';
|
|
3
1
|
import { HookConstants } from './common/index.ts';
|
|
4
|
-
import {
|
|
5
|
-
import type { IHookCommand, IReadOnlyScript, IWriteCheck, IWriteHit } from './common/index.ts';
|
|
2
|
+
import type { IHookCommand, IWriteCheck, IWriteHit } from './common/index.ts';
|
|
6
3
|
import { CommandView } from './command-view.ts';
|
|
4
|
+
import type { ICommandView } from './command-view.ts';
|
|
7
5
|
import { HookDecision } from './decision.ts';
|
|
8
6
|
import type { IProjectCommandCheck } from './project-guards.ts';
|
|
7
|
+
import { ScriptRunners } from './script-runners.ts';
|
|
8
|
+
import { WriteCommands } from './write-commands.ts';
|
|
9
9
|
import { ShellParser } from './shell.ts';
|
|
10
|
-
import {
|
|
11
|
-
|
|
12
|
-
const MUTATING_VERB = '(?:POST|PUT|PATCH|DELETE)';
|
|
13
|
-
|
|
14
|
-
/** Ordered by how much damage the action does. */
|
|
15
|
-
const COMMAND_CHECKS: IWriteCheck[] = [
|
|
16
|
-
{
|
|
17
|
-
rule: 'V-W-03',
|
|
18
|
-
what: 'deploying or hot-applying to a cluster',
|
|
19
|
-
pattern:
|
|
20
|
-
/\bkubectl\s+(apply|patch|delete|scale|rollout)\b|\bdocker\s+compose\s+(up|down|restart)\b|\.\/kc\s+(apply|patch|delete)\b/,
|
|
21
|
-
},
|
|
22
|
-
{
|
|
23
|
-
rule: 'V-W-02',
|
|
24
|
-
what: 'running a migration instead of handing it to the human',
|
|
25
|
-
pattern:
|
|
26
|
-
/\bdb:migrate\b|\bmigrate:(dev|local|alpha|develop)\b|drizzle-kit\s+(push|migrate)\b|make\s+db-migrate\b/,
|
|
27
|
-
},
|
|
28
|
-
{
|
|
29
|
-
rule: 'V-W-02',
|
|
30
|
-
what: 'writing to a database',
|
|
31
|
-
pattern:
|
|
32
|
-
/\b(psql|mysql|mongosh|sqlite3)\b[^|]*?\b(insert|update|delete|truncate|drop|alter|create|grant|revoke)\s/i,
|
|
33
|
-
},
|
|
34
|
-
{
|
|
35
|
-
rule: 'V-W-02',
|
|
36
|
-
what: 'writing to a database through a SQL file whose contents this check cannot see',
|
|
37
|
-
pattern: /\b(psql|mysql)\b[^|]*\s-f\s/,
|
|
38
|
-
},
|
|
39
|
-
{
|
|
40
|
-
rule: 'V-W-02',
|
|
41
|
-
what: 'calling an endpoint that mutates data',
|
|
42
|
-
pattern: /\bcurl\b[^|]*(-X\s*(POST|PUT|PATCH|DELETE)|--data|--upload-file|-d\s)/i,
|
|
43
|
-
},
|
|
44
|
-
];
|
|
45
|
-
|
|
46
|
-
/** A `bun x.ts` command hides its real work inside the file, so the file is read too. */
|
|
47
|
-
const SCRIPT_CHECKS: IWriteCheck[] = [
|
|
48
|
-
{
|
|
49
|
-
rule: 'V-W-02',
|
|
50
|
-
what: 'calling an endpoint that mutates data',
|
|
51
|
-
pattern: new RegExp(
|
|
52
|
-
[
|
|
53
|
-
`method\\s*:\\s*['"\`]${MUTATING_VERB}['"\`]`,
|
|
54
|
-
'\\.(?:post|put|patch|delete)\\s*\\(',
|
|
55
|
-
`['"\`]${MUTATING_VERB}['"\`]\\s*,\\s*['"\`]/`,
|
|
56
|
-
].join('|'),
|
|
57
|
-
'i',
|
|
58
|
-
),
|
|
59
|
-
},
|
|
60
|
-
{
|
|
61
|
-
rule: 'V-W-02',
|
|
62
|
-
what: 'calling an endpoint that mutates data',
|
|
63
|
-
pattern: new RegExp(`(?=[\\s\\S]*\\bfetch\\s*\\()[\\s\\S]*['"\`]${MUTATING_VERB}['"\`]`, 'i'),
|
|
64
|
-
},
|
|
65
|
-
{
|
|
66
|
-
rule: 'V-W-02',
|
|
67
|
-
what: 'writing to a database',
|
|
68
|
-
pattern:
|
|
69
|
-
/\b(INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM|TRUNCATE|DROP\s+TABLE|ALTER\s+TABLE)\b/i,
|
|
70
|
-
},
|
|
71
|
-
];
|
|
72
|
-
|
|
73
|
-
const extractScriptTargets = (opts: { command: string }): string[] =>
|
|
74
|
-
[...opts.command.matchAll(/\bbun\s+(?:run\s+)?(\S+\.ts)\b/g)].map((match) => match[1]);
|
|
75
|
-
|
|
76
|
-
/**
|
|
77
|
-
* The files a script word can mean. `bun x.ts` opens the path as the OS does, following a link before a `..`;
|
|
78
|
-
* `bun run x.ts` folds the `..` as text first. Both are read, so neither spelling hides the other.
|
|
79
|
-
*/
|
|
80
|
-
const scriptPathsOf = (opts: { target: string; cwd: string }): string[] => [
|
|
81
|
-
...new Set([ScriptPaths.targetPath(opts), resolve(opts.cwd, opts.target)]),
|
|
82
|
-
];
|
|
83
|
-
|
|
84
|
-
/** The text of a regular file; a folder, a pipe and a missing path read as nothing, so nothing is opened that can block. */
|
|
85
|
-
const readScript = (opts: { path: string }): string | undefined =>
|
|
86
|
-
existsSync(opts.path) && statSync(opts.path).isFile()
|
|
87
|
-
? readFileSync(opts.path, 'utf8')
|
|
88
|
-
: undefined;
|
|
10
|
+
import type { ISimpleCommand } from './shell.ts';
|
|
89
11
|
|
|
90
12
|
const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
|
|
91
13
|
typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
|
|
92
14
|
|
|
15
|
+
interface IInspectOptions {
|
|
16
|
+
command: string;
|
|
17
|
+
/** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
|
|
18
|
+
extra?: IProjectCommandCheck[];
|
|
19
|
+
}
|
|
20
|
+
|
|
93
21
|
export class WriteGuard {
|
|
94
22
|
/**
|
|
95
|
-
* Every reason `command` looks like a write the base rules reserve for a human (V-W-02, V-W-03)
|
|
96
|
-
* `
|
|
97
|
-
*
|
|
98
|
-
* on the command line itself always run, and a listed script that git says changed is checked like any other.
|
|
99
|
-
* `trust.readOnlyScripts` (`guard.writes.trustedScripts` objects, from the manifest) skips them for one call: the
|
|
100
|
-
* word right after the script is one of the entry's `readOnly` words and the script is tracked and equals HEAD.
|
|
23
|
+
* Every reason `command` looks like a write the base rules reserve for a human (V-W-02, V-W-03): a command of
|
|
24
|
+
* the table (`WriteCommands`) or of the project's own list, in each simple command the shell parser finds, and
|
|
25
|
+
* what a database client is given that the line does not show.
|
|
101
26
|
*/
|
|
102
|
-
static inspectCommand(opts: {
|
|
103
|
-
command: string;
|
|
104
|
-
cwd: string;
|
|
105
|
-
trust?: { root: string; scripts: string[]; readOnlyScripts?: IReadOnlyScript[] };
|
|
106
|
-
/** The project's own commands (`guard.writes.commands`), checked beside the fixed list. */
|
|
107
|
-
extra?: IProjectCommandCheck[];
|
|
108
|
-
}): IWriteHit[] {
|
|
27
|
+
static inspectCommand(opts: IInspectOptions): IWriteHit[] {
|
|
109
28
|
// The patterns run on what the command runs, not on its text: a heredoc written to a file, the pattern
|
|
110
29
|
// of an `rg` and a commit message are data.
|
|
111
|
-
const
|
|
112
|
-
const
|
|
113
|
-
...
|
|
114
|
-
...(opts.extra ?? []).map((check) => ({
|
|
30
|
+
const view = CommandView.viewOf({ command: opts.command, withMessages: true });
|
|
31
|
+
const hits: IWriteHit[] = [
|
|
32
|
+
...WriteGuard.commandChecksOf({ view, extra: opts.extra }).map((check) => ({
|
|
115
33
|
rule: check.rule,
|
|
116
|
-
|
|
117
|
-
pattern: check.pattern,
|
|
34
|
+
message: check.what,
|
|
118
35
|
})),
|
|
36
|
+
...view.commands.flatMap((command) => WriteCommands.inspectClient({ command })),
|
|
119
37
|
];
|
|
120
|
-
const
|
|
121
|
-
.filter((check) => texts.some((text) => check.pattern.test(text)))
|
|
122
|
-
.map((check) => ({
|
|
123
|
-
rule: check.rule,
|
|
124
|
-
message: check.what,
|
|
125
|
-
}));
|
|
126
|
-
|
|
127
|
-
const targets = extractScriptTargets({ command: texts.join('\n') });
|
|
128
|
-
const entries = opts.trust?.readOnlyScripts ?? [];
|
|
129
|
-
// A subcommand counts only when the shell's own words give the same scripts in the same order as the text
|
|
130
|
-
// does; any other line (a script named in an argument, a pipe into a runner) is read as a whole.
|
|
131
|
-
const invocations = ReadOnlyScripts.extractInvocations({ command: opts.command });
|
|
132
|
-
const isPaired =
|
|
133
|
-
invocations.length === targets.length &&
|
|
134
|
-
invocations.every((invocation, index) => invocation.script === targets[index]);
|
|
135
|
-
const hasMoving = texts.some((text) =>
|
|
136
|
-
ShellParser.parse({ command: text }).some((command) =>
|
|
137
|
-
ReadOnlyScripts.MOVING_COMMANDS.has(
|
|
138
|
-
ShellParser.basenameOf({ word: ShellParser.programOf({ command }).name }),
|
|
139
|
-
),
|
|
140
|
-
),
|
|
141
|
-
);
|
|
38
|
+
const keys = new Set<string>();
|
|
142
39
|
|
|
143
|
-
|
|
144
|
-
const
|
|
145
|
-
.map((path) => readScript({ path }))
|
|
146
|
-
.filter((text): text is string => text !== undefined);
|
|
40
|
+
return hits.filter((hit) => {
|
|
41
|
+
const key = `${hit.rule}\n${hit.message}`;
|
|
147
42
|
|
|
148
|
-
if (
|
|
149
|
-
|
|
43
|
+
if (keys.has(key)) {
|
|
44
|
+
return false;
|
|
150
45
|
}
|
|
151
46
|
|
|
152
|
-
|
|
153
|
-
// After a `cd` the hook does not know the folder a relative script word is from, so no entry covers it.
|
|
154
|
-
const isFromUnknownFolder =
|
|
155
|
-
!isAbsolute(target) && (isPaired ? invocations[index]?.moved === true : hasMoving);
|
|
156
|
-
// An entry covers the word only when both spellings of it (see `scriptPathsOf`) name that same entry.
|
|
157
|
-
const covered = (lookup: (spelling: { target: string }) => string | undefined) => {
|
|
158
|
-
const asWritten = lookup({ target });
|
|
159
|
-
|
|
160
|
-
return asWritten === lookup({ target: resolve(opts.cwd, target) }) ? asWritten : undefined;
|
|
161
|
-
};
|
|
162
|
-
const trusted = opts.trust;
|
|
163
|
-
const listed =
|
|
164
|
-
trusted === undefined || isFromUnknownFolder
|
|
165
|
-
? undefined
|
|
166
|
-
: (covered((spelling) =>
|
|
167
|
-
ScriptTrust.listedOf({
|
|
168
|
-
target: spelling.target,
|
|
169
|
-
cwd: opts.cwd,
|
|
170
|
-
root: trusted.root,
|
|
171
|
-
scripts: trusted.scripts,
|
|
172
|
-
}),
|
|
173
|
-
) ??
|
|
174
|
-
(subcommand === undefined
|
|
175
|
-
? undefined
|
|
176
|
-
: covered((spelling) =>
|
|
177
|
-
ReadOnlyScripts.find({
|
|
178
|
-
target: spelling.target,
|
|
179
|
-
subcommand,
|
|
180
|
-
cwd: opts.cwd,
|
|
181
|
-
root: trusted.root,
|
|
182
|
-
entries,
|
|
183
|
-
}),
|
|
184
|
-
)));
|
|
185
|
-
const trust =
|
|
186
|
-
listed === undefined || opts.trust === undefined
|
|
187
|
-
? undefined
|
|
188
|
-
: ScriptTrust.trustOf({ root: opts.trust.root, script: listed });
|
|
189
|
-
|
|
190
|
-
if (trust?.state === TrustStates.TRUSTED) {
|
|
191
|
-
continue;
|
|
192
|
-
}
|
|
47
|
+
keys.add(key);
|
|
193
48
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
hits.push({
|
|
198
|
-
rule: check.rule,
|
|
199
|
-
message: `${target} looks like it is ${check.what}${trust === undefined ? '' : ` (listed in guard.writes.trustedScripts, but not trusted: ${trust.reason})`}`,
|
|
200
|
-
});
|
|
201
|
-
}
|
|
202
|
-
}
|
|
49
|
+
return true;
|
|
50
|
+
});
|
|
51
|
+
}
|
|
203
52
|
|
|
204
|
-
|
|
53
|
+
/**
|
|
54
|
+
* The table's checks that match what a command line runs, and the project's own patterns. A check of the
|
|
55
|
+
* table does not apply to a call of its program that changes nothing (`--help`, `--dry-run`, `curl -G`); a
|
|
56
|
+
* whole line that pipes into a runner (no command behind it) always counts.
|
|
57
|
+
*/
|
|
58
|
+
private static commandChecksOf(opts: {
|
|
59
|
+
view: ICommandView;
|
|
60
|
+
extra: IProjectCommandCheck[] | undefined;
|
|
61
|
+
}): IWriteCheck[] {
|
|
62
|
+
const { texts, sources } = opts.view;
|
|
63
|
+
const fixed = WriteCommands.CHECKS.filter((check) =>
|
|
64
|
+
texts.some((text, index) => {
|
|
65
|
+
const command = sources[index];
|
|
66
|
+
|
|
67
|
+
if (command === undefined) {
|
|
68
|
+
return check.pattern.test(text);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const { program, args } = WriteGuard.callOf({ command });
|
|
72
|
+
const { script } = ScriptRunners.callOf({ program, args });
|
|
73
|
+
// `python manage.py migrate --plan`: the script is the program the row names.
|
|
74
|
+
const named = script === undefined ? program : ShellParser.basenameOf({ word: script });
|
|
75
|
+
|
|
76
|
+
return (
|
|
77
|
+
WriteCommands.isLive({ check, program, args }) &&
|
|
78
|
+
WriteCommands.isLive({ check, program: named, args }) &&
|
|
79
|
+
check.pattern.test(text)
|
|
80
|
+
);
|
|
81
|
+
}),
|
|
82
|
+
);
|
|
83
|
+
const project = (opts.extra ?? [])
|
|
84
|
+
.map((check) => ({
|
|
85
|
+
rule: check.rule,
|
|
86
|
+
what: `${check.what} (this project's pattern)`,
|
|
87
|
+
pattern: check.pattern,
|
|
88
|
+
}))
|
|
89
|
+
.filter((check) => texts.some((text) => check.pattern.test(text)));
|
|
90
|
+
|
|
91
|
+
return [...fixed, ...project];
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The program a simple command runs, past wrappers (`sudo`, `env`) and launchers (`npx` then a program, `uv run`). */
|
|
95
|
+
private static callOf(opts: { command: ISimpleCommand }): { program: string; args: string[] } {
|
|
96
|
+
const launched = ScriptRunners.launchedOf(ShellParser.programOf({ command: opts.command }));
|
|
97
|
+
|
|
98
|
+
return { program: ShellParser.basenameOf({ word: launched.name }), args: launched.args };
|
|
205
99
|
}
|
|
206
100
|
|
|
207
101
|
/** The Bash command and cwd from the hook's JSON; `undefined` when it is not what Claude Code sends. */
|
|
@@ -212,7 +106,7 @@ export class WriteGuard {
|
|
|
212
106
|
payload = JSON.parse(opts.text);
|
|
213
107
|
} catch (error) {
|
|
214
108
|
console.error(
|
|
215
|
-
`[WriteGuard.parseHookCommand] unreadable hook input
|
|
109
|
+
`[WriteGuard.parseHookCommand] unreadable hook input | ${error instanceof Error ? error.message : String(error)}`,
|
|
216
110
|
);
|
|
217
111
|
|
|
218
112
|
return undefined;
|
|
@@ -234,15 +128,24 @@ export class WriteGuard {
|
|
|
234
128
|
: undefined;
|
|
235
129
|
}
|
|
236
130
|
|
|
237
|
-
|
|
131
|
+
/** The hits the reason lists; a line of many commands can find dozens. */
|
|
132
|
+
private static readonly MAX_LISTED_HITS = 20;
|
|
133
|
+
|
|
134
|
+
static buildDecision(opts: { hits: IWriteHit[]; asks?: string; asksNote?: string }) {
|
|
135
|
+
const listed = opts.hits.slice(0, WriteGuard.MAX_LISTED_HITS);
|
|
136
|
+
const unlisted = opts.hits.length - listed.length;
|
|
137
|
+
|
|
238
138
|
return HookDecision.forHost({
|
|
139
|
+
asks: opts.asks,
|
|
140
|
+
asksNote: opts.asksNote,
|
|
239
141
|
output: {
|
|
240
142
|
hookSpecificOutput: {
|
|
241
143
|
hookEventName: HookConstants.PRE_TOOL_USE,
|
|
242
144
|
permissionDecision: HookConstants.GUARD_DECISION,
|
|
243
145
|
permissionDecisionReason: [
|
|
244
146
|
`This command looks like ${opts.hits.length === 1 ? 'an action' : 'actions'} the base rules reserve for a human:`,
|
|
245
|
-
...
|
|
147
|
+
...listed.map((hit) => ` - ${hit.rule}: ${hit.message}`),
|
|
148
|
+
...(unlisted > 0 ? [` - and ${unlisted} more`] : []),
|
|
246
149
|
'',
|
|
247
150
|
'The rules reject "it is only dev", "it is only a test row" and "it is reversible".',
|
|
248
151
|
'Produce the script, the SQL or the manifest and hand it over instead of running it.',
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import type { IManifestHookInput } from './common/index.ts';
|
|
2
|
+
|
|
3
|
+
/** The shell tool under the names the hosts give it: Cursor's `Shell`, and a lower-case `bash`. */
|
|
4
|
+
const SHELL_NAMES = new Set(['Shell', 'shell', 'bash']);
|
|
5
|
+
|
|
6
|
+
const BASH_TOOL = 'Bash';
|
|
7
|
+
|
|
8
|
+
const isRecord = (opts: { value: unknown }): opts is { value: Record<string, unknown> } =>
|
|
9
|
+
typeof opts.value === 'object' && opts.value !== null && !Array.isArray(opts.value);
|
|
10
|
+
|
|
11
|
+
const toText = (opts: { value: unknown }): string | undefined =>
|
|
12
|
+
typeof opts.value === 'string' && opts.value !== '' ? opts.value : undefined;
|
|
13
|
+
|
|
14
|
+
/** The tool name, with the shell tool of another host read as Claude's `Bash`. */
|
|
15
|
+
const toolOf = (opts: { value: unknown }): string | undefined => {
|
|
16
|
+
const name = toText(opts);
|
|
17
|
+
|
|
18
|
+
return name !== undefined && SHELL_NAMES.has(name) ? BASH_TOOL : name;
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
export class HookInput {
|
|
22
|
+
/** The tool call from the hook's JSON; `undefined` when it is not what Claude Code sends. */
|
|
23
|
+
static parse(opts: { text: string }): IManifestHookInput | undefined {
|
|
24
|
+
let payload: unknown;
|
|
25
|
+
|
|
26
|
+
try {
|
|
27
|
+
payload = JSON.parse(opts.text);
|
|
28
|
+
} catch (error) {
|
|
29
|
+
console.error(
|
|
30
|
+
`[HookInput.parse] unreadable hook input | ${error instanceof Error ? error.message : String(error)}`,
|
|
31
|
+
);
|
|
32
|
+
|
|
33
|
+
return undefined;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const holder = { value: payload };
|
|
37
|
+
|
|
38
|
+
if (!isRecord(holder)) {
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// The wire names are snake_case; they stay behind string-literal access here, at the boundary (V-C-14).
|
|
43
|
+
const toolInput = { value: holder.value['tool_input'] };
|
|
44
|
+
const input = isRecord(toolInput) ? toolInput.value : {};
|
|
45
|
+
const tool = toolOf({ value: holder.value['tool_name'] });
|
|
46
|
+
|
|
47
|
+
return tool === undefined
|
|
48
|
+
? undefined
|
|
49
|
+
: {
|
|
50
|
+
tool,
|
|
51
|
+
filePath:
|
|
52
|
+
toText({ value: input['file_path'] }) ?? toText({ value: input['notebook_path'] }),
|
|
53
|
+
command: toText({ value: input['command'] }),
|
|
54
|
+
cwd: toText({ value: holder.value['cwd'] }),
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
}
|
package/src/hooks/index.ts
CHANGED
|
@@ -1,18 +1,15 @@
|
|
|
1
1
|
export * from './common/index.ts';
|
|
2
2
|
export * from './decision.ts';
|
|
3
|
+
export * from './git-queries.ts';
|
|
3
4
|
export * from './guard-git.ts';
|
|
4
|
-
export * from './guard-
|
|
5
|
+
export * from './guard-runner.ts';
|
|
6
|
+
export * from './hook-input.ts';
|
|
5
7
|
export * from './guard-outside.ts';
|
|
6
|
-
export * from './guard-package.ts';
|
|
7
|
-
export * from './guard-scripting.ts';
|
|
8
8
|
export * from './guard-writes.ts';
|
|
9
|
-
export * from './trusted-scripts.ts';
|
|
10
9
|
export * from './session-digest.ts';
|
|
11
10
|
export * from './subagent-card.ts';
|
|
12
|
-
export * from './owner-reply.ts';
|
|
13
11
|
export * from './project-tmp.ts';
|
|
14
12
|
export * from './project-guards.ts';
|
|
15
|
-
export * from './remote-hosts.ts';
|
|
16
13
|
export * from './codex-patch.ts';
|
|
17
14
|
export * from './shell.ts';
|
|
18
15
|
export * from './command-view.ts';
|