browser-pilot 0.0.15 → 0.0.16

package/dist/providers.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,17 +17,31 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/providers/index.ts
 var providers_exports = {};
 __export(providers_exports, {
   BrowserBaseProvider: () => BrowserBaseProvider,
+  BrowserEndpointResolutionError: () => BrowserEndpointResolutionError,
   BrowserlessProvider: () => BrowserlessProvider,
   GenericProvider: () => GenericProvider,
+  buildLocalBrowserScanTargets: () => buildLocalBrowserScanTargets,
   createProvider: () => createProvider,
+  discoverLocalBrowsers: () => discoverLocalBrowsers,
   discoverTargets: () => discoverTargets,
-  getBrowserWebSocketUrl: () => getBrowserWebSocketUrl
+  getBrowserWebSocketUrl: () => getBrowserWebSocketUrl,
+  parseDevToolsActivePortFile: () => parseDevToolsActivePortFile,
+  resolveBrowserEndpoint: () => resolveBrowserEndpoint,
+  resolveChromeUserDataDirs: () => resolveChromeUserDataDirs
 });
 module.exports = __toCommonJS(providers_exports);
 
@@ -217,6 +233,619 @@ async function getBrowserWebSocketUrl(host = "localhost:9222") {
   return info.webSocketDebuggerUrl;
 }
 
