@bookedsolid/rea 0.3.0 → 0.4.0

package/dist/cli/install/pre-push.d.ts

@@ -0,0 +1,335 @@
+/**
+ * G6 — Pre-push hook fallback installer.
+ *
+ * Ships alongside `commit-msg.ts` as a second-line defender for the
+ * protected-path Codex audit gate. The primary path is `.husky/pre-push`,
+ * which rea copies into the consumer's `.husky/` via the canonical copy
+ * module. That file only runs when the consumer has husky active
+ * (`core.hooksPath` points at `.husky/`). Consumers who have never run
+ * `husky install`, or who have disabled husky entirely, would otherwise get
+ * ZERO pre-push enforcement — and the protected-path gate is exactly the
+ * thing we cannot let silently lapse.
+ *
+ * The fallback writes a small shell script that `exec`s the same
+ * `push-review-gate.sh` logic the Claude Code hook already runs. The gate
+ * itself is shared — we do NOT duplicate its 700 lines.
+ *
+ * ## Install policy (decision tree, documented)
+ *
+ * Given a consumer repo, we must decide where (if anywhere) to install a
+ * fallback `pre-push`:
+ *
+ *   1. `core.hooksPath` unset (vanilla git):
+ *      → Install `.git/hooks/pre-push`. This is the only path git will fire.
+ *        `.husky/pre-push` sits on disk as a source-of-truth copy but is not
+ *        consulted by git directly.
+ *
+ *   2. `core.hooksPath` set to a directory containing an EXECUTABLE,
+ *      governance-carrying `pre-push`:
+ *      → Do NOT install. A hook is "governance-carrying" when it either
+ *        carries our `FALLBACK_MARKER` (rea-managed) or execs / invokes
+ *        `.claude/hooks/push-review-gate.sh` (consumer-wired delegation).
+ *        This is the happy path for any project running husky 9+ that has
+ *        wired the gate.
+ *
+ *   3. `core.hooksPath` set to a directory with a pre-push that is NOT
+ *      governance-carrying (wrong bits, unrelated script, lint-only husky
+ *      hook, directory, etc.):
+ *      → Classify as foreign. Leave it alone, warn the user, and let
+ *        `rea doctor` downgrade the check to `warn` so the gap is visible.
+ *
+ *   4. `core.hooksPath` set to a directory WITHOUT a pre-push:
+ *      → Install into the configured hooksPath (as `pre-push`). This is the
+ *        "hooksPath is set but nothing lives there yet" case. The active
+ *        hook directory has changed; we install where git will actually look.
+ *
+ * Idempotency: every install writes a stable managed header
+ * (`# rea:pre-push-fallback v1`). Re-running `rea init` detects the header
+ * by ANCHORED match (exact second line after the shebang) and refreshes in
+ * place; it NEVER overwrites a hook without our marker — if the consumer
+ * has their own pre-push already, we warn and skip. Substring matches are
+ * deliberately rejected: a consumer comment, a grep log, or copy-pasted
+ * snippet containing the sentinel must not reclassify a foreign file as
+ * rea-managed.
+ *
+ * ## Why not just rely on `.husky/pre-push`?
+ *
+ * Three concrete failure modes we saw during 0.2.x dogfooding:
+ *   - Consumer hasn't run `husky install` (fresh clone, pnpm hasn't run
+ *     postinstall yet, etc.). `.husky/pre-push` exists but git's hooksPath
+ *     still points at `.git/hooks/`. No enforcement.
+ *   - Consumer deliberately uses `core.hooksPath=./custom-hooks` with a
+ *     different tool. `.husky/pre-push` is dead weight.
+ *   - CI or release automation disables husky via `HUSKY=0`. Again, no
+ *     enforcement at push time.
+ *
+ * The protected-path Codex audit requirement is too important to let any
+ * of those slip through silently. See THREAT_MODEL.md §Governance for the
+ * full rationale.
+ */
+/**
+ * Marker baked into every rea-installed fallback pre-push hook. Used for
+ * idempotency: on re-run we refresh files carrying the marker and refuse
+ * to touch anything that doesn't.
+ *
+ * Bump the version suffix whenever the embedded script semantics change so
+ * upgrades can migrate old installs. Comparison is NOT a substring match —
+ * see `isReaManagedFallback` for the anchored form required to classify
+ * a file as rea-managed.
+ */
+export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v1";
+/**
+ * Marker present in the shipped `.husky/pre-push` governance gate. Detection
+ * requires the marker to appear on the SECOND LINE of the file (immediately
+ * after the shebang) to prevent a consumer comment or copy-pasted snippet
+ * that mentions the string from causing a foreign hook to be misclassified
+ * as rea-managed and then silently overwritten. See `isReaManagedHuskyGate`
+ * for the anchored check.
+ */
+export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v1";
+/**
+ * Second versioned marker embedded in the body of the shipped `.husky/pre-push`.
+ * Required alongside `HUSKY_GATE_MARKER` so that a hook containing only the
+ * header marker + `exit 0` (or any stub body) is not classified as rea-managed.
+ * A genuine rea Husky gate always carries both. The marker is versioned so it
+ * can be bumped if the gate implementation changes significantly.
+ */
+export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v1";
+/**
+ * True when `content` starts with the exact rea fallback prelude. The
+ * marker must appear as the second line, immediately after the shebang,
+ * with no leading whitespace, no alternate shebang (`#!/usr/bin/env sh`),
+ * and no interposed blank lines. Anything else is foreign.
+ *
+ * Rejecting a substring match is what stops a consumer comment like
+ * `# Hint: the old rea:pre-push-fallback v1 marker moved into .husky/` from
+ * accidentally classifying a user's own hook as rea-managed and then
+ * getting overwritten on the next `rea init`.
+ */
+export declare function isReaManagedFallback(content: string): boolean;
+/**
+ * True when `content` has the shipped Husky gate marker on the SECOND LINE
+ * (immediately after the shebang). This is the canonical structure of the
+ * rea-authored `.husky/pre-push` — the shebang occupies line 1 and the marker
+ * occupies line 2 with no intervening blank lines.
+ *
+ * Requiring line-2 placement prevents a consumer comment, copy-pasted snippet,
+ * or any other text that merely *mentions* the marker string from reclassifying
+ * a consumer-owned hook as rea-managed and triggering an overwrite on the next
+ * `rea init`. A marker buried anywhere else in the file is not the canonical
+ * structure and must not be trusted.
+ *
+ * This classification is checked BEFORE `isReaManagedFallback` in
+ * `classifyExistingHook` so that the shipped `.husky/pre-push` is recognized
+ * as a governance-carrying hook rather than `foreign/no-marker`.
+ */
+export declare function isReaManagedHuskyGate(content: string): boolean;
+/**
+ * Pre-0.4 rea-authored `.husky/pre-push` shape — same governance behavior
+ * as the current gate but lacks the line-2/3 versioned markers
+ * (`# rea:husky-pre-push-gate v1` / `# rea:gate-body-v1`) introduced in
+ * 0.4.
+ *
+ * Codex R21 F1: without this detector, any consumer upgrading from a rea
+ * release that shipped the pre-marker hook fell into `foreign/no-marker`.
+ * `classifyPrePushInstall` mapped that to `skip/foreign-pre-push` and
+ * `rea init` refused to touch the file. `rea doctor` reported
+ * `activeForeign=true`. Users had no self-heal path short of manually
+ * deleting the hook — which is a bad migration story for a governance
+ * primitive that they are supposed to trust.
+ *
+ * Shape-level detection:
+ *   1. Line 2 is the canonical pre-0.4 filename header
+ *      `# .husky/pre-push — rea governance gate for terminal-initiated pushes.`
+ *      This header shipped verbatim across the 0.2.x/0.3.x rea releases.
+ *   2. Real governance still present — `hasHaltEnforcement(content)` AND
+ *      `hasAuditCheck(content)` both pass. A stub that only matches the
+ *      header comment (no enforcement) fails the shape check and stays
+ *      classified as foreign.
+ *
+ * Classification consequence: `classifyExistingHook` returns
+ * `rea-managed-husky` for legacy matches. `classifyPrePushInstall` maps
+ * that to `skip/active-pre-push-present` — `rea init` does not touch the
+ * hook (correctness: the file IS still functional governance), but
+ * `inspectPrePushState` reports `ok=true, activeForeign=false` so doctor
+ * stops flagging it. The canonical-manifest-driven upgrade path
+ * (`rea upgrade`) detects the hash mismatch against the packaged
+ * `.husky/pre-push` and surfaces the legacy shape as drift, letting the
+ * operator opt into the refresh explicitly.
+ */
+export declare function isLegacyReaManagedHuskyGate(content: string): boolean;
+/**
+ * True when `content` contains a REAL shell invocation of
+ * `push-review-gate.sh`. Used as a softer signal that a consumer-owned
+ * pre-push still wires the shared gate (e.g. a husky 9 file that runs
+ * lint AND execs the gate). Combined with "exists AND executable", a
+ * gate-referencing foreign hook is a legitimate integration point —
+ * doctor reports `pass`, install skips.
+ *
+ * Accepts (positive-match allowlist):
+ *   - Bare invocation: `.claude/hooks/push-review-gate.sh "$@"`
+ *   - POSIX exec keyword: `exec`, `.`, `sh`, `bash`, `zsh` followed by the
+ *     gate path. The bash-only `source` keyword is NOT accepted — the POSIX
+ *     equivalent `.` (dot) is.
+ *   - Quoted/expanded path prefix: `exec "$REA_ROOT"/.claude/hooks/push-review-gate.sh "$@"`
+ *     — double- or single-quoted variable expansions before the literal path
+ *     are treated as part of the path, not as a mention context.
+ *   - Trailing `;` after `exec <gate>`: `exec gate.sh "$@";` — exec replaces
+ *     the shell, so the `;` and anything after it never runs; gate exit IS
+ *     the hook's exit status.
+ *   - Variable indirection: `GATE=<path-containing-gate>` on one line plus
+ *     `exec "$GATE"` / `. "$GATE"` / etc. on a later line.
+ *
+ * Rejects:
+ *   - Comment lines starting with `#`
+ *   - Shell tests: `[ -x .claude/hooks/push-review-gate.sh ]`
+ *   - File tests: `test -f .claude/hooks/push-review-gate.sh`
+ *   - Chmod / cp / mv / cat / printf / echo mentioning the path
+ *   - String literals inside quoted arguments to non-invocation commands
+ *   - Invocations inside `if`/`for`/`while`/`case` blocks (conditional —
+ *     not guaranteed to run)
+ *   - Invocations after an unconditional top-level `exit`
+ *   - Non-`exec` invocations followed by `||`, `&&`, `;`, or trailing `&`
+ *     (status-swallowing operators)
+ *
+ * This is a pragmatic heuristic, not a full shell parser. R12 F2 broadened
+ * the allowlist to match the forms Codex flagged as valid but previously
+ * rejected; narrower patterns silently hard-failed `rea doctor` on
+ * correctly-governed consumer repos.
+ */
+export declare function referencesReviewGate(content: string): boolean;
+/**
+ * Resolve a configured `core.hooksPath` (possibly relative) to an absolute
+ * path relative to `targetDir`, or `null` if the key is unset.
+ */
+export declare function resolveHooksDir(targetDir: string): Promise<{
+    dir: string | null;
+    configured: boolean;
+}>;
+export type InstallDecision = 
+/** Active pre-push already present and governance-carrying. */
+{
+    action: 'skip';
+    reason: 'active-pre-push-present';
+    hookPath: string;
+}
+/** Consumer owns a non-rea pre-push; refusing to stomp it. */
+ | {
+    action: 'skip';
+    reason: 'foreign-pre-push';
+    hookPath: string;
+}
+/** Write a fresh hook. */
+ | {
+    action: 'install';
+    hookPath: string;
+}
+/** Refresh an existing rea-managed hook (marker match). */
+ | {
+    action: 'refresh';
+    hookPath: string;
+};
+/**
+ * Classify what we should do at `targetDir` based on current state. Pure —
+ * reads the filesystem and git config but performs no writes. Split out so
+ * tests can drive every branch without going through the write path.
+ *
+ * NOTE: The result is a snapshot. `installPrePushFallback` re-resolves and
+ * re-classifies immediately before writing to defend against a husky
+ * install or concurrent `rea init` running between classify and write.
+ */
+export declare function classifyPrePushInstall(targetDir: string): Promise<InstallDecision>;
+export interface PrePushInstallResult {
+    decision: InstallDecision;
+    /** Absolute path of the file written, if any. */
+    written?: string;
+    /** User-facing warnings accumulated during install. */
+    warnings: string[];
+}
+export interface WriteExecutableResult {
+    /**
+     * R25 F2 — set to true when the install path had to use a non-atomic
+     * fallback (copyFile after link() refused). Callers surface this as a
+     * warning to the operator so they know publication was best-effort on
+     * this filesystem rather than atomic.
+     */
+    degradedFromAtomic: boolean;
+}
+/**
+ * Options controlling `installPrePushFallback`. Exposed primarily for
+ * tests — production callers get sensible defaults.
+ */
+export interface InstallPrePushOptions {
+    /**
+     * Serialize concurrent installs via an advisory lockfile under `.git/`.
+     * Defaults to `true`. Tests that simulate concurrent races must keep
+     * this on; the only reason to turn it off is unit-testing a specific
+     * write branch in isolation.
+     */
+    useLock?: boolean;
+    /**
+     * Called exactly once inside the advisory lock, after classification
+     * and before re-resolution + write. Test-only seam that lets a race
+     * partner drop a file in between those two steps so we can assert on
+     * the re-check behavior. Invoked with the classified target path.
+     * Production callers never set this.
+     */
+    onBeforeReresolve?: (hookPath: string) => Promise<void> | void;
+    /**
+     * Called inside the lock, after the safety re-check passes but
+     * immediately before `writeExecutable`. Test-only seam: creates a
+     * file at the hook path to exercise the EEXIST-from-link path that
+     * guards the remaining TOCTOU window. Production callers never set this.
+     */
+    onBeforeWrite?: (hookPath: string) => Promise<void> | void;
+}
+/**
+ * Install (or refresh, or skip) the fallback pre-push hook at `targetDir`.
+ * Idempotent: safe to call on every `rea init`, including re-runs over an
+ * existing install. Never overwrites a foreign hook.
+ *
+ * Requires `targetDir/.git` to exist. Non-git directories are skipped with
+ * a warning — same shape as `installCommitMsgHook`.
+ */
+export declare function installPrePushFallback(targetDir: string, options?: InstallPrePushOptions): Promise<PrePushInstallResult>;
+/**
+ * Doctor check: at least one pre-push hook (Husky OR git fallback OR the
+ * configured hooksPath location) must exist AND be executable AND carry
+ * governance (rea marker or gate delegation). Returns a small record the
+ * doctor module can turn into a CheckResult.
+ *
+ * "Executable" is defined as having any of the user/group/other exec bits
+ * set, matching the existing `checkHooksInstalled` convention. A file that
+ * is executable but does not wire the Codex review gate is intentionally
+ * classified as non-governing: `ok=false` + `activeForeign=true`, which
+ * doctor turns into a `warn`, not a `pass`.
+ */
+export interface PrePushDoctorState {
+    /** Every candidate path we consulted, with its live status on disk. */
+    candidates: Array<{
+        path: string;
+        exists: boolean;
+        executable: boolean;
+        /** `true` when the file content carries our anchored rea prelude. */
+        reaManaged: boolean;
+        /** `true` when the body references the shared review gate. */
+        delegatesToGate: boolean;
+    }>;
+    /**
+     * The candidate path git would actually fire right now, given current
+     * `core.hooksPath`. May or may not exist.
+     */
+    activePath: string;
+    /**
+     * True when the active candidate exists, is executable, AND carries
+     * governance (rea marker OR references the review gate).
+     */
+    ok: boolean;
+    /**
+     * True when the active candidate exists + is executable but does NOT
+     * carry governance. This is the "silent bypass" case doctor surfaces as
+     * a warn. Distinct from `ok=false + absent` (which is a hard fail).
+     */
+    activeForeign: boolean;
+}
+export declare function inspectPrePushState(targetDir: string): Promise<PrePushDoctorState>;