feat: modernize CLI UX with interactive prompts, spinners, and live displays

Add questionary for arrow-key artist selection in select/edit commands,
Rich spinners for all long operations, Rich Live table for sync progress,
diff panel with colored add/remove tables, delete/sync confirmations,
and retry prompts for recoverable failures.

Also adds codecov CI integration, pytest coverage thresholds, expanded
CLAUDE.md with critical rules, Makefile dev/format/check-all targets,
pre-push validation script, releasing docs, testing checklist, and
normalizes docs/ to lowercase filenames.

Author: pdugan20

.github/workflows/ci.yml

@@ -78,8 +78,14 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install package with dev dependencies
         run: pip install -e ".[dev]"
-      - name: Run tests
-        run: python -m pytest tests/ -v --tb=short
+      - name: Run tests with coverage
+        run: python -m pytest tests/ -v --tb=short --cov-report=xml
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
 
   claude-lint:
     name: Claude Lint

CLAUDE.md

@@ -4,54 +4,85 @@ A Python CLI for syncing a music library to a classic iPod from a modern Mac.
 
 ## Stack
 
-- **Python 3.11+** with Typer, Rich, tqdm, mutagen, pylast
+- **Python 3.11+** with Typer, Rich, questionary, tqdm, mutagen, pylast
 - **SQLite** for library index, playlist storage, and scrobble cache
 - **Vendored iOpenPodv2** for iPod database management (iTunesDB + ArtworkDB)
 - **beets** for metadata cleanup (called via subprocess)
 
 ## Project Layout
 
-- `clickwheel/` — Python CLI package
+- `clickwheel/cli.py` — Typer command definitions (entry point)
+- `clickwheel/output.py` — Rich console helpers (tables, spinners, panels, errors)
+- `clickwheel/config.py` — config loading (~/.clickwheel/config.yaml, env vars)
+- `clickwheel/db.py` — SQLite database (tracks, playlists, scrobble cache)
+- `clickwheel/library.py` — music file scanning (mutagen)
+- `clickwheel/autoscan.py` — automatic library scan before commands
+- `clickwheel/scrobble.py` — Last.fm scrobbling (pylast)
 - `clickwheel/ipod/` — vendored iOpenPodv2 (excluded from ruff)
 - `tests/` — pytest test suite
-- `scripts/` — bash utilities (audit, fix-metadata, setup)
-- `beets/` — beets config template (generated config is gitignored)
-- `docs/` — architecture docs
+- `scripts/` — bash utilities (audit, fix-metadata, setup, pre-push)
+- `docs/` — architecture, releasing, and testing docs
 
 ## Commands
 
 - `clickwheel scan` — index library metadata into SQLite (incremental by default)
 - `clickwheel fix` — clean up metadata via beets (requires `[fix]` extras)
-- `clickwheel select` — interactive iPod subset picker (auto-scans if stale)
+- `clickwheel select` — interactive iPod subset picker (questionary checkbox, auto-scans if stale)
 - `clickwheel playlist` — list saved playlists
-- `clickwheel edit` — add/remove artists from a playlist
-- `clickwheel delete` — delete a playlist
-- `clickwheel diff` — preview iPod sync changes
-- `clickwheel sync` — push playlist to iPod
+- `clickwheel edit` — add/remove artists (interactive questionary menus or `--add`/`--remove` flags)
+- `clickwheel delete` — delete a playlist (with confirmation)
+- `clickwheel diff` — preview iPod sync changes (panel + colored tables)
+- `clickwheel sync` — push playlist to iPod (Rich Live table, confirmation)
 - `clickwheel ls` — show iPod contents
 - `clickwheel eject` — safely unmount iPod
 - `clickwheel scrobble` — submit iPod listens to Last.fm (`--auth` for first-time setup)
 
 ## Development
 
 ```bash
-pip install -e '.[dev]'              # install with dev dependencies
+make dev                             # install with dev dependencies
+make test                            # run tests with coverage
+make lint                            # ruff check + format check
+make format                          # auto-format code
 pre-commit install --hook-type pre-commit --hook-type commit-msg
-python -m pytest tests/ -v           # run tests
-ruff check clickwheel/               # lint
-ruff format clickwheel/              # format
 ```
 
