claude-git-hooks 2.35.3 → 2.44.0

package/lib/commands/help.js

@@ -4,7 +4,7 @@
  *
  * Features:
  * - Dynamic help from command registry (no args, --help, -h)
- * - AI help: routes questions to Claude with CLAUDE.md as knowledge base
+ * - AI help: two-pass librarian navigating .library/ for answers
  * - Report issue: interactive issue creation guided by Claude
  */
 
@@ -160,59 +160,130 @@ function printAiResponse(response, source) {
     console.log('');
 }
 
+/** Package root directory — resolved once from __dirname */
+const _packageRoot = path.join(__dirname, '..', '..');
+
 /**
- * Read CLAUDE.md from package root
- * Why: CLAUDE.md is the primary knowledge source shipped with the npm package
+ * Catalog directories within .library/ to auto-discover
+ * Why: These contain index and shelf files that form the navigational catalog.
+ * books/ is excluded — those are fetched on-demand in Pass 2.
+ */
+const _CATALOG_DIRS = ['by-code', 'by-domain', 'by-task-type'];
+
+/**
+ * Read a single file from package root, returning null on failure
  *
- * @returns {Promise<string|null>} CLAUDE.md content or null
+ * @param {string} relativePath - Path relative to package root
+ * @returns {Promise<string|null>} File content or null
  */
