claude-git-hooks 2.8.0 → 2.10.0

package/lib/commands/help.js

@@ -0,0 +1,147 @@
+/**
+ * File: help.js
+ * Purpose: Help and version display commands
+ */
+
+import { getPackageJson } from './helpers.js';
+
+/**
+ * Show version command
+ * Why: Reusable function to display current version from package.json
+ */
+export function runShowVersion() {
+    const pkg = getPackageJson();
+    console.log(`${pkg.name} v${pkg.version}`);
+}
+
+/**
+ * Show help command
+ */
+export function runShowHelp() {
+    console.log(`
+Claude Git Hooks - Code analysis and automatic messages with Claude CLI
+
+Usage: claude-hooks <command> [options]
+
+Commands:
+  install [options]    Install hooks in the current repository
+    --force           Reinstall even if they already exist
+    --skip-auth       Skip Claude authentication verification
+  update               Update to the latest available version
+  uninstall            Uninstall hooks from the repository
+  enable [hook]        Enable hooks (all or one specific)
+  disable [hook]       Disable hooks (all or one specific)
+  status               Show the status of hooks
+  analyze-diff [base]  Analyze differences between branches and generate PR info
+  create-pr [base]     Create pull request with auto-generated metadata and reviewers
+  setup-github         Setup GitHub login (required for create-pr)
+  presets              List all available presets
+  --set-preset <name>  Set the active preset
+  preset current       Show the current active preset
+  telemetry [action]   Telemetry management (show or clear)
+  --debug <value>      Set debug mode (true, false, or status)
+  --version, -v        Show the current version
+  help                 Show this help
+
+Available hooks:
+  pre-commit           Code analysis before commit
+  prepare-commit-msg   Automatic message generation
+
+Examples:
+  claude-hooks install              # Install all hooks
+  claude-hooks install --skip-auth  # Install without verifying authentication
+  claude-hooks update               # Update to the latest version
+  claude-hooks disable pre-commit   # Disable only pre-commit
+  claude-hooks enable               # Enable all hooks
+  claude-hooks status               # View current status
+  claude-hooks analyze-diff main    # Analyze differences with main
+  claude-hooks setup-github         # Configure GitHub token for PR creation
+  claude-hooks create-pr develop    # Create PR targeting develop branch
+  claude-hooks presets              # List available presets
+  claude-hooks --set-preset backend # Set backend preset
+  claude-hooks preset current       # Show current preset
+  claude-hooks telemetry show       # Show telemetry statistics
+  claude-hooks telemetry clear      # Clear telemetry data
+  claude-hooks --debug true         # Enable debug mode
+  claude-hooks --debug status       # Check debug status
+
+Commit use cases:
+  git commit -m "message"           # Manual message + blocking analysis
+  git commit -m "auto"              # Automatic message + blocking analysis
+  git commit --no-verify -m "auto"  # Automatic message without analysis
+  git commit --no-verify -m "msg"   # Manual message without analysis
+
+Analyze-diff use case:
+  claude-hooks analyze-diff main    # Analyze changes vs main and generate:
+    → PR Title: "feat: add user authentication module"
+    → PR Description: "## Summary\n- Added JWT authentication..."
+    → Suggested branch: "feature/user-authentication"
+
+Create-pr use case (v2.5.0+):
+  claude-hooks create-pr develop    # Create PR targeting develop:
+    → Validates GitHub token
+    → Extracts task-id from branch (IX-123, #456, LIN-123)
+    → Analyzes diff and generates PR metadata with Claude
+    → Creates PR directly via GitHub API (Octokit)
+    → Adds labels based on preset
+    → Returns PR URL
+
+  Token configuration:
+    → .claude/settings.local.json (recommended, gitignored)
+    → GITHUB_TOKEN environment variable
+    → Claude Desktop config (auto-detected)
+
+Presets (v2.3.0+):
+  Built-in tech-stack specific configurations:
+  - backend: Spring Boot + SQL Server (.java, .xml, .yml)
+  - frontend: React + Material-UI (.js, .jsx, .ts, .tsx, .css)
+  - fullstack: Backend + Frontend with API consistency checks
+  - database: SQL Server migrations and procedures (.sql)
+  - ai: Node.js + Claude CLI integration (.js, .json, .md)
+  - default: General-purpose mixed languages
+
+Configuration (v2.2.0+):
+  Create .claude/config.json in your project to customize:
+  - Preset selection
+  - Analysis settings (maxFileSize, maxFiles, timeout)
+  - Commit message generation (autoKeyword, timeout)
+  - Parallel execution (enabled, model, batchSize)
+  - Template paths and output files
+  - Debug mode
+
+  Example: .claude/config.json
+  {
+    "preset": "backend",
+    "analysis": { "maxFiles": 30, "timeout": 180000 },
+    "subagents": {
+      "enabled": true,      // Enable parallel execution
+      "model": "haiku",     // haiku (fast) | sonnet | opus
+      "batchSize": 2        // Files per batch (1=fastest)
+    },
+    "system": { "debug": true }
+  }
+
+Parallel Analysis (v2.2.0+):
+  When analyzing 3+ files, parallel execution runs multiple Claude CLI
+  processes simultaneously for faster analysis:
+  - batchSize: 1 → Maximum speed (1 file per process)
+  - batchSize: 2 → Balanced (2 files per process)
+  - batchSize: 4+ → Fewer API calls but slower
+  - Speed improvement: up to 4x faster with batchSize: 1
+
+Debug Mode:
+  Enable detailed logging for troubleshooting:
+  - CLI: claude-hooks --debug true
+  - Config: "system": { "debug": true } in .claude/config.json
+  - Check status: claude-hooks --debug status
+
+Customization:
+  Override prompts by copying to .claude/:
+    cp templates/COMMIT_MESSAGE.md .claude/
+    cp templates/ANALYZE_DIFF.md .claude/
+    cp templates/CLAUDE_PRE_COMMIT.md .claude/
+    # Edit as needed - system uses .claude/ version if exists
+
+More information: https://github.com/pablorovito/claude-git-hooks
+`);
+}

