@browserflow-ai/exploration 0.0.6

package/dist/adapters/claude-cli.d.ts

@@ -0,0 +1,57 @@
+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;
+}
+/**
+ * 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 declare class ClaudeCliAdapter implements AIAdapter {
+    readonly name = "claude-cli";
+    private model;
+    private cliPath;
+    private timeout;
+    constructor(config?: ClaudeCliAdapterConfig);
+    /**
+     * Execute claude CLI with a prompt and return the response
+     */
+    private runClaude;
+    /**
+     * Parse JSON from claude CLI response
+     * Handles responses wrapped in markdown code blocks
+     */
+    private parseJsonResponse;
+    /**
+     * 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
+     */
+    findElement(query: string, snapshot: EnhancedSnapshot): Promise<FindElementResult>;
+    /**
+     * 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.
+     */
+    explore(params: ExploreParams): Promise<ExplorationOutput>;
+    /**
+     * Retry exploration with review feedback
+     */
+    retryWithFeedback(params: RetryParams): Promise<ExplorationOutput>;
+}
+//# sourceMappingURL=claude-cli.d.ts.map

package/dist/adapters/claude-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-cli.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAeD;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,GAAE,sBAA2B;IAM/C;;OAEG;YACW,SAAS;IAwDvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwDxF;;;;;;OAMG;IACG,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmBhE;;OAEG;IACG,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAGzE"}

package/dist/adapters/claude-cli.js

