@devilsdev/rag-pipeline-utils 2.2.1 → 2.3.0

package/src/dev/dev-server.js

@@ -0,0 +1,356 @@
+'use strict';
+
+/**
+ * Development Server with Hot Reload Support
+ *
+ * Provides a development server with integrated hot reloading
+ * for rapid plugin and configuration development.
+ *
+ * Features:
+ * - Automatic hot reloading of plugins and configuration
+ * - Live feedback on reload status
+ * - Error notifications
+ * - Statistics dashboard
+ * - WebSocket support for real-time updates (optional)
+ *
+ * @module dev/dev-server
+ * @since 2.4.0
+ */
+
+const { EventEmitter } = require('events');
+const { createHotReloadManager } = require('./hot-reload');
+const logger = require('../utils/logger');
+
+/**
+ * Development Server
+ *
+ * Integrates hot reloading with a development workflow
+ */
+class DevServer extends EventEmitter {
+  constructor(options = {}) {
+    super();
+
+    this.options = {
+      port: options.port || 3000,
+      host: options.host || 'localhost',
+      watchPaths: options.watchPaths || ['./src/plugins', './src/mocks'],
+      configPath: options.configPath || '.ragrc.json',
+      verbose: options.verbose !== false,
+      autoReload: options.autoReload !== false,
+      notifyOnReload: options.notifyOnReload !== false,
+      pluginRegistry: options.pluginRegistry || null,
+      pipeline: options.pipeline || null,
+      ...options,
+    };
+
+    // Create hot reload manager
+    this.hotReload = createHotReloadManager({
+      enabled: this.options.autoReload,
+      watchPaths: this.options.watchPaths,
+      configPath: this.options.configPath,
+      verbose: this.options.verbose,
+      pluginRegistry: this.options.pluginRegistry,
+      preserveState: true,
+    });
+
+    this.isRunning = false;
+    this.startTime = null;
+
+    // Setup hot reload event handlers
+    this._setupHotReloadHandlers();
+  }
+
+  /**
+   * Setup hot reload event handlers
+   *
+   * @private
+   */
+  _setupHotReloadHandlers() {
+    // Plugin reloaded
+    this.hotReload.on('plugin:reloaded', ({ path, duration }) => {
+      this._log(`✓ Plugin reloaded: ${path} (${duration}ms)`, 'success');
+      this.emit('plugin:reloaded', { path, duration });
+
+      if (this.options.notifyOnReload) {
+        this._notify(`Plugin reloaded: ${path}`, 'success');
+      }
+    });
+
+    // Plugin reload failed
+    this.hotReload.on('plugin:reload-failed', ({ path, error }) => {
+      this._log(`✗ Plugin reload failed: ${path} - ${error}`, 'error');
+      this.emit('plugin:reload-failed', { path, error });
+
+      if (this.options.notifyOnReload) {
+        this._notify(`Plugin reload failed: ${path}`, 'error');
+      }
+    });
+
+    // Config reloaded
+    this.hotReload.on('config:reloaded', ({ path, duration }) => {
+      this._log(`✓ Configuration reloaded: ${path} (${duration}ms)`, 'success');
+      this.emit('config:reloaded', { path, duration });
+
+      if (this.options.notifyOnReload) {
+        this._notify(`Configuration reloaded`, 'success');
+      }
+
+      // Reinitialize pipeline if provided
+      if (this.options.pipeline && this.options.pipeline.reinitialize) {
+        this.options.pipeline.reinitialize();
+      }
+    });
+
+    // Config reload failed
+    this.hotReload.on('config:reload-failed', ({ path, error }) => {
+      this._log(`✗ Configuration reload failed: ${path} - ${error}`, 'error');
+      this.emit('config:reload-failed', { path, error });
+
+      if (this.options.notifyOnReload) {
+        this._notify(`Configuration reload failed`, 'error');
+      }
+    });
+
+    // Plugin added
+    this.hotReload.on('plugin:added', ({ path }) => {
+      this._log(`+ New plugin detected: ${path}`, 'info');
+      this.emit('plugin:added', { path });
+    });
+
+    // Plugin removed
+    this.hotReload.on('plugin:removed', ({ path }) => {
+      this._log(`- Plugin removed: ${path}`, 'info');
+      this.emit('plugin:removed', { path });
+    });
+
+    // Error
+    this.hotReload.on('error', ({ message, error }) => {
+      this._log(`ERROR: ${message} - ${error}`, 'error');
+      this.emit('error', { message, error });
+    });
+  }
+
+  /**
+   * Start the development server
+   *
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this.isRunning) {
+      this._log('Development server is already running', 'warn');
+      return;
+    }
+
+    this._log('Starting development server...', 'info');
+    this.startTime = Date.now();
+
+    // Start hot reload
+    await this.hotReload.start();
+
+    this.isRunning = true;
+
+    this._log(
+      `Development server started on ${this.options.host}:${this.options.port}`,
+      'success',
+    );
+    this._log(`Watching: ${this.options.watchPaths.join(', ')}`, 'info');
+    this._log(
+      'Hot reload enabled - changes will be applied automatically',
+      'info',
+    );
+    this._log('Press Ctrl+C to stop', 'info');
+
+    this.emit('started');
+  }
+
+  /**
+   * Stop the development server
+   *
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (!this.isRunning) {
+      return;
+    }
+
+    this._log('Stopping development server...', 'info');
+
+    // Stop hot reload
+    await this.hotReload.stop();
+
+    this.isRunning = false;
+
+    const uptime = this.startTime ? Date.now() - this.startTime : 0;
+    this._log(
+      `Development server stopped (uptime: ${this._formatDuration(uptime)})`,
+      'info',
+    );
+
+    this.emit('stopped');
+  }
+
+  /**
+   * Get server status
+   *
+   * @returns {object} Server status
+   */
+  getStatus() {
+    const stats = this.hotReload.getStats();
+    const uptime = this.startTime ? Date.now() - this.startTime : 0;
+
+    return {
+      isRunning: this.isRunning,
+      uptime,
+      host: this.options.host,
+      port: this.options.port,
+      watchPaths: this.options.watchPaths,
+      configPath: this.options.configPath,
+      hotReload: {
+        enabled: this.options.autoReload,
+        stats,
+      },
+    };
+  }
+
+  /**
+   * Get statistics dashboard
+   *
+   * @returns {string} Formatted statistics
+   */
+  getStatistics() {
+    const stats = this.hotReload.getStats();
+    const uptime = this.startTime ? Date.now() - this.startTime : 0;
+
+    return `
+╔════════════════════════════════════════════════════════════════╗
+║                   Development Server Statistics                ║
+╠════════════════════════════════════════════════════════════════╣
+║ Status:              ${this.isRunning ? 'Running' : 'Stopped'}                              ║
+║ Uptime:              ${this._formatDuration(uptime).padEnd(39)}║
+║                                                                ║
+║ Hot Reload:                                                    ║
+║   Total Reloads:     ${String(stats.totalReloads).padEnd(39)}║
+║   Successful:        ${String(stats.successfulReloads).padEnd(39)}║
+║   Failed:            ${String(stats.failedReloads).padEnd(39)}║
+║   Plugin Reloads:    ${String(stats.pluginReloads).padEnd(39)}║
+║   Config Reloads:    ${String(stats.configReloads).padEnd(39)}║
+║   Avg Reload Time:   ${String(Math.round(stats.averageReloadTime) + 'ms').padEnd(39)}║
+║                                                                ║
+║ Watching:                                                      ║
+${this.options.watchPaths.map((p) => `║   - ${p.padEnd(56)}║`).join('\n')}
+╚════════════════════════════════════════════════════════════════╝
+    `.trim();
+  }
+
+  /**
+   * Manually trigger a reload
+   *
+   * @param {string} filePath - File path to reload
+   * @param {string} type - Type ('plugin' or 'config')
+   * @returns {Promise<void>}
+   */
+  async triggerReload(filePath, type = 'plugin') {
+    this._log(`Manually triggering reload: ${filePath}`, 'info');
+    await this.hotReload.triggerReload(filePath, type);
+  }
+
+  /**
+   * Register a lifecycle hook
+   *
+   * @param {string} hookName - Hook name
+   * @param {Function} callback - Hook callback
+   */
+  registerHook(hookName, callback) {
+    this.hotReload.registerHook(hookName, callback);
+  }
+
+  /**
+   * Unregister a lifecycle hook
+   *
+   * @param {string} hookName - Hook name
+   * @param {Function} callback - Hook callback
+   */
+  unregisterHook(hookName, callback) {
+    this.hotReload.unregisterHook(hookName, callback);
+  }
+
+  /**
+   * Log message
+   *
+   * @private
+   * @param {string} message - Log message
+   * @param {string} level - Log level
+   */
+  _log(message, level = 'info') {
+    if (!this.options.verbose && level === 'info') {
+      return;
+    }
+
+    const prefix = '[DevServer]';
+
+    switch (level) {
+      case 'success':
+        console.log(`${prefix} ✓ ${message}`);
+        break;
+      case 'error':
+        console.error(`${prefix} ✗ ${message}`);
+        break;
+      case 'warn':
+        console.warn(`${prefix} ⚠ ${message}`);
+        break;
+      case 'info':
+      default:
+        console.log(`${prefix} ${message}`);
+        break;
+    }
+  }
+
+  /**
+   * Send notification
+   *
+   * @private
+   * @param {string} message - Notification message
+   * @param {string} type - Notification type
+   */
+  _notify(message, type = 'info') {
+    // In a real implementation, this could send desktop notifications
+    // or WebSocket messages to connected clients
+    this.emit('notification', { message, type, timestamp: new Date() });
+  }
+
+  /**
+   * Format duration
+   *
+   * @private
+   * @param {number} ms - Duration in milliseconds
+   * @returns {string} Formatted duration
+   */
+  _formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+    } else if (minutes > 0) {
+      return `${minutes}m ${seconds % 60}s`;
+    } else {
+      return `${seconds}s`;
+    }
+  }
+}
+
+/**
+ * Create development server
+ *
+ * @param {object} options - Server options
+ * @returns {DevServer} Development server instance
+ */
+function createDevServer(options = {}) {
+  return new DevServer(options);
+}
+
+module.exports = {
+  DevServer,
+  createDevServer,
+};