+// src/utils/json.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/cdp/protocol.ts
+var CDPError = class extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "CDPError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+};
+
+// src/cdp/transport.ts
+function createTransport(wsUrl, options = {}) {
+  const { timeout = 3e4 } = options;
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(new Error(`WebSocket connection timeout after ${timeout}ms`));
+    }, timeout);
+    const ws = new WebSocket(wsUrl);
+    const messageHandlers = [];
+    const closeHandlers = [];
+    const errorHandlers = [];
+    ws.addEventListener("open", () => {
+      clearTimeout(timeoutId);
+      const transport = {
+        send(message) {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(message);
+          } else {
+            throw new Error(
+              `Cannot send message, WebSocket is ${getReadyStateString(ws.readyState)}`
+            );
+          }
+        },
+        async close() {
+          return new Promise((resolveClose) => {
+            if (ws.readyState === WebSocket.CLOSED) {
+              resolveClose();
+              return;
+            }
+            let settled = false;
+            let fallbackTimer;
+            const finish = () => {
+              if (settled) return;
+              settled = true;
+              if (fallbackTimer) clearTimeout(fallbackTimer);
+              ws.removeEventListener("close", onClose);
+              resolveClose();
+            };
+            const onClose = () => {
+              finish();
+            };
+            ws.addEventListener("close", onClose);
+            try {
+              if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                ws.close();
+              }
+            } catch {
+              finish();
+              return;
+            }
+            fallbackTimer = setTimeout(finish, 200);
+          });
+        },
+        onMessage(handler) {
+          messageHandlers.push(handler);
+        },
+        onClose(handler) {
+          closeHandlers.push(handler);
+        },
+        onError(handler) {
+          errorHandlers.push(handler);
+        }
+      };
+      resolve(transport);
+    });
+    ws.addEventListener("message", (event) => {
+      const data = typeof event.data === "string" ? event.data : String(event.data);
+      for (const handler of messageHandlers) {
+        handler(data);
+      }
+    });
+    ws.addEventListener("close", () => {
+      for (const handler of closeHandlers) {
+        handler();
+      }
+    });
+    ws.addEventListener("error", (_event) => {
+      clearTimeout(timeoutId);
+      const error = new Error("WebSocket connection error");
+      for (const handler of errorHandlers) {
+        handler(error);
+      }
+      reject(error);
+    });
+  });
+}
+function getReadyStateString(state) {
+  switch (state) {
+    case WebSocket.CONNECTING:
+      return "CONNECTING";
+    case WebSocket.OPEN:
+      return "OPEN";
+    case WebSocket.CLOSING:
+      return "CLOSING";
+    case WebSocket.CLOSED:
+      return "CLOSED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+// src/cdp/client.ts
+async function createCDPClient(wsUrl, options = {}) {
+  const { timeout = 3e4 } = options;
+  const transport = await createTransport(wsUrl, { timeout });
+  return buildCDPClient(transport, options);
+}
+function buildCDPClient(transport, options = {}) {
+  const { debug = false, timeout = 3e4 } = options;
+  let messageId = 0;
+  let currentSessionId;
+  let connected = true;
+  const pending = /* @__PURE__ */ new Map();
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const anyEventHandlers = /* @__PURE__ */ new Set();
+  transport.onMessage((raw) => {
+    let msg;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isRecord(parsed)) {
+        if (debug) console.error("[CDP] Ignoring non-object message:", raw);
+        return;
+      }
+      if ("id" in parsed && typeof parsed["id"] === "number") {
+        msg = parsed;
+      } else if ("method" in parsed && typeof parsed["method"] === "string") {
+        msg = parsed;
+      } else {
+        if (debug) console.error("[CDP] Ignoring invalid message shape:", raw);
+        return;
+      }
+    } catch {
+      if (debug) console.error("[CDP] Failed to parse message:", raw);
+      return;
+    }
+    if (debug) {
+      console.log("[CDP] <--", JSON.stringify(msg, null, 2).slice(0, 500));
+    }
+    if ("id" in msg && typeof msg.id === "number") {
+      const response = msg;
+      const request = pending.get(response.id);
+      if (request) {
+        pending.delete(response.id);
+        clearTimeout(request.timer);
+        if (response.error) {
+          const error = typeof response.error === "string" ? { code: -32e3, message: response.error } : response.error;
+          request.reject(new CDPError(error));
+        } else {
+          request.resolve(response.result);
+        }
+      }
+      return;
+    }
+    if ("method" in msg) {
+      const event = msg;
+      const params = event.params ?? {};
+      for (const handler of anyEventHandlers) {
+        try {
+          handler(event.method, params);
+        } catch (e) {
+          if (debug) console.error("[CDP] Error in any-event handler:", e);
+        }
+      }
+      const handlers = eventHandlers.get(event.method);
+      if (handlers) {
+        for (const handler of handlers) {
+          try {
+            handler(params);
+          } catch (e) {
+            if (debug) console.error(`[CDP] Error in handler for ${event.method}:`, e);
+          }
+        }
+      }
+    }
+  });
+  transport.onClose(() => {
+    connected = false;
+    for (const [id, request] of pending) {
+      clearTimeout(request.timer);
+      request.reject(new Error("WebSocket connection closed"));
+      pending.delete(id);
+    }
+  });
+  transport.onError((error) => {
+    if (debug) console.error("[CDP] Transport error:", error);
+  });
+  const client = {
+    async send(method, params, sessionId) {
+      if (!connected) {
+        throw new Error("CDP client is not connected");
+      }
+      const id = ++messageId;
+      const effectiveSessionId = sessionId === null ? void 0 : sessionId ?? currentSessionId;
+      const request = { id, method };
+      if (params !== void 0) {
+        request.params = params;
+      }
+      if (effectiveSessionId !== void 0) {
+        request.sessionId = effectiveSessionId;
+      }
+      const message = JSON.stringify(request);
+      if (debug) {
+        console.log("[CDP] -->", message.slice(0, 500));
+      }
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`CDP command ${method} timed out after ${timeout}ms`));
+        }, timeout);
+        pending.set(id, {
+          resolve,
+          reject,
+          method,
+          timer
+        });
+        try {
+          transport.send(message);
+        } catch (e) {
+          pending.delete(id);
+          clearTimeout(timer);
+          reject(e);
+        }
+      });
+    },
+    on(event, handler) {
+      let handlers = eventHandlers.get(event);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Set();
+        eventHandlers.set(event, handlers);
+      }
+      handlers.add(handler);
+    },
+    off(event, handler) {
+      const handlers = eventHandlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          eventHandlers.delete(event);
+        }
+      }
+    },
+    onAny(handler) {
+      anyEventHandlers.add(handler);
+    },
+    offAny(handler) {
+      anyEventHandlers.delete(handler);
+    },
+    async close() {
+      connected = false;
+      await transport.close();
+    },
+    async attachToTarget(targetId) {
+      const result = await this.send("Target.attachToTarget", {
+        targetId,
+        flatten: true
+      });
+      currentSessionId = result.sessionId;
+      return result.sessionId;
+    },
+    get sessionId() {
+      return currentSessionId;
+    },
+    setSessionId(sessionId) {
+      currentSessionId = sessionId;
+    },
+    get isConnected() {
+      return connected;
+    }
+  };
+  return client;
+}
+
+// src/providers/local-discovery.ts
+var CHANNEL_ORDER = ["stable", "beta", "dev", "canary"];
+var DEFAULT_PROBE_TIMEOUT_MS = 1e3;
+var DevToolsActivePortParseError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "DevToolsActivePortParseError";
+  }
+};
+function getRuntimeEnv() {
+  if (typeof process === "undefined") {
+    return {};
+  }
+  return process.env;
+}
+function getRuntimePlatform() {
+  if (typeof process === "undefined") {
+    return void 0;
+  }
+  return process.platform;
+}
+function normalizePlatform(platform) {
+  if (platform === "darwin" || platform === "linux" || platform === "win32") {
+    return platform;
+  }
+  throw new Error(`Unsupported platform: ${platform ?? "unknown"}`);
+}
+function trimTrailingSeparator(path) {
+  return path.replace(/[\\/]+$/, "");
+}
+function joinPath(platform, ...parts) {
+  const separator = platform === "win32" ? "\\" : "/";
+  const cleaned = parts.map((part, index) => {
+    if (index === 0) return trimTrailingSeparator(part);
+    return part.replace(/^[\\/]+/, "").replace(/[\\/]+$/, "");
+  }).filter((part) => part.length > 0);
+  return cleaned.join(separator);
+}
+function resolveHomeDir(platform, env, explicitHomeDir) {
+  if (explicitHomeDir) {
+    return explicitHomeDir;
+  }
+  if (platform === "win32") {
+    return env["USERPROFILE"] ?? env["HOME"] ?? "";
+  }
+  return env["HOME"] ?? env["USERPROFILE"] ?? "";
+}
+function toFileFailure(target, error) {
+  const errno = error?.code;
+  if (errno === "ENOENT") {
+    return {
+      ...target,
+      reason: "missing-file",
+      message: `DevToolsActivePort not found at ${target.portFile}`
+    };
+  }
+  return {
+    ...target,
+    reason: "unreadable-file",
+    message: error instanceof Error ? error.message : `Could not read DevToolsActivePort at ${target.portFile}`
+  };
+}
+function toProbeFailure(target, wsUrl, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const lowerMessage = message.toLowerCase();
+  let reason = "connection-error";
+  if (lowerMessage.includes("refused") || lowerMessage.includes("econnrefused")) {
+    reason = "connection-refused";
+  } else if (lowerMessage.includes("timeout") || lowerMessage.includes("timed out")) {
+    reason = "connection-timeout";
+  } else if (lowerMessage.includes("closed")) {
+    reason = "unexpected-close";
+  } else if (lowerMessage.includes("browser.getversion") || lowerMessage.includes("cdp") || lowerMessage.includes("protocol")) {
+    reason = "cdp-error";
+  }
+  return {
+    ...target,
+    wsUrl,
+    reason,
+    message
+  };
+}
+async function readTextFile(path) {
+  const fs = await import("fs/promises");
+  return fs.readFile(path, "utf-8");
+}
+async function probeBrowserWebSocket(wsUrl, timeoutMs) {
+  let client;
+  try {
+    client = await createCDPClient(wsUrl, { timeout: timeoutMs });
+    const version = await client.send("Browser.getVersion", void 0, null);
+    return { browserVersion: version.product };
+  } finally {
+    await client?.close().catch(() => {
+    });
+  }
+}
+var defaultDependencies = {
+  readTextFile,
+  probeBrowserWebSocket,
+  getLegacyBrowserWebSocketUrl: getBrowserWebSocketUrl
+};
+function resolveChromeUserDataDirs(options = {}) {
+  const env = options.env ?? getRuntimeEnv();
+  const platform = normalizePlatform(options.platform ?? getRuntimePlatform());
+  const homeDir = resolveHomeDir(platform, env, options.homeDir);
+  if (!homeDir) {
+    throw new Error("Could not determine home directory for local Chrome discovery");
+  }
+  switch (platform) {
+    case "darwin": {
+      const base = joinPath(platform, homeDir, "Library", "Application Support", "Google");
+      return {
+        stable: joinPath(platform, base, "Chrome"),
+        beta: joinPath(platform, base, "Chrome Beta"),
+        dev: joinPath(platform, base, "Chrome Dev"),
+        canary: joinPath(platform, base, "Chrome Canary")
+      };
+    }
+    case "linux": {
+      const configHome = env["CHROME_CONFIG_HOME"] ?? env["XDG_CONFIG_HOME"] ?? joinPath(platform, homeDir, ".config");
+      return {
+        stable: joinPath(platform, configHome, "google-chrome"),
+        beta: joinPath(platform, configHome, "google-chrome-beta"),
+        dev: joinPath(platform, configHome, "google-chrome-dev"),
+        canary: joinPath(platform, configHome, "google-chrome-canary")
+      };
+    }
+    case "win32": {
+      const localAppData = env["LOCALAPPDATA"] ?? joinPath(platform, homeDir, "AppData", "Local");
+      const base = joinPath(platform, localAppData, "Google");
+      return {
+        stable: joinPath(platform, base, "Chrome", "User Data"),
+        beta: joinPath(platform, base, "Chrome Beta", "User Data"),
+        dev: joinPath(platform, base, "Chrome Dev", "User Data"),
+        canary: joinPath(platform, base, "Chrome SxS", "User Data")
+      };
+    }
+  }
+  throw new Error(`Unsupported platform for local Chrome discovery: ${platform}`);
+}
+function buildLocalBrowserScanTargets(options = {}) {
+  const env = options.env ?? getRuntimeEnv();
+  const platform = normalizePlatform(options.platform ?? getRuntimePlatform());
+  if (options.userDataDir) {
+    return [
+      {
+        channel: options.channel ?? "custom",
+        userDataDir: options.userDataDir,
+        portFile: joinPath(platform, options.userDataDir, "DevToolsActivePort")
+      }
+    ];
+  }
+  const dirs = resolveChromeUserDataDirs({
+    platform,
+    env,
+    homeDir: options.homeDir
+  });
+  const channels = options.channel ? [options.channel] : CHANNEL_ORDER;
+  return channels.map((channel) => ({
+    channel,
+    userDataDir: dirs[channel],
+    portFile: joinPath(platform, dirs[channel], "DevToolsActivePort")
+  }));
+}
+function parseDevToolsActivePortFile(content) {
+  const lines = content.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length !== 2) {
+    throw new DevToolsActivePortParseError(
+      `Expected exactly 2 non-empty lines in DevToolsActivePort, got ${lines.length}`,
+      "malformed-file"
+    );
+  }
+  const portText = lines[0];
+  const browserPath = lines[1];
+  const port = Number.parseInt(portText, 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new DevToolsActivePortParseError(
+      `Invalid DevToolsActivePort port: ${portText}`,
+      "invalid-port"
+    );
+  }
+  if (!browserPath.startsWith("/devtools/browser/") || browserPath.includes("..") || /[?#\s\\]/u.test(browserPath)) {
+    throw new DevToolsActivePortParseError(
+      `Invalid DevToolsActivePort browser path: ${browserPath}`,
+      "invalid-path"
+    );
+  }
+  return {
+    port,
+    browserPath,
+    wsUrl: `ws://127.0.0.1:${port}${browserPath}`
+  };
+}
+async function inspectScanTarget(target, options, deps) {
+  let content;
+  try {
+    content = await deps.readTextFile(target.portFile);
+  } catch (error) {
+    return { kind: "failure", failure: toFileFailure(target, error) };
+  }
+  let parsed;
+  try {
+    parsed = parseDevToolsActivePortFile(content);
+  } catch (error) {
+    if (error instanceof DevToolsActivePortParseError) {
+      return {
+        kind: "failure",
+        failure: {
+          ...target,
+          reason: error.reason,
+          message: error.message
+        }
+      };
+    }
+    throw error;
+  }
+  try {
+    const probe = await deps.probeBrowserWebSocket(
+      parsed.wsUrl,
+      options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS
+    );
+    return {
+      kind: "candidate",
+      candidate: {
+        ...target,
+        port: parsed.port,
+        browserPath: parsed.browserPath,
+        wsUrl: parsed.wsUrl,
+        browserVersion: probe.browserVersion
+      }
+    };
+  } catch (error) {
+    return {
+      kind: "failure",
+      failure: toProbeFailure(target, parsed.wsUrl, error)
+    };
+  }
+}
+async function discoverLocalBrowsers(options = {}, deps = defaultDependencies) {
+  const scanTargets = buildLocalBrowserScanTargets(options);
+  const outcomes = await Promise.all(
+    scanTargets.map((target) => inspectScanTarget(target, options, deps))
+  );
+  const candidates = [];
+  const failures = [];
+  for (const outcome of outcomes) {
+    if (outcome.kind === "candidate") {
+      candidates.push(outcome.candidate);
+    } else {
+      failures.push(outcome.failure);
+    }
+  }
+  return { candidates, failures };
+}
+var BrowserEndpointResolutionError = class extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+  name = "BrowserEndpointResolutionError";
+};
+async function resolveBrowserEndpoint(options = {}, deps = defaultDependencies) {
+  if (options.explicitWsUrl) {
+    return {
+      wsUrl: options.explicitWsUrl,
+      source: "explicit-ws"
+    };
+  }
+  let localDiscovery;
+  if (options.allowLocalDiscovery ?? true) {
+    localDiscovery = await discoverLocalBrowsers(options, deps);
+    if (localDiscovery.candidates.length === 1) {
+      const candidate = localDiscovery.candidates[0];
+      return {
+        wsUrl: candidate.wsUrl,
+        source: "devtools-active-port",
+        channel: candidate.channel,
+        userDataDir: candidate.userDataDir
+      };
+    }
+    if (localDiscovery.candidates.length > 1) {
+      throw new BrowserEndpointResolutionError(
+        "multiple-local-browsers",
+        "Multiple local Chrome profiles are available for auto-discovery",
+        {
+          candidates: localDiscovery.candidates,
+          failures: localDiscovery.failures
+        }
+      );
+    }
+  }
+  if (options.allowLegacyHostFallback ?? true) {
+    const legacyHost = options.legacyHost ?? "localhost:9222";
+    try {
+      return {
+        wsUrl: await deps.getLegacyBrowserWebSocketUrl(legacyHost),
+        source: "json-version"
+      };
+    } catch (error) {
+      throw new BrowserEndpointResolutionError(
+        "browser-not-found",
+        "Could not resolve a browser endpoint",
+        {
+          candidates: localDiscovery?.candidates,
+          failures: localDiscovery?.failures,
+          legacyError: error instanceof Error ? error : new Error(String(error)),
+          legacyHost
+        }
+      );
+    }
+  }
+  throw new BrowserEndpointResolutionError(
+    "browser-not-found",
+    "Could not resolve a browser endpoint",
+    {
+      candidates: localDiscovery?.candidates,
+      failures: localDiscovery?.failures
+    }
+  );
+}
+
 // src/providers/index.ts
 function createProvider(options) {
   switch (options.provider) {
@@ -252,9 +881,15 @@ function createProvider(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrowserBaseProvider,
+  BrowserEndpointResolutionError,
   BrowserlessProvider,
   GenericProvider,
+  buildLocalBrowserScanTargets,
   createProvider,
+  discoverLocalBrowsers,
   discoverTargets,
-  getBrowserWebSocketUrl
+  getBrowserWebSocketUrl,
+  parseDevToolsActivePortFile,
+  resolveBrowserEndpoint,
+  resolveChromeUserDataDirs
 });

package/dist/providers.d.cts

@@ -1,5 +1,5 @@
-import { P as Provider, C as CreateSessionOptions, a as ProviderSession, b as ConnectOptions } from './types--wXNHUwt.cjs';
-export { c as ProxyConfig } from './types--wXNHUwt.cjs';
+import { P as Provider, C as CreateSessionOptions, a as ProviderSession, b as ConnectOptions } from './types-DeVSWhXj.cjs';
+export { B as BrowserEndpointResolutionError, d as ChromeChannel, e as ChromeUserDataDirOptions, D as DiscoverLocalBrowsersOptions, i as ProxyConfig, R as ResolvedBrowserEndpoint, g as ResolvedBrowserSource, c as buildLocalBrowserScanTargets, f as discoverLocalBrowsers, p as parseDevToolsActivePortFile, r as resolveBrowserEndpoint, h as resolveChromeUserDataDirs } from './types-DeVSWhXj.cjs';
 
 /**
  * BrowserBase provider implementation

package/dist/providers.d.ts

@@ -1,5 +1,5 @@
-import { P as Provider, C as CreateSessionOptions, a as ProviderSession, b as ConnectOptions } from './types--wXNHUwt.js';
-export { c as ProxyConfig } from './types--wXNHUwt.js';
+import { P as Provider, C as CreateSessionOptions, a as ProviderSession, b as ConnectOptions } from './types-DeVSWhXj.js';
+export { B as BrowserEndpointResolutionError, d as ChromeChannel, e as ChromeUserDataDirOptions, D as DiscoverLocalBrowsersOptions, i as ProxyConfig, R as ResolvedBrowserEndpoint, g as ResolvedBrowserSource, c as buildLocalBrowserScanTargets, f as discoverLocalBrowsers, p as parseDevToolsActivePortFile, r as resolveBrowserEndpoint, h as resolveChromeUserDataDirs } from './types-DeVSWhXj.js';
 
 /**
  * BrowserBase provider implementation