aztrx-cli 0.4.4 → 0.5.1

package/dist/core/specCompiler.d.ts

@@ -0,0 +1,17 @@
+import type { Finding, RecordedAction } from "./types.js";
+/**
+ * F8 — spec compiler. Turns a minimal action sequence into an executable
+ * Playwright test that asserts the failure actually happens, so a human can
+ * run `npx playwright test` and see the bug with their own eyes — proof, not
+ * a log line.
+ */
+export declare function compileSpec(finding: Finding, actions: RecordedAction[], url: string): string;
+export declare function writeSpec(repoRoot: string, finding: Finding, actions: RecordedAction[], url: string): string;
+/**
+ * Install validated repro specs into the project's test directory so a fixed
+ * bug can't silently regress — the "immunity" step after find → prove → fix.
+ * Copies each deterministic/flaky repro into `<dir>/aztrx-<fingerprint>.spec.ts`
+ * and returns the written paths. `dir` defaults to an existing test dir, else a
+ * gitignored fallback.
+ */
+export declare function writeRegressionSpecs(repoRoot: string, findings: Finding[], dir?: string): string[];

package/dist/core/studio.d.ts

@@ -0,0 +1,6 @@
+import * as http from "http";
+export interface StudioOptions {
+    repoRoot: string;
+    port?: number;
+}
+export declare function startStudio(opts: StudioOptions): http.Server;

package/dist/core/studio.js

@@ -3,9 +3,6 @@ import * as http from "http";
 import * as path from "path";
 import pc from "picocolors";
 import { BASE_CSS, SEVERITY_COLOR, seismograph } from "./ui.js";
