@browserbridge/bbx 1.7.4 → 1.7.6

package/packages/agent-client/src/cli.js

@@ -4,74 +4,42 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
-import {
-  applyWindowsTcpTransportDefaults,
-  createTcpBridgeTransport,
-  getProxyConfigPath,
-  readProxyConfig,
-  SUPPORTED_BROWSERS,
-} from '../../native-host/src/config.js';
-import { writeBridgeAuthToken } from '../../native-host/src/auth-token.js';
-import { pingExistingDaemon } from '../../native-host/src/daemon.js';
+import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
-import { uninstallNativeManifest } from '../../native-host/src/install-manifest.js';
+import { createRuntimeContext, METHODS } from '../../protocol/src/index.js';
 import {
-  createRuntimeContext,
-  getProtocolVersion,
-  METHODS,
-  summarizeBatchErrorItem,
-  summarizeBatchResponseItem,
-} from '../../protocol/src/index.js';
+  restartRegisteredMcpProcesses,
+  tryStartMcpProcessControl,
+} from '../../mcp-server/src/lifecycle.js';
 import { startBridgeMcpServer } from '../../mcp-server/src/server.js';
-import { CLI_HELP_SECTIONS, SHORTCUT_COMMANDS } from './command-registry.js';
-import {
-  interactiveCheckbox,
-  interactiveConfirm,
-  methodNeedsTab,
-  parseIntArg,
-  parseJsonObject,
-  sanitizeOutput,
-} from './cli-helpers.js';
 import {
-  findInstalledManagedTargets,
-  installAgentFiles,
-  installMcpClientSetup,
-  parseInstallAgentArgs,
-  removeAgentFiles,
-  SUPPORTED_TARGETS,
-  TARGET_LABELS,
-} from './install.js';
+  extractRemoteFlag,
+  extractTabFlag,
+  parseCallCommand,
+  parseInterceptAddArgs,
+  readStdin,
+} from './cli-args.js';
+import { runBatchCalls } from './cli-batch.js';
+import { parseIntArg } from './cli-helpers.js';
+import { printCallResponse, printJson, printSummary, printUsage } from './cli-output.js';
+import { handleProxyCommand, handleRemoteCommand } from './cli-proxy-remote.js';
 import {
-  findConfiguredMcpClients,
-  formatMcpConfig,
-  isMcpClientName,
-  MCP_CLIENT_LABELS,
-  MCP_CLIENT_NAMES,
-  removeMcpConfig,
-} from './mcp-config.js';
+  runInstallMcpCommand,
+  runInstallSkillCommand,
+  uninstallBrowserBridge,
+} from './cli-setup-commands.js';
+import { SHORTCUT_COMMANDS } from './command-registry.js';
+import { formatMcpConfig, isMcpClientName, MCP_CLIENT_NAMES } from './mcp-config.js';
 import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
-import {
-  addRemoteDestination,
-  createBridgeClientForDestination,
-  listBridgeDestinations,
-  normalizeDestinationId,
-  parseRemoteEndpoint,
-  readRemoteConfig,
-  removeRemoteDestination,
-  resolveProxyEnableSettings,
-} from './remotes.js';
-import { collectSetupStatus } from './setup-status.js';
-import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
+import { createBridgeClientForDestination } from './remotes.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').ScreenshotResult} ScreenshotResult */
 
 const REQUEST_SOURCE = 'cli';
 const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
-const TEST_DETECTED_MCP_CLIENTS_ENV = 'BBX_TEST_DETECTED_MCP_CLIENTS';
 const REMOTE_ENV = 'BBX_REMOTE';
 
 /**
@@ -99,25 +67,6 @@ const LOCAL_ONLY_COMMANDS = new Set([
   'restart',
 ]);
 
-/**
- * Read all of stdin as UTF-8 text. Resolves once stdin closes.
- *
- * @returns {Promise<string>}
- */
-function readStdin() {
-  return new Promise((resolve, reject) => {
-    const chunks = /** @type {Buffer[]} */ ([]);
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
-    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8').trim()));
-    process.stdin.on('error', reject);
-    // If stdin is a TTY and nothing is piped, read nothing
-    if (process.stdin.isTTY) {
-      resolve('');
-    }
-  });
-}
-
 const remoteFlag = extractRemoteFlag(process.argv.slice(2));
 const [command, ...rest] = remoteFlag.rest;
 
