claude-git-hooks 2.3.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/preset-loader.js

@@ -13,12 +13,14 @@
  * - 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
@@ -189,7 +191,10 @@ export async function listPresets() {
             }
         }
     } catch (error) {
-        logger.warning('No presets directory found. Run "claude-hooks install" first.');
+        const errorMsg = formatError('No presets directory found', [
+            `Expected location: ${presetsDir}`
+        ]);
+        logger.warning(errorMsg);
         logger.debug(
             'preset-loader - listPresets',
             'Failed to read presets directory',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.3.0",
+    "version": "2.3.1",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {