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

package/lib/base/command-result.js

@@ -0,0 +1,184 @@
+/**
+ * Command Result Value Object
+ * Standardized result structure for all command operations
+ */
+
+class CommandResult {
+    constructor(success, data = {}) {
+        this.success = success;
+        this.timestamp = new Date().toISOString();
+        
+        // Merge provided data
+        Object.assign(this, data);
+    }
+
+    /**
+     * Create successful result
+     */
+    static success(data = {}) {
+        return new CommandResult(true, data);
+    }
+
+    /**
+     * Create failure result
+     */
+    static failure(error, data = {}) {
+        return new CommandResult(false, {
+            error: typeof error === 'string' ? error : error.message,
+            originalError: typeof error === 'object' ? error : undefined,
+            ...data
+        });
+    }
+
+    /**
+     * Create result from boolean
+     */
+    static fromBoolean(isSuccess, successData = {}, failureData = {}) {
+        return isSuccess 
+            ? CommandResult.success(successData)
+            : CommandResult.failure('Operation failed', failureData);
+    }
+
+    /**
+     * Check if result indicates success
+     */
+    isSuccess() {
+        return this.success === true;
+    }
+
+    /**
+     * Check if result indicates failure
+     */
+    isFailure() {
+        return this.success === false;
+    }
+
+    /**
+     * Get error message if failure
+     */
+    getError() {
+        return this.success ? null : (this.error || 'Unknown error');
+    }
+
+    /**
+     * Get data payload
+     */
+    getData(key = null) {
+        if (key) {
+            return this[key];
+        }
+        
+        // Return all data except control properties
+        const { success, timestamp, error, originalError, ...data } = this;
+        return data;
+    }
+
+    /**
+     * Transform result with a function
+     */
+    map(transform) {
+        if (this.isFailure()) {
+            return this; // Return unchanged failure
+        }
+        
+        try {
+            const transformedData = transform(this.getData());
+            return CommandResult.success(transformedData);
+        } catch (error) {
+            return CommandResult.failure(error);
+        }
+    }
+
+    /**
+     * Chain operations that might fail
+     */
+    flatMap(operation) {
+        if (this.isFailure()) {
+            return this; // Return unchanged failure
+        }
+        
+        try {
+            const result = operation(this.getData());
+            return result instanceof CommandResult ? result : CommandResult.success(result);
+        } catch (error) {
+            return CommandResult.failure(error);
+        }
+    }
+
+    /**
+     * Provide fallback value for failures
+     */
+    orElse(fallback) {
+        return this.isSuccess() ? this.getData() : fallback;
+    }
+
+    /**
+     * Convert to JSON for serialization
+     */
+    toJSON() {
+        return {
+            success: this.success,
+            timestamp: this.timestamp,
+            ...(this.success ? this.getData() : { error: this.getError() })
+        };
+    }
+
+    /**
+     * Convert to human-readable string
+     */
+    toString() {
+        if (this.success) {
+            const data = this.getData();
+            const keys = Object.keys(data);
+            
+            if (keys.length === 0) {
+                return '✅ Success';
+            } else if (keys.length === 1) {
+                return `✅ Success: ${keys[0]} = ${data[keys[0]]}`;
+            } else {
+                return `✅ Success (${keys.length} properties)`;
+            }
+        } else {
+            return `❌ Failure: ${this.getError()}`;
+        }
+    }
+
+    /**
+     * Merge with another result (for combining operations)
+     */
+    merge(otherResult) {
+        if (this.isFailure()) return this;
+        if (otherResult.isFailure()) return otherResult;
+        
+        return CommandResult.success({
+            ...this.getData(),
+            ...otherResult.getData()
+        });
+    }
+
+    /**
+     * Add metrics to the result
+     */
+    withMetrics(metrics) {
+        this.metrics = metrics;
+        return this;
+    }
+
+    /**
+     * Add duration to the result
+     */
+    withDuration(duration) {
+        this.duration = typeof duration === 'number' ? `${duration.toFixed(2)}s` : duration;
+        return this;
+    }
+
+    /**
+     * Add context information
+     */
+    withContext(context) {
+        this.context = context;
+        return this;
+    }
+}
+
+module.exports = CommandResult;

package/lib/config/constants.js

