prowl-tools 0.1.5 → 0.1.6

package/dist/index.js

@@ -1,13 +1,19 @@
 #!/usr/bin/env node
 import {
   DEFAULT_FLAKY_THRESHOLD,
+  analyzeAndroidApp,
+  analyzeIosApp,
   analyzeMacApp,
   analyzePage,
+  assertAndroidAppAllowed,
+  assertIosAppAllowed,
   assertTargetAppAllowed,
   closeBrowser,
   createPlaywrightDriver,
   generateHunt,
+  launchAndroidSession,
   launchBrowser,
+  launchIosSession,
   launchMacSession,
   parseBrowserEngine,
   printCiSummary,
@@ -17,7 +23,7 @@ import {
   runSuite,
   saveStorageState,
   updateBacklogFromSuite
-} from "./chunk-2KD2XCTH.js";
+} from "./chunk-5KQR3IR3.js";
 import {
   CONFIG_DIR,
   findConfigPath,
@@ -26,7 +32,7 @@ import {
   loadHuntMeta,
   loadHuntTags,
   resolveViewport
-} from "./chunk-ITOSUJCN.js";
+} from "./chunk-WHAMB4TY.js";
 
 // src/cli/program.ts
 import { Command as Command13 } from "commander";
@@ -34,7 +40,7 @@ import { Command as Command13 } from "commander";
 // package.json
 var package_default = {
   name: "prowl-tools",
-  version: "0.1.5",
+  version: "0.1.6",
   description: "CLI-first QA testing tool for deterministic Playwright flows.",
   type: "module",
   license: "Apache-2.0",
@@ -198,6 +204,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 +220,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}`);
@@ -799,6 +809,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 +946,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 +1088,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 +1177,7 @@ function buildGenerateCommand() {
         } else if (options.output) {
           let configDir;
           try {
-            const { loadConfig: loadConfig2 } = await import("./loader-FCXPARP7.js");
+            const { loadConfig: loadConfig2 } = await import("./loader-PBBYV3U7.js");
             const result = loadConfig2(options.config);
             configDir = result.configDir;
           } catch {