cdp-toolkit 1.9.7 → 1.11.0

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

package/src/install/wizard.ts

@@ -0,0 +1,412 @@
+/**
+ * `cdp install` — the interactive-or-flags installer that ties the two sibling install modules
+ * together into one command:
+ *
+ *   1. registers the cdp-toolkit MCP stdio server into the user's chosen coding harness
+ *      (claude / codex / opencode), via src/install/harness.ts, and
+ *   2. appends a shell alias that launches the user's chosen browser with the remote-debugging
+ *      port open, via src/install/browser.ts (the user chose AUTO-APPEND to the shell rc).
+ *
+ * This module owns ONLY the orchestration and the human interaction (flag parsing, interactive
+ * prompts, confirmation, summary). The actual writes — harness config and shell rc — are delegated
+ * to the two sibling modules; nothing here reimplements them.
+ *
+ * Test seams: runInstaller takes an `io` object whose `configPath` / `homeDir` (harness config
+ * target) and `rcPath` (shell rc target) let a test point every write at a temp file, so the
+ * installer can be exercised end-to-end without touching the real ~/.claude.json or ~/.zshrc.
+ * `stdout` / `stderr` default to the real process streams.
+ */
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  aliasLine,
+  appendAliasToRc,
+  defaultAliasName,
+  detectBrowser,
+  detectShellRc,
+  type BrowserChoice,
+  type RcAppendResult,
+} from "./browser.ts";
+import {
+  installMcpServer,
+  type HarnessChoice,
+  type InstallResult,
+  type McpServerConfig,
+} from "./harness.ts";
+
+export interface InstallArgs {
+  harness?: HarnessChoice;
+  browser?: BrowserChoice;
+  port?: number;
+  name?: string;
+  alias?: boolean;
+  aliasName?: string;
+  yes?: boolean;
+  help?: boolean;
+}
+
+export interface InstallerIO {
+  /** Whether we're attached to an interactive terminal. Defaults to process.stdin.isTTY. */
+  isTTY?: boolean;
+  /** Harness config path override (claude only). Test seam — points the write at a temp file. */
+  configPath?: string;
+  /** os.homedir() override when deriving the default claude config path. Test seam. */
+  homeDir?: string;
+  /** Shell rc path override. Test seam — points the alias append at a temp file. */
+  rcPath?: string;
+  /** stdout sink. Defaults to process.stdout.write. */
+  stdout?: (s: string) => void;
+  /** stderr sink. Defaults to process.stderr.write. */
+  stderr?: (s: string) => void;
+}
+
+const DEFAULT_NAME = "cdp-toolkit";
+const HARNESSES: readonly HarnessChoice[] = ["claude", "codex", "opencode"];
+const BROWSERS: readonly BrowserChoice[] = ["arc", "chrome", "firefox"];
+
+/* --------------------------------- pure: arg parsing --------------------------------- */
+
+/** Default remote-debugging port per browser: firefox listens on 9223 here, chromium on 9222. */
+function defaultPortFor(browser: BrowserChoice): number {
+  return browser === "firefox" ? 9223 : 9222;
+}
+
+function parseHarness(v: string | undefined): HarnessChoice {
+  if (v === undefined) throw new Error("--harness requires a value: claude, codex, or opencode");
+  if ((HARNESSES as readonly string[]).includes(v)) return v as HarnessChoice;
+  throw new Error(`--harness must be one of claude|codex|opencode (got '${v}')`);
+}
+
+function parseBrowserChoice(v: string | undefined): BrowserChoice {
+  if (v === undefined) throw new Error("--browser requires a value: arc, chrome, or firefox");
+  if ((BROWSERS as readonly string[]).includes(v)) return v as BrowserChoice;
+  throw new Error(`--browser must be one of arc|chrome|firefox (got '${v}')`);
+}
+
+function parsePort(v: string | undefined): number {
+  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;
+}
+
+/** Expand `--key=value` into `["--key", "value"]` so both forms parse; leaves everything else alone. */
+function normalizeArgv(argv: string[]): string[] {
+  const out: string[] = [];
+  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;
+}
+
+/**
+ * PURE. Parse `cdp install` flags. Throws on an unknown option, a missing required value, or an
+ * out-of-range/enum-invalid value. Defaults: name="cdp-toolkit", alias=true.
+ */
+export function parseInstallArgs(argv: string[]): InstallArgs {
+  const tokens = normalizeArgv(argv);
+  const out: InstallArgs = { 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;
+}
+
+/* --------------------------------- pure: server config --------------------------------- */
+
+/**
+ * PURE. Build the MCP stdio server config for a given browser + debug port.
+ *
+ * The server always runs `npx -y cdp-toolkit`. Only the env differs by browser, and even then
+ * chrome and arc are IDENTICAL: both are driven over CDP, and the driver just talks CDP to
+ * whatever is listening on CDP_BASE — the arc-vs-chrome distinction lives entirely in the shell
+ * ALIAS (which .app it launches), not in the server env. Firefox is the odd one out: it is driven
+ * over WebDriver BiDi, selected by CDP_BROWSER=firefox with the port in CDP_FIREFOX_ENDPOINT.
+ */
+export function composeServerConfig(browser: BrowserChoice, port: number): McpServerConfig {
+  const env: Record<string, string> =
+    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 };
+}
+
+/* --------------------------------- help text --------------------------------- */
+
+export function installHelpText(): string {
+  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.`;
+}
+
+/* --------------------------------- interactive prompts --------------------------------- */
+
+/** One question over a fresh readline interface, closed before returning. Reached only when TTY. */
+async function ask(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await new Promise<string>((resolve) => rl.question(question, resolve));
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptMenu<T extends string>(label: string, options: readonly T[]): Promise<T> {
+  const lines = [label];
+  options.forEach((o, i) => lines.push(`  ${i + 1}) ${o}`));
+  process.stdout.write(`${lines.join("\n")}\n`);
+  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}.\n`);
+  }
+}
+
+async function promptPort(def: number): Promise<number> {
+  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.\n");
+  }
+}
+
+/* --------------------------------- helpers --------------------------------- */
+
+/** Where the harness config lands, for the pre-write plan. claude → a file path; others → the CLI. */
+function harnessTargetDesc(harness: HarnessChoice, io: InstallerIO): string {
+  if (harness === "claude") {
+    return io.configPath ?? join(io.homeDir ?? homedir(), ".claude.json");
+  }
+  return `via \`${harness} mcp add\``;
+}
+
+/** The env var that overrides binary detection for a given browser (see src/install/browser.ts). */
+function binEnvVar(browser: BrowserChoice): string {
+  return `${browser.toUpperCase()}_BIN`;
+}
+
+/* --------------------------------- orchestration --------------------------------- */
+
+/**
+ * Run the installer. Returns a process exit code (0 success, 1 failure). Never throws for an
+ * expected condition (bad flags, missing CLI, missing required option in a pipe) — those are
+ * reported to stderr and return 1.
+ */
+export async function runInstaller(argv: string[], io: InstallerIO = {}): Promise<number> {
+  const write = io.stdout ?? ((s: string) => void process.stdout.write(s));
+  const writeErr = io.stderr ?? ((s: string) => void process.stderr.write(s));
+  const isTTY = io.isTTY ?? Boolean(process.stdin.isTTY);
+
+  // 1. parse
+  let args: InstallArgs;
+  try {
+    args = parseInstallArgs(argv);
+  } catch (err) {
+    writeErr(`${(err as Error).message}\n\n`);
+    writeErr(`${installHelpText()}\n`);
+    return 1;
+  }
+
+  if (args.help) {
+    write(`${installHelpText()}\n`);
+    return 0;
+  }
+
+  // 2. resolve harness/browser/port — prompt when interactive, fail fast in a pipe.
+  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: string[] = [];
+    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.\n`);
+      writeErr("Run `cdp install` in a terminal to be prompted, or pass the option(s) explicitly.\n\n");
+      writeErr(`${installHelpText()}\n`);
+      return 1;
+    }
+    if (port === undefined) port = defaultPortFor(browser!);
+  }
+
+  if (harness === undefined || browser === undefined || port === undefined) {
+    // Unreachable: both branches above set all three or return. Defensive for the type-checker.
+    writeErr("cdp install: internal error resolving options\n");
+    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 });
+
+  // 3. confirm the plan (interactive only; --yes or a fully-specified pipe run proceeds).
+  if (!args.yes && isTTY) {
+    const plan = [
+      "",
+      "About to:",
+      `  - Register MCP server "${name}" with ${harness}  (${harnessTargetDesc(harness, io)})`,
+      writeAlias
+        ? `  - Append a shell alias to ${rcPath}:\n      ${line}`
+        : "  - (skipping shell alias: --no-alias)",
+      "",
+    ].join("\n");
+    write(`${plan}\n`);
+    const ans = (await ask("Proceed? [y/N] ")).trim();
+    if (!/^y(es)?$/i.test(ans)) {
+      write("Aborted. Nothing was written.\n");
+      return 0;
+    }
+  }
+
+  // 4. register the MCP server.
+  let harnessResult: InstallResult;
+  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 as Error).message}\n`);
+    return 1;
+  }
+
+  // 5. append the shell alias (unless --no-alias). A missing browser binary is a WARNING, not a
+  //    failure: the alias is still written, but we tell the user it won't launch until they fix it.
+  let rcResult: RcAppendResult | undefined;
+  let browserFound = true;
+  if (writeAlias) {
+    rcResult = await appendAliasToRc(rcPath, line);
+    browserFound = detectBrowser(browser).found;
+    if (!browserFound) {
+      writeErr(
+        `\nWarning: 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.\n` +
+          `  Fix: set ${binEnvVar(browser)}=/path/to/${browser} and re-run \`cdp install\`, or edit the\n` +
+          `  alias line in ${rcPath} to point at the real binary.\n`,
+      );
+    }
+  }
+
+  // 6. summary + next steps.
+  const summary: string[] = [
+    "",
+    "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("\n")}\n`);
+  return 0;
+}