doc-detective 4.41.6 → 4.42.1

package/dist/index.cjs

@@ -518,12 +518,27 @@ function resolveManagedDepNames(pkg) {
   ]);
   return withPeerCompanions([...names]);
 }
+function packageRoot() {
+  for (let dir = __dirname; !cachedRoot; dir = import_node_path.default.dirname(dir)) {
+    try {
+      const pkg = JSON.parse(import_node_fs.default.readFileSync(import_node_path.default.join(dir, "package.json"), "utf8"));
+      if (pkg.name === "doc-detective") {
+        cachedRoot = dir;
+        cachedPkg = pkg;
+      }
+    } catch {
+    }
+    if (import_node_path.default.dirname(dir) === dir)
+      break;
+  }
+  return cachedRoot;
+}
+function ownVersion() {
+  return packageRoot() && cachedPkg.version;
+}
 function readShimPackageJson() {
-  if (cachedPkg)
-    return cachedPkg;
-  const pkgPath = import_node_path.default.resolve(__dirname, "../../package.json");
-  const raw = import_node_fs.default.readFileSync(pkgPath, "utf8");
-  cachedPkg = JSON.parse(raw);
+  if (!packageRoot())
+    throw new Error("doc-detective's package.json not found");
   return cachedPkg;
 }
 function getDeclaredVersion(name) {
@@ -583,7 +598,7 @@ function compareTuple(a, b) {
   }
   return 0;
 }
