diff --git a/plan/cli.md b/plan/cli.md new file mode 100644 index 0000000..076555d --- /dev/null +++ b/plan/cli.md @@ -0,0 +1,70 @@ +# Plan: the CLI + +Ordered, dependency-first tasks for `architecture/cli.md`, each mapped to the +gate(s)/test(s) it satisfies. + +## Foundations + +- [x] Add `clap_complete` + `clap_mangen` workspace deps; create the `cbd-cli` + crate (clap defs default; `client` feature adds the gRPC executor). +- [x] `cbd-cli`: `Role`, `RemoteArgs`, `Connection`, the command enums, the + three top-level `Cli`s, `generate_assets`, `print_completions`, and a + `run_remote` stub. Compiles with and without `client`. + +## Remote executor (`cbd-cli` `client` feature) + +- [ ] Implement `run_remote`: dispatch every `LibraryCmd`/`QueueCmd`/`GlobalCmd` + to its RPC via the generated client; pretty-print listings and the queue; + concise messages for mutations. Add the missing `Stop` call. _(Gates: remote + commands. Tests: a request-mapping unit test per group against a fake tonic + server, or at least argument-parse tests for the clap tree.)_ +- [ ] Map gRPC `Status`/transport errors to a short `color-eyre`/`eyre` report + (no chain dump for "unreachable"). _(Gate: remote errors.)_ + +## Config writers + +- [ ] Server: `ServerSettings::store(config_dir)` round-trips `[auth]` + (preserve other roles, flat shape). _(Gate: guard config write. Test: + set one role, reload, other roles intact.)_ +- [ ] Client: a `Config` writer (load/modify/save `cbd-tui.toml`/`cbd.toml`). + _(Gate: auth. Test: round-trip user/password/address.)_ + +## Server binary (`crabidy-server`) + +- [ ] Replace the `Cli`/`HashPassword` with `cbd_cli::ServerCli`. No subcommand + → `serve()` (unchanged). _(Gate: no-subcommand default.)_ +- [ ] `guard`: hash (stdin fallback), print PHC, write config unless + `--no-config`. Remove `hash-password`. _(Gate: guard.)_ +- [ ] `scan`: walk + write tomls; `--capture`/`--move` via a new + `CrabidyStore::ingest_file(path, move) -> StoreName` (factor the local-source + half of the D4 capture flow). _(Gate: scan. Tests: toml written; capture + dedups; move removes source; existing toml skipped.)_ +- [ ] `library`/`queue`/`global` → `cbd_cli::run_remote` (enable `cbd-cli` + `client`). `completions` → `print_completions`. + +## Client binary (`cbd-tui`) and `cbd` + +- [ ] Replace ClapSerde parsing: parse `cbd_cli::TuiCli`; load the TOML config + and apply `remote`/`spectrum` overrides; no subcommand → `run(config)`. + _(Gate: parsing/defaults. Tests: flag overrides file; first-run writes file.)_ +- [ ] `auth` writes the client config; `library`/`queue`/`global` → + `run_remote`; `completions` prints. +- [ ] `cbd`: parse `cbd_cli::CbdCli`; no subcommand → server + TUI (unchanged); + subcommands dispatch to the server (guard/scan), client (auth), or remote + (library/queue/global) paths. _(Gate: cbd union.)_ + +## Assets + build + +- [ ] `build.rs` in each binary: build-dep `cbd-cli` (default features), call + `generate_assets` for its `Command` into `OUT_DIR` and, when `CBD_ASSET_DIR` + is set, into that dir. _(Gate: assets.)_ +- [ ] devenv `gen-cli-assets` script: `CBD_ASSET_DIR=$PWD/dist cargo build`. + _(Gate: assets.)_ + +## Docs + verification + +- [ ] README: a CLI section (subcommands per binary, completions/man, the + password-in-argv note); update the config section for `auth`/`guard`. +- [ ] `plan/summary.md`: what was built + deviations. +- [ ] `cargo test --workspace` green; clippy `-D warnings`, fmt, markdownlint + clean (via `devenv shell`). diff --git a/quality/cli.md b/quality/cli.md new file mode 100644 index 0000000..640ecb1 --- /dev/null +++ b/quality/cli.md @@ -0,0 +1,77 @@ +# Quality gates: the CLI + +Criteria beyond the automatic tests (`cbd-cli`, `crabidy-server`, `cbd-tui`). +Each gate is pass/fail by reading the code. See `architecture/cli.md`. Boxes are +checked as the implement stage verifies them; deviations noted inline. + +## Parsing and defaults + +- [ ] Every binary (`crabidy-server`, `cbd-tui`, `cbd`) parses with clap-derive; + `--help`, `--version`, and per-subcommand `--help` work. +- [ ] **No subcommand preserves today's behavior**: `crabidy-server` runs the + server, `cbd-tui` runs the TUI, `cbd` runs the in-process server + TUI. No + extra output, no behavior change on the default path. +- [ ] The client config still writes a defaults file on first run, and a + provided `--address/--user/--password/--spectrum` overrides the file value; + omitted flags fall back to the file. The `cbd-tui.toml`/`cbd.toml` schema is + unchanged (same keys). + +## `guard` (server) + +- [ ] Prints the argon2id PHC hash to stdout and nothing else on the hash line + (pipe-friendly); the password is never logged. +- [ ] Without `--no-config`, writes the hash into the correct `[auth]` field + (`owner`/`queue_owner`/`queue_appender`) of `crabidy-server.toml`, creating the + file if missing and **preserving the other roles** and the flat shape + (`deny_unknown_fields` still parses the result). +- [ ] `--no-config` only prints (the exact replacement for the old + `hash-password`). +- [ ] A missing password argument reads one line from stdin. + +## `scan` (server) + +- [ ] Walks the path (bounded, skips hidden), selects files by audio extension, + and writes a `.cbd-track.toml` beside each with a `Playable::File` + pointing at the file's own name; an existing toml is left untouched (warned). +- [ ] `--capture` ingests each file into the content store (hash + de-dup + + sidecar) and writes a `Playable::Store` toml instead; re-scanning de-dups. +- [ ] `--move` moves the source into the store instead of copying; the original + location keeps only the toml. `--capture`/`--move` require a store dir. +- [ ] No panic on unreadable files/dirs; each defect is a warning, the walk + continues. + +## `auth` (client) + +- [ ] Writes `user` (role name) and `password` (cleartext), and `address` when + given, into the client config, preserving other fields; creates the file if + missing. The help text says the password is stored in plaintext. + +## `library` / `queue` / `global` (remote) + +- [ ] Each subcommand maps to the documented RPC (including a new `Stop` + wrapper); `library list` prints child nodes and tracks (captured rows marked). +- [ ] Connects with basic-auth from `--user/--password` (config fallback); an + empty user talks to an open server with no header. +- [ ] A server/RPC error exits non-zero with a readable message; no internal + report (color-eyre chain) is dumped for an ordinary "server unreachable" or a + gRPC status — those map to a concise message. +- [ ] The commands are available on `crabidy-server`, `cbd-tui`, and `cbd` + (cbd = union of server + client commands). + +## Assets + +- [ ] `clap_complete` + `clap_mangen` generate bash/zsh/fish completions and a + man page for each binary from its top-level `Command` in `build.rs` + (`OUT_DIR`), and into `$CBD_ASSET_DIR` when set. +- [ ] `build.rs` build-depends on `cbd-cli` with **default features only** (no + tonic on ordinary builds). +- [ ] A `completions ` subcommand prints a script to stdout. +- [ ] A devenv `gen-cli-assets` script produces `dist/completions/**` and + `dist/man/*.1`. + +## Errors and safety + +- [ ] Library errors are `thiserror`; CLI reports use `color-eyre`; no panics on + bad input, missing config, or an unreachable server. +- [ ] Passwords never appear in logs or error messages; the argv-exposure of a + password argument is documented and a stdin path is offered.