claude-git-hooks 2.1.0 → 2.3.1

package/templates/pre-commit

@@ -8,6 +8,7 @@ set -e
 
 # Colors for output
 RED='\033[0;31m'
+YELLOW='\033[1;33m'
 NC='\033[0m'
 
 # Convert Windows path to Git Bash/WSL path
@@ -64,13 +65,50 @@ find_hook_script() {
     return 1
 }
 
+# Early validation: Check if .claude directory exists
+# Why: Provides helpful error message if installation incomplete or in wrong directory
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -z "$REPO_ROOT" ]; then
+    echo -e "${RED}Error: Not in a git repository${NC}" >&2
+    exit 1
+fi
+
+if [ ! -d "$REPO_ROOT/.claude" ]; then
+    echo -e "${RED}Error: .claude directory not found${NC}" >&2
+    echo "" >&2
+    echo "Claude Git Hooks installation is incomplete or missing." >&2
+    echo "" >&2
+    echo "Current directory: $(pwd)" >&2
+    echo "Repository root:   $REPO_ROOT" >&2
+    echo "" >&2
+    echo "Common cause: Installation performed from wrong directory" >&2
+    echo "" >&2
+    echo "Solution:" >&2
+    echo "  cd $REPO_ROOT" >&2
+    echo "  claude-hooks install --force" >&2
+    exit 1
+fi
+
 # Find the Node.js script
 NODE_HOOK=$(find_hook_script)
 
 if [ -z "$NODE_HOOK" ]; then
     echo -e "${RED}Error: Could not find pre-commit.js${NC}" >&2
-    echo "Claude Git Hooks may not be properly installed." >&2
-    echo "Try running: claude-hooks install --force" >&2
+    echo "" >&2
+    echo "Claude Git Hooks installation is incomplete." >&2
+    echo "" >&2
+    echo "Current directory: $(pwd)" >&2
+    echo "Repository root:   $REPO_ROOT" >&2
+    echo "" >&2
+    echo "Common cause: Installation from wrong directory or npm package not properly installed" >&2
+    echo "" >&2
+    echo "Solution:" >&2
+    echo "  # Verify you're in repository root" >&2
+    echo "  cd $REPO_ROOT" >&2
+    echo "  # Verify npm package is installed globally" >&2
+    echo "  npm list -g claude-git-hooks" >&2
+    echo "  # Reinstall hooks" >&2
+    echo "  claude-hooks install --force" >&2
     exit 1
 fi
 

package/templates/prepare-commit-msg

@@ -8,6 +8,7 @@ set -e
 
 # Colors for output
 RED='\033[0;31m'
+YELLOW='\033[1;33m'
 NC='\033[0m'
 
 # Convert Windows path to Git Bash/WSL path
@@ -64,13 +65,50 @@ find_hook_script() {
     return 1
 }
 
+# Early validation: Check if .claude directory exists
+# Why: Provides helpful error message if installation incomplete or in wrong directory
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -z "$REPO_ROOT" ]; then
+    echo -e "${RED}Error: Not in a git repository${NC}" >&2
+    exit 1
+fi
+
+if [ ! -d "$REPO_ROOT/.claude" ]; then
+    echo -e "${RED}Error: .claude directory not found${NC}" >&2
+    echo "" >&2
+    echo "Claude Git Hooks installation is incomplete or missing." >&2
+    echo "" >&2
+    echo "Current directory: $(pwd)" >&2
+    echo "Repository root:   $REPO_ROOT" >&2
+    echo "" >&2
+    echo "Common cause: Installation performed from wrong directory" >&2
+    echo "" >&2
+    echo "Solution:" >&2
+    echo "  cd $REPO_ROOT" >&2
+    echo "  claude-hooks install --force" >&2
+    exit 1
+fi
+
 # Find the Node.js script
 NODE_HOOK=$(find_hook_script)
 
 if [ -z "$NODE_HOOK" ]; then
     echo -e "${RED}Error: Could not find prepare-commit-msg.js${NC}" >&2
