@paulduvall/claude-dev-toolkit 0.0.1-alpha.7 → 0.0.1-alpha.9

package/README.md

@@ -49,6 +49,7 @@ claude-commands install --all           # Install all 58 commands
 ```bash
 claude-commands list                     # See all available commands
 claude-commands status                   # Check installation status
+claude-commands oidc --help             # Configure GitHub Actions OIDC with AWS
 ```
 
 ## 📋 Available Commands
@@ -97,6 +98,11 @@ claude-commands config --list          # List available templates
 claude-commands config --template <name> # Apply configuration template
 claude-commands config --help          # Show config command help
 
+# OIDC Configuration (NEW)
+claude-commands oidc --help            # Show OIDC configuration options
+claude-commands oidc --dry-run         # Preview OIDC setup actions
+claude-commands oidc --region us-west-2 --stack-name my-oidc # Configure AWS OIDC
+
 # Subagents Management
 claude-commands subagents --list        # List available subagents
 claude-commands subagents --install     # Install subagents to Claude Code
@@ -174,8 +180,8 @@ npm run lint             # Code linting
 - **Configuration Tests**: Template and setup validation
 
 ### Architecture
-- **Symlink Consolidation**: Single source of truth with root directory
-- **JavaScript-Based**: Migrated from Python for better Node.js integration
+- **Self-Contained Package**: No dependencies on repository cloning
+- **JavaScript-Based**: Native Node.js integration with comprehensive testing
 - **Modular Design**: Separate installer, config, and validation modules
 - **Cross-Platform**: Works on macOS, Linux, and Windows
 
@@ -212,13 +218,13 @@ npm run validate                       # Validate package
 
 ### Validation Commands
 ```bash
-# Repository validation (from main repo)
-./validate-commands.sh                 # JavaScript-based validation
-./verify-setup.sh                     # Complete setup verification
-
 # Package validation
 npm run validate                       # Package structure validation
 npm test                              # Comprehensive test suite
+
+# CLI validation
+claude-commands verify                 # Complete setup verification
+claude-commands list                   # Check installed commands
 ```
 
 ## 📚 Documentation