@@ -0,0 +1,255 @@
+/**
+ * Configuration Constants
+ * Centralized configuration constants used throughout the application
+ */
+
+// System Requirements
+const SYSTEM_REQUIREMENTS = {
+    MIN_NODE_VERSION: '16.0.0',
+    MIN_NPM_VERSION: '7.0.0',
+    MIN_MEMORY_GB: 2,
+    MIN_DISK_SPACE_MB: 100,
+    SUPPORTED_PLATFORMS: ['linux', 'darwin', 'win32'],
+    SUPPORTED_ARCHITECTURES: ['x64', 'arm64']
+};
+
+// Download Links for Dependencies
+const DOWNLOAD_LINKS = {
+    git: {
+        linux: 'https://git-scm.com/download/linux',
+        darwin: 'https://git-scm.com/download/mac',
+        win32: 'https://git-scm.com/download/win',
+        all: 'https://git-scm.com/downloads'
+    },
+    node: {
+        all: 'https://nodejs.org/en/download/',
+        lts: 'https://nodejs.org/en/download/package-manager/',
+        docker: 'https://hub.docker.com/_/node'
+    },
+    python: {
+        all: 'https://www.python.org/downloads/',
+        anaconda: 'https://www.anaconda.com/products/distribution',
+        pyenv: 'https://github.com/pyenv/pyenv'
+    },
+    docker: {
+        linux: 'https://docs.docker.com/engine/install/',
+        darwin: 'https://docs.docker.com/desktop/install/mac-install/',
+        win32: 'https://docs.docker.com/desktop/install/windows-install/'
+    },
+    claudeCode: {
+        npm: 'https://www.npmjs.com/package/@anthropic-ai/claude-code',
+        github: 'https://github.com/anthropics/claude-code'
+    }
+};
+
+// Package Manager Commands
+const PACKAGE_MANAGERS = {
+    npm: {
+        name: 'npm',
+        install: 'npm install',
+        globalInstall: 'npm install -g',
+        update: 'npm update',
+        checkCommand: 'npm --version',
+        installUrl: 'https://docs.npmjs.com/downloading-and-installing-node-js-and-npm'
+    },
+    yarn: {
+        name: 'yarn',
+        install: 'yarn add',
+        globalInstall: 'yarn global add',
+        update: 'yarn upgrade',
+        checkCommand: 'yarn --version',
+        installUrl: 'https://classic.yarnpkg.com/lang/en/docs/install/'
+    },
+    pnpm: {
+        name: 'pnpm',
+        install: 'pnpm add',
+        globalInstall: 'pnpm add -g',
+        update: 'pnpm update',
+        checkCommand: 'pnpm --version',
+        installUrl: 'https://pnpm.io/installation'
+    },
+    brew: {
+        name: 'Homebrew',
+        install: 'brew install',
+        update: 'brew upgrade',
+        checkCommand: 'brew --version',
+        installUrl: 'https://brew.sh/',
+        platforms: ['darwin']
+    },
+    apt: {
+        name: 'apt',
+        install: 'sudo apt install',
+        update: 'sudo apt update && sudo apt upgrade',
+        checkCommand: 'apt --version',
+        platforms: ['linux']
+    },
+    yum: {
+        name: 'yum',
+        install: 'sudo yum install',
+        update: 'sudo yum update',
+        checkCommand: 'yum --version',
+        platforms: ['linux']
+    },
+    chocolatey: {
+        name: 'Chocolatey',
+        install: 'choco install',
+        update: 'choco upgrade',
+        checkCommand: 'choco --version',
+        installUrl: 'https://chocolatey.org/install',
+        platforms: ['win32']
+    },
+    winget: {
+        name: 'winget',
+        install: 'winget install',
+        update: 'winget upgrade',
+        checkCommand: 'winget --version',
+        platforms: ['win32']
+    }
+};
+
+// File and Directory Constants
+const PATHS = {
+    CLAUDE_DIR: '.claude',
+    COMMANDS_DIR: 'commands',
+    HOOKS_DIR: 'hooks',
+    BACKUPS_DIR: 'backups',
+    SUBAGENTS_DIR: 'subagents',
+    SETTINGS_FILE: 'settings.json',
+    LOG_FILE: 'claude-commands.log',
+    TEMP_DIR: '.temp',
+    ACTIVE_COMMANDS: 'active',
+    EXPERIMENTAL_COMMANDS: 'experiments'
+};
+
+// Command Configuration
+const COMMANDS = {
+    MAX_COMMANDS: 100,
+    DEFAULT_COMMAND_TYPE: 'active',
+    SUPPORTED_EXTENSIONS: ['.md', '.txt'],
+    FRONTMATTER_DELIMITER: '---',
+    REQUIRED_SECTIONS: ['description', 'usage', 'implementation'],
+    MAX_FILE_SIZE_MB: 5,
+    ENCODING: 'utf8'
+};
+
+// Backup Configuration  
+const BACKUP = {
+    MAX_BACKUPS: 10,
+    COMPRESSION_ENABLED: true,
+    COMPRESSION_LEVEL: 6,
+    RETENTION_DAYS: 30,
+    AUTO_CLEANUP: true,
+    BACKUP_FORMAT: 'tar.gz',
+    NAMING_PATTERN: 'backup-YYYYMMDD-HHMMSS'
+};
+
+// Installation Configuration
+const INSTALLATION = {
+    MAX_CONCURRENT_OPERATIONS: 5,
+    TIMEOUT_MS: 30000,
+    RETRY_ATTEMPTS: 3,
+    RETRY_DELAY_MS: 1000,
+    PROGRESS_UPDATE_INTERVAL: 500,
+    VALIDATION_ENABLED: true,
+    AUTO_BACKUP: false,
+    FORCE_OVERWRITE: false
+};
+
+// Logging Configuration
+const LOGGING = {
+    DEFAULT_LEVEL: 'info',
+    LEVELS: ['debug', 'info', 'warn', 'error'],
+    MAX_LOG_SIZE_MB: 10,
+    MAX_LOG_FILES: 5,
+    TIMESTAMP_FORMAT: 'YYYY-MM-DD HH:mm:ss',
+    ENABLE_COLORS: true,
+    ENABLE_CONTEXT: true
+};
+
+// Security Configuration
+const SECURITY = {
+    ALLOWED_PROTOCOLS: ['http:', 'https:', 'file:'],
+    MAX_DOWNLOAD_SIZE_MB: 50,
+    ALLOWED_FILE_TYPES: ['.md', '.txt', '.json', '.js', '.sh', '.py'],
+    DANGEROUS_COMMANDS: ['rm -rf', 'format', 'del /f', 'sudo rm'],
+    CREDENTIAL_PATTERNS: [
+        /api[_-]?key\s*[:=]\s*['"][^'"]+['"]/i,
+        /secret[_-]?key\s*[:=]\s*['"][^'"]+['"]/i,
+        /password\s*[:=]\s*['"][^'"]+['"]/i,
+        /token\s*[:=]\s*['"][^'"]+['"]/i
+    ],
+    HOOK_TIMEOUT_MS: 5000
+};
+
+// Error Messages
+const ERROR_MESSAGES = {
+    INSTALLATION_FAILED: 'Installation failed. Please check your setup and try again.',
+    PERMISSION_DENIED: 'Permission denied. Please check file permissions and try again.',
+    NETWORK_ERROR: 'Network error. Please check your internet connection.',
+    FILE_NOT_FOUND: 'Required file not found. Please ensure all dependencies are installed.',
+    INVALID_CONFIGURATION: 'Invalid configuration. Please check your settings.',
+    COMMAND_NOT_FOUND: 'Command not found. Please install required dependencies.',
+    VALIDATION_FAILED: 'Validation failed. Please check the input and try again.',
+    BACKUP_FAILED: 'Backup operation failed. Please check disk space and permissions.',
+    RESTORE_FAILED: 'Restore operation failed. Please check backup integrity.',
+    DEPENDENCY_MISSING: 'Required dependency is missing. Please install and try again.'
+};
+
+// Success Messages
+const SUCCESS_MESSAGES = {
+    INSTALLATION_COMPLETE: 'Installation completed successfully!',
+    BACKUP_CREATED: 'Backup created successfully.',
+    RESTORE_COMPLETE: 'Restore completed successfully.',
+    CONFIGURATION_UPDATED: 'Configuration updated successfully.',
+    VALIDATION_PASSED: 'All validations passed.',
+    CLEANUP_COMPLETE: 'Cleanup completed successfully.'
+};
+
+// CLI Configuration
+const CLI = {
+    PROGRAM_NAME: 'claude-commands',
+    VERSION: '1.0.0',
+    DESCRIPTION: 'Claude Code Custom Commands CLI',
+    DEFAULT_COMMAND: 'help',
+    EXIT_CODES: {
+        SUCCESS: 0,
+        GENERAL_ERROR: 1,
+        INVALID_USAGE: 2,
+        PERMISSION_DENIED: 3,
+        NOT_FOUND: 4,
+        NETWORK_ERROR: 5,
+        VALIDATION_ERROR: 6
+    }
+};
+
+// Export all constants
+module.exports = {
+    SYSTEM_REQUIREMENTS,
+    DOWNLOAD_LINKS,
+    PACKAGE_MANAGERS,
+    PATHS,
+    COMMANDS,
+    BACKUP,
+    INSTALLATION,
+    LOGGING,
+    SECURITY,
+    ERROR_MESSAGES,
+    SUCCESS_MESSAGES,
+    CLI
+};
+
+// Export individual constants for convenience
+module.exports.constants = {
+    SYSTEM_REQUIREMENTS,
+    DOWNLOAD_LINKS,
+    PACKAGE_MANAGERS,
+    PATHS,
+    COMMANDS,
+    BACKUP,
+    INSTALLATION,
+    LOGGING,
+    SECURITY,
+    ERROR_MESSAGES,
+    SUCCESS_MESSAGES,
+    CLI
+};

