diff options
| -rw-r--r-- | docs/design/2026-06-29-waybar-network-module-spec.org | 20 | ||||
| -rw-r--r-- | todo.org | 55 |
2 files changed, 54 insertions, 21 deletions
diff --git a/docs/design/2026-06-29-waybar-network-module-spec.org b/docs/design/2026-06-29-waybar-network-module-spec.org index 37b87b0..db9657d 100644 --- a/docs/design/2026-06-29-waybar-network-module-spec.org +++ b/docs/design/2026-06-29-waybar-network-module-spec.org @@ -4,6 +4,16 @@ * Status +*Phase 1 SHIPPED* (2026-06-29, dotfiles =5254bd8=..=c095a22=, 10 commits): engine +(=net status/probe/diagnose/repair/doctor/portal=) + =waybar-net= indicator + +split-cadence cache + redacted event log + Makefile recovery targets + airplane +absorption. 160 net tests; pure modules ≥90% branch. One as-built deviation from +this spec: airplane absorption is *display-only* (Craig's call, option 1) — net +shows the airplane state but the =airplane-mode= low-power toggle is KEPT (it does +radios + CPU + brightness + services, not a network concern); only =waybar-airplane= ++ =custom/airplane= + =waybar-netspeed= were deleted. See decision 12. Phases 2-5 +remain. Live waybar eyeball is under todo.org "Manual testing and validation". + Ready for Phase 1; Ready-with-caveats overall. Three Codex review rounds + Craig's cj comments are all incorporated — every finding has a disposition and the findings cookie reads complete ([31/31]), with no open decisions (enterprise scope settled: @@ -859,8 +869,14 @@ a *coverage-gap pass*, not just a percentage: "defer the doctor/bundle command" decision is reversed.) 11. Diagnose (read-only) and Repair (mutating, confirmed) are separated in the panel and the CLI; Repair is tiered lightest-first (rfkill → reset → bounce). -12. =custom/net= absorbs the airplane module (Craig's call, cj); the standalone - airplane module + scripts + tests are deleted once net ships. +12. =custom/net= absorbs the airplane module (Craig's call, cj). *As built + (2026-06-29, option 1): display-only.* net shows the airplane state (reads + the airplane-mode state file); the =airplane-mode= low-power toggle is kept + (radios + CPU + brightness + services is not a network concern) and moved to + =custom/net='s right-click + signal 15. Only the redundant display pieces — + =waybar-airplane=, =custom/airplane=, and the retired =waybar-netspeed= — + plus their tests/css were deleted. The earlier "delete airplane-mode" framing + is superseded. 13. Repair includes a full-stack bounce and an rfkill-unblock (Craig's calls, cj) — the latter recovers the framework-laptop post-power-loss soft-block. 14. VPN / WireGuard is a planned Phase 5 (Craig's call, cj), not a permanent @@ -97,19 +97,36 @@ Phases below, dependency order. Engine/unit work is agent-verifiable (=unittest= + fakes on PATH, coverage via venv); the live-network and visual states need real conditions, filed under "Manual testing and validation". -*** TODO Phase 1 — indicator + console recovery :network: -Deliverable: =net status= + =net probe= (native cheap captive probe) + the -=captive= =--json= probe refactor; =waybar-net= replacing =custom/netspeed=; -split-cadence cache (single-flight flock, atomic write, fresh/stale/expired/unknown -classes, iface/SSID/UUID invalidation); CSS states (captive/no-internet/degraded/ -rfkill); =net repair= tiers (rfkill/reset/bounce); =net doctor [--fix]= with the -four terminal classifications; Makefile console-recovery targets (=make online= -etc.); absorb the airplane state and delete the standalone airplane module -(=waybar-airplane=, =airplane-mode=, their tests, =custom/airplane= + css). -Tests: =tests/net/= + =tests/waybar-net/= unittest with fake nmcli/curl/rfkill/ -resolvectl on a temp PATH; doctor-classification fixtures; degraded-under-slow-nmcli -benchmark; branch coverage ≥90% on pure modules via a throwaway venv; coverage-gap -pass. +*** 2026-06-29 Mon @ 20:19:11 -0400 Phase 1 shipped — indicator + console recovery +Shipped to the dotfiles repo (10 commits, =5254bd8=..=c095a22=, pushed to main). +The =net= engine is a src-layout Python package in-tree, imported by a bin shim +that resolves the stow symlink back to the repo — so it runs from a bare TTY with +no install, which the recovery path depends on. + +Landed: =net status= (fast path, one nmcli call + sysfs, degraded fallback in +budget) + =net probe= (native captive probe, single-flight flock, atomic cache, +fresh/stale/expired/unknown classes, iface/SSID/UUID invalidation); =waybar-net= +replacing =custom/netspeed=, throughput → tooltip, CSS states in both themes + +live; =net diagnose= (read-only steps) + =net repair= (rfkill/reset/bounce/ +dns-test, cleanup-verified) + =net doctor [--fix]= with the four terminal +classifications; =net portal= + the =captive --probe-json= refactor; redacted +JSONL event log; Makefile recovery targets (=make online= etc.); =~/.config/net/ +config=. Verified live: =make net-status= reads the real wlp170s0 / @Hyatt_WiFi. + +Airplane (Craig's call, option 1): =custom/net= absorbs only the *display* — net +reads the airplane-mode state file and shows an airplane state/glyph. The +airplane-mode toggle stays (it's a low-power mode — radios + CPU + brightness + +services — not a radio switch), now on =custom/net='s right-click + signal 15. +Deleted: =waybar-airplane=, =waybar-netspeed=, =custom/airplane=, their tests + +css. =airplane-mode= kept. + +Tests: 160 in =tests/net/= (fake nmcli/curl/rfkill/resolvectl/ping/getent/ +systemctl on a temp PATH; doctor-classification fixtures; degraded-under-slow- +nmcli benchmark) + the =captive= probe-mode tests; full dotfiles suite green (32 +suites). Coverage-gap pass via throwaway venv: pure modules ≥90% branch +(classify 100%), IO-error branches excused in the test docstring. +Deferred to Phase 2/3: archsetup deps (gtk4-layer-shell/python-gobject Phase 2, +speedtest-go-bin Phase 3 — not added before the code that needs them). Verify (manual, live): see Manual testing and validation. *** TODO Phase 2 — panel shell + connection management :network: @@ -788,12 +805,12 @@ rfkill list wifi # confirm Soft blocked: yes make -C ~/.dotfiles online # or: net doctor --fix #+end_src - Expected: doctor reports the rfkill block, runs =rfkill unblock wifi= + =nmcli radio wifi on=, reconnects, and ends "online" — all from the TTY. -*** Network module Phase 1 — airplane state absorbed, old module gone -What we're verifying: the airplane toggle/state moved into =custom/net= and the standalone module is removed cleanly. -- Toggle airplane mode (the keybind / the net module's control). -- Expected: =custom/net= reflects the airplane state; wifi drops and restores. -- Check the bar has no separate =custom/airplane= module, and =waybar-airplane= / =airplane-mode= are gone from =~/.local/bin=. -- Expected: no duplicate airplane indicator; no stale scripts. +*** Network module Phase 1 — airplane state absorbed, display-only (option 1) +What we're verifying: =custom/net= shows the airplane state, the toggle stays the airplane-mode low-power script (now on the net module's right-click), and only the redundant *display* pieces were removed. Craig's call: net absorbs the display, not the low-power orchestration. +- Right-click =custom/net= (it now runs =airplane-mode=). +- Expected: airplane engages — wifi drops, brightness dims, CPU/services to low-power — and =custom/net= shows the airplane glyph in gold. Right-click again restores everything. +- Check the bar has no separate =custom/airplane= module, and =waybar-airplane= / =waybar-netspeed= are gone from =~/.local/bin= (dangling symlinks removed). +- Expected: no duplicate airplane indicator; =airplane-mode= itself is still present (=ls ~/.local/bin/airplane-mode= → exists), since the low-power toggle is not a network concern. ** DOING [#B] Prepare for GitHub open-source release :PROPERTIES: |