prowl-tools 0.1.8 → 0.1.10

package/dist/index.cjs

@@ -74,7 +74,7 @@ var init_hunt_name = __esm({
 });
 
 // src/config/schema.ts
-var import_zod, webTargetSchema, macosTargetSchema, androidTargetSchema, iosTargetSchema, targetSchema, configSchema, navigateStepSchema, clickStepSchema, singleKeyValueSchema, fillStepSchema, typeStepSchema, pressStepSchema, waitForSelectorStepSchema, waitStepSchema, waitForUrlStepSchema, waitForNetworkIdleStepSchema, selectOptionStepSchema, selectStepSchema, onDialogStepSchema, setInputFilesStepSchema, inlineAssertStepSchema, runHuntStepSchema, hoverStepSchema, scrollStepSchema, scrollToStepSchema, screenshotStepSchema, ifStepSchema, repeatStepSchema, mockRouteStepSchema, unmockRouteStepSchema, evalScriptStepSchema, runScriptStepSchema, assertScreenshotStepSchema, assertWithAiStepSchema, copyTextStepSchema, waitForDownloadStepSchema, stepSchema, assertionSchema, huntSchema;
+var import_zod, webTargetSchema, macosTargetSchema, androidTargetSchema, iosTargetSchema, targetSchema, configSchema, navigateStepSchema, clickStepSchema, singleKeyValueSchema, fillStepSchema, typeStepSchema, pressStepSchema, waitForSelectorStepSchema, waitStepSchema, waitForUrlStepSchema, waitForNetworkIdleStepSchema, waitForResponseStatusSchema, waitForResponseTimeoutSchema, waitForResponseStepSchema, selectOptionStepSchema, selectStepSchema, onDialogStepSchema, setInputFilesStepSchema, inlineAssertStepSchema, runHuntStepSchema, hoverStepSchema, scrollStepSchema, scrollToStepSchema, screenshotStepSchema, ifStepSchema, repeatStepSchema, mockRouteStepSchema, unmockRouteStepSchema, evalScriptStepSchema, runScriptStepSchema, assertScreenshotStepSchema, assertWithAiStepSchema, copyTextStepSchema, waitForDownloadStepSchema, stepSchema, assertionSchema, huntSchema;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     "use strict";
@@ -199,6 +199,21 @@ var init_schema = __esm({
     waitForNetworkIdleStepSchema = import_zod.z.object({
       waitForNetworkIdle: import_zod.z.object({ timeout: import_zod.z.number().optional() }).strict()
     }).strict();
+    waitForResponseStatusSchema = import_zod.z.number().int().min(100).max(599);
+    waitForResponseTimeoutSchema = import_zod.z.number().int().min(0).finite();
+    waitForResponseStepSchema = import_zod.z.object({
+      waitForResponse: import_zod.z.object({
+        // Matched against each response URL as a glob (`*`/`**` match any run of
+        // characters including `/`, `?` matches one character); matching is
+        // unanchored, so a pattern with no wildcards behaves as a substring match.
+        url: import_zod.z.string().min(1).describe(
+          "URL glob to wait for; unanchored, so a wildcard-free pattern is a substring match"
+        ),
+        // Optional status filter: only resolve on a response with this exact HTTP status.
+        status: waitForResponseStatusSchema.optional(),
+        timeout: waitForResponseTimeoutSchema.optional()
+      }).strict()
+    }).strict();
     selectOptionStepSchema = import_zod.z.object({
       selectOption: import_zod.z.object({ selector: import_zod.z.string().min(1), value: import_zod.z.string() }).strict()
     }).strict();
@@ -360,6 +375,7 @@ var init_schema = __esm({
       waitForSelectorStepSchema,
       waitForUrlStepSchema,
       waitForNetworkIdleStepSchema,
+      waitForResponseStepSchema,
       hoverStepSchema,
       scrollStepSchema,
       scrollToStepSchema,
@@ -592,6 +608,16 @@ function interpolateStep(step, vars, stepPath2, redacted) {
   if ("waitForNetworkIdle" in step) {
     return { waitForNetworkIdle: { timeout: step.waitForNetworkIdle.timeout } };
   }
+  if ("waitForResponse" in step) {
+    const urlResult = interpolateString(step.waitForResponse.url, vars);
+    return {
+      waitForResponse: {
+        url: urlResult.value,
+        ...step.waitForResponse.status !== void 0 ? { status: step.waitForResponse.status } : {},
+        timeout: step.waitForResponse.timeout
+      }
+    };
+  }
   if ("hover" in step) {
     const selectorResult = interpolateString(step.hover.selector, vars);
     return { hover: { selector: selectorResult.value } };
@@ -1128,12 +1154,12 @@ var init_visual = __esm({
 });
 
 // src/cli/program.ts
-var import_commander14 = require("commander");
+var import_commander15 = require("commander");
 
 // package.json
 var package_default = {
   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",
@@ -1192,7 +1218,8 @@ var package_default = {
     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",
@@ -1216,6 +1243,7 @@ var package_default = {
     "@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"
@@ -1240,6 +1268,7 @@ var WEB_ONLY_STEP_TYPES = /* @__PURE__ */ new Set([
   "navigate",
   "waitForUrl",
   "waitForNetworkIdle",
+  "waitForResponse",
   "mockRoute",
   "unmockRoute",
   "evalScript",
@@ -1625,6 +1654,9 @@ function createPlaywrightDriver(page) {
     async waitForNetworkIdle(options) {
       await page.waitForLoadState("networkidle", { timeout: options?.timeout });
     },
+    async waitForResponse(predicate, options) {
+      await page.waitForResponse((response) => predicate(response), { timeout: options?.timeout });
+    },
     evaluate(pageFunction, arg) {
       const raw = page.evaluate;
       const result = arg === void 0 ? raw.call(page, pageFunction) : raw.call(page, pageFunction, arg);
@@ -1827,6 +1859,9 @@ function createMacDriver(client, options = {}) {
     waitForNetworkIdle() {
       return rejectUnsupported("waitForNetworkIdle");
     },
+    waitForResponse() {
+      return rejectUnsupported("waitForResponse");
+    },
     // scripting & artifacts ------------------------------------------------
     evaluate() {
       return rejectUnsupported("evalScript");
@@ -1950,10 +1985,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;
@@ -1961,6 +2001,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 = (0, import_node_child_process2.spawn)(binaryPath, ["serve"], { stdio: ["pipe", "pipe", "pipe"] });
     this.child.stdout?.setEncoding("utf-8");
     this.child.stderr?.setEncoding("utf-8");
@@ -1997,6 +2040,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;
@@ -2013,6 +2060,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);
@@ -2651,6 +2710,9 @@ function createAndroidDriver(client, options = {}) {
     waitForNetworkIdle() {
       return rejectUnsupported("waitForNetworkIdle");
     },
+    waitForResponse() {
+      return rejectUnsupported("waitForResponse");
+    },
     // scripting & artifacts ------------------------------------------------
     evaluate() {
       return rejectUnsupported("evalScript");
@@ -2924,12 +2986,12 @@ var Uia2Transport = class {
    * {@link Uia2HttpError} on a non-2xx response, or a timeout error when the
    * per-request deadline elapses.
    */
-  async request(method, path27, body, timeoutMs) {
+  async request(method, path28, body, timeoutMs) {
     const requestTimeoutMs = timeoutMs ?? this.requestTimeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
     timer.unref?.();
-    const url = `${this.baseUrl}${path27}`;
+    const url = `${this.baseUrl}${path28}`;
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -2941,7 +3003,7 @@ var Uia2Transport = class {
     } catch (error) {
       if (controller.signal.aborted) {
         const shown = requestTimeoutMs >= 1e3 ? `${Math.round(requestTimeoutMs / 1e3)}s` : `${requestTimeoutMs}ms`;
-        throw new Error(`uiautomator2 request ${method} ${path27} timed out after ${shown}`);
+        throw new Error(`uiautomator2 request ${method} ${path28} timed out after ${shown}`);
       }
       throw error instanceof Error ? error : new Error(String(error));
     } finally {
@@ -2952,7 +3014,7 @@ var Uia2Transport = class {
     if (!response.ok) {
       const wdError = extractWebdriverError(parsed);
       throw new Uia2HttpError(
-        `uiautomator2 ${method} ${path27} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
+        `uiautomator2 ${method} ${path28} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
         response.status,
         wdError
       );
@@ -3035,10 +3097,10 @@ function sleep(ms) {
 }
 function createUia2AgentClient(transport, sessionId, options = {}) {
   const base = `/session/${sessionId}`;
-  async function locate(query, path27) {
+  async function locate(query, path28) {
     return transport.request(
       "POST",
-      `${base}${path27}`,
+      `${base}${path28}`,
       androidQueryToLocator(query, { appPackage: options.appPackage })
     );
   }
@@ -3517,6 +3579,9 @@ function createIosDriver(client, options) {
     waitForNetworkIdle() {
       return rejectUnsupported("waitForNetworkIdle");
     },
+    waitForResponse() {
+      return rejectUnsupported("waitForResponse");
+    },
     // scripting & artifacts ------------------------------------------------
     evaluate() {
       return rejectUnsupported("evalScript");
@@ -3839,15 +3904,15 @@ var WdaTransport = class {
    * {@link WdaHttpError} on a non-2xx response, or a timeout error when the
    * per-request deadline elapses.
    */
-  async requestFull(method, path27, body, timeoutMs) {
+  async requestFull(method, path28, body, timeoutMs) {
     const requestTimeoutMs = timeoutMs ?? this.requestTimeoutMs;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
     timer.unref?.();
-    const url = `${this.baseUrl}${path27}`;
+    const url = `${this.baseUrl}${path28}`;
     const timeoutError = () => {
       const shown = requestTimeoutMs >= 1e3 ? `${Math.round(requestTimeoutMs / 1e3)}s` : `${requestTimeoutMs}ms`;
-      return new Error(`WebDriverAgent request ${method} ${path27} timed out after ${shown}`);
+      return new Error(`WebDriverAgent request ${method} ${path28} timed out after ${shown}`);
     };
     let response;
     try {
@@ -3879,7 +3944,7 @@ var WdaTransport = class {
     if (!response.ok) {
       const wdError = extractWebdriverError2(parsed);
       throw new WdaHttpError(
-        `WebDriverAgent ${method} ${path27} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
+        `WebDriverAgent ${method} ${path28} failed (${response.status})${wdError ? `: ${wdError}` : ""}`,
         response.status,
         wdError
       );
@@ -3887,8 +3952,8 @@ var WdaTransport = class {
     return parsed;
   }
   /** Like {@link requestFull} but returns just the `value` field. */
-  async request(method, path27, body, timeoutMs) {
-    const parsed = await this.requestFull(method, path27, body, timeoutMs);
+  async request(method, path28, body, timeoutMs) {
+    const parsed = await this.requestFull(method, path28, body, timeoutMs);
     return parsed?.value;
   }
 };
@@ -3964,8 +4029,8 @@ function sleep2(ms) {
 }
 function createWdaAgentClient(transport, sessionId) {
   const base = `/session/${sessionId}`;
-  async function locate(query, path27) {
-    return transport.request("POST", `${base}${path27}`, iosQueryToLocator(query));
+  async function locate(query, path28) {
+    return transport.request("POST", `${base}${path28}`, iosQueryToLocator(query));
   }
   return {
     async findElement(query) {
@@ -4781,6 +4846,7 @@ function getStepType(step) {
   if ("waitForSelector" in step) return "waitForSelector";
   if ("waitForUrl" in step) return "waitForUrl";
   if ("waitForNetworkIdle" in step) return "waitForNetworkIdle";
+  if ("waitForResponse" in step) return "waitForResponse";
   if ("hover" in step) return "hover";
   if ("scroll" in step) return "scroll";
   if ("scrollTo" in step) return "scrollTo";
@@ -4797,6 +4863,11 @@ function getStepType(step) {
   if ("waitForDownload" in step) return "waitForDownload";
   return "step";
 }
+function compileResponseUrlMatcher(pattern) {
+  const regexBody = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*").replace(/\\\?/g, ".");
+  const regex = new RegExp(regexBody);
+  return (url) => regex.test(url);
+}
 var RUNTIME_VAR_PATTERN = /\{\{([A-Z0-9_]+)\}\}/g;
 function substituteRuntimeVars(input, vars) {
   return input.replace(RUNTIME_VAR_PATTERN, (match, name) => {
@@ -4835,6 +4906,15 @@ function applyRuntimeVars(step, vars) {
   if ("waitForSelector" in step) {
     return { waitForSelector: { selector: sub(step.waitForSelector.selector), timeout: step.waitForSelector.timeout } };
   }
+  if ("waitForResponse" in step) {
+    return {
+      waitForResponse: {
+        url: sub(step.waitForResponse.url),
+        ...step.waitForResponse.status !== void 0 ? { status: step.waitForResponse.status } : {},
+        ...step.waitForResponse.timeout !== void 0 ? { timeout: step.waitForResponse.timeout } : {}
+      }
+    };
+  }
   if ("evalScript" in step) {
     if (typeof step.evalScript === "string") return { evalScript: sub(step.evalScript) };
     return {
@@ -5444,6 +5524,32 @@ var STEP_HANDLERS = {
       };
     }
   },
+  waitForResponse: {
+    capabilities: ["response", "wait"],
+    run: async (h) => {
+      if (!("waitForResponse" in h.step)) unknownStep();
+      const { url: pattern, status, timeout } = h.step.waitForResponse;
+      const matchesResponseUrl = compileResponseUrlMatcher(pattern);
+      try {
+        await h.driver.waitForResponse(
+          (response) => matchesResponseUrl(response.url()) && (status === void 0 || response.status() === status),
+          { timeout }
+        );
+      } catch (err) {
+        const isTimeout = err instanceof Error && (err.name === "TimeoutError" || /timeout/i.test(err.message));
+        if (!isTimeout) throw err;
+        const statusPart = status !== void 0 ? ` with status ${status}` : "";
+        const timeoutPart = timeout !== void 0 ? ` within ${timeout}ms` : "";
+        throw new Error(
+          `waitForResponse: no response matching "${pattern}"${statusPart} was received${timeoutPart}.`
+        );
+      }
+      return {
+        kind: "result",
+        result: { type: "waitForResponse", status: "pass", durationMs: Date.now() - h.stepStart, value: pattern }
+      };
+    }
+  },
   waitForNetworkIdle: {
     capabilities: ["wait"],
     run: async (h) => {
@@ -6234,6 +6340,15 @@ function formatStep(step) {
   const error = step.error ? ` error=${escapeMd(step.error)}` : "";
   return `${base}${selector}${healed}${value}${error}`;
 }
+function formatRetryAttempt(attempt) {
+  const base = `- attempt ${attempt.attempt}: ${attempt.status.toUpperCase()} (${attempt.durationMs}ms)`;
+  if (attempt.status === "pass") {
+    return base;
+  }
+  const step = attempt.failedStep ? ` failed-step=[${attempt.failedStep.index}] ${escapeMd(attempt.failedStep.type)}` : "";
+  const error = attempt.error ? ` error=${escapeMd(attempt.error)}` : "";
+  return `${base}${step}${error}`;
+}
 function formatAssertion(assertion) {
   const value = assertion.value !== void 0 ? ` value=${typeof assertion.value === "string" ? escapeMd(assertion.value) : assertion.value}` : "";
   const error = assertion.error ? ` error=${escapeMd(assertion.error)}` : "";
@@ -6248,6 +6363,16 @@ function writeSummary(runDir, result) {
   lines.push(`Target: ${result.targetUrl}`);
   lines.push(`Started: ${result.startedAt}`);
   lines.push(`Duration: ${result.durationMs}ms`);
+  if (result.retryHistory && result.retryHistory.length > 1) {
+    lines.push("");
+    lines.push("## Retries");
+    if (result.retrySummary) {
+      lines.push(escapeMd(result.retrySummary));
+    }
+    for (const attempt of result.retryHistory) {
+      lines.push(formatRetryAttempt(attempt));
+    }
+  }
   lines.push("");
   lines.push("## Steps");
   for (const step of result.steps) {
@@ -6408,7 +6533,8 @@ function isHistoryEntry(value) {
     return false;
   }
   const entry = value;
-  return typeof entry.hunt === "string" && (entry.status === "pass" || entry.status === "fail") && typeof entry.durationMs === "number" && Number.isFinite(entry.durationMs) && typeof entry.startedAt === "string" && (entry.runDir === void 0 || typeof entry.runDir === "string");
+  return typeof entry.hunt === "string" && (entry.status === "pass" || entry.status === "fail") && typeof entry.durationMs === "number" && Number.isFinite(entry.durationMs) && typeof entry.startedAt === "string" && (entry.runDir === void 0 || typeof entry.runDir === "string") && // Optional (PROWL-033): older history.json files predate `retries`.
+  (entry.retries === void 0 || typeof entry.retries === "number" && Number.isInteger(entry.retries) && entry.retries >= 0);
 }
 function readHistory(configDir) {
   const filePath = historyPath(configDir);
@@ -6660,6 +6786,60 @@ async function executeHuntAttempt(options, config, configDir, interpolatedHunt,
 function delay3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function toRetryAttempt(attempt, result) {
+  const record = {
+    attempt,
+    status: result.status,
+    durationMs: result.durationMs
+  };
+  if (result.status === "fail") {
+    const failedIndex = result.steps.findIndex((step) => step.status === "fail");
+    if (failedIndex >= 0) {
+      const failed = result.steps[failedIndex];
+      record.failedStep = { index: failedIndex, type: failed.type };
+      if (failed.error) {
+        record.error = failed.error;
+      }
+    }
+    if (!record.error) {
+      const failedAssertion = result.assertions.find((assertion) => assertion.status === "fail");
+      if (failedAssertion?.error) {
+        record.error = failedAssertion.error;
+      }
+    }
+  }
+  return record;
+}
+function describeAttemptFailure(attempt) {
+  if (attempt.status !== "fail") {
+    return void 0;
+  }
+  const step = attempt.failedStep?.type;
+  if (step && attempt.error) {
+    return `${step} (${attempt.error})`;
+  }
+  return step ?? attempt.error;
+}
+function buildRetrySummary(attempts, maxRetries) {
+  const final = attempts[attempts.length - 1];
+  const firstFailure = describeAttemptFailure(attempts[0]);
+  const suffix = firstFailure ? ` \u2014 first failure: ${firstFailure}` : "";
+  if (final.status === "pass") {
+    return `Passed on attempt ${final.attempt} of ${maxRetries + 1}${suffix}`;
+  }
+  return `Failed after ${attempts.length} attempts${suffix}`;
+}
+function finalizeRetryOutcome(outcome, attempts, maxRetries, junit) {
+  outcome.result = writeReports(
+    outcome.runDir,
+    {
+      ...outcome.result,
+      retryHistory: attempts,
+      retrySummary: buildRetrySummary(attempts, maxRetries)
+    },
+    { junit }
+  );
+}
 async function runHunt(options) {
   const { config, configDir } = loadConfig(options.configPath);
   if (config.target.type === "macos") {
@@ -6689,7 +6869,9 @@ async function runHunt(options) {
   }
   const maxRetries = hunt.retry?.maxRetries ?? 0;
   const retryDelay = hunt.retry?.delay ?? 0;
+  const junit = options.junit ?? config.artifacts.junit;
   let lastResult;
+  const attempts = [];
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     if (attempt > 0 && retryDelay > 0) {
       await delay3(retryDelay);
@@ -6705,19 +6887,20 @@ async function runHunt(options) {
       targetUrl,
       allowedDomains
     );
+    attempts.push(toRetryAttempt(attempt + 1, lastResult.result));
     if (lastResult.result.status === "pass") {
-      if (attempt > 0) {
-        lastResult.result.artifacts.summary = `Passed on attempt ${attempt + 1} of ${maxRetries + 1}`;
+      if (attempts.length > 1) {
+        finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
       }
-      recordHistory(configDir, lastResult, config.history.maxRuns);
+      recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
       return lastResult;
     }
   }
-  if (maxRetries > 0 && lastResult) {
-    lastResult.result.artifacts.summary = `Failed after ${maxRetries + 1} attempts`;
-  }
   if (lastResult) {
-    recordHistory(configDir, lastResult, config.history.maxRuns);
+    if (attempts.length > 1) {
+      finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
+    }
+    recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
   }
   return lastResult;
 }
@@ -6921,7 +7104,9 @@ async function runNativeHunt(options, config, configDir, target, native) {
   }
   const maxRetries = hunt.retry?.maxRetries ?? 0;
   const retryDelay = hunt.retry?.delay ?? 0;
+  const junit = options.junit ?? config.artifacts.junit;
   let lastResult;
+  const attempts = [];
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     if (attempt > 0 && retryDelay > 0) {
       await delay3(retryDelay);
@@ -6936,23 +7121,24 @@ async function runNativeHunt(options, config, configDir, target, native) {
       randomVars,
       config.guardrails.allowedApps
     );
+    attempts.push(toRetryAttempt(attempt + 1, lastResult.result));
     if (lastResult.result.status === "pass") {
-      if (attempt > 0) {
-        lastResult.result.artifacts.summary = `Passed on attempt ${attempt + 1} of ${maxRetries + 1}`;
+      if (attempts.length > 1) {
+        finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
       }
-      recordHistory(configDir, lastResult, config.history.maxRuns);
+      recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
       return lastResult;
     }
   }
-  if (maxRetries > 0 && lastResult) {
-    lastResult.result.artifacts.summary = `Failed after ${maxRetries + 1} attempts`;
-  }
   if (lastResult) {
-    recordHistory(configDir, lastResult, config.history.maxRuns);
+    if (attempts.length > 1) {
+      finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
+    }
+    recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
   }
   return lastResult;
 }
-function recordHistory(configDir, outcome, maxRuns) {
+function recordHistory(configDir, outcome, maxRuns, retries = 0) {
   try {
     const relativeRunDir = import_node_path15.default.relative(configDir, outcome.runDir);
     appendEntry(
@@ -6962,7 +7148,9 @@ function recordHistory(configDir, outcome, maxRuns) {
         status: outcome.result.status,
         durationMs: outcome.result.durationMs,
         startedAt: outcome.result.startedAt,
-        runDir: relativeRunDir || void 0
+        runDir: relativeRunDir || void 0,
+        // Omit when no retry ran so entries stay additive/backward-compatible.
+        retries: retries > 0 ? retries : void 0
       },
       maxRuns
     );
@@ -7017,6 +7205,10 @@ function describeStep(step) {
   if ("waitForSelector" in step) return `waitForSelector "${step.waitForSelector.selector}"`;
   if ("waitForUrl" in step) return `waitForUrl "${step.waitForUrl.value}"`;
   if ("waitForNetworkIdle" in step) return "waitForNetworkIdle";
+  if ("waitForResponse" in step) {
+    const statusSuffix = step.waitForResponse.status !== void 0 ? ` (status ${step.waitForResponse.status})` : "";
+    return `waitForResponse "${step.waitForResponse.url}"${statusSuffix}`;
+  }
   if ("hover" in step) return `hover "${step.hover.selector}"`;
   if ("scroll" in step) return `scroll ${step.scroll.direction} ${step.scroll.amount ?? 500}px`;
   if ("scrollTo" in step) return `scrollTo "${step.scrollTo.selector}"`;
@@ -7080,6 +7272,10 @@ function printHuntSummary(result, runDir) {
   const duration = import_chalk.default.gray(`(${result.durationMs}ms)`);
   console.log(`
   ${status} ${import_chalk.default.bold(result.hunt)} ${duration} ${stepCount}`);
+  if (result.retrySummary) {
+    const color = result.status === "pass" ? import_chalk.default.yellow : import_chalk.default.red;
+    console.log(`  ${color(result.retrySummary)}`);
+  }
   console.log(`  ${import_chalk.default.gray("Artifacts:")} ${runDir}
 `);
 }
@@ -7189,6 +7385,7 @@ function buildRunCommand() {
 
 // src/cli/commands/init.ts
 var import_node_fs15 = __toESM(require("fs"), 1);
+var import_node_os5 = __toESM(require("os"), 1);
 var import_node_path16 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 var import_commander2 = require("commander");
@@ -7214,6 +7411,192 @@ function copyFile(source, destination) {
   import_node_fs15.default.mkdirSync(import_node_path16.default.dirname(destination), { recursive: true });
   import_node_fs15.default.copyFileSync(source, destination);
 }
+function isInsideDir(parent, child) {
+  const relative = import_node_path16.default.relative(parent, child);
+  return relative.length > 0 && !relative.startsWith("..") && !import_node_path16.default.isAbsolute(relative);
+}
+function lstatIfExists(target) {
+  try {
+    return import_node_fs15.default.lstatSync(target);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return null;
+    }
+    throw error;
+  }
+}
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function assertNoSymlinkDestination(prowlDir, destination) {
+  const relative = import_node_path16.default.relative(prowlDir, destination);
+  if (relative.startsWith("..") || import_node_path16.default.isAbsolute(relative)) {
+    throw new Error(`Refusing to write outside ${CONFIG_DIR}: ${destination}`);
+  }
+  const parts = relative.split(import_node_path16.default.sep).filter((part) => part.length > 0);
+  let current = prowlDir;
+  const rootStat = lstatIfExists(current);
+  if (rootStat?.isSymbolicLink()) {
+    throw new Error(
+      `${CONFIG_DIR} scaffold destination path contains a symlink: ${current}. Replace it with a real file or directory before running prowl init --force.`
+    );
+  }
+  if (rootStat && !rootStat.isDirectory()) {
+    throw new Error(`${CONFIG_DIR} scaffold path is not a directory: ${current}`);
+  }
+  for (let index = 0; index < parts.length; index += 1) {
+    current = import_node_path16.default.join(current, parts[index] ?? "");
+    const stat = lstatIfExists(current);
+    if (stat?.isSymbolicLink()) {
+      throw new Error(
+        `${CONFIG_DIR} scaffold destination path contains a symlink: ${current}. Replace it with a real file or directory before running prowl init --force.`
+      );
+    }
+    if (stat && index < parts.length - 1 && !stat.isDirectory()) {
+      throw new Error(`${CONFIG_DIR} scaffold parent path is not a directory: ${current}`);
+    }
+  }
+}
+function gitignoreTemplate() {
+  return [
+    "# Run artifacts (screenshots, logs, reports)",
+    "runs/",
+    "",
+    "# Auth state (tokens, cookies)",
+    "auth-state.json",
+    "",
+    "# Environment variables (credentials)",
+    ".env",
+    ""
+  ].join("\n");
+}
+function stageScaffoldTemplates(examplesDir) {
+  const stageDir = import_node_fs15.default.mkdtempSync(import_node_path16.default.join(import_node_os5.default.tmpdir(), "prowl-init-"));
+  const files = [];
+  try {
+    copyFile(import_node_path16.default.join(examplesDir, "config.yml"), import_node_path16.default.join(stageDir, "config.yml"));
+    files.push({ source: import_node_path16.default.join(stageDir, "config.yml"), relativePath: "config.yml" });
+    const exampleHuntsDir = import_node_path16.default.join(examplesDir, "hunts");
+    const huntFiles = import_node_fs15.default.readdirSync(exampleHuntsDir).filter((f) => f.endsWith(".yml"));
+    for (const huntFile of huntFiles) {
+      const relativePath = import_node_path16.default.join("hunts", huntFile);
+      copyFile(import_node_path16.default.join(exampleHuntsDir, huntFile), import_node_path16.default.join(stageDir, relativePath));
+      files.push({ source: import_node_path16.default.join(stageDir, relativePath), relativePath });
+    }
+    const gitignorePath = import_node_path16.default.join(stageDir, ".gitignore");
+    import_node_fs15.default.writeFileSync(gitignorePath, gitignoreTemplate());
+    files.push({ source: gitignorePath, relativePath: ".gitignore" });
+    return { stageDir, files };
+  } catch (error) {
+    import_node_fs15.default.rmSync(stageDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+function trackCreatedParentDirs(destination, prowlDir, createdDirs) {
+  let dir = import_node_path16.default.dirname(destination);
+  while (isInsideDir(prowlDir, dir) && !import_node_fs15.default.existsSync(dir)) {
+    createdDirs.add(dir);
+    dir = import_node_path16.default.dirname(dir);
+  }
+}
+function prepareDestinationRollback(prowlDir, files) {
+  const backupDir = import_node_fs15.default.mkdtempSync(import_node_path16.default.join(import_node_os5.default.tmpdir(), "prowl-init-rollback-"));
+  const backups = [];
+  const createdFiles = [];
+  const createdDirs = /* @__PURE__ */ new Set();
+  const prowlDirExisted = import_node_fs15.default.existsSync(prowlDir);
+  try {
+    for (const file of files) {
+      const destination = import_node_path16.default.join(prowlDir, file.relativePath);
+      assertNoSymlinkDestination(prowlDir, destination);
+      const stat = lstatIfExists(destination);
+      if (stat) {
+        if (!stat.isFile()) {
+          throw new Error(`${CONFIG_DIR} scaffold destination is not a regular file: ${destination}`);
+        }
+        const backup = import_node_path16.default.join(backupDir, file.relativePath);
+        copyFile(destination, backup);
+        backups.push({ destination, backup });
+      } else {
+        createdFiles.push(destination);
+      }
+      if (prowlDirExisted) {
+        trackCreatedParentDirs(destination, prowlDir, createdDirs);
+      }
+    }
+    return {
+      prowlDirExisted,
+      backupDir,
+      backups,
+      createdFiles,
+      createdDirs: [...createdDirs].sort((a, b) => b.length - a.length)
+    };
+  } catch (error) {
+    import_node_fs15.default.rmSync(backupDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+function rollbackDestination(prowlDir, rollback) {
+  if (!rollback.prowlDirExisted) {
+    import_node_fs15.default.rmSync(prowlDir, { recursive: true, force: true });
+    return;
+  }
+  for (const file of rollback.createdFiles) {
+    import_node_fs15.default.rmSync(file, { force: true });
+  }
+  for (const backup of rollback.backups) {
+    try {
+      copyFile(backup.backup, backup.destination);
+    } catch (error) {
+      throw new Error(
+        `Failed to restore ${backup.destination} from backup ${backup.backup}: ${errorMessage2(error)}`
+      );
+    }
+  }
+  for (const dir of rollback.createdDirs) {
+    try {
+      import_node_fs15.default.rmdirSync(dir);
+    } catch {
+    }
+  }
+}
+function scaffoldProwlDir(root) {
+  const prowlDir = import_node_path16.default.join(root, CONFIG_DIR);
+  const packageRoot = getPackageRoot2();
+  const examplesDir = import_node_path16.default.join(packageRoot, "examples");
+  const exampleConfig = import_node_path16.default.join(examplesDir, "config.yml");
+  const exampleHuntsDir = import_node_path16.default.join(examplesDir, "hunts");
+  if (!import_node_fs15.default.existsSync(exampleConfig) || !import_node_fs15.default.existsSync(exampleHuntsDir)) {
+    throw new Error("Examples not found in package. Reinstall prowl-tools.");
+  }
+  const staged = stageScaffoldTemplates(examplesDir);
+  let rollback = null;
+  let keepBackup = false;
+  try {
+    rollback = prepareDestinationRollback(prowlDir, staged.files);
+    for (const file of staged.files) {
+      copyFile(file.source, import_node_path16.default.join(prowlDir, file.relativePath));
+    }
+  } catch (error) {
+    if (rollback) {
+      try {
+        rollbackDestination(prowlDir, rollback);
+      } catch (rollbackError) {
+        keepBackup = true;
+        throw new Error(
+          `Scaffold failed: ${errorMessage2(error)}. Rollback failed: ${errorMessage2(rollbackError)}. Backup preserved at ${rollback.backupDir}.`
+        );
+      }
+    }
+    throw error;
+  } finally {
+    if (rollback && !keepBackup) {
+      import_node_fs15.default.rmSync(rollback.backupDir, { recursive: true, force: true });
+    }
+    import_node_fs15.default.rmSync(staged.stageDir, { recursive: true, force: true });
+  }
+}
 function buildInitCommand() {
   const command = new import_commander2.Command("init").option("--force", `Overwrite existing ${CONFIG_DIR} directory`).action((options) => {
     const root = process.cwd();
@@ -7227,39 +7610,18 @@ function buildInitCommand() {
       process.exitCode = 1;
       return;
     }
-    const packageRoot = getPackageRoot2();
-    const examplesDir = import_node_path16.default.join(packageRoot, "examples");
-    const exampleConfig = import_node_path16.default.join(examplesDir, "config.yml");
-    const exampleHuntsDir = import_node_path16.default.join(examplesDir, "hunts");
-    if (!import_node_fs15.default.existsSync(exampleConfig) || !import_node_fs15.default.existsSync(exampleHuntsDir)) {
-      console.error(import_chalk4.default.red("Examples not found in package. Reinstall prowl-tools."));
+    try {
+      scaffoldProwlDir(root);
+    } catch (error) {
+      console.error(import_chalk4.default.red(error instanceof Error ? error.message : "init failed"));
       process.exitCode = 1;
       return;
     }
-    copyFile(exampleConfig, import_node_path16.default.join(prowlDir, "config.yml"));
-    const huntFiles = import_node_fs15.default.readdirSync(exampleHuntsDir).filter((f) => f.endsWith(".yml"));
-    for (const huntFile of huntFiles) {
-      copyFile(
-        import_node_path16.default.join(exampleHuntsDir, huntFile),
-        import_node_path16.default.join(prowlDir, "hunts", huntFile)
-      );
-    }
-    const gitignore = [
-      "# Run artifacts (screenshots, logs, reports)",
-      "runs/",
-      "",
-      "# Auth state (tokens, cookies)",
-      "auth-state.json",
-      "",
-      "# Environment variables (credentials)",
-      ".env",
-      ""
-    ].join("\n");
-    import_node_fs15.default.writeFileSync(import_node_path16.default.join(prowlDir, ".gitignore"), gitignore);
     console.log(welcomeBanner());
     console.log(import_chalk4.default.green(`  Initialized ${CONFIG_DIR} directory.`));
     console.log(import_chalk4.default.gray("  Run ") + import_chalk4.default.bold("prowl run hello") + import_chalk4.default.gray(" to get started."));
-    console.log(import_chalk4.default.gray("  See ") + import_chalk4.default.cyan(`${CONFIG_DIR}/hunts/login-flow.yml`) + import_chalk4.default.gray(" for a fuller example.") + "\n");
+    console.log(import_chalk4.default.gray("  See ") + import_chalk4.default.cyan(`${CONFIG_DIR}/hunts/login-flow.yml`) + import_chalk4.default.gray(" (auth) and ") + import_chalk4.default.cyan(`${CONFIG_DIR}/hunts/form.yml`) + import_chalk4.default.gray(" (web forms) for fuller examples."));
+    console.log(import_chalk4.default.gray("  Desktop-first? ") + import_chalk4.default.cyan(`${CONFIG_DIR}/hunts/macos-hello.yml`) + import_chalk4.default.gray(" is a macOS starter (experimental \u2014 see its comments to enable).") + "\n");
   });
   return command;
 }
@@ -9033,6 +9395,7 @@ var STEP_REFERENCE = `
 - waitForSelector: { selector: "#el", timeout: 5000 }
 - waitForUrl: { value: "/path", timeout: 5000 }
 - waitForNetworkIdle: { timeout: 5000 }
+- waitForResponse: { url: "**/api/orders", status: 200, timeout: 10000 } \u2014 wait for a matching network response (url is a glob/substring; status is optional)
 
 ### Interaction
 - click: "Button Text" \u2014 click by text (tries role=button first)
@@ -9273,6 +9636,7 @@ function buildHistoryCommand() {
       }
       console.log();
       console.log(`  ${import_chalk13.default.bold(huntName)} \u2014 last ${recent.length} of ${entries.length} runs`);
+      console.log(`  ${import_chalk13.default.gray(formatRetryFrequency(recent))}`);
       console.log();
       console.log(formatTable(recent));
       console.log();
@@ -9288,12 +9652,23 @@ function buildHistoryCommand() {
   });
   return command;
 }
+function formatRetryFrequency(entries) {
+  const retried = entries.filter((entry) => (entry.retries ?? 0) > 0).length;
+  if (retried === 0) {
+    return "No retries in these runs";
+  }
+  return `Retried in ${retried} of ${entries.length} runs`;
+}
+function formatRetries(retries) {
+  return retries && retries > 0 ? String(retries) : "-";
+}
 function formatTable(entries) {
-  const headers = ["Status", "Started", "Duration"];
+  const headers = ["Status", "Started", "Duration", "Retries"];
   const rows = entries.map((entry) => [
     formatStatus(entry.status),
     entry.startedAt,
-    formatDuration(entry.durationMs)
+    formatDuration(entry.durationMs),
+    formatRetries(entry.retries)
   ]);
   const widths = headers.map(
     (header, index) => Math.max(
@@ -9463,7 +9838,7 @@ async function runHuntTool(args, configPath) {
 
 // src/mcp/projects.ts
 var import_node_fs21 = __toESM(require("fs"), 1);
-var import_node_os5 = __toESM(require("os"), 1);
+var import_node_os6 = __toESM(require("os"), 1);
 var import_node_path25 = __toESM(require("path"), 1);
 var import_yaml3 = __toESM(require("yaml"), 1);
 var import_zod2 = require("zod");
@@ -9476,10 +9851,10 @@ var projectRegistrySchema = import_zod2.z.object({
   projects: import_zod2.z.record(import_zod2.z.string().min(1), projectEntrySchema)
 }).strict();
 function defaultRegistryPath() {
-  return import_node_path25.default.join(import_node_os5.default.homedir(), ".prowl", "projects.yml");
+  return import_node_path25.default.join(import_node_os6.default.homedir(), ".prowl", "projects.yml");
 }
 function legacyRegistryPath() {
-  return import_node_path25.default.join(import_node_os5.default.homedir(), ".prowlqa", "projects.yml");
+  return import_node_path25.default.join(import_node_os6.default.homedir(), ".prowlqa", "projects.yml");
 }
 function resolveProjectConfigPath(root) {
   const preferred = import_node_path25.default.join(root, ".prowl", "config.yml");
@@ -9533,7 +9908,7 @@ function listRegisteredProjects(registry) {
 function textResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-function errorMessage(error) {
+function errorMessage3(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function safeStringify(value) {
@@ -9547,7 +9922,7 @@ async function toolResult(toolName, args, action) {
   try {
     return textResult(await action());
   } catch (error) {
-    throw new Error(`${toolName} failed for args=${safeStringify(args)}: ${errorMessage(error)}`, {
+    throw new Error(`${toolName} failed for args=${safeStringify(args)}: ${errorMessage3(error)}`, {
       cause: error
     });
   }
@@ -9624,7 +9999,7 @@ async function startMcpServer(options = {}) {
 }
 
 // src/cli/commands/mcp.ts
-function errorMessage2(error) {
+function errorMessage4(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function buildMcpCommand() {
@@ -9635,7 +10010,7 @@ function buildMcpCommand() {
     try {
       await startMcpServer({ registryPath: options.projects });
     } catch (error) {
-      console.error(`Failed to start MCP server: ${errorMessage2(error)}`);
+      console.error(`Failed to start MCP server: ${errorMessage4(error)}`);
       process.exit(1);
     }
   });
@@ -9649,7 +10024,7 @@ var import_commander13 = require("commander");
 var import_node_child_process7 = require("child_process");
 var import_node_crypto3 = require("crypto");
 var import_node_fs22 = __toESM(require("fs"), 1);
-var import_node_os6 = __toESM(require("os"), 1);
+var import_node_os7 = __toESM(require("os"), 1);
 var import_node_path26 = __toESM(require("path"), 1);
 var import_node_util = require("util");
 var execFileAsync = (0, import_node_util.promisify)(import_node_child_process7.execFile);
@@ -9815,7 +10190,7 @@ The download was rejected and discarded; re-run the install, and report it if it
 }
 async function installMacdriver(options = {}) {
   const version = validateMacdriverVersion(options.version ?? MACDRIVER_VERSION);
-  const homedir = options.homedir ?? import_node_os6.default.homedir();
+  const homedir = options.homedir ?? import_node_os7.default.homedir();
   const listArchiveEntries = options.listArchiveEntries ?? zipinfoArchiveLister;
   const extract = options.extract ?? dittoExtractor;
   const verifySignature = options.verifySignature ?? codesignVerifier;
@@ -9895,7 +10270,7 @@ var runVersionProbe = async (binaryPath) => {
 };
 async function collectMacdriverStatus(options = {}) {
   const env = options.env ?? process.env;
-  const homedir = options.homedir ?? import_node_os6.default.homedir();
+  const homedir = options.homedir ?? import_node_os7.default.homedir();
   const probe = options.probe ?? runVersionProbe;
   let resolved = null;
   try {
@@ -10008,10 +10383,402 @@ function buildMacdriverCommand() {
   return command;
 }
 
+// src/cli/commands/doctor.ts
+var import_chalk16 = __toESM(require("chalk"), 1);
+var import_commander14 = require("commander");
+
+// src/doctor/checks.ts
+var import_node_child_process8 = require("child_process");
+var import_node_module3 = require("module");
+var import_node_fs23 = __toESM(require("fs"), 1);
+var import_node_path27 = __toESM(require("path"), 1);
+var import_node_util2 = require("util");
+init_loader();
+var import_meta5 = {};
+var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process8.execFile);
+var MIN_NODE_MAJOR = 20;
+var CHECK_NODE = "Node.js version";
+var CHECK_PLAYWRIGHT = "Playwright installed";
+var CHECK_CHROMIUM = "Chromium browser";
+var CHECK_PROWL_DIR = ".prowl/ directory";
+var CHECK_CONFIG = "config.yml valid";
+var CHECK_MACOS = "macOS helper (prowl-macdriver)";
+var CHECK_IOS = "iOS tooling (xcrun simctl)";
+var CHECK_ANDROID = "Android tooling (adb)";
+var INSTALL_CHROMIUM_TIMEOUT_MS = 3e5;
+function nodeMajor(version) {
+  const cleaned = version.startsWith("v") ? version.slice(1) : version;
+  return Number.parseInt(cleaned.split(".")[0] ?? "", 10);
+}
+function checkNode(nodeVersion) {
+  const major = nodeMajor(nodeVersion);
+  if (Number.isFinite(major) && major >= MIN_NODE_MAJOR) {
+    return {
+      name: CHECK_NODE,
+      status: "pass",
+      message: `Node ${nodeVersion} (>= ${MIN_NODE_MAJOR} required)`,
+      fixable: false
+    };
+  }
+  return {
+    name: CHECK_NODE,
+    status: "fail",
+    message: `Node ${nodeVersion} is too old \u2014 Prowl needs Node >= ${MIN_NODE_MAJOR}. Upgrade with nvm (\`nvm install 20\`), Homebrew (\`brew install node\`), or nodejs.org.`,
+    fixable: false
+  };
+}
+function checkPlaywright(probe) {
+  if (probe.playwrightInstalled) {
+    return { name: CHECK_PLAYWRIGHT, status: "pass", message: "Playwright is installed", fixable: false };
+  }
+  return {
+    name: CHECK_PLAYWRIGHT,
+    status: "fail",
+    message: "Playwright is not installed. It ships as a dependency of prowl-tools \u2014 reinstall with `npm install` (local) or `npm install -g prowl-tools` (global).",
+    fixable: false
+  };
+}
+function checkChromium(probe) {
+  if (!probe.playwrightInstalled) {
+    return {
+      name: CHECK_CHROMIUM,
+      status: "skip",
+      message: "Skipped \u2014 Playwright is not installed",
+      fixable: false
+    };
+  }
+  if (probe.chromiumInstalled) {
+    return {
+      name: CHECK_CHROMIUM,
+      status: "pass",
+      message: `Chromium is available${probe.chromiumPath ? ` (${probe.chromiumPath})` : ""}`,
+      fixable: false
+    };
+  }
+  return {
+    name: CHECK_CHROMIUM,
+    status: "fail",
+    message: "Chromium is not installed. Run `npx playwright install chromium` (or `prowl doctor --fix`).",
+    fixable: true
+  };
+}
+function checkProwlDir(exists) {
+  if (exists) {
+    return { name: CHECK_PROWL_DIR, status: "pass", message: `${CONFIG_DIR}/ exists`, fixable: false };
+  }
+  return {
+    name: CHECK_PROWL_DIR,
+    status: "warn",
+    message: `No ${CONFIG_DIR}/ directory here. Run \`prowl init\` (or \`prowl doctor --fix\`) to scaffold config and starter hunts.`,
+    fixable: true
+  };
+}
+function checkConfig(prowlDirExists, loadConfig2) {
+  if (!prowlDirExists) {
+    return {
+      result: {
+        name: CHECK_CONFIG,
+        status: "skip",
+        message: `Skipped \u2014 no ${CONFIG_DIR}/ directory`,
+        fixable: false
+      },
+      config: null
+    };
+  }
+  try {
+    const { config } = loadConfig2();
+    return {
+      result: {
+        name: CHECK_CONFIG,
+        status: "pass",
+        message: `Valid (target: ${config.target.type})`,
+        fixable: false
+      },
+      config
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      result: {
+        name: CHECK_CONFIG,
+        status: "fail",
+        message: `Invalid config: ${detail}`,
+        fixable: false
+      },
+      config: null
+    };
+  }
+}
+function macdriverSourceLabel(source) {
+  switch (source) {
+    case "env":
+      return "PROWL_MACDRIVER_BIN override";
+    case "user-install":
+      return "user install (~/.prowl/macdriver)";
+    case "source-build":
+      return "repo source build";
+  }
+}
+async function checkMacTarget(collect2, env) {
+  let status;
+  try {
+    status = await collect2({ env });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      name: CHECK_MACOS,
+      status: "fail",
+      message: `Could not inspect prowl-macdriver status (${detail}). Run \`prowl macdriver status\` for details.`,
+      fixable: false
+    };
+  }
+  if (status.resolved && status.probedVersion) {
+    return {
+      name: CHECK_MACOS,
+      status: "pass",
+      message: `Resolved via ${macdriverSourceLabel(status.resolved.source)}: ${status.resolved.path} (reports ${status.probedVersion}). Verify Accessibility/Screen Recording permissions with \`prowl macdriver status\`.`,
+      fixable: false
+    };
+  }
+  if (status.resolved) {
+    return {
+      name: CHECK_MACOS,
+      status: "fail",
+      message: `prowl-macdriver resolved via ${macdriverSourceLabel(status.resolved.source)} (${status.resolved.path}), but the helper version probe failed. Run \`prowl macdriver status\` for details.`,
+      fixable: false
+    };
+  }
+  return {
+    name: CHECK_MACOS,
+    status: "fail",
+    message: "prowl-macdriver helper not found. Install it with `prowl macdriver install`, then check permissions with `prowl macdriver status`.",
+    fixable: false
+  };
+}
+async function checkIosTarget(platform, run) {
+  if (platform !== "darwin") {
+    return {
+      name: CHECK_IOS,
+      status: "fail",
+      message: `The iOS target requires macOS; xcrun simctl is unavailable on ${platform}.`,
+      fixable: false
+    };
+  }
+  try {
+    await run("xcrun", ["simctl", "help"]);
+    return { name: CHECK_IOS, status: "pass", message: "xcrun simctl is reachable", fixable: false };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      name: CHECK_IOS,
+      status: "fail",
+      message: `xcrun simctl is not reachable (${detail}). Install Xcode and its command-line tools (\`xcode-select --install\`), then open Xcode once to finish setup.`,
+      fixable: false
+    };
+  }
+}
+async function checkAndroidTarget(run) {
+  try {
+    await run("adb", ["version"]);
+    return { name: CHECK_ANDROID, status: "pass", message: "adb is reachable", fixable: false };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      name: CHECK_ANDROID,
+      status: "fail",
+      message: `adb is not reachable (${detail}). Install Android platform-tools and add it to your PATH (e.g. \`brew install --cask android-platform-tools\`, or via Android Studio's SDK Manager).`,
+      fixable: false
+    };
+  }
+}
+async function runDoctorChecks(deps) {
+  const results = [];
+  const probe = await deps.probePlaywright();
+  results.push(checkNode(deps.nodeVersion));
+  results.push(checkPlaywright(probe));
+  results.push(checkChromium(probe));
+  const prowlExists = deps.prowlDirExists(deps.cwd);
+  results.push(checkProwlDir(prowlExists));
+  const { result: configResult, config } = checkConfig(prowlExists, deps.loadConfig);
+  results.push(configResult);
+  if (config) {
+    switch (config.target.type) {
+      case "macos":
+        results.push(await checkMacTarget(deps.collectMacdriverStatus, deps.env));
+        break;
+      case "ios":
+        results.push(await checkIosTarget(deps.platform, deps.runCommand));
+        break;
+      case "android":
+        results.push(await checkAndroidTarget(deps.runCommand));
+        break;
+      default:
+        break;
+    }
+  }
+  return results;
+}
+async function runDoctor(deps, options = {}) {
+  let results = await runDoctorChecks(deps);
+  const fixes = [];
+  if (options.fix) {
+    for (const result of results) {
+      if (!result.fixable || result.status === "pass" || result.status === "skip") {
+        continue;
+      }
+      try {
+        if (result.name === CHECK_CHROMIUM) {
+          await deps.installChromium();
+          fixes.push({ name: result.name });
+        } else if (result.name === CHECK_PROWL_DIR) {
+          deps.scaffoldProwlDir(deps.cwd);
+          fixes.push({ name: result.name });
+        }
+      } catch (error) {
+        fixes.push({
+          name: result.name,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    if (fixes.length > 0) {
+      results = await runDoctorChecks(deps);
+    }
+  }
+  const ok = !results.some((result) => result.status === "fail");
+  return { results, fixes, ok };
+}
+async function defaultProbePlaywright() {
+  try {
+    const pw = await import("playwright");
+    let chromiumPath = null;
+    try {
+      chromiumPath = pw.chromium.executablePath();
+    } catch {
+      chromiumPath = null;
+    }
+    const chromiumInstalled = chromiumPath ? import_node_fs23.default.existsSync(chromiumPath) : false;
+    return { playwrightInstalled: true, chromiumPath, chromiumInstalled };
+  } catch {
+    return { playwrightInstalled: false, chromiumPath: null, chromiumInstalled: false };
+  }
+}
+var defaultRunCommand = async (file, args) => execFileAsync2(file, args, { timeout: 5e3 });
+function createLocalRequire() {
+  if (typeof __filename === "string") {
+    return (0, import_node_module3.createRequire)(__filename);
+  }
+  return (0, import_node_module3.createRequire)(import_meta5.url);
+}
+function resolvePlaywrightCliPath(requireFn = createLocalRequire()) {
+  return import_node_path27.default.join(import_node_path27.default.dirname(requireFn.resolve("playwright/package.json")), "cli.js");
+}
+function playwrightInstallChromiumCommand() {
+  return {
+    file: process.execPath,
+    args: [resolvePlaywrightCliPath(), "install", "chromium"]
+  };
+}
+async function defaultInstallChromium() {
+  const command = playwrightInstallChromiumCommand();
+  await execFileAsync2(command.file, command.args, { timeout: INSTALL_CHROMIUM_TIMEOUT_MS });
+}
+function defaultDoctorDeps() {
+  return {
+    nodeVersion: process.versions.node,
+    platform: process.platform,
+    cwd: process.cwd(),
+    env: process.env,
+    probePlaywright: defaultProbePlaywright,
+    runCommand: defaultRunCommand,
+    prowlDirExists: (cwd) => import_node_fs23.default.existsSync(import_node_path27.default.join(cwd, CONFIG_DIR)),
+    loadConfig: () => loadConfig(),
+    collectMacdriverStatus,
+    installChromium: defaultInstallChromium,
+    scaffoldProwlDir
+  };
+}
+
+// src/cli/commands/doctor.ts
+function symbol(status) {
+  switch (status) {
+    case "pass":
+      return import_chalk16.default.green("\u2713");
+    // ✓
+    case "fail":
+      return import_chalk16.default.red("\u2717");
+    // ✗
+    case "warn":
+      return import_chalk16.default.yellow("\u26A0");
+    // ⚠
+    case "skip":
+      return import_chalk16.default.gray("\u25CB");
+  }
+}
+function renderResult(result) {
+  console.log(`  ${symbol(result.status)} ${import_chalk16.default.bold(result.name)}`);
+  console.log(`      ${import_chalk16.default.gray(result.message)}`);
+}
+function renderReport(report, fixRequested) {
+  console.log(import_chalk16.default.bold("\nprowl doctor\n"));
+  for (const result of report.results) {
+    renderResult(result);
+  }
+  if (fixRequested) {
+    console.log("");
+    if (report.fixes.length === 0) {
+      console.log(import_chalk16.default.gray("  No auto-fixable issues to repair."));
+    } else {
+      console.log(import_chalk16.default.bold("  Attempted fixes:"));
+      for (const fix of report.fixes) {
+        if (fix.error) {
+          console.log(`    ${import_chalk16.default.red("\u2717")} ${fix.name} \u2014 ${import_chalk16.default.gray(fix.error)}`);
+        } else {
+          console.log(`    ${import_chalk16.default.green("\u2713")} ${fix.name}`);
+        }
+      }
+    }
+  }
+  const counts = { pass: 0, warn: 0, fail: 0, skip: 0 };
+  for (const result of report.results) {
+    counts[result.status] += 1;
+  }
+  const parts = [
+    import_chalk16.default.green(`${counts.pass} passed`),
+    counts.warn > 0 ? import_chalk16.default.yellow(`${counts.warn} warning${counts.warn === 1 ? "" : "s"}`) : null,
+    counts.fail > 0 ? import_chalk16.default.red(`${counts.fail} failed`) : null,
+    counts.skip > 0 ? import_chalk16.default.gray(`${counts.skip} skipped`) : null
+  ].filter((part) => part !== null);
+  console.log("\n  " + parts.join(import_chalk16.default.gray(", ")));
+  if (counts.fail > 0) {
+    console.log(import_chalk16.default.red.bold("  Environment has problems \u2014 fix the failures above, then re-run `prowl doctor`.\n"));
+  } else if (counts.warn > 0) {
+    console.log(import_chalk16.default.yellow.bold("  Environment is usable, with warnings.\n"));
+  } else {
+    console.log(import_chalk16.default.green.bold("  Environment is healthy.\n"));
+  }
+}
+function buildDoctorCommand(deps = defaultDoctorDeps()) {
+  return new import_commander14.Command("doctor").description("Check that your environment is set up to run Prowl hunts").option("--fix", "Attempt safe auto-repairs: install Chromium and scaffold a missing .prowl/").action(async (options) => {
+    try {
+      const report = await runDoctor(deps, { fix: options.fix });
+      renderReport(report, Boolean(options.fix));
+      if (!report.ok) {
+        process.exitCode = 1;
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "doctor failed";
+      console.error(import_chalk16.default.red(`Error: ${message}
+Re-run \`prowl doctor\`; if it fails again, report the error.`));
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/cli/program.ts
 var CLI_VERSION = package_default.version;
 function buildProgram() {
-  const program2 = new import_commander14.Command();
+  const program2 = new import_commander15.Command();
   program2.name("prowl").description("CLI-first QA testing tool for deterministic Playwright flows").version(CLI_VERSION);
   program2.addCommand(buildRunCommand());
   program2.addCommand(buildCiCommand());
@@ -10026,6 +10793,7 @@ function buildProgram() {
   program2.addCommand(buildFlakyCommand());
   program2.addCommand(buildMcpCommand());
   program2.addCommand(buildMacdriverCommand());
+  program2.addCommand(buildDoctorCommand());
   return program2;
 }