@webpieces/hook-runtime 0.0.1

package/src/core/command-scan.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Shared shell-command scanning for the bash guards.
+ *
+ * A guard that bans a command family (`git merge`, `git push`, …) must answer one question
+ * precisely: *does this command actually invoke `git <subcommand>`?* A bare
+ * `/\bgit\s+merge\b/.test(command)` gets that wrong in both directions:
+ *
+ *  - False positive: `grep 'git merge main' notes.md` or `echo "git rebase main"` merely MENTION
+ *    the phrase. A diagnostic grep was blocked this way while triaging the incident that motivated
+ *    the merge/rebase ban.
+ *  - False positive: `\b` sits between `e` and `-`, so `/\bgit\s+merge\b/` matches the read-only
+ *    `git merge-base origin/main HEAD` — which appears in this repo's own documented build command.
+ *
+ * Both classes vanish if you tokenize instead of substring-match: a command invokes git only when a
+ * segment's first word IS `git`, and the subcommand is then an exact token (`merge-base` is simply
+ * not the token `merge`). No lookahead regex needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandScanner = exports.CommandSegment = void 0;
+// Wrappers/prefixes that may precede the real command word (`sudo git merge`, `GIT_DIR=x git merge`).
+const COMMAND_PREFIXES = new Set(['sudo', 'command', 'nohup', 'time', 'env', 'exec']);
+// git's own global flags that consume the FOLLOWING token as their value, so
+// `git -C /some/path merge main` still resolves to the `merge` subcommand.
+const GIT_FLAGS_WITH_VALUE = new Set([
+    '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path',
+]);
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+// Package-manager wrappers that precede the real program (`pnpm exec vitest`, `npx nx`, `yarn build-all`).
+const RUNNERS = new Set(['pnpm', 'npm', 'yarn', 'npx', 'pnpx', 'bun', 'bunx']);
+// The runner's own verb, consumed with it: `pnpm run build-all` and `pnpm build-all` are one command.
+const RUNNER_VERBS = new Set(['run', 'run-script', 'exec', 'dlx', 'x']);
+/**
+ * One invoked segment of a command, plus the operator that joined it to its predecessor.
+ *
+ * `join === '|'` is what separates `git log | grep foo` (grep consumes the pipe — reads no file) from
+ * `grep foo src/` (grep reads the working tree). A guard that cares about which FILES a command
+ * reads cannot tell those apart from the segment text alone, because splitting on `|` throws exactly
+ * that fact away. `join === '&&'` vs `';'` is the same argument one operator over — see
+ * {@link SegmentJoin}. Data-only, so a class (per CLAUDE.md).
+ */
+class CommandSegment {
+    text;
+    join;
+    constructor(text, join) {
+        this.text = text;
+        this.join = join;
+    }
+}
+exports.CommandSegment = CommandSegment;
+class CommandScanner {
+    /**
+     * Split a raw command into individually-invoked segments.
+     *
+     * Splits on `&&`, `||`, `;`, `|`, `&`, newline, and the `(`/`)` of subshells and `$(…)` command
+     * substitution — the last of these matters, since it means `--base=$(git rebase main)` is scanned
+     * as its own `git rebase main` segment rather than hiding inside a `pnpm …` segment.
+     *
+     * Quoted spans are opaque: a separator inside quotes is literal text, so
+     * `git commit -m "fix; ship it"` stays one segment. (Corollary: a `$(…)` nested inside double
+     * quotes is not split out. Bash would expand it; we do not scan it. Contrived enough to accept.)
+     */
+    commandSegments(command) {
+        return this.segmentsWithJoins(command).map((s) => s.text);
+    }
+    /**
+     * commandSegments, but each segment also carries the OPERATOR that joined it to its predecessor.
+     * Only a guard reasoning about which files a segment reads, or about whether a failed first
+     * segment can stop the rest, needs that; everything else uses commandSegments, which is this
+     * method with the join dropped.
+     */
+    segmentsWithJoins(command) {
+        const segments = [];
+        let current = '';
+        let quote = null;
+        let join = 'none'; // the operator that ENDED the previous segment
+        for (let i = 0; i < command.length; i++) {
+            const ch = command[i];
+            if (quote !== null) {
+                current += ch;
+                // A backslash-escaped quote does not close the span (only meaningful inside "…").
+                if (ch === quote && command[i - 1] !== '\\')
+                    quote = null;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                quote = ch;
+                current += ch;
+                continue;
+            }
+            // The `&` of a REDIRECTION (`2>&1`, `1>&2`, `&>log`) is not a separator. Splitting on it
+            // tore `git fetch origin main 2>&1 | tail -5` into THREE segments — `git fetch … 2>`, `1`
+            // and `tail -5` — and the bare `1` is not an allowlisted command, so every guard that
+            // requires all segments to pass denied the command. That is `2>&1`, the single most common
+            // decoration an agent appends.
+            if (ch === '&' && command[i + 1] !== '&' && (current.trimEnd().endsWith('>') || command[i + 1] === '>')) {
+                current += ch;
+                continue;
+            }
+            if (ch === '\n' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === ')') {
+                // Consume the second char of `&&` / `||` so it does not start an empty segment.
+                const doubled = (ch === '|' || ch === '&') && command[i + 1] === ch;
+                if (doubled)
+                    i++;
+                segments.push(new CommandSegment(current, join));
+                // `|` pipes into the next segment; `||` is a separator, not a pipe.
+                join = doubled ? (ch + ch) : ch;
+                current = '';
+                continue;
+            }
+            current += ch;
+        }
+        segments.push(new CommandSegment(current, join));
+        return segments
+            .map((s) => new CommandSegment(s.text.trim(), s.join))
+            .filter((s) => s.text.length > 0);
+    }
+    /**
+     * One segment's shell words, with wrappers/env-assignments stripped, so `words('sudo cat a b')`
+     * is `['cat', 'a', 'b']`. The public view of the same tokenizer gitSubcommand uses — a guard that
+     * must inspect a NON-git command's arguments (which paths does this `grep` actually read?) needs
+     * the tokens, and re-splitting on whitespace in the guard would get quoting wrong.
+     */
+    words(segment) {
+        return this.stripPrefixes(this.tokenize(segment));
+    }
+    /**
+     * The git subcommand a segment invokes, or null when the segment does not invoke git at all
+     * (a different program, a mere mention inside quotes, an empty segment).
+     *
+     * Returns the subcommand as an EXACT token: `git merge-base …` yields `'merge-base'`, never `'merge'`.
+     */
+    gitSubcommand(segment) {
+        return this.gitSubcommandOf(this.stripPrefixes(this.tokenize(segment)));
+    }
+    /**
+     * gitSubcommand, for a caller that already holds the segment's effective words (ShellSegmentScan
+     * strips leading shell keywords, so `do git status` must be resolved from ITS words, not from the
+     * raw segment text where `do` is the command).
+     */
+    gitSubcommandOf(words) {
+        const tokens = this.stripPrefixes(words);
+        const at = this.gitSubcommandIndex(tokens);
+        return at === -1 ? null : tokens[at];
+    }
+    /**
+     * The ARGUMENTS following `git <subcommand>` in this segment, or null when the segment does not
+     * invoke that subcommand.
+     *
+     * `gitSubcommand` answers *which* subcommand; a guard that judges the subcommand's own flags needs
+     * the tokens after it, and slicing them in the guard would mean re-deriving where the subcommand
+     * sits — i.e. re-deriving the `sudo` / `env VAR=x` / `-C <path>` skipping this class exists to own.
+     * `git -C /x commit -m "msg"` yields `['-m', 'msg']`, never `['/x', 'commit', '-m', 'msg']`.
+     *
+     * The tokens are QUOTE-STRIPPED (see tokenize), so a quoted argument arrives as ONE token holding
+     * its literal text — newlines, backticks and all. That is what makes an argument's CONTENT
+     * inspectable at all.
+     */
+    gitSubcommandArgs(segment, subcommand) {
+        const tokens = this.stripPrefixes(this.tokenize(segment));
+        const at = this.gitSubcommandIndex(tokens);
+        if (at === -1 || tokens[at] !== subcommand)
+            return null;
+        return tokens.slice(at + 1);
+    }
+    /** Index of the subcommand token in already-prefix-stripped words, or -1 when git is not invoked. */
+    gitSubcommandIndex(tokens) {
+        if (tokens.length === 0 || tokens[0] !== 'git')
+            return -1;
+        let i = 1;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            if (GIT_FLAGS_WITH_VALUE.has(token)) {
+                i += 2;
+                continue;
+            }
+            // `--git-dir=/x` style (value attached) and any other global flag.
+            if (token.startsWith('-')) {
+                i++;
+                continue;
+            }
+            return i;
+        }
+        return -1;
+    }
+    /**
+     * The segment's words with the package-manager WRAPPER stripped, so `pnpm exec vitest run` and
+     * `vitest run` reduce to the same words. `pnpm --silent run build-all` → `['build-all']`.
+     *
+     * Lives HERE rather than in a guard because two guards now need it and they must agree: one blocks a
+     * whole-repo build, the other blocks piping a build's output. If they disagreed about whether
+     * `npx wp-build` is `wp-build`, one of them would have a spelling-shaped side door — which is exactly
+     * the failure mode the runner stripping exists to close.
+     */
+    runnerStrippedWords(segment) {
+        let words = this.words(segment);
+        while (words.length > 0 && RUNNERS.has(this.programName(words[0]))) {
+            words = words.slice(1);
+            // The runner's own flags (`--silent`, `-r`) sit between it and the program.
+            while (words.length > 0 && words[0].startsWith('-'))
+                words = words.slice(1);
+            if (words.length > 0 && RUNNER_VERBS.has(words[0]))
+                words = words.slice(1);
+        }
+        return words;
+    }
+    /** `./node_modules/.bin/nx` and `/usr/local/bin/pnpm.cmd` are the programs `nx` and `pnpm`. */
+    programName(token) {
+        const base = token.split('/').pop() ?? token;
+        return base.endsWith('.cmd') ? base.slice(0, -'.cmd'.length) : base;
+    }
+    /** True when a package-manager runner precedes the program (`pnpm …`, `npx …`). */
+    viaRunner(segment) {
+        const raw = this.words(segment);
+        return raw.length > 0 && RUNNERS.has(this.programName(raw[0]));
+    }
+    /** True when this segment actually invokes `git <subcommand>`. */
+    invokesGit(segment, subcommand) {
+        return this.gitSubcommand(segment) === subcommand;
+    }
+    /** True when ANY segment of the command invokes one of `subcommands`. */
+    commandInvokesAnyGit(command, subcommands) {
+        return this.commandSegments(command).some((seg) => subcommands.some((sub) => this.invokesGit(seg, sub)));
+    }
+    /**
+     * Split one segment into shell words, dropping quote characters (so the ARGUMENT of
+     * `echo "git merge main"` is the single word `git merge main`, never the word `git`).
+     */
+    tokenize(segment) {
+        const tokens = [];
+        let current = '';
+        let started = false;
+        let quote = null;
+        for (let i = 0; i < segment.length; i++) {
+            const ch = segment[i];
+            if (quote !== null) {
+                if (ch === quote)
+                    quote = null;
+                else
+                    current += ch;
+                started = true;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                quote = ch;
+                started = true;
+                continue;
+            }
+            if (/\s/.test(ch)) {
+                if (started) {
+                    tokens.push(current);
+                    current = '';
+                    started = false;
+                }
+                continue;
+            }
+            current += ch;
+            started = true;
+        }
+        if (started)
+            tokens.push(current);
+        return tokens;
+    }
+    stripPrefixes(tokens) {
+        let i = 0;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            if (COMMAND_PREFIXES.has(token)) {
+                i++;
+                continue;
+            }
+            if (ENV_ASSIGNMENT.test(token)) {
+                i++;
+                continue;
+            }
+            break;
+        }
+        return tokens.slice(i);
+    }
+}
+exports.CommandScanner = CommandScanner;
+//# sourceMappingURL=command-scan.js.map

package/src/core/command-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-scan.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/command-scan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared shell-command scanning for the bash guards.\n *\n * A guard that bans a command family (`git merge`, `git push`, …) must answer one question\n * precisely: *does this command actually invoke `git <subcommand>`?* A bare\n * `/\\bgit\\s+merge\\b/.test(command)` gets that wrong in both directions:\n *\n *  - False positive: `grep 'git merge main' notes.md` or `echo \"git rebase main\"` merely MENTION\n *    the phrase. A diagnostic grep was blocked this way while triaging the incident that motivated\n *    the merge/rebase ban.\n *  - False positive: `\\b` sits between `e` and `-`, so `/\\bgit\\s+merge\\b/` matches the read-only\n *    `git merge-base origin/main HEAD` — which appears in this repo's own documented build command.\n *\n * Both classes vanish if you tokenize instead of substring-match: a command invokes git only when a\n * segment's first word IS `git`, and the subcommand is then an exact token (`merge-base` is simply\n * not the token `merge`). No lookahead regex needed.\n */\n\n// Wrappers/prefixes that may precede the real command word (`sudo git merge`, `GIT_DIR=x git merge`).\nconst COMMAND_PREFIXES: ReadonlySet<string> = new Set(['sudo', 'command', 'nohup', 'time', 'env', 'exec']);\n\n// git's own global flags that consume the FOLLOWING token as their value, so\n// `git -C /some/path merge main` still resolves to the `merge` subcommand.\nconst GIT_FLAGS_WITH_VALUE: ReadonlySet<string> = new Set([\n    '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path',\n]);\n\nconst ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;\n\n// Package-manager wrappers that precede the real program (`pnpm exec vitest`, `npx nx`, `yarn build-all`).\nconst RUNNERS: ReadonlySet<string> = new Set(['pnpm', 'npm', 'yarn', 'npx', 'pnpx', 'bun', 'bunx']);\n\n// The runner's own verb, consumed with it: `pnpm run build-all` and `pnpm build-all` are one command.\nconst RUNNER_VERBS: ReadonlySet<string> = new Set(['run', 'run-script', 'exec', 'dlx', 'x']);\n\n/**\n * The shell operator that JOINED one segment to the one before it. `'none'` for the first segment.\n *\n * This used to be a single boolean, `pipedInto`, and the widening is what makes composition\n * judgeable. A pipe is only one of the joins whose MEANING differs: `cure && work` short-circuits, so\n * the work cannot run when the cure failed, while `cure ; work` discards the cure's exit code and\n * runs the work anyway. A boolean that answered only \"was it a pipe?\" threw that distinction away,\n * and a guard cannot refuse the dangerous join while allowing the safe one without it.\n */\nexport type SegmentJoin = 'none' | '|' | '&&' | '||' | ';' | '&' | '\\n' | '(' | ')';\n\n/**\n * One invoked segment of a command, plus the operator that joined it to its predecessor.\n *\n * `join === '|'` is what separates `git log | grep foo` (grep consumes the pipe — reads no file) from\n * `grep foo src/` (grep reads the working tree). A guard that cares about which FILES a command\n * reads cannot tell those apart from the segment text alone, because splitting on `|` throws exactly\n * that fact away. `join === '&&'` vs `';'` is the same argument one operator over — see\n * {@link SegmentJoin}. Data-only, so a class (per CLAUDE.md).\n */\nexport class CommandSegment {\n    text: string;\n    join: SegmentJoin;\n\n    constructor(text: string, join: SegmentJoin) {\n        this.text = text;\n        this.join = join;\n    }\n}\n\nexport class CommandScanner {\n    /**\n     * Split a raw command into individually-invoked segments.\n     *\n     * Splits on `&&`, `||`, `;`, `|`, `&`, newline, and the `(`/`)` of subshells and `$(…)` command\n     * substitution — the last of these matters, since it means `--base=$(git rebase main)` is scanned\n     * as its own `git rebase main` segment rather than hiding inside a `pnpm …` segment.\n     *\n     * Quoted spans are opaque: a separator inside quotes is literal text, so\n     * `git commit -m \"fix; ship it\"` stays one segment. (Corollary: a `$(…)` nested inside double\n     * quotes is not split out. Bash would expand it; we do not scan it. Contrived enough to accept.)\n     */\n    commandSegments(command: string): readonly string[] {\n        return this.segmentsWithJoins(command).map((s: CommandSegment): string => s.text);\n    }\n\n    /**\n     * commandSegments, but each segment also carries the OPERATOR that joined it to its predecessor.\n     * Only a guard reasoning about which files a segment reads, or about whether a failed first\n     * segment can stop the rest, needs that; everything else uses commandSegments, which is this\n     * method with the join dropped.\n     */\n    segmentsWithJoins(command: string): readonly CommandSegment[] {\n        const segments: CommandSegment[] = [];\n        let current = '';\n        let quote: string | null = null;\n        let join: SegmentJoin = 'none';   // the operator that ENDED the previous segment\n\n        for (let i = 0; i < command.length; i++) {\n            const ch = command[i];\n\n            if (quote !== null) {\n                current += ch;\n                // A backslash-escaped quote does not close the span (only meaningful inside \"…\").\n                if (ch === quote && command[i - 1] !== '\\\\') quote = null;\n                continue;\n            }\n\n            if (ch === '\"' || ch === \"'\") {\n                quote = ch;\n                current += ch;\n                continue;\n            }\n\n            // The `&` of a REDIRECTION (`2>&1`, `1>&2`, `&>log`) is not a separator. Splitting on it\n            // tore `git fetch origin main 2>&1 | tail -5` into THREE segments — `git fetch … 2>`, `1`\n            // and `tail -5` — and the bare `1` is not an allowlisted command, so every guard that\n            // requires all segments to pass denied the command. That is `2>&1`, the single most common\n            // decoration an agent appends.\n            if (ch === '&' && command[i + 1] !== '&' && (current.trimEnd().endsWith('>') || command[i + 1] === '>')) {\n                current += ch;\n                continue;\n            }\n\n            if (ch === '\\n' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === ')') {\n                // Consume the second char of `&&` / `||` so it does not start an empty segment.\n                const doubled = (ch === '|' || ch === '&') && command[i + 1] === ch;\n                if (doubled) i++;\n                segments.push(new CommandSegment(current, join));\n                // `|` pipes into the next segment; `||` is a separator, not a pipe.\n                join = doubled ? ((ch + ch) as SegmentJoin) : (ch as SegmentJoin);\n                current = '';\n                continue;\n            }\n\n            current += ch;\n        }\n        segments.push(new CommandSegment(current, join));\n\n        return segments\n            .map((s: CommandSegment): CommandSegment => new CommandSegment(s.text.trim(), s.join))\n            .filter((s: CommandSegment): boolean => s.text.length > 0);\n    }\n\n    /**\n     * One segment's shell words, with wrappers/env-assignments stripped, so `words('sudo cat a b')`\n     * is `['cat', 'a', 'b']`. The public view of the same tokenizer gitSubcommand uses — a guard that\n     * must inspect a NON-git command's arguments (which paths does this `grep` actually read?) needs\n     * the tokens, and re-splitting on whitespace in the guard would get quoting wrong.\n     */\n    words(segment: string): readonly string[] {\n        return this.stripPrefixes(this.tokenize(segment));\n    }\n\n    /**\n     * The git subcommand a segment invokes, or null when the segment does not invoke git at all\n     * (a different program, a mere mention inside quotes, an empty segment).\n     *\n     * Returns the subcommand as an EXACT token: `git merge-base …` yields `'merge-base'`, never `'merge'`.\n     */\n    gitSubcommand(segment: string): string | null {\n        return this.gitSubcommandOf(this.stripPrefixes(this.tokenize(segment)));\n    }\n\n    /**\n     * gitSubcommand, for a caller that already holds the segment's effective words (ShellSegmentScan\n     * strips leading shell keywords, so `do git status` must be resolved from ITS words, not from the\n     * raw segment text where `do` is the command).\n     */\n    gitSubcommandOf(words: readonly string[]): string | null {\n        const tokens = this.stripPrefixes(words);\n        const at = this.gitSubcommandIndex(tokens);\n        return at === -1 ? null : tokens[at];\n    }\n\n    /**\n     * The ARGUMENTS following `git <subcommand>` in this segment, or null when the segment does not\n     * invoke that subcommand.\n     *\n     * `gitSubcommand` answers *which* subcommand; a guard that judges the subcommand's own flags needs\n     * the tokens after it, and slicing them in the guard would mean re-deriving where the subcommand\n     * sits — i.e. re-deriving the `sudo` / `env VAR=x` / `-C <path>` skipping this class exists to own.\n     * `git -C /x commit -m \"msg\"` yields `['-m', 'msg']`, never `['/x', 'commit', '-m', 'msg']`.\n     *\n     * The tokens are QUOTE-STRIPPED (see tokenize), so a quoted argument arrives as ONE token holding\n     * its literal text — newlines, backticks and all. That is what makes an argument's CONTENT\n     * inspectable at all.\n     */\n    gitSubcommandArgs(segment: string, subcommand: string): readonly string[] | null {\n        const tokens = this.stripPrefixes(this.tokenize(segment));\n        const at = this.gitSubcommandIndex(tokens);\n        if (at === -1 || tokens[at] !== subcommand) return null;\n        return tokens.slice(at + 1);\n    }\n\n    /** Index of the subcommand token in already-prefix-stripped words, or -1 when git is not invoked. */\n    private gitSubcommandIndex(tokens: readonly string[]): number {\n        if (tokens.length === 0 || tokens[0] !== 'git') return -1;\n\n        let i = 1;\n        while (i < tokens.length) {\n            const token = tokens[i];\n            if (GIT_FLAGS_WITH_VALUE.has(token)) { i += 2; continue; }\n            // `--git-dir=/x` style (value attached) and any other global flag.\n            if (token.startsWith('-')) { i++; continue; }\n            return i;\n        }\n        return -1;\n    }\n\n    /**\n     * The segment's words with the package-manager WRAPPER stripped, so `pnpm exec vitest run` and\n     * `vitest run` reduce to the same words. `pnpm --silent run build-all` → `['build-all']`.\n     *\n     * Lives HERE rather than in a guard because two guards now need it and they must agree: one blocks a\n     * whole-repo build, the other blocks piping a build's output. If they disagreed about whether\n     * `npx wp-build` is `wp-build`, one of them would have a spelling-shaped side door — which is exactly\n     * the failure mode the runner stripping exists to close.\n     */\n    runnerStrippedWords(segment: string): readonly string[] {\n        let words = this.words(segment);\n        while (words.length > 0 && RUNNERS.has(this.programName(words[0]))) {\n            words = words.slice(1);\n            // The runner's own flags (`--silent`, `-r`) sit between it and the program.\n            while (words.length > 0 && words[0].startsWith('-')) words = words.slice(1);\n            if (words.length > 0 && RUNNER_VERBS.has(words[0])) words = words.slice(1);\n        }\n        return words;\n    }\n\n    /** `./node_modules/.bin/nx` and `/usr/local/bin/pnpm.cmd` are the programs `nx` and `pnpm`. */\n    programName(token: string): string {\n        const base = token.split('/').pop() ?? token;\n        return base.endsWith('.cmd') ? base.slice(0, -'.cmd'.length) : base;\n    }\n\n    /** True when a package-manager runner precedes the program (`pnpm …`, `npx …`). */\n    viaRunner(segment: string): boolean {\n        const raw = this.words(segment);\n        return raw.length > 0 && RUNNERS.has(this.programName(raw[0]));\n    }\n\n    /** True when this segment actually invokes `git <subcommand>`. */\n    invokesGit(segment: string, subcommand: string): boolean {\n        return this.gitSubcommand(segment) === subcommand;\n    }\n\n    /** True when ANY segment of the command invokes one of `subcommands`. */\n    commandInvokesAnyGit(command: string, subcommands: readonly string[]): boolean {\n        return this.commandSegments(command).some((seg: string) =>\n            subcommands.some((sub: string) => this.invokesGit(seg, sub)));\n    }\n\n    /**\n     * Split one segment into shell words, dropping quote characters (so the ARGUMENT of\n     * `echo \"git merge main\"` is the single word `git merge main`, never the word `git`).\n     */\n    private tokenize(segment: string): readonly string[] {\n        const tokens: string[] = [];\n        let current = '';\n        let started = false;\n        let quote: string | null = null;\n\n        for (let i = 0; i < segment.length; i++) {\n            const ch = segment[i];\n\n            if (quote !== null) {\n                if (ch === quote) quote = null;\n                else current += ch;\n                started = true;\n                continue;\n            }\n\n            if (ch === '\"' || ch === \"'\") {\n                quote = ch;\n                started = true;\n                continue;\n            }\n\n            if (/\\s/.test(ch)) {\n                if (started) {\n                    tokens.push(current);\n                    current = '';\n                    started = false;\n                }\n                continue;\n            }\n\n            current += ch;\n            started = true;\n        }\n        if (started) tokens.push(current);\n\n        return tokens;\n    }\n\n    private stripPrefixes(tokens: readonly string[]): readonly string[] {\n        let i = 0;\n        while (i < tokens.length) {\n            const token = tokens[i];\n            if (COMMAND_PREFIXES.has(token)) { i++; continue; }\n            if (ENV_ASSIGNMENT.test(token)) { i++; continue; }\n            break;\n        }\n        return tokens.slice(i);\n    }\n}\n"]}

