libretto 0.6.9 → 0.6.11

package/dist/cli/core/daemon/daemon.js

@@ -0,0 +1,298 @@
+import {
+  chromium
+} from "playwright";
+import { mkdir } from "node:fs/promises";
+import { appendFileSync } from "node:fs";
+import { installSessionTelemetry } from "../session-telemetry.js";
+import {
+  createLoggerForSession,
+  getSessionDir,
+  getSessionNetworkLogPath,
+  getSessionActionsLogPath
+} from "../context.js";
+import {
+  DaemonServer,
+  getDaemonSocketPath
+} from "./ipc.js";
+import { wrapPageForActionLogging } from "../telemetry.js";
+import { handlePages } from "./pages.js";
+import { handleExec, handleReadonlyExec } from "./exec.js";
+import { handleSnapshot } from "./snapshot.js";
+import {
+  isConnectConfig
+} from "./config.js";
+function isOperationalPage(page) {
+  const url = page.url();
+  return !url.startsWith("devtools://") && !url.startsWith("chrome-error://");
+}
+const PROTOCOL_VERSION = 1;
+const REQUEST_TIMEOUT_MS = 6e4;
+class BrowserDaemon {
+  constructor(session, externallyManaged, browser, context, page, ipcServer, logger) {
+    this.session = session;
+    this.externallyManaged = externallyManaged;
+    this.browser = browser;
+    this.context = context;
+    this.page = page;
+    this.ipcServer = ipcServer;
+    this.logger = logger.withScope("child");
+  }
+  logger;
+  execState = {};
+  pageById = /* @__PURE__ */ new Map();
+  shuttingDown = false;
+  trackPage(page) {
+    const id = `page-${Math.random().toString(36).slice(2, 5)}`;
+    this.pageById.set(id, page);
+    page.on("close", () => this.pageById.delete(id));
+    return id;
+  }
+  // ── Shared initialization ──────────────────────────────────────────
+  /**
+   * Common setup after the mode-specific code has obtained a browser,
+   * context, and page(s). Installs telemetry, action logging, IPC
+   * server, page tracking, and the browser disconnect handler.
+   */
+  static async initialize(args) {
+    const {
+      session,
+      externallyManaged,
+      browser,
+      context,
+      page,
+      initialPages,
+      navigateUrl
+    } = args;
+    await mkdir(getSessionDir(session), { recursive: true });
+    const networkLogFile = getSessionNetworkLogPath(session);
+    const actionsLogFile = getSessionActionsLogPath(session);
+    const logger = createLoggerForSession(session);
+    try {
+      await installSessionTelemetry({
+        context,
+        initialPage: page,
+        includeUserDomActions: true,
+        logAction: (entry) => {
+          appendFileSync(actionsLogFile, JSON.stringify(entry) + "\n");
+        },
+        logNetwork: (entry) => {
+          appendFileSync(networkLogFile, JSON.stringify(entry) + "\n");
+        }
+      });
+    } catch (err) {
+      logger.warn("telemetry-install-failed", {
+        session,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const socketPath = getDaemonSocketPath(session);
+    let handler;
+    const ipcServer = new DaemonServer(
+      socketPath,
+      (request) => handler(request)
+    );
+    const daemon = new BrowserDaemon(
+      session,
+      externallyManaged,
+      browser,
+      context,
+      page,
+      ipcServer,
+      logger
+    );
+    for (const p of initialPages) {
+      wrapPageForActionLogging(p, session);
+      daemon.trackPage(p);
+    }
+    context.on("page", (newPage) => {
+      wrapPageForActionLogging(newPage, session);
+      daemon.trackPage(newPage);
+    });
+    if (navigateUrl) {
+      await page.goto(navigateUrl);
+    }
+    handler = (request) => daemon.handleRequest(request);
+    await ipcServer.listen();
+    daemon.logger.info("ipc-server-listening", { socketPath });
+    browser.on("disconnected", () => {
+      void daemon.shutdown("browser-disconnected-exiting", false);
+    });
+    return daemon;
+  }
+  // ── Launch mode ────────────────────────────────────────────────────
+  static async launchBrowser(config) {
+    const windowPositionArg = config.windowPosition ? `--window-position=${config.windowPosition.x},${config.windowPosition.y}` : void 0;
+    const browser = await chromium.launch({
+      headless: !config.headed,
+      args: [
+        "--disable-blink-features=AutomationControlled",
+        `--remote-debugging-port=${config.port}`,
+        "--remote-debugging-address=127.0.0.1",
+        "--no-focus-on-check",
+        ...windowPositionArg ? [windowPositionArg] : []
+      ]
+    });
+    const context = await browser.newContext({
+      ...config.storageStatePath ? { storageState: config.storageStatePath } : {},
+      viewport: {
+        width: config.viewport.width,
+        height: config.viewport.height
+      },
+      userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(3e4);
+    page.setDefaultNavigationTimeout(45e3);
+    const daemon = await BrowserDaemon.initialize({
+      session: config.session,
+      externallyManaged: false,
+      browser,
+      context,
+      page,
+      initialPages: [page],
+      navigateUrl: config.url
+    });
+    daemon.logger.info("child-launched", {
+      port: config.port,
+      pid: process.pid,
+      session: config.session
+    });
+    return daemon;
+  }
+  // ── Connect mode ───────────────────────────────────────────────────
+  static async connectToEndpoint(config) {
+    const browser = await chromium.connectOverCDP(config.cdpEndpoint);
+    const contexts = browser.contexts();
+    const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+    const operationalPages = context.pages().filter(isOperationalPage);
+    const page = operationalPages.length > 0 ? operationalPages[operationalPages.length - 1] : await context.newPage();
+    const daemon = await BrowserDaemon.initialize({
+      session: config.session,
+      externallyManaged: true,
+      browser,
+      context,
+      page,
+      initialPages: operationalPages.length > 0 ? operationalPages : [page],
+      navigateUrl: config.url
+    });
+    daemon.logger.info("child-connected", {
+      cdpEndpoint: config.cdpEndpoint,
+      url: config.url,
+      pid: process.pid,
+      session: config.session
+    });
+    return daemon;
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────────
+  async shutdown(reason, closeBrowser) {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    this.logger.info(reason, { session: this.session });
+    await this.ipcServer.close();
+    if (!closeBrowser) return;
+    if (this.externallyManaged) {
+      try {
+        this.browser._connection?.close();
+      } catch {
+      }
+    } else {
+      await this.browser.close();
+    }
+  }
+  // ── Page resolution ────────────────────────────────────────────────
+  resolveTargetPage(pageId) {
+    if (!pageId) {
+      if (this.pageById.size > 1) {
+        throw new Error(
+          `Multiple pages are open in session "${this.session}". Pass --page <id> to target a page (run "libretto pages --session ${this.session}" to list ids).`
+        );
+      }
+      if (this.pageById.size === 1) {
+        return this.pageById.values().next().value;
+      }
+      return this.page;
+    }
+    const page = this.pageById.get(pageId);
+    if (!page) {
+      throw new Error(
+        `Page "${pageId}" was not found in session "${this.session}". Run "libretto pages --session ${this.session}" to list ids.`
+      );
+    }
+    return page;
+  }
+  // ── IPC handler ────────────────────────────────────────────────────
+  async handleRequest(request) {
+    if (request.command === "ping") {
+      return { protocolVersion: PROTOCOL_VERSION };
+    }
+    let timerId;
+    return Promise.race([
+      this.dispatchCommand(request).finally(() => clearTimeout(timerId)),
+      new Promise((_resolve, reject) => {
+        timerId = setTimeout(
+          () => reject(
+            new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`)
+          ),
+          REQUEST_TIMEOUT_MS
+        );
+      })
+    ]);
+  }
+  async dispatchCommand(request) {
+    switch (request.command) {
+      case "pages":
+        return handlePages(this.pageById, this.page);
+      case "exec":
+        return handleExec(
+          this.resolveTargetPage(request.pageId),
+          request.code,
+          this.context,
+          this.browser,
+          this.execState,
+          this.session,
+          request.visualize
+        );
+      case "readonly-exec":
+        return handleReadonlyExec(
+          this.resolveTargetPage(request.pageId),
+          request.code
+        );
+      case "snapshot":
+        return handleSnapshot(
+          this.resolveTargetPage(request.pageId),
+          this.session,
+          this.logger,
+          request.pageId
+        );
+      default:
+        throw new Error(
+          `Unknown command: ${request.command}`
+        );
+    }
+  }
+}
+async function main() {
+  const config = JSON.parse(process.argv[2]);
+  const daemon = isConnectConfig(config) ? await BrowserDaemon.connectToEndpoint(config) : await BrowserDaemon.launchBrowser(config);
+  process.on("SIGTERM", () => {
+    void daemon.shutdown("child-sigterm", true);
+  });
+  process.on("SIGINT", () => {
+    void daemon.shutdown("child-sigint", true);
+  });
+  process.on("uncaughtException", (err) => {
+    daemon.logger.error("uncaught-exception", err);
+    process.exit(1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    daemon.logger.warn("unhandled-rejection", { reason: String(reason) });
+  });
+  process.on("exit", (code) => {
+    daemon.logger.info("child-exit", {
+      code,
+      pid: process.pid,
+      session: config.session
+    });
+  });
+}
+await main();

package/dist/cli/core/daemon/exec.js

@@ -0,0 +1,86 @@
+import { format, formatWithOptions } from "node:util";
+import { installInstrumentation } from "../../../shared/instrumentation/index.js";
+import { compileExecFunction } from "../exec-compiler.js";
+import { createReadonlyExecHelpers } from "../readonly-exec.js";
+import { readNetworkLog, readActionLog } from "../telemetry.js";
+class DaemonExecError extends Error {
+  constructor(message, output) {
+    super(message);
+    this.output = output;
+    this.name = "DaemonExecError";
+  }
+}
+function createBufferedConsole() {
+  const output = { stdout: "", stderr: "" };
+  const writeStdout = (...args) => {
+    output.stdout += `${format(...args)}
+`;
+  };
+  const writeStderr = (...args) => {
+    output.stderr += `${format(...args)}
+`;
+  };
+  const bufferedConsole = {
+    ...globalThis.console,
+    log: writeStdout,
+    info: writeStdout,
+    debug: writeStdout,
+    dir: (value, options) => {
+      output.stdout += `${formatWithOptions(options ?? {}, value)}
+`;
+    },
+    warn: writeStderr,
+    error: writeStderr
+  };
+  return { console: bufferedConsole, output };
+}
+async function handleExec(targetPage, code, context, browser, execState, session, visualize) {
+  const buffered = createBufferedConsole();
+  if (visualize) {
+    await installInstrumentation(targetPage, { visualize: true });
+  }
+  const networkLog = (opts = {}) => readNetworkLog(session, opts);
+  const actionLog = (opts = {}) => readActionLog(session, opts);
+  const helpers = {
+    page: targetPage,
+    context,
+    browser,
+    state: execState,
+    console: buffered.console,
+    networkLog,
+    actionLog
+  };
+  const helperNames = Object.keys(helpers);
+  const fn = compileExecFunction(code, helperNames);
+  try {
+    const result = await fn(...Object.values(helpers));
+    return { result, output: buffered.output };
+  } catch (error) {
+    throw new DaemonExecError(
+      error instanceof Error ? error.message : String(error),
+      buffered.output
+    );
+  }
+}
+async function handleReadonlyExec(targetPage, code) {
+  const buffered = createBufferedConsole();
+  const helpers = createReadonlyExecHelpers(targetPage, {
+    console: buffered.console
+  });
+  const helperNames = Object.keys(helpers);
+  const fn = compileExecFunction(code, helperNames);
+  try {
+    const result = await fn(...Object.values(helpers));
+    return { result, output: buffered.output };
+  } catch (error) {
+    throw new DaemonExecError(
+      error instanceof Error ? error.message : String(error),
+      buffered.output
+    );
+  }
+}
+export {
+  DaemonExecError,
+  handleExec,
+  handleReadonlyExec
+};

package/dist/cli/core/daemon/index.js

@@ -0,0 +1,16 @@
+import {
+  DaemonServer,
+  DaemonClient,
+  DaemonClientError,
+  getDaemonSocketPath
+} from "./ipc.js";
+import {
+  spawnSessionDaemon
+} from "./spawn.js";
+export {
+  DaemonClient,
+  DaemonClientError,
+  DaemonServer,
+  getDaemonSocketPath,
+  spawnSessionDaemon
+};

package/dist/cli/core/daemon/ipc.js

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { createServer, connect as netConnect } from "node:net";
+import { unlink } from "node:fs/promises";
+import { REPO_ROOT } from "../context.js";
+class DaemonClientError extends Error {
+  constructor(message, output) {
+    super(message);
+    this.output = output;
+    this.name = "DaemonClientError";
+  }
+}
+function getDaemonSocketPath(session) {
+  const hash = createHash("sha256").update(`${REPO_ROOT}:${session}`).digest("hex").slice(0, 12);
+  return `/tmp/libretto-${process.getuid()}-${hash}.sock`;
+}
+class DaemonServer {
+  constructor(socketPath, handler) {
+    this.socketPath = socketPath;
+    this.handler = handler;
+  }
+  server = null;
+  async listen() {
+    try {
+      await unlink(this.socketPath);
+    } catch (err) {
+      if (err.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;
+          try {
+            const request = JSON.parse(line);
+            const data = await this.handler(request);
+            response = { id: request.id, type: "result", data };
+          } catch (err) {
+            const id = (() => {
+              try {
+                return JSON.parse(line).id ?? "unknown";
+              } catch {
+                return "unknown";
+              }
+            })();
+            response = {
+              id,
+              type: "error",
+              message: err instanceof Error ? err.message : String(err),
+              output: err instanceof Error ? err.output : void 0
+            };
+          }
+          socket.end(JSON.stringify(response) + "\n");
+        })();
+      });
+    });
+    this.server = server;
+    await new Promise((resolve, reject) => {
+      server.on("error", reject);
+      server.listen(this.socketPath, () => resolve());
+    });
+  }
+  async close() {
+    const server = this.server;
+    if (!server) return;
+    this.server = null;
+    await new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    });
+    try {
+      await unlink(this.socketPath);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+}
+class DaemonClient {
+  constructor(socketPath) {
+    this.socketPath = socketPath;
+  }
+  async send(request) {
+    return new Promise((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());
+          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);
+      });
+    });
+  }
+  generateId() {
+    return Math.random().toString(36).slice(2, 10);
+  }
+  async sendOrThrow(request) {
+    const response = await this.send(request);
+    if (response.type === "error") {
+      throw new DaemonClientError(response.message, response.output);
+    }
+    return response.data;
+  }
+  async sendResult(request) {
+    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 };
+  }
+  async ping() {
+    try {
+      await this.sendOrThrow({ id: this.generateId(), command: "ping" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async pages() {
+    return this.sendOrThrow({ id: this.generateId(), command: "pages" });
+  }
+  async exec(args) {
+    return this.sendResult({
+      id: this.generateId(),
+      command: "exec",
+      ...args
+    });
+  }
+  async readonlyExec(args) {
+    return this.sendResult({
+      id: this.generateId(),
+      command: "readonly-exec",
+      ...args
+    });
+  }
+  async snapshot(args = {}) {
+    return this.sendOrThrow({
+      id: this.generateId(),
+      command: "snapshot",
+      ...args
+    });
+  }
+}
+export {
+  DaemonClient,
+  DaemonClientError,
+  DaemonServer,
+  getDaemonSocketPath
+};

package/dist/cli/core/daemon/pages.js

@@ -0,0 +1,15 @@
+function handlePages(pageById, activePage) {
+  const results = [];
+  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;
+}
+export {
+  handlePages
+};

package/dist/cli/core/daemon/snapshot.js

@@ -0,0 +1,86 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { getSessionSnapshotRunDir } from "../context.js";
+import {
+  resolveSnapshotViewport,
+  readSnapshotViewportMetrics,
+  shouldForceSnapshotViewport,
+  isZeroWidthScreenshotError,
+  forceSnapshotViewport
+} from "../../commands/snapshot.js";
+const RENDER_SETTLE_TIMEOUT_MS = 1e4;
+async function handleSnapshot(targetPage, session, logger, pageId) {
+  const snapshotRunId = `snapshot-${Date.now()}`;
+  const snapshotRunDir = getSessionSnapshotRunDir(session, snapshotRunId);
+  mkdirSync(snapshotRunDir, { recursive: true });
+  let title = null;
+  try {
+    title = await targetPage.title();
+  } catch (error) {
+    logger.warn("screenshot-title-read-failed", { session, pageId, error });
+  }
+  let pageUrl = 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`;
+  await Promise.race([
+    targetPage.waitForLoadState("networkidle").catch(() => {
+    }),
+    new Promise((resolve) => setTimeout(resolve, RENDER_SETTLE_TIMEOUT_MS))
+  ]);
+  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"
+  );
+  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 });
+  }
+  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 ?? ""
+  };
+}
+export {
+  handleSnapshot
+};