-const readClaudeMd = async () => {
-    const claudeMdPath = path.join(__dirname, '..', '..', 'CLAUDE.md');
+const _readPackageFile = async (relativePath) => {
     try {
-        const content = await fs.readFile(claudeMdPath, 'utf8');
-        logger.debug('help - readClaudeMd', 'CLAUDE.md loaded', { length: content.length });
-        return content;
-    } catch (error) {
-        logger.debug('help - readClaudeMd', 'CLAUDE.md not found', {
-            path: claudeMdPath,
-            error: error.message
-        });
+        return await fs.readFile(path.join(_packageRoot, relativePath), 'utf8');
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Read the project catalog from .library/ and CLAUDE.md
+ * Why: The catalog provides navigational context for the AI librarian (Pass 1).
+ * Auto-discovers index/shelf files so the catalog stays current as .library/ grows.
+ *
+ * Reads:
+ * - CLAUDE.md (global rules)
+ * - .library/index.md (repo identity, capabilities)
+ * - .library/conventions.md (coding standards)
+ * - .library/by-code/*.md (source-path shelves)
+ * - .library/by-domain/*.md (workflow reading lists)
+ * - .library/by-task-type/*.md (task guidance)
+ *
+ * @returns {Promise<string|null>} Concatenated catalog or null if nothing could be read
+ */
+const readLibraryCatalog = async () => {
+    const sections = [];
+
+    // Fixed files: CLAUDE.md + core library files
+    const fixedFiles = [
+        { label: 'CLAUDE.md', path: 'CLAUDE.md' },
+        { label: '.library/index.md', path: '.library/index.md' },
+        { label: '.library/conventions.md', path: '.library/conventions.md' }
+    ];
+
+    for (const file of fixedFiles) {
+        const content = await _readPackageFile(file.path);
+        if (content) {
+            sections.push(`--- ${file.label} ---\n${content}`);
+        }
+    }
+
+    // Auto-discover .md files in each catalog directory
+    for (const dir of _CATALOG_DIRS) {
+        const dirPath = path.join(_packageRoot, '.library', dir);
+        let entries;
+        try {
+            entries = await fs.readdir(dirPath);
+        } catch {
+            logger.debug('help - readLibraryCatalog', `Could not read .library/${dir}/`);
+            continue;
+        }
+
+        const mdFiles = entries.filter((f) => f.endsWith('.md')).sort();
+        for (const file of mdFiles) {
+            const relativePath = `.library/${dir}/${file}`;
+            const content = await _readPackageFile(relativePath);
+            if (content) {
+                sections.push(`--- ${relativePath} ---\n${content}`);
+            }
+        }
+    }
+
+    if (sections.length === 0) {
+        logger.debug('help - readLibraryCatalog', 'No catalog files found');
         return null;
     }
+
+    const catalog = sections.join('\n\n');
+    logger.debug('help - readLibraryCatalog', 'Catalog loaded', {
+        sections: sections.length,
+        length: catalog.length
+    });
+    return catalog;
 };
 
 /**
- * AI-powered help: routes question to Claude with CLAUDE.md context
- * Why: Provides intelligent answers about claude-hooks based on documentation
+ * AI-powered help: two-pass librarian navigating .library/
+ * Why: Provides intelligent answers by reading the project catalog, then
+ * fetching specific books from local disk only when deeper detail is needed.
  *
  * Flow:
- * 1. Read CLAUDE.md from package root
- * 2. Load HELP_QUERY.md template
- * 3. Call Claude with 30s timeout
- * 4. If NEED_MORE_CONTEXT: fetch referenced files from GitHub, re-query
- * 5. Display response
- * 6. On any error: fall back to static help
+ * 1. Read catalog from .library/ (auto-discovered indexes + shelves)
+ * 2. Pass 1: Send catalog to Claude via HELP_NAVIGATE.md
+ * 3. If ANSWER: display directly (1 Claude call)
+ * 4. If BOOKS: read requested books from local disk, send to HELP_QUERY.md (2 Claude calls)
+ * 5. On any error: fall back to static help
  *
  * @param {string} question - User's natural language question
  */
 async function runAiHelp(question) {
     try {
-        const claudeMdContent = await readClaudeMd();
-        if (!claudeMdContent) {
+        const catalog = await readLibraryCatalog();
+        if (!catalog) {
             logger.debug(
                 'help - runAiHelp',
-                'CLAUDE.md not available, falling back to static help'
+                'Catalog not available, falling back to static help'
             );
             showStaticHelp();
             return;
         }
 
-        const prompt = await loadPrompt('HELP_QUERY.md', {
-            DOCUMENTATION: claudeMdContent,
+        const prompt = await loadPrompt('HELP_NAVIGATE.md', {
+            CATALOG: catalog,
             QUESTION: question
         });
 
-        logger.debug('help - runAiHelp', 'Querying Claude', { questionLength: question.length });
+        logger.debug('help - runAiHelp', 'Querying Claude (Pass 1)', {
+            questionLength: question.length
+        });
         console.log('\nSearching documentation...\n');
 
         const pkg = getPackageJson();
@@ -221,95 +292,98 @@ async function runAiHelp(question) {
         const response = await executeClaudeWithRetry(prompt, { timeout: 60000 });
         const trimmedResponse = response.trim();
 
-        // Check for NEED_MORE_CONTEXT second pass
-        const needMoreLine = trimmedResponse
-            .split('\n')
-            .find((l) => l.includes('NEED_MORE_CONTEXT'));
-        if (needMoreLine) {
-            const enrichedResponse = await handleNeedMoreContext(
-                needMoreLine,
+        // Check for BOOKS: second pass
+        const booksLine = trimmedResponse.split('\n').find((l) => l.startsWith('BOOKS:'));
+        if (booksLine) {
+            const enrichedAnswer = await readAndAnswerWithBooks(
+                booksLine,
                 question,
-                claudeMdContent
+                catalog
             );
-            if (enrichedResponse) {
-                printAiResponse(enrichedResponse, `${localVersion} + source`);
-                return;
-            }
-            // Enrichment failed: show first-pass answer with marker line stripped
-            const cleanResponse = trimmedResponse
-                .split('\n')
-                .filter((l) => !l.includes('NEED_MORE_CONTEXT'))
-                .join('\n')
-                .trim();
-            if (cleanResponse) {
-                printAiResponse(cleanResponse, localVersion);
+            if (enrichedAnswer) {
+                printAiResponse(enrichedAnswer, `${localVersion} + source`);
                 return;
             }
+            // Books not readable — avoid surfacing raw BOOKS: line to the user
+            showStaticHelp();
+            return;
         }
 
-        printAiResponse(trimmedResponse, localVersion);
-    } catch (error) {
+        // ANSWER: response or fallback — strip the "ANSWER:" prefix if present
+        const answerLine = trimmedResponse.indexOf('ANSWER:');
+        const answer =
+            answerLine !== -1
+                ? trimmedResponse.substring(answerLine + 'ANSWER:'.length).trim()
+                : trimmedResponse;
+
+        printAiResponse(answer, localVersion);
+    } catch (err) {
         logger.debug('help - runAiHelp', 'AI help failed, falling back to static help', {
-            error: error.message
+            error: err.message
         });
         showStaticHelp();
     }
 }
 
 /**
- * Handle NEED_MORE_CONTEXT response by fetching referenced files from GitHub
+ * Pass 2: Read requested books from local disk and answer with enriched context
  *
- * @param {string} needMoreLine - The line containing NEED_MORE_CONTEXT marker
+ * @param {string} booksLine - The line starting with "BOOKS:" containing comma-separated paths
  * @param {string} question - Original user question
- * @param {string} claudeMdContent - Original CLAUDE.md content
- * @returns {Promise<string|null>} Enriched response or null on failure
+ * @param {string} catalog - The catalog content from Pass 1
+ * @returns {Promise<string|null>} Enriched answer or null on failure
  */
-async function handleNeedMoreContext(needMoreLine, question, claudeMdContent) {
+async function readAndAnswerWithBooks(booksLine, question, catalog) {
     try {
-        // Parse file paths from line: "NEED_MORE_CONTEXT: file1.js, file2.js"
-        const pathsPart = needMoreLine.replace('NEED_MORE_CONTEXT', '').replace(':', '').trim();
-        const filePaths = pathsPart
+        const pathsPart = booksLine.replace('BOOKS:', '').trim();
+        const bookPaths = pathsPart
             .split(',')
             .map((p) => p.trim())
             .filter(Boolean);
 
-        if (filePaths.length === 0) {
-            logger.debug('help - handleNeedMoreContext', 'No file paths in NEED_MORE_CONTEXT');
+        if (bookPaths.length === 0) {
+            logger.debug('help - readAndAnswerWithBooks', 'No book paths in BOOKS line');
             return null;
         }
 
-        logger.debug('help - handleNeedMoreContext', 'Fetching additional files', { filePaths });
-
-        const { owner, repo } = getSourceRepo();
-
-        // Fetch files in parallel (no ref = default branch, avoids 404 on unreleased tags)
-        const fetchResults = await Promise.all(
-            filePaths.map(async (filePath) => {
-                const content = await fetchFileContent(owner, repo, filePath);
-                return { filePath, content };
+        logger.debug('help - readAndAnswerWithBooks', 'Reading books from disk', { bookPaths });
+
+        // Read books from local filesystem in parallel
+        // Contain LLM-sourced paths to the package root to prevent traversal
+        const readResults = await Promise.all(
+            bookPaths.map(async (bookPath) => {
+                const resolvedPath = path.resolve(_packageRoot, bookPath);
+                if (!resolvedPath.startsWith(_packageRoot + path.sep)) {
+                    logger.debug('help - readAndAnswerWithBooks', 'Path traversal blocked', { bookPath });
+                    return { bookPath, content: null };
+                }
+                const content = await _readPackageFile(bookPath);
+                return { bookPath, content };
             })
         );
 
-        // Build enriched documentation
-        const additionalContent = fetchResults
+        const bookContent = readResults
             .filter((r) => r.content !== null)
-            .map((r) => `\n--- Source: ${r.filePath} ---\n${r.content}`)
-            .join('\n');
+            .map((r) => `--- ${r.bookPath} ---\n${r.content}`)
+            .join('\n\n');
 
-        if (!additionalContent) {
-            logger.debug('help - handleNeedMoreContext', 'No additional content fetched');
+        if (!bookContent) {
+            logger.debug('help - readAndAnswerWithBooks', 'No book content read from disk');
             return null;
         }
 
         const enrichedPrompt = await loadPrompt('HELP_QUERY.md', {
-            DOCUMENTATION: `${claudeMdContent}\n\n=== ADDITIONAL SOURCE FILES ===\n${additionalContent}`,
+            CATALOG: catalog,
+            BOOKS: bookContent,
             QUESTION: question
         });
 
         const enrichedResponse = await executeClaudeWithRetry(enrichedPrompt, { timeout: 60000 });
         return enrichedResponse.trim();
-    } catch (error) {
-        logger.debug('help - handleNeedMoreContext', 'Enrichment failed', { error: error.message });
+    } catch (err) {
+        logger.debug('help - readAndAnswerWithBooks', 'Book enrichment failed', {
+            error: err.message
+        });
         return null;
     }
 }
@@ -371,8 +445,8 @@ async function runReportIssue() {
             return;
         }
 
-        // Step 5: Read CLAUDE.md for project context
-        const claudeMdContent = await readClaudeMd();
+        // Step 5: Read CLAUDE.md for project context (report-issue only needs basic context)
+        const claudeMdContent = await _readPackageFile('CLAUDE.md');
 
         // Step 6: Generate questions from template using Claude
         const questionsPrompt = await loadPrompt('HELP_REPORT_ISSUE.md', {

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 ──────────────────────────────────────────────