prowl-tools 0.1.3 → 0.1.5

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2026 Michael Tookes
+   Copyright 2026 Genkei Labs
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,5 +1,5 @@
 Prowl
-Copyright (c) 2026 Michael Tookes
+Copyright (c) 2026 Genkei Labs
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 this file except in compliance with the License. You may obtain a copy of the
@@ -12,6 +12,16 @@ attributions are provided for the benefit of downstream users.
 Direct Runtime Dependencies
 -------------------------------------------------------------------------------
 
+appium-uiautomator2-server
+  License: Apache-2.0
+  Copyright (c) Appium Contributors
+  https://github.com/appium/appium-uiautomator2-server
+
+appium-webdriveragent
+  License: Apache-2.0
+  Copyright (c) Appium Contributors
+  https://github.com/appium/WebDriverAgent
+
 chalk
   License: MIT
   https://github.com/chalk/chalk

package/README.md

@@ -55,6 +55,29 @@ Prowl uses Playwright under the hood. Install the browser:
 npx playwright install chromium
 ```
 
+The on-device agents for the experimental Android/iOS targets
+(`appium-uiautomator2-server`, `appium-webdriveragent`) are **optional
+dependencies** — installed by default so mobile testing works out of the box,
+but skippable for a leaner web-only install:
+
+```bash
+npm install -g prowl-tools --omit=optional
+```
+
+If a mobile target later needs an omitted agent, it fails with exact recovery
+commands for global and local installs. For a global npm install, restore the
+agents with:
+
+```bash
+npm install -g appium-uiautomator2-server@10.6.2 appium-webdriveragent@16.4.0
+```
+
+For a local project install, omit `-g`:
+
+```bash
+npm install appium-uiautomator2-server@10.6.2 appium-webdriveragent@16.4.0
+```
+
 ### 2. Initialize
 
 ```bash
