libretto 0.6.9 → 0.6.11

package/src/cli/core/daemon/ipc.ts

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import { createServer, connect as netConnect, type Server } from "node:net";
+import { unlink } from "node:fs/promises";
+import { REPO_ROOT } from "../context.js";
+
+export type DaemonExecOutput = { stdout: string; stderr: string };
+
+type ErrorWithOutput = Error & { output?: DaemonExecOutput };
+
+// ---------------------------------------------------------------------------
+// Request types — one shape per daemon command
+// ---------------------------------------------------------------------------
+
+export type DaemonRequest =
+  | { id: string; command: "ping" }
+  | { id: string; command: "pages" }
+  | { id: string; command: "snapshot"; pageId?: string }
+  | {
+      id: string;
+      command: "exec";
+      code: string;
+      pageId?: string;
+      visualize?: boolean;
+    }
+  | { id: string; command: "readonly-exec"; code: string; pageId?: string };
+
+// ---------------------------------------------------------------------------
+// Response types — success or error, keyed by the originating request id
+// ---------------------------------------------------------------------------
+
+export type DaemonResponse =
+  | { id: string; type: "result"; data: unknown }
+  | {
+      id: string;
+      type: "error";
+      message: string;
+      output?: DaemonExecOutput;
+    };
+
+export class DaemonClientError extends Error {
+  constructor(
+    message: string,
+    readonly output?: DaemonExecOutput,
+  ) {
+    super(message);
+    this.name = "DaemonClientError";
+  }
+}
+
+export type DaemonCommandResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; message: string; output?: DaemonExecOutput };
+
+// ---------------------------------------------------------------------------
+// Socket path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic Unix domain socket path for a given session.
+ *
+ * The path lives in `/tmp` to stay well under the macOS 104-byte Unix socket
+ * path limit. The hash combines `REPO_ROOT` and the session name so different
+ * repos (or sessions within the same repo) never collide.
+ */
+export function getDaemonSocketPath(session: string): string {
+  const hash = createHash("sha256")
+    .update(`${REPO_ROOT}:${session}`)
+    .digest("hex")
+    .slice(0, 12);
+  return `/tmp/libretto-${process.getuid!()}-${hash}.sock`;
+}
+
+// ---------------------------------------------------------------------------
+// DaemonServer — Unix domain socket server, NDJSON, one request per connection
+// ---------------------------------------------------------------------------
+
+export type RequestHandler = (request: DaemonRequest) => Promise<unknown>;
+
+export class DaemonServer {
+  private server: Server | null = null;
+
+  constructor(
+    private readonly socketPath: string,
+    private readonly handler: RequestHandler,
+  ) {}
+
+  async listen(): Promise<void> {
+    // Remove stale socket file if present.
+    try {
+      await unlink(this.socketPath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+
+    const server = createServer((socket) => {
+      let buffer = "";
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString();
+        const newlineIndex = buffer.indexOf("\n");
+        if (newlineIndex === -1) return;
+
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+
+        void (async () => {
+          let response: DaemonResponse;
+          try {
+            const request = JSON.parse(line) as DaemonRequest;
+            const data = await this.handler(request);
+            response = { id: request.id, type: "result", data };
+          } catch (err) {
+            const id = (() => {
+              try {
+                return (JSON.parse(line) as { id?: string }).id ?? "unknown";
+              } catch {
+                return "unknown";
+              }
+            })();
+            response = {
+              id,
+              type: "error",
+              message: err instanceof Error ? err.message : String(err),
+              output:
+                err instanceof Error
+                  ? (err as ErrorWithOutput).output
+                  : undefined,
+            };
+          }
+          socket.end(JSON.stringify(response) + "\n");
+        })();
+      });
+    });
+
+    this.server = server;
+
+    await new Promise<void>((resolve, reject) => {
+      server.on("error", reject);
+      server.listen(this.socketPath, () => resolve());
+    });
+  }
+
+  async close(): Promise<void> {
+    const server = this.server;
+    if (!server) return;
+    this.server = null;
+
+    await new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+
+    try {
+      await unlink(this.socketPath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Response data types — maps command name to the shape returned on success
+// ---------------------------------------------------------------------------
+
+export type DaemonResultMap = {
+  ping: { protocolVersion: number };
+  pages: Array<{ id: string; url: string; active: boolean }>;
+  exec: { result: unknown; output?: DaemonExecOutput };
+  "readonly-exec": {
+    result: unknown;
+    output?: DaemonExecOutput;
+  };
+  snapshot: {
+    pngPath: string;
+    htmlPath: string;
+    snapshotRunId: string;
+    pageUrl: string;
+    title: string;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// DaemonClient — connects to UDS, sends NDJSON request, reads response
+// ---------------------------------------------------------------------------
+
+export class DaemonClient {
+  constructor(private readonly socketPath: string) {}
+
+  private async send(request: DaemonRequest): Promise<DaemonResponse> {
+    return new Promise<DaemonResponse>((resolve, reject) => {
+      const socket = netConnect(this.socketPath);
+      let buffer = "";
+
+      socket.on("connect", () => {
+        socket.write(JSON.stringify(request) + "\n");
+      });
+
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString();
+      });
+
+      socket.on("end", () => {
+        try {
+          const response = JSON.parse(buffer.trim()) as DaemonResponse;
+          resolve(response);
+        } catch (err) {
+          reject(
+            new Error(
+              `Failed to parse daemon response: ${err instanceof Error ? err.message : String(err)}`,
+            ),
+          );
+        }
+      });
+
+      socket.on("error", (err) => {
+        reject(err);
+      });
+    });
+  }
+
+  private generateId(): string {
+    return Math.random().toString(36).slice(2, 10);
+  }
+
+  private async sendOrThrow<C extends DaemonRequest["command"]>(
+    request: DaemonRequest & { command: C },
+  ): Promise<DaemonResultMap[C]> {
+    const response = await this.send(request);
+    if (response.type === "error") {
+      throw new DaemonClientError(response.message, response.output);
+    }
+    return response.data as DaemonResultMap[C];
+  }
+
+  private async sendResult<C extends DaemonRequest["command"]>(
+    request: DaemonRequest & { command: C },
+  ): Promise<DaemonCommandResult<DaemonResultMap[C]>> {
+    const response = await this.send(request);
+    if (response.type === "error") {
+      return {
+        ok: false,
+        message: response.message,
+        output: response.output,
+      };
+    }
+    return { ok: true, data: response.data as DaemonResultMap[C] };
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.sendOrThrow({ id: this.generateId(), command: "ping" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async pages(): Promise<DaemonResultMap["pages"]> {
+    return this.sendOrThrow({ id: this.generateId(), command: "pages" });
+  }
+
+  async exec(args: {
+    code: string;
+    pageId?: string;
+    visualize?: boolean;
+  }): Promise<DaemonCommandResult<DaemonResultMap["exec"]>> {
+    return this.sendResult({
+      id: this.generateId(),
+      command: "exec",
+      ...args,
+    });
+  }
+
+  async readonlyExec(args: {
+    code: string;
+    pageId?: string;
+  }): Promise<DaemonCommandResult<DaemonResultMap["readonly-exec"]>> {
+    return this.sendResult({
+      id: this.generateId(),
+      command: "readonly-exec",
+      ...args,
+    });
+  }
+
+  async snapshot(
+    args: {
+      pageId?: string;
+    } = {},
+  ): Promise<DaemonResultMap["snapshot"]> {
+    return this.sendOrThrow({
+      id: this.generateId(),
+      command: "snapshot",
+      ...args,
+    });
+  }
+}

package/src/cli/core/daemon/pages.ts

@@ -0,0 +1,21 @@
+import type { Page } from "playwright";
+
+export function handlePages(
+  pageById: Map<string, Page>,
+  activePage: Page,
+): Array<{ id: string; url: string; active: boolean }> {
+  const results: Array<{ id: string; url: string; active: boolean }> = [];
+  // If the original active page has been closed (no longer in the map),
+  // fall back to the last tracked page.
+  const isActiveTracked = [...pageById.values()].includes(activePage);
+  const effectiveActive = isActiveTracked
+    ? activePage
+    : [...pageById.values()].at(-1);
+  for (const [id, page] of pageById) {
+    const url = page.url();
+    if (url.startsWith("devtools://") || url.startsWith("chrome-error://"))
+      continue;
+    results.push({ id, url, active: page === effectiveActive });
+  }
+  return results;
+}

package/src/cli/core/daemon/snapshot.ts

@@ -0,0 +1,114 @@
+import type { Page } from "playwright";
+import { mkdirSync, writeFileSync } from "node:fs";
+import type { LoggerApi } from "../../../shared/logger/index.js";
+import { getSessionSnapshotRunDir } from "../context.js";
+import {
+  resolveSnapshotViewport,
+  readSnapshotViewportMetrics,
+  shouldForceSnapshotViewport,
+  isZeroWidthScreenshotError,
+  forceSnapshotViewport,
+} from "../../commands/snapshot.js";
+
+const RENDER_SETTLE_TIMEOUT_MS = 10_000;
+
+export async function handleSnapshot(
+  targetPage: Page,
+  session: string,
+  logger: LoggerApi,
+  pageId?: string,
+): Promise<{
+  pngPath: string;
+  htmlPath: string;
+  snapshotRunId: string;
+  pageUrl: string;
+  title: string;
+}> {
+  const snapshotRunId = `snapshot-${Date.now()}`;
+  const snapshotRunDir = getSessionSnapshotRunDir(session, snapshotRunId);
+  mkdirSync(snapshotRunDir, { recursive: true });
+
+  // Capture title and URL early, before viewport normalization
+  // (matches captureScreenshot ordering).
+  let title: string | null = null;
+  try {
+    title = await targetPage.title();
+  } catch (error) {
+    logger.warn("screenshot-title-read-failed", { session, pageId, error });
+  }
+
+  let pageUrl: string | null = null;
+  try {
+    pageUrl = targetPage.url();
+  } catch (error) {
+    logger.warn("screenshot-url-read-failed", { session, pageId, error });
+  }
+
+  const pngPath = `${snapshotRunDir}/page.png`;
+  const htmlPath = `${snapshotRunDir}/page.html`;
+
+  // Wait for network to settle before capturing.
+  await Promise.race([
+    targetPage.waitForLoadState("networkidle").catch(() => {}),
+    new Promise((resolve) => setTimeout(resolve, RENDER_SETTLE_TIMEOUT_MS)),
+  ]);
+
+  // Viewport normalization — uses shared helpers from snapshot.ts.
+  const restoreViewport = resolveSnapshotViewport(session, logger);
+  const viewportMetrics = await readSnapshotViewportMetrics(targetPage);
+  logger.info("screenshot-viewport-metrics", {
+    session,
+    pageId,
+    restoreViewport,
+    ...viewportMetrics,
+  });
+  await forceSnapshotViewport(
+    targetPage,
+    restoreViewport,
+    logger,
+    session,
+    pageId,
+    shouldForceSnapshotViewport(viewportMetrics)
+      ? "preflight-invalid-viewport"
+      : "preflight-normalize-viewport",
+  );
+
+  // Screenshot with zero-width retry.
+  try {
+    await targetPage.screenshot({ path: pngPath });
+  } catch (error) {
+    if (!isZeroWidthScreenshotError(error)) {
+      throw error;
+    }
+    await forceSnapshotViewport(
+      targetPage,
+      restoreViewport,
+      logger,
+      session,
+      pageId,
+      "retry-after-zero-width-screenshot-error",
+    );
+    await targetPage.screenshot({ path: pngPath });
+  }
+
+  // Capture HTML content.
+  const htmlContent = await targetPage.content();
+  writeFileSync(htmlPath, htmlContent);
+
+  logger.info("screenshot-success", {
+    session,
+    pageUrl,
+    title,
+    pngPath,
+    htmlPath,
+    snapshotRunId,
+  });
+
+  return {
+    pngPath,
+    htmlPath,
+    snapshotRunId,
+    pageUrl: pageUrl ?? "",
+    title: title ?? "",
+  };
+}

package/src/cli/core/daemon/spawn.ts

@@ -0,0 +1,171 @@
+/**
+ * Spawn and wait for a browser daemon process.
+ *
+ * Shared by `runOpen`, `runConnect`, and `runOpenWithProvider` in
+ * `browser.ts`. Encapsulates the child-process lifecycle and IPC
+ * readiness polling so callers only need to provide config and
+ * handle session-state persistence.
+ */
+
+import { openSync, closeSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import type { LoggerApi } from "../../../shared/logger/index.js";
+import { getDaemonSocketPath } from "./ipc.js";
+import { DaemonClient } from "./ipc.js";
+import type { DaemonConfig } from "./config.js";
+
+// ── Public types ─────────────────────────────────────────────────────
+
+export type SpawnSessionDaemonOptions = {
+  /** Daemon config — serialized as JSON and passed to the child process. */
+  config: DaemonConfig;
+  session: string;
+  logger: LoggerApi;
+  /** Path for the child's stderr log file. */
+  logPath: string;
+  /** How long to wait for the daemon's IPC server (default: 10 000 ms). */
+  ipcTimeoutMs?: number;
+  /**
+   * Called before throwing when the daemon fails to start (spawn error,
+   * early exit, or IPC timeout). Use for cleanup — e.g. closing a cloud
+   * provider session. Return value is ignored.
+   */
+  onFailure?: () => Promise<unknown>;
+};
+
+export type SpawnSessionDaemonResult = {
+  /** PID of the detached daemon child process. */
+  pid: number;
+  /** Unix domain socket path for daemon IPC. */
+  socketPath: string;
+  /** Ready-to-use IPC client (already confirmed reachable via ping). */
+  client: DaemonClient;
+};
+
+// ── Implementation ───────────────────────────────────────────────────
+
+const DEFAULT_IPC_TIMEOUT_MS = 10_000;
+const IPC_POLL_INTERVAL_MS = 250;
+
+/**
+ * Spawn a daemon child process with the given config and wait for its
+ * IPC server to become reachable.
+ *
+ * The daemon entry point is resolved relative to this module so the
+ * caller doesn't need to know where the daemon script lives.
+ */
+export async function spawnSessionDaemon(
+  options: SpawnSessionDaemonOptions,
+): Promise<SpawnSessionDaemonResult> {
+  const {
+    config,
+    session,
+    logger,
+    logPath,
+    ipcTimeoutMs = DEFAULT_IPC_TIMEOUT_MS,
+    onFailure,
+  } = options;
+
+  // Resolve paths for the daemon entry point and tsx loader.
+  const daemonEntryPath = fileURLToPath(
+    new URL("./daemon.js", import.meta.url),
+  );
+  const require = createRequire(import.meta.url);
+  const tsxImportPath = pathToFileURL(require.resolve("tsx/esm")).href;
+
+  // Spawn detached child process with stderr going to the log file.
+  const childStderrFd = openSync(logPath, "a");
+  const child = spawn(
+    process.execPath,
+    ["--import", tsxImportPath, daemonEntryPath, JSON.stringify(config)],
+    {
+      detached: true,
+      stdio: ["ignore", "ignore", childStderrFd],
+    },
+  );
+  child.unref();
+  closeSync(childStderrFd);
+
+  const pid = child.pid!;
+  logger.info("daemon-spawned", { pid, session });
+
+  // Track spawn errors and early exits so the polling loop can fail fast.
+  let childSpawnError: Error | null = null;
+  let childEarlyExit: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  } | null = null;
+
+  child.on("error", (err) => {
+    childSpawnError = err;
+    logger.error("daemon-spawn-error", { error: err, session });
+  });
+
+  child.on("exit", (code, signal) => {
+    childEarlyExit = { code, signal };
+    logger.warn("daemon-early-exit", { code, signal, session, pid });
+  });
+
+  // Poll the daemon's IPC server until it responds to a ping.
+  const socketPath = getDaemonSocketPath(session);
+  const client = new DaemonClient(socketPath);
+  const maxAttempts = Math.ceil(ipcTimeoutMs / IPC_POLL_INTERVAL_MS);
+  let ipcReady = false;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    // Fail fast on spawn errors. The cast is needed because TypeScript
+    // doesn't track that the variable is mutated asynchronously by the
+    // child's "error" event handler.
+    const spawnError = childSpawnError as Error | null;
+    if (spawnError !== null) {
+      await onFailure?.();
+      const errWithCode = spawnError as Error & { code?: string };
+      const hint =
+        errWithCode.code === "ENOENT"
+          ? " Ensure Node.js is available in PATH for child processes."
+          : "";
+      throw new Error(
+        `Failed to spawn daemon: ${spawnError.message}.${hint} Check logs: ${logPath}`,
+      );
+    }
+
+    // Fail fast on early exit.
+    const earlyExit = childEarlyExit as {
+      code: number | null;
+      signal: NodeJS.Signals | null;
+    } | null;
+    if (earlyExit !== null) {
+      await onFailure?.();
+      const status = earlyExit.code ?? earlyExit.signal ?? "unknown";
+      throw new Error(
+        `Daemon exited before startup (status: ${status}). Check logs: ${logPath}`,
+      );
+    }
+
+    await new Promise((r) => setTimeout(r, IPC_POLL_INTERVAL_MS));
+    ipcReady = await client.ping();
+    if (ipcReady) break;
+
+    if (i > 0 && i % 10 === 0) {
+      logger.info("daemon-waiting-for-ipc", { attempt: i, session });
+    }
+  }
+
+  if (!ipcReady) {
+    // Kill the orphaned daemon process before reporting failure.
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // Process may have already exited.
+    }
+    await onFailure?.();
+    throw new Error(
+      `Daemon failed to start within ${Math.ceil(ipcTimeoutMs / 1000)}s. Check logs: ${logPath}`,
+    );
+  }
+
+  logger.info("daemon-ipc-ready", { session, socketPath });
+  return { pid, socketPath, client };
+}