@browserflow-ai/exploration 0.0.6

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@browserflow-ai/exploration",
+  "version": "0.0.6",
+  "description": "AI exploration engine for BrowserFlow - Human-in-the-Loop E2E Test Generation",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akatz-ai/browserflow.git",
+    "directory": "packages/exploration"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@browserflow-ai/core": "0.0.6",
+    "agent-browser": "^0.5.0"
+  }
+}

package/src/adapters/claude-cli.test.ts

@@ -0,0 +1,134 @@
+// @browserflow-ai/exploration - Claude CLI Adapter tests (with mocks)
+
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+import { ClaudeCliAdapter } from './claude-cli';
+import type { EnhancedSnapshot } from './types';
+
+// Mock child_process spawn
+const mockSpawn = mock(() => {});
+
+describe('ClaudeCliAdapter', () => {
+  let adapter: ClaudeCliAdapter;
+
+  beforeEach(() => {
+    adapter = new ClaudeCliAdapter({ model: 'haiku' });
+  });
+
+  test('has correct name', () => {
+    expect(adapter.name).toBe('claude-cli');
+  });
+
+  test('accepts custom configuration', () => {
+    const customAdapter = new ClaudeCliAdapter({
+      model: 'sonnet',
+      timeout: 60000,
+      cliPath: '/usr/local/bin/claude',
+    });
+    expect(customAdapter.name).toBe('claude-cli');
+  });
+
+  describe('explore', () => {
+    test('returns valid exploration output structure', async () => {
+      const result = await adapter.explore({
+        spec: { name: 'test-spec', steps: [] },
+        specPath: 'specs/test.yaml',
+        baseUrl: 'http://localhost:3001',
+        outputDir: '/tmp/test',
+      });
+
+      expect(result.spec).toBe('test-spec');
+      expect(result.specPath).toBe('specs/test.yaml');
+      expect(result.explorationId).toMatch(/^exp-\d+-[a-z0-9]+$/);
+      expect(result.overallStatus).toBe('completed');
+      expect(result.browser).toBe('chromium');
+      expect(result.viewport).toEqual({ width: 1280, height: 720 });
+    });
+
+    test('uses provided browser and viewport', async () => {
+      const result = await adapter.explore({
+        spec: { name: 'test-spec', steps: [] },
+        specPath: 'specs/test.yaml',
+        baseUrl: 'http://localhost:3001',
+        outputDir: '/tmp/test',
+        browser: 'firefox',
+        viewport: { width: 800, height: 600 },
+      });
+
+      expect(result.browser).toBe('firefox');
+      expect(result.viewport).toEqual({ width: 800, height: 600 });
+    });
+  });
+
+  describe('retryWithFeedback', () => {
+    test('delegates to explore', async () => {
+      const previousExploration = {
+        spec: 'old-spec',
+        specPath: 'specs/old.yaml',
+        explorationId: 'exp-123',
+        timestamp: new Date().toISOString(),
+        durationMs: 1000,
+        browser: 'chromium' as const,
+        viewport: { width: 1280, height: 720 },
+        baseUrl: 'http://localhost:3001',
+        steps: [],
+        outcomeChecks: [],
+        overallStatus: 'completed' as const,
+        errors: [],
+      };
+
+      const result = await adapter.retryWithFeedback({
+        spec: { name: 'retry-spec', steps: [] },
+        specPath: 'specs/retry.yaml',
+        baseUrl: 'http://localhost:3001',
+        outputDir: '/tmp/test',
+        previousExploration,
+        reviewFeedback: {
+          explorationId: 'exp-123',
+          reviewer: 'test',
+          steps: [],
+          verdict: 'rejected',
+        },
+      });
+
+      expect(result.spec).toBe('retry-spec');
+    });
+  });
+
+  describe('parseJsonResponse (via findElement error handling)', () => {
+    // We test JSON parsing indirectly through the error handling path
+    // since parseJsonResponse is private
+
+    test('handles CLI errors gracefully', async () => {
+      // Create adapter with non-existent CLI path to trigger error
+      const badAdapter = new ClaudeCliAdapter({
+        cliPath: '/nonexistent/claude',
+        timeout: 1000,
+      });
+
+      const snapshot: EnhancedSnapshot = {
+        tree: '- button "Add" [ref=e1]',
+        refs: { e1: { role: 'button', name: 'Add' } },
+      };
+
+      const result = await badAdapter.findElement('the Add button', snapshot);
+
+      expect(result.ref).toBe('NOT_FOUND');
+      expect(result.confidence).toBe(0);
+      expect(result.reasoning).toContain('CLI error');
+    });
+  });
+});
+
+describe('ClaudeCliAdapter interface compliance', () => {
+  test('implements AIAdapter interface', () => {
+    const adapter = new ClaudeCliAdapter();
+
+    // Check required properties
+    expect(typeof adapter.name).toBe('string');
+
+    // Check required methods
+    expect(typeof adapter.findElement).toBe('function');
+    expect(typeof adapter.explore).toBe('function');
+    expect(typeof adapter.retryWithFeedback).toBe('function');
+  });
+});

