doc-detective 4.6.1 → 4.7.0-runtime-dependency-detection.1

package/dist/index.cjs

@@ -9923,7 +9923,8 @@ var init_schemas = __esm({
             title: "Environment details"
           },
           debug: {
-            description: "Enable debugging mode. `true` allows pausing on breakpoints, waiting for user input before continuing. `stepThrough` pauses at every step, waiting for user input before continuing. `false` disables all debugging.",
+            description: "Deprecated and ignored. Previously reserved for an interactive step-through debugger that was never implemented. Retained so existing configs continue to validate. For diagnostics, run `doc-detective debug` or set the `DOC_DETECTIVE_DEBUG` environment variable.",
+            deprecated: true,
             anyOf: [
               {
                 type: "boolean"
@@ -9934,8 +9935,7 @@ var init_schemas = __esm({
                   "stepThrough"
                 ]
               }
-            ],
-            default: false
+            ]
           },
           dryRun: {
             description: "If `true`, fully resolve tests (file/env config merge, schema validation, file detection, inline-test extraction) and emit the resolved test plan as JSON, but do not execute any steps. Equivalent to `--dry-run` on the CLI.",
@@ -18245,12 +18245,6 @@ var init_schemas = __esm({
           {
             debug: false
           },
-          {
-            debug: true
-          },
-          {
-            debug: "stepThrough"
-          },
           {
             integrations: {
               docDetectiveApi: {
@@ -31882,7 +31876,8 @@ var init_schemas = __esm({
                 title: "Environment details"
               },
               debug: {
-                description: "Enable debugging mode. `true` allows pausing on breakpoints, waiting for user input before continuing. `stepThrough` pauses at every step, waiting for user input before continuing. `false` disables all debugging.",
+                description: "Deprecated and ignored. Previously reserved for an interactive step-through debugger that was never implemented. Retained so existing configs continue to validate. For diagnostics, run `doc-detective debug` or set the `DOC_DETECTIVE_DEBUG` environment variable.",
+                deprecated: true,
                 anyOf: [
                   {
                     type: "boolean"
@@ -31893,8 +31888,7 @@ var init_schemas = __esm({
                       "stepThrough"
                     ]
                   }
-                ],
-                default: false
+                ]
               },
               dryRun: {
                 description: "If `true`, fully resolve tests (file/env config merge, schema validation, file detection, inline-test extraction) and emit the resolved test plan as JSON, but do not execute any steps. Equivalent to `--dry-run` on the CLI.",
@@ -40204,12 +40198,6 @@ var init_schemas = __esm({
               {
                 debug: false
               },
-              {
-                debug: true
-              },
-              {
-                debug: "stepThrough"
-              },
               {
                 integrations: {
                   docDetectiveApi: {
@@ -130740,7 +130728,9 @@ var loader_exports = {};
 __export(loader_exports, {
   ensureRuntimeInstalled: () => ensureRuntimeInstalled,
   loadHeavyDep: () => loadHeavyDep,
-  resolveHeavyDepPath: () => resolveHeavyDepPath
+  resolveHeavyDepPath: () => resolveHeavyDepPath,
+  resolveHeavyDepSource: () => resolveHeavyDepSource,
+  resolveHeavyDepVersion: () => resolveHeavyDepVersion
 });
 function tryResolveFromShim(name) {
   try {
@@ -130764,6 +130754,36 @@ function tryResolveFromCache(name, ctx = {}) {
 function resolveHeavyDepPath(name, ctx = {}) {
   return tryResolveFromShim(name) ?? tryResolveFromCache(name, ctx);
 }
+function resolveHeavyDepSource(name, ctx = {}) {
+  if (tryResolveFromShim(name))
+    return "shim";
+  if (tryResolveFromCache(name, ctx))
+    return "cache";
+  return null;
+}
+function resolveHeavyDepVersion(name, ctx = {}) {
+  const entry = resolveHeavyDepPath(name, ctx);
+  if (!entry)
+    return null;
+  let dir = import_node_path4.default.dirname(entry);
+  for (let i = 0; i < 12; i++) {
+    const pkgJsonPath = import_node_path4.default.join(dir, "package.json");
+    try {
+      if (import_node_fs4.default.existsSync(pkgJsonPath)) {
+        const parsed = JSON.parse(import_node_fs4.default.readFileSync(pkgJsonPath, "utf8"));
+        if (parsed?.name === name && typeof parsed.version === "string") {
+          return parsed.version;
+        }
+      }
+    } catch {
+    }
+    const parent = import_node_path4.default.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
 async function loadHeavyDep(name, options = {}) {
   const { autoInstall = true, ctx = {}, deps = {} } = options;
   let resolved = tryResolveFromShim(name);
@@ -131426,6 +131446,7 @@ var config_exports = {};
 __export(config_exports, {
   clearAppCache: () => clearAppCache,
   getAvailableApps: () => getAvailableApps,
+  getBrowserDiagnostics: () => getBrowserDiagnostics,
   getEnvironment: () => getEnvironment,
   resolveConcurrentRunners: () => resolveConcurrentRunners,
   setConfig: () => setConfig
@@ -131619,19 +131640,14 @@ function clearAppCache(config) {
   }
   cachedAppsByDir.delete(cacheKeyFor(config));
 }
-async function getAvailableApps({ config }) {
-  const browsersDir = getBrowsersDir({ cacheDir: config?.cacheDir });
-  const key = browsersDir;
-  const hit = cachedAppsByDir.get(key);
-  if (hit)
-    return hit;
+async function probeBrowserEnvironment({ config, browsersDir }) {
   setAppiumHome({ cacheDir: config?.cacheDir });
   const cwd = process.cwd();
   process.chdir(import_node_path7.default.join(__dirname4, "../.."));
-  const apps = [];
+  let installedBrowsers = [];
   let browserDetectionFailed = false;
+  let appiumDriverOutput = "";
   try {
-    let installedBrowsers = [];
     const browsersInstalled = resolveHeavyDepPath("@puppeteer/browsers", {
       cacheDir: config?.cacheDir
     });
@@ -131686,47 +131702,165 @@ async function getAvailableApps({ config }) {
         });
       });
     });
-    const appiumDriverOutput = installedAppiumDrivers.stdout + "\n" + installedAppiumDrivers.stderr;
-    const chrome = installedBrowsers.find((browser) => browser.browser === "chrome");
-    const chromeVersion = chrome?.buildId;
-    const chromedriver = installedBrowsers.find((browser) => browser.browser === "chromedriver");
-    const appiumChromium = appiumDriverOutput.match(/\n.*chromium.*installed \(npm\).*\n/);
-    if (chrome && chromedriver && appiumChromium) {
-      apps.push({
-        name: "chrome",
-        version: chromeVersion,
-        path: chrome.executablePath,
-        driver: chromedriver.executablePath
-      });
-    }
-    const firefox = installedBrowsers.find((browser) => browser.browser === "firefox");
-    const appiumFirefox = appiumDriverOutput.match(/\n.*gecko.*installed \(npm\).*\n/);
-    if (firefox && appiumFirefox) {
-      apps.push({
-        name: "firefox",
-        version: firefox.buildId,
-        path: firefox.executablePath
-      });
-    }
-    if (config.environment.platform === "mac") {
-      const safariVersion = await spawnCommand("defaults read /Applications/Safari.app/Contents/Info.plist CFBundleShortVersionString");
-      const appiumSafari = appiumDriverOutput.match(/\n.*safari.*installed \(npm\).*\n/);
-      if (safariVersion.exitCode === 0 && appiumSafari) {
-        apps.push({ name: "safari", version: safariVersion.stdout.trim(), path: "" });
-      }
-    }
+    appiumDriverOutput = installedAppiumDrivers.stdout + "\n" + installedAppiumDrivers.stderr;
   } finally {
     process.chdir(cwd);
   }
+  return { installedBrowsers, appiumDriverOutput, browserDetectionFailed };
+}
+async function getAvailableApps({ config }) {
+  const browsersDir = getBrowsersDir({ cacheDir: config?.cacheDir });
+  const key = browsersDir;
+  const hit = cachedAppsByDir.get(key);
+  if (hit)
+    return hit;
+  const { installedBrowsers, appiumDriverOutput, browserDetectionFailed } = await probeBrowserEnvironment({ config, browsersDir });
+  const apps = [];
+  const chrome = installedBrowsers.find((browser) => browser.browser === "chrome");
+  const chromeVersion = chrome?.buildId;
+  const chromedriver = installedBrowsers.find((browser) => browser.browser === "chromedriver");
+  const appiumChromium = appiumDriverOutput.match(/\n.*chromium.*installed \(npm\).*\n/);
+  if (chrome && chromedriver && appiumChromium) {
+    apps.push({
+      name: "chrome",
+      version: chromeVersion,
+      path: chrome.executablePath,
+      driver: chromedriver.executablePath
+    });
+  }
+  const firefox = installedBrowsers.find((browser) => browser.browser === "firefox");
+  const appiumFirefox = appiumDriverOutput.match(/\n.*gecko.*installed \(npm\).*\n/);
+  if (firefox && appiumFirefox) {
+    apps.push({
+      name: "firefox",
+      version: firefox.buildId,
+      path: firefox.executablePath
+    });
+  }
+  if (config.environment.platform === "mac") {
+    const safariVersion = await spawnCommand("defaults read /Applications/Safari.app/Contents/Info.plist CFBundleShortVersionString");
+    const appiumSafari = appiumDriverOutput.match(/\n.*safari.*installed \(npm\).*\n/);
+    if (safariVersion.exitCode === 0 && appiumSafari) {
+      apps.push({ name: "safari", version: safariVersion.stdout.trim(), path: "" });
+    }
+  }
   if (!browserDetectionFailed)
     cachedAppsByDir.set(key, apps);
   return apps;
 }
-var import_node_os3, import_node_path7, import_node_child_process3, import_node_url5, __dirname4, platformMap, defaultFileTypes, cachedAppsByDir;
+function probeSafariVersion(timeoutMs) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = (0, import_node_child_process3.spawn)("defaults", [
+        "read",
+        "/Applications/Safari.app/Contents/Info.plist",
+        "CFBundleShortVersionString"
+      ], { stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      resolve(null);
+      return;
+    }
+    let stdout = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child.kill();
+      } catch {
+      }
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    timer.unref?.();
+    child.stdout?.on("data", (c) => {
+      stdout += typeof c === "string" ? c : c.toString("utf8");
+    });
+    child.on("error", () => finish(null));
+    child.on("close", (code) => finish(code === 0 ? stdout.trim() : null));
+  });
+}
+async function getBrowserDiagnostics({ config }) {
+  let detectionFailed = false;
+  let record;
+  try {
+    record = readInstalledRecord({ cacheDir: config?.cacheDir });
+  } catch {
+    detectionFailed = true;
+    record = { npmPackages: {}, browsers: {} };
+  }
+  const browsersRec = record.browsers || {};
+  const platform = config?.environment?.platform;
+  const brow = (name) => browsersRec[name];
+  const npmInstalled = (name) => Boolean(resolveHeavyDepPath(name, { cacheDir: config?.cacheDir }));
+  const browsers = [];
+  const chrome = brow("chrome");
+  const chromedriver = brow("chromedriver");
+  const appiumChromium = npmInstalled("appium-chromium-driver");
+  browsers.push({
+    name: "chrome",
+    supported: true,
+    available: Boolean(chrome && chromedriver && appiumChromium),
+    components: [
+      { label: "chrome browser", installed: Boolean(chrome), detail: chrome?.installedVersion },
+      { label: "chromedriver", installed: Boolean(chromedriver), detail: chromedriver?.installedVersion },
+      { label: "appium-chromium-driver", installed: appiumChromium }
+    ]
+  });
+  const firefox = brow("firefox");
+  const geckodriver = brow("geckodriver");
+  const appiumGecko = npmInstalled("appium-geckodriver");
+  browsers.push({
+    name: "firefox",
+    supported: true,
+    available: Boolean(firefox && geckodriver && appiumGecko),
+    components: [
+      { label: "firefox browser", installed: Boolean(firefox), detail: firefox?.installedVersion },
+      { label: "geckodriver", installed: Boolean(geckodriver), detail: geckodriver?.installedVersion },
+      { label: "appium-geckodriver", installed: appiumGecko }
+    ]
+  });
+  const isMac = platform === "mac";
+  const appiumSafari = npmInstalled("appium-safari-driver");
+  let safariApp = false;
+  let safariVersion;
+  let safaridriver = false;
+  if (isMac) {
+    try {
+      const version = await probeSafariVersion(4e3);
+      safariApp = version !== null;
+      safariVersion = version ?? void 0;
+      safaridriver = import_node_fs7.default.existsSync("/usr/bin/safaridriver");
+    } catch {
+      detectionFailed = true;
+    }
+  }
+  browsers.push({
+    name: "safari",
+    supported: isMac,
+    available: Boolean(isMac && safariApp && safaridriver && appiumSafari),
+    components: [
+      { label: "Safari app", installed: safariApp, detail: safariVersion },
+      {
+        label: "safaridriver",
+        installed: safaridriver,
+        detail: safaridriver ? "/usr/bin/safaridriver" : void 0
+      },
+      { label: "appium-safari-driver", installed: appiumSafari }
+    ],
+    note: isMac ? void 0 : "Safari is only available on macOS"
+  });
+  return { browsers, detectionFailed };
+}
+var import_node_os3, import_node_fs7, import_node_path7, import_node_child_process3, import_node_url5, __dirname4, platformMap, defaultFileTypes, cachedAppsByDir;
 var init_config = __esm({
   "dist/core/config.js"() {
     "use strict";
     import_node_os3 = __toESM(require("node:os"), 1);
+    import_node_fs7 = __toESM(require("node:fs"), 1);
     init_validate();
     init_utils();
     import_node_path7 = __toESM(require("node:path"), 1);
@@ -132020,8 +132154,19 @@ var browsers_exports = {};
 __export(browsers_exports, {
   BROWSER_CHANNELS: () => BROWSER_CHANNELS,
   ensureBrowserInstalled: () => ensureBrowserInstalled,
-  getInstalledBrowsers: () => getInstalledBrowsers
+  getInstalledBrowsers: () => getInstalledBrowsers,
+  requiredBrowserAssets: () => requiredBrowserAssets
 });
+function requiredBrowserAssets(name) {
+  switch ((name ?? "").toLowerCase()) {
+    case "chrome":
+      return ["chrome", "chromedriver"];
+    case "firefox":
+      return ["firefox", "geckodriver"];
+    default:
+      return [];
+  }
+}
 async function loadPuppeteerBrowsers(deps, ctx) {
   if (deps.browsersModule)
     return deps.browsersModule;
@@ -132399,7 +132544,7 @@ module.exports = __toCommonJS(index_exports);
 init_config();
 
 // dist/core/detectTests.js
-var import_node_fs8 = __toESM(require("node:fs"), 1);
+var import_node_fs9 = __toESM(require("node:fs"), 1);
 var import_node_path9 = __toESM(require("node:path"), 1);
 var import_node_os5 = __toESM(require("node:os"), 1);
 var import_node_crypto3 = __toESM(require("node:crypto"), 1);
@@ -133231,7 +133376,7 @@ init_files();
 init_utils();
 
 // dist/core/integrations/heretto.js
-var import_node_fs7 = __toESM(require("node:fs"), 1);
+var import_node_fs8 = __toESM(require("node:fs"), 1);
 var import_node_path8 = __toESM(require("node:path"), 1);
 var import_node_https = __toESM(require("node:https"), 1);
 var import_node_http = __toESM(require("node:http"), 1);
@@ -133392,11 +133537,11 @@ var HerettoUploader = class {
         return result;
       }
     }
-    if (!import_node_fs7.default.existsSync(localFilePath)) {
+    if (!import_node_fs8.default.existsSync(localFilePath)) {
       result.description = `Local file not found: ${localFilePath}`;
       return result;
     }
-    const fileContent = import_node_fs7.default.readFileSync(localFilePath);
+    const fileContent = import_node_fs8.default.readFileSync(localFilePath);
     const contentType = this.getContentType(localFilePath);
     try {
       await this.uploadFile({
@@ -134170,7 +134315,7 @@ async function pollJobStatus(client, fileId, jobId, log3, config) {
   return null;
 }
 async function downloadAndExtractOutput(client, fileId, jobId, herettoName, log3, config, deps) {
-  const fsModule = deps?.fsModule || import_node_fs7.default;
+  const fsModule = deps?.fsModule || import_node_fs8.default;
   const ZipClass = deps?.ZipClass || import_adm_zip.default;
   const tempDir = import_node_path8.default.join(import_node_os4.default.tmpdir(), "doc-detective");
   const hash = import_node_crypto2.default.createHash("md5").update(`${herettoName}_${jobId}`).digest("hex");
@@ -134408,7 +134553,7 @@ async function isValidSourceFile({ config, files, source }) {
         } else {
           beforePath = import_node_path9.default.resolve(test.before);
         }
-        if (!import_node_fs8.default.existsSync(beforePath)) {
+        if (!import_node_fs9.default.existsSync(beforePath)) {
           log(config, "debug", `${beforePath} is specified to run before a test but isn't a valid file. Skipping ${source}.`);
           return false;
         }
@@ -134420,7 +134565,7 @@ async function isValidSourceFile({ config, files, source }) {
         } else {
           afterPath = import_node_path9.default.resolve(test.after);
         }
-        if (!import_node_fs8.default.existsSync(afterPath)) {
+        if (!import_node_fs9.default.existsSync(afterPath)) {
           log(config, "debug", `${afterPath} is specified to run after a test but isn't a valid file. Skipping ${source}.`);
           return false;
         }
@@ -134438,9 +134583,9 @@ async function processDitaMap({ config, source }) {
   const hash = import_node_crypto3.default.createHash("md5").update(source).digest("hex");
   const tmpBase = import_node_path9.default.join(import_node_os5.default.tmpdir(), "doc-detective");
   const outputDir = import_node_path9.default.join(tmpBase, `ditamap_${hash}`);
-  if (!import_node_fs8.default.existsSync(tmpBase)) {
+  if (!import_node_fs9.default.existsSync(tmpBase)) {
     log(config, "debug", `Creating temp directory: ${tmpBase}`);
-    import_node_fs8.default.mkdirSync(tmpBase, { recursive: true });
+    import_node_fs9.default.mkdirSync(tmpBase, { recursive: true });
   }
   const ditaVersion = await spawnCommand("dita", ["--version"]);
   if (ditaVersion.exitCode !== 0) {
@@ -134542,8 +134687,8 @@ async function qualifyFiles({ config }) {
     let isFile = false;
     let isDir = false;
     try {
-      isFile = import_node_fs8.default.statSync(source).isFile();
-      isDir = import_node_fs8.default.statSync(source).isDirectory();
+      isFile = import_node_fs9.default.statSync(source).isFile();
+      isDir = import_node_fs9.default.statSync(source).isDirectory();
     } catch {
       log(config, "warning", `Cannot access path: ${source}. Skipping.`);
       continue;
@@ -134563,13 +134708,13 @@ async function qualifyFiles({ config }) {
       dirs = [];
       dirs[0] = source;
       for (const dir of dirs) {
-        const objects = import_node_fs8.default.readdirSync(dir);
+        const objects = import_node_fs9.default.readdirSync(dir);
         for (const object of objects) {
           const content = import_node_path9.default.resolve(dir + "/" + object);
           if (content.includes("node_modules"))
             continue;
-          const isFile2 = import_node_fs8.default.statSync(content).isFile();
-          const isDir2 = import_node_fs8.default.statSync(content).isDirectory();
+          const isFile2 = import_node_fs9.default.statSync(content).isFile();
+          const isDir2 = import_node_fs9.default.statSync(content).isDirectory();
           if (isFile2 && await isValidSourceFile({ config, files, source: content })) {
             files.push(import_node_path9.default.resolve(content));
           } else if (isDir2 && config.recursive) {
@@ -134590,7 +134735,7 @@ async function parseTests({ config, files }) {
     let rawContent;
     if (extension === "json" || extension === "yaml" || extension === "yml") {
       try {
-        rawContent = await import_node_fs8.default.promises.readFile(file, "utf8");
+        rawContent = await import_node_fs9.default.promises.readFile(file, "utf8");
         if (extension === "json") {
           content = JSON.parse(rawContent);
         } else {
@@ -134976,6 +135121,7 @@ init_utils();
 // dist/core/tests.js
 var import_tree_kill = __toESM(require("tree-kill"), 1);
 init_loader();
+init_browsers();
 var import_node_os8 = __toESM(require("node:os"), 1);
 init_utils();
 var import_axios6 = __toESM(require("axios"), 1);
@@ -136236,7 +136382,7 @@ async function waitForDOMStable(driver, idleTime, timeout) {
 // dist/core/tests/runShell.js
 init_validate();
 init_utils();
-var import_node_fs9 = __toESM(require("node:fs"), 1);
+var import_node_fs10 = __toESM(require("node:fs"), 1);
 var import_node_path10 = __toESM(require("node:path"), 1);
 async function runShell({ config, step }) {
   const result = {
@@ -136311,23 +136457,23 @@ async function runShell({ config, step }) {
   }
   if (step.runShell.path) {
     const dir = import_node_path10.default.dirname(step.runShell.path);
-    if (!import_node_fs9.default.existsSync(dir)) {
-      import_node_fs9.default.mkdirSync(dir, { recursive: true });
+    if (!import_node_fs10.default.existsSync(dir)) {
+      import_node_fs10.default.mkdirSync(dir, { recursive: true });
     }
     let filePath = step.runShell.path;
     log(config, "debug", `Saving stdio to file: ${filePath}`);
-    if (!import_node_fs9.default.existsSync(filePath)) {
-      import_node_fs9.default.writeFileSync(filePath, result.outputs.stdio.stdout);
+    if (!import_node_fs10.default.existsSync(filePath)) {
+      import_node_fs10.default.writeFileSync(filePath, result.outputs.stdio.stdout);
     } else {
       if (step.runShell.overwrite == "false") {
         result.description = result.description + ` Didn't save output. File already exists.`;
       }
-      const existingFile = import_node_fs9.default.readFileSync(filePath, "utf8");
+      const existingFile = import_node_fs10.default.readFileSync(filePath, "utf8");
       const fractionalDiff = calculateFractionalDifference(existingFile, result.outputs.stdio.stdout);
       log(config, "debug", `Fractional difference: ${fractionalDiff}`);
       if (fractionalDiff > step.runShell.maxVariation) {
         if (step.runShell.overwrite == "aboveVariation") {
-          import_node_fs9.default.writeFileSync(filePath, result.outputs.stdio.stdout);
+          import_node_fs10.default.writeFileSync(filePath, result.outputs.stdio.stdout);
           result.description += ` Saved output to file.`;
         }
         result.status = "WARNING";
@@ -136335,7 +136481,7 @@ async function runShell({ config, step }) {
         return result;
       }
       if (step.runShell.overwrite == "true") {
-        import_node_fs9.default.writeFileSync(filePath, result.outputs.stdio.stdout);
+        import_node_fs10.default.writeFileSync(filePath, result.outputs.stdio.stdout);
         result.description += ` Saved output to file.`;
       }
     }
@@ -136520,7 +136666,7 @@ async function checkLink({ config, step }) {
 init_validate();
 init_utils();
 var import_node_path11 = __toESM(require("node:path"), 1);
-var import_node_fs10 = __toESM(require("node:fs"), 1);
+var import_node_fs11 = __toESM(require("node:fs"), 1);
 init_loader();
 var _pngjs = null;
 var _sharp = null;
@@ -136647,8 +136793,8 @@ async function saveScreenshot({ config, step, driver }) {
     const rawBase = import_node_path11.default.basename(urlPathname.split("?")[0].split("#")[0].replace(/\\/g, "/"));
     const safeBase = sanitizeFilesystemName(rawBase, `${step.stepId}.png`);
     dir = import_node_path11.default.join(process.cwd(), "doc-detective-runs", getOrInitRunTimestamp(config));
-    if (!import_node_fs10.default.existsSync(dir)) {
-      import_node_fs10.default.mkdirSync(dir, { recursive: true });
+    if (!import_node_fs11.default.existsSync(dir)) {
+      import_node_fs11.default.mkdirSync(dir, { recursive: true });
     }
     const captureId = `${step.stepId || "screenshot"}_${Date.now()}`;
     filePath = import_node_path11.default.join(dir, `${captureId}_${safeBase}`);
@@ -136664,10 +136810,10 @@ async function saveScreenshot({ config, step, driver }) {
     }
   } else {
     dir = import_node_path11.default.dirname(step.screenshot.path);
-    if (!import_node_fs10.default.existsSync(dir)) {
-      import_node_fs10.default.mkdirSync(dir, { recursive: true });
+    if (!import_node_fs11.default.existsSync(dir)) {
+      import_node_fs11.default.mkdirSync(dir, { recursive: true });
     }
-    if (import_node_fs10.default.existsSync(filePath)) {
+    if (import_node_fs11.default.existsSync(filePath)) {
       if (step.screenshot.overwrite == "false") {
         result.status = "SKIPPED";
         result.description = `File already exists: ${filePath}`;
@@ -136763,8 +136909,8 @@ async function saveScreenshot({ config, step, driver }) {
   } catch (error) {
     result.status = "FAIL";
     result.description = `Couldn't save screenshot. ${error}`;
-    if (existFilePath && filePath !== existFilePath && import_node_fs10.default.existsSync(filePath)) {
-      import_node_fs10.default.unlinkSync(filePath);
+    if (existFilePath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
+      import_node_fs11.default.unlinkSync(filePath);
     }
     return result;
   }
@@ -136816,12 +136962,12 @@ async function saveScreenshot({ config, step, driver }) {
         width: rect.width,
         height: rect.height
       }).toFile(croppedPath);
-      import_node_fs10.default.renameSync(croppedPath, filePath);
+      import_node_fs11.default.renameSync(croppedPath, filePath);
     } catch (error) {
       result.status = "FAIL";
       result.description = `Couldn't crop image. ${error}`;
-      if (existFilePath && filePath !== existFilePath && import_node_fs10.default.existsSync(filePath)) {
-        import_node_fs10.default.unlinkSync(filePath);
+      if (existFilePath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
+        import_node_fs11.default.unlinkSync(filePath);
       }
       return result;
     }
@@ -136829,7 +136975,7 @@ async function saveScreenshot({ config, step, driver }) {
   if (existFilePath) {
     if (step.screenshot.overwrite == "true" && !isUrlPath) {
       result.description += ` Overwrote existing file.`;
-      import_node_fs10.default.renameSync(filePath, existFilePath);
+      import_node_fs11.default.renameSync(filePath, existFilePath);
       result.outputs.screenshotPath = existFilePath;
       result.outputs.changed = true;
       if (step.screenshot.sourceIntegration) {
@@ -136842,21 +136988,21 @@ async function saveScreenshot({ config, step, driver }) {
       let img1;
       let img2;
       try {
-        img1 = PNG.sync.read(import_node_fs10.default.readFileSync(existFilePath));
-        img2 = PNG.sync.read(import_node_fs10.default.readFileSync(filePath));
+        img1 = PNG.sync.read(import_node_fs11.default.readFileSync(existFilePath));
+        img2 = PNG.sync.read(import_node_fs11.default.readFileSync(filePath));
       } catch (error) {
         result.status = "FAIL";
         result.description = isUrlPath ? `Couldn't decode PNG for comparison. The URL reference (${redactedUrl}) may not be a valid PNG. ${error}` : `Couldn't decode PNG for comparison. ${error}`;
-        if (!isUrlPath && filePath !== existFilePath && import_node_fs10.default.existsSync(filePath)) {
-          import_node_fs10.default.unlinkSync(filePath);
+        if (!isUrlPath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
+          import_node_fs11.default.unlinkSync(filePath);
         }
         return result;
       }
       if (!aspectRatiosMatch(img1, img2)) {
         result.status = "FAIL";
         result.description = `Couldn't compare images. Images have different aspect ratios.`;
-        if (!isUrlPath && filePath !== existFilePath && import_node_fs10.default.existsSync(filePath)) {
-          import_node_fs10.default.unlinkSync(filePath);
+        if (!isUrlPath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
+          import_node_fs11.default.unlinkSync(filePath);
         }
         return result;
       }
@@ -136883,8 +137029,8 @@ async function saveScreenshot({ config, step, driver }) {
       } catch (error) {
         result.status = "FAIL";
         result.description = `Couldn't load screenshot comparison dependency (pixelmatch). ${error?.message ?? error}`;
-        if (!isUrlPath && filePath !== existFilePath && import_node_fs10.default.existsSync(filePath)) {
-          import_node_fs10.default.unlinkSync(filePath);
+        if (!isUrlPath && filePath !== existFilePath && import_node_fs11.default.existsSync(filePath)) {
+          import_node_fs11.default.unlinkSync(filePath);
         }
         return result;
       }
@@ -136897,7 +137043,7 @@ async function saveScreenshot({ config, step, driver }) {
       });
       if (fractionalDiff > step.screenshot.maxVariation) {
         if (step.screenshot.overwrite == "aboveVariation" && !isUrlPath) {
-          import_node_fs10.default.renameSync(filePath, existFilePath);
+          import_node_fs11.default.renameSync(filePath, existFilePath);
         }
         result.status = "WARNING";
         result.description += ` The difference between the existing screenshot and new screenshot (${fractionalDiff.toFixed(2)}) is greater than the max accepted variation (${step.screenshot.maxVariation}).`;
@@ -136923,7 +137069,7 @@ async function saveScreenshot({ config, step, driver }) {
             result.outputs.sourceIntegration = step.screenshot.sourceIntegration;
           }
           if (step.screenshot.overwrite != "true") {
-            import_node_fs10.default.unlinkSync(filePath);
+            import_node_fs11.default.unlinkSync(filePath);
           }
         }
       }
@@ -136943,7 +137089,7 @@ async function saveScreenshot({ config, step, driver }) {
 init_validate();
 init_utils();
 var import_node_path12 = __toESM(require("node:path"), 1);
-var import_node_fs11 = __toESM(require("node:fs"), 1);
+var import_node_fs12 = __toESM(require("node:fs"), 1);
 var import_node_os6 = __toESM(require("node:os"), 1);
 async function startRecording({ config, context, step, driver }) {
   let result = {
@@ -136981,10 +137127,10 @@ async function startRecording({ config, context, step, driver }) {
   let filePath = step.record.path;
   const baseName = import_node_path12.default.basename(filePath, import_node_path12.default.extname(filePath));
   const dir = import_node_path12.default.dirname(step.record.path);
-  if (!import_node_fs11.default.existsSync(dir)) {
-    import_node_fs11.default.mkdirSync(dir, { recursive: true });
+  if (!import_node_fs12.default.existsSync(dir)) {
+    import_node_fs12.default.mkdirSync(dir, { recursive: true });
   }
-  if (import_node_fs11.default.existsSync(filePath) && step.record.overwrite == "false") {
+  if (import_node_fs12.default.existsSync(filePath) && step.record.overwrite == "false") {
     result.status = "SKIPPED";
     result.description = `File already exists: ${filePath}`;
     return result;
@@ -137108,7 +137254,7 @@ init_validate();
 init_utils();
 var import_node_child_process4 = require("node:child_process");
 var import_node_path13 = __toESM(require("node:path"), 1);
-var import_node_fs12 = __toESM(require("node:fs"), 1);
+var import_node_fs13 = __toESM(require("node:fs"), 1);
 init_loader();
 async function getFfmpegPath(ctx = {}) {
   const mod = await loadHeavyDep("@ffmpeg-installer/ffmpeg", { ctx });
@@ -137157,11 +137303,11 @@ async function stopRecording({ config, step, driver }) {
         window.recorder.stop();
       });
       let waitCount = 0;
-      while (!import_node_fs12.default.existsSync(config.recording.downloadPath) && waitCount < 60) {
+      while (!import_node_fs13.default.existsSync(config.recording.downloadPath) && waitCount < 60) {
         await new Promise((r) => setTimeout(r, 1e3));
         waitCount++;
       }
-      if (!import_node_fs12.default.existsSync(config.recording.downloadPath)) {
+      if (!import_node_fs13.default.existsSync(config.recording.downloadPath)) {
         result.status = "FAIL";
         result.description = "Recording download timed out.";
         return result;
@@ -137186,7 +137332,7 @@ async function stopRecording({ config, step, driver }) {
           if (code === 0) {
             if (targetPath !== downloadPath) {
               try {
-                import_node_fs12.default.unlinkSync(downloadPath);
+                import_node_fs13.default.unlinkSync(downloadPath);
               } catch {
               }
             }
@@ -137232,7 +137378,7 @@ async function loadVariables({ step }) {
 init_validate();
 init_utils();
 var import_node_path14 = __toESM(require("node:path"), 1);
-var import_node_fs13 = __toESM(require("node:fs"), 1);
+var import_node_fs14 = __toESM(require("node:fs"), 1);
 async function saveCookie({ config, step, driver }) {
   let result = {
     status: "PASS",
@@ -137299,14 +137445,14 @@ async function saveCookie({ config, step, driver }) {
     if (filePath) {
       const outputDirectory = directory || config.output || process.cwd();
       const fullPath = import_node_path14.default.resolve(outputDirectory, filePath);
-      if (import_node_fs13.default.existsSync(fullPath) && !(overwrite === true || overwrite === "true")) {
+      if (import_node_fs14.default.existsSync(fullPath) && !(overwrite === true || overwrite === "true")) {
         result.status = "FAIL";
         result.description = `File '${fullPath}' already exists and overwrite is not enabled.`;
         return result;
       }
       const dir = import_node_path14.default.dirname(fullPath);
-      if (!import_node_fs13.default.existsSync(dir)) {
-        import_node_fs13.default.mkdirSync(dir, { recursive: true });
+      if (!import_node_fs14.default.existsSync(dir)) {
+        import_node_fs14.default.mkdirSync(dir, { recursive: true });
       }
       if (targetCookie) {
         const netscapeCookie = formatCookieForNetscape(targetCookie);
@@ -137314,11 +137460,11 @@ async function saveCookie({ config, step, driver }) {
 # This is a cookie file saved by Doc Detective
 ${netscapeCookie}
 `;
-        import_node_fs13.default.writeFileSync(fullPath, content, "utf8");
+        import_node_fs14.default.writeFileSync(fullPath, content, "utf8");
         result.description = `Saved cookie '${cookieName}' to '${fullPath}'.`;
         log(config, "debug", `Saved cookie '${cookieName}' to file: ${fullPath}`);
       } else {
-        import_node_fs13.default.writeFileSync(fullPath, "# No cookie data\n", "utf8");
+        import_node_fs14.default.writeFileSync(fullPath, "# No cookie data\n", "utf8");
         result.description = `Created empty cookie file at '${fullPath}'.`;
         log(config, "debug", `Created empty cookie file: ${fullPath}`);
       }
@@ -137346,7 +137492,7 @@ function formatCookieForNetscape(cookie) {
 init_validate();
 init_utils();
 var import_node_path15 = __toESM(require("node:path"), 1);
-var import_node_fs14 = __toESM(require("node:fs"), 1);
+var import_node_fs15 = __toESM(require("node:fs"), 1);
 async function loadCookie({ config, step, driver }) {
   let result = {
     status: "PASS",
@@ -137402,13 +137548,13 @@ async function loadCookie({ config, step, driver }) {
     } else if (filePath) {
       const inputDirectory = directory || config.output || process.cwd();
       const fullPath = import_node_path15.default.resolve(inputDirectory, filePath);
-      if (!import_node_fs14.default.existsSync(fullPath)) {
+      if (!import_node_fs15.default.existsSync(fullPath)) {
         result.status = "FAIL";
         result.description = `Cookie file '${fullPath}' not found`;
         return result;
       }
       try {
-        const fileContent = import_node_fs14.default.readFileSync(fullPath, "utf8");
+        const fileContent = import_node_fs15.default.readFileSync(fullPath, "utf8");
         const cookies = parseNetscapeCookieFile(fileContent);
         if (cookies.length === 0) {
           result.status = "FAIL";
@@ -137574,7 +137720,7 @@ function isDomainCompatible(currentDomain, cookieDomain) {
 // dist/core/tests/httpRequest.js
 init_validate();
 var import_axios5 = __toESM(require("axios"), 1);
-var import_node_fs15 = __toESM(require("node:fs"), 1);
+var import_node_fs16 = __toESM(require("node:fs"), 1);
 var import_node_path16 = __toESM(require("node:path"), 1);
 var import_ajv2 = __toESM(require("ajv"), 1);
 init_openapi();
@@ -137881,24 +138027,24 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
   }
   if (step.httpRequest.path) {
     const dir = import_node_path16.default.dirname(step.httpRequest.path);
-    if (!import_node_fs15.default.existsSync(dir)) {
-      import_node_fs15.default.mkdirSync(dir, { recursive: true });
+    if (!import_node_fs16.default.existsSync(dir)) {
+      import_node_fs16.default.mkdirSync(dir, { recursive: true });
     }
     let filePath = step.httpRequest.path;
     log(config, "debug", `Saving output to file: ${filePath}`);
-    if (!import_node_fs15.default.existsSync(filePath)) {
-      await import_node_fs15.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
+    if (!import_node_fs16.default.existsSync(filePath)) {
+      await import_node_fs16.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
       result.description += ` Saved output to file.`;
     } else {
       if (step.httpRequest.overwrite == "false") {
         result.description += ` Didn't save output. File already exists.`;
       }
-      const existingFile = import_node_fs15.default.readFileSync(filePath, "utf8");
+      const existingFile = import_node_fs16.default.readFileSync(filePath, "utf8");
       const fractionalDiff = calculateFractionalDifference(existingFile, JSON.stringify(response.data, null, 2));
       log(config, "debug", `Fractional difference: ${fractionalDiff}`);
       if (fractionalDiff > step.httpRequest.maxVariation) {
         if (step.httpRequest.overwrite == "aboveVariation") {
-          await import_node_fs15.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
+          await import_node_fs16.default.promises.writeFile(filePath, JSON.stringify(response.data, null, 2));
           result.description += ` Saved response to file.`;
         }
         result.status = "WARNING";
@@ -137906,7 +138052,7 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
         return result;
       }
       if (step.httpRequest.overwrite == "true") {
-        import_node_fs15.default.writeFileSync(filePath, JSON.stringify(response.data, null, 2));
+        import_node_fs16.default.writeFileSync(filePath, JSON.stringify(response.data, null, 2));
         result.description += ` Saved response to file.`;
       }
     }
@@ -138083,7 +138229,7 @@ async function clickElement({ config, step, driver }) {
 // dist/core/tests/runCode.js
 init_validate();
 init_utils();
-var import_node_fs16 = __toESM(require("node:fs"), 1);
+var import_node_fs17 = __toESM(require("node:fs"), 1);
 var import_node_path17 = __toESM(require("node:path"), 1);
 var import_node_os7 = __toESM(require("node:os"), 1);
 function createTempScript(code, language) {
@@ -138107,7 +138253,7 @@ function createTempScript(code, language) {
   const tmpDir = import_node_os7.default.tmpdir();
   const tmpFile = import_node_path17.default.join(tmpDir, `doc-detective-${Date.now()}${extension}`);
   try {
-    import_node_fs16.default.writeFileSync(tmpFile, code);
+    import_node_fs17.default.writeFileSync(tmpFile, code);
   } catch (error) {
     throw new Error(`Failed to create temporary script: ${error.message}`);
   }
@@ -138191,7 +138337,7 @@ async function runCode({ config, step }) {
     result.description = error.message;
   } finally {
     try {
-      import_node_fs16.default.unlinkSync(scriptPath);
+      import_node_fs17.default.unlinkSync(scriptPath);
       log(config, "debug", `Removed temporary script: ${scriptPath}`);
     } catch (error) {
       log(config, "warn", `Failed to remove temporary script: ${scriptPath}`);
@@ -138739,6 +138885,14 @@ var driverActions2 = [
   "type"
 ];
 var KNOWN_BROWSERS = ["firefox", "chrome", "safari", "webkit"];
+function combinationKey(context) {
+  const rawName = context?.browser?.name;
+  const name = rawName === "webkit" ? "safari" : rawName || "<none>";
+  return `${context?.platform}::${name}`;
+}
+function warmUpDecision(prev) {
+  return prev === "failed" ? "skip" : "attempt";
+}
 function getDriverCapabilities({ runnerDetails, name, options }) {
   let capabilities = {};
   let args = [];
@@ -139017,8 +139171,10 @@ async function runSpecs({ resolvedTests }) {
     allowUnsafeSteps: await allowUnsafeSteps({ config })
   };
   const platform = runnerDetails.environment.platform;
-  const availableApps = runnerDetails.availableApps;
+  let availableApps = runnerDetails.availableApps;
   const metaValues = { specs: {} };
+  const installAttempts = /* @__PURE__ */ new Map();
+  const warmUpResults = /* @__PURE__ */ new Map();
   let appium;
   const report = {
     summary: {
@@ -139133,14 +139289,46 @@ async function runSpecs({ resolvedTests }) {
           testReport.contexts.push(contextReport);
           continue;
         }
-        const supportedContext = isSupportedContext({
+        let supportedContext = isSupportedContext({
           context,
           apps: availableApps,
           platform
         });
+        let freshInstallRedetected = false;
+        if (!supportedContext && context.platform === platform && // Mirror isSupportedContext's own guard: isDriverRequired iterates
+        // context.steps, so a malformed context without a steps array would
+        // otherwise crash the loop here instead of skipping cleanly.
+        Array.isArray(context?.steps) && isDriverRequired({ test: context }) && requiredBrowserAssets(context.browser?.name).length > 0) {
+          const firstAttempt = !installAttempts.has((context.browser?.name ?? "<none>").toLowerCase());
+          const outcome = await ensureContextBrowserInstalled({
+            browserName: context.browser?.name,
+            config,
+            installAttempts,
+            deps: {
+              ensureBrowser: (asset, options) => ensureBrowserInstalled(asset, options),
+              log
+            }
+          });
+          if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
+            freshInstallRedetected = true;
+            clearAppCache(config);
+            availableApps = await getAvailableApps({ config });
+            runnerDetails.availableApps = availableApps;
+            supportedContext = isSupportedContext({
+              context,
+              apps: availableApps,
+              platform
+            });
+          }
+        }
         if (!supportedContext) {
-          log(config, "info", `Skipping context. The current system doesn't support this context: {"platform": "${context.platform}", "apps": ${JSON.stringify(context.apps)}}`);
-          contextReport = { result: "SKIPPED", ...contextReport };
+          const errorMessage = freshInstallRedetected ? `Skipping context '${context.browser?.name}' on '${context.platform}': the missing browser dependency was installed but still could not be detected.` : `Skipping context. The current system doesn't support this context: {"platform": "${context.platform}", "apps": ${JSON.stringify(context.apps)}}`;
+          log(config, freshInstallRedetected ? "warning" : "info", errorMessage);
+          contextReport = {
+            ...contextReport,
+            result: "SKIPPED",
+            resultDescription: errorMessage
+          };
           report.summary.contexts.skipped++;
           testReport.contexts.push(contextReport);
           continue;
@@ -139153,6 +139341,19 @@ ${JSON.stringify(context, null, 2)}`);
         }
         const driverRequired = isDriverRequired({ test: context });
         if (driverRequired) {
+          const combo = combinationKey(context);
+          if (warmUpDecision(warmUpResults.get(combo)) === "skip") {
+            const errorMessage = `Skipping context '${context.browser?.name}' on '${context.platform}': this context combination could not start a driver earlier in this run.`;
+            log(config, "warning", errorMessage);
+            contextReport = {
+              ...contextReport,
+              result: "SKIPPED",
+              resultDescription: errorMessage
+            };
+            report.summary.contexts.skipped++;
+            testReport.contexts.push(contextReport);
+            continue;
+          }
           let caps = getDriverCapabilities({
             runnerDetails,
             name: context.browser.name,
@@ -139185,19 +139386,23 @@ ${JSON.stringify(context, null, 2)}`);
               driver = await driverStart(caps, appiumPort, 4, { cacheDir: config?.cacheDir });
             } catch (error2) {
               let errorMessage = `Failed to start context '${context.browser?.name}' on '${platform}'.`;
-              if (context.browser?.name === "safari")
+              if (context.browser?.name === "safari" || context.browser?.name === "webkit")
                 errorMessage = errorMessage + " Make sure you've run `safaridriver --enable` in a terminal and enabled 'Allow Remote Automation' in Safari's Develop menu.";
               log(config, "error", errorMessage);
+              if (!warmUpResults.has(combo))
+                warmUpResults.set(combo, "failed");
               contextReport = {
+                ...contextReport,
                 result: "SKIPPED",
-                resultDescription: errorMessage,
-                ...contextReport
+                resultDescription: errorMessage
               };
               report.summary.contexts.skipped++;
               testReport.contexts.push(contextReport);
               continue;
             }
           }
+          if (!warmUpResults.has(combo))
+            warmUpResults.set(combo, "ok");
           if (context.browser?.viewport?.width || context.browser?.viewport?.height) {
             await setViewportSize(context, driver);
           } else if (context.browser?.window?.width || context.browser?.window?.height) {
@@ -139533,6 +139738,31 @@ async function ensureChromeAvailable(config, deps) {
   }
   return availableApps;
 }
+async function ensureContextBrowserInstalled({ browserName, config, installAttempts, deps }) {
+  const key = (browserName ?? "<none>").toLowerCase();
+  const cached = installAttempts.get(key);
+  if (cached)
+    return cached;
+  const assets = requiredBrowserAssets(browserName);
+  if (assets.length === 0) {
+    installAttempts.set(key, "notInstallable");
+    return "notInstallable";
+  }
+  const ctx = { cacheDir: config?.cacheDir };
+  const logger = (msg, level = "info") => deps.log?.(config, level === "warn" ? "warning" : level, msg);
+  try {
+    deps.log?.(config, "info", `Browser '${browserName}' is not available; attempting on-demand install of: ${assets.join(", ")}.`);
+    for (const asset of assets) {
+      await deps.ensureBrowser(asset, { ctx, deps: { logger } });
+    }
+    installAttempts.set(key, "installed");
+    return "installed";
+  } catch (err) {
+    deps.log?.(config, "warning", `On-demand install for '${browserName}' failed: ${err?.message ?? err}`);
+    installAttempts.set(key, "failed");
+    return "failed";
+  }
+}
 async function getRunner(options = {}) {
   const environment = getEnvironment();
   const config = { ...options.config, environment };
@@ -139746,22 +139976,19 @@ async function runTests(config, options = {}) {
       if (needs.browsers.size > 0) {
         try {
           const { getAvailableApps: getAvailableApps2, clearAppCache: clearAppCache2 } = await Promise.resolve().then(() => (init_config(), config_exports));
-          const { ensureBrowserInstalled: ensureBrowserInstalled2 } = await Promise.resolve().then(() => (init_browsers(), browsers_exports));
+          const { ensureBrowserInstalled: ensureBrowserInstalled2, requiredBrowserAssets: requiredBrowserAssets2 } = await Promise.resolve().then(() => (init_browsers(), browsers_exports));
           const available = await getAvailableApps2({ config });
           const availableNames = new Set(available.map((a) => a.name));
           let installedAnything = false;
           for (const browser of needs.browsers) {
             if (availableNames.has(browser))
               continue;
-            if (browser === "chrome") {
-              await ensureBrowserInstalled2("chrome", { ctx, deps: { logger: preflightLogger } });
-              await ensureBrowserInstalled2("chromedriver", { ctx, deps: { logger: preflightLogger } });
-              installedAnything = true;
-            } else if (browser === "firefox") {
-              await ensureBrowserInstalled2("firefox", { ctx, deps: { logger: preflightLogger } });
-              await ensureBrowserInstalled2("geckodriver", { ctx, deps: { logger: preflightLogger } });
-              installedAnything = true;
+            const assets = requiredBrowserAssets2(browser);
+            for (const asset of assets) {
+              await ensureBrowserInstalled2(asset, { ctx, deps: { logger: preflightLogger } });
             }
+            if (assets.length > 0)
+              installedAnything = true;
           }
           if (installedAnything)
             clearAppCache2(config);