@paulduvall/claude-dev-toolkit 0.0.1-alpha.2 → 0.0.1-alpha.21

package/lib/services/platform-instruction-service.js

@@ -0,0 +1,294 @@
+/**
+ * Platform Instruction Service
+ * Handles platform-specific installation instructions
+ */
+
+const { DOWNLOAD_LINKS, PACKAGE_MANAGERS } = require('../config/constants');
+
+class PlatformInstructionService {
+    constructor() {
+        this.downloadLinks = DOWNLOAD_LINKS;
+        this.packageManagers = PACKAGE_MANAGERS;
+    }
+
+    /**
+     * Generate platform-specific installation instructions
+     * @param {string} platform - Target platform
+     * @param {Object} dependency - Dependency information
+     * @returns {Object} Platform-specific instructions
+     */
+    generatePlatformInstructions(platform, dependency) {
+        const instructions = this._initializePlatformInstructions(platform);
+        
+        this._addPlatformPackageManagers(instructions, platform, dependency);
+        this._setDefaultPackageManager(instructions, platform);
+        this._addPlatformSpecificNotes(instructions, platform, dependency);
+        
+        return instructions;
+    }
+
+    /**
+     * Initialize platform-specific instruction structure
+     * @param {string} platform - Target platform
+     * @returns {Object} Initialized instructions
+     * @private
+     */
+    _initializePlatformInstructions(platform) {
+        return {
+            platform,
+            packageManagerOptions: [],
+            downloadLinks: this._getPlatformDownloadLinks(platform),
+            notes: [],
+            troubleshooting: []
+        };
+    }
+
+    /**
+     * Get download links for platform
+     * @param {string} platform - Target platform
+     * @returns {Object} Platform download links
+     * @private
+     */
+    _getPlatformDownloadLinks(platform) {
+        const links = {};
+        
+        Object.keys(this.downloadLinks).forEach(tool => {
+            if (this.downloadLinks[tool][platform]) {
+                links[tool] = this.downloadLinks[tool][platform];
+            } else if (this.downloadLinks[tool].all) {
+                links[tool] = this.downloadLinks[tool].all;
+            }
+        });
+        
+        return links;
+    }
+
+    /**
+     * Add platform-specific package managers
+     * @param {Object} instructions - Instructions object to modify
+     * @param {string} platform - Target platform
+     * @param {Object} dependency - Dependency information
+     * @private
+     */
+    _addPlatformPackageManagers(instructions, platform, dependency) {
+        const availableManagers = this._getAvailablePackageManagers(platform);
+        
+        availableManagers.forEach(manager => {
+            const managerInfo = this.packageManagers[manager];
+            if (this._isManagerSupportedOnPlatform(manager, platform)) {
+                instructions.packageManagerOptions.push({
+                    name: managerInfo.name,
+                    command: this._buildInstallCommand(managerInfo, dependency),
+                    checkCommand: managerInfo.checkCommand,
+                    installUrl: managerInfo.installUrl,
+                    global: dependency.global || false
+                });
+            }
+        });
+    }
+
+    /**
+     * Get available package managers for platform
+     * @param {string} platform - Target platform
+     * @returns {Array} Available package managers
+     * @private
+     */
+    _getAvailablePackageManagers(platform) {
+        const platformManagers = {
+            linux: ['npm', 'yarn', 'pnpm', 'apt', 'yum'],
+            darwin: ['npm', 'yarn', 'pnpm', 'brew'],
+            win32: ['npm', 'yarn', 'pnpm', 'chocolatey', 'winget']
+        };
+        
+        return platformManagers[platform] || ['npm', 'yarn', 'pnpm'];
+    }
+
+    /**
+     * Check if package manager is supported on platform
+     * @param {string} manager - Package manager name
+     * @param {string} platform - Target platform
+     * @returns {boolean} Is supported
+     * @private
+     */
+    _isManagerSupportedOnPlatform(manager, platform) {
+        const managerInfo = this.packageManagers[manager];
+        if (!managerInfo) return false;
+        
+        if (managerInfo.platforms) {
+            return managerInfo.platforms.includes(platform);
+        }
+        
+        return true; // Universal managers like npm
+    }
+
+    /**
+     * Build installation command for dependency
+     * @param {Object} managerInfo - Package manager information
+     * @param {Object} dependency - Dependency information
+     * @returns {string} Installation command
+     * @private
+     */
+    _buildInstallCommand(managerInfo, dependency) {
+        const baseCommand = dependency.global ? managerInfo.globalInstall : managerInfo.install;
+        const packageName = dependency.packageName || dependency.name;
+        const version = dependency.version ? `@${dependency.version}` : '';
+        
+        return `${baseCommand} ${packageName}${version}`;
+    }
+
+    /**
+     * Set default package manager based on platform
+     * @param {Object} instructions - Instructions object to modify
+     * @param {string} platform - Target platform
+     * @private
+     */
+    _setDefaultPackageManager(instructions, platform) {
+        if (instructions.packageManagerOptions.length === 0) return;
+        
+        const platformDefaults = {
+            linux: 'apt',
+            darwin: 'brew',
+            win32: 'npm'
+        };
+        
+        const defaultManager = platformDefaults[platform] || 'npm';
+        const defaultOption = instructions.packageManagerOptions.find(opt => 
+            opt.name.toLowerCase() === defaultManager
+        ) || instructions.packageManagerOptions[0];
+        
+        if (defaultOption) {
+            defaultOption.default = true;
+        }
+    }
+
+    /**
+     * Add platform-specific notes and warnings
+     * @param {Object} instructions - Instructions object to modify
+     * @param {string} platform - Target platform
+     * @param {Object} dependency - Dependency information
+     * @private
+     */
+    _addPlatformSpecificNotes(instructions, platform, dependency) {
+        switch (platform) {
+            case 'linux':
+                instructions.notes.push('You may need to use sudo for system-wide installations');
+                if (dependency.name === 'node') {
+                    instructions.notes.push('Consider using a Node version manager like nvm');
+                }
+                break;
+                
+            case 'darwin':
+                instructions.notes.push('Homebrew is the recommended package manager for macOS');
+                if (dependency.name === 'python') {
+                    instructions.notes.push('macOS comes with Python 2.7, but Python 3+ is recommended');
+                }
+                break;
+                
+            case 'win32':
+                instructions.notes.push('Run PowerShell or Command Prompt as Administrator if needed');
+                instructions.notes.push('Windows Subsystem for Linux (WSL) may provide better compatibility');
+                break;
+        }
+
+        // Add dependency-specific notes
+        this._addDependencySpecificNotes(instructions, dependency);
+    }
+
+    /**
+     * Add dependency-specific notes
+     * @param {Object} instructions - Instructions object to modify
+     * @param {Object} dependency - Dependency information
+     * @private
+     */
+    _addDependencySpecificNotes(instructions, dependency) {
+        switch (dependency.name) {
+            case 'git':
+                instructions.notes.push('Git is required for version control operations');
+                instructions.troubleshooting.push('If git command not found, add Git to your system PATH');
+                break;
+                
+            case 'node':
+                instructions.notes.push('Node.js includes npm package manager');
+                instructions.troubleshooting.push('Use "node --version" to verify installation');
+                break;
+                
+            case 'python':
+                instructions.notes.push('Python 3.8+ is recommended for modern development');
+                instructions.troubleshooting.push('Use "python3" instead of "python" on some systems');
+                break;
+                
+            case 'docker':
+                instructions.notes.push('Docker requires system virtualization to be enabled');
+                instructions.troubleshooting.push('Restart your system after Docker installation');
+                break;
+        }
+    }
+
+    /**
+     * Generate troubleshooting guide for platform
+     * @param {string} platform - Target platform
+     * @param {string} dependencyName - Dependency that failed
+     * @returns {Array} Troubleshooting steps
+     */
+    generateTroubleshootingGuide(platform, dependencyName) {
+        const guide = [];
+        
+        // Platform-specific troubleshooting
+        switch (platform) {
+            case 'linux':
+                guide.push('Check if dependency is available in your distribution\'s package repository');
+                guide.push('Update package lists: sudo apt update (Ubuntu/Debian) or sudo yum update (RHEL/CentOS)');
+                guide.push('Verify PATH environment variable includes installation directory');
+                break;
+                
+            case 'darwin':
+                guide.push('Install Xcode Command Line Tools: xcode-select --install');
+                guide.push('Update Homebrew: brew update && brew upgrade');
+                guide.push('Check for conflicting installations in /usr/local/bin');
+                break;
+                
+            case 'win32':
+                guide.push('Run installation as Administrator');
+                guide.push('Disable Windows Defender temporarily during installation');
+                guide.push('Check Windows PATH environment variable');
+                guide.push('Consider using Windows Subsystem for Linux (WSL)');
+                break;
+        }
+        
+        // Dependency-specific troubleshooting
+        guide.push(...this._getDependencyTroubleshooting(dependencyName));
+        
+        return guide;
+    }
+
+    /**
+     * Get dependency-specific troubleshooting steps
+     * @param {string} dependencyName - Name of the dependency
+     * @returns {Array} Troubleshooting steps
+     * @private
+     */
+    _getDependencyTroubleshooting(dependencyName) {
+        const troubleshooting = {
+            git: [
+                'Download from official Git website if package manager fails',
+                'Configure Git after installation: git config --global user.name "Your Name"'
+            ],
+            node: [
+                'Use Node Version Manager (nvm) for easier version management',
+                'Clear npm cache: npm cache clean --force'
+            ],
+            python: [
+                'Use pyenv for Python version management',
+                'Install pip separately if not included: python -m ensurepip --upgrade'
+            ],
+            docker: [
+                'Enable Hyper-V on Windows or ensure virtualization is enabled in BIOS',
+                'Join docker group on Linux: sudo usermod -aG docker $USER'
+            ]
+        };
+        
+        return troubleshooting[dependencyName] || [];
+    }
+}
+
+module.exports = PlatformInstructionService;

