libretto 0.4.4 → 0.5.1

package/skills/libretto/{code-generation-rules.md → references/code-generation-rules.md}

@@ -2,6 +2,8 @@
 
 These rules apply when generating production TypeScript files from interactive browser sessions. Read this file before writing any production code.
 
+Follow the user's existing codebase conventions, abstractions, and patterns whenever possible. Do not introduce a new style unless the codebase does not already have a suitable one.
+
 ## Workflow File Structure
 
 Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <exportName>`. Import `workflow` and its types from `"libretto"`:
@@ -21,27 +23,27 @@ type Output = {
 };
 
 export const myWorkflow = workflow<Input, Output>(
-  {},
   async (ctx, input): Promise<Output> => {
-    const { page } = ctx;
+    const { session, page, logger } = ctx;
 
-    // workflow logic here — use ctx.page, ctx.logger, ctx.services
+    logger.info("workflow-start", { session, query: input.query });
     await page.goto("https://example.com");
-    // ...
+    await pause(session);
 
     return { results: [] };
   },
 );
 ```
 
-**Key points:**
+Key points:
 
 - The named export (e.g., `myWorkflow`) is what you pass as the second arg to `npx libretto run ./file.ts myWorkflow`
-- `ctx` provides `page`, `logger`, and `services` (generic, default `{}`)
+- `workflow(handler)` returns a branded workflow object with a `.run(ctx, input)` method. The CLI expects that contract.
+- `ctx` provides `session`, `page`, `logger`, and `services` (generic, default `{}`)
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
 - If the site requires a saved login session, pass `--auth-profile <domain>` to the CLI (created via `npx libretto save <domain>`)
-- Use `await pause()` (imported from `"libretto"`) to pause the workflow for debugging. It is a no-op in production.
-- The browser is launched and closed automatically by the CLI — do not launch or close it in the handler
+- Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.
+- The browser is launched and closed automatically by the CLI. Do not launch or close it in the handler.
 
 ## Passing Application Dependencies via Services
 