@@ -252,8 +258,8 @@ npm test
 ```
 
 ### Adding Commands
-1. Create command files in root `slash-commands/active/` or `slash-commands/experiments/`
-2. Commands automatically sync to NPM package via symlinks
+1. Create command files in repository `slash-commands/active/` or `slash-commands/experiments/`
+2. Commands are included in NPM package through build process
 3. Validate with `npm run test:commands`
 4. Follow existing patterns and security guidelines
 
@@ -264,7 +270,21 @@ npm test
 
 ## 🔄 Recent Updates
 
-### Version 0.0.1-alpha.2
+### Version 0.0.1-alpha.9
+- ✅ **NEW: OIDC Command**: GitHub Actions to AWS OIDC integration (`claude-commands oidc`)
+- ✅ **TDD Implementation**: Phase 1 foundation with comprehensive test coverage (14/14 tests)
+- ✅ **CLI Integration**: Full command-line interface with help, dry-run, and configuration options
+- ✅ **Error Framework**: Enhanced error handling with context-aware recovery suggestions
+- ✅ **Dependency Validation**: AWS CLI, Git, and GitHub CLI availability checking
+
+### Version 0.0.1-alpha.8
+- ✅ **Documentation Consistency**: Fixed command counts (58) and subagent counts (26)
+- ✅ **Test Infrastructure**: Enhanced test-results directory handling
+- ✅ **Repository Cleanup**: Removed outdated documentation and test artifacts
+- ✅ **Validation Logic**: Improved scenario-aware test validation
+- ✅ **Version Alignment**: Synchronized all version references
+
+### Version 0.0.1-alpha.7
 - ✅ **NPM Scoped Package**: Published as `@paulduvall/claude-dev-toolkit`
 - ✅ **Configuration Command**: Built-in `config` command for template management
 - ✅ **Workflow Reporting**: Comprehensive GitHub Actions reporting

package/bin/claude-commands

@@ -48,13 +48,25 @@ program
 
 program
     .command('install')
-    .description('Install command sets')
-    .option('--active', 'Install active commands only')
-    .option('--experiments', 'Install experimental commands')
-    .option('--all', 'Install all commands')
-    .action((options) => {
+    .description('Install command sets to ~/.claude/commands/')
+    .option('--active', 'Install production-ready commands (default)')
+    .option('--experiments', 'Install experimental commands only')
+    .option('--all', 'Install both active and experimental')
+    .option('--include <pattern>', 'Include specific commands matching pattern')
+    .option('--exclude <pattern>', 'Exclude commands matching pattern')
+    .option('--dry-run', 'Show what would be installed without making changes')
+    .option('--backup', 'Create backup before installation')
+    .action(async (options) => {
         const installer = require('../lib/installer');
-        installer.install(options);
+        try {
+            const result = await installer.install(options);
+            if (!result.success && !result.dryRun) {
+                process.exit(1);
+            }
+        } catch (error) {
+            console.error(`Installation failed: ${error.message}`);
+            process.exit(1);
+        }
     });
 
 program
@@ -115,4 +127,170 @@ program
         config.handleCommand(options);
     });
 
+program
+    .command('configure')
+    .description('Configure Claude Code settings (replaces configure-claude-code.sh)')
+    .option('--template <name>', 'Apply named template')
+    .option('--interactive', 'Launch interactive configuration wizard')
+    .option('--validate', 'Validate current configuration')
+    .option('--reset', 'Reset to default configuration')
+    .option('--backup', 'Create backup before changes (default: true)')
+    .option('--no-backup', 'Skip backup creation')
+    .action(async (options) => {
+        const ConfigureCommand = require('../lib/configure-command');
+        const configureCmd = new ConfigureCommand();
+        try {
+            const result = await configureCmd.execute(options);
+            if (!result.success) {
+                process.exit(1);
+            }
+        } catch (error) {
+            console.error(`Configuration failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('setup')
+    .description('Setup the Claude Dev Toolkit with custom commands and configuration')
+    .option('--type <template>', 'Configuration template to apply (basic, comprehensive, security-focused)')
+    .option('--commands <set>', 'Command set to install (active, experiments, all, none)')
+    .option('--skip-configure', 'Skip configuration step')
+    .option('--skip-hooks', 'Skip hooks installation')
+    .option('--force', 'Overwrite existing installation')
+    .option('--dry-run', 'Preview actions without executing')
+    .action(async (options) => {
+        const SetupCommand = require('../lib/setup-command');
+        const setupCmd = new SetupCommand();
+        try {
+            const result = await setupCmd.execute(options);
+            if (!result.success && !result.dryRun) {
+                process.exit(1);
+            }
+        } catch (error) {
+            console.error(`Setup failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('verify')
+    .description('Verify the Claude Dev Toolkit installation status and health')
+    .option('--verbose', 'Show detailed verification information')
+    .option('--fix', 'Attempt to fix detected issues automatically')
+    .action(async (options) => {
+        const VerifyCommand = require('../lib/verify-command');
+        const verifyCmd = new VerifyCommand();
+        try {
+            const result = await verifyCmd.execute(options);
+            // Set exit code based on health status
+            if (result.overall === 'critical') {
+                process.exit(2);
+            } else if (result.overall === 'warning') {
+                process.exit(1);
+            }
+            // Exit 0 for healthy
+        } catch (error) {
+            console.error(`Verification failed: ${error.message}`);
+            process.exit(2);
+        }
+    });
+
+program
+    .command('backup [name]')
+    .description('Create named backup of Claude Code configuration')
+    .action(async (name) => {
+        const BackupRestoreCommand = require('../lib/backup-restore-command');
+        const backupCmd = new BackupRestoreCommand();
+        try {
+            const result = await backupCmd.backup(name);
+            if (!result.success) {
+                process.exit(1);
+            }
+        } catch (error) {
+            console.error(`Backup failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('restore <name>')
+    .description('Restore from a named backup')
+    .action(async (name) => {
+        const BackupRestoreCommand = require('../lib/backup-restore-command');
+        const restoreCmd = new BackupRestoreCommand();
+        try {
+            const result = await restoreCmd.restore(name);
+            if (!result.success) {
+                process.exit(1);
+            }
+        } catch (error) {
+            console.error(`Restore failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('oidc')
+    .description('Configure GitHub Actions OIDC integration with AWS')
+    .option('--region <region>', 'AWS region for OIDC setup', 'us-east-1')
+    .option('--stack-name <name>', 'CloudFormation stack name', 'github-oidc-stack')
+    .option('--role-name <name>', 'IAM role name for GitHub Actions', 'GitHubActionsRole')
+    .option('--repository-path <path>', 'Path to repository for OIDC setup', process.cwd())
+    .option('--dry-run', 'Preview actions without making changes')
+    .option('--verbose', 'Show detailed output')
+    .action(async (options) => {
+        const OidcCommand = require('../lib/oidc-command');
+        const oidcCmd = new OidcCommand();
+        try {
+            const result = await oidcCmd.execute(options);
+            if (!result.success && !result.dryRun) {
+                process.exit(1);
+            }
+        } catch (error) {
+            console.error(`OIDC setup failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
+program
+    .command('update')
+    .description('Check for package updates')
+    .action(async () => {
+        const { version } = require('../package.json');
+        console.log('🔍 Checking for updates...\n');
+        console.log(`Current version: ${version}`);
+        
+        try {
+            const { execSync } = require('child_process');
+            const output = execSync('npm view @paulduvall/claude-dev-toolkit version', {
+                encoding: 'utf8',
+                stdio: 'pipe'
+            }).trim();
+            
+            console.log(`Latest version: ${output}`);
+            
+            if (output !== version) {
+                console.log('\n🆕 Update available!');
+                console.log('\nTo update, run:');
+                console.log('   npm update -g @paulduvall/claude-dev-toolkit');
+                
+                // Check for breaking changes in major version
+                const currentMajor = parseInt(version.split('.')[0]);
+                const latestMajor = parseInt(output.split('.')[0]);
+                
+                if (latestMajor > currentMajor) {
+                    console.log('\n⚠️  Major version update - may contain breaking changes');
+                    console.log('   Review release notes before updating');
+                }
+            } else {
+                console.log('\n✅ You are using the latest version');
+            }
+        } catch (error) {
+            console.error('❌ Could not check for updates');
+            console.log('   Please check your internet connection');
+            process.exit(1);
+        }
+    });
+
 program.parse(process.argv);

package/lib/backup-restore-command.js

@@ -0,0 +1,140 @@
+/**
+ * Backup and Restore Commands Implementation - Refactored
+ * Orchestrator for backup and restore operations using focused services
+ */
+
+const BackupService = require('./services/backup-service');
+const RestoreService = require('./services/restore-service');
+const BackupListService = require('./services/backup-list-service');
+const BaseCommand = require('./base/base-command');
+const FileSystemUtils = require('./utils/file-system-utils');
+const { execSync } = require('child_process');
+
+class BackupRestoreCommand extends BaseCommand {
+    constructor(config = null) {
+        super(config);
+        this.backupService = new BackupService(this.config);
+        this.restoreService = new RestoreService(this.config);
+        this.listService = new BackupListService(this.config);
+    }
+
+    /**
+     * Create a backup of the entire .claude directory
+     */
+    async backup(name = null) {
+        this.logger.step('Creating backup of Claude Code configuration', { backupName: name });
+
+        try {
+            const result = await this.backupService.create(name);
+            
+            // Try to compress the backup
+            const compressed = await this.compressBackup(result.path);
+            
+            this.logger.complete(`Backup '${result.name}' created successfully`, {
+                files: result.totalFiles,
+                size: FileSystemUtils.formatSize(result.totalSize),
+                compressed: !!compressed
+            });
+            
+            if (compressed) {
+                this.logger.info(`Backup compressed and stored at: ${compressed.path}`, { 
+                    compressionRatio: compressed.size / result.totalSize 
+                });
+            } else {
+                this.logger.info(`Backup stored at: ${result.path}`);
+            }
+            
+            return {
+                success: true,
+                name: result.name,
+                path: compressed ? compressed.path : result.path,
+                metadata: result.metadata
+            };
+
+        } catch (error) {
+            return this.handleError(error);
+        }
+    }
+
+    /**
+     * Try to compress a backup using tar
+     */
+    async compressBackup(backupPath) {
+        try {
+            const backupName = require('path').basename(backupPath);
+            const tarPath = `${backupPath}.tar.gz`;
+            
+            execSync(`tar -czf "${tarPath}" -C "${this.config.backupsDir}" "${backupName}"`, {
+                encoding: 'utf8',
+                stdio: 'pipe'
+            });
+            
+            // Remove uncompressed backup
+            FileSystemUtils.remove(backupPath);
+            
+            const compressedSize = FileSystemUtils.getStats(tarPath).size;
+            return { 
+                path: tarPath, 
+                size: compressedSize 
+            };
+        } catch (error) {
+            // Compression failed, keep uncompressed backup
+            return null;
+        }
+    }
+
+    /**
+     * Restore from a backup
+     */
+    async restore(backupName) {
+        this.logger.step(`Restoring from backup: ${backupName}`, { backupName });
+
+        try {
+            // Create undo backup first
+            this.logger.info('Creating undo backup for safety');
+            const undoBackup = await this.backup('undo-before-restore');
+            
+            if (!undoBackup.success) {
+                this.logger.warn('Could not create undo backup, continuing anyway', { 
+                    risk: 'restore cannot be undone' 
+                });
+            }
+
+            // Perform restore using service
+            const result = await this.restoreService.restore(backupName);
+
+            this.logger.complete(`Restore completed successfully`, {
+                restoredCount: result.restoredCount,
+                hasUndo: undoBackup.success
+            });
+            
+            if (undoBackup.success) {
+                this.logger.info(`To undo this restore, run: claude-commands restore ${undoBackup.name}`, {
+                    undoCommand: `claude-commands restore ${undoBackup.name}`
+                });
+            }
+
+            return {
+                success: true,
+                restoredCount: result.restoredCount,
+                undoBackup: undoBackup.success ? undoBackup.name : null
+            };
+
+        } catch (error) {
+            return this.handleError(error);
+        }
+    }
+
+    /**
+     * List available backups
+     */
+    async listBackups() {
+        try {
+            return await this.listService.display();
+        } catch (error) {
+            return this.handleError(error);
+        }
+    }
+}
+
+module.exports = BackupRestoreCommand;

package/lib/base/base-command.js

@@ -0,0 +1,252 @@
+/**
+ * Base Command Pattern
+ * Abstract base class for all CLI commands with standardized error handling
+ */
+
+const ClaudePathConfig = require('../utils/claude-path-config');
+const FileSystemUtils = require('../utils/file-system-utils');
+const LoggerService = require('../services/logger-service');
+
+class BaseCommand {
+    constructor(config = null, logger = null) {
+        this.config = config || new ClaudePathConfig();
+        this.logger = logger || new LoggerService();
+        this.startTime = null;
+        this.metrics = {
+            filesProcessed: 0,
+            operationsPerformed: 0,
+            errorsEncountered: 0
+        };
+        
+        // Set logger context for this command
+        this.logger.setContext({ 
+            command: this.constructor.name,
+            timestamp: new Date().toISOString()
+        });
+    }
+
+    /**
+     * Main execution method with standardized error handling
+     */
+    async execute(options = {}) {
+        this.startTime = Date.now();
+        
+        try {
+            // Pre-execution validation
+            const preValidation = await this.preValidate(options);
+            if (!preValidation.success) {
+                return this.createFailureResult(preValidation.error, preValidation);
+            }
+
+            // Execute the main command logic
+            const result = await this.run(options);
+            
+            // Post-execution cleanup
+            await this.postExecute(result, options);
+            
+            return this.createSuccessResult(result);
+
+        } catch (error) {
+            this.metrics.errorsEncountered++;
+            return this.handleError(error, options);
+        }
+    }
+
+    /**
+     * Abstract method - must be implemented by subclasses
+     */
+    async run(options) {
+        throw new Error('Subclasses must implement the run() method');
+    }
+
+    /**
+     * Pre-execution validation hook
+     */
+    async preValidate(options) {
+        // Default validation - can be overridden
+        return { success: true };
+    }
+
+    /**
+     * Post-execution cleanup hook
+     */
+    async postExecute(result, options) {
+        // Default post-execution - can be overridden
+        const duration = this.getDuration();
+        
+        if (process.env.NODE_ENV === 'development' || options.verbose) {
+            console.log(`\n📊 Command completed in ${duration}s`);
+            if (this.metrics.filesProcessed > 0) {
+                console.log(`   Files processed: ${this.metrics.filesProcessed}`);
+            }
+            if (this.metrics.operationsPerformed > 0) {
+                console.log(`   Operations: ${this.metrics.operationsPerformed}`);
+            }
+        }
+    }
+
+    /**
+     * Standardized error handling
+     */
+    handleError(error, options = {}) {
+        const errorDetails = this.analyzeError(error);
+        
+        // Log error appropriately
+        if (options.verbose || process.env.NODE_ENV === 'development') {
+            console.error(`💥 ${this.constructor.name} Error Details:`, error);
+        } else {
+            console.error(`❌ ${errorDetails.message}`);
+        }
+
+        // Provide helpful guidance
+        if (errorDetails.suggestions.length > 0) {
+            console.log('\n💡 Suggestions:');
+            errorDetails.suggestions.forEach(suggestion => {
+                console.log(`   • ${suggestion}`);
+            });
+        }
+
+        return this.createFailureResult(errorDetails.message, {
+            type: errorDetails.type,
+            suggestions: errorDetails.suggestions,
+            originalError: options.verbose ? error : undefined
+        });
+    }
+
+    /**
+     * Analyze error type and generate helpful suggestions
+     */
+    analyzeError(error) {
+        const message = error.message || 'Unknown error occurred';
+        const suggestions = [];
+        let type = 'general';
+
+        // File system errors
+        if (message.includes('ENOENT') || message.includes('no such file')) {
+            type = 'file_not_found';
+            suggestions.push('Check that the file or directory exists');
+            suggestions.push('Verify you have the correct path');
+        } else if (message.includes('EACCES') || message.includes('permission denied')) {
+            type = 'permission_error';
+            suggestions.push('Check file/directory permissions');
+            suggestions.push('Try running with appropriate permissions');
+        } else if (message.includes('ENOTDIR') || message.includes('not a directory')) {
+            type = 'path_error';
+            suggestions.push('Verify the path is correct');
+            suggestions.push('Check that parent directories exist');
+        }
+        // Network errors
+        else if (message.includes('ECONNREFUSED') || message.includes('network')) {
+            type = 'network_error';
+            suggestions.push('Check your internet connection');
+            suggestions.push('Verify proxy settings if applicable');
+        }
+        // Git errors
+        else if (message.includes('git') || message.includes('Not a git repository')) {
+            type = 'git_error';
+            suggestions.push('Ensure you are in a git repository');
+            suggestions.push('Run "git init" if needed');
+        }
+        // Claude Code errors
+        else if (message.includes('claude') || message.includes('settings')) {
+            type = 'claude_error';
+            suggestions.push('Run "claude-commands verify" to check installation');
+            suggestions.push('Try "claude-commands setup" to reconfigure');
+        }
+
+        return {
+            message: this.sanitizeErrorMessage(message),
+            type,
+            suggestions
+        };
+    }
+
+    /**
+     * Sanitize error messages for user consumption
+     */
+    sanitizeErrorMessage(message) {
+        // Remove internal paths and stack traces
+        return message
+            .replace(/\/Users\/[^\/]+\/[^\s]+/g, '~/<path>')
+            .replace(/\s+at\s+.*/g, '')
+            .replace(/Error:\s*/g, '')
+            .trim();
+    }
+
+    /**
+     * Create standardized success result
+     */
+    createSuccessResult(data = {}) {
+        return {
+            success: true,
+            duration: this.getDuration(),
+            metrics: { ...this.metrics },
+            timestamp: new Date().toISOString(),
+            ...data
+        };
+    }
+
+    /**
+     * Create standardized failure result
+     */
+    createFailureResult(message, data = {}) {
+        return {
+            success: false,
+            error: message,
+            duration: this.getDuration(),
+            metrics: { ...this.metrics },
+            timestamp: new Date().toISOString(),
+            ...data
+        };
+    }
+
+    /**
+     * Get execution duration in seconds
+     */
+    getDuration() {
+        if (!this.startTime) return 0;
+        return ((Date.now() - this.startTime) / 1000).toFixed(2);
+    }
+
+    /**
+     * Helper method to ensure directories exist
+     */
+    ensureDirectoryExists(dirPath) {
+        FileSystemUtils.ensureDirectory(dirPath);
+        this.metrics.operationsPerformed++;
+    }
+
+    /**
+     * Helper method to safely read files
+     */
+    safeReadFile(filePath) {
+        const content = FileSystemUtils.readFile(filePath);
+        if (content !== null) {
+            this.metrics.filesProcessed++;
+        }
+        return content;
+    }
+
+    /**
+     * Helper method to safely write files
+     */
+    safeWriteFile(filePath, content, mode = 0o644) {
+        const success = FileSystemUtils.writeFile(filePath, content, mode);
+        if (success) {
+            this.metrics.filesProcessed++;
+            this.metrics.operationsPerformed++;
+        }
+        return success;
+    }
+
+    /**
+     * Display progress if verbose mode enabled
+     */
+    showProgress(message, options = {}) {
+        if (options.verbose || process.env.NODE_ENV === 'development') {
+            console.log(`🔄 ${message}`);
+        }
+    }
+}
+
+module.exports = BaseCommand;