-function escapeHtml(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
 function send(res, status, contentType, body) {
     res.writeHead(status, { "Content-Type": contentType });
     res.end(body);

package/dist/core/summarize.d.ts

@@ -0,0 +1,26 @@
+/**
+ * F13 — the "X-ray report": a plain-language summary of a run's findings,
+ * instead of a wall of stack traces. Two engines behind one entry point:
+ *
+ *   - LLM (Anthropic Messages API) when `ANTHROPIC_API_KEY` is set — friendly
+ *     prose in the requested language, mirroring the transport in `heal/llm.ts`.
+ *   - deterministic template when there is no key (or the call fails) — a
+ *     readable, structured list that needs no network.
+ *
+ * An empty run short-circuits to the template (no reason to pay for "all clear").
+ * The offer-to-apply line is emitted only when verified fixes are actually ready,
+ * so `--explain` (no healing) never promises a fix it doesn't have.
+ */
+import type { Finding } from "./types.js";
+export type Lang = "en" | "ru";
+/** Deterministic, offline summary. Used as the no-key fallback and for empty runs. */
+export declare function summarizeFindingsTemplate(findings: Finding[], lang?: Lang): string;
+export interface SummarizeOptions {
+    lang?: string;
+}
+/**
+ * Entry point. Empty run → template (no API cost). Otherwise LLM when a key is
+ * present; falls back to the deterministic template on any transport failure, so
+ * the report never crashes the run.
+ */
+export declare function summarizeFindings(findings: Finding[], opts?: SummarizeOptions): Promise<string>;

package/dist/core/swarm.d.ts

@@ -0,0 +1,97 @@
+/**
+ * F-swarm — parallel detection. Runs N workers at once, each with its own
+ * browser context, event bus, action recorder, and classifier, so the action
+ * history attached to a finding belongs to the worker that saw it (never
+ * interleaved). Workers attack different sides: a deterministic walk, several
+ * chaos-fuzz seeds, and — optionally — the server-side HTTP fuzzer.
+ *
+ * Findings are merged by fingerprint at the end (occurrences summed, the richest
+ * action history / source mapping kept); the caller then runs repro/heal on the
+ * merged set as usual.
+ */
+import type { Browser } from "playwright";
+import { EventBus } from "./eventBus.js";
+import type { Finding } from "./types.js";
+export type WorkerStrategy = {
+    kind: "walk";
+} | {
+    kind: "fuzz";
+    seed: number;
+};
+export interface DetectResult {
+    findings: Finding[];
+    actions: number;
+    /** New JS code ranges covered by this worker's fuzz pass (0 for walk). */
+    newCoverage: number;
+    /** Whether the walk encountered a login form (a password input). */
+    sawLoginForm: boolean;
+    /** Auth-state path saved by worker 0 (used to authenticate replays). */
+    replayStorageState?: string;
+}
+export interface DetectWorkerOptions {
+    url: string;
+    repoRoot: string;
+    allowHosts: Set<string>;
+    maxActions: number;
+    dryRun?: boolean;
+    guardOn: boolean;
+    storageState?: string;
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    loginUrl?: string;
+    crashTest?: boolean;
+    saveAuthState?: boolean;
+    httpFuzzMutations?: boolean;
+    /** Fold the HTTP fuzzer in as a post-pass on this worker's page. */
+    httpFuzz?: boolean;
+    /** Opt-in: include destructive controls/endpoints (delete/pay/logout/…). */
+    allowDestructive?: boolean;
+    baseline: string[];
+    log: (msg: string) => void;
+}
+/**
+ * Run one worker's detection pass and return its findings. All internal events
+ * flow through a local bus (isolation); only `action`/`route`/`noise` are
+ * forwarded to `forwardBus` so a live panel can aggregate, never per-worker
+ * findings (those are merged by the caller first).
+ */
+export declare function detectWorker(browser: Browser, opts: DetectWorkerOptions, strategy: WorkerStrategy, forwardBus?: EventBus): Promise<DetectResult>;
+/** Dedup findings across workers by fingerprint: sum occurrences, keep the richest. */
+export declare function mergeFindings(arrays: Finding[][]): Finding[];
+export interface SwarmOptions {
+    url: string;
+    repoRoot: string;
+    maxActions: number;
+    dryRun?: boolean;
+    fuzz?: boolean;
+    httpFuzz?: boolean;
+    httpFuzzMutations?: boolean;
+    seed: number;
+    workers: number;
+    allowHosts: Set<string>;
+    storageState?: string;
+    login?: boolean;
+    loginEmail?: string;
+    loginPassword?: string;
+    loginUrl?: string;
+    crashTest?: boolean;
+    /** Opt-in: include destructive controls/endpoints (delete/pay/logout/…). */
+    allowDestructive?: boolean;
+    baseline: string[];
+    guardOn: boolean;
+    log: (msg: string) => void;
+    /** Forwarded to the orchestrator's bus so a live panel can aggregate action/route counts. */
+    forwardBus?: EventBus;
+}
+export interface SwarmResult {
+    findings: Finding[];
+    replayStorageState?: string;
+    totalActions: number;
+    totalCoverage: number;
+    workerCount: number;
+    roles: string[];
+    sawLoginForm: boolean;
+}
+/** Launch one browser, run the worker roster concurrently, merge findings. */
+export declare function swarmDetect(opts: SwarmOptions): Promise<SwarmResult>;

package/dist/core/telemetry/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * F11 — opt-in telemetry / data flywheel. Collects the anonymized
+ * `[crash_fingerprint, min_repro_spec, verified_patch, framework_metadata,
+ * model_tier_used]` tuple for each crash/error finding, appends it to a local
+ * JSONL dataset, and — only under `--share-data` — dispatches an envelope to the
+ * telemetry endpoint.
+ *
+ * Privacy: everything is opt-in. `--telemetry` collects and persists locally
+ * only; `--share-data` additionally uploads. The dispatch is fire-and-forget,
+ * bounded by a 2s abort, and can never change the CLI exit code.
+ */
+import type { Finding } from "../types.js";
+import type { TelemetryEnvelope } from "./types.js";
+export interface SubmitOptions {
+    repoRoot: string;
+    url: string;
+    telemetry: boolean;
+    shareData: boolean;
+    endpoint?: string;
+    /** API key presented as `x-api-key` (falls back to `AZTRX_CLOUD_API_KEY`).
+     *  Deliberately not `AZTRX_API_KEY` — that one is a model provider credential
+     *  (`llm.ts:29,35`) and must never travel as an upload auth header. */
+    apiKey?: string;
+}
+/** Fire-and-forget upload. Never rejects; bounded by a short abort. Failures are
+ * reported on stderr rather than discarded — silence here reads as success. */
+export declare function dispatchTelemetry(envelope: TelemetryEnvelope, endpoint: string, apiKey?: string): Promise<void>;
+/** Collect + sanitize + persist, and (under `--share-data`) dispatch. Sync on
+ * the local path; the upload is detached so the run never waits on the network. */
+export declare function submitTelemetry(findings: Finding[], opts: SubmitOptions): void;
+/** Await all in-flight uploads (each already bounded). Called right before the
+ * CLI exits so a pending upload isn't killed mid-flight; never affects exit code. */
+export declare function flushTelemetry(): Promise<void>;

package/dist/core/telemetry/index.js

@@ -11,10 +11,15 @@
  */
 import * as fs from "fs";
 import * as path from "path";
+import pc from "picocolors";
 import { detectFrameworkMeta } from "../init.js";
 import { createSanitizer } from "./sanitize.js";
 const DEFAULT_ENDPOINT = process.env.AZTRX_TELEMETRY_URL || "https://api.aztrx.app/api/telemetry";
 const UPLOAD_TIMEOUT_MS = 2000;
+/** One dim line on stderr — the only place a detached upload can report. */
+function warn(msg) {
+    process.stderr.write(pc.dim(`aztrx: ${msg}\n`));
+}
 /** In-flight uploads, drained by `flushTelemetry()` before the CLI exits. */
 const pendingUploads = [];
 function readFileIfExists(p) {
@@ -56,7 +61,8 @@ function persistDataset(repoRoot, tuples) {
     fs.appendFileSync(file, lines, "utf-8");
     return file;
 }
-/** Fire-and-forget upload. Never rejects; bounded by a short abort. */
+/** Fire-and-forget upload. Never rejects; bounded by a short abort. Failures are
+ * reported on stderr rather than discarded — silence here reads as success. */
 export function dispatchTelemetry(envelope, endpoint, apiKey) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), UPLOAD_TIMEOUT_MS);
@@ -69,8 +75,20 @@ export function dispatchTelemetry(envelope, endpoint, apiKey) {
         body: JSON.stringify(envelope),
         signal: ctrl.signal,
     })