package/lib/commands/helpers.js

@@ -0,0 +1,389 @@
+/**
+ * File: helpers.js
+ * Purpose: Shared utilities for CLI commands
+ *
+ * Exports:
+ * - Terminal colors and output functions
+ * - Git repository checks
+ * - Platform detection
+ * - Package.json utilities
+ * - Config management
+ * - Entertainment (spinner with jokes)
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import https from 'https';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+// Why: ES6 modules don't have __dirname, need to recreate it
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Colors for terminal output
+export const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m'
+};
+
+export function log(message, color = 'reset') {
+    console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+export function error(message) {
+    console.error(`${colors.red}❌ ${message}${colors.reset}`);
+    process.exit(1);
+}
+
+export function success(message) {
+    log(`✅ ${message}`, 'green');
+}
+
+export function info(message) {
+    log(`ℹ️  ${message}`, 'blue');
+}
+
+export function warning(message) {
+    log(`⚠️  ${message}`, 'yellow');
+}
+
+/**
+ * Check if we are in a git repository (including worktrees created in PowerShell)
+ * @returns {boolean}
+ */
+export function checkGitRepo() {
+    try {
+        execSync('git rev-parse --git-dir', { stdio: 'ignore' });
+        return true;
+    } catch (e) {
+        // Try to detect worktree created in PowerShell
+        try {
+            if (fs.existsSync('.git')) {
+                const gitContent = fs.readFileSync('.git', 'utf8').trim();
+                // Check if it's a worktree pointer (gitdir: ...)
+                if (gitContent.startsWith('gitdir:')) {
+                    let gitdir = gitContent.substring(8).trim();
+                    // Convert Windows path to WSL if needed (C:\ -> /mnt/c/)
+                    if (/^[A-Za-z]:/.test(gitdir)) {
+                        gitdir = gitdir.replace(/^([A-Za-z]):/, (_, drive) => `/mnt/${drive.toLowerCase()}`);
+                        gitdir = gitdir.replace(/\\/g, '/');
+                    }
+                    // Verify the gitdir exists
+                    if (fs.existsSync(gitdir)) {
+                        return true;
+                    }
+                }
+            }
+        } catch (worktreeError) {
+            // Ignore worktree detection errors
+        }
+        return false;
+    }
+}
+
+/**
+ * Get the templates path relative to package root
+ * @returns {string}
+ */
+export function getTemplatesPath() {
+    return path.join(__dirname, '..', '..', 'templates');
+}
+
+/**
+ * Detect if running on Windows
+ * Why: Need to use 'wsl claude' instead of 'claude' on Windows
+ * @returns {boolean}
+ */
+export function isWindows() {
+    return os.platform() === 'win32' || process.env.OS === 'Windows_NT';
+}
+
+/**
+ * Get Claude command based on platform
+ * Why: On Windows, try native Claude first, then WSL as fallback
+ * @returns {string}
+ */
+export function getClaudeCommand() {
+    if (isWindows()) {
+        // Try native Windows Claude first
+        try {
+            execSync('claude --version', { stdio: 'ignore', timeout: 3000 });
+            return 'claude';
+        } catch (e) {
+            // Fallback to WSL
+            return 'wsl claude';
+        }
+    }
+    return 'claude';
+}
+
+/**
+ * Helper to read package.json
+ * Why: ES6 modules can't use require() for JSON files
+ * @returns {Object}
+ */
+export function getPackageJson() {
+    const packagePath = path.join(__dirname, '..', '..', 'package.json');
+    return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+}
+
+/**
+ * Cross-platform version comparison (semver)
+ * Why: Pure JavaScript, no bash dependency
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} 0 if equal, 1 if v1 > v2, -1 if v1 < v2
+ */
+export function compareVersions(v1, v2) {
+    if (v1 === v2) return 0;
+
+    const v1Parts = v1.split('.').map(Number);
+    const v2Parts = v2.split('.').map(Number);
+
+    for (let i = 0; i < Math.max(v1Parts.length, v2Parts.length); i++) {
+        const v1Part = v1Parts[i] || 0;
+        const v2Part = v2Parts[i] || 0;
+
+        if (v1Part > v2Part) return 1;
+        if (v1Part < v2Part) return -1;
+    }
+
+    return 0;
+}
+
+/**
+ * Updates a configuration value in .claude/config.json
+ * Why: Centralized config update logic for all CLI commands
+ *
+ * @param {string} propertyPath - Dot notation path (e.g., 'preset', 'system.debug')
+ * @param {any} value - Value to set
+ * @param {Object} options - Optional settings
+ * @param {Function} options.validator - Custom validation function, receives value, throws on invalid
+ * @param {Function} options.successMessage - Function that receives value and returns success message
+ */
+export async function updateConfig(propertyPath, value, options = {}) {
+    const { validator, successMessage } = options;
+
+    try {
+        // Validate value if validator provided
+        if (validator) {
+            await validator(value);
+        }
+
+        // Get repo root
+        const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+        const configDir = path.join(repoRoot, '.claude');
+        const configPath = path.join(configDir, 'config.json');
+
+        // Ensure .claude directory exists
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true });
+        }
+
+        // Load existing config or create new
+        let config = {};
+        if (fs.existsSync(configPath)) {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        }
+
+        // Set value at propertyPath (support dot notation like 'system.debug')
+        const pathParts = propertyPath.split('.');
+        let current = config;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            const part = pathParts[i];
+            if (!current[part] || typeof current[part] !== 'object') {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+        current[pathParts[pathParts.length - 1]] = value;
+
+        // Save config
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+        // Show success message
+        const message = successMessage ? await successMessage(value) : 'Configuration updated';
+        success(message);
+        info(`Configuration saved to ${configPath}`);
+    } catch (err) {
+        error(`Failed to update configuration: ${err.message}`);
+        process.exit(1);
+    }
+}
+
+/**
+ * Function to get the latest version from NPM
+ * @param {string} packageName
+ * @returns {Promise<string>}
+ */
+export function getLatestVersion(packageName) {
+    return new Promise((resolve, reject) => {
+        // Use the main NPM API, not /latest
+        https.get(`https://registry.npmjs.org/${packageName}`, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                try {
+                    const json = JSON.parse(data);
+                    // Get the version from the 'latest' tag
+                    if (json['dist-tags'] && json['dist-tags'].latest) {
+                        resolve(json['dist-tags'].latest);
+                    } else {
+                        reject(new Error('Could not get the version'));
+                    }
+                } catch (e) {
+                    // If it fails, try with npm view
+                    try {
+                        const version = execSync(`npm view ${packageName} version`, { encoding: 'utf8' }).trim();
+                        resolve(version);
+                    } catch (npmError) {
+                        reject(e);
+                    }
+                }
+            });
+        }).on('error', reject);
+    });
+}
+
+/**
+ * Entertainment system - spinner with jokes for long operations
+ */
+export class Entertainment {
+    static jokes = [
+        "Why do programmers prefer dark mode? Because light attracts bugs!",
+        "A QA engineer walks into a bar. Orders 1 beer. Orders 0 beers. Orders -1 beers.",
+        "What's a pirate's favorite programming language? R!",
+        "There are 10 types of people: those who understand binary and those who don't.",
+        "Why do programmers confuse Halloween with Christmas? Because Oct 31 = Dec 25",
+        "What does one bit say to another? See you on the bus!",
+        "Why don't Java and C++ get along? Because they have different views on pointers.",
+        "My code doesn't have bugs, just undocumented features."
+    ];
+
+    static async getJoke() {
+        return new Promise((resolve) => {
+            // Try to get joke from API
+            const req = https.get('https://icanhazdadjoke.com/', {
+                headers: { 'Accept': 'text/plain' },
+                timeout: 3000
+            }, (res) => {
+                let data = '';
+                res.on('data', chunk => data += chunk);
+                res.on('end', () => resolve(data.trim()));
+            });
+
+            req.on('error', () => {
+                // If it fails, use local joke
+                const randomJoke = this.jokes[Math.floor(Math.random() * this.jokes.length)];
+                resolve(randomJoke);
+            });
+
+            req.on('timeout', () => {
+                req.abort();
+                const randomJoke = this.jokes[Math.floor(Math.random() * this.jokes.length)];
+                resolve(randomJoke);
+            });
+        });
+    }
+
+    static async showSpinner(promise, message = 'Processing') {
+        const spinners = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        let spinnerIndex = 0;
+        let jokeCountdown = 10;
+        let currentJoke = this.jokes[Math.floor(Math.random() * this.jokes.length)];
+        let isFinished = false;
+
+        // Get first joke from API without blocking
+        this.getJoke().then(joke => {
+            if (!isFinished) currentJoke = joke;
+        }).catch(() => { }); // If it fails, keep the local one
+
+        // Hide cursor
+        process.stdout.write('\x1B[?25l');
+
+        // Reserve space for the 3 lines
+        process.stdout.write('\n\n\n');
+
+        const interval = setInterval(() => {
+            if (isFinished) {
+                clearInterval(interval);
+                return;
+            }
+
+            spinnerIndex++;
+
+            // Update countdown every second (10 iterations of 100ms)
+            if (spinnerIndex % 10 === 0) {
+                jokeCountdown--;
+
+                // Refresh joke every 10 seconds
+                if (jokeCountdown <= 0) {
+                    this.getJoke().then(joke => {
+                        if (!isFinished) currentJoke = joke;
+                    }).catch(() => {
+                        if (!isFinished) {
+                            currentJoke = this.jokes[Math.floor(Math.random() * this.jokes.length)];
+                        }
+                    });
+                    jokeCountdown = 10;
+                }
+            }
+
+            // Always go back exactly 3 lines up
+            process.stdout.write('\x1B[3A');
+
+            // Render the 3 lines from the beginning
+            const spinner = spinners[spinnerIndex % spinners.length];
+
+            // Line 1: Spinner
+            process.stdout.write('\r\x1B[2K' + `${colors.yellow}${spinner} ${message}${colors.reset}\n`);
+
+            // Line 2: Joke
+            process.stdout.write('\r\x1B[2K' + `${colors.green}🎭 ${currentJoke}${colors.reset}\n`);
+
+            // Line 3: Countdown
+            process.stdout.write('\r\x1B[2K' + `${colors.yellow}⏱️  Next joke in: ${jokeCountdown}s${colors.reset}\n`);
+        }, 100);
+
+        try {
+            const result = await promise;
+            isFinished = true;
+            clearInterval(interval);
+
+            // Clean exactly 3 lines completely
+            process.stdout.write('\x1B[3A'); // Go up 3 lines
+            process.stdout.write('\r\x1B[2K'); // Clean line 1
+            process.stdout.write('\n\r\x1B[2K'); // Go down and clean line 2
+            process.stdout.write('\n\r\x1B[2K'); // Go down and clean line 3
+            process.stdout.write('\x1B[2A'); // Go up 2 lines to end up on the first
+            process.stdout.write('\r'); // Go to beginning of line
+
+            // Show cursor
+            process.stdout.write('\x1B[?25h');
+
+            return result;
+        } catch (error) {
+            isFinished = true;
+            clearInterval(interval);
+
+            // Clean exactly 3 lines completely
+            process.stdout.write('\x1B[3A'); // Go up 3 lines
+            process.stdout.write('\r\x1B[2K'); // Clean line 1
+            process.stdout.write('\n\r\x1B[2K'); // Go down and clean line 2
+            process.stdout.write('\n\r\x1B[2K'); // Go down and clean line 3
+            process.stdout.write('\x1B[2A'); // Go up 2 lines to end up on the first
+            process.stdout.write('\r'); // Go to beginning of line
+
+            // Show cursor
+            process.stdout.write('\x1B[?25h');
+
+            throw error;
+        }
+    }
+}