-var import_node_fs, import_node_path, import_node_url, __dirname, HEAVY_NPM_DEPS, RUNTIME_PEER_COMPANIONS, cachedPkg;
+var import_node_fs, import_node_path, import_node_url, __dirname, HEAVY_NPM_DEPS, RUNTIME_PEER_COMPANIONS, cachedRoot, cachedPkg;
 var init_heavyDeps = __esm({
   "dist/runtime/heavyDeps.js"() {
     "use strict";
@@ -675,9 +690,9 @@ function getBrowsersDir(ctx = {}) {
 }
 function legacyBrowserSnapshotCandidates() {
   const out = [import_node_path2.default.resolve("browser-snapshots")];
-  const shimRoot = import_node_path2.default.resolve(__dirname2, "..", "..");
-  const fromShim = import_node_path2.default.join(shimRoot, "browser-snapshots");
-  if (fromShim !== out[0])
+  const shimRoot = packageRoot();
+  const fromShim = shimRoot && import_node_path2.default.join(shimRoot, "browser-snapshots");
+  if (fromShim && fromShim !== out[0])
     out.push(fromShim);
   return out;
 }
@@ -734,15 +749,14 @@ function writeInstalledRecord(record, ctx = {}) {
     }
   }
 }
-var import_node_fs2, import_node_os, import_node_path2, import_node_url2, __dirname2, SHELL_METAS;
+var import_node_fs2, import_node_os, import_node_path2, SHELL_METAS;
 var init_cacheDir = __esm({
   "dist/runtime/cacheDir.js"() {
     "use strict";
     import_node_fs2 = __toESM(require("node:fs"), 1);
     import_node_os = __toESM(require("node:os"), 1);
     import_node_path2 = __toESM(require("node:path"), 1);
-    import_node_url2 = require("node:url");
-    __dirname2 = import_node_path2.default.dirname((0, import_node_url2.fileURLToPath)(importMetaUrl));
+    init_heavyDeps();
     SHELL_METAS = /[;&|`$<>"'\n\r%^!]/;
   }
 });
@@ -810,7 +824,7 @@ function tryResolveFromCache(name, ctx = {}) {
     const pkgJsonAnchor = import_node_path3.default.join(runtimeDir, "package.json");
     if (!import_node_fs3.default.existsSync(pkgJsonAnchor))
       return null;
-    const requireFromCache = (0, import_node_module.createRequire)((0, import_node_url3.pathToFileURL)(pkgJsonAnchor).href);
+    const requireFromCache = (0, import_node_module.createRequire)((0, import_node_url2.pathToFileURL)(pkgJsonAnchor).href);
     return resolveEntry(requireFromCache, name);
   } catch (err) {
     const detail = err instanceof Error ? err.stack ?? `${err.name}: ${err.message}` : (0, import_node_util.inspect)(err);
@@ -870,7 +884,7 @@ async function loadHeavyDep(name, options = {}) {
       throw new Error(`Failed to resolve heavy dep '${name}' even after install. Inspect <cacheDir>/runtime/node_modules/${name}.`);
     }
   }
-  return await import((0, import_node_url3.pathToFileURL)(resolved).href);
+  return await import((0, import_node_url2.pathToFileURL)(resolved).href);
 }
 function heavyDepPrefetchTarget(name, ctx = {}) {
   const entry = resolveHeavyDepPath(name, ctx);
@@ -883,7 +897,7 @@ function prefetchHeavyDep(name, ctx = {}) {
   try {
     const target = heavyDepPrefetchTarget(name, ctx);
     if (target)
-      import((0, import_node_url3.pathToFileURL)(target).href).catch(() => {
+      import((0, import_node_url2.pathToFileURL)(target).href).catch(() => {
       });
   } catch {
   }
@@ -1099,14 +1113,14 @@ async function ensureRuntimeInstalled(packages, options = {}) {
   }
   recordRuntimeDependencies(runtimeDir, ctx);
 }
-var import_node_path3, import_node_fs3, import_node_child_process, import_node_url3, import_node_module, import_node_util, RUNTIME_DEBUG, defaultLogger, requireFromShim, PREFETCH_SIBLING, DEFAULT_INSTALL_TIMEOUT_MS, RUNTIME_PACKAGE_JSON_CONTENTS;
+var import_node_path3, import_node_fs3, import_node_child_process, import_node_url2, import_node_module, import_node_util, RUNTIME_DEBUG, defaultLogger, requireFromShim, PREFETCH_SIBLING, DEFAULT_INSTALL_TIMEOUT_MS, RUNTIME_PACKAGE_JSON_CONTENTS;
 var init_loader = __esm({
   "dist/runtime/loader.js"() {
     "use strict";
     import_node_path3 = __toESM(require("node:path"), 1);
     import_node_fs3 = __toESM(require("node:fs"), 1);
     import_node_child_process = require("node:child_process");
-    import_node_url3 = require("node:url");
+    import_node_url2 = require("node:url");
     import_node_module = require("node:module");
     import_node_util = require("node:util");
     init_heavyDeps();
@@ -1532,8 +1546,8 @@ var init_windowsBash = __esm({
 
 // dist/core/ptyWatchdog.js
 function defaultCreateWorker(data) {
-  const url = new URL("./ptyProbeWorker.js", importMetaUrl);
-  return new import_node_worker_threads.Worker(url, { workerData: data });
+  const worker = import_node_path5.default.join(packageRoot(), "dist", "core", "ptyProbeWorker.js");
+  return new import_node_worker_threads.Worker(worker, { workerData: data });
 }
 function probePtyAllocation(opts) {
   const timeoutMs = opts.timeoutMs ?? PTY_PROBE_TIMEOUT_MS;
@@ -1615,12 +1629,14 @@ async function assertConptyAllocatable(opts) {
     throw err;
   }
 }
-var import_node_fs6, import_node_worker_threads, PTY_PROBE_TIMEOUT_MS;
+var import_node_fs6, import_node_path5, import_node_worker_threads, PTY_PROBE_TIMEOUT_MS;
 var init_ptyWatchdog = __esm({
   "dist/core/ptyWatchdog.js"() {
     "use strict";
     import_node_fs6 = __toESM(require("node:fs"), 1);
+    import_node_path5 = __toESM(require("node:path"), 1);
     import_node_worker_threads = require("node:worker_threads");
+    init_heavyDeps();
     PTY_PROBE_TIMEOUT_MS = Number(process.env.DOC_DETECTIVE_PTY_PROBE_TIMEOUT_MS) || 15e3;
   }
 });
@@ -2388,6 +2404,24 @@ var init_verification = __esm({
 function loadAxios() {
   return axiosModule ??= import("axios").then((m) => m.default);
 }
+function sessionVersions({ capabilities, app }) {
+  const result = {};
+  const str = (value) => typeof value === "string" && value ? value : void 0;
+  const caps = capabilities ?? {};
+  const browserVersion = str(caps.browserVersion) ?? str(app?.version)?.replace(/^[a-z]+_/, "");
+  if (browserVersion)
+    result.browserVersion = browserVersion;
+  const chromedriver = str(caps.chrome?.chromedriverVersion);
+  if (chromedriver) {
+    result.driver = { name: "chromedriver", version: chromedriver.split(" ")[0] };
+  } else if (app?.name === "firefox") {
+    const version = str(caps["moz:geckodriverVersion"]) ?? /geckodriver-(\d+(?:\.\d+)*)/i.exec(import_node_path6.default.basename(str(app.driver) ?? ""))?.[1];
+    result.driver = { name: "geckodriver", ...version && { version } };
+  } else if (app?.name === "safari") {
+    result.driver = { name: "safaridriver" };
+  }
+  return result;
+}
 function createAppiumPool(ports) {
   const available = [...ports];
   const waiters = [];
@@ -2603,11 +2637,9 @@ async function spawnPtyBackgroundCommand(cmd, args = [], options = {}) {
   try {
     ptyProcess = pty.spawn(shell, shellArgs, {
       name: "xterm-color",
-      // TODO(phase): expose as `background.tty.cols` / `background.tty.rows` so
-      // layout-sensitive TUIs (Ink reads process.stdout.columns) can match an
-      // expected width when authoring `waitUntil.stdio` patterns.
-      cols: 120,
-      rows: 30,
+      // `tty: {cols, rows}`; Ajv skips defaults inside the schema's anyOf.
+      cols: options.cols ?? 120,
+      rows: options.rows ?? 30,
       cwd: options.cwd || process.cwd(),
       env: shellSpawnEnv(options.shell) ?? process.env
     });
@@ -2969,13 +3001,13 @@ function appendQueryParams(url, params) {
   return pathAndAuthority + (query ? "?" + query : "") + fragment;
 }
 function cleanTemp() {
-  const tempDir = import_node_path5.default.join(import_node_os2.default.tmpdir(), "doc-detective");
+  const tempDir = import_node_path6.default.join(import_node_os2.default.tmpdir(), "doc-detective");
   if (!import_node_fs7.default.existsSync(tempDir))
     return;
   for (const entry of import_node_fs7.default.readdirSync(tempDir)) {
     if (PRESERVED_TEMP_ENTRIES.has(entry))
       continue;
-    const curPath = import_node_path5.default.join(tempDir, entry);
+    const curPath = import_node_path6.default.join(tempDir, entry);
     try {
       const stat = import_node_fs7.default.statSync(curPath);
       if (stat.isDirectory()) {
@@ -3003,7 +3035,7 @@ function safeFilenameFromUrl(fileURL, fallback) {
     raw = fileURL;
   }
   raw = raw.split("?")[0].split("#")[0];
-  const base = import_node_path5.default.basename(raw.replace(/\\/g, "/"));
+  const base = import_node_path6.default.basename(raw.replace(/\\/g, "/"));
   return sanitizeFilesystemName(base, fallback);
 }
 function redactUrlForOutput(value) {
@@ -3041,36 +3073,56 @@ function isPrivateOrLoopbackAddress(ip) {
     return false;
   }
   if (import_node_net.default.isIPv6(ip)) {
-    const normalized = ip.toLowerCase();
-    if (normalized === "::1")
-      return true;
-    if (normalized === "::")
+    const g = ipv6Groups(ip);
+    const zero = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const v4 = `${g[6] >> 8}.${g[6] & 255}.${g[7] >> 8}.${g[7] & 255}`;
+    if ((g[0] & 65024) === 64512)
       return true;
-    if (normalized.startsWith("fc") || normalized.startsWith("fd"))
+    if ((g[0] & 65472) === 65152)
       return true;
-    if (normalized.startsWith("fe80:"))
+    if ((g[0] & 65472) === 65216)
       return true;
-    if (normalized.startsWith("::ffff:")) {
-      const tail = normalized.slice("::ffff:".length);
-      if (import_node_net.default.isIPv4(tail)) {
-        return isPrivateOrLoopbackAddress(tail);
-      }
-      const hexMatch = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-      if (hexMatch) {
-        const hi = parseInt(hexMatch[1], 16);
-        const lo = parseInt(hexMatch[2], 16);
-        const dotted = `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
-        return isPrivateOrLoopbackAddress(dotted);
-      }
-      return false;
+    if (g[0] === 8194) {
+      return isPrivateOrLoopbackAddress(`${g[1] >> 8}.${g[1] & 255}.${g[2] >> 8}.${g[2] & 255}`);
+    }
+    if (zero(0, 4) && g[4] === 65535 && g[5] === 0)
+      return isPrivateOrLoopbackAddress(v4);
+    if (zero(0, 6))
+      return isPrivateOrLoopbackAddress(v4);
+    if (zero(0, 5) && g[5] === 65535)
+      return isPrivateOrLoopbackAddress(v4);
+    if (g[0] === 100 && g[1] === 65435 && zero(2, 6)) {
+      return isPrivateOrLoopbackAddress(v4);
     }
     return false;
   }
   return false;
 }
-async function assertUrlHostIsPublic(fileURL) {
-  if (process.env.DOC_DETECTIVE_ALLOW_LOCAL_URLS === "true")
-    return;
+function ipv6Groups(ip) {
+  let text = ip.toLowerCase().split("%")[0];
+  const dotted = text.match(/(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (dotted) {
+    const [a, b, c, d] = dotted.slice(1).map(Number);
+    text = text.slice(0, dotted.index) + `${(a << 8 | b).toString(16)}:${(c << 8 | d).toString(16)}`;
+  }
+  const [head, tail] = text.split("::");
+  const left = head ? head.split(":") : [];
+  const right = tail ? tail.split(":") : [];
+  const groups = tail === void 0 ? left : [...left, ...Array(8 - left.length - right.length).fill("0"), ...right];
+  return groups.map((group) => parseInt(group, 16));
+}
+function envFlag(name) {
+  return /^(1|true|yes|on)$/i.test((process.env[name] ?? "").trim());
+}
+function localUrlPolicy() {
+  const allow = envFlag("DOC_DETECTIVE_ALLOW_LOCAL_URLS");
+  const block = envFlag("DOC_DETECTIVE_BLOCK_LOCAL_URLS");
+  if (allow && block) {
+    throw new UrlGuardError("DOC_DETECTIVE_ALLOW_LOCAL_URLS and DOC_DETECTIVE_BLOCK_LOCAL_URLS can't both be set.");
+  }
+  return allow ? "allow" : block ? "block" : "hops";
+}
+async function privateAddressOf(fileURL, { every = false } = {}) {
   let parsed;
   try {
     parsed = new URL(fileURL);
@@ -3082,33 +3134,117 @@ async function assertUrlHostIsPublic(fileURL) {
   }
   const host = parsed.hostname.replace(/^\[|\]$/g, "");
   if (import_node_net.default.isIP(host)) {
-    if (isPrivateOrLoopbackAddress(host)) {
-      throw new Error(`Refusing to fetch private/loopback address (${host}). Set DOC_DETECTIVE_ALLOW_LOCAL_URLS=true to allow.`);
-    }
-    return;
+    return isPrivateOrLoopbackAddress(host) ? host : void 0;
   }
   const lower = host.toLowerCase();
   if (lower === "localhost" || lower.endsWith(".localhost")) {
-    throw new Error(`Refusing to fetch localhost (${host}). Set DOC_DETECTIVE_ALLOW_LOCAL_URLS=true to allow.`);
+    return host;
   }
   let addresses;
   try {
     addresses = await import_promises.default.lookup(host, { all: true });
   } catch (error) {
-    throw new Error(`Couldn't resolve host ${host} for SSRF check: ${error.message}`);
+    throw Object.assign(new Error(`Couldn't resolve host ${host}: ${error.message}`), { host, code: error.code ?? error.message });
   }
-  for (const { address } of addresses) {
-    if (isPrivateOrLoopbackAddress(address)) {
-      throw new Error(`Host ${host} resolves to a private/loopback address (${address}); refusing to fetch. Set DOC_DETECTIVE_ALLOW_LOCAL_URLS=true to allow.`);
-    }
+  const privates = addresses.filter(({ address }) => isPrivateOrLoopbackAddress(address));
+  const isPrivate = every ? privates.length === addresses.length : privates.length > 0;
+  return isPrivate ? privates[0]?.address : void 0;
+}
+function strictModeError(url) {
+  return new UrlGuardError(`Couldn't fetch ${redactUrlForOutput(url)}: DOC_DETECTIVE_BLOCK_LOCAL_URLS refuses private and loopback addresses.
+Hint: Unset DOC_DETECTIVE_BLOCK_LOCAL_URLS to allow local URLs.`);
+}
+function redirectError(from, address) {
+  return new UrlGuardError(`Couldn't follow the redirect from ${redactUrlForOutput(from)}: it leads to ${address}, a private address, from a public one.
+Hint: If you trust this redirect, set DOC_DETECTIVE_ALLOW_LOCAL_URLS=1.`);
+}
+function hostKey(hostname) {
+  return hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+}
+function proxyConfigured() {
+  return ["http_proxy", "https_proxy", "all_proxy"].some((key) => process.env[key] || process.env[key.toUpperCase()]);
+}
+async function getGuarded(url, opts = FETCH_BINARY_DEFAULTS, refuseFirst, refuseRedirect = redirectError) {
+  const policy = localUrlPolicy();
+  const axios = await loadAxios();
+  const [{ default: http3 }, { default: https4 }] = await Promise.all([
+    import("node:http"),
+    import("node:https")
+  ]);
+  let current = url;
+  let refuse = policy === "hops" ? refuseFirst : void 0;
+  let reachedPublic = false;
+  for (let hops = 0; ; hops++) {
+    if (policy === "block") {
+      if (await privateAddressOf(current))
+        throw strictModeError(current);
+      const hopUrl = current;
+      refuse = () => strictModeError(hopUrl);
+    }
+    const seen = {};
+    const refuseAtConnect = refuse;
+    const target = hostKey(new URL(current).hostname);
+    const lookup = (hostname, options, callback) => {
+      if (proxyConfigured() && hostKey(hostname) !== target) {
+        return import_node_dns.default.lookup(hostname, options, callback);
+      }
+      return import_node_dns.default.lookup(hostname, options, (error, address, family) => {
+        if (error)
+          return callback(error, address, family);
+        const answers = Array.isArray(address) ? address : [{ address }];
+        seen.resolved = true;
+        seen.private = answers.find((a) => isPrivateOrLoopbackAddress(a.address))?.address;
+        seen.public = answers.some((a) => !isPrivateOrLoopbackAddress(a.address));
+        if (seen.private && refuseAtConnect)
+          return callback(refuseAtConnect(seen.private));
+        callback(null, address, family);
+      });
+    };
+    const response = await axios.get(current, {
+      ...opts,
+      maxRedirects: 0,
+      httpAgent: new http3.Agent({ lookup }),
+      httpsAgent: new https4.Agent({ lookup }),
+      validateStatus: (status) => status >= 200 && status < 300 || REDIRECT_STATUSES.includes(status)
+    }).catch((error) => {
+      throw error?.cause instanceof UrlGuardError ? error.cause : error;
+    });
+    let hopPublic = seen.resolved ? seen.public : import_node_net.default.isIP(target) ? !isPrivateOrLoopbackAddress(target) : void 0;
+    let fresh;
+    const freshPublic = () => fresh ??= privateAddressOf(current, { every: true }).then((a) => !a, () => true);
+    if (hopPublic === void 0 && policy !== "allow")
+      hopPublic = await freshPublic();
+    if (hopPublic)
+      reachedPublic = true;
+    if (!REDIRECT_STATUSES.includes(response.status)) {
+      return { data: response.data, url: current, reachedPublic };
+    }
+    const location = response.headers?.location;
+    if (!location || hops >= 5) {
+      throw new UrlGuardError(`Couldn't fetch ${redactUrlForOutput(url)}: ${hops >= 5 ? "it needs more than 5 redirects" : `the ${response.status} redirect has no Location header`}.`);
+    }
+    const next = new URL(location, current).toString();
+    const scheme = new URL(next).protocol;
+    if (scheme !== "http:" && scheme !== "https:") {
+      throw new UrlGuardError(`Couldn't fetch ${redactUrlForOutput(current)}: the redirect leads to an unsupported scheme (\`${scheme.slice(0, -1)}\`).`);
+    }
+    if (policy === "hops") {
+      const fromPublic = hopPublic || await freshPublic();
+      refuse = void 0;
+      if (fromPublic) {
+        const address = await privateAddressOf(next);
+        if (address)
+          throw refuseRedirect(current, address);
+        const from = current;
+        refuse = (connectAddress) => refuseRedirect(from, connectAddress);
+      }
+    }
+    current = next;
   }
 }
 async function fetchFile(fileURL, opts = {}) {
   try {
-    if (opts.binary) {
-      await assertUrlHostIsPublic(fileURL);
-    }
-    const response = await (await loadAxios()).get(fileURL, opts.binary ? FETCH_BINARY_DEFAULTS : void 0);
+    const response = opts.binary ? await getGuarded(fileURL) : await (await loadAxios()).get(fileURL);
     let data;
     if (opts.binary) {
       data = Buffer.from(response.data);
@@ -3119,11 +3255,11 @@ async function fetchFile(fileURL, opts = {}) {
     }
     const fileName = safeFilenameFromUrl(fileURL, "fetched_file");
     const hash = import_node_crypto3.default.createHash("md5").update(data).digest("hex");
-    const ddTempDir = import_node_path5.default.join(import_node_os2.default.tmpdir(), "doc-detective");
-    const filePath = import_node_path5.default.join(ddTempDir, `${hash}_${fileName}`);
-    const resolvedDir = import_node_path5.default.resolve(ddTempDir);
-    const resolvedFile = import_node_path5.default.resolve(filePath);
-    if (!resolvedFile.startsWith(resolvedDir + import_node_path5.default.sep)) {
+    const ddTempDir = import_node_path6.default.join(import_node_os2.default.tmpdir(), "doc-detective");
+    const filePath = import_node_path6.default.join(ddTempDir, `${hash}_${fileName}`);
+    const resolvedDir = import_node_path6.default.resolve(ddTempDir);
+    const resolvedFile = import_node_path6.default.resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedDir + import_node_path6.default.sep)) {
       return {
         result: "error",
         message: new Error(`Refusing to write outside temp dir: ${resolvedFile}`)
@@ -3302,10 +3438,10 @@ function expandRequirementPath(entry, env) {
 function commandOnPath(command, env, existsSync) {
   const hasSeparator = command.includes("/") || command.includes("\\");
   const pathValue = env.PATH ?? env.Path ?? "";
-  const directories = hasSeparator ? [""] : pathValue.split(import_node_path5.default.delimiter).filter(Boolean);
+  const directories = hasSeparator ? [""] : pathValue.split(import_node_path6.default.delimiter).filter(Boolean);
   const extensions = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
   for (const directory of directories) {
-    const base = hasSeparator ? command : import_node_path5.default.join(directory, command);
+    const base = hasSeparator ? command : import_node_path6.default.join(directory, command);
     for (const extension of extensions) {
       if (existsSync(base + extension))
         return true;
@@ -3396,7 +3532,7 @@ function shieldsBadge(format, date, { label = "Last verified", color = "brightgr
 }
 function writeFileAtomic(file, content) {
   const target = import_node_fs7.default.realpathSync(file);
-  const tmp = import_node_path5.default.join(import_node_path5.default.dirname(target), `.${import_node_path5.default.basename(target)}.${import_node_crypto3.default.randomBytes(6).toString("hex")}.tmp`);
+  const tmp = import_node_path6.default.join(import_node_path6.default.dirname(target), `.${import_node_path6.default.basename(target)}.${import_node_crypto3.default.randomBytes(6).toString("hex")}.tmp`);
   const fd = import_node_fs7.default.openSync(tmp, "wx", 384);
   let keepTmp = false;
   try {
@@ -3462,7 +3598,7 @@ function applyVerifiedMarkers({ config, results, files: detectedFiles = [], init
     }
   }
   const today = verifiedDate();
-  const version = (0, import_node_module3.createRequire)(importMetaUrl)("../../package.json").version;
+  const version = ownVersion() ?? "unknown";
   for (const file of files) {
     try {
       if (!import_node_fs7.default.existsSync(file))
@@ -3481,7 +3617,7 @@ function applyVerifiedMarkers({ config, results, files: detectedFiles = [], init
         version,
         resolve: (check) => resolveVerifiedId(results, check),
         onUnknown: (check) => log(config, "warning", `verified-by check '${check}' in ${file} matches no test or spec; skipping.`),
-        onSkipped: (line, reason) => log(config, "warning", `Skipping the meta statement at ${file}:${line}: ${reason}.`)
+        onSkipped: (line, reason2) => log(config, "warning", `Skipping the meta statement at ${file}:${line}: ${reason2}.`)
       });
       if (content !== original)
         writeFileAtomic(file, content);
@@ -3641,11 +3777,11 @@ function getRunOutputDir(config, { create = true } = {}) {
   let base = String(config?.output || ".");
   const reportFileExtensions = [".json", ".html", ".htm", ".xml", ".md"];
   if (reportFileExtensions.some((ext) => base.toLowerCase().endsWith(ext))) {
-    base = import_node_path5.default.dirname(base);
+    base = import_node_path6.default.dirname(base);
   }
-  const runsRoot = import_node_path5.default.resolve(base, ".doc-detective", "runs");
+  const runsRoot = import_node_path6.default.resolve(base, ".doc-detective", "runs");
   const runId = getOrInitRunTimestamp(config);
-  let dir = import_node_path5.default.join(runsRoot, runId);
+  let dir = import_node_path6.default.join(runsRoot, runId);
   if (create) {
     import_node_fs7.default.mkdirSync(runsRoot, { recursive: true });
     let suffix = 2;
@@ -3656,7 +3792,7 @@ function getRunOutputDir(config, { create = true } = {}) {
       } catch (error) {
         if (error?.code !== "EEXIST")
           throw error;
-        dir = import_node_path5.default.join(runsRoot, `${runId}-${suffix++}`);
+        dir = import_node_path6.default.join(runsRoot, `${runId}-${suffix++}`);
       }
     }
   }
@@ -3733,15 +3869,15 @@ function shellSpawnEnv(shellExecutable, deps = {}) {
     return void 0;
   if (!/bash(\.exe)?$/i.test(shellExecutable))
     return void 0;
-  const dir = import_node_path5.default.win32.dirname(shellExecutable);
-  if (!import_node_path5.default.win32.isAbsolute(dir))
+  const dir = import_node_path6.default.win32.dirname(shellExecutable);
+  if (!import_node_path6.default.win32.isAbsolute(dir))
     return void 0;
   const pathKey = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "Path";
   const existing = env[pathKey];
   return {
     ...env,
     // No trailing delimiter (an empty PATH segment) when PATH was unset.
-    [pathKey]: existing ? `${dir}${import_node_path5.default.win32.delimiter}${existing}` : dir
+    [pathKey]: existing ? `${dir}${import_node_path6.default.win32.delimiter}${existing}` : dir
   };
 }
 async function spawnCommand(cmd, args = [], options = {}) {
@@ -3842,22 +3978,30 @@ function llevenshteinDistance(s, t) {
   }
   return arr[t.length][s.length];
 }
-var import_node_fs7, import_node_os2, import_node_path5, import_node_crypto3, import_promises, import_node_net, import_node_child_process4, import_node_module3, axiosModule, BACKGROUND_BUFFER_LIMIT, PTY_PACKAGE, READY_POLL_INTERVAL_MS, TRANSIENT_SESSION_ERROR, SESSION_TIMEOUT_ABORT, BROWSER_ERROR_PAGE, INITIAL_BLANK_DOCUMENT, TRANSIENT_PROCESS_INIT_EXIT_CODES, SETTLE_CEILING_MAX_MS, PRESERVED_TEMP_ENTRIES, FETCH_BINARY_DEFAULTS, VIEWPORT_TOLERANCE_PX, VIEWPORT_SETTLE_MS, DEFAULT_VIEWPORT, ENV_VAR_REGEX, VERIFIED_FORMAT_BY_EXT, VERIFIED_IMG_BODY, posixBashProbe;
+var import_node_fs7, import_node_os2, import_node_path6, import_node_crypto3, import_promises, import_node_dns, import_node_net, import_node_child_process4, axiosModule, FETCH_BINARY_DEFAULTS, FETCH_TEXT_DEFAULTS, BACKGROUND_BUFFER_LIMIT, PTY_PACKAGE, READY_POLL_INTERVAL_MS, TRANSIENT_SESSION_ERROR, SESSION_TIMEOUT_ABORT, BROWSER_ERROR_PAGE, INITIAL_BLANK_DOCUMENT, TRANSIENT_PROCESS_INIT_EXIT_CODES, SETTLE_CEILING_MAX_MS, PRESERVED_TEMP_ENTRIES, UrlGuardError, REDIRECT_STATUSES, VIEWPORT_TOLERANCE_PX, VIEWPORT_SETTLE_MS, DEFAULT_VIEWPORT, ENV_VAR_REGEX, VERIFIED_FORMAT_BY_EXT, VERIFIED_IMG_BODY, posixBashProbe;
 var init_utils = __esm({
   "dist/core/utils.js"() {
     "use strict";
     import_node_fs7 = __toESM(require("node:fs"), 1);
     import_node_os2 = __toESM(require("node:os"), 1);
-    import_node_path5 = __toESM(require("node:path"), 1);
+    import_node_path6 = __toESM(require("node:path"), 1);
     import_node_crypto3 = __toESM(require("node:crypto"), 1);
     import_promises = __toESM(require("node:dns/promises"), 1);
+    import_node_dns = __toESM(require("node:dns"), 1);
     import_node_net = __toESM(require("node:net"), 1);
     import_node_child_process4 = require("node:child_process");
     init_loader();
     init_windowsBash();
+    init_heavyDeps();
     init_ptyWatchdog();
-    import_node_module3 = require("node:module");
     init_verification();
+    FETCH_BINARY_DEFAULTS = {
+      responseType: "arraybuffer",
+      timeout: 3e4,
+      maxContentLength: 50 * 1024 * 1024,
+      maxBodyLength: 50 * 1024 * 1024
+    };
+    FETCH_TEXT_DEFAULTS = { ...FETCH_BINARY_DEFAULTS, responseType: "text" };
     BACKGROUND_BUFFER_LIMIT = 256 * 1024;
     PTY_PACKAGE = "@homebridge/node-pty-prebuilt-multiarch";
     READY_POLL_INTERVAL_MS = 500;
@@ -3884,13 +4028,9 @@ var init_utils = __esm({
       "jre",
       "ios"
     ]);
-    FETCH_BINARY_DEFAULTS = {
-      responseType: "arraybuffer",
-      timeout: 3e4,
-      maxContentLength: 50 * 1024 * 1024,
-      maxBodyLength: 50 * 1024 * 1024,
-      maxRedirects: 5
+    UrlGuardError = class extends Error {
     };
+    REDIRECT_STATUSES = [301, 302, 303, 307, 308];
     VIEWPORT_TOLERANCE_PX = 16;
     VIEWPORT_SETTLE_MS = 2e3;
     DEFAULT_VIEWPORT = { width: 1200, height: 800 };
@@ -3932,7 +4072,7 @@ __export(browsers_exports, {
   verifyDriverBinary: () => verifyDriverBinary
 });
 function isAllowedDriverPath(binaryPath) {
-  return typeof binaryPath === "string" && import_node_path6.default.isAbsolute(binaryPath) && ALLOWED_DRIVER_PATH.test(binaryPath);
+  return typeof binaryPath === "string" && import_node_path7.default.isAbsolute(binaryPath) && ALLOWED_DRIVER_PATH.test(binaryPath);
 }
 function parseDriverVersion(output) {
   const m = output.match(/(\d+\.\d+(?:\.\d+)*)/);
@@ -4104,12 +4244,12 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
   }
   if (!force && existing && isStillFresh(existing.latestCheckedAt, now)) {
     if (existing.latestKnownVersion === existing.installedVersion) {
-      const path33 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
-      return { path: path33, version: existing.installedVersion, outdated: false };
+      const path34 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+      return { path: path34, version: existing.installedVersion, outdated: false };
     }
-    const path32 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+    const path33 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
     logger(`${name} ${existing.installedVersion} installed in ${cacheDir}; "${BROWSER_CHANNELS[name]}" channel is now ${existing.latestKnownVersion}. Run \`doc-detective install browsers ${name} --force\` to update.`, "warn");
-    return { path: path32, version: existing.installedVersion, outdated: true };
+    return { path: path33, version: existing.installedVersion, outdated: true };
   }
   let latest;
   try {
@@ -4117,8 +4257,8 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
   } catch (err) {
     logger(`Channel resolution for ${name} skipped: ${String(err)}`, "debug");
     if (existing) {
-      const path32 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
-      return { path: path32, version: existing.installedVersion, outdated: false };
+      const path33 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+      return { path: path33, version: existing.installedVersion, outdated: false };
     }
     throw err;
   }
@@ -4129,8 +4269,8 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
       latestCheckedAt: now.toISOString()
     };
     writeInstalledRecord(record, ctx);
-    const path32 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
-    return { path: path32, version: latest, outdated: false };
+    const path33 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
+    return { path: path33, version: latest, outdated: false };
   }
   if (!force && existing) {
     record.browsers[name] = {
@@ -4140,8 +4280,8 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
     };
     writeInstalledRecord(record, ctx);
     logger(`${name} ${existing.installedVersion} installed in ${cacheDir}; "${BROWSER_CHANNELS[name]}" channel is now ${latest}. Run \`doc-detective install browsers ${name} --force\` to update.`, "warn");
-    const path32 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
-    return { path: path32, version: existing.installedVersion, outdated: true };
+    const path33 = await locateExecutable(browsersModule, name, existing.installedVersion, cacheDir, platform);
+    return { path: path33, version: existing.installedVersion, outdated: true };
   }
   logger(`Installing ${name} ${latest} into ${cacheDir}`, "info");
   await browsersModule.install({
@@ -4149,9 +4289,9 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
     buildId: latest,
     cacheDir
   });
-  let path31 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
-  if (name === "chromedriver" && isAllowedDriverPath(path31)) {
-    let verify = await verifyDriverBinary(name, path31, { exec: deps.verifyExec });
+  let path32 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
+  if (name === "chromedriver" && isAllowedDriverPath(path32)) {
+    let verify = await verifyDriverBinary(name, path32, { exec: deps.verifyExec });
     if (!verify.ok) {
       logger(`Installed ${name} ${latest} failed validation (${verify.error}); reinstalling once.`, "warn");
       try {
@@ -4160,11 +4300,11 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
         logger(`Failed to prune broken ${name} ${latest}: ${String(err)}`, "debug");
       }
       await browsersModule.install({ browser: name, buildId: latest, cacheDir });
-      path31 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
-      verify = await verifyDriverBinary(name, path31, { exec: deps.verifyExec });
+      path32 = await locateExecutable(browsersModule, name, latest, cacheDir, platform);
+      verify = await verifyDriverBinary(name, path32, { exec: deps.verifyExec });
     }
     if (!verify.ok) {
-      throw new Error(`${name} ${latest} is present but non-functional after a reinstall (${verify.error}). It may be a partial or corrupt download; delete ${path31} or reinstall.`);
+      throw new Error(`${name} ${latest} is present but non-functional after a reinstall (${verify.error}). It may be a partial or corrupt download; delete ${path32} or reinstall.`);
     }
   }
   if (existing && existing.installedVersion !== latest) {
@@ -4185,7 +4325,7 @@ async function ensureBrowserInstalledImpl(name, options = {}) {
     latestCheckedAt: now.toISOString()
   };
   writeInstalledRecord(record, ctx);
-  return { path: path31, version: latest, outdated: false };
+  return { path: path32, version: latest, outdated: false };
 }
 async function locateExecutable(browsersModule, name, buildId, cacheDir, platform) {
   if (typeof browsersModule.computeExecutablePath === "function") {
@@ -4218,9 +4358,9 @@ async function withGeckodriverCacheDir(cacheDir, fn) {
   }
 }
 function isPathInside(child, dir) {
-  const resolvedDir = import_node_path6.default.resolve(dir);
-  const resolvedChild = import_node_path6.default.resolve(child);
-  return resolvedChild === resolvedDir || resolvedChild.startsWith(resolvedDir + import_node_path6.default.sep);
+  const resolvedDir = import_node_path7.default.resolve(dir);
+  const resolvedChild = import_node_path7.default.resolve(child);
+  return resolvedChild === resolvedDir || resolvedChild.startsWith(resolvedDir + import_node_path7.default.sep);
 }
 function compareGeckodriverVersionsDesc(a, b) {
   const pa = a.split(".");
@@ -4239,7 +4379,7 @@ function isRegularFileEntry(dir, entry) {
   if (!entry.isSymbolicLink())
     return false;
   try {
-    return import_node_fs8.default.statSync(import_node_path6.default.join(dir, entry.name)).isFile();
+    return import_node_fs8.default.statSync(import_node_path7.default.join(dir, entry.name)).isFile();
   } catch {
     return false;
   }
@@ -4253,7 +4393,7 @@ function readDirEntries(dir) {
 }
 function bareBinaryIn(dir, binName, entries) {
   const match = entries.find((entry) => entry.name === binName && isRegularFileEntry(dir, entry));
-  return match ? import_node_path6.default.join(dir, binName) : void 0;
+  return match ? import_node_path7.default.join(dir, binName) : void 0;
 }
 function newestVersionedIn(dir, entries) {
   const wantExe = process.platform === "win32";
@@ -4267,7 +4407,7 @@ function newestVersionedIn(dir, entries) {
     if (wantExe !== Boolean(match[2]))
       continue;
     if (!best || compareGeckodriverVersionsDesc(match[1], best.version) < 0) {
-      best = { version: match[1], file: import_node_path6.default.join(dir, entry.name) };
+      best = { version: match[1], file: import_node_path7.default.join(dir, entry.name) };
     }
   }
   return best;
@@ -4280,7 +4420,7 @@ function geckodriverBinaryInCache(cacheDir) {
   for (const entry of rootEntries) {
     if (!entry.isDirectory())
       continue;
-    const dir = import_node_path6.default.join(cacheDir, entry.name);
+    const dir = import_node_path7.default.join(cacheDir, entry.name);
     const nestedEntries = readDirEntries(dir);
     const nestedVersioned = newestVersionedIn(dir, nestedEntries);
     if (nestedVersioned && (!bestVersioned || compareGeckodriverVersionsDesc(nestedVersioned.version, bestVersioned.version) < 0)) {
@@ -4360,14 +4500,14 @@ function getInstalledBrowsers(ctx = {}) {
     latestKnownVersion: entry.latestKnownVersion
   }));
 }
-var import_node_child_process5, import_node_fs8, import_node_os3, import_node_path6, DRIVER_VERSION_ARGS, DRIVER_VERIFY_TIMEOUT_MS, ALLOWED_DRIVER_PATH, EXECUTABLE_HEADER_BYTES, ELF_MACHINE_BY_NODE_ARCH, ELF_MACHINE_LABELS, defaultDriverExec, BROWSER_CHANNELS, FRESHNESS_TTL_MS, RESOLVE_TIMEOUT_MS, RUNTIME_DEBUG2, defaultLogger2, inFlightInstalls2, geckodriverEnvQueue, GECKODRIVER_VERSIONED_NAME;
+var import_node_child_process5, import_node_fs8, import_node_os3, import_node_path7, DRIVER_VERSION_ARGS, DRIVER_VERIFY_TIMEOUT_MS, ALLOWED_DRIVER_PATH, EXECUTABLE_HEADER_BYTES, ELF_MACHINE_BY_NODE_ARCH, ELF_MACHINE_LABELS, defaultDriverExec, BROWSER_CHANNELS, FRESHNESS_TTL_MS, RESOLVE_TIMEOUT_MS, RUNTIME_DEBUG2, defaultLogger2, inFlightInstalls2, geckodriverEnvQueue, GECKODRIVER_VERSIONED_NAME;
 var init_browsers = __esm({
   "dist/runtime/browsers.js"() {
     "use strict";
     import_node_child_process5 = require("node:child_process");
     import_node_fs8 = __toESM(require("node:fs"), 1);
     import_node_os3 = __toESM(require("node:os"), 1);
-    import_node_path6 = __toESM(require("node:path"), 1);
+    import_node_path7 = __toESM(require("node:path"), 1);
     init_cacheDir();
     init_loader();
     DRIVER_VERSION_ARGS = {
@@ -4429,7 +4569,7 @@ var init_browsers = __esm({
 function useDriversArgs(appiumHome, packages) {
   let manifestText;
   try {
-    manifestText = import_node_fs9.default.readFileSync(import_node_path7.default.join(appiumHome, "node_modules", ".cache", "appium", "extensions.yaml"), "utf8");
+    manifestText = import_node_fs9.default.readFileSync(import_node_path8.default.join(appiumHome, "node_modules", ".cache", "appium", "extensions.yaml"), "utf8");
   } catch {
   }
   let registered;
@@ -4442,7 +4582,7 @@ function useDriversArgs(appiumHome, packages) {
   }
   const names = packages.flatMap((pkg) => {
     try {
-      const name = JSON.parse(import_node_fs9.default.readFileSync(import_node_path7.default.join(appiumHome, "node_modules", pkg, "package.json"), "utf8"))?.appium?.driverName;
+      const name = JSON.parse(import_node_fs9.default.readFileSync(import_node_path8.default.join(appiumHome, "node_modules", pkg, "package.json"), "utf8"))?.appium?.driverName;
       return typeof name === "string" && name ? [{ name, pkg }] : [];
     } catch {
       return [];
@@ -4461,26 +4601,26 @@ function browserPoolDriverPackages(platform) {
   ];
 }
 function appiumHomeForDriverPath(driverEntry) {
-  const marker = `${import_node_path7.default.sep}node_modules${import_node_path7.default.sep}`;
+  const marker = `${import_node_path8.default.sep}node_modules${import_node_path8.default.sep}`;
   const idx = driverEntry.lastIndexOf(marker);
   return idx === -1 ? null : driverEntry.slice(0, idx);
 }
 function setAppiumHome(ctx = {}) {
   process.env.APPIUM_HOME = getRuntimeDir({ cacheDir: ctx.cacheDir });
 }
-var import_node_fs9, import_node_path7;
+var import_node_fs9, import_node_path8;
 var init_appium = __esm({
   "dist/core/appium.js"() {
     "use strict";
     import_node_fs9 = __toESM(require("node:fs"), 1);
-    import_node_path7 = __toESM(require("node:path"), 1);
+    import_node_path8 = __toESM(require("node:path"), 1);
     init_cacheDir();
     init_lazyYaml();
   }
 });
 
 // dist/core/files.js
-async function readFile({ fileURLOrPath }) {
+async function readFile({ fileURLOrPath, throwOnError = false }) {
   if (!fileURLOrPath) {
     throw new Error("fileURLOrPath is required");
   }
@@ -4497,40 +4637,55 @@ async function readFile({ fileURLOrPath }) {
     isRemote = parsedURL.protocol === "http:" || parsedURL.protocol === "https:";
   } catch (error) {
   }
+  const fail = (message) => {
+    if (throwOnError)
+      throw new Error(message);
+    log({}, "warning", message);
+    return null;
+  };
   if (isRemote) {
     try {
       const response = await (await import("axios")).default.get(fileURLOrPath);
       content = response.data;
     } catch (error) {
-      console.warn(`Error reading remote file from ${fileURLOrPath}: ${error.message}`);
-      return null;
+      return fail(`Couldn't read ${redactUrlForOutput(fileURLOrPath)}${reason(error.message)}`);
     }
   } else {
     try {
       content = await import_node_fs10.default.promises.readFile(fileURLOrPath, "utf8");
     } catch (error) {
-      if (error.code === "ENOENT") {
-        console.warn(`File not found: ${fileURLOrPath}`);
-      } else {
-        console.warn(`Error reading file: ${error.message}`);
-      }
-      return null;
+      return fail(`Couldn't read ${import_node_path9.default.resolve(fileURLOrPath)}${error.code === "ENOENT" ? ": the file doesn't exist." : reason(error.message)}`);
     }
   }
-  const ext = fileURLOrPath.split(".").pop()?.toLowerCase();
+  return parseFileContent(content, fileURLOrPath, { throwOnError });
+}
+function locationOf(fileURLOrPath) {
+  return /^https?:\/\//i.test(fileURLOrPath) ? redactUrlForOutput(fileURLOrPath) : import_node_path9.default.resolve(fileURLOrPath);
+}
+function parseFileContent(content, fileURLOrPath, { throwOnError = false } = {}) {
+  if (typeof content !== "string")
+    return content;
+  const name = /^https?:\/\//i.test(fileURLOrPath) ? new URL(fileURLOrPath).pathname : fileURLOrPath;
+  const ext = name.split(".").pop()?.toLowerCase();
+  const failed = (format, error) => {
+    if (throwOnError) {
+      const cause = String(error.message).split("\n")[0].replace(/:$/, "");
+      throw new Error(`Couldn't read ${locationOf(fileURLOrPath)}: it isn't valid ${format} (${cause}).`);
+    }
+    log({}, "warning", `Failed to parse ${format}: ${error.message}`);
+    return content;
+  };
   if (ext === "json") {
     try {
       return JSON.parse(content);
     } catch (error) {
-      console.warn(`Failed to parse JSON: ${error.message}`);
-      return content;
+      return failed("JSON", error);
     }
   } else if (ext === "yaml" || ext === "yml") {
     try {
       return requireYaml().parse(content);
     } catch (error) {
-      console.warn(`Failed to parse YAML: ${error.message}`);
-      return content;
+      return failed("YAML", error);
     }
   } else {
     return content;
@@ -4579,13 +4734,13 @@ async function resolvePaths({ config, object, filePath, nested = false, objectTy
     if (relativePath.startsWith("https://") || relativePath.startsWith("http://") || relativePath.startsWith("heretto:")) {
       return relativePath;
     }
-    if (import_node_path8.default.isAbsolute(relativePath)) {
+    if (import_node_path9.default.isAbsolute(relativePath)) {
       return relativePath;
     }
     const fileExists = import_node_fs10.default.existsSync(filePath2);
-    const isFile = fileExists ? import_node_fs10.default.lstatSync(filePath2).isFile() : import_node_path8.default.parse(filePath2).ext !== "";
-    const basePath = isFile ? import_node_path8.default.dirname(filePath2) : filePath2;
-    return baseType === "file" ? import_node_path8.default.resolve(basePath, relativePath) : import_node_path8.default.resolve(relativePath);
+    const isFile = fileExists ? import_node_fs10.default.lstatSync(filePath2).isFile() : import_node_path9.default.parse(filePath2).ext !== "";
+    const basePath = isFile ? import_node_path9.default.dirname(filePath2) : filePath2;
+    return baseType === "file" ? import_node_path9.default.resolve(basePath, relativePath) : import_node_path9.default.resolve(relativePath);
   }
   const relativePathBase = config.relativePathBase;
   let pathProperties;
@@ -4635,7 +4790,7 @@ async function resolvePaths({ config, object, filePath, nested = false, objectTy
             isStep: property === "steps"
           });
         } else if (typeof item === "string" && pathProperties.includes(property)) {
-          const resolved = property === "path" && object.directory && import_node_path8.default.isAbsolute(object.directory) ? resolve(relativePathBase, item, object.directory) : resolve(relativePathBase, item, filePath);
+          const resolved = property === "path" && object.directory && import_node_path9.default.isAbsolute(object.directory) ? resolve(relativePathBase, item, object.directory) : resolve(relativePathBase, item, filePath);
           object[property][i] = resolved;
         }
       }
@@ -4653,7 +4808,7 @@ async function resolvePaths({ config, object, filePath, nested = false, objectTy
       }
       if (pathProperties.includes(property) || isStep && stepShorthandPathProperties.includes(property)) {
         if (property === "path" && object.directory) {
-          const directory = import_node_path8.default.isAbsolute(object.directory) ? object.directory : resolve(relativePathBase, object.directory, filePath);
+          const directory = import_node_path9.default.isAbsolute(object.directory) ? object.directory : resolve(relativePathBase, object.directory, filePath);
           object[property] = resolve(relativePathBase, object[property], directory);
         } else {
           object[property] = resolve(relativePathBase, object[property], filePath);
@@ -4663,14 +4818,19 @@ async function resolvePaths({ config, object, filePath, nested = false, objectTy
   }
   return object;
 }
-var import_node_fs10, import_node_path8;
+var import_node_fs10, import_node_path9, reason;
 var init_files = __esm({
   "dist/core/files.js"() {
     "use strict";
     import_node_fs10 = __toESM(require("node:fs"), 1);
-    import_node_path8 = __toESM(require("node:path"), 1);
+    import_node_path9 = __toESM(require("node:path"), 1);
     init_validate();
     init_lazyYaml();
+    init_utils();
+    reason = (text) => {
+      const trimmed2 = text?.trim();
+      return !trimmed2 ? "." : `: ${/[.!?]$/.test(trimmed2) ? trimmed2 : `${trimmed2}.`}`;
+    };
   }
 });
 
@@ -4685,9 +4845,80 @@ async function loadDescription(descriptionPath = "") {
   if (!descriptionPath) {
     throw new Error("Description is required.");
   }
-  const definition = await readFile({ fileURLOrPath: descriptionPath });
-  const parser = (await import("@apidevtools/json-schema-ref-parser")).default;
-  const dereferencedDefinition = await parser.dereference(definition);
+  const guard = localUrlPolicy() !== "allow";
+  let lastPublic;
+  const docName = (given, final) => {
+    const [a, b] = [given, final].map(redactUrlForOutput);
+    return a === b ? a : `${a} (redirected to ${b})`;
+  };
+  let definition;
+  if (guard && /^https?:\/\//i.test(descriptionPath)) {
+    const root = await getGuarded(descriptionPath, FETCH_TEXT_DEFAULTS);
+    const text = root.data;
+    let content = text;
+    try {
+      content = JSON.parse(text);
+    } catch {
+    }
+    definition = parseFileContent(content, descriptionPath, { throwOnError: true });
+    if (root.reachedPublic)
+      lastPublic = docName(descriptionPath, root.url);
+  } else {
+    definition = await readFile({ fileURLOrPath: descriptionPath, throwOnError: true });
+  }
+  if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+    throw new Error(`Couldn't read ${locationOf(descriptionPath)}: it's empty or isn't a JSON or YAML object.`);
+  }
+  const refused = (ref, doc, target) => new UrlGuardError(`Couldn't resolve $ref ${ref} in ${doc}: a public document can't refer to ${target}.
+Hint: If you trust this document, set DOC_DETECTIVE_ALLOW_LOCAL_URLS=1, or download it and point descriptionPath at the local copy.`);
+  const { default: parser, FileResolver, getJsonSchemaRefParserDefaultOptions } = await import("@apidevtools/json-schema-ref-parser");
+  if (typeof FileResolver.read !== "function") {
+    throw new Error("Couldn't load the OpenAPI description: json-schema-ref-parser's FileResolver.read isn't a function.");
+  }
+  const httpDefaults = getJsonSchemaRefParserDefaultOptions?.()?.resolve?.http;
+  if (typeof httpDefaults?.read !== "function" || !("safeUrlResolver" in httpDefaults)) {
+    throw new Error("Couldn't load the OpenAPI description: json-schema-ref-parser's http resolver has no read function or safeUrlResolver option, so Doc Detective can't guard its $refs.");
+  }
+  const readLocalFile = FileResolver.read.bind(FileResolver);
+  const dereferencedDefinition = await parser.dereference(definition, {
+    resolve: {
+      file: {
+        async read(file) {
+          if (lastPublic) {
+            throw refused(redactUrlForOutput(file.url.split("#")[0]), lastPublic, "a local file");
+          }
+          return readLocalFile(file);
+        }
+      },
+      http: {
+        // The parser's own guard refuses every private address, even from a
+        // local description. Doc Detective's read() below enforces
+        // localUrlPolicy() in its place, so don't remove this.
+        safeUrlResolver: false,
+        async read(file) {
+          const ref = redactUrlForOutput(file.url);
+          const doc = lastPublic;
+          if (doc) {
+            let address;
+            try {
+              address = await privateAddressOf(file.url);
+            } catch (error) {
+              if (!error.host)
+                throw error;
+              throw new Error(`Couldn't resolve $ref ${ref} in ${doc}: couldn't resolve host ${error.host} (${error.code}).`);
+            }
+            if (address)
+              throw refused(ref, doc, `${address}, a private address`);
+          }
+          const refuseRef = doc ? (privateAddress) => refused(ref, doc, `${privateAddress}, a private address`) : void 0;
+          const { data, url, reachedPublic } = await getGuarded(file.url, FETCH_TEXT_DEFAULTS, refuseRef, refuseRef && ((_from, privateAddress) => refuseRef(privateAddress)));
+          if (guard && reachedPublic)
+            lastPublic = docName(file.url, url);
+          return data;
+        }
+      }
+    }
+  });
   return dereferencedDefinition;
 }
 async function getOperation(definition = {}, operationId = "", responseCode = "", exampleKey = "", server = "") {
@@ -4697,10 +4928,10 @@ async function getOperation(definition = {}, operationId = "", responseCode = ""
   if (!operationId) {
     throw new Error("OperationId is required.");
   }
-  for (const path31 in definition.paths) {
-    for (const method in definition.paths[path31]) {
-      if (definition.paths[path31][method].operationId === operationId) {
-        const operation = definition.paths[path31][method];
+  for (const path32 in definition.paths) {
+    for (const method in definition.paths[path32]) {
+      if (definition.paths[path32][method].operationId === operationId) {
+        const operation = definition.paths[path32][method];
         if (!server) {
           if (definition.servers && definition.servers.length > 0) {
             server = definition.servers[0].url;
@@ -4708,9 +4939,9 @@ async function getOperation(definition = {}, operationId = "", responseCode = ""
             throw new Error("No server URL provided and no servers defined in the OpenAPI definition.");
           }
         }
-        const example = await compileExample(operation, server + path31, responseCode, exampleKey);
+        const example = await compileExample(operation, server + path32, responseCode, exampleKey);
         const schemas = getSchemas(operation, responseCode);
-        return { path: path31, method, definition: operation, schemas, example };
+        return { path: path32, method, definition: operation, schemas, example };
       }
     }
   }
@@ -4731,15 +4962,15 @@ function getSchemas(definition = {}, responseCode = "") {
   schemas.response = definition.responses[responseCode].content[Object.keys(definition.responses[responseCode].content)[0]].schema;
   return schemas;
 }
-async function compileExample(operation = {}, path31 = "", responseCode = "", exampleKey = "") {
+async function compileExample(operation = {}, path32 = "", responseCode = "", exampleKey = "") {
   if (!operation) {
     throw new Error("Operation is required.");
   }
-  if (!path31) {
+  if (!path32) {
     throw new Error("Path is required.");
   }
   let example = {
-    url: path31,
+    url: path32,
     request: { parameters: {}, headers: {}, body: {} },
     response: { headers: {}, body: {} }
   };
@@ -5104,6 +5335,9 @@ function getEnvironment() {
   const environment = {};
   environment.arch = import_node_os4.default.arch();
   environment.platform = platformMap[process.platform];
+  environment.docDetectiveVersion = ownVersion();
+  environment.nodeVersion = process.versions.node;
+  environment.osRelease = import_node_os4.default.release();
   return environment;
 }
 function cacheKeyFor(config) {
@@ -5177,7 +5411,7 @@ function detectInstalledBrowserDrivers(config, isInstalled = (name) => Boolean(r
 async function probeBrowserEnvironment({ config, browsersDir }) {
   setAppiumHome({ cacheDir: config?.cacheDir });
   const cwd = process.cwd();
-  process.chdir(import_node_path9.default.join(__dirname3, "../.."));
+  process.chdir(packageRoot() ?? cwd);
   let installedBrowsers = [];
   let browserDetectionFailed = false;
   let installedDrivers = { chromium: false, gecko: false, safari: false };
@@ -5393,7 +5627,7 @@ async function getBrowserDiagnostics({ config }) {
   });
   return { browsers, detectionFailed };
 }
-var import_node_os4, import_node_fs11, import_node_path9, import_node_child_process6, import_node_url4, __dirname3, platformMap, defaultFileTypes, cachedAppsByDir;
+var import_node_os4, import_node_fs11, import_node_child_process6, platformMap, defaultFileTypes, cachedAppsByDir;
 var init_config = __esm({
   "dist/core/config.js"() {
     "use strict";
@@ -5401,15 +5635,13 @@ var init_config = __esm({
     import_node_fs11 = __toESM(require("node:fs"), 1);
     init_validate();
     init_utils();
-    import_node_path9 = __toESM(require("node:path"), 1);
     import_node_child_process6 = require("node:child_process");
     init_loader();
     init_cacheDir();
+    init_heavyDeps();
     init_browsers();
     init_appium();
     init_openapi();
-    import_node_url4 = require("node:url");
-    __dirname3 = import_node_path9.default.dirname((0, import_node_url4.fileURLToPath)(importMetaUrl));
     platformMap = {
       darwin: "mac",
       linux: "linux",
@@ -6684,10 +6916,9 @@ function sendTelemetry(config, command, results) {
   if (config?.telemetry?.send === false)
     return;
   const telemetryData = process.env["DOC_DETECTIVE_META"] !== void 0 ? JSON.parse(process.env["DOC_DETECTIVE_META"]) : {};
-  const pkg = require2("../../package.json");
   telemetryData.distribution = telemetryData.distribution || "doc-detective";
   telemetryData.dist_interface = telemetryData.dist_interface || "package";
-  telemetryData.core_version = pkg.version;
+  telemetryData.core_version = ownVersion() ?? "unknown";
   telemetryData.dist_version = telemetryData.dist_version || telemetryData.core_version;
   telemetryData.core_platform = platformMap2[import_node_os14.default.platform()] || import_node_os14.default.platform();
   telemetryData.dist_platform = telemetryData.dist_platform || telemetryData.core_platform;
@@ -6706,14 +6937,14 @@ function sendTelemetry(config, command, results) {
         Object.entries(value).forEach(([key, value2]) => {
           if (typeof value2 === "object") {
             Object.entries(value2).forEach(([key2, value22]) => {
-              telemetryData[`${parentKey.replace(" ", "_")}_${key.replace(" ", "_")}_${key2.replace(" ", "_")}`] = value22;
+              telemetryData[`${parentKey.replaceAll(" ", "_")}_${key.replaceAll(" ", "_")}_${key2.replaceAll(" ", "_")}`] = value22;
             });
           } else {
-            telemetryData[`${parentKey.replace(" ", "_")}_${key.replace(" ", "_")}`] = value2;
+            telemetryData[`${parentKey.replaceAll(" ", "_")}_${key.replaceAll(" ", "_")}`] = value2;
           }
         });
       } else {
-        telemetryData[parentKey.replace(" ", "_")] = value;
+        telemetryData[parentKey.replaceAll(" ", "_")] = value;
       }
     });
   }
@@ -6728,15 +6959,14 @@ async function awaitTelemetryFlush() {
   if (pending)
     await pending;
 }
-var import_node_os14, import_posthog_node, import_node_module5, require2, platformMap2, TELEMETRY_FLUSH_TIMEOUT_MS, pendingTelemetryFlush;
+var import_node_os14, import_posthog_node, platformMap2, TELEMETRY_FLUSH_TIMEOUT_MS, pendingTelemetryFlush;
 var init_telem = __esm({
   "dist/core/telem.js"() {
     "use strict";
     import_node_os14 = __toESM(require("node:os"), 1);
     import_posthog_node = require("posthog-node");
-    import_node_module5 = require("node:module");
     init_telemLite();
-    require2 = (0, import_node_module5.createRequire)(importMetaUrl);
+    init_heavyDeps();
     platformMap2 = {
       win32: "windows",
       darwin: "mac",
@@ -6992,7 +7222,7 @@ var import_node_fs12 = __toESM(require("node:fs"), 1);
 var import_node_path10 = __toESM(require("node:path"), 1);
 var import_node_https2 = __toESM(require("node:https"), 1);
 var import_node_http = __toESM(require("node:http"), 1);
-var import_node_module4 = require("node:module");
+var import_node_module3 = require("node:module");
 var import_node_os5 = __toESM(require("node:os"), 1);
 var import_node_crypto4 = __toESM(require("node:crypto"), 1);
 var import_adm_zip = __toESM(require("adm-zip"), 1);
@@ -7773,7 +8003,7 @@ var HerettoUploader = class {
     return contentTypes[ext] || "application/octet-stream";
   }
 };
-var requireFromHere2 = (0, import_node_module4.createRequire)(importMetaUrl);
+var requireFromHere2 = (0, import_node_module3.createRequire)(importMetaUrl);
 var requireAxios = () => requireFromHere2("axios");
 var POLLING_INTERVAL_MS = 5e3;
 var POLLING_TIMEOUT_MS = 3e5;
@@ -8745,7 +8975,8 @@ function resolveContexts({ contexts, test, config }) {
           if (platform !== void 0)
             staticContext.platform = platform;
           if (browser !== void 0) {
-            staticContext.browser = browser.name === "safari" && !isMobileTargetPlatform(platform) ? { ...browser, name: "webkit" } : { ...browser };
+            const { version: _authored, ...authoredBrowser } = browser;
+            staticContext.browser = browser.name === "safari" && !isMobileTargetPlatform(platform) ? { ...authoredBrowser, name: "webkit" } : authoredBrowser;
           }
           staticContexts.push(staticContext);
         });
@@ -14816,11 +15047,11 @@ function hasUnresolvedMetaReference(expression, context) {
   }
   return false;
 }
-function getMetaValue(path31, context) {
+function getMetaValue(path32, context) {
   if (!context) {
     return void 0;
   }
-  const [basePath, jsonPointer] = path31.split("#");
+  const [basePath, jsonPointer] = path32.split("#");
   const resolvedPath = resolvePathTemplateVariables(basePath, context);
   let value = getNestedProperty(context, resolvedPath);
   if (jsonPointer && value) {
@@ -14837,9 +15068,9 @@ function getMetaValue(path31, context) {
   }
   return value;
 }
-function resolvePathTemplateVariables(path31, context) {
+function resolvePathTemplateVariables(path32, context) {
   const templateRegex = /\{\{(\w+)\}\}/g;
-  return path31.replace(templateRegex, (match, varName) => {
+  return path32.replace(templateRegex, (match, varName) => {
     if (context && context.id && varName === "id") {
       return context.id;
     }
@@ -14876,10 +15107,10 @@ async function resolveEmbeddedExpressions(str, context) {
   parts.push(str.slice(lastIdx));
   return parts.join("");
 }
-function getNestedProperty(obj, path31) {
-  if (!obj || !path31)
+function getNestedProperty(obj, path32) {
+  if (!obj || !path32)
     return void 0;
-  const parts = path31.split(".");
+  const parts = path32.split(".");
   let current = obj;
   for (const part of parts) {
     if (current === null || current === void 0)
@@ -16050,6 +16281,11 @@ async function wait({ config, step, driver }) {
   return result;
 }
 
+// dist/core/tests/timing.js
+var RECORDING_PACE_MS = 2e3;
+var RENDER_SETTLE_MS = 100;
+var RECORDER_SETTLE_MS = 500;
+
 // dist/core/tests/findElement.js
 async function finalizeFound({ result }) {
   const specs = [
@@ -16222,7 +16458,7 @@ async function findElement({ config, step, driver, click, appSession, processReg
         }
       }
       if (isRecordingActive(driver)) {
-        await wait({ config, step: { wait: 2e3 }, driver });
+        await wait({ config, step: { wait: RECORDING_PACE_MS }, driver });
       }
       return result;
     } else {
@@ -16325,7 +16561,7 @@ async function findElement({ config, step, driver, click, appSession, processReg
     }
   }
   if (isRecordingActive(driver)) {
-    await wait({ config, step: { wait: 2e3 }, driver });
+    await wait({ config, step: { wait: RECORDING_PACE_MS }, driver });
   }
   return result;
 }
@@ -16960,7 +17196,7 @@ async function goTo({ config, step, driver }) {
       }, { timeout: waitTimeout });
       waitResults.documentReady.passed = true;
       waitResults.documentReady.message = "Document ready";
-      await driver.pause(100);
+      await driver.pause(RENDER_SETTLE_MS);
       const elapsedTime = Date.now() - waitStartTime;
       const remainingTimeout = waitTimeout - elapsedTime;
       if (remainingTimeout <= 0) {
@@ -17185,10 +17421,13 @@ async function startBackgroundProcessSurface({ config, descriptor, processRegist
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     let bg;
     if (descriptor.tty) {
+      const size = typeof descriptor.tty === "object" ? descriptor.tty : {};
       try {
         bg = await d.spawnPtyBackgroundCommand(descriptor.command, args, {
           ...bgOptions,
-          cacheDir: config?.cacheDir
+          cacheDir: config?.cacheDir,
+          cols: size.cols,
+          rows: size.rows
         });
       } catch (error) {
         if (error?.code !== "NODE_PTY_UNAVAILABLE") {
@@ -17478,13 +17717,13 @@ function shouldRetry(statusCode) {
     return false;
   return statusCode === 429 || statusCode >= 500;
 }
-async function attemptRequest(method, url, headers) {
+async function attemptRequest(method, url, headers, timeout) {
   try {
     const res = await (await loadAxios()).request({
       method,
       url,
       headers,
-      timeout: 1e4,
+      timeout,
       maxRedirects: 5,
       validateStatus: () => true
     });
@@ -17497,7 +17736,7 @@ async function attemptRequest(method, url, headers) {
         retryAfter: parseRetryAfter(error.response.headers?.["retry-after"] ?? error.response.headers?.["Retry-After"])
       };
     }
-    return { statusCode: null, retryAfter: null };
+    return { statusCode: null, retryAfter: null, errorCode: error?.code };
   }
 }
 async function checkLink({ config, step }) {
@@ -17538,11 +17777,12 @@ async function checkLink({ config, step }) {
   }
   const headers = mergeHeaders(step.checkLink.headers);
   const url = step.checkLink.url;
+  const timeout = step.checkLink.timeout ?? 1e4;
   const acceptedCodes = step.checkLink.statusCodes;
   const isAccepted = (code) => code !== null && acceptedCodes.indexOf(code) >= 0;
   let last = { statusCode: null, retryAfter: null };
   for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-    last = await attemptRequest("get", url, headers);
+    last = await attemptRequest("get", url, headers, timeout);
     if (isAccepted(last.statusCode))
       break;
     if (!shouldRetry(last.statusCode))
@@ -17553,14 +17793,14 @@ async function checkLink({ config, step }) {
     }
   }
   if (!isAccepted(last.statusCode) && (last.statusCode === 429 || last.statusCode === 403)) {
-    const headResult = await attemptRequest("head", url, headers);
+    const headResult = await attemptRequest("head", url, headers, timeout);
     if (isAccepted(headResult.statusCode)) {
       last = headResult;
     }
   }
   if (last.statusCode === null) {
     result.status = "FAIL";
-    result.description = `Invalid or unresolvable URL: ${url}`;
+    result.description = last.errorCode === "ECONNABORTED" ? `Couldn't reach ${redactUrlForOutput(url)}: no response within ${timeout} ms (ECONNABORTED).` : `Invalid or unresolvable URL: ${redactUrlForOutput(url)}`;
     return result;
   }
   result.outputs = { statusCode: last.statusCode };
@@ -18048,7 +18288,8 @@ async function captureScreenshot({ config, step, driver, appSession, processRegi
     const fetched = await fetchFile(originalUrlPath, { binary: true });
     if (fetched.result !== "success") {
       result.status = "FAIL";
-      result.description = `Couldn't fetch remote reference image (${redactedUrl}): ${fetched.message}`;
+      const msg = fetched.message?.message ?? String(fetched.message);
+      result.description = fetched.message instanceof UrlGuardError ? msg : `Couldn't fetch remote reference image (${redactedUrl}): ${msg}`;
       return result;
     }
     existFilePath = fetched.path;
@@ -18171,7 +18412,7 @@ async function captureScreenshot({ config, step, driver, appSession, processRegi
       });
       window.scrollBy(-pad.left, -pad.top);
     }, element, padding);
-    await driver.pause(100);
+    await driver.pause(RENDER_SETTLE_MS);
   }
   const recordingActive = !isAppCapture && isRecordingActive(driver);
   let captureBuffer;
@@ -19103,7 +19344,7 @@ async function startRecording({ config, context, step, driver, recordingHost, ap
   proc.on("error", (err) => {
     spawnError = err;
   });
-  await new Promise((r) => setTimeout(r, 500));
+  await new Promise((r) => setTimeout(r, RECORDER_SETTLE_MS));
   if (spawnError || proc.exitCode !== null) {
     result.status = "FAIL";
     result.description = `Couldn't start ffmpeg recording.${spawnError ? ` ${spawnError}` : ` ffmpeg exited with code ${proc.exitCode}.`} On macOS, grant screen recording permission; on Linux, ensure a display (or Xvfb) is available.${stderrTail ? ` ffmpeg: ${stderrTail.trim().slice(-500)}` : ""}`;
@@ -19665,7 +19906,7 @@ async function waitForStableFile(filePath, maxSeconds) {
       stableReads = 0;
     }
     lastSize = size;
-    await new Promise((r) => setTimeout(r, 500));
+    await new Promise((r) => setTimeout(r, RECORDER_SETTLE_MS));
   }
   return false;
 }
@@ -20066,9 +20307,9 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
       delete step.httpRequest.openApi.definition;
     } else if (openApiDefinitions.length > 0) {
       findOperation: for (const openApiConfig of openApiDefinitions) {
-        for (const path31 in openApiConfig.definition.paths) {
-          for (const method in openApiConfig.definition.paths[path31]) {
-            if (openApiConfig.definition.paths[path31][method].operationId === step.httpRequest.openApi.operationId) {
+        for (const path32 in openApiConfig.definition.paths) {
+          for (const method in openApiConfig.definition.paths[path32]) {
+            if (openApiConfig.definition.paths[path32][method].operationId === step.httpRequest.openApi.operationId) {
               openApiDefinition = openApiConfig.definition;
               step.httpRequest.openApi = {
                 ...openApiConfig,
@@ -20138,10 +20379,7 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
         };
     }
     if (step.httpRequest.openApi.statusCode) {
-      step.httpRequest.statusCodes = [
-        step.httpRequest.openApi.statusCode,
-        ...step.httpRequest.statusCodes || []
-      ];
+      step.httpRequest.statusCodes = [step.httpRequest.openApi.statusCode].concat(step.httpRequest.statusCodes || []);
     } else if (!step.httpRequest.statusCodes) {
       step.httpRequest.statusCodes = Object.keys(operation.definition.responses).filter((code) => code.startsWith("2")).map((code) => Number(code));
     }
@@ -20162,7 +20400,8 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
   step.httpRequest = {
     ...step.httpRequest,
     method: step.httpRequest.method || "get",
-    statusCodes: step.httpRequest.statusCodes || [200, 201],
+    // A scalar statusCodes is one accepted code (as in checkLink).
+    statusCodes: [].concat(step.httpRequest.statusCodes || [200, 201]),
     request: step.httpRequest.request || {
       params: {},
       headers: {},
@@ -20426,8 +20665,8 @@ async function httpRequest({ config, step, openApiDefinitions = [] }) {
   result.description = descriptions.join(" ").trim();
   return result;
 }
-function fieldExistsAtPath(obj, path31) {
-  const segments = path31.match(/[^.[\]]+/g);
+function fieldExistsAtPath(obj, path32) {
+  const segments = path32.match(/[^.[\]]+/g);
   if (!segments) {
     return false;
   }
@@ -20585,6 +20824,11 @@ async function clickElement({ config, step, driver, appSession, processRegistry,
     return result;
   }
   step = isValidStep.object;
+  if (typeof step.click === "boolean") {
+    result.status = "FAIL";
+    result.description = `\`click\` needs an element, not ${step.click}. To click an element whose text is "${step.click}", quote it: "click": "${step.click}".`;
+    return result;
+  }
   let findStep;
   if (typeof step.click === "string") {
     findStep = { find: step.click };
@@ -21619,6 +21863,7 @@ function raceBootInitiation({ startAcquire, onError }) {
 
 // dist/core/tests.js
 init_cacheDir();
+init_heavyDeps();
 
 // dist/core/tests/runBrowserScript.js
 init_validate();
@@ -22141,26 +22386,35 @@ async function uploadChangedFiles({ config, report, log: log3 }) {
   for (const file of changedFiles) {
     const uploader = getUploader(file.sourceIntegration);
     if (!uploader) {
-      log3(config, "warning", `No uploader found for integration type: ${file.sourceIntegration.type}`);
+      const why = `no uploader handles integration type \`${file.sourceIntegration.type}\`.`;
+      log3(config, "warning", `Couldn't upload ${file.localPath}: ${why}`);
       results.skipped++;
       results.details.push({
         localPath: file.localPath,
         status: "SKIPPED",
-        reason: `No uploader for type: ${file.sourceIntegration.type}`
+        reason: `Skipped: ${why}`
       });
       continue;
     }
     const integrationConfig = getIntegrationConfig(config, file.sourceIntegration);
     if (!integrationConfig) {
-      log3(config, "warning", `No integration config found for: ${file.sourceIntegration.integrationName}`);
+      const why = `no \`${file.sourceIntegration.integrationName}\` integration is configured.`;
+      log3(config, "warning", `Couldn't upload ${file.localPath}: ${why}`);
       results.skipped++;
       results.details.push({
         localPath: file.localPath,
         status: "SKIPPED",
-        reason: `No integration config found for: ${file.sourceIntegration.integrationName}`
+        reason: `Skipped: ${why}`
       });
       continue;
     }
+    if (integrationConfig.uploadOnChange !== true) {
+      const reason2 = `Skipped: \`uploadOnChange\` isn't enabled for integration ${file.sourceIntegration.integrationName}.`;
+      log3(config, "debug", `${file.localPath}: ${reason2}`);
+      results.skipped++;
+      results.details.push({ localPath: file.localPath, status: "SKIPPED", reason: reason2 });
+      continue;
+    }
     uploadTasks.push({
       file,
       uploader,
@@ -22232,8 +22486,6 @@ function getIntegrationConfig(config, sourceIntegration) {
 // dist/core/tests.js
 var import_node_http2 = __toESM(require("node:http"), 1);
 var import_node_https3 = __toESM(require("node:https"), 1);
-var import_node_url5 = require("node:url");
-var __dirname4 = import_node_path30.default.dirname((0, import_node_url5.fileURLToPath)(importMetaUrl));
 var lastReuseConfig;
 var appiumServerCache = createServerCache({
   kill: (server) => killTree(server.process?.pid),
@@ -22794,6 +23046,8 @@ async function runViaApi({ resolvedTests, apiKey, config = {} }) {
           steps: { pass: 0, fail: 0, warning: 0, skipped: 0 }
         },
         // Nothing ran, but the shape stays parity with runSpecs' short-circuit.
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        environment: getEnvironment(),
         durationMs: 0,
         specs: []
       };
@@ -22891,6 +23145,8 @@ async function runSpecs({ resolvedTests }) {
         contexts: { pass: 0, fail: 0, warning: 0, skipped: 0 },
         steps: { pass: 0, fail: 0, warning: 0, skipped: 0 }
       },
+      startedAt: new Date(runStart).toISOString(),
+      environment: getEnvironment(),
       durationMs: Date.now() - runStart,
       specs: []
     };
@@ -22917,6 +23173,10 @@ async function runSpecs({ resolvedTests }) {
   const report = {
     runId,
     runDir,
+    // Run metadata (ADR 01163): when execution started and the host that ran
+    // it, so a consumer can tell product drift from environment drift.
+    startedAt: new Date(runStart).toISOString(),
+    environment: runnerDetails.environment,
     summary: {
       specs: {
         pass: 0,
@@ -23391,30 +23651,31 @@ async function runSpecs({ resolvedTests }) {
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
   }
-  const herettoConfigs = config?.integrations?.heretto || [];
-  const hasUploadEnabledIntegration = herettoConfigs.some(
-    (h) => h.uploadOnChange !== false
-    // Default to true if not explicitly set to false
-  );
-  const globalUploadOnChange = config?.uploadOnChange ?? true;
-  if (globalUploadOnChange && hasUploadEnabledIntegration && herettoConfigs.length > 0) {
-    try {
-      const uploadResults = await uploadChangedFiles({ config, report, log });
-      report.uploadResults = uploadResults;
-    } catch (error) {
-      log(config, "warning", `Failed to upload changed files: ${error.message}`);
-      report.uploadResults = {
-        total: 0,
-        successful: 0,
-        failed: 0,
-        skipped: 0,
-        error: error.message
-      };
-    }
-  }
+  const uploadResults = await uploadChangedFilesIfEnabled({ config, report, log });
+  if (uploadResults)
+    report.uploadResults = uploadResults;
   report.durationMs = Date.now() - runStart;
   return report;
 }
+async function uploadChangedFilesIfEnabled({ config, report, log: logFn, upload = uploadChangedFiles }) {
+  const integrationEntries = Object.values(config?.integrations ?? {}).flatMap((entries) => Array.isArray(entries) ? entries : []);
+  if (!integrationEntries.some((entry) => entry?.uploadOnChange === true)) {
+    return void 0;
+  }
+  try {
+    return await upload({ config, report, log: logFn });
+  } catch (error) {
+    logFn(config, "warning", `Failed to upload changed files: ${error.message}`);
+    return {
+      total: 0,
+      successful: 0,
+      failed: 0,
+      skipped: 0,
+      details: [],
+      error: error.message
+    };
+  }
+}
 async function runRoutedSpec({ spec, specReport, specGuardSkip, config, runnerDetails, appiumPool, portToDisplay, metaValues, installAttempts, warmUpResults, processRegistry, deviceRegistry, simulatorRegistry, appServerPool, platform, markAutoRecord, limit, resourceRegistry, exclusivityCtx }) {
   let stopRest = false;
   let warnedRunStop = false;
@@ -24437,6 +24698,14 @@ ${JSON.stringify(context, null, 2)}`);
         engine: String(mobileWebBrowserName).toLowerCase(),
         driver
       });
+      const versions = sessionVersions({ capabilities: driver?.capabilities });
+      if (versions.browserVersion)
+        contextReport.browser = {
+          ...contextReport.browser,
+          version: versions.browserVersion
+        };
+      if (versions.driver)
+        contextReport.driver = versions.driver;
     } else if (driverRequired) {
       appiumPort = await appiumPool.acquire();
       if (portToDisplay) {
@@ -24566,6 +24835,17 @@ ${JSON.stringify(context, null, 2)}`);
         };
         clog("warning", fellBackNote);
       }
+      const versions = sessionVersions({
+        capabilities: driver?.capabilities,
+        app: availableApps.find((app) => app.name === normalizeBrowserName(startedName))
+      });
+      if (versions.browserVersion)
+        contextReport.browser = {
+          ...contextReport.browser,
+          version: versions.browserVersion
+        };
+      if (versions.driver)
+        contextReport.driver = versions.driver;
       if (driver) {
         browserSessions = createSessionRegistry({
           open: async (engine, overrides) => {
@@ -24748,7 +25028,12 @@ ${JSON.stringify(r, null, 2)}`);
         r.resultDescription = r.description;
         delete r.status;
         delete r.description;
-        return { ...step, ...r, durationMs: Date.now() - stepStart };
+        return {
+          ...step,
+          ...r,
+          startedAt: new Date(stepStart).toISOString(),
+          durationMs: Date.now() - stepStart
+        };
       };
       let stepReport = await runStepOnce();
       let attempts = 1;
@@ -24952,6 +25237,7 @@ async function runContextWithRetries(args, runContextFn = runContext, delayMs =
     const start = Date.now();
     const report2 = await runContextFn(a);
     if (report2 && typeof report2 === "object") {
+      report2.startedAt = new Date(start).toISOString();
       report2.durationMs = Date.now() - start;
     }
     return report2;
@@ -25024,6 +25310,7 @@ async function stopAllRecordings({ config, context, driver, contextReport }) {
       contextReport.steps.push({
         ...stopRecordStep,
         ...stepResult,
+        startedAt: new Date(stopStart).toISOString(),
         durationMs: Date.now() - stopStart
       });
     } catch (error) {
@@ -25033,6 +25320,7 @@ async function stopAllRecordings({ config, context, driver, contextReport }) {
         ...stopRecordStep,
         result: "FAIL",
         resultDescription: `Couldn't stop recording. ${error?.message ?? error}`,
+        startedAt: new Date(stopStart).toISOString(),
         durationMs: Date.now() - stopStart
       });
     }
@@ -25314,7 +25602,7 @@ async function spawnAppiumServer(appiumEntry, config, display, extraEnv, extraAr
     ...extraArgs ?? []
   ], {
     windowsHide: true,
-    cwd: import_node_path30.default.join(__dirname4, "../.."),
+    cwd: packageRoot(),
     env
   });
   proc.on("error", (err) => {
@@ -25399,8 +25687,8 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
       if (!isRetryableSessionError(String(err && err.message), startupCeiling))
         throw err;
       if (attempt < maxAttempts) {
-        const reason = String(err?.message ?? err).split("\n")[0];
-        ctx.log?.(`Session start attempt ${attempt} of ${maxAttempts} failed (${reason}); retrying.`);
+        const reason2 = String(err?.message ?? err).split("\n")[0];
+        ctx.log?.(`Session start attempt ${attempt} of ${maxAttempts} failed (${reason2}); retrying.`);
         await new Promise((r) => setTimeout(r, 500 * attempt));
       }
     }
@@ -25495,7 +25783,7 @@ async function getRunner(options = {}) {
     ...useDriversArgs(process.env.APPIUM_HOME, browserPoolDriverPackages(process.platform))
   ], {
     windowsHide: true,
-    cwd: import_node_path30.default.join(__dirname4, "../..")
+    cwd: packageRoot()
   });
   appium.on("error", (err) => {
     log(config, "warning", `Appium process error: ${err?.stack ?? err?.message ?? String(err)}`);
@@ -25560,6 +25848,165 @@ async function getRunner(options = {}) {
 // dist/core/index.js
 init_telemLite();
 init_files();
+
+// dist/upgradeNotice.js
+var import_node_path31 = __toESM(require("node:path"), 1);
+var UPGRADE_GUIDE_URL = "https://docs.doc-detective.com/docs/ci/upgrade-to-v5";
+var warned = /* @__PURE__ */ new Set();
+function isAction() {
+  try {
+    return JSON.parse(process.env.DOC_DETECTIVE_META || "{}").dist_interface === "github-actions";
+  } catch {
+    return false;
+  }
+}
+function warnUpgrade(messages, logLevel) {
+  if (logLevel === "silent" || isAction())
+    return;
+  for (const message of messages) {
+    if (warned.has(message))
+      continue;
+    warned.add(message);
+    console.error(`Warning: ${message} See ${UPGRADE_GUIDE_URL}`);
+  }
+}
+function legacyEnv(env) {
+  try {
+    const parsed = JSON.parse(env.DOC_DETECTIVE || "{}");
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+var ROUTING = ["onPass", "onFail", "onWarning", "onSkip"];
+var LOCATORS = ["selector", "elementText", "elementId", "elementTestId", "elementClass", "elementAttribute", "elementAria"];
+var REJECTS = "Doc Detective 5.0 rejects with exit 2";
+var EXIT_2 = `which ${REJECTS}`;
+function routes(owner) {
+  return ROUTING.flatMap((key) => Array.isArray(owner[key]) ? owner[key] : []);
+}
+function testWarnings(test, where) {
+  return routes(test).flatMap((route) => [
+    ...route.stop === "run" ? [`A test in ${where} has \`stop: "run"\` in its routing, ${EXIT_2}. Use \`stop: "spec"\`, which is what 4.x does.`] : [],
+    ...["retry", "goToStep"].filter((key) => key in route).map((key) => `A test in ${where} has \`${key}\` in its routing, which 4.x ignores and ${REJECTS}. Remove it, or move it to a step.`)
+  ]);
+}
+var FREE_FORM = /* @__PURE__ */ new Set([
+  "request",
+  "response",
+  "headers",
+  "body",
+  "params",
+  "parameters",
+  "elementAttribute",
+  "variables",
+  "outputs",
+  "env",
+  "driverOptions",
+  "openApi"
+]);
+function negatives(value, found = /* @__PURE__ */ new Set()) {
+  if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (FREE_FORM.has(key))
+        continue;
+      if (typeof child === "number" && child < 0 && (key === "wait" || /(timeout|duration|delay)$/i.test(key)))
+        found.add(key);
+      negatives(child, found);
+    }
+  }
+  return found;
+}
+function offend(offenders, row, value, message) {
+  if (!offenders.has(row))
+    offenders.set(row, { values: /* @__PURE__ */ new Set(), message });
+  offenders.get(row).values.add(value);
+}
+function stepWarnings(step, where, offenders) {
+  const messages = [];
+  for (const route of routes(step)) {
+    if (route.stop === "spec" || route.stop === "run") {
+      messages.push(`A step in ${where} has \`stop: "${route.stop}"\` in its routing, ${EXIT_2}. Use \`stop: "test"\` on the step and \`stop: "spec"\` on the test, which works today.`);
+    }
+    if ("goToTest" in route) {
+      messages.push(`A step in ${where} has \`goToTest\` in its routing, which 4.x ignores and ${REJECTS}. Move it to the test's routing, which works today.`);
+    }
+  }
+  if (typeof step.click === "boolean") {
+    messages.push(`A \`click\` step in ${where} is \`${step.click}\`, which 4.x reads as text to click and ${REJECTS}. To click an element whose text is '${step.click}', quote it as \`"click": "${step.click}"\`, which works today. If you don't want a click, remove the step.`);
+  }
+  const objects = (value) => [value].flat().filter((s) => s && typeof s === "object");
+  if (objects(step.startSurface).concat(objects(step.closeSurface)).some((s) => s.browser === "edge")) {
+    messages.push(`A surface in ${where} uses \`browser: "edge"\`, which Doc Detective 5.0 removes. Use another \`browser\`, such as \`chrome\`, which works today.`);
+  }
+  const starts = objects(step.startSurface);
+  for (const surface of starts) {
+    const device = surface.device && typeof surface.device === "object" ? surface.device : {};
+    const removed = ["orientation", "udid", "provider"].filter((key) => key in device);
+    if (removed.length) {
+      messages.push(`A \`startSurface\` device in ${where} sets ${removed.map((key) => `\`${key}\``).join(", ")}, which Doc Detective 5.0 removes. Remove ${removed.length > 1 ? "them" : "it"}, which works today.`);
+    }
+    if (surface.app != null && surface.workingDirectory === ".") {
+      messages.push(`An app in ${where} sets \`workingDirectory: "."\`, which 4.x tolerates and Doc Detective 5.0 fails. Remove it, which works today.`);
+    }
+  }
+  const zeroTimeouts = [
+    ...["runShell", "runCode", "goTo", "httpRequest"].filter((action) => step[action]?.timeout === 0),
+    ...starts.some((s) => s.timeout === 0) ? ["startSurface"] : []
+  ];
+  for (const action of zeroTimeouts) {
+    messages.push(`A \`${action}\` step in ${where} sets \`timeout: 0\`, ${EXIT_2} on \`runShell\`, \`runCode\`, \`goTo\`, \`httpRequest\`, and \`startSurface\` processes and apps. Remove \`timeout\` for the default, or set it to 1 or more, which works today. Locator and wait timeouts can still be 0.`);
+  }
+  for (const key of negatives(step)) {
+    messages.push(`A step in ${where} has a negative \`${key}\`, ${EXIT_2}. Use a positive value, which works today.`);
+  }
+  if (step.screenshot === false) {
+    messages.push(`A \`screenshot: false\` step in ${where} takes a screenshot today, and Doc Detective 5.0 skips it. To keep the screenshot, use \`screenshot: true\`, which works today.`);
+  }
+  const find = step.find && typeof step.find === "object" ? step.find : {};
+  const click = find.click;
+  if (typeof click === "string" && !["left", "right", "middle"].includes(click) || click && typeof click === "object" && Object.keys(click).some((key) => key !== "button" && key !== "duration")) {
+    messages.push(`A \`find.click\` in ${where} isn't \`true\`, \`false\`, a button, or \`{button, duration}\`, ${EXIT_2}. Use \`click: true\` to click the found element, or a separate \`click\` step, which works today.`);
+  }
+  if (find.type && typeof find.type === "object" && LOCATORS.some((key) => key in find.type)) {
+    messages.push(`A \`find.type\` in ${where} sets its own locator, ${EXIT_2}. Move it to a separate \`type\` step, which works today.`);
+  }
+  for (const action of ["goTo", "httpRequest"]) {
+    const url = typeof step[action] === "string" ? step[action] : step[action]?.url;
+    if (typeof url === "string" && !/^(https?:\/\/|\/)/.test(url) && !/^\$[A-Za-z0-9_]+$/.test(url)) {
+      offend(offenders, `${action} URL`, url, (first) => `A \`${action}\` URL in ${where} (${first}) doesn't start with \`http://\`, \`https://\`, or \`/\`, and isn't a whole \`$VAR\`, ${EXIT_2}. Put the whole URL in one variable, which works today.`);
+    }
+  }
+  for (const action of ["saveCookie", "loadCookie"]) {
+    const value = step[action];
+    if (typeof value === "string" && value.includes("/") && !value.endsWith(".txt")) {
+      offend(offenders, action, value, (first) => `A \`${action}\` in ${where} (${first}) has a \`/\` but doesn't end in \`.txt\`, ${EXIT_2}. End a file path in \`.txt\`, which works today.`);
+    }
+  }
+  return messages;
+}
+function specWarnings(resolvedTests) {
+  const messages = [];
+  for (const spec of resolvedTests?.specs ?? []) {
+    const file = spec.contentPath;
+    const where = typeof file === "string" ? `'${import_node_path31.default.isAbsolute(file) ? import_node_path31.default.relative(process.cwd(), file) : file}'` : "a spec";
+    const offenders = /* @__PURE__ */ new Map();
+    for (const test of spec.tests ?? []) {
+      messages.push(...testWarnings(test, where));
+      for (const context of test.contexts ?? []) {
+        for (const step of context.steps ?? [])
+          messages.push(...stepWarnings(step, where, offenders));
+      }
+    }
+    for (const { values, message } of offenders.values()) {
+      const [first] = values;
+      messages.push(message(values.size > 1 ? `\`${first}\` and ${values.size - 1} more` : `\`${first}\``));
+    }
+  }
+  return [...new Set(messages)];
+}
+
+// dist/core/index.js
 var supportMessage = `
 ##########################################################################
 # Thanks for using Doc Detective! If this project was helpful to you,    #
@@ -25604,6 +26051,7 @@ async function runTestsAndReport(config, options) {
     config = { ...resolvedTests.config || {}, ...config || {} };
     resolvedTests.config = config;
   }
+  const callerLogLevel = config?.logLevel;
   if (config.dryRun) {
     config.logLevel = "silent";
     if (resolvedTests)
@@ -25635,6 +26083,12 @@ async function runTestsAndReport(config, options) {
       log(config, "warning", "Couldn't resolve any tests.");
       return null;
     }
+    const upgradeLogLevel = config.dryRun ? legacyEnv(process.env).config?.logLevel ?? callerLogLevel : effectiveConfig.logLevel;
+    try {
+      warnUpgrade(specWarnings(resolvedTests), upgradeLogLevel);
+    } catch (error) {
+      log(effectiveConfig, "debug", `Couldn't check specs for Doc Detective 5.0 changes: ${error?.message || error}`);
+    }
     const resolvedConfig = resolvedTests.config;
     if (!resolvedConfig.dryRun && (willRunViaApi || runNeedsAvailableApps(resolvedTests.specs))) {
       resolvedConfig.environment.apps = await getAvailableApps({ config: resolvedConfig });