libretto 0.4.4 → 0.5.1

package/src/cli/core/snapshot-api-config.ts

@@ -0,0 +1,231 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { type AiConfig, readAiConfig } from "./ai-config.js";
+import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
+import {
+  hasProviderCredentials,
+  parseModel,
+  type Provider,
+} from "../../shared/llm/client.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",
+} as const satisfies Record<Provider, string>;
+
+export type SnapshotApiModelSelection = {
+  model: string;
+  provider: Provider;
+  source:
+    | "config"
+    | "env:auto-openai"
+    | "env:auto-anthropic"
+    | "env:auto-google"
+    | "env:auto-vertex";
+};
+
+export class SnapshotApiUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SnapshotApiUnavailableError";
+  }
+}
+
+function providerSetupSentence(provider: Provider): string {
+  switch (provider) {
+    case "openai":
+      return "Add OPENAI_API_KEY to .env or as a shell environment variable.";
+    case "anthropic":
+      return "Add ANTHROPIC_API_KEY to .env or as a shell environment variable.";
+    case "google":
+      return "Add GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY to .env or as a shell environment variable.";
+    case "vertex":
+      return "Add GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT to .env or as a shell environment variable, and make sure application default credentials are configured.";
+  }
+}
+
+function defaultModelCommandLine(): string {
+  return "npx libretto ai configure openai | anthropic | gemini | vertex";
+}
+
+function providerMissingCredentialSummary(provider: Provider): string {
+  switch (provider) {
+    case "openai":
+      return "OPENAI_API_KEY is missing";
+    case "anthropic":
+      return "ANTHROPIC_API_KEY is missing";
+    case "google":
+      return "GEMINI_API_KEY and GOOGLE_GENERATIVE_AI_API_KEY are missing";
+    case "vertex":
+      return "GOOGLE_CLOUD_PROJECT and GCLOUD_PROJECT are missing";
+  }
+}
+
+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, 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`.",
+  ].join(" ");
+}
+
+function missingProviderSnapshotMessage(
+  selection: SnapshotApiModelSelection,
+): string {
+  const configuredSource =
+    selection.source === "config"
+      ? ` in ${LIBRETTO_CONFIG_PATH}`
+      : " from process env or .env";
+  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`.",
+  ].join(" ");
+}
+
+function readWorktreeEnvPath(): string | null {
+  const gitPath = join(REPO_ROOT, ".git");
+  if (!existsSync(gitPath)) return null;
+
+  try {
+    const gitPointer = readFileSync(gitPath, "utf-8").trim();
+    const match = gitPointer.match(/^gitdir:\s*(.+)$/i);
+    if (!match?.[1]) return null;
+    const worktreeGitDir = resolve(REPO_ROOT, match[1].trim());
+    const commonGitDir = resolve(worktreeGitDir, "..", "..");
+    return join(dirname(commonGitDir), ".env");
+  } catch {
+    return null;
+  }
+}
+
+export function loadSnapshotEnv(): void {
+  if (process.env.LIBRETTO_DISABLE_DOTENV?.trim() === "1") return;
+
+  const envPathCandidates = [
+    join(REPO_ROOT, ".env"),
+    readWorktreeEnvPath(),
+  ].filter((value): value is string => Boolean(value));
+
+  const envPath = envPathCandidates.find((candidate) => existsSync(candidate));
+  if (!envPath) return;
+
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const parsed = parseDotEnvAssignment(line);
+    if (!parsed) continue;
+    if (!(parsed.key in process.env)) {
+      process.env[parsed.key] = parsed.value;
+    }
+  }
+}
+
+export function parseDotEnvAssignment(
+  line: string,
+): { key: string; value: string } | null {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+
+  const withoutExport = trimmed.startsWith("export ")
+    ? trimmed.slice("export ".length).trimStart()
+    : trimmed;
+  const eqIdx = withoutExport.indexOf("=");
+  if (eqIdx < 1) return null;
+
+  const key = withoutExport.slice(0, eqIdx).trim();
+  if (!key) return null;
+
+  const rawValue = withoutExport.slice(eqIdx + 1).trimStart();
+  if (!rawValue) {
+    return { key, value: "" };
+  }
+
+  if (rawValue.startsWith('"')) {
+    const closeIdx = rawValue.indexOf('"', 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
+    }
+    return { key, value: rawValue.slice(1) };
+  }
+
+  if (rawValue.startsWith("'")) {
+    const closeIdx = rawValue.indexOf("'", 1);
+    if (closeIdx > 0) {
+      return { key, value: rawValue.slice(1, closeIdx) };
+    }
+    return { key, value: rawValue.slice(1) };
+  }
+
+  const inlineCommentIndex = rawValue.search(/\s#/);
+  const value =
+    inlineCommentIndex >= 0
+      ? rawValue.slice(0, inlineCommentIndex).trimEnd()
+      : rawValue.trim();
+  return { key, value };
+}
+
+function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
+  const providersInPriorityOrder: Provider[] = [
+    "openai",
+    "anthropic",
+    "google",
+    "vertex",
+  ];
+
+  for (const provider of providersInPriorityOrder) {
+    if (!hasProviderCredentials(provider)) continue;
+    return {
+      model: DEFAULT_SNAPSHOT_MODELS[provider],
+      provider,
+      source: `env:auto-${provider}` as SnapshotApiModelSelection["source"],
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Resolve which API model to use for snapshot analysis.
+ *
+ * Priority:
+ * 1. Model from .libretto/config.json ai.model field (set via `ai configure`)
+ * 2. Auto-detect from available API credentials in env
+ */
+export function resolveSnapshotApiModel(
+  config: AiConfig | null = readAiConfig(),
+): SnapshotApiModelSelection | null {
+  loadSnapshotEnv();
+
+  if (config?.model) {
+    const { provider } = parseModel(config.model);
+    return {
+      model: config.model,
+      provider,
+      source: "config",
+    };
+  }
+
+  return inferAutoSnapshotModel();
+}
+
+export function resolveSnapshotApiModelOrThrow(
+  config: AiConfig | null = readAiConfig(),
+): SnapshotApiModelSelection {
+  const selection = resolveSnapshotApiModel(config);
+  if (!selection) {
+    throw new SnapshotApiUnavailableError(noSnapshotApiConfiguredMessage());
+  }
+
+  if (!hasProviderCredentials(selection.provider)) {
+    throw new SnapshotApiUnavailableError(
+      missingProviderSnapshotMessage(selection),
+    );
+  }
+
+  return selection;
+}
+
+export function isSnapshotApiUnavailableError(error: unknown): boolean {
+  return error instanceof SnapshotApiUnavailableError;
+}

package/src/cli/core/telemetry.ts

@@ -0,0 +1,459 @@
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import type { Page } from "playwright";
+import {
+  getSessionActionsLogPath,
+  getSessionNetworkLogPath,
+} from "./context.js";
+import { assertSessionStateExistsOrThrow } from "./session.js";
+
+export type NetworkLogEntry = {
+  ts: string;
+  pageId?: string;
+  method: string;
+  url: string;
+  status: number;
+  contentType: string | null;
+  postData?: string;
+  responseBody?: string | null;
+  size: number | null;
+  durationMs: number | null;
+};
+
+export function readNetworkLog(
+  session: string,
+  opts: {
+    last?: number;
+    filter?: string;
+    method?: string;
+    pageId?: string;
+  } = {},
+): NetworkLogEntry[] {
+  assertSessionStateExistsOrThrow(session);
+  const logPath = getSessionNetworkLogPath(session);
+  if (!existsSync(logPath)) return [];
+
+  const lines = readFileSync(logPath, "utf-8")
+    .trim()
+    .split("\n")
+    .filter(Boolean);
+  let entries: NetworkLogEntry[] = lines.map(
+    (line) => JSON.parse(line) as NetworkLogEntry,
+  );
+
+  if (opts.method) {
+    const m = opts.method.toUpperCase();
+    entries = entries.filter((e) => e.method === m);
+  }
+  if (opts.filter) {
+    const re = new RegExp(opts.filter, "i");
+    entries = entries.filter((e) => re.test(e.url));
+  }
+  if (opts.pageId) {
+    entries = entries.filter((e) => e.pageId === opts.pageId);
+  }
+
+  const last = opts.last ?? 20;
+  if (entries.length > last) {
+    entries = entries.slice(-last);
+  }
+
+  return entries;
+}
+
+export function formatNetworkEntry(e: NetworkLogEntry): string {
+  const time = e.ts.replace(/.*T/, "").replace(/\.\d+Z$/, "");
+  const duration = e.durationMs != null ? `${e.durationMs}ms` : "?ms";
+  const size = e.size != null ? `${e.size}B` : "";
+  const parts = [
+    `[${time}]`,
+    `${e.status}`,
+    `${e.method.padEnd(6)}`,
+    e.url,
+    duration,
+    size,
+  ].filter(Boolean);
+  let line = parts.join(" ");
+  if (e.postData) {
+    line += `\n         body: ${e.postData.substring(0, 120)}${e.postData.length > 120 ? "..." : ""}`;
+  }
+  return line;
+}
+
+export function clearNetworkLog(session: string): void {
+  assertSessionStateExistsOrThrow(session);
+  const logPath = getSessionNetworkLogPath(session);
+  writeFileSync(logPath, "");
+}
+
+export type ActionLogEntry = {
+  ts: string;
+  pageId?: string;
+  action: string;
+  source: "user" | "agent";
+  selector?: string;
+  value?: string;
+  url?: string;
+  duration?: number;
+  success: boolean;
+  error?: string;
+};
+
+export function parentLogAction(
+  session: string,
+  entry: Record<string, unknown>,
+): void {
+  try {
+    const record = { ts: new Date().toISOString(), ...entry };
+    appendFileSync(
+      getSessionActionsLogPath(session),
+      JSON.stringify(record) + "\n",
+    );
+  } catch {}
+}
+
+export function readActionLog(
+  session: string,
+  opts: {
+    last?: number;
+    filter?: string;
+    action?: string;
+    source?: string;
+    pageId?: string;
+  } = {},
+): ActionLogEntry[] {
+  assertSessionStateExistsOrThrow(session);
+  const logPath = getSessionActionsLogPath(session);
+  if (!existsSync(logPath)) return [];
+
+  const lines = readFileSync(logPath, "utf-8")
+    .trim()
+    .split("\n")
+    .filter(Boolean);
+  let entries: ActionLogEntry[] = lines.map(
+    (line) => JSON.parse(line) as ActionLogEntry,
+  );
+
+  if (opts.action) {
+    const a = opts.action.toLowerCase();
+    entries = entries.filter((e) => e.action === a);
+  }
+  if (opts.source) {
+    const s = opts.source.toLowerCase();
+    entries = entries.filter((e) => e.source === s);
+  }
+  if (opts.filter) {
+    const re = new RegExp(opts.filter, "i");
+    entries = entries.filter(
+      (e) =>
+        re.test(e.action) ||
+        re.test(e.selector || "") ||
+        re.test(e.value || "") ||
+        re.test(e.url || ""),
+    );
+  }
+  if (opts.pageId) {
+    entries = entries.filter((e) => e.pageId === opts.pageId);
+  }
+
+  const last = opts.last ?? 20;
+  if (entries.length > last) {
+    entries = entries.slice(-last);
+  }
+
+  return entries;
+}
+
+export function formatActionEntry(e: ActionLogEntry): string {
+  const time = e.ts.replace(/.*T/, "").replace(/\.\d+Z$/, "");
+  const src = e.source.toUpperCase().padEnd(5);
+  const parts = [`[${time}]`, `[${src}]`, e.action];
+  if (e.selector) parts.push(e.selector);
+  if (e.value) parts.push(`"${e.value}"`);
+  if (e.url) parts.push(e.url);
+  if (e.duration != null) parts.push(`${e.duration}ms`);
+  if (!e.success) parts.push(`ERROR: ${e.error || "unknown"}`);
+  return parts.join(" ");
+}
+
+export function clearActionLog(session: string): void {
+  assertSessionStateExistsOrThrow(session);
+  const logPath = getSessionActionsLogPath(session);
+  writeFileSync(logPath, "");
+}
+
+const LOCATOR_ACTION_METHODS = [
+  "click",
+  "dblclick",
+  "fill",
+  "type",
+  "press",
+  "check",
+  "uncheck",
+  "selectOption",
+  "hover",
+  "focus",
+  "scrollIntoViewIfNeeded",
+  "waitFor",
+  "innerHTML",
+  "innerText",
+  "textContent",
+  "inputValue",
+  "isChecked",
+  "isDisabled",
+  "isEditable",
+  "isEnabled",
+  "isHidden",
+  "isVisible",
+  "count",
+  "boundingBox",
+  "screenshot",
+  "evaluate",
+  "evaluateAll",
+  "evaluateHandle",
+  "getAttribute",
+  "dispatchEvent",
+  "setInputFiles",
+  "selectText",
+  "dragTo",
+  "highlight",
+  "tap",
+] as const;
+
+const LOCATOR_RETURNING_METHODS = [
+  "first",
+  "last",
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "filter",
+  "and",
+  "or",
+] as const;
+
+function formatHint(method: string, args: any[]): string {
+  const formatted = args.map((a: any) => JSON.stringify(a)).join(", ");
+  return `${method}(${formatted})`;
+}
+
+function wrapLocator(
+  locator: any,
+  hint: string,
+  session: string,
+  page: Page,
+  pageId?: string,
+  onActivity?: () => void,
+): any {
+  if (locator.__librettoActionLogged) return locator;
+  locator.__librettoActionLogged = true;
+
+  for (const actMethod of LOCATOR_ACTION_METHODS) {
+    if (typeof locator[actMethod] !== "function") continue;
+    const origAct = locator[actMethod].bind(locator);
+    locator[actMethod] = async (...actArgs: any[]) => {
+      const start = Date.now();
+      try {
+        await page.evaluate(() => {
+          (window as any).__btApiActionInProgress = true;
+        });
+      } catch {}
+      try {
+        const result = await origAct(...actArgs);
+        parentLogAction(session, {
+          pageId,
+          action: actMethod,
+          source: "agent",
+          selector: hint,
+          value:
+            actArgs[0] !== undefined
+              ? String(actArgs[0]).slice(0, 100)
+              : undefined,
+          duration: Date.now() - start,
+          success: true,
+        });
+        onActivity?.();
+        return result;
+      } catch (err: any) {
+        parentLogAction(session, {
+          pageId,
+          action: actMethod,
+          source: "agent",
+          selector: hint,
+          duration: Date.now() - start,
+          success: false,
+          error: err.message,
+        });
+        onActivity?.();
+        throw err;
+      } finally {
+        try {
+          await page.evaluate(() => {
+            (window as any).__btApiActionInProgress = false;
+          });
+        } catch {}
+      }
+    };
+  }
+
+  for (const method of LOCATOR_RETURNING_METHODS) {
+    if (typeof locator[method] !== "function") continue;
+    const origMethod = locator[method].bind(locator);
+    locator[method] = (...args: any[]) => {
+      const child = origMethod(...args);
+      const childHint =
+        args.length > 0
+          ? `${hint}.${formatHint(method, args)}`
+          : `${hint}.${method}()`;
+      return wrapLocator(child, childHint, session, page, pageId, onActivity);
+    };
+  }
+
+  if (typeof locator.nth === "function") {
+    const origNth = locator.nth.bind(locator);
+    locator.nth = (index: number) => {
+      const child = origNth(index);
+      const childHint = `${hint}.nth(${index})`;
+      return wrapLocator(child, childHint, session, page, pageId, onActivity);
+    };
+  }
+
+  if (typeof locator.all === "function") {
+    const origAll = locator.all.bind(locator);
+    locator.all = async () => {
+      const items: any[] = await origAll();
+      return items.map((item: any, i: number) => {
+        const childHint = `${hint}.all()[${i}]`;
+        return wrapLocator(item, childHint, session, page, pageId, onActivity);
+      });
+    };
+  }
+
+  return locator;
+}
+
+export function wrapPageForActionLogging(
+  page: Page,
+  session: string,
+  pageId?: string,
+  onActivity?: () => void,
+): void {
+  const PAGE_ACTIONS = [
+    "click",
+    "dblclick",
+    "fill",
+    "type",
+    "press",
+    "check",
+    "uncheck",
+    "selectOption",
+    "hover",
+    "focus",
+  ] as const;
+  const NAV_ACTIONS = ["goto", "reload", "goBack", "goForward"] as const;
+
+  for (const method of PAGE_ACTIONS) {
+    const orig = (page as any)[method].bind(page);
+    (page as any)[method] = async (...args: any[]) => {
+      const start = Date.now();
+      try {
+        await page.evaluate(() => {
+          (window as any).__btApiActionInProgress = true;
+        });
+      } catch {}
+      try {
+        const result = await orig(...args);
+        parentLogAction(session, {
+          pageId,
+          action: method,
+          source: "agent",
+          selector: typeof args[0] === "string" ? args[0] : undefined,
+          value:
+            args[1] !== undefined ? String(args[1]).slice(0, 100) : undefined,
+          duration: Date.now() - start,
+          success: true,
+        });
+        onActivity?.();
+        return result;
+      } catch (err: any) {
+        parentLogAction(session, {
+          pageId,
+          action: method,
+          source: "agent",
+          selector: typeof args[0] === "string" ? args[0] : undefined,
+          duration: Date.now() - start,
+          success: false,
+          error: err.message,
+        });
+        onActivity?.();
+        throw err;
+      } finally {
+        try {
+          await page.evaluate(() => {
+            (window as any).__btApiActionInProgress = false;
+          });
+        } catch {}
+      }
+    };
+  }
+
+  for (const method of NAV_ACTIONS) {
+    const orig = (page as any)[method].bind(page);
+    (page as any)[method] = async (...args: any[]) => {
+      const start = Date.now();
+      try {
+        const result = await orig(...args);
+        parentLogAction(session, {
+          pageId,
+          action: method,
+          source: "agent",
+          url: typeof args[0] === "string" ? args[0] : page.url(),
+          duration: Date.now() - start,
+          success: true,
+        });
+        onActivity?.();
+        return result;
+      } catch (err: any) {
+        parentLogAction(session, {
+          pageId,
+          action: method,
+          source: "agent",
+          url: typeof args[0] === "string" ? args[0] : undefined,
+          duration: Date.now() - start,
+          success: false,
+          error: err.message,
+        });
+        onActivity?.();
+        throw err;
+      }
+    };
+  }
+
+  const LOCATOR_FACTORIES = [
+    "locator",
+    "getByRole",
+    "getByText",
+    "getByLabel",
+    "getByPlaceholder",
+    "getByAltText",
+    "getByTitle",
+    "getByTestId",
+  ] as const;
+
+  for (const factory of LOCATOR_FACTORIES) {
+    const orig = (page as any)[factory].bind(page);
+    (page as any)[factory] = (...factoryArgs: any[]) => {
+      const locator = orig(...factoryArgs);
+      const hint = formatHint(factory, factoryArgs);
+      return wrapLocator(locator, hint, session, page, pageId, onActivity);
+    };
+  }
+}