hyper-agent-browser 0.1.0

package/src/commands/actions.ts

@@ -0,0 +1,232 @@
+import type { Locator, Page } from "patchright";
+import { parseSelector } from "../utils/selector";
+
+// Global reference store for element mappings
+let globalReferenceStore: any = null;
+
+export function setReferenceStore(store: any) {
+  globalReferenceStore = store;
+}
+
+async function getLocator(page: Page, selector: string): Promise<Locator> {
+  const parsed = parseSelector(selector);
+
+  switch (parsed.type) {
+    case "ref": {
+      // Try to resolve @eN reference to actual selector
+      if (!globalReferenceStore) {
+        throw new Error(
+          `Element reference @${parsed.value} requires a snapshot first. Run 'hab snapshot -i' to generate element references.`,
+        );
+      }
+
+      const actualSelector = globalReferenceStore.get(parsed.value);
+      if (!actualSelector) {
+        throw new Error(
+          `Element reference @${parsed.value} not found. Run 'hab snapshot -i' to update element references.`,
+        );
+      }
+
+      // Use the mapped CSS selector
+      return page.locator(actualSelector);
+    }
+    case "css":
+      return page.locator(parsed.value);
+    case "text":
+      return page.getByText(parsed.value);
+    case "xpath":
+      return page.locator(`xpath=${parsed.value}`);
+    default:
+      throw new Error(`Unknown selector type: ${parsed.type}`);
+  }
+}
+
+export async function click(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.click();
+}
+
+export async function fill(page: Page, selector: string, value: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.fill(value);
+}
+
+export async function type(page: Page, selector: string, text: string, delay = 0): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.pressSequentially(text, { delay });
+}
+
+export async function press(page: Page, key: string): Promise<void> {
+  await page.keyboard.press(key);
+}
+
+export async function scroll(
+  page: Page,
+  direction: "up" | "down" | "left" | "right",
+  amount = 500,
+  selector?: string,
+): Promise<void> {
+  if (selector) {
+    const locator = await getLocator(page, selector);
+    const element = await locator.elementHandle();
+    if (!element) {
+      throw new Error(`Element not found: ${selector}`);
+    }
+
+    await element.evaluate(
+      (el, { direction, amount }) => {
+        const scrollMap = {
+          down: { top: amount, left: 0 },
+          up: { top: -amount, left: 0 },
+          right: { top: 0, left: amount },
+          left: { top: 0, left: -amount },
+        };
+        const scroll = scrollMap[direction as keyof typeof scrollMap];
+        el.scrollBy(scroll);
+      },
+      { direction, amount },
+    );
+  } else {
+    await page.evaluate(
+      ({ direction, amount }) => {
+        const scrollMap = {
+          down: { top: amount, left: 0 },
+          up: { top: -amount, left: 0 },
+          right: { top: 0, left: amount },
+          left: { top: 0, left: -amount },
+        };
+        const scroll = scrollMap[direction as keyof typeof scrollMap];
+        // @ts-ignore - window is available in browser context
+        window.scrollBy(scroll);
+      },
+      { direction, amount },
+    );
+  }
+}
+
+export async function hover(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.hover();
+}
+
+export async function select(page: Page, selector: string, value: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.selectOption(value);
+}
+
+export interface WaitOptions {
+  timeout?: number;
+  text?: string;
+  url?: string;
+  fn?: string;
+  load?: "load" | "domcontentloaded" | "networkidle";
+}
+
+export async function wait(
+  page: Page,
+  condition: string | number,
+  options: WaitOptions = {},
+): Promise<void> {
+  const timeout = options.timeout || 30000;
+
+  // Wait for milliseconds
+  if (typeof condition === "number") {
+    await page.waitForTimeout(condition);
+    return;
+  }
+
+  // Wait for navigation
+  if (condition === "navigation") {
+    await page.waitForLoadState("load", { timeout });
+    return;
+  }
+
+  // Wait for load state (--load networkidle)
+  if (options.load) {
+    await page.waitForLoadState(options.load, { timeout });
+    return;
+  }
+
+  // Wait for text to appear (--text "Welcome")
+  if (options.text) {
+    await page.waitForSelector(`text=${options.text}`, { timeout });
+    return;
+  }
+
+  // Wait for URL pattern (--url "**/dashboard")
+  if (options.url) {
+    await page.waitForURL(options.url, { timeout });
+    return;
+  }
+
+  // Wait for JavaScript condition (--fn "window.loaded === true")
+  if (options.fn) {
+    await page.waitForFunction(options.fn, { timeout });
+    return;
+  }
+
+  // Wait for selector to be visible
+  if (condition.startsWith("selector=")) {
+    const selector = condition.slice(9);
+    const locator = await getLocator(page, selector);
+    await locator.waitFor({ state: "visible", timeout });
+    return;
+  }
+
+  // Wait for selector to be hidden
+  if (condition.startsWith("hidden=")) {
+    const selector = condition.slice(7);
+    const locator = await getLocator(page, selector);
+    await locator.waitFor({ state: "hidden", timeout });
+    return;
+  }
+
+  throw new Error(`Unknown wait condition: ${condition}`);
+}
+
+// ============ 第一批高优先级功能 ============
+
+export async function check(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.check();
+}
+
+export async function uncheck(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.uncheck();
+}
+
+export async function dblclick(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.dblclick();
+}
+
+export async function focus(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.focus();
+}
+
+export async function upload(
+  page: Page,
+  selector: string,
+  files: string | string[],
+): Promise<void> {
+  const locator = await getLocator(page, selector);
+  const filePaths = Array.isArray(files) ? files : [files];
+  await locator.setInputFiles(filePaths);
+}
+
+export async function scrollIntoView(page: Page, selector: string): Promise<void> {
+  const locator = await getLocator(page, selector);
+  await locator.scrollIntoViewIfNeeded();
+}
+
+export async function drag(
+  page: Page,
+  sourceSelector: string,
+  targetSelector: string,
+): Promise<void> {
+  const source = await getLocator(page, sourceSelector);
+  const target = await getLocator(page, targetSelector);
+  await source.dragTo(target);
+}

