cdp-toolkit 1.10.0 → 1.11.0

package/src/bidi/session-lease.ts

@@ -0,0 +1,265 @@
+/**
+ * Firefox BiDi SESSION-slot lease: cross-process coordination for the ONE
+ * WebDriver-BiDi session a single Firefox instance will serve.
+ *
+ * WHY THIS EXISTS. Firefox admits exactly one active WebDriver-BiDi session per
+ * browser. When two cdp-toolkit MCP-server processes ATTACH to the same
+ * user-launched Firefox endpoint (e.g. ws://127.0.0.1:9223/session), they both
+ * want that one slot. Today the second process calls session.new and gets a
+ * hard "Maximum number of active sessions" with no way to tell a LIVE holder
+ * (another agent legitimately driving the browser) from a DEAD one (a crashed
+ * process that left the slot occupied). This module makes that distinction on
+ * disk, so a live holder is respected and a dead holder's orphan is reclaimed.
+ *
+ * WHY A FILE, AND WHY KEYED BY ENDPOINT. Same reasoning as the tab leases in
+ * ../leases.ts: two MCP servers are two processes, so in-process state would
+ * guard the wrong boundary. The tab lease is keyed by (backend, targetId)
+ * because it owns a tab; this lease is keyed by the BiDi ws ENDPOINT string
+ * because it owns the browser's single session slot, which is a property of the
+ * endpoint, not of any tab. One lock file per endpoint.
+ *
+ * WHY NO NONCE/TOKEN. A tab lease mints a nonce because a caller passes a token
+ * back and a reclamation must invalidate the superseded one. Nobody passes a
+ * session token back here: the slot is owned by whichever process currently
+ * holds the live BiDi connection and is released on dispose. Ownership is
+ * therefore identified by (pid, createdAt) of the record we wrote, which is
+ * enough to keep release from unlinking a record another process created after
+ * stealing the slot from us.
+ *
+ * WHY STALENESS IS PURE PID-LIVENESS, WITH NO TTL. A long-lived MCP server can
+ * legitimately hold the slot for hours, so a time-based expiry would reap a
+ * healthy holder. The only thing that makes a holder illegitimate is that its
+ * process is gone. So the sole staleness test is isPidAlive (reused from
+ * ../leases.ts): pid alive -> legitimate holder; pid dead -> orphan to steal.
+ *
+ * ATOMICITY. Claims are exclusive creates (writeFile flag "wx"), exactly like
+ * ../leases.ts claimLease, so "is the slot free, and if so take it" is atomic
+ * against a racing process for free, with no registry lock.
+ */
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPidAlive, leaseDir } from "../leases.ts";
+
+/**
+ * The on-disk record for a held session slot. Keyed by endpoint (one file per
+ * endpoint). No nonce: see the header. marionettePort is carried so a stealer
+ * can surface which Marionette port an orphaned session was bound to when it
+ * has to force-clear it.
+ */
+export interface SessionSlotRecord {
+  endpoint: string;
+  /** Owning MCP server process. The one field staleness turns on. */
+  pid: number;
+  /** Caller-supplied agent label, surfaced in busy/steal reporting. */
+  label: string;
+  createdAt: number;
+  /** Optional Marionette control port bound to this Firefox, when known. */
+  marionettePort?: number;
+}
+
+/**
+ * What a holder keeps so it can release ITS OWN record and never another
+ * process's. endpoint locates the file; (pid, createdAt) identify our record.
+ */
+export interface SessionSlotHandle {
+  endpoint: string;
+  pid: number;
+  createdAt: number;
+}
+
+export interface AcquireResult {
+  handle: SessionSlotHandle;
+  /**
+   * Set only when we STOLE a dead holder's slot. Its presence tells the caller
+   * that Firefox may still believe an orphaned BiDi session is active, so the
+   * caller must force-clear that session (e.g. via Marionette) before it calls
+   * session.new, or Firefox will still refuse with "Maximum number of active
+   * sessions". Absent on a clean first acquire.
+   */
+  staleHolder?: SessionSlotRecord;
+}
+
+export interface AcquireOptions {
+  label: string;
+  marionettePort?: number;
+  /** How long to keep polling a LIVE holder before giving up. Default sessionWaitMs(). */
+  waitMs?: number;
+  /** Injectable clock for the record's createdAt, so tests are deterministic. */
+  now?: number;
+  /** Poll interval while waiting on a live holder. Default DEFAULT_POLL_MS. */
+  pollMs?: number;
+}
+
+/** Env-overridable wait ceiling, in ms. */
+const DEFAULT_SESSION_WAIT_MS = 10_000;
+/** Poll cadence while a live holder is blocking us. */
+const DEFAULT_POLL_MS = 250;
+
+/** Same substitution rule as ../leases.ts safeId, applied to the endpoint URL. */
+function safeEndpoint(endpoint: string): string {
+  return endpoint.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/** One lock file per endpoint, a sibling of the tab lease files in ARTIFACT_DIR. */
+export function sessionSlotFile(endpoint: string): string {
+  return join(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
+}
+
+/** Read per call (like leaseDir/leaseTtlMs), so a test can redirect it. A value
+ *  that is not a finite number > 0 falls back to the default. */
+export function sessionWaitMs(): number {
+  const raw = Number(process.env.CDP_FIREFOX_SESSION_WAIT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SESSION_WAIT_MS;
+}
+
+/**
+ * Thrown when the slot is held by a LIVE process and did not free up within the
+ * wait window (or the attempt cap was hit). Names the live holder so the caller
+ * can decide to wait and retry or point this server at a different browser.
+ */
+export class SessionSlotBusyError extends Error {
+  readonly endpoint: string;
+  readonly holderPid?: number;
+  readonly holderLabel?: string;
+  constructor(endpoint: string, holder?: SessionSlotRecord) {
+    const who = holder ? `'${holder.label}' (pid ${holder.pid})` : "another live process";
+    super(
+      `Firefox BiDi session slot for endpoint '${endpoint}' is held by ${who}. ` +
+        `Firefox serves exactly ONE WebDriver-BiDi session per browser instance, and this slot is held ` +
+        `by a LIVE process, so it cannot be taken. Wait for that process to release it and retry, or point ` +
+        `this server at a different endpoint/browser.`,
+    );
+    this.name = "SessionSlotBusyError";
+    this.endpoint = endpoint;
+    if (holder) {
+      this.holderPid = holder.pid;
+      this.holderLabel = holder.label;
+    }
+  }
+}
+
+/**
+ * Read the slot record, or undefined if the slot is genuinely free.
+ *
+ * Mirrors ../leases.ts readLease's fail-closed contract: ENOENT is "free" and
+ * returns undefined; any OTHER errno (EACCES, EIO, EISDIR, EMFILE...) is
+ * rethrown rather than reported as absent, because reporting "free" for a file
+ * that merely could not be read would admit a second process to a slot that is
+ * very much held. A record that reads but does not PARSE is treated as absent,
+ * deliberately: a corrupt record can never become readable, and failing closed
+ * on it would brick the endpoint with no in-product recovery, whereas an errno
+ * is transient.
+ */
+export async function readSessionSlot(endpoint: string): Promise<SessionSlotRecord | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(sessionSlotFile(endpoint), "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined; // genuinely free
+    throw err; // unreadable is not absent: fail closed
+  }
+  try {
+    const rec = JSON.parse(raw) as SessionSlotRecord;
+    if (typeof rec?.pid === "number" && typeof rec?.endpoint === "string" && typeof rec?.label === "string") {
+      return rec;
+    }
+  } catch {
+    /* unparseable: fall through to undefined, see the doc comment above */
+  }
+  return undefined;
+}
+
+/**
+ * Take the endpoint's session slot, coordinating with any other process.
+ *
+ * Returns { handle } on a clean acquire. Returns { handle, staleHolder } when
+ * the previous holder's process was dead and we stole its orphaned slot (the
+ * caller must then force-clear Firefox's orphaned session before session.new).
+ * Throws SessionSlotBusyError when a LIVE holder does not free the slot inside
+ * the wait window.
+ */
+export async function acquireSessionSlot(endpoint: string, opts: AcquireOptions): Promise<AcquireResult> {
+  const waitMs = opts.waitMs ?? sessionWaitMs();
+  const pollMs = opts.pollMs !== undefined && opts.pollMs > 0 ? opts.pollMs : DEFAULT_POLL_MS;
+  // opts.now stamps OUR record deterministically for tests; the wait deadline
+  // uses real time (with real sleeps) so a small waitMs actually times out.
+  const createdAt = opts.now ?? Date.now();
+  const file = sessionSlotFile(endpoint);
+
+  const record: SessionSlotRecord = {
+    endpoint,
+    pid: process.pid,
+    label: opts.label,
+    createdAt,
+  };
+  if (opts.marionettePort !== undefined) record.marionettePort = opts.marionettePort;
+  const handle: SessionSlotHandle = { endpoint, pid: process.pid, createdAt };
+  const payload = JSON.stringify(record);
+
+  await mkdir(leaseDir(), { recursive: true });
+
+  const deadline = Date.now() + waitMs;
+  // Bounds the immediate-retry paths (released-mid-race, steal-raced) so a
+  // pathological create/release partner can never spin us forever. The live
+  // holder is bounded by `deadline` instead; this cap is generous relative to
+  // it so it only bites on pathology, never on ordinary waiting.
+  const maxAttempts = Math.max(100, Math.ceil(waitMs / pollMs) + 100);
+
+  let attempts = 0;
+  let lastLiveHolder: SessionSlotRecord | undefined;
+
+  while (true) {
+    if (attempts >= maxAttempts) throw new SessionSlotBusyError(endpoint, lastLiveHolder);
+    attempts++;
+
+    // 1. Try to take the slot outright.
+    try {
+      await writeFile(file, payload, { flag: "wx" });
+      return { handle };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+
+    // 2. Occupied. Read the holder to classify it.
+    const holder = await readSessionSlot(endpoint);
+    if (!holder) continue; // released between our create and our read: retry immediately
+
+    if (!isPidAlive(holder.pid)) {
+      // 3. DEAD holder: orphan. Steal it — unlink, then re-create OUR record.
+      await unlink(file).catch(() => undefined);
+      try {
+        await writeFile(file, payload, { flag: "wx" });
+        return { handle, staleHolder: holder };
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+        continue; // steal raced another process: retry immediately
+      }
+    }
+
+    // 4. LIVE holder: legitimate contention. Poll until the deadline, then fail.
+    lastLiveHolder = holder;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new SessionSlotBusyError(endpoint, holder);
+    await sleep(Math.min(pollMs, remaining));
+  }
+}
+
+/**
+ * Release the slot, but ONLY if the record on disk is still the one we wrote.
+ *
+ * A record is ours iff its pid is this process AND its createdAt matches the
+ * handle. That guard is what stops us from unlinking a record another process
+ * created after stealing the slot from us (dead-pid steal), which would hand
+ * two processes the slot at once. Idempotent: a missing record is released:false.
+ */
+export async function releaseSessionSlot(handle: SessionSlotHandle): Promise<{ released: boolean }> {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current) return { released: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt) return { released: false };
+  await unlink(sessionSlotFile(handle.endpoint)).catch(() => undefined); // swallow release races
+  return { released: true };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/cli.ts

@@ -28,6 +28,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 import { MANIFEST } from "./manifest.ts";
+import { runInstaller } from "./install/wizard.ts";
 
 const USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
@@ -210,6 +211,15 @@ function printToolHelp(name: ToolName): void {
 
 async function main(): Promise<number> {
   const rawArgv = process.argv.slice(2);
+
+  // `install` is a CLI-ONLY subcommand (the `cdp install` wizard), not an MCP tool: it is not in
+  // TOOLS/MANIFEST and never appears in --list or tools/list. Dispatch it FIRST — before --browser
+  // resolution, --help, and tool dispatch — so `cdp install --help` reaches the installer's own
+  // help rather than the global USAGE, and so nothing below can reinterpret its flags.
+  if (rawArgv[0] === "install") {
+    return await runInstaller(rawArgv.slice(1));
+  }
+
   const { kind: browser, endpoint } = resolveBackend(rawArgv);
   const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));
 

package/src/install/browser.ts

@@ -0,0 +1,211 @@
+/**
+ * Browser half of `cdp install`: binary detection, debug-launch alias generation, and an
+ * idempotent shell-rc append. The other half (harness/MCP config) lives in a sibling module and
+ * is not this file's concern — this file only knows about browsers and shell rc files.
+ *
+ * Zero runtime dependencies beyond node:fs, node:fs/promises, node:os, node:path.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+
+export type BrowserChoice = "arc" | "chrome" | "firefox";
+
+export interface BrowserInfo {
+  choice: BrowserChoice;
+  /**
+   * The binary path or command name to launch. When a PATH-relative name (e.g. "google-chrome")
+   * is the chosen candidate, this is returned UNRESOLVED — as the bare name, not an absolute path
+   * scanned off today's PATH — so the alias stays portable and lets the shell re-resolve it against
+   * PATH at invocation time rather than pinning it to wherever it happened to be found right now.
+   */
+  binary: string;
+  found: boolean;
+}
+
+export interface AliasOptions {
+  choice: BrowserChoice;
+  port: number;
+  aliasName?: string;
+  profileDir?: string;
+}
+
+export interface RcAppendResult {
+  rcPath: string;
+  action: "created-block" | "replaced-block" | "unchanged";
+}
+
+/* ------------------------------- binary detection ------------------------------- */
+
+/**
+ * Per-choice candidate lists, built fresh on every call so env var overrides (CHROME_BIN /
+ * ARC_BIN / FIREFOX_BIN) are read live rather than captured once at module load — important for
+ * tests that set/restore these env vars around a single call.
+ *
+ * macOS-first, Linux fallback. Order mirrors the spec: env override, then the macOS .app bundle
+ * path, then PATH-relative command names. Arc is macOS-mostly, so found=false on Linux (nothing
+ * in this list resolves there) is expected, not a bug.
+ */
+const CANDIDATE_BUILDERS: Record<BrowserChoice, () => Array<string | undefined>> = {
+  chrome: () => [
+    process.env.CHROME_BIN,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+  ],
+  arc: () => [process.env.ARC_BIN, "/Applications/Arc.app/Contents/MacOS/Arc", "arc"],
+  firefox: () => [
+    process.env.FIREFOX_BIN,
+    "/Applications/Firefox.app/Contents/MacOS/firefox",
+    "firefox",
+    "/usr/bin/firefox",
+  ],
+};
+
+/** Scan $PATH for `cmd`. Used only to decide `found` for a bare candidate — never to rewrite it. */
+function existsOnPath(cmd: string): boolean {
+  const pathEnv = process.env.PATH;
+  if (!pathEnv) return false;
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    if (existsSync(join(dir, cmd))) return true;
+  }
+  return false;
+}
+
+/**
+ * Mirrors the resolveBinary logic in src/bidi/launch.ts: an ABSOLUTE candidate counts only if it
+ * exists on disk (otherwise a hardcoded macOS path would shadow a real PATH fallback on Linux and
+ * yield a not-found result at spawn time); a bare PATH name is returned as-is, unresolved, for the
+ * shell to resolve — but IS checked against $PATH here purely to set an accurate `found` flag.
+ */
+function resolveCandidate(candidates: Array<string | undefined>): { binary: string; found: boolean } {
+  let lastDefined = "";
+  for (const c of candidates) {
+    if (!c) continue;
+    lastDefined = c;
+    if (c.startsWith("/")) {
+      if (existsSync(c)) return { binary: c, found: true };
+      continue;
+    }
+    if (existsOnPath(c)) return { binary: c, found: true };
+  }
+  return { binary: lastDefined, found: false };
+}
+
+export function detectBrowser(choice: BrowserChoice): BrowserInfo {
+  const { binary, found } = resolveCandidate(CANDIDATE_BUILDERS[choice]());
+  return { choice, binary, found };
+}
+
+/* ------------------------------- alias generation ------------------------------- */
+
+function defaultProfileDir(choice: BrowserChoice): string {
+  // Literal $HOME (not resolved via os.homedir()) so it survives into the alias's stored text and
+  // expands fresh every time the alias runs — see the two-phase alias substitution note below.
+  return `$HOME/.cdp-toolkit/${choice}-profile`;
+}
+
+export function defaultAliasName(choice: BrowserChoice): string {
+  return `cdp-${choice}`;
+}
+
+/**
+ * The launch flags only (no binary). Chrome and Arc are both Chromium-based and Arc accepts
+ * Chrome's flags, so they share a shape: --remote-debugging-port plus a DEDICATED
+ * --user-data-dir. The dedicated profile is required, not cosmetic — Chrome silently ignores
+ * --remote-debugging-port when it hands off to an already-running instance on the default
+ * profile, so the port never opens and there is no error, just a hung attach later.
+ *
+ * Firefox's --marionette flag is likewise required, not optional: cdp-toolkit's Firefox
+ * orphan-recovery path (src/bidi/launch.ts's header comment) uses the Marionette side channel to
+ * recover a dropped BiDi connection, and that recovery cannot fire without it.
+ */
+export function browserLaunchArgs(o: AliasOptions): string[] {
+  const profileDir = o.profileDir ?? defaultProfileDir(o.choice);
+  if (o.choice === "firefox") {
+    return ["--remote-debugging-port", String(o.port), "--marionette", "--no-remote", "--profile", profileDir];
+  }
+  return [`--remote-debugging-port=${o.port}`, `--user-data-dir=${profileDir}`];
+}
+
+/** Quote only if needed: wrapping a plain token in quotes is harmless but unquoted-with-a-space breaks word splitting. */
+function shellQuoteIfSpaced(token: string): string {
+  return /\s/.test(token) ? `"${token}"` : token;
+}
+
+/**
+ * A single `alias name='<binary> <flags>'` line. The whole value is wrapped in single quotes (so
+ * it is stored literally, unexpanded, when the alias is DEFINED); the binary is additionally
+ * double-quoted when it contains a space (the macOS "Google Chrome.app" / future spaced paths),
+ * because shell alias substitution is a two-phase process — text substitution first, then a fresh
+ * parse of the substituted text — so the inner double quotes and the bare $HOME in the profile
+ * dir both take effect correctly at every INVOCATION of the alias, not at definition time.
+ */
+export function aliasLine(o: AliasOptions): string {
+  const name = o.aliasName ?? defaultAliasName(o.choice);
+  const { binary } = detectBrowser(o.choice);
+  const parts = [shellQuoteIfSpaced(binary), ...browserLaunchArgs(o)];
+  return `alias ${name}='${parts.join(" ")}'`;
+}
+
+/* ------------------------------- shell rc detection ------------------------------- */
+
+export function detectShellRc(): string {
+  const shell = process.env.SHELL ?? "";
+  if (shell.endsWith("zsh")) return join(homedir(), ".zshrc");
+  if (shell.endsWith("bash")) return join(homedir(), ".bashrc");
+  return join(homedir(), process.platform === "darwin" ? ".zshrc" : ".bashrc");
+}
+
+/* ------------------------------- idempotent rc append ------------------------------- */
+
+const MARKER_START = "# >>> cdp-toolkit alias >>>";
+const MARKER_END = "# <<< cdp-toolkit alias <<<";
+
+function ensureTrailingNewline(s: string): string {
+  return s.endsWith("\n") ? s : `${s}\n`;
+}
+
+/**
+ * Idempotently write ONE marker block into rcPath, replacing its body in place on re-runs rather
+ * than accumulating duplicates. The wizard owns composing aliasBlockBody (e.g. joining several
+ * browsers' alias lines with "\n") — this function only manages the single marker block, so
+ * calling it again with a fuller body updates the same block rather than adding a second one.
+ */
+export async function appendAliasToRc(rcPath: string, aliasBlockBody: string): Promise<RcAppendResult> {
+  let existing = "";
+  try {
+    existing = await readFile(rcPath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+
+  const block = `${MARKER_START}\n${aliasBlockBody}\n${MARKER_END}`;
+
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const endOfEndLine = existing.indexOf("\n", endIdx);
+    const before = existing.slice(0, startIdx);
+    const after = endOfEndLine === -1 ? "" : existing.slice(endOfEndLine + 1);
+    const existingBlock = existing.slice(startIdx, endOfEndLine === -1 ? existing.length : endOfEndLine);
+
+    if (existingBlock === block) {
+      return { rcPath, action: "unchanged" };
+    }
+
+    const next = ensureTrailingNewline(`${before}${block}\n${after}`);
+    await writeFile(rcPath, next, "utf8");
+    return { rcPath, action: "replaced-block" };
+  }
+
+  await mkdir(dirname(rcPath), { recursive: true });
+  const sep = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  const next = `${existing}${sep}${block}\n`;
+  await writeFile(rcPath, next, "utf8");
+  return { rcPath, action: "created-block" };
+}