@webpieces/hook-runtime 0.0.1

package/src/core/rule-evaluation.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkConfigSync = checkConfigSync;
+exports.runRuleCheck = runRuleCheck;
+exports.runBashRules = runBashRules;
+exports.runEditRules = runEditRules;
+exports.runFileRules = runFileRules;
+const rules_config_1 = require("@webpieces/rules-config");
+const to_error_1 = require("@webpieces/tooling-common/to-error");
+const types_1 = require("./types");
+const glob_1 = require("./glob");
+// The set of CONFIG KEYS explicitly present in webpieces.config.json (every key except rulesDir).
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function configuredRuleNames(config) {
+    return new Set(Object.keys(config).filter((k) => k !== 'rulesDir'));
+}
+/**
+ * Fault Y — a loaded rule whose CONFIG KEY has no entry.
+ *
+ * Compared on `configKey`, not `name`. Eight of the loaded rules are classes behind two policy keys, so
+ * comparing names here would demand entries named `feature-branch-guard`, `pr-merge-guard` and six
+ * others — keys the validator then REJECTS as retired. That is the two-enforcement-paths deadlock this
+ * repo has already hit once (see the narration in guards.spec.ts), and it blocks every Bash/Write/Edit.
+ *
+ * De-duplicated on the key too, so one missing policy entry reports ONE paste-ready snippet rather than
+ * four copies of the same one under four different headings.
+ */
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function checkConfigSync(rules, config, registry) {
+    const configured = configuredRuleNames(config);
+    const seen = new Set();
+    const unconfiguredRules = rules.filter((r) => {
+        if (configured.has(r.configKey) || seen.has(r.configKey))
+            return false;
+        seen.add(r.configKey);
+        return true;
+    });
+    if (unconfiguredRules.length === 0)
+        return null;
+    // ONE action, no menu, no escalation — the config-validation invariant (guards/L0-tooling.md): every
+    // config problem cures to "make the file right", and editing it is never denied. This message used
+    // to tell the agent to interview the human about each rule; agents did not do it, so the block just
+    // stalled. Each rule now ships a paste-ready entry at its recommended mode.
+    //
+    // Note this is the CONFIG-BEHIND-CODE direction. The opposite one — the config names a rule the
+    // installed validator has no schema for — is unknownRuleError() in rules-config/validate-config.ts
+    // and surfaces in the validation banner, not here.
+    const lines = [
+        // Fault Y's header lives in ./l0-matrix beside the rest of the L0 fault table (same reason as
+        // CONFIG_MISSING_REPORT: one place states what this fault is and what cures it).
+        rules_config_1.CONFIG_OUT_OF_SYNC_HEADER,
+        '',
+        `Add an entry for each rule below to ${rules_config_1.CONFIG_FILENAME}. Editing that file is ALWAYS allowed through`,
+        'the guard — including right now, while this block is up — so paste the entries and retry.',
+        '',
+        'Each entry below is ready to paste at its recommended mode; adjust the option values if your',
+        'project needs different ones.',
+        '',
+        `Do NOT delete a rule from ${rules_config_1.CONFIG_FILENAME} to silence it — an entry is REQUIRED for every rule,`,
+        'and "mode": "OFF" is how a rule is turned off.',
+        '',
+    ];
+    for (const rule of unconfiguredRules) {
+        lines.push(`--- ${rule.configKey} ---`);
+        lines.push(`Description: ${rule.description}`);
+        const opts = rule.defaultOptions;
+        const optKeys = Object.keys(opts);
+        if (optKeys.length > 0) {
+            lines.push(`Available options (suggested defaults shown):`);
+            for (const key of optKeys) {
+                lines.push(`  ${key}: ${JSON.stringify(opts[key])}`);
+            }
+        }
+        else {
+            lines.push('Available options: none beyond mode');
+        }
+        // The SAME entry the installer would seed: recommended mode, both hatches, and every other
+        // schema-required field — so pasting it satisfies the loader in one pass.
+        lines.push(`Entry to add to ${rules_config_1.CONFIG_FILENAME}:`);
+        lines.push(`  "${rule.configKey}": ${JSON.stringify((0, rules_config_1.seedEntryForRule)(rule.configKey, registry))}`);
+        lines.push('');
+    }
+    // Fault Y, stamped for the audit trail — see configMissingBlock for why the producer names it.
+    return new types_1.BlockedResult(lines.join('\n'), rules_config_1.L0_FAULT_CONFIG_OUT_OF_SYNC);
+}
+// N-legs pattern: each rule runs independently so one rule can never abort the others. A rule may
+// EITHER return Violation[] OR throw — both accumulate here into visible violations the AI sees:
+//  - a thrown RuleFailError  → an expected, well-formed violation (its line/snippet/fixOptions kept);
+//  - a thrown plain Error    → a "crashed" violation (a bug, surfaced not swallowed).
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function runRuleCheck(rule, ctx) {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return rule.check(ctx);
+    }
+    catch (err) {
+        const error = (0, to_error_1.toError)(err);
+        if (error instanceof rules_config_1.RuleFailError) {
+            return [violationFromRuleFail(error)];
+        }
+        return [new types_1.Violation(0, '', `Rule '${rule.name}' crashed: ${error.message}`)];
+    }
+}
+// A thrown RuleFailError carries its own AI-facing message + optional location and cures. Fold the
+// cures into the message because Violation has no fixHint field (RuleGroup's fixHint comes from the
+// rule definition, not a per-throw value). The "Fix Option N:"/"(preferred)" labels come from the ONE
+// framework-owned renderer, exactly as report.ts renders a rule's static FixHint — a rule never
+// hand-numbers its own cures.
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function violationFromRuleFail(error) {
+    return new types_1.Violation(error.line ?? 0, error.snippet ?? '', (0, rules_config_1.renderRuleFailForAi)(error));
+}
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function ruleMatchesFile(rule, relativePath) {
+    for (const pattern of rule.files) {
+        if ((0, glob_1.globMatches)(pattern, relativePath))
+            return true;
+    }
+    return false;
+}
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function runBashRules(rules, bashContext) {
+    const groups = [];
+    for (const rule of rules) {
+        if (rule.scope !== 'bash')
+            continue;
+        if (!rule.shouldRun())
+            continue;
+        const vs = runRuleCheck(rule, bashContext);
+        if (vs.length > 0) {
+            groups.push(new types_1.RuleGroup(rule.name, rule.description, rule.fixHint, [...vs]));
+        }
+    }
+    return groups;
+}
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function runEditRules(rules, editContexts) {
+    const groups = [];
+    for (const rule of rules) {
+        if (rule.scope !== 'edit')
+            continue;
+        if (!rule.shouldRun())
+            continue;
+        const allViolations = [];
+        for (const ctx of editContexts) {
+            if (!ruleMatchesFile(rule, ctx.relativePath))
+                continue;
+            const vs = runRuleCheck(rule, ctx);
+            for (const v of vs) {
+                const copy = new types_1.Violation(v.line, v.snippet, v.message);
+                copy.editIndex = ctx.editIndex;
+                copy.editCount = ctx.editCount;
+                allViolations.push(copy);
+            }
+        }
+        if (allViolations.length > 0) {
+            groups.push(new types_1.RuleGroup(rule.name, rule.description, rule.fixHint, allViolations));
+        }
+    }
+    return groups;
+}
+// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers
+function runFileRules(rules, fileContext) {
+    const groups = [];
+    for (const rule of rules) {
+        if (rule.scope !== 'file')
+            continue;
+        if (!rule.shouldRun())
+            continue;
+        if (!ruleMatchesFile(rule, fileContext.relativePath))
+            continue;
+        const vs = runRuleCheck(rule, fileContext);
+        if (vs.length > 0) {
+            groups.push(new types_1.RuleGroup(rule.name, rule.description, rule.fixHint, [...vs]));
+        }
+    }
+    return groups;
+}
+//# sourceMappingURL=rule-evaluation.js.map

