prowl-tools 0.1.7 → 0.1.9

package/dist/index.cjs

@@ -398,575 +398,136 @@ var init_schema = __esm({
   }
 });
 
-// src/config/loader.ts
-var loader_exports = {};
-__export(loader_exports, {
-  CONFIG_DIR: () => CONFIG_DIR,
-  LEGACY_CONFIG_DIR: () => LEGACY_CONFIG_DIR,
-  ensureAllowedDomain: () => ensureAllowedDomain,
-  findConfigPath: () => findConfigPath,
-  listHunts: () => listHunts,
-  loadConfig: () => loadConfig,
-  loadHunt: () => loadHunt,
-  loadHuntMeta: () => loadHuntMeta,
-  loadHuntTags: () => loadHuntTags,
-  resolveViewport: () => resolveViewport,
-  warnLegacyConfigDir: () => warnLegacyConfigDir
-});
-function warnLegacyConfigDir() {
-  if (legacyDirWarned) {
+// src/config/interpolate.ts
+function collectInterpolatedValues(input, vars, values) {
+  if (typeof input === "string") {
+    for (const match of input.matchAll(VAR_PATTERN)) {
+      const varValue = vars[match[1]];
+      if (varValue) values.add(varValue);
+    }
     return;
   }
-  legacyDirWarned = true;
-  console.warn(
-    'Warning: the ".prowlqa/" config directory is deprecated; rename it to ".prowl/". Support for ".prowlqa/" will be removed in a future release.'
-  );
-}
-function findConfigPath(startDir) {
-  let current = startDir;
-  while (current) {
-    for (const dir of [CONFIG_DIR, LEGACY_CONFIG_DIR]) {
-      const candidate = import_node_path.default.join(current, dir, "config.yml");
-      if (import_node_fs.default.existsSync(candidate)) {
-        return candidate;
-      }
+  if (Array.isArray(input)) {
+    for (const item of input) {
+      collectInterpolatedValues(item, vars, values);
     }
-    const parent = import_node_path.default.dirname(current);
-    if (parent === current) {
-      break;
+    return;
+  }
+  if (input && typeof input === "object") {
+    for (const [key, value] of Object.entries(input)) {
+      collectInterpolatedValues(key, vars, values);
+      collectInterpolatedValues(value, vars, values);
     }
-    current = parent;
   }
-  return null;
 }
-function resolveViewport(value) {
-  if (value === void 0) {
-    return DEFAULT_CONFIG.browser.viewport;
-  }
-  if (typeof value === "string") {
-    const preset = VIEWPORT_PRESETS[value];
-    if (!preset) {
-      throw new Error(`Unknown viewport preset: "${value}". Use mobile, tablet, or desktop.`);
+function interpolateString(input, vars) {
+  const usedVars = [];
+  const value = input.replace(VAR_PATTERN, (_, name) => {
+    const varValue = vars[name];
+    if (varValue === void 0) {
+      throw new Error(`Missing variable: ${name}`);
     }
-    return preset;
-  }
-  return value;
+    usedVars.push(name);
+    return varValue;
+  });
+  return { value, usedVars };
 }
-function resolveTarget(target) {
-  const type = target?.type;
-  if (type === "macos") {
-    return { type: "macos", app: target.app };
+function generateRandomVars(randomSource) {
+  const random = randomSource?.random ?? Math.random;
+  const randomBytes = randomSource?.randomBytes ?? import_node_crypto.default.randomBytes;
+  const randomUUID = randomSource?.randomUUID ?? import_node_crypto.default.randomUUID;
+  const hex = randomBytes(4).toString("hex");
+  const firstIndex = Math.floor(random() * RANDOM_FIRST_NAMES.length);
+  const lastIndex = Math.floor(random() * RANDOM_LAST_NAMES.length);
+  const num2 = Math.floor(random() * 9e3) + 1e3;
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let text = "";
+  for (let i = 0; i < 8; i++) {
+    text += chars[Math.floor(random() * chars.length)];
   }
-  if (type === "android") {
-    const androidTarget = target;
+  return {
+    RANDOM_EMAIL: `prowl_${hex}@test.com`,
+    RANDOM_NAME: `${RANDOM_FIRST_NAMES[firstIndex]} ${RANDOM_LAST_NAMES[lastIndex]}`,
+    RANDOM_NUMBER: String(num2),
+    RANDOM_UUID: randomUUID(),
+    RANDOM_TEXT: text
+  };
+}
+function interpolateStep(step, vars, stepPath2, redacted) {
+  const isExplicitFill = (value) => typeof value.selector === "string" && typeof value.value === "string";
+  const interpolateSinglePair = (record) => {
+    const entries = Object.entries(record);
+    if (entries.length !== 1) {
+      throw new Error("Shorthand step expects exactly one key-value pair");
+    }
+    const [key, value] = entries[0];
     return {
-      type: "android",
-      app: androidTarget.app,
-      ...androidTarget.deviceSerial !== void 0 ? { deviceSerial: androidTarget.deviceSerial } : {},
-      ...androidTarget.coldStart !== void 0 ? { coldStart: androidTarget.coldStart } : {}
+      [interpolateString(key, vars).value]: interpolateString(value, vars).value
     };
+  };
+  if ("navigate" in step) {
+    const result = interpolateString(step.navigate, vars);
+    return { navigate: result.value };
   }
-  if (type === "ios") {
-    const iosTarget = target;
+  if ("click" in step) {
+    if (typeof step.click === "string") {
+      return { click: interpolateString(step.click, vars).value };
+    }
+    const result = interpolateString(step.click.selector, vars);
+    return { click: { selector: result.value } };
+  }
+  if ("fill" in step) {
+    if (isExplicitFill(step.fill)) {
+      const selectorResult = interpolateString(step.fill.selector, vars);
+      const valueResult2 = interpolateString(step.fill.value, vars);
+      if (valueResult2.usedVars.length > 0) {
+        redacted.add(stepPath2);
+      }
+      return { fill: { selector: selectorResult.value, value: valueResult2.value } };
+    }
+    const [rawLabel, rawValue] = Object.entries(step.fill)[0] ?? [];
+    if (rawLabel === void 0 || rawValue === void 0) {
+      throw new Error("Shorthand fill expects exactly one key-value pair");
+    }
+    const labelResult = interpolateString(rawLabel, vars);
+    const valueResult = interpolateString(rawValue, vars);
+    if (valueResult.usedVars.length > 0) {
+      redacted.add(stepPath2);
+    }
     return {
-      type: "ios",
-      app: iosTarget.app,
-      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
-      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
+      fill: {
+        [labelResult.value]: valueResult.value
+      }
     };
   }
-  return {
-    type: "web",
-    url: target?.url ?? DEFAULT_WEB_URL
-  };
-}
-function mergeConfig(partial) {
-  return {
-    target: resolveTarget(partial.target),
-    browser: {
-      headless: partial.browser?.headless ?? DEFAULT_CONFIG.browser.headless,
-      slowMo: partial.browser?.slowMo ?? DEFAULT_CONFIG.browser.slowMo,
-      timeout: partial.browser?.timeout ?? DEFAULT_CONFIG.browser.timeout,
-      engine: partial.browser?.engine ?? DEFAULT_CONFIG.browser.engine,
-      channel: partial.browser?.channel,
-      viewport: resolveViewport(partial.browser?.viewport)
-    },
-    artifacts: {
-      screenshots: partial.artifacts?.screenshots ?? DEFAULT_CONFIG.artifacts.screenshots,
-      networkHar: partial.artifacts?.networkHar ?? DEFAULT_CONFIG.artifacts.networkHar,
-      console: partial.artifacts?.console ?? DEFAULT_CONFIG.artifacts.console,
-      junit: partial.artifacts?.junit ?? DEFAULT_CONFIG.artifacts.junit
-    },
-    assertions: {
-      noConsoleErrors: partial.assertions?.noConsoleErrors ?? DEFAULT_CONFIG.assertions.noConsoleErrors,
-      noNetworkErrors: partial.assertions?.noNetworkErrors ?? DEFAULT_CONFIG.assertions.noNetworkErrors,
-      maxTotalTimeMs: partial.assertions?.maxTotalTimeMs ?? DEFAULT_CONFIG.assertions.maxTotalTimeMs,
-      networkIgnorePatterns: partial.assertions?.networkIgnorePatterns ?? DEFAULT_CONFIG.assertions.networkIgnorePatterns
-    },
-    guardrails: {
-      maxSteps: partial.guardrails?.maxSteps ?? DEFAULT_CONFIG.guardrails.maxSteps,
-      allowedDomains: partial.guardrails?.allowedDomains ?? DEFAULT_CONFIG.guardrails.allowedDomains,
-      allowedApps: partial.guardrails?.allowedApps ?? DEFAULT_CONFIG.guardrails.allowedApps,
-      forbiddenSelectors: partial.guardrails?.forbiddenSelectors ?? DEFAULT_CONFIG.guardrails.forbiddenSelectors,
-      selfHealing: partial.guardrails?.selfHealing ?? DEFAULT_CONFIG.guardrails.selfHealing
-    },
-    auth: {
-      storageStatePath: partial.auth?.storageStatePath ?? (partial.auth !== void 0 ? DEFAULT_CONFIG.auth.storageStatePath : void 0)
-    },
-    history: {
-      maxRuns: partial.history?.maxRuns ?? DEFAULT_CONFIG.history.maxRuns
-    },
-    bugLog: partial.bugLog,
-    tracing: partial.tracing,
-    reliability: partial.reliability
-  };
-}
-function ensureAllowedDomain(allowed, urlValue) {
-  try {
-    const host = new URL(urlValue).hostname;
-    if (!allowed.includes(host)) {
-      return [...allowed, host];
+  if ("type" in step) {
+    const valueResult = interpolateString(step.type, vars);
+    if (valueResult.usedVars.length > 0) {
+      redacted.add(stepPath2);
     }
-  } catch {
-    return allowed;
+    return { type: valueResult.value };
   }
-  return allowed;
-}
-function loadConfig(configPath) {
-  const resolvedPath = configPath ? import_node_path.default.resolve(configPath) : findConfigPath(process.cwd());
-  if (!resolvedPath) {
-    throw new Error("Could not find .prowl/config.yml. Run `prowl init` first.");
+  if ("selectOption" in step) {
+    const selectorResult = interpolateString(step.selectOption.selector, vars);
+    const valueResult = interpolateString(step.selectOption.value, vars);
+    return { selectOption: { selector: selectorResult.value, value: valueResult.value } };
   }
-  if (!import_node_fs.default.existsSync(resolvedPath)) {
-    throw new Error(`Config file not found at ${resolvedPath}`);
+  if ("select" in step) {
+    return { select: interpolateSinglePair(step.select) };
   }
-  const configDir = import_node_path.default.dirname(resolvedPath);
-  if (import_node_path.default.basename(configDir) === LEGACY_CONFIG_DIR) {
-    warnLegacyConfigDir();
+  if ("press" in step) {
+    const selectorResult = interpolateString(step.press.selector, vars);
+    const keyResult = interpolateString(step.press.key, vars);
+    return { press: { selector: selectorResult.value, key: keyResult.value } };
   }
-  import_dotenv.default.config({ path: import_node_path.default.join(configDir, ".env"), override: false });
-  const raw = import_node_fs.default.readFileSync(resolvedPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  const validated = configSchema.parse(parsed);
-  const config = mergeConfig(validated);
-  if (config.target.type === "web") {
-    config.guardrails.allowedDomains = ensureAllowedDomain(
-      config.guardrails.allowedDomains,
-      config.target.url
-    );
+  if ("onDialog" in step) {
+    return { onDialog: { action: step.onDialog.action } };
   }
-  return { config, configPath: resolvedPath, configDir };
-}
-function loadHunt(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs.default.existsSync(huntPath)) {
-    throw new Error(`Hunt file not found: ${huntPath}`);
-  }
-  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  const validated = huntSchema.parse(parsed);
-  return validated;
-}
-function loadHuntTags(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs.default.existsSync(huntPath)) {
-    return [];
-  }
-  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  return Array.isArray(parsed.tags) ? parsed.tags : [];
-}
-function loadHuntMeta(huntName, configDir) {
-  assertValidHuntName(huntName);
-  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
-  if (!import_node_fs.default.existsSync(huntPath)) {
-    return { tags: [] };
-  }
-  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
-  const parsed = import_yaml.default.parse(raw) ?? {};
-  return {
-    description: typeof parsed.description === "string" ? parsed.description : void 0,
-    tags: Array.isArray(parsed.tags) ? parsed.tags : []
-  };
-}
-function listHunts(configDir) {
-  const huntsDir = import_node_path.default.join(configDir, "hunts");
-  if (!import_node_fs.default.existsSync(huntsDir)) {
-    return [];
-  }
-  const stats = import_node_fs.default.statSync(huntsDir);
-  if (!stats.isDirectory()) {
-    throw new Error(`Hunts path is not a directory: ${huntsDir}`);
-  }
-  const results = [];
-  function scanDir(dir) {
-    const entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith(".yml")) {
-        const fullPath = import_node_path.default.join(dir, entry.name);
-        const relative = import_node_path.default.relative(huntsDir, fullPath);
-        results.push(relative.replace(/\.yml$/, ""));
-      } else if (entry.isDirectory()) {
-        scanDir(import_node_path.default.join(dir, entry.name));
-      }
-    }
-  }
-  scanDir(huntsDir);
-  return results.sort((a, b) => a.localeCompare(b));
-}
-var import_node_fs, import_node_path, import_yaml, import_dotenv, DEFAULT_WEB_URL, DEFAULT_CONFIG, CONFIG_DIR, LEGACY_CONFIG_DIR, legacyDirWarned, VIEWPORT_PRESETS;
-var init_loader = __esm({
-  "src/config/loader.ts"() {
-    "use strict";
-    import_node_fs = __toESM(require("fs"), 1);
-    import_node_path = __toESM(require("path"), 1);
-    import_yaml = __toESM(require("yaml"), 1);
-    import_dotenv = __toESM(require("dotenv"), 1);
-    init_schema();
-    init_hunt_name();
-    DEFAULT_WEB_URL = "http://localhost:3000";
-    DEFAULT_CONFIG = {
-      target: {
-        type: "web",
-        url: DEFAULT_WEB_URL
-      },
-      browser: {
-        headless: true,
-        slowMo: 0,
-        timeout: 3e4,
-        engine: "chromium",
-        viewport: { width: 1280, height: 720 }
-      },
-      artifacts: {
-        screenshots: "on-failure",
-        networkHar: false,
-        console: true,
-        junit: false
-      },
-      assertions: {
-        noConsoleErrors: true,
-        noNetworkErrors: true,
-        maxTotalTimeMs: 3e4,
-        networkIgnorePatterns: []
-      },
-      guardrails: {
-        maxSteps: 50,
-        allowedDomains: ["localhost", "127.0.0.1", "0.0.0.0"],
-        allowedApps: [],
-        forbiddenSelectors: ["[data-danger]", ".delete-btn"],
-        selfHealing: false
-      },
-      auth: {
-        storageStatePath: ".prowl/auth-state.json"
-      },
-      history: {
-        maxRuns: 100
-      }
-    };
-    CONFIG_DIR = ".prowl";
-    LEGACY_CONFIG_DIR = ".prowlqa";
-    legacyDirWarned = false;
-    VIEWPORT_PRESETS = {
-      mobile: { width: 375, height: 812 },
-      tablet: { width: 768, height: 1024 },
-      desktop: { width: 1280, height: 720 }
-    };
-  }
-});
-
-// src/runner/visual.ts
-var visual_exports = {};
-__export(visual_exports, {
-  compareScreenshots: () => compareScreenshots,
-  ensureBaselineDir: () => ensureBaselineDir
-});
-async function compareScreenshots(baselinePath, currentPath, diffPath, threshold) {
-  const baselineData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(baselinePath));
-  const currentData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(currentPath));
-  const { width, height } = baselineData;
-  if (currentData.width !== width || currentData.height !== height) {
-    const diff2 = new import_pngjs.PNG({ width, height });
-    import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff2));
-    return {
-      match: false,
-      diffPercentage: 1,
-      diffImagePath: diffPath
-    };
-  }
-  const diff = new import_pngjs.PNG({ width, height });
-  const diffPixels = (0, import_pixelmatch.default)(
-    baselineData.data,
-    currentData.data,
-    diff.data,
-    width,
-    height,
-    { threshold: 0.1 }
-  );
-  const totalPixels = width * height;
-  const diffPercentage = diffPixels / totalPixels;
-  import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff));
-  return {
-    match: diffPercentage <= threshold,
-    diffPercentage,
-    diffImagePath: diffPath
-  };
-}
-function ensureBaselineDir(configDir) {
-  const baselineDir = import_node_path9.default.join(configDir, "baselines");
-  import_node_fs8.default.mkdirSync(baselineDir, { recursive: true });
-  return baselineDir;
-}
-var import_node_fs8, import_node_path9, import_pngjs, import_pixelmatch;
-var init_visual = __esm({
-  "src/runner/visual.ts"() {
-    "use strict";
-    import_node_fs8 = __toESM(require("fs"), 1);
-    import_node_path9 = __toESM(require("path"), 1);
-    import_pngjs = require("pngjs");
-    import_pixelmatch = __toESM(require("pixelmatch"), 1);
-  }
-});
-
-// src/cli/program.ts
-var import_commander14 = require("commander");
-
-// package.json
-var package_default = {
-  name: "prowl-tools",
-  version: "0.1.7",
-  description: "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
-  type: "module",
-  license: "Apache-2.0",
-  author: "Prowl Tools",
-  repository: {
-    type: "git",
-    url: "https://github.com/prowl-tools/prowl.git"
-  },
-  homepage: "https://prowl.tools",
-  bugs: {
-    url: "https://github.com/prowl-tools/prowl/issues"
-  },
-  keywords: [
-    "testing",
-    "qa",
-    "e2e",
-    "macos",
-    "desktop-testing",
-    "accessibility",
-    "playwright",
-    "yaml",
-    "browser-testing",
-    "automation",
-    "web-testing",
-    "cli"
-  ],
-  main: "dist/lib.cjs",
-  module: "dist/lib.js",
-  types: "dist/lib.d.ts",
-  exports: {
-    ".": {
-      import: {
-        types: "./dist/lib.d.ts",
-        default: "./dist/lib.js"
-      },
-      require: {
-        types: "./dist/lib.d.cts",
-        default: "./dist/lib.cjs"
-      }
-    }
-  },
-  bin: {
-    prowl: "dist/index.js"
-  },
-  files: [
-    "dist",
-    "examples",
-    "LICENSE",
-    "README.md",
-    "NOTICE"
-  ],
-  engines: {
-    node: ">=20.0.0"
-  },
-  scripts: {
-    build: "tsup",
-    lint: "eslint .",
-    test: "vitest run",
-    "test:watch": "vitest"
-  },
-  dependencies: {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    chalk: "^5.3.0",
-    commander: "^12.1.0",
-    dotenv: "^16.6.1",
-    ora: "^8.1.1",
-    pixelmatch: "^7.1.0",
-    playwright: "^1.50.1",
-    pngjs: "^7.0.0",
-    yaml: "^2.6.1",
-    zod: "^3.23.8"
-  },
-  optionalDependencies: {
-    "appium-uiautomator2-server": "10.6.2",
-    "appium-webdriveragent": "16.4.0"
-  },
-  devDependencies: {
-    "@types/node": "^22.13.1",
-    "@types/pngjs": "^6.0.5",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    eslint: "^8.57.1",
-    tsup: "^8.3.5",
-    typescript: "^5.7.3",
-    vitest: "^2.1.8"
-  }
-};
-
-// src/cli/commands/run.ts
-var import_commander = require("commander");
-var import_chalk3 = __toESM(require("chalk"), 1);
-
-// src/runner/index.ts
-var import_node_fs14 = __toESM(require("fs"), 1);
-var import_node_path15 = __toESM(require("path"), 1);
-init_loader();
-
-// src/config/interpolate.ts
-var import_node_crypto = __toESM(require("crypto"), 1);
-var VAR_PATTERN = /\{\{([A-Z0-9_]+)\}\}/g;
-function collectInterpolatedValues(input, vars, values) {
-  if (typeof input === "string") {
-    for (const match of input.matchAll(VAR_PATTERN)) {
-      const varValue = vars[match[1]];
-      if (varValue) values.add(varValue);
-    }
-    return;
-  }
-  if (Array.isArray(input)) {
-    for (const item of input) {
-      collectInterpolatedValues(item, vars, values);
-    }
-    return;
-  }
-  if (input && typeof input === "object") {
-    for (const [key, value] of Object.entries(input)) {
-      collectInterpolatedValues(key, vars, values);
-      collectInterpolatedValues(value, vars, values);
-    }
-  }
-}
-function interpolateString(input, vars) {
-  const usedVars = [];
-  const value = input.replace(VAR_PATTERN, (_, name) => {
-    const varValue = vars[name];
-    if (varValue === void 0) {
-      throw new Error(`Missing variable: ${name}`);
-    }
-    usedVars.push(name);
-    return varValue;
-  });
-  return { value, usedVars };
-}
-var RANDOM_FIRST_NAMES = ["Alex", "Jordan", "Morgan", "Taylor", "Casey", "Riley", "Quinn", "Avery"];
-var RANDOM_LAST_NAMES = ["Smith", "Johnson", "Brown", "Davis", "Wilson", "Clark", "Hall", "Young"];
-function generateRandomVars(randomSource) {
-  const random = randomSource?.random ?? Math.random;
-  const randomBytes = randomSource?.randomBytes ?? import_node_crypto.default.randomBytes;
-  const randomUUID = randomSource?.randomUUID ?? import_node_crypto.default.randomUUID;
-  const hex = randomBytes(4).toString("hex");
-  const firstIndex = Math.floor(random() * RANDOM_FIRST_NAMES.length);
-  const lastIndex = Math.floor(random() * RANDOM_LAST_NAMES.length);
-  const num2 = Math.floor(random() * 9e3) + 1e3;
-  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
-  let text = "";
-  for (let i = 0; i < 8; i++) {
-    text += chars[Math.floor(random() * chars.length)];
-  }
-  return {
-    RANDOM_EMAIL: `prowl_${hex}@test.com`,
-    RANDOM_NAME: `${RANDOM_FIRST_NAMES[firstIndex]} ${RANDOM_LAST_NAMES[lastIndex]}`,
-    RANDOM_NUMBER: String(num2),
-    RANDOM_UUID: randomUUID(),
-    RANDOM_TEXT: text
-  };
-}
-function interpolateStep(step, vars, stepPath2, redacted) {
-  const isExplicitFill = (value) => typeof value.selector === "string" && typeof value.value === "string";
-  const interpolateSinglePair = (record) => {
-    const entries = Object.entries(record);
-    if (entries.length !== 1) {
-      throw new Error("Shorthand step expects exactly one key-value pair");
-    }
-    const [key, value] = entries[0];
-    return {
-      [interpolateString(key, vars).value]: interpolateString(value, vars).value
-    };
-  };
-  if ("navigate" in step) {
-    const result = interpolateString(step.navigate, vars);
-    return { navigate: result.value };
-  }
-  if ("click" in step) {
-    if (typeof step.click === "string") {
-      return { click: interpolateString(step.click, vars).value };
-    }
-    const result = interpolateString(step.click.selector, vars);
-    return { click: { selector: result.value } };
-  }
-  if ("fill" in step) {
-    if (isExplicitFill(step.fill)) {
-      const selectorResult = interpolateString(step.fill.selector, vars);
-      const valueResult2 = interpolateString(step.fill.value, vars);
-      if (valueResult2.usedVars.length > 0) {
-        redacted.add(stepPath2);
-      }
-      return { fill: { selector: selectorResult.value, value: valueResult2.value } };
-    }
-    const [rawLabel, rawValue] = Object.entries(step.fill)[0] ?? [];
-    if (rawLabel === void 0 || rawValue === void 0) {
-      throw new Error("Shorthand fill expects exactly one key-value pair");
-    }
-    const labelResult = interpolateString(rawLabel, vars);
-    const valueResult = interpolateString(rawValue, vars);
-    if (valueResult.usedVars.length > 0) {
-      redacted.add(stepPath2);
-    }
-    return {
-      fill: {
-        [labelResult.value]: valueResult.value
-      }
-    };
-  }
-  if ("type" in step) {
-    const valueResult = interpolateString(step.type, vars);
-    if (valueResult.usedVars.length > 0) {
-      redacted.add(stepPath2);
-    }
-    return { type: valueResult.value };
-  }
-  if ("selectOption" in step) {
-    const selectorResult = interpolateString(step.selectOption.selector, vars);
-    const valueResult = interpolateString(step.selectOption.value, vars);
-    return { selectOption: { selector: selectorResult.value, value: valueResult.value } };
-  }
-  if ("select" in step) {
-    return { select: interpolateSinglePair(step.select) };
-  }
-  if ("press" in step) {
-    const selectorResult = interpolateString(step.press.selector, vars);
-    const keyResult = interpolateString(step.press.key, vars);
-    return { press: { selector: selectorResult.value, key: keyResult.value } };
-  }
-  if ("onDialog" in step) {
-    return { onDialog: { action: step.onDialog.action } };
-  }
-  if ("setInputFiles" in step) {
-    const selectorResult = interpolateString(step.setInputFiles.selector, vars);
-    const rawFiles = step.setInputFiles.files;
-    const files = Array.isArray(rawFiles) ? rawFiles.map((f) => interpolateString(f, vars).value) : interpolateString(rawFiles, vars).value;
-    return { setInputFiles: { selector: selectorResult.value, files } };
+  if ("setInputFiles" in step) {
+    const selectorResult = interpolateString(step.setInputFiles.selector, vars);
+    const rawFiles = step.setInputFiles.files;
+    const files = Array.isArray(rawFiles) ? rawFiles.map((f) => interpolateString(f, vars).value) : interpolateString(rawFiles, vars).value;
+    return { setInputFiles: { selector: selectorResult.value, files } };
   }
   if ("runHunt" in step) {
     if (typeof step.runHunt === "string") {
@@ -1114,95 +675,562 @@ function interpolateStep(step, vars, stepPath2, redacted) {
       }
     };
   }
-  if ("runScript" in step) {
-    return {
-      runScript: { file: interpolateString(step.runScript.file, vars).value }
-    };
+  if ("runScript" in step) {
+    return {
+      runScript: { file: interpolateString(step.runScript.file, vars).value }
+    };
+  }
+  if ("assertScreenshot" in step) {
+    return {
+      assertScreenshot: {
+        name: interpolateString(step.assertScreenshot.name, vars).value,
+        ...step.assertScreenshot.threshold !== void 0 ? { threshold: step.assertScreenshot.threshold } : {}
+      }
+    };
+  }
+  if ("assertWithAI" in step) {
+    return {
+      assertWithAI: interpolateString(step.assertWithAI, vars).value
+    };
+  }
+  if ("copyText" in step) {
+    return {
+      copyText: {
+        selector: interpolateString(step.copyText.selector, vars).value,
+        as: step.copyText.as
+      }
+    };
+  }
+  if ("waitForDownload" in step) {
+    if (step.waitForDownload === null) {
+      return { waitForDownload: null };
+    }
+    return {
+      waitForDownload: {
+        ...step.waitForDownload.filename !== void 0 ? { filename: interpolateString(step.waitForDownload.filename, vars).value } : {},
+        ...step.waitForDownload.timeout !== void 0 ? { timeout: step.waitForDownload.timeout } : {}
+      }
+    };
+  }
+  return step;
+}
+function interpolateAssertion(assertion, vars) {
+  if ("selectorExists" in assertion) {
+    return { selectorExists: interpolateString(assertion.selectorExists, vars).value };
+  }
+  if ("selectorNotExists" in assertion) {
+    return { selectorNotExists: interpolateString(assertion.selectorNotExists, vars).value };
+  }
+  if ("urlIncludes" in assertion) {
+    return { urlIncludes: interpolateString(assertion.urlIncludes, vars).value };
+  }
+  if ("urlEquals" in assertion) {
+    return { urlEquals: interpolateString(assertion.urlEquals, vars).value };
+  }
+  if ("noConsoleErrors" in assertion) {
+    return { noConsoleErrors: assertion.noConsoleErrors };
+  }
+  if ("noNetworkErrors" in assertion) {
+    return { noNetworkErrors: assertion.noNetworkErrors };
+  }
+  return assertion;
+}
+function interpolateHunt(hunt, env, randomVars = generateRandomVars()) {
+  const redactedFillSteps = /* @__PURE__ */ new Set();
+  const envVars = Object.fromEntries(
+    Object.entries(env).filter(([, value]) => value !== void 0)
+  );
+  const baseVars = { ...randomVars, ...envVars };
+  const resolvedHuntVars = {};
+  for (const [key, value] of Object.entries(hunt.vars ?? {})) {
+    resolvedHuntVars[key] = interpolateString(value, baseVars).value;
+  }
+  const vars = { ...baseVars, ...resolvedHuntVars };
+  const redactionValues = /* @__PURE__ */ new Set();
+  collectInterpolatedValues(hunt.steps, vars, redactionValues);
+  collectInterpolatedValues(hunt.assertions, vars, redactionValues);
+  const steps = hunt.steps.map(
+    (step, index) => interpolateStep(step, vars, `${index}`, redactedFillSteps)
+  );
+  const assertions = hunt.assertions?.map((assertion) => interpolateAssertion(assertion, vars));
+  return {
+    hunt: {
+      ...hunt,
+      steps,
+      assertions
+    },
+    redactedFillSteps,
+    randomVars,
+    redactionValues: [...redactionValues]
+  };
+}
+var import_node_crypto, VAR_PATTERN, RANDOM_FIRST_NAMES, RANDOM_LAST_NAMES;
+var init_interpolate = __esm({
+  "src/config/interpolate.ts"() {
+    "use strict";
+    import_node_crypto = __toESM(require("crypto"), 1);
+    VAR_PATTERN = /\{\{([A-Z0-9_]+)\}\}/g;
+    RANDOM_FIRST_NAMES = ["Alex", "Jordan", "Morgan", "Taylor", "Casey", "Riley", "Quinn", "Avery"];
+    RANDOM_LAST_NAMES = ["Smith", "Johnson", "Brown", "Davis", "Wilson", "Clark", "Hall", "Young"];
+  }
+});
+
+// src/config/loader.ts
+var loader_exports = {};
+__export(loader_exports, {
+  CONFIG_DIR: () => CONFIG_DIR,
+  LEGACY_CONFIG_DIR: () => LEGACY_CONFIG_DIR,
+  ensureAllowedDomain: () => ensureAllowedDomain,
+  findConfigPath: () => findConfigPath,
+  listHunts: () => listHunts,
+  loadConfig: () => loadConfig,
+  loadHunt: () => loadHunt,
+  loadHuntMeta: () => loadHuntMeta,
+  loadHuntTags: () => loadHuntTags,
+  resolveViewport: () => resolveViewport,
+  warnLegacyConfigDir: () => warnLegacyConfigDir
+});
+function warnLegacyConfigDir() {
+  if (legacyDirWarned) {
+    return;
+  }
+  legacyDirWarned = true;
+  console.warn(
+    'Warning: the ".prowlqa/" config directory is deprecated; rename it to ".prowl/". Support for ".prowlqa/" will be removed in a future release.'
+  );
+}
+function findConfigPath(startDir) {
+  let current = startDir;
+  while (current) {
+    for (const dir of [CONFIG_DIR, LEGACY_CONFIG_DIR]) {
+      const candidate = import_node_path.default.join(current, dir, "config.yml");
+      if (import_node_fs.default.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    const parent = import_node_path.default.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return null;
+}
+function resolveViewport(value) {
+  if (value === void 0) {
+    return DEFAULT_CONFIG.browser.viewport;
+  }
+  if (typeof value === "string") {
+    const preset = VIEWPORT_PRESETS[value];
+    if (!preset) {
+      throw new Error(`Unknown viewport preset: "${value}". Use mobile, tablet, or desktop.`);
+    }
+    return preset;
+  }
+  return value;
+}
+function resolveTarget(target) {
+  const type = target?.type;
+  if (type === "macos") {
+    return { type: "macos", app: target.app };
   }
-  if ("assertScreenshot" in step) {
+  if (type === "android") {
+    const androidTarget = target;
     return {
-      assertScreenshot: {
-        name: interpolateString(step.assertScreenshot.name, vars).value,
-        ...step.assertScreenshot.threshold !== void 0 ? { threshold: step.assertScreenshot.threshold } : {}
-      }
+      type: "android",
+      app: androidTarget.app,
+      ...androidTarget.deviceSerial !== void 0 ? { deviceSerial: androidTarget.deviceSerial } : {},
+      ...androidTarget.coldStart !== void 0 ? { coldStart: androidTarget.coldStart } : {}
     };
   }
-  if ("assertWithAI" in step) {
+  if (type === "ios") {
+    const iosTarget = target;
     return {
-      assertWithAI: interpolateString(step.assertWithAI, vars).value
+      type: "ios",
+      app: iosTarget.app,
+      ...iosTarget.udid !== void 0 ? { udid: iosTarget.udid } : {},
+      ...iosTarget.coldStart !== void 0 ? { coldStart: iosTarget.coldStart } : {}
     };
   }
-  if ("copyText" in step) {
-    return {
-      copyText: {
-        selector: interpolateString(step.copyText.selector, vars).value,
-        as: step.copyText.as
-      }
-    };
+  return {
+    type: "web",
+    url: target?.url ?? DEFAULT_WEB_URL
+  };
+}
+function mergeConfig(partial) {
+  return {
+    target: resolveTarget(partial.target),
+    browser: {
+      headless: partial.browser?.headless ?? DEFAULT_CONFIG.browser.headless,
+      slowMo: partial.browser?.slowMo ?? DEFAULT_CONFIG.browser.slowMo,
+      timeout: partial.browser?.timeout ?? DEFAULT_CONFIG.browser.timeout,
+      engine: partial.browser?.engine ?? DEFAULT_CONFIG.browser.engine,
+      channel: partial.browser?.channel,
+      viewport: resolveViewport(partial.browser?.viewport)
+    },
+    artifacts: {
+      screenshots: partial.artifacts?.screenshots ?? DEFAULT_CONFIG.artifacts.screenshots,
+      networkHar: partial.artifacts?.networkHar ?? DEFAULT_CONFIG.artifacts.networkHar,
+      console: partial.artifacts?.console ?? DEFAULT_CONFIG.artifacts.console,
+      junit: partial.artifacts?.junit ?? DEFAULT_CONFIG.artifacts.junit
+    },
+    assertions: {
+      noConsoleErrors: partial.assertions?.noConsoleErrors ?? DEFAULT_CONFIG.assertions.noConsoleErrors,
+      noNetworkErrors: partial.assertions?.noNetworkErrors ?? DEFAULT_CONFIG.assertions.noNetworkErrors,
+      maxTotalTimeMs: partial.assertions?.maxTotalTimeMs ?? DEFAULT_CONFIG.assertions.maxTotalTimeMs,
+      networkIgnorePatterns: partial.assertions?.networkIgnorePatterns ?? DEFAULT_CONFIG.assertions.networkIgnorePatterns
+    },
+    guardrails: {
+      maxSteps: partial.guardrails?.maxSteps ?? DEFAULT_CONFIG.guardrails.maxSteps,
+      allowedDomains: partial.guardrails?.allowedDomains ?? DEFAULT_CONFIG.guardrails.allowedDomains,
+      allowedApps: partial.guardrails?.allowedApps ?? DEFAULT_CONFIG.guardrails.allowedApps,
+      forbiddenSelectors: partial.guardrails?.forbiddenSelectors ?? DEFAULT_CONFIG.guardrails.forbiddenSelectors,
+      selfHealing: partial.guardrails?.selfHealing ?? DEFAULT_CONFIG.guardrails.selfHealing
+    },
+    auth: {
+      storageStatePath: partial.auth?.storageStatePath ?? (partial.auth !== void 0 ? DEFAULT_CONFIG.auth.storageStatePath : void 0)
+    },
+    history: {
+      maxRuns: partial.history?.maxRuns ?? DEFAULT_CONFIG.history.maxRuns
+    },
+    bugLog: partial.bugLog,
+    tracing: partial.tracing,
+    reliability: partial.reliability
+  };
+}
+function envStringVars(env) {
+  return Object.fromEntries(
+    Object.entries(env).filter(([, value]) => value !== void 0)
+  );
+}
+function interpolateConfigStrings(value, vars) {
+  if (typeof value === "string") {
+    return interpolateString(value, vars).value;
   }
-  if ("waitForDownload" in step) {
-    if (step.waitForDownload === null) {
-      return { waitForDownload: null };
+  if (Array.isArray(value)) {
+    return value.map((item) => interpolateConfigStrings(item, vars));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, interpolateConfigStrings(item, vars)])
+    );
+  }
+  return value;
+}
+function ensureAllowedDomain(allowed, urlValue) {
+  try {
+    const host = new URL(urlValue).hostname;
+    if (!allowed.includes(host)) {
+      return [...allowed, host];
     }
-    return {
-      waitForDownload: {
-        ...step.waitForDownload.filename !== void 0 ? { filename: interpolateString(step.waitForDownload.filename, vars).value } : {},
-        ...step.waitForDownload.timeout !== void 0 ? { timeout: step.waitForDownload.timeout } : {}
-      }
-    };
+  } catch {
+    return allowed;
   }
-  return step;
+  return allowed;
 }
-function interpolateAssertion(assertion, vars) {
-  if ("selectorExists" in assertion) {
-    return { selectorExists: interpolateString(assertion.selectorExists, vars).value };
+function loadConfig(configPath) {
+  const resolvedPath = configPath ? import_node_path.default.resolve(configPath) : findConfigPath(process.cwd());
+  if (!resolvedPath) {
+    throw new Error("Could not find .prowl/config.yml. Run `prowl init` first.");
   }
-  if ("selectorNotExists" in assertion) {
-    return { selectorNotExists: interpolateString(assertion.selectorNotExists, vars).value };
+  if (!import_node_fs.default.existsSync(resolvedPath)) {
+    throw new Error(`Config file not found at ${resolvedPath}`);
   }
-  if ("urlIncludes" in assertion) {
-    return { urlIncludes: interpolateString(assertion.urlIncludes, vars).value };
+  const configDir = import_node_path.default.dirname(resolvedPath);
+  if (import_node_path.default.basename(configDir) === LEGACY_CONFIG_DIR) {
+    warnLegacyConfigDir();
   }
-  if ("urlEquals" in assertion) {
-    return { urlEquals: interpolateString(assertion.urlEquals, vars).value };
+  import_dotenv.default.config({ path: import_node_path.default.join(configDir, ".env"), override: false });
+  const raw = import_node_fs.default.readFileSync(resolvedPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  const interpolated = interpolateConfigStrings(parsed, envStringVars(process.env));
+  const validated = configSchema.parse(interpolated);
+  const config = mergeConfig(validated);
+  if (config.target.type === "web") {
+    config.guardrails.allowedDomains = ensureAllowedDomain(
+      config.guardrails.allowedDomains,
+      config.target.url
+    );
   }
-  if ("noConsoleErrors" in assertion) {
-    return { noConsoleErrors: assertion.noConsoleErrors };
+  return { config, configPath: resolvedPath, configDir };
+}
+function loadHunt(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs.default.existsSync(huntPath)) {
+    throw new Error(`Hunt file not found: ${huntPath}`);
   }
-  if ("noNetworkErrors" in assertion) {
-    return { noNetworkErrors: assertion.noNetworkErrors };
+  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  const validated = huntSchema.parse(parsed);
+  return validated;
+}
+function loadHuntTags(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs.default.existsSync(huntPath)) {
+    return [];
+  }
+  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  return Array.isArray(parsed.tags) ? parsed.tags : [];
+}
+function loadHuntMeta(huntName, configDir) {
+  assertValidHuntName(huntName);
+  const huntPath = import_node_path.default.join(configDir, "hunts", `${huntName}.yml`);
+  if (!import_node_fs.default.existsSync(huntPath)) {
+    return { tags: [] };
+  }
+  const raw = import_node_fs.default.readFileSync(huntPath, "utf-8");
+  const parsed = import_yaml.default.parse(raw) ?? {};
+  return {
+    description: typeof parsed.description === "string" ? parsed.description : void 0,
+    tags: Array.isArray(parsed.tags) ? parsed.tags : []
+  };
+}
+function listHunts(configDir) {
+  const huntsDir = import_node_path.default.join(configDir, "hunts");
+  if (!import_node_fs.default.existsSync(huntsDir)) {
+    return [];
+  }
+  const stats = import_node_fs.default.statSync(huntsDir);
+  if (!stats.isDirectory()) {
+    throw new Error(`Hunts path is not a directory: ${huntsDir}`);
+  }
+  const results = [];
+  function scanDir(dir) {
+    const entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".yml")) {
+        const fullPath = import_node_path.default.join(dir, entry.name);
+        const relative = import_node_path.default.relative(huntsDir, fullPath);
+        results.push(relative.replace(/\.yml$/, ""));
+      } else if (entry.isDirectory()) {
+        scanDir(import_node_path.default.join(dir, entry.name));
+      }
+    }
+  }
+  scanDir(huntsDir);
+  return results.sort((a, b) => a.localeCompare(b));
+}
+var import_node_fs, import_node_path, import_yaml, import_dotenv, DEFAULT_WEB_URL, DEFAULT_CONFIG, CONFIG_DIR, LEGACY_CONFIG_DIR, legacyDirWarned, VIEWPORT_PRESETS;
+var init_loader = __esm({
+  "src/config/loader.ts"() {
+    "use strict";
+    import_node_fs = __toESM(require("fs"), 1);
+    import_node_path = __toESM(require("path"), 1);
+    import_yaml = __toESM(require("yaml"), 1);
+    import_dotenv = __toESM(require("dotenv"), 1);
+    init_schema();
+    init_hunt_name();
+    init_interpolate();
+    DEFAULT_WEB_URL = "http://localhost:3000";
+    DEFAULT_CONFIG = {
+      target: {
+        type: "web",
+        url: DEFAULT_WEB_URL
+      },
+      browser: {
+        headless: true,
+        slowMo: 0,
+        timeout: 3e4,
+        engine: "chromium",
+        viewport: { width: 1280, height: 720 }
+      },
+      artifacts: {
+        screenshots: "on-failure",
+        networkHar: false,
+        console: true,
+        junit: false
+      },
+      assertions: {
+        noConsoleErrors: true,
+        noNetworkErrors: true,
+        maxTotalTimeMs: 3e4,
+        networkIgnorePatterns: []
+      },
+      guardrails: {
+        maxSteps: 50,
+        allowedDomains: ["localhost", "127.0.0.1", "0.0.0.0"],
+        allowedApps: [],
+        forbiddenSelectors: ["[data-danger]", ".delete-btn"],
+        selfHealing: false
+      },
+      auth: {
+        storageStatePath: ".prowl/auth-state.json"
+      },
+      history: {
+        maxRuns: 100
+      }
+    };
+    CONFIG_DIR = ".prowl";
+    LEGACY_CONFIG_DIR = ".prowlqa";
+    legacyDirWarned = false;
+    VIEWPORT_PRESETS = {
+      mobile: { width: 375, height: 812 },
+      tablet: { width: 768, height: 1024 },
+      desktop: { width: 1280, height: 720 }
+    };
   }
-  return assertion;
-}
-function interpolateHunt(hunt, env, randomVars = generateRandomVars()) {
-  const redactedFillSteps = /* @__PURE__ */ new Set();
-  const envVars = Object.fromEntries(
-    Object.entries(env).filter(([, value]) => value !== void 0)
-  );
-  const baseVars = { ...randomVars, ...envVars };
-  const resolvedHuntVars = {};
-  for (const [key, value] of Object.entries(hunt.vars ?? {})) {
-    resolvedHuntVars[key] = interpolateString(value, baseVars).value;
+});
+
+// src/runner/visual.ts
+var visual_exports = {};
+__export(visual_exports, {
+  compareScreenshots: () => compareScreenshots,
+  ensureBaselineDir: () => ensureBaselineDir
+});
+async function compareScreenshots(baselinePath, currentPath, diffPath, threshold) {
+  const baselineData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(baselinePath));
+  const currentData = import_pngjs.PNG.sync.read(import_node_fs8.default.readFileSync(currentPath));
+  const { width, height } = baselineData;
+  if (currentData.width !== width || currentData.height !== height) {
+    const diff2 = new import_pngjs.PNG({ width, height });
+    import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff2));
+    return {
+      match: false,
+      diffPercentage: 1,
+      diffImagePath: diffPath
+    };
   }
-  const vars = { ...baseVars, ...resolvedHuntVars };
-  const redactionValues = /* @__PURE__ */ new Set();
-  collectInterpolatedValues(hunt.steps, vars, redactionValues);
-  collectInterpolatedValues(hunt.assertions, vars, redactionValues);
-  const steps = hunt.steps.map(
-    (step, index) => interpolateStep(step, vars, `${index}`, redactedFillSteps)
+  const diff = new import_pngjs.PNG({ width, height });
+  const diffPixels = (0, import_pixelmatch.default)(
+    baselineData.data,
+    currentData.data,
+    diff.data,
+    width,
+    height,
+    { threshold: 0.1 }
   );
-  const assertions = hunt.assertions?.map((assertion) => interpolateAssertion(assertion, vars));
+  const totalPixels = width * height;
+  const diffPercentage = diffPixels / totalPixels;
+  import_node_fs8.default.writeFileSync(diffPath, import_pngjs.PNG.sync.write(diff));
   return {
-    hunt: {
-      ...hunt,
-      steps,
-      assertions
-    },
-    redactedFillSteps,
-    randomVars,
-    redactionValues: [...redactionValues]
+    match: diffPercentage <= threshold,
+    diffPercentage,
+    diffImagePath: diffPath
   };
 }
+function ensureBaselineDir(configDir) {
+  const baselineDir = import_node_path9.default.join(configDir, "baselines");
+  import_node_fs8.default.mkdirSync(baselineDir, { recursive: true });
+  return baselineDir;
+}
+var import_node_fs8, import_node_path9, import_pngjs, import_pixelmatch;
+var init_visual = __esm({
+  "src/runner/visual.ts"() {
+    "use strict";
+    import_node_fs8 = __toESM(require("fs"), 1);
+    import_node_path9 = __toESM(require("path"), 1);
+    import_pngjs = require("pngjs");
+    import_pixelmatch = __toESM(require("pixelmatch"), 1);
+  }
+});
+
+// src/cli/program.ts
+var import_commander15 = require("commander");
+
+// package.json
+var package_default = {
+  name: "prowl-tools",
+  version: "0.1.9",
+  description: "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
+  type: "module",
+  license: "Apache-2.0",
+  author: "Prowl Tools",
+  repository: {
+    type: "git",
+    url: "https://github.com/prowl-tools/prowl.git"
+  },
+  homepage: "https://prowl.tools",
+  bugs: {
+    url: "https://github.com/prowl-tools/prowl/issues"
+  },
+  keywords: [
+    "testing",
+    "qa",
+    "e2e",
+    "macos",
+    "desktop-testing",
+    "accessibility",
+    "playwright",
+    "yaml",
+    "browser-testing",
+    "automation",
+    "web-testing",
+    "cli"
+  ],
+  main: "dist/lib.cjs",
+  module: "dist/lib.js",
+  types: "dist/lib.d.ts",
+  exports: {
+    ".": {
+      import: {
+        types: "./dist/lib.d.ts",
+        default: "./dist/lib.js"
+      },
+      require: {
+        types: "./dist/lib.d.cts",
+        default: "./dist/lib.cjs"
+      }
+    }
+  },
+  bin: {
+    prowl: "dist/index.js"
+  },
+  files: [
+    "dist",
+    "examples",
+    "LICENSE",
+    "README.md",
+    "NOTICE"
+  ],
+  engines: {
+    node: ">=20.0.0"
+  },
+  scripts: {
+    build: "tsup",
+    lint: "eslint .",
+    test: "vitest run",
+    "test:watch": "vitest"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    chalk: "^5.3.0",
+    commander: "^12.1.0",
+    dotenv: "^16.6.1",
+    ora: "^8.1.1",
+    pixelmatch: "^7.1.0",
+    playwright: "^1.50.1",
+    pngjs: "^7.0.0",
+    yaml: "^2.6.1",
+    zod: "^3.23.8"
+  },
+  optionalDependencies: {
+    "appium-uiautomator2-server": "10.6.2",
+    "appium-webdriveragent": "16.4.0"
+  },
+  devDependencies: {
+    "@types/node": "^22.13.1",
+    "@types/pngjs": "^6.0.5",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    eslint: "^8.57.1",
+    tsup: "^8.3.5",
+    typescript: "^5.7.3",
+    vitest: "^2.1.8"
+  }
+};
+
+// src/cli/commands/run.ts
+var import_commander = require("commander");
+var import_chalk3 = __toESM(require("chalk"), 1);
+
+// src/runner/index.ts
+var import_node_fs14 = __toESM(require("fs"), 1);
+var import_node_path15 = __toESM(require("path"), 1);
+init_loader();
+init_interpolate();
 
 // src/config/target.ts
 var import_node_child_process = require("child_process");
@@ -1220,10 +1248,17 @@ var WEB_ONLY_STEP_TYPES = /* @__PURE__ */ new Set([
   "select",
   "selectOption",
   "setInputFiles",
-  "waitForDownload",
-  "scroll"
-  // directional scroll runs window.scrollBy (evaluate) — use scrollTo instead
+  "waitForDownload"
 ]);
+var MACOS_UNSUPPORTED_STEP_TYPES = /* @__PURE__ */ new Set(["scroll"]);
+function macosUnsupportedReason(step) {
+  for (const type of MACOS_UNSUPPORTED_STEP_TYPES) {
+    if (type in step) {
+      return type;
+    }
+  }
+  return null;
+}
 function webOnlyReason(step) {
   for (const type of WEB_ONLY_STEP_TYPES) {
     if (type in step) {
@@ -1259,6 +1294,14 @@ function assertStepsSupportedByTarget(steps, target) {
         `Step "${reason}" is not supported by the ${label} target. It is web-only; use a portable step (click, fill, type, press, wait, assert visible, screenshot, etc.).`
       );
     }
+    if (target === "macos") {
+      const macReason = macosUnsupportedReason(step);
+      if (macReason) {
+        throw new Error(
+          `Step "${macReason}" is not supported by the macOS target. Directional scroll is a touch swipe available on the iOS and Android targets; there is no macOS accessibility equivalent (use scrollTo to bring a specific element into view instead).`
+        );
+      }
+    }
     if ("if" in step) {
       assertStepsSupportedByTarget(step.if.then, target);
       if (step.if.else) {
@@ -1542,6 +1585,16 @@ function createPlaywrightDriver(page) {
     async hover(selector) {
       await page.locator(selector).hover();
     },
+    async scroll(direction, amount = 500) {
+      const deltas = {
+        up: [0, -amount],
+        down: [0, amount],
+        left: [-amount, 0],
+        right: [amount, 0]
+      };
+      const [x, y] = deltas[direction];
+      await page.evaluate(([sx, sy]) => window.scrollBy(sx, sy), [x, y]);
+    },
     async scrollIntoView(selector) {
       await page.locator(selector).scrollIntoViewIfNeeded();
     },
@@ -1736,6 +1789,9 @@ function createMacDriver(client, options = {}) {
     async hover(selector) {
       await query("hover", selector);
     },
+    scroll() {
+      return rejectUnsupported("scroll");
+    },
     async scrollIntoView(selector) {
       await query("scrollTo", selector);
     },
@@ -1894,10 +1950,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;
@@ -1905,6 +1966,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");
@@ -1941,6 +2005,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;
@@ -1957,6 +2025,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);
@@ -2269,6 +2349,101 @@ function rankNativeSelectors(fields) {
   return selectors;
 }
 
+// src/browser/touch-gestures.ts
+var DEFAULT_SWIPE_FRACTION = 0.75;
+var SCROLL_TO_PROBE_SWIPE_FRACTION = 0.6;
+var MAX_SWIPE_FRACTION = 0.9;
+var SWIPE_HOLD_MS = 100;
+var SWIPE_MOVE_DURATION_MS = 300;
+var SCROLL_TO_SWEEP_DEPTH = 10;
+var SCROLL_TO_PROBE_DIRECTIONS = [
+  ...Array.from({ length: SCROLL_TO_SWEEP_DEPTH }, () => "down"),
+  ...Array.from({ length: SCROLL_TO_SWEEP_DEPTH * 2 }, () => "up")
+];
+var MAX_SCROLL_TO_SWIPES = SCROLL_TO_PROBE_DIRECTIONS.length;
+var OPPOSITE_SWIPE_DIRECTIONS = {
+  up: "down",
+  down: "up",
+  left: "right",
+  right: "left"
+};
+async function probeScrollIntoView({
+  isVisible,
+  swipe,
+  directions = SCROLL_TO_PROBE_DIRECTIONS
+}) {
+  if (await isVisible()) {
+    return true;
+  }
+  for (const direction of directions) {
+    await swipe(direction);
+    if (await isVisible()) {
+      return true;
+    }
+  }
+  return false;
+}
+function toScreenSize(value, source) {
+  const record = value ?? {};
+  const width = Number(record.width);
+  const height = Number(record.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new Error(`${source} did not return a usable screen size`);
+  }
+  return { width, height };
+}
+function isVertical(direction) {
+  return direction === "up" || direction === "down";
+}
+function swipeDistanceFor(direction, size, amount) {
+  if (amount !== void 0 && !Number.isFinite(amount)) {
+    throw new Error("scroll amount must be a finite number");
+  }
+  const axis = isVertical(direction) ? size.height : size.width;
+  const requested = amount === void 0 ? axis * DEFAULT_SWIPE_FRACTION : Math.abs(amount);
+  const max = axis * MAX_SWIPE_FRACTION;
+  return Math.max(1, Math.round(Math.min(requested, max)));
+}
+function scrollToProbeDistanceFor(direction, size) {
+  const axis = isVertical(direction) ? size.height : size.width;
+  return Math.max(1, Math.round(axis * SCROLL_TO_PROBE_SWIPE_FRACTION));
+}
+function swipeEndpoints(direction, size, distance) {
+  const cx = Math.round(size.width / 2);
+  const cy = Math.round(size.height / 2);
+  const half = Math.round(distance / 2);
+  switch (direction) {
+    case "down":
+      return { start: { x: cx, y: cy + half }, end: { x: cx, y: cy - half } };
+    case "up":
+      return { start: { x: cx, y: cy - half }, end: { x: cx, y: cy + half } };
+    case "right":
+      return { start: { x: cx + half, y: cy }, end: { x: cx - half, y: cy } };
+    case "left":
+      return { start: { x: cx - half, y: cy }, end: { x: cx + half, y: cy } };
+  }
+}
+function buildSwipeActions(start, end) {
+  return {
+    type: "pointer",
+    id: "finger1",
+    parameters: { pointerType: "touch" },
+    actions: [
+      { type: "pointerMove", duration: 0, x: start.x, y: start.y, origin: "viewport" },
+      { type: "pointerDown", button: 0 },
+      { type: "pause", duration: SWIPE_HOLD_MS },
+      { type: "pointerMove", duration: SWIPE_MOVE_DURATION_MS, x: end.x, y: end.y, origin: "viewport" },
+      { type: "pointerUp", button: 0 }
+    ]
+  };
+}
+function buildDirectionalSwipe(direction, size, amount) {
+  const normalizedDirection = amount !== void 0 && amount < 0 ? OPPOSITE_SWIPE_DIRECTIONS[direction] : direction;
+  const distance = swipeDistanceFor(normalizedDirection, size, amount);
+  const { start, end } = swipeEndpoints(normalizedDirection, size, distance);
+  return { actions: buildSwipeActions(start, end), distance, start, end };
+}
+
 // src/browser/android-driver.ts
 var ANDROID_CAPABILITIES = /* @__PURE__ */ new Set([
   "query",
@@ -2384,6 +2559,11 @@ function createAndroidDriver(client, options = {}) {
   async function fillSelector(selector, value) {
     await client.setValue(await resolveOne(selector), value);
   }
+  async function swipe(direction, amount, size) {
+    const actualSize = size ?? await client.windowSize();
+    const { actions } = buildDirectionalSwipe(direction, actualSize, amount);
+    await client.performActions(actions);
+  }
   return {
     capabilities: ANDROID_CAPABILITIES,
     // navigation -----------------------------------------------------------
@@ -2421,8 +2601,31 @@ function createAndroidDriver(client, options = {}) {
     hover() {
       return rejectUnsupported("hover");
     },
-    scrollIntoView() {
-      return rejectUnsupported("scrollTo");
+    // Screen-centred swipe via the W3C actions endpoint (PROWL-080). Direction
+    // semantics match the web step: scrolling "down" reveals lower content, so
+    // the finger drags up. See ./touch-gestures.ts.
+    async scroll(direction, amount) {
+      await swipe(direction, amount);
+    },
+    // Resolve the element, short-circuiting if it is already present in the
+    // hierarchy; otherwise use the shared bounded down/up mobile probe before
+    // failing with a message naming the selector and attempts.
+    async scrollIntoView(selector) {
+      const query = parseAndroidSelector(selector);
+      let probeSize;
+      const found = await probeScrollIntoView({
+        isVisible: async () => (await client.findElements(query)).length > 0,
+        swipe: async (direction) => {
+          probeSize ??= await client.windowSize();
+          await swipe(direction, scrollToProbeDistanceFor(direction, probeSize), probeSize);
+        }
+      });
+      if (found) {
+        return;
+      }
+      throw new Error(
+        `scrollTo: element "${selector}" not visible after ${MAX_SCROLL_TO_SWIPES} scroll attempts on the Android target`
+      );
     },
     setInputFiles() {
       return rejectUnsupported("setInputFiles");
@@ -2745,12 +2948,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, {
@@ -2762,7 +2965,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 {
@@ -2773,7 +2976,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
       );
@@ -2856,10 +3059,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 })
     );
   }
@@ -2894,6 +3097,13 @@ function createUia2AgentClient(transport, sessionId, options = {}) {
     async pressKeyCode(keyCode) {
       await transport.request("POST", `${base}/appium/device/press_keycode`, { keycode: keyCode });
     },
+    async windowSize() {
+      const value = await transport.request("GET", `${base}/window/current/size`);
+      return toScreenSize(value, "uiautomator2 /window/current/size");
+    },
+    async performActions(actions) {
+      await transport.request("POST", `${base}/actions`, { actions: [actions] });
+    },
     async screenshotPng() {
       const value = await transport.request("GET", `${base}/screenshot`);
       if (typeof value !== "string") {
@@ -3038,6 +3248,7 @@ async function launchAndroidSession(options) {
       readyDeadlineMs,
       appPackage: pkg
     });
+    await launchPackage(runner, serial, pkg);
     const driver = createAndroidDriver(client, { appLabel: pkg });
     return { client, driver, package: pkg, serial, teardown };
   } catch (error) {
@@ -3065,6 +3276,7 @@ var IOS_CAPABILITIES = /* @__PURE__ */ new Set([
 ]);
 var WAIT_POLL_INTERVAL_MS2 = 250;
 var DEFAULT_WAIT_TIMEOUT_MS2 = 5e3;
+var DISPLAYED_CHECK_CONCURRENCY = 4;
 var IOS_PRESS_KEYS = ["backspace", "del", "delete", "enter", "home", "return"];
 function escapePredicateArg(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -3139,6 +3351,64 @@ function createIosDriver(client, options) {
   async function fillSelector(selector, value) {
     await client.setValue(await resolveOne(selector), value);
   }
+  async function swipe(direction, amount, size) {
+    const actualSize = size ?? await client.windowSize();
+    const { actions } = buildDirectionalSwipe(direction, actualSize, amount);
+    await client.performActions(actions);
+  }
+  async function visibleElementIds(query) {
+    const ids = await client.findElements(query);
+    const visible = Array.from({ length: ids.length }, () => null);
+    let nextIndex = 0;
+    const workerCount = Math.min(DISPLAYED_CHECK_CONCURRENCY, ids.length);
+    await Promise.all(
+      Array.from({ length: workerCount }, async () => {
+        for (; ; ) {
+          const index = nextIndex;
+          nextIndex += 1;
+          if (index >= ids.length) {
+            return;
+          }
+          const id = ids[index];
+          if (await client.isDisplayed(id)) {
+            visible[index] = id;
+          }
+        }
+      })
+    );
+    return visible.filter((id) => id !== null);
+  }
+  async function hasVisibleElement(query) {
+    const ids = await client.findElements(query);
+    if (ids.length === 0) {
+      return false;
+    }
+    if (await client.isDisplayed(ids[0])) {
+      return true;
+    }
+    let found = false;
+    let nextIndex = 1;
+    const workerCount = Math.min(DISPLAYED_CHECK_CONCURRENCY, ids.length - 1);
+    await Promise.all(
+      Array.from({ length: workerCount }, async () => {
+        for (; ; ) {
+          if (found) {
+            return;
+          }
+          const index = nextIndex;
+          nextIndex += 1;
+          if (index >= ids.length) {
+            return;
+          }
+          if (await client.isDisplayed(ids[index])) {
+            found = true;
+            return;
+          }
+        }
+      })
+    );
+    return found;
+  }
   async function pressKey(key) {
     const name = key.trim().toLowerCase();
     if (name === "enter" || name === "return") {
@@ -3170,6 +3440,9 @@ function createIosDriver(client, options) {
     async count(selector) {
       return (await client.findElements(parseIosSelector(selector))).length;
     },
+    async visibleCount(selector) {
+      return (await visibleElementIds(parseIosSelector(selector))).length;
+    },
     async textContent(selector) {
       const id = await client.findElement(parseIosSelector(selector));
       if (id === null) {
@@ -3194,15 +3467,38 @@ function createIosDriver(client, options) {
     hover() {
       return rejectUnsupported("hover");
     },
-    scrollIntoView() {
-      return rejectUnsupported("scrollTo");
+    // Screen-centred swipe via the W3C actions endpoint (PROWL-080). Direction
+    // semantics match the web step: scrolling "down" reveals lower content, so
+    // the finger drags up. See ./touch-gestures.ts.
+    async scroll(direction, amount) {
+      await swipe(direction, amount);
+    },
+    // Resolve the element, short-circuiting only if WDA reports a matching
+    // element displayed in the viewport; hierarchy-only matches can be offscreen.
+    // Otherwise use the shared bounded down/up mobile probe before failing.
+    async scrollIntoView(selector) {
+      const query = parseIosSelector(selector);
+      let probeSize;
+      const found = await probeScrollIntoView({
+        isVisible: () => hasVisibleElement(query),
+        swipe: async (direction) => {
+          probeSize ??= await client.windowSize();
+          await swipe(direction, scrollToProbeDistanceFor(direction, probeSize), probeSize);
+        }
+      });
+      if (found) {
+        return;
+      }
+      throw new Error(
+        `scrollTo: element "${selector}" not visible after ${MAX_SCROLL_TO_SWIPES} scroll attempts on the iOS target`
+      );
     },
     setInputFiles() {
       return rejectUnsupported("setInputFiles");
     },
     // semantic locators ----------------------------------------------------
     async countByRole(role, name) {
-      return (await client.findElements({ by: "role", role, name })).length;
+      return (await visibleElementIds({ by: "role", role, name })).length;
     },
     async clickFirstByRole(role, name) {
       const id = await client.findElement({ by: "role", role, name });
@@ -3212,7 +3508,7 @@ function createIosDriver(client, options) {
       await client.click(id);
     },
     async countByLabel(label) {
-      return (await client.findElements({ by: "label", value: label })).length;
+      return (await visibleElementIds({ by: "label", value: label })).length;
     },
     async fillFirstByLabel(label, value) {
       const id = await client.findElement({ by: "label", value: label });
@@ -3230,7 +3526,7 @@ function createIosDriver(client, options) {
       const timeoutMs = waitOptions?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS2;
       const deadline = Date.now() + timeoutMs;
       for (; ; ) {
-        if ((await client.findElements(query)).length > 0) {
+        if (await hasVisibleElement(query)) {
           return;
         }
         if (Date.now() >= deadline) {
@@ -3567,15 +3863,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 {
@@ -3607,7 +3903,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
       );
@@ -3615,8 +3911,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;
   }
 };
@@ -3692,8 +3988,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) {
@@ -3723,12 +4019,29 @@ function createWdaAgentClient(transport, sessionId) {
       const value = await transport.request("GET", `${base}/element/${elementId}/text`);
       return typeof value === "string" ? value : value == null ? null : String(value);
     },
+    async isDisplayed(elementId) {
+      try {
+        return await transport.request("GET", `${base}/element/${elementId}/displayed`) === true;
+      } catch (error) {
+        if (isNoSuchElement2(error)) {
+          return false;
+        }
+        throw error;
+      }
+    },
     async sendKeys(keys) {
       await transport.request("POST", `${base}/wda/keys`, { value: keys });
     },
     async homescreen() {
       await transport.request("POST", "/wda/homescreen", {});
     },
+    async windowSize() {
+      const value = await transport.request("GET", `${base}/window/size`);
+      return toScreenSize(value, "WebDriverAgent /window/size");
+    },
+    async performActions(actions) {
+      await transport.request("POST", `${base}/actions`, { actions: [actions] });
+    },
     async source() {
       const value = await transport.request("GET", "/source");
       if (typeof value !== "string") {
@@ -4082,6 +4395,7 @@ async function closeIosSession(session) {
 var import_node_fs9 = __toESM(require("fs"), 1);
 var import_node_path10 = __toESM(require("path"), 1);
 init_loader();
+init_interpolate();
 
 // src/runner/healing.ts
 var INTERACTIVE_TAGS = ["button", "a", "input", "select", "textarea"];
@@ -4779,11 +5093,14 @@ function toVisibilitySelector(value) {
   if (looksLikeSelector(value)) return value;
   return textContainsSelector(value);
 }
+function countVisible(driver, selector) {
+  return driver.visibleCount?.(selector) ?? driver.count(selector);
+}
 async function runInlineAssert(driver, policy, assertion) {
   if (assertion.visible !== void 0) {
     const selector = toVisibilitySelector(assertion.visible);
     policy.assertAllowedSelector(selector);
-    const count = await driver.count(selector);
+    const count = await countVisible(driver, selector);
     if (count === 0) {
       throw new Error(`Expected visible: ${assertion.visible}`);
     }
@@ -4792,7 +5109,7 @@ async function runInlineAssert(driver, policy, assertion) {
   if (assertion.notVisible !== void 0) {
     const selector = toVisibilitySelector(assertion.notVisible);
     policy.assertAllowedSelector(selector);
-    const count = await driver.count(selector);
+    const count = await countVisible(driver, selector);
     if (count > 0) {
       throw new Error(`Expected not visible: ${assertion.notVisible}`);
     }
@@ -5182,25 +5499,21 @@ var STEP_HANDLERS = {
     }
   },
   scroll: {
-    capabilities: ["evaluate"],
+    // Dispatched through the driver's `scroll` verb (interact), so native mobile
+    // targets synthesize a touch swipe while web keeps its `window.scrollBy`
+    // behavior. The per-target step gate rejects `scroll` on macOS before here.
+    capabilities: ["interact"],
     run: async (h) => {
       if (!("scroll" in h.step)) unknownStep();
-      const amount = h.step.scroll.amount ?? 500;
-      const scrollMap = {
-        up: [0, -amount],
-        down: [0, amount],
-        left: [-amount, 0],
-        right: [amount, 0]
-      };
-      const [x, y] = scrollMap[h.step.scroll.direction];
-      await h.driver.evaluate(([sx, sy]) => window.scrollBy(sx, sy), [x, y]);
+      const { direction, amount } = h.step.scroll;
+      await h.driver.scroll(direction, amount);
       return {
         kind: "result",
         result: {
           type: "scroll",
           status: "pass",
           durationMs: Date.now() - h.stepStart,
-          value: `${h.step.scroll.direction} ${amount}px`
+          value: amount === void 0 ? direction : `${direction} ${amount}px`
         }
       };
     }
@@ -5246,7 +5559,7 @@ var STEP_HANDLERS = {
       const condition = h.step.if;
       const selector = condition.visible ?? condition.notVisible;
       h.policy.assertAllowedSelector(selector);
-      const count = await h.driver.count(selector);
+      const count = await countVisible(h.driver, selector);
       const conditionMet = condition.visible !== void 0 ? count > 0 : count === 0;
       if (conditionMet) {
         const subResult = await h.executeNested({
@@ -5333,7 +5646,7 @@ var STEP_HANDLERS = {
         const whileSelector = repeat.while.visible ?? repeat.while.notVisible;
         h.policy.assertAllowedSelector(whileSelector);
         for (let i = 0; i < maxIter; i++) {
-          const whileCount = await h.driver.count(whileSelector);
+          const whileCount = await countVisible(h.driver, whileSelector);
           const shouldContinue = repeat.while.visible !== void 0 ? whileCount > 0 : whileCount === 0;
           if (!shouldContinue) break;
           totalSubSteps += repeat.steps.length;
@@ -6900,6 +7213,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");
@@ -6925,6 +7239,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();
@@ -6938,39 +7438,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;
 }
@@ -9174,7 +9653,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");
@@ -9187,10 +9666,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");
@@ -9244,7 +9723,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) {
@@ -9258,7 +9737,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
     });
   }
@@ -9335,7 +9814,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() {
@@ -9346,7 +9825,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);
     }
   });
@@ -9360,7 +9839,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);
@@ -9526,7 +10005,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;
@@ -9606,7 +10085,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 {
@@ -9719,10 +10198,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());
@@ -9737,6 +10608,7 @@ function buildProgram() {
   program2.addCommand(buildFlakyCommand());
   program2.addCommand(buildMcpCommand());
   program2.addCommand(buildMacdriverCommand());
+  program2.addCommand(buildDoctorCommand());
   return program2;
 }