enodia-sentinal/docs/superpowers/specs/2026-06-30-tray-applet-design.md

# 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.