libretto 0.6.10 → 0.6.12

package/src/cli/commands/experiments.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { librettoCommand } from "../../shared/package-manager.js";
+import {
+  EXPERIMENTS,
+  isExperimentName,
+  resolveExperiments,
+  setExperimentEnabled,
+  type ExperimentName,
+  type Experiments,
+} from "../core/experiments.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+
+const experimentNames = Object.keys(EXPERIMENTS) as ExperimentName[];
+
+const experimentsUsage = [
+  "Usage:",
+  `  ${librettoCommand("experiments")}`,
+  `  ${librettoCommand("experiments describe <experiment>")}`,
+  `  ${librettoCommand("experiments enable <experiment>")}`,
+  `  ${librettoCommand("experiments disable <experiment>")}`,
+].join("\n");
+
+export 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(): string {
+  return [
+    "Available experiments:",
+    ...experimentNames.map((name) => `  ${name}`),
+  ].join("\n");
+}
+
+function experimentUsageError(message: string): Error {
+  return new Error(
+    [message, "", experimentsUsage, "", formatAvailableExperiments()].join(
+      "\n",
+    ),
+  );
+}
+
+function printExperiments(experiments: Experiments): void {
+  console.log("Libretto experiments:");
+  for (const name of experimentNames) {
+    const metadata = EXPERIMENTS[name];
+    console.log(
+      `- ${name}: ${experiments[name] ? "enabled" : "disabled"} — ${metadata.title}`,
+    );
+    console.log(`  ${metadata.oneSentenceDescription}`);
+  }
+}
+
+function printExperimentDescription(
+  name: ExperimentName,
+  experiments: Experiments,
+): void {
+  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’s expected usage deviates from the skill. Use these instructions where they differ:",
+    );
+    console.log("");
+  }
+  console.log(metadata.docs ?? metadata.oneSentenceDescription);
+}
+
+export 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);
+    }
+  });

package/src/cli/commands/setup.ts

@@ -1,10 +1,5 @@
 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";
@@ -19,6 +14,11 @@ import {
   DEFAULT_SNAPSHOT_MODELS,
   resolveAiSetupStatus,
 } from "../core/ai-model.js";
+import {
+  detectProjectPackageManager,
+  installCommand,
+  librettoCommand,
+} from "../../shared/package-manager.js";
 import type { Provider } from "../core/resolve-model.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 
@@ -30,26 +30,6 @@ const PROVIDER_SDK_PACKAGES: Record<Provider, string> = {
   openrouter: "@ai-sdk/openai",
 };
 
