claude-git-hooks 2.8.0 → 2.10.0

package/lib/utils/claude-client.js

@@ -23,6 +23,7 @@ import logger from './logger.js';
 import config from '../config.js';
 import { detectClaudeError, formatClaudeError, ClaudeErrorType, isRecoverableError } from './claude-diagnostics.js';
 import { which } from './which-command.js';
+import { recordJsonParseFailure, recordBatchSuccess, rotateTelemetry } from './telemetry.js';
 
 /**
  * Custom error for Claude client failures
@@ -526,10 +527,11 @@ const executeClaudeInteractive = (prompt, { timeout = 300000 } = {}) => new Prom
  * Why: Claude may include markdown formatting or explanatory text around JSON
  *
  * @param {string} response - Raw response from Claude
+ * @param {Object} telemetryContext - Context for telemetry recording (optional)
  * @returns {Object} Parsed JSON object
  * @throws {ClaudeClientError} If no valid JSON found
  */
-const extractJSON = (response) => {
+const extractJSON = (response, telemetryContext = {}) => {
     logger.debug(
         'claude-client - extractJSON',
         'Extracting JSON from response',
@@ -594,16 +596,24 @@ const extractJSON = (response) => {
     }
 
     // No valid JSON found
+    const responsePreview = response.substring(0, 500);
+
     logger.error(
         'claude-client - extractJSON',
         'No valid JSON found in response',
         new ClaudeClientError('No valid JSON in response', {
-            output: response.substring(0, 500) // First 500 chars for debugging
+            output: responsePreview
         })
     );
 
+    // Telemetry is now recorded by withRetry wrapper
     throw new ClaudeClientError('No valid JSON found in Claude response', {
-        output: response.substring(0, 500)
+        context: {
+            response: response,
+            errorInfo: {
+                type: 'JSON_PARSE_ERROR'
+            }
+        }
     });
 };
 
@@ -661,8 +671,8 @@ const saveDebugResponse = async (prompt, response, filename = config.output.debu
 };
 
 /**
- * Wraps an async function with retry logic for recoverable errors
- * Why: Reusable retry logic for Claude CLI operations
+ * Wraps an async function with retry logic for recoverable errors and telemetry tracking
+ * Why: Reusable retry logic for Claude CLI operations with per-attempt telemetry
  *
  * @param {Function} fn - Async function to execute with retry
  * @param {Object} options - Retry options
@@ -670,15 +680,50 @@ const saveDebugResponse = async (prompt, response, filename = config.output.debu
  * @param {number} options.baseRetryDelay - Base delay in ms (default: 2000)
  * @param {number} options.retryCount - Current retry attempt (internal, default: 0)
  * @param {string} options.operationName - Name for logging (default: 'operation')
+ * @param {Object} options.telemetryContext - Context for telemetry recording (optional)
  * @returns {Promise<any>} Result from fn
  * @throws {Error} If fn fails after all retries
  */
-const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount = 0, operationName = 'operation' } = {}) => {
+const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount = 0, operationName = 'operation', telemetryContext = null } = {}) => {
     const retryDelay = baseRetryDelay * Math.pow(2, retryCount);
+    const startTime = Date.now();
 
     try {
-        return await fn();
+        const result = await fn();
+
+        // Record success telemetry if context provided
+        if (telemetryContext) {
+            const duration = Date.now() - startTime;
+            await recordBatchSuccess({
+                ...telemetryContext,
+                duration,
+                retryAttempt: retryCount,
+                totalRetries: maxRetries
+            }).catch(err => {
+                logger.debug('claude-client - withRetry', 'Failed to record success telemetry', err);
+            });
+        }
+
+        return result;
     } catch (error) {
+        // Record failure telemetry if context provided (before retry decision)
+        if (telemetryContext) {
+            const errorType = error.context?.errorInfo?.type || error.name || 'UNKNOWN_ERROR';
+            const errorMessage = error.message || 'Unknown error';
+
+            await recordJsonParseFailure({
+                ...telemetryContext,
+                errorType,
+                errorMessage,
+                retryAttempt: retryCount,
+                totalRetries: maxRetries,
+                responseLength: error.context?.response?.length || 0,
+                responsePreview: error.context?.response?.substring(0, 100) || ''
+            }).catch(err => {
+                logger.debug('claude-client - withRetry', 'Failed to record failure telemetry', err);
+            });
+        }
+
         // Check if error is recoverable and we haven't exceeded retry limit
         const hasContext = !!error.context;
         const hasErrorInfo = !!error.context?.errorInfo;
@@ -714,8 +759,8 @@ const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount
             // Wait before retry
             await new Promise(resolve => setTimeout(resolve, retryDelay));
 
-            // Retry with incremented count
-            return withRetry(fn, { maxRetries, baseRetryDelay, retryCount: retryCount + 1, operationName });
+            // Retry with incremented count and same telemetry context
+            return withRetry(fn, { maxRetries, baseRetryDelay, retryCount: retryCount + 1, operationName, telemetryContext });
         }
 
         // Add retry attempt to error context if not already present
@@ -730,17 +775,25 @@ const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount
 };
 
 /**
- * Executes Claude CLI with retry logic
- * Why: Provides retry capability for executeClaude calls
+ * Executes Claude CLI with retry logic and telemetry tracking
+ * Why: Provides retry capability for executeClaude calls with per-attempt telemetry
  *
  * @param {string} prompt - Prompt text
- * @param {Object} options - Execution options (timeout, allowedTools)
+ * @param {Object} options - Execution options
+ * @param {number} options.timeout - Timeout in milliseconds
+ * @param {Array<string>} options.allowedTools - Allowed tools for Claude
+ * @param {Object} options.telemetryContext - Context for telemetry (fileCount, hook, etc.)
  * @returns {Promise<string>} Claude's response
  */
 const executeClaudeWithRetry = async (prompt, options = {}) => {
+    const { telemetryContext = {}, ...executeOptions } = options;
+
     return withRetry(
-        () => executeClaude(prompt, options),
-        { operationName: 'executeClaude' }
+        () => executeClaude(prompt, executeOptions),
+        {
+            operationName: 'executeClaude',
+            telemetryContext: telemetryContext
+        }
     );
 };
 
