@aria-cli/tools 1.0.0

package/src/definitions/browser/pw-snapshot.ts

@@ -0,0 +1,383 @@
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
+
+/**
+ * Accessibility tree snapshot and role-ref system.
+ * Ported from OpenClaw's pw-role-snapshot.ts + pw-tools-core.snapshot.ts.
+ */
+
+import type { PwPage, RoleRefMap, RoleSnapshotStats, SnapshotResult } from "./types.js";
+
+// ── Role classification sets ──────────────────────────────────────────
+
+const INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "treeitem",
+]);
+
+const CONTENT_ROLES = new Set([
+  "heading",
+  "cell",
+  "gridcell",
+  "columnheader",
+  "rowheader",
+  "listitem",
+  "article",
+  "region",
+  "main",
+  "navigation",
+]);
+
+const STRUCTURAL_ROLES = new Set([
+  "generic",
+  "group",
+  "list",
+  "table",
+  "row",
+  "rowgroup",
+  "grid",
+  "treegrid",
+  "menu",
+  "menubar",
+  "toolbar",
+  "tablist",
+  "tree",
+  "directory",
+  "document",
+  "application",
+  "presentation",
+  "none",
+]);
+
+// ── Snapshot options ──────────────────────────────────────────────────
+
+export interface RoleSnapshotOptions {
+  /** Only include interactive elements (buttons, links, inputs, etc.). */
+  interactive?: boolean;
+  /** Maximum depth to include (0 = root only). */
+  maxDepth?: number;
+  /** Remove unnamed structural elements and empty branches. */
+  compact?: boolean;
+}
+
+// ── Stats ─────────────────────────────────────────────────────────────
+
+export function getRoleSnapshotStats(snapshot: string, refs: RoleRefMap): RoleSnapshotStats {
+  const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;
+  return {
+    lines: snapshot.split("\n").length,
+    chars: snapshot.length,
+    refs: Object.keys(refs).length,
+    interactive,
+  };
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────
+
+function getIndentLevel(line: string): number {
+  const match = line.match(/^(\s*)/);
+  return match ? Math.floor(match[1]!.length / 2) : 0;
+}
+
+type RoleNameTracker = {
+  counts: Map<string, number>;
+  refsByKey: Map<string, string[]>;
+  getKey: (role: string, name?: string) => string;
+  getNextIndex: (role: string, name?: string) => number;
+  trackRef: (role: string, name: string | undefined, ref: string) => void;
+  getDuplicateKeys: () => Set<string>;
+};
+
+function createRoleNameTracker(): RoleNameTracker {
+  const counts = new Map<string, number>();
+  const refsByKey = new Map<string, string[]>();
+  return {
+    counts,
+    refsByKey,
+    getKey(role: string, name?: string) {
+      return `${role}:${name ?? ""}`;
+    },
+    getNextIndex(role: string, name?: string) {
+      const key = this.getKey(role, name);
+      const current = counts.get(key) ?? 0;
+      counts.set(key, current + 1);
+      return current;
+    },
+    trackRef(role: string, name: string | undefined, ref: string) {
+      const key = this.getKey(role, name);
+      const list = refsByKey.get(key) ?? [];
+      list.push(ref);
+      refsByKey.set(key, list);
+    },
+    getDuplicateKeys() {
+      const out = new Set<string>();
+      for (const [key, refs] of refsByKey) {
+        if (refs.length > 1) {
+          out.add(key);
+        }
+      }
+      return out;
+    },
+  };
+}
+
+function removeNthFromNonDuplicates(refs: RoleRefMap, tracker: RoleNameTracker) {
+  const duplicates = tracker.getDuplicateKeys();
+  for (const [ref, data] of Object.entries(refs)) {
+    const key = tracker.getKey(data.role, data.name);
+    if (!duplicates.has(key)) {
+      delete refs[ref]?.nth;
+    }
+  }
+}
+
+function compactTree(tree: string): string {
+  const lines = tree.split("\n");
+  const result: string[] = [];
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (line.includes("[ref=")) {
+      result.push(line);
+      continue;
+    }
+    if (line.includes(":") && !line.trimEnd().endsWith(":")) {
+      result.push(line);
+      continue;
+    }
+
+    const currentIndent = getIndentLevel(line);
+    let hasRelevantChildren = false;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const childIndent = getIndentLevel(lines[j]!);
+      if (childIndent <= currentIndent) {
+        break;
+      }
+      if (lines[j]?.includes("[ref=")) {
+        hasRelevantChildren = true;
+        break;
+      }
+    }
+    if (hasRelevantChildren) {
+      result.push(line);
+    }
+  }
+
+  return result.join("\n");
+}
+
+function matchInteractiveSnapshotLine(
+  line: string,
+  options: RoleSnapshotOptions,
+): { roleRaw: string; role: string; name?: string; suffix: string } | null {
+  const depth = getIndentLevel(line);
+  if (options.maxDepth !== undefined && depth > options.maxDepth) {
+    return null;
+  }
+  const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+  if (!match) {
+    return null;
+  }
+  const [, , roleRaw, name, suffix] = match;
+  if (roleRaw!.startsWith("/")) {
+    return null;
+  }
+  const role = roleRaw!.toLowerCase();
+  return {
+    roleRaw: roleRaw!,
+    role,
+    ...(name ? { name } : {}),
+    suffix: suffix!,
+  };
+}
+
+function processLine(
+  line: string,
+  refs: RoleRefMap,
+  options: RoleSnapshotOptions,
+  tracker: RoleNameTracker,
+  nextRef: () => string,
+): string | null {
+  const depth = getIndentLevel(line);
+  if (options.maxDepth !== undefined && depth > options.maxDepth) {
+    return null;
+  }
+
+  const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+  if (!match) {
+    return options.interactive ? null : line;
+  }
+
+  const [, prefix, roleRaw, name, suffix] = match;
+  if (roleRaw!.startsWith("/")) {
+    return options.interactive ? null : line;
+  }
+
+  const role = roleRaw!.toLowerCase();
+  const isInteractive = INTERACTIVE_ROLES.has(role);
+  const isContent = CONTENT_ROLES.has(role);
+  const isStructural = STRUCTURAL_ROLES.has(role);
+
+  if (options.interactive && !isInteractive) {
+    return null;
+  }
+  if (options.compact && isStructural && !name) {
+    return null;
+  }
+
+  const shouldHaveRef = isInteractive || (isContent && !!name);
+  if (!shouldHaveRef) {
+    return line;
+  }
+
+  const ref = nextRef();
+  const nth = tracker.getNextIndex(role, name);
+  tracker.trackRef(role, name, ref);
+  refs[ref] = { role, name, nth };
+
+  let enhanced = `${prefix}${roleRaw}`;
+  if (name) {
+    enhanced += ` "${name}"`;
+  }
+  enhanced += ` [ref=${ref}]`;
+  if (nth > 0) {
+    enhanced += ` [nth=${nth}]`;
+  }
+  if (suffix) {
+    enhanced += suffix;
+  }
+  return enhanced;
+}
+
+// ── Public API ────────────────────────────────────────────────────────
+
+/**
+ * Build a role-ref snapshot from Playwright's ariaSnapshot() output.
+ * This is the core transform: raw ARIA tree text -> annotated tree + ref map.
+ */
+export function buildRoleSnapshotFromAriaSnapshot(
+  ariaSnapshot: string,
+  options: RoleSnapshotOptions = {},
+): { snapshot: string; refs: RoleRefMap } {
+  const lines = ariaSnapshot.split("\n");
+  const refs: RoleRefMap = {};
+  const tracker = createRoleNameTracker();
+
+  let counter = 0;
+  const nextRef = () => {
+    counter += 1;
+    return `e${counter}`;
+  };
+
+  if (options.interactive) {
+    const result: string[] = [];
+    for (const line of lines) {
+      const parsed = matchInteractiveSnapshotLine(line, options);
+      if (!parsed) {
+        continue;
+      }
+      const { roleRaw, role, name, suffix } = parsed;
+      if (!INTERACTIVE_ROLES.has(role)) {
+        continue;
+      }
+
+      const ref = nextRef();
+      const nth = tracker.getNextIndex(role, name);
+      tracker.trackRef(role, name, ref);
+      refs[ref] = { role, name, nth };
+
+      let enhanced = `- ${roleRaw}`;
+      if (name) {
+        enhanced += ` "${name}"`;
+      }
+      enhanced += ` [ref=${ref}]`;
+      if (nth > 0) {
+        enhanced += ` [nth=${nth}]`;
+      }
+      if (suffix.includes("[")) {
+        enhanced += suffix;
+      }
+      result.push(enhanced);
+    }
+
+    removeNthFromNonDuplicates(refs, tracker);
+
+    return {
+      snapshot: result.join("\n") || "(no interactive elements)",
+      refs,
+    };
+  }
+
+  const result: string[] = [];
+  for (const line of lines) {
+    const processed = processLine(line, refs, options, tracker, nextRef);
+    if (processed !== null) {
+      result.push(processed);
+    }
+  }
+
+  removeNthFromNonDuplicates(refs, tracker);
+
+  const tree = result.join("\n") || "(empty)";
+  return {
+    snapshot: options.compact ? compactTree(tree) : tree,
+    refs,
+  };
+}
+
+/**
+ * Take a role-based accessibility snapshot of a page.
+ * Uses Playwright's built-in ariaSnapshot() on the :root locator,
+ * then annotates elements with [ref=eN] markers.
+ */
+export async function snapshotPage(
+  page: PwPage,
+  options?: RoleSnapshotOptions,
+): Promise<SnapshotResult> {
+  const locator = page.locator(":root");
+  const ariaSnapshot = await locator.ariaSnapshot();
+  const built = buildRoleSnapshotFromAriaSnapshot(String(ariaSnapshot ?? ""), options);
+  const stats = getRoleSnapshotStats(built.snapshot, built.refs);
+  return {
+    snapshot: built.snapshot,
+    refs: built.refs,
+    stats,
+    url: page.url(),
+    title: await page.title(),
+  };
+}
+
+/**
+ * Navigate a page to a URL.
+ */
+export async function navigatePage(
+  page: PwPage,
+  url: string,
+  timeoutMs?: number,
+): Promise<{ url: string }> {
+  const target = String(url ?? "").trim();
+  if (!target) {
+    throw new Error("url is required");
+  }
+  await page.goto(target, {
+    timeout: Math.max(1000, Math.min(120_000, timeoutMs ?? 20_000)),
+    waitUntil: "domcontentloaded",
+  });
+  return { url: page.url() };
+}

package/src/definitions/browser/pw-state.ts

@@ -0,0 +1,101 @@
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
+
+/**
+ * Cookie and storage management.
+ * Ported from OpenClaw's pw-tools-core.state.ts + pw-tools-core.storage.ts.
+ */
+
+import type { PwBrowserContext, PwCookie, PwPage } from "./types.js";
+
+// ── Cookies ───────────────────────────────────────────────────────────
+
+export async function cookiesGet(context: PwBrowserContext): Promise<{ cookies: PwCookie[] }> {
+  const cookies = await context.cookies();
+  return { cookies };
+}
+
+export async function cookiesSet(
+  context: PwBrowserContext,
+  cookies: Array<{
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+  }>,
+): Promise<void> {
+  if (!cookies.length) {
+    throw new Error("cookies are required");
+  }
+  for (const cookie of cookies) {
+    if (!cookie.name || cookie.value === undefined) {
+      throw new Error("cookie name and value are required");
+    }
+    if (!cookie.domain) {
+      throw new Error("cookie domain is required");
+    }
+  }
+  await context.addCookies(
+    cookies.map((c) => ({
+      name: c.name,
+      value: c.value,
+      domain: c.domain,
+      path: c.path ?? "/",
+    })),
+  );
+}
+
+export async function cookiesClear(context: PwBrowserContext): Promise<void> {
+  await context.clearCookies();
+}
+
+// ── Storage ───────────────────────────────────────────────────────────
+// String-form evaluate is used to avoid TypeScript signature conflicts
+// with the minimal PwPage interface.
+
+type StorageKind = "local" | "session";
+
+export async function storageGet(
+  page: PwPage,
+  kind: StorageKind,
+  key?: string,
+): Promise<{ values: Record<string, string> }> {
+  const script = key
+    ? `(function() {
+        var store = ${kind === "session" ? "window.sessionStorage" : "window.localStorage"};
+        var value = store.getItem(${JSON.stringify(key)});
+        return value === null ? {} : { ${JSON.stringify(key)}: value };
+      })()`
+    : `(function() {
+        var store = ${kind === "session" ? "window.sessionStorage" : "window.localStorage"};
+        var out = {};
+        for (var i = 0; i < store.length; i++) {
+          var k = store.key(i);
+          if (!k) continue;
+          var v = store.getItem(k);
+          if (v !== null) out[k] = v;
+        }
+        return out;
+      })()`;
+  const values = (await page.evaluate(script)) as Record<string, string>;
+  return { values: values ?? {} };
+}
+
+export async function storageSet(
+  page: PwPage,
+  kind: StorageKind,
+  key: string,
+  value: string,
+): Promise<void> {
+  if (!key) {
+    throw new Error("key is required");
+  }
+  const storeName = kind === "session" ? "window.sessionStorage" : "window.localStorage";
+  await page.evaluate(`${storeName}.setItem(${JSON.stringify(key)}, ${JSON.stringify(value)})`);
+}
+
+export async function storageClear(page: PwPage, kind: StorageKind): Promise<void> {
+  const storeName = kind === "session" ? "window.sessionStorage" : "window.localStorage";
+  await page.evaluate(`${storeName}.clear()`);
+}

