@bookedsolid/rea 0.10.3 → 0.11.0

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

@@ -1,335 +1,210 @@
 /**
- * G6 — Pre-push hook fallback installer.
+ * Pre-push hook installer (0.11.0 stateless push-gate).
  *
- * 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 0.11.0 push-gate is a single 15-line shell stub that delegates to
+ * `rea hook push-gate` — no structural parsing of a bash body, no audit-log
+ * grep, no cache lookup. This module writes that stub into the right
+ * location and refuses to stomp foreign hooks.
  *
- * 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)
  *
- * ## Install policy (decision tree, documented)
+ * 1. `core.hooksPath` unset (vanilla git):
+ *    → Install `.git/hooks/pre-push` (via `git rev-parse --git-path`). The
+ *      `.husky/pre-push` file is shipped by `rea init` as a source-of-truth
+ *      copy but is not consulted by git unless `core.hooksPath=.husky` is
+ *      set.
  *
- * Given a consumer repo, we must decide where (if anywhere) to install a
- * fallback `pre-push`:
+ * 2. `core.hooksPath=.husky` (typical Husky 9 install):
+ *    → Do NOT install the `.git/hooks/pre-push` fallback. `.husky/pre-push`
+ *      is already rea's canonical gate and lives under the canonical copy
+ *      module (see `src/cli/install/copy.ts`). `rea upgrade` refreshes it
+ *      there.
  *
- *   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.
+ * 3. `core.hooksPath` set to anything else, and a foreign pre-push lives
+ *    under it:
+ *    → Leave it alone, warn the operator, let `rea doctor` flag the gap.
  *
- *   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.
+ * 4. `core.hooksPath` set but the target directory has no pre-push:
+ *    → Install the stub there — that's where git will look.
  *
- *   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.
+ * Idempotency: every install writes a stable marker header. Re-running
+ * `rea init` / `rea upgrade` refreshes files carrying the marker and
+ * NEVER overwrites a hook without one. The marker comparison is
+ * anchored at byte 0 (exact line after the shebang), not a substring
+ * match — otherwise a comment or log output that happens to contain
+ * the marker text could cause a foreign hook to be reclassified as
+ * rea-managed and silently stomped.
  *
- *   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.
+ * ## Stub body
  *
- * 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.
+ * The body is 15 lines of POSIX sh:
  *
- * ## Why not just rely on `.husky/pre-push`?
+ *   - If `.rea/HALT` exists, print the reason and exit 1.
+ *   - Otherwise `exec rea hook push-gate`, which runs `codex exec review`
+ *     against the diff and exits 0/1/2 accordingly.
  *
- * 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.
+ * All real work lives in `src/hooks/push-gate/index.ts`. Keeping the
+ * shell body minimal means the only things that could regress are HALT
+ * detection and the exec path — both trivially testable.
  */
 /**
- * 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.
+ * Marker baked into every rea-installed fallback pre-push hook. Anchored on
+ * the second line of the file (immediately after the shebang) for
+ * classification. Bump the version suffix whenever the body semantics
+ * change so upgrades can migrate old installs cleanly.
  *
- * 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.
+ * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
+ * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v1";
+export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v2";
+/** Legacy v1 marker — used by upgrade migration to detect old installs. */
+export declare const LEGACY_FALLBACK_MARKER_V1 = "# 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.
+ * Marker present in the shipped `.husky/pre-push` governance gate. The
+ * second line of the shipped husky hook is this marker — rea upgrade
+ * detects it to refresh in-place. Bump the suffix whenever the body
+ * changes; pre-0.11 markers live in `LEGACY_HUSKY_GATE_MARKER_V1`.
  */
-export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v1";
+export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v2";
+/** Legacy v1 husky marker for migration. */
+export declare const LEGACY_HUSKY_GATE_MARKER_V1 = "# 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.
+ * Body-level marker so a hook that carries the header marker but has an
+ * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
+ * A real rea hook always carries both markers.
  */