@@ -55,7 +57,6 @@ import { type Transaction } from "./db";
 type MyServices = { tx?: Transaction };
 
 export const myWorkflow = workflow<Input, Output, MyServices>(
-  {},
   async (ctx, input) => {
     if (ctx.services.tx) {
       await ctx.services.tx.insert(/* ... */);
@@ -71,7 +72,7 @@ In production, the caller passes services when invoking `.run()`:
 
 ```typescript
 await myWorkflow.run(
-  { page, logger, services: { tx } },
+  { session: "debug-flow", page, logger, services: { tx } },
   input,
 );
 ```
@@ -85,22 +86,6 @@ Generated code must use Playwright locator APIs for all DOM interactions. Do not
 
 During the interactive `exec` phase, `page.evaluate` is fine for quick prototyping. In generated production code, translate those patterns into Playwright locators.
 
-### Translation Table
-
-| Operation        | Interactive (`exec`)                                        | Production file                                                        |
-| ---------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Click            | `page.evaluate(() => document.getElementById('x').click())` | `page.locator('#x').click()`                                           |
-| Check state      | `page.evaluate(() => el.checked)`                           | `page.locator('#x').isChecked()`                                       |
-| Read text        | `page.evaluate(() => el.textContent)`                       | `page.locator('#x').textContent()`                                     |
-| Read all text    | `querySelectorAll(...).map(e => e.textContent)`             | `page.locator('.items').allTextContents()`                             |
-| Element position | `el.getBoundingClientRect()`                                | `page.locator('#x').boundingBox()`                                     |
-| Inline styles    | `el.style.top`                                              | `page.locator('#x').getAttribute('style')`                             |
-| Count elements   | `querySelectorAll(...).length`                              | `page.locator('.items').count()`                                       |
-| Select dropdown  | `selectEl.value = '...'`                                    | `page.locator('select').selectOption('...')`                           |
-| Iterate elements | `querySelectorAll(...).forEach(...)`                        | `const items = await locator.all(); for (const item of items) { ... }` |
-| Scoped query     | `parent.querySelector('.child')`                            | `parentLocator.locator('.child').textContent()`                        |
-| Batch extraction | `querySelectorAll('.item').forEach(e => { ... })`           | `for (const item of await locator.all()) { const text = await item.locator('.text').textContent(); ... }` |
-
 ### Anti-Patterns
 
 These patterns come up frequently during interactive sessions and should not carry over into production code:
@@ -116,10 +101,10 @@ const data = await page.evaluate(`(() => {
 })()`);
 
 // DO — Playwright locators with a loop
-const posts = await page.locator('.post').all();
+const posts = await page.locator(".post").all();
 for (const post of posts) {
-  const name = await post.locator('.name').textContent();
-  const content = await post.locator('.content').textContent();
+  const name = await post.locator(".name").textContent();
+  const content = await post.locator(".content").textContent();
 }
 ```
 
@@ -128,13 +113,13 @@ for (const post of posts) {
 const count = await el.evaluate(`(el) => el.querySelectorAll('.item').length`);
 
 // DO
-const count = await el.locator('.item').count();
+const count = await el.locator(".item").count();
 ```
 
 ```typescript
 // DON'T — evaluate to read scoped text
 const text = await post.evaluate(
-  `(el) => el.querySelector('[data-view-name="foo"]')?.textContent`
+  `(el) => el.querySelector('[data-view-name="foo"]')?.textContent`,
 );
 
 // DO
@@ -145,9 +130,9 @@ const text = await post.locator('[data-view-name="foo"]').textContent();
 
 Use `page.evaluate()` only for operations that have no Playwright locator equivalent:
 
-1. **Browser-native APIs** — `getComputedStyle()`, `window.*` globals, `document.cookie`, scroll position
-2. **In-browser `fetch()` calls** — making HTTP requests from the browser context
-3. **Parsing operations** — using `DOMParser` to parse HTML/XML strings inside the browser
+1. Browser-native APIs: `getComputedStyle()`, `window.*` globals, `document.cookie`, scroll position
+2. In-browser `fetch()` calls: making HTTP requests from the browser context
+3. Parsing operations: using `DOMParser` to parse HTML/XML strings inside the browser
 
 A quick test: if the evaluate body contains `querySelector`, `querySelectorAll`, `textContent`, `click()`, `getAttribute()`, or iterates DOM elements, it should be rewritten with Playwright locators.
 
@@ -198,23 +183,23 @@ class ApiClient {
 }
 ```
 
-One method per endpoint. No try-catch in API methods — let errors propagate to the orchestrator. Parse XML/HTML inside `page.evaluate()` with `DOMParser`. Use string expressions for `page.evaluate()` to avoid DOM type errors.
+One method per endpoint. No try/catch in API methods. Let errors propagate to the orchestrator. Parse XML/HTML inside `page.evaluate()` with `DOMParser`. Use string expressions for `page.evaluate()` to avoid DOM type errors.
 
 ## Comments
 
-Add comments throughout generated code to explain what each logical block is doing. Comments should describe **intent**, not restate the code. Group related actions under a single comment rather than commenting every line.
+Add comments throughout generated code to explain what each logical block is doing. Comments should describe intent, not restate the code. Group related actions under a single comment rather than commenting every line.
 
 ```typescript
 // Log in with credentials
-await page.locator('#username').fill(user);
-await page.locator('#password').fill(pass);
-await page.locator('#login').click();
+await page.locator("#username").fill(user);
+await page.locator("#password").fill(pass);
+await page.locator("#login").click();
 
 // Extract author and content from each feed post
-const posts = await page.locator('.post').all();
+const posts = await page.locator(".post").all();
 for (const post of posts) {
-  const name = await post.locator('.name').textContent();
-  const content = await post.locator('.content').textContent();
+  const name = await post.locator(".name").textContent();
+  const content = await post.locator(".content").textContent();
 }
 ```
 

package/skills/libretto/references/configuration-file-reference.md

@@ -0,0 +1,53 @@
+# Configuration File Reference
+
+Use this reference when you need to inspect or change the workspace configuration that powers `snapshot` analysis and default viewport behavior.
+
+## When to Use This
+
+- You want to confirm which AI model `snapshot` will use.
+- You want to understand where Libretto stores workspace-level settings.
+- You want a persistent default viewport for `open` or `run`.
+
+## File Location
+
+Libretto reads workspace config from `.libretto/config.json`.
+
+- The file is usually created or updated by `npx libretto ai configure ...`.
+- API credentials still come from your shell environment or `.env`. The config file stores the selected model, not the secret itself.
+- For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
+
+## Supported Settings
+
+- `ai.model` selects the configured analysis model for `snapshot`.
+- `viewport` is an optional top-level setting used by `open` and `run` when you do not pass `--viewport`.
+- Viewport precedence is: CLI `--viewport`, then `.libretto/config.json`, then the default `1366x768`.
+
+Example:
+
+```json
+{
+  "version": 1,
+  "ai": {
+    "model": "openai/gpt-5.4",
+    "updatedAt": "2026-01-01T00:00:00.000Z"
+  },
+  "viewport": {
+    "width": 1280,
+    "height": 800
+  }
+}
+```
+
+## Common Commands
+
+```bash
+npx libretto init
+npx libretto ai configure openai
+npx libretto open https://app.example.com --viewport 1440x900
+npx libretto run ./integration.ts main --viewport 1440x900
+```
+
+## Notes
+
+- If you want a persistent default viewport for the workspace, add `viewport` to `.libretto/config.json` instead of repeating `--viewport` on every command.
+- If `snapshot` analysis is not configured yet, return to the setup steps in the main `SKILL.md` flow.

package/skills/libretto/references/pages-and-page-targeting.md

@@ -0,0 +1,29 @@
+# Pages and Page Targeting
+
+Use this reference when a Libretto session has multiple open pages and you need to inspect or target the right one.
+
+## When to Use This
+
+- The workflow opens a popup, new tab, or secondary page.
+- `exec` or `snapshot` fails because more than one page is open.
+- You are not sure which page in the session holds the relevant state.
+
+## Workflow
+
+- List the open pages in the session.
+- Identify the page you want by URL.
+- Re-run the command against that page.
+
+## Commands
+
+```bash
+npx libretto pages --session debug-flow
+npx libretto exec --session debug-flow --page <page-id> "return await page.url()"
+npx libretto snapshot --session debug-flow --page <page-id> --objective "Find the active form"
+```
+
+## Notes
+
+- A session can contain more than one page.
+- When multiple pages are open, think about page targeting first before debugging selectors.
+- Use `pages` to resolve the correct page id, then pass `--page` to `exec`, `snapshot`, `network`, or `actions` when needed.

package/skills/libretto/references/site-security-review.md

@@ -0,0 +1,143 @@
+# Site Security Review
+
+Purpose: You are connected to a live Chrome session on a target website. Your job is to review the site's bot-detection and security posture before committing to an integration strategy. Probe for bot protection, fetch interception, and challenge flows, then use that review to decide which integration approaches are safe and which one to try first for this site.
+
+After completing the probes below, produce a Site Assessment Summary (see the output format at the end of this document).
+
+## Probing the Site
+
+Run these probes to build a picture of the site's detection posture. The examples below are starting points. Use your judgment to investigate further based on what you find. Sites may use detection methods not listed here.
+
+### Probe 1: Bot Protection Services and Security Signals
+
+Look for signs that the site uses bot protection, either a third-party service or custom detection. There is no complete list of indicators. These are common examples.
+
+Cookies to look for (examples, not exhaustive):
+
+| Cookie Pattern | Associated Service |
+| --- | --- |
+| `_abck` | Akamai Bot Manager |
+| `_px*` | PerimeterX (HUMAN) |
+| `datadome` | DataDome |
+| `cf_clearance` | Cloudflare |
+| `_imp_apg_r_*` | Shape Security (F5) |
+| `x-kpsdk-*` | Kasada |
+
+But do not just check this list. Examine all cookies on the page. Look for cookies with obfuscated names, telemetry-related prefixes, or values that look like fingerprint hashes or encrypted tokens. Unknown security cookies are still security cookies.
+
+Global variables to check (examples):
+
+```js
+window._pxAppId
+window.bmak
+window.ddjskey
+```
+
+Also examine the page's scripts. Look at the first `<script>` tags in the document source, and check what external domains scripts load from (for example `*.akamaized.net`, `*.perimeterx.net`, `*.datadome.co`, `*.kasada.io`). Bot protection scripts are typically injected before application code.
+
+Challenge pages:
+
+Check if the page is showing a challenge or interstitial instead of real content: "Checking your browser...", CAPTCHA iframes, or blank pages with only a spinner. These indicate active bot protection that has already been triggered.
+
+General guidance: determine whether the site has bot protection and roughly how aggressive it is. Do not limit yourself to known signatures. Look at overall page behavior, unusual scripts, and anything that seems like security telemetry.
+
+### Probe 2: Fetch and XHR Interception
+
+Check whether the site has monkey-patched `window.fetch` or `XMLHttpRequest`. If it has, making your own fetch calls from `page.evaluate()` is risky because the site can inspect call stacks and detect calls that do not originate from its own code.
+
+```js
+window.fetch.toString()
+XMLHttpRequest.prototype.open.toString()
+Object.getOwnPropertyDescriptor(window, 'fetch')
+window.fetch.hasOwnProperty('prototype')
+```
+
+Important: some sites use `Proxy` to wrap fetch, which makes `toString()` still return `"[native code]"`. The prototype check is a heuristic, not definitive. If you see any sign of fetch interception, treat it as patched.
+
+## Choosing a Data Capture Strategy
+
+Use the review above to decide what is safe to prioritize. Every integration uses Playwright to control the browser. The question is what to lean on for data capture: direct browser fetch calls, passive network interception, or DOM extraction. In practice, many integrations mix approaches, but the site-security review should tell you which approach is safest to try first.
+
+### Strategy A: Prioritize `page.evaluate(fetch(...))`
+
+Make fetch calls directly from within the browser's JavaScript context. The requests share the browser's TLS fingerprint, cookies, and origin. They look identical to requests the site's own JS would make.
+
+When to prioritize this:
+
+- No enterprise bot protection is detected
+- `fetch` is not monkey-patched
+- The API responses are parseable and useful
+- You need data that requires many API calls (deep pagination, bulk queries) where driving the UI would be slow
+
+Why: maximum control and efficiency. You call exactly the endpoints you want with the parameters you want, skip UI rendering, and get structured JSON back. On sites without aggressive detection, this is the fastest and cleanest approach.
+
+Risk: if the site monitors fetch call stacks, your calls may be flagged because they do not originate from the site's bundled code. This is uncommon but exists on high-security sites.
+
+You will still use Playwright for initial navigation, login/auth flows, cookie consent, and any UI interactions needed to establish session state before making fetch calls.
+
+### Strategy B: Prioritize `page.on('response', ...)`
+
+Listen to network responses that the browser naturally makes as you navigate. You do not make any extra requests. You capture data flowing through the site's own API calls.
+
+When to prioritize this:
+
+- Enterprise bot protection is detected
+- `fetch` is monkey-patched
+- The site's normal UI flow triggers API calls that return the data you need
+- You want to minimize detection risk as much as possible
+
+Why: zero additional network risk. The requests that happen are the ones the site's own code triggers. You are just listening. No anomalous call stacks, no unexpected request patterns, no extra fetch calls for monitoring to flag.
+
+Trade-off: you only get data the page naturally loads. If you need page 50 of results, you have to click "next" 49 times via Playwright. You must set up listeners before the navigation that triggers the requests.
+
+You will still use Playwright for all navigation and interaction to trigger the data-bearing API calls, plus any data that is not available via intercepted responses.
+
+### Strategy C: Prioritize Playwright DOM Extraction
+
+Extract data directly from the rendered page using selectors and `page.evaluate()` to read DOM content.
+
+When to prioritize this:
+
+- Data is server-rendered and no useful JSON API calls are observed
+- The site does not expose the data you need via any API
+- You need visual or layout information that only exists in the DOM
+- As a fallback when Strategies A and B cannot get specific pieces of data
+
+Why: it works regardless of the site's API architecture. If the data is visible on the page, you can extract it.
+
+Trade-off: it is slower, more fragile against DOM changes, and you only get data the UI renders.
+
+## Decision Summary
+
+| Site Profile | Primary Strategy | Supplement With |
+| --- | --- | --- |
+| No bot protection, fetch not patched | A (`page.evaluate(fetch)`) | Playwright for navigation/auth |
+| No bot protection, fetch is patched | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
+| Bot protection detected, fetch not patched | B (`page.on('response', ...)`) | Playwright for navigation; cautious use of `page.evaluate(fetch)` only if needed |
+| Bot protection detected, fetch is patched | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
+| Server-rendered content (no API calls) | C (DOM extraction) | Playwright for all interaction |
+
+## Output: Site Assessment Summary
+
+After running the probes, produce a summary in this format. This assessment tells you what is safe to try first, not what will definitely work for every endpoint.
+
+```text
+## Site Assessment: [site URL]
+
+### Bot Detection Profile
+- Enterprise bot protection: [None detected / Detected — describe what you found]
+- Fetch/XHR interception: [Native (not patched) / Patched — describe what you found]
+- Challenge pages: [None / Present — describe type]
+- Overall security posture: [None / Low / Moderate / High / Very High]
+
+### API Surface
+- API calls observed: [List key endpoints discovered, or "None — content appears server-rendered"]
+- Data format: [JSON / GraphQL / HTML fragments / Other]
+- Pagination: [Describe how pagination works if applicable]
+
+### Safe Approaches
+- `page.evaluate(fetch(...))`: [Safe / Unsafe — brief rationale]
+- `page.on('response', ...)`: [Viable / Not viable — note if response formats are parseable]
+- DOM extraction: [Always available as fallback]
+- Interaction notes: [any behavioral precautions]
+```

package/src/cli/cli.ts

@@ -0,0 +1,86 @@
+import { ensureLibrettoSetup } from "./core/context.js";
+import { createCLIApp } from "./router.js";
+
+function renderUsage(app: ReturnType<typeof createCLIApp>): string {
+  return `${app.renderHelp()}
+
+Options:
+  --session <name>        Use a named session (auto-generated for open/run if omitted)
+
+Examples:
+  libretto open https://linkedin.com
+
+  # ... manually log in ...
+  libretto save linkedin.com
+  # Next time you open linkedin.com, you'll be logged in automatically
+
+  libretto exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
+  libretto exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
+  libretto ai configure openai
+  libretto ai configure anthropic
+  libretto ai configure gemini
+  libretto ai configure vertex
+  libretto ai configure openai/gpt-4o
+  libretto snapshot
+  libretto snapshot --objective "Find the submit button" --context "Submitting a referral form, already filled in patient details"
+  libretto resume --session my-session
+  libretto close
+  libretto close --all
+  libretto close --all --force
+
+  # Multiple sessions
+  libretto open https://site1.com --session test1
+  libretto open https://site2.com --session test2
+  libretto exec "return await page.title()" --session test1
+
+Available in exec:
+  page, context, state, browser, networkLog, actionLog
+
+Profiles:
+  Profiles are saved to .libretto/profiles/<domain>.json (git-ignored)
+  They persist cookies, localStorage, and session data across browser launches.
+  Local profiles are machine-local and are not shared with other users/environments.
+  Sessions can expire; if run fails auth, log in again and re-save the profile.
+
+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 isRootHelpRequest(rawArgs: readonly string[]): boolean {
+  if (rawArgs.length === 0) return true;
+  if (rawArgs[0] === "--help" || rawArgs[0] === "-h") return true;
+  return rawArgs[0] === "help" && rawArgs.length === 1;
+}
+
+export async function runLibrettoCLI(): Promise<void> {
+  const rawArgs = process.argv.slice(2);
+  let exitCode = 0;
+  ensureLibrettoSetup();
+  const app = createCLIApp();
+
+  try {
+    if (isRootHelpRequest(rawArgs)) {
+      console.log(renderUsage(app));
+      return;
+    }
+
+    const result = await app.run(rawArgs);
+    if (typeof result === "string") {
+      console.log(result);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.startsWith("Unknown command: ")) {
+      console.error(`${message}\n`);
+      console.log(renderUsage(app));
+    } else {
+      console.error(message);
+    }
+    exitCode = 1;
+  }
+
+  process.exit(exitCode);
+}

package/src/cli/commands/ai.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { runAiConfigure } from "../core/ai-config.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+
+export 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" }),
+  },
+});
+
+export 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 ai configure`,
+          },
+        );
+      }),
+  },
+});