feat: implement monolithic template support and deprecate legacy commands

- Introduced support for a new monolithic template format, allowing for more streamlined channel and category management.
- Updated the `!createchannel` and `!createcategory` commands to check for the new template format and provide deprecation warnings for legacy usage.
- Enhanced the template application process with detailed logging and error handling for better user feedback.
- Added functions to parse and validate the new template structure, ensuring robust configuration management.

Author: evolvewithevan

docs/src/user-guide/commands.md

@@ -29,7 +29,7 @@ Create one channel from a YAML file.
 
 **Permissions:** Manage Channels
 
-**Note:** Uses a fixed file path, This will be changed with the release of 1.X: `/home/user/Projects/gitcord-template/community/off-topic.yaml` 
+**Note:** Now uses dynamic template paths. For servers using the new monolithic template format, this command shows a deprecation warning and suggests using `!git pull` instead. 
 
 ### `!createcategory` / `/createcategory`
 Create a category with multiple channels.

src/gitcord/cogs/admin.py

@@ -484,6 +484,13 @@ def _download_and_extract_github(
     async def _apply_template_from_dir(
         self, guild, template_dir, ctx=None, interaction=None
     ):
+        """Apply template from directory - now looks for monolithic template.yaml first, falls back to legacy format."""
+        # Try monolithic template format first
+        template_path = os.path.join(template_dir, "template.yaml")
+        if os.path.exists(template_path):
+            return await self._apply_monolithic_template(guild, template_path, ctx, interaction)
+        
+        # Fall back to legacy directory-based format
         result_msgs = []
         template_category_names = set()
         template_channel_names = set()
@@ -671,6 +678,175 @@ async def _apply_template_from_dir(
             result_msgs.append(msg)
         return result_msgs
 
+    async def _apply_monolithic_template(self, guild, template_path, ctx=None, interaction=None):
+        """Apply a monolithic template.yaml file to the guild."""
+        from ..utils.helpers import parse_monolithic_template
+        
+        result_msgs = []
+        template_category_names = set()
+        
+        try:
+            template_config = parse_monolithic_template(template_path)
+        except Exception as e:
+            msg = f"❌ Failed to parse template: {e}"
+            self.logger.error(f"[apply_monolithic_template] {msg}")
+            result_msgs.append(msg)
+            return result_msgs
+        
+        # Log template info if available
+        if "server" in template_config:
+            server_info = template_config["server"]
+            if "name" in server_info:
+                msg = f"📋 Applying template: {server_info['name']}"
+                if "version" in server_info:
+                    msg += f" v{server_info['version']}"
+                self.logger.info(f"[apply_monolithic_template] {msg}")
+                result_msgs.append(msg)
+        
+        # Process each category
+        for category_config in template_config["categories"]:
+            category_name = category_config["name"]
+            template_category_names.add(category_name)
+            
+            # Create or update the category
+            existing_category = discord.utils.get(guild.categories, name=category_name)
+            if existing_category:
+                category = existing_category
+                msg = f"ℹ️ Category '{category_name}' already exists. Will update channels."
+            else:
+                category = await guild.create_category(
+                    name=category_name, position=category_config.get("position", 0)
+                )
+                msg = f"✅ Created category: {category_name}"
+            
+            self.logger.info(f"[apply_monolithic_template] {msg}")
+            result_msgs.append(msg)
+            
+            # Process channels in this category
+            created, updated, skipped = 0, 0, 0
+            template_channel_names = set()
+            
+            channels = category_config.get("channels", [])
+            for channel_config in channels:
+                channel_name = channel_config["name"]
+                template_channel_names.add(channel_name)
+                
+                # Check if channel exists
+                existing_channel = discord.utils.get(category.channels, name=channel_name)
+                channel_type = channel_config["type"].lower()
+                
+                if existing_channel:
+                    # Update topic/nsfw/position if needed
+                    update_kwargs = {}
+                    if (
+                        channel_type == "text"
+                        and hasattr(existing_channel, "topic")
+                        and existing_channel.topic != channel_config.get("topic", "")
+                    ):
+                        update_kwargs["topic"] = channel_config.get("topic", "")
+                    if (
+                        channel_type in ("text", "voice")
+                        and hasattr(existing_channel, "nsfw")
+                        and existing_channel.nsfw != channel_config.get("nsfw", False)
+                    ):
+                        update_kwargs["nsfw"] = channel_config.get("nsfw", False)
+                    if (
+                        "position" in channel_config
+                        and hasattr(existing_channel, "position")
+                        and existing_channel.position != channel_config["position"]
+                    ):
+                        update_kwargs["position"] = channel_config["position"]
+                    
+                    if update_kwargs:
+                        await existing_channel.edit(**update_kwargs)
+                        updated += 1
+                        msg = f"🔄 Updated channel: {existing_channel.name} in {category_name}"
+                    else:
+                        skipped += 1
+                        msg = f"⏭️ Skipped channel (no changes): {existing_channel.name} in {category_name}"
+                    
+                    self.logger.info(f"[apply_monolithic_template] {msg}")
+                    result_msgs.append(msg)
+                else:
+                    # Create new channel
+                    channel_kwargs = {
+                        "name": channel_config["name"],
+                        "category": category,
+                    }
+                    if "position" in channel_config:
+                        channel_kwargs["position"] = channel_config["position"]
+                    
+                    if channel_type == "text":
+                        if "topic" in channel_config:
+                            channel_kwargs["topic"] = channel_config["topic"]
+                        if "nsfw" in channel_config:
+                            channel_kwargs["nsfw"] = channel_config["nsfw"]
+                        await guild.create_text_channel(**channel_kwargs)
+                    elif channel_type == "voice":
+                        await guild.create_voice_channel(**channel_kwargs)
+                    else:
+                        msg = f"❌ Unknown channel type: {channel_type} for {channel_config['name']}"
+                        self.logger.error(f"[apply_monolithic_template] {msg}")
+                        result_msgs.append(msg)
+                        skipped += 1
+                        continue
+                    
+                    created += 1
+                    msg = f"✅ Created channel: {channel_config['name']} in {category_name}"
+                    self.logger.info(f"[apply_monolithic_template] {msg}")
+                    result_msgs.append(msg)
+            
+            # Check for extra channels in this category
+            extra_channels = [
+                ch for ch in category.channels if ch.name not in template_channel_names
+            ]
+            if extra_channels:
+                msg = f"⚠️ Extra channels not in template for category '{category_name}': {', '.join(ch.name for ch in extra_channels)}"
+                self.logger.warning(f"[apply_monolithic_template] {msg}")
+                result_msgs.append(msg)
+                view = DeleteExtraObjectsView(extra_channels, object_type_label="channel")
+                if interaction:
+                    await interaction.followup.send(msg, view=view)
+                elif ctx:
+                    await ctx.send(msg, view=view)
+            
+            summary = f"**{category_name}**: {created} created, {updated} updated, {skipped} skipped"
+            result_msgs.append(summary)
+        
+        # Check for extra categories
+        extra_categories = [
+            cat for cat in guild.categories if cat.name not in template_category_names
+        ]
+        if extra_categories:
+            msg = f"⚠️ Extra categories not in template: {', '.join(cat.name for cat in extra_categories)}"
+            self.logger.warning(f"[apply_monolithic_template] {msg}")
+            result_msgs.append(msg)
+            view = DeleteExtraObjectsView(extra_categories, object_type_label="category")
+            if interaction:
+                await interaction.followup.send(msg, view=view)
+            elif ctx:
+                await ctx.send(msg, view=view)
+        
+        # Check for orphan channels
+        orphan_channels = []
+        for ch in guild.channels:
+            if getattr(ch, "category", None) is None and isinstance(
+                ch, (discord.TextChannel, discord.VoiceChannel)
+            ):
+                orphan_channels.append(ch)
+        
+        if orphan_channels:
+            msg = f"⚠️ Uncategorized channels not in template: {', '.join(ch.name for ch in orphan_channels)}"
+            self.logger.warning(f"[apply_monolithic_template] {msg}")
+            result_msgs.append(msg)
+            view = DeleteExtraObjectsView(orphan_channels, object_type_label="channel")
+            if interaction:
+                await interaction.followup.send(msg, view=view)
+            elif ctx:
+                await ctx.send(msg, view=view)
+        
+        return result_msgs
+
 
 async def setup(bot: commands.Bot) -> None:
     """Set up the Admin cog."""

src/gitcord/cogs/channels.py

@@ -20,6 +20,7 @@
     create_channel_kwargs,
     create_channel_by_type,
     check_channel_exists,
+    get_template_path,
 )
 from ..utils import template_metadata
 from ..constants.paths import get_template_repo_dir
@@ -47,7 +48,14 @@ def __init__(self, bot: commands.Bot):
         self.logger.info("Channels cog loaded")
 
     def _get_template_path(self, guild_id: int, file_name: str = None, folder: str = None) -> Optional[str]:
-        """Get the template path for a guild, falling back to None if no template repo exists."""
+        """Get the template path for a guild, now looking for monolithic template.yaml first."""
+        
+        # Try the new monolithic template format first
+        template_path = get_template_path(guild_id)
+        if template_path:
+            return template_path
+        
+        # Fall back to legacy format if requested
         meta = template_metadata.load_metadata(guild_id)
         if not meta or not os.path.exists(meta.get("local_path", "")):
             return None
@@ -446,6 +454,14 @@ def _create_category_result_embed(self, result: CategoryResult) -> discord.Embed
     @commands.has_permissions(manage_channels=True)
     async def createchannel(self, ctx: commands.Context) -> None:
         """Create a channel based on properties defined in a YAML file."""
+        # Check if we have a monolithic template first
+        template_path = self._get_template_path(ctx.guild.id)
+        if template_path and template_path.endswith("template.yaml"):
+            await self.send_error(ctx, "⚠️ Command Deprecated", 
+                                "This server uses the new monolithic template format. Please use `!git pull` to apply the entire template instead of creating individual channels.")
+            return
+        
+        # Fall back to legacy format
         yaml_path = self._get_template_path(ctx.guild.id, "off-topic.yaml")
         if not yaml_path:
             await self.send_error(ctx, "❌ No Template Repository", 
@@ -462,6 +478,14 @@ async def createcategory(self, ctx: commands.Context) -> None:
             await self.send_error(ctx, "❌ Error", "Guild not found")
             return
 
+        # Check if we have a monolithic template first
+        template_path = self._get_template_path(guild.id)
+        if template_path and template_path.endswith("template.yaml"):
+            await self.send_error(ctx, "⚠️ Command Deprecated", 
+                                "This server uses the new monolithic template format. Please use `!git pull` to apply the entire template instead of creating individual categories.")
+            return
+
+        # Fall back to legacy format
         yaml_path = self._get_template_path(guild.id, "category.yaml")
         if not yaml_path:
             await self.send_error(ctx, "❌ No Template Repository", 
@@ -539,6 +563,18 @@ async def createcategory_slash(
 
         # Use default path if none provided
         if yaml_path is None:
+            # Check if we have a monolithic template first
+            template_path = self._get_template_path(guild.id)
+            if template_path and template_path.endswith("template.yaml"):
+                embed = create_embed(
+                    title="⚠️ Command Deprecated",
+                    description="This server uses the new monolithic template format. Please use `!git pull` to apply the entire template instead of creating individual categories.",
+                    color=discord.Color.orange(),
+                )
+                await interaction.followup.send(embed=embed)
+                return
+            
+            # Fall back to legacy format
             yaml_path = self._get_template_path(guild.id, "category.yaml")
             if not yaml_path:
                 embed = create_embed(

src/gitcord/utils/helpers.py

@@ -100,6 +100,114 @@ def format_time_delta(seconds: float) -> str:
     return f"{hours:.1f}h"
 
 
+def parse_monolithic_template(yaml_path: str) -> dict:
+    """Parse and validate the monolithic YAML template file."""
+    if not os.path.exists(yaml_path):
+        raise FileNotFoundError(f"Template file not found at: {yaml_path}")
+
+    try:
+        with open(yaml_path, "r", encoding="utf-8") as file:
+            template_config = yaml.safe_load(file)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML format: {e}") from e
+
+    if template_config is None:
+        raise ValueError("Template file is empty or invalid.")
+
+    # Validate required fields
+    if "categories" not in template_config:
+        raise ValueError("Missing required field: categories")
+
+    if not isinstance(template_config["categories"], list):
+        raise ValueError("categories must be a list")
+
+    # Validate each category
+    for i, category in enumerate(template_config["categories"]):
+        if not isinstance(category, dict):
+            raise ValueError(f"Category {i} must be a dictionary")
+        
+        required_category_fields = ["name", "type"]
+        for field in required_category_fields:
+            if field not in category:
+                raise ValueError(f"Category {i} missing required field: {field}")
+        
+        if "channels" in category:
+            if not isinstance(category["channels"], list):
+                raise ValueError(f"Category {i} channels must be a list")
+            
+            # Validate each channel in the category
+            for j, channel in enumerate(category["channels"]):
+                if not isinstance(channel, dict):
+                    raise ValueError(f"Category {i}, channel {j} must be a dictionary")
+                
+                required_channel_fields = ["name", "type"]
+                for field in required_channel_fields:
+                    if field not in channel:
+                        raise ValueError(f"Category {i}, channel {j} missing required field: {field}")
+
+    return template_config
+
+
+def parse_monolithic_template_from_str(yaml_str: str) -> dict:
+    """Parse and validate monolithic YAML template from a string."""
+    try:
+        template_config = yaml.safe_load(yaml_str)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML format: {e}") from e
+
+    if template_config is None:
+        raise ValueError("Template YAML is empty or invalid.")
+
+    # Validate required fields
+    if "categories" not in template_config:
+        raise ValueError("Missing required field: categories")
+
+    if not isinstance(template_config["categories"], list):
+        raise ValueError("categories must be a list")
+
+    # Validate each category
+    for i, category in enumerate(template_config["categories"]):
+        if not isinstance(category, dict):
+            raise ValueError(f"Category {i} must be a dictionary")
+        
+        required_category_fields = ["name", "type"]
+        for field in required_category_fields:
+            if field not in category:
+                raise ValueError(f"Category {i} missing required field: {field}")
+        
+        if "channels" in category:
+            if not isinstance(category["channels"], list):
+                raise ValueError(f"Category {i} channels must be a list")
+            
+            # Validate each channel in the category
+            for j, channel in enumerate(category["channels"]):
+                if not isinstance(channel, dict):
+                    raise ValueError(f"Category {i}, channel {j} must be a dictionary")
+                
+                required_channel_fields = ["name", "type"]
+                for field in required_channel_fields:
+                    if field not in channel:
+                        raise ValueError(f"Category {i}, channel {j} missing required field: {field}")
+
+    return template_config
+
+
+def get_template_path(guild_id: int) -> Optional[str]:
+    """Get the template path for a guild, looking for template.yaml in the root of the template repo."""
+    from .template_metadata import load_metadata
+    
+    meta = load_metadata(guild_id)
+    if not meta or not os.path.exists(meta.get("local_path", "")):
+        return None
+    
+    template_path = os.path.join(meta["local_path"], "template.yaml")
+    if os.path.exists(template_path):
+        return template_path
+    
+    return None
+
+
+# Legacy functions - kept for backward compatibility during transition
 def parse_channel_config(yaml_path: str) -> dict:
     """Parse and validate the YAML configuration file."""
     if not os.path.exists(yaml_path):