prowl-tools 0.1.8 → 0.1.10

package/dist/lib.d.cts

@@ -115,6 +115,12 @@ type HistoryEntry = {
     durationMs: number;
     startedAt: string;
     runDir?: string;
+    /**
+     * Number of retry attempts beyond the first for this run (PROWL-033). Absent or
+     * `0` when the run did not retry — kept optional so older `history.json` files and
+     * runs of hunts without a `retry` block keep parsing unchanged.
+     */
+    retries?: number;
 };
 type HistoryFile = {
     entries: HistoryEntry[];
@@ -177,6 +183,13 @@ type WaitForNetworkIdleStep = {
         timeout?: number;
     };
 };
+type WaitForResponseStep = {
+    waitForResponse: {
+        url: string;
+        status?: number;
+        timeout?: number;
+    };
+};
 type SelectOptionStep = {
     selectOption: {
         selector: string;
@@ -299,7 +312,7 @@ type AssertScreenshotStep = {
 type AssertWithAiStep = {
     assertWithAI: string;
 };
-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 | AssertWithAiStep | CopyTextStep | WaitForDownloadStep;
+type Step = NavigateStep | ClickStep | FillStep | TypeStep | PressStep | WaitStep | SelectOptionStep | SelectStep | OnDialogStep | SetInputFilesStep | InlineAssertStep | RunHuntStep | WaitForSelectorStep | WaitForUrlStep | WaitForNetworkIdleStep | WaitForResponseStep | HoverStep | ScrollStep | ScrollToStep | ScreenshotStep | IfStep | RepeatStep | MockRouteStep | UnmockRouteStep | EvalScriptStep | RunScriptStep | AssertScreenshotStep | AssertWithAiStep | CopyTextStep | WaitForDownloadStep;
 type Assertion = {
     selectorExists: string;
 } | {
@@ -344,6 +357,25 @@ type TraceCorrelation = {
     traceId: string;
     header: string;
 };
+/**
+ * One attempt of a retried hunt (PROWL-033). Recorded per attempt so a passed-on-retry
+ * run keeps the reason each earlier attempt failed, helping tell a flaky test apart from
+ * a slow environment or a real regression.
+ */
+type RetryAttempt = {
+    /** 1-based attempt number (attempt 1 is the initial run). */
+    attempt: number;
+    status: "pass" | "fail";
+    durationMs: number;
+    /** The first failing step on this attempt; absent when the attempt passed. */
+    failedStep?: {
+        /** 0-based index into the hunt's steps. */
+        index: number;
+        type: string;
+    };
+    /** Failure reason for this attempt; absent when it passed. */
+    error?: string;
+};
 type RunResult = {
     status: "pass" | "fail";
     exitCode: 0 | 1;
@@ -355,6 +387,17 @@ type RunResult = {
     assertions: AssertionResult[];
     artifacts: RunArtifacts;
     traceCorrelations?: TraceCorrelation[];
+    /**
+     * Per-attempt diagnostics (PROWL-033), present only when the hunt used `retry` and
+     * more than one attempt ran. Absent when no retry occurred so existing consumers and
+     * older run artifacts keep parsing. The last entry always matches the final result.
+     */
+    retryHistory?: RetryAttempt[];
+    /**
+     * Human-readable one-line retry outcome (PROWL-033), e.g. "Passed on attempt 2 of 3
+     * — first failure: navigate (timeout)". Present only alongside `retryHistory`.
+     */
+    retrySummary?: string;
 };
 type CiHuntResult = {
     hunt: string;
@@ -477,6 +520,10 @@ interface SessionDriver {
     waitForNetworkIdle(options?: {
         timeout?: number;
     }): Promise<void>;
+    /** Resolve once a network response satisfies `predicate`, or reject on timeout. */
+    waitForResponse(predicate: (response: DriverResponse) => boolean, 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;
@@ -605,15 +652,38 @@ type ResolveHelperOptions = {
 declare function resolveHelperBinary(env?: NodeJS.ProcessEnv, options?: ResolveHelperOptions): string;
 /** Default per-request deadline for the helper transport. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * A server-initiated event line from the helper (ARCH-008): a JSON object with
+ * an `event` discriminant and **no** `id`, so it is unambiguously distinct from
+ * an id-matched command response. Emitted, for example, when an AXObserver
+ * notification fires during a `waitFor`/`openMenu` wait.
+ */
+type MacHelperEvent = Record<string, unknown> & {
+    event: string;
+};
 type SpawnMacHelperOptions = {
     /** Per-request deadline; a request that gets no response by then rejects. */
     requestTimeoutMs?: number;
+    /**
+     * Optional sink for server-initiated event lines. Events are informational —
+     * waits are resolved helper-side by the id-matched response — so they are
+     * forwarded here (if provided) and otherwise dropped, never touching the
+     * pending-request map.
+     */
+    onEvent?: (event: MacHelperEvent) => void;
+    /**
+     * Optional diagnostic sink for event handler failures. Defaults to stderr so a
+     * bad sink is visible without allowing it to break helper transport.
+     */
+    onEventError?: (message: string) => void;
 };
 /** 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 readonly onEvent?;
+    private readonly onEventError;
     private stdoutBuffer;
     private stderrBuffer;
     private nextId;
@@ -622,6 +692,7 @@ declare class SpawnMacHelperClient implements MacHelperClient {
     constructor(binaryPath: string, options?: SpawnMacHelperOptions);
     private onStdout;
     private dispatch;
+    private handleEvent;
     private failAll;
     private recordTerminalFailure;
     /** Number of in-flight requests awaiting a response (for teardown/tests). */

package/dist/lib.d.ts

@@ -115,6 +115,12 @@ type HistoryEntry = {
     durationMs: number;
     startedAt: string;
     runDir?: string;
+    /**
+     * Number of retry attempts beyond the first for this run (PROWL-033). Absent or
+     * `0` when the run did not retry — kept optional so older `history.json` files and
+     * runs of hunts without a `retry` block keep parsing unchanged.
+     */
+    retries?: number;
 };
 type HistoryFile = {
     entries: HistoryEntry[];
@@ -177,6 +183,13 @@ type WaitForNetworkIdleStep = {
         timeout?: number;
     };
 };
+type WaitForResponseStep = {
+    waitForResponse: {
+        url: string;
+        status?: number;
+        timeout?: number;
+    };
+};
 type SelectOptionStep = {
     selectOption: {
         selector: string;
@@ -299,7 +312,7 @@ type AssertScreenshotStep = {
 type AssertWithAiStep = {
     assertWithAI: string;
 };
-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 | AssertWithAiStep | CopyTextStep | WaitForDownloadStep;
+type Step = NavigateStep | ClickStep | FillStep | TypeStep | PressStep | WaitStep | SelectOptionStep | SelectStep | OnDialogStep | SetInputFilesStep | InlineAssertStep | RunHuntStep | WaitForSelectorStep | WaitForUrlStep | WaitForNetworkIdleStep | WaitForResponseStep | HoverStep | ScrollStep | ScrollToStep | ScreenshotStep | IfStep | RepeatStep | MockRouteStep | UnmockRouteStep | EvalScriptStep | RunScriptStep | AssertScreenshotStep | AssertWithAiStep | CopyTextStep | WaitForDownloadStep;
 type Assertion = {
     selectorExists: string;
 } | {
@@ -344,6 +357,25 @@ type TraceCorrelation = {
     traceId: string;
     header: string;
 };
+/**
+ * One attempt of a retried hunt (PROWL-033). Recorded per attempt so a passed-on-retry
+ * run keeps the reason each earlier attempt failed, helping tell a flaky test apart from
+ * a slow environment or a real regression.
+ */
+type RetryAttempt = {
+    /** 1-based attempt number (attempt 1 is the initial run). */
+    attempt: number;
+    status: "pass" | "fail";
+    durationMs: number;
+    /** The first failing step on this attempt; absent when the attempt passed. */
+    failedStep?: {
+        /** 0-based index into the hunt's steps. */
+        index: number;
+        type: string;
+    };
+    /** Failure reason for this attempt; absent when it passed. */
+    error?: string;
+};
 type RunResult = {
     status: "pass" | "fail";
     exitCode: 0 | 1;
@@ -355,6 +387,17 @@ type RunResult = {
     assertions: AssertionResult[];
     artifacts: RunArtifacts;
     traceCorrelations?: TraceCorrelation[];
+    /**
+     * Per-attempt diagnostics (PROWL-033), present only when the hunt used `retry` and
+     * more than one attempt ran. Absent when no retry occurred so existing consumers and
+     * older run artifacts keep parsing. The last entry always matches the final result.
+     */
+    retryHistory?: RetryAttempt[];
+    /**
+     * Human-readable one-line retry outcome (PROWL-033), e.g. "Passed on attempt 2 of 3
+     * — first failure: navigate (timeout)". Present only alongside `retryHistory`.
+     */
+    retrySummary?: string;
 };
 type CiHuntResult = {
     hunt: string;
@@ -477,6 +520,10 @@ interface SessionDriver {
     waitForNetworkIdle(options?: {
         timeout?: number;
     }): Promise<void>;
+    /** Resolve once a network response satisfies `predicate`, or reject on timeout. */
+    waitForResponse(predicate: (response: DriverResponse) => boolean, 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;
@@ -605,15 +652,38 @@ type ResolveHelperOptions = {
 declare function resolveHelperBinary(env?: NodeJS.ProcessEnv, options?: ResolveHelperOptions): string;
 /** Default per-request deadline for the helper transport. */
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * A server-initiated event line from the helper (ARCH-008): a JSON object with
+ * an `event` discriminant and **no** `id`, so it is unambiguously distinct from
+ * an id-matched command response. Emitted, for example, when an AXObserver
+ * notification fires during a `waitFor`/`openMenu` wait.
+ */
+type MacHelperEvent = Record<string, unknown> & {
+    event: string;
+};
 type SpawnMacHelperOptions = {
     /** Per-request deadline; a request that gets no response by then rejects. */
     requestTimeoutMs?: number;
+    /**
+     * Optional sink for server-initiated event lines. Events are informational —
+     * waits are resolved helper-side by the id-matched response — so they are
+     * forwarded here (if provided) and otherwise dropped, never touching the
+     * pending-request map.
+     */
+    onEvent?: (event: MacHelperEvent) => void;
+    /**
+     * Optional diagnostic sink for event handler failures. Defaults to stderr so a
+     * bad sink is visible without allowing it to break helper transport.
+     */
+    onEventError?: (message: string) => void;
 };
 /** 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 readonly onEvent?;
+    private readonly onEventError;
     private stdoutBuffer;
     private stderrBuffer;
     private nextId;
@@ -622,6 +692,7 @@ declare class SpawnMacHelperClient implements MacHelperClient {
     constructor(binaryPath: string, options?: SpawnMacHelperOptions);
     private onStdout;
     private dispatch;
+    private handleEvent;
     private failAll;
     private recordTerminalFailure;
     /** Number of in-flight requests awaiting a response (for teardown/tests). */

package/dist/lib.js

@@ -149,7 +149,7 @@ import {
   wdaTestRunArgs,
   webOnlyReason,
   zipinfoArchiveLister
-} from "./chunk-CWLRDV5P.js";
+} from "./chunk-SRWAF2RI.js";
 import {
   configSchema,
   huntSchema,
@@ -160,7 +160,7 @@ import {
   loadHuntMeta,
   loadHuntTags,
   stepSchema
-} from "./chunk-JFJQNJSJ.js";
+} from "./chunk-TTZ2IL3P.js";
 export {
   ANDROID_INTERACTIVE_CLASSES,
   ANDROID_KEYCODES,

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

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

package/examples/hunts/form.yml

@@ -0,0 +1,53 @@
+# Form Submission
+# ---
+# Pattern: Forms — fill text fields, pick a dropdown option, submit, verify result.
+# What it tests: Complete a form and confirm the success state renders.
+# Customize:
+#   - Point `navigate` at your form's path
+#   - Update the field labels, the dropdown label/option, and the button text
+#     to match your form
+#
+# Tip: Prefer stable selectors — an accessible label or a data-testid — over
+# brittle CSS. Run `prowl analyze` to dump ranked selector candidates for a page.
+
+name: form
+description: Fill and submit a form, verify the success message
+
+tags:
+  - forms
+  - input
+
+steps:
+  - navigate: "/signup"
+
+  # Shorthand fill — Prowl finds the input by its label or placeholder text.
+  # Equivalent explicit form:
+  #   fill:
+  #     selector: "input[name='name']"
+  #     value: "Ada Lovelace"
+  - fill:
+      "Full name": "Ada Lovelace"
+
+  - fill:
+      "Email": "ada@example.com"
+
+  # Shorthand select — finds the <select> by its label and picks the option by
+  # its visible text. Equivalent explicit form:
+  #   selectOption:
+  #     selector: "select[name='plan']"
+  #     value: "Pro"
+  - select:
+      "Plan": "Pro"
+
+  # Shorthand click — Prowl finds a checkbox or button by its text content.
+  - click: "I agree to the terms"
+
+  - click: "Create account"
+
+  # Mid-flow assertion — verify the success state rendered.
+  - assert:
+      visible: "Welcome, Ada"
+
+assertions:
+  - urlIncludes: "/welcome"
+  - noConsoleErrors: true

package/examples/hunts/macos-hello.yml

@@ -0,0 +1,49 @@
+# macOS Hello — Your First Desktop Hunt (Experimental)
+# ---
+# Prowl drives native macOS apps through Apple's Accessibility API, from the same
+# YAML as web hunts. This starter targets TextEdit — present on every Mac — so you
+# can try the desktop target without wiring up your own app first.
+#
+# ── Before this hunt will run ───────────────────────────────────────────────
+# 1. Install the helper:  prowl macdriver install
+#    Until the first signed release ships, `install` returns a 404 — build from
+#    source instead (needs the Swift toolchain / Xcode CLT):
+#       cd macdriver && swift build -c release
+# 2. Grant Accessibility permission to the app hosting your terminal (Terminal,
+#    iTerm, VS Code, …): System Settings → Privacy & Security → Accessibility.
+#    `prowl macdriver status` prints the resolved binary and this guidance.
+# 3. Point .prowl/config.yml at a macOS target — init's default config targets
+#    the web. Replace its `target:` block, and scope the app under guardrails:
+#
+#       target:
+#         type: macos
+#         app: "com.apple.TextEdit"   # bundle id, or an absolute /path/to/App.app
+#       guardrails:
+#         allowedApps:
+#           - "com.apple.TextEdit"
+#
+# The macOS target is EXPERIMENTAL — the selector dialect and step coverage may
+# still change. `navigate`, `waitForUrl`, and other web-only steps are rejected
+# on it; the portable steps below (`type`, `assert: visible`) run on both targets.
+#
+# ── Finding selectors ───────────────────────────────────────────────────────
+# Don't guess selectors — dump them:  prowl analyze --app com.apple.TextEdit
+# It walks the Accessibility tree and prints every element with ranked selector
+# candidates (prefer `id=` — the native analog of data-testid). TextEdit's
+# controls aren't ours, so treat the steps below as a starting point and adjust
+# to what `analyze` reports on your macOS version.
+
+name: macos-hello
+description: Type into TextEdit and verify the text appears (experimental macOS target)
+
+tags:
+  - macos
+  - smoke
+
+steps:
+  # `type` sends keystrokes to the focused element — a fresh TextEdit document.
+  - type: "Hello from Prowl!"
+
+  # Portable assertion — the document's text should now contain what we typed.
+  - assert:
+      visible: "Hello from Prowl!"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prowl-tools",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -59,7 +59,8 @@
     "build": "tsup",
     "lint": "eslint .",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "audit:licenses": "node scripts/audit-licenses.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -83,6 +84,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.57.1",
+    "license-checker-rseidelsohn": "^4.4.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8"