@bookedsolid/rea 0.32.0 → 0.33.0

package/dist/hooks/dependency-audit-gate/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Node-binary port of `hooks/dependency-audit-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #2.
+ *
+ * Detects npm/pnpm/yarn `install|i|add` invocations and verifies that
+ * every named package exists on the npm registry before allowing the
+ * install. The original bash hook is the LARGEST member of the 0.33.0
+ * tier-1 batch (179 LOC) and the only one in this tier that makes a
+ * NETWORK call (spawning `npm view <pkg> name`).
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin → `tool_input.command`. Non-Bash tool → exit 0.
+ *   3. Empty command → exit 0.
+ *   4. Use the shared quote-aware segmenter to split on shell command
+ *      separators (`;`, `&&`, `||`, `|`, `&`, newline). For each
+ *      segment whose prefix-stripped head matches the install pattern
+ *      (`(npm install|i|add) | (pnpm add|install|i) | (yarn add)`),
+ *      extract the package-name tokens after the install command.
+ *      Skip tokens that:
+ *        - start with `-` (flags)
+ *        - start with `./`, `/`, `../` (path installs)
+ *        - contain shell metacharacters (`=`, `>`, `<`, `&`, `|`, `;`,
+ *          `$`, backtick, quotes)
+ *        - use workspace/link/file/git+ prefixes
+ *      Strip trailing `@version` so `lodash@^4.0` → `lodash`.
+ *   5. For each extracted package (capped at 5 per command — same
+ *      cap as the bash hook), spawn `npm view <pkg> name` with a 5s
+ *      timeout (when GNU `timeout` is available; falls back to a
+ *      JS-side timeout otherwise). Failed lookups accumulate.
+ *   6. If any failures, emit the same multi-line banner to stderr
+ *      and exit 2. Otherwise exit 0.
+ *
+ * Key fidelity choices:
+ *   - Segment-anchored: heredoc bodies / commit-message text that
+ *     happens to contain `pnpm install` does NOT trigger; the bash
+ *     hook's 0.15.0 fix is reproduced here via `splitSegments` +
+ *     anchor-on-segment-head.
+ *   - Env-prefix strip: `CI=1 pnpm add foo` → `pnpm add foo` for
+ *     matching purposes. The segments helper strips leading
+ *     `VAR=value` env-var assignments and shell prefixes (`sudo`,
+ *     `exec`, `time`).
+ *   - Network failure is a registry-not-found verdict, same as the
+ *     bash hook's `npm view` exit≠0 → "package missing" — we don't
+ *     distinguish ECONNREFUSED from "package not found", matching the
+ *     bash hook's fail-closed posture.
+ */
+import type { Buffer } from 'node:buffer';
+export interface DependencyAuditGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+    /**
+     * Test seam — replaces the live `npm view` spawn. Returns `true`
+     * when the package is verified to exist, `false` otherwise. The
+     * production caller binds this to the real `npm view <pkg> name`
+     * spawn with a 5s timeout.
+     */
+    verifyPackage?: (pkg: string) => Promise<boolean>;
+}
+export interface DependencyAuditGateResult {
+    exitCode: number;
+    stderr: string;
+    /**
+     * Test seam — packages this run attempted to verify, in order.
+     * Useful for assertion-driven tests without grepping stderr.
+     */
+    checkedPackages: string[];
+    failedPackages: string[];
+}
+/**
+ * Walk every segment of the command. For each segment whose stripped
+ * head matches the install pattern, contribute its package tokens.
+ */
+export declare function extractPackages(cmd: string): string[];
+/**
+ * Real verifier — spawns `npm view <pkg> name`. Resolves `true` when
+ * the registry confirms the package exists; `false` on timeout,
+ * non-zero exit, or spawn failure. The bash hook treats all three
+ * the same (`npm view` exit ≠ 0 → fail).
+ */
+export declare function verifyPackageReal(pkg: string): Promise<boolean>;
+export declare function runDependencyAuditGate(options?: DependencyAuditGateOptions): Promise<DependencyAuditGateResult>;
+/**
+ * CLI entry — `rea hook dependency-audit-gate`.
+ */
+export declare function runHookDependencyAuditGate(options?: DependencyAuditGateOptions): Promise<void>;
+export declare const __INTERNAL_INSTALL_PATTERN_FOR_TESTS: RegExp;
+export declare const __INTERNAL_MAX_PACKAGES_FOR_TESTS = 5;

package/dist/hooks/dependency-audit-gate/index.js

@@ -0,0 +1,294 @@
+/**
+ * Node-binary port of `hooks/dependency-audit-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #2.
+ *
+ * Detects npm/pnpm/yarn `install|i|add` invocations and verifies that
+ * every named package exists on the npm registry before allowing the
+ * install. The original bash hook is the LARGEST member of the 0.33.0
+ * tier-1 batch (179 LOC) and the only one in this tier that makes a
+ * NETWORK call (spawning `npm view <pkg> name`).
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin → `tool_input.command`. Non-Bash tool → exit 0.
+ *   3. Empty command → exit 0.
+ *   4. Use the shared quote-aware segmenter to split on shell command
+ *      separators (`;`, `&&`, `||`, `|`, `&`, newline). For each
+ *      segment whose prefix-stripped head matches the install pattern
+ *      (`(npm install|i|add) | (pnpm add|install|i) | (yarn add)`),
+ *      extract the package-name tokens after the install command.
+ *      Skip tokens that:
+ *        - start with `-` (flags)
+ *        - start with `./`, `/`, `../` (path installs)
+ *        - contain shell metacharacters (`=`, `>`, `<`, `&`, `|`, `;`,
+ *          `$`, backtick, quotes)
+ *        - use workspace/link/file/git+ prefixes
+ *      Strip trailing `@version` so `lodash@^4.0` → `lodash`.
+ *   5. For each extracted package (capped at 5 per command — same
+ *      cap as the bash hook), spawn `npm view <pkg> name` with a 5s
+ *      timeout (when GNU `timeout` is available; falls back to a
+ *      JS-side timeout otherwise). Failed lookups accumulate.
+ *   6. If any failures, emit the same multi-line banner to stderr
+ *      and exit 2. Otherwise exit 0.
+ *
+ * Key fidelity choices:
+ *   - Segment-anchored: heredoc bodies / commit-message text that
+ *     happens to contain `pnpm install` does NOT trigger; the bash
+ *     hook's 0.15.0 fix is reproduced here via `splitSegments` +
+ *     anchor-on-segment-head.
+ *   - Env-prefix strip: `CI=1 pnpm add foo` → `pnpm add foo` for
+ *     matching purposes. The segments helper strips leading
+ *     `VAR=value` env-var assignments and shell prefixes (`sudo`,
+ *     `exec`, `time`).
+ *   - Network failure is a registry-not-found verdict, same as the
+ *     bash hook's `npm view` exit≠0 → "package missing" — we don't
+ *     distinguish ECONNREFUSED from "package not found", matching the
+ *     bash hook's fail-closed posture.
+ */
+import { spawn } from 'node:child_process';
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+import { splitSegments } from '../_lib/segments.js';
+/**
+ * Cap on packages verified per command. Mirrors the bash hook's
+ * `if [[ $CHECKED -gt 5 ]]; then break; fi`. Designed to keep the
+ * hook latency bounded — `npm view` against a slow registry can
+ * take seconds per call.
+ */
+const MAX_PACKAGES_PER_COMMAND = 5;
+/**
+ * Per-package `npm view` timeout. Mirrors the bash hook's
+ * `timeout 5 npm view ...` (or fall-through to no-timeout when
+ * `timeout` is unavailable). We always enforce in JS-space so the
+ * Node port doesn't depend on a coreutils binary.
+ */
+const NPM_VIEW_TIMEOUT_MS = 5_000;
+/**
+ * Regex matching the install-command pattern at the head of a
+ * prefix-stripped segment. Case-insensitive (bash `grep -qiE`).
+ *
+ * Note: segments.ts's `stripSegmentPrefix` already removes leading
+ * `sudo`, `exec`, `time` and `VAR=value` env-vars, so we don't need
+ * to repeat them here.
+ */
+const INSTALL_PATTERN = /^(npm\s+(install|i|add)|pnpm\s+(add|install|i)|yarn\s+add)\s+/i;
+/**
+ * Tokens that look like flags or paths — never npm registry packages.
+ */
+function looksLikeFlagOrPath(token) {
+    if (token.startsWith('-'))
+        return true;
+    if (token.startsWith('./'))
+        return true;
+    if (token.startsWith('/'))
+        return true;
+    if (token.startsWith('../'))
+        return true;
+    return false;
+}
+/**
+ * Tokens that contain shell metacharacters — never valid npm package
+ * names. The bash hook lists this set explicitly in a single conditional;
+ * we mirror it character-for-character.
+ */
+function hasShellMeta(token) {
+    return (token.includes('=') ||
+        token.includes('>') ||
+        token.includes('<') ||
+        token.includes('&') ||
+        token.includes('|') ||
+        token.includes(';') ||
+        token.includes('$') ||
+        token.includes('`') ||
+        token.includes('"') ||
+        token.includes("'"));
+}
+/**
+ * Tokens that use a workspace / link / file / git+ protocol — never
+ * resolvable via the npm registry.
+ */
+function isWorkspaceProtocol(token) {
+    return (token.startsWith('workspace:') ||
+        token.startsWith('link:') ||
+        token.startsWith('file:') ||
+        token.startsWith('git+'));
+}
+/**
+ * Strip a trailing `@version` from a package spec.
+ *
+ *   lodash         → lodash
+ *   lodash@4.17.21 → lodash
+ *   @scope/pkg     → @scope/pkg (leading-@ preserved)
+ *   @scope/pkg@1   → @scope/pkg
+ *
+ * Mirrors the bash hook's `sed -E 's/@[^@/]+$//'`. The pattern strips
+ * a trailing `@<chars-without-/-or-@>` only — leading-scope `@` is
+ * untouched because it has either a `/` or another `@` to the right.
+ */
+function stripVersion(token) {
+    const stripped = token.replace(/@[^@/]+$/, '');
+    return stripped.length === 0 ? token : stripped;
+}
+/**
+ * Extract package-name tokens from a single segment that has already
+ * been matched against the install pattern. The bash hook's logic is
+ * reproduced verbatim.
+ */
+function extractFromSegmentHead(head) {
+    // After the install pattern, the remainder is the argv-style token
+    // list (still as a string). Whitespace-separated tokens, no shell
+    // parsing required at this point because segments are already
+    // unquoted by `splitSegments`.
+    const afterCmd = head.replace(INSTALL_PATTERN, '');
+    const tokens = afterCmd.split(/\s+/).filter((t) => t.length > 0);
+    const out = [];
+    for (const token of tokens) {
+        if (looksLikeFlagOrPath(token))
+            continue;
+        if (hasShellMeta(token))
+            continue;
+        if (isWorkspaceProtocol(token))
+            continue;
+        out.push(stripVersion(token));
+    }
+    return out;
+}
+/**
+ * Walk every segment of the command. For each segment whose stripped
+ * head matches the install pattern, contribute its package tokens.
+ */
+export function extractPackages(cmd) {
+    const out = [];
+    for (const seg of splitSegments(cmd)) {
+        if (!INSTALL_PATTERN.test(seg.head))
+            continue;
+        out.push(...extractFromSegmentHead(seg.head));
+    }
+    return out;
+}
+/**
+ * Real verifier — spawns `npm view <pkg> name`. Resolves `true` when
+ * the registry confirms the package exists; `false` on timeout,
+ * non-zero exit, or spawn failure. The bash hook treats all three
+ * the same (`npm view` exit ≠ 0 → fail).
+ */
+export function verifyPackageReal(pkg) {
+    return new Promise((resolve) => {
+        let resolved = false;
+        const settle = (ok) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            resolve(ok);
+        };
+        const child = spawn('npm', ['view', pkg, 'name'], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* best effort */
+            }
+            settle(false);
+        }, NPM_VIEW_TIMEOUT_MS);
+        timer.unref?.();
+        child.on('exit', (code) => {
+            settle(code === 0);
+        });
+        child.on('error', () => {
+            settle(false);
+        });
+    });
+}
+function buildFailureBanner(failed) {
+    const lines = [
+        'DEPENDENCY AUDIT: Package not found on npm registry\n',
+        '\n',
+        '  The following packages could not be verified:\n',
+    ];
+    for (const pkg of failed) {
+        lines.push(`  - ${pkg}\n`);
+    }
+    lines.push('\n');
+    lines.push('  Rule: All packages must exist on the npm registry before installation.\n');
+    lines.push('  Check: Is the package name spelled correctly? Does it exist on npmjs.com?\n');
+    return lines.join('');
+}
+export async function runDependencyAuditGate(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    const checkedPackages = [];
+    const failedPackages = [];
+    // 1. HALT.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr, checkedPackages, failedPackages };
+    }
+    // 2. Stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let toolName = '';
+    let cmd = '';
+    try {
+        const payload = parseHookPayload(stdinRaw);
+        toolName = payload.toolName;
+        cmd = payload.command;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`dependency-audit-gate: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr, checkedPackages, failedPackages };
+        }
+        throw err;
+    }
+    if (toolName !== '' && toolName !== 'Bash') {
+        return { exitCode: 0, stderr, checkedPackages, failedPackages };
+    }
+    if (cmd.length === 0) {
+        return { exitCode: 0, stderr, checkedPackages, failedPackages };
+    }
+    const packages = extractPackages(cmd);
+    if (packages.length === 0) {
+        return { exitCode: 0, stderr, checkedPackages, failedPackages };
+    }
+    const verify = options.verifyPackage ?? verifyPackageReal;
+    for (const pkg of packages) {
+        if (checkedPackages.length >= MAX_PACKAGES_PER_COMMAND)
+            break;
+        if (pkg.length === 0)
+            continue;
+        checkedPackages.push(pkg);
+        const ok = await verify(pkg);
+        if (!ok)
+            failedPackages.push(pkg);
+    }
+    if (failedPackages.length > 0) {
+        writeStderr(buildFailureBanner(failedPackages));
+        return { exitCode: 2, stderr, checkedPackages, failedPackages };
+    }
+    return { exitCode: 0, stderr, checkedPackages, failedPackages };
+}
+/**
+ * CLI entry — `rea hook dependency-audit-gate`.
+ */
+export async function runHookDependencyAuditGate(options = {}) {
+    const result = await runDependencyAuditGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}
+export const __INTERNAL_INSTALL_PATTERN_FOR_TESTS = INSTALL_PATTERN;
+export const __INTERNAL_MAX_PACKAGES_FOR_TESTS = MAX_PACKAGES_PER_COMMAND;

package/dist/hooks/env-file-protection/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Node-binary port of `hooks/env-file-protection.sh`.
+ *
+ * 0.33.0 Phase 1 port #1 (tier-1 advisory/single-purpose hooks).
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner.
+ *   2. Read stdin, extract `tool_input.command`.
+ *   3. Only Bash tool calls (matches the bash hook's PreToolUse Bash
+ *      matcher — non-Bash payloads bypass).
+ *   4. Empty command → exit 0.
+ *   5. Three independent block patterns:
+ *        - segment-anchored `source ... .env` / `. ... .env`
+ *        - segment-anchored `cp ... .env`
+ *        - any-segment co-occurrence of a text-reading utility
+ *          (cat/head/tail/less/more/grep/sed/awk/bat/strings/printf/
+ *           xargs/tee/jq/python -c/ruby -e) AND a `.env*`/`.envrc`
+ *          filename WITHIN THE SAME segment. The co-occurrence
+ *          property is critical: multi-segment commands like
+ *          `echo "fix: don't cat .env" ; touch foo.env` would
+ *          false-positive under two independent any-segment booleans.
+ *   6. Match → exit 2 with the matching advisory banner; otherwise
+ *      exit 0.
+ *
+ * Pattern parity with the bash hook is by-design verbatim. The bash
+ * regex bodies are reused literally so a future addition to the
+ * utility list lands in one place. Case-insensitive (`grep -qiE` in
+ * bash; `new RegExp(..., 'i')` here) — same posture.
+ */
+import type { Buffer } from 'node:buffer';
+export interface EnvFileProtectionOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface EnvFileProtectionResult {
+    exitCode: number;
+    stderr: string;
+}
+/**
+ * Pure executor. Returns `{ exitCode, stderr }`; the CLI wrapper
+ * translates them into `process.stderr.write` + `process.exit`.
+ */
+export declare function runEnvFileProtection(options?: EnvFileProtectionOptions): Promise<EnvFileProtectionResult>;
+/**
+ * CLI entry point — `rea hook env-file-protection`.
+ */
+export declare function runHookEnvFileProtection(options?: EnvFileProtectionOptions): Promise<void>;
+export declare const __INTERNAL_PATTERNS_FOR_TESTS: {
+    PATTERN_UTILITY: string;
+    PATTERN_SOURCE: string;
+    PATTERN_CP_ENV: string;
+    PATTERN_ENV_FILE: string;
+};

package/dist/hooks/env-file-protection/index.js

@@ -0,0 +1,159 @@
+/**
+ * Node-binary port of `hooks/env-file-protection.sh`.
+ *
+ * 0.33.0 Phase 1 port #1 (tier-1 advisory/single-purpose hooks).
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner.
+ *   2. Read stdin, extract `tool_input.command`.
+ *   3. Only Bash tool calls (matches the bash hook's PreToolUse Bash
+ *      matcher — non-Bash payloads bypass).
+ *   4. Empty command → exit 0.
+ *   5. Three independent block patterns:
+ *        - segment-anchored `source ... .env` / `. ... .env`
+ *        - segment-anchored `cp ... .env`
+ *        - any-segment co-occurrence of a text-reading utility
+ *          (cat/head/tail/less/more/grep/sed/awk/bat/strings/printf/
+ *           xargs/tee/jq/python -c/ruby -e) AND a `.env*`/`.envrc`
+ *          filename WITHIN THE SAME segment. The co-occurrence
+ *          property is critical: multi-segment commands like
+ *          `echo "fix: don't cat .env" ; touch foo.env` would
+ *          false-positive under two independent any-segment booleans.
+ *   6. Match → exit 2 with the matching advisory banner; otherwise
+ *      exit 0.
+ *
+ * Pattern parity with the bash hook is by-design verbatim. The bash
+ * regex bodies are reused literally so a future addition to the
+ * utility list lands in one place. Case-insensitive (`grep -qiE` in
+ * bash; `new RegExp(..., 'i')` here) — same posture.
+ */
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+import { anySegmentStartsWith, anySegmentMatchesBoth, } from '../_lib/segments.js';
+/**
+ * Patterns mirroring the bash hook's PATTERN_* shell vars.
+ *
+ * `PATTERN_UTILITY` — text-reading utilities. Bash uses
+ *   `(cat|head|tail|less|more|grep|sed|awk|bat|strings|printf|xargs|
+ *    tee|jq|python3?[[:space:]]+-c|ruby[[:space:]]+-e)[[:space:]]`.
+ *   We carry the same body; bash POSIX char classes are translated to
+ *   their JavaScript regex equivalents (`[[:space:]]` → `\s`).
+ *
+ * `PATTERN_SOURCE` / `PATTERN_CP_ENV` — anchored at segment start. The
+ *   `any_segment_starts_with` walker strips leading prefixes (sudo,
+ *   env-var assignments) before applying the regex, so we DO NOT
+ *   re-anchor with `^` here.
+ *
+ * `PATTERN_ENV_FILE` — matches `.env*`, `.env.local`, `.envrc`, etc.
+ *   The trailing `(\s|"|'|$)` boundary in the bash hook keeps it from
+ *   matching `foo.environment` style identifiers; we preserve that.
+ */
+const PATTERN_UTILITY = '(cat|head|tail|less|more|grep|sed|awk|bat|strings|printf|xargs|tee|jq|python3?\\s+-c|ruby\\s+-e)\\s';
+const PATTERN_SOURCE = "(source|\\.)\\s+[^;|&]*\\.env";
+const PATTERN_CP_ENV = "cp\\s+[^;|&]*\\.env";
+const PATTERN_ENV_FILE = '(\\.env[a-zA-Z0-9._-]*|\\.envrc)(\\s|"|\'|$)';
+const MAX_DISPLAY_CMD_LEN = 100;
+function truncate(cmd) {
+    if (cmd.length <= MAX_DISPLAY_CMD_LEN)
+        return cmd;
+    return cmd.slice(0, MAX_DISPLAY_CMD_LEN) + '...';
+}
+function buildSourceBanner(cmd) {
+    return [
+        'ENV FILE PROTECTION: Direct sourcing or copying of .env files is blocked.\n',
+        '\n',
+        `  Command: ${truncate(cmd)}\n`,
+        '\n',
+        '  Rule: Load credentials in code only — never via shell source or cp.\n',
+        '  Use: process.env.VAR_NAME, os.environ["VAR_NAME"], etc.\n',
+    ].join('');
+}
+function buildReadBanner(cmd) {
+    return [
+        'ENV FILE PROTECTION: Reading .env files via Bash is blocked.\n',
+        '\n',
+        `  Command: ${truncate(cmd)}\n`,
+        '\n',
+        '  Rule: Load credentials in code only, never via shell.\n',
+        '  Use: process.env.VAR_NAME, os.environ["VAR_NAME"], etc.\n',
+        '  .env files must not be read via shell utilities in agent sessions.\n',
+    ].join('');
+}
+/**
+ * Pure executor. Returns `{ exitCode, stderr }`; the CLI wrapper
+ * translates them into `process.stderr.write` + `process.exit`.
+ */
+export async function runEnvFileProtection(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    // 1. HALT check — fail-closed (exit 2).
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr };
+    }
+    // 2. Read stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let toolName = '';
+    let cmd = '';
+    try {
+        const payload = parseHookPayload(stdinRaw);
+        toolName = payload.toolName;
+        cmd = payload.command;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`env-file-protection: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr };
+        }
+        throw err;
+    }
+    // 3. Only Bash tool calls. The bash hook's PreToolUse Bash matcher
+    //    only fires for Bash dispatches, but the shim's relevance pre-
+    //    gate is a substring scan that can over-trigger; the CLI
+    //    re-checks for safety.
+    if (toolName !== '' && toolName !== 'Bash') {
+        return { exitCode: 0, stderr };
+    }
+    // 4. Empty command → allow.
+    if (cmd.length === 0) {
+        return { exitCode: 0, stderr };
+    }
+    // 5a. Direct source/cp of .env — segment-anchored.
+    if (anySegmentStartsWith(cmd, PATTERN_SOURCE) ||
+        anySegmentStartsWith(cmd, PATTERN_CP_ENV)) {
+        writeStderr(buildSourceBanner(cmd));
+        return { exitCode: 2, stderr };
+    }
+    // 5b. Utility + .env co-occurrence within the same segment.
+    if (anySegmentMatchesBoth(cmd, PATTERN_UTILITY, PATTERN_ENV_FILE)) {
+        writeStderr(buildReadBanner(cmd));
+        return { exitCode: 2, stderr };
+    }
+    return { exitCode: 0, stderr };
+}
+/**
+ * CLI entry point — `rea hook env-file-protection`.
+ */
+export async function runHookEnvFileProtection(options = {}) {
+    const result = await runEnvFileProtection({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}
+// Internal exports for byte-fidelity / banner-drift tests.
+export const __INTERNAL_PATTERNS_FOR_TESTS = {
+    PATTERN_UTILITY,
+    PATTERN_SOURCE,
+    PATTERN_CP_ENV,
+    PATTERN_ENV_FILE,
+};