libretto 0.4.4 → 0.5.1

package/dist/cli/commands/execution.js

@@ -6,8 +6,10 @@ import { z } from "zod";
 import { installInstrumentation } from "../../shared/instrumentation/index.js";
 import {
   connect,
-  disconnectBrowser
+  disconnectBrowser,
+  resolveViewport
 } from "../core/browser.js";
+import { parseViewportArg } from "./browser.js";
 import { getPauseSignalPaths } from "../core/pause-signals.js";
 import {
   assertSessionAvailableForStart,
@@ -22,10 +24,10 @@ import {
 } from "../core/telemetry.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
-  sessionOption
+  sessionOption,
+  withAutoSession,
+  withRequiredSession
 } from "./shared.js";
 const stripTypeScriptTypes = moduleBuiltin.stripTypeScriptTypes;
 const require2 = moduleBuiltin.createRequire(import.meta.url);
@@ -69,23 +71,91 @@ function compileExecFunction(code, helperNames) {
   }).constructor;
   return new AsyncFunction(...helperNames, code);
 }
+function stripEmptyCatchHandlers(code) {
+  const catchRe = /\??\s*\.catch\(\s*\(\)\s*=>\s*\{\s*\}\s*\)/g;
+  let strippedCount = 0;
+  let result = "";
+  let i = 0;
+  while (i < code.length) {
+    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;
+    }
+    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;
+    }
+    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;
+        }
+        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;
+    }
+    catchRe.lastIndex = i;
+    const match = catchRe.exec(code);
+    if (match && match.index === i) {
+      strippedCount++;
+      i += match[0].length;
+      continue;
+    }
+    result += code[i];
+    i++;
+  }
+  return { cleaned: result, strippedCount };
+}
 async function runExec(code, session, logger, visualize = false, pageId) {
+  const { cleaned: cleanedCode, strippedCount } = stripEmptyCatchHandlers(code);
+  if (strippedCount > 0) {
+    console.log("(Stripped `.catch(() => {})` \u2014 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,
-    1e4,
-    {
-      pageId,
-      requireSinglePage: true
-    }
-  );
+  const {
+    browser,
+    context,
+    page,
+    pageId: resolvedPageId
+  } = await connect(session, logger, 1e4, {
+    pageId,
+    requireSinglePage: true
+  });
   const STALL_THRESHOLD_MS = 6e4;
   let lastActivityTs = Date.now();
   const onActivity = () => {
@@ -97,10 +167,10 @@ async function runExec(code, session, logger, visualize = false, pageId) {
       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 / 1e3)}s \u2014 exec may be hung (code: ${code.slice(0, 100)}...)`
+        `[stall-warning] No Playwright activity for ${Math.round(silenceMs / 1e3)}s \u2014 exec may be hung (code: ${cleanedCode.slice(0, 100)}...)`
       );
     }
   }, STALL_THRESHOLD_MS);
@@ -109,7 +179,7 @@ async function runExec(code, session, logger, visualize = false, pageId) {
     logger.info("exec-interrupted", {
       session,
       duration: Date.now() - execStartTs,
-      codePreview: code.slice(0, 200)
+      codePreview: cleanedCode.slice(0, 200)
     });
   };
   process.on("SIGINT", sigintHandler);
@@ -142,19 +212,21 @@ async function runExec(code, session, logger, visualize = false, pageId) {
       Buffer
     };
     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 !== void 0 });
     if (result !== void 0) {
       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 {
@@ -191,6 +263,7 @@ async function stopExistingFailedRunSession(session, logger) {
     port: existingState.port
   });
   clearSessionState(session, logger);
+  if (existingState.pid == null) return;
   const stopDeadline = Date.now() + 3e3;
   while (isProcessRunning(existingState.pid) && Date.now() < stopDeadline) {
     await new Promise((resolveWait) => setTimeout(resolveWait, 100));
@@ -257,10 +330,18 @@ async function waitForWorkflowOutcome(args) {
   }
   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,
@@ -268,15 +349,24 @@ async function waitForWorkflowOutcome(args) {
       };
     }
     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" };
     }
     await new Promise((resolveWait) => setTimeout(resolveWait, 250));
@@ -292,12 +382,12 @@ async function runResume(session, logger, sessionState) {
   } = getPauseSignalPaths(session);
   if (!existsSync(pausedSignalPath)) {
     throw new Error(
-      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call pause("${session}") first.`
+      `Session "${session}" is not paused. Run "libretto run ... --session ${session}" and call pause("${session}") first.`
     );
   }
-  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).`
     );
   }
   clearSignalIfExists(pausedSignalPath);
@@ -359,18 +449,24 @@ async function runIntegrationFromFile(args, logger) {
     session: args.session,
     params: args.params,
     headless: args.headless,
-    authProfileDomain: args.authProfileDomain
-  });
-  const worker = spawn(process.execPath, [
-    tsxCliPath,
-    ...args.tsconfigPath ? ["--tsconfig", args.tsconfigPath] : [],
-    workerEntryPath,
-    payload
-  ], {
-    detached: true,
-    stdio: "ignore",
-    env: process.env
+    visualize: args.visualize,
+    authProfileDomain: args.authProfileDomain,
+    viewport: args.viewport
   });
+  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,
@@ -409,27 +505,27 @@ 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(
   (input) => input.codeParts.length > 0,
-  "Usage: libretto-cli exec <code> [--session <name>] [--visualize]"
+  `Usage: libretto exec <code> [--session <name>] [--visualize]`
 );
-function createExecCommand(logger) {
-  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
-    );
-  });
-}
-const runUsage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]";
+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] [--no-visualize] [--viewport WxH]`;
 const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {
@@ -453,15 +549,28 @@ 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, paramsFile) {
   if (paramsFile) {
     let content;
@@ -479,51 +588,55 @@ function resolveRunParams(rawInlineParams, paramsFile) {
   }
   return {};
 }
-function createRunCommand(logger) {
-  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 : void 0;
-    await runIntegrationFromFile({
+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 : void 0;
+  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,
-      authProfileDomain: input.authProfile
-    }, logger);
-  });
-}
+      visualize,
+      authProfileDomain: input.authProfile,
+      viewport
+    },
+    ctx.logger
+  );
+});
 const resumeInput = SimpleCLI.input({
   positionals: [],
   named: {
     session: sessionOption()
   }
 });
-function createResumeCommand(logger) {
-  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);
-  });
-}
-function createExecutionCommands(logger) {
-  return {
-    exec: createExecCommand(logger),
-    run: createRunCommand(logger),
-    resume: createResumeCommand(logger)
-  };
-}
+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);
+});
+const executionCommands = {
+  exec: execCommand,
+  run: runCommand,
+  resume: resumeCommand
+};
 export {
-  createExecCommand,
-  createExecutionCommands,
-  createResumeCommand,
-  createRunCommand,
+  execCommand,
   execInput,
+  executionCommands,
+  resumeCommand,
   resumeInput,
+  runCommand,
   runInput
 };

package/dist/cli/commands/init.js

@@ -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";
@@ -83,7 +91,9 @@ function printSnapshotApiStatus() {
   printInvalidAiConfigWarning();
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  \u2713 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;
   }
@@ -98,7 +108,9 @@ function printSnapshotApiStatus() {
   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() {
   const config = safeReadAiConfig();
@@ -110,7 +122,9 @@ async function runInteractiveApiSetup() {
   printInvalidAiConfigWarning();
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  \u2713 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;
   }
   console.log("  \u2717 No snapshot API credentials detected.\n");
@@ -119,14 +133,18 @@ async function runInteractiveApiSetup() {
     output: process.stdout
   });
   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}`);
     }
     console.log("    s) Skip for now\n");
     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=...");
@@ -218,7 +236,9 @@ function detectAgentDirs(root) {
 async function copySkills() {
   const agentDirs = detectAgentDirs(REPO_ROOT);
   if (agentDirs.length === 0) {
-    console.log("\nSkills: No .agents/ or .claude/ directory found in repo root \u2014 skipping.");
+    console.log(
+      "\nSkills: No .agents/ or .claude/ directory found in repo root \u2014 skipping."
+    );
     return;
   }
   const destinations = agentDirs.map((d) => join(d, "skills", "libretto"));
@@ -246,7 +266,9 @@ ${verb} libretto skills in ${dirNames}?`);
     }
     cpSync(sourceDir, skillDest, { recursive: true });
     const fileCount = readdirSync(skillDest).length;
