prowl-tools 0.1.4 → 0.1.6

package/dist/index.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 import {
   DEFAULT_FLAKY_THRESHOLD,
+  analyzeAndroidApp,
+  analyzeIosApp,
+  analyzeMacApp,
   analyzePage,
+  assertAndroidAppAllowed,
+  assertIosAppAllowed,
+  assertTargetAppAllowed,
   closeBrowser,
   createPlaywrightDriver,
   generateHunt,
+  launchAndroidSession,
   launchBrowser,
+  launchIosSession,
+  launchMacSession,
   parseBrowserEngine,
   printCiSummary,
   rankFlaky,
@@ -14,15 +23,16 @@ import {
   runSuite,
   saveStorageState,
   updateBacklogFromSuite
-} from "./chunk-ZEFVTKQT.js";
+} from "./chunk-5KQR3IR3.js";
 import {
   CONFIG_DIR,
+  findConfigPath,
   listHunts,
   loadConfig,
   loadHuntMeta,
   loadHuntTags,
   resolveViewport
-} from "./chunk-MBAIGNVO.js";
+} from "./chunk-WHAMB4TY.js";
 
 // src/cli/program.ts
 import { Command as Command13 } from "commander";
@@ -30,7 +40,7 @@ import { Command as Command13 } from "commander";
 // package.json
 var package_default = {
   name: "prowl-tools",
-  version: "0.1.4",
+  version: "0.1.6",
   description: "CLI-first QA testing tool for deterministic Playwright flows.",
   type: "module",
   license: "Apache-2.0",
@@ -100,6 +110,10 @@ var package_default = {
     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",
@@ -190,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) {
@@ -205,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}`);
@@ -422,7 +440,7 @@ function buildLoginCommand() {
     let session = null;
     try {
       const { config, configDir } = loadConfig(options.config);
-      if (config.target.type === "macos") {
+      if (config.target.type !== "web") {
         throw new Error("`prowl login` captures browser auth state and only applies to web targets.");
       }
       const targetUrl = options.url ?? config.target.url;
@@ -779,73 +797,313 @@ function parseViewportFlag(value) {
   }
   return value;
 }
-function buildAnalyzeCommand() {
-  const command = new Command8("analyze").argument("<url>", "URL to analyze").description("Analyze a page to discover interactive elements and selectors").option("--json", "Output as JSON").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 {
-      const engine = parseBrowserEngine(options.browser);
-      const channel = options.channel;
-      const viewport = options.viewport ? resolveViewport(parseViewportFlag(options.viewport)) : { width: 1280, height: 720 };
-      const session = await launchBrowser({
-        headless: !options.headed,
-        slowMo: 0,
-        timeout: 3e4,
-        trace: false,
-        recordHar: false,
-        runDir: process.cwd(),
-        engine,
-        channel,
-        viewport
-      });
-      const driver = createPlaywrightDriver(session.page);
-      try {
-        await driver.goto(url, { waitUntil: "networkidle" });
-        const result = await analyzePage(driver);
-        if (options.json) {
-          console.log(JSON.stringify(result, null, 2));
-        } else {
-          console.log(`
+function tryLoadConfig(configPath) {
+  const configLocation = configPath !== void 0 ? configPath : findConfigPath(process.cwd());
+  if (configLocation === null) {
+    return null;
+  }
+  try {
+    return loadConfig(configLocation).config;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown configuration error";
+    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;
+  const viewport = options.viewport ? resolveViewport(parseViewportFlag(options.viewport)) : { width: 1280, height: 720 };
+  const session = await launchBrowser({
+    headless: !options.headed,
+    slowMo: 0,
+    timeout: 3e4,
+    trace: false,
+    recordHar: false,
+    runDir: process.cwd(),
+    engine,
+    channel,
+    viewport
+  });
+  const driver = createPlaywrightDriver(session.page);
+  try {
+    await driver.goto(url, { waitUntil: "networkidle" });
+    const result = await analyzePage(driver);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`
   ${chalk10.bold("Page Analysis:")} ${result.title}`);
-          console.log(`  ${chalk10.gray("URL:")} ${result.url}
+      console.log(`  ${chalk10.gray("URL:")} ${result.url}
 `);
-          if (result.forms.length > 0) {
-            console.log(chalk10.bold("  Forms:"));
-            for (const form of result.forms) {
-              const method = form.method ? chalk10.cyan(form.method) : "";
-              const action = form.action ? chalk10.gray(form.action) : "";
-              console.log(`    [${form.index}] ${method} ${action} (${form.fieldCount} fields)`);
-            }
-            console.log();
-          }
-          if (result.elements.length > 0) {
-            console.log(chalk10.bold("  Interactive Elements:"));
-            for (const el of result.elements) {
-              const tag = chalk10.cyan(el.tag);
-              const type = el.type ? chalk10.gray(`[${el.type}]`) : "";
-              const bestSelector = el.selectors.testId ?? el.selectors.label ?? el.selectors.ariaLabel ?? el.selectors.css ?? el.selectors.name ?? "";
-              const selectorStr = bestSelector ? chalk10.yellow(bestSelector) : chalk10.gray("(no selector)");
-              const req = el.required ? chalk10.red(" *") : "";
-              const form = el.formGroup !== void 0 ? chalk10.gray(` form[${el.formGroup}]`) : "";
-              console.log(`    ${tag}${type} ${selectorStr}${req}${form}`);
-            }
-            console.log();
-          }
-          if (result.links.length > 0) {
-            console.log(chalk10.bold("  Links:"));
-            for (const link of result.links.slice(0, 20)) {
-              const text = link.text || chalk10.gray("(no text)");
-              console.log(`    ${text} ${chalk10.gray("\u2192")} ${chalk10.blue(link.href)}`);
-            }
-            if (result.links.length > 20) {
-              console.log(chalk10.gray(`    ... and ${result.links.length - 20} more`));
-            }
-            console.log();
-          }
-          console.log(chalk10.gray(`  ${result.elements.length} elements, ${result.forms.length} forms, ${result.links.length} links
+      if (result.forms.length > 0) {
+        console.log(chalk10.bold("  Forms:"));
+        for (const form of result.forms) {
+          const method = form.method ? chalk10.cyan(form.method) : "";
+          const action = form.action ? chalk10.gray(form.action) : "";
+          console.log(`    [${form.index}] ${method} ${action} (${form.fieldCount} fields)`);
+        }
+        console.log();
+      }
+      if (result.elements.length > 0) {
+        console.log(chalk10.bold("  Interactive Elements:"));
+        for (const el of result.elements) {
+          const tag = chalk10.cyan(el.tag);
+          const type = el.type ? chalk10.gray(`[${el.type}]`) : "";
+          const bestSelector = el.selectors.testId ?? el.selectors.label ?? el.selectors.ariaLabel ?? el.selectors.css ?? el.selectors.name ?? "";
+          const selectorStr = bestSelector ? chalk10.yellow(bestSelector) : chalk10.gray("(no selector)");
+          const req = el.required ? chalk10.red(" *") : "";
+          const form = el.formGroup !== void 0 ? chalk10.gray(` form[${el.formGroup}]`) : "";
+          console.log(`    ${tag}${type} ${selectorStr}${req}${form}`);
+        }
+        console.log();
+      }
+      if (result.links.length > 0) {
+        console.log(chalk10.bold("  Links:"));
+        for (const link of result.links.slice(0, 20)) {
+          const text = link.text || chalk10.gray("(no text)");
+          console.log(`    ${text} ${chalk10.gray("\u2192")} ${chalk10.blue(link.href)}`);
+        }
+        if (result.links.length > 20) {
+          console.log(chalk10.gray(`    ... and ${result.links.length - 20} more`));
+        }
+        console.log();
+      }
+      console.log(chalk10.gray(`  ${result.elements.length} elements, ${result.forms.length} forms, ${result.links.length} links
 `));
+    }
+  } finally {
+    await closeBrowser(session);
+  }
+}
+function printMacElement(el) {
+  const role = chalk10.cyan(el.role);
+  const [best] = el.selectors;
+  const selectorStr = best ? chalk10.yellow(best) : chalk10.gray("(no selector)");
+  const label = el.title ?? el.description ?? el.value;
+  const labelStr = label ? ` ${chalk10.gray(`"${label}"`)}` : "";
+  const disabled = el.enabled === false ? chalk10.gray(" (disabled)") : "";
+  console.log(`    ${role} ${selectorStr}${labelStr}${disabled}`);
+}
+async function runMacAnalyze(app, config, options) {
+  const allowedApps = config?.guardrails.allowedApps ?? [];
+  assertTargetAppAllowed(allowedApps, app);
+  const session = await launchMacSession({ app, timeoutMs: config?.browser.timeout });
+  try {
+    const result = await analyzeMacApp(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.title ? chalk10.gray(`"${win.title}"`) : chalk10.gray("(untitled)");
+          console.log(`    ${title} ${chalk10.yellow(win.selector)}`);
         }
-      } finally {
-        await closeBrowser(session);
+        console.log();
+      }
+      if (result.elements.length > 0) {
+        console.log(chalk10.bold("  Interactive Elements:"));
+        for (const el of result.elements) {
+          printMacElement(el);
+        }
+        console.log();
+      }
+      if (result.menuItems.length > 0) {
+        console.log(chalk10.bold("  Menu Bar:"));
+        for (const el of result.menuItems) {
+          printMacElement(el);
+        }
+        console.log();
+      }
+      console.log(
+        chalk10.gray(
+          `  ${result.elements.length} elements, ${result.windows.length} windows, ${result.menuItems.length} menu items
+`
+        )
+      );
+    }
+  } finally {
+    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 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 (native), not both.");
+      }
+      if (options.app) {
+        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) {
+        await runWebAnalyze(url, options);
+        return;
+      }
+      const config = tryLoadConfig(options.config);
+      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|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";
       if (options.json) {
@@ -919,7 +1177,7 @@ function buildGenerateCommand() {
         } else if (options.output) {
           let configDir;
           try {
-            const { loadConfig: loadConfig2 } = await import("./loader-XMTDB6OL.js");
+            const { loadConfig: loadConfig2 } = await import("./loader-PBBYV3U7.js");
             const result = loadConfig2(options.config);
             configDir = result.configDir;
           } catch {