package/lib/commands/hooks.js

@@ -0,0 +1,150 @@
+/**
+ * File: hooks.js
+ * Purpose: Hook management commands (enable, disable, status, uninstall)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+    error,
+    success,
+    info,
+    warning,
+    checkGitRepo
+} from './helpers.js';
+
+/**
+ * Enable command
+ * @param {string} hookName - Optional specific hook to enable
+ */
+export function runEnable(hookName) {
+    if (!checkGitRepo()) {
+        error('You are not in a Git repository.');
+    }
+
+    const hooks = hookName ? [hookName] : ['pre-commit', 'prepare-commit-msg'];
+
+    hooks.forEach(hook => {
+        const disabledPath = `.git/hooks/${hook}.disabled`;
+        const enabledPath = `.git/hooks/${hook}`;
+
+        if (fs.existsSync(disabledPath)) {
+            fs.renameSync(disabledPath, enabledPath);
+            success(`${hook} enabled`);
+        } else if (fs.existsSync(enabledPath)) {
+            info(`${hook} is already enabled`);
+        } else {
+            warning(`${hook} not found`);
+        }
+    });
+}
+
+/**
+ * Disable command
+ * @param {string} hookName - Optional specific hook to disable
+ */
+export function runDisable(hookName) {
+    if (!checkGitRepo()) {
+        error('You are not in a Git repository.');
+    }
+
+    const hooks = hookName ? [hookName] : ['pre-commit', 'prepare-commit-msg'];
+
+    hooks.forEach(hook => {
+        const enabledPath = `.git/hooks/${hook}`;
+        const disabledPath = `.git/hooks/${hook}.disabled`;
+
+        if (fs.existsSync(enabledPath)) {
+            fs.renameSync(enabledPath, disabledPath);
+            success(`${hook} disabled`);
+        } else if (fs.existsSync(disabledPath)) {
+            info(`${hook} is already disabled`);
+        } else {
+            warning(`${hook} not found`);
+        }
+    });
+}
+
+/**
+ * Status command
+ */
+export function runStatus() {
+    if (!checkGitRepo()) {
+        error('You are not in a Git repository.');
+    }
+
+    info('Claude Git Hooks status:\n');
+
+    const hooks = ['pre-commit', 'prepare-commit-msg'];
+    hooks.forEach(hook => {
+        const enabledPath = `.git/hooks/${hook}`;
+        const disabledPath = `.git/hooks/${hook}.disabled`;
+
+        if (fs.existsSync(enabledPath)) {
+            success(`${hook}: enabled`);
+        } else if (fs.existsSync(disabledPath)) {
+            warning(`${hook}: disabled`);
+        } else {
+            error(`${hook}: not installed`);
+        }
+    });
+
+    // Check guidelines files
+    console.log('\nGuidelines files:');
+    const guidelines = ['CLAUDE_PRE_COMMIT.md'];
+    guidelines.forEach(guideline => {
+        const promptsPath = path.join('.claude', 'prompts', guideline);
+        const legacyPath = path.join('.claude', guideline);
+        if (fs.existsSync(promptsPath)) {
+            success(`${guideline}: present in .claude/prompts/`);
+        } else if (fs.existsSync(legacyPath)) {
+            warning(`${guideline}: present in .claude/ (should be in .claude/prompts/)`);
+        } else if (fs.existsSync(guideline)) {
+            warning(`${guideline}: present in root (should be in .claude/prompts/)`);
+        } else {
+            warning(`${guideline}: missing`);
+        }
+    });
+
+    // Verify entries in .gitignore
+    console.log('\n.gitignore:');
+    const gitignorePath = '.gitignore';
+    if (fs.existsSync(gitignorePath)) {
+        const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+        const claudeIgnore = '.claude/';
+
+        const regex = new RegExp(`^${claudeIgnore.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm');
+        if (regex.test(gitignoreContent)) {
+            success(`${claudeIgnore}: included (protects all Claude files)`);
+        } else {
+            warning(`${claudeIgnore}: missing`);
+            info('\nRun "claude-hooks install" to update .gitignore');
+        }
+    } else {
+        warning('.gitignore doesn´t exist');
+    }
+}
+
+/**
+ * Uninstall command
+ */
+export function runUninstall() {
+    if (!checkGitRepo()) {
+        error('You are not in a Git repository.');
+    }
+
+    info('Uninstalling Claude Git Hooks...');
+
+    const hooksPath = '.git/hooks';
+    const hooks = ['pre-commit', 'prepare-commit-msg'];
+
+    hooks.forEach(hook => {
+        const hookPath = path.join(hooksPath, hook);
+        if (fs.existsSync(hookPath)) {
+            fs.unlinkSync(hookPath);
+            success(`${hook} removed`);
+        }
+    });
+
+    success('Claude Git Hooks uninstalled');
+}