@bookedsolid/rea 0.10.0 → 0.10.2

package/dist/hooks/review-gate/banner.js

@@ -0,0 +1,172 @@
+/**
+ * Operator-facing banner composition.
+ *
+ * The bash core builds its banners via `printf` inside a `{ ... } >&2`
+ * block, counting diff lines with `grep -cE ...` and file changes with
+ * `grep -c '^+++ '`. Defect K (rea#62) surfaced because `grep -c`
+ * emits `0` to stdout AND exits non-zero on no-match, and the bash author
+ * wrote `$(grep -c ... || echo 0)` — which emitted `0\n0` when the pipe
+ * produced no matches. The fix in the bash core was `|| true` + default
+ * via `${LINE_COUNT:-0}`.
+ *
+ * The TS port closes this entire class of bug: counting happens over an
+ * actual string in Node, not via a pipe-on-a-side-effect. The only way
+ * LINE_COUNT / FILE_COUNT can ever be wrong now is a test-missed edge in
+ * `countChangedLines` or `countChangedFiles` — unit tests in `banner.test.ts`
+ * cover the zero case, the empty-diff case, the unicode-filename case, and
+ * the `+++ b/-file` edge explicitly.
+ *
+ * ## Format parity
+ *
+ * `renderPushReviewRequiredBanner` reproduces the byte-exact output of the
+ * bash core's "PUSH REVIEW GATE: Review required..." block, including the
+ * cache-disabled fallback branch. A fixture test in `banner.test.ts` asserts
+ * the output against a snapshot captured from the 0.10.1 bash core.
+ */
+/**
+ * Count lines that begin with `+` followed by a non-`+` character, OR `-`
+ * followed by a non-`-` character. Bash-core parity (push-review-core.sh
+ * §1082): `grep -cE '^\+[^+]|^-[^-]'`. This rejects every line whose
+ * SECOND character is the same as the first — not just `+++`/`---`
+ * headers, but also pathological `++foo` and `--bar` strings (which bash
+ * did not count). Codex pass-1 on phase 1 flagged the earlier too-lax
+ * char-1-only TS implementation that would have silently changed the
+ * Scope: banner line count vs. bash and broken phase-4 byte compatibility.
+ *
+ * Empty input → 0. Bare `+` or `-` (single char line) → 0, same as bash
+ * (the regex requires a second character).
+ */
+export function countChangedLines(diff) {
+    if (diff.length === 0)
+        return 0;
+    let n = 0;
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        if (line.length < 2)
+            continue;
+        const c0 = line.charCodeAt(0);
+        const c1 = line.charCodeAt(1);
+        // `+` = 43: match only when char-2 is NOT `+`.
+        if (c0 === 43 && c1 !== 43) {
+            n++;
+            continue;
+        }
+        // `-` = 45: match only when char-2 is NOT `-`.
+        if (c0 === 45 && c1 !== 45) {
+            n++;
+            continue;
+        }
+        // Any other leading char, including `++...` and `--...`, is skipped.
+    }
+    return n;
+}
+/**
+ * Count `^\+\+\+ ` header lines (one per file in the diff). Parity with
+ * the bash core's `grep -c '^\+\+\+ '`.
+ */
+export function countChangedFiles(diff) {
+    if (diff.length === 0)
+        return 0;
+    let n = 0;
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        if (line.startsWith('+++ '))
+            n++;
+    }
+    return n;
+}
+/**
+ * Compute `{line_count, file_count}` over a diff string. Exposed separately
+ * so callers can use just the stats without generating the full banner.
+ */
+export function computeDiffStats(diff) {
+    return {
+        line_count: countChangedLines(diff),
+        file_count: countChangedFiles(diff),
+    };
+}
+/**
+ * Compose the "PUSH REVIEW GATE: Review required before pushing" banner.
+ * Output goes to stderr via the caller; this function is pure. Returns the
+ * exact text the bash core would have printed (including trailing blank
+ * line and spacing), so the fixture snapshot can be compared byte-exactly.
+ */
+export function renderPushReviewRequiredBanner(input) {
+    const lines = [];
+    lines.push('PUSH REVIEW GATE: Review required before pushing');
+    lines.push('');
+    lines.push(`  Source ref: ${input.source_ref} (${input.source_sha.slice(0, 12)})`);
+    lines.push(`  Target: ${input.target_branch}`);
+    lines.push(`  Scope: ${input.stats.file_count} files changed, ${input.stats.line_count} lines`);
+    lines.push('');
+    lines.push('  Action required:');
+    lines.push(`  1. Spawn a code-reviewer agent to review: git diff ${input.merge_base}..${input.source_sha}`);
+    lines.push('  2. Spawn a security-engineer agent for security review');
+    if (input.push_sha.length > 0) {
+        lines.push('  3. After both pass, cache the result:');
+        lines.push(`     rea cache set ${input.push_sha} pass --branch ${input.source_branch} --base ${input.target_branch}`);
+    }
+    else {
+        lines.push('  3. Cache is DISABLED on this host (no sha256 hasher found).');
+        lines.push('     After both reviews pass, bypass the push-review gate with:');
+        lines.push('       REA_SKIP_PUSH_REVIEW="<reason>" git push ...');
+        lines.push('     The bypass is audited as push.review.skipped — this is the');
+        lines.push('     documented escape hatch when cache is unavailable.');
+        lines.push('     To restore the cache path, install one of: sha256sum,');
+        lines.push('     shasum (Perl Digest::SHA), or openssl.');
+    }
+    lines.push('');
+    // bash `printf '%s\n'` with no trailing args adds a final newline; the
+    // block renders terminal-ready. `lines.join('\n') + '\n'` reproduces
+    // exactly that shape.
+    return lines.join('\n') + '\n';
+}
+/**
+ * Compose the "PUSH BLOCKED: protected paths changed — /codex-review
+ * required" banner. Pure; exit-2 translation happens in the CLI shim.
+ */
+export function renderProtectedPathsBlockedBanner(input) {
+    const lines = [];
+    lines.push(`PUSH BLOCKED: protected paths changed — /codex-review required for ${input.source_sha}`);
+    lines.push('');
+    lines.push(`  Source ref: ${input.source_ref}`);
+    lines.push('  Diff touches one of:');
+    lines.push('    - src/gateway/middleware/');
+    lines.push('    - hooks/');
+    lines.push('    - .claude/hooks/');
+    lines.push('    - src/policy/');
+    lines.push('    - .github/workflows/');
+    lines.push('    - .rea/');
+    lines.push('    - .husky/');
+    lines.push('');
+    lines.push(`  Run /codex-review against ${input.source_sha}, then retry the push.`);
+    lines.push('  The codex-adversarial agent emits the required audit entry.');
+    lines.push('  Only `pass` or `concerns` verdicts satisfy this gate.');
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+/**
+ * Strip C0 control characters (0x00-0x1F, 0x7F) and C1 (0x80-0x9F) from a
+ * string. Used when a banner embeds text from a subprocess's stderr (e.g.
+ * the cache-check failure case). Mirrors the `LC_ALL=C tr -d` invocation
+ * in the bash core's cache-error path. Codex LOW 5 on the 0.9.4 pass.
+ */
+export function stripControlChars(input) {
+    let out = '';
+    for (let i = 0; i < input.length; i++) {
+        const c = input.charCodeAt(i);
+        // Allow tab (9), LF (10), CR (13) — but not any other C0/C1 byte.
+        if (c === 9 || c === 10 || c === 13) {
+            out += input[i];
+            continue;
+        }
+        if (c <= 0x1f)
+            continue;
+        if (c === 0x7f)
+            continue;
+        if (c >= 0x80 && c <= 0x9f)
+            continue;
+        out += input[i];
+    }
+    return out;
+}

package/dist/hooks/review-gate/cache-key.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cache-key computation. This module pins the contract between the push-
+ * review gate and the review-cache (`rea cache check` / `rea cache set`).
+ *
+ * ## The 0.10.1 revert constraint (design §8)
+ *
+ * An earlier attempt at defect N changed the cache-key input in the bash
+ * core and silently invalidated every consumer's existing cache. The
+ * failure was: the bash resolver started using the refspec target ref in
+ * the cache-key input rather than the merge-base-anchor SHA, so a
+ * legitimate cache entry from before the change produced a different key
+ * after the upgrade.
+ *
+ * The TS port makes the contract explicit:
+ *
+ *   cache_key = sha256_hex( full_git_diff_output )
+ *
+ * where `full_git_diff_output` is the UTF-8 string returned by
+ * `git diff <merge_base>..<source_sha>` with NO added framing. The key
+ * is NOT a function of ref names, branch names, or target labels — those
+ * are stored in the cache entry as context but do not participate in key
+ * derivation.
+ *
+ * ## Fixture-backed compatibility test
+ *
+ * `__fixtures__/cache-keys.json` records six scenarios captured from the
+ * 0.10.1 bash core (bare push, multi-refspec, force-push, deletion,
+ * new-branch, cross-repo). `cache-key.test.ts` asserts byte-exact
+ * `computeCacheKey(input) === expected` across all scenarios. Any phase
+ * that changes this module without updating the fixture fails the suite.
+ */
+import { type HexSha256 } from './hash.js';
+export interface CacheKeyInput {
+    /** Full `git diff <merge_base>..<source_sha>` output. */
+    diff: string;
+}
+/**
+ * Compute the cache key for a push-review entry. Stable, deterministic,
+ * pure. The key is the SHA-256 of the UTF-8 bytes of the diff string.
+ *
+ * @returns the 64-char lowercase hex digest.
+ */
+export declare function computeCacheKey(input: CacheKeyInput): HexSha256;
+/**
+ * Input shape for a cache-lookup call. The key itself is the diff digest
+ * from `computeCacheKey`; branch + base are context fields that select
+ * which entry within the key-bucket to return. The bash core and the
+ * existing `src/cache/review-cache.ts` both key lookups on
+ * `(sha, branch, base)`, and the TS port keeps that contract.
+ */
+export interface CacheLookupContext {
+    key: HexSha256;
+    branch: string;
+    base: string;
+}

package/dist/hooks/review-gate/cache-key.js

@@ -0,0 +1,41 @@
+/**
+ * Cache-key computation. This module pins the contract between the push-
+ * review gate and the review-cache (`rea cache check` / `rea cache set`).
+ *
+ * ## The 0.10.1 revert constraint (design §8)
+ *
+ * An earlier attempt at defect N changed the cache-key input in the bash
+ * core and silently invalidated every consumer's existing cache. The
+ * failure was: the bash resolver started using the refspec target ref in
+ * the cache-key input rather than the merge-base-anchor SHA, so a
+ * legitimate cache entry from before the change produced a different key
+ * after the upgrade.
+ *
+ * The TS port makes the contract explicit:
+ *
+ *   cache_key = sha256_hex( full_git_diff_output )
+ *
+ * where `full_git_diff_output` is the UTF-8 string returned by
+ * `git diff <merge_base>..<source_sha>` with NO added framing. The key
+ * is NOT a function of ref names, branch names, or target labels — those
+ * are stored in the cache entry as context but do not participate in key
+ * derivation.
+ *
+ * ## Fixture-backed compatibility test
+ *
+ * `__fixtures__/cache-keys.json` records six scenarios captured from the
+ * 0.10.1 bash core (bare push, multi-refspec, force-push, deletion,
+ * new-branch, cross-repo). `cache-key.test.ts` asserts byte-exact
+ * `computeCacheKey(input) === expected` across all scenarios. Any phase
+ * that changes this module without updating the fixture fails the suite.
+ */
+import { sha256Hex } from './hash.js';
+/**
+ * Compute the cache key for a push-review entry. Stable, deterministic,
+ * pure. The key is the SHA-256 of the UTF-8 bytes of the diff string.
+ *
+ * @returns the 64-char lowercase hex digest.
+ */
+export function computeCacheKey(input) {
+    return sha256Hex(input.diff);
+}

package/dist/hooks/review-gate/constants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Constants shared across the review-gate modules. Kept in one file so the
+ * values that a reader cares about (the all-zeros SHA, the empty-tree SHA,
+ * the protected-path set) are trivially grep-able.
+ */
+/** The git-native "null" SHA — a deletion on the pre-push contract. */
+export declare const ZERO_SHA = "0000000000000000000000000000000000000000";
+/**
+ * The canonical empty-tree SHA-1. Used as the merge-base baseline when a
+ * new-branch push has no remote-tracking ref to anchor on — `git diff
+ * <empty-tree>..<local_sha>` gives the full push content, and the gate
+ * treats it as a diff against nothing (which is what it is, operationally).
+ */
+export declare const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/**
+ * The protected-path set. A push that touches any file under one of these
+ * prefixes requires a matching `codex.review` audit record with verdict in
+ * {pass, concerns} AND emission_source in {rea-cli, codex-cli}. See the
+ * THREAT_MODEL for the full threat statement, and the design doc §9 for
+ * the carry-forward from the bash core.
+ *
+ * Pattern format: leading/trailing slashes stripped; matched as directory
+ * prefixes by `protected-paths.ts`. Order is not significant (a hit on any
+ * entry is sufficient), but we keep the list sorted for grep-ability.
+ */
+export declare const PROTECTED_PATH_PREFIXES: readonly string[];

package/dist/hooks/review-gate/constants.js

@@ -0,0 +1,34 @@
+/**
+ * Constants shared across the review-gate modules. Kept in one file so the
+ * values that a reader cares about (the all-zeros SHA, the empty-tree SHA,
+ * the protected-path set) are trivially grep-able.
+ */
+/** The git-native "null" SHA — a deletion on the pre-push contract. */
+export const ZERO_SHA = '0000000000000000000000000000000000000000';
+/**
+ * The canonical empty-tree SHA-1. Used as the merge-base baseline when a
+ * new-branch push has no remote-tracking ref to anchor on — `git diff
+ * <empty-tree>..<local_sha>` gives the full push content, and the gate
+ * treats it as a diff against nothing (which is what it is, operationally).
+ */
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * The protected-path set. A push that touches any file under one of these
+ * prefixes requires a matching `codex.review` audit record with verdict in
+ * {pass, concerns} AND emission_source in {rea-cli, codex-cli}. See the
+ * THREAT_MODEL for the full threat statement, and the design doc §9 for
+ * the carry-forward from the bash core.
+ *
+ * Pattern format: leading/trailing slashes stripped; matched as directory
+ * prefixes by `protected-paths.ts`. Order is not significant (a hit on any
+ * entry is sufficient), but we keep the list sorted for grep-ability.
+ */
+export const PROTECTED_PATH_PREFIXES = [
+    '.claude/hooks/',
+    '.github/workflows/',
+    '.husky/',
+    '.rea/',
+    'hooks/',
+    'src/gateway/middleware/',
+    'src/policy/',
+];

package/dist/hooks/review-gate/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed error set for the review-gate modules (G — push-review/commit-review
+ * TypeScript port).
+ *
+ * The bash core signals outcomes via exit codes + stderr banners. The TS port
+ * expresses each outcome as a typed error so callers can branch on class
+ * instead of parsing banner text, and so the eventual CLI entry point can
+ * translate a thrown error into the same exit code + banner the bash core
+ * emitted (preserving external contract per design §2, non-goals).
+ *
+ * Every error subclass carries:
+ *   - a stable `code` (for programmatic dispatch in tests + the CLI shim)
+ *   - an `exitCode` (matches the bash core's `exit N` semantics)
+ *   - the operator-facing `message` composed by `banner.ts`
+ *
+ * This module is intentionally dependency-free so unit tests can import it
+ * without dragging in fs/child_process. The CLI entry point is the single
+ * place that translates these to `process.exit(N)`.
+ */
+/**
+ * Stable discriminator used by tests and the CLI dispatch layer. String literals
+ * (not enum) so they survive JSON serialization in audit metadata.
+ */
+export type ReviewGateErrorCode = 'PUSH_BLOCKED_DELETE' | 'PUSH_BLOCKED_HEAD_REFSPEC' | 'PUSH_BLOCKED_SOURCE_UNRESOLVABLE' | 'PUSH_BLOCKED_NO_REFSPECS' | 'PUSH_BLOCKED_REMOTE_OBJECT_MISSING' | 'PUSH_BLOCKED_NO_MERGE_BASE' | 'PUSH_BLOCKED_NO_BASE_RESOLVABLE' | 'PUSH_BLOCKED_DIFF_FAILED' | 'PUSH_BLOCKED_REV_LIST_FAILED' | 'PUSH_BLOCKED_PROTECTED_PATHS' | 'PUSH_BLOCKED_SKIP_REFUSED_IN_CI' | 'PUSH_BLOCKED_SKIP_NO_ACTOR' | 'PUSH_BLOCKED_SKIP_AUDIT_FAILED' | 'PUSH_BLOCKED_SKIP_NOT_BUILT' | 'PUSH_BLOCKED_SKIP_METADATA_FAILED' | 'PUSH_BLOCKED_CACHE_MKTEMP_UNAVAILABLE' | 'PUSH_BLOCKED_NOT_IN_REPO' | 'PUSH_BLOCKED_DEPENDENCY_MISSING' | 'PUSH_REVIEW_REQUIRED';
+/**
+ * Base class. All review-gate errors derive from this so a CLI dispatch layer
+ * can `catch (e) { if (e instanceof ReviewGateError) ... }`.
+ */
+export declare class ReviewGateError extends Error {
+    readonly code: ReviewGateErrorCode;
+    readonly exitCode: number;
+    readonly details: Record<string, unknown>;
+    constructor(code: ReviewGateErrorCode, message: string, exitCode: number, details?: Record<string, unknown>);
+}
+/**
+ * Blocked-push errors (exit 2). The bash core uses exit 2 for every blocked
+ * condition; we preserve that invariant so the shim's exit code is unchanged.
+ */
+export declare class BlockedError extends ReviewGateError {
+    constructor(code: ReviewGateErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Deletion detected anywhere in the push (defect J). Must fail-closed even
+ * when a sibling refspec would have been reviewable.
+ */
+export declare class DeletionBlockedError extends BlockedError {
+    constructor();
+}
+/**
+ * A refspec with `HEAD` as destination is operator error (design §3.1,
+ * `pr_resolve_argv_refspecs`). Carry the refspec in details for banner render.
+ */
+export declare class HeadRefspecBlockedError extends BlockedError {
+    constructor(spec: string);
+}
+/**
+ * Invalid `--delete` refspec (empty destination or HEAD destination).
+ * Distinct from the general HEAD-refspec error because bash emits a
+ * different operator banner for the delete-mode case — the remediation
+ * text is "name the branch you meant to delete" rather than the HEAD
+ * destination error. See push-review-core.sh §161-168.
+ */
+export declare class InvalidDeleteRefspecError extends BlockedError {
+    constructor(spec: string);
+}
+/**
+ * Defect N completion (landed in phase 4, type reserved in phase 1 so
+ * `base-resolve.ts` can throw it later without schema churn).
+ */
+export declare class NoBaseResolvableError extends BlockedError {
+    constructor(source: string);
+}

package/dist/hooks/review-gate/errors.js

@@ -0,0 +1,100 @@
+/**
+ * Typed error set for the review-gate modules (G — push-review/commit-review
+ * TypeScript port).
+ *
+ * The bash core signals outcomes via exit codes + stderr banners. The TS port
+ * expresses each outcome as a typed error so callers can branch on class
+ * instead of parsing banner text, and so the eventual CLI entry point can
+ * translate a thrown error into the same exit code + banner the bash core
+ * emitted (preserving external contract per design §2, non-goals).
+ *
+ * Every error subclass carries:
+ *   - a stable `code` (for programmatic dispatch in tests + the CLI shim)
+ *   - an `exitCode` (matches the bash core's `exit N` semantics)
+ *   - the operator-facing `message` composed by `banner.ts`
+ *
+ * This module is intentionally dependency-free so unit tests can import it
+ * without dragging in fs/child_process. The CLI entry point is the single
+ * place that translates these to `process.exit(N)`.
+ */
+/**
+ * Base class. All review-gate errors derive from this so a CLI dispatch layer
+ * can `catch (e) { if (e instanceof ReviewGateError) ... }`.
+ */
+export class ReviewGateError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode, details = {}) {
+        super(message);
+        this.name = 'ReviewGateError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+        // Node gives us a stable prototype chain via Error; no need to hack it.
+    }
+}
+/**
+ * Blocked-push errors (exit 2). The bash core uses exit 2 for every blocked
+ * condition; we preserve that invariant so the shim's exit code is unchanged.
+ */
+export class BlockedError extends ReviewGateError {
+    constructor(code, message, details = {}) {
+        super(code, message, 2, details);
+        this.name = 'BlockedError';
+    }
+}
+/**
+ * Deletion detected anywhere in the push (defect J). Must fail-closed even
+ * when a sibling refspec would have been reviewable.
+ */
+export class DeletionBlockedError extends BlockedError {
+    constructor() {
+        super('PUSH_BLOCKED_DELETE', 'refspec is a branch deletion.\n' +
+            '\n' +
+            '  Branch deletions are sensitive operations and require explicit\n' +
+            '  human action outside the agent. Perform the deletion manually.\n');
+        this.name = 'DeletionBlockedError';
+    }
+}
+/**
+ * A refspec with `HEAD` as destination is operator error (design §3.1,
+ * `pr_resolve_argv_refspecs`). Carry the refspec in details for banner render.
+ */
+export class HeadRefspecBlockedError extends BlockedError {
+    constructor(spec) {
+        super('PUSH_BLOCKED_HEAD_REFSPEC', `refspec resolves to HEAD (from ${JSON.stringify(spec)})\n` +
+            '\n' +
+            '  `git push <remote> HEAD:<branch>` or similar is almost always\n' +
+            '  operator error in this context. Name the destination branch\n' +
+            '  explicitly so the review gate can diff against it.\n', { spec });
+        this.name = 'HeadRefspecBlockedError';
+    }
+}
+/**
+ * Invalid `--delete` refspec (empty destination or HEAD destination).
+ * Distinct from the general HEAD-refspec error because bash emits a
+ * different operator banner for the delete-mode case — the remediation
+ * text is "name the branch you meant to delete" rather than the HEAD
+ * destination error. See push-review-core.sh §161-168.
+ */
+export class InvalidDeleteRefspecError extends BlockedError {
+    constructor(spec) {
+        super('PUSH_BLOCKED_HEAD_REFSPEC', `--delete refspec resolves to HEAD or empty (from ${JSON.stringify(spec)})\n`, { spec, mode: 'delete' });
+        this.name = 'InvalidDeleteRefspecError';
+    }
+}
+/**
+ * Defect N completion (landed in phase 4, type reserved in phase 1 so
+ * `base-resolve.ts` can throw it later without schema churn).
+ */
+export class NoBaseResolvableError extends BlockedError {
+    constructor(source) {
+        super('PUSH_BLOCKED_NO_BASE_RESOLVABLE', `cannot resolve base branch for ${source}; run ` +
+            '`git branch --set-upstream-to=origin/<target>` or ' +
+            '`git config branch.' +
+            source +
+            '.base <ref>`', { source });
+        this.name = 'NoBaseResolvableError';
+    }
+}

package/dist/hooks/review-gate/hash.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Portable SHA-256 over arbitrary strings. Replaces the bash core's
+ * sha256sum → shasum → openssl fallback chain (defect L) with a single
+ * Node-stdlib call, removing the Alpine/distroless "no hasher on PATH"
+ * regression class entirely.
+ *
+ * ## Why a dedicated module
+ *
+ * The cache-key contract (design §8) requires byte-exact parity with the
+ * 0.10.1 bash implementation. The bash implementation computes
+ * `sha256sum( <full git diff> )` and uses the hex digest as the cache key.
+ * `crypto.createHash('sha256').update(s).digest('hex')` is bit-identical to
+ * GNU `sha256sum < <(printf '%s' s)` output (neither includes the
+ * filename-suffix padding). Regression-tested against the fixture in
+ * `__fixtures__/cache-keys.json`.
+ *
+ * ## Hex-64 validation
+ *
+ * The bash core validates the hasher output is `^[0-9a-f]{64}$` before using
+ * it as a cache key; a partial read or broken pipe would otherwise cache
+ * garbage. Node's `createHash` is synchronous and crypto-backed, so the
+ * digest is always a valid hex-64. We preserve the validation helper for
+ * any future path where user-supplied strings might be treated as SHAs (the
+ * bash core does this for push_sha env-pass, which the TS port rejects at
+ * the type level instead).
+ */
+/** A hex-lowercased SHA-256 digest (64 chars). */
+export type HexSha256 = string;
+/**
+ * Compute a SHA-256 over the UTF-8 bytes of `input`. Returns the lowercase
+ * hex digest.
+ *
+ * This is the one function the cache-key contract depends on — never change
+ * the encoding or the digest format without bumping the cache-key version
+ * (which none of phases 1–4 are permitted to do, per design §8).
+ */
+export declare function sha256Hex(input: string): HexSha256;
+/**
+ * True iff the input looks like a canonical lowercase SHA-256 hex digest.
+ * Used by tests and by defensive callers that accept a string and want to
+ * reject malformed input before writing it into the cache.
+ */
+export declare function isValidSha256Hex(value: string): value is HexSha256;

package/dist/hooks/review-gate/hash.js

@@ -0,0 +1,46 @@
+/**
+ * Portable SHA-256 over arbitrary strings. Replaces the bash core's
+ * sha256sum → shasum → openssl fallback chain (defect L) with a single
+ * Node-stdlib call, removing the Alpine/distroless "no hasher on PATH"
+ * regression class entirely.
+ *
+ * ## Why a dedicated module
+ *
+ * The cache-key contract (design §8) requires byte-exact parity with the
+ * 0.10.1 bash implementation. The bash implementation computes
+ * `sha256sum( <full git diff> )` and uses the hex digest as the cache key.
+ * `crypto.createHash('sha256').update(s).digest('hex')` is bit-identical to
+ * GNU `sha256sum < <(printf '%s' s)` output (neither includes the
+ * filename-suffix padding). Regression-tested against the fixture in
+ * `__fixtures__/cache-keys.json`.
+ *
+ * ## Hex-64 validation
+ *
+ * The bash core validates the hasher output is `^[0-9a-f]{64}$` before using
+ * it as a cache key; a partial read or broken pipe would otherwise cache
+ * garbage. Node's `createHash` is synchronous and crypto-backed, so the
+ * digest is always a valid hex-64. We preserve the validation helper for
+ * any future path where user-supplied strings might be treated as SHAs (the
+ * bash core does this for push_sha env-pass, which the TS port rejects at
+ * the type level instead).
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Compute a SHA-256 over the UTF-8 bytes of `input`. Returns the lowercase
+ * hex digest.
+ *
+ * This is the one function the cache-key contract depends on — never change
+ * the encoding or the digest format without bumping the cache-key version
+ * (which none of phases 1–4 are permitted to do, per design §8).
+ */
+export function sha256Hex(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+/**
+ * True iff the input looks like a canonical lowercase SHA-256 hex digest.
+ * Used by tests and by defensive callers that accept a string and want to
+ * reject malformed input before writing it into the cache.
+ */
+export function isValidSha256Hex(value) {
+    return /^[0-9a-f]{64}$/.test(value);
+}

package/dist/hooks/review-gate/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Public entry point for the review-gate TypeScript port (G).
+ *
+ * Phase 1 scope: expose the pure primitives (args, hash, banner, metadata,
+ * policy, protected-paths, cache-key, errors, constants) so they can be
+ * unit-tested and composed by phase 2's `runPushReviewGate` /
+ * `runCommitReviewGate`. No behavioral surface is registered here yet —
+ * the bash core in `hooks/_lib/push-review-core.sh` continues to run in
+ * production until phase 4.
+ *
+ * See `docs/design/push-review-ts-port.md` for the full plan.
+ */
+export * from './args.js';
+export * from './banner.js';
+export * from './cache-key.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './hash.js';
+export * from './metadata.js';
+export * from './policy.js';
+export * from './protected-paths.js';

package/dist/hooks/review-gate/index.js

@@ -0,0 +1,21 @@
+/**
+ * Public entry point for the review-gate TypeScript port (G).
+ *
+ * Phase 1 scope: expose the pure primitives (args, hash, banner, metadata,
+ * policy, protected-paths, cache-key, errors, constants) so they can be
+ * unit-tested and composed by phase 2's `runPushReviewGate` /
+ * `runCommitReviewGate`. No behavioral surface is registered here yet —
+ * the bash core in `hooks/_lib/push-review-core.sh` continues to run in
+ * production until phase 4.
+ *
+ * See `docs/design/push-review-ts-port.md` for the full plan.
+ */
+export * from './args.js';
+export * from './banner.js';
+export * from './cache-key.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './hash.js';
+export * from './metadata.js';
+export * from './policy.js';
+export * from './protected-paths.js';