+## Critical Rules
+
+1. **All CLI output goes through `output.py`** — never call `console.print()` directly. A pre-commit pygrep hook enforces this. Use the semantic helpers: `error()`, `warn()`, `success()`, `info()`, `status()`, `dim()`, `confirm()`, `spinner()`.
+
+2. **Never move or rename source files** — Plex reads from the same music library. Metadata changes are written in-place.
+
+3. **The `scan` command is read-only** — it only reads metadata and writes to SQLite. No file modifications.
+
+4. **FLAC files are excluded from iPod sync** — stock iPod firmware doesn't support FLAC. Don't add transcoding.
+
+5. **`clickwheel/ipod/` is vendored code** — excluded from ruff linting. Don't refactor it unless fixing a bug in the iPod database writer.
+
+6. **Interactive prompts use questionary** — not raw `typer.prompt()` or `input()`. Arrow-key selection with `questionary.select()` and `questionary.checkbox()`. Non-interactive flags (`--add`/`--remove`) are kept for scripting.
+
+7. **Long operations use `spinner()` context manager** — beets phases, iPod reads, Last.fm calls, eject. Never leave the user staring at a frozen terminal.
+
+8. **Destructive operations require confirmation** — delete, sync. Use `typer.confirm()` with sensible defaults.
+
+9. **`select`, `edit`, `diff`, `sync` auto-scan** the library if stale. `--no-scan` skips this. Controlled by `auto_scan` and `auto_scan_staleness_minutes` in config.
+
+10. **`fix` requires beets extras** — `pip install 'clickwheel[fix]'`. Auto-generates beets config on first run.
+
+## Code Style
+
+- **Naming**: snake_case for functions/variables, UPPER_CASE for constants
+- **Error handling**: use `error()` + `raise typer.Exit(1)` for fatal errors. Offer retry for recoverable failures (sync DB write, scrobble submission).
+- **Imports**: lazy imports for heavy modules (questionary, subprocess, pylast) — import inside the function that uses them
+- **Output colors**: red=errors, yellow=warnings, green=success/confirm, bold=status, dim=hints, cyan=panels
+- **Progress**: `tqdm` for scan (many small items), Rich `Live` table for sync (fewer items, show detail), `spinner()` for async waits
+
 ## Configuration
 
 Runtime config is in `~/.clickwheel/config.yaml`. Environment variables override the config file. See README for all settings.
 
-## Key Constraints
+## Testing
 
-- Never move or rename source files (Plex reads from the same library)
-- FLAC files are excluded from iPod sync (stock firmware limitation)
-- Metadata changes are written in-place to source files
-- The `scan` command is read-only (no file modifications)
-- `select`, `edit`, `diff`, `sync` auto-scan the library if stale (configurable, `--no-scan` to skip)
-- `fix` requires beets + Pillow (`pip install 'clickwheel[fix]'`); auto-generates beets config on first run
-- macOS only (iPod sync depends on macOS disk utilities)
+- pytest with coverage threshold (30% minimum, excluding vendored ipod/)
+- Coverage runs in CI and uploads to Codecov
+- Test matrix: Python 3.11-3.13 on Ubuntu and macOS

CONTRIBUTING.md

@@ -5,14 +5,25 @@
 ```bash
 git clone https://github.com/pdugan20/clickwheel.git
 cd clickwheel
-pip install -e '.[dev]'
-pre-commit install --hook-type pre-commit --hook-type commit-msg
+make dev
 ```
 
+This installs the package with dev dependencies and sets up pre-commit hooks.
+
 ## Running Tests
 
 ```bash
-python -m pytest tests/ -v
+make test
+```
+
+Tests run with coverage reporting. The minimum threshold is 30% (excluding vendored `clickwheel/ipod/`).
+
+## Linting and Formatting
+
+```bash
+make lint                            # check only
+make format                          # auto-fix
+make check-all                       # lint + test + shellcheck + shfmt
 ```
 
 ## Commit Messages
