claude-git-hooks 2.35.3 → 2.43.0

package/lib/commands/helpers.js

@@ -19,6 +19,7 @@ import https from 'https';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { getRunningWSLDistros } from '../utils/claude-client.js';
+import logger from '../utils/logger.js';
 
 // Why: ES6 modules don't have __dirname, need to recreate it
 const __filename = fileURLToPath(import.meta.url);
@@ -38,20 +39,24 @@ export function log(message, color = 'reset') {
 }
 
 export function error(message) {
-    console.error(`${colors.red}❌ ${message}${colors.reset}`);
+    logger.error('helpers', message);
+}
+
+export function fatal(message) {
+    logger.error('helpers', message);
     process.exit(1);
 }
 
 export function success(message) {
-    log(`✅ ${message}`, 'green');
+    logger.success(message);
 }
 
 export function info(message) {
-    log(`ℹ️  ${message}`, 'blue');
+    logger.info(message);
 }
 
 export function warning(message) {
-    log(`⚠️  ${message}`, 'yellow');
+    logger.warning(message);
 }
 
 /**

package/lib/commands/hooks.js

@@ -5,7 +5,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { error, success, info, warning, checkGitRepo, getGitHooksPath } from './helpers.js';
+import { error, fatal, success, info, warning, checkGitRepo, getGitHooksPath } from './helpers.js';
 import { removeCompletions } from './install.js';
 
 /**
@@ -14,7 +14,7 @@ import { removeCompletions } from './install.js';
  */
 export function runEnable(hookName) {
     if (!checkGitRepo()) {
-        error('You are not in a Git repository.');
+        fatal('You are not in a Git repository.');
     }
 
     const hooksDir = getGitHooksPath();
@@ -41,7 +41,7 @@ export function runEnable(hookName) {
  */
 export function runDisable(hookName) {
     if (!checkGitRepo()) {
-        error('You are not in a Git repository.');
+        fatal('You are not in a Git repository.');
     }
 
     const hooksDir = getGitHooksPath();
@@ -67,7 +67,7 @@ export function runDisable(hookName) {
  */
 export function runStatus() {
     if (!checkGitRepo()) {
-        error('You are not in a Git repository.');
+        fatal('You are not in a Git repository.');
     }
 
     info('Claude Git Hooks status:\n');
@@ -128,7 +128,7 @@ export function runStatus() {
  */
 export function runUninstall() {
     if (!checkGitRepo()) {
-        error('You are not in a Git repository.');
+        fatal('You are not in a Git repository.');
     }
 
     info('Uninstalling Claude Git Hooks...');

package/lib/commands/install.js

@@ -18,6 +18,7 @@ import os from 'os';
 import readline from 'readline';
 import {
     error,
+    fatal,
     success,
     info,
     warning,
@@ -176,7 +177,7 @@ async function checkAndInstallDependencies(skipAuth = false) {
         const nodeVersion = execSync('node --version', { encoding: 'utf8' }).trim();
         success(`Node.js ${nodeVersion}`);
     } catch (e) {
-        error('Node.js is not installed. Install Node.js and try again.');
+        fatal('Node.js is not installed. Install Node.js and try again.');
     }
 
     // Check npm
@@ -184,7 +185,7 @@ async function checkAndInstallDependencies(skipAuth = false) {
         const npmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
         success(`npm ${npmVersion}`);
     } catch (e) {
-        error('npm is not installed.');
+        fatal('npm is not installed.');
     }
 
     // Check Maven (optional — needed for backend/fullstack presets with Spotless)
@@ -205,7 +206,7 @@ async function checkAndInstallDependencies(skipAuth = false) {
         const gitVersion = execSync('git --version', { encoding: 'utf8' }).trim();
         success(`${gitVersion}`);
     } catch (e) {
-        error('Git is not installed. Install Git and try again.');
+        fatal('Git is not installed. Install Git and try again.');
     }
 
     // v2.0.0+: Unix tools (sed, awk, grep, etc.) no longer needed (pure Node.js implementation)
@@ -387,20 +388,30 @@ async function autoMigrateConfig(newConfigPath, backupConfigPath) {
  */
 export async function runInstall(args) {
     if (!checkGitRepo()) {
-        error(
+        fatal(
             'You are not in a Git repository. Please run this command from the root of a repository.'
         );
     }
 
     const isForce = args.includes('--force');
     const skipAuth = args.includes('--skip-auth');
+    const isHeadless = args.includes('--headless');
+    const verifySdk = args.includes('--verify-sdk');
 
-    // Check for updates (unless --skip-auth flag)
-    if (!skipAuth && !isForce) {
+    if (skipAuth) {
+        warning('--skip-auth is deprecated. Use --headless for full CI/container mode.');
+    }
+
+    const skipVersionCheck = skipAuth || isHeadless;
+
+    // Check for updates (unless --skip-auth, --headless, or --force flag)
+    if (!skipVersionCheck && !isForce) {
         await checkVersionAndPromptUpdate();
     }
 
-    if (isForce) {
+    if (isHeadless) {
+        info('Installing Claude Git Hooks (headless mode)...');
+    } else if (isForce) {
         info('Installing Claude Git Hooks (force mode)...');
     } else {
         info('Installing Claude Git Hooks...');
@@ -408,7 +419,12 @@ export async function runInstall(args) {
 
     // v2.0.0+: No sudo needed (pure Node.js, no system packages required)
     // Check dependencies
-    await checkAndInstallDependencies(skipAuth);
+    if (!isHeadless) {
+        await checkAndInstallDependencies(skipAuth);
+    } else {
+        // Headless: skip Claude CLI/auth checks and Maven — CI manages its own deps
+        info('Skipping dependency checks (headless mode)');
+    }
 
     const templatesPath = getTemplatesPath();
     const hooksPath = getGitHooksPath();
@@ -658,33 +674,66 @@ export async function runInstall(args) {
         info('settings.local.json created (add your GitHub token here)');
     }
 
-    // Configure Git
-    configureGit();
+    // Configure Git — skipped in headless to avoid mutating CI git config
+    if (!isHeadless) {
+        configureGit();
+    }
 
-    // Update .gitignore
-    updateGitignore();
+    // Update .gitignore — skipped in headless: CI repos manage .gitignore explicitly
+    if (!isHeadless) {
+        updateGitignore();
+    }
 
-    // Install shell completions
-    installCompletions();
+    // Install shell completions — skipped in headless: shell completions are useless in CI
+    if (!isHeadless) {
+        installCompletions();
+    }
 
-    // Check linter toolchain availability for the selected preset
-    try {
-        const config = await getConfig();
-        const presetName = config.preset || 'default';
-        if (config.linting?.enabled !== false) {
-            const { checkLinterAvailability } = await import('../utils/linter-runner.js');
-            await checkLinterAvailability(presetName);
+    // Check linter toolchain availability — skipped in headless: linter availability is a CI concern
+    if (!isHeadless) {
+        try {
+            const config = await getConfig();
+            const presetName = config.preset || 'default';
+            if (config.linting?.enabled !== false) {
+                const { checkLinterAvailability } = await import('../utils/linter-runner.js');
+                await checkLinterAvailability(presetName);
+            }
+        } catch {
+            // Non-fatal — linter check failure should not block installation
         }
-    } catch {
-        // Non-fatal — linter check failure should not block installation
     }
 
-    success('Claude Git Hooks installed successfully! 🎉');
-    console.log('\nRun claude-hooks --help to see all available commands.');
+    if (isHeadless) {
+        success('claude-hooks installed (headless mode).');
+    } else {
+        success('Claude Git Hooks installed successfully! 🎉');
+        console.log('\nRun claude-hooks --help to see all available commands.');
+
+        // Run GitHub token setup
+        console.log('');
+        await runSetupGitHub();
+    }
 
-    // Run GitHub token setup
-    console.log('');
-    await runSetupGitHub();
+    // Optional SDK verification — opt-in, never automatic
+    if (verifySdk) {
+        info('Verifying SDK connectivity (1-token ping)...');
+        try {
+            const { verifySDKConnection } = await import('../utils/claude-client.js');
+            const result = await verifySDKConnection();
+            if (result.ok) {
+                success(`SDK verified: ${result.usage.input_tokens} in / ${result.usage.output_tokens} out tokens.`);
+            } else {
+                throw new Error(result.error);
+            }
+        } catch (sdkErr) {
+            if (isHeadless) {
+                error(`SDK verification failed: ${sdkErr.message}`);
+                process.exit(1);
+            } else {
+                warning(`SDK verification failed: ${sdkErr.message}. Install completed but SDK is not reachable.`);
+            }
+        }
+    }
 }
 
 // ── Shell completion generation ──────────────────────────────────────────────

package/lib/commands/lint.js

@@ -8,6 +8,7 @@
  *   claude-hooks lint src/ lib/utils/          # multiple directories
  *   claude-hooks lint file1.js file2.java      # specific files
  *   claude-hooks lint src/ file3.js lib/       # mix of dirs and files
+ *   claude-hooks lint --headless --format json # CI mode with JSON output
  *
  * Path resolution (like git add):
  * - Directories → walk and collect files matching preset extensions
@@ -32,6 +33,28 @@ import { getStagedFiles, getRepoRoot } from '../utils/git-operations.js';
 import { runLinters, displayLintResults } from '../utils/linter-runner.js';
 import logger from '../utils/logger.js';
 
+// ─── JSON Error Helper ────────────────────────────────────────────────────
+
+/**
+ * Emit error JSON to stdout and set exit code
+ * @param {string} message - Error message
+ * @param {number} exitCode - Process exit code (default: 1)
+ * @private
+ */
+function _emitErrorJSON(message, exitCode = 1) {
+    process.stdout.write(`${JSON.stringify({ status: 'error', error: message })}\n`);
+    process.exitCode = exitCode;
+}
+
+/**
+ * Emit JSON result to stdout (does not exit — caller handles exit)
+ * @param {Object} payload - JSON payload
+ * @private
+ */
+function _emitJSON(payload) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
 /**
  * Resolve user-provided paths into a flat list of files
  * Handles directories (walked recursively), individual files, and mixtures.
@@ -116,13 +139,34 @@ function _walkForFiles(dir, extSet, files, depth = 0) {
     }
 }
 
+// Known flags that should not be treated as paths
+const KNOWN_FLAGS = new Set(['--headless', '--format']);
+
 /**
  * Main lint command handler
  *
  * @param {string[]} args - CLI arguments (paths and flags)
  */
 export async function runLint(args = []) {
+    // Parse flags
+    const headless = args.includes('--headless');
+    const fmtIdx = args.indexOf('--format');
+    const format = fmtIdx >= 0 ? args[fmtIdx + 1] : null;
+    const isJSON = format === 'json';
+
+    // Disallowed combo: --format json without --headless
+    if (isJSON && !headless) {
+        _emitErrorJSON('--format json requires --headless', 2);
+        return;
+    }
+
+    // Activate JSON mode before any output so info/warning route to stderr
+    if (isJSON) logger.setJSONMode(true);
+
+    const startTime = Date.now();
+
     if (!checkGitRepo()) {
+        if (isJSON) { _emitErrorJSON('Not a git repository'); return; }
         error('Not a git repository');
         process.exit(1);
     }
@@ -134,6 +178,19 @@ export async function runLint(args = []) {
     }
 
     if (config.linting?.enabled === false) {
+        if (isJSON) {
+            _emitJSON({
+                status: 'disabled',
+                preset: config.preset || 'default',
+                fileCount: 0,
+                totalErrors: 0,
+                totalWarnings: 0,
+                durationMs: Date.now() - startTime,
+                tools: []
+            });
+            process.exit(0);
+            return;
+        }
         info('Linting is disabled in configuration');
         return;
     }
@@ -142,8 +199,14 @@ export async function runLint(args = []) {
     const presetName = config.preset || 'default';
     const { metadata } = await loadPreset(presetName);
 
-    // Separate flags from paths
-    const paths = args.filter((a) => !a.startsWith('--'));
+    // Separate flags from paths — filter out known flags and their values
+    const paths = args.filter((a, i) => {
+        if (KNOWN_FLAGS.has(a)) return false;
+        // Skip value immediately after a flag that takes a value
+        if (i > 0 && args[i - 1] === '--format') return false;
+        if (a.startsWith('--')) return false;
+        return true;
+    });
 
     let filesToLint;
 
@@ -153,6 +216,19 @@ export async function runLint(args = []) {
         const stagedFiles = getStagedFiles({ extensions: metadata.fileExtensions });
 
         if (stagedFiles.length === 0) {
+            if (isJSON) {
+                _emitJSON({
+                    status: 'no-files',
+                    preset: presetName,
+                    fileCount: 0,
+                    totalErrors: 0,
+                    totalWarnings: 0,
+                    durationMs: Date.now() - startTime,
+                    tools: []
+                });
+                process.exit(0);
+                return; // guard test-mode fallthrough
+            }
             info('No staged files to lint');
             return;
         }
@@ -163,6 +239,18 @@ export async function runLint(args = []) {
         filesToLint = resolvePaths(paths, metadata.fileExtensions, repoRoot);
 
         if (filesToLint.length === 0) {
+            if (isJSON) {
+                _emitJSON({
+                    status: 'no-files',
+                    preset: presetName,
+                    fileCount: 0,
+                    totalErrors: 0,
+                    totalWarnings: 0,
+                    durationMs: Date.now() - startTime,
+                    tools: []
+                });
+                process.exit(0);
+            }
             info('No matching files found in specified paths');
             return;
         }
@@ -171,12 +259,40 @@ export async function runLint(args = []) {
     info(`🎯 Linting ${filesToLint.length} file(s) with '${metadata.displayName}' preset`);
 
     const lintResult = await runLinters(filesToLint, config, presetName);
-    displayLintResults(lintResult);
 
-    // Exit with error code if linting failed
+    if (!isJSON) {
+        displayLintResults(lintResult);
+    }
+
+    // Determine failure status
     const failOnError = config.linting?.failOnError !== false;
     const failOnWarning = config.linting?.failOnWarning === true;
+    const shouldFail =
+        (failOnError && lintResult.totalErrors > 0) ||
+        (failOnWarning && lintResult.totalWarnings > 0);
 
+    if (isJSON) {
+        _emitJSON({
+            status: shouldFail ? 'fail' : 'pass',
+            preset: presetName,
+            fileCount: filesToLint.length,
+            totalErrors: lintResult.totalErrors,
+            totalWarnings: lintResult.totalWarnings,
+            durationMs: Date.now() - startTime,
+            tools: lintResult.results.map((r) => ({
+                name: r.tool,
+                files: r.files || 0,
+                errors: r.errors.length,
+                warnings: r.warnings.length,
+                fixed: r.fixedCount || 0,
+                issues: [...r.errors, ...r.warnings]
+            }))
+        });
+        process.exit(shouldFail ? 1 : 0);
+        return;
+    }
+
+    // Exit with error code if linting failed
     if (failOnError && lintResult.totalErrors > 0) {
         process.exit(1);
     }

package/lib/config.js

@@ -91,6 +91,9 @@ const HARDCODED = {
         failOnError: true, // Block commit on linting errors
         failOnWarning: false, // Do not block on warnings
         timeout: 30000 // 30s per linter
+    },
+    claude: {
+        defaultModel: 'sonnet' // Fallback model for SDK headless mode
     }
 };
 

package/lib/hooks/pre-commit.js

@@ -19,7 +19,8 @@
  * - resolution-prompt: Issue resolution generation
  */
 
-import { getStagedFiles, getRepoRoot } from '../utils/git-operations.js';
+import { getStagedFiles, getRepoRoot, getStagedTreeSha } from '../utils/git-operations.js';
+import { writeMarker } from '../utils/hooks-verified-marker.js';
 import { filterFiles } from '../utils/file-operations.js';
 import {
     buildFilesData,
@@ -53,6 +54,10 @@ import { runLinters, displayLintResults, lintIssuesToAnalysisDetails } from '../
 const main = async () => {
     const startTime = Date.now();
 
+    // Headless mode: activated by env var for CI/ECS environments (CT-805)
+    // Declared before try/catch so the catch block can show appropriate error messages
+    const isHeadless = process.env.CLAUDE_HOOKS_HEADLESS === '1';
+
     try {
         // Load configuration
         const config = await getConfig();
@@ -194,7 +199,8 @@ const main = async () => {
         // Step 6: Run analysis using shared engine
         const result = await runAnalysis(filesData, config, {
             hook: 'pre-commit',
-            saveDebug: config.system.debug
+            saveDebug: config.system.debug,
+            headless: isHeadless
         });
 
         // Step 7: Display results using shared function
@@ -234,7 +240,7 @@ const main = async () => {
             if (judgeModule) {
                 try {
                     const { judgeAndFix } = judgeModule;
-                    const judgeResult = await judgeAndFix(result, filesData, config);
+                    const judgeResult = await judgeAndFix(result, filesData, config, { headless: isHeadless });
 
                     // Update result with remaining issues (fixed + false positives removed)
                     result.blockingIssues = judgeResult.remainingIssues.filter((i) =>
@@ -341,6 +347,16 @@ const main = async () => {
         console.log(`\n⏱️  Analysis time: ${duration}s`);
         logger.success('Code analysis completed. Quality gate passed.');
 
+        // Write hooks-verified marker for prepare-commit-msg trailer
+        try {
+            const treeSha = getStagedTreeSha();
+            writeMarker(repoRoot, treeSha, version);
+            logger.debug('pre-commit - main', 'Hooks-verified marker written', { treeSha });
+        } catch (markerErr) {
+            // Non-fatal: trailer won't be added but commit still succeeds
+            logger.warning(`Could not write hooks-verified marker: ${markerErr.message}`);
+        }
+
         process.exit(0);
     } catch (error) {
         // Record analysis failure metric
@@ -356,8 +372,13 @@ const main = async () => {
 
         logger.error('pre-commit - main', 'Pre-commit hook failed', error);
 
-        console.error('\nError executing Claude CLI');
-        console.error('Check that Claude CLI is configured correctly');
+        if (isHeadless) {
+            console.error('\nError executing Claude SDK');
+            console.error('Check that ANTHROPIC_API_KEY is set correctly');
+        } else {
+            console.error('\nError executing Claude CLI');
+            console.error('Check that Claude CLI is configured correctly');
+        }
 
         if (error.output) {
             console.error('\nClaude CLI output:');

package/lib/hooks/prepare-commit-msg.js

@@ -18,7 +18,15 @@
  */
 
 import fs from 'fs/promises';
-import { getStagedFiles, getStagedStats, getFileDiff } from '../utils/git-operations.js';
+import {
+    getStagedFiles,
+    getStagedStats,
+    getFileDiff,
+    getRepoRoot,
+    getStagedTreeSha,
+    appendTrailer
+} from '../utils/git-operations.js';
+import { readMarker, consumeMarker, validateMarker } from '../utils/hooks-verified-marker.js';
 import { analyzeCode } from '../utils/claude-client.js';
 import { loadPrompt } from '../utils/prompt-builder.js';
 import { getVersion } from '../utils/package-info.js';
@@ -119,6 +127,9 @@ const main = async () => {
     // Load configuration (includes preset + user overrides)
     const config = await getConfig();
 
+    // Headless mode: activated by env var for CI/ECS environments (CT-805)
+    const isHeadless = process.env.CLAUDE_HOOKS_HEADLESS === '1';
+
     // Enable debug mode from config
     if (config.system.debug) {
         logger.setDebugMode(true);
@@ -134,11 +145,44 @@ const main = async () => {
 
         // Only process normal commits
         // Why: Don't interfere with merge commits, amend, squash, etc.
+        // Marker is NOT consumed here — stays for the next eligible commit
         if (commitSource && commitSource !== 'message') {
             logger.debug('prepare-commit-msg - main', `Skipping: commit source is ${commitSource}`);
             process.exit(0);
         }
 
+        // Hooks-Verified trailer: validate marker now, append trailer at the very end.
+        // Why: The auto-message flow overwrites the commit file, so we can't append
+        // the trailer until the final message is written. We validate+consume the marker
+        // early (before the auto check) and remember the result for later.
+        const repoRoot = getRepoRoot();
+        const marker = readMarker(repoRoot);
+        let shouldAppendTrailer = false;
+
+        if (marker) {
+            let currentTreeSha;
+            try {
+                currentTreeSha = getStagedTreeSha();
+            } catch (err) {
+                logger.debug('prepare-commit-msg - main', 'Could not compute staged tree SHA', {
+                    err: err.message
+                });
+            }
+
+            if (currentTreeSha && validateMarker(marker, currentTreeSha)) {
+                shouldAppendTrailer = true;
+                logger.debug('prepare-commit-msg - main', 'Marker valid; trailer will be appended after message is finalized');
+            } else {
+                logger.debug(
+                    'prepare-commit-msg - main',
+                    'Marker stale (tree mismatch); ignoring'
+                );
+            }
+
+            // Always consume marker (whether matched or not) — no stale carryover
+            consumeMarker(repoRoot);
+        }
+
         // Read current message
         const currentMsg = await fs.readFile(commitMsgFile, 'utf8');
         const firstLine = currentMsg.split('\n')[0].trim();
@@ -147,6 +191,16 @@ const main = async () => {
 
         // Check if message is "auto"
         if (firstLine !== config.commitMessage.autoKeyword) {
+            // Not auto — append trailer to the manual message and exit
+            if (shouldAppendTrailer) {
+                try {
+                    const withTrailer = appendTrailer(currentMsg, 'Hooks-Verified', 'true');
+                    await fs.writeFile(commitMsgFile, withTrailer, 'utf8');
+                    logger.debug('prepare-commit-msg - main', 'Hooks-Verified trailer appended to manual message');
+                } catch (trailerErr) {
+                    logger.warning(`Could not append Hooks-Verified trailer: ${trailerErr.message}`);
+                }
+            }
             logger.debug('prepare-commit-msg - main', 'Not generating: message is not "auto"');
             process.exit(0);
         }
@@ -243,7 +297,8 @@ const main = async () => {
         const response = await analyzeCode(prompt, {
             timeout: config.commitMessage.timeout,
             saveDebug: config.system.debug,
-            telemetryContext
+            telemetryContext,
+            headless: isHeadless
         });
 
         logger.debug('prepare-commit-msg - main', 'Response received', {
@@ -266,6 +321,20 @@ const main = async () => {
         // Write to commit message file
         await fs.writeFile(commitMsgFile, `${message}\n`, 'utf8');
 
+        // Append trailer to the auto-generated message
+        if (shouldAppendTrailer) {
+            try {
+                const generated = await fs.readFile(commitMsgFile, 'utf8');
+                const withTrailer = appendTrailer(generated, 'Hooks-Verified', 'true');
+                await fs.writeFile(commitMsgFile, withTrailer, 'utf8');
+                logger.debug('prepare-commit-msg - main', 'Hooks-Verified trailer appended to auto message');
+            } catch (trailerErr) {
+                logger.warning(
+                    `Could not append Hooks-Verified trailer: ${trailerErr.message}`
+                );
+            }
+        }
+
         // Record commit generation metric
         recordMetric('commit.generated', {
             fileCount: filesData.length,
@@ -292,8 +361,13 @@ const main = async () => {
 
         logger.error('prepare-commit-msg - main', 'Failed to generate commit message', error);
 
-        logger.warning('Could not generate message automatically with Claude');
-        logger.warning('Commit canceled. Run again without "auto" to write manual message');
+        if (isHeadless) {
+            logger.warning('Could not generate message automatically via SDK');
+            logger.warning('Check that ANTHROPIC_API_KEY is set correctly');
+        } else {
+            logger.warning('Could not generate message automatically with Claude');
+            logger.warning('Commit canceled. Run again without "auto" to write manual message');
+        }
 
         process.exit(1);
     }