# Commit Workflow Guide

## Overview
This project uses Git hooks to maintain code quality. We've implemented a special workflow that **always** checks for personal information in commits while allowing you to skip time-consuming tests when needed.

## Quick Start

### Regular Commit (All Checks)
```bash
git commit -m "feat: add new feature"
# OR
npm run commit:safe -- -m "feat: add new feature"
```
Runs all checks:
- ✅ Personal information check (fast)
- ✅ Build artifact check (fast)
- 🐌 Tests and builds (can be slow)

### Fast Commit (Skip Git Hooks)
```bash
npm run commit:fast -- -m "feat: add new feature"
```
Manually runs the personal information check first, then uses `git commit --no-verify` internally, which bypasses **all** Git hooks (pre-commit, commit-msg, etc.):
- ✅ Personal information check runs FIRST (fast)
- ⚡ Then commits with --no-verify, skipping all other checks (pre-commit hooks, build verification, tests)

## Why This Exists

### The Problem
- `git commit --no-verify` skips **all** checks, including critical security checks for personal information
- Personal information (usernames, paths) should **never** be committed to the repository
- But sometimes you need to commit quickly without waiting for tests

### The Solution
We've created a safe commit wrapper that:
1. **Always** runs the personal information check (takes <1 second)
2. Optionally skips other time-consuming checks
3. Prevents accidental exposure of personal data

## Detailed Workflow

### What Gets Checked

#### Personal Information Check (Always Runs)
Detects and blocks:
- Personal usernames in paths (matches patterns like `/Users/[name]/` or `C:\Users\[name]\`)
- Cloud storage paths (Dropbox, OneDrive, Google Drive, etc.)
- Dated project folders (patterns with dates and project codes)
- Personal folder patterns (Documents, Desktop, Downloads with personal content)

#### Pre-Commit Checks (Can Be Skipped)
- Build artifacts in source directories
- Package tarballs
- Other quick validations

#### Pre-Push Checks (Run Before Push)
- ESLint
- Build verification
- Full test suite

### Commands Reference

| Command | Personal Info Check | Other Checks | Use Case |
|---------|-------------------|--------------|----------|
| `git commit` | ✅ | ✅ | Normal development |
| `npm run commit:safe` | ✅ | ✅ | Same as git commit |
| `npm run commit:fast` | ✅ | ❌ | Quick commits |
| `git commit --no-verify` | ❌ | ❌ | Emergency only! |

## Examples

### Example 1: Regular Development
```bash
# Make changes
git add .
git commit -m "fix: resolve connection issue"
# All checks run
```

### Example 2: Quick WIP Commit
```bash
# Make changes
git add .
npm run commit:fast -- -m "WIP: debugging connection"
# Only personal info check runs
```

### Example 3: If Personal Info Is Detected
```bash
$ npm run commit:fast -- -m "add test results"
🔍 Running mandatory personal information check...

❌ Personal information found in staged files!

📄 test-results.md
   Pattern detected: Personal username in file path

📝 Please replace with generic paths like:
   - /path/to/project
   - ~/workspace/project
   - C:\path\to\project

# Fix the file and try again
```

## Setting Up Git Aliases (Optional)

Add these to your `.gitconfig` for even faster access:

```bash
# Add to ~/.gitconfig
[alias]
    cs = !npm run commit:safe --
    cf = !npm run commit:fast --

# Usage
git cs -m "feat: add feature"  # Safe commit
git cf -m "WIP: quick fix"      # Fast commit (PI check only)
```

## Important Notes

1. **Personal information checks cannot be bypassed** with our safe commit commands
2. Use `git commit --no-verify` only in absolute emergencies
3. Pre-push hooks will still run all tests before code goes to GitHub
4. The PI check is fast (~1 second) so there's minimal overhead

## Troubleshooting

### "Command not found" Error
```bash
# Make the script executable (only needed if invoking directly)
chmod +x scripts/safe-commit.sh
# The script accepts --skip-tests as its first argument; all other args are forwarded to git.
```

### Personal Info Check Keeps Failing
- Check the patterns in `scripts/check-personal-paths.cjs`
- Replace personal paths with generic ones:
  - Bad: Paths containing actual usernames or personal folders
  - Good: `/path/to/project`
  - Good: `~/workspace/mcp-debugger`
  - Good: `./relative/path`

### Need to Bypass Everything (Emergency Only!)
```bash
# This skips ALL checks - use with extreme caution!
git commit --no-verify -m "emergency: critical fix"
```

## Benefits

- 🔒 **Security**: Personal information never accidentally committed
- ⚡ **Speed**: Skip slow tests for WIP commits
- 🛡️ **Safety Net**: CI/CD will catch issues before merge
- 🎯 **Flexibility**: Choose the right level of checking for your situation