| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555 |
- """Gateway platform setup wizard (hermes gateway setup): platform registry/status table, per-platform setup prompts, service offer.
- Extracted from ``hermes_cli/gateway.py``. Bodies read facade helpers through ``_gw()`` (late
- binding on ``hermes_cli.gateway``) so the seams tests and callers patch on the facade keep
- intercepting the moved code.
- """
- from __future__ import annotations
- import shutil
- import subprocess
- import sys
- def _gw():
- from hermes_cli import gateway # late: the facade imports this module
- return gateway
- # Built-in per-platform setup config (env vars, instructions, prompts). Telegram, WhatsApp, Email,
- # SMS, etc. live in plugins/platforms/<name>/ and are discovered via the platform registry.
- _PLATFORMS = [
- {
- "key": "mattermost", "label": "Mattermost", "emoji": "๐ฌ", "token_var": "MATTERMOST_TOKEN",
- "setup_instructions": [
- "1. In Mattermost: Integrations โ Bot Accounts โ Add Bot Account",
- " (System Console โ Integrations โ Bot Accounts must be enabled)",
- "2. Give it a username (e.g. hermes) and copy the bot token",
- "3. Works with any self-hosted Mattermost instance โ enter your server URL",
- "4. Find your user ID (the profile dialog does not show it):",
- " Admins: System Console โ User Management โ Users โ open your user.",
- " Anyone: while logged in, open <server>/api/v4/users/me in a browser tab.",
- " With the bot token: GET <server>/api/v4/users/username/<your-username>.",
- " Copy the \"id\" field. /users/me with the bot token returns the bot's ID.",
- " โ This is NOT your username โ it's a 26-character alphanumeric ID.",
- "5. To get a channel ID: click the channel name โ View Info โ copy the ID",
- ],
- "vars": [
- {"name": "MATTERMOST_URL", "prompt": "Server URL (e.g. https://mm.example.com)",
- "password": False, "help": "Your Mattermost server URL. Works with any self-hosted instance."},
- {"name": "MATTERMOST_TOKEN", "prompt": "Bot token", "password": True,
- "help": "Paste the bot token from step 2 above."},
- {"name": "MATTERMOST_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated)",
- "password": False, "is_allowlist": True,
- "help": "Your user ID from step 4 above (26 characters, not your @username)."},
- {"name": "MATTERMOST_HOME_CHANNEL",
- "prompt": "Home channel ID (for cron/notification delivery, or empty to set later with /set-home)",
- "password": False, "help": "Channel ID where Hermes delivers cron results and notifications."},
- {"name": "MATTERMOST_REPLY_MODE",
- "prompt": "Reply mode โ 'off' for flat messages, 'thread' for threaded replies (default: off)",
- "password": False,
- "help": "off = flat channel messages, thread = replies nest under your message."},
- ],
- },
- ]
- def _all_platforms() -> list[dict]:
- """Built-in ``_PLATFORMS`` plus registry plugin platforms (same dict shape, source in
- ``_registry_entry``). Plugins are discovered here (idempotent) so the setup menu works without a
- running gateway; user-installed ones still need ``plugins.enabled`` (untrusted code). Matrix is
- hidden on Windows: python-olm has no wheel or native build (use WSL)."""
- try:
- from hermes_cli.plugins import discover_plugins
- discover_plugins()
- except Exception as e:
- _gw().logger.debug("plugin discovery failed during platform enumeration: %s", e)
- hide_matrix = sys.platform == "win32"
- platforms = [dict(p) for p in _gw()._PLATFORMS if not (hide_matrix and p.get("key") == "matrix")]
- by_key = {p["key"]: p for p in platforms}
- try:
- from gateway.platform_registry import platform_registry
- except Exception:
- return platforms
- for entry in platform_registry.all_entries():
- if entry.name in by_key or (hide_matrix and entry.name == "matrix"):
- continue
- platforms.append({
- "key": entry.name, "label": entry.label, "emoji": entry.emoji,
- "token_var": entry.required_env[0] if entry.required_env else "",
- "install_hint": entry.install_hint, "_registry_entry": entry,
- })
- return platforms
- def _platform_status(platform: dict) -> str:
- """Plain-text status string; uncolored because ANSI codes break curses menu width math."""
- entry = platform.get("_registry_entry")
- if entry is not None:
- # Prefer is_connected (env + config.yaml) over check_fn (a coarse deps gate). Never fall back
- # to check_fn when is_connected returned False, or "SDK installed" would override "no token".
- try:
- if entry.is_connected is not None:
- from gateway.config import PlatformConfig
- configured = bool(entry.is_connected(PlatformConfig(enabled=True)))
- else:
- configured = bool(entry.check_fn())
- except Exception:
- configured = False
- return "configured" if configured else "not configured"
- token_var = platform.get("token_var", "")
- if not token_var:
- return "not configured"
- return "configured" if _gw().get_env_value(token_var) else "not configured"
- def _set_platform_unauthorized_dm_behavior(platform_key: str, behavior: str) -> None:
- """Persist a platform-specific unauthorized-DM policy in config.yaml."""
- _gw().write_platform_config_field(platform_key, "unauthorized_dm_behavior", behavior, raw=True)
- def print_setup_header(title: str) -> None:
- print()
- print(_gw().color(f" โโโ {title} Setup โโโ", _gw().Colors.CYAN))
- def confirm_reconfigure(label: str, *env_vars: str) -> bool:
- """False when ``label`` is already configured (all ``env_vars`` set) and the user declines."""
- if all(_gw().get_env_value(v) for v in env_vars):
- print()
- _gw().print_success(f"{label} is already configured.")
- return _gw().prompt_yes_no(f" Reconfigure {label}?", False)
- return True
- def offer_home_channel(home_var: str, user_id: str, what: str) -> None:
- """Offer to persist ``user_id`` as ``home_var`` (e.g. "your Telegram user ID")."""
- if _gw().prompt_yes_no(f" Use {what} ({user_id}) as the home channel?", True):
- _gw().save_env_value(home_var, user_id)
- _gw().print_success(f" Home channel set to {user_id}")
- def save_env_values(**values: str) -> None:
- for name, value in values.items():
- _gw().save_env_value(name, value)
- def prompt_csv(prompt_text: str, default: str) -> str:
- """Comma-separated ID prompt with whitespace stripped."""
- return _gw().prompt(prompt_text, default, password=False).replace(" ", "")
- # (default index, *choices) for the no-allowlist access prompt, keyed by is_email.
- _UNAUTHORIZED_ACCESS_CHOICES = {
- True: (3,
- "Enable open access (any email sender can message the bot)",
- "Use DM pairing (unknown email senders receive a pairing code)",
- "Politely decline unknown senders (one-time message, then silence)",
- "Keep unknown senders silent"),
- False: (1,
- "Enable open access (anyone can message the bot)",
- "Use DM pairing (unknown users request access, you approve with 'hermes pairing approve')",
- "Politely decline unknown senders (one-time message, then silence)",
- "Skip for now (bot will deny all users until configured)"),
- }
- def _prompt_unauthorized_access(platform_key: str) -> None:
- """No allowlist was given โ ask open access vs DM pairing vs decline vs skip/silent, and persist."""
- is_email = platform_key == "email"
- print()
- default_idx, *access_choices = _UNAUTHORIZED_ACCESS_CHOICES[is_email]
- access_idx = _gw().prompt_choice(" How should unauthorized users be handled?", access_choices, default_idx)
- if access_idx == 0:
- _gw().save_env_value("EMAIL_ALLOW_ALL_USERS" if is_email else "GATEWAY_ALLOW_ALL_USERS", "true")
- _gw().print_warning(" Open access enabled โ anyone can use your bot!")
- elif access_idx == 1:
- if is_email:
- _set_platform_unauthorized_dm_behavior("email", "pair")
- _gw().print_success(" DM pairing mode โ users will receive a code to request access.")
- _gw().print_info(" Approve with: hermes pairing approve <platform> <code>")
- elif access_idx == 2:
- _set_platform_unauthorized_dm_behavior(platform_key, "decline")
- _gw().print_success(" Unknown senders get one polite decline, then silence (unauthorized_dm_behavior: decline).")
- elif is_email:
- _gw().print_success(" Unknown email senders will be ignored.")
- else:
- _gw().print_info(" Skipped โ configure later with 'hermes gateway setup'")
- def _telegram_auto_setup(token_var: str) -> tuple[bool, object]:
- """Offer the managed-bot QR flow. Returns (token_saved, owner_user_id)."""
- print()
- _gw()._print_info_lines(
- " Telegram can be configured automatically with a managed bot:",
- " [1] Automatic (scan QR โ confirm in Telegram โ done)", " [2] Manual BotFather token",
- )
- if _gw().prompt(" Choice [1/2]", default="1").strip() != "1":
- return False, None
- try:
- from hermes_cli.telegram_managed_bot import (
- auto_setup_telegram_bot_result, is_valid_telegram_bot_token,
- )
- except ImportError:
- _gw().print_warning(" Automatic setup is unavailable in this install.")
- return False, None
- result = auto_setup_telegram_bot_result()
- if result and is_valid_telegram_bot_token(result.token):
- _gw().save_env_value(token_var, result.token)
- _gw().print_success(" Saved TELEGRAM_BOT_TOKEN")
- return True, result.owner_user_id
- if result:
- _gw().print_warning(" Automatic setup returned an invalid Telegram token.")
- print()
- _gw().print_info(" Falling back to manual setup...")
- return False, None
- def _clean_discord_ids(cleaned: str) -> str:
- """Strip common Discord prefixes (user:123, <@123>, <@!123>) from a comma-separated list."""
- parts = []
- for uid in cleaned.split(","):
- uid = uid.strip()
- if uid.startswith("<@") and uid.endswith(">"):
- uid = uid.lstrip("<@!").rstrip(">")
- if uid.lower().startswith("user:"):
- uid = uid[5:]
- if uid:
- parts.append(uid)
- return ",".join(parts)
- def _prompt_allowlist_var(var: dict, platform_key: str, auto_owner_user_id) -> str | None:
- """Allowlist prompt for one var; returns the saved value or None (open-access prompt shown)."""
- if "TELEGRAM" in var["name"] and auto_owner_user_id:
- detected_id = str(auto_owner_user_id)
- _gw().print_success(f" Detected your Telegram user ID: {detected_id}")
- if _gw().prompt_yes_no(" Allow this Telegram account to use the bot?", True):
- extra = _gw().prompt(" Additional allowed user IDs (comma-separated, optional)", password=False)
- ids = [detected_id]
- for uid in extra.replace(" ", "").split(","):
- if uid and uid not in ids:
- ids.append(uid)
- cleaned = ",".join(ids)
- _gw().save_env_value(var["name"], cleaned)
- _gw().print_success(" Saved โ only these users can interact with the bot.")
- return cleaned
- _gw()._print_info_lines(
- " The gateway DENIES all users by default for security.",
- " Enter user IDs to create an allowlist, or leave empty",
- " and you'll be asked about open access next.",
- )
- value = _gw().prompt(f" {var['prompt']}", password=False)
- if not value:
- _prompt_unauthorized_access(platform_key)
- return None
- cleaned = value.replace(" ", "")
- if "DISCORD" in var["name"]:
- cleaned = _clean_discord_ids(cleaned)
- _gw().save_env_value(var["name"], cleaned)
- _gw().print_success(" Saved โ only these users can interact with the bot.")
- return cleaned
- def _setup_standard_platform(platform: dict):
- """Interactive setup for Telegram, Discord, or Slack."""
- from hermes_cli.setup_hidden_env import is_setup_hidden_env as _is_setup_hidden_env
- emoji, label, token_var = platform["emoji"], platform["label"], platform["token_var"]
- print_setup_header(f"{emoji} {label}")
- instructions = platform.get("setup_instructions")
- if instructions:
- print()
- _gw()._print_info_lines(*(f" {line}" for line in instructions))
- if not confirm_reconfigure(label, token_var):
- return
- auto_token_saved, auto_owner_user_id = False, None
- if platform.get("key") == "telegram":
- auto_token_saved, auto_owner_user_id = _telegram_auto_setup(token_var)
- allowed_val_set = None # Track if user set an allowlist (for home channel offer)
- # Skip knobs the setup forms hide (home channel, reply mode, proxy...): they're self-configuring.
- setup_vars = [
- v for v in platform["vars"]
- if v["name"] == token_var or v.get("is_allowlist") or not _is_setup_hidden_env(v["name"])
- ]
- for var in setup_vars:
- print()
- _gw().print_info(f" {var['help']}")
- existing = _gw().get_env_value(var["name"])
- if existing and var["name"] != token_var:
- _gw().print_info(f" Current: {existing}")
- if auto_token_saved and var["name"] == token_var:
- _gw().print_info(" Token saved by automatic setup.")
- continue
- if var.get("is_allowlist"):
- saved = _prompt_allowlist_var(var, platform.get("key"), auto_owner_user_id)
- if saved is not None:
- allowed_val_set = saved
- continue
- value = _gw().prompt(f" {var['prompt']}", password=var.get("password", False))
- if value:
- _gw().save_env_value(var["name"], value)
- _gw().print_success(f" Saved {var['name']}")
- elif var["name"] == token_var:
- _gw().print_warning(f" Skipped โ {label} won't work without this.")
- return
- else:
- _gw().print_info(" Skipped (can configure later)")
- # Offer the first allowlisted user ID as home channel when none is set (Telegram DMs).
- home_var = f"{label.upper()}_HOME_CHANNEL"
- home_val = _gw().get_env_value(home_var)
- if allowed_val_set and not home_val and label == "Telegram":
- first_id = allowed_val_set.split(",")[0].strip()
- if first_id:
- offer_home_channel(home_var, first_id, "your user ID")
- print()
- _gw().print_success(f"{emoji} {label} configured!")
- def _builtin_setup_fn(key: str):
- """Resolve a built-in platform's setup function; late-bound to dodge the hermes_cli.setup cycle."""
- from hermes_cli import setup as _s
- return {
- # telegram/discord/slack/whatsapp/dingtalk/feishu/wecom setup_fns come from their plugins.
- "webhooks": _gw().setup_platforms._setup_webhooks,
- }.get(key)
- def _configure_platform(platform: dict) -> None:
- """Plugin ``setup_fn`` -> built-in by key -> ``_setup_standard_platform`` (``vars``) -> env-var hint.
- Bundled plugins auto-load; user plugins must already be in ``plugins.enabled``."""
- entry = platform.get("_registry_entry")
- fn = entry.setup_fn if entry is not None else None
- if fn is None:
- fn = _builtin_setup_fn(platform["key"])
- if fn is not None:
- fn()
- return
- if platform.get("vars"):
- _gw()._setup_standard_platform(platform)
- return
- label = platform.get("label", platform["key"])
- print_setup_header(f"{platform.get('emoji', '๐')} {label}")
- required = entry.required_env if entry else []
- if required:
- _gw().print_info(f" Set these env vars in ~/.hermes/.env: {', '.join(required)}")
- else:
- _gw().print_info(f" Configure {label} in config.yaml under gateway.platforms.{platform['key']}")
- if platform.get("install_hint"):
- _gw().print_info(f" {platform['install_hint']}")
- def _wizard_offer_service_action(action: str, question: str, failed_label: str, **kwargs) -> None:
- """Wizard start/restart prompt; prints remediation instead when system scope would need root."""
- if _gw().supports_systemd_services() and _gw()._system_scope_wizard_would_need_root():
- _gw()._print_system_scope_remediation(action)
- elif _gw().prompt_yes_no(question, True):
- _gw()._setup_service_action(action, failed_label=failed_label, **kwargs)
- def _setup_service_action(
- action: str, *, failed_label: str, windows: bool = True, system: bool = False
- ) -> None:
- """Run a wizard service start/restart, printing remediation instead of raising. ``windows=False``
- skips Windows (pre-platform status block never offers it); ``system`` is a fresh install's scope."""
- try:
- backend = _gw()._service_backend(windows=windows)
- if backend is not None:
- _gw()._service_call(backend, action, None if action == "restart" else system)
- elif action == "restart" and windows:
- _gw().stop_profile_gateway()
- _gw().print_info("Start manually: hermes gateway")
- except _gw().UserSystemdUnavailableError as e:
- _gw().print_error(f" {failed_label} โ user systemd not reachable:")
- _gw()._print_indented(str(e))
- except _gw().SystemScopeRequiresRootError as e:
- # Defense in depth: the wizard's root pre-check should have caught this.
- _gw().print_error(f" {failed_label}: {e}")
- _gw()._print_system_scope_remediation(action)
- except subprocess.CalledProcessError as e:
- _gw().print_error(f" {failed_label}: {e}")
- _WIZARD_BANNER = (
- "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ",
- "โ โค Gateway Setup โ",
- "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค",
- "โ Configure messaging platforms and the gateway service. โ",
- "โ Press Ctrl+C at any time to exit. โ",
- "โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ",
- )
- _WIZARD_BACKEND_LABELS = {"systemd": "systemd", "launchd": "launchd", "windows": "Scheduled Task"}
- # Post-setup guidance when no service backend applies, keyed by the fallthrough reason.
- _WIZARD_NO_SERVICE_LINES = {
- "wsl": (
- " WSL detected but systemd is not running.", " Run in foreground: hermes gateway run",
- " For persistence: tmux new -s hermes 'hermes gateway run'",
- " To enable systemd: add systemd=true to /etc/wsl.conf, then 'wsl --shutdown'",
- ),
- "termux": (
- " Termux does not use systemd/launchd services.", " Run in foreground: hermes gateway run",
- " Or start it manually in the background (best effort): nohup hermes gateway run >{home}/logs/gateway.log 2>&1 &",
- ),
- "unsupported": (
- " Service install not supported on this platform.", " Run in foreground: hermes gateway run",
- ),
- }
- def _wizard_service_status_block() -> None:
- """Pre-platform service status: warnings, then offer to start an installed-but-stopped service."""
- print()
- service_installed = _gw()._is_service_installed()
- service_running = _gw()._is_service_running()
- if _gw().supports_systemd_services() and _gw().has_conflicting_systemd_units():
- _gw().print_systemd_scope_conflict_warning()
- print()
- if _gw().supports_systemd_services() and _gw().has_legacy_hermes_units():
- _gw().print_legacy_unit_warning()
- print()
- if service_installed and service_running:
- _gw().print_success("Gateway service is installed and running.")
- elif service_installed:
- _gw().print_warning("Gateway service is installed but not running.")
- _wizard_offer_service_action("start", " Start it now?", "Failed to start", windows=False)
- else:
- _gw().print_info("Gateway service is not installed yet.")
- _gw().print_info("You'll be offered to install it after configuring platforms.")
- def _wizard_platform_loop() -> None:
- while True:
- print()
- _gw().print_header("Messaging Platforms")
- platforms = _gw()._all_platforms()
- menu_items = [f"{p['emoji']} {p['label']} ({_platform_status(p)})" for p in platforms] + ["Done"]
- choice = _gw().prompt_choice("Select a platform to configure:", menu_items, len(menu_items) - 1)
- if choice == len(platforms):
- break
- _gw()._configure_platform(platforms[choice])
- def _wizard_install_service(backend: str) -> None:
- """Fresh install from the wizard: ask start-now / start-on-login once, install, then start.
- The Windows installer owns its start decision (Scheduled Task and Startup-folder
- paths start the gateway themselves when start_now is true, and a UAC hand-off
- installs and starts in the elevated child), so the wizard forwards the answers
- and returns without a second start. Each install-intent question is asked exactly
- once per setup run."""
- wsl_note = " (note: services may not survive WSL restarts)" if _gw().is_wsl() else ""
- start_now = _gw().prompt_yes_no(" Start the gateway now?", True)
- start_on_login = _gw().prompt_yes_no(
- f" Start the gateway automatically on login/boot as a {_WIZARD_BACKEND_LABELS[backend]} service?"
- f"{wsl_note}",
- True,
- )
- if not (start_now or start_on_login):
- _gw().print_info(" Skipped start and auto-start setup.")
- _gw().print_info(" You can install later: hermes gateway install")
- if _gw().supports_systemd_services():
- _gw().print_info(" Or as a boot-time service: sudo hermes gateway install --system")
- _gw().print_info(" Or run in foreground: hermes gateway run")
- return
- try:
- installed_scope, did_install = None, True
- if backend == "systemd":
- installed_scope, did_install = _gw().install_linux_gateway_from_setup(
- force=False, enable_on_startup=start_on_login
- )
- elif backend == "launchd":
- _gw().launchd_install(force=False, start_now=start_now)
- else:
- _gw()._gw_windows().install(force=False, start_now=start_now, start_on_login=start_on_login)
- return
- print()
- if did_install and start_now:
- _gw()._setup_service_action("start", failed_label="Start failed", system=installed_scope == "system")
- except subprocess.CalledProcessError as e:
- _gw().print_error(f" Install failed: {e}")
- _gw().print_info(" You can try manually: hermes gateway install")
- except SystemExit:
- # The backend installers exit non-zero on a refused write (a unit pinning another home);
- # setup reports it and goes on rather than ending the wizard.
- _gw().print_warning(" Gateway service install did not complete.")
- _gw().print_info(" You can try manually: hermes gateway install")
- def _wizard_post_setup() -> None:
- """Offer to install/start/restart the gateway once at least one platform has progress."""
- print()
- print(_gw().color("โ" * 58, _gw().Colors.DIM))
- if _gw()._served_profile_needs_no_service():
- return
- service_installed = _gw()._is_service_installed()
- service_running = _gw()._is_service_running()
- if service_running:
- _wizard_offer_service_action("restart", " Restart the gateway to pick up changes?", "Restart failed")
- elif service_installed:
- _wizard_offer_service_action("start", " Start the gateway service?", "Start failed")
- else:
- print()
- backend = _gw()._service_backend()
- if backend is not None:
- _gw()._wizard_install_service(backend)
- return
- if _gw().is_wsl():
- reason, home = "wsl", ""
- elif _gw().is_termux():
- from hermes_constants import display_hermes_home as _dhh
- reason, home = "termux", _dhh()
- else:
- reason, home = "unsupported", ""
- _gw()._print_info_lines(*(line.format(home=home) for line in _WIZARD_NO_SERVICE_LINES[reason]))
- def gateway_setup():
- """Interactive setup for messaging platforms + gateway service."""
- if _gw().is_managed():
- _gw().managed_error("run gateway setup")
- return
- print()
- for banner_line in _WIZARD_BANNER:
- print(_gw().color(banner_line, _gw().Colors.MAGENTA))
- _wizard_service_status_block()
- _wizard_platform_loop()
- # Meaningful progress on any platform; ``_platform_status`` already handles plugin dual states.
- def _is_progress(status: str) -> bool:
- s = status.lower()
- return not (s == "not configured" or s.startswith("partially") or s.startswith("plugin disabled"))
- if any(_is_progress(_gw()._platform_status(p)) for p in _gw()._all_platforms()):
- _gw()._wizard_post_setup()
- else:
- print()
- _gw().print_info("No platforms configured. Run 'hermes gateway setup' when ready.")
- print()
|