libretto 0.5.5 → 0.6.0

package/src/cli/commands/init.ts

@@ -1,331 +0,0 @@
-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 { readAiConfig } from "../core/ai-config.js";
-import { REPO_ROOT } from "../core/context.js";
-import {
-  loadSnapshotEnv,
-  resolveSnapshotApiModel,
-} from "../core/snapshot-api-config.js";
-import { hasProviderCredentials } from "../../shared/llm/client.js";
-import { SimpleCLI } from "../framework/simple-cli.js";
-
-type ProviderChoice = {
-  key: string;
-  label: string;
-  envVar: string;
-  envHint: string;
-};
-
-const PROVIDER_CHOICES: ProviderChoice[] = [
-  {
-    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: ReturnType<typeof createInterface>,
-  question: string,
-): Promise<string> {
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      resolve(answer.trim());
-    });
-  });
-}
-
-function safeReadAiConfig(): ReturnType<typeof readAiConfig> {
-  try {
-    return readAiConfig();
-  } catch {
-    return null;
-  }
-}
-
-function printInvalidAiConfigWarning(): void {
-  try {
-    readAiConfig();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.log("  ! Existing AI config is invalid:");
-    for (const line of message.split("\n")) {
-      console.log(`    ${line}`);
-    }
-  }
-}
-
-function printSnapshotApiStatus(): void {
-  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}.`);
-  printInvalidAiConfigWarning();
-
-  if (selection && hasProviderCredentials(selection.provider)) {
-    console.log(`  ✓ Ready: ${selection.model} (${selection.source})`);
-    console.log(
-      "    Snapshot objectives will use the API analyzer by default.",
-    );
-    console.log("    No further action required.");
-    return;
-  }
-
-  console.log("  ✗ 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 init` interactively to set up credentials.",
-  );
-}
-
-async function runInteractiveApiSetup(): Promise<void> {
-  const config = safeReadAiConfig();
-  const selection = resolveSnapshotApiModel(config);
-  const envPath = join(REPO_ROOT, ".env");
-
-  console.log("\nSnapshot analysis setup:");
-  console.log("  Libretto uses direct API calls for snapshot analysis.");
-  console.log(`  Credentials are loaded from process env and ${envPath}.`);
-  printInvalidAiConfigWarning();
-
-  if (selection && hasProviderCredentials(selection.provider)) {
-    console.log(`  ✓ Ready: ${selection.model} (${selection.source})`);
-    console.log(
-      "    Snapshot objectives will use the API analyzer by default.",
-    );
-    return;
-  }
-
-  console.log("  ✗ 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 openai | anthropic | gemini | vertex` to set a specific model.",
-      );
-      return;
-    }
-
-    const selected = PROVIDER_CHOICES.find((choice) => choice.key === answer);
-    if (!selected) {
-      console.log(`\n  Unknown choice "${answer}". Skipping API setup.`);
-      return;
-    }
-
-    console.log(`\n  ${selected.label} selected.`);
-    console.log(`  ${selected.envHint}\n`);
-
-    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(`\n  ✓ Updated ${selected.envVar} in ${envPath}`);
-    } else {
-      const separator = envContent && !envContent.endsWith("\n") ? "\n" : "";
-      appendFileSync(envPath, `${separator}${envLine}\n`);
-      console.log(`\n  ✓ Added ${selected.envVar} to ${envPath}`);
-    }
-
-    loadSnapshotEnv();
-    process.env[selected.envVar] = apiKeyValue;
-    const newSelection = resolveSnapshotApiModel(safeReadAiConfig());
-    if (newSelection && hasProviderCredentials(newSelection.provider)) {
-      console.log(`  ✓ Snapshot API ready: ${newSelection.model}`);
-    }
-  } finally {
-    rl.close();
-  }
-}
-
-function installBrowsers(): void {
-  console.log("\nInstalling Playwright Chromium...");
-  const result = spawnSync("npx", ["playwright", "install", "chromium"], {
-    stdio: "inherit",
-    shell: true,
-  });
-  if (result.status === 0) {
-    console.log("  ✓ Playwright Chromium installed");
-  } else {
-    console.error(
-      "  ✗ Failed to install Playwright Chromium. Run manually: npx playwright install chromium",
-    );
-  }
-}
-
-function getPackageSkillsDir(): string {
-  const thisFile = fileURLToPath(import.meta.url);
-  // Walk up from dist/cli/commands/ to package root
-  let dir = dirname(thisFile);
-  while (dir !== dirname(dir)) {
-    if (existsSync(join(dir, "skills", "libretto"))) {
-      return join(dir, "skills", "libretto");
-    }
-    dir = dirname(dir);
-  }
-  throw new Error("Could not locate libretto skill files in package");
-}
-
-/**
- * Auto-detect .agents/ and .claude/ directories at a given root path.
- */
-function detectAgentDirs(root: string): string[] {
-  const dirs: string[] = [];
-  if (existsSync(join(root, ".agents"))) dirs.push(join(root, ".agents"));
-  if (existsSync(join(root, ".claude"))) dirs.push(join(root, ".claude"));
-  return dirs;
-}
-
-function copySkills(): void {
-  const agentDirs = detectAgentDirs(REPO_ROOT);
-
-  if (agentDirs.length === 0) {
-    console.log(
-      "\nSkills: No .agents/ or .claude/ directory found in repo root — skipping.",
-    );
-    return;
-  }
-
-  const destinations = agentDirs.map((d) => join(d, "skills", "libretto"));
-
-  let sourceDir: string;
-  try {
-    sourceDir = getPackageSkillsDir();
-  } catch (e) {
-    console.error(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
-    return;
-  }
-
-  for (let i = 0; i < agentDirs.length; i++) {
-    const skillDest = destinations[i];
-    const name = basename(agentDirs[i]);
-    // Remove existing dir first so stale files from prior versions don't persist
-    if (existsSync(skillDest)) {
-      rmSync(skillDest, { recursive: true });
-    }
-    cpSync(sourceDir, skillDest, { recursive: true });
-    const fileCount = readdirSync(skillDest).length;
-    console.log(
-      `  ✓ Copied ${fileCount} skill files to ${name}/skills/libretto/`,
-    );
-  }
-}
-
-export const initInput = SimpleCLI.input({
-  positionals: [],
-  named: {
-    skipBrowsers: SimpleCLI.flag({
-      name: "skip-browsers",
-      help: "Skip Playwright Chromium installation",
-    }),
-  },
-});
-
-export const initCommand = SimpleCLI.command({
-  description: "Initialize libretto in the current project",
-})
-  .input(initInput)
-  .handle(async ({ input }) => {
-    console.log("Initializing libretto...\n");
-
-    if (!input.skipBrowsers) {
-      installBrowsers();
-    } else {
-      console.log("\nSkipping browser installation (--skip-browsers)");
-    }
-
-    copySkills();
-
-    if (process.stdin.isTTY) {
-      await runInteractiveApiSetup();
-    } else {
-      loadSnapshotEnv();
-      printSnapshotApiStatus();
-    }
-
-    console.log("\n✓ libretto init complete");
-  });

package/src/cli/commands/logs.ts

@@ -1,128 +0,0 @@
-import { z } from "zod";
-import { listOpenPages } from "../core/browser.js";
-import { withSessionLogger } from "../core/context.js";
-import {
-  clearActionLog,
-  clearNetworkLog,
-  formatActionEntry,
-  formatNetworkEntry,
-  readActionLog,
-  readNetworkLog,
-} from "../core/telemetry.js";
-import { SimpleCLI } from "../framework/simple-cli.js";
-import {
-  integerOption,
-  pageOption,
-  sessionOption,
-  withRequiredSession,
-} from "./shared.js";
-
-async function resolvePageId(
-  session: string,
-  pageId?: string,
-): Promise<string | undefined> {
-  if (!pageId) return undefined;
-  const pages = await withSessionLogger(session, async (logger) =>
-    listOpenPages(session, logger),
-  );
-  const foundPage = pages.find((page) => page.id === pageId);
-  if (!foundPage) {
-    throw new Error(
-      `Page "${pageId}" was not found in session "${session}". Run "libretto pages --session ${session}" to list ids.`,
-    );
-  }
-  return pageId;
-}
-
-export const networkInput = SimpleCLI.input({
-  positionals: [],
-  named: {
-    session: sessionOption(),
-    last: integerOption(),
-    filter: SimpleCLI.option(z.string().optional()),
-    method: SimpleCLI.option(z.string().optional()),
-    page: pageOption(),
-    clear: SimpleCLI.flag(),
-  },
-});
-
-export const networkCommand = SimpleCLI.command({
-  description: "View captured network requests",
-})
-  .input(networkInput)
-  .use(withRequiredSession())
-  .handle(async ({ input, ctx }) => {
-    if (input.clear) {
-      clearNetworkLog(ctx.session);
-      console.log("Network log cleared.");
-      return;
-    }
-
-    const pageId = await resolvePageId(ctx.session, input.page);
-    const entries = readNetworkLog(ctx.session, {
-      last: input.last,
-      filter: input.filter,
-      method: input.method,
-      pageId,
-    });
-
-    if (entries.length === 0) {
-      console.log("No network requests captured.");
-      return;
-    }
-
-    for (const entry of entries) {
-      console.log(formatNetworkEntry(entry));
-    }
-    console.log(`\n${entries.length} request(s) shown.`);
-  });
-
-export const actionsInput = SimpleCLI.input({
-  positionals: [],
-  named: {
-    session: sessionOption(),
-    last: integerOption(),
-    filter: SimpleCLI.option(z.string().optional()),
-    action: SimpleCLI.option(z.string().optional()),
-    source: SimpleCLI.option(z.string().optional()),
-    page: pageOption(),
-    clear: SimpleCLI.flag(),
-  },
-});
-
-export const actionsCommand = SimpleCLI.command({
-  description: "View captured actions",
-})
-  .input(actionsInput)
-  .use(withRequiredSession())
-  .handle(async ({ input, ctx }) => {
-    if (input.clear) {
-      clearActionLog(ctx.session);
-      console.log("Action log cleared.");
-      return;
-    }
-
-    const pageId = await resolvePageId(ctx.session, input.page);
-    const entries = readActionLog(ctx.session, {
-      last: input.last,
-      filter: input.filter,
-      action: input.action,
-      source: input.source,
-      pageId,
-    });
-
-    if (entries.length === 0) {
-      console.log("No actions captured.");
-      return;
-    }
-
-    for (const entry of entries) {
-      console.log(formatActionEntry(entry));
-    }
-    console.log(`\n${entries.length} action(s) shown.`);
-  });
-
-export const logCommands = {
-  network: networkCommand,
-  actions: actionsCommand,
-};

package/src/shared/llm/ai-sdk-adapter.ts

@@ -1,81 +0,0 @@
-import { generateObject, type LanguageModel } from "ai";
-import type { ZodType, output as ZodOutput } from "zod";
-import type { LLMClient, Message } from "./types.js";
-
-/**
- * Creates a libretto LLMClient from a Vercel AI SDK LanguageModel.
- *
- * This eliminates the need for consumers to write their own adapter
- * when using @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google-vertex,
- * or any other Vercel AI SDK-compatible provider.
- *
- * @example
- * ```typescript
- * import { createLLMClientFromModel } from "libretto/llm";
- * import { openai } from "@ai-sdk/openai";
- *
- * const llmClient = createLLMClientFromModel(openai("gpt-4o"));
- * ```
- */
-export function createLLMClientFromModel(model: LanguageModel): LLMClient {
-  return {
-    async generateObject<T extends ZodType>(opts: {
-      prompt: string;
-      schema: T;
-      temperature?: number;
-    }): Promise<ZodOutput<T>> {
-      const { object } = await generateObject({
-        model,
-        schema: opts.schema,
-        prompt: opts.prompt,
-        temperature: opts.temperature ?? 0,
-      });
-      return object as ZodOutput<T>;
-    },
-
-    async generateObjectFromMessages<T extends ZodType>(opts: {
-      messages: Message[];
-      schema: T;
-      temperature?: number;
-    }): Promise<ZodOutput<T>> {
-      // Convert libretto Message format to AI SDK message format
-      const messages = opts.messages.map((msg) => {
-        if (typeof msg.content === "string") {
-          return { role: msg.role, content: msg.content };
-        }
-        if (msg.role === "assistant") {
-          // AssistantContent only supports text parts (no images)
-          return {
-            role: "assistant" as const,
-            content: msg.content
-              .filter(
-                (part): part is typeof part & { type: "text" } =>
-                  part.type === "text",
-              )
-              .map((part) => ({ type: "text" as const, text: part.text })),
-          };
-        }
-        return {
-          role: "user" as const,
-          content: msg.content.map((part) =>
-            part.type === "text"
-              ? { type: "text" as const, text: part.text }
-              : {
-                  type: "image" as const,
-                  image: part.image,
-                  ...(part.mediaType ? { mediaType: part.mediaType } : {}),
-                },
-          ),
-        };
-      });
-
-      const { object } = await generateObject({
-        model,
-        schema: opts.schema,
-        messages,
-        temperature: opts.temperature ?? 0,
-      });
-      return object as ZodOutput<T>;
-    },
-  };
-}

package/src/shared/llm/index.ts

@@ -1,3 +0,0 @@
-export type { LLMClient, Message, MessageContentPart } from "./types.js";
-export { createLLMClient } from "./client.js";
-export { createLLMClientFromModel } from "./ai-sdk-adapter.js";

package/src/shared/llm/types.ts

@@ -1,63 +0,0 @@
-import type z from "zod";
-
-export type MessageContentPart =
-  | { type: "text"; text: string }
-  | { type: "image"; image: string | Uint8Array; mediaType?: string };
-
-export type Message = {
-  role: "user" | "assistant";
-  content: string | MessageContentPart[];
-};
-
-/**
- * Pluggable LLM client interface.
- *
- * Users provide their own implementation backed by any LLM provider
- * (OpenAI, Anthropic, etc.). Libretto uses this interface for AI extraction,
- * recovery agents, and error detection.
- *
- * **Error handling:** implementations should throw on failure rather than
- * returning sentinel values (e.g. `null` or `undefined`). Libretto relies
- * on exceptions to trigger retry/recovery logic.
- *
- * A ready-made adapter for the Vercel AI SDK is available via
- * {@link createLLMClientFromModel} in `libretto/llm`.
- */
-export interface LLMClient {
-  /**
-   * Generate a structured object from a single text prompt.
-   *
-   * The underlying model **must** support structured / JSON output so that
-   * the response can be parsed and validated against the provided Zod schema.
-   *
-   * @param opts.prompt - The text prompt sent to the model.
-   * @param opts.schema - A Zod schema describing the expected response shape.
-   * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
-   * @returns The parsed object matching the schema.
-   * @throws On LLM or parsing failure.
-   */
-  generateObject<T extends z.ZodType>(opts: {
-    prompt: string;
-    schema: T;
-    temperature?: number;
-  }): Promise<z.output<T>>;
-
-  /**
-   * Generate a structured object from a conversation-style message array.
-   *
-   * Messages may contain **image content** (base64 data URIs via
-   * {@link MessageContentPart}), so the backing model must support
-   * vision / multimodal input when images are present.
-   *
-   * @param opts.messages - Ordered list of user/assistant messages, potentially multimodal.
-   * @param opts.schema - A Zod schema describing the expected response shape.
-   * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
-   * @returns The parsed object matching the schema.
-   * @throws On LLM or parsing failure.
-   */
-  generateObjectFromMessages<T extends z.ZodType>(opts: {
-    messages: Message[];
-    schema: T;
-    temperature?: number;
-  }): Promise<z.output<T>>;
-}