package/src/core/rule-evaluation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-evaluation.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/rule-evaluation.ts"],"names":[],"mappings":"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","sourcesContent":["import { CONFIG_FILENAME, CONFIG_OUT_OF_SYNC_HEADER, L0_FAULT_CONFIG_OUT_OF_SYNC, seedEntryForRule, RulePackRegistry, WebpiecesRulesConfig, RuleFailError, renderRuleFailForAi } from '@webpieces/rules-config';\nimport { toError } from '@webpieces/tooling-common/to-error';\nimport { Rule, EditContext, FileContext, BashContext, Violation, RuleGroup, BlockedResult } from './types';\n\nimport { globMatches } from './glob';\n\n// The set of CONFIG KEYS explicitly present in webpieces.config.json (every key except rulesDir).\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nfunction configuredRuleNames(config: WebpiecesRulesConfig): ReadonlySet<string> {\n    return new Set(Object.keys(config).filter((k: string) => k !== 'rulesDir'));\n}\n\n/**\n * Fault Y — a loaded rule whose CONFIG KEY has no entry.\n *\n * Compared on `configKey`, not `name`. Eight of the loaded rules are classes behind two policy keys, so\n * comparing names here would demand entries named `feature-branch-guard`, `pr-merge-guard` and six\n * others — keys the validator then REJECTS as retired. That is the two-enforcement-paths deadlock this\n * repo has already hit once (see the narration in guards.spec.ts), and it blocks every Bash/Write/Edit.\n *\n * De-duplicated on the key too, so one missing policy entry reports ONE paste-ready snippet rather than\n * four copies of the same one under four different headings.\n */\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nexport function checkConfigSync(rules: readonly Rule[], config: WebpiecesRulesConfig, registry: RulePackRegistry): BlockedResult | null {\n    const configured = configuredRuleNames(config);\n    const seen = new Set<string>();\n    const unconfiguredRules = rules.filter((r: Rule): boolean => {\n        if (configured.has(r.configKey) || seen.has(r.configKey)) return false;\n        seen.add(r.configKey);\n        return true;\n    });\n    if (unconfiguredRules.length === 0) return null;\n\n    // ONE action, no menu, no escalation — the config-validation invariant (guards/L0-tooling.md): every\n    // config problem cures to \"make the file right\", and editing it is never denied. This message used\n    // to tell the agent to interview the human about each rule; agents did not do it, so the block just\n    // stalled. Each rule now ships a paste-ready entry at its recommended mode.\n    //\n    // Note this is the CONFIG-BEHIND-CODE direction. The opposite one — the config names a rule the\n    // installed validator has no schema for — is unknownRuleError() in rules-config/validate-config.ts\n    // and surfaces in the validation banner, not here.\n    const lines = [\n        // Fault Y's header lives in ./l0-matrix beside the rest of the L0 fault table (same reason as\n        // CONFIG_MISSING_REPORT: one place states what this fault is and what cures it).\n        CONFIG_OUT_OF_SYNC_HEADER,\n        '',\n        `Add an entry for each rule below to ${CONFIG_FILENAME}. Editing that file is ALWAYS allowed through`,\n        'the guard — including right now, while this block is up — so paste the entries and retry.',\n        '',\n        'Each entry below is ready to paste at its recommended mode; adjust the option values if your',\n        'project needs different ones.',\n        '',\n        `Do NOT delete a rule from ${CONFIG_FILENAME} to silence it — an entry is REQUIRED for every rule,`,\n        'and \"mode\": \"OFF\" is how a rule is turned off.',\n        '',\n    ];\n\n    for (const rule of unconfiguredRules) {\n        lines.push(`--- ${rule.configKey} ---`);\n        lines.push(`Description: ${rule.description}`);\n        const opts = rule.defaultOptions;\n        const optKeys = Object.keys(opts);\n        if (optKeys.length > 0) {\n            lines.push(`Available options (suggested defaults shown):`);\n            for (const key of optKeys) {\n                lines.push(`  ${key}: ${JSON.stringify(opts[key])}`);\n            }\n        } else {\n            lines.push('Available options: none beyond mode');\n        }\n        // The SAME entry the installer would seed: recommended mode, both hatches, and every other\n        // schema-required field — so pasting it satisfies the loader in one pass.\n        lines.push(`Entry to add to ${CONFIG_FILENAME}:`);\n        lines.push(`  \"${rule.configKey}\": ${JSON.stringify(seedEntryForRule(rule.configKey, registry))}`);\n        lines.push('');\n    }\n\n    // Fault Y, stamped for the audit trail — see configMissingBlock for why the producer names it.\n    return new BlockedResult(lines.join('\\n'), L0_FAULT_CONFIG_OUT_OF_SYNC);\n}\n\n// N-legs pattern: each rule runs independently so one rule can never abort the others. A rule may\n// EITHER return Violation[] OR throw — both accumulate here into visible violations the AI sees:\n//  - a thrown RuleFailError  → an expected, well-formed violation (its line/snippet/fixOptions kept);\n//  - a thrown plain Error    → a \"crashed\" violation (a bug, surfaced not swallowed).\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nexport function runRuleCheck(rule: Rule, ctx: EditContext | FileContext | BashContext): readonly Violation[] {\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        return rule.check(ctx);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) {\n            return [violationFromRuleFail(error)];\n        }\n        return [new Violation(0, '', `Rule '${rule.name}' crashed: ${error.message}`)];\n    }\n}\n\n// A thrown RuleFailError carries its own AI-facing message + optional location and cures. Fold the\n// cures into the message because Violation has no fixHint field (RuleGroup's fixHint comes from the\n// rule definition, not a per-throw value). The \"Fix Option N:\"/\"(preferred)\" labels come from the ONE\n// framework-owned renderer, exactly as report.ts renders a rule's static FixHint — a rule never\n// hand-numbers its own cures.\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nfunction violationFromRuleFail(error: RuleFailError): Violation {\n    return new Violation(error.line ?? 0, error.snippet ?? '', renderRuleFailForAi(error));\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nfunction ruleMatchesFile(rule: Rule, relativePath: string): boolean {\n    for (const pattern of rule.files) {\n        if (globMatches(pattern, relativePath)) return true;\n    }\n    return false;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nexport function runBashRules(rules: readonly Rule[], bashContext: BashContext): readonly RuleGroup[] {\n    const groups: RuleGroup[] = [];\n    for (const rule of rules) {\n        if (rule.scope !== 'bash') continue;\n        if (!rule.shouldRun()) continue;\n        const vs = runRuleCheck(rule, bashContext);\n        if (vs.length > 0) {\n            groups.push(new RuleGroup(\n                rule.name, rule.description, rule.fixHint, [...vs],\n            ));\n        }\n    }\n    return groups;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nexport function runEditRules(rules: readonly Rule[], editContexts: readonly EditContext[]): readonly RuleGroup[] {\n    const groups: RuleGroup[] = [];\n    for (const rule of rules) {\n        if (rule.scope !== 'edit') continue;\n        if (!rule.shouldRun()) continue;\n        const allViolations: Violation[] = [];\n        for (const ctx of editContexts) {\n            if (!ruleMatchesFile(rule, ctx.relativePath)) continue;\n            const vs = runRuleCheck(rule, ctx);\n            for (const v of vs) {\n                const copy = new Violation(v.line, v.snippet, v.message);\n                copy.editIndex = ctx.editIndex;\n                copy.editCount = ctx.editCount;\n                allViolations.push(copy);\n            }\n        }\n        if (allViolations.length > 0) {\n            groups.push(new RuleGroup(\n                rule.name, rule.description, rule.fixHint, allViolations,\n            ));\n        }\n    }\n    return groups;\n}\n\n// webpieces-disable no-function-outside-class -- existing stateless evaluator helpers extracted intact for both hook providers\nexport function runFileRules(rules: readonly Rule[], fileContext: FileContext): readonly RuleGroup[] {\n    const groups: RuleGroup[] = [];\n    for (const rule of rules) {\n        if (rule.scope !== 'file') continue;\n        if (!rule.shouldRun()) continue;\n        if (!ruleMatchesFile(rule, fileContext.relativePath)) continue;\n        const vs = runRuleCheck(rule, fileContext);\n        if (vs.length > 0) {\n            groups.push(new RuleGroup(\n                rule.name, rule.description, rule.fixHint, [...vs],\n            ));\n        }\n    }\n    return groups;\n}\n"]}

