quick commit

DEV_GUIDE.md

@@ -0,0 +1,287 @@
+# GuardDen Development Guide
+
+This guide provides everything you need to start developing GuardDen locally.
+
+## 🚀 Quick Start
+
+```bash
+# 1. Clone the repository
+git clone <repository-url>
+cd GuardDen
+
+# 2. Set up development environment
+./scripts/dev.sh setup
+
+# 3. Configure environment variables
+cp .env.example .env
+# Edit .env with your Discord bot token and other settings
+
+# 4. Start development environment
+./scripts/dev.sh up
+
+# 5. Run tests to verify setup
+./scripts/dev.sh test
+```
+
+## 📋 Development Commands
+
+The `./scripts/dev.sh` script provides comprehensive development automation:
+
+### Environment Management
+```bash
+./scripts/dev.sh setup           # Set up development environment
+./scripts/dev.sh up              # Start development containers
+./scripts/dev.sh down            # Stop development containers
+./scripts/dev.sh logs [service]  # Show logs (optional service filter)
+./scripts/dev.sh clean           # Clean up development artifacts
+```
+
+### Code Quality
+```bash
+./scripts/dev.sh test            # Run tests with coverage
+./scripts/dev.sh lint            # Run code quality checks
+./scripts/dev.sh format          # Format code with ruff
+./scripts/dev.sh security        # Run security scans
+```
+
+### Database Management
+```bash
+./scripts/dev.sh db migrate      # Run database migrations
+./scripts/dev.sh db revision "description"  # Create new migration
+./scripts/dev.sh db reset        # Reset database (destructive)
+```
+
+### Health & Monitoring
+```bash
+./scripts/dev.sh health check    # Run health checks
+./scripts/dev.sh health json     # Health checks with JSON output
+```
+
+### Docker Operations
+```bash
+./scripts/dev.sh build           # Build Docker images
+```
+
+## 🐳 Development Services
+
+When you run `./scripts/dev.sh up`, the following services are available:
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| GuardDen Bot | - | Discord bot with hot reloading |
+| Dashboard | http://localhost:8080 | Web interface |
+| PostgreSQL | localhost:5432 | Database |
+| Redis | localhost:6379 | Caching & sessions |
+| PgAdmin | http://localhost:5050 | Database administration |
+| Redis Commander | http://localhost:8081 | Redis administration |
+| MailHog | http://localhost:8025 | Email testing |
+
+## 🧪 Testing
+
+### Running Tests
+```bash
+# Run all tests with coverage
+./scripts/dev.sh test
+
+# Run specific test files
+pytest tests/test_config.py
+
+# Run tests with verbose output
+pytest -v
+
+# Run tests in parallel (faster)
+pytest -n auto
+```
+
+### Test Structure
+- `tests/conftest.py` - Test fixtures and configuration
+- `tests/test_*.py` - Test modules
+- Test coverage reports in `htmlcov/`
+
+### Writing Tests
+- Use pytest with async support (`pytest-asyncio`)
+- Comprehensive fixtures available for database, Discord mocks, etc.
+- Follow naming convention: `test_*` functions in `Test*` classes
+
+## 🔧 Code Quality
+
+### Pre-commit Hooks
+Pre-commit hooks are automatically installed during setup:
+- **Ruff**: Code formatting and linting
+- **MyPy**: Type checking
+- **Tests**: Run tests on relevant changes
+
+### Manual Quality Checks
+```bash
+# Run all quality checks
+./scripts/dev.sh lint
+
+# Format code
+./scripts/dev.sh format
+
+# Type checking only
+mypy src
+
+# Security scanning
+./scripts/dev.sh security
+```
+
+### Code Style
+- **Line Length**: 100 characters (configured in pyproject.toml)
+- **Imports**: Sorted with ruff
+- **Type Hints**: Required for all public functions
+- **Docstrings**: Google style for modules and classes
+
+## 📊 Monitoring & Debugging
+
+### Structured Logging
+```python
+from guardden.utils.logging import get_logger, bind_context
+
+logger = get_logger(__name__)
+
+# Log with context
+bind_context(user_id=123, guild_id=456)
+logger.info("User performed action", action="kick", target="user#1234")
+```
+
+### Metrics Collection
+```python
+from guardden.utils.metrics import get_metrics
+
+metrics = get_metrics()
+metrics.record_command("ban", guild_id=123, status="success", duration=0.5)
+```
+
+### Health Checks
+```bash
+# Check application health
+./scripts/dev.sh health check
+
+# Get detailed JSON health report
+./scripts/dev.sh health json
+```
+
+## 🗄️ Database Development
+
+### Migrations
+```bash
+# Create new migration
+./scripts/dev.sh db revision "add new table"
+
+# Run migrations
+./scripts/dev.sh db migrate
+
+# Rollback one migration
+./scripts/dev.sh db downgrade
+```
+
+### Database Access
+- **PgAdmin**: http://localhost:5050 (admin@guardden.dev / admin)
+- **Direct connection**: localhost:5432 (guardden / guardden_dev)
+- **Test database**: In-memory SQLite for tests
+
+## 🐛 Debugging
+
+### Debug Mode
+Development containers include debugging support:
+- **Bot**: Debug port 5678
+- **Dashboard**: Debug port 5679
+
+### VS Code Configuration
+Add to `.vscode/launch.json`:
+```json
+{
+    "name": "Attach to Bot",
+    "type": "python",
+    "request": "attach",
+    "host": "localhost",
+    "port": 5678
+}
+```
+
+### Log Analysis
+```bash
+# Follow all logs
+./scripts/dev.sh logs
+
+# Follow specific service logs
+./scripts/dev.sh logs bot
+./scripts/dev.sh logs dashboard
+```
+
+## 🔐 Security
+
+### Environment Variables
+- **Required**: `GUARDDEN_DISCORD_TOKEN`
+- **Database**: `GUARDDEN_DATABASE_URL` (auto-configured for development)
+- **AI**: `GUARDDEN_ANTHROPIC_API_KEY` or `GUARDDEN_OPENAI_API_KEY`
+
+### Security Best Practices
+- Never commit secrets to version control
+- Use `.env` for local development secrets
+- Run security scans regularly: `./scripts/dev.sh security`
+- Keep dependencies updated
+
+## 🚀 Deployment
+
+### Building for Production
+```bash
+# Build optimized image
+docker build -t guardden:latest .
+
+# Build with AI dependencies
+docker build --build-arg INSTALL_AI=true -t guardden:ai .
+```
+
+### CI/CD Pipeline
+- **GitHub Actions**: Automated testing, security scanning, and deployment
+- **Quality Gates**: 75%+ test coverage, type checking, security scans
+- **Automated Deployments**: Staging (develop branch) and production (releases)
+
+## 🆘 Troubleshooting
+
+### Common Issues
+
+**Port conflicts**:
+```bash
+# Check what's using a port
+lsof -i :5432
+
+# Use different ports in .env
+POSTGRES_PORT=5433
+REDIS_PORT=6380
+```
+
+**Permission errors**:
+```bash
+# Fix Docker permissions
+sudo chown -R $USER:$USER data logs
+```
+
+**Database connection errors**:
+```bash
+# Reset development environment
+./scripts/dev.sh down
+./scripts/dev.sh clean
+./scripts/dev.sh up
+```
+
+**Test failures**:
+```bash
+# Run tests with more verbose output
+pytest -vvs
+
+# Run specific failing test
+pytest tests/test_config.py::TestSettingsValidation::test_discord_token_validation_valid -vvs
+```
+
+### Getting Help
+1. Check logs: `./scripts/dev.sh logs`
+2. Run health check: `./scripts/dev.sh health check`
+3. Verify environment: `./scripts/dev.sh setup`
+4. Check GitHub Issues for known problems
+
+---
+
+Happy coding! 🎉