libretto 0.5.3-experimental.6 → 0.5.3

package/README.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/libretto/README.template.md by `pnpm sync:mirrors`. Do not edit directly. -->
+
 # Libretto
 
 [![npm version](https://img.shields.io/npm/v/libretto)](https://www.npmjs.com/package/libretto)
@@ -152,6 +154,9 @@ Source layout:
 - `src/runtime/` — browser runtime (network, recovery, downloads, extraction)
 - `src/shared/` — shared utilities (config, LLM client, logging, state)
 - `test/` — test files (`*.spec.ts`)
-- `skills/libretto/` — source of truth for the Libretto skill; mirrors are synced on `pnpm i`
+- `README.template.md` — source of truth for the repo and package READMEs
+- `skills/libretto/` — source of truth for the Libretto skill
+
+Run `pnpm sync:mirrors` after editing `README.template.md` or anything under `skills/libretto/`. `pnpm i` also resyncs the skill mirrors through `postinstall`.
 
-To check that skill mirrors are in sync without fixing them, run `pnpm check:skills`. To release, run `pnpm prepare-release`.
+To check that generated READMEs, skill mirrors, and skill version metadata are in sync without fixing them, run `pnpm check:mirrors`. To release, run `pnpm prepare-release`.

package/README.template.md

@@ -0,0 +1,160 @@
+# Libretto
+
+[![npm version](https://img.shields.io/npm/v/libretto)](https://www.npmjs.com/package/libretto)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Discussions](https://img.shields.io/github/discussions/saffron-health/libretto)](https://github.com/saffron-health/libretto/discussions)
+
+Libretto is a toolkit for building robust web integrations. It gives your coding agent a live browser and a token-efficient CLI to:
+
+- Inspect live pages with minimal context overhead
+- Capture network traffic to reverse-engineer site APIs
+- Record user actions and replay them as automation scripts
+- Debug broken workflows interactively against the real site
+
+We at [Saffron Health](https://saffron.health) built Libretto to help us maintain our browser integrations to common healthcare software. We're open-sourcing it so other teams have an easier time doing the same thing.
+
+https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
+
+## Installation
+
+```bash
+npm install libretto
+
+# Install skill, download Chromium if not already installed, configure snapshot analysis
+npx libretto init
+
+# Configure or change the snapshot analysis model (see Configuration section below). `npx libretto init` sets this up the first time.
+npx libretto ai configure <openai | anthropic | gemini | vertex>
+```
+
+## Use cases
+
+Libretto is designed to be used as a skill through your coding agent. Here are some example prompts:
+
+### One-shot script generation
+
+> Use the Libretto skill. Go on LinkedIn and scrape the first 10 posts for content, who posted it, the number of reactions, the first 25 comments, and the first 25 reposts.
+
+Your coding agent will open a window for you to log into LinkedIn, and then automatically start exploring.
+
+### Interactive script building
+
+> I'm gonna show you a workflow in the eclinicalworks EHR to get a patient's primary insurance ID. Use libretto skill to turn it into a playwright script that takes patient name and dob as input to get back the insurance ID. URL is ...
+
+Libretto can read your actions you perform in the browser, so you can perform a workflow, then ask it to use your actions to rebuild the workflow.
+
+### Convert browser automation to network requests
+
+> We have a browser script at ./integration.ts that automates going to Hacker News and getting the first 10 posts. Convert it to direct network scripts instead. Use the Libretto skill.
+
+Libretto can read network requests from the browser, which it can use to reverse engineer the API and create a script that directly calls those requests. Directly making API calls is faster, and more reliable, than UI automation. You can also ask Libretto to conduct a security analysis which analyzes the requests for common security cookies, so you can understand whether a network request approach will be safe.
+
+### Fix broken integrations
+
+> We have a browser script at ./integration.ts that is supposed to go to Availity and perform an eligibility check for a patient. But I'm getting a broken selector error when I run it. Fix it. Use the Libretto skill.
+
+Agents can use Libretto to reproduce the failure, pause the workflow at any point, inspect the live page, and fix issues, all autonomously.
+
+### CLI usage
+
+You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
+
+```bash
+npx libretto init                          # interactive; run yourself, not through an agent
+npx libretto open <url>                    # launch browser and open a URL (headed by default)
+npx libretto snapshot --objective "..." --context "..."  # capture PNG + HTML and analyze with an LLM
+npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page (single quoted argument)
+echo "<code>" | npx libretto exec -        # intentionally read Playwright TypeScript from stdin
+npx libretto run <file> <workflowName>     # run an exported workflow from a file
+npx libretto resume                        # resume a paused workflow
+npx libretto network                       # view captured network requests
+npx libretto actions                       # view captured user/agent actions
+npx libretto pages                         # list open pages in the session
+npx libretto save <domain>                 # save browser session (cookies, localStorage) for reuse
+npx libretto close                         # close the browser
+npx libretto ai configure <provider>       # configure snapshot analysis model
+```
+
+## Configuration
+
+All Libretto state lives in a `.libretto/` directory at your project root. Configuration is stored in `.libretto/config.json`.
+
+### Config file
+
+`.libretto/config.json` controls snapshot analysis and viewport settings:
+
+```json
+{
+  "version": 1,
+  "ai": {
+    "model": "openai/gpt-5.4",
+    "updatedAt": "2026-01-01T00:00:00.000Z"
+  },
+  "viewport": { "width": 1280, "height": 800 }
+}
+```
+
+The `ai` field configures which model Libretto uses for snapshot analysis — extracting selectors, identifying interactive elements, or diagnosing why a step failed. This keeps heavy visual context out of your coding agent's context window. Snapshot analysis is required.
+
+The easiest way to set the model is through the CLI:
+
+```bash
+npx libretto ai configure <openai | anthropic | gemini | vertex>
+```
+
+Provider credentials are read from environment variables or a `.env` file at your project root: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex.
+
+The `viewport` field sets the default browser viewport size. Both fields are optional.
+
+### Sessions
+
+Each Libretto session gets its own directory under `.libretto/sessions/<name>/` containing runtime state. Sessions are git-ignored.
+
+- `state.json` — session metadata (debug port, PID, status)
+- `logs.jsonl` — structured session logs
+- `network.jsonl` — captured network requests
+- `actions.jsonl` — recorded user actions
+- `snapshots/` — screenshot PNGs and HTML snapshots
+
+### Profiles
+
+Profiles save browser sessions (cookies, localStorage) so you can reuse authenticated state across runs. They are stored in `.libretto/profiles/<domain>.json`, created via `npx libretto save <domain>`. Profiles are machine-local and git-ignored.
+
+## Community
+
+Have a question, idea, or want to share what you've built? Join the conversation on [GitHub Discussions](https://github.com/saffron-health/libretto/discussions).
+
+- **[Q&A](https://github.com/saffron-health/libretto/discussions/categories/q-a)** — Ask questions and get help
+- **[Ideas](https://github.com/saffron-health/libretto/discussions/categories/ideas)** — Suggest new features or improvements
+- **[Show and tell](https://github.com/saffron-health/libretto/discussions/categories/show-and-tell)** — Share your workflows and automations
+- **[General](https://github.com/saffron-health/libretto/discussions/categories/general)** — Chat about anything Libretto-related
+
+Found a bug? Please [open an issue](https://github.com/saffron-health/libretto/issues/new).
+
+## Authors
+
+Maintained by the team at [Saffron Health](https://saffron.health).
+
+## Development
+
+For local development in this repository:
+
+```bash
+pnpm i
+pnpm build
+pnpm type-check
+pnpm test
+```
+
+Source layout:
+
+- `{{LIBRETTO_PATH_PREFIX}}src/cli/` — CLI commands
+- `{{LIBRETTO_PATH_PREFIX}}src/runtime/` — browser runtime (network, recovery, downloads, extraction)
+- `{{LIBRETTO_PATH_PREFIX}}src/shared/` — shared utilities (config, LLM client, logging, state)
+- `{{LIBRETTO_PATH_PREFIX}}test/` — test files (`*.spec.ts`)
+- `{{LIBRETTO_PATH_PREFIX}}README.template.md` — source of truth for the repo and package READMEs
+- `{{LIBRETTO_PATH_PREFIX}}skills/libretto/` — source of truth for the Libretto skill
+
+Run `pnpm sync:mirrors` after editing `{{LIBRETTO_PATH_PREFIX}}README.template.md` or anything under `{{LIBRETTO_PATH_PREFIX}}skills/libretto/`. `pnpm i` also resyncs the skill mirrors through `postinstall`.
+
+To check that generated READMEs, skill mirrors, and skill version metadata are in sync without fixing them, run `pnpm check:mirrors`. To release, run `pnpm prepare-release`.

package/dist/cli/commands/deploy.js

@@ -80,7 +80,7 @@ const deployInput = SimpleCLI.input({
   }
 });
 const deployCommand = SimpleCLI.command({
-  description: "[experimental] Deploy workflows to the hosted platform",
+  description: "Deploy workflows to the hosted platform",
   experimental: true
 }).input(deployInput).handle(async ({ input }) => {
   const { apiUrl, apiKey } = getConfig();

package/dist/cli/commands/execution.js

@@ -448,7 +448,6 @@ async function runIntegrationFromFile(args, logger) {
     workflowName: args.workflowName,
     session: args.session,
     params: args.params,
-    credentials: args.credentials,
     headless: args.headless,
     visualize: args.visualize,
     authProfileDomain: args.authProfileDomain,
@@ -542,7 +541,7 @@ const execCommand = SimpleCLI.command({
     input.page
   );
 });
-const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--credentials <json>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
+const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
 const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {
@@ -561,9 +560,6 @@ const runInput = SimpleCLI.input({
       name: "params-file",
       help: "Path to a JSON params file"
     }),
-    credentials: SimpleCLI.option(z.string().optional(), {
-      help: "Inline JSON credentials passed to ctx.credentials"
-    }),
     tsconfig: SimpleCLI.option(z.string().optional(), {
       help: "Path to a tsconfig used for workflow module resolution"
     }),
@@ -614,11 +610,6 @@ const runCommand = SimpleCLI.command({
   await stopExistingFailedRunSession(ctx.session, ctx.logger);
   assertSessionAvailableForStart(ctx.session, ctx.logger);
   const params = resolveRunParams(input.params, input.paramsFile);
-  const rawCredentials = input.credentials ? parseJsonArg("--credentials", input.credentials) : void 0;
-  if (rawCredentials !== void 0 && (typeof rawCredentials !== "object" || rawCredentials === null || Array.isArray(rawCredentials))) {
-    throw new Error(`--credentials must be a JSON object (e.g., '{"key": "value"}').`);
-  }
-  const credentials = rawCredentials;
   const headlessMode = input.headed ? false : input.headless ? true : void 0;
   const visualize = !input.noVisualize;
   const viewport = resolveViewport(
@@ -631,7 +622,6 @@ const runCommand = SimpleCLI.command({
       workflowName: input.workflowName,
       session: ctx.session,
       params,
-      credentials,
       tsconfigPath: input.tsconfig,
       headless: headlessMode ?? false,
       visualize,

package/dist/cli/framework/simple-cli.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+const EXPERIMENTAL_COMMAND_PREFIX = "experimental";
+const EXPERIMENTAL_GROUP_DESCRIPTION = "Experimental commands";
 function toCamelCase(input2) {
   return input2.replace(
     /-([a-zA-Z0-9])/g,
@@ -420,7 +422,7 @@ class SimpleCLIApp {
   }
   renderRootHelp() {
     const lines = [`Usage: ${this.name} <command>`, "", "Commands:"];
-    for (const entry of this.getImmediateRouteEntries([])) {
+    for (const entry of this.getRootHelpEntries()) {
       lines.push(formatListEntry(entry.label, entry.description));
     }
     return lines.join("\n");
@@ -493,7 +495,6 @@ class SimpleCLIApp {
         continue;
       }
       const command2 = this.findCommandByPath(routeEntry.path);
-      if (command2?.experimental) continue;
       entries.push({
         label: token,
         description: command2?.description
@@ -501,6 +502,41 @@ class SimpleCLIApp {
     }
     return entries;
   }
+  getRootHelpEntries() {
+    return this.getImmediateRouteEntries([]).filter((entry) => {
+      const token = entry.label.replace(/\s+<subcommand>$/, "");
+      const group2 = this.findGroupByPath([token]);
+      if (!group2) {
+        return true;
+      }
+      if (token === EXPERIMENTAL_COMMAND_PREFIX) {
+        return this.groupHasExperimentalCommand(group2.path);
+      }
+      return this.groupHasVisibleNonExperimentalCommand(group2.path);
+    });
+  }
+  groupHasVisibleNonExperimentalCommand(path) {
+    for (const routeEntry of this.routeEntries) {
+      if (routeEntry.kind !== "command") continue;
+      if (!pathStartsWith(routeEntry.path, path)) continue;
+      const command2 = this.findCommandByPath(routeEntry.path);
+      if (command2 && !command2.experimental) {
+        return true;
+      }
+    }
+    return false;
+  }
+  groupHasExperimentalCommand(path) {
+    for (const routeEntry of this.routeEntries) {
+      if (routeEntry.kind !== "command") continue;
+      if (!pathStartsWith(routeEntry.path, path)) continue;
+      const command2 = this.findCommandByPath(routeEntry.path);
+      if (command2?.experimental) {
+        return true;
+      }
+    }
+    return false;
+  }
   findBestMatchingCommand(args) {
     let bestMatch = null;
     for (const command2 of this.resolvedCommands.values()) {
@@ -600,31 +636,38 @@ function validateRequiredNamedArgs(definitions, named) {
     throw new Error(`Missing required option --${flagName}.`);
   }
 }
-function resolveRouteTree(routes, parentPath = [], parentMiddlewares = []) {
+function resolveRouteTree(routes) {
+  const collected = collectRouteTree(routes);
+  const { groups, routeEntries } = buildResolvedRouteEntries(
+    collected.commands,
+    collected.groupDescriptions
+  );
+  return {
+    commands: collected.commands,
+    groups,
+    routeEntries
+  };
+}
+function collectRouteTree(routes, parentPath = [], parentMiddlewares = []) {
   const resolved = {
     commands: [],
-    groups: [],
-    routeEntries: []
+    groupDescriptions: /* @__PURE__ */ new Map()
   };
   for (const [token, routeValue] of Object.entries(routes)) {
     if (isGroup(routeValue)) {
       const groupPath = [...parentPath, token];
-      resolved.groups.push({
-        routeKey: pathToRouteKey(groupPath),
-        path: groupPath,
-        description: routeValue.description
-      });
-      resolved.routeEntries.push({
-        kind: "group",
-        path: groupPath
-      });
-      const nested = resolveRouteTree(routeValue.routes, groupPath, [
+      resolved.groupDescriptions.set(
+        pathToRouteKey(groupPath),
+        routeValue.description
+      );
+      const nested = collectRouteTree(routeValue.routes, groupPath, [
         ...parentMiddlewares,
         ...routeValue.middlewares
       ]);
       resolved.commands.push(...nested.commands);
-      resolved.groups.push(...nested.groups);
-      resolved.routeEntries.push(...nested.routeEntries);
+      for (const [routeKey, description] of nested.groupDescriptions) {
+        resolved.groupDescriptions.set(routeKey, description);
+      }
       continue;
     }
     const command2 = routeValue.getDefinition();
@@ -633,7 +676,8 @@ function resolveRouteTree(routes, parentPath = [], parentMiddlewares = []) {
         `Command "${[...parentPath, token].join(" ")}" is missing a handler.`
       );
     }
-    const path = [...parentPath, token];
+    const rawPath = [...parentPath, token];
+    const path = command2.config.experimental ? [EXPERIMENTAL_COMMAND_PREFIX, ...rawPath] : rawPath;
     resolved.commands.push({
       routeKey: pathToRouteKey(path),
       path,
@@ -646,12 +690,43 @@ function resolveRouteTree(routes, parentPath = [], parentMiddlewares = []) {
       ),
       handler: command2.handler
     });
-    resolved.routeEntries.push({
+  }
+  return resolved;
+}
+function buildResolvedRouteEntries(commands, groupDescriptions) {
+  const groups = /* @__PURE__ */ new Map();
+  const routeEntries = [];
+  for (const command2 of commands) {
+    for (let depth = 1; depth < command2.path.length; depth += 1) {
+      const path = command2.path.slice(0, depth);
+      const routeKey = pathToRouteKey(path);
+      if (groups.has(routeKey)) continue;
+      groups.set(routeKey, {
+        routeKey,
+        path,
+        description: resolveGroupDescription(path, groupDescriptions)
+      });
+      routeEntries.push({
+        kind: "group",
+        path
+      });
+    }
+    routeEntries.push({
       kind: "command",
-      path
+      path: command2.path
     });
   }
-  return resolved;
+  return {
+    groups: [...groups.values()],
+    routeEntries
+  };
+}
+function resolveGroupDescription(path, groupDescriptions) {
+  if (path.length === 1 && path[0] === EXPERIMENTAL_COMMAND_PREFIX) {
+    return EXPERIMENTAL_GROUP_DESCRIPTION;
+  }
+  const originalPath = path[0] === EXPERIMENTAL_COMMAND_PREFIX ? path.slice(1) : path;
+  return groupDescriptions.get(pathToRouteKey(originalPath));
 }
 function mergeInheritedMiddlewares(parentMiddlewares, commandMiddlewares) {
   if (parentMiddlewares.length === 0) {

package/dist/cli/router.js

@@ -8,12 +8,12 @@ import { snapshotCommand } from "./commands/snapshot.js";
 import { SimpleCLI } from "./framework/simple-cli.js";
 const cliRoutes = {
   ...browserCommands,
+  deploy: deployCommand,
   ...executionCommands,
   ...logCommands,
   ai: aiCommands,
   init: initCommand,
-  snapshot: snapshotCommand,
-  deploy: deployCommand
+  snapshot: snapshotCommand
 };
 function createCLIApp() {
   return SimpleCLI.define("libretto", cliRoutes);

package/dist/cli/workers/run-integration-runtime.js

@@ -176,8 +176,7 @@ async function runIntegrationInternal(args, options) {
   const workflowContext = {
     session: args.session,
     logger: integrationLogger,
-    page: browserSession.page,
-    credentials: args.credentials
+    page: browserSession.page
   };
   try {
     try {

package/dist/cli/workers/run-integration-worker-protocol.js

@@ -4,7 +4,6 @@ const RunIntegrationWorkerRequestSchema = z.object({
   workflowName: z.string().min(1),
   session: z.string().min(1),
   params: z.unknown(),
-  credentials: z.record(z.string(), z.unknown()).optional(),
   headless: z.boolean(),
   visualize: z.boolean().default(true),
   authProfileDomain: z.string().optional(),

package/dist/shared/workflow/workflow.d.ts

@@ -6,7 +6,6 @@ type LibrettoWorkflowContext = {
     session: string;
     page: Page;
     logger: MinimalLogger;
-    credentials?: Record<string, unknown>;
 };
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (ctx: LibrettoWorkflowContext, input: Input) => Promise<Output>;
 declare class LibrettoWorkflow<Input = unknown, Output = unknown> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.5.3-experimental.6",
+  "version": "0.5.3",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -31,8 +31,10 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "sync-skills": "node scripts/sync-skills.mjs",
-    "check:skills": "node scripts/check-skills-sync.mjs",
+    "sync:mirrors": "node ../dev-tools/scripts/sync-mirrors.mjs",
+    "check:mirrors": "node ../dev-tools/scripts/check-mirrors-sync.mjs",
+    "sync-skills": "pnpm run sync:mirrors",
+    "check:skills": "pnpm run check:mirrors",
     "build": "tsup --config tsup.config.ts",
     "type-check": "tsc --noEmit",
     "test": "pnpm run build && vitest run",

package/scripts/skills-libretto.mjs

@@ -1,14 +1,6 @@
 #!/usr/bin/env node
 
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-} from "node:fs";
-import { relative, resolve, join } from "node:path";
+import { cpSync, mkdirSync, rmSync } from "node:fs";
 
 export const SKILL_DIRS = [
   "packages/libretto/skills/libretto",
@@ -16,88 +8,8 @@ export const SKILL_DIRS = [
   ".claude/skills/libretto",
 ];
 
-function walkFiles(dir, baseDir = dir) {
-  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
-    a.name.localeCompare(b.name),
-  );
-  const files = [];
-
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...walkFiles(fullPath, baseDir));
-      continue;
-    }
-    if (entry.isFile()) files.push(relative(baseDir, fullPath));
-  }
-
-  return files;
-}
-
 export function syncSkillDir(sourceDir, destDir) {
   rmSync(destDir, { recursive: true, force: true });
   mkdirSync(destDir, { recursive: true });
   cpSync(sourceDir, destDir, { recursive: true });
 }
-
-export function syncRepoSkills(repoRoot) {
-  const sourceDir = resolve(repoRoot, "skills/libretto");
-  for (const dir of SKILL_DIRS.slice(1)) {
-    syncSkillDir(sourceDir, resolve(repoRoot, dir));
-  }
-}
-
-export function compareSkillDirs(repoRoot) {
-  const roots = SKILL_DIRS.map((dir) => ({
-    label: dir,
-    absPath: resolve(repoRoot, dir),
-  }));
-  const missing = roots.filter(({ absPath }) => !existsSync(absPath));
-  const mismatches = [];
-
-  if (missing.length > 0) {
-    return {
-      ok: false,
-      issues: missing.map(({ label }) => `missing directory: ${label}`),
-    };
-  }
-
-  const expectedFiles = walkFiles(roots[0].absPath);
-  const expectedFileSet = new Set(expectedFiles);
-
-  for (const root of roots.slice(1)) {
-    const actualFiles = walkFiles(root.absPath);
-    const actualFileSet = new Set(actualFiles);
-
-    for (const file of expectedFiles) {
-      if (!actualFileSet.has(file)) {
-        mismatches.push(`${root.label} is missing file: ${file}`);
-      }
-    }
-
-    for (const file of actualFiles) {
-      if (!expectedFileSet.has(file)) {
-        mismatches.push(`${root.label} has unexpected file: ${file}`);
-      }
-    }
-  }
-
-  for (const file of expectedFiles) {
-    const expectedContent = readFileSync(join(roots[0].absPath, file));
-    for (const root of roots.slice(1)) {
-      const targetPath = join(root.absPath, file);
-      if (!existsSync(targetPath)) continue;
-      const actualContent = readFileSync(targetPath);
-      if (!expectedContent.equals(actualContent)) {
-        mismatches.push(
-          `${root.label} differs from ${roots[0].label}: ${file}`,
-        );
-      }
-    }
-  }
-
-  return {
-    ok: mismatches.length === 0,
-    issues: mismatches,
-  };
-}

package/skills/libretto/SKILL.md

@@ -4,7 +4,7 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.4.2"
+  version: "0.5.3"
 ---
 
 ## How Libretto Works

package/skills/libretto/references/code-generation-rules.md

@@ -40,7 +40,7 @@ Key points:
 
 - `workflow(name, handler)` takes a unique workflow name and returns the workflow object that Libretto can run.
 - `npx libretto run ./file.ts myWorkflow` resolves `myWorkflow` from the workflows exported by `./file.ts`, so export or re-export the workflow from that file directly or through a `workflows` object, and make sure the run argument matches the name passed to `workflow("myWorkflow", ...)`.
-- `ctx` provides `session`, `page`, `logger`, and optional `credentials`
+- `ctx` provides `session`, `page`, and `logger`
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
 - Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.
 - After validation is complete and the workflow is confirmed working end to end, remove all `pause()` calls and pause-only workflow params unless the user explicitly says to keep them.

package/src/cli/commands/deploy.ts

@@ -121,7 +121,7 @@ export const deployInput = SimpleCLI.input({
 });
 
 export const deployCommand = SimpleCLI.command({
-  description: "[experimental] Deploy workflows to the hosted platform",
+  description: "Deploy workflows to the hosted platform",
   experimental: true,
 })
   .input(deployInput)

package/src/cli/commands/execution.ts

@@ -608,7 +608,6 @@ async function runIntegrationFromFile(
     workflowName: args.workflowName,
     session: args.session,
     params: args.params,
-    credentials: args.credentials,
     headless: args.headless,
     visualize: args.visualize,
     authProfileDomain: args.authProfileDomain,
@@ -707,7 +706,7 @@ export const execCommand = SimpleCLI.command({
     );
   });
 
-const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--credentials <json>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
+const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
 
 export const runInput = SimpleCLI.input({
   positionals: [
@@ -727,9 +726,6 @@ export const runInput = SimpleCLI.input({
       name: "params-file",
       help: "Path to a JSON params file",
     }),
-    credentials: SimpleCLI.option(z.string().optional(), {
-      help: "Inline JSON credentials passed to ctx.credentials",
-    }),
     tsconfig: SimpleCLI.option(z.string().optional(), {
       help: "Path to a tsconfig used for workflow module resolution",
     }),
@@ -792,13 +788,6 @@ export const runCommand = SimpleCLI.command({
     assertSessionAvailableForStart(ctx.session, ctx.logger);
 
     const params = resolveRunParams(input.params, input.paramsFile);
-    const rawCredentials = input.credentials
-      ? parseJsonArg("--credentials", input.credentials)
-      : undefined;
-    if (rawCredentials !== undefined && (typeof rawCredentials !== "object" || rawCredentials === null || Array.isArray(rawCredentials))) {
-      throw new Error("--credentials must be a JSON object (e.g., '{\"key\": \"value\"}').");
-    }
-    const credentials = rawCredentials as Record<string, unknown> | undefined;
     const headlessMode = input.headed
       ? false
       : input.headless
@@ -816,7 +805,6 @@ export const runCommand = SimpleCLI.command({
         workflowName: input.workflowName!,
         session: ctx.session,
         params,
-        credentials,
         tsconfigPath: input.tsconfig,
         headless: headlessMode ?? false,
         visualize,

package/src/cli/framework/simple-cli.ts

@@ -129,6 +129,11 @@ type InternalResolvedRouteEntry = {
   path: readonly string[];
 };
 
+type CollectedRouteTreeResult = {
+  commands: InternalResolvedCommand[];
+  groupDescriptions: Map<string, string | undefined>;
+};
+
 type ResolveRouteTreeResult = {
   commands: InternalResolvedCommand[];
   groups: InternalResolvedGroup[];
@@ -150,6 +155,9 @@ type ExtractedGlobalArgs = {
   named: Readonly<Record<string, unknown>>;
 };
 
+const EXPERIMENTAL_COMMAND_PREFIX = "experimental";
+const EXPERIMENTAL_GROUP_DESCRIPTION = "Experimental commands";
+
 function toCamelCase(input: string): string {
   return input.replace(/-([a-zA-Z0-9])/g, (_match, letter: string) =>
     letter.toUpperCase(),
@@ -761,7 +769,7 @@ export class SimpleCLIApp {
 
   private renderRootHelp(): string {
     const lines = [`Usage: ${this.name} <command>`, "", "Commands:"];
-    for (const entry of this.getImmediateRouteEntries([])) {
+    for (const entry of this.getRootHelpEntries()) {
       lines.push(formatListEntry(entry.label, entry.description));
     }
     return lines.join("\n");
@@ -860,7 +868,6 @@ export class SimpleCLIApp {
       }
 
       const command = this.findCommandByPath(routeEntry.path);
-      if (command?.experimental) continue;
       entries.push({
         label: token,
         description: command?.description,
@@ -870,6 +877,49 @@ export class SimpleCLIApp {
     return entries;
   }
 
+  private getRootHelpEntries(): Array<{
+    label: string;
+    description?: string;
+  }> {
+    return this.getImmediateRouteEntries([]).filter((entry) => {
+      const token = entry.label.replace(/\s+<subcommand>$/, "");
+      const group = this.findGroupByPath([token]);
+      if (!group) {
+        return true;
+      }
+      if (token === EXPERIMENTAL_COMMAND_PREFIX) {
+        return this.groupHasExperimentalCommand(group.path);
+      }
+      return this.groupHasVisibleNonExperimentalCommand(group.path);
+    });
+  }
+
+  private groupHasVisibleNonExperimentalCommand(path: readonly string[]): boolean {
+    for (const routeEntry of this.routeEntries) {
+      if (routeEntry.kind !== "command") continue;
+      if (!pathStartsWith(routeEntry.path, path)) continue;
+      const command = this.findCommandByPath(routeEntry.path);
+      if (command && !command.experimental) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private groupHasExperimentalCommand(path: readonly string[]): boolean {
+    for (const routeEntry of this.routeEntries) {
+      if (routeEntry.kind !== "command") continue;
+      if (!pathStartsWith(routeEntry.path, path)) continue;
+      const command = this.findCommandByPath(routeEntry.path);
+      if (command?.experimental) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   private findBestMatchingCommand(
     args: readonly string[],
   ): InternalResolvedCommand | null {
@@ -1034,37 +1084,46 @@ function validateRequiredNamedArgs(
   }
 }
 
-function resolveRouteTree(
+function resolveRouteTree(routes: SimpleCLIRouteTree<any>): ResolveRouteTreeResult {
+  const collected = collectRouteTree(routes);
+  const { groups, routeEntries } = buildResolvedRouteEntries(
+    collected.commands,
+    collected.groupDescriptions,
+  );
+
+  return {
+    commands: collected.commands,
+    groups,
+    routeEntries,
+  };
+}
+
+function collectRouteTree(
   routes: SimpleCLIRouteTree<any>,
   parentPath: readonly string[] = [],
   parentMiddlewares: readonly AnySimpleCLIMiddleware[] = [],
-): ResolveRouteTreeResult {
-  const resolved: ResolveRouteTreeResult = {
+): CollectedRouteTreeResult {
+  const resolved: CollectedRouteTreeResult = {
     commands: [],
-    groups: [],
-    routeEntries: [],
+    groupDescriptions: new Map<string, string | undefined>(),
   };
 
   for (const [token, routeValue] of Object.entries(routes)) {
     if (isGroup(routeValue)) {
       const groupPath = [...parentPath, token];
-      resolved.groups.push({
-        routeKey: pathToRouteKey(groupPath),
-        path: groupPath,
-        description: routeValue.description,
-      });
-      resolved.routeEntries.push({
-        kind: "group",
-        path: groupPath,
-      });
+      resolved.groupDescriptions.set(
+        pathToRouteKey(groupPath),
+        routeValue.description,
+      );
 
-      const nested = resolveRouteTree(routeValue.routes, groupPath, [
+      const nested = collectRouteTree(routeValue.routes, groupPath, [
         ...parentMiddlewares,
         ...routeValue.middlewares,
       ]);
       resolved.commands.push(...nested.commands);
-      resolved.groups.push(...nested.groups);
-      resolved.routeEntries.push(...nested.routeEntries);
+      for (const [routeKey, description] of nested.groupDescriptions) {
+        resolved.groupDescriptions.set(routeKey, description);
+      }
       continue;
     }
 
@@ -1075,7 +1134,10 @@ function resolveRouteTree(
       );
     }
 
-    const path = [...parentPath, token];
+    const rawPath = [...parentPath, token];
+    const path = command.config.experimental
+      ? [EXPERIMENTAL_COMMAND_PREFIX, ...rawPath]
+      : rawPath;
     resolved.commands.push({
       routeKey: pathToRouteKey(path),
       path,
@@ -1092,13 +1154,58 @@ function resolveRouteTree(
         unknown
       >,
     });
-    resolved.routeEntries.push({
+  }
+
+  return resolved;
+}
+
+function buildResolvedRouteEntries(
+  commands: readonly InternalResolvedCommand[],
+  groupDescriptions: ReadonlyMap<string, string | undefined>,
+): Pick<ResolveRouteTreeResult, "groups" | "routeEntries"> {
+  const groups = new Map<string, InternalResolvedGroup>();
+  const routeEntries: InternalResolvedRouteEntry[] = [];
+
+  for (const command of commands) {
+    for (let depth = 1; depth < command.path.length; depth += 1) {
+      const path = command.path.slice(0, depth);
+      const routeKey = pathToRouteKey(path);
+      if (groups.has(routeKey)) continue;
+
+      groups.set(routeKey, {
+        routeKey,
+        path,
+        description: resolveGroupDescription(path, groupDescriptions),
+      });
+      routeEntries.push({
+        kind: "group",
+        path,
+      });
+    }
+
+    routeEntries.push({
       kind: "command",
-      path,
+      path: command.path,
     });
   }
 
-  return resolved;
+  return {
+    groups: [...groups.values()],
+    routeEntries,
+  };
+}
+
+function resolveGroupDescription(
+  path: readonly string[],
+  groupDescriptions: ReadonlyMap<string, string | undefined>,
+): string | undefined {
+  if (path.length === 1 && path[0] === EXPERIMENTAL_COMMAND_PREFIX) {
+    return EXPERIMENTAL_GROUP_DESCRIPTION;
+  }
+
+  const originalPath =
+    path[0] === EXPERIMENTAL_COMMAND_PREFIX ? path.slice(1) : path;
+  return groupDescriptions.get(pathToRouteKey(originalPath));
 }
 
 function mergeInheritedMiddlewares(

package/src/cli/router.ts

@@ -9,12 +9,12 @@ import { SimpleCLI } from "./framework/simple-cli.js";
 
 export const cliRoutes = {
   ...browserCommands,
+  deploy: deployCommand,
   ...executionCommands,
   ...logCommands,
   ai: aiCommands,
   init: initCommand,
   snapshot: snapshotCommand,
-  deploy: deployCommand,
 };
 
 export function createCLIApp() {

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

@@ -257,7 +257,6 @@ async function runIntegrationInternal(
     session: args.session,
     logger: integrationLogger,
     page: browserSession.page,
-    credentials: args.credentials,
   };
 
   try {

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

@@ -5,7 +5,6 @@ export const RunIntegrationWorkerRequestSchema = z.object({
   workflowName: z.string().min(1),
   session: z.string().min(1),
   params: z.unknown(),
-  credentials: z.record(z.string(), z.unknown()).optional(),
   headless: z.boolean(),
   visualize: z.boolean().default(true),
   authProfileDomain: z.string().optional(),

package/src/shared/workflow/workflow.ts

@@ -7,7 +7,6 @@ export type LibrettoWorkflowContext = {
   session: string;
   page: Page;
   logger: MinimalLogger;
-  credentials?: Record<string, unknown>;
 };
 
 export type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (

package/scripts/check-skills-sync.mjs

@@ -1,25 +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/sync-skills.mjs

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { SKILL_DIRS, syncRepoSkills } from "./skills-libretto.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const repoRoot = join(__dirname, "..", "..", "..");
-
-syncRepoSkills(repoRoot);
-console.log(`libretto: synced skill mirrors across ${SKILL_DIRS.join(", ")}`);