docs(M8.1): hand off the first live TUI slice

Close the typed CLI acceptance boundary, record remaining IPC and mixer gaps without overclaiming them, and provide the Arch/PipeWire checklist for live stream navigation, control, external updates, churn, restart, and restoration.

Tests: full locked workspace format, check, test, doctest, Clippy, release, no-default-features, and Rust 1.88 all-feature gates passed.

Tests: invalid serve profile exits before creating its runtime socket.
This commit is contained in:
Dandaedre 2026-10-15 00:18:59 +02:00
parent 472625301e
commit 6ae361c595
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 127 additions and 11 deletions

View File

@ -6,11 +6,12 @@
Linux application volume and mute control from one or more USB MIDI surfaces.
This repository currently contains tested domain and configuration libraries plus
an interactive TUI shell. The domain layer supports matching, routing, balanced
group volume plans, and mute intent. Atomic TOML persistence and checkpointing are
implemented; the server, audio adapters, persistent bindings, and configuration
editor remain planned in the following documents:
This repository contains tested domain and configuration libraries, a PulseAudio
protocol worker compatible with `pipewire-pulse`, a local per-user server, and a
live terminal mixer. The domain layer supports matching, routing, balanced group
volume plans, and mute intent. Atomic TOML persistence and checkpointing are
implemented; profile aggregation, persistent MIDI lifecycle, and the
configuration editor remain on the ordered backlog:
- [Architecture and library research](architecture.md)
- [Implementation tasks and acceptance tests](task.md)
@ -19,15 +20,25 @@ editor remain planned in the following documents:
- [CI coverage and badge lifecycle](docs/ci-coverage.md)
- [Hands-on functional checklist](checklist.md)
## Run the TUI
## Run the live TUI
Start the server in one terminal:
```sh
cargo run --locked -p fader_master
cargo run --locked -p fader_master -- serve \
--config examples/profiles/desktop.toml --audio pulse
```
Use the arrow keys to move the demo fader, Home/End for its endpoints, and Q or
Escape to quit. The screen currently uses local demo state; live server and audio
integration follow in M3–M8.
Then start the client in another:
```sh
cargo run --locked -p fader_master -- tui
```
Use Up/Down or J/K to select a live playback stream, Left/Right to change its
volume, M to toggle mute, and Q or Escape to quit. See the hands-on checklist for
the exact milestone scope and restoration steps. The current view lists raw
application streams; configured application/group aggregation follows in M8.1.
# References

View File

@ -210,3 +210,57 @@ reconnection yet.
Report the controller model/firmware plus the complete `PortIdentity` lines.
Do not redact USB serials unless you prefer not to store them in the project
test record; a redacted but clearly stable/absent result is sufficient.
# First live TUI milestone checklist (Arch Linux + PipeWire)
This is the first TUI that needs hands-on testing. It controls real application
streams through the persistent local server and `pipewire-pulse`. For this
slice, rows are raw playback streams; configured application aggregation,
groups, pickup, MIDI status, and the editor remain later M8/M9 work.
## Start the server
- [ ] Start playback in at least two applications whose volume can safely be
changed, and record their original volume/mute states.
- [ ] In terminal 1, run:
```sh
cargo run --locked -p fader_master -- serve \
--config examples/profiles/desktop.toml --audio pulse
```
- [ ] Confirm it prints `serving profile=desktop backend=pulse` and remains
running without changing any application volume at startup.
- [ ] Attempt the same command in another terminal and confirm it refuses to
start a second server.
- [ ] Run `cargo run --locked -p fader_master -- status` and confirm it reports
`status=ready` plus the currently playing streams with sensible labels,
gains, mute state, and `writable=true`.
## Exercise the live mixer
- [ ] In terminal 2, run `cargo run --locked -p fader_master -- tui`.
- [ ] Confirm the header shows `pulse · ready`, and each playing application
appears as a separate row with its current volume and mute state.
- [ ] Resize the terminal smaller and larger. Confirm borders remain intact and
the selected row remains visible without a panic.
- [ ] Use `↑`/`↓` or `k`/`j` to select different application streams.
- [ ] On a disposable stream, use `←`/`→` to change volume. Confirm only that
selected application changes, channel balance is preserved, and the displayed
value converges to the desktop mixer's readback.
- [ ] Press `m` twice. Confirm the selected application mutes and unmutes without
changing its volume.
- [ ] Change volume and mute externally in the desktop mixer. Confirm the TUI
refreshes to the external values without emitting a compensating write.
- [ ] Stop and restart one playback application. Confirm its row disappears and
a fresh row appears without crashing or reusing stale state.
- [ ] Press `q` or `Esc`. Confirm the terminal is restored and terminal 1 keeps
serving; `cargo run --locked -p fader_master -- status` must still work.
## Finish and report
- [ ] Stop terminal 1 with `Ctrl-C`, then start it once more. Confirm the stale
socket is recovered automatically and the new server reaches `ready`.
- [ ] Restore the applications' original volume and mute states.
- [ ] Report any missing/mislabeled stream, wrong application being controlled,
visible error, layout corruption, or command that fails to converge.

