@flrande/browserctl 0.1.0

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

@@ -0,0 +1,100 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type NetworkWaitForCommandResult = Record<string, unknown>;
+
+function parsePositiveInteger(value: string, optionName: string): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${optionName} must be a positive integer.`);
+  }
+
+  return parsed;
+}
+
+function parseNetworkWaitOptions(tokens: string[]): {
+  method?: string;
+  status?: number;
+  timeoutMs?: number;
+  pollMs?: number;
+} {
+  let method: string | undefined;
+  let status: number | undefined;
+  let timeoutMs: number | undefined;
+  let pollMs: number | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--method") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --method.");
+      }
+      method = value.trim().toUpperCase();
+      index += 1;
+      continue;
+    }
+
+    if (token === "--status") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --status.");
+      }
+      status = parsePositiveInteger(value, "--status");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--timeout-ms") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --timeout-ms.");
+      }
+      timeoutMs = parsePositiveInteger(value, "--timeout-ms");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--poll-ms") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --poll-ms.");
+      }
+      pollMs = parsePositiveInteger(value, "--poll-ms");
+      index += 1;
+      continue;
+    }
+
+    if (timeoutMs === undefined) {
+      timeoutMs = parsePositiveInteger(token, "timeoutMs");
+      continue;
+    }
+
+    throw new Error(`Unknown network-wait-for option: ${token}`);
+  }
+
+  return {
+    ...(method !== undefined ? { method } : {}),
+    ...(status !== undefined ? { status } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    ...(pollMs !== undefined ? { pollMs } : {})
+  };
+}
+
+export async function runNetworkWaitForCommand(
+  args: string[]
+): Promise<NetworkWaitForCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const urlPattern = requirePositionalArg(context, 1, "urlPattern");
+  const options = parseNetworkWaitOptions(context.positional.slice(2));
+
+  return await callDaemonTool<NetworkWaitForCommandResult>(
+    "browser.network.waitFor",
+    buildToolArguments(context, {
+      targetId,
+      urlPattern,
+      ...options
+    })
+  );
+}

package/apps/browserctl/src/commands/profile-list.ts

@@ -0,0 +1,16 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type ProfileListCommandResult = {
+  driver: string;
+  profiles: string[];
+};
+
+export async function runProfileListCommand(args: string[] = []): Promise<ProfileListCommandResult> {
+  const context = parseCommandContext(args);
+
+  return await callDaemonTool<ProfileListCommandResult>(
+    "browser.profile.list",
+    buildToolArguments(context)
+  );
+}

package/apps/browserctl/src/commands/profile-use.ts

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type ProfileUseCommandResult = {
+  profile: string;
+};
+
+export async function runProfileUseCommand(args: string[]): Promise<ProfileUseCommandResult> {
+  const context = parseCommandContext(args);
+  const profile = requirePositionalArg(context, 0, "profile");
+
+  return await callDaemonTool<ProfileUseCommandResult>(
+    "browser.profile.use",
+    buildToolArguments(context, {
+      profile
+    })
+  );
+}

package/apps/browserctl/src/commands/response-body.ts

@@ -0,0 +1,24 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type ResponseBodyCommandResult = {
+  driver: string;
+  targetId: string;
+  requestId: string;
+  body: string;
+  encoding: string;
+};
+
+export async function runResponseBodyCommand(args: string[]): Promise<ResponseBodyCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const requestId = requirePositionalArg(context, 1, "requestId");
+
+  return await callDaemonTool<ResponseBodyCommandResult>(
+    "browser.network.responseBody",
+    buildToolArguments(context, {
+      targetId,
+      requestId
+    })
+  );
+}

package/apps/browserctl/src/commands/screenshot.ts

@@ -0,0 +1,16 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type ScreenshotCommandResult = Record<string, unknown>;
+
+export async function runScreenshotCommand(args: string[]): Promise<ScreenshotCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<ScreenshotCommandResult>(
+    "browser.screenshot",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/snapshot.ts

@@ -0,0 +1,16 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type SnapshotCommandResult = Record<string, unknown>;
+
+export async function runSnapshotCommand(args: string[]): Promise<SnapshotCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<SnapshotCommandResult>(
+    "browser.snapshot",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/status.ts

@@ -0,0 +1,10 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type StatusCommandResult = Record<string, unknown>;
+
+export async function runStatusCommand(args: string[] = []): Promise<StatusCommandResult> {
+  const context = parseCommandContext(args);
+
+  return await callDaemonTool<StatusCommandResult>("browser.status", buildToolArguments(context));
+}

package/apps/browserctl/src/commands/storage-get.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type StorageGetCommandResult = Record<string, unknown>;
+
+export async function runStorageGetCommand(args: string[]): Promise<StorageGetCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const scope = requirePositionalArg(context, 1, "scope");
+  const key = requirePositionalArg(context, 2, "key");
+
+  return await callDaemonTool<StorageGetCommandResult>(
+    "browser.storage.get",
+    buildToolArguments(context, {
+      targetId,
+      scope,
+      key
+    })
+  );
+}

package/apps/browserctl/src/commands/storage-set.ts

@@ -0,0 +1,22 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type StorageSetCommandResult = Record<string, unknown>;
+
+export async function runStorageSetCommand(args: string[]): Promise<StorageSetCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const scope = requirePositionalArg(context, 1, "scope");
+  const key = requirePositionalArg(context, 2, "key");
+  const value = requirePositionalArg(context, 3, "value");
+
+  return await callDaemonTool<StorageSetCommandResult>(
+    "browser.storage.set",
+    buildToolArguments(context, {
+      targetId,
+      scope,
+      key,
+      value
+    })
+  );
+}

package/apps/browserctl/src/commands/tab-close.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type TabCloseCommandResult = {
+  driver: string;
+  targetId: string;
+  closed: boolean;
+};
+
+export async function runTabCloseCommand(args: string[]): Promise<TabCloseCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<TabCloseCommandResult>(
+    "browser.tab.close",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/tab-focus.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type TabFocusCommandResult = {
+  driver: string;
+  targetId: string;
+  focused: boolean;
+};
+
+export async function runTabFocusCommand(args: string[]): Promise<TabFocusCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<TabFocusCommandResult>(
+    "browser.tab.focus",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/tab-open.ts

@@ -0,0 +1,19 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type TabOpenCommandResult = {
+  driver: string;
+  targetId: string;
+};
+
+export async function runTabOpenCommand(args: string[]): Promise<TabOpenCommandResult> {
+  const context = parseCommandContext(args);
+  const url = requirePositionalArg(context, 0, "url");
+
+  return await callDaemonTool<TabOpenCommandResult>(
+    "browser.tab.open",
+    buildToolArguments(context, {
+      url
+    })
+  );
+}

package/apps/browserctl/src/commands/tabs.ts

@@ -0,0 +1,13 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type TabsCommandResult = {
+  driver: string;
+  tabs: string[];
+};
+
+export async function runTabsCommand(args: string[] = []): Promise<TabsCommandResult> {
+  const context = parseCommandContext(args);
+
+  return await callDaemonTool<TabsCommandResult>("browser.tab.list", buildToolArguments(context));
+}

package/apps/browserctl/src/commands/upload-arm.ts

@@ -0,0 +1,26 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type UploadArmCommandResult = {
+  driver: string;
+  targetId: string;
+  armed: boolean;
+  files: string[];
+};
+
+export async function runUploadArmCommand(args: string[]): Promise<UploadArmCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const files = context.positional.slice(1);
+  if (files.length === 0) {
+    throw new Error("Missing required argument: files.");
+  }
+
+  return await callDaemonTool<UploadArmCommandResult>(
+    "browser.upload.arm",
+    buildToolArguments(context, {
+      targetId,
+      files
+    })
+  );
+}

package/apps/browserctl/src/daemon-client.test.ts

@@ -0,0 +1,253 @@
+import { createServer, type AddressInfo } from "node:net";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DAEMON_STARTUP_ARGUMENT } from "./commands/common";
+import { callDaemonTool, getDaemonStatus, stopDaemon } from "./daemon-client";
+
+type CapturedRequest = {
+  id: string;
+  name: string;
+  traceId: string;
+  arguments: Record<string, unknown>;
+};
+
+const ORIGINAL_DAEMON_PORT = process.env.BROWSERCTL_DAEMON_PORT;
+const ORIGINAL_AUTH_TOKEN = process.env.BROWSERCTL_AUTH_TOKEN;
+const TEST_PID_PORTS = new Set<number>();
+
+function resolveRuntimeDirForTests(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  return resolve(dirname(currentFile), "../../../.browserctl-runtime");
+}
+
+function resolvePidFileForTests(port: number): string {
+  return join(resolveRuntimeDirForTests(), `daemon-${port}.pid`);
+}
+
+function writePidRecordForTests(port: number, record: number | { pid: number; authToken?: string }): void {
+  mkdirSync(resolveRuntimeDirForTests(), { recursive: true });
+  writeFileSync(
+    resolvePidFileForTests(port),
+    typeof record === "number" ? String(record) : JSON.stringify(record),
+    { encoding: "utf8" }
+  );
+  TEST_PID_PORTS.add(port);
+}
+
+afterEach(() => {
+  if (ORIGINAL_DAEMON_PORT === undefined) {
+    delete process.env.BROWSERCTL_DAEMON_PORT;
+  } else {
+    process.env.BROWSERCTL_DAEMON_PORT = ORIGINAL_DAEMON_PORT;
+  }
+
+  if (ORIGINAL_AUTH_TOKEN === undefined) {
+    delete process.env.BROWSERCTL_AUTH_TOKEN;
+  } else {
+    process.env.BROWSERCTL_AUTH_TOKEN = ORIGINAL_AUTH_TOKEN;
+  }
+
+  for (const port of TEST_PID_PORTS) {
+    rmSync(resolvePidFileForTests(port), { force: true });
+  }
+  TEST_PID_PORTS.clear();
+  vi.restoreAllMocks();
+});
+
+async function withDaemonHarness(
+  run: (state: { port: number; requests: CapturedRequest[] }) => Promise<void>
+): Promise<void> {
+  const requests: CapturedRequest[] = [];
+  const server = createServer((socket) => {
+    socket.setEncoding("utf8");
+    let buffer = "";
+
+    socket.on("data", (chunk: string) => {
+      buffer += chunk;
+
+      let lineBreakIndex = buffer.indexOf("\n");
+      while (lineBreakIndex >= 0) {
+        const line = buffer.slice(0, lineBreakIndex).trim();
+        buffer = buffer.slice(lineBreakIndex + 1);
+
+        if (line.length === 0) {
+          lineBreakIndex = buffer.indexOf("\n");
+          continue;
+        }
+
+        const request = JSON.parse(line) as CapturedRequest;
+        requests.push(request);
+        socket.write(
+          `${JSON.stringify({
+            id: request.id,
+            ok: true,
+            traceId: request.traceId,
+            sessionId:
+              typeof request.arguments.sessionId === "string"
+                ? request.arguments.sessionId
+                : "cli:test",
+            data: {
+              ok: true
+            }
+          })}\n`
+        );
+
+        lineBreakIndex = buffer.indexOf("\n");
+      }
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  const address = server.address() as AddressInfo;
+
+  try {
+    await run({ port: address.port, requests });
+  } finally {
+    await new Promise<void>((resolve, reject) => {
+      server.close((error) => {
+        if (error !== undefined) {
+          reject(error);
+          return;
+        }
+
+        resolve();
+      });
+    });
+  }
+}
+
+describe("daemon client auth token forwarding", () => {
+  it("includes env token in daemon status probes", async () => {
+    await withDaemonHarness(async ({ port, requests }) => {
+      process.env.BROWSERCTL_DAEMON_PORT = String(port);
+      process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+      const status = await getDaemonStatus();
+
+      expect(status.running).toBe(true);
+      expect(requests).toHaveLength(1);
+      expect(requests[0]).toMatchObject({
+        name: "browser.status",
+        arguments: {
+          sessionId: "cli:daemon-status",
+          authToken: "env-token"
+        }
+      });
+    });
+  });
+
+  it("includes env token in tool calls when not explicitly provided", async () => {
+    await withDaemonHarness(async ({ port, requests }) => {
+      process.env.BROWSERCTL_DAEMON_PORT = String(port);
+      process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+      await callDaemonTool("browser.tab.list", {
+        sessionId: "cli:test"
+      });
+
+      expect(requests).toHaveLength(1);
+      expect(requests[0]).toMatchObject({
+        name: "browser.tab.list",
+        arguments: {
+          sessionId: "cli:test",
+          authToken: "env-token"
+        }
+      });
+    });
+  });
+
+  it("preserves explicit authToken in tool calls", async () => {
+    await withDaemonHarness(async ({ port, requests }) => {
+      process.env.BROWSERCTL_DAEMON_PORT = String(port);
+      process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+      await callDaemonTool("browser.tab.list", {
+        sessionId: "cli:test",
+        authToken: "cli-token"
+      });
+
+      expect(requests).toHaveLength(1);
+      expect(requests[0]).toMatchObject({
+        name: "browser.tab.list",
+        arguments: {
+          sessionId: "cli:test",
+          authToken: "cli-token"
+        }
+      });
+    });
+  });
+
+  it("does not forward internal daemon startup metadata as tool arguments", async () => {
+    await withDaemonHarness(async ({ port, requests }) => {
+      process.env.BROWSERCTL_DAEMON_PORT = String(port);
+
+      await callDaemonTool("browser.tab.list", {
+        sessionId: "cli:test",
+        [DAEMON_STARTUP_ARGUMENT]: {
+          managedLocal: {
+            browserName: "chromium",
+            channel: "msedge"
+          }
+        }
+      });
+
+      expect(requests).toHaveLength(1);
+      expect(requests[0].arguments).toMatchObject({
+        sessionId: "cli:test"
+      });
+      expect(requests[0].arguments).not.toHaveProperty(DAEMON_STARTUP_ARGUMENT);
+    });
+  });
+
+  it("reuses persisted daemon auth token when env token is missing", async () => {
+    await withDaemonHarness(async ({ port, requests }) => {
+      process.env.BROWSERCTL_DAEMON_PORT = String(port);
+      delete process.env.BROWSERCTL_AUTH_TOKEN;
+      writePidRecordForTests(port, {
+        pid: 12345,
+        authToken: "persisted-token"
+      });
+
+      const status = await getDaemonStatus();
+
+      expect(status.running).toBe(true);
+      expect(requests).toHaveLength(1);
+      expect(requests[0]).toMatchObject({
+        name: "browser.status",
+        arguments: {
+          sessionId: "cli:daemon-status",
+          authToken: "persisted-token"
+        }
+      });
+    });
+  });
+
+  it("avoids killing stale pid records when daemon cannot be verified", async () => {
+    const unreachablePort = 45999;
+    writePidRecordForTests(unreachablePort, {
+      pid: 70001,
+      authToken: "persisted-token"
+    });
+
+    const killSpy = vi.spyOn(process, "kill").mockImplementation(() => true);
+    const stopResult = await stopDaemon(unreachablePort);
+
+    expect(stopResult).toMatchObject({
+      stopped: false,
+      port: unreachablePort,
+      pid: 70001
+    });
+    expect(killSpy).not.toHaveBeenCalled();
+  });
+});