@flrande/browserctl 0.1.0

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

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type A11ySnapshotCommandResult = Record<string, unknown>;
+
+export async function runA11ySnapshotCommand(args: string[]): Promise<A11ySnapshotCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const selector = context.positional[1];
+
+  return await callDaemonTool<A11ySnapshotCommandResult>(
+    "browser.a11y.snapshot",
+    buildToolArguments(context, {
+      targetId,
+      ...(typeof selector === "string" && selector.trim().length > 0
+        ? { selector: selector.trim() }
+        : {})
+    })
+  );
+}

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

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

package/apps/browserctl/src/commands/common.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  DAEMON_STARTUP_ARGUMENT,
+  buildToolArguments,
+  parseCommandContext
+} from "./common";
+
+const ORIGINAL_AUTH_TOKEN = process.env.BROWSERCTL_AUTH_TOKEN;
+const ORIGINAL_BROWSER = process.env.BROWSERCTL_BROWSER;
+
+afterEach(() => {
+  if (ORIGINAL_AUTH_TOKEN === undefined) {
+    delete process.env.BROWSERCTL_AUTH_TOKEN;
+  } else {
+    process.env.BROWSERCTL_AUTH_TOKEN = ORIGINAL_AUTH_TOKEN;
+  }
+
+  if (ORIGINAL_BROWSER === undefined) {
+    delete process.env.BROWSERCTL_BROWSER;
+    return;
+  }
+
+  process.env.BROWSERCTL_BROWSER = ORIGINAL_BROWSER;
+});
+
+describe("parseCommandContext", () => {
+  it("uses BROWSERCTL_AUTH_TOKEN by default", () => {
+    process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+    const context = parseCommandContext(["target:1"]);
+
+    expect(context.authToken).toBe("env-token");
+    expect(context.positional).toEqual(["target:1"]);
+  });
+
+  it("allows --token to override the environment token", () => {
+    process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+
+    const context = parseCommandContext(["--token", "cli-token", "target:1"]);
+
+    expect(context.authToken).toBe("cli-token");
+    expect(context.positional).toEqual(["target:1"]);
+  });
+
+  it("throws when --token is missing a value", () => {
+    expect(() => parseCommandContext(["--token"])).toThrow("Missing value for --token.");
+  });
+
+  it("supports --browser edge preset and forwards daemon startup metadata", () => {
+    const context = parseCommandContext(["--browser", "edge", "target:1"]);
+
+    expect(context.daemonStartup).toEqual({
+      managedLocal: {
+        browserName: "chromium",
+        channel: "msedge"
+      }
+    });
+    expect(buildToolArguments(context)).toMatchObject({
+      [DAEMON_STARTUP_ARGUMENT]: {
+        managedLocal: {
+          browserName: "chromium",
+          channel: "msedge"
+        }
+      }
+    });
+  });
+
+  it("supports BROWSERCTL_BROWSER env preset", () => {
+    process.env.BROWSERCTL_BROWSER = "edge";
+
+    const context = parseCommandContext(["target:1"]);
+
+    expect(context.daemonStartup).toEqual({
+      managedLocal: {
+        browserName: "chromium",
+        channel: "msedge"
+      }
+    });
+  });
+
+  it("throws on unsupported --browser values", () => {
+    expect(() => parseCommandContext(["--browser", "opera"])).toThrow(
+      "Invalid value for --browser: opera. Supported values: chromium, chrome, edge."
+    );
+  });
+});

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

