prowl-tools 0.1.7 → 0.1.9

package/README.md

@@ -145,23 +145,33 @@ prowl init
 
 <!-- ILLUSTRATION: Terminal screenshot showing `prowl init` output with raccoon mascot and file listing -->
 
-This creates a `.prowl/` directory with a config file and two starter hunts:
+This creates a `.prowl/` directory with a config file and four starter hunts:
 
 ```text
 .prowl/
-├── config.yml         # Target URL, browser settings, guardrails
-├── .gitignore         # Keeps runs/, auth-state.json, and .env out of git
+├── config.yml          # Target URL, browser settings, guardrails
+├── .gitignore          # Keeps runs/, auth-state.json, and .env out of git
 └── hunts/
-    ├── hello.yml       # Minimal smoke test — verifies the app loads
-    └── login-flow.yml  # Fuller example — auth, secrets, assertions
+    ├── hello.yml        # Minimal smoke test — verifies the app loads
+    ├── login-flow.yml   # Auth example — fill credentials, verify redirect
+    ├── form.yml         # Forms example — fill, select, submit, assert
+    └── macos-hello.yml  # Desktop starter — drive TextEdit (macOS, experimental)
 ```
 
+The web starters (`hello`, `login-flow`, `form`) run against the default web
+target as soon as you point `config.yml` at your app. `macos-hello` is the
+desktop-first first-run hunt: it drives TextEdit through the Accessibility API,
+and its inline comments walk you through switching the target to `macos` and the
+one-time setup (`prowl macdriver install`, Accessibility permission). The macOS
+target is experimental — see [macOS Target](#macos-target-experimental).
+
 `prowl init` finishes by pointing you at the first hunt:
 
 ```text
   Initialized .prowl directory.
   Run prowl run hello to get started.
-  See .prowl/hunts/login-flow.yml for a fuller example.
+  See .prowl/hunts/login-flow.yml (auth) and .prowl/hunts/form.yml (web forms) for fuller examples.
+  Desktop-first? .prowl/hunts/macos-hello.yml is a macOS starter (experimental — see its comments to enable).
 ```
 
 ### 3. Configure
@@ -384,7 +394,20 @@ macOS target (with a clear error), and `prowl login` / URL guardrails do not app
 | `assert: visible` / `notVisible` | `evalScript`, `runScript` |
 | `screenshot`, `assertScreenshot` | `onDialog`, `select` / `selectOption` |
 | `hover`, `scrollTo` | `setInputFiles`, `waitForDownload` |
-| `repeat`, `if`, `runHunt`, `copyText` | `scroll` (directional), `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `scroll` (directional; see below) / `assert: urlIncludes` / `urlEquals` |
+
+**Scroll steps** differ per verb across targets:
+
+- **`scrollTo: { selector }`** is portable across **web, macOS, iOS, and Android**. macOS
+  resolves the element and calls **AXScrollToVisible**; iOS/Android run a bounded down/up
+  swipe probe until the element appears; web scrolls the element into view.
+- **`scroll: { direction, amount? }`** (directional) runs on **web, iOS, and Android** but is
+  **rejected on macOS** — the mobile path synthesizes a touch swipe (no macOS accessibility
+  equivalent), so on macOS use `scrollTo` to bring a specific element into view instead. On
+  the mobile targets the swipe starts from the screen centre (direction semantics match the
+  web step; `amount` maps to the swipe distance in device points, defaulting to 75% of the
+  relevant screen axis; negative amounts reverse direction, matching the web target). An
+  explicit `swipe` step is a deferred follow-up.
 
 Notes: `press` accepts the same key vocabulary as the web target — single printable
 characters, `Enter`/`Return`/`Space`, `Tab`, `Escape`, `Backspace`, `Delete`, `Home`,
@@ -1022,6 +1045,10 @@ prowl login
 prowl init
 prowl init --force                      # Overwrite existing
 
+# Doctor — check the environment is ready to run hunts
+prowl doctor
+prowl doctor --fix                      # Install Chromium / scaffold .prowl if missing
+
 # List available hunts
 prowl list
 
@@ -1045,6 +1072,28 @@ prowl mcp --projects ~/.prowl/projects.yml   # Drive multiple repos via a regist
 - Must be a positive integer (`>= 1`).
 - Invalid values (for example `0` or `1.5`) fail fast with an argument error.
 
+### Environment Check (`prowl doctor`)
+
+`prowl doctor` verifies your machine is ready to run hunts and prints a
+color-coded report (green ✓ pass, yellow ⚠ warning, red ✗ failure, gray ○
+skipped) with a one-line summary. It checks:
+
+- **Node.js** is version 20 or newer.
+- **Playwright** is installed, and its **Chromium** browser is available.
+- A **`.prowl/` directory** exists with a **valid `config.yml`**.
+- **Target tooling for your configured target only** (desktop-first): the macOS
+  target reuses `prowl macdriver status` to report which helper binary resolved;
+  the iOS target checks that `xcrun simctl` is reachable (macOS only); the
+  Android target checks that `adb` is reachable. Missing native tooling prints
+  the install command — `doctor` never installs system tools for you.
+
+Warnings do not fail the command; only real failures do (exit code `1`, so it
+slots into CI). `prowl doctor --fix` performs just the two safe repairs —
+installing Chromium through Prowl's resolved Playwright dependency and
+scaffolding a missing `.prowl/` (the same templates `prowl init` writes) — then
+re-runs the checks and reports the new status. Everything else prints a manual
+remedy.
+
 ### Run History
 
 Every `prowl run` and `prowl ci` appends an entry to `.prowl/history.json`