libretto 0.1.5 → 0.2.1

package/dist/cli/commands/execution.js

@@ -0,0 +1,422 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { fork } from "node:child_process";
+import * as moduleBuiltin from "node:module";
+import { fileURLToPath } from "node:url";
+import { installInstrumentation } from "../../shared/instrumentation/index.js";
+import {
+  connect,
+  disconnectBrowser
+} from "../core/browser.js";
+import { getPauseSignalPaths } from "../core/pause-signals.js";
+import {
+  assertSessionAvailableForStart,
+  readSessionStateOrThrow,
+  setSessionStatus
+} from "../core/session.js";
+import {
+  readActionLog,
+  readNetworkLog,
+  wrapPageForActionLogging
+} from "../core/telemetry.js";
+const stripTypeScriptTypes = moduleBuiltin.stripTypeScriptTypes;
+function withSuppressedStripTypeScriptWarning(action) {
+  const mutableProcess = process;
+  const originalEmitWarning = mutableProcess.emitWarning;
+  mutableProcess.emitWarning = (...args) => {
+    const warning = args[0];
+    const typeOrOptions = args[1];
+    const warningMessage = typeof warning === "string" ? warning : warning instanceof Error ? warning.message : "";
+    const warningType = typeof typeOrOptions === "string" ? typeOrOptions : typeof typeOrOptions === "object" && typeOrOptions !== null && "type" in typeOrOptions && typeof typeOrOptions.type === "string" ? typeOrOptions.type ?? "" : "";
+    if (warningType === "ExperimentalWarning" && warningMessage.includes("stripTypeScriptTypes")) {
+      return;
+    }
+    originalEmitWarning(...args);
+  };
+  try {
+    return action();
+  } finally {
+    mutableProcess.emitWarning = originalEmitWarning;
+  }
+}
+function compileTypeScriptExecFunction(code, helperNames) {
+  if (!stripTypeScriptTypes) return null;
+  const wrappedSource = `(async function __librettoExec(${helperNames.join(", ")}) {
+${code}
+})`;
+  const jsSource = withSuppressedStripTypeScriptWarning(
+    () => stripTypeScriptTypes(wrappedSource, { mode: "strip" })
+  );
+  const createFunction = new Function(
+    `return ${jsSource}`
+  );
+  return createFunction();
+}
+function compileExecFunction(code, helperNames) {
+  const typeStripped = compileTypeScriptExecFunction(code, helperNames);
+  if (typeStripped) return typeStripped;
+  const AsyncFunction = Object.getPrototypeOf(async function() {
+  }).constructor;
+  return new AsyncFunction(...helperNames, code);
+}
+async function runExec(code, session, logger, visualize = false, pageId) {
+  readSessionStateOrThrow(session);
+  logger.info("exec-start", {
+    session,
+    codeLength: code.length,
+    codePreview: code.slice(0, 200),
+    visualize,
+    pageId
+  });
+  const { browser, context, page, pageId: resolvedPageId } = await connect(
+    session,
+    logger,
+    1e4,
+    {
+      pageId,
+      requireSinglePage: true
+    }
+  );
+  const STALL_THRESHOLD_MS = 6e4;
+  let lastActivityTs = Date.now();
+  const onActivity = () => {
+    lastActivityTs = Date.now();
+  };
+  const stallInterval = setInterval(() => {
+    const silenceMs = Date.now() - lastActivityTs;
+    if (silenceMs >= STALL_THRESHOLD_MS) {
+      logger.warn("exec-stall-warning", {
+        session,
+        silenceMs,
+        codePreview: code.slice(0, 200)
+      });
+      console.warn(
+        `[stall-warning] No Playwright activity for ${Math.round(silenceMs / 1e3)}s \u2014 exec may be hung (code: ${code.slice(0, 100)}...)`
+      );
+    }
+  }, STALL_THRESHOLD_MS);
+  const execStartTs = Date.now();
+  const sigintHandler = () => {
+    logger.info("exec-interrupted", {
+      session,
+      duration: Date.now() - execStartTs,
+      codePreview: code.slice(0, 200)
+    });
+  };
+  process.on("SIGINT", sigintHandler);
+  wrapPageForActionLogging(page, session, resolvedPageId, onActivity);
+  if (visualize) {
+    await installInstrumentation(page, { visualize: true, logger });
+  }
+  try {
+    const execState = {};
+    const networkLog = (opts = {}) => {
+      return readNetworkLog(session, opts);
+    };
+    const actionLog = (opts = {}) => {
+      return readActionLog(session, opts);
+    };
+    const helpers = {
+      page,
+      context,
+      state: execState,
+      browser,
+      networkLog,
+      actionLog,
+      console,
+      setTimeout,
+      setInterval,
+      clearTimeout,
+      clearInterval,
+      fetch,
+      URL,
+      Buffer
+    };
+    const helperNames = Object.keys(helpers);
+    const fn = compileExecFunction(code, helperNames);
+    const result = await fn(...Object.values(helpers));
+    logger.info("exec-success", { session, hasResult: result !== void 0 });
+    if (result !== void 0) {
+      console.log(
+        typeof result === "string" ? result : JSON.stringify(result, null, 2)
+      );
+    }
+  } catch (err) {
+    logger.error("exec-error", {
+      error: err,
+      session,
+      codePreview: code.slice(0, 200)
+    });
+    throw err;
+  } finally {
+    clearInterval(stallInterval);
+    process.removeListener("SIGINT", sigintHandler);
+    disconnectBrowser(browser, logger, session);
+  }
+}
+function parseJsonArg(label, raw) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON in ${label}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readJsonFileIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readFailureMessage(path) {
+  const raw = readJsonFileIfExists(path);
+  if (!raw || typeof raw !== "object") return null;
+  const message = raw.message;
+  return typeof message === "string" ? message : null;
+}
+async function waitForFailureMessage(path, timeoutMs = 1e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const message = readFailureMessage(path);
+    if (message) return message;
+    await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+  }
+  return readFailureMessage(path);
+}
+function streamOutputSince(path, offset) {
+  if (!existsSync(path)) return offset;
+  const output = readFileSync(path);
+  if (output.length <= offset) return output.length;
+  process.stdout.write(output.subarray(offset));
+  return output.length;
+}
+function clearSignalIfExists(path) {
+  if (!existsSync(path)) return;
+  try {
+    unlinkSync(path);
+  } catch {
+  }
+}
+async function waitForWorkflowOutcome(args) {
+  const signalPaths = getPauseSignalPaths(args.session);
+  if (args.pid <= 0) {
+    return { status: "exited" };
+  }
+  let outputOffset = 0;
+  while (true) {
+    outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+    if (existsSync(signalPaths.failedSignalPath)) {
+      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      const message = await waitForFailureMessage(signalPaths.failedSignalPath);
+      return { status: "failed", message: message ?? void 0 };
+    }
+    if (existsSync(signalPaths.completedSignalPath)) {
+      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      return { status: "completed" };
+    }
+    if (existsSync(signalPaths.pausedSignalPath)) {
+      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      return { status: "paused" };
+    }
+    if (!isProcessRunning(args.pid)) {
+      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      return { status: "exited" };
+    }
+    await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+  }
+}
+async function runResume(session, logger) {
+  const state = readSessionStateOrThrow(session);
+  const {
+    pausedSignalPath,
+    resumeSignalPath,
+    completedSignalPath,
+    failedSignalPath,
+    outputSignalPath
+  } = getPauseSignalPaths(session);
+  if (!existsSync(pausedSignalPath)) {
+    throw new Error(
+      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call ctx.pause() first.`
+    );
+  }
+  if (!isProcessRunning(state.pid)) {
+    throw new Error(
+      `No active paused workflow found for session "${session}" (worker pid ${state.pid} is not running).`
+    );
+  }
+  clearSignalIfExists(pausedSignalPath);
+  clearSignalIfExists(outputSignalPath);
+  clearSignalIfExists(completedSignalPath);
+  clearSignalIfExists(failedSignalPath);
+  setSessionStatus(session, "active", logger);
+  writeFileSync(
+    resumeSignalPath,
+    JSON.stringify(
+      {
+        resumedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        sourcePid: process.pid
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+  console.log(`Resume signal sent for session "${session}".`);
+  const outcome = await waitForWorkflowOutcome({
+    session,
+    pid: state.pid
+  });
+  if (outcome.status === "completed") {
+    setSessionStatus(session, "completed", logger);
+    console.log("Integration completed.");
+    return;
+  }
+  if (outcome.status === "failed") {
+    setSessionStatus(session, "failed", logger);
+    throw new Error(
+      outcome.message ? `Workflow failed after resume: ${outcome.message}` : "Workflow failed after resume."
+    );
+  }
+  if (outcome.status === "exited") {
+    setSessionStatus(session, "exited", logger);
+    throw new Error(
+      `Workflow process for session "${session}" exited before reporting completion or pause.`
+    );
+  }
+  setSessionStatus(session, "paused", logger);
+  console.log("Workflow paused.");
+}
+async function runIntegrationFromFile(args, logger) {
+  assertSessionAvailableForStart(args.session, logger);
+  const signalPaths = getPauseSignalPaths(args.session);
+  clearSignalIfExists(signalPaths.pausedSignalPath);
+  clearSignalIfExists(signalPaths.resumeSignalPath);
+  clearSignalIfExists(signalPaths.completedSignalPath);
+  clearSignalIfExists(signalPaths.failedSignalPath);
+  clearSignalIfExists(signalPaths.outputSignalPath);
+  const workerEntryPath = fileURLToPath(
+    new URL("../workers/run-integration-worker.js", import.meta.url)
+  );
+  const payload = JSON.stringify(args);
+  const worker = fork(workerEntryPath, [payload], {
+    detached: true,
+    stdio: ["ignore", "ignore", "ignore", "ipc"],
+    env: process.env
+  });
+  worker.disconnect();
+  worker.unref();
+  const outcome = await waitForWorkflowOutcome({
+    session: args.session,
+    pid: worker.pid ?? 0
+  });
+  if (outcome.status === "paused") {
+    setSessionStatus(args.session, "paused", logger);
+    console.log("Workflow paused.");
+    return;
+  }
+  if (outcome.status === "failed") {
+    setSessionStatus(args.session, "failed", logger);
+    throw new Error(outcome.message ?? "Workflow failed during run.");
+  }
+  if (outcome.status === "exited") {
+    setSessionStatus(args.session, "exited", logger);
+    throw new Error(
+      "Workflow process exited before reporting completion or pause during run."
+    );
+  }
+  setSessionStatus(args.session, "completed", logger);
+}
+function registerExecutionCommands(yargs, logger) {
+  return yargs.command(
+    "exec [code..]",
+    "Execute Playwright TypeScript code",
+    (cmd) => cmd.option("visualize", { type: "boolean", default: false }).option("page", { type: "string" }),
+    async (argv) => {
+      const codeParts = Array.isArray(argv.code) ? argv.code : argv.code ? [String(argv.code)] : [];
+      const code = codeParts.join(" ");
+      if (!code) {
+        throw new Error(
+          "Usage: libretto-cli exec <code> [--session <name>] [--visualize]"
+        );
+      }
+      await runExec(
+        code,
+        String(argv.session),
+        logger,
+        Boolean(argv.visualize),
+        argv.page ? String(argv.page) : void 0
+      );
+    }
+  ).command(
+    "run [integrationFile] [integrationExport]",
+    "Run an exported Libretto workflow from a file",
+    (cmd) => cmd.option("params", { type: "string" }).option("params-file", { type: "string" }).option("headed", { type: "boolean", default: false }).option("headless", { type: "boolean", default: false }).option("debug", { type: "boolean" }),
+    async (argv) => {
+      const usage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--headed|--headless] [--debug]";
+      const integrationPath = argv.integrationFile;
+      const exportName = argv.integrationExport;
+      if (!integrationPath || !exportName) {
+        throw new Error(usage);
+      }
+      const session = String(argv.session);
+      const rawInlineParams = argv.params;
+      const paramsFile = argv["params-file"];
+      if (rawInlineParams && paramsFile) {
+        throw new Error("Pass either --params or --params-file, not both.");
+      }
+      const params = (() => {
+        if (paramsFile) {
+          let content;
+          try {
+            content = readFileSync(paramsFile, "utf8");
+          } catch {
+            throw new Error(
+              `Could not read --params-file "${paramsFile}". Ensure the file exists and is readable.`
+            );
+          }
+          return parseJsonArg("--params-file", content);
+        }
+        if (rawInlineParams) {
+          return parseJsonArg("--params", rawInlineParams);
+        }
+        return {};
+      })();
+      const hasHeadedFlag = Boolean(argv.headed);
+      const hasHeadlessFlag = Boolean(argv.headless);
+      if (hasHeadedFlag && hasHeadlessFlag) {
+        throw new Error("Cannot pass both --headed and --headless.");
+      }
+      const headlessMode = hasHeadedFlag ? false : hasHeadlessFlag ? true : void 0;
+      const debugFlag = argv.debug;
+      const debugMode = debugFlag !== void 0 ? debugFlag : process.env.LIBRETTO_DEBUG === "true";
+      await runIntegrationFromFile({
+        integrationPath,
+        exportName,
+        session,
+        params,
+        headless: headlessMode ?? false,
+        debug: debugMode
+      }, logger);
+    }
+  ).command(
+    "resume",
+    "Resume a paused workflow for the current session",
+    (cmd) => cmd,
+    async (argv) => {
+      await runResume(String(argv.session), logger);
+    }
+  );
+}
+export {
+  registerExecutionCommands
+};

package/dist/cli/commands/logs.js

@@ -0,0 +1,93 @@
+import { listOpenPages } from "../core/browser.js";
+import { withSessionLogger } from "../core/context.js";
+import {
+  clearActionLog,
+  clearNetworkLog,
+  formatActionEntry,
+  formatNetworkEntry,
+  readActionLog,
+  readNetworkLog
+} from "../core/telemetry.js";
+async function resolvePageId(session, pageId) {
+  if (!pageId) return void 0;
+  const pages = await withSessionLogger(
+    session,
+    async (logger) => listOpenPages(session, logger)
+  );
+  const foundPage = pages.find((page) => page.id === pageId);
+  if (!foundPage) {
+    throw new Error(
+      `Page "${pageId}" was not found in session "${session}". Run "libretto-cli pages --session ${session}" to list ids.`
+    );
+  }
+  return pageId;
+}
+function registerLogCommands(yargs) {
+  return yargs.command(
+    "network",
+    "View captured network requests",
+    (cmd) => cmd.option("last", { type: "number" }).option("filter", { type: "string" }).option("method", { type: "string" }).option("page", { type: "string" }).option("clear", { type: "boolean", default: false }),
+    async (argv) => {
+      const session = String(argv.session);
+      if (argv.clear) {
+        clearNetworkLog(session);
+        console.log("Network log cleared.");
+        return;
+      }
+      const pageId = await resolvePageId(
+        session,
+        argv.page ? String(argv.page) : void 0
+      );
+      const entries = readNetworkLog(session, {
+        last: typeof argv.last === "number" ? argv.last : void 0,
+        filter: argv.filter,
+        method: argv.method,
+        pageId
+      });
+      if (entries.length === 0) {
+        console.log("No network requests captured.");
+        return;
+      }
+      for (const entry of entries) {
+        console.log(formatNetworkEntry(entry));
+      }
+      console.log(`
+${entries.length} request(s) shown.`);
+    }
+  ).command(
+    "actions",
+    "View captured actions",
+    (cmd) => cmd.option("last", { type: "number" }).option("filter", { type: "string" }).option("action", { type: "string" }).option("source", { type: "string" }).option("page", { type: "string" }).option("clear", { type: "boolean", default: false }),
+    async (argv) => {
+      const session = String(argv.session);
+      if (argv.clear) {
+        clearActionLog(session);
+        console.log("Action log cleared.");
+        return;
+      }
+      const pageId = await resolvePageId(
+        session,
+        argv.page ? String(argv.page) : void 0
+      );
+      const entries = readActionLog(session, {
+        last: typeof argv.last === "number" ? argv.last : void 0,
+        filter: argv.filter,
+        action: argv.action,
+        source: argv.source,
+        pageId
+      });
+      if (entries.length === 0) {
+        console.log("No actions captured.");
+        return;
+      }
+      for (const entry of entries) {
+        console.log(formatActionEntry(entry));
+      }
+      console.log(`
+${entries.length} action(s) shown.`);
+    }
+  );
+}
+export {
+  registerLogCommands
+};

package/dist/cli/commands/snapshot.js

@@ -0,0 +1,106 @@
+import { mkdirSync } from "node:fs";
+import { connect, disconnectBrowser } from "../core/browser.js";
+import { getSessionSnapshotRunDir } from "../core/context.js";
+import {
+  canAnalyzeSnapshots,
+  runInterpret
+} from "../core/snapshot-analyzer.js";
+const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
+function generateSnapshotRunId() {
+  return `snapshot-${Date.now()}`;
+}
+async function captureScreenshot(session, logger, pageId) {
+  logger.info("screenshot-start", { session, pageId });
+  const snapshotRunId = generateSnapshotRunId();
+  const snapshotRunDir = getSessionSnapshotRunDir(session, snapshotRunId);
+  mkdirSync(snapshotRunDir, { recursive: true });
+  const { browser, page } = await connect(session, logger, 1e4, {
+    pageId,
+    requireSinglePage: true
+  });
+  try {
+    const title = await page.title();
+    const pageUrl = page.url();
+    const pngPath = `${snapshotRunDir}/page.png`;
+    const htmlPath = `${snapshotRunDir}/page.html`;
+    await page.screenshot({ path: pngPath });
+    const htmlContent = await page.content();
+    const fs = await import("node:fs/promises");
+    await fs.writeFile(htmlPath, htmlContent);
+    logger.info("screenshot-success", {
+      session,
+      pageUrl,
+      title,
+      pngPath,
+      htmlPath,
+      snapshotRunId
+    });
+    return { pngPath, htmlPath, baseName: snapshotRunId };
+  } catch (err) {
+    let pageAlive = false;
+    let browserConnected = false;
+    try {
+      browserConnected = browser.isConnected();
+      pageAlive = !page.isClosed();
+    } catch {
+    }
+    logger.error("screenshot-error", {
+      error: err,
+      session,
+      pageAlive,
+      browserConnected,
+      pageUrl: page.url()
+    });
+    throw err;
+  } finally {
+    disconnectBrowser(browser, logger, session);
+  }
+}
+async function runSnapshot(session, logger, pageId, objective, context) {
+  const { pngPath, htmlPath } = await captureScreenshot(session, logger, pageId);
+  console.log("Screenshot saved:");
+  console.log(`  PNG:  ${pngPath}`);
+  console.log(`  HTML: ${htmlPath}`);
+  const normalizedObjective = objective?.trim();
+  const normalizedContext = context?.trim();
+  if (!normalizedObjective && !normalizedContext) {
+    console.log("Use --objective flag to analyze snapshots.");
+    return;
+  }
+  if (!normalizedObjective) {
+    throw new Error(
+      "Couldn't run analysis: --objective is required when providing --context."
+    );
+  }
+  if (!canAnalyzeSnapshots()) {
+    throw new Error(
+      "Couldn't run analysis: no AI config set. Run 'libretto-cli ai configure codex' (or claude/gemini) to enable analysis."
+    );
+  }
+  await runInterpret({
+    objective: normalizedObjective,
+    session,
+    context: normalizedContext ?? DEFAULT_SNAPSHOT_CONTEXT,
+    pngPath,
+    htmlPath
+  }, logger);
+}
+function registerSnapshotCommands(yargs, logger) {
+  return yargs.command(
+    "snapshot",
+    "Capture PNG + HTML; analyze when --objective is provided (--context optional)",
+    (cmd) => cmd.option("page", { type: "string" }).option("objective", { type: "string" }).option("context", { type: "string" }),
+    async (argv) => {
+      await runSnapshot(
+        String(argv.session),
+        logger,
+        argv.page ? String(argv.page) : void 0,
+        argv.objective,
+        argv.context
+      );
+    }
+  );
+}
+export {
+  registerSnapshotCommands
+};