enricobuehler
6776bff82d
Implements design/web-console-diagnostics.md, WP1-WP3 (the v1). WP4 (live checks + SSE) and WP5 (instant helpers) stay deferred, as that plan sequences them. The `.181` incident is the type specimen. `preflight_takeover_privilege()` is the most careful probe in the repo — four applicability gates, and it even separates user-database membership from the running process's supplementary groups — and it spends all of that care on ONE WARN log line. A console-driven update never shows scriptlet stderr, so the operator's only symptom was a black screen on every connect. The class of bug is "the host knows, and the person operating it has no way to find out". Host ---- `diagnostics.rs` holds the `HostCheck` model and a process-global registry (probes in, cached verdicts out; `POST /refresh` re-runs them). `inapplicable` is a first-class status rather than an absent row, so the page can answer "why isn't this check relevant here?" instead of silently hiding it. `diagnostics/catalog.rs` maps verdicts to wire checks and owns every user-visible string. `GET /api/v1/diagnostics` + `POST /api/v1/diagnostics/refresh` are **admin lane only**. Neither allowlist in `auth.rs` is touched: both are opt-in, and these verdicts carry the host user's name, its group layout and device-node state. The route-classification test gets both rows so that stays a reviewed decision rather than a default. Probes stay in their owning crates and export plain verdict enums; the host does the mapping. No reverse dependency — `pf-inject`/`pf-vdisplay` never learn about host types. * `pf-vdisplay`: `preflight_takeover_privilege()` now logs FROM `takeover_privilege_verdict()`. The WARN line is unchanged, deliberately: headless operators read logs, not consoles, and this moves where the verdict GOES, not what it says. * `pf-inject`: `uinput_probe()` keeps the errno that `pen_supported()` throws away, so "you are not in the input group" (EACCES) and "the module was never installed" (ENOENT) stop looking identical — they need opposite remedies. `vhci_probe()` reports device facts only (module present, node writable by this process); who to blame is the host's question, because only the user database can answer it. Two distinctions the catalog refuses to collapse: 1. **User-database membership vs this process's groups.** `usermod -aG` satisfies the first immediately and the second not until the next login. Collapsing them produces the single most maddening support state there is — "I already added myself!" — which nothing in the logs distinguishes today. It now gets its own remedy: log out, no command to run. 2. **`usermod` does not stick on an atomic OS.** On the Universal Blue images the remedy is `ujust add-user-to-input-group`. Matched on the OS chain's LEAF, never on the `fedora` family token: plain Fedora Workstation is mutable and does want `usermod`. Console ------- The dashboard gets an `AttentionCard` that renders nothing at all on a healthy host (`ConflictsCard`'s rule), shows at most the 3 worst checks, and links onward rather than explaining — a dashboard that starts teaching remedies stops being a dashboard. Its badge says the **severity**, not the status. The badge's colour already encodes severity, so a badge reading "Failing" on both a red and an amber row leaves the difference between them carried by colour alone — which is the thing the `pin_pending` precedent exists to prevent. Caught on glass, not in the diff. The Logs page becomes Troubleshooting: checks above the log stream, because when the checks are green and something is still broken the log is the natural next step. The ROUTE stays `/logs` — bookmarks and deep links outlive a label. `LogsCard` grows a heading, since the page title no longer names it. A check id this console has never heard of still renders, from the host's English `summary`/`impact`/`remedy.text`. That is what makes console N paired with host N+1 survivable, and it is enforced as a test rather than left as a convention. The situational prose is deliberately NOT duplicated into the message catalogues: one check has many shapes (the vhci one alone has four distinct causes), and copying ~20 sentences into a package that versions independently of the one that generates them is the very drift this design set out to avoid. The console localizes the check NAMES and all chrome; when the host sends a shape discriminator alongside `id`, localized prose can key off it. Verification ------------ `cargo clippy -D warnings` and `cargo fmt --all --check` clean on Linux; 12 diagnostics unit tests and 48 mgmt handler tests green, including the openapi drift test — `api/openapi.json` and the ungated `docs-site/public/openapi.json` copy are both regenerated. Web: build, lint, `bun test server/`, storybook, and the new stories shot in both themes with the theme flip verified rather than assumed. Not yet on glass: the real `.181` box (all three vhci states), `.138` for the unpackaged-helper path, and the old-console/new-host pairing legs.
punktfunk web — management console
The browser UI for the punktfunk host's management REST API (crates/punktfunk-host/src/mgmt.rs,
OpenAPI at api/openapi.json). It shows live status, host capabilities, paired
clients, the pairing-PIN flow, and session controls.
Stack: TanStack Start (full SSR) on Bun via Nitro v2 (bun preset) · React
Query through orval codegen from the OpenAPI spec · @unom/ui
— the shared punktfunk/unom design system the marketing site + docs are built on (Tailwind v4,
animated components on the violet brand over dark chrome) ·
Paraglide i18n (en/de). Package manager + runtime: Bun.
The @unom registry mapping lives in .npmrc; the auth token comes from
~/.npmrc (or a CI secret).
Develop
# from web/ — Bun is the toolchain (https://bun.sh)
bun install # runs `prepare` → codegen (orval + paraglide)
bun run dev # http://localhost:47992
# The dev server proxies /api → https://127.0.0.1:47990 (the host's mgmt API; it serves HTTPS
# with the host's self-signed identity cert — the dev proxy uses `secure: false`).
# Point it elsewhere: PUNKTFUNK_MGMT_URL=https://<host>:47990 bun run dev
Start a host with the management API up:
# from the repo root — `serve` brings up the native punktfunk/1 plane + the mgmt API (the console
# only needs the mgmt API; add --gamestream too if you also want the Moonlight surface):
WAYLAND_DISPLAY=wayland-kde XDG_CURRENT_DESKTOP=KDE \
cargo run -rp punktfunk-host -- serve
# loopback :47990, no token (a token is mandatory for non-loopback binds).
The management token is server-side only — set PUNKTFUNK_MGMT_TOKEN in the console's
environment and the BFF injects it when proxying (server/routes/api/[...].ts). It never reaches
the browser, so there is no token field in the UI; the browser only ever holds the session cookie.
Build & run (Nitro + Bun)
The console runs on bun (Bun.serve is a Bun API — node can't run it): Nitro's bun preset
plus a custom entry (nitro-entry/bun-https.mjs) that calls Bun.serve({ tls }), so it serves
HTTPS (HTTP/1.1 over TLS) with the host's own identity cert (the cert native clients already
pin). One trust anchor across the data plane, the mgmt API, and this console. (No HTTP/2 — Bun.serve
has no h2 server — and no HTTP/3, which a browser won't speak against this self-signed, no-SAN host
cert; a browser-trusted, SAN-matching cert + a fronting server would be needed, out of scope for a
LAN console.)
bun run build # → .output/ (Nitro `bun` preset + our Bun.serve TLS entry)
PORT=47992 HOST=0.0.0.0 \
PUNKTFUNK_UI_PASSWORD=… PUNKTFUNK_MGMT_TOKEN=… \
PUNKTFUNK_MGMT_URL=https://127.0.0.1:47990 \
PUNKTFUNK_UI_TLS_CERT=~/.config/punktfunk/cert.pem \
PUNKTFUNK_UI_TLS_KEY=~/.config/punktfunk/key.pem PUNKTFUNK_UI_SECURE=1 \
bun run start # = bun run .output/server/index.mjs
# PUNKTFUNK_UI_TLS_* unset ⇒ plain HTTP (local dev); both set ⇒ HTTPS (HTTP/1.1 over TLS).
# The host's self-signed mgmt cert is accepted only for the proxy's loopback hop, scoped in code
# (Bun per-request TLS: server/routes/api/[...].ts) — no process-wide NODE_TLS_REJECT_UNAUTHORIZED.
# See .env.example.
bun run lint # tsc --noEmit
The built Nitro bun server SSR-renders the app and is the only thing exposed on the LAN.
Run it on the same box as the host; it serves the console over HTTPS on :47992 (or $PORT).
Auth (backend-for-frontend)
Single-user, login-gated. Config via env (see .env.example):
- The console requires a login (
PUNKTFUNK_UI_PASSWORD). On success the server sets a sealed session cookie (h3useSession, AES-GCM).server/middleware/auth.tsgates every request — pages redirect to/login,/apireturns 401 — and fails closed (503) ifPUNKTFUNK_UI_PASSWORDis unset, so a misconfigured LAN server admits no one. - The bearer-token admin surface of the management API is loopback-only — the host honors a
bearer token only from a loopback peer, so the admin API is never LAN-exposed. The web server
holds
PUNKTFUNK_MGMT_TOKENserver-side and injects it when proxying/api/**→PUNKTFUNK_MGMT_URL(loopback;server/routes/api/[...].ts). The token never reaches the browser; the browser only ever holds the session cookie. (The host also binds the read-only surface — host status + the game library — to the LAN so paired native clients can fetch it directly over mTLS; that path uses client certs, not the token, and never touches this console.)
So: browser ──password──▶ web server (session cookie) ──mgmt token, server-side──▶ mgmt API.
Run the host with a matching token: cargo run -rp punktfunk-host -- serve +
PUNKTFUNK_MGMT_TOKEN=… (or --mgmt-token …). vite dev has no gate (localhost-only) and
proxies straight to the loopback mgmt API.
Toolchain notes (load-bearing): TanStack Start's
start-plugin-corepeer-requires Vite ≥ 7 — on Vite 6 the build's prerender/post-build hook silently doesn't run.@vitejs/plugin-reactmust match Vite (v5 ↔ Vite 7, v6 ↔ Vite 8); it's required even for dev (TanStack Start's dev mode needs the React Refresh runtime, else a blank screen). Nitro is the server target — without itvite buildonly emits client+SSR bundles, no deployable server. The Nitrobunpreset makes.output/server/index.mjsBun-runnable.
Codegen
Generated code is not committed (gitignored) — reproduced from sources:
bun run codegen— regenerate the API client (orval) + i18n runtime (paraglide). Runs onbun install(prepare) and beforedev/build(pre*for orval; the Vite plugin compiles paraglide on dev/build).- After a management-API change, regenerate the spec on the Rust side first:
cargo run -p punktfunk-host -- openapi > api/openapi.json, thenbun run api:gen.
Layout
src/
routes/ file-based routes (index=dashboard, host, clients, pairing, settings)
components/
app-shell.tsx sidebar nav (brand lens + wordmark) + language switcher
brand-mark/wordmark/logo.tsx punktfunk lens mark + wordmark (shared with the site/docs)
ui/ @unom/ui-backed primitives (button, input, label, card; badge/table/skeleton)
query-state.tsx loading/error wrapper (401 → the session is gone, re-login)
api/
fetcher.ts orval mutator: base URL, bearer token, JSON, throwing ApiError
gen/ GENERATED react-query hooks + models (orval)
lib/i18n.ts reactive Paraglide locale hook
paraglide/ GENERATED i18n runtime (paraglide)
messages/{en,de}.json translation sources