libretto 0.5.5 → 0.6.0

package/dist/cli/commands/setup.js

@@ -0,0 +1,390 @@
+import { createInterface } from "node:readline";
+import {
+  appendFileSync,
+  cpSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeAiConfig } from "../core/config.js";
+import {
+  ensureLibrettoSetup,
+  LIBRETTO_CONFIG_PATH,
+  REPO_ROOT
+} from "../core/context.js";
+import {
+  DEFAULT_SNAPSHOT_MODELS,
+  loadSnapshotEnv,
+  resolveAiSetupStatus
+} from "../core/ai-model.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
+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"
+  }
+];
+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") {
+    writeAiConfig(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"
+  );
+}
+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: ["enter-matching-credential", "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` to set a specific model."
+  );
+  console.log(
+    "  Run `npx libretto setup` interactively to set up credentials."
+  );
+  return false;
+}
+function writeEnvVar(envVar, value, envPath) {
+  let envContent = "";
+  if (existsSync(envPath)) {
+    envContent = readFileSync(envPath, "utf-8");
+  }
+  const envLine = `${envVar}=${value}`;
+  if (envContent.includes(`${envVar}=`)) {
+    const updated = envContent.replace(
+      new RegExp(`^${envVar}=.*$`, "m"),
+      () => envLine
+    );
+    writeFileSync(envPath, updated);
+    console.log(`
+\u2713 Updated ${envVar} in ${envPath}`);
+  } else {
+    const separator = envContent && !envContent.endsWith("\n") ? "\n" : "";
+    appendFileSync(envPath, `${separator}${envLine}
+`);
+    console.log(`
+\u2713 Added ${envVar} to ${envPath}`);
+  }
+  process.env[envVar] = value;
+}
+async function promptForCredential(rl, choice, envPath, modelOverride) {
+  console.log(`
+${choice.label} selected.`);
+  console.log(`${choice.envHint}
+`);
+  const apiKeyValue = await promptUser(rl, `Enter your ${choice.envVar}: `);
+  if (!apiKeyValue) {
+    console.log("\nNo value entered. Skipping API key setup.");
+    return false;
+  }
+  writeEnvVar(choice.envVar, apiKeyValue, envPath);
+  loadSnapshotEnv();
+  const model = modelOverride ?? DEFAULT_SNAPSHOT_MODELS[choice.provider];
+  writeAiConfig(model);
+  console.log(`\u2713 Snapshot API ready: ${model}`);
+  console.log(
+    "To change: npx libretto ai configure openai | anthropic | gemini | vertex"
+  );
+  return true;
+}
+async function promptProviderSelection(rl, envPath) {
+  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;
+  }
+  return promptForCredential(rl, selected, envPath);
+}
+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` to set a specific model."
+  );
+}
+async function runInteractiveApiSetup() {
+  const status = resolveAiSetupStatus();
+  const envPath = join(REPO_ROOT, ".env");
+  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("");
+      console.log("How would you like to fix this?\n");
+      console.log(`  1) Enter ${plan.envVar}`);
+      console.log("  2) Switch to a different provider");
+      console.log("  s) Skip for now\n");
+      const answer = await promptUser(rl, "Choice: ");
+      if (answer === "1") {
+        const matchingChoice = PROVIDER_CHOICES.find(
+          (c) => c.provider === plan.provider
+        );
+        if (matchingChoice) {
+          await promptForCredential(rl, matchingChoice, envPath, plan.model);
+        }
+        return;
+      }
+      if (answer === "2") {
+        await promptProviderSelection(rl, envPath);
+        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, envPath);
+      return;
+    }
+    console.log("\u2717 No snapshot API credentials detected.\n");
+    await promptProviderSelection(rl, envPath);
+  } finally {
+    rl.close();
+  }
+}
+function installBrowsers() {
+  console.log("Installing Playwright Chromium...");
+  const result = spawnSync("npx", ["playwright", "install", "chromium"], {
+    stdio: "inherit",
+    shell: true
+  });
+  if (result.status === 0) {
+    console.log("\u2713 Playwright Chromium installed");
+  } else {
+    console.error(
+      "\u2717 Failed to install Playwright Chromium. Run manually: npx playwright install chromium"
+    );
+  }
+}
+function getPackageSkillsRoot() {
+  const thisFile = fileURLToPath(import.meta.url);
+  let dir = dirname(thisFile);
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "skills", "libretto"))) {
+      return join(dir, "skills");
+    }
+    dir = dirname(dir);
+  }
+  throw new Error("Could not locate libretto skill files in package");
+}
+function detectAgentDirs(root) {
+  const dirs = [];
+  if (existsSync(join(root, ".agents"))) dirs.push(join(root, ".agents"));
+  if (existsSync(join(root, ".claude"))) dirs.push(join(root, ".claude"));
+  return dirs;
+}
+function copySkills() {
+  const agentDirs = detectAgentDirs(REPO_ROOT);
+  if (agentDirs.length === 0) {
+    return;
+  }
+  let skillsRoot;
+  try {
+    skillsRoot = getPackageSkillsRoot();
+  } catch (e) {
+    console.error(`\u2717 ${e instanceof Error ? e.message : String(e)}`);
+    return;
+  }
+  const skillNames = readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  for (const agentDir of agentDirs) {
+    const agentName = basename(agentDir);
+    for (const skillName of skillNames) {
+      const sourceDir = join(skillsRoot, skillName);
+      const skillDest = join(agentDir, "skills", skillName);
+      if (existsSync(skillDest)) {
+        rmSync(skillDest, { recursive: true });
+      }
+      cpSync(sourceDir, skillDest, { recursive: true });
+      const fileCount = readdirSync(skillDest).length;
+      console.log(
+        `\u2713 Copied ${fileCount} skill files to ${agentName}/skills/${skillName}/`
+      );
+    }
+  }
+}
+const setupInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    skipBrowsers: SimpleCLI.flag({
+      name: "skip-browsers",
+      help: "Skip Playwright Chromium installation"
+    })
+  }
+});
+const setupCommand = SimpleCLI.command({
+  description: "Set up libretto in the current project"
+}).input(setupInput).handle(async ({ input }) => {
+  ensureLibrettoSetup();
+  if (!input.skipBrowsers) {
+    installBrowsers();
+  } else {
+    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/snapshot.js

@@ -7,8 +7,8 @@ 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 { readAiConfig } from "../core/ai-config.js";
-import { resolveSnapshotApiModelOrThrow } from "../core/snapshot-api-config.js";
+import { readAiConfig } from "../core/config.js";
+import { resolveSnapshotApiModelOrThrow } from "../core/ai-model.js";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function generateSnapshotRunId() {
   return `snapshot-${Date.now()}`;

package/dist/cli/commands/status.js

@@ -0,0 +1,62 @@
+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 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"
+      );
+      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) {
+    console.log("  No open sessions.");
+    return;
+  }
+  for (const session of sessions) {
+    const statusLabel = session.status ? ` [${session.status}]` : "";
+    const endpoint = session.provider ? `${session.provider.name} (${session.cdpEndpoint})` : `http://127.0.0.1:${session.port}`;
+    console.log(`  ${session.session}${statusLabel} \u2014 ${endpoint}`);
+  }
+}
+const statusCommand = SimpleCLI.command({
+  description: "Show workspace status: AI configuration and open sessions"
+}).input(SimpleCLI.input({ positionals: [], named: {} })).handle(async () => {
+  const aiStatus = resolveAiSetupStatus();
+  printAiStatus(aiStatus);
+  const sessions = listRunningSessions();
+  printOpenSessions(sessions);
+});
+export {
+  statusCommand
+};

