prowl-tools 0.1.3

package/dist/lib.d.ts

@@ -0,0 +1,935 @@
+import { Page } from 'playwright';
+import { z } from 'zod';
+
+type BrowserEngine = "chromium" | "firefox" | "webkit";
+type BrowserChannel = "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev";
+type Viewport = {
+    width: number;
+    height: number;
+};
+type Config = {
+    target: {
+        url: string;
+    };
+    browser: {
+        headless: boolean;
+        slowMo: number;
+        timeout: number;
+        engine: BrowserEngine;
+        channel?: BrowserChannel;
+        viewport: Viewport;
+    };
+    artifacts: {
+        screenshots: "on-failure" | "all";
+        networkHar: boolean;
+        console: boolean;
+        junit: boolean;
+    };
+    assertions: {
+        noConsoleErrors: boolean;
+        noNetworkErrors: boolean;
+        maxTotalTimeMs: number;
+        networkIgnorePatterns: string[];
+    };
+    guardrails: {
+        maxSteps: number;
+        allowedDomains: string[];
+        forbiddenSelectors: string[];
+        selfHealing: boolean;
+    };
+    auth: {
+        storageStatePath?: string;
+    };
+    history: {
+        maxRuns: number;
+    };
+    bugLog?: BugLogConfig;
+    tracing?: TracingConfig;
+    reliability?: ReliabilityConfig;
+};
+type ReliabilityConfig = {
+    /** Flake score (0-1) at or above which a hunt is flagged flaky (default 0.3). */
+    flakyThreshold?: number;
+};
+type TracingConfig = {
+    /** Response header carrying the distributed-trace id (default "traceparent"). */
+    header?: string;
+};
+type BugLogConfig = {
+    enabled?: boolean;
+    backlogPath?: string;
+    resolvedPath?: string;
+};
+type HistoryEntry = {
+    hunt: string;
+    status: "pass" | "fail";
+    durationMs: number;
+    startedAt: string;
+    runDir?: string;
+};
+type HistoryFile = {
+    entries: HistoryEntry[];
+};
+type Hunt = {
+    name?: string;
+    description?: string;
+    tags?: string[];
+    vars?: Record<string, string>;
+    steps: Step[];
+    assertions?: Assertion[];
+    retry?: {
+        maxRetries: number;
+        delay?: number;
+    };
+};
+type NavigateStep = {
+    navigate: string;
+};
+type ClickStep = {
+    click: {
+        selector: string;
+    } | string;
+};
+type FillStep = {
+    fill: {
+        selector: string;
+        value: string;
+    } | Record<string, string>;
+};
+type TypeStep = {
+    type: string;
+};
+type PressStep = {
+    press: {
+        selector: string;
+        key: string;
+    };
+};
+type WaitForSelectorStep = {
+    waitForSelector: {
+        selector: string;
+        timeout?: number;
+    };
+};
+type WaitStep = {
+    wait: string | {
+        for: string;
+        timeout?: number;
+    };
+};
+type WaitForUrlStep = {
+    waitForUrl: {
+        value: string;
+        timeout?: number;
+    };
+};
+type WaitForNetworkIdleStep = {
+    waitForNetworkIdle: {
+        timeout?: number;
+    };
+};
+type SelectOptionStep = {
+    selectOption: {
+        selector: string;
+        value: string;
+    };
+};
+type SelectStep = {
+    select: Record<string, string>;
+};
+type OnDialogStep = {
+    onDialog: {
+        action: "accept" | "dismiss";
+    };
+};
+type SetInputFilesStep = {
+    setInputFiles: {
+        selector: string;
+        files: string | string[];
+    };
+};
+type InlineAssertStep = {
+    assert: {
+        visible?: string;
+        notVisible?: string;
+        urlIncludes?: string;
+        urlEquals?: string;
+    };
+};
+type RunHuntStep = {
+    runHunt: string | {
+        name: string;
+        vars?: Record<string, string>;
+    };
+};
+type HoverStep = {
+    hover: {
+        selector: string;
+    };
+};
+type ScrollStep = {
+    scroll: {
+        direction: "up" | "down" | "left" | "right";
+        amount?: number;
+    };
+};
+type ScrollToStep = {
+    scrollTo: {
+        selector: string;
+    };
+};
+type ScreenshotStep = {
+    screenshot: {
+        name?: string;
+    };
+};
+type IfStep = {
+    if: {
+        visible?: string;
+        notVisible?: string;
+        then: Step[];
+        else?: Step[];
+    };
+};
+type RepeatStep = {
+    repeat: {
+        times?: number;
+        while?: {
+            visible?: string;
+            notVisible?: string;
+        };
+        maxIterations?: number;
+        steps: Step[];
+    };
+};
+type MockRouteStep = {
+    mockRoute: {
+        url: string;
+        response: {
+            status: number;
+            contentType?: string;
+            body?: string;
+            file?: string;
+        };
+    };
+};
+type UnmockRouteStep = {
+    unmockRoute: string | {
+        url: string;
+    };
+};
+type EvalScriptStep = {
+    evalScript: string | {
+        expression: string;
+        as?: string;
+    };
+};
+type RunScriptStep = {
+    runScript: {
+        file: string;
+    };
+};
+type CopyTextStep = {
+    copyText: {
+        selector: string;
+        as: string;
+    };
+};
+type WaitForDownloadStep = {
+    waitForDownload: {
+        filename?: string;
+        timeout?: number;
+    } | null;
+};
+type AssertScreenshotStep = {
+    assertScreenshot: {
+        name: string;
+        threshold?: number;
+    };
+};
+type Step = NavigateStep | ClickStep | FillStep | TypeStep | PressStep | WaitStep | SelectOptionStep | SelectStep | OnDialogStep | SetInputFilesStep | InlineAssertStep | RunHuntStep | WaitForSelectorStep | WaitForUrlStep | WaitForNetworkIdleStep | HoverStep | ScrollStep | ScrollToStep | ScreenshotStep | IfStep | RepeatStep | MockRouteStep | UnmockRouteStep | EvalScriptStep | RunScriptStep | AssertScreenshotStep | CopyTextStep | WaitForDownloadStep;
+type Assertion = {
+    selectorExists: string;
+} | {
+    selectorNotExists: string;
+} | {
+    urlIncludes: string;
+} | {
+    urlEquals: string;
+} | {
+    noConsoleErrors: boolean;
+} | {
+    noNetworkErrors: boolean;
+};
+type StepResult = {
+    type: string;
+    status: "pass" | "fail";
+    durationMs: number;
+    selector?: string;
+    value?: string;
+    error?: string;
+    screenshot?: string;
+    /** Original selector when the step was completed via a self-healed selector. */
+    healedFrom?: string;
+};
+type AssertionResult = {
+    type: string;
+    value?: string | boolean;
+    status: "pass" | "fail";
+    error?: string;
+};
+type RunArtifacts = {
+    summary?: string;
+    screenshots?: string[];
+    console?: string;
+    trace?: string;
+    networkHar?: string;
+    junit?: string;
+};
+type TraceCorrelation = {
+    url: string;
+    status: number;
+    traceId: string;
+    header: string;
+};
+type RunResult = {
+    status: "pass" | "fail";
+    exitCode: 0 | 1;
+    startedAt: string;
+    durationMs: number;
+    hunt: string;
+    targetUrl: string;
+    steps: StepResult[];
+    assertions: AssertionResult[];
+    artifacts: RunArtifacts;
+    traceCorrelations?: TraceCorrelation[];
+};
+type CiHuntResult = {
+    hunt: string;
+    status: "pass" | "fail" | "skipped";
+    durationMs: number;
+    runDir?: string;
+    error?: string;
+};
+type CiStatus = "pass" | "fail" | "no-hunts" | "all-skipped";
+type CiFlakyHunt = {
+    hunt: string;
+    score: number;
+};
+type CiFailureCluster = {
+    cause: string;
+    stepType?: string;
+    selector?: string;
+    error: string;
+    count: number;
+    hunts: string[];
+};
+type CiResult = {
+    status: CiStatus;
+    startedAt: string;
+    durationMs: number;
+    totalHunts: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    hunts: CiHuntResult[];
+    /** Hunts whose flake score is at/above the configured threshold (omitted when none). */
+    flaky?: CiFlakyHunt[];
+    /** Groups of failed hunts sharing a common cause (omitted when none). */
+    clusters?: CiFailureCluster[];
+};
+
+type StepCallback = (result: StepResult, step: Step, index: number) => void;
+
+type RunOptions = {
+    huntName: string;
+    urlOverride?: string;
+    headed?: boolean;
+    slowMo?: number;
+    trace?: boolean;
+    configPath?: string;
+    onStep?: StepCallback;
+    browser?: "chromium" | "firefox" | "webkit";
+    channel?: BrowserChannel;
+    viewport?: string;
+    junit?: boolean;
+};
+declare function runHunt(options: RunOptions): Promise<{
+    result: RunResult;
+    runDir: string;
+    steps: Step[];
+}>;
+
+type SkipReason = "include" | "exclude";
+type SuiteHookResult = void | Promise<void>;
+interface RunSuiteHooks {
+    onHuntStart?: (huntName: string) => SuiteHookResult;
+    onStep?: RunOptions["onStep"];
+    onHuntSuccess?: (huntName: string, result: RunResult, runDir: string) => SuiteHookResult;
+    onHuntFailure?: (huntName: string, message: string) => SuiteHookResult;
+    onHuntSkipped?: (huntName: string, reason: SkipReason) => SuiteHookResult;
+}
+interface RunSuiteOptions {
+    configPath?: string;
+    urlOverride?: string;
+    headed?: boolean;
+    slowMo?: number;
+    trace?: boolean;
+    browser?: RunOptions["browser"];
+    channel?: RunOptions["channel"];
+    viewport?: string;
+    junit?: boolean;
+    includeTags?: string[];
+    excludeTags?: string[];
+    parallel?: number;
+    hooks?: RunSuiteHooks;
+}
+interface RunSuiteResult {
+    result: CiResult;
+    /** Path to the written ci-result.json, or null when there were no hunts to run. */
+    resultPath: string | null;
+}
+/**
+ * Runs every hunt in the project and aggregates a CiResult. Side-effect-free with
+ * respect to the console and process exit — callers provide hooks for presentation
+ * and inspect the returned status for exit codes.
+ */
+declare function runSuite(options?: RunSuiteOptions): Promise<RunSuiteResult>;
+
+/**
+ * A single failure worth logging as a bug: a specific hunt failing at a specific
+ * spot. `stepType`/`selector`/`stepIndex` are absent when the hunt threw before
+ * producing step results (e.g. a missing hunt file).
+ */
+interface BugFailure {
+    hunt: string;
+    stepIndex?: number;
+    stepType?: string;
+    selector?: string;
+    error: string;
+    runDir?: string;
+}
+
+interface UpdateBacklogOptions {
+    /** Project root containing docs/. Defaults to process.cwd(). */
+    projectRoot?: string;
+    /** Overrides the backlog path (default: <projectRoot>/docs/backlog.md). */
+    backlogPath?: string;
+    /** Overrides the resolved path (default: <projectRoot>/docs/resolved.md). */
+    resolvedPath?: string;
+    /** Date stamp for new tickets (default: today, YYYY-MM-DD). */
+    date?: string;
+}
+interface BugLogSummary {
+    /** QA-NNN ids created for brand-new failures. */
+    created: string[];
+    /** QA-NNN ids created for failures that recurred after being resolved. */
+    regressions: string[];
+    /** QA-NNN ids of already-open tickets that were left untouched. */
+    skipped: string[];
+    backlogPath: string;
+}
+/** Extract one BugFailure per failed hunt from a completed suite run. */
+declare function extractFailures(suiteResult: RunSuiteResult): BugFailure[];
+/**
+ * Logs failures from a completed suite run as deduplicated bug tickets in the
+ * target project's backlog. New failures get a fresh QA-NNN ticket; failures that
+ * already have an open ticket are skipped; failures matching a resolved ticket are
+ * logged as regressions that reference the old id. Idempotent across runs.
+ */
+declare function updateBacklogFromSuite(suiteResult: RunSuiteResult, options?: UpdateBacklogOptions): BugLogSummary;
+
+declare function readHistory(configDir: string): HistoryFile;
+declare function readHuntHistory(configDir: string, huntName: string): HistoryEntry[];
+
+declare const DEFAULT_FLAKY_THRESHOLD = 0.3;
+type FlakyScore = {
+    hunt: string;
+    /** Oscillation rate in [0,1]: share of consecutive run pairs whose status changed. */
+    score: number;
+    runs: number;
+    flaky: boolean;
+};
+/**
+ * Flake score for a single hunt's run history (oldest→newest): the fraction of
+ * consecutive run pairs where the status flipped (pass↔fail). 0 = perfectly
+ * stable, 1 = flips every run. Needs at least 2 runs; fewer returns 0.
+ */
+declare function computeFlakeScore(entries: HistoryEntry[], lastN?: number): number;
+type RankFlakyOptions = {
+    /** Only score the most recent N runs per hunt. */
+    lastN?: number;
+    /** Score at/above this is flagged flaky. Defaults to DEFAULT_FLAKY_THRESHOLD. */
+    threshold?: number;
+};
+/**
+ * Rank every hunt in the project's history by flake score, highest first.
+ * Hunts are tie-broken by run count (more runs first) then name for stable output.
+ */
+declare function rankFlaky(configDir: string, options?: RankFlakyOptions): FlakyScore[];
+
+/**
+ * Self-healing selectors (PROWL-023). When an explicit selector matches nothing,
+ * derive the human "intent" from the selector and try alternative strategies —
+ * fuzzy text, ARIA label, and structural (interactive element + text) — healing
+ * ONLY to a candidate that resolves to exactly one element. Opt-in via
+ * `guardrails.selfHealing`; never guesses among multiple matches.
+ */
+type HealResult = {
+    /** The candidate selector that uniquely matched. */
+    selector: string;
+    /** The original selector that failed. */
+    healedFrom: string;
+    /** Which strategy produced the match (for reporting). */
+    strategy: "text" | "aria" | "structural";
+};
+/**
+ * Pull human-meaningful words out of a raw selector. Reads id (`#submit-btn`),
+ * class tokens (`.login-form`), and attribute values (`[data-testid="sign-in"]`,
+ * `[aria-label='Close']`), splitting on separators and camelCase. Returns the
+ * lowercased words (de-duped, in order) and a space-joined label. Mapping is
+ * intentionally literal/predictable — no noise-word filtering.
+ */
+declare function extractSelectorIntent(selector: string): {
+    words: string[];
+    label: string;
+};
+/**
+ * Build candidate Playwright selectors for a derived intent, in AC priority order:
+ * (1) fuzzy text, (2) ARIA label, (3) structural (interactive element + text).
+ * Returns [] when the selector carried no usable words.
+ */
+declare function buildHealCandidates(selector: string): Array<{
+    selector: string;
+    strategy: HealResult["strategy"];
+}>;
+/**
+ * Attempt to heal a failed selector. Returns a HealResult only when a candidate
+ * resolves to exactly one element; otherwise null. Counting is delegated so this
+ * is unit-testable with a fake page.
+ */
+declare function healSelector(page: Pick<Page, "locator">, selector: string, options: {
+    enabled: boolean;
+}): Promise<HealResult | null>;
+
+/**
+ * Failure clustering (PROWL-034). Groups failures that share a common cause —
+ * the same normalized error on the same step type and selector — so a single
+ * root cause (e.g. one renamed selector breaking 5 hunts) surfaces as one
+ * cluster instead of N independent failures.
+ */
+type FailureCluster = CiFailureCluster;
+/**
+ * Group failures by shared cause. Returns clusters sorted by size (largest first),
+ * then by cause for stable output. Every failure lands in a cluster — single-hunt
+ * clusters are included so the full picture is preserved; callers can filter to
+ * `count > 1` to show only shared root causes.
+ */
+declare function clusterFailures(failures: BugFailure[]): FailureCluster[];
+
+declare function loadConfig(configPath?: string): {
+    config: Config;
+    configPath: string;
+    configDir: string;
+};
+declare function loadHunt(huntName: string, configDir: string): Hunt;
+declare function loadHuntTags(huntName: string, configDir: string): string[];
+declare function loadHuntMeta(huntName: string, configDir: string): {
+    description?: string;
+    tags: string[];
+};
+declare function listHunts(configDir: string): string[];
+
+declare const configSchema: z.ZodObject<{
+    target: z.ZodObject<{
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+    }, {
+        url: string;
+    }>;
+    browser: z.ZodOptional<z.ZodObject<{
+        headless: z.ZodOptional<z.ZodBoolean>;
+        slowMo: z.ZodOptional<z.ZodNumber>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+        engine: z.ZodOptional<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+        channel: z.ZodOptional<z.ZodEnum<["chromium", "chrome", "chrome-beta", "chrome-canary", "chrome-dev", "msedge", "msedge-beta", "msedge-canary", "msedge-dev"]>>;
+        viewport: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["mobile", "tablet", "desktop"]>, z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width: number;
+            height: number;
+        }>]>>;
+    }, "strip", z.ZodTypeAny, {
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        timeout?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+        viewport?: "mobile" | "tablet" | "desktop" | {
+            width: number;
+            height: number;
+        } | undefined;
+    }, {
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        timeout?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+        viewport?: "mobile" | "tablet" | "desktop" | {
+            width: number;
+            height: number;
+        } | undefined;
+    }>>;
+    artifacts: z.ZodOptional<z.ZodObject<{
+        screenshots: z.ZodOptional<z.ZodEnum<["on-failure", "all"]>>;
+        networkHar: z.ZodOptional<z.ZodBoolean>;
+        console: z.ZodOptional<z.ZodBoolean>;
+        junit: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        screenshots?: "on-failure" | "all" | undefined;
+        networkHar?: boolean | undefined;
+        console?: boolean | undefined;
+        junit?: boolean | undefined;
+    }, {
+        screenshots?: "on-failure" | "all" | undefined;
+        networkHar?: boolean | undefined;
+        console?: boolean | undefined;
+        junit?: boolean | undefined;
+    }>>;
+    assertions: z.ZodOptional<z.ZodObject<{
+        noConsoleErrors: z.ZodOptional<z.ZodBoolean>;
+        noNetworkErrors: z.ZodOptional<z.ZodBoolean>;
+        maxTotalTimeMs: z.ZodOptional<z.ZodNumber>;
+        networkIgnorePatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        noConsoleErrors?: boolean | undefined;
+        noNetworkErrors?: boolean | undefined;
+        maxTotalTimeMs?: number | undefined;
+        networkIgnorePatterns?: string[] | undefined;
+    }, {
+        noConsoleErrors?: boolean | undefined;
+        noNetworkErrors?: boolean | undefined;
+        maxTotalTimeMs?: number | undefined;
+        networkIgnorePatterns?: string[] | undefined;
+    }>>;
+    guardrails: z.ZodOptional<z.ZodObject<{
+        maxSteps: z.ZodOptional<z.ZodNumber>;
+        allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        forbiddenSelectors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        selfHealing: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        maxSteps?: number | undefined;
+        allowedDomains?: string[] | undefined;
+        forbiddenSelectors?: string[] | undefined;
+        selfHealing?: boolean | undefined;
+    }, {
+        maxSteps?: number | undefined;
+        allowedDomains?: string[] | undefined;
+        forbiddenSelectors?: string[] | undefined;
+        selfHealing?: boolean | undefined;
+    }>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        storageStatePath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        storageStatePath?: string | undefined;
+    }, {
+        storageStatePath?: string | undefined;
+    }>>;
+    history: z.ZodOptional<z.ZodObject<{
+        maxRuns: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxRuns?: number | undefined;
+    }, {
+        maxRuns?: number | undefined;
+    }>>;
+    bugLog: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        backlogPath: z.ZodOptional<z.ZodString>;
+        resolvedPath: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        backlogPath?: string | undefined;
+        resolvedPath?: string | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        backlogPath?: string | undefined;
+        resolvedPath?: string | undefined;
+    }>>;
+    tracing: z.ZodOptional<z.ZodObject<{
+        header: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        header?: string | undefined;
+    }, {
+        header?: string | undefined;
+    }>>;
+    reliability: z.ZodOptional<z.ZodObject<{
+        flakyThreshold: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        flakyThreshold?: number | undefined;
+    }, {
+        flakyThreshold?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    target: {
+        url: string;
+    };
+    browser?: {
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        timeout?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+        viewport?: "mobile" | "tablet" | "desktop" | {
+            width: number;
+            height: number;
+        } | undefined;
+    } | undefined;
+    artifacts?: {
+        screenshots?: "on-failure" | "all" | undefined;
+        networkHar?: boolean | undefined;
+        console?: boolean | undefined;
+        junit?: boolean | undefined;
+    } | undefined;
+    assertions?: {
+        noConsoleErrors?: boolean | undefined;
+        noNetworkErrors?: boolean | undefined;
+        maxTotalTimeMs?: number | undefined;
+        networkIgnorePatterns?: string[] | undefined;
+    } | undefined;
+    guardrails?: {
+        maxSteps?: number | undefined;
+        allowedDomains?: string[] | undefined;
+        forbiddenSelectors?: string[] | undefined;
+        selfHealing?: boolean | undefined;
+    } | undefined;
+    auth?: {
+        storageStatePath?: string | undefined;
+    } | undefined;
+    history?: {
+        maxRuns?: number | undefined;
+    } | undefined;
+    bugLog?: {
+        enabled?: boolean | undefined;
+        backlogPath?: string | undefined;
+        resolvedPath?: string | undefined;
+    } | undefined;
+    tracing?: {
+        header?: string | undefined;
+    } | undefined;
+    reliability?: {
+        flakyThreshold?: number | undefined;
+    } | undefined;
+}, {
+    target: {
+        url: string;
+    };
+    browser?: {
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        timeout?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+        viewport?: "mobile" | "tablet" | "desktop" | {
+            width: number;
+            height: number;
+        } | undefined;
+    } | undefined;
+    artifacts?: {
+        screenshots?: "on-failure" | "all" | undefined;
+        networkHar?: boolean | undefined;
+        console?: boolean | undefined;
+        junit?: boolean | undefined;
+    } | undefined;
+    assertions?: {
+        noConsoleErrors?: boolean | undefined;
+        noNetworkErrors?: boolean | undefined;
+        maxTotalTimeMs?: number | undefined;
+        networkIgnorePatterns?: string[] | undefined;
+    } | undefined;
+    guardrails?: {
+        maxSteps?: number | undefined;
+        allowedDomains?: string[] | undefined;
+        forbiddenSelectors?: string[] | undefined;
+        selfHealing?: boolean | undefined;
+    } | undefined;
+    auth?: {
+        storageStatePath?: string | undefined;
+    } | undefined;
+    history?: {
+        maxRuns?: number | undefined;
+    } | undefined;
+    bugLog?: {
+        enabled?: boolean | undefined;
+        backlogPath?: string | undefined;
+        resolvedPath?: string | undefined;
+    } | undefined;
+    tracing?: {
+        header?: string | undefined;
+    } | undefined;
+    reliability?: {
+        flakyThreshold?: number | undefined;
+    } | undefined;
+}>;
+declare const stepSchema: z.ZodType<Step>;
+declare const huntSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    steps: z.ZodArray<z.ZodType<Step, z.ZodTypeDef, Step>, "many">;
+    assertions: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        selectorExists: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        selectorExists: string;
+    }, {
+        selectorExists: string;
+    }>, z.ZodObject<{
+        selectorNotExists: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        selectorNotExists: string;
+    }, {
+        selectorNotExists: string;
+    }>, z.ZodObject<{
+        urlIncludes: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        urlIncludes: string;
+    }, {
+        urlIncludes: string;
+    }>, z.ZodObject<{
+        urlEquals: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        urlEquals: string;
+    }, {
+        urlEquals: string;
+    }>, z.ZodObject<{
+        noConsoleErrors: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        noConsoleErrors: boolean;
+    }, {
+        noConsoleErrors: boolean;
+    }>, z.ZodObject<{
+        noNetworkErrors: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        noNetworkErrors: boolean;
+    }, {
+        noNetworkErrors: boolean;
+    }>]>, "many">>;
+    retry: z.ZodOptional<z.ZodObject<{
+        maxRetries: z.ZodNumber;
+        delay: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxRetries: number;
+        delay?: number | undefined;
+    }, {
+        maxRetries: number;
+        delay?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    steps: Step[];
+    assertions?: ({
+        selectorExists: string;
+    } | {
+        selectorNotExists: string;
+    } | {
+        urlIncludes: string;
+    } | {
+        urlEquals: string;
+    } | {
+        noConsoleErrors: boolean;
+    } | {
+        noNetworkErrors: boolean;
+    })[] | undefined;
+    name?: string | undefined;
+    vars?: Record<string, string> | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    retry?: {
+        maxRetries: number;
+        delay?: number | undefined;
+    } | undefined;
+}, {
+    steps: Step[];
+    assertions?: ({
+        selectorExists: string;
+    } | {
+        selectorNotExists: string;
+    } | {
+        urlIncludes: string;
+    } | {
+        urlEquals: string;
+    } | {
+        noConsoleErrors: boolean;
+    } | {
+        noNetworkErrors: boolean;
+    })[] | undefined;
+    name?: string | undefined;
+    vars?: Record<string, string> | undefined;
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    retry?: {
+        maxRetries: number;
+        delay?: number | undefined;
+    } | undefined;
+}>;
+
+type InterpolatedHunt = {
+    hunt: Hunt;
+    redactedFillSteps: Set<string>;
+    randomVars: Record<string, string>;
+    redactionValues: string[];
+};
+declare function interpolateHunt(hunt: Hunt, env: NodeJS.ProcessEnv, randomVars?: Record<string, string>): InterpolatedHunt;
+
+type PageElement = {
+    tag: string;
+    type?: string;
+    selectors: Record<string, string>;
+    role?: string;
+    label?: string;
+    placeholder?: string;
+    required: boolean;
+    formGroup?: number;
+};
+type PageForm = {
+    index: number;
+    action?: string;
+    method?: string;
+    fieldCount: number;
+};
+type PageLink = {
+    text: string;
+    href: string;
+    selector: string;
+};
+type AnalysisResult = {
+    url: string;
+    title: string;
+    elements: PageElement[];
+    forms: PageForm[];
+    links: PageLink[];
+};
+declare function analyzePage(page: Page): Promise<AnalysisResult>;
+
+type AiProvider = "anthropic" | "openai";
+type AiConfig = {
+    provider: AiProvider;
+    model: string;
+    apiKey: string;
+};
+
+type GenerateOptions = {
+    url?: string;
+    analysis?: AnalysisResult;
+    intent: string;
+    browser?: string;
+    viewport?: string;
+    aiConfig?: AiConfig;
+};
+declare function generateHunt(options: GenerateOptions): Promise<string>;
+
+export { type AnalysisResult, type AssertScreenshotStep, type Assertion, type AssertionResult, type BrowserChannel, type BrowserEngine, type BugFailure, type BugLogSummary, type CiFailureCluster, type CiFlakyHunt, type CiHuntResult, type CiResult, type CiStatus, type Config, DEFAULT_FLAKY_THRESHOLD, type EvalScriptStep, type FailureCluster, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, type IfStep, type MockRouteStep, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, type Step, type StepResult, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, analyzePage, buildHealCandidates, clusterFailures, computeFlakeScore, configSchema, extractFailures, extractSelectorIntent, generateHunt, healSelector, huntSchema, interpolateHunt, listHunts, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, rankFlaky, readHistory, readHuntHistory, runHunt, runSuite, stepSchema, updateBacklogFromSuite };