Code review with Gemini ; unify some cli interfaces ; fix album listing (#48)

* Generate plan for refactoring code and unifying subcommand interfaces for key entities

* Align AGENTS.md with poe usage

* feat: Unify CLI commands structure and implement missing commands

* docs: Update CLI command documentation to match standardized interface

* docs: Finalize CLI unification implementation log

* feat: improve album listing and standardize default sort order

- Collapse duplicate albums by title in 'albums list' for cleaner display
- Remove 'artist' and 'tracks' columns from default album list view
- Fix 'min-plays' filtering bug in album query logic
- Change default sort order to 'recent' for all 'list' commands
- Update documentation and tests to reflect these changes

* Update cog generated docs

* Fix QA errors: remove unused imports and update vulnerable dependencies

* Set default limit to 20 for unified commands and update docs

* Committing updated autogenerated documentation

* Refactor stats command and update plays list default limit

- Refactor 'stats' command to use shared options from 'command_utils'.
- Add support for '-f' short option for '--format'.
- Update default limit for 'plays list' from 20 to 50.
- Add 'tests/test_plays_unify.py' to verify 'plays list' changes.

Coauthored with Gemini CLI

Danger! Danger! High Voltage!

Author: crossjam

AGENTS.md

@@ -17,23 +17,24 @@ type checking.
 # set up environment from pyproject + uv.lock
 uv sync
 
+# poe is Poe the Poet, a Python task runner
+# poe integrates well with pyproject.toml
+
+# list tasks
+uv run poe
+
 # run the test suite (quiet, stop on first failure)
-uv run pytest -q -x
+uv run poe test:quick
 
 # run tests with coverage reporting
-uv run pytest --cov=./src/copyedit_ai --cov-report=html
+uv run poe test:cov
 
 # run type checks & lint (if dev deps are present)
-uv run ty src/copyedit_ai
-uv run ruff check src tests
-uv run ruff format src tests
+uv run poe type
+uv run poe lint
+uv run poe lint:fix
 
 # run the package (replace with your module/CLI)
-uv run python -m copyedit_ai --help
+uv run scrobbledb --help
 
-# poe is Poe the Poet, a Python task runner
-# poe integrates well with pyproject.toml
-
-# list tasks
-poe
 ```

docs/commands/albums.md

@@ -25,6 +25,7 @@ Commands:
   list    List albums with optional artist filter.
   search  Search for albums using fuzzy matching.
   show    Display detailed information about a specific album and list its...
+  top     Show top albums with flexible time range support.
 ```
 <!-- [[[end]]] -->
 
@@ -57,11 +58,10 @@ Options:
   -d, --database FILE             Database path (default: XDG data directory)
   -l, --limit INTEGER             Maximum results  [default: 20]
   --artist TEXT                   Filter by artist name
-  --format [table|csv|json|jsonl]
+  -f, --format [table|csv|json|jsonl]
                                   Output format  [default: table]
-  --fields TEXT                   Fields to include in output (comma-separated
-                                  or repeated). Available: id, album, artist,
-                                  tracks, plays, last_played
+  --fields TEXT                   Fields to include. Available: id, album,
+                                  artist, tracks, plays, last_played
   --select                        Interactive mode: select a single result and
                                   output its details as JSON
   --help                          Show this message and exit.
@@ -92,11 +92,99 @@ Usage: scrobbledb albums show [OPTIONS] [ALBUM_TITLE]
       # Use album ID     scrobbledb albums show --album-id 42
 
 Options:
-  -d, --database FILE          Database path (default: XDG data directory)
-  --album-id TEXT              Use album ID instead of title
-  --artist TEXT                Artist name (to disambiguate albums with same
-                               title)
-  --format [table|json|jsonl]  Output format  [default: table]
-  --help                       Show this message and exit.
+  -d, --database FILE             Database path (default: XDG data directory)
+  --album-id TEXT                 Use album ID instead of title
+  --artist TEXT                   Artist name (to disambiguate albums with same
+                                  title)
+  -f, --format [table|json|jsonl]
+                                  Output format  [default: table]
+  --help                          Show this message and exit.
+```
+<!-- [[[end]]] -->
+
+### `list`
+List albums with optional filtering and sorting.
+
+<!-- [[[cog
+result = runner.invoke(cli, ["albums", "list", "--help"], prog_name='scrobbledb')
+cog.out("```\n" + result.output + "```")
+]]] -->
+```
+Usage: scrobbledb albums list [OPTIONS]
+
+  List albums with optional artist filter.
+
+  Browse albums in your collection with sorting options. Filter by artist name
+  or artist ID to see all albums by a specific artist.
+
+  Examples:
+      # List top 50 albums by play count
+      scrobbledb albums list
+
+      # List albums by specific artist     scrobbledb albums list --artist
+      "Radiohead"
+
+      # List albums alphabetically     scrobbledb albums list --sort name
+      --order asc
+
+      # List recently played albums with tracks     scrobbledb albums list
+      --sort recent --expand
+
+Options:
+  -d, --database FILE             Database path (default: XDG data directory)
+  -l, --limit INTEGER             Maximum results  [default: 20]
+  --artist TEXT                   Filter by artist name
+  --artist-id TEXT                Filter by artist ID
+  --order [desc|asc]              Sort order  [default: desc]
+  --sort [plays|name|recent]      Sort by: plays, name, recent  [default:
+                                  recent]
+  --min-plays INTEGER             Show only albums with at least N plays
+                                  [default: 0]
+  --expand                        Show detailed view with tracks for each album
+  -f, --format [table|csv|json|jsonl]
+                                  Output format  [default: table]
+  --fields TEXT                   Fields to include. Available: id, album,
+                                  artist, tracks, plays, last_played
+  --help                          Show this message and exit.
+```
+<!-- [[[end]]] -->
+
+### `top`
+Show top albums with flexible time range support.
+
+<!-- [[[cog
+result = runner.invoke(cli, ["albums", "top", "--help"], prog_name='scrobbledb')
+cog.out("```\n" + result.output + "```")
+]]] -->
+```
+Usage: scrobbledb albums top [OPTIONS]
+
+  Show top albums with flexible time range support.
+
+  Discover your most played albums over various time periods.
+
+  Examples:
+      # Top 10 albums all-time
+      scrobbledb albums top
+
+      # Top 25 albums this month     scrobbledb albums top --limit 25 --period
+      month
+
+      # Top albums by specific artist     scrobbledb albums top --artist
+      "Radiohead"
+
+Options:
+  -d, --database FILE             Database path (default: XDG data directory)
+  -l, --limit INTEGER             Maximum results  [default: 20]
+  --period [week|month|quarter|year|all-time]
+                                  Predefined period
+  -u, --until TEXT                End date/time for analysis period
+  -s, --since TEXT                Start date/time for analysis period
+  --artist TEXT                   Filter by artist name
+  -f, --format [table|csv|json|jsonl]
+                                  Output format  [default: table]
+  --fields TEXT                   Fields to include. Available: rank, album,
+                                  artist, plays, percentage
+  --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->

docs/commands/artists.md

@@ -59,17 +59,16 @@ Usage: scrobbledb artists list [OPTIONS]
 
 Options:
   -d, --database FILE             Database path (default: XDG data directory)
-  -l, --limit INTEGER             Maximum results  [default: 50]
-  --sort [plays|name|recent]      Sort by: plays, name, or recent  [default:
-                                  plays]
+  -l, --limit INTEGER             Maximum results  [default: 20]
   --order [desc|asc]              Sort order  [default: desc]
+  --sort [plays|name|recent]      Sort by: plays, name, recent  [default:
+                                  recent]
   --min-plays INTEGER             Show only artists with at least N plays
                                   [default: 0]
-  --format [table|csv|json|jsonl]
+  -f, --format [table|csv|json|jsonl]
                                   Output format  [default: table]
-  --fields TEXT                   Fields to include in output (comma-separated
-                                  or repeated). Available: id, artist, plays,
-                                  tracks, albums, last_played
+  --fields TEXT                   Fields to include in output. Available: id,
+                                  artist, plays, tracks, albums, last_played
   --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->
@@ -103,16 +102,15 @@ Usage: scrobbledb artists top [OPTIONS]
 
 Options:
   -d, --database FILE             Database path (default: XDG data directory)
-  -l, --limit INTEGER             Number of artists to show  [default: 10]
-  -s, --since TEXT                Start date/time for analysis period
-  -u, --until TEXT                End date/time for analysis period
+  -l, --limit INTEGER             Maximum results  [default: 20]
   --period [week|month|quarter|year|all-time]
                                   Predefined period
-  --format [table|csv|json|jsonl]
+  -u, --until TEXT                End date/time for analysis period
+  -s, --since TEXT                Start date/time for analysis period
+  -f, --format [table|csv|json|jsonl]
                                   Output format  [default: table]
-  --fields TEXT                   Fields to include in output (comma-separated
-                                  or repeated). Available: rank, artist, plays,
-                                  percentage, avg_per_day
+  --fields TEXT                   Fields to include. Available: rank, artist,
+                                  plays, percentage, avg_per_day
   --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->
@@ -138,9 +136,10 @@ Usage: scrobbledb artists show [OPTIONS] [ARTIST_NAME]
       # Use artist ID     scrobbledb artists show --artist-id 123
 
 Options:
-  -d, --database FILE          Database path (default: XDG data directory)
-  --artist-id TEXT             Use artist ID instead of name
-  --format [table|json|jsonl]  Output format  [default: table]
-  --help                       Show this message and exit.
+  -d, --database FILE             Database path (default: XDG data directory)
+  --artist-id TEXT                Use artist ID instead of name
+  -f, --format [table|json|jsonl]
+                                  Output format  [default: table]
+  --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->

docs/commands/plays.md

@@ -43,11 +43,9 @@ Usage: scrobbledb plays list [OPTIONS]
   View listening history chronologically with flexible filtering.
 
   Examples:
-      # List last 20 plays
+      # List last 50 plays
       scrobbledb plays list
 
-      # List last 50 plays     scrobbledb plays list --limit 50
-
       # List plays in the last week     scrobbledb plays list --since "7 days
       ago"
 
@@ -61,22 +59,18 @@ Usage: scrobbledb plays list [OPTIONS]
 
 Options:
   -d, --database FILE             Database path (default: XDG data directory)
-  -l, --limit INTEGER             Maximum number of plays to return  [default:
-                                  20]
-  -s, --since TEXT                Show plays since date/time (ISO 8601 format or
-                                  relative like "7 days ago")
-  -u, --until TEXT                Show plays until date/time (ISO 8601 format)
-  --artist TEXT                   Filter by artist name (case-insensitive
-                                  partial match)
-  --album TEXT                    Filter by album title (case-insensitive
-                                  partial match)
-  --track TEXT                    Filter by track title (case-insensitive
-                                  partial match)
-  --format [table|csv|json|jsonl]
+  -l, --limit INTEGER             Maximum results  [default: 50]
+  --period [week|month|quarter|year|all-time]
+                                  Predefined period
+  -u, --until TEXT                End date/time for analysis period
+  -s, --since TEXT                Start date/time for analysis period
+  --artist TEXT                   Filter by artist name
+  --album TEXT                    Filter by album title
+  --track TEXT                    Filter by track title
+  -f, --format [table|csv|json|jsonl]
                                   Output format  [default: table]
-  --fields TEXT                   Fields to include in output (comma-separated
-                                  or repeated). Available: timestamp, artist,
-                                  track, album
+  --fields TEXT                   Fields to include in output. Available:
+                                  timestamp, artist, track, album
   --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->

docs/commands/stats.md

@@ -63,9 +63,9 @@ Usage: scrobbledb stats overview [OPTIONS]
       # Export to JSON     scrobbledb stats overview --format json
 
 Options:
-  -d, --database TEXT             Database path (default: XDG data dir)
-  -f, --format [table|json|jsonl|csv]
-                                  Output format (default: table)
+  -d, --database FILE             Database path (default: XDG data directory)
+  -f, --format [table|csv|json|jsonl]
+                                  Output format  [default: table]
   --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->
@@ -100,13 +100,14 @@ Usage: scrobbledb stats monthly [OPTIONS]
       monthly_stats.csv
 
 Options:
-  -d, --database TEXT             Database path (default: XDG data dir)
-  -s, --since TEXT                Start date (ISO 8601 or relative like '7 days
-                                  ago')
-  -u, --until TEXT                End date (ISO 8601 or relative)
-  -l, --limit INTEGER             Maximum number of months to display
-  -f, --format [table|json|jsonl|csv]
-                                  Output format (default: table)
+  -d, --database FILE             Database path (default: XDG data directory)
+  --period [week|month|quarter|year|all-time]
+                                  Predefined period
+  -u, --until TEXT                End date/time for analysis period
+  -s, --since TEXT                Start date/time for analysis period
+  -l, --limit INTEGER             Maximum results
+  -f, --format [table|csv|json|jsonl]
+                                  Output format  [default: table]
   --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->
@@ -138,13 +139,14 @@ Usage: scrobbledb stats yearly [OPTIONS]
       # Export to JSON     scrobbledb stats yearly --format json
 
 Options:
-  -d, --database TEXT             Database path (default: XDG data dir)
-  -s, --since TEXT                Start date (ISO 8601 or relative like '7 days
-                                  ago')
-  -u, --until TEXT                End date (ISO 8601 or relative)
-  -l, --limit INTEGER             Maximum number of years to display
-  -f, --format [table|json|jsonl|csv]
-                                  Output format (default: table)
+  -d, --database FILE             Database path (default: XDG data directory)
+  --period [week|month|quarter|year|all-time]
+                                  Predefined period
+  -u, --until TEXT                End date/time for analysis period
+  -s, --since TEXT                Start date/time for analysis period
+  -l, --limit INTEGER             Maximum results
+  -f, --format [table|csv|json|jsonl]
+                                  Output format  [default: table]
   --help                          Show this message and exit.
 ```
 <!-- [[[end]]] -->