GuardDen/MIGRATION.md

# GuardDen Migration Guide: Discord Commands to File-Based Configuration

This guide explains how to migrate from Discord command-based configuration to the new file-based YAML configuration system.

## Why Migrate?

The new file-based configuration system offers several advantages:

- **✅ Version Control**: Track configuration changes with Git
- **✅ No Discord Dependencies**: Configure without being in Discord
- **✅ Backup & Restore**: Easy configuration backups and restoration
- **✅ Hot-Reloading**: Changes apply without bot restarts
- **✅ Better Organization**: Clean, structured configuration files
- **✅ Schema Validation**: Automatic error checking and prevention
- **✅ Bulk Operations**: Configure multiple servers efficiently

## Migration Overview

### Phase 1: Preparation
1. ✅ Update GuardDen to the latest version
2. ✅ Install new dependencies: `pip install -e ".[dev,ai]"`
3. ✅ Backup your current configuration (optional but recommended)

### Phase 2: Export Existing Settings
4. ✅ Run the migration tool to export Discord settings to files
5. ✅ Verify migration results
6. ✅ Review and customize exported configurations

### Phase 3: Switch to File-Based Configuration
7. ✅ Test the new configuration system
8. ✅ (Optional) Clean up database configurations

## Step-by-Step Migration

### Step 1: Update Dependencies

```bash
# Install new required packages
pip install -e ".[dev,ai]"

# Or if you prefer individual packages:
pip install pyyaml jsonschema watchfiles
```

### Step 2: Run Migration Tool

Export your existing Discord command settings to YAML files:

```bash
# Export all guild configurations from database to files
python -m guardden.cli.config migrate from-database

# This will create files like:
# config/guilds/guild-123456789.yml
# config/guilds/guild-987654321.yml
# etc.
```

**Migration Output Example:**
```
🔄 Starting migration from database to files...
📦 Existing files will be backed up

📊 Migration Results:
   ✅ Migrated: 3 guilds
   ❌ Failed: 0 guilds  
   ⏭️  Skipped: 0 guilds
   📝 Banned words migrated: 45

✅ Successfully migrated guilds:
   • 123456789: My Gaming Server (12 banned words)
   • 987654321: Friends Chat (8 banned words)
   • 555666777: Test Server (0 banned words)
```

### Step 3: Verify Migration

Check that the migration was successful:

```bash
# Verify all guilds
python -m guardden.cli.config migrate verify

# Or verify specific guilds
python -m guardden.cli.config migrate verify 123456789 987654321
```

### Step 4: Review Generated Configurations

Examine the generated configuration files:

```bash
# List all configurations
python -m guardden.cli.config guild list

# Validate configurations  
python -m guardden.cli.config guild validate
```

**Example Generated Configuration:**
```yaml
# config/guilds/guild-123456789.yml
guild_id: 123456789
name: "My Gaming Server"
owner_id: 987654321
premium: false

settings:
  general:
    prefix: "!"
    locale: "en"
    
  ai_moderation:
    enabled: true
    sensitivity: 80
    nsfw_only_filtering: false  # ← Your new NSFW-only feature!
    confidence_threshold: 0.7
    
  automod:
    message_rate_limit: 5
    scam_allowlist:
      - "discord.com" 
      - "github.com"

# Migrated banned words (if any)
banned_words:
  - pattern: "spam"
    action: delete
    is_regex: false
    reason: "Anti-spam filter"
```

### Step 5: Customize Your Configuration

Now you can edit the YAML files directly or use the CLI:

```bash
# Enable NSFW-only filtering (only block sexual content)
python -m guardden.cli.config guild edit 123456789 ai_moderation.nsfw_only_filtering true

# Adjust AI sensitivity
python -m guardden.cli.config guild edit 123456789 ai_moderation.sensitivity 75

# Validate changes
python -m guardden.cli.config guild validate 123456789
```

**Or edit files directly:**
```yaml
# Edit config/guilds/guild-123456789.yml
ai_moderation:
  enabled: true
  sensitivity: 75                  # Changed from 80
  nsfw_only_filtering: true        # Changed from false
  confidence_threshold: 0.7
```

### Step 6: Test the New System

1. **Restart GuardDen** to load the file-based configuration:
   ```bash
   python -m guardden
   ```

2. **Test hot-reloading** by editing a config file:
   ```bash
   # Edit a setting in config/guilds/guild-123456789.yml
   # Changes should apply within seconds (check bot logs)
   ```

3. **Verify settings in Discord** using read-only commands:
   ```
   !config     # View current settings
   !ai         # View AI moderation settings
   !automod    # View automod settings
   ```

### Step 7: Manage Wordlists (Optional)

Review and customize wordlist configurations:

```bash
# View wordlist status
python -m guardden.cli.config wordlist info

# Edit wordlists directly:
nano config/wordlists/banned-words.yml
nano config/wordlists/domain-allowlists.yml
nano config/wordlists/external-sources.yml
```

