libretto 0.3.0 → 0.3.2

package/dist/cli/commands/logs.js

@@ -0,0 +1,93 @@
+import { listOpenPages } from "../core/browser.js";
+import { withSessionLogger } from "../core/context.js";
+import {
+  clearActionLog,
+  clearNetworkLog,
+  formatActionEntry,
+  formatNetworkEntry,
+  readActionLog,
+  readNetworkLog
+} from "../core/telemetry.js";
+async function resolvePageId(session, pageId) {
+  if (!pageId) return void 0;
+  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-cli pages --session ${session}" to list ids.`
+    );
+  }
+  return pageId;
+}
+function registerLogCommands(yargs) {
+  return yargs.command(
+    "network",
+    "View captured network requests",
+    (cmd) => cmd.option("last", { type: "number" }).option("filter", { type: "string" }).option("method", { type: "string" }).option("page", { type: "string" }).option("clear", { type: "boolean", default: false }),
+    async (argv) => {
+      const session = String(argv.session);
+      if (argv.clear) {
+        clearNetworkLog(session);
+        console.log("Network log cleared.");
+        return;
+      }
+      const pageId = await resolvePageId(
+        session,
+        argv.page ? String(argv.page) : void 0
+      );
+      const entries = readNetworkLog(session, {
+        last: typeof argv.last === "number" ? argv.last : void 0,
+        filter: argv.filter,
+        method: argv.method,
+        pageId
+      });
+      if (entries.length === 0) {
+        console.log("No network requests captured.");
+        return;
+      }
+      for (const entry of entries) {
+        console.log(formatNetworkEntry(entry));
+      }
+      console.log(`
+${entries.length} request(s) shown.`);
+    }
+  ).command(
+    "actions",
+    "View captured actions",
+    (cmd) => cmd.option("last", { type: "number" }).option("filter", { type: "string" }).option("action", { type: "string" }).option("source", { type: "string" }).option("page", { type: "string" }).option("clear", { type: "boolean", default: false }),
+    async (argv) => {
+      const session = String(argv.session);
+      if (argv.clear) {
+        clearActionLog(session);
+        console.log("Action log cleared.");
+        return;
+      }
+      const pageId = await resolvePageId(
+        session,
+        argv.page ? String(argv.page) : void 0
+      );
+      const entries = readActionLog(session, {
+        last: typeof argv.last === "number" ? argv.last : void 0,
+        filter: argv.filter,
+        action: argv.action,
+        source: argv.source,
+        pageId
+      });
+      if (entries.length === 0) {
+        console.log("No actions captured.");
+        return;
+      }
+      for (const entry of entries) {
+        console.log(formatActionEntry(entry));
+      }
+      console.log(`
+${entries.length} action(s) shown.`);
+    }
+  );
+}
+export {
+  registerLogCommands
+};

package/dist/cli/commands/snapshot.js

