claude-git-hooks 2.20.0 → 2.30.1

package/lib/utils/git-operations.js

@@ -1078,6 +1078,474 @@ const getCommitsBetweenRefs = (baseRef, headRef = 'HEAD', { format = 'oneline' }
     }
 };
 
+/**
+ * Checks out a branch, optionally creating it
+ * Why: Supports workflow commands that need to switch or create branches programmatically
+ *
+ * @param {string} branchName - Branch to checkout (or create)
+ * @param {Object} options
+ * @param {boolean} options.create - Create the branch with -b flag (default: false)
+ * @param {string} options.startPoint - Start point for new branch (e.g., 'origin/main')
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ */
+const checkoutBranch = (branchName, { create = false, startPoint, repoPath } = {}) => {
+    logger.debug('git-operations - checkoutBranch', 'Checking out branch', {
+        branchName,
+        create,
+        startPoint
+    });
+
+    const sanitized = sanitizeBranchName(branchName);
+    if (!sanitized) {
+        throw new GitError('Invalid branch name', {
+            command: 'checkoutBranch',
+            output: branchName
+        });
+    }
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    let command = create ? `checkout -b ${sanitized}` : `checkout ${sanitized}`;
+
+    if (startPoint) {
+        const sanitizedStart = sanitizeBranchName(startPoint);
+        if (!sanitizedStart) {
+            throw new GitError('Invalid start point', {
+                command: 'checkoutBranch',
+                output: startPoint
+            });
+        }
+        command += ` ${sanitizedStart}`;
+    }
+
+    try {
+        execGitCommand(command, opts);
+        logger.debug('git-operations - checkoutBranch', 'Checkout successful', { branchName });
+    } catch (error) {
+        logger.error('git-operations - checkoutBranch', 'Checkout failed', error);
+        throw new GitError(`Failed to checkout branch: ${sanitized}`, {
+            command: `git ${command}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Merges a branch into the current branch
+ * Why: Supports workflow commands that need to merge branches programmatically
+ *
+ * @param {string} sourceBranch - Branch to merge
+ * @param {Object} options
+ * @param {string} options.message - Custom merge commit message
+ * @param {boolean} options.noFF - Use --no-ff to always create a merge commit (default: false)
+ * @param {boolean} options.noEdit - Use --no-edit to skip editor for merge message (default: false)
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ */
+const mergeBranch = (sourceBranch, { message, noFF = false, noEdit = false, repoPath } = {}) => {
+    logger.debug('git-operations - mergeBranch', 'Merging branch', { sourceBranch, noFF, noEdit });
+
+    const sanitized = sanitizeBranchName(sourceBranch);
+    if (!sanitized) {
+        throw new GitError('Invalid branch name', { command: 'mergeBranch', output: sourceBranch });
+    }
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    let command = 'merge';
+    if (noFF) command += ' --no-ff';
+    if (noEdit) command += ' --no-edit';
+    if (message) {
+        const escapedMessage = message.replace(/"/g, '\\"');
+        command += ` -m "${escapedMessage}"`;
+    }
+    command += ` ${sanitized}`;
+
+    try {
+        execGitCommand(command, opts);
+        logger.debug('git-operations - mergeBranch', 'Merge successful', { sourceBranch });
+    } catch (error) {
+        logger.error('git-operations - mergeBranch', 'Merge failed', error);
+        throw new GitError(`Failed to merge branch: ${sanitized}`, {
+            command: `git ${command}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Resets current branch to a target ref
+ * Why: Supports workflow commands that need to undo commits (e.g., revert-feature, close-release)
+ * ⚠️ Destructive — always logs a warning before execution
+ *
+ * @param {string} target - Ref to reset to (e.g., 'origin/main', commit SHA)
+ * @param {Object} options
+ * @param {'soft'|'hard'} options.mode - Reset mode (default: 'soft')
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @param {boolean} options.dryRun - Log intent without executing (default: false)
+ */
+const resetBranch = (target, { mode = 'soft', repoPath, dryRun = false } = {}) => {
+    const sanitized = sanitizeBranchName(target);
+    if (!sanitized) {
+        throw new GitError('Invalid target', { command: 'resetBranch', output: target });
+    }
+
+    if (mode !== 'soft' && mode !== 'hard') {
+        throw new GitError('Invalid reset mode — must be "soft" or "hard"', {
+            command: 'resetBranch',
+            output: mode
+        });
+    }
+
+    if (dryRun) {
+        logger.debug(
+            'git-operations - resetBranch',
+            `[DRY RUN] Would execute: git reset --${mode} ${sanitized}`
+        );
+        return;
+    }
+
+    logger.warning('git-operations - resetBranch', `Resetting branch --${mode} to ${sanitized}`);
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        execGitCommand(`reset --${mode} ${sanitized}`, opts);
+        logger.debug('git-operations - resetBranch', 'Reset successful', {
+            target: sanitized,
+            mode
+        });
+    } catch (error) {
+        logger.error('git-operations - resetBranch', 'Reset failed', error);
+        throw new GitError(`Failed to reset branch: --${mode} ${sanitized}`, {
+            command: `git reset --${mode} ${sanitized}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Force pushes a branch to remote
+ * Why: Required after rebase or reset to update remote branch history
+ * ⚠️ Destructive — always logs a warning before execution
+ *
+ * @param {string} branchName - Branch to force push
+ * @param {Object} options
+ * @param {boolean} options.lease - Use --force-with-lease for safety (default: true)
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @param {boolean} options.dryRun - Log intent without executing (default: false)
+ * @returns {{ success: boolean, output: string, error: string }}
+ */
+const forcePush = (branchName, { lease = true, repoPath, dryRun = false } = {}) => {
+    const sanitized = sanitizeBranchName(branchName);
+    if (!sanitized) {
+        throw new GitError('Invalid branch name', { command: 'forcePush', output: branchName });
+    }
+
+    const forceFlag = lease ? '--force-with-lease' : '--force';
+    const remoteName = getRemoteName();
+
+    if (dryRun) {
+        logger.debug(
+            'git-operations - forcePush',
+            `[DRY RUN] Would execute: git push ${forceFlag} ${remoteName} ${sanitized}`
+        );
+        return { success: true, output: '', error: '' };
+    }
+
+    logger.warning(
+        'git-operations - forcePush',
+        `Force pushing ${sanitized} to ${remoteName} with ${forceFlag}`
+    );
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        const output = execGitCommand(`push ${forceFlag} ${remoteName} ${sanitized}`, opts);
+        logger.debug('git-operations - forcePush', 'Force push successful', {
+            branchName: sanitized,
+            remoteName,
+            forceFlag
+        });
+        return { success: true, output, error: '' };
+    } catch (error) {
+        logger.error('git-operations - forcePush', 'Force push failed', error);
+        return {
+            success: false,
+            output: '',
+            error:
+                error.output || error.cause?.message || error.message || 'Unknown force push error'
+        };
+    }
+};
+
+/**
+ * Deletes a branch from the remote
+ * Why: Used by workflow commands to clean up merged feature/release branches
+ * ⚠️ Destructive — logs a warning before execution; server enforces branch protection rules
+ *
+ * @param {string} branchName - Remote branch to delete
+ * @param {Object} options
+ * @param {string} options.remote - Remote name (default: detected remote)
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @param {boolean} options.dryRun - Log intent without executing (default: false)
+ */
+const deleteRemoteBranch = (branchName, { remote, repoPath, dryRun = false } = {}) => {
+    const sanitized = sanitizeBranchName(branchName);
+    if (!sanitized) {
+        throw new GitError('Invalid branch name', {
+            command: 'deleteRemoteBranch',
+            output: branchName
+        });
+    }
+
+    const remoteName = remote || getRemoteName();
+
+    if (dryRun) {
+        logger.debug(
+            'git-operations - deleteRemoteBranch',
+            `[DRY RUN] Would execute: git push ${remoteName} --delete ${sanitized}`
+        );
+        return;
+    }
+
+    logger.warning(
+        'git-operations - deleteRemoteBranch',
+        `Deleting remote branch ${remoteName}/${sanitized}`
+    );
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        execGitCommand(`push ${remoteName} --delete ${sanitized}`, opts);
+        logger.debug('git-operations - deleteRemoteBranch', 'Remote branch deleted', {
+            branchName: sanitized,
+            remoteName
+        });
+    } catch (error) {
+        logger.error(
+            'git-operations - deleteRemoteBranch',
+            'Failed to delete remote branch',
+            error
+        );
+        throw new GitError(`Failed to delete remote branch: ${remoteName}/${sanitized}`, {
+            command: `git push ${remoteName} --delete ${sanitized}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Gets the commit divergence between two refs
+ * Why: Determines how far ahead/behind a branch is for automated workflow decisions
+ *
+ * @param {string} refA - First ref (e.g., local branch)
+ * @param {string} refB - Second ref (e.g., 'origin/main')
+ * @param {Object} options
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @returns {{ ahead: number, behind: number }} Commits in refA not in refB (ahead) and vice versa (behind)
+ */
+const getDivergence = (refA, refB, { repoPath } = {}) => {
+    logger.debug('git-operations - getDivergence', 'Getting divergence', { refA, refB });
+
+    const sanitizedA = sanitizeBranchName(refA);
+    const sanitizedB = sanitizeBranchName(refB);
+    if (!sanitizedA || !sanitizedB) {
+        throw new GitError('Invalid ref', {
+            command: 'getDivergence',
+            output: `refA: ${refA}, refB: ${refB}`
+        });
+    }
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        const aheadOutput = execGitCommand(`rev-list --count ${sanitizedB}..${sanitizedA}`, opts);
+        const behindOutput = execGitCommand(`rev-list --count ${sanitizedA}..${sanitizedB}`, opts);
+        const result = {
+            ahead: parseInt(aheadOutput, 10) || 0,
+            behind: parseInt(behindOutput, 10) || 0
+        };
+        logger.debug('git-operations - getDivergence', 'Divergence calculated', { ...result });
+        return result;
+    } catch (error) {
+        logger.error('git-operations - getDivergence', 'Failed to get divergence', error);
+        throw new GitError('Failed to get divergence', {
+            command: `git rev-list --count ${sanitizedA}..${sanitizedB}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Reads a file from a specific ref without checking out
+ * Why: Allows reading file content from another branch or commit without switching branches
+ *
+ * @param {string} ref - Git ref (branch name, tag, or commit SHA)
+ * @param {string} filePath - Path to file within the repository
+ * @param {Object} options
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @returns {string} File content at the specified ref
+ */
+const readFileFromRef = (ref, filePath, { repoPath } = {}) => {
+    logger.debug('git-operations - readFileFromRef', 'Reading file from ref', { ref, filePath });
+
+    const sanitizedRef = sanitizeBranchName(ref);
+    if (!sanitizedRef) {
+        throw new GitError('Invalid ref', { command: 'readFileFromRef', output: ref });
+    }
+
+    if (!filePath || typeof filePath !== 'string' || filePath.trim().length === 0) {
+        throw new GitError('Invalid file path', {
+            command: 'readFileFromRef',
+            output: String(filePath)
+        });
+    }
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    return execGitCommand(`show "${sanitizedRef}:${filePath}"`, opts);
+};
+
+/**
+ * Gets the latest tag matching a pattern
+ * Why: Used by workflow commands to find the current release version
+ *
+ * @param {string} [pattern='v*'] - Glob pattern to match tags (e.g., 'v*', 'release-*')
+ * @param {Object} options
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @returns {string|null} Latest tag name, or null if no matching tags found
+ */
+const getLatestTag = (pattern = 'v*', { repoPath } = {}) => {
+    logger.debug('git-operations - getLatestTag', 'Getting latest tag', { pattern });
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        const matchFlag = pattern ? `--match "${pattern}"` : '';
+        const tag = execGitCommand(`describe --tags --abbrev=0 ${matchFlag}`.trim(), opts);
+        logger.debug('git-operations - getLatestTag', 'Latest tag found', { tag });
+        return tag;
+    } catch (error) {
+        logger.debug('git-operations - getLatestTag', 'No matching tag found', { pattern });
+        return null;
+    }
+};
+
+/**
+ * Checks if the working directory has no uncommitted changes
+ * Why: Workflow commands need a clean working directory before proceeding with destructive operations
+ *
+ * @param {Object} options
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @returns {boolean} True if working directory is clean (no uncommitted changes)
+ */
+const isWorkingDirectoryClean = ({ repoPath } = {}) => {
+    logger.debug('git-operations - isWorkingDirectoryClean', 'Checking working directory status');
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        const output = execGitCommand('status --porcelain', opts);
+        const isClean = output.length === 0;
+        logger.debug('git-operations - isWorkingDirectoryClean', 'Working directory status', {
+            isClean
+        });
+        return isClean;
+    } catch (error) {
+        logger.error(
+            'git-operations - isWorkingDirectoryClean',
+            'Failed to check working directory status',
+            error
+        );
+        return false;
+    }
+};
+
+/**
+ * Finds the most recently updated remote branch matching a prefix
+ * Why: Used to locate the active release or feature branch for a given workflow stage
+ *
+ * @param {string} prefix - Branch prefix to match (e.g., 'release', 'feature/IX-123')
+ * @param {Object} options
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @returns {string|null} Most recently updated matching branch name (without remote prefix), or null
+ */
+const getActiveBranch = (prefix, { repoPath } = {}) => {
+    logger.debug('git-operations - getActiveBranch', 'Finding active branch', { prefix });
+
+    const sanitizedPrefix = sanitizeBranchName(prefix);
+    if (!sanitizedPrefix) {
+        throw new GitError('Invalid branch prefix', { command: 'getActiveBranch', output: prefix });
+    }
+
+    const remoteName = getRemoteName();
+    const opts = repoPath ? { cwd: repoPath } : {};
+
+    try {
+        const output = execGitCommand(
+            `branch -r --list "${remoteName}/${sanitizedPrefix}/*" --sort=-committerdate`,
+            opts
+        );
+
+        if (!output) {
+            logger.debug('git-operations - getActiveBranch', 'No matching branches found', {
+                prefix: sanitizedPrefix
+            });
+            return null;
+        }
+
+        const branches = output
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line && !line.includes('->'))
+            .map((line) => line.replace(`${remoteName}/`, ''));
+
+        const result = branches.length > 0 ? branches[0] : null;
+        logger.debug('git-operations - getActiveBranch', 'Active branch resolved', { result });
+        return result;
+    } catch (error) {
+        logger.error('git-operations - getActiveBranch', 'Failed to get active branch', error);
+        return null;
+    }
+};
+
+/**
+ * Gets the list of files changed in a specific commit
+ * Why: Used by revert-feature to identify files touched by a commit for coupling detection
+ *
+ * @param {string} hash - Commit hash (short or full SHA)
+ * @param {Object} options
+ * @param {string} options.repoPath - Path to repository root (default: cwd)
+ * @returns {string[]} Array of file paths changed in the commit
+ */
+const getCommitFiles = (hash, { repoPath } = {}) => {
+    logger.debug('git-operations - getCommitFiles', 'Getting files for commit', { hash });
+
+    const sanitizedHash = sanitizeBranchName(hash);
+    if (!sanitizedHash) {
+        throw new GitError('Invalid commit hash', { command: 'getCommitFiles', output: hash });
+    }
+
+    const opts = repoPath ? { cwd: repoPath } : {};
+    try {
+        const output = execGitCommand(
+            `diff-tree --no-commit-id -r --name-only ${sanitizedHash}`,
+            opts
+        );
+
+        if (!output) {
+            logger.debug('git-operations - getCommitFiles', 'No files found for commit', { hash });
+            return [];
+        }
+
+        const files = output.split(/\r?\n/).filter((f) => f.length > 0);
+
+        logger.debug('git-operations - getCommitFiles', 'Files retrieved', {
+            hash,
+            fileCount: files.length
+        });
+
+        return files;
+    } catch (error) {
+        logger.error('git-operations - getCommitFiles', 'Failed to get commit files', error);
+        throw new GitError(`Failed to get files for commit: ${sanitizedHash}`, {
+            command: `git diff-tree --no-commit-id -r --name-only ${sanitizedHash}`,
+            cause: error
+        });
+    }
+};
+
 export {
     GitError,
     getStagedFiles,
@@ -1102,5 +1570,16 @@ export {
     resolveBaseBranch,
     getChangedFilesBetweenRefs,
     getDiffBetweenRefs,
-    getCommitsBetweenRefs
+    getCommitsBetweenRefs,
+    checkoutBranch,
+    mergeBranch,
+    resetBranch,
+    forcePush,
+    deleteRemoteBranch,
+    getDivergence,
+    readFileFromRef,
+    getLatestTag,
+    isWorkingDirectoryClean,
+    getActiveBranch,
+    getCommitFiles
 };