-    echo "Claude Git Hooks may not be properly installed." >&2
-    echo "Try running: claude-hooks install --force" >&2
+    echo "" >&2
+    echo "Claude Git Hooks installation is incomplete." >&2
+    echo "" >&2
+    echo "Current directory: $(pwd)" >&2
+    echo "Repository root:   $REPO_ROOT" >&2
+    echo "" >&2
+    echo "Common cause: Installation from wrong directory or npm package not properly installed" >&2
+    echo "" >&2
+    echo "Solution:" >&2
+    echo "  # Verify you're in repository root" >&2
+    echo "  cd $REPO_ROOT" >&2
+    echo "  # Verify npm package is installed globally" >&2
+    echo "  npm list -g claude-git-hooks" >&2
+    echo "  # Reinstall hooks" >&2
+    echo "  claude-hooks install --force" >&2
     exit 1
 fi
 

package/templates/presets/ai/ANALYSIS_PROMPT.md

@@ -0,0 +1,133 @@
+You are analyzing a **{{PRESET_NAME}}** project with the following technology stack:
+
+**Tech Stack:** {{TECH_STACK}}
+
+**Analyzing files matching:** {{FILE_EXTENSIONS}}
+
+## Your Task
+
+Perform a comprehensive code quality analysis focusing on these areas:
+
+{{FOCUS_AREAS}}
+
+## Analysis Guidelines
+
+1. **Claude API Best Practices**:
+   - Proper use of Claude API endpoints
+   - Correct model selection (haiku/sonnet/opus)
+   - Token usage optimization
+   - Error handling for API failures
+   - Rate limiting considerations
+   - Timeout handling
+
+2. **Prompt Engineering**:
+   - Clear and specific instructions
+   - Well-structured prompts
+   - Appropriate context inclusion
+   - Effective use of examples
+   - Proper output format specifications
+   - Token-efficient prompting
+
+3. **CLI User Experience**:
+   - Clear, helpful error messages
+   - Appropriate use of colors/formatting
+   - Progress indicators for long operations
+   - Helpful usage instructions
+   - Graceful error recovery
+   - Cross-platform compatibility
+
+4. **Git Operations**:
+   - Safe git command execution
+   - Proper error handling
+   - Repository state validation
+   - Avoiding destructive operations
+   - Cross-platform path handling
+
+5. **Security**:
+   - API key protection (never log/expose)
+   - Secure credential storage
+   - Input validation
+   - Avoiding command injection
+   - Sensitive data handling in prompts
+
+6. **Code Quality**:
+   - Proper error handling
+   - Comprehensive logging
+   - Modular, reusable functions
+   - Clear documentation
+   - Maintainable code structure
+
+## Specific Checks
+
+### Claude API Usage
+✅ Using appropriate model for task (haiku for simple, sonnet for complex)
+✅ Implementing proper error handling (network, API, rate limit)
+✅ Token usage calculated and optimized
+✅ Prompts are well-structured and clear
+✅ Output parsing is robust
+✅ API keys never logged or exposed
+
+### Git Operations
+✅ Using proper git commands
+✅ Handling errors gracefully
+✅ Cross-platform path compatibility
+✅ Avoiding destructive operations without confirmation
+✅ Proper handling of special characters in filenames
+
+### Template Quality
+✅ Clear instructions for Claude
+✅ Well-defined output format
+✅ Appropriate context provided
+✅ Token-efficient design
+✅ Placeholders used correctly
+
+## Output Format
+
+Respond with a valid JSON following the SonarQube format:
+
+```json
+{
+  "QUALITY_GATE": "PASSED|FAILED",
+  "approved": true|false,
+  "metrics": {
+    "reliability": "A|B|C|D|E",
+    "security": "A|B|C|D|E",
+    "maintainability": "A|B|C|D|E",
+    "coverage": 0-100,
+    "duplications": 0-100,
+    "complexity": "number"
+  },
+  "issues": {
+    "blocker": 0,
+    "critical": 0,
+    "major": 0,
+    "minor": 0,
+    "info": 0
+  },
+  "details": [
+    {
+      "severity": "BLOCKER|CRITICAL|MAJOR|MINOR|INFO",
+      "type": "BUG|VULNERABILITY|CODE_SMELL|PROMPT_QUALITY",
+      "file": "path/to/file",
+      "line": 123,
+      "message": "Clear description of the issue"
+    }
+  ],
+  "securityHotspots": 0,
+  "blockingIssues": ["List of critical issues that must be fixed"]
+}
+```
+
+## Analysis Rules
+
+- **Block commit** if:
+  - Exposed API keys or secrets
+  - Security vulnerabilities
+  - Critical bugs in git operations
+  - Destructive operations without safeguards
+
+- **Pass** if: Only minor issues, suggestions, or no issues
+
+- Be constructive about prompt quality - suggest improvements
+- Focus on safety and user experience
+- Provide actionable, specific feedback with line numbers