## Post-Migration Tasks

### Backup Your Configuration

```bash
# Create backups of specific guilds
python -m guardden.cli.config guild backup 123456789

# Or backup the entire config directory
cp -r config config-backup-$(date +%Y%m%d)
```

### Version Control Setup

Add configuration to Git for version tracking:

```bash
# Initialize Git repository (if not already)
git init
git add config/
git commit -m "Add GuardDen file-based configuration"

# Create .gitignore to exclude backups
echo "config/backups/" >> .gitignore
```

### Clean Up Database (Optional)

**⚠️ WARNING: Only do this AFTER verifying migration is successful!**

```bash
# This permanently deletes old configuration from database
python -c "
import asyncio
from guardden.services.config_migration import ConfigurationMigrator
from guardden.services.database import Database
from guardden.services.guild_config import GuildConfigService  
from guardden.services.file_config import FileConfigurationManager

async def cleanup():
    db = Database('your-db-url')
    guild_service = GuildConfigService(db)
    file_manager = FileConfigurationManager()
    migrator = ConfigurationMigrator(db, guild_service, file_manager)
    
    # ⚠️ This deletes all guild settings from database
    results = await migrator.cleanup_database_configs(confirm=True)
    print(f'Cleaned up: {results}')
    await db.close()

asyncio.run(cleanup())
"
```

## Troubleshooting

### Common Issues

**1. Migration Failed for Some Guilds**
```bash
# Check the specific error messages
python -m guardden.cli.config migrate from-database

# Try migrating individual guilds if needed
# (This may require manual file creation)
```

**2. Configuration Validation Errors**
```bash
# Validate and see specific errors
python -m guardden.cli.config guild validate

# Common fixes:
# - Check YAML syntax (indentation, colons, quotes)
# - Verify Discord IDs are numbers, not strings
# - Ensure boolean values are true/false, not True/False
```

**3. Hot-Reload Not Working**
- Check bot logs for configuration errors
- Ensure YAML syntax is correct
- Verify file permissions are readable
- Restart bot if needed: `python -m guardden`

**4. Lost Configuration During Migration**
- Check `config/backups/` directory for backup files
- Database configurations are preserved during migration
- Re-run migration if needed: `python -m guardden.cli.config migrate from-database`

### Getting Help

**View CLI Help:**
```bash
python -m guardden.cli.config --help
python -m guardden.cli.config guild --help
python -m guardden.cli.config migrate --help
```

**Check Configuration Status:**
```bash
python -m guardden.cli.config guild list
python -m guardden.cli.config guild validate
python -m guardden.cli.config wordlist info
```

**Backup and Recovery:**
```bash
# Create backup before making changes
python -m guardden.cli.config guild backup <guild_id>

# Recovery from backup (manual file copy)
cp config/backups/guild-123456789_20260124_123456.yml config/guilds/guild-123456789.yml
```

## Configuration Examples

### NSFW-Only Filtering Setup

For gaming communities that want to allow violence but block sexual content:

```yaml
# config/guilds/guild-123456789.yml
ai_moderation:
  enabled: true
  sensitivity: 80
  nsfw_only_filtering: true       # Only block sexual content
  confidence_threshold: 0.7
  nsfw_detection_enabled: true
  log_only: false
```

### High-Security Server Setup

For family-friendly or professional servers:

```yaml
ai_moderation:
  enabled: true
  sensitivity: 95                 # Very strict
  nsfw_only_filtering: false      # Block all inappropriate content
  confidence_threshold: 0.6      # Lower threshold = more sensitive
  log_only: false

automod:
  message_rate_limit: 3           # Stricter rate limiting
  message_rate_window: 5
  duplicate_threshold: 2          # Less tolerance for duplicates
```

### Development/Testing Server Setup

For development or testing environments:

```yaml
ai_moderation:
  enabled: true
  sensitivity: 50                 # More lenient
  nsfw_only_filtering: false
  confidence_threshold: 0.8       # Higher threshold = less sensitive
  log_only: true                  # Only log, don't take action

automod:
  message_rate_limit: 10          # More relaxed limits
  message_rate_window: 5
```

## Benefits of File-Based Configuration

After migration, you'll enjoy:

1. **Easy Bulk Changes**: Edit multiple server configs at once
2. **Configuration as Code**: Version control your bot settings
3. **Environment Management**: Different configs for dev/staging/prod
4. **Disaster Recovery**: Easy backup and restore of all settings  
5. **No Discord Dependency**: Configure servers before bot joins
6. **Better Organization**: All settings in structured, documented files
7. **Hot-Reloading**: Changes apply instantly without restarts
8. **Schema Validation**: Automatic error checking prevents misconfigurations

**Welcome to the new GuardDen configuration system! 🎉**