prowl-tools 0.1.8 → 0.1.9

package/dist/lib.d.cts

@@ -605,15 +605,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 +645,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

@@ -605,15 +605,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 +645,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-2RNOK64Y.js";
 import {
   configSchema,
   huntSchema,

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.9",
   "description": "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
   "type": "module",
   "license": "Apache-2.0",