package/dist/cli/core/{snapshot-api-config.js → ai-model.js}

@@ -1,17 +1,34 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { readAiConfig } from "./ai-config.js";
+import { readAiConfig } from "./config.js";
 import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
 import {
   hasProviderCredentials,
   parseModel
-} from "../../shared/llm/client.js";
+} from "./resolve-model.js";
 const DEFAULT_SNAPSHOT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
   google: "google/gemini-3-flash-preview",
-  vertex: "vertex/gemini-2.5-pro"
+  vertex: "vertex/gemini-2.5-flash"
 };
+function detectProviderEnvVar(provider, env = process.env) {
+  switch (provider) {
+    case "openai":
+      return env.OPENAI_API_KEY?.trim() ? "OPENAI_API_KEY" : null;
+    case "anthropic":
+      return env.ANTHROPIC_API_KEY?.trim() ? "ANTHROPIC_API_KEY" : null;
+    case "google":
+      if (env.GEMINI_API_KEY?.trim()) return "GEMINI_API_KEY";
+      if (env.GOOGLE_GENERATIVE_AI_API_KEY?.trim())
+        return "GOOGLE_GENERATIVE_AI_API_KEY";
+      return null;
+    case "vertex":
+      if (env.GOOGLE_CLOUD_PROJECT?.trim()) return "GOOGLE_CLOUD_PROJECT";
+      if (env.GCLOUD_PROJECT?.trim()) return "GCLOUD_PROJECT";
+      return null;
+  }
+}
 class SnapshotApiUnavailableError extends Error {
   constructor(message) {
     super(message);
@@ -49,7 +66,7 @@ function noSnapshotApiConfiguredMessage() {
   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, or GOOGLE_CLOUD_PROJECT to .env or as a shell environment variable, or choose a default model with \`${defaultModelCommandLine()}\`.`,
-    "For more info, run `npx libretto init`."
+    "For more info, run `npx libretto setup`."
   ].join(" ");
 }
 function missingProviderSnapshotMessage(selection) {
@@ -57,7 +74,7 @@ function missingProviderSnapshotMessage(selection) {
   return [
     `Failed to analyze snapshot because ${selection.provider} is configured${configuredSource}, but ${providerMissingCredentialSummary(selection.provider)}.`,
     providerSetupSentence(selection.provider),
-    "For more info, run `npx libretto init`."
+    "For more info, run `npx libretto setup`."
   ].join(" ");
 }
 function readWorktreeEnvPath() {
@@ -128,11 +145,12 @@ function inferAutoSnapshotModel() {
     "vertex"
   ];
   for (const provider of providersInPriorityOrder) {
-    if (!hasProviderCredentials(provider)) continue;
+    const envVar = detectProviderEnvVar(provider);
+    if (!envVar) continue;
     return {
       model: DEFAULT_SNAPSHOT_MODELS[provider],
       provider,
-      source: `env:auto-${provider}`
+      source: `env:${envVar}`
     };
   }
   return null;
@@ -164,11 +182,67 @@ function resolveSnapshotApiModelOrThrow(config = readAiConfig()) {
 function isSnapshotApiUnavailableError(error) {
   return error instanceof SnapshotApiUnavailableError;
 }
+function readAiConfigSafely(configPath) {
+  try {
+    return { ok: true, config: readAiConfig(configPath) };
+  } catch (err) {
+    return {
+      ok: false,
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function resolveAiSetupStatus(configPath = LIBRETTO_CONFIG_PATH) {
+  loadSnapshotEnv();
+  const configResult = readAiConfigSafely(configPath);
+  if (!configResult.ok) {
+    return { kind: "invalid-config", message: configResult.message };
+  }
+  if (configResult.config) {
+    let selection;
+    try {
+      selection = resolveSnapshotApiModel(configResult.config);
+    } catch (err) {
+      return {
+        kind: "invalid-config",
+        message: err instanceof Error ? err.message : String(err)
+      };
+    }
+    if (!selection) {
+      return { kind: "unconfigured" };
+    }
+    if (hasProviderCredentials(selection.provider)) {
+      return {
+        kind: "ready",
+        model: selection.model,
+        provider: selection.provider,
+        source: selection.source
+      };
+    }
+    return {
+      kind: "configured-missing-credentials",
+      model: selection.model,
+      provider: selection.provider
+    };
+  }
+  const envSelection = resolveSnapshotApiModel(null);
+  if (envSelection && hasProviderCredentials(envSelection.provider)) {
+    return {
+      kind: "ready",
+      model: envSelection.model,
+      provider: envSelection.provider,
+      source: envSelection.source
+    };
+  }
+  return { kind: "unconfigured" };
+}
 export {
+  DEFAULT_SNAPSHOT_MODELS,
   SnapshotApiUnavailableError,
   isSnapshotApiUnavailableError,
   loadSnapshotEnv,
   parseDotEnvAssignment,
+  resolveAiSetupStatus,
   resolveSnapshotApiModel,
   resolveSnapshotApiModelOrThrow
 };

package/dist/cli/core/api-snapshot-analyzer.js

@@ -1,13 +1,14 @@
 import { readFileSync } from "node:fs";
-import { createLLMClient } from "../../shared/llm/client.js";
+import { generateObject } from "ai";
+import { resolveModel } from "./resolve-model.js";
 import {
   InterpretResultSchema,
   buildInlinePromptSelection,
   getMimeType,
   readFileAsBase64
 } from "./snapshot-analyzer.js";
-import { readAiConfig } from "./ai-config.js";
-import { resolveSnapshotApiModelOrThrow } from "./snapshot-api-config.js";
+import { readAiConfig } from "./config.js";
+import { resolveSnapshotApiModelOrThrow } from "./ai-model.js";
 async function runApiInterpret(args, logger, configuredAi = readAiConfig()) {
   const selection = resolveSnapshotApiModelOrThrow(configuredAi);
   logger.info("api-interpret-start", {
@@ -41,8 +42,9 @@ async function runApiInterpret(args, logger, configuredAi = readAiConfig()) {
   const imageBase64 = readFileAsBase64(args.pngPath);
   const imageMimeType = getMimeType(args.pngPath);
   const imageBytes = Buffer.from(imageBase64, "base64");
-  const client = createLLMClient(selection.model);
-  const result = await client.generateObjectFromMessages({
+  const model = await resolveModel(selection.model);
+  const { object: result } = await generateObject({
+    model,
     schema: InterpretResultSchema,
     messages: [
       {