@@ -422,15 +445,29 @@ assertions:
 Config lives at `.prowl/config.yml`. All options with defaults:
 
 ```yaml
-# The base URL for all hunt navigation
+# Execution target. Defaults to the web target; existing configs work unchanged.
 target:
-  url: "http://localhost:3000"        # Required
+  type: "web"                         # "web" (default), "macos", "android", or "ios" (experimental)
+  url: "http://localhost:3000"        # Required for web targets
+  # For the experimental macOS target instead:
+  #   type: "macos"
+  #   app: "com.example.App"          # bundle id or /path/to/App.app  (see "macOS Target")
+  # For the experimental Android target instead:
+  #   type: "android"
+  #   app: "com.example.app"          # package name or /path/to/app.apk  (see "Android Target")
+  #   deviceSerial: "emulator-5554"   # optional; required only with several devices attached
+  #   coldStart: false                # optional; pm clear before launch
+  # For the experimental iOS simulator target instead:
+  #   type: "ios"
+  #   app: "com.example.App"          # bundle id or /path/to/App.app  (see "iOS Target")
+  #   udid: "..."                     # optional; required only with several booted simulators
+  #   coldStart: false                # optional; uninstall+reinstall before launch (needs a .app)
 
 # Browser settings
 browser:
   headless: true                       # false = show the browser window
   slowMo: 0                           # ms delay between actions (debugging)
-  timeout: 30000                       # default page operation timeout
+  timeout: 30000                       # default page operation timeout; macOS app launch timeout
 
 # What gets saved per run
 artifacts:
@@ -454,6 +491,7 @@ guardrails:
   forbiddenSelectors:                  # selectors that steps cannot use
     - "[data-danger]"
     - ".delete-btn"
+  allowedApps: []                      # native targets only: macOS bundle IDs/names/.app paths, Android package IDs/canonical APK paths, or iOS bundle IDs/.app paths
 
 # Auth state from `prowl login`
 auth:
@@ -897,6 +935,355 @@ Templates cover auth flows (OAuth, 2FA), e-commerce (Stripe), admin panels, SaaS
 
 ---
 
+## macOS Target (Experimental)
+
+> **Experimental (PROWL-048).** Prowl can drive **native macOS apps** — including
+> menu bar extras (`NSStatusItem` + `NSMenu`) — through Apple's Accessibility API,
+> in addition to the web. The API, selector dialect, and step coverage may change.
+> **Distribution is deferred:** the required helper binary is **not** shipped in the
+> npm package; you build it locally (below).
+
+### Enabling it
+
+1. **Build the helper** (one time; requires the Swift toolchain / Xcode CLT):
+
+   ```bash
+   cd macdriver
+   swift build -c release
+   ```
+
+   Prowl finds the binary at `macdriver/.build/release/prowl-macdriver`, or at
+   `$PROWL_MACDRIVER_BIN` if set. If it is missing, Prowl fails with a clear
+   "build the helper" message rather than crashing.
+
+2. **Point your config at a macOS target:**
+
+   ```yaml
+   target:
+     type: macos
+     app: "com.example.App"        # bundle id, or an absolute /path/to/App.app
+   guardrails:
+     allowedApps:                   # optional scope; empty = allow the target app
+       - "com.example.App"
+   ```
+
+   When `target.app` is an app path, `allowedApps` may list the exact `.app`
+   path, the app bundle name (`Example` for `Example.app`), or the bundle id
+   from `Contents/Info.plist` when that file is readable.
+
+3. **Grant Accessibility permission** (see below), then run a hunt as usual:
+   `prowl run my-macos-hunt`.
+
+### Accessibility & Screen Recording permission
+
+The **process that hosts** Prowl (your terminal — Terminal, iTerm, VS Code, or a CI
+agent) must be granted **Accessibility** permission: **System Settings → Privacy &
+Security → Accessibility**, then enable that app. macOS attributes the grant to the
+hosting app, not to `prowl-macdriver`. Preflight from the helper:
+
+```bash
+macdriver/.build/release/prowl-macdriver check   # prints {"trusted": <bool>}; prompts on first run
+```
+
+The `screenshot`/`assertScreenshot` steps additionally need **Screen Recording**
+permission for the hosting app.
+
+**CI notes (macOS runners):** headless CI cannot click "Allow" in a dialog, so grant
+the permissions non-interactively before the run. On a self-hosted runner you can
+pre-authorize the agent's host app with a TCC profile via MDM, or (on ephemeral
+runners where it's acceptable) seed the TCC database, e.g.:
+
+```bash
+sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" \
+  "INSERT OR REPLACE INTO access VALUES('kTCCServiceAccessibility','<runner-app-bundle-id>',0,2,2,1,NULL,NULL,NULL,'UNUSED',NULL,0,1,NULL,NULL,NULL);"
+```
+
+GitHub-hosted macOS runners do not grant Accessibility, so the macOS target is aimed
+at self-hosted / MDM-managed runners for now.
+
+### Selector dialect (macOS)
+
+Native selectors address accessibility identifiers, roles, and labels:
+
+| Selector | Matches |
+|---|---|
+| `id=openSettings` | element whose `AXIdentifier` equals `openSettings` |
+| `role=button[name="Save"]` | an `AXButton` whose title/description/value contains `Save` |
+| `label="Email"` | element whose accessibility label equals `Email` |
+| `text="Save"` or bare `Save` | element whose title/description/value contains the text |
+| `statusItem` | opens the app's menu bar status-item menu |
+| `menu=Preferences…` | opens the status-item menu and clicks that item |
+
+`forbiddenSelectors` still applies (text patterns match via the same substring
+semantics as the web target). Prefer `id=` (accessibility identifiers) — the native
+analog of `data-testid`.
+
+### Finding selectors
+
+Don't guess selectors — dump them. `prowl analyze` works on the macOS target the
+same way it does on the web: it launches/attaches to the app, walks the
+Accessibility tree, and prints every interactive element with **ranked selector
+candidates** (best first) plus the app's windows and status-item menu contents.
+It is read-only (the only interaction is opening and closing the status menu),
+honors `guardrails.allowedApps`, and leaves the app running when done.
+
+```bash
+# Uses the macOS target from .prowl/config.yml:
+prowl analyze
+
+# …or point it at any app without a config:
+prowl analyze --app com.example.App
+prowl analyze --app "/Applications/Example.app"
+
+# Machine-readable output for agents:
+prowl analyze --app com.example.App --json
+```
+
+Example (human-readable) output:
+
+```text
+  App Analysis: com.example.App
+
+  Windows:
+    "Main Window" id=mainWindow
+
+  Interactive Elements:
+    AXButton id=saveButton "Save"
+    AXTextField label="Email" "Email"
+    AXCheckBox label="Remember me" "Remember me" (disabled)
+
+  Menu Bar:
+    AXMenuItem id=preferences "Preferences…"
+    AXMenuItem label="Quit" "Quit"
+
+  3 elements, 1 windows, 2 menu items
+```
+
+Selectors are ranked `id=` > `label=` > `role=…[name="…"]` > `text=` — copy the
+first (most durable) candidate into your hunt. Status-item menu identifiers
+(`id=preferences` above) are especially valuable, since menu titles often carry
+ellipses or localized text that are awkward to match by substring.
+
+### Step compatibility
+
+Portable steps run on **both** targets; web-only steps are rejected up front on the
+macOS target (with a clear error), and `prowl login` / URL guardrails do not apply.
+
+| Portable (web + macOS) | Web-only (rejected on macOS) |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute` |
+| `assert: visible` / `notVisible` | `evalScript`, `runScript` |
+| `screenshot`, `assertScreenshot` | `onDialog`, `select` / `selectOption` |
+| `hover`, `scrollTo` | `setInputFiles`, `waitForDownload` |
+| `repeat`, `if`, `runHunt`, `copyText` | `scroll` (directional), `assert: urlIncludes` / `urlEquals` |
+
+Notes: `press` maps Enter/Return/Space onto the element's activate action (other keys
+are unsupported); `type` fills the focused control; app teardown quits the target app
+after the run.
+
+> Docs follow-up: the customer-facing docs site (`prowl-docs`) should gain a "macOS
+> target" page mirroring this section (target type + step-compatibility matrix +
+> permission setup); tracked separately from this repo.
+
+---
+
+## Android Target (Experimental)
+
+> **Experimental (PROWL-058).** Prowl can drive **native Android apps** on an
+> emulator or a USB-connected device, in addition to the web and macOS targets.
+> It follows the same "external agent + JSON protocol" shape as the macOS target:
+> `adb` handles device lifecycle and the on-device
+> [`appium-uiautomator2-server`](https://github.com/appium/appium-uiautomator2-driver)
+> (Apache-2.0) handles UI interaction over a plain HTTP/JSON API driven with raw
+> `fetch`. The API, selector dialect, and step coverage may change.
+
+### Requirements
+
+- **`adb`** on your `PATH` (from the Android SDK platform-tools), plus at least
+  one **booted emulator or device** (`adb devices -l` should list it as `device`).
+- The two prebuilt agent APKs ship inside the `appium-uiautomator2-server` npm
+  dependency and are installed onto the device automatically — **nothing to build**.
+  No Appium server, no JVM, no gRPC.
+- If `target.app` is an **`.apk`**, Android build-tools **`aapt`/`aapt2`** must be
+  on `PATH` so Prowl can read the package name (or set `target.app` to the package
+  name directly and install the APK yourself).
+
+### Enabling it
+
+Point your config at an Android target:
+
+```yaml
+target:
+  type: android
+  app: "com.example.app"        # a package name, or a path to an .apk to install
+  # deviceSerial: "emulator-5554"  # required only when several devices are attached
+  # coldStart: true                # `pm clear` before launch for a deterministic start (default off)
+guardrails:
+  allowedApps:                     # optional scope; empty = allow the target app
+    - "com.example.app"
+```
+
+Then run a hunt as usual: `prowl run my-android-hunt`.
+
+On launch Prowl selects the device (failing with an actionable error, listing
+serials, if several are attached and no `deviceSerial` is set), installs the app
+(when given an `.apk`) and the agent, starts the agent via `am instrument`,
+port-forwards it on a **dynamically allocated** local port (so parallel sessions /
+CI jobs don't collide), and waits for the agent to report ready. Everything is
+torn down (agent session, instrumentation, port forward, `am force-stop`) after
+the run. `guardrails.allowedApps` accepts Android package IDs or canonical full
+`.apk` paths; when `target.app` is an APK, Prowl resolves its package ID and
+validates it before installing.
+
+### Selector dialect (Android)
+
+Native selectors address `resource-id`, `content-desc`, visible text, and widget
+class. Semantics match the macOS target so a selector means the same thing on both
+native targets:
+
+| Selector | Matches |
+|---|---|
+| `id=save` | element whose `resource-id` is `save` — a bare name is auto-qualified with the target app's package (`com.pkg:id/save`); ids in other namespaces need the full form (e.g. `id=android:id/title`) |
+| `label="Submit"` | element whose `content-desc` equals `Submit` (exact) |
+| `role=android.widget.Button` | element of that widget class |
+| `role=android.widget.Button[name="Save"]` | that widget class whose visible text contains `Save` |
+| `text="Save"` or bare `Save` | element whose visible text contains the text (substring) |
+
+Prefer `id=` (the native analog of `data-testid`). **Jetpack Compose caveat:**
+Compose nodes only expose a `resource-id` when the app sets
+`Modifier.testTag(...)` **and** enables `testTagsAsResourceId = true`; otherwise
+match Compose UI with `text=` or `label=` (from `Modifier.semantics { contentDescription = ... }`).
+`forbiddenSelectors` still applies (text patterns use the same substring semantics
+as the other targets).
+
+### Step compatibility
+
+Portable steps run on the Android target; web-only steps are rejected up front
+(with a clear error), and `prowl login` / URL guardrails do not apply.
+
+| Portable (Android) | Not supported on Android |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute`, `evalScript`, `runScript` |
+| `assert: visible` / `notVisible` | `onDialog`, `select` / `selectOption`, `setInputFiles` |
+| `screenshot`, `assertScreenshot` | `waitForDownload`, `scroll`, `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `hover`, `scrollTo` (no touch equivalent yet — see below) |
+
+Notes: `type` and `fill` set text on the focused / matched field **unicode-safely**
+(via the agent's `element/value`, not `adb shell input text`); `press` maps key
+names (`Enter`, `Tab`, `Backspace`, `Back`, `Home`, arrow keys, …) onto Android key
+codes and dispatches them to the focused view. `hover` and `scrollTo` have no touch
+equivalent yet and are rejected with a clear message; scroll-gesture support is a
+follow-up. A degraded pure-`adb` fallback (`uiautomator dump` + `input tap`) is a
+possible future diagnostic mode, not the primary path.
+
+> Out of scope for PROWL-058 (tracked separately): `prowl analyze` for Android and
+> CI recipes (PROWL-061), the unified native selector engine (PROWL-060), and real
+> iOS devices (PROWL-062). The iOS **simulator** target ships below.
+
+---
+
+## iOS Target (Experimental)
+
+> **Experimental (PROWL-059).** Prowl can drive **native iOS apps** on a **booted
+> iOS Simulator**, in addition to the web, macOS, and Android targets. It follows
+> the same "external agent + JSON protocol" shape: `xcrun simctl` handles simulator
+> lifecycle and screenshots, and the on-simulator
+> [WebDriverAgent](https://github.com/appium/WebDriverAgent) (Apache-2.0) handles UI
+> interaction over its W3C-shaped HTTP/JSON API driven with raw `fetch`. The API,
+> selector dialect, and step coverage may change. **Real devices are out of scope**
+> (PROWL-062) — simulators only.
+
+### Requirements
+
+- **macOS with a full Xcode** (not just the command-line tools) installed and
+  selected (`xcode-select -p`), so `xcrun simctl` and `xcodebuild` are available.
+- At least one **booted simulator** (`xcrun simctl list devices | grep Booted`, or
+  boot one with `xcrun simctl boot <udid>` / from Xcode).
+- The **WebDriverAgent** runner is built **once** from the `appium-webdriveragent`
+  npm dependency (`xcodebuild build-for-testing`) and cached under
+  `~/.prowl/wda/<wda-version>-xcode<xcode-version>/`; the first run prints a one-time
+  "building WebDriverAgent…" notice and can take a few minutes. Simulators need **no
+  code signing**. Set `PROWL_WDA_RUNNER` to a prebuilt `WebDriverAgentRunner-Runner.app`
+  to skip the build (e.g. in CI with a cached runner).
+
+### Enabling it
+
+Point your config at an iOS target:
+
+```yaml
+target:
+  type: ios
+  app: "com.example.App"          # a bundle id, or a path to a built .app to install
+  # udid: "ABCD-1234"                # required only when several simulators are booted
+  # coldStart: true                  # uninstall+reinstall before launch (requires a .app path)
+guardrails:
+  allowedApps:                       # optional scope; empty = allow the target app
+    - "com.example.App"
+```
+
+Then run a hunt as usual: `prowl run my-ios-hunt`.
+
+On launch Prowl selects the booted simulator (failing with an actionable error,
+listing candidates, if several are booted and no `udid` is set), installs the app
+(when given a `.app`, reading its bundle id from the bundle's **root** `Info.plist`),
+builds/caches and installs the WebDriverAgent runner, launches it on a
+**dynamically allocated** port (passed via `SIMCTL_CHILD_USE_PORT` so parallel
+sessions / CI jobs don't collide), launches the target app, and waits for WDA to
+report ready. Everything is torn down (WDA session, `simctl terminate` of the runner
+and the app) after the run. `guardrails.allowedApps` accepts iOS bundle ids or
+`.app` paths; a `.app` path is authorized by its path, bundle name, or the bundle id
+read from its root `Info.plist`. Note: a bare `target.app` ending in `.app` is
+treated as a **bundle id** unless a directory of that name exists, so bundle ids like
+`com.company.app` are not mistaken for paths.
+
+### Selector dialect (iOS)
+
+Native selectors address accessibility ids, labels, visible text, and element type.
+Semantics match the macOS/Android targets so a selector means the same thing across
+native targets:
+
+| Selector | Matches |
+|---|---|
+| `id=save` | element whose accessibility id (`accessibilityIdentifier` / name) is `save` |
+| `label="Submit"` | element whose `accessibilityLabel` equals `Submit` (exact) |
+| `role=XCUIElementTypeButton` | element of that type (shorthand `role=Button` works too) |
+| `role=Button[name="Save"]` | that type whose visible `label`/`value` contains `Save` |
+| `text="Save"` or bare `Save` | element whose `label` or `value` contains the text (substring) |
+| `:focus` | the element with keyboard focus (`hasKeyboardFocus == 1`) |
+
+Prefer `id=` (set `accessibilityIdentifier` in your app — the native analog of
+`data-testid`). Text/label/role+name selectors compile to WDA NSPredicate strings
+(quotes and backslashes are escaped). `forbiddenSelectors` still applies.
+
+### Step compatibility
+
+Portable steps run on the iOS target; web-only steps are rejected up front (with a
+clear error), and URL guardrails do not apply.
+
+| Portable (iOS) | Not supported on iOS |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute`, `evalScript`, `runScript` |
+| `assert: visible` / `notVisible` | `onDialog`, `select` / `selectOption`, `setInputFiles` |
+| `screenshot`, `assertScreenshot` | `waitForDownload`, `scroll`, `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `hover`, `scrollTo` (no touch equivalent yet) |
+
+Notes: `type` and `fill` set text on the focused / matched field via WDA's
+`element/value`; `press` supports a small honest key set — `enter`/`return` and
+`delete`/`backspace` (sent through WDA's key endpoint to the focused element) and
+`home` (returns to the springboard) — and rejects other keys with the supported-keys
+message. Screenshots are captured with `simctl` (not WDA), so artifacts still work
+even if the agent wedges. `hover` and `scrollTo` have no touch equivalent yet and are
+rejected with a clear message; scroll-gesture support is a follow-up.
+
+> Out of scope for PROWL-059 (tracked separately): `prowl analyze` for iOS and CI
+> recipes (PROWL-061), the unified native selector engine (PROWL-060), and real iOS
+> devices (PROWL-062).
+
+---
+
 ## Troubleshooting
 
 ### "Could not find .prowl/config.yml"