@@ -0,0 +1,191 @@
+export type ManagedLocalBrowserPreset = "chromium" | "chrome" | "edge";
+
+export type DaemonStartupConfig = {
+  managedLocal: {
+    browserName: "chromium";
+    channel?: string;
+  };
+};
+
+export type CommandContext = {
+  sessionId: string;
+  profile?: string;
+  authToken?: string;
+  daemonStartup?: DaemonStartupConfig;
+  positional: string[];
+};
+
+export const DAEMON_STARTUP_ARGUMENT = "__browserctlDaemonStartup";
+
+const DEFAULT_SESSION_ID = "cli:local";
+const SUPPORTED_BROWSER_PRESETS = new Set<ManagedLocalBrowserPreset>([
+  "chromium",
+  "chrome",
+  "edge"
+]);
+
+function resolveAuthToken(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+  return trimmedValue.length > 0 ? trimmedValue : undefined;
+}
+
+function requireValue(args: string[], index: number, option: string): string {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`Missing value for ${option}.`);
+  }
+
+  return value;
+}
+
+function parseBrowserPreset(
+  value: string | undefined,
+  optionName: string
+): ManagedLocalBrowserPreset | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalizedValue = value.trim().toLowerCase();
+  if (normalizedValue.length === 0) {
+    return undefined;
+  }
+
+  if (SUPPORTED_BROWSER_PRESETS.has(normalizedValue as ManagedLocalBrowserPreset)) {
+    return normalizedValue as ManagedLocalBrowserPreset;
+  }
+
+  throw new Error(
+    `Invalid value for ${optionName}: ${value}. Supported values: chromium, chrome, edge.`
+  );
+}
+
+function resolveDaemonStartupConfig(
+  browserPreset: ManagedLocalBrowserPreset | undefined
+): DaemonStartupConfig | undefined {
+  if (browserPreset === undefined) {
+    return undefined;
+  }
+
+  if (browserPreset === "edge") {
+    return {
+      managedLocal: {
+        browserName: "chromium",
+        channel: "msedge"
+      }
+    };
+  }
+
+  if (browserPreset === "chrome") {
+    return {
+      managedLocal: {
+        browserName: "chromium",
+        channel: "chrome"
+      }
+    };
+  }
+
+  return {
+    managedLocal: {
+      browserName: "chromium"
+    }
+  };
+}
+
+export function parseCommandContext(args: string[]): CommandContext {
+  const positional: string[] = [];
+  let sessionId = DEFAULT_SESSION_ID;
+  let profile: string | undefined;
+  let authToken = resolveAuthToken(process.env.BROWSERCTL_AUTH_TOKEN);
+  let browserPreset = parseBrowserPreset(process.env.BROWSERCTL_BROWSER, "BROWSERCTL_BROWSER");
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+
+    if (token === "--session") {
+      sessionId = requireValue(args, index, "--session");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--profile") {
+      profile = requireValue(args, index, "--profile");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--token") {
+      authToken = resolveAuthToken(requireValue(args, index, "--token"));
+      if (authToken === undefined) {
+        throw new Error("Missing value for --token.");
+      }
+
+      index += 1;
+      continue;
+    }
+
+    if (token === "--browser") {
+      browserPreset = parseBrowserPreset(requireValue(args, index, "--browser"), "--browser");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--") {
+      positional.push(...args.slice(index + 1));
+      break;
+    }
+
+    positional.push(token);
+  }
+
+  return {
+    sessionId,
+    profile,
+    authToken,
+    daemonStartup: resolveDaemonStartupConfig(browserPreset),
+    positional
+  };
+}
+
+export function buildToolArguments(
+  context: CommandContext,
+  args: Record<string, unknown> = {}
+): Record<string, unknown> {
+  const baseArguments: Record<string, unknown> = {
+    sessionId: context.sessionId
+  };
+
+  if (context.profile !== undefined) {
+    baseArguments.profile = context.profile;
+  }
+
+  if (context.authToken !== undefined) {
+    baseArguments.authToken = context.authToken;
+  }
+
+  if (context.daemonStartup !== undefined) {
+    baseArguments[DAEMON_STARTUP_ARGUMENT] = context.daemonStartup;
+  }
+
+  return {
+    ...baseArguments,
+    ...args
+  };
+}
+
+export function requirePositionalArg(
+  context: CommandContext,
+  index: number,
+  name: string
+): string {
+  const value = context.positional[index];
+  if (value === undefined) {
+    throw new Error(`Missing required argument: ${name}.`);
+  }
+
+  return value;
+}

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

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type ConsoleListCommandResult = {
+  driver: string;
+  targetId: string;
+  entries: unknown[];
+};
+
+export async function runConsoleListCommand(args: string[]): Promise<ConsoleListCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<ConsoleListCommandResult>(
+    "browser.console.list",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/cookie-clear.ts

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type CookieClearCommandResult = Record<string, unknown>;
+
+export async function runCookieClearCommand(args: string[]): Promise<CookieClearCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const name = context.positional[1];
+
+  return await callDaemonTool<CookieClearCommandResult>(
+    "browser.cookie.clear",
+    buildToolArguments(context, {
+      targetId,
+      ...(typeof name === "string" && name.trim().length > 0 ? { name: name.trim() } : {})
+    })
+  );
+}

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