-        .then(() => { })
-        .catch(() => { })
+        .then((res) => {
+        // `fetch` resolves on 4xx/5xx too — without this check a rejected upload
+        // is indistinguishable from a delivered one.
+        if (!res.ok)
+            warn(`telemetry upload rejected — HTTP ${res.status} from ${endpoint}`);
+    })
+        .catch((e) => {
+        const why = e instanceof Error && e.name === "AbortError"
+            ? `no response within ${UPLOAD_TIMEOUT_MS}ms`
+            : e instanceof Error
+                ? e.message
+                : String(e);
+        warn(`telemetry upload failed — ${why}`);
+    })
         .finally(() => clearTimeout(timer));
 }
 /** Collect + sanitize + persist, and (under `--share-data`) dispatch. Sync on
@@ -89,7 +107,7 @@ export function submitTelemetry(findings, opts) {
             sentAt: new Date().toISOString(),
             tuples,
         };
-        const apiKey = opts.apiKey ?? process.env.AZTRX_API_KEY;
+        const apiKey = opts.apiKey ?? process.env.AZTRX_CLOUD_API_KEY;
         pendingUploads.push(dispatchTelemetry(envelope, opts.endpoint ?? DEFAULT_ENDPOINT, apiKey));
     }
 }

package/dist/core/telemetry/sanitize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Telemetry sanitizer — the privacy gate before any byte is packaged. A strict
+ * superset of the heal redaction layer, applied irreversibly: secrets first
+ * (the redaction map is discarded), then URLs, webpack namespaces, and
+ * repo-absolute paths. The output must be safe to leave the machine even if the
+ * user's app, routes, and file layout are proprietary.
+ */
+/**
+ * Anonymize a single URL: strip query/fragment/userinfo; keep only a localhost
+ * authority (already anonymous) or a literal `<host>` placeholder. The route
+ * path is kept — it's structural, not identifying.
+ */
+export declare function sanitizeUrl(raw: string): string;
+export interface Sanitizer {
+    url: (raw: string) => string;
+    text: (raw: string) => string;
+}
+/** Bound to a repo root so repo-absolute paths and the repo name can be scrubbed. */
+export declare function createSanitizer(repoRoot: string): Sanitizer;

package/dist/core/telemetry/types.d.ts

