@flrande/browserctl 0.1.0 → 0.2.0-dev.9.1

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

@@ -0,0 +1,256 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import * as a11ySnapshotCommand from "./commands/a11y-snapshot";
+import * as consoleListCommand from "./commands/console-list";
+import * as cookieClearCommand from "./commands/cookie-clear";
+import * as cookieGetCommand from "./commands/cookie-get";
+import * as cookieSetCommand from "./commands/cookie-set";
+import * as daemonClient from "./daemon-client";
+import * as dialogArmCommand from "./commands/dialog-arm";
+import * as domQueryAllCommand from "./commands/dom-query-all";
+import * as domQueryCommand from "./commands/dom-query";
+import * as downloadTriggerCommand from "./commands/download-trigger";
+import * as downloadWaitCommand from "./commands/download-wait";
+import * as elementScreenshotCommand from "./commands/element-screenshot";
+import * as frameListCommand from "./commands/frame-list";
+import * as frameSnapshotCommand from "./commands/frame-snapshot";
+import * as networkWaitForCommand from "./commands/network-wait-for";
+import * as profileListCommand from "./commands/profile-list";
+import * as profileUseCommand from "./commands/profile-use";
+import * as responseBodyCommand from "./commands/response-body";
+import * as snapshotCommand from "./commands/snapshot";
+import * as storageGetCommand from "./commands/storage-get";
+import * as storageSetCommand from "./commands/storage-set";
+import * as tabCloseCommand from "./commands/tab-close";
+import * as tabFocusCommand from "./commands/tab-focus";
+import * as tabOpenCommand from "./commands/tab-open";
+import * as uploadArmCommand from "./commands/upload-arm";
+import { EXIT_CODES, 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;
+        }
+      }
+    }
+  };
+}
+
+type DispatchCase = {
+  command: string;
+  commandArgs: string[];
+  moduleRef: Record<string, unknown>;
+  handlerName: string;
+};
+
+const COMMAND_DISPATCH_CASES: DispatchCase[] = [
+  {
+    command: "a11y-snapshot",
+    commandArgs: ["target:1"],
+    moduleRef: a11ySnapshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runA11ySnapshotCommand"
+  },
+  {
+    command: "console-list",
+    commandArgs: ["target:1"],
+    moduleRef: consoleListCommand as unknown as Record<string, unknown>,
+    handlerName: "runConsoleListCommand"
+  },
+  {
+    command: "cookie-clear",
+    commandArgs: ["target:1"],
+    moduleRef: cookieClearCommand as unknown as Record<string, unknown>,
+    handlerName: "runCookieClearCommand"
+  },
+  {
+    command: "cookie-get",
+    commandArgs: ["target:1"],
+    moduleRef: cookieGetCommand as unknown as Record<string, unknown>,
+    handlerName: "runCookieGetCommand"
+  },
+  {
+    command: "cookie-set",
+    commandArgs: ["target:1", "sid", "abc"],
+    moduleRef: cookieSetCommand as unknown as Record<string, unknown>,
+    handlerName: "runCookieSetCommand"
+  },
+  {
+    command: "dialog-arm",
+    commandArgs: ["target:1"],
+    moduleRef: dialogArmCommand as unknown as Record<string, unknown>,
+    handlerName: "runDialogArmCommand"
+  },
+  {
+    command: "dom-query",
+    commandArgs: ["target:1", "#root"],
+    moduleRef: domQueryCommand as unknown as Record<string, unknown>,
+    handlerName: "runDomQueryCommand"
+  },
+  {
+    command: "dom-query-all",
+    commandArgs: ["target:1", ".item"],
+    moduleRef: domQueryAllCommand as unknown as Record<string, unknown>,
+    handlerName: "runDomQueryAllCommand"
+  },
+  {
+    command: "download-trigger",
+    commandArgs: ["target:1"],
+    moduleRef: downloadTriggerCommand as unknown as Record<string, unknown>,
+    handlerName: "runDownloadTriggerCommand"
+  },
+  {
+    command: "download-wait",
+    commandArgs: ["target:1"],
+    moduleRef: downloadWaitCommand as unknown as Record<string, unknown>,
+    handlerName: "runDownloadWaitCommand"
+  },
+  {
+    command: "element-screenshot",
+    commandArgs: ["target:1", "#hero"],
+    moduleRef: elementScreenshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runElementScreenshotCommand"
+  },
+  {
+    command: "frame-list",
+    commandArgs: ["target:1"],
+    moduleRef: frameListCommand as unknown as Record<string, unknown>,
+    handlerName: "runFrameListCommand"
+  },
+  {
+    command: "frame-snapshot",
+    commandArgs: ["target:1", "frame:0"],
+    moduleRef: frameSnapshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runFrameSnapshotCommand"
+  },
+  {
+    command: "network-wait-for",
+    commandArgs: ["target:1", "/api", "1000"],
+    moduleRef: networkWaitForCommand as unknown as Record<string, unknown>,
+    handlerName: "runNetworkWaitForCommand"
+  },
+  {
+    command: "profile-list",
+    commandArgs: [],
+    moduleRef: profileListCommand as unknown as Record<string, unknown>,
+    handlerName: "runProfileListCommand"
+  },
+  {
+    command: "profile-use",
+    commandArgs: ["managed"],
+    moduleRef: profileUseCommand as unknown as Record<string, unknown>,
+    handlerName: "runProfileUseCommand"
+  },
+  {
+    command: "response-body",
+    commandArgs: ["target:1", "request:1"],
+    moduleRef: responseBodyCommand as unknown as Record<string, unknown>,
+    handlerName: "runResponseBodyCommand"
+  },
+  {
+    command: "snapshot",
+    commandArgs: ["target:1"],
+    moduleRef: snapshotCommand as unknown as Record<string, unknown>,
+    handlerName: "runSnapshotCommand"
+  },
+  {
+    command: "storage-get",
+    commandArgs: ["target:1", "local", "theme"],
+    moduleRef: storageGetCommand as unknown as Record<string, unknown>,
+    handlerName: "runStorageGetCommand"
+  },
+  {
+    command: "storage-set",
+    commandArgs: ["target:1", "local", "theme", "dark"],
+    moduleRef: storageSetCommand as unknown as Record<string, unknown>,
+    handlerName: "runStorageSetCommand"
+  },
+  {
+    command: "tab-close",
+    commandArgs: ["target:1"],
+    moduleRef: tabCloseCommand as unknown as Record<string, unknown>,
+    handlerName: "runTabCloseCommand"
+  },
+  {
+    command: "tab-focus",
+    commandArgs: ["target:1"],
+    moduleRef: tabFocusCommand as unknown as Record<string, unknown>,
+    handlerName: "runTabFocusCommand"
+  },
+  {
+    command: "tab-open",
+    commandArgs: ["https://example.com"],
+    moduleRef: tabOpenCommand as unknown as Record<string, unknown>,
+    handlerName: "runTabOpenCommand"
+  },
+  {
+    command: "upload-arm",
+    commandArgs: ["target:1", "upload.txt"],
+    moduleRef: uploadArmCommand as unknown as Record<string, unknown>,
+    handlerName: "runUploadArmCommand"
+  }
+];
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("cli dispatch matrix", () => {
+  it.each(COMMAND_DISPATCH_CASES)(
+    "dispatches $command to $handlerName",
+    async ({ command, commandArgs, moduleRef, handlerName }) => {
+      const handler = moduleRef[handlerName] as ((args: string[]) => Promise<unknown>) | undefined;
+      if (typeof handler !== "function") {
+        throw new Error(`Expected ${handlerName} to be a function.`);
+      }
+
+      const handlerSpy = vi.spyOn(moduleRef as Record<string, (...args: unknown[]) => unknown>, handlerName)
+        .mockResolvedValue({ ok: true });
+      const { io, state } = createIoCapture();
+
+      const exitCode = await runCli([command, ...commandArgs], io);
+
+      expect(exitCode).toBe(EXIT_CODES.OK);
+      expect(state.stderr).toBe("");
+      expect(state.stdout).toMatch(new RegExp(`^${command}: `));
+      expect(handlerSpy).toHaveBeenCalledTimes(1);
+      expect(handlerSpy).toHaveBeenCalledWith(commandArgs);
+    }
+  );
+
+  it("dispatches daemon-stop through daemon client", async () => {
+    const stopSpy = vi.spyOn(daemonClient, "stopDaemon").mockResolvedValue({
+      stopped: true,
+      port: 41337,
+      pid: 12345
+    });
+    const { io, state } = createIoCapture();
+
+    const exitCode = await runCli(["daemon-stop", "--json"], io);
+
+    expect(exitCode).toBe(EXIT_CODES.OK);
+    expect(stopSpy).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(state.stdout)).toEqual({
+      ok: true,
+      command: "daemon-stop",
+      data: {
+        stopped: true,
+        port: 41337,
+        pid: 12345
+      }
+    });
+  });
+});

