libretto 0.3.0 → 0.3.1

package/dist/cli/commands/execution.js

@@ -0,0 +1,490 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawn } 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,
+  clearSessionState,
+  readSessionState,
+  readSessionStateOrThrow,
+  setSessionStatus
+} from "../core/session.js";
+import {
+  readActionLog,
+  readNetworkLog,
+  wrapPageForActionLogging
+} from "../core/telemetry.js";
+const stripTypeScriptTypes = moduleBuiltin.stripTypeScriptTypes;
+const require2 = moduleBuiltin.createRequire(import.meta.url);
+const tsxCliPath = require2.resolve("tsx/cli");
+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;
+  }
+}
+async function stopExistingFailedRunSession(session, logger) {
+  const existingState = readSessionState(session, logger);
+  if (!existingState || existingState.status !== "failed") {
+    return;
+  }
+  logger.info("run-release-existing-failed-session", {
+    session,
+    pid: existingState.pid,
+    port: existingState.port
+  });
+  clearSessionState(session, logger);
+  const stopDeadline = Date.now() + 3e3;
+  while (isProcessRunning(existingState.pid) && Date.now() < stopDeadline) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+  }
+  if (isProcessRunning(existingState.pid)) {
+    logger.warn("run-release-existing-failed-session-timeout", {
+      session,
+      pid: existingState.pid
+    });
+    console.warn(
+      `Existing failed workflow process for session "${session}" (pid ${existingState.pid}) is still shutting down; continuing.`
+    );
+    return;
+  }
+  console.log(
+    `Closed existing failed workflow process for session "${session}" (pid ${existingState.pid}).`
+  );
+}
+function readJsonFileIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readFailureSignal(path) {
+  const raw = readJsonFileIfExists(path);
+  if (!raw || typeof raw !== "object") return null;
+  const message = raw.message;
+  if (typeof message !== "string") return null;
+  const phase = raw.phase;
+  return {
+    message,
+    phase: phase === "setup" || phase === "workflow" ? phase : void 0
+  };
+}
+async function waitForFailureSignal(path, timeoutMs = 1e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const failure = readFailureSignal(path);
+    if (failure) return failure;
+    await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+  }
+  return readFailureSignal(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 failure = await waitForFailureSignal(signalPaths.failedSignalPath);
+      return {
+        status: "failed",
+        message: failure?.message,
+        failurePhase: failure?.phase
+      };
+    }
+    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 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) {
+  await stopExistingFailedRunSession(args.session, 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({
+    integrationPath: args.integrationPath,
+    exportName: args.exportName,
+    session: args.session,
+    params: args.params,
+    headless: args.headless,
+    authProfileDomain: args.authProfileDomain
+  });
+  const worker = spawn(process.execPath, [
+    tsxCliPath,
+    ...args.tsconfigPath ? ["--tsconfig", args.tsconfigPath] : [],
+    workerEntryPath,
+    payload
+  ], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  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);
+    const message = outcome.message ?? "Workflow failed during run.";
+    if (outcome.failurePhase === "workflow") {
+      throw new Error(
+        `${message}
+Browser is still open. You can use \`exec\` to inspect it. Call \`run\` to re-run the workflow.`
+      );
+    }
+    throw new Error(message);
+  }
+  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("tsconfig", { type: "string" }).option("headed", { type: "boolean", default: false }).option("headless", { type: "boolean", default: false }).option("auth-profile", { type: "string", describe: "Domain for local auth profile (e.g. apps.example.com)" }),
+    async (argv) => {
+      const usage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]";
+      const integrationPath = argv.integrationFile;
+      const exportName = argv.integrationExport;
+      const legacyDebug = argv.debug;
+      if (legacyDebug !== void 0) {
+        throw new Error(
+          "The --debug flag has been removed. Run the command without --debug."
+        );
+      }
+      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 authProfileDomain = argv["auth-profile"];
+      const tsconfigPath = argv.tsconfig;
+      await runIntegrationFromFile({
+        integrationPath,
+        exportName,
+        session,
+        params,
+        headless: headlessMode ?? false,
+        authProfileDomain,
+        tsconfigPath
+      }, 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/init.js

@@ -0,0 +1,166 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { join, delimiter, extname } from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  AI_CONFIG_PRESETS,
+  AiPresetSchema,
+  formatCommandPrefix,
+  readAiConfig
+} from "../core/ai-config.js";
+const AI_RUNTIME_PRESETS = AiPresetSchema.options;
+function getPresetCommand(preset) {
+  return AI_CONFIG_PRESETS[preset][0] ?? "";
+}
+function isRunnableFile(filePath) {
+  try {
+    const stats = statSync(filePath);
+    if (!stats.isFile()) return false;
+    if (process.platform === "win32") {
+      const pathExt = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+      const extensions = pathExt.split(";").map((ext) => ext.trim().toUpperCase()).filter(Boolean);
+      const fileExt = extname(filePath).toUpperCase();
+      return extensions.includes(fileExt);
+    }
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isCommandDefined(command) {
+  if (!command) return false;
+  if (command.includes("/") || command.includes("\\")) {
+    return isRunnableFile(command);
+  }
+  const pathEnv = process.env.PATH ?? "";
+  if (!pathEnv) return false;
+  const pathEntries = pathEnv.split(delimiter).filter(Boolean);
+  if (process.platform === "win32") {
+    const pathExt = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+    const extensions = pathExt.split(";").map((ext) => ext.trim()).filter(Boolean);
+    const hasExtension = /\.[^./\\]+$/.test(command);
+    const candidates = hasExtension ? [command] : extensions.map(
+      (ext) => ext.startsWith(".") ? `${command}${ext}` : `${command}.${ext}`
+    );
+    return pathEntries.some(
+      (dir) => candidates.some((candidate) => isRunnableFile(join(dir, candidate)))
+    );
+  }
+  return pathEntries.some((dir) => isRunnableFile(join(dir, command)));
+}
+function detectAvailableAiRuntimeCommands() {
+  return AI_RUNTIME_PRESETS.filter(
+    (preset) => isCommandDefined(getPresetCommand(preset))
+  );
+}
+function printAiConfigureCommands(prefix = "    ") {
+  for (const preset of AI_RUNTIME_PRESETS) {
+    console.log(`${prefix}npx libretto ai configure ${preset}`);
+  }
+}
+function printDifferentAnalyzerHint(prefix = "    ") {
+  console.log(
+    `${prefix}Use npx libretto ai configure <gemini|claude|codex> to configure a different AI analyzer.`
+  );
+}
+function installBrowsers() {
+  console.log("\nInstalling Playwright Chromium...");
+  const result = spawnSync("npx", ["playwright", "install", "chromium"], {
+    stdio: "inherit",
+    shell: true
+  });
+  if (result.status === 0) {
+    console.log("  \u2713 Playwright Chromium installed");
+  } else {
+    console.error(
+      "  \u2717 Failed to install Playwright Chromium. Run manually: npx playwright install chromium"
+    );
+  }
+}
+function checkAiRuntimeConfiguration() {
+  let config = null;
+  let configReadError = null;
+  try {
+    config = readAiConfig();
+  } catch (error) {
+    configReadError = error instanceof Error ? error.message : String(error);
+  }
+  const availableCommands = detectAvailableAiRuntimeCommands();
+  console.log("\nAI runtime configuration:");
+  console.log(
+    "  Libretto can use your coding agent as a subagent to analyze snapshots and other page signals."
+  );
+  console.log(
+    "  This is optional, but it significantly improves page understanding and debugging performance."
+  );
+  if (configReadError) {
+    console.log(`  \u2717 Could not read AI config: ${configReadError}`);
+    console.log("    Reconfigure with:");
+    printAiConfigureCommands("      ");
+    printDifferentAnalyzerHint("    ");
+    return;
+  }
+  if (config) {
+    const configuredCommand = config.commandPrefix[0];
+    if (!isCommandDefined(configuredCommand)) {
+      console.log(
+        `  \u2717 Configured command not found: ${configuredCommand ?? "(empty)"}`
+      );
+      if (availableCommands.length > 0) {
+        console.log(
+          `    Detected available commands: ${availableCommands.join(", ")}`
+        );
+      } else {
+        console.log(
+          "    No codex, claude, or gemini analyzer command was detected on PATH."
+        );
+      }
+      console.log("    Reconfigure with:");
+      printAiConfigureCommands("      ");
+      printDifferentAnalyzerHint("    ");
+      return;
+    }
+    console.log(
+      `  \u2713 Configured (${config.preset}): ${formatCommandPrefix(config.commandPrefix)}`
+    );
+    console.log("    Analysis commands are ready to use.");
+    printDifferentAnalyzerHint("    ");
+    return;
+  }
+  console.log("  \u2717 No AI config set.");
+  if (availableCommands.length > 0) {
+    console.log(
+      `    Detected available commands: ${availableCommands.join(", ")}`
+    );
+  } else {
+    console.log("    No codex, claude, or gemini analyzer command was detected on PATH.");
+  }
+  console.log("    Configure one with:");
+  printAiConfigureCommands("      ");
+  printDifferentAnalyzerHint("    ");
+  console.log("    Optionally provide a custom command prefix with '-- ...'.");
+}
+function registerInitCommand(yargs) {
+  return yargs.command(
+    "init",
+    "Initialize libretto in the current project",
+    (cmd) => cmd.option("skip-browsers", {
+      type: "boolean",
+      default: false,
+      describe: "Skip Playwright Chromium installation"
+    }),
+    (argv) => {
+      console.log("Initializing libretto...\n");
+      if (!argv["skip-browsers"]) {
+        installBrowsers();
+      } else {
+        console.log("\nSkipping browser installation (--skip-browsers)");
+      }
+      checkAiRuntimeConfiguration();
+      console.log("\n\u2713 libretto init complete");
+    }
+  );
+}
+export {
+  registerInitCommand
+};