@@ -0,0 +1,26 @@
+/** Telemetry payload schema — the data-flywheel columnar tuple. Flat on purpose
+ * so a record can be appended to a JSONL dataset as-is and loaded into any
+ * columnar store later. Everything in here has already passed the sanitizer. */
+export interface FrameworkMetadata {
+    /** Detected framework name, e.g. "Next.js", "Vite", "unknown". */
+    framework: string;
+    /** The installed version range from package.json, e.g. "^16.3.2". */
+    version?: string;
+}
+export interface TelemetryTuple {
+    /** Stable stack fingerprint — already a hash, carries no source text. */
+    crash_fingerprint: string;
+    /** Sanitized minimized Playwright spec (repro steps), or null if none. */
+    min_repro_spec: string | null;
+    /** Sanitized verified patch diff, or null if healing didn't produce a fix. */
+    verified_patch: string | null;
+    framework_metadata: FrameworkMetadata;
+    /** The model tier that produced the winning patch, or null. */
+    model_tier_used: string | null;
+}
+export interface TelemetryEnvelope {
+    schema: "aztrx.telemetry/1";
+    /** ISO timestamp. */
+    sentAt: string;
+    tuples: TelemetryTuple[];
+}

package/dist/core/types.d.ts

@@ -0,0 +1,88 @@
+export type Severity = "crash" | "error" | "warning" | "noise";
+export type FindingType = "uncaught_exception" | "unhandled_rejection" | "console_error" | "network_5xx" | "network_timeout";
+/** A server-side source location, e.g. a stack frame from a 500 response body. */
+export interface ServerFrame {
+    /** Raw path string as it appeared in the stack (file:// URL, POSIX, or Windows). */
+    filePath: string;
+    line: number;
+    column: number;
+}
+/** Server-side error captured from a 500 response body by the HTTP fuzzer. */
+export interface ServerErrorInfo {
+    /** The server's own error message, best-effort extracted from the body. */
+    message: string;
+    /** Truncated response body. */
+    body: string;
+    /** Best-effort source location parsed from a stack trace in the body. */
+    frame?: ServerFrame;
+}
+export interface TelemetryErrorPayload {
+    type: FindingType;
+    rawMessage: string;
+    rawStack: string;
+    url?: string;
+    line?: number;
+    column?: number;
+    /** Server-side error context (F5-http). Present only for network findings. */
+    serverError?: ServerErrorInfo;
+}
+export type ActionType = "click" | "input" | "navigate" | "hover" | "keypress" | "select" | "scroll" | "request";
+/** A raw HTTP request synthesized by the HTTP mutation fuzzer (F5-http). */
+export interface HttpRequestAction {
+    method: string;
+    /** Absolute URL — matches the interceptor's `res.url()` so fingerprints line up. */
+    url: string;
+    headers?: Record<string, string>;
+    /** Already-serialized body (JSON string, form-encoded, etc.). */
+    body?: string;
+}
+export interface RecordedAction {
+    type: ActionType;
+    /** Selector cascade, most-reliable first: data-testid → text → css path. */
+    selectors: string[];
+    value?: string;
+    timestamp: number;
+    postState?: {
+        url: string;
+    };
+    /** Present when `type === "request"` — the hostile HTTP request to replay. */
+    request?: HttpRequestAction;
+}
+export interface MappedLocation {
+    filePath: string;
+    line: number;
+    column: number;
+    codeContext: string;
+    isOwnCode: boolean;
+}
+export type ReproVerdict = "deterministic" | "flaky" | "unreliable";
+export interface ReproReport {
+    actions: RecordedAction[];
+    specPath: string;
+    verdict: ReproVerdict;
+    rate: number;
+    runs: number;
+    reproductions: number;
+}
+export interface Finding {
+    id: string;
+    fingerprint: string;
+    /** Cross-signal root-cause key (see `rootKeyOf` in classifier.ts). Grouped by
+     * `collapseSignals` so distinct capture paths of one fault merge into one. */
+    rootKey?: string;
+    occurrences: number;
+    severity: Severity;
+    type: FindingType;
+    rawMessage: string;
+    rawStack: string;
+    mappedLocation?: MappedLocation;
+    /** Server's own error response, captured by `--http-fuzz` (message + body). */
+    serverError?: {
+        message: string;
+        body: string;
+    };
+    actionHistory: RecordedAction[];
+    repro?: ReproReport;
+    /** F10 closed-loop healing result, attached when `--heal` ran for this finding. */
+    heal?: import("./heal/types.js").HealResult;
+}

