libretto 0.5.0 → 0.5.1

package/src/cli/commands/execution.ts

@@ -8,7 +8,9 @@ import type { LoggerApi } from "../../shared/logger/index.js";
 import {
   connect,
   disconnectBrowser,
+  resolveViewport,
 } from "../core/browser.js";
+import { parseViewportArg } from "./browser.js";
 import { getPauseSignalPaths } from "../core/pause-signals.js";
 import {
   assertSessionAvailableForStart,
@@ -22,15 +24,13 @@ import {
   readNetworkLog,
   wrapPageForActionLogging,
 } from "../core/telemetry.js";
-import type {
-  RunIntegrationWorkerRequest,
-} from "../workers/run-integration-worker-protocol.js";
+import type { RunIntegrationWorkerRequest } from "../workers/run-integration-worker-protocol.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
   sessionOption,
+  withAutoSession,
+  withRequiredSession,
 } from "./shared.js";
 
 type ExecFunction = (...args: unknown[]) => Promise<unknown>;
@@ -117,6 +117,87 @@ function compileExecFunction(
   return new AsyncFunction(...helperNames, code);
 }
 
+/**
+ * Strip `.catch(() => {})` / `?.catch(() => {})` from executable code,
+ * skipping occurrences inside string literals (single, double, backtick)
+ * and single-line / multi-line comments so we never corrupt non-code text.
+ */
+function stripEmptyCatchHandlers(code: string): {
+  cleaned: string;
+  strippedCount: number;
+} {
+  const catchRe = /\??\s*\.catch\(\s*\(\)\s*=>\s*\{\s*\}\s*\)/g;
+  let strippedCount = 0;
+  let result = "";
+  let i = 0;
+
+  while (i < code.length) {
+    // Single-line comment
+    if (code[i] === "/" && code[i + 1] === "/") {
+      const end = code.indexOf("\n", i);
+      const slice = end === -1 ? code.slice(i) : code.slice(i, end + 1);
+      result += slice;
+      i += slice.length;
+      continue;
+    }
+    // Multi-line comment
+    if (code[i] === "/" && code[i + 1] === "*") {
+      const end = code.indexOf("*/", i + 2);
+      const slice = end === -1 ? code.slice(i) : code.slice(i, end + 2);
+      result += slice;
+      i += slice.length;
+      continue;
+    }
+    // String literals
+    if (code[i] === '"' || code[i] === "'" || code[i] === "`") {
+      const quote = code[i];
+      let j = i + 1;
+      while (j < code.length) {
+        if (code[j] === "\\" && quote !== "`") {
+          j += 2;
+          continue;
+        }
+        if (code[j] === "\\" && quote === "`") {
+          j += 2;
+          continue;
+        }
+        if (code[j] === quote) {
+          j++;
+          break;
+        }
+        // Template literal interpolation — skip nested braces
+        if (quote === "`" && code[j] === "$" && code[j + 1] === "{") {
+          let depth = 1;
+          j += 2;
+          while (j < code.length && depth > 0) {
+            if (code[j] === "{") depth++;
+            else if (code[j] === "}") depth--;
+            j++;
+          }
+          continue;
+        }
+        j++;
+      }
+      result += code.slice(i, j);
+      i = j;
+      continue;
+    }
+    // Try to match the catch pattern at the current position
+    catchRe.lastIndex = i;
+    const match = catchRe.exec(code);
+    if (match && match.index === i) {
+      strippedCount++;
+      i += match[0].length;
+      continue;
+    }
+    // Regular character
+    result += code[i];
+    i++;
+  }
+
+  return { cleaned: result, strippedCount };
+}
+
 async function runExec(
   code: string,
   session: string,
@@ -124,22 +205,26 @@ async function runExec(
   visualize = false,
   pageId?: string,
 ): Promise<void> {
+  const { cleaned: cleanedCode, strippedCount } = stripEmptyCatchHandlers(code);
+  if (strippedCount > 0) {
+    console.log("(Stripped `.catch(() => {})` — letting errors bubble up)");
+  }
   logger.info("exec-start", {
     session,
-    codeLength: code.length,
-    codePreview: code.slice(0, 200),
+    codeLength: cleanedCode.length,
+    codePreview: cleanedCode.slice(0, 200),
     visualize,
     pageId,
   });
-  const { browser, context, page, pageId: resolvedPageId } = await connect(
-    session,
-    logger,
-    10000,
-    {
-      pageId,
-      requireSinglePage: true,
-    },
-  );
+  const {
+    browser,
+    context,
+    page,
+    pageId: resolvedPageId,
+  } = await connect(session, logger, 10000, {
+    pageId,
+    requireSinglePage: true,
+  });
 
   const STALL_THRESHOLD_MS = 60_000;
   let lastActivityTs = Date.now();
@@ -153,10 +238,10 @@ async function runExec(
       logger.warn("exec-stall-warning", {
         session,
         silenceMs,
-        codePreview: code.slice(0, 200),
+        codePreview: cleanedCode.slice(0, 200),
       });
       console.warn(
-        `[stall-warning] No Playwright activity for ${Math.round(silenceMs / 1000)}s — exec may be hung (code: ${code.slice(0, 100)}...)`,
+        `[stall-warning] No Playwright activity for ${Math.round(silenceMs / 1000)}s — exec may be hung (code: ${cleanedCode.slice(0, 100)}...)`,
       );
     }
   }, STALL_THRESHOLD_MS);
@@ -166,7 +251,7 @@ async function runExec(
     logger.info("exec-interrupted", {
       session,
       duration: Date.now() - execStartTs,
-      codePreview: code.slice(0, 200),
+      codePreview: cleanedCode.slice(0, 200),
     });
   };
   process.on("SIGINT", sigintHandler);
@@ -181,7 +266,12 @@ async function runExec(
     const execState: Record<string, unknown> = {};
 
     const networkLog = (
-      opts: { last?: number; filter?: string; method?: string; pageId?: string } = {},
+      opts: {
+        last?: number;
+        filter?: string;
+        method?: string;
+        pageId?: string;
+      } = {},
     ) => {
       return readNetworkLog(session, opts);
     };
@@ -216,7 +306,7 @@ async function runExec(
     };
 
     const helperNames = Object.keys(helpers);
-    const fn = compileExecFunction(code, helperNames);
+    const fn = compileExecFunction(cleanedCode, helperNames);
 
     const result = await fn(...Object.values(helpers));
     logger.info("exec-success", { session, hasResult: result !== undefined });
@@ -224,12 +314,14 @@ async function runExec(
       console.log(
         typeof result === "string" ? result : JSON.stringify(result, null, 2),
       );
+    } else {
+      console.log("Executed successfully");
     }
   } catch (err) {
     logger.error("exec-error", {
       error: err,
       session,
-      codePreview: code.slice(0, 200),
+      codePreview: cleanedCode.slice(0, 200),
     });
     throw err;
   } finally {
@@ -273,6 +365,8 @@ async function stopExistingFailedRunSession(
   });
   clearSessionState(session, logger);
 
