From 6ae361c595a6eb7a0af3bb240b6515bd06dc3a04 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 00:18:59 +0200 Subject: [PATCH] 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. --- README.md | 31 ++++++++++++------ checklist.md | 54 +++++++++++++++++++++++++++++++ fader_master/tests/cli_process.rs | 25 ++++++++++++++ task.md | 28 +++++++++++++++- 4 files changed, 127 insertions(+), 11 deletions(-) create mode 100644 fader_master/tests/cli_process.rs diff --git a/README.md b/README.md index e6c19e8..8a2c0f9 100644 --- a/README.md +++ b/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 diff --git a/checklist.md b/checklist.md index 8dd30e3..82fb668 100644 --- a/checklist.md +++ b/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. diff --git a/fader_master/tests/cli_process.rs b/fader_master/tests/cli_process.rs new file mode 100644 index 0000000..5f70e4f --- /dev/null +++ b/fader_master/tests/cli_process.rs @@ -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")); +} diff --git a/task.md b/task.md index aa383dd..b75d9d0 100644 --- a/task.md +++ b/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.