@@ -52,15 +63,22 @@ test: add unit tests for scrobble dedup logic
 - Keep the header under 100 characters
 - No period at the end of the subject
 
-## Linting
+## Building
 
 ```bash
-ruff check clickwheel/
-ruff format clickwheel/
+make build
 ```
 
-## Building
+## Releasing
+
+See [docs/releasing.md](docs/releasing.md) for how versioning and releases work.
+
+## Pre-push Checks
+
+Run the full validation suite before pushing:
 
 ```bash
-python -m build
+./scripts/pre-push-checks.sh
 ```
+
+This checks lint, tests, shell scripts, and debug artifacts.

Makefile

@@ -1,9 +1,17 @@
-.PHONY: lint test build clean release release-dry release-patch release-minor release-major
+.PHONY: dev lint format test build clean check-all release release-dry release-patch release-minor release-major
+
+dev:
+	pip install -e '.[dev]'
+	pre-commit install --hook-type pre-commit --hook-type commit-msg
 
 lint:
 	ruff check clickwheel/
 	ruff format --check clickwheel/
 
+format:
+	ruff check --fix clickwheel/
+	ruff format clickwheel/
+
 test:
 	python -m pytest tests/ -v
 
@@ -13,6 +21,10 @@ build: clean
 clean:
 	rm -rf dist/ build/ *.egg-info clickwheel/*.egg-info
 
+check-all: lint test
+	shellcheck scripts/*.sh
+	shfmt -d scripts/*.sh
+
 release-dry:
 	semantic-release version --print
 

README.md

@@ -7,7 +7,7 @@
 
 A CLI for syncing a music library to a classic iPod from a modern Mac — no iTunes required.
 
-Handles the full workflow: scan and clean up your library's metadata, interactively pick what goes on the iPod, and sync with a progress bar.
+Handles the full workflow: scan and clean up your library's metadata, interactively pick what goes on the iPod, and sync — all with a modern terminal UI.
 
 ## Install
 
@@ -38,19 +38,19 @@ Commands like `select`, `edit`, `diff`, and `sync` automatically check for libra
 
 ## Commands
 
-| Command               | Description                                                                   |
-| --------------------- | ----------------------------------------------------------------------------- |
-| `clickwheel scan`     | Index your music library and report on metadata quality                       |
-| `clickwheel fix`      | Clean up metadata, fetch album art, fill genres via beets                     |
-| `clickwheel select`   | Interactive picker — browse by artist/album/genre                             |
-| `clickwheel playlist` | List saved playlists or show details for one                                  |
-| `clickwheel edit`     | Add or remove artists from a playlist (interactive or via `--add`/`--remove`) |
-| `clickwheel delete`   | Delete a saved playlist                                                       |
-| `clickwheel diff`     | Preview what would be added or removed on the iPod                            |
-| `clickwheel sync`     | Push your playlist to the iPod                                                |
-| `clickwheel ls`       | Show what's on the iPod                                                       |
-| `clickwheel eject`    | Safely unmount the iPod                                                       |
-| `clickwheel scrobble` | Submit recent iPod listens to Last.fm                                         |
+| Command               | Description                                                             |
+| --------------------- | ----------------------------------------------------------------------- |
+| `clickwheel scan`     | Index your music library and report on metadata quality                 |
+| `clickwheel fix`      | Clean up metadata, fetch album art, fill genres via beets               |
+| `clickwheel select`   | Interactive picker — checkbox artist selection                          |
+| `clickwheel playlist` | List saved playlists or show details for one                            |
+| `clickwheel edit`     | Add or remove artists via interactive menus or `--add`/`--remove` flags |
+| `clickwheel delete`   | Delete a saved playlist (with confirmation)                             |
+| `clickwheel diff`     | Preview what would be added or removed on the iPod                      |
+| `clickwheel sync`     | Push your playlist to the iPod (with live progress table)               |
+| `clickwheel ls`       | Show what's on the iPod                                                 |
+| `clickwheel eject`    | Safely unmount the iPod                                                 |
+| `clickwheel scrobble` | Submit recent iPod listens to Last.fm                                   |
 
 ## Configuration