bot-cmder 0.2.0__py3-none-any.whl

bot_cmder/__init__.py

@@ -0,0 +1,10 @@
+"""bot-cmder — multi-platform SRE ChatOps bot."""
+
+from __future__ import annotations
+
+# Single source of truth for the package version. `pyproject.toml`
+# reads this via `[tool.hatch.version] path = "bot_cmder/__init__.py"`,
+# `bot_cmder/main.py` passes it to FastAPI's OpenAPI metadata, and the
+# CLI dispatcher prints it for `bot-cmder --version`. Bump here before
+# tagging a release; everything downstream picks up automatically.
+__version__ = "0.2.0"

bot_cmder/__main__.py

@@ -0,0 +1,15 @@
+"""`python -m bot_cmder` entry point — delegates to the CLI dispatcher.
+
+Pairs with the console-script `bot-cmder` declared in `pyproject.toml`'s
+`[project.scripts]`. Both invocations end up in `bot_cmder.cli.main`,
+so `python -m bot_cmder serve` and `bot-cmder serve` are equivalent.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from bot_cmder.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bot_cmder/adapters/base.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from bot_cmder.core.events import IncomingMessage, OutgoingResponse, Platform
+
+
+class PlatformAdapter(ABC):
+    """How a chat platform talks to bot-cmder.
+
+    Each adapter owns its own incoming-payload schema and outbound
+    client; the only contract here is the conversion in/out of the
+    platform-neutral IncomingMessage / OutgoingResponse types.
+    """
+
+    platform: Platform
+
+    @abstractmethod
+    def parse(self, raw: Any) -> IncomingMessage | None: ...
+
+    @abstractmethod
+    async def send(self, msg: IncomingMessage, resp: OutgoingResponse) -> None: ...

bot_cmder/adapters/discord/__init__.py

@@ -0,0 +1,5 @@
+from bot_cmder.adapters.discord.adapter import DiscordAdapter
+from bot_cmder.adapters.discord.client import DiscordClient
+from bot_cmder.adapters.discord.router import make_router
+
+__all__ = ["DiscordAdapter", "DiscordClient", "make_router"]

bot_cmder/adapters/discord/adapter.py

@@ -0,0 +1,203 @@
+"""DiscordAdapter — Discord Interactions OR Gateway events → IncomingMessages.
+
+Two ingestion paths feed the same dispatcher:
+
+  - **HTTP Interactions** (Phase 4, default): slash commands arrive
+    as the `Interaction` envelope. Schema is intentionally flat —
+    one Discord application command per top-level chat command, with
+    a single optional `args` STRING option. We rebuild that into the
+    `/cmd <args...>` text shape Telegram produces, so behavior matches
+    one-to-one.
+
+  - **Gateway** (Phase 6c, `DISCORD_MODE=gateway`): chat messages
+    arrive as `MESSAGE_CREATE` dispatch events over WSS. Discord does
+    NOT deliver slash command interactions through the Gateway
+    (platform limitation), so the UX shifts to "@bot cmd args" in
+    guild channels OR plain `cmd args` in DMs. The adapter strips
+    the `<@bot_id>` mention prefix and normalizes the result into the
+    same `/cmd args...` shape the dispatcher expects.
+
+Replies:
+  - Interactions path → PATCH @original webhook URL (no bot-token auth)
+  - Gateway path → POST /channels/{id}/messages (bot-token auth)
+
+The two paths share `parse()` via type sniffing on the raw payload —
+Interaction objects always have a `type` int field; MessageCreatePayload
+always has `content` + `author`. Easier than splitting into two
+adapters and saves the router/daemon from caring which path the
+adapter chose.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from bot_cmder.adapters.base import PlatformAdapter
+from bot_cmder.adapters.discord.client import DiscordClient
+from bot_cmder.adapters.discord.schemas import Interaction, InteractionType, MessageCreatePayload
+from bot_cmder.core.events import IncomingMessage, OutgoingResponse, Platform, PlatformUser
+
+if TYPE_CHECKING:
+    pass
+
+
+# Discord renders @-mentions in message content as `<@USER_ID>` (or
+# `<@!USER_ID>` for nicknames in older clients). Strip both shapes.
+_MENTION_RE = re.compile(r"<@!?(\d+)>")
+
+
+class DiscordAdapter(PlatformAdapter):
+    platform = Platform.DISCORD
+
+    def __init__(self, client: DiscordClient, bot_user_id: str | None = None) -> None:
+        """`bot_user_id` is required for Gateway mode (so the adapter
+        knows which mention IDs to strip from message content); for
+        Interactions-only mode it can be None."""
+        self._client = client
+        self._bot_user_id = bot_user_id
+
+    @property
+    def client(self) -> DiscordClient:
+        return self._client
+
+    def parse(self, raw: Any) -> IncomingMessage | None:
+        # Type-sniff between the two payload shapes. MessageCreatePayload
+        # always has `content` + `author`; Interaction always has `type`
+        # + `application_id`. Pre-validated objects pass through.
+        if isinstance(raw, Interaction):
+            return self._parse_interaction(raw)
+        if isinstance(raw, MessageCreatePayload):
+            return self._parse_message_create(raw)
+        if isinstance(raw, dict):
+            if "application_id" in raw and "type" in raw:
+                return self._parse_interaction(Interaction.model_validate(raw))
+            if "content" in raw and "author" in raw:
+                return self._parse_message_create(MessageCreatePayload.model_validate(raw))
+        return None
+
+    def _parse_interaction(self, interaction: Interaction) -> IncomingMessage | None:
+        if interaction.type != InteractionType.APPLICATION_COMMAND:
+            # PING (type 1) is answered inline in the router. Other
+            # types (autocomplete, modal submit, message component)
+            # aren't part of Phase 4's surface.
+            return None
+        if interaction.data is None or not interaction.data.name:
+            return None
+        caller = interaction.caller()
+        if caller is None:
+            return None
+
+        # Flatten the option tree back into `/cmd args...` text so the
+        # dispatcher sees the same shape Telegram produces. Two layouts
+        # we accept (Discord rule: a slash command's options are EITHER
+        # all leaf values OR all sub-commands, never mixed):
+        #
+        #   1. Leaf options only — e.g. /service with one `args` STRING:
+        #        options=[{name:"args", type:3, value:"restart api"}]
+        #      → "/service restart api"
+        #
+        #   2. SUB_COMMAND wrapper (issue #18) — e.g. /otp emergency 5:
+        #        options=[{name:"emergency", type:1, options:[
+        #           {name:"minutes", type:4, value:5}]}]
+        #      → "/otp emergency 5"
+        #
+        # SUB_COMMAND_GROUP (type=2) would add another nesting level,
+        # but we don't emit any in our schema, so a single descent
+        # suffices. If we ever do, this should grow into a recursive
+        # walk.
+        parts: list[str] = [f"/{interaction.data.name}"]
+        for opt in interaction.data.options or []:
+            if opt.type == 1:  # SUB_COMMAND — descend one level
+                parts.append(opt.name)
+                for inner in opt.options or []:
+                    if inner.value is None:
+                        continue
+                    parts.append(str(inner.value))
+                continue
+            if opt.value is None:
+                continue
+            parts.append(str(opt.value))
+        text = " ".join(parts)
+
+        return IncomingMessage(
+            platform=Platform.DISCORD,
+            user=PlatformUser(
+                platform=Platform.DISCORD,
+                raw_id=caller.id,
+                handle=caller.username,
+                display_name=caller.global_name or caller.username,
+            ),
+            chat_id=interaction.channel_id or interaction.guild_id or "dm",
+            text=text,
+            message_id=interaction.id,
+            raw=interaction.model_dump(),
+            received_at=datetime.now(timezone.utc),
+        )
+
+    def _parse_message_create(self, msg: MessageCreatePayload) -> IncomingMessage | None:
+        """Decide whether a Gateway MESSAGE_CREATE counts as a command,
+        and if so, normalize it to `/cmd args...` text shape.
+
+        Three filters in order:
+          1. Skip messages from any bot account (including ourselves) —
+             prevents reply loops.
+          2. Decide if the message addresses our bot:
+               - DM (guild_id null): every message counts
+               - guild channel: only if our bot is in `mentions`
+          3. Strip the `<@bot_id>` mention prefix from content; if the
+             remaining text doesn't already start with `/`, prepend it
+             so the dispatcher recognizes it as a command.
+
+        Returns None when any filter rejects (caller logs and moves on).
+        """
+        if msg.author.bot:
+            return None
+        # Guild messages must @-mention us to count as a command;
+        # DMs accept any content.
+        if not msg.is_dm() and (self._bot_user_id is None or not msg.mentions_user(self._bot_user_id)):
+            return None
+
+        # Strip every <@id> / <@!id> mention from the content (not just
+        # the leading one) and collapse whitespace. This handles
+        # `@sre_bot service restart` AND `service @sre_bot restart`
+        # (the second is unusual but Discord allows mentions anywhere).
+        bare = _MENTION_RE.sub(" ", msg.content).strip()
+        bare = " ".join(bare.split())  # collapse runs of whitespace
+        if not bare:
+            return None
+
+        text = bare if bare.startswith("/") else f"/{bare}"
+
+        return IncomingMessage(
+            platform=Platform.DISCORD,
+            user=PlatformUser(
+                platform=Platform.DISCORD,
+                raw_id=msg.author.id,
+                handle=msg.author.username,
+                display_name=msg.author.global_name or msg.author.username,
+            ),
+            chat_id=msg.channel_id,
+            text=text,
+            message_id=msg.id,
+            # Stash channel_id explicitly — adapter.send() uses it to
+            # route the reply via the Gateway path (POST /channels/.../messages).
+            raw={**msg.model_dump(), "_via": "gateway"},
+            received_at=datetime.now(timezone.utc),
+        )
+
+    async def send(self, msg: IncomingMessage, resp: OutgoingResponse) -> None:
+        # Branch by ingestion path. Gateway-originated messages
+        # don't have a per-invocation interaction token — they reply
+        # via the regular bot-authed REST endpoint.
+        raw = msg.raw if isinstance(msg.raw, dict) else {}
+        if raw.get("_via") == "gateway":
+            await self._client.create_message(msg.chat_id, resp.text)
+            return
+        token = raw.get("token")
+        if not token:
+            # Without the per-interaction token we can't reach the
+            # @original webhook URL; nothing to do.
+            return
+        await self._client.patch_original_response(token, resp.text)

bot_cmder/adapters/discord/client.py

@@ -0,0 +1,126 @@
+"""Minimal async Discord REST client.
+
+Two-purpose:
+
+  1. Reply to a deferred interaction by PATCHing the @original
+     message via the interaction's webhook URL. These endpoints are
+     keyed by interaction_token and don't take the bot's Bearer auth
+     — they're effectively per-interaction one-shot URLs.
+  2. Register the application's slash command schema (PUT
+     /applications/{id}/commands or .../guilds/{guild_id}/commands).
+     These endpoints DO need the bot token in `Authorization: Bot`.
+
+Discord caps message content at 2000 chars; longer replies are
+truncated with a `[...truncated]` marker so the operator knows.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+_DISCORD_MAX_MESSAGE_CHARS = 2000
+
+
+class DiscordClient:
+    BASE_URL = "https://discord.com/api/v10"
+
+    def __init__(
+        self,
+        *,
+        bot_token: str,
+        application_id: str,
+        base_url: str = BASE_URL,
+        timeout_s: float = 10.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._bot_token = bot_token
+        self._application_id = application_id
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout_s,
+            transport=transport,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> DiscordClient:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def patch_original_response(
+        self,
+        interaction_token: str,
+        content: str,
+    ) -> dict[str, Any]:
+        """Replace a deferred interaction's @original message body.
+
+        No bot-token auth: the interaction_token itself authorizes
+        the call. Discord's content limit is 2000 chars; we truncate
+        beyond that with a marker so reply contents that come back
+        from a chatty SSH command don't silently disappear.
+        """
+        url = f"/webhooks/{self._application_id}/{interaction_token}/messages/@original"
+        truncated = _truncate(content)
+        resp = await self._client.patch(url, json={"content": truncated})
+        resp.raise_for_status()
+        data: dict[str, Any] = resp.json()
+        return data
+
+    async def create_message(self, channel_id: str, content: str) -> dict[str, Any]:
+        """POST a chat message to a channel.
+
+        Used by Phase 6c Gateway-mode replies — interactions reply via
+        the per-invocation webhook URL (no auth needed), but Gateway-
+        originated messages don't have one, so we go through the
+        regular bot-authed REST endpoint. Same 2000-char truncation
+        the @original PATCH path uses.
+        """
+        url = f"/channels/{channel_id}/messages"
+        truncated = _truncate(content)
+        resp = await self._client.post(
+            url,
+            json={"content": truncated},
+            headers={"Authorization": f"Bot {self._bot_token}"},
+        )
+        resp.raise_for_status()
+        data: dict[str, Any] = resp.json()
+        return data
+
+    async def overwrite_global_commands(self, commands: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """PUT-replace the application's global slash command set."""
+        return await self._put_commands(f"/applications/{self._application_id}/commands", commands)
+
+    async def overwrite_guild_commands(
+        self,
+        guild_id: str,
+        commands: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """PUT-replace a guild's slash command set. Updates propagate instantly."""
+        return await self._put_commands(
+            f"/applications/{self._application_id}/guilds/{guild_id}/commands",
+            commands,
+        )
+
+    async def _put_commands(self, url: str, commands: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        resp = await self._client.put(
+            url,
+            json=commands,
+            headers={"Authorization": f"Bot {self._bot_token}"},
+        )
+        resp.raise_for_status()
+        data: list[dict[str, Any]] = resp.json()
+        return data
+
+
+def _truncate(content: str) -> str:
+    if not content:
+        return "(no output)"
+    if len(content) <= _DISCORD_MAX_MESSAGE_CHARS:
+        return content
+    marker = "\n[...truncated]"
+    return content[: _DISCORD_MAX_MESSAGE_CHARS - len(marker)] + marker