Implement library watchlist management in shanty-watch #6

New Issue

connor · 2026-03-17T14:30:45-04:00

connor commented

2026-03-17 14:30:45 -04:00

The shanty-watch crate manages the user's "library" — the collection of artists, albums, and individual songs they want to have. This is what makes Shanty more than just a tagger/organizer — it tracks what the user wants and compares it against what they have. Unlike Lidarr, Shanty supports monitoring at the individual song level, not just artist/album.

This issue covers the MVP watchlist functionality:

Adding items to the library — the user should be able to add:
- An artist (meaning "I want all releases by this artist")
- A specific album (meaning "I want this particular album")
- A specific track (meaning "I want this particular song")
  Each item can be in one of these states: wanted, available (found online but not downloaded), downloaded, owned (already in the local library)
Matching against existing library — when an item is added to the watchlist, check if it already exists in the database (from indexing). If so, mark it as owned. This cross-referencing should use fuzzy matching (artist name + title similarity) since local files may not match online metadata exactly.
Listing/querying the watchlist — provide functions to:
- List all monitored artists/albums/tracks
- Filter by status (show only "wanted" items, for example)
- Show a summary (e.g., "Artist X: 8/12 albums owned, 3 wanted, 1 available")
CLI interface — the shanty-watch binary should accept:
- add artist <name> — add an artist to the watchlist
- add album <artist> <album> — add a specific album
- add track <artist> <title> — add a specific track
- list [--status <status>] [--artist <name>] — list watchlist items
- remove <id> — remove an item from the watchlist
- status — show a summary of the library state

Design Considerations

The watchlist items should reference MusicBrainz IDs where available (from the tagging step) for more reliable matching than string comparison.
This crate doesn't do downloading or new-release checking in the MVP — it just manages the list. The downloading crate will look at "wanted" items, and new-release checking will be a post-MVP enhancement.
Think about how the web interface will interact with this — the web UI will be the primary way users add items (via search results from shanty-search), so the library API should be clean and JSON-serializable.

Acceptance Criteria

Users can add artists, albums, and individual tracks to the watchlist
Each watchlist item has a status (wanted, available, downloaded, owned)
Adding an item that already exists in the local library auto-marks it as owned
Watchlist can be queried/filtered by status and artist
Summary statistics work (X of Y albums owned, etc.)
Items can be removed from the watchlist
CLI interface works as specified
Watchlist data is stored in shanty-db
Unit tests for status transitions and matching logic
Fuzzy matching between watchlist items and local library entries works

Dependencies

Issue #1 (workspace scaffolding)
Issue #2 (shared database schema)
Issue #3 (music indexing — for cross-referencing against local library)

The `shanty-watch` crate manages the user's "library" — the collection of artists, albums, and individual songs they want to have. This is what makes Shanty more than just a tagger/organizer — it tracks what the user *wants* and compares it against what they *have*. Unlike Lidarr, Shanty supports monitoring at the individual song level, not just artist/album. This issue covers the MVP watchlist functionality: 1. **Adding items to the library** — the user should be able to add: - An artist (meaning "I want all releases by this artist") - A specific album (meaning "I want this particular album") - A specific track (meaning "I want this particular song") Each item can be in one of these states: `wanted`, `available` (found online but not downloaded), `downloaded`, `owned` (already in the local library) 2. **Matching against existing library** — when an item is added to the watchlist, check if it already exists in the database (from indexing). If so, mark it as `owned`. This cross-referencing should use fuzzy matching (artist name + title similarity) since local files may not match online metadata exactly. 3. **Listing/querying the watchlist** — provide functions to: - List all monitored artists/albums/tracks - Filter by status (show only "wanted" items, for example) - Show a summary (e.g., "Artist X: 8/12 albums owned, 3 wanted, 1 available") 4. **CLI interface** — the `shanty-watch` binary should accept: - `add artist <name>` — add an artist to the watchlist - `add album <artist> <album>` — add a specific album - `add track <artist> <title>` — add a specific track - `list [--status <status>] [--artist <name>]` — list watchlist items - `remove <id>` — remove an item from the watchlist - `status` — show a summary of the library state ### Design Considerations - The watchlist items should reference MusicBrainz IDs where available (from the tagging step) for more reliable matching than string comparison. - This crate doesn't do downloading or new-release checking in the MVP — it just manages the list. The downloading crate will look at "wanted" items, and new-release checking will be a post-MVP enhancement. - Think about how the web interface will interact with this — the web UI will be the primary way users add items (via search results from `shanty-search`), so the library API should be clean and JSON-serializable. ### Acceptance Criteria - [ ] Users can add artists, albums, and individual tracks to the watchlist - [ ] Each watchlist item has a status (`wanted`, `available`, `downloaded`, `owned`) - [ ] Adding an item that already exists in the local library auto-marks it as `owned` - [ ] Watchlist can be queried/filtered by status and artist - [ ] Summary statistics work (X of Y albums owned, etc.) - [ ] Items can be removed from the watchlist - [ ] CLI interface works as specified - [ ] Watchlist data is stored in `shanty-db` - [ ] Unit tests for status transitions and matching logic - [ ] Fuzzy matching between watchlist items and local library entries works ### Dependencies - Issue #1 (workspace scaffolding) - Issue #2 (shared database schema) - Issue #3 (music indexing — for cross-referencing against local library)

connor added the HighPriority MVP labels 2026-03-17 14:30:50 -04:00

connor referenced this issue

2026-03-17 16:24:56 -04:00

Implement the Actix web backend for `shanty-web` #9

connor referenced this issue

2026-03-17 16:38:37 -04:00

Implement new release monitoring in `shanty-watch` #19

connor referenced this issue

2026-03-17 16:44:10 -04:00

Add import from existing Lidarr database #26

connor referenced this issue

2026-03-17 16:45:12 -04:00