@zgeoff/skill-gate 0.2.1 → 0.2.3
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 +9 -10
- package/dist/index.js +1118 -0
- package/package.json +5 -9
- package/src/build-bash-skill-gate-output.ts +0 -41
- package/src/build-skill-gate-output.ts +0 -54
- package/src/collect-gate-skills.ts +0 -19
- package/src/collect-loaded-skills.ts +0 -98
- package/src/collect-written-paths.ts +0 -450
- package/src/format-skill-list.ts +0 -10
- package/src/index.ts +0 -1
- package/src/parse-shell-commands.ts +0 -429
- package/src/parse-skill-gate-rules.ts +0 -72
- package/src/plan-bash-skill-gate.ts +0 -21
- package/src/plan-skill-gate.ts +0 -21
- package/src/run-skill-gate.ts +0 -235
- package/src/types.ts +0 -96
package/src/run-skill-gate.ts
DELETED
|
@@ -1,235 +0,0 @@
|
|
|
1
|
-
import { statSync } from 'node:fs';
|
|
2
|
-
import path from 'node:path';
|
|
3
|
-
import { isRecord } from '@zgeoff/std';
|
|
4
|
-
import type { BunFile } from 'bun';
|
|
5
|
-
import { buildBashSkillGateOutput } from './build-bash-skill-gate-output.ts';
|
|
6
|
-
import { buildSkillGateOutput } from './build-skill-gate-output.ts';
|
|
7
|
-
import { collectLoadedSkills } from './collect-loaded-skills.ts';
|
|
8
|
-
import { collectWrittenPaths } from './collect-written-paths.ts';
|
|
9
|
-
import { parseSkillGateRules } from './parse-skill-gate-rules.ts';
|
|
10
|
-
import { planBashSkillGate } from './plan-bash-skill-gate.ts';
|
|
11
|
-
import { planSkillGate } from './plan-skill-gate.ts';
|
|
12
|
-
import type { WrittenPath } from './types.ts';
|
|
13
|
-
|
|
14
|
-
// The PreToolUse hook for Edit, Write, MultiEdit and Bash, which exits once it prints its output.
|
|
15
|
-
// The repo's own .claude/skill-gate.json holds the rules; a repo without that file has no gate. A
|
|
16
|
-
// subagent's loads come from its own transcript, never the main session's.
|
|
17
|
-
export async function runSkillGate(): Promise<never> {
|
|
18
|
-
const payload: unknown = await Bun.stdin.json().catch(() => null);
|
|
19
|
-
|
|
20
|
-
const input = parseHookInput(payload);
|
|
21
|
-
|
|
22
|
-
if (input === null) {
|
|
23
|
-
process.exit(0);
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
const projectDir = process.env['CLAUDE_PROJECT_DIR'] ?? input.cwd;
|
|
27
|
-
const rulesFile = Bun.file(path.join(projectDir, '.claude', 'skill-gate.json'));
|
|
28
|
-
|
|
29
|
-
const hasRules = await rulesFile.exists();
|
|
30
|
-
|
|
31
|
-
if (hasRules && input.command !== null) {
|
|
32
|
-
await checkBashCommand({ hookInput: input, command: input.command, projectDir, rulesFile });
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
if (input.filePath === null) {
|
|
36
|
-
process.exit(0);
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
const filePath = path.resolve(input.cwd, input.filePath);
|
|
40
|
-
const relativePath = toProjectPath(projectDir, filePath);
|
|
41
|
-
|
|
42
|
-
if (!hasRules || isOutsideProject(relativePath)) {
|
|
43
|
-
process.exit(0);
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
const rulesText = await rulesFile.text();
|
|
47
|
-
|
|
48
|
-
const parsed = parseSkillGateRules(rulesText);
|
|
49
|
-
|
|
50
|
-
if (!parsed.ok) {
|
|
51
|
-
printOutput(
|
|
52
|
-
buildSkillGateOutput(filePath, { missing: [], unknown: [] }, { rulesError: parsed.error }),
|
|
53
|
-
);
|
|
54
|
-
|
|
55
|
-
process.exit(0);
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
const availableSkills = await readAvailableSkills(path.join(projectDir, '.claude', 'skills'));
|
|
59
|
-
const transcript = await readTranscript(resolveSessionTranscriptPath(input));
|
|
60
|
-
|
|
61
|
-
const loaded = collectLoadedSkills(transcript);
|
|
62
|
-
|
|
63
|
-
const plan = planSkillGate({
|
|
64
|
-
rules: parsed.rules,
|
|
65
|
-
relativePath,
|
|
66
|
-
loadedSkills: loaded.skills,
|
|
67
|
-
availableSkills,
|
|
68
|
-
});
|
|
69
|
-
|
|
70
|
-
printOutput(buildSkillGateOutput(filePath, plan, { compacted: loaded.compacted }));
|
|
71
|
-
|
|
72
|
-
process.exit(0);
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
// An Edit, Write or MultiEdit call carries `file_path`, and a Bash call carries `command`.
|
|
76
|
-
interface HookInput {
|
|
77
|
-
readonly cwd: string;
|
|
78
|
-
readonly filePath: string | null;
|
|
79
|
-
readonly command: string | null;
|
|
80
|
-
readonly transcriptPath: string;
|
|
81
|
-
readonly agentID: unknown;
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
function parseHookInput(value: unknown): HookInput | null {
|
|
85
|
-
if (!isRecord(value) || !isRecord(value['tool_input'])) {
|
|
86
|
-
return null;
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
const cwd = value['cwd'];
|
|
90
|
-
const transcriptPath = value['transcript_path'];
|
|
91
|
-
const editPath = value['tool_input']['file_path'];
|
|
92
|
-
const command = value['tool_input']['command'];
|
|
93
|
-
|
|
94
|
-
if (typeof cwd !== 'string' || typeof transcriptPath !== 'string') {
|
|
95
|
-
return null;
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
if (typeof editPath !== 'string' && typeof command !== 'string') {
|
|
99
|
-
return null;
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
return {
|
|
103
|
-
cwd,
|
|
104
|
-
filePath: typeof editPath === 'string' ? editPath : null,
|
|
105
|
-
command: typeof command === 'string' ? command : null,
|
|
106
|
-
transcriptPath,
|
|
107
|
-
agentID: value['agent_id'],
|
|
108
|
-
};
|
|
109
|
-
}
|
|
110
|
-
|
|
111
|
-
interface BashCheck {
|
|
112
|
-
readonly hookInput: HookInput;
|
|
113
|
-
readonly command: string;
|
|
114
|
-
readonly projectDir: string;
|
|
115
|
-
readonly rulesFile: BunFile;
|
|
116
|
-
}
|
|
117
|
-
|
|
118
|
-
// Warns on a command that writes a gated path in the project and exits; any other command goes
|
|
119
|
-
// ahead in silence. A broken rules file lets every command through, since the next edit reports it.
|
|
120
|
-
async function checkBashCommand(check: BashCheck): Promise<void> {
|
|
121
|
-
const written = collectWrittenPaths(check.command).map((entry) =>
|
|
122
|
-
readWrittenPath(check.hookInput.cwd, entry),
|
|
123
|
-
);
|
|
124
|
-
|
|
125
|
-
const candidates = [...new Set(written)].filter(
|
|
126
|
-
(entry) => !isOutsideProject(toProjectPath(check.projectDir, entry)),
|
|
127
|
-
);
|
|
128
|
-
|
|
129
|
-
if (candidates.length === 0) {
|
|
130
|
-
process.exit(0);
|
|
131
|
-
}
|
|
132
|
-
|
|
133
|
-
const text = await check.rulesFile.text();
|
|
134
|
-
|
|
135
|
-
const parsedRules = parseSkillGateRules(text);
|
|
136
|
-
|
|
137
|
-
if (!parsedRules.ok) {
|
|
138
|
-
process.exit(0);
|
|
139
|
-
}
|
|
140
|
-
|
|
141
|
-
const skills = await readAvailableSkills(path.join(check.projectDir, '.claude', 'skills'));
|
|
142
|
-
const sessionTranscript = await readTranscript(resolveSessionTranscriptPath(check.hookInput));
|
|
143
|
-
|
|
144
|
-
const sessionLoads = collectLoadedSkills(sessionTranscript);
|
|
145
|
-
|
|
146
|
-
const bashPlan = planBashSkillGate({
|
|
147
|
-
rules: parsedRules.rules,
|
|
148
|
-
paths: candidates.map((entry) => ({
|
|
149
|
-
path: entry,
|
|
150
|
-
relativePath: toProjectPath(check.projectDir, entry),
|
|
151
|
-
})),
|
|
152
|
-
loadedSkills: sessionLoads.skills,
|
|
153
|
-
availableSkills: skills,
|
|
154
|
-
});
|
|
155
|
-
|
|
156
|
-
printOutput(
|
|
157
|
-
buildBashSkillGateOutput(bashPlan.gatedPaths, bashPlan.missing, {
|
|
158
|
-
compacted: sessionLoads.compacted,
|
|
159
|
-
}),
|
|
160
|
-
);
|
|
161
|
-
|
|
162
|
-
process.exit(0);
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
// A `cp` or `mv` onto an existing directory writes the source's file name inside it.
|
|
166
|
-
function readWrittenPath(cwd: string, written: WrittenPath): string {
|
|
167
|
-
const absolute = path.resolve(cwd, written.path);
|
|
168
|
-
|
|
169
|
-
if (written.fileName === undefined) {
|
|
170
|
-
return absolute;
|
|
171
|
-
}
|
|
172
|
-
|
|
173
|
-
const isDirectory = statSync(absolute, { throwIfNoEntry: false })?.isDirectory() === true;
|
|
174
|
-
|
|
175
|
-
return isDirectory ? path.join(absolute, written.fileName) : absolute;
|
|
176
|
-
}
|
|
177
|
-
|
|
178
|
-
function isOutsideProject(fromProject: string): boolean {
|
|
179
|
-
return fromProject === '..' || fromProject.startsWith('../') || path.isAbsolute(fromProject);
|
|
180
|
-
}
|
|
181
|
-
|
|
182
|
-
function toProjectPath(projectDir: string, absolute: string): string {
|
|
183
|
-
return path.relative(projectDir, absolute).split(path.sep).join('/');
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
async function readAvailableSkills(skillsDir: string): Promise<readonly string[]> {
|
|
187
|
-
const skills: string[] = [];
|
|
188
|
-
|
|
189
|
-
const scan = new Bun.Glob('*/SKILL.md').scan({ cwd: skillsDir, followSymlinks: true });
|
|
190
|
-
|
|
191
|
-
try {
|
|
192
|
-
for await (const match of scan) {
|
|
193
|
-
skills.push(path.dirname(match));
|
|
194
|
-
}
|
|
195
|
-
} catch {
|
|
196
|
-
// A repo without .claude/skills has no skills, so each rule reports its skills as unknown.
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
return skills;
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
async function readTranscript(transcriptPath: string | null): Promise<string> {
|
|
203
|
-
if (transcriptPath === null) {
|
|
204
|
-
return '';
|
|
205
|
-
}
|
|
206
|
-
|
|
207
|
-
const transcriptFile = Bun.file(transcriptPath);
|
|
208
|
-
|
|
209
|
-
const exists = await transcriptFile.exists();
|
|
210
|
-
|
|
211
|
-
return exists ? transcriptFile.text() : '';
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
// A subagent's call carries the main session's transcript_path plus its own agent_id, and Claude
|
|
215
|
-
// Code keeps its transcript at <session>/subagents/agent-<agent_id>.jsonl. An agent_id that is not
|
|
216
|
-
// a plain name resolves to no transcript, so the edit is denied.
|
|
217
|
-
function resolveSessionTranscriptPath(edit: HookInput): string | null {
|
|
218
|
-
if (edit.agentID === undefined) {
|
|
219
|
-
return edit.transcriptPath;
|
|
220
|
-
}
|
|
221
|
-
|
|
222
|
-
if (typeof edit.agentID !== 'string' || !/^[\w-]+$/u.test(edit.agentID)) {
|
|
223
|
-
return null;
|
|
224
|
-
}
|
|
225
|
-
|
|
226
|
-
const sessionDir = edit.transcriptPath.replace(/\.jsonl$/u, '');
|
|
227
|
-
|
|
228
|
-
return path.join(sessionDir, 'subagents', `agent-${edit.agentID}.jsonl`);
|
|
229
|
-
}
|
|
230
|
-
|
|
231
|
-
function printOutput(output: object | null): void {
|
|
232
|
-
if (output !== null) {
|
|
233
|
-
console.log(JSON.stringify(output));
|
|
234
|
-
}
|
|
235
|
-
}
|
package/src/types.ts
DELETED
|
@@ -1,96 +0,0 @@
|
|
|
1
|
-
export interface SkillGate {
|
|
2
|
-
readonly match: string;
|
|
3
|
-
readonly skills: readonly string[];
|
|
4
|
-
}
|
|
5
|
-
|
|
6
|
-
export interface SkillGateRules {
|
|
7
|
-
readonly ignore: readonly string[];
|
|
8
|
-
readonly gates: readonly SkillGate[];
|
|
9
|
-
}
|
|
10
|
-
|
|
11
|
-
export type SkillGateRulesResult =
|
|
12
|
-
| { readonly ok: true; readonly rules: SkillGateRules }
|
|
13
|
-
| { readonly ok: false; readonly error: string };
|
|
14
|
-
|
|
15
|
-
export interface UnknownSkill {
|
|
16
|
-
readonly match: string;
|
|
17
|
-
readonly skill: string;
|
|
18
|
-
}
|
|
19
|
-
|
|
20
|
-
export interface LoadedSkills {
|
|
21
|
-
readonly skills: readonly string[];
|
|
22
|
-
readonly compacted: boolean;
|
|
23
|
-
}
|
|
24
|
-
|
|
25
|
-
export interface SkillGateInput {
|
|
26
|
-
readonly rules: SkillGateRules;
|
|
27
|
-
readonly relativePath: string;
|
|
28
|
-
readonly loadedSkills: readonly string[];
|
|
29
|
-
readonly availableSkills: readonly string[];
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
// A path a Bash command writes inside the project: absolute, and relative to the project root.
|
|
33
|
-
export interface ProjectPath {
|
|
34
|
-
readonly path: string;
|
|
35
|
-
readonly relativePath: string;
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
export interface BashSkillGateInput {
|
|
39
|
-
readonly rules: SkillGateRules;
|
|
40
|
-
readonly paths: readonly ProjectPath[];
|
|
41
|
-
readonly loadedSkills: readonly string[];
|
|
42
|
-
readonly availableSkills: readonly string[];
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
export interface BashSkillGatePlan {
|
|
46
|
-
readonly gatedPaths: readonly string[];
|
|
47
|
-
readonly missing: readonly string[];
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
export interface SkillGatePlan {
|
|
51
|
-
readonly missing: readonly string[];
|
|
52
|
-
readonly unknown: readonly UnknownSkill[];
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
export interface ShellWord {
|
|
56
|
-
readonly text: string;
|
|
57
|
-
readonly literal: boolean;
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
export interface ShellRedirect {
|
|
61
|
-
readonly operator: string;
|
|
62
|
-
readonly target: ShellWord;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
// `enters` counts the subshells that open just before the command, and `leaves` the ones that
|
|
66
|
-
// close just after it.
|
|
67
|
-
export interface ShellCommand {
|
|
68
|
-
readonly words: readonly ShellWord[];
|
|
69
|
-
readonly redirects: readonly ShellRedirect[];
|
|
70
|
-
readonly stdin: string | null;
|
|
71
|
-
readonly enters: number;
|
|
72
|
-
readonly leaves: number;
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
// A path a Bash command writes, relative to the command's working directory unless absolute. With
|
|
76
|
-
// a `fileName`, as for `cp a.ts dest`, the write lands at `path/fileName` when `path` is a
|
|
77
|
-
// directory, and at `path` otherwise.
|
|
78
|
-
export interface WrittenPath {
|
|
79
|
-
readonly path: string;
|
|
80
|
-
readonly fileName?: string;
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
export interface SkillGateOutputContext {
|
|
84
|
-
readonly compacted?: boolean;
|
|
85
|
-
readonly rulesError?: string;
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
export interface SkillGateHookOutput {
|
|
89
|
-
readonly systemMessage?: string;
|
|
90
|
-
readonly hookSpecificOutput: {
|
|
91
|
-
readonly hookEventName: 'PreToolUse';
|
|
92
|
-
readonly permissionDecision?: 'deny';
|
|
93
|
-
readonly permissionDecisionReason?: string;
|
|
94
|
-
readonly additionalContext?: string;
|
|
95
|
-
};
|
|
96
|
-
}
|