@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/cli/desktop-pane-shot.ts

@@ -1,9 +1,10 @@
-import { logFailure } from "../utils/log-failure";
 import type { ScannerCapture } from "../plugins/builtin/shared/scanner-capture";
 import type { TapeCapture } from "../plugins/builtin/time-sales/snapshot-client";
-import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
+import { mkdtemp, rm } from "fs/promises";
+import { randomBytes, timingSafeEqual } from "crypto";
 import { tmpdir } from "os";
 import { join } from "path";
+import { writeOutputFile } from "./output-file";
 import { encodeRpcValue } from "../renderers/electrobun/shared/rpc-codec";
 import type { AppConfig } from "../types/config";
 import type { ChartResolutionResult } from "../time-series/types";
@@ -21,11 +22,20 @@ import type { HttpProxyRequestEnvelope, HttpProxyResponseEnvelope } from "../uti
 import type { PaneAccessGate } from "./pane-functions/access-gate";
 import { readVisibleKeyValues } from "./visible-key-values";
 import { scrollTruncationReasons } from "./scroll-truncation";
-import { SHOT_API_PROXY_PREFIX, SHOT_HTTP_BRIDGE_PATH, SHOT_MARKET_BRIDGE_PATH } from "./desktop-pane-shot-routes";
+import {
+  SHOT_API_PROXY_PREFIX,
+  SHOT_API_SOCKET_PATH,
+  SHOT_HTTP_BRIDGE_PATH,
+  SHOT_MARKET_BRIDGE_PATH,
+  type ShotApiSocketCall,
+  type ShotApiSocketReply,
+} from "./desktop-pane-shot-routes";
 import { SESSION_COOKIE_NAMES } from "../api-client/session-cookie";
+import { isShotApiRequestAllowed, isShotSessionPath } from "./desktop-pane-shot-api-policy";
 import { renderElectrobunViewHtml } from "../renderers/dom/build-assets";
 import { loadShotView, SHOT_VIEW_SCRIPT, SHOT_VIEW_STYLESHEET, type ShotViewFiles } from "./desktop-pane-shot-view";
 import { errorMessage } from "../utils/errors";
