libretto 0.6.11 → 0.6.13

package/dist/cli/commands/experiments.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { librettoCommand } from "../../shared/package-manager.js";
+import {
+  EXPERIMENTS,
+  isExperimentName,
+  resolveExperiments,
+  setExperimentEnabled
+} from "../core/experiments.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+const experimentNames = Object.keys(EXPERIMENTS);
+const experimentsUsage = [
+  "Usage:",
+  `  ${librettoCommand("experiments")}`,
+  `  ${librettoCommand("experiments describe <experiment>")}`,
+  `  ${librettoCommand("experiments enable <experiment>")}`,
+  `  ${librettoCommand("experiments disable <experiment>")}`
+].join("\n");
+const experimentsInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("action", z.string().optional(), {
+      help: "Action to apply"
+    }),
+    SimpleCLI.positional("experiment", z.string().optional(), {
+      help: "Experiment name"
+    })
+  ],
+  named: {}
+});
+function formatAvailableExperiments() {
+  return [
+    "Available experiments:",
+    ...experimentNames.map((name) => `  ${name}`)
+  ].join("\n");
+}
+function experimentUsageError(message) {
+  return new Error(
+    [message, "", experimentsUsage, "", formatAvailableExperiments()].join(
+      "\n"
+    )
+  );
+}
+function printExperiments(experiments) {
+  console.log("Libretto experiments:");
+  for (const name of experimentNames) {
+    const metadata = EXPERIMENTS[name];
+    console.log(
+      `- ${name}: ${experiments[name] ? "enabled" : "disabled"} \u2014 ${metadata.title}`
+    );
+    console.log(`  ${metadata.oneSentenceDescription}`);
+  }
+}
+function printExperimentDescription(name, experiments) {
+  const metadata = EXPERIMENTS[name];
+  console.log(`${metadata.title} (${name})`);
+  console.log(`Status: ${experiments[name] ? "enabled" : "disabled"}`);
+  console.log("");
+  if (experiments[name]) {
+    console.log(
+      "Since this experiment is enabled, Libretto\u2019s expected usage deviates from the skill. Use these instructions where they differ:"
+    );
+    console.log("");
+  }
+  console.log(metadata.docs ?? metadata.oneSentenceDescription);
+}
+const experimentsCommand = SimpleCLI.command({
+  description: "List or update Libretto experiment flags"
+}).input(experimentsInput).handle(async ({ input }) => {
+  if (!input.action) {
+    printExperiments(resolveExperiments());
+    return;
+  }
+  if (input.action !== "describe" && input.action !== "enable" && input.action !== "disable") {
+    throw experimentUsageError(`Unknown experiments action "${input.action}".`);
+  }
+  if (!input.experiment) {
+    throw experimentUsageError(
+      `Missing experiment name for ${input.action}.`
+    );
+  }
+  if (!isExperimentName(input.experiment)) {
+    throw experimentUsageError(`Unknown experiment "${input.experiment}".`);
+  }
+  if (input.action === "describe") {
+    printExperimentDescription(input.experiment, resolveExperiments());
+    return;
+  }
+  const experiments = setExperimentEnabled(
+    input.experiment,
+    input.action === "enable"
+  );
+  console.log(`Experiment "${input.experiment}" ${input.action}d.`);
+  if (input.action === "enable") {
+    console.log("");
+    printExperimentDescription(input.experiment, experiments);
+  }
+});
+export {
+  experimentsCommand,
+  experimentsInput
+};

package/dist/cli/commands/setup.js

