@dynamicu/chromedebug-mcp 2.2.0

package/src/capture/index.js

@@ -0,0 +1,508 @@
+/**
+ * Unified Interaction Capture System - Main Entry Point
+ *
+ * This module provides the complete unified interaction capture system
+ * that replaces the legacy frame recording, workflow recording, and
+ * function tracing systems.
+ *
+ * WHAT THIS SYSTEM PROVIDES:
+ * ==========================
+ * • Unified data format for all interaction types
+ * • Modular architecture enabling parallel development
+ * • Memory-efficient capture and storage
+ * • High-performance processing pipelines
+ * • Extensible design for future capture types
+ * • Chrome extension compatibility
+ * • Database-optimized storage
+ * • Rich query and analysis capabilities
+ *
+ * SYSTEM ARCHITECTURE:
+ * ====================
+ *
+ * 1. CAPTURE SOURCES: Generate interaction events
+ *    - Chrome Extension: Screen captures, user interactions, console logs
+ *    - Puppeteer: DOM snapshots, network traffic, browser state
+ *    - DevTools: Function traces, performance data, debugging info
+ *
+ * 2. CAPTURE COLLECTOR: Route and coordinate events
+ *    - Event routing from sources to processors
+ *    - Flow control and backpressure management
+ *    - Source lifecycle management
+ *
+ * 3. CAPTURE PROCESSORS: Transform and enrich events
+ *    - Filter out unwanted events
+ *    - Compress large data (images, DOM)
+ *    - Enrich with metadata and context
+ *    - Format for storage optimization
+ *
+ * 4. CAPTURE STORAGE: Persist events efficiently
+ *    - Database for metadata and small events
+ *    - File system for large binary data
+ *    - Memory cache for recent events
+ *    - Network storage for backup/sync
+ *
+ * 5. CAPTURE QUERY: Search and retrieve events
+ *    - Filter by type, time, session, etc.
+ *    - Full-text search across event data
+ *    - Pagination and streaming for large results
+ *    - Performance-optimized queries
+ *
+ * 6. CAPTURE ANALYZER: Extract insights and patterns
+ *    - User interaction patterns
+ *    - Performance bottlenecks
+ *    - Error detection and analysis
+ *    - Session summaries and comparisons
+ *
+ * MIGRATION FROM LEGACY SYSTEMS:
+ * ===============================
+ *
+ * LEGACY FRAME RECORDING → UNIFIED SCREEN EVENTS:
+ * • Frame data becomes ScreenCaptureData events
+ * • Console logs become ConsoleCaptureData events
+ * • Maintains existing screenshot and logging functionality
+ * • Adds support for element-specific captures
+ *
+ * LEGACY WORKFLOW RECORDING → UNIFIED USER EVENTS:
+ * • User actions become UserInteractionData events
+ * • DOM snapshots become DOMCaptureData events
+ * • Restore points become StateChangeData events
+ * • Maintains existing replay functionality
+ *
+ * LEGACY FUNCTION TRACING → UNIFIED FUNCTION EVENTS:
+ * • Function calls become FunctionTraceData events
+ * • Execution traces maintain same detail level
+ * • Adds support for async function tracking
+ * • Better correlation with other event types
+ *
+ * KEY BENEFITS:
+ * =============
+ *
+ * 1. UNIFIED FORMAT: Single consistent data structure for all events
+ * 2. BETTER CORRELATION: Events can be correlated across different types
+ * 3. IMPROVED PERFORMANCE: Optimized storage and memory management
+ * 4. EXTENSIBILITY: Easy to add new capture types without breaking changes
+ * 5. MODULARITY: Independent development and testing of components
+ * 6. CHROME COMPATIBILITY: Designed for Chrome extension constraints
+ * 7. MEMORY EFFICIENCY: Smart memory management with size-based optimization
+ * 8. ANALYTICS: Rich analysis capabilities across all interaction types
+ *
+ * USAGE EXAMPLES:
+ * ===============
+ *
+ * // Basic system setup
+ * import { CaptureSystem } from './capture/index.js';
+ *
+ * const system = new CaptureSystem();
+ * await system.initialize({
+ *   sources: ['chrome-extension', 'puppeteer'],
+ *   storage: 'sqlite',
+ *   memoryLimitMB: 100
+ * });
+ *
+ * // Start capture session
+ * const session = await system.startSession({
+ *   name: 'User Journey Test',
+ *   captureTypes: ['screen', 'user', 'console'],
+ *   config: {
+ *     screenshots: { quality: 80, interval: 1000 },
+ *     userEvents: { includeHover: true }
+ *   }
+ * });
+ *
+ * // Query captured events
+ * const events = await system.query.queryEvents({
+ *   sessionId: session.id,
+ *   type: 'user',
+ *   timeRange: { start: Date.now() - 60000, end: Date.now() }
+ * });
+ *
+ * // Analyze session
+ * const analysis = await system.analyzer.generateSummary(session.id);
+ *
+ * // Stop and cleanup
+ * await system.stopSession();
+ * await system.shutdown();
+ *
+ * IMPLEMENTATION ROADMAP:
+ * =======================
+ *
+ * PHASE 1: Foundation (THIS DELIVERABLE)
+ * • Core data types and interfaces ✓
+ * • Module architecture design ✓
+ * • Memory management strategy ✓
+ * • Data flow architecture ✓
+ *
+ * PHASE 2: Core Implementation
+ * • Basic SQLite storage implementation
+ * • Memory buffer and batch processor
+ * • Simple query engine
+ * • Basic Chrome extension source
+ *
+ * PHASE 3: Processing Pipeline
+ * • Event filtering and transformation
+ * • Compression processors
+ * • Error handling and recovery
+ * • Performance optimization
+ *
+ * PHASE 4: Advanced Features
+ * • Full-text search capabilities
+ * • Advanced analytics and insights
+ * • Real-time streaming support
+ * • Network storage and sync
+ *
+ * PHASE 5: Migration & Integration
+ * • Legacy system compatibility layer
+ * • Data migration tools
+ * • MCP tool integration
+ * • Production deployment
+ */
+
+// Export core types and interfaces
+export * from './types.js';
+export * from './interfaces.js';
+export * from './architecture.js';
+export * from './memory-manager.js';
+
+/**
+ * Factory function to create a complete capture system
+ * @param {Object} config - System configuration
+ * @returns {Promise<ICaptureSystem>} Configured capture system
+ */
+export async function createCaptureSystem(config = {}) {
+  const { CaptureSystem } = await import('./implementations/capture-system.js');
+  const system = new CaptureSystem();
+  await system.initialize(config);
+  return system;
+}
+
+/**
+ * Factory function to create storage implementation
+ * @param {string} type - Storage type ('sqlite', 'memory', 'filesystem')
+ * @param {Object} config - Storage configuration
+ * @returns {Promise<ICaptureStorage>} Storage implementation
+ */
+export async function createStorage(type = 'sqlite', config = {}) {
+  switch (type) {
+    case 'sqlite': {
+      const { SQLiteCaptureStorage } = await import('./implementations/sqlite-storage.js');
+      const storage = new SQLiteCaptureStorage();
+      await storage.initialize(config);
+      return storage;
+    }
+    case 'memory': {
+      const { MemoryCaptureStorage } = await import('./implementations/memory-storage.js');
+      const storage = new MemoryCaptureStorage();
+      await storage.initialize(config);
+      return storage;
+    }
+    case 'filesystem': {
+      const { FileSystemCaptureStorage } = await import('./implementations/filesystem-storage.js');
+      const storage = new FileSystemCaptureStorage();
+      await storage.initialize(config);
+      return storage;
+    }
+    default:
+      throw new Error(`Unknown storage type: ${type}`);
+  }
+}
+
+/**
+ * Factory function to create Chrome extension source
+ * @param {Object} config - Source configuration
+ * @returns {Promise<ICaptureSource>} Chrome extension source
+ */
+export async function createChromeExtensionSource(config = {}) {
+  const { ChromeExtensionCaptureSource } = await import('./implementations/chrome-extension-source.js');
+  const source = new ChromeExtensionCaptureSource();
+  await source.initialize(config);
+  return source;
+}
+
+/**
+ * Factory function to create Puppeteer source
+ * @param {Object} config - Source configuration
+ * @returns {Promise<ICaptureSource>} Puppeteer source
+ */
+export async function createPuppeteerSource(config = {}) {
+  const { PuppeteerCaptureSource } = await import('./implementations/puppeteer-source.js');
+  const source = new PuppeteerCaptureSource();
+  await source.initialize(config);
+  return source;
+}
+
+/**
+ * Utility function to validate capture event
+ * @param {CaptureEvent} event - Event to validate
+ * @returns {boolean} True if valid
+ */
+export function validateCaptureEvent(event) {
+  const { CAPTURE_TYPES, EVENT_DATA_TYPES } = require('./types.js');
+
+  if (!event || typeof event !== 'object') {
+    return false;
+  }
+
+  // Check required fields
+  const requiredFields = ['id', 'sessionId', 'sequence', 'timestamp', 'type', 'data'];
+  for (const field of requiredFields) {
+    if (!(field in event)) {
+      return false;
+    }
+  }
+
+  // Check event type
+  if (!Object.values(CAPTURE_TYPES).includes(event.type)) {
+    return false;
+  }
+
+  // Check timestamp format
+  if (!event.timestamp.relative || !event.timestamp.absolute) {
+    return false;
+  }
+
+  // Check data structure based on type
+  const expectedDataType = EVENT_DATA_TYPES[event.type];
+  if (expectedDataType && event.data) {
+    // Basic validation - could be extended with JSON schema
+    return typeof event.data === 'object';
+  }
+
+  return true;
+}
+
+/**
+ * Utility function to estimate event memory usage
+ * @param {CaptureEvent} event - Event to estimate
+ * @returns {number} Estimated bytes
+ */
+export function estimateEventMemoryUsage(event) {
+  if (!event) return 0;
+
+  let size = 0;
+
+  // Base event structure
+  size += JSON.stringify({
+    id: event.id,
+    sessionId: event.sessionId,
+    sequence: event.sequence,
+    timestamp: event.timestamp,
+    type: event.type,
+    subtype: event.subtype,
+    pageId: event.pageId,
+    url: event.url,
+    metadata: event.metadata
+  }).length;
+
+  // Event data size
+  if (event.data) {
+    switch (event.type) {
+      case 'screen':
+        // Image data is typically the largest
+        if (event.data.imageData) {
+          size += event.data.imageData.length;
+        }
+        break;
+
+      case 'dom':
+        // HTML content size
+        if (event.data.html) {
+          size += event.data.html.length;
+        }
+        if (event.data.styles) {
+          size += JSON.stringify(event.data.styles).length;
+        }
+        break;
+
+      default:
+        // For other types, estimate JSON size
+        size += JSON.stringify(event.data).length;
+    }
+  }
+
+  return size;
+}
+
+/**
+ * Utility function to create a new capture event
+ * @param {Object} options - Event options
+ * @returns {CaptureEvent} Created event
+ */
+export function createCaptureEvent(options) {
+  const { CaptureEvent, TimestampInfo } = require('./types.js');
+
+  const now = Date.now();
+  const perfNow = performance.now();
+
+  return {
+    ...CaptureEvent,
+    id: options.id || `evt_${now}_${Math.random().toString(36).substr(2, 9)}`,
+    sessionId: options.sessionId || '',
+    sequence: options.sequence || 0,
+    timestamp: {
+      ...TimestampInfo,
+      relative: options.relativeTime || perfNow,
+      absolute: options.absoluteTime || now,
+      performance: perfNow
+    },
+    type: options.type || '',
+    subtype: options.subtype || '',
+    pageId: options.pageId || '',
+    url: options.url || '',
+    data: options.data || {},
+    metadata: {
+      tags: options.tags || [],
+      source: options.source || '',
+      priority: options.priority || 'normal',
+      sizeHint: options.sizeHint || 'small',
+      ...options.metadata
+    }
+  };
+}
+
+/**
+ * Development utilities for testing and debugging
+ */
+export const DevUtils = {
+  /**
+   * Create mock capture events for testing
+   * @param {number} count - Number of events to create
+   * @param {Object} options - Event options
+   * @returns {CaptureEvent[]} Mock events
+   */
+  createMockEvents(count = 10, options = {}) {
+    const events = [];
+    const sessionId = options.sessionId || `session_${Date.now()}`;
+    const types = options.types || ['screen', 'user', 'console'];
+
+    for (let i = 0; i < count; i++) {
+      const type = types[i % types.length];
+      events.push(createCaptureEvent({
+        sessionId,
+        sequence: i,
+        type,
+        relativeTime: i * 1000,
+        data: this.createMockData(type),
+        ...options
+      }));
+    }
+
+    return events;
+  },
+
+  /**
+   * Create mock data for event type
+   * @param {string} type - Event type
+   * @returns {Object} Mock data
+   */
+  createMockData(type) {
+    switch (type) {
+      case 'screen':
+        return {
+          imageData: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/',
+          format: 'jpeg',
+          width: 1920,
+          height: 1080,
+          quality: 80,
+          viewport: { x: 0, y: 0, width: 1920, height: 1080, scale: 1.0 }
+        };
+
+      case 'user':
+        return {
+          action: 'click',
+          target: {
+            selector: '#submit-button',
+            tagName: 'BUTTON',
+            text: 'Submit',
+            attributes: { type: 'submit', class: 'btn btn-primary' },
+            bounds: { x: 100, y: 200, width: 120, height: 40 }
+          },
+          coordinates: { x: 160, y: 220 },
+          modifiers: [],
+          duration: 150
+        };
+
+      case 'console':
+        return {
+          level: 'info',
+          message: 'Mock console message',
+          args: ['Mock', 'console', 'message'],
+          source: { file: 'test.js', line: 42, column: 10 },
+          method: 'log'
+        };
+
+      default:
+        return { mockData: true, type };
+    }
+  },
+
+  /**
+   * Performance test helper
+   * @param {Function} fn - Function to test
+   * @param {number} iterations - Number of iterations
+   * @returns {Object} Performance results
+   */
+  async performanceTest(fn, iterations = 1000) {
+    const start = performance.now();
+    const results = [];
+
+    for (let i = 0; i < iterations; i++) {
+      const iterStart = performance.now();
+      await fn(i);
+      const iterEnd = performance.now();
+      results.push(iterEnd - iterStart);
+    }
+
+    const end = performance.now();
+    const total = end - start;
+    const avg = results.reduce((a, b) => a + b, 0) / results.length;
+    const min = Math.min(...results);
+    const max = Math.max(...results);
+
+    return {
+      total,
+      average: avg,
+      min,
+      max,
+      iterations,
+      opsPerSecond: iterations / (total / 1000)
+    };
+  }
+};
+
+/**
+ * Version and metadata
+ */
+export const META = {
+  version: '1.0.0',
+  name: 'Unified Interaction Capture System',
+  description: 'Modular capture system replacing legacy frame, workflow, and function recording',
+  architecture: 'event-driven modular pipeline',
+  compatibility: {
+    chrome: '>=90',
+    node: '>=14',
+    databases: ['sqlite', 'postgresql', 'mongodb'],
+    storage: ['filesystem', 'memory', 's3', 'gcs']
+  },
+  features: [
+    'unified-event-format',
+    'modular-architecture',
+    'memory-optimization',
+    'chrome-extension-support',
+    'real-time-processing',
+    'advanced-analytics',
+    'extensible-design',
+    'performance-optimized'
+  ]
+};
+
+export default {
+  createCaptureSystem,
+  createStorage,
+  createChromeExtensionSource,
+  createPuppeteerSource,
+  validateCaptureEvent,
+  estimateEventMemoryUsage,
+  createCaptureEvent,
+  DevUtils,
+  META
+};