libretto 0.2.0 → 0.2.2

package/skill/integration-approach-selection.md

@@ -0,0 +1,174 @@
+# Integration Approach Selection Guide
+
+**Purpose:** You are connected to a live Chrome session on a target website. Your job is to probe the site for bot detection measures, assess its security posture, and determine the best integration strategy for data extraction. All strategies use Playwright for browser control — the question is what to **prioritize** for data capture: in-browser fetch calls, passive network interception, or DOM extraction.
+
+After completing the probes below, produce a **Site Assessment Summary** (see the output format at the end of this document).
+
+---
+
+## Probing the Site
+
+Run these probes to build a picture of the site's detection posture. The examples below are starting points — use your judgment to investigate further based on what you find. Sites may use detection methods not listed here.
+
+### Probe 1: Bot Protection Services & Security Signals
+
+Look for signs that the site uses bot protection — either a third-party service or custom detection. There is no complete list of indicators; these are common examples.
+
+**Cookies to look for (examples, not exhaustive):**
+
+| Cookie Pattern | Associated Service |
+|---|---|
+| `_abck` | Akamai Bot Manager |
+| `_px*` | PerimeterX (HUMAN) |
+| `datadome` | DataDome |
+| `cf_clearance` | Cloudflare |
+| `_imp_apg_r_*` | Shape Security (F5) |
+| `x-kpsdk-*` | Kasada |
+
+But don't just check this list. Examine **all** cookies on the page — look for any cookies with obfuscated names, telemetry-related prefixes, or values that look like fingerprint hashes or encrypted tokens. Unknown security cookies are still security cookies.
+
+**Global variables to check (examples):**
+
+```js
+// Known telemetry globals — but probe broadly, not just these
+window._pxAppId   // PerimeterX
+window.bmak       // Akamai
+window.ddjskey    // DataDome
+```
+
+Also examine the page's scripts: look at the first `<script>` tags in the document source, check what external domains scripts load from (e.g., `*.akamaized.net`, `*.perimeterx.net`, `*.datadome.co`, `*.kasada.io`). Bot protection scripts are typically injected before any application code.
+
+**Challenge pages:**
+
+Check if the page is showing a challenge or interstitial instead of real content — "Checking your browser...", CAPTCHA iframes, blank pages with only a spinner. These indicate active bot protection that has already been triggered.
+
+**General guidance:** The goal is to determine whether the site has bot protection and roughly how aggressive it is. Don't limit yourself to known signatures — look at the overall page behavior, unusual scripts, and anything that seems like security telemetry.
+
+### Probe 2: Fetch / XHR Interception
+
+Check whether the site has monkey-patched `window.fetch` or `XMLHttpRequest`. If it has, making your own fetch calls from `page.evaluate()` is risky because the site can inspect call stacks and detect calls that don't originate from its own code.
+
+```js
+// Check if fetch has been wrapped
+window.fetch.toString()
+// Native: "function fetch() { [native code] }"
+// Patched: shows actual JavaScript source
+
+// Check XMLHttpRequest
+XMLHttpRequest.prototype.open.toString()
+
+// Check property descriptors for tampering
+Object.getOwnPropertyDescriptor(window, 'fetch')
+// Normal: { value: ƒ, writable: true, enumerable: true, configurable: true }
+
+// Proxy-based wrapping is harder to detect — native fetch has no prototype
+window.fetch.hasOwnProperty('prototype')  // true may indicate a Proxy wrapper
+```
+
+**Important:** Some sites use `Proxy` to wrap fetch, which makes `toString()` still return `"[native code]"`. The prototype check is a heuristic, not definitive. If you see any sign of fetch interception, treat it as patched.
+
+### Probe 3: Behavioral Monitoring
+
+Look for signs that the site collects behavioral telemetry (mouse movements, keystrokes, scroll patterns). Heavy monitoring means you should use natural, human-like interaction patterns when driving the UI.
+
+Things to check:
+- Unusually large numbers of event listeners on `document` or `body` for `mousemove`, `keydown`, `scroll`, `touchstart`, `click`
+- Known telemetry collection scripts
+- `MutationObserver` instances watching the DOM for injected elements
+- `requestAnimationFrame` loops that aren't tied to visible animations
+
+If you're in a DevTools context, `getEventListeners(document)` is the quickest way to assess this. Otherwise, use heuristics — heavy behavioral monitoring usually correlates with enterprise bot protection from Probe 1.
+
+---
+
+## Choosing a Data Capture Strategy
+
+Every integration uses Playwright to control the browser. The question is what to **prioritize** for getting data out. In practice, most integrations use a mix — you'll always need some Playwright interaction for navigation, login flows, cookie consent, etc. The strategies below describe what to lean on for the core data extraction.
+
+### Strategy A: Prioritize `page.evaluate(fetch(...))`
+
+Make fetch calls directly from within the browser's JavaScript context. The requests share the browser's TLS fingerprint, cookies, and origin — they look identical to requests the site's own JS would make.
+
+**When to prioritize this:**
+- No enterprise bot protection detected
+- `fetch` is NOT monkey-patched
+- You've identified API endpoints that return the data you need
+- You need data that requires many API calls (deep pagination, bulk queries) where driving the UI would be slow
+
+**Why:** Maximum control and efficiency. You call exactly the endpoints you want with the parameters you want, skip UI rendering, and get structured JSON back. On sites without aggressive detection, this is the fastest and cleanest approach.
+
+**Risk:** If the site monitors fetch call stacks (Layer 4 detection), your calls will be flagged because they don't originate from the site's bundled code. This is uncommon but exists on high-security sites.
+
+**You'll still use Playwright for:** Initial navigation, login/auth flows, cookie consent, and any UI interactions needed to establish session state before making fetch calls.
+
+### Strategy B: Prioritize `page.on('response', ...)` (Passive Interception)
+
+Listen to network responses that the browser naturally makes as you navigate. You don't make any extra requests — you capture data flowing through the site's own API calls.
+
+**When to prioritize this:**
+- Enterprise bot protection is detected
+- `fetch` IS monkey-patched
+- The site's normal UI flow triggers API calls that return the data you need
+- You want to minimize detection risk as much as possible
+
+**Why:** Zero additional network risk. The requests that happen are the ones the site's own code triggers. You're just listening. No anomalous call stacks, no unexpected request patterns, no extra fetch calls for monitoring to flag.
+
+**Trade-off:** You only get data the page naturally loads. If you need page 50 of results, you have to click "next" 49 times via Playwright. You must set up listeners before the navigation that triggers the requests.
+
+**You'll still use Playwright for:** All navigation and interaction to trigger the data-bearing API calls, plus any data that isn't available via intercepted responses (DOM-only content).
+
+### Strategy C: Prioritize Playwright DOM Extraction
+
+Extract data directly from the rendered page using selectors and `page.evaluate()` to read DOM content.
+
+**When to prioritize this:**
+- Data is server-rendered (no JSON API calls observed)
+- The site doesn't expose the data you need via any API
+- You need visual/layout information that only exists in the DOM
+- As a fallback when Strategies A and B can't get specific pieces of data
+
+**Why:** Works regardless of the site's API architecture. If the data is visible on the page, you can extract it.
+
+**Trade-off:** Slower, fragile against DOM changes, and you only get data the UI renders (which may be less than what API responses contain).
+
+---
+
+## Decision Summary
+
+| Site Profile | Primary Strategy | Supplement With |
+|---|---|---|
+| No bot protection, fetch not patched | **A** (`page.evaluate(fetch)`) | Playwright for navigation/auth |
+| No bot protection, fetch IS patched | **B** (`page.onResponse`) | Playwright for navigation; DOM extraction as fallback |
+| Bot protection detected, fetch not patched | **B** (`page.onResponse`) | Playwright for all navigation; cautious use of `page.evaluate(fetch)` only if needed |
+| Bot protection detected, fetch IS patched | **B** (`page.onResponse`) | Playwright for all navigation; DOM extraction as fallback |
+| Server-rendered content (no API calls) | **C** (DOM extraction) | Playwright for all interaction |
+
+---
+
+## Output: Site Assessment Summary
+
+After running the probes, produce a summary in this format. **Do NOT include a final strategy recommendation.** The security assessment determines what's *safe to use*, not what will *work*. Present this to the user for input, then use the safe approaches as you build the integration — adapting if specific endpoints don't work as expected (see "Handling Approach Mismatches" in SKILL.md).
+
+```
+## Site Assessment: [site URL]
+
+### Bot Detection Profile
+- **Enterprise bot protection:** [None detected / Detected — describe what you found (service name if identifiable, cookies, scripts, telemetry globals)]
+- **Fetch/XHR interception:** [Native (not patched) / Patched — describe what you found]
+- **Behavioral monitoring:** [None detected / Light / Heavy — describe indicators]
+- **Challenge pages:** [None / Present — describe type (CAPTCHA, interstitial, etc.)]
+- **Overall security posture:** [None / Low / Moderate / High / Very High]
+
+### API Surface
+- **API calls observed:** [List key endpoints discovered, or "None — content appears server-rendered"]
+- **Data format:** [JSON / GraphQL / HTML fragments / Other — note if any responses use proprietary/binary formats]
+- **Pagination:** [Describe how pagination works if applicable]
+
+### Safe Approaches
+- **`page.evaluate(fetch(...))`:** [Safe / Unsafe — brief rationale based on fetch patching, bot detection, etc.]
+- **`page.on('response', ...)`:** [Viable / Not viable — note if response formats are parseable or proprietary]
+- **DOM extraction:** [Always available as fallback]
+- **Interaction notes:** [any behavioral precautions — natural mouse movements, typing delays, etc.]
+```
+
+**Important:** This assessment tells you which tools are in your toolbox. Present it to the user, get their input, then start building the integration using the safe approaches.

package/dist/runtime/step/index.cjs

@@ -1,31 +0,0 @@
-"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, {
-  createRunner: () => import_runner.createRunner,
-  step: () => import_step.step
-});
-module.exports = __toCommonJS(step_exports);
-var import_step = require("./step.js");
-var import_runner = require("./runner.js");
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createRunner,
-  step
-});

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

@@ -1,7 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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

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

package/dist/runtime/step/runner.cjs

@@ -1,208 +0,0 @@
-"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

@@ -1,16 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,187 +0,0 @@
-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
-};