package/lib/config.js

@@ -145,7 +145,7 @@ function getAvailableTemplates(templatesDir) {
                         id: path.basename(file, '.json'),
                         name: file,
                         path: templatePath,
-                        description: data['// Description'] || `${file} template`,
+                        description: getTemplateDescription(file, data),
                         features: Object.keys(data).filter(key => !key.startsWith('//')).length
                     });
                 } catch (error) {
@@ -161,6 +161,226 @@ function getAvailableTemplates(templatesDir) {
     }
 }
 
+/**
+ * Get human-readable description for a template
+ * @param {string} filename - Template filename
+ * @param {Object} data - Parsed template data
+ * @returns {string} - Human-readable description
+ */
+function getTemplateDescription(filename, data) {
+    // Check for explicit description in template
+    if (data['// Description']) {
+        return data['// Description'];
+    }
+    
+    // Generate description based on filename
+    const basename = path.basename(filename, '.json');
+    switch (basename) {
+        case 'basic-settings':
+            return 'Minimal configuration for getting started with Claude Code';
+        case 'comprehensive-settings':
+            return 'Full-featured configuration with all available options';
+        case 'security-focused-settings':
+            return 'Security-enhanced configuration with additional protections';
+        default:
+            return `Configuration template: ${basename}`;
+    }
+}
+
+/**
+ * GREEN PHASE: Config Command CLI Handler
+ * Implements claude-commands config feature requirements
+ */
+class ConfigManager {
+    constructor() {
+        this.templatesDir = path.join(__dirname, '..', 'templates');
+        this.claudeDir = path.join(os.homedir(), '.claude');
+        this.settingsPath = path.join(this.claudeDir, 'settings.json');
+    }
+
+    // REQ-CONFIG-001: List Templates
+    listTemplates() {
+        console.log('📋 Available Configuration Templates:\n');
+        
+        try {
+            if (!fs.existsSync(this.templatesDir)) {
+                console.log('❌ Templates directory not found');
+                return;
+            }
+
+            const templates = getAvailableTemplates(this.templatesDir);
+
+            if (templates.length === 0) {
+                console.log('No configuration templates found');
+                return;
+            }
+
+            templates.forEach(template => {
+                console.log(`  📄 ${template.name}`);
+                console.log(`     ${template.description}`);
+            });
+
+            console.log(`\n💡 Usage: claude-commands config --template <name>`);
+        } catch (error) {
+            console.error('❌ Error listing templates:', error.message);
+        }
+    }
+
+    // REQ-CONFIG-002: Apply Template
+    applyTemplate(templateName) {
+        try {
+            // Resolve template name to full filename
+            const resolvedTemplate = this.resolveTemplateName(templateName);
+            if (!resolvedTemplate) {
+                this.handleTemplateNotFound(templateName);
+                return false;
+            }
+
+            const templatePath = path.join(this.templatesDir, resolvedTemplate);
+            if (!fs.existsSync(templatePath)) {
+                this.handleTemplateNotFound(templateName);
+                return false;
+            }
+
+            // Ensure Claude directory exists
+            this.ensureClaudeDirectory();
+
+            // Backup existing settings if present
+            this.backupExistingSettings();
+
+            // Apply template using existing function
+            const success = applyConfigurationTemplate(templatePath, this.settingsPath);
+            
+            if (success) {
+                console.log(`✅ Successfully applied template '${templateName}' (${resolvedTemplate})`);
+                console.log(`📝 Configuration saved to: ${this.settingsPath}`);
+                return true;
+            } else {
+                console.error(`❌ Failed to apply template '${templateName}'`);
+                return false;
+            }
+        } catch (error) {
+            console.error('❌ Error applying template:', error.message);
+            return false;
+        }
+    }
+
+    // Helper method to resolve template names (supports short names)
+    resolveTemplateName(templateName) {
+        // Return as-is if it already has .json extension
+        if (templateName.endsWith('.json')) {
+            return templateName;
+        }
+
+        // Map short names to full filenames
+        const templateMap = {
+            'basic': 'basic-settings.json',
+            'comprehensive': 'comprehensive-settings.json',
+            'security-focused': 'security-focused-settings.json',
+            'security': 'security-focused-settings.json'
+        };
+
+        // Check if it's a known short name
+        if (templateMap[templateName]) {
+            return templateMap[templateName];
+        }
+
+        // Try adding .json extension
+        const withExtension = `${templateName}.json`;
+        if (fs.existsSync(path.join(this.templatesDir, withExtension))) {
+            return withExtension;
+        }
+
+        // Try adding -settings.json extension
+        const withSettingsExtension = `${templateName}-settings.json`;
+        if (fs.existsSync(path.join(this.templatesDir, withSettingsExtension))) {
+            return withSettingsExtension;
+        }
+
+        return null;
+    }
+
+    // Helper method for template not found error
+    handleTemplateNotFound(templateName) {
+        console.error(`❌ Template '${templateName}' not found.`);
+        this.listTemplates();
+    }
+
+    // Helper method to ensure Claude directory exists
+    ensureClaudeDirectory() {
+        if (!fs.existsSync(this.claudeDir)) {
+            fs.mkdirSync(this.claudeDir, { recursive: true });
+            console.log(`📁 Created directory: ${this.claudeDir}`);
+        }
+    }
+
+    // Helper method to backup existing settings
+    backupExistingSettings() {
+        if (fs.existsSync(this.settingsPath)) {
+            const backupPath = this.createBackup();
+            console.log(`💾 Backed up existing settings to: ${backupPath}`);
+        }
+    }
+
+    // REQ-CONFIG-002: Backup functionality
+    createBackup() {
+        const timestamp = new Date().toISOString()
+            .replace(/[:.]/g, '-')
+            .replace('T', '-')
+            .split('.')[0]; // YYYY-MM-DD-HHMMSS format
+        
+        const backupPath = `${this.settingsPath}.backup.${timestamp}`;
+        fs.copyFileSync(this.settingsPath, backupPath);
+        return backupPath;
+    }
+
+    // REQ-CONFIG-003: Show Help
+    showHelp() {
+        console.log('🔧 Claude Commands Config Tool\n');
+        console.log('Usage:');
+        console.log('  claude-commands config [options]\n');
+        console.log('Options:');
+        console.log('  -l, --list                List available configuration templates');
+        console.log('  -t, --template <name>     Apply configuration template');
+        console.log('  -h, --help                Show this help message\n');
+        console.log('Examples:');
+        console.log('  claude-commands config --list                    # Show available templates');
+        console.log('  claude-commands config --template comprehensive  # Apply comprehensive template');
+        console.log('  claude-commands config --template basic          # Apply basic template');
+        console.log('  claude-commands config --help                    # Show this help\n');
+        console.log('Description:');
+        console.log('  Manage Claude Code configuration templates. Templates are applied');
+        console.log('  to ~/.claude/settings.json with automatic backup of existing settings.');
+    }
+
+    // Main command handler
+    handleCommand(options) {
+        // REQ-CONFIG-003: Show help when no options or explicit help
+        if (!options.list && !options.template) {
+            this.showHelp();
+            return;
+        }
+
+        // REQ-CONFIG-001: List templates
+        if (options.list) {
+            this.listTemplates();
+            return;
+        }
+
+        // REQ-CONFIG-002: Apply template
+        if (options.template) {
+            const success = this.applyTemplate(options.template);
+            if (!success) {
+                process.exit(1);
+            }
+            return;
+        }
+    }
+}
+
+// Create config manager instance
+const configManager = new ConfigManager();
+
 module.exports = {
     getConfigPath: () => {
         return path.join(os.homedir(), '.claude', 'commands');
@@ -172,11 +392,16 @@ module.exports = {
         colorOutput: true
     },
 
-    // REQ-009 Implementation
+    // REQ-009 Implementation (existing)
     applyConfigurationTemplate,
     getAvailableTemplates,
     
     // Utility functions (exposed for testing)
     parseJSONC,
-    deepMerge
+    deepMerge,
+    getTemplateDescription,
+
+    // CLI command handler (new)
+    handleCommand: (options) => configManager.handleCommand(options),
+    ConfigManager
 };