claude-git-hooks 2.35.2 → 2.43.0

package/lib/utils/hooks-verified-marker.js

@@ -0,0 +1,121 @@
+/**
+ * File: hooks-verified-marker.js
+ * Purpose: Manages the .git/.hooks-verified marker file used to coordinate
+ * between pre-commit.js (writes marker on success) and prepare-commit-msg.js
+ * (reads marker, appends Hooks-Verified trailer).
+ *
+ * The marker contains the tree-SHA of the staged content at the time pre-commit
+ * passed. prepare-commit-msg compares it against the current tree-SHA to detect
+ * staging changes between hooks (e.g., user ran `git add` after pre-commit).
+ *
+ * Design:
+ * - No git operations — standalone testable
+ * - Marker file lives inside .git/ (not tracked, per-worktree)
+ * - Permissions 0o600 (defensive, even though .git/ is user-scoped)
+ *
+ * Dependencies:
+ * - fs (sync operations for simplicity — marker is tiny)
+ * - path
+ * - logger
+ */
+
+import fs from 'fs';
+import path from 'path';
+import logger from './logger.js';
+
+/**
+ * Returns the path to the hooks-verified marker file
+ *
+ * @param {string} repoRoot - Absolute path to repository root
+ * @returns {string} Absolute path to .git/.hooks-verified
+ */
+const getMarkerPath = (repoRoot) => path.join(repoRoot, '.git', '.hooks-verified');
+
+/**
+ * Writes the hooks-verified marker file
+ *
+ * @param {string} repoRoot - Absolute path to repository root
+ * @param {string} treeSha - 40-char hex SHA from git write-tree
+ * @param {string} version - Package version (e.g., '2.41.0')
+ * @throws {Error} If .git/ directory doesn't exist or write fails
+ */
+const writeMarker = (repoRoot, treeSha, version) => {
+    const markerPath = getMarkerPath(repoRoot);
+
+    const payload = JSON.stringify({
+        tree: treeSha,
+        timestamp: new Date().toISOString(),
+        version
+    });
+
+    fs.writeFileSync(markerPath, payload, { mode: 0o600 });
+
+    logger.debug('hooks-verified-marker - writeMarker', 'Marker written', {
+        path: markerPath,
+        treeSha
+    });
+};
+
+/**
+ * Reads the hooks-verified marker file
+ *
+ * @param {string} repoRoot - Absolute path to repository root
+ * @returns {Object|null} Parsed marker object, or null if absent/malformed
+ */
+const readMarker = (repoRoot) => {
+    const markerPath = getMarkerPath(repoRoot);
+
+    try {
+        const content = fs.readFileSync(markerPath, 'utf8');
+        const parsed = JSON.parse(content);
+
+        logger.debug('hooks-verified-marker - readMarker', 'Marker read', {
+            tree: parsed.tree
+        });
+
+        return parsed;
+    } catch (err) {
+        if (err.code === 'ENOENT') {
+            logger.debug('hooks-verified-marker - readMarker', 'No marker file found');
+            return null;
+        }
+
+        // Malformed JSON or other read error
+        logger.warning(`Hooks-verified marker is malformed: ${err.message}`);
+        return null;
+    }
+};
+
+/**
+ * Deletes the hooks-verified marker file (best-effort)
+ *
+ * @param {string} repoRoot - Absolute path to repository root
+ */
+const consumeMarker = (repoRoot) => {
+    const markerPath = getMarkerPath(repoRoot);
+
+    try {
+        fs.unlinkSync(markerPath);
+        logger.debug('hooks-verified-marker - consumeMarker', 'Marker consumed');
+    } catch (err) {
+        if (err.code === 'ENOENT') {
+            // Already gone — nothing to do
+            return;
+        }
+        logger.debug('hooks-verified-marker - consumeMarker', 'Could not delete marker', {
+            error: err.message
+        });
+    }
+};
+
+/**
+ * Validates a marker against the current staged tree SHA
+ *
+ * @param {Object|null} marker - Parsed marker from readMarker()
+ * @param {string} currentTreeSha - Current tree SHA from getStagedTreeSha()
+ * @returns {boolean} True if marker is valid and tree SHAs match
+ */
+const validateMarker = (marker, currentTreeSha) =>
+    marker !== null && marker.tree === currentTreeSha;
+
+export { getMarkerPath, writeMarker, readMarker, consumeMarker, validateMarker };

