claude-git-hooks 2.1.0 → 2.3.1

package/lib/utils/installation-diagnostics.js

@@ -0,0 +1,145 @@
+/**
+ * File: installation-diagnostics.js
+ * Purpose: Reusable error diagnostics and formatting utilities
+ *
+ * Key features:
+ * - Generic error formatting with installation diagnostics
+ * - Detects common installation issues
+ * - Provides actionable remediation steps
+ * - Extensible for future diagnostic checks
+ *
+ * Usage:
+ *   import { formatError } from './installation-diagnostics.js';
+ *
+ *   try {
+ *     // ... operation that might fail
+ *   } catch (error) {
+ *     console.error(formatError('Presets not found'));
+ *     process.exit(1);
+ *   }
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { getRepoRoot } from './git-operations.js';
+
+/**
+ * Gets installation diagnostics
+ * Why: Centralized logic to detect common installation issues
+ *
+ * Future enhancements:
+ * - Check file permissions
+ * - Verify Claude CLI installation
+ * - Check Node.js version compatibility
+ * - Validate .gitignore entries
+ * - Check hook file integrity
+ * - Verify template files exist
+ * - Check config.json validity
+ *
+ * @returns {Object} Diagnostic information
+ */
+export const getInstallationDiagnostics = () => {
+    const diagnostics = {
+        currentDir: process.cwd(),
+        repoRoot: null,
+        isInRepoRoot: false,
+        claudeDirExists: false,
+        claudeDirPath: null,
+        presetsDirExists: false,
+        presetsDirPath: null,
+        gitHooksExists: false,
+    };
+
+    try {
+        diagnostics.repoRoot = getRepoRoot();
+        diagnostics.isInRepoRoot = diagnostics.currentDir === diagnostics.repoRoot;
+
+        diagnostics.claudeDirPath = path.join(diagnostics.repoRoot, '.claude');
+        diagnostics.claudeDirExists = fs.existsSync(diagnostics.claudeDirPath);
+
+        diagnostics.presetsDirPath = path.join(diagnostics.claudeDirPath, 'presets');
+        diagnostics.presetsDirExists = fs.existsSync(diagnostics.presetsDirPath);
+
+        const gitHooksPath = path.join(diagnostics.repoRoot, '.git', 'hooks');
+        diagnostics.gitHooksExists = fs.existsSync(gitHooksPath);
+    } catch (error) {
+        // Not in a git repository - diagnostics.repoRoot will be null
+    }
+
+    return diagnostics;
+};
+
+/**
+ * Formats error message with diagnostics and remediation steps
+ * Why: Provides consistent, actionable error messages across all errors
+ *
+ * @param {string} errorMessage - Description of what failed (e.g., "Presets not found", "Template file missing")
+ * @param {string[]} additionalContext - Optional additional context lines
+ * @returns {string} Formatted error message with diagnostics and remediation steps
+ */
+export const formatError = (errorMessage, additionalContext = []) => {
+    const diagnostics = getInstallationDiagnostics();
+    const lines = [];
+
+    lines.push(`⚠️  ${errorMessage}`);
+    lines.push('');
+
+    // Add any additional context first
+    if (additionalContext.length > 0) {
+        lines.push(...additionalContext);
+        lines.push('');
+    }
+
+    // Diagnostic information
+    lines.push('Installation diagnostics:');
+    lines.push(`  Current directory: ${diagnostics.currentDir}`);
+    if (diagnostics.repoRoot) {
+        lines.push(`  Repository root:   ${diagnostics.repoRoot}`);
+        lines.push(`  .claude/ exists:   ${diagnostics.claudeDirExists ? '✓' : '✗'}`);
+        lines.push(`  presets/ exists:   ${diagnostics.presetsDirExists ? '✓' : '✗'}`);
+    } else {
+        lines.push(`  Repository root:   [Not in a git repository]`);
+    }
+    lines.push('');
+
+    // Remediation steps based on detected issues
+    lines.push('Recommended solution:');
+    if (!diagnostics.repoRoot) {
+        lines.push('  Not in a git repository');
+        lines.push('  → Navigate to your repository and try again');
+    } else if (!diagnostics.claudeDirExists) {
+        lines.push('  claude-hooks not installed');
+        if (!diagnostics.isInRepoRoot) {
+            lines.push(`  → cd ${diagnostics.repoRoot}`);
+            lines.push('  → claude-hooks install');
+        } else {
+            lines.push('  → claude-hooks install');
+        }
+    } else if (!diagnostics.isInRepoRoot) {
+        lines.push('  Running from subdirectory (may cause path issues)');
+        lines.push(`  → cd ${diagnostics.repoRoot}`);
+        lines.push('  → claude-hooks uninstall');
+        lines.push('  → claude-hooks install');
+    } else if (!diagnostics.presetsDirExists) {
+        lines.push('  Incomplete installation (presets missing)');
+        lines.push('  → claude-hooks install --force');
+    } else {
+        lines.push('  Unknown issue detected');
+        lines.push('  → claude-hooks install --force');
+    }
+
+    return lines.join('\n');
+};
+
+/**
+ * Checks if installation appears healthy
+ * Why: Quick validation before operations that require full installation
+ *
+ * @returns {boolean} True if installation looks healthy
+ */
+export const isInstallationHealthy = () => {
+    const diagnostics = getInstallationDiagnostics();
+    return diagnostics.claudeDirExists &&
+           diagnostics.presetsDirExists &&
+           diagnostics.gitHooksExists;
+};

