rework command framework

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

Author: timkpaine

csp_bot/__init__.py

@@ -21,15 +21,21 @@
 from .commands import (
     BaseCommand,
     BaseCommandModel,
+    BotInfo,
+    Command,
+    CommandContext,
+    CommandModel,
     EchoCommand,
     HelpCommand,
+    LegacyCommandAdapter,
     NoResponseCommand,
     ReplyCommand,
     ReplyToAllCommand,
     ReplyToAuthorCommand,
     ReplyToOtherCommand,
     ScheduleCommand,
     StatusCommand,
+    command,
     mention_user,
 )
 from .gateway import CspBotGateway, Gateway, GatewayChannels, GatewayModule, GatewaySettings
@@ -53,7 +59,14 @@
     "DiscordConfig",
     "SlackConfig",
     "SymphonyConfig",
-    # Commands
+    # Commands — new framework
+    "Command",
+    "CommandContext",
+    "CommandModel",
+    "BotInfo",
+    "LegacyCommandAdapter",
+    "command",
+    # Commands — legacy
     "BaseCommand",
     "BaseCommandModel",
     "EchoCommand",

csp_bot/bot.py

@@ -38,16 +38,21 @@
 from .bot_config import BotConfig
 from .commands import (
     BaseCommand,
-    BaseCommandModel,
+    BotInfo,
+    Command,
+    CommandContext,
     HelpCommand,
     ScheduleCommand,
     StatusCommand,
+    execute_command_func,
+    get_registered_commands,
 )
 from .gateway import GatewayChannels, GatewayModule
 from .structs import (
     Backend,
     BotCommand,
     BotMessage,
+    CommandVariant,
 )
 
 log = getLogger(__name__)
@@ -70,18 +75,23 @@ class Bot(GatewayModule):
 
     config: BotConfig
 
-    _command_models: List[BaseCommandModel] = PrivateAttr(default_factory=list)
-    _commands: Dict[str, BaseCommand] = PrivateAttr(default_factory=dict)
+    _command_models: List[Any] = PrivateAttr(default_factory=list)
+    _commands: Dict[str, Any] = PrivateAttr(default_factory=dict)
     _configs: Dict[Backend, Any] = PrivateAttr(default_factory=dict)
     _adapters: Dict[Backend, Any] = PrivateAttr(default_factory=dict)
     _connected_backends: Dict[Backend, Tuple[Any, asyncio.AbstractEventLoop]] = PrivateAttr(default_factory=dict)
     _scheduled: Dict[str, BotCommand] = PrivateAttr(default_factory=dict)
     _authorized_users: Dict[Backend, Set[str]] = PrivateAttr(default_factory=dict)
     _bot_user_ids: Dict[Backend, str] = PrivateAttr(default_factory=dict)
     _bot_names: Dict[Backend, str] = PrivateAttr(default_factory=dict)
+    _deps: Any = PrivateAttr(default=None)
     _thread: Optional[threading.Thread] = PrivateAttr(None)
     _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)
 
