dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-browser-qa/lib/chrome.js

@@ -0,0 +1,466 @@
+/**
+ * Chrome/Chromium detection and a short-lived headless session.
+ *
+ * Every run gets its own temp `--user-data-dir` and `--remote-debugging-port=0`
+ * (the port is read back from `DevToolsActivePort`), so it never touches the
+ * user's browsing profile. `close()` always kills the browser and removes the
+ * profile; an `exit` guard force-kills sessions if the host process goes away
+ * for any reason. Only Node built-ins are used.
+ */
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+
+import { Cdp } from "./cdp.js";
+
+export const CHROME_ARGS = Object.freeze([
+  "--headless=new",
+  "--disable-gpu",
+  "--hide-scrollbars",
+  "--no-first-run",
+  "--no-default-browser-check",
+  "--disable-extensions",
+  "--disable-background-networking",
+  "--disable-background-timer-throttling",
+  "--disable-renderer-backgrounding",
+  "--disable-sync",
+  "--disable-default-apps",
+  "--disable-component-update",
+  "--mute-audio",
+  "--force-device-scale-factor=1",
+  "--allow-file-access-from-files",
+  "--remote-allow-origins=*",
+]);
+
+const VERSION_CACHE_MS = 5 * 60_000;
+const versionCache = new Map();
+const activeSessions = new Set();
+let exitGuardInstalled = false;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/* ------------------------------------------------------------------ */
+/* detection                                                           */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Ordered candidate executables: CHROME_PATH, installed Chrome builds, then
+ * Edge (Chromium, same DevTools protocol) as a fallback.
+ */
+export function candidatePaths(env = process.env, platform = process.platform) {
+  const candidates = [];
+  const add = (file, kind, source) => {
+    if (typeof file !== "string") return;
+    const cleaned = file.trim().replace(/^["']+|["']+$/gu, "");
+    if (cleaned.length === 0) return;
+    let resolved;
+    try {
+      resolved = path.resolve(cleaned);
+    } catch {
+      return;
+    }
+    if (candidates.some((candidate) => candidate.path.toLowerCase() === resolved.toLowerCase())) return;
+    candidates.push({ path: resolved, kind, source });
+  };
+
+  add(env.CHROME_PATH, "custom", "CHROME_PATH");
+  if (platform === "win32") {
+    const programFiles = env.ProgramFiles || "C:\\Program Files";
+    const programFilesX86 = env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
+    const localAppData = env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    add(path.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"), "chrome", "Program Files");
+    add(path.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"), "chrome", "Program Files (x86)");
+    add(path.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"), "chrome", "LOCALAPPDATA");
+    add(path.join(localAppData, "Google", "Chrome SxS", "Application", "chrome.exe"), "chrome", "Canary");
+    add(path.join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"), "edge", "Edge");
+    add(path.join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe"), "edge", "Edge");
+    add(path.join(localAppData, "Microsoft", "Edge", "Application", "msedge.exe"), "edge", "Edge");
+  } else if (platform === "darwin") {
+    add("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "chrome", "Applications");
+    add(path.join(os.homedir(), "Applications", "Google Chrome.app", "Contents", "MacOS", "Google Chrome"), "chrome", "~/Applications");
+    add("/Applications/Chromium.app/Contents/MacOS/Chromium", "chromium", "Applications");
+  } else {
+    for (const file of [
+      "/usr/bin/google-chrome",
+      "/usr/bin/google-chrome-stable",
+      "/usr/bin/chromium",
+      "/usr/bin/chromium-browser",
+      "/snap/bin/chromium",
+    ]) {
+      add(file, "chrome", "system");
+    }
+  }
+  return candidates;
+}
+
+export function detectChrome(options = {}) {
+  const candidates = candidatePaths(options.env, options.platform);
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate.path).isFile()) {
+        return {
+          found: true,
+          path: candidate.path,
+          kind: candidate.kind,
+          source: candidate.source,
+          candidates: candidates.map((entry) => entry.path),
+        };
+      }
+    } catch {
+      /* not installed / not readable */
+    }
+  }
+  return { found: false, path: null, kind: null, source: null, candidates: candidates.map((entry) => entry.path) };
+}
+
+export function parseBrowserInfo(info = {}) {
+  const browser = typeof info?.Browser === "string" ? info.Browser : "";
+  const slash = browser.indexOf("/");
+  return {
+    browser,
+    product: slash >= 0 ? browser.slice(0, slash) : browser || null,
+    version: slash >= 0 ? browser.slice(slash + 1) : null,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* low-level helpers                                                   */
+/* ------------------------------------------------------------------ */
+
+function httpGetJson(port, pathname, timeoutMs = 2_000) {
+  return new Promise((resolve, reject) => {
+    const request = http.get(
+      { host: "127.0.0.1", port, path: pathname, timeout: timeoutMs, headers: { accept: "application/json" } },
+      (response) => {
+        const chunks = [];
+        let size = 0;
+        response.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > 2_000_000) {
+            request.destroy(new Error(`DevTools response too large from ${pathname}`));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        response.on("end", () => {
+          try {
+            resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+          } catch (error) {
+            reject(new Error(`invalid DevTools JSON from ${pathname}: ${errorMessage(error)}`));
+          }
+        });
+        response.on("error", reject);
+      },
+    );
+    request.on("timeout", () => request.destroy(new Error(`DevTools endpoint timeout: ${pathname}`)));
+    request.on("error", reject);
+  });
+}
+
+function spawnChrome(executablePath, profileDir) {
+  const state = { child: null, spawnError: null };
+  const child = spawn(
+    executablePath,
+    [...CHROME_ARGS, `--user-data-dir=${profileDir}`, "--remote-debugging-port=0", "about:blank"],
+    { stdio: "ignore", windowsHide: true },
+  );
+  state.child = child;
+  child.once("error", (error) => {
+    state.spawnError = new Error(`cannot start ${executablePath}: ${errorMessage(error)}`);
+  });
+  return state;
+}
+
+async function waitForDevToolsPort(profileDir, state, timeoutMs) {
+  const file = path.join(profileDir, "DevToolsActivePort");
+  const deadline = Date.now() + Math.max(1_000, timeoutMs);
+  while (Date.now() < deadline) {
+    if (state.spawnError) throw state.spawnError;
+    if (state.child && state.child.exitCode !== null) {
+      throw new Error(`Chrome exited before DevTools was ready (code ${state.child.exitCode})`);
+    }
+    try {
+      const text = await fsp.readFile(file, "utf8");
+      const lines = text.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+      const port = Number(lines[0]);
+      if (Number.isInteger(port) && port > 0) return { port, browserWebSocketPath: lines[1] ?? "" };
+    } catch {
+      /* not written yet */
+    }
+    await sleep(80);
+  }
+  throw new Error(`Chrome did not expose a DevTools port within ${Math.round(timeoutMs)} ms`);
+}
+
+async function waitForVersion(port, deadline) {
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      const info = await httpGetJson(port, "/json/version", 1_500);
+      if (info && typeof info === "object") return info;
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(80);
+  }
+  throw new Error(`Chrome DevTools endpoint did not respond: ${errorMessage(lastError ?? new Error("timeout"))}`);
+}
+
+function forceKillSync(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  try {
+    if (process.platform === "win32") {
+      spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: 5_000 });
+    } else {
+      try {
+        process.kill(-pid, "SIGKILL");
+      } catch {
+        process.kill(pid, "SIGKILL");
+      }
+    }
+  } catch {
+    /* already gone */
+  }
+}
+
+async function terminateChild(state) {
+  const child = state?.child;
+  if (!child) return;
+  if (state.spawnError) {
+    try {
+      child.kill();
+    } catch {
+      /* never started */
+    }
+    return;
+  }
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  await new Promise((resolve) => {
+    let finished = false;
+    let forceTimer = null;
+    let safetyTimer = null;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(forceTimer);
+      clearTimeout(safetyTimer);
+      resolve();
+    };
+    child.once("exit", finish);
+    try {
+      child.kill();
+    } catch {
+      /* ignore */
+    }
+    if (child.exitCode !== null) {
+      finish();
+      return;
+    }
+    forceTimer = setTimeout(() => forceKillSync(child.pid), 1_500);
+    safetyTimer = setTimeout(finish, 5_000);
+    if (typeof forceTimer.unref === "function") forceTimer.unref();
+    if (typeof safetyTimer.unref === "function") safetyTimer.unref();
+  });
+}
+
+async function removeProfileDir(dir) {
+  if (typeof dir !== "string" || dir.length === 0) return null;
+  try {
+    await fsp.rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 120 });
+    return null;
+  } catch (error) {
+    return `temp profile not fully removed: ${errorMessage(error)}`;
+  }
+}
+
+function installExitGuard() {
+  if (exitGuardInstalled) return;
+  exitGuardInstalled = true;
+  process.once("exit", () => {
+    for (const session of activeSessions) {
+      try {
+        const pid = session?.state?.child?.pid;
+        if (Number.isInteger(pid) && session.state.child.exitCode === null) forceKillSync(pid);
+      } catch {
+        /* ignore */
+      }
+      try {
+        if (typeof session?.profileDir === "string") fs.rmSync(session.profileDir, { recursive: true, force: true, maxRetries: 2 });
+      } catch {
+        /* best effort on process exit */
+      }
+    }
+    activeSessions.clear();
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* one-shot version probe                                              */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Launch a throwaway headless browser, read `/json/version`, kill it. Used by
+ * the status action; the answer is cached for five minutes per executable.
+ */
+export async function probeChrome(executablePath, options = {}) {
+  const pathKey = String(executablePath ?? "");
+  if (pathKey.length === 0) throw new Error("Chrome path is empty");
+  const cached = versionCache.get(pathKey);
+  if (cached && Date.now() - cached.at < VERSION_CACHE_MS) {
+    return { ...cached.info, found: true, path: pathKey, cached: true };
+  }
+  installExitGuard();
+  const profileDir = await fsp.mkdtemp(path.join(os.tmpdir(), "dsh-browser-qa-probe-"));
+  const state = spawnChrome(pathKey, profileDir);
+  const guardEntry = { state, profileDir };
+  activeSessions.add(guardEntry);
+  const timeoutMs = Math.max(2_000, Math.min(20_000, Number(options.timeoutMs) || 8_000));
+  const deadline = Date.now() + timeoutMs;
+  try {
+    const portInfo = await waitForDevToolsPort(profileDir, state, Math.max(1_000, deadline - Date.now()));
+    const info = await waitForVersion(portInfo.port, deadline);
+    const parsed = parseBrowserInfo(info);
+    const result = {
+      found: true,
+      path: pathKey,
+      kind: options.kind ?? "chrome",
+      product: parsed.product,
+      version: parsed.version,
+      browser: parsed.browser || null,
+      protocolVersion: info?.["Protocol-Version"] ?? null,
+      userAgent: info?.["User-Agent"] ?? null,
+    };
+    versionCache.set(pathKey, { at: Date.now(), info: result });
+    return { ...result, cached: false };
+  } finally {
+    activeSessions.delete(guardEntry);
+    await terminateChild(state);
+    await removeProfileDir(profileDir);
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* long-lived (per tool call) session                                  */
+/* ------------------------------------------------------------------ */
+
+export class ChromeSession {
+  static async start(options = {}) {
+    const executablePath = options.executablePath;
+    if (typeof executablePath !== "string" || executablePath.length === 0) {
+      throw new Error("Chrome executable path is empty");
+    }
+    installExitGuard();
+    const timeoutMs = Math.max(2_000, Math.min(25_000, Number(options.timeoutMs) || 15_000));
+    const profileDir = await fsp.mkdtemp(path.join(os.tmpdir(), "dsh-browser-qa-"));
+    const state = spawnChrome(executablePath, profileDir);
+    const session = new ChromeSession({ executablePath, kind: options.kind ?? "chrome", profileDir, state });
+    activeSessions.add(session);
+    try {
+      await session.boot(timeoutMs);
+      return session;
+    } catch (error) {
+      await session.close();
+      throw error;
+    }
+  }
+
+  constructor({ executablePath, kind, profileDir, state }) {
+    this.executablePath = executablePath;
+    this.kind = kind;
+    this.profileDir = profileDir;
+    this.state = state;
+    this.port = null;
+    this.browserWebSocketPath = "";
+    this.versionInfo = null;
+    this.product = null;
+    this.version = null;
+    this.protocolVersion = null;
+    this.cdp = null;
+    this.cleanupWarning = null;
+    this.closed = false;
+  }
+
+  chromeInfo() {
+    return {
+      path: this.executablePath,
+      kind: this.kind,
+      product: this.product,
+      version: this.version,
+      protocolVersion: this.protocolVersion,
+    };
+  }
+
+  async boot(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const portInfo = await waitForDevToolsPort(this.profileDir, this.state, Math.max(1_000, deadline - Date.now()));
+    this.port = portInfo.port;
+    this.browserWebSocketPath = portInfo.browserWebSocketPath;
+    this.versionInfo = await waitForVersion(this.port, deadline);
+    const parsed = parseBrowserInfo(this.versionInfo);
+    this.product = parsed.product;
+    this.version = parsed.version;
+    this.protocolVersion = this.versionInfo?.["Protocol-Version"] ?? null;
+    versionCache.set(this.executablePath, {
+      at: Date.now(),
+      info: {
+        found: true,
+        path: this.executablePath,
+        kind: this.kind,
+        product: this.product,
+        version: this.version,
+        browser: parsed.browser || null,
+        protocolVersion: this.protocolVersion,
+        userAgent: this.versionInfo?.["User-Agent"] ?? null,
+      },
+    });
+    const target = await this.pageTarget(deadline);
+    const connectTimeout = Math.max(1_000, Math.min(10_000, deadline - Date.now()));
+    this.cdp = await new Cdp(target.webSocketDebuggerUrl).connect(connectTimeout);
+    return this;
+  }
+
+  async pageTarget(deadline) {
+    let lastError = null;
+    while (Date.now() < deadline) {
+      if (this.state.spawnError) throw this.state.spawnError;
+      try {
+        const targets = await httpGetJson(this.port, "/json/list", 1_500);
+        if (Array.isArray(targets)) {
+          const page = targets.find(
+            (target) => target && target.type === "page" && typeof target.webSocketDebuggerUrl === "string" && target.webSocketDebuggerUrl.length > 0,
+          );
+          if (page) return page;
+        }
+      } catch (error) {
+        lastError = error;
+      }
+      await sleep(80);
+    }
+    throw new Error(`Chrome did not expose a debuggable page target: ${errorMessage(lastError ?? new Error("timeout"))}`);
+  }
+
+  /** Kill the browser and delete the temp profile. Safe to call twice. */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      this.cdp?.close();
+    } catch {
+      /* ignore */
+    }
+    this.cdp = null;
+    activeSessions.delete(this);
+    await terminateChild(this.state);
+    const warning = await removeProfileDir(this.profileDir);
+    this.cleanupWarning = warning;
+  }
+}