cdp-toolkit 1.10.0 → 2.0.0

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" };
+}

package/src/install/harness.ts

@@ -0,0 +1,224 @@
+/**
+ * Registering the cdp-toolkit MCP stdio server into a coding-agent harness.
+ *
+ * Three harnesses, three different registration mechanisms, chosen per-harness
+ * from what was actually verified against real on-disk configs, the official
+ * docs, and the installed CLIs (not assumed):
+ *
+ * - claude: `claude mcp add` is NOT an upsert — it errors on a duplicate
+ *   server name. So this does a direct read-modify-write of the JSON config
+ *   (~/.claude.json) instead, which is naturally idempotent: same input in,
+ *   same file out, unrelated keys and servers preserved untouched.
+ * - codex: no confirmed idempotent single command, so this shells out to
+ *   `codex mcp add`, first checking `codex mcp get <name>` and doing a
+ *   remove-then-add when the name already exists.
+ * - opencode: `opencode mcp add` is a confirmed idempotent upsert (verified
+ *   against its source), so this just shells out to it directly.
+ *
+ * Only the pure argv builders (codexAddArgs, opencodeAddArgs) and the
+ * claude-side JSON shape are exported for unit testing; the codex/opencode
+ * shell-outs are not covered by tests here because doing so would mean either
+ * running the real CLIs or mocking node:child_process, and the spec for this
+ * module calls only for testing the pure builders plus the claude RMW path.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type HarnessChoice = "claude" | "codex" | "opencode";
+
+export interface McpServerConfig {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+export interface InstallResult {
+  harness: HarnessChoice;
+  method: "file" | "cli";
+  path?: string;
+  action: "added" | "updated" | "unchanged";
+  detail?: string;
+}
+
+export interface InstallOpts {
+  /** Overrides the on-disk config path (claude only). For tests. */
+  configPath?: string;
+  /** Overrides os.homedir() when deriving the default config path (claude only). For tests. */
+  homeDir?: string;
+}
+
+export async function installMcpServer(
+  harness: HarnessChoice,
+  name: string,
+  cfg: McpServerConfig,
+  opts: InstallOpts = {},
+): Promise<InstallResult> {
+  switch (harness) {
+    case "claude":
+      return installClaude(name, cfg, opts);
+    case "codex":
+      return installCodex(name, cfg);
+    case "opencode":
+      return installOpencode(name, cfg);
+    default: {
+      const exhaustive: never = harness;
+      throw new Error(`unknown harness: ${String(exhaustive)}`);
+    }
+  }
+}
+
+/* ------------------------------- claude: file RMW ------------------------------- */
+
+async function installClaude(name: string, cfg: McpServerConfig, opts: InstallOpts): Promise<InstallResult> {
+  const path = opts.configPath ?? join(opts.homeDir ?? homedir(), ".claude.json");
+
+  let root: Record<string, unknown>;
+  let fileExisted: boolean;
+  try {
+    const text = await readFile(path, "utf8");
+    const parsed: unknown = 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 as Record<string, unknown>;
+    fileExisted = true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      root = {};
+      fileExisted = false;
+    } else {
+      throw err;
+    }
+  }
+
+  const rawServers = root.mcpServers;
+  const mcpServers: Record<string, unknown> =
+    typeof rawServers === "object" && rawServers !== null && !Array.isArray(rawServers)
+      ? (rawServers as Record<string, unknown>)
+      : {};
+  root.mcpServers = mcpServers;
+
+  // No `type` field: stdio is the implicit default for this shape in
+  // ~/.claude.json, and adding one would diverge from what `claude mcp add`
+  // itself writes for a stdio server.
+  const entry: Record<string, unknown> = { command: cfg.command, args: cfg.args };
+  if (Object.keys(cfg.env).length > 0) entry.env = cfg.env;
+
+  const prior = mcpServers[name];
+  const action: InstallResult["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 mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(root, null, 2) + "\n", "utf8");
+
+  return {
+    harness: "claude",
+    method: "file",
+    path,
+    action,
+    detail: fileExisted ? undefined : "created new config file",
+  };
+}
+
+/** Deep-equality via a key-sorted JSON string, so key order never causes a false "updated". */
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/* -------------------------------- codex: CLI shell-out -------------------------------- */
+
+/** Pure argv builder (argv AFTER `codex`), exported for unit tests. */
+export function codexAddArgs(name: string, cfg: McpServerConfig): string[] {
+  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: string, cfg: McpServerConfig): Promise<InstallResult> {
+  if (!isOnPath("codex")) {
+    throw new Error("codex CLI not found on PATH — install Codex or pick a different harness");
+  }
+
+  // codex mcp add is not confirmed idempotent upstream, so probe first and
+  // remove-then-add when the name already exists.
+  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,
+  };
+}
+
+/* ------------------------------ opencode: CLI shell-out ------------------------------- */
+
+/** Pure argv builder (argv AFTER `opencode`), exported for unit tests. */
+export function opencodeAddArgs(name: string, cfg: McpServerConfig): string[] {
+  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: string, cfg: McpServerConfig): Promise<InstallResult> {
+  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()}`);
+  }
+
+  // `opencode mcp add` is a confirmed idempotent upsert, and telling "added"
+  // from "updated" cheaply would mean an extra `opencode mcp get` round trip
+  // whose output shape isn't confirmed; "added" is accurate enough either way
+  // since the end state (server registered with this config) is identical.
+  return {
+    harness: "opencode",
+    method: "cli",
+    action: "added",
+    detail: added.stdout?.trim() || undefined,
+  };
+}
+
+/* ---------------------------------- shared helpers ------------------------------------ */
+
+function isOnPath(bin: string): boolean {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(finder, [bin], { encoding: "utf8" });
+  return result.status === 0;
+}