package/src/core/rules/shell-segment-scan.d.ts

@@ -0,0 +1,64 @@
+import { CommandScanner, CommandSegment } from '../command-scan';
+/**
+ * What ROLE one segment of a shell command plays — the question every allowlist-shaped bash guard has
+ * to answer before it can judge a compound command.
+ *
+ * WHY this exists: `merged-branch-bash-guard` allowlists the commands that get you OFF a merged
+ * branch, and the redirect it prints tells the agent to run them. An agent bounds tool output by
+ * reflex, so it runs `git fetch origin main 2>&1 | tail -5` — and the guard, evaluating `tail -5` as
+ * an ordinary command, denied the very remedy it had just printed. Verified pairs from the field:
+ *
+ *     pnpm wp-cleanup                    allowed
+ *     pnpm wp-cleanup 2>&1 | tail -40    BLOCKED
+ *     git fetch origin main              allowed
+ *     git fetch origin main 2>&1; echo   BLOCKED
+ *
+ * Nothing in `| tail -40` or `; echo done` can touch the repo, and `done`/`do`/`for x in a b` are not
+ * commands at all. So a segment is one of three things:
+ *
+ *   - STRUCTURE — pure shell syntax, invokes nothing (`for b in a b c`, `done`, `fi`).
+ *   - SHAPING   — cannot change the repo: a pager/filter fed by a PIPE (`| tail`, `| head`, `| wc`),
+ *                 or an always-inert command (`echo`, `cd`, `pwd`, `true`).
+ *   - COMMAND   — a real invocation, with `words` giving the effective argv AFTER leading shell
+ *                 keywords are stripped, so `do gh pr list` classifies as `gh pr list`.
+ *
+ * Two things keep SHAPING honest. A filter counts only when a PIPE fed it — bare `tail src/x.ts`
+ * reads the working tree and stays a COMMAND. And a segment carrying an output REDIRECT (`> file`,
+ * `>> file`) is always a COMMAND, because `echo x > src/y.ts` writes the repo. `2>&1` is not a
+ * redirect to a file and is deliberately not caught.
+ *
+ * Deciding WHETHER a shaping segment is acceptable is still the guard's call: merged-branch-bash-guard
+ * pairs this with ContentReadScan so `git status | cat src/foo.ts` (a filter with a workspace path)
+ * stays blocked.
+ */
+export type SegmentRole = 'structure' | 'shaping' | 'command';
+/** Data-only (per CLAUDE.md, classes for data). */
+export declare class SegmentVerdict {
+    role: SegmentRole;
+    /** The effective argv for a COMMAND, leading shell keywords stripped. Empty for the other roles. */
+    words: readonly string[];
+    constructor(role: SegmentRole, words: readonly string[]);
+}
+export declare class ShellSegmentScan {
+    private readonly scanner;
+    constructor(scanner?: CommandScanner);
+    classify(segment: CommandSegment): SegmentVerdict;
+    /**
+     * The effective argv of a segment with leading shell keywords removed — what a guard should judge
+     * instead of the raw words. `for b in $(…); do git status; done` splits into three segments and
+     * the middle one is literally `do git status`; without this, `do` is the command name and every
+     * loop body walks straight past a git allowlist.
+     */
+    effectiveWords(segmentText: string): readonly string[];
+    private stripKeywords;
+    /**
+     * `>`, `>>`, `>out.txt`, `2>log` — but NOT `2>&1`/`1>&2`, which merely rewire fds.
+     *
+     * PUBLIC because RecoveryAllowlist asks the same question of a segment it is about to allow on the
+     * strength of the program name alone (`curl`, `gh`): those cannot touch the tree by themselves, but
+     * `curl … > src/x.ts` can. One implementation, so the two callers cannot disagree about what
+     * counts as a redirect — the `2>&1` carve-out above is exactly the kind of detail a second copy
+     * gets wrong.
+     */
+    redirectsToFile(words: readonly string[]): boolean;
+}

