Design Panama Health and Recovery
This commit is contained in:
Gabriel Brown
@@ -0,0 +1,235 @@
|
|||||||
|
# Panama Health & Recovery Design
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Panama Health & Recovery makes the desktop explain itself. It verifies the
|
||||||
|
local services, dependencies, links, and integrations that Panama relies on,
|
||||||
|
then presents useful recovery actions without asking the user to read logs or
|
||||||
|
diagnose a collection of unrelated Linux processes.
|
||||||
|
|
||||||
|
The feature is intentionally quiet. A healthy desktop produces no notification,
|
||||||
|
banner, or permanent bar ornament. Problems appear in Panama Settings and, when
|
||||||
|
actionable, as one restrained bar indicator. User-initiated repairs receive
|
||||||
|
immediate Prism OSD or inline feedback.
|
||||||
|
|
||||||
|
## Product boundaries
|
||||||
|
|
||||||
|
The first release covers Panama-owned or Panama-integrated functionality:
|
||||||
|
|
||||||
|
- Hyprland, Quickshell, the notification server, XDG desktop portals, PipeWire,
|
||||||
|
Vicinae, the clipboard watcher, wallpaper, idle policy, and Panama's runtime
|
||||||
|
configuration links.
|
||||||
|
- The Panama command collection, screenshot and OCR dependencies, DDC
|
||||||
|
brightness support, and the currently selected terminal and launcher.
|
||||||
|
- Nextcloud, RustDesk, KDE Connect, BlueBubbles, Home Assistant, calendar
|
||||||
|
aggregation, and the configured autostart entries.
|
||||||
|
- Orphaned Panama processes and inhibitors, including duplicate Caffeine locks.
|
||||||
|
- Versions and non-sensitive diagnostic context needed for a useful copied
|
||||||
|
report.
|
||||||
|
|
||||||
|
It does not become a package manager, a generic system monitor, or a replacement
|
||||||
|
for Fedora's troubleshooting tools. It never installs packages, invokes `sudo`,
|
||||||
|
deletes user data, rewrites arbitrary configuration, or repairs services Panama
|
||||||
|
does not own.
|
||||||
|
|
||||||
|
An optional integration that has never been configured is neutral **Not set
|
||||||
|
up**, not a warning. A configured integration that cannot operate is degraded.
|
||||||
|
This distinction prevents the health UI from pressuring the user to enable
|
||||||
|
features they do not want.
|
||||||
|
|
||||||
|
## Information architecture
|
||||||
|
|
||||||
|
The existing **Startup & Services** destination becomes **System Health**. This
|
||||||
|
avoids two pages reporting the same background services. Its existing Open and
|
||||||
|
Refresh actions remain available through the richer health rows.
|
||||||
|
|
||||||
|
The page has four levels:
|
||||||
|
|
||||||
|
1. A compact summary hero: **Healthy**, **Needs attention**, or **Action
|
||||||
|
required**, the last completed scan time, Refresh, and Copy Report.
|
||||||
|
2. An issues-first section shown only when one or more checks are degraded.
|
||||||
|
3. Grouped cards for Desktop Foundation, Input & Media, Integrations, and Panama
|
||||||
|
Tools. Healthy rows remain visible but visually quiet.
|
||||||
|
4. A short boundary note linking to GNOME or Fedora tools for system areas Panama
|
||||||
|
does not own.
|
||||||
|
|
||||||
|
Each row contains a stable title, one-sentence observation, status label, and at
|
||||||
|
most one primary action. Actions use concrete language such as **Restart
|
||||||
|
Vicinae**, **Repair command link**, **Open Home settings**, or **View setup
|
||||||
|
instructions**. There is no generic Fix Everything button.
|
||||||
|
|
||||||
|
The Settings sidebar's existing health footer becomes real and clickable. It
|
||||||
|
shows the aggregate state and opens System Health. The top bar gains a small
|
||||||
|
`HealthIndicator` only while an actionable warning or error exists; clicking it
|
||||||
|
opens the same page. Background scans never publish Signal Glass events or
|
||||||
|
desktop notifications.
|
||||||
|
|
||||||
|
## Diagnostic engine
|
||||||
|
|
||||||
|
`config/dot/quickshell/scripts/panama-doctor` is the single operating-system
|
||||||
|
boundary. It supports:
|
||||||
|
|
||||||
|
- `panama-doctor --json` for a complete versioned snapshot.
|
||||||
|
- `panama-doctor --summary` for a concise human-readable installer or terminal
|
||||||
|
result.
|
||||||
|
- `panama-doctor --repair CHECK_ID --json` for an explicitly allow-listed repair.
|
||||||
|
|
||||||
|
The helper emits one schema:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schemaVersion": 1,
|
||||||
|
"generatedAt": "2026-08-18T12:00:00Z",
|
||||||
|
"summary": {
|
||||||
|
"status": "warning",
|
||||||
|
"healthy": 18,
|
||||||
|
"warnings": 1,
|
||||||
|
"errors": 0,
|
||||||
|
"unconfigured": 2
|
||||||
|
},
|
||||||
|
"checks": [
|
||||||
|
{
|
||||||
|
"id": "launcher.panama-commands",
|
||||||
|
"group": "panama-tools",
|
||||||
|
"title": "Panama Commands",
|
||||||
|
"status": "warning",
|
||||||
|
"detail": "16 of 17 commands are loaded",
|
||||||
|
"action": {
|
||||||
|
"kind": "repair",
|
||||||
|
"label": "Repair command link"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Allowed statuses are `ok`, `warning`, `error`, and `unconfigured`. Check IDs,
|
||||||
|
group IDs, titles, and repair mappings are authored constants. Probe output may
|
||||||
|
populate observations but can never become a command or executable argument.
|
||||||
|
|
||||||
|
Checks run concurrently where doing so is safe, with short per-probe timeouts.
|
||||||
|
A failed or timed-out probe yields a check result rather than aborting the whole
|
||||||
|
snapshot. Output order is deterministic so tests, copied reports, and visual
|
||||||
|
rows do not jump between scans.
|
||||||
|
|
||||||
|
No secrets are read. The report may state whether a Home Assistant URL or token
|
||||||
|
is configured, but never includes either value. It excludes clipboard contents,
|
||||||
|
notification bodies, calendar event data, SSIDs, device addresses, environment
|
||||||
|
values, file contents, and command output that has not been explicitly parsed.
|
||||||
|
|
||||||
|
## Quickshell state and refresh model
|
||||||
|
|
||||||
|
`services/Health.qml` owns the latest accepted snapshot, aggregate severity,
|
||||||
|
busy state, last scan time, and the result of the most recent repair. It invokes
|
||||||
|
`panama-doctor` with argument arrays through `Process`; UI components never
|
||||||
|
construct shell commands.
|
||||||
|
|
||||||
|
Health performs one delayed scan after the shell reaches a stable startup state.
|
||||||
|
It scans again when the System Health page is opened, when the user presses
|
||||||
|
Refresh, and after a repair settles. There is no periodic polling loop while the
|
||||||
|
desktop is idle. Services that already expose event-driven state remain the
|
||||||
|
authoritative source for their own interactive controls; Health is a diagnostic
|
||||||
|
snapshot, not a competing live service model.
|
||||||
|
|
||||||
|
Every scan receives a monotonically increasing generation. Late output from an
|
||||||
|
older scan is discarded. A malformed snapshot leaves the last valid result in
|
||||||
|
place, marks the diagnostic engine unavailable, and offers a bounded Retry.
|
||||||
|
|
||||||
|
The shell exposes a typed `health` IPC target with `refresh`, `status`, `open`,
|
||||||
|
and `repair(id)` operations. Vicinae gains **Panama: Check System Health**, which
|
||||||
|
opens the page and requests a fresh scan through the existing `panama-action`
|
||||||
|
dispatcher.
|
||||||
|
|
||||||
|
## Repair policy
|
||||||
|
|
||||||
|
Repairs are narrow, reversible, and attached to one check. The first release may:
|
||||||
|
|
||||||
|
- Restart Panama's user services such as Vicinae, Hyprpaper, or Hypridle.
|
||||||
|
- Recreate Panama-owned symlinks when their destination is known and tracked.
|
||||||
|
- Reload Vicinae's Panama command collection.
|
||||||
|
- Release duplicate user-owned inhibitors whose metadata identifies Panama and
|
||||||
|
Caffeine.
|
||||||
|
- Restart Quickshell through the verified `panama-action restart-shell` path.
|
||||||
|
- Open the exact Panama Settings page required to finish credentials or entity
|
||||||
|
selection.
|
||||||
|
|
||||||
|
Restarting a working service is not presented as a repair. Repairs that interrupt
|
||||||
|
visible desktop chrome require a confirmation sheet in Settings. Navigation and
|
||||||
|
setup actions do not. Package installation, privileged service changes, display
|
||||||
|
mode writes, and destructive cleanup are never automatic; the UI shows concise
|
||||||
|
instructions instead.
|
||||||
|
|
||||||
|
After a repair, Health rescans and judges success from the observed result. A
|
||||||
|
zero exit status alone never turns a row green. Failure remains inline on the
|
||||||
|
affected row and also produces the existing Panama action-failure notification
|
||||||
|
when the action originated outside Settings.
|
||||||
|
|
||||||
|
## Visual language and interaction
|
||||||
|
|
||||||
|
System Health uses the established Settings cards and Prism tokens. Healthy
|
||||||
|
states use a small muted green dot and subdued **Healthy** copy. Warnings use
|
||||||
|
amber; red is reserved for functionality that is configured, required, and
|
||||||
|
currently broken. `unconfigured` rows use neutral gray.
|
||||||
|
|
||||||
|
The summary hero does not use a decorative gauge, percentage score, pulse,
|
||||||
|
shimmer, or animated gradient. A desktop is not “82% healthy.” The headline and
|
||||||
|
issue count are more understandable and do not create false precision.
|
||||||
|
|
||||||
|
Rows keep their height stable while refreshing. The previous snapshot remains
|
||||||
|
visible with a quiet **Checking…** label rather than replacing the page with a
|
||||||
|
spinner. Keyboard focus order reaches Refresh, Copy Report, issue rows, repair
|
||||||
|
actions, and external handoffs. Status is always expressed in text as well as
|
||||||
|
color.
|
||||||
|
|
||||||
|
Before production components are edited, the page and degraded bar indicator
|
||||||
|
will be shown in several static mocks using the existing Settings geometry. The
|
||||||
|
chosen mock must preserve this information architecture and Panama's current
|
||||||
|
Prism language rather than introduce a new visual system.
|
||||||
|
|
||||||
|
## Failure handling
|
||||||
|
|
||||||
|
- Missing required executables become actionable check results.
|
||||||
|
- Missing optional applications remain neutral until configured.
|
||||||
|
- A doctor crash, timeout, or malformed JSON does not clear the last good
|
||||||
|
snapshot or crash Quickshell.
|
||||||
|
- Concurrent refresh requests coalesce into one follow-up scan.
|
||||||
|
- A repair request for an unknown or non-repairable ID is rejected before any
|
||||||
|
process starts.
|
||||||
|
- Copy Report uses only the already-redacted snapshot and reports clipboard
|
||||||
|
failure inline.
|
||||||
|
- If the Settings window is closed during a scan or repair, the process may
|
||||||
|
finish; reopening the page shows the settled result.
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
- Run the real helper against isolated fake command, config, state, and runtime
|
||||||
|
directories and prove every status transition deterministically.
|
||||||
|
- Validate the JSON schema, stable check IDs, deterministic ordering, and
|
||||||
|
uniqueness of each ID.
|
||||||
|
- Prove unconfigured integrations remain neutral while configured failures are
|
||||||
|
degraded.
|
||||||
|
- Prove reports contain no fixture secrets, clipboard text, calendar data,
|
||||||
|
addresses, or unparsed environment values.
|
||||||
|
- Exercise every repair through the allow-list, assert its exact command, and
|
||||||
|
prove unknown IDs cannot execute anything.
|
||||||
|
- Test scan generations, malformed snapshots, refresh coalescing, repair
|
||||||
|
rescans, and preservation of the last valid state in a Quickshell harness.
|
||||||
|
- Verify Settings routing, search entries, the live sidebar footer, and the
|
||||||
|
degraded-only bar indicator without QML warnings.
|
||||||
|
- Validate the Vicinae command and typed IPC surface.
|
||||||
|
- Run a read-only doctor scan on the real workstation and compare key results to
|
||||||
|
direct service checks. State-changing live repair tests require an actually
|
||||||
|
degraded disposable target or explicit user approval.
|
||||||
|
- Restart the live shell, inspect the fresh log, and visually review healthy,
|
||||||
|
warning, error, unconfigured, refreshing, and repair-result states.
|
||||||
|
|
||||||
|
## Delivery slices
|
||||||
|
|
||||||
|
1. Diagnostic schema, read-only probes, redaction, and contract tests.
|
||||||
|
2. `Health.qml`, typed IPC, startup/manual refresh, and fixture harness.
|
||||||
|
3. System Health Settings page, live sidebar footer, search, and report copy.
|
||||||
|
4. Degraded-only bar indicator and Vicinae command.
|
||||||
|
5. Allow-listed repairs, confirmations, post-repair verification, and live audit.
|
||||||
|
|
||||||
|
The slices are one feature and land together. Their order keeps the UI backed by
|
||||||
|
real diagnostics from its first production render.
|
||||||
Reference in New Issue
Block a user