prowl-tools 0.1.5 → 0.1.7

package/dist/index.js

@@ -1,14 +1,24 @@
 #!/usr/bin/env node
 import {
   DEFAULT_FLAKY_THRESHOLD,
+  MACDRIVER_VERSION,
+  analyzeAndroidApp,
+  analyzeIosApp,
   analyzeMacApp,
   analyzePage,
+  assertAndroidAppAllowed,
+  assertIosAppAllowed,
   assertTargetAppAllowed,
   closeBrowser,
+  collectMacdriverStatus,
   createPlaywrightDriver,
   generateHunt,
+  installMacdriver,
+  launchAndroidSession,
   launchBrowser,
+  launchIosSession,
   launchMacSession,
+  macdriverReleaseTag,
   parseBrowserEngine,
   printCiSummary,
   rankFlaky,
@@ -16,8 +26,9 @@ import {
   runHunt,
   runSuite,
   saveStorageState,
+  tccGuidance,
   updateBacklogFromSuite
-} from "./chunk-2KD2XCTH.js";
+} from "./chunk-R7NUH44M.js";
 import {
   CONFIG_DIR,
   findConfigPath,
@@ -25,17 +36,18 @@ import {
   loadConfig,
   loadHuntMeta,
   loadHuntTags,
+  normalizeHuntName,
   resolveViewport
-} from "./chunk-ITOSUJCN.js";
+} from "./chunk-O3OUTZ2P.js";
 
 // src/cli/program.ts
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 
 // package.json
 var package_default = {
   name: "prowl-tools",
-  version: "0.1.5",
-  description: "CLI-first QA testing tool for deterministic Playwright flows.",
+  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",
@@ -50,9 +62,12 @@ var package_default = {
   keywords: [
     "testing",
     "qa",
+    "e2e",
+    "macos",
+    "desktop-testing",
+    "accessibility",
     "playwright",
     "yaml",
-    "e2e",
     "browser-testing",
     "automation",
     "web-testing",
@@ -198,6 +213,7 @@ function describeStep(step) {
     const th = step.assertScreenshot.threshold !== void 0 ? ` (threshold: ${step.assertScreenshot.threshold})` : "";
     return `assertScreenshot "${step.assertScreenshot.name}"${th}`;
   }
+  if ("assertWithAI" in step) return `assertWithAI "${truncate(step.assertWithAI, 60)}"`;
   return "unknown step";
 }
 function truncate(text, max) {
@@ -213,6 +229,9 @@ function printStepResult(result, step, _index) {
   const duration = chalk.gray(`(${result.durationMs}ms)`);
   if (result.status === "pass") {
     console.log(`    ${chalk.green("\u2713")} ${label} ${duration}`);
+  } else if (result.status === "warn") {
+    const note = result.value ? chalk.gray(` \u2014 ${result.value}`) : "";
+    console.log(`    ${chalk.yellow("\u25CB")} ${label} ${duration}${note}`);
   } else {
     const error = result.error ? chalk.gray(` \u2014 ${result.error}`) : "";
     console.log(`    ${chalk.red("\u2717")} ${label} ${duration}${error}`);
@@ -264,7 +283,11 @@ ${bot}`);
 
 // src/cli/commands/run.ts
 function buildRunCommand() {
-  const command = new Command("run").argument("<hunt-name>", "Hunt name or path (e.g. homepage or admin/users-crud)").option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--browser <engine>", "Browser engine: chromium, firefox, or webkit").option("--channel <name>", "Browser channel: chrome, msedge, chrome-beta, etc.").option("--viewport <size>", "Viewport size: WxH (e.g. 1920x1080) or preset (mobile, tablet, desktop)").option("--include-tags <tags>", "Only run hunts matching these tags (comma-separated)").option("--exclude-tags <tags>", "Skip hunts matching these tags (comma-separated)").option("--junit", "Generate JUnit XML report").option("--config <path>", "Custom config path").option("--json", "Output results as JSON").action(async (huntName, options) => {
+  const command = new Command("run").argument(
+    "<hunt-name>",
+    "Hunt name or path (e.g. homepage, admin/users-crud, or .prowl/hunts/homepage.yml)"
+  ).option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--browser <engine>", "Browser engine: chromium, firefox, or webkit").option("--channel <name>", "Browser channel: chrome, msedge, chrome-beta, etc.").option("--viewport <size>", "Viewport size: WxH (e.g. 1920x1080) or preset (mobile, tablet, desktop)").option("--include-tags <tags>", "Only run hunts matching these tags (comma-separated)").option("--exclude-tags <tags>", "Skip hunts matching these tags (comma-separated)").option("--junit", "Generate JUnit XML report").option("--config <path>", "Custom config path").option("--json", "Output results as JSON").action(async (huntArg, options) => {
+    const huntName = normalizeHuntName(huntArg);
     try {
       if (options.includeTags || options.excludeTags) {
         const { configDir } = loadConfig(options.config);
@@ -399,7 +422,7 @@ function buildInitCommand() {
     console.log(welcomeBanner());
     console.log(chalk4.green(`  Initialized ${CONFIG_DIR} directory.`));
     console.log(chalk4.gray("  Run ") + chalk4.bold("prowl run hello") + chalk4.gray(" to get started."));
-    console.log(chalk4.gray("  Browse hunt templates at ") + chalk4.cyan("https://hub.prowl.tools") + "\n");
+    console.log(chalk4.gray("  See ") + chalk4.cyan(`${CONFIG_DIR}/hunts/login-flow.yml`) + chalk4.gray(" for a fuller example.") + "\n");
   });
   return command;
 }
@@ -536,7 +559,11 @@ function createDebouncer(delayMs, fn) {
 
 // src/cli/commands/watch.ts
 function buildWatchCommand() {
-  const command = new Command5("watch").argument("<hunt-name>", "Hunt name or path (e.g. homepage or admin/users-crud)").option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--config <path>", "Custom config path").action(async (huntName, options) => {
+  const command = new Command5("watch").argument(
+    "<hunt-name>",
+    "Hunt name or path (e.g. homepage, admin/users-crud, or .prowl/hunts/homepage.yml)"
+  ).option("--url <target>", "Override target URL").option("--headed", "Show browser window").option("--slow-mo <ms>", "Slow down Playwright actions", (value) => Number(value)).option("--trace", "Capture Playwright trace").option("--config <path>", "Custom config path").action(async (huntArg, options) => {
+    const huntName = normalizeHuntName(huntArg);
     const { configDir } = loadConfig(options.config);
     const watchTargets = getWatchTargets(configDir, huntName);
     let running = false;
@@ -799,6 +826,23 @@ function tryLoadConfig(configPath) {
     throw new Error(`Failed to load config at ${configLocation}: ${message}`);
   }
 }
+function looksLikeApk(app) {
+  return /\.apk$/i.test(app.trim());
+}
+function pickNativePlatform(platformFlag, config, app) {
+  if (platformFlag !== void 0) {
+    const normalized = platformFlag.trim().toLowerCase();
+    if (normalized === "macos" || normalized === "android" || normalized === "ios") {
+      return normalized;
+    }
+    throw new Error(`Unknown --platform "${platformFlag}". Use one of: macos, android, ios.`);
+  }
+  const configType = config?.target.type;
+  if (configType === "macos" || configType === "android" || configType === "ios") {
+    return configType;
+  }
+  return looksLikeApk(app) ? "android" : "macos";
+}
 async function runWebAnalyze(url, options) {
   const engine = parseBrowserEngine(options.browser);
   const channel = options.channel;
@@ -919,14 +963,141 @@ async function runMacAnalyze(app, config, options) {
     await session.client.close();
   }
 }
+function printAndroidElement(el) {
+  const role = chalk10.cyan(el.className);
+  const [best] = el.selectors;
+  const selectorStr = best ? chalk10.yellow(best) : chalk10.gray("(no selector)");
+  const label = el.contentDesc ?? el.text;
+  const labelStr = label ? ` ${chalk10.gray(`"${label}"`)}` : "";
+  const disabled = el.enabled === false ? chalk10.gray(" (disabled)") : "";
+  console.log(`    ${role} ${selectorStr}${labelStr}${disabled}`);
+}
+async function runAndroidAnalyze(app, config, options, deviceSerial) {
+  const allowedApps = config?.guardrails.allowedApps ?? [];
+  if (!looksLikeApk(app)) {
+    assertAndroidAppAllowed(allowedApps, app);
+  }
+  const session = await launchAndroidSession({
+    app,
+    ...deviceSerial ? { deviceSerial } : {},
+    timeoutMs: config?.browser.timeout,
+    allowedApps
+  });
+  try {
+    const sourceFn = session.client.source;
+    if (typeof sourceFn !== "function") {
+      throw new Error(
+        "The Android agent client does not expose source(); a live uiautomator2 session is required to analyze."
+      );
+    }
+    const result = await analyzeAndroidApp(
+      { source: () => sourceFn.call(session.client) },
+      { app: session.package }
+    );
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`
+  ${chalk10.bold("App Analysis:")} ${result.app}
+`);
+      if (result.elements.length > 0) {
+        console.log(chalk10.bold("  Interactive Elements:"));
+        for (const el of result.elements) {
+          printAndroidElement(el);
+        }
+        console.log();
+      }
+      console.log(chalk10.gray(`  ${result.elements.length} elements
+`));
+    }
+  } finally {
+    await session.teardown();
+  }
+}
+function printIosElement(el) {
+  const role = chalk10.cyan(el.type);
+  const [best] = el.selectors;
+  const selectorStr = best ? chalk10.yellow(best) : chalk10.gray("(no selector)");
+  const label = el.label ?? el.value ?? el.name;
+  const labelStr = label ? ` ${chalk10.gray(`"${label}"`)}` : "";
+  const disabled = el.enabled === false ? chalk10.gray(" (disabled)") : "";
+  console.log(`    ${role} ${selectorStr}${labelStr}${disabled}`);
+}
+async function runIosAnalyze(app, config, options, udid) {
+  const allowedApps = config?.guardrails.allowedApps ?? [];
+  if (!/\//.test(app) && !/\.app$/i.test(app.trim())) {
+    assertIosAppAllowed(allowedApps, app);
+  }
+  const session = await launchIosSession({
+    app,
+    ...udid ? { udid } : {},
+    timeoutMs: config?.browser.timeout,
+    allowedApps
+  });
+  try {
+    const sourceFn = session.client.source;
+    if (typeof sourceFn !== "function") {
+      throw new Error(
+        "The iOS agent client does not expose source(); a live WebDriverAgent session is required to analyze."
+      );
+    }
+    const result = await analyzeIosApp(
+      { source: () => sourceFn.call(session.client) },
+      { app: session.bundleId }
+    );
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`
+  ${chalk10.bold("App Analysis:")} ${result.app}
+`);
+      if (result.windows.length > 0) {
+        console.log(chalk10.bold("  Windows:"));
+        for (const win of result.windows) {
+          const title = win.label ?? win.name;
+          const titleStr = title ? chalk10.gray(`"${title}"`) : chalk10.gray("(untitled)");
+          console.log(`    ${titleStr} ${chalk10.yellow(win.selector)}`);
+        }
+        console.log();
+      }
+      if (result.elements.length > 0) {
+        console.log(chalk10.bold("  Interactive Elements:"));
+        for (const el of result.elements) {
+          printIosElement(el);
+        }
+        console.log();
+      }
+      console.log(chalk10.gray(`  ${result.elements.length} elements, ${result.windows.length} windows
+`));
+    }
+  } finally {
+    await session.teardown();
+  }
+}
+async function runNativeAnalyze(platform, app, config, options, device) {
+  if (platform === "android") {
+    await runAndroidAnalyze(app, config, options, device.deviceSerial);
+    return;
+  }
+  if (platform === "ios") {
+    await runIosAnalyze(app, config, options, device.udid);
+    return;
+  }
+  await runMacAnalyze(app, config, options);
+}
 function buildAnalyzeCommand() {
-  const command = new Command8("analyze").argument("[url]", "URL to analyze (web target)").description("Analyze a page or macOS app to discover interactive elements and selectors").option("--json", "Output as JSON").option("--app <app>", "macOS app to analyze: bundle id or /path/to/App.app (macOS target)").option("--browser <engine>", "Browser engine: chromium, firefox, or webkit").option("--channel <name>", "Browser channel: chrome, msedge, etc.").option("--viewport <size>", "Viewport size: WxH or preset (mobile, tablet, desktop)").option("--headed", "Show browser window").option("--config <path>", "Custom config path").action(async (url, options) => {
+  const command = new Command8("analyze").argument("[url]", "URL to analyze (web target)").description("Analyze a page or native app to discover interactive elements and selectors").option("--json", "Output as JSON").option("--app <app>", "Native app to analyze: bundle id / package / .app / .apk (macOS, Android, or iOS)").option("--platform <name>", "Native platform for --app: macos, android, or ios (else inferred)").option("--device <serial>", "Android adb device serial (native Android target)").option("--udid <udid>", "iOS simulator UDID (native iOS target)").option("--browser <engine>", "Browser engine: chromium, firefox, or webkit").option("--channel <name>", "Browser channel: chrome, msedge, etc.").option("--viewport <size>", "Viewport size: WxH or preset (mobile, tablet, desktop)").option("--headed", "Show browser window").option("--config <path>", "Custom config path").action(async (url, options) => {
     try {
       if (options.app && url) {
-        throw new Error("Pass either a URL argument (web) or --app (macOS), not both.");
+        throw new Error("Pass either a URL argument (web) or --app (native), not both.");
       }
       if (options.app) {
-        await runMacAnalyze(options.app, tryLoadConfig(options.config), options);
+        const config2 = tryLoadConfig(options.config);
+        const platform = pickNativePlatform(options.platform, config2, options.app);
+        await runNativeAnalyze(platform, options.app, config2, options, {
+          deviceSerial: options.device,
+          udid: options.udid
+        });
         return;
       }
       if (url) {
@@ -934,12 +1105,21 @@ function buildAnalyzeCommand() {
         return;
       }
       const config = tryLoadConfig(options.config);
-      if (config?.target.type === "macos") {
-        await runMacAnalyze(config.target.app, config, options);
+      const target = config?.target;
+      if (target?.type === "macos") {
+        await runMacAnalyze(target.app, config, options);
+        return;
+      }
+      if (target?.type === "android") {
+        await runAndroidAnalyze(target.app, config, options, options.device ?? target.deviceSerial);
+        return;
+      }
+      if (target?.type === "ios") {
+        await runIosAnalyze(target.app, config, options, options.udid ?? target.udid);
         return;
       }
       throw new Error(
-        "analyze needs a target: pass a URL for the web target, or use --app <bundle-id|.app-path> (or set target.type: macos in .prowl/config.yml) for the macOS target."
+        "analyze needs a target: pass a URL for the web target, or use --app <bundle-id|package|.app|.apk> (optionally with --platform), or set a native target.type in .prowl/config.yml."
       );
     } catch (error) {
       const message = error instanceof Error ? error.message : "Analysis failed";
@@ -1014,7 +1194,7 @@ function buildGenerateCommand() {
         } else if (options.output) {
           let configDir;
           try {
-            const { loadConfig: loadConfig2 } = await import("./loader-FCXPARP7.js");
+            const { loadConfig: loadConfig2 } = await import("./loader-X37URHUV.js");
             const result = loadConfig2(options.config);
             configDir = result.configDir;
           } catch {
@@ -1048,13 +1228,17 @@ function buildGenerateCommand() {
 import { Command as Command10 } from "commander";
 import chalk12 from "chalk";
 function buildHistoryCommand() {
-  const command = new Command10("history").argument("<hunt-name>", "Hunt name or path (e.g. homepage or admin/users-crud)").description("Show run history for a hunt").option("--config <path>", "Custom config path").option("--limit <n>", "Show the last N runs (default: 20)", (value) => {
+  const command = new Command10("history").argument(
+    "<hunt-name>",
+    "Hunt name or path (e.g. homepage, admin/users-crud, or .prowl/hunts/homepage.yml)"
+  ).description("Show run history for a hunt").option("--config <path>", "Custom config path").option("--limit <n>", "Show the last N runs (default: 20)", (value) => {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 1) {
       throw new Error("--limit must be a positive integer");
     }
     return n;
-  }).option("--json", "Output as JSON").action((huntName, options) => {
+  }).option("--json", "Output as JSON").action((huntArg, options) => {
+    const huntName = normalizeHuntName(huntArg);
     try {
       const { configDir } = loadConfig(options.config);
       const entries = readHuntHistory(configDir, huntName);
@@ -1442,10 +1626,83 @@ function buildMcpCommand() {
   });
 }
 
+// src/cli/commands/macdriver.ts
+import chalk14 from "chalk";
+import { Command as Command13 } from "commander";
+function buildInstallCommand() {
+  return new Command13("install").description("Download and install the prebuilt, signed prowl-macdriver helper").option("--force", "Reinstall even if the pinned version is already present").action(async (options) => {
+    try {
+      console.log(
+        chalk14.cyan(
+          `Installing prowl-macdriver ${MACDRIVER_VERSION} (${macdriverReleaseTag(MACDRIVER_VERSION)})\u2026`
+        )
+      );
+      const result = await installMacdriver({ force: options.force });
+      if (result.alreadyInstalled) {
+        console.log(
+          chalk14.green(`Already installed at ${result.binaryPath}`) + chalk14.dim(" (use --force to reinstall)")
+        );
+      } else {
+        console.log(chalk14.green(`Installed prowl-macdriver ${result.version} \u2192 ${result.binaryPath}`));
+      }
+      console.log("");
+      console.log(tccGuidance());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Install failed";
+      console.error(chalk14.red(`Error: ${message}`));
+      process.exitCode = 1;
+    }
+  });
+}
+function buildStatusCommand() {
+  return new Command13("status").description("Report the resolved prowl-macdriver binary, installed versions, and permissions guidance").action(async () => {
+    try {
+      const status = await collectMacdriverStatus();
+      console.log(chalk14.bold("prowl-macdriver status"));
+      console.log(`  pinned version:   ${status.pinnedVersion}`);
+      if (status.resolved) {
+        const label = status.resolved.source === "env" ? "PROWL_MACDRIVER_BIN override" : status.resolved.source === "user-install" ? "user install (~/.prowl/macdriver)" : "repo source build (macdriver/.build)";
+        console.log(`  resolved binary:  ${status.resolved.path}`);
+        console.log(`  resolved via:     ${label}`);
+        console.log(
+          `  runs:             ${status.probedVersion ? chalk14.green(`yes (reports ${status.probedVersion})`) : chalk14.yellow("no (binary did not respond to `version`)")}`
+        );
+      } else {
+        console.log(`  resolved binary:  ${chalk14.yellow("none")}`);
+        console.log(chalk14.dim("  search order: PROWL_MACDRIVER_BIN \u2192 ~/.prowl/macdriver \u2192 macdriver/.build"));
+        console.log(chalk14.cyan("  Run `prowl macdriver install` to install the prebuilt helper."));
+      }
+      if (status.installed.length > 0) {
+        console.log("  installed versions:");
+        for (const entry of status.installed) {
+          const marker = entry.version === status.pinnedVersion ? chalk14.green(" (pinned)") : "";
+          console.log(`    - ${entry.version}${marker}  ${chalk14.dim(entry.binaryPath)}`);
+        }
+      } else {
+        console.log("  installed versions: none");
+      }
+      console.log("");
+      console.log(tccGuidance());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Status failed";
+      console.error(chalk14.red(`Error: ${message}`));
+      process.exitCode = 1;
+    }
+  });
+}
+function buildMacdriverCommand() {
+  const command = new Command13("macdriver").description(
+    "Manage the macOS helper binary (prowl-macdriver) for the macOS target"
+  );
+  command.addCommand(buildInstallCommand());
+  command.addCommand(buildStatusCommand());
+  return command;
+}
+
 // src/cli/program.ts
 var CLI_VERSION = package_default.version;
 function buildProgram() {
-  const program2 = new Command13();
+  const program2 = new Command14();
   program2.name("prowl").description("CLI-first QA testing tool for deterministic Playwright flows").version(CLI_VERSION);
   program2.addCommand(buildRunCommand());
   program2.addCommand(buildCiCommand());
@@ -1459,6 +1716,7 @@ function buildProgram() {
   program2.addCommand(buildHistoryCommand());
   program2.addCommand(buildFlakyCommand());
   program2.addCommand(buildMcpCommand());
+  program2.addCommand(buildMacdriverCommand());
   return program2;
 }