explorbot 0.0.1 → 0.0.5

package/src/utils/context-formatter.ts

@@ -0,0 +1,239 @@
+import { basename } from 'node:path';
+import chalk from 'chalk';
+import { compactAriaSnapshot } from './aria.js';
+
+export interface ContextData {
+  url: string;
+  title?: string;
+  headings: {
+    h1?: string;
+    h2?: string;
+    h3?: string;
+    h4?: string;
+  };
+  experience: Array<{ filePath: string; data: any; content: string }>;
+  knowledge: Array<{ filePath: string; url: string; content: string }>;
+  ariaSnapshot: string | null;
+  combinedHtml?: string;
+  research?: string;
+}
+
+function section(title: string): string {
+  return chalk.bold.white(title.toUpperCase());
+}
+
+function indent(text: string): string {
+  return text
+    .split('\n')
+    .map((line) => chalk.gray(`    ${line}`))
+    .join('\n');
+}
+
+export type ContextMode = 'attached' | 'compact' | 'full';
+
+export function formatContextSummary(data: ContextData, mode: ContextMode = 'compact'): string {
+  if (mode === 'full') {
+    return formatContextFull(data);
+  }
+  if (mode === 'attached') {
+    return formatContextAttached(data);
+  }
+  return formatContextCompact(data);
+}
+
+function formatContextAttached(data: ContextData): string {
+  const lines: string[] = [];
+
+  lines.push(section('PAGE') + chalk.gray(' (Auto-attached)'));
+  lines.push(indent(data.url));
+  if (data.title) {
+    lines.push(indent(data.title));
+  }
+  lines.push('');
+
+  const headingLines: string[] = [];
+  if (data.headings.h1) headingLines.push(`H1: ${data.headings.h1}`);
+  if (data.headings.h2) headingLines.push(`H2: ${data.headings.h2}`);
+  if (data.headings.h3) headingLines.push(`H3: ${data.headings.h3}`);
+  if (data.headings.h4) headingLines.push(`H4: ${data.headings.h4}`);
+
+  if (headingLines.length > 0) {
+    lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
+    lines.push(indent(headingLines.join('\n')));
+    lines.push('');
+  }
+
+  if (data.experience.length > 0) {
+    lines.push(section(`EXPERIENCE (${data.experience.length} files)`) + chalk.gray(' (Auto-attached)'));
+    for (const exp of data.experience) {
+      lines.push(indent(`--- ${basename(exp.filePath)} ---`));
+      if (exp.data?.url) {
+        lines.push(indent(`URL: ${exp.data.url}`));
+      }
+      if (exp.content.trim()) {
+        lines.push(indent(exp.content.trim()));
+      }
+    }
+    lines.push('');
+  }
+
+  if (data.knowledge.length > 0) {
+    lines.push(section(`KNOWLEDGE (${data.knowledge.length} files)`) + chalk.gray(' (Auto-attached)'));
+    for (const k of data.knowledge) {
+      lines.push(indent(`--- ${basename(k.filePath)} ---`));
+      lines.push(indent(`Pattern: ${k.url}`));
+      if (k.content.trim()) {
+        lines.push(indent(k.content.trim()));
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push(section('RESEARCH') + chalk.gray(' (Auto-attached)'));
+  if (data.research) {
+    lines.push(indent(data.research));
+  } else {
+    lines.push(indent('(Not available)'));
+  }
+  lines.push('');
+
+  if (data.ariaSnapshot) {
+    lines.push(section('ARIA') + chalk.gray(' (Auto-attached)'));
+    lines.push(indent(data.ariaSnapshot));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatContextCompact(data: ContextData): string {
+  const lines: string[] = [];
+
+  lines.push(section('PAGE') + chalk.gray(' (Auto-attached)'));
+  lines.push(indent(data.url));
+  if (data.title) {
+    lines.push(indent(data.title));
+  }
+  lines.push('');
+
+  const headingLines: string[] = [];
+  if (data.headings.h1) headingLines.push(`H1: ${data.headings.h1}`);
+  if (data.headings.h2) headingLines.push(`H2: ${data.headings.h2}`);
+  if (data.headings.h3) headingLines.push(`H3: ${data.headings.h3}`);
+  if (data.headings.h4) headingLines.push(`H4: ${data.headings.h4}`);
+
+  if (headingLines.length > 0) {
+    lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
+    lines.push(indent(headingLines.join('\n')));
+    lines.push('');
+  }
+
+  if (data.experience.length > 0) {
+    lines.push(section(`EXPERIENCE (${data.experience.length} files)`) + chalk.gray(' (Auto-attached)'));
+    const expFiles = data.experience.map((exp) => basename(exp.filePath)).join('\n');
+    lines.push(indent(expFiles));
+    lines.push('');
+  }
+
+  if (data.knowledge.length > 0) {
+    lines.push(section(`KNOWLEDGE (${data.knowledge.length} files)`) + chalk.gray(' (Auto-attached)'));
+    const knowFiles = data.knowledge.map((k) => `${basename(k.filePath)} → ${k.url}`).join('\n');
+    lines.push(indent(knowFiles));
+    lines.push('');
+  }
+
+  lines.push(section('RESEARCH') + chalk.gray(' (Auto-attached)'));
+  if (data.research) {
+    lines.push(indent('(cached)'));
+  } else {
+    lines.push(indent('(Not available)'));
+  }
+  lines.push('');
+
+  const ariaSummary = compactAriaSnapshot(data.ariaSnapshot, false);
+  if (ariaSummary) {
+    lines.push(section('INTERACTIVE ELEMENTS') + chalk.gray(' (Auto-attached)'));
+    const ariaLines = ariaSummary.split('\n');
+    const display = ariaLines.slice(0, 15);
+    lines.push(indent(display.join('\n')));
+    if (ariaLines.length > 15) {
+      lines.push(indent(`... and ${ariaLines.length - 15} more`));
+    }
+    lines.push('');
+  }
+
+  lines.push(chalk.gray('Commands: /context:aria, /context:html, /context:knowledge, /context:experience'));
+
+  return lines.join('\n');
+}
+
+function formatContextFull(data: ContextData): string {
+  const lines: string[] = [];
+
+  lines.push(section('PAGE') + chalk.gray(' (Auto-attached)'));
+  lines.push(indent(data.url));
+  if (data.title) {
+    lines.push(indent(data.title));
+  }
+  lines.push('');
+
+  const headingLines: string[] = [];
+  if (data.headings.h1) headingLines.push(`H1: ${data.headings.h1}`);
+  if (data.headings.h2) headingLines.push(`H2: ${data.headings.h2}`);
+  if (data.headings.h3) headingLines.push(`H3: ${data.headings.h3}`);
+  if (data.headings.h4) headingLines.push(`H4: ${data.headings.h4}`);
+
+  if (headingLines.length > 0) {
+    lines.push(section('HEADINGS') + chalk.gray(' (Auto-attached)'));
+    lines.push(indent(headingLines.join('\n')));
+    lines.push('');
+  }
+
+  if (data.experience.length > 0) {
+    lines.push(section(`EXPERIENCE (${data.experience.length} files)`) + chalk.gray(' (Auto-attached)'));
+    for (const exp of data.experience) {
+      lines.push(indent(`--- ${basename(exp.filePath)} ---`));
+      if (exp.data?.url) {
+        lines.push(indent(`URL: ${exp.data.url}`));
+      }
+      if (exp.content.trim()) {
+        lines.push(indent(exp.content.trim()));
+      }
+    }
+    lines.push('');
+  }
+
+  if (data.knowledge.length > 0) {
+    lines.push(section(`KNOWLEDGE (${data.knowledge.length} files)`) + chalk.gray(' (Auto-attached)'));
+    for (const k of data.knowledge) {
+      lines.push(indent(`--- ${basename(k.filePath)} ---`));
+      lines.push(indent(`Pattern: ${k.url}`));
+      if (k.content.trim()) {
+        lines.push(indent(k.content.trim()));
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push(section('RESEARCH') + chalk.gray(' (Auto-attached)'));
+  if (data.research) {
+    lines.push(indent(data.research));
+  } else {
+    lines.push(indent('(Not available)'));
+  }
+  lines.push('');
+
+  if (data.ariaSnapshot) {
+    lines.push(section('ARIA') + chalk.gray(' (Auto-attached)'));
+    lines.push(indent(data.ariaSnapshot));
+    lines.push('');
+  }
+
+  if (data.combinedHtml) {
+    lines.push(section('HTML'));
+    lines.push(chalk.gray(data.combinedHtml));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/utils/error-page.ts

@@ -0,0 +1,23 @@
+import type { ActionResult } from '../action-result.js';
+import { isBodyEmpty } from './html.js';
+
+const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
+
+const SMALL_PAGE_THRESHOLD = 500;
+
+export function isErrorPage(actionResult: ActionResult): boolean {
+  const checkFields = [actionResult.title, actionResult.h1, actionResult.h2].filter(Boolean) as string[];
+
+  for (const field of checkFields) {
+    for (const error of HTTP_ERRORS) {
+      if (field.toLowerCase().includes(error.toLowerCase())) return true;
+    }
+  }
+
+  if (!actionResult.html || isBodyEmpty(actionResult.html)) return true;
+
+  const bodyMatch = actionResult.html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+  if (bodyMatch && bodyMatch[1].trim().length < SMALL_PAGE_THRESHOLD) return true;
+
+  return false;
+}

package/src/utils/expandable.ts

@@ -0,0 +1,38 @@
+import { cssToAncestorXPath } from './xpath.ts';
+
+export const EXPANDABLE_ICON_DESCRIPTIONS = [
+  'three horizontal dots (ellipsis/more options)',
+  'three vertical dots (kebab menu)',
+  'chevron pointing down or right',
+  'caret / small triangle arrow',
+  'down arrow or right arrow',
+  'hamburger icon (three horizontal lines)',
+  'plus or minus icon next to a section',
+  'filter / funnel icon',
+  'gear / settings icon that might open a menu',
+  'expand / collapse toggle icon',
+];
+
+const ICON_CLASSES = ['dots', 'chevron', 'ellipsis', 'caret', 'arrow', 'expand', 'collapse', 'hamburger', 'more', 'filter', 'tune'];
+const TRIGGER_CLASSES = ['toggle', 'trigger', 'split', 'popup', 'filter', 'tune'];
+const CONTAINER_CLASSES = ['dropdown-trigger', 'dropdown-toggle', 'popover-trigger', 'menu-trigger'];
+const CLICKABLE = `@role='button' or self::button or self::a or @tabindex`;
+const cc = (classes: string[]) => classes.map((c) => `contains(@class,'${c}')`).join(' or ');
+
+export const EXPANDABLE_XPATHS = ['//*[@aria-haspopup or @aria-expanded]', `//*[(${CLICKABLE}) and .//*[${cc(ICON_CLASSES)}]]`, `//*[${cc(CONTAINER_CLASSES)}]`, `//*[(${CLICKABLE}) and (${cc(TRIGGER_CLASSES)})]`];
+
+export function buildExpandableXPath(excludeContainers: string[] = []): string {
+  const exclusions = excludeContainers.map((css) => cssToAncestorXPath(css)).filter(Boolean);
+  const predicate = exclusions.length > 0 ? `[not(ancestor::*[${exclusions.join(' or ')}])]` : '';
+  return EXPANDABLE_XPATHS.map((x) => `(${x}${predicate})`).join(' | ');
+}
+
+export function buildExpandableXPathInsideContainers(containers: string[]): string[] {
+  return containers
+    .map((css) => {
+      const pred = cssToAncestorXPath(css);
+      if (!pred) return null;
+      return EXPANDABLE_XPATHS.map((x) => `(${x}[ancestor::*[${pred}]])`).join(' | ');
+    })
+    .filter((x): x is string => x !== null);
+}

package/src/utils/hooks-runner.ts

@@ -0,0 +1,79 @@
+import type { ExplorbotConfig, Hook, HookConfig } from '../config.ts';
+import type Explorer from '../explorer.ts';
+import { createDebug } from './logger.ts';
+import { matchesUrl } from './url-matcher.ts';
+
+const debugLog = createDebug('explorbot:hooks');
+
+export class HooksRunner {
+  constructor(
+    private explorer: Explorer,
+    private config: ExplorbotConfig
+  ) {}
+
+  async runBeforeHook(agentName: string, url: string): Promise<void> {
+    await this.runHook(agentName, 'beforeHook', url);
+  }
+
+  async runAfterHook(agentName: string, url: string): Promise<void> {
+    await this.runHook(agentName, 'afterHook', url);
+  }
+
+  private async runHook(agentName: string, hookType: 'beforeHook' | 'afterHook', url: string): Promise<void> {
+    const agentConfig = this.config.ai?.agents?.[agentName as keyof typeof this.config.ai.agents];
+    if (!agentConfig) return;
+
+    const hookConfig = agentConfig[hookType];
+    if (!hookConfig) return;
+
+    const hook = this.findMatchingHook(hookConfig, url);
+    if (!hook) return;
+
+    debugLog(`Running ${hookType} for ${agentName} at ${url}`);
+    await this.executeHook(hook, url);
+  }
+
+  private findMatchingHook(config: HookConfig, url: string): Hook | null {
+    if (this.isSingleHook(config)) return config as Hook;
+
+    const urlPath = this.extractPath(url);
+    const entries = Object.entries(config).sort(([a], [b]) => this.patternSpecificity(b) - this.patternSpecificity(a));
+    for (const [pattern, hook] of entries) {
+      if (matchesUrl(pattern, urlPath)) return hook as Hook;
+    }
+    return null;
+  }
+
+  private patternSpecificity(pattern: string): number {
+    if (pattern === '*') return 0;
+    if (pattern.includes('*')) return pattern.length;
+    return pattern.length + 1000;
+  }
+
+  private async executeHook(hook: Hook, url: string): Promise<void> {
+    try {
+      if (hook.type === 'playwright') {
+        const page = this.explorer.playwrightHelper.page;
+        await hook.hook({ page, url });
+      } else {
+        const I = this.explorer.actor;
+        await hook.hook({ I, url });
+      }
+    } catch (error) {
+      debugLog(`Hook error: ${error}`);
+    }
+  }
+
+  private isSingleHook(config: HookConfig): boolean {
+    return 'type' in config && 'hook' in config;
+  }
+
+  private extractPath(url: string): string {
+    if (url.startsWith('/')) return url;
+    try {
+      return new URL(url).pathname;
+    } catch {
+      return url;
+    }
+  }
+}