+import { findChromeExecutable, launchShotBrowser, type CdpPage } from "./desktop-pane-shot-browser";
 
 export interface DesktopPaneShotIntradayHistory {
   target?: InstrumentRef;
@@ -172,7 +182,8 @@ export interface DesktopPaneShotRenderResult {
 
 /**
  * The status line variants for a capture, longest first, worked out from what
- * the pane rendered; null leaves the footer row empty. `dates` says what the
+ * the pane rendered; null gives the footer row back to the pane, for a capture
+ * with nothing loaded to date (a wall, an empty state). `dates` says what the
  * line dates (`CaptureStatusLine`): the pane's own data, whose `as of` text is
  * then left out rather than repeat the date, or the quotes on screen.
  */
@@ -182,17 +193,6 @@ interface ShotStatusLineVariants {
 }
 type ShotStatusLine = (rendered: DesktopPaneShotRenderResult) => ShotStatusLineVariants | null | Promise<ShotStatusLineVariants | null>;
 
-type CdpResponse = {
-  id?: number;
-  result?: unknown;
-  error?: { message?: string; data?: string };
-};
-
-type PendingCdpCall = {
-  resolve: (value: unknown) => void;
-  reject: (error: Error) => void;
-};
-
 const SHOT_MODE_CSS = [
   "[data-gloom-role='composite-chart-toolbar']",
   "[data-gloom-role='chart-series-quick-add']",
@@ -209,10 +209,7 @@ const SHOT_MODE_CSS = [
   + " line-height: var(--cell-h); font-size: 12px; letter-spacing: 0.02em; color: var(--gloom-text-dim, #888);"
   + " pointer-events: none; z-index: 1000; }";
 
-// Chrome gets 30 s (300 polls x 100 ms) to open its DevTools port: 8 s was not enough on a busy machine.
-const CHROME_POLL_ATTEMPTS = 300;
 const SHOT_READY_TIMEOUT_MS = 45_000;
-const CDP_CALL_TIMEOUT_MS = 10_000;
 const DEFAULT_DEVICE_SCALE_FACTOR = 2;
 
 export async function renderDesktopPaneScreenshot(
@@ -224,12 +221,12 @@ export async function renderDesktopPaneScreenshot(
   const chrome = await findChromeExecutable();
   const view = await loadShotView();
   const tempDir = await mkdtemp(join(tmpdir(), "gloom-pane-shot-"));
-  let server: ReturnType<typeof Bun.serve> | null = null;
+  let server: ShotServer | null = null;
   try {
     server = serveShotPage(view, shotPageHtml(view, payload), apiProxy, options.bridge ?? null);
     return await capturePageScreenshot({
       chrome,
-      url: new URL("/", server.url).href,
+      url: server.url,
       outputPath,
       widthPx: payload.widthPx,
       heightPx: payload.heightPx,
@@ -246,7 +243,7 @@ export async function renderDesktopPaneScreenshot(
       } : {}),
     });
   } finally {
-    server?.stop(true);
+    server?.stop();
     await rm(tempDir, { recursive: true, force: true });
   }
 }
@@ -287,30 +284,107 @@ function shotPageHtml(view: ShotViewFiles, payload: DesktopPaneShotPayload): str
   });
 }
 
-function serveShotPage(
+/** A capture's page server: `url` is the page Chrome opens, the only way in. */
+export interface ShotServer {
+  url: string;
+  stop(): void;
+}
+
+/**
+ * The route a request to the shot server asks for, or null when it is not
+ * the capture's own page asking. Any program on this machine and any website
+ * open in the user's browser can reach the port, and behind it are the
+ * capture's data, reads made with the user's session and fetches made from
+ * this machine. So every request must name the server as `127.0.0.1:<port>`
+ * (a website that rebinds its own name to this address sends its own name),
+ * come from no other origin, and start its path with the secret folder the
+ * page was opened at, which nothing but Chrome is given.
+ */
+function shotRequestRoute(request: Request, port: number | undefined, secret: string): URL | null {
+  if (port === undefined) return null;
+  const origin = `http://127.0.0.1:${port}`;
+  if (request.headers.get("host") !== `127.0.0.1:${port}`) return null;
+  const sentFrom = request.headers.get("origin");
+  if (sentFrom !== null && sentFrom !== origin) return null;
+  const url = new URL(request.url);
+  const folder = `/${secret}/`;
+  const given = Buffer.from(url.pathname.slice(0, folder.length));
+  const expected = Buffer.from(folder);
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
+  const route = new URL(url);
+  route.pathname = url.pathname.slice(folder.length - 1);
+  return route;
+}
+
+/**
+ * Serves one capture's page under a secret folder made for this run (see
+ * `shotRequestRoute`). The page reaches its API proxy, socket and bridges by
+ * paths relative to that folder.
+ */
+export function serveShotPage(
   view: ShotViewFiles,
   html: string,
   apiProxy: DesktopPaneShotApiProxy,
   bridge: DesktopPaneShotBridge | null,
-): ReturnType<typeof Bun.serve> {
-  return Bun.serve({
+): ShotServer {
+  const secret = randomBytes(32).toString("hex");
+  const server = Bun.serve({
     hostname: "127.0.0.1",
     port: 0,
     idleTimeout: 60,
-    fetch(request) {
-      const url = new URL(request.url);
+    fetch(request, server) {
+      const url = shotRequestRoute(request, server.port, secret);
+      if (!url) return new Response("Forbidden", { status: 403 });
+      if (url.pathname === SHOT_API_SOCKET_PATH) {
+        // A browser always sends a socket's origin; only the page's own gets here.
+        if (request.headers.get("origin") === null) return new Response("Forbidden", { status: 403 });
+        return server.upgrade(request, { data: undefined }) ? undefined : new Response("Expected a WebSocket upgrade", { status: 426 });
+      }
       if (url.pathname.startsWith(`${SHOT_API_PROXY_PREFIX}/`)) {
         return proxyShotApiRequest(request, url, apiProxy);
       }
-      if (url.pathname === SHOT_MARKET_BRIDGE_PATH) {
-        return runShotMarketBridge(request, bridge);
-      }
-      if (url.pathname === SHOT_HTTP_BRIDGE_PATH) {
-        return runShotHttpBridge(request, bridge);
+      if (url.pathname === SHOT_MARKET_BRIDGE_PATH || url.pathname === SHOT_HTTP_BRIDGE_PATH) {
+        if (request.method !== "POST") return new Response("Method not allowed", { status: 405 });
+        return url.pathname === SHOT_MARKET_BRIDGE_PATH ? runShotMarketBridge(request, bridge) : runShotHttpBridge(request, bridge);
       }
+      if (request.method !== "GET" && request.method !== "HEAD") return new Response("Method not allowed", { status: 405 });
       return serveShotAsset(url, view, html);
     },
+    websocket: {
+      message(socket, message) {
+        void answerShotApiCall(String(message), apiProxy).then((reply) => socket.send(reply));
+      },
+    },
   });
+  return {
+    url: `http://127.0.0.1:${server.port}/${secret}/`,
+    stop: () => server.stop(true),
+  };
+}
+
+/**
+ * One read the page sent over its API socket (`SHOT_API_SOCKET_PATH`), made
+ * as the proxy makes it, with the session the page never holds: the reply's
+ * JSON, its body in base64. A call that is not an API path answers why.
+ */
+export async function answerShotApiCall(message: string, apiProxy: DesktopPaneShotApiProxy): Promise<string> {
+  let id = 0;
+  try {
+    const call = JSON.parse(message) as Partial<ShotApiSocketCall>;
+    id = typeof call.id === "number" ? call.id : 0;
+    if (typeof call.path !== "string" || !call.path.startsWith("/") || call.path.startsWith("//")) throw new Error("Not an API path.");
+    const url = new URL(`${SHOT_API_PROXY_PREFIX}${call.path}`, "http://127.0.0.1");
+    const sent = new Headers(Array.isArray(call.headers) ? call.headers : []);
+    const response = await proxyShotApiRequest(new Request(url, { headers: sent }), url, apiProxy);
+    const body = Buffer.from(await response.arrayBuffer()).toString("base64");
+    const headers: Array<[string, string]> = [];
+    response.headers.forEach((value, name) => headers.push([name, value]));
+    const reply: ShotApiSocketReply = { id, status: response.status, statusText: response.statusText, headers, body };
+    return JSON.stringify(reply);
+  } catch (error) {
+    const reply: ShotApiSocketReply = { id, error: errorMessage(error) };
+    return JSON.stringify(reply);
+  }
 }
 
 async function runShotMarketBridge(
@@ -361,43 +435,49 @@ function serveShotAsset(url: URL, view: ShotViewFiles, html: string): Response {
   return new Response(body, { headers: { "Content-Type": `${type}; charset=utf-8` } });
 }
 
+/**
+ * The request headers the proxy passes on: what the page accepts and sends, a
+ * cached copy's validators and the client's feature list. Everything else is
+ * the proxy's to set (the session cookie, the API's origin) or nobody's: a
+ * client address, a method override, a key.
+ */
+const SHOT_API_REQUEST_HEADERS = ["accept", "accept-language", "content-type", "if-modified-since", "if-none-match", "x-gloom-features"];
+/** Response headers that belong to the API's own origin, not the page's. */
+const SHOT_API_DROPPED_RESPONSE_HEADERS = [
+  "access-control-allow-credentials",
+  "access-control-allow-origin",
+  "content-encoding",
+  "content-length",
+  "set-cookie",
+  "transfer-encoding",
+];
+const SHOT_API_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const SHOT_API_MAX_REDIRECTS = 5;
+
+function shotApiError(message: string, status: number): Response {
+  return Response.json({ error: message }, { status, headers: { "Cache-Control": "no-store" } });
+}
+
+/**
+ * Sends one of the page's API requests with the user's session, if the page
+ * may send it (`isShotApiRequestAllowed`). A redirect is followed only within
+ * the API, to a path the page may ask for too.
+ */
 async function proxyShotApiRequest(
   request: Request,
   requestUrl: URL,
   apiProxy: DesktopPaneShotApiProxy,
 ): Promise<Response> {
   const baseUrl = new URL(apiProxy.baseUrl);
-  const proxiedPath = requestUrl.pathname.slice(SHOT_API_PROXY_PREFIX.length) || "/";
-  const target = new URL(baseUrl);
   const basePath = baseUrl.pathname.replace(/\/+$/, "");
-  target.pathname = `${basePath}${proxiedPath.startsWith("/") ? proxiedPath : `/${proxiedPath}`}`;
-  target.search = requestUrl.search;
-  target.hash = "";
-  const headers = new Headers(request.headers);
-  for (const name of [
-    "authorization",
-    "connection",
-    "content-length",
-    "cookie",
-    "host",
-    "origin",
-    "proxy-authorization",
-    "referer",
-    "te",
-    "trailer",
-    "transfer-encoding",
-    "upgrade",
-    "x-forwarded-for",
-    "x-forwarded-host",
-    "x-forwarded-proto",
-  ]) {
-    headers.delete(name);
+  let path = requestUrl.pathname.slice(SHOT_API_PROXY_PREFIX.length) || "/";
+  let method = request.method.toUpperCase();
+  if (!isShotApiRequestAllowed(method, path)) return shotApiError("The pane screenshot does not send this request.", 403);
+  const headers = new Headers();
+  for (const name of SHOT_API_REQUEST_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
   }
-  const browserOwnedHeaders: string[] = [];
-  headers.forEach((_value, name) => {
-    if (name.startsWith("sec-") || name === "accept-encoding") browserOwnedHeaders.push(name);
-  });
-  for (const name of browserOwnedHeaders) headers.delete(name);
   headers.set("Origin", baseUrl.origin);
   if (apiProxy.sessionToken) {
     headers.set(
@@ -405,57 +485,60 @@ async function proxyShotApiRequest(
       SESSION_COOKIE_NAMES.map((name) => `${name}=${apiProxy.sessionToken}`).join("; "),
     );
   }
+  let target = new URL(baseUrl);
+  target.pathname = `${basePath}${path}`;
+  target.search = requestUrl.search;
+  target.hash = "";
 
   try {
-    const response = await fetch(target, {
-      method: request.method,
-      headers,
-      body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
-      redirect: "follow",
-    });
-    const responseHeaders = new Headers(response.headers);
-    for (const name of [
-      "access-control-allow-credentials",
-      "access-control-allow-origin",
-      "content-encoding",
-      "content-length",
-      "set-cookie",
-      "transfer-encoding",
-    ]) {
-      responseHeaders.delete(name);
+    let body = method === "GET" || method === "HEAD" ? undefined : new Uint8Array(await request.arrayBuffer());
+    for (let followed = 0; ; followed += 1) {
+      const response = await fetch(target, { method, headers, body, redirect: "manual" });
+      const location = SHOT_API_REDIRECT_STATUSES.has(response.status) ? response.headers.get("location") : null;
+      if (location === null) return await shotApiResponse(response, path);
+      await response.body?.cancel().catch(() => { /* Intentional ignore: a redirect's own body is never read, only dropped. */ });
+      if (followed >= SHOT_API_MAX_REDIRECTS) return shotApiError("Cloud API redirected too many times.", 502);
+      const next = new URL(location, target);
+      if (
+        (response.status === 303 && method !== "GET" && method !== "HEAD")
+        || ((response.status === 301 || response.status === 302) && method === "POST")
+      ) {
+        method = "GET";
+        body = undefined;
+        headers.delete("content-type");
+      }
+      const inApi = next.origin === baseUrl.origin && (next.pathname === basePath || next.pathname.startsWith(`${basePath}/`));
+      path = next.pathname.slice(basePath.length) || "/";
+      if (!inApi || !isShotApiRequestAllowed(method, path)) return shotApiError("Cloud API redirected the request elsewhere.", 502);
+      target = next;
     }
-    responseHeaders.set("Cache-Control", "no-store");
-    return new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers: responseHeaders,
-    });
   } catch {
-    return Response.json({ error: "Cloud API request failed." }, { status: 502 });
+    // Intentional ignore: the page is told the read failed, as a dropped connection tells fetch.
+    return shotApiError("Cloud API request failed.", 502);
   }
 }
 
-async function findChromeExecutable(): Promise<string> {
-  const candidates = [
-    process.env.CHROME_PATH,
-    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-    "/Applications/Chromium.app/Contents/MacOS/Chromium",
-    Bun.which("google-chrome"),
-    Bun.which("google-chrome-stable"),
-    Bun.which("chromium"),
-    Bun.which("chromium-browser"),
-    // Windows installs Chrome outside PATH, per machine or per user.
-    ...["PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA"].map((name) => {
-      const dir = process.env[name];
-      return dir ? join(dir, "Google", "Chrome", "Application", "chrome.exe") : null;
-    }),
-  ].filter((value): value is string => !!value);
-
-  for (const candidate of candidates) {
-    const file = Bun.file(candidate);
-    if (await file.exists()) return candidate;
+/**
+ * The API's answer as the page gets it: without the API origin's headers, and
+ * for the session read only its user, since the session's token rides along
+ * in that answer and the page never holds the session.
+ */
+async function shotApiResponse(response: Response, path: string): Promise<Response> {
+  const headers = new Headers(response.headers);
+  for (const name of SHOT_API_DROPPED_RESPONSE_HEADERS) headers.delete(name);
+  headers.set("Cache-Control", "no-store");
+  if (!isShotSessionPath(path)) {
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
   }
-  throw new Error("Drawing a pane needs Google Chrome or Chromium, and neither was found. Install one, or set CHROME_PATH to its executable.");
+  let user: unknown = null;
+  try {
+    const answer = await response.json() as { user?: unknown } | null;
+    user = answer?.user ?? null;
+  } catch {
+    // Intentional ignore: an answer that is not JSON names no user, which reads as signed out.
+  }
+  headers.set("Content-Type", "application/json");
+  return new Response(JSON.stringify({ user }), { status: response.status, statusText: response.statusText, headers });
 }
 
 async function capturePageScreenshot({
@@ -481,39 +564,9 @@ async function capturePageScreenshot({
   statusLine?: ShotStatusLine;
   fitRows?: { heightCells: number; maxHeightCells: number; roles: readonly string[] };
 }): Promise<DesktopPaneShotRenderResult> {
-  await mkdir(userDataDir, { recursive: true });
-  const port = 43000 + Math.floor(Math.random() * 10000);
-  const proc = Bun.spawn([
-    chrome,
-    "--headless=new",
-    "--disable-gpu",
-    // Software WebGL for GPU-drawn panes (the 3D volatility surface).
-    "--use-angle=swiftshader",
-    "--enable-unsafe-swiftshader",
-    "--no-sandbox",
-    "--disable-dev-shm-usage",
-    "--disable-background-networking",
-    "--disable-default-apps",
-    "--disable-extensions",
-    "--disable-popup-blocking",
-    "--hide-scrollbars",
-    "--no-first-run",
-    "--no-default-browser-check",
-    "--allow-file-access-from-files",
-    `--remote-debugging-port=${port}`,
-    `--user-data-dir=${userDataDir}`,
-    `--window-size=${widthPx},${heightPx}`,
-    url,
-  ], {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  let session: CdpSession | null = null;
+  const browser = await launchShotBrowser(chrome, { widthPx, heightPx, userDataDir });
+  const session = browser.page;
   try {
-    const wsUrl = await waitForPageWebSocket(port, url);
-    session = await CdpSession.connect(wsUrl);
-    await session.send("Page.enable");
     await session.send("Runtime.enable");
     await session.send("Emulation.setDeviceMetricsOverride", {
       width: widthPx,
@@ -524,12 +577,13 @@ async function capturePageScreenshot({
     await session.send("Emulation.setDefaultBackgroundColorOverride", {
       color: { r: 0, g: 0, b: 0, a: 0 },
     });
+    await browser.open(url);
     await waitForShotReady(session);
     if (fitRows) await growToFitRows(session, { widthPx, heightPx, deviceScaleFactor, ...fitRows });
     const rendered = await readRenderedPaneState(session);
     if (captureImage && statusLine) {
       const line = await statusLine(rendered);
-      rendered.statusLine = line?.variants.length ? await fitShotStatusLine(session, line) : null;
+      rendered.statusLine = (await fitShotStatusLine(session, line ?? { variants: [] })) || null;
     }
     if (captureImage) {
       const screenshot = await session.send("Page.captureScreenshot", {
@@ -538,16 +592,14 @@ async function capturePageScreenshot({
         captureBeyondViewport: false,
       }) as { data?: string };
       if (!screenshot.data) throw new Error("Chrome did not return screenshot data.");
-      await writeFile(outputPath, Uint8Array.from(Buffer.from(screenshot.data, "base64")));
+      await writeOutputFile(outputPath, Buffer.from(screenshot.data, "base64"));
     }
     return rendered;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(message);
   } finally {
-    session?.close();
-    proc.kill();
-    await proc.exited.catch(() => { /* Intentional ignore: The screenshot browser was killed during cleanup; preserve the capture result. */ });
+    await browser.close();
   }
 }
 
@@ -557,7 +609,7 @@ async function capturePageScreenshot({
  * taller pane to settle: a board a default capture would cut (FUT's last
  * sectors) shows every row, and a docs page its whole text.
  */
-async function growToFitRows(session: CdpSession, size: {
+async function growToFitRows(session: CdpPage, size: {
   widthPx: number;
   heightPx: number;
   deviceScaleFactor: number;
@@ -638,7 +690,7 @@ function stateMarkers(text: string, patterns: RegExp[]): string[] {
   )))];
 }
 
-async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneShotRenderResult> {
+async function readRenderedPaneState(session: CdpPage): Promise<DesktopPaneShotRenderResult> {
   const result = await session.send("Runtime.evaluate", {
     expression: `(() => {
       const root = document.getElementById("root") || document.body;
@@ -865,7 +917,7 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
 }
 
 /** Draws the first variant that fits the pane footer, and returns what it drew. */
-async function fitShotStatusLine(session: CdpSession, { variants, dates }: ShotStatusLineVariants): Promise<string | null> {
+async function fitShotStatusLine(session: CdpPage, { variants, dates }: ShotStatusLineVariants): Promise<string | null> {
   const result = await session.send("Runtime.evaluate", {
     expression: `(() => {
       const fit = window.__GLOOM_CLI_SHOT_FIT_STATUS__;
@@ -878,28 +930,7 @@ async function fitShotStatusLine(session: CdpSession, { variants, dates }: ShotS
   return typeof value === "string" ? value : null;
 }
 
-async function waitForPageWebSocket(port: number, targetUrl: string): Promise<string> {
-  for (let attempt = 0; attempt < CHROME_POLL_ATTEMPTS; attempt += 1) {
-    try {
-      const response = await fetch(`http://127.0.0.1:${port}/json/list`);
-      if (response.ok) {
-        const targets = await response.json() as Array<{ url?: string; type?: string; webSocketDebuggerUrl?: string }>;
-        const page = targets.find((target) => (
-          target.type === "page"
-          && target.webSocketDebuggerUrl
-          && (target.url === targetUrl || target.url?.startsWith("file:"))
-        ));
-        if (page?.webSocketDebuggerUrl) return page.webSocketDebuggerUrl;
-      }
-    } catch {
-      // Intentional ignore: Chrome may still be starting; the polling deadline reports failure.
-    }
-    await sleep(100);
-  }
-  throw new Error("Timed out waiting for Chrome DevTools.");
-}
-
-async function waitForShotReady(session: CdpSession): Promise<void> {
+async function waitForShotReady(session: CdpPage): Promise<void> {
   const startedAt = Date.now();
   while (Date.now() - startedAt < SHOT_READY_TIMEOUT_MS) {
     const result = await session.send("Runtime.evaluate", {
@@ -917,94 +948,3 @@ async function waitForShotReady(session: CdpSession): Promise<void> {
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-
-class CdpSession {
-  private nextId = 1;
-  private readonly pending = new Map<number, PendingCdpCall>();
-
-  private constructor(private readonly ws: WebSocket) {
-    ws.addEventListener("message", (event) => {
-      void this.handleMessage(event.data);
-    });
-    ws.addEventListener("close", () => {
-      for (const pending of this.pending.values()) {
-        pending.reject(new Error("Chrome DevTools connection closed."));
-      }
-      this.pending.clear();
-    });
-  }
-
-  static connect(url: string): Promise<CdpSession> {
-    return new Promise((resolve, reject) => {
-      const ws = new WebSocket(url);
-      ws.addEventListener("open", () => resolve(new CdpSession(ws)), { once: true });
-      ws.addEventListener("error", () => reject(new Error("Could not connect to Chrome DevTools.")), { once: true });
-    });
-  }
-
-  send(method: string, params?: Record<string, unknown>): Promise<unknown> {
-    const id = this.nextId++;
-    return new Promise((resolve, reject) => {
-      if (this.ws.readyState !== WebSocket.OPEN) {
-        reject(new Error("Chrome DevTools connection is not open."));
-        return;
-      }
-
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`Timed out waiting for Chrome DevTools method ${method}.`));
-      }, CDP_CALL_TIMEOUT_MS);
-      const settle = {
-        resolve: (value: unknown) => {
-          clearTimeout(timer);
-          resolve(value);
-        },
-        reject: (error: Error) => {
-          clearTimeout(timer);
-          reject(error);
-        },
-      };
-
-      this.pending.set(id, settle);
-      try {
-        this.ws.send(JSON.stringify({ id, method, params }));
-      } catch (error) {
-        this.pending.delete(id);
-        settle.reject(error instanceof Error ? error : new Error(String(error)));
-      }
-    });
-  }
-
-  close(): void {
-    this.ws.close();
-  }
-
-  private async handleMessage(data: unknown): Promise<void> {
-    let response: CdpResponse;
-    try {
-      response = JSON.parse(await stringifyWebSocketMessage(data)) as CdpResponse;
-    } catch (error) {
-      logFailure("cli.screenshot", "Decode screenshot browser response failed")(error);
-      return;
-    }
-    if (!response.id) return;
-    const pending = this.pending.get(response.id);
-    if (!pending) return;
-    this.pending.delete(response.id);
-    if (response.error) {
-      pending.reject(new Error([response.error.message, response.error.data].filter(Boolean).join("\n")));
-    } else {
-      pending.resolve(response.result);
-    }
-  }
-}
-
-async function stringifyWebSocketMessage(data: unknown): Promise<string> {
-  if (typeof data === "string") return data;
-  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
-  if (ArrayBuffer.isView(data)) {
-    return new TextDecoder().decode(data as Uint8Array);
-  }
-  if (typeof Blob !== "undefined" && data instanceof Blob) return data.text();
-  return String(data);
-}

package/src/cli/early-command.ts

@@ -0,0 +1,42 @@
+import { parseCliGlobalArgs } from "./options";
+import { printVersion, versionCommand } from "./commands/version";
+import { checkCliCommandOptions, foldCommandArgs } from "./command-options";
+import { describeCliCommand, renderCommandHelp } from "./help";
+import { printCliResult } from "./result";
+import { printCliError } from "./errors";
+import { setCliColorEnabledOverride, setCliPlainOverride, setCliWidthOverride } from "../utils/cli-output";
+import { foldTypedText } from "../utils/typed-text";
+
+/** Version and its help need neither a plugin registry nor application services. */
+export async function dispatchEarlyCommand(args: string[]): Promise<boolean> {
+  let parsed;
+  try {
+    parsed = parseCliGlobalArgs(args);
+  } catch {
+    // Intentional ignore: The regular dispatcher reports malformed global options.
+    return false;
+  }
+  const token = foldTypedText(parsed.args[0] ?? "").trim().toLowerCase();
+  if (token !== versionCommand.name && !versionCommand.aliases?.includes(token)) return false;
+  const options = parsed.options;
+  setCliColorEnabledOverride(options.color);
+  setCliWidthOverride(options.width ?? null);
+  if (options.plain != null) setCliPlainOverride(options.plain);
+  const commandArgs = foldCommandArgs(versionCommand, parsed.args.slice(1), parsed.literalStart - 1);
+  try {
+    if (parsed.help) {
+      if (options.format === "text") {
+        if (!options.quiet) process.stdout.write(`${renderCommandHelp(versionCommand)}\n`);
+      } else {
+        printCliResult({ data: { ...describeCliCommand(versionCommand), sections: versionCommand.help?.sections ?? [] } }, options);
+      }
+    } else {
+      checkCliCommandOptions(versionCommand, commandArgs, parsed.literalStart - 1);
+      await printVersion((result, renderOptions) => printCliResult(result, options, renderOptions, commandArgs));
+    }
+  } catch (error) {
+    printCliError(error, options, { command: versionCommand.name, args: commandArgs });
+    process.exitCode = 1;
+  }
+  return true;
+}