doc-detective 4.28.0 → 4.29.0

package/dist/index.cjs

@@ -383844,6 +383844,71 @@ var init_schemas = __esm({
                 }
               ]
             }
+          },
+          warm: {
+            type: "object",
+            description: "Results of the run's inline warm phase \u2014 the always-on, best-effort provisioning pass (dependency installs, device boots, session probes) performed between test resolution and test execution. A failed task never gates the run; the per-context paths retry or skip with their normal semantics. Absent when the run ended before the phase (for example, when no specs matched). System-populated.",
+            readOnly: true,
+            additionalProperties: false,
+            required: [
+              "durationMs",
+              "tasks"
+            ],
+            properties: {
+              durationMs: {
+                type: "number",
+                description: "Wall-clock duration of the warm phase in milliseconds. Tasks overlap, so this is less than the sum of the per-task durations."
+              },
+              tasks: {
+                type: "array",
+                description: "One entry per executed warm task.",
+                items: {
+                  type: "object",
+                  additionalProperties: false,
+                  required: [
+                    "name",
+                    "kind",
+                    "outcome",
+                    "durationMs"
+                  ],
+                  properties: {
+                    name: {
+                      type: "string",
+                      description: "Task identity, e.g. `browser-install:chrome` or `device-boot:android:<default>:<latest>`."
+                    },
+                    kind: {
+                      type: "string",
+                      enum: [
+                        "driver-install",
+                        "browser-install",
+                        "device-boot",
+                        "wda-check",
+                        "session-probe",
+                        "chromedriver-prefetch"
+                      ],
+                      description: "What the task pre-pays: a native app driver install, a browser install, a simulator/emulator boot, the managed WebDriverAgent availability check, the concurrent-run driver session probe, or the android mobile-web chromedriver download."
+                    },
+                    outcome: {
+                      type: "string",
+                      enum: [
+                        "warmed",
+                        "skipped",
+                        "failed"
+                      ],
+                      description: "`warmed` \u2014 the work was performed (for device boots, the boot was initiated); `skipped` \u2014 nothing to do or the environment isn't ready (the consuming context handles it as usual); `failed` \u2014 the attempt failed (logged as a warning; never fails the run)."
+                    },
+                    durationMs: {
+                      type: "number",
+                      description: "Wall-clock duration of this task in milliseconds."
+                    },
+                    note: {
+                      type: "string",
+                      description: "Human-readable detail about the outcome."
+                    }
+                  }
+                }
+              }
+            }
           }
         },
         required: [
@@ -383865,7 +383930,26 @@ var init_schemas = __esm({
                   }
                 ]
               }
