@bookedsolid/rea 0.31.0 → 0.33.0

package/dist/hooks/pr-issue-link-gate/index.js

@@ -0,0 +1,127 @@
+/**
+ * Node-binary port of `hooks/pr-issue-link-gate.sh`.
+ *
+ * 0.32.0 Phase 1 Pilot #1 — selected first because the bash original
+ * has the smallest dependency surface in the hook tree:
+ *
+ *   - No segment splitter (just substring match on `gh pr create`)
+ *   - No `--body-file` resolution
+ *   - No multi-pattern catalog
+ *   - Advisory only (always exits 0)
+ *
+ * That makes it the safest place to validate the playbook end-to-end:
+ * archive bash → write TS module → wire `rea hook pr-issue-link-gate`
+ * subcommand → replace .sh with a 15-line shim → mirror to
+ * `.claude/hooks/pr-issue-link-gate.sh` (PROTECTED — staged for git
+ * apply) → byte-fidelity test → consumer migration via `rea upgrade`
+ * picks up the new shim on next install.
+ *
+ * Behavioral contract — preserves bash hook byte-for-byte:
+ *
+ *   1. HALT check — exits 2 with banner when `.rea/HALT` is present.
+ *      Bash original called `check_halt` from `_lib/halt-check.sh`;
+ *      Node port calls the shared `checkHalt` primitive in
+ *      `src/hooks/_lib/halt-check.ts`. Same fail-closed posture.
+ *   2. Reads stdin payload, extracts `tool_input.command`. When the
+ *      tool isn't `Bash`, exits 0 silently (matches bash original
+ *      `[[ "$TOOL_NAME" != "Bash" ]] && exit 0`).
+ *   3. When command does NOT contain `gh\s+pr\s+create`, exits 0.
+ *   4. When command DOES contain a closing keyword paired with `#N`
+ *      (case-insensitive `closes`/`fixes`/`resolves` + whitespace +
+ *      `#` + digits), exits 0 — the agent has already linked an issue.
+ *   5. Otherwise, prints the same advisory banner to stderr and exits
+ *      0 (advisory only — never blocks).
+ *
+ * Wider-net pattern choice: the bash original used `grep -qiE
+ * 'gh\s+pr\s+create'` (free `\s` shorthand). The Node port uses the
+ * equivalent JavaScript regex `/gh\s+pr\s+create/i` — same byte
+ * outcomes for ASCII inputs, which is the only shape `gh` accepts.
+ */
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+const ADVISORY_BANNER = [
+    'PR ISSUE LINK ADVISORY: This PR does not reference a GitHub issue.\n',
+    '\n',
+    'When a PR body includes a closing reference, GitHub automatically:\n',
+    '  - Closes the issue when the PR merges to the default branch\n',
+    '  - Creates a cross-reference in the issue timeline\n',
+    '  - Links the PR in the CHANGELOG context\n',
+    '\n',
+    'Add to the --body:\n',
+    '  closes #N    closes one issue\n',
+    '  fixes #N     same effect\n',
+    '  resolves #N  same effect\n',
+    '  closes #N, closes #M   closes multiple issues\n',
+    '\n',
+    'If this is a chore, release, or hotfix PR with no upstream issue, you may proceed.\n',
+].join('');
+/**
+ * Pure executor — no `process.exit`, no stdin read (when
+ * `stdinOverride` is set), no HALT-check side effects beyond reading
+ * the file. Returns the exit code + full stderr; the CLI wrapper
+ * applies them to the actual process.
+ */
+export async function runPrIssueLinkGate(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(`pr-issue-link-gate: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr };
+        }
+        throw err;
+    }
+    // 3. Only Bash tool calls.
+    if (toolName !== '' && toolName !== 'Bash') {
+        return { exitCode: 0, stderr };
+    }
+    // 4. Only `gh pr create`.
+    if (!/gh\s+pr\s+create/i.test(cmd)) {
+        return { exitCode: 0, stderr };
+    }
+    // 5. Closing keyword paired with `#N` → satisfied, no advisory.
+    if (/(closes|fixes|resolves)\s+#[0-9]+/i.test(cmd)) {
+        return { exitCode: 0, stderr };
+    }
+    // 6. Advisory.
+    writeStderr(ADVISORY_BANNER);
+    return { exitCode: 0, stderr };
+}
+/**
+ * CLI entry — `rea hook pr-issue-link-gate`. Wires the pure executor
+ * to `process.stderr.write` + `process.exit`. Mirrors the wiring
+ * pattern in `runHookScanBash` / `runHookCodexReview`.
+ */
+export async function runHookPrIssueLinkGate(options = {}) {
+    const result = await runPrIssueLinkGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}
+// Internal export — used by the byte-fidelity test to assert the
+// advisory banner string hasn't drifted vs. the bash hook's
+// `printf` lines.
+export const __INTERNAL_ADVISORY_BANNER_FOR_TESTS = ADVISORY_BANNER;

package/dist/hooks/security-disclosure-gate/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Node-binary port of `hooks/security-disclosure-gate.sh`.
+ *
+ * 0.32.0 Phase 1 Pilot #2 — env-var-policy + body-file-resolver +
+ * mode-aware redirect router for `gh issue create` commands that
+ * mention vulnerability-class keywords.
+ *
+ * Why pilot #2 (and not #3): pilot #2 is the LARGEST of the three
+ * (339 LOC bash) and exercises every primitive landed in Phase 0:
+ *   - `checkHalt` (Phase 0)
+ *   - `parseHookPayload` (Phase 0)
+ *   - `splitSegments` / `anySegmentStartsWith` (Phase 0, used by
+ *     pilot #3 first but in scope here for `gh issue create`)
+ *   - File-IO resolver for `--body-file` / `-F` paths with `..`
+ *     traversal refusal, ABSOLUTE-vs-relative resolution, 64 KiB cap.
+ *   - Read of `REA_DISCLOSURE_MODE` env var with three-state semantics
+ *     (`advisory` / `issues` / `disabled`).
+ *
+ * Behavioral contract — preserves bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read `REA_DISCLOSURE_MODE` env var. `disabled` → exit 0
+ *      immediately (no scan at all).
+ *   3. Read stdin. If `tool_name` isn't `Bash`, exit 0.
+ *   4. Identify `gh issue create` segments via `anySegmentStartsWith`.
+ *      Substring fallback when the segment splitter is unreachable is
+ *      moot in Node — `splitSegments` is always in scope. (The bash
+ *      hook had a fallback only because `cmd-segments.sh` might be
+ *      absent in foreign installs.)
+ *   5. Resolve `--body-file PATH` and `-F PATH` arguments. The
+ *      resolver MUST match the bash quote-aware awk tokenizer for the
+ *      shape `--body-file "path with spaces.md"` — we run our own
+ *      quote-aware walker that yields each `--body-file` / `-F`
+ *      value. Stdin form (`-`) is skipped. Paths whose CANONICAL form
+ *      (after resolving `..` segments) escape REA_ROOT are REFUSED
+ *      with exit 2 + advisory banner (matches the 0.17.0 helix-019 #1
+ *      fix). Readable files contribute the first 64 KiB to the scan
+ *      buffer; unreadable files print a warning and continue.
+ *   6. Build `FULL_TEXT` = body-file contents + command text (both
+ *      lowercased) and scan for SECURITY_PATTERNS (an ordered list of
+ *      ERE patterns mirroring the bash array). First match wins;
+ *      `MATCHED_PATTERN` becomes the body-banner placeholder.
+ *   7. Route on mode:
+ *        - `issues`   → block banner pointing to `gh issue create
+ *                       --label 'security,internal' …` private form
+ *        - `advisory` → block banner pointing to `gh api
+ *                       repos/.../security-advisories` private form
+ *      Both return exit 2.
+ *
+ * Out-of-scope vs. the bash hook (intentional simplifications):
+ *
+ *   - The bash hook emits `json_output "block" "..."` via
+ *     `_lib/common.sh`. The JSON format is a Claude Code-specific
+ *     wrapper that lets the hook present a structured block reason
+ *     to the agent. In the Node tier, the canonical surface is `{
+ *     hookSpecificOutput: { hookEventName: 'PreToolUse', ... } }`
+ *     emitted on STDOUT with exit code 0; the legacy bash hook emits
+ *     it on stdout. We preserve that exact shape via `emitJsonBlock`.
+ *   - The bash hook's `require_jq` check is moot — Node parses JSON
+ *     natively.
+ */
+import { Buffer } from 'node:buffer';
+export type DisclosureMode = 'advisory' | 'issues' | 'disabled';
+export interface SecurityDisclosureGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+    stdoutWrite?: (s: string) => void;
+    /** Override `REA_DISCLOSURE_MODE`. Production reads `process.env`. */
+    disclosureModeOverride?: string;
+    /**
+     * Override `cwd()` for relative `--body-file` path resolution. The
+     * bash hook uses `pwd` (the shell's cwd at hook-execution time).
+     * Tests inject this so they don't have to `process.chdir`.
+     */
+    cwdOverride?: string;
+}
+export interface SecurityDisclosureGateResult {
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}
+/**
+ * Pure executor.
+ */
+export declare function runSecurityDisclosureGate(options?: SecurityDisclosureGateOptions): Promise<SecurityDisclosureGateResult>;
+/**
+ * CLI entry — `rea hook security-disclosure-gate`.
+ */
+export declare function runHookSecurityDisclosureGate(options?: SecurityDisclosureGateOptions): Promise<void>;
+export declare const __INTERNAL_SECURITY_PATTERNS_FOR_TESTS: readonly string[];