claude-git-hooks 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -5,28 +5,80 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.12.0] - 2026-02-03
+
+### ✨ Added
+
+- **Automatic version management with `bump-version` command**
+    - Detects project type (Node.js, Maven, or monorepo with both)
+    - Increments version following semantic versioning (major/minor/patch)
+    - Supports version suffixes (SNAPSHOT, RC, custom)
+    - Updates package.json and/or pom.xml automatically
+    - Generates CHANGELOG entries using Claude AI analysis of commits
+    - Creates annotated Git tags with `v` prefix (v2.7.0, v2.7.0-SNAPSHOT)
+    - Automatically pushes tags to remote
+    - CLI options: `--suffix`, `--update-changelog`, `--dry-run`, `--no-tag`, `--no-push`
+
+- **CHANGELOG generation with Claude integration**
+    - Standalone `generate-changelog` command for independent CHANGELOG generation without version bumping
+    - Support for manual version specification in CHANGELOG generation via command argument
+    - Base branch selection for CHANGELOG comparison via `--base-branch` flag
+    - Release marking option via `--release` flag to control [Unreleased] header behavior
+    - Analyzes commits since last final version tag
+    - Categorizes changes by Conventional Commits types
+    - Generates human-readable entries in Keep a Changelog format
+    - Sections: Added, Changed, Fixed, Security, Deprecated, Removed
+    - Places entries in [Unreleased] for suffixed versions, [X.Y.Z] for final versions
+
+- **Version alignment validation in `create-pr`** (#44)
+    - Checks consistency across package.json, pom.xml, CHANGELOG.md, and git tags
+    - Compares local version vs remote version
+    - Shows helpful prompts with fix commands if misalignment detected
+    - Allows user to continue or abort PR creation based on validation results
+
+- **Unpushed tags detection in `create-pr`** (#44)
+    - Detects local tags not pushed to remote
+    - Prompts user to push tags before creating PR
+    - Prevents version inconsistencies between local and remote
+
+- **New utility modules**:
+    - `lib/utils/version-manager.js` - Version detection, parsing, incrementing, validation
+    - `lib/utils/git-tag-manager.js` - Git tag operations (create, list, compare, push)
+    - `lib/utils/changelog-generator.js` - CHANGELOG generation with Claude
+    - `templates/GENERATE_CHANGELOG.md` - Claude prompt for changelog analysis
+
+### 🔧 Changed
+
+- Improved Windows compatibility by quoting git log format string in changelog-generator.js
+
+### 📚 Documentation
+
+- Updated help.js with bump-version command documentation and examples
+- Added version workflow examples (development → RC → release)
+- Updated CLAUDE.md with new utility modules and exports
+
 ## [2.11.0] - 2026-02-03
 
 ### ✨ Added
 
 - **Auto-push functionality in `create-pr` command** - Automatically detects and pushes unpublished branches before creating PR (#59, #34)
-  - Handles 3 scenarios: unpublished branch, unpushed commits, up-to-date branch
-  - Interactive confirmation prompt before pushing (configurable)
-  - Commit preview showing what will be pushed
-  - Diverged branch detection with helpful error message and resolution steps
-  - Never uses `git push --force` for security
+    - Handles 3 scenarios: unpublished branch, unpushed commits, up-to-date branch
+    - Interactive confirmation prompt before pushing (configurable)
+    - Commit preview showing what will be pushed
+    - Diverged branch detection with helpful error message and resolution steps
+    - Never uses `git push --force` for security
 
 - **New configuration options** under `github.pr`:
-  - `autoPush: true` - Enable/disable auto-push (enabled by default)
-  - `pushConfirm: true` - Prompt for confirmation before push
-  - `showCommits: true` - Show commit preview before push
-  - `verifyRemote: true` - Verify remote exists before push
+    - `autoPush: true` - Enable/disable auto-push (enabled by default)
+    - `pushConfirm: true` - Prompt for confirmation before push
+    - `showCommits: true` - Show commit preview before push
+    - `verifyRemote: true` - Verify remote exists before push
 
 - **New git-operations functions**:
-  - `getRemoteName()` - Get configured remote name (usually 'origin')
-  - `verifyRemoteExists()` - Check if remote is configured
-  - `getBranchPushStatus()` - Detect branch publish status and unpushed commits
-  - `pushBranch()` - Execute git push with upstream tracking
+    - `getRemoteName()` - Get configured remote name (usually 'origin')
+    - `verifyRemoteExists()` - Check if remote is configured
+    - `getBranchPushStatus()` - Detect branch publish status and unpushed commits
+    - `pushBranch()` - Execute git push with upstream tracking
 
 ### 🔧 Fixed
 
@@ -76,13 +128,13 @@ This release implements a **modular, decoupled, reusable** architecture for bett
 
 ### 🎯 Benefits
 
-| Aspect | Before | After |
-|--------|--------|-------|
-| `bin/claude-hooks` size | 2,277 lines | 111 lines |
-| Command modules | 1 (`setup-github.js`) | 13 files |
-| Testability | Hard (monolithic) | Easy (modular) |
-| Finding code | Search entire file | Match filename to command |
-| Adding commands | Edit large file | Create new module |
+| Aspect                  | Before                | After                     |
+| ----------------------- | --------------------- | ------------------------- |
+| `bin/claude-hooks` size | 2,277 lines           | 111 lines                 |
+| Command modules         | 1 (`setup-github.js`) | 13 files                  |
+| Testability             | Hard (monolithic)     | Easy (modular)            |
+| Finding code            | Search entire file    | Match filename to command |
+| Adding commands         | Edit large file       | Create new module         |
 
 ### 📚 Documentation
 
@@ -94,6 +146,7 @@ This release implements a **modular, decoupled, reusable** architecture for bett
 ### 🔧 Technical Details
 
 **New module structure:**
+
 ```
 lib/commands/
 ├── helpers.js        (389 lines) - Shared utilities
@@ -111,6 +164,7 @@ lib/commands/
 ```
 
 **Key patterns implemented:**
+
 - **Command Pattern**: Each CLI command is a self-contained module
 - **Thin Controller**: `bin/claude-hooks` only routes, doesn't implement
 - **Separation of Concerns**: UI helpers in `helpers.js`, business logic in specific modules

package/README.md

@@ -67,6 +67,65 @@ claude-hooks analyze-diff develop
 # Generates PR metadata without creating
 ```
 
+### Bump Version
+
+Automatic version management with CHANGELOG generation and Git tagging:
+
+```bash
+# Bump patch version (1.0.0 → 1.0.1)
+claude-hooks bump-version patch
+
+# Bump with suffix
+claude-hooks bump-version minor --suffix SNAPSHOT  # → 1.1.0-SNAPSHOT
+
+# Bump and generate CHANGELOG
+claude-hooks bump-version major --update-changelog
+
+# Preview without applying
+claude-hooks bump-version patch --dry-run
+```
+
+**What it does:**
+- Detects project type (Node.js, Maven, or monorepo with both)
+- Updates `package.json` and/or `pom.xml`
+- Generates CHANGELOG entry with Claude (analyzes commits)
+- Creates annotated Git tag with `v` prefix (e.g., `v2.7.0`)
+- Pushes tag to remote automatically
+
+**Version workflow:**
+```
+2.7.0 → 2.8.0-SNAPSHOT    # Start development
+2.8.0-SNAPSHOT → 2.8.0-RC # Release candidate
+2.8.0-RC → 2.8.0          # Final release
+```
+
+**Integration with create-pr:**
+- Validates version alignment (package.json, pom.xml, CHANGELOG, tags)
+- Detects and prompts to push unpushed tags
+- Warns if local version ≤ remote version
+
+### Generate CHANGELOG
+
+Standalone CHANGELOG generation (without version bump):
+
+```bash
+# Auto-detect version from package.json/pom.xml
+claude-hooks generate-changelog
+
+# Specific version with release marking
+claude-hooks generate-changelog 2.7.0 --release
+
+# Compare against different base branch
+claude-hooks generate-changelog --base-branch develop
+```
+
+**What it does:**
+- Analyzes commits since last tag using Claude
+- Categorizes by Conventional Commits types (feat, fix, refactor, etc.)
+- Generates Keep a Changelog format entries
+- Updates CHANGELOG.md automatically
+- Useful when `bump-version --update-changelog` fails
+
 ### Disable/Enable Hooks
 
 ```bash

package/bin/claude-hooks

@@ -22,6 +22,8 @@ import { runMigrateConfig } from '../lib/commands/migrate-config.js';
 import { runSetDebug } from '../lib/commands/debug.js';
 import { runShowTelemetry, runClearTelemetry } from '../lib/commands/telemetry-cmd.js';
 import { runShowHelp, runShowVersion } from '../lib/commands/help.js';
+import { runBumpVersion } from '../lib/commands/bump-version.js';
+import { runGenerateChangelog } from '../lib/commands/generate-changelog.js';
 
 /**
  * Main CLI router
@@ -75,6 +77,12 @@ async function main() {
         case 'migrate-config':
             await runMigrateConfig();
             break;
+        case 'bump-version':
+            await runBumpVersion(args.slice(1));
+            break;
+        case 'generate-changelog':
+            await runGenerateChangelog(args.slice(1));
+            break;
         case 'telemetry':
             // Handle subcommands: telemetry show, telemetry clear
             if (args[1] === 'show' || args[1] === undefined) {

package/lib/commands/bump-version.js

@@ -0,0 +1,452 @@
+/**
+ * File: bump-version.js
+ * Purpose: Bump version command with automatic CHANGELOG and Git tag
+ *
+ * Workflow:
+ * 1. Validate prerequisites (clean working directory, valid branch, remote)
+ * 2. Detect project type and current version
+ * 3. Calculate new version with optional suffix
+ * 4. Update version file(s)
+ * 5. [Optional] Generate and update CHANGELOG
+ * 6. Create annotated Git tag
+ * 7. Push tag to remote
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import {
+    detectProjectType,
+    getCurrentVersion,
+    incrementVersion,
+    updateVersion,
+    parseVersion
+} from '../utils/version-manager.js';
+import {
+    createTag,
+    pushTags,
+    tagExists,
+    formatTagName
+} from '../utils/git-tag-manager.js';
+import {
+    generateChangelogEntry,
+    updateChangelogFile
+} from '../utils/changelog-generator.js';
+import {
+    getRepoRoot,
+    getCurrentBranch,
+    verifyRemoteExists,
+    getRemoteName
+} from '../utils/git-operations.js';
+import { getConfig } from '../config.js';
+import { showInfo, showSuccess, showError, showWarning, promptConfirmation } from '../utils/interactive-ui.js';
+import logger from '../utils/logger.js';
+import {
+    colors,
+    error,
+    success,
+    info,
+    warning,
+    checkGitRepo
+} from './helpers.js';
+
+/**
+ * Validates prerequisites before version bump
+ * Why: Prevents version bump in invalid state
+ *
+ * @returns {Object} Validation result: { valid, errors }
+ */
+function validatePrerequisites() {
+    logger.debug('bump-version - validatePrerequisites', 'Validating prerequisites');
+
+    const errors = [];
+
+    try {
+        // Check if git repo
+        if (!checkGitRepo()) {
+            errors.push('Not a git repository');
+        }
+
+        // Check for clean working directory
+        try {
+            const status = execSync('git status --porcelain', { encoding: 'utf8' }).trim();
+            if (status) {
+                errors.push('Working directory has uncommitted changes');
+            }
+        } catch (err) {
+            errors.push('Failed to check git status');
+        }
+
+        // Check for valid branch (not detached HEAD)
+        const currentBranch = getCurrentBranch();
+        if (!currentBranch || currentBranch === 'unknown') {
+            errors.push('Not on a valid branch (detached HEAD?)');
+        }
+
+        // Check for remote
+        const remoteName = getRemoteName();
+        if (!verifyRemoteExists(remoteName)) {
+            errors.push(`Remote '${remoteName}' does not exist`);
+        }
+
+        const valid = errors.length === 0;
+
+        logger.debug('bump-version - validatePrerequisites', 'Validation complete', {
+            valid,
+            errorCount: errors.length
+        });
+
+        return { valid, errors };
+
+    } catch (err) {
+        logger.error('bump-version - validatePrerequisites', 'Validation failed', err);
+        return {
+            valid: false,
+            errors: ['Validation error: ' + err.message]
+        };
+    }
+}
+
+/**
+ * Parses command line arguments
+ * Why: Extracts bump type and options from CLI args
+ *
+ * @param {Array<string>} args - CLI arguments
+ * @returns {Object} Parsed args: { bumpType, suffix, updateChangelog, baseBranch, dryRun, noTag, noPush }
+ */
+function parseArguments(args) {
+    logger.debug('bump-version - parseArguments', 'Parsing arguments', { args });
+
+    const parsed = {
+        bumpType: null,
+        suffix: null,
+        updateChangelog: false,
+        baseBranch: 'main',
+        dryRun: false,
+        noTag: false,
+        noPush: false
+    };
+
+    // First argument should be bump type
+    if (args.length === 0) {
+        return parsed;
+    }
+
+    const firstArg = args[0].toLowerCase();
+    if (['major', 'minor', 'patch'].includes(firstArg)) {
+        parsed.bumpType = firstArg;
+    }
+
+    // Parse options
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+
+        if (arg === '--suffix' && i + 1 < args.length) {
+            parsed.suffix = args[i + 1];
+            i++; // Skip next arg
+        } else if (arg === '--update-changelog') {
+            parsed.updateChangelog = true;
+            // Check if next arg is a branch name (not starting with --)
+            if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+                parsed.baseBranch = args[i + 1];
+                i++; // Skip next arg
+            }
+        } else if (arg === '--dry-run') {
+            parsed.dryRun = true;
+        } else if (arg === '--no-tag') {
+            parsed.noTag = true;
+        } else if (arg === '--no-push') {
+            parsed.noPush = true;
+        }
+    }
+
+    logger.debug('bump-version - parseArguments', 'Arguments parsed', parsed);
+
+    return parsed;
+}
+
+/**
+ * Displays dry run preview
+ * Why: Shows what would change without applying
+ *
+ * @param {Object} info - Version info
+ */
+function showDryRunPreview(info) {
+    console.log('');
+    console.log(`${colors.yellow}═════════════════════════════════════════════════${colors.reset}`);
+    console.log(`${colors.yellow}           DRY RUN - No changes will be made      ${colors.reset}`);
+    console.log(`${colors.yellow}═════════════════════════════════════════════════${colors.reset}`);
+    console.log('');
+    console.log(`${colors.blue}Project Type:${colors.reset} ${info.projectType}`);
+    console.log(`${colors.blue}Current Version:${colors.reset} ${info.currentVersion}`);
+    console.log(`${colors.green}New Version:${colors.reset} ${info.newVersion}`);
+    console.log(`${colors.blue}Tag Name:${colors.reset} ${info.tagName}`);
+    console.log('');
+
+    if (info.files.length > 0) {
+        console.log(`${colors.blue}Files to update:${colors.reset}`);
+        info.files.forEach(file => console.log(`  - ${file}`));
+        console.log('');
+    }
+
+    if (info.updateChangelog) {
+        console.log(`${colors.blue}CHANGELOG:${colors.reset} Will be generated and updated`);
+        console.log('');
+    }
+
+    console.log(`${colors.yellow}Run without --dry-run to apply these changes${colors.reset}`);
+    console.log('');
+}
+
+/**
+ * Bump version command
+ * @param {Array<string>} args - Command arguments
+ */
+export async function runBumpVersion(args) {
+    logger.debug('bump-version', 'Starting bump-version command', { args });
+
+    // Parse arguments
+    const options = parseArguments(args);
+
+    if (!options.bumpType) {
+        error('Usage: claude-hooks bump-version <major|minor|patch> [options]');
+        console.log('');
+        console.log('Options:');
+        console.log('  --suffix <value>         Add version suffix (e.g., SNAPSHOT, RC)');
+        console.log('  --update-changelog [branch]  Generate CHANGELOG entry (default branch: main)');
+        console.log('  --dry-run                Preview changes without applying');
+        console.log('  --no-tag                 Skip Git tag creation');
+        console.log('  --no-push                Create tag but don\'t push to remote');
+        console.log('');
+        console.log('Examples:');
+        console.log('  claude-hooks bump-version minor --suffix SNAPSHOT');
+        console.log('  claude-hooks bump-version patch --update-changelog');
+        console.log('  claude-hooks bump-version major --dry-run');
+        return;
+    }
+
+    showInfo(`🔢 Bumping version (${options.bumpType})...`);
+    console.log('');
+
+    // Step 1: Validate prerequisites
+    logger.debug('bump-version', 'Step 1: Validating prerequisites');
+    const validation = validatePrerequisites();
+
+    if (!validation.valid) {
+        showError('Prerequisites validation failed:');
+        console.log('');
+        validation.errors.forEach(err => console.log(`  ❌ ${err}`));
+        console.log('');
+        console.log('Please fix these issues:');
+        console.log('  - Commit or stash uncommitted changes: git stash');
+        console.log('  - Checkout a branch: git checkout main');
+        console.log('  - Configure remote: git remote add origin <url>');
+        console.log('');
+        process.exit(1);
+    }
+
+    showSuccess('Prerequisites validated');
+
+    // Step 2: Detect project type and current version
+    logger.debug('bump-version', 'Step 2: Detecting project type and version');
+    const projectType = detectProjectType();
+
+    if (projectType === 'none') {
+        showError('No version files found');
+        console.log('');
+        console.log('This command requires either:');
+        console.log('  - package.json (Node.js project)');
+        console.log('  - pom.xml (Maven project)');
+        console.log('');
+        process.exit(1);
+    }
+
+    const versions = getCurrentVersion(projectType);
+    const currentVersion = versions.resolved;
+
+    if (!currentVersion) {
+        showError('Could not determine current version');
+        process.exit(1);
+    }
+
+    // Warn if monorepo has version mismatch
+    if (versions.mismatch) {
+        showWarning('Version mismatch detected in monorepo:');
+        console.log(`  package.json: ${versions.packageJson}`);
+        console.log(`  pom.xml: ${versions.pomXml}`);
+        console.log('');
+        console.log('Both files will be updated to the new version.');
+        console.log('');
+    }
+
+    showInfo(`Project: ${projectType}`);
+    showInfo(`Current version: ${currentVersion}`);
+
+    // Step 3: Calculate new version
+    logger.debug('bump-version', 'Step 3: Calculating new version');
+    const newVersion = incrementVersion(currentVersion, options.bumpType, options.suffix);
+    const tagName = formatTagName(newVersion);
+
+    showSuccess(`New version: ${newVersion}`);
+    console.log('');
+
+    // Prepare files list
+    const filesToUpdate = [];
+    if (projectType === 'node' || projectType === 'both') {
+        filesToUpdate.push('package.json');
+    }
+    if (projectType === 'maven' || projectType === 'both') {
+        filesToUpdate.push('pom.xml');
+    }
+
+    // Dry run preview
+    if (options.dryRun) {
+        showDryRunPreview({
+            projectType,
+            currentVersion,
+            newVersion,
+            tagName,
+            files: filesToUpdate,
+            updateChangelog: options.updateChangelog
+        });
+        return;
+    }
+
+    // Confirm with user
+    const shouldContinue = await promptConfirmation(
+        `Update version to ${newVersion}?`,
+        true
+    );
+
+    if (!shouldContinue) {
+        showInfo('Version bump cancelled');
+        process.exit(0);
+    }
+
+    console.log('');
+
+    try {
+        // Step 4: Update version files
+        logger.debug('bump-version', 'Step 4: Updating version files');
+        showInfo('Updating version files...');
+        updateVersion(projectType, newVersion);
+
+        filesToUpdate.forEach(file => {
+            showSuccess(`✓ Updated ${file}`);
+        });
+
+        console.log('');
+
+        // Step 5: Generate CHANGELOG (if requested)
+        if (options.updateChangelog) {
+            logger.debug('bump-version', 'Step 5: Generating CHANGELOG');
+            showInfo('Generating CHANGELOG entry...');
+
+            const config = await getConfig();
+            const isReleaseVersion = !options.suffix; // Final version if no suffix
+
+            const changelogResult = await generateChangelogEntry({
+                version: newVersion,
+                isReleaseVersion,
+                baseBranch: options.baseBranch,
+                config
+            });
+
+            if (changelogResult.content) {
+                const updated = updateChangelogFile(changelogResult.content);
+                if (updated) {
+                    showSuccess('✓ CHANGELOG.md updated');
+                } else {
+                    showWarning('⚠ Failed to update CHANGELOG.md');
+                }
+            } else {
+                showWarning('⚠ No commits found for CHANGELOG');
+            }
+
+            console.log('');
+        }
+
+        // Step 6: Create Git tag (if not disabled)
+        if (!options.noTag) {
+            logger.debug('bump-version', 'Step 6: Creating Git tag');
+            showInfo('Creating Git tag...');
+
+            // Check if tag already exists
+            const exists = await tagExists(tagName, 'local');
+            if (exists) {
+                showWarning(`Tag ${tagName} already exists locally`);
+                const shouldOverwrite = await promptConfirmation(
+                    'Overwrite existing tag?',
+                    false
+                );
+
+                if (!shouldOverwrite) {
+                    showInfo('Tag creation skipped');
+                    console.log('');
+                    console.log('Version files updated successfully, but tag was not created.');
+                    return;
+                }
+            }
+
+            const tagMessage = `Release version ${newVersion}`;
+            const tagResult = createTag(newVersion, tagMessage, { force: exists });
+
+            if (tagResult.success) {
+                showSuccess(`✓ Tag created: ${tagName}`);
+                console.log('');
+
+                // Step 7: Push tag (if not disabled)
+                if (!options.noPush) {
+                    logger.debug('bump-version', 'Step 7: Pushing tag to remote');
+                    showInfo('Pushing tag to remote...');
+
+                    const pushResult = pushTags(null, tagName);
+
+                    if (pushResult.success) {
+                        showSuccess(`✓ Tag pushed to remote`);
+                    } else {
+                        showError(`Failed to push tag: ${pushResult.error}`);
+                        console.log('');
+                        console.log('You can push the tag manually:');
+                        console.log(`  git push origin ${tagName}`);
+                    }
+                } else {
+                    showInfo('Tag push skipped (--no-push)');
+                    console.log('');
+                    console.log('To push the tag later:');
+                    console.log(`  git push origin ${tagName}`);
+                }
+            } else {
+                showError(`Failed to create tag: ${tagResult.error}`);
+            }
+        } else {
+            showInfo('Tag creation skipped (--no-tag)');
+        }
+
+        // Success summary
+        console.log('');
+        console.log(`${colors.green}════════════════════════════════════════════════${colors.reset}`);
+        console.log(`${colors.green}        Version Bump Complete ✅                ${colors.reset}`);
+        console.log(`${colors.green}════════════════════════════════════════════════${colors.reset}`);
+        console.log('');
+        console.log(`${colors.blue}Old version:${colors.reset} ${currentVersion}`);
+        console.log(`${colors.blue}New version:${colors.reset} ${newVersion}`);
+        console.log(`${colors.blue}Tag:${colors.reset} ${tagName}`);
+        console.log('');
+        console.log('Next steps:');
+        console.log('  1. Review the changes: git diff');
+        console.log('  2. Commit the version bump: git add . && git commit -m "chore: bump version to ' + newVersion + '"');
+        console.log('  3. Create PR: claude-hooks create-pr main');
+        console.log('');
+
+    } catch (err) {
+        logger.error('bump-version', 'Version bump failed', err);
+        showError(`Version bump failed: ${err.message}`);
+        console.log('');
+        console.log('The operation was interrupted. You may need to:');
+        console.log('  - Revert changes: git checkout .');
+        console.log('  - Delete tag if created: git tag -d ' + tagName);
+        console.log('');
+        process.exit(1);
+    }
+}