claude-git-hooks 2.18.1 → 2.20.0

package/lib/cli-metadata.js

@@ -0,0 +1,306 @@
+/**
+ * File: cli-metadata.js
+ * Purpose: Single source of truth for CLI commands, flags, and descriptions
+ *
+ * Three consumers read from this registry:
+ * 1. bin/claude-hooks — routing (replaces switch/case)
+ * 2. installCompletions() — generates shell completion scripts at install time
+ * 3. showStaticHelp() — can derive help text from metadata
+ *
+ * Adding a new command = adding one entry here.
+ * Completions auto-update for every user at next install.
+ */
+
+/**
+ * Available preset names for --set-preset completion
+ * @type {string[]}
+ */
+export const PRESET_NAMES = ['ai', 'backend', 'database', 'default', 'frontend', 'fullstack'];
+
+/**
+ * Hook names for enable/disable completion
+ * @type {string[]}
+ */
+export const HOOK_NAMES = ['pre-commit', 'prepare-commit-msg'];
+
+/**
+ * Bump types for bump-version completion
+ * @type {string[]}
+ */
+export const BUMP_TYPES = ['major', 'minor', 'patch'];
+
+/**
+ * @typedef {Object} CommandFlag
+ * @property {string} description - Flag description for completions
+ * @property {string[]} [values] - Completable values for the flag
+ * @property {boolean} [takesValue] - Whether the flag expects a value argument
+ */
+
+/**
+ * @typedef {Object} CommandEntry
+ * @property {string} name - Primary command name
+ * @property {string[]} [aliases] - Alternative names (e.g., --version, -v)
+ * @property {string} description - Short description for completions and help
+ * @property {function(): Promise<function>} handler - Dynamic import returning handler function
+ * @property {Object<string, CommandFlag>} [flags] - Supported flags
+ * @property {string[]} [subcommands] - Available subcommands
+ * @property {Object} [args] - Positional argument info
+ * @property {string} [args.name] - Argument name
+ * @property {string[]} [args.values] - Completable values
+ * @property {string} [args.completion] - Shell command for dynamic completion
+ */
+
+/**
+ * Command registry — all CLI commands defined declaratively
+ * @type {CommandEntry[]}
+ */
+export const commands = [
+    {
+        name: 'install',
+        description: 'Install hooks in current repository',
+        handler: async () => (await import('./commands/install.js')).runInstall,
+        flags: {
+            '--force': { description: 'Reinstall even if already exist' },
+            '--skip-auth': { description: 'Skip Claude authentication check' }
+        }
+    },
+    {
+        name: 'update',
+        description: 'Update to latest version',
+        handler: async () => (await import('./commands/update.js')).runUpdate
+    },
+    {
+        name: 'uninstall',
+        description: 'Remove hooks from repository',
+        handler: async () => (await import('./commands/hooks.js')).runUninstall
+    },
+    {
+        name: 'enable',
+        description: 'Enable hooks (all or specific)',
+        handler: async () => (await import('./commands/hooks.js')).runEnable,
+        args: {
+            name: 'hook',
+            values: HOOK_NAMES
+        }
+    },
+    {
+        name: 'disable',
+        description: 'Disable hooks (all or specific)',
+        handler: async () => (await import('./commands/hooks.js')).runDisable,
+        args: {
+            name: 'hook',
+            values: HOOK_NAMES
+        }
+    },
+    {
+        name: 'status',
+        description: 'Show hook status',
+        handler: async () => (await import('./commands/hooks.js')).runStatus
+    },
+    {
+        name: 'analyze',
+        description: 'Analyze code interactively before committing',
+        handler: async () => (await import('./commands/analyze.js')).runAnalyze,
+        flags: {
+            '--unstaged': { description: 'Analyze unstaged changes' },
+            '--all': { description: 'Analyze all tracked files' }
+        }
+    },
+    {
+        name: 'analyze-diff',
+        description: 'Analyze diff and generate PR metadata',
+        handler: async () => (await import('./commands/analyze-diff.js')).runAnalyzeDiff,
+        args: {
+            name: 'base-branch',
+            completion: "git branch --format='%(refname:short)'"
+        }
+    },
+    {
+        name: 'create-pr',
+        description: 'Create PR with auto-generated metadata',
+        handler: async () => (await import('./commands/create-pr.js')).runCreatePr,
+        args: {
+            name: 'base-branch',
+            completion: "git branch --format='%(refname:short)'"
+        }
+    },
+    {
+        name: 'setup-github',
+        description: 'Configure GitHub token for PR creation',
+        handler: async () => (await import('./commands/setup-github.js')).runSetupGitHub
+    },
+    {
+        name: 'presets',
+        description: 'List all available presets',
+        handler: async () => (await import('./commands/presets.js')).runShowPresets
+    },
+    {
+        name: '--set-preset',
+        description: 'Set the active preset',
+        handler: async () => (await import('./commands/presets.js')).runSetPreset,
+        args: {
+            name: 'preset',
+            values: PRESET_NAMES
+        }
+    },
+    {
+        name: 'preset',
+        description: 'Preset management',
+        handler: async () => null,
+        subcommands: ['current']
+    },
+    {
+        name: 'migrate-config',
+        description: 'Migrate legacy config to v2.8.0 format',
+        handler: async () => (await import('./commands/migrate-config.js')).runMigrateConfig
+    },
+    {
+        name: 'bump-version',
+        description: 'Bump version with CHANGELOG and Git tag',
+        handler: async () => (await import('./commands/bump-version.js')).runBumpVersion,
+        args: {
+            name: 'type',
+            values: BUMP_TYPES
+        },
+        flags: {
+            '--dry-run': { description: 'Preview changes without applying' },
+            '--interactive': { description: 'Force file selection menu' },
+            '--no-commit': { description: 'Skip automatic commit' },
+            '--no-tag': { description: 'Skip Git tag creation' },
+            '--push': { description: 'Push tag to remote' },
+            '--remove-suffix': { description: 'Remove version suffix' },
+            '--set-suffix': { description: 'Set/replace version suffix', takesValue: true },
+            '--suffix': { description: 'Add version suffix (e.g., SNAPSHOT)', takesValue: true },
+            '--update-changelog': { description: 'Generate CHANGELOG entry' }
+        }
+    },
+    {
+        name: 'generate-changelog',
+        description: 'Generate CHANGELOG entry independently',
+        handler: async () =>
+            (await import('./commands/generate-changelog.js')).runGenerateChangelog,
+        flags: {
+            '--base-branch': { description: 'Compare against branch', takesValue: true },
+            '--release': { description: 'Mark as released' }
+        }
+    },
+    {
+        name: 'batch-info',
+        description: 'Show intelligent diff-analysis orchestration configuration and speed telemetry',
+        handler: async () => (await import('./commands/diff-batch-info.js')).runDiffBatchInfo
+    },
+    {
+        name: 'telemetry',
+        description: 'View or clear telemetry data',
+        handler: async () => null,
+        subcommands: ['show', 'clear']
+    },
+    {
+        name: '--debug',
+        description: 'Toggle debug mode',
+        handler: async () => (await import('./commands/debug.js')).runSetDebug,
+        args: {
+            name: 'value',
+            values: ['true', 'false', 'status']
+        }
+    },
+    {
+        name: 'version',
+        aliases: ['--version', '-v'],
+        description: 'Show current version',
+        handler: async () => (await import('./commands/help.js')).runShowVersion
+    },
+    {
+        name: 'help',
+        aliases: ['--help', '-h'],
+        description: 'Show help or ask AI a question',
+        handler: async () => (await import('./commands/help.js')).runShowHelp,
+        flags: {
+            '--report-issue': { description: 'Create GitHub issue interactively' }
+        }
+    }
+];
+
+/**
+ * Build a lookup map from command name/alias to command entry
+ * @returns {Map<string, CommandEntry>}
+ */
+export function buildCommandMap() {
+    const map = new Map();
+    for (const cmd of commands) {
+        map.set(cmd.name, cmd);
+        if (cmd.aliases) {
+            for (const alias of cmd.aliases) {
+                map.set(alias, cmd);
+            }
+        }
+    }
+    return map;
+}
+
+/**
+ * Generate flat completion data for shell script generators
+ *
+ * @returns {{ commands: string[], descriptions: Object<string, string>, flags: Object<string, string[]>, subcommands: Object<string, string[]>, argValues: Object<string, string[]>, argCompletions: Object<string, string>, flagValues: Object<string, Object<string, string[]>> }}
+ */
+export function generateCompletionData() {
+    const data = {
+        commands: [],
+        descriptions: {},
+        flags: {},
+        subcommands: {},
+        argValues: {},
+        argCompletions: {},
+        flagValues: {}
+    };
+
+    for (const cmd of commands) {
+        // Skip alias-only entries (--version, --help mapped via version/help)
+        if (cmd.name.startsWith('-')) {
+            // Still include --set-preset and --debug as they are primary names
+            if (cmd.name !== '--set-preset' && cmd.name !== '--debug') {
+                continue;
+            }
+        }
+
+        data.commands.push(cmd.name);
+        data.descriptions[cmd.name] = cmd.description;
+
+        if (cmd.flags) {
+            data.flags[cmd.name] = Object.keys(cmd.flags);
+
+            // Collect flag-level values (e.g., --suffix takes a value)
+            const flagVals = {};
+            for (const [flag, meta] of Object.entries(cmd.flags)) {
+                if (meta.values) {
+                    flagVals[flag] = meta.values;
+                }
+            }
+            if (Object.keys(flagVals).length > 0) {
+                data.flagValues[cmd.name] = flagVals;
+            }
+        }
+
+        if (cmd.subcommands) {
+            data.subcommands[cmd.name] = cmd.subcommands;
+        }
+
+        if (cmd.args) {
+            if (cmd.args.values) {
+                data.argValues[cmd.name] = cmd.args.values;
+            }
+            if (cmd.args.completion) {
+                data.argCompletions[cmd.name] = cmd.args.completion;
+            }
+        }
+    }
+
+    // Add aliases that users type directly
+    data.commands.push('--version', '-v', '--help', '-h');
+    data.descriptions['--version'] = 'Show current version';
+    data.descriptions['-v'] = 'Show current version';
+    data.descriptions['--help'] = 'Show help';
+    data.descriptions['-h'] = 'Show help';
+
+    return data;
+}

