@paulduvall/claude-dev-toolkit 0.0.1-alpha.1 → 0.0.1-alpha.11

package/README.md

@@ -1,19 +1,12 @@
 # Claude Dev Toolkit
 
-[![npm version](https://badge.fury.io/js/claude-dev-toolkit.svg)](https://www.npmjs.com/package/claude-dev-toolkit)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-![Test Status](https://img.shields.io/badge/tests-100%25%20passing-brightgreen)
-![Active Commands](https://img.shields.io/badge/active%20commands-13-blue)
-![Experimental Commands](https://img.shields.io/badge/experimental%20commands-45-orange)
-![Total Commands](https://img.shields.io/badge/total%20commands-58-brightgreen)
-
 **Transform Claude Code into a complete development platform** with 58 AI-powered custom commands that automate your entire software development workflow.
 
 ## 🚀 Quick Installation
 
 ```bash
 # Install globally via NPM
-npm install -g claude-dev-toolkit
+npm install -g @paulduvall/claude-dev-toolkit
 
 # Commands are immediately available in Claude Code
 claude
@@ -33,7 +26,7 @@ claude
 
 ### Option 1: Automatic Setup (Recommended)
 ```bash
-npm install -g claude-dev-toolkit
+npm install -g @paulduvall/claude-dev-toolkit
 # Interactive setup wizard runs automatically
 ```
 
@@ -41,7 +34,7 @@ npm install -g claude-dev-toolkit
 ```bash
 # Install specific command sets
 claude-commands install --active        # Install 13 production commands
-claude-commands install --experimental  # Install 45 experimental commands  
+claude-commands install --experiments  # Install 45 experimental commands  
 claude-commands install --all           # Install all 58 commands
 ```
 
@@ -49,6 +42,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
@@ -89,9 +83,24 @@ Advanced commands for specialized workflows:
 claude-commands list                    # List all available commands
 claude-commands status                  # Show installation status
 claude-commands install --active       # Install production commands
-claude-commands install --experimental # Install experimental commands
+claude-commands install --experiments # Install experimental commands
 claude-commands install --all          # Install all commands
 
+# Configuration Management
+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
+claude-commands subagents --help        # Show subagents command help
+
 # In Claude Code
 /xhelp                                 # Show command help
 /xtest                                 # Run intelligent test suite
@@ -102,19 +111,37 @@ claude-commands install --all          # Install all commands
 
 ## 🔧 Configuration
 
+### Configuration Management
+
+Use the built-in config command to manage Claude Code settings:
+
+```bash
+# List available configuration templates
+claude-commands config --list
+
+# Apply a specific template
+claude-commands config --template basic-settings.json
+claude-commands config --template security-focused-settings.json  
+claude-commands config --template comprehensive-settings.json
+
+# Show help for config command
+claude-commands config --help
+```
+
 ### Installation Locations
 - **Commands**: `~/.claude/commands/active/` and `~/.claude/commands/experiments/`
 - **Configuration**: `~/.claude/settings.json`
 - **Security Hooks**: `~/.claude/hooks/`
+- **Templates**: Bundled with package installation
 
 ### Configuration Templates
 The package includes three pre-configured templates:
 
 1. **Basic** (`basic-settings.json`): Minimal setup for command functionality
-2. **Security-Focused** (`security-focused-settings.json`): Enhanced security with hooks
+2. **Security-Focused** (`security-focused-settings.json`): Enhanced security with hooks  
 3. **Comprehensive** (`comprehensive-settings.json`): Full feature set with governance
 
-Templates are automatically applied during interactive setup or can be manually copied to `~/.claude/settings.json`.
+Templates are applied via the config command with automatic backup of existing settings.
 
 ## 🧪 Development & Testing
 
@@ -127,6 +154,8 @@ npm test
 npm run test:commands     # Command validation
 npm run test:workflow     # Core workflow tests
 npm run test:security     # Security command tests
+npm run test:config       # Configuration command tests
+npm run test:subagents    # Subagents CLI command tests
 npm run test:req007       # Interactive setup wizard
 npm run test:req009       # Configuration templates
 npm run test:req018       # Security hook installation
@@ -144,8 +173,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
 
@@ -173,7 +202,7 @@ claude-commands install --active       # Reinstall commands
 chmod 755 ~/.claude/commands/*.md      # Fix permissions
 
 # Missing experimental commands?
-claude-commands install --experimental # Install experimental set
+claude-commands install --experiments # Install experimental set
 
 # Test failures?
 npm test                               # Run full test suite
@@ -182,13 +211,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
@@ -204,6 +233,7 @@ Every command includes built-in help:
 /xtest help         # Show all testing options
 /xquality help      # Show quality check options  
 /xsecurity help     # Show security scanning options
+/xconfig help       # Show configuration options
 ```
 
 ## 🤝 Contributing
@@ -221,8 +251,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
 
@@ -233,7 +263,28 @@ npm test
 
 ## 🔄 Recent Updates
 
-### Version 0.0.1-alpha.1
+### 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
+- ✅ **Subagents Support**: Multi-agent coordination capabilities
+- ✅ **Enhanced Documentation**: Updated installation and usage instructions
+
+### Version 0.0.1-alpha.2
 - ✅ **Symlink Consolidation**: Eliminated duplicate directories
 - ✅ **JavaScript Migration**: Complete test suite migration from Python
 - ✅ **Enhanced Templates**: Fixed configuration template issues

package/bin/claude-commands

@@ -20,64 +20,53 @@ program
     .command('list')
     .description('List all available commands')
     .option('-a, --active', 'Show only active commands')
-    .option('-e, --experimental', 'Show only experimental commands')
+    .option('-e, --experiments', 'Show only experimental commands')
     .action((options) => {
         const claudeDir = path.join(os.homedir(), '.claude', 'commands');
-        const activeDir = path.join(claudeDir, 'active');
-        const experimentalDir = path.join(claudeDir, 'experiments');
         
         console.log('📦 Claude Custom Commands\n');
         
-        if (!options.experimental) {
-            console.log('🎯 Active Commands:');
-            if (fs.existsSync(activeDir)) {
-                const activeCommands = fs.readdirSync(activeDir)
-                    .filter(f => f.endsWith('.md'))
-                    .map(f => f.replace('.md', ''))
-                    .sort();
-                
-                if (activeCommands.length > 0) {
-                    activeCommands.forEach(cmd => console.log(`  /${cmd}`));
-                } else {
-                    console.log('  No active commands found');
-                }
+        if (fs.existsSync(claudeDir)) {
+            const allCommands = fs.readdirSync(claudeDir)
+                .filter(f => f.endsWith('.md'))
+                .map(f => f.replace('.md', ''))
+                .sort();
+            
+            if (allCommands.length > 0) {
+                console.log('🚀 Available Commands:');
+                allCommands.forEach(cmd => console.log(`  /${cmd}`));
+                console.log(`\n📊 Total: ${allCommands.length} commands`);
             } else {
-                console.log('  Commands directory not found');
+                console.log('  No commands found');
             }
-            console.log('');
+        } else {
+            console.log('  Commands directory not found');
         }
         
-        if (!options.active) {
-            console.log('🧪 Experimental Commands:');
-            if (fs.existsSync(experimentalDir)) {
-                const expCommands = fs.readdirSync(experimentalDir)
-                    .filter(f => f.endsWith('.md'))
-                    .map(f => f.replace('.md', ''))
-                    .sort();
-                
-                if (expCommands.length > 0) {
-                    expCommands.forEach(cmd => console.log(`  /${cmd}`));
-                } else {
-                    console.log('  No experimental commands found');
-                }
-            } else {
-                console.log('  Commands directory not found');
-            }
-            console.log('');
-        }
-        
-        console.log('💡 Usage: Try /xhelp in Claude Code to see all commands');
+        console.log('\n💡 Usage: Try /xhelp in Claude Code to see all commands');
     });
 
 program
     .command('install')
-    .description('Install command sets')
-    .option('--active', 'Install active commands only')
-    .option('--experimental', '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
@@ -85,33 +74,22 @@ program
     .description('Show installation status')
     .action(() => {
         const claudeDir = path.join(os.homedir(), '.claude', 'commands');
-        const activeDir = path.join(claudeDir, 'active');
-        const experimentalDir = path.join(claudeDir, 'experiments');
         
         console.log('📊 Claude Dev Toolkit Status\n');
         
         // Check Claude directory
-        console.log('📁 Installation Paths:');
-        console.log(`   Claude directory: ${fs.existsSync(claudeDir) ? '✅' : '❌'} ${claudeDir}`);
-        console.log(`   Active commands:  ${fs.existsSync(activeDir) ? '✅' : '❌'} ${activeDir}`);
-        console.log(`   Experimental:     ${fs.existsSync(experimentalDir) ? '✅' : '❌'} ${experimentalDir}\n`);
+        console.log('📁 Installation Path:');
+        console.log(`   Commands directory: ${fs.existsSync(claudeDir) ? '✅' : '❌'} ${claudeDir}\n`);
         
         // Count commands
-        let activeCount = 0;
-        let expCount = 0;
+        let totalCount = 0;
         
-        if (fs.existsSync(activeDir)) {
-            activeCount = fs.readdirSync(activeDir).filter(f => f.endsWith('.md')).length;
-        }
-        
-        if (fs.existsSync(experimentalDir)) {
-            expCount = fs.readdirSync(experimentalDir).filter(f => f.endsWith('.md')).length;
+        if (fs.existsSync(claudeDir)) {
+            totalCount = fs.readdirSync(claudeDir).filter(f => f.endsWith('.md')).length;
         }
         
         console.log('📦 Command Inventory:');
-        console.log(`   Active commands:      ${activeCount}`);
-        console.log(`   Experimental commands: ${expCount}`);
-        console.log(`   Total commands:       ${activeCount + expCount}\n`);
+        console.log(`   Total commands: ${totalCount}\n`);
         
         // Package info
         console.log('📋 Package Information:');
@@ -119,13 +97,234 @@ program
         console.log(`   CLI Location: ${process.argv[1]}\n`);
         
         // Quick health check
-        const isHealthy = fs.existsSync(claudeDir) && (activeCount > 0 || expCount > 0);
+        const isHealthy = fs.existsSync(claudeDir) && totalCount > 0;
         console.log(`🔍 Overall Status: ${isHealthy ? '✅ Healthy' : '⚠️  Issues detected'}`);
         
         if (!isHealthy) {
             console.log('\n💡 Troubleshooting:');
-            console.log('   • Try: npm install -g claude-dev-toolkit');
-            console.log('   • Or reinstall to refresh commands');
+            console.log('   • Try: npm install -g @paulduvall/claude-dev-toolkit');
+            console.log('   • Or reinstall: claude-commands install --all');
+        }
+    });
+
+program
+    .command('subagents')
+    .description('Manage AI subagents for Claude Code')
+    .option('-l, --list', 'List available subagents')
+    .option('-i, --install', 'Install subagents to Claude Code')
+    .action((options) => {
+        const subagents = require('../lib/subagents');
+        subagents.handleCommand(options);
+    });
+
+program
+    .command('config')
+    .description('Manage Claude Code configuration templates')
+    .option('-l, --list', 'List available configuration templates')
+    .option('-t, --template <name>', 'Apply configuration template')
+    .action((options) => {
+        const config = require('../lib/config');
+        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 (OpenID Connect) integration with AWS
+
+    🎯 WHAT IT DOES:
+    • Creates GitHub OIDC identity provider in AWS
+    • Sets up IAM role with trust policy for GitHub Actions
+    • Configures repository variables for secure AWS access
+    • Enables passwordless authentication from GitHub to AWS
+
+    📋 PREREQUISITES (REQUIRED):
+    • AWS CLI installed and configured (aws configure)
+    • GitHub CLI authenticated (gh auth login) 
+    • Git repository with GitHub remote origin
+    • AWS account with IAM permissions
+
+    ⚙️  WHAT IT CREATES:
+    • AWS OIDC Identity Provider for GitHub
+    • IAM Role for GitHub Actions (with trust policy)
+    • IAM policies for AWS resource access
+    • GitHub repository variables (AWS_DEPLOYMENT_ROLE, AWS_REGION)
+
+    🚀 BASIC USAGE:
+    • claude-commands oidc                    # Auto-detect settings
+    • claude-commands oidc --dry-run          # Preview without changes
+    • claude-commands oidc --region us-west-2 # Specify AWS region`)
+    .option('--region <region>', 'AWS region for OIDC setup', 'us-east-1')
+    .option('--role-name <name>', 'IAM role name for GitHub Actions', 'GitHubActionsRole')
+    .option('--repository-path <path>', 'Path to repository for OIDC setup (auto-detected)', process.cwd())
+    .option('--dry-run', 'Preview actions without making changes (SAFE to run)')
+    .option('--verbose', 'Show detailed output during execution')
+    .action(async (options) => {
+        const OidcCommand = require('../lib/oidc-command');
+        const oidcCmd = new OidcCommand();
+        try {
+            const result = await oidcCmd.execute(options);
+            if (result.success) {
+                if (result.message) {
+                    console.log(result.message);
+                }
+                if (options.verbose && result.duration) {
+                    console.log(`✅ Completed in ${result.duration}ms`);
+                }
+            } else {
+                console.error(`❌ OIDC setup failed: ${result.error || 'Unknown error'}`);
+                if (result.enhancedError && result.enhancedError.suggestions) {
+                    result.enhancedError.suggestions.forEach(suggestion => {
+                        console.log(suggestion);
+                    });
+                }
+                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);
         }
     });