libretto 0.5.3-experimental.5 → 0.5.3

package/src/cli/router.ts

@@ -1,28 +1,22 @@
-import type { Logger } from "../shared/logger/index.js";
 import { aiCommands } from "./commands/ai.js";
-import { createBrowserCommands } from "./commands/browser.js";
-import { createExecutionCommands } from "./commands/execution.js";
+import { browserCommands } from "./commands/browser.js";
+import { deployCommand } from "./commands/deploy.js";
+import { executionCommands } from "./commands/execution.js";
 import { initCommand } from "./commands/init.js";
 import { logCommands } from "./commands/logs.js";
-import { sessionOption } from "./commands/shared.js";
-import { createSnapshotCommand } from "./commands/snapshot.js";
+import { snapshotCommand } from "./commands/snapshot.js";
 import { SimpleCLI } from "./framework/simple-cli.js";
 
-export function buildCLIRoutes(logger: Logger) {
-  return {
-    ...createBrowserCommands(logger),
-    ...createExecutionCommands(logger),
-    ...logCommands,
-    ai: aiCommands,
-    init: initCommand,
-    snapshot: createSnapshotCommand(logger),
-  };
-}
+export const cliRoutes = {
+  ...browserCommands,
+  deploy: deployCommand,
+  ...executionCommands,
+  ...logCommands,
+  ai: aiCommands,
+  init: initCommand,
+  snapshot: snapshotCommand,
+};
 
-export function createCLIApp(logger: Logger) {
-  return SimpleCLI.define("libretto", buildCLIRoutes(logger), {
-    globalNamed: {
-      session: sessionOption(),
-    },
-  });
+export function createCLIApp() {
+  return SimpleCLI.define("libretto", cliRoutes);
 }

package/src/cli/workers/run-integration-runtime.ts

@@ -5,8 +5,11 @@ import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  getWorkflowFromModuleExports,
+  getWorkflowsFromModuleExports,
   instrumentContext,
   launchBrowser,
+  type ExportedLibrettoWorkflow,
   type LibrettoWorkflowContext,
 } from "../../index.js";
 import type { LoggerApi } from "../../shared/logger/index.js";
@@ -18,14 +21,14 @@ import {
   getSessionNetworkLogPath,
   getSessionStatePath,
 } from "../core/context.js";
-import { getPauseSignalPaths, removeSignalIfExists } from "../core/pause-signals.js";
+import {
+  getPauseSignalPaths,
+  removeSignalIfExists,
+} from "../core/pause-signals.js";
 import { installSessionTelemetry } from "../core/session-telemetry.js";
 import type { RunIntegrationWorkerRequest } from "./run-integration-worker-protocol.js";
 
