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

package/scripts/postinstall.js

@@ -3,180 +3,195 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
 
-// Check for skip flag
-const skipSetup = process.env.CLAUDE_SKIP_SETUP === 'true' || 
-                 process.argv.includes('--skip-setup');
+const skipSetup = process.env.CLAUDE_SKIP_SETUP === 'true' ||
+                  process.argv.includes('--skip-setup');
 
-console.log('🚀 Setting up Claude Custom Commands...');
+console.log('Setting up Claude Custom Commands...');
 
-async function runSetup() {
-    try {
-        // Get Claude Code directory
-        const homeDir = os.homedir();
-        const claudeDir = path.join(homeDir, '.claude');
-        const commandsDir = path.join(claudeDir, 'commands');
-        const hooksDir = path.join(claudeDir, 'hooks');
-        
-        // Ensure Claude directories exist
-        if (!fs.existsSync(claudeDir)) {
-            fs.mkdirSync(claudeDir, { recursive: true });
-            console.log('✅ Created .claude directory');
-        }
-        
-        if (!fs.existsSync(commandsDir)) {
-            fs.mkdirSync(commandsDir, { recursive: true });
-            console.log('✅ Created .claude/commands directory');
-        }
-        
-        if (!fs.existsSync(hooksDir)) {
-            fs.mkdirSync(hooksDir, { recursive: true });
-            console.log('✅ Created .claude/hooks directory');
-        }
-        
-        // Get package installation directory
-        const packageDir = __dirname.replace('/scripts', '');
-        
-        // Check if we should run interactive setup
-        if (!skipSetup && process.stdin.isTTY) {
-            console.log('\n📋 Starting Interactive Setup Wizard...');
-            console.log('(Use --skip-setup or set CLAUDE_SKIP_SETUP=true to skip)\n');
-            
-            const InteractiveSetupWizard = require('../lib/setup-wizard');
-            const wizard = new InteractiveSetupWizard(claudeDir);
-            
-            // Validate environment first (REQ-006)
-            const envCheck = wizard.validateEnvironment();
-            if (!envCheck.valid) {
-                console.error('❌ Environment validation failed:', envCheck.message);
-                process.exit(1);
-            }
-            
-            // Run interactive setup (REQ-007)
-            const setupResult = await wizard.runInteractiveSetup();
-            
-            if (setupResult.completed) {
-                const config = setupResult.configuration;
-                
-                // Install commands based on selection
-                const sourceCommandsDir = path.join(packageDir, 'commands');
-                if (fs.existsSync(sourceCommandsDir)) {
-                    copySelectedCommands(sourceCommandsDir, commandsDir, config);
-                }
-                
-                // Install security hooks if selected
-                if (config.securityHooks) {
-                    const sourceHooksDir = path.join(packageDir, 'hooks');
-                    if (fs.existsSync(sourceHooksDir)) {
-                        copySelectedHooks(sourceHooksDir, hooksDir, config.selectedHooks || []);
-                    }
-                }
-                
-                // Apply configuration template
-                if (config.template) {
-                    const templateFile = path.join(packageDir, 'templates', `${config.template}-settings.json`);
-                    const targetFile = path.join(claudeDir, 'settings.json');
-                    if (fs.existsSync(templateFile)) {
-                        fs.copyFileSync(templateFile, targetFile);
-                        console.log(`✅ Applied ${config.template} configuration template`);
-                    }
-                }
-            }
-        } else {
-            // Non-interactive installation - install all commands by default
-            console.log('Running non-interactive installation...');
-            
-            const sourceCommandsDir = path.join(packageDir, 'commands');
-            if (fs.existsSync(sourceCommandsDir)) {
-                copyAllCommands(sourceCommandsDir, commandsDir);
-            }
-        }
-        
-        // Count installed commands (now in flat structure)
-        if (fs.existsSync(commandsDir)) {
-            const installedCommands = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md')).length;
-            console.log(`\n📦 Installed ${installedCommands} commands`);
-        }
-        
-        console.log('\n🎉 Installation complete!');
-        console.log('\nNext steps:');
-        console.log('1. Run: claude-commands list');
-        console.log('2. Try: claude-commands --help');
-        console.log('3. Configure: claude-commands config');
-        console.log('4. Explore commands in Claude Code using /xhelp\n');
-        
-    } catch (error) {
-        console.error('❌ Installation failed:', error.message);
-        process.exit(1);
-    }
+// --- Directory helpers ---
+
+function ensureDir(dirPath, label) {
+    if (fs.existsSync(dirPath)) return;
+    fs.mkdirSync(dirPath, { recursive: true });
+    console.log(`  Created ${label}`);
+}
+
+function getClaudeDirs() {
+    const homeDir = os.homedir();
+    const claudeDir = path.join(homeDir, '.claude');
+    return {
+        claudeDir,
+        commandsDir: path.join(claudeDir, 'commands'),
+        hooksDir: path.join(claudeDir, 'hooks')
+    };
 }
 
-function copyAllCommands(sourceDir, targetDir) {
-    const items = fs.readdirSync(sourceDir);
-    for (const item of items) {
-        const sourcePath = path.join(sourceDir, item);
-        const targetPath = path.join(targetDir, item);
-        
-        if (fs.statSync(sourcePath).isDirectory()) {
-            if (!fs.existsSync(targetPath)) {
-                fs.mkdirSync(targetPath, { recursive: true });
-            }
-            copyAllCommands(sourcePath, targetPath);
+// --- Command copying ---
+
+function copyCommandsFlat(sourceDir, targetDir) {
+    if (!fs.existsSync(sourceDir)) return;
+    for (const item of fs.readdirSync(sourceDir)) {
+        const src = path.join(sourceDir, item);
+        if (fs.statSync(src).isDirectory()) {
+            copyCommandsFlat(src, targetDir);
         } else if (item.endsWith('.md')) {
-            fs.copyFileSync(sourcePath, targetPath);
+            fs.copyFileSync(src, path.join(targetDir, item));
+            console.log(`  Installed command: ${item}`);
         }
     }
 }
 
+function copyCommandSubdir(sourceDir, subdir, targetDir) {
+    const sub = path.join(sourceDir, subdir);
+    if (fs.existsSync(sub)) copyCommandsFlat(sub, targetDir);
+}
+
+function shouldCopyActive(type, sets) {
+    return type === 'standard' || sets.includes('development');
+}
+
+function shouldCopyExperimental(type, sets) {
+    return type === 'full' || sets.includes('experimental');
+}
+
 function copySelectedCommands(sourceDir, targetDir, config) {
-    // Based on installation type, copy appropriate commands
-    const installationType = config.installationType || 'standard';
-    
-    if (installationType === 'full' || !config.commandSets) {
-        // Copy all commands
-        copyAllCommands(sourceDir, targetDir);
-    } else {
-        // Copy selected command sets
-        const commandSets = config.commandSets || [];
-        
-        // Always copy active commands for standard installation (flat structure)
-        if (installationType === 'standard' || commandSets.includes('development')) {
-            const activeSource = path.join(sourceDir, 'active');
-            if (fs.existsSync(activeSource)) {
-                copyAllCommands(activeSource, targetDir); // Copy directly to targetDir, no subdirectory
-            }
-        }
-        
-        // Copy experimental if selected (flat structure to avoid namespace)
-        if (commandSets.includes('experimental') || installationType === 'full') {
-            const expSource = path.join(sourceDir, 'experiments');
-            if (fs.existsSync(expSource)) {
-                copyAllCommands(expSource, targetDir); // Copy directly to targetDir, no subdirectory
-            }
+    const type = config.installationType || 'standard';
+    if (type === 'full' || !config.commandSets) {
+        copyCommandsFlat(sourceDir, targetDir);
+        return;
+    }
+    const sets = config.commandSets || [];
+    if (shouldCopyActive(type, sets)) copyCommandSubdir(sourceDir, 'active', targetDir);
+    if (shouldCopyExperimental(type, sets)) copyCommandSubdir(sourceDir, 'experiments', targetDir);
+}
+
+// --- Hook copying ---
+
+function copyHookFile(src, dest, label) {
+    fs.copyFileSync(src, dest);
+    if (label.endsWith('.sh')) fs.chmodSync(dest, '755');
+    console.log(`  Installed hook: ${label}`);
+}
+
+function copyHooksLibDir(sourceDir, targetDir) {
+    const libSrc = path.join(sourceDir, 'lib');
+    if (!fs.existsSync(libSrc)) return;
+    const libDest = path.join(targetDir, 'lib');
+    ensureDir(libDest, 'hooks/lib');
+    for (const f of fs.readdirSync(libSrc)) {
+        const src = path.join(libSrc, f);
+        if (fs.statSync(src).isFile()) {
+            copyHookFile(src, path.join(libDest, f), `lib/${f}`);
         }
     }
 }
 
 function copySelectedHooks(sourceDir, targetDir, selectedHooks) {
-    const items = fs.readdirSync(sourceDir);
-    for (const item of items) {
-        const sourcePath = path.join(sourceDir, item);
-        
-        // Copy hook if it's selected or if no specific selection (copy all)
-        if (selectedHooks.length === 0 || selectedHooks.some(h => item.includes(h))) {
-            const targetPath = path.join(targetDir, item);
-            fs.copyFileSync(sourcePath, targetPath);
-            
-            // Make shell scripts executable
-            if (item.endsWith('.sh')) {
-                fs.chmodSync(targetPath, '755');
-            }
-            
-            console.log(`✅ Installed hook: ${item}`);
+    for (const item of fs.readdirSync(sourceDir)) {
+        const src = path.join(sourceDir, item);
+        if (fs.statSync(src).isDirectory()) continue;
+        const match = selectedHooks.length === 0 || selectedHooks.some(h => item.includes(h));
+        if (match) copyHookFile(src, path.join(targetDir, item), item);
+    }
+    copyHooksLibDir(sourceDir, targetDir);
+}
+
+// --- Template application ---
+
+function applyTemplate(packageDir, claudeDir, templateName) {
+    const src = path.join(packageDir, 'templates', `${templateName}-settings.json`);
+    if (!fs.existsSync(src)) return;
+    const dest = path.join(claudeDir, 'settings.json');
+    fs.copyFileSync(src, dest);
+    console.log(`  Applied ${templateName} configuration template`);
+}
+
+// --- Interactive setup ---
+
+function installFromConfig(packageDir, dirs, config) {
+    const cmdSrc = path.join(packageDir, 'commands');
+    if (fs.existsSync(cmdSrc)) copySelectedCommands(cmdSrc, dirs.commandsDir, config);
+    if (config.securityHooks) {
+        const hookSrc = path.join(packageDir, 'hooks');
+        if (fs.existsSync(hookSrc)) copySelectedHooks(hookSrc, dirs.hooksDir, config.selectedHooks || []);
+    }
+    if (config.template) applyTemplate(packageDir, dirs.claudeDir, config.template);
+}
+
+async function runInteractiveInstall(packageDir, dirs) {
+    console.log('\nStarting Interactive Setup Wizard...');
+    console.log('(Use --skip-setup or set CLAUDE_SKIP_SETUP=true to skip)\n');
+    const Wizard = require('../lib/setup-wizard');
+    const wizard = new Wizard(dirs.claudeDir);
+    const envCheck = wizard.validateEnvironment();
+    if (!envCheck.valid) {
+        console.error('Environment validation failed:', envCheck.message);
+        console.error('\nTroubleshooting:');
+        console.error('  - Ensure Node.js >= 18 is installed');
+        console.error('  - Check write permissions on ~/.claude/');
+        console.error('  - Try: claude-commands setup --dry-run');
+        process.exit(1);
+    }
+    const result = await wizard.runInteractiveSetup();
+    if (!result.completed) return;
+    installFromConfig(packageDir, dirs, result.configuration);
+}
+
+// --- Non-interactive setup ---
+
+function runNonInteractiveInstall(packageDir, dirs) {
+    console.log('Running non-interactive installation...');
+    const cmdSrc = path.join(packageDir, 'commands');
+    if (fs.existsSync(cmdSrc)) copyCommandsFlat(cmdSrc, dirs.commandsDir);
+}
+
+// --- Main ---
+
+function printSummary(commandsDir) {
+    if (fs.existsSync(commandsDir)) {
+        const count = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md')).length;
+        console.log(`\nInstalled ${count} commands`);
+    }
+    console.log('\nInstallation complete!');
+    console.log('\nNext steps:');
+    console.log('1. Run: claude-commands list');
+    console.log('2. Try: claude-commands --help');
+    console.log('3. Configure: claude-commands config');
+    console.log('4. Explore commands in Claude Code using /xhelp\n');
+}
+
+function printInstallError(error) {
+    console.error('Installation failed:', error.message);
+    console.error('\nTroubleshooting:');
+    console.error('  - Check write permissions: ls -la ~/.claude/');
+    console.error('  - Try manual install: claude-commands install --all');
+    console.error('  - Report issues: https://github.com/PaulDuvall/claude-code/issues');
+}
+
+function initDirs() {
+    const dirs = getClaudeDirs();
+    ensureDir(dirs.claudeDir, '.claude');
+    ensureDir(dirs.commandsDir, '.claude/commands');
+    ensureDir(dirs.hooksDir, '.claude/hooks');
+    return dirs;
+}
+
+async function runSetup() {
+    try {
+        const dirs = initDirs();
+        const packageDir = path.dirname(__dirname);
+
+        if (!skipSetup && process.stdin.isTTY) {
+            await runInteractiveInstall(packageDir, dirs);
+        } else {
+            runNonInteractiveInstall(packageDir, dirs);
         }
+        printSummary(dirs.commandsDir);
+    } catch (error) {
+        printInstallError(error);
+        process.exit(1);
     }
 }
 
-// Run the setup
-runSetup();
+runSetup();

package/subagents/debug-specialist.md

@@ -1,3 +1,10 @@
+---
+name: debug-specialist
+description: "Specialized debugging assistant with expertise in root cause analysis, error interpretation, and systematic troubleshooting"
+tags: ["debugging", "error-analysis", "troubleshooting", "performance"]
+tools: ["Read", "Bash", "Grep", "Edit", "Glob"]
+---
+
 # Debug Specialist Sub-Agent
 
 ## Agent Description

package/templates/README.md

@@ -0,0 +1,115 @@
+# Claude Code Settings Templates
+
+This directory contains example `settings.json` configurations for different use cases.
+
+## Templates Available
+
+### 1. `basic-settings.json`
+**Use case**: Simple development setup
+**Features**:
+- Basic tool permissions for custom commands
+- API key helper configuration
+- Standard performance settings
+- Minimal environment variables
+
+**To use**:
+```bash
+cp templates/basic-settings.json ~/.claude/settings.json
+```
+
+### 2. `security-focused-settings.json` 
+**Use case**: Security-conscious development
+**Features**:
+- All basic features plus:
+- Security hooks enabled (credential exposure prevention)
+- Restrictive tool permissions
+- Security environment variables
+- Slack/Teams webhook integration for alerts
+
+**Prerequisites**: Install security hooks first
+```bash
+cp hooks/prevent-credential-exposure.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/prevent-credential-exposure.sh
+```
+
+**To use**:
+```bash
+cp templates/security-focused-settings.json ~/.claude/settings.json
+# Edit SECURITY_WEBHOOK_URL to your actual webhook
+```
+
+### 3. `comprehensive-settings.json`
+**Use case**: Comprehensive development with full governance
+**Features**:
+- All security features plus:
+- Comprehensive audit logging
+- Comprehensive permissions
+- MCP server integration
+- Enhanced performance settings
+- Full monitoring and compliance
+
+**Prerequisites**: 
+- Install all security hooks
+- Docker Desktop running (for MCP servers)
+- Configure organizational webhooks
+
+**To use**:
+```bash
+cp templates/comprehensive-settings.json ~/.claude/settings.json
+# Configure webhooks and organizational settings
+```
+
+### 4. `global-claude.md`
+**Use case**: Universal development standards for all projects
+**Features**:
+- Verification-before-action rules (prevent fabricated references)
+- Zero-error test policy
+- Platform-specific formatting guidelines (LinkedIn, Slack, GitHub, email)
+- Code structure limits (function length, nesting, complexity)
+- Security checklist (no hardcoded secrets, parameterized SQL, input validation)
+- Session management and failure protocols
+
+**To use**:
+```bash
+cp templates/global-claude.md ~/.claude/CLAUDE.md
+```
+
+## Configuration Notes
+
+### Settings Hierarchy
+Settings are applied in this order (later overrides earlier):
+1. User settings: `~/.claude/settings.json`
+2. Project settings: `.claude/settings.json` 
+3. Local settings: `.claude/settings.local.json`
+
+### Security Considerations
+- Always review webhook URLs before using
+- Set appropriate file permissions: `chmod 600 ~/.claude/settings.json`
+- Store sensitive settings in environment variables, not directly in JSON
+- Use `.claude/settings.local.json` for personal settings in team projects
+
+### Customization
+These templates are starting points. Customize based on your needs:
+- Add/remove allowed tools
+- Adjust timeout values
+- Configure additional hooks
+- Set team-specific environment variables
+
+### Validation
+Use the validation script to check your configuration:
+```bash
+./validate-commands.sh --check-settings
+```
+
+## Troubleshooting
+
+### Common Issues
+1. **Commands not working**: Check `allowedTools` array includes required tools
+2. **Hooks not running**: Verify executable permissions and file paths
+3. **Timeouts**: Increase timeout values for slow operations
+4. **Permissions errors**: Check file permissions on settings.json and hooks
+
+### Getting Help
+- Run `./verify-setup.sh` to diagnose issues
+- Check Claude Code logs: `~/.claude/logs/`
+- Review the main README.md troubleshooting section

package/templates/basic-settings.json

@@ -0,0 +1,30 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Read(*)",
+      "Edit(*)",
+      "Write(*)",
+      "Glob(*)",
+      "Grep(*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Tool execution logged at $(date)' >> ~/.claude/logs/tool-usage.log"
+          }
+        ]
+      }
+    ]
+  },
+  "env": {
+    "DISABLE_TELEMETRY": "1"
+  },
+  "includeCoAuthoredBy": true,
+  "cleanupPeriodDays": 30
+}

package/templates/comprehensive-settings.json

@@ -0,0 +1,57 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Read(*)",
+      "Edit(*)",
+      "Write(*)",
+      "Glob(*)",
+      "Grep(*)",
+      "WebFetch(*)",
+      "WebSearch(*)",
+      "NotebookEdit(*)"
+    ],
+    "ask": [
+      "Bash(sudo *)",
+      "Bash(rm -rf *)",
+      "Edit(/etc/*)",
+      "Read(~/.ssh/*)"
+    ],
+    "deny": [
+      "Bash(*production*)",
+      "Bash(*admin*)",
+      "Read(/etc/shadow)",
+      "Edit(/etc/passwd)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/prevent-credential-exposure.sh",
+            "blocking": true,
+            "timeout": 10000
+          },
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/verify-before-edit.sh",
+            "blocking": false,
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": []
+  },
+  "env": {
+    "DISABLE_TELEMETRY": "1",
+    "ANTHROPIC_LOG": "info"
+  },
+  "includeCoAuthoredBy": true,
+  "cleanupPeriodDays": 30,
+  "model": "claude-sonnet-4-6",
+  "enableAllProjectMcpServers": false
+}