Add tray applet design spec
Optional desktop system-tray applet as a thin launcher over the existing CLI and systemd. Core agent stays stdlib-only; tray ships as an optional [tray] extra (pystray + Pillow). Covers menu actions, icon state, error handling, packaging, and testing seams. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Luna
parent
6a9e94c9fa
commit
2e7bf8b248
1 changed files with 129 additions and 0 deletions
129
docs/superpowers/specs/2026-06-30-tray-applet-design.md
Normal file
129
docs/superpowers/specs/2026-06-30-tray-applet-design.md
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
# Tray Applet Design
|
||||
|
||||
Date: 2026-06-30
|
||||
Status: Approved (pending spec review)
|
||||
Topic: Optional desktop system-tray applet for ease-of-use.
|
||||
|
||||
## Goal
|
||||
|
||||
Provide a lightweight, optional desktop tray icon that lets an operator open
|
||||
the dashboard, control the daemon, see status at a glance, and run a quick
|
||||
check — without compromising the core agent's stdlib-only, zero runtime
|
||||
dependency posture.
|
||||
|
||||
## Constraints and Non-Negotiables
|
||||
|
||||
- The core `enodia_sentinel` package and the daemon stay **stdlib-only**. Their
|
||||
runtime dependency list remains empty. The tray dependency is an *optional
|
||||
extra* only.
|
||||
- The applet is a **frontend**. It must not import daemon internals or add GUI
|
||||
libraries to the daemon's import graph. It drives the existing
|
||||
`enodia-sentinel` CLI and `systemctl`. This keeps the trust boundary clean
|
||||
and the applet auditable.
|
||||
- No new config keys. The applet reuses the existing `Config` values
|
||||
(`web_port` default `8787`, `web_bind`, `log_dir`).
|
||||
- No stealth, persistence tricks, or destructive remediation (project rule).
|
||||
|
||||
## Approach
|
||||
|
||||
Approach A — thin launcher (chosen over an embedded in-process controller,
|
||||
which would drag GUI deps into the daemon's import graph and blur the
|
||||
stdlib-only boundary).
|
||||
|
||||
Library: `pystray` + `Pillow`, shipped as an optional extra. On the target KDE
|
||||
Plasma Wayland host `pystray` already resolves to the AppIndicator (Ayatana)
|
||||
backend — the correct StatusNotifierItem path — and it is cross-desktop, so the
|
||||
applet is not KDE-locked. PySide6/Qt would be the most KDE-native option but is
|
||||
too heavy for a launcher menu.
|
||||
|
||||
Process model: systemd. Start/Stop/Restart go through `systemctl` against the
|
||||
packaged system units (`enodia-sentinel.service`, `enodia-sentinel-web.service`).
|
||||
On KDE the polkit agent prompts for auth, which is expected and correct.
|
||||
|
||||
## Architecture
|
||||
|
||||
New, separate optional component:
|
||||
|
||||
- `enodia_sentinel/tray/__init__.py`
|
||||
- `enodia_sentinel/tray/app.py` — applet wiring (pystray icon, menu, run loop).
|
||||
- `enodia_sentinel/tray/__main__.py` — `python -m enodia_sentinel.tray`.
|
||||
- New console entry point `enodia-sentinel-tray` (separate from
|
||||
`enodia-sentinel`).
|
||||
- `pyproject.toml`: `[project.optional-dependencies] tray = ["pystray", "Pillow"]`.
|
||||
Core `dependencies` stays `[]`.
|
||||
|
||||
Internal seams (kept pure and testable, no GUI/subprocess at import time):
|
||||
|
||||
- A status reader that runs `enodia-sentinel status --json`, parses it, and maps
|
||||
it to a small `TrayState` (running/stopped/unknown, alert count, derived icon
|
||||
color). Subprocess runner is injectable for tests.
|
||||
- A URL builder that computes the loopback dashboard URL from `Config`.
|
||||
- An action layer that wraps `systemctl` / CLI calls behind named functions, all
|
||||
timeout-bounded, returning a result object (ok, message, stderr tail).
|
||||
- A notification helper that prefers `notify-send` and falls back to pystray's
|
||||
`notify`.
|
||||
- The pystray wiring layer that binds menu items to the action layer — a thin
|
||||
shell, intentionally minimal and not unit-tested.
|
||||
|
||||
## Components and Menu Behavior
|
||||
|
||||
| Menu item | Behavior |
|
||||
|---|---|
|
||||
| Status line (disabled label) | `Running — N alerts today` / `Stopped` / `Unknown`. Sourced from `enodia-sentinel status --json`. Refreshed on a timer (default 15s) and on menu open. |
|
||||
| Open dashboard | Compute loopback URL `https://127.0.0.1:<web_port>/`; ensure `enodia-sentinel-web.service` is active (start if not); open via `webbrowser`. Loopback needs no token. Self-signed cert triggers the existing first-visit browser warning. |
|
||||
| Start / Stop / Restart daemon | `systemctl start/stop/restart enodia-sentinel.service`. Polkit prompts on KDE. Status line reflects the new state after the action. |
|
||||
| Run quick check | Run `enodia-sentinel check --json` in a worker thread; summarize findings as a desktop notification. (Optionally also `rootcheck`.) |
|
||||
| Quit | Exit the applet only. Does not touch the daemon. |
|
||||
|
||||
## Icon State
|
||||
|
||||
The tray icon reflects daemon health:
|
||||
|
||||
- green — running, no recent alerts
|
||||
- amber — running with recent alerts
|
||||
- grey — stopped or unknown
|
||||
|
||||
Icons are generated in-memory with Pillow to avoid shipping and managing binary
|
||||
asset files.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- `systemctl` or `enodia-sentinel` missing / non-zero exit → status line shows
|
||||
`Unknown`; the triggering action raises a desktop notification with the
|
||||
stderr tail. The applet never crashes on a failed subprocess.
|
||||
- Polkit auth cancelled → notification "action cancelled"; no state change.
|
||||
- All subprocess calls are timeout-bounded and run off the UI thread so the menu
|
||||
never freezes.
|
||||
|
||||
## Packaging and Docs
|
||||
|
||||
- `packaging/enodia-sentinel-tray.desktop` — opt-in autostart entry so the tray
|
||||
can launch on login.
|
||||
- Update `README.md`, `docs/COMMAND_REFERENCE.md` (new `enodia-sentinel-tray`
|
||||
entry and `[tray]` extra), `docs/OPERATIONS.md`, and `docs/PACKAGING.md`.
|
||||
- No `config/enodia-sentinel.toml` changes (no new keys).
|
||||
|
||||
## Testing
|
||||
|
||||
- Pure-logic units tested with stdlib `unittest`, injecting fake subprocess
|
||||
runners: status JSON parsing, `TrayState` mapping, loopback URL building,
|
||||
notification formatting, action-result handling. No GUI or X/Wayland server
|
||||
required in CI.
|
||||
- The pystray wiring layer is a thin shell and is not unit-tested, consistent
|
||||
with how the web GUI layer is treated.
|
||||
|
||||
## Scope Guardrails (YAGNI)
|
||||
|
||||
Out of scope: in-applet config editor, live event stream, alert-history browser
|
||||
(all the dashboard's job). The applet is a launcher plus a status light, nothing
|
||||
more.
|
||||
|
||||
## Open Considerations
|
||||
|
||||
- Non-loopback web binds (e.g. Tailscale IP with a required token): the applet
|
||||
targets the loopback URL for local desktop use, which avoids token handling.
|
||||
If a deployment binds web off-loopback only, "Open dashboard" still opens the
|
||||
loopback URL; surfacing a token-bearing remote URL is explicitly out of scope
|
||||
for this iteration.
|
||||
- System units require privilege; the polkit prompt is the intended UX. A future
|
||||
`systemctl --user` variant is out of scope here.
|
||||
Loading…
Add table
Add a link
Reference in a new issue