package/lib/commands/analyze-diff.js

@@ -7,12 +7,7 @@ import fs from 'fs';
 import { analyzeBranchForPR } from '../utils/pr-metadata-engine.js';
 import { getConfig } from '../config.js';
 import logger from '../utils/logger.js';
-import {
-    colors,
-    error,
-    info,
-    checkGitRepo
-} from './helpers.js';
+import { colors, error, info, checkGitRepo } from './helpers.js';
 
 /**
  * Analyze-diff command
@@ -33,12 +28,18 @@ export async function runAnalyzeDiff(args) {
     // Parse target branch from arguments
     const targetBranch = args[0];
 
-    info(targetBranch ? `Analyzing differences with ${targetBranch}...` : 'Analyzing differences...');
+    info(
+        targetBranch ? `Analyzing differences with ${targetBranch}...` : 'Analyzing differences...'
+    );
     const startTime = Date.now();
 
     try {
         // Call PR metadata engine
-        const { success: engineSuccess, result, error: engineError } = await analyzeBranchForPR(targetBranch, {
+        const {
+            success: engineSuccess,
+            result,
+            error: engineError
+        } = await analyzeBranchForPR(targetBranch, {
             hook: 'analyze-diff'
         });
 
@@ -132,8 +133,9 @@ export async function runAnalyzeDiff(args) {
             console.log(`   git branch -m ${result.suggestedBranchName}`);
         }
 
-        console.log(`💡 ${colors.yellow}Tip:${colors.reset} Use this information to create your PR on GitHub.`);
-
+        console.log(
+            `💡 ${colors.yellow}Tip:${colors.reset} Use this information to create your PR on GitHub.`
+        );
     } catch (e) {
         error(`Error analyzing diff: ${e.message}`);
     }

package/lib/commands/analyze.js

@@ -19,7 +19,12 @@
  *   claude-hooks analyze --all        # Analyze all tracked files
  */
 
-import { getStagedFiles, getUnstagedFiles, getAllTrackedFiles, createCommit } from '../utils/git-operations.js';
+import {
+    getStagedFiles,
+    getUnstagedFiles,
+    getAllTrackedFiles,
+    createCommit
+} from '../utils/git-operations.js';
 import { filterFiles } from '../utils/file-operations.js';
 import {
     buildFilesData,
@@ -97,12 +102,12 @@ export const runAnalyze = async (options = {}) => {
             extensions: allowedExtensions
         });
 
-        const validFiles = filteredFiles.filter(f => f.valid);
-        const invalidFiles = filteredFiles.filter(f => !f.valid);
+        const validFiles = filteredFiles.filter((f) => f.valid);
+        const invalidFiles = filteredFiles.filter((f) => !f.valid);
 
         // Show warnings for skipped files
         if (invalidFiles.length > 0) {
-            invalidFiles.forEach(file => {
+            invalidFiles.forEach((file) => {
                 logger.warning(`Skipping ${file.path}: ${file.reason}`);
             });
         }
@@ -208,7 +213,6 @@ export const runAnalyze = async (options = {}) => {
                 process.exit(1);
             }
         }
-
     } catch (err) {
         logger.error('analyze', 'Analysis failed', err);
         error(`Analysis failed: ${err.message}`);

package/lib/commands/bump-version.js

@@ -27,12 +27,7 @@ import {
     updateVersionFiles,
     validateVersionFormat
 } from '../utils/version-manager.js';
-import {
-    createTag,
-    pushTags,
-    tagExists,
-    formatTagName
-} from '../utils/git-tag-manager.js';
+import { createTag, pushTags, tagExists, formatTagName } from '../utils/git-tag-manager.js';
 import {
     generateChangelogEntry,
     updateChangelogFile,
@@ -58,11 +53,7 @@ import {
     promptEditField
 } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
-import {
-    colors,
-    error,
-    checkGitRepo
-} from './helpers.js';
+import { colors, error, checkGitRepo } from './helpers.js';
 
 /**
  * Validates prerequisites before version bump
@@ -111,7 +102,6 @@ function validatePrerequisites() {
         });
 
         return { valid, errors };
-
     } catch (err) {
         logger.error('bump-version - validatePrerequisites', 'Validation failed', err);
         return {
@@ -204,9 +194,15 @@ function parseArguments(args) {
  */
 function displayDiscoveryTable(discovery) {
     console.log('');
-    console.log(`${colors.blue}═══════════════════════════════════════════════════════════════${colors.reset}`);
-    console.log(`${colors.blue}                   Version Files Discovery                      ${colors.reset}`);
-    console.log(`${colors.blue}═══════════════════════════════════════════════════════════════${colors.reset}`);
+    console.log(
+        `${colors.blue}═══════════════════════════════════════════════════════════════${colors.reset}`
+    );
+    console.log(
+        `${colors.blue}                   Version Files Discovery                      ${colors.reset}`
+    );
+    console.log(
+        `${colors.blue}═══════════════════════════════════════════════════════════════${colors.reset}`
+    );
     console.log('');
 
     if (discovery.files.length === 0) {
@@ -216,7 +212,9 @@ function displayDiscoveryTable(discovery) {
     }
 
     // Table header
-    console.log(`  ${'#'.padEnd(3)} ${'File'.padEnd(35)} ${'Type'.padEnd(15)} ${'Version'.padEnd(15)}`);
+    console.log(
+        `  ${'#'.padEnd(3)} ${'File'.padEnd(35)} ${'Type'.padEnd(15)} ${'Version'.padEnd(15)}`
+    );
     console.log(`  ${'-'.repeat(3)} ${'-'.repeat(35)} ${'-'.repeat(15)} ${'-'.repeat(15)}`);
 
     // Table rows
@@ -225,7 +223,8 @@ function displayDiscoveryTable(discovery) {
         const filePath = file.relativePath.padEnd(35);
         const fileType = file.projectLabel.padEnd(15);
         const version = file.version ? file.version.padEnd(15) : 'N/A'.padEnd(15);
-        const mismatchMarker = discovery.mismatch && file.version !== discovery.resolvedVersion ? ' ⚠️ ' : '';
+        const mismatchMarker =
+            discovery.mismatch && file.version !== discovery.resolvedVersion ? ' ⚠️ ' : '';
 
         console.log(`  ${num} ${filePath} ${fileType} ${version}${mismatchMarker}`);
     });
@@ -249,7 +248,9 @@ function displayDiscoveryTable(discovery) {
 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}           DRY RUN - No changes will be made      ${colors.reset}`
+    );
     console.log(`${colors.yellow}═════════════════════════════════════════════════${colors.reset}`);
     console.log('');
 
@@ -263,7 +264,7 @@ function showDryRunPreview(info) {
 
     if (info.selectedFiles.length > 0) {
         console.log(`${colors.blue}Files to update:${colors.reset}`);
-        info.selectedFiles.forEach(file => {
+        info.selectedFiles.forEach((file) => {
             const targetVer = file.targetVersion || info.newVersion;
             console.log(`  - ${file.relativePath} (${file.version} → ${targetVer})`);
         });
@@ -397,7 +398,9 @@ export async function runBumpVersion(args) {
         console.log('  --remove-suffix           Remove version suffix (2.15.5-SNAPSHOT → 2.15.5)');
         console.log('  --set-suffix <value>      Set/replace suffix (2.15.5 → 2.15.5-SNAPSHOT)');
         console.log('  --interactive             Force interactive file selection menu');
-        console.log('  --update-changelog [branch]  Generate CHANGELOG entry (default branch: main)');
+        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('  --push                    Push tag to remote (default: tags stay local)');
@@ -426,7 +429,7 @@ export async function runBumpVersion(args) {
     if (!validation.valid) {
         showError('Prerequisites validation failed:');
         console.log('');
-        validation.errors.forEach(err => console.log(`  ❌ ${err}`));
+        validation.errors.forEach((err) => console.log(`  ❌ ${err}`));
         console.log('');
         console.log('Please fix these issues:');
         console.log('  - Commit or stash uncommitted changes: git stash');
@@ -472,7 +475,7 @@ export async function runBumpVersion(args) {
     showInfo(`Current version: ${currentVersion}`);
 
     // Step 3: File selection (if mismatch or interactive mode)
-    let selectedFiles = discovery.files.filter(f => f.selected);
+    let selectedFiles = discovery.files.filter((f) => f.selected);
 
     if (discovery.mismatch || options.interactive) {
         selectedFiles = await promptFileSelection(discovery);
@@ -500,7 +503,11 @@ export async function runBumpVersion(args) {
             operation = `Set suffix to ${options.setSuffix}`;
         }
     } else {
-        newVersion = incrementVersion(currentVersion, options.bumpType, options.suffix || options.setSuffix);
+        newVersion = incrementVersion(
+            currentVersion,
+            options.bumpType,
+            options.suffix || options.setSuffix
+        );
         operation = `Bump ${options.bumpType}`;
     }
 
@@ -524,10 +531,7 @@ export async function runBumpVersion(args) {
     }
 
     // Step 6: Confirm with user
-    const shouldContinue = await promptConfirmation(
-        `Update version to ${newVersion}?`,
-        true
-    );
+    const shouldContinue = await promptConfirmation(`Update version to ${newVersion}?`, true);
 
     if (!shouldContinue) {
         showInfo('Version bump cancelled');
@@ -545,7 +549,7 @@ export async function runBumpVersion(args) {
         // Step 7: Snapshot files for rollback
         logger.debug('bump-version', 'Step 7: Creating snapshot for rollback');
         const snapshot = new Map();
-        selectedFiles.forEach(file => {
+        selectedFiles.forEach((file) => {
             try {
                 const content = fs.readFileSync(file.path, 'utf8');
                 snapshot.set(file.path, content);
@@ -568,7 +572,7 @@ export async function runBumpVersion(args) {
         try {
             updateVersionFiles(selectedFiles, newVersion);
 
-            selectedFiles.forEach(file => {
+            selectedFiles.forEach((file) => {
                 const targetVer = file.targetVersion || newVersion;
                 showSuccess(`✓ Updated ${file.relativePath} → ${targetVer}`);
             });
@@ -625,11 +629,12 @@ export async function runBumpVersion(args) {
             showInfo('Staging and committing changes...');
 
             // Collect files to stage
-            const filesToStage = selectedFiles.map(f => f.path);
+            const filesToStage = selectedFiles.map((f) => f.path);
 
             // Add CHANGELOG if it was updated (use selected path from Step 9, or default root)
             if (options.updateChangelog) {
-                const changelogPath = selectedChangelogPath || path.join(getRepoRoot(), 'CHANGELOG.md');
+                const changelogPath =
+                    selectedChangelogPath || path.join(getRepoRoot(), 'CHANGELOG.md');
                 if (fs.existsSync(changelogPath)) {
                     filesToStage.push(changelogPath);
                 }
@@ -642,7 +647,7 @@ export async function runBumpVersion(args) {
                 showError(`Failed to stage files: ${stageResult.error}`);
                 console.log('');
                 console.log('Files that should be staged:');
-                filesToStage.forEach(f => console.log(`  - ${path.relative(getRepoRoot(), f)}`));
+                filesToStage.forEach((f) => console.log(`  - ${path.relative(getRepoRoot(), f)}`));
                 console.log('');
 
                 // Rollback version changes
@@ -694,7 +699,9 @@ export async function runBumpVersion(args) {
 
             // Prevent tag creation if changes not committed
             if (options.noCommit) {
-                showWarning('Tag creation skipped: --no-commit requires manual commit before tagging');
+                showWarning(
+                    'Tag creation skipped: --no-commit requires manual commit before tagging'
+                );
                 console.log('');
                 console.log('After committing, you can create the tag:');
                 console.log(`  git tag -a ${tagName} -m "Release version ${newVersion}"`);
@@ -758,16 +765,24 @@ export async function runBumpVersion(args) {
 
         // 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(
+            `${colors.green}════════════════════════════════════════════════${colors.reset}`
+        );
+        console.log(
+            `${colors.green}        Version Bump Complete ✅                ${colors.reset}`
+        );
+        console.log(
+            `${colors.green}════════════════════════════════════════════════${colors.reset}`
+        );
         console.log('');
 
         // Show updated files table
         console.log(`${colors.blue}Updated files:${colors.reset}`);
-        selectedFiles.forEach(file => {
+        selectedFiles.forEach((file) => {
             const targetVer = file.targetVersion || newVersion;
-            console.log(`  ✓ ${file.relativePath} (${file.projectLabel}) - ${file.version} → ${targetVer}`);
+            console.log(
+                `  ✓ ${file.relativePath} (${file.projectLabel}) - ${file.version} → ${targetVer}`
+            );
         });
         console.log('');
 
@@ -785,7 +800,9 @@ export async function runBumpVersion(args) {
                 console.log('     git add CHANGELOG.md');
             }
             console.log(`  3. Commit: git commit -m "chore(version): bump to ${newVersion}"`);
-            console.log(`  4. Create tag: git tag -a ${tagName} -m "Release version ${newVersion}"`);
+            console.log(
+                `  4. Create tag: git tag -a ${tagName} -m "Release version ${newVersion}"`
+            );
             console.log(`  5. Push: git push origin $(git branch --show-current) ${tagName}`);
             console.log('');
         } else if (commitCreated && !options.noTag && options.push) {
@@ -802,7 +819,6 @@ export async function runBumpVersion(args) {
             }
             console.log('');
         }
-
     } catch (err) {
         logger.error('bump-version', 'Version bump failed', err);
         showError(`Version bump failed: ${err.message}`);