libretto 0.4.4 → 0.5.0

package/skills/libretto/references/reverse-engineering-network-requests.md

@@ -0,0 +1,39 @@
+# Reverse Engineering Network Requests
+
+Use this reference when the user wants to turn a browser workflow into direct network requests.
+
+This is the default approach for new integrations when the site exposes a clear and stable HTTP request path.
+
+## When to Use This
+
+- The page clearly loads or submits data through HTTP requests.
+- The user can perform the workflow manually in a headed browser.
+- Replaying the request is likely faster or more stable than reproducing every UI action.
+- Fall back to browser automation when the request path is unclear, too dynamic, or blocked by anti-bot systems.
+
+## Workflow
+
+- Open the page in headed mode.
+- Let the user perform the relevant workflow manually.
+- Read the network log after the relevant step.
+- Identify the smallest set of requests that actually carries the data or performs the action.
+- Confirm with the user before replaying any request that could mutate data.
+- Recreate the request in code outside Libretto.
+- Verify the resulting workflow with `npx libretto run ...`.
+
+## Commands
+
+```bash
+npx libretto open https://target.example.com --headed
+npx libretto network --last 20
+npx libretto network --method POST --last 20
+npx libretto network --filter 'referral|patient|search'
+npx libretto exec "return await networkLog({ method: 'POST', last: 10 })"
+```
+
+## Notes
+
+- Start with the request that returns the data you need, not every request on the page.
+- Prefer captured requests over guessing payload shape.
+- If the request format is opaque, highly dynamic, or heavily defended, fall back to UI automation for that part.
+- Treat all replayed requests as potentially side-effectful until proven otherwise.

package/skills/libretto/references/user-action-log.md

@@ -0,0 +1,31 @@
+# User Action Log
+
+Use this reference when the user performs steps manually in a headed Libretto session and you want to incorporate those steps into a workflow.
+
+## When to Use This
+
+- The user demonstrates the workflow in the browser window.
+- You want to know what they clicked, typed, or selected.
+- You need to reconcile manual user actions with captured network requests.
+
+## Workflow
+
+- Open the session in headed mode.
+- Ask the user to perform the workflow.
+- Read the user action log after they finish.
+- Use the log to identify the important transitions in the workflow.
+- Combine the action log with `snapshot` or `network` when the log alone is not enough.
+
+## Commands
+
+```bash
+npx libretto actions --source user --last 20
+npx libretto actions --source user --filter 'button|input|select'
+npx libretto exec "return await actionLog({ source: 'user', last: 10 })"
+```
+
+## Notes
+
+- The action log is most useful for reconstructing the sequence of a workflow, not for discovering every selector you need.
+- If the user performed relevant manual steps, read the action log before writing or revising the workflow code.
+- Use the action log to anchor your understanding, then inspect the current page state with `snapshot` or `exec`.

package/src/cli/cli.ts

