prowl-tools 0.1.9 → 0.1.10

package/dist/index.cjs

@@ -74,7 +74,7 @@ var init_hunt_name = __esm({
 });
 
 // src/config/schema.ts
-var import_zod, webTargetSchema, macosTargetSchema, androidTargetSchema, iosTargetSchema, targetSchema, configSchema, navigateStepSchema, clickStepSchema, singleKeyValueSchema, fillStepSchema, typeStepSchema, pressStepSchema, waitForSelectorStepSchema, waitStepSchema, waitForUrlStepSchema, waitForNetworkIdleStepSchema, selectOptionStepSchema, selectStepSchema, onDialogStepSchema, setInputFilesStepSchema, inlineAssertStepSchema, runHuntStepSchema, hoverStepSchema, scrollStepSchema, scrollToStepSchema, screenshotStepSchema, ifStepSchema, repeatStepSchema, mockRouteStepSchema, unmockRouteStepSchema, evalScriptStepSchema, runScriptStepSchema, assertScreenshotStepSchema, assertWithAiStepSchema, copyTextStepSchema, waitForDownloadStepSchema, stepSchema, assertionSchema, huntSchema;
+var import_zod, webTargetSchema, macosTargetSchema, androidTargetSchema, iosTargetSchema, targetSchema, configSchema, navigateStepSchema, clickStepSchema, singleKeyValueSchema, fillStepSchema, typeStepSchema, pressStepSchema, waitForSelectorStepSchema, waitStepSchema, waitForUrlStepSchema, waitForNetworkIdleStepSchema, waitForResponseStatusSchema, waitForResponseTimeoutSchema, waitForResponseStepSchema, selectOptionStepSchema, selectStepSchema, onDialogStepSchema, setInputFilesStepSchema, inlineAssertStepSchema, runHuntStepSchema, hoverStepSchema, scrollStepSchema, scrollToStepSchema, screenshotStepSchema, ifStepSchema, repeatStepSchema, mockRouteStepSchema, unmockRouteStepSchema, evalScriptStepSchema, runScriptStepSchema, assertScreenshotStepSchema, assertWithAiStepSchema, copyTextStepSchema, waitForDownloadStepSchema, stepSchema, assertionSchema, huntSchema;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     "use strict";
@@ -199,6 +199,21 @@ var init_schema = __esm({
     waitForNetworkIdleStepSchema = import_zod.z.object({
       waitForNetworkIdle: import_zod.z.object({ timeout: import_zod.z.number().optional() }).strict()
     }).strict();
+    waitForResponseStatusSchema = import_zod.z.number().int().min(100).max(599);
+    waitForResponseTimeoutSchema = import_zod.z.number().int().min(0).finite();
+    waitForResponseStepSchema = import_zod.z.object({
+      waitForResponse: import_zod.z.object({
+        // Matched against each response URL as a glob (`*`/`**` match any run of
+        // characters including `/`, `?` matches one character); matching is
+        // unanchored, so a pattern with no wildcards behaves as a substring match.
+        url: import_zod.z.string().min(1).describe(
+          "URL glob to wait for; unanchored, so a wildcard-free pattern is a substring match"
+        ),
+        // Optional status filter: only resolve on a response with this exact HTTP status.
+        status: waitForResponseStatusSchema.optional(),
+        timeout: waitForResponseTimeoutSchema.optional()
+      }).strict()
+    }).strict();
     selectOptionStepSchema = import_zod.z.object({
       selectOption: import_zod.z.object({ selector: import_zod.z.string().min(1), value: import_zod.z.string() }).strict()
     }).strict();
@@ -360,6 +375,7 @@ var init_schema = __esm({
       waitForSelectorStepSchema,
       waitForUrlStepSchema,
       waitForNetworkIdleStepSchema,
+      waitForResponseStepSchema,
       hoverStepSchema,
       scrollStepSchema,
       scrollToStepSchema,
@@ -592,6 +608,16 @@ function interpolateStep(step, vars, stepPath2, redacted) {
   if ("waitForNetworkIdle" in step) {
     return { waitForNetworkIdle: { timeout: step.waitForNetworkIdle.timeout } };
   }
+  if ("waitForResponse" in step) {
+    const urlResult = interpolateString(step.waitForResponse.url, vars);
+    return {
+      waitForResponse: {
+        url: urlResult.value,
+        ...step.waitForResponse.status !== void 0 ? { status: step.waitForResponse.status } : {},
+        timeout: step.waitForResponse.timeout
+      }
+    };
+  }
   if ("hover" in step) {
     const selectorResult = interpolateString(step.hover.selector, vars);
     return { hover: { selector: selectorResult.value } };
@@ -1133,7 +1159,7 @@ var import_commander15 = require("commander");
 // package.json
 var package_default = {
   name: "prowl-tools",
-  version: "0.1.9",
+  version: "0.1.10",
   description: "E2E testing for native macOS apps and web apps from declarative YAML hunts.",
   type: "module",
   license: "Apache-2.0",
@@ -1192,7 +1218,8 @@ var package_default = {
     build: "tsup",
     lint: "eslint .",
     test: "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "audit:licenses": "node scripts/audit-licenses.mjs"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -1216,6 +1243,7 @@ var package_default = {
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     eslint: "^8.57.1",
+    "license-checker-rseidelsohn": "^4.4.2",
     tsup: "^8.3.5",
     typescript: "^5.7.3",
     vitest: "^2.1.8"
@@ -1240,6 +1268,7 @@ var WEB_ONLY_STEP_TYPES = /* @__PURE__ */ new Set([
   "navigate",
   "waitForUrl",
   "waitForNetworkIdle",
+  "waitForResponse",
   "mockRoute",
   "unmockRoute",
   "evalScript",
@@ -1625,6 +1654,9 @@ function createPlaywrightDriver(page) {
     async waitForNetworkIdle(options) {
       await page.waitForLoadState("networkidle", { timeout: options?.timeout });
     },
+    async waitForResponse(predicate, options) {
+      await page.waitForResponse((response) => predicate(response), { timeout: options?.timeout });
+    },
     evaluate(pageFunction, arg) {
       const raw = page.evaluate;
       const result = arg === void 0 ? raw.call(page, pageFunction) : raw.call(page, pageFunction, arg);
@@ -1827,6 +1859,9 @@ function createMacDriver(client, options = {}) {
     waitForNetworkIdle() {
       return rejectUnsupported("waitForNetworkIdle");
     },
+    waitForResponse() {
+      return rejectUnsupported("waitForResponse");
+    },
     // scripting & artifacts ------------------------------------------------
     evaluate() {
       return rejectUnsupported("evalScript");
@@ -2675,6 +2710,9 @@ function createAndroidDriver(client, options = {}) {
     waitForNetworkIdle() {
       return rejectUnsupported("waitForNetworkIdle");
     },
+    waitForResponse() {
+      return rejectUnsupported("waitForResponse");
+    },
     // scripting & artifacts ------------------------------------------------
     evaluate() {
       return rejectUnsupported("evalScript");
@@ -3541,6 +3579,9 @@ function createIosDriver(client, options) {
     waitForNetworkIdle() {
       return rejectUnsupported("waitForNetworkIdle");
     },
+    waitForResponse() {
+      return rejectUnsupported("waitForResponse");
+    },
     // scripting & artifacts ------------------------------------------------
     evaluate() {
       return rejectUnsupported("evalScript");
@@ -4805,6 +4846,7 @@ function getStepType(step) {
   if ("waitForSelector" in step) return "waitForSelector";
   if ("waitForUrl" in step) return "waitForUrl";
   if ("waitForNetworkIdle" in step) return "waitForNetworkIdle";
+  if ("waitForResponse" in step) return "waitForResponse";
   if ("hover" in step) return "hover";
   if ("scroll" in step) return "scroll";
   if ("scrollTo" in step) return "scrollTo";
@@ -4821,6 +4863,11 @@ function getStepType(step) {
   if ("waitForDownload" in step) return "waitForDownload";
   return "step";
 }
+function compileResponseUrlMatcher(pattern) {
+  const regexBody = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*").replace(/\\\?/g, ".");
+  const regex = new RegExp(regexBody);
+  return (url) => regex.test(url);
+}
 var RUNTIME_VAR_PATTERN = /\{\{([A-Z0-9_]+)\}\}/g;
 function substituteRuntimeVars(input, vars) {
   return input.replace(RUNTIME_VAR_PATTERN, (match, name) => {
@@ -4859,6 +4906,15 @@ function applyRuntimeVars(step, vars) {
   if ("waitForSelector" in step) {
     return { waitForSelector: { selector: sub(step.waitForSelector.selector), timeout: step.waitForSelector.timeout } };
   }
+  if ("waitForResponse" in step) {
+    return {
+      waitForResponse: {
+        url: sub(step.waitForResponse.url),
+        ...step.waitForResponse.status !== void 0 ? { status: step.waitForResponse.status } : {},
+        ...step.waitForResponse.timeout !== void 0 ? { timeout: step.waitForResponse.timeout } : {}
+      }
+    };
+  }
   if ("evalScript" in step) {
     if (typeof step.evalScript === "string") return { evalScript: sub(step.evalScript) };
     return {
@@ -5468,6 +5524,32 @@ var STEP_HANDLERS = {
       };
     }
   },
+  waitForResponse: {
+    capabilities: ["response", "wait"],
+    run: async (h) => {
+      if (!("waitForResponse" in h.step)) unknownStep();
+      const { url: pattern, status, timeout } = h.step.waitForResponse;
+      const matchesResponseUrl = compileResponseUrlMatcher(pattern);
+      try {
+        await h.driver.waitForResponse(
+          (response) => matchesResponseUrl(response.url()) && (status === void 0 || response.status() === status),
+          { timeout }
+        );
+      } catch (err) {
+        const isTimeout = err instanceof Error && (err.name === "TimeoutError" || /timeout/i.test(err.message));
+        if (!isTimeout) throw err;
+        const statusPart = status !== void 0 ? ` with status ${status}` : "";
+        const timeoutPart = timeout !== void 0 ? ` within ${timeout}ms` : "";
+        throw new Error(
+          `waitForResponse: no response matching "${pattern}"${statusPart} was received${timeoutPart}.`
+        );
+      }
+      return {
+        kind: "result",
+        result: { type: "waitForResponse", status: "pass", durationMs: Date.now() - h.stepStart, value: pattern }
+      };
+    }
+  },
   waitForNetworkIdle: {
     capabilities: ["wait"],
     run: async (h) => {
@@ -6258,6 +6340,15 @@ function formatStep(step) {
   const error = step.error ? ` error=${escapeMd(step.error)}` : "";
   return `${base}${selector}${healed}${value}${error}`;
 }
+function formatRetryAttempt(attempt) {
+  const base = `- attempt ${attempt.attempt}: ${attempt.status.toUpperCase()} (${attempt.durationMs}ms)`;
+  if (attempt.status === "pass") {
+    return base;
+  }
+  const step = attempt.failedStep ? ` failed-step=[${attempt.failedStep.index}] ${escapeMd(attempt.failedStep.type)}` : "";
+  const error = attempt.error ? ` error=${escapeMd(attempt.error)}` : "";
+  return `${base}${step}${error}`;
+}
 function formatAssertion(assertion) {
   const value = assertion.value !== void 0 ? ` value=${typeof assertion.value === "string" ? escapeMd(assertion.value) : assertion.value}` : "";
   const error = assertion.error ? ` error=${escapeMd(assertion.error)}` : "";
@@ -6272,6 +6363,16 @@ function writeSummary(runDir, result) {
   lines.push(`Target: ${result.targetUrl}`);
   lines.push(`Started: ${result.startedAt}`);
   lines.push(`Duration: ${result.durationMs}ms`);
+  if (result.retryHistory && result.retryHistory.length > 1) {
+    lines.push("");
+    lines.push("## Retries");
+    if (result.retrySummary) {
+      lines.push(escapeMd(result.retrySummary));
+    }
+    for (const attempt of result.retryHistory) {
+      lines.push(formatRetryAttempt(attempt));
+    }
+  }
   lines.push("");
   lines.push("## Steps");
   for (const step of result.steps) {
@@ -6432,7 +6533,8 @@ function isHistoryEntry(value) {
     return false;
   }
   const entry = value;
-  return typeof entry.hunt === "string" && (entry.status === "pass" || entry.status === "fail") && typeof entry.durationMs === "number" && Number.isFinite(entry.durationMs) && typeof entry.startedAt === "string" && (entry.runDir === void 0 || typeof entry.runDir === "string");
+  return typeof entry.hunt === "string" && (entry.status === "pass" || entry.status === "fail") && typeof entry.durationMs === "number" && Number.isFinite(entry.durationMs) && typeof entry.startedAt === "string" && (entry.runDir === void 0 || typeof entry.runDir === "string") && // Optional (PROWL-033): older history.json files predate `retries`.
+  (entry.retries === void 0 || typeof entry.retries === "number" && Number.isInteger(entry.retries) && entry.retries >= 0);
 }
 function readHistory(configDir) {
   const filePath = historyPath(configDir);
@@ -6684,6 +6786,60 @@ async function executeHuntAttempt(options, config, configDir, interpolatedHunt,
 function delay3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function toRetryAttempt(attempt, result) {
+  const record = {
+    attempt,
+    status: result.status,
+    durationMs: result.durationMs
+  };
+  if (result.status === "fail") {
+    const failedIndex = result.steps.findIndex((step) => step.status === "fail");
+    if (failedIndex >= 0) {
+      const failed = result.steps[failedIndex];
+      record.failedStep = { index: failedIndex, type: failed.type };
+      if (failed.error) {
+        record.error = failed.error;
+      }
+    }
+    if (!record.error) {
+      const failedAssertion = result.assertions.find((assertion) => assertion.status === "fail");
+      if (failedAssertion?.error) {
+        record.error = failedAssertion.error;
+      }
+    }
+  }
+  return record;
+}
+function describeAttemptFailure(attempt) {
+  if (attempt.status !== "fail") {
+    return void 0;
+  }
+  const step = attempt.failedStep?.type;
+  if (step && attempt.error) {
+    return `${step} (${attempt.error})`;
+  }
+  return step ?? attempt.error;
+}
+function buildRetrySummary(attempts, maxRetries) {
+  const final = attempts[attempts.length - 1];
+  const firstFailure = describeAttemptFailure(attempts[0]);
+  const suffix = firstFailure ? ` \u2014 first failure: ${firstFailure}` : "";
+  if (final.status === "pass") {
+    return `Passed on attempt ${final.attempt} of ${maxRetries + 1}${suffix}`;
+  }
+  return `Failed after ${attempts.length} attempts${suffix}`;
+}
+function finalizeRetryOutcome(outcome, attempts, maxRetries, junit) {
+  outcome.result = writeReports(
+    outcome.runDir,
+    {
+      ...outcome.result,
+      retryHistory: attempts,
+      retrySummary: buildRetrySummary(attempts, maxRetries)
+    },
+    { junit }
+  );
+}
 async function runHunt(options) {
   const { config, configDir } = loadConfig(options.configPath);
   if (config.target.type === "macos") {
@@ -6713,7 +6869,9 @@ async function runHunt(options) {
   }
   const maxRetries = hunt.retry?.maxRetries ?? 0;
   const retryDelay = hunt.retry?.delay ?? 0;
+  const junit = options.junit ?? config.artifacts.junit;
   let lastResult;
+  const attempts = [];
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     if (attempt > 0 && retryDelay > 0) {
       await delay3(retryDelay);
@@ -6729,19 +6887,20 @@ async function runHunt(options) {
       targetUrl,
       allowedDomains
     );
+    attempts.push(toRetryAttempt(attempt + 1, lastResult.result));
     if (lastResult.result.status === "pass") {
-      if (attempt > 0) {
-        lastResult.result.artifacts.summary = `Passed on attempt ${attempt + 1} of ${maxRetries + 1}`;
+      if (attempts.length > 1) {
+        finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
       }
-      recordHistory(configDir, lastResult, config.history.maxRuns);
+      recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
       return lastResult;
     }
   }
-  if (maxRetries > 0 && lastResult) {
-    lastResult.result.artifacts.summary = `Failed after ${maxRetries + 1} attempts`;
-  }
   if (lastResult) {
-    recordHistory(configDir, lastResult, config.history.maxRuns);
+    if (attempts.length > 1) {
+      finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
+    }
+    recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
   }
   return lastResult;
 }
@@ -6945,7 +7104,9 @@ async function runNativeHunt(options, config, configDir, target, native) {
   }
   const maxRetries = hunt.retry?.maxRetries ?? 0;
   const retryDelay = hunt.retry?.delay ?? 0;
+  const junit = options.junit ?? config.artifacts.junit;
   let lastResult;
+  const attempts = [];
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     if (attempt > 0 && retryDelay > 0) {
       await delay3(retryDelay);
@@ -6960,23 +7121,24 @@ async function runNativeHunt(options, config, configDir, target, native) {
       randomVars,
       config.guardrails.allowedApps
     );
+    attempts.push(toRetryAttempt(attempt + 1, lastResult.result));
     if (lastResult.result.status === "pass") {
-      if (attempt > 0) {
-        lastResult.result.artifacts.summary = `Passed on attempt ${attempt + 1} of ${maxRetries + 1}`;
+      if (attempts.length > 1) {
+        finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
       }
-      recordHistory(configDir, lastResult, config.history.maxRuns);
+      recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
       return lastResult;
     }
   }
-  if (maxRetries > 0 && lastResult) {
-    lastResult.result.artifacts.summary = `Failed after ${maxRetries + 1} attempts`;
-  }
   if (lastResult) {
-    recordHistory(configDir, lastResult, config.history.maxRuns);
+    if (attempts.length > 1) {
+      finalizeRetryOutcome(lastResult, attempts, maxRetries, junit);
+    }
+    recordHistory(configDir, lastResult, config.history.maxRuns, attempts.length - 1);
   }
   return lastResult;
 }
-function recordHistory(configDir, outcome, maxRuns) {
+function recordHistory(configDir, outcome, maxRuns, retries = 0) {
   try {
     const relativeRunDir = import_node_path15.default.relative(configDir, outcome.runDir);
     appendEntry(
@@ -6986,7 +7148,9 @@ function recordHistory(configDir, outcome, maxRuns) {
         status: outcome.result.status,
         durationMs: outcome.result.durationMs,
         startedAt: outcome.result.startedAt,
-        runDir: relativeRunDir || void 0
+        runDir: relativeRunDir || void 0,
+        // Omit when no retry ran so entries stay additive/backward-compatible.
+        retries: retries > 0 ? retries : void 0
       },
       maxRuns
     );
@@ -7041,6 +7205,10 @@ function describeStep(step) {
   if ("waitForSelector" in step) return `waitForSelector "${step.waitForSelector.selector}"`;
   if ("waitForUrl" in step) return `waitForUrl "${step.waitForUrl.value}"`;
   if ("waitForNetworkIdle" in step) return "waitForNetworkIdle";
+  if ("waitForResponse" in step) {
+    const statusSuffix = step.waitForResponse.status !== void 0 ? ` (status ${step.waitForResponse.status})` : "";
+    return `waitForResponse "${step.waitForResponse.url}"${statusSuffix}`;
+  }
   if ("hover" in step) return `hover "${step.hover.selector}"`;
   if ("scroll" in step) return `scroll ${step.scroll.direction} ${step.scroll.amount ?? 500}px`;
   if ("scrollTo" in step) return `scrollTo "${step.scrollTo.selector}"`;
@@ -7104,6 +7272,10 @@ function printHuntSummary(result, runDir) {
   const duration = import_chalk.default.gray(`(${result.durationMs}ms)`);
   console.log(`
   ${status} ${import_chalk.default.bold(result.hunt)} ${duration} ${stepCount}`);
+  if (result.retrySummary) {
+    const color = result.status === "pass" ? import_chalk.default.yellow : import_chalk.default.red;
+    console.log(`  ${color(result.retrySummary)}`);
+  }
   console.log(`  ${import_chalk.default.gray("Artifacts:")} ${runDir}
 `);
 }
@@ -9223,6 +9395,7 @@ var STEP_REFERENCE = `
 - waitForSelector: { selector: "#el", timeout: 5000 }
 - waitForUrl: { value: "/path", timeout: 5000 }
 - waitForNetworkIdle: { timeout: 5000 }
+- waitForResponse: { url: "**/api/orders", status: 200, timeout: 10000 } \u2014 wait for a matching network response (url is a glob/substring; status is optional)
 
 ### Interaction
 - click: "Button Text" \u2014 click by text (tries role=button first)
@@ -9463,6 +9636,7 @@ function buildHistoryCommand() {
       }
       console.log();
       console.log(`  ${import_chalk13.default.bold(huntName)} \u2014 last ${recent.length} of ${entries.length} runs`);
+      console.log(`  ${import_chalk13.default.gray(formatRetryFrequency(recent))}`);
       console.log();
       console.log(formatTable(recent));
       console.log();
@@ -9478,12 +9652,23 @@ function buildHistoryCommand() {
   });
   return command;
 }
+function formatRetryFrequency(entries) {
+  const retried = entries.filter((entry) => (entry.retries ?? 0) > 0).length;
+  if (retried === 0) {
+    return "No retries in these runs";
+  }
+  return `Retried in ${retried} of ${entries.length} runs`;
+}
+function formatRetries(retries) {
+  return retries && retries > 0 ? String(retries) : "-";
+}
 function formatTable(entries) {
-  const headers = ["Status", "Started", "Duration"];
+  const headers = ["Status", "Started", "Duration", "Retries"];
   const rows = entries.map((entry) => [
     formatStatus(entry.status),
     entry.startedAt,
-    formatDuration(entry.durationMs)
+    formatDuration(entry.durationMs),
+    formatRetries(entry.retries)
   ]);
   const widths = headers.map(
     (header, index) => Math.max(