libretto 0.5.0 → 0.5.2

package/src/cli/commands/logs.ts

@@ -12,13 +12,15 @@ import {
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   integerOption,
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
   sessionOption,
+  withRequiredSession,
 } from "./shared.js";
 
-async function resolvePageId(session: string, pageId?: string): Promise<string | undefined> {
+async function resolvePageId(
+  session: string,
+  pageId?: string,
+): Promise<string | undefined> {
   if (!pageId) return undefined;
   const pages = await withSessionLogger(session, async (logger) =>
     listOpenPages(session, logger),
@@ -48,8 +50,7 @@ export const networkCommand = SimpleCLI.command({
   description: "View captured network requests",
 })
   .input(networkInput)
-  .use(resolveSessionMiddleware)
-  .use(loadSessionStateMiddleware)
+  .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
     if (input.clear) {
       clearNetworkLog(ctx.session);
@@ -93,8 +94,7 @@ export const actionsCommand = SimpleCLI.command({
   description: "View captured actions",
 })
   .input(actionsInput)
-  .use(resolveSessionMiddleware)
-  .use(loadSessionStateMiddleware)
+  .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
     if (input.clear) {
       clearActionLog(ctx.session);

package/src/cli/commands/shared.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
+import type { LoggerApi } from "../../shared/logger/index.js";
+import { createLoggerForSession } from "../core/context.js";
 import {
-  SESSION_DEFAULT,
+  generateSessionName,
   readSessionStateOrThrow,
   type SessionState,
   validateSessionName,
@@ -10,21 +12,8 @@ import {
   type SimpleCLIMiddleware,
 } from "../framework/simple-cli.js";
 
-export function createSessionSchema() {
-  return z.string().default(SESSION_DEFAULT).superRefine((value, ctx) => {
-    try {
-      validateSessionName(value);
-    } catch (err) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: err instanceof Error ? err.message : String(err),
-      });
-    }
-  });
-}
-
-export function sessionOption(help = "Use a named session") {
-  return SimpleCLI.option(createSessionSchema(), { help });
+export function sessionOption(help = "Session name") {
+  return SimpleCLI.option(z.string().optional(), { help });
 }
 
 export function pageOption(help = "Target a specific page id") {
@@ -35,36 +24,46 @@ export function integerOption(help?: string) {
   return SimpleCLI.option(z.coerce.number().int().optional(), { help });
 }
 
-export type SessionInput = {
-  session: string;
-};
-
 export type SessionContext = {
   session: string;
+  logger: LoggerApi;
 };
 
 export type SessionStateContext = SessionContext & {
   sessionState: SessionState;
 };
 
-export const resolveSessionMiddleware: SimpleCLIMiddleware<
-  SessionInput,
+export function withRequiredSession(): SimpleCLIMiddleware<
+  { session?: string },
   {},
-  SessionContext
-> = async ({ input, ctx }) => {
-  return {
-    ...ctx,
-    session: input.session,
+  SessionStateContext
+> {
+  return async ({ input, ctx }) => {
+    if (!input.session) {
+      throw new Error("Missing required option --session.");
+    }
+    validateSessionName(input.session);
+    const logger = createLoggerForSession(input.session);
+    return {
+      ...ctx,
+      session: input.session,
+      logger,
+      sessionState: readSessionStateOrThrow(input.session),
+    };
   };
-};
+}
 
-export const loadSessionStateMiddleware: SimpleCLIMiddleware<
-  SessionInput,
-  SessionContext,
-  SessionStateContext
-> = async ({ ctx }) => {
-  return {
-    ...ctx,
-    sessionState: readSessionStateOrThrow(ctx.session),
+export function withAutoSession(): SimpleCLIMiddleware<
+  { session?: string },
+  {},
+  SessionContext
+> {
+  return async ({ input, ctx }) => {
+    const session = input.session ?? generateSessionName();
+    if (input.session) {
+      validateSessionName(input.session);
+    }
+    const logger = createLoggerForSession(session);
+    return { ...ctx, session, logger };
   };
-};
+}

package/src/cli/commands/snapshot.ts

@@ -10,17 +10,11 @@ import {
   type ScreenshotPair,
 } from "../core/snapshot-analyzer.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
-import {
-  loadSessionStateMiddleware,
-  pageOption,
-  resolveSessionMiddleware,
-  sessionOption,
-} from "./shared.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";
 
-const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 } as const;
 
 function generateSnapshotRunId(): string {
@@ -38,28 +32,28 @@ function isZeroViewport(value: number | null): boolean {
   return typeof value === "number" && value <= 0;
 }
 
-function shouldForceSnapshotViewport(metrics: SnapshotViewportMetrics): boolean {
+function shouldForceSnapshotViewport(
+  metrics: SnapshotViewportMetrics,
+): boolean {
   return (
-    isZeroViewport(metrics.configuredWidth)
-    || isZeroViewport(metrics.configuredHeight)
-    || isZeroViewport(metrics.innerWidth)
-    || isZeroViewport(metrics.innerHeight)
+    isZeroViewport(metrics.configuredWidth) ||
+    isZeroViewport(metrics.configuredHeight) ||
+    isZeroViewport(metrics.innerWidth) ||
+    isZeroViewport(metrics.innerHeight)
   );
 }
 
 function isZeroWidthScreenshotError(error: unknown): boolean {
   return (
-    error instanceof Error
-    && error.message.includes("Cannot take screenshot with 0 width")
+    error instanceof Error &&
+    error.message.includes("Cannot take screenshot with 0 width")
   );
 }
 
-async function readSnapshotViewportMetrics(
-  page: {
-    viewportSize(): { width: number; height: number } | null;
-    evaluate<T>(pageFunction: () => T | Promise<T>): Promise<T>;
-  },
-): Promise<SnapshotViewportMetrics> {
+async function readSnapshotViewportMetrics(page: {
+  viewportSize(): { width: number; height: number } | null;
+  evaluate<T>(pageFunction: () => T | Promise<T>): Promise<T>;
+}): Promise<SnapshotViewportMetrics> {
   const configuredViewport = page.viewportSize();
   let innerWidth: number | null = null;
   let innerHeight: number | null = null;
@@ -161,6 +155,12 @@ async function captureScreenshot(
     const htmlPath = `${snapshotRunDir}/page.html`;
     const condensedHtmlPath = `${snapshotRunDir}/page.condensed.html`;
 
+    const RENDER_SETTLE_TIMEOUT_MS = 10_000;
+    await Promise.race([
+      page.waitForLoadState("networkidle").catch(() => {}),
+      new Promise((resolve) => setTimeout(resolve, RENDER_SETTLE_TIMEOUT_MS)),
+    ]);
+
     const restoreViewport = resolveSnapshotViewport(session, logger);
     const viewportMetrics = await readSnapshotViewportMetrics(page);
     logger.info("screenshot-viewport-metrics", {
@@ -249,22 +249,15 @@ async function captureScreenshot(
 async function runSnapshot(
   session: string,
   logger: LoggerApi,
-  pageId?: string,
-  objective?: string,
-  context?: string,
+  pageId: string | undefined,
+  objective: string,
+  context: string,
 ): Promise<void> {
-  const normalizedObjective = objective?.trim();
-  const normalizedContext = context?.trim();
-  if (!normalizedObjective && normalizedContext) {
-    throw new Error(
-      "Couldn't run analysis: --objective is required when providing --context.",
-    );
-  }
+  const normalizedObjective = objective.trim();
+  const normalizedContext = context.trim();
 
-  const configuredAi = normalizedObjective ? readAiConfig() : null;
-  if (normalizedObjective) {
-    resolveSnapshotApiModelOrThrow(configuredAi);
-  }
+  const configuredAi = readAiConfig();
+  resolveSnapshotApiModelOrThrow(configuredAi);
 
   const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
     session,
@@ -277,15 +270,10 @@ async function runSnapshot(
   console.log(`  HTML:            ${htmlPath}`);
   console.log(`  Condensed HTML:  ${condensedHtmlPath}`);
 
-  if (!normalizedObjective) {
-    console.log("Use --objective flag to analyze snapshots.");
-    return;
-  }
-
   const interpretArgs: InterpretArgs = {
     objective: normalizedObjective,
     session,
-    context: normalizedContext ?? DEFAULT_SNAPSHOT_CONTEXT,
+    context: normalizedContext,
     pngPath,
     htmlPath,
     condensedHtmlPath,
@@ -303,25 +291,22 @@ export const snapshotInput = SimpleCLI.input({
   named: {
     session: sessionOption(),
     page: pageOption(),
-    objective: SimpleCLI.option(z.string().optional()),
-    context: SimpleCLI.option(z.string().optional()),
+    objective: SimpleCLI.option(z.string()),
+    context: SimpleCLI.option(z.string()),
   },
 });
 
-export function createSnapshotCommand(logger: LoggerApi) {
-  return SimpleCLI.command({
-    description: "Capture PNG + HTML; analyze when --objective is provided (--context optional)",
-  })
-    .input(snapshotInput)
-    .use(resolveSessionMiddleware)
-    .use(loadSessionStateMiddleware)
-    .handle(async ({ input, ctx }) => {
-      await runSnapshot(
-        ctx.session,
-        logger,
-        input.page,
-        input.objective,
-        input.context,
-      );
-    });
-}
+export const snapshotCommand = SimpleCLI.command({
+  description: "Capture PNG + HTML and analyze with --objective and --context",
+})
+  .input(snapshotInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    await runSnapshot(
+      ctx.session,
+      ctx.logger,
+      input.page,
+      input.objective,
+      input.context,
+    );
+  });

package/src/cli/core/ai-config.ts

@@ -29,11 +29,18 @@ export const ViewportConfigSchema = z.object({
 });
 export type ViewportConfig = z.infer<typeof ViewportConfigSchema>;
 
+export const WindowPositionConfigSchema = z.object({
+  x: z.number().int(),
+  y: z.number().int(),
+});
+export type WindowPositionConfig = z.infer<typeof WindowPositionConfigSchema>;
+
 export const LibrettoConfigSchema = z
   .object({
     version: z.literal(CURRENT_CONFIG_VERSION),
     ai: AiConfigSchema.optional(),
     viewport: ViewportConfigSchema.optional(),
+    windowPosition: WindowPositionConfigSchema.optional(),
   })
   .passthrough();
 export type LibrettoConfig = z.infer<typeof LibrettoConfigSchema>;
@@ -51,7 +58,12 @@ const PROVIDER_ALIASES: Record<string, string> = {
   google: DEFAULT_MODELS.gemini,
 };
 
-const CONFIGURE_PROVIDERS = ["openai", "anthropic", "gemini", "vertex"] as const;
+const CONFIGURE_PROVIDERS = [
+  "openai",
+  "anthropic",
+  "gemini",
+  "vertex",
+] as const;
 
 function formatConfigureProviders(separator = " | "): string {
   return CONFIGURE_PROVIDERS.join(separator);
@@ -75,6 +87,10 @@ function formatExpectedConfigExample(): string {
         width: 1280,
         height: 800,
       },
+      windowPosition: {
+        x: 1600,
+        y: 120,
+      },
     },
     null,
     2,
@@ -89,11 +105,13 @@ function invalidConfigError(configPath: string, detail?: string): Error {
       "Expected config example:",
       formatExpectedConfigExample(),
       "Notes:",
-      '  - "ai" and "viewport" are optional.',
+      '  - "ai", "viewport", and "windowPosition" are optional.',
       '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
       "Fix the file to match this shape, or delete it and rerun:",
       `  npx libretto ai configure ${formatConfigureProviders()}`,
-    ].filter(Boolean).join("\n"),
+    ]
+      .filter(Boolean)
+      .join("\n"),
   );
 }
 
@@ -220,7 +238,9 @@ export function runAiConfigure(
       console.log(
         `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`,
       );
-      console.log("Provider credentials still come from your shell or .env file.");
+      console.log(
+        "Provider credentials still come from your shell or .env file.",
+      );
       return;
     }
     printAiConfig(config, configPath);

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

@@ -10,7 +10,6 @@ import { readFileSync } from "node:fs";
 import type { LoggerApi } from "../../shared/logger/index.js";
 import { createLLMClient } from "../../shared/llm/client.js";
 import {
-  formatInterpretationOutput,
   InterpretResultSchema,
   buildInlinePromptSelection,
   getMimeType,
@@ -19,9 +18,7 @@ import {
   type InterpretArgs,
 } from "./snapshot-analyzer.js";
 import { readAiConfig, type AiConfig } from "./ai-config.js";
-import {
-  resolveSnapshotApiModelOrThrow,
-} from "./snapshot-api-config.js";
+import { resolveSnapshotApiModelOrThrow } from "./snapshot-api-config.js";
 
 export async function runApiInterpret(
   args: InterpretArgs,
@@ -52,7 +49,8 @@ export async function runApiInterpret(
   logger.info("api-interpret-dom-selection", {
     configuredModel: promptSelection.stats.configuredModel,
     fullDomEstimatedTokens: promptSelection.stats.fullDomEstimatedTokens,
-    condensedDomEstimatedTokens: promptSelection.stats.condensedDomEstimatedTokens,
+    condensedDomEstimatedTokens:
+      promptSelection.stats.condensedDomEstimatedTokens,
     contextWindowTokens: promptSelection.budget.contextWindowTokens,
     promptBudgetTokens: promptSelection.budget.promptBudgetTokens,
     selectedDom: promptSelection.domSource,
@@ -93,5 +91,18 @@ export async function runApiInterpret(
     answer: parsed.answer.slice(0, 200),
   });
 
-  console.log(formatInterpretationOutput(parsed, "Interpretation (via API):"));
+  console.log("");
+  console.log("Analysis:");
+  console.log(parsed.answer);
+  if (parsed.selectors.length > 0) {
+    console.log("");
+    console.log("Selectors:");
+    parsed.selectors.forEach((selector, index) => {
+      console.log(`  ${index + 1}. ${selector.label}: ${selector.selector}`);
+    });
+  }
+  if (parsed.notes?.trim()) {
+    console.log("");
+    console.log(`Notes: ${parsed.notes.trim()}`);
+  }
 }