sasa/wireguard-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve application help

Browse Source
This commit is contained in:
sasa
2026-10-29 00:01:35 +02:00
parent 4960c65f65
commit 23d6180f24
6 changed files with 1126 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLANS.md
+73 -2
View File
@@ -126,7 +126,7 @@ Each row is a delivery milestone, not a completion claim. Expand its record befo
| 14 | Restart verification for valid legacy peers | 13 | accepted |
| 15 | Diagnosable systemd restart and unloaded-unit resolution | 14 | accepted |
| 16 | Root systemd private peer restart transport | 15 | accepted |
| 17 | Adaptive client list, persistent details and clear states | 16 accepted; existing M7/M12 TUI | accepted |
| 17 | Adaptive client list, persistent details and clear states | 16 accepted; existing M7/M12 TUI | accepted || 18 | Readable, complete in-app help for implemented workflows | 17 | accepted |
### Milestone 1 — Rust foundation, settings, and domain states
@@ -3796,8 +3796,79 @@ The user's requested subset is adaptive columns, persistent details and clear st
Accepted for the presentation and synthetic fixture scope after independent review, R1/R2 closure and pinned Rust gates. No real WireGuard/systemd, Alpine, disposable-VM or manual terminal-emulator behavior is claimed. Stop after M17; do not commit, deploy, resume retired M9 VM work or access production.
### Milestone 18 — Readable, complete in-app help for implemented workflows
Status: accepted (2026-10-29T00:00:18+02:00) after independent review, R1/R2 repair and re-review, and pinned Rust gates on final inputs. Evidence: [M18](docs/evidence/milestone-18.md).
Prerequisites: M17 accepted; existing TUI and pinned Rust environment. The user previously confirmed this coordinator session is GPT-6-Sol/medium; project configuration and role definitions specify GPT-6-Luna/high for implementer, reviewer and repairer. M9 remains retired by user direction.
#### Outcome and scope
Replace the `?` screen's dense prose with a readable English guide to the application, its implemented functions, and exact keyboard workflows. The guide must describe actual shipped behavior, including M17 adaptive list/details and existing footer, rather than planned features. Follow [SPEC](docs/SPEC.md), [CONTEXT](CONTEXT.md), all three [ADRs](docs/adr/), and development/testing/execution-record rules. Do not change product requirements or claim real-system validation from fixture evidence.
Scope: help content, styling, responsive layout, help navigation, focused tests, and synchronization of relevant user-facing documentation. Preserve actions, authorization, drafts, saved/applied semantics, forms, QR privacy and the stable footer. No new management commands, dependencies, runtime transport work, search/sorting, localization system or application log/history feature. CLI `--help` is not the target of this milestone.
#### Context and implementation steps
At the start of M18, `src/tui/render.rs::render_help` rendered a single literal containing long paragraphs and an inline shortcut list. The draw branch called it without UiState; `src/tui/terminal.rs` changed `scroll_offset` for Help but the renderer did not consume it, and page keys moved one line. Help footer hints omitted scrolling. The implementation corrected these behaviors after tracing current terminal/form handlers and guards.
Read before dispatch: AGENTS.md, docs/SPEC.md, CONTEXT.md, docs/adr/0001-explicit-restart.md, docs/adr/0002-client-secret-storage.md, docs/adr/0003-server-config-authority.md, docs/IMPLEMENTATION.md, docs/EXECUTION_RECORDS.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/ENVIRONMENT.md, docs/DEPENDENCIES.md, docs/PROJECT_LAYOUT.md and docs/CODEX.md. Coordinator owns plan and acceptance. Use one implementation writer, configured GPT-6-Luna/high implementer, a separate reviewer, and repairer for actionable findings; verify actual model prerequisites without silent substitution.
| Task | Owner | State | Owned scope and deliverable |
| --- | --- | --- | --- |
| M18.1 | implementer | complete | Read-only handler/form/guard audit; shortcut inventory in [evidence](docs/evidence/milestone-18.md) |
| M18.2 | implementer | complete | `src/tui/render.rs`: nine structured sections, styled/wrapped visual rows, row-range title, Help footer and shared navigation metrics |
| M18.3 | implementer | complete | `src/tui/terminal.rs`, tests and README: bounded visual-row/page scrolling, resize, reset/Esc; synthetic PTY Help flow |
| M18.4 | independent reviewer; repairer | complete | M18-R1 and R2 repaired by separate repairer and independently re-reviewed closed |
| M18.5 | coordinator | complete | Integrated gates passed on R2 repair; final source/binary identities and limits in [M18 evidence](docs/evidence/milestone-18.md); accepted |
1. Inventory actual global, screen-specific and form-specific shortcuts and their availability conditions. Cover `?`, arrows, Enter, Esc, q/handled Ctrl-C; n/r/d; p/c/x/R; o/O; b/B; s/i/!. Verify exact setup/import/delivery/confirmation behavior in forms instead of guessing field navigation. Explicitly distinguish lowercase/uppercase pairs. A help entry documents existing availability; it must not enable an action where it was previously unavailable.
2. Organize content with a short application introduction and these clearly separated sections: quick start; list and selected-client details; Draft/Saved/Applied states and statistics; client creation/rename/deletion; preview/Commit/discard/explicit restart; first delivery/password reissue/file and optional QR; backup/previewed restore; vault setup/import/anomalies; navigation, cancellation and exit. Each action gets a visible key, short purpose, prerequisites where applicable, and expected result. Include concise walkthroughs: create -> preview -> Commit -> first delivery -> explicit restart (delivery warns until verification), change/delete -> Commit -> restart, reissue with password, and backup selection -> restore preview -> confirmation -> separate restart when desired.
3. Explain that aliases may repeat and public keys identify clients; inspection-only restrictions differ from malformed configuration. Explain unknown/unavailable/verified state without implying that Saved or a handshake means verified access. Handshakes and RX/TX are current read-only observations, not online status or historical totals. Commit and restore save files only; mandatory backups stop protected actions on failure; deleted addresses remain reserved until verified restart. Explain per-client password reissue, first-delivery retry within its creation session, original imported-file preservation, masked password entry and Esc clearing explicit QR disclosure. Use concise practical language, not internal Rust enums, architecture details or promises about unsupported features.
4. Render section headings, whitespace, aligned key/action entries and wrapped explanatory text with theme-safe styles. Colors supplement structure. Prefer a single ordered vertical document, avoiding dense multi-column prose on wide screens. Use display-cell widths and the actual inner viewport; long explanations must wrap without key labels colliding. Keep essential help navigation visible in the existing fixed-height footer, with a position/continuation indicator when content exceeds the viewport. Do not expand the footer or move the list layout based on help length.
5. Wire Help to its scroll position. Calculate wrapped visual rows consistently for rendering, maximum offset and page movement; clamp at both ends, prevent scrolling to a blank page, and clamp after resize. Up/Down move one visual row, PageUp/PageDown move a viewport page with useful overlap if chosen and documented. Opening `?` starts at the top; Esc returns to the client list preserving the selected client and drafts. Reset/clamp help position without leaking it into other screens. Avoid unsolicited changes to non-Help scrolling or action dispatch. Every section must remain reachable on supported small terminals; retain the existing terminal-too-small guard.
#### Acceptance and validation
- [x] M18-A1: content accurately describes the implemented application and all listed shortcut families; inventory maps entries to current handlers/guards. R2 completed required state/password/delivery explanations and independent re-review closed it.
- [x] M18-A2: introduction, section headings, key/action entries, workflow steps and warnings are visually distinguishable in wide and narrow synthetic buffers; key case is unambiguous and text is neither overlapped nor silently inaccessible.
- [x] M18-A3: scrolling visibly changes the rendered Help, reaches the last section, stops at valid bounds, pages by viewport rather than one line, and remains valid after shrinking/growing the terminal. Footer accurately advertises available Help navigation.
- [x] M18-A4: `?` resets Help to its beginning and Esc restores the list with the same selected identity and unchanged draft/saved/applied state. Opening, reading and closing Help performs no file, vault, service or runtime mutation. Existing action/form/QR behavior and fixed two-row footer remain intact.
- [x] M18-A5: cover 34x8, 40x9, 60x16, 80x24, 100x30 and 180x50 with synthetic buffers, plus focused navigation/workflow checks. Verify all help sections can be reached; prefer semantic/geometry assertions over brittle full-document snapshots. Fixtures contain no production keys, payloads or QR matrices.
- [x] M18-A6: independent content/implementation review closed R1/R2; focused tests and required integrated Rust gates passed on final inputs, with evidence and user documentation updated.
Validation: pinned Rust/Cargo 1.97.1, rustfmt 1.9.0 and Clippy 0.1.97; `cargo fmt --all -- --check`, `cargo clippy --locked --all-targets -- -D warnings`, `cargo test --locked`, `cargo build --locked --release` and `git diff --check` all exited 0 on final inputs. Focused `cargo test --locked tui::` passed 79; `cargo test --locked --test tui_workflow` passed 8. Full suite passed 392 with 3 explicitly ignored. Exact source/artifact identities and synthetic/PTY limits are in [M18 evidence](docs/evidence/milestone-18.md). No Docker, root, VM or production checks were run for this presentation milestone.
#### Progress
- [x] M18.1: current shortcut/form/guard audit completed without edits; content inventory recorded in [evidence](docs/evidence/milestone-18.md).
- [x] M18.2: structured Help rendering and focused buffer tests completed in `src/tui/render.rs`; coordinator inspected changed-file scope and the navigation-metrics interface.
- [x] M18.3: visual-row/page scrolling, bounds, resize, `?` reset, Esc preservation and synthetic PTY Help flow completed; coordinator inspected terminal/README/workflow diff.
- [x] M18.4: independent review found R1 in the narrow footer; coordinator audit and reviewer confirmed R2 content gaps. A separate repairer fixed both, and independent re-review closed both with focused regressions.
- [x] M18.5: final integrated pinned Rust gates and release build passed; refreshed source/binary identity and limitations are in [M18 evidence](docs/evidence/milestone-18.md). Milestone accepted.
#### Review and repair
| Finding | Iteration | Location and impact | Owner | Resolution and evidence | State |
| --- | --- | --- | --- | --- | --- |
| M18-R1 (P2) | R1 | `src/tui/render.rs`: 34×8 compact Help footer omitted Esc return key | repairer | Help-specific narrow packing keeps scroll/Esc and honest overflow; 34×8/40×9 regression passed; independent re-review closed | closed |
| M18-R2 (P2) | coordinator audit | `src/tui/render.rs::help_document`: required password, observation and delivery-warning explanations were incomplete | reviewer; repairer | Four claims and 34×8 reachability test added; focused test passed and independent re-review closed | closed |
#### Evidence and handoff
Final [M18 evidence](docs/evidence/milestone-18.md) records shortcut audit, fingerprinted source/release binary, 79 focused TUI tests, 8 workflow tests, 392 full-suite passes with 3 ignored, all pinned Rust gates and independent R1/R2 closure. Synthetic PTY coverage is distinct from manual terminal-emulator or real-system acceptance.
#### Decisions and discoveries
A more detailed guide requires functional scrolling as well as rewritten text. Keep application UI/help in English, as required by AGENTS.md. Reuse current public presentation facts and existing widgets rather than introducing a documentation framework. Describe actual action guards and cancellation semantics; help is guidance, not a second implementation of authorization rules.
#### Outcome
Accepted for presentation and synthetic fixture scope after independent review, R1/R2 closure and pinned Rust gates. No manual terminal-emulator, Alpine, disposable-VM, live WireGuard or production result is claimed. Stop after M18; do not commit, publish, deploy, access production or resume VM work.
## Current progress and resume point
- M18 is accepted (2026-10-29): structured, accurate in-app Help, responsive wrapping and bounded scrolling passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M18 evidence](docs/evidence/milestone-18.md) records final inputs and limits. Stop here; no next milestone is started.
- M17 is accepted (2026-10-28): adaptive columns, persistent selected-client details and explicit state/count presentation passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M17 evidence](docs/evidence/milestone-17.md) records final inputs and limits. Stop here; no next milestone is started.
- TUI-FL-001 is complete (2026-10-27): fixed-height two-row keyboard footer, narrow Help/overflow behavior and compact nine-row handling passed synthetic rendering tests, independent R1–R3 closure and pinned Rust gates. [Footer evidence](docs/evidence/tui-footer-layout.md) identifies source/artifact inputs.
@@ -3823,7 +3894,7 @@ Accepted for the presentation and synthetic fixture scope after independent revi
- Milestone 8 delivered reviewed opt-in Alpine Testcontainers coverage for real IPv4 WireGuard peers, application lifecycle, saved/runtime separation, restoration, import/reissue, backup failures and the real Rustix reader. Host gates and three fresh real-container runs passed on one stable source fingerprint; M8-A1–A10 accepted. Real IPv6 behavior is unverified by user-authorized scope.
- Milestone 9 is retired and unaccepted: the reviewed disposable VM preparation and guarded first start did not establish Debian/systemd acceptance. The exact VM was powered off after the user stopped work. M9.2–M9.3 were not started; M9-A1–A9 are unchecked.
- Next action: none for M17. Stop after acceptance. Keep the undocumented M16 manual check and absent disposable-VM evidence separate from M17 fixture evidence. Do not access production, commit, or deploy.
- Next action: none for M18. Stop after acceptance. Keep M16 validation limitations separate from TUI evidence. Do not access production, commit, deploy or resume VM work.
## Plan maintenance