package/src/core/custom-rule-adapter.d.ts

@@ -0,0 +1,23 @@
+import { BaseRuleConfig } from '@webpieces/rules-sdk';
+import { AbstractRule, RuleOptions } from '@webpieces/rules-config';
+import type { PlainRule, Rule, RuleScope, EditContext, FileContext, BashContext, Violation } from './types';
+import type { FixHint } from './fix-hint';
+/**
+ * Wraps a custom rule loaded from a `rulesDir` (a plain object) so it satisfies the same
+ * runtime `Rule` contract as the built-in rule classes: it gains `shouldRun()` (driven by the
+ * rule's config entry in webpieces.config.json) from AbstractRule, and it seeds `ctx.options`
+ * with the merged option bag before delegating to the plain rule's `check()` — preserving the
+ * exact behavior custom rules had under the old options-based runner.
+ */
+export declare class CustomRuleAdapter extends AbstractRule<BaseRuleConfig> implements Rule {
+    readonly scope: RuleScope;
+    readonly files: readonly string[];
+    readonly description: string;
+    readonly fixHint: FixHint;
+    readonly defaultOptions: RuleOptions;
+    private readonly impl;
+    private readonly rawConfig;
+    constructor(impl: PlainRule, rawConfig: RuleOptions);
+    private buildOptions;
+    check(ctx: EditContext | FileContext | BashContext): readonly Violation[];
+}

