@flrande/browserctl 0.4.0-dev.15.1 → 0.5.0-dev.19.1

package/apps/browserctl/src/commands/network-list.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runNetworkListCommand } from "./network-list";
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+});
+
+describe("runNetworkListCommand", () => {
+  it("forwards filter options", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runNetworkListCommand([
+      "target:1",
+      "--url-contains",
+      "/api/",
+      "--method",
+      "post",
+      "--status",
+      "201",
+      "--since",
+      "2026-01-01T00:00:00.000Z",
+      "--limit",
+      "50"
+    ]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.network.list", {
+      sessionId: "cli:local",
+      targetId: "target:1",
+      urlContains: "/api/",
+      method: "POST",
+      status: 201,
+      since: "2026-01-01T00:00:00.000Z",
+      limit: 50
+    });
+  });
+
+  it.each([
+    {
+      label: "--url-contains",
+      args: ["target:1", "--url-contains"],
+      message: "Missing value for --url-contains."
+    },
+    {
+      label: "--method",
+      args: ["target:1", "--method"],
+      message: "Missing value for --method."
+    },
+    {
+      label: "--status",
+      args: ["target:1", "--status"],
+      message: "Missing value for --status."
+    },
+    {
+      label: "--since",
+      args: ["target:1", "--since"],
+      message: "Missing value for --since."
+    },
+    {
+      label: "--limit",
+      args: ["target:1", "--limit"],
+      message: "Missing value for --limit."
+    }
+  ])("throws when $label is missing a value", async ({ args, message }) => {
+    await expect(runNetworkListCommand(args)).rejects.toThrow(message);
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {
+      label: "empty --url-contains",
+      args: ["target:1", "--url-contains", " "],
+      message: "--url-contains must be a non-empty string."
+    },
+    {
+      label: "status <= 0",
+      args: ["target:1", "--status", "0"],
+      message: "--status must be a positive integer."
+    },
+    {
+      label: "status non-strict integer text",
+      args: ["target:1", "--status", "200ok"],
+      message: "--status must be a positive integer."
+    },
+    {
+      label: "limit <= 0",
+      args: ["target:1", "--limit", "0"],
+      message: "--limit must be a positive integer."
+    }
+  ])("throws on invalid option value: $label", async ({ args, message }) => {
+    await expect(runNetworkListCommand(args)).rejects.toThrow(message);
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on unknown option token", async () => {
+    await expect(runNetworkListCommand(["target:1", "--unknown"]))
+      .rejects.toThrow("Unknown network-list option: --unknown");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,112 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type NetworkListCommandResult = Record<string, unknown>;
+
+function parsePositiveInteger(value: string, optionName: string): number {
+  const normalized = value.trim();
+  if (!/^[1-9]\d*$/.test(normalized)) {
+    throw new Error(`${optionName} must be a positive integer.`);
+  }
+
+  return Number.parseInt(normalized, 10);
+}
+
+function parseNetworkListOptions(tokens: string[]): {
+  urlContains?: string;
+  method?: string;
+  status?: number;
+  since?: string;
+  limit?: number;
+} {
+  let urlContains: string | undefined;
+  let method: string | undefined;
+  let status: number | undefined;
+  let since: string | undefined;
+  let limit: number | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--url-contains") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --url-contains.");
+      }
+      const trimmed = value.trim();
+      if (trimmed.length === 0) {
+        throw new Error("--url-contains must be a non-empty string.");
+      }
+      urlContains = trimmed;
+      index += 1;
+      continue;
+    }
+
+    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 === "--since") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --since.");
+      }
+      const trimmed = value.trim();
+      if (trimmed.length === 0) {
+        throw new Error("--since must be a non-empty ISO timestamp.");
+      }
+      since = trimmed;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--limit") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --limit.");
+      }
+      limit = parsePositiveInteger(value, "--limit");
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown network-list option: ${token}`);
+  }
+
+  return {
+    ...(urlContains !== undefined ? { urlContains } : {}),
+    ...(method !== undefined ? { method } : {}),
+    ...(status !== undefined ? { status } : {}),
+    ...(since !== undefined ? { since } : {}),
+    ...(limit !== undefined ? { limit } : {})
+  };
+}
+
+export async function runNetworkListCommand(args: string[]): Promise<NetworkListCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const options = parseNetworkListOptions(context.positional.slice(1));
+
+  return await callDaemonTool<NetworkListCommandResult>(
+    "browser.network.list",
+    buildToolArguments(context, {
+      targetId,
+      ...options
+    })
+  );
+}

package/apps/browserctl/src/commands/session-drop.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runSessionDropCommand } from "./session-drop";
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+});
+
+describe("runSessionDropCommand", () => {
+  it("forwards session id to drop", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runSessionDropCommand(["tenant-a:task-1"]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.session.drop", {
+      sessionId: "cli:local",
+      sessionIdToDelete: "tenant-a:task-1"
+    });
+  });
+
+  it("throws when session id is missing", async () => {
+    await expect(runSessionDropCommand([])).rejects.toThrow(
+      "Missing required argument: sessionId."
+    );
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

package/apps/browserctl/src/commands/session-drop.ts

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

package/apps/browserctl/src/commands/session-list.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runSessionListCommand } from "./session-list";
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+});
+
+describe("runSessionListCommand", () => {
+  it("forwards tenant and limit filters", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runSessionListCommand([
+      "--tenant",
+      "finance",
+      "--limit",
+      "20"
+    ]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.session.list", {
+      sessionId: "cli:local",
+      tenant: "finance",
+      limit: 20
+    });
+  });
+
+  it("supports no options", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runSessionListCommand([]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.session.list", {
+      sessionId: "cli:local"
+    });
+  });
+
+  it("throws when --tenant is missing value", async () => {
+    await expect(runSessionListCommand(["--tenant"])).rejects.toThrow(
+      "Missing value for --tenant."
+    );
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws when --limit is missing value", async () => {
+    await expect(runSessionListCommand(["--limit"])).rejects.toThrow(
+      "Missing value for --limit."
+    );
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on invalid --limit", async () => {
+    await expect(runSessionListCommand(["--limit", "0"])).rejects.toThrow(
+      "--limit must be a positive integer."
+    );
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-strict integer text for --limit", async () => {
+    await expect(runSessionListCommand(["--limit", "20abc"])).rejects.toThrow(
+      "--limit must be a positive integer."
+    );
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on unknown option token", async () => {
+    await expect(runSessionListCommand(["--unknown"])).rejects.toThrow(
+      "Unknown session-list option: --unknown"
+    );
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,70 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type SessionListCommandResult = Record<string, unknown>;
+
+function parsePositiveInteger(value: string, optionName: string): number {
+  const normalized = value.trim();
+  if (!/^[1-9]\d*$/.test(normalized)) {
+    throw new Error(`${optionName} must be a positive integer.`);
+  }
+
+  return Number.parseInt(normalized, 10);
+}
+
+function parseSessionListOptions(tokens: string[]): {
+  tenant?: string;
+  limit?: number;
+} {
+  let tenant: string | undefined;
+  let limit: number | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--tenant") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --tenant.");
+      }
+
+      const trimmedValue = value.trim();
+      if (trimmedValue.length === 0) {
+        throw new Error("--tenant must be a non-empty string.");
+      }
+
+      tenant = trimmedValue;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--limit") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --limit.");
+      }
+
+      limit = parsePositiveInteger(value, "--limit");
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown session-list option: ${token}`);
+  }
+
+  return {
+    ...(tenant !== undefined ? { tenant } : {}),
+    ...(limit !== undefined ? { limit } : {})
+  };
+}
+
+export async function runSessionListCommand(args: string[]): Promise<SessionListCommandResult> {
+  const context = parseCommandContext(args);
+  const options = parseSessionListOptions(context.positional);
+
+  return await callDaemonTool<SessionListCommandResult>(
+    "browser.session.list",
+    buildToolArguments(context, {
+      ...options
+    })
+  );
+}