package/dist/core/ui.d.ts

@@ -0,0 +1,23 @@
+import type { Severity } from "./types.js";
+export declare const PALETTE: {
+    readonly bg: "#07090d";
+    readonly surface: "#0d1117";
+    readonly surface2: "#12161e";
+    readonly border: "#232a36";
+    readonly fg: "#e9edf4";
+    readonly muted: "#a6aebb";
+    readonly dim: "#5b6573";
+    readonly azure: "#4cc2ff";
+    readonly azureBright: "#8ad9ff";
+    readonly red: "#ff5a5f";
+    readonly amber: "#f5a623";
+    readonly green: "#43e58a";
+};
+export declare const SEVERITY_COLOR: Record<Severity, string>;
+export declare const BASE_CSS = "\n:root{color-scheme:dark;--bg:#07090d;--surface:#0d1117;--surface-2:#12161e;--border:#232a36;--fg:#e9edf4;--muted:#a6aebb;--dim:#5b6573;--azure:#4cc2ff;--azure-bright:#8ad9ff;--red:#ff5a5f;--amber:#f5a623;--green:#43e58a}\n*{box-sizing:border-box}\nbody{margin:0;background:var(--bg);color:var(--fg);font:14px/1.65 ui-monospace,\"SF Mono\",SFMono-Regular,Menlo,Consolas,\"Liberation Mono\",monospace;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;background-image:linear-gradient(rgba(76,194,255,.035) 1px,transparent 1px),linear-gradient(90deg,rgba(76,194,255,.035) 1px,transparent 1px);background-size:44px 44px}\nmain{max-width:920px;margin:0 auto;padding:40px 24px 80px}\n.hero{margin-bottom:26px}\n.hero svg{width:100%;height:64px;display:block}\n.brand-row{display:flex;align-items:baseline;gap:10px;flex-wrap:wrap;margin-top:16px}\nh1{margin:0;font-size:20px;font-weight:700;letter-spacing:.02em}\nh1 .brand{color:var(--azure)}\nh1 .brand-sub{color:var(--dim)}\n.target{color:var(--dim);font-size:13px;margin-top:4px;word-break:break-all}\n.live{display:inline-flex;align-items:center;gap:7px;font-size:12px;color:var(--muted);margin-top:6px}\n.live-dot{width:8px;height:8px;border-radius:50%;background:var(--green);box-shadow:0 0 8px var(--green);animation:pulse 1.8s ease-in-out infinite}\n@keyframes pulse{0%,100%{opacity:1}50%{opacity:.25}}\n.bar{display:flex;gap:10px;margin:0 0 24px;flex-wrap:wrap}\n.count{font:600 13px/1 ui-monospace,monospace;border:1px solid var(--border);border-radius:8px;padding:7px 12px;color:var(--dim);background:var(--surface)}\n.count b{color:var(--fg);font-weight:600}\n.count b.crash{color:var(--red)}\n.count b.error{color:var(--red)}\n.count b.warning{color:var(--amber)}\n.finding{background:var(--surface);border:1px solid var(--border);border-left:3px solid var(--sev,var(--azure));border-radius:10px;padding:16px 18px;margin-bottom:14px;animation:line-in .35s ease both}\n.finding header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}\n.sev{font:600 11px/1 ui-monospace,monospace;text-transform:uppercase;letter-spacing:.08em;color:var(--sev);border:1px solid var(--sev);border-radius:999px;padding:3px 9px;flex:none}\nh2{font-size:15px;margin:0;font-weight:600;word-break:break-word}\n.loc{color:var(--dim);font-size:12.5px;margin-top:8px}\n.dx{color:var(--azure);font-size:12.5px;margin-top:6px}\n.snippet{background:var(--surface-2);border:1px solid var(--border);border-radius:8px;padding:12px 14px;overflow-x:auto;font:12px/1.6 ui-monospace,monospace;color:var(--muted);margin:12px 0 0;white-space:pre}\n.server{color:var(--amber);font-size:12.5px;margin-top:8px}\n.server-body{background:var(--surface-2);border:1px solid var(--border);border-radius:8px;padding:12px 14px;overflow-x:auto;font:12px/1.6 ui-monospace,monospace;color:var(--muted);margin:8px 0 0;white-space:pre;max-height:240px;overflow-y:auto}\n.occ{color:var(--dim);font-size:12px;margin-top:8px}\n.repro{display:inline-flex;align-items:center;gap:8px;font-size:12px;margin-top:12px;padding:4px 10px;border-radius:6px;border:1px solid}\n.repro.deterministic{color:var(--green);border-color:rgba(67,229,138,.35);background:rgba(67,229,138,.07)}\n.repro.flaky{color:var(--amber);border-color:rgba(245,166,35,.35);background:rgba(245,166,35,.07)}\n.repro.unreliable{color:var(--red);border-color:rgba(255,90,95,.35);background:rgba(255,90,95,.07)}\ndetails{margin-top:12px;color:var(--dim);font-size:12.5px;border-top:1px solid var(--border);padding-top:10px}\nsummary{cursor:pointer;color:var(--muted)}\ndetails ol{margin:8px 0 0;padding-left:22px;display:flex;flex-direction:column;gap:4px}\ndetails code{color:var(--fg)}\n.empty{color:var(--dim);border:1px dashed var(--border);border-radius:10px;padding:24px;text-align:center}\n.foot{color:var(--dim);font-size:12.5px;margin-top:24px}\na{color:var(--azure)}\n@keyframes line-in{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}\n";
+/**
+ * The crash seismograph: an azure trace with one red spike per crash. The
+ * spikes live inside `<g id="spikes">` so the Studio can append them live as
+ * crashes stream in; the report pre-fills them.
+ */
+export declare function seismograph(crashes: number): string;