package/src/definitions/browser/types.ts

@@ -0,0 +1,203 @@
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
+
+/**
+ * Shared browser tool types.
+ *
+ * Playwright types are referenced dynamically (the `playwright` package is an
+ * optional peer dependency loaded via `await import("playwright")`).
+ */
+
+// ── Playwright stand-in types ─────────────────────────────────────────
+// We avoid a static import of playwright so the tool module can load even
+// when the package is not installed. These narrow interfaces cover only
+// the subset our code actually touches.
+
+/** Minimal Browser interface (matches Playwright's Browser). */
+export interface PwBrowser {
+  close(): Promise<void>;
+  contexts(): PwBrowserContext[];
+  isConnected(): boolean;
+}
+
+/** Minimal BrowserContext interface. */
+export interface PwBrowserContext {
+  pages(): PwPage[];
+  newPage(): Promise<PwPage>;
+  cookies(urls?: string | string[]): Promise<PwCookie[]>;
+  addCookies(cookies: PwCookie[]): Promise<void>;
+  clearCookies(): Promise<void>;
+  setOffline(offline: boolean): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Minimal Page interface. */
+export interface PwPage {
+  goto(
+    url: string,
+    options?: {
+      timeout?: number;
+      waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    },
+  ): Promise<unknown>;
+  url(): string;
+  title(): Promise<string>;
+  close(): Promise<void>;
+  content(): Promise<string>;
+  setViewportSize(size: { width: number; height: number }): Promise<void>;
+  screenshot(options?: { type?: "png" | "jpeg"; fullPage?: boolean }): Promise<Buffer>;
+  evaluate<T>(fn: string | ((...args: unknown[]) => T), arg?: unknown): Promise<T>;
+  locator(selector: string): PwLocator;
+  getByRole(role: string, options?: { name?: string; exact?: boolean }): PwLocator;
+  keyboard: { press(key: string, options?: { delay?: number }): Promise<void> };
+  mouse: {
+    wheel(deltaX: number, deltaY: number): Promise<void>;
+  };
+  waitForTimeout(timeout: number): Promise<void>;
+  waitForSelector(
+    selector: string,
+    options?: { timeout?: number; state?: string },
+  ): Promise<unknown>;
+  waitForLoadState(state?: string, options?: { timeout?: number }): Promise<void>;
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  off(event: string, handler: (...args: unknown[]) => void): void;
+  isClosed(): boolean;
+  frameLocator(selector: string): PwFrameLocator;
+}
+
+export interface PwFrameLocator {
+  locator(selector: string): PwLocator;
+  getByRole(role: string, options?: { name?: string; exact?: boolean }): PwLocator;
+}
+
+export interface PwLocator {
+  click(options?: { timeout?: number; button?: string; modifiers?: string[] }): Promise<void>;
+  dblclick(options?: { timeout?: number; button?: string; modifiers?: string[] }): Promise<void>;
+  fill(value: string, options?: { timeout?: number }): Promise<void>;
+  type(text: string, options?: { timeout?: number; delay?: number }): Promise<void>;
+  press(key: string, options?: { timeout?: number }): Promise<void>;
+  hover(options?: { timeout?: number }): Promise<void>;
+  selectOption(values: string | string[], options?: { timeout?: number }): Promise<string[]>;
+  dragTo(target: PwLocator, options?: { timeout?: number }): Promise<void>;
+  setInputFiles(files: string | string[]): Promise<void>;
+  highlight(): Promise<void>;
+  screenshot(options?: { type?: "png" | "jpeg" }): Promise<Buffer>;
+  scrollIntoViewIfNeeded(options?: { timeout?: number }): Promise<void>;
+  boundingBox(): Promise<{ x: number; y: number; width: number; height: number } | null>;
+  elementHandle(): Promise<PwElementHandle | null>;
+  nth(index: number): PwLocator;
+  first(): PwLocator;
+  waitFor(options?: { state?: string; timeout?: number }): Promise<void>;
+  ariaSnapshot(): Promise<string>;
+  setChecked(checked: boolean, options?: { timeout?: number }): Promise<void>;
+}
+
+export interface PwElementHandle {
+  evaluate<T>(fn: (el: Element, ...args: unknown[]) => T, ...args: unknown[]): Promise<T>;
+}
+
+export interface PwCookie {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  url?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Lax" | "None" | "Strict";
+}
+
+// ── ARIA browser types ────────────────────────────────────────────────
+
+export interface BrowserSession {
+  browser: PwBrowser;
+  context: PwBrowserContext;
+  page: PwPage;
+}
+
+export interface RoleRef {
+  role: string;
+  name?: string;
+  /** Index used only when role+name duplicates exist. */
+  nth?: number;
+}
+
+export type RoleRefMap = Record<string, RoleRef>;
+
+export interface RoleSnapshotStats {
+  lines: number;
+  chars: number;
+  refs: number;
+  interactive: number;
+}
+
+export interface SnapshotResult {
+  /** Text representation of accessibility tree */
+  snapshot: string;
+  refs: RoleRefMap;
+  stats: RoleSnapshotStats;
+  url: string;
+  title: string;
+}
+
+export interface BrowserConsoleMessage {
+  type: string;
+  text: string;
+  timestamp: string;
+}
+
+export interface BrowserNetworkRequest {
+  id: string;
+  timestamp: string;
+  method: string;
+  url: string;
+  status?: number;
+  resourceType?: string;
+  ok?: boolean;
+  failureText?: string;
+}
+
+export interface BrowserPageError {
+  message: string;
+  name?: string;
+  timestamp: string;
+}
+
+// ── Action union ──────────────────────────────────────────────────────
+
+export type BrowserAction =
+  | { action: "launch"; url?: string; headless?: boolean }
+  | { action: "close" }
+  | { action: "navigate"; url: string }
+  | { action: "snapshot"; interactive?: boolean }
+  | {
+      action: "click";
+      ref: string;
+      button?: "left" | "right" | "middle";
+      modifiers?: string[];
+      doubleClick?: boolean;
+    }
+  | { action: "type"; ref: string; text: string; submit?: boolean; slowly?: boolean }
+  | { action: "hover"; ref: string }
+  | { action: "drag"; startRef: string; endRef: string }
+  | { action: "select_option"; ref: string; values: string[] }
+  | { action: "press_key"; key: string }
+  | { action: "scroll"; direction: "up" | "down"; amount?: number }
+  | { action: "evaluate"; script: string }
+  | { action: "screenshot" }
+  | { action: "get_console"; level?: string }
+  | { action: "get_network"; filter?: string }
+  | { action: "wait"; selector?: string; text?: string; timeout?: number }
+  | { action: "tab_list" }
+  | { action: "tab_new"; url?: string }
+  | { action: "tab_select"; index: number }
+  | { action: "tab_close"; index?: number }
+  | { action: "cookies_get"; url?: string }
+  | {
+      action: "cookies_set";
+      cookies: Array<{ name: string; value: string; domain: string; path?: string }>;
+    }
+  | { action: "cookies_clear" }
+  | { action: "upload"; ref: string; paths: string[] };