@flrande/browserctl 0.1.0

package/apps/browserctl/src/main.test.ts

@@ -0,0 +1,215 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import * as actCommand from "./commands/act";
+import * as daemonClient from "./daemon-client";
+import * as screenshotCommand from "./commands/screenshot";
+import * as statusCommand from "./commands/status";
+import * as tabsCommand from "./commands/tabs";
+import { EXIT_CODES, parseArgs, runCli } from "./main";
+
+function createIoCapture() {
+  const state = {
+    stdout: "",
+    stderr: ""
+  };
+
+  return {
+    state,
+    io: {
+      stdout: {
+        write(content: string) {
+          state.stdout += content;
+        }
+      },
+      stderr: {
+        write(content: string) {
+          state.stderr += content;
+        }
+      }
+    }
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("cli", () => {
+  it("parses status command", () => {
+    expect(parseArgs(["status"]).command).toBe("status");
+  });
+
+  it("preserves unknown flags and '--' separator as command args", () => {
+    expect(parseArgs(["status", "--profile", "default", "--", "--raw"])).toEqual({
+      command: "status",
+      commandArgs: ["--profile", "default", "--", "--raw"],
+      json: false
+    });
+  });
+
+  it("consumes --json globally while preserving command args", () => {
+    expect(parseArgs(["--json", "tabs", "--verbose"])).toEqual({
+      command: "tabs",
+      commandArgs: ["--verbose"],
+      json: true
+    });
+  });
+
+  it("writes JSON output on successful run", async () => {
+    vi.spyOn(statusCommand, "runStatusCommand").mockResolvedValue({
+      kind: "browserd",
+      ready: true
+    });
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["status", "--json"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(state.stderr).toBe("");
+    expect(JSON.parse(state.stdout)).toEqual({
+      ok: true,
+      command: "status",
+      data: {
+        kind: "browserd",
+        ready: true
+      }
+    });
+  });
+
+  it("returns INVALID_ARGS for unknown command", async () => {
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["unknown"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.INVALID_ARGS);
+    expect(state.stdout).toBe("");
+    expect(state.stderr).toContain("Unknown command: unknown");
+  });
+
+  it("writes non-JSON output when --json is not provided", async () => {
+    vi.spyOn(tabsCommand, "runTabsCommand").mockResolvedValue({
+      driver: "managed",
+      tabs: ["target:1"]
+    });
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["tabs"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(state.stderr).toBe("");
+    expect(state.stdout).toMatch(/^tabs: /);
+  });
+
+  it("dispatches to act command handler with forwarded args", async () => {
+    const actSpy = vi.spyOn(actCommand, "runActCommand").mockResolvedValue({
+      ok: true
+    });
+    const { io } = createIoCapture();
+
+    const exitCode = await runCli(["act", "click", "tab:42"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(actSpy).toHaveBeenCalledTimes(1);
+    expect(actSpy).toHaveBeenCalledWith(["click", "tab:42"]);
+  });
+
+  it("dispatches to screenshot command handler with forwarded args", async () => {
+    const screenshotSpy = vi.spyOn(screenshotCommand, "runScreenshotCommand").mockResolvedValue({
+      ok: true
+    });
+    const { io } = createIoCapture();
+
+    const exitCode = await runCli(["screenshot", "tab:42"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(screenshotSpy).toHaveBeenCalledTimes(1);
+    expect(screenshotSpy).toHaveBeenCalledWith(["tab:42"]);
+  });
+
+  it("dispatches to status command handler", async () => {
+    const statusSpy = vi.spyOn(statusCommand, "runStatusCommand").mockResolvedValue({
+      kind: "browserd",
+      ready: true
+    });
+    const { io } = createIoCapture();
+
+    const exitCode = await runCli(["status", "--json"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(statusSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispatches daemon-status through daemon client", async () => {
+    const daemonStatusSpy = vi.spyOn(daemonClient, "getDaemonStatus").mockResolvedValue({
+      running: true,
+      port: 41337,
+      pid: 12345
+    });
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["daemon-status", "--json"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(daemonStatusSpy).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(state.stdout)).toEqual({
+      ok: true,
+      command: "daemon-status",
+      data: {
+        running: true,
+        port: 41337,
+        pid: 12345
+      }
+    });
+  });
+
+  it("forwards --browser preset to daemon-start", async () => {
+    const daemonStartSpy = vi.spyOn(daemonClient, "ensureDaemonRunning").mockResolvedValue({
+      running: true,
+      port: 41337,
+      pid: 12345
+    });
+    const { io } = createIoCapture();
+
+    const exitCode = await runCli(["daemon-start", "--json", "--browser", "edge"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(daemonStartSpy).toHaveBeenCalledTimes(1);
+    expect(daemonStartSpy).toHaveBeenCalledWith({
+      authToken: undefined,
+      startup: {
+        managedLocal: {
+          browserName: "chromium",
+          channel: "msedge"
+        }
+      }
+    });
+  });
+
+  it("adds relay setup guidance when chrome-relay connection fails", async () => {
+    vi.spyOn(statusCommand, "runStatusCommand").mockRejectedValue(
+      new Error("E_INTERNAL: connect ECONNREFUSED 127.0.0.1:9223")
+    );
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["status", "--profile", "chrome-relay"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.COMMAND_ERROR);
+    expect(state.stderr).toContain("chrome-relay 连接失败");
+    expect(state.stderr).toContain("扩展");
+    expect(state.stderr).toContain("BROWSERD_CHROME_RELAY_URL");
+  });
+
+  it("adds relay setup guidance when extension relay is not connected", async () => {
+    vi.spyOn(statusCommand, "runStatusCommand").mockRejectedValue(
+      new Error("E_INTERNAL: Chrome relay extension is not connected.")
+    );
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["status", "--profile", "chrome-relay"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.COMMAND_ERROR);
+    expect(state.stderr).toContain("chrome-relay 连接失败");
+    expect(state.stderr).toContain("BROWSERD_CHROME_RELAY_MODE=extension");
+    expect(state.stderr).toContain("extensions/chrome-relay");
+  });
+});

package/apps/browserctl/src/main.ts

@@ -0,0 +1,372 @@
+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 { 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 { 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 { runUploadArmCommand } from "./commands/upload-arm";
+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"
+  | "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"
+  | "daemon-status"
+  | "daemon-start"
+  | "daemon-stop";
+
+export interface ParsedArgs {
+  command: CommandName | null;
+  commandArgs: string[];
+  json: boolean;
+  error?: string;
+}
+
+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",
+  "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",
+  "daemon-status",
+  "daemon-start",
+  "daemon-stop"
+]);
+
+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");
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const positional = [];
+  let json = false;
+
+  for (const value of argv) {
+    if (value === "--json") {
+      json = true;
+      continue;
+    }
+
+    positional.push(value);
+  }
+
+  const [commandToken, ...commandArgs] = positional;
+  if (commandToken === undefined) {
+    return {
+      command: null,
+      commandArgs: [],
+      json,
+      error: "Missing command."
+    };
+  }
+
+  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 "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 "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;
+  }
+
+  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;
+    });
+}

package/apps/browserctl/src/smoke.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+
+import { getSmokeCommand } from "./smoke";
+
+describe("smoke wiring", () => {
+  it("returns a PowerShell command with required flags and default script path", () => {
+    const command = getSmokeCommand();
+
+    expect(command).toContain("pwsh");
+    expect(command).toContain("-NoLogo");
+    expect(command).toContain("-NoProfile");
+    expect(command).toContain("-NonInteractive");
+    expect(command).toContain("-File");
+    expect(command).toContain('".\\scripts\\smoke.ps1"');
+  });
+});

package/apps/browserctl/src/smoke.ts

@@ -0,0 +1,5 @@
+const DEFAULT_SMOKE_SCRIPT_PATH = ".\\scripts\\smoke.ps1";
+
+export function getSmokeCommand(scriptPath: string = DEFAULT_SMOKE_SCRIPT_PATH): string {
+  return `pwsh -NoLogo -NoProfile -NonInteractive -File "${scriptPath}"`;
+}