-export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v1";
+export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v2";
+/** Legacy body marker — used by upgrade migration detection. */
+export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V1 = "# rea:gate-body-v1";
+/** Fallback hook body — `.git/hooks/pre-push` in vanilla-git installs. */
+export declare function fallbackHookContent(): string;
+/** Husky hook body — `.husky/pre-push` when hooksPath=.husky. */
+export declare function huskyHookContent(): string;
 /**
- * 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`.
+ * True when `content` starts with the exact rea fallback prelude (shebang
+ * + v2 marker). Strict: the marker must be on line 2, nothing interposed,
+ * no leading whitespace. Substring matches are deliberately rejected.
  */
 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`.
+ * True when `content` is the legacy v1 fallback (`.git/hooks/pre-push`
+ * that delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea
+ * upgrade` to migrate — we overwrite these unconditionally because we
+ * control the entire body shape.
+ */
+export declare function isLegacyReaManagedFallback(content: string): boolean;
+/**
+ * True when `content` carries the rea Husky gate markers in the canonical
+ * positions — shebang on line 1, `HUSKY_GATE_MARKER` on line 2,
+ * `HUSKY_GATE_BODY_MARKER` on line 3.
+ *
+ * Why three anchored lines instead of a substring search: the 0.10.x
+ * implementation lived in ~2000 lines of structural parser because the old
+ * body varied. The 0.11.0 body is hand-templated and stable — anchored
+ * matching on three fixed lines closes the classification question with
+ * six comparisons.
  */
 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.
+ * True when `content` is the legacy v1 Husky gate (`.husky/pre-push` from
+ * 0.10.x and earlier). Used to trigger the upgrade migration.
  */
 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.
+ * True when `content` looks like a user-authored pre-push that still
+ * invokes `rea hook push-gate` (a legitimate governance-carrying custom
+ * hook). We don't attempt to parse control flow — the 0.10.x attempt at
+ * that produced 800 lines of heuristics that still had gaps. Instead, we
+ * match only on the substring `rea hook push-gate` preceded by one of
+ * `exec`, `$(`, \``, `;`, or line-start whitespace. A comment containing
+ * the phrase does NOT qualify (leading `#`).
+ *
+ * Governance-carrying is a soft signal: `rea doctor` uses it to print
+ * "external (delegates to rea hook push-gate)" rather than "foreign".
+ * `classifyPrePushInstall` maps it to "skip / active-pre-push-present"
+ * — we don't overwrite consumer-authored hooks that respect the gate.
  */
 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. */
-{
+export type ClassifyExistingHook = {
+    kind: 'absent';
+} | {
+    kind: 'rea-managed';
+} | {
+    kind: 'rea-managed-legacy-v1';
+} | {
+    kind: 'rea-managed-husky';
+} | {
+    kind: 'rea-managed-husky-legacy-v1';
+} | {
+    kind: 'gate-delegating';
+} | {
+    kind: 'foreign';
+    reason: string;
+};
+export declare function classifyExistingHook(hookPath: string): Promise<ClassifyExistingHook>;
+export type InstallDecision = {
     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;
+export interface InstallPrePushFallbackOptions {
+    targetDir: string;
 }
 /**
- * Options controlling `installPrePushFallback`. Exposed primarily for
- * tests — production callers get sensible defaults.
+ * Install (or refresh) the `.git/hooks/pre-push` stub when there is no
+ * active governance-carrying hook. Never overwrites foreign hooks.
+ *
+ * Concurrency: a proper-lockfile-based advisory lock on the git common-dir
+ * serializes concurrent installs (two `rea init` runs in the same repo).
+ * Atomicity: fresh installs use `link(2)` (atomic create-or-fail); refresh
+ * uses `rename(2)` with a dev+ino+mtime guard against mid-write
+ * replacement.
  */
-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;
+export declare function installPrePushFallback(options: InstallPrePushFallbackOptions): Promise<PrePushInstallResult>;
+export interface PrePushCandidate {
+    path: string;
+    exists: boolean;
+    executable: boolean;
+    /** The marker classification of the file (if it exists). */
+    kind?: ClassifyExistingHook['kind'];
+    /** True when a rea-authored marker is present. */
+    reaManaged?: boolean;
+    /** True when the body contains `rea hook push-gate`. */
+    delegatesToGate?: boolean;
 }
-/**
- * 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;
+    activePath: string | null;
     /**
-     * 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).
+     * Foreign file detected at the active path — present + executable but
+     * neither rea-managed nor gate-delegating. Treated as a hard fail
+     * (silent-bypass risk).
      */
     activeForeign: boolean;
+    candidates: PrePushCandidate[];
 }
+/**
+ * Read-only probe used by `rea doctor`. Inspects every plausible hook
+ * location and reports whether governance is active.
+ */
 export declare function inspectPrePushState(targetDir: string): Promise<PrePushDoctorState>;