@@ -0,0 +1,195 @@
+// @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) {
+    if (DEBUG) {
+        console.error('[claude-cli]', ...args);
+    }
+}
+/**
+ * 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 {
+    name = 'claude-cli';
+    model;
+    cliPath;
+    timeout;
+    constructor(config = {}) {
+        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
+     */
+    async runClaude(prompt) {
+        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) => {
+                stdout += data.toString();
+                debug('stdout chunk:', data.toString().slice(0, 100));
+            });
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+                debug('stderr chunk:', data.toString().slice(0, 200));
+            });
+            proc.on('error', (err) => {
+                debug('spawn error:', err.message);
+                reject(new Error(`Failed to spawn claude CLI: ${err.message}`));
+            });
+            proc.on('close', (code) => {
+                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
+     */
+    parseJsonResponse(response) {
+        // 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, snapshot) {
+        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) {
+        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) {
+        return this.explore(params);
+    }
+}
+//# sourceMappingURL=claude-cli.js.map

package/dist/adapters/claude-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli.js","sourceRoot":"","sources":["../../src/adapters/claude-cli.ts"],"names":[],"mappings":"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"}

package/dist/adapters/claude.d.ts

@@ -0,0 +1,54 @@
+import type { AIAdapter, ExploreParams, ExplorationOutput, RetryParams, EnhancedSnapshot, FindElementResult } from './types';
+/**
+ * Configuration options for the Claude adapter
+ */
+export interface ClaudeAdapterConfig {
+    apiKey?: string;
+    model?: string;
+    maxTokens?: number;
+}
+/**
+ * Claude adapter for AI-powered browser exploration
+ *
+ * Uses Claude's vision and reasoning capabilities to:
+ * - Interpret spec steps
+ * - Identify elements in browser snapshots
+ * - Execute exploration workflows
+ */
+export declare class ClaudeAdapter implements AIAdapter {
+    readonly name = "claude";
+    private client;
+    private model;
+    private maxTokens;
+    constructor(config?: ClaudeAdapterConfig);
+    /**
+     * Find element from natural language query using Claude
+     *
+     * @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
+     */
+    findElement(query: string, snapshot: EnhancedSnapshot): Promise<FindElementResult>;
+    /**
+     * Run exploration on a spec using Claude
+     *
+     * 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.
+     *
+     * @param params - Exploration parameters including spec and browser config
+     * @returns Promise resolving to exploration output
+     */
+    explore(params: ExploreParams): Promise<ExplorationOutput>;
+    /**
+     * Retry exploration with review feedback
+     *
+     * Note: Currently delegates to explore(). Future enhancement could use
+     * review feedback to improve element selection accuracy.
+     *
+     * @param params - Retry parameters including previous exploration and feedback
+     * @returns Promise resolving to new exploration output
+     */
+    retryWithFeedback(params: RetryParams): Promise<ExplorationOutput>;
+}
+//# sourceMappingURL=claude.d.ts.map

package/dist/adapters/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyCD;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC7C,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,GAAE,mBAAwB;IAQ5C;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0DxF;;;;;;;;;OASG;IACG,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmBhE;;;;;;;;OAQG;IACG,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAGzE"}

package/dist/adapters/claude.js

@@ -0,0 +1,160 @@
+// @browserflow-ai/exploration - Claude AI Adapter
+import Anthropic from '@anthropic-ai/sdk';
+/**
+ * System prompt for element finding
+ */
+const ELEMENT_FINDER_SYSTEM_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 using the select_element tool
+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`;
+/**
+ * Tool definition for structured element selection
+ */
+const SELECT_ELEMENT_TOOL = {
+    name: 'select_element',
+    description: 'Select an element by its ref from the page snapshot',
+    input_schema: {
+        type: 'object',
+        properties: {
+            ref: {
+                type: 'string',
+                description: 'Element ref like e1, e2, or NOT_FOUND if no match',
+            },
+            confidence: {
+                type: 'number',
+                description: 'Confidence score 0-1 for the selection',
+            },
+            reasoning: {
+                type: 'string',
+                description: 'Explanation for why this element was selected',
+            },
+        },
+        required: ['ref', 'confidence', 'reasoning'],
+    },
+};
+/**
+ * Claude adapter for AI-powered browser exploration
+ *
+ * Uses Claude's vision and reasoning capabilities to:
+ * - Interpret spec steps
+ * - Identify elements in browser snapshots
+ * - Execute exploration workflows
+ */
+export class ClaudeAdapter {
+    name = 'claude';
+    client;
+    model;
+    maxTokens;
+    constructor(config = {}) {
+        this.client = new Anthropic({
+            apiKey: config.apiKey,
+        });
+        this.model = config.model ?? 'claude-haiku-4-5';
+        this.maxTokens = config.maxTokens ?? 8192;
+    }
+    /**
+     * Find element from natural language query using Claude
+     *
+     * @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, snapshot) {
+        const userMessage = `Find the element matching this description: "${query}"
+
+Current page snapshot:
+${snapshot.tree}
+
+Available refs: ${Object.keys(snapshot.refs).join(', ')}
+
+Use the select_element tool to return the ref of the best matching element.`;
+        const response = await this.client.messages.create({
+            model: this.model,
+            max_tokens: 1024,
+            system: ELEMENT_FINDER_SYSTEM_PROMPT,
+            tools: [SELECT_ELEMENT_TOOL],
+            tool_choice: { type: 'tool', name: 'select_element' },
+            messages: [
+                {
+                    role: 'user',
+                    content: userMessage,
+                },
+            ],
+        });
+        // Handle tool_use response (preferred)
+        for (const block of response.content) {
+            if (block.type === 'tool_use' && block.name === 'select_element') {
+                const input = block.input;
+                return {
+                    ref: input.ref,
+                    confidence: input.confidence,
+                    reasoning: input.reasoning,
+                };
+            }
+        }
+        // Fallback: parse text response if no tool_use
+        for (const block of response.content) {
+            if (block.type === 'text') {
+                const refMatch = block.text.match(/\be(\d+)\b/);
+                if (refMatch) {
+                    return {
+                        ref: refMatch[0],
+                        confidence: 0.7, // Lower confidence for text extraction
+                        reasoning: block.text,
+                    };
+                }
+            }
+        }
+        // No element found
+        return {
+            ref: 'NOT_FOUND',
+            confidence: 0,
+            reasoning: 'Could not extract element ref from response',
+        };
+    }
+    /**
+     * Run exploration on a spec using Claude
+     *
+     * 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.
+     *
+     * @param params - Exploration parameters including spec and browser config
+     * @returns Promise resolving to exploration output
+     */
+    async explore(params) {
+        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
+     *
+     * Note: Currently delegates to explore(). Future enhancement could use
+     * review feedback to improve element selection accuracy.
+     *
+     * @param params - Retry parameters including previous exploration and feedback
+     * @returns Promise resolving to new exploration output
+     */
+    async retryWithFeedback(params) {
+        return this.explore(params);
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/adapters/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}

package/dist/adapters/index.d.ts

@@ -0,0 +1,6 @@
+export { ClaudeAdapter } from './claude';
+export type { ClaudeAdapterConfig } from './claude';
+export { ClaudeCliAdapter } from './claude-cli';
+export type { ClaudeCliAdapterConfig } from './claude-cli';
+export type { AIAdapter, ExploreParams, ExplorationOutput, RetryParams, ReviewFeedback, Spec, SpecStep, StepResult, StepExecution, StepScreenshots, OutcomeCheck, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3D,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,4 @@
+// @browserflow-ai/exploration - Adapter exports
+export { ClaudeAdapter } from './claude';
+export { ClaudeCliAdapter } from './claude-cli';
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAEhD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}