-            ]
+            ],
+            warm: {
+              durationMs: 4211,
+              tasks: [
+                {
+                  name: "browser-install:chrome",
+                  kind: "browser-install",
+                  outcome: "skipped",
+                  durationMs: 2,
+                  note: "'chrome' is already available"
+                },
+                {
+                  name: "session-probe",
+                  kind: "session-probe",
+                  outcome: "warmed",
+                  durationMs: 4205,
+                  note: "1 combination ok"
+                }
+              ]
+            }
           },
           {
             specs: [
@@ -633977,21 +634061,23 @@ async function loadEnvs(envsFile) {
     return { status: "FAIL", description: "Invalid file." };
   }
 }
+function logLevelEnabled(config, level) {
+  if (config.logLevel === "error" && level === "error")
+    return true;
+  if (config.logLevel === "warning" && (level === "error" || level === "warning"))
+    return true;
+  if (config.logLevel === "info" && (level === "error" || level === "warning" || level === "info"))
+    return true;
+  if (config.logLevel === "debug" && (level === "error" || level === "warning" || level === "info" || level === "debug"))
+    return true;
+  return false;
+}
 async function log(config, level, message) {
   if (message === void 0) {
     message = config;
     config = {};
   }
-  let logLevelMatch = false;
-  if (config.logLevel === "error" && level === "error") {
-    logLevelMatch = true;
-  } else if (config.logLevel === "warning" && (level === "error" || level === "warning")) {
-    logLevelMatch = true;
-  } else if (config.logLevel === "info" && (level === "error" || level === "warning" || level === "info")) {
-    logLevelMatch = true;
-  } else if (config.logLevel === "debug" && (level === "error" || level === "warning" || level === "info" || level === "debug")) {
-    logLevelMatch = true;
-  }
+  const logLevelMatch = logLevelEnabled(config, level);
   if (logLevelMatch) {
     if (typeof message === "string") {
       let logMessage = `(${level.toUpperCase()}) ${message}`;
@@ -634076,8 +634162,7 @@ function replaceEnvs(stringOrObject) {
       stringOrObject[key] = replaceEnvs(stringOrObject[key]);
     });
   } else if (typeof stringOrObject === "string") {
-    const variableRegex = new RegExp(/\$[a-zA-Z0-9_]+(?![a-zA-Z0-9_$])/, "g");
-    const matches = stringOrObject.match(variableRegex);
+    const matches = stringOrObject.match(ENV_VAR_REGEX);
     if (!matches)
       return stringOrObject;
     matches.forEach((match) => {
@@ -634321,7 +634406,7 @@ function llevenshteinDistance(s, t) {
   }
   return arr[t.length][s.length];
 }
-var import_node_fs7, import_node_os2, import_node_path5, import_node_crypto2, import_promises, import_node_net, import_axios, import_node_child_process4, BACKGROUND_BUFFER_LIMIT, PTY_PACKAGE, READY_POLL_INTERVAL_MS, TRANSIENT_SESSION_ERROR, SESSION_TIMEOUT_ABORT, TRANSIENT_PROCESS_INIT_EXIT_CODES, SETTLE_CEILING_MAX_MS, PRESERVED_TEMP_ENTRIES, FETCH_BINARY_DEFAULTS, posixBashProbe;
+var import_node_fs7, import_node_os2, import_node_path5, import_node_crypto2, import_promises, import_node_net, import_axios, import_node_child_process4, BACKGROUND_BUFFER_LIMIT, PTY_PACKAGE, READY_POLL_INTERVAL_MS, TRANSIENT_SESSION_ERROR, SESSION_TIMEOUT_ABORT, TRANSIENT_PROCESS_INIT_EXIT_CODES, SETTLE_CEILING_MAX_MS, PRESERVED_TEMP_ENTRIES, FETCH_BINARY_DEFAULTS, ENV_VAR_REGEX, posixBashProbe;
 var init_utils = __esm({
   "dist/core/utils.js"() {
     "use strict";
@@ -634363,6 +634448,7 @@ var init_utils = __esm({
       maxBodyLength: 50 * 1024 * 1024,
       maxRedirects: 5
     };
+    ENV_VAR_REGEX = /\$[a-zA-Z0-9_]+(?![a-zA-Z0-9_$])/g;
   }
 });
 
@@ -636496,17 +636582,24 @@ function detectFileTypeFromContent(content) {
 }
 
 // dist/common/src/detectTests.js
+var compiledRegExpCache = /* @__PURE__ */ new Map();
 function safeRegExp(pattern, flags) {
   if (typeof pattern !== "string" || pattern.length === 0)
     return null;
   if (pattern.length > 1500)
     return null;
-  const sanitized = Array.from(pattern, (c) => String.fromCharCode(c.charCodeAt(0))).join("");
+  const cacheKey = pattern + " " + flags;
+  const cached = compiledRegExpCache.get(cacheKey);
+  if (cached !== void 0)
+    return cached;
+  let compiled;
   try {
-    return new RegExp(sanitized, flags);
+    compiled = new RegExp(pattern, flags);
   } catch {
-    return null;
+    compiled = null;
   }
+  compiledRegExpCache.set(cacheKey, compiled);
+  return compiled;
 }
 var HASH_EXCLUDED_KEYS = /* @__PURE__ */ new Set([
   "location",
@@ -638219,12 +638312,16 @@ function generateSpecId(filePath) {
   const normalizedPath = relativePath.split(import_node_path11.default.sep).join("/").replace(/^\.\//, "").replace(/[^a-zA-Z0-9._\-\/]/g, "_");
   return normalizedPath;
 }
-async function isValidSourceFile({ config, files, source }) {
-  log(config, "debug", `validation: ${source}`);
-  let allowedExtensions = ["json", "yaml", "yml"];
-  config.fileTypes.forEach((fileType) => {
-    allowedExtensions = allowedExtensions.concat(fileType.extensions);
+function buildAllowedExtensions(config) {
+  const allowed = /* @__PURE__ */ new Set(["json", "yaml", "yml"]);
+  (config.fileTypes || []).forEach((fileType) => {
+    fileType.extensions.forEach((ext) => allowed.add(ext));
   });
+  return allowed;
+}
+async function isValidSourceFile({ config, files, source, allowedExtensions }) {
+  log(config, "debug", `validation: ${source}`);
+  const allowed = allowedExtensions;
   if (files.indexOf(source) >= 0)
     return false;
   if (import_node_path11.default.extname(source) === ".json" || import_node_path11.default.extname(source) === ".yaml" || import_node_path11.default.extname(source) === ".yml") {
@@ -638271,7 +638368,7 @@ async function isValidSourceFile({ config, files, source }) {
     }
   }
   const extension = import_node_path11.default.extname(source).substring(1);
-  if (!allowedExtensions.includes(extension)) {
+  if (!allowed.has(extension)) {
     log(config, "debug", `${source} extension isn't specified in a \`config.fileTypes\` object. Skipping.`);
     return false;
   }
@@ -638323,6 +638420,7 @@ async function qualifyFiles({ config }) {
     return [];
   }
   const ignoredDitaMaps = [];
+  const allowedExtensions = buildAllowedExtensions(config);
   if (!config._herettoPathMapping) {
     config._herettoPathMapping = {};
   }
@@ -638390,8 +638488,9 @@ async function qualifyFiles({ config }) {
     let isFile = false;
     let isDir = false;
     try {
-      isFile = import_node_fs13.default.statSync(source).isFile();
-      isDir = import_node_fs13.default.statSync(source).isDirectory();
+      const stat = import_node_fs13.default.statSync(source);
+      isFile = stat.isFile();
+      isDir = stat.isDirectory();
     } catch {
       log(config, "warning", `Cannot access path: ${source}. Skipping.`);
       continue;
@@ -638406,7 +638505,7 @@ async function qualifyFiles({ config }) {
       continue;
     }
     const resolved = import_node_path11.default.resolve(source);
-    if (isFile && await isValidSourceFile({ config, files, source: resolved })) {
+    if (isFile && await isValidSourceFile({ config, files, allowedExtensions, source: resolved })) {
       files.push(resolved);
       if (!phaseByFile.has(resolved))
         phaseByFile.set(resolved, phase);
@@ -638419,9 +638518,10 @@ async function qualifyFiles({ config }) {
           const content = import_node_path11.default.resolve(dir + "/" + object);
           if (content.includes("node_modules"))
             continue;
-          const isFile2 = import_node_fs13.default.statSync(content).isFile();
-          const isDir2 = import_node_fs13.default.statSync(content).isDirectory();
-          if (isFile2 && await isValidSourceFile({ config, files, source: content })) {
+          const stat = import_node_fs13.default.statSync(content);
+          const isFile2 = stat.isFile();
+          const isDir2 = stat.isDirectory();
+          if (isFile2 && await isValidSourceFile({ config, files, allowedExtensions, source: content })) {
             const resolved2 = import_node_path11.default.resolve(content);
             files.push(resolved2);
             if (!phaseByFile.has(resolved2))
@@ -638785,12 +638885,14 @@ function resolveContexts({ contexts, test, config }) {
   if (resolvedContexts.length === 0) {
     resolvedContexts.push({});
   }
-  log(config, "debug", `Resolved contexts for test ${test.testId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `Resolved contexts for test ${test.testId}:
 ${JSON.stringify(resolvedContexts, null, 2)}`);
   return resolvedContexts;
 }
 async function fetchOpenApiDocuments({ config, documentArray }) {
-  log(config, "debug", `Fetching OpenAPI documents:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `Fetching OpenAPI documents:
 ${JSON.stringify(documentArray, null, 2)}`);
   const openApiDocuments = [];
   if (config?.integrations?.openApi?.length > 0)
@@ -638811,7 +638913,8 @@ ${JSON.stringify(documentArray, null, 2)}`);
       openApiDocuments.push(definition);
     }
   }
-  log(config, "debug", `Fetched OpenAPI documents:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `Fetched OpenAPI documents:
 ${JSON.stringify(openApiDocuments, null, 2)}`);
   return openApiDocuments;
 }
@@ -638831,7 +638934,8 @@ async function resolveContext({ config, test, context, usedContextIds, openApi }
   context.contextId = context.contextId ? uniqueId(context.contextId, usedContextIds) : deriveContextId({ context, usedIds: usedContextIds });
   const contextId = context.contextId;
   usedContextIds.add(contextId);
-  log(config, "debug", `RESOLVING CONTEXT ID ${contextId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVING CONTEXT ID ${contextId}:
 ${JSON.stringify(context, null, 2)}`);
   const resolvedContext = {
     ...context,
@@ -638844,13 +638948,15 @@ ${JSON.stringify(context, null, 2)}`);
     steps: [...test.steps],
     contextId
   };
-  log(config, "debug", `RESOLVED CONTEXT ${contextId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVED CONTEXT ${contextId}:
 ${JSON.stringify(resolvedContext, null, 2)}`);
   return resolvedContext;
 }
 async function resolveTest({ config, spec, test }) {
   const testId = test.testId || `${spec.specId}~${contentHash(test)}`;
-  log(config, "debug", `RESOLVING TEST ID ${testId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVING TEST ID ${testId}:
 ${JSON.stringify(test, null, 2)}`);
   const resolvedTest = {
     ...test,
@@ -638880,13 +638986,15 @@ ${JSON.stringify(test, null, 2)}`);
     });
     resolvedTest.contexts.push(resolvedContext);
   }
-  log(config, "debug", `RESOLVED TEST ${testId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVED TEST ${testId}:
 ${JSON.stringify(resolvedTest, null, 2)}`);
   return resolvedTest;
 }
 async function resolveSpec({ config, spec }) {
   const specId = spec.specId || (spec.contentPath ? generateSpecId(spec.contentPath) : import_node_crypto5.default.randomUUID());
-  log(config, "debug", `RESOLVING SPEC ID ${specId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVING SPEC ID ${specId}:
 ${JSON.stringify(spec, null, 2)}`);
   const resolvedSpec = {
     ...spec,
@@ -638906,12 +639014,14 @@ ${JSON.stringify(spec, null, 2)}`);
     });
     resolvedSpec.tests.push(resolvedTest);
   }
-  log(config, "debug", `RESOLVED SPEC ${specId}:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVED SPEC ${specId}:
 ${JSON.stringify(resolvedSpec, null, 2)}`);
   return resolvedSpec;
 }
 async function resolveTests({ config, detectedTests }) {
-  log(config, "debug", `RESOLVING DETECTED TEST SPECS:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVING DETECTED TEST SPECS:
 ${JSON.stringify(detectedTests, null, 2)}`);
   const resolvedTests = {
     resolvedTestsId: import_node_crypto5.default.randomUUID(),
@@ -638923,7 +639033,8 @@ ${JSON.stringify(detectedTests, null, 2)}`);
     const resolvedSpec = await resolveSpec({ config, spec });
     resolvedTests.specs.push(resolvedSpec);
   }
-  log(config, "debug", `RESOLVED TEST SPECS:
+  if (logLevelEnabled(config, "debug"))
+    log(config, "debug", `RESOLVED TEST SPECS:
 ${JSON.stringify(resolvedTests, null, 2)}`);
   return resolvedTests;
 }
@@ -641084,6 +641195,13 @@ async function teardownDeviceRegistry(registry, kill4) {
   for (const entry of registry.values()) {
     if (!entry.bootedByUs)
       continue;
+    if (entry.ready) {
+      try {
+        await entry.ready;
+      } catch {
+        continue;
+      }
+    }
     try {
       await kill4(entry);
     } catch {
@@ -643777,6 +643895,7 @@ function containsOperators(expression, allowOperators = false) {
   }
   return false;
 }
+var compiledEvaluatorCache = /* @__PURE__ */ new Map();
 async function evaluateExpression(expression, context) {
   try {
     expression = preprocessExpression(expression);
@@ -643850,7 +643969,13 @@ async function evaluateExpression(expression, context) {
         }
       })
     };
-    const evaluator = new Function(...Object.keys(evalContext), `return ${expression};`);
+    const argNames = Object.keys(evalContext);
+    const cacheKey = `${argNames.join(",")}\0${expression}`;
+    let evaluator = compiledEvaluatorCache.get(cacheKey);
+    if (!evaluator) {
+      evaluator = new Function(...argNames, `return ${expression};`);
+      compiledEvaluatorCache.set(cacheKey, evaluator);
+    }
     return evaluator(...Object.values(evalContext));
   } catch (error) {
     log(`Error evaluating expression '${expression}': ${error.message}`, "error");
@@ -648672,6 +648797,10 @@ function mobileBrowserConfigError(browser) {
   }
   return null;
 }
+var CHROMEDRIVER_AUTODOWNLOAD_ARGS = [
+  "--allow-insecure",
+  "uiautomator2:chromedriver_autodownload"
+];
 function mobileBrowserGate({ platform, browser, hasBrowserStep, hasAppStep }) {
   if (!hasBrowserStep)
     return { action: "proceed", browserName: null };
@@ -648732,6 +648861,216 @@ function buildMobileBrowserCapabilities({ platform, udid, cacheDir, timeout, loc
   return capabilities;
 }
 
+// dist/core/warmPhase.js
+init_utils();
+var WARM_POOL_LIMIT = 4;
+var RUNTIME_INSTALL_RESOURCE = "runtime-install";
+function deviceIdentity(platform, desc) {
+  if (desc?.name)
+    return `${platform}:name:${desc.name}`;
+  return `${platform}:default:${desc?.deviceType ?? "<any>"}:${desc?.osVersion ?? "<latest>"}`;
+}
+function deviceResourceTag(platform, desc) {
+  return `warm-device:${deviceIdentity(platform, desc)}`;
+}
+function wrapInitiationEffects(deps, keys, signal) {
+  const wrapped = { ...deps };
+  for (const key of keys) {
+    const original = deps[key];
+    if (typeof original !== "function")
+      continue;
+    wrapped[key] = (...args) => {
+      const result = original(...args);
+      signal();
+      return result;
+    };
+  }
+  return wrapped;
+}
+function planWarmTasks({ sizingJobs, runnerDetails, limit, hasAppiumPool, deps }) {
+  const hostPlatform = runnerDetails?.environment?.platform;
+  const tasks = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addTask = (task) => {
+    if (seen.has(task.name))
+      return;
+    seen.add(task.name);
+    tasks.push(task);
+  };
+  let probeEligible = false;
+  let defaultBrowser;
+  const getDefaultBrowser2 = () => defaultBrowser ??= deps.getDefaultBrowser({ runnerDetails });
+  const bootPlannedFor = /* @__PURE__ */ new Set();
+  for (const job of sizingJobs ?? []) {
+    const context = job?.context;
+    if (!context)
+      continue;
+    if (deps.contextRequirementsSkipMessage({ context }))
+      continue;
+    const effPlatform = context.platform || hostPlatform;
+    const mobileTarget = deps.isMobileTargetPlatform(effPlatform);
+    if (mobileTarget) {
+      if (mobileTarget === "ios" && hostPlatform !== "mac")
+        continue;
+      const hasAppStep = deps.isAppDriverRequired({ test: context });
+      const gate = deps.mobileBrowserGate({
+        platform: mobileTarget,
+        browser: context.browser,
+        hasBrowserStep: deps.isBrowserRequired({ test: context }),
+        hasAppStep
+      });
+      if (gate.action !== "proceed")
+        continue;
+      const isMobileWeb = typeof gate.browserName === "string";
+      if (!isMobileWeb && !hasAppStep)
+        continue;
+      const driverPackage = deps.appDriverPlatforms[mobileTarget]?.driverPackage;
+      if (driverPackage) {
+        addTask({
+          name: `driver-install:${driverPackage}`,
+          kind: "driver-install",
+          exclusiveResources: [RUNTIME_INSTALL_RESOURCE],
+          payload: { driverPackage, platform: mobileTarget }
+        });
+      }
+      for (const stepDevice of deps.collectDeviceDescriptors(context)) {
+        const desc = deps.normalizeDeviceDescriptor({
+          contextDevice: context.device,
+          stepDevice,
+          platform: mobileTarget
+        });
+        const identity = deviceIdentity(mobileTarget, desc);
+        const tag = deviceResourceTag(mobileTarget, desc);
+        if (!bootPlannedFor.has(mobileTarget)) {
+          bootPlannedFor.add(mobileTarget);
+          addTask({
+            name: `device-boot:${identity}`,
+            kind: "device-boot",
+            exclusiveResources: [tag],
+            payload: { platform: mobileTarget, desc }
+          });
+        }
+        if (mobileTarget === "android" && isMobileWeb) {
+          addTask({
+            name: `chromedriver-prefetch:${identity}`,
+            kind: "chromedriver-prefetch",
+            exclusiveResources: [tag],
+            payload: { platform: mobileTarget, desc }
+          });
+        }
+      }
+      if (mobileTarget === "ios") {
+        addTask({
+          name: "wda-check",
+          kind: "wda-check",
+          // Read-only (plus the last-used stamp) — contends with nothing.
+          exclusiveResources: [],
+          payload: {}
+        });
+      }
+      continue;
+    }
+    if (deps.isBrowserRequired({ test: context })) {
+      const effBrowser = context.browser ?? getDefaultBrowser2();
+      const browserName = effBrowser?.name;
+      if (browserName && effPlatform === hostPlatform) {
+        probeEligible = true;
+        if (deps.requiredBrowserAssets(browserName).length > 0) {
+          addTask({
+            name: `browser-install:${browserName.toLowerCase()}`,
+            kind: "browser-install",
+            exclusiveResources: [RUNTIME_INSTALL_RESOURCE],
+            payload: { browserName }
+          });
+        }
+      }
+    }
+    if ((effPlatform === "windows" || effPlatform === "mac") && effPlatform === hostPlatform && deps.isAppDriverRequired({ test: context })) {
+      const driverPackage = deps.appDriverPlatforms[effPlatform]?.driverPackage;
+      if (driverPackage) {
+        addTask({
+          name: `driver-install:${driverPackage}`,
+          kind: "driver-install",
+          exclusiveResources: [RUNTIME_INSTALL_RESOURCE],
+          payload: { driverPackage, platform: effPlatform }
+        });
+      }
+    }
+  }
+  if (limit > 1 && hasAppiumPool && probeEligible) {
+    addTask({
+      name: "session-probe",
+      kind: "session-probe",
+      // Its install half mutates the shared caches, exactly like the
+      // dedicated install tasks (usually a memo hit by the time it runs).
+      exclusiveResources: [RUNTIME_INSTALL_RESOURCE],
+      payload: {}
+    });
+  }
+  return tasks;
+}
+async function executeWarmTasks({ tasks, registry, runTask, log: log3, now = Date.now }) {
+  const results = [];
+  const start = now();
+  await runResourceAware(tasks, WARM_POOL_LIMIT, registry, async (task) => {
+    const taskStart = now();
+    try {
+      const { outcome, note } = await runTask(task);
+      results.push({
+        name: task.name,
+        kind: task.kind,
+        outcome,
+        durationMs: now() - taskStart,
+        ...note ? { note } : {}
+      });
+      if (outcome === "failed") {
+        log3("warning", `Warm task '${task.name}' failed (continuing)${note ? `: ${note}` : "."}`);
+      } else {
+        log3("debug", `Warm task '${task.name}': ${outcome}${note ? ` (${note})` : ""}.`);
+      }
+    } catch (error) {
+      const note = error?.message ?? String(error);
+      results.push({
+        name: task.name,
+        kind: task.kind,
+        outcome: "failed",
+        durationMs: now() - taskStart,
+        note
+      });
+      log3("warning", `Warm task '${task.name}' failed (continuing): ${note}`);
+    }
+  });
+  return { durationMs: now() - start, tasks: results };
+}
+function raceBootInitiation({ startAcquire, onError }) {
+  let initiatedResolve;
+  const initiated = new Promise((resolve) => {
+    initiatedResolve = resolve;
+  });
+  const acquired = (async () => {
+    try {
+      const result = await startAcquire(() => initiatedResolve());
+      if (result && typeof result === "object" && "skip" in result) {
+        return { outcome: "skipped", note: result.skip };
+      }
+      return { outcome: "warmed", note: "device ready" };
+    } catch (error) {
+      onError(error);
+      return {
+        outcome: "failed",
+        note: error?.message ?? String(error)
+      };
+    }
+  })();
+  return Promise.race([
+    initiated.then(() => ({
+      outcome: "warmed",
+      note: "boot initiated"
+    })),
+    acquired
+  ]);
+}
+
 // dist/core/tests.js
 init_cacheDir();
 
@@ -649001,6 +649340,13 @@ async function teardownSimulatorRegistry(registry, shutdown) {
   for (const entry of registry.values()) {
     if (!entry.bootedByUs)
       continue;
+    if (entry.ready) {
+      try {
+        await entry.ready;
+      } catch {
+        continue;
+      }
+    }
     try {
       await shutdown(entry);
     } catch {
@@ -649537,6 +649883,20 @@ function combinationKey(context) {
 function warmUpDecision(prev) {
   return prev === "failed" ? "skip" : "attempt";
 }
+function buildWarmPlanDeps() {
+  return {
+    isBrowserRequired,
+    isAppDriverRequired,
+    isMobileTargetPlatform,
+    getDefaultBrowser,
+    requiredBrowserAssets,
+    collectDeviceDescriptors,
+    normalizeDeviceDescriptor,
+    mobileBrowserGate,
+    contextRequirementsSkipMessage,
+    appDriverPlatforms: APP_DRIVER_PLATFORMS
+  };
+}
 function getDriverCapabilities({ runnerDetails, name, options }) {
   let capabilities = {};
   let args = [];
@@ -650146,7 +650506,12 @@ async function runSpecs({ resolvedTests }) {
         skipped: 0
       }
     },
-    specs: []
+    specs: [],
+    // Inline warm phase results (docs/design/warm-phase.md). Present on the
+    // skeleton so a run that plans nothing (or whose planning fails —
+    // best-effort) still reports the structural empty block; the phase
+    // overwrites it with real task results below.
+    warm: { durationMs: 0, tasks: [] }
   };
   let limit = resolveConcurrentRunners(config);
   log(config, "info", "Running test specs.");
@@ -650301,6 +650666,7 @@ async function runSpecs({ resolvedTests }) {
     const serverCount = Math.min(limit, browserPoolJobCount);
     log(config, "debug", `Starting ${serverCount} Appium server(s).`);
     try {
+      const readinessWaits = [];
       for (let i = 0; i < serverCount; i++) {
         let display;
         if (useXvfbDisplays) {
@@ -650308,7 +650674,16 @@ async function runSpecs({ resolvedTests }) {
           xvfbProcesses.push(await startXvfb(display));
           log(config, "debug", `Started Xvfb on ${display} for recording.`);
         }
-        appiumServers.push(await startAppiumServer(appiumEntry, config, display));
+        const server = await spawnAppiumServer(appiumEntry, config, display);
+        appiumServers.push(server);
+        const wait2 = appiumIsReady(server.port);
+        wait2.catch(() => {
+        });
+        readinessWaits.push(wait2);
+      }
+      await Promise.all(readinessWaits);
+      for (const server of appiumServers) {
+        log(config, "debug", `Appium is ready on port ${server.port}.`);
       }
     } catch (error) {
       await Promise.all(appiumServers.map((server) => {
@@ -650331,6 +650706,7 @@ async function runSpecs({ resolvedTests }) {
   const processRegistry = /* @__PURE__ */ new Map();
   const deviceRegistry = createDeviceRegistry();
   const simulatorRegistry = createSimulatorRegistry();
+  const resourceRegistry = createResourceRegistry();
   const killAllRegistered = async () => {
     const entries = [...processRegistry.entries()];
     processRegistry.clear();
@@ -650367,15 +650743,35 @@ async function runSpecs({ resolvedTests }) {
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
   try {
-    if (limit > 1 && appiumPool) {
-      await warmUpContexts({
-        jobs: sizingJobs,
-        config,
+    try {
+      const warmTasks = planWarmTasks({
+        sizingJobs,
         runnerDetails,
-        appiumPool,
-        installAttempts,
-        warmUpResults
+        limit,
+        hasAppiumPool: !!appiumPool,
+        deps: buildWarmPlanDeps()
       });
+      if (warmTasks.length > 0) {
+        log(config, "debug", `Warm phase: ${warmTasks.length} task(s).`);
+        report.warm = await executeWarmTasks({
+          tasks: warmTasks,
+          registry: resourceRegistry,
+          runTask: buildWarmTaskRunner({
+            config,
+            runnerDetails,
+            sizingJobs,
+            appiumPool,
+            installAttempts,
+            warmUpResults,
+            deviceRegistry,
+            simulatorRegistry,
+            resourceRegistry
+          }),
+          log: (level, message) => log(config, level, message)
+        });
+      }
+    } catch (error) {
+      log(config, "warning", `Warm phase skipped (planning failed; the run proceeds with on-demand provisioning): ${error?.message ?? error}`);
     }
     const runJob = async (job) => {
       try {
@@ -650427,7 +650823,6 @@ async function runSpecs({ resolvedTests }) {
       const phase = PHASES.includes(entry.spec?._phase) ? entry.spec._phase : "main";
       routedByPhase[phase].push(entry);
     }
-    const resourceRegistry = createResourceRegistry();
     for (const phase of PHASES) {
       if (limit > 1) {
         await runResourceAware(jobsByPhase[phase], limit, resourceRegistry, runJob);
@@ -650741,27 +651136,17 @@ async function warmUpContexts({ jobs, config, runnerDetails, appiumPool, install
       platform
     });
     if (!supported && context.platform === platform && Array.isArray(context?.steps) && requiredBrowserAssets(context.browser?.name).length > 0) {
-      const firstAttempt = !installAttempts.has((context.browser?.name ?? "<none>").toLowerCase());
-      const outcome = await ensureContextBrowserInstalled({
+      await warmBrowserInstall({
         browserName: context.browser?.name,
         config,
-        installAttempts,
-        deps: {
-          ensureBrowser: (asset, options) => ensureBrowserInstalled(asset, options),
-          log
-        },
-        // Repair a present-but-broken driver, not just install-if-missing.
-        repair: true
+        runnerDetails,
+        installAttempts
+      });
+      supported = isSupportedContext({
+        context,
+        apps: runnerDetails.availableApps,
+        platform
       });
-      if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
-        clearAppCache(config);
-        runnerDetails.availableApps = await getAvailableApps({ config });
-        supported = isSupportedContext({
-          context,
-          apps: runnerDetails.availableApps,
-          platform
-        });
-      }
     }
     if (!supported)
       continue;
@@ -650803,6 +651188,292 @@ async function warmUpContexts({ jobs, config, runnerDetails, appiumPool, install
     }
   }
 }
+async function warmBrowserInstall({ browserName, config, runnerDetails, installAttempts, deps = {} }) {
+  const appName = normalizeBrowserName(browserName);
+  if (runnerDetails.availableApps?.find((app) => app.name === appName)) {
+    return {
+      outcome: "skipped",
+      note: `'${browserName}' is already available`
+    };
+  }
+  const firstAttempt = !installAttempts.has((browserName ?? "<none>").toLowerCase());
+  const outcome = await ensureContextBrowserInstalled({
+    browserName,
+    config,
+    installAttempts,
+    deps: {
+      ensureBrowser: deps.ensureBrowser ?? ((asset, options) => ensureBrowserInstalled(asset, options)),
+      log
+    },
+    // Repair a present-but-broken driver, not just install-if-missing.
+    repair: true
+  });
+  if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
+    (deps.clearAppCache ?? clearAppCache)(config);
+    runnerDetails.availableApps = await (deps.getAvailableApps ?? getAvailableApps)({ config });
+  }
+  if (outcome === "installed")
+    return { outcome: "warmed" };
+  if (outcome === "failed") {
+    return { outcome: "failed", note: `couldn't install '${browserName}'` };
+  }
+  return {
+    outcome: "skipped",
+    note: `'${browserName}' has no installable assets`
+  };
+}
+async function resolveAndroidWarmEnv(config) {
+  try {
+    const abi = hostAbi();
+    const sdk = detectAndroidSdk({ cacheDir: config?.cacheDir });
+    if (!sdk?.emulator)
+      return null;
+    const deviceDeps = buildAcquireDeviceDeps(sdk, abi, (m) => log(config, "debug", m));
+    const running = await deviceDeps.listRunning();
+    const capable = running.length > 0 || await checkEmulatorAcceleration(sdk.emulator);
+    if (!capable)
+      return null;
+    return { sdkRoot: sdk.sdkRoot, deviceDeps };
+  } catch {
+    return null;
+  }
+}
+async function probeIosToolchainWarm() {
+  if (process.platform !== "darwin")
+    return probeIosToolchain();
+  const runAsync = (command, args, timeout) => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    try {
+      const child = (0, import_node_child_process15.spawn)(command, args, { windowsHide: true, timeout });
+      child.stdout?.on("data", (d) => stdout += String(d));
+      child.stderr?.on("data", (d) => stderr += String(d));
+      child.on("error", () => resolve({ status: null, stdout, stderr }));
+      child.on("close", (status) => resolve({ status, stdout, stderr }));
+    } catch {
+      resolve({ status: null, stdout, stderr });
+    }
+  });
+  const [xcodeSelect, simctl] = await Promise.all([
+    runAsync("xcode-select", ["-p"], 15e3),
+    // Same generous ceiling as the sync probe's xcrun spawn: the first cold
+    // simctl call launches CoreSimulatorService.
+    runAsync("xcrun", ["simctl", "list", "devices", "available"], 12e4)
+  ]);
+  return probeIosToolchain({
+    run: (command) => command === "xcrun" ? simctl : xcodeSelect
+  });
+}
+function buildWarmTaskRunner({ config, runnerDetails, sizingJobs, appiumPool, installAttempts, warmUpResults, deviceRegistry, simulatorRegistry, resourceRegistry }) {
+  let androidEnv;
+  const getAndroidEnv = () => androidEnv ??= resolveAndroidWarmEnv(config);
+  let iosToolchain;
+  const getIosToolchain = () => iosToolchain ??= probeIosToolchainWarm();
+  const acquireLease = async (names) => {
+    while (!resourceRegistry.tryAcquire(names)) {
+      await resourceRegistry.waitForFree();
+    }
+    let released = false;
+    return () => {
+      if (released)
+        return;
+      released = true;
+      resourceRegistry.release(names);
+    };
+  };
+  const withRuntimeInstallLock = async (fn) => {
+    const release = await acquireLease([RUNTIME_INSTALL_RESOURCE]);
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  };
+  let androidPreflight;
+  const getAndroidPreflight = () => androidPreflight ??= withRuntimeInstallLock(() => appSurfacePreflight({ config, platform: "android" }));
+  return async (task) => {
+    switch (task.kind) {
+      case "browser-install":
+        return warmBrowserInstall({
+          browserName: task.payload.browserName,
+          config,
+          runnerDetails,
+          installAttempts
+        });
+      case "driver-install": {
+        if (task.payload.platform === "android") {
+          const env = await getAndroidEnv();
+          if (!env) {
+            return {
+              outcome: "skipped",
+              note: "Android toolchain not ready; the driver install stays with the consuming context"
+            };
+          }
+        }
+        if (task.payload.platform === "ios") {
+          const toolchain = await getIosToolchain();
+          if (!toolchain.ok) {
+            return { outcome: "skipped", note: toolchain.reason };
+          }
+        }
+        const { ensureRuntimeInstalled: ensureRuntimeInstalled2 } = await Promise.resolve().then(() => (init_loader(), loader_exports));
+        await ensureRuntimeInstalled2([task.payload.driverPackage], {
+          ctx: { cacheDir: config?.cacheDir },
+          deps: { logger: (m) => log(config, "debug", m) }
+        });
+        return { outcome: "warmed" };
+      }
+      case "device-boot": {
+        const desc = task.payload.desc;
+        const onError = (error) => log(config, "warning", `Warm boot of '${task.name}' failed (a consuming context will retry): ${error?.message ?? String(error)}`);
+        if (task.payload.platform === "android") {
+          const env = await getAndroidEnv();
+          if (!env) {
+            return {
+              outcome: "skipped",
+              note: "Android toolchain not ready; device setup stays with the consuming context"
+            };
+          }
+          const releaseEmulatorLease = await acquireLease([
+            "android-emulator"
+          ]);
+          return raceBootInitiation({
+            onError,
+            startAcquire: (signalInitiated) => {
+              const acquiring = acquireDevice({
+                desc,
+                registry: deviceRegistry,
+                sdkRoot: env.sdkRoot,
+                deps: wrapInitiationEffects(env.deviceDeps, ["createAvd", "boot"], signalInitiated)
+              });
+              acquiring.then(() => releaseEmulatorLease(), () => releaseEmulatorLease());
+              return acquiring;
+            }
+          });
+        }
+        const toolchain = await getIosToolchain();
+        if (!toolchain.ok) {
+          return { outcome: "skipped", note: toolchain.reason };
+        }
+        const simDeps = buildAcquireSimulatorDeps((m) => log(config, "debug", m));
+        return raceBootInitiation({
+          onError,
+          startAcquire: (signalInitiated) => acquireSimulator({
+            desc,
+            registry: simulatorRegistry,
+            deps: wrapInitiationEffects(simDeps, ["create", "boot"], signalInitiated)
+          })
+        });
+      }
+      case "wda-check": {
+        const hit = locateManagedWda({ ctx: { cacheDir: config?.cacheDir } });
+        if (hit) {
+          return {
+            outcome: "warmed",
+            note: `prebuilt WebDriverAgent available (${hit.key})`
+          };
+        }
+        return {
+          outcome: "skipped",
+          note: "no prebuilt WebDriverAgent for the current toolchain \u2014 `doc-detective install ios` prebuilds it"
+        };
+      }
+      case "session-probe": {
+        if (!appiumPool) {
+          return { outcome: "skipped", note: "no browser Appium pool" };
+        }
+        await warmUpContexts({
+          jobs: sizingJobs,
+          config,
+          runnerDetails,
+          appiumPool,
+          installAttempts,
+          warmUpResults
+        });
+        const ok = [...warmUpResults.values()].filter((v) => v === "ok").length;
+        const failed = warmUpResults.size - ok;
+        return {
+          outcome: "warmed",
+          note: `${ok} combination${ok === 1 ? "" : "s"} ok${failed ? `, ${failed} failed` : ""}`
+        };
+      }
+      case "chromedriver-prefetch":
+        return prefetchMobileChromedriver({
+          config,
+          desc: task.payload.desc,
+          deviceRegistry,
+          getAndroidEnv,
+          deps: {
+            // The cache-mutating half (driver install + Appium co-homing)
+            // runs once per run under the manual runtime-install lease, so
+            // the prefetch task itself only holds its device tag while it
+            // awaits readiness and runs the throwaway session.
+            appSurfacePreflight: () => getAndroidPreflight(),
+            acquireEmulatorLease: () => acquireLease(["android-emulator"])
+          }
+        });
+    }
+  };
+}
+async function prefetchMobileChromedriver({ config, desc, deviceRegistry, getAndroidEnv, deps = {} }) {
+  const preflight = deps.appSurfacePreflight ?? appSurfacePreflight;
+  const acquire = deps.acquireDevice ?? acquireDevice;
+  const startServer = deps.startAppiumServer ?? startAppiumServer;
+  const startDriver = deps.driverStart ?? driverStart;
+  const kill4 = deps.killTree ?? killTree;
+  const env = await getAndroidEnv();
+  if (!env) {
+    return {
+      outcome: "skipped",
+      note: "Android toolchain not ready; the first mobile-web session downloads chromedriver as needed"
+    };
+  }
+  const pre = await preflight({ config, platform: "android" });
+  if (!pre.ok)
+    return { outcome: "skipped", note: pre.reason };
+  const releaseLease = deps.acquireEmulatorLease ? await deps.acquireEmulatorLease() : void 0;
+  let acquired;
+  try {
+    acquired = await acquire({
+      desc,
+      registry: deviceRegistry,
+      sdkRoot: env.sdkRoot,
+      deps: env.deviceDeps
+    });
+  } finally {
+    releaseLease?.();
+  }
+  if ("skip" in acquired)
+    return { outcome: "skipped", note: acquired.skip };
+  let server;
+  let driver;
+  try {
+    server = await startServer(pre.appiumEntry, config, void 0, {
+      APPIUM_HOME: pre.appiumHome,
+      ANDROID_HOME: env.sdkRoot,
+      ANDROID_SDK_ROOT: env.sdkRoot
+    }, CHROMEDRIVER_AUTODOWNLOAD_ARGS);
+    driver = await startDriver(buildMobileBrowserCapabilities({
+      platform: "android",
+      udid: acquired.entry.udid,
+      cacheDir: getCacheDir({ cacheDir: config?.cacheDir })
+    }), server.port, 2, { cacheDir: config?.cacheDir });
+    return {
+      outcome: "warmed",
+      note: `chromedriver ready for device '${acquired.entry.name}'`
+    };
+  } finally {
+    if (driver) {
+      try {
+        await driver.deleteSession();
+      } catch {
+      }
+    }
+    if (server) {
+      await kill4(server.process?.pid);
+    }
+  }
+}
 function specIsRouted(spec) {
   if (!spec || !Array.isArray(spec.tests))
     return false;
@@ -651150,7 +651821,8 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     contextReport.resultDescription = errorMessage;
     return contextReport;
   }
-  clog("debug", `CONTEXT:
+  if (logLevelEnabled(config, "debug"))
+    clog("debug", `CONTEXT:
 ${JSON.stringify(context, null, 2)}`);
   let driver;
   let appiumPort;
@@ -651169,7 +651841,7 @@ ${JSON.stringify(context, null, 2)}`);
         env.ANDROID_HOME = appSession.androidSdkRoot;
         env.ANDROID_SDK_ROOT = appSession.androidSdkRoot;
       }
-      const extraArgs = mobileTarget === "android" ? ["--allow-insecure", "uiautomator2:chromedriver_autodownload"] : [];
+      const extraArgs = mobileTarget === "android" ? CHROMEDRIVER_AUTODOWNLOAD_ARGS : [];
       let acquired;
       try {
         const server = await startAppiumServer(appSession.appiumEntry, config, void 0, env, extraArgs);
@@ -651462,7 +652134,8 @@ ${JSON.stringify(context, null, 2)}`);
         stepExecutionFailed = true;
         break;
       }
-      clog("debug", `STEP:
+      if (logLevelEnabled(config, "debug"))
+        clog("debug", `STEP:
 ${JSON.stringify(step, null, 2)}`);
       if (step.unsafe && runnerDetails.allowUnsafeSteps === false) {
         clog("warning", `Skipping unsafe step: ${step.description} in test ${test.testId} context ${context.contextId}`);
@@ -651528,7 +652201,8 @@ ${JSON.stringify(step, null, 2)}`);
           processRegistry,
           appSession
         });
-        clog("debug", `RESULT: ${r.status}
+        if (logLevelEnabled(config, "debug"))
+          clog("debug", `RESULT: ${r.status}
 ${JSON.stringify(r, null, 2)}`);
         r.result = r.status;
         r.resultDescription = r.description;
@@ -651925,7 +652599,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
   }
   return actionResult;
 }
-async function startAppiumServer(appiumEntry, config, display, extraEnv, extraArgs) {
+async function spawnAppiumServer(appiumEntry, config, display, extraEnv, extraArgs) {
   const port = await findFreePort();
   log(config, "debug", `Starting Appium on port ${port}`);
   const env = display || extraEnv ? {
@@ -651945,31 +652619,41 @@ async function startAppiumServer(appiumEntry, config, display, extraEnv, extraAr
   });
   proc.stderr.on("data", () => {
   });
+  return { port, process: proc, display };
+}
+async function startAppiumServer(appiumEntry, config, display, extraEnv, extraArgs) {
+  const server = await spawnAppiumServer(appiumEntry, config, display, extraEnv, extraArgs);
   try {
-    await appiumIsReady(port);
+    await appiumIsReady(server.port);
   } catch (error) {
-    await killTree(proc?.pid);
+    await killTree(server.process?.pid);
     throw error;
   }
-  log(config, "debug", `Appium is ready on port ${port}.`);
-  return { port, process: proc, display };
+  log(config, "debug", `Appium is ready on port ${server.port}.`);
+  return server;
 }
-async function appiumIsReady(port, timeoutMs = 12e4) {
-  let isReady = false;
+var STATUS_PROBE_TIMEOUT_MS = 1e4;
+async function appiumIsReady(port, timeoutMs = 12e4, deps = {}) {
+  const probe = deps.probe ?? (async (p) => {
+    try {
+      const resp = await import_axios6.default.get(`http://127.0.0.1:${p}/status`, {
+        timeout: STATUS_PROBE_TIMEOUT_MS
+      });
+      return resp.status === 200;
+    } catch {
+      return false;
+    }
+  });
+  const sleep4 = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const start = Date.now();
-  while (!isReady) {
+  while (true) {
+    if (await probe(port))
+      return true;
     if (Date.now() - start > timeoutMs) {
       throw new Error(`Appium server on port ${port} failed to start within ${timeoutMs / 1e3} seconds`);
     }
-    await new Promise((resolve) => setTimeout(resolve, 1e3));
-    try {
-      let resp = await import_axios6.default.get(`http://127.0.0.1:${port}/status`);
-      if (resp.status === 200)
-        isReady = true;
-    } catch {
-    }
+    await sleep4(250);
   }
-  return isReady;
 }
 async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
   const wdio = await loadHeavyDep("webdriverio", { ctx });
@@ -652159,6 +652843,8 @@ function telemetryNotice(config) {
     log(config, "info", "Doc Detective collects basic anonymous telemetry to understand product issues and usage. To disable telemetry, set 'telemetry.send' to 'false' in your .doc-detective.json config file.");
   }
 }
+var TELEMETRY_FLUSH_TIMEOUT_MS = 2e3;
+var pendingTelemetryFlush = null;
 function sendTelemetry(config, command, results) {
   if (config?.telemetry?.send === false)
     return;
@@ -652199,7 +652885,7 @@ function sendTelemetry(config, command, results) {
   const event = { distinctId, event: command, properties: telemetryData };
   const client = new import_posthog_node.PostHog("phc_rjV0MH3nsAd45zFISLgaKAdAXbgDeXt2mOBV2EBHomB", { host: "https://app.posthog.com" });
   client.capture(event);
-  client.shutdown();
+  pendingTelemetryFlush = Promise.resolve(client.shutdown(TELEMETRY_FLUSH_TIMEOUT_MS)).then(() => void 0).catch(() => void 0);
 }
 
 // dist/core/index.js