@flrande/browserctl 0.4.0 → 0.5.0-dev.19.1

package/apps/browserctl/src/commands/har-export.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callDaemonToolMock } = vi.hoisted(() => ({
+  callDaemonToolMock: vi.fn()
+}));
+
+vi.mock("../daemon-client", () => ({
+  callDaemonTool: callDaemonToolMock
+}));
+
+import { runHarExportCommand } from "./har-export";
+
+afterEach(() => {
+  callDaemonToolMock.mockReset();
+});
+
+describe("runHarExportCommand", () => {
+  it("forwards export options", async () => {
+    callDaemonToolMock.mockResolvedValue({ ok: true });
+
+    await runHarExportCommand([
+      "target:1",
+      "--include-bodies",
+      "--url-contains",
+      "/api/",
+      "--method",
+      "get",
+      "--status",
+      "200",
+      "--since",
+      "2026-01-01T00:00:00.000Z",
+      "--limit",
+      "30"
+    ]);
+
+    expect(callDaemonToolMock).toHaveBeenCalledTimes(1);
+    expect(callDaemonToolMock).toHaveBeenCalledWith("browser.network.harExport", {
+      sessionId: "cli:local",
+      targetId: "target:1",
+      includeBodies: true,
+      urlContains: "/api/",
+      method: "GET",
+      status: 200,
+      since: "2026-01-01T00:00:00.000Z",
+      limit: 30
+    });
+  });
+
+  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(runHarExportCommand(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", "201ok"],
+      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(runHarExportCommand(args)).rejects.toThrow(message);
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+
+  it("throws on unknown option token", async () => {
+    await expect(runHarExportCommand(["target:1", "--unknown"]))
+      .rejects.toThrow("Unknown har-export option: --unknown");
+
+    expect(callDaemonToolMock).not.toHaveBeenCalled();
+  });
+});

package/apps/browserctl/src/commands/har-export.ts

@@ -0,0 +1,120 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type HarExportCommandResult = 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 parseHarExportOptions(tokens: string[]): {
+  includeBodies?: boolean;
+  urlContains?: string;
+  method?: string;
+  status?: number;
+  since?: string;
+  limit?: number;
+} {
+  let includeBodies = false;
+  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 === "--include-bodies") {
+      includeBodies = true;
+      continue;
+    }
+
+    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 har-export option: ${token}`);
+  }
+
+  return {
+    ...(includeBodies ? { includeBodies: true } : {}),
+    ...(urlContains !== undefined ? { urlContains } : {}),
+    ...(method !== undefined ? { method } : {}),
+    ...(status !== undefined ? { status } : {}),
+    ...(since !== undefined ? { since } : {}),
+    ...(limit !== undefined ? { limit } : {})
+  };
+}
+
+export async function runHarExportCommand(args: string[]): Promise<HarExportCommandResult> {
+  const context = parseCommandContext(args);
+  const targetId = requirePositionalArg(context, 0, "targetId");
+  const options = parseHarExportOptions(context.positional.slice(1));
+
+  return await callDaemonTool<HarExportCommandResult>(
+    "browser.network.harExport",
+    buildToolArguments(context, {
+      targetId,
+      ...options
+    })
+  );
+}

package/apps/browserctl/src/commands/memory-delete.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type MemoryDeleteCommandResult = Record<string, unknown>;
+
+export async function runMemoryDeleteCommand(args: string[]): Promise<MemoryDeleteCommandResult> {
+  const context = parseCommandContext(args);
+  const id = requirePositionalArg(context, 0, "id");
+
+  if (context.positional.length > 1) {
+    throw new Error(`Unknown memory-delete option: ${context.positional[1]}`);
+  }
+
+  return await callDaemonTool<MemoryDeleteCommandResult>(
+    "browser.memory.delete",
+    buildToolArguments(context, {
+      id
+    })
+  );
+}

package/apps/browserctl/src/commands/memory-inspect.ts

@@ -0,0 +1,20 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type MemoryInspectCommandResult = Record<string, unknown>;
+
+export async function runMemoryInspectCommand(args: string[]): Promise<MemoryInspectCommandResult> {
+  const context = parseCommandContext(args);
+  const id = requirePositionalArg(context, 0, "id");
+
+  if (context.positional.length > 1) {
+    throw new Error(`Unknown memory-inspect option: ${context.positional[1]}`);
+  }
+
+  return await callDaemonTool<MemoryInspectCommandResult>(
+    "browser.memory.inspect",
+    buildToolArguments(context, {
+      id
+    })
+  );
+}

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

@@ -0,0 +1,90 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type MemoryListCommandResult = Record<string, unknown>;
+
+type MemoryListOptions = {
+  domain?: string;
+  profileId?: string;
+  intentKey?: string;
+};
+
+function requireOptionValue(tokens: string[], index: number, optionName: string): string {
+  const value = tokens[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+
+  return value;
+}
+
+function parseListOptions(tokens: string[]): MemoryListOptions {
+  let domain: string | undefined;
+  let profileId: string | undefined;
+  let intentKey: string | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--domain") {
+      const value = requireOptionValue(tokens, index, "--domain");
+
+      const trimmedValue = value.trim();
+      if (trimmedValue.length === 0) {
+        throw new Error("--domain must be a non-empty string.");
+      }
+
+      domain = trimmedValue;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--profile-id") {
+      const value = requireOptionValue(tokens, index, "--profile-id");
+
+      const trimmedValue = value.trim();
+      if (trimmedValue.length === 0) {
+        throw new Error("--profile-id must be a non-empty string.");
+      }
+
+      profileId = trimmedValue;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--intent-key") {
+      const value = requireOptionValue(tokens, index, "--intent-key");
+
+      const trimmedValue = value.trim();
+      if (trimmedValue.length === 0) {
+        throw new Error("--intent-key must be a non-empty string.");
+      }
+
+      intentKey = trimmedValue;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown memory-list option: ${token}`);
+  }
+
+  return {
+    ...(domain !== undefined ? { domain } : {}),
+    ...(profileId !== undefined ? { profileId } : {}),
+    ...(intentKey !== undefined ? { intentKey } : {})
+  };
+}
+
+export async function runMemoryListCommand(args: string[]): Promise<MemoryListCommandResult> {
+  const context = parseCommandContext(args);
+  const options = parseListOptions(context.positional);
+  const profileId = options.profileId ?? context.profile;
+
+  return await callDaemonTool<MemoryListCommandResult>(
+    "browser.memory.list",
+    buildToolArguments(context, {
+      ...(options.domain !== undefined ? { domain: options.domain } : {}),
+      ...(profileId !== undefined ? { profileId } : {}),
+      ...(options.intentKey !== undefined ? { intentKey: options.intentKey } : {})
+    })
+  );
+}

