hyper-agent-browser 0.1.0

package/src/session/store.ts

@@ -0,0 +1,172 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+
+export const SessionSchema = z.object({
+  name: z.string(),
+  status: z.enum(["running", "stopped"]),
+  channel: z.enum(["chrome", "msedge", "chromium"]),
+  userDataDir: z.string(),
+  url: z.string().optional(),
+  title: z.string().optional(),
+  pid: z.number().optional(),
+  wsEndpoint: z.string().optional(),
+  createdAt: z.number(),
+  lastActiveAt: z.number(),
+});
+
+export type Session = z.infer<typeof SessionSchema>;
+
+export class SessionStore {
+  private baseDir: string;
+
+  constructor(baseDir?: string) {
+    this.baseDir = baseDir || join(homedir(), ".hab", "sessions");
+  }
+
+  private getSessionDir(name: string): string {
+    return join(this.baseDir, name);
+  }
+
+  private getSessionFile(name: string): string {
+    return join(this.getSessionDir(name), "session.json");
+  }
+
+  private getUserDataDir(name: string): string {
+    return join(this.getSessionDir(name), "userdata");
+  }
+
+  async ensureBaseDir(): Promise<void> {
+    if (!existsSync(this.baseDir)) {
+      await mkdir(this.baseDir, { recursive: true, mode: 0o700 });
+    }
+  }
+
+  async exists(name: string): Promise<boolean> {
+    return existsSync(this.getSessionFile(name));
+  }
+
+  async load(name: string): Promise<Session | null> {
+    const file = this.getSessionFile(name);
+    if (!existsSync(file)) {
+      return null;
+    }
+
+    try {
+      const content = await readFile(file, "utf-8");
+      const data = JSON.parse(content);
+      return SessionSchema.parse(data);
+    } catch (error) {
+      console.error(`Failed to load session ${name}:`, error);
+      return null;
+    }
+  }
+
+  async save(session: Session): Promise<void> {
+    await this.ensureBaseDir();
+    const sessionDir = this.getSessionDir(session.name);
+
+    if (!existsSync(sessionDir)) {
+      await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+    }
+
+    const file = this.getSessionFile(session.name);
+    const content = JSON.stringify(session, null, 2);
+    await writeFile(file, content, "utf-8");
+
+    // Security: Set file permissions to 0o600 (owner read/write only)
+    // Protects wsEndpoint from being read by other processes
+    const { chmod } = await import("node:fs/promises");
+    await chmod(file, 0o600);
+  }
+
+  async create(name: string, channel: "chrome" | "msedge" | "chromium"): Promise<Session> {
+    await this.ensureBaseDir();
+
+    const sessionDir = this.getSessionDir(name);
+    const userDataDir = this.getUserDataDir(name);
+
+    if (!existsSync(sessionDir)) {
+      await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+    }
+
+    if (!existsSync(userDataDir)) {
+      await mkdir(userDataDir, { recursive: true, mode: 0o700 });
+    }
+
+    const now = Date.now();
+    const session: Session = {
+      name,
+      status: "stopped",
+      channel,
+      userDataDir,
+      createdAt: now,
+      lastActiveAt: now,
+    };
+
+    await this.save(session);
+    return session;
+  }
+
+  async update(name: string, updates: Partial<Session>): Promise<Session | null> {
+    const session = await this.load(name);
+    if (!session) {
+      return null;
+    }
+
+    const updated = {
+      ...session,
+      ...updates,
+      lastActiveAt: Date.now(),
+    };
+
+    await this.save(updated);
+    return updated;
+  }
+
+  async list(): Promise<Session[]> {
+    await this.ensureBaseDir();
+
+    if (!existsSync(this.baseDir)) {
+      return [];
+    }
+
+    const sessions: Session[] = [];
+
+    // Bun's readdir with withFileTypes not fully compatible, fallback to simple approach
+    const { readdirSync } = await import("node:fs");
+    const dirs = readdirSync(this.baseDir, { withFileTypes: true });
+
+    for (const entry of dirs) {
+      if (entry.isDirectory()) {
+        const session = await this.load(entry.name);
+        if (session) {
+          sessions.push(session);
+        }
+      }
+    }
+
+    return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt);
+  }
+
+  async delete(name: string): Promise<boolean> {
+    const sessionDir = this.getSessionDir(name);
+    if (!existsSync(sessionDir)) {
+      return false;
+    }
+
+    const { rmSync } = await import("node:fs");
+    rmSync(sessionDir, { recursive: true, force: true });
+    return true;
+  }
+
+  async updateActivity(name: string): Promise<void> {
+    const session = await this.load(name);
+    if (session) {
+      session.lastActiveAt = Date.now();
+      await this.save(session);
+    }
+  }
+}

package/src/snapshot/accessibility.ts

@@ -0,0 +1,182 @@
+import type { Page } from "patchright";
+
+export interface SnapshotElement {
+  ref: string;
+  role: string;
+  name: string;
+  value?: string;
+  description?: string;
+  checked?: boolean;
+  selected?: boolean;
+  disabled?: boolean;
+  focused?: boolean;
+  required?: boolean;
+  boundingBox?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+}
+
+export interface Snapshot {
+  url: string;
+  title: string;
+  timestamp: number;
+  elements: SnapshotElement[];
+}
+
+const INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "menuitem",
+  "tab",
+  "searchbox",
+  "spinbutton",
+  "slider",
+  "switch",
+  "option",
+]);
+
+interface AccessibilityNode {
+  role?: string;
+  name?: string;
+  value?: string | number;
+  description?: string;
+  checked?: boolean | "mixed";
+  disabled?: boolean;
+  expanded?: boolean;
+  focused?: boolean;
+  level?: number;
+  modal?: boolean;
+  multiline?: boolean;
+  multiselectable?: boolean;
+  orientation?: string;
+  placeholder?: string;
+  pressed?: boolean | "mixed";
+  readonly?: boolean;
+  required?: boolean;
+  selected?: boolean;
+  valuemax?: number;
+  valuemin?: number;
+  valuenow?: number;
+  valuetext?: string;
+  children?: AccessibilityNode[];
+}
+
+export class AccessibilityExtractor {
+  private elementCounter = 0;
+  private elementMap = new Map<string, SnapshotElement>();
+
+  private async getAccessibilitySnapshot(page: Page): Promise<AccessibilityNode | null> {
+    try {
+      // Try to use accessibility API if available
+      return await (page as any).accessibility?.snapshot();
+    } catch {
+      // Fallback: return null, we'll implement alternative extraction later
+      return null;
+    }
+  }
+
+  async extract(page: Page, interactiveOnly = true): Promise<Snapshot> {
+    this.elementCounter = 0;
+    this.elementMap.clear();
+
+    const url = page.url();
+    const title = await page.title();
+    const timestamp = Date.now();
+
+    // Get accessibility tree
+    // Note: Using locator API as fallback since accessibility API may not be available
+    const snapshot = await this.getAccessibilitySnapshot(page);
+    if (!snapshot) {
+      return { url, title, timestamp, elements: [] };
+    }
+
+    // Extract elements
+    const elements = this.extractElements(snapshot, interactiveOnly);
+
+    return {
+      url,
+      title,
+      timestamp,
+      elements,
+    };
+  }
+
+  private extractElements(node: AccessibilityNode, interactiveOnly: boolean): SnapshotElement[] {
+    const elements: SnapshotElement[] = [];
+
+    if (this.shouldInclude(node, interactiveOnly)) {
+      const element = this.nodeToElement(node);
+      if (element) {
+        elements.push(element);
+      }
+    }
+
+    // Recursively process children
+    if (node.children) {
+      for (const child of node.children) {
+        elements.push(...this.extractElements(child, interactiveOnly));
+      }
+    }
+
+    return elements;
+  }
+
+  private shouldInclude(node: AccessibilityNode, interactiveOnly: boolean): boolean {
+    if (!node.role) {
+      return false;
+    }
+
+    if (interactiveOnly) {
+      return INTERACTIVE_ROLES.has(node.role);
+    }
+
+    return true;
+  }
+
+  private nodeToElement(node: AccessibilityNode): SnapshotElement | null {
+    if (!node.role) {
+      return null;
+    }
+
+    this.elementCounter++;
+    const ref = `e${this.elementCounter}`;
+
+    const element: SnapshotElement = {
+      ref,
+      role: node.role,
+      name: node.name || "",
+      value: this.formatValue(node.value),
+      description: node.description,
+      checked: typeof node.checked === "boolean" ? node.checked : undefined,
+      selected: node.selected,
+      disabled: node.disabled,
+      focused: node.focused,
+      required: node.required,
+    };
+
+    this.elementMap.set(ref, element);
+    return element;
+  }
+
+  private formatValue(value: string | number | undefined): string | undefined {
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+    return String(value);
+  }
+
+  getElementByRef(ref: string): SnapshotElement | undefined {
+    return this.elementMap.get(ref);
+  }
+
+  getAllElements(): SnapshotElement[] {
+    return Array.from(this.elementMap.values());
+  }
+}

package/src/snapshot/dom-extractor.ts