package/src/core/custom-rule-adapter.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomRuleAdapter = void 0;
+const rules_config_1 = require("@webpieces/rules-config");
+/**
+ * Wraps a custom rule loaded from a `rulesDir` (a plain object) so it satisfies the same
+ * runtime `Rule` contract as the built-in rule classes: it gains `shouldRun()` (driven by the
+ * rule's config entry in webpieces.config.json) from AbstractRule, and it seeds `ctx.options`
+ * with the merged option bag before delegating to the plain rule's `check()` — preserving the
+ * exact behavior custom rules had under the old options-based runner.
+ */
+class CustomRuleAdapter extends rules_config_1.AbstractRule {
+    scope;
+    files;
+    description;
+    fixHint;
+    defaultOptions;
+    impl;
+    rawConfig;
+    constructor(impl, rawConfig) {
+        // A custom rule from `rulesDir` is keyed in webpieces.config.json by its own `name`, so the
+        // two identities coincide. Stated twice rather than defaulted — see AbstractRule.
+        super(rawConfig, impl.name, impl.name);
+        this.impl = impl;
+        this.scope = impl.scope;
+        this.files = impl.files;
+        this.description = impl.description;
+        this.fixHint = impl.fixHint;
+        this.defaultOptions = impl.defaultOptions;
+        this.rawConfig = rawConfig;
+    }
+    buildOptions() {
+        const out = {};
+        for (const key of Object.keys(this.defaultOptions))
+            out[key] = this.defaultOptions[key];
+        for (const key of Object.keys(this.rawConfig)) {
+            // 'mode' is the framework-level on/off switch, not a rule option.
+            if (key === 'mode')
+                continue;
+            out[key] = this.rawConfig[key];
+        }
+        return out;
+    }
+    check(ctx) {
+        ctx.options = this.buildOptions();
+        return this.impl.check(ctx);
+    }
+}
+exports.CustomRuleAdapter = CustomRuleAdapter;
+//# sourceMappingURL=custom-rule-adapter.js.map

