@aria-cli/tools 1.0.9 → 1.0.11

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

@@ -1,383 +0,0 @@
-// 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

@@ -1,101 +0,0 @@
-// 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

@@ -1,203 +0,0 @@
-// 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[] };