package/src/commands/advanced.ts

@@ -0,0 +1,252 @@
+import type { Cookie, Page } from "patchright";
+
+// ============ Dialog 对话框处理 ============
+
+export async function setupDialogHandler(
+  page: Page,
+  action: "accept" | "dismiss",
+  promptText?: string,
+): Promise<void> {
+  page.on("dialog", async (dialog) => {
+    if (action === "accept") {
+      await dialog.accept(promptText);
+    } else {
+      await dialog.dismiss();
+    }
+  });
+}
+
+export async function dialogAccept(page: Page, text?: string): Promise<void> {
+  await setupDialogHandler(page, "accept", text);
+}
+
+export async function dialogDismiss(page: Page): Promise<void> {
+  await setupDialogHandler(page, "dismiss");
+}
+
+// ============ Cookie 管理 ============
+
+export async function getCookies(page: Page): Promise<Cookie[]> {
+  const context = page.context();
+  return await context.cookies();
+}
+
+export async function setCookie(page: Page, name: string, value: string): Promise<void> {
+  const context = page.context();
+  const url = page.url();
+
+  await context.addCookies([
+    {
+      name,
+      value,
+      url,
+    },
+  ]);
+}
+
+export async function clearCookies(page: Page): Promise<void> {
+  const context = page.context();
+  await context.clearCookies();
+}
+
+// ============ Storage 管理 ============
+
+export async function getLocalStorage(page: Page, key?: string): Promise<any> {
+  if (key) {
+    return await page.evaluate((k) => localStorage.getItem(k), key);
+  }
+
+  return await page.evaluate(() => {
+    const items: Record<string, string> = {};
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key) {
+        items[key] = localStorage.getItem(key) || "";
+      }
+    }
+    return items;
+  });
+}
+
+export async function setLocalStorage(page: Page, key: string, value: string): Promise<void> {
+  await page.evaluate(({ k, v }) => localStorage.setItem(k, v), { k: key, v: value });
+}
+
+export async function clearLocalStorage(page: Page): Promise<void> {
+  await page.evaluate(() => localStorage.clear());
+}
+
+export async function getSessionStorage(page: Page, key?: string): Promise<any> {
+  if (key) {
+    return await page.evaluate((k) => sessionStorage.getItem(k), key);
+  }
+
+  return await page.evaluate(() => {
+    const items: Record<string, string> = {};
+    for (let i = 0; i < sessionStorage.length; i++) {
+      const key = sessionStorage.key(i);
+      if (key) {
+        items[key] = sessionStorage.getItem(key) || "";
+      }
+    }
+    return items;
+  });
+}
+
+export async function setSessionStorage(page: Page, key: string, value: string): Promise<void> {
+  await page.evaluate(({ k, v }) => sessionStorage.setItem(k, v), { k: key, v: value });
+}
+
+export async function clearSessionStorage(page: Page): Promise<void> {
+  await page.evaluate(() => sessionStorage.clear());
+}
+
+// ============ PDF 导出 ============
+
+export interface PDFOptions {
+  path: string;
+  format?:
+    | "Letter"
+    | "Legal"
+    | "Tabloid"
+    | "Ledger"
+    | "A0"
+    | "A1"
+    | "A2"
+    | "A3"
+    | "A4"
+    | "A5"
+    | "A6";
+  landscape?: boolean;
+  printBackground?: boolean;
+  margin?: {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+  };
+}
+
+export async function savePDF(page: Page, options: PDFOptions): Promise<string> {
+  await page.pdf({
+    path: options.path,
+    format: options.format || "A4",
+    landscape: options.landscape || false,
+    printBackground: options.printBackground !== false,
+    margin: options.margin,
+  });
+
+  return options.path;
+}
+
+// ============ 设备模拟 ============
+
+export async function setViewport(page: Page, width: number, height: number): Promise<void> {
+  await page.setViewportSize({ width, height });
+}
+
+export async function setGeolocation(
+  page: Page,
+  latitude: number,
+  longitude: number,
+): Promise<void> {
+  const context = page.context();
+  await context.setGeolocation({ latitude, longitude });
+}
+
+export async function setOffline(page: Page, offline: boolean): Promise<void> {
+  const context = page.context();
+  await context.setOffline(offline);
+}
+
+export async function setExtraHeaders(page: Page, headers: Record<string, string>): Promise<void> {
+  const context = page.context();
+  await context.setExtraHTTPHeaders(headers);
+}
+
+export async function setMediaColorScheme(
+  page: Page,
+  scheme: "light" | "dark" | "no-preference",
+): Promise<void> {
+  await page.emulateMedia({ colorScheme: scheme });
+}
+
+// ============ 鼠标控制 ============
+
+export async function mouseMove(page: Page, x: number, y: number): Promise<void> {
+  await page.mouse.move(x, y);
+}
+
+export async function mouseDown(
+  page: Page,
+  button: "left" | "right" | "middle" = "left",
+): Promise<void> {
+  await page.mouse.down({ button });
+}
+
+export async function mouseUp(
+  page: Page,
+  button: "left" | "right" | "middle" = "left",
+): Promise<void> {
+  await page.mouse.up({ button });
+}
+
+export async function mouseWheel(page: Page, deltaY: number, deltaX = 0): Promise<void> {
+  await page.mouse.wheel(deltaX, deltaY);
+}
+
+// ============ 键盘控制 ============
+
+export async function keyDown(page: Page, key: string): Promise<void> {
+  await page.keyboard.down(key);
+}
+
+export async function keyUp(page: Page, key: string): Promise<void> {
+  await page.keyboard.up(key);
+}
+
+// ============ Console & Errors ============
+
+const consoleLogs: string[] = [];
+const pageErrors: string[] = [];
+
+export function setupConsoleCapture(page: Page): void {
+  page.on("console", (msg) => {
+    consoleLogs.push(`[${msg.type()}] ${msg.text()}`);
+  });
+}
+
+export function setupErrorCapture(page: Page): void {
+  page.on("pageerror", (error) => {
+    pageErrors.push(error.message);
+  });
+}
+
+export function getConsoleLogs(): string[] {
+  return [...consoleLogs];
+}
+
+export function clearConsoleLogs(): void {
+  consoleLogs.length = 0;
+}
+
+export function getPageErrors(): string[] {
+  return [...pageErrors];
+}
+
+export function clearPageErrors(): void {
+  pageErrors.length = 0;
+}
+
+// ============ 元素高亮 ============
+
+export async function highlightElement(page: Page, selector: string): Promise<void> {
+  await page.evaluate((sel) => {
+    const element = document.querySelector(sel);
+    if (element && element instanceof HTMLElement) {
+      element.style.outline = "3px solid red";
+      element.style.outlineOffset = "2px";
+      element.scrollIntoView({ behavior: "smooth", block: "center" });
+    }
+  }, selector);
+}

package/src/commands/config.ts

@@ -0,0 +1,44 @@
+import { getConfigValue, loadConfig, setConfigValue } from "../utils/config";
+
+export async function listConfig(): Promise<string> {
+  const config = await loadConfig();
+  return JSON.stringify(config, null, 2);
+}
+
+export async function getConfig(key: string): Promise<string> {
+  const value = await getConfigValue(key);
+
+  if (value === undefined) {
+    throw new Error(`Config key not found: ${key}`);
+  }
+
+  if (typeof value === "object") {
+    return JSON.stringify(value, null, 2);
+  }
+
+  return String(value);
+}
+
+export async function setConfig(key: string, value: string): Promise<string> {
+  // Parse value
+  let parsedValue: unknown = value;
+
+  // Try to parse as JSON first
+  if (value === "true") {
+    parsedValue = true;
+  } else if (value === "false") {
+    parsedValue = false;
+  } else if (!Number.isNaN(Number(value))) {
+    parsedValue = Number(value);
+  } else {
+    try {
+      parsedValue = JSON.parse(value);
+    } catch {
+      // Keep as string
+      parsedValue = value;
+    }
+  }
+
+  await setConfigValue(key, parsedValue);
+  return `Config updated: ${key} = ${JSON.stringify(parsedValue)}`;
+}

package/src/commands/getters.ts

@@ -0,0 +1,110 @@
+import type { Page } from "patchright";
+import { parseSelector } from "../utils/selector";
+
+// Global reference store for element mappings
+let globalReferenceStore: any = null;
+
+export function setReferenceStore(store: any) {
+  globalReferenceStore = store;
+}
+
+async function getLocator(page: Page, selector: string) {
+  const parsed = parseSelector(selector);
+
+  switch (parsed.type) {
+    case "ref": {
+      if (!globalReferenceStore) {
+        throw new Error(
+          `Element reference @${parsed.value} requires a snapshot first. Run 'hab snapshot -i' to generate element references.`,
+        );
+      }
+
+      const actualSelector = globalReferenceStore.get(parsed.value);
+      if (!actualSelector) {
+        throw new Error(
+          `Element reference @${parsed.value} not found. Run 'hab snapshot -i' to update element references.`,
+        );
+      }
+
+      return page.locator(actualSelector);
+    }
+    case "css":
+      return page.locator(parsed.value);
+    case "text":
+      return page.getByText(parsed.value);
+    case "xpath":
+      return page.locator(`xpath=${parsed.value}`);
+    default:
+      throw new Error(`Unknown selector type: ${parsed.type}`);
+  }
+}
+
+// ============ Get 系列命令 ============
+
+export async function getText(page: Page, selector: string): Promise<string> {
+  const locator = await getLocator(page, selector);
+  const text = await locator.textContent();
+  return text || "";
+}
+
+export async function getValue(page: Page, selector: string): Promise<string> {
+  const locator = await getLocator(page, selector);
+  const value = await locator.inputValue();
+  return value || "";
+}
+
+export async function getAttr(page: Page, selector: string, attribute: string): Promise<string> {
+  const locator = await getLocator(page, selector);
+  const value = await locator.getAttribute(attribute);
+  return value || "";
+}
+
+export async function getHtml(page: Page, selector: string): Promise<string> {
+  const locator = await getLocator(page, selector);
+  const html = await locator.innerHTML();
+  return html || "";
+}
+
+export async function getCount(page: Page, selector: string): Promise<number> {
+  const locator = await getLocator(page, selector);
+  return await locator.count();
+}
+
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export async function getBox(page: Page, selector: string): Promise<BoundingBox | null> {
+  const locator = await getLocator(page, selector);
+  return await locator.boundingBox();
+}
+
+// ============ Is 系列命令 (状态检查) ============
+
+export async function isVisible(page: Page, selector: string): Promise<boolean> {
+  const locator = await getLocator(page, selector);
+  return await locator.isVisible();
+}
+
+export async function isEnabled(page: Page, selector: string): Promise<boolean> {
+  const locator = await getLocator(page, selector);
+  return await locator.isEnabled();
+}
+
+export async function isChecked(page: Page, selector: string): Promise<boolean> {
+  const locator = await getLocator(page, selector);
+  return await locator.isChecked();
+}
+
+export async function isEditable(page: Page, selector: string): Promise<boolean> {
+  const locator = await getLocator(page, selector);
+  return await locator.isEditable();
+}
+
+export async function isHidden(page: Page, selector: string): Promise<boolean> {
+  const locator = await getLocator(page, selector);
+  return await locator.isHidden();
+}