package/lib/services/recovery-instruction-service.js

@@ -0,0 +1,348 @@
+/**
+ * Recovery Instruction Service
+ * Generates recovery and troubleshooting instructions for failed installations
+ */
+
+const { ERROR_MESSAGES } = require('../config/constants');
+
+class RecoveryInstructionService {
+    constructor() {
+        this.errorMessages = ERROR_MESSAGES;
+        this.commonRecoverySteps = this._initializeCommonRecoverySteps();
+    }
+
+    /**
+     * Generate recovery suggestions for failed dependency
+     * @param {Object} failedDependency - Dependency that failed validation
+     * @returns {Object} Recovery suggestions
+     */
+    generateRecoverySuggestions(failedDependency) {
+        const suggestions = {
+            immediate: [],
+            alternative: [],
+            troubleshooting: [],
+            additionalResources: []
+        };
+
+        if (!failedDependency || !failedDependency.error) {
+            return this._getGenericRecoverySuggestions(failedDependency);
+        }
+
+        // Generate error-specific suggestions
+        this._addErrorSpecificSuggestions(suggestions, failedDependency);
+        
+        // Add dependency-specific suggestions
+        this._addDependencySpecificSuggestions(suggestions, failedDependency);
+        
+        // Add platform-specific suggestions
+        this._addPlatformSpecificSuggestions(suggestions, failedDependency);
+        
+        // Add general troubleshooting steps
+        this._addGeneralTroubleshootingSteps(suggestions);
+
+        return suggestions;
+    }
+
+    /**
+     * Initialize common recovery steps
+     * @returns {Object} Common recovery steps by category
+     * @private
+     */
+    _initializeCommonRecoverySteps() {
+        return {
+            permissions: [
+                'Run command prompt or terminal as administrator/sudo',
+                'Check file and directory permissions',
+                'Ensure user has installation privileges'
+            ],
+            network: [
+                'Check internet connection',
+                'Try using a different network or VPN',
+                'Configure proxy settings if behind corporate firewall',
+                'Clear DNS cache: ipconfig /flushdns (Windows) or sudo dscacheutil -flushcache (macOS)'
+            ],
+            cache: [
+                'Clear package manager cache',
+                'Remove temporary installation files',
+                'Reset package manager configuration'
+            ],
+            environment: [
+                'Check system PATH environment variable',
+                'Verify required environment variables are set',
+                'Restart terminal/command prompt after installation',
+                'Reboot system if necessary'
+            ]
+        };
+    }
+
+    /**
+     * Add error-specific recovery suggestions
+     * @param {Object} suggestions - Suggestions object to modify
+     * @param {Object} failedDependency - Failed dependency information
+     * @private
+     */
+    _addErrorSpecificSuggestions(suggestions, failedDependency) {
+        const errorCode = failedDependency.error.code || 'UNKNOWN';
+        
+        switch (errorCode) {
+            case 'NOT_FOUND':
+                suggestions.immediate.push(`Install ${failedDependency.name} using your system package manager`);
+                suggestions.immediate.push(`Add ${failedDependency.name} to your system PATH`);
+                suggestions.alternative.push(`Download and install ${failedDependency.name} manually`);
+                suggestions.alternative.push(`Use portable version of ${failedDependency.name}`);
+                suggestions.troubleshooting.push(`Verify ${failedDependency.name} installation directory`);
+                suggestions.troubleshooting.push(`Check if ${failedDependency.name} was installed with different name`);
+                break;
+                
+            case 'VERSION_MISMATCH':
+                suggestions.immediate.push(`Update ${failedDependency.name} to version ${failedDependency.requiredVersion || 'latest'}`);
+                suggestions.immediate.push(`Use version manager to install specific version`);
+                suggestions.alternative.push(`Install required version manually`);
+                suggestions.alternative.push(`Use Docker container with required version`);
+                suggestions.troubleshooting.push(`Check if multiple versions are installed`);
+                suggestions.troubleshooting.push(`Verify which version is in PATH`);
+                break;
+                
+            case 'PERMISSION_DENIED':
+                suggestions.immediate.push(...this.commonRecoverySteps.permissions);
+                suggestions.alternative.push(`Install to user directory instead of system-wide`);
+                suggestions.alternative.push(`Use package manager that doesn't require admin rights`);
+                break;
+                
+            case 'NETWORK_ERROR':
+                suggestions.immediate.push(...this.commonRecoverySteps.network);
+                suggestions.alternative.push(`Download installation files manually`);
+                suggestions.alternative.push(`Use offline installer if available`);
+                break;
+                
+            case 'DISK_SPACE':
+                suggestions.immediate.push('Free up disk space by removing unnecessary files');
+                suggestions.immediate.push('Clean temporary files and caches');
+                suggestions.alternative.push('Install to different drive with more space');
+                suggestions.alternative.push('Use symbolic links to move installation');
+                break;
+                
+            case 'CORRUPTED_DOWNLOAD':
+                suggestions.immediate.push('Clear download cache and retry');
+                suggestions.immediate.push('Download from different mirror or source');
+                suggestions.alternative.push('Verify download integrity with checksums');
+                suggestions.alternative.push('Use different download method');
+                break;
+                
+            default:
+                suggestions.immediate.push(`Reinstall ${failedDependency.name} from scratch`);
+                suggestions.immediate.push('Check system logs for more details');
+                suggestions.troubleshooting.push('Run installation in verbose mode');
+                suggestions.troubleshooting.push('Check for conflicting software');
+        }
+    }
+
+    /**
+     * Add dependency-specific recovery suggestions
+     * @param {Object} suggestions - Suggestions object to modify
+     * @param {Object} failedDependency - Failed dependency information
+     * @private
+     */
+    _addDependencySpecificSuggestions(suggestions, failedDependency) {
+        const dependencyName = failedDependency.name.toLowerCase();
+        
+        switch (dependencyName) {
+            case 'node':
+            case 'nodejs':
+                suggestions.immediate.push('Install Node.js from official website: https://nodejs.org');
+                suggestions.alternative.push('Use Node Version Manager (nvm) for easier management');
+                suggestions.alternative.push('Install via package manager: brew install node (macOS)');
+                suggestions.troubleshooting.push('Check if Node.js is installed as "nodejs" instead of "node"');
+                suggestions.additionalResources.push('https://nodejs.org/en/download/package-manager/');
+                break;
+                
+            case 'npm':
+                suggestions.immediate.push('npm comes with Node.js - install Node.js first');
+                suggestions.alternative.push('Install npm separately: npm install -g npm@latest');
+                suggestions.troubleshooting.push('Check npm configuration: npm config list');
+                suggestions.troubleshooting.push('Reset npm to defaults: npm config delete prefix');
+                break;
+                
+            case 'git':
+                suggestions.immediate.push('Install Git from official website: https://git-scm.com');
+                suggestions.alternative.push('Install via package manager based on your OS');
+                suggestions.troubleshooting.push('Configure Git after installation with user name and email');
+                suggestions.additionalResources.push('https://git-scm.com/book/en/v2/Getting-Started-Installing-Git');
+                break;
+                
+            case 'python':
+            case 'python3':
+                suggestions.immediate.push('Install Python from official website: https://python.org');
+                suggestions.alternative.push('Use Python version manager like pyenv');
+                suggestions.alternative.push('Install Anaconda for scientific computing');
+                suggestions.troubleshooting.push('Check if python3 command is available instead of python');
+                suggestions.troubleshooting.push('Verify pip is installed: python -m ensurepip');
+                suggestions.additionalResources.push('https://docs.python.org/3/using/index.html');
+                break;
+                
+            case 'docker':
+                suggestions.immediate.push('Install Docker Desktop from official website');
+                suggestions.alternative.push('Use Docker CE for server installations');
+                suggestions.troubleshooting.push('Enable virtualization in BIOS settings');
+                suggestions.troubleshooting.push('Restart Docker service after installation');
+                suggestions.additionalResources.push('https://docs.docker.com/get-docker/');
+                break;
+        }
+    }
+
+    /**
+     * Add platform-specific recovery suggestions
+     * @param {Object} suggestions - Suggestions object to modify
+     * @param {Object} failedDependency - Failed dependency information
+     * @private
+     */
+    _addPlatformSpecificSuggestions(suggestions, failedDependency) {
+        const platform = process.platform;
+        
+        switch (platform) {
+            case 'win32':
+                suggestions.troubleshooting.push('Try Windows Subsystem for Linux (WSL) for better compatibility');
+                suggestions.troubleshooting.push('Use PowerShell instead of Command Prompt');
+                suggestions.troubleshooting.push('Temporarily disable Windows Defender during installation');
+                suggestions.alternative.push('Use Chocolatey package manager: https://chocolatey.org');
+                suggestions.alternative.push('Use winget package manager if available');
+                break;
+                
+            case 'darwin':
+                suggestions.alternative.push('Use Homebrew package manager: https://brew.sh');
+                suggestions.troubleshooting.push('Install Xcode Command Line Tools: xcode-select --install');
+                suggestions.troubleshooting.push('Check for conflicting installations in /usr/local');
+                break;
+                
+            case 'linux':
+                suggestions.alternative.push('Use distribution package manager (apt, yum, pacman, etc.)');
+                suggestions.troubleshooting.push('Update package lists before installation');
+                suggestions.troubleshooting.push('Check if package is available in distribution repositories');
+                suggestions.troubleshooting.push('Consider using Snap or Flatpak for universal packages');
+                break;
+        }
+    }
+
+    /**
+     * Add general troubleshooting steps
+     * @param {Object} suggestions - Suggestions object to modify
+     * @private
+     */
+    _addGeneralTroubleshootingSteps(suggestions) {
+        suggestions.troubleshooting.push(...this.commonRecoverySteps.environment);
+        suggestions.troubleshooting.push('Check system logs for error details');
+        suggestions.troubleshooting.push('Try installation in safe mode or clean environment');
+        suggestions.troubleshooting.push('Verify system meets minimum requirements');
+    }
+
+    /**
+     * Get generic recovery suggestions when error details are not available
+     * @param {Object} failedDependency - Failed dependency information
+     * @returns {Object} Generic recovery suggestions
+     * @private
+     */
+    _getGenericRecoverySuggestions(failedDependency) {
+        const name = failedDependency?.name || 'dependency';
+        
+        return {
+            immediate: [
+                `Try reinstalling ${name}`,
+                `Check if ${name} is in your system PATH`,
+                'Restart your terminal or command prompt'
+            ],
+            alternative: [
+                `Install ${name} using different package manager`,
+                `Download ${name} manually from official website`,
+                `Use portable version of ${name}`
+            ],
+            troubleshooting: [
+                'Check system requirements',
+                'Verify internet connection',
+                'Run installation as administrator if needed',
+                'Check for system updates'
+            ],
+            additionalResources: []
+        };
+    }
+
+    /**
+     * Generate step-by-step recovery guide
+     * @param {Object} failedDependency - Failed dependency information
+     * @returns {Array} Step-by-step recovery instructions
+     */
+    generateStepByStepGuide(failedDependency) {
+        const guide = [];
+        const suggestions = this.generateRecoverySuggestions(failedDependency);
+        
+        // Step 1: Immediate actions
+        if (suggestions.immediate.length > 0) {
+            guide.push({
+                step: 1,
+                title: 'Try these immediate solutions first:',
+                actions: suggestions.immediate.slice(0, 3) // Top 3 immediate suggestions
+            });
+        }
+        
+        // Step 2: Alternative approaches
+        if (suggestions.alternative.length > 0) {
+            guide.push({
+                step: 2,
+                title: 'If immediate solutions don\'t work, try these alternatives:',
+                actions: suggestions.alternative.slice(0, 3) // Top 3 alternatives
+            });
+        }
+        
+        // Step 3: Troubleshooting
+        if (suggestions.troubleshooting.length > 0) {
+            guide.push({
+                step: 3,
+                title: 'For advanced troubleshooting:',
+                actions: suggestions.troubleshooting.slice(0, 3) // Top 3 troubleshooting steps
+            });
+        }
+        
+        // Step 4: Additional resources
+        if (suggestions.additionalResources.length > 0) {
+            guide.push({
+                step: 4,
+                title: 'Additional resources:',
+                actions: suggestions.additionalResources
+            });
+        }
+        
+        return guide;
+    }
+
+    /**
+     * Generate recovery instructions for multiple failed dependencies
+     * @param {Array} failedDependencies - Array of failed dependencies
+     * @returns {Object} Consolidated recovery instructions
+     */
+    generateBulkRecoveryInstructions(failedDependencies) {
+        const consolidated = {
+            immediate: new Set(),
+            alternative: new Set(),
+            troubleshooting: new Set(),
+            additionalResources: new Set()
+        };
+        
+        failedDependencies.forEach(dependency => {
+            const suggestions = this.generateRecoverySuggestions(dependency);
+            
+            suggestions.immediate.forEach(item => consolidated.immediate.add(item));
+            suggestions.alternative.forEach(item => consolidated.alternative.add(item));
+            suggestions.troubleshooting.forEach(item => consolidated.troubleshooting.add(item));
+            suggestions.additionalResources.forEach(item => consolidated.additionalResources.add(item));
+        });
+        
+        return {
+            immediate: Array.from(consolidated.immediate),
+            alternative: Array.from(consolidated.alternative),
+            troubleshooting: Array.from(consolidated.troubleshooting),
+            additionalResources: Array.from(consolidated.additionalResources),
+            affectedDependencies: failedDependencies.map(dep => dep.name)
+        };
+    }
+}
+
+module.exports = RecoveryInstructionService;