package/templates/presets/ai/PRE_COMMIT_GUIDELINES.md

@@ -0,0 +1,176 @@
+# AI/CLI Code Quality Guidelines
+
+## Claude API Best Practices
+
+### Model Selection
+✅ **Haiku**: Simple tasks, fast responses, cost-effective
+✅ **Sonnet**: Balanced performance, most use cases
+✅ **Opus**: Complex reasoning, highest quality
+❌ Don't use Opus when Haiku would suffice
+
+### API Usage
+✅ Implement proper timeout handling
+✅ Handle rate limiting gracefully
+✅ Retry with exponential backoff on failures
+✅ Validate API responses before use
+✅ Log API errors (but never log API keys!)
+✅ Calculate and monitor token usage
+
+### Error Handling
+```javascript
+// ✅ Good
+try {
+    const response = await callClaudeAPI(prompt);
+    if (!response || !response.content) {
+        throw new Error('Invalid API response');
+    }
+    return parseResponse(response);
+} catch (error) {
+    if (error.status === 429) {
+        // Handle rate limiting
+    } else if (error.status === 500) {
+        // Handle server error
+    }
+    logger.error('API call failed', error);
+    throw new UserFriendlyError('Failed to analyze code');
+}
+```
+
+## Prompt Engineering
+
+### Structure
+✅ Clear role/context at the beginning
+✅ Specific task instructions
+✅ Well-defined output format (usually JSON)
+✅ Relevant examples when helpful
+✅ Appropriate length (token-efficient)
+
+### Quality Checklist
+✅ Instructions are unambiguous
+✅ Output format is machine-parseable
+✅ Context is sufficient but not excessive
+✅ Examples match expected usage
+✅ Placeholders are replaced correctly
+
+### Common Prompt Issues
+❌ Vague instructions
+❌ No output format specification
+❌ Too much unnecessary context
+❌ Ambiguous requirements
+❌ Missing examples for complex tasks
+
+## CLI User Experience
+
+### Error Messages
+✅ Clear, actionable error messages
+✅ Suggest solutions when possible
+✅ Use appropriate log levels
+✅ Color-code for readability (error=red, success=green)
+✅ Include context (what was being attempted)
+
+### User Feedback
+✅ Show progress for long operations
+✅ Confirm destructive operations
+✅ Provide helpful usage information
+✅ Display meaningful results
+✅ Log debug info only when debug mode enabled
+
+## Git Operations Safety
+
+### Safe Practices
+✅ Validate repository state before operations
+✅ Use `--cached` for staged changes
+✅ Handle special characters in filenames
+✅ Cross-platform path handling
+✅ Graceful handling of git errors
+
+### Dangerous Operations
+❌ Never run git commands that modify history without explicit user confirmation
+❌ Avoid hard resets
+❌ Be careful with force pushes
+❌ Validate before bulk operations
+
+## Security
+
+### API Keys
+✅ Load from environment variables
+✅ Never log or display API keys
+✅ Never commit API keys to repository
+✅ Use secure storage methods
+✅ Clear keys from memory when done
+
+### Command Injection
+✅ Validate all user input
+✅ Use parameterized commands when possible
+✅ Escape special characters
+✅ Avoid `eval()` and similar
+✅ Sanitize file paths
+
+### Sensitive Data
+✅ Don't send secrets to Claude API
+✅ Filter sensitive data from diffs
+✅ Be careful with error messages (don't expose internals)
+✅ Implement SKIP_ANALYSIS for sensitive code
+
+## Code Organization
+
+### File Structure
+```
+lib/
+  hooks/         # Git hook implementations
+  utils/         # Utility functions
+    claude-client.js
+    git-operations.js
+    file-operations.js
+    logger.js
+  config.js      # Configuration management
+templates/       # Prompt templates
+bin/            # CLI entry points
+```
+
+### Module Design
+✅ Single responsibility principle
+✅ Clear, descriptive function names
+✅ Comprehensive error handling
+✅ Proper logging at decision points
+✅ Export reusable functions
+
+## Common Issues to Avoid
+
+### Critical Issues
+❌ Exposed API keys or secrets
+❌ Command injection vulnerabilities
+❌ Destructive git operations without confirmation
+❌ Unhandled promise rejections
+
+### Major Issues
+❌ Missing error handling
+❌ Poor user experience (unclear errors)
+❌ Cross-platform incompatibility
+❌ Memory leaks (large file handling)
+❌ Missing input validation
+
+### Minor Issues
+❌ Insufficient logging
+❌ Unclear variable names
+❌ Missing documentation
+❌ Inefficient token usage
+❌ Poor code organization
+
+## Testing
+
+✅ Test with various input sizes
+✅ Test error scenarios (API failures, git errors)
+✅ Test cross-platform compatibility
+✅ Mock external dependencies (Claude API, git)
+✅ Test with edge cases (special characters, large files)
+✅ Verify token usage calculations
+
+## Documentation
+
+✅ Document API usage patterns
+✅ Explain prompt design decisions
+✅ Document configuration options
+✅ Provide usage examples
+✅ Keep README up to date
+✅ Document breaking changes

package/templates/presets/ai/config.json

@@ -0,0 +1,12 @@
+{
+  "analysis": {
+    "maxFileSize": 100000,
+    "maxFiles": 10,
+    "timeout": 120000
+  },
+  "subagents": {
+    "enabled": false,
+    "model": "sonnet",
+    "batchSize": 3
+  }
+}

package/templates/presets/ai/preset.json

@@ -0,0 +1,42 @@
+{
+  "name": "ai",
+  "displayName": "AI/CLI (Node.js + Claude)",
+  "description": "Node.js CLI tools with Claude API integration",
+  "version": "1.0.0",
+
+  "techStack": [
+    "Node.js",
+    "ES Modules",
+    "Claude API",
+    "CLI tools",
+    "Git hooks",
+    "Bash scripting",
+    "Markdown templates"
+  ],
+
+  "fileExtensions": [
+    ".js",
+    ".json",
+    ".md",
+    ".sh"
+  ],
+
+  "focusAreas": [
+    "Claude API usage and best practices",
+    "Prompt engineering quality",
+    "CLI user experience",
+    "Error handling and logging",
+    "Git operations safety",
+    "Cross-platform compatibility",
+    "Token usage optimization",
+    "Security (API keys, secrets)"
+  ],
+
+  "templates": {
+    "analysis": "ANALYSIS_PROMPT.md",
+    "guidelines": "PRE_COMMIT_GUIDELINES.md",
+    "commitMessage": "../shared/COMMIT_MESSAGE.md",
+    "analyzeDiff": "../shared/ANALYZE_DIFF.md",
+    "resolution": "../shared/RESOLUTION_PROMPT.md"
+  }
+}

package/templates/presets/backend/ANALYSIS_PROMPT.md

@@ -0,0 +1,85 @@
+You are analyzing a **{{PRESET_NAME}}** project with the following technology stack:
+
+**Tech Stack:** {{TECH_STACK}}
+
+**Analyzing files matching:** {{FILE_EXTENSIONS}}
+
+## Your Task
+
+Perform a comprehensive code quality analysis focusing on these areas:
+
+{{FOCUS_AREAS}}
+
+## Analysis Guidelines
+
+1. **Security First**: Check for OWASP Top 10 vulnerabilities, especially:
+   - SQL injection risks
+   - Authentication/authorization flaws
+   - Sensitive data exposure
+   - XML external entities (XXE)
+   - Insecure deserialization
+
+2. **Spring Boot Best Practices**:
+   - Proper use of `@Transactional`
+   - Correct exception handling
+   - Appropriate use of DTOs vs Entities
+   - Proper dependency injection
+   - Configuration management
+
+3. **JPA/Hibernate**:
+   - N+1 query problems
+   - Lazy loading issues
+   - Proper use of relationships
+   - Query optimization
+   - Transaction boundaries
+
+4. **Code Quality**:
+   - SOLID principles
+   - DRY violations
+   - Proper error handling
+   - Logging best practices
+   - Test coverage
+
+## Output Format
+
+Respond with a valid JSON following the SonarQube format:
+
+```json
+{
+  "QUALITY_GATE": "PASSED|FAILED",
+  "approved": true|false,
+  "metrics": {
+    "reliability": "A|B|C|D|E",
+    "security": "A|B|C|D|E",
+    "maintainability": "A|B|C|D|E",
+    "coverage": 0-100,
+    "duplications": 0-100,
+    "complexity": "number"
+  },
+  "issues": {
+    "blocker": 0,
+    "critical": 0,
+    "major": 0,
+    "minor": 0,
+    "info": 0
+  },
+  "details": [
+    {
+      "severity": "BLOCKER|CRITICAL|MAJOR|MINOR|INFO",
+      "type": "BUG|VULNERABILITY|CODE_SMELL",
+      "file": "path/to/file.java",
+      "line": 123,
+      "message": "Clear description of the issue"
+    }
+  ],
+  "securityHotspots": 0,
+  "blockingIssues": ["List of critical issues that must be fixed"]
+}
+```
+
+## Analysis Rules
+
+- **Block commit** if: Security vulnerabilities, critical bugs, or blocker issues found
+- **Pass** if: Only minor issues, info messages, or no issues
+- Be strict but fair - focus on real problems, not style preferences
+- Provide actionable, specific feedback with line numbers

package/templates/presets/backend/PRE_COMMIT_GUIDELINES.md

@@ -0,0 +1,87 @@
+# Backend Code Quality Guidelines
+
+## Spring Boot Standards
+
+### Controllers
+- Use proper HTTP methods and status codes
+- Validate input with `@Valid`
+- Handle exceptions with `@ExceptionHandler`
+- Keep controllers thin - business logic in services
+- Use DTOs for API contracts
+
+### Services
+- Use `@Transactional` appropriately
+- Handle exceptions properly
+- Keep methods focused and small
+- Avoid business logic in controllers or repositories
+
+### Repositories
+- Extend appropriate Spring Data interfaces
+- Use method naming conventions for queries
+- Optimize queries with `@Query` when needed
+- Avoid N+1 problems with `@EntityGraph`
+
+### Entities
+- Use Lombok annotations appropriately
+- Define proper relationships (`@OneToMany`, `@ManyToOne`, etc.)
+- Use `@Version` for optimistic locking
+- Never expose entities in API - use DTOs
+
+## Security Requirements
+
+### Authentication & Authorization
+- Never hardcode credentials
+- Use Spring Security properly
+- Validate JWT tokens correctly
+- Check permissions before operations
+
+### Data Validation
+- Validate all user input
+- Use parameterized queries (JPA does this by default)
+- Sanitize data before logging
+- Never trust client-side validation alone
+
+### SQL Injection Prevention
+- Always use JPA/JPQL or prepared statements
+- Never concatenate SQL strings
+- Be careful with native queries
+- Use `@Query` with proper parameter binding
+
+## Performance
+
+### Database
+- Use pagination for large result sets
+- Optimize queries with proper indexes
+- Avoid loading unnecessary data
+- Use projections when you don't need full entities
+
+### Threading
+- Be careful with `@Async` methods
+- Use proper thread pool configuration
+- Avoid blocking operations in async methods
+- Handle exceptions in async methods
+
+### Caching
+- Use `@Cacheable` appropriately
+- Clear caches when data changes
+- Don't cache sensitive data without encryption
+
+## Testing
+
+- Write unit tests for business logic
+- Use `@DataJpaTest` for repository tests
+- Use `@WebMvcTest` for controller tests
+- Mock external dependencies
+- Aim for 80%+ coverage on new code
+
+## Common Issues to Avoid
+
+❌ Returning entities from controllers
+❌ Missing `@Transactional` on write operations
+❌ N+1 query problems
+❌ Hardcoded secrets or credentials
+❌ Catching and ignoring exceptions
+❌ Missing input validation
+❌ Exposing sensitive data in logs
+❌ Using `SELECT *` in queries
+❌ Not handling null values properly

package/templates/presets/backend/config.json

@@ -0,0 +1,12 @@
+{
+  "analysis": {
+    "maxFileSize": 100000,
+    "maxFiles": 10,
+    "timeout": 120000
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "sonnet",
+    "batchSize": 3
+  }
+}