@@ -0,0 +1,217 @@
+import { mkdirSync } from "node:fs";
+import { connect, disconnectBrowser } from "../core/browser.js";
+import { getSessionSnapshotRunDir } from "../core/context.js";
+import { readSessionState } from "../core/session.js";
+import {
+  canAnalyzeSnapshots,
+  runInterpret
+} from "../core/snapshot-analyzer.js";
+const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
+const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
+function generateSnapshotRunId() {
+  return `snapshot-${Date.now()}`;
+}
+function isZeroViewport(value) {
+  return typeof value === "number" && value <= 0;
+}
+function shouldForceSnapshotViewport(metrics) {
+  return isZeroViewport(metrics.configuredWidth) || isZeroViewport(metrics.configuredHeight) || isZeroViewport(metrics.innerWidth) || isZeroViewport(metrics.innerHeight);
+}
+function isZeroWidthScreenshotError(error) {
+  return error instanceof Error && error.message.includes("Cannot take screenshot with 0 width");
+}
+async function readSnapshotViewportMetrics(page) {
+  const configuredViewport = page.viewportSize();
+  let innerWidth = null;
+  let innerHeight = null;
+  try {
+    const innerViewport = await page.evaluate(() => ({
+      width: window.innerWidth,
+      height: window.innerHeight
+    }));
+    innerWidth = innerViewport.width;
+    innerHeight = innerViewport.height;
+  } catch {
+  }
+  return {
+    configuredWidth: configuredViewport?.width ?? null,
+    configuredHeight: configuredViewport?.height ?? null,
+    innerWidth,
+    innerHeight
+  };
+}
+function resolveSnapshotViewport(session, logger) {
+  const state = readSessionState(session, logger);
+  if (state?.viewport) {
+    logger.info("screenshot-viewport-from-session-state", {
+      session,
+      viewport: state.viewport
+    });
+    return state.viewport;
+  }
+  logger.info("screenshot-viewport-fallback", {
+    session,
+    reason: "no viewport in session state",
+    viewport: FALLBACK_SNAPSHOT_VIEWPORT
+  });
+  return FALLBACK_SNAPSHOT_VIEWPORT;
+}
+async function forceSnapshotViewport(page, viewport, logger, session, pageId, reason) {
+  await page.setViewportSize(viewport);
+  logger.warn("screenshot-viewport-forced", {
+    session,
+    pageId,
+    reason,
+    viewport
+  });
+}
+async function captureScreenshot(session, logger, pageId) {
+  logger.info("screenshot-start", { session, pageId });
+  const snapshotRunId = generateSnapshotRunId();
+  const snapshotRunDir = getSessionSnapshotRunDir(session, snapshotRunId);
+  mkdirSync(snapshotRunDir, { recursive: true });
+  const { browser, page } = await connect(session, logger, 1e4, {
+    pageId,
+    requireSinglePage: true
+  });
+  try {
+    let title = null;
+    try {
+      title = await page.title();
+    } catch (error) {
+      logger.warn("screenshot-title-read-failed", {
+        session,
+        pageId,
+        error
+      });
+    }
+    let pageUrl = null;
+    try {
+      pageUrl = page.url();
+    } catch (error) {
+      logger.warn("screenshot-url-read-failed", {
+        session,
+        pageId,
+        error
+      });
+    }
+    const pngPath = `${snapshotRunDir}/page.png`;
+    const htmlPath = `${snapshotRunDir}/page.html`;
+    const restoreViewport = resolveSnapshotViewport(session, logger);
+    const viewportMetrics = await readSnapshotViewportMetrics(page);
+    logger.info("screenshot-viewport-metrics", {
+      session,
+      pageId,
+      restoreViewport,
+      ...viewportMetrics
+    });
+    await forceSnapshotViewport(
+      page,
+      restoreViewport,
+      logger,
+      session,
+      pageId,
+      shouldForceSnapshotViewport(viewportMetrics) ? "preflight-invalid-viewport" : "preflight-normalize-viewport"
+    );
+    try {
+      await page.screenshot({ path: pngPath });
+    } catch (error) {
+      if (!isZeroWidthScreenshotError(error)) {
+        throw error;
+      }
+      await forceSnapshotViewport(
+        page,
+        restoreViewport,
+        logger,
+        session,
+        pageId,
+        "retry-after-zero-width-screenshot-error"
+      );
+      await page.screenshot({ path: pngPath });
+    }
+    const htmlContent = await page.content();
+    const fs = await import("node:fs/promises");
+    await fs.writeFile(htmlPath, htmlContent);
+    logger.info("screenshot-success", {
+      session,
+      pageUrl,
+      title,
+      pngPath,
+      htmlPath,
+      snapshotRunId
+    });
+    return { pngPath, htmlPath, baseName: snapshotRunId };
+  } catch (err) {
+    let pageAlive = false;
+    let browserConnected = false;
+    try {
+      browserConnected = browser.isConnected();
+      pageAlive = !page.isClosed();
+    } catch {
+    }
+    logger.error("screenshot-error", {
+      error: err,
+      session,
+      pageAlive,
+      browserConnected,
+      pageUrl: (() => {
+        try {
+          return page.url();
+        } catch {
+          return null;
+        }
+      })()
+    });
+    throw err;
+  } finally {
+    disconnectBrowser(browser, logger, session);
+  }
+}
+async function runSnapshot(session, logger, pageId, objective, context) {
+  const { pngPath, htmlPath } = await captureScreenshot(session, logger, pageId);
+  console.log("Screenshot saved:");
+  console.log(`  PNG:  ${pngPath}`);
+  console.log(`  HTML: ${htmlPath}`);
+  const normalizedObjective = objective?.trim();
+  const normalizedContext = context?.trim();
+  if (!normalizedObjective && !normalizedContext) {
+    console.log("Use --objective flag to analyze snapshots.");
+    return;
+  }
+  if (!normalizedObjective) {
+    throw new Error(
+      "Couldn't run analysis: --objective is required when providing --context."
+    );
+  }
+  if (!canAnalyzeSnapshots()) {
+    throw new Error(
+      "Couldn't run analysis: no AI config set. Run 'libretto-cli ai configure codex' (or claude/gemini) to enable analysis."
+    );
+  }
+  await runInterpret({
+    objective: normalizedObjective,
+    session,
+    context: normalizedContext ?? DEFAULT_SNAPSHOT_CONTEXT,
+    pngPath,
+    htmlPath
+  }, logger);
+}
+function registerSnapshotCommands(yargs, logger) {
+  return yargs.command(
+    "snapshot",
+    "Capture PNG + HTML; analyze when --objective is provided (--context optional)",
+    (cmd) => cmd.option("page", { type: "string" }).option("objective", { type: "string" }).option("context", { type: "string" }),
+    async (argv) => {
+      await runSnapshot(
+        String(argv.session),
+        logger,
+        argv.page ? String(argv.page) : void 0,
+        argv.objective,
+        argv.context
+      );
+    }
+  );
+}
+export {
+  registerSnapshotCommands
+};

