prowl-tools 0.1.3 → 0.1.4

package/dist/lib.d.cts

@@ -1,16 +1,30 @@
-import { Page } from 'playwright';
 import { z } from 'zod';
 
-type BrowserEngine = "chromium" | "firefox" | "webkit";
+declare const SUPPORTED_BROWSER_ENGINES: readonly ["chromium", "firefox", "webkit"];
+type BrowserEngine = (typeof SUPPORTED_BROWSER_ENGINES)[number];
 type BrowserChannel = "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev";
 type Viewport = {
     width: number;
     height: number;
 };
+/** Web execution target (default): drives a browser at `url`. */
+type WebTarget = {
+    type: "web";
+    url: string;
+};
+/**
+ * macOS native execution target (experimental, PROWL-048). `app` is a bundle
+ * identifier (e.g. `com.example.App`) or an absolute path to a `.app` bundle.
+ * App-path guardrails are matched against the path, bundle name, and
+ * `CFBundleIdentifier` from `Contents/Info.plist` when it is readable.
+ */
+type MacosTarget = {
+    type: "macos";
+    app: string;
+};
+type Target = WebTarget | MacosTarget;
 type Config = {
-    target: {
-        url: string;
-    };
+    target: Target;
     browser: {
         headless: boolean;
         slowMo: number;
@@ -34,6 +48,8 @@ type Config = {
     guardrails: {
         maxSteps: number;
         allowedDomains: string[];
+        /** Native scope analog of `allowedDomains`: allowed bundle IDs, app bundle names, or `.app` paths. */
+        allowedApps: string[];
         forbiddenSelectors: string[];
         selfHealing: boolean;
     };
@@ -339,6 +355,241 @@ type CiResult = {
     clusters?: CiFailureCluster[];
 };
 
+/**
+ * PROWL-047 / ARCH-001 — Session driver abstraction.
+ *
+ * `SessionDriver` is the narrow, engine-agnostic surface the step runner drives.
+ * Today the only implementation is the Playwright driver (`playwright-driver.ts`),
+ * but factoring the runner against this interface is the prerequisite for
+ * non-browser execution targets (macOS native, Electron, mobile — see PROWL-048).
+ *
+ * The interface intentionally covers only the verbs `src/runner/steps.ts`
+ * actually uses. Selector strings are the driver's own dialect: the driver
+ * supplies `parseTextSelector` so the guardrail policy can reason about them
+ * without knowing the engine.
+ */
+/** Coarse capability groups a step handler can require of a driver. */
+type DriverCapability = "navigate" | "query" | "interact" | "wait" | "screenshot" | "evaluate" | "response" | "route" | "dialog" | "files" | "download";
+/** How a dialog opened by the page should be answered. */
+type DialogAction = "accept" | "dismiss";
+/** Options accepted when navigating; mirrors the subset of Playwright's `goto`. */
+type NavigateOptions = {
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+};
+/** A network response as the driver exposes it (engine-neutral). */
+type DriverResponse = {
+    url(): string;
+    status(): number;
+    /** Header names MUST be lowercased by the driver; consumers look up lowercase keys. */
+    headers(): Record<string, string>;
+};
+/** A route intercepted via `route()`; the handler fulfills it with a canned response. */
+type DriverRoute = {
+    fulfill(response: {
+        status: number;
+        contentType?: string;
+        body?: string;
+    }): Promise<void>;
+};
+/** A file download surfaced by `waitForDownloadEvent()`. */
+type DriverDownload = {
+    suggestedFilename(): string;
+    saveAs(path: string): Promise<void>;
+};
+/**
+ * The operations the step runner performs against a live session. Each method
+ * corresponds to one Playwright Page/Locator call in the legacy runner, so the
+ * Playwright implementation is a faithful pass-through and behaviour is
+ * unchanged.
+ */
+interface SessionDriver {
+    /** Capabilities this driver supports; handlers declare what they need. */
+    readonly capabilities: ReadonlySet<DriverCapability>;
+    goto(url: string, options?: NavigateOptions): Promise<void>;
+    currentUrl(): string;
+    count(selector: string): Promise<number>;
+    textContent(selector: string): Promise<string | null>;
+    click(selector: string): Promise<void>;
+    clickFirst(selector: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    fillFirst(selector: string, value: string): Promise<void>;
+    press(selector: string, key: string): Promise<void>;
+    selectOption(selector: string, value: string): Promise<void>;
+    selectOptionFirst(selector: string, value: string): Promise<void>;
+    hover(selector: string): Promise<void>;
+    scrollIntoView(selector: string): Promise<void>;
+    setInputFiles(selector: string, files: string | string[]): Promise<void>;
+    countByRole(role: string, name: string): Promise<number>;
+    clickFirstByRole(role: string, name: string): Promise<void>;
+    countByLabel(label: string): Promise<number>;
+    fillFirstByLabel(label: string, value: string): Promise<void>;
+    selectOptionFirstByLabel(label: string, value: string): Promise<void>;
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForUrl(predicate: (url: string) => boolean, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForNetworkIdle(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    evaluate<R = unknown, A = unknown>(pageFunction: string | ((arg: A) => R | Promise<R>), arg?: A): Promise<R>;
+    screenshot(options: {
+        path: string;
+        fullPage?: boolean;
+    }): Promise<void>;
+    onResponse(handler: (response: DriverResponse) => void): void;
+    route(url: string, handler: (route: DriverRoute) => void | Promise<void>): Promise<void>;
+    unroute(url: string): Promise<void>;
+    onDialog(action: DialogAction): void;
+    waitForDownloadEvent(options?: {
+        timeout?: number;
+    }): Promise<DriverDownload>;
+    /**
+     * Driver-supplied selector parser: returns the literal text a text-engine
+     * selector matches (e.g. `text="Delete"` → `Delete`), or null for any other
+     * selector. The guardrail policy uses this to interpret forbidden patterns
+     * without hard-coding the engine's selector dialect.
+     */
+    parseTextSelector(selector: string): string | null;
+}
+
+/**
+ * PROWL-048 / ARCH-002 — macOS native implementation of {@link SessionDriver}.
+ *
+ * `MacDriver` drives a native macOS app through the `prowl-macdriver` Swift
+ * helper (Accessibility / AXUIElement) over a long-lived JSON-over-stdio
+ * transport ({@link MacHelperClient}). It implements only the portable subset of
+ * the driver surface — its `capabilities` set is honest: `query`, `interact`,
+ * `wait`, `screenshot`. Web-only verbs (navigation, network, dialogs, files,
+ * downloads, script evaluation) are unsupported stubs; the runner never reaches
+ * them because both the target step-compatibility check and the runtime
+ * capability gate reject web-only steps for the macOS target.
+ *
+ * Selector dialect (parsed here, so the Swift helper only matches attributes):
+ *   id=openSettings              → accessibility identifier
+ *   role=button[name="Save"]     → AX role + accessible name
+ *   label="Email"                → exact accessibility label
+ *   text="Save" | Save           → title/description/value substring
+ *   statusItem                   → open the app's menu bar status-item menu
+ *   menu=Preferences…            → open the status-item menu and click an item
+ */
+
+/** A structured accessibility query understood by the Swift helper. */
+type MacQuery = {
+    by: "id";
+    value: string;
+} | {
+    by: "role";
+    role: string;
+    name?: string;
+} | {
+    by: "text";
+    value: string;
+} | {
+    by: "label";
+    value: string;
+} | {
+    by: "focused";
+};
+/** The transport MacDriver talks to: one request → one response, matched by id. */
+interface MacHelperClient {
+    /** Send a command; resolve with its `result` payload or reject with its error. */
+    request(cmd: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Shut the helper down. */
+    close(): Promise<void>;
+}
+type MacDriverOptions = {
+    /** Bundle id / app label, used only for the informational `currentUrl()` value. */
+    appLabel?: string;
+};
+/** Parse a Prowl selector string into a {@link MacQuery}. Bare text matches by text. */
+declare function parseMacSelector(selector: string): MacQuery;
+/** Wrap a live {@link MacHelperClient} as a {@link SessionDriver}. */
+declare function createMacDriver(client: MacHelperClient, options?: MacDriverOptions): SessionDriver;
+
+declare function macdriverBuildInstructions(): string;
+/**
+ * Resolve the helper binary path. Order: `PROWL_MACDRIVER_BIN`, then the
+ * release then debug build under `macdriver/.build/`. Throws with build
+ * instructions when none is found.
+ */
+declare function resolveHelperBinary(env?: NodeJS.ProcessEnv): string;
+/** Default per-request deadline for the helper transport. */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+type SpawnMacHelperOptions = {
+    /** Per-request deadline; a request that gets no response by then rejects. */
+    requestTimeoutMs?: number;
+};
+/** A {@link MacHelperClient} backed by a spawned `prowl-macdriver serve` process. */
+declare class SpawnMacHelperClient implements MacHelperClient {
+    private readonly child;
+    private readonly pending;
+    private readonly requestTimeoutMs;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private nextId;
+    private closed;
+    private terminalError;
+    constructor(binaryPath: string, options?: SpawnMacHelperOptions);
+    private onStdout;
+    private dispatch;
+    private failAll;
+    private recordTerminalFailure;
+    /** Number of in-flight requests awaiting a response (for teardown/tests). */
+    get pendingCount(): number;
+    request(cmd: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+type MacSession = {
+    client: MacHelperClient;
+    driver: SessionDriver;
+    bundleId: string;
+};
+type LaunchMacOptions = {
+    /** Bundle id or absolute `.app` path. */
+    app: string;
+    timeoutMs?: number;
+    /** Inject a helper client (tests / a prebuilt binary); defaults to spawning the helper. */
+    clientFactory?: () => MacHelperClient;
+};
+/** Launch/attach the target app through the helper and build a {@link MacDriver}. */
+declare function launchMacSession(options: LaunchMacOptions): Promise<MacSession>;
+/** Quit the target app (best effort) and shut the helper down. */
+declare function closeMacSession(session: MacSession): Promise<void>;
+
+/**
+ * PROWL-048 / ARCH-002 — target ⇄ step compatibility.
+ *
+ * The runtime capability gate in the step runner already rejects steps a driver
+ * cannot honor. This adds a friendlier, earlier validation-time rejection: when
+ * the selected target is macOS, hunts using web-only steps fail fast with a
+ * clear message before anything launches.
+ */
+
+/**
+ * Step types that only make sense on the web target. Everything else
+ * (`click`, `fill`, `type`, `press`, `wait`, `assert visible/notVisible`,
+ * `screenshot`, `assertScreenshot`, `repeat`, `runHunt`, `if`, `copyText`,
+ * `hover`, `scrollTo`, `waitForSelector`) is portable across targets.
+ */
+declare const WEB_ONLY_STEP_TYPES: ReadonlySet<string>;
+/** The web-only reason a step is unsupported on a non-web target, or null if portable. */
+declare function webOnlyReason(step: Step): string | null;
+/**
+ * Throw if any step in `steps` (recursing into `if`/`repeat` bodies) is not
+ * supported by `target`. `runHunt` references are validated when the referenced
+ * hunt itself runs. No-op for the web target.
+ */
+declare function assertStepsSupportedByTarget(steps: Step[], target: Target["type"]): void;
+/**
+ * Native scope guardrail: if `allowedApps` is non-empty it must include an
+ * accepted identity for the target app: bundle id, app bundle name, or `.app`
+ * path. An empty list means the scope is unset and the target app is implicitly
+ * allowed — mirroring how allowedDomains auto-includes the web target's host.
+ */
+declare function assertTargetAppAllowed(allowedApps: string[], app: string): void;
+
 type StepCallback = (result: StepResult, step: Step, index: number) => void;
 
 type RunOptions = {
@@ -353,6 +604,8 @@ type RunOptions = {
     channel?: BrowserChannel;
     viewport?: string;
     junit?: boolean;
+    /** Inject a macOS helper client (tests / a prebuilt binary); defaults to spawning the helper. */
+    macClientFactory?: () => MacHelperClient;
 };
 declare function runHunt(options: RunOptions): Promise<{
     result: RunResult;
@@ -468,6 +721,16 @@ type RankFlakyOptions = {
  */
 declare function rankFlaky(configDir: string, options?: RankFlakyOptions): FlakyScore[];
 
+/**
+ * The minimal probe surface healing needs: count matches for a candidate
+ * selector. A live Playwright page and a {@link SessionDriver}-backed adapter
+ * both satisfy it, so healing carries no Playwright dependency.
+ */
+type SelectorProbe = {
+    locator(selector: string): {
+        count(): Promise<number>;
+    };
+};
 /**
  * Self-healing selectors (PROWL-023). When an explicit selector matches nothing,
  * derive the human "intent" from the selector and try alternative strategies —
@@ -508,7 +771,7 @@ declare function buildHealCandidates(selector: string): Array<{
  * 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: {
+declare function healSelector(probe: SelectorProbe, selector: string, options: {
     enabled: boolean;
 }): Promise<HealResult | null>;
 
@@ -541,13 +804,25 @@ declare function loadHuntMeta(huntName: string, configDir: string): {
 declare function listHunts(configDir: string): string[];
 
 declare const configSchema: z.ZodObject<{
-    target: z.ZodObject<{
+    target: z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"macos">;
+        app: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        app: string;
+        type: "macos";
+    }, {
+        app: string;
+        type: "macos";
+    }>, z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"web">>;
         url: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         url: string;
+        type?: "web" | undefined;
     }, {
         url: string;
-    }>;
+        type?: "web" | undefined;
+    }>]>;
     browser: z.ZodOptional<z.ZodObject<{
         headless: z.ZodOptional<z.ZodBoolean>;
         slowMo: z.ZodOptional<z.ZodNumber>;
@@ -565,9 +840,9 @@ declare const configSchema: z.ZodObject<{
             height: number;
         }>]>>;
     }, "strip", z.ZodTypeAny, {
+        timeout?: 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" | {
@@ -575,9 +850,9 @@ declare const configSchema: z.ZodObject<{
             height: number;
         } | undefined;
     }, {
+        timeout?: 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" | {
@@ -620,16 +895,19 @@ declare const configSchema: z.ZodObject<{
     guardrails: z.ZodOptional<z.ZodObject<{
         maxSteps: z.ZodOptional<z.ZodNumber>;
         allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedApps: 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;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     }, {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     }>>;
@@ -677,11 +955,15 @@ declare const configSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     target: {
         url: string;
+        type?: "web" | undefined;
+    } | {
+        app: string;
+        type: "macos";
     };
     browser?: {
+        timeout?: 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" | {
@@ -704,6 +986,7 @@ declare const configSchema: z.ZodObject<{
     guardrails?: {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     } | undefined;
@@ -727,11 +1010,15 @@ declare const configSchema: z.ZodObject<{
 }, {
     target: {
         url: string;
+        type?: "web" | undefined;
+    } | {
+        app: string;
+        type: "macos";
     };
     browser?: {
+        timeout?: 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" | {
@@ -754,6 +1041,7 @@ declare const configSchema: z.ZodObject<{
     guardrails?: {
         maxSteps?: number | undefined;
         allowedDomains?: string[] | undefined;
+        allowedApps?: string[] | undefined;
         forbiddenSelectors?: string[] | undefined;
         selfHealing?: boolean | undefined;
     } | undefined;
@@ -831,6 +1119,7 @@ declare const huntSchema: z.ZodObject<{
     }>>;
 }, "strict", z.ZodTypeAny, {
     steps: Step[];
+    name?: string | undefined;
     assertions?: ({
         selectorExists: string;
     } | {
@@ -844,7 +1133,6 @@ declare const huntSchema: z.ZodObject<{
     } | {
         noNetworkErrors: boolean;
     })[] | undefined;
-    name?: string | undefined;
     vars?: Record<string, string> | undefined;
     description?: string | undefined;
     tags?: string[] | undefined;
@@ -854,6 +1142,7 @@ declare const huntSchema: z.ZodObject<{
     } | undefined;
 }, {
     steps: Step[];
+    name?: string | undefined;
     assertions?: ({
         selectorExists: string;
     } | {
@@ -867,7 +1156,6 @@ declare const huntSchema: z.ZodObject<{
     } | {
         noNetworkErrors: boolean;
     })[] | undefined;
-    name?: string | undefined;
     vars?: Record<string, string> | undefined;
     description?: string | undefined;
     tags?: string[] | undefined;
@@ -885,6 +1173,15 @@ type InterpolatedHunt = {
 };
 declare function interpolateHunt(hunt: Hunt, env: NodeJS.ProcessEnv, randomVars?: Record<string, string>): InterpolatedHunt;
 
+/**
+ * The minimal surface `analyzePage` needs: a way to evaluate a DOM-scraping
+ * function in the page. Both a live Playwright page and a {@link SessionDriver}
+ * satisfy it (the driver's `evaluate` verb), so the analyzer has no direct
+ * Playwright dependency — its DOM scraping runs through the driver.
+ */
+type DomEvaluator = {
+    evaluate(pageFunction: () => unknown): Promise<unknown>;
+};
 type PageElement = {
     tag: string;
     type?: string;
@@ -913,7 +1210,7 @@ type AnalysisResult = {
     forms: PageForm[];
     links: PageLink[];
 };
-declare function analyzePage(page: Page): Promise<AnalysisResult>;
+declare function analyzePage(page: DomEvaluator): Promise<AnalysisResult>;
 
 type AiProvider = "anthropic" | "openai";
 type AiConfig = {
@@ -932,4 +1229,4 @@ type GenerateOptions = {
 };
 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 };
+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, DEFAULT_REQUEST_TIMEOUT_MS, type EvalScriptStep, type FailureCluster, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, type IfStep, type LaunchMacOptions, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacosTarget, 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, SpawnMacHelperClient, type SpawnMacHelperOptions, type Step, type StepResult, type Target, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, WEB_ONLY_STEP_TYPES, type WebTarget, analyzePage, assertStepsSupportedByTarget, assertTargetAppAllowed, buildHealCandidates, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createMacDriver, extractFailures, extractSelectorIntent, generateHunt, healSelector, huntSchema, interpolateHunt, launchMacSession, listHunts, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, parseMacSelector, rankFlaky, readHistory, readHuntHistory, resolveHelperBinary, runHunt, runSuite, stepSchema, updateBacklogFromSuite, webOnlyReason };