@bookedsolid/rea 0.22.0 → 0.23.1

package/dist/hooks/bash-scanner/blocked-scan.js

@@ -0,0 +1,467 @@
+/**
+ * Blocked-paths policy composition. Mirrors `blocked-paths-bash-gate.sh`
+ * + the `_match_blocked` helper byte-for-byte:
+ *
+ *   - directory entry (ends with `/`): prefix match OR exact match
+ *     against the bare-dir form (entry without trailing slash)
+ *   - glob entry (contains `*`): convert to ERE (escape `.`, `*` → `.*`),
+ *     anchored, case-insensitive
+ *   - exact (case-insensitive) otherwise
+ *
+ * Path normalization is identical to protected-scan.ts: URL-decode,
+ * backslash → slash, leading-./ strip, `..` walk-up + outside-root
+ * sentinel, optional symlink-resolved form.
+ *
+ * Out-of-scope-of-blocked: paths outside REA_ROOT. blocked_paths is a
+ * project-relative concept; an outside-root write can't match a
+ * blocked_paths entry. The PROTECTED-paths gate handles outside-root
+ * rejection on the protected list itself.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { allowVerdict, blockVerdict } from './verdict.js';
+function normalizeTarget(reaRoot, raw, form) {
+    let t = raw;
+    if (t.length >= 2 && t.startsWith('"') && t.endsWith('"'))
+        t = t.slice(1, -1);
+    if (t.length >= 2 && t.startsWith("'") && t.endsWith("'"))
+        t = t.slice(1, -1);
+    // Codex round 1 F-15: strip backslash-escapes prefixing path chars.
+    t = stripBashBackslashEscapes(t);
+    // Codex round 1 F-16: ANSI-C $'…' quoting → dynamic.
+    if (t.startsWith("$'") || t.includes("$'")) {
+        return {
+            pathLc: '__rea_unresolved_expansion__',
+            outsideRoot: false,
+            expansion: true,
+            original: raw,
+            resolvedLc: null,
+        };
+    }
+    if (t.includes('$') || t.includes('`')) {
+        return {
+            pathLc: '__rea_unresolved_expansion__',
+            outsideRoot: false,
+            expansion: true,
+            original: raw,
+            resolvedLc: null,
+        };
+    }
+    // Codex round 1 F-14: glob metachars in REDIRECT targets → dynamic.
+    // See protected-scan.ts::normalizeTarget for the rationale on
+    // scoping this to redirect-form only.
+    if (form === 'redirect' && containsGlobMetachar(t)) {
+        return {
+            pathLc: '__rea_unresolved_expansion__',
+            outsideRoot: false,
+            expansion: true,
+            original: raw,
+            resolvedLc: null,
+        };
+    }
+    // Codex round 1 F-24: tilde expansion → dynamic.
+    if (t === '~' || t.startsWith('~/') || t.startsWith('~')) {
+        return {
+            pathLc: '__rea_unresolved_expansion__',
+            outsideRoot: false,
+            expansion: true,
+            original: raw,
+            resolvedLc: null,
+        };
+    }
+    let normalized = t;
+    try {
+        normalized = decodeURIComponent(t);
+    }
+    catch {
+        normalized = t;
+    }
+    normalized = normalized.replace(/\\/g, '/');
+    while (normalized.startsWith('./')) {
+        normalized = normalized.slice(2);
+    }
+    let abs = normalized;
+    if (!abs.startsWith('/')) {
+        abs = path.join(reaRoot, abs);
+    }
+    const collapsed = collapseDotDot(abs);
+    if (!isInsideRoot(collapsed, reaRoot)) {
+        // blocked_paths is project-relative; an outside-root write can't
+        // match. Return a non-matching sentinel form that the matcher
+        // ignores — same posture as the bash hook's "outside root → exit 0".
+        return {
+            pathLc: `__outside_root_allowed:${collapsed.toLowerCase()}`,
+            outsideRoot: true,
+            expansion: false,
+            original: raw,
+            resolvedLc: null,
+        };
+    }
+    const projectRelative = collapsed === reaRoot ? '' : collapsed.slice(reaRoot.length + 1);
+    const inputHadTrailingSlash = normalized.endsWith('/');
+    const pathLc = (inputHadTrailingSlash && projectRelative.length > 0 && !projectRelative.endsWith('/')
+        ? projectRelative + '/'
+        : projectRelative).toLowerCase();
+    let resolvedLc = null;
+    try {
+        const resolved = resolveSymlinksWalkUp(collapsed);
+        if (resolved === SYMLINK_DYNAMIC_SENTINEL) {
+            // Codex round 2 R2-2: cycle / depth-cap → refuse on uncertainty.
+            return {
+                pathLc: '__rea_unresolved_expansion__',
+                outsideRoot: false,
+                expansion: true,
+                original: raw,
+                resolvedLc: null,
+            };
+        }
+        if (resolved !== null) {
+            const realRoot = realpathSafe(reaRoot) ?? reaRoot;
+            let resolvedRelative = null;
+            if (resolved === realRoot)
+                resolvedRelative = '';
+            else if (resolved.startsWith(realRoot + '/'))
+                resolvedRelative = resolved.slice(realRoot.length + 1);
+            else if (resolved.startsWith(reaRoot + '/'))
+                resolvedRelative = resolved.slice(reaRoot.length + 1);
+            if (resolvedRelative !== null) {
+                const candidate = resolvedRelative.toLowerCase();
+                if (candidate !== pathLc)
+                    resolvedLc = candidate;
+            }
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return { pathLc, outsideRoot: false, expansion: false, original: raw, resolvedLc };
+}
+function collapseDotDot(absPath) {
+    const parts = absPath.split('/');
+    const out = [];
+    for (const p of parts) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..') {
+            out.pop();
+        }
+        else {
+            out.push(p);
+        }
+    }
+    return '/' + out.join('/');
+}
+function isInsideRoot(absPath, reaRoot) {
+    if (absPath === reaRoot)
+        return true;
+    const realRoot = realpathSafe(reaRoot);
+    if (realRoot && absPath === realRoot)
+        return true;
+    if (absPath.startsWith(reaRoot + '/'))
+        return true;
+    if (realRoot && absPath.startsWith(realRoot + '/'))
+        return true;
+    return false;
+}
+function realpathSafe(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk to the nearest existing-or-symlink ancestor and resolve. Codex
+ * round 1 F-2 — see protected-scan.ts::resolveSymlinksWalkUp for the
+ * full rationale.
+ *
+ * Codex round 2 R2-2: same cycle-guard + depth-cap as protected-scan.
+ * Returns SYMLINK_DYNAMIC_SENTINEL to signal "refuse on uncertainty".
+ */
+const SYMLINK_DYNAMIC_SENTINEL = Symbol('symlink-dynamic-blocked');
+const SYMLINK_DEPTH_CAP = 32;
+function resolveSymlinksWalkUp(absPath) {
+    return resolveSymlinksWalkUpInner(absPath, new Set(), 0);
+}
+function resolveSymlinksWalkUpInner(absPath, visited, depth) {
+    if (depth >= SYMLINK_DEPTH_CAP)
+        return SYMLINK_DYNAMIC_SENTINEL;
+    if (visited.has(absPath))
+        return SYMLINK_DYNAMIC_SENTINEL;
+    visited.add(absPath);
+    const parts = absPath.split('/').filter((p) => p.length > 0);
+    for (let i = parts.length; i >= 0; i -= 1) {
+        const prefix = '/' + parts.slice(0, i).join('/');
+        const lstat = lstatSafe(prefix);
+        if (lstat !== null) {
+            if (lstat.isSymbolicLink()) {
+                const linkTarget = readlinkSafe(prefix);
+                if (linkTarget === null)
+                    return null;
+                const linkDir = '/' + parts.slice(0, i - 1).join('/');
+                const targetAbs = linkTarget.startsWith('/')
+                    ? linkTarget
+                    : path.resolve(linkDir, linkTarget);
+                const recursive = resolveSymlinksWalkUpInner(targetAbs, visited, depth + 1);
+                if (recursive === SYMLINK_DYNAMIC_SENTINEL)
+                    return SYMLINK_DYNAMIC_SENTINEL;
+                if (recursive === null)
+                    return null;
+                const tail = parts.slice(i).join('/');
+                return tail.length === 0
+                    ? recursive
+                    : recursive === '/'
+                        ? '/' + tail
+                        : recursive + '/' + tail;
+            }
+            const real = realpathSafe(prefix);
+            if (real === null)
+                return null;
+            const tail = parts.slice(i).join('/');
+            if (tail.length === 0)
+                return real;
+            return real === '/' ? '/' + tail : real + '/' + tail;
+        }
+    }
+    return null;
+}
+function lstatSafe(p) {
+    try {
+        return fs.lstatSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function readlinkSafe(p) {
+    try {
+        return fs.readlinkSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function stripBashBackslashEscapes(s) {
+    return s.replace(/\\([A-Za-z0-9./_~\-])/g, '$1');
+}
+function containsGlobMetachar(s) {
+    return /[*?[{]/.test(s);
+}
+/**
+ * Match a normalized lowercase path against the blocked_paths list.
+ * Returns the matching entry (preserving original case for the error
+ * message) or null.
+ */
+function matchBlockedEntry(pathLc, blockedPaths, options) {
+    const inputHadTrailingSlash = pathLc.endsWith('/');
+    const inputIsDir = inputHadTrailingSlash || (options?.forceDirSemantics ?? false);
+    const inputBase = inputHadTrailingSlash ? pathLc.slice(0, -1) : pathLc;
+    for (const entry of blockedPaths) {
+        const entryLc = entry.toLowerCase();
+        // Directory match.
+        if (entryLc.endsWith('/')) {
+            if (pathLc.startsWith(entryLc))
+                return entry;
+            if (pathLc === entryLc.slice(0, -1))
+                return entry;
+            // Codex round 1 F-7: dir-target input matches a dir-pattern
+            // even when `pathLc` is `.rea` (no trailing slash) but the
+            // walker flagged it as dir-target.
+            if (inputIsDir && entryLc.startsWith(inputBase + '/'))
+                return entry;
+            continue;
+        }
+        // Glob match.
+        if (entry.includes('*')) {
+            const re = globToRegex(entryLc);
+            if (re.test(pathLc))
+                return entry;
+            continue;
+        }
+        // Exact match.
+        if (pathLc === entryLc)
+            return entry;
+        // Dir-target input vs file entry inside that dir.
+        if (inputIsDir && entryLc.startsWith(inputBase + '/'))
+            return entry;
+    }
+    return null;
+}
+/**
+ * Convert a glob entry to a case-insensitive anchored regex. Mirrors
+ * the bash `sed` transform applied in the pre-0.23.0 hook: escape `.`,
+ * convert `*` to `.*`, anchor both ends. We additionally escape every
+ * other regex metacharacter so values like `[`, `(`, `+` in a
+ * blocked_paths entry don't blow up at runtime.
+ */
+function globToRegex(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob.charAt(i);
+        if (c === '*') {
+            re += '.*';
+        }
+        else if (c === '?') {
+            re += '.';
+        }
+        else {
+            // Escape any regex-meta characters.
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp('^' + re + '$', 'i');
+}
+function buildBlockReason(args) {
+    return [
+        'BLOCKED PATH (bash): write denied by policy',
+        '',
+        `  Blocked by:      ${args.entry}`,
+        `  Resolved target: ${args.hitForm}`,
+        `  Original token:  ${args.originalToken}`,
+        `  Detected as:     ${args.detectedForm}`,
+        '',
+        '  Source: .rea/policy.yaml → blocked_paths',
+        '  Rule: blocked_paths entries are unreachable via Bash redirects',
+        '        too — not just Write/Edit/MultiEdit. To modify, a human',
+        '        must edit directly or update blocked_paths in policy.yaml.',
+    ].join('\n');
+}
+export function scanForBlockedViolations(ctx, detections) {
+    if (ctx.blockedPaths.length === 0)
+        return allowVerdict();
+    if (detections.length === 0)
+        return allowVerdict();
+    for (const d of detections) {
+        if (d.dynamic) {
+            if (d.form === 'xargs_unresolvable') {
+                return blockVerdict({
+                    reason: [
+                        'BLOCKED PATH (bash): xargs destination is fed via stdin and cannot be statically resolved.',
+                        '',
+                        '  rea refuses on uncertainty against the blocked_paths policy. Rewrite without',
+                        '  xargs (use a loop with explicit destinations).',
+                    ].join('\n'),
+                    hitPattern: '(xargs unresolvable stdin)',
+                    detectedForm: d.form,
+                    ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+                });
+            }
+            if (d.form === 'nested_shell_inner') {
+                return blockVerdict({
+                    reason: [
+                        'BLOCKED PATH (bash): nested-shell payload is dynamic or exceeds the recursion depth cap (8).',
+                        '',
+                        '  rea refuses on uncertainty.',
+                    ].join('\n'),
+                    hitPattern: '(nested-shell unresolvable)',
+                    detectedForm: d.form,
+                    ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+                });
+            }
+            // Codex round 11 F11-1 / F11-5 / F11-4: refuse-on-uncertainty
+            // forms surfaced as dynamic detections. Same pattern as
+            // protected-scan: each form gets its own message.
+            if (d.form === 'find_exec_placeholder_unresolvable') {
+                return blockVerdict({
+                    reason: [
+                        'BLOCKED PATH (bash): find -exec with `{}` placeholder targets runtime-resolved paths.',
+                        '',
+                        '  rea refuses on uncertainty.',
+                    ].join('\n'),
+                    hitPattern: '(find -exec placeholder unresolvable)',
+                    detectedForm: d.form,
+                    ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+                });
+            }
+            if (d.form === 'parallel_stdin_unresolvable') {
+                return blockVerdict({
+                    reason: [
+                        'BLOCKED PATH (bash): parallel without `:::` reads inputs from stdin and cannot be statically resolved.',
+                        '',
+                        '  rea refuses on uncertainty.',
+                    ].join('\n'),
+                    hitPattern: '(parallel stdin unresolvable)',
+                    detectedForm: d.form,
+                    ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+                });
+            }
+            if (d.form === 'archive_extract_unresolvable') {
+                return blockVerdict({
+                    reason: [
+                        'BLOCKED PATH (bash): archive extraction targets are unresolvable.',
+                        '',
+                        '  rea refuses on uncertainty.',
+                    ].join('\n'),
+                    hitPattern: '(archive extract unresolvable)',
+                    detectedForm: d.form,
+                    ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+                });
+            }
+            return blockVerdict({
+                reason: [
+                    'BLOCKED PATH (bash): unresolved shell expansion in target.',
+                    '',
+                    `  Token:           ${d.path}`,
+                    `  Detected as:     ${d.form}`,
+                ].join('\n'),
+                hitPattern: '(dynamic target)',
+                detectedForm: d.form,
+                ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+            });
+        }
+        if (d.path.length === 0)
+            continue;
+        const norm = normalizeTarget(ctx.reaRoot, d.path, d.form);
+        if (norm.expansion) {
+            return blockVerdict({
+                reason: [
+                    'BLOCKED PATH (bash): unresolved shell expansion in target.',
+                    '',
+                    `  Token:           ${norm.original}`,
+                    `  Detected as:     ${d.form}`,
+                ].join('\n'),
+                hitPattern: '(dynamic target)',
+                detectedForm: d.form,
+                ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+            });
+        }
+        if (norm.outsideRoot) {
+            // blocked_paths is project-relative; outside-root paths can't
+            // match. Continue to the next detection.
+            continue;
+        }
+        const dirOptions = d.isDirTarget === true ? { forceDirSemantics: true } : undefined;
+        const logicalHit = matchBlockedEntry(norm.pathLc, ctx.blockedPaths, dirOptions);
+        if (logicalHit !== null) {
+            return blockVerdict({
+                reason: buildBlockReason({
+                    entry: logicalHit,
+                    hitForm: norm.pathLc,
+                    detectedForm: d.form,
+                    originalToken: norm.original,
+                }),
+                hitPattern: logicalHit,
+                detectedForm: d.form,
+                ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+            });
+        }
+        if (norm.resolvedLc !== null) {
+            const resolvedHit = matchBlockedEntry(norm.resolvedLc, ctx.blockedPaths, dirOptions);
+            if (resolvedHit !== null) {
+                return blockVerdict({
+                    reason: buildBlockReason({
+                        entry: resolvedHit,
+                        hitForm: norm.resolvedLc,
+                        detectedForm: d.form,
+                        originalToken: norm.original,
+                    }),
+                    hitPattern: resolvedHit,
+                    detectedForm: d.form,
+                    ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+                });
+            }
+        }
+    }
+    return allowVerdict();
+}

package/dist/hooks/bash-scanner/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `src/hooks/bash-scanner/` — parser-backed bash-tier scanner. Replaces
+ * the regex-and-segmenter pipeline at `hooks/_lib/cmd-segments.sh` +
+ * `hooks/_lib/interpreter-scanner.sh` with an AST-driven walker.
+ *
+ * Public surface:
+ *
+ *   - `runProtectedScan(ctx, cmd)`   — protected-paths gate
+ *   - `runBlockedScan(ctx, cmd)`     — blocked_paths gate
+ *
+ * Both return a `Verdict` (allow|block + reason). The CLI subcommand
+ * `rea hook scan-bash` consumes the verdict and translates to exit
+ * codes for the bash shims.
+ */
+import { type ProtectedScanContext } from './protected-scan.js';
+import { type BlockedScanContext } from './blocked-scan.js';
+import type { Verdict } from './verdict.js';
+export type { Verdict, DetectedForm, SourcePosition } from './verdict.js';
+export type { DetectedWrite } from './walker.js';
+export type { ProtectedScanContext } from './protected-scan.js';
+export type { BlockedScanContext } from './blocked-scan.js';
+export { allowVerdict, blockVerdict, parseFailureVerdict } from './verdict.js';
+/**
+ * Run the protected-paths scanner against a bash command string.
+ *
+ * Empty / whitespace-only commands are an immediate allow (the bash
+ * gate's `[[ -z "$CMD" ]] && exit 0` guard).
+ *
+ * Parse failures BLOCK — see `parse-fail-closed.ts` for the contract
+ * rationale. The bash gates pre-0.23.0 silently allowed on segmenter
+ * failure; the rewrite closes that bug class definitionally.
+ */
+export declare function runProtectedScan(ctx: ProtectedScanContext, cmd: string): Verdict;
+/**
+ * Run the blocked_paths scanner against a bash command string. Identical
+ * structure to runProtectedScan; the policy data shape differs.
+ *
+ * Empty blockedPaths list → allow (matches the bash gate's no-op
+ * exit-0 behavior when policy.blocked_paths is empty).
+ */
+export declare function runBlockedScan(ctx: BlockedScanContext, cmd: string): Verdict;

package/dist/hooks/bash-scanner/index.js

@@ -0,0 +1,62 @@
+/**
+ * `src/hooks/bash-scanner/` — parser-backed bash-tier scanner. Replaces
+ * the regex-and-segmenter pipeline at `hooks/_lib/cmd-segments.sh` +
+ * `hooks/_lib/interpreter-scanner.sh` with an AST-driven walker.
+ *
+ * Public surface:
+ *
+ *   - `runProtectedScan(ctx, cmd)`   — protected-paths gate
+ *   - `runBlockedScan(ctx, cmd)`     — blocked_paths gate
+ *
+ * Both return a `Verdict` (allow|block + reason). The CLI subcommand
+ * `rea hook scan-bash` consumes the verdict and translates to exit
+ * codes for the bash shims.
+ */
+import { parseBashCommand } from './parser.js';
+import { walkForWrites } from './walker.js';
+import { scanForProtectedViolations } from './protected-scan.js';
+import { scanForBlockedViolations } from './blocked-scan.js';
+import { buildParseFailureVerdict } from './parse-fail-closed.js';
+export { allowVerdict, blockVerdict, parseFailureVerdict } from './verdict.js';
+/**
+ * Run the protected-paths scanner against a bash command string.
+ *
+ * Empty / whitespace-only commands are an immediate allow (the bash
+ * gate's `[[ -z "$CMD" ]] && exit 0` guard).
+ *
+ * Parse failures BLOCK — see `parse-fail-closed.ts` for the contract
+ * rationale. The bash gates pre-0.23.0 silently allowed on segmenter
+ * failure; the rewrite closes that bug class definitionally.
+ */
+export function runProtectedScan(ctx, cmd) {
+    if (cmd.trim().length === 0) {
+        return { verdict: 'allow' };
+    }
+    const parsed = parseBashCommand(cmd);
+    if (!parsed.ok) {
+        return buildParseFailureVerdict({ parserMessage: parsed.error, originalCommand: cmd });
+    }
+    const detections = walkForWrites(parsed.file);
+    return scanForProtectedViolations(ctx, detections);
+}
+/**
+ * Run the blocked_paths scanner against a bash command string. Identical
+ * structure to runProtectedScan; the policy data shape differs.
+ *
+ * Empty blockedPaths list → allow (matches the bash gate's no-op
+ * exit-0 behavior when policy.blocked_paths is empty).
+ */
+export function runBlockedScan(ctx, cmd) {
+    if (cmd.trim().length === 0) {
+        return { verdict: 'allow' };
+    }
+    if (ctx.blockedPaths.length === 0) {
+        return { verdict: 'allow' };
+    }
+    const parsed = parseBashCommand(cmd);
+    if (!parsed.ok) {
+        return buildParseFailureVerdict({ parserMessage: parsed.error, originalCommand: cmd });
+    }
+    const detections = walkForWrites(parsed.file);
+    return scanForBlockedViolations(ctx, detections);
+}

package/dist/hooks/bash-scanner/parse-fail-closed.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Parser-failure handling. The contract: any failure of the parser
+ * (malformed bash, unterminated quote, etc.) returns BLOCK with a
+ * canned reason. NEVER ALLOW on parse failure — that is the entire
+ * bug class this 0.23.0 rewrite exists to close.
+ *
+ * Lifted into its own module so the bash-shim contract is easy to
+ * eyeball: the verdict shape on parse failure is a stable wire format,
+ * and snapshot-tested in `verdict-shape.test.ts`.
+ */
+import { type Verdict } from './verdict.js';
+export interface ParseFailureInput {
+    /** The raw parser error message (already normalized to a string). */
+    parserMessage: string;
+    /** The original command string the parser rejected (truncated for log size). */
+    originalCommand?: string;
+}
+/**
+ * Build a parse-failure verdict. Wraps `parseFailureVerdict` so callers
+ * have a single import point for both the construction logic and the
+ * "must always block" contract.
+ *
+ * Implementation note: we intentionally DO NOT include `originalCommand`
+ * in the verdict body. The parser message alone is enough for the
+ * operator to debug, and including the full command in a JSON wire-
+ * format that flows through stderr risks log-injection vectors (a
+ * crafted command could embed ANSI escapes in its literals). The
+ * `input` field is consumed only by structured logging in callers
+ * that opt in to it.
+ */
+export declare function buildParseFailureVerdict(input: ParseFailureInput): Verdict;

package/dist/hooks/bash-scanner/parse-fail-closed.js

@@ -0,0 +1,27 @@
+/**
+ * Parser-failure handling. The contract: any failure of the parser
+ * (malformed bash, unterminated quote, etc.) returns BLOCK with a
+ * canned reason. NEVER ALLOW on parse failure — that is the entire
+ * bug class this 0.23.0 rewrite exists to close.
+ *
+ * Lifted into its own module so the bash-shim contract is easy to
+ * eyeball: the verdict shape on parse failure is a stable wire format,
+ * and snapshot-tested in `verdict-shape.test.ts`.
+ */
+import { parseFailureVerdict } from './verdict.js';
+/**
+ * Build a parse-failure verdict. Wraps `parseFailureVerdict` so callers
+ * have a single import point for both the construction logic and the
+ * "must always block" contract.
+ *
+ * Implementation note: we intentionally DO NOT include `originalCommand`
+ * in the verdict body. The parser message alone is enough for the
+ * operator to debug, and including the full command in a JSON wire-
+ * format that flows through stderr risks log-injection vectors (a
+ * crafted command could embed ANSI escapes in its literals). The
+ * `input` field is consumed only by structured logging in callers
+ * that opt in to it.
+ */
+export function buildParseFailureVerdict(input) {
+    return parseFailureVerdict(input.parserMessage);
+}

package/dist/hooks/bash-scanner/parser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Thin wrapper around `mvdan-sh` — the GopherJS-compiled JS port of
+ * the upstream Go bash parser at `mvdan.cc/sh/v3/syntax`.
+ *
+ * Why a wrapper:
+ *   1. The parser instance is mutable (it tracks state across calls
+ *      to `Parse`). Construct once per process; serialize all parses
+ *      through it. Multiple concurrent Node CLI invocations get one
+ *      parser each — fine, it's cheap.
+ *   2. The library throws Go-style error objects with `.Error()`
+ *      methods, not native JS Errors. Normalize them to native Error
+ *      with a clean message.
+ *   3. Callers care only about three outcomes: parsed, parse-failed,
+ *      or unexpected JS-level throw. Collapse the Go-vs-JS-error
+ *      ambiguity to a single discriminated union.
+ *
+ * 0.23.0 — first release of this module. Pinned to mvdan-sh@0.10.1
+ * (deprecated upstream but functionally complete; see issue 1145).
+ * If we ever migrate to `sh-syntax` (the WASM successor), this
+ * wrapper is the only file that changes — everything downstream
+ * works against `BashFile`/`BashNode` from our local d.ts shim.
+ */
+import type { BashFile } from 'mvdan-sh';
+export type ParseResult = {
+    ok: true;
+    file: BashFile;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse a bash command string into an AST. Returns a tagged union so
+ * the caller never has to wrap this in try/catch — every failure mode
+ * (Go parse error, JS throw, weird native return) is collapsed to
+ * `{ ok: false, error }`.
+ *
+ * Empty / whitespace-only input is a no-op success — the parser
+ * returns a `File` with zero `Stmts`, which the walker will yield
+ * zero detections for. Equivalent to the bash gates' `[[ -z "$CMD" ]]
+ * && exit 0` guard.
+ */
+export declare function parseBashCommand(src: string): ParseResult;