libretto 0.3.1 → 0.4.0

package/README.md

@@ -6,21 +6,18 @@ It is designed for engineering teams that automate workflows in web apps and wan
 
 ## Installation
 
-Install Libretto in your project with your favorite package manager:
-
 ```bash
-npm install libretto playwright zod
-yarn add libretto playwright zod
-bun add libretto playwright zod
-pnpm add libretto playwright zod
+npm install --save-dev libretto
 ```
 
-Then initialize Libretto:
+Chromium is downloaded automatically via a `postinstall` script. If postinstall scripts are disabled (e.g. `--ignore-scripts`, common in monorepos), run init manually:
 
 ```bash
 npx libretto init
 ```
 
+This installs the Chromium browser binary and optionally configures an AI subagent (Gemini, Claude, or Codex) that can analyze page snapshots without consuming the coding agent's context window.
+
 ## Usage
 
 Libretto is usually used through prompts with the Libretto skill.
@@ -56,6 +53,19 @@ npx libretto help
 npx libretto run ./integration.ts main
 ```
 
+## The `.libretto/` directory
+
+Libretto stores local runtime state in a `.libretto/` directory at your project root. Sensitive directories (`sessions/` and `profiles/`) are automatically git-ignored via `.libretto/.gitignore`.
+
+- **`profiles/<domain>.json`** — Saved browser sessions (cookies, localStorage) for authenticated sites. Created via `npx libretto save <domain>`. Machine-local and never committed.
+- **`sessions/<name>/`** — Per-session runtime state:
+  - `state.json` — Session metadata (debug port, PID, status)
+  - `logs.jsonl` — Structured session logs
+  - `network.jsonl` — Captured network requests (URLs, methods, headers, response status)
+  - `actions.jsonl` — Recorded user actions (clicks, fills, navigations)
+  - `snapshots/` — Screenshot PNGs and HTML snapshots captured via `npx libretto snapshot`
+- **`ai.json`** — AI runtime configuration set via `npx libretto ai configure`.
+
 ## Authors
 
 Maintained by the team at [Saffron Health](https://saffron.health).

package/dist/cli/commands/ai.js

@@ -2,16 +2,14 @@ import { runAiConfigure } from "../core/ai-config.js";
 function registerAICommands(yargs) {
   return yargs.command(
     "ai configure [preset]",
-    "Configure AI runtime",
+    "Configure AI model for snapshot analysis",
     (cmd) => cmd.option("clear", { type: "boolean", default: false }),
     (argv) => {
-      const customPrefix = Array.isArray(argv["--"]) ? argv["--"] : [];
       runAiConfigure({
         clear: Boolean(argv.clear),
-        preset: argv.preset,
-        customPrefix
+        preset: argv.preset
       }, {
-        configureCommandName: "libretto-cli ai configure"
+        configureCommandName: "npx libretto ai configure"
       });
     }
   );

package/dist/cli/commands/browser.js

@@ -16,6 +16,9 @@ function registerBrowserCommands(yargs, logger) {
     }).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);
@@ -27,10 +30,28 @@ function registerBrowserCommands(yargs, logger) {
       const url = argv.url;
       if (!url) {
         throw new Error(
-          "Usage: libretto-cli open <url> [--headless] [--session <name>]"
+          "Usage: libretto-cli open <url> [--headless] [--viewport WxH] [--session <name>]"
         );
       }
-      await runOpen(url, headed, String(argv.session), logger);
+      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]",

package/dist/cli/commands/init.js

@@ -1,67 +1,169 @@
-import { accessSync, constants, statSync } from "node:fs";
-import { join, delimiter, extname } from "node:path";
+import { createInterface } from "node:readline";
+import { existsSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { join } from "node:path";
 import {
-  AI_CONFIG_PRESETS,
-  AiPresetSchema,
-  formatCommandPrefix,
   readAiConfig
 } from "../core/ai-config.js";
-const AI_RUNTIME_PRESETS = AiPresetSchema.options;
-function getPresetCommand(preset) {
-  return AI_CONFIG_PRESETS[preset][0] ?? "";
+import { REPO_ROOT } from "../core/context.js";
+import {
+  loadSnapshotEnv,
+  resolveSnapshotApiModel
+} from "../core/snapshot-api-config.js";
+import { hasProviderCredentials } from "../../shared/llm/client.js";
+const PROVIDER_CHOICES = [
+  {
+    key: "1",
+    label: "OpenAI",
+    envVar: "OPENAI_API_KEY",
+    envHint: "Get your key at https://platform.openai.com/api-keys"
+  },
+  {
+    key: "2",
+    label: "Anthropic",
+    envVar: "ANTHROPIC_API_KEY",
+    envHint: "Get your key at https://console.anthropic.com/settings/keys"
+  },
+  {
+    key: "3",
+    label: "Google Gemini",
+    envVar: "GEMINI_API_KEY",
+    envHint: "Get your key at https://aistudio.google.com/apikey"
+  },
+  {
+    key: "4",
+    label: "Google Vertex AI",
+    envVar: "GOOGLE_CLOUD_PROJECT",
+    envHint: "Requires gcloud auth application-default login and a GCP project ID"
+  }
+];
+function promptUser(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
 }
-function isRunnableFile(filePath) {
+function safeReadAiConfig() {
   try {
-    const stats = statSync(filePath);
-    if (!stats.isFile()) return false;
-    if (process.platform === "win32") {
-      const pathExt = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
-      const extensions = pathExt.split(";").map((ext) => ext.trim().toUpperCase()).filter(Boolean);
-      const fileExt = extname(filePath).toUpperCase();
-      return extensions.includes(fileExt);
-    }
-    accessSync(filePath, constants.X_OK);
-    return true;
+    return readAiConfig();
   } catch {
-    return false;
+    return null;
   }
 }
-function isCommandDefined(command) {
-  if (!command) return false;
-  if (command.includes("/") || command.includes("\\")) {
-    return isRunnableFile(command);
-  }
-  const pathEnv = process.env.PATH ?? "";
-  if (!pathEnv) return false;
-  const pathEntries = pathEnv.split(delimiter).filter(Boolean);
-  if (process.platform === "win32") {
-    const pathExt = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
-    const extensions = pathExt.split(";").map((ext) => ext.trim()).filter(Boolean);
-    const hasExtension = /\.[^./\\]+$/.test(command);
-    const candidates = hasExtension ? [command] : extensions.map(
-      (ext) => ext.startsWith(".") ? `${command}${ext}` : `${command}.${ext}`
-    );
-    return pathEntries.some(
-      (dir) => candidates.some((candidate) => isRunnableFile(join(dir, candidate)))
+function printSnapshotApiStatus() {
+  const config = safeReadAiConfig();
+  const selection = resolveSnapshotApiModel(config);
+  const envPath = join(REPO_ROOT, ".env");
+  console.log("\nSnapshot analysis:");
+  console.log(
+    "  Libretto uses direct API calls for snapshot analysis when supported credentials are available."
+  );
+  console.log(`  Credentials are loaded from process env and ${envPath}.`);
+  if (selection && hasProviderCredentials(selection.provider)) {
+    console.log(
+      `  \u2713 Ready: ${selection.model} (${selection.source})`
     );
+    console.log("    Snapshot objectives will use the API analyzer by default.");
+    console.log("    No further action required.");
+    return;
   }
-  return pathEntries.some((dir) => isRunnableFile(join(dir, command)));
-}
-function detectAvailableAiRuntimeCommands() {
-  return AI_RUNTIME_PRESETS.filter(
-    (preset) => isCommandDefined(getPresetCommand(preset))
+  console.log("  \u2717 No snapshot API credentials detected.");
+  console.log("    Add one provider to .env:");
+  console.log("      OPENAI_API_KEY=...");
+  console.log("      ANTHROPIC_API_KEY=...");
+  console.log("      GEMINI_API_KEY=...  # or GOOGLE_GENERATIVE_AI_API_KEY");
+  console.log(
+    "      GOOGLE_CLOUD_PROJECT=...  # plus application default credentials for Vertex"
   );
+  console.log(
+    "    Or run `npx libretto ai configure <provider>` to set a specific model."
+  );
+  console.log("    Run `npx libretto init` interactively to set up credentials.");
 }
-function printAiConfigureCommands(prefix = "    ") {
-  for (const preset of AI_RUNTIME_PRESETS) {
-    console.log(`${prefix}npx libretto ai configure ${preset}`);
-  }
-}
-function printDifferentAnalyzerHint(prefix = "    ") {
+async function runInteractiveApiSetup() {
+  const config = safeReadAiConfig();
+  const selection = resolveSnapshotApiModel(config);
+  const envPath = join(REPO_ROOT, ".env");
+  console.log("\nSnapshot analysis setup:");
   console.log(
-    `${prefix}Use npx libretto ai configure <gemini|claude|codex> to configure a different AI analyzer.`
+    "  Libretto uses direct API calls for snapshot analysis."
   );
+  console.log(`  Credentials are loaded from process env and ${envPath}.`);
+  if (selection && hasProviderCredentials(selection.provider)) {
+    console.log(
+      `  \u2713 Ready: ${selection.model} (${selection.source})`
+    );
+    console.log("    Snapshot objectives will use the API analyzer by default.");
+    return;
+  }
+  console.log("  \u2717 No snapshot API credentials detected.\n");
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    console.log("  Which API provider would you like to use for snapshot analysis?\n");
+    for (const choice of PROVIDER_CHOICES) {
+      console.log(`    ${choice.key}) ${choice.label}`);
+    }
+    console.log("    s) Skip for now\n");
+    const answer = await promptUser(rl, "  Choice: ");
+    if (answer.toLowerCase() === "s" || !answer) {
+      console.log("\n  Skipped. You can set up API credentials later by rerunning `npx libretto init`.");
+      console.log("  Or add credentials directly to your .env file:");
+      console.log("    OPENAI_API_KEY=...");
+      console.log("    ANTHROPIC_API_KEY=...");
+      console.log("    GEMINI_API_KEY=...");
+      console.log(
+        "    Or run `npx libretto ai configure <provider>` to set a specific model."
+      );
+      return;
+    }
+    const selected = PROVIDER_CHOICES.find((c) => c.key === answer);
+    if (!selected) {
+      console.log(`
+  Unknown choice "${answer}". Skipping API setup.`);
+      return;
+    }
+    console.log(`
+  ${selected.label} selected.`);
+    console.log(`  ${selected.envHint}
+`);
+    const apiKeyValue = await promptUser(rl, `  Enter your ${selected.envVar}: `);
+    if (!apiKeyValue) {
+      console.log("\n  No value entered. Skipping API key setup.");
+      return;
+    }
+    let envContent = "";
+    if (existsSync(envPath)) {
+      envContent = readFileSync(envPath, "utf-8");
+    }
+    const envLine = `${selected.envVar}=${apiKeyValue}`;
+    if (envContent.includes(`${selected.envVar}=`)) {
+      const updated = envContent.replace(
+        new RegExp(`^${selected.envVar}=.*$`, "m"),
+        () => envLine
+      );
+      writeFileSync(envPath, updated);
+      console.log(`
+  \u2713 Updated ${selected.envVar} in ${envPath}`);
+    } else {
+      const separator = envContent && !envContent.endsWith("\n") ? "\n" : "";
+      appendFileSync(envPath, `${separator}${envLine}
+`);
+      console.log(`
+  \u2713 Added ${selected.envVar} to ${envPath}`);
+    }
+    loadSnapshotEnv();
+    process.env[selected.envVar] = apiKeyValue;
+    const newSelection = resolveSnapshotApiModel(safeReadAiConfig());
+    if (newSelection && hasProviderCredentials(newSelection.provider)) {
+      console.log(`  \u2713 Snapshot API ready: ${newSelection.model}`);
+    }
+  } finally {
+    rl.close();
+  }
 }
 function installBrowsers() {
   console.log("\nInstalling Playwright Chromium...");
@@ -77,69 +179,6 @@ function installBrowsers() {
     );
   }
 }
-function checkAiRuntimeConfiguration() {
-  let config = null;
-  let configReadError = null;
-  try {
-    config = readAiConfig();
-  } catch (error) {
-    configReadError = error instanceof Error ? error.message : String(error);
-  }
-  const availableCommands = detectAvailableAiRuntimeCommands();
-  console.log("\nAI runtime configuration:");
-  console.log(
-    "  Libretto can use your coding agent as a subagent to analyze snapshots and other page signals."
-  );
-  console.log(
-    "  This is optional, but it significantly improves page understanding and debugging performance."
-  );
-  if (configReadError) {
-    console.log(`  \u2717 Could not read AI config: ${configReadError}`);
-    console.log("    Reconfigure with:");
-    printAiConfigureCommands("      ");
-    printDifferentAnalyzerHint("    ");
-    return;
-  }
-  if (config) {
-    const configuredCommand = config.commandPrefix[0];
-    if (!isCommandDefined(configuredCommand)) {
-      console.log(
-        `  \u2717 Configured command not found: ${configuredCommand ?? "(empty)"}`
-      );
-      if (availableCommands.length > 0) {
-        console.log(
-          `    Detected available commands: ${availableCommands.join(", ")}`
-        );
-      } else {
-        console.log(
-          "    No codex, claude, or gemini analyzer command was detected on PATH."
-        );
-      }
-      console.log("    Reconfigure with:");
-      printAiConfigureCommands("      ");
-      printDifferentAnalyzerHint("    ");
-      return;
-    }
-    console.log(
-      `  \u2713 Configured (${config.preset}): ${formatCommandPrefix(config.commandPrefix)}`
-    );
-    console.log("    Analysis commands are ready to use.");
-    printDifferentAnalyzerHint("    ");
-    return;
-  }
-  console.log("  \u2717 No AI config set.");
-  if (availableCommands.length > 0) {
-    console.log(
-      `    Detected available commands: ${availableCommands.join(", ")}`
-    );
-  } else {
-    console.log("    No codex, claude, or gemini analyzer command was detected on PATH.");
-  }
-  console.log("    Configure one with:");
-  printAiConfigureCommands("      ");
-  printDifferentAnalyzerHint("    ");
-  console.log("    Optionally provide a custom command prefix with '-- ...'.");
-}
 function registerInitCommand(yargs) {
   return yargs.command(
     "init",
@@ -149,14 +188,18 @@ function registerInitCommand(yargs) {
       default: false,
       describe: "Skip Playwright Chromium installation"
     }),
-    (argv) => {
+    async (argv) => {
       console.log("Initializing libretto...\n");
       if (!argv["skip-browsers"]) {
         installBrowsers();
       } else {
         console.log("\nSkipping browser installation (--skip-browsers)");
       }
-      checkAiRuntimeConfiguration();
+      if (process.stdin.isTTY) {
+        await runInteractiveApiSetup();
+      } else {
+        printSnapshotApiStatus();
+      }
       console.log("\n\u2713 libretto init complete");
     }
   );

package/dist/cli/commands/snapshot.js

@@ -1,14 +1,69 @@
 import { mkdirSync } from "node:fs";
 import { connect, disconnectBrowser } from "../core/browser.js";
 import { getSessionSnapshotRunDir } from "../core/context.js";
-import {
-  canAnalyzeSnapshots,
-  runInterpret
-} from "../core/snapshot-analyzer.js";
+import { condenseDom } from "../../shared/condense-dom/condense-dom.js";
+import { readSessionState } from "../core/session.js";
+import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
+import { readAiConfig } from "../core/ai-config.js";
 const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
+const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function generateSnapshotRunId() {
   return `snapshot-${Date.now()}`;
 }
+function isZeroViewport(value) {
+  return typeof value === "number" && value <= 0;
+}
+function shouldForceSnapshotViewport(metrics) {
+  return isZeroViewport(metrics.configuredWidth) || isZeroViewport(metrics.configuredHeight) || isZeroViewport(metrics.innerWidth) || isZeroViewport(metrics.innerHeight);
+}
+function isZeroWidthScreenshotError(error) {
+  return error instanceof Error && error.message.includes("Cannot take screenshot with 0 width");
+}
+async function readSnapshotViewportMetrics(page) {
+  const configuredViewport = page.viewportSize();
+  let innerWidth = null;
+  let innerHeight = null;
+  try {
+    const innerViewport = await page.evaluate(() => ({
+      width: window.innerWidth,
+      height: window.innerHeight
+    }));
+    innerWidth = innerViewport.width;
+    innerHeight = innerViewport.height;
+  } catch {
+  }
+  return {
+    configuredWidth: configuredViewport?.width ?? null,
+    configuredHeight: configuredViewport?.height ?? null,
+    innerWidth,
+    innerHeight
+  };
+}
+function resolveSnapshotViewport(session, logger) {
+  const state = readSessionState(session, logger);
+  if (state?.viewport) {
+    logger.info("screenshot-viewport-from-session-state", {
+      session,
+      viewport: state.viewport
+    });
+    return state.viewport;
+  }
+  logger.info("screenshot-viewport-fallback", {
+    session,
+    reason: "no viewport in session state",
+    viewport: FALLBACK_SNAPSHOT_VIEWPORT
+  });
+  return FALLBACK_SNAPSHOT_VIEWPORT;
+}
+async function forceSnapshotViewport(page, viewport, logger, session, pageId, reason) {
+  await page.setViewportSize(viewport);
+  logger.warn("screenshot-viewport-forced", {
+    session,
+    pageId,
+    reason,
+    viewport
+  });
+}
 async function captureScreenshot(session, logger, pageId) {
   logger.info("screenshot-start", { session, pageId });
   const snapshotRunId = generateSnapshotRunId();
@@ -19,23 +74,81 @@ async function captureScreenshot(session, logger, pageId) {
     requireSinglePage: true
   });
   try {
-    const title = await page.title();
-    const pageUrl = page.url();
+    let title = null;
+    try {
+      title = await page.title();
+    } catch (error) {
+      logger.warn("screenshot-title-read-failed", {
+        session,
+        pageId,
+        error
+      });
+    }
+    let pageUrl = null;
+    try {
+      pageUrl = page.url();
+    } catch (error) {
+      logger.warn("screenshot-url-read-failed", {
+        session,
+        pageId,
+        error
+      });
+    }
     const pngPath = `${snapshotRunDir}/page.png`;
     const htmlPath = `${snapshotRunDir}/page.html`;
-    await page.screenshot({ path: pngPath });
+    const condensedHtmlPath = `${snapshotRunDir}/page.condensed.html`;
+    const restoreViewport = resolveSnapshotViewport(session, logger);
+    const viewportMetrics = await readSnapshotViewportMetrics(page);
+    logger.info("screenshot-viewport-metrics", {
+      session,
+      pageId,
+      restoreViewport,
+      ...viewportMetrics
+    });
+    await forceSnapshotViewport(
+      page,
+      restoreViewport,
+      logger,
+      session,
+      pageId,
+      shouldForceSnapshotViewport(viewportMetrics) ? "preflight-invalid-viewport" : "preflight-normalize-viewport"
+    );
+    try {
+      await page.screenshot({ path: pngPath });
+    } catch (error) {
+      if (!isZeroWidthScreenshotError(error)) {
+        throw error;
+      }
+      await forceSnapshotViewport(
+        page,
+        restoreViewport,
+        logger,
+        session,
+        pageId,
+        "retry-after-zero-width-screenshot-error"
+      );
+      await page.screenshot({ path: pngPath });
+    }
     const htmlContent = await page.content();
     const fs = await import("node:fs/promises");
     await fs.writeFile(htmlPath, htmlContent);
+    const condenseResult = condenseDom(htmlContent);
+    await fs.writeFile(condensedHtmlPath, condenseResult.html);
     logger.info("screenshot-success", {
       session,
       pageUrl,
       title,
       pngPath,
       htmlPath,
-      snapshotRunId
+      condensedHtmlPath,
+      snapshotRunId,
+      domCondenseStats: {
+        originalLength: condenseResult.originalLength,
+        condensedLength: condenseResult.condensedLength,
+        reductions: condenseResult.reductions
+      }
     });
-    return { pngPath, htmlPath, baseName: snapshotRunId };
+    return { pngPath, htmlPath, condensedHtmlPath, baseName: snapshotRunId };
   } catch (err) {
     let pageAlive = false;
     let browserConnected = false;
@@ -49,7 +162,13 @@ async function captureScreenshot(session, logger, pageId) {
       session,
       pageAlive,
       browserConnected,
-      pageUrl: page.url()
+      pageUrl: (() => {
+        try {
+          return page.url();
+        } catch {
+          return null;
+        }
+      })()
     });
     throw err;
   } finally {
@@ -57,33 +176,35 @@ async function captureScreenshot(session, logger, pageId) {
   }
 }
 async function runSnapshot(session, logger, pageId, objective, context) {
-  const { pngPath, htmlPath } = await captureScreenshot(session, logger, pageId);
-  console.log("Screenshot saved:");
-  console.log(`  PNG:  ${pngPath}`);
-  console.log(`  HTML: ${htmlPath}`);
   const normalizedObjective = objective?.trim();
   const normalizedContext = context?.trim();
-  if (!normalizedObjective && !normalizedContext) {
-    console.log("Use --objective flag to analyze snapshots.");
-    return;
-  }
-  if (!normalizedObjective) {
+  if (!normalizedObjective && normalizedContext) {
     throw new Error(
       "Couldn't run analysis: --objective is required when providing --context."
     );
   }
-  if (!canAnalyzeSnapshots()) {
-    throw new Error(
-      "Couldn't run analysis: no AI config set. Run 'libretto-cli ai configure codex' (or claude/gemini) to enable analysis."
-    );
+  const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
+    session,
+    logger,
+    pageId
+  );
+  console.log("Screenshot saved:");
+  console.log(`  PNG:             ${pngPath}`);
+  console.log(`  HTML:            ${htmlPath}`);
+  console.log(`  Condensed HTML:  ${condensedHtmlPath}`);
+  if (!normalizedObjective) {
+    console.log("Use --objective flag to analyze snapshots.");
+    return;
   }
-  await runInterpret({
+  const interpretArgs = {
     objective: normalizedObjective,
     session,
     context: normalizedContext ?? DEFAULT_SNAPSHOT_CONTEXT,
     pngPath,
-    htmlPath
-  }, logger);
+    htmlPath,
+    condensedHtmlPath
+  };
+  await runApiInterpret(interpretArgs, logger, readAiConfig());
 }
 function registerSnapshotCommands(yargs, logger) {
   return yargs.command(