@flrande/browserctl 0.1.0

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

@@ -0,0 +1,632 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { Socket } from "node:net";
+
+import { DAEMON_STARTUP_ARGUMENT, type DaemonStartupConfig } from "./commands/common";
+
+const DEFAULT_DAEMON_HOST = "127.0.0.1";
+const DEFAULT_DAEMON_PORT = 41337;
+const DEFAULT_DAEMON_STARTUP_TIMEOUT_MS = 10_000;
+const DEFAULT_DAEMON_REQUEST_TIMEOUT_MS = 5_000;
+const STARTUP_POLL_INTERVAL_MS = 200;
+
+type ErrorPayload = {
+  code: string;
+  message: string;
+};
+
+type ToolEnvelope<TData = Record<string, unknown>> = {
+  id?: string;
+  ok: boolean;
+  traceId: string;
+  sessionId: string;
+  profile?: string;
+  targetId?: string;
+  data?: TData;
+  error?: ErrorPayload;
+};
+
+type ToolRequest = {
+  id: string;
+  name: string;
+  traceId: string;
+  arguments: Record<string, unknown>;
+};
+
+type DaemonLifecycleStatus = {
+  running: boolean;
+  port: number;
+  pid?: number;
+};
+
+type DaemonRequestOptions = {
+  port?: number;
+  authToken?: string;
+  startup?: DaemonStartupConfig;
+};
+
+type DaemonRuntimeRecord = {
+  pid: number;
+  authToken?: string;
+};
+
+const startupLocks = new Map<number, Promise<void>>();
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toNumber(value: string | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function resolveDaemonPort(): number {
+  return toNumber(process.env.BROWSERCTL_DAEMON_PORT) ?? DEFAULT_DAEMON_PORT;
+}
+
+function resolveDaemonStartupTimeoutMs(): number {
+  return (
+    toNumber(process.env.BROWSERCTL_DAEMON_STARTUP_TIMEOUT_MS) ??
+    DEFAULT_DAEMON_STARTUP_TIMEOUT_MS
+  );
+}
+
+function resolveDaemonRequestTimeoutMs(): number {
+  return (
+    toNumber(process.env.BROWSERCTL_DAEMON_REQUEST_TIMEOUT_MS) ??
+    DEFAULT_DAEMON_REQUEST_TIMEOUT_MS
+  );
+}
+
+function normalizeAuthToken(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+  return trimmedValue.length === 0 ? undefined : trimmedValue;
+}
+
+function resolveDefaultAuthToken(port = resolveDaemonPort()): string | undefined {
+  return normalizeAuthToken(process.env.BROWSERCTL_AUTH_TOKEN) ?? readDaemonRuntimeRecord(port)?.authToken;
+}
+
+function withAuthToken(
+  args: Record<string, unknown>,
+  explicitAuthToken?: string
+): Record<string, unknown> {
+  const authToken =
+    normalizeAuthToken(explicitAuthToken) ??
+    normalizeAuthToken(args.authToken) ??
+    resolveDefaultAuthToken();
+
+  if (authToken === undefined) {
+    return args;
+  }
+
+  return {
+    ...args,
+    authToken
+  };
+}
+
+function isDaemonStartupConfig(value: unknown): value is DaemonStartupConfig {
+  if (!isObjectRecord(value)) {
+    return false;
+  }
+
+  const managedLocal = value.managedLocal;
+  if (!isObjectRecord(managedLocal)) {
+    return false;
+  }
+
+  if (managedLocal.browserName !== "chromium") {
+    return false;
+  }
+
+  if (managedLocal.channel !== undefined && typeof managedLocal.channel !== "string") {
+    return false;
+  }
+
+  return true;
+}
+
+function extractDaemonStartupConfig(args: Record<string, unknown>): {
+  requestArgs: Record<string, unknown>;
+  startup?: DaemonStartupConfig;
+} {
+  const rawStartup = args[DAEMON_STARTUP_ARGUMENT];
+  if (rawStartup === undefined) {
+    return {
+      requestArgs: args
+    };
+  }
+
+  const { [DAEMON_STARTUP_ARGUMENT]: _ignored, ...requestArgs } = args;
+  if (!isDaemonStartupConfig(rawStartup)) {
+    return {
+      requestArgs
+    };
+  }
+
+  return {
+    requestArgs,
+    startup: {
+      managedLocal: {
+        browserName: "chromium",
+        ...(rawStartup.managedLocal.channel !== undefined
+          ? { channel: rawStartup.managedLocal.channel }
+          : {})
+      }
+    }
+  };
+}
+
+function resolveRepoRoot(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  return resolve(dirname(currentFile), "../../..");
+}
+
+function resolveBrowserdEntry(): string {
+  return resolve(resolveRepoRoot(), "apps/browserd/src/main.ts");
+}
+
+function resolveRuntimeDir(): string {
+  return join(resolveRepoRoot(), ".browserctl-runtime");
+}
+
+function resolvePidFile(port: number): string {
+  return join(resolveRuntimeDir(), `daemon-${port}.pid`);
+}
+
+function ensureRuntimeDir(): void {
+  mkdirSync(resolveRuntimeDir(), { recursive: true });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}
+
+function getErrorCode(error: unknown): string | undefined {
+  if (!isObjectRecord(error)) {
+    return undefined;
+  }
+
+  const code = error.code;
+  return typeof code === "string" ? code : undefined;
+}
+
+function isConnectionError(error: unknown): boolean {
+  const code = getErrorCode(error);
+  return code === "ECONNREFUSED" || code === "ENOENT" || code === "ECONNRESET";
+}
+
+function parseResponseLine(stdoutLine: string, requestId: string): ToolEnvelope {
+  const parsed = JSON.parse(stdoutLine);
+  if (!isObjectRecord(parsed)) {
+    throw new Error("Daemon returned a non-object response.");
+  }
+
+  if (typeof parsed.ok !== "boolean") {
+    throw new Error("Daemon response is missing boolean ok.");
+  }
+
+  if (typeof parsed.id === "string" && parsed.id !== requestId) {
+    throw new Error(`Daemon response id mismatch. expected=${requestId} got=${parsed.id}`);
+  }
+
+  return parsed as ToolEnvelope;
+}
+
+function createToolRequest(name: string, args: Record<string, unknown>): ToolRequest {
+  return {
+    id: randomUUID(),
+    name,
+    traceId: `trace:browserctl:${randomUUID()}`,
+    arguments: args
+  };
+}
+
+async function requestDaemon(
+  request: ToolRequest,
+  port: number,
+  timeoutMs: number
+): Promise<ToolEnvelope> {
+  return await new Promise<ToolEnvelope>((resolvePromise, rejectPromise) => {
+    const socket = new Socket();
+    socket.setEncoding("utf8");
+
+    let settled = false;
+    let buffer = "";
+
+    const timer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      socket.destroy();
+      rejectPromise(
+        new Error(`Timed out waiting for daemon response after ${timeoutMs}ms (port ${port}).`)
+      );
+    }, timeoutMs);
+
+    function settleResolve(value: ToolEnvelope): void {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      clearTimeout(timer);
+      socket.end();
+      resolvePromise(value);
+    }
+
+    function settleReject(error: unknown): void {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      rejectPromise(error);
+    }
+
+    socket.on("error", settleReject);
+
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(request)}\n`);
+    });
+
+    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;
+        }
+
+        try {
+          settleResolve(parseResponseLine(line, request.id));
+        } catch (error) {
+          settleReject(error);
+        }
+
+        return;
+      }
+    });
+
+    socket.connect(port, DEFAULT_DAEMON_HOST);
+  });
+}
+
+function parseDaemonRuntimeRecord(raw: string): DaemonRuntimeRecord | undefined {
+  const trimmedRaw = raw.trim();
+  if (trimmedRaw.length === 0) {
+    return undefined;
+  }
+
+  const legacyPid = Number.parseInt(trimmedRaw, 10);
+  if (Number.isFinite(legacyPid) && String(legacyPid) === trimmedRaw) {
+    return {
+      pid: legacyPid
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(trimmedRaw);
+    if (!isObjectRecord(parsed)) {
+      return undefined;
+    }
+
+    const rawPid = parsed.pid;
+    if (typeof rawPid !== "number" || !Number.isFinite(rawPid) || rawPid <= 0) {
+      return undefined;
+    }
+
+    return {
+      pid: rawPid,
+      authToken: normalizeAuthToken(parsed.authToken)
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function persistDaemonRuntimeRecord(port: number, record: DaemonRuntimeRecord): void {
+  ensureRuntimeDir();
+  writeFileSync(resolvePidFile(port), JSON.stringify(record), { encoding: "utf8" });
+}
+
+function readDaemonRuntimeRecord(port: number): DaemonRuntimeRecord | undefined {
+  try {
+    const content = readFileSync(resolvePidFile(port), { encoding: "utf8" });
+    return parseDaemonRuntimeRecord(content);
+  } catch {
+    return undefined;
+  }
+}
+
+function readDaemonPid(port: number): number | undefined {
+  return readDaemonRuntimeRecord(port)?.pid;
+}
+
+function clearDaemonPid(port: number): void {
+  rmSync(resolvePidFile(port), { force: true });
+}
+
+function createDaemonSpawnEnv(
+  port: number,
+  authToken: string,
+  startup?: DaemonStartupConfig
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    BROWSERD_TRANSPORT: "tcp",
+    BROWSERD_PORT: String(port),
+    BROWSERD_AUTH_TOKEN: authToken
+  };
+
+  if (startup !== undefined) {
+    env.BROWSERD_MANAGED_LOCAL_ENABLED = "true";
+    env.BROWSERD_MANAGED_LOCAL_BROWSER = startup.managedLocal.browserName;
+    if (startup.managedLocal.channel === undefined) {
+      delete env.BROWSERD_MANAGED_LOCAL_CHANNEL;
+    } else {
+      env.BROWSERD_MANAGED_LOCAL_CHANNEL = startup.managedLocal.channel;
+    }
+  }
+
+  return env;
+}
+
+function spawnDaemon(port: number, authToken: string, startup?: DaemonStartupConfig): void {
+  const daemonEntry = resolveBrowserdEntry();
+  const child = spawn(process.execPath, ["--import", "tsx", daemonEntry], {
+    cwd: resolveRepoRoot(),
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: createDaemonSpawnEnv(port, authToken, startup)
+  });
+
+  if (child.pid === undefined) {
+    throw new Error("Failed to spawn daemon: missing pid.");
+  }
+
+  persistDaemonRuntimeRecord(port, {
+    pid: child.pid,
+    authToken
+  });
+  child.unref();
+}
+
+async function waitForDaemonReady(port: number, authToken?: string): Promise<void> {
+  const timeoutMs = resolveDaemonStartupTimeoutMs();
+  const requestTimeoutMs = resolveDaemonRequestTimeoutMs();
+  const start = Date.now();
+  let lastError: unknown;
+
+  while (Date.now() - start <= timeoutMs) {
+    try {
+      await requestDaemon(
+        createToolRequest(
+          "browser.status",
+          withAuthToken(
+            {
+              sessionId: "cli:daemon-ready-check"
+            },
+            authToken
+          )
+        ),
+        port,
+        requestTimeoutMs
+      );
+      return;
+    } catch (error) {
+      lastError = error;
+      await delay(STARTUP_POLL_INTERVAL_MS);
+    }
+  }
+
+  const message = lastError instanceof Error ? lastError.message : String(lastError);
+  throw new Error(`Daemon did not become ready on port ${port}: ${message}`);
+}
+
+async function ensureDaemonStarted(
+  port: number,
+  authToken?: string,
+  startup?: DaemonStartupConfig
+): Promise<void> {
+  const existingLock = startupLocks.get(port);
+  if (existingLock !== undefined) {
+    await existingLock;
+    return;
+  }
+
+  const lock = (async () => {
+    const startupAuthToken = normalizeAuthToken(authToken) ?? `daemon-token:${randomUUID()}`;
+    spawnDaemon(port, startupAuthToken, startup);
+    await waitForDaemonReady(port, startupAuthToken);
+  })();
+
+  startupLocks.set(port, lock);
+  try {
+    await lock;
+  } finally {
+    startupLocks.delete(port);
+  }
+}
+
+export async function getDaemonStatus(options: DaemonRequestOptions = {}): Promise<DaemonLifecycleStatus> {
+  const port = options.port ?? resolveDaemonPort();
+  const authToken = options.authToken ?? resolveDefaultAuthToken(port);
+  const requestTimeoutMs = resolveDaemonRequestTimeoutMs();
+  try {
+    await requestDaemon(
+      createToolRequest(
+        "browser.status",
+        withAuthToken(
+          {
+            sessionId: "cli:daemon-status"
+          },
+          authToken
+        )
+      ),
+      port,
+      requestTimeoutMs
+    );
+    return {
+      running: true,
+      port,
+      pid: readDaemonPid(port)
+    };
+  } catch (error) {
+    if (isConnectionError(error)) {
+      return {
+        running: false,
+        port,
+        pid: readDaemonPid(port)
+      };
+    }
+
+    throw error;
+  }
+}
+
+export async function ensureDaemonRunning(
+  options: DaemonRequestOptions = {}
+): Promise<DaemonLifecycleStatus> {
+  const port = options.port ?? resolveDaemonPort();
+  const authToken = options.authToken ?? resolveDefaultAuthToken(port);
+  const status = await getDaemonStatus({
+    port,
+    authToken
+  });
+  if (status.running) {
+    return status;
+  }
+
+  await ensureDaemonStarted(port, authToken, options.startup);
+  return {
+    running: true,
+    port,
+    pid: readDaemonPid(port)
+  };
+}
+
+export async function stopDaemon(
+  port = resolveDaemonPort()
+): Promise<{ stopped: boolean; port: number; pid?: number }> {
+  const runtimeRecord = readDaemonRuntimeRecord(port);
+  if (runtimeRecord === undefined) {
+    return {
+      stopped: false,
+      port
+    };
+  }
+
+  const pid = runtimeRecord.pid;
+  const authToken = runtimeRecord.authToken;
+  const requestTimeoutMs = resolveDaemonRequestTimeoutMs();
+
+  try {
+    const probe = await requestDaemon(
+      createToolRequest(
+        "browser.status",
+        withAuthToken(
+          {
+            sessionId: "cli:daemon-stop-check"
+          },
+          authToken
+        )
+      ),
+      port,
+      requestTimeoutMs
+    );
+    if (!probe.ok) {
+      clearDaemonPid(port);
+      return {
+        stopped: false,
+        port,
+        pid
+      };
+    }
+  } catch {
+    clearDaemonPid(port);
+    return {
+      stopped: false,
+      port,
+      pid
+    };
+  }
+
+  try {
+    process.kill(pid);
+    clearDaemonPid(port);
+    return {
+      stopped: true,
+      port,
+      pid
+    };
+  } catch {
+    clearDaemonPid(port);
+    return {
+      stopped: false,
+      port,
+      pid
+    };
+  }
+}
+
+export async function callDaemonTool<TData = Record<string, unknown>>(
+  name: string,
+  args: Record<string, unknown>
+): Promise<TData> {
+  const port = resolveDaemonPort();
+  const extracted = extractDaemonStartupConfig(args);
+  const authToken = normalizeAuthToken(extracted.requestArgs.authToken) ?? resolveDefaultAuthToken(port);
+  const requestArgs = withAuthToken(extracted.requestArgs, authToken);
+  const requestTimeoutMs = resolveDaemonRequestTimeoutMs();
+  const request = createToolRequest(name, requestArgs);
+
+  let response: ToolEnvelope;
+  try {
+    response = await requestDaemon(request, port, requestTimeoutMs);
+  } catch (error) {
+    if (!isConnectionError(error)) {
+      throw error;
+    }
+
+    await ensureDaemonStarted(port, authToken, extracted.startup);
+    response = await requestDaemon(request, port, requestTimeoutMs);
+  }
+
+  if (!response.ok) {
+    const code = response.error?.code ?? "E_INTERNAL";
+    const message = response.error?.message ?? "Unknown daemon error.";
+    throw new Error(`${code}: ${message}`);
+  }
+
+  if (!isObjectRecord(response.data)) {
+    return {} as TData;
+  }
+
+  return response.data as TData;
+}

package/apps/browserctl/src/e2e.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { stopDaemon } from "./daemon-client";
+import { EXIT_CODES, runCli } from "./main";
+
+const TEST_DAEMON_PORT = "42491";
+const TEST_SESSION_ID = "session:e2e";
+
+function createIoCapture() {
+  const state = {
+    stdout: "",
+    stderr: ""
+  };
+
+  return {
+    state,
+    io: {
+      stdout: {
+        write(content: string) {
+          state.stdout += content;
+        }
+      },
+      stderr: {
+        write(content: string) {
+          state.stderr += content;
+        }
+      }
+    }
+  };
+}
+
+function parseJsonLine(state: { stdout: string }): Record<string, unknown> {
+  return JSON.parse(state.stdout.trim()) as Record<string, unknown>;
+}
+
+beforeEach(async () => {
+  process.env.BROWSERCTL_DAEMON_PORT = TEST_DAEMON_PORT;
+  process.env.BROWSERD_MANAGED_LOCAL_ENABLED = "false";
+  process.env.BROWSERD_DEFAULT_DRIVER = "managed";
+  await stopDaemon(Number.parseInt(TEST_DAEMON_PORT, 10));
+});
+
+afterEach(async () => {
+  await stopDaemon(Number.parseInt(TEST_DAEMON_PORT, 10));
+  delete process.env.BROWSERCTL_DAEMON_PORT;
+  delete process.env.BROWSERD_MANAGED_LOCAL_ENABLED;
+  delete process.env.BROWSERD_DEFAULT_DRIVER;
+});
+
+describe("browserctl e2e", () => {
+  it("reuses daemon state across multiple commands in the same session", async () => {
+    const startCapture = createIoCapture();
+    const startExitCode = await runCli(["daemon-start", "--json"], startCapture.io);
+
+    expect(startExitCode).toBe(EXIT_CODES.OK);
+    const startPayload = parseJsonLine(startCapture.state);
+    expect(startPayload.ok).toBe(true);
+    const startData = startPayload.data as Record<string, unknown>;
+    expect(startData.running).toBe(true);
+    expect(startData.port).toBe(Number.parseInt(TEST_DAEMON_PORT, 10));
+
+    const openCapture = createIoCapture();
+    const openExitCode = await runCli(
+      ["tab-open", "--session", TEST_SESSION_ID, "https://example.com", "--json"],
+      openCapture.io
+    );
+
+    expect(openExitCode).toBe(EXIT_CODES.OK);
+    const openPayload = parseJsonLine(openCapture.state);
+    expect(openPayload.ok).toBe(true);
+    const openData = openPayload.data as Record<string, unknown>;
+    expect(openData.driver).toBe("managed");
+    const targetId = openData.targetId;
+    expect(typeof targetId).toBe("string");
+
+    const listCapture = createIoCapture();
+    const listExitCode = await runCli(["tabs", "--session", TEST_SESSION_ID, "--json"], listCapture.io);
+
+    expect(listExitCode).toBe(EXIT_CODES.OK);
+    const listPayload = parseJsonLine(listCapture.state);
+    expect(listPayload.ok).toBe(true);
+    const listData = listPayload.data as { tabs: string[] };
+    expect(listData.tabs).toContain(targetId);
+
+    const consoleCapture = createIoCapture();
+    const consoleExitCode = await runCli(
+      ["console-list", "--session", TEST_SESSION_ID, String(targetId), "--json"],
+      consoleCapture.io
+    );
+    expect(consoleExitCode).toBe(EXIT_CODES.OK);
+    const consolePayload = parseJsonLine(consoleCapture.state);
+    expect(consolePayload.ok).toBe(true);
+    expect(consolePayload.data).toMatchObject({
+      driver: "managed",
+      targetId,
+      entries: []
+    });
+  }, 20_000);
+});