claude-git-hooks 2.35.2 → 2.43.0

package/README.md

@@ -570,4 +570,117 @@ claude-hooks batch-info   # Shows config + per-model avg speed from telemetry
 
 ---
 
+## Contributing
+
+### Branching Strategy
+
+This repository follows **simplified GitHub Flow**:
+
+- **Main branch**: `main` (protected)
+- **Feature branches**: `feature/issue-description` or `feature/TASK-ID-description`
+- **Fix branches**: `fix/issue-description`
+- **Hotfix branches**: `hotfix/urgent-description`
+
+**Rules:**
+
+1. All changes require PR to `main`
+2. No direct commits to `main`
+3. PRs require review (auto-merge NOT allowed)
+
+### Development Process
+
+**1. Initial setup**
+
+```bash
+git clone https://github.com/mscope-S-L/git-hooks.git
+cd git-hooks
+npm install
+npm link  # Install globally as symlink for development
+```
+
+**2. Create feature branch**
+
+```bash
+git checkout -b feature/new-functionality
+# or with task-id: feature/IX-123-new-functionality
+```
+
+**3. Develop and test**
+
+```bash
+npm run lint        # Check ESLint
+npm run lint:fix    # Auto-fix ESLint issues
+npm run format      # Format with Prettier
+npm run test        # Run all tests (Jest)
+npm run test:watch  # Tests in watch mode
+npm run test:coverage # Coverage report
+```
+
+**4. Local testing in a test repo**
+
+```bash
+cd /path/to/test-repo
+claude-hooks install --force --skip-auth  # Reinstall from symlink
+git commit -m "test"  # Test hook (npm link is active, no reinstall needed)
+```
+
+**5. Create PR**
+
+```bash
+git push -u origin feature/new-functionality
+claude-hooks analyze-diff main    # Generate PR metadata
+claude-hooks create-pr main       # Or create PR directly on GitHub
+```
+
+### CI/CD
+
+No automated CI/CD (GitHub Actions pending). Manual verifications before merge:
+
+1. `npm run lint` passes
+2. `npm run test` — all tests pass
+3. Manual testing in test repo
+4. Peer code review
+5. CHANGELOG.md updated
+
+### Versioning
+
+Follows **Semantic Versioning** (MAJOR.MINOR.PATCH):
+
+- **MAJOR**: Breaking changes (config format, CLI arguments)
+- **MINOR**: New features without breaking changes
+- **PATCH**: Bug fixes
+
+```bash
+npm version patch    # 2.6.1 → 2.6.2
+npm version minor    # 2.6.1 → 2.7.0
+npm version major    # 2.6.1 → 3.0.0
+npm publish          # Publish to NPM
+```
+
+### Conventional Commits
+
+Format: `<type>(<scope>): <subject>`
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New functionality |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting (no logic change) |
+| `refactor` | Refactoring without functional change |
+| `test` | Add or modify tests |
+| `chore` | Maintenance (deps, config) |
+| `perf` | Performance improvements |
+
+**Optional scopes:** `hooks`, `presets`, `github`, `cli`, `config`, `windows`
+
+```
+feat(presets): add database preset for SQL analysis
+fix(windows): resolve spawn ENOENT with .cmd files
+docs: update CLAUDE.md with architecture details
+chore(deps): upgrade @octokit/rest to v21
+```
+
+---
+
 More information: https://github.com/mscope-S-L/git-hooks

package/bin/claude-hooks

@@ -8,7 +8,7 @@
  * All command implementations are in lib/commands/
  */
 
-import { error } from '../lib/commands/helpers.js';
+import { error, fatal } from '../lib/commands/helpers.js';
 import { buildCommandMap } from '../lib/cli-metadata.js';
 import logger from '../lib/utils/logger.js';
 import { getConfig } from '../lib/config.js';
@@ -41,14 +41,12 @@ async function main() {
     }
 
     if (!entry) {
-        error(`Unknown command: ${command}`);
-        const { runShowHelp } = await import('../lib/commands/help.js');
-        runShowHelp();
-        return;
+        fatal(`Unknown command: ${command}`);
     }
 
     // --- Authorization guard for protected workflow commands ---
-    {
+    const isHeadless = args.includes('--headless');
+    if (!isHeadless) {
         const { authorizeCommand, AuthorizationError, PERMISSIONS_SOURCE } = await import(
             '../lib/utils/authorization.js'
         );
@@ -128,6 +126,9 @@ async function main() {
             }
             process.exit(1);
         }
+    } else {
+        const { default: logger } = await import('../lib/utils/logger.js');
+        logger.debug('bin - main', 'Authorization guard bypassed (--headless)', { command: entry.name });
     }
 
     // --- Commands with special argument handling ---
@@ -135,10 +136,13 @@ async function main() {
     // analyze: translate flags to options object
     if (entry.name === 'analyze') {
         const handler = await entry.handler();
+        const fmtIdx = args.indexOf('--format');
         await handler({
             staged: !args.includes('--unstaged') && !args.includes('--all'),
             unstaged: args.includes('--unstaged'),
-            all: args.includes('--all')
+            all: args.includes('--all'),
+            headless: args.includes('--headless'),
+            format: fmtIdx >= 0 ? args[fmtIdx + 1] : null
         });
         return;
     }

package/lib/cli-metadata.js

@@ -61,7 +61,9 @@ export const commands = [
         handler: async () => (await import('./commands/install.js')).runInstall,
         flags: {
             '--force': { description: 'Reinstall even if already exist' },
-            '--skip-auth': { description: 'Skip Claude authentication check' }
+            '--skip-auth': { description: 'Deprecated: use --headless. Will be removed in a future version.' },
+            '--headless': { description: 'Skip all side effects (CI/container mode). Copies hooks only.' },
+            '--verify-sdk': { description: 'After install, ping the Anthropic SDK with 1 token to verify ANTHROPIC_API_KEY.' }
         }
     },
     {
@@ -104,6 +106,10 @@ export const commands = [
         args: {
             name: 'paths',
             completion: "find . -maxdepth 3 -type d -not -path '*/\\.*' -not -path '*/node_modules/*'"
+        },
+        flags: {
+            '--headless': { description: 'Skip interactive prompts (CI mode)' },
+            '--format': { description: 'Output format', takesValue: true, values: ['json'] }
         }
     },
     {
@@ -112,7 +118,9 @@ export const commands = [
         handler: async () => (await import('./commands/analyze.js')).runAnalyze,
         flags: {
             '--unstaged': { description: 'Analyze unstaged changes' },
-            '--all': { description: 'Analyze all tracked files' }
+            '--all': { description: 'Analyze all tracked files' },
+            '--headless': { description: 'Skip interactive prompts (CI mode)' },
+            '--format': { description: 'Output format', takesValue: true, values: ['json'] }
         }
     },
     {
@@ -136,7 +144,9 @@ export const commands = [
                 values: PRESET_NAMES
             },
             '--model': { description: 'Claude model override', takesValue: true },
-            '--dry-run': { description: 'Analyze without posting comments' }
+            '--dry-run': { description: 'Analyze without posting comments' },
+            '--headless': { description: 'Skip interactive prompts (CI mode)' },
+            '--format': { description: 'Output format', takesValue: true, values: ['json'] }
         }
     },
     {
@@ -146,6 +156,10 @@ export const commands = [
         args: {
             name: 'base-branch',
             completion: "git branch --format='%(refname:short)'"
+        },
+        flags: {
+            '--headless': { description: 'Skip interactive prompts (CI mode)' },
+            '--format': { description: 'Output format', takesValue: true, values: ['json'] }
         }
     },
     {