@@ -155,7 +104,6 @@ if (command === 'skill') {
 
 if (command === 'install') {
   const { execFileSync } = await import('node:child_process');
-  const { fileURLToPath } = await import('node:url');
   const installScript = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
     '../../native-host/bin/install-manifest.js'
@@ -177,250 +125,23 @@ if (command === 'uninstall') {
 }
 
 if (command === 'install-skill') {
-  // When no positional target is given, detect installed agents and prompt.
-  const positional = rest.filter((a) => !a.startsWith('--'));
-
-  if (positional.length === 0) {
-    let scopeOptions;
-    try {
-      scopeOptions = parseInstallAgentArgs(rest);
-    } catch (error) {
-      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-      process.exit(1);
-    }
-
-    const isGlobal = scopeOptions.global !== false;
-    const projectPath = isGlobal ? os.homedir() : scopeOptions.projectPath;
-
-    const setupStatus = await collectSetupStatus({
-      global: isGlobal,
-      cwd: process.cwd(),
-      projectPath,
-      ...getSetupStatusTestOverrides(),
-    });
-    /** @type {import('./types.js').SupportedTarget[]} */
-    const detected = /** @type {import('./types.js').SupportedTarget[]} */ (
-      setupStatus.skillTargets.filter((entry) => entry.detected).map((entry) => entry.key)
-    );
-    const installedManagedTargets = new Set(
-      setupStatus.skillTargets
-        .filter((entry) => entry.installed && entry.managed)
-        .map((entry) => entry.key)
-    );
-    const installedManagedTargetList =
-      /** @type {import('./types.js').SupportedTarget[]} */ ([...installedManagedTargets]);
-
-    // Aliases like 'openai' and 'google' map to canonical targets and stay omitted.
-    const items = SUPPORTED_TARGETS.map((t) => ({
-      value: t,
-      label: `${t.padEnd(10)}  ${TARGET_LABELS[t]}`,
-      hint: formatSelectionHint({
-        detected: detected.includes(t),
-        installed: installedManagedTargets.has(t),
-      }),
-      checked: installedManagedTargets.has(t),
-    }));
-
-    const selected = await interactiveCheckbox(
-      'Select agents to install skill for  (↑↓ move · space toggle · a all · enter confirm)',
-      items
-    );
-
-    /** @type {import('./types.js').SupportedTarget[]} */
-    let targets;
-    if (selected === null) {
-      // Non-TTY: prefer managed installs, then detected targets (always includes 'agents').
-      targets = installedManagedTargets.size > 0 ? installedManagedTargetList : detected;
-    } else {
-      targets = /** @type {import('./types.js').SupportedTarget[]} */ (selected);
-    }
-
-    if (selected !== null) {
-      const deselectedTargets =
-        /** @type {import('./types.js').SupportedTarget[]} */ (
-          installedManagedTargetList.filter((target) => !targets.includes(target))
-        );
-      const removableTargets = await findInstalledManagedTargets({
-        targets: deselectedTargets,
-        projectPath,
-        global: isGlobal,
-      });
-      if (removableTargets.length > 0) {
-        const confirmed = await interactiveConfirm(
-          `Remove Browser Bridge skill from deselected targets: ${removableTargets.join(', ')}?`
-        );
-        if (confirmed) {
-          const removedPaths = await removeAgentFiles({
-            targets: removableTargets,
-            projectPath,
-            global: isGlobal,
-          });
-          for (const p of removedPaths) process.stdout.write(`Removed ${p}\n`);
-        }
-      }
-    }
-
-    if (targets.length === 0) {
-      process.stdout.write('No targets selected.\n');
-      process.exit(0);
-    }
-
-    const installedPaths = await installAgentFiles({
-      targets,
-      projectPath,
-      global: isGlobal,
-    });
-    for (const p of installedPaths) process.stdout.write(`Installed ${p}\n`);
-    process.exit(0);
-  }
-
-  // Explicit targets or 'all' provided - use existing arg-parsing logic.
-  const options = parseInstallAgentArgs(rest);
-  const installedPaths = await installAgentFiles(options);
-  for (const installedPath of installedPaths) {
-    process.stdout.write(`Installed ${installedPath}\n`);
-  }
-  process.exit(0);
+  await runInstallSkillCommand(rest);
 }
 
 if (command === 'install-mcp') {
-  let isGlobal = true;
-  /** @type {string[]} */
-  const positionals = [];
-
-  for (const arg of rest) {
-    if (arg === '--local') {
-      isGlobal = false;
-      continue;
-    }
-    if (arg === '--global') {
-      isGlobal = true;
-      continue;
-    }
-    if (arg.startsWith('--')) {
-      process.stderr.write(`Unknown install-mcp option "${arg}".\n`);
-      process.exit(1);
-    }
-    positionals.push(arg);
-  }
-
-  if (positionals.length > 1) {
-    process.stderr.write(`Unexpected extra argument "${positionals[1]}".\n`);
-    process.exit(1);
-  }
-
-  const clientArg = positionals[0];
-
-  /** @type {import('./types.js').McpClientName[]} */
-  let clients;
-
-  if (!clientArg) {
-    // No client specified: inspect current MCP config and prompt interactively.
-    const setupStatus = await collectSetupStatus({
-      global: isGlobal,
-      cwd: process.cwd(),
-      projectPath: process.cwd(),
-      ...getSetupStatusTestOverrides(),
-    });
-    const detected = /** @type {import('./types.js').McpClientName[]} */ (
-      setupStatus.mcpClients.filter((entry) => entry.detected).map((entry) => entry.key)
-    );
-    const configuredClients = new Set(
-      setupStatus.mcpClients.filter((entry) => entry.configured).map((entry) => entry.key)
-    );
-    const configuredClientList =
-      /** @type {import('./types.js').McpClientName[]} */ ([...configuredClients]);
-    const items = MCP_CLIENT_NAMES.map((c) => ({
-      value: c,
-      label: `${c.padEnd(10)}  ${MCP_CLIENT_LABELS[c]}`,
-      hint: formatSelectionHint({
-        detected: detected.includes(c),
-        installed: configuredClients.has(c),
-      }),
-      checked: configuredClients.has(c),
-    }));
-
-    const selected = await interactiveCheckbox(
-      'Select clients to configure  (↑↓ move · space toggle · a all · enter confirm)',
-      items
-    );
-
-    if (selected === null) {
-      // Non-TTY: prefer configured clients, then detected clients, then all.
-      clients =
-        configuredClients.size > 0
-          ? configuredClientList
-          : detected.length > 0
-            ? detected
-            : [...MCP_CLIENT_NAMES];
-    } else {
-      clients = /** @type {import('./types.js').McpClientName[]} */ (selected);
-    }
-
-    if (selected !== null) {
-      const deselectedClients =
-        /** @type {import('./types.js').McpClientName[]} */ (
-          configuredClientList.filter((clientName) => !clients.includes(clientName))
-        );
-      const removableClients = await findConfiguredMcpClients({
-        clients: deselectedClients,
-        global: isGlobal,
-        cwd: process.cwd(),
-      });
-      if (removableClients.length > 0) {
-        const confirmed = await interactiveConfirm(
-          `Remove Browser Bridge MCP config from deselected clients: ${removableClients.join(', ')}?`
-        );
-        if (confirmed) {
-          for (const clientName of removableClients) {
-            await removeMcpConfig(clientName, {
-              global: isGlobal,
-              cwd: process.cwd(),
-            });
-          }
-        }
-      }
-    }
-
-    if (clients.length === 0) {
-      process.stdout.write('No clients selected.\n');
-      process.exit(0);
-    }
-  } else if (clientArg === 'all') {
-    clients = [...MCP_CLIENT_NAMES];
-  } else {
-    const parts = clientArg
-      .split(',')
-      .map((s) => s.trim().toLowerCase())
-      .filter(Boolean);
-    if (parts.includes('all')) {
-      clients = [...MCP_CLIENT_NAMES];
-    } else {
-      clients = [];
-      for (const part of parts) {
-        if (!isMcpClientName(part)) {
-          process.stderr.write(
-            `Unknown client "${part}". Supported: ${MCP_CLIENT_NAMES.join(', ')}, all\n`
-          );
-          process.exit(1);
-        }
-        clients.push(part);
-      }
-    }
-  }
-
-  await installMcpClientSetup(clients, {
-    global: isGlobal,
-    projectPath: process.cwd(),
-    stdout: process.stdout,
-  });
-  process.exit(0);
+  await runInstallMcpCommand(rest);
 }
 
 if (command === 'mcp') {
   const [subcommand, clientName] = rest;
   if (subcommand === 'serve') {
-    await startBridgeMcpServer();
+    const control = await tryStartMcpProcessControl();
+    try {
+      await startBridgeMcpServer();
+    } catch (error) {
+      await control?.dispose();
+      throw error;
+    }
     await new Promise(() => {});
   }
   if (subcommand === 'config') {
@@ -528,12 +249,26 @@ async function main() {
 
     if (command === 'restart') {
       const result = await restartBridgeDaemon();
+      const mcpProcesses = await restartRegisteredMcpProcesses();
+      if (mcpProcesses.restartFailed > 0) {
+        process.exitCode = 1;
+      }
       printJson({
-        ok: true,
-        summary: result.previouslyRunning
-          ? 'Browser Bridge daemon restarted.'
-          : 'Browser Bridge daemon started.',
-        evidence: result,
+        ok: mcpProcesses.restartFailed === 0,
+        summary: `${
+          result.previouslyRunning
+            ? 'Browser Bridge daemon restarted.'
+            : 'Browser Bridge daemon started.'
+        }${
+          mcpProcesses.restartRequested > 0
+            ? ` Restart requested for ${mcpProcesses.restartRequested} MCP server(s).`
+            : ''
+        }${
+          mcpProcesses.restartFailed > 0
+            ? ` Could not contact ${mcpProcesses.restartFailed} MCP server(s).`
+            : ''
+        }`,
+        evidence: { ...result, mcpProcesses },
       });
       return;
     }
@@ -607,83 +342,10 @@ async function main() {
     }
 
     if (command === 'batch') {
-      const input = rest[0];
-      if (!input) {
-        throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
-      }
-      let calls;
-      try {
-        calls = JSON.parse(input);
-      } catch {
-        throw new Error('Invalid JSON syntax. Expected a JSON array of bridge calls.');
-      }
-      if (!Array.isArray(calls)) {
-        throw new Error('Batch input must be a JSON array.');
+      const results = await runBatchCalls(client, rest[0], REQUEST_SOURCE);
+      if (results.some((result) => !result.ok)) {
+        process.exitCode = 1;
       }
-      await ensureClientConnection();
-      const results = await Promise.all(
-        calls.map(async (call) => {
-          if (!call || typeof call !== 'object' || typeof call.method !== 'string') {
-            return {
-              method: '',
-              tabId: null,
-              ok: false,
-              summary: 'INVALID_REQUEST: Each batch call needs a method.',
-              evidence: null,
-              durationMs: 0,
-              approxTokens: 0,
-              meta: { protocol_version: getProtocolVersion() },
-              error: {
-                code: 'INVALID_REQUEST',
-                message: 'Each batch call needs a method.',
-              },
-              response: null,
-            };
-          }
-          if (!METHODS.includes(/** @type {BridgeMethod} */ (call.method))) {
-            return {
-              method: call.method,
-              tabId: null,
-              ok: false,
-              summary: `INVALID_REQUEST: Unknown bridge method "${call.method}".`,
-              evidence: null,
-              durationMs: 0,
-              approxTokens: 0,
-              meta: { protocol_version: getProtocolVersion() },
-              error: {
-                code: 'INVALID_REQUEST',
-                message: `Unknown bridge method "${call.method}".`,
-              },
-              response: null,
-            };
-          }
-          const method = /** @type {BridgeMethod} */ (call.method);
-          const tabId =
-            methodNeedsTab(call.method) && typeof call.tabId === 'number' ? call.tabId : null;
-          const startTime = Date.now();
-          try {
-            const response = await client.request({
-              method,
-              tabId,
-              params: call.params || {},
-              meta: { source: REQUEST_SOURCE },
-            });
-            return summarizeBatchResponseItem({
-              method,
-              tabId,
-              response,
-              durationMs: Date.now() - startTime,
-            });
-          } catch (err) {
-            return summarizeBatchErrorItem({
-              method,
-              tabId,
-              error: err,
-              durationMs: Date.now() - startTime,
-            });
-          }
-        })
-      );
       printJson(results);
       return;
     }
@@ -817,22 +479,7 @@ async function main() {
       const { tabId, rest: iArgs } = extractTabFlag(rest);
       const sub = iArgs[0];
       if (sub === 'add') {
-        const pattern = iArgs[1];
-        if (!pattern)
-          throw new Error(
-            'Usage: intercept add <urlPattern> [--respond <body>] [--status <code>] [--block]'
-          );
-        const isBlock = iArgs.includes('--block');
-        const statusIdx = iArgs.indexOf('--status');
-        const statusCode = statusIdx !== -1 ? parseIntArg(iArgs[statusIdx + 1], 'status') : 200;
-        const respondIdx = iArgs.indexOf('--respond');
-        const body =
-          respondIdx !== -1
-            ? iArgs
-                .slice(respondIdx + 1)
-                .filter((a) => !a.startsWith('--'))
-                .join(' ')
-            : undefined;
+        const { pattern, isBlock, statusCode, body } = parseInterceptAddArgs(iArgs.slice(1));
         const response = await requestBridge(
           client,
           'network.intercept.add',
@@ -847,7 +494,9 @@ async function main() {
         await printSummary(response);
       } else if (sub === 'remove') {
         const ruleId = iArgs[1];
-        if (!ruleId) throw new Error('Usage: intercept remove <ruleId>');
+        if (!ruleId || iArgs.length !== 2) {
+          throw new Error('Usage: intercept remove <ruleId>');
+        }
         const response = await requestBridge(
           client,
           'network.intercept.remove',
@@ -856,6 +505,9 @@ async function main() {
         );
         await printSummary(response);
       } else if (sub === 'list') {
+        if (iArgs.length !== 1) {
+          throw new Error('Usage: intercept list');
+        }
         const response = await requestBridge(
           client,
           'network.intercept.list',
@@ -864,6 +516,9 @@ async function main() {
         );
         await printSummary(response);
       } else if (sub === 'clear') {
+        if (iArgs.length !== 1) {
+          throw new Error('Usage: intercept clear');
+        }
         const response = await requestBridge(
           client,
           'network.intercept.clear',
@@ -931,291 +586,6 @@ async function main() {
   }
 }
 
-/**
- * @param {string[]} args
- * @returns {Promise<void>}
- */
-async function handleProxyCommand(args) {
-  const [subcommand, ...restArgs] = args;
-  if (subcommand === 'enable') {
-    const options = parseProxyEnableArgs(restArgs);
-    const existing = readProxyConfig();
-    const { port, bindHost, token, tokenSource } = resolveProxyEnableSettings(
-      existing,
-      options,
-      randomUUID
-    );
-    await writeBridgeAuthToken(token);
-    const configPath = getProxyConfigPath();
-    await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-    await fs.promises.writeFile(
-      configPath,
-      `${JSON.stringify(
-        {
-          enabled: true,
-          port,
-          bindHost,
-          token,
-        },
-        null,
-        2
-      )}\n`,
-      { encoding: 'utf8', mode: 0o600 }
-    );
-    const result = await restartBridgeDaemon();
-    const exampleHost = getProxyExampleHost(bindHost);
-    const tokenNote =
-      tokenSource === 'existing'
-        ? ' (unchanged - already-configured clients keep working; pass --rotate-token to generate a new secret)'
-        : tokenSource === 'generated' && existing
-          ? ' (rotated - update every configured client with `bbx remote add`)'
-          : '';
-    const lines = [
-      `Browser Bridge proxy enabled on ${bindHost}:${port}.`,
-      '',
-      `Token: ${token}${tokenNote}`,
-      `Config: ${configPath}`,
-      `Daemon: ${result.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
-    ];
-    if (tokenSource !== 'existing') {
-      lines.push(
-        '',
-        'On your dev machine, add this remote:',
-        '',
-        `bbx remote add <name> <host:port> --token ${token}`,
-        '',
-        'Example:',
-        '',
-        `bbx remote add remote-bbx ${exampleHost}:${port} --token ${token}`
-      );
-    }
-    lines.push('');
-    process.stdout.write(lines.join('\n'));
-    return;
-  }
-
-  if (subcommand === 'disable') {
-    const configPath = getProxyConfigPath();
-    await fs.promises.rm(configPath, { force: true });
-    const result = await restartBridgeDaemon();
-    process.stdout.write(
-      `Browser Bridge proxy disabled. Daemon ${result.previouslyRunning ? 'restarted' : 'started'}.\n`
-    );
-    return;
-  }
-
-  if (subcommand === 'status') {
-    const config = readProxyConfig();
-    if (!config) {
-      process.stdout.write('Browser Bridge proxy is disabled.\n');
-      return;
-    }
-    const reachable = await pingExistingDaemon(createTcpBridgeTransport(config.port, '127.0.0.1'));
-    process.stdout.write(
-      [
-        `Browser Bridge proxy is enabled on ${config.bindHost}:${config.port}.`,
-        `Config: ${getProxyConfigPath()}`,
-        `Daemon: ${reachable ? 'reachable' : 'not reachable'} on 127.0.0.1:${config.port}`,
-        '',
-      ].join('\n')
-    );
-    return;
-  }
-
-  throw new Error('Usage: bbx proxy <enable|disable|status>');
-}
-
-/**
- * Parse `bbx proxy enable` flags. Values stay undefined when not passed so an
- * existing proxy config can be reused instead of silently reset to defaults.
- *
- * @param {string[]} args
- * @returns {import('./remotes.js').ProxyEnableOptions}
- */
-function parseProxyEnableArgs(args) {
-  /** @type {import('./remotes.js').ProxyEnableOptions} */
-  const options = {};
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === '--port') {
-      options.port = parseIntArg(args[++index] || '', 'port');
-      continue;
-    }
-    if (arg === '--bind-host') {
-      options.bindHost = args[++index] || '';
-      if (!options.bindHost.trim()) {
-        throw new Error('--bind-host requires a value.');
-      }
-      continue;
-    }
-    if (arg === '--token') {
-      options.token = args[++index] || '';
-      if (!options.token.trim()) {
-        throw new Error('--token requires a value.');
-      }
-      continue;
-    }
-    if (arg === '--rotate-token') {
-      options.rotateToken = true;
-      continue;
-    }
-    throw new Error(`Unknown proxy enable option "${arg}".`);
-  }
-  if (options.token && options.rotateToken) {
-    throw new Error('Use either --token or --rotate-token, not both.');
-  }
-  if (options.port !== undefined && (options.port < 1 || options.port > 65535)) {
-    throw new Error('port must be an integer between 1 and 65535.');
-  }
-  return options;
-}
-
-/**
- * @param {string} bindHost
- * @returns {string}
- */
-function getProxyExampleHost(bindHost) {
-  if (bindHost !== '0.0.0.0' && bindHost !== '::') {
-    return bindHost;
-  }
-
-  /** @type {string | null} */
-  let firstIpv4 = null;
-  for (const [name, entries] of Object.entries(os.networkInterfaces())) {
-    for (const entry of entries ?? []) {
-      if (!entry.internal && entry.family === 'IPv4') {
-        if (name.toLowerCase() === 'ethernet 0') {
-          return entry.address;
-        }
-        firstIpv4 ??= entry.address;
-      }
-    }
-  }
-
-  return firstIpv4 ?? '<host>';
-}
-
-/**
- * @param {string[]} args
- * @returns {Promise<void>}
- */
-async function handleRemoteCommand(args) {
-  const [subcommand, ...restArgs] = args;
-  if (subcommand === 'add') {
-    const [name, endpoint, ...optionArgs] = restArgs;
-    if (!name || !endpoint) {
-      throw new Error('Usage: bbx remote add <name> <host:port> --token <token>');
-    }
-    const token = parseRemoteTokenOption(optionArgs);
-    const { host, port } = parseRemoteEndpoint(endpoint);
-    const remote = await addRemoteDestination({
-      id: normalizeDestinationId(name),
-      host,
-      port,
-      token,
-    });
-    process.stdout.write(
-      `Remote destination "${remote.id}" saved (${remote.host}:${remote.port}).\n`
-    );
-    return;
-  }
-
-  if (subcommand === 'remove') {
-    const [name] = restArgs;
-    if (!name) {
-      throw new Error('Usage: bbx remote remove <name>');
-    }
-    const removed = await removeRemoteDestination(name);
-    process.stdout.write(
-      removed
-        ? `Remote destination "${name}" removed.\n`
-        : `Remote destination "${name}" was not configured.\n`
-    );
-    return;
-  }
-
-  if (subcommand === 'list') {
-    const config = await readRemoteConfig();
-    if (config.remotes.length === 0) {
-      process.stdout.write('No remote destinations configured.\n');
-      return;
-    }
-    process.stdout.write(
-      `${config.remotes.map((remote) => `${remote.id}\t${remote.host}:${remote.port}`).join('\n')}\n`
-    );
-    return;
-  }
-
-  if (subcommand === 'test') {
-    const [name] = restArgs;
-    if (!name) {
-      throw new Error('Usage: bbx remote test <name>');
-    }
-    const remoteClient = await createBridgeClientForDestination(name);
-    try {
-      await remoteClient.connect();
-      const response = await remoteClient.request({ method: 'health.ping' });
-      if (response.ok) {
-        const health = /** @type {{ extensionConnected?: boolean }} */ (response.result);
-        process.stdout.write(
-          `Remote destination "${name}" is reachable (extension ${
-            health.extensionConnected === true ? 'connected' : 'not connected'
-          }).\n`
-        );
-      } else {
-        process.exitCode = 1;
-        process.stdout.write(`Remote destination "${name}" failed: ${response.error.message}\n`);
-      }
-    } catch (error) {
-      process.exitCode = 1;
-      process.stdout.write(
-        `Remote destination "${name}" is not reachable: ${
-          error instanceof Error ? error.message : String(error)
-        }\n`
-      );
-    } finally {
-      await remoteClient.close();
-    }
-    return;
-  }
-
-  if (subcommand === 'destinations') {
-    const destinations = await listBridgeDestinations();
-    process.stdout.write(
-      `${destinations
-        .map((destination) =>
-          destination.local
-            ? `${destination.id}\tlocal`
-            : `${destination.id}\t${destination.host}:${destination.port}`
-        )
-        .join('\n')}\n`
-    );
-    return;
-  }
-
-  throw new Error('Usage: bbx remote <add|remove|list|test|destinations>');
-}
-
-/**
- * @param {string[]} args
- * @returns {string}
- */
-function parseRemoteTokenOption(args) {
-  let token = '';
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === '--token') {
-      token = args[++index] || '';
-      continue;
-    }
-    throw new Error(`Unknown remote add option "${arg}".`);
-  }
-  if (!token.trim()) {
-    throw new Error('Usage: bbx remote add <name> <host:port> --token <token>');
-  }
-  return token.trim();
-}
-
 /**
  * @param {unknown} error
  * @returns {string}
@@ -1242,216 +612,3 @@ function getClientTimeoutOverride() {
   const value = Number.parseInt(raw, 10);
   return Number.isFinite(value) && value > 0 ? value : undefined;
 }
-
-/**
- * Allow CLI tests to provide deterministic MCP client detection without relying
- * on whatever tools happen to be installed on the host machine.
- *
- * @returns {{
- *   mcpDetectors?: Record<string, () => boolean>,
- * }}
- */
-function getSetupStatusTestOverrides() {
-  if (!(TEST_DETECTED_MCP_CLIENTS_ENV in process.env)) {
-    return {};
-  }
-
-  const detectedClients = new Set(
-    (process.env[TEST_DETECTED_MCP_CLIENTS_ENV] || '')
-      .split(',')
-      .map((value) => value.trim().toLowerCase())
-      .filter(Boolean)
-  );
-
-  return {
-    mcpDetectors: Object.fromEntries(
-      MCP_CLIENT_NAMES.map((clientName) => [clientName, () => detectedClients.has(clientName)])
-    ),
-  };
-}
-
-/**
- * @param {{ detected: boolean, installed: boolean }} options
- * @returns {string | undefined}
- */
-function formatSelectionHint(options) {
-  /** @type {string[]} */
-  const parts = [];
-  if (options.detected) {
-    parts.push('● detected');
-  }
-  if (options.installed) {
-    parts.push('installed');
-  }
-  return parts.length > 0 ? parts.join(' · ') : undefined;
-}
-
-/**
- * @returns {Promise<void>}
- */
-async function ensureClientConnection() {
-  if (!client.connected) {
-    await client.connect();
-  }
-}
-
-/**
- * @param {import('../../protocol/src/types.js').BridgeResponse} response
- * @param {string} [method] - Optional method name for disambiguation
- * @returns {Promise<void>}
- */
-async function printSummary(response, method) {
-  if (!response.ok) {
-    process.exitCode = 1;
-  }
-  printJson(annotateBridgeSummary(summarizeBridgeResponse(response, method), response));
-}
-
-/**
- * @param {unknown} value
- * @returns {void}
- */
-function printJson(value) {
-  process.stdout.write(
-    `${JSON.stringify(sanitizeOutput(value), null, process.stdout.isTTY ? 2 : undefined)}\n`
-  );
-}
-
-/**
- * @param {import('../../protocol/src/types.js').BridgeResponse} response
- * @returns {void}
- */
-function printCallResponse(response) {
-  if (response.ok) {
-    printJson(response.result);
-    return;
-  }
-
-  process.exitCode = 1;
-  const errorText = `${response.error.code}: ${response.error.message}`;
-  process.stderr.write(
-    `${process.stderr.isTTY ? `\u001b[31m${sanitizeOutput(errorText)}\u001b[0m` : sanitizeOutput(errorText)}\n`
-  );
-  printJson(response);
-}
-
-function printUsage() {
-  const blocks = ['Usage: bbx [--remote <name>] <command> [args]'];
-  for (const section of CLI_HELP_SECTIONS) {
-    blocks.push('', `${section.title}:`);
-    blocks.push(...section.lines.map((line) => `  ${line}`));
-  }
-  process.stdout.write(`${blocks.join('\n')}\n`);
-}
-
-/**
- * @returns {Promise<void>}
- */
-async function uninstallBrowserBridge() {
-  const cwd = process.cwd();
-  const globalProjectPath = os.homedir();
-
-  for (const clientName of MCP_CLIENT_NAMES) {
-    await removeMcpConfig(clientName, { global: true, cwd });
-  }
-
-  const removedGlobalSkillPaths = await removeAgentFiles({
-    targets: SUPPORTED_TARGETS,
-    projectPath: globalProjectPath,
-    global: true,
-  });
-  for (const removedPath of removedGlobalSkillPaths) {
-    process.stdout.write(`Removed ${removedPath}\n`);
-  }
-
-  for (const clientName of MCP_CLIENT_NAMES) {
-    await removeMcpConfig(clientName, { global: false, cwd });
-  }
-
-  const removedLocalSkillPaths = await removeAgentFiles({
-    targets: SUPPORTED_TARGETS,
-    projectPath: cwd,
-    global: false,
-  });
-  for (const removedPath of removedLocalSkillPaths) {
-    process.stdout.write(`Removed ${removedPath}\n`);
-  }
-
-  for (const [index, browser] of SUPPORTED_BROWSERS.entries()) {
-    await uninstallNativeManifest({
-      browser,
-      removeBridgeDir: index === SUPPORTED_BROWSERS.length - 1,
-    });
-  }
-}
-
-/**
- * @param {string[]} args
- * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
- */
-async function parseCallCommand(args) {
-  const parsed = extractTabFlag(args);
-  const [first, second, ...extra] = parsed.rest;
-  if (!first) {
-    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
-  }
-  if (extra.length > 0) {
-    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
-  }
-
-  if (first.includes('.')) {
-    const method = /** @type {BridgeMethod} */ (first);
-    if (!METHODS.includes(method)) {
-      throw new Error(`Unknown method "${first}". Run bbx skill to see available methods.`);
-    }
-    let rawParams = second;
-    // Support piped stdin: `echo '{"key":"val"}' | bbx call method -`
-    if (rawParams === '-') {
-      rawParams = await readStdin();
-    }
-    return {
-      method,
-      tabId: methodNeedsTab(method) ? parsed.tabId : null,
-      params: parseJsonObject(rawParams),
-    };
-  }
-
-  throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
-}
-
-/**
- * Extract the global --remote flag from anywhere in the argument list.
- * Exits with a usage error when the flag is present without a value.
- *
- * @param {string[]} args
- * @returns {{ remoteId: string | null, explicit: boolean, rest: string[] }}
- */
-function extractRemoteFlag(args) {
-  const rest = [...args];
-  const index = rest.indexOf('--remote');
-  if (index === -1) {
-    return { remoteId: null, explicit: false, rest };
-  }
-  const remoteId = rest[index + 1];
-  if (!remoteId || remoteId.startsWith('--')) {
-    process.stderr.write('--remote requires a destination name (see `bbx remote list`).\n');
-    process.exit(1);
-  }
-  rest.splice(index, 2);
-  return { remoteId, explicit: true, rest };
-}
-
-/**
- * @param {string[]} args
- * @returns {{ tabId: number | null, rest: string[] }}
- */
-function extractTabFlag(args) {
-  const rest = [...args];
-  let tabId = null;
-  const tabIndex = rest.indexOf('--tab');
-  if (tabIndex !== -1) {
-    tabId = parseIntArg(rest[tabIndex + 1], 'tabId');
-    rest.splice(tabIndex, 2);
-  }
-  return { tabId, rest };
-}