opengstack 0.13.7 → 0.13.9

package/skills/browse/src/snapshot.ts

@@ -0,0 +1,407 @@
+/**
+ * Snapshot command — accessibility tree with ref-based element selection
+ *
+ * Architecture (Locator map — no DOM mutation):
+ *   1. page.locator(scope).ariaSnapshot() → YAML-like accessibility tree
+ *   2. Parse tree, assign refs @e1, @e2, ...
+ *   3. Build Playwright Locator for each ref (getByRole + nth)
+ *   4. Store Map<string, Locator> on BrowserManager
+ *   5. Return compact text output with refs prepended
+ *
+ * Extended features:
+ *   --diff / -D:       Compare against last snapshot, return unified diff
+ *   --annotate / -a:   Screenshot with overlay boxes at each @ref
+ *   --output / -o:     Output path for annotated screenshot
+ *   -C / --cursor-interactive: Scan for cursor:pointer/onclick/tabindex elements
+ *
+ * Later: "click @e3" → look up Locator → locator.click()
+ */
+
+import type { Page, Frame, Locator } from 'playwright';
+import type { BrowserManager, RefEntry } from './browser-manager';
+import * as Diff from 'diff';
+import { TEMP_DIR, isPathWithin } from './platform';
+
+// Roles considered "interactive" for the -i flag
+const INTERACTIVE_ROLES = new Set([
+  'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
+  'listbox', 'menuitem', 'menuitemcheckbox', 'menuitemradio',
+  'option', 'searchbox', 'slider', 'spinbutton', 'switch', 'tab',
+  'treeitem',
+]);
+
+interface SnapshotOptions {
+  interactive?: boolean;       // -i: only interactive elements
+  compact?: boolean;           // -c: remove empty structural elements
+  depth?: number;              // -d N: limit tree depth
+  selector?: string;           // -s SEL: scope to CSS selector
+  diff?: boolean;              // -D / --diff: diff against last snapshot
+  annotate?: boolean;          // -a / --annotate: annotated screenshot
+  outputPath?: string;         // -o / --output: path for annotated screenshot
+  cursorInteractive?: boolean; // -C / --cursor-interactive: scan cursor:pointer etc.
+}
+
+/**
+ * Snapshot flag metadata — single source of truth for CLI parsing and doc generation.
+ *
+ * Imported by:
+ *   - gen-skill-docs.ts (generates {{SNAPSHOT_FLAGS}} tables)
+ *   - skill-parser.ts (validates flags in SKILL.md examples)
+ */
+export const SNAPSHOT_FLAGS: Array<{
+  short: string;
+  long: string;
+  description: string;
+  takesValue?: boolean;
+  valueHint?: string;
+  optionKey: keyof SnapshotOptions;
+}> = [
+  { short: '-i', long: '--interactive', description: 'Interactive elements only (buttons, links, inputs) with @e refs', optionKey: 'interactive' },
+  { short: '-c', long: '--compact', description: 'Compact (no empty structural nodes)', optionKey: 'compact' },
+  { short: '-d', long: '--depth', description: 'Limit tree depth (0 = root only, default: unlimited)', takesValue: true, valueHint: '<N>', optionKey: 'depth' },
+  { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, valueHint: '<sel>', optionKey: 'selector' },
+  { short: '-D', long: '--diff', description: 'Unified diff against previous snapshot (first call stores baseline)', optionKey: 'diff' },
+  { short: '-a', long: '--annotate', description: 'Annotated screenshot with red overlay boxes and ref labels', optionKey: 'annotate' },
+  { short: '-o', long: '--output', description: 'Output path for annotated screenshot (default: <temp>/browse-annotated.png)', takesValue: true, valueHint: '<path>', optionKey: 'outputPath' },
+  { short: '-C', long: '--cursor-interactive', description: 'Cursor-interactive elements (@c refs — divs with pointer, onclick)', optionKey: 'cursorInteractive' },
+];
+
+interface ParsedNode {
+  indent: number;
+  role: string;
+  name: string | null;
+  props: string;      // e.g., "[level=1]"
+  children: string;   // inline text content after ":"
+  rawLine: string;
+}
+
+/**
+ * Parse CLI args into SnapshotOptions — driven by SNAPSHOT_FLAGS metadata.
+ */
+export function parseSnapshotArgs(args: string[]): SnapshotOptions {
+  const opts: SnapshotOptions = {};
+  for (let i = 0; i < args.length; i++) {
+    const flag = SNAPSHOT_FLAGS.find(f => f.short === args[i] || f.long === args[i]);
+    if (!flag) throw new Error(`Unknown snapshot flag: ${args[i]}`);
+    if (flag.takesValue) {
+      const value = args[++i];
+      if (!value) throw new Error(`Usage: snapshot ${flag.short} <value>`);
+      if (flag.optionKey === 'depth') {
+        (opts as any)[flag.optionKey] = parseInt(value, 10);
+        if (isNaN(opts.depth!)) throw new Error('Usage: snapshot -d <number>');
+      } else {
+        (opts as any)[flag.optionKey] = value;
+      }
+    } else {
+      (opts as any)[flag.optionKey] = true;
+    }
+  }
+  return opts;
+}
+
+/**
+ * Parse one line of ariaSnapshot output.
+ *
+ * Format examples:
+ *   - heading "Test" [level=1]
+ *   - link "Link A":
+ *     - /url: /a
+ *   - textbox "Name"
+ *   - paragraph: Some text
+ *   - combobox "Role":
+ */
+function parseLine(line: string): ParsedNode | null {
+  // Match: (indent)(- )(role)( "name")?( [props])?(: inline)?
+  const match = line.match(/^(\s*)-\s+(\w+)(?:\s+"([^"]*)")?(?:\s+(\[.*?\]))?\s*(?::\s*(.*))?$/);
+  if (!match) {
+    // Skip metadata lines like "- /url: /a"
+    return null;
+  }
+  return {
+    indent: match[1].length,
+    role: match[2],
+    name: match[3] ?? null,
+    props: match[4] || '',
+    children: match[5]?.trim() || '',
+    rawLine: line,
+  };
+}
+
+/**
+ * Take an accessibility snapshot and build the ref map.
+ */
+export async function handleSnapshot(
+  args: string[],
+  bm: BrowserManager
+): Promise<string> {
+  const opts = parseSnapshotArgs(args);
+  const page = bm.getPage();
+  // Frame-aware target for accessibility tree
+  const target = bm.getActiveFrameOrPage();
+  const inFrame = bm.getFrame() !== null;
+
+  // Get accessibility tree via ariaSnapshot
+  let rootLocator: Locator;
+  if (opts.selector) {
+    rootLocator = target.locator(opts.selector);
+    const count = await rootLocator.count();
+    if (count === 0) throw new Error(`Selector not found: ${opts.selector}`);
+  } else {
+    rootLocator = target.locator('body');
+  }
+
+  const ariaText = await rootLocator.ariaSnapshot();
+  if (!ariaText || ariaText.trim().length === 0) {
+    bm.setRefMap(new Map());
+    return '(no accessible elements found)';
+  }
+
+  // Parse the ariaSnapshot output
+  const lines = ariaText.split('\n');
+  const refMap = new Map<string, RefEntry>();
+  const output: string[] = [];
+  let refCounter = 1;
+
+  // Track role+name occurrences for nth() disambiguation
+  const roleNameCounts = new Map<string, number>();
+  const roleNameSeen = new Map<string, number>();
+
+  // First pass: count role+name pairs for disambiguation
+  for (const line of lines) {
+    const node = parseLine(line);
+    if (!node) continue;
+    const key = `${node.role}:${node.name || ''}`;
+    roleNameCounts.set(key, (roleNameCounts.get(key) || 0) + 1);
+  }
+
+  // Second pass: assign refs and build locators
+  for (const line of lines) {
+    const node = parseLine(line);
+    if (!node) continue;
+
+    const depth = Math.floor(node.indent / 2);
+    const isInteractive = INTERACTIVE_ROLES.has(node.role);
+
+    // Depth filter
+    if (opts.depth !== undefined && depth > opts.depth) continue;
+
+    // Interactive filter: skip non-interactive but still count for locator indices
+    if (opts.interactive && !isInteractive) {
+      // Still track for nth() counts
+      const key = `${node.role}:${node.name || ''}`;
+      roleNameSeen.set(key, (roleNameSeen.get(key) || 0) + 1);
+      continue;
+    }
+
+    // Compact filter: skip elements with no name and no inline content that aren't interactive
+    if (opts.compact && !isInteractive && !node.name && !node.children) continue;
+
+    // Assign ref
+    const ref = `e${refCounter++}`;
+    const indent = '  '.repeat(depth);
+
+    // Build Playwright locator
+    const key = `${node.role}:${node.name || ''}`;
+    const seenIndex = roleNameSeen.get(key) || 0;
+    roleNameSeen.set(key, seenIndex + 1);
+    const totalCount = roleNameCounts.get(key) || 1;
+
+    let locator: Locator;
+    if (opts.selector) {
+      locator = target.locator(opts.selector).getByRole(node.role as any, {
+        name: node.name || undefined,
+      });
+    } else {
+      locator = target.getByRole(node.role as any, {
+        name: node.name || undefined,
+      });
+    }
+
+    // Disambiguate with nth() if multiple elements share role+name
+    if (totalCount > 1) {
+      locator = locator.nth(seenIndex);
+    }
+
+    refMap.set(ref, { locator, role: node.role, name: node.name || '' });
+
+    // Format output line
+    let outputLine = `${indent}@${ref} [${node.role}]`;
+    if (node.name) outputLine += ` "${node.name}"`;
+    if (node.props) outputLine += ` ${node.props}`;
+    if (node.children) outputLine += `: ${node.children}`;
+
+    output.push(outputLine);
+  }
+
+  // ─── Cursor-interactive scan (-C) ─────────────────────────
+  if (opts.cursorInteractive) {
+    try {
+      const cursorElements = await target.evaluate(() => {
+        const STANDARD_INTERACTIVE = new Set([
+          'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY', 'DETAILS',
+        ]);
+
+        const results: Array<{ selector: string; text: string; reason: string }> = [];
+        const allElements = document.querySelectorAll('*');
+
+        for (const el of allElements) {
+          // Skip standard interactive elements (already in ARIA tree)
+          if (STANDARD_INTERACTIVE.has(el.tagName)) continue;
+          // Skip hidden elements
+          if (!(el as HTMLElement).offsetParent && el.tagName !== 'BODY') continue;
+
+          const style = getComputedStyle(el);
+          const hasCursorPointer = style.cursor === 'pointer';
+          const hasOnclick = el.hasAttribute('onclick');
+          const hasTabindex = el.hasAttribute('tabindex') && parseInt(el.getAttribute('tabindex')!, 10) >= 0;
+          const hasRole = el.hasAttribute('role');
+
+          if (!hasCursorPointer && !hasOnclick && !hasTabindex) continue;
+          // Skip if it has an ARIA role (likely already captured)
+          if (hasRole) continue;
+
+          // Build deterministic nth-child CSS path
+          const parts: string[] = [];
+          let current: Element | null = el;
+          while (current && current !== document.documentElement) {
+            const parent = current.parentElement;
+            if (!parent) break;
+            const siblings = [...parent.children];
+            const index = siblings.indexOf(current) + 1;
+            parts.unshift(`${current.tagName.toLowerCase()}:nth-child(${index})`);
+            current = parent;
+          }
+          const selector = parts.join(' > ');
+
+          const text = (el as HTMLElement).innerText?.trim().slice(0, 80) || el.tagName.toLowerCase();
+          const reasons: string[] = [];
+          if (hasCursorPointer) reasons.push('cursor:pointer');
+          if (hasOnclick) reasons.push('onclick');
+          if (hasTabindex) reasons.push(`tabindex=${el.getAttribute('tabindex')}`);
+
+          results.push({ selector, text, reason: reasons.join(', ') });
+        }
+        return results;
+      });
+
+      if (cursorElements.length > 0) {
+        output.push('');
+        output.push('── cursor-interactive (not in ARIA tree) ──');
+        let cRefCounter = 1;
+        for (const elem of cursorElements) {
+          const ref = `c${cRefCounter++}`;
+          const locator = target.locator(elem.selector);
+          refMap.set(ref, { locator, role: 'cursor-interactive', name: elem.text });
+          output.push(`@${ref} [${elem.reason}] "${elem.text}"`);
+        }
+      }
+    } catch {
+      output.push('');
+      output.push('(cursor scan failed — CSP restriction)');
+    }
+  }
+
+  // Store ref map on BrowserManager
+  bm.setRefMap(refMap);
+
+  if (output.length === 0) {
+    return '(no interactive elements found)';
+  }
+
+  const snapshotText = output.join('\n');
+
+  // ─── Annotated screenshot (-a) ────────────────────────────
+  if (opts.annotate) {
+    const screenshotPath = opts.outputPath || `${TEMP_DIR}/browse-annotated.png`;
+    // Validate output path (consistent with screenshot/pdf/responsive)
+    const resolvedPath = require('path').resolve(screenshotPath);
+    const safeDirs = [TEMP_DIR, process.cwd()];
+    if (!safeDirs.some((dir: string) => isPathWithin(resolvedPath, dir))) {
+      throw new Error(`Path must be within: ${safeDirs.join(', ')}`);
+    }
+    try {
+      // Inject overlay divs at each ref's bounding box
+      const boxes: Array<{ ref: string; box: { x: number; y: number; width: number; height: number } }> = [];
+      for (const [ref, entry] of refMap) {
+        try {
+          const box = await entry.locator.boundingBox({ timeout: 1000 });
+          if (box) {
+            boxes.push({ ref: `@${ref}`, box });
+          }
+        } catch {
+          // Element may be offscreen or hidden — skip
+        }
+      }
+
+      await page.evaluate((boxes) => {
+        for (const { ref, box } of boxes) {
+          const overlay = document.createElement('div');
+          overlay.className = '__browse_annotation__';
+          overlay.style.cssText = `
+            position: absolute; top: ${box.y}px; left: ${box.x}px;
+            width: ${box.width}px; height: ${box.height}px;
+            border: 2px solid red; background: rgba(255,0,0,0.1);
+            pointer-events: none; z-index: 99999;
+            font-size: 10px; color: red; font-weight: bold;
+          `;
+          const label = document.createElement('span');
+          label.textContent = ref;
+          label.style.cssText = 'position: absolute; top: -14px; left: 0; background: red; color: white; padding: 0 3px; font-size: 10px;';
+          overlay.appendChild(label);
+          document.body.appendChild(overlay);
+        }
+      }, boxes);
+
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+
+      // Always remove overlays
+      await page.evaluate(() => {
+        document.querySelectorAll('.__browse_annotation__').forEach(el => el.remove());
+      });
+
+      output.push('');
+      output.push(`[annotated screenshot: ${screenshotPath}]`);
+    } catch {
+      // Remove overlays even on screenshot failure
+      try {
+        await page.evaluate(() => {
+          document.querySelectorAll('.__browse_annotation__').forEach(el => el.remove());
+        });
+      } catch {}
+    }
+  }
+
+  // ─── Diff mode (-D) ───────────────────────────────────────
+  if (opts.diff) {
+    const lastSnapshot = bm.getLastSnapshot();
+    if (!lastSnapshot) {
+      bm.setLastSnapshot(snapshotText);
+      return snapshotText + '\n\n(no previous snapshot to diff against — this snapshot stored as baseline)';
+    }
+
+    const changes = Diff.diffLines(lastSnapshot, snapshotText);
+    const diffOutput: string[] = ['--- previous snapshot', '+++ current snapshot', ''];
+
+    for (const part of changes) {
+      const prefix = part.added ? '+' : part.removed ? '-' : ' ';
+      const diffLines = part.value.split('\n').filter(l => l.length > 0);
+      for (const line of diffLines) {
+        diffOutput.push(`${prefix} ${line}`);
+      }
+    }
+
+    bm.setLastSnapshot(snapshotText);
+    return diffOutput.join('\n');
+  }
+
+  // Store for future diffs
+  bm.setLastSnapshot(snapshotText);
+
+  // Add frame context header when operating inside an iframe
+  if (inFrame) {
+    const frameUrl = bm.getFrame()?.url() ?? 'unknown';
+    output.unshift(`[Context: iframe src="${frameUrl}"]`);
+  }
+
+  return output.join('\n');
+}

