harnery 0.31.6 → 0.32.0

package/src/lib/browser/client.ts

@@ -1,11 +1,12 @@
-import { mkdirSync } from "node:fs";
+import { chmodSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import axe from "axe-core";
 import {
   type BrowserContext,
   type ConsoleMessage,
   chromium,
+  type Locator,
   type Page,
   type Cookie as PWCookie,
   type Request,
@@ -112,6 +113,8 @@ export interface BrowserOptions {
    * defaults only.
    */
   launchArgs?: string[];
+  /** Authenticated browser proxy passed directly to Playwright. */
+  proxy?: { server: string; username?: string; password?: string };
 }
 
 export interface NavigateResult {
@@ -154,6 +157,83 @@ export interface Diagnostics {
   viewport: { width: number; height: number } | null;
 }
 
+export type BrowserSessionLocator =
+  | { kind: "selector"; value: string; partial: boolean }
+  | { kind: "role"; value: string; name?: string; partial: boolean }
+  | { kind: "label"; value: string; partial: boolean }
+  | { kind: "text"; value: string; partial: boolean };
+
+export interface BrowserSessionStatus {
+  phase: "ready";
+  active_tab: number;
+  tab_count: number;
+  revision: number;
+  navigation: BrowserSessionNavigation;
+}
+
+export type BrowserSessionNavigationType =
+  | "navigate"
+  | "reload"
+  | "back_forward"
+  | "prerender"
+  | "unknown";
+
+export interface BrowserSessionNavigation {
+  /** Monotonic count of committed documents observed in this tab. */
+  sequence: number;
+  /** UTC time when the latest document reached DOMContentLoaded. */
+  occurred_at: string | null;
+  /** URL committed by the latest observed document navigation. */
+  url: string;
+  /** Browser Navigation Timing classification for the current document. */
+  type: BrowserSessionNavigationType;
+}
+
+export interface BrowserSessionTab {
+  index: number;
+  title: string;
+  url: string;
+  active: boolean;
+  revision: number;
+  navigation: BrowserSessionNavigation;
+}
+
+export interface BrowserSessionControl {
+  kind: string;
+  name: string;
+  attributes: Record<string, string | boolean>;
+  has_value?: boolean;
+}
+
+export interface BrowserSessionInspection {
+  active_tab: number;
+  url: string;
+  title: string;
+  text: string;
+  controls: BrowserSessionControl[];
+  focus: BrowserSessionControl | null;
+  revision: number;
+  navigation: BrowserSessionNavigation;
+  truncated: boolean;
+}
+
+export interface BrowserSessionScreenshot {
+  path: string;
+  width: number;
+  height: number;
+  revision: number;
+}
+
+export class BrowserSessionActionError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "BrowserSessionActionError";
+  }
+}
+
 const DEFAULT_PROFILE = resolve(homedir(), ".cache", "harnery", "browser-profile");
 
 // Bound how many Chromium processes SPAWN at the same moment. When many Browser
@@ -162,10 +242,12 @@ const DEFAULT_PROFILE = resolve(homedir(), ".cache", "harnery", "browser-profile
 // resources and Chromium launch dies with an unhandled ENOENT that a per-call
 // retry can't catch. Serializing only the brief launch phase (never the
 // browser's lifetime, so N browsers still run concurrently) removes the burst
-// that causes it. Overridable via HARNERY_MAX_BROWSER_LAUNCHES.
+// that causes it. The default stays at one because even a three-process burst
+// can exhaust Bun/Playwright's IPC sockets under a full suite; callers with
+// more headroom can opt into a higher value via HARNERY_MAX_BROWSER_LAUNCHES.
 const MAX_CONCURRENT_LAUNCHES = Math.max(
   1,
-  Number.parseInt(process.env.HARNERY_MAX_BROWSER_LAUNCHES ?? "3", 10) || 3,
+  Number.parseInt(process.env.HARNERY_MAX_BROWSER_LAUNCHES ?? "1", 10) || 1,
 );
 let activeLaunches = 0;
 const launchWaiters: Array<() => void> = [];
@@ -191,6 +273,12 @@ function releaseLaunchSlot(): void {
 export class Browser {
   private context: BrowserContext | null = null;
   private page: Page | null = null;
+  private pageIndexes = new Map<Page, number>();
+  private pageRecency = new Map<Page, number>();
+  private pageNavigations = new Map<Page, BrowserSessionNavigation>();
+  private nextPageIndex = 0;
+  private recencyClock = 0;
+  private sessionRevision = 0;
   readonly profileDir: string;
   private consoleEvents: ConsoleEvent[] = [];
   private pageErrors: PageErrorEvent[] = [];
@@ -202,6 +290,7 @@ export class Browser {
 
   /** Lazy: caller-side helper to find the active page if mid-flow. */
   get currentPage(): Page {
+    if (!this.page || this.page.isClosed()) this.selectMostRecentPage();
     if (!this.page) {
       throw new Error("Browser not opened. Call open() first.");
     }
@@ -223,6 +312,7 @@ export class Browser {
         ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
           ? { args: this.opts.launchArgs }
           : {}),
+        ...(this.opts.proxy ? { proxy: this.opts.proxy } : {}),
         ...(this.opts.recordHarPath
           ? { recordHar: { path: this.opts.recordHarPath, mode: "full" as const } }
           : {}),
@@ -253,8 +343,9 @@ export class Browser {
     }
 
     const pages = this.context.pages();
-    this.page = pages[0] ?? (await this.context.newPage());
-    this.attachDiagnosticListeners(this.page);
+    const firstPage = pages[0] ?? (await this.context.newPage());
+    for (const page of this.context.pages()) this.trackPage(page, page === firstPage);
+    this.context.on("page", (page) => this.trackPage(page, true));
   }
 
   /**
@@ -292,6 +383,10 @@ export class Browser {
         }
         this.context = null;
         this.page = null;
+        this.pageIndexes.clear();
+        this.pageRecency.clear();
+        this.nextPageIndex = 0;
+        this.recencyClock = 0;
         this.consoleEvents = [];
         this.pageErrors = [];
         this.failedRequests = [];
@@ -351,6 +446,80 @@ export class Browser {
     });
   }
 
+  private trackPage(page: Page, makeActive: boolean): void {
+    if (!this.pageIndexes.has(page)) {
+      this.pageIndexes.set(page, this.nextPageIndex++);
+      this.pageNavigations.set(page, {
+        sequence: 0,
+        occurred_at: null,
+        url: page.url(),
+        type: "unknown",
+      });
+      this.attachDiagnosticListeners(page);
+      page.on("domcontentloaded", () => this.recordDocumentNavigation(page));
+      page.once("close", () => {
+        this.pageRecency.delete(page);
+        this.pageNavigations.delete(page);
+        if (this.page === page) this.selectMostRecentPage();
+      });
+    }
+    if (makeActive) this.setActivePage(page);
+  }
+
+  private setActivePage(page: Page): void {
+    if (page.isClosed()) return;
+    this.page = page;
+    this.pageRecency.set(page, ++this.recencyClock);
+  }
+
+  private recordDocumentNavigation(page: Page): void {
+    if (page.isClosed()) return;
+    const previous = this.pageNavigations.get(page);
+    this.pageNavigations.set(page, {
+      sequence: (previous?.sequence ?? 0) + 1,
+      occurred_at: new Date().toISOString(),
+      url: page.url(),
+      type: "unknown",
+    });
+  }
+
+  private async describeNavigation(page: Page): Promise<BrowserSessionNavigation> {
+    const current = this.pageNavigations.get(page) ?? {
+      sequence: 0,
+      occurred_at: null,
+      url: page.url(),
+      type: "unknown" as const,
+    };
+    const type = await page
+      .evaluate<BrowserSessionNavigationType>(() => {
+        const entry = performance.getEntriesByType("navigation")[0] as
+          | PerformanceNavigationTiming
+          | undefined;
+        const observed = entry?.type;
+        return observed === "navigate" ||
+          observed === "reload" ||
+          observed === "back_forward" ||
+          observed === "prerender"
+          ? observed
+          : "unknown";
+      })
+      .catch(() => current.type);
+    const latest = this.pageNavigations.get(page);
+    if (latest?.sequence === current.sequence) {
+      const updated = { ...latest, type };
+      this.pageNavigations.set(page, updated);
+      return updated;
+    }
+    return latest ?? current;
+  }
+
+  private selectMostRecentPage(): void {
+    const surviving = [...this.pageIndexes.keys()].filter((page) => !page.isClosed());
+    surviving.sort((a, b) => (this.pageRecency.get(b) ?? 0) - (this.pageRecency.get(a) ?? 0));
+    this.page = surviving[0] ?? null;
+    if (this.page) this.pageRecency.set(this.page, ++this.recencyClock);
+  }
+
   /**
    * Snapshot of every event captured since `open()`. Returned objects are
    * copies, so callers can safely store them after `close()`.
@@ -661,6 +830,339 @@ export class Browser {
     });
   }
 
+  async sessionStatus(): Promise<BrowserSessionStatus> {
+    const tabs = await this.sessionTabs();
+    const active = tabs.find((tab) => tab.active);
+    if (!active) throw new BrowserSessionActionError("no_active_tab", "No active browser tab.");
+    return {
+      phase: "ready",
+      active_tab: active.index,
+      tab_count: tabs.length,
+      revision: this.sessionRevision,
+      navigation: active.navigation,
+    };
+  }
+
+  async sessionTabs(): Promise<BrowserSessionTab[]> {
+    this.selectMostRecentPageIfNeeded();
+    const pages = [...this.pageIndexes.entries()]
+      .filter(([page]) => !page.isClosed())
+      .sort((a, b) => a[1] - b[1]);
+    return await Promise.all(
+      pages.map(async ([page, index]) => ({
+        index,
+        title: await page.title().catch(() => ""),
+        url: page.url(),
+        active: page === this.page,
+        revision: this.sessionRevision,
+        navigation: await this.describeNavigation(page),
+      })),
+    );
+  }
+
+  async sessionSelectTab(index: number): Promise<BrowserSessionTab> {
+    const page = this.pageForIndex(index);
+    await page.bringToFront();
+    this.setActivePage(page);
+    this.sessionRevision++;
+    return this.describeTab(page);
+  }
+
+  async sessionOpenTab(url: string): Promise<BrowserSessionTab> {
+    if (!this.context) throw new BrowserSessionActionError("not_ready", "Browser is not open.");
+    const previous = this.page;
+    const page = await this.context.newPage();
+    this.trackPage(page, true);
+    try {
+      await page.goto(url, { waitUntil: this.opts.waitUntil ?? "load" });
+      this.sessionRevision++;
+      return await this.describeTab(page);
+    } catch (error) {
+      await page.close().catch(() => {});
+      if (previous && !previous.isClosed()) this.setActivePage(previous);
+      throw error;
+    }
+  }
+
+  async sessionCloseTab(index: number): Promise<BrowserSessionTab> {
+    const surviving = [...this.pageIndexes.keys()].filter((page) => !page.isClosed());
+    if (surviving.length <= 1) {
+      throw new BrowserSessionActionError("final_tab", "The final browser tab cannot be closed.");
+    }
+    const page = this.pageForIndex(index);
+    await page.close();
+    this.selectMostRecentPageIfNeeded();
+    this.sessionRevision++;
+    return this.describeTab(this.currentPage);
+  }
+
+  async sessionGoto(url: string): Promise<BrowserSessionTab> {
+    const page = this.currentPage;
+    await page.goto(url, { waitUntil: this.opts.waitUntil ?? "load" });
+    this.sessionRevision++;
+    return this.describeTab(page);
+  }
+
+  async sessionReload(): Promise<BrowserSessionTab> {
+    const page = this.currentPage;
+    await page.reload({ waitUntil: this.opts.waitUntil ?? "load" });
+    this.sessionRevision++;
+    return this.describeTab(page);
+  }
+
+  async sessionClick(locator: BrowserSessionLocator): Promise<{ revision: number }> {
+    const target = await this.strictSessionLocator(locator);
+    await target.click();
+    this.sessionRevision++;
+    return { revision: this.sessionRevision };
+  }
+
+  async sessionFill(locator: BrowserSessionLocator, value: string): Promise<{ revision: number }> {
+    const target = await this.strictSessionLocator(locator);
+    await target.fill(value);
+    this.sessionRevision++;
+    return { revision: this.sessionRevision };
+  }
+
+  async sessionPress(key: string): Promise<{ revision: number }> {
+    await this.currentPage.keyboard.press(key);
+    this.sessionRevision++;
+    return { revision: this.sessionRevision };
+  }
+
+  async sessionWait(locator: BrowserSessionLocator): Promise<{ revision: number }> {
+    const target = this.sessionLocator(locator);
+    await target.first().waitFor({ state: "visible" });
+    await this.requireStrictLocator(target);
+    this.sessionRevision++;
+    return { revision: this.sessionRevision };
+  }
+
+  async sessionInspect(locator?: BrowserSessionLocator): Promise<BrowserSessionInspection> {
+    const page = this.currentPage;
+    const tabIndex = this.pageIndexes.get(page);
+    if (tabIndex === undefined) {
+      throw new BrowserSessionActionError("no_active_tab", "No active browser tab.");
+    }
+    const rawText = locator
+      ? await (await this.strictSessionLocator(locator)).innerText()
+      : await page.locator("body").innerText();
+    const textResult = truncateUtf8(rawText, 256 * 1024);
+    const observed = await page.evaluate(() => {
+      const visible = (element: Element): boolean => {
+        const style = getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return (
+          style.display !== "none" &&
+          style.visibility !== "hidden" &&
+          Number(style.opacity) > 0 &&
+          rect.width > 0 &&
+          rect.height > 0
+        );
+      };
+      const named = (element: Element): string => {
+        const aria = element.getAttribute("aria-label")?.trim();
+        if (aria) return aria;
+        const labelledBy = element.getAttribute("aria-labelledby");
+        if (labelledBy) {
+          const text = labelledBy
+            .split(/\s+/)
+            .map((id) => document.getElementById(id)?.textContent?.trim() ?? "")
+            .filter(Boolean)
+            .join(" ");
+          if (text) return text;
+        }
+        if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+          const label = element.labels?.[0]?.textContent?.trim();
+          if (label) return label;
+          return element.placeholder?.trim() ?? "";
+        }
+        if (element instanceof HTMLSelectElement) {
+          return element.labels?.[0]?.textContent?.trim() ?? "";
+        }
+        return element.textContent?.replace(/\s+/g, " ").trim().slice(0, 200) ?? "";
+      };
+      const describe = (element: Element): BrowserSessionControl => {
+        const tag = element.tagName.toLowerCase();
+        const role = element.getAttribute("role")?.trim();
+        let kind = role || tag;
+        if (element instanceof HTMLAnchorElement) kind = "link";
+        if (element instanceof HTMLButtonElement) kind = "button";
+        const attributes: Record<string, string | boolean> = {};
+        const type = element.getAttribute("type")?.trim();
+        if (type) attributes.type = type;
+        const name = element.getAttribute("name")?.trim();
+        if (name) attributes.name = name;
+        const autocomplete = element.getAttribute("autocomplete")?.trim();
+        if (autocomplete) attributes.autocomplete = autocomplete;
+        if (element instanceof HTMLAnchorElement && element.href) {
+          try {
+            const href = new URL(element.href);
+            href.username = "";
+            href.password = "";
+            href.search = "";
+            href.hash = "";
+            attributes.href = href.toString();
+          } catch {
+            // Ignore malformed link targets.
+          }
+        }
+        if ("disabled" in element && (element as HTMLInputElement).disabled) {
+          attributes.disabled = true;
+        }
+        if (
+          (element instanceof HTMLInputElement && element.type !== "hidden") ||
+          element instanceof HTMLTextAreaElement ||
+          element instanceof HTMLSelectElement
+        ) {
+          return {
+            kind,
+            name: named(element),
+            attributes,
+            has_value: element.value.length > 0,
+          };
+        }
+        return { kind, name: named(element), attributes };
+      };
+      const selector = [
+        "a[href]",
+        "button",
+        "input:not([type=hidden])",
+        "select",
+        "textarea",
+        '[role="button"]',
+        '[role="link"]',
+        '[role="checkbox"]',
+        '[role="radio"]',
+        '[role="textbox"]',
+        '[role="combobox"]',
+      ].join(",");
+      const controls = Array.from(document.querySelectorAll(selector))
+        .filter(visible)
+        .slice(0, 500)
+        .map(describe);
+      const focus = document.activeElement;
+      return {
+        controls,
+        focus: focus && focus !== document.body && visible(focus) ? describe(focus) : null,
+      };
+    });
+    return {
+      active_tab: tabIndex,
+      url: page.url(),
+      title: await page.title(),
+      text: textResult.text,
+      controls: observed.controls,
+      focus: observed.focus,
+      revision: this.sessionRevision,
+      navigation: await this.describeNavigation(page),
+      truncated: textResult.truncated,
+    };
+  }
+
+  async sessionScreenshot(outInput: string): Promise<BrowserSessionScreenshot> {
+    const out = resolve(outInput);
+    let parent: ReturnType<typeof statSync>;
+    try {
+      parent = statSync(dirname(out));
+    } catch {
+      throw new BrowserSessionActionError(
+        "screenshot_parent_missing",
+        "Screenshot parent directory must already exist.",
+      );
+    }
+    if (!parent.isDirectory()) {
+      throw new BrowserSessionActionError(
+        "screenshot_parent_invalid",
+        "Screenshot parent is not a directory.",
+      );
+    }
+    const buffer = await this.currentPage.screenshot({ type: "png", fullPage: true });
+    if (buffer.length < 24 || buffer.toString("ascii", 1, 4) !== "PNG") {
+      throw new BrowserSessionActionError("screenshot_invalid", "Browser returned an invalid PNG.");
+    }
+    try {
+      writeFileSync(out, buffer, { flag: "wx", mode: 0o600 });
+      chmodSync(out, 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        throw new BrowserSessionActionError(
+          "screenshot_exists",
+          "Screenshot output already exists.",
+        );
+      }
+      throw error;
+    }
+    this.sessionRevision++;
+    return {
+      path: out,
+      width: buffer.readUInt32BE(16),
+      height: buffer.readUInt32BE(20),
+      revision: this.sessionRevision,
+    };
+  }
+
+  private sessionLocator(locator: BrowserSessionLocator): Locator {
+    const page = this.currentPage;
+    switch (locator.kind) {
+      case "selector":
+        return page.locator(locator.value);
+      case "role":
+        return page.getByRole(locator.value as Parameters<Page["getByRole"]>[0], {
+          ...(locator.name === undefined ? {} : { name: locator.name, exact: !locator.partial }),
+        });
+      case "label":
+        return page.getByLabel(locator.value, { exact: !locator.partial });
+      case "text":
+        return page.getByText(locator.value, { exact: !locator.partial });
+    }
+  }
+
+  private async strictSessionLocator(locator: BrowserSessionLocator): Promise<Locator> {
+    return this.requireStrictLocator(this.sessionLocator(locator));
+  }
+
+  private async requireStrictLocator(locator: Locator): Promise<Locator> {
+    const count = await locator.count();
+    if (count === 0) {
+      throw new BrowserSessionActionError("locator_not_found", "Locator matched no elements.");
+    }
+    if (count !== 1) {
+      throw new BrowserSessionActionError(
+        "locator_ambiguous",
+        `Locator matched ${count} elements; refine it before acting.`,
+      );
+    }
+    return locator;
+  }
+
+  private pageForIndex(index: number): Page {
+    const entry = [...this.pageIndexes.entries()].find(
+      ([page, pageIndex]) => pageIndex === index && !page.isClosed(),
+    );
+    if (!entry) throw new BrowserSessionActionError("tab_not_found", "Browser tab was not found.");
+    return entry[0];
+  }
+
+  private async describeTab(page: Page): Promise<BrowserSessionTab> {
+    const index = this.pageIndexes.get(page);
+    if (index === undefined || page.isClosed()) {
+      throw new BrowserSessionActionError("tab_not_found", "Browser tab was not found.");
+    }
+    return {
+      index,
+      title: await page.title().catch(() => ""),
+      url: page.url(),
+      active: page === this.page,
+      revision: this.sessionRevision,
+      navigation: await this.describeNavigation(page),
+    };
+  }
+
+  private selectMostRecentPageIfNeeded(): void {
+    if (!this.page || this.page.isClosed()) this.selectMostRecentPage();
+  }
+
   /**
    * Run occlusion checks on one or more selectors. For each, samples a grid
    * of points inside the element's bounding rect and uses
@@ -826,6 +1328,12 @@ export class Browser {
     await this.context.addInitScript(script);
   }
 
+  /** Snapshot all cookies in the live persistent context. */
+  async cookies(): Promise<PWCookie[]> {
+    if (!this.context) throw new Error("Browser not opened. Call open() first.");
+    return this.context.cookies();
+  }
+
   /**
    * Sync cookies from the live context back into the jar (if one was provided),
    * then tear everything down. Safe to call multiple times.
@@ -845,6 +1353,12 @@ export class Browser {
     await this.context.close().catch(() => {});
     this.context = null;
     this.page = null;
+    this.pageIndexes.clear();
+    this.pageRecency.clear();
+    this.pageNavigations.clear();
+    this.nextPageIndex = 0;
+    this.recencyClock = 0;
+    this.sessionRevision = 0;
   }
 }
 
@@ -890,3 +1404,11 @@ function normalizeSameSite(s: string | undefined): "Strict" | "Lax" | "None" | u
   if (lower === "none") return "None";
   return undefined;
 }
+
+function truncateUtf8(value: string, maxBytes: number): { text: string; truncated: boolean } {
+  const buffer = Buffer.from(value, "utf8");
+  if (buffer.length <= maxBytes) return { text: value, truncated: false };
+  let end = maxBytes;
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) end--;
+  return { text: buffer.subarray(0, end).toString("utf8"), truncated: true };
+}