From a56408711e3d81154ada347cc5f6186ed6395152 Mon Sep 17 00:00:00 2001 From: evandrodevbr Date: Wed, 15 Jul 2026 17:58:49 -0300 Subject: [PATCH] docs: specify Telegram status integration --- .../2026-07-15-telegram-omp-status-design.md | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-15-telegram-omp-status-design.md diff --git a/docs/superpowers/specs/2026-07-15-telegram-omp-status-design.md b/docs/superpowers/specs/2026-07-15-telegram-omp-status-design.md new file mode 100644 index 0000000..9335d23 --- /dev/null +++ b/docs/superpowers/specs/2026-07-15-telegram-omp-status-design.md @@ -0,0 +1,73 @@ +# Telegram OMP 17 status indicator + +## Goal + +Make the Telegram bridge visible in OMP 17's upper status bar, immediately after the cost segment, and correct the OMP installation guidance. Configure a replacement bot token only through the local interactive OMP setup flow. + +## Scope + +- Add a public OMP extension API for a status-bar segment placed after `cost`. +- Have `@evandrodevbr/oh-my-pi-telegram` register one segment through that API. +- Update the segment when bridge polling starts, stops, fails, or a session is replaced. +- Update the plugin README with OMP 17 plugin commands and secure setup instructions. + +## OMP core API + +OMP owns status-bar ordering and rendering. The API accepts a keyed text segment and exposes only the supported placement: + +- `after: "cost"` +- a stable extension key +- plain text supplied by the extension + +OMP sanitizes extension text using the existing status-text sanitizer and renders registered segments after its own `cost` segment, before subsequent built-in segments. An extension clears its segment by passing `undefined`. Extension segments cannot choose arbitrary insertion positions or access the status-line component directly. + +The implementation belongs in a versioned OMP source checkout or fork, not the global Bun installation, because `omp update` replaces global package files. + +## Telegram bridge behavior + +The plugin registers the `telegram` segment once the extension UI is available. It derives the value from the existing bridge status runtime: + +| Runtime condition | Status-bar text | +| --- | --- | +| Telegram polling active | `Telegram: conectado` | +| Telegram polling inactive | `Telegram: desconectado` | + +The plugin updates the registered segment through its existing status update flow. This covers `/telegram-connect`, `/telegram-disconnect`, polling errors and recovery, lock ownership changes, and session lifecycle updates. It does not make a network request merely to render a status value. + +## Configuration + +The replacement token is configured only in an interactive local OMP session: + +```text +/telegram-setup +/telegram-connect +``` + +The token must not be put in chat, source code, README examples, committed configuration, test fixtures, logs, or terminal output. The plugin continues using its existing local configuration file and profile behavior. + +## README + +The primary OMP installation commands become: + +```bash +omp plugin install npm:@evandrodevbr/oh-my-pi-telegram +omp plugin install git:github.com/evandrodevbr/oh-my-pi-telegram +omp plugin link /path/to/oh-my-pi-telegram +``` + +The README states that an OMP session must be restarted after installation or linking, then documents `/telegram-setup`, `/telegram-connect`, `/telegram-disconnect`, and `/telegram-status`. + +## Verification + +- OMP unit test: a registered extension segment is rendered immediately after `cost`; clearing it removes it; text is sanitized. +- Telegram plugin test: active polling renders `Telegram: conectado`; inactive polling renders `Telegram: desconectado`; the current UI registration API is exercised. +- Plugin type-check and public-package tests pass. +- OMP 17 smoke test: the linked plugin loads and `/telegram-status` returns. +- Manual local configuration: `/telegram-setup` validates the new bot token, `/telegram-connect` activates polling, and the status bar changes state. + +## Non-goals + +- No direct modification of global Bun-installed OMP files. +- No status segment placement other than after `cost`. +- No retry policy, network health probe, or separate Telegram connection abstraction. +- No token migration or token disclosure.