package/skills/browse/src/url-validation.ts

@@ -0,0 +1,95 @@
+/**
+ * URL validation for navigation commands — blocks dangerous schemes and cloud metadata endpoints.
+ * Localhost and private IPs are allowed (primary use case: QA testing local dev servers).
+ */
+
+const BLOCKED_METADATA_HOSTS = new Set([
+  '169.254.169.254',  // AWS/GCP/Azure instance metadata
+  'fd00::',           // IPv6 unique local (metadata in some cloud setups)
+  'metadata.google.internal', // GCP metadata
+  'metadata.azure.internal',  // Azure IMDS
+]);
+
+/**
+ * Normalize hostname for blocklist comparison:
+ * - Strip trailing dot (DNS fully-qualified notation)
+ * - Strip IPv6 brackets (URL.hostname includes [] for IPv6)
+ * - Resolve hex (0xA9FEA9FE) and decimal (2852039166) IP representations
+ */
+function normalizeHostname(hostname: string): string {
+  // Strip IPv6 brackets
+  let h = hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+  // Strip trailing dot
+  if (h.endsWith('.')) h = h.slice(0, -1);
+  return h;
+}
+
+/**
+ * Check if a hostname resolves to the link-local metadata IP 169.254.169.254.
+ * Catches hex (0xA9FEA9FE), decimal (2852039166), and octal (0251.0376.0251.0376) forms.
+ */
+function isMetadataIp(hostname: string): boolean {
+  // Try to parse as a numeric IP via URL constructor — it normalizes all forms
+  try {
+    const probe = new URL(`http://${hostname}`);
+    const normalized = probe.hostname;
+    if (BLOCKED_METADATA_HOSTS.has(normalized)) return true;
+    // Also check after stripping trailing dot
+    if (normalized.endsWith('.') && BLOCKED_METADATA_HOSTS.has(normalized.slice(0, -1))) return true;
+  } catch {
+    // Not a valid hostname — can't be a metadata IP
+  }
+  return false;
+}
+
+/**
+ * Resolve a hostname to its IP addresses and check if any resolve to blocked metadata IPs.
+ * Mitigates DNS rebinding: even if the hostname looks safe, the resolved IP might not be.
+ */
+async function resolvesToBlockedIp(hostname: string): Promise<boolean> {
+  try {
+    const dns = await import('node:dns');
+    const { resolve4 } = dns.promises;
+    const addresses = await resolve4(hostname);
+    return addresses.some(addr => BLOCKED_METADATA_HOSTS.has(addr));
+  } catch {
+    // DNS resolution failed — not a rebinding risk
+    return false;
+  }
+}
+
+export async function validateNavigationUrl(url: string): Promise<void> {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(
+      `Blocked: scheme "${parsed.protocol}" is not allowed. Only http: and https: URLs are permitted.`
+    );
+  }
+
+  const hostname = normalizeHostname(parsed.hostname.toLowerCase());
+
+  if (BLOCKED_METADATA_HOSTS.has(hostname) || isMetadataIp(hostname)) {
+    throw new Error(
+      `Blocked: ${parsed.hostname} is a cloud metadata endpoint. Access is denied for security.`
+    );
+  }
+
+  // DNS rebinding protection: resolve hostname and check if it points to metadata IPs.
+  // Skip for loopback/private IPs — they can't be DNS-rebinded and the async DNS
+  // resolution adds latency that breaks concurrent E2E tests under load.
+  const isLoopback = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+  const isPrivateNet = /^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)/.test(hostname);
+  if (!isLoopback && !isPrivateNet && await resolvesToBlockedIp(hostname)) {
+    throw new Error(
+      `Blocked: ${parsed.hostname} resolves to a cloud metadata IP. Possible DNS rebinding attack.`
+    );
+  }
+}