-    console.log(`  \u2713 Copied ${fileCount} skill files to ${name}/skills/libretto/`);
+    console.log(
+      `  \u2713 Copied ${fileCount} skill files to ${name}/skills/libretto/`
+    );
   }
 }
 const initInput = SimpleCLI.input({

package/dist/cli/commands/logs.js

@@ -12,10 +12,9 @@ import {
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   integerOption,
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
-  sessionOption
+  sessionOption,
+  withRequiredSession
 } from "./shared.js";
 async function resolvePageId(session, pageId) {
   if (!pageId) return void 0;
@@ -26,7 +25,7 @@ async function resolvePageId(session, pageId) {
   const foundPage = pages.find((page) => page.id === pageId);
   if (!foundPage) {
     throw new Error(
-      `Page "${pageId}" was not found in session "${session}". Run "libretto-cli pages --session ${session}" to list ids.`
+      `Page "${pageId}" was not found in session "${session}". Run "libretto pages --session ${session}" to list ids.`
     );
   }
   return pageId;
@@ -44,7 +43,7 @@ const networkInput = SimpleCLI.input({
 });
 const networkCommand = SimpleCLI.command({
   description: "View captured network requests"
-}).input(networkInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ input, ctx }) => {
+}).input(networkInput).use(withRequiredSession()).handle(async ({ input, ctx }) => {
   if (input.clear) {
     clearNetworkLog(ctx.session);
     console.log("Network log cleared.");
@@ -81,7 +80,7 @@ const actionsInput = SimpleCLI.input({
 });
 const actionsCommand = SimpleCLI.command({
   description: "View captured actions"
-}).input(actionsInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ input, ctx }) => {
+}).input(actionsInput).use(withRequiredSession()).handle(async ({ input, ctx }) => {
   if (input.clear) {
     clearActionLog(ctx.session);
     console.log("Action log cleared.");

package/dist/cli/commands/shared.js

@@ -1,26 +1,15 @@
 import { z } from "zod";
+import { createLoggerForSession } from "../core/context.js";
 import {
-  SESSION_DEFAULT,
+  generateSessionName,
   readSessionStateOrThrow,
   validateSessionName
 } from "../core/session.js";
 import {
   SimpleCLI
 } from "../framework/simple-cli.js";
-function createSessionSchema() {
-  return z.string().default(SESSION_DEFAULT).superRefine((value, ctx) => {
-    try {
-      validateSessionName(value);
-    } catch (err) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: err instanceof Error ? err.message : String(err)
-      });
-    }
-  });
-}
-function sessionOption(help = "Use a named session") {
-  return SimpleCLI.option(createSessionSchema(), { help });
+function sessionOption(help = "Session name") {
+  return SimpleCLI.option(z.string().optional(), { help });
 }
 function pageOption(help = "Target a specific page id") {
   return SimpleCLI.option(z.string().optional(), { help });
@@ -28,23 +17,35 @@ function pageOption(help = "Target a specific page id") {
 function integerOption(help) {
   return SimpleCLI.option(z.coerce.number().int().optional(), { help });
 }
-const resolveSessionMiddleware = async ({ input, ctx }) => {
-  return {
-    ...ctx,
-    session: input.session
+function withRequiredSession() {
+  return async ({ input, ctx }) => {
+    if (!input.session) {
+      throw new Error("Missing required option --session.");
+    }
+    validateSessionName(input.session);
+    const logger = createLoggerForSession(input.session);
+    return {
+      ...ctx,
+      session: input.session,
+      logger,
+      sessionState: readSessionStateOrThrow(input.session)
+    };
   };
-};
-const loadSessionStateMiddleware = async ({ ctx }) => {
-  return {
-    ...ctx,
-    sessionState: readSessionStateOrThrow(ctx.session)
+}
+function withAutoSession() {
+  return async ({ input, ctx }) => {
+    const session = input.session ?? generateSessionName();
+    if (input.session) {
+      validateSessionName(input.session);
+    }
+    const logger = createLoggerForSession(session);
+    return { ...ctx, session, logger };
   };
-};
+}
 export {
-  createSessionSchema,
   integerOption,
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
-  sessionOption
+  sessionOption,
+  withAutoSession,
+  withRequiredSession
 };