Rename package to scrobbledb and modernize project configuration

[crossjam]

Summary

This PR renames the package from lastfm-to-sqlite to scrobbledb and modernizes the project configuration.

Changes

• Package Rename: Renamed lastfm_to_sqlite module to scrobbledb throughout the codebase
• CLI Command: Updated command-line tool from lastfm-to-sqlite to scrobbledb
• Build System: Migrated from Poetry to modern setuptools backend with PEP 621 metadata
• Dependencies: Configured project to use uv for dependency management
• Authors: Added Brian M. Dennis as a project author
• License: Updated license from wtfpl to Apache-2.0
• Documentation: Added comprehensive docstring to the plays command explaining its functionality
• Testing:
  • Updated all test imports to use scrobbledb module
  • Fixed timestamp test expectation to match actual UTC time
  • Configured pytest.ini with testpaths = tests to automatically discover and run all tests
• Configuration: Updated .gitignore with Python-specific patterns (__pycache__/, .venv/, uv.lock)

All tests pass successfully.

🤖 Generated with Claude Code

[crossjam]

XDG Compliant Directory Support

This commit adds support for OS-specific standard user data directories using platformdirs.

Changes Made:

1. Added platformdirs dependency - Provides cross-platform directory path management

2. Configured app name as dev.pirateninja.scrobbledb for directory identification

3. Created helper functions in cli.py:

   • get_default_auth_path() - Returns XDG compliant path for auth.json
   • get_default_db_path() - Returns XDG compliant path for database

4. Updated auth command:

   • Now defaults to storing auth.json in XDG data directory
   • Users can still override with -a/--auth option
   • Help text updated to reflect the new default behavior

5. Updated plays command:

   • Database argument is now optional (previously required)
   • Defaults to scrobbledb.db in XDG data directory
   • Auth file also defaults to XDG data directory
   • Updated docstring to explain the new behavior

Default File Locations by Platform:

• Linux: ~/.local/share/dev.pirateninja.scrobbledb/
• macOS: ~/Library/Application Support/dev.pirateninja.scrobbledb/
• Windows: %LOCALAPPDATA%\dev.pirateninja.scrobbledb\

Files stored:

• auth.json - Authentication credentials
• scrobbledb.db - SQLite database with play history

Benefits:

• ✅ Follows OS conventions for user data storage
• ✅ No more cluttering working directory with auth.json and database files
• ✅ Backward compatible - users can still specify custom paths via CLI options
• ✅ Cross-platform friendly

All tests pass successfully.

---

Implementation assisted by Claude Code

[crossjam]

Rich Console UI and Init Command

This commit adds the rich library for enhanced console output and implements a new init command.

Changes Made:

1. Added Rich Package Dependency

• Added rich>=10.11.0 for beautiful, styled terminal output
• Provides components for panels, tables, progress bars, and styled text

2. Enhanced Console Interactions

• Replaced click.echo → rich console.print for colorful, styled output
• Replaced click.prompt → rich Prompt.ask for better user input experience
• Replaced click.progressbar → rich Progress for animated spinners and real-time progress tracking
• All output now uses rich markup for colors, styles, and formatting

3. New scrobbledb init Command

Implements a user-friendly initialization workflow:

• ✅ Checks for XDG compliant data directory and creates it if needed
• ✅ Creates default scrobbledb.db SQLite database
• ✅ Detects existing database and displays statistics (table names and row counts)
• ✅ Shows formatted summary panel with:
  • Data directory location
  • Database path
  • Auth file path
  • Helpful next steps for getting started

4. Improved Existing Commands

scrobbledb auth:

• Displays configuration prompt in a styled panel
• Shows clickable links to API registration pages
• Provides visual confirmation when credentials are saved

scrobbledb plays:

• Uses rich progress spinner during import for better feedback
• Shows username being imported
• Confirms successful completion with file path

Benefits:

• 🎨 Much improved user experience with colors, formatting, and visual feedback
• 📊 Better progress indication during long-running operations
• 🚀 Easier onboarding with the new init command
• ✨ Professional, modern CLI appearance
• 🔗 Clickable links in supported terminals

All tests pass successfully.

---

Implementation by Claude Code

[crossjam]

Dry-Run Option for Init Command

This commit adds a --dry-run flag to the scrobbledb init command for checking initialization state without making changes.

Changes Made:

Added --dry-run Flag

