libretto 0.5.3-experimental.5 → 0.5.3

package/src/shared/visualization/highlight.ts

@@ -1,19 +1,19 @@
 import type { Page } from "playwright";
 
 export type HighlightOptions = {
-	color?: string;
-	zIndex?: number;
+  color?: string;
+  zIndex?: number;
 };
 
 const HIGHLIGHT_DEFAULTS = {
-	color: "rgba(59, 130, 246, 0.25)",
-	zIndex: 2147483645,
+  color: "rgba(59, 130, 246, 0.25)",
+  zIndex: 2147483645,
 };
 
 const LAYER_ID = "__libretto_highlight_layer__";
 
 function buildHighlightInitScript(opts: { zIndex: number }): string {
-	return `
+  return `
 (function() {
 	if (document.getElementById("${LAYER_ID}")) return;
 	var el = document.createElement("div");
@@ -27,59 +27,59 @@ function buildHighlightInitScript(opts: { zIndex: number }): string {
 const installedPages = new WeakSet<Page>();
 
 export async function ensureHighlightLayer(
-	page: Page,
-	options?: HighlightOptions,
+  page: Page,
+  options?: HighlightOptions,
 ): Promise<void> {
-	const existingOpts = (page as any).__librettoHighlightOpts as
-		| { color: string; zIndex: number }
-		| undefined;
-	const zIndex =
-		options?.zIndex ?? existingOpts?.zIndex ?? HIGHLIGHT_DEFAULTS.zIndex;
-	const initScript = buildHighlightInitScript({ zIndex });
-
-	if (!installedPages.has(page)) {
-		installedPages.add(page);
-		await page.addInitScript({ content: initScript });
-	}
-
-	// Store/refresh options for later.
-	(page as any).__librettoHighlightOpts = {
-		color: options?.color ?? existingOpts?.color ?? HIGHLIGHT_DEFAULTS.color,
-		zIndex,
-	};
-
-	// Re-run in-page installer so overlays recover after page.setContent() or DOM resets.
-	try {
-		await page.evaluate(new Function(initScript) as () => void);
-	} catch {
-		// Page may not be ready
-	}
+  const existingOpts = (page as any).__librettoHighlightOpts as
+    | { color: string; zIndex: number }
+    | undefined;
+  const zIndex =
+    options?.zIndex ?? existingOpts?.zIndex ?? HIGHLIGHT_DEFAULTS.zIndex;
+  const initScript = buildHighlightInitScript({ zIndex });
+
+  if (!installedPages.has(page)) {
+    installedPages.add(page);
+    await page.addInitScript({ content: initScript });
+  }
+
+  // Store/refresh options for later.
+  (page as any).__librettoHighlightOpts = {
+    color: options?.color ?? existingOpts?.color ?? HIGHLIGHT_DEFAULTS.color,
+    zIndex,
+  };
+
+  // Re-run in-page installer so overlays recover after page.setContent() or DOM resets.
+  try {
+    await page.evaluate(new Function(initScript) as () => void);
+  } catch {
+    // Page may not be ready
+  }
 }
 
 export type ShowHighlightParams = {
-	box: { x: number; y: number; width: number; height: number };
-	label?: string;
-	color?: string;
-	durationMs?: number;
+  box: { x: number; y: number; width: number; height: number };
+  label?: string;
+  color?: string;
+  durationMs?: number;
 };
 
 export async function showHighlight(
-	page: Page,
-	params: ShowHighlightParams,
+  page: Page,
+  params: ShowHighlightParams,
 ): Promise<void> {
-	const opts = (page as any).__librettoHighlightOpts ?? HIGHLIGHT_DEFAULTS;
-	const color = params.color ?? opts.color;
-	const durationMs = params.durationMs ?? 350;
-
-	try {
-		await page.evaluate(
-			({ layerId, box, color, label, durationMs }) => {
-				const layer = document.getElementById(layerId);
-				if (!layer) return;
-
-				const rect = document.createElement("div");
-				rect.className = "__libretto_highlight_rect__";
-				rect.style.cssText = `
+  const opts = (page as any).__librettoHighlightOpts ?? HIGHLIGHT_DEFAULTS;
+  const color = params.color ?? opts.color;
+  const durationMs = params.durationMs ?? 350;
+
+  try {
+    await page.evaluate(
+      ({ layerId, box, color, label, durationMs }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+
+        const rect = document.createElement("div");
+        rect.className = "__libretto_highlight_rect__";
+        rect.style.cssText = `
 					position:absolute;
 					left:${box.x}px;
 					top:${box.y}px;
@@ -93,10 +93,10 @@ export async function showHighlight(
 					opacity:1;
 				`;
 
-				if (label) {
-					const labelEl = document.createElement("div");
-					labelEl.textContent = label;
-					labelEl.style.cssText = `
+        if (label) {
+          const labelEl = document.createElement("div");
+          labelEl.textContent = label;
+          labelEl.style.cssText = `
 						position:absolute;
 						top:-22px;
 						left:0;
@@ -108,39 +108,42 @@ export async function showHighlight(
 						white-space:nowrap;
 						pointer-events:none;
 					`;
-					rect.appendChild(labelEl);
-				}
-
-				layer.appendChild(rect);
-
-				// Auto-fade after duration
-				setTimeout(() => {
-					rect.style.opacity = "0";
-					setTimeout(() => rect.remove(), 250);
-				}, durationMs);
-			},
-			{
-				layerId: LAYER_ID,
-				box: params.box,
-				color,
-				label: params.label,
-				durationMs,
-			},
-		);
-	} catch {
-		// Best-effort
-	}
+          rect.appendChild(labelEl);
+        }
+
+        layer.appendChild(rect);
+
+        // Auto-fade after duration
+        setTimeout(() => {
+          rect.style.opacity = "0";
+          setTimeout(() => rect.remove(), 250);
+        }, durationMs);
+      },
+      {
+        layerId: LAYER_ID,
+        box: params.box,
+        color,
+        label: params.label,
+        durationMs,
+      },
+    );
+  } catch {
+    // Best-effort
+  }
 }
 
 export async function clearHighlights(page: Page): Promise<void> {
-	try {
-		await page.evaluate(({ layerId }) => {
-			const layer = document.getElementById(layerId);
-			if (!layer) return;
-			const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
-			rects.forEach((r) => r.remove());
-		}, { layerId: LAYER_ID });
-	} catch {
-		// Best-effort
-	}
+  try {
+    await page.evaluate(
+      ({ layerId }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+        const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
+        rects.forEach((r) => r.remove());
+      },
+      { layerId: LAYER_ID },
+    );
+  } catch {
+    // Best-effort
+  }
 }

package/src/shared/visualization/index.ts

@@ -1,18 +1,18 @@
 export {
-	ensureGhostCursor,
-	moveGhostCursor,
-	moveGhostCursorWithDistance,
-	ghostClick,
-	hideGhostCursor,
-	getGhostCursorPosition,
-	type GhostCursorOptions,
-	type GhostCursorStyle,
+  ensureGhostCursor,
+  moveGhostCursor,
+  moveGhostCursorWithDistance,
+  ghostClick,
+  hideGhostCursor,
+  getGhostCursorPosition,
+  type GhostCursorOptions,
+  type GhostCursorStyle,
 } from "./ghost-cursor.js";
 
 export {
-	ensureHighlightLayer,
-	showHighlight,
-	clearHighlights,
-	type HighlightOptions,
-	type ShowHighlightParams,
+  ensureHighlightLayer,
+  showHighlight,
+  clearHighlights,
+  type HighlightOptions,
+  type ShowHighlightParams,
 } from "./highlight.js";

package/src/shared/workflow/workflow.ts

@@ -3,40 +3,117 @@ import type { MinimalLogger } from "../logger/logger.js";
 
 export const LIBRETTO_WORKFLOW_BRAND = Symbol.for("libretto.workflow");
 
-export type LibrettoWorkflowMetadata = {};
-
-export type LibrettoWorkflowContext<S = {}> = {
-	page: Page;
-	logger: MinimalLogger;
-	services: S;
+export type LibrettoWorkflowContext = {
+  session: string;
+  page: Page;
+  logger: MinimalLogger;
 };
 
-export type LibrettoWorkflowHandler<Input = unknown, Output = unknown, S = {}> = (
-	ctx: LibrettoWorkflowContext<S>,
-	input: Input,
+export type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (
+  ctx: LibrettoWorkflowContext,
+  input: Input,
 ) => Promise<Output>;
 
-export class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
-	public readonly [LIBRETTO_WORKFLOW_BRAND] = true;
-	public readonly metadata: LibrettoWorkflowMetadata;
-	private readonly handler: LibrettoWorkflowHandler<Input, Output, S>;
-
-	constructor(
-		metadata: LibrettoWorkflowMetadata,
-		handler: LibrettoWorkflowHandler<Input, Output, S>,
-	) {
-		this.metadata = metadata;
-		this.handler = handler;
-	}
-
-	async run(ctx: LibrettoWorkflowContext<S>, input: Input): Promise<Output> {
-		return this.handler(ctx, input);
-	}
+export class LibrettoWorkflow<Input = unknown, Output = unknown> {
+  public readonly [LIBRETTO_WORKFLOW_BRAND] = true;
+  public readonly name: string;
+  private readonly handler: LibrettoWorkflowHandler<Input, Output>;
+
+  constructor(
+    name: string,
+    handler: LibrettoWorkflowHandler<Input, Output>,
+  ) {
+    this.name = name;
+    this.handler = handler;
+  }
+
+  async run(ctx: LibrettoWorkflowContext, input: Input): Promise<Output> {
+    return this.handler(ctx, input);
+  }
+}
+
+export type ExportedLibrettoWorkflow = {
+  readonly [LIBRETTO_WORKFLOW_BRAND]: true;
+  readonly name: string;
+  run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
+};
+
+type WorkflowModuleExports = Record<string, unknown>;
+
+// Use the workflow brand instead of `instanceof` so imported workflows are
+// still recognized after loading the integration module dynamically.
+export function isLibrettoWorkflow(
+  value: unknown,
+): value is ExportedLibrettoWorkflow {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Record<PropertyKey, unknown>;
+  return (
+    candidate[LIBRETTO_WORKFLOW_BRAND] === true &&
+    typeof candidate.name === "string" &&
+    typeof candidate.run === "function"
+  );
+}
+
+function addWorkflowOrThrow(
+  workflowsByName: Map<string, ExportedLibrettoWorkflow>,
+  value: unknown,
+): void {
+  if (!isLibrettoWorkflow(value)) return;
+
+  // Re-exporting the same workflow object is fine, but two distinct workflow
+  // instances cannot claim the same runtime name.
+  const existing = workflowsByName.get(value.name);
+  if (existing && existing !== value) {
+    throw new Error(
+      `Duplicate workflow name: "${value.name}". Each workflow() call must use a unique name.`,
+    );
+  }
+
+  workflowsByName.set(value.name, value);
+}
+
+export function getWorkflowsFromModuleExports(
+  moduleExports: WorkflowModuleExports,
+): ExportedLibrettoWorkflow[] {
+  const workflowsByName = new Map<string, ExportedLibrettoWorkflow>();
+
+  for (const [exportName, value] of Object.entries(moduleExports)) {
+    if (exportName === "workflows" && value && typeof value === "object") {
+      // Support both `export const workflows = workflow(...)` and
+      // `export const workflows = { myWorkflow }`.
+      if (isLibrettoWorkflow(value)) {
+        addWorkflowOrThrow(workflowsByName, value);
+      } else {
+        for (const nestedValue of Object.values(
+          value as Record<string, unknown>,
+        )) {
+          addWorkflowOrThrow(workflowsByName, nestedValue);
+        }
+      }
+      continue;
+    }
+
+    addWorkflowOrThrow(workflowsByName, value);
+  }
+
+  return [...workflowsByName.values()];
+}
+
+export function getWorkflowFromModuleExports(
+  moduleExports: WorkflowModuleExports,
+  workflowName: string,
+): ExportedLibrettoWorkflow | null {
+  for (const workflow of getWorkflowsFromModuleExports(moduleExports)) {
+    if (workflow.name === workflowName) {
+      return workflow;
+    }
+  }
+  return null;
 }
 
-export function workflow<Input = unknown, Output = unknown, S = {}>(
-	metadata: LibrettoWorkflowMetadata,
-	handler: LibrettoWorkflowHandler<Input, Output, S>,
-): LibrettoWorkflow<Input, Output, S> {
-	return new LibrettoWorkflow(metadata, handler);
+export function workflow<Input = unknown, Output = unknown>(
+  name: string,
+  handler: LibrettoWorkflowHandler<Input, Output>,
+): LibrettoWorkflow<Input, Output> {
+  return new LibrettoWorkflow(name, handler);
 }

package/scripts/check-skills-sync.mjs

@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { compareSkillDirs, SKILL_DIRS } from "./skills-libretto.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const repoRoot = join(__dirname, "..");
-const result = compareSkillDirs(repoRoot);
-
-if (result.ok) {
-  console.log(`libretto: verified identical skill mirrors across ${SKILL_DIRS.join(", ")}`);
-  process.exit(0);
-}
-
-console.error("libretto: skill directories must be identical:");
-for (const issue of result.issues) {
-  console.error(`- ${issue}`);
-}
-console.error("");
-console.error("Run `pnpm i` to resync the mirrors in this repository.");
-process.exit(1);

package/scripts/prepare-release.sh

@@ -1,97 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage: scripts/prepare-release.sh [patch|minor|major]
-
-Creates a release PR branch from main, bumps package.json, pushes the branch,
-and opens a pull request targeting main.
-EOF
-}
-
-bump="${1:-patch}"
-
-case "$bump" in
-  patch|minor|major)
-    ;;
-  -h|--help|help)
-    usage
-    exit 0
-    ;;
-  *)
-    echo "Invalid bump type: $bump" >&2
-    usage >&2
-    exit 1
-    ;;
-esac
-
-if ! command -v gh >/dev/null 2>&1; then
-  echo "gh CLI is required." >&2
-  exit 1
-fi
-
-if [ -n "$(git status --porcelain)" ]; then
-  echo "Working tree must be clean before preparing a release." >&2
-  exit 1
-fi
-
-current_branch="$(git branch --show-current)"
-if [ "$current_branch" != "main" ]; then
-  echo "Switching from $current_branch to main."
-fi
-
-git fetch origin
-git checkout main
-git pull --ff-only origin main
-
-pnpm install --frozen-lockfile
-pnpm type-check
-pnpm test
-
-current_version="$(node -p "require('./package.json').version")"
-next_version="$(node -e '
-const [major, minor, patch] = process.argv[1].split(".").map(Number)
-const bump = process.argv[2]
-
-let next
-if (bump === "major") next = [major + 1, 0, 0]
-else if (bump === "minor") next = [major, minor + 1, 0]
-else next = [major, minor, patch + 1]
-
-process.stdout.write(next.join("."))
-' "$current_version" "$bump")"
-branch_name="tk-release-v${next_version}"
-
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  echo "Local branch ${branch_name} already exists." >&2
-  exit 1
-fi
-
-if git ls-remote --exit-code --heads origin "${branch_name}" >/dev/null 2>&1; then
-  echo "Remote branch ${branch_name} already exists." >&2
-  exit 1
-fi
-
-npm version "$next_version" --no-git-tag-version >/dev/null
-
-git checkout -b "$branch_name"
-git add package.json
-git commit -m "release: v${next_version}"
-git push -u origin "$branch_name"
-
-gh pr create \
-  --base main \
-  --head "$branch_name" \
-  --title "release: v${next_version}" \
-  --body "$(cat <<EOF
-## Summary
-
-- release libretto v${next_version}
-
-## Verification
-
-- pnpm type-check
-- pnpm test
-EOF
-)"

package/skills/libretto/references/reverse-engineering-network-requests.md

@@ -1,75 +0,0 @@
-# Reverse Engineering Network Requests
-
-Use this reference when the user wants to turn a browser workflow into direct network requests or decide whether direct request replay is the right extraction path.
-
-This is the default approach for new integrations when the site exposes a clear and stable HTTP request path.
-
-## When to Use This
-
-- The page clearly loads or submits data through HTTP requests.
-- The user can perform the workflow manually in a headed browser.
-- Replaying the request is likely faster or more stable than reproducing every UI action.
-- You need to decide whether direct browser `fetch` is safe enough to try.
-- Fall back to browser automation when the request path is unclear, too dynamic, or blocked by anti-bot systems.
-
-## Choosing the Capture Path
-
-- Prefer direct browser `fetch` when the site exposes a stable endpoint, `window.fetch` appears unpatched, and the response returns the data or action result you need.
-- Prefer passive capture plus UI automation when the site appears to wrap `fetch`, shows challenge pages or other bot-protection signals, or only exposes useful requests through normal page interaction.
-- Fall back to DOM extraction when the page is server-rendered or the captured responses are not usable.
-
-## Common Bot-Protection Signals
-
-These are examples, not a complete checklist.
-
-| Cookie Pattern | Common Association |
-| --- | --- |
-| `_abck` | Akamai Bot Manager |
-| `_px*` | PerimeterX / HUMAN |
-| `datadome` | DataDome |
-| `cf_clearance` | Cloudflare |
-| `_imp_apg_r_*` | Shape Security / F5 |
-| `x-kpsdk-*` | Kasada |
-
-- Unknown cookies can still be relevant if they look like telemetry, fingerprint, or signed security tokens.
-- If cookies suggest bot protection, also check for challenge pages, early-loading security scripts, and wrapped `fetch` or XHR APIs before trying direct request replay.
-
-## Workflow
-
-- Open the page in headed mode.
-- Let the user perform the relevant workflow manually.
-- Read the network log after the relevant step.
-- Identify the smallest set of requests that actually carries the data or performs the action.
-- Before replaying a request, check whether direct browser `fetch` looks safe to try.
-- Look for challenge pages, obvious bot-protection signals, or wrapped `fetch` and XHR APIs.
-- Confirm with the user before replaying any request that could mutate data.
-- If direct browser `fetch` looks safe, recreate a key request with `page.evaluate(() => fetch(...))`.
-- If direct browser `fetch` is unsafe or does not work, keep using captured responses and UI automation for the triggering steps.
-- Recreate the working request path in code outside Libretto.
-- Verify the resulting workflow with `npx libretto run ...`.
-
-## Commands
-
-```bash
-npx libretto open https://target.example.com --headed
-npx libretto network --last 20
-npx libretto network --method POST --last 20
-npx libretto network --filter 'referral|patient|search'
-npx libretto exec "return await networkLog({ method: 'POST', last: 10 })"
-npx libretto exec "return await page.evaluate(() => ({ fetch: window.fetch.toString(), xhrOpen: XMLHttpRequest.prototype.open.toString() }))"
-npx libretto exec "
-  return await page.evaluate(async () => {
-    const resp = await fetch('/api/example', { method: 'GET' });
-    return await resp.text();
-  });
-"
-```
-
-## Notes
-
-- Start with the request that returns the data you need, not every request on the page.
-- Prefer captured requests over guessing payload shape.
-- Treat every replayed request, including `GET`, as potentially side-effectful until proven otherwise.
-- `page.evaluate(() => fetch(...))` can recreate either fetch-based or XHR-based endpoints because you are issuing a new browser-context request.
-- If a captured endpoint depends on signatures, rotating tokens, or opaque response formats, use Playwright to trigger it and capture the result instead of forcing direct replay.
-- If the request format is opaque, highly dynamic, or heavily defended, fall back to UI automation for that part.

package/skills/libretto/references/user-action-log.md

@@ -1,31 +0,0 @@
-# User Action Log
-
-Use this reference when the user performs steps manually in a headed Libretto session and you want to incorporate those steps into a workflow.
-
-## When to Use This
-
-- The user demonstrates the workflow in the browser window.
-- You want to know what they clicked, typed, or selected.
-- You need to reconcile manual user actions with captured network requests.
-
-## Workflow
-
-- Open the session in headed mode.
-- Ask the user to perform the workflow.
-- Read the user action log after they finish.
-- Use the log to identify the important transitions in the workflow.
-- Combine the action log with `snapshot` or `network` when the log alone is not enough.
-
-## Commands
-
-```bash
-npx libretto actions --source user --last 20
-npx libretto actions --source user --filter 'button|input|select'
-npx libretto exec "return await actionLog({ source: 'user', last: 10 })"
-```
-
-## Notes
-
-- The action log is most useful for reconstructing the sequence of a workflow, not for discovering every selector you need.
-- If the user performed relevant manual steps, read the action log before writing or revising the workflow code.
-- Use the action log to anchor your understanding, then inspect the current page state with `snapshot` or `exec`.