@flrande/browserctl 0.1.0-dev.7.1 → 0.1.0-dev.8.1

package/apps/browserctl/src/commands/command-wrappers.test.ts

@@ -0,0 +1,386 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { DAEMON_STARTUP_ARGUMENT } from "./common";
+import { runA11ySnapshotCommand } from "./a11y-snapshot";
+import { runActCommand } from "./act";
+import { runConsoleListCommand } from "./console-list";
+import { runCookieClearCommand } from "./cookie-clear";
+import { runCookieGetCommand } from "./cookie-get";
+import { runCookieSetCommand } from "./cookie-set";
+import { runDialogArmCommand } from "./dialog-arm";
+import { runDomQueryAllCommand } from "./dom-query-all";
+import { runDomQueryCommand } from "./dom-query";
+import { runDownloadTriggerCommand } from "./download-trigger";
+import { runDownloadWaitCommand } from "./download-wait";
+import { runElementScreenshotCommand } from "./element-screenshot";
+import { runFrameListCommand } from "./frame-list";
+import { runFrameSnapshotCommand } from "./frame-snapshot";
+import { runNetworkWaitForCommand } from "./network-wait-for";
+import { runProfileListCommand } from "./profile-list";
+import { runProfileUseCommand } from "./profile-use";
+import { runResponseBodyCommand } from "./response-body";
+import { runScreenshotCommand } from "./screenshot";
+import { runSnapshotCommand } from "./snapshot";
+import { runStatusCommand } from "./status";
+import { runStorageGetCommand } from "./storage-get";
+import { runStorageSetCommand } from "./storage-set";
+import { runTabCloseCommand } from "./tab-close";
+import { runTabFocusCommand } from "./tab-focus";
+import { runTabOpenCommand } from "./tab-open";
+import { runTabsCommand } from "./tabs";
+import { runUploadArmCommand } from "./upload-arm";
+
+type WrapperCase = {
+  name: string;
+  run: () => Promise<unknown>;
+  expectedTool: string;
+  expectedArgs: Record<string, unknown>;
+};
+
+const BASE_ARGS = {
+  sessionId: "cli:local"
+};
+
+const CASES: WrapperCase[] = [
+  {
+    name: "status",
+    run: async () => await runStatusCommand(),
+    expectedTool: "browser.status",
+    expectedArgs: { ...BASE_ARGS }
+  },
+  {
+    name: "tabs",
+    run: async () => await runTabsCommand(),
+    expectedTool: "browser.tab.list",
+    expectedArgs: { ...BASE_ARGS }
+  },
+  {
+    name: "profile-list",
+    run: async () => await runProfileListCommand(),
+    expectedTool: "browser.profile.list",
+    expectedArgs: { ...BASE_ARGS }
+  },
+  {
+    name: "profile-use",
+    run: async () => await runProfileUseCommand(["managed"]),
+    expectedTool: "browser.profile.use",
+    expectedArgs: {
+      ...BASE_ARGS,
+      profile: "managed"
+    }
+  },
+  {
+    name: "tab-open",
+    run: async () => await runTabOpenCommand(["https://example.com"]),
+    expectedTool: "browser.tab.open",
+    expectedArgs: {
+      ...BASE_ARGS,
+      url: "https://example.com"
+    }
+  },
+  {
+    name: "tab-focus",
+    run: async () => await runTabFocusCommand(["target:1"]),
+    expectedTool: "browser.tab.focus",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "tab-close",
+    run: async () => await runTabCloseCommand(["target:1"]),
+    expectedTool: "browser.tab.close",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "snapshot",
+    run: async () => await runSnapshotCommand(["target:1"]),
+    expectedTool: "browser.snapshot",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "screenshot",
+    run: async () => await runScreenshotCommand(["target:1"]),
+    expectedTool: "browser.screenshot",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "dom-query",
+    run: async () => await runDomQueryCommand(["target:1", "#root"]),
+    expectedTool: "browser.dom.query",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      selector: "#root"
+    }
+  },
+  {
+    name: "dom-query-all",
+    run: async () => await runDomQueryAllCommand(["target:1", ".item"]),
+    expectedTool: "browser.dom.queryAll",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      selector: ".item"
+    }
+  },
+  {
+    name: "element-screenshot",
+    run: async () => await runElementScreenshotCommand(["target:1", "#hero"]),
+    expectedTool: "browser.element.screenshot",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      selector: "#hero"
+    }
+  },
+  {
+    name: "a11y-snapshot",
+    run: async () => await runA11ySnapshotCommand(["target:1", "  #main  "]),
+    expectedTool: "browser.a11y.snapshot",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      selector: "#main"
+    }
+  },
+  {
+    name: "network-wait-for",
+    run: async () =>
+      await runNetworkWaitForCommand([
+        "target:1",
+        "/api/items",
+        "--method",
+        "post",
+        "--status",
+        "201",
+        "--timeout-ms",
+        "3000",
+        "--poll-ms",
+        "50"
+      ]),
+    expectedTool: "browser.network.waitFor",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      urlPattern: "/api/items",
+      method: "POST",
+      status: 201,
+      timeoutMs: 3000,
+      pollMs: 50
+    }
+  },
+  {
+    name: "cookie-get",
+    run: async () => await runCookieGetCommand(["target:1", "  sid  "]),
+    expectedTool: "browser.cookie.get",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      name: "sid"
+    }
+  },
+  {
+    name: "cookie-set",
+    run: async () => await runCookieSetCommand(["target:1", "sid", "abc", "  https://example.com  "]),
+    expectedTool: "browser.cookie.set",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      name: "sid",
+      value: "abc",
+      url: "https://example.com"
+    }
+  },
+  {
+    name: "cookie-clear",
+    run: async () => await runCookieClearCommand(["target:1", "  sid  "]),
+    expectedTool: "browser.cookie.clear",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      name: "sid"
+    }
+  },
+  {
+    name: "storage-get",
+    run: async () => await runStorageGetCommand(["target:1", "local", "theme"]),
+    expectedTool: "browser.storage.get",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      scope: "local",
+      key: "theme"
+    }
+  },
+  {
+    name: "storage-set",
+    run: async () => await runStorageSetCommand(["target:1", "session", "token", "abc"]),
+    expectedTool: "browser.storage.set",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      scope: "session",
+      key: "token",
+      value: "abc"
+    }
+  },
+  {
+    name: "frame-list",
+    run: async () => await runFrameListCommand(["target:1"]),
+    expectedTool: "browser.frame.list",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "frame-snapshot",
+    run: async () => await runFrameSnapshotCommand(["target:1", "frame:0"]),
+    expectedTool: "browser.frame.snapshot",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      frameId: "frame:0"
+    }
+  },
+  {
+    name: "act",
+    run: async () => await runActCommand(["click", "target:1"]),
+    expectedTool: "browser.act",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      action: {
+        type: "click"
+      }
+    }
+  },
+  {
+    name: "upload-arm",
+    run: async () => await runUploadArmCommand(["target:1", "a.txt", "b.txt"]),
+    expectedTool: "browser.upload.arm",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      files: ["a.txt", "b.txt"]
+    }
+  },
+  {
+    name: "dialog-arm",
+    run: async () => await runDialogArmCommand(["target:1"]),
+    expectedTool: "browser.dialog.arm",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "download-trigger",
+    run: async () => await runDownloadTriggerCommand(["target:1"]),
+    expectedTool: "browser.download.trigger",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "download-wait",
+    run: async () => await runDownloadWaitCommand(["target:1", "downloads/file.bin"]),
+    expectedTool: "browser.download.wait",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      path: "downloads/file.bin"
+    }
+  },
+  {
+    name: "console-list",
+    run: async () => await runConsoleListCommand(["target:1"]),
+    expectedTool: "browser.console.list",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1"
+    }
+  },
+  {
+    name: "response-body",
+    run: async () => await runResponseBodyCommand(["target:1", "request:1"]),
+    expectedTool: "browser.network.responseBody",
+    expectedArgs: {
+      ...BASE_ARGS,
+      targetId: "target:1",
+      requestId: "request:1"
+    }
+  }
+];
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+  delete process.env.BROWSERCTL_AUTH_TOKEN;
+  delete process.env.BROWSERCTL_BROWSER;
+});
+
+describe("command wrappers", () => {
+  it.each(CASES)("forwards $name to daemon tool", async ({ run, expectedTool, expectedArgs }) => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await run();
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith(expectedTool, expectedArgs);
+  });
+
+  it("forwards session/profile/token/browser context switches", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runStatusCommand([
+      "--session",
+      "session:matrix",
+      "--profile",
+      "chrome-relay",
+      "--token",
+      "cli-token",
+      "--browser",
+      "edge"
+    ]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.status", {
+      sessionId: "session:matrix",
+      profile: "chrome-relay",
+      authToken: "cli-token",
+      [DAEMON_STARTUP_ARGUMENT]: {
+        managedLocal: {
+          browserName: "chromium",
+          channel: "msedge"
+        }
+      }
+    });
+  });
+
+  it("throws for upload-arm when files are missing", async () => {
+    await expect(runUploadArmCommand(["target:1"]))
+      .rejects.toThrow("Missing required argument: files.");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

package/apps/browserctl/src/commands/network-wait-for.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runNetworkWaitForCommand } from "./network-wait-for";
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+});
+
+describe("runNetworkWaitForCommand", () => {
+  it("supports positional timeout shorthand", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runNetworkWaitForCommand(["target:1", "/api", "2500"]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.network.waitFor", {
+      sessionId: "cli:local",
+      targetId: "target:1",
+      urlPattern: "/api",
+      timeoutMs: 2500
+    });
+  });
+
+  it.each([
+    {
+      label: "--method",
+      args: ["target:1", "/api", "--method"],
+      message: "Missing value for --method."
+    },
+    {
+      label: "--status",
+      args: ["target:1", "/api", "--status"],
+      message: "Missing value for --status."
+    },
+    {
+      label: "--timeout-ms",
+      args: ["target:1", "/api", "--timeout-ms"],
+      message: "Missing value for --timeout-ms."
+    },
+    {
+      label: "--poll-ms",
+      args: ["target:1", "/api", "--poll-ms"],
+      message: "Missing value for --poll-ms."
+    }
+  ])("throws when $label is missing a value", async ({ args, message }) => {
+    await expect(runNetworkWaitForCommand(args)).rejects.toThrow(message);
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {
+      label: "status <= 0",
+      args: ["target:1", "/api", "--status", "0"],
+      message: "--status must be a positive integer."
+    },
+    {
+      label: "timeout <= 0",
+      args: ["target:1", "/api", "--timeout-ms", "-10"],
+      message: "--timeout-ms must be a positive integer."
+    },
+    {
+      label: "poll <= 0",
+      args: ["target:1", "/api", "--poll-ms", "0"],
+      message: "--poll-ms must be a positive integer."
+    },
+    {
+      label: "positional timeout <= 0",
+      args: ["target:1", "/api", "0"],
+      message: "timeoutMs must be a positive integer."
+    }
+  ])("throws on non-positive numeric option: $label", async ({ args, message }) => {
+    await expect(runNetworkWaitForCommand(args)).rejects.toThrow(message);
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on unknown option token", async () => {
+    await expect(runNetworkWaitForCommand(["target:1", "/api", "1200", "--unknown"]))
+      .rejects.toThrow("Unknown network-wait-for option: --unknown");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

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/package.json

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