megaproxy/Petbot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add development documentation and task tracking

Browse source 
- CLAUDE.md: Comprehensive development guide documenting patterns, conventions, and project structure
- TODO.md: Organized task list with completed items, bugs, enhancements, and feature ideas
- Both files provide context for future AI-assisted development sessions
- Includes testing procedures, coding standards, and architectural decisions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
megaproxy 2025-07-15 17:38:54 +01:00
parent c8cb99a4d0
commit f8ac661cd1
2 changed files with 503 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

296
CLAUDE.md Normal file
View file

@ -0,0 +1,296 @@
# 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. Testing and Validation
- Always run `python3 -c "import webserver; print('✅ syntax check')"` after webserver changes
- Test database operations with simple validation scripts
- Check IRC bot functionality with `python3 run_bot_debug.py`
- Verify web interface functionality through browser testing
## 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_debug.py # Bot startup and debug mode
├── help.html # Static help documentation
├── 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.

207
TODO.md Normal file
View file

@ -0,0 +1,207 @@
# TODO.md - PetBot Development Tasks
This file tracks completed work, pending bugs, enhancements, and feature ideas for the PetBot project.
## 📊 Summary
- **✅ Completed**: 14 items
- **🐛 Bugs**: 1 item
- **🔧 Enhancements**: 5 items
- **💡 Ideas**: 10 items
- **📋 Total**: 30 items tracked
---
## ✅ COMPLETED ITEMS
### High Priority Completed ✅
- [x] **Create unified theme and navigation bar for all webserver pages**
- Implemented comprehensive navigation system with hover dropdowns
- Added unified CSS variables and consistent styling across all pages
- Enhanced user experience with active page highlighting
- [x] **Fix petdex repetition of pets issue**
- Added DISTINCT to SQL queries to prevent database-level duplicates
- Resolved display issues showing multiple entries for same pets
- [x] **Fix exploration bug: prevent multiple !explore when encounter is active**
- Added state management to prevent multiple explores
- Users must resolve active encounters before exploring again
- [x] **Fix battle bug: prevent starting multiple battles from exploration encounters**
- Implemented proper encounter workflow enforcement
- Prevents race conditions in battle system
- [x] **Enforce exploration encounter workflow: must choose fight/capture/flee before exploring again**
- Added clear error messages for active encounters
- Improved game flow and state consistency
- [x] **Fix team builder drag-and-drop functionality and center alignment**
- Complete rewrite of team builder interface
- Working drag-and-drop between storage and numbered team slots (1-6)
- Proper center alignment with `max-width: 1200px; margin: 0 auto`
- Added double-click backup method for accessibility
- [x] **Implement IRC PIN delivery for team builder security**
- Added secure PIN verification system for team changes
- PINs sent via IRC private messages with 10-minute expiration
- Integrated bot instance with webserver for IRC messaging
### Medium Priority Completed ✅
- [x] **Redirect !items command to player profile URL instead of IRC response**
- Updated inventory commands to redirect to web interface
- Added #inventory jump points for direct section navigation
- Improved user experience with detailed web-based inventory management
- [x] **Add jump points to player page (/<playername>#inventory) for direct linking to sections**
- Implemented anchor links for direct navigation to specific sections
- Enhanced accessibility and user workflow
- [x] **Remove !swap command - team management moved to website**
- Streamlined pet management through unified web interface
- Removed redundant IRC command in favor of superior web experience
- [x] **Implement player team pet order persistence in database**
- Added team_order column with numbered slots (1-6)
- Database migration for existing players
- Persistent team ordering across sessions
- [x] **Fix !gym challenge to use player's current location instead of requiring location parameter**
- Simplified gym challenge workflow
- Uses player's current location automatically
- [x] **Update all project documentation (CHANGELOG.md, README.md, help.html)**
- Comprehensive documentation updates reflecting new features
- Updated help system with web interface integration
- Enhanced project documentation for contributors
### Low Priority Completed ✅
- [x] **Create CLAUDE.md file documenting development patterns and conventions**
- Comprehensive development guide for AI-assisted development
- Documents coding conventions, patterns, and project structure
- Useful reference for future development sessions
---
## 🐛 KNOWN BUGS
### Medium Priority Bugs 🔴
- [ ] **IRC connection monitoring and auto-reconnect functionality**
- Bot may lose connection without proper recovery
- Need robust reconnection logic with exponential backoff
- Monitor connection health and implement graceful reconnection
---
## 🔧 ENHANCEMENTS NEEDED
### High Priority Enhancements 🟠
- [ ] **Implement automated database backup system**
- Regular automated backups of SQLite database
- Backup rotation and retention policies
- Recovery procedures and testing
- [ ] **Conduct security audit of web interface and IRC bot**
- Review all user input validation
- Audit authentication and authorization mechanisms
- Test for common web vulnerabilities (XSS, CSRF, injection attacks)
- Review IRC bot security practices
### Medium Priority Enhancements 🟡
- [ ] **Add rate limiting to prevent command spam and abuse**
- Implement per-user rate limiting on IRC commands
- Web interface request throttling
- Graceful handling of rate limit violations
- [ ] **Implement comprehensive error logging and monitoring system**
- Structured logging with appropriate log levels
- Error tracking and alerting system
- Performance monitoring and metrics collection
- [ ] **Optimize database queries and web interface loading times**
- Database query performance analysis
- Add proper indexing for frequently accessed data
- Optimize web interface assets and loading times
- Implement caching where appropriate
---
## 💡 FEATURE IDEAS
### Medium Priority Ideas 🔵
- [ ] **Add mobile-responsive design to web interface for better mobile experience**
- Responsive CSS for mobile devices
- Touch-friendly drag-and-drop alternatives
- Mobile-optimized navigation and layouts
- [ ] **Enhance leaderboard with more categories (gym badges, rare pets, achievements)**
- Multiple leaderboard categories
- Filtering and sorting options
- Achievement-based rankings
- [ ] **Add auto-save draft functionality to team builder to prevent data loss**
- Local storage for unsaved team changes
- Recovery from browser crashes or accidental navigation
- Draft management and persistence
- [ ] **Add search and filter functionality to pet collection page**
- Search pets by name, type, level, or stats
- Advanced filtering options
- Sorting by various criteria
### Low Priority Ideas 🟢
- [ ] **Implement pet evolution system with evolution stones and level requirements**
- Evolution trees for existing pet species
- Evolution stones as rare items
- Level and friendship requirements for evolution
- [ ] **Add player-to-player pet trading system with web interface**
- Secure trading mechanism
- Trade history and verification
- Web-based trading interface
- [ ] **Add visual battle animations to web interface**
- Animated battle sequences
- Visual effects for different move types
- Enhanced battle experience
- [ ] **Add bulk actions for pet management (release multiple pets, mass healing)**
- Multi-select functionality for pet collections
- Bulk operations with confirmation dialogs
- Batch processing for efficiency
- [ ] **Add real-time achievement unlock notifications to web interface**
- WebSocket or SSE for real-time updates
- Toast notifications for achievements
- Achievement celebration animations
- [ ] **Add preset team configurations for different battle strategies**
- Pre-configured teams for different scenarios
- Team templates and sharing
- Strategic team building assistance
---
## 📝 Notes for Future Development
### Priorities for Next Development Session
1. **High Priority**: Address database backup system and security audit
2. **Medium Priority**: Implement rate limiting and error logging
3. **Feature Focus**: Mobile responsiveness and enhanced leaderboards
### Development Guidelines
- Follow patterns established in CLAUDE.md
- Test thoroughly before committing changes
- Update documentation with any new features
- Maintain modular architecture for easy feature additions
### Testing Checklist
- [ ] IRC bot functionality and command processing
- [ ] Web interface responsiveness and interaction
- [ ] Database operations and data integrity
- [ ] PIN verification and security features
- [ ] Cross-browser compatibility
---
*Last Updated: Current development session*
*Next Review: Before major feature additions*