package/apps/browserctl/src/commands/memory-mode-set.ts

@@ -0,0 +1,29 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type MemoryModeSetCommandResult = Record<string, unknown>;
+
+function parseMemoryMode(value: string): "off" | "ask" | "auto" {
+  const normalizedValue = value.trim().toLowerCase();
+  if (normalizedValue === "off" || normalizedValue === "ask" || normalizedValue === "auto") {
+    return normalizedValue;
+  }
+
+  throw new Error("mode must be one of: off, ask, auto.");
+}
+
+export async function runMemoryModeSetCommand(args: string[]): Promise<MemoryModeSetCommandResult> {
+  const context = parseCommandContext(args);
+  const mode = parseMemoryMode(requirePositionalArg(context, 0, "mode"));
+
+  if (context.positional.length > 1) {
+    throw new Error(`Unknown memory-mode-set option: ${context.positional[1]}`);
+  }
+
+  return await callDaemonTool<MemoryModeSetCommandResult>(
+    "browser.memory.mode.set",
+    buildToolArguments(context, {
+      mode
+    })
+  );
+}

package/apps/browserctl/src/commands/memory-purge.ts

@@ -0,0 +1,16 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type MemoryPurgeCommandResult = Record<string, unknown>;
+
+export async function runMemoryPurgeCommand(args: string[]): Promise<MemoryPurgeCommandResult> {
+  const context = parseCommandContext(args);
+  if (context.positional.length > 0) {
+    throw new Error(`Unknown memory-purge option: ${context.positional[0]}`);
+  }
+
+  return await callDaemonTool<MemoryPurgeCommandResult>(
+    "browser.memory.purge",
+    buildToolArguments(context)
+  );
+}

