claude-git-hooks 1.5.5 → 2.1.0

package/lib/utils/claude-client.js

@@ -0,0 +1,373 @@
+/**
+ * File: claude-client.js
+ * Purpose: Interface with Claude CLI for code analysis
+ *
+ * Key responsibilities:
+ * - Execute Claude CLI with prompts
+ * - Parse JSON responses from Claude
+ * - Handle errors and timeouts
+ * - Optional debug output
+ *
+ * Dependencies:
+ * - child_process: For executing Claude CLI
+ * - fs/promises: For debug file writing
+ * - logger: Debug and error logging
+ */
+
+import { spawn, execSync } from 'child_process';
+import fs from 'fs/promises';
+import os from 'os';
+import logger from './logger.js';
+
+/**
+ * Custom error for Claude client failures
+ */
+class ClaudeClientError extends Error {
+    constructor(message, { cause, output, context } = {}) {
+        super(message);
+        this.name = 'ClaudeClientError';
+        this.cause = cause;
+        this.output = output;
+        this.context = context;
+    }
+}
+
+/**
+ * Detect if running on Windows
+ * Why: Need to use 'wsl claude' instead of 'claude' on Windows
+ */
+const isWindows = () => {
+    return os.platform() === 'win32' || process.env.OS === 'Windows_NT';
+};
+
+/**
+ * Check if WSL is available on Windows
+ * Why: Windows users need WSL to run Claude CLI, verify it exists before attempting
+ *
+ * @returns {boolean} True if WSL is available
+ */
+const isWSLAvailable = () => {
+    if (!isWindows()) {
+        return true; // Not Windows, WSL check not needed
+    }
+
+    try {
+        // Try to run wsl --version to check if WSL is installed
+        execSync('wsl --version', { stdio: 'ignore', timeout: 3000 });
+        return true;
+    } catch (error) {
+        logger.debug('claude-client - isWSLAvailable', 'WSL not available', error);
+        return false;
+    }
+};
+
+/**
+ * Get Claude command configuration for current platform
+ * Why: On Windows, Claude CLI runs in WSL, so we need 'wsl' as command and 'claude' as arg
+ *
+ * @returns {Object} { command, args } - Command and base arguments
+ * @throws {ClaudeClientError} If Windows without WSL
+ */
+const getClaudeCommand = () => {
+    if (isWindows()) {
+        if (!isWSLAvailable()) {
+            throw new ClaudeClientError('WSL is required on Windows but not found', {
+                context: {
+                    platform: 'Windows',
+                    suggestion: 'Install WSL: https://docs.microsoft.com/en-us/windows/wsl/install'
+                }
+            });
+        }
+        return { command: 'wsl', args: ['claude'] };
+    }
+    return { command: 'claude', args: [] };
+};
+
+/**
+ * Executes Claude CLI with a prompt
+ * Why: Centralized Claude CLI execution with error handling and timeout
+ * Why platform detection: On Windows, must use 'wsl claude' to access Claude in WSL
+ *
+ * @param {string} prompt - Prompt text to send to Claude
+ * @param {Object} options - Execution options
+ * @param {number} options.timeout - Timeout in milliseconds (default: 120000 = 2 minutes)
+ * @returns {Promise<string>} Claude's response
+ * @throws {ClaudeClientError} If execution fails or times out
+ */
+const executeClaude = (prompt, { timeout = 120000 } = {}) => {
+    return new Promise((resolve, reject) => {
+        // Get platform-specific command
+        const { command, args } = getClaudeCommand();
+        const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command;
+
+        logger.debug(
+            'claude-client - executeClaude',
+            'Executing Claude CLI',
+            { promptLength: prompt.length, timeout, command: fullCommand, isWindows: isWindows() }
+        );
+
+        const startTime = Date.now();
+
+        // Why: Use spawn instead of exec to handle large prompts and responses
+        // spawn streams data, exec buffers everything in memory
+        const claude = spawn(command, args, {
+            stdio: ['pipe', 'pipe', 'pipe'] // stdin, stdout, stderr
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        // Collect stdout
+        claude.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+
+        // Collect stderr
+        claude.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+
+        // Handle process completion
+        claude.on('close', (code) => {
+            const duration = Date.now() - startTime;
+
+            if (code === 0) {
+                logger.debug(
+                    'claude-client - executeClaude',
+                    'Claude CLI execution successful',
+                    { duration, outputLength: stdout.length }
+                );
+                resolve(stdout);
+            } else {
+                logger.error(
+                    'claude-client - executeClaude',
+                    `Claude CLI failed with exit code ${code}`,
+                    new ClaudeClientError('Claude CLI execution failed', {
+                        output: { stdout, stderr },
+                        context: { exitCode: code, duration }
+                    })
+                );
+
+                reject(new ClaudeClientError('Claude CLI execution failed', {
+                    output: { stdout, stderr },
+                    context: { exitCode: code, duration }
+                }));
+            }
+        });
+
+        // Handle errors
+        claude.on('error', (error) => {
+            logger.error(
+                'claude-client - executeClaude',
+                'Failed to spawn Claude CLI process',
+                error
+            );
+
+            reject(new ClaudeClientError('Failed to spawn Claude CLI', {
+                cause: error,
+                context: { command, args }
+            }));
+        });
+
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            claude.kill();
+            logger.error(
+                'claude-client - executeClaude',
+                'Claude CLI execution timed out',
+                new ClaudeClientError('Claude CLI timeout', {
+                    context: { timeout }
+                })
+            );
+
+            reject(new ClaudeClientError('Claude CLI execution timed out', {
+                context: { timeout }
+            }));
+        }, timeout);
+
+        // Clear timeout if process completes
+        claude.on('close', () => clearTimeout(timeoutId));
+
+        // Write prompt to stdin
+        // Why: Claude CLI reads prompt from stdin, not command arguments
+        try {
+            claude.stdin.write(prompt);
+            claude.stdin.end();
+        } catch (error) {
+            logger.error(
+                'claude-client - executeClaude',
+                'Failed to write prompt to Claude CLI stdin',
+                error
+            );
+
+            reject(new ClaudeClientError('Failed to write prompt', {
+                cause: error
+            }));
+        }
+    });
+};
+
+/**
+ * Extracts JSON from Claude's response
+ * Why: Claude may include markdown formatting or explanatory text around JSON
+ *
+ * @param {string} response - Raw response from Claude
+ * @returns {Object} Parsed JSON object
+ * @throws {ClaudeClientError} If no valid JSON found
+ */
+const extractJSON = (response) => {
+    logger.debug(
+        'claude-client - extractJSON',
+        'Extracting JSON from response',
+        { responseLength: response.length }
+    );
+
+    // Why: Try multiple patterns to find JSON
+    // Pattern 1: JSON in markdown code block
+    const markdownMatch = response.match(/```json\s*([\s\S]*?)\s*```/);
+    if (markdownMatch) {
+        try {
+            const json = JSON.parse(markdownMatch[1]);
+            logger.debug('claude-client - extractJSON', 'JSON extracted from markdown block');
+            return json;
+        } catch (error) {
+            // Continue to next pattern
+        }
+    }
+
+    // Pattern 2: JSON object (curly braces)
+    const jsonMatch = response.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        try {
+            const json = JSON.parse(jsonMatch[0]);
+            logger.debug('claude-client - extractJSON', 'JSON extracted from response body');
+            return json;
+        } catch (error) {
+            // Continue to next pattern
+        }
+    }
+
+    // Pattern 3: Extract lines starting with { until matching }
+    const lines = response.split('\n');
+    let jsonStartIndex = -1;
+    let braceCount = 0;
+    let jsonLines = [];
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+
+        if (jsonStartIndex === -1 && line.startsWith('{')) {
+            jsonStartIndex = i;
+            braceCount = (line.match(/{/g) || []).length - (line.match(/}/g) || []).length;
+            jsonLines.push(line);
+        } else if (jsonStartIndex !== -1) {
+            jsonLines.push(line);
+            braceCount += (line.match(/{/g) || []).length - (line.match(/}/g) || []).length;
+
+            if (braceCount === 0) {
+                const jsonText = jsonLines.join('\n');
+                try {
+                    const json = JSON.parse(jsonText);
+                    logger.debug('claude-client - extractJSON', 'JSON extracted using line matching');
+                    return json;
+                } catch (error) {
+                    // Try next occurrence
+                    jsonStartIndex = -1;
+                    jsonLines = [];
+                }
+            }
+        }
+    }
+
+    // No valid JSON found
+    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
+        })
+    );
+
+    throw new ClaudeClientError('No valid JSON found in Claude response', {
+        output: response.substring(0, 500)
+    });
+};
+
+/**
+ * Saves response to debug file
+ * Why: Helps troubleshoot issues with Claude responses
+ *
+ * @param {string} response - Raw response to save
+ * @param {string} filename - Debug filename (default: 'debug-claude-response.json')
+ */
+const saveDebugResponse = async (response, filename = 'debug-claude-response.json') => {
+    try {
+        await fs.writeFile(filename, response, 'utf8');
+        logger.debug(
+            'claude-client - saveDebugResponse',
+            `Debug response saved to ${filename}`
+        );
+    } catch (error) {
+        logger.error(
+            'claude-client - saveDebugResponse',
+            'Failed to save debug response',
+            error
+        );
+    }
+};
+
+/**
+ * Analyzes code using Claude CLI
+ * Why: High-level interface that handles execution, parsing, and debug
+ *
+ * @param {string} prompt - Analysis prompt
+ * @param {Object} options - Analysis options
+ * @param {number} options.timeout - Timeout in milliseconds
+ * @param {boolean} options.saveDebug - Save response to debug file (default: from DEBUG env)
+ * @returns {Promise<Object>} Parsed analysis result
+ * @throws {ClaudeClientError} If analysis fails
+ */
+const analyzeCode = async (prompt, { timeout = 120000, saveDebug = process.env.DEBUG === 'true' } = {}) => {
+    logger.debug(
+        'claude-client - analyzeCode',
+        'Starting code analysis',
+        { promptLength: prompt.length, timeout, saveDebug }
+    );
+
+    try {
+        // Execute Claude CLI
+        const response = await executeClaude(prompt, { timeout });
+
+        // Save debug if requested
+        if (saveDebug) {
+            await saveDebugResponse(response);
+        }
+
+        // Extract and parse JSON
+        const result = extractJSON(response);
+
+        logger.debug(
+            'claude-client - analyzeCode',
+            'Analysis complete',
+            {
+                hasApproved: 'approved' in result,
+                hasQualityGate: 'QUALITY_GATE' in result,
+                blockingIssuesCount: result.blockingIssues?.length ?? 0
+            }
+        );
+
+        return result;
+
+    } catch (error) {
+        logger.error('claude-client - analyzeCode', 'Code analysis failed', error);
+        throw error;
+    }
+};
+
+export {
+    ClaudeClientError,
+    executeClaude,
+    extractJSON,
+    saveDebugResponse,
+    analyzeCode
+};