prowl-tools 0.1.8 → 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
@@ -1035,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
 
@@ -1058,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`

package/dist/{chunk-CWLRDV5P.js → chunk-2RNOK64Y.js}

@@ -499,10 +499,15 @@ ${macdriverBuildInstructions()}`
 ${macdriverBuildInstructions()}`);
 }
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 var SpawnMacHelperClient = class {
   child;
   pending = /* @__PURE__ */ new Map();
   requestTimeoutMs;
+  onEvent;
+  onEventError;
   stdoutBuffer = "";
   stderrBuffer = "";
   nextId = 1;
@@ -510,6 +515,9 @@ var SpawnMacHelperClient = class {
   terminalError;
   constructor(binaryPath, options = {}) {
     this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    this.onEvent = options.onEvent;
+    this.onEventError = options.onEventError ?? ((message) => process.stderr.write(`${message}
+`));
     this.child = spawn(binaryPath, ["serve"], { stdio: ["pipe", "pipe", "pipe"] });
     this.child.stdout?.setEncoding("utf-8");
     this.child.stderr?.setEncoding("utf-8");
@@ -546,6 +554,10 @@ var SpawnMacHelperClient = class {
     } catch {
       return;
     }
+    if (typeof message.event === "string" && typeof message.id !== "number") {
+      this.handleEvent(message);
+      return;
+    }
     const id = typeof message.id === "number" ? message.id : void 0;
     if (id === void 0) {
       return;
@@ -562,6 +574,18 @@ var SpawnMacHelperClient = class {
       pending.reject(new Error(typeof message.error === "string" ? message.error : "prowl-macdriver error"));
     }
   }
+  handleEvent(event) {
+    try {
+      this.onEvent?.(event);
+    } catch (error) {
+      try {
+        this.onEventError(
+          `prowl-macdriver event sink failed for event "${event.event}": ${errorMessage(error)}`
+        );
+      } catch {
+      }
+    }
+  }
   failAll(error) {
     for (const pending of this.pending.values()) {
       clearTimeout(pending.timer);
@@ -7482,4 +7506,4 @@ export {
   collectMacdriverStatus,
   tccGuidance
 };
-//# sourceMappingURL=chunk-CWLRDV5P.js.map
+//# sourceMappingURL=chunk-2RNOK64Y.js.map