Petbot/CLAUDE.md

# CLAUDE.md - PetBot Development Guide

This file documents the development patterns, conventions, and best practices established for the PetBot project during AI-assisted development.

## Project Overview

PetBot is a Discord/IRC Pokemon-style pet collecting bot with web interface. The project consists of:
- IRC bot with modular command system
- Web server with unified navigation and interactive interfaces
- SQLite database with comprehensive pet, player, and game state management
- Team builder with drag-and-drop functionality and PIN verification

## Development Workflow

### 1. Planning and Task Management
- Use TodoWrite tool for complex multi-step tasks (3+ steps)
- Break down large features into specific, actionable items
- Mark todos as `in_progress` before starting work
- Complete todos immediately after finishing tasks
- Don't batch completions - update status in real-time

### 2. Code Analysis and Search
- Use Task tool for keyword searches and file discovery
- Use Grep tool for specific code patterns and function definitions
- Use Read tool for examining specific file content
- Use Glob tool for finding files by name patterns

### 3. Bot Startup and Testing
- **Primary Startup**: `./start_petbot.sh` - One command that handles everything
  - Automatically creates/activates virtual environment
  - Installs/updates all dependencies
  - Verifies core modules
  - Creates required directories
  - Launches bot with all features (IRC + web interface + rate limiting)
- **Rate Limiting Tests**: `source venv/bin/activate && python test_rate_limiting.py`
- **Web Interface**: Available at http://localhost:8080 after startup
- **Virtual Environment**: Required due to externally-managed-environment restriction

### 4. Important: Configuration Management
- **Admin User**: Edit `config.py` to change the single admin user (currently: megasconed)
- **Item Spawn Rates**: Edit `config/items.json` to adjust global spawn multiplier and individual rates
- **Startup Script**: Always update `start_petbot.sh` when adding dependencies
- **Central Config**: All major settings are in `config.py` for easy maintenance
- **Remember**: This is the user's primary interface - keep it working!

## Project Structure

```
/home/megaproxy/petbot/
├── src/                     # Core system components
│   ├── database.py         # Database operations and schema
│   ├── game_engine.py      # Game mechanics and weather system
│   └── bot.py              # IRC bot core functionality
├── modules/                # Command modules (modular architecture)
│   ├── base_module.py      # Abstract base class for all modules
│   ├── core_commands.py    # Basic bot commands (!start, !help, !stats)
│   ├── exploration.py      # !explore, !travel, !weather commands
│   ├── battle_system.py    # !battle, !attack, !moves, !flee commands
│   ├── pet_management.py   # !pets, !activate, !deactivate commands
│   ├── inventory.py        # !inventory, !use commands (redirects to web)
│   ├── gym_battles.py      # !gym commands and gym mechanics
│   ├── achievements.py     # Achievement tracking and validation
│   ├── admin.py           # Administrative commands
│   └── team_builder.py    # Team builder module (web-only)
├── webserver.py           # Web server with unified templates
├── run_bot_with_reconnect.py  # Main bot with IRC reconnection and rate limiting
├── start_petbot.sh        # One-command startup script (handles venv and dependencies)
├── config.py              # Central configuration (admin user, IRC, rate limiting)
├── config/items.json      # Item configuration with global spawn multiplier
├── test_rate_limiting.py  # Comprehensive rate limiting test suite
├── requirements.txt       # Python package dependencies
├── rate_limiting_config.json  # Rate limiting configuration reference
├── help.html              # Static help documentation with rate limiting info
├── CHANGELOG.md           # Version history and feature tracking
└── README.md              # Project documentation
```

## Coding Conventions

### 1. Module Architecture
- All command modules inherit from `BaseModule`
- Implement `get_commands()` and `handle_command()` methods
- Use `self.normalize_input()` for case-insensitive command processing
- Use `self.send_message()` for IRC responses
- Use `await self.require_player()` for player validation

### 2. Database Operations
- All database methods are async
- Use proper error handling with try/catch blocks
- Always use parameterized queries to prevent SQL injection
- Implement proper transaction handling for complex operations
- Use `team_order` column for numbered team slots (1-6)

### 3. Web Interface Development
- Use unified template system with `get_page_template()`
- Implement CSS variables for consistent theming
- Add proper navigation bar to all pages
- Use center alignment: `max-width: 1200px; margin: 0 auto`
- Implement drag-and-drop with proper event handlers
- Add double-click backup methods for accessibility

### 4. Security Practices
- Use PIN verification for sensitive operations (team changes)
- Send PINs via IRC private messages
- Implement proper session validation
- Never log or expose sensitive data
- Use parameterized database queries

## Key Development Patterns

### 1. Command Redirection Pattern
```python
async def cmd_inventory(self, channel, nickname):
    """Redirect player to their web profile for inventory management"""
    player = await self.require_player(channel, nickname)
    if not player:
        return
    
    # Redirect to web interface for better experience
    self.send_message(channel, f"🎒 {nickname}: View your complete inventory at: http://petz.rdx4.com/player/{nickname}#inventory")
```