@@ -0,0 +1,220 @@
+import type { Page } from "patchright";
+import type { SnapshotElement } from "./accessibility";
+
+/**
+ * Fallback snapshot extractor using DOM traversal
+ * Used when accessibility API is not available
+ */
+export class DomSnapshotExtractor {
+  private elementCounter = 0;
+  private elementMap = new Map<string, { selector: string; element: SnapshotElement }>();
+
+  async extract(page: Page, interactiveOnly = true): Promise<SnapshotElement[]> {
+    this.elementCounter = 0;
+    this.elementMap.clear();
+
+    // Inject script to extract interactive elements from DOM
+    const elements = await page.evaluate((interactiveOnly) => {
+      const interactiveRoles = new Set([
+        "button",
+        "link",
+        "textbox",
+        "checkbox",
+        "radio",
+        "combobox",
+        "menuitem",
+        "tab",
+        "searchbox",
+      ]);
+
+      const results: any[] = [];
+
+      // Helper to get role from element
+      function getRole(el: Element): string | null {
+        // Check ARIA role
+        const ariaRole = el.getAttribute("role");
+        if (ariaRole) return ariaRole;
+
+        // Infer from tag name
+        const tagName = el.tagName.toLowerCase();
+        switch (tagName) {
+          case "button":
+            return "button";
+          case "a":
+            return "link";
+          case "input": {
+            const type = (el as HTMLInputElement).type.toLowerCase();
+            if (type === "checkbox") return "checkbox";
+            if (type === "radio") return "radio";
+            if (type === "submit" || type === "button") return "button";
+            return "textbox";
+          }
+          case "textarea":
+            return "textbox";
+          case "select":
+            return "combobox";
+          default:
+            return null;
+        }
+      }
+
+      // Helper to get accessible name
+      function getName(el: Element): string {
+        // Check aria-label
+        const ariaLabel = el.getAttribute("aria-label");
+        if (ariaLabel) return ariaLabel;
+
+        // Check aria-labelledby
+        const labelledBy = el.getAttribute("aria-labelledby");
+        if (labelledBy) {
+          const labelEl = document.getElementById(labelledBy);
+          if (labelEl) return labelEl.textContent?.trim() || "";
+        }
+
+        // Check associated label
+        if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+          const labels = (el as any).labels;
+          if (labels && labels.length > 0) {
+            return labels[0].textContent?.trim() || "";
+          }
+        }
+
+        // Check placeholder
+        const placeholder = el.getAttribute("placeholder");
+        if (placeholder) return placeholder;
+
+        // Use text content for buttons and links
+        if (el.tagName === "BUTTON" || el.tagName === "A") {
+          return el.textContent?.trim() || "";
+        }
+
+        // Use value for inputs
+        if (el instanceof HTMLInputElement) {
+          return el.value || "";
+        }
+
+        return "";
+      }
+
+      // Helper to generate CSS selector
+      function getSelector(el: Element): string {
+        // Try ID first
+        if (el.id) return `#${el.id}`;
+
+        // Generate nth-child selector
+        let selector = el.tagName.toLowerCase();
+        let current: Element | null = el;
+
+        while (current?.parentElement) {
+          const parent: Element = current.parentElement;
+          const siblings = Array.from(parent.children);
+          const index = siblings.indexOf(current);
+
+          if (index >= 0) {
+            selector = `${parent.tagName.toLowerCase()} > ${selector}:nth-child(${index + 1})`;
+          }
+
+          current = parent;
+          if (current?.id) {
+            selector = `#${current.id} ${selector}`;
+            break;
+          }
+
+          // Limit depth
+          if (selector.split(">").length > 5) break;
+        }
+
+        return selector;
+      }
+
+      // Traverse DOM
+      function traverse(el: Element) {
+        const role = getRole(el);
+
+        if (role && (!interactiveOnly || interactiveRoles.has(role))) {
+          const name = getName(el);
+          const selector = getSelector(el);
+
+          // Get element properties
+          const result: any = {
+            role,
+            name,
+            selector,
+            disabled: (el as any).disabled || false,
+            focused: el === document.activeElement,
+            required: (el as any).required || false,
+          };
+
+          // Get value for inputs
+          if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            result.value = el.value;
+          }
+
+          // Get checked state for checkboxes/radios
+          if (el instanceof HTMLInputElement) {
+            if (el.type === "checkbox" || el.type === "radio") {
+              result.checked = el.checked;
+            }
+          }
+
+          results.push(result);
+        }
+
+        // Recurse to children
+        for (const child of Array.from(el.children)) {
+          traverse(child);
+        }
+      }
+
+      traverse(document.body);
+      return results;
+    }, interactiveOnly);
+
+    // Convert to SnapshotElement format with @eN references
+    const snapshotElements: SnapshotElement[] = [];
+
+    for (const el of elements) {
+      this.elementCounter++;
+      const ref = `e${this.elementCounter}`;
+
+      const snapshotElement: SnapshotElement = {
+        ref,
+        role: el.role,
+        name: el.name,
+        value: el.value,
+        checked: el.checked,
+        disabled: el.disabled,
+        focused: el.focused,
+        required: el.required,
+      };
+
+      snapshotElements.push(snapshotElement);
+
+      // Store mapping from ref to selector
+      this.elementMap.set(ref, {
+        selector: el.selector,
+        element: snapshotElement,
+      });
+    }
+
+    return snapshotElements;
+  }
+
+  /**
+   * Get CSS selector for an element reference
+   */
+  getSelector(ref: string): string | undefined {
+    return this.elementMap.get(ref)?.selector;
+  }
+
+  /**
+   * Get all element references and their selectors
+   */
+  getAllMappings(): Map<string, string> {
+    const mappings = new Map<string, string>();
+    for (const [ref, { selector }] of this.elementMap.entries()) {
+      mappings.set(ref, selector);
+    }
+    return mappings;
+  }
+}