@@ -0,0 +1,173 @@
+import type { Logger } from "../shared/logger/index.js";
+import {
+  closeLogger,
+  createLoggerForSession,
+  ensureLibrettoSetup,
+} from "./core/context.js";
+import {
+  SESSION_DEFAULT,
+  validateSessionName,
+} from "./core/session.js";
+import { createCLIApp } from "./router.js";
+
+function renderUsage(app: ReturnType<typeof createCLIApp>): string {
+  return `${app.renderHelp()}
+
+Options:
+  --session <name>        Use a named session (default: "default")
+                          Built-in sessions: default, dev-server, browser-agent
+
+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 default
+  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 readSessionArgBeforePassthrough(
+  rawArgs: readonly string[],
+): string | null | undefined {
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const token = rawArgs[index];
+    if (token === "--") return undefined;
+    if (token === "--session") {
+      const value = rawArgs[index + 1];
+      if (!value || value === "--" || value.startsWith("--")) {
+        return null;
+      }
+      return value;
+    }
+    if (!token.startsWith("--session=")) continue;
+
+    const value = token.slice("--session=".length);
+    if (value.length === 0 || value === "--" || value.startsWith("--")) {
+      return null;
+    }
+    return value;
+  }
+
+  return undefined;
+}
+
+function parseSessionForLog(rawArgs: string[]): string {
+  const value = readSessionArgBeforePassthrough(rawArgs);
+  if (value === undefined || value === null) {
+    return SESSION_DEFAULT;
+  }
+  try {
+    validateSessionName(value);
+    return value;
+  } catch {
+    return SESSION_DEFAULT;
+  }
+}
+
+function validateLegacySessionArg(rawArgs: string[]): void {
+  const value = readSessionArgBeforePassthrough(rawArgs);
+  if (value === undefined) return;
+  if (value === null) {
+    throw new Error(
+      `Usage: libretto <command> [--session <name>]\nMissing or invalid --session value.`,
+    );
+  }
+  validateSessionName(value);
+}
+
+function initializeLogger(rawArgs: string[]): Logger {
+  const sessionForLog = parseSessionForLog(rawArgs);
+  const logger = createLoggerForSession(sessionForLog);
+  logger.info("cli-start", {
+    args: rawArgs,
+    cwd: process.cwd(),
+    session: sessionForLog,
+  });
+  return logger;
+}
+
+async function withCliLogger<T>(
+  rawArgs: string[],
+  run: (logger: Logger) => Promise<T>,
+): Promise<T> {
+  const logger = initializeLogger(rawArgs);
+  try {
+    return await run(logger);
+  } finally {
+    await closeLogger(logger);
+  }
+}
+
+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();
+  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}\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`,
+          },
+        );
+      }),
+  },
+});

package/src/cli/commands/browser.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import type { LoggerApi } from "../../shared/logger/index.js";
+import {
+  runClose as runCloseWithLogger,
+  runCloseAll as runCloseAllWithLogger,
+  runOpen,
+  runPages,
+  runSave,
+} from "../core/browser.js";
+import { withSessionLogger } from "../core/context.js";
+import { assertSessionAvailableForStart } from "../core/session.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+import {
+  loadSessionStateMiddleware,
+  resolveSessionMiddleware,
+  sessionOption,
+} from "./shared.js";
+
+function parseViewportArg(
+  viewportArg: string | undefined,
+): { width: number; height: number } | undefined {
+  if (!viewportArg) return undefined;
+
+  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 };
+}
+
+export 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 open <url> [--headless] [--viewport WxH] [--session <name>]`,
+  )
+  .refine(
+    (input) => !(input.headed && input.headless),
+    "Cannot pass both --headed and --headless.",
+  );
+
+export function createOpenCommand(logger: LoggerApi) {
+  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 });
+    });
+}
+
+export 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 save <url|domain> [--session <name>]`,
+);
+
+export function createSaveCommand(logger: LoggerApi) {
+  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);
+    });
+}
+
+export const pagesInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    session: sessionOption(),
+  },
+});
+
+export function createPagesCommand(logger: LoggerApi) {
+  return SimpleCLI.command({
+    description: "List open pages in the session",
+  })
+    .input(pagesInput)
+    .use(resolveSessionMiddleware)
+    .use(loadSessionStateMiddleware)
+    .handle(async ({ ctx }) => {
+      await runPages(ctx.session, logger);
+    });
+}
+
+export 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)" }),
+  },
+});
+
+export function createCloseCommand(logger: LoggerApi) {
+  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 close --all [--force]`);
+      }
+      if (input.all) {
+        await runCloseAllWithLogger(logger, { force: input.force });
+        return;
+      }
+      await runCloseWithLogger(ctx.session, logger);
+    });
+}
+
+export function createBrowserCommands(logger: LoggerApi) {
+  return {
+    open: createOpenCommand(logger),
+    save: createSaveCommand(logger),
+    pages: createPagesCommand(logger),
+    close: createCloseCommand(logger),
+  };
+}
+
+export async function runClose(session: string): Promise<void> {
+  await withSessionLogger(session, async (logger) => {
+    await runCloseWithLogger(session, logger);
+  });
+}