@@ -1,308 +1,14 @@
-import { createInterface } from "node:readline";
-import {
-  cpSync,
-  existsSync,
-  readdirSync,
-  rmSync
-} from "node:fs";
+import { cpSync, existsSync, readdirSync, rmSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { writeSnapshotModel } from "../core/config.js";
 import {
   ensureLibrettoSetup,
   LIBRETTO_CONFIG_PATH,
   REPO_ROOT
 } from "../core/context.js";
-import {
-  DEFAULT_SNAPSHOT_MODELS,
-  resolveAiSetupStatus
-} from "../core/ai-model.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
-const PROVIDER_SDK_PACKAGES = {
-  openai: "@ai-sdk/openai",
-  anthropic: "@ai-sdk/anthropic",
-  google: "@ai-sdk/google",
-  vertex: "@ai-sdk/google-vertex",
-  openrouter: "@ai-sdk/openai"
-};
-function detectPackageManager() {
-  if (existsSync(join(REPO_ROOT, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(join(REPO_ROOT, "yarn.lock"))) return "yarn";
-  if (existsSync(join(REPO_ROOT, "bun.lockb"))) return "bun";
-  return "npm";
-}
-function installCommand(pkgManager) {
-  switch (pkgManager) {
-    case "yarn":
-      return "yarn add";
-    case "bun":
-      return "bun add";
-    case "pnpm":
-      return "pnpm add";
-    default:
-      return "npm install";
-  }
-}
-function isSdkInstalled(sdkPackage) {
-  try {
-    const result = spawnSync("node", ["-e", `require.resolve("${sdkPackage}")`], {
-      cwd: REPO_ROOT,
-      stdio: "pipe"
-    });
-    return result.status === 0;
-  } catch {
-    return false;
-  }
-}
-function installSdkIfNeeded(provider) {
-  const sdkPackage = PROVIDER_SDK_PACKAGES[provider];
-  if (isSdkInstalled(sdkPackage)) return;
-  const pkgManager = detectPackageManager();
-  const cmd = installCommand(pkgManager);
-  console.log(`
-Installing ${sdkPackage}...`);
-  const result = spawnSync(cmd, [sdkPackage], {
-    cwd: REPO_ROOT,
-    stdio: "inherit",
-    shell: true
-  });
-  if (result.status === 0) {
-    console.log(`\u2713 Installed ${sdkPackage}`);
-  } else {
-    console.error(
-      `\u2717 Failed to install ${sdkPackage}. Install it manually: ${cmd} ${sdkPackage}`
-    );
-  }
-}
-const PROVIDER_CHOICES = [
-  {
-    key: "1",
-    label: "OpenAI",
-    provider: "openai",
-    envVar: "OPENAI_API_KEY",
-    envHint: "Get your key at https://platform.openai.com/api-keys"
-  },
-  {
-    key: "2",
-    label: "Anthropic",
-    provider: "anthropic",
-    envVar: "ANTHROPIC_API_KEY",
-    envHint: "Get your key at https://console.anthropic.com/settings/keys"
-  },
-  {
-    key: "3",
-    label: "Google Gemini",
-    provider: "google",
-    envVar: "GEMINI_API_KEY",
-    envHint: "Get your key at https://aistudio.google.com/apikey"
-  },
-  {
-    key: "4",
-    label: "Google Vertex AI",
-    provider: "vertex",
-    envVar: "GOOGLE_CLOUD_PROJECT",
-    envHint: "Requires `gcloud auth application-default login` and a GCP project ID"
-  },
-  {
-    key: "5",
-    label: "OpenRouter",
-    provider: "openrouter",
-    envVar: "OPENROUTER_API_KEY",
-    envHint: "Get your key at https://openrouter.ai/settings/keys"
-  }
-];
-function promptUser(rl, question) {
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      resolve(answer.trim());
-    });
-  });
-}
-function providerLabel(provider) {
-  const choice = PROVIDER_CHOICES.find((c) => c.provider === provider);
-  return choice?.label ?? provider;
-}
-function sourceEnvVar(source) {
-  if (source.startsWith("env:")) return source.slice(4);
-  return null;
-}
-function ensurePinnedDefaultModel(status) {
-  if (status.source !== "config") {
-    writeSnapshotModel(status.model);
-    return { ...status, source: "config" };
-  }
-  return status;
-}
-function printHealthySummary(status) {
-  const envVar = sourceEnvVar(status.source);
-  if (envVar) {
-    console.log(
-      `\u2713 Detected ${envVar}. Using ${providerLabel(status.provider)}.`
-    );
-  } else {
-    console.log(`\u2713 Using ${providerLabel(status.provider)} (${status.model}).`);
-  }
-  console.log(
-    "To change: npx libretto ai configure openai | anthropic | gemini | vertex | openrouter"
-  );
-}
-function printInvalidAiConfigWarning(status) {
-  if (status.kind !== "invalid-config") return;
-  console.log("! Existing AI config is invalid:");
-  for (const line of status.message.split("\n")) {
-    console.log(`  ${line}`);
-  }
-}
-function buildRepairPlan(status) {
-  if (status.kind === "configured-missing-credentials") {
-    const choice = PROVIDER_CHOICES.find((c) => c.provider === status.provider);
-    return {
-      kind: "repair-missing-credentials",
-      provider: status.provider,
-      model: status.model,
-      envVar: choice?.envVar ?? `${status.provider.toUpperCase()}_API_KEY`,
-      choices: ["switch-provider", "skip"]
-    };
-  }
-  if (status.kind === "invalid-config") {
-    return { kind: "repair-invalid-config", message: status.message };
-  }
-  return { kind: "no-repair-needed" };
-}
-function formatMissingCredentialsMessage(plan) {
-  return `\u2717 ${plan.provider} is configured (model: ${plan.model}), but ${plan.envVar} is not set.`;
-}
-function printSnapshotApiStatus() {
-  const status = resolveAiSetupStatus();
-  console.log(
-    "\nLibretto uses a sub-agent to analyze DOM snapshots. The model is determined by environment variables."
-  );
-  if (status.kind === "ready") {
-    console.log();
-    printHealthySummary(status);
-    ensurePinnedDefaultModel(status);
-    return true;
-  }
-  const plan = buildRepairPlan(status);
-  if (plan.kind === "repair-missing-credentials") {
-    console.log();
-    console.log(formatMissingCredentialsMessage(plan));
-    console.log(
-      `  To fix: add ${plan.envVar} to .env, or run \`npx libretto setup\` interactively to repair.`
-    );
-    return false;
-  }
-  if (plan.kind === "repair-invalid-config") {
-    printInvalidAiConfigWarning(status);
-    console.log("  Run `npx libretto setup` interactively to reconfigure.");
-    return false;
-  }
-  console.log();
-  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 openai | anthropic | gemini | vertex | openrouter` to set a specific model."
-  );
-  console.log(
-    "  Run `npx libretto setup` interactively to set up credentials."
-  );
-  return false;
-}
-async function promptProviderSelection(rl) {
-  console.log(
-    "Which model 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) {
-    printSkipMessage();
-    return false;
-  }
-  const selected = PROVIDER_CHOICES.find((choice) => choice.key === answer);
-  if (!selected) {
-    console.log(`
-Unknown choice "${answer}". Skipping API setup.`);
-    return false;
-  }
-  const model = DEFAULT_SNAPSHOT_MODELS[selected.provider];
-  writeSnapshotModel(model);
-  console.log(`
-\u2713 ${selected.label} selected (model: ${model}).`);
-  console.log(`
-Add ${selected.envVar} to your .env file:`);
-  console.log(`  ${selected.envHint}`);
-  installSdkIfNeeded(selected.provider);
-  return true;
-}
-function printSkipMessage() {
-  console.log(
-    "\nSkipped. You can set up API credentials later by rerunning `npx libretto setup`."
-  );
-  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 openai | anthropic | gemini | vertex | openrouter` to set a specific model."
-  );
-}
-async function runInteractiveApiSetup() {
-  const status = resolveAiSetupStatus();
-  console.log(
-    "\nLibretto uses a sub-agent to analyze DOM snapshots. The model is determined by environment variables."
-  );
-  if (status.kind === "ready") {
-    console.log();
-    printHealthySummary(status);
-    ensurePinnedDefaultModel(status);
-    return;
-  }
-  const plan = buildRepairPlan(status);
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  try {
-    if (plan.kind === "repair-missing-credentials") {
-      console.log(formatMissingCredentialsMessage(plan));
-      console.log(`
-Add ${plan.envVar} to your .env file to fix this.`);
-      console.log("");
-      console.log("Or switch to a different provider:\n");
-      console.log("  1) Switch to a different provider");
-      console.log("  s) Skip for now\n");
-      const answer = await promptUser(rl, "Choice: ");
-      if (answer === "1") {
-        await promptProviderSelection(rl);
-        return;
-      }
-      printSkipMessage();
-      return;
-    }
-    if (plan.kind === "repair-invalid-config") {
-      printInvalidAiConfigWarning(status);
-      console.log(
-        "\nWould you like to reconfigure with a fresh provider selection?\n"
-      );
-      await promptProviderSelection(rl);
-      return;
-    }
-    console.log("\u2717 No snapshot API credentials detected.\n");
-    await promptProviderSelection(rl);
-  } finally {
-    rl.close();
-  }
-}
 function installBrowsers() {
   console.log("Installing Playwright Chromium...");
   const result = spawnSync("npx", ["playwright", "install", "chromium"], {
@@ -341,7 +47,7 @@ function copySkills() {
       "\n\u26A0\uFE0F No .agents/ or .claude/ directory found. Libretto skills were not installed."
     );
     console.log(
-      "  Create one of these directories in your repo root and rerun `npx libretto setup` to install skills:"
+      `  Create one of these directories in your repo root and rerun \`${librettoCommand("setup")}\` to install skills:`
     );
     console.log(`    mkdir ${join(REPO_ROOT, ".claude")}`);
     return;
@@ -389,24 +95,11 @@ const setupCommand = SimpleCLI.command({
     console.log("Skipping browser installation (--skip-browsers)");
   }
   copySkills();
-  if (process.stdin.isTTY) {
-    await runInteractiveApiSetup();
-  } else {
-    const ready = printSnapshotApiStatus();
-    if (!ready) {
-      console.log(
-        "\nIf you're an agent, request the user to run `npx libretto setup`."
-      );
-    }
-  }
   console.log(`
 Config set up at ${LIBRETTO_CONFIG_PATH}`);
   console.log("\n\u2713 libretto setup complete");
 });
 export {
-  PROVIDER_CHOICES,
-  buildRepairPlan,
-  formatMissingCredentialsMessage,
   setupCommand,
   setupInput
 };

package/dist/cli/commands/shared.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { resolveExperiments } from "../core/experiments.js";
 import { createLoggerForSession } from "../core/context.js";
 import {
   generateSessionName,
@@ -17,6 +18,14 @@ function pageOption(help = "Target a specific page id") {
 function integerOption(help) {
   return SimpleCLI.option(z.coerce.number().int().optional(), { help });
 }
+function withExperiments() {
+  return async ({
+    ctx
+  }) => ({
+    ...ctx,
+    experiments: resolveExperiments()
+  });
+}
 function withRequiredSession() {
   return async ({ input, ctx }) => {
     if (!input.session) {
@@ -47,5 +56,6 @@ export {
   pageOption,
   sessionOption,
   withAutoSession,
+  withExperiments,
   withRequiredSession
 };

package/dist/cli/commands/snapshot.js

@@ -1,13 +1,14 @@
-import { readFileSync, writeFileSync } from "node:fs";
 import { z } from "zod";
-import { condenseDom } from "../../shared/condense-dom/condense-dom.js";
 import { readSessionState } from "../core/session.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
-import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
-import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
-import { readSnapshotModel } from "../core/config.js";
-import { resolveSnapshotApiModelOrThrow } from "../core/ai-model.js";
-import { DaemonClient } from "../core/daemon/index.js";
+import {
+  pageOption,
+  sessionOption,
+  withRequiredSession
+} from "./shared.js";
+import { DaemonClient } from "../core/daemon/ipc.js";
+import { librettoCommand } from "../../shared/package-manager.js";
+import { renderSnapshot } from "../../shared/snapshot/render-snapshot.js";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function isZeroViewport(value) {
   return typeof value === "number" && value <= 0;
@@ -63,75 +64,56 @@ async function forceSnapshotViewport(page, viewport, logger, session, pageId, re
     viewport
   });
 }
-async function captureSnapshot(session, logger, daemonSocketPath, pageId) {
-  logger.info("snapshot-via-daemon", { session, pageId });
-  const client = new DaemonClient(daemonSocketPath);
-  const { pngPath, htmlPath, snapshotRunId, pageUrl, title } = await client.snapshot({ pageId });
-  const htmlContent = readFileSync(htmlPath, "utf8");
-  const condenseResult = condenseDom(htmlContent);
-  const condensedHtmlPath = htmlPath.replace(/\.html$/, ".condensed.html");
-  writeFileSync(condensedHtmlPath, condenseResult.html);
-  logger.info("snapshot-daemon-success", {
-    session,
-    pageUrl,
-    title,
-    pngPath,
-    htmlPath,
-    condensedHtmlPath,
-    snapshotRunId,
-    domCondenseStats: {
-      originalLength: condenseResult.originalLength,
-      condensedLength: condenseResult.condensedLength,
-      reductions: condenseResult.reductions
-    }
-  });
-  return { pngPath, htmlPath, condensedHtmlPath, baseName: snapshotRunId };
-}
-async function runSnapshot(session, logger, pageId, objective, context) {
-  const normalizedObjective = objective.trim();
-  const normalizedContext = context.trim();
-  const snapshotModel = readSnapshotModel();
-  resolveSnapshotApiModelOrThrow(snapshotModel);
-  const state = readSessionState(session, logger);
-  if (!state?.daemonSocketPath) {
+async function runCompactSnapshot(args) {
+  if (!args.daemonSocketPath) {
     throw new Error(
-      `Session "${session}" has no daemon socket. The browser daemon may have crashed. Close and reopen the session: libretto close --session ${session}`
+      `Session "${args.session}" has no daemon socket. The browser daemon may have crashed. Close and reopen the session: ${librettoCommand(`close --session ${args.session}`)}`
     );
   }
-  const { pngPath, htmlPath, condensedHtmlPath } = await captureSnapshot(session, logger, state.daemonSocketPath, pageId);
-  console.log("Screenshot saved:");
-  console.log(`  PNG:             ${pngPath}`);
-  console.log(`  HTML:            ${htmlPath}`);
-  console.log(`  Condensed HTML:  ${condensedHtmlPath}`);
-  const interpretArgs = {
-    objective: normalizedObjective,
-    session,
-    context: normalizedContext,
-    pngPath,
-    htmlPath,
-    condensedHtmlPath
-  };
-  await runApiInterpret(interpretArgs, logger, snapshotModel);
+  args.logger.info("compact-snapshot-via-daemon", {
+    session: args.session,
+    pageId: args.pageId,
+    ref: args.ref
+  });
+  const client = await DaemonClient.connect(args.daemonSocketPath);
+  let result;
+  try {
+    result = await client.snapshot({
+      pageId: args.pageId,
+      useCachedSnapshot: args.ref !== void 0
+    });
+  } finally {
+    client.destroy();
+  }
+  console.log(`Screenshot at ${result.pngPath}`);
+  console.log(renderSnapshot(result.snapshot, args.ref));
+  console.log(
+    `Hint: Use ${librettoCommand(`snapshot <ref> --session ${args.session}`)} to inspect a subtree.`
+  );
 }
 const snapshotInput = SimpleCLI.input({
-  positionals: [],
+  positionals: [
+    SimpleCLI.positional("ref", z.string().optional(), {
+      help: "Optional element ref to scope output to that subtree (for example, l16 or e16)"
+    })
+  ],
   named: {
     session: sessionOption(),
     page: pageOption(),
-    objective: SimpleCLI.option(z.string()),
-    context: SimpleCLI.option(z.string())
+    objective: SimpleCLI.option(z.string().optional()),
+    context: SimpleCLI.option(z.string().optional())
   }
 });
 const snapshotCommand = SimpleCLI.command({
-  description: "Capture PNG + HTML and analyze with --objective and --context"
+  description: "Capture a screenshot and compact accessibility snapshot"
 }).input(snapshotInput).use(withRequiredSession()).handle(async ({ input, ctx }) => {
-  await runSnapshot(
-    ctx.session,
-    ctx.logger,
-    input.page,
-    input.objective,
-    input.context
-  );
+  await runCompactSnapshot({
+    session: ctx.session,
+    daemonSocketPath: ctx.sessionState.daemonSocketPath,
+    logger: ctx.logger,
+    pageId: input.page,
+    ref: input.ref
+  });
 });
 export {
   FALLBACK_SNAPSHOT_VIEWPORT,

package/dist/cli/commands/status.js

@@ -1,42 +1,5 @@
-import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
-import { resolveAiSetupStatus } from "../core/ai-model.js";
 import { listRunningSessions } from "../core/session.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
-function printAiStatus(status) {
-  console.log("AI configuration:");
-  switch (status.kind) {
-    case "ready":
-      console.log(`  \u2713 Snapshot model: ${status.model}`);
-      if (status.source === "config") {
-        console.log(`  Config: ${LIBRETTO_CONFIG_PATH}`);
-      } else {
-        console.log(`  Source: ${status.source}`);
-      }
-      console.log(
-        "  To change: npx libretto ai configure openai | anthropic | gemini | vertex | openrouter"
-      );
-      break;
-    case "configured-missing-credentials":
-      console.log(
-        `  \u2717 ${status.provider} is configured (model: ${status.model}), but credentials are missing.`
-      );
-      console.log("  Run `npx libretto setup` to repair.");
-      break;
-    case "invalid-config":
-      console.log("  \u2717 Config is invalid:");
-      for (const line of status.message.split("\n")) {
-        console.log(`    ${line}`);
-      }
-      console.log("  Run `npx libretto setup` to reconfigure.");
-      break;
-    case "unconfigured":
-      console.log("  \u2717 No AI model configured.");
-      console.log(
-        "  Run `npx libretto setup` or `npx libretto ai configure` to set up."
-      );
-      break;
-  }
-}
 function printOpenSessions(sessions) {
   console.log("\nOpen sessions:");
   if (sessions.length === 0) {
@@ -50,10 +13,8 @@ function printOpenSessions(sessions) {
   }
 }
 const statusCommand = SimpleCLI.command({
-  description: "Show workspace status: AI configuration and open sessions"
+  description: "Show workspace status and open sessions"
 }).input(SimpleCLI.input({ positionals: [], named: {} })).handle(async () => {
-  const aiStatus = resolveAiSetupStatus();
-  printAiStatus(aiStatus);
   const sessions = listRunningSessions();
   printOpenSessions(sessions);
 });