From 76c94bbe085847c3d680376856167ea5c331de13 Mon Sep 17 00:00:00 2001
From: Matthew Raymer <matthew.raymer@anomalistdesign.com>
Date: Tue, 19 Aug 2025 05:47:29 +0000
Subject: [PATCH] docs: add comprehensive debug hook guide for team members

Consolidates all debug hook documentation into single comprehensive guide.
Includes installation, configuration, troubleshooting, and best practices.

- Quick installation with automated script
- Manual installation options
- Configuration customization
- Troubleshooting guide
- Team workflow recommendations
- Emergency bypass procedures
---
 doc/debug-hook-guide.md | 165 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 165 insertions(+)
 create mode 100644 doc/debug-hook-guide.md

diff --git a/doc/debug-hook-guide.md b/doc/debug-hook-guide.md
new file mode 100644
index 00000000..2b029d33
--- /dev/null
+++ b/doc/debug-hook-guide.md
@@ -0,0 +1,165 @@
+# 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.
+
+## 🔧 Manual Installation
+
+**Copy files manually:**
+
+```bash
+cp .git/hooks/pre-commit /path/to/your/repo/.git/hooks/
+cp .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
+
+## 🎯 How It Works
+
+1. **Branch Detection**: Only runs on protected branches
+2. **File Filtering**: Automatically skips tests, scripts, and documentation
+3. **Pattern Matching**: Detects debug code using regex patterns
+4. **Commit Prevention**: Blocks commits containing debug code
+
+## 🌿 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**: `.git/hooks/README.md`
+- **Configuration**: `.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