package/lib/utils/package-info.js

@@ -0,0 +1,75 @@
+/**
+ * File: package-info.js
+ * Purpose: Utility for reading package.json information
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * @typedef {Object} PackageData
+ * @property {string} name - Package name
+ * @property {string} version - Package version
+ * @property {string} [description] - Package description
+ */
+
+/**
+ * Cache for package.json to avoid repeated file reads
+ * @type {PackageData|undefined}
+ */
+let packageCache;
+
+/**
+ * Gets package.json data with caching (async)
+ * @returns {Promise<PackageData>} Package data with name and version
+ * @throws {Error} If package.json cannot be read
+ */
+export const getPackageJson = async () => {
+    // Return cached value if available
+    if (packageCache) {
+        return packageCache;
+    }
+
+    try {
+        const packagePath = path.join(__dirname, '..', '..', 'package.json');
+        const content = await fs.readFile(packagePath, 'utf8');
+        packageCache = JSON.parse(content);
+        return packageCache;
+    } catch (error) {
+        throw new Error(`Failed to read package.json: ${error.message}`);
+    }
+};
+
+/**
+ * Gets package version (async)
+ * @returns {Promise<string>} Package version
+ */
+export const getVersion = async () => {
+    const pkg = await getPackageJson();
+    return pkg.version;
+};
+
+/**
+ * Gets package name (async)
+ * @returns {Promise<string>} Package name
+ */
+export const getPackageName = async () => {
+    const pkg = await getPackageJson();
+    return pkg.name;
+};
+
+/**
+ * Calculates batch information for subagent processing
+ * @param {number} fileCount - Number of files to process
+ * @param {number} batchSize - Size of each batch
+ * @returns {Object} Batch information { numBatches, shouldShowBatches }
+ */
+export const calculateBatches = (fileCount, batchSize) => {
+    const numBatches = Math.ceil(fileCount / batchSize);
+    const shouldShowBatches = fileCount > batchSize;
+    return { numBatches, shouldShowBatches };
+};

package/lib/utils/preset-loader.js

