prowl-tools 0.1.6 → 0.1.8

package/dist/lib.d.ts

@@ -327,7 +327,7 @@ type StepResult = {
 type AssertionResult = {
     type: string;
     value?: string | boolean;
-    status: "pass" | "fail";
+    status: "pass" | "fail" | "skipped";
     error?: string;
 };
 type RunArtifacts = {
@@ -444,6 +444,8 @@ interface SessionDriver {
     goto(url: string, options?: NavigateOptions): Promise<void>;
     currentUrl(): string;
     count(selector: string): Promise<number>;
+    /** Count only elements the driver considers visibly present, when it can distinguish visibility from existence. */
+    visibleCount?(selector: string): Promise<number>;
     textContent(selector: string): Promise<string | null>;
     click(selector: string): Promise<void>;
     clickFirst(selector: string): Promise<void>;
@@ -453,6 +455,12 @@ interface SessionDriver {
     selectOption(selector: string, value: string): Promise<void>;
     selectOptionFirst(selector: string, value: string): Promise<void>;
     hover(selector: string): Promise<void>;
+    /**
+     * Scroll the viewport in `direction` by `amount` (engine-defined units: CSS
+     * pixels on web, a synthesized swipe distance on mobile). Native targets that
+     * have no scroll gesture (macOS) reject this.
+     */
+    scroll(direction: "up" | "down" | "left" | "right", amount?: number): Promise<void>;
     scrollIntoView(selector: string): Promise<void>;
     setInputFiles(selector: string, files: string | string[]): Promise<void>;
     countByRole(role: string, name: string): Promise<number>;
@@ -544,13 +552,57 @@ 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;
+/** Basename of the helper executable, in the tarball and on disk. */
+declare const HELPER_BINARY = "prowl-macdriver";
+/** Pinned helper version. A CLI release always installs this exact version. */
+declare const MACDRIVER_VERSION = "0.1.0";
+/** GitHub `owner/repo` that hosts the helper releases. */
+declare const MACDRIVER_REPO = "prowl-tools/prowl";
+/** Code-signing identifier assigned to release builds. */
+declare const MACDRIVER_SIGNING_IDENTIFIER = "tools.prowl.macdriver";
+/** Developer ID Application common-name prefix expected on release builds. */
+declare const MACDRIVER_SIGNING_AUTHORITY_PREFIX = "Developer ID Application: Genkei Labs";
+/** Accepted helper release version token. */
+declare const MACDRIVER_VERSION_PATTERN: RegExp;
+/** Validate the helper release version before using it in URLs or paths. */
+declare function validateMacdriverVersion(version: string): string;
+/** Git tag for a helper version — the release the workflow builds. */
+declare function macdriverReleaseTag(version?: string): string;
+/** Release asset file name for the universal (arm64 + x86_64) binary zip. */
+declare function macdriverAssetName(version?: string): string;
+/** Release asset file name for the SHA-256 checksum sidecar. */
+declare function macdriverChecksumName(version?: string): string;
+/** Download URL for a named asset of the pinned release (follows redirects). */
+declare function macdriverAssetUrl(assetName: string, version?: string): string;
+/** Root of all user-level installs: `~/.prowl/macdriver`. */
+declare function macdriverInstallRoot(homedir?: string): string;
+/** Directory that holds a specific installed version. */
+declare function macdriverVersionDir(version?: string, homedir?: string): string;
+/** Absolute path to the installed helper binary for a version. */
+declare function macdriverInstalledBinary(version?: string, homedir?: string): 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.
+ * Guidance shown when the helper can't be resolved. Leads with the
+ * two-minute `prowl macdriver install` path; source build and the
+ * `PROWL_MACDRIVER_BIN` override are the contributor fallbacks.
  */
-declare function resolveHelperBinary(env?: NodeJS.ProcessEnv): string;
+declare function macdriverBuildInstructions(): string;
+type ResolveHelperOptions = {
+    /** Home directory for the user-level install lookup (defaults to `os.homedir()`). */
+    homedir?: string;
+};
+/**
+ * Resolve the helper binary path. Search order (documented in the README's
+ * macOS Target section):
+ *   1. `PROWL_MACDRIVER_BIN` env override (absolute path to the binary);
+ *   2. the user-level install of the pinned version at
+ *      `~/.prowl/macdriver/<MACDRIVER_VERSION>/prowl-macdriver`
+ *      (what `prowl macdriver install` writes);
+ *   3. the contributor's repo-local source build under `macdriver/.build/`
+ *      (`release` then `debug`).
+ * Throws with install-first guidance when none is found.
+ */
+declare function resolveHelperBinary(env?: NodeJS.ProcessEnv, options?: ResolveHelperOptions): string;
 /** Default per-request deadline for the helper transport. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 type SpawnMacHelperOptions = {
@@ -594,6 +646,151 @@ 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>;
 
+/** Minimal shape of the `fetch` responses this module consumes. */
+interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+/** A `fetch`-like function; the real global `fetch` satisfies it. */
+type FetchLike$2 = (url: string, init?: {
+    redirect?: "follow" | "error" | "manual";
+}) => Promise<FetchResponseLike>;
+/** Extracts the binary out of a downloaded zip into `destDir`. */
+type Extractor = (zipPath: string, destDir: string) => Promise<void>;
+/** Lists the raw path entries in a downloaded zip before extraction. */
+type ArchiveLister = (zipPath: string) => Promise<string[]>;
+/** Verifies the code signature of an installed binary; throws if invalid. */
+type SignatureVerifier = (binaryPath: string) => Promise<void>;
+interface CommandResult {
+    stdout?: string | Buffer;
+    stderr?: string | Buffer;
+}
+type CommandRunner = (file: string, args: string[]) => Promise<CommandResult>;
+/** Parse the hex digest out of a `shasum`-style `.sha256` file. */
+declare function parseChecksumFile(text: string): string;
+/** SHA-256 of a buffer, lowercase hex. */
+declare function sha256Hex(bytes: Buffer): string;
+/** Default archive lister: `zipinfo -1`, used before any extraction happens. */
+declare const zipinfoArchiveLister: ArchiveLister;
+/** Validate the zip member list before extraction. */
+declare function validateMacdriverArchiveEntries(entries: string[]): void;
+/** Default extractor: Apple's `ditto`, which preserves the code signature. */
+declare const dittoExtractor: Extractor;
+interface CodesignDetails {
+    identifier: string | null;
+    authorities: string[];
+    teamIdentifier: string | null;
+}
+declare function parseCodesignDetails(text: string): CodesignDetails;
+declare function verifyMacdriverSignature(binaryPath: string, run?: CommandRunner): Promise<void>;
+/**
+ * Default signature verifier: fail closed unless `codesign` verifies the
+ * signature, the identity matches the release contract, and Gatekeeper accepts
+ * the executable through `spctl --assess --type execute`.
+ */
+declare const codesignVerifier: SignatureVerifier;
+interface DownloadOptions {
+    version?: string;
+    fetchImpl?: FetchLike$2;
+}
+/**
+ * Download the pinned release's universal-binary zip and verify its SHA-256
+ * against the released `.sha256` sidecar. Returns the verified zip bytes.
+ * Throws a clear, actionable error on a 404 (no release cut yet) or a checksum
+ * mismatch.
+ */
+declare function downloadAndVerify(options?: DownloadOptions): Promise<Buffer>;
+interface InstallOptions {
+    version?: string;
+    force?: boolean;
+    homedir?: string;
+    fetchImpl?: FetchLike$2;
+    listArchiveEntries?: ArchiveLister;
+    extract?: Extractor;
+    verifySignature?: SignatureVerifier;
+}
+interface InstallResult {
+    version: string;
+    binaryPath: string;
+    alreadyInstalled: boolean;
+}
+/**
+ * Install the pinned helper to `~/.prowl/macdriver/<version>/prowl-macdriver`
+ * (0755). Returns `alreadyInstalled: true` (a no-op) when the binary is already
+ * present and `force` is not set. The downloaded archive is inspected before
+ * extraction, extracted into a temporary staging directory, and moved into place
+ * only after the staged helper passes file and signature verification.
+ */
+declare function installMacdriver(options?: InstallOptions): Promise<InstallResult>;
+interface InstalledVersion {
+    version: string;
+    binaryPath: string;
+}
+interface MacdriverStatus {
+    /** The binary Prowl would use now, and how it was found. */
+    resolved: {
+        path: string;
+        source: "env" | "user-install" | "source-build";
+    } | null;
+    /** The pinned version the CLI targets. */
+    pinnedVersion: string;
+    /** All versions found under `~/.prowl/macdriver/`. */
+    installed: InstalledVersion[];
+    /** Version string the resolved binary reports, or null if it couldn't run. */
+    probedVersion: string | null;
+}
+/** Probe a helper binary's `version` output; null if it can't be run/parsed. */
+type VersionProbe = (binaryPath: string) => Promise<string | null>;
+/** Default probe: run `<binary> version` and parse the `prowl-macdriver X.Y.Z` line. */
+declare const runVersionProbe: VersionProbe;
+interface StatusOptions {
+    env?: NodeJS.ProcessEnv;
+    homedir?: string;
+    probe?: VersionProbe;
+}
+/**
+ * Gather the state `prowl macdriver status` reports: the resolved binary and
+ * how it was found, every installed version, and the resolved binary's probed
+ * version. Pure aside from filesystem reads and the (injectable) probe.
+ */
+declare function collectMacdriverStatus(options?: StatusOptions): Promise<MacdriverStatus>;
+/** Static TCC-permission guidance printed after install / in status. */
+declare function tccGuidance(): string;
+
+/** Screen dimensions in device points, as reported by the agent. */
+interface ScreenSize {
+    width: number;
+    height: number;
+}
+/** One item in a W3C `pointer` action sequence. */
+type PointerActionItem = {
+    type: "pointerMove";
+    duration: number;
+    x: number;
+    y: number;
+    origin?: "viewport";
+} | {
+    type: "pointerDown";
+    button: number;
+} | {
+    type: "pointerUp";
+    button: number;
+} | {
+    type: "pause";
+    duration: number;
+};
+/** A single `touch` pointer input source and its ordered actions. */
+interface PointerActionSequence {
+    type: "pointer";
+    id: string;
+    parameters: {
+        pointerType: "touch";
+    };
+    actions: PointerActionItem[];
+}
+
 /** The selector kinds the native dialect understands. */
 type NativeSelectorKind = "id" | "label" | "text" | "role" | "focused";
 /**
@@ -811,6 +1008,10 @@ interface AndroidAgentClient {
     getText(elementId: string): Promise<string | null>;
     /** Dispatch a global key event by Android key code (goes to the focused view). */
     pressKeyCode(keyCode: number): Promise<void>;
+    /** Current screen size in pixels (uiautomator2 `/window/current/size`), for gestures. */
+    windowSize(): Promise<ScreenSize>;
+    /** Perform a W3C pointer action sequence (`POST /session/:id/actions`). */
+    performActions(actions: PointerActionSequence): Promise<void>;
     /** Capture the current screen as PNG bytes. */
     screenshotPng(): Promise<Buffer>;
     /**
@@ -1054,10 +1255,16 @@ interface IosAgentClient {
     /** Replace an element's text (W3C `element/value`). */
     setValue(elementId: string, text: string): Promise<void>;
     getText(elementId: string): Promise<string | null>;
+    /** True only when WDA reports the element is displayed in the current viewport. */
+    isDisplayed(elementId: string): Promise<boolean>;
     /** Send raw key sequences to the focused element (WDA `/wda/keys`). */
     sendKeys(keys: string[]): Promise<void>;
     /** Return to the springboard home screen (WDA `/wda/homescreen`). */
     homescreen(): Promise<void>;
+    /** Current screen size in points (WDA `/window/size`), for gesture geometry. */
+    windowSize(): Promise<ScreenSize>;
+    /** Perform a W3C pointer action sequence (WDA `POST /session/:id/actions`). */
+    performActions(actions: PointerActionSequence): Promise<void>;
     /**
      * Return the current UI hierarchy as WebDriverAgent `/source` XML. Present on
      * live clients and consumed by the analyzer (PROWL-061); optional so lighter
@@ -1359,7 +1566,9 @@ declare function createWdaAgentClient(transport: WdaTransport, sessionId: string
  * 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.
+ * `hover`, `scrollTo`, `waitForSelector`) is portable across targets. The
+ * directional `scroll` step is the one per-target exception — see
+ * {@link MACOS_UNSUPPORTED_STEP_TYPES}.
  */
 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. */
@@ -1367,8 +1576,10 @@ 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; every native target (macOS,
- * Android, iOS) rejects the same web-only step vocabulary.
+ * hunt itself runs. No-op for the web target; every native target rejects the
+ * same web-only step vocabulary, and macOS additionally rejects the directional
+ * `scroll` swipe (no AX equivalent) — but NOT `scrollTo`, which macOS maps to
+ * AXScrollToVisible just as iOS/Android map it to a swipe loop.
  */
 declare function assertStepsSupportedByTarget(steps: Step[], target: Target["type"]): void;
 /** Read the bundle id from an iOS `.app` (root `Info.plist`), or null. */
@@ -1705,24 +1916,24 @@ declare const configSchema: z.ZodObject<{
         }>]>>;
     }, "strip", z.ZodTypeAny, {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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;
-    }, {
-        timeout?: number | undefined;
         headless?: boolean | undefined;
         slowMo?: number | undefined;
         engine?: "chromium" | "firefox" | "webkit" | undefined;
         channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
+    }, {
+        timeout?: number | undefined;
         viewport?: "mobile" | "tablet" | "desktop" | {
             width: number;
             height: number;
         } | undefined;
+        headless?: boolean | undefined;
+        slowMo?: number | undefined;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     }>>;
     artifacts: z.ZodOptional<z.ZodObject<{
         screenshots: z.ZodOptional<z.ZodEnum<["on-failure", "all"]>>;
@@ -1836,14 +2047,14 @@ declare const configSchema: z.ZodObject<{
     };
     browser?: {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     } | undefined;
     artifacts?: {
         screenshots?: "on-failure" | "all" | undefined;
@@ -1901,14 +2112,14 @@ declare const configSchema: z.ZodObject<{
     };
     browser?: {
         timeout?: number | undefined;
-        headless?: boolean | undefined;
-        slowMo?: 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;
+        engine?: "chromium" | "firefox" | "webkit" | undefined;
+        channel?: "chromium" | "chrome" | "chrome-beta" | "chrome-canary" | "chrome-dev" | "msedge" | "msedge-beta" | "msedge-canary" | "msedge-dev" | undefined;
     } | undefined;
     artifacts?: {
         screenshots?: "on-failure" | "all" | undefined;
@@ -2454,4 +2665,4 @@ type GenerateOptions = {
 };
 declare function generateHunt(options: GenerateOptions): Promise<string>;
 
-export { ANDROID_INTERACTIVE_CLASSES, ANDROID_KEYCODES, ANDROID_MATCH_DIALECT, type AdbDevice, type AdbResult, type AdbRunner, type AdbSpawner, type AgentApks, type AgentConnector, type AnalysisResult, type AnalyzeAndroidOptions, type AnalyzeIosOptions, type AnalyzeMacOptions, type AndroidAgentClient, type AndroidAnalysisElement, type AndroidAnalysisResult, type AndroidDriverOptions, type AndroidLocator, type AndroidQuery, type AndroidSession, type AndroidTarget, type AndroidUiNode, type AndroidUiSource, 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_AGENT_REQUEST_TIMEOUT_MS, DEFAULT_ANALYZE_TREE_DEPTH, DEFAULT_FLAKY_THRESHOLD, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SIMULATOR_LOCK_ROOT, DEFAULT_WDA_REQUEST_TIMEOUT_MS, type EvalScriptStep, type FailureCluster, type FetchLike$1 as FetchLike, type FlakyScore, type GenerateOptions, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, INTERACTIVE_ROLES, IOS_INTERACTIVE_TYPES, IOS_MATCH_DIALECT, IOS_PRESS_KEYS, IOS_WINDOW_TYPE, type IfStep, type IosAgentClient, type IosAgentConnector, type IosAnalysisElement, type IosAnalysisResult, type IosAnalysisWindow, type IosDriverOptions, type IosLocator, type IosQuery, type IosSession, type IosTarget, type IosUiNode, type IosUiSource, type LaunchAndroidOptions, type LaunchIosOptions, type LaunchMacOptions, MACOS_MATCH_DIALECT, type MacAnalysisElement, type MacAnalysisResult, type MacAnalysisWindow, type MacAxNode, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacosTarget, type MockRouteStep, NATIVE_ATTRIBUTE_MAP, type NativeMatchDialect, type NativeMatchOptions, type NativeNode, type NativePlatform, type NativeRankFields, type NativeSelector, type NativeSelectorKind, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type ReserveSimulatorOptions, type ResolveWdaTestRunOptions, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, type SelectorKindMapping, type SimDevice, type SimctlResult, type SimctlRunner, type SimulatorReservation, SpawnMacHelperClient, type SpawnMacHelperOptions, type Step, type StepResult, type Target, UIA2_REMOTE_PORT, Uia2HttpError, Uia2Transport, type Uia2TransportOptions, type UnmockRouteStep, type UpdateBacklogOptions, type Viewport, WDA_RUNNER_BUNDLE_ID, WDA_USE_PORT_ENV, WEB_ONLY_STEP_TYPES, WdaHttpError, type WdaTestRunPreparer, WdaTransport, type WdaTransportOptions, type WebTarget, type XmlElement, analyzeAndroidApp, analyzeIosApp, analyzeMacApp, analyzePage, androidAppAllowedIdentities, androidNodeToNative, androidQueryToLocator, assertAndroidAppAllowed, assertIosAppAllowed, assertStepsSupportedByTarget, assertTargetAppAllowed, bootedDevices, bootedSimulators, buildHealCandidates, closeAndroidSession, closeIosSession, closeMacSession, clusterFailures, computeFlakeScore, configSchema, createAndroidDriver, createIosDriver, createMacDriver, createUia2AgentClient, createUia2Session, createWdaAgentClient, createWdaSession, decodeXmlEntities, defaultAgentConnector, defaultIosAgentConnector, defaultWdaTestRunPreparer, escapePredicateArg, escapeUiSelectorArg, extractElementId, extractFailures, extractSelectorIntent, findFreePort, generateHunt, healSelector, huntSchema, injectUsePortIntoXctestrun, interpolateHunt, iosAppAllowedIdentities, iosNodeToNative, iosQueryToLocator, isAndroidInteractive, isIosInteractive, launchAndroidSession, launchIosSession, launchMacSession, listDevices, listHunts, listSimulators, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverBuildInstructions, matchAndroidSelector, matchIosSelector, matchNativeTree, nodeMatchesSelector, normalizeXcuiClassName, parseAaptPackage, parseAdbDevices, parseAndroidHierarchy, parseAndroidSelector, parseForwardPort, parseIosHierarchy, parseIosSelector, parseMacSelector, parseNativeSelector, parseSimctlDevices, parseSnapshot, parseXcodeVersion, parseXml, qualifyResourceId, quoteSelectorValue, rankAndroidSelectors, rankFlaky, rankIosSelectors, rankMacSelectors, rankNativeSelectors, readHistory, readHuntHistory, readIosBundleIdentifier, reserveSimulatorUdid, resolveAgentApks, resolveHelperBinary, resolveWdaProject, resolveWdaTestRun, runHunt, runSuite, selectDeviceSerial, selectSimulatorUdid, shortIosType, stepSchema, unquoteSelectorValue, unwrapAndroidTextSelector, unwrapIosTextSelector, unwrapNativeTextSelector, updateBacklogFromSuite, waitForAgentReady, waitForWdaReady, wdaCacheDir, wdaTestRunArgs, webOnlyReason };
+export { ANDROID_INTERACTIVE_CLASSES, ANDROID_KEYCODES, ANDROID_MATCH_DIALECT, type AdbDevice, type AdbResult, type AdbRunner, type AdbSpawner, type AgentApks, type AgentConnector, type AnalysisResult, type AnalyzeAndroidOptions, type AnalyzeIosOptions, type AnalyzeMacOptions, type AndroidAgentClient, type AndroidAnalysisElement, type AndroidAnalysisResult, type AndroidDriverOptions, type AndroidLocator, type AndroidQuery, type AndroidSession, type AndroidTarget, type AndroidUiNode, type AndroidUiSource, type ArchiveLister, 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 CodesignDetails, type CommandResult, type CommandRunner, type Config, DEFAULT_AGENT_REQUEST_TIMEOUT_MS, DEFAULT_ANALYZE_TREE_DEPTH, DEFAULT_FLAKY_THRESHOLD, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SIMULATOR_LOCK_ROOT, DEFAULT_WDA_REQUEST_TIMEOUT_MS, type DownloadOptions, type EvalScriptStep, type Extractor, type FailureCluster, type FetchLike$1 as FetchLike, type FlakyScore, type GenerateOptions, HELPER_BINARY, type HealResult, type HistoryEntry, type HistoryFile, type Hunt, INTERACTIVE_ROLES, IOS_INTERACTIVE_TYPES, IOS_MATCH_DIALECT, IOS_PRESS_KEYS, IOS_WINDOW_TYPE, type IfStep, type InstallOptions, type InstallResult, type InstalledVersion, type IosAgentClient, type IosAgentConnector, type IosAnalysisElement, type IosAnalysisResult, type IosAnalysisWindow, type IosDriverOptions, type IosLocator, type IosQuery, type IosSession, type IosTarget, type IosUiNode, type IosUiSource, type LaunchAndroidOptions, type LaunchIosOptions, type LaunchMacOptions, MACDRIVER_REPO, MACDRIVER_SIGNING_AUTHORITY_PREFIX, MACDRIVER_SIGNING_IDENTIFIER, MACDRIVER_VERSION, MACDRIVER_VERSION_PATTERN, MACOS_MATCH_DIALECT, type MacAnalysisElement, type MacAnalysisResult, type MacAnalysisWindow, type MacAxNode, type MacDriverOptions, type MacHelperClient, type MacQuery, type MacSession, type MacdriverStatus, type MacosTarget, type MockRouteStep, NATIVE_ATTRIBUTE_MAP, type NativeMatchDialect, type NativeMatchOptions, type NativeNode, type NativePlatform, type NativeRankFields, type NativeSelector, type NativeSelectorKind, type PageElement, type PageForm, type PageLink, type RankFlakyOptions, type ReliabilityConfig, type RepeatStep, type ReserveSimulatorOptions, type ResolveHelperOptions, type ResolveWdaTestRunOptions, type RunArtifacts, type RunOptions, type RunResult, type RunScriptStep, type RunSuiteHooks, type RunSuiteOptions, type RunSuiteResult, type SelectorKindMapping, type SignatureVerifier, type SimDevice, type SimctlResult, type SimctlRunner, type SimulatorReservation, SpawnMacHelperClient, type SpawnMacHelperOptions, type StatusOptions, type Step, type StepResult, type Target, UIA2_REMOTE_PORT, Uia2HttpError, Uia2Transport, type Uia2TransportOptions, type UnmockRouteStep, type UpdateBacklogOptions, type VersionProbe, type Viewport, WDA_RUNNER_BUNDLE_ID, WDA_USE_PORT_ENV, WEB_ONLY_STEP_TYPES, WdaHttpError, type WdaTestRunPreparer, WdaTransport, type WdaTransportOptions, type WebTarget, type XmlElement, analyzeAndroidApp, analyzeIosApp, analyzeMacApp, analyzePage, androidAppAllowedIdentities, androidNodeToNative, androidQueryToLocator, assertAndroidAppAllowed, assertIosAppAllowed, assertStepsSupportedByTarget, assertTargetAppAllowed, bootedDevices, bootedSimulators, buildHealCandidates, closeAndroidSession, closeIosSession, closeMacSession, clusterFailures, codesignVerifier, collectMacdriverStatus, computeFlakeScore, configSchema, createAndroidDriver, createIosDriver, createMacDriver, createUia2AgentClient, createUia2Session, createWdaAgentClient, createWdaSession, decodeXmlEntities, defaultAgentConnector, defaultIosAgentConnector, defaultWdaTestRunPreparer, dittoExtractor, downloadAndVerify, escapePredicateArg, escapeUiSelectorArg, extractElementId, extractFailures, extractSelectorIntent, findFreePort, generateHunt, healSelector, huntSchema, injectUsePortIntoXctestrun, installMacdriver, interpolateHunt, iosAppAllowedIdentities, iosNodeToNative, iosQueryToLocator, isAndroidInteractive, isIosInteractive, launchAndroidSession, launchIosSession, launchMacSession, listDevices, listHunts, listSimulators, loadConfig, loadHunt, loadHuntMeta, loadHuntTags, macdriverAssetName, macdriverAssetUrl, macdriverBuildInstructions, macdriverChecksumName, macdriverInstallRoot, macdriverInstalledBinary, macdriverReleaseTag, macdriverVersionDir, matchAndroidSelector, matchIosSelector, matchNativeTree, nodeMatchesSelector, normalizeXcuiClassName, parseAaptPackage, parseAdbDevices, parseAndroidHierarchy, parseAndroidSelector, parseChecksumFile, parseCodesignDetails, parseForwardPort, parseIosHierarchy, parseIosSelector, parseMacSelector, parseNativeSelector, parseSimctlDevices, parseSnapshot, parseXcodeVersion, parseXml, qualifyResourceId, quoteSelectorValue, rankAndroidSelectors, rankFlaky, rankIosSelectors, rankMacSelectors, rankNativeSelectors, readHistory, readHuntHistory, readIosBundleIdentifier, reserveSimulatorUdid, resolveAgentApks, resolveHelperBinary, resolveWdaProject, resolveWdaTestRun, runHunt, runSuite, runVersionProbe, selectDeviceSerial, selectSimulatorUdid, sha256Hex, shortIosType, stepSchema, tccGuidance, unquoteSelectorValue, unwrapAndroidTextSelector, unwrapIosTextSelector, unwrapNativeTextSelector, updateBacklogFromSuite, validateMacdriverArchiveEntries, validateMacdriverVersion, verifyMacdriverSignature, waitForAgentReady, waitForWdaReady, wdaCacheDir, wdaTestRunArgs, webOnlyReason, zipinfoArchiveLister };

package/dist/lib.js

@@ -8,11 +8,17 @@ import {
   DEFAULT_REQUEST_TIMEOUT_MS,
   DEFAULT_SIMULATOR_LOCK_ROOT,
   DEFAULT_WDA_REQUEST_TIMEOUT_MS,
+  HELPER_BINARY,
   INTERACTIVE_ROLES,
   IOS_INTERACTIVE_TYPES,
   IOS_MATCH_DIALECT,
   IOS_PRESS_KEYS,
   IOS_WINDOW_TYPE,
+  MACDRIVER_REPO,
+  MACDRIVER_SIGNING_AUTHORITY_PREFIX,
+  MACDRIVER_SIGNING_IDENTIFIER,
+  MACDRIVER_VERSION,
+  MACDRIVER_VERSION_PATTERN,
   MACOS_MATCH_DIALECT,
   NATIVE_ATTRIBUTE_MAP,
   SpawnMacHelperClient,
@@ -42,6 +48,8 @@ import {
   closeIosSession,
   closeMacSession,
   clusterFailures,
+  codesignVerifier,
+  collectMacdriverStatus,
   computeFlakeScore,
   createAndroidDriver,
   createIosDriver,
@@ -54,6 +62,8 @@ import {
   defaultAgentConnector,
   defaultIosAgentConnector,
   defaultWdaTestRunPreparer,
+  dittoExtractor,
+  downloadAndVerify,
   escapePredicateArg,
   escapeUiSelectorArg,
   extractElementId,
@@ -63,7 +73,7 @@ import {
   generateHunt,
   healSelector,
   injectUsePortIntoXctestrun,
-  interpolateHunt,
+  installMacdriver,
   iosAppAllowedIdentities,
   iosNodeToNative,
   iosQueryToLocator,
@@ -74,7 +84,14 @@ import {
   launchMacSession,
   listDevices,
   listSimulators,
+  macdriverAssetName,
+  macdriverAssetUrl,
   macdriverBuildInstructions,
+  macdriverChecksumName,
+  macdriverInstallRoot,
+  macdriverInstalledBinary,
+  macdriverReleaseTag,
+  macdriverVersionDir,
   matchAndroidSelector,
   matchIosSelector,
   matchNativeTree,
@@ -84,6 +101,8 @@ import {
   parseAdbDevices,
   parseAndroidHierarchy,
   parseAndroidSelector,
+  parseChecksumFile,
+  parseCodesignDetails,
   parseForwardPort,
   parseIosHierarchy,
   parseIosSelector,
@@ -110,30 +129,38 @@ import {
   resolveWdaTestRun,
   runHunt,
   runSuite,
+  runVersionProbe,
   selectDeviceSerial,
   selectSimulatorUdid,
+  sha256Hex,
   shortIosType,
+  tccGuidance,
   unquoteSelectorValue,
   unwrapAndroidTextSelector,
   unwrapIosTextSelector,
   unwrapNativeTextSelector,
   updateBacklogFromSuite,
+  validateMacdriverArchiveEntries,
+  validateMacdriverVersion,
+  verifyMacdriverSignature,
   waitForAgentReady,
   waitForWdaReady,
   wdaCacheDir,
   wdaTestRunArgs,
-  webOnlyReason
-} from "./chunk-5KQR3IR3.js";
+  webOnlyReason,
+  zipinfoArchiveLister
+} from "./chunk-CWLRDV5P.js";
 import {
   configSchema,
   huntSchema,
+  interpolateHunt,
   listHunts,
   loadConfig,
   loadHunt,
   loadHuntMeta,
   loadHuntTags,
   stepSchema
-} from "./chunk-WHAMB4TY.js";
+} from "./chunk-JFJQNJSJ.js";
 export {
   ANDROID_INTERACTIVE_CLASSES,
   ANDROID_KEYCODES,
@@ -144,11 +171,17 @@ export {
   DEFAULT_REQUEST_TIMEOUT_MS,
   DEFAULT_SIMULATOR_LOCK_ROOT,
   DEFAULT_WDA_REQUEST_TIMEOUT_MS,
+  HELPER_BINARY,
   INTERACTIVE_ROLES,
   IOS_INTERACTIVE_TYPES,
   IOS_MATCH_DIALECT,
   IOS_PRESS_KEYS,
   IOS_WINDOW_TYPE,
+  MACDRIVER_REPO,
+  MACDRIVER_SIGNING_AUTHORITY_PREFIX,
+  MACDRIVER_SIGNING_IDENTIFIER,
+  MACDRIVER_VERSION,
+  MACDRIVER_VERSION_PATTERN,
   MACOS_MATCH_DIALECT,
   NATIVE_ATTRIBUTE_MAP,
   SpawnMacHelperClient,
@@ -178,6 +211,8 @@ export {
   closeIosSession,
   closeMacSession,
   clusterFailures,
+  codesignVerifier,
+  collectMacdriverStatus,
   computeFlakeScore,
   configSchema,
   createAndroidDriver,
@@ -191,6 +226,8 @@ export {
   defaultAgentConnector,
   defaultIosAgentConnector,
   defaultWdaTestRunPreparer,
+  dittoExtractor,
+  downloadAndVerify,
   escapePredicateArg,
   escapeUiSelectorArg,
   extractElementId,
@@ -201,6 +238,7 @@ export {
   healSelector,
   huntSchema,
   injectUsePortIntoXctestrun,
+  installMacdriver,
   interpolateHunt,
   iosAppAllowedIdentities,
   iosNodeToNative,
@@ -217,7 +255,14 @@ export {
   loadHunt,
   loadHuntMeta,
   loadHuntTags,
+  macdriverAssetName,
+  macdriverAssetUrl,
   macdriverBuildInstructions,
+  macdriverChecksumName,
+  macdriverInstallRoot,
+  macdriverInstalledBinary,
+  macdriverReleaseTag,
+  macdriverVersionDir,
   matchAndroidSelector,
   matchIosSelector,
   matchNativeTree,
@@ -227,6 +272,8 @@ export {
   parseAdbDevices,
   parseAndroidHierarchy,
   parseAndroidSelector,
+  parseChecksumFile,
+  parseCodesignDetails,
   parseForwardPort,
   parseIosHierarchy,
   parseIosSelector,
@@ -253,19 +300,26 @@ export {
   resolveWdaTestRun,
   runHunt,
   runSuite,
+  runVersionProbe,
   selectDeviceSerial,
   selectSimulatorUdid,
+  sha256Hex,
   shortIosType,
   stepSchema,
+  tccGuidance,
   unquoteSelectorValue,
   unwrapAndroidTextSelector,
   unwrapIosTextSelector,
   unwrapNativeTextSelector,
   updateBacklogFromSuite,
+  validateMacdriverArchiveEntries,
+  validateMacdriverVersion,
+  verifyMacdriverSignature,
   waitForAgentReady,
   waitForWdaReady,
   wdaCacheDir,
   wdaTestRunArgs,
-  webOnlyReason
+  webOnlyReason,
+  zipinfoArchiveLister
 };
 //# sourceMappingURL=lib.js.map

package/dist/{loader-PBBYV3U7.js → loader-JTHA4BYG.js}

@@ -10,7 +10,7 @@ import {
   loadHuntTags,
   resolveViewport,
   warnLegacyConfigDir
-} from "./chunk-WHAMB4TY.js";
+} from "./chunk-JFJQNJSJ.js";
 export {
   CONFIG_DIR,
   LEGACY_CONFIG_DIR,
@@ -24,4 +24,4 @@ export {
   resolveViewport,
   warnLegacyConfigDir
 };
-//# sourceMappingURL=loader-PBBYV3U7.js.map
+//# sourceMappingURL=loader-JTHA4BYG.js.map

package/examples/hunts/hello.yml

@@ -5,7 +5,7 @@
 #
 # Run it:  prowl run hello
 #
-# Browse more hunt templates at https://hub.prowl.tools
+# See .prowl/hunts/login-flow.yml for a fuller example (auth, secrets, assertions).
 
 name: hello
 description: Verify the target app loads successfully

package/examples/hunts/login-flow.yml

@@ -0,0 +1,58 @@
+# Login Flow
+# ---
+# Pattern: Authentication — email/password login with redirect verification
+# What it tests: Fill credentials, submit, verify redirect to dashboard.
+# Customize:
+#   - Update the selectors and URL paths to match your app's login page
+#   - Store credentials in .prowl/.env and reference them with {{VAR}}
+#
+# Tip: Use `prowl login` to capture auth state so other hunts can skip login.
+
+name: login-flow
+description: Log in with email and password, verify redirect to dashboard
+
+tags:
+  - auth
+  - login
+  - credentials
+
+# Store secrets in .prowl/.env — they'll be redacted in reports automatically.
+# Example .env:
+#   TEST_EMAIL=user@example.com
+#   TEST_PASSWORD=secret123
+vars:
+  EMAIL: "{{TEST_EMAIL}}"
+  PASSWORD: "{{TEST_PASSWORD}}"
+
+steps:
+  - navigate: "/login"
+
+  # Shorthand fill — Prowl finds the input by its label or placeholder text.
+  # Equivalent explicit form:
+  #   fill:
+  #     selector: "input[placeholder='Email']"
+  #     value: "{{EMAIL}}"
+  - fill:
+      "Email": "{{EMAIL}}"
+
+  - fill:
+      "Password": "{{PASSWORD}}"
+
+  # Shorthand click — Prowl finds a button by its text content.
+  # Equivalent explicit form:
+  #   click:
+  #     selector: "button:has-text('Sign In')"
+  - click: "Sign In"
+
+  # Wait for navigation to complete after login
+  - waitForUrl:
+      value: "/dashboard"
+      timeout: 10000
+
+  # Mid-flow assertion — verify the dashboard loaded
+  - assert:
+      visible: "Dashboard"
+
+assertions:
+  - urlIncludes: "/dashboard"
+  - noConsoleErrors: true