Extract shared detectBrowser() and bound findCftExecutable walk

The browser detection priority chain (QUARTO_CHROMIUM → chrome-headless-shell
→ system Chrome) was duplicated in `getBrowserExecutablePath()` and
`detectChromeForCheck()`. Extract the shared logic into `detectBrowser()` in
puppeteer.ts, keeping only the context-specific legacy fallbacks in each
caller.

Also add a known-path check in `findCftExecutable` before falling back to
`walkSync`, and bound the fallback walk to `maxDepth: 3`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cderv

src/command/check/check.ts

@@ -31,13 +31,7 @@ import { typstBinaryPath } from "../../core/typst.ts";
 import { quartoCacheDir } from "../../core/appdirs.ts";
 import { isWindows } from "../../deno_ral/platform.ts";
 import { makeStringEnumTypeEnforcer } from "../../typing/dynamic.ts";
-import { findChrome } from "../../core/puppeteer.ts";
-import { safeExistsSync } from "../../core/path.ts";
-import {
-  chromeHeadlessShellExecutablePath,
-  chromeHeadlessShellInstallDir,
-  readInstalledVersion,
-} from "../../tools/impl/chrome-headless-shell.ts";
+import { detectBrowser } from "../../core/puppeteer.ts";
 import { executionEngines } from "../../execute/engine.ts";
 
 export function getTargets(): readonly string[] {
@@ -538,49 +532,18 @@ interface ChromeCheckInfo {
 }
 
 async function detectChromeForCheck(): Promise<ChromeCheckInfo> {
-  const result: ChromeCheckInfo = {};
-
-  // 1. QUARTO_CHROMIUM environment variable
-  const envPath = Deno.env.get("QUARTO_CHROMIUM");
-  if (envPath) {
-    if (safeExistsSync(envPath)) {
-      result.detected = {
-        label: "Chrome from QUARTO_CHROMIUM",
-        path: envPath,
-        source: "QUARTO_CHROMIUM",
-      };
-      return result;
-    }
-    result.warning =
-      `QUARTO_CHROMIUM is set to ${envPath} but the path does not exist.`;
-  }
+  const detection = await detectBrowser();
 
-  // 2. Chrome headless shell installed by Quarto
-  const chromeHsPath = chromeHeadlessShellExecutablePath();
-  if (chromeHsPath !== undefined) {
-    const version = readInstalledVersion(chromeHeadlessShellInstallDir());
-    result.detected = {
-      label: "Chrome Headless Shell installed by Quarto",
-      path: chromeHsPath,
-      source: "quarto-chrome-headless-shell",
-      version,
-    };
-    return result;
+  if (detection.detected) {
+    return { detected: detection.detected };
   }
 
-  // 3. System Chrome
-  const chromeDetected = await findChrome();
-  if (chromeDetected.path !== undefined) {
-    result.detected = {
-      label: "Chrome found on system",
-      path: chromeDetected.path,
-      source: chromeDetected.source ?? "system",
-      displaySource: chromeDetected.source,
-    };
-    return result;
+  const result: ChromeCheckInfo = {};
+  if (detection.warning) {
+    result.warning = detection.warning;
   }
 
-  // 4. Legacy chromium installed by Quarto
+  // Legacy: chromium installed by Quarto
   const chromiumTool = installableTool("chromium");
   if (chromiumTool && await chromiumTool.installed()) {
     let path: string | undefined;
@@ -594,9 +557,7 @@ async function detectChromeForCheck(): Promise<ChromeCheckInfo> {
       source: "quarto",
       version,
     };
-    return result;
   }
 
-  // 5. Not found
   return result;
 }

src/core/puppeteer.ts

@@ -12,7 +12,11 @@ import { UnreachableError } from "./lib/error.ts";
 import { quartoDataDir } from "./appdirs.ts";
 import { isMac, isWindows } from "../deno_ral/platform.ts";
 import puppeteer from "puppeteer";
-import { chromeHeadlessShellExecutablePath } from "../tools/impl/chrome-headless-shell.ts";
+import {
+  chromeHeadlessShellExecutablePath,
+  chromeHeadlessShellInstallDir,
+  readInstalledVersion,
+} from "../tools/impl/chrome-headless-shell.ts";
 
 // deno-lint-ignore no-explicit-any
 // let puppeteerImport: any = undefined;
@@ -273,59 +277,101 @@ export async function findChrome(): Promise<ChromeInfo> {
   return { path: path, source: source };
 }
 
-export async function getBrowserExecutablePath() {
-  // Cook up a new instance
-  const browserFetcher = await fetcher();
-  const availableRevisions = await browserFetcher.localRevisions();
+export interface BrowserDetection {
+  path: string;
+  source: string;
+  label: string;
+  version?: string;
+  displaySource?: string;
+}
 
-  let executablePath: string | undefined = undefined;
+export interface BrowserDetectionResult {
+  detected?: BrowserDetection;
+  warning?: string;
+}
 
-  // Priority 1: QUARTO_CHROMIUM env var
+/**
+ * Detect available Chrome/Chromium browser using the standard priority order:
+ * 1. QUARTO_CHROMIUM env var
+ * 2. Quarto-installed chrome-headless-shell
+ * 3. System Chrome/Edge
+ *
+ * Does NOT check legacy fallbacks (puppeteer revisions, chromium tool) —
+ * callers handle those based on their context.
+ */
+export async function detectBrowser(): Promise<BrowserDetectionResult> {
+  const result: BrowserDetectionResult = {};
+
+  // 1. QUARTO_CHROMIUM environment variable
   const envPath = Deno.env.get("QUARTO_CHROMIUM");
   if (envPath) {
     if (safeExistsSync(envPath)) {
-      debug(`[CHROMIUM] Using QUARTO_CHROMIUM: ${envPath}`);
-      executablePath = envPath;
-    } else {
-      debug(`[CHROMIUM] QUARTO_CHROMIUM is set to ${envPath} but the path does not exist. Searching for another browser.`);
+      result.detected = {
+        path: envPath,
+        source: "QUARTO_CHROMIUM",
+        label: "Chrome from QUARTO_CHROMIUM",
+      };
+      return result;
     }
+    result.warning =
+      `QUARTO_CHROMIUM is set to ${envPath} but the path does not exist.`;
   }
 
-  // Priority 2: Quarto-installed chrome-headless-shell
-  if (executablePath === undefined) {
-    executablePath = chromeHeadlessShellExecutablePath();
-    if (executablePath) {
-      debug(`[CHROMIUM] Using chrome-headless-shell: ${executablePath}`);
-    }
+  // 2. Quarto-installed chrome-headless-shell
+  const chromeHsPath = chromeHeadlessShellExecutablePath();
+  if (chromeHsPath !== undefined) {
+    const version = readInstalledVersion(chromeHeadlessShellInstallDir());
+    result.detected = {
+      path: chromeHsPath,
+      source: "quarto-chrome-headless-shell",
+      label: "Chrome Headless Shell installed by Quarto",
+      version,
+    };
+    return result;
   }
 
-  // Priority 3: System Chrome/Edge
-  if (executablePath === undefined) {
-    const chromeInfo = await findChrome();
-    if (chromeInfo.path) {
-      debug(`[CHROMIUM] Using system Chrome from ${chromeInfo.source}: ${chromeInfo.path}`);
-      executablePath = chromeInfo.path;
-    }
+  // 3. System Chrome/Edge
+  const chromeInfo = await findChrome();
+  if (chromeInfo.path) {
+    result.detected = {
+      path: chromeInfo.path,
+      source: chromeInfo.source ?? "system",
+      label: "Chrome found on system",
+      displaySource: chromeInfo.source,
+    };
+    return result;
+  }
+
+  return result;
+}
+
+export async function getBrowserExecutablePath() {
+  const detection = await detectBrowser();
+
+  if (detection.detected) {
+    debug(`[CHROMIUM] Using ${detection.detected.label}: ${detection.detected.path}`);
+    return detection.detected.path;
+  }
+
+  if (detection.warning) {
+    debug(`[CHROMIUM] ${detection.warning} Searching for another browser.`);
   }
 
-  // Priority 4: Legacy puppeteer-managed Chromium revisions
-  if (executablePath === undefined && availableRevisions.length > 0) {
-    // get the latest available revision
+  // Legacy: puppeteer-managed Chromium revisions
+  const browserFetcher = await fetcher();
+  const availableRevisions = await browserFetcher.localRevisions();
+  if (availableRevisions.length > 0) {
     availableRevisions.sort((a: string, b: string) => Number(b) - Number(a));
     const revision = availableRevisions[0];
     const revisionInfo = browserFetcher.revisionInfo(revision);
-    executablePath = revisionInfo.executablePath;
-  }
-
-  if (executablePath === undefined) {
-    error("Chrome not found");
-    info(
-      "\nNo Chrome or Chromium installation was detected.\n\nPlease run 'quarto install chrome-headless-shell' to install a headless browser.\n",
-    );
-    throw new Error();
+    return revisionInfo.executablePath;
   }
 
-  return executablePath;
+  error("Chrome not found");
+  info(
+    "\nNo Chrome or Chromium installation was detected.\n\nPlease run 'quarto install chrome-headless-shell' to install a headless browser.\n",
+  );
+  throw new Error();
 }
 
 async function fetchBrowser() {

src/tools/impl/chrome-for-testing.ts

@@ -8,8 +8,8 @@
  * Copyright (C) 2026 Posit Software, PBC
  */
 
-import { basename } from "../../deno_ral/path.ts";
-import { safeChmodSync, safeRemoveSync, walkSync } from "../../deno_ral/fs.ts";
+import { basename, join } from "../../deno_ral/path.ts";
+import { existsSync, safeChmodSync, safeRemoveSync, walkSync } from "../../deno_ral/fs.ts";
 import { debug } from "../../deno_ral/log.ts";
 import { arch, isWindows, os } from "../../deno_ral/platform.ts";
 import { unzip } from "../../core/zip.ts";
@@ -133,7 +133,19 @@ export function findCftExecutable(
 ): string | undefined {
   const target = isWindows ? `${binaryName}.exe` : binaryName;
 
-  for (const entry of walkSync(extractedDir, { includeDirs: false })) {
+  // CfT zips extract to {binaryName}-{platform}/{target}
+  try {
+    const { platform } = detectCftPlatform();
+    const knownPath = join(extractedDir, `${binaryName}-${platform}`, target);
+    if (existsSync(knownPath)) {
+      return knownPath;
+    }
+  } catch {
+    // Platform detection failed — fall through to walk
+  }
+
+  // Fallback: bounded walk for unexpected directory structures
+  for (const entry of walkSync(extractedDir, { includeDirs: false, maxDepth: 3 })) {
     if (basename(entry.path) === target) {
       return entry.path;
     }