@tamyla/clodo-framework 1.0.0

package/dist/shared/utils/graceful-shutdown-manager.js

@@ -0,0 +1,380 @@
+/**
+ * Graceful Shutdown Manager
+ * Implements SIGTERM/SIGINT handlers and cleanup routines for CLI tools
+ */
+
+export class GracefulShutdownManager {
+  constructor(options = {}) {
+    this.options = options;
+    this.config = null;
+    this.isShuttingDown = false;
+    this.shutdownHandlers = [];
+    this.shutdownPromise = null;
+    this.registered = false;
+  }
+
+  /**
+   * Initialize with framework configuration
+   */
+  async initialize() {
+    // Import framework config for consistent timing
+    const {
+      frameworkConfig
+    } = await import('../../../src/utils/framework-config.js');
+    const timing = frameworkConfig.getTiming();
+    this.config = {
+      shutdownTimeout: this.options.shutdownTimeout || timing.shutdownTimeout,
+      forceShutdownTimeout: this.options.forceShutdownTimeout || timing.forceShutdownTimeout,
+      enableLogging: this.options.enableLogging !== false,
+      ...this.options
+    };
+  }
+
+  /**
+   * Register the shutdown manager
+   */
+  register() {
+    if (this.registered) return;
+    this.registered = true;
+
+    // Register signal handlers
+    process.on('SIGTERM', () => this.initiateShutdown('SIGTERM'));
+    process.on('SIGINT', () => this.initiateShutdown('SIGINT'));
+
+    // Handle uncaught exceptions and unhandled rejections
+    process.on('uncaughtException', error => {
+      console.error('💥 Uncaught exception:', error);
+      this.initiateShutdown('uncaughtException', error);
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+      console.error('💥 Unhandled rejection at:', promise, 'reason:', reason);
+      this.initiateShutdown('unhandledRejection', reason);
+    });
+    if (this.config.enableLogging) {
+      console.log('🛑 Graceful shutdown manager registered');
+    }
+  }
+
+  /**
+   * Unregister the shutdown manager
+   */
+  unregister() {
+    if (!this.registered) return;
+    this.registered = false;
+    process.removeAllListeners('SIGTERM');
+    process.removeAllListeners('SIGINT');
+    process.removeAllListeners('uncaughtException');
+    process.removeAllListeners('unhandledRejection');
+    if (this.config.enableLogging) {
+      console.log('🛑 Graceful shutdown manager unregistered');
+    }
+  }
+
+  /**
+   * Add a shutdown handler
+   */
+  addShutdownHandler(handler, priority = 0) {
+    this.shutdownHandlers.push({
+      handler,
+      priority,
+      id: `handler_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+    });
+
+    // Sort by priority (higher priority first)
+    this.shutdownHandlers.sort((a, b) => b.priority - a.priority);
+
+    // Return removal function
+    return () => {
+      const index = this.shutdownHandlers.findIndex(h => h.id === this.id);
+      if (index !== -1) {
+        this.shutdownHandlers.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Remove a shutdown handler
+   */
+  removeShutdownHandler(handlerId) {
+    const index = this.shutdownHandlers.findIndex(h => h.id === handlerId);
+    if (index !== -1) {
+      this.shutdownHandlers.splice(index, 1);
+    }
+  }
+
+  /**
+   * Initiate graceful shutdown
+   */
+  async initiateShutdown(signal, error = null) {
+    if (this.isShuttingDown) return;
+    this.isShuttingDown = true;
+    if (this.config.enableLogging) {
+      console.log(`🛑 Initiating graceful shutdown: ${signal}`);
+      if (error) {
+        console.error('Shutdown triggered by error:', error);
+      }
+    }
+
+    // Prevent new work from starting
+    this.preventNewWork();
+
+    // Execute shutdown handlers
+    await this.executeShutdownHandlers(signal, error);
+
+    // Force exit if handlers don't complete in time
+    this.forceExitIfNeeded(signal);
+
+    // Exit with appropriate code
+    const exitCode = error ? 1 : 0;
+    process.exit(exitCode);
+  }
+
+  /**
+   * Prevent new work from starting
+   */
+  preventNewWork() {
+    // Set global shutdown flag
+    if (typeof global !== 'undefined') {
+      global.isShuttingDown = true;
+    }
+
+    // Prevent new database connections
+    if (typeof global !== 'undefined' && global.dbManagers) {
+      global.dbManagers.forEach(manager => {
+        if (typeof manager.preventNewConnections === 'function') {
+          manager.preventNewConnections();
+        }
+      });
+    }
+  }
+
+  /**
+   * Execute shutdown handlers
+   */
+  async executeShutdownHandlers(signal, error) {
+    const shutdownPromises = [];
+    for (const {
+      handler
+    } of this.shutdownHandlers) {
+      try {
+        const promise = handler(signal, error);
+        if (promise && typeof promise.then === 'function') {
+          shutdownPromises.push(promise);
+        }
+      } catch (handlerError) {
+        console.error('Error in shutdown handler:', handlerError);
+      }
+    }
+
+    // Wait for all handlers to complete or timeout
+    if (shutdownPromises.length > 0) {
+      try {
+        await Promise.race([Promise.all(shutdownPromises), new Promise(resolve => setTimeout(resolve, this.config.shutdownTimeout))]);
+      } catch (timeoutError) {
+        console.error('Shutdown handlers timed out:', timeoutError);
+      }
+    }
+  }
+
+  /**
+   * Force exit if needed
+   */
+  forceExitIfNeeded(signal) {
+    setTimeout(() => {
+      console.error(`💥 Force exiting after ${this.config.forceShutdownTimeout}ms`);
+      process.exit(1);
+    }, this.config.forceShutdownTimeout).unref();
+  }
+
+  /**
+   * Create a shutdown-aware interval
+   */
+  createShutdownAwareInterval(callback, delay) {
+    const intervalId = setInterval(() => {
+      if (this.isShuttingDown) {
+        clearInterval(intervalId);
+        return;
+      }
+      try {
+        callback();
+      } catch (error) {
+        console.error('Error in shutdown-aware interval:', error);
+        clearInterval(intervalId);
+      }
+    }, delay);
+    intervalId.unref?.();
+
+    // Add cleanup handler
+    this.addShutdownHandler(() => {
+      clearInterval(intervalId);
+    }, 100); // High priority
+
+    return intervalId;
+  }
+
+  /**
+   * Create a shutdown-aware timeout
+   */
+  createShutdownAwareTimeout(callback, delay) {
+    const timeoutId = setTimeout(() => {
+      if (this.isShuttingDown) return;
+      try {
+        callback();
+      } catch (error) {
+        console.error('Error in shutdown-aware timeout:', error);
+      }
+    }, delay);
+    timeoutId.unref?.();
+
+    // Add cleanup handler
+    this.addShutdownHandler(() => {
+      clearTimeout(timeoutId);
+    }, 100); // High priority
+
+    return timeoutId;
+  }
+
+  /**
+   * Wait for shutdown signal
+   */
+  async waitForShutdownSignal() {
+    return new Promise(resolve => {
+      const handler = signal => {
+        resolve(signal);
+      };
+      process.once('SIGTERM', () => handler('SIGTERM'));
+      process.once('SIGINT', () => handler('SIGINT'));
+    });
+  }
+
+  /**
+   * Get shutdown status
+   */
+  getShutdownStatus() {
+    return {
+      isShuttingDown: this.isShuttingDown,
+      handlerCount: this.shutdownHandlers.length,
+      registered: this.registered,
+      config: this.config
+    };
+  }
+
+  /**
+   * Create database cleanup handler
+   */
+  createDatabaseCleanupHandler(dbManager) {
+    return async signal => {
+      if (dbManager && typeof dbManager.closeAllConnections === 'function') {
+        console.log('🗃️  Closing database connections...');
+        await dbManager.closeAllConnections();
+        console.log('✅ Database connections closed');
+      }
+    };
+  }
+
+  /**
+   * Create monitoring cleanup handler
+   */
+  createMonitoringCleanupHandler(monitor) {
+    return async signal => {
+      if (monitor && typeof monitor.stopMonitoring === 'function') {
+        console.log('📊 Stopping monitoring...');
+        await monitor.stopMonitoring();
+        console.log('✅ Monitoring stopped');
+      }
+    };
+  }
+
+  /**
+   * Create token cleanup handler
+   */
+  createTokenCleanupHandler(tokenManager) {
+    return async signal => {
+      // Token manager doesn't need special cleanup, but we could log the event
+      console.log('🔐 Token manager cleanup completed');
+    };
+  }
+
+  /**
+   * Setup standard handlers for common services
+   */
+  setupStandardHandlers(services = {}) {
+    const {
+      dbManager,
+      monitor,
+      tokenManager,
+      memoryManager
+    } = services;
+
+    // Database cleanup (high priority)
+    if (dbManager) {
+      this.addShutdownHandler(this.createDatabaseCleanupHandler(dbManager), 1000);
+    }
+
+    // Monitoring cleanup (medium priority)
+    if (monitor) {
+      this.addShutdownHandler(this.createMonitoringCleanupHandler(monitor), 500);
+    }
+
+    // Memory cleanup (medium priority)
+    if (memoryManager) {
+      this.addShutdownHandler(async signal => {
+        console.log('🧠 Stopping memory monitoring...');
+        memoryManager.stopMonitoring();
+        console.log('✅ Memory monitoring stopped');
+      }, 500);
+    }
+
+    // Token cleanup (low priority)
+    if (tokenManager) {
+      this.addShutdownHandler(this.createTokenCleanupHandler(tokenManager), 100);
+    }
+
+    // Final cleanup (lowest priority)
+    this.addShutdownHandler(async signal => {
+      console.log('🧹 Running final cleanup...');
+      // Force garbage collection if available
+      if (global.gc) {
+        global.gc();
+      }
+      console.log('✅ Final cleanup completed');
+    }, 1);
+  }
+}
+
+// Global shutdown manager instance
+let globalShutdownManager = null;
+
+/**
+ * Get the global shutdown manager instance
+ */
+export function getShutdownManager(options = {}) {
+  if (!globalShutdownManager) {
+    globalShutdownManager = new GracefulShutdownManager(options);
+  }
+  return globalShutdownManager;
+}
+
+/**
+ * Initialize graceful shutdown handling
+ */
+export async function initializeGracefulShutdown(services = {}, options = {}) {
+  const manager = getShutdownManager(options);
+  await manager.initialize();
+  manager.setupStandardHandlers(services);
+  manager.register();
+  return manager;
+}
+
+/**
+ * Quick shutdown for simple scripts
+ */
+export async function withGracefulShutdown(callback, services = {}, options = {}) {
+  const manager = initializeGracefulShutdown(services, options);
+  try {
+    await callback();
+  } catch (error) {
+    console.error('Error in main execution:', error);
+    await manager.initiateShutdown('error', error);
+  }
+}

package/dist/shared/utils/index.js

@@ -0,0 +1,9 @@
+/**
+ * Utilities Module
+ * Exports all general utility functions and managers
+ */
+
+export { InteractivePrompts } from './interactive-prompts.js';
+export { ErrorRecovery } from './error-recovery.js';
+export { GracefulShutdownManager } from './graceful-shutdown-manager.js';
+export { RateLimiter } from './rate-limiter.js';

package/dist/shared/utils/interactive-prompts.js

@@ -0,0 +1,134 @@
+/**
+ * Interactive Prompts Module
+ * Standardized user input functions for all scripts
+ * 
+ * Replaces duplicate prompt code across 10+ scripts
+ */
+
+import readline from 'readline';
+
+// Create readline interface (singleton)
+let rl = null;
+function getReadlineInterface() {
+  if (!rl) {
+    rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+  }
+  return rl;
+}
+export function askUser(question, defaultValue = null) {
+  return new Promise(resolve => {
+    const prompt = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
+    getReadlineInterface().question(prompt, answer => {
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+export function askYesNo(question, defaultValue = 'n') {
+  return new Promise(resolve => {
+    const prompt = `${question} [y/N]: `;
+    getReadlineInterface().question(prompt, answer => {
+      const response = answer.trim().toLowerCase() || defaultValue;
+      resolve(response === 'y' || response === 'yes');
+    });
+  });
+}
+export function askChoice(question, choices, defaultIndex = 0) {
+  return new Promise(resolve => {
+    console.log(`\n${question}`);
+    choices.forEach((choice, index) => {
+      const marker = index === defaultIndex ? '>' : ' ';
+      console.log(`${marker} ${index + 1}. ${choice}`);
+    });
+    getReadlineInterface().question(`\nSelect option [1-${choices.length}]: `, answer => {
+      const choice = parseInt(answer) - 1;
+      if (isNaN(choice) || choice < 0 || choice >= choices.length) {
+        resolve(defaultIndex);
+      } else {
+        resolve(choice);
+      }
+    });
+  });
+}
+export function askMultiChoice(question, choices, defaultIndices = []) {
+  return new Promise(resolve => {
+    console.log(`\n${question}`);
+    console.log('(Enter comma-separated numbers, e.g., "1,3,5")');
+    choices.forEach((choice, index) => {
+      const marker = defaultIndices.includes(index) ? '>' : ' ';
+      console.log(`${marker} ${index + 1}. ${choice}`);
+    });
+    const defaultStr = defaultIndices.map(i => i + 1).join(',');
+    getReadlineInterface().question(`\nSelect options [${defaultStr}]: `, answer => {
+      if (!answer.trim()) {
+        resolve(defaultIndices);
+        return;
+      }
+      const selected = answer.split(',').map(s => parseInt(s.trim()) - 1).filter(i => !isNaN(i) && i >= 0 && i < choices.length);
+      resolve(selected.length > 0 ? selected : defaultIndices);
+    });
+  });
+}
+export function closePrompts() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+// Utility function for progress indicators
+export function showProgress(message, steps = ['⏳', '⚡', '✅']) {
+  return new Promise(resolve => {
+    let stepIndex = 0;
+    const interval = setInterval(() => {
+      process.stdout.write(`\r${steps[stepIndex]} ${message}`);
+      stepIndex = (stepIndex + 1) % steps.length;
+    }, 500);
+
+    // Auto-resolve after 2 seconds or when manually resolved
+    setTimeout(() => {
+      clearInterval(interval);
+      process.stdout.write(`\r✅ ${message}\n`);
+      resolve();
+    }, 2000);
+  });
+}
+
+/**
+ * Ask for sensitive input (like API tokens) with hidden input
+ */
+export function askPassword(question) {
+  return new Promise(resolve => {
+    const prompt = `${question}: `;
+    process.stdout.write(prompt);
+
+    // Hide input for sensitive data
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    let password = '';
+    const onData = char => {
+      const charCode = char[0];
+      if (charCode === 13) {
+        // Enter key
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeListener('data', onData);
+        process.stdout.write('\n');
+        resolve(password);
+      } else if (charCode === 127 || charCode === 8) {
+        // Backspace
+        if (password.length > 0) {
+          password = password.slice(0, -1);
+          process.stdout.write('\b \b');
+        }
+      } else if (charCode >= 32 && charCode <= 126) {
+        // Printable characters
+        password += char.toString();
+        process.stdout.write('*');
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}