View File

@ -0,0 +1,25 @@
use std::{fs, process::Command};
#[test]
fn invalid_serve_profile_fails_before_socket_or_audio_side_effects() {
let directory = tempfile::tempdir().unwrap();
let config = directory.path().join("invalid.toml");
let socket = directory.path().join("runtime/control.sock");
fs::write(&config, "schema_version = 999\nid = 'broken'\n").unwrap();
let output = Command::new(env!("CARGO_BIN_EXE_fader_master"))
.args([
"serve",
"--config",
config.to_str().unwrap(),
"--socket",
socket.to_str().unwrap(),
])
.output()
.unwrap();
assert!(!output.status.success());
assert!(!socket.exists());
assert!(!socket.parent().unwrap().exists());
assert!(String::from_utf8_lossy(&output.stderr).contains("profile"));
}

28
task.md
View File

@ -189,18 +189,44 @@ Dependencies: M4, M5.
Dependencies: M3, M2; may proceed after the fake-adapter slice.
- [ ] **M7.1 CLI:** serve/tui/validate/devices/status/profile switch arguments and override precedence. Tests: help/errors, invalid config has no side effects, explicit override wins for the session without silently modifying disk.
- [x] **M7.1 CLI:** serve/tui/validate/devices/status/profile switch arguments and override precedence. Tests: help/errors, invalid config has no side effects, explicit override wins for the session without silently modifying disk.
Typed subcommands now validate profiles before probing audio or creating the
runtime socket. `serve`, `tui`, `validate`, `devices`, and `status` are active;
`profile switch` parsing is reserved for the transactional M10 implementation.
A session audio override is applied only to runtime selection.
- [ ] **M7.2 IPC:** owned Unix socket, one-instance lock, version negotiation, length-bounded TOML frames, request IDs and revisioned state. Tests: wrong peer permissions, oversized/truncated/incompatible messages, second server, stale socket recovery and slow/disconnected client.
The first local slice uses an owned mode-0600 socket, bounded request timeouts,
versioned/request-correlated 64-KiB TOML frames, revisioned snapshots,
one-instance detection, and safe stale-socket replacement. Keep this item open
pending explicit peer-credential and slow-client concurrency coverage.
- [ ] **M7.3 Client resync:** full snapshot on attach/lag and revision checks for edits. Tests: TUI exit never stops the server; reconnect shows current observations; concurrent clients cannot overwrite each other's edits unnoticed.
Each short-lived client request receives a complete current snapshot; stale
edit revisions return a resync error. The live TUI reconnects on every refresh
and exits independently of the server. Keep this item open until concurrent
client and lag stress tests pass.
## M8 — Live TUI
Dependencies: M7, M4 for real use.
- [ ] **M8.1 Mixer:** replace blocking prototype with event-driven client views and volume/mute actions. Test-backend assertions: groups/applications, mixed/offline/pending/error indicators, pickup state, resize and keyboard navigation reflect snapshots accurately.
The first testable live slice lists real Pulse application streams, refreshes
without blocking server operation, and sends selected volume/mute actions with
pending, read-only, and error indicators. Keep this item open until profile
applications/groups, mixed/offline aggregates, and pickup state replace the
raw-stream view.
- [ ] **M8.2 Devices/status:** show adapter selection/probe errors, device mappings, ambiguity and persistence problems. Tests: disconnected/unsupported states have useful actions; manual backend selection validates rather than silently applying incompatible mappings.
- [ ] **M8.3 Terminal lifecycle:** restoration on normal/error exit, nonblocking refresh, logging away from display. Tests: injected IO/client failure releases terminal guard; polling/refresh does not block server operation.
First live TUI slice verification on 2026-10-15: a real server selected Pulse
against PipeWire, reached `ready`, and published the active Qobuz playback stream
through the private socket. A PTY-rendered client displayed its confirmed 9%
gain and restored the terminal on quit without stopping the server. Locked
workspace formatting, all-target/all-feature checks and tests, doctests, strict
Clippy, release build, no-default-feature checks/tests, and the complete Rust
1.88 all-feature test suite pass. M7.2, M7.3, and M8.1 remain open for the
explicit acceptance gaps noted above and in the hands-on checklist.
## M9 — TUI configuration editor
Dependencies: M8, M2, M1.