• New optional flag that checks initialization state without performing any actions
• Ensures no side effects - directories and files are not created in dry-run mode
• Fixed issue where helper functions were inadvertently creating directories during checks

Dry-Run Behavior

State Checking:

• Reports existence of data directory with visual indicators
• Shows database status and table statistics if database exists
• Checks for auth file presence
• Uses checkmarks (✓) for existing items and circles (○) for missing items

Action Reporting:

• Lists specific actions needed to complete initialization
• When initialization is incomplete: Shows yellow warning panel with required actions
• When already initialized: Shows green success panel with next steps
• Always provides clear guidance on what to do next

Benefits:

• 🔍 Non-destructive way to check scrobbledb setup status
• 📋 Clear reporting of what exists and what's missing
• 🎯 Actionable guidance on what needs to be done
• ✅ Helps users verify their environment before running commands
• 🚀 Useful for troubleshooting and documentation

All tests pass successfully.

---

Implementation by Claude Code

[crossjam]

Add Limit Option to Plays Command

This commit adds a --limit option to the scrobbledb plays command to cap the number of tracks imported.

Changes Made:

Added --limit CLI Option

• New optional integer parameter for the plays command
• Allows users to specify maximum number of tracks to import from last.fm
• Useful for testing imports or retrieving only recent history

Updated lastfm.recent_tracks() Function

• Added optional limit parameter to function signature
• Generator now tracks number of tracks yielded
• Implements early return when limit is reached to avoid unnecessary API calls
• Stops paginating through results once limit is satisfied

Enhanced User Feedback

• Console displays "Importing up to N plays..." when limit is specified
• Progress bar total automatically adjusted to reflect expected count
• Shows minimum of limit or total playcount for accurate progress indication

Benefits:

• 🧪 Enables testing imports without downloading entire play history
• ⚡ Faster retrieval when only recent plays are needed
• 💾 Reduces bandwidth and storage requirements for partial imports
• ✅ Works seamlessly with existing --since and --since-date options
• 🎯 No breaking changes - limit is completely optional

All tests pass successfully.

---

Implementation by Claude Code

[crossjam]

Recent Changes: Authentication, Command Rename, and Testing Improvements

This set of commits adds authentication support, renames the main command, and significantly expands test coverage.

Session Key Authentication

Fixed Last.fm API Authentication

• Added proper session key authentication flow using pylast.SessionKeyGenerator
• Auth command now prompts for password and obtains session key from Last.fm
• Session key is stored in auth.json and used for all API requests
• Prevents "User required to be logged in" errors from Last.fm API
• Updated get_network() to accept optional session_key parameter
• Added validation to check for session key before making API calls

Note: Users with existing auth files need to run scrobbledb auth again to obtain a session key.

Command Rename: plays → ingest

Renamed Command for Better Semantics

• scrobbledb plays → scrobbledb ingest
• Updated all docstrings and help text to use "ingest" terminology
• Updated console output messages:
  • "Importing plays" → "Ingesting tracks"
  • "Successfully imported plays" → "Successfully ingested tracks"
• Updated references in init command help text
• Database table name remains "plays" for data compatibility

Testing Improvements

Fixed Timezone-Independent Test

• Updated timestamp test to use dt.datetime.fromtimestamp() matching implementation
• Test now works correctly across all timezones (previously failed on EDT/non-UTC systems)
• Calculates expected timestamp the same way the code does

Added Comprehensive Database Insertion Tests

• test_save_artist: Verifies artist insertion and table structure
• test_save_artist_upsert: Tests upsert behavior (no duplicates)
• test_save_album: Tests album insertion with foreign key to artist
• test_save_track: Tests track insertion with foreign key to album
• test_save_play: Tests play insertion with composite primary key
• test_save_complete_scrobble: Tests full workflow with all tables
• test_save_multiple_plays_same_track: Tests multiple plays of same track

Test features:

• Uses temporary database fixtures for isolation
• Verifies primary keys and foreign keys are configured correctly
• Tests data integrity through SQL joins
• Validates upsert behavior prevents duplicates
• Confirms composite primary keys work properly

Test Results: All 8 tests pass successfully

Module Entry Point

Added __main__.py for Module Invocation

• Created src/scrobbledb/__main__.py module entry point
• Enables running as a module: python -m scrobbledb
• Provides alternative invocation method alongside scrobbledb command

Usage:

python -m scrobbledb --help
python -m scrobbledb init
python -m scrobbledb auth
python -m scrobbledb ingest

[crossjam]

LGTM. Great progress.