@jevitate/cli 0.1.0 → 0.3.0

package/dist/verify-fix-api.d.ts

@@ -0,0 +1,194 @@
+import { type PrefixFromBranchOptions, type RecordedBranch } from "./journey-prefix.js";
+import { type TargetConfig } from "./target-config.js";
+import { type InvariantSpec, type Recording } from "@jevitate/recording";
+import { type FixtureFlags } from "./fixture-cli.js";
+import { type FixtureRecord } from "./mission-fixtures.js";
+import { type BrowserPort, type EmulationSpec } from "@jevitate/playwright";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+import { type HangSignal, type VerifyFixResult, type VerifyFixVerdict } from "@jevitate/explore";
+import { type DefectEvidence } from "./defect-evidence.js";
+import { type ScreenshotsResult, type ScreenshotsSpec } from "./run-screenshots.js";
+/**
+ * The programmatic surface behind `jevitate verify-fix` and the MCP `verify_fix` tool: loads a
+ * finished mission's persisted typed result (`<stem>.result.json`), finds the defect by
+ * fingerprint, and replays its reproduction in a FRESH browser session (`@jevitate/explore`'s
+ * `verifyFix`, which reuses the Recording interpreter). The replay is authorized against the
+ * mission's own allowlist before any browser opens.
+ *
+ * Exit codes: 0 fixed · 1 still reproduces · 2 inconclusive (the replay could not reach the
+ * defect's step, or the input was unusable) · 4 intermittent (the signal fired on some but not
+ * all fresh-context replays — #74; mirrors the mission `intermittent` hang outcome) — a broken or
+ * flaky check never reads as "fixed".
+ */
+export declare const VERIFY_FIX_EXIT_CODES: Readonly<Record<VerifyFixVerdict, number>>;
+export interface RunVerifyFixOptions {
+    /** Path of the mission's `<stem>.result.json`. */
+    readonly resultPath: string;
+    /**
+     * #293: a finding a journey-anchored run found (its result's `branch`) is replayed THROUGH the same
+     * Journey prefix — every replay session replays it first, and the finding's Recording starts on
+     * the live anchor page (its leading navigate becomes an assertion). These are the prefix's secret
+     * `--param`s (never persisted) and the site-policy database / environment seams it runs under.
+     */
+    readonly journeyPrefix?: PrefixFromBranchOptions;
+    /** The defect (or hang) fingerprint to verify. */
+    readonly fingerprint: string;
+    /** Overrides the storageState recorded with the mission (CLI `--storage-state`). */
+    readonly storageState?: string;
+    readonly browserPortFactory?: () => BrowserPort;
+    /** How Chromium is launched and shown (#245: `--headed`/`--slow-mo`/`--record-video`). Default: headless. */
+    readonly browser?: BrowserRunOptions;
+    /** Settle ceiling after the replay (ms). */
+    readonly settleCeilingMs?: number;
+    /** Per-target settle/hang configuration, keyed by origin (`~/.jevitate/targets.json`). */
+    readonly targets?: Readonly<Record<string, TargetConfig>>;
+    /** Fresh-context replays for a non-hang defect signal (#74, CLI `--replays`). Default 3. */
+    readonly replays?: number;
+    /** #303 `--action-deltas`: compare the replayed defect step's delta with the recorded one (evidence). */
+    readonly actionDeltas?: boolean;
+    /**
+     * Invariant files (CLI `--invariants`, #86) to re-check a declared-invariant defect with, instead of
+     * the spec persisted with the mission. Validated against the MISSION's allowlist before any replay.
+     */
+    readonly invariantFiles?: readonly string[];
+    /** Re-checking a `server-log` defect whose sources include a `cmd:` one needs this too (#142). */
+    readonly allowLogCmd?: boolean;
+    /** `--hang-replay-writes` (#153): a hang's replay may re-send a paid/destructive write. */
+    readonly hangReplayWrites?: boolean;
+    /**
+     * Mission fixtures (#140/#144): every replay restores + re-runs the mission's own fixture (saved
+     * with its result) so it starts from the same state. `fixtures` overrides the saved spec; the
+     * mission's shell hooks are never replayed from the file — the operator re-supplies the SAME
+     * `before`/`after` (checked by hash) with `allowShellHooks`.
+     */
+    readonly fixtureFlags?: FixtureFlags;
+    /** Values redacted from everything the fixture logs (CLI `--secret`). */
+    readonly secrets?: readonly string[];
+    /**
+     * Explicit `--viewport` / `--device` override (#149). Defaults to the finding's OWN recorded
+     * emulation (`recording.emulation`) — a 375px defect replays at 375px, not the caller's desktop
+     * default. An override that DIFFERS from the recorded emulation is refused (fails closed) unless
+     * `allowEmulationOverride` is set: replaying at the wrong device could report a false "fixed".
+     */
+    readonly emulation?: EmulationSpec;
+    /** Replay at `emulation` even though it differs from the finding's recorded emulation. */
+    readonly allowEmulationOverride?: boolean;
+    /**
+     * #251 `--screenshots`: masked screenshots of the captioned "after" replay (one per distinct
+     * screen, or per step) + `index.md`.
+     */
+    readonly screenshots?: ScreenshotsSpec;
+    /** #250: caption time per step in the "after" clip (ms). Default `EVIDENCE_PACE_MS`. */
+    readonly evidencePaceMs?: number;
+}
+/**
+ * #250 — `verify-fix --record-video`: a before/after pair for the PR. `before` is the run's own
+ * evidence clip of the defect (`--evidence-video` on the original run), `after` a captioned replay
+ * of the same steps now (still reproducing, or passing), its final card the verdict.
+ */
+export interface VerifyFixEvidence {
+    readonly before?: {
+        readonly videoPath?: string;
+        readonly screenshots: string[];
+    };
+    /** Why there is no `before` (the run recorded no evidence clip for this defect). */
+    readonly beforeMissing?: string;
+    readonly after: DefectEvidence;
+}
+export interface VerifyFixReport extends VerifyFixResult {
+    readonly exitCode: number;
+    /** #293: the Journey step the finding branched from, when its replays went through that prefix. */
+    readonly branch?: RecordedBranch;
+    /** #293: why the replays proved nothing — `journey-stale` when the prefix no longer replays. */
+    readonly failure?: {
+        readonly kind: "journey-stale";
+        readonly message: string;
+    };
+    readonly title?: string;
+    /** The fixture every replay started from (#140/#144): the mission's identity and this run's setup/restore log. */
+    readonly fixtures?: FixtureRecord & {
+        readonly missionIdentity: string;
+    };
+    /** #245: `--record-video` files of every replay session (each closed, so finalized). */
+    readonly videoPaths?: string[];
+    /** #250: with `--record-video` (or `--screenshots`), the before/after evidence pair. */
+    readonly evidence?: VerifyFixEvidence;
+    /** #251: `--screenshots` of the captioned after-replay. */
+    readonly screenshotPaths?: string[];
+    readonly screenshotIndex?: string;
+    readonly screenshotsSkipped?: ScreenshotsResult["screenshotsSkipped"];
+}
+export declare class VerifyFixInputError extends Error {
+    readonly code: "E_VERIFY_FIX_INPUT";
+    constructor(message: string);
+}
+export interface PersistedFinding {
+    readonly fingerprint: string;
+    readonly related?: readonly string[];
+    readonly kind: string;
+    readonly title?: string;
+    readonly repro: {
+        readonly recordingStepIndex: number;
+    };
+    /** For a hang finding: its signal (what the replay must no longer show). */
+    readonly hang?: HangSignal;
+    /** The finding's own Recording (found after a reset / on a coverage path), when it has one. */
+    readonly recording?: Recording;
+    /** How many times the mission's OWN run hit this same finding (its `occurrences`), when recorded. */
+    readonly occurrences?: number;
+    /** For a declared-invariant defect (#86): the invariant id to re-check. */
+    readonly invariantId?: string;
+    /** For a `server-log` defect (#142): what to re-tail and match, from the defect's own `serverLog`. */
+    readonly serverLog?: {
+        readonly sources: readonly string[];
+        readonly matcher: string;
+        readonly normalizedMessage: string;
+        readonly drainMs: number;
+        /** #282: the run's `--log-scope`. */
+        readonly scope?: readonly string[];
+    };
+}
+/** #147: a persisted actor — its name, role and storageState PATH (never its contents). */
+export interface PersistedActor {
+    readonly name: string;
+    readonly storageStatePath: string;
+    readonly role: "primary" | "observer";
+}
+export interface PersistedMission {
+    readonly recording: Recording | null;
+    readonly target: {
+        readonly seedUrl: string;
+        readonly allowlist: string[];
+        readonly storageStatePath?: string;
+        /** #147: the mission's actors (`--actor`), when it had any. */
+        readonly actors?: readonly PersistedActor[];
+    };
+    readonly findings: PersistedFinding[];
+    /** The declared-invariant spec the mission evaluated (#86), when it had one and it still validates. */
+    readonly invariantSpec?: InvariantSpec;
+    /** The mission's fixture (#140/#144): spec (re-validated before use), hook hashes and recorded outputs. */
+    readonly fixtures?: PersistedMissionFixtures;
+}
+interface PersistedMissionFixtures {
+    readonly identity: string;
+    readonly spec?: unknown;
+    readonly hooks: {
+        readonly before?: string;
+        readonly after?: string;
+    };
+    readonly outputs: Readonly<Record<string, string>>;
+    /** #243: the fixture identities the mission's steps authenticated as → storageState paths. */
+    readonly identities?: Readonly<Record<string, string>>;
+}
+/** Parses a persisted mission result, failing closed on anything it cannot trust. */
+export declare function parsePersistedMission(raw: unknown): PersistedMission;
+/**
+ * The one place a mission's findings (declared-invariant defects, hangs, adversarial defects) are
+ * looked up by fingerprint — a fingerprint the CALLER supplied may equal the finding's own, or one
+ * of its `related` fingerprints (the same underlying defect observed at a different point). Shared
+ * by `verify-fix` and `regression capture` (#119/#129): the latter reuses this lookup rather than
+ * re-implementing "is this fingerprint a defect this mission found" itself.
+ */
+export declare function findFinding(mission: PersistedMission, fingerprint: string): PersistedFinding | undefined;
+export declare function runVerifyFix(opts: RunVerifyFixOptions): Promise<VerifyFixReport>;
+export {};