@@ -752,17 +805,25 @@ const executeClaudeWithRetry = async (prompt, options = {}) => {
  * @param {Object} options - Analysis options
  * @param {number} options.timeout - Timeout in milliseconds
  * @param {boolean} options.saveDebug - Save response to debug file (default: from config)
+ * @param {Object} options.telemetryContext - Context for telemetry (fileCount, batchSize, etc.)
  * @returns {Promise<Object>} Parsed analysis result
  * @throws {ClaudeClientError} If analysis fails
  */
-const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system.debug } = {}) => {
+const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system.debug, telemetryContext = {} } = {}) => {
+    const startTime = Date.now();
+
     logger.debug(
         'claude-client - analyzeCode',
         'Starting code analysis',
         { promptLength: prompt.length, timeout, saveDebug }
     );
 
-    // Use withRetry to wrap the entire analysis flow
+    // Rotate telemetry files periodically
+    rotateTelemetry().catch(err => {
+        logger.debug('claude-client - analyzeCode', 'Failed to rotate telemetry', err);
+    });
+
+    // Use withRetry to wrap the entire analysis flow (with telemetry tracking)
     return withRetry(
         async () => {
             // Execute Claude CLI
@@ -774,7 +835,9 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system
             }
 
             // Extract and parse JSON
-            const result = extractJSON(response);
+            const result = extractJSON(response, telemetryContext);
+
+            const duration = Date.now() - startTime;
 
             logger.debug(
                 'claude-client - analyzeCode',
@@ -782,13 +845,21 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system
                 {
                     hasApproved: 'approved' in result,
                     hasQualityGate: 'QUALITY_GATE' in result,
-                    blockingIssuesCount: result.blockingIssues?.length ?? 0
+                    blockingIssuesCount: result.blockingIssues?.length ?? 0,
+                    duration
                 }
             );
 
+            // Telemetry is now recorded by withRetry wrapper
             return result;
         },
-        { operationName: 'analyzeCode' }
+        {
+            operationName: 'analyzeCode',
+            telemetryContext: {
+                responseLength: 0, // Will be updated in withRetry
+                ...telemetryContext
+            }
+        }
     );
 };
 