package/apps/browserctl/src/commands/memory-resolve.ts

@@ -0,0 +1,56 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type MemoryResolveCommandResult = Record<string, unknown>;
+
+function requireOptionValue(tokens: string[], index: number, optionName: string): string {
+  const value = tokens[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+
+  return value;
+}
+
+function parseResolveOptions(tokens: string[]): {
+  profileId?: string;
+} {
+  let profileId: string | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--profile-id") {
+      const value = requireOptionValue(tokens, index, "--profile-id");
+
+      const trimmedValue = value.trim();
+      if (trimmedValue.length === 0) {
+        throw new Error("--profile-id must be a non-empty string.");
+      }
+
+      profileId = trimmedValue;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown memory-resolve option: ${token}`);
+  }
+
+  return profileId === undefined ? {} : { profileId };
+}
+
+export async function runMemoryResolveCommand(args: string[]): Promise<MemoryResolveCommandResult> {
+  const context = parseCommandContext(args);
+  const domain = requirePositionalArg(context, 0, "domain");
+  const intentKey = requirePositionalArg(context, 1, "intentKey");
+  const options = parseResolveOptions(context.positional.slice(2));
+  const profileId = options.profileId ?? context.profile ?? "default";
+
+  return await callDaemonTool<MemoryResolveCommandResult>(
+    "browser.memory.resolve",
+    buildToolArguments(context, {
+      domain,
+      profileId,
+      intentKey
+    })
+  );
+}

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

@@ -0,0 +1,16 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext } from "./common";
+
+export type MemoryStatusCommandResult = Record<string, unknown>;
+
+export async function runMemoryStatusCommand(args: string[]): Promise<MemoryStatusCommandResult> {
+  const context = parseCommandContext(args);
+  if (context.positional.length > 0) {
+    throw new Error(`Unknown memory-status option: ${context.positional[0]}`);
+  }
+
+  return await callDaemonTool<MemoryStatusCommandResult>(
+    "browser.memory.status",
+    buildToolArguments(context)
+  );
+}

package/apps/browserctl/src/commands/memory-ttl-set.ts

@@ -0,0 +1,28 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type MemoryTtlSetCommandResult = Record<string, unknown>;
+
+function parseNonNegativeIntegerString(value: string): number {
+  if (!/^(0|[1-9]\d*)$/.test(value)) {
+    throw new Error("ttlDays must be a non-negative integer string.");
+  }
+
+  return Number.parseInt(value, 10);
+}
+
+export async function runMemoryTtlSetCommand(args: string[]): Promise<MemoryTtlSetCommandResult> {
+  const context = parseCommandContext(args);
+  const ttlDays = parseNonNegativeIntegerString(requirePositionalArg(context, 0, "ttlDays"));
+
+  if (context.positional.length > 1) {
+    throw new Error(`Unknown memory-ttl-set option: ${context.positional[1]}`);
+  }
+
+  return await callDaemonTool<MemoryTtlSetCommandResult>(
+    "browser.memory.ttl.set",
+    buildToolArguments(context, {
+      ttlDays
+    })
+  );
+}

package/apps/browserctl/src/commands/memory-upsert.ts

@@ -0,0 +1,142 @@
+import { callDaemonTool } from "../daemon-client";
+import { buildToolArguments, parseCommandContext, requirePositionalArg } from "./common";
+
+export type MemoryUpsertCommandResult = Record<string, unknown>;
+
+type MemoryUpsertOptions = {
+  profileId?: string;
+  signals: unknown[];
+  confidence?: number;
+  confirmed?: boolean;
+};
+
+function requireOptionValue(tokens: string[], index: number, optionName: string): string {
+  const value = tokens[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`Missing value for ${optionName}.`);
+  }
+
+  return value;
+}
+
+function parseNumber(value: string, optionName: string): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${optionName} must be a valid number.`);
+  }
+
+  return parsed;
+}
+
+function parseBoolean(value: string, optionName: string): boolean {
+  const normalizedValue = value.trim().toLowerCase();
+  if (normalizedValue === "true") {
+    return true;
+  }
+
+  if (normalizedValue === "false") {
+    return false;
+  }
+
+  throw new Error(`${optionName} must be true or false when provided with a value.`);
+}
+
+function parseSignalsJson(value: string): unknown[] {
+  let parsedValue: unknown;
+  try {
+    parsedValue = JSON.parse(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON for --signals-json: ${message}`);
+  }
+
+  if (!Array.isArray(parsedValue)) {
+    throw new Error("--signals-json must decode to a JSON array.");
+  }
+
+  return parsedValue;
+}
+
+function parseUpsertOptions(tokens: string[]): MemoryUpsertOptions {
+  let profileId: string | undefined;
+  let signals: unknown[] | undefined;
+  let confidence: number | undefined;
+  let confirmed: boolean | undefined;
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--profile-id") {
+      const value = requireOptionValue(tokens, index, "--profile-id");
+
+      const trimmedValue = value.trim();
+      if (trimmedValue.length === 0) {
+        throw new Error("--profile-id must be a non-empty string.");
+      }
+
+      profileId = trimmedValue;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--signals-json") {
+      const value = requireOptionValue(tokens, index, "--signals-json");
+
+      signals = parseSignalsJson(value);
+      index += 1;
+      continue;
+    }
+
+    if (token === "--confidence") {
+      const value = requireOptionValue(tokens, index, "--confidence");
+
+      confidence = parseNumber(value, "--confidence");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--confirmed") {
+      const maybeValue = tokens[index + 1];
+      if (maybeValue === undefined || maybeValue.startsWith("--")) {
+        confirmed = true;
+        continue;
+      }
+
+      confirmed = parseBoolean(maybeValue, "--confirmed");
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown memory-upsert option: ${token}`);
+  }
+
+  if (signals === undefined) {
+    throw new Error("Missing value for --signals-json.");
+  }
+
+  return {
+    signals,
+    ...(profileId !== undefined ? { profileId } : {}),
+    ...(confidence !== undefined ? { confidence } : {}),
+    ...(confirmed !== undefined ? { confirmed } : {})
+  };
+}
+
+export async function runMemoryUpsertCommand(args: string[]): Promise<MemoryUpsertCommandResult> {
+  const context = parseCommandContext(args);
+  const domain = requirePositionalArg(context, 0, "domain");
+  const intentKey = requirePositionalArg(context, 1, "intentKey");
+  const options = parseUpsertOptions(context.positional.slice(2));
+  const profileId = options.profileId ?? context.profile ?? "default";
+
+  return await callDaemonTool<MemoryUpsertCommandResult>(
+    "browser.memory.upsert",
+    buildToolArguments(context, {
+      domain,
+      profileId,
+      intentKey,
+      signals: options.signals,
+      ...(options.confidence !== undefined ? { confidence: options.confidence } : {}),
+      ...(options.confirmed !== undefined ? { confirmed: options.confirmed } : {})
+    })
+  );
+}