crowd-funder-from-jason/doc/debug-hook-guide.md

# TimeSafari Debug Hook Guide

**Complete Guide for Team Members**

**Date**: 2025-01-27  
**Author**: Matthew Raymer  
**Status**: ✅ **ACTIVE** - Ready for production use

## 🎯 Overview

A pre-commit hook that automatically detects and prevents debug code from reaching protected branches (master, main, production, release, stable). This ensures production code remains clean while allowing free development on feature branches.

## 🚀 Quick Installation

**From within the TimeSafari repository:**

```bash
./scripts/install-debug-hook.sh
```

This automatically installs, updates, and verifies the hook in your current
repository. **Note**: Hooks are not automatically installed - you must run this
script deliberately to enable debug code checking.

## 🔧 Manual Installation

**Copy files manually:**

```bash
cp scripts/git-hooks/pre-commit /path/to/your/repo/.git/hooks/
cp scripts/git-hooks/debug-checker.config /path/to/your/repo/.git/hooks/
chmod +x /path/to/your/repo/.git/hooks/pre-commit
```

## 📋 What Gets Installed

- **`pre-commit`** - Main hook script (executable)
- **`debug-checker.config`** - Configuration file
- **`README.md`** - Documentation and troubleshooting

**Note**: Hooks are stored in `scripts/git-hooks/` and must be deliberately
installed by each developer. They are not automatically active.

## 🎯 How It Works

1. **Deliberate Installation**: Hooks must be explicitly installed by each
   developer
2. **Branch Detection**: Only runs on protected branches
3. **File Filtering**: Automatically skips tests, scripts, and documentation
4. **Pattern Matching**: Detects debug code using regex patterns
5. **Commit Prevention**: Blocks commits containing debug code

## 🔒 Installation Philosophy

**Why deliberate installation?**

- **Developer choice**: Each developer decides whether to use the hook
- **No forced behavior**: Hooks don't interfere with existing workflows
- **Local control**: Hooks are installed locally, not globally
- **Easy removal**: Can be uninstalled at any time
- **Team flexibility**: Some developers may prefer different tools

## 🌿 Branch Behavior

- **Protected branches** (master, main, production, release, stable): Hook runs automatically
- **Feature branches**: Hook is skipped, allowing free development with debug code

## 🔍 Debug Patterns Detected

- **Console statements**: `console.log`, `console.debug`, `console.error`
- **Template debug**: `Debug:`, `debug:` in Vue templates
- **Debug constants**: `DEBUG_`, `debug_` variables
- **HTML debug**: `<!-- debug` comments
- **Debug attributes**: `debug="true"` attributes
- **Vue debug**: `v-if="debug"`, `v-show="debug"`
- **Debug TODOs**: `TODO debug`, `FIXME debug`

## 📁 Files Automatically Skipped

- Test files: `*.test.js`, `*.spec.ts`, `*.test.vue`
- Scripts: `scripts/` directory
- Test directories: `test-*` directories
- Documentation: `docs/`, `*.md`, `*.txt`
- Config files: `*.json`, `*.yml`, `*.yaml`
- IDE files: `.cursor/` directory

## ✅ Verification

**After installation, verify it's working:**

```bash
# Check if files exist
ls -la .git/hooks/pre-commit
ls -la .git/hooks/debug-checker.config

# Test the hook manually
.git/hooks/pre-commit

# Test with actual commit
echo "console.log('test')" > test.vue
git add test.vue
git commit -m "test"  # Should be blocked
```

## 📊 Example Output

```
❌ Debug code detected in staged files!
   Branch: master
   Files checked: 1
   Errors found: 3

   🚨 AccountViewView.vue: Found debug pattern 'console\.'
   🚨 AccountViewView.vue: Found debug pattern 'Debug:'
   🚨 AccountViewView.vue: Found debug pattern 'DEBUG_'

💡 Please remove debug code before committing to master
```

## ⚙️ Configuration

Edit `.git/hooks/debug-checker.config` to customize:

- **Protected branches**: Add/remove branches as needed
- **Debug patterns**: Customize what gets detected
- **Skip patterns**: Adjust file filtering rules

## 🚨 Emergency Bypass

If you absolutely need to commit debug code to a protected branch:

```bash
git commit --no-verify -m "emergency: debug code needed"
```

⚠️ **Warning**: This bypasses all pre-commit hooks. Use sparingly.

## 🔄 Updates

When the hook is updated in the main repository:

```bash
./scripts/install-debug-hook.sh
```

## 🚨 Troubleshooting

| Issue | Solution |
|-------|----------|
| Hook not running | Check if on protected branch, verify permissions |
| Permission denied | Run `chmod +x .git/hooks/pre-commit` |
| Files not found | Ensure you're copying from TimeSafari repo |
| False positives | Edit `debug-checker.config` to customize patterns |

## 🧪 Testing

A test script is available at `scripts/test-debug-hook.sh` to verify the hook works correctly.

## 💡 Best Practices

1. **Use feature branches** for development with debug code
2. **Use proper logging** instead of console statements (`logger.info`, `logger.debug`)
3. **Test thoroughly** before merging to protected branches
4. **Review commits** to ensure no debug code slips through
5. **Keep hooks updated** across all repositories

## 📚 Additional Resources

- **Hook documentation**: `scripts/git-hooks/README.md`
- **Configuration**: `scripts/git-hooks/debug-checker.config`
- **Test script**: `scripts/test-debug-hook.sh`
- **Installation script**: `scripts/install-debug-hook.sh`

## 🎯 Team Workflow

**Recommended setup:**

1. **Repository setup**: Include hook files in `.githooks/` directory
2. **Team onboarding**: Run installation script in each repo
3. **Updates**: Re-run installation script when hooks are updated
4. **Documentation**: Keep this guide updated

---

**Status**: Active and enforced  
**Last Updated**: 2025-01-27  
**Maintainer**: Matthew Raymer