cdp-toolkit 1.10.0 → 1.11.0

package/dist/cli.js

@@ -5396,6 +5396,252 @@ async function connectBidiSessionUrl(wsUrl, opts = {}) {
   return conn;
 }
 
+// src/bidi/session-lease.ts
+import { mkdir as mkdir12, readFile as readFile8, unlink as unlink5, writeFile as writeFile9 } from "node:fs/promises";
+import { join as join10 } from "node:path";
+var DEFAULT_SESSION_WAIT_MS = 1e4;
+var DEFAULT_POLL_MS = 250;
+function safeEndpoint(endpoint) {
+  return endpoint.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function sessionSlotFile(endpoint) {
+  return join10(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
+}
+function sessionWaitMs() {
+  const raw = Number(process.env.CDP_FIREFOX_SESSION_WAIT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SESSION_WAIT_MS;
+}
+
+class SessionSlotBusyError extends Error {
+  endpoint;
+  holderPid;
+  holderLabel;
+  constructor(endpoint, holder) {
+    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;
+    }
+  }
+}
+async function readSessionSlot(endpoint) {
+  let raw;
+  try {
+    raw = await readFile8(sessionSlotFile(endpoint), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return;
+    throw err;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.pid === "number" && typeof rec?.endpoint === "string" && typeof rec?.label === "string") {
+      return rec;
+    }
+  } catch {}
+  return;
+}
+async function acquireSessionSlot(endpoint, opts) {
+  const waitMs = opts.waitMs ?? sessionWaitMs();
+  const pollMs = opts.pollMs !== undefined && opts.pollMs > 0 ? opts.pollMs : DEFAULT_POLL_MS;
+  const createdAt = opts.now ?? Date.now();
+  const file = sessionSlotFile(endpoint);
+  const record2 = {
+    endpoint,
+    pid: process.pid,
+    label: opts.label,
+    createdAt
+  };
+  if (opts.marionettePort !== undefined)
+    record2.marionettePort = opts.marionettePort;
+  const handle = { endpoint, pid: process.pid, createdAt };
+  const payload = JSON.stringify(record2);
+  await mkdir12(leaseDir(), { recursive: true });
+  const deadline = Date.now() + waitMs;
+  const maxAttempts = Math.max(100, Math.ceil(waitMs / pollMs) + 100);
+  let attempts = 0;
+  let lastLiveHolder;
+  while (true) {
+    if (attempts >= maxAttempts)
+      throw new SessionSlotBusyError(endpoint, lastLiveHolder);
+    attempts++;
+    try {
+      await writeFile9(file, payload, { flag: "wx" });
+      return { handle };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    const holder = await readSessionSlot(endpoint);
+    if (!holder)
+      continue;
+    if (!isPidAlive(holder.pid)) {
+      await unlink5(file).catch(() => {
+        return;
+      });
+      try {
+        await writeFile9(file, payload, { flag: "wx" });
+        return { handle, staleHolder: holder };
+      } catch (err) {
+        if (err.code !== "EEXIST")
+          throw err;
+        continue;
+      }
+    }
+    lastLiveHolder = holder;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+      throw new SessionSlotBusyError(endpoint, holder);
+    await sleep2(Math.min(pollMs, remaining));
+  }
+}
+async function releaseSessionSlot(handle) {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current)
+    return { released: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt)
+    return { released: false };
+  await unlink5(sessionSlotFile(handle.endpoint)).catch(() => {
+    return;
+  });
+  return { released: true };
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/bidi/marionette.ts
+import { Socket } from "node:net";
+var DEFAULT_MARIONETTE_PORT = 2828;
+var DEFAULT_TIMEOUT_MS3 = 4000;
+var HOST = "127.0.0.1";
+var COLON = 58;
+var DELETE_SESSION_FRAME = encodeFrame([0, 1, "WebDriver:DeleteSession", {}]);
+function defaultMarionettePort() {
+  const raw = Number(process.env.CDP_FIREFOX_MARIONETTE_PORT);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MARIONETTE_PORT;
+}
+function encodeFrame(json) {
+  const body = Buffer.from(JSON.stringify(json), "utf8");
+  const prefix = Buffer.from(`${body.length}:`, "ascii");
+  return Buffer.concat([prefix, body]);
+}
+
+class MarionetteProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MarionetteProtocolError";
+  }
+}
+
+class FrameDecoder {
+  buf = Buffer.alloc(0);
+  push(chunk) {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+  next() {
+    const colon = this.buf.indexOf(COLON);
+    if (colon === -1) {
+      this.assertDigitsPrefix(this.buf.length);
+      return;
+    }
+    if (colon === 0)
+      throw new MarionetteProtocolError("empty frame length prefix");
+    this.assertDigitsPrefix(colon);
+    const len = Number.parseInt(this.buf.toString("ascii", 0, colon), 10);
+    const start = colon + 1;
+    const end = start + len;
+    if (this.buf.length < end)
+      return;
+    const payload = this.buf.toString("utf8", start, end);
+    this.buf = this.buf.subarray(end);
+    try {
+      return JSON.parse(payload);
+    } catch {
+      throw new MarionetteProtocolError(`frame body was not valid JSON (${len} bytes): ${payload.slice(0, 80)}`);
+    }
+  }
+  assertDigitsPrefix(upTo) {
+    for (let i = 0;i < upTo; i++) {
+      const b = this.buf[i];
+      if (b < 48 || b > 57) {
+        throw new MarionetteProtocolError(`non-digit byte 0x${b.toString(16)} in frame length prefix`);
+      }
+    }
+  }
+}
+function isSlotFreedReply(frame) {
+  if (!Array.isArray(frame))
+    return false;
+  const err = frame[2];
+  if (err === null)
+    return true;
+  if (typeof err === "object" && err !== null && err.error === "invalid session id") {
+    return true;
+  }
+  return false;
+}
+function forceClearOrphanSession(marionettePort, opts = {}) {
+  const timeoutMs = opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS3;
+  return new Promise((resolve) => {
+    if (!Number.isFinite(marionettePort) || marionettePort <= 0 || marionettePort > 65535) {
+      resolve(false);
+      return;
+    }
+    const sock = new Socket;
+    const decoder = new FrameDecoder;
+    let settled = false;
+    let handshakeSeen = false;
+    let commandSent = false;
+    const settle = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(value);
+    };
+    const timer = setTimeout(() => settle(false), timeoutMs);
+    if (typeof timer.unref === "function")
+      timer.unref();
+    sock.on("error", () => settle(false));
+    sock.on("close", () => settle(false));
+    sock.on("data", (chunk) => {
+      if (settled)
+        return;
+      try {
+        decoder.push(chunk);
+        for (;; ) {
+          const frame = decoder.next();
+          if (frame === undefined)
+            break;
+          if (!handshakeSeen) {
+            handshakeSeen = true;
+            continue;
+          }
+          settle(isSlotFreedReply(frame));
+          return;
+        }
+        if (handshakeSeen && !commandSent) {
+          commandSent = true;
+          sock.write(DELETE_SESSION_FRAME);
+        }
+      } catch {
+        settle(false);
+      }
+    });
+    try {
+      sock.connect(marionettePort, HOST);
+    } catch {
+      settle(false);
+    }
+  });
+}
+
 // src/bidi/snapshot.ts
 var STAMP_ATTR = "data-cdp-uid";
 async function takeStampedSnapshot(evaluate) {
@@ -5972,6 +6218,22 @@ var BIDI_CAPABILITIES = new Set([
   "locate.xpath"
 ]);
 var connections = new Map;
+var slotHandles = new Map;
+var connecting = new Map;
+async function releaseSlotOnDialFailure(endpoint, owned) {
+  if (owned)
+    return;
+  const h = slotHandles.get(endpoint);
+  if (h) {
+    await releaseSessionSlot(h).catch(() => {
+      return;
+    });
+    slotHandles.delete(endpoint);
+  }
+}
+function orphanNotClearedError(endpoint) {
+  return driverError2("disconnected", `Firefox holds an orphaned WebDriver BiDi session on ${endpoint} that could not be auto-cleared. ` + `Marionette recovery needs Firefox launched with --marionette (default port 2828, or set ` + `CDP_FIREFOX_MARIONETTE_PORT); otherwise restart Firefox to free the slot. (A client killed without ` + `session.end can leave a session Firefox does not reap.)`);
+}
 async function getConnection(endpoint, timeoutMs) {
   const existing = connections.get(endpoint);
   if (existing && existing.isOpen) {
@@ -5980,17 +6242,68 @@ async function getConnection(endpoint, timeoutMs) {
   }
   if (existing)
     connections.delete(endpoint);
-  const conn = await connectBidiSessionUrl(endpoint, {
-    ...timeoutMs !== undefined ? { timeoutMs } : {},
-    capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
-  }).catch((e) => {
-    if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
-      throw driverError2("disconnected", `Firefox already has an active WebDriver BiDi session on ${endpoint}; it allows only one. ` + `Close the other client, or restart Firefox, then retry. (A previously killed client can leave a ` + `session that Firefox does not reap.)`);
+  const inflight = connecting.get(endpoint);
+  if (inflight) {
+    const conn = await inflight;
+    conn.retain();
+    return conn;
+  }
+  const create = (async () => {
+    const mport = defaultMarionettePort();
+    const owned = slotHandles.has(endpoint);
+    if (!owned) {
+      let acq;
+      try {
+        acq = await acquireSessionSlot(endpoint, { label: defaultLabel(), marionettePort: mport });
+      } catch (e) {
+        if (e instanceof SessionSlotBusyError) {
+          const who = e.holderLabel ? `'${e.holderLabel}' (pid ${e.holderPid})` : "another live process";
+          throw driverError2("disconnected", `Firefox's single WebDriver BiDi session on ${endpoint} is held by a LIVE process ${who}. ` + `Firefox serves exactly ONE BiDi session per browser instance, so this server cannot take it ` + `while that process is running. Wait for it to release the session and retry, or point this ` + `server at a different endpoint/browser.`);
+        }
+        throw e;
+      }
+      slotHandles.set(endpoint, acq.handle);
+      if (acq.staleHolder) {
+        await forceClearOrphanSession(acq.staleHolder.marionettePort ?? mport);
+      }
     }
-    throw e;
-  });
-  connections.set(endpoint, conn);
-  return conn;
+    const dialOpts = {
+      ...timeoutMs !== undefined ? { timeoutMs } : {},
+      capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
+    };
+    let conn;
+    try {
+      conn = await connectBidiSessionUrl(endpoint, dialOpts);
+    } catch (e) {
+      if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
+        const cleared = await forceClearOrphanSession(mport);
+        if (!cleared) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          throw orphanNotClearedError(endpoint);
+        }
+        try {
+          conn = await connectBidiSessionUrl(endpoint, dialOpts);
+        } catch (e2) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          if (e2 instanceof BidiError && /maximum number of active sessions/i.test(e2.message)) {
+            throw orphanNotClearedError(endpoint);
+          }
+          throw e2;
+        }
+      } else {
+        await releaseSlotOnDialFailure(endpoint, owned);
+        throw e;
+      }
+    }
+    connections.set(endpoint, conn);
+    return conn;
+  })();
+  connecting.set(endpoint, create);
+  try {
+    return await create;
+  } finally {
+    connecting.delete(endpoint);
+  }
 }
 var bidiBeaconScripts = new Map;
 async function safeTitle(conn, contextId) {
@@ -6756,14 +7069,27 @@ class BidiBrowserDriver {
       if (key.startsWith(`${this.endpoint}:`))
         bidiBeaconScripts.delete(key);
     }
+    connecting.delete(this.endpoint);
     const conn = connections.get(this.endpoint);
-    if (!conn)
+    if (!conn) {
+      await this.releaseSessionSlotIfHeld();
       return;
+    }
     connections.delete(this.endpoint);
     await conn.send("session.end", {}).catch(() => {
       return;
     });
     conn.dispose();
+    await this.releaseSessionSlotIfHeld();
+  }
+  async releaseSessionSlotIfHeld() {
+    const h = slotHandles.get(this.endpoint);
+    if (!h)
+      return;
+    await releaseSessionSlot(h).catch(() => {
+      return;
+    });
+    slotHandles.delete(this.endpoint);
   }
 }
 function createFirefoxDriver(port, opts) {
@@ -6778,7 +7104,7 @@ import { spawn as spawn3 } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -6856,7 +7182,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join10(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join11(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -8886,6 +9212,566 @@ var MANIFEST = [
   }
 ];
 
+// src/install/wizard.ts
+import { createInterface } from "node:readline";
+import { homedir as homedir3 } from "node:os";
+import { join as join14 } from "node:path";
+
+// src/install/browser.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir as mkdir13, readFile as readFile9, writeFile as writeFile10 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname as dirname3, join as join12 } from "node:path";
+var CANDIDATE_BUILDERS = {
+  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"
+  ]
+};
+function existsOnPath(cmd) {
+  const pathEnv = process.env.PATH;
+  if (!pathEnv)
+    return false;
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir)
+      continue;
+    if (existsSync2(join12(dir, cmd)))
+      return true;
+  }
+  return false;
+}
+function resolveCandidate(candidates) {
+  let lastDefined = "";
+  for (const c of candidates) {
+    if (!c)
+      continue;
+    lastDefined = c;
+    if (c.startsWith("/")) {
+      if (existsSync2(c))
+        return { binary: c, found: true };
+      continue;
+    }
+    if (existsOnPath(c))
+      return { binary: c, found: true };
+  }
+  return { binary: lastDefined, found: false };
+}
+function detectBrowser(choice) {
+  const { binary, found } = resolveCandidate(CANDIDATE_BUILDERS[choice]());
+  return { choice, binary, found };
+}
+function defaultProfileDir(choice) {
+  return `$HOME/.cdp-toolkit/${choice}-profile`;
+}
+function defaultAliasName(choice) {
+  return `cdp-${choice}`;
+}
+function browserLaunchArgs(o) {
+  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}`];
+}
+function shellQuoteIfSpaced(token) {
+  return /\s/.test(token) ? `"${token}"` : token;
+}
+function aliasLine(o) {
+  const name = o.aliasName ?? defaultAliasName(o.choice);
+  const { binary } = detectBrowser(o.choice);
+  const parts = [shellQuoteIfSpaced(binary), ...browserLaunchArgs(o)];
+  return `alias ${name}='${parts.join(" ")}'`;
+}
+function detectShellRc() {
+  const shell = process.env.SHELL ?? "";
+  if (shell.endsWith("zsh"))
+    return join12(homedir(), ".zshrc");
+  if (shell.endsWith("bash"))
+    return join12(homedir(), ".bashrc");
+  return join12(homedir(), process.platform === "darwin" ? ".zshrc" : ".bashrc");
+}
+var MARKER_START = "# >>> cdp-toolkit alias >>>";
+var MARKER_END = "# <<< cdp-toolkit alias <<<";
+function ensureTrailingNewline(s) {
+  return s.endsWith(`
+`) ? s : `${s}
+`;
+}
+async function appendAliasToRc(rcPath, aliasBlockBody) {
+  let existing = "";
+  try {
+    existing = await readFile9(rcPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT")
+      throw err;
+  }
+  const block = `${MARKER_START}
+${aliasBlockBody}
+${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(`
+`, 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 next2 = ensureTrailingNewline(`${before}${block}
+${after}`);
+    await writeFile10(rcPath, next2, "utf8");
+    return { rcPath, action: "replaced-block" };
+  }
+  await mkdir13(dirname3(rcPath), { recursive: true });
+  const sep = existing.length === 0 || existing.endsWith(`
+`) ? "" : `
+`;
+  const next = `${existing}${sep}${block}
+`;
+  await writeFile10(rcPath, next, "utf8");
+  return { rcPath, action: "created-block" };
+}
+
+// src/install/harness.ts
+import { spawnSync } from "node:child_process";
+import { mkdir as mkdir14, readFile as readFile10, writeFile as writeFile11 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname4, join as join13 } from "node:path";
+async function installMcpServer(harness, name, cfg, opts = {}) {
+  switch (harness) {
+    case "claude":
+      return installClaude(name, cfg, opts);
+    case "codex":
+      return installCodex(name, cfg);
+    case "opencode":
+      return installOpencode(name, cfg);
+    default: {
+      const exhaustive = harness;
+      throw new Error(`unknown harness: ${String(exhaustive)}`);
+    }
+  }
+}
+async function installClaude(name, cfg, opts) {
+  const path = opts.configPath ?? join13(opts.homeDir ?? homedir2(), ".claude.json");
+  let root;
+  let fileExisted;
+  try {
+    const text = await readFile10(path, "utf8");
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`${path} does not contain a JSON object at its top level`);
+    }
+    root = parsed;
+    fileExisted = true;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      root = {};
+      fileExisted = false;
+    } else {
+      throw err;
+    }
+  }
+  const rawServers = root.mcpServers;
+  const mcpServers = typeof rawServers === "object" && rawServers !== null && !Array.isArray(rawServers) ? rawServers : {};
+  root.mcpServers = mcpServers;
+  const entry = { command: cfg.command, args: cfg.args };
+  if (Object.keys(cfg.env).length > 0)
+    entry.env = cfg.env;
+  const prior = mcpServers[name];
+  const action = prior === undefined ? "added" : canonicalJson(prior) === canonicalJson(entry) ? "unchanged" : "updated";
+  mcpServers[name] = entry;
+  if (action === "unchanged") {
+    return { harness: "claude", method: "file", path, action, detail: "no change needed" };
+  }
+  await mkdir14(dirname4(path), { recursive: true });
+  await writeFile11(path, JSON.stringify(root, null, 2) + `
+`, "utf8");
+  return {
+    harness: "claude",
+    method: "file",
+    path,
+    action,
+    detail: fileExisted ? undefined : "created new config file"
+  };
+}
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+  if (Array.isArray(value))
+    return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function codexAddArgs(name, cfg) {
+  const envArgs = Object.entries(cfg.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  return ["mcp", "add", name, ...envArgs, "--", cfg.command, ...cfg.args];
+}
+async function installCodex(name, cfg) {
+  if (!isOnPath("codex")) {
+    throw new Error("codex CLI not found on PATH — install Codex or pick a different harness");
+  }
+  const probe = spawnSync("codex", ["mcp", "get", name], { encoding: "utf8" });
+  const exists = probe.status === 0;
+  if (exists) {
+    const removed = spawnSync("codex", ["mcp", "remove", name], { encoding: "utf8" });
+    if (removed.status !== 0) {
+      throw new Error(`codex mcp remove ${name} failed: ${(removed.stderr || removed.stdout || "").trim()}`);
+    }
+  }
+  const addArgs = codexAddArgs(name, cfg);
+  const added = spawnSync("codex", addArgs, { encoding: "utf8" });
+  if (added.status !== 0) {
+    throw new Error(`codex ${addArgs.join(" ")} failed: ${(added.stderr || added.stdout || "").trim()}`);
+  }
+  return {
+    harness: "codex",
+    method: "cli",
+    action: exists ? "updated" : "added",
+    detail: added.stdout?.trim() || undefined
+  };
+}
+function opencodeAddArgs(name, cfg) {
+  const envArgs = Object.entries(cfg.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  return ["mcp", "add", name, ...envArgs, "--", cfg.command, ...cfg.args];
+}
+async function installOpencode(name, cfg) {
+  if (!isOnPath("opencode")) {
+    throw new Error("opencode CLI not found on PATH — install OpenCode or pick a different harness");
+  }
+  const addArgs = opencodeAddArgs(name, cfg);
+  const added = spawnSync("opencode", addArgs, { encoding: "utf8" });
+  if (added.status !== 0) {
+    throw new Error(`opencode ${addArgs.join(" ")} failed: ${(added.stderr || added.stdout || "").trim()}`);
+  }
+  return {
+    harness: "opencode",
+    method: "cli",
+    action: "added",
+    detail: added.stdout?.trim() || undefined
+  };
+}
+function isOnPath(bin) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(finder, [bin], { encoding: "utf8" });
+  return result.status === 0;
+}
+
+// src/install/wizard.ts
+var DEFAULT_NAME = "cdp-toolkit";
+var HARNESSES = ["claude", "codex", "opencode"];
+var BROWSERS = ["arc", "chrome", "firefox"];
+function defaultPortFor(browser) {
+  return browser === "firefox" ? 9223 : 9222;
+}
+function parseHarness(v) {
+  if (v === undefined)
+    throw new Error("--harness requires a value: claude, codex, or opencode");
+  if (HARNESSES.includes(v))
+    return v;
+  throw new Error(`--harness must be one of claude|codex|opencode (got '${v}')`);
+}
+function parseBrowserChoice(v) {
+  if (v === undefined)
+    throw new Error("--browser requires a value: arc, chrome, or firefox");
+  if (BROWSERS.includes(v))
+    return v;
+  throw new Error(`--browser must be one of arc|chrome|firefox (got '${v}')`);
+}
+function parsePort(v) {
+  if (v === undefined)
+    throw new Error("--port requires a value (an integer 1-65535)");
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    throw new Error(`--port must be an integer 1-65535 (got '${v}')`);
+  }
+  return n;
+}
+function normalizeArgv(argv) {
+  const out = [];
+  for (const t of argv) {
+    if (t.startsWith("--") && t.includes("=")) {
+      const eq = t.indexOf("=");
+      out.push(t.slice(0, eq), t.slice(eq + 1));
+    } else {
+      out.push(t);
+    }
+  }
+  return out;
+}
+function parseInstallArgs(argv) {
+  const tokens = normalizeArgv(argv);
+  const out = { name: DEFAULT_NAME, alias: true };
+  for (let i = 0;i < tokens.length; i++) {
+    const t = tokens[i];
+    switch (t) {
+      case "--help":
+      case "-h":
+        out.help = true;
+        break;
+      case "--yes":
+      case "-y":
+        out.yes = true;
+        break;
+      case "--no-alias":
+        out.alias = false;
+        break;
+      case "--alias":
+        out.alias = true;
+        break;
+      case "--harness":
+        out.harness = parseHarness(tokens[++i]);
+        break;
+      case "--browser":
+        out.browser = parseBrowserChoice(tokens[++i]);
+        break;
+      case "--port":
+        out.port = parsePort(tokens[++i]);
+        break;
+      case "--name": {
+        const v = tokens[++i];
+        if (v === undefined)
+          throw new Error("--name requires a value");
+        out.name = v;
+        break;
+      }
+      case "--alias-name": {
+        const v = tokens[++i];
+        if (v === undefined)
+          throw new Error("--alias-name requires a value");
+        out.aliasName = v;
+        break;
+      }
+      default:
+        throw new Error(`cdp install: unknown option '${t}' (run \`cdp install --help\`)`);
+    }
+  }
+  return out;
+}
+function composeServerConfig(browser, port) {
+  const env = browser === "firefox" ? { CDP_BROWSER: "firefox", CDP_FIREFOX_ENDPOINT: String(port) } : { CDP_BASE: `http://127.0.0.1:${port}` };
+  return { command: "npx", args: ["-y", "cdp-toolkit"], env };
+}
+function installHelpText() {
+  return `cdp install — register the cdp-toolkit MCP server with your coding harness and add a
+browser-launch alias (with the remote-debugging port open) to your shell rc.
+
+Usage:
+  cdp install [--harness <claude|codex|opencode>] [--browser <arc|chrome|firefox>]
+              [--port <n>] [--name <server-name>] [--alias-name <name>]
+              [--no-alias] [--yes|-y] [--help|-h]
+
+Options:
+  --harness <h>     Coding harness to register the MCP server with: claude, codex, opencode.
+  --browser <b>     Browser the alias launches: arc, chrome, firefox.
+  --port <n>        Remote-debugging port (1-65535). Default: 9222 (chrome/arc), 9223 (firefox).
+  --name <name>     MCP server name to register. Default: ${DEFAULT_NAME}.
+  --alias-name <n>  Shell alias name. Default: cdp-<browser> (e.g. cdp-firefox).
+  --no-alias        Register the MCP server only; skip writing the shell alias.
+  --yes, -y         Skip the confirmation prompt (proceed immediately).
+  --help, -h        Show this help.
+
+Interactive: run \`cdp install\` in a terminal with no flags and it prompts for harness, browser,
+and port, then asks before writing anything.
+
+Non-interactive (piped/CI): pass at least --harness and --browser (port defaults per browser); a
+missing required value fails fast with usage instead of hanging on stdin.`;
+}
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await new Promise((resolve) => rl.question(question, resolve));
+  } finally {
+    rl.close();
+  }
+}
+async function promptMenu(label, options) {
+  const lines = [label];
+  options.forEach((o, i) => lines.push(`  ${i + 1}) ${o}`));
+  process.stdout.write(`${lines.join(`
+`)}
+`);
+  for (;; ) {
+    const ans = (await ask(`Enter 1-${options.length}: `)).trim();
+    const n = Number(ans);
+    if (Number.isInteger(n) && n >= 1 && n <= options.length)
+      return options[n - 1];
+    process.stdout.write(`Please enter a number between 1 and ${options.length}.
+`);
+  }
+}
+async function promptPort(def) {
+  for (;; ) {
+    const ans = (await ask(`Remote-debugging port [${def}]: `)).trim();
+    if (ans === "")
+      return def;
+    const n = Number(ans);
+    if (Number.isInteger(n) && n >= 1 && n <= 65535)
+      return n;
+    process.stdout.write(`Please enter an integer between 1 and 65535.
+`);
+  }
+}
+function harnessTargetDesc(harness, io) {
+  if (harness === "claude") {
+    return io.configPath ?? join14(io.homeDir ?? homedir3(), ".claude.json");
+  }
+  return `via \`${harness} mcp add\``;
+}
+function binEnvVar(browser) {
+  return `${browser.toUpperCase()}_BIN`;
+}
+async function runInstaller(argv, io = {}) {
+  const write = io.stdout ?? ((s) => void process.stdout.write(s));
+  const writeErr = io.stderr ?? ((s) => void process.stderr.write(s));
+  const isTTY = io.isTTY ?? Boolean(process.stdin.isTTY);
+  let args;
+  try {
+    args = parseInstallArgs(argv);
+  } catch (err) {
+    writeErr(`${err.message}
+
+`);
+    writeErr(`${installHelpText()}
+`);
+    return 1;
+  }
+  if (args.help) {
+    write(`${installHelpText()}
+`);
+    return 0;
+  }
+  let harness = args.harness;
+  let browser = args.browser;
+  let port = args.port;
+  if (isTTY) {
+    if (harness === undefined)
+      harness = await promptMenu("Which coding harness?", HARNESSES);
+    if (browser === undefined)
+      browser = await promptMenu("Which browser?", BROWSERS);
+    if (port === undefined)
+      port = await promptPort(defaultPortFor(browser));
+  } else {
+    const missing = [];
+    if (harness === undefined)
+      missing.push("--harness");
+    if (browser === undefined)
+      missing.push("--browser");
+    if (missing.length > 0) {
+      writeErr(`cdp install: missing required option(s) ${missing.join(", ")} in non-interactive mode.
+`);
+      writeErr("Run `cdp install` in a terminal to be prompted, or pass the option(s) explicitly.\n\n");
+      writeErr(`${installHelpText()}
+`);
+      return 1;
+    }
+    if (port === undefined)
+      port = defaultPortFor(browser);
+  }
+  if (harness === undefined || browser === undefined || port === undefined) {
+    writeErr(`cdp install: internal error resolving options
+`);
+    return 1;
+  }
+  const name = args.name ?? DEFAULT_NAME;
+  const writeAlias = args.alias !== false;
+  const rcPath = io.rcPath ?? detectShellRc();
+  const resolvedAliasName = args.aliasName ?? defaultAliasName(browser);
+  const line = aliasLine({ choice: browser, port, aliasName: args.aliasName });
+  if (!args.yes && isTTY) {
+    const plan = [
+      "",
+      "About to:",
+      `  - Register MCP server "${name}" with ${harness}  (${harnessTargetDesc(harness, io)})`,
+      writeAlias ? `  - Append a shell alias to ${rcPath}:
+      ${line}` : "  - (skipping shell alias: --no-alias)",
+      ""
+    ].join(`
+`);
+    write(`${plan}
+`);
+    const ans = (await ask("Proceed? [y/N] ")).trim();
+    if (!/^y(es)?$/i.test(ans)) {
+      write(`Aborted. Nothing was written.
+`);
+      return 0;
+    }
+  }
+  let harnessResult;
+  try {
+    harnessResult = await installMcpServer(harness, name, composeServerConfig(browser, port), {
+      configPath: io.configPath,
+      homeDir: io.homeDir
+    });
+  } catch (err) {
+    writeErr(`cdp install: could not register the MCP server with ${harness}: ${err.message}
+`);
+    return 1;
+  }
+  let rcResult;
+  let browserFound = true;
+  if (writeAlias) {
+    rcResult = await appendAliasToRc(rcPath, line);
+    browserFound = detectBrowser(browser).found;
+    if (!browserFound) {
+      writeErr(`
+Warning: could not find the ${browser} binary at its expected location. The alias was ` + `written anyway, but \`${resolvedAliasName}\` will not launch until the binary is found.
+` + `  Fix: set ${binEnvVar(browser)}=/path/to/${browser} and re-run \`cdp install\`, or edit the
+` + `  alias line in ${rcPath} to point at the real binary.
+`);
+    }
+  }
+  const summary = [
+    "",
+    "cdp-toolkit install complete.",
+    "",
+    `Harness: ${harness}`,
+    `  server name: ${name}`,
+    harnessResult.path ? `  config:      ${harnessResult.path}` : `  registered:  ${harnessTargetDesc(harness, io)}`,
+    `  method:      ${harnessResult.method}`,
+    `  action:      ${harnessResult.action}${harnessResult.detail ? `  (${harnessResult.detail})` : ""}`
+  ];
+  if (writeAlias && rcResult) {
+    summary.push("", `Browser alias: ${resolvedAliasName} -> ${rcResult.rcPath}`, `  action:  ${rcResult.action}`, `  line:    ${line}`);
+    if (!browserFound)
+      summary.push(`  note:    ${browser} binary not found yet (see warning above)`);
+  } else {
+    summary.push("", "Browser alias: skipped (--no-alias).");
+  }
+  summary.push("", "Next steps:");
+  if (writeAlias && rcResult) {
+    summary.push(`  1. Load the alias into your shell:  source ${rcResult.rcPath}   (or open a new terminal)`, `  2. Launch the browser with the debug port open:  ${resolvedAliasName}`, `  3. Restart / reconnect ${harness} so it picks up the "${name}" MCP server.`);
+    if (browser === "firefox") {
+      summary.push("", "Firefox note: the alias includes --marionette, which cdp-toolkit needs for its orphan", "auto-recovery path — don't remove it.");
+    }
+  } else {
+    summary.push(`  1. Restart / reconnect ${harness} so it picks up the "${name}" MCP server.`);
+  }
+  summary.push("");
+  write(`${summary.join(`
+`)}
+`);
+  return 0;
+}
+
 // src/cli.ts
 var USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
@@ -9034,6 +9920,9 @@ function printToolHelp(name) {
 }
 async function main() {
   const rawArgv = process.argv.slice(2);
+  if (rawArgv[0] === "install") {
+    return await runInstaller(rawArgv.slice(1));
+  }
   const { kind: browser, endpoint } = resolveBackend(rawArgv);
   const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));
   if (parsed.help) {