package/dist/core/ui.js

@@ -21,11 +21,6 @@ export const SEVERITY_COLOR = {
     warning: PALETTE.amber,
     noise: PALETTE.dim,
 };
-export const REPRO_COLOR = {
-    deterministic: PALETTE.green,
-    flaky: PALETTE.amber,
-    unreliable: PALETTE.red,
-};
 export const BASE_CSS = `
 :root{color-scheme:dark;--bg:#07090d;--surface:#0d1117;--surface-2:#12161e;--border:#232a36;--fg:#e9edf4;--muted:#a6aebb;--dim:#5b6573;--azure:#4cc2ff;--azure-bright:#8ad9ff;--red:#ff5a5f;--amber:#f5a623;--green:#43e58a}
 *{box-sizing:border-box}

package/dist/core/validator.d.ts

@@ -0,0 +1,14 @@
+import type { Finding, RecordedAction, ReproVerdict } from "./types.js";
+import type { ReplayEngine } from "./replay.js";
+export interface ValidateResult {
+    runs: number;
+    reproductions: number;
+    rate: number;
+    verdict: ReproVerdict;
+}
+/**
+ * F9 — repro validator. Replays the minimized sequence `runs` times and gates
+ * on the flake rate: 100% → deterministic, ≥60% → flaky, else unreliable. This
+ * is the difference between "we saw an error" and "we proved the bug".
+ */
+export declare function validate(engine: ReplayEngine, url: string, finding: Finding, actions: RecordedAction[], runs?: number): Promise<ValidateResult>;

package/dist/core/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/hooks/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Git hook integration — `aztrx-cli hook install | uninstall | run pre-push`.
+ *
+ * The file that lands in `.git/hooks/` is a short POSIX shim that calls back
+ * into the CLI. That split is the design, not a shortcut: a hook carrying its
+ * own implementation has to be *reinstalled* to be fixed, and by the time the
+ * bug matters the user has already deleted the thing. Here, upgrading
+ * `aztrx-cli` upgrades the hook.
+ *
+ * Everything below is **fail-open**. A missing tool, a shallow clone with no
+ * base to diff against, a scan that could not run — none of those are reasons to
+ * block someone's push. Only a crash we actually found is. A hook that blocks
+ * pushes when it is merely broken gets turned off, and then it catches nothing.
+ */
+/** The line that marks a hook file as ours. Used to decide whether installing
+ * is safe (never clobber a hook somebody else wrote) and whether uninstalling
+ * would delete something we own. */
+export declare const HOOK_MARKER = "aztrx-cli hook run pre-push";
+/** The shim that lands in `.git/hooks/pre-push`.
+ *
+ * Built as an array of lines joined with `\n` rather than one multi-line
+ * template literal, and that is load-bearing: a literal's line breaks are the
+ * *source file's* line breaks, so on a checkout with `core.autocrlf=true` this
+ * would come out CRLF — and `sh` reads `#!/bin/sh\r` as an interpreter named
+ * `/bin/sh\r`, which is not a thing. The hook would fail with "bad
+ * interpreter", on Windows only, for reasons invisible in the source. */
+export declare function hookScript(): string;
+export interface PushRef {
+    localRef: string;
+    localSha: string;
+    remoteRef: string;
+    remoteSha: string;
+}
+/** git hands a pre-push hook one line per ref on stdin:
+ * `<local ref> <local sha> <remote ref> <remote sha>`. An all-zero sha means
+ * "does not exist on that side". Malformed rows are dropped rather than
+ * guessed at — a ref we cannot read is a ref we must not silently skip. */
+export declare function parsePushLines(stdin: string): PushRef[];
+/** Deleting a remote branch pushes no code. */
+export declare function isBranchDelete(ref: PushRef): boolean;
+/** A branch the remote has never seen. There is no base to diff against, so
+ * what is new cannot be known — the conservative answer is "all of it". */
+export declare function isNewBranch(ref: PushRef): boolean;
+export interface PushAnalysis {
+    /** Files the push touches, relative to the repo root. `null` when that cannot
+     * be known — nothing on stdin, a new branch, a base missing from a shallow
+     * clone — which means scan. */
+    changed: string[] | null;
+    /** Refs that actually carry code. Empty means deletions only. */
+    liveRefs: PushRef[];
+    /** Why `changed` is unknown, phrased for the user. Empty when it is known.
+     * Three different situations land on `null`, and one message covering all of
+     * them sent me hunting for a shallow clone that was not there — the actual
+     * cause was a wrapper script that had drained stdin. */
+    blind: string;
+}
+/** What is this push bringing? Pure but for the injected `diff`, so the branches
+ * that are awkward to arrange in a real repo (shallow clone, new branch) are
+ * cheap to test. */
+export declare function analyzePush(refs: PushRef[], diff: (base: string, head: string) => string[] | null): PushAnalysis;
+/** Could this file change the app's runtime behaviour? */
+export declare function isAppCode(file: string): boolean;
+export interface PushDecision {
+    scan: boolean;
+    /** One line for the user explaining the call. */
+    reason: string;
+}
+export declare function decidePush(analysis: PushAnalysis, always: boolean): PushDecision;
+/** `git rev-parse --git-path hooks` resolves the hooks directory the way git
+ * itself will — through `.git` being a file in a worktree, and through
+ * `core.hooksPath` (husky sets it). Installing into `.git/hooks` while
+ * `core.hooksPath` points somewhere else produces a hook git never runs, which
+ * is the worst possible outcome: the user believes they are covered. */
+export declare function hooksDir(repoRoot: string): string | null;
+/** Which files a range touches, or null when git cannot answer. */
+export declare function diffNames(repoRoot: string, base: string, head: string): string[] | null;
+export type HookAction = "installed" | "updated" | "unchanged" | "refused" | "removed" | "absent";
+export interface HookResult {
+    ok: boolean;
+    action: HookAction;
+    hookPath?: string;
+    message: string;
+}
+/** Is this file a shim we wrote (as opposed to a hook the project already had)? */
+export declare function isOurs(hookPath: string): boolean;
+export declare function installHook(repoRoot: string, force?: boolean): HookResult;
+export declare function uninstallHook(repoRoot: string): HookResult;
+export interface PrePushOptions {
+    repoRoot: string;
+    /** Raw hook stdin. Read from fd 0 when omitted. */
+    stdin?: string;
+    /** Scan even when nothing app-shaped changed (`--always`). */
+    always?: boolean;
+    /** Called once, just before the scan starts. The scan itself is silent until
+     * it has a result (that is what `--json` means), so without this the push
+     * would look hung for the better part of a minute. */
+    onProgress?: (message: string) => void;
+}
+export interface PrePushOutcome {
+    /** Exit code for the hook process. Non-zero blocks the push. */
+    code: number;
+    /** Everything to show the user, in order. */
+    lines: string[];
+}
+/** `aztrx-cli hook run pre-push` — the body of the shim. */
+export declare function runPrePush(opts: PrePushOptions): Promise<PrePushOutcome>;