Skip to content

feat(cli): add telegram channel adapter, scoped bridge config, and diagnostics#110

Closed
cdenneen wants to merge 28 commits intohappier-dev:devfrom
cdenneen:feat/telegram-channel-adapter
Closed

feat(cli): add telegram channel adapter, scoped bridge config, and diagnostics#110
cdenneen wants to merge 28 commits intohappier-dev:devfrom
cdenneen:feat/telegram-channel-adapter

Conversation

@cdenneen
Copy link

@cdenneen cdenneen commented Mar 4, 2026

⚠️ Stacked PR

This PR is stacked on top of PR1 (channel bridge core).
Please review against base branch: feat/channel-bridge-core.


Summary

This PR adds Telegram support on top of the provider-agnostic channel bridge core, including:

  • Telegram adapter (polling + optional webhook relay mode)
  • Account-scoped bridge config and CLI management
  • Server KV sync for non-secret bridge state
  • Local-only secret handling policy
  • Doctor diagnostics with critical failure aggregation
  • UAT + onboarding docs and screenshot evidence

What’s Included

Telegram adapter + runtime wiring

  • Added Telegram adapter:
    • apps/cli/src/channels/telegram/telegramAdapter.ts
    • apps/cli/src/channels/telegram/telegramAdapter.test.ts
  • Added optional daemon-local webhook relay:
    • apps/cli/src/channels/telegram/telegramWebhookRelay.ts
    • apps/cli/src/channels/telegram/telegramWebhookRelay.test.ts
  • Wired bridge startup/runtime:
    • apps/cli/src/channels/startChannelBridgeWorker.ts
    • apps/cli/src/channels/startChannelBridgeWorker.test.ts

Scoped bridge configuration + persistence

  • Added server/account-scoped bridge config model:
    • apps/cli/src/channels/channelBridgeAccountConfig.ts
    • apps/cli/src/channels/channelBridgeConfig.ts
  • Added server KV record + overlay logic:
    • apps/cli/src/channels/channelBridgeServerKv.ts
    • apps/cli/src/channels/channelBridgeServerConfigOverlay.ts
  • Added server-backed binding store:
    • apps/cli/src/channels/channelBindingStore.server.ts

CLI management

  • Added happier bridge command group:
    • apps/cli/src/cli/commands/bridge.ts
    • apps/cli/src/cli/commands/bridge.test.ts
  • Registered CLI command wiring:
    • apps/cli/src/cli/commandRegistry.ts
    • apps/cli/src/cli/dispatch.ts

Security / Secret Handling

Implemented local-only secret policy for bridge credentials:

  • botToken / webhookSecret stay local (settings.json / env)
  • server KV sync stores non-secret bridge config only
  • precedence: env > server KV (non-secret) > local scoped settings > defaults

This establishes the same pattern for future adapters (Discord/Slack/WhatsApp/etc).


Doctor Diagnostics Improvements

Updated doctor behavior to surface bridge health as real pass/fail:

  • masks secrets in output
  • marks critical bridge failures (red ❌)
  • final diagnosis now reflects aggregated critical failures:
    • ✅ Doctor diagnosis complete! only when no critical failures
    • ❌ Doctor diagnosis complete! when any critical failure exists
  • critical webhook checks when webhook.enabled=true:
    • missing webhook.secret
    • missing/invalid webhook.host
    • missing/invalid webhook.port
  • generic webhook-required checks also applied for non-Telegram providers when present

Documentation

  • Telegram onboarding + bridge architecture:
    • docs/telegram-channel-bridge.md
  • UAT checklist:
    • docs/channel-bridge-uat.md
  • README link update:
    • README.md

Screenshot evidence

  • Doctor critical webhook secret check

  • Doctor critical webhook host/port check


Tests

Added/updated focused tests across:

  • channel bridge config and KV flows
  • scoped config split (shared vs local secrets)
  • runtime wiring and adapter behavior
  • bridge CLI command behavior
  • doctor critical diagnostics behavior

Representative files:

  • apps/cli/src/channels/channelBridgeAccountConfig.test.ts
  • apps/cli/src/channels/channelBridgeConfig.test.ts
  • apps/cli/src/channels/channelBridgeServerKv.test.ts
  • apps/cli/src/channels/channelBridgeServerConfigOverlay.test.ts
  • apps/cli/src/channels/channelBindingStore.server.test.ts
  • apps/cli/src/channels/startChannelBridgeWorker.test.ts
  • apps/cli/src/channels/telegram/telegramAdapter.test.ts
  • apps/cli/src/channels/telegram/telegramWebhookRelay.test.ts
  • apps/cli/src/cli/commands/bridge.test.ts
  • apps/cli/src/ui/doctor.test.ts

Suggestions:

  • Set PR2 base to feat/channel-bridge-core before opening (so review is clean).
  • After PR1 merges, retarget PR2 to dev and verify diff stays unchanged.

Summary by CodeRabbit

  • New Features

    • Channel Bridge for Telegram: runtime worker, Telegram adapter (polling & webhook), server-backed KV persistence with in-memory fallback, CLI "bridge" commands, webhook relay, and start-from-env bootstrap.
  • Documentation

    • Added Channel Bridge core guide, Telegram guide, UAT checklist, and updated docs index; README Channel Integrations section added.
  • Improvements

    • Doctor CLI now validates Telegram webhook/bridge settings; settings schema includes channelBridge.
  • Tests

    • Extensive coverage for config resolution, KV behavior, adapter, worker, webhook relay, CLI, and lifecycle.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant