libretto 0.4.0 → 0.4.1

package/dist/cli/cli.js

@@ -1,61 +1,18 @@
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
-import { registerAICommands } from "./commands/ai.js";
-import { registerBrowserCommands } from "./commands/browser.js";
-import { registerExecutionCommands } from "./commands/execution.js";
-import { registerLogCommands } from "./commands/logs.js";
-import { registerInitCommand } from "./commands/init.js";
-import { registerSnapshotCommands } from "./commands/snapshot.js";
 import {
   closeLogger,
   createLoggerForSession,
   ensureLibrettoSetup
 } from "./core/context.js";
 import {
-  listSessionsWithStateFile,
+  SESSION_DEFAULT,
   validateSessionName
 } from "./core/session.js";
-const AUTO_SESSION_COMMANDS = /* @__PURE__ */ new Set(["open", "run"]);
-const SESSION_OPTIONAL_COMMANDS = /* @__PURE__ */ new Set(["help", "--help", "-h", "init", "ai"]);
-const CLI_COMMANDS = /* @__PURE__ */ new Set([
-  "open",
-  "run",
-  "ai",
-  "save",
-  "exec",
-  "snapshot",
-  "network",
-  "actions",
-  "pages",
-  "resume",
-  "close",
-  "init",
-  "--help",
-  "-h",
-  "help"
-]);
-function printUsage() {
-  console.log(`Usage: libretto-cli <command> [--session <name>]
-
-Commands:
-  init [--skip-browsers] Initialize libretto (install browsers, check AI setup)
-  open <url> [--headless] Launch browser and open URL (headed by default)
-                          Automatically loads saved profile if available
-  run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless]  Run an exported Libretto workflow from a file
-  ai configure [preset] [-- <command prefix...>]  Configure AI runtime for analysis commands
-  save <url|domain>       Save current browser session (cookies, localStorage, etc.)
-  exec <code> [--visualize]  Execute Playwright typescript code (--visualize enables ghost cursor + highlight)
-  snapshot [--objective <text> --context <text>]  Capture PNG + HTML; analyze when objective is provided (context optional)
-  network [--last N] [--filter regex] [--method M] [--clear]  View captured network requests
-  actions [--last N] [--filter regex] [--action TYPE] [--source SOURCE] [--clear]  View captured actions
-  pages                   List open pages in the active session
-  resume                  Resume a paused workflow in the active session
-  close [--all] [--force]  Close the browser for the session, or all tracked sessions with --all
+import { createCLIApp } from "./router.js";
+function renderUsage(app) {
+  return `${app.renderHelp()}
 
 Options:
-  --session <name>        Use a named session
-                          If omitted for open/run, a session id is auto-generated
-                          All other stateful commands require --session
+  --session <name>        Use a named session (default: "default")
                           Built-in sessions: default, dev-server, browser-agent
 
 Examples:
@@ -67,10 +24,11 @@ Examples:
 
   libretto-cli exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
   libretto-cli exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
-  libretto-cli ai configure codex
-  libretto-cli ai configure claude
+  libretto-cli ai configure openai
+  libretto-cli ai configure anthropic
   libretto-cli ai configure gemini
-  libretto-cli ai configure <codex|claude|gemini> -- <command prefix...>
+  libretto-cli ai configure vertex
+  libretto-cli ai configure openai/gpt-4o
   libretto-cli snapshot
   libretto-cli snapshot --objective "Find the submit button" --context "Submitting a referral form, already filled in patient details"
   libretto-cli resume --session default
@@ -96,201 +54,103 @@ Sessions:
   Session state is stored in .libretto/sessions/<session>/state.json
   CLI logs are stored in .libretto/sessions/<session>/logs.jsonl
   Each session runs an isolated browser instance on a dynamic port.
-`);
+`;
 }
-function filterSessionArgs(args) {
-  const result = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--session") {
-      i++;
-    } else {
-      result.push(args[i]);
+function readSessionArgBeforePassthrough(rawArgs) {
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const token = rawArgs[index];
+    if (token === "--") return void 0;
+    if (token === "--session") {
+      const value2 = rawArgs[index + 1];
+      if (!value2 || value2 === "--" || value2.startsWith("--")) {
+        return null;
+      }
+      return value2;
     }
+    if (!token.startsWith("--session=")) continue;
+    const value = token.slice("--session=".length);
+    if (value.length === 0 || value === "--" || value.startsWith("--")) {
+      return null;
+    }
+    return value;
   }
-  return result;
+  return void 0;
 }
 function parseSessionForLog(rawArgs) {
-  const idx = rawArgs.indexOf("--session");
-  if (idx < 0) return null;
-  const value = rawArgs[idx + 1];
-  if (!value || value.startsWith("--") || CLI_COMMANDS.has(value)) {
-    return null;
+  const value = readSessionArgBeforePassthrough(rawArgs);
+  if (value === void 0 || value === null) {
+    return SESSION_DEFAULT;
   }
   try {
     validateSessionName(value);
     return value;
   } catch {
-    return null;
-  }
-}
-function hasExplicitSession(rawArgs) {
-  return rawArgs.includes("--session");
-}
-function randomSessionId() {
-  const digits = Math.floor(Math.random() * 1e4).toString().padStart(4, "0");
-  return `ses-${digits}`;
-}
-function generateSessionId() {
-  const activeSessions = new Set(listSessionsWithStateFile());
-  for (let attempt = 0; attempt < 1e4; attempt += 1) {
-    const candidate = randomSessionId();
-    if (!activeSessions.has(candidate)) {
-      return candidate;
-    }
+    return SESSION_DEFAULT;
   }
-  throw new Error(
-    "Could not generate an available session id. Close an existing session and try again."
-  );
 }
-function hasExecCodeArg(filteredArgs) {
-  for (let i = 1; i < filteredArgs.length; i += 1) {
-    const token = filteredArgs[i];
-    if (!token) continue;
-    if (token === "--") {
-      return filteredArgs.length > i + 1;
-    }
-    if (token === "--visualize") {
-      continue;
-    }
-    if (token === "--page") {
-      const maybeValue = filteredArgs[i + 1];
-      if (maybeValue && !maybeValue.startsWith("--")) {
-        i += 1;
-      }
-      continue;
-    }
-    if (token.startsWith("--page=")) {
-      continue;
-    }
-    if (token.startsWith("-")) {
-      continue;
-    }
-    return true;
+function validateLegacySessionArg(rawArgs) {
+  const value = readSessionArgBeforePassthrough(rawArgs);
+  if (value === void 0) return;
+  if (value === null) {
+    throw new Error(
+      "Usage: libretto-cli <command> [--session <name>]\nMissing or invalid --session value."
+    );
   }
-  return false;
+  validateSessionName(value);
 }
-function commandNeedsSession(command, rawArgs, filteredArgs) {
-  if (AUTO_SESSION_COMMANDS.has(command)) return false;
-  if (SESSION_OPTIONAL_COMMANDS.has(command)) return false;
-  if (command === "close" && rawArgs.includes("--all")) return false;
-  if (command === "close" && rawArgs.includes("--force")) return false;
-  if (command === "exec" && !hasExecCodeArg(filteredArgs)) return false;
-  if (command === "save" && filteredArgs.length <= 1) return false;
-  if (!CLI_COMMANDS.has(command)) return false;
-  return true;
+function initializeLogger(rawArgs) {
+  const sessionForLog = parseSessionForLog(rawArgs);
+  const logger = createLoggerForSession(sessionForLog);
+  logger.info("cli-start", {
+    args: rawArgs,
+    cwd: process.cwd(),
+    session: sessionForLog
+  });
+  return logger;
 }
-function resolveSessionArgs(rawArgs) {
-  const filtered = filterSessionArgs(rawArgs);
-  const command = filtered[0];
-  const explicitSession = parseSessionForLog(rawArgs);
-  if (!command) {
-    return {
-      args: rawArgs,
-      generatedSession: null,
-      resolvedSession: explicitSession
-    };
-  }
-  if (hasExplicitSession(rawArgs)) {
-    return {
-      args: rawArgs,
-      generatedSession: null,
-      resolvedSession: explicitSession
-    };
-  }
-  if (!AUTO_SESSION_COMMANDS.has(command)) {
-    return {
-      args: rawArgs,
-      generatedSession: null,
-      resolvedSession: null
-    };
+async function withCliLogger(rawArgs, run) {
+  const logger = initializeLogger(rawArgs);
+  try {
+    return await run(logger);
+  } finally {
+    await closeLogger(logger);
   }
-  const generatedSession = generateSessionId();
-  return {
-    args: [...rawArgs, "--session", generatedSession],
-    generatedSession,
-    resolvedSession: generatedSession
-  };
 }
-function createParser(logger) {
-  let parser = yargs(hideBin(process.argv)).scriptName("libretto-cli").parserConfiguration({ "populate--": true }).option("session", {
-    type: "string",
-    describe: "Use a named session",
-    global: true,
-    requiresArg: true
-  }).middleware((argv) => {
-    if (argv.session !== void 0) {
-      validateSessionName(String(argv.session));
-    }
-  }).exitProcess(false).help(false).version(false).fail((msg, err) => {
-    if (err) throw err;
-    throw new Error(msg || "Command failed");
-  });
-  parser = registerBrowserCommands(parser, logger);
-  parser = registerExecutionCommands(parser, logger);
-  parser = registerLogCommands(parser);
-  parser = registerAICommands(parser);
-  parser = registerSnapshotCommands(parser, logger);
-  parser = registerInitCommand(parser);
-  parser = parser.command("help", "Show usage", () => {
-  }, () => {
-    printUsage();
-  });
-  return parser;
+function isRootHelpRequest(rawArgs) {
+  if (rawArgs.length === 0) return true;
+  if (rawArgs[0] === "--help" || rawArgs[0] === "-h") return true;
+  return rawArgs[0] === "help" && rawArgs.length === 1;
 }
 async function runLibrettoCLI() {
   const rawArgs = process.argv.slice(2);
   let exitCode = 0;
-  let effectiveArgs = rawArgs;
-  let generatedSession = null;
-  let resolvedSession = null;
-  ({
-    args: effectiveArgs,
-    generatedSession,
-    resolvedSession
-  } = resolveSessionArgs(rawArgs));
   ensureLibrettoSetup();
-  const args = filterSessionArgs(effectiveArgs);
-  const command = args[0];
-  if (!command || command === "--help" || command === "-h" || command === "help") {
-    printUsage();
-    process.exit(exitCode);
-    return;
-  }
-  if (!CLI_COMMANDS.has(command)) {
-    console.error(`Unknown command: ${command}
+  await withCliLogger(rawArgs, async (logger) => {
+    const app = createCLIApp(logger);
+    try {
+      validateLegacySessionArg(rawArgs);
+      if (isRootHelpRequest(rawArgs)) {
+        console.log(renderUsage(app));
+        return;
+      }
+      logger.info("cli-command", { args: rawArgs });
+      const result = await app.run(rawArgs);
+      if (typeof result === "string") {
+        console.log(result);
+      }
+    } catch (err) {
+      logger.error("cli-error", { error: err, args: rawArgs });
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.startsWith("Unknown command: ")) {
+        console.error(`${message}
 `);
-    printUsage();
-    process.exit(1);
-    return;
-  }
-  if (!hasExplicitSession(effectiveArgs) && commandNeedsSession(command, effectiveArgs, args)) {
-    console.error(
-      [
-        `Missing required --session for "${command}".`,
-        "Pass --session <name>, or use open/run without --session to auto-create one."
-      ].join("\n")
-    );
-    process.exit(1);
-    return;
-  }
-  const sessionForLogger = resolvedSession ?? "cli";
-  const logger = createLoggerForSession(sessionForLogger);
-  try {
-    const parser = createParser(logger);
-    await parser.parseAsync(effectiveArgs);
-  } catch (err) {
-    logger.error("cli-error", {
-      error: err,
-      args: rawArgs,
-      effectiveArgs,
-      generatedSession
-    });
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(message);
-    exitCode = 1;
-  } finally {
-    await closeLogger(logger);
-  }
+        console.log(renderUsage(app));
+      } else {
+        console.error(message);
+      }
+      exitCode = 1;
+    }
+  });
   process.exit(exitCode);
 }
 export {

package/dist/cli/commands/ai.js

@@ -1,19 +1,35 @@
+import { z } from "zod";
 import { runAiConfigure } from "../core/ai-config.js";
-function registerAICommands(yargs) {
-  return yargs.command(
-    "ai configure [preset]",
-    "Configure AI model for snapshot analysis",
-    (cmd) => cmd.option("clear", { type: "boolean", default: false }),
-    (argv) => {
-      runAiConfigure({
-        clear: Boolean(argv.clear),
-        preset: argv.preset
-      }, {
-        configureCommandName: "npx libretto ai configure"
-      });
-    }
-  );
-}
+import { SimpleCLI } from "../framework/simple-cli.js";
+const aiConfigureInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("preset", z.string().optional(), {
+      help: "Provider shorthand or provider/model-id"
+    })
+  ],
+  named: {
+    clear: SimpleCLI.flag({ help: "Clear existing AI config" })
+  }
+});
+const aiCommands = SimpleCLI.group({
+  description: "AI commands",
+  routes: {
+    configure: SimpleCLI.command({
+      description: "Configure AI runtime"
+    }).input(aiConfigureInput).handle(async ({ input }) => {
+      runAiConfigure(
+        {
+          clear: input.clear,
+          preset: input.preset
+        },
+        {
+          configureCommandName: "libretto-cli ai configure"
+        }
+      );
+    })
+  }
+});
 export {
-  registerAICommands
+  aiCommands,
+  aiConfigureInput
 };

package/dist/cli/commands/browser.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import {
   runClose as runCloseWithLogger,
   runCloseAll as runCloseAllWithLogger,
@@ -6,91 +7,123 @@ import {
   runSave
 } from "../core/browser.js";
 import { withSessionLogger } from "../core/context.js";
-function registerBrowserCommands(yargs, logger) {
-  return yargs.command(
-    "open [url]",
-    "Launch browser and open URL (headed by default)",
-    (cmd) => cmd.option("headed", {
-      type: "boolean",
-      default: false
-    }).option("headless", {
-      type: "boolean",
-      default: false
-    }).option("viewport", {
-      type: "string",
-      describe: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)"
-    }),
-    async (argv) => {
-      const hasHeadedFlag = Boolean(argv.headed);
-      const hasHeadlessFlag = Boolean(argv.headless);
-      if (hasHeadedFlag && hasHeadlessFlag) {
-        throw new Error("Cannot pass both --headed and --headless.");
-      }
-      const headed = hasHeadedFlag || !hasHeadlessFlag;
-      const url = argv.url;
-      if (!url) {
-        throw new Error(
-          "Usage: libretto-cli open <url> [--headless] [--viewport WxH] [--session <name>]"
-        );
-      }
-      const viewportArg = argv.viewport;
-      let viewport;
-      if (viewportArg) {
-        const match = viewportArg.match(/^(\d+)x(\d+)$/i);
-        if (!match) {
-          throw new Error(
-            "Invalid --viewport format. Expected WIDTHxHEIGHT (e.g. 1920x1080)."
-          );
-        }
-        const w = Number(match[1]);
-        const h = Number(match[2]);
-        if (w < 1 || h < 1) {
-          throw new Error(
-            "Invalid --viewport dimensions. Width and height must be at least 1."
-          );
-        }
-        viewport = { width: w, height: h };
-      }
-      await runOpen(url, headed, String(argv.session), logger, { viewport });
-    }
-  ).command(
-    "save [urlOrDomain]",
-    "Save current browser session",
-    (cmd) => cmd,
-    async (argv) => {
-      const urlOrDomain = argv.urlOrDomain;
-      if (!urlOrDomain) {
-        throw new Error("Usage: libretto-cli save <url|domain> [--session <name>]");
-      }
-      await runSave(urlOrDomain, String(argv.session), logger);
+import { assertSessionAvailableForStart } from "../core/session.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+import {
+  loadSessionStateMiddleware,
+  resolveSessionMiddleware,
+  sessionOption
+} from "./shared.js";
+function parseViewportArg(viewportArg) {
+  if (!viewportArg) return void 0;
+  const match = viewportArg.match(/^(\d+)x(\d+)$/i);
+  if (!match) {
+    throw new Error(
+      "Invalid --viewport format. Expected WIDTHxHEIGHT (e.g. 1920x1080)."
+    );
+  }
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  if (width < 1 || height < 1) {
+    throw new Error(
+      "Invalid --viewport dimensions. Width and height must be at least 1."
+    );
+  }
+  return { width, height };
+}
+const openInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("url", z.string().optional(), {
+      help: "URL to open"
+    })
+  ],
+  named: {
+    session: sessionOption(),
+    headed: SimpleCLI.flag({ help: "Run browser in headed mode" }),
+    headless: SimpleCLI.flag({ help: "Run browser in headless mode" }),
+    viewport: SimpleCLI.option(z.string().optional(), {
+      help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)"
+    })
+  }
+}).refine(
+  (input) => Boolean(input.url),
+  "Usage: libretto-cli open <url> [--headless] [--viewport WxH] [--session <name>]"
+).refine(
+  (input) => !(input.headed && input.headless),
+  "Cannot pass both --headed and --headless."
+);
+function createOpenCommand(logger) {
+  return SimpleCLI.command({
+    description: "Launch browser and open URL (headed by default)"
+  }).input(openInput).use(resolveSessionMiddleware).handle(async ({ input, ctx }) => {
+    assertSessionAvailableForStart(ctx.session, logger);
+    const headed = input.headed || !input.headless;
+    const viewport = parseViewportArg(input.viewport);
+    await runOpen(input.url, headed, ctx.session, logger, { viewport });
+  });
+}
+const saveInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("urlOrDomain", z.string().optional(), {
+      help: "URL or domain to save"
+    })
+  ],
+  named: {
+    session: sessionOption()
+  }
+}).refine(
+  (input) => Boolean(input.urlOrDomain),
+  "Usage: libretto-cli save <url|domain> [--session <name>]"
+);
+function createSaveCommand(logger) {
+  return SimpleCLI.command({
+    description: "Save current browser session"
+  }).input(saveInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ input, ctx }) => {
+    await runSave(input.urlOrDomain, ctx.session, logger);
+  });
+}
+const pagesInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    session: sessionOption()
+  }
+});
+function createPagesCommand(logger) {
+  return SimpleCLI.command({
+    description: "List open pages in the session"
+  }).input(pagesInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ ctx }) => {
+    await runPages(ctx.session, logger);
+  });
+}
+const closeInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    session: sessionOption(),
+    all: SimpleCLI.flag({ help: "Close all tracked sessions in this workspace" }),
+    force: SimpleCLI.flag({ help: "Force kill sessions that ignore SIGTERM (requires --all)" })
+  }
+});
+function createCloseCommand(logger) {
+  return SimpleCLI.command({
+    description: "Close the browser"
+  }).input(closeInput).use(resolveSessionMiddleware).handle(async ({ input, ctx }) => {
+    if (input.force && !input.all) {
+      throw new Error("Usage: libretto-cli close --all [--force]");
     }
-  ).command("pages", "List open pages in the session", (cmd) => cmd, async (argv) => {
-    await runPages(String(argv.session), logger);
-  }).command(
-    "close",
-    "Close the browser",
-    (cmd) => cmd.option("all", {
-      type: "boolean",
-      default: false,
-      describe: "Close all tracked sessions in this workspace"
-    }).option("force", {
-      type: "boolean",
-      default: false,
-      describe: "Force kill sessions that ignore SIGTERM (requires --all)"
-    }),
-    async (argv) => {
-      const closeAll = Boolean(argv.all);
-      const force = Boolean(argv.force);
-      if (force && !closeAll) {
-        throw new Error("Usage: libretto-cli close --all [--force]");
-      }
-      if (closeAll) {
-        await runCloseAllWithLogger(logger, { force });
-        return;
-      }
-      await runCloseWithLogger(String(argv.session), logger);
+    if (input.all) {
+      await runCloseAllWithLogger(logger, { force: input.force });
+      return;
     }
-  );
+    await runCloseWithLogger(ctx.session, logger);
+  });
+}
+function createBrowserCommands(logger) {
+  return {
+    open: createOpenCommand(logger),
+    save: createSaveCommand(logger),
+    pages: createPagesCommand(logger),
+    close: createCloseCommand(logger)
+  };
 }
 async function runClose(session) {
   await withSessionLogger(session, async (logger) => {
@@ -98,6 +131,14 @@ async function runClose(session) {
   });
 }
 export {
-  registerBrowserCommands,
-  runClose
+  closeInput,
+  createBrowserCommands,
+  createCloseCommand,
+  createOpenCommand,
+  createPagesCommand,
+  createSaveCommand,
+  openInput,
+  pagesInput,
+  runClose,
+  saveInput
 };