fix(photon): correct gateway start command (#45566)

hermes_cli/subcommands/gateway.py

@@ -14,6 +14,21 @@ from typing import Callable
 from hermes_cli.subcommands._shared import add_accept_hooks_flag
 
 
+def _add_compat_platform_flag(parser: argparse.ArgumentParser) -> None:
+    """Accept stale `gateway <verb> --platform X` docs without advertising it.
+
+    Gateway service lifecycle commands operate on the gateway process, not a
+    single messaging adapter.  Photon briefly printed a per-platform start
+    command during setup; keep that command parseable so users following the
+    old hint don't get blocked by argparse before the gateway can start.
+    """
+    parser.add_argument(
+        "--platform",
+        dest="platform",
+        help=argparse.SUPPRESS,
+    )
+
+
 def build_gateway_parser(subparsers, *, cmd_gateway: Callable, cmd_proxy: Callable) -> None:
     """Attach the ``gateway`` and ``proxy`` subcommands to ``subparsers``."""
     # =========================================================================
@@ -75,6 +90,7 @@ def build_gateway_parser(subparsers, *, cmd_gateway: Callable, cmd_proxy: Callab
         action="store_true",
         help="Kill ALL stale gateway processes across all profiles before starting",
     )
+    _add_compat_platform_flag(gateway_start)
 
     # gateway stop
     gateway_stop = gateway_subparsers.add_parser("stop", help="Stop gateway service")
@@ -103,6 +119,7 @@ def build_gateway_parser(subparsers, *, cmd_gateway: Callable, cmd_proxy: Callab
         action="store_true",
         help="Kill ALL gateway processes across all profiles before restarting",
     )
+    _add_compat_platform_flag(gateway_restart)
 
     # gateway status
     gateway_status = gateway_subparsers.add_parser("status", help="Show gateway status")
@@ -118,6 +135,7 @@ def build_gateway_parser(subparsers, *, cmd_gateway: Callable, cmd_proxy: Callab
         action="store_true",
         help="Target the Linux system-level gateway service",
     )
+    _add_compat_platform_flag(gateway_status)
 
     # gateway install
     gateway_install = gateway_subparsers.add_parser(

plugins/platforms/photon/README.md

@@ -46,7 +46,7 @@ talks to it over loopback.
 hermes photon setup --phone +15551234567
 
 # Start the gateway
-hermes gateway start --platform photon
+hermes gateway start
 ```
 
 `hermes photon setup` does, in order:

plugins/platforms/photon/cli.py

@@ -274,7 +274,7 @@ def _cmd_setup(args: argparse.Namespace) -> int:
 
     print()
     print("✓ Photon setup complete.")
-    print("  Start the gateway:  hermes gateway start --platform photon")
+    print("  Start the gateway:  hermes gateway start")
     return 0
 
 

tests/hermes_cli/test_gateway.py

@@ -274,6 +274,20 @@ def test_gateway_start_in_container_with_operational_systemd_uses_systemd(monkey
     assert calls == [False]
 
 
+def test_gateway_start_ignores_legacy_platform_selector(monkeypatch):
+    monkeypatch.setattr(gateway, "supports_systemd_services", lambda: True)
+    monkeypatch.setattr(gateway, "is_wsl", lambda: False)
+    monkeypatch.setattr(gateway, "is_macos", lambda: False)
+
+    calls = []
+    monkeypatch.setattr(gateway, "systemd_start", lambda system=False: calls.append(system))
+
+    args = SimpleNamespace(gateway_command="start", system=False, all=False, platform="photon")
+    gateway.gateway_command(args)
+
+    assert calls == [False]
+
+
 def test_gateway_restart_on_windows_without_service_uses_detached_backend(monkeypatch):
     """Windows manual restart must not fall back to foreground run_gateway().
 

tests/hermes_cli/test_subcommands_profile_gateway.py

@@ -81,3 +81,12 @@ def test_gateway_accept_hooks_flag():
     p = _gateway_parser()
     ns = p.parse_args(["gateway", "run", "--accept-hooks"])
     assert ns.accept_hooks is True
+
+
+def test_gateway_lifecycle_accepts_legacy_platform_flag():
+    p = _gateway_parser()
+    for action in ("start", "restart", "status"):
+        ns = p.parse_args(["gateway", action, "--platform", "photon"])
+        assert ns.gateway_command == action
+        assert ns.platform == "photon"
+        assert ns.func is _h_gateway

tests/plugins/platforms/photon/test_setup_access.py

@@ -7,6 +7,8 @@ never clobbers a hand-tuned allowlist.
 """
 from __future__ import annotations
 
+import argparse
+
 import pytest
 
 from hermes_cli.config import get_env_value, save_env_value
@@ -67,3 +69,44 @@ def test_env_enablement_home_channel_defaults_name(monkeypatch: pytest.MonkeyPat
         "chat_id": "+15551234567",
         "name": "Home",
     }
+
+
+def test_setup_hint_uses_gateway_service_command(monkeypatch: pytest.MonkeyPatch, capsys) -> None:
+    monkeypatch.setattr(cli.photon_auth, "load_photon_token", lambda: "token")
+    monkeypatch.setattr(cli.photon_auth, "load_dashboard_project_id", lambda: "dashboard")
+    monkeypatch.setattr(
+        cli.photon_auth,
+        "ensure_spectrum_enabled",
+        lambda token, dashboard_id: {"spectrumProjectId": "project_123"},
+    )
+    monkeypatch.setattr(
+        cli.photon_auth,
+        "regenerate_project_secret",
+        lambda token, dashboard_id: "secret_123",
+    )
+    monkeypatch.setattr(cli.photon_auth, "store_project_credentials", lambda **kwargs: None)
+    monkeypatch.setattr(
+        cli.photon_auth,
+        "register_user_if_absent",
+        lambda *args, **kwargs: ({"id": "user_123", "phoneNumber": "+15551234567"}, True),
+    )
+    monkeypatch.setattr(cli.photon_auth, "user_assigned_line", lambda user: "+15557654321")
+    monkeypatch.setattr(cli.photon_auth, "store_user_numbers", lambda **kwargs: None)
+    monkeypatch.setattr(cli, "_install_sidecar", lambda: 0)
+
+    rc = cli._cmd_setup(
+        argparse.Namespace(
+            project_name=None,
+            phone="+15551234567",
+            first_name=None,
+            last_name=None,
+            email=None,
+            no_browser=True,
+            skip_sidecar_install=False,
+        )
+    )
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "Start the gateway:  hermes gateway start" in out
+    assert "--platform photon" not in out

website/docs/user-guide/messaging/photon.md

@@ -145,7 +145,7 @@ BlueBubbles iMessage channel uses.
 ## Start the gateway
 
 ```bash
-hermes gateway start --platform photon
+hermes gateway start
 ```
 
 You'll see something like: