feat: implement core bot infrastructure and monitoring system

tux/app.py

@@ -1,17 +1,28 @@
-"""TuxApp: Orchestration and lifecycle management for the Tux Discord bot."""
+"""
+TuxApp: Main application entrypoint and lifecycle orchestrator.
+
+This module contains the `TuxApp` class, which serves as the primary entrypoint
+for the Tux Discord bot. It is responsible for:
+
+- **Environment Setup**: Validating configuration, initializing Sentry, and setting
+  up OS-level signal handlers for graceful shutdown.
+- **Bot Instantiation**: Creating the instance of the `Tux` bot class with the
+  appropriate intents, command prefix logic, and owner IDs.
+- **Lifecycle Management**: Starting the asyncio event loop and managing the
+  bot's main `start` and `shutdown` sequence, including handling `KeyboardInterrupt`.
+"""
 
 import asyncio
 import signal
-from types import FrameType
+import sys
 
 import discord
-import sentry_sdk
 from loguru import logger
 
 from tux.bot import Tux
 from tux.help import TuxHelp
 from tux.utils.config import CONFIG
-from tux.utils.env import get_current_env
+from tux.utils.sentry_manager import SentryManager
 
 
 async def get_prefix(bot: Tux, message: discord.Message) -> list[str]:
@@ -28,129 +39,145 @@
 
 
 class TuxApp:
-    """Orchestrates the startup, shutdown, and environment for the Tux bot."""
+    """
+    Orchestrates the startup, shutdown, and environment for the Tux bot.
 
-    def __init__(self):
-        """Initialize the TuxApp with no bot instance yet."""
-        self.bot = None
+    This class is not a `discord.py` cog, but rather a top-level application
+    runner that manages the bot's entire lifecycle from an OS perspective.
+    """
 
-    def run(self) -> None:
-        """Run the Tux bot application (entrypoint for CLI)."""
-        asyncio.run(self.start())
+    # --- Initialization ---
 
-    def setup_sentry(self) -> None:
-        """Initialize Sentry for error monitoring and tracing."""
-        if not CONFIG.SENTRY_DSN:
-            logger.warning("No Sentry DSN configured, skipping Sentry setup")
-            return
-
-        logger.info("Setting up Sentry...")
-
-        try:
-            sentry_sdk.init(
-                dsn=CONFIG.SENTRY_DSN,
-                release=CONFIG.BOT_VERSION,
-                environment=get_current_env(),
-                enable_tracing=True,
-                attach_stacktrace=True,
-                send_default_pii=False,
-                traces_sample_rate=1.0,
-                profiles_sample_rate=1.0,
-                _experiments={
-                    "enable_logs": True,  # https://docs.sentry.io/platforms/python/logs/
-                },
-            )
+    def __init__(self):
+        """Initializes the TuxApp, setting the bot instance to None initially."""
+        self.bot: Tux | None = None
 
-            # Add additional global tags
-            sentry_sdk.set_tag("discord_library_version", discord.__version__)
+    # --- Application Lifecycle ---
 
-            logger.info(f"Sentry initialized: {sentry_sdk.is_initialized()}")
+    def run(self) -> None:
+        """
+        The main synchronous entrypoint for the application.
 
-        except Exception as e:
-            logger.error(f"Failed to initialize Sentry: {e}")
-
-    def setup_signals(self) -> None:
-        """Set up signal handlers for graceful shutdown."""
-        signal.signal(signal.SIGTERM, self.handle_sigterm)
-        signal.signal(signal.SIGINT, self.handle_sigterm)
-
-    def handle_sigterm(self, signum: int, frame: FrameType | None) -> None:
-        """Handle SIGTERM/SIGINT by raising KeyboardInterrupt for graceful shutdown."""
-        logger.info(f"Received signal {signum}")
-
-        if sentry_sdk.is_initialized():
-            with sentry_sdk.push_scope() as scope:
-                scope.set_tag("signal.number", signum)
-                scope.set_tag("lifecycle.event", "termination_signal")
-
-                sentry_sdk.add_breadcrumb(
-                    category="lifecycle",
-                    message=f"Received termination signal {signum}",
-                    level="info",
-                )
+        This method starts the asyncio event loop and runs the primary `start`
+        coroutine, effectively launching the bot.
+        """
+        asyncio.run(self.start())
 
-        raise KeyboardInterrupt
+    async def start(self) -> None:
+        """
+        The main asynchronous entrypoint for the application.
 
-    def validate_config(self) -> bool:
-        """Validate that all required configuration is present."""
-        if not CONFIG.BOT_TOKEN:
-            logger.critical("No bot token provided. Set DEV_BOT_TOKEN or PROD_BOT_TOKEN in your .env file.")
-            return False
+        This method orchestrates the entire bot startup sequence: setting up
+        Sentry and signal handlers, validating config, creating the `Tux`
+        instance, and connecting to Discord. It includes a robust
+        try/except/finally block to ensure graceful shutdown.
+        """
 
-        return True
+        # Initialize Sentry
+        SentryManager.setup()
 
-    async def start(self) -> None:
-        """Start the Tux bot, handling setup, errors, and shutdown."""
-        self.setup_sentry()
-
-        self.setup_signals()
+        # Set up signal handlers using the event loop for cross-platform compatibility
+        loop = asyncio.get_event_loop()
+        self.setup_signals(loop)
 
+        # Validate config
         if not self.validate_config():
             return
 
+        # Configure owner IDs, dynamically adding sysadmins if configured.
+        # This allows specified users to have access to sensitive commands like `eval`.
         owner_ids = {CONFIG.BOT_OWNER_ID}
-
         if CONFIG.ALLOW_SYSADMINS_EVAL:
             logger.warning(
-                "⚠️ Eval is enabled for sysadmins, this is potentially dangerous; see settings.yml.example for more info.",
+                "⚠️ Eval is enabled for sysadmins, this is potentially dangerous; "
+                "see settings.yml.example for more info.",
             )
             owner_ids.update(CONFIG.SYSADMIN_IDS)
-
         else:
             logger.warning("🔒️ Eval is disabled for sysadmins; see settings.yml.example for more info.")
 
+        # Instantiate the main bot class with all necessary parameters.
         self.bot = Tux(
             command_prefix=get_prefix,
             strip_after_prefix=True,
             case_insensitive=True,
             intents=discord.Intents.all(),
-            # owner_ids={CONFIG.BOT_OWNER_ID, *CONFIG.SYSADMIN_IDS},
             owner_ids=owner_ids,
             allowed_mentions=discord.AllowedMentions(everyone=False),
             help_command=TuxHelp(),
             activity=None,
             status=discord.Status.online,
         )
 
+        # Start the bot
         try:
+            # This is the main blocking call that connects to Discord and runs the bot.
             await self.bot.start(CONFIG.BOT_TOKEN, reconnect=True)
 
         except KeyboardInterrupt:
+            # This is caught when the user presses Ctrl+C.
             logger.info("Shutdown requested (KeyboardInterrupt)")
         except Exception as e:
-            logger.critical(f"Bot failed to start: {e}")
-            await self.shutdown()
-
+            # Catch any other unexpected exception during bot runtime.
+            logger.critical(f"Bot failed to start or run: {e}")
         finally:
+            # Ensure that shutdown is always called to clean up resources.
             await self.shutdown()
 
     async def shutdown(self) -> None:
-        """Gracefully shut down the bot and flush Sentry."""
+        """
+        Gracefully shuts down the bot and its resources.
+
+        This involves calling the bot's internal shutdown sequence and then
+        flushing any remaining Sentry events to ensure all data is sent.
+        """
         if self.bot and not self.bot.is_closed():
             await self.bot.shutdown()
 
-        if sentry_sdk.is_initialized():
-            sentry_sdk.flush()
-            await asyncio.sleep(0.1)
+        await SentryManager.flush_async()
+        await asyncio.sleep(0.1)  # Brief pause to allow buffers to flush
 
         logger.info("Shutdown complete")
+
+    # --- Environment Setup ---
+
+    def setup_signals(self, loop: asyncio.AbstractEventLoop) -> None:
+        """
+        Sets up OS-level signal handlers for graceful shutdown using the event loop for better cross-platform compatibility.
+
+        Note: loop.add_signal_handler may not be available on all platforms (e.g., Windows for some signals).
+        """
+
+        def handle_sigterm() -> None:
+            SentryManager.report_signal(signal.SIGTERM, None)
+
+        def handle_sigint() -> None:
+            SentryManager.report_signal(signal.SIGINT, None)
+
+        try:
+            loop.add_signal_handler(signal.SIGTERM, handle_sigterm)
+            loop.add_signal_handler(signal.SIGINT, handle_sigint)
+        except NotImplementedError:
+            # Fallback for platforms that do not support add_signal_handler (e.g., Windows)
+            signal.signal(signal.SIGINT, SentryManager.report_signal)
+            signal.signal(signal.SIGTERM, SentryManager.report_signal)
+            if sys.platform.startswith("win"):
+                # Document limitation
+                logger.warning(
+                    "Warning: Signal handling is limited on Windows. Some signals may not be handled as expected.",
+                )
+
+    def validate_config(self) -> bool:
+        """
+        Performs a pre-flight check for essential configuration.
+
+        Returns
+        -------
+        bool
+            True if the configuration is valid, False otherwise.
+        """
+        if not CONFIG.BOT_TOKEN:
+            logger.critical("No bot token provided. Set DEV_BOT_TOKEN or PROD_BOT_TOKEN in your .env file.")
+            return False
+
+        return True