libretto 0.6.11 → 0.6.13

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

@@ -1,666 +0,0 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { extname, isAbsolute, join, resolve } from "node:path";
-import { spawn } from "node:child_process";
-import { tmpdir } from "node:os";
-import { z } from "zod";
-const InterpretResultSchema = z.object({
-  answer: z.string(),
-  selectors: z.array(
-    z.object({
-      label: z.string(),
-      selector: z.string(),
-      rationale: z.string()
-    })
-  ),
-  notes: z.string()
-});
-class UserCodingAgent {
-  constructor(config) {
-    this.config = config;
-  }
-  static resolveFromConfig(config) {
-    switch (config.preset) {
-      case "codex":
-        return new CodexUserCodingAgent(config);
-      case "claude":
-        return new ClaudeUserCodingAgent(config);
-      case "gemini":
-        return new GeminiUserCodingAgent(config);
-    }
-  }
-  static readConfiguredConfig() {
-    return null;
-  }
-  static getConfigured() {
-    const config = this.readConfiguredConfig();
-    return config ? this.resolveFromConfig(config) : null;
-  }
-  get snapshotAnalyzerConfig() {
-    return this.config;
-  }
-  get command() {
-    const command = this.config.commandPrefix[0];
-    if (!command) {
-      throw new Error("AI config is invalid: command prefix is empty.");
-    }
-    return command;
-  }
-  get baseArgs() {
-    return this.config.commandPrefix.slice(1);
-  }
-  screenshotHint(pngPath) {
-    return `
-
-Screenshot file path: ${pngPath}
-Use the screenshot alongside the HTML snapshot context above.`;
-  }
-  async runAnalyzer(args, logger, stdinText) {
-    const result = await runExternalCommand(
-      this.command,
-      args,
-      logger,
-      stdinText
-    );
-    if (result.exitCode !== 0) {
-      throw new Error(
-        `Analyzer command failed (${[this.command, ...args].join(" ")}).
-${stripAnsi(result.stderr).trim() || stripAnsi(result.stdout).trim() || "No error output."}`
-      );
-    }
-    return result;
-  }
-  async runAndParse(args, logger, stdinText) {
-    const result = await this.runAnalyzer(args, logger, stdinText);
-    return parseInterpretResultFromText(result.stdout);
-  }
-}
-class CodexUserCodingAgent extends UserCodingAgent {
-  async analyzeSnapshot(prompt, pngPath, logger) {
-    const tempDir = mkdtempSync(join(tmpdir(), "libretto-analyzer-"));
-    const outputPath = join(
-      tempDir,
-      `snapshot-analyzer-${Date.now()}-${Math.random().toString(36).slice(2)}.json`
-    );
-    const args = [
-      ...this.baseArgs,
-      "--output-last-message",
-      outputPath,
-      "-i",
-      pngPath,
-      "-"
-    ];
-    logger.info("interpret-analyzer-codex-start", {
-      outputPath,
-      pngPath,
-      promptChars: prompt.length,
-      args
-    });
-    const result = await this.runAnalyzer(args, logger, prompt);
-    let outputText = result.stdout;
-    try {
-      logger.info("interpret-analyzer-codex-finish", {
-        outputPath,
-        outputFileExists: existsSync(outputPath),
-        stdoutChars: result.stdout.length,
-        stderrChars: result.stderr.length
-      });
-      if (existsSync(outputPath)) {
-        outputText = readFileSync(outputPath, "utf-8");
-      }
-      return parseInterpretResultFromText(outputText);
-    } finally {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  }
-}
-class ClaudeUserCodingAgent extends UserCodingAgent {
-  async analyzeSnapshot(prompt, pngPath, logger) {
-    return await this.runAndParse(
-      [...this.baseArgs],
-      logger,
-      `${prompt}${this.screenshotHint(pngPath)}`
-    );
-  }
-}
-class GeminiUserCodingAgent extends UserCodingAgent {
-  async analyzeSnapshot(prompt, pngPath, logger) {
-    return await this.runAndParse(
-      [...this.baseArgs],
-      logger,
-      `${prompt}${this.screenshotHint(pngPath)}`
-    );
-  }
-}
-async function runExternalCommand(command, args, logger, stdinText) {
-  return await new Promise((resolve2, reject) => {
-    const startedAt = Date.now();
-    logger.info("interpret-analyzer-spawn-start", {
-      command,
-      args,
-      stdinChars: stdinText?.length ?? 0
-    });
-    const child = spawn(command, args, {
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    let stdinError = null;
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.stdin.on("error", (err) => {
-      stdinError = err;
-      logger.warn("interpret-analyzer-stdin-pipe-error", {
-        command,
-        args,
-        code: stdinError.code ?? null,
-        message: stdinError.message,
-        hint: stdinError.code === "EPIPE" ? "Child process exited before consuming all stdin data" : "Unexpected stdin write error"
-      });
-    });
-    child.on("error", (err) => {
-      logger.error("interpret-analyzer-spawn-error", {
-        command,
-        args,
-        error: err
-      });
-      const error = err;
-      if (error.code === "ENOENT") {
-        reject(
-          new Error(
-            `Command not found: ${command}. Configure AI with 'libretto ai configure'.`
-          )
-        );
-        return;
-      }
-      reject(err);
-    });
-    child.on("close", (code) => {
-      const stdinNote = formatStdinError(stderr, stdinError);
-      const combinedStderr = `${stderr}${stdinNote}`;
-      logger.info("interpret-analyzer-spawn-close", {
-        command,
-        args,
-        exitCode: code ?? 1,
-        durationMs: Date.now() - startedAt,
-        stdoutChars: stdout.length,
-        stderrChars: combinedStderr.length,
-        stdinErrorCode: stdinError?.code ?? null,
-        stdoutPreview: summarizeForLog(stdout),
-        stderrPreview: summarizeForLog(combinedStderr)
-      });
-      resolve2({
-        exitCode: code ?? 1,
-        stdout,
-        stderr: combinedStderr
-      });
-    });
-    try {
-      if (stdinText !== void 0) {
-        child.stdin.end(stdinText);
-      } else {
-        child.stdin.end();
-      }
-    } catch (err) {
-      stdinError = err;
-      logger.warn("interpret-analyzer-stdin-write-error", {
-        command,
-        args,
-        code: stdinError.code ?? null,
-        message: stdinError.message,
-        hint: stdinError.code === "EPIPE" ? "Child process exited before consuming all stdin data" : "Unexpected stdin write error"
-      });
-    }
-  });
-}
-function stripAnsi(value) {
-  return value.replace(
-    /\u001b\[[0-9;]*[A-Za-z]|\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g,
-    ""
-  );
-}
-function summarizeForLog(value, maxChars = 800) {
-  const cleaned = stripAnsi(value).trim();
-  if (!cleaned) return "";
-  if (cleaned.length <= maxChars) return cleaned;
-  return `${cleaned.slice(0, maxChars)}\u2026 [truncated ${cleaned.length - maxChars} chars]`;
-}
-function formatStdinError(stderr, error) {
-  if (!error) return "";
-  const detail = error.code === "EPIPE" ? "Analyzer closed stdin before Libretto finished sending the snapshot prompt." : `Analyzer stdin error: ${error.message}`;
-  if (stderr.includes(detail)) return "";
-  return `${stderr.endsWith("\n") || stderr.length === 0 ? "" : "\n"}${detail}
-`;
-}
-function extractJsonObjectCandidates(text) {
-  const candidates = [];
-  const seen = /* @__PURE__ */ new Set();
-  const add = (value) => {
-    const trimmed = value.trim();
-    if (!trimmed || seen.has(trimmed)) return;
-    seen.add(trimmed);
-    candidates.push(trimmed);
-  };
-  try {
-    const direct = text.trim();
-    if (direct.startsWith("{") && direct.endsWith("}")) {
-      add(direct);
-    }
-  } catch {
-  }
-  const codeBlockRegex = /```(?:json)?\s*([\s\S]*?)```/gi;
-  let codeBlockMatch;
-  while ((codeBlockMatch = codeBlockRegex.exec(text)) !== null) {
-    const body = codeBlockMatch[1]?.trim();
-    if (body && body.startsWith("{") && body.endsWith("}")) {
-      add(body);
-    }
-  }
-  const lines = text.split("\n");
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
-      add(trimmed);
-    }
-  }
-  let depth = 0;
-  let start = -1;
-  let inString = false;
-  let escaped = false;
-  for (let i = 0; i < text.length; i++) {
-    const char = text[i];
-    if (inString) {
-      if (escaped) {
-        escaped = false;
-        continue;
-      }
-      if (char === "\\") {
-        escaped = true;
-        continue;
-      }
-      if (char === '"') {
-        inString = false;
-      }
-      continue;
-    }
-    if (char === '"') {
-      inString = true;
-      continue;
-    }
-    if (char === "{") {
-      if (depth === 0) start = i;
-      depth += 1;
-      continue;
-    }
-    if (char === "}") {
-      if (depth > 0) depth -= 1;
-      if (depth === 0 && start >= 0) {
-        add(text.slice(start, i + 1));
-        start = -1;
-      }
-    }
-  }
-  return candidates;
-}
-function collectStringLeaves(value, out, depth = 0) {
-  if (depth > 6 || value == null) return;
-  if (typeof value === "string") {
-    out.push(value);
-    return;
-  }
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      collectStringLeaves(item, out, depth + 1);
-    }
-    return;
-  }
-  if (typeof value === "object") {
-    for (const nested of Object.values(value)) {
-      collectStringLeaves(nested, out, depth + 1);
-    }
-  }
-}
-function parseInterpretResultFromText(text) {
-  const cleaned = stripAnsi(text).trim();
-  const candidates = extractJsonObjectCandidates(cleaned);
-  if (candidates.length === 0) {
-    throw new Error(
-      "Analyzer output did not include a JSON object matching the interpret schema."
-    );
-  }
-  for (const candidate of candidates) {
-    try {
-      const parsed = JSON.parse(candidate);
-      const valid = InterpretResultSchema.safeParse(parsed);
-      if (valid.success) {
-        return valid.data;
-      }
-      const nestedStrings = [];
-      collectStringLeaves(parsed, nestedStrings);
-      for (const nestedText of nestedStrings) {
-        const nestedCandidates = extractJsonObjectCandidates(nestedText);
-        for (const nestedCandidate of nestedCandidates) {
-          try {
-            const nestedParsed = JSON.parse(nestedCandidate);
-            const nestedValid = InterpretResultSchema.safeParse(nestedParsed);
-            if (nestedValid.success) {
-              return nestedValid.data;
-            }
-          } catch {
-          }
-        }
-      }
-    } catch {
-    }
-  }
-  throw new Error(
-    "Analyzer output could not be parsed as valid interpret JSON. Ensure the configured command returns only the requested JSON object."
-  );
-}
-function resolvePath(filePath) {
-  return isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
-}
-function getMimeType(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  if (ext === ".png") return "image/png";
-  if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
-  if (ext === ".webp") return "image/webp";
-  if (ext === ".gif") return "image/gif";
-  return "application/octet-stream";
-}
-function readFileAsBase64(filePath) {
-  return readFileSync(filePath).toString("base64");
-}
-function truncateText(text, maxChars) {
-  if (text.length <= maxChars) {
-    return { text, truncated: false };
-  }
-  const head = text.slice(0, Math.floor(maxChars * 0.6));
-  const tail = text.slice(-Math.floor(maxChars * 0.4));
-  return {
-    text: `${head}
-
-... [truncated] ...
-
-${tail}`,
-    truncated: true
-  };
-}
-function collectSelectorHints(html, limit = 120) {
-  const candidates = [];
-  const seen = /* @__PURE__ */ new Set();
-  const add = (value) => {
-    if (candidates.length >= limit || seen.has(value)) return;
-    seen.add(value);
-    candidates.push(value);
-  };
-  const selectors = [
-    { attr: "data-testid", format: (value) => `[data-testid="${value}"]` },
-    { attr: "data-test", format: (value) => `[data-test="${value}"]` },
-    { attr: "data-qa", format: (value) => `[data-qa="${value}"]` },
-    { attr: "aria-label", format: (value) => `[aria-label="${value}"]` },
-    { attr: "role", format: (value) => `[role="${value}"]` },
-    { attr: "name", format: (value) => `[name="${value}"]` },
-    { attr: "placeholder", format: (value) => `[placeholder="${value}"]` },
-    { attr: "id", format: (value) => `#${value}` }
-  ];
-  for (const selector of selectors) {
-    const regex = new RegExp(`${selector.attr}\\s*=\\s*["']([^"']+)["']`, "gi");
-    let match;
-    while ((match = regex.exec(html)) !== null) {
-      const value = match[1]?.trim();
-      if (!value) continue;
-      add(selector.format(value));
-      if (candidates.length >= limit) break;
-    }
-    if (candidates.length >= limit) break;
-  }
-  return candidates;
-}
-function estimateTokensFromChars(chars) {
-  return Math.ceil(chars / 4);
-}
-function inferContextWindowTokens(model) {
-  const normalized = model.trim().toLowerCase();
-  if (normalized.includes("claude")) {
-    return { contextWindowTokens: 2e5, source: "model:claude" };
-  }
-  if (normalized.includes("gpt-5") || normalized.includes("o3") || normalized.includes("o4")) {
-    return { contextWindowTokens: 2e5, source: "model:openai" };
-  }
-  if (normalized.includes("gemini")) {
-    return { contextWindowTokens: 1e6, source: "model:gemini" };
-  }
-  if (normalized.startsWith("openai/") || normalized.startsWith("codex/")) {
-    return { contextWindowTokens: 2e5, source: "provider:openai" };
-  }
-  if (normalized.startsWith("anthropic/")) {
-    return { contextWindowTokens: 2e5, source: "provider:anthropic" };
-  }
-  if (normalized.startsWith("google/") || normalized.startsWith("vertex/")) {
-    return { contextWindowTokens: 1e6, source: "provider:google" };
-  }
-  return { contextWindowTokens: 128e3, source: "default" };
-}
-function buildSnapshotBudget(model) {
-  const { contextWindowTokens, source } = inferContextWindowTokens(model);
-  const outputReserveTokens = Math.min(
-    32e3,
-    Math.max(8e3, Math.floor(contextWindowTokens * 0.1))
-  );
-  const promptBudgetTokens = Math.max(
-    8e3,
-    contextWindowTokens - outputReserveTokens - 2e3
-  );
-  return {
-    contextWindowTokens,
-    outputReserveTokens,
-    promptBudgetTokens,
-    source
-  };
-}
-function buildInterpretInstructions() {
-  let prompt = `# Instructions
-`;
-  prompt += `You are analyzing a screenshot and HTML snapshot of the same web page on behalf of an automation agent.
-`;
-  prompt += `The agent needs to interact with this page programmatically using Playwright.
-
-`;
-  prompt += `Based on the objective and context above:
-`;
-  prompt += `1. Answer the objective concisely
-`;
-  prompt += `2. Identify ALL interactive elements relevant to the objective and provide Playwright-ready CSS selectors
-`;
-  prompt += `3. Note any relevant page state (loading indicators, error messages, disabled elements, modals/overlays)
-`;
-  prompt += `4. If elements are inside iframes, identify the iframe selector and the element selector within it
-
-`;
-  prompt += `Output JSON with this shape:
-`;
-  prompt += `{"answer": string, "selectors": [{"label": string, "selector": string, "rationale": string}], "notes": string}
-
-`;
-  prompt += `Selectors should prefer robust attributes: data-testid, data-test, aria-label, name, id, role. Avoid fragile class-based or positional selectors.
-`;
-  prompt += `Only include selectors that exist in the HTML snapshot.
-`;
-  return prompt;
-}
-function buildInlineHtmlPrompt(args, options) {
-  const selectorHints = collectSelectorHints(options.htmlContent, 120);
-  let prompt = `# Objective
-${args.objective}
-
-`;
-  prompt += `# Context
-${args.context}
-
-`;
-  prompt += `# Snapshot Selection
-`;
-  prompt += `- Selected HTML snapshot: ${options.domLabel}
-`;
-  prompt += `- Selection reason: ${options.selectionReason}
-
-`;
-  prompt += buildInterpretInstructions();
-  if (selectorHints.length > 0) {
-    prompt += `
-Selector hints from HTML attributes (use if relevant):
-`;
-    prompt += selectorHints.map((hint) => `- ${hint}`).join("\n");
-    prompt += "\n";
-  }
-  if (options.truncated) {
-    prompt += `
-HTML content is truncated to fit token limits.
-`;
-  }
-  prompt += `
-HTML snapshot (${options.domLabel}):
-
-${options.htmlContent}`;
-  prompt += "\n\nReturn only a JSON object. Do not include markdown code fences or extra commentary.";
-  return prompt;
-}
-function buildInlinePromptSelection(args, fullHtmlContent, condensedHtmlContent, model) {
-  const budget = buildSnapshotBudget(model);
-  const stats = {
-    fullDomChars: fullHtmlContent.length,
-    fullDomEstimatedTokens: estimateTokensFromChars(fullHtmlContent.length),
-    condensedDomChars: condensedHtmlContent.length,
-    condensedDomEstimatedTokens: estimateTokensFromChars(
-      condensedHtmlContent.length
-    ),
-    configuredModel: model
-  };
-  const buildCandidate = (domSource, htmlContent, selectionReason, truncated) => {
-    const domLabel = domSource === "full" ? "full DOM" : "condensed DOM";
-    const prompt = buildInlineHtmlPrompt(args, {
-      htmlContent,
-      domLabel,
-      truncated,
-      selectionReason,
-      budget,
-      stats
-    });
-    return {
-      prompt,
-      domSource,
-      domLabel,
-      htmlChars: htmlContent.length,
-      htmlEstimatedTokens: estimateTokensFromChars(htmlContent.length),
-      promptEstimatedTokens: estimateTokensFromChars(prompt.length),
-      truncated,
-      selectionReason,
-      budget,
-      stats
-    };
-  };
-  const fullCandidate = buildCandidate(
-    "full",
-    fullHtmlContent,
-    "placeholder",
-    false
-  );
-  if (fullCandidate.promptEstimatedTokens <= budget.promptBudgetTokens) {
-    const selectionReason = `Full DOM fits within the estimated prompt budget (~${fullCandidate.promptEstimatedTokens.toLocaleString()} <= ${budget.promptBudgetTokens.toLocaleString()} tokens), so the analyzer receives the uncondensed page HTML.`;
-    const prompt = buildInlineHtmlPrompt(args, {
-      htmlContent: fullHtmlContent,
-      domLabel: "full DOM",
-      truncated: false,
-      selectionReason,
-      budget,
-      stats
-    });
-    return {
-      ...fullCandidate,
-      selectionReason,
-      prompt,
-      promptEstimatedTokens: estimateTokensFromChars(prompt.length)
-    };
-  }
-  const condensedReason = `Full DOM would exceed the estimated prompt budget (~${fullCandidate.promptEstimatedTokens.toLocaleString()} > ${budget.promptBudgetTokens.toLocaleString()} tokens), so the analyzer receives the condensed DOM instead.`;
-  const condensedCandidate = buildCandidate(
-    "condensed",
-    condensedHtmlContent,
-    condensedReason,
-    false
-  );
-  if (condensedCandidate.promptEstimatedTokens <= budget.promptBudgetTokens) {
-    return condensedCandidate;
-  }
-  const truncateReason = `Both full and condensed DOM snapshots exceed the estimated prompt budget (full ~${fullCandidate.promptEstimatedTokens.toLocaleString()}, condensed ~${condensedCandidate.promptEstimatedTokens.toLocaleString()}, budget ${budget.promptBudgetTokens.toLocaleString()} tokens), so the condensed DOM is truncated to fit.`;
-  const basePrompt = buildInlineHtmlPrompt(args, {
-    htmlContent: "",
-    domLabel: "condensed DOM",
-    truncated: true,
-    selectionReason: truncateReason,
-    budget,
-    stats
-  });
-  const availableHtmlTokens = Math.max(
-    2e3,
-    budget.promptBudgetTokens - estimateTokensFromChars(basePrompt.length)
-  );
-  const truncatedHtml = truncateText(
-    condensedHtmlContent,
-    availableHtmlTokens * 4
-  );
-  return buildCandidate(
-    "condensed",
-    truncatedHtml.text,
-    truncateReason,
-    truncatedHtml.truncated
-  );
-}
-async function runInterpret(args, logger) {
-  logger.info("interpret-start", {
-    objective: args.objective,
-    pngPath: args.pngPath,
-    htmlPath: args.htmlPath,
-    condensedHtmlPath: args.condensedHtmlPath
-  });
-  process.env.NODE_ENV = "development";
-  const pngPath = resolvePath(args.pngPath);
-  const htmlPath = resolvePath(args.htmlPath);
-  const condensedHtmlPath = resolvePath(args.condensedHtmlPath);
-  if (!existsSync(pngPath)) {
-    throw new Error(`PNG file not found: ${pngPath}`);
-  }
-  if (!existsSync(htmlPath)) {
-    throw new Error(`HTML file not found: ${htmlPath}`);
-  }
-  if (!existsSync(condensedHtmlPath)) {
-    throw new Error(`Condensed HTML file not found: ${condensedHtmlPath}`);
-  }
-  const fullHtmlContent = readFileSync(htmlPath, "utf-8");
-  const condensedHtmlContent = readFileSync(condensedHtmlPath, "utf-8");
-  const configuredAgent = UserCodingAgent.getConfigured();
-  if (!configuredAgent) {
-    throw new Error(
-      "No AI config set. Run 'npx libretto ai configure codex' (or claude/gemini), or set API credentials in your .env file for direct API analysis."
-    );
-  }
-  const configuredAnalyzer = configuredAgent.snapshotAnalyzerConfig;
-  throw new Error(
-    "The CLI-agent snapshot analysis path is not active. Update your config to the current format with `npx libretto ai configure <provider>`, or set API credentials in .env for direct API analysis."
-  );
-}
-function canAnalyzeSnapshots() {
-  return UserCodingAgent.getConfigured() !== null;
-}
-export {
-  InterpretResultSchema,
-  buildInlinePromptSelection,
-  canAnalyzeSnapshots,
-  getMimeType,
-  readFileAsBase64,
-  runInterpret
-};