package/apps/browserd/src/tool-matrix.test.ts

@@ -0,0 +1,394 @@
+import { PassThrough } from "node:stream";
+
+import { describe, expect, it } from "vitest";
+
+import { bootstrapBrowserd } from "./bootstrap";
+
+function waitForNextJsonLine(stream: PassThrough): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    const timeout = setTimeout(() => {
+      stream.off("data", onData);
+      reject(new Error("Timed out waiting for JSON line response."));
+    }, 1000);
+
+    const onData = (chunk: string | Buffer) => {
+      buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex < 0) {
+        return;
+      }
+
+      clearTimeout(timeout);
+      stream.off("data", onData);
+      const line = buffer.slice(0, newlineIndex);
+
+      resolve(JSON.parse(line) as Record<string, unknown>);
+    };
+
+    stream.on("data", onData);
+  });
+}
+
+function sendToolRequest(
+  input: PassThrough,
+  output: PassThrough,
+  request: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  const responsePromise = waitForNextJsonLine(output);
+  input.write(`${JSON.stringify(request)}\n`);
+  return responsePromise;
+}
+
+function createManagedLegacyRuntime() {
+  const input = new PassThrough();
+  const output = new PassThrough();
+  const runtime = bootstrapBrowserd({
+    env: {
+      BROWSERD_DEFAULT_DRIVER: "managed"
+    },
+    input,
+    output,
+    stdioProtocol: "legacy"
+  });
+
+  return {
+    input,
+    output,
+    runtime
+  };
+}
+
+describe("browserd tool matrix", () => {
+  it("returns E_INVALID_ARG for missing required arguments on routed tools", async () => {
+    const { input, output, runtime } = createManagedLegacyRuntime();
+
+    try {
+      const toolNames = [
+        "browser.profile.use",
+        "browser.tab.focus",
+        "browser.tab.close",
+        "browser.snapshot",
+        "browser.dom.query",
+        "browser.dom.queryAll",
+        "browser.element.screenshot",
+        "browser.a11y.snapshot",
+        "browser.cookie.get",
+        "browser.cookie.set",
+        "browser.cookie.clear",
+        "browser.storage.get",
+        "browser.storage.set",
+        "browser.frame.list",
+        "browser.frame.snapshot",
+        "browser.act",
+        "browser.dialog.arm",
+        "browser.download.trigger",
+        "browser.network.waitFor"
+      ] as const;
+
+      for (const [index, toolName] of toolNames.entries()) {
+        const response = await sendToolRequest(input, output, {
+          id: `request-missing-arg-${index}`,
+          name: toolName,
+          traceId: `trace:missing-arg:${index}`,
+          arguments: {
+            sessionId: "session:missing-arg"
+          }
+        });
+
+        expect(response.ok).toBe(false);
+        expect(response.error).toMatchObject({
+          code: "E_INVALID_ARG"
+        });
+      }
+    } finally {
+      runtime.close();
+      input.end();
+      output.end();
+    }
+  });
+
+  it("returns E_DRIVER_UNAVAILABLE for structured action tools on managed driver", async () => {
+    const { input, output, runtime } = createManagedLegacyRuntime();
+
+    try {
+      const openResponse = await sendToolRequest(input, output, {
+        id: "request-unavailable-open",
+        name: "browser.tab.open",
+        traceId: "trace:unavailable:open",
+        arguments: {
+          sessionId: "session:unavailable",
+          url: "https://example.com/unavailable"
+        }
+      });
+      const targetId = (openResponse.data as { targetId: string }).targetId;
+
+      const cases: Array<{ name: string; arguments: Record<string, unknown> }> = [
+        {
+          name: "browser.dom.query",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            selector: "#root"
+          }
+        },
+        {
+          name: "browser.dom.queryAll",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            selector: ".item"
+          }
+        },
+        {
+          name: "browser.element.screenshot",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            selector: "#hero"
+          }
+        },
+        {
+          name: "browser.a11y.snapshot",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.cookie.get",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.cookie.set",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            name: "sid",
+            value: "abc"
+          }
+        },
+        {
+          name: "browser.cookie.clear",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.storage.get",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            scope: "local",
+            key: "theme"
+          }
+        },
+        {
+          name: "browser.storage.set",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            scope: "local",
+            key: "theme",
+            value: "dark"
+          }
+        },
+        {
+          name: "browser.frame.list",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId
+          }
+        },
+        {
+          name: "browser.frame.snapshot",
+          arguments: {
+            sessionId: "session:unavailable",
+            targetId,
+            frameId: "frame:0"
+          }
+        }
+      ];
+
+      for (const [index, testCase] of cases.entries()) {
+        const response = await sendToolRequest(input, output, {
+          id: `request-driver-unavailable-${index}`,
+          name: testCase.name,
+          traceId: `trace:driver-unavailable:${index}`,
+          arguments: testCase.arguments
+        });
+
+        expect(response.ok).toBe(false);
+        expect(response.error).toMatchObject({
+          code: "E_DRIVER_UNAVAILABLE"
+        });
+      }
+    } finally {
+      runtime.close();
+      input.end();
+      output.end();
+    }
+  });
+
+  it("routes managed-driver tools including profile.use, act, focus/close, and waitFor timeout", async () => {
+    const { input, output, runtime } = createManagedLegacyRuntime();
+
+    try {
+      const profileUseResponse = await sendToolRequest(input, output, {
+        id: "request-profile-use",
+        name: "browser.profile.use",
+        traceId: "trace:matrix:profile-use",
+        arguments: {
+          sessionId: "session:profile-use",
+          profile: "managed"
+        }
+      });
+      expect(profileUseResponse.ok).toBe(true);
+      expect(profileUseResponse.data).toEqual({
+        profile: "managed"
+      });
+
+      const openResponse = await sendToolRequest(input, output, {
+        id: "request-flow-open",
+        name: "browser.tab.open",
+        traceId: "trace:matrix:open",
+        arguments: {
+          sessionId: "session:flow",
+          url: "https://example.com/flow"
+        }
+      });
+      const targetId = (openResponse.data as { targetId: string }).targetId;
+
+      const snapshotResponse = await sendToolRequest(input, output, {
+        id: "request-flow-snapshot",
+        name: "browser.snapshot",
+        traceId: "trace:matrix:snapshot",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(snapshotResponse.ok).toBe(true);
+      expect(snapshotResponse.data).toMatchObject({
+        driver: "managed",
+        targetId
+      });
+
+      const focusResponse = await sendToolRequest(input, output, {
+        id: "request-flow-focus",
+        name: "browser.tab.focus",
+        traceId: "trace:matrix:focus",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(focusResponse.ok).toBe(true);
+      expect(focusResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        focused: true
+      });
+
+      const actResponse = await sendToolRequest(input, output, {
+        id: "request-flow-act",
+        name: "browser.act",
+        traceId: "trace:matrix:act",
+        arguments: {
+          sessionId: "session:flow",
+          targetId,
+          action: {
+            type: "click",
+            payload: {
+              selector: "#go"
+            }
+          }
+        }
+      });
+      expect(actResponse.ok).toBe(true);
+      expect(actResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        result: {
+          actionType: "click",
+          targetId,
+          targetKnown: true,
+          ok: true
+        }
+      });
+
+      const dialogResponse = await sendToolRequest(input, output, {
+        id: "request-flow-dialog",
+        name: "browser.dialog.arm",
+        traceId: "trace:matrix:dialog",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(dialogResponse.ok).toBe(true);
+      expect(dialogResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        armed: true
+      });
+
+      const triggerResponse = await sendToolRequest(input, output, {
+        id: "request-flow-trigger",
+        name: "browser.download.trigger",
+        traceId: "trace:matrix:trigger",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(triggerResponse.ok).toBe(true);
+      expect(triggerResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        triggered: true
+      });
+
+      const waitForResponse = await sendToolRequest(input, output, {
+        id: "request-flow-waitfor",
+        name: "browser.network.waitFor",
+        traceId: "trace:matrix:waitfor",
+        arguments: {
+          sessionId: "session:flow",
+          targetId,
+          urlPattern: "/never-match",
+          timeoutMs: 5,
+          pollMs: 1
+        }
+      });
+      expect(waitForResponse.ok).toBe(false);
+      expect(waitForResponse.error).toMatchObject({
+        code: "E_TIMEOUT"
+      });
+
+      const closeResponse = await sendToolRequest(input, output, {
+        id: "request-flow-close",
+        name: "browser.tab.close",
+        traceId: "trace:matrix:close",
+        arguments: {
+          sessionId: "session:flow",
+          targetId
+        }
+      });
+      expect(closeResponse.ok).toBe(true);
+      expect(closeResponse.data).toMatchObject({
+        driver: "managed",
+        targetId,
+        closed: true
+      });
+    } finally {
+      runtime.close();
+      input.end();
+      output.end();
+    }
+  });
+});

package/extensions/chrome-relay/README-CN.md

@@ -0,0 +1,38 @@
+# BrowserCtl Relay 扩展
+
+[English](README.md) | 简体中文
+
+此扩展用于将 Chromium 系浏览器标签页层连接到本地 BrowserCtl 扩展桥接服务。
+
+## 加载已解压扩展
+
+1. 打开 `chrome://extensions`（Edge 使用 `edge://extensions`）。
+2. 开启**开发者模式**。
+3. 点击**加载已解压的扩展程序**。
+4. 选择目录：`extensions/chrome-relay`。
+
+该扩展使用 `debugger` 权限采集控制台/网络遥测，以供 agent 侧诊断与分析。
+
+## 配置
+
+1. 打开扩展弹窗。
+2. 将 `Bridge URL` 设置为桥接地址。
+3. 将 token 设置为与 `BROWSERD_CHROME_RELAY_EXTENSION_TOKEN` 一致（必填）。
+4. 点击 **Save**，然后点击 **Reconnect**。
+
+默认 Bridge URL：
+
+- `ws://127.0.0.1:9223/bridge`
+
+## 弹窗故障排查
+
+弹窗内置了专门的排查区域：
+
+- **Run Diagnostics**：对比扩展侧连接状态与 relay 侧 `/browserctl/relay/status`。
+- **Copy Report**：复制包含状态快照与建议动作的 JSON 诊断报告。
+- **Guidance list**：给出常见问题的定向建议（URL 不匹配、token 不匹配、relay 不可达、连接陈旧等）。
+
+## 语言切换
+
+使用弹窗语言选择器可切换 **English** 与 **中文**。
+所选语言会保存到扩展本地存储，并在下次打开弹窗时自动应用。

package/extensions/chrome-relay/README.md

@@ -1,5 +1,7 @@
 # BrowserCtl Relay Extension
 
+English | [简体中文](README-CN.md)
+
 This extension connects a Chromium-based browser tab layer to the local BrowserCtl extension bridge.
 
 ## Load Unpacked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flrande/browserctl",
-  "version": "0.1.0",
+  "version": "0.2.0-dev.9.1",
   "private": false,
   "bin": {
     "browserctl": "bin/browserctl.cjs",