libretto 0.5.0 → 0.5.2

package/src/cli/core/browser.ts

@@ -1,4 +1,10 @@
-import { chromium, type Browser, type BrowserContext, type CDPSession, type Page } from "playwright";
+import {
+  chromium,
+  type Browser,
+  type BrowserContext,
+  type CDPSession,
+  type Page,
+} from "playwright";
 import { openSync, existsSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -6,6 +12,14 @@ import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { spawn } from "node:child_process";
 import type { LoggerApi } from "../../shared/logger/index.js";
+import {
+  filterSemanticClasses,
+  INTERACTIVE_ROLE_NAMES,
+  INTERACTIVE_TAG_NAMES,
+  isObfuscatedClass,
+  TEST_ATTRIBUTE_NAMES,
+  TRUSTED_ATTRIBUTE_NAMES,
+} from "../../shared/dom-semantics.js";
 import {
   getSessionActionsLogPath,
   getSessionNetworkLogPath,
@@ -66,13 +80,12 @@ export function hasProfile(domain: string): boolean {
   return existsSync(getProfilePath(domain));
 }
 
-async function tryConnectToPort(
-  port: number,
+async function tryConnectToCDP(
+  endpoint: string,
   logger: LoggerApi,
   timeoutMs: number = 5000,
 ): Promise<Browser | null> {
-  const endpoint = `http://localhost:${port}`;
-  logger.info("cdp-connect-attempt", { port, endpoint, timeoutMs });
+  logger.info("cdp-connect-attempt", { endpoint, timeoutMs });
   try {
     const connectPromise = chromium.connectOverCDP(endpoint);
     const timeoutPromise = new Promise<null>((resolve) =>
@@ -81,16 +94,15 @@ async function tryConnectToPort(
     const browser = await Promise.race([connectPromise, timeoutPromise]);
     if (browser) {
       logger.info("cdp-connect-success", {
-        port,
         endpoint,
         contexts: browser.contexts().length,
       });
     } else {
-      logger.warn("cdp-connect-timeout", { port, endpoint, timeoutMs });
+      logger.warn("cdp-connect-timeout", { endpoint, timeoutMs });
     }
     return browser;
   } catch (err) {
-    logger.error("cdp-connect-error", { error: err, port, endpoint });
+    logger.error("cdp-connect-error", { error: err, endpoint });
     return null;
   }
 }
@@ -135,10 +147,12 @@ async function resolvePageId(page: Page): Promise<string> {
   const cdpSession: CDPSession = await page.context().newCDPSession(page);
   try {
     const targetInfo = await cdpSession.send("Target.getTargetInfo");
-    const targetId = (targetInfo as { targetInfo?: { targetId?: unknown } })?.targetInfo
-      ?.targetId;
+    const targetId = (targetInfo as { targetInfo?: { targetId?: unknown } })
+      ?.targetInfo?.targetId;
     if (typeof targetId !== "string" || targetId.length === 0) {
-      throw new Error(`Could not resolve target id for page at URL "${page.url()}".`);
+      throw new Error(
+        `Could not resolve target id for page at URL "${page.url()}".`,
+      );
     }
     return targetId;
   } finally {
@@ -162,7 +176,10 @@ export async function listOpenPages(
 ): Promise<OpenPageSummary[]> {
   const { browser, page: activePage } = await connect(session, logger);
   try {
-    const pages = browser.contexts().flatMap((ctx) => ctx.pages()).filter(isOperationalPage);
+    const pages = browser
+      .contexts()
+      .flatMap((ctx) => ctx.pages())
+      .filter(isOperationalPage);
     const pageRefs = await resolvePageReferences(pages);
     return pageRefs.map(({ id, page }) => ({
       id,
@@ -190,14 +207,15 @@ export async function connect(
 }> {
   logger.info("connect", { session, timeoutMs });
   const state = readSessionStateOrThrow(session);
-  const browser = await tryConnectToPort(state.port, logger, timeoutMs);
+  const endpoint = state.cdpEndpoint ?? `http://localhost:${state.port}`;
+  const browser = await tryConnectToCDP(endpoint, logger, timeoutMs);
   if (!browser) {
     logger.error("connect-no-browser", {
       session,
-      port: state.port,
+      endpoint,
       pid: state.pid,
     });
-    if (!isPidRunning(state.pid)) {
+    if (state.pid == null || !isPidRunning(state.pid)) {
       clearSessionState(session, logger);
       throw new Error(
         `No browser running for session "${session}". Run 'libretto open <url> --session ${session}' first.`,
@@ -205,7 +223,7 @@ export async function connect(
     }
 
     throw new Error(
-      `Could not connect to the browser for session "${session}" at http://127.0.0.1:${state.port}, but the session process (pid ${state.pid}) is still running. Try the command again, or close and reopen the session if it stays stuck.`,
+      `Could not connect to the browser for session "${session}" at ${endpoint}, but the session process (pid ${state.pid}) is still running. Try the command again, or close and reopen the session if it stays stuck.`,
     );
   }
 
@@ -276,7 +294,10 @@ export async function connect(
   return { browser, context, page, pageId: pageRef.id };
 }
 
-export async function runPages(session: string, logger: LoggerApi): Promise<void> {
+export async function runPages(
+  session: string,
+  logger: LoggerApi,
+): Promise<void> {
   logger.info("pages-start", { session });
   const pageSummaries = await listOpenPages(session, logger);
 
@@ -294,7 +315,7 @@ export async function runPages(session: string, logger: LoggerApi): Promise<void
 
 const DEFAULT_VIEWPORT = { width: 1366, height: 768 } as const;
 
-function resolveViewport(
+export function resolveViewport(
   cliViewport: { width: number; height: number } | undefined,
   logger: LoggerApi,
 ): { width: number; height: number } {
@@ -304,13 +325,33 @@ function resolveViewport(
   }
   const config = readLibrettoConfig();
   if (config.viewport) {
-    logger.info("viewport-source", { source: "config", viewport: config.viewport });
+    logger.info("viewport-source", {
+      source: "config",
+      viewport: config.viewport,
+    });
     return config.viewport;
   }
-  logger.info("viewport-source", { source: "default", viewport: DEFAULT_VIEWPORT });
+  logger.info("viewport-source", {
+    source: "default",
+    viewport: DEFAULT_VIEWPORT,
+  });
   return DEFAULT_VIEWPORT;
 }
 
+function resolveWindowPosition(
+  logger: LoggerApi,
+): { x: number; y: number } | undefined {
+  const config = readLibrettoConfig();
+  if (config.windowPosition) {
+    logger.info("window-position-source", {
+      source: "config",
+      windowPosition: config.windowPosition,
+    });
+    return config.windowPosition;
+  }
+  return undefined;
+}
+
 export async function runOpen(
   rawUrl: string,
   headed: boolean,
@@ -320,7 +361,8 @@ export async function runOpen(
 ): Promise<void> {
   const url = normalizeUrl(rawUrl);
   const viewport = resolveViewport(options?.viewport, logger);
-  logger.info("open-start", { url, headed, session, viewport });
+  const windowPosition = headed ? resolveWindowPosition(logger) : undefined;
+  logger.info("open-start", { url, headed, session, viewport, windowPosition });
   assertSessionAvailableForStart(session, logger);
 
   const port = await pickFreePort();
@@ -363,6 +405,49 @@ export async function runOpen(
   const escapedActionsLogPath = actionsLogPath
     .replace(/\\/g, "\\\\")
     .replace(/'/g, "\\'");
+  const windowPositionArg = windowPosition
+    ? `, '--window-position=${windowPosition.x},${windowPosition.y}'`
+    : "";
+  const windowBoundsSetupCode = windowPosition
+    ? `
+const requestedWindowBounds = { left: ${windowPosition.x}, top: ${windowPosition.y}, windowState: 'normal' };
+const pageCdp = await context.newCDPSession(page);
+let browserCdp;
+try {
+	const targetInfo = await pageCdp.send('Target.getTargetInfo');
+	const targetId = targetInfo?.targetInfo?.targetId;
+	browserCdp = await browser.newBrowserCDPSession();
+	const windowResult = await browserCdp.send(
+		'Browser.getWindowForTarget',
+		targetId ? { targetId } : {},
+	);
+	await browserCdp.send('Browser.setWindowBounds', {
+		windowId: windowResult.windowId,
+		bounds: requestedWindowBounds,
+	});
+	await new Promise((resolve) => setTimeout(resolve, 250));
+	const actualWindow = await browserCdp.send('Browser.getWindowBounds', {
+		windowId: windowResult.windowId,
+	});
+	childLog('info', 'window-bounds-set', {
+		windowId: windowResult.windowId,
+		requestedBounds: requestedWindowBounds,
+		actualBounds: actualWindow.bounds,
+	});
+} catch (error) {
+	childLog('warn', 'window-bounds-set-failed', {
+		requestedBounds: requestedWindowBounds,
+		message: error instanceof Error ? error.message : String(error),
+		stack: error instanceof Error ? error.stack : undefined,
+	});
+} finally {
+	await pageCdp.detach().catch(() => {});
+	if (browserCdp) {
+		await browserCdp.detach().catch(() => {});
+	}
+}
+`
+    : "";
 
   const launcherCode = `
 import { chromium } from 'playwright';
@@ -375,14 +460,21 @@ const ACTIONS_LOG = '${escapedActionsLogPath}';
 mkdirSync(dirname(NETWORK_LOG), { recursive: true });
 
 // tsx/esbuild may emit __name() wrappers in Function#toString output.
-const __name = (target, value) =>
-	Object.defineProperty(target, 'name', { value, configurable: true });
+	const __name = (target, value) =>
+		Object.defineProperty(target, 'name', { value, configurable: true });
 
-${installSessionTelemetry.toString()}
+	const TEST_ATTRIBUTE_NAMES = ${JSON.stringify([...TEST_ATTRIBUTE_NAMES])};
+	const TRUSTED_ATTRIBUTE_NAMES = ${JSON.stringify([...TRUSTED_ATTRIBUTE_NAMES])};
+	const INTERACTIVE_TAG_NAMES = ${JSON.stringify([...INTERACTIVE_TAG_NAMES])};
+	const INTERACTIVE_ROLE_NAMES = ${JSON.stringify([...INTERACTIVE_ROLE_NAMES])};
+	const filterSemanticClasses = ${filterSemanticClasses.toString()};
+	const isObfuscatedClass = ${isObfuscatedClass.toString()};
 
-function logAction(entry) {
-	appendFileSync(ACTIONS_LOG, JSON.stringify(entry) + '\\n');
-}
+	${installSessionTelemetry.toString()}
+
+	function logAction(entry) {
+		appendFileSync(ACTIONS_LOG, JSON.stringify(entry) + '\\n');
+	}
 
 function logNetwork(entry) {
 	appendFileSync(NETWORK_LOG, JSON.stringify(entry) + '\\n');
@@ -404,7 +496,7 @@ function childLog(level, event, data = {}) {
 
 const browser = await chromium.launch({
 	headless: ${!headed},
-	args: ['--disable-blink-features=AutomationControlled', '--remote-debugging-port=${port}', '--remote-debugging-address=127.0.0.1', '--no-focus-on-check'],
+	args: ['--disable-blink-features=AutomationControlled', '--remote-debugging-port=${port}', '--remote-debugging-address=127.0.0.1', '--no-focus-on-check'${windowPositionArg}],
 });
 
 browser.on('disconnected', () => {
@@ -418,6 +510,7 @@ const context = await browser.newContext({
 });
 
 const page = await context.newPage();
+${windowBoundsSetupCode}
 page.setDefaultTimeout(30000);
 page.setDefaultNavigationTimeout(45000);
 
@@ -474,8 +567,10 @@ await new Promise(() => {});
   logger.info("open-child-spawned", { pid: child.pid, port, session });
 
   let childSpawnError: Error | null = null;
-  let childEarlyExit: { code: number | null; signal: NodeJS.Signals | null } | null =
-    null;
+  let childEarlyExit: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  } | null = null;
 
   child.on("error", (err) => {
     childSpawnError = err;
@@ -529,14 +624,17 @@ await new Promise(() => {});
       logger.info("open-waiting-for-cdp", { attempt: i, port, session });
     }
     if (ready) {
-      writeSessionState({
-        port,
-        pid: child.pid!,
-        session,
-        startedAt: new Date().toISOString(),
-        status: "active",
-        viewport,
-      }, logger);
+      writeSessionState(
+        {
+          port,
+          pid: child.pid!,
+          session,
+          startedAt: new Date().toISOString(),
+          status: "active",
+          viewport,
+        },
+        logger,
+      );
       logger.info("open-success", {
         url,
         mode: browserMode,
@@ -644,7 +742,10 @@ export async function runSave(
   }
 }
 
-export async function runClose(session: string, logger: LoggerApi): Promise<void> {
+export async function runClose(
+  session: string,
+  logger: LoggerApi,
+): Promise<void> {
   logger.info("close-start", { session });
   const state = readSessionState(session, logger);
   if (!state) {
@@ -655,9 +756,10 @@ export async function runClose(session: string, logger: LoggerApi): Promise<void
 
   logger.info("close-killing", { session, pid: state.pid, port: state.port });
 
-  sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
-
-  await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+  if (state.pid != null) {
+    sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
+    await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+  }
 
   clearSessionState(session, logger);
   logger.info("close-success", { session });
@@ -666,7 +768,7 @@ export async function runClose(session: string, logger: LoggerApi): Promise<void
 
 type ClosableSession = {
   session: string;
-  pid: number;
+  pid?: number;
   port: number;
 };
 
@@ -705,7 +807,9 @@ function sendSignalToProcessGroupOrPid(
   }
 }
 
-function formatSessionList(targets: ReadonlyArray<{ session: string }>): string {
+function formatSessionList(
+  targets: ReadonlyArray<{ session: string }>,
+): string {
   return targets.map((target) => `"${target.session}"`).join(", ");
 }
 
@@ -739,7 +843,7 @@ function clearStoppedSessionStates(
 ): number {
   let cleared = 0;
   for (const session of sessions) {
-    if (!isPidRunning(session.pid)) {
+    if (session.pid == null || !isPidRunning(session.pid)) {
       clearSessionState(session.session, logger);
       cleared += 1;
     }
@@ -770,12 +874,21 @@ export async function runCloseAll(
       pid: target.pid,
       port: target.port,
     });
-    sendSignalToProcessGroupOrPid(target.pid, "SIGTERM", logger, target.session);
+    if (target.pid != null) {
+      sendSignalToProcessGroupOrPid(
+        target.pid,
+        "SIGTERM",
+        logger,
+        target.session,
+      );
+    }
   }
 
   await waitForCloseSignalWindow(CLOSE_WAIT_MS);
 
-  let survivors = closable.filter((target) => isPidRunning(target.pid));
+  let survivors = closable.filter(
+    (target) => target.pid != null && isPidRunning(target.pid),
+  );
   if (survivors.length > 0 && !force) {
     const closed = clearStoppedSessionStates(closable, logger);
 
@@ -795,11 +908,20 @@ export async function runCloseAll(
         session: survivor.session,
         pid: survivor.pid,
       });
-      sendSignalToProcessGroupOrPid(survivor.pid, "SIGKILL", logger, survivor.session);
+      if (survivor.pid != null) {
+        sendSignalToProcessGroupOrPid(
+          survivor.pid,
+          "SIGKILL",
+          logger,
+          survivor.session,
+        );
+      }
       forceKilled += 1;
     }
     await waitForCloseSignalWindow(FORCE_CLOSE_WAIT_MS);
-    survivors = survivors.filter((target) => isPidRunning(target.pid));
+    survivors = survivors.filter(
+      (target) => target.pid != null && isPidRunning(target.pid),
+    );
     if (survivors.length > 0) {
       const closed = clearStoppedSessionStates(closable, logger);
       throw new Error(
@@ -824,6 +946,95 @@ export async function runCloseAll(
   }
 }
 
+export async function runConnect(
+  cdpUrl: string,
+  session: string,
+  logger: LoggerApi,
+): Promise<void> {
+  logger.info("connect-start", { cdpUrl, session });
+  assertSessionAvailableForStart(session, logger);
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(cdpUrl);
+  } catch {
+    throw new Error(
+      [
+        `Invalid CDP URL: ${cdpUrl}`,
+        ``,
+        `Expected an HTTP URL pointing to a Chrome DevTools Protocol endpoint, for example:`,
+        `  libretto connect http://127.0.0.1:9222`,
+        `  libretto connect http://remote-host:9222`,
+        `  libretto connect http://remote-host:9222/devtools/browser/<id>`,
+      ].join("\n"),
+    );
+  }
+
+  const endpoint = parsedUrl.href;
+  const port = parsedUrl.port
+    ? Number(parsedUrl.port)
+    : parsedUrl.protocol === "https:"
+      ? 443
+      : 80;
+
+  console.log(
+    `Connecting to CDP endpoint at ${endpoint} (session: ${session})...`,
+  );
+
+  // Verify the CDP endpoint is reachable
+  const versionUrl = `${parsedUrl.protocol}//${parsedUrl.host}/json/version`;
+  try {
+    const resp = await fetch(versionUrl);
+    const versionInfo = await resp.json();
+    logger.info("connect-version-ok", { versionUrl, versionInfo });
+  } catch (err) {
+    logger.error("connect-version-failed", { versionUrl, error: err });
+    throw new Error(
+      `Cannot reach CDP endpoint at ${versionUrl}. Make sure the target is running and accessible at ${parsedUrl.host}.`,
+    );
+  }
+
+  // Connect via CDP using the full endpoint URL
+  const browser = await tryConnectToCDP(endpoint, logger, 10_000);
+  if (!browser) {
+    throw new Error(
+      `CDP endpoint at ${endpoint} is reachable but Playwright could not connect. Check that the URL is a Chrome DevTools Protocol endpoint.`,
+    );
+  }
+
+  const pages = resolveOperationalPages(browser);
+  logger.info("connect-pages", {
+    session,
+    pageCount: pages.length,
+    urls: pages.map((p) => p.url()),
+  });
+
+  disconnectBrowser(browser, logger, session);
+
+  writeSessionState(
+    {
+      port,
+      cdpEndpoint: endpoint,
+      session,
+      startedAt: new Date().toISOString(),
+      status: "active",
+    },
+    logger,
+  );
+
+  logger.info("connect-success", { cdpUrl: endpoint, session, port });
+  console.log(`Connected to ${endpoint} (session: ${session})`);
+  console.log(`  Pages found: ${pages.length}`);
+  if (pages.length > 0) {
+    for (const p of pages.slice(0, 5)) {
+      console.log(`    ${p.url()}`);
+    }
+    if (pages.length > 5) {
+      console.log(`    ... and ${pages.length - 5} more`);
+    }
+  }
+}
+
 export function resolvePath(filePath: string): string {
   return join(process.cwd(), filePath);
 }

package/src/cli/core/context.ts

@@ -66,10 +66,15 @@ export function createLoggerForSession(session: string): Logger {
   const sessionDir = getSessionDir(session);
   mkdirSync(sessionDir, { recursive: true });
   const logFilePath = getSessionLogsPath(session);
-  return new Logger(["libretto"], [createFileLogSink({ filePath: logFilePath })]);
+  return new Logger(
+    ["libretto"],
+    [createFileLogSink({ filePath: logFilePath })],
+  );
 }
 
-export async function closeLogger(logger: Logger | null | undefined): Promise<void> {
+export async function closeLogger(
+  logger: Logger | null | undefined,
+): Promise<void> {
   if (!logger) return;
   await logger.close();
 }