package/apps/browserctl/src/commands/trace-get.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runTraceGetCommand } from "./trace-get";
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+});
+
+describe("runTraceGetCommand", () => {
+  it("forwards limit option", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runTraceGetCommand(["--limit", "50"]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.trace.get", {
+      sessionId: "cli:local",
+      limit: 50
+    });
+  });
+
+  it("supports empty options", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runTraceGetCommand([]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.trace.get", {
+      sessionId: "cli:local"
+    });
+  });
+
+  it("throws when --limit is missing a value", async () => {
+    await expect(runTraceGetCommand(["--limit"]))
+      .rejects.toThrow("Missing value for --limit.");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws when --limit is invalid", async () => {
+    await expect(runTraceGetCommand(["--limit", "0"]))
+      .rejects.toThrow("--limit must be a positive integer.");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on unknown option token", async () => {
+    await expect(runTraceGetCommand(["--unknown"]))
+      .rejects.toThrow("Unknown trace-get option: --unknown");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,62 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+type TraceGetKeyResponse = {
+  stepIndex?: number;
+  kind?: string;
+  timestamp?: string;
+  data?: {
+    memoryHit?: boolean;
+  } & Record<string, unknown>;
+};
+
+export type TraceGetCommandResult = {
+  sessionId?: string;
+  steps?: Array<Record<string, unknown>>;
+  keyResponses?: TraceGetKeyResponse[];
+  screenshots?: Array<Record<string, unknown>>;
+} & 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 parseTraceGetOptions(tokens: string[]): {
+  limit?: number;
+} {
+  let limit: number | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--limit") {
+      const value = tokens[index + 1];
+      if (value === undefined) {
+        throw new Error("Missing value for --limit.");
+      }
+      limit = parsePositiveInteger(value, "--limit");
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown trace-get option: ${token}`);
+  }
+
+  return limit === undefined ? {} : { limit };
+}
+
+export async function runTraceGetCommand(args: string[]): Promise<TraceGetCommandResult> {
+  const context = parseCommandContext(args);
+  const options = parseTraceGetOptions(context.positional);
+
+  return await callDaemonTool<TraceGetCommandResult>(
+    "browser.trace.get",
+    buildToolArguments(context, {
+      ...options
+    })
+  );
+}

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

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