package/src/core/rules/shell-segment-scan.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShellSegmentScan = exports.SegmentVerdict = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const command_scan_1 = require("../command-scan");
+/** Data-only (per CLAUDE.md, classes for data). */
+class SegmentVerdict {
+    role;
+    /** The effective argv for a COMMAND, leading shell keywords stripped. Empty for the other roles. */
+    words;
+    constructor(role, words) {
+        this.role = role;
+        this.words = words;
+    }
+}
+exports.SegmentVerdict = SegmentVerdict;
+class ShellSegmentScan {
+    scanner;
+    constructor(scanner = new command_scan_1.CommandScanner()) {
+        this.scanner = scanner;
+    }
+    classify(segment) {
+        const words = this.stripKeywords(this.scanner.words(segment.text));
+        if (words.length === 0)
+            return STRUCTURE;
+        const head = path.basename(words[0]);
+        if (STRUCTURE_HEADS.has(head))
+            return STRUCTURE;
+        // A redirect can create or overwrite a file, so it is never inert — judge it as a command.
+        if (this.redirectsToFile(words))
+            return new SegmentVerdict('command', words);
+        if (ALWAYS_INERT.has(head))
+            return new SegmentVerdict('shaping', words);
+        if (segment.join === '|' && OUTPUT_FILTERS.has(head))
+            return new SegmentVerdict('shaping', words);
+        return new SegmentVerdict('command', words);
+    }
+    /**
+     * The effective argv of a segment with leading shell keywords removed — what a guard should judge
+     * instead of the raw words. `for b in $(…); do git status; done` splits into three segments and
+     * the middle one is literally `do git status`; without this, `do` is the command name and every
+     * loop body walks straight past a git allowlist.
+     */
+    effectiveWords(segmentText) {
+        return this.stripKeywords(this.scanner.words(segmentText));
+    }
+    stripKeywords(words) {
+        let i = 0;
+        while (i < words.length && STRIPPABLE_KEYWORDS.has(words[i]))
+            i++;
+        return words.slice(i);
+    }
+    /**
+     * `>`, `>>`, `>out.txt`, `2>log` — but NOT `2>&1`/`1>&2`, which merely rewire fds.
+     *
+     * PUBLIC because RecoveryAllowlist asks the same question of a segment it is about to allow on the
+     * strength of the program name alone (`curl`, `gh`): those cannot touch the tree by themselves, but
+     * `curl … > src/x.ts` can. One implementation, so the two callers cannot disagree about what
+     * counts as a redirect — the `2>&1` carve-out above is exactly the kind of detail a second copy
+     * gets wrong.
+     */
+    redirectsToFile(words) {
+        return words.some((word) => REDIRECT_TO_FILE.test(word));
+    }
+}
+exports.ShellSegmentScan = ShellSegmentScan;
+const STRUCTURE = new SegmentVerdict('structure', []);
+// Keywords that PRECEDE a real command; strip them and judge what follows.
+const STRIPPABLE_KEYWORDS = new Set([
+    'do', 'then', 'else', 'elif', 'if', 'while', 'until', '!', '{', '}', '(', ')',
+]);
+// Segments that invoke nothing at all: loop/case HEADERS (their tail is a word list, and any `$(…)`
+// inside was already split into its own segment by CommandScanner) and the closing keywords.
+const STRUCTURE_HEADS = new Set([
+    'for', 'case', 'select', 'done', 'fi', 'esac', ';;', 'in',
+]);
+// Commands that cannot read repo content or change the repo, piped or not.
+const ALWAYS_INERT = new Set([
+    'echo', 'printf', 'true', 'false', ':', 'cd', 'pwd', 'date', 'whoami', 'which', 'sleep', 'test', '[',
+]);
+// Pagers/filters that read STDIN. Only when a pipe fed them — bare, they read the working tree.
+const OUTPUT_FILTERS = new Set([
+    'head', 'tail', 'wc', 'cat', 'less', 'more', 'nl', 'tac', 'rev', 'sort', 'uniq', 'cut', 'tr',
+    'column', 'fold', 'expand', 'grep', 'egrep', 'fgrep', 'rg', 'sed', 'awk', 'jq', 'yq',
+]);
+const REDIRECT_TO_FILE = /^\d*>>?(?!&)/;
+//# sourceMappingURL=shell-segment-scan.js.map