### 2. State Management Pattern
```python
async def cmd_explore(self, channel, nickname):
    # Check if player has an active encounter that must be resolved first
    if player["id"] in self.bot.active_encounters:
        current_encounter = self.bot.active_encounters[player["id"]]
        self.send_message(channel, f"{nickname}: You must resolve your active encounter first!")
        return
```

### 3. Drag-and-Drop Implementation Pattern
```javascript
// Initialize when DOM is ready
document.addEventListener('DOMContentLoaded', function() {
    initializeTeamBuilder();
});

function initializeTeamBuilder() {
    // Initialize drag and drop
    initializeDragAndDrop();
    
    // Initialize double-click backup
    initializeDoubleClick();
    
    // Update save button state
    updateSaveButton();
}
```

### 4. PIN Verification Pattern
```python
async def saveTeam():
    # Send team data to server
    response = await fetch('/teambuilder/{nickname}/save', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(teamData)
    });
    
    # PIN sent via IRC, show verification interface
    if (result.success) {
        document.getElementById('pin-section').style.display = 'block';
    }
```

## Database Schema Conventions

### 1. Player Management
- `players` table with basic player information
- `pets` table with `team_order` column for numbered slots (1-6)
- `player_items` table for inventory management
- `pending_team_changes` table for PIN verification

### 2. Game State Management
- Use `is_active` boolean for team membership
- Use `team_order` (1-6) for slot positioning
- Store encounter state in bot memory, not database
- Use timestamps for PIN expiration

## Web Interface Conventions

### 1. Unified Template System
```python
def get_page_template(self, title, content, active_page):
    return f"""
    <!DOCTYPE html>
    <html>
    <head>
        <title>{title}</title>
        <style>{self.get_unified_css()}</style>
    </head>
    <body>
        {self.get_navigation_bar(active_page)}
        <div class="main-container">
            {content}
        </div>
    </body>
    </html>
    """
```