package/src/adapters/claude-cli.ts

@@ -0,0 +1,240 @@
+// @browserflow-ai/exploration - Claude CLI Adapter
+// Uses the `claude` CLI tool instead of the Anthropic SDK
+// This allows users to leverage their existing Claude Code authentication
+
+import { spawn } from 'node:child_process';
+
+// Debug flag - set via BF_DEBUG=1 environment variable
+const DEBUG = process.env.BF_DEBUG === '1';
+
+function debug(...args: unknown[]): void {
+  if (DEBUG) {
+    console.error('[claude-cli]', ...args);
+  }
+}
+import type {
+  AIAdapter,
+  ExploreParams,
+  ExplorationOutput,
+  RetryParams,
+  EnhancedSnapshot,
+  FindElementResult,
+} from './types';
+
+/**
+ * Configuration options for the Claude CLI adapter
+ */
+export interface ClaudeCliAdapterConfig {
+  /** Model to use (default: haiku) */
+  model?: string;
+  /** Path to claude CLI executable (default: 'claude') */
+  cliPath?: string;
+  /** Timeout in milliseconds (default: 30000) */
+  timeout?: number;
+}
+
+/**
+ * System prompt for element finding - embedded in the user prompt
+ */
+const ELEMENT_FINDER_PROMPT = `You are helping find UI elements based on natural language descriptions.
+Given an accessibility snapshot of a web page, identify the element that best matches the user's description.
+
+Rules:
+1. Return the ref (like "e1", "e2") of the matching element
+2. If multiple elements could match, pick the most likely based on context
+3. If no element matches, use ref "NOT_FOUND" with confidence 0
+4. Consider the element's role, name, text content, and position in the hierarchy
+5. Be precise - prefer exact matches over partial matches`;
+
+/**
+ * Claude CLI adapter for AI-powered browser exploration
+ *
+ * Uses the `claude` CLI tool to make LLM calls, allowing users to:
+ * - Use their existing Claude Code authentication
+ * - Leverage local CLI configuration
+ * - Avoid managing API keys separately
+ */
+export class ClaudeCliAdapter implements AIAdapter {
+  readonly name = 'claude-cli';
+
+  private model: string;
+  private cliPath: string;
+  private timeout: number;
+
+  constructor(config: ClaudeCliAdapterConfig = {}) {
+    this.model = config.model ?? 'haiku';
+    this.cliPath = config.cliPath ?? 'claude';
+    this.timeout = config.timeout ?? 30000;
+  }
+
+  /**
+   * Execute claude CLI with a prompt and return the response
+   */
+  private async runClaude(prompt: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      // Note: --dangerously-skip-permissions is required for non-interactive mode
+      // because the CLI may otherwise wait for trust/permission dialogs
+      const args = ['--model', this.model, '--dangerously-skip-permissions', '-p', prompt];
+
+      debug('Spawning CLI:', this.cliPath, args.slice(0, 2).join(' '), '...');
+      debug('Prompt length:', prompt.length, 'chars');
+      const startTime = Date.now();
+
+      const proc = spawn(this.cliPath, args, {
+        // stdin must be 'ignore' - otherwise claude CLI waits for input
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      proc.stdout.on('data', (data: Buffer) => {
+        stdout += data.toString();
+        debug('stdout chunk:', data.toString().slice(0, 100));
+      });
+
+      proc.stderr.on('data', (data: Buffer) => {
+        stderr += data.toString();
+        debug('stderr chunk:', data.toString().slice(0, 200));
+      });
+
+      proc.on('error', (err: Error) => {
+        debug('spawn error:', err.message);
+        reject(new Error(`Failed to spawn claude CLI: ${err.message}`));
+      });
+
+      proc.on('close', (code: number | null) => {
+        const elapsed = Date.now() - startTime;
+        debug('CLI exited with code', code, 'after', elapsed, 'ms');
+        debug('stdout length:', stdout.length, 'stderr length:', stderr.length);
+
+        if (code === 0) {
+          resolve(stdout);
+        } else {
+          reject(new Error(`claude CLI exited with code ${code}: ${stderr}`));
+        }
+      });
+
+      // Handle timeout
+      const timer = setTimeout(() => {
+        debug('TIMEOUT after', this.timeout, 'ms - killing process');
+        proc.kill('SIGTERM');
+        reject(new Error(`claude CLI timed out after ${this.timeout}ms`));
+      }, this.timeout);
+
+      proc.on('close', () => clearTimeout(timer));
+    });
+  }
+
+  /**
+   * Parse JSON from claude CLI response
+   * Handles responses wrapped in markdown code blocks
+   */
+  private parseJsonResponse(response: string): Record<string, unknown> {
+    // Try to extract JSON from markdown code block
+    const jsonBlockMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const jsonStr = jsonBlockMatch ? jsonBlockMatch[1].trim() : response.trim();
+
+    try {
+      return JSON.parse(jsonStr);
+    } catch {
+      throw new Error(`Failed to parse JSON response: ${response}`);
+    }
+  }
+
+  /**
+   * Find element from natural language query using Claude CLI
+   *
+   * @param query - Natural language description of the element
+   * @param snapshot - Browser snapshot with element tree and refs
+   * @returns Promise resolving to element ref with reasoning
+   */
+  async findElement(query: string, snapshot: EnhancedSnapshot): Promise<FindElementResult> {
+    const availableRefs = Object.keys(snapshot.refs);
+
+    debug('findElement called with query:', query);
+    debug('Snapshot tree length:', snapshot.tree.length);
+    debug('Available refs:', availableRefs.length, availableRefs.slice(0, 5).join(', '), '...');
+
+    // If snapshot is empty, return early
+    if (!availableRefs.length || snapshot.tree === '(no interactive elements)') {
+      debug('Empty snapshot - returning NOT_FOUND immediately');
+      return {
+        ref: 'NOT_FOUND',
+        confidence: 0,
+        reasoning: 'Snapshot contains no interactive elements',
+      };
+    }
+
+    const prompt = `${ELEMENT_FINDER_PROMPT}
+
+Find the element matching this description: "${query}"
+
+Accessibility tree:
+${snapshot.tree}
+
+Available refs: ${availableRefs.join(', ')}
+
+Return ONLY a JSON object with these fields:
+- ref: the element reference (e.g., "e3") or "NOT_FOUND" if no match
+- confidence: a number 0-1
+- reasoning: why you selected this element
+
+JSON response:`;
+
+    try {
+      debug('Calling runClaude...');
+      const response = await this.runClaude(prompt);
+      debug('Got response:', response.slice(0, 200));
+      const parsed = this.parseJsonResponse(response);
+      debug('Parsed result:', parsed);
+
+      return {
+        ref: String(parsed.ref ?? 'NOT_FOUND'),
+        confidence: Number(parsed.confidence ?? 0),
+        reasoning: String(parsed.reasoning ?? 'No reasoning provided'),
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      debug('Error in findElement:', errorMessage);
+      return {
+        ref: 'NOT_FOUND',
+        confidence: 0,
+        reasoning: `CLI error: ${errorMessage}`,
+      };
+    }
+  }
+
+  /**
+   * Run exploration on a spec using Claude CLI
+   *
+   * Note: The primary AI method is findElement(). This explore() method is a stub
+   * that returns a minimal valid structure. Full exploration is orchestrated by
+   * the Explorer class which uses findElement() for AI-powered element discovery.
+   */
+  async explore(params: ExploreParams): Promise<ExplorationOutput> {
+    const explorationId = `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    return {
+      spec: params.spec.name,
+      specPath: params.specPath,
+      explorationId,
+      timestamp: new Date().toISOString(),
+      durationMs: 0,
+      browser: params.browser ?? 'chromium',
+      viewport: params.viewport ?? { width: 1280, height: 720 },
+      baseUrl: params.baseUrl,
+      steps: [],
+      outcomeChecks: [],
+      overallStatus: 'completed',
+      errors: [],
+    };
+  }
+
+  /**
+   * Retry exploration with review feedback
+   */
+  async retryWithFeedback(params: RetryParams): Promise<ExplorationOutput> {
+    return this.explore(params);
+  }
+}

package/src/adapters/claude.test.ts

@@ -0,0 +1,195 @@
+// @browserflow-ai/exploration - Claude adapter tests
+import { describe, it, expect, beforeEach, mock } from 'bun:test';
+import { ClaudeAdapter } from './claude';
+
+// Mock the Anthropic SDK
+const mockCreate = mock(() =>
+  Promise.resolve({
+    content: [
+      {
+        type: 'tool_use',
+        id: 'tool_1',
+        name: 'select_element',
+        input: {
+          ref: 'e5',
+          confidence: 0.95,
+          reasoning: 'The element with ref e5 is a button with text "Submit" which matches the query for a submit button.',
+        },
+      },
+    ],
+    stop_reason: 'tool_use',
+  })
+);
+
+// Mock Anthropic constructor
+mock.module('@anthropic-ai/sdk', () => ({
+  default: class MockAnthropic {
+    messages = {
+      create: mockCreate,
+    };
+  },
+}));
+
+describe('ClaudeAdapter', () => {
+  let adapter: ClaudeAdapter;
+
+  beforeEach(() => {
+    mockCreate.mockClear();
+    adapter = new ClaudeAdapter();
+  });
+
+  describe('constructor', () => {
+    it('should create adapter with default config', () => {
+      expect(adapter.name).toBe('claude');
+    });
+
+    it('should accept custom model config', () => {
+      const customAdapter = new ClaudeAdapter({
+        model: 'claude-opus-4-20250514',
+        maxTokens: 4096,
+      });
+      expect(customAdapter.name).toBe('claude');
+    });
+  });
+
+  describe('findElement', () => {
+    const sampleSnapshot = {
+      tree: `
+        <page url="http://localhost:3000/login">
+          <form>
+            <input ref="e1" type="email" placeholder="Email" />
+            <input ref="e2" type="password" placeholder="Password" />
+            <button ref="e5" type="submit">Submit</button>
+          </form>
+        </page>
+      `,
+      refs: {
+        e1: { tag: 'input', type: 'email', placeholder: 'Email' },
+        e2: { tag: 'input', type: 'password', placeholder: 'Password' },
+        e5: { tag: 'button', type: 'submit', text: 'Submit' },
+      },
+    };
+
+    it('should find element from natural language query', async () => {
+      const result = await adapter.findElement('submit button', sampleSnapshot);
+
+      expect(result.ref).toBe('e5');
+      expect(result.confidence).toBeGreaterThan(0);
+      expect(result.reasoning).toBeDefined();
+    });
+
+    it('should call Claude API with correct parameters', async () => {
+      await adapter.findElement('email input field', sampleSnapshot);
+
+      expect(mockCreate).toHaveBeenCalledTimes(1);
+      const callArgs = mockCreate.mock.calls[0][0];
+
+      expect(callArgs.model).toMatch(/claude/);
+      expect(callArgs.max_tokens).toBeGreaterThan(0);
+      expect(callArgs.messages).toBeDefined();
+      expect(callArgs.tools).toBeDefined();
+    });
+
+    it('should include snapshot tree in prompt', async () => {
+      await adapter.findElement('password field', sampleSnapshot);
+
+      const callArgs = mockCreate.mock.calls[0][0];
+      const userMessage = callArgs.messages.find((m: { role: string }) => m.role === 'user');
+
+      expect(userMessage.content).toContain('password field');
+    });
+
+    it('should use tool_use for structured output', async () => {
+      await adapter.findElement('submit button', sampleSnapshot);
+
+      const callArgs = mockCreate.mock.calls[0][0];
+      expect(callArgs.tools).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: 'select_element',
+          }),
+        ])
+      );
+    });
+
+    it('should return NOT_FOUND when element not found', async () => {
+      mockCreate.mockImplementationOnce(() =>
+        Promise.resolve({
+          content: [
+            {
+              type: 'tool_use',
+              id: 'tool_1',
+              name: 'select_element',
+              input: {
+                ref: 'NOT_FOUND',
+                confidence: 0,
+                reasoning: 'No element matches the description "purple unicorn button".',
+              },
+            },
+          ],
+          stop_reason: 'tool_use',
+        })
+      );
+
+      const result = await adapter.findElement('purple unicorn button', sampleSnapshot);
+
+      expect(result.ref).toBe('NOT_FOUND');
+      expect(result.confidence).toBe(0);
+    });
+
+    it('should handle API errors gracefully', async () => {
+      mockCreate.mockImplementationOnce(() => Promise.reject(new Error('API rate limit exceeded')));
+
+      await expect(adapter.findElement('button', sampleSnapshot)).rejects.toThrow('API rate limit exceeded');
+    });
+
+    it('should extract ref from text response as fallback', async () => {
+      mockCreate.mockImplementationOnce(() =>
+        Promise.resolve({
+          content: [
+            {
+              type: 'text',
+              text: 'The submit button is element e5. I selected this because it has type="submit" and the text "Submit".',
+            },
+          ],
+          stop_reason: 'end_turn',
+        })
+      );
+
+      const result = await adapter.findElement('submit button', sampleSnapshot);
+
+      expect(result.ref).toBe('e5');
+    });
+  });
+
+  describe('findElement with ambiguous queries', () => {
+    const snapshotWithMultipleButtons = {
+      tree: `
+        <page>
+          <button ref="e1">Cancel</button>
+          <button ref="e2">Submit</button>
+          <button ref="e3">Submit</button>
+        </page>
+      `,
+      refs: {
+        e1: { tag: 'button', text: 'Cancel' },
+        e2: { tag: 'button', text: 'Submit' },
+        e3: { tag: 'button', text: 'Submit' },
+      },
+    };
+
+    it('should pick most likely element for ambiguous query', async () => {
+      const result = await adapter.findElement('submit button', snapshotWithMultipleButtons);
+
+      // Should return one of the submit buttons
+      expect(['e2', 'e3', 'e5']).toContain(result.ref);
+    });
+
+    it('should include reasoning for ambiguous cases', async () => {
+      const result = await adapter.findElement('submit button', snapshotWithMultipleButtons);
+
+      expect(result.reasoning).toBeDefined();
+      expect(result.reasoning.length).toBeGreaterThan(0);
+    });
+  });
+});