package/src/core/rules/shell-segment-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-segment-scan.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/hook-runtime/src/core/rules/shell-segment-scan.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'path';\n\nimport { CommandScanner, CommandSegment } from '../command-scan';\n\n/**\n * What ROLE one segment of a shell command plays — the question every allowlist-shaped bash guard has\n * to answer before it can judge a compound command.\n *\n * WHY this exists: `merged-branch-bash-guard` allowlists the commands that get you OFF a merged\n * branch, and the redirect it prints tells the agent to run them. An agent bounds tool output by\n * reflex, so it runs `git fetch origin main 2>&1 | tail -5` — and the guard, evaluating `tail -5` as\n * an ordinary command, denied the very remedy it had just printed. Verified pairs from the field:\n *\n *     pnpm wp-cleanup                    allowed\n *     pnpm wp-cleanup 2>&1 | tail -40    BLOCKED\n *     git fetch origin main              allowed\n *     git fetch origin main 2>&1; echo   BLOCKED\n *\n * Nothing in `| tail -40` or `; echo done` can touch the repo, and `done`/`do`/`for x in a b` are not\n * commands at all. So a segment is one of three things:\n *\n *   - STRUCTURE — pure shell syntax, invokes nothing (`for b in a b c`, `done`, `fi`).\n *   - SHAPING   — cannot change the repo: a pager/filter fed by a PIPE (`| tail`, `| head`, `| wc`),\n *                 or an always-inert command (`echo`, `cd`, `pwd`, `true`).\n *   - COMMAND   — a real invocation, with `words` giving the effective argv AFTER leading shell\n *                 keywords are stripped, so `do gh pr list` classifies as `gh pr list`.\n *\n * Two things keep SHAPING honest. A filter counts only when a PIPE fed it — bare `tail src/x.ts`\n * reads the working tree and stays a COMMAND. And a segment carrying an output REDIRECT (`> file`,\n * `>> file`) is always a COMMAND, because `echo x > src/y.ts` writes the repo. `2>&1` is not a\n * redirect to a file and is deliberately not caught.\n *\n * Deciding WHETHER a shaping segment is acceptable is still the guard's call: merged-branch-bash-guard\n * pairs this with ContentReadScan so `git status | cat src/foo.ts` (a filter with a workspace path)\n * stays blocked.\n */\nexport type SegmentRole = 'structure' | 'shaping' | 'command';\n\n/** Data-only (per CLAUDE.md, classes for data). */\nexport class SegmentVerdict {\n    role: SegmentRole;\n    /** The effective argv for a COMMAND, leading shell keywords stripped. Empty for the other roles. */\n    words: readonly string[];\n\n    constructor(role: SegmentRole, words: readonly string[]) {\n        this.role = role;\n        this.words = words;\n    }\n}\n\nexport class ShellSegmentScan {\n    constructor(private readonly scanner: CommandScanner = new CommandScanner()) {}\n\n    classify(segment: CommandSegment): SegmentVerdict {\n        const words = this.stripKeywords(this.scanner.words(segment.text));\n        if (words.length === 0) return STRUCTURE;\n\n        const head = path.basename(words[0]);\n        if (STRUCTURE_HEADS.has(head)) return STRUCTURE;\n\n        // A redirect can create or overwrite a file, so it is never inert — judge it as a command.\n        if (this.redirectsToFile(words)) return new SegmentVerdict('command', words);\n\n        if (ALWAYS_INERT.has(head)) return new SegmentVerdict('shaping', words);\n        if (segment.join === '|' && OUTPUT_FILTERS.has(head)) return new SegmentVerdict('shaping', words);\n\n        return new SegmentVerdict('command', words);\n    }\n\n    /**\n     * The effective argv of a segment with leading shell keywords removed — what a guard should judge\n     * instead of the raw words. `for b in $(…); do git status; done` splits into three segments and\n     * the middle one is literally `do git status`; without this, `do` is the command name and every\n     * loop body walks straight past a git allowlist.\n     */\n    effectiveWords(segmentText: string): readonly string[] {\n        return this.stripKeywords(this.scanner.words(segmentText));\n    }\n\n    private stripKeywords(words: readonly string[]): readonly string[] {\n        let i = 0;\n        while (i < words.length && STRIPPABLE_KEYWORDS.has(words[i])) i++;\n        return words.slice(i);\n    }\n\n    /**\n     * `>`, `>>`, `>out.txt`, `2>log` — but NOT `2>&1`/`1>&2`, which merely rewire fds.\n     *\n     * PUBLIC because RecoveryAllowlist asks the same question of a segment it is about to allow on the\n     * strength of the program name alone (`curl`, `gh`): those cannot touch the tree by themselves, but\n     * `curl … > src/x.ts` can. One implementation, so the two callers cannot disagree about what\n     * counts as a redirect — the `2>&1` carve-out above is exactly the kind of detail a second copy\n     * gets wrong.\n     */\n    redirectsToFile(words: readonly string[]): boolean {\n        return words.some((word: string): boolean => REDIRECT_TO_FILE.test(word));\n    }\n}\n\nconst STRUCTURE = new SegmentVerdict('structure', []);\n\n// Keywords that PRECEDE a real command; strip them and judge what follows.\nconst STRIPPABLE_KEYWORDS: ReadonlySet<string> = new Set([\n    'do', 'then', 'else', 'elif', 'if', 'while', 'until', '!', '{', '}', '(', ')',\n]);\n\n// Segments that invoke nothing at all: loop/case HEADERS (their tail is a word list, and any `$(…)`\n// inside was already split into its own segment by CommandScanner) and the closing keywords.\nconst STRUCTURE_HEADS: ReadonlySet<string> = new Set([\n    'for', 'case', 'select', 'done', 'fi', 'esac', ';;', 'in',\n]);\n\n// Commands that cannot read repo content or change the repo, piped or not.\nconst ALWAYS_INERT: ReadonlySet<string> = new Set([\n    'echo', 'printf', 'true', 'false', ':', 'cd', 'pwd', 'date', 'whoami', 'which', 'sleep', 'test', '[',\n]);\n\n// Pagers/filters that read STDIN. Only when a pipe fed them — bare, they read the working tree.\nconst OUTPUT_FILTERS: ReadonlySet<string> = new Set([\n    'head', 'tail', 'wc', 'cat', 'less', 'more', 'nl', 'tac', 'rev', 'sort', 'uniq', 'cut', 'tr',\n    'column', 'fold', 'expand', 'grep', 'egrep', 'fgrep', 'rg', 'sed', 'awk', 'jq', 'yq',\n]);\n\nconst REDIRECT_TO_FILE = /^\\d*>>?(?!&)/;\n"]}

package/src/core/shell-read-parity.d.ts

@@ -0,0 +1,34 @@
+export { READ_COMMANDS } from '@webpieces/rules-config';
+/**
+ * The only `sed` script shape that is a read: a line range printed with `-n` — as a regex BODY, so the
+ * L0 allowlist's ERE twin can be built from the same characters instead of retyping them.
+ *
+ * EXPORTED for `bin/l0-allowlist.ts`. The L0 entry that lets a Codex session read its way out of an L0
+ * fault has to mean the same thing as this module or the two definitions of "read-shaped" drift, and a
+ * drifted L0 entry is either a hole or a deadlock. It cannot literally CALL this module — L0's sh half
+ * has no JS at all — so the shared thing is the vocabulary, and `codex-l0-read.spec.ts` asserts the two
+ * agree over a corpus.
+ */
+export declare const SED_RANGE_BODY = "[0-9]+(,[0-9]+)?p";
+export declare class ShellReadParity {
+    /**
+     * The absolute paths this command reads, or an empty list when it is not a read-shaped command.
+     * `root` is the tree the read must fall inside; a path outside it is not this repo's read.
+     */
+    readTargets(command: string, cwd: string, root: string): readonly string[];
+    /**
+     * `sed`'s operands, or null when this `sed` invocation is not a plain range print. `-n` and a
+     * single `<range>p` script are BOTH required: without `-n` sed echoes and edits, and any other
+     * script is a transformation, not a read.
+     */
+    private sedOperands;
+    private isFileInTree;
+    /**
+     * Split on whitespace, honouring single and double quotes. Returns null on an unterminated quote —
+     * a command we cannot read confidently is never a read.
+     *
+     * There is no escape or expansion handling here on purpose: `NOT_ONE_COMMAND` has already refused
+     * everything carrying shell syntax, so what reaches this is a literal argv.
+     */
+    private tokenize;
+}

package/src/core/shell-read-parity.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShellReadParity = exports.SED_RANGE_BODY = exports.READ_COMMANDS = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+/**
+ * READ PARITY, and it is a CODEX-ONLY surface.
+ *
+ * Claude Code has a first-class `Read` tool, so the read-scoped guard (read-stale-guard) and the
+ * `calls/` audit trail see every file the agent opens. Codex has no such tool: a file read arrives as
+ * `Bash` running `sed -n '1,240p' <path>` (measured). Without this, every Codex read is invisible to
+ * the read guard and to the audit log, and the two harnesses cannot be compared at all.
+ *
+ * The caller gates this on `aiType === 'codex'`. Nothing here is reachable from a Claude Code payload,
+ * and a spec pins that.
+ *
+ * DELIBERATELY CONSERVATIVE, because a false positive here is not a missed read — it is a Read GUARD
+ * verdict applied to a command that was never a read, i.e. a new way to block work:
+ *
+ *  - ONE command only. Any `;` `&&` `||` `|` backtick `$(` or redirect and the answer is "not a read";
+ *    the command still runs the ordinary bash guards, exactly as today.
+ *  - `argv[0]` must be one of the six pure pagers, or `sed -n '<range>p'`.
+ *  - EVERY non-flag argument must resolve to a file that exists inside the tree. `cat /etc/passwd` is
+ *    not a read of this repo, and neither is a heredoc.
+ *
+ * A match does NOT replace the bash guards — the caller runs BOTH, and either may deny.
+ */
+const rules_config_1 = require("@webpieces/rules-config");
+var rules_config_2 = require("@webpieces/rules-config");
+Object.defineProperty(exports, "READ_COMMANDS", { enumerable: true, get: function () { return rules_config_2.READ_COMMANDS; } });
+/** Shell syntax that makes a command more than one command, or redirects it. Any hit ⇒ not a read. */
+const NOT_ONE_COMMAND = /[;|&`<>]|\$\(/;
+/** Flags that consume the FOLLOWING token as their value, so it is never mistaken for a file. */
+const VALUE_FLAGS = new Set(['-n', '-c', '-b', '-e', '-f']);
+/**
+ * The only `sed` script shape that is a read: a line range printed with `-n` — as a regex BODY, so the
+ * L0 allowlist's ERE twin can be built from the same characters instead of retyping them.
+ *
+ * EXPORTED for `bin/l0-allowlist.ts`. The L0 entry that lets a Codex session read its way out of an L0
+ * fault has to mean the same thing as this module or the two definitions of "read-shaped" drift, and a
+ * drifted L0 entry is either a hole or a deadlock. It cannot literally CALL this module — L0's sh half
+ * has no JS at all — so the shared thing is the vocabulary, and `codex-l0-read.spec.ts` asserts the two
+ * agree over a corpus.
+ */
+exports.SED_RANGE_BODY = '[0-9]+(,[0-9]+)?p';
+const SED_RANGE = new RegExp('^' + exports.SED_RANGE_BODY + '$');
+class ShellReadParity {
+    /**
+     * The absolute paths this command reads, or an empty list when it is not a read-shaped command.
+     * `root` is the tree the read must fall inside; a path outside it is not this repo's read.
+     */
+    readTargets(command, cwd, root) {
+        const trimmed = command.trim();
+        if (trimmed === '' || NOT_ONE_COMMAND.test(trimmed))
+            return [];
+        const tokens = this.tokenize(trimmed);
+        if (tokens === null || tokens.length < 2)
+            return [];
+        const argv0 = tokens[0];
+        const rest = argv0 === 'sed' ? this.sedOperands(tokens.slice(1)) : (rules_config_1.READ_COMMANDS.has(argv0) ? tokens.slice(1) : null);
+        if (rest === null)
+            return [];
+        const files = [];
+        let index = 0;
+        while (index < rest.length) {
+            const token = rest[index];
+            if (token.startsWith('-') && token !== '-') {
+                if (VALUE_FLAGS.has(token))
+                    index += 1;
+                index += 1;
+                continue;
+            }
+            const resolved = path.resolve(cwd, token);
+            if (!this.isFileInTree(resolved, root))
+                return [];
+            files.push(resolved);
+            index += 1;
+        }
+        return files;
+    }
+    /**
+     * `sed`'s operands, or null when this `sed` invocation is not a plain range print. `-n` and a
+     * single `<range>p` script are BOTH required: without `-n` sed echoes and edits, and any other
+     * script is a transformation, not a read.
+     */
+    sedOperands(args) {
+        if (!args.includes('-n'))
+            return null;
+        const scripts = args.filter((a) => !a.startsWith('-'));
+        if (scripts.length < 2)
+            return null;
+        if (!SED_RANGE.test(scripts[0]))
+            return null;
+        return scripts.slice(1);
+    }
+    isFileInTree(resolved, root) {
+        const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+        if (!resolved.startsWith(rootWithSep))
+            return false;
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.statSync(resolved).isFile();
+        }
+        catch (err) {
+            // Nothing is swallowed here: a token we cannot stat is simply NOT a read target, which is an
+            // ANSWER, and the command still runs the ordinary bash guards either way. The commented-out
+            // toError() call below is the form `catch-error-pattern` requires for a deliberately ignored
+            // error — it is the rule's spelling of "ignored on purpose", not a disabled line.
+            //const error = toError(err);
+            return false;
+        }
+    }
+    /**
+     * Split on whitespace, honouring single and double quotes. Returns null on an unterminated quote —
+     * a command we cannot read confidently is never a read.
+     *
+     * There is no escape or expansion handling here on purpose: `NOT_ONE_COMMAND` has already refused
+     * everything carrying shell syntax, so what reaches this is a literal argv.
+     */
+    tokenize(command) {
+        const tokens = [];
+        let current = '';
+        let quote = '';
+        let started = false;
+        for (const ch of command) {
+            if (quote !== '') {
+                if (ch === quote)
+                    quote = '';
+                else
+                    current += ch;
+                continue;
+            }
+            if (ch === '\'' || ch === '"') {
+                quote = ch;
+                started = true;
+                continue;
+            }
+            if (ch === ' ' || ch === '\t' || ch === '\n') {
+                if (started)
+                    tokens.push(current);
+                current = '';
+                started = false;
+                continue;
+            }
+            current += ch;
+            started = true;
+        }
+        if (quote !== '')
+            return null;
+        if (started)
+            tokens.push(current);
+        return tokens;
+    }
+}
+exports.ShellReadParity = ShellReadParity;
+//# sourceMappingURL=shell-read-parity.js.map

package/src/core/shell-read-parity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-read-parity.js","sourceRoot":"","sources":["../../../../../../packages/tooling/hook-runtime/src/core/shell-read-parity.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\n\n/**\n * READ PARITY, and it is a CODEX-ONLY surface.\n *\n * Claude Code has a first-class `Read` tool, so the read-scoped guard (read-stale-guard) and the\n * `calls/` audit trail see every file the agent opens. Codex has no such tool: a file read arrives as\n * `Bash` running `sed -n '1,240p' <path>` (measured). Without this, every Codex read is invisible to\n * the read guard and to the audit log, and the two harnesses cannot be compared at all.\n *\n * The caller gates this on `aiType === 'codex'`. Nothing here is reachable from a Claude Code payload,\n * and a spec pins that.\n *\n * DELIBERATELY CONSERVATIVE, because a false positive here is not a missed read — it is a Read GUARD\n * verdict applied to a command that was never a read, i.e. a new way to block work:\n *\n *  - ONE command only. Any `;` `&&` `||` `|` backtick `$(` or redirect and the answer is \"not a read\";\n *    the command still runs the ordinary bash guards, exactly as today.\n *  - `argv[0]` must be one of the six pure pagers, or `sed -n '<range>p'`.\n *  - EVERY non-flag argument must resolve to a file that exists inside the tree. `cat /etc/passwd` is\n *    not a read of this repo, and neither is a heredoc.\n *\n * A match does NOT replace the bash guards — the caller runs BOTH, and either may deny.\n */\nimport { READ_COMMANDS } from '@webpieces/rules-config';\nexport { READ_COMMANDS } from '@webpieces/rules-config';\n\n/** Shell syntax that makes a command more than one command, or redirects it. Any hit ⇒ not a read. */\nconst NOT_ONE_COMMAND = /[;|&`<>]|\\$\\(/;\n\n/** Flags that consume the FOLLOWING token as their value, so it is never mistaken for a file. */\nconst VALUE_FLAGS: ReadonlySet<string> = new Set(['-n', '-c', '-b', '-e', '-f']);\n\n/**\n * The only `sed` script shape that is a read: a line range printed with `-n` — as a regex BODY, so the\n * L0 allowlist's ERE twin can be built from the same characters instead of retyping them.\n *\n * EXPORTED for `bin/l0-allowlist.ts`. The L0 entry that lets a Codex session read its way out of an L0\n * fault has to mean the same thing as this module or the two definitions of \"read-shaped\" drift, and a\n * drifted L0 entry is either a hole or a deadlock. It cannot literally CALL this module — L0's sh half\n * has no JS at all — so the shared thing is the vocabulary, and `codex-l0-read.spec.ts` asserts the two\n * agree over a corpus.\n */\nexport const SED_RANGE_BODY = '[0-9]+(,[0-9]+)?p';\n\nconst SED_RANGE = new RegExp('^' + SED_RANGE_BODY + '$');\n\nexport class ShellReadParity {\n    /**\n     * The absolute paths this command reads, or an empty list when it is not a read-shaped command.\n     * `root` is the tree the read must fall inside; a path outside it is not this repo's read.\n     */\n    readTargets(command: string, cwd: string, root: string): readonly string[] {\n        const trimmed = command.trim();\n        if (trimmed === '' || NOT_ONE_COMMAND.test(trimmed)) return [];\n        const tokens = this.tokenize(trimmed);\n        if (tokens === null || tokens.length < 2) return [];\n\n        const argv0 = tokens[0];\n        const rest = argv0 === 'sed' ? this.sedOperands(tokens.slice(1)) : (READ_COMMANDS.has(argv0) ? tokens.slice(1) : null);\n        if (rest === null) return [];\n\n        const files: string[] = [];\n        let index = 0;\n        while (index < rest.length) {\n            const token = rest[index];\n            if (token.startsWith('-') && token !== '-') {\n                if (VALUE_FLAGS.has(token)) index += 1;\n                index += 1;\n                continue;\n            }\n            const resolved = path.resolve(cwd, token);\n            if (!this.isFileInTree(resolved, root)) return [];\n            files.push(resolved);\n            index += 1;\n        }\n        return files;\n    }\n\n    /**\n     * `sed`'s operands, or null when this `sed` invocation is not a plain range print. `-n` and a\n     * single `<range>p` script are BOTH required: without `-n` sed echoes and edits, and any other\n     * script is a transformation, not a read.\n     */\n    private sedOperands(args: readonly string[]): readonly string[] | null {\n        if (!args.includes('-n')) return null;\n        const scripts = args.filter((a: string): boolean => !a.startsWith('-'));\n        if (scripts.length < 2) return null;\n        if (!SED_RANGE.test(scripts[0])) return null;\n        return scripts.slice(1);\n    }\n\n    private isFileInTree(resolved: string, root: string): boolean {\n        const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;\n        if (!resolved.startsWith(rootWithSep)) return false;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.statSync(resolved).isFile();\n        } catch (err: unknown) {\n            // Nothing is swallowed here: a token we cannot stat is simply NOT a read target, which is an\n            // ANSWER, and the command still runs the ordinary bash guards either way. The commented-out\n            // toError() call below is the form `catch-error-pattern` requires for a deliberately ignored\n            // error — it is the rule's spelling of \"ignored on purpose\", not a disabled line.\n            //const error = toError(err);\n            return false;\n        }\n    }\n\n    /**\n     * Split on whitespace, honouring single and double quotes. Returns null on an unterminated quote —\n     * a command we cannot read confidently is never a read.\n     *\n     * There is no escape or expansion handling here on purpose: `NOT_ONE_COMMAND` has already refused\n     * everything carrying shell syntax, so what reaches this is a literal argv.\n     */\n    private tokenize(command: string): readonly string[] | null {\n        const tokens: string[] = [];\n        let current = '';\n        let quote = '';\n        let started = false;\n        for (const ch of command) {\n            if (quote !== '') {\n                if (ch === quote) quote = '';\n                else current += ch;\n                continue;\n            }\n            if (ch === '\\'' || ch === '\"') { quote = ch; started = true; continue; }\n            if (ch === ' ' || ch === '\\t' || ch === '\\n') {\n                if (started) tokens.push(current);\n                current = '';\n                started = false;\n                continue;\n            }\n            current += ch;\n            started = true;\n        }\n        if (quote !== '') return null;\n        if (started) tokens.push(current);\n        return tokens;\n    }\n}\n"]}

package/src/core/strip-ts-noise.d.ts

@@ -0,0 +1 @@
+export declare function stripTsNoise(source: string): string;