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.