vibecodingmachine-core 2026.2.20-438 → 2026.2.26-1739

package/src/agents/InstallationErrorHandler.js

@@ -0,0 +1,372 @@
+/**
+ * Installation Error Handler
+ * 
+ * Provides comprehensive error messages and resolution suggestions
+ * for all installation failure scenarios.
+ * Follows constitutional requirements: <555 lines, test-first approach.
+ */
+
+/**
+ * Installation Error Handler class
+ */
+class InstallationErrorHandler {
+  /**
+   * Create error handler instance
+   * @param {Object} options - Handler options
+   */
+  constructor(options = {}) {
+    this.logger = options.logger || null;
+    this.platform = options.platform || process.platform;
+    this.arch = options.arch || process.arch;
+  }
+
+  /**
+   * Handle installation error and provide comprehensive message
+   * @param {Error} error - Original error
+   * @param {Object} context - Installation context
+   * @returns {Object} - Enhanced error information
+   */
+  handleError(error, context = {}) {
+    const { agentId, installerType, command, phase } = context;
+    
+    const errorInfo = {
+      originalError: error,
+      agentId,
+      installerType,
+      command,
+      phase,
+      timestamp: new Date().toISOString(),
+      platform: this.platform,
+      arch: this.arch
+    };
+
+    // Categorize error and provide specific guidance
+    const categorizedError = this.categorizeError(error, context);
+    
+    return {
+      ...errorInfo,
+      ...categorizedError,
+      userMessage: categorizedError.message,
+      technicalDetails: error.message,
+      resolutionSteps: categorizedError.resolutionSteps,
+      severity: categorizedError.severity,
+      category: categorizedError.category
+    };
+  }
+
+  /**
+   * Categorize error and provide specific resolution steps
+   * @param {Error} error - Error to categorize
+   * @param {Object} context - Installation context
+   * @returns {Object} - Categorized error information
+   */
+  categorizeError(error, context) {
+    const errorMessage = error.message.toLowerCase();
+    const { installerType, agentId } = context;
+
+    // Network-related errors
+    if (this.isNetworkError(errorMessage)) {
+      return {
+        category: 'NETWORK',
+        severity: 'MEDIUM',
+        message: `Network connection failed while installing ${agentId}. Please check your internet connection and try again.`,
+        resolutionSteps: [
+          'Check internet connection',
+          'Verify firewall allows package manager access',
+          'Try using VPN if network is restricted',
+          'Wait a few minutes and retry (rate limiting)',
+          'Consider alternative installation method'
+        ]
+      };
+    }
+
+    // Permission errors
+    if (this.isPermissionError(errorMessage)) {
+      return {
+        category: 'PERMISSION',
+        severity: 'HIGH',
+        message: `Permission denied while installing ${agentId}. Administrator privileges may be required.`,
+        resolutionSteps: [
+          'Run command prompt as Administrator',
+          'Check User Account Control (UAC) settings',
+          'Verify write permissions to installation directory',
+          'Temporarily disable antivirus software',
+          'Consider installing in user directory instead'
+        ]
+      };
+    }
+
+    // Package manager not found
+    if (this.isPackageManagerError(errorMessage, installerType)) {
+      return this.getPackageManagerError(installerType, agentId);
+    }
+
+    // Disk space errors
+    if (this.isDiskSpaceError(errorMessage)) {
+      return {
+        category: 'DISK_SPACE',
+        severity: 'HIGH',
+        message: `Insufficient disk space to install ${agentId}. Please free up disk space and try again.`,
+        resolutionSteps: [
+          'Run Disk Cleanup utility',
+          'Delete temporary files',
+          'Uninstall unused applications',
+          'Move files to external storage',
+          'Consider installing on different drive'
+        ]
+      };
+    }
+
+    // Dependency errors
+    if (this.isDependencyError(errorMessage)) {
+      return {
+        category: 'DEPENDENCY',
+        severity: 'MEDIUM',
+        message: `Missing dependencies required for ${agentId} installation.`,
+        resolutionSteps: [
+          'Install Node.js from nodejs.org',
+          'Install Windows Package Manager (winget)',
+          'Install Git for Windows',
+          'Install Visual Studio Build Tools',
+          'Check system requirements documentation'
+        ]
+      };
+    }
+
+    // Timeout errors
+    if (this.isTimeoutError(errorMessage)) {
+      return {
+        category: 'TIMEOUT',
+        severity: 'MEDIUM',
+        message: `Installation of ${agentId} timed out. The installation may be stuck or very slow.`,
+        resolutionSteps: [
+          'Check internet connection speed',
+          'Temporarily disable antivirus software',
+          'Close other applications to free resources',
+          'Increase timeout value in configuration',
+          'Try installation during off-peak hours'
+        ]
+      };
+    }
+
+    // Version conflicts
+    if (this.isVersionConflictError(errorMessage)) {
+      return {
+        category: 'VERSION_CONFLICT',
+        severity: 'MEDIUM',
+        message: `Version conflict detected while installing ${agentId}. An existing version may interfere.`,
+        resolutionSteps: [
+          'Uninstall existing version first',
+          'Use --force flag to override',
+          'Clear package manager cache',
+          'Restart computer before retrying',
+          'Check for multiple installations'
+        ]
+      };
+    }
+
+    // Default/unknown errors
+    return {
+      category: 'UNKNOWN',
+      severity: 'MEDIUM',
+      message: `An unexpected error occurred while installing ${agentId}: ${error.message}`,
+      resolutionSteps: [
+        'Check system requirements',
+        'Verify all dependencies are installed',
+        'Try alternative installation method',
+        'Check installation logs for details',
+        'Contact support with error details'
+      ]
+    };
+  }
+
+  /**
+   * Check if error is network-related
+   * @param {string} errorMessage - Error message to check
+   * @returns {boolean} - Whether error is network-related
+   */
+  isNetworkError(errorMessage) {
+    const networkKeywords = [
+      'network', 'connection', 'timeout', 'unreachable', 'dns',
+      'proxy', 'firewall', 'internet', 'offline', 'host not found',
+      'connection refused', 'socket', 'etimedout', 'enotfound'
+    ];
+    
+    return networkKeywords.some(keyword => errorMessage.includes(keyword));
+  }
+
+  /**
+   * Check if error is permission-related
+   * @param {string} errorMessage - Error message to check
+   * @returns {boolean} - Whether error is permission-related
+   */
+  isPermissionError(errorMessage) {
+    const permissionKeywords = [
+      'permission denied', 'access denied', 'eacces', 'eperm',
+      'administrator', 'privilege', 'unauthorized', 'forbidden',
+      'write protected', 'read-only', 'uid', 'gid'
+    ];
+    
+    return permissionKeywords.some(keyword => errorMessage.includes(keyword));
+  }
+
+  /**
+   * Check if error is package manager related
+   * @param {string} errorMessage - Error message to check
+   * @param {string} installerType - Type of installer
+   * @returns {boolean} - Whether error is package manager related
+   */
+  isPackageManagerError(errorMessage, installerType) {
+    const pmErrors = {
+      'WINGET': ['winget not found', 'command not found: winget', 'not recognized as an internal or external command'],
+      'NPM': ['npm not found', 'command not found: npm', 'not recognized as an internal or external command'],
+      'POWERSHELL': ['powershell not found', 'execution policy', 'cannot be loaded'],
+      'CHOCOLATEY': ['choco not found', 'chocolatey not found', 'command not found: choco']
+    };
+
+    const errors = pmErrors[installerType] || [];
+    return errors.some(error => errorMessage.includes(error));
+  }
+
+  /**
+   * Get package manager specific error
+   * @param {string} installerType - Type of installer
+   * @param {string} agentId - Agent ID
+   * @returns {Object} - Package manager error information
+   */
+  getPackageManagerError(installerType, agentId) {
+    const pmErrors = {
+      'WINGET': {
+        message: `Windows Package Manager (winget) is not installed or not in PATH. Cannot install ${agentId}.`,
+        resolutionSteps: [
+          'Install Windows Package Manager from Microsoft Store',
+          'Update Windows to version 1709 or later',
+          'Install winget from GitHub releases',
+          'Add winget to system PATH',
+          'Restart command prompt after installation'
+        ]
+      },
+      'NPM': {
+        message: `Node Package Manager (npm) is not installed or not in PATH. Cannot install ${agentId}.`,
+        resolutionSteps: [
+          'Install Node.js from nodejs.org (includes npm)',
+          'Download Node.js LTS version',
+          'Add Node.js to system PATH',
+          'Restart command prompt after installation',
+          'Verify installation with "npm --version"'
+        ]
+      },
+      'POWERSHELL': {
+        message: `PowerShell execution policy prevents installation. Cannot install ${agentId}.`,
+        resolutionSteps: [
+          'Run PowerShell as Administrator',
+          'Set execution policy: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser',
+          'Use -ExecutionPolicy Bypass flag',
+          'Check PowerShell security settings',
+          'Consider using alternative installation method'
+        ]
+      },
+      'CHOCOLATEY': {
+        message: `Chocolatey Package Manager is not installed. Cannot install ${agentId}.`,
+        resolutionSteps: [
+          'Install Chocolatey from chocolatey.org',
+          'Run PowerShell as Administrator',
+          'Execute installation command from chocolatey.org',
+          'Add Chocolatey to system PATH',
+          'Restart command prompt after installation'
+        ]
+      }
+    };
+
+    const errorInfo = pmErrors[installerType] || pmErrors['WINGET'];
+    
+    return {
+      category: 'PACKAGE_MANAGER',
+      severity: 'HIGH',
+      ...errorInfo
+    };
+  }
+
+  /**
+   * Check if error is disk space related
+   * @param {string} errorMessage - Error message to check
+   * @returns {boolean} - Whether error is disk space related
+   */
+  isDiskSpaceError(errorMessage) {
+    const diskKeywords = [
+      'disk space', 'insufficient space', 'no space left', 'disk full',
+      'enospace', 'not enough space', 'storage', 'drive full'
+    ];
+    
+    return diskKeywords.some(keyword => errorMessage.includes(keyword));
+  }
+
+  /**
+   * Check if error is dependency related
+   * @param {string} errorMessage - Error message to check
+   * @returns {boolean} - Whether error is dependency related
+   */
+  isDependencyError(errorMessage) {
+    const dependencyKeywords = [
+      'dependency', 'missing', 'required', 'not found', 'module not found',
+      'cannot find module', 'dependency not satisfied', 'requires'
+    ];
+    
+    return dependencyKeywords.some(keyword => errorMessage.includes(keyword));
+  }
+
+  /**
+   * Check if error is timeout related
+   * @param {string} errorMessage - Error message to check
+   * @returns {boolean} - Whether error is timeout related
+   */
+  isTimeoutError(errorMessage) {
+    const timeoutKeywords = [
+      'timeout', 'timed out', 'time out', 'etimedout', 'timeout exceeded',
+      'operation timed out', 'connection timeout'
+    ];
+    
+    return timeoutKeywords.some(keyword => errorMessage.includes(keyword));
+  }
+
+  /**
+   * Check if error is version conflict related
+   * @param {string} errorMessage - Error message to check
+   * @returns {boolean} - Whether error is version conflict related
+   */
+  isVersionConflictError(errorMessage) {
+    const conflictKeywords = [
+      'version conflict', 'already installed', 'exists', 'conflict',
+      'version mismatch', 'incompatible version', 'already exists'
+    ];
+    
+    return conflictKeywords.some(keyword => errorMessage.includes(keyword));
+  }
+
+  /**
+   * Get success message with additional context
+   * @param {Object} context - Installation context
+   * @returns {Object} - Success information
+   */
+  getSuccessMessage(context) {
+    const { agentId, installerType, duration, version } = context;
+    
+    return {
+      category: 'SUCCESS',
+      severity: 'INFO',
+      message: `Successfully installed ${agentId} using ${installerType} in ${Math.round(duration / 1000)}s`,
+      agentId,
+      installerType,
+      duration,
+      version,
+      nextSteps: [
+        'Run verification tests to confirm functionality',
+        'Check agent documentation for configuration',
+        'Test basic agent commands',
+        'Consider enabling auto-updates'
+      ]
+    };
+  }
+}
+
+module.exports = InstallationErrorHandler;