Design a comprehensive clap-derive CLI (architecture/cli.md)
Stage 1 of the CLI dev-flow: every binary becomes a clap-derive CLI with --help; no subcommand keeps the current default (TUI / run server / both). A shared cbd-cli crate holds the clap definitions and a feature-gated gRPC executor for the remote library/queue/global commands; server guard/scan and client auth live in their binaries; completions + man pages generate in each build.rs. Includes a d2 component diagram. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Test User
parent
99419dcdcf
commit
56098f7c26
|
|
@ -0,0 +1,238 @@
|
|||
# A comprehensive CLI for every binary
|
||||
|
||||
## Context and problem statement
|
||||
|
||||
Today the command line is thin and inconsistent:
|
||||
|
||||
- `crabidy-server` uses clap-derive but exposes only `hash-password` and no
|
||||
flags (it always binds the fixed `LISTEN_ADDR`).
|
||||
- `cbd-tui` and `cbd` share a ClapSerde `Config` (`-a/-u/-p`, `--spectrum`)
|
||||
that doubles as the TOML schema; neither has subcommands.
|
||||
- Every user operation is reachable *only* through the interactive TUI. There
|
||||
is no way to script the player, set up auth, or index a music folder from the
|
||||
shell.
|
||||
|
||||
The goal: **every binary is a clap-derive CLI with `--help`; every operation
|
||||
the TUI can do is also a subcommand; there are shell completions and man pages;
|
||||
and running a binary with no subcommand behaves exactly as today** (TUI, run the
|
||||
server, or `cbd`'s server+TUI).
|
||||
|
||||
New capabilities requested:
|
||||
|
||||
- **`guard`** (server): hash a role password and, by default, write it into
|
||||
`crabidy-server.toml`'s `[auth]`.
|
||||
- **`scan`** (server): walk a path, drop a `.cbd-track.toml` beside every
|
||||
playable file; `--capture` copies the audio into the content store (toml
|
||||
points there), `--move` moves it instead of copying.
|
||||
- **`auth`** (client): write a role + cleartext password into the client config.
|
||||
- **`library` / `queue` / `global`** (server *and* client): the full set of
|
||||
library, queue, and playback operations, run against a server over gRPC.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The `library`/`queue`/`global` commands are **remote**: they connect to a
|
||||
running server at `--address` (default localhost) with the same basic-auth as
|
||||
the TUI, reusing the generated gRPC client. A "server" binary running them is
|
||||
just acting as a client to whatever server is up — including its own.
|
||||
- One config file per client binary stays the source of truth for connection
|
||||
defaults (`cbd-tui.toml`, `cbd.toml`); flags override it.
|
||||
- Passwords may be given as an argument *or* on stdin. Argv is visible in the
|
||||
process list — the help text says so, and omitting the argument reads stdin
|
||||
(pipe-friendly, the current `hash-password` behavior).
|
||||
- No tag extraction in `scan` v1 (title = file stem); no machine-readable
|
||||
output format v1 (human-readable text). Both are noted as future work.
|
||||
|
||||
## D1 — A shared `cbd-cli` crate
|
||||
|
||||
A new library crate **`cbd-cli`** holds the clap definitions so all three
|
||||
binaries share one command surface and each binary's `build.rs` can generate
|
||||
assets from it. It is feature-split to keep `build.rs` light:
|
||||
|
||||
- **default features (clap only)**: the `Parser`/`Subcommand` types
|
||||
(`LibraryCmd`, `QueueCmd`, `GlobalCmd`, `GuardCmd`, `ScanArgs`, `AuthCmd`, the
|
||||
per-binary top-level `ServerCli`/`TuiCli`/`CbdCli`), a `Role` enum, a
|
||||
`RemoteArgs` flatten (`--address/--user/--password`), and
|
||||
`generate_assets(cmd, out_dir)` (wrapping `clap_complete` + `clap_mangen`).
|
||||
Depends only on `clap`, `clap_complete`, `clap_mangen`.
|
||||
- **feature `client`**: `run_remote(remote: &RemoteArgs, cmd: RemoteCmd)` — the
|
||||
executor that connects a `crabidy_core` gRPC client (with a standalone
|
||||
basic-auth interceptor) and runs a `library`/`queue`/`global` subcommand,
|
||||
printing results. Adds `tonic`, `crabidy-core`, `tokio`.
|
||||
|
||||
`guard`/`scan`/`auth` *definitions* live in `cbd-cli` (so completions and man
|
||||
pages cover them) but their *execution* lives in the owning binary, which has
|
||||
the server config / store / client config internals `cbd-cli` must not depend
|
||||
on.
|
||||
|
||||
```d2
|
||||
direction: right
|
||||
cbd_cli: cbd-cli (clap defs + asset gen) {
|
||||
defs: "Parser/Subcommand types\nRemoteArgs, Role\ngenerate_assets()"
|
||||
client: "feature=client:\nrun_remote() gRPC executor"
|
||||
}
|
||||
server: crabidy-server {
|
||||
guard_scan: "guard + scan\n(config writer, store)"
|
||||
}
|
||||
tui: cbd-tui {
|
||||
auth: "auth (client config writer)"
|
||||
}
|
||||
cbd: cbd (bundle)
|
||||
core: crabidy-core (generated client)
|
||||
cbd_cli.defs -> server.guard_scan: defines
|
||||
cbd_cli.defs -> tui.auth: defines
|
||||
cbd_cli.client -> core: gRPC to a running server
|
||||
server -> cbd_cli.client: library/queue/global
|
||||
tui -> cbd_cli.client: library/queue/global
|
||||
cbd -> server: reuses guard/scan
|
||||
cbd -> tui: reuses auth
|
||||
cbd -> cbd_cli.client: library/queue/global
|
||||
```
|
||||
|
||||
## D2 — Per-binary CLI and the no-subcommand default
|
||||
|
||||
Each binary defines a top-level clap `Parser` (in `cbd-cli`) with global
|
||||
connection flags and an **optional** subcommand:
|
||||
|
||||
- `ServerCli`: `[guard|scan|library|queue|global|completions]`; none → run the
|
||||
server (as today).
|
||||
- `TuiCli`: `RemoteArgs` + `--spectrum` + `[auth|library|queue|global|
|
||||
completions]`; none → run the TUI.
|
||||
- `CbdCli`: the union — `[guard|scan|auth|library|queue|global|completions]`;
|
||||
none → server + TUI (as today). This is "cbd has the commands from both."
|
||||
|
||||
**Config merge.** The no-subcommand path must keep today's behavior: read the
|
||||
TOML (writing defaults on first run) and let flags override. ClapSerde did this
|
||||
implicitly; a top-level `Parser` with a subcommand does not compose cleanly with
|
||||
ClapSerde's `Opt`. Decision: replace ClapSerde for the client binaries with a
|
||||
plain `serde` config load plus an explicit override step — the `RemoteArgs`
|
||||
fields are `Option`, and a provided flag overrides the file value. `init_config`
|
||||
keeps writing a defaults file on first run. This is a small, well-contained
|
||||
change to `cbd-tui/src/config.rs` and the two `main.rs` files.
|
||||
|
||||
Alternative considered: sniff argv for a known subcommand before ClapSerde
|
||||
parsing and branch. Rejected — it forfeits a unified `--help`/completions and is
|
||||
fragile.
|
||||
|
||||
## D3 — `library` / `queue` / `global` (remote)
|
||||
|
||||
The executor (`cbd-cli` feature `client`) maps subcommands to the existing RPCs
|
||||
(`RpcClient` already wraps all but `Stop`, which gains a wrapper):
|
||||
|
||||
- `library list [PATH]` (default `/`) → `GetLibraryNode`; prints child nodes and
|
||||
tracks (path, title; captured rows marked, per architecture/crabidy-store.md).
|
||||
- `library create <PARENT> <TITLE>`, `rename <PATH> <TITLE>`,
|
||||
`delete <PATH>` → the matching library RPCs.
|
||||
- `library save <PATH> <NAME>` → `CaptureLibraryNode{download:false}`;
|
||||
`library capture <PATH> <NAME>` → `{download:true}`.
|
||||
- `queue show` → `Queue`; `queue append|insert|replace <PATH>…`,
|
||||
`queue remove <POS>…`, `queue clear [--keep-current]`,
|
||||
`queue set-current <POS>`, `queue save <NAME>`, `queue capture <NAME>`
|
||||
(→ `CaptureLibraryNode` on `/crabidy/current`), `queue shuffle`,
|
||||
`queue repeat` (the `QueueModifiers` toggles).
|
||||
- `global play|stop|next|prev|restart|mute`, `global volume <DELTA>` (or
|
||||
`up|down` sugar around `ChangeVolume`).
|
||||
|
||||
Connection: `RemoteArgs` → a lazily-connected `CrabidyServiceClient` with a
|
||||
basic-auth interceptor built from `--user/--password` (empty user = no header,
|
||||
i.e. an open server). Each command is a one-shot: connect, call, print, exit.
|
||||
`RpcClient::connect`'s `&'static ServerConfig` signature is loosened (or the
|
||||
executor builds the client directly) so a CLI can pass an owned config.
|
||||
|
||||
Output is human-readable text; a `--json` flag is future work (D9).
|
||||
|
||||
## D4 — `guard` (server)
|
||||
|
||||
`crabidy-server guard <ROLE> [PASSWORD] [--no-config]` where `ROLE` ∈
|
||||
`owner|queue-owner|appender`:
|
||||
|
||||
1. Read the password from the argument, or from stdin if omitted.
|
||||
2. Hash it (`auth::hash_password`, argon2id) and **print the PHC string** to
|
||||
stdout (so it stays pipeable and `--no-config` reproduces today's
|
||||
`hash-password`).
|
||||
3. Unless `--no-config`: load `crabidy-server.toml` (or defaults), set the role's
|
||||
field (`owner`/`queue_owner`/`queue_appender`) to the hash, and write it back,
|
||||
preserving the flat `[auth]` shape and the other roles. This needs a **config
|
||||
writer** (D8) — none exists today.
|
||||
|
||||
`hash-password` is removed in favor of `guard` (`guard owner <pw> --no-config`
|
||||
is the exact replacement). The role names match the basic-auth user names.
|
||||
|
||||
## D5 — `scan` (server)
|
||||
|
||||
`crabidy-server scan <PATH> [--capture] [--move]`:
|
||||
|
||||
- Walk `<PATH>` recursively (bounded, skipping hidden entries), selecting files
|
||||
by audio extension (flac/mp3/m4a/ogg/opus/wav/webm/aac…).
|
||||
- For each audio file, write a `<stem>.cbd-track.toml` **beside it** using
|
||||
`fsdy::TrackFile` (`to_toml`, the shared naming), so the folder becomes a
|
||||
browsable `/fs` tree. Title defaults to the file stem (tag extraction is
|
||||
future work).
|
||||
- Default (neither flag): the toml's playable is `Playable::File` pointing at
|
||||
the audio's own file name (relative) — the audio stays where it is.
|
||||
- `--capture`: ingest the audio into the content store (hash + de-dup + sidecar,
|
||||
reusing `CrabidyStore`), and the beside-file toml gets a `Playable::Store`
|
||||
entry instead. Idempotent: an already-stored file de-dups.
|
||||
- `--move`: like `--capture` but the source audio is moved into the store, not
|
||||
copied — the original location keeps only the toml.
|
||||
- `--capture`/`--move` require the content store (a state/data dir);
|
||||
`scan` opens a `CrabidyStore` directly and calls a new `ingest_file(path,
|
||||
move) -> StoreName` helper (the local-source half of the D4 capture flow,
|
||||
factored out).
|
||||
|
||||
Existing `.cbd-track.toml` files are left untouched (scan never clobbers a
|
||||
hand-edited toml); a warning notes skips.
|
||||
|
||||
## D6 — `auth` (client)
|
||||
|
||||
`cbd-tui auth <ROLE> [PASSWORD] [--address ADDR]` (and the same on `cbd`):
|
||||
loads the client config (`cbd-tui.toml` / `cbd.toml`), sets `user` to the role
|
||||
name and `password` to the cleartext (optionally `address`), and writes it back
|
||||
via the **client config writer** (D8). The file is chmod-private-friendly; the
|
||||
help text repeats that the client config holds a plaintext password.
|
||||
|
||||
## D7 — Shell completions and man pages
|
||||
|
||||
Add `clap_complete` and `clap_mangen`. Each binary's `build.rs` build-depends on
|
||||
`cbd-cli` (default features — clap only, cheap) and, from its top-level
|
||||
`Command`, writes bash/zsh/fish completions and a `man` page into `OUT_DIR`
|
||||
every build (a genuine build step). When `CBD_ASSET_DIR` is set, `build.rs` also
|
||||
copies them into that stable directory. A devenv `gen-cli-assets` script sets
|
||||
`CBD_ASSET_DIR=$PWD/dist` and builds, so `dist/completions/**` and `dist/man/*.1`
|
||||
are produced on demand. A hidden `completions <shell>` subcommand on each binary
|
||||
prints a completion script to stdout for ad-hoc use.
|
||||
|
||||
Alternative considered: an `xtask` generator binary. Rejected — a `build.rs`
|
||||
keeps generation automatic and in lockstep with the CLI definition; the
|
||||
`CBD_ASSET_DIR` copy covers the "get them into the repo" need.
|
||||
|
||||
## D8 — Config writers (new)
|
||||
|
||||
Two small, careful serializers, both load-modify-write preserving shape:
|
||||
|
||||
- **Server** (`crabidy-server`): `ServerSettings` gains a `store(config_dir)`
|
||||
that serializes the current `[auth]` (round-tripping the existing file so
|
||||
unknown-field rejection stays satisfiable) — used by `guard`.
|
||||
- **Client** (`cbd-tui`): the `Config`/`ServerConfig` is already `Serialize`;
|
||||
`auth` loads it, sets the fields, and writes `toml::to_string_pretty` back to
|
||||
the config path — used by `auth`.
|
||||
|
||||
Both write to `dirs::config_dir()/crabidy/<file>` and create it if missing.
|
||||
|
||||
## D9 — Out of scope / future
|
||||
|
||||
- Tag extraction in `scan` (a `lofty`-backed title/artist/album/duration).
|
||||
- `--json` machine-readable output for `library list` / `queue show`.
|
||||
- Watching/streaming (`global watch` over `GetUpdateStream`).
|
||||
- Bulk auth (multiple roles in one `guard` invocation).
|
||||
|
||||
## Risks
|
||||
|
||||
- **Password in argv** is visible process-wide; mitigated by the stdin fallback
|
||||
and documented in help. Accepted per the explicit request.
|
||||
- **ClapSerde → clap migration** for the client config changes the parse path;
|
||||
the first-run-writes-defaults and flag-overrides-file behaviors must be
|
||||
preserved by tests.
|
||||
- **`build.rs` writing outside `OUT_DIR`** (the `CBD_ASSET_DIR` copy) is
|
||||
unconventional; gated on the env var so ordinary builds only touch `OUT_DIR`.
|
||||
- **`cbd-cli` as a build-dependency** must stay clap-only by default, or every
|
||||
build drags in tonic — enforced by the feature split.
|
||||
Loading…
Reference in New Issue