+  if (existingState.pid == null) return;
+
   const stopDeadline = Date.now() + 3_000;
   while (isProcessRunning(existingState.pid) && Date.now() < stopDeadline) {
     await new Promise((resolveWait) => setTimeout(resolveWait, 100));
@@ -371,11 +465,19 @@ async function waitForWorkflowOutcome(
   let outputOffset = 0;
 
   while (true) {
-    outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+    outputOffset = streamOutputSince(
+      signalPaths.outputSignalPath,
+      outputOffset,
+    );
 
     if (existsSync(signalPaths.failedSignalPath)) {
-      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
-      const failureDetails = await waitForFailureDetails(signalPaths.failedSignalPath);
+      outputOffset = streamOutputSince(
+        signalPaths.outputSignalPath,
+        outputOffset,
+      );
+      const failureDetails = await waitForFailureDetails(
+        signalPaths.failedSignalPath,
+      );
       return {
         status: "failed",
         message: failureDetails?.message,
@@ -384,17 +486,26 @@ async function waitForWorkflowOutcome(
     }
 
     if (existsSync(signalPaths.completedSignalPath)) {
-      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      outputOffset = streamOutputSince(
+        signalPaths.outputSignalPath,
+        outputOffset,
+      );
       return { status: "completed" };
     }
 
     if (existsSync(signalPaths.pausedSignalPath)) {
-      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      outputOffset = streamOutputSince(
+        signalPaths.outputSignalPath,
+        outputOffset,
+      );
       return { status: "paused" };
     }
 
     if (!isProcessRunning(args.pid)) {
-      outputOffset = streamOutputSince(signalPaths.outputSignalPath, outputOffset);
+      outputOffset = streamOutputSince(
+        signalPaths.outputSignalPath,
+        outputOffset,
+      );
       return { status: "exited" };
     }
 
@@ -421,9 +532,9 @@ async function runResume(
     );
   }
 
-  if (!isProcessRunning(sessionState.pid)) {
+  if (sessionState.pid == null || !isProcessRunning(sessionState.pid)) {
     throw new Error(
-      `No active paused workflow found for session "${session}" (worker pid ${sessionState.pid} is not running).`,
+      `No active paused workflow found for session "${session}" (worker pid ${sessionState.pid ?? "unknown"} is not running).`,
     );
   }
 
@@ -451,7 +562,7 @@ async function runResume(
 
   const outcome = await waitForWorkflowOutcome({
     session,
-    pid: sessionState.pid,
+    pid: sessionState.pid!,
   });
 
   if (outcome.status === "completed") {
@@ -498,18 +609,24 @@ async function runIntegrationFromFile(
     session: args.session,
     params: args.params,
     headless: args.headless,
+    visualize: args.visualize,
     authProfileDomain: args.authProfileDomain,
+    viewport: args.viewport,
   } satisfies RunIntegrationWorkerRequest);
-  const worker = spawn(process.execPath, [
-    tsxCliPath,
-    ...(args.tsconfigPath ? ["--tsconfig", args.tsconfigPath] : []),
-    workerEntryPath,
-    payload,
-  ], {
-    detached: true,
-    stdio: "ignore",
-    env: process.env,
-  });
+  const worker = spawn(
+    process.execPath,
+    [
+      tsxCliPath,
+      ...(args.tsconfigPath ? ["--tsconfig", args.tsconfigPath] : []),
+      workerEntryPath,
+      payload,
+    ],
+    {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+    },
+  );
   worker.unref();
   const outcome = await waitForWorkflowOutcome({
     session: args.session,
@@ -548,7 +665,9 @@ export const execInput = SimpleCLI.input({
   ],
   named: {
     session: sessionOption(),
-    visualize: SimpleCLI.flag({ help: "Enable ghost cursor + highlight visualization" }),
+    visualize: SimpleCLI.flag({
+      help: "Enable ghost cursor + highlight visualization",
+    }),
     page: pageOption(),
   },
 }).refine(
@@ -556,26 +675,22 @@ export const execInput = SimpleCLI.input({
   `Usage: libretto exec <code> [--session <name>] [--visualize]`,
 );
 
-export function createExecCommand(logger: LoggerApi) {
-  return SimpleCLI.command({
-    description: "Execute Playwright TypeScript code",
-  })
-    .input(execInput)
-    .use(resolveSessionMiddleware)
-    .use(loadSessionStateMiddleware)
-    .handle(async ({ input, ctx }) => {
-      await runExec(
-        input.codeParts.join(" "),
-        ctx.session,
-        logger,
-        input.visualize,
-        input.page,
-      );
-    });
-}
+export const execCommand = SimpleCLI.command({
+  description: "Execute Playwright TypeScript code",
+})
+  .input(execInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    await runExec(
+      input.codeParts.join(" "),
+      ctx.session,
+      ctx.logger,
+      input.visualize,
+      input.page,
+    );
+  });
 
-const runUsage =
-  `Usage: libretto run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]`;
+const runUsage = `Usage: libretto run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
 
 export const runInput = SimpleCLI.input({
   positionals: [
@@ -600,18 +715,31 @@ export const runInput = SimpleCLI.input({
     }),
     headed: SimpleCLI.flag({ help: "Run in headed mode" }),
     headless: SimpleCLI.flag({ help: "Run in headless mode" }),
+    noVisualize: SimpleCLI.flag({
+      name: "no-visualize",
+      help: "Disable ghost cursor + highlight visualization in headed mode",
+    }),
     authProfile: SimpleCLI.option(z.string().optional(), {
       name: "auth-profile",
       help: "Domain for local auth profile (e.g. apps.example.com)",
     }),
+    viewport: SimpleCLI.option(z.string().optional(), {
+      help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)",
+    }),
   },
 })
   .refine(
     (input) => Boolean(input.integrationFile && input.integrationExport),
     runUsage,
   )
-  .refine((input) => !(input.params && input.paramsFile), "Pass either --params or --params-file, not both.")
-  .refine((input) => !(input.headed && input.headless), "Cannot pass both --headed and --headless.");
+  .refine(
+    (input) => !(input.params && input.paramsFile),
+    "Pass either --params or --params-file, not both.",
+  )
+  .refine(
+    (input) => !(input.headed && input.headless),
+    "Cannot pass both --headed and --headless.",
+  );
 
 function resolveRunParams(
   rawInlineParams: string | undefined,
@@ -634,34 +762,42 @@ function resolveRunParams(
   return {};
 }
 
-export function createRunCommand(logger: LoggerApi) {
-  return SimpleCLI.command({
-    description: "Run an exported Libretto workflow from a file",
-  })
-    .input(runInput)
-    .use(resolveSessionMiddleware)
-    .handle(async ({ input, ctx }) => {
-      await stopExistingFailedRunSession(ctx.session, logger);
-      assertSessionAvailableForStart(ctx.session, logger);
-
-      const params = resolveRunParams(input.params, input.paramsFile);
-      const headlessMode = input.headed
-        ? false
-        : input.headless
-          ? true
-          : undefined;
-
-      await runIntegrationFromFile({
+export const runCommand = SimpleCLI.command({
+  description: "Run an exported Libretto workflow from a file",
+})
+  .input(runInput)
+  .use(withAutoSession())
+  .handle(async ({ input, ctx }) => {
+    await stopExistingFailedRunSession(ctx.session, ctx.logger);
+    assertSessionAvailableForStart(ctx.session, ctx.logger);
+
+    const params = resolveRunParams(input.params, input.paramsFile);
+    const headlessMode = input.headed
+      ? false
+      : input.headless
+        ? true
+        : undefined;
+    const visualize = !input.noVisualize;
+    const viewport = resolveViewport(
+      parseViewportArg(input.viewport),
+      ctx.logger,
+    );
+
+    await runIntegrationFromFile(
+      {
         integrationPath: input.integrationFile!,
         exportName: input.integrationExport!,
         session: ctx.session,
         params,
         tsconfigPath: input.tsconfig,
         headless: headlessMode ?? false,
+        visualize,
         authProfileDomain: input.authProfile,
-      }, logger);
-    });
-}
+        viewport,
+      },
+      ctx.logger,
+    );
+  });
 
 export const resumeInput = SimpleCLI.input({
   positionals: [],
@@ -670,22 +806,17 @@ export const resumeInput = SimpleCLI.input({
   },
 });
 
-export function createResumeCommand(logger: LoggerApi) {
-  return SimpleCLI.command({
-    description: "Resume a paused workflow for the current session",
-  })
-    .input(resumeInput)
-    .use(resolveSessionMiddleware)
-    .use(loadSessionStateMiddleware)
-    .handle(async ({ ctx }) => {
-      await runResume(ctx.session, logger, ctx.sessionState);
-    });
-}
+export const resumeCommand = SimpleCLI.command({
+  description: "Resume a paused workflow for the current session",
+})
+  .input(resumeInput)
+  .use(withRequiredSession())
+  .handle(async ({ ctx }) => {
+    await runResume(ctx.session, ctx.logger, ctx.sessionState);
+  });
 
-export function createExecutionCommands(logger: LoggerApi) {
-  return {
-    exec: createExecCommand(logger),
-    run: createRunCommand(logger),
-    resume: createResumeCommand(logger),
-  };
-}
+export const executionCommands = {
+  exec: execCommand,
+  run: runCommand,
+  resume: resumeCommand,
+};

package/src/cli/commands/init.ts

@@ -1,5 +1,13 @@
 import { createInterface } from "node:readline";
-import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  cpSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -42,7 +50,8 @@ const PROVIDER_CHOICES: ProviderChoice[] = [
     key: "4",
     label: "Google Vertex AI",
     envVar: "GOOGLE_CLOUD_PROJECT",
-    envHint: "Requires gcloud auth application-default login and a GCP project ID",
+    envHint:
+      "Requires gcloud auth application-default login and a GCP project ID",
   },
 ];
 
@@ -101,7 +110,9 @@ function printSnapshotApiStatus(): void {
 
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  ✓ Ready: ${selection.model} (${selection.source})`);
-    console.log("    Snapshot objectives will use the API analyzer by default.");
+    console.log(
+      "    Snapshot objectives will use the API analyzer by default.",
+    );
     console.log("    No further action required.");
     return;
   }
@@ -117,7 +128,9 @@ function printSnapshotApiStatus(): void {
   console.log(
     "    Or run `npx libretto ai configure openai | anthropic | gemini | vertex` to set a specific model.",
   );
-  console.log("    Run `npx libretto init` interactively to set up credentials.");
+  console.log(
+    "    Run `npx libretto init` interactively to set up credentials.",
+  );
 }
 
 async function runInteractiveApiSetup(): Promise<void> {
@@ -132,7 +145,9 @@ async function runInteractiveApiSetup(): Promise<void> {
 
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  ✓ Ready: ${selection.model} (${selection.source})`);
-    console.log("    Snapshot objectives will use the API analyzer by default.");
+    console.log(
+      "    Snapshot objectives will use the API analyzer by default.",
+    );
     return;
   }
 
@@ -144,7 +159,9 @@ async function runInteractiveApiSetup(): Promise<void> {
   });
 
   try {
-    console.log("  Which API provider would you like to use for snapshot analysis?\n");
+    console.log(
+      "  Which API provider would you like to use for snapshot analysis?\n",
+    );
     for (const choice of PROVIDER_CHOICES) {
       console.log(`    ${choice.key}) ${choice.label}`);
     }
@@ -153,7 +170,9 @@ async function runInteractiveApiSetup(): Promise<void> {
     const answer = await promptUser(rl, "  Choice: ");
 
     if (answer.toLowerCase() === "s" || !answer) {
-      console.log("\n  Skipped. You can set up API credentials later by rerunning `npx libretto init`.");
+      console.log(
+        "\n  Skipped. You can set up API credentials later by rerunning `npx libretto init`.",
+      );
       console.log("  Or add credentials directly to your .env file:");
       console.log("    OPENAI_API_KEY=...");
       console.log("    ANTHROPIC_API_KEY=...");
@@ -255,7 +274,9 @@ async function copySkills(): Promise<void> {
   const agentDirs = detectAgentDirs(REPO_ROOT);
 
   if (agentDirs.length === 0) {
-    console.log("\nSkills: No .agents/ or .claude/ directory found in repo root — skipping.");
+    console.log(
+      "\nSkills: No .agents/ or .claude/ directory found in repo root — skipping.",
+    );
     return;
   }
 
@@ -289,7 +310,9 @@ async function copySkills(): Promise<void> {
     }
     cpSync(sourceDir, skillDest, { recursive: true });
     const fileCount = readdirSync(skillDest).length;
-    console.log(`  ✓ Copied ${fileCount} skill files to ${name}/skills/libretto/`);
+    console.log(
+      `  ✓ Copied ${fileCount} skill files to ${name}/skills/libretto/`,
+    );
   }
 }
 

package/src/cli/commands/logs.ts

@@ -12,13 +12,15 @@ import {
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   integerOption,
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
   sessionOption,
+  withRequiredSession,
 } from "./shared.js";
 
-async function resolvePageId(session: string, pageId?: string): Promise<string | undefined> {
+async function resolvePageId(
+  session: string,
+  pageId?: string,
+): Promise<string | undefined> {
   if (!pageId) return undefined;
   const pages = await withSessionLogger(session, async (logger) =>
     listOpenPages(session, logger),
@@ -48,8 +50,7 @@ export const networkCommand = SimpleCLI.command({
   description: "View captured network requests",
 })
   .input(networkInput)
-  .use(resolveSessionMiddleware)
-  .use(loadSessionStateMiddleware)
+  .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
     if (input.clear) {
       clearNetworkLog(ctx.session);
@@ -93,8 +94,7 @@ export const actionsCommand = SimpleCLI.command({
   description: "View captured actions",
 })
   .input(actionsInput)
-  .use(resolveSessionMiddleware)
-  .use(loadSessionStateMiddleware)
+  .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
     if (input.clear) {
       clearActionLog(ctx.session);