@flrande/browserctl 0.5.0-dev.22.1 → 0.6.0

package/apps/browserctl/src/main.ts

@@ -1,957 +0,0 @@
-import { pathToFileURL } from "node:url";
-
-import { runActCommand } from "./commands/act";
-import { runA11ySnapshotCommand } from "./commands/a11y-snapshot";
-import { runCookieClearCommand } from "./commands/cookie-clear";
-import { runCookieGetCommand } from "./commands/cookie-get";
-import { runCookieSetCommand } from "./commands/cookie-set";
-import { runConsoleListCommand } from "./commands/console-list";
-import { runDialogArmCommand } from "./commands/dialog-arm";
-import { runDomQueryAllCommand } from "./commands/dom-query-all";
-import { runDomQueryCommand } from "./commands/dom-query";
-import { runDownloadTriggerCommand } from "./commands/download-trigger";
-import { runDownloadWaitCommand } from "./commands/download-wait";
-import { runElementScreenshotCommand } from "./commands/element-screenshot";
-import { runFrameListCommand } from "./commands/frame-list";
-import { runFrameSnapshotCommand } from "./commands/frame-snapshot";
-import { runHarExportCommand } from "./commands/har-export";
-import { runMemoryDeleteCommand } from "./commands/memory-delete";
-import { runMemoryInspectCommand } from "./commands/memory-inspect";
-import { runMemoryListCommand } from "./commands/memory-list";
-import { runMemoryModeSetCommand } from "./commands/memory-mode-set";
-import { runMemoryPurgeCommand } from "./commands/memory-purge";
-import { runMemoryResolveCommand } from "./commands/memory-resolve";
-import { runMemoryStatusCommand } from "./commands/memory-status";
-import { runMemoryTtlSetCommand } from "./commands/memory-ttl-set";
-import { runMemoryUpsertCommand } from "./commands/memory-upsert";
-import { runNetworkListCommand } from "./commands/network-list";
-import { runNetworkWaitForCommand } from "./commands/network-wait-for";
-import { parseCommandContext } from "./commands/common";
-import { runProfileListCommand } from "./commands/profile-list";
-import { runProfileUseCommand } from "./commands/profile-use";
-import { runResponseBodyCommand } from "./commands/response-body";
-import { runScreenshotCommand } from "./commands/screenshot";
-import { runSessionDropCommand } from "./commands/session-drop";
-import { runSessionListCommand } from "./commands/session-list";
-import { runSnapshotCommand } from "./commands/snapshot";
-import { runStatusCommand } from "./commands/status";
-import { runStorageGetCommand } from "./commands/storage-get";
-import { runStorageSetCommand } from "./commands/storage-set";
-import { runTabCloseCommand } from "./commands/tab-close";
-import { runTabFocusCommand } from "./commands/tab-focus";
-import { runTabOpenCommand } from "./commands/tab-open";
-import { runTabsCommand } from "./commands/tabs";
-import { runTraceGetCommand } from "./commands/trace-get";
-import { runUploadArmCommand } from "./commands/upload-arm";
-import { runWaitElementCommand } from "./commands/wait-element";
-import { runWaitTextCommand } from "./commands/wait-text";
-import { runWaitUrlCommand } from "./commands/wait-url";
-import { ensureDaemonRunning, getDaemonStatus, stopDaemon } from "./daemon-client";
-
-export const EXIT_CODES = {
-  OK: 0,
-  COMMAND_ERROR: 1,
-  INVALID_ARGS: 2
-} as const;
-
-export type CommandName =
-  | "status"
-  | "tabs"
-  | "profile-list"
-  | "profile-use"
-  | "tab-open"
-  | "tab-focus"
-  | "tab-close"
-  | "snapshot"
-  | "screenshot"
-  | "dom-query"
-  | "dom-query-all"
-  | "element-screenshot"
-  | "a11y-snapshot"
-  | "wait-element"
-  | "wait-text"
-  | "wait-url"
-  | "network-list"
-  | "har-export"
-  | "network-wait-for"
-  | "cookie-get"
-  | "cookie-set"
-  | "cookie-clear"
-  | "storage-get"
-  | "storage-set"
-  | "frame-list"
-  | "frame-snapshot"
-  | "act"
-  | "upload-arm"
-  | "dialog-arm"
-  | "download-trigger"
-  | "download-wait"
-  | "console-list"
-  | "response-body"
-  | "session-list"
-  | "session-drop"
-  | "trace-get"
-  | "memory-status"
-  | "memory-resolve"
-  | "memory-upsert"
-  | "memory-list"
-  | "memory-inspect"
-  | "memory-delete"
-  | "memory-purge"
-  | "memory-mode-set"
-  | "memory-ttl-set"
-  | "daemon-status"
-  | "daemon-start"
-  | "daemon-stop";
-
-export interface ParsedArgs {
-  command: CommandName | null;
-  commandArgs: string[];
-  json: boolean;
-  helpTopic?: HelpTopic;
-  error?: string;
-}
-
-export type HelpTopic = "all" | CommandName;
-
-const VALID_COMMANDS: ReadonlySet<CommandName> = new Set([
-  "status",
-  "tabs",
-  "profile-list",
-  "profile-use",
-  "tab-open",
-  "tab-focus",
-  "tab-close",
-  "snapshot",
-  "screenshot",
-  "dom-query",
-  "dom-query-all",
-  "element-screenshot",
-  "a11y-snapshot",
-  "wait-element",
-  "wait-text",
-  "wait-url",
-  "network-list",
-  "har-export",
-  "network-wait-for",
-  "cookie-get",
-  "cookie-set",
-  "cookie-clear",
-  "storage-get",
-  "storage-set",
-  "frame-list",
-  "frame-snapshot",
-  "act",
-  "upload-arm",
-  "dialog-arm",
-  "download-trigger",
-  "download-wait",
-  "console-list",
-  "response-body",
-  "session-list",
-  "session-drop",
-  "trace-get",
-  "memory-status",
-  "memory-resolve",
-  "memory-upsert",
-  "memory-list",
-  "memory-inspect",
-  "memory-delete",
-  "memory-purge",
-  "memory-mode-set",
-  "memory-ttl-set",
-  "daemon-status",
-  "daemon-start",
-  "daemon-stop"
-]);
-
-interface CommandHelpEntry {
-  usage: string;
-  description: string;
-}
-
-const COMMAND_HELP: Readonly<Record<CommandName, CommandHelpEntry>> = {
-  status: {
-    usage: "status",
-    description: "Query daemon and active profile readiness."
-  },
-  tabs: {
-    usage: "tabs",
-    description: "List tabs for the current session."
-  },
-  "profile-list": {
-    usage: "profile-list",
-    description: "List available driver profiles."
-  },
-  "profile-use": {
-    usage: "profile-use <driverKey>",
-    description: "Bind session to a driver profile."
-  },
-  "tab-open": {
-    usage: "tab-open <url>",
-    description: "Open a new tab with the given URL."
-  },
-  "tab-focus": {
-    usage: "tab-focus <targetId>",
-    description: "Activate an existing tab target."
-  },
-  "tab-close": {
-    usage: "tab-close <targetId>",
-    description: "Close a tab target."
-  },
-  snapshot: {
-    usage: "snapshot <targetId>",
-    description: "Get structured DOM snapshot for a tab."
-  },
-  screenshot: {
-    usage: "screenshot <targetId>",
-    description: "Capture full-page screenshot for a tab."
-  },
-  "dom-query": {
-    usage: "dom-query <targetId> <selector>",
-    description: "Get first matching element details."
-  },
-  "dom-query-all": {
-    usage: "dom-query-all <targetId> <selector>",
-    description: "List all matching elements."
-  },
-  "element-screenshot": {
-    usage: "element-screenshot <targetId> <selector>",
-    description: "Capture screenshot for one element."
-  },
-  "a11y-snapshot": {
-    usage: "a11y-snapshot <targetId> [selector]",
-    description: "Get accessibility tree snapshot."
-  },
-  "wait-element": {
-    usage: "wait-element <targetId> <selector> [--timeout-ms <ms>] [--poll-ms <ms>]",
-    description: "Wait until selector appears in the page."
-  },
-  "wait-text": {
-    usage: "wait-text <targetId> <text> [--selector <selector>] [--timeout-ms <ms>] [--poll-ms <ms>]",
-    description: "Wait until expected text appears."
-  },
-  "wait-url": {
-    usage: "wait-url <targetId> <urlPattern> [--timeout-ms <ms>] [--poll-ms <ms>]",
-    description: "Wait until current URL matches a pattern."
-  },
-  "network-list": {
-    usage:
-      "network-list <targetId> [--url-contains <text>] [--method <METHOD>] [--status <CODE>] [--since <ISO>] [--limit <n>]",
-    description: "List captured network requests with filters."
-  },
-  "har-export": {
-    usage:
-      "har-export <targetId> [--include-bodies] [--url-contains <text>] [--method <METHOD>] [--status <CODE>] [--since <ISO>] [--limit <n>]",
-    description: "Export captured network requests as HAR."
-  },
-  "network-wait-for": {
-    usage:
-      "network-wait-for <targetId> <urlPattern> [--method <METHOD>] [--status <CODE>] [--timeout-ms <ms>] [--poll-ms <ms>]",
-    description: "Wait until a matching network response appears."
-  },
-  "cookie-get": {
-    usage: "cookie-get <targetId> [name]",
-    description: "Read cookie(s) from page context."
-  },
-  "cookie-set": {
-    usage: "cookie-set <targetId> <name> <value> [url]",
-    description: "Set one cookie in page context."
-  },
-  "cookie-clear": {
-    usage: "cookie-clear <targetId> [name]",
-    description: "Clear one or all cookies."
-  },
-  "storage-get": {
-    usage: "storage-get <targetId> <local|session> <key>",
-    description: "Read a storage value."
-  },
-  "storage-set": {
-    usage: "storage-set <targetId> <local|session> <key> <value>",
-    description: "Write a storage value."
-  },
-  "frame-list": {
-    usage: "frame-list <targetId>",
-    description: "List frames for a tab."
-  },
-  "frame-snapshot": {
-    usage: "frame-snapshot <targetId> <frameId>",
-    description: "Snapshot one frame subtree."
-  },
-  act: {
-    usage: "act <actionType> <targetId> [--payload-json <json>]",
-    description: "Execute high-level action against a tab."
-  },
-  "upload-arm": {
-    usage: "upload-arm <targetId> <file1> [file2 ...]",
-    description: "Prepare file chooser upload paths."
-  },
-  "dialog-arm": {
-    usage: "dialog-arm <targetId>",
-    description: "Prepare next JS dialog interception."
-  },
-  "download-trigger": {
-    usage: "download-trigger <targetId>",
-    description: "Trigger download capture mode."
-  },
-  "download-wait": {
-    usage: "download-wait <targetId> [path]",
-    description: "Wait for next download and persist file."
-  },
-  "console-list": {
-    usage: "console-list <targetId> [--type <type>] [--contains <text>] [--since <ISO>] [--limit <n>]",
-    description: "List collected console events."
-  },
-  "response-body": {
-    usage: "response-body <targetId> <requestId>",
-    description: "Read response body for a captured request."
-  },
-  "session-list": {
-    usage: "session-list [--tenant <tenant>] [--limit <n>]",
-    description: "List active sessions for governance and multi-tenant inspection."
-  },
-  "session-drop": {
-    usage: "session-drop <sessionId>",
-    description: "Drop one session state by id."
-  },
-  "trace-get": {
-    usage: "trace-get [--limit <n>]",
-    description: "Read task-level trace steps and key responses for current session."
-  },
-  "memory-status": {
-    usage: "memory-status",
-    description: "Read navigation memory runtime status and counters."
-  },
-  "memory-resolve": {
-    usage: "memory-resolve <domain> <intentKey> [--profile-id <profileId>]",
-    description: "Resolve a memory entry for a domain/intent key."
-  },
-  "memory-upsert": {
-    usage:
-      "memory-upsert <domain> <intentKey> --signals-json <json> [--profile-id <profileId>] [--confidence <n>] [--confirmed [true|false]]",
-    description: "Create or update one memory entry."
-  },
-  "memory-list": {
-    usage: "memory-list [--domain <domain>] [--profile-id <profileId>] [--intent-key <intentKey>]",
-    description: "List navigation memory entries with optional filters."
-  },
-  "memory-inspect": {
-    usage: "memory-inspect <id>",
-    description: "Inspect one memory entry by id."
-  },
-  "memory-delete": {
-    usage: "memory-delete <id>",
-    description: "Delete one memory entry by id."
-  },
-  "memory-purge": {
-    usage: "memory-purge",
-    description: "Purge expired memory entries."
-  },
-  "memory-mode-set": {
-    usage: "memory-mode-set <mode>",
-    description: "Set navigation memory mode (off/ask/auto)."
-  },
-  "memory-ttl-set": {
-    usage: "memory-ttl-set <ttlDays>",
-    description: "Set navigation memory retention in days."
-  },
-  "daemon-status": {
-    usage: "daemon-status",
-    description: "Inspect local daemon process status."
-  },
-  "daemon-start": {
-    usage: "daemon-start [--browser <chromium|chrome|edge>]",
-    description: "Start daemon if needed and report runtime."
-  },
-  "daemon-stop": {
-    usage: "daemon-stop",
-    description: "Stop local daemon process."
-  }
-};
-
-const COMMAND_GROUPS: ReadonlyArray<{ title: string; commands: readonly CommandName[] }> = [
-  {
-    title: "Daemon lifecycle",
-    commands: ["daemon-start", "daemon-status", "daemon-stop"]
-  },
-  {
-    title: "Driver/session",
-    commands: ["status", "profile-list", "profile-use", "tabs", "session-list", "session-drop"]
-  },
-  {
-    title: "Navigation memory",
-    commands: [
-      "memory-status",
-      "memory-resolve",
-      "memory-upsert",
-      "memory-list",
-      "memory-inspect",
-      "memory-delete",
-      "memory-purge",
-      "memory-mode-set",
-      "memory-ttl-set"
-    ]
-  },
-  {
-    title: "Tab/page",
-    commands: ["tab-open", "tab-focus", "tab-close", "snapshot", "screenshot"]
-  },
-  {
-    title: "Structured reads",
-    commands: [
-      "dom-query",
-      "dom-query-all",
-      "element-screenshot",
-      "a11y-snapshot",
-      "wait-element",
-      "wait-text",
-      "wait-url",
-      "network-list",
-      "har-export",
-      "network-wait-for",
-      "cookie-get",
-      "cookie-set",
-      "cookie-clear",
-      "storage-get",
-      "storage-set",
-      "frame-list",
-      "frame-snapshot",
-      "console-list",
-      "response-body",
-      "trace-get"
-    ]
-  },
-  {
-    title: "Action/file flow",
-    commands: ["act", "upload-arm", "dialog-arm", "download-trigger", "download-wait"]
-  }
-];
-
-const CHROME_RELAY_FAILURE_GUIDANCE = [
-  "chrome-relay 连接失败，请先完成以下检查：",
-  "1) 扩展 relay 方案：设置 BROWSERD_CHROME_RELAY_MODE=extension。",
-  "2) 在 chrome://extensions 或 edge://extensions 中加载 extensions/chrome-relay（Load unpacked）。",
-  "3) 在扩展弹窗里确认 Bridge URL 与 BROWSERD_CHROME_RELAY_URL 一致（默认 ws://127.0.0.1:9223/bridge）。",
-  "4) 如果你走 CDP relay 方案，确认浏览器已启动远程调试端口（例如 --remote-debugging-port=9223）。",
-  "5) 确认 BROWSERD_CHROME_RELAY_URL 指向可访问地址（默认 http://127.0.0.1:9223）。"
-].join("\n");
-
-function isHelpFlag(value: string): boolean {
-  return value === "--help" || value === "-h";
-}
-
-function formatGeneralHelp(): string {
-  const lines = [
-    "browserctl - BrowserCtl command line client",
-    "",
-    "Usage:",
-    "  browserctl [--json] <command> [command-options] [positionals]",
-    "  browserctl help [command]",
-    "  browserctl <command> --help",
-    "",
-    "Global options:",
-    "  --json         Print success/error envelopes as JSON.",
-    "  --help, -h     Show general help or command help.",
-    "",
-    "Context options (browser commands):",
-    "  --session <id>         Session namespace (default: cli:local).",
-    "  --profile <driverKey>  Driver override.",
-    "  --token <authToken>    Request auth token override.",
-    "  --browser <preset>     Daemon startup browser preset (daemon-start only).",
-    "",
-    "Commands:"
-  ];
-
-  for (const group of COMMAND_GROUPS) {
-    lines.push(`  ${group.title}:`);
-    for (const command of group.commands) {
-      const entry = COMMAND_HELP[command];
-      lines.push(`    ${entry.usage}`);
-      lines.push(`      ${entry.description}`);
-    }
-  }
-
-  lines.push("");
-  lines.push("Run \"browserctl help <command>\" for command-specific usage.");
-
-  return `${lines.join("\n")}\n`;
-}
-
-function formatCommandHelp(command: CommandName): string {
-  const entry = COMMAND_HELP[command];
-  const lines = [`Command: ${command}`, "", "Usage:", `  browserctl ${entry.usage}`, "", entry.description];
-  const isDaemonCommand = command.startsWith("daemon-");
-
-  if (!isDaemonCommand) {
-    lines.push("");
-    lines.push("Context options:");
-    lines.push("  --session <id>         Session namespace (default: cli:local).");
-    lines.push("  --profile <driverKey>  Driver override.");
-    lines.push("  --token <authToken>    Request auth token override.");
-    if (command === "act") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --payload-json <json>  JSON object forwarded as action.payload.");
-    } else if (command === "wait-element" || command === "wait-url") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --timeout-ms <ms>  Maximum wait time (positive integer).");
-      lines.push("  --poll-ms <ms>     Poll interval (positive integer).");
-    } else if (command === "wait-text") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --selector <selector>  Limit matching to selector results.");
-      lines.push("  --timeout-ms <ms>      Maximum wait time (positive integer).");
-      lines.push("  --poll-ms <ms>         Poll interval (positive integer).");
-    } else if (command === "network-list") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --url-contains <text>  URL substring filter.");
-      lines.push("  --method <METHOD>      HTTP method filter.");
-      lines.push("  --status <CODE>        HTTP status filter.");
-      lines.push("  --since <ISO>          Timestamp lower bound.");
-      lines.push("  --limit <n>            Max number of entries.");
-    } else if (command === "console-list") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --type <type>      Console type filter (log/error/warn...).");
-      lines.push("  --contains <text>  Message substring filter.");
-      lines.push("  --since <ISO>      Timestamp lower bound.");
-      lines.push("  --limit <n>        Max number of entries.");
-    } else if (command === "har-export") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --include-bodies       Include response bodies when available.");
-      lines.push("  --url-contains <text>  URL substring filter.");
-      lines.push("  --method <METHOD>      HTTP method filter.");
-      lines.push("  --status <CODE>        HTTP status filter.");
-      lines.push("  --since <ISO>          Timestamp lower bound.");
-      lines.push("  --limit <n>            Max number of entries.");
-    } else if (command === "trace-get") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --limit <n>  Max number of records per trace section.");
-    } else if (command === "session-list") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --tenant <tenant>  Tenant filter.");
-      lines.push("  --limit <n>        Max number of sessions.");
-    } else if (command === "memory-resolve") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --profile-id <profileId>  Override memory scope profile id.");
-    } else if (command === "memory-upsert") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --signals-json <json>         Required JSON array of memory signals.");
-      lines.push("  --profile-id <profileId>      Override memory scope profile id.");
-      lines.push("  --confidence <n>              Optional confidence score.");
-      lines.push("  --confirmed [true|false]      Optional confirmation flag.");
-    } else if (command === "memory-list") {
-      lines.push("");
-      lines.push("Command options:");
-      lines.push("  --domain <domain>          Optional domain filter.");
-      lines.push("  --profile-id <profileId>   Optional profile id filter.");
-      lines.push("  --intent-key <intentKey>   Optional intent key filter.");
-    }
-  } else if (command === "daemon-start") {
-    lines.push("");
-    lines.push("Command options:");
-    lines.push("  --browser <chromium|chrome|edge>  managed-local browser preset.");
-    lines.push("  --token <authToken>               Request auth token override.");
-  } else if (command === "daemon-status") {
-    lines.push("");
-    lines.push("Command options:");
-    lines.push("  --token <authToken>  Request auth token override.");
-  }
-
-  lines.push("");
-  lines.push("Global options:");
-  lines.push("  --json");
-  lines.push("  --help, -h");
-
-  return `${lines.join("\n")}\n`;
-}
-
-function formatHelp(topic: HelpTopic): string {
-  if (topic === "all") {
-    return formatGeneralHelp();
-  }
-
-  return formatCommandHelp(topic);
-}
-
-export function parseArgs(argv: string[]): ParsedArgs {
-  const positional: string[] = [];
-  let json = false;
-  let helpRequested = false;
-
-  for (const value of argv) {
-    if (value === "--json") {
-      json = true;
-      continue;
-    }
-
-    if (isHelpFlag(value)) {
-      helpRequested = true;
-      continue;
-    }
-
-    positional.push(value);
-  }
-
-  const [commandToken, ...commandArgs] = positional;
-  if (commandToken === undefined) {
-    if (helpRequested) {
-      return {
-        command: null,
-        commandArgs: [],
-        json,
-        helpTopic: "all"
-      };
-    }
-
-    return {
-      command: null,
-      commandArgs: [],
-      json,
-      error: "Missing command."
-    };
-  }
-
-  if (commandToken === "help") {
-    if (commandArgs.length === 0) {
-      return {
-        command: null,
-        commandArgs: [],
-        json,
-        helpTopic: "all"
-      };
-    }
-
-    if (commandArgs.length > 1) {
-      return {
-        command: null,
-        commandArgs: [],
-        json,
-        error: "Too many arguments for help."
-      };
-    }
-
-    const topic = commandArgs[0];
-    if (!VALID_COMMANDS.has(topic as CommandName)) {
-      return {
-        command: null,
-        commandArgs: [],
-        json,
-        error: `Unknown help topic: ${topic}`
-      };
-    }
-
-    return {
-      command: null,
-      commandArgs: [],
-      json,
-      helpTopic: topic as CommandName
-    };
-  }
-
-  if (helpRequested) {
-    if (!VALID_COMMANDS.has(commandToken as CommandName)) {
-      return {
-        command: null,
-        commandArgs: [],
-        json,
-        error: `Unknown command: ${commandToken}`
-      };
-    }
-
-    return {
-      command: null,
-      commandArgs: [],
-      json,
-      helpTopic: commandToken as CommandName
-    };
-  }
-
-  if (!VALID_COMMANDS.has(commandToken as CommandName)) {
-    return {
-      command: null,
-      commandArgs: [],
-      json,
-      error: `Unknown command: ${commandToken}`
-    };
-  }
-
-  return {
-    command: commandToken as CommandName,
-    commandArgs,
-    json
-  };
-}
-
-function tryResolveProfile(commandArgs: string[]): string | undefined {
-  try {
-    return parseCommandContext(commandArgs).profile;
-  } catch {
-    return undefined;
-  }
-}
-
-function isConnectionFailureMessage(message: string): boolean {
-  return /ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|Timed out/i.test(message);
-}
-
-function shouldAttachChromeRelayGuidance(commandArgs: string[], message: string): boolean {
-  const lowerMessage = message.toLowerCase();
-  if (lowerMessage.includes("chrome relay extension is not connected")) {
-    return true;
-  }
-
-  if (!isConnectionFailureMessage(message)) {
-    return false;
-  }
-
-  const profile = tryResolveProfile(commandArgs);
-  if (profile === "chrome-relay") {
-    return true;
-  }
-
-  return (
-    lowerMessage.includes("chrome-relay") ||
-    lowerMessage.includes("connectovercdp") ||
-    lowerMessage.includes("/json/version") ||
-    lowerMessage.includes("9223")
-  );
-}
-
-function enrichCommandErrorMessage(commandArgs: string[], message: string): string {
-  if (!shouldAttachChromeRelayGuidance(commandArgs, message)) {
-    return message;
-  }
-
-  return `${message}\n\n${CHROME_RELAY_FAILURE_GUIDANCE}`;
-}
-
-interface WritableLike {
-  write(content: string): void;
-}
-
-export interface CliIo {
-  stdout: WritableLike;
-  stderr: WritableLike;
-}
-
-function formatHumanOutput(command: CommandName, data: unknown): string {
-  return `${command}: ${JSON.stringify(data)}\n`;
-}
-
-function writeError(io: CliIo, message: string, json: boolean, exitCode: number): void {
-  if (json) {
-    io.stderr.write(
-      `${JSON.stringify({
-        ok: false,
-        error: {
-          message,
-          exitCode
-        }
-      })}\n`
-    );
-    return;
-  }
-
-  io.stderr.write(`${message}\n`);
-}
-
-async function executeCommand(command: CommandName, commandArgs: string[]): Promise<unknown> {
-  switch (command) {
-    case "status":
-      return await runStatusCommand(commandArgs);
-    case "tabs":
-      return await runTabsCommand(commandArgs);
-    case "profile-list":
-      return await runProfileListCommand(commandArgs);
-    case "profile-use":
-      return await runProfileUseCommand(commandArgs);
-    case "tab-open":
-      return await runTabOpenCommand(commandArgs);
-    case "tab-focus":
-      return await runTabFocusCommand(commandArgs);
-    case "tab-close":
-      return await runTabCloseCommand(commandArgs);
-    case "snapshot":
-      return await runSnapshotCommand(commandArgs);
-    case "screenshot":
-      return await runScreenshotCommand(commandArgs);
-    case "dom-query":
-      return await runDomQueryCommand(commandArgs);
-    case "dom-query-all":
-      return await runDomQueryAllCommand(commandArgs);
-    case "element-screenshot":
-      return await runElementScreenshotCommand(commandArgs);
-    case "a11y-snapshot":
-      return await runA11ySnapshotCommand(commandArgs);
-    case "wait-element":
-      return await runWaitElementCommand(commandArgs);
-    case "wait-text":
-      return await runWaitTextCommand(commandArgs);
-    case "wait-url":
-      return await runWaitUrlCommand(commandArgs);
-    case "network-list":
-      return await runNetworkListCommand(commandArgs);
-    case "har-export":
-      return await runHarExportCommand(commandArgs);
-    case "network-wait-for":
-      return await runNetworkWaitForCommand(commandArgs);
-    case "cookie-get":
-      return await runCookieGetCommand(commandArgs);
-    case "cookie-set":
-      return await runCookieSetCommand(commandArgs);
-    case "cookie-clear":
-      return await runCookieClearCommand(commandArgs);
-    case "storage-get":
-      return await runStorageGetCommand(commandArgs);
-    case "storage-set":
-      return await runStorageSetCommand(commandArgs);
-    case "frame-list":
-      return await runFrameListCommand(commandArgs);
-    case "frame-snapshot":
-      return await runFrameSnapshotCommand(commandArgs);
-    case "act":
-      return await runActCommand(commandArgs);
-    case "upload-arm":
-      return await runUploadArmCommand(commandArgs);
-    case "dialog-arm":
-      return await runDialogArmCommand(commandArgs);
-    case "download-trigger":
-      return await runDownloadTriggerCommand(commandArgs);
-    case "download-wait":
-      return await runDownloadWaitCommand(commandArgs);
-    case "console-list":
-      return await runConsoleListCommand(commandArgs);
-    case "response-body":
-      return await runResponseBodyCommand(commandArgs);
-    case "session-list":
-      return await runSessionListCommand(commandArgs);
-    case "session-drop":
-      return await runSessionDropCommand(commandArgs);
-    case "trace-get":
-      return await runTraceGetCommand(commandArgs);
-    case "memory-status":
-      return await runMemoryStatusCommand(commandArgs);
-    case "memory-resolve":
-      return await runMemoryResolveCommand(commandArgs);
-    case "memory-upsert":
-      return await runMemoryUpsertCommand(commandArgs);
-    case "memory-list":
-      return await runMemoryListCommand(commandArgs);
-    case "memory-inspect":
-      return await runMemoryInspectCommand(commandArgs);
-    case "memory-delete":
-      return await runMemoryDeleteCommand(commandArgs);
-    case "memory-purge":
-      return await runMemoryPurgeCommand(commandArgs);
-    case "memory-mode-set":
-      return await runMemoryModeSetCommand(commandArgs);
-    case "memory-ttl-set":
-      return await runMemoryTtlSetCommand(commandArgs);
-    case "daemon-status": {
-      const context = parseCommandContext(commandArgs);
-      return await getDaemonStatus({
-        authToken: context.authToken
-      });
-    }
-    case "daemon-start": {
-      const context = parseCommandContext(commandArgs);
-      return await ensureDaemonRunning({
-        authToken: context.authToken,
-        startup: context.daemonStartup
-      });
-    }
-    case "daemon-stop":
-      return stopDaemon();
-    default:
-      return neverCommand(command);
-  }
-}
-
-function neverCommand(command: never): never {
-  throw new Error(`Unsupported command: ${command}`);
-}
-
-export async function runCli(
-  argv: string[],
-  io: CliIo = {
-    stdout: process.stdout,
-    stderr: process.stderr
-  }
-): Promise<number> {
-  const parsedArgs = parseArgs(argv);
-  if (parsedArgs.error !== undefined) {
-    writeError(io, parsedArgs.error, parsedArgs.json, EXIT_CODES.INVALID_ARGS);
-    return EXIT_CODES.INVALID_ARGS;
-  }
-
-  if (parsedArgs.helpTopic !== undefined) {
-    const helpText = formatHelp(parsedArgs.helpTopic);
-    if (parsedArgs.json) {
-      io.stdout.write(
-        `${JSON.stringify({
-          ok: true,
-          command: "help",
-          data: {
-            topic: parsedArgs.helpTopic,
-            text: helpText.trimEnd()
-          }
-        })}\n`
-      );
-    } else {
-      io.stdout.write(helpText);
-    }
-
-    return EXIT_CODES.OK;
-  }
-
-  try {
-    const data = await executeCommand(parsedArgs.command, parsedArgs.commandArgs);
-
-    if (parsedArgs.json) {
-      io.stdout.write(
-        `${JSON.stringify({
-          ok: true,
-          command: parsedArgs.command,
-          data
-        })}\n`
-      );
-    } else {
-      io.stdout.write(formatHumanOutput(parsedArgs.command, data));
-    }
-
-    return EXIT_CODES.OK;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown command failure.";
-    writeError(
-      io,
-      enrichCommandErrorMessage(parsedArgs.commandArgs, message),
-      parsedArgs.json,
-      EXIT_CODES.COMMAND_ERROR
-    );
-    return EXIT_CODES.COMMAND_ERROR;
-  }
-}
-
-export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
-  return await runCli(argv);
-}
-
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  void main()
-    .then((exitCode) => {
-      process.exitCode = exitCode;
-    })
-    .catch((error) => {
-      const message = error instanceof Error ? error.message : "Unexpected CLI failure.";
-      process.stderr.write(`${message}\n`);
-      process.exitCode = EXIT_CODES.COMMAND_ERROR;
-    });
-}