-const LIBRETTO_WORKFLOW_BRAND = Symbol.for("libretto.workflow");
-
-type LoadedLibrettoWorkflow = {
-  metadata: {};
+type LoadedLibrettoWorkflow = ExportedLibrettoWorkflow & {
   run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };
 
@@ -73,7 +76,10 @@ function readSessionStatePid(session: string): number | null {
   if (!existsSync(statePath)) return null;
 
   try {
-    return parseSessionStateContent(readFileSync(statePath, "utf8"), statePath).pid;
+    return (
+      parseSessionStateContent(readFileSync(statePath, "utf8"), statePath)
+        .pid ?? null
+    );
   } catch {
     return null;
   }
@@ -103,17 +109,6 @@ async function waitForFailureSessionRelease(args: {
   }
 }
 
-function isLoadedLibrettoWorkflow(value: unknown): value is LoadedLibrettoWorkflow {
-  if (!value || typeof value !== "object") return false;
-  const candidate = value as Record<PropertyKey, unknown>;
-  return (
-    candidate[LIBRETTO_WORKFLOW_BRAND] === true &&
-    typeof candidate.run === "function" &&
-    !!candidate.metadata &&
-    typeof candidate.metadata === "object"
-  );
-}
-
 function resolveLocalAuthProfilePath(domain: string): string {
   return getProfilePath(normalizeDomain(domain));
 }
@@ -144,9 +139,9 @@ function getAbsoluteIntegrationPath(integrationPath: string): string {
   return absolutePath;
 }
 
-async function loadWorkflowExport(
+async function loadWorkflowByName(
   absolutePath: string,
-  exportName: string,
+  workflowName: string,
 ): Promise<LoadedLibrettoWorkflow> {
   let loadedModule: Record<string, unknown>;
   try {
@@ -162,42 +157,23 @@ async function loadWorkflowExport(
     );
   }
 
-  const targetExport = loadedModule[exportName];
-  if (!targetExport) {
-    const availableExports = Object.keys(loadedModule);
-    const detail =
-      availableExports.length > 0
-        ? ` Available exports: ${availableExports.join(", ")}`
-        : " The module has no exports.";
-    throw new Error(
-      `Export "${exportName}" was not found in ${absolutePath}.${detail}`,
-    );
+  const workflow = getWorkflowFromModuleExports(loadedModule, workflowName);
+  if (workflow) {
+    return workflow as LoadedLibrettoWorkflow;
   }
 
-  if (!isLoadedLibrettoWorkflow(targetExport)) {
-    throw new Error(
-      [
-        `Export "${exportName}" in ${absolutePath} is not a valid Libretto workflow.`,
-        "",
-        'A workflow must be created using the workflow() function from "libretto":',
-        "",
-        '  import { workflow } from "libretto";',
-        "",
-        `  export const ${exportName} = workflow<InputType, OutputType>(`,
-        "    {},",
-        "    async (ctx, input) => {",
-        "      // ctx.page     — Playwright Page instance",
-        "      // ctx.logger   — MinimalLogger",
-        "      // ctx.services — injected dependencies (generic, default {})",
-        "      // input        — JSON-serializable input matching InputType",
-        "      return output; // must match OutputType",
-        "    },",
-        "  );",
-      ].join("\n"),
-    );
-  }
+  const availableWorkflows = getWorkflowsFromModuleExports(loadedModule).map(
+    (candidate) => candidate.name,
+  );
+
+  const detail =
+    availableWorkflows.length > 0
+      ? ` Available workflows: ${availableWorkflows.join(", ")}`
+      : ' No workflows found in this file. Export a workflow() instance from "libretto" directly or via `export const workflows = { ... }`.';
 
-  return targetExport;
+  throw new Error(
+    `Workflow "${workflowName}" not found in ${absolutePath}.${detail}`,
+  );
 }
 
 export async function installHeadedWorkflowVisualization(args: {
@@ -219,7 +195,7 @@ async function runIntegrationInternal(
 ): Promise<RunIntegrationOutcome> {
   const { logger } = options;
   const absolutePath = getAbsoluteIntegrationPath(args.integrationPath);
-  const workflow = await loadWorkflowExport(absolutePath, args.exportName);
+  const workflow = await loadWorkflowByName(absolutePath, args.workflowName);
   const signalPaths = getPauseSignalPaths(args.session);
   await removeSignalIfExists(signalPaths.pausedSignalPath);
   await removeSignalIfExists(signalPaths.resumeSignalPath);
@@ -228,12 +204,12 @@ async function runIntegrationInternal(
   const restoreStdout = mirrorStdoutToFile(signalPaths.outputSignalPath);
 
   console.log(
-    `Running integration "${args.exportName}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
+    `Running workflow "${args.workflowName}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
   );
 
   const integrationLogger = logger.withScope("integration-run", {
     integrationPath: absolutePath,
-    integrationExport: args.exportName,
+    workflowName: args.workflowName,
     session: args.session,
   });
 
@@ -255,6 +231,7 @@ async function runIntegrationInternal(
     sessionName: args.session,
     headless: args.headless,
     storageStatePath,
+    viewport: args.viewport,
   });
   if (!args.headless && args.visualize !== false) {
     await installHeadedWorkflowVisualization({
@@ -277,16 +254,17 @@ async function runIntegrationInternal(
   });
 
   const workflowContext: LibrettoWorkflowContext = {
+    session: args.session,
     logger: integrationLogger,
     page: browserSession.page,
-    services: {},
   };
 
   try {
     try {
       await workflow.run(workflowContext, args.params ?? {});
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
       await writeFile(
         signalPaths.failedSignalPath,
         JSON.stringify(

package/src/cli/workers/run-integration-worker-protocol.ts

@@ -2,12 +2,13 @@ import { z } from "zod";
 
 export const RunIntegrationWorkerRequestSchema = z.object({
   integrationPath: z.string().min(1),
-  exportName: z.string().min(1),
+  workflowName: z.string().min(1),
   session: z.string().min(1),
   params: z.unknown(),
   headless: z.boolean(),
   visualize: z.boolean().default(true),
   authProfileDomain: z.string().optional(),
+  viewport: z.object({ width: z.number(), height: z.number() }).optional(),
 });
 
 export type RunIntegrationWorkerRequest = z.infer<

package/src/cli/workers/run-integration-worker.ts

@@ -5,10 +5,7 @@ import {
   type RunIntegrationWorkerRequest,
 } from "./run-integration-worker-protocol.js";
 import { runIntegrationFromFileInWorker } from "./run-integration-runtime.js";
-import {
-  ensureLibrettoSetup,
-  withSessionLogger,
-} from "../core/context.js";
+import { ensureLibrettoSetup, withSessionLogger } from "../core/context.js";
 import { getPauseSignalPaths } from "../core/pause-signals.js";
 
 function parseWorkerRequest(argv: string[]): RunIntegrationWorkerRequest {

package/src/index.ts

@@ -2,119 +2,129 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // Logger
-export { Logger, defaultLogger, type LoggerApi, type MinimalLogger, type LoggerSink, type LogOptions } from "./shared/logger/logger.js";
 export {
-	createFileLogSink,
-	prettyConsoleSink,
-	jsonlConsoleSink,
+  Logger,
+  defaultLogger,
+  type LoggerApi,
+  type MinimalLogger,
+  type LoggerSink,
+  type LogOptions,
+} from "./shared/logger/logger.js";
+export {
+  createFileLogSink,
+  prettyConsoleSink,
+  jsonlConsoleSink,
 } from "./shared/logger/sinks.js";
 
 // LLM client interface
-export type { LLMClient, Message, MessageContentPart } from "./shared/llm/types.js";
+export type {
+  LLMClient,
+  Message,
+  MessageContentPart,
+} from "./shared/llm/types.js";
 export { createLLMClientFromModel } from "./shared/llm/ai-sdk-adapter.js";
 export {
-	SESSION_STATE_VERSION,
-	SessionStatusSchema,
-	SessionStateFileSchema,
-	parseSessionStateData,
-	parseSessionStateContent,
-	serializeSessionState,
-	type SessionStatus,
-	type SessionState,
-	type SessionStateFile,
+  SESSION_STATE_VERSION,
+  SessionStatusSchema,
+  SessionStateFileSchema,
+  parseSessionStateData,
+  parseSessionStateContent,
+  serializeSessionState,
+  type SessionStatus,
+  type SessionState,
+  type SessionStateFile,
 } from "./shared/state/index.js";
 
 // Recovery
 export { executeRecoveryAgent } from "./runtime/recovery/agent.js";
 export { attemptWithRecovery } from "./runtime/recovery/recovery.js";
 export {
-	detectSubmissionError,
-	type KnownSubmissionError,
-	type DetectedSubmissionError,
+  detectSubmissionError,
+  type KnownSubmissionError,
+  type DetectedSubmissionError,
 } from "./runtime/recovery/errors.js";
 
 // AI extraction
-export { extractFromPage, type ExtractOptions } from "./runtime/extract/extract.js";
+export {
+  extractFromPage,
+  type ExtractOptions,
+} from "./runtime/extract/extract.js";
 
 // Network helpers
 export {
-	pageRequest,
-	type RequestConfig,
-	type PageRequestOptions,
+  pageRequest,
+  type RequestConfig,
+  type PageRequestOptions,
 } from "./runtime/network/network.js";
 
 // Download helpers
 export {
-	downloadViaClick,
-	downloadAndSave,
-	type DownloadResult,
-	type DownloadViaClickOptions,
-	type SaveDownloadOptions,
+  downloadViaClick,
+  downloadAndSave,
+  type DownloadResult,
+  type DownloadViaClickOptions,
+  type SaveDownloadOptions,
 } from "./runtime/download/download.js";
 
 // Debug / Pause
 export { pause } from "./shared/debug/pause.js";
 
-// Config
-export {
-	isDebugMode,
-	isDryRun,
-	shouldPauseBeforeMutation,
-} from "./shared/config/config.js";
-
 // Instrumentation
 export {
-	instrumentPage,
-	installInstrumentation,
-	instrumentContext,
-	type InstrumentationOptions,
-	type InstrumentedPage,
+  instrumentPage,
+  installInstrumentation,
+  instrumentContext,
+  type InstrumentationOptions,
+  type InstrumentedPage,
 } from "./shared/instrumentation/instrument.js";
 
 // Visualization
 export {
-	ensureGhostCursor,
-	moveGhostCursor,
-	ghostClick,
-	hideGhostCursor,
-	type GhostCursorOptions,
+  ensureGhostCursor,
+  moveGhostCursor,
+  ghostClick,
+  hideGhostCursor,
+  type GhostCursorOptions,
 } from "./shared/visualization/ghost-cursor.js";
 export {
-	ensureHighlightLayer,
-	showHighlight,
-	clearHighlights,
-	type HighlightOptions,
+  ensureHighlightLayer,
+  showHighlight,
+  clearHighlights,
+  type HighlightOptions,
 } from "./shared/visualization/highlight.js";
 
 // Run helpers
 export {
-	launchBrowser,
-	type LaunchBrowserArgs,
-	type BrowserSession,
+  launchBrowser,
+  type LaunchBrowserArgs,
+  type BrowserSession,
 } from "./shared/run/api.js";
 
 // Workflow helpers
 export {
-	LibrettoWorkflow,
-	LIBRETTO_WORKFLOW_BRAND,
-	workflow,
-	type LibrettoWorkflowMetadata,
-	type LibrettoWorkflowContext,
-	type LibrettoWorkflowHandler,
+  getWorkflowFromModuleExports,
+  getWorkflowsFromModuleExports,
+  isLibrettoWorkflow,
+  LibrettoWorkflow,
+  LIBRETTO_WORKFLOW_BRAND,
+  workflow,
+  type ExportedLibrettoWorkflow,
+  type LibrettoWorkflowContext,
+  type LibrettoWorkflowHandler,
 } from "./shared/workflow/workflow.js";
-
 const isDirectExecution = (): boolean => {
-	const entryArg = process.argv[1];
-	if (!entryArg) {
-		return false;
-	}
-	return pathToFileURL(resolve(entryArg)).href === import.meta.url;
+  const entryArg = process.argv[1];
+  if (!entryArg) {
+    return false;
+  }
+  return pathToFileURL(resolve(entryArg)).href === import.meta.url;
 };
 
 if (isDirectExecution()) {
-	void import("./cli/index.js").catch((error: unknown) => {
-			const message = error instanceof Error ? error.stack ?? error.message : String(error);
-			process.stderr.write(`${message}\n`);
-			process.exitCode = 1;
-		});
+  void import("./cli/index.js").catch((error: unknown) => {
+    const message =
+      error instanceof Error ? (error.stack ?? error.message) : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
 }

package/src/runtime/download/download.ts

@@ -4,16 +4,16 @@ import type { Page, Download } from "playwright";
 import type { MinimalLogger } from "../../shared/logger/logger.js";
 
 export type DownloadResult = {
-	/** The raw file contents. */
-	buffer: Buffer;
-	/** The filename suggested by the server (Content-Disposition header or URL). */
-	filename: string;
+  /** The raw file contents. */
+  buffer: Buffer;
+  /** The filename suggested by the server (Content-Disposition header or URL). */
+  filename: string;
 };
 
 export type DownloadViaClickOptions = {
-	logger?: MinimalLogger;
-	/** Timeout in milliseconds for waiting on the download event. Defaults to 30 000. */
-	timeout?: number;
+  logger?: MinimalLogger;
+  /** Timeout in milliseconds for waiting on the download event. Defaults to 30 000. */
+  timeout?: number;
 };
 
 /**
@@ -24,55 +24,55 @@ export type DownloadViaClickOptions = {
  * never missed.
  */
 export async function downloadViaClick(
-	page: Page,
-	selector: string,
-	options?: DownloadViaClickOptions,
+  page: Page,
+  selector: string,
+  options?: DownloadViaClickOptions,
 ): Promise<DownloadResult> {
-	const { logger, timeout = 30_000 } = options ?? {};
+  const { logger, timeout = 30_000 } = options ?? {};
 
-	const startTime = Date.now();
+  const startTime = Date.now();
 
-	// 1. Register the download listener BEFORE clicking
-	const downloadPromise = page.waitForEvent("download", { timeout });
+  // 1. Register the download listener BEFORE clicking
+  const downloadPromise = page.waitForEvent("download", { timeout });
 
-	// 2. Click the element that triggers the download
-	await page.locator(selector).click();
+  // 2. Click the element that triggers the download
+  await page.locator(selector).click();
 
-	// 3. Await the download event
-	const download: Download = await downloadPromise;
+  // 3. Await the download event
+  const download: Download = await downloadPromise;
 
-	// 4. Get the suggested filename
-	const filename = download.suggestedFilename();
+  // 4. Get the suggested filename
+  const filename = download.suggestedFilename();
 
-	// 5. Read the downloaded file into a buffer
-	const readStream = await download.createReadStream();
-	if (!readStream) {
-		throw new Error(
-			`Download stream unavailable for "${filename}". The browser may have been closed before the download completed.`,
-		);
-	}
+  // 5. Read the downloaded file into a buffer
+  const readStream = await download.createReadStream();
+  if (!readStream) {
+    throw new Error(
+      `Download stream unavailable for "${filename}". The browser may have been closed before the download completed.`,
+    );
+  }
 
-	const chunks: Buffer[] = [];
-	for await (const chunk of readStream) {
-		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-	}
-	const buffer = Buffer.concat(chunks);
+  const chunks: Buffer[] = [];
+  for await (const chunk of readStream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const buffer = Buffer.concat(chunks);
 
-	const duration = Date.now() - startTime;
+  const duration = Date.now() - startTime;
 
-	logger?.info("download:click", {
-		selector,
-		filename,
-		size: buffer.length,
-		duration,
-	});
+  logger?.info("download:click", {
+    selector,
+    filename,
+    size: buffer.length,
+    duration,
+  });
 
-	return { buffer, filename };
+  return { buffer, filename };
 }
 
 export type SaveDownloadOptions = DownloadViaClickOptions & {
-	/** Absolute or relative path to save the file to. When omitted the suggested filename is used in the current working directory. */
-	savePath?: string;
+  /** Absolute or relative path to save the file to. When omitted the suggested filename is used in the current working directory. */
+  savePath?: string;
 };
 
 /**
@@ -80,21 +80,25 @@ export type SaveDownloadOptions = DownloadViaClickOptions & {
  * downloaded file to disk.
  */
 export async function downloadAndSave(
-	page: Page,
-	selector: string,
-	options?: SaveDownloadOptions,
+  page: Page,
+  selector: string,
+  options?: SaveDownloadOptions,
 ): Promise<DownloadResult & { savedTo: string }> {
-	const { savePath, ...downloadOpts } = options ?? {};
-	const { buffer, filename } = await downloadViaClick(page, selector, downloadOpts);
-
-	const dest = resolve(savePath ?? filename);
-	await writeFile(dest, buffer);
-
-	options?.logger?.info("download:saved", {
-		filename,
-		savedTo: dest,
-		size: buffer.length,
-	});
-
-	return { buffer, filename, savedTo: dest };
+  const { savePath, ...downloadOpts } = options ?? {};
+  const { buffer, filename } = await downloadViaClick(
+    page,
+    selector,
+    downloadOpts,
+  );
+
+  const dest = resolve(savePath ?? filename);
+  await writeFile(dest, buffer);
+
+  options?.logger?.info("download:saved", {
+    filename,
+    savedTo: dest,
+    size: buffer.length,
+  });
+
+  return { buffer, filename, savedTo: dest };
 }

package/src/runtime/download/index.ts

@@ -1,7 +1,7 @@
 export {
-	downloadViaClick,
-	downloadAndSave,
-	type DownloadResult,
-	type DownloadViaClickOptions,
-	type SaveDownloadOptions,
+  downloadViaClick,
+  downloadAndSave,
+  type DownloadResult,
+  type DownloadViaClickOptions,
+  type SaveDownloadOptions,
 } from "./download.js";