libretto 0.5.3-experimental.5 → 0.5.3

package/src/cli/commands/init.ts

@@ -1,5 +1,13 @@
 import { createInterface } from "node:readline";
-import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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";
@@ -9,8 +17,8 @@ import {
   loadSnapshotEnv,
   resolveSnapshotApiModel,
 } from "../core/snapshot-api-config.js";
-import { SimpleCLI } from "../framework/simple-cli.js";
 import { hasProviderCredentials } from "../../shared/llm/client.js";
+import { SimpleCLI } from "../framework/simple-cli.js";
 
 type ProviderChoice = {
   key: string;
@@ -42,7 +50,8 @@ const PROVIDER_CHOICES: ProviderChoice[] = [
     key: "4",
     label: "Google Vertex AI",
     envVar: "GOOGLE_CLOUD_PROJECT",
-    envHint: "Requires gcloud auth application-default login and a GCP project ID",
+    envHint:
+      "Requires gcloud auth application-default login and a GCP project ID",
   },
 ];
 
@@ -57,16 +66,6 @@ function promptUser(
   });
 }
 
-function askYesNo(question: string): Promise<boolean> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(`${question} (y/N) `, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase() === "y");
-    });
-  });
-}
-
 function safeReadAiConfig(): ReturnType<typeof readAiConfig> {
   try {
     return readAiConfig();
@@ -101,7 +100,9 @@ function printSnapshotApiStatus(): void {
 
   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(
+      "    Snapshot objectives will use the API analyzer by default.",
+    );
     console.log("    No further action required.");
     return;
   }
@@ -117,7 +118,9 @@ function printSnapshotApiStatus(): void {
   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.");
+  console.log(
+    "    Run `npx libretto init` interactively to set up credentials.",
+  );
 }
 
 async function runInteractiveApiSetup(): Promise<void> {
@@ -132,7 +135,9 @@ async function runInteractiveApiSetup(): Promise<void> {
 
   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(
+      "    Snapshot objectives will use the API analyzer by default.",
+    );
     return;
   }
 
@@ -144,7 +149,9 @@ async function runInteractiveApiSetup(): Promise<void> {
   });
 
   try {
-    console.log("  Which API provider would you like to use for snapshot analysis?\n");
+    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}`);
     }
@@ -153,7 +160,9 @@ async function runInteractiveApiSetup(): Promise<void> {
     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(
+        "\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=...");
@@ -251,26 +260,17 @@ function detectAgentDirs(root: string): string[] {
   return dirs;
 }
 
-async function copySkills(): Promise<void> {
+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.");
+    console.log(
+      "\nSkills: No .agents/ or .claude/ directory found in repo root — skipping.",
+    );
     return;
   }
 
   const destinations = agentDirs.map((d) => join(d, "skills", "libretto"));
-  const dirNames = agentDirs.map((d) => basename(d)).join(" and ");
-  // Say "Overwrite" if skills already exist in ANY target dir — skills must
-  // be identical across coding agents, so we always copy to all of them.
-  const existing = destinations.filter((d) => existsSync(d));
-  const verb = existing.length > 0 ? "Overwrite" : "Install";
-
-  const proceed = await askYesNo(`\n${verb} libretto skills in ${dirNames}?`);
-  if (!proceed) {
-    console.log("  Skipping skill copy.");
-    return;
-  }
 
   let sourceDir: string;
   try {
@@ -289,7 +289,9 @@ async function copySkills(): Promise<void> {
     }
     cpSync(sourceDir, skillDest, { recursive: true });
     const fileCount = readdirSync(skillDest).length;
-    console.log(`  ✓ Copied ${fileCount} skill files to ${name}/skills/libretto/`);
+    console.log(
+      `  ✓ Copied ${fileCount} skill files to ${name}/skills/libretto/`,
+    );
   }
 }
 
@@ -316,10 +318,12 @@ export const initCommand = SimpleCLI.command({
       console.log("\nSkipping browser installation (--skip-browsers)");
     }
 
+    copySkills();
+
     if (process.stdin.isTTY) {
-      await copySkills();
       await runInteractiveApiSetup();
     } else {
+      loadSnapshotEnv();
       printSnapshotApiStatus();
     }
 

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()}`);
+  }
 }