@@ -810,6 +881,7 @@ const chunkArray = (array, size) => {
  * Runs multiple analyzeCode calls in parallel
  * @param {Array<string>} prompts - Array of prompts to analyze
  * @param {Object} options - Same options as analyzeCode
+ * @param {Object} options.telemetryContext - Base telemetry context (will be augmented per batch)
  * @returns {Promise<Array<Object>>} Array of results
  */
 const analyzeCodeParallel = async (prompts, options = {}) => {
@@ -824,7 +896,18 @@ const analyzeCodeParallel = async (prompts, options = {}) => {
     const promises = prompts.map((prompt, index) => {
         console.log(`  ⚡ Launching batch ${index + 1}/${prompts.length}...`);
         logger.debug('claude-client - analyzeCodeParallel', `Starting batch ${index + 1}`);
-        return analyzeCode(prompt, options);
+
+        // Augment telemetry context with batch info
+        const batchTelemetryContext = {
+            ...(options.telemetryContext || {}),
+            batchIndex: index,
+            totalBatches: prompts.length
+        };
+
+        return analyzeCode(prompt, {
+            ...options,
+            telemetryContext: batchTelemetryContext
+        });
     });
 
     console.log('  ⏳ Waiting for all batches to complete...\n');

package/lib/utils/github-api.js

@@ -2,7 +2,7 @@
  * File: github-api.js
  * Purpose: Direct GitHub API integration via Octokit
  *
- * Why Octokit instead of MCP:
+ * Why Octokit:
  * - PR creation is deterministic (no AI judgment needed)
  * - Reliable error handling
  * - No external process dependencies
@@ -11,8 +11,7 @@
  * Token priority:
  * 1. GITHUB_TOKEN env var (CI/CD friendly)
  * 2. GITHUB_PERSONAL_ACCESS_TOKEN env var
- * 3. .claude/settings.local.json → githubToken
- * 4. Claude Desktop config (cross-platform)
+ * 3. .claude/settings.local.json → githubToken (local dev, gitignored)
  */
 
 import { Octokit } from '@octokit/rest';
@@ -21,7 +20,6 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import logger from './logger.js';
-import { findGitHubTokenInDesktopConfig } from './mcp-setup.js';
 
 // Get package info for user agent
 const __filename = fileURLToPath(import.meta.url);
@@ -89,6 +87,89 @@ const loadLocalSettings = () => {
     return {};
 };
 
+/**
+ * Save GitHub token to .claude/settings.local.json
+ * Why: Persist token in gitignored location for local development
+ *
+ * @param {string} token - GitHub Personal Access Token
+ * @returns {Object} { success: boolean, path: string, error?: string }
+ */
+export const saveGitHubToken = (token) => {
+    try {
+        const repoRoot = getRepoRoot();
+        const claudeDir = path.join(repoRoot, '.claude');
+        const settingsPath = path.join(claudeDir, 'settings.local.json');
+
+        logger.debug('github-api - saveGitHubToken', 'Saving token', { settingsPath });
+
+        // Ensure .claude directory exists
+        if (!fs.existsSync(claudeDir)) {
+            fs.mkdirSync(claudeDir, { recursive: true });
+            logger.debug('github-api - saveGitHubToken', 'Created .claude directory');
+        }
+
+        // Load existing settings or create new
+        let settings = {};
+        if (fs.existsSync(settingsPath)) {
+            try {
+                settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            } catch (e) {
+                logger.debug('github-api - saveGitHubToken', 'Invalid existing settings, starting fresh');
+                settings = {};
+            }
+        }
+
+        // Update token
+        settings.githubToken = token;
+
+        // Add comment if new file
+        if (!settings._comment) {
+            settings._comment = 'Local settings - DO NOT COMMIT. This file is gitignored.';
+        }
+
+        // Save settings
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+
+        logger.debug('github-api - saveGitHubToken', 'Token saved successfully');
+
+        return { success: true, path: settingsPath };
+
+    } catch (error) {
+        logger.error('github-api - saveGitHubToken', 'Failed to save token', error);
+        return { success: false, path: null, error: error.message };
+    }
+};
+
+/**
+ * Validate GitHub token format
+ * Why: Catch obvious format errors before API call
+ *
+ * @param {string} token - Token to validate
+ * @returns {Object} { valid: boolean, warning?: string }
+ */
+export const validateTokenFormat = (token) => {
+    if (!token || token.trim() === '') {
+        return { valid: false, warning: 'Token is empty' };
+    }
+
+    const trimmed = token.trim();
+
+    // Valid prefixes for GitHub tokens
+    if (trimmed.startsWith('ghp_') || trimmed.startsWith('github_pat_')) {
+        return { valid: true };
+    }
+
+    // Older token format (40 hex chars)
+    if (/^[a-f0-9]{40}$/i.test(trimmed)) {
+        return { valid: true };
+    }
+
+    return {
+        valid: true, // Still allow, just warn
+        warning: 'Token format looks unusual (expected ghp_... or github_pat_...)'
+    };
+};
+
 /**
  * Get GitHub authentication token
  * Why: Centralized token resolution with multiple fallback sources
@@ -97,7 +178,6 @@ const loadLocalSettings = () => {
  * 1. GITHUB_TOKEN env var (standard for CI/CD)
  * 2. GITHUB_PERSONAL_ACCESS_TOKEN env var (legacy support)
  * 3. .claude/settings.local.json → githubToken (local dev, gitignored)
- * 4. Claude Desktop config (cross-platform GUI users)
  *
  * @returns {string} GitHub token
  * @throws {GitHubAPIError} If no token found
@@ -122,15 +202,6 @@ export const getGitHubToken = () => {
         return localSettings.githubToken;
     }
 
-    // Priority 4: Claude Desktop config
-    const desktopToken = findGitHubTokenInDesktopConfig();
-    if (desktopToken?.token) {
-        logger.debug('github-api - getGitHubToken', 'Using token from Claude Desktop config', {
-            configPath: desktopToken.configPath
-        });
-        return desktopToken.token;
-    }
-
     // No token found
     throw new GitHubAPIError(
         'GitHub token not found. Please configure authentication.',
@@ -139,10 +210,9 @@ export const getGitHubToken = () => {
                 searchedLocations: [
                     'GITHUB_TOKEN env var',
                     'GITHUB_PERSONAL_ACCESS_TOKEN env var',
-                    '.claude/settings.local.json → githubToken',
-                    'Claude Desktop config'
+                    '.claude/settings.local.json → githubToken'
                 ],
-                suggestion: 'Run: claude-hooks setup-github or create .claude/settings.local.json with {"githubToken": "ghp_..."}'
+                suggestion: 'Run: claude-hooks setup-github'
             }
         }
     );