-function detectPackageManager(): string {
-  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: string): string {
-  switch (pkgManager) {
-    case "yarn":
-      return "yarn add";
-    case "bun":
-      return "bun add";
-    case "pnpm":
-      return "pnpm add";
-    default:
-      return "npm install";
-  }
-}
-
 function isSdkInstalled(sdkPackage: string): boolean {
   try {
     const result = spawnSync("node", ["-e", `require.resolve("${sdkPackage}")`], {
@@ -66,7 +46,7 @@ function installSdkIfNeeded(provider: Provider): void {
   const sdkPackage = PROVIDER_SDK_PACKAGES[provider];
   if (isSdkInstalled(sdkPackage)) return;
 
-  const pkgManager = detectPackageManager();
+  const pkgManager = detectProjectPackageManager();
   const cmd = installCommand(pkgManager);
   console.log(`\nInstalling ${sdkPackage}...`);
   const result = spawnSync(cmd, [sdkPackage], {
@@ -177,7 +157,7 @@ function printHealthySummary(status: AiSetupStatus & { kind: "ready" }): void {
     console.log(`✓ Using ${providerLabel(status.provider)} (${status.model}).`);
   }
   console.log(
-    "To change: npx libretto ai configure openai | anthropic | gemini | vertex | openrouter",
+    `To change: ${librettoCommand("ai configure openai | anthropic | gemini | vertex | openrouter")}`,
   );
 }
 
@@ -254,14 +234,16 @@ function printSnapshotApiStatus(): boolean {
     console.log();
     console.log(formatMissingCredentialsMessage(plan));
     console.log(
-      `  To fix: add ${plan.envVar} to .env, or run \`npx libretto setup\` interactively to repair.`,
+      `  To fix: add ${plan.envVar} to .env, or run \`${librettoCommand("setup")}\` interactively to repair.`,
     );
     return false;
   }
 
   if (plan.kind === "repair-invalid-config") {
     printInvalidAiConfigWarning(status);
-    console.log("  Run `npx libretto setup` interactively to reconfigure.");
+    console.log(
+      `  Run \`${librettoCommand("setup")}\` interactively to reconfigure.`,
+    );
     return false;
   }
 
@@ -275,10 +257,10 @@ function printSnapshotApiStatus(): boolean {
     "    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.",
+    `  Or run \`${librettoCommand("ai configure openai | anthropic | gemini | vertex | openrouter")}\` to set a specific model.`,
   );
   console.log(
-    "  Run `npx libretto setup` interactively to set up credentials.",
+    `  Run \`${librettoCommand("setup")}\` interactively to set up credentials.`,
   );
   return false;
 }
@@ -324,14 +306,14 @@ async function promptProviderSelection(
 
 function printSkipMessage(): void {
   console.log(
-    "\nSkipped. You can set up API credentials later by rerunning `npx libretto setup`.",
+    `\nSkipped. You can set up API credentials later by rerunning \`${librettoCommand("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.",
+    `  Or run \`${librettoCommand("ai configure openai | anthropic | gemini | vertex | openrouter")}\` to set a specific model.`,
   );
 }
 
@@ -442,7 +424,7 @@ function copySkills(): void {
       "\n⚠️ 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;
@@ -510,7 +492,7 @@ export const setupCommand = SimpleCLI.command({
       const ready = printSnapshotApiStatus();
       if (!ready) {
         console.log(
-          "\nIf you're an agent, request the user to run `npx libretto setup`.",
+          `\nIf you're an agent, request the user to run \`${librettoCommand("setup")}\`.`,
         );
       }
     }

package/src/cli/commands/shared.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import type { LoggerApi } from "../../shared/logger/index.js";
+import type { Experiments } from "../core/experiments.js";
+import { resolveExperiments } from "../core/experiments.js";
 import { createLoggerForSession } from "../core/context.js";
 import {
   generateSessionName,
@@ -9,6 +11,8 @@ import {
 } from "../core/session.js";
 import {
   SimpleCLI,
+  type SimpleCLIMiddlewareArgs,
+  type SimpleCLIContext,
   type SimpleCLIMiddleware,
 } from "../framework/simple-cli.js";
 
@@ -33,6 +37,22 @@ export type SessionStateContext = SessionContext & {
   sessionState: SessionState;
 };
 
+export type ExperimentsContext = {
+  experiments: Experiments;
+};
+
+export function withExperiments() {
+  return async <TInput, TContext extends SimpleCLIContext>({
+    ctx,
+  }: SimpleCLIMiddlewareArgs<
+    TInput,
+    TContext
+  >): Promise<TContext & ExperimentsContext> => ({
+    ...ctx,
+    experiments: resolveExperiments(),
+  });
+}
+
 export function withRequiredSession(): SimpleCLIMiddleware<
   { session?: string },
   {},

package/src/cli/commands/snapshot.ts

@@ -8,11 +8,18 @@ import {
   type ScreenshotPair,
 } from "../core/snapshot-analyzer.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
-import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
+import {
+  pageOption,
+  sessionOption,
+  withExperiments,
+  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 { DaemonClient } from "../core/daemon/ipc.js";
+import { librettoCommand } from "../../shared/package-manager.js";
+import { renderSnapshot } from "../../shared/snapshot/render-snapshot.js";
 
 export const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 } as const;
 
@@ -116,9 +123,17 @@ async function captureSnapshot(
   pageId?: string,
 ): Promise<ScreenshotPair> {
   logger.info("snapshot-via-daemon", { session, pageId });
-  const client = new DaemonClient(daemonSocketPath);
-  const { pngPath, htmlPath, snapshotRunId, pageUrl, title } =
-    await client.snapshot({ pageId });
+  const client = await DaemonClient.connect(daemonSocketPath);
+  let snapshotResult: Awaited<ReturnType<DaemonClient["snapshot"]>>;
+  try {
+    snapshotResult = await client.snapshot({ pageId });
+  } finally {
+    client.destroy();
+  }
+  if (!("htmlPath" in snapshotResult)) {
+    throw new Error("Daemon returned a compact snapshot for a legacy request.");
+  }
+  const { pngPath, htmlPath, snapshotRunId, pageUrl, title } = snapshotResult;
 
   // condenseDom runs in the CLI process, not the daemon.
   const htmlContent = readFileSync(htmlPath, "utf8");
@@ -148,9 +163,16 @@ async function runSnapshot(
   session: string,
   logger: LoggerApi,
   pageId: string | undefined,
-  objective: string,
-  context: string,
+  objective: string | undefined,
+  context: string | undefined,
 ): Promise<void> {
+  if (objective === undefined) {
+    throw new Error("Missing required option --objective.");
+  }
+  if (context === undefined) {
+    throw new Error("Missing required option --context.");
+  }
+
   const normalizedObjective = objective.trim();
   const normalizedContext = context.trim();
 
@@ -161,7 +183,7 @@ async function runSnapshot(
   if (!state?.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}`,
+        `Close and reopen the session: ${librettoCommand(`close --session ${session}`)}`,
     );
   }
 
@@ -189,13 +211,61 @@ async function runSnapshot(
   await runApiInterpret(interpretArgs, logger, snapshotModel);
 }
 
+async function runCompactSnapshot(
+  args: {
+    session: string;
+    daemonSocketPath?: string;
+    logger: LoggerApi;
+    pageId?: string;
+    ref?: string;
+  },
+): Promise<void> {
+  if (!args.daemonSocketPath) {
+    throw new Error(
+      `Session "${args.session}" has no daemon socket. The browser daemon may have crashed. ` +
+        `Close and reopen the session: ${librettoCommand(`close --session ${args.session}`)}`,
+    );
+  }
+
+  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: Awaited<ReturnType<DaemonClient["snapshot"]>>;
+  try {
+    result = await client.snapshot({
+      mode: "compact",
+      pageId: args.pageId,
+      useCachedSnapshot: args.ref !== undefined,
+    });
+  } finally {
+    client.destroy();
+  }
+  if (!("mode" in result) || result.mode !== "compact") {
+    throw new Error("Daemon returned a legacy snapshot for a compact request.");
+  }
+
+  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.`,
+  );
+}
+
 export 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()),
   },
 });
 
@@ -204,7 +274,25 @@ export const snapshotCommand = SimpleCLI.command({
 })
   .input(snapshotInput)
   .use(withRequiredSession())
+  .use(withExperiments())
   .handle(async ({ input, ctx }) => {
+    if (ctx.experiments["compact-snapshot-format"]) {
+      await runCompactSnapshot({
+        session: ctx.session,
+        daemonSocketPath: ctx.sessionState.daemonSocketPath,
+        logger: ctx.logger,
+        pageId: input.page,
+        ref: input.ref,
+      });
+      return;
+    }
+
+    if (input.ref) {
+      throw new Error(
+        `Snapshot refs require the compact-snapshot-format experiment. Enable it with ${librettoCommand("experiments enable compact-snapshot-format")}.`,
+      );
+    }
+
     await runSnapshot(
       ctx.session,
       ctx.logger,

package/src/cli/commands/status.ts

@@ -1,5 +1,6 @@
 import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
 import { type AiSetupStatus, resolveAiSetupStatus } from "../core/ai-model.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 import { listRunningSessions, type SessionState } from "../core/session.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 
@@ -17,7 +18,7 @@ function printAiStatus(status: AiSetupStatus): void {
         console.log(`  Source: ${status.source}`);
       }
       console.log(
-        "  To change: npx libretto ai configure openai | anthropic | gemini | vertex | openrouter",
+        `  To change: ${librettoCommand("ai configure openai | anthropic | gemini | vertex | openrouter")}`,
       );
       break;
 
@@ -25,7 +26,7 @@ function printAiStatus(status: AiSetupStatus): void {
       console.log(
         `  ✗ ${status.provider} is configured (model: ${status.model}), but credentials are missing.`,
       );
-      console.log("  Run `npx libretto setup` to repair.");
+      console.log(`  Run \`${librettoCommand("setup")}\` to repair.`);
       break;
 
     case "invalid-config":
@@ -33,13 +34,13 @@ function printAiStatus(status: AiSetupStatus): void {
       for (const line of status.message.split("\n")) {
         console.log(`    ${line}`);
       }
-      console.log("  Run `npx libretto setup` to reconfigure.");
+      console.log(`  Run \`${librettoCommand("setup")}\` to reconfigure.`);
       break;
 
     case "unconfigured":
       console.log("  ✗ No AI model configured.");
       console.log(
-        "  Run `npx libretto setup` or `npx libretto ai configure` to set up.",
+        `  Run \`${librettoCommand("setup")}\` or \`${librettoCommand("ai configure")}\` to set up.`,
       );
       break;
   }

package/src/cli/core/ai-model.ts

@@ -1,5 +1,6 @@
 import { readSnapshotModel } from "./config.js";
 import { LIBRETTO_CONFIG_PATH } from "./context.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 import {
   hasProviderCredentials,
   parseModel,
@@ -80,7 +81,9 @@ function providerSetupSentence(provider: Provider): string {
 }
 
 function defaultModelCommandLine(): string {
-  return "npx libretto ai configure openai | anthropic | gemini | vertex | openrouter";
+  return librettoCommand(
+    "ai configure openai | anthropic | gemini | vertex | openrouter",
+  );
 }
 
 function providerMissingCredentialSummary(provider: Provider): string {
@@ -102,7 +105,7 @@ function noSnapshotApiConfiguredMessage(): string {
   return [
     "Failed to analyze snapshot because no snapshot analyzer is configured.",
     `Add OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY, GOOGLE_CLOUD_PROJECT, or OPENROUTER_API_KEY to .env or as a shell environment variable, or choose a default model with \`${defaultModelCommandLine()}\`.`,
-    "For more info, run `npx libretto setup`.",
+    `For more info, run \`${librettoCommand("setup")}\`.`,
   ].join(" ");
 }
 
@@ -116,7 +119,7 @@ function missingProviderSnapshotMessage(
   return [
     `Failed to analyze snapshot because ${selection.provider} is configured${configuredSource}, but ${providerMissingCredentialSummary(selection.provider)}.`,
     providerSetupSentence(selection.provider),
-    "For more info, run `npx libretto setup`.",
+    `For more info, run \`${librettoCommand("setup")}\`.`,
   ].join(" ");
 }