claude-git-hooks 2.13.0 → 2.14.1

package/lib/commands/create-pr.js

@@ -6,8 +6,7 @@
 import { execSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
-import { executeClaudeWithRetry, extractJSON } from '../utils/claude-client.js';
-import { loadPrompt } from '../utils/prompt-builder.js';
+import { analyzeBranchForPR } from '../utils/pr-metadata-engine.js';
 import { getConfig } from '../config.js';
 import { getOrPromptTaskId, formatWithTaskId } from '../utils/task-id.js';
 import { getReviewersForFiles } from '../utils/github-client.js';
@@ -82,7 +81,7 @@ export async function runCreatePr(args) {
         const taskId = await getOrPromptTaskId({
             prompt: true,      // DO prompt for PRs (unlike commit messages)
             required: false,   // Allow skipping
-            config: config     // Pass config for custom pattern
+            config             // Pass config for custom pattern
         });
         logger.debug('create-pr', 'Task ID determined', { taskId });
 
@@ -336,90 +335,26 @@ export async function runCreatePr(args) {
             }
         }
 
-        // Step 6: Update remote and check for differences
-        logger.debug('create-pr', 'Step 6: Fetching latest changes from remote');
-        execSync('git fetch', { stdio: 'ignore' });
-        const compareWith = `origin/${baseBranch}...HEAD`;
-
-        try {
-            execSync(`git rev-parse --verify origin/${baseBranch}`, { stdio: 'ignore' });
-        } catch (e) {
-            error(`Base branch origin/${baseBranch} does not exist`);
-            return;
-        }
-
-        let diffFiles;
-        try {
-            diffFiles = execSync(`git diff ${compareWith} --name-only`, { encoding: 'utf8' }).trim();
-            if (!diffFiles) {
-                showWarning('No differences with remote branch. Nothing to create a PR for.');
-                return;
-            }
-        } catch (e) {
-            error('Error getting differences: ' + e.message);
-            return;
-        }
+        // Step 6: Generate PR metadata using engine
+        logger.debug('create-pr', 'Step 6: Generating PR metadata with engine');
+        showInfo('Generating PR metadata with Claude...');
 
-        const filesArray = diffFiles.split('\n').filter(f => f.trim());
-        logger.debug('create-pr', 'Modified files detected', {
-            fileCount: filesArray.length,
-            files: filesArray
+        const { success: engineSuccess, result: analysisResult, error: engineError } = await analyzeBranchForPR(baseBranch, {
+            hook: 'create-pr'
         });
-        showInfo(`Found ${filesArray.length} modified file(s)`);
 
-        // Step 7: Generate PR metadata with Claude (reuse analyze-diff logic)
-        logger.debug('create-pr', 'Step 7: Generating PR metadata with Claude');
-        let fullDiff, commits;
-        try {
-            fullDiff = execSync(`git diff ${compareWith}`, { encoding: 'utf8' });
-            commits = execSync(`git log origin/${baseBranch}..HEAD --oneline`, { encoding: 'utf8' }).trim();
-        } catch (e) {
-            error('Error getting diff or commits: ' + e.message);
+        if (!engineSuccess) {
+            logger.error('create-pr', 'Failed to generate PR metadata', { error: engineError });
+            error(engineError || 'Failed to generate PR metadata');
             return;
         }
 
-        const truncatedDiff = fullDiff.length > 50000
-            ? fullDiff.substring(0, 50000) + '\n... (truncated)'
-            : fullDiff;
-
-        const contextDescription = `${currentBranch} vs origin/${baseBranch}`;
-        const prompt = await loadPrompt('ANALYZE_DIFF.md', {
-            CONTEXT_DESCRIPTION: contextDescription,
-            SUBAGENT_INSTRUCTION: '',
-            COMMITS: commits,
-            DIFF_FILES: diffFiles,
-            FULL_DIFF: truncatedDiff
-        });
-
-        showInfo('Generating PR metadata with Claude...');
-        logger.debug('create-pr', 'Calling Claude with prompt', { promptLength: prompt.length });
-
-        // Prepare telemetry context for create-pr
-        const telemetryContext = {
+        const filesArray = analysisResult.context.files;
+        logger.debug('create-pr', 'PR metadata generated', {
             fileCount: filesArray.length,
-            batchSize: filesArray.length,
-            totalBatches: 1,
-            model: 'sonnet', // create-pr always uses main model
-            hook: 'create-pr'
-        };
-
-        const response = await executeClaudeWithRetry(prompt, {
-            timeout: 180000,
-            telemetryContext
+            hasPrTitle: !!analysisResult.prTitle
         });
-        logger.debug('create-pr', 'Claude response received', { responseLength: response.length });
-
-        const analysisResult = extractJSON(response);
-        logger.debug('create-pr', 'Analysis result extracted', {
-            hasResult: !!analysisResult,
-            hasPrTitle: !!analysisResult?.prTitle
-        });
-
-        if (!analysisResult || !analysisResult.prTitle) {
-            logger.error('create-pr', 'Failed to generate PR metadata from analysis', { analysisResult });
-            error('Failed to generate PR metadata from analysis');
-            return;
-        }
+        showInfo(`Found ${filesArray.length} modified file(s)`);
 
         // Step 8: Prepare PR data
         logger.debug('create-pr', 'Step 8: Preparing PR data');
@@ -562,7 +497,7 @@ export async function runCreatePr(args) {
 
     } catch (err) {
         logger.error('create-pr', 'Error creating PR', err);
-        showError('Error creating PR: ' + err.message);
+        showError(`Error creating PR: ${err.message}`);
 
         if (err.context) {
             logger.debug('create-pr', 'Error context', err.context);

package/lib/commands/helpers.js

@@ -193,8 +193,15 @@ export async function updateConfig(propertyPath, value, options = {}) {
         }
 
         // Set value at propertyPath (support dot notation like 'system.debug')
+        // For v2.8.0 format, write inside 'overrides' so loadUserConfig picks it up
         const pathParts = propertyPath.split('.');
         let current = config;
+        if (config.version === '2.8.0') {
+            if (!config.overrides || typeof config.overrides !== 'object') {
+                config.overrides = {};
+            }
+            current = config.overrides;
+        }
         for (let i = 0; i < pathParts.length - 1; i++) {
             const part = pathParts[i];
             if (!current[part] || typeof current[part] !== 'object') {

package/lib/utils/claude-client.js

@@ -380,7 +380,12 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [] } = {}) =>
         reject(new ClaudeClientError('Claude CLI execution timed out', {
             context: {
                 elapsedTime,
-                timeoutValue: timeout
+                timeoutValue: timeout,
+                errorInfo: {
+                    type: ClaudeErrorType.TIMEOUT,
+                    elapsedTime,
+                    timeoutValue: timeout
+                }
             }
         }));
     }, timeout);

package/lib/utils/claude-diagnostics.js

@@ -353,5 +353,6 @@ const formatGenericError = (errorInfo) => {
 export const isRecoverableError = (errorInfo) => {
     return errorInfo.type === ClaudeErrorType.EXECUTION_ERROR ||
            errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
-           errorInfo.type === ClaudeErrorType.NETWORK;
+           errorInfo.type === ClaudeErrorType.NETWORK ||
+           errorInfo.type === ClaudeErrorType.TIMEOUT;
 };

package/lib/utils/git-operations.js

@@ -13,8 +13,10 @@
  */
 
 import { execSync } from 'child_process';
+import fs from 'fs';
 import path from 'path';
 import logger from './logger.js';
+import { sanitizeBranchName } from './sanitize.js';
 
 /**
  * Custom error for git operation failures
@@ -616,6 +618,82 @@ const createCommit = (message, { noVerify = false } = {}) => {
     }
 };
 
+/**
+ * Stages files for commit
+ * Why: Prepares specific files for git commit (used by version bumping, changelog generation)
+ *
+ * @param {Array<string>} filePaths - Array of absolute file paths to stage
+ * @returns {Object} Result: { success: boolean, stagedFiles: Array<string>, error: string }
+ */
+const stageFiles = (filePaths) => {
+    logger.debug('git-operations - stageFiles', 'Staging files', { count: filePaths.length });
+
+    if (!Array.isArray(filePaths) || filePaths.length === 0) {
+        logger.warning('git-operations - stageFiles', 'No files provided');
+        return {
+            success: false,
+            stagedFiles: [],
+            error: 'No files provided to stage'
+        };
+    }
+
+    try {
+        const repoRoot = getRepoRoot();
+        const stagedFiles = [];
+
+        // Stage each file individually for granular error handling
+        for (const filePath of filePaths) {
+            // Convert to repo-relative path
+            const relativePath = path.relative(repoRoot, filePath);
+
+            // Verify file exists
+            if (!fs.existsSync(filePath)) {
+                logger.warning('git-operations - stageFiles', 'File not found, skipping', { filePath });
+                continue;
+            }
+
+            try {
+                execGitCommand(`add "${relativePath}"`);
+                stagedFiles.push(filePath);
+                logger.debug('git-operations - stageFiles', 'File staged', { relativePath });
+            } catch (error) {
+                logger.warning('git-operations - stageFiles', 'Failed to stage file', {
+                    filePath,
+                    error: error.message
+                });
+                // Continue staging other files
+            }
+        }
+
+        if (stagedFiles.length === 0) {
+            return {
+                success: false,
+                stagedFiles: [],
+                error: 'No files were successfully staged'
+            };
+        }
+
+        logger.debug('git-operations - stageFiles', 'Files staged successfully', {
+            count: stagedFiles.length
+        });
+
+        return {
+            success: true,
+            stagedFiles,
+            error: ''
+        };
+
+    } catch (error) {
+        logger.error('git-operations - stageFiles', 'Staging failed', error);
+
+        return {
+            success: false,
+            stagedFiles: [],
+            error: error.message || 'Unknown staging error'
+        };
+    }
+};
+
 /**
  * Pushes branch to remote
  * Why: Publishes local branch to remote before creating PR
@@ -663,6 +741,327 @@ const pushBranch = (branchName, { setUpstream = false } = {}) => {
     }
 };
 
+/**
+ * Fetches latest from remote
+ * Why: Ensures local git has up-to-date remote refs before comparing branches
+ *
+ * @param {string} [remoteName='origin'] - Remote name
+ */
+const fetchRemote = (remoteName = 'origin') => {
+    logger.debug('git-operations - fetchRemote', 'Fetching from remote', { remoteName });
+
+    // Sanitize remote name
+    const sanitizedRemote = sanitizeBranchName(remoteName);
+    if (!sanitizedRemote) {
+        throw new GitError('Invalid remote name', { command: 'fetch', output: remoteName });
+    }
+
+    try {
+        execGitCommand(`fetch ${sanitizedRemote}`);
+        logger.debug('git-operations - fetchRemote', 'Fetch successful', { remoteName: sanitizedRemote });
+    } catch (error) {
+        logger.error('git-operations - fetchRemote', 'Fetch failed', error);
+        throw new GitError('Failed to fetch from remote', {
+            command: `git fetch ${sanitizedRemote}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Checks if a branch reference exists
+ * Why: Validates branch refs before attempting operations to avoid failures
+ *
+ * @param {string} branchRef - Branch reference to verify (e.g., 'origin/main')
+ * @returns {boolean}
+ */
+const branchExists = (branchRef) => {
+    logger.debug('git-operations - branchExists', 'Checking if branch exists', { branchRef });
+
+    // Sanitize branch reference
+    const sanitizedRef = sanitizeBranchName(branchRef);
+    if (!sanitizedRef) {
+        logger.debug('git-operations - branchExists', 'Invalid branch reference', { branchRef });
+        return false;
+    }
+
+    try {
+        // Why: rev-parse --verify exits with 0 if ref exists, non-zero otherwise
+        // Why execSync instead of execGitCommand: Expected failures should not log at error level.
+        // branchExists() is a probe — failure is a valid outcome, not an error.
+        execSync(`git rev-parse --verify ${sanitizedRef}`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        logger.debug('git-operations - branchExists', 'Branch exists', { branchRef: sanitizedRef });
+        return true;
+    } catch (error) {
+        logger.debug('git-operations - branchExists', 'Branch does not exist', { branchRef: sanitizedRef });
+        return false;
+    }
+};
+
+/**
+ * Gets remote branch names (stripped of remote prefix)
+ * Why: Used by resolveBaseBranch to suggest similar branches
+ *
+ * @param {string} [remoteName='origin'] - Remote name
+ * @returns {string[]} Branch names without remote prefix
+ */
+const getRemoteBranches = (remoteName = 'origin') => {
+    try {
+        const output = execSync(`git branch -r --list "${remoteName}/*"`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+
+        if (!output) return [];
+
+        return output
+            .split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(line => !line.includes('->'))  // Skip HEAD -> origin/main
+            .map(line => line.replace(`${remoteName}/`, ''));
+    } catch {
+        return [];
+    }
+};
+
+/**
+ * Finds remote branches similar to the target by shared keywords
+ *
+ * @param {string} target - Branch name to match against
+ * @param {string[]} branches - Available branch names
+ * @returns {string[]} Similar branch names, sorted by relevance
+ */
+const findSimilarBranches = (target, branches) => {
+    const targetWords = target.toLowerCase().split(/[/\-_.]/).filter(w => w.length > 1);
+
+    const scored = branches
+        .map(branch => {
+            const branchWords = branch.toLowerCase().split(/[/\-_.]/).filter(w => w.length > 1);
+            const matches = targetWords.filter(tw => branchWords.some(bw => bw.includes(tw) || tw.includes(bw)));
+            return { branch, score: matches.length };
+        })
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score);
+
+    return scored.map(({ branch }) => branch);
+};
+
+/**
+ * Resolves base branch on remote.
+ * Verifies origin/{target} exists. If not, throws with suggestions
+ * of similar remote branches to help the user correct the name.
+ *
+ * @param {string} targetBranch - Requested base branch
+ * @returns {string} Resolved remote ref (e.g., 'origin/main')
+ * @throws {GitError} If branch not found (message includes suggestions)
+ */
+const resolveBaseBranch = (targetBranch) => {
+    logger.debug('git-operations - resolveBaseBranch', 'Resolving base branch', { targetBranch });
+
+    // Sanitize target branch
+    const sanitizedTarget = sanitizeBranchName(targetBranch);
+    if (!sanitizedTarget) {
+        throw new GitError('Invalid target branch name', { command: 'resolveBaseBranch', output: targetBranch });
+    }
+
+    // Try requested branch with origin/ prefix
+    const targetRef = `origin/${sanitizedTarget}`;
+    if (branchExists(targetRef)) {
+        logger.debug('git-operations - resolveBaseBranch', 'Target branch found', { ref: targetRef });
+        return targetRef;
+    }
+
+    // Branch not found — build helpful error with suggestions
+    const remoteBranches = getRemoteBranches();
+    const similar = findSimilarBranches(sanitizedTarget, remoteBranches);
+
+    let suggestion = '';
+    if (similar.length > 0) {
+        const shown = similar.slice(0, 5);
+        suggestion = `\n\nSimilar branches on remote:\n${shown.map(b => `  - ${b}`).join('\n')}`;
+    } else if (remoteBranches.length > 0) {
+        const shown = remoteBranches.slice(0, 10);
+        suggestion = `\n\nAvailable branches on remote:\n${shown.map(b => `  - ${b}`).join('\n')}`;
+        if (remoteBranches.length > 10) {
+            suggestion += `\n  ... and ${remoteBranches.length - 10} more`;
+        }
+    }
+
+    throw new GitError(`Branch '${sanitizedTarget}' not found on remote${suggestion}`, {
+        command: 'resolveBaseBranch',
+        output: `target: ${targetBranch}`
+    });
+};
+
+/**
+ * Gets list of files changed between two refs
+ * Why: Shows which files differ between branches for PR context
+ *
+ * @param {string} baseRef - Base reference (e.g., 'origin/main')
+ * @param {string} [headRef='HEAD'] - Head reference
+ * @returns {string[]} Array of changed file paths
+ */
+const getChangedFilesBetweenRefs = (baseRef, headRef = 'HEAD') => {
+    logger.debug('git-operations - getChangedFilesBetweenRefs', 'Getting changed files', { baseRef, headRef });
+
+    // Sanitize refs
+    const sanitizedBase = sanitizeBranchName(baseRef);
+    const sanitizedHead = sanitizeBranchName(headRef);
+
+    if (!sanitizedBase || !sanitizedHead) {
+        throw new GitError('Invalid branch reference', {
+            command: 'getChangedFilesBetweenRefs',
+            output: `base: ${baseRef}, head: ${headRef}`
+        });
+    }
+
+    try {
+        // Why: --name-only shows just file paths, ... compares merge-base to head
+        const output = execGitCommand(`diff --name-only ${sanitizedBase}...${sanitizedHead}`);
+
+        if (!output) {
+            logger.debug('git-operations - getChangedFilesBetweenRefs', 'No changed files', { baseRef, headRef });
+            return [];
+        }
+
+        const files = output.split(/\r?\n/).filter(f => f.length > 0);
+
+        logger.debug('git-operations - getChangedFilesBetweenRefs', 'Changed files retrieved', {
+            baseRef,
+            headRef,
+            fileCount: files.length
+        });
+
+        return files;
+
+    } catch (error) {
+        logger.error('git-operations - getChangedFilesBetweenRefs', 'Failed to get changed files', error);
+        throw new GitError('Failed to get changed files between refs', {
+            command: `git diff --name-only ${sanitizedBase}...${sanitizedHead}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Gets full diff between two refs.
+ *
+ * Complements the existing getFileDiff() which operates on a single file's
+ * staged/unstaged diff (git diff [--cached] -- <file>). This function operates
+ * on the comparison between two branch refs (git diff origin/main...HEAD) —
+ * the branch-level counterpart that is currently missing, which is why both
+ * analyze-diff.js and create-pr.js resort to raw execSync.
+ *
+ * Returns the raw diff string. Truncation/reduction is handled by
+ * buildDiffPayload() in pr-metadata-engine.js, not here.
+ *
+ * @param {string} baseRef - Base reference
+ * @param {string} [headRef='HEAD'] - Head reference
+ * @param {Object} [options]
+ * @param {number} [options.contextLines=3] - Lines of context around changes (-U flag)
+ * @returns {string} Raw unified diff
+ */
+const getDiffBetweenRefs = (baseRef, headRef = 'HEAD', { contextLines = 3 } = {}) => {
+    logger.debug('git-operations - getDiffBetweenRefs', 'Getting diff between refs', {
+        baseRef,
+        headRef,
+        contextLines
+    });
+
+    // Sanitize refs
+    const sanitizedBase = sanitizeBranchName(baseRef);
+    const sanitizedHead = sanitizeBranchName(headRef);
+
+    if (!sanitizedBase || !sanitizedHead) {
+        throw new GitError('Invalid branch reference', {
+            command: 'getDiffBetweenRefs',
+            output: `base: ${baseRef}, head: ${headRef}`
+        });
+    }
+
+    try {
+        // Why: -U flag sets context lines, ... compares merge-base to head
+        const contextFlag = `-U${contextLines}`;
+        const output = execGitCommand(`diff ${contextFlag} ${sanitizedBase}...${sanitizedHead}`);
+
+        logger.debug('git-operations - getDiffBetweenRefs', 'Diff retrieved', {
+            baseRef,
+            headRef,
+            contextLines,
+            diffSize: output.length
+        });
+
+        return output;
+
+    } catch (error) {
+        logger.error('git-operations - getDiffBetweenRefs', 'Failed to get diff', error);
+        throw new GitError('Failed to get diff between refs', {
+            command: `git diff -U${contextLines} ${sanitizedBase}...${sanitizedHead}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Gets commit log between two refs
+ * Why: Shows commit history for PR description and context
+ *
+ * @param {string} baseRef - Base reference
+ * @param {string} [headRef='HEAD'] - Head reference
+ * @param {Object} [options]
+ * @param {string} [options.format='oneline'] - Git log format
+ * @returns {string} Commit log output
+ */
+const getCommitsBetweenRefs = (baseRef, headRef = 'HEAD', { format = 'oneline' } = {}) => {
+    logger.debug('git-operations - getCommitsBetweenRefs', 'Getting commits between refs', {
+        baseRef,
+        headRef,
+        format
+    });
+
+    // Sanitize refs
+    const sanitizedBase = sanitizeBranchName(baseRef);
+    const sanitizedHead = sanitizeBranchName(headRef);
+
+    if (!sanitizedBase || !sanitizedHead) {
+        throw new GitError('Invalid branch reference', {
+            command: 'getCommitsBetweenRefs',
+            output: `base: ${baseRef}, head: ${headRef}`
+        });
+    }
+
+    try {
+        // Why: --format specifies output format, ... shows commits on head not on base
+        const output = execGitCommand(`log --format=${format} ${sanitizedBase}...${sanitizedHead}`);
+
+        if (!output) {
+            logger.debug('git-operations - getCommitsBetweenRefs', 'No commits found', { baseRef, headRef });
+            return '';
+        }
+
+        const commitCount = output.split(/\r?\n/).filter(line => line.length > 0).length;
+
+        logger.debug('git-operations - getCommitsBetweenRefs', 'Commits retrieved', {
+            baseRef,
+            headRef,
+            format,
+            commitCount
+        });
+
+        return output;
+
+    } catch (error) {
+        logger.error('git-operations - getCommitsBetweenRefs', 'Failed to get commits', error);
+        throw new GitError('Failed to get commits between refs', {
+            command: `git log --format=${format} ${sanitizedBase}...${sanitizedHead}`,
+            cause: error
+        });
+    }
+};
+
 export {
     GitError,
     getStagedFiles,
@@ -679,5 +1078,13 @@ export {
     verifyRemoteExists,
     getBranchPushStatus,
     pushBranch,
-    createCommit
+    stageFiles,
+    createCommit,
+    fetchRemote,
+    branchExists,
+    getRemoteBranches,
+    resolveBaseBranch,
+    getChangedFilesBetweenRefs,
+    getDiffBetweenRefs,
+    getCommitsBetweenRefs
 };