feat(irc): add interactive setup

feat(gateway): refine Platform._missing_ and platform-connected dispatch

Restricts plugin-name acceptance to bundled plugin scan + registry
(no arbitrary string -> enum-pollution), pulls per-platform connectivity
checks into a _PLATFORM_CONNECTED_CHECKERS lambda map with a clean
_is_platform_connected method, and adds tests covering the checker map,
plugin platform interface, and IRC setup wizard.

tests/gateway/test_irc_adapter.py

@@ -300,6 +300,129 @@ class TestIRCAdapterMessageParsing:
         assert len(dispatched) == 1
         assert dispatched[0]["text"] == "* user waves"
 
+    @pytest.mark.asyncio
+    async def test_allowed_users_case_insensitive(self, monkeypatch):
+        """Allowlist should match nicks case-insensitively."""
+        for key in ("IRC_SERVER", "IRC_PORT", "IRC_NICKNAME", "IRC_CHANNEL", "IRC_USE_TLS"):
+            monkeypatch.delenv(key, raising=False)
+        from gateway.config import PlatformConfig
+        cfg = PlatformConfig(
+            enabled=True,
+            extra={
+                "server": "localhost",
+                "port": 6667,
+                "nickname": "hermes",
+                "channel": "#test",
+                "use_tls": False,
+                "allowed_users": ["Admin", "BOB"],
+            },
+        )
+        adapter = IRCAdapter(cfg)
+        adapter._current_nick = "hermes"
+        adapter._registered = True
+        dispatched = []
+
+        async def capture_dispatch(**kwargs):
+            dispatched.append(kwargs)
+
+        adapter._dispatch_message = capture_dispatch
+        adapter._message_handler = AsyncMock()
+
+        # "admin" matches "Admin" in allowlist
+        await adapter._handle_line(":admin!u@host PRIVMSG #test :hermes: hello")
+        assert len(dispatched) == 1
+        assert dispatched[0]["text"] == "hello"
+
+    @pytest.mark.asyncio
+    async def test_unauthorized_user_blocked(self, monkeypatch):
+        """Nicks not in allowlist should be ignored."""
+        for key in ("IRC_SERVER", "IRC_PORT", "IRC_NICKNAME", "IRC_CHANNEL", "IRC_USE_TLS"):
+            monkeypatch.delenv(key, raising=False)
+        from gateway.config import PlatformConfig
+        cfg = PlatformConfig(
+            enabled=True,
+            extra={
+                "server": "localhost",
+                "port": 6667,
+                "nickname": "hermes",
+                "channel": "#test",
+                "use_tls": False,
+                "allowed_users": ["Admin", "BOB"],
+            },
+        )
+        adapter = IRCAdapter(cfg)
+        adapter._current_nick = "hermes"
+        adapter._registered = True
+        dispatched = []
+
+        async def capture_dispatch(**kwargs):
+            dispatched.append(kwargs)
+
+        adapter._dispatch_message = capture_dispatch
+        adapter._message_handler = AsyncMock()
+
+        await adapter._handle_line(":eve!u@host PRIVMSG #test :hermes: hello")
+        assert len(dispatched) == 0
+
+    @pytest.mark.asyncio
+    async def test_nick_collision_retry(self, adapter):
+        """Multiple 433 responses should keep incrementing the suffix."""
+        writer = MagicMock()
+        writer.is_closing = MagicMock(return_value=False)
+        writer.write = MagicMock()
+        writer.drain = AsyncMock()
+        adapter._writer = writer
+
+        await adapter._handle_line(":server 433 * hermes :Nickname in use")
+        assert adapter._current_nick == "hermes_"
+        await adapter._handle_line(":server 433 * hermes_ :Nickname in use")
+        assert adapter._current_nick == "hermes_1"
+        await adapter._handle_line(":server 433 * hermes_1 :Nickname in use")
+        assert adapter._current_nick == "hermes_2"
+
+
+class TestIRCAdapterSplitting:
+
+    def test_split_respects_byte_limit(self):
+        """Multi-byte characters should not exceed IRC byte limit."""
+        # 100 japanese chars = 300 bytes in utf-8
+        text = "あ" * 100
+        from gateway.config import PlatformConfig
+        cfg = PlatformConfig(enabled=True, extra={"server": "x", "channel": "#x"})
+        adapter = IRCAdapter(cfg)
+        adapter._current_nick = "bot"
+        lines = adapter._split_message(text, "#test")
+        for line in lines:
+            overhead = len(f"PRIVMSG #test :{line}\r\n".encode("utf-8"))
+            assert overhead <= 512, f"line over 512 bytes: {overhead}"
+
+    def test_split_prefers_word_boundary(self):
+        text = "hello world foo bar baz qux"
+        from gateway.config import PlatformConfig
+        cfg = PlatformConfig(enabled=True, extra={"server": "x", "channel": "#x"})
+        adapter = IRCAdapter(cfg)
+        adapter._current_nick = "bot"
+        lines = adapter._split_message(text, "#test")
+        # Should not split in the middle of "world"
+        assert any("hello" in ln for ln in lines)
+        assert any("world" in ln for ln in lines)
+
+
+class TestIRCProtocolHelpersExtra:
+
+    def test_parse_malformed_no_space(self):
+        """A line starting with : but no space should not crash."""
+        msg = _parse_irc_message(":justaprefix")
+        assert msg["prefix"] == "justaprefix"
+        assert msg["command"] == ""
+        assert msg["params"] == []
+
+    def test_parse_empty(self):
+        msg = _parse_irc_message("")
+        assert msg["prefix"] == ""
+        assert msg["command"] == ""
+        assert msg["params"] == []
+
 
 class TestIRCAdapterMarkdown:
 