+    def set_deps(self, deps: Any) -> None:
+        """Set shared dependency object for new command framework contexts."""
+        self._deps = deps
+
     def connect(self, channels: GatewayChannels) -> None:
         """Connect to configured backends and set up message processing.
 
@@ -318,8 +328,11 @@ async def _fetch() -> Optional[Channel]:
             log.exception(f"Error resolving channel: {channel_identifier}")
             return None
 
-    def load_commands(self, command_models: List[BaseCommandModel]) -> None:
-        """Load command handlers from command models."""
+    def load_commands(self, command_models: List[Any]) -> None:
+        """Load command handlers from command models and decorator registry.
+
+        Supports both legacy BaseCommandModel and the new CommandModel.
+        """
         log.info(f"Loading {len(command_models)} commands...")
         for model in command_models:
             try:
@@ -328,14 +341,59 @@ def load_commands(self, command_models: List[BaseCommandModel]) -> None:
                 log.critical(f"Incomplete command type - implement all abstract methods: {model.command}")
                 raise e
 
-            command_str = command.command()
+            if isinstance(command, BaseCommand):
+                command_str = command.command()
+                runner: Any = command
+            elif isinstance(command, Command):
+                command_str = command.name
+                runner = command
+            else:
+                raise TypeError(f"Unsupported command type from model {type(model).__name__}: {type(command).__name__}")
+
             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]}")
 
-            self._commands[command_str] = command
+            self._commands[command_str] = runner
             self._command_models.append(model)
 
+        # Decorator-registered commands are available globally and can be mixed
+        # with model-based commands. Explicit model definitions win on conflicts.
+        for command_name, entry in get_registered_commands().items():
+            if command_name in self._commands:
+                continue
+            log.info(f"Registered decorated command: /{command_name}")
+            self._commands[command_name] = entry
+
+    def _command_backends(self, command_runner: Any) -> List[str]:
+        """Return supported backends for either legacy or new command types."""
+        if isinstance(command_runner, BaseCommand):
+            return command_runner.backends()
+        if isinstance(command_runner, Command):
+            return command_runner.backends
+        return list(getattr(command_runner, "backends", []) or [])
+
+    def _build_command_context(self, cmd: BotCommand) -> CommandContext:
+        """Build CommandContext from legacy BotCommand for new framework execution."""
+        bot_info = BotInfo(
+            id=self._get_bot_id(cmd.backend) or "",
+            name=self._get_bot_name(cmd.backend) or "",
+            version="",
+        )
+        channel = Channel(id=cmd.channel_id, name=cmd.channel_name)
+        return CommandContext(
+            command_name=cmd.command,
+            source=cmd.source,
+            targets=list(cmd.targets),
+            channel=channel,
+            message=cmd.message,
+            args=list(cmd.args),
+            args_text=" ".join(cmd.args),
+            backend=cmd.backend,
+            bot=bot_info,
+            deps=self._deps,
+        )
+
     # =========================================================================
     # Message Processing Nodes
     # =========================================================================
@@ -733,7 +791,8 @@ def _extract_commands(
             command_runner = self._commands[command_name]
 
             # Check backend support
-            if command_runner.backends() and backend not in command_runner.backends():
+            command_backends = self._command_backends(command_runner)
+            if command_backends and backend not in command_backends:
                 log.warning(f"Command {command_name} not supported on {backend}")
                 return None
 
@@ -764,7 +823,7 @@ def _extract_commands(
                 channel_id=target_channel,
                 channel_name=channel_name,
                 backend=backend,
-                variant=command_runner.kind(),
+                variant=command_runner.kind() if isinstance(command_runner, BaseCommand) else CommandVariant.REPLY,
                 message=msg,
                 delay=None,
                 schedule="",
@@ -874,7 +933,7 @@ def _create_help_command(self, msg: Message, backend: str, channel_id: str) -> B
             channel_id=channel_id,
             channel_name=channel_name,
             backend=backend,
-            variant=command_runner.kind(),
+            variant=command_runner.kind() if isinstance(command_runner, BaseCommand) else CommandVariant.REPLY,
             message=msg,
             delay=None,
             schedule="",
@@ -888,12 +947,22 @@ def _execute_command(self, cmd: BotCommand) -> Optional[Union[Message, List[Mess
             return None
 
         try:
-            if isinstance(command_runner, HelpCommand):
-                responses = command_runner.execute(cmd, MappingProxyType(self._commands))
-            elif isinstance(command_runner, ScheduleCommand):
-                responses = command_runner.execute(cmd, self._scheduled)
+            if isinstance(command_runner, BaseCommand):
+                if isinstance(command_runner, HelpCommand):
+                    responses = command_runner.execute(cmd, MappingProxyType(self._commands))
+                elif isinstance(command_runner, ScheduleCommand):
+                    responses = command_runner.execute(cmd, self._scheduled)
+                else:
+                    responses = command_runner.execute(cmd)
+            elif isinstance(command_runner, Command):
+                ctx = self._build_command_context(cmd)
+                responses = [r for r in execute_command_func(command_runner.execute, ctx) if r is not None]
+            elif hasattr(command_runner, "handler"):
+                ctx = self._build_command_context(cmd)
+                responses = [r for r in execute_command_func(command_runner.handler, ctx) if r is not None]
             else:
-                responses = command_runner.execute(cmd)
+                log.error(f"Unsupported command runner type for {cmd.command}: {type(command_runner).__name__}")
+                return None
         except Exception:
             log.exception(f"Error executing command: {cmd.command}")
             return None

csp_bot/commands/__init__.py

@@ -2,6 +2,14 @@
 
 Commands can leverage chatom's cross-platform features for
 mentions, formatting, and entity recognition.
+
+Two command APIs are available:
+
+1. ``@command`` decorator for stateless function-based commands
+2. ``Command`` BaseModel subclass for stateful class-based commands
+
+The legacy ``BaseCommand`` hierarchy is still supported via
+``LegacyCommandAdapter``.
 """
 
 from csp_bot.utils import mention_user
@@ -15,13 +23,28 @@
     ReplyToAuthorCommand,
     ReplyToOtherCommand,
 )
+from .context import BotInfo, CommandContext
 from .echo import EchoCommand, EchoCommandModel
+from .executor import execute_command_func
+from .framework import Command, CommandEntry, CommandModel, clear_registry, command, get_registered_commands
 from .help import HelpCommand, HelpCommandModel
+from .legacy import LegacyCommandAdapter
 from .schedule import ScheduleCommand, ScheduleCommandModel
 from .status import StatusCommand, StatusCommandModel
 
 __all__ = (
-    # Base classes
+    # New framework
+    "Command",
+    "CommandContext",
+    "CommandEntry",
+    "CommandModel",
+    "BotInfo",
+    "LegacyCommandAdapter",
+    "command",
+    "clear_registry",
+    "get_registered_commands",
+    "execute_command_func",
+    # Legacy base classes
     "BaseCommand",
     "BaseCommandModel",
     "NoResponseCommand",