@sparkleideas/browser 3.0.0-alpha.3

package/src/mcp-tools/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @sparkleideas/browser - MCP Tools Index
+ */
+
+export { browserTools, type MCPTool } from './browser-tools.js';
+export { default } from './browser-tools.js';

package/src/skill/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser Skill Exports
+ * Re-exports skill-related functionality for Claude Code integration
+ */
+
+export { browserTools } from '../mcp-tools/browser-tools.js';
+export { BrowserService, createBrowserService } from '../application/browser-service.js';
+export { preBrowseHook, postBrowseHook, browserHooks } from '../infrastructure/hooks-integration.js';
+
+// Skill metadata
+export const SKILL_METADATA = {
+  name: 'browser',
+  description: 'Web browser automation with AI-optimized snapshots for @sparkleideas/claude-flow agents',
+  version: '1.0.0',
+  triggers: ['/browser', 'browse', 'web automation', 'scrape', 'navigate', 'screenshot'],
+  tools: [
+    'browser/open',
+    'browser/snapshot',
+    'browser/click',
+    'browser/fill',
+    'browser/screenshot',
+    'browser/close',
+  ],
+};

package/tests/agent-browser-adapter.test.ts

@@ -0,0 +1,328 @@
+/**
+ * @sparkleideas/browser - Agent Browser Adapter Tests
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { AgentBrowserAdapter } from '../src/infrastructure/agent-browser-adapter.js';
+import { execSync } from 'child_process';
+
+// Mock execSync
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+  spawn: vi.fn(),
+}));
+
+const mockExecSync = vi.mocked(execSync);
+
+describe('AgentBrowserAdapter', () => {
+  let adapter: AgentBrowserAdapter;
+
+  beforeEach(() => {
+    adapter = new AgentBrowserAdapter({
+      session: 'test-session',
+      timeout: 5000,
+    });
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('should create adapter with default options', () => {
+      const defaultAdapter = new AgentBrowserAdapter();
+      expect(defaultAdapter).toBeInstanceOf(AgentBrowserAdapter);
+    });
+
+    it('should create adapter with custom options', () => {
+      const customAdapter = new AgentBrowserAdapter({
+        session: 'custom',
+        timeout: 10000,
+        headless: false,
+        debug: true,
+      });
+      expect(customAdapter).toBeInstanceOf(AgentBrowserAdapter);
+    });
+  });
+
+  describe('navigation', () => {
+    it('should open a URL', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: { url: 'https://example.com' },
+      }));
+
+      const result = await adapter.open({ url: 'https://example.com' });
+
+      expect(result.success).toBe(true);
+      expect(mockExecSync).toHaveBeenCalled();
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('open');
+      expect(callArgs).toContain('https://example.com');
+    });
+
+    it('should go back', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.back();
+
+      expect(result.success).toBe(true);
+      expect(mockExecSync).toHaveBeenCalled();
+    });
+
+    it('should go forward', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.forward();
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should reload', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.reload();
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should close', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.close();
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('interaction', () => {
+    it('should click an element', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: { clicked: true },
+      }));
+
+      const result = await adapter.click({ target: '@e1' });
+
+      expect(result.success).toBe(true);
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('click');
+      expect(callArgs).toContain('@e1');
+    });
+
+    it('should fill an input', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: { filled: true },
+      }));
+
+      const result = await adapter.fill({ target: '@e1', value: 'test' });
+
+      expect(result.success).toBe(true);
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('fill');
+    });
+
+    it('should type text', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.type({ target: '@e1', text: 'hello' });
+
+      expect(result.success).toBe(true);
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('type');
+    });
+
+    it('should press a key', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.press('Enter');
+
+      expect(result.success).toBe(true);
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('press');
+      expect(callArgs).toContain('Enter');
+    });
+
+    it('should hover an element', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.hover('@e1');
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should scroll', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.scroll('down', 500);
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('information retrieval', () => {
+    it('should get text', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: 'Element text',
+      }));
+
+      const result = await adapter.getText('@e1');
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe('Element text');
+    });
+
+    it('should get title', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: 'Page Title',
+      }));
+
+      const result = await adapter.getTitle();
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should get URL', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: 'https://example.com',
+      }));
+
+      const result = await adapter.getUrl();
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('state checks', () => {
+    it('should check visibility', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: true,
+      }));
+
+      const result = await adapter.isVisible('@e1');
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(true);
+    });
+
+    it('should check if enabled', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: true,
+      }));
+
+      const result = await adapter.isEnabled('@e1');
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('snapshot', () => {
+    it('should take a snapshot', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: {
+          tree: { role: 'document', children: [] },
+          refs: {},
+          url: 'https://example.com',
+          title: 'Test',
+        },
+      }));
+
+      const result = await adapter.snapshot();
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+    });
+
+    it('should take interactive snapshot', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: { tree: { role: 'document' } },
+      }));
+
+      const result = await adapter.snapshot({ interactive: true });
+
+      expect(result.success).toBe(true);
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('-i');
+    });
+
+    it('should take compact snapshot', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.snapshot({ compact: true });
+
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('-c');
+    });
+  });
+
+  describe('screenshot', () => {
+    it('should take a screenshot', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({
+        success: true,
+        data: 'base64encodedimage',
+      }));
+
+      const result = await adapter.screenshot();
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should take full page screenshot', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.screenshot({ fullPage: true });
+
+      const callArgs = mockExecSync.mock.calls[0][0] as string;
+      expect(callArgs).toContain('--full');
+    });
+  });
+
+  describe('wait', () => {
+    it('should wait for selector', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.wait({ selector: '#element' });
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should wait for timeout', async () => {
+      mockExecSync.mockReturnValue(JSON.stringify({ success: true }));
+
+      const result = await adapter.wait({ timeout: 1000 });
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle command failure', async () => {
+      mockExecSync.mockImplementation(() => {
+        throw new Error('Command failed');
+      });
+
+      const result = await adapter.open({ url: 'https://example.com' });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Command failed');
+    });
+
+    it('should handle invalid JSON response', async () => {
+      mockExecSync.mockReturnValue('invalid json');
+
+      const result = await adapter.open({ url: 'https://example.com' });
+
+      // Should fall back to raw string
+      expect(result.success).toBe(true);
+    });
+  });
+});

package/tests/browser-service.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @sparkleideas/browser - Browser Service Tests
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { BrowserService, createBrowserService } from '../src/application/browser-service.js';
+
+// Mock execSync for agent-browser CLI
+vi.mock('child_process', () => ({
+  execSync: vi.fn(() => JSON.stringify({ success: true, data: { test: 'value' } })),
+  spawn: vi.fn(),
+}));
+
+describe('BrowserService', () => {
+  let service: BrowserService;
+
+  beforeEach(() => {
+    service = createBrowserService({ sessionId: 'test-session' });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('createBrowserService', () => {
+    it('should create a browser service with default options', () => {
+      const svc = createBrowserService();
+      expect(svc).toBeInstanceOf(BrowserService);
+    });
+
+    it('should create a browser service with custom session', () => {
+      const svc = createBrowserService({ sessionId: 'custom-session' });
+      expect(svc).toBeInstanceOf(BrowserService);
+    });
+  });
+
+  describe('trajectory tracking', () => {
+    it('should start a trajectory', () => {
+      const id = service.startTrajectory('test task');
+      expect(id).toBeDefined();
+      expect(typeof id).toBe('string');
+      expect(id.startsWith('traj-')).toBe(true);
+    });
+
+    it('should end a trajectory', async () => {
+      service.startTrajectory('test task');
+      const trajectory = await service.endTrajectory(true, 'success');
+
+      expect(trajectory).toBeDefined();
+      expect(trajectory?.goal).toBe('test task');
+      expect(trajectory?.success).toBe(true);
+      expect(trajectory?.verdict).toBe('success');
+    });
+
+    it('should return null if no trajectory is active', async () => {
+      const trajectory = await service.endTrajectory(true);
+      expect(trajectory).toBeNull();
+    });
+  });
+
+  describe('navigation', () => {
+    it('should navigate to a URL', async () => {
+      const result = await service.open('https://example.com');
+      expect(result).toBeDefined();
+    });
+
+    it('should close the browser', async () => {
+      const result = await service.close();
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('snapshot', () => {
+    it('should take a snapshot with default options', async () => {
+      const result = await service.snapshot();
+      expect(result).toBeDefined();
+    });
+
+    it('should take a snapshot with interactive option', async () => {
+      const result = await service.snapshot({ interactive: true });
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('interaction', () => {
+    it('should click an element', async () => {
+      const result = await service.click('@e1');
+      expect(result).toBeDefined();
+    });
+
+    it('should fill an input', async () => {
+      const result = await service.fill('@e1', 'test value');
+      expect(result).toBeDefined();
+    });
+
+    it('should type text', async () => {
+      const result = await service.type('@e1', 'typed text');
+      expect(result).toBeDefined();
+    });
+
+    it('should press a key', async () => {
+      const result = await service.press('Enter');
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('wait', () => {
+    it('should wait for an element', async () => {
+      const result = await service.wait({ selector: '#element' });
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('data extraction', () => {
+    it('should get text from element', async () => {
+      const result = await service.getText('@e1');
+      expect(result).toBeDefined();
+    });
+
+    it('should evaluate JavaScript', async () => {
+      const result = await service.eval('document.title');
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('screenshot', () => {
+    it('should take a screenshot', async () => {
+      const result = await service.screenshot();
+      expect(result).toBeDefined();
+    });
+
+    it('should take a screenshot with path', async () => {
+      const result = await service.screenshot({ path: '/tmp/test.png' });
+      expect(result).toBeDefined();
+    });
+  });
+});

package/tests/e2e/browser-e2e.test.ts

@@ -0,0 +1,175 @@
+/**
+ * @sparkleideas/browser - E2E Browser Tests
+ *
+ * These tests run against a real browser using agent-browser.
+ * Run with: docker compose --profile e2e up browser-e2e
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'child_process';
+
+const TEST_URL = process.env.TEST_URL || 'http://localhost:3000';
+const SESSION = 'e2e-test';
+
+/**
+ * Execute agent-browser command
+ */
+function browser(command: string): string {
+  try {
+    const result = execSync(`agent-browser --session ${SESSION} --json ${command}`, {
+      encoding: 'utf-8',
+      timeout: 30000,
+    });
+    return result;
+  } catch (error) {
+    throw new Error(`Browser command failed: ${error instanceof Error ? error.message : error}`);
+  }
+}
+
+/**
+ * Parse JSON result from agent-browser
+ */
+function parseResult(output: string): { success: boolean; data?: unknown; error?: string } {
+  try {
+    return JSON.parse(output);
+  } catch {
+    return { success: true, data: output.trim() };
+  }
+}
+
+describe('Browser E2E Tests', () => {
+  // Skip if not in E2E environment
+  const runE2E = process.env.TEST_URL !== undefined;
+
+  beforeAll(async () => {
+    if (!runE2E) {
+      console.log('Skipping E2E tests - TEST_URL not set');
+      return;
+    }
+
+    // Open test page
+    const result = browser(`open ${TEST_URL}`);
+    const parsed = parseResult(result);
+    expect(parsed.success).toBe(true);
+  });
+
+  afterAll(async () => {
+    if (!runE2E) return;
+
+    // Close browser
+    try {
+      browser('close');
+    } catch {
+      // Ignore close errors
+    }
+  });
+
+  describe('Navigation', () => {
+    it.skipIf(!runE2E)('should navigate to test page', () => {
+      const result = browser('get url');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      expect(parsed.data).toContain(TEST_URL);
+    });
+
+    it.skipIf(!runE2E)('should get page title', () => {
+      const result = browser('get title');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      expect(parsed.data).toBe('Browser Test Page');
+    });
+  });
+
+  describe('Snapshot', () => {
+    it.skipIf(!runE2E)('should take accessibility snapshot', () => {
+      const result = browser('snapshot');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      expect(parsed.data).toBeDefined();
+    });
+
+    it.skipIf(!runE2E)('should get interactive elements only', () => {
+      const result = browser('snapshot -i');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      // Should have element refs like @e1, @e2
+    });
+  });
+
+  describe('Form Interaction', () => {
+    it.skipIf(!runE2E)('should fill email input', () => {
+      // First get snapshot to find refs
+      browser('snapshot -i');
+
+      // Fill using CSS selector
+      const result = browser('fill "#email" "test@example.com"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+    });
+
+    it.skipIf(!runE2E)('should fill password input', () => {
+      const result = browser('fill "#password" "secretpassword"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+    });
+
+    it.skipIf(!runE2E)('should check checkbox', () => {
+      const result = browser('check "#agree"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+    });
+
+    it.skipIf(!runE2E)('should submit form', () => {
+      const result = browser('click "#submit-btn"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+    });
+
+    it.skipIf(!runE2E)('should see result after form submit', () => {
+      // Wait for result to appear
+      browser('wait "#result"');
+
+      const result = browser('get text "#result-data"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      expect(parsed.data).toContain('test@example.com');
+    });
+  });
+
+  describe('Screenshot', () => {
+    it.skipIf(!runE2E)('should take screenshot', () => {
+      const result = browser('screenshot');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      // Should return base64 image data
+    });
+  });
+
+  describe('JavaScript Execution', () => {
+    it.skipIf(!runE2E)('should execute JavaScript', () => {
+      const result = browser('eval "document.title"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      expect(parsed.data).toBe('Browser Test Page');
+    });
+
+    it.skipIf(!runE2E)('should extract data with JavaScript', () => {
+      const result = browser('eval "document.getElementById(\'email\').value"');
+      const parsed = parseResult(result);
+
+      expect(parsed.success).toBe(true);
+      expect(parsed.data).toBe('test@example.com');
+    });
+  });
+});