Load commands via entrypoints, enforce backend compatibility

Signed-off-by: Tim Paine <3105306+timkpaine@users.noreply.github.com>

Author: timkpaine

csp_bot/bot.py

@@ -12,6 +12,7 @@
 
 import asyncio
 import html
+import importlib.metadata as importlib_metadata
 import re
 import threading
 import time
@@ -88,6 +89,8 @@ class Bot(GatewayModule):
     _thread: Optional[threading.Thread] = PrivateAttr(None)
     _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
 
+    _KNOWN_BACKENDS: Set[str] = {"discord", "slack", "symphony", "telegram"}
+
     def set_deps(self, deps: Any) -> None:
         """Set shared dependency object for new command framework contexts."""
         self._deps = deps
@@ -334,6 +337,8 @@ def load_commands(self, command_models: List[Any]) -> None:
         Supports both legacy BaseCommandModel and the new CommandModel.
         """
         log.info(f"Loading {len(command_models)} commands...")
+        self._load_entrypoint_commands()
+        active_backends = self._active_backends()
         for model in command_models:
             try:
                 command = model.command()
@@ -350,6 +355,9 @@ def load_commands(self, command_models: List[Any]) -> None:
             else:
                 raise TypeError(f"Unsupported command type from model {type(model).__name__}: {type(command).__name__}")
 
+            if not self._is_command_backend_compatible(command_str, runner, active_backends):
+                continue
+
             log.info(f"Registered command: /{command_str}")
             if command_str in self._commands:
                 raise Exception(f"Command already registered: {command_str}\n\t{command}\n\t{self._commands[command_str]}")
@@ -362,9 +370,86 @@ def load_commands(self, command_models: List[Any]) -> None:
         for command_name, entry in get_registered_commands().items():
             if command_name in self._commands:
                 continue
+            if not self._is_command_backend_compatible(command_name, entry, active_backends):
+                continue
             log.info(f"Registered decorated command: /{command_name}")
             self._commands[command_name] = entry
 
+    def _load_entrypoint_commands(self) -> None:
+        """Load command plugins from Python entry points.
+
+        Entry points in the ``csp_bot.commands`` group are imported so they can
+        register commands through decorators or module import side effects.
+        If the loaded object is callable, it is invoked with no arguments.
+        """
+        try:
+            try:
+                entry_points = importlib_metadata.entry_points(group="csp_bot.commands")
+            except TypeError:
+                all_entry_points = importlib_metadata.entry_points()
+                entry_points = all_entry_points.get("csp_bot.commands", [])
+        except Exception:
+            log.exception("Failed to discover csp_bot.commands entry points")
+            return
+
+        for entry_point in entry_points:
+            try:
+                loaded = entry_point.load()
+            except Exception:
+                log.exception("Failed to load command entry point: %s", getattr(entry_point, "name", "<unknown>"))
+                continue
+
+            if callable(loaded):
+                try:
+                    loaded()
+                except Exception:
+                    log.exception("Failed to initialize command entry point: %s", getattr(entry_point, "name", "<unknown>"))
+                    continue
+
+            log.info("Loaded command entry point: %s", getattr(entry_point, "name", "<unknown>"))
+
+    def _active_backends(self) -> Set[str]:
+        """Return configured backends for this bot instance."""
+        active: Set[str] = set()
+        if self.config.discord:
+            active.add("discord")
+        if self.config.slack:
+            active.add("slack")
+        if self.config.symphony:
+            active.add("symphony")
+        return active
+
+    def _normalize_command_backends(self, command_name: str, backends: List[str]) -> List[str]:
+        """Normalize and validate declared command backends."""
+        normalized = [b.lower() for b in backends]
+        unknown = sorted({b for b in normalized if b not in self._KNOWN_BACKENDS})
+        if unknown:
+            raise ValueError(f"Command '{command_name}' declared unknown backends: {', '.join(unknown)}")
+        return normalized
+
+    def _is_command_backend_compatible(self, command_name: str, command_runner: Any, active_backends: Set[str]) -> bool:
+        """Check registration-time backend compatibility for a command."""
+        declared_backends = self._command_backends(command_runner)
+        if not declared_backends:
+            return True
+
+        normalized = self._normalize_command_backends(command_name, declared_backends)
+
+        # If no backends are configured yet, keep command registration permissive.
+        if not active_backends:
+            return True
+
+        if active_backends.intersection(normalized):
+            return True
+
+        log.info(
+            "Skipping command /%s: declared backends %s do not match active backends %s",
+            command_name,
+            normalized,
+            sorted(active_backends),
+        )
+        return False
+
     def _command_backends(self, command_runner: Any) -> List[str]:
         """Return supported backends for either legacy or new command types."""
         if isinstance(command_runner, BaseCommand):
@@ -394,10 +479,6 @@ def _build_command_context(self, cmd: BotCommand) -> CommandContext:
             deps=self._deps,
         )
 
-    # =========================================================================
-    # Message Processing Nodes
-    # =========================================================================
-
     @csp.node
     def _process_incoming_messages(self, msg: ts[Message]) -> Outputs(bot_commands=ts[[BotCommand]], unauthorized_message=ts[Message]):
         """Process incoming messages to extract bot commands.
@@ -521,10 +602,6 @@ def _handle_commands(self, cmd: ts[BotCommand]) -> Outputs(messages=ts[[Message]
 
             csp.schedule_alarm(a_ratelimit, timedelta(seconds=self.config.ratelimit_seconds), True)
 
-    # =========================================================================
-    # Message Analysis using chatom
-    # =========================================================================
-
     def _is_message_to_bot(self, msg: Message, backend: str) -> Tuple[bool, str, str, List[User]]:
         """Check if a message is directed at the bot.
 
@@ -713,10 +790,6 @@ def _is_authorized(self, msg: Message, backend: str) -> bool:
             authorized = self._authorized_users.get(backend, set())
             return author_id in authorized
 
-    # =========================================================================
-    # Command Extraction and Execution
-    # =========================================================================
-
     def _extract_commands(
         self,
         msg: Message,

csp_bot/commands/echo.py

@@ -36,8 +36,7 @@ def execute(self, command: BotCommand) -> Optional[Message]:
 
         # Add mentions for any tagged users
         if command.targets:
-            users = [t.to_chatom_user() if hasattr(t, "to_chatom_user") else t for t in command.targets]
-            mentions = mention_users(users, command.backend)
+            mentions = mention_users(list(command.targets), command.backend)
             if mentions:
                 content = f"{content} {mentions}".strip()
 

csp_bot/tests/test_bot_integration.py

@@ -17,7 +17,7 @@
 from csp_bot import Bot, BotCommand, BotConfig, BotMessage
 from csp_bot.bot_config import SymphonyConfig
 from csp_bot.commands import HelpCommand, ReplyToOtherCommand
-from csp_bot.commands.framework import Command, clear_registry, command
+from csp_bot.commands.framework import Command, CommandModel, clear_registry, command
 from csp_bot.structs import CommandVariant
 
 # Test Fixtures
@@ -371,6 +371,116 @@ def execute(self, ctx):
         assert results[0].content == "token=abc123"
 
 
+class TestRegistrationTimeBackendPolicy:
+    """Tests for registration-time backend compatibility checks."""
+
+    def setup_method(self):
+        clear_registry()
+
+    def teardown_method(self):
+        clear_registry()
+
+    def test_decorated_command_skipped_when_backend_not_active(self, bot_with_symphony):
+        """Commands limited to inactive backends should not be registered."""
+
+        @command(name="slack_only", help="Slack only", backends=["slack"])
+        def slack_only(ctx):
+            return "nope"
+
+        bot_with_symphony.load_commands([])
+
+        assert "slack_only" not in bot_with_symphony._commands
+
+    def test_decorated_command_registered_when_backend_active(self, bot_with_symphony):
+        """Commands limited to active backends should be registered."""
+
+        @command(name="symphony_only", help="Symphony only", backends=["symphony"])
+        def symphony_only(ctx):
+            return "ok"
+
+        bot_with_symphony.load_commands([])
+
+        assert "symphony_only" in bot_with_symphony._commands
+
+    def test_invalid_backend_name_raises_on_registration(self, bot_with_symphony):
+        """Unknown backend names should fail fast during registration."""
+
+        @command(name="bad_backend", help="Bad backend", backends=["not-a-backend"])
+        def bad_backend(ctx):
+            return "nope"
+
+        with pytest.raises(ValueError, match="unknown backends"):
+            bot_with_symphony.load_commands([])
+
+    def test_model_command_skipped_when_backend_not_active(self, bot_with_symphony):
+        """Model-loaded commands should obey registration-time backend filtering."""
+
+        class SlackOnlyCommand(Command):
+            name: str = "model_slack_only"
+            help: str = "Slack-only model command"
+            backends: list[str] = ["slack"]
+
+            def execute(self, ctx):
+                return "nope"
+
+        model = CommandModel(command=SlackOnlyCommand)
+        bot_with_symphony.load_commands([model])
+
+        assert "model_slack_only" not in bot_with_symphony._commands
+
+
+class TestEntryPointCommandDiscovery:
+    """Tests for plugin command discovery through Python entry points."""
+
+    def setup_method(self):
+        clear_registry()
+
+    def teardown_method(self):
+        clear_registry()
+
+    def test_load_commands_discovers_entrypoint_registered_command(self, bot_with_symphony):
+        """Entry-point loader should import plugin and register its decorated command."""
+
+        def register_plugin_command():
+            @command(name="from_ep", help="Registered from entry point")
+            def from_ep(ctx):
+                return "ok"
+
+        entry_point = MagicMock()
+        entry_point.name = "plugin.from_ep"
+        entry_point.load.return_value = register_plugin_command
+
+        with patch("csp_bot.bot.importlib_metadata.entry_points", return_value=[entry_point]):
+            bot_with_symphony.load_commands([])
+
+        assert "from_ep" in bot_with_symphony._commands
+
+    def test_model_command_precedence_over_entrypoint_command(self, bot_with_symphony):
+        """Explicit model registration should win when entry point uses same command name."""
+
+        def register_plugin_command():
+            @command(name="clash", help="Plugin command")
+            def clash(ctx):
+                return "plugin"
+
+        class ClashModelCommand(Command):
+            name: str = "clash"
+            help: str = "Model command"
+
+            def execute(self, ctx):
+                return "model"
+
+        entry_point = MagicMock()
+        entry_point.name = "plugin.clash"
+        entry_point.load.return_value = register_plugin_command
+
+        with patch("csp_bot.bot.importlib_metadata.entry_points", return_value=[entry_point]):
+            bot_with_symphony.load_commands([CommandModel(command=ClashModelCommand)])
+
+        assert "clash" in bot_with_symphony._commands
+        assert isinstance(bot_with_symphony._commands["clash"], ClashModelCommand)
+
+
 # Command Argument Parsing Tests
 
 

csp_bot/tests/test_command_framework.py

@@ -37,11 +37,6 @@ def _make_ctx(**overrides) -> CommandContext:
     return CommandContext(**defaults)
 
 
-# ===========================================================================
-# CommandContext tests
-# ===========================================================================
-
-
 class TestCommandContext:
     def test_basic_attributes(self):
         ctx = _make_ctx()
@@ -109,11 +104,6 @@ def test_deps_accessible(self):
         assert ctx.deps["api_key"] == "abc"
 
 
-# ===========================================================================
-# @command decorator tests
-# ===========================================================================
-
-
 class TestCommandDecorator:
     def setup_method(self):
         clear_registry()
@@ -163,11 +153,6 @@ def echo(ctx):
         assert echo(ctx) == "hello world"
 
 
-# ===========================================================================
-# Command class tests
-# ===========================================================================
-
-
 class TestCommandClass:
     def test_subclass_with_fields(self):
         class MyCmd(Command):
@@ -205,11 +190,6 @@ def test_base_command_raises_not_implemented(self):
             cmd.execute(ctx)
 
 
-# ===========================================================================
-# Executor tests — four signatures
-# ===========================================================================
-
-
 class TestExecutorSync:
     def test_sync_returns_str(self):
         def echo(ctx):
@@ -491,11 +471,6 @@ async def bad_agen(ctx):
             execute_command_func(bad_agen, ctx)
 
 
-# ===========================================================================
-# Executor — Command class integration
-# ===========================================================================
-
-
 class TestExecutorWithCommandClass:
     def test_sync_command_class(self):
         class Echo(Command):
@@ -552,11 +527,6 @@ async def execute(self, ctx):
         assert len(results) == 2
 
 
-# ===========================================================================
-# _coerce_response tests
-# ===========================================================================
-
-
 class TestCoerceResponse:
     def test_none(self):
         assert _coerce_response(None, "slack") is None
@@ -590,11 +560,6 @@ def test_unknown_type(self):
         assert result.content == "42"
 
 
-# ===========================================================================
-# Legacy adapter tests
-# ===========================================================================
-
-
 class _FakeEchoCommand(ReplyToOtherCommand):
     """Minimal legacy command for testing."""
 
@@ -644,11 +609,6 @@ def test_context_to_bot_command(self):
         assert bot_cmd.variant == CommandVariant.REPLY_TO_OTHER
 
 
-# ===========================================================================
-# End-to-end: decorated command through executor
-# ===========================================================================
-
-
 class TestEndToEnd:
     def setup_method(self):
         clear_registry()

csp_bot/utils.py

@@ -120,11 +120,6 @@ def get_backend_format(backend: Backend) -> Format:
     return get_format_for_backend(backend)
 
 
-# ============================================================================
-# Symphony MessageML formatting utilities
-# ============================================================================
-
-
 def format_with_message_ml(text: str, to_message_ml: bool = True) -> str:
     """Convert text to/from Symphony MessageML format.