package/src/dev/examples/hot-reload-usage.js

@@ -0,0 +1,355 @@
+'use strict';
+
+/**
+ * Hot Reload Usage Examples
+ *
+ * This file demonstrates various ways to use the hot reload functionality
+ * in development environments.
+ */
+
+const { createHotReloadManager } = require('../hot-reload');
+const { createDevServer } = require('../dev-server');
+const { createRagPipeline } = require('../../core/create-pipeline');
+const pluginRegistry = require('../../core/plugin-registry');
+
+// ============================================================================
+// Example 1: Basic Hot Reload Setup
+// ============================================================================
+
+function basicHotReloadExample() {
+  console.log('\n=== Example 1: Basic Hot Reload ===\n');
+
+  // Create hot reload manager
+  const hotReload = createHotReloadManager({
+    enabled: true,
+    watchPaths: ['./src/plugins', './src/mocks'],
+    configPath: '.ragrc.json',
+    verbose: true,
+  });
+
+  // Listen to events
+  hotReload.on('plugin:reloaded', ({ path, duration }) => {
+    console.log(`Plugin reloaded: ${path} in ${duration}ms`);
+  });
+
+  hotReload.on('config:reloaded', ({ config }) => {
+    console.log('Configuration reloaded:', config.metadata?.name);
+  });
+
+  // Start watching
+  hotReload.start().then(() => {
+    console.log('Hot reload started');
+  });
+
+  // To stop:
+  // hotReload.stop();
+}
+
+// ============================================================================
+// Example 2: Hot Reload with Plugin Registry Integration
+// ============================================================================
+
+async function hotReloadWithRegistryExample() {
+  console.log('\n=== Example 2: Hot Reload with Plugin Registry ===\n');
+
+  // Create hot reload manager with plugin registry
+  const hotReload = createHotReloadManager({
+    enabled: true,
+    watchPaths: ['./src/plugins'],
+    pluginRegistry: pluginRegistry,
+    verbose: true,
+    preserveState: true, // Preserve plugin state during reloads
+  });
+
+  // Register hooks for advanced control
+  hotReload.registerHook('beforeReload', async (data) => {
+    console.log(`About to reload ${data.type}: ${data.path}`);
+    // Perform any cleanup or preparation
+  });
+
+  hotReload.registerHook('afterReload', async (data) => {
+    console.log(`Reload completed for ${data.type}: ${data.path}`);
+    // Re-register with plugin registry, update references, etc.
+  });
+
+  hotReload.registerHook('onError', async ({ message, error }) => {
+    console.error(`Reload error: ${message}`, error);
+    // Send notification, log to service, etc.
+  });
+
+  await hotReload.start();
+
+  // Get statistics
+  setInterval(() => {
+    const stats = hotReload.getStats();
+    console.log('Reload Stats:', {
+      total: stats.totalReloads,
+      successful: stats.successfulReloads,
+      failed: stats.failedReloads,
+      avgTime: Math.round(stats.averageReloadTime) + 'ms',
+    });
+  }, 60000); // Every minute
+}
+
+// ============================================================================
+// Example 3: Development Server with Hot Reload
+// ============================================================================
+
+async function devServerExample() {
+  console.log('\n=== Example 3: Development Server ===\n');
+
+  // Create development server with integrated hot reload
+  const devServer = createDevServer({
+    port: 3000,
+    host: 'localhost',
+    watchPaths: ['./src/plugins', './src/mocks'],
+    configPath: '.ragrc.json',
+    verbose: true,
+    autoReload: true,
+    notifyOnReload: true,
+  });
+
+  // Listen to server events
+  devServer.on('started', () => {
+    console.log('Development server started');
+    console.log(devServer.getStatistics());
+  });
+
+  devServer.on('plugin:reloaded', ({ path, duration }) => {
+    console.log(`✓ Plugin reloaded: ${path} (${duration}ms)`);
+  });
+
+  devServer.on('config:reloaded', ({ path, duration }) => {
+    console.log(`✓ Config reloaded: ${path} (${duration}ms)`);
+  });
+
+  devServer.on('notification', ({ message, type }) => {
+    console.log(`[${type.toUpperCase()}] ${message}`);
+  });
+
+  // Start the server
+  await devServer.start();
+
+  // Display statistics periodically
+  setInterval(() => {
+    console.log(devServer.getStatistics());
+  }, 300000); // Every 5 minutes
+
+  // Handle graceful shutdown
+  process.on('SIGINT', async () => {
+    console.log('\nShutting down...');
+    await devServer.stop();
+    process.exit(0);
+  });
+}
+
+// ============================================================================
+// Example 4: Hot Reload with RAG Pipeline
+// ============================================================================
+
+async function hotReloadWithPipelineExample() {
+  console.log('\n=== Example 4: Hot Reload with Pipeline ===\n');
+
+  // Create pipeline
+  const pipeline = await createRagPipeline({
+    configPath: '.ragrc.json',
+  });
+
+  // Create dev server with pipeline integration
+  const devServer = createDevServer({
+    watchPaths: ['./src/plugins', './src/mocks'],
+    configPath: '.ragrc.json',
+    verbose: true,
+    pluginRegistry: pluginRegistry,
+    pipeline: pipeline,
+  });
+
+  // When config changes, pipeline will be reinitialized automatically
+  devServer.on('config:reloaded', async () => {
+    console.log('Pipeline configuration updated');
+    // Pipeline is automatically reinitialized by dev server
+  });
+
+  // When plugins change, they're hot-reloaded
+  devServer.on('plugin:reloaded', async ({ path }) => {
+    console.log(`Plugin ${path} updated and reloaded`);
+    // Plugin is automatically updated in registry
+  });
+
+  await devServer.start();
+}
+
+// ============================================================================
+// Example 5: Custom State Preservation
+// ============================================================================
+
+async function customStatePreservationExample() {
+  console.log('\n=== Example 5: Custom State Preservation ===\n');
+
+  const hotReload = createHotReloadManager({
+    enabled: true,
+    watchPaths: ['./src/plugins'],
+    preserveState: true,
+    verbose: true,
+  });
+
+  // Hook into state preservation
+  hotReload.registerHook('onStatePreserve', async ({ path, state }) => {
+    console.log(`Preserving state for ${path}:`, state);
+    // You can save state to external storage here
+  });
+
+  hotReload.registerHook('onStateRestore', async ({ plugin, state }) => {
+    console.log('Restoring state:', state);
+    // You can restore state from external storage here
+  });
+
+  await hotReload.start();
+}
+
+// ============================================================================
+// Example 6: Manual Reload Triggering
+// ============================================================================
+
+async function manualReloadExample() {
+  console.log('\n=== Example 6: Manual Reload ===\n');
+
+  const devServer = createDevServer({
+    watchPaths: ['./src/plugins'],
+    autoReload: false, // Disable automatic reloading
+    verbose: true,
+  });
+
+  await devServer.start();
+
+  // Manually trigger reloads
+  await devServer.triggerReload('./src/plugins/my-plugin.js', 'plugin');
+  await devServer.triggerReload('.ragrc.json', 'config');
+
+  console.log('Manual reloads completed');
+}
+
+// ============================================================================
+// Example 7: Configuration Validation
+// ============================================================================
+
+async function configValidationExample() {
+  console.log('\n=== Example 7: Config Validation ===\n');
+
+  const hotReload = createHotReloadManager({
+    enabled: true,
+    configPath: '.ragrc.json',
+    verbose: true,
+    // Custom config validator
+    configValidator: (config) => {
+      const errors = [];
+
+      // Validate required fields
+      if (!config.metadata || !config.metadata.name) {
+        errors.push({ message: 'metadata.name is required' });
+      }
+
+      if (!config.pipeline || !config.pipeline.stages) {
+        errors.push({ message: 'pipeline.stages is required' });
+      }
+
+      return {
+        valid: errors.length === 0,
+        errors,
+      };
+    },
+  });
+
+  hotReload.on('config:reload-failed', ({ error }) => {
+    console.error('Configuration validation failed:', error);
+  });
+
+  await hotReload.start();
+}
+
+// ============================================================================
+// Example 8: Development Workflow Integration
+// ============================================================================
+
+async function developmentWorkflowExample() {
+  console.log('\n=== Example 8: Complete Development Workflow ===\n');
+
+  // Create a complete development environment
+  const devServer = createDevServer({
+    port: 3000,
+    host: 'localhost',
+    watchPaths: ['./src/plugins', './src/mocks', './src/config'],
+    configPath: '.ragrc.json',
+    verbose: true,
+    autoReload: true,
+    notifyOnReload: true,
+    pluginRegistry: pluginRegistry,
+  });
+
+  // Add custom hooks
+  devServer.registerHook('beforeReload', async (data) => {
+    console.log(`[BEFORE] Reloading ${data.type}: ${data.path}`);
+    // Run pre-reload tasks (tests, linting, etc.)
+  });
+
+  devServer.registerHook('afterReload', async (data) => {
+    console.log(`[AFTER] Reloaded ${data.type}: ${data.path}`);
+    // Run post-reload tasks (smoke tests, notifications, etc.)
+  });
+
+  // Start server
+  await devServer.start();
+
+  // Log status every 5 minutes
+  setInterval(() => {
+    const status = devServer.getStatus();
+    console.log('\n=== Server Status ===');
+    console.log(`Uptime: ${Math.floor(status.uptime / 1000)}s`);
+    console.log(`Total Reloads: ${status.hotReload.stats.totalReloads}`);
+    console.log(
+      `Success Rate: ${
+        status.hotReload.stats.totalReloads > 0
+          ? Math.round(
+              (status.hotReload.stats.successfulReloads /
+                status.hotReload.stats.totalReloads) *
+                100,
+            ) + '%'
+          : 'N/A'
+      }`,
+    );
+  }, 300000);
+
+  // Handle shutdown
+  process.on('SIGINT', async () => {
+    console.log('\n\nShutting down development server...');
+    console.log(devServer.getStatistics());
+    await devServer.stop();
+    process.exit(0);
+  });
+}
+
+// ============================================================================
+// Run Examples
+// ============================================================================
+
+// Uncomment the example you want to run:
+
+// basicHotReloadExample();
+// hotReloadWithRegistryExample();
+// devServerExample();
+// hotReloadWithPipelineExample();
+// customStatePreservationExample();
+// manualReloadExample();
+// configValidationExample();
+// developmentWorkflowExample();
+
+module.exports = {
+  basicHotReloadExample,
+  hotReloadWithRegistryExample,
+  devServerExample,
+  hotReloadWithPipelineExample,
+  customStatePreservationExample,
+  manualReloadExample,
+  configValidationExample,
+  developmentWorkflowExample,
+};