libretto 0.1.5 → 0.2.0

package/dist/runtime/step/index.d.cts

@@ -0,0 +1,7 @@
+export { step } from './step.cjs';
+export { Runner, createRunner } from './runner.cjs';
+export { DebugBundle, RecoveryHandler, RunnerConfig, Step, StepContext, StepHandler, StepHistoryEntry, StepOptions } from './types.cjs';
+import 'playwright';
+import '../../shared/logger/logger.cjs';
+import '../../shared/llm/types.cjs';
+import 'zod';

package/dist/runtime/step/index.d.ts

@@ -0,0 +1,7 @@
+export { step } from './step.js';
+export { Runner, createRunner } from './runner.js';
+export { DebugBundle, RecoveryHandler, RunnerConfig, Step, StepContext, StepHandler, StepHistoryEntry, StepOptions } from './types.js';
+import 'playwright';
+import '../../shared/logger/logger.js';
+import '../../shared/llm/types.js';
+import 'zod';

package/dist/runtime/step/index.js

@@ -0,0 +1,6 @@
+import { step } from "./step.js";
+import { createRunner } from "./runner.js";
+export {
+  createRunner,
+  step
+};

package/dist/runtime/step/runner.cjs

@@ -0,0 +1,208 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var runner_exports = {};
+__export(runner_exports, {
+  createRunner: () => createRunner
+});
+module.exports = __toCommonJS(runner_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var import_logger = require("../../shared/logger/logger.js");
+var import_sinks = require("../../shared/logger/sinks.js");
+var import_config = require("../../shared/config/config.js");
+var import_pause = require("../../shared/debug/pause.js");
+var import_recovery = require("../recovery/recovery.js");
+var import_paths = require("../../shared/paths/paths.js");
+function createRunner(config = {}) {
+  const {
+    llmClient,
+    dryRun: dryRunOption,
+    debug: debugOption,
+    sessionName = "libretto",
+    logDir: configuredLogDir
+  } = config;
+  const dryRun = dryRunOption ?? (0, import_config.isDryRun)();
+  const debug = debugOption ?? false;
+  const logDir = configuredLogDir ?? (0, import_paths.ensureLibrettoRunnerLogDir)(sessionName);
+  return {
+    run: async (page, steps) => {
+      (0, import_node_fs.mkdirSync)(logDir, { recursive: true });
+      const logPath = (0, import_paths.getRunnerLogPathForDir)(logDir);
+      const logger = new import_logger.Logger().withSink((0, import_sinks.createFileLogSink)({ filePath: logPath })).withSink(import_sinks.prettyConsoleSink);
+      const stepHistory = [];
+      logger.info("runner:start", {
+        totalSteps: steps.length,
+        dryRun,
+        debug,
+        logDir
+      });
+      for (const step of steps) {
+        const stepLogger = logger.withScope(`step:${step.name}`);
+        const startTime = Date.now();
+        if (dryRun && step.options.dryRun !== "execute") {
+          if (step.options.dryRun === "skip") {
+            stepLogger.info("skipped (dry-run)");
+            stepHistory.push({
+              name: step.name,
+              status: "skipped",
+              duration: 0
+            });
+            continue;
+          }
+          if (step.options.dryRun === "simulate" && step.options.simulate) {
+            stepLogger.info("simulating (dry-run)");
+            try {
+              await step.options.simulate({ logger: stepLogger });
+            } catch (simError) {
+              stepLogger.warn("simulate failed", { error: simError });
+            }
+            stepHistory.push({
+              name: step.name,
+              status: "simulated",
+              duration: Date.now() - startTime
+            });
+            continue;
+          }
+          stepLogger.info("skipped (dry-run, no simulate fn)");
+          stepHistory.push({
+            name: step.name,
+            status: "skipped",
+            duration: 0
+          });
+          continue;
+        }
+        await captureScreenshot(page, (0, import_node_path.join)(logDir, `${step.name}-start.png`), stepLogger);
+        stepLogger.info("start");
+        try {
+          await (0, import_recovery.attemptWithRecovery)(
+            page,
+            () => step.handler({ page, logger: stepLogger, config: { dryRun, debug, logDir } }),
+            stepLogger,
+            llmClient
+          );
+          stepHistory.push({
+            name: step.name,
+            status: "completed",
+            duration: Date.now() - startTime
+          });
+          stepLogger.info("end", { status: "completed", duration: Date.now() - startTime });
+        } catch (firstError) {
+          let recovered = false;
+          const customRecovery = step.options.recovery ?? {};
+          for (const [recoveryName, recoveryHandler] of Object.entries(customRecovery)) {
+            try {
+              stepLogger.info(`trying custom recovery: ${recoveryName}`);
+              await recoveryHandler({ page, logger: stepLogger });
+              await step.handler({ page, logger: stepLogger, config: { dryRun, debug, logDir } });
+              recovered = true;
+              stepHistory.push({
+                name: step.name,
+                status: "completed",
+                duration: Date.now() - startTime
+              });
+              stepLogger.info("end", {
+                status: "completed",
+                recoveredBy: recoveryName,
+                duration: Date.now() - startTime
+              });
+              break;
+            } catch {
+              stepLogger.warn(`custom recovery "${recoveryName}" failed`);
+            }
+          }
+          if (!recovered) {
+            stepHistory.push({
+              name: step.name,
+              status: "failed",
+              duration: Date.now() - startTime
+            });
+            const bundle = await generateDebugBundle(
+              page,
+              step.name,
+              firstError,
+              logDir,
+              logPath,
+              stepHistory,
+              stepLogger
+            );
+            stepLogger.info("step:debug-bundle", { path: bundle.bundlePath });
+            if (debug) {
+              await (0, import_pause.debugPause)({
+                page,
+                session: sessionName
+              });
+            }
+            throw firstError;
+          }
+        }
+        await captureScreenshot(page, (0, import_node_path.join)(logDir, `${step.name}-end.png`), stepLogger);
+      }
+      logger.info("runner:complete", {
+        totalSteps: steps.length,
+        completed: stepHistory.filter((s) => s.status === "completed").length,
+        skipped: stepHistory.filter((s) => s.status === "skipped").length,
+        simulated: stepHistory.filter((s) => s.status === "simulated").length
+      });
+      await logger.close();
+    }
+  };
+}
+async function captureScreenshot(page, filePath, logger) {
+  try {
+    const buffer = await page.screenshot({ fullPage: false, timeout: 5e3 });
+    (0, import_node_fs.writeFileSync)(filePath, buffer);
+  } catch (err) {
+    logger.warn("Failed to capture screenshot", {
+      path: filePath,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+async function generateDebugBundle(page, stepName, error, logDir, logPath, stepHistory, logger) {
+  const screenshotPath = (0, import_node_path.join)(logDir, `${stepName}-error.png`);
+  const domPath = (0, import_node_path.join)(logDir, `${stepName}-error.html`);
+  const bundlePath = (0, import_node_path.join)(logDir, `${stepName}-debug-bundle.json`);
+  await captureScreenshot(page, screenshotPath, logger);
+  try {
+    const html = await page.content();
+    (0, import_node_fs.writeFileSync)(domPath, html);
+  } catch (domErr) {
+    logger.warn("Failed to capture DOM for debug bundle", {
+      error: domErr instanceof Error ? domErr.message : String(domErr)
+    });
+  }
+  const pageUrl = page.isClosed() ? "" : page.url();
+  const bundle = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    step: stepName,
+    error: error instanceof Error ? error.message : String(error),
+    stacktrace: error instanceof Error ? error.stack ?? "" : "",
+    screenshotPath,
+    domPath,
+    logPath,
+    stepHistory,
+    pageUrl
+  };
+  (0, import_node_fs.writeFileSync)(bundlePath, JSON.stringify(bundle, null, 2));
+  return { bundlePath };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRunner
+});

package/dist/runtime/step/runner.d.cts

@@ -0,0 +1,16 @@
+import { Page } from 'playwright';
+import { Step, RunnerConfig } from './types.cjs';
+import '../../shared/logger/logger.cjs';
+import '../../shared/llm/types.cjs';
+import 'zod';
+
+type Runner = {
+    run: (page: Page, steps: Step[]) => Promise<void>;
+};
+/**
+ * Creates a step runner that executes a sequence of steps with logging,
+ * recovery, dry-run support, and debug bundle generation.
+ */
+declare function createRunner(config?: RunnerConfig): Runner;
+
+export { type Runner, createRunner };

package/dist/runtime/step/runner.d.ts

@@ -0,0 +1,16 @@
+import { Page } from 'playwright';
+import { Step, RunnerConfig } from './types.js';
+import '../../shared/logger/logger.js';
+import '../../shared/llm/types.js';
+import 'zod';
+
+type Runner = {
+    run: (page: Page, steps: Step[]) => Promise<void>;
+};
+/**
+ * Creates a step runner that executes a sequence of steps with logging,
+ * recovery, dry-run support, and debug bundle generation.
+ */
+declare function createRunner(config?: RunnerConfig): Runner;
+
+export { type Runner, createRunner };

package/dist/runtime/step/runner.js

@@ -0,0 +1,187 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Logger } from "../../shared/logger/logger.js";
+import { createFileLogSink, prettyConsoleSink } from "../../shared/logger/sinks.js";
+import { isDryRun } from "../../shared/config/config.js";
+import { debugPause } from "../../shared/debug/pause.js";
+import { attemptWithRecovery } from "../recovery/recovery.js";
+import {
+  ensureLibrettoRunnerLogDir,
+  getRunnerLogPathForDir
+} from "../../shared/paths/paths.js";
+function createRunner(config = {}) {
+  const {
+    llmClient,
+    dryRun: dryRunOption,
+    debug: debugOption,
+    sessionName = "libretto",
+    logDir: configuredLogDir
+  } = config;
+  const dryRun = dryRunOption ?? isDryRun();
+  const debug = debugOption ?? false;
+  const logDir = configuredLogDir ?? ensureLibrettoRunnerLogDir(sessionName);
+  return {
+    run: async (page, steps) => {
+      mkdirSync(logDir, { recursive: true });
+      const logPath = getRunnerLogPathForDir(logDir);
+      const logger = new Logger().withSink(createFileLogSink({ filePath: logPath })).withSink(prettyConsoleSink);
+      const stepHistory = [];
+      logger.info("runner:start", {
+        totalSteps: steps.length,
+        dryRun,
+        debug,
+        logDir
+      });
+      for (const step of steps) {
+        const stepLogger = logger.withScope(`step:${step.name}`);
+        const startTime = Date.now();
+        if (dryRun && step.options.dryRun !== "execute") {
+          if (step.options.dryRun === "skip") {
+            stepLogger.info("skipped (dry-run)");
+            stepHistory.push({
+              name: step.name,
+              status: "skipped",
+              duration: 0
+            });
+            continue;
+          }
+          if (step.options.dryRun === "simulate" && step.options.simulate) {
+            stepLogger.info("simulating (dry-run)");
+            try {
+              await step.options.simulate({ logger: stepLogger });
+            } catch (simError) {
+              stepLogger.warn("simulate failed", { error: simError });
+            }
+            stepHistory.push({
+              name: step.name,
+              status: "simulated",
+              duration: Date.now() - startTime
+            });
+            continue;
+          }
+          stepLogger.info("skipped (dry-run, no simulate fn)");
+          stepHistory.push({
+            name: step.name,
+            status: "skipped",
+            duration: 0
+          });
+          continue;
+        }
+        await captureScreenshot(page, join(logDir, `${step.name}-start.png`), stepLogger);
+        stepLogger.info("start");
+        try {
+          await attemptWithRecovery(
+            page,
+            () => step.handler({ page, logger: stepLogger, config: { dryRun, debug, logDir } }),
+            stepLogger,
+            llmClient
+          );
+          stepHistory.push({
+            name: step.name,
+            status: "completed",
+            duration: Date.now() - startTime
+          });
+          stepLogger.info("end", { status: "completed", duration: Date.now() - startTime });
+        } catch (firstError) {
+          let recovered = false;
+          const customRecovery = step.options.recovery ?? {};
+          for (const [recoveryName, recoveryHandler] of Object.entries(customRecovery)) {
+            try {
+              stepLogger.info(`trying custom recovery: ${recoveryName}`);
+              await recoveryHandler({ page, logger: stepLogger });
+              await step.handler({ page, logger: stepLogger, config: { dryRun, debug, logDir } });
+              recovered = true;
+              stepHistory.push({
+                name: step.name,
+                status: "completed",
+                duration: Date.now() - startTime
+              });
+              stepLogger.info("end", {
+                status: "completed",
+                recoveredBy: recoveryName,
+                duration: Date.now() - startTime
+              });
+              break;
+            } catch {
+              stepLogger.warn(`custom recovery "${recoveryName}" failed`);
+            }
+          }
+          if (!recovered) {
+            stepHistory.push({
+              name: step.name,
+              status: "failed",
+              duration: Date.now() - startTime
+            });
+            const bundle = await generateDebugBundle(
+              page,
+              step.name,
+              firstError,
+              logDir,
+              logPath,
+              stepHistory,
+              stepLogger
+            );
+            stepLogger.info("step:debug-bundle", { path: bundle.bundlePath });
+            if (debug) {
+              await debugPause({
+                page,
+                session: sessionName
+              });
+            }
+            throw firstError;
+          }
+        }
+        await captureScreenshot(page, join(logDir, `${step.name}-end.png`), stepLogger);
+      }
+      logger.info("runner:complete", {
+        totalSteps: steps.length,
+        completed: stepHistory.filter((s) => s.status === "completed").length,
+        skipped: stepHistory.filter((s) => s.status === "skipped").length,
+        simulated: stepHistory.filter((s) => s.status === "simulated").length
+      });
+      await logger.close();
+    }
+  };
+}
+async function captureScreenshot(page, filePath, logger) {
+  try {
+    const buffer = await page.screenshot({ fullPage: false, timeout: 5e3 });
+    writeFileSync(filePath, buffer);
+  } catch (err) {
+    logger.warn("Failed to capture screenshot", {
+      path: filePath,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+async function generateDebugBundle(page, stepName, error, logDir, logPath, stepHistory, logger) {
+  const screenshotPath = join(logDir, `${stepName}-error.png`);
+  const domPath = join(logDir, `${stepName}-error.html`);
+  const bundlePath = join(logDir, `${stepName}-debug-bundle.json`);
+  await captureScreenshot(page, screenshotPath, logger);
+  try {
+    const html = await page.content();
+    writeFileSync(domPath, html);
+  } catch (domErr) {
+    logger.warn("Failed to capture DOM for debug bundle", {
+      error: domErr instanceof Error ? domErr.message : String(domErr)
+    });
+  }
+  const pageUrl = page.isClosed() ? "" : page.url();
+  const bundle = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    step: stepName,
+    error: error instanceof Error ? error.message : String(error),
+    stacktrace: error instanceof Error ? error.stack ?? "" : "",
+    screenshotPath,
+    domPath,
+    logPath,
+    stepHistory,
+    pageUrl
+  };
+  writeFileSync(bundlePath, JSON.stringify(bundle, null, 2));
+  return { bundlePath };
+}
+export {
+  createRunner
+};

package/dist/runtime/step/step.cjs

@@ -0,0 +1,67 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var step_exports = {};
+__export(step_exports, {
+  step: () => step
+});
+module.exports = __toCommonJS(step_exports);
+function step(nameOrHandler, handlerOrOptions, maybeOptions) {
+  let name;
+  let handler;
+  let options;
+  if (typeof nameOrHandler === "string") {
+    name = nameOrHandler;
+    handler = handlerOrOptions;
+    options = maybeOptions ?? {};
+  } else {
+    name = `step-${_autoNameCounter++}`;
+    handler = nameOrHandler;
+    options = handlerOrOptions ?? {};
+  }
+  return {
+    name,
+    handler,
+    options: {
+      dryRun: options.dryRun ?? "skip",
+      simulate: options.simulate,
+      recovery: options.recovery
+    }
+  };
+}
+let _autoNameCounter = 1;
+step.extend = function extend(extendOptions) {
+  return function extendedStep(nameOrHandler, handlerOrOptions, maybeOptions) {
+    const baseStep = step(nameOrHandler, handlerOrOptions, maybeOptions);
+    const mergedRecovery = {
+      ...extendOptions.recovery,
+      ...baseStep.options.recovery
+    };
+    return {
+      ...baseStep,
+      options: {
+        ...baseStep.options,
+        recovery: mergedRecovery
+      }
+    };
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  step
+});

package/dist/runtime/step/step.d.cts

@@ -0,0 +1,23 @@
+import { StepHandler, StepOptions, Step, RecoveryHandler } from './types.cjs';
+import 'playwright';
+import '../../shared/logger/logger.cjs';
+import '../../shared/llm/types.cjs';
+import 'zod';
+
+/**
+ * Creates a Step object from a name, handler, and options.
+ *
+ * Usage:
+ *   step("login", async ({ page }) => { ... })
+ *   step("login", async ({ page }) => { ... }, { dryRun: "execute" })
+ *   step(async ({ page }) => { ... })  // auto-named
+ */
+declare function step(nameOrHandler: string | StepHandler, handlerOrOptions?: StepHandler | StepOptions, maybeOptions?: StepOptions): Step;
+declare namespace step {
+    var extend: (extendOptions: ExtendOptions) => (nameOrHandler: string | StepHandler, handlerOrOptions?: StepHandler | StepOptions, maybeOptions?: StepOptions) => Step;
+}
+type ExtendOptions = {
+    recovery: Record<string, RecoveryHandler>;
+};
+
+export { type ExtendOptions, step };

package/dist/runtime/step/step.d.ts

@@ -0,0 +1,23 @@
+import { StepHandler, StepOptions, Step, RecoveryHandler } from './types.js';
+import 'playwright';
+import '../../shared/logger/logger.js';
+import '../../shared/llm/types.js';
+import 'zod';
+
+/**
+ * Creates a Step object from a name, handler, and options.
+ *
+ * Usage:
+ *   step("login", async ({ page }) => { ... })
+ *   step("login", async ({ page }) => { ... }, { dryRun: "execute" })
+ *   step(async ({ page }) => { ... })  // auto-named
+ */
+declare function step(nameOrHandler: string | StepHandler, handlerOrOptions?: StepHandler | StepOptions, maybeOptions?: StepOptions): Step;
+declare namespace step {
+    var extend: (extendOptions: ExtendOptions) => (nameOrHandler: string | StepHandler, handlerOrOptions?: StepHandler | StepOptions, maybeOptions?: StepOptions) => Step;
+}
+type ExtendOptions = {
+    recovery: Record<string, RecoveryHandler>;
+};
+
+export { type ExtendOptions, step };

package/dist/runtime/step/step.js

@@ -0,0 +1,43 @@
+function step(nameOrHandler, handlerOrOptions, maybeOptions) {
+  let name;
+  let handler;
+  let options;
+  if (typeof nameOrHandler === "string") {
+    name = nameOrHandler;
+    handler = handlerOrOptions;
+    options = maybeOptions ?? {};
+  } else {
+    name = `step-${_autoNameCounter++}`;
+    handler = nameOrHandler;
+    options = handlerOrOptions ?? {};
+  }
+  return {
+    name,
+    handler,
+    options: {
+      dryRun: options.dryRun ?? "skip",
+      simulate: options.simulate,
+      recovery: options.recovery
+    }
+  };
+}
+let _autoNameCounter = 1;
+step.extend = function extend(extendOptions) {
+  return function extendedStep(nameOrHandler, handlerOrOptions, maybeOptions) {
+    const baseStep = step(nameOrHandler, handlerOrOptions, maybeOptions);
+    const mergedRecovery = {
+      ...extendOptions.recovery,
+      ...baseStep.options.recovery
+    };
+    return {
+      ...baseStep,
+      options: {
+        ...baseStep.options,
+        recovery: mergedRecovery
+      }
+    };
+  };
+};
+export {
+  step
+};

package/dist/runtime/step/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);