diff --git a/AGENTS.md b/AGENTS.md index 0a7c876..7057fd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,7 +34,7 @@ node scripts/check-links.js 'https://example.com/' [''…] # each o Things that catch contributors out: - A rendered report can be corrected by copying its archive JSON back to `kosh-reports/data/qa-report-.json`, editing the text and running `run-qa-report.sh` again. It counts as a correction when its seal holds and an archived JSON has the same seal; a refused report is sealed too but never archived, so a retry still merges. The merge restores `url`, `pages[]`, `inventory[]` and `linkChecks[]` from that copy, whatever the edit did to them, and the seal keeps the timestamp and `heldTo`. It leaves the session's capture, one held for a retry and the link record for their own runs. Functional's findings are still numbered, so an ID can change between copies, and their `fixAt` checked. If a browser that isn't in the run's capture has loaded the site since, it's refused, since that's how a new run reusing an old report looks: finish the later run first, or save the copy under another name, which skips the merge. So does editing the archive copy in place, and nothing restores its measurements. Earlier copies move aside under the run's timestamp, then `-2` and so on, and every copy gets the capture its hash covers, even under a new website name. -- `hooks/guard-capture.js` refuses edits to `capture*.jsonl` files and the link checker's `links*.jsonl` record in `kosh-reports/data/`, and anything naming this session's capture or record, since the merge seals both into a report as kosh's own. For commands that can reach a `kosh-reports/` kosh has run in (one holding a capture: anywhere in the session's project, or a run folder or a path in its `kosh-reports/` named by absolute path), it also refuses `*.jsonl` globs and any `rm` or `mv` of `kosh-reports/`, `kosh-reports/data`, the archive, or a glob of their contents, so clearing them is done by hand. +- `hooks/guard-capture.js` refuses edits to `capture*.jsonl` files and the link checker's `links*.jsonl` record in `kosh-reports/data/`, and anything naming this session's capture or record, since the merge seals both into a report as kosh's own. For commands that can reach a `kosh-reports/` kosh has run in (one holding a capture: anywhere in the session's project, or a run folder or a path in its `kosh-reports/` named by absolute path), it also refuses `*.jsonl` globs and any `rm` or `mv` of `kosh-reports/`, `kosh-reports/data`, the archive, or a glob of their contents, so clearing them is done by hand. Plugin hooks run on every Bash and edit call in every project, so `hooks/guard-capture.sh` starts Node only when the call's `command` or `file_path`, the only fields the guard reads, names `capture`, `links`, `jsonl` or `kosh-reports`, a word every rule needs; a rule that matches without one would be skipped, and the tests run every case through it. Without `node` on PATH it refuses such a call, since a guard that can't run shouldn't pass it. - The merge keeps only the visits from the last browser that loaded the report's host, since a performance run starts with `browser_close`. A skill that closes the browser mid-run drops what it measured before. - `kosh-reports/` is the project's, not kosh's: `$CLAUDE_PROJECT_DIR/kosh-reports`, which Claude Code sets for the capture and the hooks. Bash commands don't get it, so the scripts use the nearest `kosh-reports/data` at or above the cwd, looking no higher than the git root, else `kosh-reports/` in the cwd. The name is kosh's own so a project's `reports/` never gets client data mixed in. If `kosh-reports/.gitignore` is missing, the capture adds one (`*`) when it creates `data/`, and so does every successful render, even when Playwright made the folder first, since reports hold client URLs and console text. Schemas, skills and `plugin.json` still resolve from kosh's own folder. `KOSH_REPORTS_DIR` moves where the scripts and the capture look (the tests use it), not where the skills write. diff --git a/hooks/guard-capture.sh b/hooks/guard-capture.sh new file mode 100644 index 0000000..7681fe1 --- /dev/null +++ b/hooks/guard-capture.sh @@ -0,0 +1,12 @@ +#!/bin/sh +# Plugin hooks run on every Bash and edit call in every project, so Node starts only when a rule in guard-capture.js could match. +input=$(cat) +# The guard reads only command and file_path, so the transcript path (always .jsonl), the cwd and an edit's text never count. A key quoted inside a JSON string is escaped, so only real keys match. +printf '%s' "$input" \ + | grep -oE '"(file_path|command)"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' \ + | grep -qiE 'capture|links|jsonl|kosh-reports' || exit 0 +if ! command -v node >/dev/null 2>&1; then + echo "Blocked: kosh's capture guard needs node on PATH to check this call." >&2 + exit 2 +fi +printf '%s' "$input" | node "$(dirname "$0")/guard-capture.js" diff --git a/hooks/hooks.json b/hooks/hooks.json index 5d1c763..ba41853 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -6,7 +6,7 @@ "hooks": [ { "type": "command", - "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-capture.js\"" + "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-capture.sh\"" } ] }, diff --git a/tests/guard-capture.test.js b/tests/guard-capture.test.js index b59347c..438e6a0 100644 --- a/tests/guard-capture.test.js +++ b/tests/guard-capture.test.js @@ -7,6 +7,7 @@ const { spawnSync } = require('child_process'); const ROOT = path.join(__dirname, '..'); const HOOK = path.join(ROOT, 'hooks/guard-capture.js'); +const WRAPPER = path.join(ROOT, 'hooks/guard-capture.sh'); // KOSH and SPACED are folders kosh has run in, FRESH a clone no run has used yet, ELSEWHERE an unrelated project, // OTHER one whose kosh-reports/data holds a log that only looks like a capture, NESTED a project inside KOSH. @@ -36,14 +37,14 @@ const SESSION = '0b3f6c2e-5d1a'; const RECASED = path.join(path.dirname(KOSH), path.basename(KOSH).toUpperCase()); const caseInsensitiveDisk = fs.existsSync(RECASED); -// `reports: null` runs the guard as installed, with KOSH_REPORTS_DIR unset; `project` is the root Claude Code gives hooks. +// Every case goes through the shell pre-filter, so a block it skipped fails here. `reports: null` runs the guard as installed, with KOSH_REPORTS_DIR unset; `project` is the root Claude Code gives hooks. const guard = (input, { reports = KOSH, project, cwd = ROOT } = {}) => { const env = { ...process.env, KOSH_REPORTS_DIR: reports && path.join(reports, 'kosh-reports'), CLAUDE_PROJECT_DIR: project }; if (!reports) delete env.KOSH_REPORTS_DIR; if (!project) delete env.CLAUDE_PROJECT_DIR; - return spawnSync('node', [HOOK], { input: typeof input === 'string' ? input : JSON.stringify(input), encoding: 'utf8', cwd, env }); + return spawnSync('sh', [WRAPPER], { input: typeof input === 'string' ? input : JSON.stringify(input), encoding: 'utf8', cwd, env }); }; -const call = (tool_name, tool_input, cwd = KOSH) => ({ hook_event_name: 'PreToolUse', cwd, tool_name, tool_input }); +const call = (tool_name, tool_input, cwd = KOSH) => ({ hook_event_name: 'PreToolUse', transcript_path: '/Users/x/.claude/projects/p/s.jsonl', cwd, tool_name, tool_input }); for (const [name, input, options] of [ ['writing a capture', call('Write', { file_path: path.join(KOSH, 'kosh-reports/data/capture-0b3f6c2e-5d1a.jsonl'), content: '{}' })], @@ -154,9 +155,42 @@ for (const [name, input, options] of [ test('the plugin runs the guard before every write and shell command', () => { const entries = require(path.join(ROOT, 'hooks/hooks.json')).hooks.PreToolUse; - const guarded = entries.filter((entry) => entry.hooks.some((hook) => hook.command.includes('hooks/guard-capture.js'))); - assert.ok(fs.existsSync(HOOK)); + const guarded = entries.filter((entry) => entry.hooks.some((hook) => hook.command.includes('hooks/guard-capture.sh'))); + assert.ok(fs.existsSync(HOOK) && fs.existsSync(WRAPPER)); for (const tool of ['Write', 'Edit', 'MultiEdit', 'Bash']) { assert.ok(guarded.some((entry) => new RegExp(`^(?:${entry.matcher})$`).test(tool)), `${tool} is not guarded`); } }); + +// A PATH with the tools the pre-filter needs and no node. +const withoutNode = () => { + const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'kosh-guard-bin-')); + for (const tool of ['cat', 'grep', 'sed', 'dirname']) { + fs.symlinkSync(spawnSync('sh', ['-c', `command -v ${tool}`], { encoding: 'utf8' }).stdout.trim(), path.join(bin, tool)); + } + return bin; +}; + +test('without node, the guard blocks a call a rule could match and allows any other', (t) => { + const bin = withoutNode(); + t.after(() => fs.rmSync(bin, { recursive: true, force: true })); + const run = (input) => spawnSync('/bin/sh', [WRAPPER], { input: JSON.stringify(input), encoding: 'utf8', cwd: KOSH, env: { PATH: bin } }); + const blocked = run(call('Bash', { command: 'rm kosh-reports/data/capture-abc.jsonl' })); + assert.strictEqual(blocked.status, 2, blocked.stderr); + assert.match(blocked.stderr, /needs node/); + const allowed = run(call('Bash', { command: 'git status' })); + assert.strictEqual(allowed.status, 0, allowed.stderr); + // Claude Code's input always has a .jsonl transcript path, and a project folder can be named anything. + const real = run({ ...call('Bash', { command: 'git status' }, path.join(OTHER, 'kosh-reports/data/capture-links')), session_id: SESSION, transcript_path: `/Users/x/.claude/projects/p/${SESSION}.jsonl` }); + assert.strictEqual(real.status, 0, real.stderr); + const spaced = spawnSync('/bin/sh', [WRAPPER], { input: JSON.stringify({ transcript_path: '/p/s.jsonl', cwd: '/capture', tool_name: 'Bash', tool_input: { command: 'ls' } }, null, 1), encoding: 'utf8', cwd: KOSH, env: { PATH: bin } }); + assert.strictEqual(spaced.status, 0, spaced.stderr); + // The guard never reads an edit's text, so text that mentions captures doesn't need node. + for (const input of [ + call('Edit', { file_path: 'README.md', old_string: 'a', new_string: 'see the links and kosh-reports/data/capture-abc.jsonl' }), + call('Write', { file_path: 'docs/notes.md', content: '"command": "rm capture.jsonl"' }), + ]) { + const text = run(input); + assert.strictEqual(text.status, 0, text.stderr); + } +});