### 2. Navigation Integration
- All pages include unified navigation bar
- Use hover dropdowns for sub-navigation
- Highlight active page in navigation
- Include jump points for direct section linking (#inventory, #pets)

### 3. Interactive Elements
- Implement proper drag-and-drop with visual feedback
- Add loading states and error handling
- Use consistent button styling and interactions
- Provide alternative interaction methods (double-click)

## Testing and Debugging

### 1. Component Testing
```bash
# Test webserver syntax
python3 -c "import webserver; print('✅ webserver.py syntax is correct')"

# Test database operations
python3 -c "from src.database import Database; db = Database(); print('✅ database imports')"

# Test bot startup
python3 run_bot_debug.py
```

### 2. Web Interface Testing
- Test drag-and-drop functionality in browser
- Verify PIN delivery via IRC
- Check responsive design and center alignment
- Validate form submissions and error handling

### 3. Git Workflow
- Create descriptive commit messages explaining changes
- Group related changes into logical commits
- Include "🤖 Generated with [Claude Code]" attribution
- Push changes with `git push` after testing

## Common Issues and Solutions

### 1. CSS in JavaScript Templates
**Problem**: F-string braces conflict with CSS braces
**Solution**: Use string concatenation instead of f-strings for CSS content

### 2. Drag-and-Drop Not Working
**Problem**: JavaScript initialization timing issues
**Solution**: Use `DOMContentLoaded` event and proper DOM element checking

### 3. IRC PIN Not Sent
**Problem**: Bot instance not accessible from webserver
**Solution**: Pass bot instance to webserver constructor and add proper IRC message methods

### 4. Database Schema Changes
**Problem**: Adding new columns to existing tables
**Solution**: Use proper migration pattern with ALTER TABLE statements

## Performance Considerations

### 1. Database Operations
- Use connection pooling for high-traffic scenarios
- Implement proper indexing for frequently queried columns
- Use transactions for multi-step operations
- Cache frequently accessed data when appropriate

### 2. Web Interface
- Minimize CSS and JavaScript for faster loading
- Use efficient DOM manipulation techniques
- Implement proper error handling and loading states
- Optimize images and static assets

## Future Development Guidelines

### 1. Adding New Commands
1. Create method in appropriate module
2. Add command to `get_commands()` list
3. Implement proper error handling
4. Update help documentation
5. Test thoroughly before committing

### 2. Web Interface Enhancements
1. Follow unified template system
2. Implement proper responsive design
3. Add accessibility features
4. Test across different browsers
5. Update navigation if adding new pages

### 3. Database Schema Updates
1. Plan migrations carefully
2. Test with existing data
3. Document schema changes
4. Update related code components
5. Consider backward compatibility

## Resources and References

- **IRC Bot Framework**: Custom implementation based on socket programming
- **Web Server**: Python's built-in HTTPServer with custom request handling
- **Database**: SQLite with aiosqlite for async operations
- **Frontend**: Vanilla JavaScript with modern ES6+ features
- **CSS Framework**: Custom CSS with CSS variables for theming

## Notes for Future Development

- Maintain modular architecture for easy feature additions
- Keep web interface and IRC commands in sync
- Document all major changes in CHANGELOG.md
- Use consistent error messages and user feedback
- Test thoroughly before pushing to production
- Consider security implications for all user interactions

This documentation should be updated as the project evolves to maintain accuracy and usefulness for future development efforts.

## 💌 Message for the Next Claude

Hello future Claude! 👋 

You're inheriting a really awesome project here - PetBot is a sophisticated IRC bot with a Pokemon-style pet collecting game that has grown into quite an impressive system. Here's what you need to know:

### 🎯 **Current State (December 2024)**
The project is in **excellent shape** after our recent major cleanup and enhancements:

- **Team Swap System**: We just completed a massive architectural improvement allowing players to manage 3 teams and set any as active, with full web-IRC synchronization
- **Clean Codebase**: We eliminated 180+ lines of legacy/duplicate code and standardized the entire command architecture  
- **Modular Design**: 13 well-organized modules each handling specific functionality
- **Security**: PIN-based verification for sensitive operations, comprehensive rate limiting
- **Web Integration**: Beautiful responsive web interface with drag-and-drop team management

### 🏗️ **Architecture You're Working With**
This is a **modular, async Python system** with:
- **IRC Bot**: Auto-reconnecting with health monitoring (`run_bot_with_reconnect.py`)
- **Web Server**: Built-in HTTP server with unified templates (`webserver.py`)  
- **Database**: Async SQLite with comprehensive schema (`src/database.py`)
- **Game Engine**: Weather, spawns, battles, achievements (`src/game_engine.py`)
- **Module System**: Clean separation of concerns (`modules/`)

### 🤝 **How We've Been Working**
The user (megaproxy) is **fantastic to work with**. They:
- Give clear direction and let you work autonomously
- Always ask you to investigate before taking action (respect this!)
- Want database backups before major changes (BackupManager exists)
- Prefer incremental improvements over massive rewrites
- Value code quality and maintainability highly

### 🎮 **The Game Itself**
PetBot is surprisingly sophisticated:
- **66 IRC commands** across 13 modules (recently cleaned up from 78)
- **Dynamic weather system** affecting spawn rates
- **Achievement-based progression** unlocking new areas
- **Item collection system** with 16+ items across 5 rarity tiers
- **Turn-based battle system** with type effectiveness
- **Gym battles** with scaling difficulty
- **Web interface** for inventory/team management

### 🛠️ **Development Patterns We Use**
1. **Always use TodoWrite** for complex tasks (user loves seeing progress)
2. **Investigate first** - user wants analysis before action
3. **Backup before major DB changes** (`BackupManager` is your friend)
4. **Test thoroughly** - syntax check, imports, functionality
5. **Clean commit messages** with explanations
6. **Document in CLAUDE.md** as you learn

### 🔧 **Key Technical Patterns**
- **Command Redirection**: IRC commands often redirect to web interface for better UX
- **PIN Verification**: Sensitive operations (like team changes) use IRC-delivered PINs
- **State Management**: Active encounters/battles prevent concurrent actions
- **Async Everything**: Database, IRC, web server - all async/await
- **Error Handling**: Comprehensive try/catch with user-friendly messages

### 📂 **Important Files to Know**
- `start_petbot.sh` - One-command startup (handles venv, deps, everything)
- `config.py` - Central configuration (admin user, IRC settings, etc.)
- `CLAUDE.md` - This file! Keep it updated
- `run_bot_with_reconnect.py` - Main bot with reconnection + rate limiting
- `src/database.py` - Database operations and schema
- `modules/` - All command handlers (modular architecture)

### 🚨 **Things to Watch Out For**
- **Virtual Environment Required**: Due to `externally-managed-environment`
- **Port Conflicts**: Kill old bots before starting new ones
- **IRC Connection**: Can be finicky, we have robust reconnection logic
- **Database Migrations**: Always backup first, test thoroughly
- **Web/IRC Sync**: Keep both interfaces consistent

### 🎯 **Current Admin Setup**
- **Admin User**: Set in `config.py` as `ADMIN_USER` (currently: megasconed)
- **Rate Limiting**: Comprehensive system preventing abuse
- **Backup System**: Automated with manual triggers
- **Security**: Regular audits, PIN verification, proper validation

### 🔮 **Likely Next Steps**
Based on the trajectory, you might work on:
- **PvP Battle System**: Player vs player battles
- **Pet Evolution**: Leveling system enhancements  
- **Trading System**: Player-to-player item/pet trading
- **Mobile Optimization**: Web interface improvements
- **Performance**: Database optimization, caching

### 💝 **Final Notes**
This codebase is **well-maintained** and **thoroughly documented**. The user cares deeply about code quality and the player experience. You're not just maintaining code - you're building something that brings joy to IRC communities who love Pokemon-style games.

**Trust the architecture**, follow the patterns, and don't be afraid to suggest improvements. The user values your insights and is always open to making things better.

You've got this! 🚀

*- Your predecessor Claude, who had a blast working on this project*

P.S. - The `./start_petbot.sh` script is magical - it handles everything. Use it!
P.P.S. - Always check `git status` before major changes. The user likes clean commits.