package/src/core/custom-rule-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-rule-adapter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/custom-rule-adapter.ts"],"names":[],"mappings":";;;AACA,0DAAoE;AAKpE;;;;;;GAMG;AACH,MAAa,iBAAkB,SAAQ,2BAA4B;IACtD,KAAK,CAAY;IACjB,KAAK,CAAoB;IACzB,WAAW,CAAS;IACpB,OAAO,CAAU;IACjB,cAAc,CAAc;IACpB,IAAI,CAAY;IAChB,SAAS,CAAc;IAExC,YAAY,IAAe,EAAE,SAAsB;QAC/C,4FAA4F;QAC5F,kFAAkF;QAClF,KAAK,CAAC,SAA2B,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;IAEO,YAAY;QAChB,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACxF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5C,kEAAkE;YAClE,IAAI,GAAG,KAAK,MAAM;gBAAE,SAAS;YAC7B,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED,KAAK,CAAC,GAA4C;QAC9C,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;CACJ;AArCD,8CAqCC","sourcesContent":["import { BaseRuleConfig } from '@webpieces/rules-sdk';\nimport { AbstractRule, RuleOptions } from '@webpieces/rules-config';\n\nimport type { PlainRule, Rule, RuleScope, EditContext, FileContext, BashContext, Violation } from './types';\nimport type { FixHint } from './fix-hint';\n\n/**\n * Wraps a custom rule loaded from a `rulesDir` (a plain object) so it satisfies the same\n * runtime `Rule` contract as the built-in rule classes: it gains `shouldRun()` (driven by the\n * rule's config entry in webpieces.config.json) from AbstractRule, and it seeds `ctx.options`\n * with the merged option bag before delegating to the plain rule's `check()` — preserving the\n * exact behavior custom rules had under the old options-based runner.\n */\nexport class CustomRuleAdapter extends AbstractRule<BaseRuleConfig> implements Rule {\n    readonly scope: RuleScope;\n    readonly files: readonly string[];\n    readonly description: string;\n    readonly fixHint: FixHint;\n    readonly defaultOptions: RuleOptions;\n    private readonly impl: PlainRule;\n    private readonly rawConfig: RuleOptions;\n\n    constructor(impl: PlainRule, rawConfig: RuleOptions) {\n        // A custom rule from `rulesDir` is keyed in webpieces.config.json by its own `name`, so the\n        // two identities coincide. Stated twice rather than defaulted — see AbstractRule.\n        super(rawConfig as BaseRuleConfig, impl.name, impl.name);\n        this.impl = impl;\n        this.scope = impl.scope;\n        this.files = impl.files;\n        this.description = impl.description;\n        this.fixHint = impl.fixHint;\n        this.defaultOptions = impl.defaultOptions;\n        this.rawConfig = rawConfig;\n    }\n\n    private buildOptions(): RuleOptions {\n        const out: RuleOptions = {};\n        for (const key of Object.keys(this.defaultOptions)) out[key] = this.defaultOptions[key];\n        for (const key of Object.keys(this.rawConfig)) {\n            // 'mode' is the framework-level on/off switch, not a rule option.\n            if (key === 'mode') continue;\n            out[key] = this.rawConfig[key];\n        }\n        return out;\n    }\n\n    check(ctx: EditContext | FileContext | BashContext): readonly Violation[] {\n        ctx.options = this.buildOptions();\n        return this.impl.check(ctx);\n    }\n}\n"]}

package/src/core/delete-scoped-rules.d.ts

@@ -0,0 +1,9 @@
+import { Rule } from './types';
+import { ToolKind } from '../protocol';
+export declare class DeleteScopedRules {
+    /**
+     * `rules` unchanged for every other ToolKind; for a Delete, narrowed to the rules that opted into
+     * judging one — today, none of them, so a delete is always allowed.
+     */
+    narrow(toolKind: ToolKind, rules: readonly Rule[]): readonly Rule[];
+}

package/src/core/delete-scoped-rules.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeleteScopedRules = void 0;
+/**
+ * The rules that judge a FILE DELETION. Empty, deliberately, and changing that is a human's call.
+ *
+ * `Delete` is a new ToolKind, reachable only from Codex's `apply_patch` `*** Delete File:` directive —
+ * Claude Code has no delete tool at all. Every rule in this engine was written against the bytes an
+ * edit ADDS (an EditContext's `addedContent`), and a deletion has none, so running them on one would
+ * either produce nothing or produce a verdict about content that is going away. Defaulting all of them
+ * OFF keeps every existing rule's behaviour exactly what it was.
+ *
+ * Two families would arguably be RIGHT to fire here, and are listed rather than enabled because the
+ * decision is a policy call, not a refactor: rules that keep a barrel/index in step with the files it
+ * exports, and rules that keep a doc in step with the file it documents. Deleting a file is precisely
+ * when those two go stale.
+ */
+const DELETE_SCOPED_RULES = new Set([]);
+class DeleteScopedRules {
+    /**
+     * `rules` unchanged for every other ToolKind; for a Delete, narrowed to the rules that opted into
+     * judging one — today, none of them, so a delete is always allowed.
+     */
+    narrow(toolKind, rules) {
+        if (toolKind !== 'Delete')
+            return rules;
+        return rules.filter((r) => DELETE_SCOPED_RULES.has(r.name));
+    }
+}
+exports.DeleteScopedRules = DeleteScopedRules;
+//# sourceMappingURL=delete-scoped-rules.js.map

package/src/core/delete-scoped-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-scoped-rules.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/delete-scoped-rules.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;GAaG;AACH,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;AAE7D,MAAa,iBAAiB;IAC1B;;;OAGG;IACH,MAAM,CAAC,QAAkB,EAAE,KAAsB;QAC7C,IAAI,QAAQ,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAO,EAAW,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,CAAC;CACJ;AATD,8CASC","sourcesContent":["import { Rule } from './types';\nimport { ToolKind } from '../protocol';\n\n/**\n * The rules that judge a FILE DELETION. Empty, deliberately, and changing that is a human's call.\n *\n * `Delete` is a new ToolKind, reachable only from Codex's `apply_patch` `*** Delete File:` directive —\n * Claude Code has no delete tool at all. Every rule in this engine was written against the bytes an\n * edit ADDS (an EditContext's `addedContent`), and a deletion has none, so running them on one would\n * either produce nothing or produce a verdict about content that is going away. Defaulting all of them\n * OFF keeps every existing rule's behaviour exactly what it was.\n *\n * Two families would arguably be RIGHT to fire here, and are listed rather than enabled because the\n * decision is a policy call, not a refactor: rules that keep a barrel/index in step with the files it\n * exports, and rules that keep a doc in step with the file it documents. Deleting a file is precisely\n * when those two go stale.\n */\nconst DELETE_SCOPED_RULES: ReadonlySet<string> = new Set([]);\n\nexport class DeleteScopedRules {\n    /**\n     * `rules` unchanged for every other ToolKind; for a Delete, narrowed to the rules that opted into\n     * judging one — today, none of them, so a delete is always allowed.\n     */\n    narrow(toolKind: ToolKind, rules: readonly Rule[]): readonly Rule[] {\n        if (toolKind !== 'Delete') return rules;\n        return rules.filter((r: Rule): boolean => DELETE_SCOPED_RULES.has(r.name));\n    }\n}\n"]}

package/src/core/disable-directives.d.ts

@@ -0,0 +1,8 @@
+import type { IsLineDisabled } from './types';
+export declare class DirectiveIndex {
+    private readonly lineDisables;
+    constructor(lineDisables: Map<number, Set<string>>);
+    isLineDisabled(lineNum: number, ruleName: string): boolean;
+}
+export declare function parseDirectives(source: string): DirectiveIndex;
+export declare function createIsLineDisabled(source: string): IsLineDisabled;

package/src/core/disable-directives.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectiveIndex = void 0;
+exports.parseDirectives = parseDirectives;
+exports.createIsLineDisabled = createIsLineDisabled;
+const rules_config_1 = require("@webpieces/rules-config");
+// Exactly ONE disable form: `// webpieces-disable <rule>[, <rule2>] -- reason`.
+// A rule (or comma-list of rules) is REQUIRED — there is no bare/`*` "disable everything",
+// no `ai-hook-disable` alias, and no `-file`/`-next`/`-all` variants. A disable applies to
+// the same line (when code precedes the `//`) or the next non-comment line.
+const DIRECTIVE_RE = new RegExp(`//\\s*${rules_config_1.WEBPIECES_DISABLE}\\s+([\\w-]+(?:\\s*,\\s*[\\w-]+)*)(?:\\s*--\\s*.*)?\\s*$`);
+const COMMENT_PREFIX_RE = new RegExp(`^//\\s*${rules_config_1.WEBPIECES_DISABLE}`);
+class DirectiveIndex {
+    lineDisables;
+    constructor(lineDisables) {
+        this.lineDisables = lineDisables;
+    }
+    isLineDisabled(lineNum, ruleName) {
+        const set = this.lineDisables.get(lineNum);
+        if (!set)
+            return false;
+        return set.has(ruleName);
+    }
+}
+exports.DirectiveIndex = DirectiveIndex;
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function parseRuleList(raw) {
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && s !== '*');
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function nextTargetLine(lines, lineIdx) {
+    for (let j = lineIdx + 1; j < lines.length; j += 1) {
+        const trimmed = lines[j].trim();
+        if (trimmed === '')
+            continue;
+        if (COMMENT_PREFIX_RE.test(trimmed))
+            continue;
+        return j + 1;
+    }
+    return null;
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function addDisable(map, lineNum, rules) {
+    if (!map.has(lineNum))
+        map.set(lineNum, new Set());
+    const set = map.get(lineNum);
+    for (const r of rules)
+        set.add(r);
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function resolveTarget(line, lines, i, map, rules) {
+    const beforeComment = line.slice(0, line.indexOf('//')).trim();
+    if (beforeComment !== '') {
+        addDisable(map, i + 1, rules);
+    }
+    else {
+        const target = nextTargetLine(lines, i);
+        if (target !== null)
+            addDisable(map, target, rules);
+    }
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function parseDirectives(source) {
+    const lines = source.split('\n');
+    const lineDisables = new Map();
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const match = line.match(DIRECTIVE_RE);
+        if (!match)
+            continue;
+        const rules = parseRuleList(match[1]);
+        if (rules.length === 0)
+            continue;
+        resolveTarget(line, lines, i, lineDisables, rules);
+    }
+    return new DirectiveIndex(lineDisables);
+}
+// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API
+function createIsLineDisabled(source) {
+    const index = parseDirectives(source);
+    return (lineNum, ruleName) => index.isLineDisabled(lineNum, ruleName);
+}
+//# sourceMappingURL=disable-directives.js.map

package/src/core/disable-directives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disable-directives.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/disable-directives.ts"],"names":[],"mappings":"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","sourcesContent":["import { WEBPIECES_DISABLE } from '@webpieces/rules-config';\nimport type { IsLineDisabled } from './types';\n\n// Exactly ONE disable form: `// webpieces-disable <rule>[, <rule2>] -- reason`.\n// A rule (or comma-list of rules) is REQUIRED — there is no bare/`*` \"disable everything\",\n// no `ai-hook-disable` alias, and no `-file`/`-next`/`-all` variants. A disable applies to\n// the same line (when code precedes the `//`) or the next non-comment line.\nconst DIRECTIVE_RE = new RegExp(\n    `//\\\\s*${WEBPIECES_DISABLE}\\\\s+([\\\\w-]+(?:\\\\s*,\\\\s*[\\\\w-]+)*)(?:\\\\s*--\\\\s*.*)?\\\\s*$`,\n);\nconst COMMENT_PREFIX_RE = new RegExp(`^//\\\\s*${WEBPIECES_DISABLE}`);\n\nexport class DirectiveIndex {\n    private readonly lineDisables: Map<number, Set<string>>;\n\n    constructor(lineDisables: Map<number, Set<string>>) {\n        this.lineDisables = lineDisables;\n    }\n\n    isLineDisabled(lineNum: number, ruleName: string): boolean {\n        const set = this.lineDisables.get(lineNum);\n        if (!set) return false;\n        return set.has(ruleName);\n    }\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction parseRuleList(raw: string): readonly string[] {\n    return raw\n        .split(',')\n        .map((s: string): string => s.trim())\n        .filter((s: string): boolean => s.length > 0 && s !== '*');\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction nextTargetLine(lines: readonly string[], lineIdx: number): number | null {\n    for (let j = lineIdx + 1; j < lines.length; j += 1) {\n        const trimmed = lines[j].trim();\n        if (trimmed === '') continue;\n        if (COMMENT_PREFIX_RE.test(trimmed)) continue;\n        return j + 1;\n    }\n    return null;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction addDisable(map: Map<number, Set<string>>, lineNum: number, rules: readonly string[]): void {\n    if (!map.has(lineNum)) map.set(lineNum, new Set<string>());\n    const set = map.get(lineNum)!;\n    for (const r of rules) set.add(r);\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nfunction resolveTarget(\n    line: string, lines: readonly string[], i: number,\n    map: Map<number, Set<string>>, rules: readonly string[],\n): void {\n    const beforeComment = line.slice(0, line.indexOf('//')).trim();\n    if (beforeComment !== '') {\n        addDisable(map, i + 1, rules);\n    } else {\n        const target = nextTargetLine(lines, i);\n        if (target !== null) addDisable(map, target, rules);\n    }\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nexport function parseDirectives(source: string): DirectiveIndex {\n    const lines = source.split('\\n');\n    const lineDisables = new Map<number, Set<string>>();\n\n    for (let i = 0; i < lines.length; i += 1) {\n        const line = lines[i];\n        const match = line.match(DIRECTIVE_RE);\n        if (!match) continue;\n        const rules = parseRuleList(match[1]);\n        if (rules.length === 0) continue;\n        resolveTarget(line, lines, i, lineDisables, rules);\n    }\n    return new DirectiveIndex(lineDisables);\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless module helper moved intact with its callers; ownership extraction preserves its functional API\nexport function createIsLineDisabled(source: string): IsLineDisabled {\n    const index = parseDirectives(source);\n    return (lineNum: number, ruleName: string): boolean => index.isLineDisabled(lineNum, ruleName);\n}\n"]}