@@ -0,0 +1,18 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type CookieGetCommandResult = Record<string, unknown>;
+
+export async function runCookieGetCommand(args: string[]): Promise<CookieGetCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const name = context.positional[1];
+
+  return await callDaemonTool<CookieGetCommandResult>(
+    "browser.cookie.get",
+    buildToolArguments(context, {
+      targetId,
+      ...(typeof name === "string" && name.trim().length > 0 ? { name: name.trim() } : {})
+    })
+  );
+}

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

@@ -0,0 +1,22 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type CookieSetCommandResult = Record<string, unknown>;
+
+export async function runCookieSetCommand(args: string[]): Promise<CookieSetCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const name = requirePositionalArg(context, 1, "name");
+  const value = requirePositionalArg(context, 2, "value");
+  const url = context.positional[3];
+
+  return await callDaemonTool<CookieSetCommandResult>(
+    "browser.cookie.set",
+    buildToolArguments(context, {
+      targetId,
+      name,
+      value,
+      ...(typeof url === "string" && url.trim().length > 0 ? { url: url.trim() } : {})
+    })
+  );
+}

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

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

package/apps/browserctl/src/commands/dom-query-all.ts

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

package/apps/browserctl/src/commands/dom-query.ts

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

package/apps/browserctl/src/commands/download-trigger.ts

@@ -0,0 +1,22 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type DownloadTriggerCommandResult = {
+  driver: string;
+  targetId: string;
+  triggered: boolean;
+};
+
+export async function runDownloadTriggerCommand(
+  args: string[]
+): Promise<DownloadTriggerCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+
+  return await callDaemonTool<DownloadTriggerCommandResult>(
+    "browser.download.trigger",
+    buildToolArguments(context, {
+      targetId
+    })
+  );
+}

package/apps/browserctl/src/commands/download-wait.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runDownloadWaitCommand } from "./download-wait";
+
+const ORIGINAL_AUTH_TOKEN = process.env.BROWSERCTL_AUTH_TOKEN;
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+
+  if (ORIGINAL_AUTH_TOKEN === undefined) {
+    delete process.env.BROWSERCTL_AUTH_TOKEN;
+    return;
+  }
+
+  process.env.BROWSERCTL_AUTH_TOKEN = ORIGINAL_AUTH_TOKEN;
+});
+
+describe("runDownloadWaitCommand", () => {
+  it("forwards optional download path when provided", async () => {
+    callDaemonToolMock.mockResolvedValue({
+      driver: "managed",
+      targetId: "target:1",
+      download: {}
+    });
+
+    await runDownloadWaitCommand(["target:1", "downloads/file.bin"]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith(
+      "browser.download.wait",
+      expect.objectContaining({
+        sessionId: "cli:local",
+        targetId: "target:1",
+        path: "downloads/file.bin"
+      })
+    );
+  });
+
+  it("uses --token over environment token", async () => {
+    process.env.BROWSERCTL_AUTH_TOKEN = "env-token";
+    callDaemonToolMock.mockResolvedValue({
+      driver: "managed",
+      targetId: "target:1",
+      download: {}
+    });
+
+    await runDownloadWaitCommand(["--token", "cli-token", "target:1"]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith(
+      "browser.download.wait",
+      expect.objectContaining({
+        sessionId: "cli:local",
+        targetId: "target:1",
+        authToken: "cli-token"
+      })
+    );
+  });
+});

package/apps/browserctl/src/commands/download-wait.ts

@@ -0,0 +1,27 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type DownloadWaitCommandResult = {
+  driver: string;
+  targetId: string;
+  download: Record<string, unknown>;
+};
+
+export async function runDownloadWaitCommand(args: string[]): Promise<DownloadWaitCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const path = context.positional[1];
+
+  return await callDaemonTool<DownloadWaitCommandResult>(
+    "browser.download.wait",
+    buildToolArguments(
+      context,
+      path === undefined
+        ? { targetId }
+        : {
+            targetId,
+            path
+          }
+    )
+  );
+}

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

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

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

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

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

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