@dynamicu/chromedebug-mcp 2.2.0

package/src/capture/interfaces.js

@@ -0,0 +1,625 @@
+/**
+ * Unified Interaction Capture System - Module Interfaces
+ *
+ * This module defines clean interfaces between capture system components.
+ * Each interface can be implemented independently, enabling parallel development.
+ *
+ * ARCHITECTURE BOUNDARIES:
+ * ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+ * │ CaptureSource   │───▶│ CaptureCollector │───▶│ CaptureProcessor│
+ * │ (Chrome Ext)    │    │ (Event Router)   │    │ (Transform)     │
+ * └─────────────────┘    └──────────────────┘    └─────────────────┘
+ *                                                           │
+ * ┌─────────────────┐    ┌──────────────────┐              ▼
+ * │ CaptureQuery    │◀───│ CaptureStorage   │    ┌─────────────────┐
+ * │ (Search/Filter) │    │ (Persistence)    │◀───│ CaptureAnalyzer │
+ * └─────────────────┘    └──────────────────┘    │ (Processing)    │
+ *                                                 └─────────────────┘
+ */
+
+import { CaptureEvent, CaptureSession } from './types.js';
+
+/**
+ * Interface for capture event sources (Chrome extension, Puppeteer, etc.)
+ *
+ * INDEPENDENCE: Can be implemented without knowledge of other modules
+ * TESTING: Easy to mock for unit tests
+ */
+export class ICaptureSource {
+  /**
+   * Initialize the capture source
+   * @param {Object} config - Source-specific configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureSource.initialize() must be implemented');
+  }
+
+  /**
+   * Start capturing events for a session
+   * @param {CaptureSession} session - Session to capture for
+   * @returns {Promise<void>}
+   */
+  async startCapture(session) {
+    throw new Error('ICaptureSource.startCapture() must be implemented');
+  }
+
+  /**
+   * Stop capturing events
+   * @returns {Promise<void>}
+   */
+  async stopCapture() {
+    throw new Error('ICaptureSource.stopCapture() must be implemented');
+  }
+
+  /**
+   * Register event handler for captured events
+   * @param {Function} handler - Function to handle events: (CaptureEvent) => void
+   */
+  onEvent(handler) {
+    throw new Error('ICaptureSource.onEvent() must be implemented');
+  }
+
+  /**
+   * Get current capture status
+   * @returns {Object} Status information
+   */
+  getStatus() {
+    throw new Error('ICaptureSource.getStatus() must be implemented');
+  }
+
+  /**
+   * Cleanup resources
+   * @returns {Promise<void>}
+   */
+  async dispose() {
+    throw new Error('ICaptureSource.dispose() must be implemented');
+  }
+}
+
+/**
+ * Interface for collecting and routing capture events
+ *
+ * RESPONSIBILITY: Route events from sources to processors
+ * INDEPENDENCE: Works with any source/processor implementation
+ */
+export class ICaptureCollector {
+  /**
+   * Initialize the collector
+   * @param {Object} config - Collector configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureCollector.initialize() must be implemented');
+  }
+
+  /**
+   * Register a capture source
+   * @param {ICaptureSource} source - Source to register
+   * @returns {Promise<void>}
+   */
+  async registerSource(source) {
+    throw new Error('ICaptureCollector.registerSource() must be implemented');
+  }
+
+  /**
+   * Register a capture processor
+   * @param {ICaptureProcessor} processor - Processor to register
+   * @returns {Promise<void>}
+   */
+  async registerProcessor(processor) {
+    throw new Error('ICaptureCollector.registerProcessor() must be implemented');
+  }
+
+  /**
+   * Start collecting events for a session
+   * @param {CaptureSession} session - Session to collect for
+   * @returns {Promise<void>}
+   */
+  async startCollection(session) {
+    throw new Error('ICaptureCollector.startCollection() must be implemented');
+  }
+
+  /**
+   * Stop collecting events
+   * @returns {Promise<void>}
+   */
+  async stopCollection() {
+    throw new Error('ICaptureCollector.stopCollection() must be implemented');
+  }
+
+  /**
+   * Get collection statistics
+   * @returns {Object} Collection stats
+   */
+  getStats() {
+    throw new Error('ICaptureCollector.getStats() must be implemented');
+  }
+}
+
+/**
+ * Interface for processing and transforming capture events
+ *
+ * RESPONSIBILITY: Transform, filter, and enrich events
+ * INDEPENDENCE: Can process any CaptureEvent without knowing source
+ */
+export class ICaptureProcessor {
+  /**
+   * Initialize the processor
+   * @param {Object} config - Processor configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureProcessor.initialize() must be implemented');
+  }
+
+  /**
+   * Process a capture event
+   * @param {CaptureEvent} event - Event to process
+   * @returns {Promise<CaptureEvent|CaptureEvent[]|null>} Processed event(s) or null to drop
+   */
+  async processEvent(event) {
+    throw new Error('ICaptureProcessor.processEvent() must be implemented');
+  }
+
+  /**
+   * Process multiple events as a batch
+   * @param {CaptureEvent[]} events - Events to process
+   * @returns {Promise<CaptureEvent[]>} Processed events
+   */
+  async processBatch(events) {
+    // Default implementation processes individually
+    const results = [];
+    for (const event of events) {
+      const processed = await this.processEvent(event);
+      if (processed) {
+        if (Array.isArray(processed)) {
+          results.push(...processed);
+        } else {
+          results.push(processed);
+        }
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Get processor capabilities
+   * @returns {Object} Processor capabilities
+   */
+  getCapabilities() {
+    return {
+      supportedTypes: ['*'], // Types this processor handles
+      canBatch: false,       // Whether it supports batch processing
+      canStream: false,      // Whether it supports streaming
+      priority: 'normal'     // Processing priority
+    };
+  }
+}
+
+/**
+ * Interface for storing capture events
+ *
+ * RESPONSIBILITY: Persist events to storage (database, files, etc.)
+ * INDEPENDENCE: Can store any CaptureEvent without knowing source/processor
+ */
+export class ICaptureStorage {
+  /**
+   * Initialize the storage
+   * @param {Object} config - Storage configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureStorage.initialize() must be implemented');
+  }
+
+  /**
+   * Store a single event
+   * @param {CaptureEvent} event - Event to store
+   * @returns {Promise<string>} Stored event ID
+   */
+  async storeEvent(event) {
+    throw new Error('ICaptureStorage.storeEvent() must be implemented');
+  }
+
+  /**
+   * Store multiple events efficiently
+   * @param {CaptureEvent[]} events - Events to store
+   * @returns {Promise<string[]>} Stored event IDs
+   */
+  async storeEvents(events) {
+    // Default implementation stores individually
+    const ids = [];
+    for (const event of events) {
+      const id = await this.storeEvent(event);
+      ids.push(id);
+    }
+    return ids;
+  }
+
+  /**
+   * Store session metadata
+   * @param {CaptureSession} session - Session to store
+   * @returns {Promise<string>} Stored session ID
+   */
+  async storeSession(session) {
+    throw new Error('ICaptureStorage.storeSession() must be implemented');
+  }
+
+  /**
+   * Update session metadata
+   * @param {string} sessionId - Session ID to update
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<void>}
+   */
+  async updateSession(sessionId, updates) {
+    throw new Error('ICaptureStorage.updateSession() must be implemented');
+  }
+
+  /**
+   * Get storage statistics
+   * @returns {Promise<Object>} Storage statistics
+   */
+  async getStats() {
+    throw new Error('ICaptureStorage.getStats() must be implemented');
+  }
+
+  /**
+   * Cleanup old data
+   * @param {Object} criteria - Cleanup criteria
+   * @returns {Promise<Object>} Cleanup results
+   */
+  async cleanup(criteria) {
+    throw new Error('ICaptureStorage.cleanup() must be implemented');
+  }
+}
+
+/**
+ * Interface for querying and analyzing capture data
+ *
+ * RESPONSIBILITY: Search, filter, and analyze stored events
+ * INDEPENDENCE: Can query any stored CaptureEvent format
+ */
+export class ICaptureQuery {
+  /**
+   * Initialize the query engine
+   * @param {ICaptureStorage} storage - Storage to query
+   * @returns {Promise<void>}
+   */
+  async initialize(storage) {
+    throw new Error('ICaptureQuery.initialize() must be implemented');
+  }
+
+  /**
+   * Query events by criteria
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options (pagination, sorting)
+   * @returns {Promise<Object>} Query results with events and metadata
+   */
+  async queryEvents(criteria, options = {}) {
+    throw new Error('ICaptureQuery.queryEvents() must be implemented');
+  }
+
+  /**
+   * Get session by ID
+   * @param {string} sessionId - Session ID
+   * @returns {Promise<CaptureSession|null>} Session data
+   */
+  async getSession(sessionId) {
+    throw new Error('ICaptureQuery.getSession() must be implemented');
+  }
+
+  /**
+   * List all sessions
+   * @param {Object} options - List options
+   * @returns {Promise<CaptureSession[]>} Session list
+   */
+  async listSessions(options = {}) {
+    throw new Error('ICaptureQuery.listSessions() must be implemented');
+  }
+
+  /**
+   * Search events by text
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<Object>} Search results
+   */
+  async searchEvents(query, options = {}) {
+    throw new Error('ICaptureQuery.searchEvents() must be implemented');
+  }
+
+  /**
+   * Get event statistics
+   * @param {Object} criteria - Statistics criteria
+   * @returns {Promise<Object>} Event statistics
+   */
+  async getEventStats(criteria = {}) {
+    throw new Error('ICaptureQuery.getEventStats() must be implemented');
+  }
+}
+
+/**
+ * Interface for analyzing capture data patterns
+ *
+ * RESPONSIBILITY: Extract insights and patterns from events
+ * INDEPENDENCE: Can analyze any CaptureEvent data
+ */
+export class ICaptureAnalyzer {
+  /**
+   * Initialize the analyzer
+   * @param {ICaptureQuery} query - Query interface for data access
+   * @returns {Promise<void>}
+   */
+  async initialize(query) {
+    throw new Error('ICaptureAnalyzer.initialize() must be implemented');
+  }
+
+  /**
+   * Analyze user interaction patterns
+   * @param {string} sessionId - Session to analyze
+   * @returns {Promise<Object>} Interaction analysis
+   */
+  async analyzeInteractions(sessionId) {
+    throw new Error('ICaptureAnalyzer.analyzeInteractions() must be implemented');
+  }
+
+  /**
+   * Analyze performance patterns
+   * @param {string} sessionId - Session to analyze
+   * @returns {Promise<Object>} Performance analysis
+   */
+  async analyzePerformance(sessionId) {
+    throw new Error('ICaptureAnalyzer.analyzePerformance() must be implemented');
+  }
+
+  /**
+   * Detect errors and issues
+   * @param {string} sessionId - Session to analyze
+   * @returns {Promise<Object>} Error analysis
+   */
+  async detectErrors(sessionId) {
+    throw new Error('ICaptureAnalyzer.detectErrors() must be implemented');
+  }
+
+  /**
+   * Generate session summary
+   * @param {string} sessionId - Session to summarize
+   * @returns {Promise<Object>} Session summary
+   */
+  async generateSummary(sessionId) {
+    throw new Error('ICaptureAnalyzer.generateSummary() must be implemented');
+  }
+
+  /**
+   * Compare multiple sessions
+   * @param {string[]} sessionIds - Sessions to compare
+   * @returns {Promise<Object>} Comparison results
+   */
+  async compareSessions(sessionIds) {
+    throw new Error('ICaptureAnalyzer.compareSessions() must be implemented');
+  }
+}
+
+/**
+ * Interface for memory management and optimization
+ *
+ * RESPONSIBILITY: Manage memory usage and optimize performance
+ * INDEPENDENCE: Can manage any capture system component
+ */
+export class ICaptureMemoryManager {
+  /**
+   * Initialize the memory manager
+   * @param {Object} config - Memory management configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureMemoryManager.initialize() must be implemented');
+  }
+
+  /**
+   * Check current memory usage
+   * @returns {Promise<Object>} Memory usage statistics
+   */
+  async getMemoryUsage() {
+    throw new Error('ICaptureMemoryManager.getMemoryUsage() must be implemented');
+  }
+
+  /**
+   * Request memory cleanup
+   * @param {string} [priority='normal'] - Cleanup priority
+   * @returns {Promise<Object>} Cleanup results
+   */
+  async requestCleanup(priority = 'normal') {
+    throw new Error('ICaptureMemoryManager.requestCleanup() must be implemented');
+  }
+
+  /**
+   * Set memory limits
+   * @param {Object} limits - Memory limits configuration
+   * @returns {Promise<void>}
+   */
+  async setLimits(limits) {
+    throw new Error('ICaptureMemoryManager.setLimits() must be implemented');
+  }
+
+  /**
+   * Register component for memory monitoring
+   * @param {string} componentId - Component identifier
+   * @param {Object} component - Component to monitor
+   * @returns {Promise<void>}
+   */
+  async registerComponent(componentId, component) {
+    throw new Error('ICaptureMemoryManager.registerComponent() must be implemented');
+  }
+}
+
+/**
+ * Error handling interface for capture system
+ *
+ * RESPONSIBILITY: Standardized error handling across all modules
+ * INDEPENDENCE: Can handle errors from any capture component
+ */
+export class ICaptureErrorHandler {
+  /**
+   * Initialize the error handler
+   * @param {Object} config - Error handling configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureErrorHandler.initialize() must be implemented');
+  }
+
+  /**
+   * Handle capture error
+   * @param {Error} error - Error to handle
+   * @param {Object} context - Error context
+   * @returns {Promise<void>}
+   */
+  async handleError(error, context) {
+    throw new Error('ICaptureErrorHandler.handleError() must be implemented');
+  }
+
+  /**
+   * Get error statistics
+   * @returns {Promise<Object>} Error statistics
+   */
+  async getErrorStats() {
+    throw new Error('ICaptureErrorHandler.getErrorStats() must be implemented');
+  }
+
+  /**
+   * Register error recovery strategy
+   * @param {string} errorType - Type of error
+   * @param {Function} recoveryFn - Recovery function
+   * @returns {Promise<void>}
+   */
+  async registerRecovery(errorType, recoveryFn) {
+    throw new Error('ICaptureErrorHandler.registerRecovery() must be implemented');
+  }
+}
+
+/**
+ * Main capture system coordinator interface
+ *
+ * RESPONSIBILITY: Coordinate all capture system components
+ * INDEPENDENCE: Orchestrates but doesn't implement specific capture logic
+ */
+export class ICaptureSystem {
+  /**
+   * Initialize the complete capture system
+   * @param {Object} config - System configuration
+   * @returns {Promise<void>}
+   */
+  async initialize(config) {
+    throw new Error('ICaptureSystem.initialize() must be implemented');
+  }
+
+  /**
+   * Start a new capture session
+   * @param {Object} sessionConfig - Session configuration
+   * @returns {Promise<CaptureSession>} Created session
+   */
+  async startSession(sessionConfig) {
+    throw new Error('ICaptureSystem.startSession() must be implemented');
+  }
+
+  /**
+   * Stop the current capture session
+   * @returns {Promise<void>}
+   */
+  async stopSession() {
+    throw new Error('ICaptureSystem.stopSession() must be implemented');
+  }
+
+  /**
+   * Get system status
+   * @returns {Promise<Object>} System status
+   */
+  async getStatus() {
+    throw new Error('ICaptureSystem.getStatus() must be implemented');
+  }
+
+  /**
+   * Shutdown the capture system
+   * @returns {Promise<void>}
+   */
+  async shutdown() {
+    throw new Error('ICaptureSystem.shutdown() must be implemented');
+  }
+}
+
+/**
+ * Module registry for dependency injection and testing
+ */
+export class CaptureModuleRegistry {
+  constructor() {
+    this.modules = new Map();
+    this.instances = new Map();
+  }
+
+  /**
+   * Register a module implementation
+   * @param {string} interfaceName - Interface name
+   * @param {Class} implementation - Implementation class
+   */
+  register(interfaceName, implementation) {
+    this.modules.set(interfaceName, implementation);
+  }
+
+  /**
+   * Get module implementation
+   * @param {string} interfaceName - Interface name
+   * @returns {Class} Implementation class
+   */
+  get(interfaceName) {
+    return this.modules.get(interfaceName);
+  }
+
+  /**
+   * Create module instance
+   * @param {string} interfaceName - Interface name
+   * @param {...any} args - Constructor arguments
+   * @returns {Object} Module instance
+   */
+  create(interfaceName, ...args) {
+    const Implementation = this.modules.get(interfaceName);
+    if (!Implementation) {
+      throw new Error(`No implementation registered for ${interfaceName}`);
+    }
+    return new Implementation(...args);
+  }
+
+  /**
+   * Get or create singleton instance
+   * @param {string} interfaceName - Interface name
+   * @param {...any} args - Constructor arguments
+   * @returns {Object} Module instance
+   */
+  getInstance(interfaceName, ...args) {
+    if (!this.instances.has(interfaceName)) {
+      this.instances.set(interfaceName, this.create(interfaceName, ...args));
+    }
+    return this.instances.get(interfaceName);
+  }
+
+  /**
+   * Clear all registrations
+   */
+  clear() {
+    this.modules.clear();
+    this.instances.clear();
+  }
+}
+
+// Export all interfaces for easy importing
+export {
+  ICaptureSource,
+  ICaptureCollector,
+  ICaptureProcessor,
+  ICaptureStorage,
+  ICaptureQuery,
+  ICaptureAnalyzer,
+  ICaptureMemoryManager,
+  ICaptureErrorHandler,
+  ICaptureSystem
+};