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

package/hooks/verify-before-edit.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Claude Code Hook: Verify Before Edit
+#
+# Description: Warns about potentially fabricated references in file edits
+# Purpose: Prevent use of fabricated URLs, account IDs, or asset paths by validating references
+# Trigger: PreToolUse
+# Blocking: No
+# Tools: Edit, Write, MultiEdit
+# Author: Claude Dev Toolkit
+# Version: 1.0.0
+# Category: security
+#
+# This hook checks for placeholder or fabricated identifiers to prevent
+# accidental use of invalid references in code and configuration files.
+
+##################################
+# Configuration
+##################################
+HOOK_NAME="verify-before-edit"
+LOG_FILE="$HOME/.claude/logs/verify-before-edit.log"
+
+mkdir -p "$(dirname "$LOG_FILE")"
+chmod 700 "$(dirname "$LOG_FILE")"
+touch "$LOG_FILE"
+chmod 600 "$LOG_FILE"
+
+##################################
+# Logging
+##################################
+log() {
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] [$HOOK_NAME] $*" >> "$LOG_FILE"
+}
+
+warn() {
+    echo "[WARN] $*" >&2
+    log "WARNING: $*"
+}
+
+##################################
+# Skip Checks
+##################################
+should_skip_file() {
+    local file="$1"
+    case "$file" in
+        *test*|*spec*|*example*|*fixture*|*mock*|*stub*)
+            return 0 ;;
+        *)
+            return 1 ;;
+    esac
+}
+
+##################################
+# Pattern Scanning
+##################################
+scan_for_placeholders() {
+    local content="$1"
+
+    local patterns=(
+        'your-api-key-here'
+        'REPLACE_ME'
+        '<INSERT>'
+        'your-.*-here'
+        'xxx-.*-xxx'
+        'TODO:.*http'
+        'placeholder'
+    )
+
+    for pattern in "${patterns[@]}"; do
+        if echo "$content" | grep -qiE "$pattern"; then
+            warn "Suspicious placeholder detected: $pattern"
+        fi
+    done
+}
+
+scan_for_fabricated_ids() {
+    local content="$1"
+
+    if echo "$content" | grep -qE '000000|123456|111111'; then
+        warn "Sequential/zero ID detected — check if valid"
+    fi
+
+    if echo "$content" | grep -qE 'G-[A-Z0-9]{10}|UA-[0-9]{9}' 2>/dev/null; then
+        warn "Analytics ID found — validate against project config"
+    fi
+}
+
+##################################
+# Main Hook Logic
+##################################
+main() {
+    local tool_name="${CLAUDE_TOOL:-unknown}"
+    local file_path="${CLAUDE_FILE:-}"
+    local content="${CLAUDE_CONTENT:-}"
+
+    log "Hook triggered for tool: $tool_name, file: $file_path"
+
+    case "$tool_name" in
+        "Edit"|"Write"|"MultiEdit") ;;
+        *)
+            log "Skipping non-edit tool: $tool_name"
+            exit 0 ;;
+    esac
+
+    if should_skip_file "$file_path"; then
+        log "Skipping check for test/example file: $file_path"
+        exit 0
+    fi
+
+    if [[ -z "$content" ]] && [[ -n "$file_path" ]] && [[ -f "$file_path" ]]; then
+        content=$(cat "$file_path" 2>/dev/null || echo "")
+    fi
+
+    if [[ -z "$content" ]]; then
+        log "No content to validate"
+        exit 0
+    fi
+
+    scan_for_placeholders "$content"
+    scan_for_fabricated_ids "$content"
+
+    log "Security validation complete for $file_path"
+    exit 0
+}
+
+##################################
+# Error Handling
+##################################
+trap 'log "Hook failed with error on line $LINENO"' ERR
+
+##################################
+# Execute
+##################################
+main "$@"

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;

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;