@@ -0,0 +1,214 @@
+/**
+ * File: preset-loader.js
+ * Purpose: Loads preset configurations and metadata
+ *
+ * Key responsibilities:
+ * - Load preset.json (metadata)
+ * - Load config.json (overrides)
+ * - Resolve template paths
+ * - Replace placeholders in templates
+ *
+ * Dependencies:
+ * - fs/promises: Async file operations
+ * - path: Cross-platform path handling
+ * - git-operations: For getRepoRoot()
+ * - logger: Debug and error logging
+ * - installation-diagnostics: Error formatting with remediation steps
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { getRepoRoot } from './git-operations.js';
+import logger from './logger.js';
+import { formatError } from './installation-diagnostics.js';
+
+/**
+ * Custom error for preset loading failures
+ */
+class PresetError extends Error {
+    constructor(message, { presetName, cause } = {}) {
+        super(message);
+        this.name = 'PresetError';
+        this.presetName = presetName;
+        this.cause = cause;
+    }
+}
+
+/**
+ * Loads preset metadata + config
+ * @param {string} presetName - Name of preset (backend, frontend, etc.)
+ * @returns {Promise<Object>} { metadata, config, templates }
+ */
+export async function loadPreset(presetName) {
+    logger.debug(
+        'preset-loader - loadPreset',
+        'Loading preset',
+        { presetName }
+    );
+
+    const repoRoot = getRepoRoot();
+
+    // Only try .claude/presets/{name} (installed by claude-hooks install)
+    const presetDir = path.join(repoRoot, '.claude', 'presets', presetName);
+
+    logger.debug('preset-loader - loadPreset', 'Loading preset from', { presetDir });
+
+    try {
+        // Load preset.json (metadata)
+        const presetJsonPath = path.join(presetDir, 'preset.json');
+        const metadataRaw = await fs.readFile(presetJsonPath, 'utf8');
+        const metadata = JSON.parse(metadataRaw);
+
+        // Load config.json (overrides)
+        const configJsonPath = path.join(presetDir, 'config.json');
+        const configRaw = await fs.readFile(configJsonPath, 'utf8');
+        const config = JSON.parse(configRaw);
+
+        // Resolve template paths
+        const templates = {};
+        for (const [key, templatePath] of Object.entries(metadata.templates)) {
+            templates[key] = path.join(presetDir, templatePath);
+        }
+
+        logger.debug(
+            'preset-loader - loadPreset',
+            'Preset loaded successfully',
+            {
+                presetName,
+                displayName: metadata.displayName,
+                fileExtensions: metadata.fileExtensions,
+                templateCount: Object.keys(templates).length
+            }
+        );
+
+        return { metadata, config, templates };
+
+    } catch (error) {
+        logger.error(
+            'preset-loader - loadPreset',
+            `Failed to load preset: ${presetName}`,
+            error
+        );
+
+        throw new PresetError(`Preset "${presetName}" not found or invalid`, {
+            presetName,
+            cause: error
+        });
+    }
+}
+
+/**
+ * Loads a template file and replaces placeholders
+ * @param {string} templatePath - Absolute path to template file
+ * @param {Object} metadata - Preset metadata for placeholder replacement
+ * @returns {Promise<string>} Template content with placeholders replaced
+ */
+export async function loadTemplate(templatePath, metadata) {
+    logger.debug(
+        'preset-loader - loadTemplate',
+        'Loading template',
+        { templatePath }
+    );
+
+    try {
+        let template = await fs.readFile(templatePath, 'utf8');
+
+        // Replace placeholders
+        template = template.replace(
+            /{{TECH_STACK}}/g,
+            metadata.techStack.join(', ')
+        );
+        template = template.replace(
+            /{{FOCUS_AREAS}}/g,
+            metadata.focusAreas.join(', ')
+        );
+        template = template.replace(
+            /{{FILE_EXTENSIONS}}/g,
+            metadata.fileExtensions.join(', ')
+        );
+        template = template.replace(
+            /{{PRESET_NAME}}/g,
+            metadata.name
+        );
+
+        logger.debug(
+            'preset-loader - loadTemplate',
+            'Template loaded and processed',
+            {
+                templatePath,
+                originalLength: template.length
+            }
+        );
+
+        return template;
+
+    } catch (error) {
+        logger.error(
+            'preset-loader - loadTemplate',
+            `Failed to load template: ${templatePath}`,
+            error
+        );
+
+        throw new PresetError(`Template not found: ${templatePath}`, {
+            cause: error
+        });
+    }
+}
+
+/**
+ * Lists all available presets in .claude/presets/
+ * @returns {Promise<Array<Object>>} Array of preset metadata
+ * Returns: [{ name, displayName, description }]
+ */
+export async function listPresets() {
+    logger.debug('preset-loader - listPresets', 'Listing available presets');
+
+    const repoRoot = getRepoRoot();
+    const presets = [];
+
+    // Load all presets from .claude/presets/ (installed by claude-hooks install)
+    const presetsDir = path.join(repoRoot, '.claude', 'presets');
+    try {
+        const presetNames = await fs.readdir(presetsDir);
+
+        for (const name of presetNames) {
+            const presetJsonPath = path.join(presetsDir, name, 'preset.json');
+            try {
+                const metadataRaw = await fs.readFile(presetJsonPath, 'utf8');
+                const metadata = JSON.parse(metadataRaw);
+
+                presets.push({
+                    name: metadata.name,
+                    displayName: metadata.displayName,
+                    description: metadata.description
+                });
+            } catch (error) {
+                logger.debug(
+                    'preset-loader - listPresets',
+                    `Skipping invalid preset: ${name}`,
+                    error
+                );
+            }
+        }
+    } catch (error) {
+        const errorMsg = formatError('No presets directory found', [
+            `Expected location: ${presetsDir}`
+        ]);
+        logger.warning(errorMsg);
+        logger.debug(
+            'preset-loader - listPresets',
+            'Failed to read presets directory',
+            error
+        );
+    }
+
+    logger.debug(
+        'preset-loader - listPresets',
+        'Presets listed',
+        { count: presets.length }
+    );
+
+    return presets;
+}
+
+export { PresetError };

package/lib/utils/prompt-builder.js

@@ -38,14 +38,22 @@ class PromptBuilderError extends Error {
  * Why absolute path: Ensures templates are found regardless of cwd (cross-platform)
  *
  * @param {string} templateName - Name of template file
- * @param {string} baseDir - Base directory (default: .claude)
+ * @param {string} baseDir - Base directory (default: try .claude, fallback to templates)
  * @returns {Promise<string>} Template content
  * @throws {PromptBuilderError} If template not found
  */
 const loadTemplate = async (templateName, baseDir = '.claude') => {
     // Why: Use repo root for absolute path (works on Windows/PowerShell/Git Bash)
     const repoRoot = getRepoRoot();
-    const templatePath = path.join(repoRoot, baseDir, templateName);
+    let templatePath = path.join(repoRoot, baseDir, templateName);
+
+    // Try .claude first, fallback to templates/ if not found
+    try {
+        await fs.access(templatePath);
+    } catch {
+        // Try templates/ directory as fallback
+        templatePath = path.join(repoRoot, 'templates', templateName);
+    }
 
     logger.debug(
         'prompt-builder - loadTemplate',
@@ -104,6 +112,57 @@ const replaceTemplate = (template, variables) => {
     }, template);
 };
 
+/**
+ * Loads a prompt template and replaces variables
+ * Why: High-level interface that combines loading and variable replacement
+ *
+ * @param {string} templateName - Name of template file
+ * @param {Object} variables - Variables to replace in template
+ * @param {string} baseDir - Base directory (default: .claude)
+ * @returns {Promise<string>} Prompt with replaced variables
+ * @throws {PromptBuilderError} If template not found
+ *
+ * Example:
+ * const prompt = await loadPrompt('COMMIT_MESSAGE.md', {
+ *   FILE_LIST: 'file1.js\nfile2.js',
+ *   FILE_COUNT: 2,
+ *   INSERTIONS: 10,
+ *   DELETIONS: 5
+ * });
+ */
+const loadPrompt = async (templateName, variables = {}, baseDir = '.claude') => {
+    logger.debug(
+        'prompt-builder - loadPrompt',
+        'Loading prompt with variables',
+        { templateName, variableCount: Object.keys(variables).length }
+    );
+
+    try {
+        // Load template
+        const template = await loadTemplate(templateName, baseDir);
+
+        // Replace variables
+        const prompt = replaceTemplate(template, variables);
+
+        logger.debug(
+            'prompt-builder - loadPrompt',
+            'Prompt loaded successfully',
+            { templateName, promptLength: prompt.length }
+        );
+
+        return prompt;
+
+    } catch (error) {
+        logger.error(
+            'prompt-builder - loadPrompt',
+            `Failed to load prompt: ${templateName}`,
+            error
+        );
+
+        throw error;
+    }
+};
+
 /**
  * Formats file information for prompt
  * Why: Structures file data in readable format for Claude
@@ -144,6 +203,7 @@ const formatFileSection = ({ path, diff, content, isNew }) => {
  * @param {string} options.guidelinesName - Guidelines filename
  * @param {Array<Object>} options.files - Array of file data objects
  * @param {Object} options.metadata - Additional metadata (repo name, branch, etc.)
+ * @param {Object} options.subagentConfig - Subagent configuration (optional)
  * @returns {Promise<string>} Complete analysis prompt
  *
  * File data object structure:
@@ -158,12 +218,13 @@ const buildAnalysisPrompt = async ({
     templateName = 'CLAUDE_ANALYSIS_PROMPT_SONAR.md',
     guidelinesName = 'CLAUDE_PRE_COMMIT_SONAR.md',
     files = [],
-    metadata = {}
+    metadata = {},
+    subagentConfig = null
 } = {}) => {
     logger.debug(
         'prompt-builder - buildAnalysisPrompt',
         'Building analysis prompt',
-        { templateName, guidelinesName, fileCount: files.length }
+        { templateName, guidelinesName, fileCount: files.length, subagentsEnabled: subagentConfig?.enabled }
     );
 
     try {
@@ -176,6 +237,22 @@ const buildAnalysisPrompt = async ({
         // Start with template
         let prompt = template;
 
+        // Add subagent instruction if enabled and 3+ files
+        if (subagentConfig?.enabled && files.length >= 3) {
+            try {
+                const subagentInstruction = await loadTemplate('SUBAGENT_INSTRUCTION.md');
+                const subagentVariables = {
+                    BATCH_SIZE: subagentConfig.batchSize || 3,
+                    MODEL: subagentConfig.model || 'haiku'
+                };
+                prompt += '\n\n' + replaceTemplate(subagentInstruction, subagentVariables) + '\n';
+
+                logger.info(`🚀 Batch optimization enabled: ${files.length} files, ${subagentVariables.BATCH_SIZE} per batch, ${subagentVariables.MODEL} model`);
+            } catch (error) {
+                logger.warning('Subagent instruction template not found, proceeding without parallel analysis');
+            }
+        }
+
         // Add guidelines section
         prompt += '\n\n=== EVALUATION GUIDELINES ===\n';
         prompt += guidelines;
@@ -212,72 +289,11 @@ const buildAnalysisPrompt = async ({
     }
 };
 
-/**
- * Builds commit message generation prompt
- * Why: Used by prepare-commit-msg hook
- *
- * @param {Object} options - Build options
- * @param {Array<Object>} options.files - Array of changed files with diffs
- * @param {Object} options.stats - Staging statistics
- * @returns {Promise<string>} Complete commit message prompt
- *
- * Stats object structure:
- * {
- *   totalFiles: number,
- *   addedFiles: number,
- *   modifiedFiles: number,
- *   deletedFiles: number,
- *   insertions: number,
- *   deletions: number
- * }
- */
-const buildCommitMessagePrompt = async ({ files = [], stats = {} } = {}) => {
-    logger.debug(
-        'prompt-builder - buildCommitMessagePrompt',
-        'Building commit message prompt',
-        { fileCount: files.length, stats }
-    );
-
-    let prompt = `Generate a conventional commit message for the following changes.\n\n`;
-
-    // Add statistics
-    prompt += `=== STATISTICS ===\n`;
-    prompt += `Files changed: ${stats.totalFiles || files.length}\n`;
-    prompt += `Added: ${stats.addedFiles || 0}, Modified: ${stats.modifiedFiles || 0}, Deleted: ${stats.deletedFiles || 0}\n`;
-    prompt += `Insertions: ${stats.insertions || 0}, Deletions: ${stats.deletions || 0}\n\n`;
-
-    // Add file changes
-    prompt += `=== CHANGED FILES ===\n`;
-    files.forEach(({ path, diff }) => {
-        prompt += `\n--- ${path} ---\n`;
-        if (diff) {
-            prompt += `${diff}\n`;
-        }
-    });
-
-    // Add instructions
-    prompt += `\n\n=== INSTRUCTIONS ===\n`;
-    prompt += `Generate a concise commit message following Conventional Commits format:\n`;
-    prompt += `- type: feat, fix, docs, style, refactor, test, chore\n`;
-    prompt += `- Format: "type: description" or "type(scope): description"\n`;
-    prompt += `- Description: Clear, imperative mood, no period at end\n`;
-    prompt += `- Optional body: Detailed explanation if needed\n\n`;
-    prompt += `Respond with ONLY the commit message, no explanations.\n`;
-
-    logger.debug(
-        'prompt-builder - buildCommitMessagePrompt',
-        'Commit message prompt built',
-        { promptLength: prompt.length }
-    );
-
-    return prompt;
-};
-
 export {
     PromptBuilderError,
     loadTemplate,
     replaceTemplate,
+    loadPrompt,
     formatFileSection,
-    buildAnalysisPrompt,
-    buildCommitMessagePrompt
+    buildAnalysisPrompt
 };

package/lib/utils/resolution-prompt.js

@@ -179,14 +179,20 @@ ${content}
 const generateResolutionPrompt = async (
     analysisResult,
     {
-        outputPath = 'claude_resolution_prompt.md',
+        outputPath = null,
         templatePath = '.claude/CLAUDE_RESOLUTION_PROMPT.md',
         fileCount = 0
     } = {}
 ) => {
     // Why: Use repo root for absolute paths (works on Windows/PowerShell/Git Bash)
     const repoRoot = getRepoRoot();
-    const absoluteOutputPath = path.join(repoRoot, outputPath);
+
+    // Load config to get default output path
+    const { getConfig } = await import('../config.js');
+    const config = await getConfig();
+    const finalOutputPath = outputPath || config.output.resolutionFile;
+
+    const absoluteOutputPath = path.join(repoRoot, finalOutputPath);
     const absoluteTemplatePath = path.join(repoRoot, templatePath);
 
     logger.debug(
@@ -226,6 +232,10 @@ const generateResolutionPrompt = async (
             .replace(/{{BLOCKING_ISSUES}}/g, issuesFormatted)
             .replace(/{{FILE_CONTENTS}}/g, fileContentsFormatted);
 
+        // Ensure output directory exists
+        const outputDir = path.dirname(absoluteOutputPath);
+        await fs.mkdir(outputDir, { recursive: true });
+
         // Write resolution prompt file
         await fs.writeFile(absoluteOutputPath, prompt, 'utf8');