package/dist/cli/core/ai-config.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { LIBRETTO_CONFIG_PATH } from "./context.js";
+const CURRENT_CONFIG_VERSION = 1;
+const AiPresetSchema = z.enum(["codex", "claude", "gemini"]);
+const AiConfigSchema = z.object({
+  preset: AiPresetSchema,
+  commandPrefix: z.array(z.string()).min(1),
+  updatedAt: z.string()
+}).strict();
+const ViewportConfigSchema = z.object({
+  width: z.number().int().min(1),
+  height: z.number().int().min(1)
+});
+const LibrettoConfigSchema = z.object({
+  version: z.literal(CURRENT_CONFIG_VERSION),
+  ai: AiConfigSchema.optional(),
+  viewport: ViewportConfigSchema.optional()
+}).passthrough();
+const AI_CONFIG_PRESETS = {
+  codex: ["codex", "exec", "--skip-git-repo-check", "--sandbox", "read-only"],
+  claude: [join(homedir(), ".claude", "local", "claude"), "-p"],
+  gemini: ["gemini", "--output-format", "json"]
+};
+function invalidConfigError(configPath) {
+  return new Error(
+    `AI config is invalid at ${configPath}. Fix the file to match the expected schema or delete it.`
+  );
+}
+function parseConfig(raw, configPath) {
+  try {
+    return LibrettoConfigSchema.parse(JSON.parse(raw));
+  } catch {
+    throw invalidConfigError(configPath);
+  }
+}
+function readLibrettoConfig(configPath = LIBRETTO_CONFIG_PATH) {
+  if (!existsSync(configPath)) {
+    return { version: CURRENT_CONFIG_VERSION };
+  }
+  return parseConfig(readFileSync(configPath, "utf-8"), configPath);
+}
+function writeLibrettoConfig(config, configPath = LIBRETTO_CONFIG_PATH) {
+  const parsed = LibrettoConfigSchema.parse(config);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(parsed, null, 2), "utf-8");
+  return parsed;
+}
+function readAiConfig(configPath = LIBRETTO_CONFIG_PATH) {
+  return readLibrettoConfig(configPath).ai ?? null;
+}
+function quoteShellArg(value) {
+  if (/^[a-zA-Z0-9_./:@=-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+function formatCommandPrefix(prefix) {
+  return prefix.map((arg) => quoteShellArg(arg)).join(" ");
+}
+function writeAiConfig(preset, commandPrefix, configPath = LIBRETTO_CONFIG_PATH) {
+  const librettoConfig = readLibrettoConfig(configPath);
+  const ai = AiConfigSchema.parse({
+    preset,
+    commandPrefix,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  writeLibrettoConfig(
+    {
+      ...librettoConfig,
+      version: CURRENT_CONFIG_VERSION,
+      ai
+    },
+    configPath
+  );
+  return ai;
+}
+function clearAiConfig(configPath = LIBRETTO_CONFIG_PATH) {
+  const librettoConfig = readLibrettoConfig(configPath);
+  if (!librettoConfig.ai) return false;
+  const { ai: _ai, ...rest } = librettoConfig;
+  writeLibrettoConfig(
+    {
+      ...rest
+    },
+    configPath
+  );
+  return true;
+}
+function printAiConfig(config, configPath) {
+  console.log(`AI preset: ${config.preset}`);
+  console.log(`Command prefix: ${formatCommandPrefix(config.commandPrefix)}`);
+  console.log(`Config file: ${configPath}`);
+  console.log(`Updated at: ${config.updatedAt}`);
+}
+function printConfigureUsage(commandName) {
+  console.log(
+    `Usage: ${commandName} <codex|claude|gemini> [-- <command prefix...>]
+       ${commandName}
+       ${commandName} --clear`
+  );
+}
+function runAiConfigure(input, options = {}) {
+  const configureCommandName = options.configureCommandName ?? "libretto-cli ai configure";
+  const configPath = options.configPath ?? LIBRETTO_CONFIG_PATH;
+  const presetArg = input.preset?.trim();
+  const customPrefix = (input.customPrefix ?? []).filter(Boolean);
+  if (!presetArg && customPrefix.length === 0 && !input.clear) {
+    const config2 = readAiConfig(configPath);
+    if (!config2) {
+      console.log(`No AI config set. Run '${configureCommandName} codex' to set one.`);
+      return;
+    }
+    printAiConfig(config2, configPath);
+    return;
+  }
+  if (input.clear) {
+    const removed = clearAiConfig(configPath);
+    if (removed) {
+      console.log(`Cleared AI config: ${configPath}`);
+    } else {
+      console.log("No AI config was set.");
+    }
+    return;
+  }
+  const parsedPreset = AiPresetSchema.safeParse(presetArg);
+  if (!parsedPreset.success) {
+    printConfigureUsage(configureCommandName);
+    throw new Error(
+      "Missing or invalid preset. Use one of: codex, claude, gemini."
+    );
+  }
+  if (input.customPrefix && input.customPrefix.length > 0 && customPrefix.length === 0) {
+    throw new Error("Custom command prefix cannot be empty.");
+  }
+  const preset = parsedPreset.data;
+  const commandPrefix = customPrefix.length > 0 ? customPrefix : AI_CONFIG_PRESETS[preset];
+  const config = writeAiConfig(preset, commandPrefix, configPath);
+  console.log("AI config saved.");
+  printAiConfig(config, configPath);
+}
+export {
+  AI_CONFIG_PRESETS,
+  AiConfigSchema,
+  AiPresetSchema,
+  CURRENT_CONFIG_VERSION,
+  LibrettoConfigSchema,
+  ViewportConfigSchema,
+  clearAiConfig,
+  formatCommandPrefix,
+  readAiConfig,
+  readLibrettoConfig,
+  runAiConfigure,
+  writeAiConfig,
+  writeLibrettoConfig
+};