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:
parent
472625301e
commit
6ae361c595
31
README.md
31
README.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
54
checklist.md
54
checklist.md
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
28
task.md
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue