chore: modularize command categories

Author: evolvewithevan

COG_MODULARIZATION.md

@@ -0,0 +1,131 @@
+# GitCord Cog Modularization
+
+This document describes the modularization of the original `general.py` cog into separate, focused cog files for better organization and maintainability.
+
+## Overview
+
+The original `general.py` file contained 1196 lines with mixed functionality. It has been split into four focused cog files:
+
+1. **`admin.py`** - Administrative Commands
+2. **`channels.py`** - Channel Management Commands  
+3. **`utility.py`** - Basic Utility Commands
+4. **`help.py`** - Help System
+
+## Cog Breakdown
+
+### 1. Admin Cog (`admin.py`)
+**Purpose**: Administrative utility commands requiring elevated permissions.
+
+**Commands**:
+- `!fetchurl <url>` (prefix) - Fetch and display text content from URLs
+- `/fetchurl <url>` (slash) - Slash command version of fetchurl
+- `!synccommands` (prefix) - Manually sync slash commands
+- `/synccommands` (slash) - Slash command version of synccommands
+
+**Permissions**: Administrator level required for all commands.
+
+**Error Handling**: Comprehensive error handlers for permission checks, network errors, and Discord API errors.
+
+### 2. Channels Cog (`channels.py`)
+**Purpose**: Channel and category management commands.
+
+**Commands**:
+- `!createchannel` (prefix) - Create a single channel from YAML configuration
+- `!createcategory` (prefix) - Create a category and its channels from YAML
+- `/createcategory [yaml_path]` (slash) - Slash command version with optional YAML path
+
+**Permissions**: Manage Channels permission required.
+
+**Features**:
+- YAML-based channel/category creation
+- Incremental updates for existing categories
+- Channel deletion logic via DeleteExtraChannelsView
+- Comprehensive error handling
+
+### 3. Utility Cog (`utility.py`)
+**Purpose**: Basic utility commands for general use.
+
+**Commands**:
+- `!hello` (prefix) - Simple greeting command
+- `!ping` (prefix) - Check bot latency
+- `/slashping` (slash) - Slash command latency check
+
+**Permissions**: No special permissions required.
+
+**Error Handling**: Basic error handling for utility commands.
+
+### 4. Help Cog (`help.py`)
+**Purpose**: Help system and documentation links.
+
+**Commands**:
+- `!help` (prefix) - Show help information and documentation links
+- `/help` (slash) - Slash command version of help
+
+**Features**:
+- Comprehensive help content
+- Documentation links to GitHub Wiki
+- Quick links to repository, issues, roadmap
+- Security policy links
+
+## File Structure
+
+```
+src/gitcord/cogs/
+├── __init__.py
+├── admin.py          # Administrative commands
+├── channels.py       # Channel management
+├── utility.py        # Basic utilities
+├── help.py          # Help system
+└── general.py       # Original file (can be removed)
+```
+
+## Bot Integration
+
+The `bot.py` file has been updated to load the new modularized cogs:
+
+```python
+async def _load_cogs(self) -> None:
+    """Load all bot cogs."""
+    # Load the modularized cogs
+    await self.load_extension("gitcord.cogs.admin")
+    await self.load_extension("gitcord.cogs.channels")
+    await self.load_extension("gitcord.cogs.utility")
+    await self.load_extension("gitcord.cogs.help")
+    logger.info("Loaded all modularized cogs")
+```
+
+## Benefits of Modularization
+
+1. **Separation of Concerns**: Each cog has a specific purpose and responsibility
+2. **Maintainability**: Easier to find and modify specific functionality
+3. **Scalability**: New cogs can be added without affecting existing ones
+4. **Code Organization**: Related commands are grouped together
+5. **Testing**: Individual cogs can be tested in isolation
+6. **Documentation**: Each cog can have its own documentation
+
+## Migration Notes
+
+- All original functionality has been preserved
+- Command names and behavior remain the same
+- Error handling has been maintained
+- Permission requirements are unchanged
+- The original `general.py` file can be safely removed after testing
+
+## Future Enhancements
+
+- Each cog can be extended independently
+- New cogs can be added for additional functionality (e.g., `git.py`, `moderation.py`)
+- Cog-specific configuration can be implemented
+- Individual cog reloading can be added for development
+
+## Testing
+
+To test the modularization:
+
+1. Ensure all cogs load without errors
+2. Verify all commands work as expected
+3. Check that error handling functions properly
+4. Confirm permission checks work correctly
+5. Test both prefix and slash command variants
+
+The modularization maintains full backward compatibility while providing a cleaner, more maintainable codebase structure. 

src/gitcord/bot.py

@@ -44,13 +44,15 @@ async def setup_hook(self) -> None:
 
     async def _load_cogs(self) -> None:
         """Load all bot cogs."""
-        # Load the general cog
-        await self.load_extension("gitcord.cogs.general")
-        logger.info("Loaded general cog")
+        # Load the modularized cogs
+        await self.load_extension("gitcord.cogs.admin")
+        await self.load_extension("gitcord.cogs.channels")
+        await self.load_extension("gitcord.cogs.utility")
+        await self.load_extension("gitcord.cogs.help")
+        logger.info("Loaded all modularized cogs")
 
         # Add more cogs here as they are created
         # await self.load_extension("gitcord.cogs.git")
-        # await self.load_extension("gitcord.cogs.admin")
 
     async def on_command_error(self, context, error):  # pylint: disable=arguments-differ
         """Global command error handler."""