libretto 0.5.0 → 0.5.2

package/src/runtime/recovery/errors.ts

@@ -1,5 +1,8 @@
 import type { Page } from "playwright";
-import { type MinimalLogger, defaultLogger } from "../../shared/logger/logger.js";
+import {
+  type MinimalLogger,
+  defaultLogger,
+} from "../../shared/logger/logger.js";
 import type { LLMClient } from "../../shared/llm/types.js";
 import { z } from "zod";
 
@@ -9,27 +12,27 @@ import { z } from "zod";
  * userMessage is the friendly message returned when matched.
  */
 export type KnownSubmissionError = {
-	id: string;
-	errorPatterns: string[];
-	userMessage: string;
+  id: string;
+  errorPatterns: string[];
+  userMessage: string;
 };
 
 export type DetectedSubmissionError = {
-	matched: true;
-	errorId: string;
-	message: string;
+  matched: true;
+  errorId: string;
+  message: string;
 };
 
 const detectSubmissionErrorSchema = z.object({
-	hasError: z.boolean().describe("Whether an error is visible on the page"),
-	matchedKnownErrorId: z
-		.string()
-		.nullable()
-		.describe("The ID of the matched known error, or null if no match"),
-	errorMessage: z
-		.string()
-		.nullable()
-		.describe("The error message visible on screen, or null if no error"),
+  hasError: z.boolean().describe("Whether an error is visible on the page"),
+  matchedKnownErrorId: z
+    .string()
+    .nullable()
+    .describe("The ID of the matched known error, or null if no match"),
+  errorMessage: z
+    .string()
+    .nullable()
+    .describe("The error message visible on screen, or null if no error"),
 });
 
 /**
@@ -41,52 +44,52 @@ const detectSubmissionErrorSchema = z.object({
  * @throws The original error if no known error matches
  */
 export async function detectSubmissionError(
-	page: Page,
-	error: unknown,
-	logContext: string,
-	llmClient: LLMClient,
-	knownErrors: KnownSubmissionError[] = [],
-	logger?: MinimalLogger,
+  page: Page,
+  error: unknown,
+  logContext: string,
+  llmClient: LLMClient,
+  knownErrors: KnownSubmissionError[] = [],
+  logger?: MinimalLogger,
 ): Promise<DetectedSubmissionError> {
-	const log = logger ?? defaultLogger;
-	// Capture screenshot using CDP to handle unresponsive pages
-	let screenshot: string;
-	let domSnapshot: string | undefined;
-
-	try {
-		const cdpClient = await page.context().newCDPSession(page);
-		await cdpClient.send("Page.enable");
-		const { data } = await cdpClient.send("Page.captureScreenshot", {
-			format: "png",
-		});
-		screenshot = data;
-	} catch (screenshotError) {
-		log.warn(
-			"Failed to take screenshot via CDP for error detection, skipping LLM analysis",
-			{ screenshotError, originalError: error },
-		);
-		throw error;
-	}
-
-	// Capture DOM snapshot for additional context
-	try {
-		const htmlContent = await page.content();
-		domSnapshot =
-			htmlContent.length > 50000
-				? htmlContent.slice(0, 50000) + "\n... [truncated]"
-				: htmlContent;
-	} catch (domError) {
-		log.warn("Failed to capture DOM snapshot", {
-			domError: domError instanceof Error ? domError.message : String(domError),
-		});
-	}
-
-	const knownErrorsDescription =
-		knownErrors.length > 0
-			? `\nKnown error patterns to look for:\n${knownErrors.map((e, i) => `${i + 1}. ID: "${e.id}" - Patterns: ${e.errorPatterns.join(", ")}`).join("\n")}\n`
-			: "";
-
-	const prompt = `You are analyzing a screenshot and DOM of a web page to detect if an error occurred during a browser automation process.
+  const log = logger ?? defaultLogger;
+  // Capture screenshot using CDP to handle unresponsive pages
+  let screenshot: string;
+  let domSnapshot: string | undefined;
+
+  try {
+    const cdpClient = await page.context().newCDPSession(page);
+    await cdpClient.send("Page.enable");
+    const { data } = await cdpClient.send("Page.captureScreenshot", {
+      format: "png",
+    });
+    screenshot = data;
+  } catch (screenshotError) {
+    log.warn(
+      "Failed to take screenshot via CDP for error detection, skipping LLM analysis",
+      { screenshotError, originalError: error },
+    );
+    throw error;
+  }
+
+  // Capture DOM snapshot for additional context
+  try {
+    const htmlContent = await page.content();
+    domSnapshot =
+      htmlContent.length > 50000
+        ? htmlContent.slice(0, 50000) + "\n... [truncated]"
+        : htmlContent;
+  } catch (domError) {
+    log.warn("Failed to capture DOM snapshot", {
+      domError: domError instanceof Error ? domError.message : String(domError),
+    });
+  }
+
+  const knownErrorsDescription =
+    knownErrors.length > 0
+      ? `\nKnown error patterns to look for:\n${knownErrors.map((e, i) => `${i + 1}. ID: "${e.id}" - Patterns: ${e.errorPatterns.join(", ")}`).join("\n")}\n`
+      : "";
+
+  const prompt = `You are analyzing a screenshot and DOM of a web page to detect if an error occurred during a browser automation process.
 
 Context: ${logContext}
 
@@ -106,47 +109,47 @@ IMPORTANT:
 
 ${domSnapshot ? `<dom_snapshot>\n${domSnapshot}\n</dom_snapshot>` : ""}`;
 
-	const result = await llmClient.generateObjectFromMessages({
-		schema: detectSubmissionErrorSchema,
-		messages: [
-			{
-				role: "user",
-				content: [
-					{ type: "text", text: prompt },
-					{ type: "image", image: `data:image/png;base64,${screenshot}` },
-				],
-			},
-		],
-		temperature: 0,
-	});
-
-	if (!result.hasError) {
-		log.info("No error detected by LLM", { result });
-	}
-
-	// Check if it matches a known error
-	if (result.matchedKnownErrorId) {
-		const knownError = knownErrors.find(
-			(e) => e.id === result.matchedKnownErrorId,
-		);
-		if (knownError) {
-			log.warn(logContext, {
-				error,
-				browserError: result.errorMessage,
-				knownErrorId: result.matchedKnownErrorId,
-			});
-			return {
-				matched: true,
-				errorId: knownError.id,
-				message: knownError.userMessage,
-			};
-		}
-	}
-
-	// Log and re-throw for unknown errors
-	log.warn(logContext, {
-		error,
-		browserError: result.errorMessage,
-	});
-	throw error;
+  const result = await llmClient.generateObjectFromMessages({
+    schema: detectSubmissionErrorSchema,
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: prompt },
+          { type: "image", image: `data:image/png;base64,${screenshot}` },
+        ],
+      },
+    ],
+    temperature: 0,
+  });
+
+  if (!result.hasError) {
+    log.info("No error detected by LLM", { result });
+  }
+
+  // Check if it matches a known error
+  if (result.matchedKnownErrorId) {
+    const knownError = knownErrors.find(
+      (e) => e.id === result.matchedKnownErrorId,
+    );
+    if (knownError) {
+      log.warn(logContext, {
+        error,
+        browserError: result.errorMessage,
+        knownErrorId: result.matchedKnownErrorId,
+      });
+      return {
+        matched: true,
+        errorId: knownError.id,
+        message: knownError.userMessage,
+      };
+    }
+  }
+
+  // Log and re-throw for unknown errors
+  log.warn(logContext, {
+    error,
+    browserError: result.errorMessage,
+  });
+  throw error;
 }

package/src/runtime/recovery/index.ts

@@ -1,7 +1,7 @@
 export { executeRecoveryAgent } from "./agent.js";
 export { attemptWithRecovery } from "./recovery.js";
 export {
-	detectSubmissionError,
-	type KnownSubmissionError,
-	type DetectedSubmissionError,
+  detectSubmissionError,
+  type KnownSubmissionError,
+  type DetectedSubmissionError,
 } from "./errors.js";

package/src/runtime/recovery/recovery.ts

@@ -1,5 +1,8 @@
 import type { Page } from "playwright";
-import { type MinimalLogger, defaultLogger } from "../../shared/logger/logger.js";
+import {
+  type MinimalLogger,
+  defaultLogger,
+} from "../../shared/logger/logger.js";
 import type { LLMClient } from "../../shared/llm/types.js";
 import { executeRecoveryAgent } from "./agent.js";
 
@@ -8,43 +11,43 @@ import { executeRecoveryAgent } from "./agent.js";
  * (if an LLM client is provided) and retries the function once.
  */
 export async function attemptWithRecovery<T>(
-	page: Page,
-	fn: () => Promise<T>,
-	logger?: MinimalLogger,
-	llmClient?: LLMClient,
+  page: Page,
+  fn: () => Promise<T>,
+  logger?: MinimalLogger,
+  llmClient?: LLMClient,
 ): Promise<T> {
-	const log = logger ?? defaultLogger;
-	try {
-		return await fn();
-	} catch (error) {
-		// Don't attempt recovery if the browser/page is closed
-		if (
-			error instanceof Error &&
-			(error.message.includes("Target closed") ||
-				error.message.includes("browser has been closed") ||
-				error.message.includes("context or browser has been closed"))
-		) {
-			log.warn("Page/browser has been closed, cannot recover", {
-				error: error.message,
-			});
-			throw error;
-		}
+  const log = logger ?? defaultLogger;
+  try {
+    return await fn();
+  } catch (error) {
+    // Don't attempt recovery if the browser/page is closed
+    if (
+      error instanceof Error &&
+      (error.message.includes("Target closed") ||
+        error.message.includes("browser has been closed") ||
+        error.message.includes("context or browser has been closed"))
+    ) {
+      log.warn("Page/browser has been closed, cannot recover", {
+        error: error.message,
+      });
+      throw error;
+    }
 
-		if (!llmClient) {
-			throw error;
-		}
+    if (!llmClient) {
+      throw error;
+    }
 
-		log.info("Action failed, attempting popup recovery", {
-			error: error instanceof Error ? error.message : String(error),
-		});
+    log.info("Action failed, attempting popup recovery", {
+      error: error instanceof Error ? error.message : String(error),
+    });
 
-		await executeRecoveryAgent(
-			page,
-			"Look at the page to see if there is a popup blocking the screen. If so, close the popup.",
-			log,
-			llmClient,
-		);
+    await executeRecoveryAgent(
+      page,
+      "Look at the page to see if there is a popup blocking the screen. If so, close the popup.",
+      log,
+      llmClient,
+    );
 
-		return await fn();
-	}
+    return await fn();
+  }
 }

package/src/shared/condense-dom/condense-dom.ts

@@ -20,6 +20,14 @@
  *  12.  Whitespace — collapse (preserve <pre> content)
  */
 
+import {
+  filterSemanticClasses,
+  INTERACTIVE_ROLE_NAMES,
+  INTERACTIVE_TAG_NAMES,
+  TEST_ATTRIBUTE_NAMES,
+  TRUSTED_ATTRIBUTE_NAMES,
+} from "../dom-semantics.js";
+
 export type CondenseDomResult = {
   /** The condensed HTML string. Valid, parseable HTML. */
   html: string;
@@ -37,25 +45,8 @@ type ParsedAttribute = {
   value: string | null;
 };
 
-const TEST_ATTRS = new Set(["data-testid", "data-test", "data-qa", "data-cy"]);
-const TRUSTED_ATTRS = new Set([
-  "id",
-  "name",
-  "for",
-  "tabindex",
-  "contenteditable",
-  "role",
-  "title",
-  "alt",
-  "type",
-  "value",
-  "placeholder",
-  "autocomplete",
-  "href",
-  "action",
-  "method",
-  "src",
-]);
+const TEST_ATTRS: Set<string> = new Set(TEST_ATTRIBUTE_NAMES);
+const TRUSTED_ATTRS: Set<string> = new Set(TRUSTED_ATTRIBUTE_NAMES);
 const STATE_ATTRS = new Set([
   "disabled",
   "hidden",
@@ -67,12 +58,7 @@ const STATE_ATTRS = new Set([
   "open",
   "multiple",
 ]);
-const BOOLEAN_ATTRS = new Set([
-  ...STATE_ATTRS,
-  "async",
-  "defer",
-  "nomodule",
-]);
+const BOOLEAN_ATTRS = new Set([...STATE_ATTRS, "async", "defer", "nomodule"]);
 const EMPTY_VALUE_DROP_ATTRS = new Set([
   "alt",
   "autocomplete",
@@ -99,28 +85,8 @@ const SCRIPT_ATTRS = new Set([
   "referrerpolicy",
 ]);
 const STYLE_TAG_ATTRS = new Set(["media", "type", "nonce", "title"]);
-const INTERACTIVE_TAGS = new Set([
-  "a",
-  "button",
-  "input",
-  "select",
-  "textarea",
-  "form",
-  "details",
-  "dialog",
-  "label",
-]);
-const INTERACTIVE_ROLES = new Set([
-  "button",
-  "link",
-  "tab",
-  "menuitem",
-  "checkbox",
-  "radio",
-  "switch",
-  "slider",
-  "combobox",
-]);
+const INTERACTIVE_TAGS: Set<string> = new Set(INTERACTIVE_TAG_NAMES);
+const INTERACTIVE_ROLES: Set<string> = new Set(INTERACTIVE_ROLE_NAMES);
 const OPEN_TAG_PATTERN =
   /<([a-zA-Z][\w:-]*)(\s(?:[^"'<>/]|"[^"]*"|'[^']*')*)?\s*(\/?)>/g;
 
@@ -232,12 +198,8 @@ export function condenseDom(html: string): CondenseDomResult {
 
             const hasAriaLabel = /aria-label\s*=/i.test(attrs);
             if (!hasAriaLabel) {
-              const titleMatch = inner.match(
-                /<title[^>]*>([^<]+)<\/title>/i,
-              );
-              const descMatch = inner.match(
-                /<desc[^>]*>([^<]+)<\/desc>/i,
-              );
+              const titleMatch = inner.match(/<title[^>]*>([^<]+)<\/title>/i);
+              const descMatch = inner.match(/<desc[^>]*>([^<]+)<\/desc>/i);
               const labelText =
                 titleMatch?.[1]?.trim() || descMatch?.[1]?.trim();
               if (labelText) {
@@ -342,7 +304,12 @@ export function condenseDom(html: string): CondenseDomResult {
 function rewriteTagAttributes(html: string): string {
   return html.replace(
     OPEN_TAG_PATTERN,
-    (match, rawTagName: string, rawAttrs: string | undefined, selfClosing: string) => {
+    (
+      match,
+      rawTagName: string,
+      rawAttrs: string | undefined,
+      selfClosing: string,
+    ) => {
       const tagName = rawTagName.toLowerCase();
       if (!rawAttrs?.trim()) return match;
 
@@ -431,10 +398,7 @@ function serializePreservedAttribute(attr: ParsedAttribute): string | null {
   return attr.rawToken;
 }
 
-function shouldDropEmptyValue(
-  name: string,
-  value: string | null,
-): boolean {
+function shouldDropEmptyValue(name: string, value: string | null): boolean {
   if (value === null) return false;
   if (value.trim()) return false;
   if (name.startsWith("aria-")) return true;
@@ -465,29 +429,6 @@ function normalizeUrlValue(value: string): string {
   }
 }
 
-function filterSemanticClasses(value: string): string {
-  const classes = value.split(/\s+/).filter(Boolean);
-  const kept = classes.filter((cls) => !isObfuscatedClass(cls));
-  return kept.join(" ");
-}
-
-/**
- * Heuristic: a class name is "obfuscated" if it looks like a hash or random ID
- * rather than a human-readable semantic name.
- */
-function isObfuscatedClass(cls: string): boolean {
-  if (cls.length > 80) return true;
-  if (/^_?[0-9a-f]{6,}$/i.test(cls)) return true;
-  if (/^[a-z]+_[0-9a-f]{4,}$/i.test(cls)) return true;
-  if (/^[a-z]{1,2}[0-9]{2,}$/i.test(cls)) return true;
-
-  const digits = (cls.match(/[0-9]/g) || []).length;
-  const letters = (cls.match(/[a-zA-Z]/g) || []).length;
-  if (cls.length >= 6 && digits >= letters * 0.5 && digits >= 2) return true;
-
-  return false;
-}
-
 function parseAttributes(rawAttrs: string): ParsedAttribute[] {
   const attrs: ParsedAttribute[] = [];
   const attrPattern =
@@ -550,7 +491,11 @@ function shouldKeepCustomDataAttribute(
 function looksMeaningfulToken(value: string): boolean {
   if (!/^[a-z][a-z0-9-]{1,40}$/i.test(value)) return false;
   if (!/[a-z]{3}/i.test(value)) return false;
-  if (/(track|metric|telemetry|analytics|component|display|loaded|token|dps|color|screen|strict|rehydr|fetch)/i.test(value)) {
+  if (
+    /(track|metric|telemetry|analytics|component|display|loaded|token|dps|color|screen|strict|rehydr|fetch)/i.test(
+      value,
+    )
+  ) {
     return false;
   }
   return true;

package/src/shared/config/config.ts

@@ -1,22 +1,3 @@
 /**
  * Runtime configuration for libretto.
- *
- * Values are derived from environment variables only.
  */
-
-export function isDebugMode(): boolean {
-	return process.env.LIBRETTO_DEBUG === "true";
-}
-
-export function isDryRun(): boolean {
-	const explicit = process.env.LIBRETTO_DRY_RUN;
-	if (explicit !== undefined) {
-		return explicit === "true";
-	}
-
-	return process.env.NODE_ENV === "development";
-}
-
-export function shouldPauseBeforeMutation(): boolean {
-	return isDryRun() && isDebugMode();
-}

package/src/shared/config/index.ts

@@ -1,5 +0,0 @@
-export {
-	isDebugMode,
-	isDryRun,
-	shouldPauseBeforeMutation,
-} from "./config.js";

package/src/shared/debug/pause.ts

@@ -1,37 +1,43 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { getSessionDir } from "../../cli/core/context.js";
-import { getPauseSignalPaths, removeSignalIfExists } from "../../cli/core/pause-signals.js";
-import { listSessionsWithStateFile, readSessionState } from "../../cli/core/session.js";
+import {
+  getPauseSignalPaths,
+  removeSignalIfExists,
+} from "../../cli/core/pause-signals.js";
+import {
+  listSessionsWithStateFile,
+  readSessionState,
+} from "../../cli/core/session.js";
 
 function isPidRunning(pid: number): boolean {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch {
-		return false;
-	}
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function getRunningSessions(): string[] {
-	return listSessionsWithStateFile().filter((candidate) => {
-		const state = readSessionState(candidate);
-		return state !== null && isPidRunning(state.pid);
-	});
+  return listSessionsWithStateFile().filter((candidate) => {
+    const state = readSessionState(candidate);
+    return state !== null && state.pid != null && isPidRunning(state.pid);
+  });
 }
 
 function throwMissingSessionError(): never {
-	const runningSessions = getRunningSessions();
-	const lines = ["pause(session) requires a non-empty session ID."];
+  const runningSessions = getRunningSessions();
+  const lines = ["pause(session) requires a non-empty session ID."];
 
-	if (runningSessions.length > 0) {
-		lines.push("", "Running sessions:");
-		for (const runningSession of runningSessions) {
-			lines.push(`  ${runningSession}`);
-		}
-	}
+  if (runningSessions.length > 0) {
+    lines.push("", "Running sessions:");
+    for (const runningSession of runningSessions) {
+      lines.push(`  ${runningSession}`);
+    }
+  }
 
-	throw new Error(lines.join("\n"));
+  throw new Error(lines.join("\n"));
 }
 
 /**
@@ -44,42 +50,42 @@ function throwMissingSessionError(): never {
  * Import directly: `import { pause } from "libretto";`
  */
 export async function pause(session: string): Promise<void> {
-	if (process.env.NODE_ENV === "production") {
-		return;
-	}
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
 
-	if (typeof session !== "string" || session.trim().length === 0) {
-		throwMissingSessionError();
-	}
+  if (typeof session !== "string" || session.trim().length === 0) {
+    throwMissingSessionError();
+  }
 
-	const signalPaths = getPauseSignalPaths(session);
-	const { pausedSignalPath, resumeSignalPath } = signalPaths;
+  const signalPaths = getPauseSignalPaths(session);
+  const { pausedSignalPath, resumeSignalPath } = signalPaths;
 
-	await mkdir(getSessionDir(session), { recursive: true });
-	await removeSignalIfExists(resumeSignalPath);
+  await mkdir(getSessionDir(session), { recursive: true });
+  await removeSignalIfExists(resumeSignalPath);
 
-	const details = {
-		sessionName: session,
-		pausedAt: new Date().toISOString(),
-		url: "unknown",
-	};
+  const details = {
+    sessionName: session,
+    pausedAt: new Date().toISOString(),
+    url: "unknown",
+  };
 
-	// Try to read the current page URL from the process (best-effort).
-	// The standalone pause doesn't have access to the page object,
-	// so we just record what we can.
-	await writeFile(pausedSignalPath, JSON.stringify(details, null, 2), "utf8");
+  // Try to read the current page URL from the process (best-effort).
+  // The standalone pause doesn't have access to the page object,
+  // so we just record what we can.
+  await writeFile(pausedSignalPath, JSON.stringify(details, null, 2), "utf8");
 
-	console.log(`[pause] Paused (session: ${session})`);
-	console.log("[pause] Waiting for resume signal...");
+  console.log(`[pause] Paused (session: ${session})`);
+  console.log("[pause] Waiting for resume signal...");
 
-	const RESUME_POLL_INTERVAL_MS = 250;
-	while (!existsSync(resumeSignalPath)) {
-		await new Promise((resolve) =>
-			setTimeout(resolve, RESUME_POLL_INTERVAL_MS),
-		);
-	}
+  const RESUME_POLL_INTERVAL_MS = 250;
+  while (!existsSync(resumeSignalPath)) {
+    await new Promise((resolve) =>
+      setTimeout(resolve, RESUME_POLL_INTERVAL_MS),
+    );
+  }
 
-	await removeSignalIfExists(resumeSignalPath);
-	await removeSignalIfExists(pausedSignalPath);
-	console.log("[pause] Resume signal received. Continuing workflow...");
+  await removeSignalIfExists(resumeSignalPath);
+  await removeSignalIfExists(pausedSignalPath);
+  console.log("[pause] Resume signal received. Continuing workflow...");
 }