tests/gateway/test_platform_connected_checkers.py

@@ -0,0 +1,99 @@
+"""
+Verify that every gateway platform — built-in and plugin — has a connection
+checker so ``GatewayConfig.get_connected_platforms()`` doesn't silently drop
+platforms with bespoke auth requirements.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from gateway.config import Platform, _PLATFORM_CONNECTED_CHECKERS, _BUILTIN_PLATFORM_VALUES
+
+
+def test_all_builtins_have_checker_or_generic_token_path():
+    """Every built-in Platform member must be reachable by either:
+
+    1. The generic ``config.token or config.api_key`` check, OR
+    2. A platform-specific entry in ``_PLATFORM_CONNECTED_CHECKERS``.
+
+    This guarantees ``get_connected_platforms()`` doesn't silently ignore
+    a built-in just because nobody added it to the checker dict.
+    """
+    # Platforms covered by the generic token/api_key branch
+    generic_token_values = {p.value for p in {
+        Platform.TELEGRAM,
+        Platform.DISCORD,
+        Platform.SLACK,
+        Platform.MATRIX,
+        Platform.MATTERMOST,
+        Platform.HOMEASSISTANT,
+    }}
+
+    # Platforms with a bespoke checker
+    checker_values = {p.value for p in set(_PLATFORM_CONNECTED_CHECKERS.keys())}
+
+    # Every built-in should be in one of the two sets
+    all_builtins = set(_BUILTIN_PLATFORM_VALUES)
+    missing = all_builtins - generic_token_values - checker_values - {"local"}
+
+    assert not missing, (
+        f"Built-in platforms missing a connection checker: "
+        f"{sorted(missing)}.  "
+        f"Add them to _PLATFORM_CONNECTED_CHECKERS or generic_token_platforms."
+    )
+
+
+@pytest.mark.parametrize("platform, checker", list(_PLATFORM_CONNECTED_CHECKERS.items()))
+def test_checker_handles_minimal_config(platform, checker):
+    """Each bespoke checker must not crash on a minimal PlatformConfig."""
+    mock_config = MagicMock()
+    mock_config.extra = {}
+    mock_config.token = None
+    mock_config.api_key = None
+    mock_config.enabled = True
+
+    # Should return a bool without raising
+    result = checker(mock_config)
+    assert isinstance(result, bool)
+
+
+@pytest.mark.parametrize("platform, checker", list(_PLATFORM_CONNECTED_CHECKERS.items()))
+def test_checker_returns_true_when_configured(platform, checker, monkeypatch):
+    """Each bespoke checker must return True when the config looks valid."""
+    mock_config = MagicMock()
+    mock_config.token = None
+    mock_config.api_key = None
+    mock_config.enabled = True
+
+    # Set up platform-specific mock extra fields so the checker succeeds
+    if platform == Platform.WEIXIN:
+        mock_config.extra = {"account_id": "123", "token": "***"}
+    elif platform == Platform.SIGNAL:
+        mock_config.extra = {"http_url": "http://signal:8080"}
+    elif platform == Platform.EMAIL:
+        mock_config.extra = {"address": "hermes@example.com"}
+    elif platform == Platform.SMS:
+        monkeypatch.setenv("TWILIO_ACCOUNT_SID", "ACtest")
+        mock_config.extra = {}
+    elif platform in (Platform.API_SERVER, Platform.WEBHOOK, Platform.WHATSAPP):
+        mock_config.extra = {}
+    elif platform == Platform.FEISHU:
+        mock_config.extra = {"app_id": "app"}
+    elif platform == Platform.WECOM:
+        mock_config.extra = {"bot_id": "bot"}
+    elif platform == Platform.WECOM_CALLBACK:
+        mock_config.extra = {"corp_id": "corp"}
+    elif platform == Platform.BLUEBUBBLES:
+        mock_config.extra = {"server_url": "http://bb:1234", "password": "pw"}
+    elif platform == Platform.QQBOT:
+        mock_config.extra = {"app_id": "app", "client_secret": "sec"}
+    elif platform == Platform.YUANBAO:
+        mock_config.extra = {"app_id": "app", "app_secret": "sec"}
+    elif platform == Platform.DINGTALK:
+        mock_config.extra = {"client_id": "id", "client_secret": "sec"}
+    else:
+        pytest.skip(f"No synthetic config defined for {platform.value}")
+
+    result = checker(mock_config)
+    assert result is True, f"{platform.value} checker should return True with valid-looking config"

tests/gateway/test_platform_registry.py

@@ -38,9 +38,28 @@ class TestPlatformEnumDynamic:
         assert a.value == "irc"
 
     def test_dynamic_member_with_hyphens(self):
-        p = Platform("my-platform")
-        assert p.value == "my-platform"
-        assert p.name == "MY_PLATFORM"
+        """Registered plugin platforms with hyphens work once registered."""
+        from gateway.platform_registry import platform_registry as _reg
+
+        entry = PlatformEntry(
+            name="my-platform",
+            label="My Platform",
+            adapter_factory=lambda cfg: MagicMock(),
+            check_fn=lambda: True,
+            source="plugin",
+        )
+        _reg.register(entry)
+        try:
+            p = Platform("my-platform")
+            assert p.value == "my-platform"
+            assert p.name == "MY_PLATFORM"
+        finally:
+            _reg.unregister("my-platform")
+
+    def test_dynamic_member_rejects_unregistered(self):
+        """Arbitrary strings are rejected to prevent enum pollution."""
+        with pytest.raises(ValueError):
+            Platform("totally-fake-platform")
 
     def test_dynamic_member_rejects_non_string(self):
         with pytest.raises(ValueError):

tests/gateway/test_plugin_platform_interface.py

@@ -0,0 +1,230 @@
+"""
+Interface compliance tests for all plugin-based gateway platforms.
+
+Discovers platforms dynamically under ``plugins/platforms/`` — no manual
+enumeration — and verifies each one implements the required contract.
+"""
+
+import importlib
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).parent.parent.resolve()
+PLATFORMS_DIR = PROJECT_ROOT / "plugins" / "platforms"
+
+
+def _discover_platform_plugins() -> list[str]:
+    """Return names of all bundled platform plugins."""
+    if not PLATFORMS_DIR.is_dir():
+        return []
+    names = []
+    for child in sorted(PLATFORMS_DIR.iterdir()):
+        if child.is_dir() and (child / "__init__.py").exists():
+            names.append(child.name)
+    return names
+
+
+# Dynamically parametrise over discovered platforms
+_PLATFORM_NAMES = _discover_platform_plugins()
+
+
+@pytest.fixture
+def clean_registry():
+    """Yield with a clean platform registry, restoring state afterwards."""
+    from gateway.platform_registry import platform_registry
+
+    original = dict(platform_registry._entries)
+    platform_registry._entries.clear()
+    yield platform_registry
+    platform_registry._entries.clear()
+    platform_registry._entries.update(original)
+
+
+class _MockPluginContext:
+    """Minimal mock of hermes_cli.plugins.PluginContext.
+
+    Only implements register_platform so we can exercise the plugin's
+    register() entrypoint without importing the real plugin system.
+    """
+
+    def __init__(self):
+        self.registered_names: list[str] = []
+
+    def register_platform(
+        self,
+        *,
+        name: str,
+        label: str,
+        adapter_factory: Any,
+        check_fn: Any,
+        **kwargs: Any,
+    ) -> None:
+        from gateway.platform_registry import platform_registry, PlatformEntry
+
+        entry = PlatformEntry(
+            name=name,
+            label=label,
+            adapter_factory=adapter_factory,
+            check_fn=check_fn,
+            **kwargs,
+        )
+        platform_registry.register(entry)
+        self.registered_names.append(name)
+
+
+def _import_platform_module(name: str) -> ModuleType:
+    """Import plugins.platforms.<name> in a test-safe way."""
+    # Make sure the project root is on sys.path so relative imports work
+    if str(PROJECT_ROOT) not in sys.path:
+        sys.path.insert(0, str(PROJECT_ROOT))
+    module = importlib.import_module(f"plugins.platforms.{name}")
+    return module
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_plugin_exposes_register_function(platform_name: str):
+    """Every platform plugin must expose a callable register function."""
+    module = _import_platform_module(platform_name)
+    assert hasattr(module, "register"), f"{platform_name} missing register()"
+    assert callable(module.register), f"{platform_name}.register not callable"
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_plugin_registers_valid_platform_entry(platform_name: str, clean_registry):
+    """Calling register() must create a valid PlatformEntry."""
+    module = _import_platform_module(platform_name)
+    ctx = _MockPluginContext()
+    module.register(ctx)
+
+    assert platform_name in ctx.registered_names
+
+    from gateway.platform_registry import platform_registry
+    entry = platform_registry.get(platform_name)
+    assert entry is not None, f"{platform_name} did not register an entry"
+    assert entry.name == platform_name
+    assert entry.label
+    assert callable(entry.adapter_factory)
+    assert callable(entry.check_fn)
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_platform_entry_has_required_fields(platform_name: str, clean_registry):
+    """PlatformEntry must have the mandatory metadata fields."""
+    module = _import_platform_module(platform_name)
+    ctx = _MockPluginContext()
+    module.register(ctx)
+
+    from gateway.platform_registry import platform_registry
+    entry = platform_registry.get(platform_name)
+    assert entry is not None
+
+    # Mandatory fields
+    assert isinstance(entry.name, str) and entry.name
+    assert isinstance(entry.label, str) and entry.label
+    assert callable(entry.adapter_factory)
+    assert callable(entry.check_fn)
+
+    # Optional but recommended fields
+    if entry.validate_config is not None:
+        assert callable(entry.validate_config)
+    if entry.is_connected is not None:
+        assert callable(entry.is_connected)
+    if entry.setup_fn is not None:
+        assert callable(entry.setup_fn)
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_adapter_factory_produces_valid_adapter(platform_name: str, clean_registry):
+    """The adapter factory must return an object with the base interface."""
+    module = _import_platform_module(platform_name)
+    ctx = _MockPluginContext()
+    module.register(ctx)
+
+    from gateway.platform_registry import platform_registry
+    entry = platform_registry.get(platform_name)
+    assert entry is not None
+
+    # Build a minimal synthetic config that shouldn't crash __init__
+    mock_config = MagicMock()
+    mock_config.extra = {}
+    mock_config.enabled = True
+    mock_config.token = None
+    mock_config.api_key = None
+    mock_config.home_channel = None
+    mock_config.reply_to_mode = "first"
+
+    adapter = entry.adapter_factory(mock_config)
+    assert adapter is not None, f"{platform_name} adapter_factory returned None"
+
+    # Required adapter interface
+    assert hasattr(adapter, "connect") and callable(adapter.connect)
+    assert hasattr(adapter, "disconnect") and callable(adapter.disconnect)
+    assert hasattr(adapter, "send") and callable(adapter.send)
+    assert hasattr(adapter, "name")
+
+    # Should be a BasePlatformAdapter subclass if importable
+    try:
+        from gateway.platforms.base import BasePlatformAdapter
+        assert isinstance(adapter, BasePlatformAdapter)
+    except Exception:
+        pytest.skip("BasePlatformAdapter not available for isinstance check")
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_check_fn_returns_bool(platform_name: str, clean_registry):
+    """check_fn() must return a boolean."""
+    module = _import_platform_module(platform_name)
+    ctx = _MockPluginContext()
+    module.register(ctx)
+
+    from gateway.platform_registry import platform_registry
+    entry = platform_registry.get(platform_name)
+    assert entry is not None
+
+    result = entry.check_fn()
+    assert isinstance(result, bool), f"{platform_name}.check_fn() returned {type(result)}, expected bool"
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_validate_config_if_present(platform_name: str, clean_registry):
+    """If validate_config is provided, it must accept a config object."""
+    module = _import_platform_module(platform_name)
+    ctx = _MockPluginContext()
+    module.register(ctx)
+
+    from gateway.platform_registry import platform_registry
+    entry = platform_registry.get(platform_name)
+    assert entry is not None
+
+    if entry.validate_config is None:
+        pytest.skip("No validate_config provided")
+
+    mock_config = MagicMock()
+    mock_config.extra = {}
+    result = entry.validate_config(mock_config)
+    assert isinstance(result, bool)
+
+
+@pytest.mark.parametrize("platform_name", _PLATFORM_NAMES)
+def test_is_connected_if_present(platform_name: str, clean_registry):
+    """If is_connected is provided, it must accept a config object."""
+    module = _import_platform_module(platform_name)
+    ctx = _MockPluginContext()
+    module.register(ctx)
+
+    from gateway.platform_registry import platform_registry
+    entry = platform_registry.get(platform_name)
+    assert entry is not None
+
+    if entry.is_connected is None:
+        pytest.skip("No is_connected provided")
+
+    mock_config = MagicMock()
+    mock_config.extra = {}
+    result = entry.is_connected(mock_config)
+    assert isinstance(result, bool)

tests/gateway/test_session.py

@@ -89,12 +89,14 @@ class TestSessionSourceRoundtrip:
         assert restored.chat_topic is None
         assert restored.chat_type == "dm"
 
-    def test_unknown_platform_accepted_for_plugins(self):
-        """Unknown platform names are now accepted (dynamic enum members for
-        plugin platforms), so from_dict should succeed rather than raise."""
-        source = SessionSource.from_dict({"platform": "nonexistent", "chat_id": "1"})
-        assert source.platform.value == "nonexistent"
-        assert source.chat_id == "1"
+    def test_unknown_platform_rejected_for_bad_names(self):
+        """Arbitrary platform names are rejected (no accidental enum pollution).
+
+        Only bundled platform plugins (discovered under ``plugins/platforms/``)
+        and runtime-registered plugins get dynamic enum members.
+        """
+        with pytest.raises(ValueError):
+            SessionSource.from_dict({"platform": "nonexistent", "chat_id": "1"})
 
 
 class TestSessionSourceDescription: