arcvision 0.2.14 → 0.2.15

package/src/core/cli-error-handler.js

@@ -0,0 +1,458 @@
+/**
+ * CLI Error Handler - Comprehensive error management for ArcVision CLI
+ * Provides authoritative error reporting and recovery mechanisms
+ */
+
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+
+class CLIErrorHandler {
+  constructor() {
+    this.errorCategories = {
+      FILE_SYSTEM: 'FILE_SYSTEM',
+      NETWORK: 'NETWORK',
+      VALIDATION: 'VALIDATION',
+      PARSING: 'PARSING',
+      CONFIGURATION: 'CONFIGURATION',
+      PERMISSION: 'PERMISSION',
+      TIMEOUT: 'TIMEOUT',
+      UNKNOWN: 'UNKNOWN'
+    };
+    
+    this.recoveryStrategies = {
+      RETRY: 'RETRY',
+      FALLBACK: 'FALLBACK',
+      SKIP: 'SKIP',
+      ABORT: 'ABORT',
+      MANUAL_INTERVENTION: 'MANUAL_INTERVENTION'
+    };
+  }
+  
+  /**
+   * Categorize and handle errors based on type
+   */
+  handleError(error, context = {}) {
+    const categorizedError = this.categorizeError(error);
+    
+    // Log the error with context
+    this.logError(categorizedError, context);
+    
+    // Apply recovery strategy
+    const recoveryResult = this.applyRecoveryStrategy(categorizedError, context);
+    
+    // Format user-friendly message
+    const userMessage = this.formatUserMessage(categorizedError, recoveryResult);
+    
+    return {
+      ...categorizedError,
+      recovery: recoveryResult,
+      userMessage
+    };
+  }
+  
+  /**
+   * Categorize error based on its properties and message
+   */
+  categorizeError(error) {
+    const errorInfo = {
+      original: error,
+      message: error.message || 'Unknown error',
+      code: error.code || null,
+      type: error.constructor.name,
+      stack: error.stack || null
+    };
+    
+    // File system errors
+    if (error.code && ['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'ENOTDIR'].includes(error.code)) {
+      errorInfo.category = this.errorCategories.FILE_SYSTEM;
+      errorInfo.subtype = this.getFileSubtype(error.code);
+    }
+    // Network errors
+    else if (error.code && ['ENOTFOUND', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT'].includes(error.code)) {
+      errorInfo.category = this.errorCategories.NETWORK;
+      errorInfo.subtype = this.getNetworkSubtype(error.code);
+    }
+    // Validation errors
+    else if (error.message && (
+      error.message.includes('validation') || 
+      error.message.includes('schema') ||
+      error.message.includes('invalid')
+    )) {
+      errorInfo.category = this.errorCategories.VALIDATION;
+    }
+    // Parsing errors
+    else if (error.message && (
+      error.message.includes('parse') || 
+      error.message.includes('syntax') ||
+      error.message.includes('JSON')
+    )) {
+      errorInfo.category = this.errorCategories.PARSING;
+    }
+    // Permission errors
+    else if (error.message && error.message.includes('permission')) {
+      errorInfo.category = this.errorCategories.PERMISSION;
+    }
+    // Timeout errors
+    else if (error.name === 'AbortError' || error.message.includes('timeout')) {
+      errorInfo.category = this.errorCategories.TIMEOUT;
+    }
+    // Configuration errors
+    else if (error.message && (
+      error.message.includes('config') || 
+      error.message.includes('token') ||
+      error.message.includes('missing')
+    )) {
+      errorInfo.category = this.errorCategories.CONFIGURATION;
+    }
+    // Unknown errors
+    else {
+      errorInfo.category = this.errorCategories.UNKNOWN;
+    }
+    
+    return errorInfo;
+  }
+  
+  getFileSubtype(errorCode) {
+    const subtypeMap = {
+      'ENOENT': 'FILE_NOT_FOUND',
+      'EACCES': 'ACCESS_DENIED',
+      'EPERM': 'PERMISSION_DENIED',
+      'EISDIR': 'IS_DIRECTORY',
+      'ENOTDIR': 'NOT_DIRECTORY'
+    };
+    return subtypeMap[errorCode] || 'FILE_SYSTEM_ERROR';
+  }
+  
+  getNetworkSubtype(errorCode) {
+    const subtypeMap = {
+      'ENOTFOUND': 'HOST_NOT_FOUND',
+      'ECONNREFUSED': 'CONNECTION_REFUSED',
+      'ECONNRESET': 'CONNECTION_RESET',
+      'ETIMEDOUT': 'TIMEOUT'
+    };
+    return subtypeMap[errorCode] || 'NETWORK_ERROR';
+  }
+  
+  /**
+   * Log error with detailed context
+   */
+  logError(errorInfo, context) {
+    const timestamp = new Date().toISOString();
+    const logEntry = {
+      timestamp,
+      error: {
+        category: errorInfo.category,
+        subtype: errorInfo.subtype,
+        message: errorInfo.message,
+        code: errorInfo.code,
+        type: errorInfo.type
+      },
+      context: {
+        operation: context.operation,
+        directory: context.directory,
+        file: context.file,
+        ...context.additional
+      },
+      stack: errorInfo.stack
+    };
+    
+    // Write to error log file
+    try {
+      const logDir = path.join(process.cwd(), '.arcvision', 'logs');
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+      
+      const logFile = path.join(logDir, 'errors.log');
+      const logLine = JSON.stringify(logEntry) + '\n';
+      fs.appendFileSync(logFile, logLine);
+    } catch (logError) {
+      // Silently fail if we can't write logs
+      console.warn('Could not write error log:', logError.message);
+    }
+  }
+  
+  /**
+   * Apply appropriate recovery strategy based on error type
+   */
+  applyRecoveryStrategy(errorInfo, context) {
+    const strategy = this.determineRecoveryStrategy(errorInfo, context);
+    
+    switch (strategy) {
+      case this.recoveryStrategies.RETRY:
+        return this.handleRetry(errorInfo, context);
+      
+      case this.recoveryStrategies.FALLBACK:
+        return this.handleFallback(errorInfo, context);
+      
+      case this.recoveryStrategies.SKIP:
+        return this.handleSkip(errorInfo, context);
+      
+      case this.recoveryStrategies.MANUAL_INTERVENTION:
+        return this.handleManualIntervention(errorInfo, context);
+      
+      case this.recoveryStrategies.ABORT:
+      default:
+        return { strategy: 'ABORT', canContinue: false };
+    }
+  }
+  
+  /**
+   * Determine the best recovery strategy for an error
+   */
+  determineRecoveryStrategy(errorInfo, context) {
+    // Network errors - retry with exponential backoff
+    if (errorInfo.category === this.errorCategories.NETWORK) {
+      if (context.retryCount && context.retryCount < 3) {
+        return this.recoveryStrategies.RETRY;
+      }
+      return this.recoveryStrategies.FALLBACK;
+    }
+    
+    // File not found - abort if critical, skip if optional
+    if (errorInfo.subtype === 'FILE_NOT_FOUND') {
+      if (context.isCritical) {
+        return this.recoveryStrategies.ABORT;
+      }
+      return this.recoveryStrategies.SKIP;
+    }
+    
+    // Permission errors - manual intervention required
+    if (errorInfo.category === this.errorCategories.PERMISSION) {
+      return this.recoveryStrategies.MANUAL_INTERVENTION;
+    }
+    
+    // Parsing errors - skip problematic files
+    if (errorInfo.category === this.errorCategories.PARSING) {
+      return this.recoveryStrategies.SKIP;
+    }
+    
+    // Validation errors - depends on severity
+    if (errorInfo.category === this.errorCategories.VALIDATION) {
+      if (context.allowInvalid) {
+        return this.recoveryStrategies.FALLBACK;
+      }
+      return this.recoveryStrategies.ABORT;
+    }
+    
+    // Timeout errors - retry once
+    if (errorInfo.category === this.errorCategories.TIMEOUT) {
+      if (context.retryCount && context.retryCount < 1) {
+        return this.recoveryStrategies.RETRY;
+      }
+      return this.recoveryStrategies.ABORT;
+    }
+    
+    // Default - abort for unknown errors
+    return this.recoveryStrategies.ABORT;
+  }
+  
+  /**
+   * Handle retry strategy
+   */
+  handleRetry(errorInfo, context) {
+    const retryCount = (context.retryCount || 0) + 1;
+    const delay = Math.min(1000 * Math.pow(2, retryCount), 10000); // Max 10s
+    
+    return {
+      strategy: 'RETRY',
+      canContinue: true,
+      retryCount,
+      delay,
+      message: `Retrying in ${delay}ms... (attempt ${retryCount})`
+    };
+  }
+  
+  /**
+   * Handle fallback strategy
+   */
+  handleFallback(errorInfo, context) {
+    return {
+      strategy: 'FALLBACK',
+      canContinue: true,
+      message: 'Using fallback mechanism to continue operation'
+    };
+  }
+  
+  /**
+   * Handle skip strategy
+   */
+  handleSkip(errorInfo, context) {
+    return {
+      strategy: 'SKIP',
+      canContinue: true,
+      message: `Skipping ${context.file || 'resource'} due to error`
+    };
+  }
+  
+  /**
+   * Handle manual intervention strategy
+   */
+  handleManualIntervention(errorInfo, context) {
+    return {
+      strategy: 'MANUAL_INTERVENTION',
+      canContinue: false,
+      message: 'Manual intervention required - operation cannot continue automatically'
+    };
+  }
+  
+  /**
+   * Format user-friendly error message
+   */
+  formatUserMessage(errorInfo, recoveryResult) {
+    let message = '';
+    
+    // Error category header
+    switch (errorInfo.category) {
+      case this.errorCategories.FILE_SYSTEM:
+        message += chalk.red('📁 File System Error: ');
+        break;
+      case this.errorCategories.NETWORK:
+        message += chalk.red('🌐 Network Error: ');
+        break;
+      case this.errorCategories.VALIDATION:
+        message += chalk.red('❌ Validation Error: ');
+        break;
+      case this.errorCategories.PARSING:
+        message += chalk.red('📄 Parsing Error: ');
+        break;
+      case this.errorCategories.PERMISSION:
+        message += chalk.red('🔐 Permission Error: ');
+        break;
+      case this.errorCategories.TIMEOUT:
+        message += chalk.red('⏰ Timeout Error: ');
+        break;
+      case this.errorCategories.CONFIGURATION:
+        message += chalk.red('⚙️  Configuration Error: ');
+        break;
+      default:
+        message += chalk.red('💥 Unknown Error: ');
+    }
+    
+    // Specific error message
+    message += errorInfo.message + '\n';
+    
+    // Recovery information
+    if (recoveryResult.canContinue) {
+      message += chalk.yellow(`🔄 Recovery: ${recoveryResult.message}\n`);
+    } else {
+      message += chalk.red(`🛑 Cannot continue: ${recoveryResult.message}\n`);
+    }
+    
+    // Helpful suggestions
+    message += this.getSuggestions(errorInfo);
+    
+    return message;
+  }
+  
+  /**
+   * Get helpful suggestions based on error type
+   */
+  getSuggestions(errorInfo) {
+    const suggestions = [];
+    
+    switch (errorInfo.category) {
+      case this.errorCategories.FILE_SYSTEM:
+        if (errorInfo.subtype === 'FILE_NOT_FOUND') {
+          suggestions.push('• Check if the file path is correct');
+          suggestions.push('• Verify the file exists in the specified location');
+        } else if (errorInfo.subtype === 'ACCESS_DENIED') {
+          suggestions.push('• Check file permissions');
+          suggestions.push('• Ensure you have read/write access to the file/directory');
+        }
+        break;
+        
+      case this.errorCategories.NETWORK:
+        suggestions.push('• Check your internet connection');
+        suggestions.push('• Verify the API endpoint is accessible');
+        suggestions.push('• Try again in a few minutes');
+        break;
+        
+      case this.errorCategories.VALIDATION:
+        suggestions.push('• Check the structure of your configuration files');
+        suggestions.push('• Ensure JSON files are properly formatted');
+        suggestions.push('• Refer to documentation for correct schema');
+        break;
+        
+      case this.errorCategories.PARSING:
+        suggestions.push('• Check for syntax errors in the file');
+        suggestions.push('• Verify the file encoding is UTF-8');
+        suggestions.push('• Ensure the file contains valid content for its type');
+        break;
+        
+      case this.errorCategories.PERMISSION:
+        suggestions.push('• Run the command with appropriate permissions');
+        suggestions.push('• Check if the file/directory is locked by another process');
+        suggestions.push('• Verify your user account has necessary access rights');
+        break;
+        
+      case this.errorCategories.TIMEOUT:
+        suggestions.push('• Check network connectivity');
+        suggestions.push('• Try with a smaller dataset');
+        suggestions.push('• Increase timeout settings if available');
+        break;
+    }
+    
+    return suggestions.length > 0 
+      ? chalk.dim('\n💡 Suggestions:\n' + suggestions.map(s => `  ${s}`).join('\n') + '\n')
+      : '';
+  }
+  
+  /**
+   * Display error to user with appropriate formatting
+   */
+  displayError(errorInfo) {
+    console.error('\n' + '='.repeat(60));
+    console.error(chalk.bold.red('ARCVISION CLI ERROR REPORT'));
+    console.error('='.repeat(60));
+    console.error('');
+    console.error(errorInfo.userMessage);
+    
+    // Show stack trace for debugging in verbose mode
+    if (process.env.DEBUG || process.argv.includes('--debug')) {
+      console.error(chalk.dim('\n🔧 Debug Information:'));
+      console.error(chalk.dim(`Category: ${errorInfo.category}`));
+      console.error(chalk.dim(`Type: ${errorInfo.type}`));
+      console.error(chalk.dim(`Code: ${errorInfo.code || 'N/A'}`));
+      if (errorInfo.stack) {
+        console.error(chalk.dim(`Stack:\n${errorInfo.stack}`));
+      }
+    }
+    
+    console.error('='.repeat(60) + '\n');
+  }
+  
+  /**
+   * Handle fatal errors that should terminate the process
+   */
+  handleFatalError(error, context = {}) {
+    const errorInfo = this.handleError(error, context);
+    this.displayError(errorInfo);
+    
+    // Log additional fatal error information
+    console.error(chalk.red.bold('💀 FATAL ERROR - Terminating process'));
+    
+    process.exit(1);
+  }
+  
+  /**
+   * Handle recoverable errors that allow continuation
+   */
+  handleRecoverableError(error, context = {}) {
+    const errorInfo = this.handleError(error, context);
+    
+    if (errorInfo.recovery.canContinue) {
+      console.warn('\n' + chalk.yellow('⚠️  Recoverable Error:'));
+      console.warn(errorInfo.userMessage);
+      return true; // Can continue
+    } else {
+      this.displayError(errorInfo);
+      return false; // Cannot continue
+    }
+  }
+}
+
+// Export singleton instance
+const cliErrorHandler = new CLIErrorHandler();
+module.exports = { CLIErrorHandler, cliErrorHandler };