package/src/snapshot/formatter.ts

@@ -0,0 +1,115 @@
+import type { Snapshot, SnapshotElement } from "./accessibility";
+
+export interface FormatOptions {
+  maxElements?: number;
+  includeDisabled?: boolean;
+}
+
+export class SnapshotFormatter {
+  format(snapshot: Snapshot, options: FormatOptions = {}): string {
+    const lines: string[] = [];
+
+    // Header
+    lines.push(`URL: ${snapshot.url}`);
+    lines.push(`Title: ${snapshot.title}`);
+    lines.push("");
+
+    // Elements
+    let elements = snapshot.elements;
+
+    // Filter disabled elements if needed
+    if (!options.includeDisabled) {
+      elements = elements.filter((el) => !el.disabled);
+    }
+
+    // Limit elements
+    if (options.maxElements && elements.length > options.maxElements) {
+      elements = elements.slice(0, options.maxElements);
+      lines.push(
+        `Interactive Elements (showing ${options.maxElements} of ${snapshot.elements.length}):`,
+      );
+    } else {
+      lines.push("Interactive Elements:");
+    }
+
+    // Format each element
+    for (const element of elements) {
+      lines.push(this.formatElement(element));
+    }
+
+    if (elements.length === 0) {
+      lines.push("  (no interactive elements found)");
+    }
+
+    return lines.join("\n");
+  }
+
+  formatElement(element: SnapshotElement): string {
+    const parts: string[] = [];
+
+    // Reference
+    parts.push(`@${element.ref}`);
+
+    // Role
+    parts.push(`[${element.role}]`.padEnd(12));
+
+    // Name
+    if (element.name) {
+      parts.push(`"${element.name}"`);
+    }
+
+    // Value
+    if (element.value && element.value !== element.name) {
+      parts.push(`value="${element.value}"`);
+    }
+
+    // States
+    const states: string[] = [];
+    if (element.focused) states.push("focused");
+    if (element.checked !== undefined) {
+      states.push(element.checked ? "checked" : "unchecked");
+    }
+    if (element.selected) states.push("selected");
+    if (element.disabled) states.push("disabled");
+    if (element.required) states.push("required");
+
+    if (states.length > 0) {
+      parts.push(`(${states.join(", ")})`);
+    }
+
+    return parts.join("  ");
+  }
+
+  formatJson(snapshot: Snapshot, pretty = true): string {
+    return JSON.stringify(snapshot, null, pretty ? 2 : 0);
+  }
+
+  formatCompact(snapshot: Snapshot): string {
+    const lines: string[] = [];
+    lines.push(`${snapshot.url} | ${snapshot.title}`);
+    lines.push(`Elements: ${snapshot.elements.length}`);
+    return lines.join("\n");
+  }
+
+  formatSummary(snapshot: Snapshot): string {
+    const roleCounts = new Map<string, number>();
+
+    for (const element of snapshot.elements) {
+      const count = roleCounts.get(element.role) || 0;
+      roleCounts.set(element.role, count + 1);
+    }
+
+    const lines: string[] = [];
+    lines.push(`URL: ${snapshot.url}`);
+    lines.push(`Title: ${snapshot.title}`);
+    lines.push("");
+    lines.push("Element Summary:");
+
+    const sorted = Array.from(roleCounts.entries()).sort((a, b) => b[1] - a[1]);
+    for (const [role, count] of sorted) {
+      lines.push(`  ${role}: ${count}`);
+    }
+
+    return lines.join("\n");
+  }
+}