package/lib/utils/interactive-ui.js

@@ -267,7 +267,7 @@ export const showSpinner = (message) => {
  * @param {string} message - Success message
  */
 export const showSuccess = (message) => {
-    console.log(`✅ ${message}`);
+    logger.success(message);
 };
 
 /**
@@ -275,7 +275,7 @@ export const showSuccess = (message) => {
  * @param {string} message - Error message
  */
 export const showError = (message) => {
-    console.log(`❌ ${message}`);
+    logger.error('interactive-ui', message);
 };
 
 /**
@@ -283,7 +283,7 @@ export const showError = (message) => {
  * @param {string} message - Warning message
  */
 export const showWarning = (message) => {
-    console.log(`⚠️  ${message}`);
+    logger.warning(message);
 };
 
 /**
@@ -291,7 +291,7 @@ export const showWarning = (message) => {
  * @param {string} message - Info message
  */
 export const showInfo = (message) => {
-    console.log(`ℹ️  ${message}`);
+    logger.info(message);
 };
 
 /**

package/lib/utils/judge.js

@@ -28,7 +28,7 @@ import logger from './logger.js';
 import { recordMetric } from './metrics.js';
 
 const JUDGE_DEFAULT_MODEL = 'sonnet';
-const JUDGE_TIMEOUT = 180000;
+const JUDGE_TIMEOUT = 360000;
 
 /**
  * Applies a single search/replace fix to a file and stages it
@@ -102,7 +102,7 @@ const applyFix = async (fix, repoRoot) => {
  * @param {Object} config - Application config
  * @returns {Promise<{fixedCount: number, falsePositiveCount: number, remainingIssues: Array, verdicts: Array}>}
  */
-const judgeAndFix = async (analysisResult, filesData, config) => {
+const judgeAndFix = async (analysisResult, filesData, config, { headless = false } = {}) => {
     const model = config.judge?.model || JUDGE_DEFAULT_MODEL;
     const repoRoot = getRepoRoot();
 
@@ -135,7 +135,8 @@ const judgeAndFix = async (analysisResult, filesData, config) => {
     // Call LLM
     const response = await executeClaudeWithRetry(prompt, {
         model,
-        timeout: JUDGE_TIMEOUT
+        timeout: JUDGE_TIMEOUT,
+        headless
     });
 
     const parsed = extractJSON(response);

package/lib/utils/langfuse-tracer.js

@@ -0,0 +1,156 @@
+/**
+ * File: langfuse-tracer.js
+ * Purpose: Optional Langfuse integration for headless SDK calls.
+ *
+ * Mirrors Lumiere's observability/langfuse_tracer.py — same field names,
+ * same metadata conventions, same graceful degradation pattern.
+ *
+ * Disabled by default. Activate via env vars:
+ *   LANGFUSE_ENABLED=true
+ *   LANGFUSE_SECRET_KEY=sk-lf-...
+ *   LANGFUSE_PUBLIC_KEY=pk-lf-...
+ *   LANGFUSE_HOST=https://cloud.langfuse.com  (optional, default shown)
+ *
+ * The `langfuse` npm package is lazy-loaded (same pattern as @anthropic-ai/sdk).
+ * It is NOT listed in package.json — expected to be installed in the ECS/CI
+ * environment where headless mode runs.
+ */
+
+import logger from './logger.js';
+import { calculateCost } from './cost-tracker.js';
+
+let _client = null;
+let _enabled = null;
+
+/**
+ * Check whether Langfuse tracing is enabled and credentials are present.
+ * Result is cached after first evaluation.
+ *
+ * @returns {boolean}
+ */
+function isEnabled() {
+    if (_enabled !== null) return _enabled;
+    _enabled =
+        process.env.LANGFUSE_ENABLED === 'true' &&
+        !!process.env.LANGFUSE_SECRET_KEY &&
+        !!process.env.LANGFUSE_PUBLIC_KEY;
+    return _enabled;
+}
+
+/**
+ * Lazily initialize the Langfuse client. Returns null when disabled or on any failure.
+ *
+ * @returns {Promise<Object|null>}
+ */
+async function _getClient() {
+    if (_client) return _client;
+    if (!isEnabled()) return null;
+
+    try {
+        const { Langfuse } = await import('langfuse');
+        _client = new Langfuse({
+            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+            secretKey: process.env.LANGFUSE_SECRET_KEY,
+            baseUrl: process.env.LANGFUSE_HOST || 'https://cloud.langfuse.com'
+        });
+        logger.debug('langfuse-tracer', 'Langfuse client initialized');
+        return _client;
+    } catch (err) {
+        logger.warning(`langfuse-tracer: failed to initialize — ${err.message}`);
+        _enabled = false;
+        return null;
+    }
+}
+
+/**
+ * Record a single LLM generation in Langfuse.
+ *
+ * Creates a trace (named `claude_hooks`) with one nested generation.
+ * Metadata field names match Lumiere's orchestrator.py for cross-repo
+ * dashboard consistency. All metadata values are strings (Langfuse requirement).
+ *
+ * @param {Object} params
+ * @param {string} params.name - Generation name (e.g. 'executeClaude')
+ * @param {string} params.model - Full Anthropic model ID
+ * @param {string} [params.input] - Prompt text (optional, can be large)
+ * @param {string} [params.output] - Response text (optional)
+ * @param {Object} params.usage - Token counts from SDK response
+ * @param {number} params.usage.input_tokens
+ * @param {number} params.usage.output_tokens
+ * @param {number} [params.usage.cache_creation_input_tokens=0]
+ * @param {number} [params.usage.cache_read_input_tokens=0]
+ * @param {number} [params.durationMs=0] - Wall-clock milliseconds
+ */
+async function traceGeneration({ name, model, input, output, usage, durationMs = 0 }) {
+    const client = await _getClient();
+    if (!client) return;
+
+    try {
+        const inputTokens = usage.input_tokens || 0;
+        const outputTokens = usage.output_tokens || 0;
+        const cacheCreation = usage.cache_creation_input_tokens || 0;
+        const cacheRead = usage.cache_read_input_tokens || 0;
+
+        const totalCost = calculateCost({
+            tokens_input: inputTokens,
+            tokens_output: outputTokens,
+            model,
+            cache_creation: cacheCreation,
+            cache_read: cacheRead
+        });
+
+        const trace = client.trace({
+            name: 'claude_hooks',
+            tags: ['claude-hooks'],
+            metadata: { source: 'claude-hooks' }
+        });
+
+        trace.generation({
+            name,
+            model,
+            input: input !== undefined ? input : undefined,
+            output: output !== undefined ? output : undefined,
+            usage: {
+                input: inputTokens + cacheCreation + cacheRead,
+                output: outputTokens,
+                total: inputTokens + cacheCreation + cacheRead + outputTokens
+            },
+            metadata: {
+                tokens_input_regular: String(inputTokens),
+                cache_creation_tokens: String(cacheCreation),
+                cache_read_tokens: String(cacheRead),
+                total_cost_usd: String(totalCost),
+                duration_ms: String(durationMs),
+                source: 'claude-hooks'
+            }
+        });
+
+        logger.debug('langfuse-tracer', 'Generation recorded', { name, model, totalCost });
+    } catch (err) {
+        logger.warning(`langfuse-tracer: failed to record generation — ${err.message}`);
+    }
+}
+
+/**
+ * Flush pending Langfuse events. Call at the end of a command/analysis
+ * to ensure data is sent before the process exits.
+ */
+async function flush() {
+    if (!_client) return;
+    try {
+        await _client.flushAsync();
+        logger.debug('langfuse-tracer', 'Flushed');
+    } catch (err) {
+        logger.warning(`langfuse-tracer: flush failed — ${err.message}`);
+    }
+}
+
+/**
+ * Reset client state — for testing only.
+ */
+function _resetClient() {
+    _client = null;
+    _enabled = null;
+}
+
+export { isEnabled, traceGeneration, flush, _getClient, _resetClient };

package/lib/utils/linter-runner.js

@@ -25,6 +25,7 @@ import {
     displayToolResult
 } from './tool-runner.js';
 import { getRepoRoot } from './git-operations.js';
+import { which } from './which-command.js';
 import { fetchRemoteConfig } from './remote-config.js';
 import logger from './logger.js';
 
@@ -324,7 +325,7 @@ export const LINTER_TOOLS = {
         installHint: 'Add spotless-maven-plugin to pom.xml (see https://github.com/diffplug/spotless)',
         extensions: ['.java'],
         parseOutput: parseSpotlessOutput,
-        timeout: 60000,
+        timeout: 120000,
         // Run per-file to avoid | (pipe) in regex on Windows.
         // filesToSpotlessRegex joins files with | for regex alternation.
         // cmd.exe interprets | as a pipe at every expansion level —
@@ -474,9 +475,13 @@ export async function runLinters(files, config, presetName = 'default') {
             }
         }
 
+        // Use the higher of config timeout and tool-specific timeout.
+        // Spotless (120s) should not be silently capped to the config default (30s).
+        const effectiveTimeout = Math.max(timeout, effectiveToolDef.timeout || 0);
+
         const toolOpts = {
             autoFix,
-            timeout,
+            timeout: effectiveTimeout,
             restage: true,
             localBin: availability.localBin,
             toolCwd: availability.configDir
@@ -487,9 +492,29 @@ export async function runLinters(files, config, presetName = 'default') {
         // ^ escaping is consumed at the first parse, and %VAR% expansion in batch
         // scripts (mvn.cmd) re-exposes unescaped | to a second parse.
         // Running per-file ensures each invocation has a single-file regex (no |).
-        if (effectiveToolDef.perFile && matchingFiles.length > 1) {
+        //
+        // However, per-file mode is ONLY needed when the command routes through
+        // cmd.exe (.cmd/.bat files). Direct executables and bash scripts (e.g.,
+        // mvnw) pass args to the process directly — | is never interpreted as a pipe.
+        // Batch mode avoids N separate JVM startups, which is critical for Spotless
+        // on Windows/WSL where each startup adds significant overhead.
+        let needsPerFile = effectiveToolDef.perFile && matchingFiles.length > 1;
+        if (needsPerFile) {
+            const resolvedCmd = effectiveToolDef.command.includes(path.sep)
+                ? effectiveToolDef.command
+                : (which(effectiveToolDef.command) || effectiveToolDef.command);
+            if (!/\.(cmd|bat)$/i.test(resolvedCmd)) {
+                needsPerFile = false;
+                logger.debug('linter-runner - runLinters',
+                    `${effectiveToolDef.name} command bypasses cmd.exe, using batch mode`,
+                    { command: resolvedCmd });
+            }
+        }
+
+        if (needsPerFile) {
             logger.debug('linter-runner - runLinters',
-                `Running ${effectiveToolDef.name} per-file`, { fileCount: matchingFiles.length });
+                `Running ${effectiveToolDef.name} per-file (cmd.exe path)`,
+                { fileCount: matchingFiles.length });
 
             const perFileResults = matchingFiles.map((file) =>
                 runToolWithAutoFix(effectiveToolDef, [file], toolOpts)

package/lib/utils/logger.js

@@ -17,6 +17,7 @@
 class Logger {
     constructor({ debugMode = false } = {}) {
         this.debugMode = debugMode;
+        this.jsonMode = false;
         this.colors = {
             reset: '\x1b[0m',
             red: '\x1b[31m',
@@ -34,7 +35,8 @@ class Logger {
      * @param {string} message - Simple message for end users
      */
     info(message) {
-        console.log(`${this.colors.blue}ℹ️  ${message}${this.colors.reset}`);
+        const out = this.jsonMode ? console.error : console.log;
+        out(`${this.colors.blue}ℹ️  ${message}${this.colors.reset}`);
     }
 
     /**
@@ -44,7 +46,8 @@ class Logger {
      * @param {string} message - Success message
      */
     success(message) {
-        console.log(`${this.colors.green}✅ ${message}${this.colors.reset}`);
+        const out = this.jsonMode ? console.error : console.log;
+        out(`${this.colors.green}✅ ${message}${this.colors.reset}`);
     }
 
     /**
@@ -54,7 +57,8 @@ class Logger {
      * @param {string} message - Warning message
      */
     warning(message) {
-        console.log(`${this.colors.yellow}⚠️  ${message}${this.colors.reset}`);
+        const out = this.jsonMode ? console.error : console.log;
+        out(`${this.colors.yellow}⚠️  ${message}${this.colors.reset}`);
     }
 
     /**
@@ -71,13 +75,14 @@ class Logger {
     debug(context, message, data = {}) {
         if (!this.debugMode) return;
 
+        const out = this.jsonMode ? console.error : console.log;
         const timestamp = new Date().toISOString();
-        console.log(
+        out(
             `${this.colors.gray}[DEBUG ${timestamp}] [${context}] ${message}${this.colors.reset}`
         );
 
         if (Object.keys(data).length > 0) {
-            console.log(this.colors.gray, JSON.stringify(data, null, 2), this.colors.reset);
+            out(this.colors.gray, JSON.stringify(data, null, 2), this.colors.reset);
         }
     }
 
@@ -137,6 +142,26 @@ class Logger {
     isDebugMode() {
         return this.debugMode;
     }
+
+    /**
+     * Set JSON mode dynamically
+     * Why: When active, info/success/warning/debug write to stderr so stdout
+     * is reserved exclusively for structured JSON output.
+     *
+     * @param {boolean} enabled - Whether to enable JSON mode
+     */
+    setJSONMode(enabled) {
+        this.jsonMode = !!enabled;
+    }
+
+    /**
+     * Check if JSON mode is enabled
+     *
+     * @returns {boolean} True if JSON mode is active
+     */
+    isJSONMode() {
+        return this.jsonMode;
+    }
 }
 
 // Export singleton instance

package/lib/utils/pr-metadata-engine.js

@@ -371,7 +371,7 @@ export const getBranchContext = async (targetBranch) => {
 export const generatePRMetadata = async (context, options = {}) => {
     const config = await getConfig();
     const configTimeout = config.analysis?.timeout;
-    const { timeout = configTimeout || DEFAULTS.timeout, hook = 'pr-metadata' } = options;
+    const { timeout = configTimeout || DEFAULTS.timeout, hook = 'pr-metadata', headless = false, costTracker = null } = options;
 
     logger.debug('pr-metadata-engine - generatePRMetadata', 'Generating PR metadata', {
         filesCount: context.filesCount,
@@ -411,7 +411,9 @@ export const generatePRMetadata = async (context, options = {}) => {
         // Call Claude with retry logic
         const response = await executeClaudeWithRetry(prompt, {
             timeout,
-            telemetryContext
+            telemetryContext,
+            headless,
+            costTracker
         });
 
         logger.debug('pr-metadata-engine - generatePRMetadata', 'Claude response received', {

package/lib/utils/tool-runner.js

@@ -461,8 +461,9 @@ export function runTool(toolDef, files, options = {}) {
             const parsed = toolDef.parseOutput(err.stdout);
             result.errors = parsed.errors || [];
             result.warnings = parsed.warnings || [];
-        } else if (err.killed) {
-            // Timeout
+        } else if (err.killed || err.code === 'ETIMEDOUT') {
+            // Timeout — err.killed for Node.js timeout, ETIMEDOUT for OS-level
+            // spawn timeout (common on Windows when cmd.exe → JVM startup is slow)
             logger.warning(`${toolDef.name} timed out after ${timeout}ms`);
             result.errors.push({
                 file: '',
@@ -543,7 +544,7 @@ export function runToolFix(toolDef, files, options = {}) {
     try {
         execFileSync(exec.command, exec.args, execOptions);
     } catch (err) {
-        if (err.killed) {
+        if (err.killed || err.code === 'ETIMEDOUT') {
             logger.warning(`${toolDef.name} auto-fix timed out`);
             return { fixedFiles: [], fixedCount: 0 };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.35.2",
+    "version": "2.43.0",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {
@@ -60,7 +60,9 @@
         "LICENSE"
     ],
     "dependencies": {
-        "@octokit/rest": "^21.0.0"
+        "@anthropic-ai/sdk": "^0.91.0",
+        "@octokit/rest": "^21.0.0",
+        "langfuse": "^3.38.20"
     },
     "devDependencies": {
         "@types/jest": "^29.5.0",

package/templates/CUSTOMIZATION_GUIDE.md

@@ -284,7 +284,7 @@ cd python-django
     "analysis": {
         "maxFileSize": 1000000,
         "maxFiles": 12,
-        "timeout": 180000
+        "timeout": 360000
     },
     "subagents": {
         "enabled": true,
@@ -308,7 +308,7 @@ cd python-django
   analysis: {
     maxFileSize: 1000000,  // 1MB
     maxFiles: 30,
-    timeout: 180000        // 3 minutes
+    timeout: 360000        // 6 minutes
   },
   subagents: {
     enabled: true,