explorbot 0.0.1 → 0.1.0

package/src/utils/aria.ts

@@ -0,0 +1,629 @@
+const INTERACTIVE_ROLES = new Set(
+  [
+    'button',
+    'link',
+    'textbox',
+    'searchbox',
+    'checkbox',
+    'radio',
+    'radiogroup',
+    'switch',
+    'combobox',
+    'listbox',
+    'listitem',
+    'menu',
+    'menubar',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'tab',
+    'tabpanel',
+    'tablist',
+    'slider',
+    'spinbutton',
+    'tree',
+    'treeitem',
+    'grid',
+    'gridcell',
+    'row',
+    'rowheader',
+    'columnheader',
+    'toolbar',
+    'progressbar',
+    'buttonmenu',
+    'comboboxbutton',
+    'gridcellbutton',
+  ].map((role) => role.toLowerCase())
+);
+
+const IGNORED_CONTAINER_ROLES = new Set(['navigation']);
+
+type AriaNode = {
+  role: string;
+  name?: string;
+  value?: string | boolean | null;
+  attributes: Record<string, string | boolean | null>;
+  children: AriaNode[];
+  rawChildren?: AriaNode[];
+};
+
+const serializeChildContent = (node: AriaNode): string => {
+  const children = node.rawChildren || node.children;
+  const parts: string[] = [];
+  for (const child of children) {
+    let part = child.role;
+    if (child.name) part += ` "${child.name}"`;
+    const nested = serializeChildContent(child);
+    if (nested) part += ` > ${nested}`;
+    parts.push(part);
+  }
+  return parts.join(', ');
+};
+
+const buildInteractiveEntry = (node: AriaNode): Record<string, unknown> | null => {
+  if (!INTERACTIVE_ROLES.has(node.role)) {
+    return null;
+  }
+  const entry: Record<string, unknown> = { role: node.role };
+  if (node.name && node.name.trim() !== '') {
+    entry.name = node.name.trim();
+  }
+  if (node.value !== undefined && node.value !== null) {
+    const valueText = `${node.value}`.trim();
+    if (valueText !== '') {
+      entry.value = node.value;
+    }
+  }
+  for (const [key, value] of Object.entries(node.attributes)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (value === '') {
+      continue;
+    }
+    entry[key] = value;
+  }
+  const hasData = Object.keys(entry).some((key) => key !== 'role');
+  const entryName = typeof entry.name === 'string' ? entry.name : '';
+  const hasValue = Object.prototype.hasOwnProperty.call(entry, 'value');
+  const isButtonOrLink = node.role === 'button' || node.role === 'link';
+  let shouldInclude = hasData;
+  if (!shouldInclude && hasValue) {
+    shouldInclude = true;
+  }
+  if (isButtonOrLink && !entryName && !hasValue) {
+    const resolved = resolveDisplayName(node);
+    if (resolved) {
+      entry.name = resolved;
+    } else {
+      entry.unnamed = true;
+    }
+    shouldInclude = true;
+  }
+  if (!shouldInclude) {
+    return null;
+  }
+  return entry;
+};
+
+const normalizeScalar = (input: string): string | boolean | null => {
+  let value = input.trim();
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  }
+  const lower = value.toLowerCase();
+  if (lower === 'true') {
+    return true;
+  }
+  if (lower === 'false') {
+    return false;
+  }
+  if (lower === 'null') {
+    return null;
+  }
+  return value;
+};
+
+const tokenizeAttributes = (input: string): string[] => {
+  const tokens: string[] = [];
+  let current = '';
+  let inQuotes = false;
+  let quoteChar = '';
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    if ((char === '"' || char === "'") && input[i - 1] !== '\\') {
+      if (inQuotes && quoteChar === char) {
+        inQuotes = false;
+        quoteChar = '';
+      } else if (!inQuotes) {
+        inQuotes = true;
+        quoteChar = char;
+      }
+      current += char;
+      continue;
+    }
+    if (!inQuotes && (char === ' ' || char === ',')) {
+      if (current.trim() !== '') {
+        tokens.push(current.trim());
+      }
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim() !== '') {
+    tokens.push(current.trim());
+  }
+  return tokens;
+};
+
+const parseAttributes = (input: string): Record<string, string | boolean | null> => {
+  const attributes: Record<string, string | boolean | null> = {};
+  const tokens = tokenizeAttributes(input);
+  for (const token of tokens) {
+    if (token === '') {
+      continue;
+    }
+    const separatorIndex = token.indexOf('=');
+    if (separatorIndex === -1) {
+      attributes[token.toLowerCase()] = true;
+      continue;
+    }
+    const key = token.slice(0, separatorIndex).trim().toLowerCase();
+    const valueRaw = token.slice(separatorIndex + 1).trim();
+    attributes[key] = normalizeScalar(valueRaw);
+  }
+  return attributes;
+};
+
+const parseHeader = (header: string): { role: string; name?: string; attributes: Record<string, string | boolean | null> } | null => {
+  if (!header) {
+    return null;
+  }
+  let index = 0;
+  const length = header.length;
+  while (index < length && header[index] === ' ') {
+    index += 1;
+  }
+  let roleEnd = index;
+  while (roleEnd < length) {
+    const char = header[roleEnd];
+    if (char === ' ' || char === '[' || char === '"' || char === "'") {
+      break;
+    }
+    roleEnd += 1;
+  }
+  const role = header.slice(index, roleEnd).trim().toLowerCase();
+  if (!role) {
+    return null;
+  }
+  let name: string | undefined;
+  const attributes: Record<string, string | boolean | null> = {};
+  index = roleEnd;
+  while (index < length) {
+    const char = header[index];
+    if (char === ' ') {
+      index += 1;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      const quoteChar = char;
+      index += 1;
+      let value = '';
+      while (index < length) {
+        const currentChar = header[index];
+        if (currentChar === quoteChar && header[index - 1] !== '\\') {
+          index += 1;
+          break;
+        }
+        value += currentChar;
+        index += 1;
+      }
+      if (!name) {
+        name = value;
+      }
+      continue;
+    }
+    if (char === '[') {
+      const end = header.indexOf(']', index);
+      const content = end === -1 ? header.slice(index + 1) : header.slice(index + 1, end);
+      const parsed = parseAttributes(content);
+      for (const [key, value] of Object.entries(parsed)) {
+        attributes[key] = value;
+      }
+      index = end === -1 ? length : end + 1;
+      continue;
+    }
+    break;
+  }
+  return { role, name, attributes };
+};
+
+const splitHeaderValue = (content: string): { header: string; value: string | null } => {
+  let activeQuote: string | null = null;
+  let bracketDepth = 0;
+  for (let i = 0; i < content.length; i += 1) {
+    const char = content[i];
+    if ((char === '"' || char === "'") && content[i - 1] !== '\\') {
+      if (activeQuote === char) {
+        activeQuote = null;
+      } else if (!activeQuote) {
+        activeQuote = char;
+      }
+      continue;
+    }
+    if (!activeQuote) {
+      if (char === '[') {
+        bracketDepth += 1;
+        continue;
+      }
+      if (char === ']') {
+        if (bracketDepth > 0) {
+          bracketDepth -= 1;
+        }
+        continue;
+      }
+      if (char === ':') {
+        if (bracketDepth === 0) {
+          const header = content.slice(0, i).trimEnd();
+          const value = content.slice(i + 1).trimStart();
+          return { header, value: value === '' ? null : value };
+        }
+      }
+    }
+  }
+  return { header: content.trim(), value: null };
+};
+
+const pruneNodes = (nodes: AriaNode[], keepNamed = false): AriaNode[] => {
+  const result: AriaNode[] = [];
+  for (const node of nodes) {
+    const children = pruneNodes(node.children, keepNamed);
+    if (IGNORED_CONTAINER_ROLES.has(node.role)) {
+      result.push(...children);
+      continue;
+    }
+    const interactive = INTERACTIVE_ROLES.has(node.role);
+    if (!interactive && children.length === 0) {
+      if (!keepNamed || (!node.name && node.value === undefined)) {
+        continue;
+      }
+    }
+    result.push({ ...node, children, rawChildren: node.children });
+  }
+  return result;
+};
+
+const parseAriaSnapshot = (snapshot: string | null, keepNamed = false): AriaNode[] => {
+  if (!snapshot) {
+    return [];
+  }
+  const roots: AriaNode[] = [];
+  const stack: Array<{ depth: number; node: AriaNode }> = [];
+  const lines = snapshot.split(/\r?\n/);
+  for (const line of lines) {
+    if (!line.trim()) {
+      continue;
+    }
+    const indentMatch = line.match(/^\s*/);
+    const indent = indentMatch ? indentMatch[0].length : 0;
+    const trimmed = line.slice(indent);
+    if (!trimmed.startsWith('-')) {
+      continue;
+    }
+    const content = trimmed.slice(1).trim();
+    if (content === '') {
+      continue;
+    }
+    const { header, value } = splitHeaderValue(content);
+    const parsedHeader = parseHeader(header);
+    if (!parsedHeader) {
+      continue;
+    }
+    const node: AriaNode = {
+      role: parsedHeader.role,
+      attributes: { ...parsedHeader.attributes },
+      children: [],
+    };
+    if (parsedHeader.name && parsedHeader.name.trim() !== '') {
+      node.name = parsedHeader.name.trim();
+    }
+    if (value !== null) {
+      const normalizedValue = normalizeScalar(value);
+      if (normalizedValue !== '' && normalizedValue !== undefined) {
+        node.value = normalizedValue;
+      }
+    }
+    const depth = Math.floor(indent / 2);
+    while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+      stack.pop();
+    }
+    if (stack.length === 0) {
+      roots.push(node);
+    } else {
+      stack[stack.length - 1].node.children.push(node);
+    }
+    stack.push({ depth, node });
+  }
+  return pruneNodes(roots, keepNamed);
+};
+
+export interface FocusAreaResult {
+  detected: boolean;
+  type: 'dialog' | 'modal' | null;
+  name: string | null;
+}
+
+export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
+  const nodes = parseAriaSnapshot(snapshot);
+
+  const findFocusArea = (nodeList: AriaNode[]): FocusAreaResult | null => {
+    for (const node of nodeList) {
+      if (node.role === 'dialog' || node.role === 'alertdialog') {
+        return {
+          detected: true,
+          type: 'dialog',
+          name: node.name || null,
+        };
+      }
+
+      if (node.attributes.modal === true || node.attributes.modal === 'true') {
+        return {
+          detected: true,
+          type: 'modal',
+          name: node.name || null,
+        };
+      }
+
+      const childResult = findFocusArea(node.children);
+      if (childResult) {
+        return childResult;
+      }
+    }
+    return null;
+  };
+
+  const result = findFocusArea(nodes);
+  return result || { detected: false, type: null, name: null };
+};
+
+export const collectInteractiveNodes = (snapshot: string | null): Array<Record<string, unknown>> => {
+  const nodes = parseAriaSnapshot(snapshot);
+  const result: Array<Record<string, unknown>> = [];
+  const visit = (node: AriaNode) => {
+    if (IGNORED_CONTAINER_ROLES.has(node.role)) {
+      node.children.forEach(visit);
+      return;
+    }
+    const entry = buildInteractiveEntry(node);
+    if (entry) {
+      result.push(entry);
+    }
+    node.children.forEach(visit);
+  };
+  nodes.forEach(visit);
+  return result;
+};
+
+const renderNodeLine = (role: string, name: string | undefined, attrs: Record<string, string | boolean | null>, value: string | boolean | null | undefined): string => {
+  let line = role;
+  const displayName = name?.trim();
+  if (displayName) line += ` "${displayName}"`;
+  const attrStr = Object.entries(attrs)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => (v === true ? k : `${k}=${v}`))
+    .join(' ');
+  if (attrStr) line += ` [${attrStr}]`;
+  if (value !== undefined && value !== null) {
+    const text = `${value}`.trim();
+    if (text) line += `: ${text}`;
+  }
+  return line;
+};
+
+const formatSummary = (node: Record<string, unknown>): string => {
+  const role = typeof node.role === 'string' ? node.role : '';
+  if (!role) return '';
+  const name = typeof node.name === 'string' ? node.name : undefined;
+  const attrs: Record<string, string | boolean | null> = {};
+  for (const key of Object.keys(node)
+    .filter((k) => k !== 'role' && k !== 'name' && k !== 'value')
+    .sort()) {
+    attrs[key] = node[key] as string | boolean | null;
+  }
+  const value = Object.prototype.hasOwnProperty.call(node, 'value') ? (node.value as string | boolean | null) : undefined;
+  return renderNodeLine(role, name, attrs, value);
+};
+
+type FlatInteractiveNode = {
+  path: string;
+  summary: string;
+};
+
+const flattenInteractiveNodes = (snapshot: string | null): FlatInteractiveNode[] => {
+  const nodes = parseAriaSnapshot(snapshot);
+  const result: FlatInteractiveNode[] = [];
+  const visit = (node: AriaNode, path: string) => {
+    if (!IGNORED_CONTAINER_ROLES.has(node.role)) {
+      const entry = buildInteractiveEntry(node);
+      if (entry) {
+        const summary = formatSummary(entry);
+        if (summary !== '') {
+          result.push({ path, summary });
+        }
+      }
+    }
+    node.children.forEach((child, index) => {
+      const childPath = path === '' ? `${index}` : `${path}.${index}`;
+      visit(child, childPath);
+    });
+  };
+  nodes.forEach((node, index) => {
+    visit(node, `${index}`);
+  });
+  return result;
+};
+
+const buildCountMap = (items: string[]): Map<string, number> => {
+  const map = new Map<string, number>();
+  for (const item of items) {
+    if (item === '') {
+      continue;
+    }
+    map.set(item, (map.get(item) ?? 0) + 1);
+  }
+  return map;
+};
+
+const formatDiffItem = (item: string, count: number): string => {
+  if (count > 1) {
+    return `${item} (x${count})`;
+  }
+  return item;
+};
+
+export interface FocusedElementInfo {
+  role: string;
+  name: string;
+  value?: string;
+  attributes?: string[];
+}
+
+export function extractFocusedElement(ariaSnapshot: string | null): FocusedElementInfo | null {
+  if (!ariaSnapshot) return null;
+
+  const focusedMatch = ariaSnapshot.match(/-\s*(\w+)\s+"([^"]*)"([^:\n]*)\[focused\](?::\s*(.*))?/);
+  if (!focusedMatch) return null;
+
+  const [, role, name, attributesStr, value] = focusedMatch;
+
+  const attributes: string[] = [];
+  if (attributesStr) {
+    const attrMatches = attributesStr.matchAll(/\[([^\]]+)\]/g);
+    for (const match of attrMatches) {
+      if (match[1] !== 'focused') {
+        attributes.push(match[1]);
+      }
+    }
+  }
+
+  return {
+    role,
+    name,
+    ...(value && { value: value.trim() }),
+    ...(attributes.length > 0 && { attributes }),
+  };
+}
+
+export function parseAriaLocator(ariaStr: string): { role: string; text: string } | null {
+  const trimmed = ariaStr.trim();
+  if (trimmed === '-' || trimmed === '' || trimmed === '"-"') return null;
+
+  const match = trimmed.match(/\{\s*["']?role["']?\s*:\s*['"]([^'"]+)['"]\s*,\s*["']?text["']?\s*:\s*['"]([^'"]*)['"]\s*\}/);
+  if (!match) return null;
+
+  return { role: match[1], text: match[2] };
+}
+
+export const diffAriaSnapshots = (previous: string | null, current: string | null): string | null => {
+  const previousEntries = flattenInteractiveNodes(previous);
+  const currentEntries = flattenInteractiveNodes(current);
+  const previousTotals = buildCountMap(previousEntries.map((entry) => entry.summary));
+  const currentTotals = buildCountMap(currentEntries.map((entry) => entry.summary));
+  const added: string[] = [];
+  const removed: string[] = [];
+  const allSummaries = new Set<string>([...previousTotals.keys(), ...currentTotals.keys()]);
+  for (const summary of allSummaries) {
+    const before = previousTotals.get(summary) ?? 0;
+    const after = currentTotals.get(summary) ?? 0;
+    if (after > before) {
+      for (let i = 0; i < after - before; i += 1) {
+        added.push(summary);
+      }
+    }
+    if (before > after) {
+      for (let i = 0; i < before - after; i += 1) {
+        removed.push(summary);
+      }
+    }
+  }
+  const previousByPath = new Map<string, string>();
+  for (const entry of previousEntries) {
+    previousByPath.set(entry.path, entry.summary);
+  }
+  const currentByPath = new Map<string, string>();
+  for (const entry of currentEntries) {
+    currentByPath.set(entry.path, entry.summary);
+  }
+  for (const [path, beforeSummary] of previousByPath.entries()) {
+    const afterSummary = currentByPath.get(path);
+    if (!afterSummary || afterSummary === beforeSummary) {
+      continue;
+    }
+    const totalsEqualAfter = (currentTotals.get(afterSummary) ?? 0) === (previousTotals.get(afterSummary) ?? 0);
+    const totalsEqualBefore = (currentTotals.get(beforeSummary) ?? 0) === (previousTotals.get(beforeSummary) ?? 0);
+    if (!totalsEqualAfter || !totalsEqualBefore) {
+      continue;
+    }
+    const beforeExistsElsewhere = currentEntries.some((entry) => entry.path !== path && entry.summary === beforeSummary);
+    const afterExistsElsewhere = previousEntries.some((entry) => entry.path !== path && entry.summary === afterSummary);
+    if (beforeExistsElsewhere && afterExistsElsewhere) {
+      continue;
+    }
+    added.push(afterSummary);
+    removed.push(beforeSummary);
+  }
+  if (added.length === 0 && removed.length === 0) {
+    return null;
+  }
+  const lines: string[] = ['ariaDiff:'];
+  const addedSummary = buildCountMap(added);
+  if (addedSummary.size === 0) {
+    lines.push('  added: []');
+  } else {
+    lines.push('  added:');
+    Array.from(addedSummary.entries())
+      .sort(([a], [b]) => a.localeCompare(b))
+      .forEach(([item, count]) => {
+        lines.push(`    - ${formatDiffItem(item, count)}`);
+      });
+  }
+  if (removed.length === 0) {
+    lines.push('  removed: []');
+  } else {
+    lines.push(`  removed: ${removed.length} interactive elements`);
+  }
+  return lines.join('\n');
+};
+
+const resolveDisplayName = (node: AriaNode): string | undefined => {
+  if (node.name) return node.name;
+  const isButtonOrLink = node.role === 'button' || node.role === 'link';
+  if (!isButtonOrLink) return undefined;
+  const childContent = serializeChildContent(node);
+  if (childContent) return `{${childContent}}`;
+  return undefined;
+};
+
+const serializeAriaNodes = (nodes: AriaNode[], depth = 0): string => {
+  const lines: string[] = [];
+  for (const node of nodes) {
+    const indent = '  '.repeat(depth);
+    let line = `${indent}- ${renderNodeLine(node.role, resolveDisplayName(node), node.attributes, node.value)}`;
+    if (node.children.length > 0) {
+      line += ':';
+    }
+    lines.push(line);
+    if (node.children.length > 0) {
+      lines.push(serializeAriaNodes(node.children, depth + 1));
+    }
+  }
+  return lines.join('\n');
+};
+
+export const compactAriaSnapshot = (snapshot: string | null, keepNamed = false): string => {
+  if (!snapshot) return '';
+  const nodes = parseAriaSnapshot(snapshot, keepNamed);
+  return serializeAriaNodes(nodes);
+};

package/src/utils/cli-name.ts

@@ -0,0 +1,13 @@
+import path from 'node:path';
+
+let cached: string | undefined;
+
+export function getCliName(): string {
+  if (cached) return cached;
+  const ua = process.env.npm_config_user_agent || '';
+  if (ua.includes('bun')) cached = 'bunx explorbot';
+  else if (ua.includes('npm')) cached = 'npx explorbot';
+  else if (process.argv[1]?.endsWith('.ts')) cached = `bun ${path.relative(process.cwd(), process.argv[1])}`;
+  else cached = 'explorbot';
+  return cached;
+}

package/src/utils/code-extractor.ts

@@ -0,0 +1,22 @@
+import { createDebug } from './logger.js';
+
+const debugLog = createDebug('explorbot:code-extractor');
+
+export function extractCodeBlocks(aiResponse: string): string[] {
+  const codeBlockRegex = /```(?:js|javascript)?\s*\n([\s\S]*?)\n```/g;
+  const codeBlocks: string[] = [];
+  let match: RegExpExecArray | null = null;
+
+  while ((match = codeBlockRegex.exec(aiResponse))) {
+    const code = match[1].trim();
+    if (!code) continue;
+    try {
+      new Function('I', code);
+      codeBlocks.push(code);
+    } catch {
+      debugLog('Invalid JavaScript code block skipped:', code);
+    }
+  }
+
+  return codeBlocks;
+}