diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b9973c9 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,33 @@ +name: Verify + +"on": + push: + branches: [v2-redesign] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-24.04 + strategy: + fail-fast: false + matrix: + python-version: ["3.11", "3.14"] + + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-python@v7 + with: + python-version: ${{ matrix.python-version }} + cache: pip + - name: Install project and test tools + run: python -m pip install --upgrade pip build pytest && python -m pip install -e . + - name: Run tests + run: pytest -q + - name: Compile sources + run: python -m compileall -q src + - name: Check distributable artifacts + run: python -m build diff --git a/.gitignore b/.gitignore index d27ba4f..8a0bf82 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,16 @@ __pycache__/ .pytest_cache/ .mypy_cache/ .ruff_cache/ +.coverage +.coverage.* +coverage.xml +htmlcov/ +.tox/ +.nox/ +.pyright/ +.DS_Store +*.swp +*.swo dist/ build/ *.egg-info/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4d591b0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,100 @@ +# 999 agent handoff + +Start with [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md). It is the canonical +current-state handoff. Use `PROJECT_CONTEXT.md` for durable product context and +the other `docs/` files for architecture, decisions, workflows, and UI detail. + +## Identity and purpose + +- Product and primary command: `999` +- Legacy command alias: `juice-lyrics` +- Python package: `juice_lyrics` +- Distribution: `juice-wrld-lyrics` +- XDG storage namespace: `juice-lyrics` (do not rename or duplicate it) +- Current beta candidate version: `2.0.0b1` (not yet released or tagged) +- Active development branch: `v2-redesign` +- Purpose: a Linux CLI/TUI for a local Juice WRLD library, catalogue browsing, + safe lyric maintenance, downloads, backups, and optional rmpc integration. + +## Non-negotiable safety rules + +- Never let automated tests touch the user's real music, config, state, + backups, queue, sidecars, or rmpc configuration. +- Tests that use application paths must isolate `HOME`, `XDG_CONFIG_HOME`, + `XDG_DATA_HOME`, and `XDG_CACHE_HOME`. Preserve the guard in + `tests/conftest.py`. +- Never run library operations against `/home/nobloat/Music` during automated + work. +- Preserve atomic state/LRC writes, backup-before-media-mutation, restore + rollback, state-conflict checks, and newest-10 valid backup retention. +- Wrong confident catalogue matches are worse than `Unknown`. Do not weaken + matcher thresholds, version/variant safeguards, duration rules, or ambiguity + handling without a reproduced generic bug and regression tests. +- Automatic Sync, backfill, refresh, cache changes, and ordinary identity + rebuilds must not overwrite a valid file-bound manual identity lock. +- Preserve downloader destination checks, `.part` handling, response/content + validation, checksums, resume safety, and atomic finalization. +- Do not make normal Sync modify audio, lyrics, backups, downloads, or rmpc + configuration. + +## Supported media and lyrics + +- MP3: native discovery/metadata, ID3 USLT/SYLT, adjacent timed `.lrc`. +- FLAC: native discovery/metadata, plain Vorbis `LYRICS`, adjacent timed `.lrc`. +- M4A: native discovery/metadata, plain MP4 `©lyr`, adjacent timed `.lrc`. +- No conversion occurs. `sidecar_lrc_path(audio_path)` is authoritative. +- The deprecated `lyrics_dir` may load for compatibility but cannot redirect + new output. + +## Development entry points + +- TUI/CLI: `.venv/bin/999` +- CLI: `src/juice_lyrics/cli.py` +- TUI: `src/juice_lyrics/tui/app.py`, `src/juice_lyrics/tui/screens/` +- Incremental Library Sync: `src/juice_lyrics/services/library_index_sync.py` +- Status/maintenance: `src/juice_lyrics/services/library_status.py` and + `library_sync.py` +- Read-only duplicate analysis: `src/juice_lyrics/services/library_duplicates.py` +- Read-only metadata proposals: `src/juice_lyrics/services/metadata_audit.py` +- Transactional metadata writer foundation: `src/juice_lyrics/services/metadata_repair.py` +- Read-only diagnostics/support reports: `src/juice_lyrics/services/doctor.py` +- Shell completion generation: `src/juice_lyrics/services/shell_completion.py` +- Matching/identity: `src/juice_lyrics/library/matching.py` and + `src/juice_lyrics/services/library_identity.py` +- State: `src/juice_lyrics/state.py` +- Media/sidecars/backups: `src/juice_lyrics/library/media.py`, + `src/juice_lyrics/lyrics/sidecar.py`, `src/juice_lyrics/backup/manager.py` + +## Verification + +Use focused tests while developing, then one full run before declaring a code +milestone complete: + +```bash +pytest -q tests/test_library_index_sync.py tests/test_tui_library.py +pytest -q +python -m compileall -q src +git diff --check +``` + +For packaging milestones, build with `python -m build` and clean-install both +the wheel and sdist in temporary environments outside the checkout. Never test +installation by replacing the user's real pipx environment. +For release preparation, follow `docs/BETA_RELEASE_CHECKLIST.md`. Do not merge +to `main`, create a tag/release, or publish a package without explicit approval. + +Normal Library use is `999` → Library → `s` (**Sync Library**). Press `?` for +the implemented key map. Common safe routine work should be automatic/simple; +ambiguous or destructive work requires an explicit user decision. +Duplicate findings are evidence for review only; never auto-delete, merge, +move, retag, or replace media. +Metadata repair is exposed only through explicit per-field selection and a +cancel-first confirmation. Never bypass `metadata_repair.py` with direct tag +writes or weaken its backup, preservation, conflict, rollback, and lock checks. + +## Roadmap discipline + +The current roadmap is in `docs/PROJECT_STATE.md` and `docs/ROADMAP.md`. Keep +normal Library UX centered on **Sync Library** and **Issues**; keep +repair/recovery tools secondary. After substantial milestones, update +`docs/PROJECT_STATE.md` and any directly affected design/user documentation. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..352a3ef --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,11 @@ +include LICENSE +include README.md +include pyproject.toml +recursive-include src *.py +prune docs +prune tests +exclude AGENTS.md +exclude PROJECT_CONTEXT.md +exclude .gitignore +global-exclude __pycache__ +global-exclude *.py[cod] diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index b4f5c9a..e7aba5c 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -1,302 +1,63 @@ -# Project Context +# Project context -This file preserves the human/project context needed to continue development across chats and coding agents. +This file records durable human and product context. For the current technical +checkpoint and roadmap, read `docs/PROJECT_STATE.md`. -## User / environment context +## User and environment -* Primary OS: Arch Linux. -* The user prefers lightweight Linux tools and CLI/TUI workflows. -* The user uses MPD + rmpc for music playback. -* The user is comfortable running commands, but is not a Python developer. -* Normal workflows should use straightforward commands, friendly output, sensible defaults, and safe automation. -* The user should not be expected to understand Python internals to use the application. +- Primary platform: Arch Linux. +- The user prefers lightweight keyboard-first Linux CLI/TUI tools and uses MPD + with rmpc. +- The user can run documented commands but should not need Python knowledge or + internal terms such as job UUIDs, SYLT frames, or state records. +- Defaults and error messages should be safe, direct, and understandable. -## Music setup +The usual local collection is under `~/Music/Juice WRLD`, but every path is +configurable. Automated work must never touch the user's real library or XDG +state. Tests use temporary HOME/XDG roots. -Default local library: +## Product identity -`~/Music/Juice WRLD/Unreleased` +- Product and primary executable: `999` +- Legacy executable: `juice-lyrics` +- Python package: `juice_lyrics` +- Distribution: `juice-wrld-lyrics` +- Existing storage namespace: `juice-lyrics` -Default rmpc lyric directory: +The internal and storage names intentionally remain stable. Do not create a +second `999` state tree or silently migrate user data. -`~/Music/Juice WRLD/lyrics` +## Product principles -These paths are defaults only and must remain configurable and portable. - -## Existing proven behavior - -The 1.4.0 release was tested against a 35-song local library: - -* 35/35 API matches -* 18 songs with synchronized lyrics -* 17 songs with plain lyrics only -* 18 rmpc LRC files generated -* 35/35 lyric embeddings verified -* version-aware matching works for v1/v2 tracks -* backups and restore work -* rmpc integration works - -The existing lyrics workflow is proven and should not be unnecessarily redesigned. - -## Lyrics behavior - -* Prefer API `synced_lyrics`. -* Synced lyrics are embedded as ID3 SYLT. -* Synced lyrics also produce `.lrc` files for rmpc. -* If only API `lyrics` exists, embed them as ID3 USLT. -* Never invent timestamps or fake-sync plain lyrics. -* Plain lyrics without timestamps do not generate timed `.lrc` files. - -## rmpc - -Keep MPD + rmpc as the primary playback setup. - -Default lyrics directory: - -`~/Music/Juice WRLD/lyrics` - -Preserve unrelated rmpc configuration when modifying configuration files. - -Advanced commands: - -```bash -juice-lyrics rmpc setup -juice-lyrics rmpc sync -juice-lyrics rmpc verify -``` - -## Matching - -Matching intentionally uses several signals rather than trusting a title alone: - -* explicit version (`v1`, `v2`, etc.) -* exact API filename -* exact API path filename -* title/original key -* known Juice WRLD aliases -* local audio duration vs API duration -* category preference - -This helps prevent version mix-ups such as selecting `Starstruck (v1)` for a local `Starstruck (v2)` file. - -## Normal workflow - -First-time setup: - -```bash -juice-lyrics setup -``` - -Normal maintenance: - -```bash -juice-lyrics sync -``` - -Useful commands: - -```bash -juice-lyrics status -juice-lyrics search -juice-lyrics info -juice-lyrics guide -juice-lyrics doctor -``` - -## Project direction - -The project is evolving from a focused lyrics utility into a polished Juice WRLD API frontend/hub while retaining the existing CLI functionality. - -Long-term direction includes: - -* interactive browse/search TUI -* API search and discovery -* explicit resource acquisition -* bulk acquisition from explicitly selected resources -* richer local library management -* improved user-facing UX - -Do not replace MPD/rmpc with a custom streaming system. - -## Acquisition subsystem - -The project contains an acquisition subsystem for resources represented by the application's resource/API layer and explicitly selected by the user. - -The intended flow is: +The core download journey is: ```text -resource/API result - ↓ -explicit user selection - ↓ -AcquisitionItem - ↓ -persistent acquisition job - ↓ -downloader - ↓ -validation/finalization - ↓ -post-processing - ↓ -existing lyrics/library workflow +Browse → Add → Downloads → Download queue → Done ``` -The acquisition layer is deliberately separated into: - -* resource resolution -* selection -* acquisition item modelling -* duplicate detection -* persistent jobs -* transport/download -* validation -* post-processing - -The downloader is a transport component. It should not perform catalogue discovery, matching, or lyrics processing. - -## Acquisition components - -The current architecture includes: - -* `models.py` for acquisition item/result/job state data -* `manifests.py` for explicit selection manifests -* `resolver.py` for converting selected resources into normalized acquisition items -* `downloader.py` for transport -* `jobs.py` for persistent acquisition jobs -* duplicate detection -* job execution/orchestration -* MP3 post-processing integration - -The repository must be inspected to determine which of these components are complete, incomplete, or require refinement. - -## Downloader expectations - -The downloader is responsible for normal transport concerns such as: - -* HTTPS transport -* streaming -* connection/read timeouts -* normal HTTP error handling -* retries for transient failures -* temporary `.part` files -* resumable transfers where the server supports them -* expected-size validation when supplied -* SHA-256 validation when supplied -* duplicate/existing destination handling -* progress reporting -* atomic finalization -* cleanup after failed transfers - -It receives an already-resolved `AcquisitionItem`. - -It should not: - -* crawl the catalogue -* discover unrelated resources -* perform lyric matching -* modify MP3 metadata -* configure rmpc - -## Acquisition CLI - -The initial acquisition workflow is: - -```bash -juice-lyrics acquire search "rental" -juice-lyrics acquire add "rental" --index 1 -juice-lyrics acquire jobs -juice-lyrics acquire run -``` - -The selection model must remain explicit. A search operation should not silently create acquisition jobs for every result. - -## Persistent acquisition jobs - -Jobs are stored persistently under the application's XDG data location. - -The job system should: - -* save atomically -* preserve per-item progress/state -* record errors -* recover interrupted states -* avoid losing successful completed items when another item fails - -## Acquisition → lyrics integration - -After successful MP3 acquisition, an optional post-processing hook uses the existing lyrics engine. - -The existing behavior remains: +The normal local-library action is Library → `s` → **Sync Library**. ```text -acquired MP3 - ↓ -API metadata/lyrics - ↓ -SYLT or USLT - ↓ -verification - ↓ -rmpc .lrc when synced lyrics exist +common safe routine work → automatic/simple +ambiguous/destructive work → explicit user decision ``` -Non-MP3 resources remain acquisition-only for now. - -A post-processing failure must be persisted as an item failure rather than reported as full success. - -## File safety - -Before modifying an MP3: - -* create a timestamped backup -* write metadata safely -* verify the result -* restore the backup immediately if verification fails - -Backups: - -`~/.local/share/juice-lyrics/backups/` - -Only lyric frames created by this tool are replaced. - -Other unrelated lyric frames remain untouched. - -## Current checkpoint - -The latest development checkpoint reports: - -* live API resource resolution implemented and verified -* multi-index selection and manifest-based bulk acquisition implemented -* retry and job deletion commands implemented -* persistent acquisition jobs and transient state recovery verified -* generic transport downloader with HTTP range resume and validation verified -* MP3 post-processing with ID3 SYLT/USLT and rmpc LRC integration verified -* Settings / Path CLI compatibility verified -* 80 automated tests passing across the suite - -## Development rules - -Before major architectural changes, read: - -* `PROJECT_CONTEXT.md` -* `docs/ROADMAP.md` -* `docs/ARCHITECTURE.md` - -Prefer incremental, testable changes. - -Preserve proven behavior. - -Avoid unnecessary rewrites. - -Add/update tests whenever behavior changes. - -Update this file, `docs/ROADMAP.md`, and `docs/CHANGELOG.md` at meaningful milestones. - -## Continuity - -The latest transferred project archive is the current development source of truth. - -The existing GitHub repository is not authoritative. - -When documentation conflicts with the actual implementation, inspect the code and tests and resolve the discrepancy deliberately. +Keep the TUI simpler than the CLI. The CLI remains useful for scripting, +diagnostics, and unusual recovery. Do not replace MPD/rmpc with a custom player. + +## Durable safety decisions + +- Preserve embedded lyrics and adjacent synchronized `.lrc` files. +- Never invent timestamps or treat untimed text as synchronized lyrics. +- Never convert MP3, FLAC, or M4A audio. +- The finalized audio path controls the sidecar path; deprecated `lyrics_dir` + cannot redirect new writes. +- Back up before in-place media metadata mutation and verify afterward. +- Keep the newest 10 valid backups and preserve historical restore manifests. +- Matching is conservative: wrong confident identity is worse than Unknown. +- Normal startup and Library Sync never rewrite rmpc configuration. +- Acquisition is explicit; adding to the queue does not start downloading. + +Detailed architecture, decisions, user behavior, and history live in +`docs/ARCHITECTURE.md`, `docs/DECISIONS.md`, `docs/USER_GUIDE.md`, and +`docs/CHANGELOG.md`. diff --git a/README.md b/README.md index fd9c483..1aac6b8 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,48 @@ -# juice-lyrics 1.4.0 +# 999 -A small, cautious Linux CLI for managing lyrics metadata in local MP3 libraries and generating synced `.lrc` files for rmpc. +A terminal-native Juice WRLD music hub for Linux, with cautious lyrics +management for local MP3, FLAC, and M4A libraries and synchronized `.lrc` +sidecars for rmpc. -It uses the Juice WRLD API as a metadata/lyrics source, prefers synchronized lyrics (`SYLT`), and falls back to ordinary embedded lyrics (`USLT`) when timestamps are unavailable. +> **Beta release:** `2.0.0b1` is the first beta of the redesigned `999`. +> Keep a separate backup of valuable media and review every confirmed repair. +> This release is distributed from its immutable Git tag, not a package index. + +999 uses the Juice WRLD API as a catalogue and lyrics source. MP3 supports +plain and synchronized embedded lyrics; FLAC and M4A use standard plain lyric +tags. Genuine synchronized lyrics for every supported format use an adjacent +same-basename `.lrc` file. + +This is an unofficial fan-made tool. It is not affiliated with or endorsed by +Juice WRLD's estate, record labels, or the Juice WRLD API. The repository does +not include music or lyric content; users are responsible for the media and +services they access. + +## Preview + +![999 dashboard rendered with synthetic demo data](docs/assets/999-dashboard.png) + +_Captured from the real TUI with synthetic counts and a generic path. It +contains no user library or state data._ ## The simple workflow ### First time ```bash -juice-lyrics setup +999 ``` -This configures the library, embeds available lyrics, and configures rmpc automatically when rmpc and its config are detected. +This opens the TUI. Missing configuration or library folders are reported in +the interface without changing rmpc or starting a download. + +Configuration is optional. To write a starter configuration, or explicitly +configure rmpc later: + +```bash +999 config init +999 rmpc setup +``` Your Juice WRLD folder is kept together: @@ -20,47 +50,87 @@ Your Juice WRLD folder is kept together: ~/Music/Juice WRLD/ ├── Unreleased/ │ ├── Bottle.mp3 +│ ├── Bottle.lrc │ ├── Rental.mp3 +│ ├── Rental.lrc │ └── ... -└── lyrics/ - ├── Bigger.lrc - ├── Blade.lrc - └── ... ``` ### Normal use -After adding or changing songs: +Open `999`, choose **Library**, then press `s` for **Sync Library**. It discovers +new, changed, and removed local tracks, identifies confident catalogue matches, +and updates the Library view without changing audio or lyrics. Press `a` for +**Issues**, the snapshot-backed list of tracks that still need a decision or +repair. Press `d` for a read-only **Duplicates** view showing exact file copies +and conservative probable-recording groups with their evidence and paths. +Press `g` for **Missing Library**, an exact catalogue-ID comparison that keeps +alternate versions distinct and labels partial/offline catalogue coverage. +A selected missing recording can be added to the existing Downloads queue; it +is never downloaded automatically. +**Maintain lyrics** +is the separate, explicitly approved repair action. Maintenance shows a non-mutating preview and +a cancel-first confirmation before changing audio metadata or sidecars. +Press `?` on any TUI section for a scrollable guide to every app shortcut. +The on-screen shortcut lines show the common actions; adding songs to Downloads +is immediate and never starts a download. Confirmations are reserved for bulk +downloads and high-impact changes to audio, backups, catalogue identities, or player configuration. +Library lyric coverage is determined from the local audio and a genuinely +timestamped adjacent `.lrc`; catalogue matching is shown separately because it +is needed for automatic refresh, not for recognizing already healthy lyrics. +The separate Library **Refresh** action remains a read-only local rescan. +Routine discovery and safe identity backfill belong to **Sync Library**. +When a track remains Unknown or has a wrong automatic identity, select it in +Library and press `c` to search, choose, and lock the correct catalogue +record. Press `u` to unlock and clear a manual choice so a later Sync can +reconsider it. + +Duplicate review uses the already-loaded Library snapshot. It does not rescan, +contact the catalogue, or change files. Distinct versions such as live, +remix, session, extended, TV mix, and numbered versions are kept separate. +Select a track and press `e` to review metadata repair proposals. Nothing is +selected automatically: choose individual title, artist, album, or track-number +changes, then review a cancel-first confirmation. Apply creates a full audio +backup and verifies that audio, artwork, lyrics, unrelated tags, and the +adjacent sidecar were preserved. Existing values and version differences are +marked for review rather than silently replaced. + +The CLI remains available for scripting and automation. `999 sync` remembers +files it has already processed, so unchanged verified files are skipped. + +Useful status command: ```bash -juice-lyrics sync +999 status ``` -`sync` remembers the files it has already processed. Unchanged, verified files are skipped, so normal updates are much faster than a full rescan. - -Useful status command: +Read-only diagnostics and an optional sanitized support report: ```bash -juice-lyrics status +999 doctor +999 doctor --support-report +999 doctor --save-report ./999-support.json ``` Built-in guide: ```bash -juice-lyrics guide +999 guide ``` ## What `sync` does ```text -local MP3 +local MP3, FLAC, or M4A │ ├── match to API using title + version + API path + duration │ - ├── synced lyrics available ──► ID3 SYLT - │ └── rmpc .lrc + ├── synced lyrics available ──► MP3: ID3 SYLT + │ FLAC: plain-text Vorbis LYRICS + │ M4A: plain-text MP4 ©lyr + │ └── adjacent rmpc .lrc (timing authority) │ - └── only ordinary lyrics ─────► ID3 USLT + └── only ordinary lyrics ─────► MP3: ID3 USLT / FLAC: Vorbis LYRICS / M4A: MP4 ©lyr ``` Songs without synchronized lyrics still receive ordinary embedded lyrics. rmpc's synchronized Lyrics pane cannot display those as timed lyrics unless timestamps are available. @@ -70,9 +140,9 @@ Songs without synchronized lyrics still receive ordinary embedded lyrics. rmpc's The API's catalogue can be searched without downloading media: ```bash -juice-lyrics search "red dead" -juice-lyrics search --category unreleased --era DRFL "moncler" -juice-lyrics info "Rental" +999 search "red dead" +999 search --category unreleased --era DRFL "moncler" +999 info "Rental" ``` `search` shows useful catalogue metadata, lyric availability, era, duration, and file path information. `info` fetches the detailed song record when possible. @@ -83,38 +153,45 @@ The project avoids untargeted catalogue scraping; media acquisition is explicit, The repository keeps its development and continuity context in version-controlled documentation so work can safely continue across chats or coding agents: -- `PROJECT_CONTEXT.md` — user/project context and major decisions -- `docs/ROADMAP.md` — current and planned work +- `AGENTS.md` — concise first-stop instructions for coding agents +- `docs/PROJECT_STATE.md` — canonical current checkpoint and roadmap +- `PROJECT_CONTEXT.md` — durable user and product context +- `docs/ROADMAP.md` — concise forward roadmap - `docs/ARCHITECTURE.md` — component responsibilities and dependency direction - `docs/USER_GUIDE.md` — straightforward user workflows - `docs/DEVELOPMENT.md` — development and testing guidance - `docs/CHANGELOG.md` — release and milestone history +- `docs/BETA_RELEASE_CHECKLIST.md` — pre-release acceptance and release steps -Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/ARCHITECTURE.md`. +Before major changes, read `AGENTS.md`, `docs/PROJECT_STATE.md`, and the +relevant architecture or user document. ## Commands | Command | Purpose | |---|---| -| `setup` | First-time setup and rmpc integration | +| `setup` | Compatibility shortcut for an initial library sync; never rewrites rmpc | | `sync` | Normal day-to-day library update | | `status` | Show current library state without API calls | | `scan` | Detailed API scan/troubleshooting | | `embed` | Lower-level embed-only command | -| `verify` | Validate embedded SYLT/USLT frames | -| `restore` | Restore a previous MP3 backup | -| `doctor` | Diagnose Python, Mutagen, API, and paths | +| `verify` | Validate supported MP3/FLAC/M4A embedded lyrics | +| `restore` | Restore a previous audio backup | +| `doctor` | Bounded read-only health checks; optional sanitized support report | +| `completion bash/zsh/fish` | Generate completion from the current CLI command tree | | `guide` | Show this workflow in the terminal | | `search` | Search the public song catalogue | | `info` | Inspect a song's API metadata | | `acquire` | Explicitly select, queue, and acquire API media resources | -| `rmpc setup/sync/verify` | Advanced rmpc-only operations | +| `rmpc setup/sync/verify` | Scriptable and advanced rmpc operations; basic check/setup is also in Library | | `config` | Manage persistent configuration | | `cache clear` | Clear cached API responses | +| `state clean` | Preview clearly stale external state records; `--yes` backs up state before pruning | +| `state rebuild-identities` | Preview rematching current library identities; `--yes` backs up state and applies | ## Safety -Before modifying MP3s, the tool creates timestamped backups under: +Before modifying MP3, FLAC, or M4A metadata, the tool creates timestamped backups under: ```text ~/.local/share/juice-lyrics/backups/ @@ -122,9 +199,26 @@ Before modifying MP3s, the tool creates timestamped backups under: Each modified file is verified after writing. If verification fails for that file, it is immediately restored from its backup. -The audio stream is never decoded/re-encoded by this tool; it only edits MP3 metadata and writes separate LRC text files. +The audio stream is never decoded/re-encoded by this tool. It edits MP3 ID3, +FLAC Vorbis, or M4A MP4 metadata and writes separate adjacent LRC text files. + +For MP3, only lyric frames created by this tool (`desc = "Juice WRLD API"`) are +replaced. For FLAC, the standard `LYRICS` field is updated while unrelated +Vorbis comments are preserved. For M4A, standard `©lyr` is updated while +unrelated MP4 atoms are preserved. + +State cleanup is intentionally explicit. `999 state clean` is preview-only; +`999 state clean --yes` first copies `state.json` beside itself with a +`pre-clean-...bak` suffix, then atomically removes only clearly stale external +records. It never deletes audio or LRC files. -Only lyric frames created by this tool (`desc = "Juice WRLD API"`) are replaced. Other unrelated lyric frames are preserved. +Catalogue identity rebuilding is also preview-first. Use +`999 state rebuild-identities` to inspect its scope, then add `--yes` to rerun +the current matcher for every current library file. The operation changes only +`song_id` and `api_name`, preserves lyric state and unrelated records, and +creates a complete `state.json.pre-identity-rebuild-...bak` copy before one +atomic state write. `--refresh` bypasses otherwise-valid catalogue search cache +entries, and `--details` prints every changed mapping. ## Matching @@ -136,26 +230,40 @@ The matcher intentionally uses several signals rather than trusting a title alon - title/original key - known Juice WRLD aliases - local audio duration vs API duration -- category preference +- candidate-only version/variant penalties +- small released-category evidence +- compatible local album/API path evidence This prevents common version mix-ups such as selecting `Starstruck (v1)` for `Starstruck (v2)`. +Known durations normally use the configured three-second tolerance. A released, +unversioned, unvaried candidate with exact base-title and compatible album/path +evidence may use a tightly bounded catalogue-metadata grace: at most two +additional seconds, five seconds total, and two percent of the local duration. +Grace receives reduced negative evidence rather than a normal duration-match +bonus; larger or weakly corroborated differences remain ineligible. ## rmpc -The normal `setup`/`sync` workflow uses: +Audio and external synchronized lyrics stay together. A synchronized song gets +a same-basename sidecar beside its audio file: ```text -~/Music/Juice WRLD/lyrics +song.mp3 +song.lrc ``` -and safely patches the relevant rmpc lyrics settings while preserving the rest of the user's `config.ron`. +The old `lyrics_dir` configuration key is accepted for compatibility but is +deprecated and does not direct new output. Existing centralized files are not +moved automatically; migration is a separate, explicit operation. Sidecars work +naturally when the music tree is synchronized between devices. Embedded lyrics +remain supported. The advanced commands remain available: ```bash -juice-lyrics rmpc setup -juice-lyrics rmpc sync -juice-lyrics rmpc verify +999 rmpc setup +999 rmpc sync +999 rmpc verify ``` ## Configuration @@ -163,26 +271,55 @@ juice-lyrics rmpc verify Defaults are designed for the user's common Linux layout, but the library can be overridden globally: ```bash -juice-lyrics config init -juice-lyrics config show +999 config init +999 config show ``` or for a single command: ```bash -juice-lyrics --path ~/Music/MyLibrary status +999 --path ~/Music/MyLibrary status ``` The tool follows XDG locations for its config, cache, state, and backups. ## Installation -### pipx +### Recommended pipx install + +```bash +pipx install "git+https://github.com/NotAI-fr/juice-lyrics.git@v2.0.0b1" +command -v 999 +999 --version +999 doctor +``` + +The distribution remains named `juice-wrld-lyrics` for update compatibility. +The command above installs the immutable `v2.0.0b1` tag into pipx without +depending on the source checkout after installation. If pipx already has an +older or stale copy, replace it deliberately: + +```bash +pipx install --force "git+https://github.com/NotAI-fr/juice-lyrics.git@v2.0.0b1" +hash -r +command -v 999 +999 --version +999 doctor +``` + +Repeating the `--force` command is the deterministic upgrade or reinstall path +for this beta. Installing a locally built wheel is also supported: ```bash -pipx install . +pipx install --force /absolute/path/to/juice_wrld_lyrics-2.0.0b1-py3-none-any.whl ``` +If a stale pipx registration cannot be replaced, `pipx uninstall +juice-wrld-lyrics` followed by the normal install command removes only the +isolated application environment. It does not remove 999's existing +`~/.config/juice-lyrics`, `~/.cache/juice-lyrics`, or +`~/.local/share/juice-lyrics` data. + ### Editable development install ```bash @@ -191,6 +328,56 @@ python -m venv .venv pip install -e . ``` +For development checkpoints, invoke the repository environment explicitly: + +```bash +.venv/bin/999 +``` + +If `command -v 999` points at an older pipx installation, that command will not +contain current checkout changes. Reinstall it deliberately or keep using +`.venv/bin/999`; changing the repository cannot update an installed copy. + +`juice-lyrics` remains available as a legacy compatibility command. Both names +run the same CLI. Existing config, state, queue, cache, and backups continue to +use the `juice-lyrics` XDG namespace so no data migration is required. + +### Shell completion + +Generate completion from the installed CLI after installing or updating `999`. +Generation only inspects command definitions; it does not load configuration, +state, or the catalogue. + +For Bash: + +```bash +mkdir -p ~/.local/share/bash-completion/completions +999 completion bash > ~/.local/share/bash-completion/completions/999 +``` + +Start a new Bash session (with `bash-completion` enabled), or source that file. + +For Zsh: + +```zsh +mkdir -p ~/.zfunc +999 completion zsh > ~/.zfunc/_999 +``` + +Add `fpath=(~/.zfunc $fpath)` before `autoload -Uz compinit && compinit` in +`~/.zshrc`, then start a new Zsh session. + +For Fish: + +```fish +mkdir -p ~/.config/fish/completions +999 completion fish > ~/.config/fish/completions/999.fish +``` + +Fish loads that file in new sessions. The generated definitions also support +the legacy `juice-lyrics` command. Regenerate them after a CLI upgrade so the +available commands and flags stay current. + ## Development Run the test suite with: @@ -206,23 +393,23 @@ The project includes an acquisition subsystem for explicitly selected API resour ```bash # 1. Search the catalogue and check downloadable resources -juice-lyrics acquire search "rental" +999 acquire search "rental" # 2. Queue selected item(s) by 1-based index (or use --manifest) -juice-lyrics acquire add "rental" --index 1 +999 acquire add "rental" --index 1 # 3. Queue from a plain-text manifest file -juice-lyrics acquire manifest manifest.txt +999 acquire manifest manifest.txt # 4. View queued persistent jobs -juice-lyrics acquire jobs +999 acquire jobs # 5. Run a persistent job (with automatic resume, size/hash checks, and post-processing) -juice-lyrics acquire run +999 acquire run # 6. Retry failed/pending items or delete job records -juice-lyrics acquire retry -juice-lyrics acquire delete +999 acquire retry +999 acquire delete ``` Acquisition is intentionally opt-in and operates only on explicitly selected resources. The transport downloader streams via temporary `.part` files, supports HTTP range resume, validates payload size and checksums, and integrates acquired MP3s directly with the synced/plain lyrics and rmpc workflow. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b38d2d9..6e589bc 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,9 +40,15 @@ The API layer should not know about terminal prompts, MP3 tagging, or rmpc UI. ## Library layer +The Library TUI is an orchestration frontend over the same scanner, status, +sync, verification, backup/restore, and rmpc services used by the CLI. It never +shells out to `999` and does not duplicate matching or media mutation rules. +Planning and verification are read-only; applying a reviewed plan, restoring a +backup, and configuring rmpc require explicit cancel-first confirmation. + Responsibilities: -* scan local MP3s +* scan local MP3, FLAC, and M4A files recursively * extract metadata * duration handling * fingerprints/state @@ -52,13 +58,36 @@ Responsibilities: Matching must remain version-aware, alias-aware, and duration-aware. +Local lyric health and catalogue matchability are independent axes. Coverage +uses format-aware embedded lyric verification plus an adjacent LRC that parses +to at least one timestamped lyric line. A catalogue match is required to fetch +or refresh lyrics, but is not required to recognize an already covered local +track. Ordinary TUI maintenance protects fully covered unmatched tracks; an +explicit per-track refresh may retry conservative matching without changing the +file when no safe candidate is found. + +One-button Library Sync uses `services/library_index_sync.py` as the shared +incremental orchestration boundary. It compares cheap filesystem fingerprints +to classify unchanged, new, changed, and removed current-library paths; reuses +safe snapshot/identity information for unchanged files; invalidates identity +trust when file evidence changes; and offers new, changed, and Unknown MP3, +FLAC, and M4A tracks to the normal conservative matcher. Confident identities +are atomically merged without inferring lyric-processing state. Removed paths +are retired rather than destructively deleting historical/custom state. + +The TUI runs Sync in a worker and prevents concurrent duplicate runs. Ordinary +Sync does not mutate audio, lyrics, backups, downloads, or rmpc configuration. +The older Refresh action remains a direct read-only local rescan. + ## Lyrics layer Responsibilities: * parse API LRC-style `synced_lyrics` -* produce SYLT frames -* produce USLT frames +* produce MP3 SYLT frames +* produce MP3 USLT frames +* write standard plain-text FLAC/Vorbis `LYRICS` comments +* write standard plain-text M4A/MP4 `©lyr` atoms * verify lyric frames * write `.lrc` text when synchronized lyrics exist @@ -68,12 +97,17 @@ It must never manufacture timestamps for plain lyrics. Responsibilities: -* generate `.lrc` files for synced lyrics +* generate same-basename `.lrc` sidecars beside audio for synced lyrics * locate/configure the user's rmpc config safely * preserve unrelated rmpc settings/layout/keybinds * trigger lyric re-indexing where supported * provide diagnostics +The finalized audio path is authoritative for external lyrics. Historical state, +rmpc configuration, and the deprecated `lyrics_dir` setting cannot redirect a +new write. A generated sidecar is passed to rmpc's individual-path indexing +boundary. + ## Backup layer Responsibilities: @@ -96,12 +130,26 @@ Do not hard-code a particular user's home directory. ## State layer +Catalogue identity rebuilds are explicit state-only transactions. Preview scans +the current library without API calls or writes. Apply rematches every current +track in memory, preserves non-identity fields, ignores stale external records, +backs up the complete source state, and performs one atomic replacement. A +provider-wide failure aborts; an isolated request failure preserves that +track's prior identity. + Track enough information to skip unchanged files safely. State should include a local file identity/fingerprint and enough processing information to know whether lyrics/rmpc output are current. Losing state must be recoverable: the application should be able to rescan and reconstruct it. +Exact library-relative keys are authoritative. An older basename-only key may +be read when both the local file and historical record are unambiguous; it is +not automatically duplicated or deleted. Clearly stale nonexistent absolute +external references are ignored by normal lookup and may be pruned only through +the preview-first state cleanup service, which makes a safety copy and writes +atomically. + ## Acquisition layer Responsibilities: @@ -206,6 +254,11 @@ Responsibilities: Normal user commands should be easy to remember. +The product and primary executable are named `999`. The legacy +`juice-lyrics` console script resolves to the same `juice_lyrics.cli:main` +function. The import namespace remains `juice_lyrics`, and persisted XDG paths +remain under `juice-lyrics`; branding must not create a second storage tree. + ## UI layer Long term, an interactive TUI can sit on top of the same services. @@ -221,7 +274,7 @@ Both CLI and TUI should reuse the same API, acquisition, library, and lyrics ser * duration matching * SYLT first / USLT fallback * rmpc `.lrc` generation only for synced lyrics -* backups before MP3 metadata changes +* backups before MP3, FLAC, or M4A metadata changes * verification after writes * incremental sync @@ -231,10 +284,15 @@ Acquisition owns transport and persistent job state. After a successfully acquired MP3 is written, the optional post-processing hook passes the file through the existing lyrics engine. -Synced lyrics become ID3 SYLT and an rmpc `.lrc`. +For MP3, synced lyrics become ID3 SYLT and a same-basename `.lrc` beside the audio. -Plain lyrics become ID3 USLT. +MP3 plain lyrics become ID3 USLT. FLAC embeds standard plain-text Vorbis +`LYRICS`; synchronized timing remains in the adjacent `.lrc` because Vorbis +comments have no interoperable equivalent to ID3 SYLT. M4A embeds standard +plain-text MP4 `©lyr`; its synchronized timing likewise remains in the adjacent +`.lrc`. No audio format is converted. -Non-MP3 resources remain untouched for now. +Acquisition post-processing remains MP3-only. Native FLAC and M4A support +applies to existing local-library files. Post-processing errors fail the individual job item and are persisted. diff --git a/docs/BETA_RELEASE_CHECKLIST.md b/docs/BETA_RELEASE_CHECKLIST.md new file mode 100644 index 0000000..17d88eb --- /dev/null +++ b/docs/BETA_RELEASE_CHECKLIST.md @@ -0,0 +1,283 @@ +# 999 beta release checklist + +Target: `2.0.0b1` (PEP 440) / Git tag `v2.0.0b1`. + +This checklist prepares a release; it does not authorize publishing, tagging, +or merging. `main` remains the stable v1.4 baseline until the beta is accepted. + +## Final automated release-candidate acceptance — 2026-09-25 + +This pass started from clean `v2-redesign` at `db1ef2c`, equal to +`origin/v2-redesign`. No production regression was found and no production +code changed. + +Live and isolated acceptance results: + +- A deliberately small live catalogue pass verified search, refresh parameter + handling, two distinct five-item pages with correct next/previous metadata, + and stable-ID details. The catalogue reported 2,741 records. Released Bandit + resolved to `94107`; released 10 Feet resolved to `94102` without weakening + matcher rules. +- A four-file disposable live-Sync library recorded two new paths, matched + Bandit to `94107`, kept one deliberately ambiguous healthy MP3 Unknown, and + preserved two file-bound manual locks. The exact summary was `2 new recorded + · 1 newly matched · 1 catalogue unknown`. Repeat Sync changed neither state + nor cache and reported local state up to date; a later mtime-only change was + accurately reported as `1 changed refreshed`. All health rows were warning + follow-ups (`~`), with zero genuine errors (`!`). Deterministic 503/530, + malformed JSON, empty-result, and offline regressions remain green. +- One explicitly selected Bandit item was queued and downloaded to `/tmp`. + The service streamed 8,392,557 bytes, finalized and postprocessed one MP3, + persisted the complete queue result, left no `.part`, and a retry correctly + performed no second download. Local-server regressions cover progress, + resume, 503 retry, exhausted/404/403 failures, checksum/size/content + rejection, and duplicate suppression. +- The integrated focused suite covered Sync, Library, Issues, manual lock and + unlock, Duplicates, metadata preview/apply/cancel, Missing Library, + backup/restore, Browse/Downloads, Help/navigation/quit, Doctor, and rmpc + helpers: **385 passed**. +- Temporary copies of representative real MP3, FLAC, and M4A files completed + metadata preview, confirmed apply, backup, and exact restore. Encoded media, + artwork, embedded lyrics, unrelated tags, adjacent sidecars, and manual locks + were preserved. Original file hashes, sizes, mtimes, and ctimes were unchanged. +- The isolated support report was valid JSON and an automated forbidden-value + audit found no username, absolute home/acceptance path, token/credential, + job ID, song title/list, or private state contents. Paths were redacted. +- Fresh wheel and sdist builds installed independently outside the checkout + with no `PYTHONPATH`. Both provided `999` and `juice-lyrics` at `2.0.0b1`, + help, Doctor, Bash/Zsh/Fish completion generation, and installed-package TUI + startup. In both installed harnesses `q` set the app to stopped; the external + Textual harness process itself still required a timeout during teardown. + The wheel upgrade/no-op, uninstall, command removal, reinstall, and import + lifecycle passed. Packaging/completion checks passed **34 tests** with the + understood missing-Fish skip. Artifact SHA-256 values were recorded in the + acceptance log; artifacts remain temporary and were not published. +- GitHub Verify for `db1ef2c` passed. `main` remains the private default branch; + visibility, merge, tag, release, and publication were not changed. +- Before/after manifests matched exactly for the real music tree and real + config, state/backups/queue, and cache. The global pipx installation was not + replaced. + +Release-blocker classification: + +- **BLOCKER:** none demonstrated. +- **NON-BLOCKING BETA LIMITATION:** manual visual polish was not independently + confirmed; Fish is unavailable for runtime syntax acceptance, although + deterministic generation is green; no independent second-machine pipx + tester was available. +- **OPTIONAL / POST-BETA:** rmpc and MPD executables are installed but no live + rmpc TUI socket was available. The installed rmpc accepts the query target + `activetab`, while the optional notification probe currently uses the older + `active-tab` spelling, so live notification acceptance remains unverified. + Explicit rmpc setup was not run and real player configuration was untouched. + +Candidate verdict: **READY FOR 2.0.0b1 RELEASE**. Release procedure steps, +including date/link updates, visibility decision, merge, tag, and publishing, +still require explicit authorization. + +## Real-library correctness evidence — 2026-09-24 + +This pass started from clean `v2-redesign` at `b3e740a`, equal to +`origin/v2-redesign`. The installed pipx commands were inspected only: `999` +and `juice-lyrics` both reported `2.0.0b1`; neither was replaced. + +The real library diagnostic was strictly read-only and made no catalogue +requests. Before/after SHA-256 and filesystem-metadata manifests confirmed each +diagnostic made no changes to real music, config, data (including state, +backups, and queue), or cache. Concurrent external activity added eight MP3s +during the long test run; no pre-existing music entry changed, and the final read-only +snapshot was stable. Sanitized final aggregate findings: + +- 195 readable tracks: 83 MP3, 43 FLAC, and 69 M4A; zero scan warnings, + unreadable/damaged containers, missing required title/artist metadata, + unavailable durations, or verification errors. +- 141 tracks were fully covered and 185 had no local lyric follow-up. The ten + local lyric follow-ups were nine optional unmanaged embedded lyrics and one + invalid existing LRC; none was evidence of damaged audio. +- 76 tracks had Unknown catalogue identity. State classified 121 current, 40 + new, 34 changed, and zero invalid tracks. All 76 Unknown checks were due; + none was hidden by a retry TTL or an API-unavailable marker. +- The old UI produced 76 `!` rows even though every row was warning severity + and there were zero genuine errors. + It also replaced the Sync action on new/changed Unknown tracks with manual + matching. Those misleading behaviors are fixed: warnings use `~`, `!` is + error-only, the headline separates follow-ups/errors/local lyrics/Unknown + identity, and new/changed rows retain the Sync action. +- Normal Sync can record the 74 new/changed paths and attempt 76 due Unknown + identities when the catalogue is available. It does not repair the + ten lyric/LRC conditions, modify media, or delete historical state. There + were zero explicit safe stale-state cleanup candidates among 235 stored + records. +- Offline/provider-wide 503, 530, Cloudflare tunnel, DNS, and invalid-JSON + failures now stop repeated requests for the rest of that Sync pass. Local + health remains available, pending/Unknown counts are reported, and trusted + identities and state are not erased. Ambiguous or genuinely empty searches + still remain conservatively Unknown and use the normal retry TTL. + +Focused regressions passed **141 tests**. The one required post-change full +suite passed **540 tests with one understood skip** because Fish is not +installed. `compileall` and `git diff --check` passed. + +Remaining human judgment is unchanged: visually assess the revised Library +labels/markers and keyboard flow in a normal terminal; perform an explicitly +approved temporary download; retry live 10 Feet when the provider is healthy; +review rmpc setup and a support report; preview GitHub presentation/privacy; +and obtain an independent supported-Linux pipx installation report. + +## Focused acceptance evidence — 2026-09-23 + +Automation is appropriate for repository/version checks, guarded test suites, +isolated builds and installs, generated completion syntax, generated media +fixtures, read-only live catalogue requests, queue creation that does not run a +download, and before/after integrity manifests. Human involvement remains +required for visual/keyboard UX judgment, an actual explicitly approved +temporary download, GitHub rendering and privacy review, local rmpc setup, +support-report disclosure review, repository visibility, and an independent +pipx tester. + +Verified in this pass: + +- Starting point was clean `v2-redesign` at `55b4b4b`, equal to + `origin/v2-redesign`. The existing pipx commands at + `~/.local/share/pipx/venvs/juice-wrld-lyrics/bin/` were inspected only; both + reported `999 2.0.0b1` and were not replaced. +- Live `999 search Bandit --refresh` returned the released recording as + `94107`. A live isolated acquisition search and queue add created one pending + job under `/tmp` and no media file. This exposed and fixed incorrect + positional forwarding of acquisition `--refresh`, which had sent + `page=True` and received HTTP 404. +- The isolated focused workflow pass covered Browse/Downloads, confirmed + whole-queue control flow with non-network executors, Sync new/changed/ + unchanged/removed/offline behavior, manual locks, Issues, Duplicates, + Missing Library, MP3/FLAC/M4A metadata repair, backup/restore, and the + Bandit/10 Feet matcher regressions: **256 passed**. +- The post-fix full suite passed **534 tests with one understood skip** because + Fish is not installed. `compileall` and `git diff --check` passed. +- Fresh wheel and sdist builds were inspected and installed independently + outside the checkout. Both commands, help/version, Doctor, imports, + Bash/Zsh/Fish completion generation, Bash/Zsh syntax, and wheel + force-reinstall/uninstall/reinstall passed. Fish syntax and independent + artifact `q` exit still need an installed Fish shell/manual terminal check. +- Both artifact TUIs visibly launched against empty temporary libraries. The + automated suite covers normal launch/quit, but this pass's PTY harness could + not reliably inject `q`; manual launch/navigation/exit remains below. +- The synthetic screenshot was visually inspected and searched for embedded + sensitive strings; it contains only synthetic counts and `Music/Juice WRLD`. + Artifact contents contain the license, README, metadata, and runtime modules + with no tests, docs, caches, bytecode, secrets, or checkout paths. +- Before/after manifests confirmed no change to `/home/nobloat/Music` or the + real `juice-lyrics` config, data (including state/backups/queue), or cache. + +Remaining manual acceptance: + +- Run the installed app in a normal terminal and judge Help, navigation, + pagination/details, queue/Retry, confirmed temporary download, and quit. +- Retry live `10 Feet` identification and confirm `94102`; two requests in this + pass received HTTP 530, while the deterministic matcher regression passed. +- Exercise the Library workflows below on user-approved disposable copies, + including one representative MP3, FLAC, and M4A plus a visible restore. +- Review rmpc verify/setup separately, inspect a support report before sharing, + preview README links/image on GitHub, decide repository visibility, and get + an independent supported-Linux pipx install/upgrade report. + +## 1. Repository and metadata + +- [ ] `v2-redesign` is clean, pushed, and reviewed against `main`. +- [x] `juice_lyrics.__version__`, `999 --version`, wheel metadata, and the + changelog all say `2.0.0b1`. +- [x] The changelog heading has the actual release date instead of + `Unreleased`. +- [x] README installation commands point to the intended immutable tag or + attached wheel, not the moving development branch. Before any package- + index publication, give its long description an immutable public image + URL or omit the screenshot there. +- [x] The synthetic screenshot contains no username, home path, token, state, + song list, or real-library data. +- [x] Distribution contents contain the license, README, metadata, and every + runtime module, with no tests, caches, secrets, or checkout paths. + +## 2. Automated release candidate checks + +Run from a clean checkout with isolated build and application paths: + +```bash +pytest -q +python -m compileall -q src +git diff --check +python -m build +``` + +- [x] Full test suite passes with only understood environment skips. +- [x] Wheel and sdist install independently in new environments outside the + checkout, with no source tree on `PYTHONPATH`. +- [x] `999 --help`, `999 --version`, `juice-lyrics --version`, and + `999 doctor` work from both artifacts. +- [x] TUI launches from both artifacts and `q` transitions each installed app + to stopped; manual visual polish and the harness teardown limitation are + documented above. +- [x] Bash/Zsh/Fish completion generation succeeds; syntax is checked where + the shell is installed. +- [x] Force-reinstall, uninstall, and reinstall leave the commands and imports + in the expected state without touching application XDG data. +- [x] The GitHub `Verify` workflow passes on supported oldest/current Python + versions for the release pull request. + +## 3. GitHub presentation settings + +- [x] Keep `main` as the default/stable branch until the beta pull request is + approved; do not point normal users at an unreviewed branch. +- [x] Set the repository description to “999 — a cautious Juice WRLD library + and lyrics TUI for Linux”. +- [x] Add concise topics such as `linux`, `python`, `tui`, `music-library`, + `lyrics`, `mpd`, and `rmpc`. +- [x] Confirm Issues are enabled and the repository license is detected as MIT. +- [ ] Decide explicitly when the currently private repository should become + public; do not change visibility as a side effect of release prep. +- [ ] Preview README links and the synthetic screenshot on GitHub before merge. + +## 4. Beta acceptance + +Use an explicit backup and a small temporary copy of representative media +before testing any mutating workflow. + +- [x] Launch, Help, navigation, Browse search/pagination/details, queue Add, + Downloads, Retry, and confirmed Download queue work. +- [x] Sync Library handles unchanged/new/changed/removed files and remains + usable offline. +- [x] Bandit identifies as `94107`; 10 Feet identifies as `94102`. +- [x] Manual match/lock, unlock, Issues, Duplicates, and Missing Library behave + as documented. +- [x] One copied MP3, FLAC, and M4A completes metadata preview/apply with its + audio payload, artwork, lyrics, unrelated tags, sidecar, backup, and lock + verified. +- [x] Restore succeeds from a generated backup and does not delete the backup. +- [ ] rmpc verify works when installed; explicit setup is reviewed separately. +- [x] `999 doctor --support-report` passes an automated forbidden-value privacy + audit; review the particular report again before attaching it publicly. +- [ ] A beta tester confirms clean pipx install and upgrade on the supported + Linux environment. + +## 5. Release procedure — only after explicit approval + +1. Open and review a pull request from `v2-redesign` into `main`. +2. Resolve acceptance findings on `v2-redesign`; rerun the checks above. +3. Update the changelog date and replace moving-branch install examples with + `v2.0.0b1` release/tag instructions. +4. Merge without rewriting published history. +5. Create the annotated tag `v2.0.0b1` on the accepted merge commit. +6. Build artifacts from a clean checkout of that tag and record SHA-256 sums. +7. Create a GitHub **pre-release**, paste the changelog section, and attach the + wheel, sdist, and checksum file. +8. Install once from the attached wheel and run `999 doctor` before announcing + the beta. + +Package-index publication is a separate explicit decision. Do not upload to +PyPI merely because GitHub artifacts exist. + +## 6. Stop/rollback conditions + +Do not release if tests fail, artifact versions disagree, generated packages +depend on the checkout, privacy review fails, or a mutating acceptance test +cannot prove backup and preservation behavior. Fix on `v2-redesign`; do not +move an existing tag. If a published beta is defective, document it and issue +a new prerelease version rather than replacing its artifacts silently. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 9256537..616832e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,47 +1,78 @@ # Changelog -## Unreleased — 2026-08-25 - -### Live API path resolution and backend polish - -* Resolved live Juice WRLD API `path` resources into authorized download URLs (`/files/download/?path=...`) with correct URL encoding and destination filename extraction. -* Preserved default HTTPS security policy with opt-in HTTP fallback. -* Fixed CLI `Settings` vs `Path` regression in `library.scanner.find_mp3s()`, restoring stability across `status`, `setup`, `sync`, `scan`, `embed`, `verify`, and `rmpc` commands. -* Fixed safe era metadata formatting in `search` and `info` commands. -* Added multi-index selection (`--index 1,2,4`), manifest-based bulk acquisition (`acquire manifest`), retry (`acquire retry`), and job deletion (`acquire delete`). -* Verified end-to-end live API acquisition and CLI workflows. -* Reached 80 automated unit and integration tests passing. - -### Existing acquisition milestones - -* Added the acquisition resource resolver for explicitly selected resources. -* Added HTTPS-by-default URL validation and safe destination filename handling. -* Added propagation/validation of expected size and SHA-256 metadata. -* Added acquisition resolver tests; the project test suite then passed 11 tests. -* Added duplicate detection for existing resources using checksum, safe destination checks, and title/version matching; the project test suite then passed 15 tests. -* Added persistent acquisition jobs backed by atomic JSON saves, per-item progress/state, job listing/lookup/deletion, and recovery of interrupted transient states; the project test suite then passed 20 tests. -* Added a conservative sequential acquisition job runner. -* Added duplicate checks before download, atomic per-item persistence, progress callbacks, and failure isolation. -* Added runner tests; the project test suite then passed 23 tests. -* Added the first integrated acquisition CLI workflow: `acquire search`, `acquire add`, `acquire jobs`, and `acquire run`. -* Acquisition does not silently crawl the catalogue. -* Added CLI workflow tests; the project test suite then passed 26 tests. -* Added post-download integration for acquired MP3s. -* Reused the established synced/plain lyric embedding and verification pipeline. -* Generated rmpc-compatible `.lrc` files for acquired files with synced lyrics. -* Post-processing failures are persisted as job failures. - -## Unreleased — Architecture - -* Began separating reusable engine code from the CLI entrypoint. -* Added dedicated API, library matching/scanning, lyrics, rmpc, backup, config, and state modules. -* Kept existing CLI commands compatible through adapters. - -## Unreleased — Acquisition foundation - -* Added an isolated `acquisition/` package. -* Added acquisition item/result/state models. -* Added explicit-selection manifests. -* Added a generic HTTPS downloader with temporary `.part` files, retries, optional resume, size/checksum validation, maximum-size protection, and atomic finalization. -* Added acquisition foundation tests. -* Kept acquisition transport independent from lyrics/rmpc post-processing. +This project follows [Semantic Versioning](https://semver.org/) and uses PEP +440-compatible Python versions. Dates are added only when a release is +published. + +## [2.0.0b1] - 2026-09-25 + +This is the first beta release of the redesigned `999` product. + +### User experience + +- Made `999` the primary command while retaining `juice-lyrics` as a legacy + alias and preserving the existing `juice-lyrics` XDG data namespace. +- Added the keyboard-first Textual interface for Dashboard, Browse, Library, + Downloads, and Settings, with global Help and consistent confirmations. +- Made **Sync Library** the routine one-button Library workflow and added + focused Issues, Duplicates, Missing Library, backup/restore, manual match, + and metadata-repair views. + +### Library and lyrics + +- Added native recursive MP3, FLAC, and M4A discovery and format-aware + metadata, lyric, status, backup, restore, and verification behavior. +- Standardized synchronized external lyrics as atomic adjacent + same-basename `.lrc` files. No audio conversion or centralized lyric output + occurs. +- Added conservative catalogue backfill, manual identity locks, explicit + identity rebuild, stale-state cleanup, and regression coverage for Bandit + (`94107`) and 10 Feet (`94102`). +- Added transactional metadata repair for selected fields with backup, + preservation checks, state-conflict protection, rollback, and post-edit + manual-lock rebinding. + +### Downloads and integration + +- Added explicit catalogue browsing, a durable download queue, safe resume, + response/size/checksum validation, retry, and post-processing. +- Kept queue addition separate from confirmed download execution. +- Added optional rmpc verification/setup and sidecar notification without + rewriting rmpc configuration during normal startup or Library Sync. + +### Operations and distribution + +- Added bounded read-only `999 doctor` diagnostics with an optional sanitized + support report. +- Added generated Bash, Zsh, and Fish completion from the actual CLI tree. +- Added deterministic wheel/sdist contents and clean-install acceptance for + both console scripts without depending on the source checkout. +- Added incremental snapshot reuse and state-safety checks to avoid redundant + hashing, metadata reads, API searches, and state writes. + +### Compatibility and limitations + +- Existing configuration, state, cache, backups, queue, and history remain in + the `juice-lyrics` XDG namespace; no automatic migration is required. +- Acquisition/post-processing remains MP3-focused. FLAC and M4A support is for + existing local-library files. +- Active download cancellation is not included in this beta candidate. + +## [1.4.0] - 2026-08-25 + +### Backend and acquisition baseline + +- Resolved live Juice WRLD API path resources into authorized download URLs + with correct encoding and filename extraction. +- Preserved HTTPS-by-default transport with explicit HTTP fallback. +- Added safe catalogue search/info commands, multi-index and manifest queueing, + persistent acquisition jobs, sequential execution, retry, and deletion. +- Added `.part` downloads, resume, size/checksum validation, maximum-size + protection, destination checks, and atomic finalization. +- Added MP3 lyric post-processing with ID3 SYLT/USLT and rmpc-compatible LRC + generation. +- Established the initial API, scanner, matching, lyrics, rmpc, backup, + configuration, state, and acquisition service boundaries. + +[2.0.0b1]: https://github.com/NotAI-fr/juice-lyrics/releases/tag/v2.0.0b1 +[1.4.0]: https://github.com/NotAI-fr/juice-lyrics/releases/tag/v1.4.0-backend-complete diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..92e30d6 --- /dev/null +++ b/docs/DECISIONS.md @@ -0,0 +1,239 @@ +# Project Decisions + +This document records important architectural and product decisions. + +The purpose is to prevent future redesigns from accidentally removing important behaviour. + +--- + +# Lyrics Architecture + +## Embedded lyrics remain supported + +The application should preserve lyrics inside MP3, FLAC, and M4A files when possible. + +Reasons: + +- Embedded lyrics travel with the file. +- Android music players commonly support embedded ID3 lyrics. +- Users may move files between devices. +- The MP3 should remain self-contained. + +Supported embedded formats: + +- ID3 SYLT: + - Synchronized lyrics with timestamps. + - Preferred when synced lyrics are available. + +- ID3 USLT: + - Plain unsynchronized lyrics. + - Used when only normal text lyrics are available. + +- FLAC Vorbis `LYRICS`: + - Standard plain-text embedded lyrics. + - Used for plain lyrics and as a plain-text representation when synchronized + source lyrics are available. + - FLAC has no sane interoperable equivalent to ID3 SYLT. Timing is not + invented or stored in a proprietary comment; the adjacent `.lrc` is authoritative. + +- M4A/MP4 `©lyr`: + - Standard plain-text embedded lyrics. + - Used for plain lyrics and as a plain-text representation when synchronized + source lyrics are available. + - M4A has no interoperable equivalent to ID3 SYLT. Timing remains in the + adjacent `.lrc`, not in a proprietary MP4 atom. + +--- + +# LRC Files and rmpc + +rmpc does not read embedded ID3 lyrics. + +rmpc currently relies on external `.lrc` lyric files. + +Audio and external synchronized lyrics stay together. Every LRC destination is +derived from the finalized audio path (`song.mp3`, `song.flac`, or `song.m4a` -> `song.lrc`) rather than a +global directory, title metadata, historical state, or rmpc configuration. +Read-only operations and plans create nothing. LRC writes generate complete +content first and atomically replace the adjacent sidecar where practical. + +The old `lyrics_dir` setting remains accepted for configuration compatibility, +but is deprecated and does not direct current output. Existing centralized LRC +files are not moved automatically; migration remains a separate explicit task. + +Therefore: + +- SYLT lyrics should generate `.lrc` files. +- USLT-only lyrics should remain embedded but cannot produce valid `.lrc` files. + +Reason: + +An LRC file requires timestamped lines. + +Example: + + +[00:12.00] First lyric line +[00:15.00] Second lyric line + + +Plain lyrics do not contain timing information. + +The application must never invent timestamps to make LRC files. + +--- + +# Lyrics Priority + +The lyric pipeline should behave like this: + +API synced lyrics + | + v +Embed SYLT + | + v +Generate LRC for rmpc + + +API plain lyrics only + | + v +Embed USLT + | + v +No LRC generated + +--- + +# Player Choice + +rmpc remains the preferred desktop player integration. + +Reasons: + +- Lightweight. +- Fast. +- Terminal UI fits the Linux workflow. +- Highly configurable. +- Works well with custom Linux setups. + +The application should support rmpc without making it the only playback target. + +--- + +# UX Principle + +Technical details should not leak unnecessarily to users. + +Avoid showing: + +- SYLT +- USLT +- job UUIDs +- internal API terminology + +Prefer: + +- Synced Lyrics +- Plain Lyrics +- Downloads +- Queue +- Library + +## Downloads are a track queue + +Persistent acquisition jobs remain the durable backend mechanism for +resumability, validation, recovery, and CLI compatibility. They are not the +normal user-facing model. Frontends present one flat download queue containing +individual songs and hide job UUIDs from ordinary workflows. + +Completed entries remain in durable storage but do not clutter the active +queue. Failed entries remain visible and actionable until a future retry or +remove action resolves them. Internal references may appear only in an advanced +troubleshooting detail. + +Adding to the queue, Download selected, Retry, Remove, and completed-history +cleanup are immediate because they are explicit or record-only actions. +Sequential Download queue and bulk waiting/failed cleanup retain cancel-first +confirmation. Active download cancellation remains unimplemented. + +Browse selection is an in-memory set keyed by stable catalogue song ID. Marks +may span pages only within one logical search and are cleared when the search or +server-side filters change. Batch Add revalidates queue and destination +duplicates immediately before one atomic persistent write; it never starts a +download. Durable acquisition jobs remain hidden behind this song-oriented +operation. + +The backend can remain technical while the user interface becomes friendly. + +## Catalogue identity and state cleanup + +Catalogue identity is stored in the existing state file but is not a prerequisite +for recognizing healthy local lyrics. One-button Library Sync may backfill a +confident identity through the normal matcher; it must not manufacture lyric +state or change media. Clearly stale external state records are ignored during +normal lookup and deleted only by an explicit preview-first cleanup that makes a +state backup. Legitimate historical relative keys are not speculatively +deduplicated. + +Normal Sync is safe routine work and therefore starts immediately. It detects +unchanged, new, changed, and removed current-library paths, avoids expensive +work for unchanged files, retires removed paths without deleting historical +records, and cannot run twice concurrently. It never rewrites audio, lyrics, +backups, downloads, or rmpc configuration. + +A full catalogue-identity rebuild is an explicit recovery operation, not a +library reset. It removes/replaces only `song_id` and `api_name` for current +tracks after rerunning the conservative matcher. Preview is read-only; apply +builds the result in memory, preserves isolated-failure identities, creates a +complete state backup, and performs one atomic state write. Stale and +non-current historical records are not deleted by the rebuild. + +An explicit manual catalogue choice is stored with `identity_source = +"manual"` and `identity_locked = true`, tied to the current file hash. +Automatic operations preserve a valid lock. Changed/replaced audio invalidates +it; ordinary rebuild preserves it; only the advanced `--include-locked` +rebuild option may override it. Unlocking clears identity/provenance fields so a +later Sync can reconsider the track, while lyric and custom state survive. + +Duration remains a primary matching safeguard. The configured tolerance is the +normal trusted range. A small catalogue-duration discrepancy is eligible only +for a normal released candidate with exact base title, no extra version or +named variant, and exact or recognized-edition-compatible album/path evidence. +The grace is bounded to two seconds beyond configured tolerance, five seconds +absolute, and two percent of local duration, and carries a score penalty. + +--- + +# Backend Stability + +The current modular backend should be preserved. + +Major systems: + +- API client +- lyrics engine +- acquisition system +- downloader +- library matching +- rmpc integration +- backup system + +Future redesigns should build on these systems rather than replacing them. + +--- + +# Product Identity and Compatibility + +- Product name: `999` +- Primary executable: `999` +- Legacy compatibility executable: `juice-lyrics` +- Python package: `juice_lyrics` +- Distribution name: `juice-wrld-lyrics` +- XDG storage namespace: `juice-lyrics` + +Both executable names call the same CLI implementation. Existing configuration, +cache, state, queue records, and backups are not renamed or duplicated. Normal +startup never rewrites rmpc configuration. Only explicit `999 rmpc setup` or +the cancel-first **Library → Player → Set up rmpc** action may do that. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 6e423e1..0b40380 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -2,7 +2,9 @@ ## Baseline -The 1.4.0 release is the known-good functional baseline. +The `main` branch and `v1.4.0-backend-complete` tag are the stable v1.4 +baseline. Development of the redesigned product remains on `v2-redesign`; its +current unreleased beta candidate version is `2.0.0b1`. Run: @@ -16,9 +18,9 @@ The baseline test suite includes core parsing and rmpc configuration/LRC checks. Read: -1. `PROJECT_CONTEXT.md` -2. `docs/ROADMAP.md` -3. `docs/ARCHITECTURE.md` +1. `AGENTS.md` +2. `docs/PROJECT_STATE.md` +3. the relevant architecture, decision, or user document Then inspect the current implementation and tests. @@ -48,16 +50,126 @@ New components should receive focused tests before being integrated into the mai ## Packaging -The project uses `pyproject.toml` and exposes the `juice-lyrics` console script. +The project uses `pyproject.toml` and exposes `999` as its primary console +script. `juice-lyrics` is a legacy compatibility alias; both entry points call +`juice_lyrics.cli:main`. + +The distribution remains `juice-wrld-lyrics`, the import package remains +`juice_lyrics`, and XDG storage remains under `juice-lyrics` for compatibility. Keep the runtime dependency set small. -## Source of truth and Git workflow +### Experimental Textual interface + +From the repository's editable installation, launch the TUI with: + +```bash +.venv/bin/999 +``` -The latest transferred project checkpoint/archive is the source of truth for ongoing development. The existing GitHub repository is not authoritative and should not be used as the development baseline. +Use `command -v 999` before manual regression testing. A separately +installed pipx copy is a frozen package snapshot and does not follow this working +tree; reinstall it deliberately after a checkpoint or use the explicit `.venv` +command above. -When version control is introduced, create a fresh repository from a known-good checkpoint and make logical milestones so changes can be inspected or reverted independently. The user should be given copy/paste instructions rather than being expected to understand Git internals. +For a deterministic pipx installation that does not depend on the checkout +after installation: -## Checkpoint workflow +```bash +pipx install --force "git+https://github.com/NotAI-fr/juice-lyrics.git@v2-redesign" +hash -r +command -v 999 +999 --version +999 doctor +``` + +Use `pip install -e .` inside `.venv` for development. A local wheel can be +tested or installed with `pipx install --force /absolute/path/to/wheel.whl`. +Build release artifacts with `python -m build`; both the wheel and source +distribution must be clean-installed outside the repository before release. + +The terminal interface provides functional Dashboard, Browse, Library, +Downloads, and Settings screens. Its primary journey is **Browse → Add → +Downloads → Download queue**. Browse supports both direct single-song Add and +optional batch selection; Downloads makes `A` Download queue primary and keeps +individual download, Retry, and cleanup actions in Help. Press `/` to focus catalogue search and Enter to +submit. Category and Era are keyboard-usable selectors populated from API +metadata; choose All for no filter. Filter-only searches are supported. Results +use the API's 50-song pages and show a permanently visible page, range, and +total bar. Use `n` for the next API page and `p` for the previous one. Arrows or +`j`/`k` move one result, PageDown/PageUp move through the loaded page, and +Home/End select its first/last result. The list scrolls to keep that selection +visible. Enter loads full details and a lyric preview, while `r` refreshes the +current API page. Space marks or unmarks the highlighted result, `M` toggles all +downloadable songs on the current page, and `u` clears the marks. Marks may span +pages of the same search; changing the title, Category, or Era clears them. +Press `a` to add the marked songs, or the highlighted song when none are +marked. Addition is immediate, reports eligible/skipped songs, and does not +start a download. Global keys remain `1`–`5` for +sections, `?` for help, and `q` to quit. Browse does not run downloads, sync +lyrics, edit settings, or modify the local library. +It uses Textual's ANSI-color mode and ANSI palette names rather than a bundled +theme. Exact terminal-background transparency can still vary with Textual's +alternate-screen rendering and the terminal emulator. + +In Downloads, press `A` to download the eligible waiting queue sequentially. +Use arrows or `j`/`k` to select an individual queued song, +Home/End for the first or last song, and PageUp/PageDown for longer queues. +Enter opens track details and Escape returns to the queue. Press `r` to refresh. +Completed backend records are counted but hidden from the active queue; failed +songs remain visible. Press `d` to start the explicitly selected queued song; +the whole-queue `A` action remains cancel-first. The runner uses the existing +download, validation, lyric, LRC, state, backup, and rmpc pipeline. Press `t` +on a failed song to retry it immediately. A verified +finalized file may reuse the existing media safely; otherwise the downloader +resume/redownload path is used. Active-download cancellation remains unavailable. +Use `x` to remove a waiting/failed song, `c` to clear waiting and failed songs, +and `H` to clear completed history. These record-only actions never delete +downloaded music or lyrics; active downloads cannot be cancelled yet. +Failed and active entries are skipped and remain available for their explicit +actions. The one-line footer advertises only the primary action and context; +`?` keeps Remove, Clear, history cleanup, Refresh, and Retry discoverable +without making the normal workflow look like queue administration. + +In Library, arrows or `j`/`k` select local MP3, FLAC, and M4A tracks, Home/End select the first +or last track, and PageUp/PageDown move through longer lists. Press `/` for a +local title/filename search and use the Status selector for Matched, Unmatched, +Synced lyrics, Plain lyrics, No lyrics, or Needs attention. These filters operate +on the loaded snapshot and do not contact the catalogue API or rescan files. +Press Enter for track details in narrow terminals, Escape to return, and `r` to +refresh the read-only snapshot. Press `s` explicitly to generate an API-backed +sync plan. It is a preview only: no audio, state, backup, LRC, configuration, or +rmpc changes are made. The existing API cache may be updated by that explicit +preview. Actual library sync remains CLI-only via `999 sync`. The +scanner recursively supports MP3, FLAC, and M4A. FLAC and M4A matching reads +native title, artist, album, and duration metadata and conservatively leaves +tracks with missing title or artist metadata unmatched. + +In Settings, the Music folder, Download folder, sidecar lyric behavior, and rmpc status are +shown before the Advanced configuration, provenance, cache, and state details. +Arrows or `j`/`k` inspect values; Home/End and PageUp/PageDown navigate longer content. +The view reports the active config file, reliable default/config/runtime source +labels, that external lyrics live beside each song, path existence, and whether +rmpc indexes the music tree containing those sidecars. Press `r` +to refresh. The screen is strictly read-only: configuration changes and setup +remain CLI-only, and no missing XDG paths are created. + +External synchronized LRC files use the finalized audio path: `song.mp3`, +`song.flac`, and `song.m4a` map to `song.lrc` in the same directory. Content is generated before an atomic replace, +and read-only inspection or planning creates nothing. The legacy `lyrics_dir` +setting remains parseable but cannot redirect current output; neither historical +state nor rmpc configuration is an output-path authority. Existing centralized +files are not migrated by the application. + +FLAC and M4A files are never converted. Mutagen writes standard plain-text +Vorbis `LYRICS` for FLAC and MP4 `©lyr` for M4A while preserving unrelated +metadata and the audio stream. Synchronized timing is kept in the adjacent LRC +because neither container provides an interoperable SYLT equivalent. Backups +and restore support MP3, FLAC, and M4A. + +## Source of truth and Git workflow -Development checkpoints are distributed as source ZIPs. When applying one to a local Git checkout, keep `.git/` untouched, run the test suite, then commit the result as a single logical milestone. +The `v2-redesign` branch in this repository is the active development source +of truth. Keep milestones inspectable, run the documented verification, and +push completed work to `origin/v2-redesign`. Do not merge into `main`, tag, or +publish a distribution as part of an ordinary development milestone. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md new file mode 100644 index 0000000..15e2759 --- /dev/null +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -0,0 +1,33 @@ +# 999 v2 continuity brief + +This file is retained for old links and session prompts. It is no longer a +second full project-history document. + +Use this handoff order: + +1. `../AGENTS.md` — concise operating and safety instructions +2. `PROJECT_STATE.md` — canonical current checkpoint and roadmap +3. `../PROJECT_CONTEXT.md` — durable user/product context +4. Relevant design documents in `docs/` + +## Current checkpoint + +`999` is a Linux terminal music hub on branch `v2-redesign`. The primary +executable is `999`; `juice-lyrics` remains a compatibility alias, the Python +package remains `juice_lyrics`, and XDG data remains under `juice-lyrics`. + +At commit `31ebaf2 Add one-button Library Sync`, MP3/FLAC/M4A local-library +support, adjacent LRC architecture, catalogue browsing/matching, downloads, +backups/restore, rmpc integration, the five-section TUI, Help/confirmation +polish, identity rebuild/state cleanup, performance safeguards, and one-button +incremental Library Sync are integrated. That checkpoint passed 410 tests plus +14 isolated recovery smoke tests, compileall, and `git diff --check`. + +The normal Library action is `s` → **Sync Library**. It detects unchanged, new, +changed, and removed files; avoids redundant work for unchanged files; safely +backfills confident Unknown identities; retires removed entries; stays usable +offline; and does not modify audio, lyrics, backups, downloads, or rmpc config. + +The next roadmap item is manual catalogue matching with an explicit identity +lock. The complete ordered roadmap, known limitations, safety invariants, and +resume commands are maintained only in `PROJECT_STATE.md`. diff --git a/docs/METADATA_REPAIR_DESIGN.md b/docs/METADATA_REPAIR_DESIGN.md new file mode 100644 index 0000000..d96aa5d --- /dev/null +++ b/docs/METADATA_REPAIR_DESIGN.md @@ -0,0 +1,94 @@ +# Metadata repair safety design + +The Library UI now exposes the backend transaction in +`services/metadata_repair.py` for MP3, FLAC, and M4A through explicit per-field +selection and a cancel-first confirmation. Nothing is selected by default and +the write runs in a guarded background worker. + +## Evidence and user decision + +- Repairs require a current, confirmed catalogue identity. Unknown tracks never + receive guessed values. +- Missing local fields backed by explicit catalogue data may be marked + **Confident**. A difference from an existing non-empty value is **Review** and + must be selected explicitly by the user. +- Recording/version markers remain meaningful. Live, remix, session, extended, + TV mix, numbered versions, and similar distinctions must not be flattened. +- The apply plan must pin the audio path, pre-edit whole-file SHA-256 and + filesystem fingerprint, catalogue ID, selected fields, identity provenance, + and state-file signature shown in the preview. + +## Format-specific writes + +Only the selected common text fields should change: + +- MP3: `TIT2`, `TPE1`, `TALB`, and `TRCK` ID3 frames. +- FLAC: `TITLE`, `ARTIST`, `ALBUM`, and `TRACKNUMBER` Vorbis comments. +- M4A: `©nam`, `©ART`, `©alb`, and `trkn` MP4 atoms. + +The writer must preserve the encoded audio stream and every unrelated tag. In +particular it must round-trip MP3 USLT/SYLT/APIC, FLAC `LYRICS` and pictures, +M4A `©lyr` and cover art, custom/free-form tags, and unknown metadata. Adjacent +`.lrc` files are outside the transaction and must remain byte-identical. + +## Transaction and recovery + +1. Re-read state and the source fingerprint/hash; abort if either differs from + the preview. +2. Create the normal complete audio backup before any original-file mutation. +3. Copy to a same-filesystem temporary file, update only approved fields, and + save/fsync the temporary copy. +4. Re-open the temporary copy and verify the requested tags, media readability, + audio-stream identity where measurable, embedded lyrics, artwork, and all + unrelated tags. +5. Recheck source and state conflict guards, then atomically replace the audio. +6. Compute and verify the new whole-file SHA-256/fingerprint and atomically bind + state to that result. If this final state update conflicts or fails, restore + and verify the backed-up original rather than leaving state and media split. +7. Keep the backup under the existing newest-10-valid retention policy. Clean + abandoned temporary files safely after interruption; never treat them as + library audio. + +No state should record a post-edit hash until the replacement has been verified. +No success should be reported until both media and state agree. + +The implemented service requires an explicit subset of previewed fields and an +explicit `confirmed=True` execution gate. It pins the original state bytes, +whole-file hash/fingerprint, catalogue ID, unrelated tag snapshot, encoded +media payload hash, and adjacent-sidecar signature. It creates and manifests a +normal backup before editing a same-filesystem temporary copy. The copy is +reopened and verified before atomic replacement; state failure rolls the audio +back. Tests also cover interruptions immediately after media/state replacement. + +## Manual identity locks + +A controlled metadata edit necessarily changes the whole-file SHA-256. A valid +manual identity lock may be rebound to the new hash only when all of these are +true: + +- the pre-edit hash/fingerprint still matches the lock and preview; +- the catalogue ID is unchanged; +- only explicitly approved metadata fields changed; +- post-write media/tag/preservation verification passed; and +- the atomic state update succeeded without a conflict. + +Any unexpected file change, identity change, verification failure, interruption, +or state conflict must preserve/restore the original binding rather than weaken +the normal changed-file safety rules. + +## Implemented UI integration + +- The preview separates Confident and Review proposals and shows each original + and proposed value. No field is preselected. +- Apply is unavailable with zero selections. Its confirmation lists the exact + fields and backup behavior, starts on Cancel, and cannot submit twice. +- Execution runs off the UI thread. Success reports the backup and refreshes + Library health/Issues; failure distinguishes safe failure from rollback + failure requiring recovery. +- Generated MP3, FLAC, and M4A fixtures exercise audio, artwork, embedded lyric, + custom-tag, sidecar, backup, interruption, conflict, and rollback guarantees. +- Isolated temporary copies of representative real MP3, FLAC, and M4A files + passed the same preservation checks and an injected state-write rollback. + The audit added explicit preservation for unselected ID3v1 fields and unique + backup roots for rapid independent repairs. Originals were hash/stat checked + before and after and were unchanged. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md new file mode 100644 index 0000000..4eef66e --- /dev/null +++ b/docs/PROJECT_STATE.md @@ -0,0 +1,551 @@ +# 999 project state + +This is the canonical detailed handoff for the current application. One-button +Sync, manual catalogue locking, snapshot-backed Library Issues, read-only +duplicate review, and safe metadata repair are integrated. Read the +code and tests if a later working tree disagrees with this document. + +## Repository checkpoint + +- Repository: `/home/nobloat/Downloads/juice-lyrics-codex` +- Active development branch: `v2-redesign` +- Stable pre-redesign branch/tag: `main` / `v1.4.0-backend-complete` +- Product/primary executable: `999` +- Compatibility executable: `juice-lyrics` +- Python package: `juice_lyrics` +- Distribution: `juice-wrld-lyrics` +- XDG storage namespace: `juice-lyrics` +- Unreleased beta candidate: `2.0.0b1` (no release or tag yet) +- One-button Sync baseline: `31ebaf2` (410 tests plus 14 isolated recovery + smoke tests, compileall, and `git diff --check`). +- Manual identity-lock milestone verification: 424 full-suite tests and 34 + explicit temporary-HOME/XDG identity/state smoke tests passed; compileall and + `git diff --check` passed. +- Library Issues milestone verification: 435 full-suite tests and 30 explicit + temporary-HOME/XDG Issues/Sync/identity smoke tests passed; compileall and + `git diff --check` passed. +- Duplicate detector milestone verification: 453 full-suite tests and 45 + explicit temporary-HOME/XDG duplicate/status/Sync smoke tests passed; + compileall and `git diff --check` passed. +- Metadata audit/preview milestone verification: 470 full-suite tests and 50 + explicit temporary-HOME/XDG metadata/status/identity/Sync smoke tests passed; + compileall and `git diff --check` passed. +- Metadata safe-apply foundation verification: 486 full-suite tests, 158 + affected regression tests, and 51 explicit temporary-HOME/XDG + repair/audit/identity/Sync smoke tests passed; compileall and + `git diff --check` passed. +- Metadata safe-TUI-apply verification: 492 full-suite tests, 156 affected + regression tests, and 51 explicit temporary-HOME/XDG + repair/audit/identity/Sync smoke tests passed; compileall and + `git diff --check` passed. +- Metadata real-copy acceptance used isolated copies of representative MP3, + FLAC, and M4A files with embedded lyrics/artwork/unrelated tags and adjacent + sidecars. Three repairs plus an injected post-replacement state-write + rollback passed without changing the originals. The audit found and fixed + ID3v1 false rejection/comment loss and same-second backup-directory reuse. + Post-fix verification: 81 affected tests, 33 final targeted tests, and 494 + full-suite tests passed; compileall and `git diff --check` passed. +- Missing Library milestone verification: 108 focused catalogue/queue/Library + tests, 502 full-suite tests, and 35 explicit temporary-HOME/XDG + snapshot/Sync smoke tests passed; compileall and `git diff --check` passed. +- Doctor milestone verification: 47 focused CLI/diagnostic/state/cache/rmpc/ + backup tests, 510 full-suite tests, and 24 explicit temporary-HOME/XDG + diagnostic/settings smoke tests passed; compileall and `git diff --check` + passed. +- Shell-completion milestone verification: 20 focused completion/identity + tests passed (one Fish syntax check skipped because Fish was not installed), + 523 full-suite tests passed with the same skip, and an explicit temporary- + HOME/XDG generation smoke created no application directories. Bash and Zsh + syntax checks, compileall, and `git diff --check` passed. +- Final performance/reliability acceptance: 276 broad workflow tests and 29 + focused repair/Sync/lock/Issues regressions passed; the final suite passed + 527 tests with one Fish-environment skip. All pytest paths used the guarded + temporary HOME/XDG environment; compileall and `git diff --check` passed. +- Packaging and clean-install acceptance: 34 focused packaging/identity/ + doctor/completion tests passed with one Fish-environment skip; the full suite + passed 533 tests with the same skip. Fresh wheel and sdist installs outside + the checkout passed imports, both console scripts, help/version/Doctor, + completion generation, TUI launch/exit, reinstall, uninstall, and reinstall + checks. Their temporary application HOME/XDG roots remained untouched. +- GitHub/beta-readiness preparation selected `2.0.0b1`, consolidated the + changelog, added a synthetic-data TUI preview and explicit release checklist, + and kept `main` as the stable v1.4 default branch. The isolated build produced + correctly versioned wheel/sdist artifacts; 34 focused tests passed with one + Fish-environment skip and the full suite passed 533 tests with the same skip. + GitHub's Ubuntu 24.04 matrix also passed the full checks on Python 3.11 and + 3.14. Publishing, tagging, and merging remain deliberately undone pending + manual acceptance. +- A focused beta acceptance pass on 2026-09-23 used only temporary HOME/XDG + roots, generated media fixtures, and an isolated live queue. It fixed + `acquire search --refresh` incorrectly forwarding refresh as `page=True`. + The focused pass completed 256 tests; the post-fix suite completed 534 tests + with the expected missing-Fish skip. Fresh wheel/sdist installs, command and + completion smoke checks, compileall, and diff hygiene passed. Before/after + manifests proved the real music, config, state/backups/queue, and cache were + unchanged. Live Bandit returned `94107`; live 10 Feet remained manual after + two HTTP 530 responses. Detailed evidence and the remaining human checks are + recorded in `docs/BETA_RELEASE_CHECKLIST.md`. +- A read-only real-library correctness audit on 2026-09-24 started from clean + `v2-redesign` at `b3e740a`. The first stable snapshot found 187 readable + tracks; concurrent external activity added eight MP3s during the later test + run, so a + final stable read-only snapshot found 195 (83 MP3, 43 FLAC, 69 M4A), with no + scan/container/required-metadata failures, 141 fully covered tracks, ten + local lyric follow-ups, 76 catalogue-Unknown tracks, 40 new state paths, and + 34 changed state paths. No pre-existing music entry changed. The old UI + rendered all 76 combined follow-up rows as `!`, which misleadingly made + conservative Unknown identity and stale state look like + damaged media. The Library now separates follow-ups, genuine errors, lyrics + to improve, full coverage, and Unknown identity; `!` is error-only and `~` + marks a non-error follow-up. Sync summaries say what was recorded/refreshed, + what remains Unknown, and whether catalogue checks failed. New/changed + Unknown rows correctly recommend Sync before manual matching. A provider- + wide 503/530, Cloudflare tunnel, DNS, or invalid-JSON failure now stops the + current backfill pass instead of making one doomed request per track, while + preserving every established identity and keeping the local snapshot usable. + Before/after manifests proved each diagnostic was read-only and that config, + data/state/backups/queue, and cache were unchanged. Focused verification + passed 141 tests; the full suite passed 540 with the expected missing-Fish + skip, followed by compileall and diff hygiene. +- Final automated release-candidate acceptance on 2026-09-25 started from + clean `db1ef2c`. A small live pass confirmed catalogue pagination/details, + Bandit `94107`, 10 Feet `94102`, one isolated completed download, and an + actual isolated Sync that matched Bandit, retained an ambiguous Unknown, + preserved manual locks, avoided repeat work, reported a changed path, and + produced zero genuine health errors. The integrated Library/Browse/download/ + repair/backup/TUI/Doctor pass completed 385 tests. Representative real MP3, + FLAC, and M4A copies preserved encoded audio, artwork, lyrics, unrelated + tags, sidecars, and locks through metadata apply plus exact restore; the + originals remained byte/stat identical. Wheel and sdist clean installs, + command/completion checks, and wheel lifecycle passed outside the checkout; + 34 packaging/completion tests passed with the expected missing-Fish skip. + The support report passed a forbidden-value privacy audit, GitHub Verify for + `db1ef2c` was green, and before/after manifests proved real music and all real + application XDG data were unchanged. No functional release blocker was + demonstrated. Remaining limitations are manual visual polish, absent Fish + runtime acceptance, no independent second-machine tester, and optional live + rmpc notification acceptance. Detailed evidence and classification are in + `docs/BETA_RELEASE_CHECKLIST.md`. + +Test totals are checkpoint evidence, not a permanent promise. Run the current +suite before reporting a later code milestone. + +## Product experience + +The main download journey remains: + +```text +Browse → Add → Downloads → Download queue → Done +``` + +Browse supports catalogue filters, pagination, details, stable-ID multi-select, +and immediate queue addition. Adding never starts a download. Downloads exposes +individual download/retry plus a confirmed whole-queue action while keeping +durable acquisition-job IDs out of the normal UI. + +Library is the maintenance centre. The primary routine action is: + +```text +s → Sync Library +a → Issues +d → Duplicates +g → Missing Library +e → Metadata repair preview for the selected track +``` + +`?` opens the complete scrollable key guide globally. Common actions remain in +screen shortcut lines. Harmless actions are immediate; high-impact operations +use a cancel-first confirmation where `y` executes immediately, `n`/Escape +cancels, and initial Enter cancels. + +## One-button Library Sync + +Sync Library runs in a background worker and cannot be started twice +concurrently. It uses persisted filesystem fingerprints and the current scan to +classify library-relative MP3, FLAC, and M4A paths as: + +- **unchanged** — same path, size, and nanosecond mtime; reuse safe snapshot and + identity information and avoid redundant hashes, metadata reads, and writes; +- **new** — newly discovered current-library audio; +- **changed** — filesystem evidence changed; reread metadata and do not trust a + stale identity merely because the relative path is the same; +- **removed** — previously active path no longer exists in the current scan. + +New, changed, and currently Unknown tracks are offered to the shared +conservative catalogue matcher. Confident identities are persisted; ambiguous +or empty-result tracks remain Unknown. Normal cache expiry governs retries, so +Sync does not force every catalogue request on every run. One failed lookup does +not prevent other confident matches from being saved. A broad/offline failure +leaves local health useful and does not wipe established identities. + +Removed tracks are retired with current-library bookkeeping rather than having +their historical/custom state records destructively deleted. Clearly stale +external records remain the responsibility of explicit state cleanup. + +Sync refreshes displayed local lyric health but does **not** edit audio, +embedded lyrics, sidecars, audio backups, queue/history, or rmpc configuration. +It does not download music. Optional rmpc absence/failure is not a Library Sync +failure. + +## Library health and maintenance + +Catalogue identity and local lyric health are separate axes. A locally covered +track may be catalogue Unknown without needing lyric attention. An adjacent `.lrc` +counts as synchronized only when it contains genuine timestamped lyric lines. + +The Library headline reports total tracks, follow-up rows, genuine errors, +local lyrics to improve, and catalogue-Unknown tracks separately. Warning rows +use `~`; `!` is reserved for errors. `a` +opens **Issues** immediately from the current snapshot: opening it performs no +scan, hash, or API request. There is at most one row per track, combining +catalogue, lyrics, verification, metadata, and state reasons. Unknown identities +appear because they may need a manual decision even when local lyrics are fully +covered. Valid file-bound manual locks stay out; an unavailable locked choice +appears after a catalogue-backed operation observes that failure, without +replacing the choice. Retired history stays out because it requires no routine +action. + +Issue details reuse only existing safe actions: manual catalogue match, +selected lyric-refresh preview, read-only verification, or Sync Library. Every +completed Sync replaces the displayed snapshot, so resolved rows disappear and +newly discovered problems appear immediately. + +## Duplicate review + +`d` opens **Duplicates** immediately from the current Library snapshot. It does +not rescan, rehash, call the catalogue API, or mutate files/state merely to +render the view. Exact groups share the same saved whole-file SHA-256. Probable +groups require compatible recording-version evidence and either the same +catalogue identity or compatible title, artist, and known duration metadata. + +The detail panel explains the evidence and lists every library-relative path. +Numbered versions and named variants such as live, remix, recording session, +extended, TV mix, acoustic, demo, instrumental, and stems remain distinct. +Detection is review-only: it never deletes, merges, moves, retags, or replaces +audio. Because the view deliberately reuses current snapshot data, running Sync +first provides the freshest paths, metadata, identities, and saved hashes. + +## Missing Library + +`g` opens **Missing Library** from the current Library snapshot. Catalogue +pages load in a background worker through the existing TTL cache and pagination +service. Ownership is determined only by exact confirmed `song_id` values, +including valid manual locks; titles are never used as ownership evidence. +Duplicate titles and released, live, remix, session, demo, extended, TV mix, +and numbered-version records therefore remain distinct. + +The view separately reports confirmed missing recordings, local Unknown tracks, +and catalogue coverage. A page/network failure produces **Partial** or +**Unavailable** coverage rather than a falsely complete list. `/` filters the +already-loaded records without rescanning or another API search. `a` sends the +selected exact recording through the existing queue planner and durable queue; +it never starts a download. Opening/filtering the view does not modify audio, +state, lyrics, sidecars, backups, or rmpc configuration. + +## Metadata repair audit and safe apply + +`e` prepares a metadata repair review for the selected MP3, FLAC, or M4A in a +background worker. Metadata Issues also expose the same action. The +service reads the exact supported local tags and only the already-confirmed +catalogue ID; Unknown identities short-circuit without guessing or making a +catalogue request. Repeated preview in the same unchanged snapshot reuses its +result. + +Supported proposal fields are title, artist, album, and track number. A missing +local field with explicit trustworthy catalogue evidence is **Confident**. Any +different non-empty local value is **Review** and is not treated as an automatic +replacement. Recording/version markers remain significant, including live, +remix, session, extended, TV mix, and numbered versions. Missing catalogue +fields produce no proposal. Album inference from an API path is limited to a +normal released record; track number requires an explicit API value. + +The review checks that the local file fingerprint did not change while it was +read and displays before/after evidence, identity provenance, format, and path. +It separates Confident missing-field proposals from Review differences. No +field is selected by default. Space/Enter toggles the current field; `a` moves +to a confirmation listing the exact changes and backup behavior. Cancel has +initial focus, initial Enter cancels, and duplicate submission is guarded. + +The backend safe-apply foundation is implemented in `metadata_repair.py` for +MP3, FLAC, and M4A. Planning accepts only an explicit subset of proposals from +the reviewed audit. Execution additionally requires explicit confirmation. It +pins the current path, whole-file hash/fingerprint, state bytes, catalogue ID, +encoded media payload, unrelated tags/artwork/lyrics, and adjacent sidecar. + +Execution creates and manifests a normal backup before modifying a +same-filesystem temporary copy. It writes only the selected format-native tags, +fsyncs, reopens, and verifies the copy before atomic replacement. It then +updates the existing state entry's hash without discarding custom or lyric +fields. State conflict/failure restores the original audio; interruption paths +before/after media and state replacement are covered. A valid manual lock is +preserved and rebound only after the controlled edit verifies successfully. + +Confirmed execution runs in a background worker and reuses the backend without +duplicating tag logic. Success reports the backup path, clears cached audit +evidence, and refreshes the Library snapshot, health, and Issues. Safe failure +reports preserved/restored data; rollback failure is surfaced as needing +recovery with the backup retained. Opening, selecting, cancelling, and planning +remain non-mutating. + +Repository tests use comprehensive generated MP3, FLAC, and M4A containers and +verify preservation of encoded audio, artwork, embedded lyrics, custom tags, +and sidecars through success and failure paths. A focused beta audit also ran +the same transaction against temporary copies of three representative real +files. It verified their encoded payloads, lyrics, artwork, unrelated tags, +sidecars, recoverable backups, state hashes, and manual locks, plus rollback +after an injected state-write failure. Source hashes, sizes, and mtimes remained +unchanged. + +That audit exposed two production issues which are now regression-covered: +selected MP3 fields may legitimately change in both ID3v2 and ID3v1 while +unselected ID3v1 year/comment/genre fields must be explicitly preserved; and +rapid independent repairs must receive unique suffixed backup roots rather +than sharing a second-resolution directory. + +- MP3 full coverage uses the existing format-aware ID3 requirements plus its + synchronized sidecar behavior. +- FLAC full coverage requires supported embedded plain lyrics and a valid timed + adjacent `.lrc`; MP3 SYLT is not required. +- M4A full coverage requires supported embedded plain lyrics and a valid timed + adjacent `.lrc`; MP3 SYLT is not required. + +`m` previews lyric maintenance without mutation, then requires explicit +confirmation before applying the shared sync/backup/verification pipeline. +`v` verifies read-only. Track details, selected lyric refresh, backup browsing +and confirmed restore, rmpc verify/explicit setup, identity rebuild, and stale +state cleanup remain available as contextual or advanced operations. + +## Catalogue identity and matcher + +Normal discovery does not depend on historical state: unknown MP3, FLAC, and +M4A tracks can be identified through the shared backfill/matcher path. Only a +confident `song_id` and `api_name` are merged; lyric state is never fabricated. +Known compatible persisted identities are reused until file-change evidence +invalidates them. + +Matching remains conservative and uses normalized titles/collaboration credits, +artist evidence, meaningful version/named-variant penalties, category evidence, +album/API-path evidence, duration tolerance, a narrow released-album duration +grace, a confidence threshold, and an ambiguity margin. Key live-shaped +regressions are: + +```text +Bandit → song_id 94107 +10 Feet → song_id 94102 +``` + +A wrong confident result is worse than Unknown. Do not weaken safeguards merely +to reduce the Unknown count. + +## Manual catalogue identity + +Select any Library track and press `c` to open **Match manually**. The +background catalogue search starts with the local title; `/` focuses a small +refinement field, arrows choose a candidate, Enter saves it, and Escape +cancels. Candidate rows show title, category, era, duration, and catalogue ID +so released/session/version variants remain distinguishable. + +A saved choice adds `identity_source = "manual"` and `identity_locked = +true` alongside the existing `song_id`, `api_name`, and current audio +SHA-256. Missing fields in historical state continue to mean +automatic/unlocked. The lock is visible only in track details and survives +restart, normal Sync, backfill, cache refresh, local refresh, and ordinary +identity rebuild. Lyric maintenance also uses the exact locked catalogue ID and +refuses to substitute a different candidate. + +Locks are bound to the scanned audio fingerprint/hash. Changed or replaced +audio does not inherit the old lock. Press `u` to unlock: because the existing +automatic pipeline reuses any valid identity, unlock deliberately clears only +the catalogue identity/provenance fields and leaves lyrics, history, and custom +state untouched. It does not immediately search; a later Sync may identify the +track automatically. + +Ordinary full identity rebuild preserves valid manual locks. The technical CLI +`999 state rebuild-identities --include-locked --yes` explicitly opts into +reconsidering them. + +Full identity rebuild is an explicit recovery transaction. Preview is +non-mutating; apply rematches current files in memory, preserves non-identity +state, creates a complete state backup, audits changed IDs, and atomically +replaces state. A provider-wide outage aborts rather than erasing identities. + +Explicit stale-state cleanup previews first, makes a state backup, and +atomically removes only clearly stale nonexistent external records. Historical +relative paths and uncertain legacy duplicates are deliberately preserved. + +## Media, lyrics, backups, and rmpc + +- MP3, FLAC, and M4A are recursively discovered case-insensitively. +- MP3 retains ID3 USLT/SYLT behavior. +- FLAC stores plain lyrics in standard Vorbis `LYRICS`. +- M4A stores plain lyrics in standard MP4 `©lyr`. +- Synchronized external lyrics always use the exact adjacent same-basename + `.lrc`; no format conversion or centralized lyrics output occurs. +- Media metadata mutation is preceded by backup and followed by verification; + failure restores the original. Backup retention keeps the newest 10 valid + backups, and historical manifests remain readable. +- rmpc receives the actual adjacent sidecar path. Normal startup, status, + refresh, and Sync never rewrite rmpc configuration; setup is explicit. + +## State and filesystem safety + +State/LRC writes are atomic. State updates retain conflict protection so an +operation does not silently overwrite a concurrently changed state file. +Restore uses safe replacement/rollback semantics. Tests install isolated HOME +and XDG paths before application imports and guard against the real home. + +Never run automated library work against `/home/nobloat/Music` or the user's +real config, state, backups, queue, sidecars, or rmpc configuration. + +## Doctor diagnostics + +`999 doctor` is a bounded, read-only diagnostic command. It emits `PASS`, +`WARN`, and `FAIL` checks for the installed command/Python/package version, +Mutagen, configuration validity, state shape, a capped cache JSON sample, +music-directory readability and MP3/FLAC/M4A filename counts, one one-record +catalogue request, valid backup count/free storage, and optional rmpc setup. +Offline catalogue access is a warning because local features remain usable; +an invalid catalogue response is a failure. + +Doctor does not hash or parse every audio file, enumerate the full catalogue, +run Library Sync, invoke rmpc/MPD, download anything, or write application +paths. `--support-report` prints sanitized JSON and `--save-report PATH` +deliberately writes it. The report excludes song lists and state contents and +redacts home paths and common credential forms by default. + +## Shell completion + +`999 completion bash`, `999 completion zsh`, and `999 completion fish` +generate shell-native completion from the same argparse tree used by the CLI. +Current top-level commands, nested actions, option names, fixed choices, and +path-valued options are therefore covered without maintaining separate static +command lists. The scripts bind both `999` and the legacy `juice-lyrics` name. + +Completion generation exits before settings are loaded. It does not read or +write application state, access the catalogue, scan music, or alter the normal +CLI startup path. Users deliberately redirect the generated output into their +shell's completion directory and regenerate it after CLI upgrades. + +## Packaging and clean installation + +The installable distribution remains `juice-wrld-lyrics`; its primary console +script is `999`, the `juice-lyrics` console script remains a compatibility +alias, and the import/XDG namespaces remain `juice_lyrics` and `juice-lyrics`. +The package version has one code authority (`juice_lyrics.__version__`) and is +resolved dynamically into wheel/sdist metadata. The v2 development branch now +uses the PEP 440 prerelease version `2.0.0b1`; this distinguishes its artifacts +from stable v1.4 without claiming that a release has been published. + +`python -m build` produces a platform-independent wheel and a source +distribution containing the runtime Python packages, README, license, and +build metadata. Repository-only tests, detailed handoff documents, caches, and +generated bytecode are excluded. Runtime UI styling and completion templates +are Python resources, so there are no separate package-data files or checkout +paths required after installation. + +The normal pre-release pipx install is from `origin/v2-redesign`; repeat the +same command with `--force` to replace a stale installed snapshot. Editable +installation is now documented as a development workflow only. Installing or +uninstalling the distribution does not rename or delete existing +`juice-lyrics` XDG data. + +Acceptance also corrected Doctor's executable-location probe: an explicitly +invoked isolated `999`/`juice-lyrics` script is now reported instead of a stale +same-named command elsewhere on `PATH`. Bash and Zsh parsed installed generated +completion successfully. Fish generation passed deterministic coverage, but +the acceptance host does not have Fish installed for an external syntax pass. + +## GitHub and beta readiness + +The branch README now leads with beta status, the normal user workflow, an +actual TUI screenshot rendered from synthetic data, safety boundaries, and +source-independent installation guidance. It clearly identifies the project as +unofficial and states that no music or lyrics are distributed. The screenshot +contains only generic paths/counts and no real user data. + +`docs/CHANGELOG.md` has one coherent `2.0.0b1` prerelease section instead of +several competing Unreleased milestone headings. The executable release gate is +`docs/BETA_RELEASE_CHECKLIST.md`: it covers version/date consistency, clean +artifacts, isolated installs, manual media safety acceptance, privacy review, +release notes/checksums, and explicit stop conditions. + +GitHub's default branch remains `main`, presenting the stable v1.4 baseline. +The v2 presentation is prepared on `v2-redesign`; it must be reviewed through a +pull request before any merge. No release, tag, package upload, or branch merge +has been performed. The repository description/topics are populated, Issues +are enabled, and GitHub detects the MIT license. The repository is currently +private; any visibility change is an explicit remaining release decision. + +## Final performance and reliability acceptance + +The normal launch/navigation, Browse and queue, Library Sync, manual identity, +Issues, Duplicates, metadata repair, Missing Library, backup/restore, doctor, +and completion workflows have a combined focused acceptance pass. Catalogue, +filesystem, and UI work remains backgrounded where designed; the audit found +no reason to weaken matcher, downloader, backup, or state-conflict safeguards. + +One measured Library refresh bottleneck was fixed. Previously, changing any +part of `state.json` invalidated cached status for every track, so one manual +match or metadata repair caused every unchanged audio file to be rehashed and +its metadata/lyrics rechecked. Snapshots now retain a canonical signature of +the resolved state entry that affects each track. A changed entry rechecks only +that track; a top-level or unrelated-entry change reuses safe unchanged track +results. File and sidecar fingerprints, whole-state conflict signatures, and +same-path replacement detection remain mandatory, so this does not trust stale +identity after an actual media change. + +Cross-feature acceptance now explicitly covers verified MP3, FLAC, and M4A +metadata repairs followed by snapshot refresh and Sync. The updated whole-file +hash stays current, valid manual locks survive, catalogue search is skipped, +and stale State/Catalogue Issues do not remain after the controlled edit. + +## Known limitations and risks + +- Active download cancellation is not implemented. +- Acquisition/post-processing remains MP3-focused; FLAC/M4A support is for + existing local-library files. +- Configuration editing remains primarily CLI-based. +- `cli.py` still contains a second equivalent `load_settings()` plus later + service-adapter definitions that shadow older local `search_api`, + `search_api_advanced`, and `get_song` implementations. This + compatibility-era layering is maintenance debt; consolidate only with + focused CLI/API tests. +- `tui/screens/placeholder.py` is still exported but no current screen uses it. + Remove it only as a small tested code-cleanup change. +- The old `lyrics_dir` configuration is compatibility-only and does not migrate + historical centralized files. +- The beta still needs the manual acceptance and release procedure in + `docs/BETA_RELEASE_CHECKLIST.md`. No package has been published and no release + tag exists. +- Metadata repair has safe TUI selection/apply integration and passed isolated + real-copy acceptance for MP3, FLAC, and M4A. Wider beta use should remain + conservative because tag combinations in the wild are unbounded. + +## Roadmap + +Product principle: + +```text +common safe routine work → automatic/simple +ambiguous/destructive work → explicit user decision +``` + +Keep normal Library UX centered on **Sync Library** and **Issues**; +advanced repair/recovery must not overwhelm normal use. + +1. Complete manual beta acceptance +2. Review and merge `v2-redesign` through a pull request +3. Create the approved beta pre-release and attach verified artifacts + +## Resume safely + +```bash +cd /home/nobloat/Downloads/juice-lyrics-codex +git switch v2-redesign +git status --short +pytest -q +.venv/bin/999 +``` + +Read `AGENTS.md` first, then this file, then the relevant architecture/user +document. Update this file after substantial milestones. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 18023e0..57e1ad3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,121 +1,24 @@ # Roadmap -## Current baseline: 1.4.0 +The canonical current checkpoint is `PROJECT_STATE.md`. This file keeps +only the forward product sequence. -The project already provides a working local-library lyrics workflow: +## Product rule -* API song search and metadata lookup -* version-aware local/API matching -* alias-aware matching -* duration-aware matching -* synced lyrics parsing -* ID3 SYLT embedding -* ID3 USLT fallback -* rmpc `.lrc` generation -* safe rmpc config patching -* incremental state tracking -* timestamped MP3 backups -* verification and restore -* XDG-aware config/cache/data locations -* `setup`, `sync`, `status`, `scan`, `embed`, `verify`, `restore`, `doctor`, `guide`, `search`, `info`, `config`, and `rmpc` commands +```text +common safe routine work → automatic/simple +ambiguous/destructive work → explicit user decision +``` -## Phase 1 — Safety net and architecture +Normal Library UX stays centered on **Sync Library** and **Issues**. +Advanced repair and recovery remain available without crowding routine use. -* Keep project documentation current. -* Separate API, library, lyrics, rmpc, backup, configuration, UI, and acquisition responsibilities. -* Reduce reusable logic living in `cli.py`. -* Keep all currently working behavior intact. -* Increase unit/integration test coverage before major feature work. +## Remaining sequence -## Phase 2 — Acquisition foundation +1. Complete `BETA_RELEASE_CHECKLIST.md` manual acceptance +2. Review and merge `v2-redesign` through a pull request +3. Create the approved `v2.0.0b1` GitHub pre-release and attach artifacts -For explicitly selected resources: - -* normalized acquisition models ✅ -* resource resolution with live API path support ✅ -* single-item download foundation ✅ -* temporary-file downloads ✅ -* atomic finalization ✅ -* content/size validation ✅ -* retries and resumable downloads where supported ✅ -* duplicate detection ✅ -* explicit overwrite policy ✅ -* progress reporting ✅ -* persistent acquisition state/jobs ✅ -* job execution/orchestration ✅ -* post-download MP3 lyrics/rmpc integration ✅ - -## Phase 3 — Acquisition UX and bulk workflows - -Completed milestones: - -* real API/resource validation ✅ -* multi-index explicit selection (`--index 1,2,4`) ✅ -* manifest-driven bulk selection (`acquire manifest`) ✅ -* retry failed/pending items (`acquire retry`) ✅ -* job record deletion (`acquire delete`) ✅ -* interrupted-item recovery on startup ✅ -* duplicate detection and skip policy ✅ -* per-item status and run summaries ✅ - -Bulk operations operate on explicitly selected resources rather than silently turning catalogue searches into acquisition jobs. - -## Phase 4 — Post-download library integration - -* metadata matching ✅ -* canonical filename handling ✅ -* synced/plain lyric embedding ✅ -* rmpc LRC generation ✅ -* verification and rollback ✅ -* incremental state updates (`state.json`) ✅ -* automated backups ✅ - -The existing lyrics pipeline remains the implementation used for acquired MP3s. - -## Phase 5 — Browse/search frontend - -Build an interactive TUI using the same backend services: - -* interactive API search -* result browsing -* song details -* category/era filters -* random discovery -* explicit acquisition actions - -Do not duplicate acquisition or matching logic inside the TUI. - -## Phase 6 — Project rename / hub UX - -Only after the core architecture is stable: - -* consider a broader Juice WRLD API hub name -* polish the interactive frontend -* update package/executable/docs carefully -* preserve compatibility where practical - -## Explicitly not planned right now - -* custom streaming engine -* fake lyric synchronization -* unexplained popularity rankings -* unnecessary heavyweight GUI dependencies - -## Current status - -Completed: - -* core engine modularization -* acquisition models & live API resource resolution -* duplicate detection -* persistent jobs & transient state recovery -* sequential job execution & resume support -* acquisition CLI (`search`, `add`, `manifest`, `jobs`, `run`, `retry`, `delete`) -* MP3 post-download lyrics/rmpc integration -* Settings/Path CLI compatibility across all commands -* 80 automated unit and integration tests passing - -Current focus: - -1. freeze the backend and verify CLI stability -2. proceed to application rename and interactive TUI frontend development +Do not force ambiguous tracks into identities. Do not combine these milestones +into a broad rewrite. Each milestone should preserve the safety invariants in +`../AGENTS.md`, add focused regressions, and update `PROJECT_STATE.md`. diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md new file mode 100644 index 0000000..34ce300 --- /dev/null +++ b/docs/ROADMAP_V2.md @@ -0,0 +1,12 @@ +# Historical v2 roadmap + +The original v2 phases—backend extraction, acquisition, Textual TUI, product +rename, native FLAC/M4A support, Library management, matcher/state hardening, +performance work, and one-button Library Sync—are complete. + +This filename remains for compatibility with old links. Do not maintain a +second roadmap here. See: + +- `PROJECT_STATE.md` for the current checkpoint and limitations; +- `ROADMAP.md` for the ordered remaining work; +- `CHANGELOG.md` for milestone history. diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md new file mode 100644 index 0000000..9f63bc3 --- /dev/null +++ b/docs/UI_DESIGN.md @@ -0,0 +1,406 @@ +# 999 TUI Design Specification + +## Purpose + +This document defines the user interface and interaction design for 999. + +999 is a Juice WRLD music management hub designed for Linux terminals. + +It combines: + +- catalogue browsing +- local music management +- lyric management +- acquisition/downloads +- rmpc integration + +The goal is to feel like a native Linux terminal application similar to tools like rmpc and superfile. + +--- + +# Design Philosophy + +## Principles + +### Keyboard First + +The entire application should be usable without a mouse. + +Common actions should be reachable through: + +- arrows +- enter +- escape +- single-key shortcuts + +--- + +### Terminal Native + +999 should respect the user's terminal environment. + +The application should: + +- use terminal colours +- avoid forcing a custom theme +- work with existing rice setups + +Examples: + +- Catppuccin +- Tokyo Night +- Gruvbox +- Dracula +- Nord +- custom ANSI themes + +The application should feel like it belongs inside the user's terminal. + +--- + +### Simple Frontend, Powerful Backend + +The user should not need to understand: + +- API paths +- UUID job IDs +- ID3 frame names +- internal processing steps + +The interface should translate technical complexity into simple actions. + +Use: + +"Synced Lyrics" + +instead of: + +"SYLT" + +Use: + +"Downloads" + +instead of: + +"Acquisition Jobs" + +--- + +# Global Layout + +The application uses a persistent layout. + +Example: + + +┌──────────────────────────────────────┐ +│ 999 — Juice WRLD Music Hub │ +├──────────────────────────────────────┤ +│ │ +│ CONTENT │ +│ │ +│ │ +├──────────────────────────────────────┤ +│ ? Help / Search q Quit │ +└──────────────────────────────────────┘ + + +--- + +# Main Navigation + +Primary sections: + + +[1] Dashboard +[2] Browse +[3] Library +[4] Downloads +[5] Settings + + +Navigation should be possible with: + +- number keys +- shortcuts +- tab switching + +--- + +# Dashboard + +Purpose: + +The first screen when opening 999. + +Shows a quick overview. + +Example: + + +┌──────────────────────────────────────┐ +│ Dashboard │ +├──────────────────────────────────────┤ +│ │ +│ Library │ +│ │ +│ 542 Tracks │ +│ 510 With Lyrics │ +│ 32 Missing │ +│ │ +│ Downloads │ +│ 2 Active │ +│ │ +│ Player │ +│ rmpc Connected ✓ │ +│ │ +├──────────────────────────────────────┤ +│ Browse Library Sync Downloads │ +└──────────────────────────────────────┘ + + +The Dashboard opens by default and summarizes the current local snapshot and +download state without waiting for network work. It links users toward Browse, +Library Sync, and Downloads rather than becoming a second control panel. + +--- + +# Browse Screen + +Purpose: + +Discover songs from the Juice WRLD catalogue. + +The default path is intentionally direct: search, highlight a song, press `a`, +then open Downloads with `4`. Marking is optional. Empty selection boxes are +hidden until Space marks the first song; `M` page selection and `u` clearing +remain secondary actions in Help. + +Features: + +- search +- filtering +- sorting +- song preview + +Example: + + +Search: +[rental________________] + +Results: + +Rental (v1) +DRFL +Synced Lyrics +Download Available + +Rental (v2) +DRFL +No Lyrics +Download Available + +Preview: + +Rental (v1) + +Era: +Death Race For Love + +Producer: +Seezyn + +[a] Add to Downloads +[4] Open Downloads +[enter] Details + + +--- + +# Song Details Screen + +Purpose: + +Show complete information. + +Example: + + +Rental (v1) + +Category: +Unreleased + +Era: +DRFL + +Length: +4:13 + +Producer: +Seezyn + +Lyrics: +Synced + +Actions: + +d Download + +l View Lyrics + +esc Back + + +--- + +# Library Screen + +Purpose: + +Manage local files. + +Example: + + +Library + +315 tracks · 15 follow-ups · 2 errors +Lyrics to improve 9 · Fully covered 287 · Catalogue unknown 6 · MP3 170 · FLAC 85 · M4A 60 + +Rental.flac +Catalogue match ✓ +Embedded lyrics ✓ +Synced LRC ✓ + + +Actions: + + +s Sync Library +a Issues +g Missing Library +d Duplicates +e Metadata repair +r Refresh +m Maintain lyrics +v Verify +b Backups +p Player integration +c Match manually +u Unlock manual match +enter Details; l refresh selected lyrics + + +--- + +# Downloads Screen + +Purpose: + +Replace technical job management. + +The user should never need UUIDs. + +The primary view is a flat queue of songs. Persistent acquisition jobs remain +an internal durability and execution detail; an internal reference may be shown +only under troubleshooting details. Completed records contribute to the summary +but are hidden from the active queue, while failed songs remain visible. + +Browse uses Space to mark stable song IDs, `M` to toggle downloadable songs on +the visible page, and `u` to clear marks. Marks may span pages of one logical +search; search or filter changes clear them. `a` immediately adds the marked +set, or the current song when nothing is marked. The status line reports the +result and reminds the user that adding does not start a download. + +The persistent Browse shortcut line shows movement, details, marking, adding, +and Help. `?` opens a scrollable keyboard guide from any section, including all +secondary actions and the shared confirmation keys. Harmless actions execute +immediately; high-impact actions use a cancel-first dialog. In those dialogs, +`y` confirms immediately, `n`/`Esc` cancels, and initial `Enter` cancels. + +Example: + + +Downloads + +✓ Rental +Complete + +↓ Lemon Glow +Downloading 54% + +! Track +Failed + +Retry + + +Actions: + +`A` Download queue is the primary action. `d` downloads only the highlighted +song and `t` tries a failed song again. Remove, clear, history cleanup, and +refresh remain available through `?` rather than filling the persistent bar. + + +--- + +# Settings Screen + +Purpose: + +Inspect configuration, with everyday folders and rmpc status before advanced +cache, state, provenance, and diagnostic paths. + +Example: + + +Settings + +Music folder + +~/Music/Juice WRLD + +Download location + +~/Music/Juice WRLD + +External lyrics + +Beside each song (.lrc) + +Player + +rmpc detected ✓ + + +--- + +# Keybindings + +The running app's `?` Help screen is the complete key guide and is derived +from the maintained TUI action inventory. The visible shortcut lines prioritize +movement, details, and the main action for each section. Core bindings: + +| Section | Common keys | +| --- | --- | +| Global | `1`–`5` sections, `?` Help, `q` Quit, `Esc` back/close, `r` refresh | +| Browse | `↑`/`↓` move, `Enter` details, `/` search, `Space` mark, `a` add, `M` mark page, `u` clear marks | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `a` Issues, `g` Missing Library, `d` Duplicates, `e` metadata repair, `c` manual match; `u` unlock, `m`, `r`, `v`, `b`, `p` are secondary | +| Downloads | `↑`/`↓` move, `Enter` details, `d` selected download, `t` retry, `A` whole queue | +| Settings | `↑`/`↓` inspect, `PgUp`/`PgDn` scroll, `r` refresh | + +`y` immediately accepts a high-impact confirmation. `n`/`Esc` cancels. +`Enter` chooses the focused action, which is Cancel initially. `Tab`, +`Shift+Tab`, and left/right move between actions. + + +--- + +# Current scope + +Dashboard, Browse, Library, Downloads, Settings, song details, and global Help +are implemented. Forward product work is tracked in `PROJECT_STATE.md` rather +than as speculative screens here. diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md new file mode 100644 index 0000000..65643ad --- /dev/null +++ b/docs/USER_FLOWS.md @@ -0,0 +1,614 @@ +# 999 User Flow Specification + +## Purpose + +This document defines the main user journeys inside 999. + +The goal is to make complex backend features feel simple and natural. + +The user should think in terms of: + +- finding music +- managing a library +- downloading songs +- viewing lyrics +- keeping everything organized + +The user should not need to understand: + +- API requests +- acquisition jobs +- ID3 tags +- metadata matching +- file processing + +--- + +# Core User Experience + +The main loop of 999: + + +Discover +↓ +Inspect +↓ +Acquire +↓ +Organize +↓ +Listen +↓ +Maintain + + +--- + +# Flow 1: First Launch + +## Goal + +A new user opens 999 for the first time. + +The application must open safely even when configuration or the default library +is missing. + +--- + +## Experience + +User runs: + + +999 + + +The Dashboard opens without downloading, modifying media, creating a +centralized lyrics folder, or rewriting rmpc. Missing paths are shown in plain +language. Settings exposes the configured locations; `999 config init` is the +optional CLI path for writing starter configuration, and rmpc setup remains an +explicit action. + + +--- + +# Flow 2: Daily Opening + +## Goal + +User opens 999 normally. + +Command: + + +999 + + +--- + +Expected: + +No long startup. + +Show dashboard immediately. + +Example: + + +999 + +Library +542 tracks + +Lyrics +510 synced +32 missing + +Downloads +1 active + +rmpc +Connected ✓ + + +Available actions: + + +Browse +Library +Downloads +Sync + + +--- + +# Flow 3: Finding a Song + +## Goal + +User wants to find a Juice WRLD song. + +--- + +User: + + +Press / + + +Search opens. + +Input: + + +rental + + +Results appear: + + +Rental (v1) + +DRFL + +Synced Lyrics +Download Available + +Rental (v2) + +DRFL + +No Lyrics +Download Available + + +--- + +User actions: + + +Enter + + +opens details. + + +d + + +downloads. + + +l + + +opens lyrics. + +--- + +# Flow 4: Downloading a Song + +## Goal + +Downloading should feel instant and simple. + +Current: + + +search +add +copy UUID +run job + + +Problem: + +Too technical. + +--- + +v2 primary user-facing model: + +Browse → press `a` to Add → open Downloads → press `A` to Download queue + +Adding a song creates durable internal acquisition state but does not begin a +download. The Downloads screen shows individual tracks, not jobs or UUIDs. +Completed tracks are hidden from the active queue; failed tracks remain visible +for future Retry or Remove actions. + +Marking is optional. Space toggles the highlighted song, `M` toggles downloadable songs on the +visible API page, and `u` clears all marks. Marks may span pages of the same +logical search, but a title, Category, or Era change clears them. `a` immediately +adds the marked set, or the highlighted song when nothing is marked. Adding +never starts a download and the application +does not bulk-fetch an unbounded catalogue merely to fill the queue. + +Download queue is the primary Downloads action. Download selected, Retry, +Remove, Clear queue, and Clear completed history remain available as secondary +actions. Active-download cancellation remains future work. + +v2: + +User selects: + + +Rental (v1) + + +Presses: + + +d + + +--- + +Application: + + +Download Rental (v1)? + +Destination: + +~/Music/Juice WRLD/Unreleased + +[Download] Confirm +[Esc] Cancel + + +--- + +After confirming: + + +Downloads + +Rental (v1) + +Downloading... + +████████░░ 80% + +Lyrics: +Synced + +After completion: + +✓ Added to library +✓ Lyrics embedded +✓ Sidecar lyrics ready + +The confirmation defaults to Cancel and explains that the operation may write +the media file, embed lyrics, create an LRC file, update library state, and +notify rmpc. Failed downloads remain in the queue with a readable failure; +completed downloads leave the active queue but remain counted and durable. +When synchronized lyrics exist, the external LRC is written beside the finalized +audio with the same basename. Audio and external lyrics therefore travel +together when the music folder is synchronized. + + +--- + +# Flow 5: Viewing Song Details + +## Goal + +Users can understand a track before downloading. + +--- + +Example: + + +Rental (v1) + +Category: +Unreleased + +Era: +DRFL + +Length: +4:13 + +Producer: +Seezyn + +Lyrics: +Synced + +Local: +Not downloaded + + +Actions: + + +d Download +l Lyrics +esc Back + + +--- + +# Flow 6: Managing Local Library + +## Goal + +Users can inspect and safely maintain their own collection. + +--- + +Library view: + + +My Library + +Rental.mp3 +Synced Lyrics ✓ + +Robbery.mp3 +Plain Lyrics + +Unknown Track +Missing Lyrics + + +--- + +Actions: + + +s Sync Library + +a Issues + +g Missing Library + +d Duplicates + +e Metadata repair + +r Refresh + +m Maintain lyrics + +v Verify + +b Backups + +enter Details; l refresh selected lyrics + +c Match manually; u unlock manual match + + +--- + +# Flow 7: Syncing Library + +## Goal + +Bring 999's view of the current library up to date without understanding scan, +backfill, verification, or state internals. + +--- + +User: + + +Press s + + +--- + +Progress: + + +Syncing library... + + +--- + +Summary: + + +Library synced + +181 tracks +4 new recorded +1 changed refreshed +2 removed +37 newly matched +15 catalogue unknown + + +--- + +Sync runs in the background without confirmation. It avoids expensive work for +unchanged files, identifies only confident Unknowns, retires removed paths in +state, and refreshes local health. It never edits audio, embedded lyrics, +sidecars, backups, downloads, or rmpc configuration. Offline or ambiguous +catalogue results remain Unknown without making the local Library unusable. The +Library headline separately reports follow-ups, genuine errors, local lyrics to +improve, and catalogue-Unknown tracks; an Unknown identity is not presented as +damaged audio. + +To change lyrics, the separate `m` action first presents a non-mutating +maintenance preview and uses cancel-first confirmation before applying changes. + +When automatic identity remains Unknown or is wrong, `c` opens a catalogue +chooser. The user may refine the query with `/`, choose with arrows, and save +with Enter. That explicit choice becomes a file-bound manual lock; normal Sync +and rebuild preserve it. `u` clears the identity lock without touching lyrics +and leaves automatic reconsideration for a later Sync. + +`a` opens Issues from the current snapshot without another scan or catalogue +request. One row per track combines the reasons that still require attention. +Arrows select a row; its detail explains the problem; `c`, `l`, `v`, and `s` +reuse manual match, lyric preview, verification, and Sync. + +`d` opens a read-only duplicate review from that same snapshot. Exact groups +share a saved whole-file hash; probable groups show the catalogue, metadata, +duration, and version evidence that connected them. Distinct live, remix, +session, extended, TV mix, and numbered versions stay separate. No files are +deleted, merged, moved, retagged, or replaced. + +`e` reads the selected track's supported tags and confirmed catalogue record. +The preview shows before/after values and separates confidently repairable +missing fields from existing differences requiring review. Nothing is selected +by default. Space/Enter toggles a field and `a` opens a cancel-first summary of +the exact changes. Confirmed work runs in the background through the shared +backup, temporary-copy verification, atomic replacement, rollback, and state +conflict service. Unknown identities are not guessed. + + +--- + +# Flow 8: Managing Downloads + +## Goal + +Replace job management with a friendly queue. + +--- + +Downloads screen: + + +Queue + +✓ Rental + +Complete + +↓ Lemon Glow + +Downloading 52% + +! Track + +Failed + + +--- + +Current actions: + +`A` Download queue + +`d` Download selected queued song + +`t` Try selected failed song again + +`?` Secondary queue management and help + +Completed history and cleanup are intentionally not part of the primary +journey. Active-download cancellation remains planned. + + +--- + +# Flow 9: Lyrics Viewing + +## Goal + +Allow users to inspect lyrics. + +--- + +For synced lyrics: + +Show timestamps. + +Example: + + +Rental + +[00:01] +Lyrics line + +[00:05] +Lyrics line + + +--- + +For plain lyrics: + +Show text only. + +Never invent timestamps. + +--- + +# Flow 10: Error Handling + +## Goal + +Errors should explain what happened. + +Avoid: + + +HTTPError 404 + + +Prefer: + + +Unable to download. + +The file is no longer available on the server. + +[Retry] +[Back] + + +--- + +# Important UX Rules + +## Never expose unnecessary technical details + +Avoid showing: + +- UUIDs +- API paths +- stack traces +- ID3 frame names + +--- + +## Always show current state + +Users should know: + +- what is happening +- what finished +- what failed +- what they can do next + +--- + +## Avoid unnecessary confirmations + +Do not ask: + +"Are you sure?" + +for harmless actions. + +Ask only before: + +- deleting files +- changing configuration +- destructive actions + +--- + +# Forward flows + +Sync Library, Issues, Missing Library, duplicate review, and manual catalogue matching form the normal Library +workflow. The ordered remaining roadmap lives in `PROJECT_STATE.md`; +speculative screen lists are intentionally not duplicated here. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 1bbdd82..f446366 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -1,40 +1,210 @@ # User Guide -## First-time setup +## First run Run: ```bash -juice-lyrics setup +999 ``` -This creates/updates configuration and, when rmpc is detected, prepares the lyric directory and relevant rmpc settings. +This opens the terminal interface. It does not download anything or rewrite +rmpc configuration. If the default library is missing, Settings shows the +configured path and the next action without a traceback. + +Press `?` from any section for the scrollable keyboard guide. The bottom lines +show the most common actions for the current section. Use `1`–`5` to switch +sections when not typing, `↑`/`↓` to move, `Enter` for details, `Esc` to return, +and `q` to quit. Digits and `q` type normally in a focused search field; Enter +submits the search and returns focus to the results. +Browse uses `Space` to mark songs and `a` to add the current or marked songs +directly to Downloads; adding does not start a download. In Downloads, `d` +downloads one selected song, `t` retries a failed song, and `A` starts the +whole queue after confirmation. Library Sync, local refresh, verification, and +maintenance preview do not change audio or lyrics. Applying maintenance, +restoring, rebuilding catalogue +matches, and changing rmpc setup remain cancel-first confirmations: `y` +confirms immediately, `n`/`Esc` cancels, and initial `Enter` cancels. + +Configuration is optional. `999 config init` writes a starter config only. +`999 setup` remains a compatibility shortcut for an initial library lyric sync; +it does not configure rmpc. Only the explicit `999 rmpc setup` command changes +rmpc configuration. + +## Configuration + +The application configuration is `~/.config/juice-lyrics/config.toml`. Embedded +lyrics remain inside each audio file. External synchronized lyrics are written +beside the audio with the same basename: -## Normal day-to-day use +```text +song.mp3 +song.lrc +another-song.flac +another-song.lrc +third-song.m4a +third-song.lrc +``` + +The legacy `lyrics_dir` key remains readable so old configurations continue to +load, but it is deprecated and ignored for new LRC output. Existing centralized +files are not moved automatically. Local FLAC and M4A files are scanned and +synchronized natively without conversion. FLAC embeds plain-text Vorbis +`LYRICS`; M4A embeds standard MP4 `©lyr`; synchronized timing remains in the +adjacent `.lrc`. + +## Manage your local library + +Open `999`, choose **Library**, and use: + +* **Sync Library** (`s`) for the normal update: discover MP3, FLAC, and M4A changes, retire known removed entries, and identify safe catalogue matches without changing audio or lyrics; +* **Issues** (`a`) to see only tracks still needing a decision or repair; +* **Duplicates** (`d`) to review exact file copies and conservative probable recordings without changing anything; +* **Missing Library** (`g`) to compare confirmed local recording IDs with the paginated catalogue and optionally queue one exact recording; +* **Metadata repair** (`e`) on the selected track to compare supported tags, explicitly select fields, and review a cancel-first Apply confirmation; +* **Maintain lyrics** to preview needed changes, then explicitly approve them; +* **Verify** for a read-only health check and attention list; +* **Backups** to inspect valid backups and restore one with confirmation; +* **Player** to check rmpc and explicitly configure its sidecar indexing. + +Press `?` in Library to see the infrequent **Rebuild catalogue matches** action. +It previews current tracks and existing identities, then uses a cancel-first +confirmation. The rebuild changes application identity state only; it does not +modify audio or lyrics. + +Sync Library keeps unchanged tracks fast and checks unknown tracks against the +catalogue in the background. Only confident identities are saved. A recent +empty or ambiguous search is retried after the normal catalogue cache window. +The separate **Refresh** key remains available for a direct local rescan. +Audio, embedded lyrics, sidecars, audio backups, and rmpc configuration are not +changed. If the catalogue is unavailable, local health remains usable and the +track stays **Unknown**. + +Duplicates opens immediately from the current Library snapshot. Exact groups +share the same recorded whole-file SHA-256. Probable groups use compatible +catalogue identity, duration, title, artist, and recording-version evidence. +Live, remix, session, extended, TV mix, and numbered versions are not treated +as interchangeable. The view shows its evidence and every path, but never +deletes, merges, moves, retags, or replaces audio. Run Sync Library first when +you want the snapshot and saved fingerprints brought up to date. + +Missing Library loads cached/paginated catalogue data in the background. It +uses stable catalogue IDs only: duplicate titles and live, remix, session, +demo, extended, or numbered versions remain separate. Local Unknown tracks are +shown as a separate count and never used as loose-title proof of ownership. If +pages cannot be loaded, coverage is labelled partial or unavailable. `/` +filters loaded results and `a` adds the selected recording to the normal +Downloads queue without starting it. + +Metadata repair reads the selected MP3, FLAC, or M4A tags and its confirmed +catalogue record. It can propose title, artist, album, and track number where +the catalogue actually supplies those fields. Missing local values are marked +**Confident**; differences from existing values are marked **Review**. Unknown +tracks receive no guesses, and version distinctions are preserved. No fields +are selected by default. Space or Enter toggles one field; `a` reviews the exact +selection; the final confirmation starts on Cancel. A confirmed repair runs in +the background, creates a complete audio backup, writes a temporary copy, and +verifies the encoded audio, artwork, embedded lyrics, unrelated tags, and +adjacent sidecar before replacing the file. Failure restores the original where +replacement began. Success updates the saved whole-file hash and refreshes the +Library and Issues view. Normal repair does not change lyrics or player config. + +Issues opens instantly from the current Library snapshot and does not rescan or +contact the catalogue merely to display the list. Each affected track appears +once with its combined catalogue, lyric, verification, metadata, or state +reasons. From an issue, use `c` for manual matching, `l` for the existing +selected lyric-refresh preview, `v` to verify, or `s` to Sync Library. A valid +manual lock stays out of follow-ups; if a catalogue-backed action later +observes that its +chosen recording is unavailable, the lock is preserved and an Issue explains +the problem. + +To resolve an Unknown track—or correct a wrong automatic match—select it and +press `c`. The **Match manually** chooser searches using the local title; press +`/` to refine the search, use the arrow keys to choose a clearly identified +candidate, and press Enter to save it. This saves only catalogue identity state +and marks the choice as manual and locked. It does not modify the audio, +lyrics, sidecar, backups, downloads, or rmpc configuration. + +A valid manual lock survives normal Sync, automatic backfill, restart, and an +ordinary identity rebuild. It is tied to the current audio content, so a +changed or replaced file does not inherit it. Press `u` on a manually matched +track to unlock and clear its catalogue identity; lyric and custom state remain +untouched, and a later Sync may match it automatically again. + +Select a song and press `l` to refresh lyrics for only that song. The CLI +`999 sync` command is the separate scriptable lyric-maintenance workflow; it +may modify lyrics and should not be confused with the TUI's state-only Sync +Library action. + +**Fully covered** describes local lyric health, not catalogue identity. A FLAC +or M4A file is fully covered when it has embedded plain lyrics and its adjacent +`.lrc` contains timestamped lyric lines. MP3 keeps its existing synchronized +embedded-lyrics requirement. A locally covered track may still show **Catalogue match: +Unknown**; that only means automatic refresh cannot identify a safe catalogue +record yet. It appears in Issues as an identity decision, not as a claim that +the existing lyrics are broken. -After adding or changing local songs: +## Check health ```bash -juice-lyrics sync +999 status ``` -`sync` should be the main command to remember. +Use this when you simply want to know whether the library is up to date. -It matches songs, fetches lyrics, embeds metadata, generates rmpc LRC files when synchronized lyrics exist, verifies results, and updates state. +`999 scan` is the advanced catalogue-matching diagnostic. Its **Catalogue +uncertain** count means identity could not be established safely; it does not by +itself mean that local lyrics are missing or broken. -## Check health +## Clean clearly stale state records + +Preview first: ```bash -juice-lyrics status +999 state clean ``` -Use this when you simply want to know whether the library is up to date. +If the listed records are genuinely obsolete, apply the cleanup: + +```bash +999 state clean --yes +``` + +The apply command writes a timestamped `state.json.pre-clean-...bak` safety +copy before an atomic state update. It removes no audio or LRC files. Ordinary +missing relative entries are retained because they may describe music moved +within the configured library. + +## Rebuild catalogue matches + +If older persisted matches were created by an outdated matcher, preview a full +current-library rebuild: + +```bash +999 state rebuild-identities +``` + +Apply it only after reviewing the counts: + +```bash +999 state rebuild-identities --yes --details +``` + +Use `--refresh` as well when cached catalogue search responses must be fetched +again. The rebuild reconsiders MP3, FLAC, and M4A files, preserves all lyric and +other state fields, preserves valid manual locks, ignores stale external +records, makes a complete state backup, and commits the result atomically. +Ambiguous tracks become Unknown. The advanced `--include-locked` option is the +explicit way to reconsider manual choices too. +An individual API failure preserves that track's old identity; a catalogue-wide +failure aborts without changing state. ## Find songs in the API catalogue ```bash -juice-lyrics search "rental" -juice-lyrics info "Rental" +999 search "rental" +999 info "Rental" ``` Search and info provide catalogue metadata and discovery. @@ -47,25 +217,25 @@ The workflow commands: ```bash # Search for downloadable candidates -juice-lyrics acquire search "rental" +999 acquire search "rental" # Add one or more items (1-based index, e.g. 1 or 1,2,4) -juice-lyrics acquire add "rental" --index 1 +999 acquire add "rental" --index 1 # Add from a plain-text manifest file -juice-lyrics acquire manifest manifest.txt +999 acquire manifest manifest.txt # List queued acquisition jobs -juice-lyrics acquire jobs +999 acquire jobs # Run an acquisition job -juice-lyrics acquire run +999 acquire run # Retry failed or pending items in a job -juice-lyrics acquire retry +999 acquire retry # Delete a job record -juice-lyrics acquire delete +999 acquire delete ``` The acquisition system maintains persistent job state, skips already-present files, supports HTTP range download resumption, validates payloads, and automatically applies the lyrics and rmpc pipeline to downloaded MP3s. @@ -75,7 +245,7 @@ The acquisition system maintains persistent job state, skips already-present fil Songs with API synchronized lyrics get: * embedded ID3 SYLT -* an `.lrc` file for rmpc +* a same-basename `.lrc` beside the audio for rmpc Songs with only ordinary API lyrics get: @@ -86,39 +256,92 @@ Those plain-only songs are still tagged correctly, but rmpc's synchronized Lyric ## Troubleshooting ```bash -juice-lyrics doctor +999 doctor +``` + +Doctor reports clear `PASS`, `WARN`, and `FAIL` results for the installed +command/Python package, configuration, state and cache JSON, the configured +music directory and supported-format counts, one small catalogue connectivity +probe, backup storage, and optional rmpc integration. It does not hash the +library, run Sync, write cache/state, invoke downloads, or change rmpc. + +For support, print or deliberately save a JSON report: + +```bash +999 doctor --support-report +999 doctor --save-report ./999-support.json +``` + +The report is sanitized by default: it contains no song list or state content, +and home paths and common credential forms are redacted. Review any report +before sharing it, as unusual third-party error text cannot be guaranteed to +follow common formats. + +## Shell completion + +`999` generates completion directly from its current command definitions, so +the suggestions cover the installed commands, nested actions, and options. +Generation is read-only and does not load application configuration, state, or +catalogue data. + +Bash (requires the normal `bash-completion` setup): + +```bash +mkdir -p ~/.local/share/bash-completion/completions +999 completion bash > ~/.local/share/bash-completion/completions/999 +``` + +Zsh: + +```zsh +mkdir -p ~/.zfunc +999 completion zsh > ~/.zfunc/_999 +``` + +Ensure `fpath=(~/.zfunc $fpath)` appears before `autoload -Uz compinit && +compinit` in `~/.zshrc`. + +Fish: + +```fish +mkdir -p ~/.config/fish/completions +999 completion fish > ~/.config/fish/completions/999.fish ``` +Open a new shell after installation, and regenerate the file after updating +`999`. Each generated script also binds the legacy `juice-lyrics` command. + For detailed matching: ```bash -juice-lyrics scan +999 scan ``` For metadata verification: ```bash -juice-lyrics verify +999 verify ``` -For rmpc-specific problems: +For advanced or scripted rmpc checks: ```bash -juice-lyrics rmpc verify +999 rmpc verify ``` ## Backups -MP3 metadata changes create timestamped backups under: +MP3, FLAC, and M4A metadata changes create timestamped backups under: ```text ~/.local/share/juice-lyrics/backups/ ``` -Restore the most recent backup with: +Backups can be browsed and restored from **Library → Backups**. For scripted or +unusual recovery, restore the most recent backup with: ```bash -juice-lyrics restore +999 restore ``` ## Paths @@ -129,10 +352,31 @@ Default local library: ~/Music/Juice WRLD/Unreleased ``` -Default rmpc lyrics directory: +External synchronized lyrics: + +```text +song.mp3 +song.lrc +another-song.flac +another-song.lrc +third-song.m4a +third-song.lrc +``` + +The audio path is authoritative; no global LRC destination is configured. +Existing centralized LRC files are not moved automatically. Use the separate +explicit migration utility if migration is required. + +## Compatibility names and data + +`999` is the product and primary executable. `juice-lyrics` remains a legacy +compatibility command and invokes the same Python CLI. The internal package is +still `juice_lyrics`, while existing XDG data remains under `juice-lyrics`: ```text -~/Music/Juice WRLD/lyrics +~/.config/juice-lyrics/ +~/.cache/juice-lyrics/ +~/.local/share/juice-lyrics/ ``` -Both should remain configurable. +No duplicate `999` data tree is created and no migration is required. diff --git a/docs/V2_DESIGN.md b/docs/V2_DESIGN.md new file mode 100644 index 0000000..7b42f37 --- /dev/null +++ b/docs/V2_DESIGN.md @@ -0,0 +1,13 @@ +# Historical v2 design + +The original v2 proposal led to the current `999` product: a Textual +application with Dashboard, Browse, Library, Downloads, Settings, global Help, +MP3/FLAC/M4A support, and a compatibility CLI. + +This filename remains for historical links, but its prospective naming and +screen proposals are no longer authoritative. See: + +- `PROJECT_STATE.md` for the implemented checkpoint and remaining roadmap; +- `UI_DESIGN.md` for current interaction rules; +- `USER_FLOWS.md` for current workflows; +- `ARCHITECTURE.md` and `DECISIONS.md` for technical constraints. diff --git a/docs/assets/999-dashboard.png b/docs/assets/999-dashboard.png new file mode 100644 index 0000000..77e12fa Binary files /dev/null and b/docs/assets/999-dashboard.png differ diff --git a/pyproject.toml b/pyproject.toml index ebcb982..0d05f2d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,34 +1,52 @@ [build-system] -requires = ["setuptools>=75"] +requires = ["setuptools>=77"] build-backend = "setuptools.build_meta" [project] name = "juice-wrld-lyrics" -version = "1.4.0" -description = "Manage local lyrics metadata and rmpc LRC files for MP3 libraries" +dynamic = ["version"] +description = "999: a Juice WRLD music hub for Linux" readme = "README.md" requires-python = ">=3.11" -dependencies = ["mutagen>=1.47"] -license = { text = "MIT" } +dependencies = [ + "mutagen>=1.47,<2.0", + "textual>=1.0,<2.0", +] +license = "MIT" +license-files = ["LICENSE"] authors = [ { name = "juice-wrld-lyrics contributors" } ] -keywords = ["juice-wrld", "lyrics", "mp3", "id3", "sylt", "uslt", "rmpc"] +keywords = ["juice-wrld", "lyrics", "mp3", "flac", "m4a", "id3", "sylt", "uslt", "rmpc"] classifiers = [ + "Development Status :: 4 - Beta", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Environment :: Console", + "Intended Audience :: End Users/Desktop", "Operating System :: POSIX :: Linux", + "Topic :: Multimedia :: Sound/Audio", ] [project.scripts] +999 = "juice_lyrics.cli:main" juice-lyrics = "juice_lyrics.cli:main" [project.urls] -Homepage = "https://juicewrldapi.com/" +Homepage = "https://github.com/NotAI-fr/juice-lyrics" +Repository = "https://github.com/NotAI-fr/juice-lyrics" +Issues = "https://github.com/NotAI-fr/juice-lyrics/issues" +"Catalogue API" = "https://juicewrldapi.com/" [tool.setuptools] package-dir = {"" = "src"} [tool.setuptools.packages.find] where = ["src"] + +[tool.setuptools.dynamic] +version = { attr = "juice_lyrics.__version__" } diff --git a/src/juice_lyrics/__init__.py b/src/juice_lyrics/__init__.py index 3e8d9f9..9b8d3ee 100644 --- a/src/juice_lyrics/__init__.py +++ b/src/juice_lyrics/__init__.py @@ -1 +1 @@ -__version__ = "1.4.0" +__version__ = "2.0.0b1" diff --git a/src/juice_lyrics/acquisition/__init__.py b/src/juice_lyrics/acquisition/__init__.py index 8b65b08..c217d6d 100644 --- a/src/juice_lyrics/acquisition/__init__.py +++ b/src/juice_lyrics/acquisition/__init__.py @@ -1,4 +1,10 @@ -from .models import AcquisitionItem, AcquisitionResult, AcquisitionState +from .models import ( + AcquisitionFailureStage, + AcquisitionItem, + AcquisitionPostProcessingError, + AcquisitionResult, + AcquisitionState, +) from .resolver import ResourceResolutionError, resolve_resource from .duplicates import DuplicateMatch, find_duplicate from .manifests import load_manifest @@ -8,6 +14,8 @@ __all__ = [ "AcquisitionItem", + "AcquisitionFailureStage", + "AcquisitionPostProcessingError", "AcquisitionResult", "AcquisitionState", "ResourceResolutionError", diff --git a/src/juice_lyrics/acquisition/downloader.py b/src/juice_lyrics/acquisition/downloader.py index 8a9b196..64ab5ec 100644 --- a/src/juice_lyrics/acquisition/downloader.py +++ b/src/juice_lyrics/acquisition/downloader.py @@ -9,7 +9,7 @@ from urllib.error import HTTPError, URLError from urllib.request import Request, urlopen -from .models import AcquisitionItem, AcquisitionResult, AcquisitionState +from .models import AcquisitionFailureStage, AcquisitionItem, AcquisitionResult, AcquisitionState ProgressCallback = Callable[[int, int | None], None] NON_RETRYABLE_HTTP_CODES = {400, 401, 403, 404, 410} @@ -107,7 +107,9 @@ def download_to( partial = item.destination.with_name(item.destination.name + ".part") last_error: Exception | None = None + failure_stage = AcquisitionFailureStage.TRANSPORT for attempt in range(policy.retries + 1): + failure_stage = AcquisitionFailureStage.TRANSPORT resume_from = partial.stat().st_size if policy.resume and partial.exists() else 0 try: headers = { @@ -145,6 +147,7 @@ def download_to( progress(written, total) result.state = AcquisitionState.VALIDATING + failure_stage = AcquisitionFailureStage.VALIDATION if _is_probable_error_payload(partial): partial.unlink(missing_ok=True) raise RuntimeError("Downloaded payload looks empty or like an error response") @@ -167,6 +170,7 @@ def download_to( break except HTTPError as exc: + failure_stage = AcquisitionFailureStage.TRANSPORT last_error = exc if exc.code in NON_RETRYABLE_HTTP_CODES: break @@ -187,5 +191,5 @@ def download_to( result.state = AcquisitionState.FAILED result.error = str(last_error or "Download failed") + result.failure_stage = failure_stage return result - diff --git a/src/juice_lyrics/acquisition/integration.py b/src/juice_lyrics/acquisition/integration.py index 3f537c4..1d50fd3 100644 --- a/src/juice_lyrics/acquisition/integration.py +++ b/src/juice_lyrics/acquisition/integration.py @@ -4,11 +4,17 @@ from pathlib import Path from typing import Any, Callable -from ..backup.manager import now_iso +from ..backup.manager import ( + backup_file, + make_backup_root, + now_iso, + restore_file, + write_manifest, +) from ..lyrics.engine import embed_lyrics, parse_synced_lyrics, verify_file, write_lrc from ..rmpc.integration import notify_rmpc_index from ..state import load_state, save_state, sha256_file -from .models import AcquisitionItem +from .models import AcquisitionFailureStage, AcquisitionItem, AcquisitionPostProcessingError @dataclass(frozen=True, slots=True) @@ -20,6 +26,7 @@ class IntegrationResult: lrc_path: Path | None = None rmpc_notified: int = 0 message: str = "" + backup_path: Path | None = None def integrate_downloaded_mp3( @@ -40,6 +47,8 @@ def integrate_downloaded_mp3( """ path = item.destination + # ``lyrics_dir`` remains accepted for callers from older releases, but it + # is intentionally ignored. The finalized media path now owns its sidecar. if path.suffix.lower() != ".mp3": return IntegrationResult(path=path, message="not an MP3; lyrics integration skipped") @@ -53,24 +62,77 @@ def integrate_downloaded_mp3( plain = str(song.get("lyrics") or "") lrc_path: Path | None = None + backup_path: Path | None = None rmpc_notified = 0 + rmpc_warning: str | None = None if not synced and not plain.strip(): lyric_type = "NONE" verification = "no lyrics available" else: - lyric_type = embed_lyrics(path, synced, plain) - valid, verification = verify_file(path) - if not valid: - raise RuntimeError(f"Lyrics were embedded but verification failed: {verification}") - - if synced and lyrics_dir is not None: - lrc_path = write_lrc(path, synced, song, Path(lyrics_dir)) + music_dir = getattr(settings, "music_dir", None) if settings is not None else None + backup_base = Path(music_dir) if music_dir is not None else path.parent + try: + path.relative_to(backup_base) + except ValueError: + backup_base = path.parent + + try: + original_hash = sha256_file(path) + backup_root = make_backup_root() + backup_path = backup_file(path, backup_root, backup_base) + write_manifest( + backup_root, + [{ + "file": str(path), + "sha256_before": original_hash, + "purpose": "acquisition lyric post-processing", + }], + ) + except Exception as exc: + raise AcquisitionPostProcessingError( + AcquisitionFailureStage.LYRICS, + f"Audio download completed, but lyric backup failed before metadata modification: {exc}. " + "The downloaded file was not modified." + ) from exc + + try: + lyric_type = embed_lyrics(path, synced, plain) + valid, verification = verify_file(path) + if not valid: + raise RuntimeError(f"verification failed: {verification}") + except Exception as exc: + try: + restore_file(backup_path, path) + except Exception as restore_exc: + raise AcquisitionPostProcessingError( + AcquisitionFailureStage.LYRICS, + f"Audio download completed, but lyric post-processing failed: {exc}. " + f"Automatic restore also failed: {restore_exc}. " + f"The pristine backup remains at {backup_path}; the downloaded file may be partially modified.", + reuse_finalized_file=False, + ) from restore_exc + raise AcquisitionPostProcessingError( + AcquisitionFailureStage.LYRICS, + f"Audio download completed, but lyric post-processing failed: {exc}. " + "The original downloaded file was restored from backup; the failed item remains retryable." + ) from exc + + if synced: + try: + lrc_path = write_lrc(path, synced, song) + except Exception as exc: + raise AcquisitionPostProcessingError( + AcquisitionFailureStage.LRC, + f"Audio download and lyric processing succeeded, but LRC integration failed: {exc}. " + "The verified MP3 and pristine backup were retained; the failed item remains retryable." + ) from exc if notify_rmpc: try: rmpc_notified = notify_rmpc_index([lrc_path]) - except Exception: + except Exception as exc: rmpc_notified = 0 + rmpc_warning = str(exc) # Synchronize library state.json so future `sync` operations recognize this file try: @@ -95,18 +157,26 @@ def integrate_downloaded_mp3( if state is None: save_state(current_state) except Exception as exc: - raise RuntimeError(f"Failed to synchronize library state: {exc}") from exc + processed = " and lyric processing succeeded" if lyric_type != "NONE" else "" + raise AcquisitionPostProcessingError( + AcquisitionFailureStage.STATE, + f"Audio download{processed}, but state update failed " + f"(Failed to synchronize library state): {exc}. " + "The finalized MP3 was retained; the failed item remains retryable." + ) from exc detail = f"{lyric_type}; {verification}" if lrc_path: detail += f"; LRC: {lrc_path}" if rmpc_notified: detail += f"; rmpc notified: {rmpc_notified}" + if rmpc_warning: + detail += f"; rmpc notification failed: {rmpc_warning}" return IntegrationResult( path=path, lyric_type=lyric_type, + backup_path=backup_path, lrc_path=lrc_path, rmpc_notified=rmpc_notified, message=detail, ) - diff --git a/src/juice_lyrics/acquisition/jobs.py b/src/juice_lyrics/acquisition/jobs.py index 5a001cc..5f80975 100644 --- a/src/juice_lyrics/acquisition/jobs.py +++ b/src/juice_lyrics/acquisition/jobs.py @@ -10,7 +10,7 @@ from ..backup.manager import ensure_data_dirs from ..config.settings import DATA_DIR -from .models import AcquisitionItem, AcquisitionResult, AcquisitionState +from .models import AcquisitionFailureStage, AcquisitionItem, AcquisitionResult, AcquisitionState DEFAULT_JOBS_FILE = DATA_DIR / "acquisition_jobs.json" @@ -28,6 +28,9 @@ class JobItem: bytes_written: int = 0 resumed: bool = False error: str | None = None + failure_stage: AcquisitionFailureStage | None = None + retry_file_size: int | None = None + retry_file_sha256: str | None = None def to_dict(self) -> dict[str, Any]: return { @@ -44,6 +47,9 @@ def to_dict(self) -> dict[str, Any]: "bytes_written": self.bytes_written, "resumed": self.resumed, "error": self.error, + "failure_stage": self.failure_stage.value if self.failure_stage else None, + "retry_file_size": self.retry_file_size, + "retry_file_sha256": self.retry_file_sha256, } @classmethod @@ -60,6 +66,12 @@ def from_dict(cls, raw: dict[str, Any]) -> "JobItem": metadata={str(k): str(v) for k, v in dict(item_raw.get("metadata", {})).items()}, ) state = AcquisitionState(str(raw.get("state", AcquisitionState.PENDING.value))) + failure_stage_raw = raw.get("failure_stage") + failure_stage = ( + AcquisitionFailureStage(str(failure_stage_raw)) + if failure_stage_raw not in (None, "") + else None + ) except (KeyError, TypeError, ValueError) as exc: raise JobStoreError(f"Invalid acquisition job item: {exc}") from exc @@ -69,6 +81,17 @@ def from_dict(cls, raw: dict[str, Any]) -> "JobItem": bytes_written=int(raw.get("bytes_written", 0)), resumed=bool(raw.get("resumed", False)), error=raw.get("error"), + failure_stage=failure_stage, + retry_file_size=( + int(raw["retry_file_size"]) + if raw.get("retry_file_size") is not None + else None + ), + retry_file_sha256=( + str(raw["retry_file_sha256"]) + if raw.get("retry_file_sha256") + else None + ), ) @@ -119,6 +142,9 @@ def record_result(self, index: int, result: AcquisitionResult) -> None: entry.bytes_written = result.bytes_written entry.resumed = result.resumed entry.error = result.error + entry.failure_stage = result.failure_stage + entry.retry_file_size = None + entry.retry_file_sha256 = None self.touch() def to_dict(self) -> dict[str, Any]: diff --git a/src/juice_lyrics/acquisition/models.py b/src/juice_lyrics/acquisition/models.py index 059620f..049fbad 100644 --- a/src/juice_lyrics/acquisition/models.py +++ b/src/juice_lyrics/acquisition/models.py @@ -18,6 +18,33 @@ class AcquisitionState(str, Enum): COMPLETE = "complete" +class AcquisitionFailureStage(str, Enum): + TRANSPORT = "transport" + VALIDATION = "validation" + LYRICS = "lyrics" + LRC = "lrc" + STATE = "state" + + @property + def is_post_processing(self) -> bool: + return self in {self.LYRICS, self.LRC, self.STATE} + + +class AcquisitionPostProcessingError(RuntimeError): + """A finalized download failed during a structured post-processing stage.""" + + def __init__( + self, + stage: AcquisitionFailureStage, + message: str, + *, + reuse_finalized_file: bool = True, + ) -> None: + super().__init__(message) + self.stage = stage + self.reuse_finalized_file = reuse_finalized_file + + @dataclass(slots=True) class AcquisitionItem: """One explicitly selected/authorized acquisition target.""" @@ -39,6 +66,8 @@ class AcquisitionResult: bytes_written: int = 0 resumed: bool = False error: str | None = None + failure_stage: AcquisitionFailureStage | None = None + postprocessing_retry: bool = False @property def ok(self) -> bool: diff --git a/src/juice_lyrics/acquisition/runner.py b/src/juice_lyrics/acquisition/runner.py index 03d5ed1..5c383f3 100644 --- a/src/juice_lyrics/acquisition/runner.py +++ b/src/juice_lyrics/acquisition/runner.py @@ -1,12 +1,19 @@ from __future__ import annotations from dataclasses import dataclass +import hashlib +from pathlib import Path from typing import Callable, Any from .downloader import DownloadPolicy, download_to from .duplicates import find_duplicate from .jobs import AcquisitionJob, JobStore -from .models import AcquisitionResult, AcquisitionState +from .models import ( + AcquisitionFailureStage, + AcquisitionPostProcessingError, + AcquisitionResult, + AcquisitionState, +) @dataclass(frozen=True, slots=True) @@ -28,6 +35,49 @@ def ok(self) -> bool: PostprocessCallback = Callable[[AcquisitionResult], Any] +def _sha256(path: Path, chunk_size: int = 1024 * 128) -> str: + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(chunk_size), b""): + digest.update(chunk) + return digest.hexdigest() + + +def _can_retry_postprocessing(entry: Any) -> bool: + stage = entry.failure_stage + if entry.state is not AcquisitionState.FAILED or stage is None or not stage.is_post_processing: + return False + destination = entry.item.destination + if not destination.is_file(): + return False + if entry.retry_file_size is None or not entry.retry_file_sha256: + return False + try: + actual_size = destination.stat().st_size + return ( + actual_size == entry.retry_file_size + and _sha256(destination) == entry.retry_file_sha256.lower() + ) + except OSError: + return False + + +def _record_postprocessing_failure(entry: Any, exc: AcquisitionPostProcessingError) -> None: + entry.state = AcquisitionState.FAILED + entry.error = str(exc) + entry.failure_stage = exc.stage + entry.retry_file_size = None + entry.retry_file_sha256 = None + destination = entry.item.destination + if exc.reuse_finalized_file and destination.is_file(): + try: + entry.retry_file_size = destination.stat().st_size + entry.retry_file_sha256 = _sha256(destination) + except OSError: + entry.retry_file_size = None + entry.retry_file_sha256 = None + + def run_job( job: AcquisitionJob, store: JobStore, @@ -35,6 +85,7 @@ def run_job( policy: DownloadPolicy | None = None, progress: ItemProgressCallback | None = None, postprocess: PostprocessCallback | None = None, + item_indexes: set[int] | None = None, ) -> AcquisitionRunSummary: """Run a persistent acquisition job one item at a time. @@ -51,10 +102,46 @@ def report(index: int, written: int, remote_total: int | None) -> None: progress(index, total, written, remote_total) for index, entry in enumerate(job.items): + if item_indexes is not None and index not in item_indexes: + continue if entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: continue + retry_postprocessing = postprocess is not None and _can_retry_postprocessing(entry) + + if retry_postprocessing: + result = AcquisitionResult( + item=entry.item, + state=AcquisitionState.COMPLETE, + destination=entry.item.destination, + bytes_written=entry.bytes_written, + resumed=entry.resumed, + postprocessing_retry=True, + ) + try: + if postprocess is not None: + postprocess(result) + job.record_result(index, result) + store.save(job) + except AcquisitionPostProcessingError as exc: + _record_postprocessing_failure(entry, exc) + entry.error = f"Post-processing retry from existing finalized file failed: {entry.error}" + job.touch() + store.save(job) + except Exception as exc: + entry.state = AcquisitionState.FAILED + entry.error = f"Post-processing retry from existing finalized file failed: {exc}" + entry.failure_stage = AcquisitionFailureStage.LYRICS + entry.retry_file_size = None + entry.retry_file_sha256 = None + job.touch() + store.save(job) + continue + entry.error = None + entry.failure_stage = None + entry.retry_file_size = None + entry.retry_file_sha256 = None entry.state = AcquisitionState.CHECKING_EXISTING entry.resumed = False job.touch() @@ -66,6 +153,7 @@ def report(index: int, written: int, remote_total: int | None) -> None: entry.state = AcquisitionState.SKIPPED entry.bytes_written = duplicate.path.stat().st_size entry.error = None + entry.failure_stage = None job.touch() store.save(job) continue @@ -86,12 +174,34 @@ def item_progress(written: int, remote_total: int | None) -> None: progress=item_progress, ) if result.state is AcquisitionState.COMPLETE and postprocess is not None: - postprocess(result) + try: + postprocess(result) + except AcquisitionPostProcessingError as exc: + entry.bytes_written = result.bytes_written + entry.resumed = result.resumed + _record_postprocessing_failure(entry, exc) + job.touch() + store.save(job) + continue + except Exception as exc: + entry.state = AcquisitionState.FAILED + entry.bytes_written = result.bytes_written + entry.resumed = result.resumed + entry.error = f"Audio download completed, but post-processing failed: {exc}" + entry.failure_stage = AcquisitionFailureStage.LYRICS + entry.retry_file_size = None + entry.retry_file_sha256 = None + job.touch() + store.save(job) + continue job.record_result(index, result) store.save(job) except Exception as exc: # keep one bad item from killing the whole job entry.state = AcquisitionState.FAILED entry.error = str(exc) + entry.failure_stage = AcquisitionFailureStage.TRANSPORT + entry.retry_file_size = None + entry.retry_file_sha256 = None job.touch() store.save(job) diff --git a/src/juice_lyrics/api/client.py b/src/juice_lyrics/api/client.py index 1eb45d6..44ec4d9 100644 --- a/src/juice_lyrics/api/client.py +++ b/src/juice_lyrics/api/client.py @@ -1,11 +1,12 @@ from __future__ import annotations +import hashlib import json import time from pathlib import Path from typing import Any from urllib.error import HTTPError, URLError -from urllib.parse import quote +from urllib.parse import quote, urlencode from urllib.request import Request, urlopen from .. import __version__ @@ -41,30 +42,93 @@ def api_get(url: str, timeout: int) -> Any: raise RuntimeError("The API returned invalid JSON") from exc -def search_songs(settings: Settings, query: str, *, category: str | None = None, era: str | None = None, refresh: bool = False) -> dict[str, Any]: - params = [f"search={quote(query)}", "page_size=50"] - if category: - params.append(f"category={quote(category)}") - if era: - params.append(f"era={quote(era)}") - cache_name = "advanced_" + cache_key("|".join(params)) + ".json" +def _cached_get(settings: Settings, url: str, cache_name: str, refresh: bool) -> Any: cache_file = CACHE_DIR / cache_name ensure_cache() ttl = settings.cache_ttl_hours * 3600 if not refresh and cache_file.exists() and time.time() - cache_file.stat().st_mtime <= ttl: try: - cached = json.loads(cache_file.read_text(encoding="utf-8")) - if isinstance(cached, dict): - return cached + return json.loads(cache_file.read_text(encoding="utf-8")) except Exception: pass - data = api_get(f"{settings.songs_endpoint}?{'&'.join(params)}", settings.timeout) - result = data if isinstance(data, dict) else {"results": []} - cache_file.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + data = api_get(url, settings.timeout) + cache_file.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8") time.sleep(settings.delay) + return data + + +def search_songs( + settings: Settings, + query: str, + *, + category: str | None = None, + era: str | None = None, + page: int = 1, + page_size: int = 50, + refresh: bool = False, +) -> dict[str, Any]: + params: list[tuple[str, str | int]] = [ + ("search", query), + ("page_size", page_size), + ("page", page), + ] + if category: + params.append(("category", category)) + if era: + params.append(("era", era)) + query_string = urlencode(params) + # API filter values are case-sensitive (for example, ``DRFL`` works while + # ``drfl`` does not), so the cache identity must preserve the exact query. + query_digest = hashlib.sha256(query_string.encode("utf-8")).hexdigest()[:24] + cache_name = f"catalogue_v3_{query_digest}.json" + data = _cached_get( + settings, + f"{settings.songs_endpoint}?{query_string}", + cache_name, + refresh, + ) + result = data if isinstance(data, dict) else {"results": []} return result +def get_categories(settings: Settings, *, refresh: bool = False) -> dict[str, Any]: + """Return the API's canonical category values and display labels.""" + + data = _cached_get( + settings, + settings.api_base.rstrip("/") + "/categories/", + "catalogue_categories_v1.json", + refresh, + ) + return data if isinstance(data, dict) else {"categories": []} + + +def get_eras(settings: Settings, *, refresh: bool = False) -> list[dict[str, Any]]: + """Read every small era-metadata page without using the song catalogue.""" + + eras: list[dict[str, Any]] = [] + page = 1 + while True: + query_string = urlencode({"page": page, "page_size": 100}) + data = _cached_get( + settings, + settings.api_base.rstrip("/") + f"/eras/?{query_string}", + f"catalogue_eras_v1_page_{page}.json", + refresh, + ) + if not isinstance(data, dict): + break + values = data.get("results", []) + if isinstance(values, list): + eras.extend(value for value in values if isinstance(value, dict)) + if not data.get("next"): + break + page += 1 + if page > 20: + raise RuntimeError("Era metadata pagination exceeded the safety limit") + return eras + + def search_song_names(settings: Settings, title: str, *, refresh: bool = False) -> list[dict[str, Any]]: data = search_songs(settings, title, refresh=refresh) results = data.get("results", []) if isinstance(data, dict) else [] diff --git a/src/juice_lyrics/backup/manager.py b/src/juice_lyrics/backup/manager.py index c7deba0..76f6be7 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -1,25 +1,201 @@ from __future__ import annotations -import json, shutil + +import json +import logging +import os +import shutil +import tempfile +from collections.abc import Callable +from dataclasses import dataclass from datetime import datetime, timezone from pathlib import Path from typing import Any + from ..config.settings import BACKUP_DIR, DATA_DIR -def ensure_data_dirs(): - DATA_DIR.mkdir(parents=True,exist_ok=True); BACKUP_DIR.mkdir(parents=True,exist_ok=True) +BACKUP_RETENTION_COUNT = 10 +BACKUP_AUDIO_SUFFIXES = frozenset({".mp3", ".flac", ".m4a"}) + +logger = logging.getLogger(__name__) + + +def _backup_audio_files(root: Path) -> tuple[Path, ...]: + return tuple( + path + for path in root.rglob("*") + if path.is_file() and path.suffix.casefold() in BACKUP_AUDIO_SUFFIXES + ) + + +@dataclass(frozen=True, slots=True) +class BackupRecord: + """A completed backup with an authoritative manifest timestamp.""" + + path: Path + created_at: datetime + + @property + def file_count(self) -> int: + """Number of restorable audio files in this valid backup.""" + + try: + return len(_backup_audio_files(self.path)) + except OSError: + return 0 + + +@dataclass(frozen=True, slots=True) +class BackupPruneResult: + """Conservative result of applying rolling backup retention.""" + + removed: tuple[Path, ...] = () + error: str | None = None + + +def ensure_data_dirs() -> None: + DATA_DIR.mkdir(parents=True, exist_ok=True) + BACKUP_DIR.mkdir(parents=True, exist_ok=True) + + +def now_iso() -> str: + return datetime.now(timezone.utc).isoformat() + + +def make_backup_root() -> Path: + ensure_data_dirs() + stem = datetime.now().strftime("%Y%m%d-%H%M%S") + for counter in range(10_000): + suffix = "" if counter == 0 else f"-{counter:02d}" + root = BACKUP_DIR / f"{stem}{suffix}" + try: + root.mkdir(parents=True, exist_ok=False) + except FileExistsError: + continue + return root + raise RuntimeError("Could not allocate a unique backup directory.") + + +def backup_file(path: Path, root: Path, base: Path) -> Path: + destination = root / path.relative_to(base) + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(path, destination) + return destination + + +def restore_file(backup: Path, destination: Path) -> None: + destination.parent.mkdir(parents=True, exist_ok=True) + descriptor, temporary_name = tempfile.mkstemp( + prefix=f".{destination.name}.", suffix=".restore", dir=destination.parent + ) + os.close(descriptor) + temporary = Path(temporary_name) + try: + shutil.copy2(backup, temporary) + os.replace(temporary, destination) + finally: + temporary.unlink(missing_ok=True) + + +def _manifest_created_at(root: Path) -> datetime | None: + """Return a completed backup's timestamp without trusting its filename.""" + + if not root.is_dir() or root.is_symlink(): + return None + try: + manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8")) + raw_created = manifest.get("created") if isinstance(manifest, dict) else None + if not isinstance(raw_created, str): + return None + files = manifest.get("files") + if not (isinstance(files, list) and files) and not _backup_audio_files(root): + return None + created_at = datetime.fromisoformat(raw_created.replace("Z", "+00:00")) + except (OSError, ValueError, json.JSONDecodeError): + return None + if created_at.tzinfo is None: + created_at = created_at.replace(tzinfo=timezone.utc) + return created_at.astimezone(timezone.utc) + + +def list_backups(backup_dir: Path = BACKUP_DIR) -> tuple[BackupRecord, ...]: + """List completed backups oldest-first without modifying the directory.""" + + directory = Path(backup_dir) + if not directory.is_dir(): + return () + try: + children = tuple(directory.iterdir()) + except OSError: + return () + records: list[BackupRecord] = [] + for child in children: + created_at = _manifest_created_at(child) + if created_at is not None: + records.append(BackupRecord(child, created_at)) + return tuple(sorted(records, key=lambda record: (record.created_at, record.path.name))) + + +def prune_backup_history( + backup_dir: Path = BACKUP_DIR, + *, + keep: int = BACKUP_RETENTION_COUNT, + protected: Path | None = None, + remover: Callable[[Path], None] = shutil.rmtree, +) -> BackupPruneResult: + """Keep the newest completed backups and stop on the first prune failure.""" + + if keep < 0: + raise ValueError("keep must not be negative") + records = list_backups(Path(backup_dir)) + newest = {record.path for record in records[-keep:]} if keep else set() + if protected is not None: + newest.add(Path(protected)) + candidates = [record.path for record in records if record.path not in newest] + + removed: list[Path] = [] + for candidate in candidates: + try: + remover(candidate) + except Exception as exc: + return BackupPruneResult( + tuple(removed), + f"could not remove old backup {candidate}: {exc}", + ) + removed.append(candidate) + return BackupPruneResult(tuple(removed)) -def now_iso(): return datetime.now(timezone.utc).isoformat() -def make_backup_root(): ensure_data_dirs(); root=BACKUP_DIR/datetime.now().strftime("%Y%m%d-%H%M%S"); root.mkdir(parents=True,exist_ok=True); return root +def write_manifest(root: Path, entries: list[dict[str, Any]]) -> None: + """Finalize a backup, then apply retention without invalidating that backup.""" -def backup_file(path:Path,root:Path,base:Path)->Path: - dest=root/path.relative_to(base); dest.parent.mkdir(parents=True,exist_ok=True); shutil.copy2(path,dest); return dest + (root / "manifest.json").write_text( + json.dumps( + {"created": now_iso(), "files": entries}, + indent=2, + ensure_ascii=False, + ), + encoding="utf-8", + ) + # Some batch failures occur after the pristine audio was copied but before + # its manifest entry was assembled. That copy is still a recoverable + # backup. Conversely, an empty root after every copy failed must not + # trigger deletion of older backups. + try: + has_backup_file = bool(entries) or bool(_backup_audio_files(root)) + except OSError as exc: + logger.warning("Backup created, but retention cleanup could not inspect it: %s", exc) + return + if not has_backup_file: + return + result = prune_backup_history(root.parent, protected=root) + if result.error: + logger.warning("Backup created, but retention cleanup failed: %s", result.error) -def write_manifest(root:Path, entries:list[dict[str,Any]]): - (root/"manifest.json").write_text(json.dumps({"created":now_iso(),"files":entries},indent=2,ensure_ascii=False),encoding="utf-8") -def restore_backup(root:Path, base:Path)->int: - restored=0 - for src in root.rglob("*.mp3"): - dst=base/src.relative_to(root); dst.parent.mkdir(parents=True,exist_ok=True); shutil.copy2(src,dst); restored+=1 +def restore_backup(root: Path, base: Path) -> int: + restored = 0 + for source in _backup_audio_files(root): + destination = base / source.relative_to(root) + restore_file(source, destination) + restored += 1 return restored diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index d21bc40..83a1048 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -9,6 +9,7 @@ import shutil import subprocess import sys +import tempfile import time from datetime import datetime, timezone from pathlib import Path @@ -21,8 +22,12 @@ from mutagen.mp3 import MP3 from . import __version__ +from .config.settings import DEFAULT_LYRICS_DIR +from .identity import PRODUCT_NAME, STORAGE_NAMESPACE +from .lyrics.sidecar import sidecar_lrc_path +from .services.shell_completion import generate_completion -APP_NAME = "juice-lyrics" +APP_NAME = PRODUCT_NAME DEFAULT_API_BASE = "https://juicewrldapi.com/juicewrld" DEFAULT_MUSIC_DIR = Path.home() / "Music" / "Juice WRLD" / "Unreleased" DEFAULT_DESCRIPTION = "Juice WRLD API" @@ -58,18 +63,18 @@ def xdg_dir(name: str, fallback: Path) -> Path: CONFIG_HOME = xdg_dir("XDG_CONFIG_HOME", Path.home() / ".config") CACHE_HOME = xdg_dir("XDG_CACHE_HOME", Path.home() / ".cache") DATA_HOME = xdg_dir("XDG_DATA_HOME", Path.home() / ".local" / "share") -CONFIG_FILE = CONFIG_HOME / APP_NAME / "config.toml" -CACHE_DIR = CACHE_HOME / APP_NAME -DATA_DIR = DATA_HOME / APP_NAME +CONFIG_FILE = CONFIG_HOME / STORAGE_NAMESPACE / "config.toml" +CACHE_DIR = CACHE_HOME / STORAGE_NAMESPACE +DATA_DIR = DATA_HOME / STORAGE_NAMESPACE BACKUP_DIR = DATA_DIR / "backups" STATE_FILE = DATA_DIR / "state.json" -DEFAULT_RMPC_LYRICS_DIR = DEFAULT_MUSIC_DIR.parent / "lyrics" DEFAULT_RMPC_CONFIG = CONFIG_HOME / "rmpc" / "config.ron" class Settings: def __init__(self) -> None: self.music_dir = DEFAULT_MUSIC_DIR + self.lyrics_dir = DEFAULT_LYRICS_DIR self.api_base = DEFAULT_API_BASE self.timeout = DEFAULT_TIMEOUT self.delay = DEFAULT_DELAY @@ -103,6 +108,9 @@ def load_settings(path_override: str | None = None, api_override: str | None = N data = tomllib.loads(CONFIG_FILE.read_text(encoding="utf-8")) if data.get("music_dir"): settings.music_dir = Path(str(data["music_dir"])).expanduser() + if data.get("lyrics_dir"): + settings.lyrics_dir = Path(str(data["lyrics_dir"])).expanduser() + settings.lyrics_dir_explicit = True settings.api_base = str(data.get("api_base", settings.api_base)).rstrip("/") settings.timeout = int(data.get("timeout", settings.timeout)) settings.delay = float(data.get("delay", settings.delay)) @@ -232,8 +240,8 @@ def search_api(settings: Settings, title: str, refresh: bool = False) -> list[di return results -def search_api_advanced(settings: Settings, query: str, category: str | None = None, era: str | None = None, refresh: bool = False) -> dict[str, Any]: - params = [f"search={quote(query)}", "page_size=50"] +def search_api_advanced(settings: Settings, query: str, category: str | None = None, era: str | None = None, page: int = 1, page_size: int = 50, refresh: bool = False) -> dict[str, Any]: + params = [f"search={quote(query)}", f"page_size={page_size}", f"page={page}"] if category: params.append(f"category={quote(category)}") if era: @@ -479,30 +487,6 @@ def first_text(frame_id: str) -> str: return {"artist": artist, "title": title, "album": album, "length": f"{minutes:02d}:{seconds:02d}.{centiseconds:02d}"} -def write_lrc(path: Path, analysis: dict[str, Any], out_dir: Path) -> Path: - synced = analysis.get("synced") or [] - candidate = analysis.get("candidate") or {} - if not synced: - raise ValueError("No synchronized lyrics available") - meta = read_mp3_metadata(path, candidate) - out_dir.mkdir(parents=True, exist_ok=True) - out_file = out_dir / f"{path.stem}.lrc" - lines = [f"[ar:{meta['artist'].replace(']', '}')}]", f"[ti:{meta['title'].replace(']', '}')}]"] - if meta["album"]: - lines.append(f"[al:{meta['album'].replace(']', '}')}]") - lines.append(f"[length:{meta['length']}]") - lines.append("") - for text, timestamp_ms in synced: - cs = max(0, int(round(timestamp_ms / 10))) - minutes, remainder = divmod(cs, 6000) - seconds, centiseconds = divmod(remainder, 100) - lines.append(f"[{minutes:02d}:{seconds:02d}.{centiseconds:02d}] {text}") - tmp = out_file.with_suffix(".lrc.tmp") - tmp.write_text("\n".join(lines) + "\n", encoding="utf-8") - tmp.replace(out_file) - return out_file - - def patch_rmpc_config(config_path: Path, lyrics_dir: Path) -> Path: if not config_path.exists(): raise RuntimeError(f"rmpc config not found: {config_path}") @@ -548,17 +532,21 @@ def notify_rmpc_index(paths: list[Path]) -> int: return count -def configured_rmpc_lyrics_dir() -> Path: - return DEFAULT_RMPC_LYRICS_DIR - - def write_state_entry(state: dict[str, Any], path: Path, settings: Settings, analysis: dict[str, Any], lrc_path: Path | None) -> None: relative = str(path.relative_to(settings.music_dir)) state.setdefault("files", {})[relative] = { "sha256": sha256_file(path), "song_id": analysis["candidate"].get("id") if analysis.get("candidate") else None, "api_name": analysis["candidate"].get("name") if analysis.get("candidate") else None, - "lyric_type": "SYLT" if analysis.get("synced") else ("USLT" if analysis.get("plain") else "NONE"), + "lyric_type": ( + "FLAC_LYRICS_SYNCED" if analysis.get("synced") else "FLAC_LYRICS_PLAIN" + ) if path.suffix.casefold() == ".flac" else ( + ( + "M4A_LYRICS_SYNCED" if analysis.get("synced") else "M4A_LYRICS_PLAIN" + ) if path.suffix.casefold() == ".m4a" else ( + "SYLT" if analysis.get("synced") else ("USLT" if analysis.get("plain") else "NONE") + ) + ), "lrc": str(lrc_path) if lrc_path else None, "updated": now_iso(), } @@ -577,16 +565,18 @@ def state_is_current(state: dict[str, Any], path: Path, settings: Settings, want valid, _ = verify_file(path) if not valid: return False - if want_rmpc and entry.get("lyric_type") == "SYLT": - lrc = Path(entry.get("lrc") or "") - if not lrc.is_file(): + if want_rmpc and entry.get("lyric_type") in { + "SYLT", + "FLAC_LYRICS_SYNCED", + "M4A_LYRICS_SYNCED", + }: + if not sidecar_lrc_path(path).is_file(): return False return True def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: bool, dry_run: bool, yes: bool, with_rmpc: bool) -> int: state = load_state() - lyric_dir = configured_rmpc_lyrics_dir() if with_rmpc else None work: list[dict[str, Any]] = [] skipped_unchanged = 0 for index, path in enumerate(files, 1): @@ -637,7 +627,7 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: if not sys.stdin.isatty(): print("Non-interactive mode: use --yes to confirm synchronization.") return 2 - if input(f"Apply lyrics to {len(ready)} changed/new MP3(s)? [y/N] ").strip().lower() not in {"y", "yes"}: + if input(f"Apply lyrics to {len(ready)} changed/new audio file(s)? [y/N] ").strip().lower() not in {"y", "yes"}: print("Cancelled. No files changed.") return 0 backup_root = make_backup_root() @@ -657,7 +647,7 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: raise RuntimeError(f"verification failed: {message}") lrc_path = None if with_rmpc and analysis["synced"]: - lrc_path = write_lrc(path, analysis, lyric_dir) # type: ignore[arg-type] + lrc_path = write_lrc(path, analysis) generated_lrc.append(lrc_path) write_state_entry(state, path, settings, analysis, lrc_path) manifest.append({"file": str(path), "sha256_before": original_hash, "lyric_type": lyric_type, "verification": message}) @@ -703,14 +693,45 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: from .backup.manager import make_backup_root as _make_backup_root, backup_file as _backup_file, write_manifest as _write_manifest, restore_backup as _restore_backup from .state import load_state as _load_state, save_state as _save_state, sha256_file as _sha256_file from .rmpc.integration import patch_rmpc_config as _patch_rmpc_config, rmpc_running as _rmpc_running, notify_rmpc_index as _notify_rmpc_index +from .services.library_status import get_library_status +from .services.catalogue import get_song_details, search_catalogue +from .services.acquisition_queue import get_queue_snapshot +from .services.library_sync import ( + LibrarySyncOptions, + MatchOutcome, + SyncEventKind, + execute_library_sync, + plan_library_sync, +) +from .services.state_maintenance import ( + execute_stale_state_cleanup, + plan_stale_state_cleanup, +) +from .services.identity_rebuild import ( + execute_catalogue_identity_rebuild, + plan_catalogue_identity_rebuild, +) +from .services.doctor import ( + DoctorStatus, + render_support_report, + run_doctor, +) def search_api(settings: Settings, title: str, refresh: bool = False) -> list[dict[str, Any]]: return _api_search_song_names(settings, title, refresh=refresh) -def search_api_advanced(settings: Settings, query: str, category: str | None = None, era: str | None = None, refresh: bool = False) -> dict[str, Any]: - return _api_search_songs(settings, query, category=category, era=era, refresh=refresh) +def search_api_advanced(settings: Settings, query: str, category: str | None = None, era: str | None = None, page: int = 1, page_size: int = 50, refresh: bool = False) -> dict[str, Any]: + return _api_search_songs( + settings, + query, + category=category, + era=era, + page=page, + page_size=page_size, + refresh=refresh, + ) def get_song(settings: Settings, song_id: int) -> dict[str, Any]: @@ -741,8 +762,14 @@ def get_song(settings: Settings, song_id: int) -> dict[str, Any]: notify_rmpc_index = _notify_rmpc_index -def write_lrc(path: Path, analysis: dict[str, Any], out_dir: Path) -> Path: - return _write_lrc(path, analysis.get("synced") or [], analysis.get("candidate") or {}, out_dir) +def write_lrc( + path: Path, + analysis: dict[str, Any], + out_dir: Path | None = None, +) -> Path: + """Write a sidecar LRC; ``out_dir`` is ignored for CLI compatibility.""" + + return _write_lrc(path, analysis.get("synced") or [], analysis.get("candidate") or {}) def load_settings(path_override: str | None = None, api_override: str | None = None) -> Settings: @@ -753,6 +780,9 @@ def load_settings(path_override: str | None = None, api_override: str | None = N data = tomllib.loads(CONFIG_FILE.read_text(encoding="utf-8")) if data.get("music_dir"): settings.music_dir = Path(str(data["music_dir"])).expanduser() + if data.get("lyrics_dir"): + settings.lyrics_dir = Path(str(data["lyrics_dir"])).expanduser() + settings.lyrics_dir_explicit = True settings.api_base = str(data.get("api_base", settings.api_base)).rstrip("/") settings.timeout = int(data.get("timeout", settings.timeout)) settings.delay = float(data.get("delay", settings.delay)) @@ -767,7 +797,7 @@ def load_settings(path_override: str | None = None, api_override: str | None = N return settings def command_setup(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - print_header("juice-lyrics First-Time Setup", use_color) + print_header("999 Library Setup", use_color) print(f"Library: {settings.music_dir}") if not settings.music_dir.is_dir(): raise RuntimeError(f"Music directory does not exist: {settings.music_dir}") @@ -777,61 +807,117 @@ def command_setup(args: argparse.Namespace, settings: Settings, use_color: bool) if not sys.stdin.isatty(): print("Non-interactive mode: use --yes to confirm setup.") return 2 - print("\nSetup will use the library, embed lyrics, and configure rmpc when detected.") + print("\nSetup will synchronize lyrics in the library.") + print("It will not change rmpc configuration; use `999 rmpc setup` for that.") if input("Continue? [Y/n] ").strip().lower() not in {"", "y", "yes"}: print("Cancelled.") return 0 - if rmpc_available: - patch_rmpc_config(DEFAULT_RMPC_CONFIG, DEFAULT_RMPC_LYRICS_DIR) - DEFAULT_RMPC_LYRICS_DIR.mkdir(parents=True, exist_ok=True) files = find_mp3s(settings) return embed_batch(settings, files, use_color, args.refresh, False, True, rmpc_available) def command_sync(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - files = find_mp3s(settings) rmpc_enabled = args.no_rmpc is False - if rmpc_enabled and shutil.which("rmpc") is not None and DEFAULT_RMPC_CONFIG.exists(): - DEFAULT_RMPC_LYRICS_DIR.mkdir(parents=True, exist_ok=True) - # Ensure the config points at our folder, but do not rewrite it on every sync. - text = DEFAULT_RMPC_CONFIG.read_text(encoding="utf-8") - if str(DEFAULT_RMPC_LYRICS_DIR) not in text: - patch_rmpc_config(DEFAULT_RMPC_CONFIG, DEFAULT_RMPC_LYRICS_DIR) - elif rmpc_enabled: + if rmpc_enabled and not (shutil.which("rmpc") is not None and DEFAULT_RMPC_CONFIG.exists()): rmpc_enabled = False - return embed_batch(settings, files, use_color, args.refresh, args.dry_run, args.yes, rmpc_enabled) + options = LibrarySyncOptions.from_settings( + settings, + dry_run=args.dry_run, + refresh=args.refresh, + rmpc_enabled=rmpc_enabled, + lyrics_dir=None, + rmpc_config_path=DEFAULT_RMPC_CONFIG if rmpc_enabled else None, + state_file=STATE_FILE, + ) + + def scan_progress(event): + if event.kind is SyncEventKind.TRACK_INSPECTED and event.path is not None: + suffix = " (unchanged)" if event.message == "unchanged" else "" + print(f"\rScanning: [{event.index:>2}/{event.total}] {event.path.name:<42}{suffix}", end="", flush=True) + elif event.kind is SyncEventKind.TRACK_FAILED and event.path is not None: + print() + print(colorize(f"✗ {event.path.name} — {event.message}", RED, use_color)) + + plan = plan_library_sync(options, progress=scan_progress) + if plan.total_files: + print("\r" + " " * 100 + "\r", end="") + print_header("Library Sync", use_color) + print(f"Changed/new: {plan.changed_or_new_files}") + print(f"Unchanged: {plan.unchanged_files}") + print(f"Ready: {plan.ready_files}") + print(f" Synced: {plan.synced_files}") + print(f" Plain fallback: {plan.plain_files}") + if rmpc_enabled: + print(f"rmpc LRC ready: {plan.synced_files}") + print(f"Unresolved: {plan.unresolved_files}") + print(f"No lyrics: {plan.no_lyrics_files}") + unresolved = [track for track in plan.tracks if track.outcome is MatchOutcome.UNRESOLVED] + no_lyrics = [track for track in plan.tracks if track.outcome is MatchOutcome.NO_LYRICS] + if unresolved: + print(colorize("Unresolved:", YELLOW, use_color)) + for track in unresolved: + print(f" - {track.path.name}") + if no_lyrics: + print(colorize("No lyrics:", YELLOW, use_color)) + for track in no_lyrics: + print(f" - {track.path.name}") + if args.dry_run: + sidecars = [track.lrc_path for track in plan.tracks if track.lrc_path is not None] + if sidecars: + print("LRC sidecars:") + for sidecar in sidecars: + print(f" - {sidecar}") + print(colorize("\nDry run: no files changed.", CYAN, use_color)) + return 0 + if not plan.ready_files: + execute_library_sync(plan) + print("Nothing needs updating.") + return 0 + if not args.yes: + if not sys.stdin.isatty(): + print("Non-interactive mode: use --yes to confirm synchronization.") + return 2 + if input(f"Apply lyrics to {plan.ready_files} changed/new audio file(s)? [y/N] ").strip().lower() not in {"y", "yes"}: + print("Cancelled. No files changed.") + return 0 + + def execution_progress(event): + if event.kind is SyncEventKind.TRACK_COMPLETED and event.path is not None: + print(colorize(f"✓ {event.path.name}", GREEN, use_color) + f" → {event.message}") + elif event.kind is SyncEventKind.TRACK_FAILED and event.path is not None: + print(colorize(f"✗ {event.path.name} — {event.message}", RED, use_color)) + + result = execute_library_sync(plan, progress=execution_progress) + print() + print(colorize("Sync complete", BOLD, use_color)) + print(f" Updated: {result.updated_files}") + print(f" Unchanged: {plan.unchanged_files}") + print(f" rmpc LRC files: {result.lrc_files_generated}") + if result.rmpc_notifications: + print(f" rmpc notified: {result.rmpc_notifications}") + print(f" Errors: {result.processing_failed_files}") + print(f" Backup: {result.backup_path}") + return 1 if result.processing_failed_files else 0 def command_status(settings: Settings, use_color: bool) -> int: - files = find_mp3s(settings) - state = load_state() - synced = plain = missing = stale = 0 - lrc = 0 - for path in files: - valid, msg = verify_file(path) - if valid: - if msg.startswith("SYLT"): - synced += 1 - else: - plain += 1 - else: - missing += 1 - rel = str(path.relative_to(settings.music_dir)) - entry = state.get("files", {}).get(rel) - if not entry or entry.get("sha256") != sha256_file(path): - stale += 1 - if entry and entry.get("lrc") and Path(entry["lrc"]).is_file(): - lrc += 1 + status = get_library_status( + settings, + state_file=STATE_FILE, + backup_dir=BACKUP_DIR, + verifier=verify_file, + ) print_header("Library Status", use_color) - print(f"Library: {settings.music_dir}") - print(f"MP3 files: {len(files)}") - print(f"Embedded synced: {synced}") - print(f"Embedded plain: {plain}") - print(f"Missing/invalid: {missing}") - print(f"rmpc LRC files: {lrc}") - print(f"New/changed for sync: {stale}") - print(f"Backups: {len([p for p in BACKUP_DIR.iterdir() if p.is_dir()]) if BACKUP_DIR.exists() else 0}") - return 1 if missing else 0 + print(f"Library: {status.library_path}") + print("External lyrics: Beside each song (.lrc)") + print(f"Audio files: {status.track_count}") + print(f"Embedded synced: {status.embedded_synced_count}") + print(f"Embedded plain: {status.embedded_plain_count}") + print(f"Missing/invalid: {status.missing_or_invalid_count}") + print(f"rmpc LRC files: {status.rmpc_lrc_count}") + print(f"New/changed for sync: {status.new_or_changed_count}") + print(f"Backups: {status.backup_count}") + return 1 if status.missing_or_invalid_count else 0 def command_scan(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: @@ -858,13 +944,22 @@ def command_scan(args: argparse.Namespace, settings: Settings, use_color: bool) counts[kind] += 1 if files: print("\r" + " " * 100 + "\r", end="") - print(f"Synced: {counts['SYNCED']} Plain: {counts['PLAIN']} No lyrics: {counts['NONE']} Uncertain: {counts['?']}") + print( + f"Synced: {counts['SYNCED']} Plain: {counts['PLAIN']} " + f"No lyrics: {counts['NONE']} Catalogue uncertain: {counts['?']}" + ) return 1 if counts["?"] else 0 def command_search(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - data = search_api_advanced(settings, args.query, args.category, args.era, args.refresh) - results = data.get("results", []) + results = search_catalogue( + settings, + args.query, + category=args.category, + era=args.era, + refresh=args.refresh, + searcher=search_api_advanced, + ) print_header(f'Juice WRLD API Search: "{args.query}"', use_color) if args.category or args.era: filters = [] @@ -874,47 +969,36 @@ def command_search(args: argparse.Namespace, settings: Settings, use_color: bool if not results: print("No results.") return 0 - for idx, song in enumerate(results, 1): - synced = bool(str(song.get("synced_lyrics") or "").strip()) - plain = bool(str(song.get("lyrics") or "").strip()) - lyrics = "SYNCED" if synced else ("PLAIN" if plain else "NONE") - path = str(song.get("path") or "") - era_val = song.get("era") - era_str = era_val.get("name", "") if isinstance(era_val, dict) else str(era_val or "") - print(f"{idx:>2}. {song.get('name', 'Unknown')} [{song.get('category', '?')}] [{lyrics}]") - print(f" id={song.get('id')} era={era_str} length={song.get('length') or '?'}") - if path: - print(f" {path}") + for song in results: + print(f"{song.selection_index:>2}. {song.title or 'Unknown'} [{song.category or '?'}] [{song.lyrics.value.upper()}]") + print(f" id={song.song_id} era={song.era or ''} length={song.length or '?'}") + if song.media_path: + print(f" {song.media_path}") return 0 def command_info(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - results = search_api(settings, args.query, refresh=args.refresh) - if not results: + details = get_song_details( + settings, + args.query, + selection_index=args.index, + refresh=args.refresh, + searcher=search_api, + details_fetcher=get_song, + ) + if details is None: print("No results.") return 1 - candidate = results[0] - if args.index: - if args.index < 1 or args.index > len(results): - raise RuntimeError("--index is outside the result list") - candidate = results[args.index - 1] - if candidate.get("id"): - try: - candidate = get_song(settings, int(candidate["id"])) - except Exception: - pass - print_header(str(candidate.get("name", "Song")), use_color) - era_val = candidate.get("era") - era_str = era_val.get("name", "") if isinstance(era_val, dict) else str(era_val or "") + print_header(details.title or "Song", use_color) fields = [ - ("ID", candidate.get("id")), - ("Category", candidate.get("category")), - ("Era", era_str), - ("Length", candidate.get("length")), - ("Artist", candidate.get("credited_artists")), - ("Producers", candidate.get("producers")), - ("Path", candidate.get("path")), - ("Lyrics", "synced" if candidate.get("synced_lyrics") else ("plain" if candidate.get("lyrics") else "none")), + ("ID", details.song_id), + ("Category", details.category), + ("Era", details.era), + ("Length", details.length), + ("Artist", ", ".join(details.artists)), + ("Producers", ", ".join(details.producers)), + ("Path", details.media_path), + ("Lyrics", details.lyrics.value), ] for key, value in fields: if value not in (None, ""): @@ -925,40 +1009,36 @@ def command_info(args: argparse.Namespace, settings: Settings, use_color: bool) def command_guide() -> int: print(f"""{APP_NAME} quick guide -FIRST TIME - juice-lyrics setup +OPEN THE APP + 999 NORMAL USE - juice-lyrics sync - juice-lyrics status - -ACQUISITION - juice-lyrics acquire search "rental" - juice-lyrics acquire add "rental" --index 1 - juice-lyrics acquire manifest manifest.txt - juice-lyrics acquire jobs - juice-lyrics acquire run - juice-lyrics acquire retry - juice-lyrics acquire delete + 999 status + 999 sync --dry-run + 999 sync + +OPTIONAL SETUP + 999 config init + 999 rmpc setup CHECK / TROUBLESHOOT - juice-lyrics scan - juice-lyrics verify - juice-lyrics doctor - juice-lyrics guide + 999 verify + 999 rmpc verify + 999 doctor + 999 guide FIND SONGS IN THE API - juice-lyrics search "rental" - juice-lyrics search --category unreleased --era DRFL "moncler" - juice-lyrics info "rental" + 999 search "rental" + 999 search --category unreleased --era DRFL "moncler" + 999 info "rental" UNDO - juice-lyrics restore + 999 restore WHAT SYNC DOES - 1. Matches new/changed MP3s to the API. - 2. Prefers synced lyrics (SYLT). - 3. Falls back to normal embedded lyrics (USLT). + 1. Matches new/changed MP3, FLAC, and M4A files to the API. + 2. Prefers synchronized lyrics and adjacent LRC files. + 3. Embeds supported lyrics without converting audio. 4. Generates .lrc files for rmpc when synced lyrics exist. 5. Backs up files before changing them. 6. Verifies the result. @@ -999,29 +1079,68 @@ def command_restore(args: argparse.Namespace, settings: Settings, use_color: boo if input("Restore this backup? [y/N] ").strip().lower() not in {"y", "yes"}: print("Cancelled."); return 0 count = restore_backup(root, settings.music_dir) - print(f"Restored {count} MP3s.") + print(f"Restored {count} audio file(s).") return 0 def command_doctor(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - print_header("juice-lyrics Doctor", use_color) - problems = 0 - print(f"Version: {__version__}\nPython: {sys.version.split()[0]}\nMutagen: OK\nLibrary: {settings.music_dir}") - if not settings.music_dir.is_dir(): problems += 1; print(colorize(" Library directory does not exist", RED, use_color)) - try: - api_get(settings.api_base.rstrip("/") + "/", settings.timeout); print("API: OK") - except Exception as exc: - problems += 1; print(colorize(f"API: FAILED ({exc})", RED, use_color)) - print(f"Config: {CONFIG_FILE}\nCache: {CACHE_DIR}\nState: {STATE_FILE}\nBackups: {BACKUP_DIR}") - return 1 if problems else 0 - - -def command_config(args: argparse.Namespace) -> int: + report = run_doctor( + settings, + config_path=CONFIG_FILE, + state_file=STATE_FILE, + cache_dir=CACHE_DIR, + backup_dir=BACKUP_DIR, + rmpc_config_path=DEFAULT_RMPC_CONFIG, + ) + support_text = render_support_report(report) + if args.support_report: + print(support_text) + else: + print_header("999 Doctor", use_color) + colors = { + DoctorStatus.PASS: GREEN, + DoctorStatus.WARN: YELLOW, + DoctorStatus.FAIL: RED, + } + for check in report.checks: + prefix = colorize(f"{check.status.value:<4}", colors[check.status], use_color) + print(f"{prefix} {check.label}: {check.detail}") + if check.suggestion: + print(f" Suggestion: {check.suggestion}") + print(f"\nSummary: {report.passed} PASS · {report.warned} WARN · {report.failed} FAIL") + print("No audio, state, cache, configuration, backups, downloads, or rmpc settings were changed.") + if args.save_report: + destination = Path(args.save_report).expanduser() + temporary: Path | None = None + try: + descriptor, temporary_name = tempfile.mkstemp( + prefix=f".{destination.name}.", suffix=".tmp", dir=destination.parent + ) + os.close(descriptor) + temporary = Path(temporary_name) + temporary.write_text(support_text + "\n", encoding="utf-8") + temporary.replace(destination) + except OSError as exc: + if temporary is not None: + temporary.unlink(missing_ok=True) + raise RuntimeError(f"Could not save support report: {exc}") from exc + if not args.support_report: + print(f"Sanitized support report saved to {destination}") + return 1 if report.failed else 0 + + +def command_config(args: argparse.Namespace, settings: Settings | None = None) -> int: if args.action == "init": write_default_config(args.force); print(f"Created {CONFIG_FILE}"); return 0 if args.action == "show": - if CONFIG_FILE.exists(): print(CONFIG_FILE.read_text(encoding="utf-8")) - else: print(f"No config. Defaults are in use.\n{CONFIG_FILE}") + effective = settings or load_settings() + if CONFIG_FILE.exists(): + print(CONFIG_FILE.read_text(encoding="utf-8").rstrip()) + else: + print(f"No config. Defaults are in use.\n{CONFIG_FILE}") + if effective.lyrics_dir_explicit: + print(f"Deprecated lyrics_dir (ignored for LRC output): {effective.lyrics_dir}") + print("External lyrics: beside each song (.lrc)") return 0 raise RuntimeError("Unknown config action") @@ -1033,19 +1152,80 @@ def command_cache(args: argparse.Namespace) -> int: raise RuntimeError("Unknown cache action") +def command_state(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: + if args.action == "clean": + plan = plan_stale_state_cleanup(settings, state_file=STATE_FILE) + print_header("Stale State Cleanup", use_color) + print(f"State: {plan.state_file}") + if not plan.stale_keys: + print("No clearly stale external records found. No changes made.") + return 0 + print(f"Clearly stale records: {plan.stale_count}") + for key in plan.stale_keys: + print(f" - {key}") + if not args.yes: + print("\nPreview only. Run `999 state clean --yes` to back up state and remove these records.") + return 0 + result = execute_stale_state_cleanup(plan) + print(f"\nRemoved: {result.removed_count}") + print(f"State backup: {result.backup_path}") + print("Audio and LRC files were not changed.") + return 0 + if args.action == "rebuild-identities": + plan = plan_catalogue_identity_rebuild(settings, state_file=STATE_FILE) + print_header("Catalogue Identity Rebuild", use_color) + print(f"State: {plan.state_file}") + print(f"Current tracks: {plan.current_tracks}") + print(f"Existing identities: {plan.existing_identities}") + print(f"Currently unknown: {plan.currently_unknown}") + print(f"Manual locks kept: {plan.locked_identities}") + print(f"Stale records ignored: {len(plan.stale_keys)}") + if not args.yes: + print("\nNo changes made. Run `999 state rebuild-identities --yes` to rebuild safely.") + return 0 + result = execute_catalogue_identity_rebuild( + plan, + refresh=args.refresh, + include_locked=args.include_locked, + ) + if result.aborted: + print(f"\nRebuild aborted safely: {result.abort_reason}") + return 1 + print("\nCatalogue rebuild complete") + print(f"Matched: {result.matched}") + print(f"Unknown: {result.unknown}") + print(f"Changed identities: {result.changed_identities}") + print(f"Unchanged identities: {result.unchanged_identities}") + print(f"Failed, preserved: {result.failed_preserved}") + print(f"Stale ignored: {result.stale_ignored}") + print(f"State backup: {result.backup_path or 'Not needed'}") + changes = result.changes if args.details else result.changes[:10] + if changes: + print("\nIdentity changes:") + for change in changes: + old = f"{change.old_song_id} ({change.old_api_name or 'Unknown'})" if change.old_song_id is not None else "Unknown" + new = f"{change.new_song_id} ({change.new_api_name or 'Unknown'})" if change.new_song_id is not None else "Unknown" + print(f" {change.path}: {old} -> {new}") + if not args.details and len(result.changes) > len(changes): + print(f" … {len(result.changes) - len(changes)} more; rerun with --details to show all") + print("Audio, embedded lyrics, sidecars, and rmpc configuration were not changed.") + return 0 + raise RuntimeError("Unknown state action") + + def command_rmpc_setup(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: config_path = Path(args.config).expanduser() if args.config else DEFAULT_RMPC_CONFIG - lyrics_dir = Path(args.lyrics_dir).expanduser() if args.lyrics_dir else DEFAULT_RMPC_LYRICS_DIR - if not lyrics_dir.is_absolute(): lyrics_dir = lyrics_dir.resolve() + music_root = Path(settings.music_dir).expanduser() + if not music_root.is_absolute(): + music_root = music_root.resolve() if shutil.which("rmpc") is None: raise RuntimeError("rmpc was not found in PATH") if not config_path.exists(): raise RuntimeError(f"rmpc config not found: {config_path}") print_header("rmpc Lyrics Setup", use_color) - print(f"Library: {settings.music_dir}\nLRC folder: {lyrics_dir}\nrmpc config: {config_path}\n") + print(f"Library: {settings.music_dir}\nExternal lyrics: beside each song\nrmpc config: {config_path}\n") if not args.yes: if not sys.stdin.isatty(): print("Non-interactive mode: use --yes."); return 2 if input("Create LRC files and update rmpc config? [y/N] ").strip().lower() not in {"y", "yes"}: print("Cancelled. No changes made."); return 0 - lyrics_dir.mkdir(parents=True, exist_ok=True) analyses = [] files = find_mp3s(settings) for i, path in enumerate(files, 1): @@ -1055,32 +1235,33 @@ def command_rmpc_setup(args: argparse.Namespace, settings: Settings, use_color: generated = [] for a in analyses: if not a.get("synced"): continue - generated.append(write_lrc(a["path"], a, lyrics_dir)) + generated.append(write_lrc(a["path"], a)) print(colorize(f"✓ {a['path'].name}", GREEN, use_color) + " → LRC") - backup = patch_rmpc_config(config_path, lyrics_dir) + backup = patch_rmpc_config(config_path, music_root) indexed = notify_rmpc_index(generated) - print(f"\nrmpc setup complete\n LRC files: {len(generated)}\n Lyrics folder: {lyrics_dir}\n Config backup: {backup}") + print(f"\nrmpc setup complete\n LRC files: {len(generated)}\n Indexed tree: {music_root}\n Config backup: {backup}") if indexed: print(f" rmpc notified: {indexed}") elif not rmpc_running(): print(" rmpc: not currently running; start/restart it to load the setup") return 0 def command_rmpc_sync(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - lyrics_dir = Path(args.lyrics_dir).expanduser() if args.lyrics_dir else DEFAULT_RMPC_LYRICS_DIR - lyrics_dir.mkdir(parents=True, exist_ok=True) generated = [] for path in find_mp3s(settings): a = analyse(settings, path, args.refresh) if not a.get("synced"): continue - generated.append(write_lrc(path, a, lyrics_dir)) + generated.append(write_lrc(path, a)) print(colorize(f"✓ {path.name}", GREEN, use_color)) print(f"Generated: {len(generated)} Notified: {notify_rmpc_index(generated)}") return 0 def command_rmpc_verify(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - lyrics_dir = Path(args.lyrics_dir).expanduser() if args.lyrics_dir else DEFAULT_RMPC_LYRICS_DIR - files = sorted(lyrics_dir.glob("*.lrc")) if lyrics_dir.is_dir() else [] + files = [ + sidecar_lrc_path(path) + for path in find_mp3s(settings) + if sidecar_lrc_path(path).is_file() + ] good = bad = 0 for path in files: text = path.read_text(encoding="utf-8") @@ -1106,7 +1287,13 @@ def _acquisition_resource_url(resource: dict[str, Any], api_base: str = DEFAULT_ def command_acquire_search(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - data = search_api_advanced(settings, args.query, args.category, args.era, args.refresh) + data = search_api_advanced( + settings, + args.query, + category=args.category, + era=args.era, + refresh=args.refresh, + ) results = data.get("results", []) if isinstance(data, dict) else [] if not isinstance(results, list) or not results: print("No API results found.") @@ -1129,7 +1316,7 @@ def command_acquire_search(args: argparse.Namespace, settings: Settings, use_col if shown == 0: print("No usable API results found.") return 1 - print("\nUse: juice-lyrics acquire add \"\" --index ") + print("\nUse: 999 acquire add \"\" --index ") return 0 @@ -1253,7 +1440,7 @@ def command_acquire_add(args: argparse.Namespace, settings: Settings, use_color: print(f"Items ({len(items)}):") for item in items: print(f" - {item.title} → {item.destination}") - print(f"\nRun it with: juice-lyrics acquire run {job.job_id}") + print(f"\nRun it with: 999 acquire run {job.job_id}") return 0 @@ -1323,21 +1510,21 @@ def command_acquire_manifest(args: argparse.Namespace, settings: Settings, use_c print(colorize("\nUnresolved / Skipped entries:", YELLOW, use_color)) for u in unresolved: print(f" - {u}") - print(f"\nRun it with: juice-lyrics acquire run {job.job_id}") + print(f"\nRun it with: 999 acquire run {job.job_id}") return 0 def command_acquire_jobs(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: store = JobStore() - jobs = store.list() - if not jobs: + snapshot = get_queue_snapshot(store.path) + if not snapshot.jobs: print("No acquisition jobs.") return 0 print_header("Acquisition jobs", use_color) - for job in jobs: - print(f" {job.job_id} — {job.state.value} — {len(job.items)} item(s)") - for entry in job.items: - print(f" {entry.state.value:<14} {entry.item.title} → {entry.item.destination}") + for job in snapshot.jobs: + print(f" {job.job_id} — {job.stored_state} — {job.total_item_count} item(s)") + for item in job.items: + print(f" {item.stored_state:<14} {item.title} → {item.destination}") return 0 @@ -1348,10 +1535,11 @@ def progress(index: int, total: int, written: int, remote_total: int | None) -> print_header(title, use_color) def postprocess(result): + if result.postprocessing_retry: + print(f"\n Retrying post-processing from existing finalized file: {result.item.destination}") integration = integrate_downloaded_mp3( result.item, song_fetcher=lambda song_id: _api_get_song(settings, song_id), - lyrics_dir=configured_rmpc_lyrics_dir(), settings=settings, ) if integration.message: @@ -1443,15 +1631,23 @@ def command_acquire(args: argparse.Namespace, settings: Settings, use_color: boo return command_acquire_delete(args, settings, use_color) raise RuntimeError("Unknown acquisition action") + +def command_tui(settings: Settings) -> int: + """Launch the 999 terminal interface.""" + + from .tui import run_tui + + return run_tui(settings) + def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser(prog=APP_NAME, description="Manage lyrics metadata and rmpc LRC files for local MP3 libraries.") + parser = argparse.ArgumentParser(prog=APP_NAME, description="Manage lyrics metadata and rmpc LRC files for local MP3, FLAC, and M4A libraries.") parser.add_argument("--version", action="version", version=f"{APP_NAME} {__version__}") - parser.add_argument("--path", help="MP3 library directory (overrides config).") + parser.add_argument("--path", help="Music library directory (overrides config).") parser.add_argument("--api-base", help="Override the API base URL.") parser.add_argument("--no-color", action="store_true") - sub = parser.add_subparsers(dest="command", required=True) + sub = parser.add_subparsers(dest="command") - setup = sub.add_parser("setup", help="First-time setup: embed lyrics and configure rmpc when detected.") + setup = sub.add_parser("setup", help="Synchronize the current library without changing rmpc configuration.") setup.add_argument("--yes", action="store_true") setup.add_argument("--refresh", action="store_true") @@ -1466,21 +1662,31 @@ def build_parser() -> argparse.ArgumentParser: scan = sub.add_parser("scan", help="Scan the API and report matches.") scan.add_argument("--refresh", action="store_true") - embed = sub.add_parser("embed", help="Low-level command: embed lyrics into MP3s.") + embed = sub.add_parser("embed", help="Low-level command: embed lyrics into supported audio files.") embed.add_argument("--yes", action="store_true") embed.add_argument("--dry-run", action="store_true") embed.add_argument("--refresh", action="store_true") verify = sub.add_parser("verify", help="Verify embedded lyrics.") - restore = sub.add_parser("restore", help="Restore a previous MP3 backup.") + restore = sub.add_parser("restore", help="Restore a previous audio backup.") restore.add_argument("--backup") restore.add_argument("--yes", action="store_true") - doctor = sub.add_parser("doctor", help="Check the installation and API connection.") + doctor = sub.add_parser("doctor", help="Run bounded, read-only installation and library diagnostics.") + doctor.add_argument("--support-report", action="store_true", help="Print a sanitized JSON support report.") + doctor.add_argument("--save-report", metavar="PATH", help="Deliberately save the sanitized support report to PATH.") + + completion = sub.add_parser( + "completion", + help="Generate shell completion without loading application data.", + ) + completion.add_argument("shell", choices=("bash", "zsh", "fish")) guide = sub.add_parser("guide", help="Show the built-in quick guide.") + sub.add_parser("tui", help="Launch the 999 terminal interface.") + search = sub.add_parser("search", help="Search the public Juice WRLD song catalogue.") search.add_argument("query") search.add_argument("--category") @@ -1492,7 +1698,7 @@ def build_parser() -> argparse.ArgumentParser: info.add_argument("--index", type=int, help="Choose a result from the search list (1-based).") info.add_argument("--refresh", action="store_true") - acquire = sub.add_parser("acquire", help="Explicitly select and acquire API media resources.") + acquire = sub.add_parser("acquire", help="Advanced download operations.") ac = acquire.add_subparsers(dest="action", required=True) acs = ac.add_parser("search", help="Search acquisition candidates without downloading anything.") acs.add_argument("query") @@ -1524,14 +1730,14 @@ def build_parser() -> argparse.ArgumentParser: rs = rmpc.add_subparsers(dest="action", required=True) r1 = rs.add_parser("setup") r1.add_argument("--config") - r1.add_argument("--lyrics-dir") + r1.add_argument("--lyrics-dir", help="Deprecated compatibility option; sidecars are written beside songs.") r1.add_argument("--yes", action="store_true") r1.add_argument("--refresh", action="store_true") r2 = rs.add_parser("sync") - r2.add_argument("--lyrics-dir") + r2.add_argument("--lyrics-dir", help="Deprecated compatibility option; sidecars are written beside songs.") r2.add_argument("--refresh", action="store_true") r3 = rs.add_parser("verify") - r3.add_argument("--lyrics-dir") + r3.add_argument("--lyrics-dir", help="Deprecated compatibility option; sidecars are read beside songs.") config = sub.add_parser("config", help="Manage configuration.") cs = config.add_subparsers(dest="action", required=True) @@ -1540,6 +1746,23 @@ def build_parser() -> argparse.ArgumentParser: cache = sub.add_parser("cache", help="Manage API cache.") csub = cache.add_subparsers(dest="action", required=True); csub.add_parser("clear") + + state = sub.add_parser("state", help="Inspect or safely maintain application state.") + state_sub = state.add_subparsers(dest="action", required=True) + state_clean = state_sub.add_parser("clean", help="Preview clearly stale external state records.") + state_clean.add_argument("--yes", action="store_true", help="Back up state and remove the listed stale records.") + rebuild = state_sub.add_parser( + "rebuild-identities", + help="Preview re-identifying current library files with the latest matcher.", + ) + rebuild.add_argument("--yes", action="store_true", help="Back up state and apply the identity rebuild.") + rebuild.add_argument("--refresh", action="store_true", help="Refresh catalogue search responses instead of using valid cache entries.") + rebuild.add_argument("--details", action="store_true", help="Show every changed identity mapping.") + rebuild.add_argument( + "--include-locked", + action="store_true", + help="Advanced: reconsider manual locked identities too.", + ) return parser @@ -1547,8 +1770,21 @@ def main(argv: list[str] | None = None) -> int: parser = build_parser() args = parser.parse_args(argv) use_color = not args.no_color and sys.stdout.isatty() + if args.command == "completion": + print(generate_completion(parser, args.shell), end="") + return 0 try: - settings = load_settings(getattr(args, "path", None), getattr(args, "api_base", None)) + try: + settings = load_settings(getattr(args, "path", None), getattr(args, "api_base", None)) + except RuntimeError: + if args.command != "doctor": + raise + settings = Settings() + if getattr(args, "path", None): + settings.music_dir = Path(args.path).expanduser() + if getattr(args, "api_base", None): + settings.api_base = args.api_base.rstrip("/") + if args.command is None: return command_tui(settings) if args.command == "setup": return command_setup(args, settings, use_color) if args.command == "sync": return command_sync(args, settings, use_color) if args.command == "status": return command_status(settings, use_color) @@ -1558,6 +1794,7 @@ def main(argv: list[str] | None = None) -> int: if args.command == "restore": return command_restore(args, settings, use_color) if args.command == "doctor": return command_doctor(args, settings, use_color) if args.command == "guide": return command_guide() + if args.command == "tui": return command_tui(settings) if args.command == "search": return command_search(args, settings, use_color) if args.command == "info": return command_info(args, settings, use_color) if args.command == "acquire": return command_acquire(args, settings, use_color) @@ -1565,8 +1802,9 @@ def main(argv: list[str] | None = None) -> int: if args.action == "setup": return command_rmpc_setup(args, settings, use_color) if args.action == "sync": return command_rmpc_sync(args, settings, use_color) if args.action == "verify": return command_rmpc_verify(args, settings, use_color) - if args.command == "config": return command_config(args) + if args.command == "config": return command_config(args, settings) if args.command == "cache": return command_cache(args) + if args.command == "state": return command_state(args, settings, use_color) parser.error("Unknown command") except KeyboardInterrupt: print("\nCancelled.", file=sys.stderr); return 130 diff --git a/src/juice_lyrics/config/settings.py b/src/juice_lyrics/config/settings.py index 8970b6e..409b766 100644 --- a/src/juice_lyrics/config/settings.py +++ b/src/juice_lyrics/config/settings.py @@ -4,13 +4,20 @@ from pathlib import Path from dataclasses import dataclass -APP_NAME = "juice-lyrics" +from ..identity import STORAGE_NAMESPACE + +# Compatibility alias for older imports. This identifies persisted storage, +# not the user-facing product or command name. +APP_NAME = STORAGE_NAMESPACE DEFAULT_API_BASE = "https://juicewrldapi.com/juicewrld" DEFAULT_MUSIC_DIR = Path.home() / "Music" / "Juice WRLD" / "Unreleased" DEFAULT_TIMEOUT = 20 DEFAULT_DELAY = 0.15 DEFAULT_DURATION_TOLERANCE = 3.0 DEFAULT_CACHE_TTL_HOURS = 24 +DEFAULT_LYRICS_DIR = Path.home() / "Music" / "lyrics" +# Historical compatibility values only; neither controls current LRC output. +LEGACY_IMPLICIT_LYRICS_DIR = Path.home() / "Music" / "Juice WRLD" / "lyrics" def xdg_dir(name: str, fallback: Path) -> Path: @@ -20,24 +27,48 @@ def xdg_dir(name: str, fallback: Path) -> Path: CONFIG_HOME = xdg_dir("XDG_CONFIG_HOME", Path.home() / ".config") CACHE_HOME = xdg_dir("XDG_CACHE_HOME", Path.home() / ".cache") DATA_HOME = xdg_dir("XDG_DATA_HOME", Path.home() / ".local" / "share") -CONFIG_FILE = CONFIG_HOME / APP_NAME / "config.toml" -CACHE_DIR = CACHE_HOME / APP_NAME -DATA_DIR = DATA_HOME / APP_NAME +CONFIG_FILE = CONFIG_HOME / STORAGE_NAMESPACE / "config.toml" +CACHE_DIR = CACHE_HOME / STORAGE_NAMESPACE +DATA_DIR = DATA_HOME / STORAGE_NAMESPACE BACKUP_DIR = DATA_DIR / "backups" STATE_FILE = DATA_DIR / "state.json" ACQUISITION_JOBS_FILE = DATA_DIR / "acquisition_jobs.json" -DEFAULT_RMPC_LYRICS_DIR = DEFAULT_MUSIC_DIR.parent / "lyrics" DEFAULT_RMPC_CONFIG = CONFIG_HOME / "rmpc" / "config.ron" @dataclass class Settings: music_dir: Path = DEFAULT_MUSIC_DIR + lyrics_dir: Path = DEFAULT_LYRICS_DIR api_base: str = DEFAULT_API_BASE timeout: int = DEFAULT_TIMEOUT delay: float = DEFAULT_DELAY duration_tolerance: float = DEFAULT_DURATION_TOLERANCE cache_ttl_hours: float = DEFAULT_CACHE_TTL_HOURS + # Deprecated compatibility field. New LRC output is always beside audio. + lyrics_dir_explicit: bool = False @property def songs_endpoint(self) -> str: return self.api_base.rstrip("/") + "/songs/" + + +def resolve_lyrics_dir( + settings: Settings, + *, + explicit_override: str | Path | None = None, +) -> Path: + """Resolve the deprecated centralized directory for compatibility tools. + + Current acquisition, sync, retry, and status paths must not call this + helper. New external lyrics are derived from the finalized audio path. + """ + + if explicit_override is not None: + return Path(explicit_override).expanduser() + resolved = Path(settings.lyrics_dir).expanduser() + if ( + resolved == LEGACY_IMPLICIT_LYRICS_DIR + and not settings.lyrics_dir_explicit + ): + return DEFAULT_LYRICS_DIR + return resolved diff --git a/src/juice_lyrics/identity.py b/src/juice_lyrics/identity.py new file mode 100644 index 0000000..9611d68 --- /dev/null +++ b/src/juice_lyrics/identity.py @@ -0,0 +1,7 @@ +"""Stable product, command, and storage names.""" + +PRODUCT_NAME = "999" +PRIMARY_COMMAND = "999" +LEGACY_COMMAND = "juice-lyrics" +STORAGE_NAMESPACE = "juice-lyrics" +DIST_NAME = "juice-wrld-lyrics" diff --git a/src/juice_lyrics/library/matching.py b/src/juice_lyrics/library/matching.py index 8917ce2..91202b2 100644 --- a/src/juice_lyrics/library/matching.py +++ b/src/juice_lyrics/library/matching.py @@ -1,12 +1,14 @@ from __future__ import annotations import re +from dataclasses import dataclass from pathlib import Path from typing import Any from mutagen.mp3 import MP3 from ..config.settings import Settings +from .media import is_tagged_container, read_tagged_metadata, tagged_matching_title CANONICAL_SEARCH = { "chase the dragon": "Life's a Dungeon", @@ -17,6 +19,46 @@ "whatever": "Call Me Whenever", } +MATCH_THRESHOLD = 70.0 +AMBIGUITY_MARGIN = 12.0 +DURATION_GRACE_EXTRA_SECONDS = 2.0 +MAX_DURATION_GRACE_SECONDS = 5.0 +MAX_DURATION_GRACE_RATIO = 0.02 +_NAMED_VARIANTS = { + "acoustic": r"\bacoustic\b", + "demo": r"\bdemo\b", + "extended outro": r"\bextended\s+outro\b", + "instrumental": r"\binstrumental\b", + "live": r"\blive\b", + "radio edit": r"\bradio\s+edit\b", + "remix": r"\bremix\b", + "slowed": r"\bslowed\b", + "sped up": r"\bsped\s+up\b", + "stem": r"\bstems?\b", + "tv mix": r"\btv\s+mix\b", +} +_ALBUM_EDITION_GROUP = re.compile( + r"\s*[\[(]\s*(?:" + r"bonus\s+track\s+version|" + r"deluxe(?:\s+edition)?|" + r"(?:[1-9]\d*(?:[\s-]+year|(?:st|nd|rd|th))\s+)?anniversary(?:\s+edition)?|" + r"expanded(?:\s+edition)?|" + r"special\s+edition" + r")\s*[\])]\s*", + re.I, +) + + +@dataclass(frozen=True, slots=True) +class CandidateDiagnostic: + song_id: Any + name: str + score: float + eligible: bool + selected: bool + rejection: str | None + reasons: tuple[str, ...] + def normalize(text: str) -> str: text = str(text).lower().replace("’", "'") @@ -26,6 +68,14 @@ def normalize(text: str) -> str: return re.sub(r"\s+", " ", text).strip() +def normalize_words(text: str) -> str: + """Normalize words while retaining parenthetical edition information.""" + + text = str(text).lower().replace("’", "'") + text = re.sub(r"[^a-z0-9]+", " ", text) + return re.sub(r"\s+", " ", text).strip() + + def parse_version(text: str) -> int | None: match = re.search(r"(?:\(|\[)?v(\d+)(?:\)|\])?", text, flags=re.I) return int(match.group(1)) if match else None @@ -35,6 +85,25 @@ def strip_version(text: str) -> str: return re.sub(r"\s*(?:\(|\[)?v\d+(?:\.\d+)?(?:\)|\])?\s*$", "", text, flags=re.I).strip() +def strip_feature_credit(text: str) -> str: + """Remove only collaboration credits that commonly impede catalogue search.""" + + return re.sub( + r"\s*[\[(]\s*(?:feat(?:uring)?\.?|ft\.?|with)\s+[^\])]+[\])]\s*", + " ", + text, + flags=re.I, + ).strip() + + +def named_variants(text: str) -> frozenset[str]: + """Return explicit non-version recording variants from a title.""" + + return frozenset( + label for label, pattern in _NAMED_VARIANTS.items() if re.search(pattern, text, re.I) + ) + + def parse_length(value: str) -> float | None: if not value: return None @@ -51,24 +120,120 @@ def parse_length(value: str) -> float | None: def local_duration(path: Path) -> float | None: try: + if is_tagged_container(path): + return read_tagged_metadata(path).duration_seconds return float(MP3(path).info.length) except Exception: return None +def local_album(path: Path) -> str | None: + """Read optional album evidence without making it a matching requirement.""" + + try: + if is_tagged_container(path): + return read_tagged_metadata(path).album + tags = MP3(path).tags + frame = tags.get("TALB") if tags is not None else None + values = getattr(frame, "text", None) + if values: + value = str(values[0]).strip() + return value or None + except Exception: + pass + return None + + +def _album_key(value: str) -> str: + return re.sub(r"^\d+\s+", "", normalize_words(value)) + + +def _album_edition_base(value: str) -> str: + return _album_key(_ALBUM_EDITION_GROUP.sub(" ", value)) + + +def _candidate_album_values(candidate: dict[str, Any]) -> list[str]: + values: list[str] = [] + album = candidate.get("album") + if isinstance(album, dict): + values.extend(str(album.get(key) or "") for key in ("name", "title")) + elif isinstance(album, (list, tuple)): + values.extend(str(value) for value in album) + elif album: + values.append(str(album)) + api_path = str(candidate.get("path") or "") + if api_path: + values.extend(Path(api_path).parts[:-1]) + return values + + +def album_match_kind(path: Path, candidate: dict[str, Any]) -> str | None: + album = local_album(path) + if not album: + return None + local_key = _album_key(album) + candidate_values = _candidate_album_values(candidate) + candidates = {key for value in candidate_values if (key := _album_key(value))} + if local_key and local_key in candidates: + return "exact" + local_base = _album_edition_base(album) + if local_base and any( + local_base == _album_edition_base(candidate_album) + for candidate_album in candidate_values + ): + return "edition" + return None + + +def album_matches(path: Path, candidate: dict[str, Any]) -> bool: + return album_match_kind(path, candidate) is not None + + +def _duration_grace_allowed( + settings: Settings, + *, + local_title: str, + candidate_title: str, + local_version: int | None, + candidate_version: int | None, + extra_variants: frozenset[str], + category: object, + album_evidence: str | None, + local_seconds: float, + difference: float, +) -> bool: + maximum = min( + MAX_DURATION_GRACE_SECONDS, + settings.duration_tolerance + DURATION_GRACE_EXTRA_SECONDS, + ) + return ( + difference <= maximum + and difference / max(local_seconds, 1.0) <= MAX_DURATION_GRACE_RATIO + and local_title == candidate_title + and (candidate_version is None or candidate_version == local_version) + and not extra_variants + and category == "released" + and album_evidence is not None + ) + + def search_title_for(path: Path) -> str: - stripped = strip_version(path.stem) + raw_title = tagged_matching_title(path) if is_tagged_container(path) else path.stem + stripped = strip_feature_credit(strip_version(raw_title)) return CANONICAL_SEARCH.get(normalize(stripped), stripped) def score_candidate(settings: Settings, path: Path, candidate: dict[str, Any], search_title: str) -> tuple[float, list[str]]: - local_raw = path.stem + local_raw = tagged_matching_title(path) if is_tagged_container(path) else path.stem candidate_raw = str(candidate.get("name", "")) local = normalize(strip_version(local_raw)) candidate_name = normalize(strip_version(candidate_raw)) original_key = normalize(strip_version(str(candidate.get("original_key", "")))) local_version = parse_version(local_raw) candidate_version = parse_version(candidate_raw) + local_variants = named_variants(local_raw) + candidate_variants = named_variants(candidate_raw) + album_evidence = album_match_kind(path, candidate) reasons: list[str] = [] score = 0.0 if local_version is not None: @@ -78,6 +243,17 @@ def score_candidate(settings: Settings, path: Path, candidate: dict[str, Any], s elif candidate_version is not None: score -= 120 reasons.append(f"wrong version (API v{candidate_version}, local v{local_version})") + else: + score -= 60 + reasons.append(f"missing local version v{local_version} (-60)") + elif candidate_version is not None: + score -= 80 + reasons.append(f"candidate-only version v{candidate_version} (-80)") + extra_variants = candidate_variants - local_variants + if extra_variants: + penalty = 90 * len(extra_variants) + score -= penalty + reasons.append(f"candidate-only variant {', '.join(sorted(extra_variants))} (-{penalty})") api_path = str(candidate.get("path") or "") if api_path: if normalize(Path(api_path).name) == normalize(path.name): @@ -85,25 +261,64 @@ def score_candidate(settings: Settings, path: Path, candidate: dict[str, Any], s if normalize(Path(api_path).stem) == normalize(path.stem): score += 120; reasons.append("exact API path filename") if local and local == candidate_name: - score += 100; reasons.append("exact title") + score += 100; reasons.append("exact title (+100)") if local and local == original_key: score += 90; reasons.append("exact original key") if normalize(search_title) == candidate_name: - score += 45; reasons.append("search title match") + score += 45; reasons.append("search title match (+45)") lt, ct = set(local.split()), set(candidate_name.split()) if lt and ct: - score += (len(lt & ct) / len(lt | ct)) * 30 + overlap = (len(lt & ct) / len(lt | ct)) * 30 + score += overlap + reasons.append(f"title token overlap (+{overlap:.2f})") local_len = local_duration(path); api_len = parse_length(str(candidate.get("length") or "")) if local_len is not None and api_len is not None: diff = abs(local_len - api_len) if diff <= settings.duration_tolerance: - score += max(0.0, 60.0 - diff * 10.0); reasons.append(f"duration match ({diff:.2f}s)") + duration_score = max(0.0, 60.0 - diff * 10.0) + score += duration_score + reasons.append(f"duration match ({diff:.2f}s, +{duration_score:.2f})") + elif _duration_grace_allowed( + settings, + local_title=local, + candidate_title=candidate_name, + local_version=local_version, + candidate_version=candidate_version, + extra_variants=extra_variants, + category=candidate.get("category"), + album_evidence=album_evidence, + local_seconds=local_len, + difference=diff, + ): + duration_score = -(5.0 + (diff - settings.duration_tolerance) * 5.0) + score += duration_score + reasons.append( + f"duration catalogue grace ({diff:.3f}s delta; outside normal " + f"{settings.duration_tolerance:.2f}s; strong released-album evidence; " + f"{duration_score:+.2f})" + ) else: - score -= min(diff * 5.0, 60.0); reasons.append(f"duration mismatch ({diff:.2f}s)") - if candidate.get("category") == "unreleased": - score += 10; reasons.append("unreleased") + duration_penalty = min(diff * 5.0, 60.0) + score -= duration_penalty + maximum = min( + MAX_DURATION_GRACE_SECONDS, + settings.duration_tolerance + DURATION_GRACE_EXTRA_SECONDS, + ) + reasons.append( + f"duration mismatch ({diff:.3f}s; outside maximum grace " + f"{maximum:.2f}s or missing corroboration; -{duration_penalty:.2f})" + ) + else: + reasons.append("duration unknown (+0)") if candidate.get("category") == "released": - score -= 150; reasons.append("released") + score += 10 + reasons.append("released (+10)") + if album_evidence == "exact": + score += 35 + reasons.append("album/path match (+35)") + elif album_evidence == "edition": + score += 30 + reasons.append("album edition/path match (+30)") return score, reasons @@ -115,7 +330,69 @@ def choose_candidate(settings: Settings, path: Path, results: list[dict[str, Any scored.sort(key=lambda x: x[0], reverse=True) if not scored: return None, 0.0, [], [] - best_score, best, reasons = scored[0] - if best_score < 70 or (len(scored) >= 2 and best_score - scored[1][0] < 12): + eligible = [ + item + for item in scored + if not any(reason.startswith("duration mismatch") for reason in item[2]) + ] + if not eligible: + best_score, _, reasons = scored[0] + return None, best_score, reasons, scored + best_score, best, reasons = eligible[0] + if best_score < MATCH_THRESHOLD or ( + len(eligible) >= 2 and best_score - eligible[1][0] < AMBIGUITY_MARGIN + ): return None, best_score, reasons, scored return best, best_score, reasons, scored + + +def diagnose_candidates( + settings: Settings, + path: Path, + results: list[dict[str, Any]], + search_title: str, +) -> tuple[CandidateDiagnostic, ...]: + """Expose deterministic matcher evidence for tests and developer diagnosis.""" + + selected, _, _, ranked = choose_candidate(settings, path, results, search_title) + eligible = [ + item + for item in ranked + if not any(reason.startswith("duration mismatch") for reason in item[2]) + ] + ambiguous = bool( + selected is None + and eligible + and eligible[0][0] >= MATCH_THRESHOLD + and len(eligible) >= 2 + and eligible[0][0] - eligible[1][0] < AMBIGUITY_MARGIN + ) + ambiguous_scores = {item[0] for item in eligible[:2]} if ambiguous else set() + diagnostics: list[CandidateDiagnostic] = [] + for score, candidate, reasons in ranked: + duration_incompatible = any( + reason.startswith("duration mismatch") for reason in reasons + ) + is_selected = candidate is selected + if is_selected: + rejection = None + elif duration_incompatible: + rejection = "known duration outside tolerance" + elif score < MATCH_THRESHOLD: + rejection = "below confidence threshold" + elif ambiguous and score in ambiguous_scores: + rejection = "ambiguous within safety margin" + else: + rejection = "lower-ranked candidate" + diagnostics.append( + CandidateDiagnostic( + song_id=candidate.get("id"), + name=str(candidate.get("name") or ""), + score=score, + eligible=not duration_incompatible, + selected=is_selected, + rejection=rejection, + reasons=tuple(reasons), + ) + ) + return tuple(diagnostics) diff --git a/src/juice_lyrics/library/media.py b/src/juice_lyrics/library/media.py new file mode 100644 index 0000000..6465fbf --- /dev/null +++ b/src/juice_lyrics/library/media.py @@ -0,0 +1,157 @@ +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + +from mutagen.flac import FLAC +from mutagen.mp3 import MP3 +from mutagen.mp4 import MP4 + + +SUPPORTED_LIBRARY_SUFFIXES = frozenset({".mp3", ".flac", ".m4a"}) + + +class MediaMetadataError(ValueError): + """Raised when a supported local file lacks safe matching metadata.""" + + +@dataclass(frozen=True, slots=True) +class AudioMetadata: + title: str | None + artist: str | None + album: str | None + duration_seconds: float | None + track_number: str | None = None + + +def is_flac(path: Path) -> bool: + return Path(path).suffix.casefold() == ".flac" + + +def is_m4a(path: Path) -> bool: + return Path(path).suffix.casefold() == ".m4a" + + +def is_tagged_container(path: Path) -> bool: + return is_flac(path) or is_m4a(path) + + +def is_supported_audio(path: Path) -> bool: + return Path(path).suffix.casefold() in SUPPORTED_LIBRARY_SUFFIXES + + +def _first(values: object) -> str | None: + if not isinstance(values, (list, tuple)) or not values: + return None + value = str(values[0]).strip() + return value or None + + +def _mp3_text(audio: MP3, frame_name: str) -> str | None: + frame = audio.tags.get(frame_name) if audio.tags is not None else None + values = getattr(frame, "text", None) + return _first(values) + + +def read_mp3_metadata(path: Path) -> AudioMetadata: + """Read common ID3 metadata without modifying the file.""" + + audio = MP3(path) + return AudioMetadata( + title=_mp3_text(audio, "TIT2"), + artist=_mp3_text(audio, "TPE1"), + album=_mp3_text(audio, "TALB"), + duration_seconds=float(audio.info.length) if audio.info is not None else None, + track_number=_mp3_text(audio, "TRCK"), + ) + + +def read_flac_metadata(path: Path) -> AudioMetadata: + """Read standard FLAC/Vorbis metadata without modifying the file.""" + + audio = FLAC(path) + return AudioMetadata( + title=_first(audio.get("title")), + artist=_first(audio.get("artist")), + album=_first(audio.get("album")), + duration_seconds=float(audio.info.length) if audio.info is not None else None, + track_number=_first(audio.get("tracknumber")), + ) + + +def read_m4a_metadata(path: Path) -> AudioMetadata: + """Read standard MP4/M4A atoms without modifying the file.""" + + audio = MP4(path) + track = None + raw_track = audio.get("trkn") + if isinstance(raw_track, (list, tuple)) and raw_track: + pair = raw_track[0] + if isinstance(pair, (list, tuple)) and pair: + number = pair[0] + total = pair[1] if len(pair) > 1 else 0 + if isinstance(number, int) and number > 0: + track = f"{number}/{total}" if isinstance(total, int) and total > 0 else str(number) + return AudioMetadata( + title=_first(audio.get("\xa9nam")), + artist=_first(audio.get("\xa9ART")), + album=_first(audio.get("\xa9alb")), + duration_seconds=float(audio.info.length) if audio.info is not None else None, + track_number=track, + ) + + +def read_audio_metadata(path: Path) -> AudioMetadata: + """Read common metadata from every supported local-library format.""" + + if is_flac(path): + return read_flac_metadata(path) + if is_m4a(path): + return read_m4a_metadata(path) + if Path(path).suffix.casefold() == ".mp3": + return read_mp3_metadata(path) + raise MediaMetadataError(f"Unsupported audio format: {path.suffix or '(none)'}") + + +def read_tagged_metadata(path: Path) -> AudioMetadata: + if is_flac(path): + return read_flac_metadata(path) + if is_m4a(path): + return read_m4a_metadata(path) + raise MediaMetadataError(f"Unsupported tagged audio format: {path.suffix or '(none)'}") + + +def media_format(path: Path) -> str: + if is_flac(path): + return "FLAC" + if is_m4a(path): + return "M4A" + return "MP3" + + +def tagged_matching_title(path: Path) -> str: + """Return trustworthy native metadata or refuse filename-only guessing.""" + + format_name = media_format(path) + try: + metadata = read_tagged_metadata(path) + except Exception as exc: + raise MediaMetadataError( + f"{format_name} metadata could not be read; track left unmatched: {exc}" + ) from exc + missing = [ + label + for label, value in (("title", metadata.title), ("artist", metadata.artist)) + if not value + ] + if missing: + raise MediaMetadataError( + f"{format_name} metadata is missing {', '.join(missing)}; track left unmatched" + ) + return metadata.title or "" + + +def flac_matching_title(path: Path) -> str: + """Backward-compatible FLAC-specific matching helper.""" + + return tagged_matching_title(path) diff --git a/src/juice_lyrics/library/scanner.py b/src/juice_lyrics/library/scanner.py index 5c66e34..cc6f3f3 100644 --- a/src/juice_lyrics/library/scanner.py +++ b/src/juice_lyrics/library/scanner.py @@ -1,13 +1,26 @@ from __future__ import annotations from pathlib import Path from typing import Any -from .matching import local_duration -def find_mp3s(target: Path | Any) -> list[Path]: +from .media import is_supported_audio + + +def find_audio_files(target: Path | Any) -> list[Path]: + """Find supported local audio recursively beneath the configured root.""" + if hasattr(target, "music_dir"): music_dir = Path(target.music_dir) else: music_dir = Path(target) if not music_dir.is_dir(): raise RuntimeError(f"Music directory does not exist: {music_dir}") - return sorted(music_dir.rglob("*.mp3"), key=lambda p: str(p).lower()) + return sorted( + (path for path in music_dir.rglob("*") if path.is_file() and is_supported_audio(path)), + key=lambda path: str(path).casefold(), + ) + + +def find_mp3s(target: Path | Any) -> list[Path]: + """Backward-compatible name for the MP3, FLAC, and M4A library scanner.""" + + return find_audio_files(target) diff --git a/src/juice_lyrics/lyrics/engine.py b/src/juice_lyrics/lyrics/engine.py index 54ee5cb..613f5d6 100644 --- a/src/juice_lyrics/lyrics/engine.py +++ b/src/juice_lyrics/lyrics/engine.py @@ -1,10 +1,16 @@ from __future__ import annotations +import os import re +import tempfile from pathlib import Path from typing import Any +from mutagen.flac import FLAC from mutagen.id3 import ID3, ID3NoHeaderError, SYLT, USLT, Encoding +from mutagen.mp4 import MP4 from ..library.matching import local_duration, parse_length +from ..library.media import is_flac, is_m4a, is_tagged_container, read_tagged_metadata +from .sidecar import sidecar_lrc_path DESCRIPTION = "Juice WRLD API" LANGUAGE = "eng" @@ -39,7 +45,31 @@ def _save(tag: ID3, path: Path) -> None: version = 3 if getattr(tag, "version", None) and tag.version[0] == 3 else 4 tag.save(path, v2_version=version) +def _plain_lyric_text(synced: list[tuple[str, int]], plain: str) -> str: + # FLAC and M4A have no interoperable SYLT equivalent. Preserve useful + # plain text in their standard lyric field; timing remains in the sidecar. + return plain.strip() or "\n".join(text for text, _ in synced).strip() + + def embed_lyrics(path: Path, synced: list[tuple[str,int]], plain: str) -> str: + if is_flac(path): + text = _plain_lyric_text(synced, plain) + if not text: + raise ValueError("No lyrics available") + audio = FLAC(path) + audio["LYRICS"] = [text] + audio.save() + return "FLAC_LYRICS" + if is_m4a(path): + text = _plain_lyric_text(synced, plain) + if not text: + raise ValueError("No lyrics available") + audio = MP4(path) + if audio.tags is None: + audio.add_tags() + audio["\xa9lyr"] = [text] + audio.save() + return "M4A_LYRICS" tag = load_id3(path); _remove_managed(tag) if synced: tag.add(SYLT(encoding=Encoding.UTF8, lang=LANGUAGE, format=2, type=1, desc=DESCRIPTION, text=synced)); _save(tag, path); return "SYLT" @@ -49,6 +79,27 @@ def embed_lyrics(path: Path, synced: list[tuple[str,int]], plain: str) -> str: def verify_file(path: Path) -> tuple[bool,str]: try: + if is_flac(path): + audio = FLAC(path) + lyrics = [ + str(value).strip() + for key in ("lyrics", "unsyncedlyrics") + for value in audio.get(key, []) + if str(value).strip() + ] + if lyrics: + return True, f"FLAC LYRICS ({sum(len(value) for value in lyrics)} characters)" + return False, "no embedded FLAC lyrics" + if is_m4a(path): + audio = MP4(path) + lyrics = [ + str(value).strip() + for value in audio.get("\xa9lyr", []) + if str(value).strip() + ] + if lyrics: + return True, f"M4A LYRICS ({sum(len(value) for value in lyrics)} characters)" + return False, "no embedded M4A lyrics" tag = ID3(path) sylt = [f for f in tag.getall("SYLT") if getattr(f,"desc","")==DESCRIPTION] if sylt: @@ -80,13 +131,62 @@ def first(fid): cs=max(0,int(round(duration*100))); minutes,remainder=divmod(cs,6000); seconds,centiseconds=divmod(remainder,100) return {"artist":artist,"title":title,"album":album,"length":f"{minutes:02d}:{seconds:02d}.{centiseconds:02d}"} -def write_lrc(path: Path, synced: list[tuple[str,int]], fallback: dict[str,Any], out_dir: Path) -> Path: + +def read_tagged_lrc_metadata(path: Path, fallback: dict[str, Any]) -> dict[str, str]: + metadata = read_tagged_metadata(path) + artist = metadata.artist or str(fallback.get("credited_artists") or "Juice WRLD") + title = metadata.title or str(fallback.get("name") or path.stem) + album = metadata.album or str(fallback.get("album") or "") + duration = metadata.duration_seconds or parse_length(str(fallback.get("length") or "")) or 0.0 + centiseconds_total = max(0, int(round(duration * 100))) + minutes, remainder = divmod(centiseconds_total, 6000) + seconds, centiseconds = divmod(remainder, 100) + return { + "artist": artist, + "title": title, + "album": album, + "length": f"{minutes:02d}:{seconds:02d}.{centiseconds:02d}", + } +def write_lrc( + path: Path, + synced: list[tuple[str, int]], + fallback: dict[str, Any], +) -> Path: + """Atomically create or update synchronized lyrics beside ``path``.""" + if not synced: raise ValueError("No synchronized lyrics available") - meta=read_mp3_metadata(path,fallback); out_dir.mkdir(parents=True,exist_ok=True); out=out_dir/f"{path.stem}.lrc" + if is_tagged_container(path): + meta = read_tagged_lrc_metadata(path, fallback) + else: + meta = read_mp3_metadata(path, fallback) + out = sidecar_lrc_path(path) safe=lambda s:str(s).replace("]","}") lines=[f"[ar:{safe(meta['artist'])}]",f"[ti:{safe(meta['title'])}]"] if meta["album"]: lines.append(f"[al:{safe(meta['album'])}]") lines += [f"[length:{meta['length']}]",""] for text,ms in synced: cs=max(0,int(round(ms/10))); m,r=divmod(cs,6000); s,cs2=divmod(r,100); lines.append(f"[{m:02d}:{s:02d}.{cs2:02d}] {text}") - tmp=out.with_suffix(".lrc.tmp"); tmp.write_text("\n".join(lines)+"\n",encoding="utf-8"); tmp.replace(out); return out + content = "\n".join(lines) + "\n" + try: + if out.read_text(encoding="utf-8") == content: + return out + except FileNotFoundError: + pass + + temporary: Path | None = None + try: + descriptor, temporary_name = tempfile.mkstemp( + dir=out.parent, + prefix=f".{out.name}.", + suffix=".tmp", + ) + temporary = Path(temporary_name) + with os.fdopen(descriptor, "w", encoding="utf-8") as handle: + handle.write(content) + handle.flush() + os.fsync(handle.fileno()) + temporary.replace(out) + finally: + if temporary is not None: + temporary.unlink(missing_ok=True) + return out diff --git a/src/juice_lyrics/lyrics/sidecar.py b/src/juice_lyrics/lyrics/sidecar.py new file mode 100644 index 0000000..9b68c6c --- /dev/null +++ b/src/juice_lyrics/lyrics/sidecar.py @@ -0,0 +1,9 @@ +from __future__ import annotations + +from pathlib import Path + + +def sidecar_lrc_path(audio_path: Path) -> Path: + """Return the same-basename LRC path beside a finalized audio file.""" + + return Path(audio_path).with_suffix(".lrc") diff --git a/src/juice_lyrics/rmpc/integration.py b/src/juice_lyrics/rmpc/integration.py index 2bd1c63..161b68f 100644 --- a/src/juice_lyrics/rmpc/integration.py +++ b/src/juice_lyrics/rmpc/integration.py @@ -2,8 +2,6 @@ import re, shutil, subprocess from datetime import datetime from pathlib import Path -from ..config.settings import DEFAULT_RMPC_CONFIG, DEFAULT_RMPC_LYRICS_DIR -from ..lyrics.engine import write_lrc def rmpc_running()->bool: try: return subprocess.run(["rmpc","remote","query","active-tab"],stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL,timeout=3,check=False).returncode==0 @@ -19,12 +17,12 @@ def notify_rmpc_index(paths:list[Path])->int: if r.returncode==0: count+=1 return count -def patch_rmpc_config(config_path:Path,lyrics_dir:Path)->Path: +def patch_rmpc_config(config_path:Path,music_root:Path)->Path: if not config_path.exists(): raise RuntimeError(f"rmpc config not found: {config_path}") original=config_path.read_text(encoding="utf-8") backup=config_path.with_name(f"{config_path.name}.juice-lyrics-{datetime.now().strftime('%Y%m%d-%H%M%S')}.bak") shutil.copy2(config_path,backup) - escaped=str(lyrics_dir).replace("\\","\\\\").replace('"','\\"') + escaped=str(music_root).replace("\\","\\\\").replace('"','\\"') replacement=f' lyrics_dir: Some("{escaped}"),' if re.search(r"(?m)^\s*lyrics_dir\s*:",original): updated=re.sub(r"(?m)^\s*lyrics_dir\s*:\s*[^,]+,",replacement,original,count=1) else: updated=original.replace("(","(\n"+replacement,1) diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py new file mode 100644 index 0000000..bb42472 --- /dev/null +++ b/src/juice_lyrics/services/__init__.py @@ -0,0 +1,320 @@ +"""Application services shared by command-line and interactive frontends.""" + +from .acquisition_queue import ( + QueueFailureStage, + QueueItem, + QueueJob, + QueueReferenceError, + QueueSnapshot, + QueueStatus, + get_queue_snapshot, + resolve_queue_reference, +) +from .catalogue import ( + CatalogueFilterMetadata, + CatalogueFilterOption, + CataloguePage, + CatalogueSearchResult, + LyricAvailability, + SongDetails, + get_catalogue_filters, + get_song_details, + get_song_details_by_id, + search_catalogue, + search_catalogue_page, +) +from .download_queue import ( + DownloadExecutionAction, + DownloadExecutionPlan, + DownloadExecutionResult, + DownloadExecutionStatus, + DownloadRetryAction, + DownloadRetryPlan, + DownloadRetryResult, + DownloadRetryStatus, + DownloadAllPlan, + DownloadAllResult, + DownloadBatchItemResult, + DownloadBatchProgress, + DownloadBatchStatus, + QueueMutationPlan, + QueueMutationResult, + QueueMutationStatus, + DownloadProgress, + DownloadQueueItem, + DownloadQueueItemStatus, + DownloadQueueSnapshot, + PlannedQueueItem, + QueueBatchAddItem, + QueueBatchAddItemStatus, + QueueBatchAddPlan, + QueueBatchAddResult, + QueueBatchAddStatus, + QueueAddPlan, + QueueAddResult, + QueueAddStatus, + QueueDuplicateReason, + add_to_download_queue, + add_batch_to_download_queue, + execute_selected_download, + execute_selected_retry, + get_download_queue_snapshot, + plan_queue_additions, + plan_queue_batch_additions, + plan_download_execution, + plan_download_retry, + remove_queue_item, + clear_download_queue, + clear_completed_history, + plan_download_all, + execute_download_all, + project_download_queue, +) +from .library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryStatus, + LibraryTrack, + get_library_snapshot, + get_library_status, +) +from .library_identity import ( + IdentityBackfillDependencies, + IdentityBackfillResult, + backfill_catalogue_identities, +) +from .library_issues import ( + LibraryHealth, + LibraryIssue, + LibraryIssueAction, + LibraryIssueCategory, + LibraryIssueSeverity, + get_library_health, +) +from .library_duplicates import ( + DuplicateConfidence, + DuplicateGroup, + DuplicateReport, + detect_library_duplicates, +) +from .metadata_audit import ( + MetadataAudit, + MetadataProposal, + MetadataProposalConfidence, + audit_track_metadata, + build_metadata_audit, +) +from .metadata_repair import ( + MediaPreservation, + MetadataRepairDependencies, + MetadataRepairPlan, + MetadataRepairResult, + execute_metadata_repair, + inspect_media_preservation, + plan_metadata_repair, + write_metadata_fields, +) +from .missing_library import ( + CatalogueCoverage, + MissingLibraryReport, + get_missing_library, +) +from .doctor import ( + DoctorCheck, + DoctorReport, + DoctorStatus, + render_support_report, + run_doctor, + sanitize_support_text, + support_report_data, +) +from .shell_completion import ( + CompletionNode, + CompletionOption, + completion_tree, + generate_completion, +) +from .manual_identity import ( + ManualIdentityDependencies, + ManualIdentityResult, + is_identity_locked, + set_manual_identity, + unlock_manual_identity, +) +from .identity_rebuild import ( + IdentityChange, + IdentityRebuildDependencies, + IdentityRebuildPlan, + IdentityRebuildProgress, + IdentityRebuildResult, + execute_catalogue_identity_rebuild, + plan_catalogue_identity_rebuild, +) +from .library_sync import ( + LibrarySyncDependencies, + LibrarySyncOptions, + LibrarySyncPlan, + LibrarySyncResult, + MatchOutcome, + SyncEvent, + SyncEventKind, + SyncLyricType, + TrackSyncPlan, + TrackSyncResult, + execute_library_sync, + execute_library_sync_preview, + get_library_sync_preview, + plan_library_sync, +) +from .settings_snapshot import ( + IntegrationSnapshot, + IntegrationStatus, + SettingValue, + SettingsPath, + SettingsSnapshot, + SettingsSource, + get_settings_snapshot, +) +from .state_maintenance import ( + StateCleanupResult, + StaleStatePlan, + execute_stale_state_cleanup, + plan_stale_state_cleanup, +) + +__all__ = [ + "CatalogueSearchResult", + "CatalogueFilterMetadata", + "CatalogueFilterOption", + "CataloguePage", + "DownloadQueueItem", + "DownloadQueueItemStatus", + "DownloadQueueSnapshot", + "DownloadExecutionAction", + "DownloadExecutionPlan", + "DownloadExecutionResult", + "DownloadExecutionStatus", + "DownloadProgress", + "LibraryStatus", + "LibraryHealth", + "LibraryIssue", + "LibraryIssueAction", + "LibraryIssueCategory", + "LibraryIssueSeverity", + "DuplicateConfidence", + "DuplicateGroup", + "DuplicateReport", + "MetadataAudit", + "MetadataProposal", + "MetadataProposalConfidence", + "MediaPreservation", + "MetadataRepairDependencies", + "MetadataRepairPlan", + "MetadataRepairResult", + "CatalogueCoverage", + "MissingLibraryReport", + "get_missing_library", + "DoctorCheck", + "DoctorReport", + "DoctorStatus", + "CompletionNode", + "CompletionOption", + "render_support_report", + "run_doctor", + "sanitize_support_text", + "support_report_data", + "completion_tree", + "generate_completion", + "IdentityBackfillDependencies", + "IdentityBackfillResult", + "ManualIdentityDependencies", + "ManualIdentityResult", + "LibraryLrcStatus", + "LibraryLyricStatus", + "LibraryMatchStatus", + "LibrarySnapshot", + "LibraryStateStatus", + "LibraryTrack", + "IntegrationSnapshot", + "IntegrationStatus", + "LibrarySyncDependencies", + "LibrarySyncOptions", + "LibrarySyncPlan", + "LibrarySyncResult", + "LyricAvailability", + "MatchOutcome", + "QueueItem", + "PlannedQueueItem", + "QueueAddPlan", + "QueueAddResult", + "QueueAddStatus", + "QueueBatchAddItem", + "QueueBatchAddItemStatus", + "QueueBatchAddPlan", + "QueueBatchAddResult", + "QueueBatchAddStatus", + "QueueDuplicateReason", + "QueueFailureStage", + "QueueJob", + "QueueReferenceError", + "QueueSnapshot", + "QueueStatus", + "SettingValue", + "SettingsPath", + "SettingsSnapshot", + "SettingsSource", + "SongDetails", + "SyncEvent", + "SyncEventKind", + "SyncLyricType", + "TrackSyncPlan", + "TrackSyncResult", + "StateCleanupResult", + "StaleStatePlan", + "IdentityChange", + "IdentityRebuildDependencies", + "IdentityRebuildPlan", + "IdentityRebuildProgress", + "IdentityRebuildResult", + "backfill_catalogue_identities", + "get_library_health", + "detect_library_duplicates", + "audit_track_metadata", + "build_metadata_audit", + "execute_metadata_repair", + "inspect_media_preservation", + "plan_metadata_repair", + "write_metadata_fields", + "is_identity_locked", + "set_manual_identity", + "unlock_manual_identity", + "execute_library_sync", + "execute_library_sync_preview", + "execute_stale_state_cleanup", + "execute_catalogue_identity_rebuild", + "execute_selected_download", + "get_library_sync_preview", + "get_catalogue_filters", + "get_download_queue_snapshot", + "get_queue_snapshot", + "get_library_status", + "get_library_snapshot", + "get_settings_snapshot", + "get_song_details", + "get_song_details_by_id", + "plan_library_sync", + "plan_stale_state_cleanup", + "plan_catalogue_identity_rebuild", + "plan_download_execution", + "plan_queue_additions", + "plan_queue_batch_additions", + "project_download_queue", + "add_to_download_queue", + "add_batch_to_download_queue", + "search_catalogue", + "search_catalogue_page", + "resolve_queue_reference", +] diff --git a/src/juice_lyrics/services/acquisition_queue.py b/src/juice_lyrics/services/acquisition_queue.py new file mode 100644 index 0000000..5185144 --- /dev/null +++ b/src/juice_lyrics/services/acquisition_queue.py @@ -0,0 +1,348 @@ +from __future__ import annotations + +import hashlib +import json +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +from typing import Any + +from ..acquisition.jobs import DEFAULT_JOBS_FILE, JobStoreError +from ..acquisition.models import AcquisitionFailureStage, AcquisitionState + + +class QueueStatus(str, Enum): + PENDING = "pending" + CHECKING_EXISTING = "checking_existing" + DOWNLOADING = "downloading" + VALIDATING = "validating" + POST_PROCESSING = "post_processing" + COMPLETED = "complete" + SKIPPED = "skipped" + FAILED = "failed" + UNKNOWN = "unknown" + + +class QueueFailureStage(str, Enum): + TRANSPORT = "transport" + VALIDATION = "validation" + LYRICS = "lyrics" + LRC = "lrc" + STATE = "state" + UNKNOWN = "unknown" + + +@dataclass(frozen=True, slots=True) +class QueueItem: + title: str | None + destination: Path | None + status: QueueStatus + stored_state: str + bytes_written: int + expected_bytes: int | None + resumed: bool + error: str | None + retryable: bool + failure_stage: QueueFailureStage | None = None + postprocessing_retryable: bool = False + identifier: str | None = None + metadata: tuple[tuple[str, str], ...] = () + + +@dataclass(frozen=True, slots=True) +class QueueJob: + display_number: int + job_id: str + label: str + created_at: str | None + destination: Path | None + total_item_count: int + pending_item_count: int + active_item_count: int + completed_item_count: int + failed_item_count: int + status: QueueStatus + stored_state: str + retryable: bool + deletion_allowed: bool + items: tuple[QueueItem, ...] + updated_at: str | None = None + + +@dataclass(frozen=True, slots=True) +class QueueSnapshot: + jobs: tuple[QueueJob, ...] + total_job_count: int + active_job_count: int + pending_job_count: int + completed_job_count: int + failed_job_count: int + + +class QueueReferenceError(ValueError): + """A friendly queue reference does not identify a displayed job.""" + + +_ACTIVE = { + QueueStatus.CHECKING_EXISTING, + QueueStatus.DOWNLOADING, + QueueStatus.VALIDATING, + QueueStatus.POST_PROCESSING, +} +_TERMINAL = {QueueStatus.COMPLETED, QueueStatus.SKIPPED} +_DELETE_BLOCKING_STORED_STATES = { + AcquisitionState.CHECKING_EXISTING.value, + AcquisitionState.DOWNLOADING.value, + AcquisitionState.VALIDATING.value, +} + + +def _text(value: Any) -> str | None: + if value is None or isinstance(value, (Mapping, list, tuple, set)): + return None + text = str(value).strip() + return text or None + + +def _nonnegative_int(value: Any, default: int = 0) -> int: + try: + parsed = int(value) + except (TypeError, ValueError): + return default + return max(0, parsed) + + +def _optional_nonnegative_int(value: Any) -> int | None: + if value in (None, ""): + return None + try: + parsed = int(value) + except (TypeError, ValueError): + return None + return parsed if parsed >= 0 else None + + +def _item_status(value: Any) -> tuple[QueueStatus, str]: + stored = _text(value) or AcquisitionState.PENDING.value + normalized = { + AcquisitionState.PENDING.value: QueueStatus.PENDING, + AcquisitionState.RESOLVED.value: QueueStatus.PENDING, + AcquisitionState.CHECKING_EXISTING.value: QueueStatus.CHECKING_EXISTING, + AcquisitionState.DOWNLOADING.value: QueueStatus.DOWNLOADING, + AcquisitionState.DOWNLOADED.value: QueueStatus.POST_PROCESSING, + AcquisitionState.VALIDATING.value: QueueStatus.VALIDATING, + AcquisitionState.IMPORTED.value: QueueStatus.POST_PROCESSING, + AcquisitionState.COMPLETE.value: QueueStatus.COMPLETED, + AcquisitionState.SKIPPED.value: QueueStatus.SKIPPED, + AcquisitionState.FAILED.value: QueueStatus.FAILED, + }.get(stored, QueueStatus.UNKNOWN) + return normalized, stored + + +def _failure_stage(value: Any) -> QueueFailureStage | None: + stored = _text(value) + if stored is None: + return None + return { + AcquisitionFailureStage.TRANSPORT.value: QueueFailureStage.TRANSPORT, + AcquisitionFailureStage.VALIDATION.value: QueueFailureStage.VALIDATION, + AcquisitionFailureStage.LYRICS.value: QueueFailureStage.LYRICS, + AcquisitionFailureStage.LRC.value: QueueFailureStage.LRC, + AcquisitionFailureStage.STATE.value: QueueFailureStage.STATE, + }.get(stored, QueueFailureStage.UNKNOWN) + + +def _sha256(path: Path, chunk_size: int = 1024 * 128) -> str: + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(chunk_size), b""): + digest.update(chunk) + return digest.hexdigest() + + +def _safe_postprocessing_retry( + record: Mapping[str, Any], + destination: Path | None, + status: QueueStatus, + stage: QueueFailureStage | None, +) -> bool: + if status is not QueueStatus.FAILED or stage not in { + QueueFailureStage.LYRICS, + QueueFailureStage.LRC, + QueueFailureStage.STATE, + }: + return False + expected_size = _optional_nonnegative_int(record.get("retry_file_size")) + expected_sha256 = _text(record.get("retry_file_sha256")) + if destination is None or expected_size is None or expected_sha256 is None: + return False + try: + return ( + destination.is_file() + and destination.stat().st_size == expected_size + and _sha256(destination) == expected_sha256.lower() + ) + except OSError: + return False + + +def _queue_item(raw: Any) -> QueueItem: + record = raw if isinstance(raw, Mapping) else {} + item = record.get("item") + item_record = item if isinstance(item, Mapping) else {} + status, stored_state = _item_status(record.get("state")) + destination_text = _text(item_record.get("destination")) + destination = Path(destination_text) if destination_text else None + expected = _optional_nonnegative_int(item_record.get("expected_size")) + error = _text(record.get("error")) + failure_stage = _failure_stage(record.get("failure_stage")) + return QueueItem( + title=_text(item_record.get("title")), + destination=destination, + status=status, + stored_state=stored_state, + bytes_written=_nonnegative_int(record.get("bytes_written")), + expected_bytes=expected, + resumed=bool(record.get("resumed", False)), + error=error, + retryable=status not in _TERMINAL and status is not QueueStatus.UNKNOWN, + failure_stage=failure_stage, + postprocessing_retryable=_safe_postprocessing_retry( + record, + destination, + status, + failure_stage, + ), + identifier=_text(item_record.get("identifier")), + metadata=tuple( + (str(key), str(value)) + for key, value in sorted( + (item_record.get("metadata") or {}).items() + if isinstance(item_record.get("metadata"), Mapping) + else () + ) + ), + ) + + +def _job_status(items: tuple[QueueItem, ...]) -> tuple[QueueStatus, str]: + statuses = [item.status for item in items] + if not statuses: + return QueueStatus.COMPLETED, AcquisitionState.COMPLETE.value + if QueueStatus.FAILED in statuses: + return QueueStatus.FAILED, AcquisitionState.FAILED.value + if all(status in _TERMINAL for status in statuses): + return QueueStatus.COMPLETED, AcquisitionState.COMPLETE.value + if any(status in _ACTIVE for status in statuses): + normalized = next(status for status in statuses if status in _ACTIVE) + legacy = ( + AcquisitionState.DOWNLOADING.value + if any(item.stored_state in { + AcquisitionState.DOWNLOADING.value, + AcquisitionState.VALIDATING.value, + } for item in items) + else AcquisitionState.PENDING.value + ) + return normalized, legacy + if all(status is QueueStatus.UNKNOWN for status in statuses): + return QueueStatus.UNKNOWN, QueueStatus.UNKNOWN.value + return QueueStatus.PENDING, AcquisitionState.PENDING.value + + +def _job_label(items: tuple[QueueItem, ...]) -> str: + titles = [item.title for item in items if item.title] + if not titles: + return "Untitled job" + if len(items) == 1: + return titles[0] + return f"{titles[0]} + {len(items) - 1} more" + + +def _read_jobs(path: Path) -> list[tuple[int, str, Mapping[str, Any]]]: + if not path.exists(): + return [] + try: + raw = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + raise JobStoreError(f"Could not read acquisition job store: {path}") from exc + jobs = raw.get("jobs", {}) if isinstance(raw, Mapping) else None + if not isinstance(jobs, Mapping): + raise JobStoreError(f"Invalid acquisition job store format: {path}") + records: list[tuple[int, str, Mapping[str, Any]]] = [] + for position, (stored_id, payload) in enumerate(jobs.items()): + if isinstance(payload, Mapping): + records.append((position, str(stored_id), payload)) + records.sort( + key=lambda record: (_text(record[2].get("created_at")) or ""), + reverse=True, + ) + return records + + +def get_queue_snapshot(path: Path = DEFAULT_JOBS_FILE) -> QueueSnapshot: + """Read and normalize the persistent queue without mutating or recovering it.""" + + jobs: list[QueueJob] = [] + for display_number, (_, stored_id, raw) in enumerate(_read_jobs(Path(path)), start=1): + raw_items = raw.get("items", []) + source_items = ( + raw_items + if isinstance(raw_items, Sequence) and not isinstance(raw_items, (str, bytes, bytearray)) + else [] + ) + items = tuple(_queue_item(item) for item in source_items) + status, stored_state = _job_status(items) + destinations = [item.destination for item in items if item.destination is not None] + job_id = _text(raw.get("job_id")) or stored_id + jobs.append( + QueueJob( + display_number=display_number, + job_id=job_id, + label=_job_label(items), + created_at=_text(raw.get("created_at")), + destination=destinations[0] if len(destinations) == 1 else None, + total_item_count=len(items), + pending_item_count=sum(item.status in {QueueStatus.PENDING, QueueStatus.UNKNOWN} for item in items), + active_item_count=sum(item.status in _ACTIVE for item in items), + completed_item_count=sum(item.status in _TERMINAL for item in items), + failed_item_count=sum(item.status is QueueStatus.FAILED for item in items), + status=status, + stored_state=stored_state, + retryable=any(item.retryable for item in items), + deletion_allowed=not any( + item.stored_state in _DELETE_BLOCKING_STORED_STATES for item in items + ), + items=items, + updated_at=_text(raw.get("updated_at")), + ) + ) + + snapshot_jobs = tuple(jobs) + return QueueSnapshot( + jobs=snapshot_jobs, + total_job_count=len(snapshot_jobs), + active_job_count=sum(job.status in _ACTIVE for job in snapshot_jobs), + pending_job_count=sum(job.status in {QueueStatus.PENDING, QueueStatus.UNKNOWN} for job in snapshot_jobs), + completed_job_count=sum(job.status is QueueStatus.COMPLETED for job in snapshot_jobs), + failed_job_count=sum(job.status is QueueStatus.FAILED for job in snapshot_jobs), + ) + + +def resolve_queue_reference(snapshot: QueueSnapshot, reference: str | int) -> QueueJob: + """Resolve a display number, ``latest``, or exact persistent job ID.""" + + text = str(reference).strip() + if text.lower() == "latest": + if snapshot.jobs: + return snapshot.jobs[0] + raise QueueReferenceError("The acquisition queue is empty") + if text.isdigit(): + number = int(text) + if 1 <= number <= len(snapshot.jobs): + return snapshot.jobs[number - 1] + raise QueueReferenceError(f"Queue number is out of range: {text}") + for job in snapshot.jobs: + if job.job_id == text: + return job + raise QueueReferenceError(f"Acquisition job not found: {text}") diff --git a/src/juice_lyrics/services/catalogue.py b/src/juice_lyrics/services/catalogue.py new file mode 100644 index 0000000..48c3841 --- /dev/null +++ b/src/juice_lyrics/services/catalogue.py @@ -0,0 +1,392 @@ +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +import re +from typing import Any + +from ..acquisition.resolver import ResourceResolutionError, resolve_resource +from ..api.client import ( + get_categories, + get_eras, + get_song, + search_song_names, + search_songs, +) +from ..config.settings import Settings + +SearchResponse = Mapping[str, Any] +SearchFunction = Callable[..., SearchResponse] +NameSearchFunction = Callable[..., Sequence[Any]] +DetailsFunction = Callable[[Settings, int], Mapping[str, Any]] +CategoryFunction = Callable[..., Mapping[str, Any]] +EraFunction = Callable[..., Sequence[Mapping[str, Any]]] +SongId = int | str + + +class LyricAvailability(str, Enum): + SYNCED = "synced" + PLAIN = "plain" + NONE = "none" + + +@dataclass(frozen=True, slots=True) +class CatalogueSearchResult: + selection_index: int + song_id: SongId | None + title: str | None + category: str | None + era: str | None + length: str | None + artists: tuple[str, ...] + producers: tuple[str, ...] + media_path: str | None + lyrics: LyricAvailability + downloadable: bool + album: str | None = None + track_number: str | None = None + + +@dataclass(frozen=True, slots=True) +class CataloguePage: + results: tuple[CatalogueSearchResult, ...] + page: int + page_size: int + total_count: int + next_page: int | None + previous_page: int | None + + @property + def range_start(self) -> int: + return (self.page - 1) * self.page_size + 1 if self.results else 0 + + @property + def range_end(self) -> int: + return self.range_start + len(self.results) - 1 if self.results else 0 + + +@dataclass(frozen=True, slots=True) +class CatalogueFilterOption: + label: str + value: str + identifier: int | str | None = None + + +@dataclass(frozen=True, slots=True) +class CatalogueFilterMetadata: + categories: tuple[CatalogueFilterOption, ...] + eras: tuple[CatalogueFilterOption, ...] + + +@dataclass(frozen=True, slots=True) +class SongDetails: + selection_index: int + song_id: SongId | None + title: str | None + category: str | None + era: str | None + length: str | None + artists: tuple[str, ...] + producers: tuple[str, ...] + media_path: str | None + lyrics: LyricAvailability + synced_lyrics: str | None + plain_lyrics: str | None + downloadable: bool + album: str | None = None + track_number: str | None = None + + +def _text(value: Any) -> str | None: + if value is None or isinstance(value, (dict, list, tuple, set)): + return None + text = str(value).strip() + return text or None + + +def _named_values(value: Any) -> tuple[str, ...]: + if value is None: + return () + if isinstance(value, str): + text = value.strip() + return (text,) if text else () + if isinstance(value, Mapping): + for key in ("name", "title"): + text = _text(value.get(key)) + if text: + return (text,) + return () + if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)): + values: list[str] = [] + for item in value: + values.extend(_named_values(item)) + return tuple(values) + return () + + +def _era(value: Any) -> str | None: + if isinstance(value, Mapping): + return _text(value.get("name")) + return _text(value) + + +def _named_value(value: Any) -> str | None: + if isinstance(value, Mapping): + return _text(value.get("name")) or _text(value.get("title")) + if isinstance(value, str): + return _text(value) + values = _named_values(value) + return values[0] if values else None + + +def _catalogue_album(record: Mapping[str, Any]) -> str | None: + explicit = _named_value(record.get("album")) + if explicit: + return explicit + media_path = _text(record.get("path") or record.get("file_path")) + category = _text(record.get("category")) + if not media_path or category is None or category.casefold() != "released": + return None + parent = Path(media_path).parent.name.strip() + parent = re.sub(r"^\d+\.\s*", "", parent).strip() + if parent.casefold() in {"released", "released discography", "singles", "compilation"}: + return None + return parent or None + + +def _track_number(record: Mapping[str, Any]) -> str | None: + for key in ("track_number", "track", "track_no"): + value = record.get(key) + if isinstance(value, bool) or isinstance(value, Mapping): + continue + if isinstance(value, (list, tuple)) and value: + if ( + len(value) > 1 + and isinstance(value[0], int) + and isinstance(value[1], int) + and value[0] > 0 + ): + value = f"{value[0]}/{value[1]}" if value[1] > 0 else value[0] + else: + value = value[0] + text = _text(value) + if text: + return text + return None + + +def _song_id(value: Any) -> SongId | None: + if isinstance(value, bool) or value is None: + return None + if isinstance(value, int): + return value + return _text(value) + + +def _lyrics(record: Mapping[str, Any]) -> tuple[LyricAvailability, str | None, str | None]: + synced = _text(record.get("synced_lyrics")) + plain = _text(record.get("lyrics")) + if synced: + return LyricAvailability.SYNCED, synced, plain + if plain: + return LyricAvailability.PLAIN, None, plain + return LyricAvailability.NONE, None, None + + +def _is_downloadable(settings: Settings, record: Mapping[str, Any]) -> bool: + try: + resolve_resource( + dict(record), + destination_dir=Path(settings.music_dir), + api_base=settings.api_base, + ) + except (ResourceResolutionError, TypeError, ValueError): + return False + return True + + +def _common_fields(settings: Settings, record: Mapping[str, Any]) -> dict[str, Any]: + lyric_status, synced, plain = _lyrics(record) + return { + "song_id": _song_id(record.get("id")), + "title": _text(record.get("title")) or _text(record.get("name")), + "category": _text(record.get("category")), + "era": _era(record.get("era")), + "length": _text(record.get("length")), + "artists": _named_values(record.get("credited_artists") or record.get("artist")), + "producers": _named_values(record.get("producers") or record.get("producer")), + "media_path": _text(record.get("path") or record.get("file_path")), + "lyrics": lyric_status, + "synced_lyrics": synced, + "plain_lyrics": plain, + "downloadable": _is_downloadable(settings, record), + "album": _catalogue_album(record), + "track_number": _track_number(record), + } + + +def search_catalogue( + settings: Settings, + query: str, + *, + category: str | None = None, + era: str | None = None, + refresh: bool = False, + searcher: SearchFunction = search_songs, +) -> tuple[CatalogueSearchResult, ...]: + """Search and normalize catalogue records without changing application state.""" + + return search_catalogue_page( + settings, + query, + category=category, + era=era, + refresh=refresh, + searcher=searcher, + ).results + + +def search_catalogue_page( + settings: Settings, + query: str, + *, + category: str | None = None, + era: str | None = None, + page: int = 1, + page_size: int = 50, + refresh: bool = False, + searcher: SearchFunction = search_songs, +) -> CataloguePage: + """Return one normalized, server-filtered catalogue page.""" + + response = searcher( + settings, + query, + category=category, + era=era, + page=page, + page_size=page_size, + refresh=refresh, + ) + response_data = response if isinstance(response, Mapping) else {} + raw_results = response_data.get("results", []) + if not isinstance(raw_results, Sequence) or isinstance(raw_results, (str, bytes, bytearray)): + raw_results = () + + results: list[CatalogueSearchResult] = [] + for index, record in enumerate(raw_results, start=1): + if not isinstance(record, Mapping): + continue + fields = _common_fields(settings, record) + fields.pop("synced_lyrics") + fields.pop("plain_lyrics") + results.append(CatalogueSearchResult(selection_index=index, **fields)) + normalized = tuple(results) + total = _nonnegative_int(response_data.get("count"), len(normalized)) + return CataloguePage( + results=normalized, + page=max(1, page), + page_size=max(1, page_size), + total_count=total, + next_page=page + 1 if response_data.get("next") else None, + previous_page=page - 1 if page > 1 and response_data.get("previous") else None, + ) + + +def get_catalogue_filters( + settings: Settings, + *, + refresh: bool = False, + category_fetcher: CategoryFunction = get_categories, + era_fetcher: EraFunction = get_eras, +) -> CatalogueFilterMetadata: + """Normalize API-provided selector labels and canonical request values.""" + + category_data = category_fetcher(settings, refresh=refresh) + raw_categories = category_data.get("categories", []) if isinstance(category_data, Mapping) else [] + categories: list[CatalogueFilterOption] = [] + if isinstance(raw_categories, Sequence) and not isinstance(raw_categories, (str, bytes, bytearray)): + for item in raw_categories: + if not isinstance(item, Mapping): + continue + value = _text(item.get("value")) + label = _text(item.get("label")) + if value and label: + categories.append(CatalogueFilterOption(label, value)) + + eras: list[CatalogueFilterOption] = [] + for item in era_fetcher(settings, refresh=refresh): + if not isinstance(item, Mapping): + continue + name = _text(item.get("name")) + identifier = _song_id(item.get("id")) + if name: + eras.append(CatalogueFilterOption(name, name, identifier)) + return CatalogueFilterMetadata(tuple(categories), tuple(eras)) + + +def get_song_details_by_id( + settings: Settings, + song_id: SongId, + *, + selection_index: int = 1, + details_fetcher: DetailsFunction = get_song, +) -> SongDetails | None: + """Load stable details for a selected catalogue record by numeric API ID.""" + + try: + numeric_id = int(song_id) + record = details_fetcher(settings, numeric_id) + except (TypeError, ValueError): + return None + if not isinstance(record, Mapping): + return None + return SongDetails(selection_index=selection_index, **_common_fields(settings, record)) + + +def _nonnegative_int(value: Any, default: int) -> int: + try: + parsed = int(value) + except (TypeError, ValueError): + return default + return max(0, parsed) + + +def get_song_details( + settings: Settings, + query: str, + *, + selection_index: int | None = None, + refresh: bool = False, + searcher: NameSearchFunction = search_song_names, + details_fetcher: DetailsFunction = get_song, +) -> SongDetails | None: + """Select a search result and return normalized song details.""" + + raw_results = searcher(settings, query, refresh=refresh) + results = list(raw_results) if isinstance(raw_results, Sequence) else [] + if not results: + return None + + selected = selection_index or 1 + if selected < 1 or selected > len(results): + raise RuntimeError("--index is outside the result list") + candidate = results[selected - 1] + if not isinstance(candidate, Mapping): + return None + + record: Mapping[str, Any] = candidate + candidate_id = _song_id(candidate.get("id")) + if candidate_id is not None: + try: + numeric_id = int(candidate_id) + fetched = details_fetcher(settings, numeric_id) + if isinstance(fetched, Mapping): + record = fetched + except Exception: + pass + + fields = _common_fields(settings, record) + return SongDetails(selection_index=selected, **fields) diff --git a/src/juice_lyrics/services/doctor.py b/src/juice_lyrics/services/doctor.py new file mode 100644 index 0000000..1b9ef72 --- /dev/null +++ b/src/juice_lyrics/services/doctor.py @@ -0,0 +1,402 @@ +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import asdict, dataclass +from enum import Enum +import importlib.util +import json +import os +from pathlib import Path +import re +import shutil +import subprocess +import sys +import tomllib +from typing import Any + +from .. import __version__ +from ..api.client import api_get +from ..backup.manager import list_backups +from ..config.settings import Settings +from .settings_snapshot import _rmpc_configured + + +class DoctorStatus(str, Enum): + PASS = "PASS" + WARN = "WARN" + FAIL = "FAIL" + + +@dataclass(frozen=True, slots=True) +class DoctorCheck: + key: str + label: str + status: DoctorStatus + detail: str + suggestion: str | None = None + + +@dataclass(frozen=True, slots=True) +class DoctorReport: + checks: tuple[DoctorCheck, ...] + + @property + def failed(self) -> int: + return sum(item.status is DoctorStatus.FAIL for item in self.checks) + + @property + def warned(self) -> int: + return sum(item.status is DoctorStatus.WARN for item in self.checks) + + @property + def passed(self) -> int: + return sum(item.status is DoctorStatus.PASS for item in self.checks) + + +ApiProbe = Callable[[str, int], Any] +ExecutableFinder = Callable[[str], str | None] +DiskUsageProbe = Callable[[str | os.PathLike[str]], Any] +RmpcProbe = Callable[[Path], bool] + + +def _nearest_existing(path: Path) -> Path | None: + candidate = path.expanduser() + while not candidate.exists(): + if candidate.parent == candidate: + return None + candidate = candidate.parent + return candidate + + +def _check_runtime( + command_finder: ExecutableFinder, + *, + invoked_command: str | None = None, +) -> DoctorCheck: + try: + invoked = Path(invoked_command or sys.argv[0]).expanduser() + if invoked.name in {"999", "juice-lyrics"} and invoked.parent != Path("."): + executable = str(invoked.resolve(strict=True)) + else: + executable = command_finder(invoked.name if invoked.name in {"999", "juice-lyrics"} else "999") + except Exception as exc: + return DoctorCheck("runtime", "Runtime", DoctorStatus.WARN, f"Executable location could not be inspected: {exc}") + detail = f"999 {__version__}; Python {sys.version.split()[0]}; executable {executable or 'not found in PATH'}" + if executable: + return DoctorCheck("runtime", "Runtime", DoctorStatus.PASS, detail) + return DoctorCheck( + "runtime", "Runtime", DoctorStatus.WARN, detail, + "The current Python package is importable, but reinstall the editable/pipx command if `999` should be on PATH.", + ) + + +def _check_dependencies() -> DoctorCheck: + if importlib.util.find_spec("mutagen") is None: + return DoctorCheck( + "dependencies", "Media dependency", DoctorStatus.FAIL, + "Mutagen is not importable.", "Reinstall 999 and its declared dependencies.", + ) + return DoctorCheck("dependencies", "Media dependency", DoctorStatus.PASS, "Mutagen is available.") + + +def _check_config(config_path: Path) -> DoctorCheck: + if not config_path.exists(): + return DoctorCheck( + "config", "Configuration", DoctorStatus.PASS, + f"No config file at {config_path}; built-in defaults or command-line overrides are in use.", + ) + try: + value = tomllib.loads(config_path.read_text(encoding="utf-8")) + if not isinstance(value, dict): + raise ValueError("configuration root is not a table") + for key, converter in ( + ("timeout", int), ("delay", float), + ("duration_tolerance", float), ("cache_ttl_hours", float), + ): + if key in value: + converter(value[key]) + if "music_dir" in value and not str(value["music_dir"]).strip(): + raise ValueError("music_dir is empty") + if "api_base" in value and not str(value["api_base"]).strip(): + raise ValueError("api_base is empty") + except (OSError, UnicodeError, tomllib.TOMLDecodeError, TypeError, ValueError) as exc: + return DoctorCheck( + "config", "Configuration", DoctorStatus.FAIL, + f"Configuration is unreadable or invalid: {exc}", + "Correct the config file, then run `999 doctor` again.", + ) + return DoctorCheck("config", "Configuration", DoctorStatus.PASS, f"Configuration is valid at {config_path}.") + + +def _check_state(state_file: Path) -> DoctorCheck: + if not state_file.exists(): + return DoctorCheck("state", "Library state", DoctorStatus.PASS, f"No state file at {state_file}; this is valid before the first Library Sync.") + try: + value = json.loads(state_file.read_text(encoding="utf-8")) + if not isinstance(value, dict): + raise ValueError("root must be an object") + files = value.get("files", {}) + if not isinstance(files, dict): + raise ValueError("files must be an object") + malformed = sum(not isinstance(key, str) or not isinstance(entry, dict) for key, entry in files.items()) + except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as exc: + return DoctorCheck( + "state", "Library state", DoctorStatus.FAIL, + f"State is unreadable or malformed: {exc}", + "Preserve the file for recovery; do not delete it blindly. Use a backup or advanced state maintenance.", + ) + if malformed: + return DoctorCheck( + "state", "Library state", DoctorStatus.WARN, + f"State loaded, but {malformed} record(s) have an unsupported shape.", + "Run the state maintenance preview before removing anything.", + ) + return DoctorCheck("state", "Library state", DoctorStatus.PASS, f"State is valid at {state_file} ({len(files)} record(s)).") + + +def _check_cache(cache_dir: Path, *, sample_limit: int = 100) -> DoctorCheck: + if not cache_dir.exists(): + return DoctorCheck("cache", "API cache", DoctorStatus.PASS, f"Cache has not been created at {cache_dir} yet.") + if not cache_dir.is_dir(): + return DoctorCheck("cache", "API cache", DoctorStatus.FAIL, "Cache path is not a directory.", "Move the conflicting path and retry.") + try: + files = tuple(path for path in cache_dir.iterdir() if path.is_file() and path.suffix.casefold() == ".json") + malformed = 0 + for path in files[:sample_limit]: + try: + json.loads(path.read_text(encoding="utf-8")) + except (OSError, UnicodeError, json.JSONDecodeError): + malformed += 1 + except OSError as exc: + return DoctorCheck("cache", "API cache", DoctorStatus.FAIL, f"Cache cannot be inspected: {exc}", "Check cache directory permissions.") + sampled = min(len(files), sample_limit) + if malformed: + return DoctorCheck( + "cache", "API cache", DoctorStatus.WARN, + f"{malformed} malformed JSON file(s) found among {sampled} inspected.", + "Run `999 cache clear`; catalogue data will be fetched again when needed.", + ) + suffix = f"; first {sample_limit} inspected" if len(files) > sample_limit else "" + return DoctorCheck("cache", "API cache", DoctorStatus.PASS, f"Cache is readable ({len(files)} JSON file(s){suffix}).") + + +def _check_library(music_dir: Path) -> DoctorCheck: + root = music_dir.expanduser() + if not root.exists(): + return DoctorCheck( + "library", "Music library", DoctorStatus.FAIL, + f"Configured music directory does not exist: {root}", + "Create it or update music_dir in the 999 configuration.", + ) + if not root.is_dir(): + return DoctorCheck("library", "Music library", DoctorStatus.FAIL, "Configured music path is not a directory.", "Update music_dir to a directory.") + if not os.access(root, os.R_OK | os.X_OK): + return DoctorCheck("library", "Music library", DoctorStatus.FAIL, "Music directory is not readable.", "Check directory ownership and permissions.") + counts = {"MP3": 0, "FLAC": 0, "M4A": 0} + errors: list[str] = [] + + def failed(exc: OSError) -> None: + errors.append(str(exc) or type(exc).__name__) + + try: + for _, _, names in os.walk(root, onerror=failed): + for name in names: + suffix = Path(name).suffix.casefold() + if suffix in {".mp3", ".flac", ".m4a"}: + counts[suffix[1:].upper()] += 1 + except OSError as exc: + errors.append(str(exc) or type(exc).__name__) + total = sum(counts.values()) + detail = f"Readable at {root}; {total} supported file(s) (MP3 {counts['MP3']}, FLAC {counts['FLAC']}, M4A {counts['M4A']})." + if errors: + return DoctorCheck("library", "Music library", DoctorStatus.WARN, detail + " Some directories could not be read.", "Check permissions on nested library directories.") + if total == 0: + return DoctorCheck("library", "Music library", DoctorStatus.WARN, detail, "Add supported audio or verify that music_dir points to the intended library.") + return DoctorCheck("library", "Music library", DoctorStatus.PASS, detail) + + +def _check_catalogue(settings: Settings, probe: ApiProbe) -> DoctorCheck: + url = settings.songs_endpoint + "?page=1&page_size=1" + try: + value = probe(url, min(settings.timeout, 10)) + except Exception as exc: + return DoctorCheck( + "catalogue", "Catalogue", DoctorStatus.WARN, + f"Catalogue is offline or unreachable: {exc}", + "Check the network/API URL. Local Library features remain available offline.", + ) + if not isinstance(value, Mapping): + return DoctorCheck("catalogue", "Catalogue", DoctorStatus.FAIL, "Catalogue returned an invalid non-object response.", "Check api_base or try again later.") + results = value.get("results") + if not isinstance(results, Sequence) or isinstance(results, (str, bytes, bytearray)): + return DoctorCheck("catalogue", "Catalogue", DoctorStatus.FAIL, "Catalogue response is missing a valid results list.", "Check api_base or report an API compatibility problem.") + if any(not isinstance(item, Mapping) for item in results): + return DoctorCheck("catalogue", "Catalogue", DoctorStatus.FAIL, "Catalogue results contain invalid records.", "Report an API compatibility problem.") + return DoctorCheck("catalogue", "Catalogue", DoctorStatus.PASS, "Catalogue responded with a valid small page.") + + +def _check_backups(backup_dir: Path, disk_usage: DiskUsageProbe) -> tuple[DoctorCheck, DoctorCheck]: + directory = backup_dir.expanduser() + if directory.exists() and not directory.is_dir(): + backups = DoctorCheck("backups", "Backups", DoctorStatus.FAIL, "Backup path is not a directory.", "Move the conflicting path before metadata or lyric maintenance.") + elif directory.exists() and not os.access(directory, os.R_OK | os.X_OK): + backups = DoctorCheck("backups", "Backups", DoctorStatus.FAIL, "Backup directory is not readable.", "Check backup directory ownership and permissions.") + else: + records = list_backups(directory) + backups = DoctorCheck("backups", "Backups", DoctorStatus.PASS, f"Backup location {directory} is available; {len(records)} valid backup(s).") + nearest = _nearest_existing(directory) + if nearest is None: + storage = DoctorCheck("storage", "Available storage", DoctorStatus.WARN, "Available storage could not be determined.") + else: + try: + usage = disk_usage(nearest) + free = int(usage.free) + gib = free / (1024 ** 3) + status = DoctorStatus.WARN if free < 512 * 1024 * 1024 else DoctorStatus.PASS + suggestion = "Free space is low; metadata backups require room for complete audio copies." if status is DoctorStatus.WARN else None + storage = DoctorCheck("storage", "Available storage", status, f"{gib:.1f} GiB free on the data filesystem.", suggestion) + except (OSError, ValueError, AttributeError) as exc: + storage = DoctorCheck("storage", "Available storage", DoctorStatus.WARN, f"Available storage could not be determined: {exc}") + return backups, storage + + +def _probe_rmpc(executable: Path) -> bool: + try: + return subprocess.run( + [str(executable), "remote", "query", "active-tab"], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + timeout=3, + check=False, + ).returncode == 0 + except (OSError, subprocess.SubprocessError): + return False + + +def _check_rmpc( + settings: Settings, + *, + config_path: Path, + executable_finder: ExecutableFinder, + connectivity_probe: RmpcProbe, +) -> DoctorCheck: + try: + executable_raw = executable_finder("rmpc") + executable = Path(executable_raw) if executable_raw else None + except Exception as exc: + return DoctorCheck("rmpc", "rmpc / MPD", DoctorStatus.WARN, f"Optional rmpc executable could not be inspected: {exc}") + if executable is None: + return DoctorCheck("rmpc", "rmpc / MPD", DoctorStatus.WARN, "Optional rmpc executable is not installed or not in PATH.", "Install rmpc only if player integration is wanted.") + try: + configured = config_path.exists() and _rmpc_configured( + config_path.read_text(encoding="utf-8"), Path(settings.music_dir) + ) + except (OSError, UnicodeError) as exc: + return DoctorCheck("rmpc", "rmpc / MPD", DoctorStatus.WARN, f"Optional rmpc config could not be read: {exc}") + if not configured: + return DoctorCheck( + "rmpc", "rmpc / MPD", DoctorStatus.WARN, + "rmpc is detected, but sidecar indexing is not configured for this music directory.", + "Use `999 rmpc setup` only if this integration is wanted.", + ) + if not connectivity_probe(executable): + return DoctorCheck( + "rmpc", "rmpc / MPD", DoctorStatus.WARN, + "rmpc is configured, but rmpc/MPD is not currently responding.", + "Start MPD/rmpc and retry if player integration is wanted.", + ) + return DoctorCheck("rmpc", "rmpc / MPD", DoctorStatus.PASS, "Optional rmpc sidecar configuration and MPD connection are available.") + + +def run_doctor( + settings: Settings, + *, + config_path: Path, + state_file: Path, + cache_dir: Path, + backup_dir: Path, + rmpc_config_path: Path, + api_probe: ApiProbe = api_get, + command_finder: ExecutableFinder = shutil.which, + disk_usage: DiskUsageProbe = shutil.disk_usage, + rmpc_probe: RmpcProbe = _probe_rmpc, + invoked_command: str | None = None, +) -> DoctorReport: + """Run bounded, read-only application diagnostics.""" + + def safe(key: str, label: str, action: Callable[[], DoctorCheck]) -> DoctorCheck: + try: + return action() + except Exception as exc: + return DoctorCheck( + key, label, DoctorStatus.FAIL, + f"Could not inspect this area safely: {exc}", + "Check path permissions and retry.", + ) + + checks = [ + safe( + "runtime", + "Runtime", + lambda: _check_runtime(command_finder, invoked_command=invoked_command), + ), + safe("dependencies", "Media dependency", _check_dependencies), + safe("config", "Configuration", lambda: _check_config(Path(config_path))), + safe("state", "Library state", lambda: _check_state(Path(state_file))), + safe("cache", "API cache", lambda: _check_cache(Path(cache_dir))), + safe("library", "Music library", lambda: _check_library(Path(settings.music_dir))), + safe("catalogue", "Catalogue", lambda: _check_catalogue(settings, api_probe)), + ] + try: + checks.extend(_check_backups(Path(backup_dir), disk_usage)) + except Exception as exc: + checks.extend(( + DoctorCheck("backups", "Backups", DoctorStatus.FAIL, f"Could not inspect backups safely: {exc}", "Check backup path permissions."), + DoctorCheck("storage", "Available storage", DoctorStatus.WARN, "Available storage could not be determined."), + )) + checks.append(safe("rmpc", "rmpc / MPD", lambda: _check_rmpc( + settings, + config_path=Path(rmpc_config_path), + executable_finder=command_finder, + connectivity_probe=rmpc_probe, + ))) + return DoctorReport(tuple(checks)) + + +_SECRET_RE = re.compile(r"(?i)(token|secret|password|credential|api[_-]?key)(\s*[:=]\s*)([^\s,;]+)") + + +def sanitize_support_text(value: str, *, home: Path | None = None) -> str: + """Remove common path and credential material from a support-report value.""" + + text = str(value) + home_path = str((home or Path.home()).expanduser()) + if home_path and home_path != "/": + text = re.sub(re.escape(home_path) + r"[^\s,;]*", "", text) + text = re.sub(r"(?", text) + text = _SECRET_RE.sub(lambda match: f"{match.group(1)}{match.group(2)}", text) + text = re.sub(r"(?i)(https?://)([^/@\s:]+):([^/@\s]+)@", r"\1@", text) + return text + + +def support_report_data(report: DoctorReport, *, home: Path | None = None) -> dict[str, Any]: + return { + "product": "999", + "version": __version__, + "python": sys.version.split()[0], + "summary": {"pass": report.passed, "warn": report.warned, "fail": report.failed}, + "checks": [ + { + **asdict(check), + "status": check.status.value, + "detail": sanitize_support_text(check.detail, home=home), + "suggestion": sanitize_support_text(check.suggestion, home=home) if check.suggestion else None, + } + for check in report.checks + ], + "privacy": "Sanitized: no song list or state contents are included.", + } + + +def render_support_report(report: DoctorReport, *, home: Path | None = None) -> str: + return json.dumps(support_report_data(report, home=home), indent=2, ensure_ascii=False) diff --git a/src/juice_lyrics/services/download_queue.py b/src/juice_lyrics/services/download_queue.py new file mode 100644 index 0000000..f3ea86c --- /dev/null +++ b/src/juice_lyrics/services/download_queue.py @@ -0,0 +1,1172 @@ +from __future__ import annotations + +from collections.abc import Callable, Sequence +from dataclasses import dataclass +from enum import Enum +import hashlib +from pathlib import Path +from threading import Lock + +from ..acquisition.duplicates import DuplicateMatch, find_duplicate +from ..acquisition.jobs import DEFAULT_JOBS_FILE, AcquisitionJob, JobStore, JobStoreError +from ..acquisition.downloader import DownloadPolicy +from ..acquisition.integration import IntegrationResult, integrate_downloaded_mp3 +from ..acquisition.models import ( + AcquisitionFailureStage, + AcquisitionItem, + AcquisitionResult, + AcquisitionState, +) +from ..acquisition.resolver import ResourceResolutionError, resolve_resource +from ..acquisition.runner import AcquisitionRunSummary, run_job +from ..api.client import get_song +from ..config.settings import Settings +from .acquisition_queue import ( + QueueFailureStage, + QueueItem, + QueueSnapshot, + QueueStatus, + get_queue_snapshot, +) +from .catalogue import CatalogueSearchResult + + +class DownloadQueueItemStatus(str, Enum): + QUEUED = "queued" + DOWNLOADING = "downloading" + PROCESSING = "processing" + COMPLETED = "completed" + FAILED = "failed" + NEEDS_ATTENTION = "needs_attention" + + +class QueueDuplicateReason(str, Enum): + ALREADY_QUEUED = "already_queued" + ALREADY_DOWNLOADED = "already_downloaded" + + +class QueueAddStatus(str, Enum): + READY = "ready" + ADDED = "added" + ALREADY_QUEUED = "already_queued" + ALREADY_DOWNLOADED = "already_downloaded" + MEDIA_UNAVAILABLE = "media_unavailable" + INVALID_SELECTION = "invalid_selection" + RESOLUTION_FAILED = "resolution_failed" + SAVE_FAILED = "save_failed" + + +class QueueBatchAddItemStatus(str, Enum): + ELIGIBLE = "eligible" + ALREADY_QUEUED = "already_queued" + ALREADY_DOWNLOADED = "already_downloaded" + UNAVAILABLE = "unavailable" + STALE = "stale" + INVALID = "invalid" + + +class QueueBatchAddStatus(str, Enum): + READY = "ready" + ADDED = "added" + NOTHING_TO_ADD = "nothing_to_add" + SAVE_FAILED = "save_failed" + + +class DownloadExecutionAction(str, Enum): + START = "start" + RESUME = "resume" + + +class DownloadExecutionStatus(str, Enum): + READY = "ready" + DOWNLOADING = "downloading" + PROCESSING = "processing" + COMPLETED = "completed" + FAILED = "failed" + NOT_FOUND = "not_found" + NOT_ELIGIBLE = "not_eligible" + ALREADY_RUNNING = "already_running" + RETRY_REQUIRED = "retry_required" + STORE_FAILED = "store_failed" + + +class DownloadRetryAction(str, Enum): + RESUME_DOWNLOAD = "resume_download" + DOWNLOAD_AGAIN = "download_again" + PROCESS_ONLY = "process_only" + + +class DownloadRetryStatus(str, Enum): + READY = "ready" + COMPLETED = "completed" + FAILED = "failed" + NOT_FOUND = "not_found" + NOT_ELIGIBLE = "not_eligible" + ALREADY_RUNNING = "already_running" + STORE_FAILED = "store_failed" + + +@dataclass(frozen=True, slots=True) +class DownloadQueueItem: + reference: str + song_id: str | None + title: str + artist: str | None + category: str | None + era: str | None + destination: Path | None + status: DownloadQueueItemStatus + bytes_written: int + expected_bytes: int | None + failure_stage: str | None + error: str | None + retryable: bool + queued_at: str | None + internal_reference: str | None = None + + @property + def progress_percent(self) -> int | None: + if self.expected_bytes is None or self.expected_bytes <= 0: + return None + return min(100, int(self.bytes_written * 100 / self.expected_bytes)) + + +@dataclass(frozen=True, slots=True) +class DownloadQueueSnapshot: + items: tuple[DownloadQueueItem, ...] + queued_count: int + downloading_count: int + processing_count: int + failed_count: int + completed_count: int + + @property + def active_count(self) -> int: + return len(self.items) + + +@dataclass(frozen=True, slots=True) +class PlannedQueueItem: + item: AcquisitionItem + song_id: str + artist: str | None + category: str | None + era: str | None + + +@dataclass(frozen=True, slots=True) +class QueueAddPlan: + items: tuple[PlannedQueueItem, ...] + + +@dataclass(frozen=True, slots=True) +class QueueAddResult: + status: QueueAddStatus + message: str + plan: QueueAddPlan | None = None + added_count: int = 0 + queue_references: tuple[str, ...] = () + duplicate_reason: QueueDuplicateReason | None = None + + @property + def ok(self) -> bool: + return self.status in {QueueAddStatus.READY, QueueAddStatus.ADDED} + + +@dataclass(frozen=True, slots=True) +class QueueBatchAddItem: + song_id: str | None + title: str + status: QueueBatchAddItemStatus + message: str + planned: PlannedQueueItem | None = None + + +@dataclass(frozen=True, slots=True) +class QueueBatchAddPlan: + items: tuple[QueueBatchAddItem, ...] + + @property + def selected_count(self) -> int: + return len(self.items) + + @property + def eligible(self) -> tuple[PlannedQueueItem, ...]: + return tuple( + item.planned + for item in self.items + if item.status is QueueBatchAddItemStatus.ELIGIBLE and item.planned is not None + ) + + @property + def eligible_count(self) -> int: + return len(self.eligible) + + def count(self, status: QueueBatchAddItemStatus) -> int: + return sum(item.status is status for item in self.items) + + +@dataclass(frozen=True, slots=True) +class QueueBatchAddResult: + status: QueueBatchAddStatus + message: str + plan: QueueBatchAddPlan | None = None + added_count: int = 0 + queue_references: tuple[str, ...] = () + added_song_ids: tuple[str, ...] = () + + @property + def ok(self) -> bool: + return self.status in {QueueBatchAddStatus.READY, QueueBatchAddStatus.ADDED} + + +@dataclass(frozen=True, slots=True) +class DownloadExecutionPlan: + reference: str + job_id: str + item_index: int + song_id: str + title: str + artist: str | None + destination: Path + current_status: DownloadQueueItemStatus + action: DownloadExecutionAction + + +@dataclass(frozen=True, slots=True) +class DownloadProgress: + reference: str + status: DownloadExecutionStatus + bytes_written: int = 0 + total_bytes: int | None = None + message: str = "" + + @property + def percent(self) -> int | None: + if self.total_bytes is None or self.total_bytes <= 0: + return None + return min(100, int(self.bytes_written * 100 / self.total_bytes)) + + +@dataclass(frozen=True, slots=True) +class DownloadExecutionResult: + status: DownloadExecutionStatus + message: str + plan: DownloadExecutionPlan | None = None + failure_stage: str | None = None + error: str | None = None + + @property + def ok(self) -> bool: + return self.status in {DownloadExecutionStatus.READY, DownloadExecutionStatus.COMPLETED} + + +@dataclass(frozen=True, slots=True) +class DownloadRetryPlan: + reference: str + job_id: str + item_index: int + song_id: str + title: str + destination: Path + previous_failure: str + action: DownloadRetryAction + + +@dataclass(frozen=True, slots=True) +class DownloadRetryResult: + status: DownloadRetryStatus + message: str + plan: DownloadRetryPlan | None = None + failure_stage: str | None = None + error: str | None = None + + @property + def ok(self) -> bool: + return self.status in {DownloadRetryStatus.READY, DownloadRetryStatus.COMPLETED} + + +class QueueMutationStatus(str, Enum): + READY = "ready" + COMPLETED = "completed" + NOT_FOUND = "not_found" + NOT_ELIGIBLE = "not_eligible" + ACTIVE = "active" + STORE_FAILED = "store_failed" + + +@dataclass(frozen=True, slots=True) +class QueueMutationPlan: + action: str + reference: str | None = None + count: int = 0 + + +@dataclass(frozen=True, slots=True) +class QueueMutationResult: + status: QueueMutationStatus + message: str + removed_count: int = 0 + retained_active_count: int = 0 + + +@dataclass(frozen=True, slots=True) +class DownloadAllPlan: + eligible: tuple[DownloadExecutionPlan, ...] + failed_count: int + active_count: int + completed_count: int + skipped_count: int + + +class DownloadBatchStatus(str, Enum): + READY = "ready" + COMPLETED = "completed" + FAILED = "failed" + STORE_FAILED = "store_failed" + + +@dataclass(frozen=True, slots=True) +class DownloadBatchItemResult: + reference: str + title: str + status: DownloadBatchStatus + message: str + + +@dataclass(frozen=True, slots=True) +class DownloadBatchProgress: + completed: int + total: int + reference: str + title: str + status: DownloadExecutionStatus + + +@dataclass(frozen=True, slots=True) +class DownloadAllResult: + status: DownloadBatchStatus + message: str + completed_count: int = 0 + failed_count: int = 0 + skipped_count: int = 0 + items: tuple[DownloadBatchItemResult, ...] = () + + +QueueReader = Callable[[Path], QueueSnapshot] +Resolver = Callable[..., AcquisitionItem] +DuplicateFinder = Callable[..., DuplicateMatch | None] +StoreFactory = Callable[[Path], JobStore] +ExecutionProgressCallback = Callable[[DownloadProgress], None] +Runner = Callable[..., AcquisitionRunSummary] +Integration = Callable[..., IntegrationResult] +SongFetcher = Callable[[Settings, int], dict[str, object]] + + +_EXECUTION_CLAIM_LOCK = Lock() +_ACTIVE_EXECUTIONS: set[str] = set() + + +def _metadata(item: QueueItem) -> dict[str, str]: + return dict(item.metadata) + + +def _status(status: QueueStatus) -> DownloadQueueItemStatus: + if status is QueueStatus.PENDING: + return DownloadQueueItemStatus.QUEUED + if status in {QueueStatus.CHECKING_EXISTING, QueueStatus.DOWNLOADING}: + return DownloadQueueItemStatus.DOWNLOADING + if status in {QueueStatus.VALIDATING, QueueStatus.POST_PROCESSING}: + return DownloadQueueItemStatus.PROCESSING + if status in {QueueStatus.COMPLETED, QueueStatus.SKIPPED}: + return DownloadQueueItemStatus.COMPLETED + if status is QueueStatus.FAILED: + return DownloadQueueItemStatus.FAILED + return DownloadQueueItemStatus.NEEDS_ATTENTION + + +def _failure_label(stage: QueueFailureStage | None) -> str | None: + return { + QueueFailureStage.TRANSPORT: "Download failed", + QueueFailureStage.VALIDATION: "File validation failed", + QueueFailureStage.LYRICS: "Lyrics processing failed", + QueueFailureStage.LRC: "LRC creation failed", + QueueFailureStage.STATE: "Library update failed", + QueueFailureStage.UNKNOWN: "Queue processing failed", + None: None, + }[stage] + + +def project_download_queue(snapshot: QueueSnapshot) -> DownloadQueueSnapshot: + """Flatten durable jobs into the track-oriented queue used by frontends.""" + + projected: list[DownloadQueueItem] = [] + completed_count = 0 + for job in snapshot.jobs: + for item_index, item in enumerate(job.items): + status = _status(item.status) + if status is DownloadQueueItemStatus.COMPLETED: + completed_count += 1 + continue + metadata = _metadata(item) + projected.append(DownloadQueueItem( + reference=f"{job.job_id}:{item_index}", + song_id=item.identifier, + title=item.title or "Unknown song", + artist=metadata.get("artist"), + category=metadata.get("category"), + era=metadata.get("era"), + destination=item.destination, + status=status, + bytes_written=item.bytes_written, + expected_bytes=item.expected_bytes, + failure_stage=_failure_label(item.failure_stage), + error=item.error, + retryable=item.retryable, + queued_at=job.created_at, + internal_reference=f"{job.job_id}:{item_index}", + )) + items = tuple(projected) + return DownloadQueueSnapshot( + items=items, + queued_count=sum(item.status is DownloadQueueItemStatus.QUEUED for item in items), + downloading_count=sum(item.status is DownloadQueueItemStatus.DOWNLOADING for item in items), + processing_count=sum(item.status is DownloadQueueItemStatus.PROCESSING for item in items), + failed_count=sum(item.status in {DownloadQueueItemStatus.FAILED, DownloadQueueItemStatus.NEEDS_ATTENTION} for item in items), + completed_count=completed_count, + ) + + +def get_download_queue_snapshot(path: Path = DEFAULT_JOBS_FILE) -> DownloadQueueSnapshot: + return project_download_queue(get_queue_snapshot(path)) + + +def _selection_resource(selection: CatalogueSearchResult) -> dict[str, object]: + return { + "id": selection.song_id, + "title": selection.title, + "path": selection.media_path, + "artist": ", ".join(selection.artists) or None, + "category": selection.category, + "era": selection.era, + } + + +def _existing_queue_duplicate( + item: AcquisitionItem, + snapshot: QueueSnapshot, +) -> QueueItem | None: + for job in snapshot.jobs: + for queued in job.items: + if queued.status in {QueueStatus.COMPLETED, QueueStatus.SKIPPED}: + continue + if item.identifier and queued.identifier == item.identifier: + return queued + if queued.destination == item.destination: + return queued + return None + + +def plan_queue_additions( + settings: Settings, + selections: Sequence[CatalogueSearchResult], + *, + destination_dir: Path | None = None, + jobs_path: Path = DEFAULT_JOBS_FILE, + queue_reader: QueueReader = get_queue_snapshot, + resolver: Resolver = resolve_resource, + duplicate_finder: DuplicateFinder = find_duplicate, +) -> QueueAddResult: + """Validate one or more explicit catalogue selections without writing anything.""" + + if not selections: + return QueueAddResult(QueueAddStatus.INVALID_SELECTION, "Select a song first.") + target_dir = Path(destination_dir or settings.music_dir).expanduser() + try: + snapshot = queue_reader(Path(jobs_path)) + except PermissionError: + return QueueAddResult(QueueAddStatus.SAVE_FAILED, "Unable to inspect the queue: permission denied.") + except (JobStoreError, OSError) as exc: + return QueueAddResult(QueueAddStatus.SAVE_FAILED, f"Unable to inspect the queue: {exc}") + planned: list[PlannedQueueItem] = [] + seen_ids: set[str] = set() + seen_destinations: set[Path] = set() + for selection in selections: + if not selection.downloadable or not selection.media_path: + return QueueAddResult(QueueAddStatus.MEDIA_UNAVAILABLE, "Media is unavailable for this song.") + if selection.song_id is None or not selection.title: + return QueueAddResult(QueueAddStatus.INVALID_SELECTION, "This song lacks a stable catalogue ID or title.") + try: + item = resolver( + _selection_resource(selection), + destination_dir=target_dir, + api_base=settings.api_base, + ) + except (ResourceResolutionError, TypeError, ValueError) as exc: + return QueueAddResult(QueueAddStatus.RESOLUTION_FAILED, f"Unable to resolve download: {exc}") + if item.identifier in seen_ids or item.destination in seen_destinations: + return QueueAddResult(QueueAddStatus.ALREADY_QUEUED, f"{item.title} is already selected.", duplicate_reason=QueueDuplicateReason.ALREADY_QUEUED) + if _existing_queue_duplicate(item, snapshot) is not None: + return QueueAddResult(QueueAddStatus.ALREADY_QUEUED, f"{item.title} is already in the queue.", duplicate_reason=QueueDuplicateReason.ALREADY_QUEUED) + duplicate = duplicate_finder(item, search_dir=target_dir) + if duplicate is not None: + return QueueAddResult( + QueueAddStatus.ALREADY_DOWNLOADED, + f"{item.title} is already downloaded at {duplicate.path}.", + duplicate_reason=QueueDuplicateReason.ALREADY_DOWNLOADED, + ) + seen_ids.add(item.identifier) + seen_destinations.add(item.destination) + planned.append(PlannedQueueItem( + item=item, + song_id=str(selection.song_id), + artist=", ".join(selection.artists) or None, + category=selection.category, + era=selection.era, + )) + plan = QueueAddPlan(tuple(planned)) + return QueueAddResult(QueueAddStatus.READY, "Ready to add to the download queue.", plan=plan) + + +def add_to_download_queue( + plan: QueueAddPlan, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + queue_reader: QueueReader = get_queue_snapshot, + duplicate_finder: DuplicateFinder = find_duplicate, + store_factory: StoreFactory = JobStore, +) -> QueueAddResult: + """Persist a validated queue addition exactly once as one durable backend job.""" + + if not plan.items: + return QueueAddResult(QueueAddStatus.INVALID_SELECTION, "Nothing was selected for the queue.") + try: + snapshot = queue_reader(Path(jobs_path)) + for planned in plan.items: + if _existing_queue_duplicate(planned.item, snapshot) is not None: + return QueueAddResult(QueueAddStatus.ALREADY_QUEUED, f"{planned.item.title} is already in the queue.", duplicate_reason=QueueDuplicateReason.ALREADY_QUEUED) + duplicate = duplicate_finder(planned.item, search_dir=planned.item.destination.parent) + if duplicate is not None: + return QueueAddResult(QueueAddStatus.ALREADY_DOWNLOADED, f"{planned.item.title} is already downloaded at {duplicate.path}.", duplicate_reason=QueueDuplicateReason.ALREADY_DOWNLOADED) + store = store_factory(Path(jobs_path)) + job: AcquisitionJob = store.create(planned.item for planned in plan.items) + except PermissionError: + return QueueAddResult(QueueAddStatus.SAVE_FAILED, "Unable to save the queue: permission denied.") + except (JobStoreError, OSError) as exc: + return QueueAddResult(QueueAddStatus.SAVE_FAILED, f"Unable to save the queue: {exc}") + references = tuple(f"{job.job_id}:{index}" for index in range(len(plan.items))) + return QueueAddResult( + QueueAddStatus.ADDED, + f"Added {len(plan.items)} song{'s' if len(plan.items) != 1 else ''} to the download queue.", + added_count=len(plan.items), + queue_references=references, + ) + + +def _batch_add_message(added: int, plan: QueueBatchAddPlan) -> str: + parts = ["No songs added" if added == 0 else f"Added {added} song{'s' if added != 1 else ''}"] + already_queued = plan.count(QueueBatchAddItemStatus.ALREADY_QUEUED) + unavailable = plan.count(QueueBatchAddItemStatus.UNAVAILABLE) + plan.count(QueueBatchAddItemStatus.STALE) + downloaded = plan.count(QueueBatchAddItemStatus.ALREADY_DOWNLOADED) + invalid = plan.count(QueueBatchAddItemStatus.INVALID) + if already_queued: + parts.append(f"{already_queued} already queued") + if downloaded: + parts.append(f"{downloaded} already downloaded") + if unavailable: + parts.append(f"{unavailable} unavailable") + if invalid: + parts.append(f"{invalid} invalid") + return " · ".join(parts) + + +def plan_queue_batch_additions( + settings: Settings, + selections: Sequence[CatalogueSearchResult], + *, + destination_dir: Path | None = None, + jobs_path: Path = DEFAULT_JOBS_FILE, + queue_reader: QueueReader = get_queue_snapshot, + resolver: Resolver = resolve_resource, + duplicate_finder: DuplicateFinder = find_duplicate, +) -> QueueBatchAddResult: + """Plan a stable-ID batch queue addition without writing persistent state.""" + + if not selections: + return QueueBatchAddResult(QueueBatchAddStatus.NOTHING_TO_ADD, "Select one or more songs first.") + target_dir = Path(destination_dir or settings.music_dir).expanduser() + try: + snapshot = queue_reader(Path(jobs_path)) + except PermissionError: + return QueueBatchAddResult(QueueBatchAddStatus.SAVE_FAILED, "Unable to inspect the queue: permission denied.") + except (JobStoreError, OSError) as exc: + return QueueBatchAddResult(QueueBatchAddStatus.SAVE_FAILED, f"Unable to inspect the queue: {exc}") + + outcomes: list[QueueBatchAddItem] = [] + seen_ids: set[str] = set() + seen_destinations: set[Path] = set() + for selection in selections: + song_id = str(selection.song_id) if selection.song_id is not None else None + title = selection.title or "Unknown song" + if song_id is None or not selection.title: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.STALE, "Stable catalogue metadata is unavailable.")) + continue + if song_id in seen_ids: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.ALREADY_QUEUED, "Repeated selection was ignored.")) + continue + seen_ids.add(song_id) + if not selection.downloadable or not selection.media_path: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.UNAVAILABLE, "Media is unavailable.")) + continue + try: + item = resolver( + _selection_resource(selection), + destination_dir=target_dir, + api_base=settings.api_base, + ) + except (ResourceResolutionError, TypeError, ValueError) as exc: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.INVALID, f"Unable to resolve download: {exc}")) + continue + if item.destination in seen_destinations: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.ALREADY_QUEUED, "Another selection has the same destination.")) + continue + seen_destinations.add(item.destination) + if _existing_queue_duplicate(item, snapshot) is not None: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.ALREADY_QUEUED, "Already in Downloads.")) + continue + duplicate = duplicate_finder(item, search_dir=target_dir) + if duplicate is not None: + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.ALREADY_DOWNLOADED, f"Already downloaded at {duplicate.path}.")) + continue + planned = PlannedQueueItem( + item=item, + song_id=song_id, + artist=", ".join(selection.artists) or None, + category=selection.category, + era=selection.era, + ) + outcomes.append(QueueBatchAddItem(song_id, title, QueueBatchAddItemStatus.ELIGIBLE, "Ready to add.", planned)) + + plan = QueueBatchAddPlan(tuple(outcomes)) + status = QueueBatchAddStatus.READY if plan.eligible else QueueBatchAddStatus.NOTHING_TO_ADD + message = "Ready to add selected songs." if plan.eligible else _batch_add_message(0, plan) + return QueueBatchAddResult(status, message, plan=plan) + + +def add_batch_to_download_queue( + plan: QueueBatchAddPlan, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + queue_reader: QueueReader = get_queue_snapshot, + duplicate_finder: DuplicateFinder = find_duplicate, + store_factory: StoreFactory = JobStore, +) -> QueueBatchAddResult: + """Revalidate and atomically persist the still-eligible portion of a batch.""" + + if not plan.items: + return QueueBatchAddResult(QueueBatchAddStatus.NOTHING_TO_ADD, "Nothing was selected for Downloads.", plan=plan) + try: + snapshot = queue_reader(Path(jobs_path)) + final_items: list[QueueBatchAddItem] = [] + eligible: list[PlannedQueueItem] = [] + for outcome in plan.items: + planned = outcome.planned + if outcome.status is not QueueBatchAddItemStatus.ELIGIBLE or planned is None: + final_items.append(outcome) + continue + if _existing_queue_duplicate(planned.item, snapshot) is not None: + final_items.append(QueueBatchAddItem(outcome.song_id, outcome.title, QueueBatchAddItemStatus.ALREADY_QUEUED, "Already in Downloads.")) + continue + duplicate = duplicate_finder(planned.item, search_dir=planned.item.destination.parent) + if duplicate is not None: + final_items.append(QueueBatchAddItem(outcome.song_id, outcome.title, QueueBatchAddItemStatus.ALREADY_DOWNLOADED, f"Already downloaded at {duplicate.path}.")) + continue + final_items.append(outcome) + eligible.append(planned) + final_plan = QueueBatchAddPlan(tuple(final_items)) + if not eligible: + return QueueBatchAddResult( + QueueBatchAddStatus.NOTHING_TO_ADD, + _batch_add_message(0, final_plan), + plan=final_plan, + ) + store = store_factory(Path(jobs_path)) + job: AcquisitionJob = store.create(planned.item for planned in eligible) + except PermissionError: + return QueueBatchAddResult(QueueBatchAddStatus.SAVE_FAILED, "Unable to save Downloads: permission denied.", plan=plan) + except (JobStoreError, OSError) as exc: + return QueueBatchAddResult(QueueBatchAddStatus.SAVE_FAILED, f"Unable to save Downloads: {exc}", plan=plan) + + references = tuple(f"{job.job_id}:{index}" for index in range(len(eligible))) + added_ids = tuple(planned.song_id for planned in eligible) + return QueueBatchAddResult( + QueueBatchAddStatus.ADDED, + _batch_add_message(len(eligible), final_plan), + plan=final_plan, + added_count=len(eligible), + queue_references=references, + added_song_ids=added_ids, + ) + + +def _parse_queue_reference(reference: str) -> tuple[str, int] | None: + job_id, separator, index_text = str(reference).rpartition(":") + if not separator or not job_id or not index_text.isdigit(): + return None + return job_id, int(index_text) + + +def _mutation_error(exc: Exception) -> QueueMutationResult: + return QueueMutationResult(QueueMutationStatus.STORE_FAILED, f"Unable to update the download queue: {exc}") + + +def remove_queue_item( + reference: str, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + store_factory: StoreFactory = JobStore, +) -> QueueMutationResult: + parsed = _parse_queue_reference(reference) + if parsed is None: + return QueueMutationResult(QueueMutationStatus.NOT_FOUND, "This queued song no longer exists.") + job_id, index = parsed + with _EXECUTION_CLAIM_LOCK: + if reference in _ACTIVE_EXECUTIONS: + return QueueMutationResult(QueueMutationStatus.ACTIVE, "This song is currently being processed and cannot be removed.") + try: + store = store_factory(Path(jobs_path)); job = store.get(job_id) + if job is None or index < 0 or index >= len(job.items): + return QueueMutationResult(QueueMutationStatus.NOT_FOUND, "This queued song no longer exists.") + entry = job.items[index] + if entry.state in {AcquisitionState.CHECKING_EXISTING, AcquisitionState.DOWNLOADING, AcquisitionState.DOWNLOADED, AcquisitionState.VALIDATING, AcquisitionState.IMPORTED}: + return QueueMutationResult(QueueMutationStatus.ACTIVE, "This song is currently being processed and cannot be removed.") + if entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + return QueueMutationResult(QueueMutationStatus.NOT_ELIGIBLE, "Completed songs are managed as history.") + title = entry.item.title + job.items.pop(index) + if job.items: + store.save(job) + else: + store.delete(job_id) + return QueueMutationResult(QueueMutationStatus.COMPLETED, f"Removed {title} from the download queue.", removed_count=1) + except PermissionError: + return QueueMutationResult(QueueMutationStatus.STORE_FAILED, "Unable to update the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + return _mutation_error(exc) + + +def clear_download_queue(*, jobs_path: Path = DEFAULT_JOBS_FILE, store_factory: StoreFactory = JobStore) -> QueueMutationResult: + removed = retained = 0 + with _EXECUTION_CLAIM_LOCK: + try: + store = store_factory(Path(jobs_path)) + for job in list(store.list()): + kept = [] + for index, entry in enumerate(job.items): + ref = f"{job.job_id}:{index}" + if entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + kept.append(entry); continue + if entry.state in {AcquisitionState.CHECKING_EXISTING, AcquisitionState.DOWNLOADING, AcquisitionState.DOWNLOADED, AcquisitionState.VALIDATING, AcquisitionState.IMPORTED} or ref in _ACTIVE_EXECUTIONS: + kept.append(entry); retained += 1 + else: + removed += 1 + if len(kept) != len(job.items): + if kept: + job.items = kept; store.save(job) + else: + store.delete(job.job_id) + message = f"Cleared {removed} waiting or failed song(s)." + if retained: message += f" Retained {retained} active song(s)." + return QueueMutationResult(QueueMutationStatus.COMPLETED, message, removed_count=removed, retained_active_count=retained) + except PermissionError: + return QueueMutationResult(QueueMutationStatus.STORE_FAILED, "Unable to update the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + return _mutation_error(exc) + + +def clear_completed_history(*, jobs_path: Path = DEFAULT_JOBS_FILE, store_factory: StoreFactory = JobStore) -> QueueMutationResult: + removed = 0 + with _EXECUTION_CLAIM_LOCK: + try: + store = store_factory(Path(jobs_path)) + for job in list(store.list()): + kept = [entry for entry in job.items if entry.state not in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}] + removed += len(job.items) - len(kept) + if len(kept) != len(job.items): + if kept: + job.items = kept; store.save(job) + else: + store.delete(job.job_id) + return QueueMutationResult(QueueMutationStatus.COMPLETED, f"Cleared {removed} completed history entr{'y' if removed == 1 else 'ies'}.", removed_count=removed) + except PermissionError: + return QueueMutationResult(QueueMutationStatus.STORE_FAILED, "Unable to update the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + return _mutation_error(exc) + + +def _execution_failure( + status: DownloadExecutionStatus, + message: str, +) -> DownloadExecutionResult: + return DownloadExecutionResult(status, message) + + +def plan_download_execution( + settings: Settings, + reference: str, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + store_factory: StoreFactory = JobStore, +) -> DownloadExecutionResult: + """Resolve one frontend queue reference and validate download eligibility.""" + + parsed = _parse_queue_reference(reference) + if parsed is None: + return _execution_failure(DownloadExecutionStatus.NOT_FOUND, "This queue item no longer exists.") + job_id, item_index = parsed + try: + job = store_factory(Path(jobs_path)).get(job_id) + except PermissionError: + return _execution_failure(DownloadExecutionStatus.STORE_FAILED, "Unable to read the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + return _execution_failure(DownloadExecutionStatus.STORE_FAILED, f"Unable to read the download queue: {exc}") + if job is None or item_index < 0 or item_index >= len(job.items): + return _execution_failure(DownloadExecutionStatus.NOT_FOUND, "This queue item no longer exists.") + entry = job.items[item_index] + if entry.state is AcquisitionState.FAILED: + return _execution_failure( + DownloadExecutionStatus.RETRY_REQUIRED, + "This download failed previously. Retry will be available in a future action.", + ) + if entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + return _execution_failure(DownloadExecutionStatus.NOT_ELIGIBLE, "This song is already completed.") + if entry.state in { + AcquisitionState.CHECKING_EXISTING, + AcquisitionState.DOWNLOADING, + AcquisitionState.DOWNLOADED, + AcquisitionState.VALIDATING, + AcquisitionState.IMPORTED, + }: + return _execution_failure(DownloadExecutionStatus.ALREADY_RUNNING, "This song is already downloading or processing.") + item = entry.item + if not item.destination.name: + return _execution_failure(DownloadExecutionStatus.NOT_ELIGIBLE, "This queue item has no valid destination.") + if not item.url or not item.identifier: + return _execution_failure(DownloadExecutionStatus.NOT_ELIGIBLE, "This queue item has no valid downloadable resource.") + partial = item.destination.with_name(item.destination.name + ".part") + action = DownloadExecutionAction.RESUME if partial.is_file() else DownloadExecutionAction.START + return DownloadExecutionResult( + DownloadExecutionStatus.READY, + "Ready to resume download." if action is DownloadExecutionAction.RESUME else "Ready to start download.", + plan=DownloadExecutionPlan( + reference=reference, + job_id=job_id, + item_index=item_index, + song_id=item.identifier, + title=item.title, + artist=item.metadata.get("artist"), + destination=item.destination, + current_status=DownloadQueueItemStatus.QUEUED, + action=action, + ), + ) + + +def plan_download_all( + settings: Settings, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + store_factory: StoreFactory = JobStore, +) -> DownloadAllPlan | DownloadAllResult: + """Plan eligible queued songs from the authoritative persistent queue.""" + try: + snapshot = get_queue_snapshot(jobs_path) + except (JobStoreError, OSError) as exc: + return DownloadAllResult(DownloadBatchStatus.STORE_FAILED, f"Unable to read the download queue: {exc}") + eligible: list[DownloadExecutionPlan] = [] + failed = active = completed = skipped = 0 + for job in snapshot.jobs: + for index, item in enumerate(job.items): + status = _status(item.status) + reference = f"{job.job_id}:{index}" + if status in {DownloadQueueItemStatus.COMPLETED}: completed += 1; continue + if status is DownloadQueueItemStatus.FAILED: failed += 1; continue + if status in {DownloadQueueItemStatus.DOWNLOADING, DownloadQueueItemStatus.PROCESSING}: active += 1; continue + if item.destination is None or not item.identifier: + skipped += 1; continue + if reference in _ACTIVE_EXECUTIONS: + active += 1; continue + metadata = dict(item.metadata) + eligible.append(DownloadExecutionPlan(reference, job.job_id, index, item.identifier, item.title or "Unknown song", metadata.get("artist"), item.destination, DownloadQueueItemStatus.QUEUED, DownloadExecutionAction.RESUME if item.destination.with_name(item.destination.name + ".part").is_file() else DownloadExecutionAction.START)) + return DownloadAllPlan(tuple(eligible), failed, active, completed, skipped) + + +def execute_download_all( + settings: Settings, + plan: DownloadAllPlan, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + runner: Runner = run_job, + integration: Integration = integrate_downloaded_mp3, + song_fetcher: SongFetcher = get_song, + lyrics_dir: Path | None = None, + progress: Callable[[DownloadBatchProgress], None] | None = None, +) -> DownloadAllResult: + results: list[DownloadBatchItemResult] = [] + completed = failed = skipped = 0 + for position, execution_plan in enumerate(plan.eligible, 1): + if progress: + progress(DownloadBatchProgress(position - 1, len(plan.eligible), execution_plan.reference, execution_plan.title, DownloadExecutionStatus.READY)) + current = plan_download_execution(settings, execution_plan.reference, jobs_path=jobs_path) + if current.plan is None: + skipped += 1 + results.append(DownloadBatchItemResult(execution_plan.reference, execution_plan.title, DownloadBatchStatus.FAILED, current.message)) + continue + result = execute_selected_download(settings, current.plan, jobs_path=jobs_path, runner=runner, integration=integration, song_fetcher=song_fetcher, progress=(lambda update, pos=position: progress(DownloadBatchProgress(pos, len(plan.eligible), execution_plan.reference, execution_plan.title, update.status)) if progress else None)) + if result.status is DownloadExecutionStatus.COMPLETED: + completed += 1; batch_status = DownloadBatchStatus.COMPLETED + else: + failed += 1; batch_status = DownloadBatchStatus.FAILED + results.append(DownloadBatchItemResult(execution_plan.reference, execution_plan.title, batch_status, result.message)) + return DownloadAllResult(DownloadBatchStatus.COMPLETED if failed == 0 else DownloadBatchStatus.FAILED, f"Download all finished · {completed} completed · {failed} failed · {skipped} skipped", completed, failed, skipped, tuple(results)) + + +def _verified_retry_file(entry: Any) -> bool: + destination = entry.item.destination + if not destination.is_file() or entry.retry_file_size is None or not entry.retry_file_sha256: + return False + try: + digest = hashlib.sha256(destination.read_bytes()).hexdigest() + return destination.stat().st_size == entry.retry_file_size and digest == entry.retry_file_sha256.lower() + except OSError: + return False + + +def plan_download_retry( + settings: Settings, + reference: str, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + store_factory: StoreFactory = JobStore, +) -> DownloadRetryResult: + parsed = _parse_queue_reference(reference) + if parsed is None: + return DownloadRetryResult(DownloadRetryStatus.NOT_FOUND, "This queue item no longer exists.") + job_id, item_index = parsed + try: + job = store_factory(Path(jobs_path)).get(job_id) + except PermissionError: + return DownloadRetryResult(DownloadRetryStatus.STORE_FAILED, "Unable to read the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + return DownloadRetryResult(DownloadRetryStatus.STORE_FAILED, f"Unable to read the download queue: {exc}") + if job is None or item_index < 0 or item_index >= len(job.items): + return DownloadRetryResult(DownloadRetryStatus.NOT_FOUND, "This queue item no longer exists.") + entry = job.items[item_index] + if entry.state is not AcquisitionState.FAILED: + if entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + return DownloadRetryResult(DownloadRetryStatus.NOT_ELIGIBLE, "This song is already completed.") + return DownloadRetryResult(DownloadRetryStatus.ALREADY_RUNNING, "This song is already downloading or processing.") + if not entry.item.url or not entry.item.identifier or not entry.item.destination.name: + return DownloadRetryResult(DownloadRetryStatus.NOT_ELIGIBLE, "This song cannot be retried because its download resource is incomplete.") + if entry.failure_stage is not None and entry.failure_stage.is_post_processing and _verified_retry_file(entry): + action = DownloadRetryAction.PROCESS_ONLY + elif entry.item.destination.with_name(entry.item.destination.name + ".part").is_file(): + action = DownloadRetryAction.RESUME_DOWNLOAD + else: + action = DownloadRetryAction.DOWNLOAD_AGAIN + return DownloadRetryResult( + DownloadRetryStatus.READY, + "Ready to retry processing only." if action is DownloadRetryAction.PROCESS_ONLY else ("Ready to resume download." if action is DownloadRetryAction.RESUME_DOWNLOAD else "Ready to download again."), + plan=DownloadRetryPlan(reference, job_id, item_index, entry.item.identifier, entry.item.title, entry.item.destination, entry.error or "Previous attempt failed.", action), + ) + + +def execute_selected_download( + settings: Settings, + plan: DownloadExecutionPlan, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + store_factory: StoreFactory = JobStore, + runner: Runner = run_job, + integration: Integration = integrate_downloaded_mp3, + song_fetcher: SongFetcher = get_song, + lyrics_dir: Path | None = None, + progress: ExecutionProgressCallback | None = None, + _allow_failed: bool = False, +) -> DownloadExecutionResult: + """Execute exactly one confirmed queue item through the existing runner.""" + + try: + store = store_factory(Path(jobs_path)) + # Claim the exact persisted item before starting the long-running worker. + # This closes the same-process double-submit race without changing the + # durable job schema or runner semantics. + with _EXECUTION_CLAIM_LOCK: + if plan.reference in _ACTIVE_EXECUTIONS: + return _execution_failure(DownloadExecutionStatus.ALREADY_RUNNING, "This song is already downloading or processing.") + job = store.get(plan.job_id) + if job is None or plan.item_index < 0 or plan.item_index >= len(job.items): + return _execution_failure(DownloadExecutionStatus.NOT_FOUND, "This queue item no longer exists.") + entry = job.items[plan.item_index] + if ( + entry.item.identifier != plan.song_id + or entry.item.destination != plan.destination + ): + return _execution_failure(DownloadExecutionStatus.NOT_FOUND, "The selected queue item changed before download could start.") + if entry.state is AcquisitionState.FAILED and not _allow_failed: + return _execution_failure(DownloadExecutionStatus.RETRY_REQUIRED, "This failed song requires the future Retry action.") + if entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + return _execution_failure(DownloadExecutionStatus.NOT_ELIGIBLE, "This song is already completed.") + if entry.state not in {AcquisitionState.PENDING, AcquisitionState.RESOLVED}: + return _execution_failure(DownloadExecutionStatus.ALREADY_RUNNING, "This song is already downloading or processing.") + if not entry.item.destination.name: + return _execution_failure(DownloadExecutionStatus.NOT_ELIGIBLE, "This queue item has no valid destination.") + + entry.state = AcquisitionState.CHECKING_EXISTING + entry.error = None + entry.failure_stage = None + job.touch() + store.save(job) + _ACTIVE_EXECUTIONS.add(plan.reference) + if progress: + progress(DownloadProgress(plan.reference, DownloadExecutionStatus.DOWNLOADING, message="Downloading…")) + + def report(_index: int, _total: int, written: int, remote_total: int | None) -> None: + if progress: + progress(DownloadProgress( + plan.reference, + DownloadExecutionStatus.DOWNLOADING, + written, + remote_total, + "Downloading…", + )) + + def postprocess(result: AcquisitionResult) -> IntegrationResult: + if progress: + progress(DownloadProgress( + plan.reference, + DownloadExecutionStatus.PROCESSING, + entry.bytes_written, + entry.item.expected_size, + "Processing lyrics and library metadata…", + )) + return integration( + entry.item, + song_fetcher=lambda song_id: song_fetcher(settings, song_id), + settings=settings, + ) + + runner( + job, + store, + policy=DownloadPolicy(), + progress=report, + postprocess=postprocess, + item_indexes={plan.item_index}, + ) + authoritative = store.get(plan.job_id) + except PermissionError: + with _EXECUTION_CLAIM_LOCK: _ACTIVE_EXECUTIONS.discard(plan.reference) + return _execution_failure(DownloadExecutionStatus.STORE_FAILED, "Unable to update the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + with _EXECUTION_CLAIM_LOCK: _ACTIVE_EXECUTIONS.discard(plan.reference) + return _execution_failure(DownloadExecutionStatus.STORE_FAILED, f"Unable to update the download queue: {exc}") + except Exception as exc: + with _EXECUTION_CLAIM_LOCK: _ACTIVE_EXECUTIONS.discard(plan.reference) + error = str(exc) or type(exc).__name__ + try: + interrupted = store.get(plan.job_id) + if interrupted is not None and plan.item_index < len(interrupted.items): + failed_entry = interrupted.items[plan.item_index] + if failed_entry.state not in { + AcquisitionState.COMPLETE, + AcquisitionState.SKIPPED, + AcquisitionState.FAILED, + }: + failed_entry.state = AcquisitionState.FAILED + failed_entry.error = error + failed_entry.failure_stage = AcquisitionFailureStage.TRANSPORT + interrupted.touch() + store.save(interrupted) + except Exception: + pass + return DownloadExecutionResult( + DownloadExecutionStatus.FAILED, + "Download execution failed safely.", + plan=plan, + error=error, + ) + + try: + if authoritative is None or plan.item_index >= len(authoritative.items): + return _execution_failure(DownloadExecutionStatus.NOT_FOUND, "The queue record disappeared after execution.") + final_entry = authoritative.items[plan.item_index] + if final_entry.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + message = (f"{plan.title} was already present and left the active queue." if final_entry.state is AcquisitionState.SKIPPED else f"{plan.title} finished downloading.") + return DownloadExecutionResult(DownloadExecutionStatus.COMPLETED, message, plan=plan) + stage = { + AcquisitionFailureStage.TRANSPORT: "Download failed", + AcquisitionFailureStage.VALIDATION: "File validation failed", + AcquisitionFailureStage.LYRICS: "Lyrics processing failed", + AcquisitionFailureStage.LRC: "LRC creation failed", + AcquisitionFailureStage.STATE: "Library update failed", + None: "Download failed", + }[final_entry.failure_stage] + return DownloadExecutionResult(DownloadExecutionStatus.FAILED, stage, plan=plan, failure_stage=stage, error=final_entry.error or "The selected download did not complete.") + finally: + with _EXECUTION_CLAIM_LOCK: + _ACTIVE_EXECUTIONS.discard(plan.reference) + + +def execute_selected_retry( + settings: Settings, + plan: DownloadRetryPlan, + *, + jobs_path: Path = DEFAULT_JOBS_FILE, + store_factory: StoreFactory = JobStore, + runner: Runner = run_job, + integration: Integration = integrate_downloaded_mp3, + song_fetcher: SongFetcher = get_song, + lyrics_dir: Path | None = None, + progress: ExecutionProgressCallback | None = None, +) -> DownloadRetryResult: + with _EXECUTION_CLAIM_LOCK: + if plan.reference in _ACTIVE_EXECUTIONS: + return DownloadRetryResult(DownloadRetryStatus.ALREADY_RUNNING, "This song is already downloading or processing.", plan=plan) + try: + store = store_factory(Path(jobs_path)); job = store.get(plan.job_id) + except PermissionError: + return DownloadRetryResult(DownloadRetryStatus.STORE_FAILED, "Unable to update the download queue: permission denied.", plan=plan) + except (JobStoreError, OSError) as exc: + return DownloadRetryResult(DownloadRetryStatus.STORE_FAILED, f"Unable to update the download queue: {exc}", plan=plan) + if job is None or plan.item_index >= len(job.items): + return DownloadRetryResult(DownloadRetryStatus.NOT_FOUND, "This queue item no longer exists.", plan=plan) + entry = job.items[plan.item_index] + if entry.item.identifier != plan.song_id or entry.item.destination != plan.destination: + return DownloadRetryResult(DownloadRetryStatus.NOT_FOUND, "The selected queue item changed before retry could start.", plan=plan) + if entry.state is not AcquisitionState.FAILED: + return DownloadRetryResult(DownloadRetryStatus.ALREADY_RUNNING, "This song is no longer failed and cannot be retried here.", plan=plan) + _ACTIVE_EXECUTIONS.add(plan.reference) + try: + def report(index: int, total: int, written: int, remote_total: int | None) -> None: + if progress: + progress(DownloadProgress(plan.reference, DownloadExecutionStatus.DOWNLOADING, written, remote_total, "Downloading…")) + def postprocess(result: AcquisitionResult) -> IntegrationResult: + if progress: + progress(DownloadProgress(plan.reference, DownloadExecutionStatus.PROCESSING, result.bytes_written, entry.item.expected_size, "Processing lyrics and library metadata…")) + return integration( + entry.item, + song_fetcher=lambda song_id: song_fetcher(settings, song_id), + settings=settings, + ) + runner(job, store, policy=DownloadPolicy(), progress=report, postprocess=postprocess, item_indexes={plan.item_index}) + authoritative = store.get(plan.job_id) + final = authoritative.items[plan.item_index] if authoritative is not None and plan.item_index < len(authoritative.items) else None + if final is not None and final.state in {AcquisitionState.COMPLETE, AcquisitionState.SKIPPED}: + return DownloadRetryResult(DownloadRetryStatus.COMPLETED, f"{plan.title} finished successfully.", plan=plan) + error = final.error if final is not None else "The queue record disappeared after retry." + return DownloadRetryResult(DownloadRetryStatus.FAILED, "Retry failed", plan=plan, error=error) + except Exception as exc: + return DownloadRetryResult(DownloadRetryStatus.FAILED, "Retry failed", plan=plan, error=str(exc) or type(exc).__name__) + finally: + with _EXECUTION_CLAIM_LOCK: _ACTIVE_EXECUTIONS.discard(plan.reference) diff --git a/src/juice_lyrics/services/identity_rebuild.py b/src/juice_lyrics/services/identity_rebuild.py new file mode 100644 index 0000000..c072e1d --- /dev/null +++ b/src/juice_lyrics/services/identity_rebuild.py @@ -0,0 +1,302 @@ +from __future__ import annotations + +import hashlib +import shutil +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from ..api.client import search_song_names +from ..config.settings import STATE_FILE, Settings +from ..library.matching import choose_candidate, search_title_for +from ..state import read_state_file, resolve_state_entry, write_state_file +from .library_status import LibrarySnapshot, LibraryTrack, get_library_snapshot +from .library_status import LibraryStateStatus +from .manual_identity import ( + IDENTITY_LOCK_FIELD, + IDENTITY_SOURCE_FIELD, + is_identity_locked, +) +from .state_maintenance import plan_stale_state_cleanup + + +IDENTITY_FIELDS = ("song_id", "api_name", IDENTITY_SOURCE_FIELD, IDENTITY_LOCK_FIELD) + + +def _valid_track_lock(entry: Mapping[str, Any] | None, track: LibraryTrack) -> bool: + return bool( + is_identity_locked(entry) + and track.state_status is LibraryStateStatus.CURRENT + and track.content_sha256 + and entry.get("sha256") == track.content_sha256 + ) + + +@dataclass(frozen=True, slots=True) +class IdentityRebuildPlan: + settings: Settings + state_file: Path + source_digest: str + state: dict[str, Any] + tracks: tuple[LibraryTrack, ...] + stale_keys: tuple[str, ...] + existing_identities: int + + @property + def current_tracks(self) -> int: + return len(self.tracks) + + @property + def currently_unknown(self) -> int: + return self.current_tracks - self.existing_identities + + @property + def locked_identities(self) -> int: + files = self.state.get("files", {}) + state_files = files if isinstance(files, Mapping) else {} + relative_paths = tuple(track.relative_path for track in self.tracks) + return sum( + _valid_track_lock( + resolve_state_entry(state_files, track.relative_path, relative_paths)[1], + track, + ) + for track in self.tracks + ) + + +@dataclass(frozen=True, slots=True) +class IdentityChange: + path: Path + old_song_id: Any + old_api_name: str | None + new_song_id: Any + new_api_name: str | None + + +@dataclass(frozen=True, slots=True) +class IdentityRebuildProgress: + completed: int + total: int + path: Path + status: str + + +@dataclass(frozen=True, slots=True) +class IdentityRebuildResult: + inspected: int + matched: int + unknown: int + changed_identities: int + unchanged_identities: int + failed_preserved: int + stale_ignored: int + changes: tuple[IdentityChange, ...] + errors: tuple[str, ...] + backup_path: Path | None + aborted: bool = False + abort_reason: str | None = None + + +@dataclass(slots=True) +class IdentityRebuildDependencies: + state_reader: Callable[[Path], dict[str, Any]] = read_state_file + state_writer: Callable[[Path, Mapping[str, Any]], None] = write_state_file + searcher: Callable[..., list[dict[str, Any]]] = search_song_names + matcher: Callable[..., Any] = choose_candidate + search_title: Callable[[Path], str] = search_title_for + copier: Callable[[Path, Path], Any] = shutil.copy2 + + +def _source_bytes(path: Path) -> bytes: + return path.read_bytes() if path.exists() else b"" + + +def _digest(path: Path) -> str: + return hashlib.sha256(_source_bytes(path)).hexdigest() + + +def _identity(entry: Mapping[str, Any] | None) -> tuple[Any, str | None]: + if not isinstance(entry, Mapping): + return None, None + name = str(entry.get("api_name") or "").strip() or None + return entry.get("song_id"), name + + +def _has_identity(entry: Mapping[str, Any] | None) -> bool: + song_id, name = _identity(entry) + return song_id is not None and name is not None + + +def plan_catalogue_identity_rebuild( + settings: Settings, + *, + state_file: Path = STATE_FILE, + snapshot_provider: Callable[..., LibrarySnapshot] = get_library_snapshot, +) -> IdentityRebuildPlan: + """Create a read-only rebuild preview for the current local library.""" + + state_path = Path(state_file) + maintenance = plan_stale_state_cleanup(settings, state_file=state_path) + snapshot = snapshot_provider(settings, state_file=state_path) + state = maintenance.state + files = state.get("files", {}) + state_files = files if isinstance(files, Mapping) else {} + relative_paths = tuple(track.relative_path for track in snapshot.tracks) + existing = sum( + _has_identity(resolve_state_entry(state_files, track.relative_path, relative_paths)[1]) + for track in snapshot.tracks + ) + return IdentityRebuildPlan( + settings=settings, + state_file=state_path, + source_digest=maintenance.source_digest, + state=state, + tracks=snapshot.tracks, + stale_keys=maintenance.stale_keys, + existing_identities=existing, + ) + + +def _validate_candidate_state(state: Mapping[str, Any], tracks: Sequence[LibraryTrack]) -> None: + files = state.get("files") + if not isinstance(files, Mapping): + raise RuntimeError("Rebuilt state has an invalid files collection.") + relative_paths = tuple(track.relative_path for track in tracks) + for track in tracks: + _, entry = resolve_state_entry(files, track.relative_path, relative_paths) + if entry is None: + continue + song_id, api_name = _identity(entry) + if (song_id is None) != (api_name is None): + raise RuntimeError(f"Rebuilt identity is incomplete for {track.relative_path}.") + + +def execute_catalogue_identity_rebuild( + plan: IdentityRebuildPlan, + *, + refresh: bool = False, + dependencies: IdentityRebuildDependencies | None = None, + progress: Callable[[IdentityRebuildProgress], None] | None = None, + include_locked: bool = False, +) -> IdentityRebuildResult: + """Re-match current tracks and atomically replace identity fields only.""" + + dependencies = dependencies or IdentityRebuildDependencies() + if _digest(plan.state_file) != plan.source_digest: + raise RuntimeError("State changed after the rebuild preview; run the preview again.") + + original_files = plan.state.get("files", {}) + source_files = original_files if isinstance(original_files, Mapping) else {} + rebuilt_files = dict(source_files) + rebuilt_state = dict(plan.state) + relative_paths = tuple(track.relative_path for track in plan.tracks) + changes: list[IdentityChange] = [] + errors: list[str] = [] + successful_queries = failures = 0 + + for completed, track in enumerate(plan.tracks, start=1): + _, resolved = resolve_state_entry(source_files, track.relative_path, relative_paths) + old_song_id, old_api_name = _identity(resolved) + reference = str(track.relative_path) + exact = source_files.get(reference) + had_entry = isinstance(exact, Mapping) or isinstance(resolved, Mapping) + base = dict(exact) if isinstance(exact, Mapping) else dict(resolved or {}) + if _valid_track_lock(resolved, track) and not include_locked: + if progress is not None: + progress( + IdentityRebuildProgress( + completed, len(plan.tracks), track.path, "manual match preserved" + ) + ) + continue + try: + query = dependencies.search_title(track.path) + results = dependencies.searcher(plan.settings, query, refresh=refresh) + successful_queries += 1 + candidate, _, _, _ = dependencies.matcher( + plan.settings, track.path, results, query + ) + for field in IDENTITY_FIELDS: + base.pop(field, None) + if isinstance(candidate, Mapping): + song_id = candidate.get("id") + api_name = str(candidate.get("name") or "").strip() or None + if song_id is not None and api_name is not None: + base["song_id"] = song_id + base["api_name"] = api_name + new_song_id, new_api_name = _identity(base) + if had_entry or base: + rebuilt_files[reference] = base + if (old_song_id, old_api_name) != (new_song_id, new_api_name): + changes.append( + IdentityChange( + track.relative_path, + old_song_id, + old_api_name, + new_song_id, + new_api_name, + ) + ) + status = "matched" if new_song_id is not None else "unknown" + except Exception as exc: + failures += 1 + errors.append(f"{track.filename}: {str(exc) or type(exc).__name__}") + status = "preserved after failure" + if progress is not None: + progress(IdentityRebuildProgress(completed, len(plan.tracks), track.path, status)) + + if failures and successful_queries == 0: + return IdentityRebuildResult( + inspected=len(plan.tracks), + matched=plan.existing_identities, + unknown=plan.currently_unknown, + changed_identities=0, + unchanged_identities=len(plan.tracks), + failed_preserved=failures, + stale_ignored=len(plan.stale_keys), + changes=(), + errors=tuple(errors), + backup_path=None, + aborted=True, + abort_reason="Catalogue provider was unavailable; original identities were preserved.", + ) + + rebuilt_state["files"] = rebuilt_files + _validate_candidate_state(rebuilt_state, plan.tracks) + if _digest(plan.state_file) != plan.source_digest: + raise RuntimeError("State changed during the rebuild; no changes were written.") + + matched = unknown = 0 + for track in plan.tracks: + _, entry = resolve_state_entry(rebuilt_files, track.relative_path, relative_paths) + if _has_identity(entry): + matched += 1 + else: + unknown += 1 + changed = len(changes) + unchanged = len(plan.tracks) - changed + + backup: Path | None = None + if rebuilt_state != plan.state: + if plan.state_file.exists(): + stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f") + backup = plan.state_file.with_name( + f"{plan.state_file.name}.pre-identity-rebuild-{stamp}.bak" + ) + dependencies.copier(plan.state_file, backup) + dependencies.state_writer(plan.state_file, rebuilt_state) + + return IdentityRebuildResult( + inspected=len(plan.tracks), + matched=matched, + unknown=unknown, + changed_identities=changed, + unchanged_identities=unchanged, + failed_preserved=failures, + stale_ignored=len(plan.stale_keys), + changes=tuple(changes), + errors=tuple(errors), + backup_path=backup, + ) diff --git a/src/juice_lyrics/services/library_duplicates.py b/src/juice_lyrics/services/library_duplicates.py new file mode 100644 index 0000000..4f16633 --- /dev/null +++ b/src/juice_lyrics/services/library_duplicates.py @@ -0,0 +1,205 @@ +"""Read-only duplicate evidence derived from an existing Library snapshot.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +import re + +from ..config.settings import DEFAULT_DURATION_TOLERANCE +from ..library.matching import ( + named_variants, + normalize, + normalize_words, + parse_version, + strip_feature_credit, + strip_version, +) +from .library_status import LibrarySnapshot, LibraryTrack + + +class DuplicateConfidence(str, Enum): + EXACT = "exact" + PROBABLE = "probable" + + +@dataclass(frozen=True, slots=True) +class DuplicateGroup: + confidence: DuplicateConfidence + tracks: tuple[LibraryTrack, ...] + evidence: tuple[str, ...] + + @property + def title(self) -> str: + return self.tracks[0].title + + +@dataclass(frozen=True, slots=True) +class DuplicateReport: + snapshot: LibrarySnapshot + groups: tuple[DuplicateGroup, ...] + + @property + def file_count(self) -> int: + return len({track.reference for group in self.groups for track in group.tracks}) + + +_EXTRA_VARIANTS = { + "alternate": r"\b(?:alternate|alt)\b", + "extended": r"\bextended\b", + "mix": r"\bmix\b", + "remaster": r"\bremaster(?:ed)?\b", + "session": r"\b(?:recording\s+session|studio\s+session|session)\b", +} + + +def _variant_signature(track: LibraryTrack) -> tuple[int | None, frozenset[str]]: + variants = set(named_variants(track.title)) + variants.update( + label + for label, pattern in _EXTRA_VARIANTS.items() + if re.search(pattern, track.title, re.I) + ) + return parse_version(track.title), frozenset(variants) + + +def _base_title(track: LibraryTrack) -> str: + return normalize(strip_version(strip_feature_credit(track.title))) + + +def _artist_key(value: str | None) -> tuple[str, ...]: + if not value: + return () + parts = re.split( + r"\s*(?:,|&|\bx\b|\bfeat(?:uring)?\.?\b|\bft\.?\b|\bwith\b)\s*", + value, + flags=re.I, + ) + return tuple(sorted(part for raw in parts if (part := normalize_words(raw)))) + + +def _duration_compatible( + left: LibraryTrack, + right: LibraryTrack, + tolerance: float, +) -> bool: + if left.duration_seconds is None or right.duration_seconds is None: + return False + return abs(left.duration_seconds - right.duration_seconds) <= tolerance + + +def _probable_pair( + left: LibraryTrack, + right: LibraryTrack, + tolerance: float, +) -> bool: + if _variant_signature(left) != _variant_signature(right): + return False + left_id, right_id = left.catalogue_id, right.catalogue_id + if left_id is not None and right_id is not None: + return ( + str(left_id) == str(right_id) + and ( + _duration_compatible(left, right, tolerance) + or left.duration_seconds is None + or right.duration_seconds is None + ) + ) + return bool( + _base_title(left) + and _base_title(left) == _base_title(right) + and _artist_key(left.artist) + and _artist_key(left.artist) == _artist_key(right.artist) + and _duration_compatible(left, right, tolerance) + ) + + +def _related(left: LibraryTrack, right: LibraryTrack, tolerance: float) -> bool: + return bool( + left.content_sha256 + and left.content_sha256 == right.content_sha256 + ) or _probable_pair(left, right, tolerance) + + +def _groups( + tracks: tuple[LibraryTrack, ...], + tolerance: float, +) -> tuple[tuple[LibraryTrack, ...], ...]: + grouped: list[list[LibraryTrack]] = [] + for track in sorted(tracks, key=lambda item: item.reference.casefold()): + compatible = next( + ( + group + for group in grouped + if all(_related(track, member, tolerance) for member in group) + ), + None, + ) + if compatible is None: + grouped.append([track]) + else: + compatible.append(track) + return tuple( + tuple(group) + for group in grouped + if len(group) > 1 + ) + + +def _group_evidence(tracks: tuple[LibraryTrack, ...], tolerance: float) -> tuple[str, ...]: + evidence: list[str] = [] + hashes = {track.content_sha256 for track in tracks if track.content_sha256} + if len(hashes) == 1 and all(track.content_sha256 for track in tracks): + evidence.append("Identical file bytes (same SHA-256)") + elif any( + left.content_sha256 + and left.content_sha256 == right.content_sha256 + for index, left in enumerate(tracks) + for right in tracks[index + 1 :] + ): + evidence.append("Some files have identical file bytes") + ids = {str(track.catalogue_id) for track in tracks if track.catalogue_id is not None} + if len(ids) == 1: + evidence.append(f"Same catalogue identity ({next(iter(ids))})") + base_title = _base_title(tracks[0]) + if base_title and all(_base_title(track) == base_title for track in tracks[1:]): + evidence.append("Compatible title and recording variant") + artist_key = _artist_key(tracks[0].artist) + if artist_key and all(_artist_key(track.artist) == artist_key for track in tracks[1:]): + evidence.append("Same artist metadata") + durations = [track.duration_seconds for track in tracks if track.duration_seconds is not None] + if len(durations) == len(tracks) and max(durations) - min(durations) <= tolerance: + evidence.append(f"Durations within {max(durations) - min(durations):.2f}s") + return tuple(evidence) + + +def detect_library_duplicates( + snapshot: LibrarySnapshot, + *, + duration_tolerance: float = DEFAULT_DURATION_TOLERANCE, +) -> DuplicateReport: + """Find conservative duplicate groups without reading files or calling APIs.""" + + groups: list[DuplicateGroup] = [] + for tracks in _groups(snapshot.tracks, max(0.0, duration_tolerance)): + hashes = {track.content_sha256 for track in tracks} + confidence = ( + DuplicateConfidence.EXACT + if None not in hashes and len(hashes) == 1 + else DuplicateConfidence.PROBABLE + ) + groups.append( + DuplicateGroup( + confidence, + tracks, + _group_evidence(tracks, max(0.0, duration_tolerance)), + ) + ) + groups.sort( + key=lambda group: ( + group.confidence is not DuplicateConfidence.EXACT, + group.title.casefold(), + group.tracks[0].reference.casefold(), + ) + ) + return DuplicateReport(snapshot, tuple(groups)) diff --git a/src/juice_lyrics/services/library_identity.py b/src/juice_lyrics/services/library_identity.py new file mode 100644 index 0000000..7e7d0c9 --- /dev/null +++ b/src/juice_lyrics/services/library_identity.py @@ -0,0 +1,175 @@ +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass +from pathlib import Path +import re +from typing import Any + +from ..api.client import search_song_names +from ..backup.manager import now_iso +from ..config.settings import STATE_FILE, Settings +from ..library.matching import choose_candidate, search_title_for +from ..state import file_fingerprint, read_state_file, resolve_state_entry, sha256_file, write_state_file +from .library_status import LibraryTrack +from .manual_identity import IDENTITY_LOCK_FIELD, IDENTITY_SOURCE_FIELD + + +@dataclass(frozen=True, slots=True) +class IdentityBackfillResult: + inspected: int + reused: int + identified: int + unknown: int + failed: int + errors: tuple[str, ...] = () + failed_paths: tuple[str, ...] = () + + @property + def changed(self) -> bool: + return self.identified > 0 + + +@dataclass(slots=True) +class IdentityBackfillDependencies: + state_reader: Callable[[Path], dict[str, Any]] = read_state_file + state_writer: Callable[[Path, Mapping[str, Any]], None] = write_state_file + searcher: Callable[..., list[dict[str, Any]]] = search_song_names + matcher: Callable[..., Any] = choose_candidate + search_title: Callable[[Path], str] = search_title_for + hasher: Callable[[Path], str] = sha256_file + + +def _has_identity(entry: Mapping[str, Any] | None) -> bool: + if not isinstance(entry, Mapping): + return False + name = str(entry.get("api_name") or "").strip() + return entry.get("song_id") is not None and bool(name) + + +def _state_bytes(path: Path) -> bytes | None: + try: + return path.read_bytes() + except FileNotFoundError: + return None + + +def _provider_unavailable(exc: Exception) -> bool: + """Recognize provider-wide failures that should trip the Sync circuit breaker.""" + + message = (str(exc) or type(exc).__name__).casefold() + http_status = re.search(r"api returned http\s+(\d{3})", message) + if http_status is not None and int(http_status.group(1)) >= 500: + return True + return any( + marker in message + for marker in ( + "could not reach the juice wrld api", + "cloudflare", + "tunnel failure", + "tunnel error", + "temporary failure in name resolution", + "the api returned invalid json", + ) + ) + + +def backfill_catalogue_identities( + settings: Settings, + tracks: Sequence[LibraryTrack], + *, + state_file: Path = STATE_FILE, + dependencies: IdentityBackfillDependencies | None = None, +) -> IdentityBackfillResult: + """Persist confident catalogue identities without changing any media files.""" + + dependencies = dependencies or IdentityBackfillDependencies() + state_path = Path(state_file) + original_state = _state_bytes(state_path) + state = dependencies.state_reader(state_path) + if _state_bytes(state_path) != original_state: + raise RuntimeError("Library state changed during catalogue identification; refresh again.") + files = state.setdefault("files", {}) + if not isinstance(files, dict): + files = {} + state["files"] = files + + relative_paths = tuple(track.relative_path for track in tracks) + reused = identified = unknown = failed = 0 + errors: list[str] = [] + failed_paths: list[str] = [] + + for index, track in enumerate(tracks): + _, existing = resolve_state_entry(files, track.relative_path, relative_paths) + try: + if ( + track.content_sha256 is not None + and track.content_fingerprint is not None + and file_fingerprint(track.path) == track.content_fingerprint + ): + audio_hash = track.content_sha256 + else: + audio_hash = dependencies.hasher(track.path) + if _has_identity(existing) and existing.get("sha256") == audio_hash: + reused += 1 + continue + query = dependencies.search_title(track.path) + results = dependencies.searcher(settings, query, refresh=False) + candidate, _, _, _ = dependencies.matcher(settings, track.path, results, query) + if not isinstance(candidate, Mapping): + unknown += 1 + continue + song_id = candidate.get("id") + api_name = str(candidate.get("name") or "").strip() + if song_id is None or not api_name: + unknown += 1 + continue + + if dependencies.hasher(track.path) != audio_hash: + raise RuntimeError("Audio changed during catalogue identification; refresh again.") + + reference = str(track.relative_path) + current = files.get(reference) + entry = dict(current) if isinstance(current, Mapping) else {} + # A match recalculated for different audio must not inherit a + # user lock that belonged to the previous file at this path. + entry.pop(IDENTITY_SOURCE_FIELD, None) + entry.pop(IDENTITY_LOCK_FIELD, None) + entry.update( + { + "sha256": audio_hash, + "song_id": song_id, + "api_name": api_name, + "updated": now_iso(), + } + ) + files[reference] = entry + identified += 1 + except Exception as exc: + failed += 1 + errors.append(f"{track.filename}: {str(exc) or type(exc).__name__}") + failed_paths.append(str(track.relative_path)) + if _provider_unavailable(exc): + remaining = tracks[index + 1 :] + failed += len(remaining) + failed_paths.extend(str(item.relative_path) for item in remaining) + if remaining: + errors.append( + f"Catalogue provider unavailable; skipped {len(remaining)} remaining " + f"track{'s' if len(remaining) != 1 else ''}." + ) + break + + if identified: + if _state_bytes(state_path) != original_state: + raise RuntimeError("Library state changed during catalogue identification; refresh again.") + dependencies.state_writer(state_path, state) + return IdentityBackfillResult( + inspected=len(tracks), + reused=reused, + identified=identified, + unknown=unknown, + failed=failed, + errors=tuple(errors), + failed_paths=tuple(failed_paths), + ) diff --git a/src/juice_lyrics/services/library_index_sync.py b/src/juice_lyrics/services/library_index_sync.py new file mode 100644 index 0000000..53d6216 --- /dev/null +++ b/src/juice_lyrics/services/library_index_sync.py @@ -0,0 +1,300 @@ +"""Routine, state-only Library Sync for local discovery and catalogue identity.""" + +from __future__ import annotations + +import copy +import hashlib +import json +from collections.abc import Callable, Mapping +from dataclasses import dataclass, replace +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from ..config.settings import STATE_FILE, Settings +from ..state import file_fingerprint, read_state_file, sha256_file, write_state_file +from .library_identity import ( + IdentityBackfillDependencies, + backfill_catalogue_identities, +) +from .manual_identity import IDENTITY_LOCK_FIELD, IDENTITY_SOURCE_FIELD +from .library_status import ( + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, + get_library_snapshot, + state_entry_signature, +) + + +@dataclass(frozen=True, slots=True) +class LibraryIndexSyncResult: + snapshot: LibrarySnapshot + new: int = 0 + changed: int = 0 + removed: int = 0 + identified: int = 0 + unknown: int = 0 + failed: int = 0 + error: str | None = None + + @property + def summary(self) -> str: + if self.error: + parts = ["Library scan complete", self.error] + if self.new: + parts.append(f"{self.new} new pending") + if self.changed: + parts.append(f"{self.changed} changed pending") + if self.unknown: + parts.append(f"{self.unknown} catalogue unknown") + return " · ".join(parts) + if not (self.new or self.changed or self.removed or self.identified or self.failed): + if self.unknown: + return f"Local library up to date · {self.unknown} catalogue unknown" + return "Local library is up to date" + parts = [f"Library synced · {self.snapshot.total_track_count} tracks"] + for count, label in ( + (self.new, "new recorded"), (self.changed, "changed refreshed"), + (self.removed, "removed"), (self.identified, "newly matched"), + (self.unknown, "catalogue unknown"), + (self.failed, "catalogue checks failed"), + ): + if count: + parts.append(f"{count} {label}") + return " · ".join(parts) + + +@dataclass(slots=True) +class LibraryIndexSyncDependencies: + snapshot_provider: Callable[..., LibrarySnapshot] = get_library_snapshot + identity: IdentityBackfillDependencies | None = None + state_reader: Callable[[Path], dict[str, Any]] = read_state_file + state_writer: Callable[[Path, Mapping[str, Any]], None] = write_state_file + hasher: Callable[[Path], str] = sha256_file + + +def _source_bytes(path: Path) -> bytes | None: + try: + return path.read_bytes() + except FileNotFoundError: + return None + + +def _current_hash(track: LibraryTrack, hasher: Callable[[Path], str]) -> str: + if ( + track.content_sha256 is not None + and track.content_fingerprint is not None + and file_fingerprint(track.path) == track.content_fingerprint + ): + return track.content_sha256 + return hasher(track.path) + + +def _unknown_check_due(entry: object, track: LibraryTrack, settings: Settings) -> bool: + if not isinstance(entry, dict) or entry.get("sha256") != track.content_sha256: + return True + checked = entry.get("catalogue_checked_at") + if not isinstance(checked, str): + return True + try: + when = datetime.fromisoformat(checked) + if when.tzinfo is None: + return True + age = (datetime.now(timezone.utc) - when).total_seconds() + except ValueError: + return True + return age < 0 or age >= settings.cache_ttl_hours * 3600 + + +def sync_library_index( + settings: Settings, + *, + previous_snapshot: LibrarySnapshot | None = None, + state_file: Path = STATE_FILE, + dependencies: LibraryIndexSyncDependencies | None = None, +) -> LibraryIndexSyncResult: + """Discover, identify, and retire only known active records; never edit media.""" + + deps = dependencies or LibraryIndexSyncDependencies() + state_path = Path(state_file) + original_bytes = _source_bytes(state_path) + if original_bytes is not None: + try: + raw_state = json.loads(original_bytes) + except (UnicodeError, ValueError) as exc: + raise RuntimeError("Library state is malformed; Sync will not overwrite it.") from exc + if not isinstance(raw_state, dict) or not isinstance(raw_state.get("files", {}), dict): + raise RuntimeError("Library state is malformed; Sync will not overwrite it.") + original = deps.state_reader(state_path) + if original_bytes is not None and ( + not isinstance(original, dict) or not isinstance(original.get("files", {}), dict) + ): + raise RuntimeError("Library state is malformed; Sync will not overwrite it.") + if _source_bytes(state_path) != original_bytes: + raise RuntimeError("Library state changed while Sync started; try again.") + + snapshot = deps.snapshot_provider( + settings, state_file=state_path, previous_snapshot=previous_snapshot + ) + if not snapshot.directory_exists: + return LibraryIndexSyncResult(snapshot, error="Music directory is unavailable") + current = {str(track.relative_path): track for track in snapshot.tracks} + prior = ( + {str(track.relative_path): track for track in previous_snapshot.tracks} + if previous_snapshot is not None and previous_snapshot.library_path == snapshot.library_path + else {} + ) + new = changed = 0 + for reference, track in current.items(): + earlier = prior.get(reference) + if earlier is None: + if track.state_status is LibraryStateStatus.NEW: + new += 1 + elif track.state_status is LibraryStateStatus.CHANGED: + changed += 1 + elif earlier.content_fingerprint != track.content_fingerprint: + changed += 1 + + managed_paths = original.get("library_sync_paths", ()) + previously_active = { + reference for reference in (managed_paths if isinstance(managed_paths, list) else ()) + if isinstance(reference, str) + and reference + and not Path(reference).is_absolute() + and ".." not in Path(reference).parts + } + previously_active.update(prior) + removed_paths = previously_active - current.keys() + candidate_state = copy.deepcopy(original) + files = candidate_state.setdefault("files", {}) + if not isinstance(files, dict): + raise RuntimeError("Library state records are malformed; Sync will not overwrite them.") + for reference in removed_paths: + # Retire exact active records without destroying their custom history. + # Historical basename aliases and unrelated records are untouched. + entry = files.get(reference) + if isinstance(entry, dict): + entry["library_removed_at"] = datetime.now(timezone.utc).isoformat() + for reference in current: + entry = files.get(reference) + if isinstance(entry, dict): + entry.pop("library_removed_at", None) + + targets = tuple( + track for track in snapshot.tracks + if track.match_status is LibraryMatchStatus.UNMATCHED + and (track.media_format == "MP3" or (track.title and track.artist)) + and _unknown_check_due(files.get(str(track.relative_path)), track, settings) + ) + identity_deps = replace( + deps.identity or IdentityBackfillDependencies(), + state_reader=lambda path: candidate_state, + state_writer=lambda path, state: None, + ) + try: + identity = backfill_catalogue_identities( + settings, targets, state_file=state_path, dependencies=identity_deps + ) if targets else None + except RuntimeError: + return LibraryIndexSyncResult(snapshot, new, changed, len(removed_paths), error="State changed during Sync; retry safely") + failed_paths = set(identity.failed_paths) if identity is not None else set() + attempted_paths = {str(track.relative_path) for track in targets} + if identity is not None and identity.failed == len(targets) and not identity.identified: + return LibraryIndexSyncResult( + snapshot, new, changed, len(removed_paths), + unknown=snapshot.unmatched_count, failed=identity.failed, + error="Catalogue identification unavailable; existing state was kept", + ) + + calculated_hashes: dict[str, str] = {} + for reference, track in current.items(): + if reference in failed_paths: + continue + entry = files.get(reference) + if ( + track.state_status is LibraryStateStatus.CHANGED + and isinstance(entry, dict) + and entry.get("sha256") == track.content_sha256 + ): + # A newly identified replacement must not inherit lyric claims + # derived from the previous audio bytes at this same path. + entry.pop("lyric_type", None) + entry.pop("lrc", None) + if isinstance(entry, dict) and entry.get("sha256") == track.content_sha256 and entry.get("song_id") is not None: + continue + if track.state_status not in {LibraryStateStatus.NEW, LibraryStateStatus.CHANGED}: + continue + try: + audio_hash = _current_hash(track, deps.hasher) + except OSError: + failed_paths.add(reference) + continue + calculated_hashes[reference] = audio_hash + updated = dict(entry) if isinstance(entry, dict) else {} + if updated.get("sha256") != audio_hash: + updated.pop("song_id", None) + updated.pop("api_name", None) + updated.pop(IDENTITY_SOURCE_FIELD, None) + updated.pop(IDENTITY_LOCK_FIELD, None) + updated.pop("lyric_type", None) + updated.pop("lrc", None) + updated.pop("catalogue_checked_at", None) + updated["sha256"] = audio_hash + if reference in attempted_paths and not updated.get("song_id"): + updated["catalogue_checked_at"] = datetime.now(timezone.utc).isoformat() + files[reference] = updated + + candidate_state["library_sync_paths"] = sorted(current) + if _source_bytes(state_path) != original_bytes: + return LibraryIndexSyncResult(snapshot, new, changed, len(removed_paths), error="State changed during Sync; retry safely") + effective_change = candidate_state != original + if effective_change: + deps.state_writer(state_path, candidate_state) + + refreshed_tracks: list[LibraryTrack] = [] + for track in snapshot.tracks: + reference = str(track.relative_path) + entry = files.get(reference) + if not isinstance(entry, dict) or not entry.get("sha256"): + refreshed_tracks.append(track) + continue + try: + audio_hash = calculated_hashes.get(reference) or _current_hash(track, deps.hasher) + except OSError: + refreshed_tracks.append(track) + continue + if entry.get("sha256") != audio_hash: + refreshed_tracks.append(track) + continue + updated_track = replace( + track, + state_status=LibraryStateStatus.CURRENT, + content_sha256=audio_hash, + state_entry_signature=state_entry_signature(reference, entry), + ) + if ( + entry.get("song_id") is not None + and entry.get("api_name") + and (track.media_format == "MP3" or (track.title and track.artist)) + ): + updated_track = replace( + updated_track, + match_status=LibraryMatchStatus.MATCHED, + matched_title=str(entry["api_name"]), + ) + refreshed_tracks.append(updated_track) + final_signature = ( + hashlib.sha256(_source_bytes(state_path) or b"").hexdigest() + if state_path.is_file() else None + ) + final_snapshot = replace( + snapshot, tracks=tuple(refreshed_tracks), state_signature=final_signature + ) + return LibraryIndexSyncResult( + final_snapshot, new, changed, len(removed_paths), + identified=identity.identified if identity else 0, + unknown=final_snapshot.unmatched_count, + failed=len(failed_paths), + ) diff --git a/src/juice_lyrics/services/library_issues.py b/src/juice_lyrics/services/library_issues.py new file mode 100644 index 0000000..ed90e57 --- /dev/null +++ b/src/juice_lyrics/services/library_issues.py @@ -0,0 +1,193 @@ +"""Actionable Library health derived from the existing read-only snapshot.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum + +from .library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, +) + + +class LibraryIssueCategory(str, Enum): + CATALOGUE = "catalogue" + LYRICS = "lyrics" + VERIFICATION = "verification" + METADATA = "metadata" + STATE = "state" + + +class LibraryIssueSeverity(str, Enum): + WARNING = "warning" + ERROR = "error" + + +class LibraryIssueAction(str, Enum): + MANUAL_MATCH = "manual_match" + REFRESH_LYRICS = "refresh_lyrics" + VERIFY = "verify" + SYNC = "sync" + METADATA_AUDIT = "metadata_audit" + + +@dataclass(frozen=True, slots=True) +class LibraryIssue: + """One user-facing row for all actionable conditions on one track.""" + + track: LibraryTrack + categories: tuple[LibraryIssueCategory, ...] + severity: LibraryIssueSeverity + summary: str + details: tuple[str, ...] + action: LibraryIssueAction + + @property + def category_label(self) -> str: + return " / ".join(category.value.title() for category in self.categories) + + +@dataclass(frozen=True, slots=True) +class LibraryHealth: + snapshot: LibrarySnapshot + issues: tuple[LibraryIssue, ...] + + @property + def issue_count(self) -> int: + return len(self.issues) + + @property + def healthy_count(self) -> int: + return max(0, self.snapshot.total_track_count - self.issue_count) + + +def _append_once(values: list[str], value: str) -> None: + if value not in values: + values.append(value) + + +def _issue_for_track(track: LibraryTrack) -> LibraryIssue | None: + categories: list[LibraryIssueCategory] = [] + details: list[str] = [] + severity = LibraryIssueSeverity.WARNING + summary: str | None = None + action: LibraryIssueAction | None = None + warning = (track.warning or "").casefold() + + if track.state_status is LibraryStateStatus.INVALID: + categories.append(LibraryIssueCategory.STATE) + _append_once(details, "Stored state or the local audio could not be validated safely.") + summary = "Library state could not be validated" + action = LibraryIssueAction.SYNC + severity = LibraryIssueSeverity.ERROR + elif track.state_status is LibraryStateStatus.CHANGED: + categories.append(LibraryIssueCategory.STATE) + _append_once(details, "The local audio changed since its saved library state.") + summary = "Local audio changed" + action = LibraryIssueAction.SYNC + elif track.state_status is LibraryStateStatus.NEW: + categories.append(LibraryIssueCategory.STATE) + _append_once(details, "This track has not been recorded by Sync Library yet.") + summary = "New track needs Library Sync" + action = LibraryIssueAction.SYNC + + locked_unavailable = track.identity_locked and ( + "manually selected catalogue recording is unavailable" in warning + or "manual catalogue" in warning and "unavailable" in warning + ) + if locked_unavailable: + categories.append(LibraryIssueCategory.CATALOGUE) + _append_once( + details, + "The saved manual choice is preserved, but that catalogue recording was unavailable when last checked.", + ) + summary = "Manual catalogue choice unavailable" + action = LibraryIssueAction.MANUAL_MATCH + elif track.match_status is LibraryMatchStatus.UNMATCHED: + categories.append(LibraryIssueCategory.CATALOGUE) + _append_once(details, "No catalogue identity has been established safely.") + if summary is None: + summary = "Catalogue match unknown" + if action is None: + action = LibraryIssueAction.MANUAL_MATCH + + metadata_problem = ( + "metadata is missing" in warning + or "metadata could not be read" in warning + ) + if metadata_problem: + categories.append(LibraryIssueCategory.METADATA) + _append_once(details, "Local metadata is incomplete or unreadable and blocks safe automatic matching.") + if summary is None or summary == "Catalogue match unknown": + summary = "Metadata blocks automatic matching" + if action is None: + action = LibraryIssueAction.MANUAL_MATCH + + verification_text = (track.verification_error or "").casefold() + verification_problem = bool( + verification_text + and not verification_text.startswith("no embedded ") + and verification_text != "no managed lyrics frame" + ) + if verification_problem: + categories.append(LibraryIssueCategory.VERIFICATION) + _append_once(details, f"Verification reported: {track.verification_error}") + severity = LibraryIssueSeverity.ERROR + if summary is None: + summary = "Audio or embedded lyrics failed verification" + if action is None: + action = LibraryIssueAction.VERIFY + + if track.lyric_status is LibraryLyricStatus.NONE: + categories.append(LibraryIssueCategory.LYRICS) + if verification_problem: + _append_once(details, "Supported embedded lyrics could not be verified.") + else: + _append_once( + details, + "No 999-managed embedded lyrics are present; this does not mean the audio is damaged.", + ) + if not verification_problem: + summary = summary or "Optional lyrics are not managed yet" + if action is None or action is LibraryIssueAction.VERIFY: + action = LibraryIssueAction.REFRESH_LYRICS + if track.lrc_status is LibraryLrcStatus.INVALID: + categories.append(LibraryIssueCategory.LYRICS) + _append_once(details, "The adjacent LRC does not contain valid timestamped lyric lines.") + summary = summary or "Synchronized LRC is invalid" + action = action or LibraryIssueAction.REFRESH_LYRICS + elif track.lrc_status is LibraryLrcStatus.MISSING and track.needs_attention: + categories.append(LibraryIssueCategory.LYRICS) + _append_once(details, "The expected adjacent synchronized LRC is missing.") + summary = summary or "Synchronized LRC is missing" + action = action or LibraryIssueAction.REFRESH_LYRICS + + if not categories: + return None + unique_categories = tuple(dict.fromkeys(categories)) + return LibraryIssue( + track=track, + categories=unique_categories, + severity=severity, + summary=summary or "Track needs attention", + details=tuple(details), + action=action or LibraryIssueAction.VERIFY, + ) + + +def get_library_health(snapshot: LibrarySnapshot) -> LibraryHealth: + """Project a current snapshot into one actionable issue row per track.""" + + return LibraryHealth( + snapshot, + tuple( + issue + for track in snapshot.tracks + if (issue := _issue_for_track(track)) is not None + ), + ) diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py new file mode 100644 index 0000000..2a11c20 --- /dev/null +++ b/src/juice_lyrics/services/library_status.py @@ -0,0 +1,522 @@ +from __future__ import annotations + +import json +import hashlib +from collections.abc import Callable +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +from typing import Any + +from ..backup.manager import list_backups +from ..config.settings import BACKUP_DIR, STATE_FILE, Settings +from ..library.scanner import find_mp3s +from ..library.matching import local_duration +from ..library.media import ( + AudioMetadata, + is_tagged_container, + media_format, + read_tagged_metadata, +) +from ..lyrics.engine import parse_synced_lyrics, verify_file +from ..lyrics.sidecar import sidecar_lrc_path +from ..state import file_fingerprint, resolve_state_entry, sha256_file +from .manual_identity import is_identity_locked + +LyricsVerifier = Callable[[Path], tuple[bool, str]] +DurationReader = Callable[[Path], float | None] + + +class LibraryLyricStatus(str, Enum): + SYNCED = "synced" + PLAIN = "plain" + NONE = "none" + + +class LibraryMatchStatus(str, Enum): + MATCHED = "matched" + UNMATCHED = "unmatched" + + +class LibraryLrcStatus(str, Enum): + PRESENT = "present" + MISSING = "missing" + INVALID = "invalid" + NONE = "none" + + +class LibraryStateStatus(str, Enum): + CURRENT = "current" + NEW = "new" + CHANGED = "changed" + INVALID = "invalid" + + +@dataclass(frozen=True, slots=True) +class LibraryTrack: + """Presentation-neutral read-only information about one local audio file.""" + + reference: str + path: Path + relative_path: Path + filename: str + title: str + duration_seconds: float | None + match_status: LibraryMatchStatus + matched_title: str | None + lyric_status: LibraryLyricStatus + lrc_status: LibraryLrcStatus + lrc_path: Path | None + state_status: LibraryStateStatus + warning: str | None = None + artist: str | None = None + album: str | None = None + media_format: str = "MP3" + synchronized_source: bool = False + content_sha256: str | None = None + content_fingerprint: tuple[int, int, int, int, int] | None = None + sidecar_fingerprint: tuple[int, int, int, int, int] | None = None + identity_source: str | None = None + identity_locked: bool = False + verification_error: str | None = None + catalogue_id: Any | None = None + state_entry_signature: str | None = None + + @property + def needs_attention(self) -> bool: + if self.lyric_status is LibraryLyricStatus.NONE: + return True + if self.lrc_status is LibraryLrcStatus.INVALID: + return True + if self.lyric_status is LibraryLyricStatus.SYNCED: + return self.lrc_status is not LibraryLrcStatus.PRESENT + if self.synchronized_source: + return self.lrc_status is not LibraryLrcStatus.PRESENT + return False + + @property + def fully_covered(self) -> bool: + """Whether format-appropriate embedded lyrics and a synced sidecar are healthy.""" + + return ( + self.lrc_status is LibraryLrcStatus.PRESENT + and ( + self.lyric_status is LibraryLyricStatus.SYNCED + or ( + self.media_format.casefold() in {"flac", "m4a"} + and self.lyric_status is LibraryLyricStatus.PLAIN + ) + ) + ) + + +@dataclass(frozen=True, slots=True) +class LibrarySnapshot: + """Read-only track-level snapshot for frontend library browsing.""" + + library_path: Path + directory_exists: bool + tracks: tuple[LibraryTrack, ...] + warnings: tuple[str, ...] = () + state_signature: str | None = None + + @property + def total_track_count(self) -> int: + return len(self.tracks) + + @property + def matched_count(self) -> int: + return sum(track.match_status is LibraryMatchStatus.MATCHED for track in self.tracks) + + @property + def unmatched_count(self) -> int: + return self.total_track_count - self.matched_count + + @property + def synced_count(self) -> int: + return sum(track.lyric_status is LibraryLyricStatus.SYNCED for track in self.tracks) + + @property + def plain_count(self) -> int: + return sum(track.lyric_status is LibraryLyricStatus.PLAIN for track in self.tracks) + + @property + def no_lyrics_count(self) -> int: + return sum(track.lyric_status is LibraryLyricStatus.NONE for track in self.tracks) + + @property + def external_lrc_count(self) -> int: + return sum(track.lrc_status is LibraryLrcStatus.PRESENT for track in self.tracks) + + @property + def needs_attention_count(self) -> int: + return sum(track.needs_attention for track in self.tracks) + + @property + def fully_covered_count(self) -> int: + return sum(track.fully_covered for track in self.tracks) + + @property + def plain_only_count(self) -> int: + return sum( + track.lyric_status is LibraryLyricStatus.PLAIN + and not track.fully_covered + for track in self.tracks + ) + + @property + def missing_lyrics_count(self) -> int: + return sum(track.lyric_status is LibraryLyricStatus.NONE for track in self.tracks) + + def format_count(self, name: str) -> int: + return sum(track.media_format.casefold() == name.casefold() for track in self.tracks) + + +@dataclass(frozen=True, slots=True) +class LibraryStatus: + """Read-only snapshot of the application's local audio library status.""" + + library_path: Path + track_count: int + embedded_synced_count: int + embedded_plain_count: int + missing_or_invalid_count: int + rmpc_lrc_count: int + new_or_changed_count: int + backup_count: int + warnings: tuple[str, ...] = () + + +def _read_state(path: Path) -> dict[str, Any]: + """Read state without creating or modifying application data directories.""" + + if not path.exists(): + return {"files": {}, "updated": None} + try: + value = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return {"files": {}, "updated": None} + return value if isinstance(value, dict) else {"files": {}, "updated": None} + + +def _read_state_snapshot(path: Path) -> tuple[dict[str, Any], tuple[str, ...]]: + if not path.exists(): + return {"files": {}, "updated": None}, () + try: + value = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + return {"files": {}, "updated": None}, (f"Library state could not be read: {exc}",) + if not isinstance(value, dict): + return {"files": {}, "updated": None}, ("Library state has an unsupported format.",) + if not isinstance(value.get("files", {}), dict): + return {"files": {}, "updated": value.get("updated")}, ("Library state file records are malformed.",) + return value, () + + +def _has_timed_lrc(path: Path) -> tuple[bool, str | None]: + try: + raw = path.read_text(encoding="utf-8") + except (OSError, UnicodeError) as exc: + return False, f"Adjacent LRC could not be read: {exc}" + if parse_synced_lyrics(raw): + return True, None + return False, "Adjacent LRC has no timestamped lyric lines." + + +def state_entry_signature(state_key: str | None, raw_entry: object) -> str: + """Fingerprint only the state record that can affect one displayed track.""" + + encoded = json.dumps( + (state_key, raw_entry), + sort_keys=True, + separators=(",", ":"), + ensure_ascii=False, + ).encode("utf-8") + return hashlib.sha256(encoded).hexdigest() + + +def get_library_snapshot( + settings: Settings, + *, + state_file: Path = STATE_FILE, + verifier: LyricsVerifier = verify_file, + duration_reader: DurationReader = local_duration, + hasher: Callable[[Path], str] = sha256_file, + metadata_reader: Callable[[Path], AudioMetadata] = read_tagged_metadata, + previous_snapshot: LibrarySnapshot | None = None, +) -> LibrarySnapshot: + """Inspect local MP3, FLAC, and M4A files without APIs or writes.""" + + library_path = Path(settings.music_dir) + if not library_path.is_dir(): + return LibrarySnapshot( + library_path, + False, + (), + (f"Music directory does not exist: {library_path}",), + ) + + state, warnings = _read_state_snapshot(Path(state_file)) + try: + state_signature = hashlib.sha256(Path(state_file).read_bytes()).hexdigest() + except FileNotFoundError: + state_signature = None + except OSError: + state_signature = None + state_files = state.get("files", {}) + discovered = find_mp3s(settings) + relative_paths = tuple(path.relative_to(library_path) for path in discovered) + previous_tracks = ( + {track.relative_path: track for track in previous_snapshot.tracks} + if previous_snapshot is not None + and not warnings + and previous_snapshot.library_path == library_path + else {} + ) + whole_state_unchanged = bool( + previous_snapshot is not None + and previous_snapshot.state_signature == state_signature + ) + tracks: list[LibraryTrack] = [] + for path in discovered: + relative_path = path.relative_to(library_path) + state_key, resolved_entry = resolve_state_entry( + state_files, + relative_path, + relative_paths, + ) + raw_entry = state_files.get(state_key) if state_key is not None else None + entry_signature = state_entry_signature(state_key, raw_entry) + prior = previous_tracks.get(relative_path) + if prior is not None and prior.content_fingerprint is not None: + sidecar = sidecar_lrc_path(path) + try: + current_sidecar = file_fingerprint(sidecar) if sidecar.is_file() else None + if ( + file_fingerprint(path) == prior.content_fingerprint + and current_sidecar == prior.sidecar_fingerprint + and ( + whole_state_unchanged + or prior.state_entry_signature == entry_signature + ) + ): + tracks.append(prior) + continue + except OSError: + pass + reference = str(relative_path) + entry = resolved_entry if isinstance(resolved_entry, dict) else None + content_sha256 = None + content_fingerprint = None + track_warnings: list[str] = [] + metadata: AudioMetadata | None = None + metadata_safe_for_matching = True + + if is_tagged_container(path): + try: + metadata = metadata_reader(path) + missing_metadata = [ + label + for label, value in (("title", metadata.title), ("artist", metadata.artist)) + if not value + ] + if missing_metadata: + metadata_safe_for_matching = False + track_warnings.append( + f"{media_format(path)} metadata is missing {', '.join(missing_metadata)}; track cannot be matched safely." + ) + except Exception as exc: + metadata_safe_for_matching = False + track_warnings.append(f"{media_format(path)} metadata could not be read: {exc}") + + try: + valid, verification = verifier(path) + except Exception as exc: + valid, verification = False, str(exc) or type(exc).__name__ + if valid and verification.startswith("SYLT"): + lyric_status = LibraryLyricStatus.SYNCED + elif valid: + lyric_status = LibraryLyricStatus.PLAIN + else: + lyric_status = LibraryLyricStatus.NONE + if verification: + track_warnings.append(verification) + + if raw_entry is None: + state_status = LibraryStateStatus.NEW + try: + content_fingerprint = file_fingerprint(path) + except OSError: + pass + elif entry is None: + state_status = LibraryStateStatus.INVALID + track_warnings.append("Stored library state is malformed.") + else: + try: + before = file_fingerprint(path) + content_sha256 = hasher(path) + after = file_fingerprint(path) + if before != after: + state_status = LibraryStateStatus.INVALID + content_sha256 = None + track_warnings.append("Audio changed while being scanned; refresh again.") + else: + content_fingerprint = after + state_status = ( + LibraryStateStatus.CURRENT + if entry.get("sha256") == content_sha256 + else LibraryStateStatus.CHANGED + ) + except OSError as exc: + state_status = LibraryStateStatus.INVALID + track_warnings.append(f"Could not hash file: {exc}") + + matched_title = None + if entry is not None and state_status is LibraryStateStatus.CURRENT: + candidate_title = entry.get("api_name") + if candidate_title is not None and str(candidate_title).strip(): + matched_title = str(candidate_title).strip() + matched = metadata_safe_for_matching and bool( + matched_title + or ( + entry is not None + and state_status is LibraryStateStatus.CURRENT + and entry.get("song_id") is not None + ) + ) + + expected_synced = bool( + entry is not None + and entry.get("lyric_type") in { + "SYLT", + "FLAC_LYRICS_SYNCED", + "M4A_LYRICS_SYNCED", + } + ) + adjacent_lrc = sidecar_lrc_path(path) + sidecar_exists = adjacent_lrc.is_file() + sidecar_fingerprint = None + if sidecar_exists: + try: + sidecar_fingerprint = file_fingerprint(adjacent_lrc) + except OSError: + pass + lrc_path = adjacent_lrc if lyric_status is LibraryLyricStatus.SYNCED or expected_synced or sidecar_exists else None + if lrc_path is None: + lrc_status = LibraryLrcStatus.NONE + elif sidecar_exists: + valid_lrc, lrc_warning = _has_timed_lrc(lrc_path) + lrc_status = LibraryLrcStatus.PRESENT if valid_lrc else LibraryLrcStatus.INVALID + if lrc_warning: + track_warnings.append(lrc_warning) + else: + lrc_status = LibraryLrcStatus.MISSING + track_warnings.append("Adjacent external LRC file is missing.") + + try: + duration = ( + metadata.duration_seconds + if metadata is not None + else duration_reader(path) + ) + except Exception as exc: + duration = None + track_warnings.append(f"Duration unavailable: {exc}") + + tracks.append( + LibraryTrack( + reference=reference, + path=path, + relative_path=relative_path, + filename=path.name, + title=metadata.title if metadata is not None and metadata.title else path.stem, + duration_seconds=duration, + match_status=( + LibraryMatchStatus.MATCHED if matched else LibraryMatchStatus.UNMATCHED + ), + matched_title=matched_title, + lyric_status=lyric_status, + lrc_status=lrc_status, + lrc_path=lrc_path, + state_status=state_status, + artist=metadata.artist if metadata is not None else None, + album=metadata.album if metadata is not None else None, + media_format=media_format(path), + synchronized_source=expected_synced, + warning=" ".join(track_warnings) or None, + content_sha256=content_sha256, + content_fingerprint=content_fingerprint, + sidecar_fingerprint=sidecar_fingerprint, + identity_source=( + str(entry.get("identity_source")) + if entry is not None + and state_status is LibraryStateStatus.CURRENT + and entry.get("identity_source") + else None + ), + identity_locked=( + state_status is LibraryStateStatus.CURRENT + and is_identity_locked(entry) + ), + verification_error=verification if not valid else None, + catalogue_id=( + entry.get("song_id") + if entry is not None + and state_status is LibraryStateStatus.CURRENT + else None + ), + state_entry_signature=entry_signature, + ) + ) + return LibrarySnapshot(library_path, True, tuple(tracks), warnings, state_signature) + + +def get_library_status( + settings: Settings, + *, + state_file: Path = STATE_FILE, + backup_dir: Path = BACKUP_DIR, + verifier: LyricsVerifier = verify_file, +) -> LibraryStatus: + """Calculate a status snapshot without contacting APIs or changing local state.""" + + library_path = Path(settings.music_dir) + files = find_mp3s(settings) + state = _read_state(Path(state_file)) + state_files = state.get("files", {}) + if not isinstance(state_files, dict): + state_files = {} + + synced = plain = missing = new_or_changed = lrc = 0 + relative_paths = tuple(path.relative_to(library_path) for path in files) + for path in files: + valid, message = verifier(path) + if valid: + if message.startswith("SYLT"): + synced += 1 + else: + plain += 1 + else: + missing += 1 + + relative = str(path.relative_to(library_path)) + _, entry = resolve_state_entry(state_files, Path(relative), relative_paths) + if not isinstance(entry, dict) or entry.get("sha256") != sha256_file(path): + new_or_changed += 1 + adjacent_lrc = sidecar_lrc_path(path) + if adjacent_lrc.is_file() and _has_timed_lrc(adjacent_lrc)[0] and ( + (valid and message.startswith("SYLT")) or is_tagged_container(path) + ): + lrc += 1 + + backup_count = len(list_backups(Path(backup_dir))) + return LibraryStatus( + library_path=library_path, + track_count=len(files), + embedded_synced_count=synced, + embedded_plain_count=plain, + missing_or_invalid_count=missing, + rmpc_lrc_count=lrc, + new_or_changed_count=new_or_changed, + backup_count=backup_count, + ) diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py new file mode 100644 index 0000000..05f3f0a --- /dev/null +++ b/src/juice_lyrics/services/library_sync.py @@ -0,0 +1,628 @@ +from __future__ import annotations + +import json +import shutil +from collections.abc import Callable, Mapping +from dataclasses import dataclass, field, replace +from enum import Enum +from pathlib import Path +from typing import Any + +from ..api.client import search_song_names +from ..backup.manager import backup_file, make_backup_root, restore_file, write_manifest +from ..config.settings import DEFAULT_RMPC_CONFIG, STATE_FILE, Settings +from ..library.matching import choose_candidate, search_title_for +from ..library.media import MediaMetadataError, is_flac, is_m4a +from ..library.scanner import find_mp3s +from ..lyrics.engine import embed_lyrics, parse_synced_lyrics, verify_file, write_lrc +from ..lyrics.sidecar import sidecar_lrc_path +from ..rmpc.integration import notify_rmpc_index, patch_rmpc_config +from ..state import load_state, resolve_state_entry, save_state, sha256_file +from ..backup.manager import now_iso +from .manual_identity import ( + IDENTITY_LOCK_FIELD, + IDENTITY_SOURCE_FIELD, + is_identity_locked, +) + + +class SyncLyricType(str, Enum): + SYNCED = "SYLT" + PLAIN = "USLT" + NONE = "NONE" + + +class MatchOutcome(str, Enum): + UNCHANGED = "unchanged" + MATCHED = "matched" + UNRESOLVED = "unresolved" + NO_LYRICS = "no_lyrics" + FAILED = "failed" + + +class SyncEventKind(str, Enum): + SCAN_STARTED = "scan_started" + TRACK_INSPECTED = "track_inspected" + MATCH_FOUND = "match_found" + UNRESOLVED = "unresolved" + SCAN_COMPLETED = "scan_completed" + BACKUP_CREATED = "backup_created" + LYRICS_EMBEDDED = "lyrics_embedded" + VERIFICATION_SUCCEEDED = "verification_succeeded" + VERIFICATION_FAILED = "verification_failed" + LRC_GENERATED = "lrc_generated" + STATE_UPDATED = "state_updated" + TRACK_COMPLETED = "track_completed" + TRACK_FAILED = "track_failed" + + +@dataclass(frozen=True, slots=True) +class LibrarySyncOptions: + settings: Settings + music_dir: Path + dry_run: bool = False + refresh: bool = False + rmpc_enabled: bool = False + lyrics_dir: Path | None = None + rmpc_config_path: Path | None = None + duration_tolerance: float = 3.0 + state_file: Path = STATE_FILE + selected_paths: tuple[Path, ...] = () + protected_paths: tuple[Path, ...] = () + + def __post_init__(self) -> None: + # Kept as a constructor field for compatibility with older callers. + # External lyrics are now derived solely from each audio path. + object.__setattr__(self, "lyrics_dir", None) + + @classmethod + def from_settings( + cls, + settings: Settings, + *, + dry_run: bool = False, + refresh: bool = False, + rmpc_enabled: bool = False, + lyrics_dir: Path | None = None, + rmpc_config_path: Path | None = None, + state_file: Path = STATE_FILE, + selected_paths: tuple[Path, ...] = (), + protected_paths: tuple[Path, ...] = (), + ) -> "LibrarySyncOptions": + return cls( + settings=settings, + music_dir=Path(settings.music_dir), + dry_run=dry_run, + refresh=refresh, + rmpc_enabled=rmpc_enabled, + lyrics_dir=None, + rmpc_config_path=Path(rmpc_config_path) if rmpc_config_path is not None else None, + duration_tolerance=settings.duration_tolerance, + state_file=Path(state_file), + selected_paths=tuple(Path(path) for path in selected_paths), + protected_paths=tuple(Path(path) for path in protected_paths), + ) + + +@dataclass(frozen=True, slots=True) +class SyncEvent: + kind: SyncEventKind + path: Path | None = None + index: int | None = None + total: int | None = None + message: str | None = None + + +@dataclass(frozen=True, slots=True) +class TrackSyncPlan: + path: Path + outcome: MatchOutcome + lyric_type: SyncLyricType + candidate: Mapping[str, Any] | None = None + synced_lyrics: tuple[tuple[str, int], ...] = () + plain_lyrics: str = "" + error: str | None = None + lrc_path: Path | None = None + identity_locked: bool = False + + +@dataclass(frozen=True, slots=True) +class TrackSyncResult: + path: Path + outcome: MatchOutcome + lyric_type: SyncLyricType + updated: bool = False + verification: str | None = None + backup_path: Path | None = None + lrc_path: Path | None = None + error: str | None = None + warning: str | None = None + + +@dataclass(frozen=True, slots=True) +class LibrarySyncPlan: + options: LibrarySyncOptions + tracks: tuple[TrackSyncPlan, ...] + state: dict[str, Any] = field(repr=False, compare=False) + + @property + def total_files(self) -> int: + return len(self.tracks) + + @property + def unchanged_files(self) -> int: + return sum(track.outcome is MatchOutcome.UNCHANGED for track in self.tracks) + + @property + def changed_or_new_files(self) -> int: + return sum(track.outcome is not MatchOutcome.UNCHANGED and track.outcome is not MatchOutcome.FAILED for track in self.tracks) + + @property + def ready_files(self) -> int: + return sum(track.outcome is MatchOutcome.MATCHED for track in self.tracks) + + @property + def unresolved_files(self) -> int: + return sum(track.outcome is MatchOutcome.UNRESOLVED for track in self.tracks) + + @property + def no_lyrics_files(self) -> int: + return sum(track.outcome is MatchOutcome.NO_LYRICS for track in self.tracks) + + @property + def synced_files(self) -> int: + return sum(track.outcome is MatchOutcome.MATCHED and track.lyric_type is SyncLyricType.SYNCED for track in self.tracks) + + @property + def plain_files(self) -> int: + return sum(track.outcome is MatchOutcome.MATCHED and track.lyric_type is SyncLyricType.PLAIN for track in self.tracks) + + @property + def analysis_failures(self) -> int: + return sum(track.outcome is MatchOutcome.FAILED for track in self.tracks) + + +@dataclass(frozen=True, slots=True) +class LibrarySyncResult: + plan: LibrarySyncPlan + tracks: tuple[TrackSyncResult, ...] + updated_files: int + failed_files: int + processing_failed_files: int + lrc_files_generated: int + rmpc_notifications: int + backup_path: Path | None + warnings: tuple[str, ...] = () + + +ProgressCallback = Callable[[SyncEvent], None] + + +@dataclass(slots=True) +class LibrarySyncDependencies: + scanner: Callable[[Any], list[Path]] = find_mp3s + searcher: Callable[..., list[dict[str, Any]]] = search_song_names + matcher: Callable[..., Any] = choose_candidate + search_title: Callable[[Path], str] = search_title_for + lyric_parser: Callable[[str], list[tuple[str, int]]] = parse_synced_lyrics + embedder: Callable[[Path, list[tuple[str, int]], str], str] = embed_lyrics + verifier: Callable[[Path], tuple[bool, str]] = verify_file + backup_root_factory: Callable[[], Path] = make_backup_root + backup_writer: Callable[[Path, Path, Path], Path] = backup_file + restorer: Callable[[Path, Path], None] = restore_file + manifest_writer: Callable[[Path, list[dict[str, Any]]], None] = write_manifest + lrc_writer: Callable[[Path, list[tuple[str, int]], dict[str, Any]], Path] = write_lrc + rmpc_notifier: Callable[[list[Path]], int] = notify_rmpc_index + rmpc_configurer: Callable[[Path, Path], Path] = patch_rmpc_config + state_loader: Callable[[], dict[str, Any]] = load_state + state_saver: Callable[[dict[str, Any]], None] = save_state + hasher: Callable[[Path], str] = sha256_file + + +def _emit(callback: ProgressCallback | None, kind: SyncEventKind, **kwargs: Any) -> None: + if callback: + callback(SyncEvent(kind=kind, **kwargs)) + + +def _read_state(path: Path) -> dict[str, Any]: + if not path.exists(): + return {"files": {}, "updated": None} + try: + value = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return {"files": {}, "updated": None} + return value if isinstance(value, dict) else {"files": {}, "updated": None} + + +def _state_is_current( + state: Mapping[str, Any], + path: Path, + options: LibrarySyncOptions, + dependencies: LibrarySyncDependencies, + library_relative_paths: tuple[Path, ...] = (), +) -> bool: + state_files = state.get("files", {}) + if not isinstance(state_files, Mapping): + return False + _, entry = resolve_state_entry( + state_files, + path.relative_to(options.music_dir), + library_relative_paths, + ) + if not isinstance(entry, Mapping): + return False + try: + if entry.get("sha256") != dependencies.hasher(path): + return False + except OSError: + return False + valid, _ = dependencies.verifier(path) + if not valid: + return False + if options.rmpc_enabled and entry.get("lyric_type") in { + SyncLyricType.SYNCED.value, + "FLAC_LYRICS_SYNCED", + "M4A_LYRICS_SYNCED", + }: + lrc_path = sidecar_lrc_path(path) + try: + synced_lines = dependencies.lyric_parser(lrc_path.read_text(encoding="utf-8")) + except (OSError, UnicodeError): + return False + if not synced_lines: + return False + return True + + +def _locked_song_id( + state: Mapping[str, Any], + path: Path, + options: LibrarySyncOptions, + dependencies: LibrarySyncDependencies, + library_relative_paths: tuple[Path, ...], +) -> Any | None: + state_files = state.get("files", {}) + if not isinstance(state_files, Mapping): + return None + _, entry = resolve_state_entry( + state_files, + path.relative_to(options.music_dir), + library_relative_paths, + ) + if not is_identity_locked(entry): + return None + try: + if entry.get("sha256") != dependencies.hasher(path): + return None + except OSError: + return None + return entry.get("song_id") + + +def plan_library_sync( + options: LibrarySyncOptions, + *, + dependencies: LibrarySyncDependencies | None = None, + progress: ProgressCallback | None = None, +) -> LibrarySyncPlan: + dependencies = dependencies or LibrarySyncDependencies() + files = dependencies.scanner(options.settings) + if options.selected_paths: + selected = {path.resolve() for path in options.selected_paths} + files = [path for path in files if path.resolve() in selected] + state = _read_state(options.state_file) if options.dry_run else dependencies.state_loader() + tracks: list[TrackSyncPlan] = [] + protected = {path.resolve() for path in options.protected_paths} + relative_paths = tuple(path.relative_to(options.music_dir) for path in files) + _emit(progress, SyncEventKind.SCAN_STARTED, total=len(files)) + for index, path in enumerate(files, start=1): + if path.resolve() in protected: + tracks.append(TrackSyncPlan(path, MatchOutcome.UNCHANGED, SyncLyricType.NONE)) + _emit( + progress, + SyncEventKind.TRACK_INSPECTED, + path=path, + index=index, + total=len(files), + message="locally covered", + ) + continue + if not options.refresh and _state_is_current( + state, + path, + options, + dependencies, + relative_paths, + ): + _emit( + progress, + SyncEventKind.TRACK_INSPECTED, + path=path, + index=index, + total=len(files), + message="unchanged", + ) + tracks.append(TrackSyncPlan(path, MatchOutcome.UNCHANGED, SyncLyricType.NONE)) + continue + _emit(progress, SyncEventKind.TRACK_INSPECTED, path=path, index=index, total=len(files)) + try: + title = dependencies.search_title(path) + results = dependencies.searcher(options.settings, title, refresh=options.refresh) + locked_song_id = _locked_song_id( + state, path, options, dependencies, relative_paths + ) + if locked_song_id is not None: + candidate = next( + ( + result + for result in results + if isinstance(result, Mapping) + and str(result.get("id")) == str(locked_song_id) + ), + None, + ) + else: + candidate, _, _, _ = dependencies.matcher( + options.settings, path, results, title + ) + if candidate is None: + error = ( + "The manually selected catalogue recording is unavailable." + if locked_song_id is not None + else None + ) + tracks.append( + TrackSyncPlan( + path, + MatchOutcome.UNRESOLVED, + SyncLyricType.NONE, + error=error, + identity_locked=locked_song_id is not None, + ) + ) + _emit(progress, SyncEventKind.UNRESOLVED, path=path, message=error) + continue + synced = tuple(dependencies.lyric_parser(str(candidate.get("synced_lyrics") or ""))) + plain = str(candidate.get("lyrics") or "") + if synced: + lyric_type = SyncLyricType.SYNCED + elif plain.strip(): + lyric_type = SyncLyricType.PLAIN + else: + tracks.append(TrackSyncPlan(path, MatchOutcome.NO_LYRICS, SyncLyricType.NONE, candidate)) + continue + tracks.append( + TrackSyncPlan( + path, + MatchOutcome.MATCHED, + lyric_type, + candidate, + synced, + plain, + lrc_path=( + sidecar_lrc_path(path) + if options.rmpc_enabled and lyric_type is SyncLyricType.SYNCED + else None + ), + identity_locked=locked_song_id is not None, + ) + ) + _emit(progress, SyncEventKind.MATCH_FOUND, path=path, message=lyric_type.value) + except MediaMetadataError as exc: + tracks.append( + TrackSyncPlan( + path, + MatchOutcome.UNRESOLVED, + SyncLyricType.NONE, + error=str(exc), + ) + ) + _emit(progress, SyncEventKind.UNRESOLVED, path=path, message=str(exc)) + except Exception as exc: + tracks.append(TrackSyncPlan(path, MatchOutcome.FAILED, SyncLyricType.NONE, error=str(exc))) + _emit(progress, SyncEventKind.TRACK_FAILED, path=path, message=str(exc)) + _emit(progress, SyncEventKind.SCAN_COMPLETED, total=len(files)) + return LibrarySyncPlan(options, tuple(tracks), state) + + +def get_library_sync_preview( + settings: Settings, + *, + rmpc_enabled: bool | None = None, + lyrics_dir: Path | None = None, + state_file: Path = STATE_FILE, + dependencies: LibrarySyncDependencies | None = None, + progress: ProgressCallback | None = None, + refresh: bool = False, + selected_paths: tuple[Path, ...] = (), + protected_paths: tuple[Path, ...] = (), +) -> LibrarySyncPlan: + """Build a non-mutating sync plan suitable for read-only frontends.""" + + if rmpc_enabled is None: + rmpc_enabled = shutil.which("rmpc") is not None and DEFAULT_RMPC_CONFIG.exists() + options = LibrarySyncOptions.from_settings( + settings, + dry_run=True, + refresh=refresh, + rmpc_enabled=rmpc_enabled, + lyrics_dir=lyrics_dir, + state_file=state_file, + selected_paths=selected_paths, + protected_paths=protected_paths, + ) + return plan_library_sync(options, dependencies=dependencies, progress=progress) + + +def execute_library_sync_preview( + preview: LibrarySyncPlan, + *, + dependencies: LibrarySyncDependencies | None = None, + progress: ProgressCallback | None = None, +) -> LibrarySyncResult: + """Apply an explicitly reviewed dry-run plan through the normal sync engine.""" + + if not preview.options.dry_run: + raise ValueError("library maintenance requires a dry-run preview") + live_plan = LibrarySyncPlan( + replace(preview.options, dry_run=False), + preview.tracks, + preview.state, + ) + return execute_library_sync(live_plan, dependencies=dependencies, progress=progress) + + +def _state_entry( + state: dict[str, Any], + track: TrackSyncPlan, + options: LibrarySyncOptions, + lrc_path: Path | None, + dependencies: LibrarySyncDependencies, +) -> None: + candidate = track.candidate or {} + lyric_type = track.lyric_type.value + if is_flac(track.path): + lyric_type = ( + "FLAC_LYRICS_SYNCED" + if track.lyric_type is SyncLyricType.SYNCED + else "FLAC_LYRICS_PLAIN" + ) + elif is_m4a(track.path): + lyric_type = ( + "M4A_LYRICS_SYNCED" + if track.lyric_type is SyncLyricType.SYNCED + else "M4A_LYRICS_PLAIN" + ) + reference = str(track.path.relative_to(options.music_dir)) + files = state.setdefault("files", {}) + previous = files.get(reference) if isinstance(files, dict) else None + entry = dict(previous) if isinstance(previous, Mapping) else {} + if not track.identity_locked: + entry.pop(IDENTITY_SOURCE_FIELD, None) + entry.pop(IDENTITY_LOCK_FIELD, None) + entry.update( + { + "sha256": dependencies.hasher(track.path), + "song_id": candidate.get("id"), + "api_name": candidate.get("name"), + "lyric_type": lyric_type, + "lrc": str(lrc_path) if lrc_path else None, + "updated": now_iso(), + } + ) + files[reference] = entry + + +def execute_library_sync( + plan: LibrarySyncPlan, + *, + dependencies: LibrarySyncDependencies | None = None, + progress: ProgressCallback | None = None, +) -> LibrarySyncResult: + dependencies = dependencies or LibrarySyncDependencies() + options = plan.options + initial_results = [ + TrackSyncResult(track.path, track.outcome, track.lyric_type, error=track.error) + for track in plan.tracks + if track.outcome is not MatchOutcome.MATCHED + ] + if options.dry_run: + return LibrarySyncResult( + plan, tuple(initial_results), 0, plan.analysis_failures, 0, 0, 0, None + ) + + ready = [track for track in plan.tracks if track.outcome is MatchOutcome.MATCHED] + if not ready: + dependencies.state_saver(plan.state) + return LibrarySyncResult( + plan, tuple(initial_results), 0, plan.analysis_failures, 0, 0, 0, None + ) + + backup_root = dependencies.backup_root_factory() + manifest: list[dict[str, Any]] = [] + generated_lrc: list[Path] = [] + results: list[TrackSyncResult] = initial_results + for track in ready: + backup: Path | None = None + try: + original_hash = dependencies.hasher(track.path) + backup = dependencies.backup_writer(track.path, backup_root, options.music_dir) + _emit(progress, SyncEventKind.BACKUP_CREATED, path=track.path, message=str(backup)) + try: + embedded = dependencies.embedder(track.path, list(track.synced_lyrics), track.plain_lyrics) + _emit(progress, SyncEventKind.LYRICS_EMBEDDED, path=track.path, message=embedded) + valid, verification = dependencies.verifier(track.path) + if not valid: + _emit(progress, SyncEventKind.VERIFICATION_FAILED, path=track.path, message=verification) + raise RuntimeError(f"verification failed: {verification}") + _emit(progress, SyncEventKind.VERIFICATION_SUCCEEDED, path=track.path, message=verification) + except Exception: + dependencies.restorer(backup, track.path) + raise + + lrc_path: Path | None = None + if options.rmpc_enabled and track.lyric_type is SyncLyricType.SYNCED: + lrc_path = dependencies.lrc_writer( + track.path, + list(track.synced_lyrics), + dict(track.candidate or {}), + ) + generated_lrc.append(lrc_path) + _emit(progress, SyncEventKind.LRC_GENERATED, path=track.path, message=str(lrc_path)) + _state_entry(plan.state, track, options, lrc_path, dependencies) + _emit(progress, SyncEventKind.STATE_UPDATED, path=track.path) + manifest.append({ + "file": str(track.path), + "sha256_before": original_hash, + "lyric_type": track.lyric_type.value, + "verification": verification, + }) + result = TrackSyncResult( + track.path, + MatchOutcome.MATCHED, + track.lyric_type, + updated=True, + verification=verification, + backup_path=backup, + lrc_path=lrc_path, + ) + results.append(result) + completion = track.lyric_type.value + (" + LRC" if lrc_path else "") + _emit(progress, SyncEventKind.TRACK_COMPLETED, path=track.path, message=completion) + except Exception as exc: + results.append(TrackSyncResult( + track.path, + MatchOutcome.FAILED, + track.lyric_type, + backup_path=backup, + error=str(exc), + )) + _emit(progress, SyncEventKind.TRACK_FAILED, path=track.path, message=str(exc)) + + dependencies.manifest_writer(backup_root, manifest) + dependencies.state_saver(plan.state) + warnings: list[str] = [] + notified = 0 + if options.rmpc_enabled: + try: + notified = dependencies.rmpc_notifier(generated_lrc) + except Exception as exc: + warnings.append(str(exc)) + result_by_path = {result.path: result for result in results} + ordered_results = tuple(result_by_path[track.path] for track in plan.tracks) + ready_paths = {track.path for track in ready} + processing_failures = sum( + result.outcome is MatchOutcome.FAILED and result.path in ready_paths + for result in ordered_results + ) + return LibrarySyncResult( + plan=plan, + tracks=ordered_results, + updated_files=sum(result.updated for result in ordered_results), + failed_files=sum(result.outcome is MatchOutcome.FAILED for result in ordered_results), + processing_failed_files=processing_failures, + lrc_files_generated=len(generated_lrc), + rmpc_notifications=notified, + backup_path=backup_root, + warnings=tuple(warnings), + ) diff --git a/src/juice_lyrics/services/manual_identity.py b/src/juice_lyrics/services/manual_identity.py new file mode 100644 index 0000000..4f39d9b --- /dev/null +++ b/src/juice_lyrics/services/manual_identity.py @@ -0,0 +1,201 @@ +"""Explicit user-selected catalogue identities with file-bound locking.""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from ..backup.manager import now_iso +from ..config.settings import STATE_FILE, Settings +from ..state import ( + file_fingerprint, + read_state_file, + resolve_state_entry, + sha256_file, + write_state_file, +) +if TYPE_CHECKING: + from .library_status import LibraryTrack + +IDENTITY_SOURCE_FIELD = "identity_source" +IDENTITY_LOCK_FIELD = "identity_locked" +MANUAL_IDENTITY_SOURCE = "manual" + + +def is_identity_locked(entry: Mapping[str, Any] | None) -> bool: + """Return whether an entry contains a complete, explicit manual lock.""" + + return bool( + isinstance(entry, Mapping) + and entry.get(IDENTITY_LOCK_FIELD) is True + and entry.get(IDENTITY_SOURCE_FIELD) == MANUAL_IDENTITY_SOURCE + and entry.get("song_id") is not None + and str(entry.get("api_name") or "").strip() + ) + + +@dataclass(frozen=True, slots=True) +class ManualIdentityResult: + reference: str + song_id: Any | None + api_name: str | None + locked: bool + changed: bool + + +@dataclass(slots=True) +class ManualIdentityDependencies: + state_reader: Callable[[Path], dict[str, Any]] = read_state_file + state_writer: Callable[[Path, Mapping[str, Any]], None] = write_state_file + hasher: Callable[[Path], str] = sha256_file + + +def _source_bytes(path: Path) -> bytes | None: + try: + return path.read_bytes() + except FileNotFoundError: + return None + + +def _current_file_hash( + track: LibraryTrack, + hasher: Callable[[Path], str], +) -> tuple[str, tuple[int, int, int, int, int]]: + try: + before = file_fingerprint(track.path) + except OSError as exc: + raise RuntimeError("The selected audio file is no longer available.") from exc + if track.content_fingerprint is not None and before != track.content_fingerprint: + raise RuntimeError("The selected audio file changed; refresh Library and choose again.") + try: + digest = hasher(track.path) + after = file_fingerprint(track.path) + except OSError as exc: + raise RuntimeError("The selected audio file could not be read.") from exc + if before != after: + raise RuntimeError("The selected audio file changed; refresh Library and choose again.") + if track.content_sha256 is not None and digest != track.content_sha256: + raise RuntimeError("The selected audio file changed; refresh Library and choose again.") + return digest, after + + +def _validate_track_scope(settings: Settings, track: LibraryTrack) -> None: + try: + root = Path(settings.music_dir).resolve() + audio = track.path.resolve(strict=True) + actual_relative = audio.relative_to(root) + except (OSError, ValueError) as exc: + raise RuntimeError("The selected track is outside the configured music library.") from exc + if ( + Path(track.reference).is_absolute() + or ".." in Path(track.reference).parts + or actual_relative != track.relative_path + or track.reference != str(track.relative_path) + ): + raise RuntimeError("The selected track path is no longer valid; refresh Library.") + + +def set_manual_identity( + settings: Settings, + track: LibraryTrack, + *, + song_id: Any, + api_name: str, + state_file: Path = STATE_FILE, + dependencies: ManualIdentityDependencies | None = None, +) -> ManualIdentityResult: + """Atomically bind a user-selected identity to the exact scanned audio.""" + + _validate_track_scope(settings, track) + name = str(api_name or "").strip() + if song_id is None or not name: + raise RuntimeError("The selected catalogue result has no usable identity.") + deps = dependencies or ManualIdentityDependencies() + state_path = Path(state_file) + original_bytes = _source_bytes(state_path) + state = deps.state_reader(state_path) + if _source_bytes(state_path) != original_bytes: + raise RuntimeError("Library state changed; refresh Library and choose again.") + files = state.setdefault("files", {}) + if not isinstance(files, dict): + raise RuntimeError("Library state records are malformed.") + + audio_hash, fingerprint = _current_file_hash(track, deps.hasher) + relative_paths = (track.relative_path,) + _, resolved = resolve_state_entry(files, track.relative_path, relative_paths) + exact = files.get(track.reference) + entry = dict(exact) if isinstance(exact, Mapping) else dict(resolved or {}) + before_identity = ( + entry.get("song_id"), + str(entry.get("api_name") or "").strip() or None, + is_identity_locked(entry), + ) + entry.update( + { + "sha256": audio_hash, + "song_id": song_id, + "api_name": name, + IDENTITY_SOURCE_FIELD: MANUAL_IDENTITY_SOURCE, + IDENTITY_LOCK_FIELD: True, + "updated": now_iso(), + } + ) + files[track.reference] = entry + + if _source_bytes(state_path) != original_bytes: + raise RuntimeError("Library state changed; no catalogue match was saved.") + try: + if file_fingerprint(track.path) != fingerprint: + raise RuntimeError + except (OSError, RuntimeError) as exc: + raise RuntimeError("The selected audio file changed; no catalogue match was saved.") from exc + + changed = before_identity != (song_id, name, True) + if changed: + deps.state_writer(state_path, state) + return ManualIdentityResult(track.reference, song_id, name, True, changed) + + +def unlock_manual_identity( + settings: Settings, + track: LibraryTrack, + *, + state_file: Path = STATE_FILE, + dependencies: ManualIdentityDependencies | None = None, +) -> ManualIdentityResult: + """Clear a manual identity so a later normal Sync may reconsider the track.""" + + _validate_track_scope(settings, track) + deps = dependencies or ManualIdentityDependencies() + state_path = Path(state_file) + original_bytes = _source_bytes(state_path) + state = deps.state_reader(state_path) + if _source_bytes(state_path) != original_bytes: + raise RuntimeError("Library state changed; refresh Library and try again.") + files = state.get("files", {}) + if not isinstance(files, dict): + raise RuntimeError("Library state records are malformed.") + _current_file_hash(track, deps.hasher) + relative_paths = (track.relative_path,) + _, resolved = resolve_state_entry(files, track.relative_path, relative_paths) + exact = files.get(track.reference) + entry = dict(exact) if isinstance(exact, Mapping) else dict(resolved or {}) + if not is_identity_locked(entry): + return ManualIdentityResult( + track.reference, + entry.get("song_id"), + str(entry.get("api_name") or "").strip() or None, + False, + False, + ) + for field in ("song_id", "api_name", IDENTITY_SOURCE_FIELD, IDENTITY_LOCK_FIELD): + entry.pop(field, None) + entry.pop("catalogue_checked_at", None) + entry["updated"] = now_iso() + files[track.reference] = entry + if _source_bytes(state_path) != original_bytes: + raise RuntimeError("Library state changed; the catalogue match was not unlocked.") + deps.state_writer(state_path, state) + return ManualIdentityResult(track.reference, None, None, False, True) diff --git a/src/juice_lyrics/services/metadata_audit.py b/src/juice_lyrics/services/metadata_audit.py new file mode 100644 index 0000000..2dfa497 --- /dev/null +++ b/src/juice_lyrics/services/metadata_audit.py @@ -0,0 +1,232 @@ +"""Read-only metadata repair proposals for one confirmed local track.""" + +from __future__ import annotations + +from collections.abc import Callable +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +import re + +from ..library.matching import named_variants, parse_version +from ..library.media import AudioMetadata, read_audio_metadata +from ..state import file_fingerprint +from .catalogue import SongDetails, get_song_details_by_id +from .library_status import LibraryTrack + + +class MetadataProposalConfidence(str, Enum): + CONFIDENT = "confident" + REVIEW = "review" + + +@dataclass(frozen=True, slots=True) +class MetadataProposal: + field: str + label: str + before: str | None + after: str + confidence: MetadataProposalConfidence + reason: str + + +@dataclass(frozen=True, slots=True) +class MetadataAudit: + track: LibraryTrack + local: AudioMetadata | None + catalogue: SongDetails | None + proposals: tuple[MetadataProposal, ...] + notes: tuple[str, ...] + error: str | None = None + + @property + def confident_count(self) -> int: + return sum( + item.confidence is MetadataProposalConfidence.CONFIDENT + for item in self.proposals + ) + + @property + def review_count(self) -> int: + return len(self.proposals) - self.confident_count + + +MetadataReader = Callable[[Path], AudioMetadata] +DetailsProvider = Callable[..., SongDetails | None] +FingerprintReader = Callable[[Path], tuple[int, int, int, int, int]] + + +def _clean(value: str | None) -> str | None: + text = str(value or "").strip() + return text or None + + +def _title_is_version_sensitive(before: str, after: str) -> bool: + patterns = { + "alternate": r"\b(?:alternate|alt)\b", + "extended": r"\bextended\b", + "mix": r"\bmix\b", + "remaster": r"\bremaster(?:ed)?\b", + "session": r"\b(?:recording\s+session|session)\b", + } + before_extra = {label for label, pattern in patterns.items() if re.search(pattern, before, re.I)} + after_extra = {label for label, pattern in patterns.items() if re.search(pattern, after, re.I)} + return ( + parse_version(before) != parse_version(after) + or named_variants(before) != named_variants(after) + or before_extra != after_extra + ) + + +def _proposal( + field: str, + label: str, + before: str | None, + after: str | None, +) -> MetadataProposal | None: + current = _clean(before) + expected = _clean(after) + if expected is None or current == expected: + return None + if current is None: + return MetadataProposal( + field, + label, + None, + expected, + MetadataProposalConfidence.CONFIDENT, + "The local field is missing and the confirmed catalogue record supplies it.", + ) + if field == "title" and _title_is_version_sensitive(current, expected): + reason = ( + "The titles describe different recording/version markers; preserve the local " + "value unless the user confirms this exact recording." + ) + else: + reason = ( + "The existing value is valid but differs from the catalogue; user review is " + "required before replacing it." + ) + return MetadataProposal( + field, + label, + current, + expected, + MetadataProposalConfidence.REVIEW, + reason, + ) + + +def build_metadata_audit( + track: LibraryTrack, + local: AudioMetadata, + catalogue: SongDetails, +) -> MetadataAudit: + """Compare trustworthy local tags with an already confirmed catalogue record.""" + + catalogue_artist = ", ".join(catalogue.artists) or None + proposals = tuple( + item + for item in ( + _proposal("title", "Title", local.title, catalogue.title), + _proposal("artist", "Artist", local.artist, catalogue_artist), + _proposal("album", "Album", local.album, catalogue.album), + _proposal( + "track_number", + "Track number", + local.track_number, + catalogue.track_number, + ), + ) + if item is not None + ) + notes: list[str] = [] + if not proposals: + notes.append("No repairable differences were found in supported fields.") + if not catalogue.artists: + notes.append("The catalogue record does not provide trustworthy artist metadata.") + if catalogue.album is None: + notes.append("The catalogue record does not provide trustworthy album metadata.") + if catalogue.track_number is None: + notes.append("The catalogue record does not provide a track number.") + if track.identity_locked: + notes.append("Catalogue identity was selected and locked manually.") + notes.append("Preview only — no files or application state were changed.") + return MetadataAudit(track, local, catalogue, proposals, tuple(notes)) + + +def audit_track_metadata( + settings: object, + track: LibraryTrack, + *, + details_provider: DetailsProvider = get_song_details_by_id, + metadata_reader: MetadataReader = read_audio_metadata, + fingerprint_reader: FingerprintReader = file_fingerprint, +) -> MetadataAudit: + """Load one selected track's metadata evidence without writing anything.""" + + if track.catalogue_id is None: + return MetadataAudit( + track, + None, + None, + (), + ( + "No confirmed catalogue identity is available; metadata was not guessed.", + "Choose a catalogue match before preparing a repair preview.", + ), + ) + try: + before = fingerprint_reader(track.path) + except Exception as exc: + return MetadataAudit( + track, + None, + None, + (), + ("Preview only — no files or application state were changed.",), + str(exc) or type(exc).__name__, + ) + if track.content_fingerprint is not None and before != track.content_fingerprint: + return MetadataAudit( + track, + None, + None, + (), + ("The local file no longer matches the current Library snapshot.",), + "Sync Library and try again.", + ) + try: + local = metadata_reader(track.path) + catalogue = details_provider(settings, track.catalogue_id) + after = fingerprint_reader(track.path) + except Exception as exc: + return MetadataAudit( + track, + None, + None, + (), + ("Preview only — no files or application state were changed.",), + str(exc) or type(exc).__name__, + ) + if before != after: + return MetadataAudit( + track, + local, + catalogue, + (), + ("The local file changed while metadata was being inspected.",), + "Refresh the Library and try again.", + ) + if catalogue is None or str(catalogue.song_id) != str(track.catalogue_id): + return MetadataAudit( + track, + local, + catalogue, + (), + ( + "The confirmed catalogue recording was unavailable or returned inconsistent data.", + "No metadata proposal was produced.", + ), + ) + return build_metadata_audit(track, local, catalogue) diff --git a/src/juice_lyrics/services/metadata_repair.py b/src/juice_lyrics/services/metadata_repair.py new file mode 100644 index 0000000..d8463a8 --- /dev/null +++ b/src/juice_lyrics/services/metadata_repair.py @@ -0,0 +1,608 @@ +"""Transactional metadata repair foundation; intentionally not exposed in the TUI.""" + +from __future__ import annotations + +import hashlib +import os +import shutil +import tempfile +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from mutagen.flac import FLAC +from mutagen.id3 import ID3, ID3NoHeaderError, TALB, TIT2, TPE1, TRCK +from mutagen.mp4 import MP4 + +from ..backup.manager import ( + backup_file, + make_backup_root, + now_iso, + restore_file, + write_manifest, +) +from ..config.settings import STATE_FILE, Settings +from ..library.media import AudioMetadata, is_flac, is_m4a, read_audio_metadata +from ..lyrics.sidecar import sidecar_lrc_path +from ..state import ( + file_fingerprint, + read_state_file, + resolve_state_entry, + sha256_file, + write_state_file, +) +from .manual_identity import is_identity_locked +from .metadata_audit import MetadataAudit, MetadataProposal + + +@dataclass(frozen=True, slots=True) +class MediaPreservation: + audio_payload_sha256: str + unrelated_tags: tuple[Any, ...] + + +@dataclass(frozen=True, slots=True) +class MetadataRepairPlan: + track_path: Path + music_dir: Path + reference: str + state_file: Path + state_key: str + state_digest: str + state_bytes: bytes + state: dict[str, Any] + selected: tuple[MetadataProposal, ...] + original_sha256: str + original_fingerprint: tuple[int, int, int, int, int] + preservation: MediaPreservation + sidecar_signature: tuple[bool, str | None] + catalogue_id: Any + identity_locked: bool + + +@dataclass(frozen=True, slots=True) +class MetadataRepairResult: + path: Path + fields: tuple[str, ...] + backup_path: Path + backup_root: Path + sha256_before: str + sha256_after: str + identity_lock_preserved: bool + + +@dataclass(slots=True) +class MetadataRepairDependencies: + state_reader: Callable[[Path], dict[str, Any]] = read_state_file + state_writer: Callable[[Path, Mapping[str, Any]], None] = write_state_file + hasher: Callable[[Path], str] = sha256_file + fingerprint_reader: Callable[[Path], tuple[int, int, int, int, int]] = file_fingerprint + backup_root_factory: Callable[[], Path] = make_backup_root + backup_writer: Callable[[Path, Path, Path], Path] = backup_file + manifest_writer: Callable[[Path, list[dict[str, Any]]], None] = write_manifest + restorer: Callable[[Path, Path], None] = restore_file + copier: Callable[[Path, Path], Any] = shutil.copy2 + replacer: Callable[[Path, Path], None] = os.replace + tag_writer: Callable[[Path, Mapping[str, str]], None] | None = None + metadata_reader: Callable[[Path], AudioMetadata] = read_audio_metadata + + +def _source_bytes(path: Path) -> bytes: + try: + return path.read_bytes() + except FileNotFoundError: + return b"" + + +def _digest_bytes(value: bytes) -> str: + return hashlib.sha256(value).hexdigest() + + +def _validate_scope(settings: Settings, path: Path, reference: str) -> Path: + try: + root = Path(settings.music_dir).resolve(strict=True) + resolved = Path(path).resolve(strict=True) + relative = resolved.relative_to(root) + except (OSError, ValueError) as exc: + raise RuntimeError("The selected track is outside the configured music library.") from exc + if Path(reference).is_absolute() or ".." in Path(reference).parts or str(relative) != reference: + raise RuntimeError("The selected track path is no longer valid; Sync Library first.") + return root + + +def _freeze(value: Any) -> Any: + if value is None or isinstance(value, (str, int, float, bool)): + return value + if isinstance(value, bytes): + return ("bytes", len(value), hashlib.sha256(value).hexdigest()) + if isinstance(value, Mapping): + return tuple(sorted((str(key), _freeze(item)) for key, item in value.items())) + if isinstance(value, (list, tuple)): + return tuple(_freeze(item) for item in value) + attributes = getattr(value, "__dict__", None) + if isinstance(attributes, dict): + return (type(value).__name__, _freeze(attributes)) + return (type(value).__name__, repr(value)) + + +def _mp3_audio_payload(data: bytes) -> bytes: + start = 0 + if len(data) >= 10 and data[:3] == b"ID3": + size_bytes = data[6:10] + if any(value & 0x80 for value in size_bytes): + raise RuntimeError("MP3 has an invalid ID3 size header.") + tag_size = sum(value << shift for value, shift in zip(size_bytes, (21, 14, 7, 0))) + start = 10 + tag_size + if data[5] & 0x10: + start += 10 + end = len(data) - 128 if len(data) >= 128 and data[-128:-125] == b"TAG" else len(data) + if start > end: + raise RuntimeError("MP3 tag boundaries are invalid.") + return data[start:end] + + +def _flac_audio_payload(data: bytes) -> bytes: + if not data.startswith(b"fLaC"): + raise RuntimeError("FLAC stream marker is missing.") + position = 4 + while True: + if position + 4 > len(data): + raise RuntimeError("FLAC metadata blocks are truncated.") + header = data[position] + length = int.from_bytes(data[position + 1 : position + 4], "big") + position += 4 + length + if position > len(data): + raise RuntimeError("FLAC metadata blocks are truncated.") + if header & 0x80: + return data[position:] + + +def _m4a_audio_payload(data: bytes) -> bytes: + position = 0 + payloads: list[bytes] = [] + while position + 8 <= len(data): + size = int.from_bytes(data[position : position + 4], "big") + atom = data[position + 4 : position + 8] + header_size = 8 + if size == 1: + if position + 16 > len(data): + raise RuntimeError("M4A atom header is truncated.") + size = int.from_bytes(data[position + 8 : position + 16], "big") + header_size = 16 + elif size == 0: + size = len(data) - position + if size < header_size or position + size > len(data): + raise RuntimeError("M4A atom boundaries are invalid.") + if atom == b"mdat": + payloads.append(data[position + header_size : position + size]) + position += size + if not payloads: + raise RuntimeError("M4A media payload is missing.") + return b"".join(payloads) + + +def _audio_payload_sha256(path: Path) -> str: + data = path.read_bytes() + if is_flac(path): + payload = _flac_audio_payload(data) + elif is_m4a(path): + payload = _m4a_audio_payload(data) + else: + payload = _mp3_audio_payload(data) + return hashlib.sha256(payload).hexdigest() + + +def _unrelated_tags(path: Path, selected_fields: frozenset[str]) -> tuple[Any, ...]: + if is_flac(path): + audio = FLAC(path) + keys = { + "title": "title", + "artist": "artist", + "album": "album", + "track_number": "tracknumber", + } + excluded = {keys[field] for field in selected_fields} + tags = tuple( + sorted( + (key.casefold(), _freeze(values)) + for key, values in (audio.tags or {}).items() + if key.casefold() not in excluded + ) + ) + pictures = tuple(_freeze(picture.write()) for picture in audio.pictures) + return ("FLAC", tags, pictures) + if is_m4a(path): + audio = MP4(path) + atoms = { + "title": "\xa9nam", + "artist": "\xa9ART", + "album": "\xa9alb", + "track_number": "trkn", + } + excluded = {atoms[field] for field in selected_fields} + tags = tuple( + sorted( + (key, _freeze(values)) + for key, values in (audio.tags or {}).items() + if key not in excluded + ) + ) + return ("M4A", tags) + try: + tags = ID3(path) + except ID3NoHeaderError: + tags = ID3() + frames = { + "title": "TIT2", + "artist": "TPE1", + "album": "TALB", + "track_number": "TRCK", + } + excluded = {frames[field] for field in selected_fields} + preserved = tuple( + sorted( + (key, _freeze(frame)) + for key, frame in tags.items() + if key.split(":", 1)[0] not in excluded + ) + ) + data = path.read_bytes() + id3v1 = _unrelated_id3v1(data, selected_fields) + return ("MP3", preserved, _freeze(id3v1)) + + +def _unrelated_id3v1(data: bytes, selected_fields: frozenset[str]) -> bytes: + """Mask only selected ID3v1 fields while preserving the rest byte-for-byte.""" + + if len(data) < 128 or data[-128:-125] != b"TAG": + return b"" + tag = bytearray(data[-128:]) + ranges = { + "title": (3, 33), + "artist": (33, 63), + "album": (63, 93), + } + for field, (start, end) in ranges.items(): + if field in selected_fields: + tag[start:end] = b"\0" * (end - start) + if "track_number" in selected_fields and tag[125] == 0: + tag[126] = 0 + return bytes(tag) + + +def inspect_media_preservation( + path: Path, + selected_fields: frozenset[str], +) -> MediaPreservation: + return MediaPreservation( + _audio_payload_sha256(path), + _unrelated_tags(path, selected_fields), + ) + + +def _parse_track_number(value: str) -> tuple[int, int]: + parts = value.strip().split("/", 1) + try: + number = int(parts[0]) + total = int(parts[1]) if len(parts) > 1 and parts[1].strip() else 0 + except ValueError as exc: + raise RuntimeError("The proposed track number is not valid.") from exc + if number <= 0 or total < 0: + raise RuntimeError("The proposed track number is not valid.") + return number, total + + +def _preserve_unselected_id3v1( + path: Path, + original: bytes, + selected_fields: frozenset[str], +) -> None: + """Restore unselected ID3v1 bytes that Mutagen cannot round-trip itself.""" + + if len(original) != 128 or original[:3] != b"TAG": + return + data = path.read_bytes() + if len(data) < 128 or data[-128:-125] != b"TAG": + raise RuntimeError("MP3 ID3v1 metadata disappeared during the tag write.") + updated = bytearray(data[-128:]) + ranges = { + "title": (3, 33), + "artist": (33, 63), + "album": (63, 93), + } + for field, (start, end) in ranges.items(): + if field not in selected_fields: + updated[start:end] = original[start:end] + updated[93:97] = original[93:97] # year is not a supported repair field + if "track_number" in selected_fields and original[125] == 0: + updated[97:125] = original[97:125] + else: + updated[97:127] = original[97:127] + updated[127] = original[127] # genre is not a supported repair field + if updated != data[-128:]: + with path.open("r+b") as handle: + handle.seek(-128, os.SEEK_END) + handle.write(updated) + + +def write_metadata_fields(path: Path, values: Mapping[str, str]) -> None: + """Write only supported common fields to a disposable working copy.""" + + if is_flac(path): + audio = FLAC(path) + keys = { + "title": "TITLE", + "artist": "ARTIST", + "album": "ALBUM", + "track_number": "TRACKNUMBER", + } + for field, value in values.items(): + audio[keys[field]] = [value] + audio.save() + return + if is_m4a(path): + audio = MP4(path) + if audio.tags is None: + audio.add_tags() + atoms = {"title": "\xa9nam", "artist": "\xa9ART", "album": "\xa9alb"} + for field, value in values.items(): + if field == "track_number": + audio["trkn"] = [_parse_track_number(value)] + else: + audio[atoms[field]] = [value] + audio.save() + return + source = path.read_bytes() + original_id3v1 = ( + source[-128:] + if len(source) >= 128 and source[-128:-125] == b"TAG" + else b"" + ) + try: + tags = ID3(path) + except ID3NoHeaderError: + tags = ID3() + frames = {"title": TIT2, "artist": TPE1, "album": TALB, "track_number": TRCK} + for field, value in values.items(): + tags.delall(frames[field].__name__) + tags.add(frames[field](encoding=3, text=[value])) + version = 3 if getattr(tags, "version", None) and tags.version[0] == 3 else 4 + tags.save(path, v2_version=version) + _preserve_unselected_id3v1(path, original_id3v1, frozenset(values)) + + +def _sidecar_signature(path: Path) -> tuple[bool, str | None]: + sidecar = sidecar_lrc_path(path) + if not sidecar.exists(): + return False, None + return True, sha256_file(sidecar) + + +def _metadata_value(metadata: AudioMetadata, field: str) -> str | None: + value = getattr(metadata, field) + return str(value).strip() if value is not None else None + + +def _field_matches(field: str, actual: str | None, expected: str) -> bool: + if actual is None: + return False + if field == "track_number": + try: + return _parse_track_number(actual) == _parse_track_number(expected) + except RuntimeError: + return False + return actual == expected + + +def plan_metadata_repair( + settings: Settings, + audit: MetadataAudit, + selected_fields: tuple[str, ...], + *, + state_file: Path = STATE_FILE, + dependencies: MetadataRepairDependencies | None = None, +) -> MetadataRepairPlan: + """Pin an explicit subset of previewed fields without modifying anything.""" + + deps = dependencies or MetadataRepairDependencies() + track = audit.track + root = _validate_scope(settings, track.path, track.reference) + if audit.catalogue is None or track.catalogue_id is None: + raise RuntimeError("A confirmed catalogue identity is required for metadata repair.") + if str(audit.catalogue.song_id) != str(track.catalogue_id): + raise RuntimeError("Catalogue evidence no longer matches the selected identity.") + proposal_by_field = {proposal.field: proposal for proposal in audit.proposals} + if not selected_fields or len(set(selected_fields)) != len(selected_fields): + raise RuntimeError("Select at least one metadata field exactly once.") + try: + selected = tuple(proposal_by_field[field] for field in selected_fields) + except KeyError as exc: + raise RuntimeError("A selected field is not present in the reviewed preview.") from exc + + fingerprint = deps.fingerprint_reader(track.path) + if track.content_fingerprint is not None and fingerprint != track.content_fingerprint: + raise RuntimeError("The selected audio changed; Sync Library and preview again.") + digest = deps.hasher(track.path) + if track.content_sha256 is not None and digest != track.content_sha256: + raise RuntimeError("The selected audio changed; Sync Library and preview again.") + if deps.fingerprint_reader(track.path) != fingerprint: + raise RuntimeError("The selected audio changed while the plan was prepared.") + + state_path = Path(state_file) + state_bytes = _source_bytes(state_path) + state = deps.state_reader(state_path) + files = state.get("files", {}) + if not isinstance(files, Mapping): + raise RuntimeError("Library state records are malformed.") + state_key, resolved = resolve_state_entry(files, track.relative_path, (track.relative_path,)) + if state_key is None or not isinstance(resolved, Mapping): + raise RuntimeError("Current state for the selected track is unavailable.") + if resolved.get("sha256") != digest or str(resolved.get("song_id")) != str(track.catalogue_id): + raise RuntimeError("Library state no longer matches the reviewed audio and identity.") + locked = is_identity_locked(resolved) + if track.identity_locked != locked: + raise RuntimeError("Catalogue lock state changed; refresh and preview again.") + selected_names = frozenset(proposal.field for proposal in selected) + return MetadataRepairPlan( + track.path, + root, + track.reference, + state_path, + state_key, + _digest_bytes(state_bytes), + state_bytes, + state, + selected, + digest, + fingerprint, + inspect_media_preservation(track.path, selected_names), + _sidecar_signature(track.path), + track.catalogue_id, + locked, + ) + + +def _revalidate(plan: MetadataRepairPlan, deps: MetadataRepairDependencies) -> None: + if _digest_bytes(_source_bytes(plan.state_file)) != plan.state_digest: + raise RuntimeError("Library state changed after preview; no metadata was applied.") + if deps.fingerprint_reader(plan.track_path) != plan.original_fingerprint: + raise RuntimeError("The selected audio changed after preview; no metadata was applied.") + if deps.hasher(plan.track_path) != plan.original_sha256: + raise RuntimeError("The selected audio changed after preview; no metadata was applied.") + selected = frozenset(proposal.field for proposal in plan.selected) + if inspect_media_preservation(plan.track_path, selected) != plan.preservation: + raise RuntimeError("The selected audio metadata changed after preview.") + if _sidecar_signature(plan.track_path) != plan.sidecar_signature: + raise RuntimeError("The adjacent lyrics changed after preview; no metadata was applied.") + + +def execute_metadata_repair( + plan: MetadataRepairPlan, + *, + confirmed: bool = False, + dependencies: MetadataRepairDependencies | None = None, +) -> MetadataRepairResult: + """Apply a pinned plan through backup, temporary verification, and rollback.""" + + if not confirmed: + raise RuntimeError("Metadata repair requires explicit confirmation.") + deps = dependencies or MetadataRepairDependencies() + _revalidate(plan, deps) + backup_root = deps.backup_root_factory() + backup = deps.backup_writer(plan.track_path, backup_root, plan.music_dir) + deps.manifest_writer( + backup_root, + [ + { + "file": str(plan.track_path), + "sha256_before": plan.original_sha256, + "operation": "metadata_repair", + "fields": [proposal.field for proposal in plan.selected], + } + ], + ) + + descriptor, temporary_name = tempfile.mkstemp( + dir=plan.track_path.parent, + prefix=f".{plan.track_path.name}.", + suffix=plan.track_path.suffix, + ) + os.close(descriptor) + temporary = Path(temporary_name) + replaced = False + state_candidate: dict[str, Any] | None = None + new_sha256: str | None = None + try: + deps.copier(plan.track_path, temporary) + values = {proposal.field: proposal.after for proposal in plan.selected} + (deps.tag_writer or write_metadata_fields)(temporary, values) + with temporary.open("rb") as handle: + os.fsync(handle.fileno()) + selected = frozenset(values) + metadata = deps.metadata_reader(temporary) + for field, expected in values.items(): + if not _field_matches(field, _metadata_value(metadata, field), expected): + raise RuntimeError(f"Temporary metadata verification failed for {field}.") + if inspect_media_preservation(temporary, selected) != plan.preservation: + raise RuntimeError("Metadata write changed audio or unrelated tags.") + _revalidate(plan, deps) + deps.replacer(temporary, plan.track_path) + replaced = True + + metadata = deps.metadata_reader(plan.track_path) + for field, expected in values.items(): + if not _field_matches(field, _metadata_value(metadata, field), expected): + raise RuntimeError(f"Final metadata verification failed for {field}.") + if inspect_media_preservation(plan.track_path, selected) != plan.preservation: + raise RuntimeError("Final verification found changed audio or unrelated tags.") + if _sidecar_signature(plan.track_path) != plan.sidecar_signature: + raise RuntimeError("The adjacent lyrics changed during metadata repair.") + new_sha256 = deps.hasher(plan.track_path) + + if _digest_bytes(_source_bytes(plan.state_file)) != plan.state_digest: + raise RuntimeError("Library state changed during metadata repair.") + updated = dict(plan.state) + files = dict(updated.get("files", {})) + entry = dict(files.get(plan.state_key, {})) + if str(entry.get("song_id")) != str(plan.catalogue_id): + raise RuntimeError("Catalogue identity changed during metadata repair.") + if plan.identity_locked and not is_identity_locked(entry): + raise RuntimeError("Manual catalogue lock changed during metadata repair.") + entry["sha256"] = new_sha256 + entry["updated"] = now_iso() + files[plan.state_key] = entry + updated["files"] = files + state_candidate = updated + deps.state_writer(plan.state_file, updated) + return MetadataRepairResult( + plan.track_path, + tuple(values), + backup, + backup_root, + plan.original_sha256, + new_sha256, + plan.identity_locked, + ) + except BaseException as exc: + if not replaced and not temporary.exists(): + # os.replace may have completed just before an asynchronous + # interruption was delivered to Python. + replaced = True + if replaced: + try: + deps.restorer(backup, plan.track_path) + if deps.hasher(plan.track_path) != plan.original_sha256: + raise RuntimeError("restored file hash does not match the original") + except Exception as restore_error: + raise RuntimeError( + f"Metadata repair failed and automatic rollback failed: {restore_error}" + ) from exc + if state_candidate is not None and new_sha256 is not None: + current = deps.state_reader(plan.state_file) + expected = dict(state_candidate) + current_without_timestamp = dict(current) + expected.pop("updated", None) + current_without_timestamp.pop("updated", None) + if current_without_timestamp == expected: + _atomic_restore_bytes(plan.state_file, plan.state_bytes) + raise + finally: + temporary.unlink(missing_ok=True) + + +def _atomic_restore_bytes(path: Path, content: bytes) -> None: + descriptor, temporary_name = tempfile.mkstemp( + dir=path.parent, + prefix=f".{path.name}.", + suffix=".rollback", + ) + temporary = Path(temporary_name) + try: + with os.fdopen(descriptor, "wb") as handle: + handle.write(content) + handle.flush() + os.fsync(handle.fileno()) + os.replace(temporary, path) + finally: + temporary.unlink(missing_ok=True) diff --git a/src/juice_lyrics/services/missing_library.py b/src/juice_lyrics/services/missing_library.py new file mode 100644 index 0000000..9971bdf --- /dev/null +++ b/src/juice_lyrics/services/missing_library.py @@ -0,0 +1,132 @@ +from __future__ import annotations + +from collections.abc import Callable +from dataclasses import dataclass +from enum import Enum +from typing import Any + +from ..config.settings import Settings +from .catalogue import CataloguePage, CatalogueSearchResult, search_catalogue_page +from .library_status import LibraryMatchStatus, LibrarySnapshot + + +CataloguePageProvider = Callable[..., CataloguePage] + + +class CatalogueCoverage(str, Enum): + COMPLETE = "complete" + PARTIAL = "partial" + UNAVAILABLE = "unavailable" + + +@dataclass(frozen=True, slots=True) +class MissingLibraryReport: + """Identity-based comparison of loaded catalogue records and local media.""" + + recordings: tuple[CatalogueSearchResult, ...] + owned_ids: frozenset[str] + local_unknown_count: int + loaded_recording_count: int + catalogue_total_count: int | None + pages_loaded: int + coverage: CatalogueCoverage + unidentifiable_catalogue_count: int = 0 + error: str | None = None + + @property + def missing_count(self) -> int: + return len(self.recordings) + + @property + def complete(self) -> bool: + return self.coverage is CatalogueCoverage.COMPLETE + + +def get_missing_library( + settings: Settings, + snapshot: LibrarySnapshot, + *, + page_provider: CataloguePageProvider = search_catalogue_page, + page_size: int = 100, + max_pages: int = 200, +) -> MissingLibraryReport: + """Load the paginated catalogue and compare only stable recording identities. + + Valid cached pages are naturally reused by ``search_catalogue_page``. This + function never reads or writes media/state and deliberately does not infer + ownership from titles. + """ + + owned_ids = frozenset( + str(track.catalogue_id) + for track in snapshot.tracks + if track.match_status is LibraryMatchStatus.MATCHED + and track.catalogue_id is not None + ) + unknown_count = sum( + track.match_status is LibraryMatchStatus.UNMATCHED + or track.catalogue_id is None + for track in snapshot.tracks + ) + records: dict[str, CatalogueSearchResult] = {} + unidentifiable = 0 + page_number = 1 + pages_loaded = 0 + total_count: int | None = None + terminal_page = False + seen_pages: set[int] = set() + error: str | None = None + + while page_number <= max_pages: + if page_number in seen_pages: + error = "Catalogue pagination repeated a page." + break + seen_pages.add(page_number) + try: + page = page_provider( + settings, + "", + page=page_number, + page_size=page_size, + refresh=False, + ) + except Exception as exc: + error = str(exc) or type(exc).__name__ + break + pages_loaded += 1 + total_count = max(total_count or 0, page.total_count) + for item in page.results: + if item.song_id is None: + unidentifiable += 1 + continue + records.setdefault(str(item.song_id), item) + if page.next_page is None: + terminal_page = True + break + page_number = page.next_page + else: + error = f"Catalogue pagination exceeded the {max_pages}-page safety limit." + + if pages_loaded == 0: + coverage = CatalogueCoverage.UNAVAILABLE + elif error or not terminal_page or unidentifiable: + coverage = CatalogueCoverage.PARTIAL + else: + coverage = CatalogueCoverage.COMPLETE + + missing = tuple( + item + for song_id, item in records.items() + if song_id not in owned_ids + ) + return MissingLibraryReport( + recordings=missing, + owned_ids=owned_ids, + local_unknown_count=unknown_count, + loaded_recording_count=len(records), + catalogue_total_count=total_count, + pages_loaded=pages_loaded, + coverage=coverage, + unidentifiable_catalogue_count=unidentifiable, + error=error, + ) diff --git a/src/juice_lyrics/services/settings_snapshot.py b/src/juice_lyrics/services/settings_snapshot.py new file mode 100644 index 0000000..582153e --- /dev/null +++ b/src/juice_lyrics/services/settings_snapshot.py @@ -0,0 +1,284 @@ +from __future__ import annotations + +import shutil +import tomllib +import re +from collections.abc import Callable +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +from typing import TypeAlias + +from .. import __version__ +from ..config.settings import ( + ACQUISITION_JOBS_FILE, + BACKUP_DIR, + CACHE_DIR, + CONFIG_FILE, + DEFAULT_API_BASE, + DEFAULT_CACHE_TTL_HOURS, + DEFAULT_DELAY, + DEFAULT_DURATION_TOLERANCE, + DEFAULT_MUSIC_DIR, + DEFAULT_RMPC_CONFIG, + DEFAULT_TIMEOUT, + STATE_FILE, + Settings, +) + +SettingScalar: TypeAlias = str | int | float | Path +ExecutableFinder = Callable[[str], str | None] + + +class SettingsSource(str, Enum): + DEFAULT = "default" + CONFIG = "config" + RUNTIME_OVERRIDE = "runtime_override" + + +class IntegrationStatus(str, Enum): + DETECTED_CONFIGURED = "detected_configured" + DETECTED_NOT_CONFIGURED = "detected_not_configured" + NOT_DETECTED = "not_detected" + UNABLE_TO_INSPECT = "unable_to_inspect" + + +@dataclass(frozen=True, slots=True) +class SettingValue: + key: str + label: str + value: SettingScalar + default_value: SettingScalar + source: SettingsSource + + +@dataclass(frozen=True, slots=True) +class SettingsPath: + key: str + label: str + path: Path + exists: bool + warning: str | None = None + + +@dataclass(frozen=True, slots=True) +class IntegrationSnapshot: + status: IntegrationStatus + executable: Path | None + config_path: Path + config_exists: bool + config_has_lyrics_support: bool + detail: str + + +@dataclass(frozen=True, slots=True) +class SettingsSnapshot: + config_path: Path + config_exists: bool + values: tuple[SettingValue, ...] + paths: tuple[SettingsPath, ...] + rmpc: IntegrationSnapshot + application_version: str + limitations: tuple[str, ...] + warnings: tuple[str, ...] = () + + +_SETTING_SPECS = ( + ("music_dir", "Music directory", DEFAULT_MUSIC_DIR), + ("api_base", "API base URL", DEFAULT_API_BASE), + ("timeout", "Request timeout", DEFAULT_TIMEOUT), + ("delay", "Request delay", DEFAULT_DELAY), + ("duration_tolerance", "Duration tolerance", DEFAULT_DURATION_TOLERANCE), + ("cache_ttl_hours", "Cache TTL", DEFAULT_CACHE_TTL_HOURS), +) + + +def _normalized_config_value(key: str, value: object) -> SettingScalar: + if key == "music_dir": + return Path(str(value)).expanduser() + if key == "api_base": + return str(value).rstrip("/") + if key == "timeout": + return int(value) + return float(value) + + +def _same_value(left: SettingScalar, right: SettingScalar) -> bool: + return left == right + + +def _source_for( + key: str, + effective: SettingScalar, + default: SettingScalar, + config: dict[str, object], +) -> SettingsSource: + if key in config: + configured = _normalized_config_value(key, config[key]) + return SettingsSource.CONFIG if _same_value(effective, configured) else SettingsSource.RUNTIME_OVERRIDE + return SettingsSource.DEFAULT if _same_value(effective, default) else SettingsSource.RUNTIME_OVERRIDE + + +def _inspect_path(key: str, label: str, path: Path) -> SettingsPath: + try: + exists = path.exists() + warning = None + except OSError as exc: + exists = False + warning = str(exc) or type(exc).__name__ + return SettingsPath(key, label, path, exists, warning) + + +def _rmpc_configured(text: str, music_root: Path) -> bool: + directory = re.search( + r'(?im)^\s*lyrics_dir\s*:\s*some\s*\(\s*"([^"]+)"\s*\)', + text, + ) + configured_directory = ( + Path(directory.group(1).replace(r'\"', '"').replace(r"\\", "\\")).expanduser() + if directory is not None + else None + ) + covers_music = False + if configured_directory is not None: + try: + music_root.expanduser().relative_to(configured_directory) + covers_music = True + except ValueError: + pass + return covers_music and ( + re.search(r"(?im)^\s*enable_lyrics_index\s*:\s*true\s*,?", text) is not None + and re.search(r"(?im)^\s*enable_lyrics_hot_reload\s*:\s*true\s*,?", text) is not None + ) + + +def _inspect_rmpc( + config_path: Path, + music_root: Path, + executable_finder: ExecutableFinder, +) -> IntegrationSnapshot: + try: + executable_raw = executable_finder("rmpc") + executable = Path(executable_raw) if executable_raw else None + config_exists = config_path.exists() + configured = False + if config_exists: + configured = _rmpc_configured( + config_path.read_text(encoding="utf-8"), + music_root, + ) + except Exception as exc: + return IntegrationSnapshot( + IntegrationStatus.UNABLE_TO_INSPECT, + None, + config_path, + False, + False, + f"Unable to inspect rmpc: {exc}", + ) + if executable is None: + status = IntegrationStatus.NOT_DETECTED + detail = "rmpc was not found in PATH." + elif configured: + status = IntegrationStatus.DETECTED_CONFIGURED + detail = "rmpc is detected and indexes the music tree containing sidecar lyrics." + else: + status = IntegrationStatus.DETECTED_NOT_CONFIGURED + detail = "rmpc is detected, but its lyrics directory does not cover the music tree." + return IntegrationSnapshot(status, executable, config_path, config_exists, configured, detail) + + +def get_settings_snapshot( + settings: Settings, + *, + config_path: Path = CONFIG_FILE, + cache_dir: Path = CACHE_DIR, + state_file: Path = STATE_FILE, + backup_dir: Path = BACKUP_DIR, + jobs_file: Path = ACQUISITION_JOBS_FILE, + rmpc_config_path: Path = DEFAULT_RMPC_CONFIG, + executable_finder: ExecutableFinder = shutil.which, +) -> SettingsSnapshot: + """Inspect effective settings and environment without creating or changing files.""" + + config_path = Path(config_path) + config: dict[str, object] = {} + try: + config_exists = config_path.exists() + if config_exists: + parsed = tomllib.loads(config_path.read_text(encoding="utf-8")) + if not isinstance(parsed, dict): + raise ValueError("configuration root must be a table") + config = parsed + for key, _, _ in _SETTING_SPECS: + if key in config: + _normalized_config_value(key, config[key]) + except Exception as exc: + raise RuntimeError(f"Could not read config {config_path}: {exc}") from exc + + effective_values = {key: getattr(settings, key) for key, _, _ in _SETTING_SPECS} + values_list = [ + SettingValue( + key, + label, + effective_values[key], + default, + _source_for(key, effective_values[key], default, config), + ) + for key, label, default in _SETTING_SPECS + ] + values_list.append( + SettingValue( + "external_lyrics", + "External lyrics", + "Beside each song (.lrc)", + "Beside each song (.lrc)", + SettingsSource.DEFAULT, + ) + ) + if "lyrics_dir" in config or settings.lyrics_dir_explicit: + values_list.append( + SettingValue( + "lyrics_dir", + "Legacy lyrics_dir (deprecated)", + Path(settings.lyrics_dir).expanduser(), + Path(settings.lyrics_dir).expanduser(), + SettingsSource.CONFIG if "lyrics_dir" in config else SettingsSource.RUNTIME_OVERRIDE, + ) + ) + values = tuple(values_list) + paths = tuple( + _inspect_path(key, label, Path(path)) + for key, label, path in ( + ("music", "Music library", settings.music_dir), + ("cache", "API cache", cache_dir), + ("state", "Library state", state_file), + ("backups", "Backups", backup_dir), + ("jobs", "Acquisition jobs", jobs_file), + ("config", "Application config", config_path), + ("rmpc_config", "rmpc config", rmpc_config_path), + ) + ) + warnings = tuple( + f"{item.label}: {item.warning}" for item in paths if item.warning is not None + ) + return SettingsSnapshot( + config_path=config_path, + config_exists=config_exists, + values=values, + paths=paths, + rmpc=_inspect_rmpc( + Path(rmpc_config_path), + Path(settings.music_dir), + executable_finder, + ), + application_version=__version__, + limitations=( + "Local library scanning supports MP3, FLAC, and M4A files.", + "FLAC and M4A timing use adjacent LRC; embedded lyrics are plain text.", + "Settings inspection remains read-only in the TUI.", + "Library sync execution remains CLI-only.", + "Configuration changes remain CLI-only.", + ), + warnings=warnings, + ) diff --git a/src/juice_lyrics/services/shell_completion.py b/src/juice_lyrics/services/shell_completion.py new file mode 100644 index 0000000..e5d397a --- /dev/null +++ b/src/juice_lyrics/services/shell_completion.py @@ -0,0 +1,322 @@ +from __future__ import annotations + +import argparse +from dataclasses import dataclass +import shlex + + +@dataclass(frozen=True, slots=True) +class CompletionOption: + names: tuple[str, ...] + description: str + takes_value: bool + choices: tuple[str, ...] = () + path_value: bool = False + + +@dataclass(frozen=True, slots=True) +class CompletionNode: + path: tuple[str, ...] + description: str + options: tuple[CompletionOption, ...] + positional_choices: tuple[str, ...] + children: tuple["CompletionNode", ...] + + +_PATH_DESTINATIONS = { + "path", + "save_report", + "config", + "lyrics_dir", + "destination", + "manifest", + "manifest_path", + "backup", +} + + +def _description(value: object) -> str: + if value is None or value is argparse.SUPPRESS: + return "" + return " ".join(str(value).split()) + + +def _takes_value(action: argparse.Action) -> bool: + return not isinstance( + action, + ( + argparse._HelpAction, + argparse._StoreTrueAction, + argparse._StoreFalseAction, + argparse._VersionAction, + argparse._CountAction, + ), + ) and action.nargs != 0 + + +def completion_tree(parser: argparse.ArgumentParser) -> CompletionNode: + """Build a small immutable completion model from the real argparse tree.""" + + def visit( + current: argparse.ArgumentParser, + path: tuple[str, ...], + description: str, + ) -> CompletionNode: + options: list[CompletionOption] = [] + positional_choices: list[str] = [] + children: list[CompletionNode] = [] + for action in current._actions: + if isinstance(action, argparse._SubParsersAction): + help_by_name = { + choice.dest: _description(choice.help) + for choice in action._choices_actions + } + for name, child_parser in action.choices.items(): + children.append( + visit(child_parser, (*path, name), help_by_name.get(name, "")) + ) + continue + if action.option_strings: + options.append( + CompletionOption( + tuple(action.option_strings), + _description(action.help), + _takes_value(action), + tuple(str(item) for item in action.choices) + if action.choices + else (), + action.dest in _PATH_DESTINATIONS, + ) + ) + elif action.choices: + positional_choices.extend(str(item) for item in action.choices) + return CompletionNode( + path, + description, + tuple(options), + tuple(positional_choices), + tuple(children), + ) + + return visit(parser, (), _description(parser.description)) + + +def _flatten(root: CompletionNode) -> tuple[CompletionNode, ...]: + values = [root] + for child in root.children: + values.extend(_flatten(child)) + return tuple(values) + + +def _all_option_names(node: CompletionNode) -> tuple[str, ...]: + return tuple(name for option in node.options for name in option.names) + + +def _bash(root: CompletionNode) -> str: + nodes = _flatten(root) + root_commands = "|".join(child.path[-1] for child in root.children) + lines = [ + "# bash completion for 999 (generated from the argparse command tree)", + "_999_complete() {", + " local cur prev path first second command_index i", + " COMPREPLY=()", + " cur=\"${COMP_WORDS[COMP_CWORD]}\"", + " prev=\"${COMP_WORDS[COMP_CWORD-1]}\"", + " first=", + " second=", + " command_index=0", + " for ((i=1; i str: + return value.replace("'", "'\\''").replace(":", "\\:") + + +def _zsh(root: CompletionNode) -> str: + nodes = _flatten(root) + root_commands = "|".join(child.path[-1] for child in root.children) + lines = [ + "#compdef 999 juice-lyrics", + "# zsh completion for 999 (generated from the argparse command tree)", + "_999() {", + " local path= first= second=", + " integer command_index=0 i", + " for ((i=2; i str: + return value.replace("\\", "\\\\").replace("'", "\\'") + + +def _fish_condition(path: tuple[str, ...], *, exact: bool) -> str: + function = "__999_at_path" if exact else "__999_in_path" + return function + (" " + " ".join(shlex.quote(item) for item in path) if path else "") + + +def _fish(root: CompletionNode) -> str: + root_commands = " ".join(child.path[-1] for child in root.children) + lines = [ + "# fish completion for 999 (generated from the argparse command tree)", + "function __999_in_path", + " set -l words (commandline -opc)", + " test (count $argv) -gt 0; or return 0", + " for start in (seq 2 (count $words))", + " set -l matched 1", + " for i in (seq (count $argv))", + " set -l word_index (math $start + $i - 1)", + " if test $word_index -gt (count $words); or test \"$words[$word_index]\" != \"$argv[$i]\"", + " set matched 0", + " break", + " end", + " end", + " test $matched -eq 1; and return 0", + " end", + " return 1", + "end", + "function __999_at_path", + " set -l words (commandline -opc)", + " if test (count $argv) -eq 0", + f" for command in {root_commands}", + " contains -- $command $words[2..-1]; and return 1", + " end", + " return 0", + " end", + " __999_in_path $argv; or return 1", + " test \"$words[-1]\" = \"$argv[-1]\"", + "end", + ] + for command in ("999", "juice-lyrics"): + for node in _flatten(root): + at_condition = _fish_condition(node.path, exact=True) + option_condition = _fish_condition(node.path, exact=bool(node.children) or not node.path) + for child in node.children: + description = _fish_escape(child.description or "command") + lines.append(f"complete -c {command} -f -n '{at_condition}' -a '{_fish_escape(child.path[-1])}' -d '{description}'") + for choice in node.positional_choices: + lines.append(f"complete -c {command} -f -n '{at_condition}' -a '{_fish_escape(choice)}'") + for option in node.options: + pieces = [f"complete -c {command}", f"-n '{option_condition}'"] + for name in option.names: + pieces.append(("-l " + name[2:]) if name.startswith("--") else ("-s " + name[1:])) + if option.description: + pieces.append(f"-d '{_fish_escape(option.description)}'") + if option.takes_value: + pieces.append("-r") + if option.choices: + pieces.extend(("-f", f"-a '{_fish_escape(' '.join(option.choices))}'")) + lines.append(" ".join(pieces)) + lines.append("") + return "\n".join(lines) + + +def generate_completion(parser: argparse.ArgumentParser, shell: str) -> str: + """Generate a completion script without reading settings or application data.""" + + root = completion_tree(parser) + if shell == "bash": + return _bash(root) + if shell == "zsh": + return _zsh(root) + if shell == "fish": + return _fish(root) + raise ValueError(f"Unsupported shell: {shell}") diff --git a/src/juice_lyrics/services/state_maintenance.py b/src/juice_lyrics/services/state_maintenance.py new file mode 100644 index 0000000..9b62653 --- /dev/null +++ b/src/juice_lyrics/services/state_maintenance.py @@ -0,0 +1,144 @@ +from __future__ import annotations + +import hashlib +import json +import shutil +from collections.abc import Callable, Mapping +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from ..config.settings import STATE_FILE, Settings +from ..state import write_state_file + + +@dataclass(frozen=True, slots=True) +class StaleStatePlan: + state_file: Path + music_dir: Path + stale_keys: tuple[str, ...] + source_digest: str + state: dict[str, Any] + + @property + def stale_count(self) -> int: + return len(self.stale_keys) + + +@dataclass(frozen=True, slots=True) +class StateCleanupResult: + removed_count: int + backup_path: Path | None + + +def _is_outside(path: Path, root: Path) -> bool: + try: + path.resolve(strict=False).relative_to(root.resolve(strict=False)) + except ValueError: + return True + return False + + +def _is_pytest_temp_path(path: Path) -> bool: + if not path.is_absolute(): + return False + parts = path.parts + return ( + len(parts) >= 3 + and parts[1] == "tmp" + and any(part.startswith("pytest-") for part in parts[2:]) + ) + + +def _absolute_media_paths(key: str, entry: object) -> tuple[Path, ...]: + paths: list[Path] = [] + key_path = Path(key) + if key_path.is_absolute(): + paths.append(key_path) + if isinstance(entry, Mapping): + for field in ("audio_path", "media_path", "file", "path"): + raw = entry.get(field) + if isinstance(raw, str) and Path(raw).is_absolute(): + paths.append(Path(raw)) + return tuple(paths) + + +def _is_stale_record(key: str, entry: object, music_dir: Path) -> bool: + media_paths = _absolute_media_paths(key, entry) + if any(not path.exists() and _is_outside(path, music_dir) for path in media_paths): + return True + + # Preserve ordinary missing relative records because they may represent a + # track moved within the library. A missing pytest-temporary LRC is useful + # corroboration only when that relative media record is also absent. + if isinstance(entry, Mapping) and not Path(key).is_absolute(): + raw_lrc = entry.get("lrc") + lrc_path = Path(raw_lrc) if isinstance(raw_lrc, str) else None + media_path = music_dir / key + if ( + lrc_path is not None + and _is_pytest_temp_path(lrc_path) + and not lrc_path.exists() + and not media_path.exists() + ): + return True + return False + + +def plan_stale_state_cleanup( + settings: Settings, + *, + state_file: Path = STATE_FILE, +) -> StaleStatePlan: + source = Path(state_file) + raw = source.read_bytes() if source.exists() else b"" + try: + value = json.loads(raw.decode("utf-8")) if raw else {"files": {}, "updated": None} + except (UnicodeError, json.JSONDecodeError): + value = {"files": {}, "updated": None} + state = value if isinstance(value, dict) else {"files": {}, "updated": None} + files = state.get("files", {}) + stale_keys = ( + tuple( + key + for key, entry in files.items() + if isinstance(key, str) + and _is_stale_record(key, entry, Path(settings.music_dir)) + ) + if isinstance(files, dict) + else () + ) + return StaleStatePlan( + source, + Path(settings.music_dir), + tuple(stale_keys), + hashlib.sha256(raw).hexdigest(), + state, + ) + + +def execute_stale_state_cleanup( + plan: StaleStatePlan, + *, + copier: Callable[[Path, Path], Any] = shutil.copy2, + writer: Callable[[Path, Mapping[str, Any]], None] = write_state_file, +) -> StateCleanupResult: + if not plan.stale_keys: + return StateCleanupResult(0, None) + + current = plan.state_file.read_bytes() + if hashlib.sha256(current).hexdigest() != plan.source_digest: + raise RuntimeError("State changed after the cleanup preview; run the preview again.") + + stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f") + backup = plan.state_file.with_name(f"{plan.state_file.name}.pre-clean-{stamp}.bak") + copier(plan.state_file, backup) + + updated = dict(plan.state) + files = dict(updated.get("files", {})) + for key in plan.stale_keys: + files.pop(key, None) + updated["files"] = files + writer(plan.state_file, updated) + return StateCleanupResult(len(plan.stale_keys), backup) diff --git a/src/juice_lyrics/state.py b/src/juice_lyrics/state.py index c1f9153..19ec3c0 100644 --- a/src/juice_lyrics/state.py +++ b/src/juice_lyrics/state.py @@ -1,22 +1,119 @@ from __future__ import annotations -import hashlib, json + +import hashlib +import json +from collections.abc import Mapping, Sequence from pathlib import Path from typing import Any -from .config.settings import STATE_FILE, DATA_DIR + from .backup.manager import ensure_data_dirs, now_iso +from .config.settings import STATE_FILE -def load_state()->dict[str,Any]: - ensure_data_dirs() - if not STATE_FILE.exists(): return {"files":{},"updated":None} + +def empty_state() -> dict[str, Any]: + return {"files": {}, "updated": None} + + +def read_state_file(path: Path = STATE_FILE) -> dict[str, Any]: + """Read state without creating directories or mutating the source file.""" + + source = Path(path) + if not source.exists(): + return empty_state() try: - v=json.loads(STATE_FILE.read_text(encoding="utf-8")); return v if isinstance(v,dict) else {"files":{},"updated":None} - except Exception: return {"files":{},"updated":None} + value = json.loads(source.read_text(encoding="utf-8")) + except (OSError, UnicodeError, json.JSONDecodeError): + return empty_state() + if not isinstance(value, dict): + return empty_state() + if not isinstance(value.get("files", {}), dict): + value["files"] = {} + return value + + +def write_state_file( + path: Path, + state: Mapping[str, Any], + *, + update_timestamp: bool = True, +) -> None: + """Atomically write state to an explicit path.""" + + destination = Path(path) + destination.parent.mkdir(parents=True, exist_ok=True) + value = dict(state) + if update_timestamp: + value["updated"] = now_iso() + temporary = destination.with_suffix(destination.suffix + ".tmp") + try: + temporary.write_text( + json.dumps(value, indent=2, ensure_ascii=False), + encoding="utf-8", + ) + temporary.replace(destination) + except Exception: + try: + temporary.unlink(missing_ok=True) + except OSError: + pass + raise + + +def load_state() -> dict[str, Any]: + """Backward-compatible loader used by established write workflows.""" + + ensure_data_dirs() + return read_state_file(STATE_FILE) + + +def save_state(state: dict[str, Any]) -> None: + ensure_data_dirs() + write_state_file(STATE_FILE, state) + state["updated"] = read_state_file(STATE_FILE).get("updated") + + +def resolve_state_entry( + files: Mapping[str, Any], + relative_path: Path, + library_relative_paths: Sequence[Path] = (), +) -> tuple[str | None, dict[str, Any] | None]: + """Resolve an exact or unambiguous historical relative-path record.""" + + reference = str(relative_path) + exact = files.get(reference) + if isinstance(exact, dict): + return reference, exact + if exact is not None: + return reference, None + + basename = relative_path.name.casefold() + if library_relative_paths: + library_matches = [path for path in library_relative_paths if path.name.casefold() == basename] + if len(library_matches) != 1: + return None, None + candidates = [ + (key, value) + for key, value in files.items() + if isinstance(key, str) + and not Path(key).is_absolute() + and Path(key).name.casefold() == basename + and isinstance(value, dict) + ] + if len(candidates) == 1: + return candidates[0] + return None, None + + +def sha256_file(path: Path) -> str: + digest = hashlib.sha256() + with Path(path).open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + return digest.hexdigest() + -def save_state(state:dict[str,Any])->None: - ensure_data_dirs(); state["updated"]=now_iso(); tmp=STATE_FILE.with_suffix(".tmp"); tmp.write_text(json.dumps(state,indent=2,ensure_ascii=False),encoding="utf-8"); tmp.replace(STATE_FILE) +def file_fingerprint(path: Path) -> tuple[int, int, int, int, int]: + """Cheap in-process guard for reusing a hash, including replacement/in-place edits.""" -def sha256_file(path:Path)->str: - h=hashlib.sha256() - with path.open("rb") as f: - for chunk in iter(lambda:f.read(1024*1024),b""): h.update(chunk) - return h.hexdigest() + info = Path(path).stat() + return (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns) diff --git a/src/juice_lyrics/tui/__init__.py b/src/juice_lyrics/tui/__init__.py new file mode 100644 index 0000000..3d9dec5 --- /dev/null +++ b/src/juice_lyrics/tui/__init__.py @@ -0,0 +1,5 @@ +"""The 999 Textual frontend.""" + +from .app import JuiceLyricsApp, run_tui + +__all__ = ["JuiceLyricsApp", "run_tui"] diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py new file mode 100644 index 0000000..49e3f91 --- /dev/null +++ b/src/juice_lyrics/tui/app.py @@ -0,0 +1,1286 @@ +from __future__ import annotations + +from collections.abc import Callable +from typing import Any + +from textual.app import App +from textual.binding import Binding +from textual.screen import ModalScreen + +from ..backup.manager import BackupRecord, list_backups, restore_backup +from ..rmpc.integration import patch_rmpc_config +from ..services.acquisition_queue import QueueSnapshot, get_queue_snapshot +from ..services.catalogue import ( + CatalogueFilterMetadata, + CataloguePage, + SongDetails, + get_catalogue_filters, + get_song_details_by_id, + search_catalogue_page, +) +from ..services.download_queue import ( + DownloadExecutionResult, + DownloadQueueSnapshot, + QueueAddResult, + QueueBatchAddResult, + add_batch_to_download_queue, + execute_selected_download, + execute_selected_retry, + remove_queue_item, + clear_download_queue, + clear_completed_history, + plan_download_all, + execute_download_all, + plan_download_execution, + plan_download_retry, + plan_queue_batch_additions, + project_download_queue, +) +from ..services.library_status import LibrarySnapshot, LibraryStatus, get_library_snapshot, get_library_status +from ..services.library_identity import IdentityBackfillResult, backfill_catalogue_identities +from ..services.library_index_sync import LibraryIndexSyncResult, sync_library_index +from ..services.metadata_audit import MetadataAudit, audit_track_metadata +from ..services.metadata_repair import ( + MetadataRepairPlan, + MetadataRepairResult, + execute_metadata_repair, + plan_metadata_repair, +) +from ..services.missing_library import MissingLibraryReport, get_missing_library +from ..services.manual_identity import ( + ManualIdentityResult, + set_manual_identity, + unlock_manual_identity, +) +from ..services.identity_rebuild import ( + IdentityRebuildPlan, + IdentityRebuildResult, + execute_catalogue_identity_rebuild, + plan_catalogue_identity_rebuild, +) +from ..services.library_sync import ( + LibrarySyncPlan, + LibrarySyncResult, + execute_library_sync_preview, + get_library_sync_preview, +) +from ..services.settings_snapshot import SettingsSnapshot, get_settings_snapshot +from .screens.base import NavigationItem +from .screens.browse import BrowseScreen +from .screens.dashboard import DashboardScreen +from .screens.downloads import DownloadsScreen +from .screens.library import ( + LibraryDuplicatesDialog, + LibraryIssuesDialog, + LibraryScreen, + ManualMatchDialog, + MissingLibraryDialog, + MetadataAuditDialog, + MetadataRepairConfirmationDialog, +) +from .screens.settings import SettingsScreen +from .help import HelpScreen + +LibraryStatusProvider = Callable[[Any], LibraryStatus] +QueueSnapshotProvider = Callable[[], QueueSnapshot] +DownloadQueueProvider = Callable[[], DownloadQueueSnapshot] +QueuePlanProvider = Callable[..., QueueAddResult | QueueBatchAddResult] +QueueAddProvider = Callable[..., QueueAddResult | QueueBatchAddResult] +DownloadPlanProvider = Callable[..., DownloadExecutionResult] +DownloadExecutionProvider = Callable[..., DownloadExecutionResult] +CatalogueSearchProvider = Callable[..., CataloguePage] +CatalogueDetailsProvider = Callable[..., SongDetails | None] +CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] +LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] +LibraryIdentityProvider = Callable[..., IdentityBackfillResult] +LibraryIndexSyncProvider = Callable[..., LibraryIndexSyncResult] +ManualIdentityProvider = Callable[..., ManualIdentityResult] +IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] +IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] +LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] +LibraryExecutionProvider = Callable[..., LibrarySyncResult] +SettingsSnapshotProvider = Callable[[Any], SettingsSnapshot] +MetadataAuditProvider = Callable[..., MetadataAudit] +MetadataRepairPlanProvider = Callable[..., MetadataRepairPlan] +MetadataRepairExecutionProvider = Callable[..., MetadataRepairResult] +MissingLibraryProvider = Callable[..., MissingLibraryReport] + + +class JuiceLyricsApp(App[None]): + """The 999 terminal application.""" + + TITLE = "999" + SUB_TITLE = "Juice WRLD Music Hub" + + BINDINGS = [ + Binding("1", "show_section('dashboard')", "Dashboard", show=False), + Binding("2", "show_section('browse')", "Browse", show=False), + Binding("3", "show_section('library')", "Library", show=False), + Binding("4", "show_section('downloads')", "Downloads", show=False), + Binding("5", "show_section('settings')", "Settings", show=False), + Binding("r", "refresh_active", "Refresh", show=False), + Binding("question_mark", "show_help", "Help", show=False, priority=True), + Binding("q", "quit", "Quit", show=False), + ] + + def _get_dom_base(self): + """Keep application-level queries scoped to the visible section.""" + + return self.screen + + CSS = """ + Screen { + background: transparent; + } + + HelpScreen { + align: center middle; + background: transparent; + } + + #help-dialog { + width: 86; + max-width: 96%; + height: 88%; + border: round ansi_cyan; + background: transparent; + padding: 0 2; + } + + #help-title { + height: 2; + text-style: bold; + color: ansi_blue; + } + + #help-scroll { + height: 1fr; + background: transparent; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + } + + #help-content { + height: auto; + background: transparent; + } + + #help-footer { + height: 1; + text-style: dim; + } + + #brand { + height: 2; + padding: 0 1; + text-style: bold; + border-bottom: solid ansi_cyan; + } + + #primary-navigation { + height: 3; + padding: 0; + align-horizontal: center; + } + + #primary-navigation NavigationItem { + width: auto; + min-width: 12; + height: 3; + margin: 0 1; + background: transparent; + color: ansi_default; + border: none; + text-align: center; + content-align: center middle; + } + + #primary-navigation NavigationItem:hover { + color: ansi_default; + text-style: bold; + } + + #primary-navigation NavigationItem.-current, + #primary-navigation NavigationItem.-current:hover { + color: ansi_blue; + text-style: bold; + } + + #screen-content { + height: 1fr; + padding: 0 2 1 2; + } + + #screen-title { + height: 2; + text-style: bold; + } + + #dashboard-panels { + layout: grid; + grid-size: 2 1; + grid-gutter: 1 2; + height: 1fr; + } + + .dashboard-panel { + border: round ansi_cyan; + padding: 1 2; + height: auto; + min-height: 12; + } + + .panel-title { + text-style: bold; + height: 2; + } + + .panel-error { + color: ansi_red; + height: auto; + } + + #browse-controls { + height: auto; + layout: grid; + grid-size: 3 1; + grid-columns: 2fr 1fr 1fr; + grid-rows: 4; + grid-gutter: 0 1; + } + + .browse-filter { + height: 4; + } + + #browse-controls Input, + #browse-controls SelectCurrent, + #library-controls Input, + #library-controls SelectCurrent { + background: transparent; + color: ansi_default; + border: tall ansi_default; + background-tint: transparent; + padding: 0 1; + } + + #browse-controls Input:focus, + #browse-controls Select:focus > SelectCurrent, + #library-controls Input:focus, + #library-controls Select:focus > SelectCurrent { + background: transparent; + border: tall ansi_blue; + background-tint: transparent; + } + + #browse-controls Select, + #browse-controls SelectOverlay { + background: transparent; + color: ansi_default; + } + + #browse-controls SelectOverlay { + border: tall ansi_blue; + } + + #browse-controls Input > .input--cursor, + #library-controls Input > .input--cursor { + background: ansi_blue; + color: ansi_default; + text-style: bold; + } + + #browse-controls Input > .input--selection, + #library-controls Input > .input--selection { + background: ansi_blue; + color: ansi_default; + } + + #browse-controls SelectOverlay, + #library-controls SelectOverlay, + #browse-controls SelectOverlay OptionList, + #library-controls SelectOverlay OptionList { + background: transparent; + background-tint: transparent; + color: ansi_default; + } + + #browse-controls SelectOverlay:focus, + #library-controls SelectOverlay:focus, + #browse-controls Select:focus > SelectCurrent, + #library-controls Select:focus > SelectCurrent { + background: transparent; + background-tint: transparent; + border: tall ansi_blue; + } + + #browse-controls SelectCurrent Static#label, + #library-controls SelectCurrent Static#label, + #browse-controls SelectCurrent .arrow, + #library-controls SelectCurrent .arrow { + background: transparent; + color: ansi_default; + } + + #browse-controls .option-list--option-highlighted { + background: transparent; + color: ansi_blue; + text-style: bold; + } + + .filter-label { + height: 1; + text-style: dim; + } + + #browse-status { + height: 2; + padding: 0 1; + } + + #browse-status.-error { + color: ansi_red; + } + + #browse-main { + height: 1fr; + layout: grid; + grid-size: 2 1; + grid-columns: 3fr 2fr; + grid-gutter: 0 1; + } + + .browse-panel { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + } + + #browse-results-scroll, + #browse-details-scroll { + height: 1fr; + background: transparent; + } + + #browse-results-scroll { + overflow-y: scroll; + overflow-x: hidden; + scrollbar-size-vertical: 1; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + scrollbar-corner-color: transparent; + } + + #browse-results, + #browse-details { + height: auto; + background: transparent; + } + + #browse-pagination { + height: 2; + layout: grid; + grid-size: 3 1; + grid-columns: 14 1fr 10; + padding: 0 1; + } + + #browse-shortcuts { + height: 1; + padding: 0 1; + color: ansi_default; + text-style: dim; + overflow: hidden; + background: transparent; + } + + #browse-pagination PaginationControl { + width: 100%; + height: 1; + background: transparent; + border: none; + color: ansi_default; + text-align: center; + } + + #browse-pagination PaginationControl.-available { + color: ansi_blue; + text-style: bold; + } + + #browse-pagination PaginationControl.-available:hover { + background: transparent; + text-style: bold; + } + + #browse-pagination PaginationControl.-unavailable { + color: ansi_default; + text-style: dim; + } + + #browse-page-position { + height: 1; + text-align: center; + color: ansi_default; + } + + AddToQueueDialog { + align: center middle; + background: transparent; + } + + #queue-confirm-dialog { + width: 72; + max-width: 92%; + height: auto; + max-height: 92%; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #queue-confirm-title { + height: 2; + text-style: bold; + color: ansi_blue; + } + + #queue-confirm-body { + height: auto; + } + + #queue-confirm-status { + height: 2; + padding-top: 1; + } + + #queue-confirm-actions { + height: 2; + layout: grid; + grid-size: 2 1; + grid-columns: 1fr 1fr; + } + + #queue-confirm-actions QueueDialogAction { + background: transparent; + border: none; + color: ansi_blue; + text-style: bold; + text-align: center; + } + + #queue-confirm-actions QueueDialogAction:hover { + background: transparent; + text-style: bold; + } + + DownloadSelectedDialog, + RetryFailedDialog, + QueueCleanupDialog, + DownloadAllDialog { + align: center middle; + background: transparent; + } + + MaintenanceDialog, + BackupBrowser, + RestoreDialog, + RmpcDialog, + ManualMatchDialog, + LibraryIssuesDialog, + LibraryDuplicatesDialog, + MissingLibraryDialog, + MetadataAuditDialog, + MetadataRepairConfirmationDialog { + align: center middle; + background: transparent; + } + + #library-dialog { + width: 76; + max-width: 92%; + max-height: 88%; + height: auto; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #manual-match-dialog { + width: 82; + max-width: 94%; + height: 80%; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #manual-match-context { + height: 3; + } + + #manual-match-query { + height: 3; + background: transparent; + border: tall ansi_cyan; + } + + #manual-match-query:focus { + border: tall ansi_blue; + } + + #manual-match-scroll { + height: 1fr; + background: transparent; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + } + + #manual-match-results { + height: auto; + background: transparent; + } + + #library-issues-dialog { + width: 92; + max-width: 96%; + height: 82%; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #library-issues-summary, + #library-issues-help { + height: 2; + text-style: bold; + } + + #library-issues-main { + height: 1fr; + layout: grid; + grid-size: 2 1; + grid-columns: 3fr 2fr; + grid-gutter: 0 1; + } + + #library-issues-list-scroll, + #library-issues-detail-scroll { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + background: transparent; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + } + + #library-issues-list, + #library-issues-detail { + height: auto; + background: transparent; + } + + #library-duplicates-dialog { + width: 94; + max-width: 96%; + height: 82%; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #library-duplicates-summary, + #library-duplicates-help { + height: 2; + text-style: bold; + } + + #library-duplicates-main { + height: 1fr; + layout: grid; + grid-size: 2 1; + grid-columns: 2fr 3fr; + grid-gutter: 0 1; + } + + #library-duplicates-list-scroll, + #library-duplicates-detail-scroll { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + background: transparent; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + } + + #library-duplicates-list, + #library-duplicates-detail { + height: auto; + background: transparent; + } + + #missing-library-dialog { + width: 96; + max-width: 96%; + height: 84%; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #missing-library-summary, + #missing-library-help { + height: 2; + text-style: bold; + } + + #missing-library-query { + height: 3; + background: transparent; + border: tall ansi_cyan; + } + + #missing-library-query:focus { + border: tall ansi_blue; + } + + #missing-library-main { + height: 1fr; + layout: grid; + grid-size: 2 1; + grid-columns: 3fr 2fr; + grid-gutter: 0 1; + } + + #missing-library-list-scroll, + #missing-library-detail-scroll { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + background: transparent; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + } + + #missing-library-list, + #missing-library-detail { + height: auto; + background: transparent; + } + + #metadata-audit-dialog { + width: 88; + max-width: 96%; + height: 82%; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #metadata-audit-scroll { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + background: transparent; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + } + + #metadata-audit-content { + height: auto; + background: transparent; + } + + #metadata-audit-help { + height: 2; + text-style: bold; + } + + #library-dialog-title { + height: 2; + text-style: bold; + color: ansi_blue; + } + + #library-dialog-body { + height: auto; + } + + #library-dialog-help { + height: 2; + text-style: dim; + } + + #library-dialog-actions { + height: 2; + grid-size: 2 1; + grid-columns: 1fr 1fr; + } + + #library-dialog-actions LibraryDialogAction { + background: transparent; + border: none; + color: ansi_blue; + text-style: bold; + text-align: center; + } + + #download-confirm-dialog { + width: 76; + max-width: 92%; + max-height: 88%; + height: auto; + padding: 1 2; + border: round ansi_cyan; + background: transparent; + } + + #download-confirm-title { + height: 2; + text-style: bold; + color: ansi_blue; + } + + #download-confirm-body { + height: auto; + } + + #download-confirm-actions { + height: 2; + layout: grid; + grid-size: 2 1; + grid-columns: 1fr 1fr; + } + + #download-confirm-actions DownloadDialogAction { + background: transparent; + border: none; + color: ansi_blue; + text-style: bold; + text-align: center; + } + + #download-confirm-actions DownloadDialogAction:hover { + background: transparent; + text-style: bold; + } + + #downloads-summary { + height: 2; + padding: 0 1; + text-style: bold; + } + + #downloads-status, + #downloads-position { + height: 2; + padding: 0 1; + overflow: hidden; + } + + #downloads-status.-error { + color: ansi_red; + } + + #downloads-main { + height: 1fr; + layout: grid; + grid-size: 2 1; + grid-columns: 2fr 3fr; + grid-gutter: 0 1; + } + + .downloads-panel { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + } + + #download-queue-scroll, + #download-details-scroll { + height: 1fr; + overflow-y: scroll; + overflow-x: hidden; + background: transparent; + scrollbar-size-vertical: 1; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + scrollbar-corner-color: transparent; + } + + #download-queue, + #download-details { + height: auto; + background: transparent; + } + + #library-summary { + height: 2; + padding: 0 1; + text-style: bold; + } + + #library-status, + #library-preview, + #library-position { + height: 2; + padding: 0 1; + } + + #library-status.-error { + color: ansi_red; + } + + #library-controls { + height: 4; + layout: grid; + grid-size: 2 1; + grid-columns: 2fr 1fr; + grid-gutter: 0 1; + } + + .library-filter { + height: 4; + } + + #library-controls Select, + #library-controls SelectOverlay { + background: transparent; + color: ansi_default; + } + + #library-controls SelectOverlay { + border: tall ansi_blue; + } + + #library-controls .option-list--option-highlighted { + background: transparent; + color: ansi_blue; + text-style: bold; + } + + #library-main { + height: 1fr; + layout: grid; + grid-size: 2 1; + grid-columns: 3fr 2fr; + grid-gutter: 0 1; + } + + .library-panel { + height: 1fr; + border: round ansi_cyan; + padding: 0 1; + } + + #library-tracks-scroll, + #library-details-scroll { + height: 1fr; + overflow-y: scroll; + overflow-x: hidden; + background: transparent; + scrollbar-size-vertical: 1; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + scrollbar-corner-color: transparent; + } + + #library-tracks, + #library-details { + height: auto; + background: transparent; + } + + #settings-warning { + height: 2; + padding: 0 1; + color: ansi_blue; + text-style: bold; + } + + #settings-status, + #settings-position { + height: 2; + padding: 0 1; + } + + #settings-status.-error { + color: ansi_red; + } + + #settings-scroll { + height: 1fr; + overflow-y: scroll; + overflow-x: hidden; + background: transparent; + scrollbar-size-vertical: 1; + scrollbar-color: ansi_blue; + scrollbar-background: transparent; + scrollbar-corner-color: transparent; + } + + #settings-main { + height: auto; + layout: grid; + grid-size: 2 2; + grid-columns: 1fr 1fr; + grid-gutter: 1 1; + } + + .settings-panel { + height: auto; + min-height: 8; + border: round ansi_cyan; + padding: 0 1; + } + + #settings-configuration, + #settings-paths, + #settings-integrations, + #settings-capabilities { + height: auto; + background: transparent; + } + + #settings-detail { + height: auto; + min-height: 3; + margin-top: 1; + border-top: solid ansi_cyan; + padding: 0 1; + background: transparent; + } + + #placeholder-panel { + border: round ansi_cyan; + padding: 2 3; + height: auto; + max-width: 72; + } + + #status-footer { + height: 2; + padding: 0 2; + border-top: solid ansi_cyan; + text-style: dim; + } + + Screen.-narrow #primary-navigation NavigationItem { + min-width: 7; + margin: 0; + } + + Screen.-narrow #dashboard-panels { + grid-size: 1 2; + overflow-y: auto; + } + + Screen.-narrow #screen-content { + padding: 1; + } + + Screen.-narrow #browse-controls { + grid-size: 3 1; + grid-columns: 2fr 1fr 1fr; + grid-rows: 4; + } + + Screen.-narrow #browse-main { + grid-size: 1 2; + grid-columns: 1fr; + grid-rows: 2fr 1fr; + } + + Screen.-narrow #browse-pagination { + padding: 0; + } + + Screen.-short #screen-title { + display: none; + } + + Screen.-short #browse-status, + Screen.-short #browse-pagination, + Screen.-short .browse-panel .panel-title { + height: 1; + } + + Screen.-downloads-narrow #downloads-main { + grid-size: 1 2; + grid-columns: 1fr; + grid-rows: 2fr 1fr; + } + + Screen.-downloads-narrow.-details-mode #downloads-main { + grid-size: 1 1; + grid-rows: 1fr; + } + + Screen.-downloads-narrow.-details-mode #download-queue-panel { + display: none; + } + + Screen.-short #downloads-summary, + Screen.-short #downloads-status, + Screen.-short #downloads-position, + Screen.-short .downloads-panel .panel-title { + height: 1; + } + + Screen.-library-narrow #library-main { + grid-size: 1 1; + grid-columns: 1fr; + grid-rows: 1fr; + } + + Screen.-library-narrow #library-details-panel { + display: none; + } + + Screen.-library-narrow.-details-mode #library-tracks-panel { + display: none; + } + + Screen.-library-narrow.-details-mode #library-details-panel { + display: block; + } + + Screen.-short #library-summary, + Screen.-short #library-status, + Screen.-short #library-preview, + Screen.-short #library-position, + Screen.-short .library-panel .panel-title { + height: 1; + } + + Screen.-library-compact #screen-title { + display: none; + } + + Screen.-library-compact #library-summary, + Screen.-library-compact #library-status, + Screen.-library-compact #library-preview, + Screen.-library-compact #library-position, + Screen.-library-compact .library-panel .panel-title { + height: 1; + } + + Screen.-settings-narrow #settings-main { + grid-size: 1 4; + grid-columns: 1fr; + } + + Screen.-settings-compact #screen-title { + display: none; + } + + Screen.-settings-compact #settings-warning, + Screen.-settings-compact #settings-status, + Screen.-settings-compact #settings-position, + Screen.-settings-compact .settings-panel .panel-title { + height: 1; + } + """ + + def __init__( + self, + settings: Any, + *, + library_status_provider: LibraryStatusProvider = get_library_status, + queue_snapshot_provider: QueueSnapshotProvider = get_queue_snapshot, + catalogue_search_provider: CatalogueSearchProvider = search_catalogue_page, + catalogue_details_provider: CatalogueDetailsProvider = get_song_details_by_id, + catalogue_filters_provider: CatalogueFiltersProvider = get_catalogue_filters, + downloads_queue_provider: DownloadQueueProvider | None = None, + queue_plan_provider: QueuePlanProvider = plan_queue_batch_additions, + queue_add_provider: QueueAddProvider = add_batch_to_download_queue, + download_plan_provider: DownloadPlanProvider = plan_download_execution, + download_execution_provider: DownloadExecutionProvider = execute_selected_download, + download_retry_plan_provider: Callable[..., Any] = plan_download_retry, + download_retry_execution_provider: Callable[..., Any] = execute_selected_retry, + queue_remove_provider: Callable[..., Any] = remove_queue_item, + queue_clear_provider: Callable[..., Any] = clear_download_queue, + queue_history_provider: Callable[..., Any] = clear_completed_history, + download_all_plan_provider: Callable[..., Any] = plan_download_all, + download_all_execution_provider: Callable[..., Any] = execute_download_all, + library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, + library_index_sync_provider: LibraryIndexSyncProvider = sync_library_index, + library_identity_provider: LibraryIdentityProvider = backfill_catalogue_identities, + identity_rebuild_plan_provider: IdentityRebuildPlanProvider = plan_catalogue_identity_rebuild, + identity_rebuild_execution_provider: IdentityRebuildExecutionProvider = execute_catalogue_identity_rebuild, + manual_identity_provider: ManualIdentityProvider = set_manual_identity, + manual_unlock_provider: ManualIdentityProvider = unlock_manual_identity, + library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, + library_execution_provider: LibraryExecutionProvider = execute_library_sync_preview, + metadata_audit_provider: MetadataAuditProvider = audit_track_metadata, + metadata_repair_plan_provider: MetadataRepairPlanProvider = plan_metadata_repair, + metadata_repair_execution_provider: MetadataRepairExecutionProvider = execute_metadata_repair, + missing_library_provider: MissingLibraryProvider = get_missing_library, + backup_provider: Callable[[], tuple[BackupRecord, ...]] = list_backups, + restore_provider: Callable[[Any, Any], int] = restore_backup, + rmpc_setup_provider: Callable[[Any, Any], Any] = patch_rmpc_config, + settings_snapshot_provider: SettingsSnapshotProvider = get_settings_snapshot, + ) -> None: + super().__init__(ansi_color=True) + self.settings = settings + self.library_status_provider = library_status_provider + self.queue_snapshot_provider = queue_snapshot_provider + self.catalogue_search_provider = catalogue_search_provider + self.catalogue_details_provider = catalogue_details_provider + self.catalogue_filters_provider = catalogue_filters_provider + source_downloads_provider = downloads_queue_provider or queue_snapshot_provider + + def normalized_downloads_provider() -> DownloadQueueSnapshot: + snapshot = source_downloads_provider() + if isinstance(snapshot, QueueSnapshot): + return project_download_queue(snapshot) + return snapshot + + self.downloads_queue_provider = normalized_downloads_provider + self.queue_plan_provider = queue_plan_provider + self.queue_add_provider = queue_add_provider + self.download_plan_provider = download_plan_provider + self.download_execution_provider = download_execution_provider + self.download_retry_plan_provider = download_retry_plan_provider + self.download_retry_execution_provider = download_retry_execution_provider + self.queue_remove_provider = queue_remove_provider + self.queue_clear_provider = queue_clear_provider + self.queue_history_provider = queue_history_provider + self.download_all_plan_provider = download_all_plan_provider + self.download_all_execution_provider = download_all_execution_provider + self.library_snapshot_provider = library_snapshot_provider + self.library_index_sync_provider = library_index_sync_provider + self.library_identity_provider = library_identity_provider + self.identity_rebuild_plan_provider = identity_rebuild_plan_provider + self.identity_rebuild_execution_provider = identity_rebuild_execution_provider + self.manual_identity_provider = manual_identity_provider + self.manual_unlock_provider = manual_unlock_provider + self.library_preview_provider = library_preview_provider + self.library_execution_provider = library_execution_provider + self.metadata_audit_provider = metadata_audit_provider + self.metadata_repair_plan_provider = metadata_repair_plan_provider + self.metadata_repair_execution_provider = metadata_repair_execution_provider + self.missing_library_provider = missing_library_provider + self.backup_provider = backup_provider + self.restore_provider = restore_provider + self.rmpc_setup_provider = rmpc_setup_provider + self.settings_snapshot_provider = settings_snapshot_provider + + def on_mount(self) -> None: + self.install_screen( + DashboardScreen( + self.settings, + library_status_provider=self.library_status_provider, + queue_snapshot_provider=self.queue_snapshot_provider, + ), + "dashboard", + ) + self.install_screen( + BrowseScreen( + self.settings, + search_provider=self.catalogue_search_provider, + details_provider=self.catalogue_details_provider, + filters_provider=self.catalogue_filters_provider, + queue_plan_provider=self.queue_plan_provider, + queue_add_provider=self.queue_add_provider, + ), + "browse", + ) + self.install_screen( + LibraryScreen( + self.settings, + snapshot_provider=self.library_snapshot_provider, + index_sync_provider=self.library_index_sync_provider, + identity_provider=self.library_identity_provider, + identity_rebuild_plan_provider=self.identity_rebuild_plan_provider, + identity_rebuild_execution_provider=self.identity_rebuild_execution_provider, + preview_provider=self.library_preview_provider, + execution_provider=self.library_execution_provider, + backup_provider=self.backup_provider, + restore_provider=self.restore_provider, + rmpc_status_provider=self.settings_snapshot_provider, + rmpc_setup_provider=self.rmpc_setup_provider, + manual_search_provider=self.catalogue_search_provider, + catalogue_details_provider=self.catalogue_details_provider, + metadata_audit_provider=self.metadata_audit_provider, + metadata_repair_plan_provider=self.metadata_repair_plan_provider, + metadata_repair_execution_provider=self.metadata_repair_execution_provider, + manual_identity_provider=self.manual_identity_provider, + manual_unlock_provider=self.manual_unlock_provider, + missing_library_provider=self.missing_library_provider, + queue_plan_provider=self.queue_plan_provider, + queue_add_provider=self.queue_add_provider, + ), + "library", + ) + self.install_screen( + DownloadsScreen( + self.settings, + queue_provider=self.downloads_queue_provider, + plan_provider=self.download_plan_provider, + execution_provider=self.download_execution_provider, + retry_plan_provider=self.download_retry_plan_provider, + retry_execution_provider=self.download_retry_execution_provider, + remove_provider=self.queue_remove_provider, + clear_provider=self.queue_clear_provider, + history_provider=self.queue_history_provider, + batch_plan_provider=self.download_all_plan_provider, + batch_execution_provider=self.download_all_execution_provider, + ), + "downloads", + ) + self.install_screen( + SettingsScreen( + self.settings, + snapshot_provider=self.settings_snapshot_provider, + ), + "settings", + ) + self.push_screen("dashboard") + + def action_show_section(self, section: str) -> None: + if isinstance(self.screen, ModalScreen): + return + if self.screen.name == section: + return + self.switch_screen(section) + + def action_quit(self) -> None: + if not isinstance(self.screen, ModalScreen): + self.exit() + + def invalidate_download_queue(self) -> None: + downloads = self.get_screen("downloads") + invalidate = getattr(downloads, "invalidate_snapshot", None) + if callable(invalidate): + invalidate() + + def invalidate_library_views(self) -> None: + for name in ("dashboard", "library"): + screen = self.get_screen(name) + invalidate = getattr(screen, "invalidate_snapshot", None) + if callable(invalidate): + invalidate() + + def action_refresh_active(self) -> None: + refresh = getattr(self.screen, "refresh_snapshot", None) + if callable(refresh): + refresh() + else: + self.notify(f"{self.screen.title or 'This section'} has no data to refresh yet.") + + def action_show_help(self) -> None: + if not isinstance(self.screen, ModalScreen) or isinstance( + self.screen, (LibraryDuplicatesDialog, MissingLibraryDialog) + ): + self.push_screen(HelpScreen()) + + def on_navigation_item_activated(self, event: NavigationItem.Activated) -> None: + self.action_show_section(event.item.section) + + +def run_tui(settings: Any) -> int: + """Run the interactive application and return a CLI-compatible exit code.""" + + JuiceLyricsApp(settings).run() + return 0 diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py new file mode 100644 index 0000000..1af1080 --- /dev/null +++ b/src/juice_lyrics/tui/help.py @@ -0,0 +1,86 @@ +"""Human-readable keyboard guide for the implemented TUI actions.""" + +from textual.app import ComposeResult +from textual.containers import Container, VerticalScroll +from textual.events import Key +from textual.screen import ModalScreen +from textual.widgets import Static + + +# Keep descriptions here alongside the screen action inventory. The same concise +# labels are reused by screen footers; this is not a second executable keymap. +KEY_GUIDE: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = ( + ("Global", (("1–5", "Switch sections (outside text entry)"), + ("r", "Refresh current section"), ("?", "Open Help"), + ("q", "Quit"), ("Esc", "Close dialog or return from details"))), + ("Browse", (("↑/↓ or j/k", "Move through results"), ("Enter", "Show song details"), + ("/", "Focus title search; Enter searches"), ("Space", "Mark or unmark song"), + ("M", "Toggle marks on this page"), ("u", "Clear marks"), + ("a", "Add current or marked songs to Downloads"), + ("n / p", "Next / previous catalogue page"), + ("PgUp/PgDn", "Scroll loaded results"), ("Home/End", "First / last result"))), + ("Library", (("↑/↓ or j/k", "Select track"), ("Enter", "Track details"), + ("/", "Focus track search; Enter filters"), + ("s", "Sync paths and catalogue identity (no media edits)"), + ("a", "Open Library Issues"), + ("g", "Show catalogue recordings missing locally"), + ("d", "Review duplicate recordings"), + ("e", "Review and apply selected metadata repairs"), + ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), + ("v", "Recheck local media and lyrics (read-only)"), + ("b", "Browse backups"), + ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), + ("c", "Choose and lock a catalogue match"), + ("u", "Unlock and clear a manual match"), + ("i", "Preview catalogue identity rebuild"), + ("PgUp/PgDn", "Scroll tracks or details"), ("Home/End", "First / last track"))), + ("Missing Library", (("↑/↓ or j/k", "Select missing recording"), + ("/", "Filter loaded catalogue recordings"), + ("a", "Add selected recording to Downloads"), + ("Esc", "Return to Library"))), + ("Downloads", (("↑/↓ or j/k", "Select queue item"), ("Enter", "Item details"), + ("d", "Download selected song"), ("t", "Retry failed song"), + ("A", "Download entire queue (confirmation)"), + ("x", "Remove selected waiting/failed item"), + ("c", "Clear waiting/failed queue (confirmation)"), + ("H", "Clear completed history"), + ("PgUp/PgDn", "Scroll queue or details"), ("Home/End", "First / last item"))), + ("Settings", (("↑/↓ or j/k", "Inspect setting"), ("r", "Refresh"), + ("PgUp/PgDn", "Scroll settings"), ("Home/End", "First / last setting"))), + ("Backups", (("↑/↓ or j/k", "Select backup"), ("r", "Review restore confirmation"), + ("Esc", "Return to Library"))), + ("Confirmations", (("y", "Confirm immediately"), ("n / Esc", "Cancel immediately"), + ("Enter", "Choose focused action (Cancel initially)"), + ("Tab / Shift+Tab / ←/→", "Move between actions"))), +) + + +def guide_text() -> str: + return "\n\n".join( + f"{heading}\n{'─' * len(heading)}\n" + "\n".join(f"{key:<24}{description}" for key, description in rows) + for heading, rows in KEY_GUIDE + ) + + +class HelpScreen(ModalScreen[None]): + """Scrollable, globally available keyboard guide.""" + + def compose(self) -> ComposeResult: + with Container(id="help-dialog"): + yield Static("Keyboard help", id="help-title") + with VerticalScroll(id="help-scroll"): + yield Static(guide_text(), id="help-content", markup=False) + yield Static("↑↓ / PgUp/PgDn Scroll Esc Close", id="help-footer", markup=False) + + def on_mount(self) -> None: + self.query_one("#help-scroll", VerticalScroll).focus() + + def on_key(self, event: Key) -> None: + if event.key in {"escape", "question_mark", "q"}: + self.dismiss(None) + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() diff --git a/src/juice_lyrics/tui/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py new file mode 100644 index 0000000..767259d --- /dev/null +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -0,0 +1,10 @@ +"""Screens for the 999 Textual frontend.""" + +from .browse import BrowseScreen +from .dashboard import DashboardScreen +from .downloads import DownloadsScreen +from .library import LibraryScreen +from .settings import SettingsScreen +from .placeholder import PlaceholderScreen + +__all__ = ["BrowseScreen", "DashboardScreen", "DownloadsScreen", "LibraryScreen", "PlaceholderScreen", "SettingsScreen"] diff --git a/src/juice_lyrics/tui/screens/base.py b/src/juice_lyrics/tui/screens/base.py new file mode 100644 index 0000000..d1dd4f1 --- /dev/null +++ b/src/juice_lyrics/tui/screens/base.py @@ -0,0 +1,67 @@ +from __future__ import annotations + +from collections.abc import Iterable + +from textual.app import ComposeResult +from textual.containers import Container, Horizontal +from textual.events import Click, Resize +from textual.message import Message +from textual.screen import Screen +from textual.widget import Widget +from textual.widgets import Static + +_SECTIONS = ( + ("dashboard", "1 Dashboard"), + ("browse", "2 Browse"), + ("library", "3 Library"), + ("downloads", "4 Downloads"), + ("settings", "5 Settings"), +) + + +class NavigationItem(Static): + """Lightweight mouse navigation without themed button state styling.""" + + can_focus = False + + class Activated(Message): + def __init__(self, item: NavigationItem) -> None: + self.item = item + super().__init__() + + def __init__(self, label: str, section: str) -> None: + super().__init__(label, id=f"nav-{section}", markup=False) + self.section = section + + def on_click(self, event: Click) -> None: + self.post_message(self.Activated(self)) + + +class HubScreen(Screen[None]): + """Shared persistent application chrome for primary screens.""" + + def __init__(self, section: str, title: str) -> None: + super().__init__(id=f"screen-{section}") + self.section = section + self.title = title + + def compose_content(self) -> Iterable[Widget]: + return () + + def compose(self) -> ComposeResult: + yield Static("999 · Juice WRLD Music Hub", id="brand") + with Horizontal(id="primary-navigation"): + for section, label in _SECTIONS: + current = section == self.section + item = NavigationItem(f"[{label}]" if current else label, section) + if current: + item.add_class("-current") + yield item + with Container(id="screen-content"): + yield Static(self.title, id="screen-title") + yield from self.compose_content() + yield Static("1–5 Switch section r Refresh ? Help q Quit", id="status-footer") + + def on_resize(self, event: Resize) -> None: + self.set_class(event.size.width < 70, "-narrow") + self.set_class(event.size.height < 30, "-short") diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py new file mode 100644 index 0000000..111e435 --- /dev/null +++ b/src/juice_lyrics/tui/screens/browse.py @@ -0,0 +1,1063 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass, replace +from math import ceil +from typing import Any + +from rich.text import Text +from textual import work +from textual.app import ComposeResult +from textual.binding import Binding +from textual.containers import Container, Grid, Vertical, VerticalScroll +from textual.events import Click, Key, Resize, ScreenResume +from textual.geometry import Region +from textual.message import Message +from textual.screen import ModalScreen +from textual.widget import Widget +from textual.widgets import Input, Select, Static +from textual.worker import Worker, WorkerState + +from ...services.catalogue import ( + CatalogueFilterMetadata, + CataloguePage, + CatalogueSearchResult, + LyricAvailability, + SongDetails, +) +from ...services.download_queue import ( + QueueAddPlan, + QueueAddResult, + QueueAddStatus, + QueueBatchAddItemStatus, + QueueBatchAddPlan, + QueueBatchAddResult, + QueueBatchAddStatus, +) +from .base import HubScreen + +SearchProvider = Callable[..., CataloguePage | tuple[CatalogueSearchResult, ...]] +DetailsProvider = Callable[..., SongDetails | None] +FiltersProvider = Callable[..., CatalogueFilterMetadata] +QueuePlanResult = QueueAddResult | QueueBatchAddResult +QueuePlan = QueueAddPlan | QueueBatchAddPlan +QueuePlanProvider = Callable[..., QueuePlanResult] +QueueAddProvider = Callable[[QueuePlan], QueuePlanResult] +_PREVIEW_LINES = 6 +_PAGE_SIZE = 50 + + +class BrowseInput(Input): + """Filter input that preserves the shell's global numeric navigation.""" + + def on_key(self, event: Key) -> None: + if event.key == "escape": + self.screen.set_focus(None) + event.prevent_default() + event.stop() + return + if event.key == "question_mark": + self.app.action_show_help() + event.prevent_default() + event.stop() + return + if event.key == "slash": + self.screen.action_focus_search() + event.prevent_default() + event.stop() + return + + +class BrowseSelect(Select[str]): + """Catalogue selector that preserves global section shortcuts.""" + + def on_key(self, event: Key) -> None: + if event.key == "question_mark": + self.app.action_show_help() + event.prevent_default() + event.stop() + return + if event.key == "slash": + self.screen.action_focus_search() + event.prevent_default() + event.stop() + return + if event.key in "12345": + sections = ("dashboard", "browse", "library", "downloads", "settings") + self.app.action_show_section(sections[int(event.key) - 1]) + event.prevent_default() + event.stop() + + +class PaginationControl(Static): + """Non-focusable terminal-native previous/next page control.""" + + can_focus = False + + class Activated(Message): + def __init__(self, item: PaginationControl) -> None: + self.item = item + super().__init__() + + def __init__(self, label: str, direction: int, *, id: str) -> None: + super().__init__(label, id=id, markup=False) + self.label = label + self.direction = direction + self.available = False + + def set_available(self, available: bool) -> None: + self.available = available + self.set_class(available, "-available") + self.set_class(not available, "-unavailable") + self.update(Text(f"[{self.label}]")) + + def on_click(self, event: Click) -> None: + if self.available: + self.post_message(self.Activated(self)) + + +@dataclass(frozen=True, slots=True) +class SearchRequest: + query: str + category: str | None + era: str | None + page: int + refresh: bool + + +@dataclass(frozen=True, slots=True) +class SearchOutcome: + request: SearchRequest + page: CataloguePage | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class DetailsOutcome: + result: CatalogueSearchResult + details: SongDetails | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class FiltersOutcome: + metadata: CatalogueFilterMetadata | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class QueuePlanOutcome: + selections: tuple[CatalogueSearchResult, ...] + result: QueuePlanResult | None = None + marked: bool = False + error: str | None = None + + +class QueueDialogAction(Static): + can_focus = True + + class Activated(Message): + def __init__(self, action: str) -> None: + self.action = action + super().__init__() + + def __init__(self, label: str, action: str, *, id: str) -> None: + super().__init__(label, id=id, markup=False) + self.action = action + + def on_click(self, event: Click) -> None: + self.post_message(self.Activated(self.action)) + + +class AddToQueueDialog(ModalScreen[QueuePlanResult | None]): + """Explicit, cancel-first confirmation for one or more queue additions.""" + + def __init__(self, plan: QueuePlan, creator: QueueAddProvider, *, batch: bool = False) -> None: + super().__init__() + self.plan = plan + self._batch = batch + self._creator = creator + self._choice = "cancel" + self._creating = False + self._created_result: QueuePlanResult | None = None + self._worker: Worker[QueuePlanResult] | None = None + + @property + def _is_batch(self) -> bool: + return self._batch + + @property + def _add_label(self) -> str: + return "Add selected" if self._is_batch else "Add to queue" + + def compose(self) -> ComposeResult: + with Container(id="queue-confirm-dialog"): + if self._is_batch and isinstance(self.plan, QueueBatchAddPlan): + count = self.plan.selected_count + title = f"Add {count} selected song{'s' if count != 1 else ''} to Downloads" + else: + title = "Add to download queue" + yield Static(title, id="queue-confirm-title") + yield Static(self._body_text(), id="queue-confirm-body", markup=False) + yield Static("Choose an action.", id="queue-confirm-status", markup=False) + with Grid(id="queue-confirm-actions"): + yield QueueDialogAction(self._add_label, "confirm", id="queue-confirm-add") + yield QueueDialogAction("Cancel", "cancel", id="queue-confirm-cancel") + + def _body_text(self) -> str: + if not self._is_batch: + planned = self.plan.items[0] if isinstance(self.plan, QueueAddPlan) else self.plan.eligible[0] + item = planned.item + return f"Add this song to Downloads?\n\n{item.title}\n\nThis does not start downloading." + preview = [item.title for item in self.plan.items[:3]] + if self.plan.selected_count > len(preview): + preview.append(f"…and {self.plan.selected_count - len(preview)} more") + queued = self.plan.count(QueueBatchAddItemStatus.ALREADY_QUEUED) + unavailable = self.plan.count(QueueBatchAddItemStatus.UNAVAILABLE) + self.plan.count(QueueBatchAddItemStatus.STALE) + local = self.plan.count(QueueBatchAddItemStatus.ALREADY_DOWNLOADED) + invalid = self.plan.count(QueueBatchAddItemStatus.INVALID) + count = self.plan.eligible_count + lines = [f"Add {count} song{'s' if count != 1 else ''} to Downloads?"] + skipped = queued + unavailable + invalid + local + if skipped: + lines.extend(("", f"{skipped} selected song{'s' if skipped != 1 else ''} will be skipped.")) + if preview: + lines.extend(("", *preview)) + lines.extend(("", "This does not start downloading.")) + return "\n".join(lines) + + def on_mount(self) -> None: + self._render_choice() + self.query_one("#queue-confirm-cancel", QueueDialogAction).focus() + + def _render_choice(self) -> None: + if self._created_result is not None: + self.query_one("#queue-confirm-add", Static).update("[v View Downloads]") + self.query_one("#queue-confirm-cancel", Static).update("[Enter Close]") + return + add = f"[{self._add_label}]" if self._choice == "confirm" else self._add_label + cancel = "[Cancel]" if self._choice == "cancel" else "Cancel" + self.query_one("#queue-confirm-add", Static).update(add) + self.query_one("#queue-confirm-cancel", Static).update(cancel) + + def on_queue_dialog_action_activated(self, event: QueueDialogAction.Activated) -> None: + if self._created_result is not None: + if event.action == "confirm": + self._view_downloads() + else: + self.dismiss(self._created_result) + return + self._choice = event.action + self._render_choice() + self._activate_choice() + + def on_key(self, event: Key) -> None: + if self._creating: + event.prevent_default() + event.stop() + return + if self._created_result is not None: + if event.key == "v": + self._view_downloads() + elif event.key in {"enter", "escape"}: + self.dismiss(self._created_result) + else: + return + elif event.key in {"escape", "n"}: + self.dismiss(None) + elif event.key == "y": + self._choice = "confirm" + self._render_choice() + self._activate_choice() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + self.query_one( + "#queue-confirm-add" if self._choice == "confirm" else "#queue-confirm-cancel", + QueueDialogAction, + ).focus() + elif event.key == "enter": + self._activate_choice() + else: + return + event.prevent_default() + event.stop() + + def _activate_choice(self) -> None: + if self._choice == "cancel": + self.dismiss(None) + return + if self._creating: + return + self._creating = True + self.query_one("#queue-confirm-status", Static).update("Adding to queue…") + self._worker = self._create_queue_item() + + @work(thread=True, exclusive=True, group="queue-add", exit_on_error=False) + def _create_queue_item(self) -> QueuePlanResult: + try: + return self._creator(self.plan) + except Exception as exc: + if isinstance(self.plan, QueueBatchAddPlan): + return QueueBatchAddResult(QueueBatchAddStatus.SAVE_FAILED, f"Unable to save Downloads: {exc}", plan=self.plan) + return QueueAddResult(QueueAddStatus.SAVE_FAILED, f"Unable to save the queue: {exc}") + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is not self._worker: + return + if event.state is WorkerState.SUCCESS: + result = event.worker.result + elif event.state is WorkerState.ERROR: + result = ( + QueueBatchAddResult(QueueBatchAddStatus.SAVE_FAILED, "Unable to save Downloads.", plan=self.plan) + if isinstance(self.plan, QueueBatchAddPlan) + else QueueAddResult(QueueAddStatus.SAVE_FAILED, "Unable to save the queue.") + ) + else: + return + self._creating = False + if result.status in {QueueAddStatus.ADDED, QueueBatchAddStatus.ADDED}: + self._created_result = result + invalidate = getattr(self.app, "invalidate_download_queue", None) + if callable(invalidate): + invalidate() + self.query_one("#queue-confirm-status", Static).update( + f"{result.message} Nothing has started." + ) + self._render_choice() + else: + self._choice = "cancel" + self.query_one("#queue-confirm-status", Static).update(result.message) + self._render_choice() + + def _view_downloads(self) -> None: + result = self._created_result + self.dismiss(result) + if result is not None: + self.app.call_after_refresh(self.app.action_show_section, "downloads") + + +class BrowseScreen(HubScreen): + """Interactive, read-only catalogue search and song-details screen.""" + + BINDINGS = [Binding("/", "focus_search", "Search", show=False)] + + def __init__( + self, + settings: Any, + *, + search_provider: SearchProvider, + details_provider: DetailsProvider, + filters_provider: FiltersProvider, + queue_plan_provider: QueuePlanProvider, + queue_add_provider: QueueAddProvider, + ) -> None: + super().__init__("browse", "Browse") + self.settings = settings + self._search_provider = search_provider + self._details_provider = details_provider + self._filters_provider = filters_provider + self._queue_plan_provider = queue_plan_provider + self._queue_add_provider = queue_add_provider + self.results: tuple[CatalogueSearchResult, ...] = () + self.current_page: CataloguePage | None = None + self.selected_index = 0 + self.last_request: SearchRequest | None = None + self._search_worker: Worker[SearchOutcome] | None = None + self._details_worker: Worker[DetailsOutcome] | None = None + self._filters_worker: Worker[FiltersOutcome] | None = None + self._queue_plan_worker: Worker[QueuePlanOutcome] | None = None + self._queue_add_worker: Worker[QueuePlanResult] | None = None + self._applying_filters = False + self.marked: dict[str, CatalogueSearchResult] = {} + self._marked_pages: dict[str, int] = {} + self._pending_add_ids: tuple[str, ...] = () + self._selection_notice: str | None = None + + def compose_content(self) -> Iterable[Widget]: + with Grid(id="browse-controls"): + with Vertical(classes="browse-filter"): + yield Static("Search", classes="filter-label") + yield BrowseInput(placeholder="Optional song title", id="browse-query") + with Vertical(classes="browse-filter"): + yield Static("Category", classes="filter-label") + yield BrowseSelect([("Loading…", "")], allow_blank=False, id="browse-category", disabled=True) + with Vertical(classes="browse-filter"): + yield Static("Era", classes="filter-label") + yield BrowseSelect([("Loading…", "")], allow_blank=False, id="browse-era", disabled=True) + yield Static("Enter a title or choose at least one filter.", id="browse-status", markup=False) + with Grid(id="browse-main"): + with Container(classes="browse-panel", id="browse-results-panel"): + yield Static("Results · 0 loaded", classes="panel-title", id="browse-results-title") + with VerticalScroll(id="browse-results-scroll"): + yield Static("No search yet.", id="browse-results", markup=False) + with Container(classes="browse-panel", id="browse-details-panel"): + yield Static("Details", classes="panel-title") + with VerticalScroll(id="browse-details-scroll"): + yield Static("Select a result to inspect it.", id="browse-details", markup=False) + with Grid(id="browse-pagination"): + yield PaginationControl("p Previous", -1, id="browse-previous") + yield Static("No catalogue page loaded", id="browse-page-position", markup=False) + yield PaginationControl("n Next", 1, id="browse-next") + yield Static("↑↓ Move · Enter Details · Space Mark · a Add · ? Help", id="browse-shortcuts", markup=False) + + def action_focus_search(self) -> None: + self.query_one("#browse-query", Input).focus() + + def on_input_submitted(self, event: Input.Submitted) -> None: + self.submit_search(refresh=False) + self.set_focus(None) + + def on_select_changed(self, event: Select.Changed) -> None: + if not self._applying_filters and not event.select.disabled: + self.submit_search(refresh=False) + + def on_screen_resume(self, event: ScreenResume) -> None: + if self._filters_worker is None: + self._filters_worker = self._load_filters() + self.call_after_refresh(self.set_focus, None) + self._update_shortcuts() + + def submit_search(self, *, refresh: bool) -> None: + query = self.query_one("#browse-query", Input).value.strip() + category = _select_value(self.query_one("#browse-category", Select)) + era = _select_value(self.query_one("#browse-era", Select)) + if not query and not category and not era: + self._set_status("Enter a title or choose at least one filter.", error=True) + return + + request = SearchRequest(query, category, era, 1, refresh) + self._start_search(request) + + def _start_search(self, request: SearchRequest) -> None: + changed = self.last_request is not None and self._logical_search(self.last_request) != self._logical_search(request) + cleared = len(self.marked) if changed else 0 + if changed: + self.marked.clear() + self._marked_pages.clear() + if cleared: + self._selection_notice = "Selection cleared because the search changed" + self.last_request = request + self.set_focus(None) + self.results = () + self.current_page = None + self.selected_index = 0 + self.query_one("#browse-results", Static).update("Searching…") + self.query_one("#browse-results-title", Static).update("Results · loading") + self.query_one("#browse-details", Static).update("Waiting for results…") + self.query_one("#browse-results-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + self._update_pagination(None, loading_page=request.page) + prefix = f"{self._selection_notice} · " if self._selection_notice else "" + self._set_status(prefix + self._loading_status(request)) + self._update_shortcuts() + self._search_worker = self._run_search(request) + + @staticmethod + def _logical_search(request: SearchRequest) -> tuple[str, str | None, str | None]: + return request.query, request.category, request.era + + def refresh_snapshot(self) -> None: + if self.last_request is None: + self.submit_search(refresh=True) + return + self.query_one("#browse-query", Input).value = self.last_request.query + self.query_one("#browse-category", Select).value = self.last_request.category or "" + self.query_one("#browse-era", Select).value = self.last_request.era or "" + self._start_search(SearchRequest( + self.last_request.query, + self.last_request.category, + self.last_request.era, + self.last_request.page, + True, + )) + + @work(thread=True, exclusive=True, group="catalogue-filters", exit_on_error=False) + def _load_filters(self) -> FiltersOutcome: + try: + return FiltersOutcome(self._filters_provider(self.settings, refresh=False)) + except Exception as exc: + return FiltersOutcome(error=str(exc) or type(exc).__name__) + + @work(thread=True, exclusive=True, group="catalogue-search", exit_on_error=False) + def _run_search(self, request: SearchRequest) -> SearchOutcome: + try: + results = self._search_provider( + self.settings, + request.query, + category=request.category, + era=request.era, + page=request.page, + page_size=_PAGE_SIZE, + refresh=request.refresh, + ) + if isinstance(results, CataloguePage): + page = results + else: + normalized = tuple(results) + page = CataloguePage(normalized, request.page, _PAGE_SIZE, len(normalized), None, None) + return SearchOutcome(request, page) + except Exception as exc: + return SearchOutcome(request, error=str(exc) or type(exc).__name__) + + @work(thread=True, exclusive=True, group="catalogue-details", exit_on_error=False) + def _run_details(self, result: CatalogueSearchResult) -> DetailsOutcome: + request = self.last_request + if request is None: + return DetailsOutcome(result, error="Search context is unavailable") + if result.song_id is None: + return DetailsOutcome(result, error="This result has no stable song ID") + try: + details = self._details_provider( + self.settings, + result.song_id, + selection_index=result.selection_index, + ) + return DetailsOutcome(result, details) + except Exception as exc: + return DetailsOutcome(result, error=str(exc) or type(exc).__name__) + + @work(thread=True, exclusive=True, group="queue-plan", exit_on_error=False) + def _plan_queue_add(self, selections: tuple[CatalogueSearchResult, ...], marked: bool) -> QueuePlanOutcome: + try: + result = self._queue_plan_provider(self.settings, selections) + return QueuePlanOutcome(selections, result, marked) + except Exception as exc: + return QueuePlanOutcome(selections, marked=marked, error=str(exc) or type(exc).__name__) + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is self._filters_worker: + if event.state is WorkerState.SUCCESS: + self._apply_filters(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_filters(FiltersOutcome(error="Filter options could not be loaded")) + elif event.worker is self._search_worker: + if event.state is WorkerState.SUCCESS: + self._apply_search(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_search(SearchOutcome( + self.last_request or SearchRequest("", None, None, 1, False), + error="Search stopped unexpectedly", + )) + elif event.worker is self._details_worker: + if event.state is WorkerState.SUCCESS: + self._apply_details(event.worker.result) + elif event.state is WorkerState.ERROR: + self.query_one("#browse-details", Static).update("Unable to load song details.") + elif event.worker is self._queue_plan_worker: + if event.state is WorkerState.SUCCESS: + self._apply_queue_plan(event.worker.result) + elif event.state is WorkerState.ERROR: + self._set_status("Unable to check the download queue.", error=True) + elif event.worker is self._queue_add_worker: + if event.state is WorkerState.SUCCESS: + self._queue_add_worker = None + self._queue_add_completed(event.worker.result) + elif event.state is WorkerState.ERROR: + self._queue_add_worker = None + self._set_status("Unable to add songs to Downloads.", error=True) + + def _apply_queue_plan(self, outcome: QueuePlanOutcome) -> None: + if self.app.screen is not self: + return + if not outcome.marked and ( + not self.results or not outcome.selections or self.results[self.selected_index] != outcome.selections[0] + ): + self._set_status("Selection changed; press a again to add the current song.", error=True) + return + if outcome.error or outcome.result is None: + self._set_status(f"Unable to check the queue: {outcome.error or 'Unknown error'}", error=True) + return + ready = outcome.result.status in {QueueAddStatus.READY, QueueBatchAddStatus.READY} + if not ready or outcome.result.plan is None: + self._set_status(outcome.result.message, error=True) + return + if outcome.marked and len(outcome.selections) > 1 and not isinstance(outcome.result.plan, QueueBatchAddPlan): + self._set_status("The queue provider cannot safely add several selected songs.", error=True) + return + if self._queue_add_worker is not None: + self._set_status("Songs are already being added to Downloads.") + return + self._pending_add_ids = tuple( + str(selection.song_id) for selection in outcome.selections if selection.song_id is not None + ) + self._set_status("Adding to Downloads…") + self._queue_add_worker = self._create_queue_item(outcome.result.plan) + + @work(thread=True, exclusive=True, group="queue-add", exit_on_error=False) + def _create_queue_item(self, plan: QueuePlan) -> QueuePlanResult: + return self._queue_add_provider(plan) + + def _queue_add_completed(self, result: QueuePlanResult) -> None: + if result.status in {QueueAddStatus.ADDED, QueueBatchAddStatus.ADDED}: + for song_id in self._pending_add_ids: + self.marked.pop(song_id, None) + self._marked_pages.pop(song_id, None) + self._set_status(f"{result.message} It has not started. Press 4 to view Downloads.") + invalidate = getattr(self.app, "invalidate_download_queue", None) + if callable(invalidate): + invalidate() + self._render_results() + self._update_shortcuts() + else: + self._set_status(result.message, error=True) + self._pending_add_ids = () + + def _apply_search(self, outcome: SearchOutcome) -> None: + if outcome.error: + self.results = () + self.current_page = None + self.query_one("#browse-results", Static).update("Search unavailable.") + self.query_one("#browse-results-title", Static).update("Results · unavailable") + self.query_one("#browse-details", Static).update("No song selected.") + self._update_pagination(None) + self._set_status(f"Search failed: {outcome.error}", error=True) + return + + page = outcome.page or CataloguePage((), outcome.request.page, _PAGE_SIZE, 0, None, None) + self.current_page = page + self.results = page.results + self.selected_index = 0 + visible = { + key: result + for result in self.results + if (key := self._song_key(result)) is not None + } + for key, marked_page in tuple(self._marked_pages.items()): + if marked_page != page.page: + continue + if key in visible: + self.marked[key] = visible[key] + elif key in self.marked: + self.marked[key] = replace(self.marked[key], media_path=None, downloadable=False) + self._update_results_title() + self._update_pagination(page) + if not self.results: + self.query_one("#browse-results", Static).update("No catalogue results found.") + if outcome.request.page > 1: + self.query_one("#browse-details", Static).update("Return to the previous or first page.") + self._set_status(f"Page {outcome.request.page} is no longer available.", error=True) + else: + self.query_one("#browse-details", Static).update("Try another title or filter.") + self._set_status(self._with_selection_notice(_empty_result_status(outcome.request))) + return + + self._render_results() + self._render_summary(self.results[0]) + self._set_status(self._with_selection_notice(self._result_status(outcome.request, page))) + self._update_shortcuts() + self.call_after_refresh(self._scroll_selection_into_view) + + def _apply_filters(self, outcome: FiltersOutcome) -> None: + category = self.query_one("#browse-category", Select) + era = self.query_one("#browse-era", Select) + if outcome.error or outcome.metadata is None: + category.set_options([("Unavailable", "")]) + era.set_options([("Unavailable", "")]) + category.disabled = era.disabled = True + self._set_status(f"Filter metadata unavailable: {outcome.error or 'Unknown error'}. Title search remains available.", error=True) + return + self._applying_filters = True + category.set_options([("All", ""), *((item.label, item.value) for item in outcome.metadata.categories)]) + era.set_options([("All", ""), *((item.label, item.value) for item in outcome.metadata.eras)]) + category.value = era.value = "" + self._applying_filters = False + category.disabled = era.disabled = False + if self.last_request is None: + self._set_status("Enter an optional title or choose filters, then press / and Enter.") + + def _apply_details(self, outcome: DetailsOutcome) -> None: + if not self.results or self.results[self.selected_index] != outcome.result: + return + if outcome.error: + self.query_one("#browse-details", Static).update(f"Unable to load details: {outcome.error}") + elif outcome.details is None: + self.query_one("#browse-details", Static).update("No additional details are available.") + else: + self.query_one("#browse-details", Static).update(self._details_text(outcome.details)) + + def on_key(self, event: Key) -> None: + if any(select.expanded for select in self.query(Select)): + return + if isinstance(self.app.focused, (Input, Select)): + return + if event.key in ("down", "j"): + self._move_selection(1) + elif event.key in ("up", "k"): + self._move_selection(-1) + elif event.key == "enter": + self._load_selected_details() + elif event.key == "a": + self._add_selected_to_queue() + elif event.key == "space": + self._toggle_mark() + elif event.key in {"M", "shift+m"}: + self._toggle_page_marks() + elif event.key == "u": + self._clear_marks() + elif event.key == "n": + self._change_page(next_page=True) + elif event.key == "p": + self._change_page(next_page=False) + elif event.key == "pagedown": + self._move_viewport(1) + elif event.key == "pageup": + self._move_viewport(-1) + elif event.key == "home": + self._select_index(0) + elif event.key == "end": + self._select_index(len(self.results) - 1) + else: + return + event.prevent_default() + event.stop() + + def _add_selected_to_queue(self) -> None: + if (self._queue_plan_worker is not None and not self._queue_plan_worker.is_finished) or self._queue_add_worker is not None: + self._set_status("Songs are already being added to Downloads.") + return + if self.marked: + selections = tuple(self.marked.values()) + marked = True + elif self.results: + selections = (self.results[self.selected_index],) + marked = False + else: + self._set_status("Select a downloadable song first.", error=True) + return + if not marked and not selections[0].downloadable: + self._set_status("Media unavailable; this song cannot be added to the queue.", error=True) + return + count = len(selections) + self._set_status( + "Checking destination and download queue…" + if count == 1 + else f"Checking {count} selected songs and Downloads…" + ) + self._queue_plan_worker = self._plan_queue_add(selections, marked) + + @staticmethod + def _song_key(result: CatalogueSearchResult) -> str | None: + return str(result.song_id) if result.song_id is not None else None + + def _toggle_mark(self) -> None: + if not self.results: + return + result = self.results[self.selected_index] + key = self._song_key(result) + if key is None or not result.downloadable: + self._set_status("Media unavailable; this result cannot be marked.", error=True) + return + if key in self.marked: + self.marked.pop(key) + self._marked_pages.pop(key, None) + else: + self.marked[key] = result + self._marked_pages[key] = self.current_page.page if self.current_page is not None else 1 + self._render_results() + self._update_results_title() + self._update_shortcuts() + if self.current_page is not None and self.last_request is not None: + self._set_status(self._result_status(self.last_request, self.current_page)) + + def _toggle_page_marks(self) -> None: + eligible = tuple(result for result in self.results if result.downloadable and self._song_key(result) is not None) + if not eligible: + self._set_status("No downloadable songs are visible on this page.", error=True) + return + all_marked = all(self._song_key(result) in self.marked for result in eligible) + for result in eligible: + key = self._song_key(result) + if key is None: + continue + if all_marked: + self.marked.pop(key, None) + self._marked_pages.pop(key, None) + else: + self.marked[key] = result + self._marked_pages[key] = self.current_page.page if self.current_page is not None else 1 + self._render_results() + self._update_results_title() + self._update_shortcuts() + self._set_status(self._marked_label() if self.marked else "Selection cleared.") + + def _clear_marks(self) -> None: + if not self.marked: + self._set_status("No songs are marked.") + return + self.marked.clear() + self._marked_pages.clear() + self._render_results() + self._update_results_title() + self._update_shortcuts() + self._set_status("Selection cleared.") + + def _change_page(self, *, next_page: bool) -> None: + if self.current_page is None or self.last_request is None: + return + page = self.current_page.next_page if next_page else self.current_page.previous_page + if page is None: + self.notify("No next page." if next_page else "Already on the first page.") + return + self._start_search(SearchRequest( + self.last_request.query, + self.last_request.category, + self.last_request.era, + page, + False, + )) + + def on_pagination_control_activated(self, event: PaginationControl.Activated) -> None: + self._change_page(next_page=event.item.direction > 0) + + def _move_selection(self, amount: int) -> None: + if not self.results: + return + self._select_index(self.selected_index + amount) + + def _move_viewport(self, direction: int) -> None: + scroll = self.query_one("#browse-results-scroll", VerticalScroll) + row_height = 2 if "-narrow" in self.classes else 1 + visible_rows = max(1, scroll.size.height // row_height) + self._select_index(self.selected_index + direction * max(1, visible_rows - 1)) + + def _select_index(self, index: int) -> None: + if not self.results: + return + self.selected_index = max(0, min(len(self.results) - 1, index)) + self._render_results() + self._render_summary(self.results[self.selected_index]) + self._update_shortcuts() + if self.last_request is not None and self.current_page is not None: + self._set_status(self._result_status(self.last_request, self.current_page)) + self.call_after_refresh(self._scroll_selection_into_view) + + def _scroll_selection_into_view(self) -> None: + if not self.results: + return + scroll = self.query_one("#browse-results-scroll", VerticalScroll) + row_height = 2 if "-narrow" in self.classes else 1 + row_y = self.selected_index * row_height + scroll.scroll_to_region( + Region(0, row_y, max(1, scroll.virtual_size.width), row_height), + animate=False, + immediate=True, + x_axis=False, + ) + + def _load_selected_details(self) -> None: + if not self.results: + return + result = self.results[self.selected_index] + self.query_one("#browse-details", Static).update("Loading full details…") + self._details_worker = self._run_details(result) + + def _render_results(self) -> None: + narrow = "-narrow" in self.classes + lines: list[str] = [] + for index, result in enumerate(self.results): + marker = ">" if index == self.selected_index else " " + song_key = self._song_key(result) + marked = ( + "[x]" if song_key is not None and song_key in self.marked else "[ ]" + ) if self.marked else "" + title = result.title or "Unknown title" + era = result.era or "Unknown era" + category = result.category or "Unknown category" + lyrics = _lyrics_label(result.lyrics) + available = "Available" if result.downloadable else "Unavailable" + if narrow: + suffix = f" {marked}" if marked else "" + lines.extend((f"{marker} {title}{suffix}", f" {era} · {category} · {lyrics} · {available}")) + else: + length = result.length or "?" + lines.append( + f"{marker} {title[:26]:26}{f' {marked}' if marked else ' '} {era[:10]:10} {category[:12]:12} " + f"{length[:7]:7} {lyrics:6} {available}" + ) + self.query_one("#browse-results", Static).update( + Text("\n".join(lines), no_wrap=True, overflow="ellipsis") + ) + + def _update_pagination(self, page: CataloguePage | None, *, loading_page: int | None = None) -> None: + previous = self.query_one("#browse-previous", PaginationControl) + next_control = self.query_one("#browse-next", PaginationControl) + position = self.query_one("#browse-page-position", Static) + if page is None: + previous.set_available(False) + next_control.set_available(False) + position.update( + f"Page {loading_page} · Loading…" + if loading_page + else "No catalogue page loaded" + ) + return + previous.set_available(page.previous_page is not None) + next_control.set_available(page.next_page is not None) + page_count = max(1, ceil(page.total_count / page.page_size)) + if page.results: + position.update( + f"Page {page.page} of {page_count} · " + f"Results {page.range_start}–{page.range_end} of {page.total_count:,}" + ) + else: + position.update(f"Page {page.page} of {page_count} · No results") + + def _render_summary(self, result: CatalogueSearchResult) -> None: + artists = ", ".join(result.artists) or "Unknown" + producers = ", ".join(result.producers) or "Unknown" + path = result.media_path or "Unavailable" + lyrics = _lyrics_label(result.lyrics) + download = "Available" if result.downloadable else "Unavailable" + lines = ( + result.title or "Unknown title", + "", + f"ID {result.song_id if result.song_id is not None else 'Unknown'}", + f"Era {result.era or 'Unknown'}", + f"Category {result.category or 'Unknown'}", + f"Length {result.length or 'Unknown'}", + f"Artists {artists}", + f"Producers {producers}", + f"Lyrics {lyrics}", + f"Download {download}", + f"Path {path}", + "", + "Press Enter for full details and lyric preview.", + ( + f"Press a to add {len(self.marked)} selected song{'s' if len(self.marked) != 1 else ''} to Downloads." + if self.marked + else "Press a to add this song to Downloads." + ) if result.downloadable else "Media unavailable.", + ) + self.query_one("#browse-details", Static).update("\n".join(lines)) + + def _details_text(self, details: SongDetails) -> str: + lyrics = _lyrics_label(details.lyrics) + preview = _lyric_preview(details) + return "\n".join(( + details.title or "Unknown title", + "", + f"ID {details.song_id if details.song_id is not None else 'Unknown'}", + f"Era {details.era or 'Unknown'}", + f"Category {details.category or 'Unknown'}", + f"Length {details.length or 'Unknown'}", + f"Artists {', '.join(details.artists) or 'Unknown'}", + f"Producers {', '.join(details.producers) or 'Unknown'}", + f"Lyrics {lyrics}", + f"Download {'Available' if details.downloadable else 'Unavailable'}", + f"Path {details.media_path or 'Unavailable'}", + "", + "Lyrics preview", + preview, + )) + + def _set_status(self, message: str, *, error: bool = False) -> None: + status = self.query_one("#browse-status", Static) + status.update(message) + status.set_class(error, "-error") + + def _marked_label(self) -> str: + count = len(self.marked) + return f"{count} song{'s' if count != 1 else ''} marked" + + def _with_selection_notice(self, message: str) -> str: + if self._selection_notice is None: + return message + notice = self._selection_notice + self._selection_notice = None + return f"{notice} · {message}" + + def _update_results_title(self) -> None: + title = f"Results · {len(self.results)} loaded" + if self.marked: + title += f" · {self._marked_label()}" + self.query_one("#browse-results-title", Static).update(title) + + def _update_shortcuts(self) -> None: + try: + shortcuts = self.query_one("#browse-shortcuts", Static) + except Exception: + return + count = len(self.marked) + narrow = self.size.width < 100 + current_key = self._song_key(self.results[self.selected_index]) if self.results else None + toggle = "Unmark" if current_key is not None and current_key in self.marked else "Mark" + if narrow: + text = ( + f"Space {toggle.lower()} · a add selected · ? help" + if count + else "↑↓ move · Enter details · a add · ? help" + ) + elif count: + text = f"↑↓ Move · Enter Details · Space {toggle} · a Add selected · ? Help" + else: + text = "↑↓ Move · Enter Details · Space Mark · a Add · ? Help" + shortcuts.update(Text(text, no_wrap=True, overflow="ellipsis")) + + @staticmethod + def _loading_status(request: SearchRequest) -> str: + if request.query: + return f'Searching for "{request.query}"…{_filter_text(request.category, request.era)}' + return f"Searching: {_filter_values(request.category, request.era)}…" + + def _result_status(self, request: SearchRequest, page: CataloguePage) -> str: + filters = _filter_text(request.category, request.era) + selected = min(len(page.results), self.selected_index + 1) + marked = f" · {self._marked_label()}" if self.marked else "" + return ( + f"Result {selected} of {len(page.results)} loaded{marked}." + f"{filters}" + ) + + def on_resize(self, event: Resize) -> None: + super().on_resize(event) + self._update_shortcuts() + if self.results: + self._render_results() + self.call_after_refresh(self._scroll_selection_into_view) + + +def _lyrics_label(value: LyricAvailability) -> str: + return { + LyricAvailability.SYNCED: "Synced", + LyricAvailability.PLAIN: "Plain", + LyricAvailability.NONE: "None", + }[value] + + +def _filter_text(category: str | None, era: str | None) -> str: + values = _filter_values(category, era) + return f" Filters: {values}." if values else " Filters: All." + + +def _filter_values(category: str | None, era: str | None) -> str: + values = [] + if category: + values.append(f"category={category}") + if era: + values.append(f"era={era}") + return ", ".join(values) + + +def _empty_result_status(request: SearchRequest) -> str: + if request.query: + return f'No results for "{request.query}".{_filter_text(request.category, request.era)}' + return f"No results for filters: {_filter_values(request.category, request.era)}." + + +def _select_value(select: Select) -> str | None: + value = select.value + return value if isinstance(value, str) and value else None + + +def _lyric_preview(details: SongDetails) -> str: + if details.lyrics is LyricAvailability.SYNCED: + text = details.synced_lyrics or "" + elif details.lyrics is LyricAvailability.PLAIN: + text = details.plain_lyrics or "" + else: + return "No lyrics available." + lines = text.splitlines() + preview = lines[:_PREVIEW_LINES] + if len(lines) > _PREVIEW_LINES: + preview.append("…") + return "\n".join(preview) if preview else "No lyrics available." diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py new file mode 100644 index 0000000..b770361 --- /dev/null +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -0,0 +1,148 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from typing import Any + +from textual import work +from textual.containers import Container, Grid +from textual.events import ScreenResume +from textual.widget import Widget +from textual.widgets import Static +from textual.worker import Worker, WorkerState + +from ...services import LibraryStatus, QueueSnapshot +from .base import HubScreen + + +class DashboardScreen(HubScreen): + """Read-only summary assembled exclusively from application services.""" + + def __init__( + self, + settings: Any, + *, + library_status_provider: Callable[[Any], LibraryStatus], + queue_snapshot_provider: Callable[[], QueueSnapshot], + ) -> None: + super().__init__("dashboard", "Dashboard") + self.settings = settings + self._library_status_provider = library_status_provider + self._queue_snapshot_provider = queue_snapshot_provider + self._refresh_worker: Worker[tuple[LibraryStatus | None, str | None]] | None = None + self._queue_worker: Worker[tuple[QueueSnapshot | None, str | None]] | None = None + self._invalidated = False + + def compose_content(self) -> Iterable[Widget]: + with Grid(id="dashboard-panels"): + with Container(classes="dashboard-panel", id="library-panel"): + yield Static("Library", classes="panel-title") + yield Static("Loading…", id="library-data", markup=False) + yield Static("", id="library-error", classes="panel-error", markup=False) + with Container(classes="dashboard-panel", id="downloads-panel"): + yield Static("Downloads", classes="panel-title") + yield Static("Loading…", id="queue-data", markup=False) + yield Static("", id="queue-error", classes="panel-error", markup=False) + + def on_mount(self) -> None: + self.refresh_snapshot() + + def on_screen_resume(self, event: ScreenResume) -> None: + if self._invalidated: + self.refresh_snapshot() + + def refresh_snapshot(self) -> None: + self._invalidated = False + self.query_one("#library-data", Static).update("Loading library status…") + self.query_one("#queue-data", Static).update("Loading queue status…") + self.query_one("#library-error", Static).update("") + self.query_one("#queue-error", Static).update("") + self._refresh_worker = self._load_library() + self._queue_worker = self._load_queue() + + def invalidate_snapshot(self) -> None: + self._invalidated = True + + @work( + thread=True, + exclusive=True, + group="dashboard-library", + exit_on_error=False, + ) + def _load_library(self) -> tuple[LibraryStatus | None, str | None]: + try: + return self._library_status_provider(self.settings), None + except Exception as exc: + return None, str(exc) or type(exc).__name__ + + @work(thread=True, exclusive=True, group="dashboard-queue", exit_on_error=False) + def _load_queue(self) -> tuple[QueueSnapshot | None, str | None]: + try: + return self._queue_snapshot_provider(), None + except Exception as exc: + return None, str(exc) or type(exc).__name__ + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is self._refresh_worker: + if event.state is WorkerState.SUCCESS: + self._render_library(*event.worker.result) + elif event.state is WorkerState.ERROR: + message = str(event.worker.error) if event.worker.error else "Unable to load library data" + self._render_library(None, message) + elif event.worker is self._queue_worker: + if event.state is WorkerState.SUCCESS: + self._render_queue(*event.worker.result) + elif event.state is WorkerState.ERROR: + message = str(event.worker.error) if event.worker.error else "Unable to load queue data" + self._render_queue(None, message) + + def _render_library(self, status: LibraryStatus | None, failure: str | None) -> None: + error = self.query_one("#library-error", Static) + if status is None: + self.query_one("#library-data", Static).update( + "Library data unavailable\n\nPress 5 for Settings" + ) + error.update(f"Warning: {failure or 'Unknown library status error'}") + return + + lines = ( + f"Path {status.library_path}", + f"Audio tracks {status.track_count}", + f"Synced lyrics {status.embedded_synced_count}", + f"Plain lyrics {status.embedded_plain_count}", + f"Missing / invalid {status.missing_or_invalid_count}", + f"New / changed {status.new_or_changed_count}", + f"Backups {status.backup_count}", + f"rmpc LRC files {status.rmpc_lrc_count}", + ) + self.query_one("#library-data", Static).update("\n".join(lines)) + error.update("\n".join(status.warnings)) + + def _render_queue(self, snapshot: QueueSnapshot | None, failure: str | None) -> None: + error = self.query_one("#queue-error", Static) + if snapshot is None: + self.query_one("#queue-data", Static).update("Queue data unavailable") + error.update(f"Warning: {failure or 'Unknown queue status error'}") + return + + waiting = sum(job.pending_item_count for job in snapshot.jobs) + active = sum(job.active_item_count for job in snapshot.jobs) + failed = sum(job.failed_item_count for job in snapshot.jobs) + if not snapshot.jobs: + waiting = snapshot.pending_job_count + active = snapshot.active_job_count + failed = snapshot.failed_job_count + if waiting: + lines = ( + f"{waiting} song{'s' if waiting != 1 else ''} ready to download", + "", + "Press 4 to Downloads", + ) + elif active: + lines = ("Downloading now", "", "Press 4 to Downloads") + elif failed: + label = "1 song needs attention" if failed == 1 else f"{failed} songs need attention" + lines = (label, "", "Press 4 to Downloads") + else: + lines = ("Search for songs in Browse", "", "Press 2 to Browse") + self.query_one("#queue-data", Static).update("\n".join(lines)) + error.update("") diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py new file mode 100644 index 0000000..0c463aa --- /dev/null +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -0,0 +1,962 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass +from datetime import datetime + +from rich.text import Text +from textual import work +from textual.app import ComposeResult +from textual.containers import Container, Grid, VerticalScroll +from textual.events import Click, Key, Resize, ScreenResume +from textual.geometry import Region +from textual.message import Message +from textual.screen import ModalScreen +from textual.widget import Widget +from textual.widgets import Static +from textual.worker import Worker, WorkerState + +from ...services.download_queue import ( + DownloadExecutionPlan, + DownloadExecutionResult, + DownloadExecutionStatus, + DownloadProgress, + DownloadRetryPlan, + DownloadRetryResult, + DownloadRetryStatus, + DownloadAllPlan, + DownloadAllResult, + DownloadBatchStatus, + plan_download_all, + execute_download_all, + QueueMutationResult, + QueueMutationStatus, + remove_queue_item, + clear_download_queue, + clear_completed_history, + DownloadQueueItem, + DownloadQueueItemStatus, + DownloadQueueSnapshot, +) +from .base import HubScreen + +QueueProvider = Callable[[], DownloadQueueSnapshot] +PlanProvider = Callable[..., DownloadExecutionResult] +ExecutionProvider = Callable[..., DownloadExecutionResult] +RetryPlanProvider = Callable[..., DownloadRetryResult] +RetryExecutionProvider = Callable[..., DownloadRetryResult] +MutationProvider = Callable[..., QueueMutationResult] +BatchPlanProvider = Callable[..., DownloadAllPlan | DownloadAllResult] +BatchExecutionProvider = Callable[..., DownloadAllResult] + + +@dataclass(frozen=True, slots=True) +class QueueLoadOutcome: + snapshot: DownloadQueueSnapshot | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class ExecutionPlanOutcome: + reference: str + result: DownloadExecutionResult | None = None + error: str | None = None + + +class DownloadDialogAction(Static): + can_focus = True + + class Activated(Message): + def __init__(self, action: str) -> None: + self.action = action + super().__init__() + + def __init__(self, label: str, action: str, *, id: str) -> None: + super().__init__(label, id=id, markup=False) + self.action = action + + def on_click(self, event: Click) -> None: + self.post_message(self.Activated(self.action)) + + +class _CancelFirstModal: + """Shared focus and keyboard behavior for simple Downloads confirmations.""" + + confirm_label = "Confirm" + + def _setup_cancel_first(self) -> None: + self._choice = "cancel" + self._confirmed = False + + def _confirmation_result(self): + raise NotImplementedError + + def on_mount(self) -> None: + self._render_choice() + cancel = self.query_one("#download-confirm-cancel", DownloadDialogAction) + self.call_after_refresh(cancel.focus) + + def _render_choice(self) -> None: + confirm = f"[{self.confirm_label}]" if self._choice == "confirm" else self.confirm_label + cancel = "[Cancel]" if self._choice == "cancel" else "Cancel" + self.query_one("#download-confirm-download", Static).update(confirm) + self.query_one("#download-confirm-cancel", Static).update(cancel) + + def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: + if self._confirmed: + return + self._choice = event.action + self._render_choice() + self._activate_choice() + + def on_key(self, event: Key) -> None: + if self._confirmed: + event.prevent_default() + event.stop() + return + if event.key in {"escape", "n"}: + self._confirmed = True + self.dismiss(None) + elif event.key == "y": + self._choice = "confirm" + self._render_choice() + self._activate_choice() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + target = "#download-confirm-download" if self._choice == "confirm" else "#download-confirm-cancel" + self.query_one(target, DownloadDialogAction).focus() + elif event.key == "enter": + self._activate_choice() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + def _activate_choice(self) -> None: + if self._choice == "cancel": + self._confirmed = True + self.dismiss(None) + elif not self._confirmed: + self._confirmed = True + self.dismiss(self._confirmation_result()) + + +class DownloadSelectedDialog(ModalScreen[DownloadExecutionPlan | None]): + """Cancel-first confirmation for executing one selected queue track.""" + + def __init__(self, plan: DownloadExecutionPlan) -> None: + super().__init__() + self.plan = plan + self._choice = "cancel" + self._confirmed = False + + def compose(self) -> ComposeResult: + with Container(id="download-confirm-dialog"): + yield Static("Download selected", id="download-confirm-title") + yield Static( + f"Download {self.plan.title}?\n\nLyrics will be added automatically.", + id="download-confirm-body", + markup=False, + ) + with Grid(id="download-confirm-actions"): + yield DownloadDialogAction("Download", "confirm", id="download-confirm-download") + yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") + + def on_mount(self) -> None: + self._render_choice() + cancel = self.query_one("#download-confirm-cancel", DownloadDialogAction) + self.call_after_refresh(cancel.focus) + + def _render_choice(self) -> None: + download = "[Download]" if self._choice == "confirm" else "Download" + cancel = "[Cancel]" if self._choice == "cancel" else "Cancel" + self.query_one("#download-confirm-download", Static).update(download) + self.query_one("#download-confirm-cancel", Static).update(cancel) + + def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: + if self._confirmed: + return + self._choice = event.action + self._render_choice() + self._activate() + + def on_key(self, event: Key) -> None: + if self._confirmed: + event.prevent_default() + event.stop() + return + if event.key in {"escape", "n"}: + self.dismiss(None) + elif event.key == "y": + self._choice = "confirm" + self._render_choice() + self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + target = "#download-confirm-download" if self._choice == "confirm" else "#download-confirm-cancel" + self.query_one(target, DownloadDialogAction).focus() + elif event.key == "enter": + self._activate() + else: + return + event.prevent_default() + event.stop() + + def _activate(self) -> None: + if self._choice == "cancel": + self.dismiss(None) + return + if not self._confirmed: + self._confirmed = True + self.dismiss(self.plan) + + +class RetryFailedDialog(_CancelFirstModal, ModalScreen[DownloadRetryPlan | None]): + confirm_label = "Retry" + + def __init__(self, plan: DownloadRetryPlan) -> None: + super().__init__() + self.plan = plan + self._setup_cancel_first() + + def compose(self) -> ComposeResult: + with Container(id="download-confirm-dialog"): + yield Static("Try again", id="download-confirm-title") + yield Static( + f"Try {self.plan.title} again?\n\nPrevious problem: {self.plan.previous_failure}\n\nLyrics will be added automatically.", + id="download-confirm-body", + markup=False, + ) + with Grid(id="download-confirm-actions"): + yield DownloadDialogAction("Retry", "confirm", id="download-confirm-download") + yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") + + def _confirmation_result(self) -> DownloadRetryPlan: + return self.plan + + +class QueueCleanupDialog(ModalScreen[str | None]): + def __init__(self, action: str, body: str) -> None: + super().__init__() + self.action_name = action + self.body = body + self._choice = "cancel" + self._confirmed = False + def compose(self) -> ComposeResult: + with Container(id="download-confirm-dialog"): + yield Static(self.action_name, id="download-confirm-title") + yield Static(self.body, id="download-confirm-body", markup=False) + with Grid(id="download-confirm-actions"): + yield DownloadDialogAction(self.action_name, "confirm", id="download-confirm-download") + yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") + def on_mount(self) -> None: + self._render_choice() + cancel = self.query_one("#download-confirm-cancel", DownloadDialogAction) + self.call_after_refresh(cancel.focus) + + def _render_choice(self) -> None: + confirm = f"[{self.action_name}]" if self._choice == "confirm" else self.action_name + cancel = "[Cancel]" if self._choice == "cancel" else "Cancel" + self.query_one("#download-confirm-download", Static).update(confirm) + self.query_one("#download-confirm-cancel", Static).update(cancel) + + def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: + if self._confirmed: + return + self._choice = event.action + self._render_choice() + self._activate() + + def on_key(self, event: Key) -> None: + if self._confirmed: + event.prevent_default() + event.stop() + return + if event.key in {"escape", "n"}: + self._confirmed = True + self.dismiss(None) + elif event.key == "y": + self._choice = "confirm" + self._render_choice() + self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + target = "#download-confirm-download" if self._choice == "confirm" else "#download-confirm-cancel" + self.query_one(target, DownloadDialogAction).focus() + elif event.key == "enter": + self._activate() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + def _activate(self) -> None: + if self._choice == "cancel": + self._confirmed = True + self.dismiss(None) + elif not self._confirmed: + self._confirmed = True + self.dismiss(self.action_name) + + +class DownloadAllDialog(_CancelFirstModal, ModalScreen[DownloadAllPlan | None]): + confirm_label = "Download" + + def __init__(self, plan: DownloadAllPlan) -> None: + super().__init__() + self.plan = plan + self._setup_cancel_first() + + def compose(self) -> ComposeResult: + count = len(self.plan.eligible) + body = f"Download {count} {'song' if count == 1 else 'songs'}?\n\nLyrics will be added automatically." + skipped = self.plan.failed_count + self.plan.active_count + self.plan.skipped_count + if skipped: + body += f"\n\n{skipped} other {'song' if skipped == 1 else 'songs'} will be left alone." + with Container(id="download-confirm-dialog"): + yield Static("Download queue", id="download-confirm-title") + yield Static(body, id="download-confirm-body", markup=False) + with Grid(id="download-confirm-actions"): + yield DownloadDialogAction("Download", "confirm", id="download-confirm-download") + yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") + + def _confirmation_result(self) -> DownloadAllPlan: + return self.plan + + +class DownloadsScreen(HubScreen): + """Track-oriented view over the durable acquisition queue.""" + + def __init__( + self, + settings: object, + *, + queue_provider: QueueProvider, + plan_provider: PlanProvider, + execution_provider: ExecutionProvider, + retry_plan_provider: RetryPlanProvider, + retry_execution_provider: RetryExecutionProvider, + remove_provider: MutationProvider = remove_queue_item, + clear_provider: MutationProvider = clear_download_queue, + history_provider: MutationProvider = clear_completed_history, + batch_plan_provider: BatchPlanProvider = plan_download_all, + batch_execution_provider: BatchExecutionProvider = execute_download_all, + ) -> None: + super().__init__("downloads", "Downloads") + self.settings = settings + self._queue_provider = queue_provider + self._plan_provider = plan_provider + self._execution_provider = execution_provider + self._retry_plan_provider = retry_plan_provider + self._retry_execution_provider = retry_execution_provider + self._remove_provider = remove_provider + self._clear_provider = clear_provider + self._history_provider = history_provider + self._batch_plan_provider = batch_plan_provider + self._batch_execution_provider = batch_execution_provider + self.snapshot: DownloadQueueSnapshot | None = None + self.items: tuple[DownloadQueueItem, ...] = () + self.selected_index = 0 + self._details_mode = False + self._refresh_worker: Worker[QueueLoadOutcome] | None = None + self._plan_worker: Worker[ExecutionPlanOutcome] | None = None + self._execution_worker: Worker[DownloadExecutionResult] | None = None + self._retry_plan_worker: Worker[DownloadRetryResult] | None = None + self._retry_execution_worker: Worker[DownloadRetryResult] | None = None + self._mutation_worker: Worker[QueueMutationResult] | None = None + self._batch_plan_worker: Worker[DownloadAllPlan | DownloadAllResult] | None = None + self._batch_worker: Worker[DownloadAllResult] | None = None + self._active_reference: str | None = None + self._live_progress: DownloadProgress | None = None + self._completion_message: tuple[str, bool] | None = None + + def compose_content(self) -> Iterable[Widget]: + yield Static("Waiting 0 · Downloading 0 · Adding lyrics 0 · Failed 0 · Complete 0", id="downloads-summary", markup=False) + yield Static("Loading download queue…", id="downloads-status", markup=False) + with Grid(id="downloads-main"): + with Container(classes="downloads-panel", id="download-queue-panel"): + yield Static("Queue · loading", classes="panel-title", id="download-queue-title") + with VerticalScroll(id="download-queue-scroll"): + yield Static("Loading queue…", id="download-queue", markup=False) + with Container(classes="downloads-panel", id="download-details-panel"): + yield Static("Track details", classes="panel-title") + with VerticalScroll(id="download-details-scroll"): + yield Static("Select a queued song to inspect it.", id="download-details", markup=False) + yield Static("↑↓ Move · Enter Details · A Download queue · ? Help", id="downloads-position", markup=False) + + def on_screen_resume(self, event: ScreenResume) -> None: + if self.snapshot is None and self._refresh_worker is None: + self.refresh_snapshot() + + def invalidate_snapshot(self) -> None: + self.snapshot = None + self._refresh_worker = None + + def refresh_snapshot(self) -> None: + if self._execution_worker is not None: + self.notify("The selected download is still running.") + return + if self.snapshot is None: + self.query_one("#download-queue", Static).update("Loading queue…") + self.query_one("#download-details", Static).update("Waiting for queue data…") + status = self.query_one("#downloads-status", Static) + status.update("Refreshing download queue…") + status.remove_class("-error") + self._refresh_worker = self._load_queue() + + @work(thread=True, exclusive=True, group="downloads-queue", exit_on_error=False) + def _load_queue(self) -> QueueLoadOutcome: + try: + return QueueLoadOutcome(snapshot=self._queue_provider()) + except Exception as exc: + return QueueLoadOutcome(error=str(exc) or type(exc).__name__) + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is self._plan_worker: + if event.state is WorkerState.SUCCESS: + self._apply_execution_plan(event.worker.result) + elif event.state is WorkerState.ERROR: + self._set_status("Unable to prepare the selected download.", error=True) + return + if event.worker is self._retry_plan_worker: + if event.state is WorkerState.SUCCESS: self._apply_retry_plan(event.worker.result) + elif event.state is WorkerState.ERROR: self._set_status("Unable to prepare retry.", error=True) + return + if event.worker is self._retry_execution_worker: + if event.state is WorkerState.SUCCESS: self._apply_retry_result(event.worker.result) + elif event.state is WorkerState.ERROR: self._apply_retry_result(DownloadRetryResult(DownloadRetryStatus.FAILED, "Retry failed safely.", error=str(event.worker.error))) + return + if event.worker is self._mutation_worker: + if event.state not in {WorkerState.SUCCESS, WorkerState.ERROR}: + return + self._mutation_worker = None + if event.state is WorkerState.SUCCESS: self._apply_mutation(event.worker.result) + elif event.state is WorkerState.ERROR: self._apply_mutation(QueueMutationResult(QueueMutationStatus.STORE_FAILED, "Queue update failed safely.")) + return + if event.worker is self._batch_plan_worker: + if event.state not in {WorkerState.SUCCESS, WorkerState.ERROR}: + return + self._batch_plan_worker = None + if event.state is WorkerState.SUCCESS: self._apply_batch_plan(event.worker.result) + else: + detail = str(event.worker.error) if event.worker.error else "Unknown planning error" + self._set_status(f"Unable to prepare the download queue: {detail}", error=True) + return + if event.worker is self._batch_worker: + if event.state not in {WorkerState.SUCCESS, WorkerState.ERROR}: + return + self._batch_worker = None + if event.state is WorkerState.SUCCESS: self._apply_batch_result(event.worker.result) + else: self._set_status("Downloading the queue failed safely.", error=True) + return + if event.worker is self._execution_worker: + if event.state is WorkerState.SUCCESS: + self._apply_execution_result(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_execution_result(DownloadExecutionResult( + DownloadExecutionStatus.FAILED, + "Download failed safely.", + error=str(event.worker.error) if event.worker.error else "Unknown execution error", + )) + return + if event.worker is not self._refresh_worker: + return + if self.app.screen is not self: + # Textual unmounts the screen's widgets after section navigation. + # Discard this now-stale read and load a fresh snapshot on resume. + self._refresh_worker = None + return + if event.state is WorkerState.SUCCESS: + self._apply_queue(event.worker.result) + elif event.state is WorkerState.ERROR: + message = str(event.worker.error) if event.worker.error else "Unable to load Downloads" + self._apply_queue(QueueLoadOutcome(error=message)) + + def _apply_queue(self, outcome: QueueLoadOutcome) -> None: + status = self.query_one("#downloads-status", Static) + if outcome.error or outcome.snapshot is None: + status.update(f"Queue unavailable: {outcome.error or 'Unknown queue error'}") + status.add_class("-error") + if self.snapshot is None: + self.items = () + self.query_one("#download-queue-title", Static).update("Queue · unavailable") + self.query_one("#download-queue", Static).update("Unable to load the download queue.") + self.query_one("#download-details", Static).update("Queue details are unavailable.") + self.query_one("#downloads-position", Static).update("? Help · r Refresh") + return + + previous = self.selected_item.reference if self.selected_item is not None else None + self.snapshot = outcome.snapshot + self.items = outcome.snapshot.items + self.selected_index = next((index for index, item in enumerate(self.items) if item.reference == previous), 0) + self._details_mode = False + self.remove_class("-details-mode") + self._render_summary() + self._render_items() + self._render_selected_details() + if self.items: + self._update_context_status() + self._update_position() + self.call_after_refresh(self._scroll_selected_into_view) + else: + status.update("Search for songs in Browse · Press 2") + self.query_one("#downloads-position", Static).update("2 Browse songs · ? Help") + if self._completion_message is not None: + message, error = self._completion_message + self._set_status(message, error=error) + self._completion_message = None + + @property + def selected_item(self) -> DownloadQueueItem | None: + return self.items[self.selected_index] if self.items else None + + def _render_summary(self) -> None: + if self.snapshot is None: + return + snapshot = self.snapshot + self.query_one("#downloads-summary", Static).update( + f"Waiting {snapshot.queued_count} · Downloading {snapshot.downloading_count} · Adding lyrics {snapshot.processing_count} · Failed {snapshot.failed_count} · Complete {snapshot.completed_count}" + ) + + def _render_items(self) -> None: + position = f" · {self.selected_index + 1}/{len(self.items)}" if self.items else "" + self.query_one("#download-queue-title", Static).update(f"Downloads · {len(self.items)} active{position}") + if not self.items: + self.query_one("#download-queue", Static).update("Nothing waiting to download.") + return + lines = [] + for index, item in enumerate(self.items): + marker = ">" if index == self.selected_index else " " + live = self._live_progress if item.reference == self._active_reference else None + display_status = _progress_status(live) if live else item.status + error = " · error" if display_status in {DownloadQueueItemStatus.FAILED, DownloadQueueItemStatus.NEEDS_ATTENTION} else "" + lines.append(f"{marker} {_status_label(display_status):<15} {item.title[:32]:32} {_progress_label(item, live)}{error}") + self.query_one("#download-queue", Static).update(Text("\n".join(lines), no_wrap=True, overflow="ellipsis")) + + def _render_selected_details(self) -> None: + item = self.selected_item + details = self.query_one("#download-details", Static) + self.query_one("#download-details-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + if item is None: + details.update("No active queue item selected.") + return + lines = [ + item.title, "", + f"Artist {item.artist or 'Unknown'}", + f"Category {item.category or 'Unknown'}", + f"Era {item.era or 'Unknown'}", + f"Destination {item.destination or 'Unavailable'}", + f"Status {_status_label(_progress_status(self._live_progress) if item.reference == self._active_reference and self._live_progress else item.status)}", + f"Progress {_progress_label(item, self._live_progress if item.reference == self._active_reference else None)}", + f"Added {_timestamp(item.queued_at)}", + f"Try again {'Available' if item.retryable else 'Not available'}", + ] + if item.failure_stage: + lines.append(f"Failure {item.failure_stage}") + if item.error: + lines.append(f"Error {_concise_error(item.error)}") + if item.internal_reference: + lines.extend(("", "Troubleshooting", f"Internal ref {item.internal_reference}")) + details.update(Text("\n".join(lines), overflow="ellipsis")) + + def _update_position(self) -> None: + if self.items: + item = self.selected_item + if item and item.status is DownloadQueueItemStatus.FAILED: + actions = "↑↓ Move · Enter Details · t Retry · A Download queue · ? Help" + elif item and item.status is DownloadQueueItemStatus.QUEUED: + actions = "↑↓ Move · Enter Details · d Download · A Queue · ? Help" + elif item and item.status is DownloadQueueItemStatus.DOWNLOADING: + actions = "Downloading · Enter Details · ? Help" + elif item and item.status is DownloadQueueItemStatus.PROCESSING: + actions = "Adding lyrics · Enter Details · ? Help" + else: + actions = "↑↓ Move · Enter Details · ? Help" + self.query_one("#downloads-position", Static).update(actions) + + def _update_context_status(self) -> None: + if self._batch_worker or self._execution_worker or self._retry_execution_worker or self._completion_message is not None: + return + item = self.selected_item + if item is None: + self._set_status("Search for songs in Browse · Press 2") + elif item.status is DownloadQueueItemStatus.QUEUED: + self._set_status("Ready to download · A Download queue") + elif item.status is DownloadQueueItemStatus.FAILED: + self._set_status("Download failed · t Try again", error=True) + elif item.status is DownloadQueueItemStatus.DOWNLOADING: + self._set_status("Downloading · queue management is temporarily limited") + elif item.status is DownloadQueueItemStatus.PROCESSING: + self._set_status("Adding lyrics and updating your library") + + def on_key(self, event: Key) -> None: + if event.key == "escape" and self._details_mode: + self._details_mode = False + self.remove_class("-details-mode") + self._update_position() + elif event.key == "enter" and self.selected_item is not None: + self._details_mode = True + self.add_class("-details-mode") + self.query_one("#download-details-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + self._update_position() + elif event.key == "d": + self._download_selected() + elif event.key == "t": + self._retry_selected() + elif event.key == "x": + self._remove_selected() + elif event.key == "c": + self._confirm_clear_queue() + elif event.key in {"H", "shift+h"}: + self._confirm_clear_history() + elif event.key in {"A", "shift+a"}: + self._download_all() + elif event.key in ("pagedown", "pageup") and self._details_mode: + scroll = self.query_one("#download-details-scroll", VerticalScroll) + (scroll.scroll_page_down if event.key == "pagedown" else scroll.scroll_page_up)(animate=False) + elif event.key in ("down", "j"): + self._select_item(self.selected_index + 1) + elif event.key in ("up", "k"): + self._select_item(self.selected_index - 1) + elif event.key == "home": + self._select_item(0) + elif event.key == "end": + self._select_item(len(self.items) - 1) + elif event.key in ("pagedown", "pageup"): + scroll = self.query_one("#download-queue-scroll", VerticalScroll) + step = max(1, scroll.size.height - 1) + self._select_item(self.selected_index + (step if event.key == "pagedown" else -step)) + else: + return + event.prevent_default() + event.stop() + + def _retry_selected(self) -> None: + if self._execution_worker or self._plan_worker or self._retry_plan_worker or self._retry_execution_worker: + self._set_status("Another download is already in progress.", error=True); return + item = self.selected_item + if item is None or item.status is not DownloadQueueItemStatus.FAILED: + self._set_status("Select a failed song to retry.", error=True); return + self._retry_plan_worker = self._prepare_retry(item.reference) + + def _remove_selected(self) -> None: + item = self.selected_item + if item is None or item.status not in {DownloadQueueItemStatus.QUEUED, DownloadQueueItemStatus.FAILED}: + self._set_status("Select a queued or failed song to remove.", error=True); return + if self._mutation_worker is None: + self._mutation_worker = self._mutate(self._remove_provider, item.reference) + + def _download_all(self) -> None: + if self._batch_plan_worker or self._batch_worker or self._execution_worker or self._retry_execution_worker: + self._set_status("Another download is already in progress.", error=True); return + self._set_status("Preparing the download queue…") + self._batch_plan_worker = self._prepare_batch() + + @work(thread=True, exclusive=True, group="download-all-plan", exit_on_error=False) + def _prepare_batch(self) -> DownloadAllPlan | DownloadAllResult: + return self._batch_plan_provider(self.settings) + + def _apply_batch_plan(self, result: DownloadAllPlan | DownloadAllResult) -> None: + if isinstance(result, DownloadAllResult): self._set_status(result.message, error=True); return + if not result.eligible: + self._set_status(f"No eligible songs. Failed: {result.failed_count} · Active: {result.active_count}"); return + self.app.push_screen(DownloadAllDialog(result), self._batch_dialog_closed) + + def _batch_dialog_closed(self, plan: DownloadAllPlan | None) -> None: + if plan is None or self._batch_worker is not None: return + self._batch_worker = self._execute_batch(plan) + + @work(thread=True, exclusive=True, group="download-all", exit_on_error=False) + def _execute_batch(self, plan: DownloadAllPlan) -> DownloadAllResult: + return self._batch_execution_provider(self.settings, plan, progress=self._batch_progress) + + def _batch_progress(self, progress: object) -> None: + try: + self.app.call_from_thread(self._set_status, f"Downloading {getattr(progress, 'completed', 0)} of {getattr(progress, 'total', 0)} · {getattr(progress, 'title', '')}") + except RuntimeError: + pass + + def _apply_batch_result(self, result: DownloadAllResult) -> None: + self.snapshot = None; self._completion_message = (result.message, result.status is not DownloadBatchStatus.COMPLETED) + invalidate = getattr(self.app, "invalidate_library_views", None) + if callable(invalidate): invalidate() + if self.app.screen is self: self.refresh_snapshot() + + def _confirm_clear_queue(self) -> None: + if self.snapshot is None or not (self.snapshot.queued_count or self.snapshot.failed_count): + self._set_status("The queue has no waiting or failed songs."); return + active = self.snapshot.downloading_count + self.snapshot.processing_count + removable = self.snapshot.queued_count + self.snapshot.failed_count + body = f"Clear {removable} waiting or failed song{'s' if removable != 1 else ''}?" + if active: + body += f"\n\n{active} active song{'s' if active != 1 else ''} will remain." + body += "\n\nDownloaded music and lyrics will not be deleted." + self.app.push_screen(QueueCleanupDialog("Clear queue", body), self._cleanup_closed) + + def _confirm_clear_history(self) -> None: + if self.snapshot is None or self.snapshot.completed_count == 0: + self._set_status("There is no completed history to clear."); return + if self._mutation_worker is None: + self._mutation_worker = self._mutate(self._history_provider) + + def _cleanup_closed(self, action: str | None) -> None: + if action is None or self._mutation_worker is not None: return + if action == "Remove": + item = self.selected_item + if item is None: return + self._mutation_worker = self._mutate(self._remove_provider, item.reference) + elif action == "Clear queue": self._mutation_worker = self._mutate(self._clear_provider) + else: self._mutation_worker = self._mutate(self._history_provider) + + @work(thread=True, exclusive=True, group="queue-mutation", exit_on_error=False) + def _mutate(self, provider: MutationProvider, *args: object) -> QueueMutationResult: + return provider(*args) + + def _apply_mutation(self, result: QueueMutationResult) -> None: + self._completion_message = (result.message, result.status is not QueueMutationStatus.COMPLETED) + self.snapshot = None + if self.app.screen is self: self.refresh_snapshot() + + @work(thread=True, exclusive=True, group="retry-plan", exit_on_error=False) + def _prepare_retry(self, reference: str) -> DownloadRetryResult: + return self._retry_plan_provider(self.settings, reference) + + def _apply_retry_plan(self, result: DownloadRetryResult) -> None: + self._retry_plan_worker = None + if self.app.screen is not self: return + if result.status is not DownloadRetryStatus.READY or result.plan is None: + self._set_status(result.message, error=True); return + self._retry_dialog_closed(result.plan) + + def _retry_dialog_closed(self, plan: DownloadRetryPlan | None) -> None: + if plan is None or self._retry_execution_worker is not None: return + self._active_reference = plan.reference + self._live_progress = DownloadProgress(plan.reference, DownloadExecutionStatus.DOWNLOADING, message="Preparing retry…") + self._render_items(); self._render_selected_details() + self._retry_execution_worker = self._execute_retry(plan) + + @work(thread=True, exclusive=True, group="selected-retry", exit_on_error=False) + def _execute_retry(self, plan: DownloadRetryPlan) -> DownloadRetryResult: + return self._retry_execution_provider(self.settings, plan, progress=self._thread_progress) + + def _apply_retry_result(self, result: DownloadRetryResult) -> None: + self._retry_execution_worker = None; self._retry_plan_worker = None; self._active_reference = None; self._live_progress = None; self.snapshot = None + if result.status is DownloadRetryStatus.COMPLETED: + invalidate = getattr(self.app, "invalidate_library_views", None) + if callable(invalidate): invalidate() + self._completion_message = (result.message if result.status is DownloadRetryStatus.COMPLETED else f"{result.message}{': ' + result.error if result.error else ''}", result.status is not DownloadRetryStatus.COMPLETED) + if self.app.screen is self: self.refresh_snapshot() + + def _download_selected(self) -> None: + if self._execution_worker is not None or self._plan_worker is not None: + self._set_status("Another selected download is already being prepared or downloaded.", error=True) + return + item = self.selected_item + if item is None: + self._set_status("Select a queued song first.", error=True) + return + if item.status is DownloadQueueItemStatus.FAILED: + self._set_status("This song failed. Press t to try again.", error=True) + return + if item.status in {DownloadQueueItemStatus.DOWNLOADING, DownloadQueueItemStatus.PROCESSING}: + self._set_status("This song is already downloading or processing.", error=True) + return + if item.status is not DownloadQueueItemStatus.QUEUED: + self._set_status("This song is not eligible for Download selected.", error=True) + return + self._set_status("Checking the selected download…") + self._plan_worker = self._prepare_execution(item.reference) + + @work(thread=True, exclusive=True, group="download-plan", exit_on_error=False) + def _prepare_execution(self, reference: str) -> ExecutionPlanOutcome: + try: + return ExecutionPlanOutcome(reference, self._plan_provider(self.settings, reference)) + except Exception as exc: + return ExecutionPlanOutcome(reference, error=str(exc) or type(exc).__name__) + + def _apply_execution_plan(self, outcome: ExecutionPlanOutcome) -> None: + self._plan_worker = None + if self.app.screen is not self: + return + if self.selected_item is None or self.selected_item.reference != outcome.reference: + self._set_status("Selection changed; press d again for the current song.", error=True) + return + if outcome.error or outcome.result is None: + self._set_status(f"Unable to prepare download: {outcome.error or 'Unknown error'}", error=True) + return + if outcome.result.status is not DownloadExecutionStatus.READY or outcome.result.plan is None: + self._set_status(outcome.result.message, error=True) + return + self._download_dialog_closed(outcome.result.plan) + + def _download_dialog_closed(self, plan: DownloadExecutionPlan | None) -> None: + if plan is None: + return + if self._execution_worker is not None: + self._set_status("This song is already downloading.", error=True) + return + self._active_reference = plan.reference + self._live_progress = DownloadProgress( + plan.reference, + DownloadExecutionStatus.DOWNLOADING, + message="Starting download…", + ) + self._render_items() + self._render_selected_details() + self._set_status(f"Starting {plan.title}…") + self._execution_worker = self._execute_selected(plan) + + @work(thread=True, exclusive=True, group="selected-download", exit_on_error=False) + def _execute_selected(self, plan: DownloadExecutionPlan) -> DownloadExecutionResult: + try: + return self._execution_provider( + self.settings, + plan, + progress=self._thread_progress, + ) + except Exception as exc: + return DownloadExecutionResult( + DownloadExecutionStatus.FAILED, + "Download failed safely.", + plan=plan, + error=str(exc) or type(exc).__name__, + ) + + def _thread_progress(self, progress: DownloadProgress) -> None: + try: + self.app.call_from_thread(self._apply_progress, progress) + except RuntimeError: + pass + + def _apply_progress(self, progress: DownloadProgress) -> None: + if progress.reference != self._active_reference or self.app.screen is not self: + return + self._live_progress = progress + self._render_items() + self._render_selected_details() + message = ( + "Adding lyrics and updating your library…" + if progress.status is DownloadExecutionStatus.PROCESSING + else progress.message or _execution_status_label(progress.status) + ) + self._set_status(message) + + def _apply_execution_result(self, result: DownloadExecutionResult) -> None: + self._execution_worker = None + self._plan_worker = None + self._active_reference = None + self._live_progress = None + self.snapshot = None + if result.status is DownloadExecutionStatus.COMPLETED: + invalidate = getattr(self.app, "invalidate_library_views", None) + if callable(invalidate): + invalidate() + message = result.message + error = False + else: + detail = f": {result.error}" if result.error else "" + message = f"{result.message}{detail}" + error = True + self._completion_message = (message, error) + if self.app.screen is self: + self.refresh_snapshot() + else: + self._refresh_worker = None + + def _set_status(self, message: str, *, error: bool = False) -> None: + status = self.query_one("#downloads-status", Static) + status.update(message) + status.set_class(error, "-error") + + def _select_item(self, index: int) -> None: + if not self.items: + return + self.selected_index = max(0, min(len(self.items) - 1, index)) + self._render_items() + self._render_selected_details() + self._update_context_status() + self._update_position() + self.call_after_refresh(self._scroll_selected_into_view) + + def _scroll_selected_into_view(self) -> None: + if self.items: + scroll = self.query_one("#download-queue-scroll", VerticalScroll) + scroll.scroll_to_region(Region(0, self.selected_index, max(1, scroll.virtual_size.width), 1), animate=False, immediate=True, x_axis=False) + + def on_resize(self, event: Resize) -> None: + super().on_resize(event) + self.set_class(event.size.width < 90, "-downloads-narrow") + if self.items: + self.call_after_refresh(self._scroll_selected_into_view) + + +def _status_label(status: DownloadQueueItemStatus) -> str: + return { + DownloadQueueItemStatus.QUEUED: "Waiting", + DownloadQueueItemStatus.DOWNLOADING: "Downloading", + DownloadQueueItemStatus.PROCESSING: "Adding lyrics", + DownloadQueueItemStatus.COMPLETED: "Complete", + DownloadQueueItemStatus.FAILED: "Failed", + DownloadQueueItemStatus.NEEDS_ATTENTION: "Needs attention", + }[status] + + +def _progress_label(item: DownloadQueueItem, live: DownloadProgress | None = None) -> str: + if live is not None: + if live.percent is not None: + return f"{live.percent}% ({live.bytes_written}/{live.total_bytes} bytes)" + if live.bytes_written: + return f"{live.bytes_written} bytes" + return _execution_status_label(live.status) + percent = item.progress_percent + if percent is not None: + return f"{percent}% ({item.bytes_written}/{item.expected_bytes} bytes)" + return f"{item.bytes_written} bytes" if item.bytes_written else "Not started" + + +def _progress_status(progress: DownloadProgress) -> DownloadQueueItemStatus: + if progress.status is DownloadExecutionStatus.PROCESSING: + return DownloadQueueItemStatus.PROCESSING + if progress.status is DownloadExecutionStatus.FAILED: + return DownloadQueueItemStatus.FAILED + if progress.status is DownloadExecutionStatus.COMPLETED: + return DownloadQueueItemStatus.COMPLETED + return DownloadQueueItemStatus.DOWNLOADING + + +def _execution_status_label(status: DownloadExecutionStatus) -> str: + return { + DownloadExecutionStatus.READY: "Ready", + DownloadExecutionStatus.DOWNLOADING: "Downloading", + DownloadExecutionStatus.PROCESSING: "Adding lyrics", + DownloadExecutionStatus.COMPLETED: "Complete", + DownloadExecutionStatus.FAILED: "Failed", + DownloadExecutionStatus.NOT_FOUND: "Not found", + DownloadExecutionStatus.NOT_ELIGIBLE: "Not eligible", + DownloadExecutionStatus.ALREADY_RUNNING: "Already running", + DownloadExecutionStatus.RETRY_REQUIRED: "Retry required", + DownloadExecutionStatus.STORE_FAILED: "Queue unavailable", + }[status] + + +def _concise_error(error: str, limit: int = 240) -> str: + text = " ".join(error.splitlines()).strip() + return text if len(text) <= limit else text[: limit - 1] + "…" + + +def _timestamp(value: str | None) -> str: + if not value: + return "Unavailable" + try: + parsed = datetime.fromisoformat(value.replace("Z", "+00:00")) + except ValueError: + return value + zone = f" {parsed.tzname()}" if parsed.tzinfo and parsed.tzname() else "" + return parsed.strftime("%Y-%m-%d %H:%M:%S") + zone diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py new file mode 100644 index 0000000..bd40d47 --- /dev/null +++ b/src/juice_lyrics/tui/screens/library.py @@ -0,0 +1,2734 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass, replace +from enum import Enum +from pathlib import Path +from typing import Any + +from rich.text import Text +from textual import work +from textual.binding import Binding +from textual.containers import Container, Grid, Vertical, VerticalScroll +from textual.events import Click, Key, Resize, ScreenResume +from textual.geometry import Region +from textual.message import Message +from textual.screen import ModalScreen +from textual.widget import Widget +from textual.widgets import Input, Select, Static +from textual.worker import Worker, WorkerState + +from ...services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, +) +from ...services.library_identity import IdentityBackfillResult +from ...services.library_index_sync import LibraryIndexSyncResult +from ...services.library_issues import ( + LibraryHealth, + LibraryIssue, + LibraryIssueAction, + LibraryIssueCategory, + LibraryIssueSeverity, + get_library_health, +) +from ...services.library_duplicates import ( + DuplicateConfidence, + DuplicateGroup, + DuplicateReport, + detect_library_duplicates, +) +from ...services.missing_library import ( + CatalogueCoverage, + MissingLibraryReport, + get_missing_library, +) +from ...services.download_queue import ( + QueueAddResult, + QueueBatchAddResult, + add_batch_to_download_queue, + plan_queue_batch_additions, +) +from ...services.metadata_audit import ( + MetadataAudit, + MetadataProposalConfidence, + audit_track_metadata, +) +from ...services.metadata_repair import ( + MetadataRepairPlan, + MetadataRepairResult, + execute_metadata_repair, + plan_metadata_repair, +) +from ...services.catalogue import ( + CataloguePage, + CatalogueSearchResult, + SongDetails, + get_song_details_by_id, +) +from ...services.identity_rebuild import ( + IdentityRebuildPlan, + IdentityRebuildProgress, + IdentityRebuildResult, +) +from ...services.manual_identity import ( + ManualIdentityResult, + set_manual_identity, + unlock_manual_identity, +) +from ...services.library_sync import LibrarySyncPlan, MatchOutcome, SyncLyricType +from ...services.library_sync import LibrarySyncResult, SyncEvent, SyncEventKind +from ...backup.manager import BackupRecord +from ...services.settings_snapshot import IntegrationStatus, SettingsSnapshot +from .base import HubScreen + +SnapshotProvider = Callable[[Any], LibrarySnapshot] +IdentityProvider = Callable[..., IdentityBackfillResult] +IndexSyncProvider = Callable[..., LibraryIndexSyncResult] +IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] +IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] +ManualSearchProvider = Callable[..., CataloguePage] +ManualIdentityProvider = Callable[..., ManualIdentityResult] +MetadataAuditProvider = Callable[..., MetadataAudit] +MetadataRepairPlanProvider = Callable[..., MetadataRepairPlan] +MetadataRepairExecutionProvider = Callable[..., MetadataRepairResult] +MissingLibraryProvider = Callable[..., MissingLibraryReport] +QueuePlanProvider = Callable[..., QueueAddResult | QueueBatchAddResult] +QueueAddProvider = Callable[..., QueueAddResult | QueueBatchAddResult] +CatalogueDetailsProvider = Callable[..., SongDetails | None] +PreviewProvider = Callable[[Any], LibrarySyncPlan] +ExecutionProvider = Callable[..., LibrarySyncResult] +BackupProvider = Callable[[], tuple[BackupRecord, ...]] +RestoreProvider = Callable[[Path, Path], int] +RmpcStatusProvider = Callable[[Any], SettingsSnapshot] +RmpcSetupProvider = Callable[[Path, Path], Path] + + +class LibraryFilter(str, Enum): + ALL = "all" + MATCHED = "matched" + UNMATCHED = "unmatched" + SYNCED = "synced" + PLAIN = "plain" + NO_LYRICS = "no_lyrics" + ATTENTION = "attention" + + +_FILTER_OPTIONS = ( + ("All", LibraryFilter.ALL.value), + ("Matched", LibraryFilter.MATCHED.value), + ("Unmatched", LibraryFilter.UNMATCHED.value), + ("Synced lyrics", LibraryFilter.SYNCED.value), + ("Plain lyrics", LibraryFilter.PLAIN.value), + ("No lyrics", LibraryFilter.NO_LYRICS.value), + ("Lyrics to improve", LibraryFilter.ATTENTION.value), +) + + +class LibraryInput(Input): + """Local search input that preserves global section shortcuts.""" + + def on_key(self, event: Key) -> None: + if event.key == "escape": + self.screen.set_focus(None) + event.prevent_default() + event.stop() + return + if event.key == "question_mark": + self.app.action_show_help() + event.prevent_default() + event.stop() + return + if event.key == "slash": + self.screen.action_focus_search() + event.prevent_default() + event.stop() + return + + +class LibrarySelect(Select[str]): + """Local status selector that preserves global section shortcuts.""" + + def on_key(self, event: Key) -> None: + if event.key == "question_mark": + self.app.action_show_help() + event.prevent_default() + event.stop() + return + if event.key == "slash": + self.screen.action_focus_search() + event.prevent_default() + event.stop() + return + if event.key in "12345": + sections = ("dashboard", "browse", "library", "downloads", "settings") + self.app.action_show_section(sections[int(event.key) - 1]) + event.prevent_default() + event.stop() + + +@dataclass(frozen=True, slots=True) +class SnapshotOutcome: + snapshot: LibrarySnapshot | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class IdentityOutcome: + result: IdentityBackfillResult | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class PreviewOutcome: + plan: LibrarySyncPlan | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class ExecutionOutcome: + result: LibrarySyncResult | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class BackupOutcome: + records: tuple[BackupRecord, ...] = () + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class IdentityRebuildPlanOutcome: + plan: IdentityRebuildPlan | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class IdentityRebuildOutcome: + result: IdentityRebuildResult | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class ManualMatchChoice: + song_id: Any + api_name: str + + +@dataclass(frozen=True, slots=True) +class ManualIdentityOutcome: + result: ManualIdentityResult | None = None + error: str | None = None + action: str = "match" + + +@dataclass(frozen=True, slots=True) +class MetadataAuditOutcome: + reference: str + audit: MetadataAudit | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class MetadataRepairPlanOutcome: + plan: MetadataRepairPlan | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class MetadataRepairOutcome: + result: MetadataRepairResult | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class LibraryIssueChoice: + reference: str + action: LibraryIssueAction + + +class LibraryDialogAction(Static): + can_focus = True + + class Activated(Message): + def __init__(self, action: str) -> None: + self.action = action + super().__init__() + + def __init__(self, label: str, action: str, *, id: str) -> None: + super().__init__(label, id=id, markup=False) + self.action = action + + def on_click(self, event: Click) -> None: + self.post_message(self.Activated(self.action)) + + +class ManualMatchInput(Input): + """Search field for the state-only manual catalogue chooser.""" + + def on_key(self, event: Key) -> None: + if event.key == "question_mark": + self.app.action_show_help() + event.prevent_default() + event.stop() + + +class ManualMatchDialog(ModalScreen[ManualMatchChoice | None]): + """Search and choose one catalogue identity without touching media.""" + + def __init__( + self, + settings: Any, + track: LibraryTrack, + search_provider: ManualSearchProvider, + ) -> None: + super().__init__() + self.settings = settings + self.track = track + self._search_provider = search_provider + self.results: tuple[CatalogueSearchResult, ...] = () + self.index = 0 + self._search_worker: Worker[tuple[CataloguePage | None, str | None]] | None = None + + def compose(self) -> Iterable[Widget]: + with Container(id="manual-match-dialog"): + yield Static("Match manually", id="library-dialog-title") + yield Static( + f"{self.track.title}\nChoose the catalogue recording for this local file.", + id="manual-match-context", + markup=False, + ) + yield ManualMatchInput( + value=self.track.title, + placeholder="Catalogue search", + id="manual-match-query", + ) + with VerticalScroll(id="manual-match-scroll"): + yield Static("Searching catalogue…", id="manual-match-results", markup=False) + yield Static( + "↑/↓ Choose · Enter Save locked match · / Refine search · Esc Cancel", + id="library-dialog-help", + markup=False, + ) + + def on_mount(self) -> None: + self.query_one("#manual-match-query", Input).focus() + self._start_search(self.track.title) + + def on_input_submitted(self, event: Input.Submitted) -> None: + query = event.value.strip() + if query: + self._start_search(query) + + def _start_search(self, query: str) -> None: + self.results = () + self.index = 0 + self.query_one("#manual-match-results", Static).update("Searching catalogue…") + self._search_worker = self._search(query) + + @work(thread=True, exclusive=True, group="manual-match-search", exit_on_error=False) + def _search(self, query: str) -> tuple[CataloguePage | None, str | None]: + try: + return self._search_provider( + self.settings, + query, + page=1, + page_size=50, + refresh=False, + ), None + except Exception as exc: + return None, str(exc) or type(exc).__name__ + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is not self._search_worker: + return + if event.state is WorkerState.SUCCESS: + page, error = event.worker.result + self._search_worker = None + if error or page is None: + self.query_one("#manual-match-results", Static).update( + f"Catalogue search unavailable: {error or 'Unknown error'}\nNo changes were made." + ) + return + self.results = tuple( + result + for result in page.results + if result.song_id is not None and result.title + ) + self.index = 0 + self.set_focus(None) + self._render_results() + elif event.state is WorkerState.ERROR: + self._search_worker = None + self.query_one("#manual-match-results", Static).update( + "Catalogue search stopped safely. No changes were made." + ) + + def _render_results(self) -> None: + if not self.results: + self.query_one("#manual-match-results", Static).update( + "No usable catalogue candidates found. Press / to refine the search." + ) + return + lines: list[str] = [] + for index, result in enumerate(self.results): + marker = ">" if index == self.index else " " + category = result.category or "category unknown" + era = result.era or "era unknown" + length = result.length or "duration unknown" + lines.append( + f"{marker} {result.title}\n" + f" {category} · {era} · {length} · ID {result.song_id}" + ) + self.query_one("#manual-match-results", Static).update( + Text("\n".join(lines), no_wrap=False, overflow="ellipsis") + ) + self.call_after_refresh(self._scroll_selection_into_view) + + def _scroll_selection_into_view(self) -> None: + if not self.results: + return + scroll = self.query_one("#manual-match-scroll", VerticalScroll) + scroll.scroll_to(y=self.index * 2, animate=False, immediate=True) + + def on_key(self, event: Key) -> None: + if event.key == "escape": + self.dismiss(None) + elif event.key == "question_mark": + self.app.action_show_help() + elif event.key == "slash": + self.query_one("#manual-match-query", Input).focus() + elif isinstance(self.app.focused, Input): + return + elif event.key in {"down", "j"} and self.results: + self.index = min(len(self.results) - 1, self.index + 1) + self._render_results() + elif event.key in {"up", "k"} and self.results: + self.index = max(0, self.index - 1) + self._render_results() + elif event.key == "enter" and self.results: + selected = self.results[self.index] + self.dismiss(ManualMatchChoice(selected.song_id, selected.title or "")) + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + +class LibraryIssuesDialog(ModalScreen[LibraryIssueChoice | None]): + """Cheap snapshot-backed list of tracks that still need user attention.""" + + def __init__(self, health: LibraryHealth) -> None: + super().__init__() + self.health = health + self.index = 0 + + @property + def selected_issue(self) -> LibraryIssue | None: + if not self.health.issues: + return None + return self.health.issues[self.index] + + def compose(self) -> Iterable[Widget]: + with Container(id="library-issues-dialog"): + yield Static("Library Issues", id="library-dialog-title") + yield Static("", id="library-issues-summary", markup=False) + with Grid(id="library-issues-main"): + with VerticalScroll(id="library-issues-list-scroll"): + yield Static("", id="library-issues-list", markup=False) + with VerticalScroll(id="library-issues-detail-scroll"): + yield Static("", id="library-issues-detail", markup=False) + yield Static("", id="library-issues-help", markup=False) + + def on_mount(self) -> None: + self._render_issues() + + def _render_issues(self) -> None: + issues = self.health.issues + self.query_one("#library-issues-summary", Static).update( + f"{self.health.snapshot.total_track_count} tracks · " + f"{self.health.healthy_count} issue-free · {self.health.issue_count} follow-ups" + ) + if not issues: + self.query_one("#library-issues-list", Static).update("No follow-ups") + self.query_one("#library-issues-detail", Static).update( + "No library issues found.\n\nSync Library will keep this view current." + ) + self.query_one("#library-issues-help", Static).update("Esc Close · ? Help") + return + lines = [] + for index, issue in enumerate(issues): + marker = ">" if index == self.index else " " + lines.append( + f"{marker} {issue.track.title[:27]:27} · " + f"{issue.category_label:15} · {issue.severity.value.title()}" + ) + self.query_one("#library-issues-list", Static).update( + Text("\n".join(lines), no_wrap=True, overflow="ellipsis") + ) + issue = issues[self.index] + detail_lines = [ + issue.track.title, + "", + f"Issue {issue.summary}", + f"Category {issue.category_label}", + f"Severity {issue.severity.value.title()}", + f"Format {issue.track.media_format}", + f"Artist {issue.track.artist or 'Not available'}", + f"Album {issue.track.album or 'Not available'}", + f"Path {issue.track.relative_path}", + "", + *issue.details, + ] + if issue.action is LibraryIssueAction.MANUAL_MATCH: + detail_lines.extend(("", "Next step: press c to choose a catalogue match.")) + elif issue.action is LibraryIssueAction.REFRESH_LYRICS: + detail_lines.extend(("", "Next step: press l to preview a lyric refresh.")) + elif issue.action is LibraryIssueAction.SYNC: + detail_lines.extend(("", "Next step: press s to Sync Library.")) + else: + detail_lines.extend(("", "Next step: press v to verify the library again.")) + if LibraryIssueCategory.METADATA in issue.categories: + detail_lines.extend(("", "Press e to review and select metadata repairs.")) + self.query_one("#library-issues-detail", Static).update( + Text("\n".join(detail_lines), overflow="ellipsis") + ) + available = ["↑/↓ Select"] + if LibraryIssueCategory.CATALOGUE in issue.categories: + available.append("c Match manually") + if LibraryIssueCategory.METADATA in issue.categories: + available.append("e Metadata repair") + if LibraryIssueCategory.LYRICS in issue.categories: + available.append("l Refresh lyrics") + available.extend(("v Verify", "s Sync Library", "Esc Close", "? Help")) + self.query_one("#library-issues-help", Static).update(" · ".join(available)) + self.call_after_refresh(self._scroll_selection_into_view) + + def _scroll_selection_into_view(self) -> None: + if not self.health.issues: + return + scroll = self.query_one("#library-issues-list-scroll", VerticalScroll) + scroll.scroll_to(y=self.index, animate=False, immediate=True) + + def on_key(self, event: Key) -> None: + issue = self.selected_issue + if event.key in {"escape", "a"}: + self.dismiss(None) + elif event.key == "question_mark": + self.app.action_show_help() + elif event.key in {"down", "j"} and issue is not None: + self.index = min(len(self.health.issues) - 1, self.index + 1) + self._render_issues() + elif event.key in {"up", "k"} and issue is not None: + self.index = max(0, self.index - 1) + self._render_issues() + elif event.key == "home" and issue is not None: + self.index = 0 + self._render_issues() + elif event.key == "end" and issue is not None: + self.index = len(self.health.issues) - 1 + self._render_issues() + elif ( + event.key == "c" + and issue is not None + and LibraryIssueCategory.CATALOGUE in issue.categories + ): + self.dismiss(LibraryIssueChoice(issue.track.reference, LibraryIssueAction.MANUAL_MATCH)) + elif event.key == "l" and issue is not None and LibraryIssueCategory.LYRICS in issue.categories: + self.dismiss(LibraryIssueChoice(issue.track.reference, LibraryIssueAction.REFRESH_LYRICS)) + elif event.key == "e" and issue is not None and LibraryIssueCategory.METADATA in issue.categories: + self.dismiss(LibraryIssueChoice(issue.track.reference, LibraryIssueAction.METADATA_AUDIT)) + elif event.key == "v": + self.dismiss( + LibraryIssueChoice(issue.track.reference if issue else "", LibraryIssueAction.VERIFY) + ) + elif event.key == "s": + self.dismiss( + LibraryIssueChoice(issue.track.reference if issue else "", LibraryIssueAction.SYNC) + ) + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + +class LibraryDuplicatesDialog(ModalScreen[None]): + """Read-only duplicate groups derived from the current Library snapshot.""" + + def __init__(self, report: DuplicateReport) -> None: + super().__init__() + self.report = report + self.index = 0 + + def compose(self) -> Iterable[Widget]: + with Container(id="library-duplicates-dialog"): + yield Static("Duplicate recordings", id="library-dialog-title") + yield Static("", id="library-duplicates-summary", markup=False) + with Grid(id="library-duplicates-main"): + with VerticalScroll(id="library-duplicates-list-scroll"): + yield Static("", id="library-duplicates-list", markup=False) + with VerticalScroll(id="library-duplicates-detail-scroll"): + yield Static("", id="library-duplicates-detail", markup=False) + yield Static("↑/↓ Select · Esc Close · ? Help", id="library-duplicates-help", markup=False) + + def on_mount(self) -> None: + self._render_duplicates() + + def _render_duplicates(self) -> None: + groups = self.report.groups + self.query_one("#library-duplicates-summary", Static).update( + f"{len(groups)} duplicate group{'s' if len(groups) != 1 else ''} · " + f"{self.report.file_count} file{'s' if self.report.file_count != 1 else ''}" + ) + if not groups: + self.query_one("#library-duplicates-list", Static).update( + "No duplicate recordings found" + ) + self.query_one("#library-duplicates-detail", Static).update( + "No exact or probable duplicate groups are present in the current Library snapshot." + ) + return + lines = [] + for index, group in enumerate(groups): + marker = ">" if index == self.index else " " + label = "Exact" if group.confidence is DuplicateConfidence.EXACT else "Probable" + lines.append( + f"{marker} {group.title[:27]:27} · {label:8} · {len(group.tracks)} files" + ) + self.query_one("#library-duplicates-list", Static).update( + Text("\n".join(lines), no_wrap=True, overflow="ellipsis") + ) + self._render_duplicate_detail(groups[self.index]) + self.call_after_refresh(self._scroll_duplicate_selection_into_view) + + def _render_duplicate_detail(self, group: DuplicateGroup) -> None: + label = "Exact duplicate audio" if group.confidence is DuplicateConfidence.EXACT else "Probable duplicate recording" + lines = [group.title, "", f"Assessment {label}", "", "Evidence"] + lines.extend(f"- {item}" for item in group.evidence) + lines.extend(("", "Files")) + for track in group.tracks: + duration = _duration(track.duration_seconds) + catalogue = ( + f" · catalogue {track.catalogue_id}" + if track.catalogue_id is not None + else "" + ) + lines.extend( + ( + f"- {track.relative_path}", + f" {track.media_format} · {duration}{catalogue}", + ) + ) + lines.extend(("", "Review only — no files will be changed.")) + self.query_one("#library-duplicates-detail", Static).update( + Text("\n".join(lines), overflow="ellipsis") + ) + + def _scroll_duplicate_selection_into_view(self) -> None: + if not self.report.groups: + return + self.query_one("#library-duplicates-list-scroll", VerticalScroll).scroll_to( + y=self.index, animate=False, immediate=True + ) + + def on_key(self, event: Key) -> None: + groups = self.report.groups + if event.key in {"escape", "d"}: + self.dismiss(None) + elif event.key == "question_mark": + self.app.action_show_help() + elif event.key in {"down", "j"} and groups: + self.index = min(len(groups) - 1, self.index + 1) + self._render_duplicates() + elif event.key in {"up", "k"} and groups: + self.index = max(0, self.index - 1) + self._render_duplicates() + elif event.key == "home" and groups: + self.index = 0 + self._render_duplicates() + elif event.key == "end" and groups: + self.index = len(groups) - 1 + self._render_duplicates() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + +class MissingLibraryInput(Input): + """Local filter input for the Missing Library modal.""" + + def on_key(self, event: Key) -> None: + if event.key == "escape": + self.screen.set_focus(None) + event.prevent_default() + event.stop() + elif event.key == "question_mark": + self.app.action_show_help() + event.prevent_default() + event.stop() + + +class MissingLibraryDialog(ModalScreen[None]): + """Identity-based, read-only catalogue gap view with explicit queue add.""" + + def __init__( + self, + settings: Any, + snapshot: LibrarySnapshot, + *, + report_provider: MissingLibraryProvider = get_missing_library, + queue_plan_provider: QueuePlanProvider = plan_queue_batch_additions, + queue_add_provider: QueueAddProvider = add_batch_to_download_queue, + ) -> None: + super().__init__() + self.settings = settings + self.snapshot = snapshot + self._report_provider = report_provider + self._queue_plan_provider = queue_plan_provider + self._queue_add_provider = queue_add_provider + self.report: MissingLibraryReport | None = None + self.results: tuple[CatalogueSearchResult, ...] = () + self.index = 0 + self._load_worker: Worker[MissingLibraryReport] | None = None + self._queue_worker: Worker[QueueAddResult | QueueBatchAddResult] | None = None + self._adding = False + + def compose(self) -> Iterable[Widget]: + with Container(id="missing-library-dialog"): + yield Static("Missing Library", id="library-dialog-title") + yield Static("Loading catalogue coverage…", id="missing-library-summary", markup=False) + yield MissingLibraryInput(placeholder="Filter loaded recordings", id="missing-library-query") + with Grid(id="missing-library-main"): + with VerticalScroll(id="missing-library-list-scroll"): + yield Static("Loading…", id="missing-library-list", markup=False) + with VerticalScroll(id="missing-library-detail-scroll"): + yield Static("The catalogue is loading in the background.", id="missing-library-detail", markup=False) + yield Static("/ Filter · ↑/↓ Select · a Add to Downloads · Esc Close · ? Help", id="missing-library-help", markup=False) + + def on_mount(self) -> None: + self.call_after_refresh(self.set_focus, None) + self._load_worker = self._load_report() + + @work(thread=True, exclusive=True, group="missing-library-load", exit_on_error=False) + def _load_report(self) -> MissingLibraryReport: + return self._report_provider(self.settings, self.snapshot) + + @work(thread=True, exclusive=True, group="missing-library-queue", exit_on_error=False) + def _queue_selected(self, selection: CatalogueSearchResult) -> QueueAddResult | QueueBatchAddResult: + planned = self._queue_plan_provider(self.settings, (selection,)) + plan = getattr(planned, "plan", None) + if plan is None: + return planned + return self._queue_add_provider(plan) + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is self._load_worker: + if event.state is WorkerState.SUCCESS: + self.report = event.worker.result + self._filter_results() + elif event.state is WorkerState.ERROR: + self.query_one("#missing-library-summary", Static).update("Catalogue coverage unavailable") + self.query_one("#missing-library-list", Static).update("Unable to load the catalogue.") + self.query_one("#missing-library-detail", Static).update("Your local Library was not changed.") + elif event.worker is self._queue_worker: + if event.state is WorkerState.SUCCESS: + result = event.worker.result + self._adding = False + self.query_one("#missing-library-summary", Static).update(result.message) + if result.ok: + invalidate = getattr(self.app, "invalidate_download_queue", None) + if callable(invalidate): + invalidate() + elif event.state is WorkerState.ERROR: + self._adding = False + self.query_one("#missing-library-summary", Static).update("Unable to add this recording to Downloads.") + + def on_input_changed(self, event: Input.Changed) -> None: + if event.input.id == "missing-library-query" and self.report is not None: + self._filter_results() + + def on_input_submitted(self, event: Input.Submitted) -> None: + if event.input.id == "missing-library-query": + self.set_focus(None) + + def _filter_results(self) -> None: + if self.report is None: + return + query = self.query_one("#missing-library-query", Input).value.strip().casefold() + self.results = tuple( + item for item in self.report.recordings + if not query or query in " ".join( + filter(None, (item.title, item.category, item.era, item.album, " ".join(item.artists))) + ).casefold() + ) + self.index = min(self.index, max(0, len(self.results) - 1)) + self._render_report() + + def _render_report(self) -> None: + report = self.report + if report is None: + return + coverage = { + CatalogueCoverage.COMPLETE: "Complete catalogue coverage", + CatalogueCoverage.PARTIAL: "Partial catalogue coverage", + CatalogueCoverage.UNAVAILABLE: "Catalogue unavailable", + }[report.coverage] + summary = ( + f"{report.missing_count} confirmed missing · {report.local_unknown_count} local Unknown · " + f"{report.loaded_recording_count} catalogue recordings loaded · {coverage}" + ) + if report.error: + summary += f" · {report.error}" + self.query_one("#missing-library-summary", Static).update(summary) + if not self.results: + message = "No missing recordings match this filter." if report.recordings else ( + "No confirmed missing recordings in the loaded catalogue." + if report.complete else "No missing recordings can be confirmed from the loaded catalogue data." + ) + self.query_one("#missing-library-list", Static).update(message) + self.query_one("#missing-library-detail", Static).update( + "Local Unknown tracks are not assumed to own any catalogue recording. Run Sync or match them manually." + ) + return + lines = [] + for index, item in enumerate(self.results): + marker = ">" if index == self.index else " " + category = item.category or "unknown category" + lines.append(f"{marker} {(item.title or 'Untitled')[:32]:32} · {category}") + self.query_one("#missing-library-list", Static).update(Text("\n".join(lines), no_wrap=True, overflow="ellipsis")) + item = self.results[self.index] + artists = ", ".join(item.artists) or "Unknown" + fields = ( + item.title or "Untitled", + "", + f"Catalogue ID {item.song_id}", + f"Category {item.category or 'Unknown'}", + f"Artists {artists}", + f"Album / era {item.album or item.era or 'Unknown'}", + f"Duration {item.length or 'Unknown'}", + f"Download {'Available' if item.downloadable else 'Unavailable'}", + "", + "This exact catalogue recording ID is not present among confirmed local identities.", + ) + self.query_one("#missing-library-detail", Static).update(Text("\n".join(fields), overflow="ellipsis")) + self.call_after_refresh( + self.query_one("#missing-library-list-scroll", VerticalScroll).scroll_to, + y=self.index, animate=False, immediate=True, + ) + + def on_key(self, event: Key) -> None: + if isinstance(self.app.focused, Input): + return + if event.key in {"escape", "g"}: + self.dismiss(None) + elif event.key == "question_mark": + self.app.action_show_help() + elif event.key == "slash": + self.query_one("#missing-library-query", Input).focus() + elif event.key in {"down", "j"} and self.results: + self.index = min(len(self.results) - 1, self.index + 1) + self._render_report() + elif event.key in {"up", "k"} and self.results: + self.index = max(0, self.index - 1) + self._render_report() + elif event.key == "home" and self.results: + self.index = 0 + self._render_report() + elif event.key == "end" and self.results: + self.index = len(self.results) - 1 + self._render_report() + elif event.key == "a" and self.results and not self._adding: + selected = self.results[self.index] + if not selected.downloadable: + self.query_one("#missing-library-summary", Static).update("This recording is not available to download.") + else: + self._adding = True + self.query_one("#missing-library-summary", Static).update("Adding to Downloads…") + self._queue_worker = self._queue_selected(selected) + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + +class MetadataAuditDialog(ModalScreen[tuple[str, ...] | None]): + """Select explicit fields from a before/after metadata preview.""" + + def __init__(self, audit: MetadataAudit) -> None: + super().__init__() + self.audit = audit + self.index = 0 + self.selected: set[str] = set() + self._submitted = False + + def compose(self) -> Iterable[Widget]: + with Container(id="metadata-audit-dialog"): + yield Static("Metadata repair preview", id="library-dialog-title") + with VerticalScroll(id="metadata-audit-scroll"): + yield Static(self._text(), id="metadata-audit-content", markup=False) + yield Static(self._help_text(), id="metadata-audit-help", markup=False) + + def on_mount(self) -> None: + self.query_one("#metadata-audit-scroll", VerticalScroll).focus() + + def _help_text(self) -> str: + if not self.audit.proposals: + return "No repairable fields · Esc Close" + return "↑↓ Choose · Space/Enter Select · a Review apply · Esc Cancel" + + @property + def _ordered_proposals(self) -> tuple[Any, ...]: + return tuple( + proposal + for confidence in ( + MetadataProposalConfidence.CONFIDENT, + MetadataProposalConfidence.REVIEW, + ) + for proposal in self.audit.proposals + if proposal.confidence is confidence + ) + + def _text(self) -> Text: + audit = self.audit + track = audit.track + lines = [ + track.title, + "", + f"Format {track.media_format}", + f"Path {track.relative_path}", + f"Catalogue ID {track.catalogue_id or 'Unknown'}", + f"Identity {'Manual lock' if track.identity_locked else 'Automatic' if track.catalogue_id is not None else 'Unknown'}", + ] + if audit.error: + lines.extend(("", f"Preview unavailable: {audit.error}")) + if audit.catalogue is not None: + lines.extend( + ( + f"Catalogue {audit.catalogue.title or 'Not available'}", + f"Category {audit.catalogue.category or 'Not available'}", + f"Era {audit.catalogue.era or 'Not available'}", + f"Duration {audit.catalogue.length or 'Not available'}", + ) + ) + lines.extend(("", "Proposed metadata · nothing is selected by default")) + if not audit.proposals: + lines.append("No metadata changes proposed") + for confidence, heading in ( + (MetadataProposalConfidence.CONFIDENT, "Confident recommendations"), + (MetadataProposalConfidence.REVIEW, "Review carefully"), + ): + proposals = tuple( + (index, proposal) + for index, proposal in enumerate(self._ordered_proposals) + if proposal.confidence is confidence + ) + if not proposals: + continue + lines.extend(("", heading)) + for index, proposal in proposals: + cursor = ">" if index == self.index else " " + checked = "x" if proposal.field in self.selected else " " + lines.extend( + ( + f"{cursor} [{checked}] {proposal.label}", + f" {proposal.before or '(missing)'} → {proposal.after}", + f" {proposal.reason}", + ) + ) + if audit.notes: + lines.extend(("", "Notes", *(f"- {note}" for note in audit.notes))) + return Text("\n".join(lines), overflow="ellipsis") + + def _render_content(self) -> None: + self.query_one("#metadata-audit-content", Static).update(self._text()) + + def _toggle(self) -> None: + if not self.audit.proposals: + return + field = self._ordered_proposals[self.index].field + if field in self.selected: + self.selected.remove(field) + else: + self.selected.add(field) + self._render_content() + + def on_key(self, event: Key) -> None: + if self._submitted: + event.prevent_default() + event.stop() + return + if event.key in {"escape", "e"}: + self._submitted = True + self.dismiss(None) + elif event.key in {"down", "j"} and self.audit.proposals: + self.index = min(len(self._ordered_proposals) - 1, self.index + 1) + self._render_content() + elif event.key in {"up", "k"} and self.audit.proposals: + self.index = max(0, self.index - 1) + self._render_content() + elif event.key in {"space", "enter"}: + self._toggle() + elif event.key == "a": + if not self.selected: + self.query_one("#metadata-audit-help", Static).update( + "Select at least one field · No changes have been made" + ) + else: + self._submitted = True + fields = tuple( + proposal.field + for proposal in self._ordered_proposals + if proposal.field in self.selected + ) + self.dismiss(fields) + elif event.key == "question_mark": + self.app.action_show_help() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + +class MetadataRepairConfirmationDialog(ModalScreen[bool]): + """Cancel-first confirmation for one pinned metadata repair plan.""" + + def __init__(self, plan: MetadataRepairPlan) -> None: + super().__init__() + self.plan = plan + self._choice = "cancel" + self._submitted = False + + def compose(self) -> Iterable[Widget]: + changes = "\n".join( + f"{proposal.label}: {proposal.before or '(missing)'} → {proposal.after}" + for proposal in self.plan.selected + ) + body = ( + f"{self.plan.reference}\n\n{changes}\n\n" + "A complete audio backup will be created first. Only the selected " + "metadata fields will change; audio, artwork, lyrics, and other tags " + "will be verified." + ) + with Container(id="library-dialog"): + yield Static("Apply metadata repair?", id="library-dialog-title") + yield Static(body, id="library-dialog-body", markup=False) + with Grid(id="library-dialog-actions"): + yield LibraryDialogAction("Apply", "confirm", id="library-dialog-confirm") + yield LibraryDialogAction("Cancel", "cancel", id="library-dialog-cancel") + + def on_mount(self) -> None: + self._render_choice() + self.call_after_refresh( + self.query_one("#library-dialog-cancel", LibraryDialogAction).focus + ) + + def _render_choice(self) -> None: + self.query_one("#library-dialog-confirm", Static).update( + "[Apply]" if self._choice == "confirm" else "Apply" + ) + self.query_one("#library-dialog-cancel", Static).update( + "[Cancel]" if self._choice == "cancel" else "Cancel" + ) + + def _activate(self) -> None: + if self._submitted: + return + self._submitted = True + self.dismiss(self._choice == "confirm") + + def on_library_dialog_action_activated( + self, event: LibraryDialogAction.Activated + ) -> None: + if self._submitted: + return + self._choice = event.action + self._render_choice() + self._activate() + + def on_key(self, event: Key) -> None: + if self._submitted: + event.prevent_default() + event.stop() + return + if event.key in {"escape", "n"}: + self._choice = "cancel" + self._activate() + elif event.key == "y": + self._choice = "confirm" + self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + target = ( + "#library-dialog-confirm" + if self._choice == "confirm" + else "#library-dialog-cancel" + ) + self.query_one(target, LibraryDialogAction).focus() + elif event.key == "enter": + self._activate() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default() + event.stop() + + +class MaintenanceDialog(ModalScreen[LibrarySyncPlan | None]): + """Cancel-first confirmation for an already non-mutating maintenance preview.""" + + def __init__(self, plan: LibrarySyncPlan) -> None: + super().__init__() + self.plan = plan + self._choice = "cancel" + self._confirmed = False + + def compose(self) -> Iterable[Widget]: + problems = self.plan.unresolved_files + self.plan.no_lyrics_files + self.plan.analysis_failures + count = self.plan.ready_files + body = ( + f"{count} song{'s' if count != 1 else ''} can be updated · " + f"{problems} cannot be updated now\n\n" + f"{self.plan.synced_files:2} Synced lyrics available\n" + f"{self.plan.plain_files:2} Plain lyrics available\n" + f"{self.plan.unresolved_files:2} Could not be matched\n" + f"{self.plan.no_lyrics_files:2} Lyrics unavailable\n" + f"{self.plan.analysis_failures:2} Could not be checked\n\n" + "No changes have been made." + ) + with Container(id="library-dialog"): + yield Static("Library maintenance", id="library-dialog-title") + yield Static(body, id="library-dialog-body", markup=False) + with Grid(id="library-dialog-actions"): + yield LibraryDialogAction( + f"Update {count} song{'s' if count != 1 else ''}", "confirm", id="library-dialog-confirm" + ) + yield LibraryDialogAction("Cancel", "cancel", id="library-dialog-cancel") + + def on_mount(self) -> None: + self._render_choice() + self.call_after_refresh(self.query_one("#library-dialog-cancel", LibraryDialogAction).focus) + + def _render_choice(self) -> None: + confirm = self.query_one("#library-dialog-confirm", Static) + cancel = self.query_one("#library-dialog-cancel", Static) + confirm.update(f"[Update {self.plan.ready_files} song{'s' if self.plan.ready_files != 1 else ''}]" if self._choice == "confirm" else f"Update {self.plan.ready_files} song{'s' if self.plan.ready_files != 1 else ''}") + cancel.update("[Cancel]" if self._choice == "cancel" else "Cancel") + + def on_library_dialog_action_activated(self, event: LibraryDialogAction.Activated) -> None: + if not self._confirmed: + self._choice = event.action + self._render_choice() + self._activate() + + def on_key(self, event: Key) -> None: + if self._confirmed: + event.prevent_default(); event.stop(); return + if event.key in {"escape", "n"}: + self._confirmed = True + self.dismiss(None) + elif event.key == "y" and self.plan.ready_files: + self._choice = "confirm"; self._render_choice(); self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"} and self.plan.ready_files: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + target = "#library-dialog-confirm" if self._choice == "confirm" else "#library-dialog-cancel" + self.query_one(target, LibraryDialogAction).focus() + elif event.key == "enter": + self._activate() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default(); event.stop() + + def _activate(self) -> None: + if self._choice == "cancel" or not self.plan.ready_files: + self._confirmed = True + self.dismiss(None) + elif not self._confirmed: + self._confirmed = True + self.dismiss(self.plan) + + +class IdentityRebuildDialog(ModalScreen[IdentityRebuildPlan | None]): + """Cancel-first confirmation for rebuilding catalogue identity state.""" + + def __init__(self, plan: IdentityRebuildPlan) -> None: + super().__init__() + self.plan = plan + self._choice = "cancel" + self._confirmed = False + + def compose(self) -> Iterable[Widget]: + body = ( + "This will re-identify your current library using the latest matcher.\n" + "Audio and lyrics will not be modified.\n\n" + f"Current tracks {self.plan.current_tracks}\n" + f"Existing identities {self.plan.existing_identities}\n" + f"Manual locks kept {self.plan.locked_identities}\n" + f"Currently unknown {self.plan.currently_unknown}\n" + f"Stale records ignored {len(self.plan.stale_keys)}" + ) + with Container(id="library-dialog"): + yield Static("Rebuild catalogue matches?", id="library-dialog-title") + yield Static(body, id="library-dialog-body", markup=False) + with Grid(id="library-dialog-actions"): + yield LibraryDialogAction("Rebuild matches", "confirm", id="library-dialog-confirm") + yield LibraryDialogAction("Cancel", "cancel", id="library-dialog-cancel") + + def on_mount(self) -> None: + self._render_choice() + self.call_after_refresh( + self.query_one("#library-dialog-cancel", LibraryDialogAction).focus + ) + + def _render_choice(self) -> None: + self.query_one("#library-dialog-confirm", Static).update( + "[Rebuild matches]" if self._choice == "confirm" else "Rebuild matches" + ) + self.query_one("#library-dialog-cancel", Static).update( + "[Cancel]" if self._choice == "cancel" else "Cancel" + ) + + def on_library_dialog_action_activated(self, event: LibraryDialogAction.Activated) -> None: + if not self._confirmed: + self._choice = event.action + self._render_choice() + self._activate() + + def on_key(self, event: Key) -> None: + if self._confirmed: + event.prevent_default(); event.stop(); return + if event.key in {"escape", "n"}: + self._confirmed = True + self.dismiss(None) + elif event.key == "y": + self._choice = "confirm"; self._render_choice(); self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel" + self._render_choice() + target = "#library-dialog-confirm" if self._choice == "confirm" else "#library-dialog-cancel" + self.query_one(target, LibraryDialogAction).focus() + elif event.key == "enter": + self._activate() + elif event.key in {"1", "2", "3", "4", "5"}: + pass + else: + return + event.prevent_default(); event.stop() + + def _activate(self) -> None: + if self._choice == "cancel": + self._confirmed = True + self.dismiss(None) + elif not self._confirmed: + self._confirmed = True + self.dismiss(self.plan) + + +class BackupBrowser(ModalScreen[BackupRecord | None]): + """Read-only valid backup browser; choosing Restore returns a record.""" + + def __init__(self, records: tuple[BackupRecord, ...]) -> None: + super().__init__() + self.records = tuple(reversed(records)) + self.index = 0 + + def compose(self) -> Iterable[Widget]: + with Container(id="library-dialog"): + yield Static("Backups", id="library-dialog-title") + yield Static("", id="library-dialog-body", markup=False) + yield Static("↑/↓ select · r restore · Escape close", id="library-dialog-help", markup=False) + + def on_mount(self) -> None: + self._render_records() + + def _render_records(self) -> None: + if not self.records: + self.query_one("#library-dialog-body", Static).update("No backups available") + return + lines = [f"{len(self.records)} valid backup{'s' if len(self.records) != 1 else ''}\n"] + for index, record in enumerate(self.records): + marker = ">" if index == self.index else " " + stamp = record.created_at.astimezone().strftime("%Y-%m-%d %H:%M") + lines.append(f"{marker} {stamp} · {record.file_count} file{'s' if record.file_count != 1 else ''}") + self.query_one("#library-dialog-body", Static).update("\n".join(lines)) + + def on_key(self, event: Key) -> None: + if event.key == "escape": self.dismiss(None) + elif event.key in {"down", "j"} and self.records: self.index = min(len(self.records) - 1, self.index + 1); self._render_records() + elif event.key in {"up", "k"} and self.records: self.index = max(0, self.index - 1); self._render_records() + elif event.key == "r" and self.records: self.dismiss(self.records[self.index]) + elif event.key in {"1", "2", "3", "4", "5"}: pass + else: return + event.prevent_default(); event.stop() + + +class RestoreDialog(ModalScreen[BackupRecord | None]): + """Cancel-first destructive restore confirmation.""" + + def __init__(self, record: BackupRecord) -> None: + super().__init__(); self.record = record; self._choice = "cancel"; self._confirmed = False + + def compose(self) -> Iterable[Widget]: + with Container(id="library-dialog"): + yield Static("Restore backup?", id="library-dialog-title") + yield Static( + f"This will replace {self.record.file_count} current audio file{'s' if self.record.file_count != 1 else ''}\nwith copies from the selected backup.", + id="library-dialog-body", markup=False, + ) + with Grid(id="library-dialog-actions"): + yield LibraryDialogAction("Restore", "confirm", id="library-dialog-confirm") + yield LibraryDialogAction("Cancel", "cancel", id="library-dialog-cancel") + + def on_mount(self) -> None: + self._render_choice(); self.call_after_refresh(self.query_one("#library-dialog-cancel", LibraryDialogAction).focus) + + def _render_choice(self) -> None: + self.query_one("#library-dialog-confirm", Static).update("[Restore]" if self._choice == "confirm" else "Restore") + self.query_one("#library-dialog-cancel", Static).update("[Cancel]" if self._choice == "cancel" else "Cancel") + + def on_library_dialog_action_activated(self, event: LibraryDialogAction.Activated) -> None: + if not self._confirmed: self._choice = event.action; self._render_choice(); self._activate() + + def on_key(self, event: Key) -> None: + if self._confirmed: event.prevent_default(); event.stop(); return + if event.key in {"escape", "n"}: self._confirmed = True; self.dismiss(None) + elif event.key == "y": self._choice = "confirm"; self._render_choice(); self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"}: + self._choice = "confirm" if self._choice == "cancel" else "cancel"; self._render_choice() + self.query_one("#library-dialog-confirm" if self._choice == "confirm" else "#library-dialog-cancel", LibraryDialogAction).focus() + elif event.key == "enter": self._activate() + elif event.key in {"1", "2", "3", "4", "5"}: pass + else: return + event.prevent_default(); event.stop() + + def _activate(self) -> None: + if self._choice == "cancel": self._confirmed = True; self.dismiss(None) + elif not self._confirmed: self._confirmed = True; self.dismiss(self.record) + + +class RmpcDialog(ModalScreen[SettingsSnapshot | None]): + """Read-only rmpc check with an explicit, cancel-first setup option.""" + + def __init__(self, snapshot: SettingsSnapshot) -> None: + super().__init__(); self.snapshot = snapshot; self._choice = "cancel"; self._confirmed = False + + @property + def can_setup(self) -> bool: + return ( + self.snapshot.rmpc.status is IntegrationStatus.DETECTED_NOT_CONFIGURED + and self.snapshot.rmpc.config_exists + ) + + def compose(self) -> Iterable[Widget]: + body = self.snapshot.rmpc.detail + if self.can_setup: + body += "\n\nSet up rmpc? This may update its configuration." + elif ( + self.snapshot.rmpc.status is IntegrationStatus.DETECTED_NOT_CONFIGURED + and not self.snapshot.rmpc.config_exists + ): + body += "\n\nOpen rmpc once to create its configuration, then check again." + with Container(id="library-dialog"): + yield Static("rmpc integration", id="library-dialog-title") + yield Static(body, id="library-dialog-body", markup=False) + with Grid(id="library-dialog-actions"): + yield LibraryDialogAction("Set up rmpc", "confirm", id="library-dialog-confirm") + yield LibraryDialogAction("Close", "cancel", id="library-dialog-cancel") + + def on_mount(self) -> None: + self.query_one("#library-dialog-confirm", LibraryDialogAction).disabled = not self.can_setup + self._render_choice(); self.call_after_refresh(self.query_one("#library-dialog-cancel", LibraryDialogAction).focus) + + def _render_choice(self) -> None: + self.query_one("#library-dialog-confirm", Static).update("[Set up rmpc]" if self._choice == "confirm" else "Set up rmpc") + self.query_one("#library-dialog-cancel", Static).update("[Close]" if self._choice == "cancel" else "Close") + + def on_library_dialog_action_activated(self, event: LibraryDialogAction.Activated) -> None: + if event.action == "confirm" and not self.can_setup: return + if not self._confirmed: self._choice = event.action; self._render_choice(); self._activate() + + def on_key(self, event: Key) -> None: + if self._confirmed: event.prevent_default(); event.stop(); return + if event.key in {"escape", "n"}: self._confirmed = True; self.dismiss(None) + elif event.key == "y" and self.can_setup: self._choice = "confirm"; self._render_choice(); self._activate() + elif event.key in {"left", "right", "tab", "shift+tab"} and self.can_setup: + self._choice = "confirm" if self._choice == "cancel" else "cancel"; self._render_choice() + self.query_one("#library-dialog-confirm" if self._choice == "confirm" else "#library-dialog-cancel", LibraryDialogAction).focus() + elif event.key == "enter": self._activate() + elif event.key in {"1", "2", "3", "4", "5"}: pass + else: return + event.prevent_default(); event.stop() + + def _activate(self) -> None: + if self._choice == "cancel": self._confirmed = True; self.dismiss(None) + elif self.can_setup and not self._confirmed: self._confirmed = True; self.dismiss(self.snapshot) + + +class LibraryScreen(HubScreen): + """Local library browser and safe maintenance centre.""" + + BINDINGS = [Binding("/", "focus_search", "Search", show=False)] + + def __init__( + self, + settings: Any, + *, + snapshot_provider: SnapshotProvider, + index_sync_provider: IndexSyncProvider, + identity_provider: IdentityProvider, + identity_rebuild_plan_provider: IdentityRebuildPlanProvider, + identity_rebuild_execution_provider: IdentityRebuildExecutionProvider, + preview_provider: PreviewProvider, + execution_provider: ExecutionProvider, + backup_provider: BackupProvider, + restore_provider: RestoreProvider, + rmpc_status_provider: RmpcStatusProvider, + rmpc_setup_provider: RmpcSetupProvider, + manual_search_provider: ManualSearchProvider, + catalogue_details_provider: CatalogueDetailsProvider = get_song_details_by_id, + metadata_audit_provider: MetadataAuditProvider = audit_track_metadata, + metadata_repair_plan_provider: MetadataRepairPlanProvider = plan_metadata_repair, + metadata_repair_execution_provider: MetadataRepairExecutionProvider = execute_metadata_repair, + manual_identity_provider: ManualIdentityProvider = set_manual_identity, + manual_unlock_provider: ManualIdentityProvider = unlock_manual_identity, + missing_library_provider: MissingLibraryProvider = get_missing_library, + queue_plan_provider: QueuePlanProvider = plan_queue_batch_additions, + queue_add_provider: QueueAddProvider = add_batch_to_download_queue, + ) -> None: + super().__init__("library", "Library") + self.settings = settings + self._snapshot_provider = snapshot_provider + self._index_sync_provider = index_sync_provider + self._identity_provider = identity_provider + self._identity_rebuild_plan_provider = identity_rebuild_plan_provider + self._identity_rebuild_execution_provider = identity_rebuild_execution_provider + self._preview_provider = preview_provider + self._execution_provider = execution_provider + self._backup_provider = backup_provider + self._restore_provider = restore_provider + self._rmpc_status_provider = rmpc_status_provider + self._rmpc_setup_provider = rmpc_setup_provider + self._manual_search_provider = manual_search_provider + self._catalogue_details_provider = catalogue_details_provider + self._metadata_audit_provider = metadata_audit_provider + self._metadata_repair_plan_provider = metadata_repair_plan_provider + self._metadata_repair_execution_provider = metadata_repair_execution_provider + self._manual_identity_provider = manual_identity_provider + self._manual_unlock_provider = manual_unlock_provider + self._missing_library_provider = missing_library_provider + self._queue_plan_provider = queue_plan_provider + self._queue_add_provider = queue_add_provider + self.snapshot: LibrarySnapshot | None = None + self.filtered_tracks: tuple[LibraryTrack, ...] = () + self.selected_index = 0 + self.preview: LibrarySyncPlan | None = None + self._details_mode = False + self._snapshot_worker: Worker[SnapshotOutcome] | None = None + self._identity_worker: Worker[IdentityOutcome] | None = None + self._index_sync_worker: Worker[LibraryIndexSyncResult] | None = None + self._pending_index_sync: LibraryIndexSyncResult | None = None + self._identity_rebuild_plan_worker: Worker[IdentityRebuildPlanOutcome] | None = None + self._identity_rebuild_worker: Worker[IdentityRebuildOutcome] | None = None + self._preview_worker: Worker[PreviewOutcome] | None = None + self._pending_snapshot: SnapshotOutcome | None = None + self._pending_identity: IdentityOutcome | None = None + self._pending_preview: PreviewOutcome | None = None + self._preview_action: str | None = None + self._execution_worker: Worker[ExecutionOutcome] | None = None + self._backup_worker: Worker[BackupOutcome] | None = None + self._restore_worker: Worker[tuple[int | None, str | None]] | None = None + self._rmpc_worker: Worker[tuple[SettingsSnapshot | None, str | None]] | None = None + self._rmpc_setup_worker: Worker[tuple[Path | None, str | None]] | None = None + self._snapshot_action = "scan" + self._maintenance_completed = 0 + self._maintenance_total = 0 + self._completion_message: tuple[str, bool] | None = None + self._identify_requested = False + self._identity_rebuild_completed = 0 + self._manual_identity_worker: Worker[ManualIdentityOutcome] | None = None + self._manual_track: LibraryTrack | None = None + self._metadata_audit_worker: Worker[MetadataAuditOutcome] | None = None + self._pending_metadata_audit: MetadataAuditOutcome | None = None + self._metadata_audit_cache: dict[tuple[str, str | None, str], MetadataAudit] = {} + self._metadata_repair_plan_worker: Worker[MetadataRepairPlanOutcome] | None = None + self._metadata_repair_worker: Worker[MetadataRepairOutcome] | None = None + + def compose_content(self) -> Iterable[Widget]: + yield Static( + "0 tracks · 0 follow-ups · 0 errors\n" + "Lyrics to improve 0 · Fully covered 0 · Catalogue unknown 0 · " + "MP3 0 · FLAC 0 · M4A 0", + id="library-summary", + markup=False, + ) + yield Static("Loading local audio library…", id="library-status", markup=False) + with Grid(id="library-controls"): + with Vertical(classes="library-filter"): + yield Static("Local search", classes="filter-label") + yield LibraryInput(placeholder="Optional title or filename", id="library-query") + with Vertical(classes="library-filter"): + yield Static("Status", classes="filter-label") + yield LibrarySelect(_FILTER_OPTIONS, value=LibraryFilter.ALL.value, allow_blank=False, id="library-filter") + with Grid(id="library-main"): + with Container(classes="library-panel", id="library-tracks-panel"): + yield Static("Tracks · loading", classes="panel-title", id="library-tracks-title") + with VerticalScroll(id="library-tracks-scroll"): + yield Static("Loading tracks…", id="library-tracks", markup=False) + with Container(classes="library-panel", id="library-details-panel"): + yield Static("Track details", classes="panel-title") + with VerticalScroll(id="library-details-scroll"): + yield Static("Select a track to inspect it.", id="library-details", markup=False) + yield Static("Sync Library updates the catalogue view without changing audio or lyrics.", id="library-preview", markup=False) + yield Static("s Sync Library · a Issues · g Missing · d Duplicates · ↑↓ Move · Enter Details · ? Help", id="library-position", markup=False) + + def action_focus_search(self) -> None: + self.query_one("#library-query", Input).focus() + + def on_screen_resume(self, event: ScreenResume) -> None: + self.call_after_refresh(self.set_focus, None) + if self._pending_index_sync is not None: + outcome, self._pending_index_sync = self._pending_index_sync, None + self._apply_index_sync(outcome) + if self._pending_snapshot is not None: + outcome, self._pending_snapshot = self._pending_snapshot, None + self._apply_snapshot(outcome) + elif self.snapshot is None and self._snapshot_worker is None: + self.refresh_snapshot(identify=False) + if self._pending_preview is not None: + outcome, self._pending_preview = self._pending_preview, None + self._apply_preview(outcome) + if self._pending_identity is not None: + outcome, self._pending_identity = self._pending_identity, None + self._apply_identity(outcome) + if self._pending_metadata_audit is not None: + outcome, self._pending_metadata_audit = self._pending_metadata_audit, None + self._apply_metadata_audit(outcome) + + def refresh_snapshot(self, *, identify: bool = True) -> None: + if self._index_sync_worker is not None and not self._index_sync_worker.is_finished: + self._set_status("Library Sync is running; the view will update when it finishes.") + return + if self.snapshot is None: + self.query_one("#library-tracks", Static).update("Loading tracks…") + self.query_one("#library-details", Static).update("Waiting for library data…") + self.preview = None + self.query_one("#library-preview", Static).update("Sync Library updates the catalogue view without changing audio or lyrics.") + self._identify_requested = identify and self._snapshot_action != "verify" + self._set_status("Verifying library…" if self._snapshot_action == "verify" else "Scanning library…") + self._snapshot_worker = self._load_snapshot() + + def invalidate_snapshot(self) -> None: + self.snapshot = None + self.preview = None + self._snapshot_worker = None + self._identity_worker = None + self._identity_rebuild_plan_worker = None + self._identity_rebuild_worker = None + self._manual_identity_worker = None + self._manual_track = None + self._metadata_audit_worker = None + self._pending_metadata_audit = None + self._metadata_audit_cache.clear() + self._metadata_repair_plan_worker = None + self._metadata_repair_worker = None + self._preview_worker = None + self._pending_snapshot = None + self._pending_identity = None + self._pending_preview = None + + def sync_library(self) -> None: + if self._index_sync_worker is not None and not self._index_sync_worker.is_finished: + self._set_status("Library Sync is already running.") + return + self._snapshot_worker = None + self._identity_worker = None + self._set_status("Syncing library…") + self._index_sync_worker = self._run_index_sync(self.snapshot) + + @work(thread=True, exclusive=True, group="library-index-sync", exit_on_error=False) + def _run_index_sync(self, previous: LibrarySnapshot | None) -> LibraryIndexSyncResult: + return self._index_sync_provider(self.settings, previous_snapshot=previous) + + def _apply_index_sync(self, result: LibraryIndexSyncResult) -> None: + self._index_sync_worker = None + self._identify_requested = False + self._apply_snapshot(SnapshotOutcome(result.snapshot)) + self._set_status(result.summary, error=bool(result.error or result.failed)) + + @work(thread=True, exclusive=True, group="library-snapshot", exit_on_error=False) + def _load_snapshot(self) -> SnapshotOutcome: + try: + return SnapshotOutcome(self._snapshot_provider(self.settings)) + except Exception as exc: + return SnapshotOutcome(error=str(exc) or type(exc).__name__) + + def generate_preview(self, *, action: str = "preview", selected_path: Path | None = None) -> None: + if self.snapshot is None: + self._set_status("Load the library before generating a sync preview.", error=True) + return + self._preview_action = action + self.query_one("#library-preview", Static).update("Checking library needs… · No files are being changed") + self._preview_worker = self._load_preview(selected_path) + + @work(thread=True, exclusive=True, group="library-preview", exit_on_error=False) + def _load_preview(self, selected_path: Path | None = None) -> PreviewOutcome: + try: + if selected_path is None: + if self._preview_action != "maintain" or self.snapshot is None: + return PreviewOutcome(self._preview_provider(self.settings)) + protected_paths = tuple( + track.path + for track in self.snapshot.tracks + if track.fully_covered + and track.match_status is LibraryMatchStatus.UNMATCHED + ) + return PreviewOutcome( + self._preview_provider( + self.settings, + protected_paths=protected_paths, + ) + ) + return PreviewOutcome( + self._preview_provider( + self.settings, + refresh=True, + selected_paths=(selected_path,), + ) + ) + except Exception as exc: + return PreviewOutcome(error=str(exc) or type(exc).__name__) + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is self._index_sync_worker: + if event.state is WorkerState.SUCCESS: + if self._can_render(): + self._apply_index_sync(event.worker.result) + else: + self._pending_index_sync = event.worker.result + elif event.state is WorkerState.ERROR: + self._index_sync_worker = None + self._set_status("Library Sync stopped safely. Please try again.", error=True) + elif event.worker is self._snapshot_worker: + if event.state is WorkerState.SUCCESS: + outcome = event.worker.result + if self._can_render(): + self._apply_snapshot(outcome) + else: + self._pending_snapshot = outcome + elif event.state is WorkerState.ERROR: + outcome = SnapshotOutcome(error="Library scan stopped unexpectedly") + if self._can_render(): + self._apply_snapshot(outcome) + else: + self._pending_snapshot = outcome + elif event.worker is self._identity_worker: + if event.state is WorkerState.SUCCESS: + outcome = event.worker.result + if self._can_render(): + self._apply_identity(outcome) + else: + self._pending_identity = outcome + elif event.state is WorkerState.ERROR: + outcome = IdentityOutcome(error="Catalogue identification stopped unexpectedly") + if self._can_render(): + self._apply_identity(outcome) + else: + self._pending_identity = outcome + elif event.worker is self._identity_rebuild_plan_worker: + if event.state is WorkerState.SUCCESS: + self._apply_identity_rebuild_plan(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_identity_rebuild_plan( + IdentityRebuildPlanOutcome(error="Catalogue rebuild preview stopped unexpectedly") + ) + elif event.worker is self._identity_rebuild_worker: + if event.state is WorkerState.SUCCESS: + self._apply_identity_rebuild(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_identity_rebuild( + IdentityRebuildOutcome(error="Catalogue rebuild stopped unexpectedly") + ) + elif event.worker is self._manual_identity_worker: + if event.state is WorkerState.SUCCESS: + self._apply_manual_identity(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_manual_identity( + ManualIdentityOutcome(error="Catalogue match update stopped safely.") + ) + elif event.worker is self._metadata_audit_worker: + if event.state is WorkerState.SUCCESS: + outcome = event.worker.result + if self._can_render(): + self._apply_metadata_audit(outcome) + else: + self._pending_metadata_audit = outcome + elif event.state is WorkerState.ERROR: + self._apply_metadata_audit( + MetadataAuditOutcome("", error="Metadata preview stopped safely.") + ) + elif event.worker is self._metadata_repair_plan_worker: + if event.state is WorkerState.SUCCESS: + self._apply_metadata_repair_plan(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_metadata_repair_plan( + MetadataRepairPlanOutcome(error="Metadata repair planning stopped safely.") + ) + elif event.worker is self._metadata_repair_worker: + if event.state is WorkerState.SUCCESS: + self._apply_metadata_repair(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_metadata_repair( + MetadataRepairOutcome(error="Metadata repair stopped safely.") + ) + elif event.worker is self._preview_worker: + if event.state is WorkerState.SUCCESS: + outcome = event.worker.result + if self._can_render(): + self._apply_preview(outcome) + else: + self._pending_preview = outcome + elif event.state is WorkerState.ERROR: + outcome = PreviewOutcome(error="Maintenance preview stopped unexpectedly") + if self._can_render(): + self._apply_preview(outcome) + else: + self._pending_preview = outcome + elif event.worker is self._execution_worker: + if event.state is WorkerState.SUCCESS: + self._apply_execution(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_execution(ExecutionOutcome(error="Library maintenance stopped unexpectedly.")) + elif event.worker is self._backup_worker: + if event.state is WorkerState.SUCCESS: + self._apply_backups(event.worker.result) + elif event.state is WorkerState.ERROR: + self._apply_backups(BackupOutcome(error="Backups could not be inspected.")) + elif event.worker is self._restore_worker: + if event.state is WorkerState.SUCCESS: + count, error = event.worker.result + self._apply_restore(count, error) + elif event.state is WorkerState.ERROR: + self._apply_restore(None, "Restore stopped unexpectedly.") + elif event.worker is self._rmpc_worker and event.state is WorkerState.SUCCESS: + snapshot, error = event.worker.result + self._rmpc_worker = None + if error or snapshot is None: self._set_status(f"rmpc check failed: {error or 'Unknown error'}", error=True) + else: self.app.push_screen(RmpcDialog(snapshot), self._rmpc_dialog_closed) + elif event.worker is self._rmpc_worker and event.state is WorkerState.ERROR: + self._rmpc_worker = None + self._set_status("rmpc check stopped unexpectedly.", error=True) + elif event.worker is self._rmpc_setup_worker and event.state is WorkerState.SUCCESS: + path, error = event.worker.result + self._rmpc_setup_worker = None + self._set_status(f"rmpc setup failed safely: {error}", error=True) if error else self._set_status(f"rmpc setup complete · previous config backed up at {path}") + elif event.worker is self._rmpc_setup_worker and event.state is WorkerState.ERROR: + self._rmpc_setup_worker = None + self._set_status("rmpc setup stopped safely.", error=True) + + def _can_render(self) -> bool: + if not self.is_mounted or not list(self.query("#library-summary")): + return False + try: + return self.app.screen is self + except Exception: + return False + + def _apply_snapshot(self, outcome: SnapshotOutcome) -> None: + if outcome.error or outcome.snapshot is None: + self._set_status(f"Library unavailable: {outcome.error or 'Unknown library error'}", error=True) + if self.snapshot is None: + self.filtered_tracks = () + self.query_one("#library-tracks-title", Static).update("Tracks · unavailable") + self.query_one("#library-tracks", Static).update("Unable to load local tracks.") + self.query_one("#library-details", Static).update("Track details are unavailable.") + return + + previous_reference = self.selected_track.reference if self.selected_track else None + self.snapshot = outcome.snapshot + self.set_focus(None) + self.preview = None + self._details_mode = False + self.remove_class("-details-mode") + self._render_summary() + self._apply_local_filter(preferred_reference=previous_reference) + action, self._snapshot_action = self._snapshot_action, "scan" + completion, self._completion_message = self._completion_message, None + if not outcome.snapshot.directory_exists: + self._set_status(outcome.snapshot.warnings[0], error=True) + elif not outcome.snapshot.tracks: + self._set_status("No supported MP3, FLAC, or M4A tracks found.") + elif outcome.snapshot.warnings: + self._set_status(" ".join(outcome.snapshot.warnings), error=True) + elif completion is not None: + self._set_status(completion[0], error=completion[1]) + elif action == "verify": + health = get_library_health(outcome.snapshot) + errors = sum( + issue.severity is LibraryIssueSeverity.ERROR + for issue in health.issues + ) + self._set_status( + f"Verification complete · {health.issue_count} follow-ups · " + f"{errors} errors" + ) + if outcome.snapshot.needs_attention_count: + self.query_one("#library-filter", Select).value = LibraryFilter.ATTENTION.value + else: + self._set_status( + f"Library refreshed · {outcome.snapshot.total_track_count} " + f"song{'s' if outcome.snapshot.total_track_count != 1 else ''} found" + ) + identify = self._identify_requested + self._identify_requested = False + if identify and outcome.snapshot.unmatched_count: + unknown = tuple( + track + for track in outcome.snapshot.tracks + if track.match_status is LibraryMatchStatus.UNMATCHED + ) + self._set_status( + f"Library refreshed · {outcome.snapshot.total_track_count} " + f"song{'s' if outcome.snapshot.total_track_count != 1 else ''} found · " + f"Identifying {len(unknown)} catalogue entr{'y' if len(unknown) == 1 else 'ies'}…" + ) + self._identity_worker = self._identify_unknown(unknown) + + @work(thread=True, exclusive=True, group="library-identity", exit_on_error=False) + def _identify_unknown(self, tracks: tuple[LibraryTrack, ...]) -> IdentityOutcome: + try: + return IdentityOutcome(self._identity_provider(self.settings, tracks)) + except Exception as exc: + return IdentityOutcome(error=str(exc) or type(exc).__name__) + + def _apply_identity(self, outcome: IdentityOutcome) -> None: + self._identity_worker = None + snapshot = self.snapshot + if outcome.error or outcome.result is None: + self._set_status( + "Catalogue identification unavailable · Local library health is still available", + error=True, + ) + return + result = outcome.result + if result.identified: + message = ( + f"Catalogue identification complete · {result.identified} " + f"song{'s' if result.identified != 1 else ''} identified" + ) + remaining = result.unknown + result.failed + if remaining: + message += f" · {remaining} remain unknown" + self._completion_message = (message, bool(result.failed)) + self.refresh_snapshot(identify=False) + return + count = snapshot.total_track_count if snapshot is not None else result.inspected + if result.failed: + self._set_status( + f"Library refreshed · {count} song{'s' if count != 1 else ''} found · " + "Catalogue identification unavailable", + error=True, + ) + else: + self._set_status( + f"Library refreshed · {count} song{'s' if count != 1 else ''} found · " + f"{result.unknown} catalogue match{'es' if result.unknown != 1 else ''} remain unknown" + ) + + def _apply_preview(self, outcome: PreviewOutcome) -> None: + if outcome.error or outcome.plan is None: + self.preview = None + self.query_one("#library-preview", Static).update( + f"Preview failed: {outcome.error or 'Unknown preview error'} · Preview only — no files changed" + ) + self._set_status("Maintenance preview unavailable.", error=True) + self._render_details() + return + self.preview = outcome.plan + plan = outcome.plan + unavailable_locks = { + item.path + for item in plan.tracks + if item.identity_locked + and item.error + and "manually selected catalogue recording is unavailable" + in item.error.casefold() + } + if unavailable_locks and self.snapshot is not None: + marker = "The manually selected catalogue recording is unavailable." + self.snapshot = replace( + self.snapshot, + tracks=tuple( + replace( + track, + warning=( + f"{track.warning} {marker}" if track.warning else marker + ), + ) + if track.path in unavailable_locks + and marker.casefold() not in (track.warning or "").casefold() + else track + for track in self.snapshot.tracks + ), + ) + self._render_summary() + self._apply_local_filter(preferred_reference=self.selected_track.reference if self.selected_track else None) + lrc = plan.synced_files if plan.options.rmpc_enabled else 0 + lrc_destination = " · LRC beside each song" if lrc else "" + self.query_one("#library-preview", Static).update( + f"Preview only — no files changed · Current {plan.unchanged_files} · Update {plan.ready_files} " + f"(Synced {plan.synced_files}, Plain {plan.plain_files}) · LRC {lrc} · " + f"Unresolved {plan.unresolved_files} · No lyrics {plan.no_lyrics_files} · Errors {plan.analysis_failures}" + f"{lrc_destination}" + ) + self._set_status("Maintenance preview ready. No files were changed.") + self._render_details() + action, self._preview_action = self._preview_action, None + if action in {"maintain", "selected"} and self.app.screen is self: + if plan.ready_files or plan.unresolved_files or plan.no_lyrics_files or plan.analysis_failures: + self.app.push_screen(MaintenanceDialog(plan), self._maintenance_dialog_closed) + else: + self._set_status("Your library is up to date." if action == "maintain" else "This song is up to date.") + + @property + def selected_track(self) -> LibraryTrack | None: + if not self.filtered_tracks: + return None + return self.filtered_tracks[self.selected_index] + + def _render_summary(self) -> None: + snapshot = self.snapshot + if snapshot is None: + return + health = get_library_health(snapshot) + errors = sum( + issue.severity is LibraryIssueSeverity.ERROR for issue in health.issues + ) + self.query_one("#library-summary", Static).update( + f"{snapshot.total_track_count} tracks · {health.issue_count} follow-ups · " + f"{errors} errors\nLyrics to improve {snapshot.needs_attention_count} · " + f"Fully covered {snapshot.fully_covered_count} · " + f"Catalogue unknown {snapshot.unmatched_count} · " + f"MP3 {snapshot.format_count('MP3')} · " + f"FLAC {snapshot.format_count('FLAC')} · M4A {snapshot.format_count('M4A')}" + ) + + def on_input_submitted(self, event: Input.Submitted) -> None: + self.set_focus(None) + self._apply_local_filter() + + def on_select_changed(self, event: Select.Changed) -> None: + self._apply_local_filter() + + def _apply_local_filter(self, *, preferred_reference: str | None = None) -> None: + if self.snapshot is None: + return + current_reference = preferred_reference or (self.selected_track.reference if self.selected_track else None) + query = self.query_one("#library-query", Input).value.strip().casefold() + raw_filter = self.query_one("#library-filter", Select).value + selected_filter = LibraryFilter(str(raw_filter)) if raw_filter is not Select.BLANK else LibraryFilter.ALL + tracks = tuple( + track for track in self.snapshot.tracks + if _matches_filter(track, selected_filter) + and (not query or query in track.title.casefold() or query in track.filename.casefold()) + ) + self.filtered_tracks = tracks + self.selected_index = next( + (index for index, track in enumerate(tracks) if track.reference == current_reference), + 0, + ) + self._render_tracks() + self._render_details() + self._update_position() + self.query_one("#library-tracks-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + if tracks: + self.call_after_refresh(self._scroll_selection_into_view) + + def _render_tracks(self) -> None: + self.query_one("#library-tracks-title", Static).update( + f"Tracks · {len(self.filtered_tracks)} of " + f"{self.snapshot.total_track_count if self.snapshot else 0} · ! error · ~ follow-up" + ) + if not self.filtered_tracks: + message = "No tracks match the local search or filter." if self.snapshot and self.snapshot.tracks else "No supported audio tracks found." + self.query_one("#library-tracks", Static).update(message) + return + lines = [] + issues_by_reference = { + issue.track.reference: issue + for issue in get_library_health(self.snapshot).issues + } if self.snapshot is not None else {} + for index, track in enumerate(self.filtered_tracks): + marker = ">" if index == self.selected_index else " " + issue = issues_by_reference.get(track.reference) + attention = ( + "!" + if issue is not None and issue.severity is LibraryIssueSeverity.ERROR + else "~" if issue is not None else " " + ) + lines.append( + f"{marker}{attention} {track.title[:30]:30} · {_match_label(track):9} · " + f"{_lyric_label(track.lyric_status):13} · LRC {_lrc_label(track.lrc_status)}" + ) + self.query_one("#library-tracks", Static).update( + Text("\n".join(lines), no_wrap=True, overflow="ellipsis") + ) + + def _render_details(self) -> None: + track = self.selected_track + details = self.query_one("#library-details", Static) + self.query_one("#library-details-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + if track is None: + details.update("No track selected.") + return + issue = next( + ( + item + for item in get_library_health(self.snapshot).issues + if item.track.reference == track.reference + ), + None, + ) if self.snapshot is not None else None + lines = [ + track.title, + "", + f"Filename {track.filename}", + f"Format {track.media_format}", + f"Artist {track.artist or 'Not available'}", + f"Album {track.album or 'Not available'}", + f"Relative path {track.relative_path}", + f"Full path {track.path}", + f"Catalogue match {track.matched_title or _match_label(track)}", + f"Match source {'Manual (locked)' if track.identity_locked else 'Automatic' if track.match_status is LibraryMatchStatus.MATCHED else 'Not identified'}", + f"Duration {_duration(track.duration_seconds)}", + f"Lyrics {_lyric_label(track.lyric_status)}", + f"External LRC {_lrc_label(track.lrc_status)}", + f"LRC path {track.lrc_path or 'Not recorded'}", + f"Library state {_state_label(track.state_status)}", + f"Library issue {issue.summary if issue is not None else 'None'}", + f"Coverage {'Fully covered' if track.fully_covered else _coverage_label(track)}", + ] + if track.warning: + lines.extend(("", f"Warning {track.warning}")) + if track.match_status is LibraryMatchStatus.UNMATCHED: + lines.extend(("", "Automatic refresh requires a catalogue match.")) + lines.extend(("", "Lyric maintenance preview", _track_preview_text(self.preview, track.path))) + details.update(Text("\n".join(lines), overflow="ellipsis")) + + def _update_position(self) -> None: + if not self.filtered_tracks: + self.query_one("#library-position", Static).update("s Sync Library · a Issues · g Missing · d Duplicates · ? Help") + return + suffix = "Esc Back · e Metadata · c Match · l Refresh · ? Help" if self._details_mode else "s Sync Library · a Issues · g Missing · d Duplicates · e Metadata · ↑↓ Move · ? Help" + self.query_one("#library-position", Static).update( + f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" + ) + + def on_key(self, event: Key) -> None: + if any(select.expanded for select in self.query(Select)): + return + if isinstance(self.app.focused, (Input, Select)): + return + if event.key == "s": + self.sync_library() + elif event.key == "a": + self._open_issues() + elif event.key == "d": + self._open_duplicates() + elif event.key == "g": + self._open_missing_library() + elif event.key == "e" and self.selected_track is not None: + self._open_metadata_audit(self.selected_track) + elif event.key == "m": + self.generate_preview(action="maintain") + elif event.key == "v": + self._snapshot_action = "verify" + self.refresh_snapshot() + elif event.key == "b": + self._open_backups() + elif event.key == "p": + self._check_rmpc() + elif event.key == "i": + self._preview_identity_rebuild() + elif event.key == "c" and self.selected_track is not None: + self._open_manual_match() + elif event.key == "u" and self.selected_track is not None: + self._unlock_manual_match() + elif event.key == "l" and self.selected_track is not None: + self.generate_preview(action="selected", selected_path=self.selected_track.path) + elif event.key == "escape" and self._details_mode: + self._details_mode = False + self.remove_class("-details-mode") + self._update_position() + elif event.key == "enter" and self.selected_track is not None: + self._details_mode = True + self.add_class("-details-mode") + self.query_one("#library-details-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + self._update_position() + elif event.key in ("down", "j"): + self._select_track(self.selected_index + 1) + elif event.key in ("up", "k"): + self._select_track(self.selected_index - 1) + elif event.key == "home": + self._select_track(0) + elif event.key == "end": + self._select_track(len(self.filtered_tracks) - 1) + elif event.key in ("pagedown", "pageup") and self._details_mode: + scroll = self.query_one("#library-details-scroll", VerticalScroll) + (scroll.scroll_page_down if event.key == "pagedown" else scroll.scroll_page_up)(animate=False) + elif event.key in ("pagedown", "pageup"): + scroll = self.query_one("#library-tracks-scroll", VerticalScroll) + step = max(1, scroll.size.height - 1) + self._select_track(self.selected_index + (step if event.key == "pagedown" else -step)) + else: + return + event.prevent_default() + event.stop() + + def _open_issues(self) -> None: + if self.snapshot is None: + self._set_status("Load the library before viewing Issues.", error=True) + return + self.app.push_screen( + LibraryIssuesDialog(get_library_health(self.snapshot)), + self._issue_action_selected, + ) + + def _open_duplicates(self) -> None: + if self.snapshot is None: + self._set_status("Load the library before viewing duplicates.", error=True) + return + self.app.push_screen( + LibraryDuplicatesDialog( + detect_library_duplicates( + self.snapshot, + duration_tolerance=self.settings.duration_tolerance, + ) + ) + ) + + def _open_missing_library(self) -> None: + if self.snapshot is None: + self._set_status("Load the library before checking Missing Library.", error=True) + return + self.app.push_screen( + MissingLibraryDialog( + self.settings, + self.snapshot, + report_provider=self._missing_library_provider, + queue_plan_provider=self._queue_plan_provider, + queue_add_provider=self._queue_add_provider, + ) + ) + + def _issue_action_selected(self, choice: LibraryIssueChoice | None) -> None: + if choice is None: + self._set_status("Issues closed. No files were changed.") + return + track = next( + ( + item + for item in self.snapshot.tracks + if item.reference == choice.reference + ), + None, + ) if self.snapshot is not None else None + if choice.action is LibraryIssueAction.SYNC: + self.sync_library() + elif choice.action is LibraryIssueAction.VERIFY: + self._snapshot_action = "verify" + self.refresh_snapshot(identify=False) + elif track is None: + self._set_status("That track is no longer in the current Library view.", error=True) + elif choice.action is LibraryIssueAction.MANUAL_MATCH: + self._open_manual_match(track) + elif choice.action is LibraryIssueAction.REFRESH_LYRICS: + self.generate_preview(action="selected", selected_path=track.path) + elif choice.action is LibraryIssueAction.METADATA_AUDIT: + self._open_metadata_audit(track) + + def _metadata_cache_key(self, track: LibraryTrack) -> tuple[str, str | None, str]: + return track.reference, track.content_sha256, str(track.catalogue_id) + + def _open_metadata_audit(self, track: LibraryTrack) -> None: + if ( + self._metadata_repair_plan_worker is not None + and not self._metadata_repair_plan_worker.is_finished + ) or ( + self._metadata_repair_worker is not None + and not self._metadata_repair_worker.is_finished + ): + self._set_status("A metadata repair is already running.") + return + if self._metadata_audit_worker is not None and not self._metadata_audit_worker.is_finished: + self._set_status("A metadata preview is already being prepared.") + return + cached = self._metadata_audit_cache.get(self._metadata_cache_key(track)) + if cached is not None: + self._show_metadata_audit(cached) + return + self._set_status("Preparing metadata repair preview… · No files are being changed") + self._metadata_audit_worker = self._load_metadata_audit(track) + + @work(thread=True, exclusive=True, group="metadata-audit", exit_on_error=False) + def _load_metadata_audit(self, track: LibraryTrack) -> MetadataAuditOutcome: + try: + return MetadataAuditOutcome( + track.reference, + self._metadata_audit_provider( + self.settings, + track, + details_provider=self._catalogue_details_provider, + ), + ) + except Exception as exc: + return MetadataAuditOutcome( + track.reference, + error=str(exc) or type(exc).__name__, + ) + + def _apply_metadata_audit(self, outcome: MetadataAuditOutcome) -> None: + self._metadata_audit_worker = None + track = next( + (item for item in self.snapshot.tracks if item.reference == outcome.reference), + None, + ) if self.snapshot is not None else None + if outcome.error or outcome.audit is None: + self._set_status( + f"Metadata preview unavailable: {outcome.error or 'Unknown error'}", + error=True, + ) + return + if track is None or self._metadata_cache_key(track) != self._metadata_cache_key(outcome.audit.track): + self._set_status("The selected track changed; refresh and preview it again.", error=True) + return + self._metadata_audit_cache[self._metadata_cache_key(track)] = outcome.audit + self._set_status("Metadata repair preview ready · No files were changed") + self._show_metadata_audit(outcome.audit) + + def _show_metadata_audit(self, audit: MetadataAudit) -> None: + self.app.push_screen( + MetadataAuditDialog(audit), + lambda fields: self._metadata_selection_closed(audit, fields), + ) + + def _metadata_selection_closed( + self, audit: MetadataAudit, fields: tuple[str, ...] | None + ) -> None: + if fields is None: + self._set_status("Metadata repair cancelled. No files were changed.") + return + if not fields: + self._set_status("Select at least one metadata field.", error=True) + return + if ( + self._metadata_repair_plan_worker is not None + and not self._metadata_repair_plan_worker.is_finished + ) or ( + self._metadata_repair_worker is not None + and not self._metadata_repair_worker.is_finished + ): + self._set_status("A metadata repair is already running.") + return + self._set_status("Checking selected metadata fields… · No files are being changed") + self._metadata_repair_plan_worker = self._plan_metadata_repair(audit, fields) + + @work(thread=True, exclusive=True, group="metadata-repair-plan", exit_on_error=False) + def _plan_metadata_repair( + self, audit: MetadataAudit, fields: tuple[str, ...] + ) -> MetadataRepairPlanOutcome: + try: + return MetadataRepairPlanOutcome( + self._metadata_repair_plan_provider(self.settings, audit, fields) + ) + except Exception as exc: + return MetadataRepairPlanOutcome(error=str(exc) or type(exc).__name__) + + def _apply_metadata_repair_plan(self, outcome: MetadataRepairPlanOutcome) -> None: + self._metadata_repair_plan_worker = None + if outcome.error or outcome.plan is None: + self._set_status( + f"Metadata repair unavailable: {outcome.error or 'Unknown error'}", + error=True, + ) + return + self._set_status("Metadata repair ready for confirmation · No files were changed") + self.app.push_screen( + MetadataRepairConfirmationDialog(outcome.plan), + lambda confirmed: self._metadata_repair_confirmation_closed( + outcome.plan, confirmed + ), + ) + + def _metadata_repair_confirmation_closed( + self, plan: MetadataRepairPlan, confirmed: bool + ) -> None: + if not confirmed: + self._set_status("Metadata repair cancelled. No files were changed.") + return + if self._metadata_repair_worker is not None and not self._metadata_repair_worker.is_finished: + self._set_status("A metadata repair is already running.") + return + self._set_status("Applying metadata repair… · 0 / 1 · Creating a backup first") + self._metadata_repair_worker = self._execute_metadata_repair(plan) + + @work(thread=True, exclusive=True, group="metadata-repair-apply", exit_on_error=False) + def _execute_metadata_repair( + self, plan: MetadataRepairPlan + ) -> MetadataRepairOutcome: + try: + return MetadataRepairOutcome( + self._metadata_repair_execution_provider(plan, confirmed=True) + ) + except BaseException as exc: + return MetadataRepairOutcome(error=str(exc) or type(exc).__name__) + + def _apply_metadata_repair(self, outcome: MetadataRepairOutcome) -> None: + self._metadata_repair_worker = None + if outcome.error or outcome.result is None: + message = outcome.error or "Unknown error" + if "rollback failed" in message.casefold(): + self._set_status( + f"Metadata repair needs recovery: {message} · The backup was retained", + error=True, + ) + else: + self._set_status( + f"Metadata repair failed safely: {message} · Existing data was preserved or restored", + error=True, + ) + return + result = outcome.result + fields = ", ".join(result.fields) + self._metadata_audit_cache.clear() + self._completion_message = ( + f"Metadata repaired · {fields} · Backup: {result.backup_path}", + False, + ) + self._set_status("Metadata repair complete · Refreshing Library health…") + self.refresh_snapshot(identify=False) + + def _open_manual_match(self, track: LibraryTrack | None = None) -> None: + track = track or self.selected_track + if track is None or ( + self._manual_identity_worker is not None + and not self._manual_identity_worker.is_finished + ): + return + self._manual_track = track + self.app.push_screen( + ManualMatchDialog(self.settings, track, self._manual_search_provider), + self._manual_match_closed, + ) + + def _manual_match_closed(self, choice: ManualMatchChoice | None) -> None: + track, self._manual_track = self._manual_track, None + if choice is None: + self._set_status("Manual catalogue matching cancelled. No changes were made.") + return + if track is None: + self._set_status("The selected track is no longer available.", error=True) + return + self._set_status("Saving manual catalogue match…") + self._manual_identity_worker = self._save_manual_identity(track, choice) + + def _unlock_manual_match(self) -> None: + track = self.selected_track + if track is None: + return + if not track.identity_locked: + self._set_status("This track does not have a manual catalogue lock.") + return + if self._manual_identity_worker is not None and not self._manual_identity_worker.is_finished: + return + self._set_status("Unlocking catalogue match…") + self._manual_identity_worker = self._unlock_identity(track) + + @work(thread=True, exclusive=True, group="manual-identity-write", exit_on_error=False) + def _save_manual_identity( + self, + track: LibraryTrack, + choice: ManualMatchChoice, + ) -> ManualIdentityOutcome: + try: + return ManualIdentityOutcome( + self._manual_identity_provider( + self.settings, + track, + song_id=choice.song_id, + api_name=choice.api_name, + ), + action="match", + ) + except Exception as exc: + return ManualIdentityOutcome(error=str(exc) or type(exc).__name__, action="match") + + @work(thread=True, exclusive=True, group="manual-identity-write", exit_on_error=False) + def _unlock_identity(self, track: LibraryTrack) -> ManualIdentityOutcome: + try: + return ManualIdentityOutcome( + self._manual_unlock_provider(self.settings, track), + action="unlock", + ) + except Exception as exc: + return ManualIdentityOutcome(error=str(exc) or type(exc).__name__, action="unlock") + + def _apply_manual_identity(self, outcome: ManualIdentityOutcome) -> None: + self._manual_identity_worker = None + if outcome.error or outcome.result is None: + self._set_status( + f"Catalogue match was not changed: {outcome.error or 'Unknown error'}", + error=True, + ) + return + if outcome.action == "unlock": + message = "Manual catalogue match unlocked and cleared · Sync Library may identify it again" + else: + message = f"Manual catalogue match saved and locked · {outcome.result.api_name}" + self._completion_message = (message, False) + self.refresh_snapshot(identify=False) + + def _select_track(self, index: int) -> None: + if not self.filtered_tracks: + return + self.selected_index = max(0, min(len(self.filtered_tracks) - 1, index)) + self._render_tracks() + self._render_details() + self._update_position() + self.call_after_refresh(self._scroll_selection_into_view) + + def _scroll_selection_into_view(self) -> None: + if not self.filtered_tracks: + return + scroll = self.query_one("#library-tracks-scroll", VerticalScroll) + scroll.scroll_to_region( + Region(0, self.selected_index, max(1, scroll.virtual_size.width), 1), + animate=False, + immediate=True, + x_axis=False, + ) + + def _set_status(self, message: str, *, error: bool = False) -> None: + status = self.query_one("#library-status", Static) + status.update(message) + status.set_class(error, "-error") + + def _maintenance_dialog_closed(self, plan: LibrarySyncPlan | None) -> None: + if plan is None: + self._set_status("Library maintenance cancelled. No files were changed.") + return + if self._execution_worker is not None: + return + self._maintenance_completed = 0 + self._maintenance_total = plan.ready_files + self._set_status(f"Maintaining library… 0 / {plan.ready_files} songs") + self._execution_worker = self._execute_maintenance(plan) + + def _preview_identity_rebuild(self) -> None: + if self._identity_rebuild_plan_worker is not None or self._identity_rebuild_worker is not None: + return + self._set_status("Preparing catalogue rebuild preview…") + self._identity_rebuild_plan_worker = self._load_identity_rebuild_plan() + + @work(thread=True, exclusive=True, group="library-identity-rebuild-plan", exit_on_error=False) + def _load_identity_rebuild_plan(self) -> IdentityRebuildPlanOutcome: + try: + return IdentityRebuildPlanOutcome(self._identity_rebuild_plan_provider(self.settings)) + except Exception as exc: + return IdentityRebuildPlanOutcome(error=str(exc) or type(exc).__name__) + + def _apply_identity_rebuild_plan(self, outcome: IdentityRebuildPlanOutcome) -> None: + self._identity_rebuild_plan_worker = None + if outcome.error or outcome.plan is None: + self._set_status( + f"Catalogue rebuild preview unavailable: {outcome.error or 'Unknown error'}", + error=True, + ) + return + self.app.push_screen(IdentityRebuildDialog(outcome.plan), self._identity_rebuild_confirmed) + + def _identity_rebuild_confirmed(self, plan: IdentityRebuildPlan | None) -> None: + if plan is None: + self._set_status("Catalogue rebuild cancelled. No state was changed.") + return + if self._identity_rebuild_worker is not None: + return + self._identity_rebuild_completed = 0 + self._set_status(f"Rebuilding catalogue matches… 0 / {plan.current_tracks}") + self._identity_rebuild_worker = self._execute_identity_rebuild(plan) + + @work(thread=True, exclusive=True, group="library-identity-rebuild", exit_on_error=False) + def _execute_identity_rebuild(self, plan: IdentityRebuildPlan) -> IdentityRebuildOutcome: + try: + return IdentityRebuildOutcome( + self._identity_rebuild_execution_provider( + plan, + progress=self._identity_rebuild_progress, + ) + ) + except Exception as exc: + return IdentityRebuildOutcome(error=str(exc) or type(exc).__name__) + + def _identity_rebuild_progress(self, event: IdentityRebuildProgress) -> None: + self._identity_rebuild_completed = event.completed + try: + self.app.call_from_thread( + self._set_status, + f"Rebuilding catalogue matches… {event.completed} / {event.total} · {event.path.stem}", + ) + except RuntimeError: + pass + + def _apply_identity_rebuild(self, outcome: IdentityRebuildOutcome) -> None: + self._identity_rebuild_worker = None + if outcome.error or outcome.result is None: + self._set_status( + f"Catalogue rebuild failed safely: {outcome.error or 'Unknown error'}", + error=True, + ) + return + result = outcome.result + if result.aborted: + self._set_status( + f"Catalogue rebuild aborted safely · {result.abort_reason}", + error=True, + ) + return + message = ( + f"Catalogue rebuild complete · {result.matched} matched · " + f"{result.unknown} unknown · {result.changed_identities} changed" + ) + if result.failed_preserved: + message += f" · {result.failed_preserved} preserved after errors" + self._completion_message = (message, bool(result.failed_preserved)) + self.snapshot = None + self._snapshot_action = "scan" + self.refresh_snapshot(identify=False) + + @work(thread=True, exclusive=True, group="library-maintenance", exit_on_error=False) + def _execute_maintenance(self, plan: LibrarySyncPlan) -> ExecutionOutcome: + try: + return ExecutionOutcome(self._execution_provider(plan, progress=self._maintenance_progress)) + except Exception as exc: + return ExecutionOutcome(error=str(exc) or type(exc).__name__) + + def _maintenance_progress(self, event: SyncEvent) -> None: + if event.kind not in {SyncEventKind.TRACK_COMPLETED, SyncEventKind.TRACK_FAILED}: + return + self._maintenance_completed += 1 + title = event.path.stem if event.path is not None else "" + try: + self.app.call_from_thread( + self._set_status, + f"Maintaining library… {self._maintenance_completed} / {self._maintenance_total} songs · {title}", + ) + except RuntimeError: + pass + + def _apply_execution(self, outcome: ExecutionOutcome) -> None: + self._execution_worker = None + if outcome.error or outcome.result is None: + self._set_status(f"Library maintenance failed safely: {outcome.error or 'Unknown error'}", error=True) + return + result = outcome.result + remaining = result.failed_files + result.plan.unresolved_files + result.plan.no_lyrics_files + updated_word = "song" if result.updated_files == 1 else "songs" + message = f"Library updated · {result.updated_files} {updated_word} updated" + if remaining: + message += f" · {remaining} could not be updated" + if result.warnings: + message += f" · {result.warnings[0]}" + self._completion_message = (message, bool(result.failed_files)) + self.snapshot = None + self.preview = None + self._snapshot_action = "scan" + self.refresh_snapshot(identify=False) + + def _open_backups(self) -> None: + if self._backup_worker is None: + self._set_status("Loading backups…") + self._backup_worker = self._load_backups() + + @work(thread=True, exclusive=True, group="library-backups", exit_on_error=False) + def _load_backups(self) -> BackupOutcome: + try: + return BackupOutcome(self._backup_provider()) + except Exception as exc: + return BackupOutcome(error=str(exc) or type(exc).__name__) + + def _apply_backups(self, outcome: BackupOutcome) -> None: + self._backup_worker = None + if outcome.error: + self._set_status(f"Backups unavailable: {outcome.error}", error=True) + return + self.app.push_screen(BackupBrowser(outcome.records), self._backup_selected) + + def _backup_selected(self, record: BackupRecord | None) -> None: + self._backup_worker = None + if record is not None: + self.app.push_screen(RestoreDialog(record), self._restore_confirmed) + + def _restore_confirmed(self, record: BackupRecord | None) -> None: + if record is None: + self._set_status("Restore cancelled. No files were changed.") + return + self._set_status("Restoring backup…") + self._restore_worker = self._restore(record) + + @work(thread=True, exclusive=True, group="library-restore", exit_on_error=False) + def _restore(self, record: BackupRecord) -> tuple[int | None, str | None]: + try: + return self._restore_provider(record.path, Path(self.settings.music_dir)), None + except Exception as exc: + return None, str(exc) or type(exc).__name__ + + def _apply_restore(self, count: int | None, error: str | None) -> None: + self._restore_worker = None + if error is not None or count is None: + self._set_status(f"Restore failed safely: {error or 'Unknown error'}", error=True) + return + self._completion_message = ( + f"Restored {count} audio file{'s' if count != 1 else ''}.", + False, + ) + self.snapshot = None + self._snapshot_action = "scan" + self.refresh_snapshot(identify=False) + + def _check_rmpc(self) -> None: + if self._rmpc_worker is None: + self._set_status("Checking rmpc integration…") + self._rmpc_worker = self._load_rmpc() + + @work(thread=True, exclusive=True, group="library-rmpc", exit_on_error=False) + def _load_rmpc(self) -> tuple[SettingsSnapshot | None, str | None]: + try: return self._rmpc_status_provider(self.settings), None + except Exception as exc: return None, str(exc) or type(exc).__name__ + + def _rmpc_dialog_closed(self, snapshot: SettingsSnapshot | None) -> None: + self._rmpc_worker = None + if snapshot is None: + self._set_status("rmpc check complete. No configuration was changed.") + return + self._set_status("Setting up rmpc…") + self._rmpc_setup_worker = self._setup_rmpc(snapshot) + + @work(thread=True, exclusive=True, group="library-rmpc-setup", exit_on_error=False) + def _setup_rmpc(self, snapshot: SettingsSnapshot) -> tuple[Path | None, str | None]: + try: return self._rmpc_setup_provider(snapshot.rmpc.config_path, Path(self.settings.music_dir)), None + except Exception as exc: return None, str(exc) or type(exc).__name__ + + def on_resize(self, event: Resize) -> None: + super().on_resize(event) + self.set_class(event.size.width < 110, "-library-narrow") + self.set_class(event.size.height <= 30, "-library-compact") + if self.filtered_tracks: + self.call_after_refresh(self._scroll_selection_into_view) + + +def _matches_filter(track: LibraryTrack, selected: LibraryFilter) -> bool: + return { + LibraryFilter.ALL: True, + LibraryFilter.MATCHED: track.match_status is LibraryMatchStatus.MATCHED, + LibraryFilter.UNMATCHED: track.match_status is LibraryMatchStatus.UNMATCHED, + LibraryFilter.SYNCED: track.lyric_status is LibraryLyricStatus.SYNCED, + LibraryFilter.PLAIN: track.lyric_status is LibraryLyricStatus.PLAIN, + LibraryFilter.NO_LYRICS: track.lyric_status is LibraryLyricStatus.NONE, + LibraryFilter.ATTENTION: track.needs_attention, + }[selected] + + +def _match_label(track: LibraryTrack) -> str: + return "Matched" if track.match_status is LibraryMatchStatus.MATCHED else "Unknown" + + +def _lyric_label(status: LibraryLyricStatus) -> str: + return { + LibraryLyricStatus.SYNCED: "Synced lyrics", + LibraryLyricStatus.PLAIN: "Plain lyrics", + LibraryLyricStatus.NONE: "No lyrics", + }[status] + + +def _lrc_label(status: LibraryLrcStatus) -> str: + return { + LibraryLrcStatus.PRESENT: "Present", + LibraryLrcStatus.MISSING: "Missing", + LibraryLrcStatus.INVALID: "Invalid", + LibraryLrcStatus.NONE: "None", + }[status] + + +def _state_label(status: LibraryStateStatus) -> str: + return { + LibraryStateStatus.CURRENT: "Current", + LibraryStateStatus.NEW: "New", + LibraryStateStatus.CHANGED: "Changed", + LibraryStateStatus.INVALID: "Invalid", + }[status] + + +def _coverage_label(track: LibraryTrack) -> str: + if track.fully_covered: + return "Fully covered" + if track.lyric_status is LibraryLyricStatus.NONE: + return "No managed lyrics" + if track.lrc_status in {LibraryLrcStatus.MISSING, LibraryLrcStatus.INVALID}: + return "Synced LRC needs attention" + if track.lyric_status is LibraryLyricStatus.PLAIN: + return "Plain lyrics only" + return "Needs attention" if track.needs_attention else "Lyrics present" + + +def _duration(seconds: float | None) -> str: + if seconds is None: + return "Unavailable" + minutes, remainder = divmod(max(0, int(round(seconds))), 60) + return f"{minutes}:{remainder:02d}" + + +def _track_preview_text(plan: LibrarySyncPlan | None, path: Path) -> str: + if plan is None: + return " Not generated. Press l for this song or m for the library." + track = next((item for item in plan.tracks if item.path == path), None) + if track is None: + return " Track was not present in the latest preview." + outcome = { + MatchOutcome.UNCHANGED: "Already current", + MatchOutcome.MATCHED: "Would update lyrics", + MatchOutcome.UNRESOLVED: "Would remain unmatched", + MatchOutcome.NO_LYRICS: "Matched, but no lyrics are available", + MatchOutcome.FAILED: "Preview failed", + }[track.outcome] + lyric = { + SyncLyricType.SYNCED: "Synced lyrics", + SyncLyricType.PLAIN: "Plain lyrics", + SyncLyricType.NONE: "No lyric change", + }[track.lyric_type] + candidate = str((track.candidate or {}).get("name") or "").strip() + text = f" {outcome} · {lyric}" + if candidate: + text += f" · {candidate}" + if track.lrc_path is not None: + text += f" · LRC {track.lrc_path}" + if track.error: + text += f" · {track.error}" + return text diff --git a/src/juice_lyrics/tui/screens/placeholder.py b/src/juice_lyrics/tui/screens/placeholder.py new file mode 100644 index 0000000..45bc1fb --- /dev/null +++ b/src/juice_lyrics/tui/screens/placeholder.py @@ -0,0 +1,22 @@ +from __future__ import annotations + +from collections.abc import Iterable + +from textual.containers import Container +from textual.widget import Widget +from textual.widgets import Static + +from .base import HubScreen + + +class PlaceholderScreen(HubScreen): + """Navigable, explicit placeholder for a planned product section.""" + + def __init__(self, title: str, message: str) -> None: + super().__init__(title.lower(), title) + self.message = message + + def compose_content(self) -> Iterable[Widget]: + with Container(id="placeholder-panel"): + yield Static(self.message, id="placeholder-message", markup=False) + yield Static("This early TUI shell is read-only.", markup=False) diff --git a/src/juice_lyrics/tui/screens/settings.py b/src/juice_lyrics/tui/screens/settings.py new file mode 100644 index 0000000..63fc889 --- /dev/null +++ b/src/juice_lyrics/tui/screens/settings.py @@ -0,0 +1,364 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass +from typing import Any + +from rich.text import Text +from textual import work +from textual.containers import Container, Grid, VerticalScroll +from textual.events import Key, Resize, ScreenResume +from textual.widget import Widget +from textual.widgets import Static +from textual.worker import Worker, WorkerState + +from ...services.settings_snapshot import ( + IntegrationStatus, + SettingValue, + SettingsPath, + SettingsSnapshot, + SettingsSource, +) +from .base import HubScreen + +SnapshotProvider = Callable[[Any], SettingsSnapshot] + + +@dataclass(frozen=True, slots=True) +class SettingsOutcome: + snapshot: SettingsSnapshot | None = None + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class SettingsRow: + section: str + label: str + value: str + detail: str + + +class SettingsScreen(HubScreen): + """Read-only effective configuration and environment inspector.""" + + def __init__(self, settings: Any, *, snapshot_provider: SnapshotProvider) -> None: + super().__init__("settings", "Settings") + self.settings = settings + self._snapshot_provider = snapshot_provider + self.snapshot: SettingsSnapshot | None = None + self.rows: tuple[SettingsRow, ...] = () + self.selected_index = 0 + self._refresh_worker: Worker[SettingsOutcome] | None = None + self._pending_outcome: SettingsOutcome | None = None + + def compose_content(self) -> Iterable[Widget]: + yield Static( + "Read-only settings — configuration changes use the 999 CLI", + id="settings-warning", + markup=False, + ) + yield Static("Loading configuration and environment…", id="settings-status", markup=False) + with VerticalScroll(id="settings-scroll"): + with Grid(id="settings-main"): + with Container(classes="settings-panel", id="settings-paths-panel"): + yield Static("Folders", classes="panel-title") + yield Static("Loading…", id="settings-paths", markup=False) + with Container(classes="settings-panel", id="settings-integrations-panel"): + yield Static("rmpc", classes="panel-title") + yield Static("Loading…", id="settings-integrations", markup=False) + with Container(classes="settings-panel", id="settings-configuration-panel"): + yield Static("Advanced", classes="panel-title") + yield Static("Loading…", id="settings-configuration", markup=False) + with Container(classes="settings-panel", id="settings-capabilities-panel"): + yield Static("Capabilities and limitations", classes="panel-title") + yield Static("Loading…", id="settings-capabilities", markup=False) + yield Static("Selected setting details will appear here.", id="settings-detail", markup=False) + yield Static("↑↓ Inspect · PgUp/PgDn Scroll · r Refresh · ? Help", id="settings-position", markup=False) + + def on_screen_resume(self, event: ScreenResume) -> None: + if self._pending_outcome is not None: + outcome, self._pending_outcome = self._pending_outcome, None + self._apply_snapshot(outcome) + elif self.snapshot is None and self._refresh_worker is None: + self.refresh_snapshot() + + def refresh_snapshot(self) -> None: + if self.snapshot is None: + for selector in ( + "#settings-configuration", + "#settings-paths", + "#settings-integrations", + "#settings-capabilities", + ): + self.query_one(selector, Static).update("Loading…") + self._set_status("Refreshing configuration and environment…") + self._refresh_worker = self._load_snapshot() + + @work(thread=True, exclusive=True, group="settings-snapshot", exit_on_error=False) + def _load_snapshot(self) -> SettingsOutcome: + try: + return SettingsOutcome(self._snapshot_provider(self.settings)) + except Exception as exc: + return SettingsOutcome(error=str(exc) or type(exc).__name__) + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if event.worker is not self._refresh_worker: + return + if event.state is WorkerState.SUCCESS: + outcome = event.worker.result + elif event.state is WorkerState.ERROR: + outcome = SettingsOutcome(error="Settings could not be loaded") + else: + return + if self._can_render(): + self._apply_snapshot(outcome) + else: + self._pending_outcome = outcome + + def _can_render(self) -> bool: + if not self.is_mounted or not list(self.query("#settings-warning")): + return False + try: + return self.app.screen is self + except Exception: + return False + + def _apply_snapshot(self, outcome: SettingsOutcome) -> None: + if outcome.error or outcome.snapshot is None: + self._set_status( + f"Settings unavailable: {outcome.error or 'Unknown settings error'}", + error=True, + ) + if self.snapshot is None: + self.rows = () + self.query_one("#settings-configuration", Static).update( + "Unable to inspect configuration." + ) + self.query_one("#settings-paths", Static).update("Path details are unavailable.") + self.query_one("#settings-integrations", Static).update( + "Integration details are unavailable." + ) + self.query_one("#settings-capabilities", Static).update( + "Capabilities could not be loaded." + ) + self.query_one("#settings-detail", Static).update( + "Correct the configuration error and press r to retry." + ) + return + + previous = self.rows[self.selected_index].detail if self.rows else None + self.snapshot = outcome.snapshot + self.rows = _rows_for(outcome.snapshot) + self.selected_index = next( + (index for index, row in enumerate(self.rows) if row.detail == previous), + 0, + ) + self._render_rows() + if outcome.snapshot.warnings: + self._set_status(" ".join(outcome.snapshot.warnings), error=True) + elif outcome.snapshot.config_exists: + self._set_status("Effective configuration loaded from the active config file.") + else: + self._set_status("No config file · defaults and runtime overrides are shown.") + self.query_one("#settings-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) + + def _render_rows(self) -> None: + grouped: dict[str, list[tuple[int, SettingsRow]]] = { + "configuration": [], + "paths": [], + "integrations": [], + "capabilities": [], + } + for index, row in enumerate(self.rows): + grouped[row.section].append((index, row)) + for section, selector in ( + ("configuration", "#settings-configuration"), + ("paths", "#settings-paths"), + ("integrations", "#settings-integrations"), + ("capabilities", "#settings-capabilities"), + ): + lines = [ + f"{'> ' if index == self.selected_index else ' '}{row.label:<21} {_compact(row.value, 52)}" + for index, row in grouped[section] + ] + self.query_one(selector, Static).update( + Text("\n".join(lines) or "No information available.", no_wrap=True, overflow="ellipsis") + ) + if self.rows: + row = self.rows[self.selected_index] + self.query_one("#settings-detail", Static).update( + f"{row.label}\n{row.detail}" + ) + self.query_one("#settings-position", Static).update( + f"Setting {self.selected_index + 1} of {len(self.rows)} · ↑↓ Inspect · r Refresh · ? Help" + ) + + def on_key(self, event: Key) -> None: + if event.key in ("down", "j"): + self._select(self.selected_index + 1) + elif event.key in ("up", "k"): + self._select(self.selected_index - 1) + elif event.key == "home": + self._select(0) + elif event.key == "end": + self._select(len(self.rows) - 1) + elif event.key in ("pagedown", "pageup"): + scroll = self.query_one("#settings-scroll", VerticalScroll) + step = max(1, scroll.size.height // 2) + self._select(self.selected_index + (step if event.key == "pagedown" else -step)) + if event.key == "pagedown": + scroll.scroll_page_down(animate=False) + else: + scroll.scroll_page_up(animate=False) + elif event.key in ("enter", "escape"): + return + else: + return + event.prevent_default() + event.stop() + + def _select(self, index: int) -> None: + if not self.rows: + return + self.selected_index = max(0, min(len(self.rows) - 1, index)) + self._render_rows() + section = self.rows[self.selected_index].section + self.call_after_refresh( + self.query_one("#settings-scroll", VerticalScroll).scroll_to_widget, + self.query_one(f"#settings-{section}-panel"), + animate=False, + ) + + def _set_status(self, message: str, *, error: bool = False) -> None: + status = self.query_one("#settings-status", Static) + status.update(message) + status.set_class(error, "-error") + + def on_resize(self, event: Resize) -> None: + super().on_resize(event) + self.set_class(event.size.width < 100, "-settings-narrow") + self.set_class(event.size.height <= 30, "-settings-compact") + + +def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: + paths = {item.key: item for item in snapshot.paths} + essential_rows: list[SettingsRow] = [] + if "music" in paths: + essential_rows.append(_path_row(paths["music"], section="paths", label="Music folder")) + if "music" in paths: + essential_rows.append(_path_row(paths["music"], section="paths", label="Download location")) + external_lyrics = next( + (item for item in snapshot.values if item.key == "external_lyrics"), + None, + ) + if external_lyrics is not None: + essential_rows.append( + SettingsRow( + "paths", + "External lyrics", + str(external_lyrics.value), + "Synchronized external lyrics use a same-basename .lrc beside each song.", + ) + ) + + advanced_rows = [ + SettingsRow( + "configuration", + "Active config", + str(snapshot.config_path), + f"{snapshot.config_path} · {'Exists' if snapshot.config_exists else 'Missing; defaults are in use'}", + ), + SettingsRow( + "configuration", + "Application version", + snapshot.application_version, + snapshot.application_version, + ), + ] + advanced_rows.extend( + _value_row(item) + for item in snapshot.values + if item.key not in {"music_dir", "external_lyrics"} + ) + advanced_rows.extend( + _path_row(item, section="configuration") + for item in snapshot.paths + if item.key != "music" + ) + integration_rows = [ + SettingsRow( + "integrations", + "rmpc status", + _integration_label(snapshot.rmpc.status), + snapshot.rmpc.detail, + ), + SettingsRow( + "configuration", + "rmpc executable", + str(snapshot.rmpc.executable or "Not detected"), + str(snapshot.rmpc.executable or "rmpc was not found in PATH."), + ), + SettingsRow( + "configuration", + "rmpc configuration", + "Configured" if snapshot.rmpc.config_has_lyrics_support else "Not configured", + f"{snapshot.rmpc.config_path} · {'Exists' if snapshot.rmpc.config_exists else 'Missing'}", + ), + ] + capability_rows = [ + SettingsRow("capabilities", f"Limitation {index}", value, value) + for index, value in enumerate(snapshot.limitations, start=1) + ] + primary_integration = integration_rows[:1] + advanced_rows.extend(integration_rows[1:]) + return tuple((*essential_rows, *primary_integration, *advanced_rows, *capability_rows)) + + +def _value_row(item: SettingValue) -> SettingsRow: + source = { + SettingsSource.DEFAULT: "Default", + SettingsSource.CONFIG: "Config file", + SettingsSource.RUNTIME_OVERRIDE: "Runtime override", + }[item.source] + value = str(item.value) + units = { + "timeout": " seconds", + "delay": " seconds", + "duration_tolerance": " seconds", + "cache_ttl_hours": " hours", + }.get(item.key, "") + return SettingsRow( + "configuration", + item.label, + f"{value}{units} [{source}]", + f"Effective: {value}{units} · Source: {source} · Default: {item.default_value}{units}", + ) + + +def _path_row( + item: SettingsPath, + *, + section: str = "paths", + label: str | None = None, +) -> SettingsRow: + state = "Exists" if item.exists else "Missing" + warning = f" · Inspection warning: {item.warning}" if item.warning else "" + return SettingsRow( + section, + label or item.label, + f"{item.path} [{state}]", + f"{item.path} · {state}{warning}", + ) + + +def _integration_label(status: IntegrationStatus) -> str: + return { + IntegrationStatus.DETECTED_CONFIGURED: "Detected and configured", + IntegrationStatus.DETECTED_NOT_CONFIGURED: "Detected but not configured", + IntegrationStatus.NOT_DETECTED: "Not detected", + IntegrationStatus.UNABLE_TO_INSPECT: "Unable to inspect", + }[status] + + +def _compact(value: str, limit: int) -> str: + return value if len(value) <= limit else "…" + value[-(limit - 1):] diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..c943563 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,28 @@ +"""Keep every automated test away from the user's real application data.""" + +from __future__ import annotations + +import os +from pathlib import Path +import shutil +import tempfile + + +_REAL_HOME = Path.home() +_TEST_HOME = Path(tempfile.mkdtemp(prefix="juice-lyrics-tests-")) + +# This runs while pytest loads conftest, before test modules import the package +# and freeze Path.home()/XDG-derived constants. +os.environ["HOME"] = str(_TEST_HOME) +os.environ["XDG_CONFIG_HOME"] = str(_TEST_HOME / ".config") +os.environ["XDG_CACHE_HOME"] = str(_TEST_HOME / ".cache") +os.environ["XDG_DATA_HOME"] = str(_TEST_HOME / ".local" / "share") + + +def pytest_sessionstart(session) -> None: + if Path.home() == _REAL_HOME or Path.home() != _TEST_HOME: + raise RuntimeError("Tests refused to run with the real HOME") + + +def pytest_sessionfinish(session, exitstatus) -> None: + shutil.rmtree(_TEST_HOME, ignore_errors=True) diff --git a/tests/fixtures/catalogue/categories.json b/tests/fixtures/catalogue/categories.json new file mode 100644 index 0000000..7f5b890 --- /dev/null +++ b/tests/fixtures/catalogue/categories.json @@ -0,0 +1,8 @@ +{ + "categories": [ + {"value": "released", "label": "Released"}, + {"value": "unreleased", "label": "Unreleased"}, + {"value": "unsurfaced", "label": "Unsurfaced"}, + {"value": "recording_session", "label": "Recording Session"} + ] +} diff --git a/tests/fixtures/catalogue/eras_page_1.json b/tests/fixtures/catalogue/eras_page_1.json new file mode 100644 index 0000000..d612a15 --- /dev/null +++ b/tests/fixtures/catalogue/eras_page_1.json @@ -0,0 +1,19 @@ +{ + "count": 34, + "next": "http://juicewrldapi.com/juicewrld/eras/?page=2&page_size=100", + "previous": null, + "results": [ + { + "id": 109, + "name": "WOD", + "description": "WRLD On Drugs era", + "time_frame": "(August 2018-December 2018)" + }, + { + "id": 110, + "name": "DRFL", + "description": "Death Race For Love era", + "time_frame": "(May 2018-March 2019)" + } + ] +} diff --git a/tests/fixtures/catalogue/eras_page_2.json b/tests/fixtures/catalogue/eras_page_2.json new file mode 100644 index 0000000..c53e529 --- /dev/null +++ b/tests/fixtures/catalogue/eras_page_2.json @@ -0,0 +1,13 @@ +{ + "count": 34, + "next": null, + "previous": "http://juicewrldapi.com/juicewrld/eras/?page_size=100", + "results": [ + { + "id": 130, + "name": "DRFL (TV)", + "description": "DRFL television performances", + "time_frame": "" + } + ] +} diff --git a/tests/fixtures/catalogue/songs_unreleased_drfl_page_2.json b/tests/fixtures/catalogue/songs_unreleased_drfl_page_2.json new file mode 100644 index 0000000..2078ab9 --- /dev/null +++ b/tests/fixtures/catalogue/songs_unreleased_drfl_page_2.json @@ -0,0 +1,24 @@ +{ + "count": 235, + "next": "http://juicewrldapi.com/juicewrld/songs/?category=unreleased&era=DRFL&page=3&page_size=50&search=", + "previous": "http://juicewrldapi.com/juicewrld/songs/?category=unreleased&era=DRFL&page_size=50&search=", + "results": [ + { + "id": 95214, + "name": "Rental (v1)", + "category": "unreleased", + "era": {"id": 110, "name": "DRFL"}, + "length": "4:13", + "path": "Tracks/Rental (v1).mp3", + "synced_lyrics": "[00:01.00] line" + }, + { + "id": 95061, + "name": "10 Feet (v1)", + "category": "unreleased", + "era": {"id": 110, "name": "DRFL"}, + "length": "3:38", + "path": "Tracks/10 Feet (v1).mp3" + } + ] +} diff --git a/tests/test_acquisition.py b/tests/test_acquisition.py index f975227..22711e2 100644 --- a/tests/test_acquisition.py +++ b/tests/test_acquisition.py @@ -400,6 +400,36 @@ def fake_download(item, policy, *, progress=None): assert job.items[1].state is AcquisitionState.COMPLETE +def test_run_job_can_execute_only_one_selected_item(tmp_path, monkeypatch): + store = JobStore(tmp_path / "jobs.json") + items = [_job_item(tmp_path, "first.mp3"), _job_item(tmp_path, "selected.mp3")] + items[0].identifier = "1" + items[1].identifier = "2" + job = store.create(items) + calls = [] + + monkeypatch.setattr("juice_lyrics.acquisition.runner.find_duplicate", lambda item: None) + + def fake_download(item, policy, *, progress=None): + calls.append(item.identifier) + return AcquisitionResult( + item=item, + state=AcquisitionState.COMPLETE, + destination=item.destination, + bytes_written=10, + ) + + monkeypatch.setattr("juice_lyrics.acquisition.runner.download_to", fake_download) + + summary = run_job(job, store, item_indexes={1}) + + assert calls == ["2"] + assert job.items[0].state is AcquisitionState.PENDING + assert job.items[1].state is AcquisitionState.COMPLETE + assert summary.completed == 1 + assert summary.pending == 1 + + def test_cli_acquire_parser_exposes_user_workflow(): from juice_lyrics.cli import build_parser @@ -466,6 +496,41 @@ def test_cli_acquire_search_with_api_path_shows_downloadable(tmp_path, monkeypat assert "NO DOWNLOAD URL" not in output +def test_cli_acquire_search_forwards_filters_and_refresh_without_changing_page( + tmp_path, monkeypatch, capsys +): + import juice_lyrics.cli as cli + + calls = [] + + def search( + settings, + query, + *, + category=None, + era=None, + page=1, + page_size=50, + refresh=False, + ): + calls.append((query, category, era, page, page_size, refresh)) + return {"results": []} + + monkeypatch.setattr(cli, "search_api_advanced", search) + args = cli.build_parser().parse_args([ + "--path", str(tmp_path), + "acquire", "search", "Bandit", + "--category", "released", + "--era", "Mainstream", + "--refresh", + ]) + settings = cli.load_settings(str(tmp_path), None) + + assert cli.command_acquire(args, settings, False) == 1 + assert calls == [("Bandit", "released", "Mainstream", 1, 50, True)] + assert "No API results found." in capsys.readouterr().out + + def test_cli_acquire_add_with_live_api_path_creates_job(tmp_path, monkeypatch, capsys): import juice_lyrics.cli as cli @@ -545,7 +610,7 @@ def test_integrate_downloaded_mp3_embeds_synced_lyrics_and_lrc(tmp_path): ) assert result.lyric_type == "SYLT" - assert result.lrc_path == tmp_path / "lyrics" / "Rental.lrc" + assert result.lrc_path == mp3.with_suffix(".lrc") assert result.lrc_path.is_file() @@ -1073,7 +1138,7 @@ def test_integrate_acquired_mp3_updates_state_json(tmp_path, monkeypatch): mp3.write_bytes(b"dummy mp3 payload") item = AcquisitionItem(identifier="101", title="Rental", url="https://example.invalid/rental.mp3", destination=mp3) - settings = Settings(music_dir=tmp_path) + settings = Settings(music_dir=tmp_path, lyrics_dir=tmp_path / "lyrics") result = integrate_downloaded_mp3( item, song_fetcher=lambda song_id: { @@ -1097,7 +1162,7 @@ def test_integrate_acquired_mp3_updates_state_json(tmp_path, monkeypatch): assert entry["api_name"] == "Rental" assert entry["lyric_type"] == "SYLT" assert entry["sha256"] == state_mod.sha256_file(mp3) - assert entry["lrc"] == str(tmp_path / "lyrics" / "Rental.lrc") + assert entry["lrc"] == str(mp3.with_suffix(".lrc")) def test_later_sync_recognizes_acquired_file_as_already_processed(tmp_path, monkeypatch): @@ -1113,7 +1178,7 @@ def test_later_sync_recognizes_acquired_file_as_already_processed(tmp_path, monk mp3.write_bytes(b"dummy mp3 payload") item = AcquisitionItem(identifier="101", title="Rental", url="https://example.invalid/rental.mp3", destination=mp3) - settings = Settings(music_dir=tmp_path) + settings = Settings(music_dir=tmp_path, lyrics_dir=tmp_path / "lyrics") integrate_downloaded_mp3( item, song_fetcher=lambda song_id: { @@ -1167,7 +1232,7 @@ def mock_notify(paths): assert result.rmpc_notified == 1 assert len(notified) == 1 - assert notified[0] == [tmp_path / "lyrics" / "Rental.lrc"] + assert notified[0] == [mp3.with_suffix(".lrc")] assert "rmpc notified: 1" in result.message @@ -1238,8 +1303,3 @@ def failing_postprocess(result): assert loaded is not None assert loaded.items[0].state is AcquisitionState.FAILED assert "Failed to synchronize library state" in (loaded.items[0].error or "") - - - - - diff --git a/tests/test_acquisition_integration_safety.py b/tests/test_acquisition_integration_safety.py new file mode 100644 index 0000000..960cff8 --- /dev/null +++ b/tests/test_acquisition_integration_safety.py @@ -0,0 +1,334 @@ +from pathlib import Path +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +import pytest + +from juice_lyrics.acquisition import runner +from juice_lyrics.acquisition.integration import integrate_downloaded_mp3 +from juice_lyrics.acquisition.jobs import JobStore +from juice_lyrics.acquisition.models import AcquisitionItem, AcquisitionResult, AcquisitionState +from juice_lyrics.config.settings import Settings + + +def _item(path: Path) -> AcquisitionItem: + return AcquisitionItem( + identifier="101", + title="Rental", + url="https://example.invalid/Rental.mp3", + destination=path, + ) + + +def _song(*, synced=True, plain=True): + return { + "id": 101, + "name": "Rental", + "synced_lyrics": "[00:01.00] line" if synced else "", + "lyrics": "plain line" if plain else "", + } + + +def _isolated_backup(monkeypatch, tmp_path): + import juice_lyrics.acquisition.integration as integration + + root = tmp_path / "backups" / "checkpoint" + + def make_root(): + root.mkdir(parents=True, exist_ok=True) + return root + + monkeypatch.setattr(integration, "make_backup_root", make_root) + return root + + +@pytest.mark.parametrize( + ("song", "expected_type"), + [(_song(synced=True, plain=True), "SYLT"), (_song(synced=False, plain=True), "USLT")], +) +def test_success_backs_up_pristine_file_then_retains_verified_modification( + tmp_path, monkeypatch, song, expected_type +): + import juice_lyrics.acquisition.integration as integration + + root = _isolated_backup(monkeypatch, tmp_path) + path = tmp_path / "music" / "Rental.mp3" + path.parent.mkdir() + pristine = b"pristine finalized audio" + path.write_bytes(pristine) + events = [] + + def embed(target, synced, plain): + backup = root / "Rental.mp3" + assert backup.read_bytes() == pristine + events.append("embed") + target.write_bytes(b"verified metadata audio") + return expected_type + + monkeypatch.setattr(integration, "embed_lyrics", embed) + monkeypatch.setattr(integration, "verify_file", lambda target: (True, "verified")) + + result = integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: song, + state={}, + notify_rmpc=False, + ) + + assert events == ["embed"] + assert result.lyric_type == expected_type + assert result.backup_path == root / "Rental.mp3" + assert result.backup_path.read_bytes() == pristine + assert path.read_bytes() == b"verified metadata audio" + assert (root / "manifest.json").is_file() + + +def test_acquisition_writes_adjacent_lrc_and_ignores_legacy_setting(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + _isolated_backup(monkeypatch, tmp_path) + music = tmp_path / "Music" / "Juice WRLD" / "Unreleased" + configured_lyrics = tmp_path / "Music" / "lyrics" + old_derived_lyrics = tmp_path / "Music" / "Juice WRLD" / "lyrics" + path = music / "Rental.mp3" + path.parent.mkdir(parents=True) + path.write_bytes(b"pristine") + + monkeypatch.setattr(integration, "embed_lyrics", lambda *args: "SYLT") + monkeypatch.setattr(integration, "verify_file", lambda target: (True, "verified")) + + def write_lrc(target, synced, song): + result = target.with_suffix(".lrc") + result.write_text("[00:01.00] line\n", encoding="utf-8") + return result + + monkeypatch.setattr(integration, "write_lrc", write_lrc) + + result = integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(synced=True, plain=True), + settings=Settings(music_dir=music, lyrics_dir=configured_lyrics), + state={}, + notify_rmpc=False, + ) + + assert result.lrc_path == path.with_suffix(".lrc") + assert result.lrc_path.is_file() + assert not configured_lyrics.exists() + assert not old_derived_lyrics.exists() + + +@pytest.mark.parametrize("failure_kind", ["verification_failure", "embed_exception", "verify_exception"]) +def test_lyric_processing_failure_restores_byte_identical_pristine_file( + tmp_path, monkeypatch, failure_kind +): + import juice_lyrics.acquisition.integration as integration + + _isolated_backup(monkeypatch, tmp_path) + path = tmp_path / "Rental.mp3" + pristine = b"pristine downloaded bytes" + path.write_bytes(pristine) + + def embed(target, synced, plain): + target.write_bytes(b"partially modified") + if failure_kind == "embed_exception": + raise RuntimeError("embed exploded") + return "USLT" + + def verify(target): + if failure_kind == "verify_exception": + raise RuntimeError("verify exploded") + return False, "bad frame" + + monkeypatch.setattr(integration, "embed_lyrics", embed) + monkeypatch.setattr(integration, "verify_file", verify) + + with pytest.raises(RuntimeError, match="restored from backup"): + integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(synced=False, plain=True), + state={}, + ) + + assert path.read_bytes() == pristine + + +def test_backup_failure_prevents_metadata_mutation(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + path = tmp_path / "Rental.mp3" + pristine = b"pristine" + path.write_bytes(pristine) + embedded = [] + monkeypatch.setattr(integration, "make_backup_root", lambda: (_ for _ in ()).throw(OSError("disk full"))) + monkeypatch.setattr(integration, "embed_lyrics", lambda *args: embedded.append(True)) + + with pytest.raises(RuntimeError, match="backup failed before metadata modification"): + integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(synced=False, plain=True), + state={}, + ) + + assert embedded == [] + assert path.read_bytes() == pristine + + +def test_restore_failure_is_clear_and_preserves_pristine_backup(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + root = _isolated_backup(monkeypatch, tmp_path) + path = tmp_path / "Rental.mp3" + pristine = b"pristine" + path.write_bytes(pristine) + + def embed(target, synced, plain): + target.write_bytes(b"partial") + raise RuntimeError("embed failed") + + monkeypatch.setattr(integration, "embed_lyrics", embed) + monkeypatch.setattr(integration, "restore_file", lambda *args: (_ for _ in ()).throw(OSError("restore denied"))) + + with pytest.raises(RuntimeError, match="Automatic restore also failed") as exc_info: + integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(synced=False, plain=True), + state={}, + ) + + assert "may be partially modified" in str(exc_info.value) + assert (root / "Rental.mp3").read_bytes() == pristine + assert path.read_bytes() == b"partial" + + +def test_no_lyrics_creates_no_backup_or_metadata_change(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + path = tmp_path / "Rental.mp3" + pristine = b"pristine" + path.write_bytes(pristine) + monkeypatch.setattr(integration, "make_backup_root", lambda: (_ for _ in ()).throw(AssertionError("backup called"))) + + result = integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(synced=False, plain=False), + state={}, + ) + + assert result.lyric_type == "NONE" + assert result.backup_path is None + assert path.read_bytes() == pristine + + +def test_lrc_failure_retains_verified_mp3_and_backup(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + root = _isolated_backup(monkeypatch, tmp_path) + path = tmp_path / "Rental.mp3" + pristine = b"pristine" + path.write_bytes(pristine) + def embed(target, *_): + target.write_bytes(b"verified") + return "SYLT" + + monkeypatch.setattr(integration, "embed_lyrics", embed) + monkeypatch.setattr(integration, "verify_file", lambda target: (True, "verified")) + monkeypatch.setattr(integration, "write_lrc", lambda *args: (_ for _ in ()).throw(OSError("LRC disk full"))) + + with pytest.raises(RuntimeError, match="LRC integration failed"): + integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(), + lyrics_dir=tmp_path / "lyrics", + state={}, + ) + + assert path.read_bytes() == b"verified" + assert (root / "Rental.mp3").read_bytes() == pristine + + +def test_rmpc_notification_failure_is_warning_and_keeps_success(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + _isolated_backup(monkeypatch, tmp_path) + path = tmp_path / "Rental.mp3" + path.write_bytes(b"pristine") + def embed(target, *_): + target.write_bytes(b"verified") + return "SYLT" + + monkeypatch.setattr(integration, "embed_lyrics", embed) + monkeypatch.setattr(integration, "verify_file", lambda target: (True, "verified")) + monkeypatch.setattr(integration, "write_lrc", lambda *args: tmp_path / "lyrics" / "Rental.lrc") + monkeypatch.setattr(integration, "notify_rmpc_index", lambda paths: (_ for _ in ()).throw(RuntimeError("rmpc unavailable"))) + + result = integrate_downloaded_mp3( + _item(path), + song_fetcher=lambda _: _song(), + lyrics_dir=tmp_path / "lyrics", + state={}, + ) + + assert result.lyric_type == "SYLT" + assert result.rmpc_notified == 0 + assert "rmpc notification failed" in result.message + assert path.read_bytes() == b"verified" + + +def test_state_failure_retains_verified_mp3_and_runner_marks_failed(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + _isolated_backup(monkeypatch, tmp_path) + path = tmp_path / "Rental.mp3" + item = _item(path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="state-failure") + + def download(download_item, policy=None, *, progress=None): + download_item.destination.write_bytes(b"pristine") + return AcquisitionResult(download_item, AcquisitionState.COMPLETE, download_item.destination, 8) + + monkeypatch.setattr(runner, "download_to", download) + def embed(target, *_): + target.write_bytes(b"verified") + return "USLT" + + monkeypatch.setattr(integration, "embed_lyrics", embed) + monkeypatch.setattr(integration, "verify_file", lambda target: (True, "verified")) + monkeypatch.setattr(integration, "save_state", lambda state: (_ for _ in ()).throw(OSError("state disk full"))) + + summary = runner.run_job( + job, + store, + postprocess=lambda result: integrate_downloaded_mp3( + result.item, + song_fetcher=lambda _: _song(synced=False, plain=True), + ), + ) + + loaded = store.get("state-failure") + assert summary.failed == 1 + assert loaded is not None + assert loaded.items[0].state is AcquisitionState.FAILED + assert "state update failed" in (loaded.items[0].error or "") + assert path.read_bytes() == b"verified" + + +def test_duplicate_skip_creates_no_backup(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + path = tmp_path / "Rental.mp3" + path.write_bytes(b"already present") + store = JobStore(tmp_path / "jobs.json") + job = store.create([_item(path)], job_id="duplicate") + monkeypatch.setattr(integration, "make_backup_root", lambda: (_ for _ in ()).throw(AssertionError("backup called"))) + + summary = runner.run_job( + job, + store, + postprocess=lambda result: integrate_downloaded_mp3(result.item, song_fetcher=lambda _: _song()), + ) + + assert summary.skipped == 1 + assert job.items[0].state is AcquisitionState.SKIPPED diff --git a/tests/test_acquisition_postprocess_retry.py b/tests/test_acquisition_postprocess_retry.py new file mode 100644 index 0000000..c62081b --- /dev/null +++ b/tests/test_acquisition_postprocess_retry.py @@ -0,0 +1,327 @@ +import json +from pathlib import Path +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.acquisition import runner +from juice_lyrics.acquisition.integration import integrate_downloaded_mp3 +from juice_lyrics.acquisition.integration import IntegrationResult +from juice_lyrics.acquisition.jobs import JobStore +from juice_lyrics.acquisition.models import ( + AcquisitionFailureStage, + AcquisitionItem, + AcquisitionPostProcessingError, + AcquisitionResult, + AcquisitionState, +) + + +def _item(tmp_path, *, destination=None): + return AcquisitionItem( + identifier="101", + title="Rental", + url="https://example.invalid/Rental.mp3", + destination=destination or tmp_path / "Rental.mp3", + ) + + +def _complete_download(calls, payload=b"finalized audio"): + def download(item, policy=None, *, progress=None): + calls.append(item.destination) + item.destination.parent.mkdir(parents=True, exist_ok=True) + item.destination.write_bytes(payload) + return AcquisitionResult( + item=item, + state=AcquisitionState.COMPLETE, + destination=item.destination, + bytes_written=len(payload), + ) + + return download + + +def test_postprocessing_failure_retries_exact_file_without_downloader(tmp_path, monkeypatch): + item = _item(tmp_path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="post-retry") + downloads = [] + monkeypatch.setattr(runner, "download_to", _complete_download(downloads)) + + first = runner.run_job( + job, + store, + postprocess=lambda result: (_ for _ in ()).throw( + AcquisitionPostProcessingError(AcquisitionFailureStage.STATE, "state failed") + ), + ) + assert first.failed == 1 + failed = store.get("post-retry") + assert failed is not None + assert failed.items[0].failure_stage is AcquisitionFailureStage.STATE + assert failed.items[0].retry_file_size == item.destination.stat().st_size + assert failed.items[0].retry_file_sha256 + + postprocess_calls = [] + retried = runner.run_job( + failed, + store, + postprocess=lambda result: postprocess_calls.append( + (result.item.destination, result.postprocessing_retry) + ), + ) + + assert downloads == [item.destination] + assert postprocess_calls == [(item.destination, True)] + assert retried.completed == 1 + loaded = store.get("post-retry") + assert loaded is not None + assert loaded.items[0].state is AcquisitionState.COMPLETE + assert loaded.items[0].failure_stage is None + assert loaded.items[0].retry_file_sha256 is None + + +def test_failed_postprocessing_retry_remains_failed_and_rolls_back(tmp_path, monkeypatch): + import juice_lyrics.acquisition.integration as integration + + backup_counter = 0 + + def backup_root(): + nonlocal backup_counter + backup_counter += 1 + root = tmp_path / "backups" / str(backup_counter) + root.mkdir(parents=True) + return root + + monkeypatch.setattr(integration, "make_backup_root", backup_root) + monkeypatch.setattr(integration, "verify_file", lambda path: (False, "bad lyrics")) + + def embed(path, synced, plain): + path.write_bytes(b"partial metadata") + return "USLT" + + monkeypatch.setattr(integration, "embed_lyrics", embed) + downloads = [] + monkeypatch.setattr(runner, "download_to", _complete_download(downloads, b"pristine finalized")) + item = _item(tmp_path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="rollback-retry") + + def postprocess(result): + return integrate_downloaded_mp3( + result.item, + song_fetcher=lambda _: {"id": 101, "name": "Rental", "lyrics": "plain"}, + state={}, + ) + + assert runner.run_job(job, store, postprocess=postprocess).failed == 1 + assert item.destination.read_bytes() == b"pristine finalized" + failed = store.get("rollback-retry") + assert failed is not None + assert runner.run_job(failed, store, postprocess=postprocess).failed == 1 + assert downloads == [item.destination] + assert item.destination.read_bytes() == b"pristine finalized" + loaded = store.get("rollback-retry") + assert loaded is not None + assert "Post-processing retry from existing finalized file failed" in (loaded.items[0].error or "") + + +def test_missing_retry_file_falls_back_to_download(tmp_path, monkeypatch): + item = _item(tmp_path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="missing-file") + downloads = [] + monkeypatch.setattr(runner, "download_to", _complete_download(downloads)) + runner.run_job( + job, + store, + postprocess=lambda result: (_ for _ in ()).throw( + AcquisitionPostProcessingError(AcquisitionFailureStage.LRC, "lrc failed") + ), + ) + item.destination.unlink() + failed = store.get("missing-file") + assert failed is not None + + result = runner.run_job(failed, store, postprocess=lambda result: None) + + assert len(downloads) == 2 + assert result.completed == 1 + + +def test_transport_failure_uses_downloader_again(tmp_path, monkeypatch): + item = _item(tmp_path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="transport-retry") + calls = [] + + def fail_download(download_item, policy=None, *, progress=None): + calls.append("failed") + return AcquisitionResult( + download_item, + AcquisitionState.FAILED, + error="timeout", + failure_stage=AcquisitionFailureStage.TRANSPORT, + ) + + monkeypatch.setattr(runner, "download_to", fail_download) + assert runner.run_job(job, store).failed == 1 + failed = store.get("transport-retry") + assert failed is not None + monkeypatch.setattr(runner, "download_to", _complete_download(calls)) + + assert runner.run_job(failed, store).completed == 1 + assert calls == ["failed", item.destination] + + +def test_unrelated_duplicate_is_still_skipped(tmp_path, monkeypatch): + unrelated = tmp_path / "elsewhere" / "Rental.mp3" + unrelated.parent.mkdir() + unrelated.write_bytes(b"unrelated existing audio") + item = _item(tmp_path, destination=tmp_path / "elsewhere" / "Wanted.mp3") + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="unrelated-duplicate") + monkeypatch.setattr( + runner, + "download_to", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("download called")), + ) + + summary = runner.run_job(job, store) + + assert summary.skipped == 1 + assert unrelated.read_bytes() == b"unrelated existing audio" + assert not item.destination.exists() + + +def test_changed_exact_destination_does_not_bypass_duplicate_check(tmp_path, monkeypatch): + item = _item(tmp_path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="changed-destination") + downloads = [] + monkeypatch.setattr(runner, "download_to", _complete_download(downloads)) + runner.run_job( + job, + store, + postprocess=lambda result: (_ for _ in ()).throw( + AcquisitionPostProcessingError(AcquisitionFailureStage.STATE, "state failed") + ), + ) + item.destination.write_bytes(b"replacement unrelated file") + failed = store.get("changed-destination") + assert failed is not None + postprocess_calls = [] + + summary = runner.run_job( + failed, + store, + postprocess=lambda result: postprocess_calls.append(result), + ) + + assert summary.skipped == 1 + assert postprocess_calls == [] + assert downloads == [item.destination] + assert item.destination.read_bytes() == b"replacement unrelated file" + + +def test_failure_metadata_round_trip_and_old_record_compatibility(tmp_path): + item = _item(tmp_path) + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="new-record") + entry = job.items[0] + entry.state = AcquisitionState.FAILED + entry.failure_stage = AcquisitionFailureStage.LRC + entry.retry_file_size = 42 + entry.retry_file_sha256 = "a" * 64 + store.save(job) + + loaded = store.get("new-record") + assert loaded is not None + assert loaded.items[0].failure_stage is AcquisitionFailureStage.LRC + assert loaded.items[0].retry_file_size == 42 + assert loaded.items[0].retry_file_sha256 == "a" * 64 + + raw = json.loads(store.path.read_text(encoding="utf-8")) + old_item = raw["jobs"]["new-record"]["items"][0] + old_item.pop("failure_stage") + old_item.pop("retry_file_size") + old_item.pop("retry_file_sha256") + store.path.write_text(json.dumps(raw), encoding="utf-8") + + old = store.get("new-record") + assert old is not None + assert old.items[0].failure_stage is None + assert old.items[0].retry_file_size is None + assert old.items[0].retry_file_sha256 is None + + +def test_completed_skipped_and_no_lyrics_items_remain_compatible(tmp_path, monkeypatch): + completed_item = _item(tmp_path, destination=tmp_path / "complete.mp3") + skipped_item = _item(tmp_path, destination=tmp_path / "skip.mp3") + store = JobStore(tmp_path / "jobs.json") + job = store.create([completed_item, skipped_item], job_id="terminals") + job.items[0].state = AcquisitionState.COMPLETE + job.items[1].state = AcquisitionState.SKIPPED + store.save(job) + monkeypatch.setattr( + runner, + "download_to", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("download called")), + ) + assert runner.run_job(job, store).completed == 1 + assert runner.run_job(job, store).skipped == 1 + + no_lyrics = _item(tmp_path, destination=tmp_path / "none.mp3") + no_lyrics_job = store.create([no_lyrics], job_id="no-lyrics") + downloads = [] + monkeypatch.setattr(runner, "download_to", _complete_download(downloads)) + summary = runner.run_job( + no_lyrics_job, + store, + postprocess=lambda result: integrate_downloaded_mp3( + result.item, + song_fetcher=lambda _: {"id": 101, "name": "Rental", "lyrics": "", "synced_lyrics": ""}, + state={}, + ), + ) + assert summary.completed == 1 + assert downloads == [no_lyrics.destination] + + +def test_cli_retry_reports_existing_file_postprocessing_path(tmp_path, monkeypatch, capsys): + import juice_lyrics.cli as cli + + item = _item(tmp_path) + item.destination.write_bytes(b"finalized") + store = JobStore(tmp_path / "jobs.json") + job = store.create([item], job_id="cli-post-retry") + entry = job.items[0] + entry.state = AcquisitionState.FAILED + entry.failure_stage = AcquisitionFailureStage.STATE + entry.retry_file_size = item.destination.stat().st_size + entry.retry_file_sha256 = runner._sha256(item.destination) + entry.bytes_written = item.destination.stat().st_size + store.save(job) + + monkeypatch.setattr(cli, "JobStore", lambda: JobStore(store.path)) + monkeypatch.setattr( + runner, + "download_to", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("download called")), + ) + monkeypatch.setattr( + cli, + "integrate_downloaded_mp3", + lambda integration_item, **kwargs: IntegrationResult( + integration_item.destination, + message="USLT; verified", + ), + ) + + args = cli.build_parser().parse_args(["acquire", "retry", "cli-post-retry"]) + result = cli.command_acquire(args, cli.load_settings(str(tmp_path), None), False) + output = capsys.readouterr().out + + assert result == 0 + assert "Retrying post-processing from existing finalized file" in output + assert "Completed: 1" in output diff --git a/tests/test_acquisition_queue_service.py b/tests/test_acquisition_queue_service.py new file mode 100644 index 0000000..de40089 --- /dev/null +++ b/tests/test_acquisition_queue_service.py @@ -0,0 +1,220 @@ +import hashlib +import json +from pathlib import Path +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +import pytest + +from juice_lyrics.acquisition.jobs import JobStore +from juice_lyrics.acquisition.models import AcquisitionFailureStage, AcquisitionItem, AcquisitionState +from juice_lyrics.services.acquisition_queue import ( + QueueFailureStage, + QueueReferenceError, + QueueStatus, + get_queue_snapshot, + resolve_queue_reference, +) + + +def _item(tmp_path, title="Rental"): + return AcquisitionItem( + identifier=title.lower(), + title=title, + url=f"https://example.invalid/{title.lower()}.mp3", + destination=tmp_path / f"{title}.mp3", + expected_size=100, + ) + + +def test_empty_queue_is_read_only(tmp_path): + path = tmp_path / "missing" / "jobs.json" + snapshot = get_queue_snapshot(path) + + assert snapshot.jobs == () + assert snapshot.total_job_count == 0 + assert snapshot.active_job_count == 0 + assert snapshot.pending_job_count == 0 + assert snapshot.completed_job_count == 0 + assert snapshot.failed_job_count == 0 + assert not path.parent.exists() + + +def test_queue_orders_newest_first_and_resolves_references(tmp_path): + path = tmp_path / "jobs.json" + store = JobStore(path) + older = store.create([_item(tmp_path, "Older")], job_id="older-uuid") + newer = store.create([_item(tmp_path, "Newer")], job_id="newer-uuid") + older.created_at = "2024-01-01T00:00:00+00:00" + newer.created_at = "2025-01-01T00:00:00+00:00" + store.save(older) + store.save(newer) + + snapshot = get_queue_snapshot(path) + + assert [job.job_id for job in snapshot.jobs] == ["newer-uuid", "older-uuid"] + assert [job.display_number for job in snapshot.jobs] == [1, 2] + assert resolve_queue_reference(snapshot, 1).job_id == "newer-uuid" + assert resolve_queue_reference(snapshot, "2").job_id == "older-uuid" + assert resolve_queue_reference(snapshot, "latest").job_id == "newer-uuid" + assert resolve_queue_reference(snapshot, "older-uuid").display_number == 2 + + +def test_invalid_queue_references(tmp_path): + snapshot = get_queue_snapshot(tmp_path / "missing.json") + with pytest.raises(QueueReferenceError, match="empty"): + resolve_queue_reference(snapshot, "latest") + with pytest.raises(QueueReferenceError, match="out of range"): + resolve_queue_reference(snapshot, 1) + with pytest.raises(QueueReferenceError, match="not found"): + resolve_queue_reference(snapshot, "unknown-uuid") + + +def test_mixed_states_counts_retry_and_deletion_rules(tmp_path): + store = JobStore(tmp_path / "jobs.json") + job = store.create( + [_item(tmp_path, name) for name in ("Pending", "Active", "Done", "Skipped", "Failed")], + job_id="mixed-uuid", + ) + states = [ + AcquisitionState.PENDING, + AcquisitionState.DOWNLOADING, + AcquisitionState.COMPLETE, + AcquisitionState.SKIPPED, + AcquisitionState.FAILED, + ] + for entry, state in zip(job.items, states): + entry.state = state + job.items[1].bytes_written = 40 + job.items[4].error = "network failed" + store.save(job) + + snapshot = get_queue_snapshot(store.path) + view = snapshot.jobs[0] + + assert view.status is QueueStatus.FAILED + assert view.pending_item_count == 1 + assert view.active_item_count == 1 + assert view.completed_item_count == 2 + assert view.failed_item_count == 1 + assert view.items[1].bytes_written == 40 + assert view.items[1].expected_bytes == 100 + assert view.items[4].error == "network failed" + assert view.items[2].retryable is False + assert view.items[3].retryable is False + assert view.items[4].retryable is True + assert view.retryable is True + assert view.deletion_allowed is False + assert snapshot.failed_job_count == 1 + + +def test_completed_pending_and_transitional_job_statuses(tmp_path): + store = JobStore(tmp_path / "jobs.json") + completed = store.create([_item(tmp_path, "Complete")], job_id="complete") + completed.items[0].state = AcquisitionState.COMPLETE + store.save(completed) + pending = store.create([_item(tmp_path, "Pending")], job_id="pending") + transitional = store.create([_item(tmp_path, "Imported")], job_id="transitional") + transitional.items[0].state = AcquisitionState.IMPORTED + store.save(transitional) + + snapshot = get_queue_snapshot(store.path) + by_id = {job.job_id: job for job in snapshot.jobs} + + assert by_id["complete"].status is QueueStatus.COMPLETED + assert by_id["complete"].retryable is False + assert by_id["complete"].deletion_allowed is True + assert by_id["pending"].status is QueueStatus.PENDING + assert by_id["transitional"].status is QueueStatus.POST_PROCESSING + assert snapshot.completed_job_count == 1 + assert snapshot.pending_job_count == 1 + assert snapshot.active_job_count == 1 + + +def test_unknown_state_and_malformed_optional_values_are_safe(tmp_path): + path = tmp_path / "jobs.json" + path.write_text( + json.dumps({ + "jobs": { + "unknown-uuid": { + "job_id": "unknown-uuid", + "created_at": None, + "items": [{ + "state": "future_state", + "bytes_written": "bad", + "resumed": False, + "error": {"bad": "shape"}, + "item": { + "title": None, + "destination": None, + "expected_size": "bad", + }, + }], + } + } + }), + encoding="utf-8", + ) + + view = get_queue_snapshot(path).jobs[0] + assert view.status is QueueStatus.UNKNOWN + assert view.items[0].status is QueueStatus.UNKNOWN + assert view.items[0].bytes_written == 0 + assert view.items[0].expected_bytes is None + assert view.items[0].retryable is False + assert view.label == "Untitled job" + + +def test_view_does_not_recover_or_rewrite_store(tmp_path): + store = JobStore(tmp_path / "jobs.json") + job = store.create([_item(tmp_path)], job_id="active-uuid") + job.items[0].state = AcquisitionState.CHECKING_EXISTING + store.save(job) + before = store.path.read_bytes() + + snapshot = get_queue_snapshot(store.path) + + assert snapshot.jobs[0].items[0].status is QueueStatus.CHECKING_EXISTING + assert store.path.read_bytes() == before + loaded = store.get("active-uuid") + assert loaded is not None + assert loaded.items[0].state is AcquisitionState.CHECKING_EXISTING + + +def test_failure_stage_updated_time_and_safe_postprocessing_retry_are_exposed(tmp_path): + store = JobStore(tmp_path / "jobs.json") + job = store.create([_item(tmp_path)], job_id="lyrics-failure") + destination = job.items[0].item.destination + destination.write_bytes(b"finalized audio") + job.items[0].state = AcquisitionState.FAILED + job.items[0].failure_stage = AcquisitionFailureStage.LYRICS + job.items[0].error = "lyrics verification failed" + job.items[0].retry_file_size = destination.stat().st_size + job.items[0].retry_file_sha256 = hashlib.sha256(destination.read_bytes()).hexdigest() + store.save(job) + + view = get_queue_snapshot(store.path).jobs[0] + + assert view.updated_at is not None + assert view.items[0].failure_stage is QueueFailureStage.LYRICS + assert view.items[0].postprocessing_retryable is True + + destination.write_bytes(b"changed") + assert get_queue_snapshot(store.path).jobs[0].items[0].postprocessing_retryable is False + + +def test_cli_jobs_uses_queue_view_and_preserves_output(tmp_path, monkeypatch, capsys): + import juice_lyrics.cli as cli + + store = JobStore(tmp_path / "jobs.json") + store.create([_item(tmp_path)], job_id="job-xyz") + monkeypatch.setattr(cli, "JobStore", lambda: JobStore(store.path)) + + args = cli.build_parser().parse_args(["acquire", "jobs"]) + result = cli.command_acquire(args, cli.load_settings(str(tmp_path), None), False) + output = capsys.readouterr().out + + assert result == 0 + assert "job-xyz — pending — 1 item(s)" in output + assert f"pending Rental → {tmp_path / 'Rental.mp3'}" in output diff --git a/tests/test_api_catalogue.py b/tests/test_api_catalogue.py new file mode 100644 index 0000000..4707f18 --- /dev/null +++ b/tests/test_api_catalogue.py @@ -0,0 +1,95 @@ +import json +from pathlib import Path +import sys +from urllib.parse import parse_qs, urlparse + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +import juice_lyrics.api.client as client +from juice_lyrics.config.settings import Settings + +FIXTURES = Path(__file__).parent / "fixtures" / "catalogue" + + +def _fixture(name): + return json.loads((FIXTURES / name).read_text(encoding="utf-8")) + + +def test_song_request_uses_canonical_filters_page_and_page_size(tmp_path, monkeypatch): + urls = [] + monkeypatch.setattr(client, "CACHE_DIR", tmp_path) + monkeypatch.setattr(client, "api_get", lambda url, timeout: urls.append(url) or {"count": 0, "results": []}) + + client.search_songs( + Settings(cache_ttl_hours=0, delay=0), + "Rental", + category="unreleased", + era="DRFL", + page=2, + page_size=50, + refresh=True, + ) + + parsed = urlparse(urls[0]) + assert parsed.path == "/juicewrld/songs/" + assert parse_qs(parsed.query) == { + "search": ["Rental"], + "category": ["unreleased"], + "era": ["DRFL"], + "page": ["2"], + "page_size": ["50"], + } + + +def test_filter_only_request_preserves_blank_search_and_server_filters(tmp_path, monkeypatch): + urls = [] + monkeypatch.setattr(client, "CACHE_DIR", tmp_path) + monkeypatch.setattr(client, "api_get", lambda url, timeout: urls.append(url) or {"count": 0, "results": []}) + + client.search_songs( + Settings(cache_ttl_hours=0, delay=0), + "", + category="unreleased", + era="DRFL", + refresh=True, + ) + + assert "search=" in urlparse(urls[0]).query + assert "category=unreleased" in urls[0] + assert "era=DRFL" in urls[0] + + +def test_case_sensitive_filter_values_have_distinct_cache_entries(tmp_path, monkeypatch): + urls = [] + monkeypatch.setattr(client, "CACHE_DIR", tmp_path) + monkeypatch.setattr(client, "api_get", lambda url, timeout: urls.append(url) or {"count": 0, "results": []}) + settings = Settings(cache_ttl_hours=24, delay=0) + + client.search_songs(settings, "", era="drfl") + client.search_songs(settings, "", era="DRFL") + + assert len(urls) == 2 + assert len(list(tmp_path.glob("catalogue_v3_*.json"))) == 2 + + +def test_api_metadata_shapes_and_era_pagination(tmp_path, monkeypatch): + urls = [] + monkeypatch.setattr(client, "CACHE_DIR", tmp_path) + + def api_get(url, timeout): + urls.append(url) + if "/categories/" in url: + return _fixture("categories.json") + if "page=1" in url: + return _fixture("eras_page_1.json") + return _fixture("eras_page_2.json") + + monkeypatch.setattr(client, "api_get", api_get) + settings = Settings(cache_ttl_hours=0, delay=0) + + categories = client.get_categories(settings, refresh=True) + eras = client.get_eras(settings, refresh=True) + + assert categories["categories"][1] == {"value": "unreleased", "label": "Unreleased"} + assert [(era["id"], era["name"]) for era in eras] == [(109, "WOD"), (110, "DRFL"), (130, "DRFL (TV)")] + assert len([url for url in urls if "/eras/" in url]) == 2 diff --git a/tests/test_backup_retention.py b/tests/test_backup_retention.py new file mode 100644 index 0000000..052cc97 --- /dev/null +++ b/tests/test_backup_retention.py @@ -0,0 +1,311 @@ +import json +from datetime import datetime, timedelta, timezone +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.backup import manager +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.library_status import get_library_status + + +def _completed_backup( + backup_dir: Path, + name: str, + created_at: datetime, + *, + audio: bytes = b"original audio", +) -> Path: + root = backup_dir / name + root.mkdir(parents=True) + (root / "Track.mp3").write_bytes(audio) + (root / "manifest.json").write_text( + json.dumps({"created": created_at.isoformat(), "files": [{"file": "Track.mp3"}]}), + encoding="utf-8", + ) + return root + + +def _backup_set(backup_dir: Path, count: int) -> list[Path]: + start = datetime(2026, 1, 1, tzinfo=timezone.utc) + return [ + _completed_backup( + backup_dir, + f"backup-{index:02d}", + start + timedelta(days=index), + ) + for index in range(count) + ] + + +def test_backup_roots_are_unique_within_the_same_second(tmp_path, monkeypatch): + backup_dir = tmp_path / "backups" + + class FixedDatetime(datetime): + @classmethod + def now(cls, tz=None): + return cls(2026, 9, 20, 13, 31, 40, tzinfo=tz) + + monkeypatch.setattr(manager, "BACKUP_DIR", backup_dir) + monkeypatch.setattr(manager, "DATA_DIR", tmp_path) + monkeypatch.setattr(manager, "datetime", FixedDatetime) + + first = manager.make_backup_root() + second = manager.make_backup_root() + third = manager.make_backup_root() + + assert first.name == "20260920-133140" + assert second.name == "20260920-133140-01" + assert third.name == "20260920-133140-02" + assert len({first, second, third}) == 3 + + +@pytest.mark.parametrize("count", [9, 10]) +def test_retention_does_nothing_at_or_below_limit(tmp_path, count): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, count) + + result = manager.prune_backup_history(backup_dir) + + assert result.removed == () + assert result.error is None + assert all(root.is_dir() for root in roots) + + +def test_successful_eleventh_backup_removes_only_oldest(tmp_path, monkeypatch): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 10) + newest = backup_dir / "newly-created" + newest.mkdir() + monkeypatch.setattr( + manager, + "now_iso", + lambda: datetime(2026, 2, 1, tzinfo=timezone.utc).isoformat(), + ) + + manager.write_manifest(newest, [{"file": "new.mp3"}]) + + assert not roots[0].exists() + assert all(root.exists() for root in roots[1:]) + assert newest.exists() + assert len(manager.list_backups(backup_dir)) == 10 + + +def test_repeated_successful_backups_never_retain_more_than_ten(tmp_path, monkeypatch): + backup_dir = tmp_path / "backups" + start = datetime(2026, 1, 1, tzinfo=timezone.utc) + created: list[Path] = [] + for index in range(15): + root = backup_dir / f"run-{index:02d}" + root.mkdir(parents=True) + created.append(root) + monkeypatch.setattr( + manager, + "now_iso", + lambda index=index: (start + timedelta(days=index)).isoformat(), + ) + manager.write_manifest(root, [{"file": f"{index}.mp3"}]) + assert len(manager.list_backups(backup_dir)) <= 10 + + assert all(not root.exists() for root in created[:5]) + assert all(root.exists() for root in created[5:]) + assert created[-1].exists() + + +def test_manifest_timestamp_controls_order_and_unrelated_entries_are_ignored(tmp_path): + backup_dir = tmp_path / "backups" + newer = _completed_backup( + backup_dir, + "0000-lexically-first", + datetime(2026, 2, 1, tzinfo=timezone.utc), + ) + oldest = _completed_backup( + backup_dir, + "9999-lexically-last", + datetime(2026, 1, 1, tzinfo=timezone.utc), + ) + (backup_dir / "notes.txt").write_text("leave me", encoding="utf-8") + (backup_dir / "unrelated-directory").mkdir() + (backup_dir / "broken-backup").mkdir() + (backup_dir / "broken-backup" / "manifest.json").write_text("not json", encoding="utf-8") + + result = manager.prune_backup_history(backup_dir, keep=1) + + assert result.removed == (oldest,) + assert newer.exists() + assert (backup_dir / "notes.txt").exists() + assert (backup_dir / "unrelated-directory").exists() + assert (backup_dir / "broken-backup").exists() + + +def test_manifest_failure_does_not_start_pruning(tmp_path, monkeypatch): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 11) + prune_called = False + + def unexpected_prune(*args, **kwargs): + nonlocal prune_called + prune_called = True + raise AssertionError("pruning started") + + monkeypatch.setattr(manager, "prune_backup_history", unexpected_prune) + missing_root = backup_dir / "backup-that-was-not-created" + + with pytest.raises(OSError): + manager.write_manifest(missing_root, []) + + assert not prune_called + assert all(root.exists() for root in roots) + + +def test_empty_backup_after_copy_failure_does_not_start_pruning(tmp_path, monkeypatch): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 11) + empty_root = backup_dir / "empty-failed-run" + empty_root.mkdir() + prune_called = False + + def unexpected_prune(*args, **kwargs): + nonlocal prune_called + prune_called = True + raise AssertionError("pruning started") + + monkeypatch.setattr(manager, "prune_backup_history", unexpected_prune) + + manager.write_manifest(empty_root, []) + + assert not prune_called + assert all(root.exists() for root in roots) + + +def test_prune_failure_stops_cleanup_and_preserves_new_backup(tmp_path): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 11) + attempted: list[Path] = [] + + def fail(candidate: Path) -> None: + attempted.append(candidate) + raise PermissionError("read only") + + result = manager.prune_backup_history( + backup_dir, + keep=10, + protected=roots[-1], + remover=fail, + ) + + assert attempted == [roots[0]] + assert result.removed == () + assert "read only" in (result.error or "") + assert all(root.exists() for root in roots) + assert roots[-1].exists() + + +def test_cleanup_failure_is_logged_without_failing_completed_backup(tmp_path, monkeypatch, caplog): + root = tmp_path / "backups" / "new" + root.mkdir(parents=True) + monkeypatch.setattr( + manager, + "prune_backup_history", + lambda *args, **kwargs: manager.BackupPruneResult(error="permission denied"), + ) + + manager.write_manifest(root, [{"file": "Track.mp3"}]) + + assert (root / "manifest.json").is_file() + assert "Backup created, but retention cleanup failed" in caplog.text + + +def test_read_only_status_counts_backups_without_pruning(tmp_path): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 11) + music_dir = tmp_path / "music" + music_dir.mkdir() + + status = get_library_status( + Settings(music_dir=music_dir), + state_file=tmp_path / "missing-state.json", + backup_dir=backup_dir, + ) + + assert status.backup_count == 11 + assert all(root.exists() for root in roots) + + +def test_retained_backup_can_still_be_restored(tmp_path): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 11) + result = manager.prune_backup_history(backup_dir) + target = tmp_path / "restored" + + restored = manager.restore_backup(roots[-1], target) + + assert result.removed == (roots[0],) + assert restored == 1 + assert (target / "Track.mp3").read_bytes() == b"original audio" + + +@pytest.mark.parametrize("batch", [False, True]) +def test_interrupted_restore_preserves_existing_audio(tmp_path, monkeypatch, batch): + backup = tmp_path / "backup" + backup.mkdir() + source = backup / "Track.mp3" + source.write_bytes(b"backup audio") + target = tmp_path / "music" / "Track.mp3" + target.parent.mkdir() + target.write_bytes(b"current audio") + + def interrupted_copy(source_path, destination_path): + Path(destination_path).write_bytes(b"partial") + raise OSError("copy interrupted") + + monkeypatch.setattr(manager.shutil, "copy2", interrupted_copy) + with pytest.raises(OSError, match="copy interrupted"): + if batch: + manager.restore_backup(backup, target.parent) + else: + manager.restore_file(source, target) + + assert target.read_bytes() == b"current audio" + assert list(target.parent.iterdir()) == [target] + + +def test_completed_flac_backup_is_valid_for_retention_and_restore(tmp_path): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 10) + newest = backup_dir / "flac-backup" + (newest / "Nested").mkdir(parents=True) + (newest / "Nested" / "Track.FLAC").write_bytes(b"flac backup") + (newest / "manifest.json").write_text( + json.dumps({"created": "2026-02-01T00:00:00+00:00", "files": []}), + encoding="utf-8", + ) + + result = manager.prune_backup_history(backup_dir) + target = tmp_path / "restored" + + assert result.removed == (roots[0],) + assert len(manager.list_backups(backup_dir)) == 10 + assert manager.restore_backup(newest, target) == 1 + assert (target / "Nested" / "Track.FLAC").read_bytes() == b"flac backup" + + +def test_completed_m4a_backup_uses_existing_retention_policy(tmp_path): + backup_dir = tmp_path / "backups" + roots = _backup_set(backup_dir, 10) + newest = backup_dir / "m4a-backup" + newest.mkdir(parents=True) + (newest / "Track.M4A").write_bytes(b"m4a backup") + (newest / "manifest.json").write_text( + json.dumps({"created": "2026-02-01T00:00:00+00:00", "files": []}), + encoding="utf-8", + ) + + result = manager.prune_backup_history(backup_dir) + + assert result.removed == (roots[0],) + assert len(manager.list_backups(backup_dir)) == 10 + assert newest.is_dir() diff --git a/tests/test_catalogue_service.py b/tests/test_catalogue_service.py new file mode 100644 index 0000000..fe2c0d6 --- /dev/null +++ b/tests/test_catalogue_service.py @@ -0,0 +1,305 @@ +import json +from pathlib import Path +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +import pytest + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.catalogue import ( + CatalogueFilterMetadata, + CataloguePage, + LyricAvailability, + get_catalogue_filters, + get_song_details, + get_song_details_by_id, + search_catalogue, + search_catalogue_page, +) + + +def test_empty_catalogue_search_preserves_filters(): + calls = [] + + def searcher(settings, query, **kwargs): + calls.append((query, kwargs)) + return {"results": []} + + results = search_catalogue( + Settings(), + "rental", + category="unreleased", + era="DRFL", + refresh=True, + searcher=searcher, + ) + + assert results == () + assert calls == [("rental", { + "category": "unreleased", + "era": "DRFL", + "page": 1, + "page_size": 50, + "refresh": True, + })] + + +def test_catalogue_search_forwards_empty_title_with_server_filters(): + calls = [] + + def searcher(settings, query, **kwargs): + calls.append((query, kwargs)) + return {"results": []} + + results = search_catalogue( + Settings(), + "", + category="unreleased", + era="DRFL", + searcher=searcher, + ) + + assert results == () + assert calls == [("", { + "category": "unreleased", + "era": "DRFL", + "page": 1, + "page_size": 50, + "refresh": False, + })] + + +def test_search_normalizes_shapes_lyrics_and_downloadability(tmp_path): + records = [ + { + "id": 1, + "name": "Synced Song", + "category": "unreleased", + "era": "DRFL", + "length": "3:00", + "credited_artists": "Juice WRLD", + "producers": [{"name": "Producer One"}, "Producer Two"], + "path": "Tracks/Synced Song.mp3", + "synced_lyrics": "[00:01.00] line", + "lyrics": "line", + }, + { + "id": "2", + "title": "Plain Song", + "era": {"id": 4, "name": "JW3"}, + "artist": [{"name": "Juice WRLD"}], + "producer": {"name": "Producer Three"}, + "download_url": "https://example.invalid/plain.mp3", + "lyrics": "plain lyrics", + }, + {"id": 3, "name": "Unavailable", "era": None}, + ] + + results = search_catalogue( + Settings(music_dir=tmp_path), + "song", + searcher=lambda *args, **kwargs: {"results": records}, + ) + + assert [result.selection_index for result in results] == [1, 2, 3] + assert [result.title for result in results] == ["Synced Song", "Plain Song", "Unavailable"] + assert results[0].era == "DRFL" + assert results[1].era == "JW3" + assert results[0].artists == ("Juice WRLD",) + assert results[0].producers == ("Producer One", "Producer Two") + assert results[1].producers == ("Producer Three",) + assert results[0].lyrics is LyricAvailability.SYNCED + assert results[1].lyrics is LyricAvailability.PLAIN + assert results[2].lyrics is LyricAvailability.NONE + assert results[0].downloadable is True + assert results[1].downloadable is True + assert results[2].downloadable is False + + +def test_page_normalizes_total_next_previous_and_visible_range(tmp_path): + payload = json.loads( + (Path(__file__).parent / "fixtures" / "catalogue" / "songs_unreleased_drfl_page_2.json").read_text(encoding="utf-8") + ) + calls = [] + + page = search_catalogue_page( + Settings(music_dir=tmp_path), + "", + category="unreleased", + era="DRFL", + page=2, + page_size=50, + searcher=lambda settings, query, **kwargs: calls.append((query, kwargs)) or payload, + ) + + assert isinstance(page, CataloguePage) + assert page.total_count == 235 + assert page.page == 2 + assert page.page_size == 50 + assert page.previous_page == 1 + assert page.next_page == 3 + assert page.range_start == 51 + assert page.range_end == 52 + assert [result.song_id for result in page.results] == [95214, 95061] + assert calls[0][1]["page"] == 2 + assert calls[0][1]["page_size"] == 50 + + +def test_filter_metadata_maps_labels_to_canonical_request_values(): + metadata = get_catalogue_filters( + Settings(), + category_fetcher=lambda *args, **kwargs: json.loads( + (Path(__file__).parent / "fixtures" / "catalogue" / "categories.json").read_text(encoding="utf-8") + ), + era_fetcher=lambda *args, **kwargs: json.loads( + (Path(__file__).parent / "fixtures" / "catalogue" / "eras_page_1.json").read_text(encoding="utf-8") + )["results"], + ) + + assert isinstance(metadata, CatalogueFilterMetadata) + assert [(item.label, item.value) for item in metadata.categories] == [ + ("Released", "released"), + ("Unreleased", "unreleased"), + ("Unsurfaced", "unsurfaced"), + ("Recording Session", "recording_session"), + ] + drfl = next(item for item in metadata.eras if item.label == "DRFL") + assert drfl.value == "DRFL" + assert drfl.identifier == 110 + + +def test_details_by_id_uses_stable_selected_song_id(tmp_path): + fetched = [] + details = get_song_details_by_id( + Settings(music_dir=tmp_path), + 95214, + selection_index=7, + details_fetcher=lambda settings, song_id: fetched.append(song_id) or { + "id": song_id, + "name": "Rental (v1)", + "era": {"id": 110, "name": "DRFL"}, + "category": "unreleased", + }, + ) + + assert details is not None + assert details.song_id == 95214 + assert details.selection_index == 7 + assert fetched == [95214] + + +def test_details_normalize_explicit_track_number_and_released_path_album(tmp_path): + details = get_song_details_by_id( + Settings(music_dir=tmp_path), + 94102, + details_fetcher=lambda settings, song_id: { + "id": song_id, + "name": "10 Feet", + "category": "released", + "track_number": "8/22", + "path": "Compilation/Released Discography/11. Death Race For Love/10 Feet.mp3", + }, + ) + + assert details is not None + assert details.album == "Death Race For Love" + assert details.track_number == "8/22" + + +def test_search_handles_malformed_optional_metadata_without_writes(tmp_path): + settings = Settings(music_dir=tmp_path / "does-not-exist") + record = { + "id": True, + "name": {"unexpected": "shape"}, + "era": {"unexpected": "shape"}, + "length": ["3:00"], + "credited_artists": [{"unexpected": "shape"}, None], + "producers": 42, + "album": 42, + } + + result = search_catalogue( + settings, + "bad", + searcher=lambda *args, **kwargs: {"results": [record]}, + )[0] + + assert result.song_id is None + assert result.title is None + assert result.era is None + assert result.length is None + assert result.artists == () + assert result.producers == () + assert result.album is None + assert result.media_path is None + assert result.downloadable is False + assert not settings.music_dir.exists() + + +def test_details_selects_index_fetches_and_normalizes_content(tmp_path): + search_records = [ + {"id": 10, "name": "First"}, + {"id": 20, "name": "Second"}, + ] + fetched_ids = [] + + def fetcher(settings, song_id): + fetched_ids.append(song_id) + return { + "id": song_id, + "name": "Second Details", + "category": "unreleased", + "era": {"name": "WOD"}, + "length": "2:19", + "credited_artists": ["Juice WRLD", {"name": "Guest"}], + "producers": "Producer", + "path": "Tracks/Second.mp3", + "synced_lyrics": "[00:01.00] synced", + "lyrics": "plain fallback", + } + + details = get_song_details( + Settings(music_dir=tmp_path), + "second", + selection_index=2, + refresh=True, + searcher=lambda settings, query, refresh=False: search_records, + details_fetcher=fetcher, + ) + + assert details is not None + assert details.selection_index == 2 + assert details.song_id == 20 + assert details.title == "Second Details" + assert details.era == "WOD" + assert details.artists == ("Juice WRLD", "Guest") + assert details.producers == ("Producer",) + assert details.lyrics is LyricAvailability.SYNCED + assert details.synced_lyrics == "[00:01.00] synced" + assert details.plain_lyrics == "plain fallback" + assert details.downloadable is True + assert fetched_ids == [20] + + +def test_details_empty_invalid_index_and_fetch_fallback(tmp_path): + settings = Settings(music_dir=tmp_path) + assert get_song_details( + settings, + "none", + searcher=lambda *args, **kwargs: [], + ) is None + + searcher = lambda *args, **kwargs: [{"id": 1, "name": "Fallback", "lyrics": "plain"}] + with pytest.raises(RuntimeError, match="--index is outside the result list"): + get_song_details(settings, "song", selection_index=2, searcher=searcher) + + details = get_song_details( + settings, + "song", + searcher=searcher, + details_fetcher=lambda *args: (_ for _ in ()).throw(RuntimeError("offline")), + ) + assert details is not None + assert details.title == "Fallback" + assert details.lyrics is LyricAvailability.PLAIN diff --git a/tests/test_core.py b/tests/test_core.py index 2d52bbe..7b9fbe5 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -1,7 +1,10 @@ from pathlib import Path +import argparse import sys import tempfile +import pytest + sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) from juice_lyrics.cli import parse_length, parse_synced_lyrics, patch_rmpc_config @@ -56,13 +59,14 @@ def test_command_status_with_settings(tmp_path, capsys, monkeypatch): import juice_lyrics.cli as cli from juice_lyrics.config.settings import Settings - settings = Settings(music_dir=tmp_path) + settings = Settings(music_dir=tmp_path, lyrics_dir=tmp_path / "central-lyrics") # Empty directory status rc = cli.command_status(settings, use_color=False) assert rc == 0 out = capsys.readouterr().out assert "Library Status" in out - assert "MP3 files: 0" in out + assert "External lyrics: Beside each song (.lrc)" in out + assert "Audio files: 0" in out # Status with an MP3 file mp3 = tmp_path / "track.mp3" @@ -71,7 +75,7 @@ def test_command_status_with_settings(tmp_path, capsys, monkeypatch): rc = cli.command_status(settings, use_color=False) assert rc == 0 out = capsys.readouterr().out - assert "MP3 files: 1" in out + assert "Audio files: 1" in out assert "Embedded synced: 1" in out @@ -152,6 +156,194 @@ def test_command_guide(capsys): rc = cli.command_guide() assert rc == 0 out = capsys.readouterr().out - assert "juice-lyrics quick guide" in out - assert "juice-lyrics acquire search" in out - assert "juice-lyrics sync" in out + assert "999 quick guide" in out + assert "999 sync --dry-run" in out + assert "999 rmpc setup" in out + assert "juice-lyrics" not in out + + +def test_config_show_preserves_missing_and_existing_cli_behavior(tmp_path, monkeypatch, capsys): + import argparse + import juice_lyrics.cli as cli + + config = tmp_path / "config.toml" + monkeypatch.setattr(cli, "CONFIG_FILE", config) + args = argparse.Namespace(action="show") + + assert cli.command_config(args) == 0 + output = capsys.readouterr().out + assert "No config. Defaults are in use." in output + assert str(config) in output + + content = 'music_dir = "/music"\ntimeout = 20\n' + config.write_text(content, encoding="utf-8") + assert cli.command_config(args) == 0 + shown = capsys.readouterr().out + assert content.strip() in shown + assert "External lyrics: beside each song (.lrc)" in shown + + +def test_lyrics_directory_default_config_override_and_unknown_keys(tmp_path, monkeypatch, capsys): + import juice_lyrics.cli as cli + from juice_lyrics.config.settings import DEFAULT_LYRICS_DIR, Settings + + config = tmp_path / "config.toml" + monkeypatch.setattr(cli, "CONFIG_FILE", config) + + assert DEFAULT_LYRICS_DIR == Path.home() / "Music" / "lyrics" + assert Settings().lyrics_dir == DEFAULT_LYRICS_DIR + assert cli.load_settings().lyrics_dir == DEFAULT_LYRICS_DIR + assert not config.exists() + + config.write_text('rmpc_lyrics_dir = "~/ignored-legacy-suggestion"\n', encoding="utf-8") + assert cli.load_settings().lyrics_dir == DEFAULT_LYRICS_DIR + + config.write_text( + 'lyrics_dir = "~/shared-lyrics"\nunknown_future_key = "ignored"\n', + encoding="utf-8", + ) + loaded = cli.load_settings() + assert loaded.lyrics_dir == Path.home() / "shared-lyrics" + assert config.read_text(encoding="utf-8").endswith('unknown_future_key = "ignored"\n') + assert cli.command_config(argparse.Namespace(action="show"), loaded) == 0 + shown = capsys.readouterr().out + assert "Deprecated lyrics_dir (ignored for LRC output)" in shown + assert "External lyrics: beside each song (.lrc)" in shown + + missing_lyrics = tmp_path / "not-created" / "lyrics" + config.write_text(f'lyrics_dir = "{missing_lyrics}"\n', encoding="utf-8") + assert cli.load_settings().lyrics_dir == missing_lyrics + assert not missing_lyrics.exists() + + config.unlink() + cli.write_default_config() + assert "lyrics_dir" not in config.read_text(encoding="utf-8") + + +def test_rmpc_setup_indexes_music_tree_without_creating_legacy_lyrics_directory( + tmp_path, monkeypatch +): + import argparse + import juice_lyrics.cli as cli + from juice_lyrics.config.settings import Settings + + rmpc_config = tmp_path / "rmpc" / "config.ron" + rmpc_config.parent.mkdir() + rmpc_config.write_text("()", encoding="utf-8") + configured_lyrics = tmp_path / "Music" / "lyrics" + configured = [] + + monkeypatch.setattr(cli.shutil, "which", lambda name: "/usr/bin/rmpc") + monkeypatch.setattr(cli, "find_mp3s", lambda settings: []) + monkeypatch.setattr( + cli, + "patch_rmpc_config", + lambda path, lyrics: configured.append((path, lyrics)) or tmp_path / "rmpc.bak", + ) + monkeypatch.setattr(cli, "notify_rmpc_index", lambda paths: 0) + monkeypatch.setattr(cli, "rmpc_running", lambda: False) + + result = cli.command_rmpc_setup( + argparse.Namespace(config=str(rmpc_config), lyrics_dir=None, yes=True, refresh=False), + Settings(music_dir=tmp_path / "music", lyrics_dir=configured_lyrics), + False, + ) + + assert result == 0 + assert configured == [(rmpc_config, tmp_path / "music")] + assert not configured_lyrics.exists() + + +def test_config_init_and_missing_library_setup_dispatch_remain_compatible(tmp_path, monkeypatch): + import argparse + import juice_lyrics.cli as cli + from juice_lyrics.config.settings import Settings + + calls = [] + monkeypatch.setattr(cli, "write_default_config", lambda force: calls.append(force)) + assert cli.command_config(argparse.Namespace(action="init", force=True)) == 0 + assert calls == [True] + + missing = tmp_path / "missing-library" + with pytest.raises(RuntimeError, match="Music directory does not exist"): + cli.command_setup( + argparse.Namespace(yes=True, refresh=False), + Settings(music_dir=missing), + use_color=False, + ) + assert not missing.exists() + + +def test_library_setup_never_rewrites_rmpc_configuration(tmp_path, monkeypatch): + import juice_lyrics.cli as cli + from juice_lyrics.config.settings import Settings + + rmpc_config = tmp_path / "rmpc" / "config.ron" + rmpc_config.parent.mkdir() + rmpc_config.write_text("original rmpc configuration", encoding="utf-8") + monkeypatch.setattr(cli, "DEFAULT_RMPC_CONFIG", rmpc_config) + monkeypatch.setattr(cli.shutil, "which", lambda name: "/usr/bin/rmpc") + monkeypatch.setattr( + cli, + "patch_rmpc_config", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("rmpc rewritten")), + ) + monkeypatch.setattr(cli, "find_mp3s", lambda settings: []) + calls = [] + monkeypatch.setattr( + cli, + "embed_batch", + lambda settings, files, use_color, refresh, dry_run, yes, with_rmpc: ( + calls.append((files, with_rmpc)) or 0 + ), + ) + + result = cli.command_setup( + argparse.Namespace(yes=True, refresh=False), + Settings(music_dir=tmp_path), + use_color=False, + ) + + assert result == 0 + assert calls == [([], True)] + assert rmpc_config.read_text(encoding="utf-8") == "original rmpc configuration" + + +def test_state_clean_cli_is_preview_first_then_reports_backup(tmp_path, monkeypatch, capsys): + import juice_lyrics.cli as cli + from juice_lyrics.config.settings import Settings + + music = tmp_path / "Music" + music.mkdir() + state_file = tmp_path / "state.json" + stale = "/tmp/pytest-of-someone/pytest-8/test_case/Song.flac" + state_file.write_text( + __import__("json").dumps( + { + "files": { + stale: {"song_id": 1}, + "24 Hours.mp3": {"song_id": 94760, "api_name": "24 Hours"}, + } + } + ), + encoding="utf-8", + ) + monkeypatch.setattr(cli, "STATE_FILE", state_file) + + assert cli.command_state( + argparse.Namespace(action="clean", yes=False), Settings(music_dir=music), False + ) == 0 + preview = capsys.readouterr().out + assert stale in preview + assert "Preview only" in preview + assert stale in state_file.read_text(encoding="utf-8") + + assert cli.command_state( + argparse.Namespace(action="clean", yes=True), Settings(music_dir=music), False + ) == 0 + output = capsys.readouterr().out + assert "Removed: 1" in output + assert "State backup:" in output + cleaned = state_file.read_text(encoding="utf-8") + assert stale not in cleaned + assert "24 Hours" in cleaned diff --git a/tests/test_doctor.py b/tests/test_doctor.py new file mode 100644 index 0000000..4356d59 --- /dev/null +++ b/tests/test_doctor.py @@ -0,0 +1,222 @@ +from collections import namedtuple +import json +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics import cli +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.doctor import ( + DoctorCheck, + DoctorReport, + DoctorStatus, + render_support_report, + run_doctor, +) + + +Usage = namedtuple("Usage", "total used free") + + +def _paths(tmp_path): + return { + "config_path": tmp_path / "config" / "config.toml", + "state_file": tmp_path / "data" / "state.json", + "cache_dir": tmp_path / "cache", + "backup_dir": tmp_path / "data" / "backups", + "rmpc_config_path": tmp_path / "rmpc" / "config.ron", + } + + +def _run(tmp_path, *, probe=lambda url, timeout: {"count": 1, "results": [{"id": 1}]}, finder=None): + music = tmp_path / "music" + music.mkdir(exist_ok=True) + paths = _paths(tmp_path) + return run_doctor( + Settings(music_dir=music), + **paths, + api_probe=probe, + command_finder=finder or (lambda name: f"/usr/bin/{name}"), + disk_usage=lambda path: Usage(10_000_000_000, 1, 9_000_000_000), + rmpc_probe=lambda executable: True, + ) + + +def _check(report, key): + return next(item for item in report.checks if item.key == key) + + +def test_healthy_doctor_is_bounded_read_only_and_counts_supported_formats(tmp_path): + music = tmp_path / "music" + (music / "nested").mkdir(parents=True) + for name in ("One.mp3", "nested/Two.FLAC", "Three.m4a"): + path = music / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(b"untouched") + paths = _paths(tmp_path) + paths["config_path"].parent.mkdir(parents=True) + paths["config_path"].write_text(f'music_dir = "{music}"\ntimeout = 2\n', encoding="utf-8") + paths["state_file"].parent.mkdir(parents=True) + paths["state_file"].write_text('{"files": {"One.mp3": {"song_id": 1}}}', encoding="utf-8") + paths["cache_dir"].mkdir() + (paths["cache_dir"] / "page.json").write_text('{"results": []}', encoding="utf-8") + paths["rmpc_config_path"].parent.mkdir(parents=True) + paths["rmpc_config_path"].write_text( + f'lyrics_dir: Some("{music.parent}"),\nenable_lyrics_index: true,\nenable_lyrics_hot_reload: true,\n', + encoding="utf-8", + ) + before = {path: path.read_bytes() for path in tmp_path.rglob("*") if path.is_file()} + calls = [] + + report = run_doctor( + Settings(music_dir=music), **paths, + api_probe=lambda url, timeout: calls.append((url, timeout)) or {"count": 1, "results": [{"id": 1}]}, + command_finder=lambda name: f"/usr/bin/{name}", + disk_usage=lambda path: Usage(10_000_000_000, 1, 9_000_000_000), + rmpc_probe=lambda executable: True, + ) + + assert report.failed == 0 + assert _check(report, "library").status is DoctorStatus.PASS + assert "MP3 1, FLAC 1, M4A 1" in _check(report, "library").detail + assert _check(report, "catalogue").status is DoctorStatus.PASS + assert len(calls) == 1 and "page_size=1" in calls[0][0] + assert {path: path.read_bytes() for path in tmp_path.rglob("*") if path.is_file()} == before + + +def test_doctor_reports_the_invoked_isolated_executable_instead_of_a_stale_path(tmp_path): + launcher = tmp_path / "isolated-env" / "bin" / "999" + launcher.parent.mkdir(parents=True) + launcher.write_text("#!/bin/sh\n", encoding="utf-8") + + report = run_doctor( + Settings(music_dir=tmp_path / "music"), + **_paths(tmp_path), + api_probe=lambda url, timeout: {"count": 1, "results": [{"id": 1}]}, + command_finder=lambda name: "/home/user/.local/bin/999", + disk_usage=lambda path: Usage(10_000_000_000, 1, 9_000_000_000), + rmpc_probe=lambda executable: True, + invoked_command=str(launcher), + ) + + runtime = _check(report, "runtime") + assert runtime.status is DoctorStatus.PASS + assert str(launcher) in runtime.detail + assert "/home/user/.local/bin/999" not in runtime.detail + + +def test_offline_catalogue_is_warning_but_invalid_response_is_failure(tmp_path): + def offline(url, timeout): + raise RuntimeError("network timed out") + + offline_report = _run(tmp_path, probe=offline) + assert _check(offline_report, "catalogue").status is DoctorStatus.WARN + assert "offline or unreachable" in _check(offline_report, "catalogue").detail + + invalid_report = _run(tmp_path, probe=lambda url, timeout: {"unexpected": []}) + assert _check(invalid_report, "catalogue").status is DoctorStatus.FAIL + assert "results list" in _check(invalid_report, "catalogue").detail + + +def test_malformed_state_and_cache_are_reported_without_repair(tmp_path): + paths = _paths(tmp_path) + paths["config_path"].parent.mkdir(parents=True) + paths["config_path"].write_text("timeout = 'not a number'", encoding="utf-8") + paths["state_file"].parent.mkdir(parents=True) + paths["state_file"].write_text("{broken", encoding="utf-8") + paths["cache_dir"].mkdir() + (paths["cache_dir"] / "broken.json").write_text("not json", encoding="utf-8") + original_state = paths["state_file"].read_bytes() + original_cache = (paths["cache_dir"] / "broken.json").read_bytes() + + report = _run(tmp_path) + + assert _check(report, "state").status is DoctorStatus.FAIL + assert _check(report, "cache").status is DoctorStatus.WARN + assert _check(report, "config").status is DoctorStatus.FAIL + assert paths["state_file"].read_bytes() == original_state + assert (paths["cache_dir"] / "broken.json").read_bytes() == original_cache + + +def test_missing_and_unreadable_music_directories_are_clear_failures(tmp_path, monkeypatch): + paths = _paths(tmp_path) + missing = tmp_path / "missing" + report = run_doctor( + Settings(music_dir=missing), **paths, + api_probe=lambda url, timeout: {"results": []}, + command_finder=lambda name: None, + disk_usage=lambda path: Usage(1_000_000_000, 0, 900_000_000), + rmpc_probe=lambda executable: True, + ) + assert _check(report, "library").status is DoctorStatus.FAIL + assert "does not exist" in _check(report, "library").detail + + music = tmp_path / "music" + music.mkdir() + import juice_lyrics.services.doctor as doctor_module + real_access = doctor_module.os.access + monkeypatch.setattr(doctor_module.os, "access", lambda path, mode: False if Path(path) == music else real_access(path, mode)) + report = _run(tmp_path) + assert _check(report, "library").status is DoctorStatus.FAIL + assert "not readable" in _check(report, "library").detail + + +def test_support_report_redacts_home_user_credentials_and_private_contents(tmp_path): + home = Path("/home/alice") + report = DoctorReport(( + DoctorCheck( + "privacy", "Privacy", DoctorStatus.FAIL, + "/home/alice/Music/private/song.mp3 token=super-secret https://bob:hunter2@example.test", + "password: dont-print-this", + ), + )) + + text = render_support_report(report, home=home) + parsed = json.loads(text) + + assert parsed["privacy"].startswith("Sanitized") + for secret in ("alice", "private/song", "super-secret", "bob", "hunter2", "dont-print-this"): + assert secret not in text + assert "" in text and "" in text + assert "song list" in parsed["privacy"] + + +def test_malformed_config_still_reaches_cli_doctor_and_support_report_save_is_explicit(tmp_path, monkeypatch, capsys): + config = tmp_path / "config.toml" + config.write_text("invalid = [", encoding="utf-8") + destination = tmp_path / "support.json" + captured = [] + report = DoctorReport((DoctorCheck("config", "Configuration", DoctorStatus.FAIL, "invalid token=secret"),)) + monkeypatch.setattr(cli, "CONFIG_FILE", config) + monkeypatch.setattr(cli, "run_doctor", lambda settings, **kwargs: captured.append(settings) or report) + + result = cli.main(["--no-color", "doctor", "--save-report", str(destination)]) + + assert result == 1 + assert captured + assert destination.exists() + assert "secret" not in destination.read_text(encoding="utf-8") + output = capsys.readouterr().out + assert "FAIL Configuration" in output + assert "Sanitized support report saved" in output + + +def test_doctor_parser_exposes_sanitized_report_options(): + args = cli.build_parser().parse_args(["doctor", "--support-report", "--save-report", "report.json"]) + assert args.command == "doctor" + assert args.support_report is True + assert args.save_report == "report.json" + + +def test_missing_required_and_optional_dependencies_are_distinguished(tmp_path, monkeypatch): + import juice_lyrics.services.doctor as doctor_module + + monkeypatch.setattr(doctor_module.importlib.util, "find_spec", lambda name: None) + report = _run(tmp_path, finder=lambda name: None) + + assert _check(report, "dependencies").status is DoctorStatus.FAIL + assert _check(report, "rmpc").status is DoctorStatus.WARN + assert "Optional" in _check(report, "rmpc").detail diff --git a/tests/test_download_queue_service.py b/tests/test_download_queue_service.py new file mode 100644 index 0000000..991ae93 --- /dev/null +++ b/tests/test_download_queue_service.py @@ -0,0 +1,558 @@ +from pathlib import Path + +from juice_lyrics.acquisition.jobs import JobStore +from juice_lyrics.acquisition.integration import IntegrationResult +from juice_lyrics.acquisition.models import ( + AcquisitionFailureStage, + AcquisitionItem, + AcquisitionResult, + AcquisitionState, +) +from juice_lyrics.acquisition.runner import AcquisitionRunSummary +from juice_lyrics.acquisition.resolver import ResourceResolutionError +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.acquisition_queue import ( + QueueFailureStage, + QueueItem, + QueueJob, + QueueSnapshot, + QueueStatus, +) +from juice_lyrics.services.catalogue import CatalogueSearchResult, LyricAvailability +from juice_lyrics.services.download_queue import ( + DownloadExecutionAction, + DownloadExecutionStatus, + DownloadAllResult, + DownloadAllPlan, + DownloadRetryAction, + DownloadRetryStatus, + DownloadQueueItemStatus, + QueueAddStatus, + QueueBatchAddItemStatus, + QueueBatchAddStatus, + add_batch_to_download_queue, + add_to_download_queue, + execute_selected_download, + get_download_queue_snapshot, + plan_download_execution, + plan_download_retry, + plan_download_all, + execute_download_all, + remove_queue_item, + clear_download_queue, + clear_completed_history, + plan_queue_additions, + plan_queue_batch_additions, + project_download_queue, +) + + +def _queue_item(tmp_path: Path, title: str, status: QueueStatus, **kwargs) -> QueueItem: + return QueueItem( + title=title, + destination=tmp_path / f"{title}.mp3", + status=status, + stored_state=status.value, + bytes_written=kwargs.get("bytes_written", 0), + expected_bytes=kwargs.get("expected_bytes", 100), + resumed=False, + error=kwargs.get("error"), + retryable=kwargs.get("retryable", status is QueueStatus.FAILED), + failure_stage=kwargs.get("failure_stage"), + identifier=kwargs.get("identifier", title.lower()), + metadata=(("artist", "Juice WRLD"), ("category", "unreleased"), ("era", "DRFL")), + ) + + +def _job(number: int, job_id: str, items: tuple[QueueItem, ...]) -> QueueJob: + return QueueJob( + display_number=number, + job_id=job_id, + label=items[0].title or "Untitled", + created_at=f"2026-08-30T12:0{number}:00+00:00", + destination=items[0].destination, + total_item_count=len(items), + pending_item_count=sum(item.status is QueueStatus.PENDING for item in items), + active_item_count=sum(item.status is QueueStatus.DOWNLOADING for item in items), + completed_item_count=sum(item.status is QueueStatus.COMPLETED for item in items), + failed_item_count=sum(item.status is QueueStatus.FAILED for item in items), + status=QueueStatus.FAILED if any(item.status is QueueStatus.FAILED for item in items) else items[0].status, + stored_state="failed" if any(item.status is QueueStatus.FAILED for item in items) else "pending", + retryable=any(item.retryable for item in items), + deletion_allowed=True, + items=items, + ) + + +def _selection( + *, + downloadable: bool = True, + song_id: int | None = 94902, + title: str = "Lemon Glow", +) -> CatalogueSearchResult: + return CatalogueSearchResult( + selection_index=1, + song_id=song_id, + title=title, + category="unreleased", + era="DRFL", + length="3:12", + artists=("Juice WRLD",), + producers=(), + media_path=f"Compilation/DRFL/{title}.mp3" if downloadable else None, + lyrics=LyricAvailability.SYNCED, + downloadable=downloadable, + ) + + +def test_internal_jobs_flatten_into_tracks_and_completed_stays_out_of_active_queue(tmp_path): + queued = _queue_item(tmp_path, "Queued", QueueStatus.PENDING) + downloading = _queue_item(tmp_path, "Moving", QueueStatus.DOWNLOADING, bytes_written=50) + complete = _queue_item(tmp_path, "Done", QueueStatus.COMPLETED, bytes_written=100) + failed = _queue_item( + tmp_path, + "Broken", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.LYRICS, + error="verification failed", + ) + snapshot = QueueSnapshot( + (_job(1, "first-job", (queued, downloading)), _job(2, "second-job", (complete, failed))), + 2, 1, 1, 0, 1, + ) + + projected = project_download_queue(snapshot) + + assert [item.title for item in projected.items] == ["Queued", "Moving", "Broken"] + assert projected.queued_count == 1 + assert projected.downloading_count == 1 + assert projected.failed_count == 1 + assert projected.completed_count == 1 + broken = projected.items[-1] + assert broken.failure_stage == "Lyrics processing failed" + assert broken.retryable + assert broken.artist == "Juice WRLD" + assert broken.status is DownloadQueueItemStatus.FAILED + + +def test_retry_plan_uses_verified_finalized_file_for_processing_only(tmp_path): + jobs_path = tmp_path / "jobs.json" + destination = tmp_path / "Lemon Glow.mp3" + destination.write_bytes(b"pristine") + item = AcquisitionItem("94902", "Lemon Glow", "https://example.test/song", destination) + job = JobStore(jobs_path).create([item], job_id="retry-job") + entry = job.items[0] + entry.state = AcquisitionState.FAILED + entry.failure_stage = AcquisitionFailureStage.LYRICS + entry.error = "lyrics verification failed" + import hashlib + entry.retry_file_size = destination.stat().st_size + entry.retry_file_sha256 = hashlib.sha256(destination.read_bytes()).hexdigest() + JobStore(jobs_path).save(job) + + result = plan_download_retry(Settings(music_dir=tmp_path / "music"), "retry-job:0", jobs_path=jobs_path) + assert result.status is DownloadRetryStatus.READY + assert result.plan is not None + assert result.plan.action is DownloadRetryAction.PROCESS_ONLY + assert result.plan.song_id == "94902" + + +def test_retry_plan_chooses_resume_or_download_again_for_transport_failure(tmp_path): + jobs_path = tmp_path / "jobs.json" + destination = tmp_path / "song.mp3" + item = AcquisitionItem("1", "Song", "https://example.test/song", destination) + job = JobStore(jobs_path).create([item], job_id="transport-job") + entry = job.items[0]; entry.state = AcquisitionState.FAILED; entry.failure_stage = AcquisitionFailureStage.TRANSPORT + JobStore(jobs_path).save(job) + settings = Settings(music_dir=tmp_path / "music") + result = plan_download_retry(settings, "transport-job:0", jobs_path=jobs_path) + assert result.plan is not None and result.plan.action is DownloadRetryAction.DOWNLOAD_AGAIN + destination.with_name("song.mp3.part").write_bytes(b"partial") + result = plan_download_retry(settings, "transport-job:0", jobs_path=jobs_path) + assert result.plan is not None and result.plan.action is DownloadRetryAction.RESUME_DOWNLOAD + + +def test_queue_cleanup_is_record_only_and_preserves_files(tmp_path): + jobs_path = tmp_path / "jobs.json" + queued_path = tmp_path / "queued.mp3"; queued_path.write_bytes(b"audio") + done_path = tmp_path / "done.mp3"; done_path.write_bytes(b"audio") + store = JobStore(jobs_path) + job = store.create([AcquisitionItem("q", "Queued", "url", queued_path), AcquisitionItem("d", "Done", "url", done_path)], job_id="cleanup") + job.items[1].state = AcquisitionState.COMPLETE; store.save(job) + removed = remove_queue_item("cleanup:0", jobs_path=jobs_path) + assert removed.removed_count == 1 and queued_path.exists() and done_path.exists() + history = clear_completed_history(jobs_path=jobs_path) + assert history.removed_count == 1 and done_path.exists() + + +def test_clear_queue_keeps_active_and_completed_history(tmp_path): + jobs_path = tmp_path / "jobs.json"; store = JobStore(jobs_path) + job = store.create([AcquisitionItem("q", "Queued", "url", tmp_path / "q.mp3"), AcquisitionItem("a", "Active", "url", tmp_path / "a.mp3")], job_id="clear") + job.items[1].state = AcquisitionState.DOWNLOADING; store.save(job) + result = clear_download_queue(jobs_path=jobs_path) + assert result.removed_count == 1 and result.retained_active_count == 1 + remaining = JobStore(jobs_path).get("clear"); assert remaining is not None and len(remaining.items) == 1 + + +def test_download_all_plan_includes_only_waiting_songs(tmp_path): + jobs_path = tmp_path / "jobs.json"; store = JobStore(jobs_path) + job = store.create([ + AcquisitionItem("q", "Queued", "url", tmp_path / "q.mp3"), + AcquisitionItem("f", "Failed", "url", tmp_path / "f.mp3"), + AcquisitionItem("a", "Active", "url", tmp_path / "a.mp3"), + AcquisitionItem("d", "Done", "url", tmp_path / "d.mp3"), + ], job_id="batch") + job.items[1].state = AcquisitionState.FAILED + job.items[2].state = AcquisitionState.DOWNLOADING + job.items[3].state = AcquisitionState.COMPLETE + store.save(job) + planned = plan_download_all(Settings(music_dir=tmp_path / "music"), jobs_path=jobs_path) + assert not isinstance(planned, DownloadAllResult) + assert [item.title for item in planned.eligible] == ["Queued"] + assert (planned.failed_count, planned.active_count, planned.completed_count) == (1, 1, 1) + + +def test_download_all_executes_exactly_one_eligible_song(tmp_path): + jobs_path = tmp_path / "jobs.json" + item = AcquisitionItem("one", "One Song", "https://example.test/one.mp3", tmp_path / "One Song.mp3") + job = JobStore(jobs_path).create([item], job_id="one-song") + settings = Settings(music_dir=tmp_path, lyrics_dir=tmp_path / "lyrics") + planned = plan_download_all(settings, jobs_path=jobs_path) + assert isinstance(planned, DownloadAllPlan) + assert len(planned.eligible) == 1 + calls = [] + + def runner(job, store, *, item_indexes, **kwargs): + calls.append(tuple(item_indexes)) + result = AcquisitionResult(job.items[0].item, AcquisitionState.COMPLETE, destination=job.items[0].item.destination, bytes_written=10) + job.record_result(0, result) + store.save(job) + return AcquisitionRunSummary(job.job_id, 1, 0, 0, 0) + + result = execute_download_all(settings, planned, jobs_path=jobs_path, runner=runner) + assert calls == [(0,)] + assert result.completed_count == 1 + assert result.failed_count == 0 + assert result.skipped_count == 0 + assert "1 completed" in result.message + + +def test_plan_and_confirm_adds_exactly_one_song_without_running_it(tmp_path, monkeypatch): + import juice_lyrics.acquisition.downloader as downloader + import juice_lyrics.acquisition.runner as runner + + jobs_path = tmp_path / "jobs.json" + music = tmp_path / "music" + settings = Settings(music_dir=music) + monkeypatch.setattr(downloader, "download_to", lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("download ran"))) + monkeypatch.setattr(runner, "run_job", lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("runner ran"))) + + planned = plan_queue_additions(settings, (_selection(),), jobs_path=jobs_path) + assert planned.status is QueueAddStatus.READY + assert not jobs_path.exists() + + added = add_to_download_queue(planned.plan, jobs_path=jobs_path) # type: ignore[arg-type] + assert added.status is QueueAddStatus.ADDED + assert added.added_count == 1 + jobs = JobStore(jobs_path).list() + assert len(jobs) == 1 + assert jobs[0].items[0].state is AcquisitionState.PENDING + assert jobs[0].items[0].item.identifier == "94902" + assert jobs[0].items[0].item.destination == music / "Lemon Glow.mp3" + queue = get_download_queue_snapshot(jobs_path) + assert [item.title for item in queue.items] == ["Lemon Glow"] + + +def test_batch_add_plans_eligible_items_and_reports_skips_by_stable_id(tmp_path): + jobs_path = tmp_path / "jobs.json" + settings = Settings(music_dir=tmp_path / "music") + first = _selection(song_id=101, title="First") + second = _selection(song_id=202, title="Second") + unavailable = _selection(song_id=303, title="Unavailable", downloadable=False) + stale = _selection(song_id=None, title="Stale") + + existing = plan_queue_additions(settings, (second,), jobs_path=jobs_path) + assert existing.plan is not None + assert add_to_download_queue(existing.plan, jobs_path=jobs_path).status is QueueAddStatus.ADDED + + result = plan_queue_batch_additions( + settings, + (first, first, second, unavailable, stale), + jobs_path=jobs_path, + ) + assert result.status is QueueBatchAddStatus.READY + assert result.plan is not None + assert [item.song_id for item in result.plan.eligible] == ["101"] + assert result.plan.count(QueueBatchAddItemStatus.ALREADY_QUEUED) == 2 + assert result.plan.count(QueueBatchAddItemStatus.UNAVAILABLE) == 1 + assert result.plan.count(QueueBatchAddItemStatus.STALE) == 1 + + +def test_batch_add_revalidates_then_atomically_persists_only_eligible_items(tmp_path, monkeypatch): + import juice_lyrics.acquisition.downloader as downloader + import juice_lyrics.acquisition.runner as runner + + monkeypatch.setattr(downloader, "download_to", lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("download ran"))) + monkeypatch.setattr(runner, "run_job", lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("runner ran"))) + jobs_path = tmp_path / "jobs.json" + settings = Settings(music_dir=tmp_path / "music") + selections = ( + _selection(song_id=101, title="First"), + _selection(song_id=202, title="Second"), + _selection(song_id=303, title="Unavailable", downloadable=False), + ) + planned = plan_queue_batch_additions(settings, selections, jobs_path=jobs_path) + assert planned.plan is not None + result = add_batch_to_download_queue(planned.plan, jobs_path=jobs_path) + assert result.status is QueueBatchAddStatus.ADDED + assert result.added_count == 2 + assert result.added_song_ids == ("101", "202") + jobs = JobStore(jobs_path).list() + assert len(jobs) == 1 + assert [entry.item.identifier for entry in jobs[0].items] == ["101", "202"] + assert "1 unavailable" in result.message + download_all = plan_download_all(settings, jobs_path=jobs_path) + assert [item.song_id for item in download_all.eligible] == ["101", "202"] + + repeated = add_batch_to_download_queue(planned.plan, jobs_path=jobs_path) + assert repeated.status is QueueBatchAddStatus.NOTHING_TO_ADD + assert "2 already queued" in repeated.message + assert len(JobStore(jobs_path).list()) == 1 + + +def test_batch_add_store_failure_reports_no_success_or_partial_write(tmp_path): + settings = Settings(music_dir=tmp_path / "music") + planned = plan_queue_batch_additions( + settings, + (_selection(song_id=101, title="First"), _selection(song_id=202, title="Second")), + jobs_path=tmp_path / "jobs.json", + ) + assert planned.plan is not None + + class BrokenStore: + def create(self, items): + tuple(items) + raise PermissionError + + result = add_batch_to_download_queue( + planned.plan, + jobs_path=tmp_path / "jobs.json", + store_factory=lambda path: BrokenStore(), + ) + assert result.status is QueueBatchAddStatus.SAVE_FAILED + assert result.added_count == 0 + assert not (tmp_path / "jobs.json").exists() + + +def test_queue_plan_reports_unavailable_queued_downloaded_and_store_failures(tmp_path): + jobs_path = tmp_path / "jobs.json" + music = tmp_path / "music" + settings = Settings(music_dir=music) + + unavailable = plan_queue_additions(settings, (_selection(downloadable=False),), jobs_path=jobs_path) + assert unavailable.status is QueueAddStatus.MEDIA_UNAVAILABLE + + unresolved = plan_queue_additions( + settings, + (_selection(),), + jobs_path=jobs_path, + resolver=lambda *args, **kwargs: (_ for _ in ()).throw( + ResourceResolutionError("missing safe media path") + ), + ) + assert unresolved.status is QueueAddStatus.RESOLUTION_FAILED + assert unresolved.message == "Unable to resolve download: missing safe media path" + + first = plan_queue_additions(settings, (_selection(),), jobs_path=jobs_path) + assert first.plan is not None + assert add_to_download_queue(first.plan, jobs_path=jobs_path).status is QueueAddStatus.ADDED + queued = plan_queue_additions(settings, (_selection(),), jobs_path=jobs_path) + assert queued.status is QueueAddStatus.ALREADY_QUEUED + + other_jobs = tmp_path / "other.json" + music.mkdir(parents=True) + (music / "Lemon Glow.mp3").write_bytes(b"downloaded") + downloaded = plan_queue_additions(settings, (_selection(),), jobs_path=other_jobs) + assert downloaded.status is QueueAddStatus.ALREADY_DOWNLOADED + + class BrokenStore: + def create(self, items): + raise PermissionError + + failed = add_to_download_queue( + first.plan, + jobs_path=tmp_path / "failure.json", + duplicate_finder=lambda *args, **kwargs: None, + store_factory=lambda path: BrokenStore(), + ) + assert failed.status is QueueAddStatus.SAVE_FAILED + assert "permission denied" in failed.message + + +def _stored_downloads(tmp_path: Path): + jobs_path = tmp_path / "jobs.json" + items = ( + AcquisitionItem( + "101", + "First Song", + "https://example.test/first.mp3", + tmp_path / "music" / "First Song.mp3", + metadata={"artist": "Juice WRLD"}, + ), + AcquisitionItem( + "202", + "Selected Song", + "https://example.test/selected.mp3", + tmp_path / "music" / "Selected Song.mp3", + expected_size=100, + metadata={"artist": "Juice WRLD"}, + ), + ) + job = JobStore(jobs_path).create(items, job_id="durable-job") + return jobs_path, job + + +def test_download_execution_plan_maps_exact_item_and_detects_resume(tmp_path): + jobs_path, job = _stored_downloads(tmp_path) + settings = Settings(music_dir=tmp_path / "music") + + ready = plan_download_execution(settings, f"{job.job_id}:1", jobs_path=jobs_path) + + assert ready.status is DownloadExecutionStatus.READY + assert ready.plan is not None + assert ready.plan.item_index == 1 + assert ready.plan.song_id == "202" + assert ready.plan.destination == tmp_path / "music" / "Selected Song.mp3" + assert ready.plan.action is DownloadExecutionAction.START + + ready.plan.destination.parent.mkdir(parents=True) + ready.plan.destination.with_name("Selected Song.mp3.part").write_bytes(b"partial") + resumed = plan_download_execution(settings, ready.plan.reference, jobs_path=jobs_path) + assert resumed.plan is not None + assert resumed.plan.action is DownloadExecutionAction.RESUME + + missing = plan_download_execution(settings, "durable-job:99", jobs_path=jobs_path) + assert missing.status is DownloadExecutionStatus.NOT_FOUND + + +def test_execute_selected_download_delegates_exactly_one_item_and_reports_progress(tmp_path): + jobs_path, job = _stored_downloads(tmp_path) + settings = Settings(music_dir=tmp_path / "music") + planned = plan_download_execution(settings, f"{job.job_id}:1", jobs_path=jobs_path) + assert planned.plan is not None + progress = [] + integrated = [] + + def integration(item, **kwargs): + integrated.append(item.identifier) + return IntegrationResult(item.destination, message="processed") + + def runner(job, store, *, progress, postprocess, item_indexes, **kwargs): + assert item_indexes == {1} + assert job.items[0].state is AcquisitionState.PENDING + assert job.items[1].state is AcquisitionState.CHECKING_EXISTING + progress(1, 2, 50, 100) + result = AcquisitionResult( + job.items[1].item, + AcquisitionState.COMPLETE, + destination=job.items[1].item.destination, + bytes_written=100, + ) + postprocess(result) + job.record_result(1, result) + store.save(job) + return AcquisitionRunSummary(job.job_id, 1, 0, 0, 1) + + result = execute_selected_download( + settings, + planned.plan, + jobs_path=jobs_path, + runner=runner, + integration=integration, + progress=progress.append, + ) + + assert result.status is DownloadExecutionStatus.COMPLETED + assert integrated == ["202"] + assert [event.status for event in progress] == [ + DownloadExecutionStatus.DOWNLOADING, + DownloadExecutionStatus.DOWNLOADING, + DownloadExecutionStatus.PROCESSING, + ] + assert progress[1].percent == 50 + authoritative = JobStore(jobs_path).get(job.job_id) + assert authoritative is not None + assert authoritative.items[0].state is AcquisitionState.PENDING + assert authoritative.items[1].state is AcquisitionState.COMPLETE + + +def test_execute_selected_download_preserves_structured_failure_and_rejects_second_start(tmp_path): + jobs_path, job = _stored_downloads(tmp_path) + settings = Settings(music_dir=tmp_path / "music") + planned = plan_download_execution(settings, f"{job.job_id}:1", jobs_path=jobs_path) + assert planned.plan is not None + calls = 0 + + def failing_runner(job, store, *, item_indexes, **kwargs): + nonlocal calls + calls += 1 + entry = job.items[1] + entry.state = AcquisitionState.FAILED + entry.failure_stage = AcquisitionFailureStage.VALIDATION + entry.error = "checksum mismatch" + store.save(job) + return AcquisitionRunSummary(job.job_id, 0, 0, 1, 1) + + failed = execute_selected_download( + settings, + planned.plan, + jobs_path=jobs_path, + runner=failing_runner, + ) + second = execute_selected_download( + settings, + planned.plan, + jobs_path=jobs_path, + runner=failing_runner, + ) + + assert failed.status is DownloadExecutionStatus.FAILED + assert failed.message == "File validation failed" + assert failed.error == "checksum mismatch" + assert second.status is DownloadExecutionStatus.RETRY_REQUIRED + assert calls == 1 + + +def test_unexpected_runner_failure_is_persisted_and_exact_destination_is_rechecked(tmp_path): + jobs_path, job = _stored_downloads(tmp_path) + settings = Settings(music_dir=tmp_path / "music") + planned = plan_download_execution(settings, f"{job.job_id}:1", jobs_path=jobs_path) + assert planned.plan is not None + + changed = JobStore(jobs_path).get(job.job_id) + assert changed is not None + changed.items[1].item.destination = tmp_path / "other" / "Unrelated.mp3" + JobStore(jobs_path).save(changed) + wrong_target = execute_selected_download( + settings, + planned.plan, + jobs_path=jobs_path, + runner=lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("runner called")), + ) + assert wrong_target.status is DownloadExecutionStatus.NOT_FOUND + + changed.items[1].item.destination = planned.plan.destination + changed.items[1].state = AcquisitionState.PENDING + JobStore(jobs_path).save(changed) + failed = execute_selected_download( + settings, + planned.plan, + jobs_path=jobs_path, + runner=lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("runner stopped")), + ) + assert failed.status is DownloadExecutionStatus.FAILED + assert failed.error == "runner stopped" + authoritative = JobStore(jobs_path).get(job.job_id) + assert authoritative is not None + assert authoritative.items[1].state is AcquisitionState.FAILED + assert authoritative.items[1].failure_stage is AcquisitionFailureStage.TRANSPORT diff --git a/tests/test_flac_support.py b/tests/test_flac_support.py new file mode 100644 index 0000000..3cb6da5 --- /dev/null +++ b/tests/test_flac_support.py @@ -0,0 +1,372 @@ +from __future__ import annotations + +import json +import struct +from pathlib import Path + +import pytest +from mutagen.flac import FLAC + +from juice_lyrics.backup.manager import backup_file, restore_backup, write_manifest +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.matching import choose_candidate, local_duration, search_title_for +from juice_lyrics.library.media import MediaMetadataError, read_flac_metadata +from juice_lyrics.library.scanner import find_audio_files, find_mp3s +from juice_lyrics.lyrics.engine import embed_lyrics, verify_file +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + get_library_snapshot, +) +from juice_lyrics.services.library_sync import ( + LibrarySyncDependencies, + LibrarySyncOptions, + MatchOutcome, + execute_library_sync, + plan_library_sync, +) +from juice_lyrics.state import sha256_file + + +def _make_flac( + path: Path, + *, + title: str | None = "Rental", + artist: str | None = "Juice WRLD", + album: str | None = "Unreleased", + track_number: str | None = None, + duration: float = 2.0, +) -> Path: + """Create a tiny metadata-capable FLAC container without audio samples.""" + + path.parent.mkdir(parents=True, exist_ok=True) + sample_rate = 44_100 + total_samples = int(sample_rate * duration) + packed = ( + (sample_rate << 44) + | ((2 - 1) << 41) + | ((16 - 1) << 36) + | total_samples + ) + stream_info = ( + struct.pack(">HH", 4096, 4096) + + b"\0" * 6 + + packed.to_bytes(8, "big") + + b"\0" * 16 + ) + path.write_bytes(b"fLaC" + b"\x80" + len(stream_info).to_bytes(3, "big") + stream_info) + tags = FLAC(path) + for key, value in (("TITLE", title), ("ARTIST", artist), ("ALBUM", album), ("TRACKNUMBER", track_number)): + if value is not None: + tags[key] = [value] + if any(value is not None for value in (title, artist, album, track_number)): + tags.save() + return path + + +def _candidate(*, synced: bool = True) -> dict[str, object]: + return { + "id": 101, + "name": "Rental", + "credited_artists": "Juice WRLD", + "album": "Unreleased", + "length": "0:02", + "category": "unreleased", + "synced_lyrics": "[00:00.50] first\n[00:01.20] second" if synced else "", + "lyrics": "first\nsecond", + } + + +def test_recursive_flac_discovery_is_case_insensitive_and_stays_in_root(tmp_path): + root = tmp_path / "Juice WRLD" + lower = _make_flac(root / "Album (v2)" / "Légend's [Mix].flac") + upper = _make_flac(root / "Nested" / "Song.final.v2.FLAC") + mp3 = root / "Still MP3.MP3" + mp3.write_bytes(b"audio") + outside = _make_flac(tmp_path / "outside.flac") + (root / "ignore.aac").write_bytes(b"audio") + + assert find_audio_files(root) == sorted([lower, upper, mp3], key=lambda path: str(path).casefold()) + assert find_mp3s(Settings(music_dir=root)) == find_audio_files(root) + assert outside not in find_audio_files(root) + + +def test_flac_metadata_and_duration_are_read_natively(tmp_path): + path = _make_flac( + tmp_path / "metadata.flac", + title="Rental (v2)", + artist="Juice WRLD", + album="Test Album", + track_number="7/20", + duration=3.25, + ) + + metadata = read_flac_metadata(path) + + assert metadata.title == "Rental (v2)" + assert metadata.artist == "Juice WRLD" + assert metadata.album == "Test Album" + assert metadata.track_number == "7/20" + assert metadata.duration_seconds == pytest.approx(3.25) + assert local_duration(path) == pytest.approx(3.25) + assert search_title_for(path) == "Rental" + + +def test_missing_flac_matching_metadata_is_left_unresolved(tmp_path): + path = _make_flac(tmp_path / "Do Not Guess.flac", title=None, artist=None, album=None) + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path), + dry_run=True, + state_file=tmp_path / "missing-state.json", + ) + dependencies = LibrarySyncDependencies( + searcher=lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("API called")), + ) + + with pytest.raises(MediaMetadataError, match="missing title, artist"): + search_title_for(path) + plan = plan_library_sync(options, dependencies=dependencies) + + assert plan.tracks[0].outcome is MatchOutcome.UNRESOLVED + assert "left unmatched" in (plan.tracks[0].error or "") + + +def test_malformed_flac_is_left_unresolved_instead_of_guessed(tmp_path): + path = tmp_path / "Looks Like Rental.flac" + path.write_bytes(b"not a FLAC stream") + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path), + dry_run=True, + state_file=tmp_path / "missing-state.json", + ) + + plan = plan_library_sync(options, dependencies=LibrarySyncDependencies()) + + assert plan.tracks[0].path == path + assert plan.tracks[0].outcome is MatchOutcome.UNRESOLVED + assert "could not be read" in (plan.tracks[0].error or "") + + +def test_flac_matching_reuses_normal_version_title_and_duration_scoring(tmp_path): + path = _make_flac(tmp_path / "opaque filename.flac", title="Rental (v2)", duration=2.0) + right = {**_candidate(), "name": "Rental (v2)"} + wrong = {**_candidate(), "name": "Rental (v1)"} + + chosen, score, reasons, _ = choose_candidate( + Settings(music_dir=tmp_path), + path, + [wrong, right], + search_title_for(path), + ) + + assert chosen is right + assert score >= 70 + assert "exact version v2" in reasons + assert any(reason.startswith("duration match") for reason in reasons) + + +def test_bandit_collaboration_credit_searches_base_title_and_matches_by_duration(tmp_path): + path = _make_flac( + tmp_path / "opaque.flac", + title="Bandit (with YoungBoy Never Broke Again)", + artist="Juice WRLD, YoungBoy Never Broke Again", + album="Death Race For Love (Bonus Track Version)", + duration=189.322562, + ) + candidate = { + **_candidate(), + "name": "Bandit (feat. YoungBoy Never Broke Again)", + "credited_artists": "Juice WRLD", + "album": "Death Race For Love", + "length": "3:09", + "category": "released", + } + + search_title = search_title_for(path) + chosen, score, reasons, _ = choose_candidate( + Settings(music_dir=tmp_path), path, [candidate], search_title + ) + + assert search_title == "Bandit" + assert chosen is candidate + assert score >= 70 + assert any(reason.startswith("duration match") for reason in reasons) + + +def test_real_flac_with_embedded_plain_and_timed_sidecar_is_healthy_without_state(tmp_path): + path = _make_flac( + tmp_path / "Bandit (with YoungBoy Never Broke Again).flac", + title="Bandit (with YoungBoy Never Broke Again)", + artist="Juice WRLD, YoungBoy Never Broke Again", + album="Death Race For Love (Bonus Track Version)", + duration=189.322562, + ) + embed_lyrics(path, [], "Oh-oh\nYeah") + path.with_suffix(".lrc").write_text( + "[00:05.77]Oh-oh\n[00:10.45]Yeah\n", + encoding="utf-8", + ) + + snapshot = get_library_snapshot( + Settings(music_dir=tmp_path), + state_file=tmp_path / "missing-state.json", + ) + + track = snapshot.tracks[0] + assert track.match_status is LibraryMatchStatus.UNMATCHED + assert track.lyric_status is LibraryLyricStatus.PLAIN + assert track.lrc_status is LibraryLrcStatus.PRESENT + assert track.fully_covered is True + assert track.needs_attention is False + + +def test_flac_plain_embedding_preserves_unrelated_metadata_and_verifies(tmp_path): + path = _make_flac(tmp_path / "Rental.flac") + before_samples = FLAC(path).info.total_samples + audio = FLAC(path) + audio["COMMENT"] = ["keep me"] + audio.save() + + result = embed_lyrics(path, [], "ordinary lyrics") + valid, message = verify_file(path) + updated = FLAC(path) + + assert result == "FLAC_LYRICS" + assert updated["lyrics"] == ["ordinary lyrics"] + assert updated["comment"] == ["keep me"] + assert updated.info.total_samples == before_samples + assert valid is True + assert message.startswith("FLAC LYRICS") + + +def test_synced_flac_embeds_plain_text_without_inventing_embedded_timing(tmp_path): + path = _make_flac(tmp_path / "Rental.flac") + + embed_lyrics(path, [("first", 500), ("second", 1200)], "") + + assert FLAC(path)["lyrics"] == ["first\nsecond"] + assert not any("500" in value or "1200" in value for value in FLAC(path)["lyrics"]) + + +def test_flac_sync_dry_run_writes_nothing(tmp_path): + path = _make_flac(tmp_path / "Album" / "Rental.flac") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {}}), encoding="utf-8") + before = path.read_bytes() + dependencies = LibrarySyncDependencies( + searcher=lambda settings, title, refresh=False: [_candidate()], + ) + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path, lyrics_dir=tmp_path / "central"), + dry_run=True, + rmpc_enabled=True, + state_file=state_file, + ) + + plan = plan_library_sync(options, dependencies=dependencies) + result = execute_library_sync(plan, dependencies=dependencies) + + assert plan.ready_files == 1 + assert plan.tracks[0].lrc_path == path.with_suffix(".lrc") + assert result.updated_files == 0 + assert path.read_bytes() == before + assert not path.with_suffix(".lrc").exists() + assert not (tmp_path / "central").exists() + assert state_file.read_text(encoding="utf-8") == json.dumps({"files": {}}) + + +def test_flac_sync_backs_up_before_mutation_writes_state_sidecar_and_notifies(tmp_path): + music = tmp_path / "music" + path = _make_flac(music / "Album" / "Rental.flac") + pristine = path.read_bytes() + backup_root = tmp_path / "backups" / "run" + state = {"files": {}} + saved: list[dict[str, object]] = [] + notified: list[list[Path]] = [] + + def make_backup_root() -> Path: + backup_root.mkdir(parents=True, exist_ok=True) + return backup_root + + def checked_embed(target: Path, synced, plain) -> str: + assert (backup_root / target.relative_to(music)).read_bytes() == pristine + return embed_lyrics(target, synced, plain) + + dependencies = LibrarySyncDependencies( + searcher=lambda settings, title, refresh=False: [_candidate()], + backup_root_factory=make_backup_root, + embedder=checked_embed, + state_loader=lambda: state, + state_saver=lambda value: saved.append(json.loads(json.dumps(value))), + rmpc_notifier=lambda paths: notified.append(list(paths)) or len(paths), + ) + options = LibrarySyncOptions.from_settings( + Settings(music_dir=music, lyrics_dir=tmp_path / "central"), + rmpc_enabled=True, + ) + + result = execute_library_sync( + plan_library_sync(options, dependencies=dependencies), + dependencies=dependencies, + ) + + sidecar = path.with_suffix(".lrc") + entry = saved[0]["files"]["Album/Rental.flac"] + assert result.updated_files == 1 + assert result.lrc_files_generated == 1 + assert sidecar.is_file() + assert notified == [[sidecar]] + assert entry["lyric_type"] == "FLAC_LYRICS_SYNCED" + assert entry["lrc"] == str(sidecar) + assert entry["sha256"] == sha256_file(path) + assert not (tmp_path / "central").exists() + assert (backup_root / "Album" / "Rental.flac").read_bytes() == pristine + + +def test_flac_status_distinguishes_embedded_lyrics_and_external_lrc(tmp_path): + music = tmp_path / "music" + path = _make_flac(music / "Rental.flac") + embed_lyrics(path, [("line", 500)], "plain representation") + sidecar = path.with_suffix(".lrc") + sidecar.write_text("[00:00.50] line\n", encoding="utf-8") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"Rental.flac": { + "sha256": sha256_file(path), + "song_id": 101, + "api_name": "Rental", + "lyric_type": "FLAC_LYRICS_SYNCED", + "lrc": str(sidecar), + }}}), encoding="utf-8") + + snapshot = get_library_snapshot(Settings(music_dir=music), state_file=state_file) + track = snapshot.tracks[0] + + assert track.media_format == "FLAC" + assert track.title == "Rental" + assert track.artist == "Juice WRLD" + assert track.album == "Unreleased" + assert track.match_status is LibraryMatchStatus.MATCHED + assert track.lyric_status is LibraryLyricStatus.PLAIN + assert track.lrc_status is LibraryLrcStatus.PRESENT + assert track.lrc_path == sidecar + assert track.warning is None + + +def test_flac_and_historical_mp3_backups_restore_together(tmp_path): + music = tmp_path / "music" + flac = _make_flac(music / "Nested" / "Song.FLAC") + mp3 = music / "Old.mp3" + mp3.write_bytes(b"historical mp3") + backup_root = tmp_path / "backups" / "historical" + backup_file(flac, backup_root, music) + backup_file(mp3, backup_root, music) + write_manifest(backup_root, [{"file": str(mp3)}]) + flac.unlink() + mp3.unlink() + + restored = restore_backup(backup_root, music) + + assert restored == 2 + assert FLAC(flac).get("title") == ["Rental"] + assert mp3.read_bytes() == b"historical mp3" diff --git a/tests/test_identity_rebuild.py b/tests/test_identity_rebuild.py new file mode 100644 index 0000000..2c1cbc0 --- /dev/null +++ b/tests/test_identity_rebuild.py @@ -0,0 +1,488 @@ +from __future__ import annotations + +import hashlib +import json +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library import matching +from juice_lyrics.services.identity_rebuild import ( + IdentityChange, + IdentityRebuildDependencies, + IdentityRebuildPlan, + IdentityRebuildResult, + execute_catalogue_identity_rebuild, + plan_catalogue_identity_rebuild, +) +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, +) +from juice_lyrics.state import file_fingerprint, sha256_file + + +def _track(root: Path, relative: str, *, title: str | None = None, album: str = "Album") -> LibraryTrack: + path = root / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(f"audio:{relative}".encode()) + path.with_suffix(".lrc").write_text("[00:01.00]keep\n", encoding="utf-8") + return LibraryTrack( + reference=relative, + path=path, + relative_path=Path(relative), + filename=path.name, + title=title or path.stem, + duration_seconds=180.0, + match_status=LibraryMatchStatus.MATCHED, + matched_title=title or path.stem, + lyric_status=( + LibraryLyricStatus.SYNCED + if path.suffix.casefold() == ".mp3" + else LibraryLyricStatus.PLAIN + ), + lrc_status=LibraryLrcStatus.PRESENT, + lrc_path=path.with_suffix(".lrc"), + state_status=LibraryStateStatus.CURRENT, + artist="Juice WRLD", + album=album, + media_format=path.suffix[1:].upper(), + content_sha256=sha256_file(path), + content_fingerprint=file_fingerprint(path), + ) + + +def _write_state(path: Path, files: dict) -> bytes: + path.write_text(json.dumps({"files": files, "updated": "old", "keep": "top"}), encoding="utf-8") + return path.read_bytes() + + +def _plan(settings: Settings, state_file: Path, tracks: tuple[LibraryTrack, ...], *, stale=()): + raw = state_file.read_bytes() if state_file.exists() else b"" + state = json.loads(raw) if raw else {"files": {}, "updated": None} + existing = sum( + bool(entry.get("song_id") is not None and entry.get("api_name")) + for entry in state.get("files", {}).values() + if isinstance(entry, dict) + ) + return IdentityRebuildPlan( + settings, + state_file, + hashlib.sha256(raw).hexdigest(), + state, + tracks, + tuple(stale), + min(existing, len(tracks)), + ) + + +def test_rebuild_preview_is_read_only_and_reports_current_identity_and_stale_counts(tmp_path): + music = tmp_path / "music" + track = _track(music, "Album/Song.flac") + state_file = tmp_path / "state.json" + stale = "/tmp/pytest-of-someone/pytest-4/Song.mp3" + original = _write_state( + state_file, + { + "Album/Song.flac": {"song_id": 1, "api_name": "Song", "lyric_type": "FLAC_LYRICS"}, + stale: {"song_id": 2, "api_name": "Temporary"}, + }, + ) + snapshot = LibrarySnapshot(music, True, (track,)) + + plan = plan_catalogue_identity_rebuild( + Settings(music_dir=music), + state_file=state_file, + snapshot_provider=lambda *args, **kwargs: snapshot, + ) + + assert plan.current_tracks == 1 + assert plan.existing_identities == 1 + assert plan.currently_unknown == 0 + assert plan.stale_keys == (stale,) + assert state_file.read_bytes() == original + assert not tuple(tmp_path.glob("state.json.pre-identity-rebuild-*.bak")) + + +def test_rebuild_preserves_manual_locks_unless_advanced_override_is_explicit( + tmp_path, +): + music = tmp_path / "music" + track = _track(music, "Album/Manual.flac") + state_file = tmp_path / "state.json" + original = { + "sha256": track.content_sha256, + "song_id": 11, + "api_name": "User Choice", + "identity_source": "manual", + "identity_locked": True, + "lyric_type": "FLAC_LYRICS_PLAIN", + } + _write_state(state_file, {track.reference: original}) + plan = _plan(Settings(music_dir=music), state_file, (track,)) + searches: list[str] = [] + candidate = {"id": 22, "name": "New Automatic Choice"} + deps = IdentityRebuildDependencies( + searcher=lambda *args, **kwargs: searches.append("search") or [candidate], + search_title=lambda path: path.stem, + matcher=lambda *args: (candidate, 100.0, [], []), + ) + + kept = execute_catalogue_identity_rebuild(plan, dependencies=deps) + + assert searches == [] + assert kept.changed_identities == 0 + assert json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ] == original + + override_plan = _plan(Settings(music_dir=music), state_file, (track,)) + replaced = execute_catalogue_identity_rebuild( + override_plan, + dependencies=deps, + include_locked=True, + ) + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ] + assert searches == ["search"] + assert replaced.changed_identities == 1 + assert entry["song_id"] == 22 + assert entry["lyric_type"] == "FLAC_LYRICS_PLAIN" + assert "identity_source" not in entry + assert "identity_locked" not in entry + + +def test_rebuild_does_not_preserve_lock_from_replaced_audio(tmp_path): + music = tmp_path / "music" + track = _track(music, "Changed.mp3") + state_file = tmp_path / "state.json" + _write_state( + state_file, + { + track.reference: { + "sha256": "previous audio", + "song_id": 1, + "api_name": "Old Manual Choice", + "identity_source": "manual", + "identity_locked": True, + } + }, + ) + plan = _plan(Settings(music_dir=music), state_file, (track,)) + candidate = {"id": 2, "name": "Replacement"} + searches: list[str] = [] + + execute_catalogue_identity_rebuild( + plan, + dependencies=IdentityRebuildDependencies( + searcher=lambda *args, **kwargs: searches.append("search") or [candidate], + search_title=lambda path: path.stem, + matcher=lambda *args: (candidate, 100.0, [], []), + ), + ) + + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ] + assert searches == ["search"] + assert entry["song_id"] == 2 + assert "identity_source" not in entry + assert "identity_locked" not in entry + + +def test_rebuild_corrects_live_bandit_and_ten_feet_and_preserves_everything_else(tmp_path, monkeypatch): + music = tmp_path / "music" + bandit = _track( + music, + "Albums/Bandit.flac", + title="Bandit (with YoungBoy Never Broke Again)", + album="Death Race For Love (Bonus Track Version)", + ) + ten_feet = _track( + music, + "Albums/10 Feet.m4a", + title="10 Feet", + album="Death Race For Love (Bonus Track Version)", + ) + audio_before = {track.path: track.path.read_bytes() for track in (bandit, ten_feet)} + lrc_before = {track.lrc_path: track.lrc_path.read_bytes() for track in (bandit, ten_feet)} + state_file = tmp_path / "state.json" + stale = "/tmp/pytest-of-someone/pytest-8/Old.mp3" + original = _write_state( + state_file, + { + str(bandit.relative_path): {"sha256": "bandit", "lyric_type": "FLAC_LYRICS", "lrc": str(bandit.lrc_path), "history": ["keep"]}, + str(ten_feet.relative_path): {"sha256": "ten", "song_id": 96383, "api_name": "10 Feet", "lyric_type": "M4A_LYRICS", "lrc": str(ten_feet.lrc_path)}, + "Historical/Keep.mp3": {"song_id": 55, "api_name": "Historical", "lyric_type": "USLT"}, + stale: {"song_id": 66, "api_name": "Stale"}, + }, + ) + bandit_results = [ + {"id": 96405, "name": bandit.title, "category": "recording_session", "length": ""}, + {"id": 95296, "name": f"{bandit.title} [v1]", "category": "unreleased", "length": "3:12"}, + {"id": 95298, "name": f"{bandit.title} [v4]", "category": "unreleased", "length": "3:12"}, + {"id": 94107, "name": "Bandit (feat. YoungBoy Never Broke Again)", "category": "released", "length": "3:09", "path": "Compilation/Released Discography/15. Death Race For Love (Bonus Track Version)/Bandit.mp3"}, + ] + ten_results = [ + {"id": 94102, "name": "10 Feet", "category": "released", "length": "3:36", "path": "Compilation/Released Discography/11. Death Race For Love/10 Feet.mp3"}, + {"id": 96383, "name": "10 Feet", "category": "recording_session", "length": ""}, + {"id": 95062, "name": "10 Feet (v3)", "category": "unreleased", "length": "3:36"}, + {"id": 94269, "name": "10 Feet (TV Mix) [v1]", "category": "released", "length": "3:36"}, + ] + monkeypatch.setattr(matching, "is_tagged_container", lambda path: True) + monkeypatch.setattr(matching, "tagged_matching_title", lambda path: bandit.title if "Bandit" in path.name else "10 Feet") + monkeypatch.setattr( + matching, + "local_duration", + lambda path: 189.322562 if "Bandit" in path.name else 212.311927, + ) + monkeypatch.setattr(matching, "local_album", lambda path: bandit.album if "Bandit" in path.name else ten_feet.album) + dependencies = IdentityRebuildDependencies( + searcher=lambda settings, query, refresh=False: bandit_results if query == "Bandit" else ten_results, + matcher=matching.choose_candidate, + search_title=lambda path: "Bandit" if "Bandit" in path.name else "10 Feet", + ) + + result = execute_catalogue_identity_rebuild( + _plan(Settings(music_dir=music), state_file, (bandit, ten_feet), stale=(stale,)), + dependencies=dependencies, + ) + saved = json.loads(state_file.read_text(encoding="utf-8")) + + assert saved["files"][str(bandit.relative_path)]["song_id"] == 94107 + assert saved["files"][str(ten_feet.relative_path)]["song_id"] == 94102 + assert saved["files"][str(ten_feet.relative_path)]["lyric_type"] == "M4A_LYRICS" + assert saved["files"][str(bandit.relative_path)]["history"] == ["keep"] + assert saved["files"]["Historical/Keep.mp3"]["song_id"] == 55 + assert saved["files"][stale]["song_id"] == 66 + assert saved["keep"] == "top" + assert result.matched == 2 + assert result.unknown == 0 + assert result.changed_identities == 2 + assert result.stale_ignored == 1 + assert {(change.old_song_id, change.new_song_id) for change in result.changes} == {(None, 94107), (96383, 94102)} + assert result.backup_path is not None and result.backup_path.read_bytes() == original + assert all(path.read_bytes() == value for path, value in audio_before.items()) + assert all(path.read_bytes() == value for path, value in lrc_before.items()) + assert not (tmp_path / "backups").exists() + + +@pytest.mark.parametrize("relative", ["Song.mp3", "Nested/Song.FLAC", "Nested/Song.M4A"]) +def test_rebuild_forces_current_matcher_for_every_supported_format(tmp_path, relative): + music = tmp_path / "music" + track = _track(music, relative, title="Song") + state_file = tmp_path / "state.json" + _write_state(state_file, {relative: {"song_id": 1, "api_name": "Wrong", "lyric_type": "keep"}}) + calls = [] + dependencies = IdentityRebuildDependencies( + searcher=lambda settings, query, refresh=False: calls.append(query) or [{"id": 2, "name": "Song"}], + search_title=lambda path: "Song", + matcher=lambda settings, path, results, query: (results[0], 100.0, [], []), + ) + + result = execute_catalogue_identity_rebuild( + _plan(Settings(music_dir=music), state_file, (track,)), dependencies=dependencies + ) + saved = json.loads(state_file.read_text(encoding="utf-8"))["files"][relative] + + assert calls == ["Song"] + assert saved["song_id"] == 2 + assert saved["api_name"] == "Song" + assert saved["lyric_type"] == "keep" + assert result.changed_identities == 1 + + +def test_correct_identity_stays_unchanged_and_ambiguous_identity_becomes_unknown(tmp_path): + music = tmp_path / "music" + correct = _track(music, "Correct.mp3") + ambiguous = _track(music, "Ambiguous.flac") + state_file = tmp_path / "state.json" + _write_state( + state_file, + { + "Correct.mp3": {"song_id": 1, "api_name": "Correct", "lyric_type": "SYLT"}, + "Ambiguous.flac": {"song_id": 9, "api_name": "Wrong", "lyric_type": "FLAC_LYRICS"}, + }, + ) + dependencies = IdentityRebuildDependencies( + searcher=lambda settings, query, refresh=False: [{"id": 1, "name": "Correct"}] if query == "Correct" else [], + search_title=lambda path: path.stem, + matcher=lambda settings, path, results, query: ((results[0], 100.0, [], []) if results else (None, 0.0, [], [])), + ) + + result = execute_catalogue_identity_rebuild( + _plan(Settings(music_dir=music), state_file, (correct, ambiguous)), + dependencies=dependencies, + ) + files = json.loads(state_file.read_text(encoding="utf-8"))["files"] + + assert files["Correct.mp3"]["song_id"] == 1 + assert "song_id" not in files["Ambiguous.flac"] + assert "api_name" not in files["Ambiguous.flac"] + assert files["Ambiguous.flac"]["lyric_type"] == "FLAC_LYRICS" + assert result.matched == 1 + assert result.unknown == 1 + assert result.changed_identities == 1 + assert result.unchanged_identities == 1 + + +def test_broad_catalogue_outage_aborts_without_backup_or_state_change(tmp_path): + music = tmp_path / "music" + tracks = (_track(music, "One.mp3"), _track(music, "Two.flac")) + state_file = tmp_path / "state.json" + original = _write_state( + state_file, + {track.reference: {"song_id": index, "api_name": track.title} for index, track in enumerate(tracks, 1)}, + ) + dependencies = IdentityRebuildDependencies( + searcher=lambda *args, **kwargs: (_ for _ in ()).throw(OSError("offline")), + search_title=lambda path: path.stem, + ) + + result = execute_catalogue_identity_rebuild( + _plan(Settings(music_dir=music), state_file, tracks), dependencies=dependencies + ) + + assert result.aborted is True + assert result.failed_preserved == 2 + assert result.backup_path is None + assert state_file.read_bytes() == original + + +def test_individual_failure_preserves_old_identity_while_other_track_rebuilds(tmp_path): + music = tmp_path / "music" + failed = _track(music, "Failed.mp3") + repaired = _track(music, "Repaired.flac") + state_file = tmp_path / "state.json" + _write_state( + state_file, + { + "Failed.mp3": {"song_id": 1, "api_name": "Keep"}, + "Repaired.flac": {"song_id": 2, "api_name": "Wrong"}, + }, + ) + + def search(settings, query, refresh=False): + if query == "Failed": + raise TimeoutError("one request timed out") + return [{"id": 3, "name": "Repaired"}] + + result = execute_catalogue_identity_rebuild( + _plan(Settings(music_dir=music), state_file, (failed, repaired)), + dependencies=IdentityRebuildDependencies( + searcher=search, + search_title=lambda path: path.stem, + matcher=lambda settings, path, results, query: (results[0], 100.0, [], []), + ), + ) + files = json.loads(state_file.read_text(encoding="utf-8"))["files"] + + assert files["Failed.mp3"]["song_id"] == 1 + assert files["Repaired.flac"]["song_id"] == 3 + assert result.failed_preserved == 1 + assert result.changed_identities == 1 + + +def test_atomic_write_failure_preserves_original_and_complete_safety_backup(tmp_path): + music = tmp_path / "music" + track = _track(music, "Song.m4a") + state_file = tmp_path / "state.json" + original = _write_state(state_file, {"Song.m4a": {"song_id": 1, "api_name": "Old"}}) + plan = _plan(Settings(music_dir=music), state_file, (track,)) + + with pytest.raises(OSError, match="disk full"): + execute_catalogue_identity_rebuild( + plan, + dependencies=IdentityRebuildDependencies( + searcher=lambda *args, **kwargs: [{"id": 2, "name": "Song"}], + search_title=lambda path: "Song", + matcher=lambda settings, path, results, query: (results[0], 100.0, [], []), + state_writer=lambda path, state: (_ for _ in ()).throw(OSError("disk full")), + ), + ) + + assert state_file.read_bytes() == original + backups = tuple(tmp_path.glob("state.json.pre-identity-rebuild-*.bak")) + assert len(backups) == 1 + assert backups[0].read_bytes() == original + + +def test_rebuild_refuses_stale_preview_before_contacting_catalogue(tmp_path): + music = tmp_path / "music" + track = _track(music, "Song.mp3") + state_file = tmp_path / "state.json" + _write_state(state_file, {"Song.mp3": {"song_id": 1, "api_name": "Old"}}) + plan = _plan(Settings(music_dir=music), state_file, (track,)) + state_file.write_text('{"files": {}, "changed": true}', encoding="utf-8") + calls = [] + + with pytest.raises(RuntimeError, match="changed after the rebuild preview"): + execute_catalogue_identity_rebuild( + plan, + dependencies=IdentityRebuildDependencies( + searcher=lambda *args, **kwargs: calls.append(True) or [], + ), + ) + + assert calls == [] + + +def test_cli_rebuild_preview_requires_yes_and_apply_reports_audit(tmp_path, monkeypatch, capsys): + from juice_lyrics import cli + + music = tmp_path / "music" + track = _track(music, "10 Feet.flac") + state_file = tmp_path / "state.json" + _write_state(state_file, {track.reference: {"song_id": 96383, "api_name": "10 Feet"}}) + plan = _plan(Settings(music_dir=music), state_file, (track,)) + result = IdentityRebuildResult( + 1, + 1, + 0, + 1, + 0, + 0, + 0, + (IdentityChange(track.relative_path, 96383, "10 Feet", 94102, "10 Feet"),), + (), + tmp_path / "state.backup", + ) + executions = [] + monkeypatch.setattr(cli, "plan_catalogue_identity_rebuild", lambda *args, **kwargs: plan) + monkeypatch.setattr( + cli, + "execute_catalogue_identity_rebuild", + lambda value, **kwargs: executions.append((value, kwargs)) or result, + ) + + preview_args = cli.build_parser().parse_args(["state", "rebuild-identities"]) + assert cli.command_state(preview_args, plan.settings, False) == 0 + assert not executions + assert "No changes made" in capsys.readouterr().out + + apply_args = cli.build_parser().parse_args( + ["state", "rebuild-identities", "--yes", "--details", "--refresh"] + ) + assert cli.command_state(apply_args, plan.settings, False) == 0 + output = capsys.readouterr().out + assert executions == [(plan, {"refresh": True, "include_locked": False})] + assert "96383 (10 Feet) -> 94102 (10 Feet)" in output + assert "Audio, embedded lyrics, sidecars, and rmpc configuration were not changed" in output + + override_args = cli.build_parser().parse_args( + ["state", "rebuild-identities", "--yes", "--include-locked"] + ) + assert cli.command_state(override_args, plan.settings, False) == 0 + assert executions[-1] == ( + plan, + {"refresh": False, "include_locked": True}, + ) diff --git a/tests/test_library_duplicates.py b/tests/test_library_duplicates.py new file mode 100644 index 0000000..96da677 --- /dev/null +++ b/tests/test_library_duplicates.py @@ -0,0 +1,194 @@ +from __future__ import annotations + +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.services.library_duplicates import ( + DuplicateConfidence, + detect_library_duplicates, +) +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, +) + + +def _track( + root: Path, + name: str, + *, + title: str = "Song", + artist: str | None = "Juice WRLD", + duration: float | None = 180.0, + digest: str | None = None, + song_id=None, +) -> LibraryTrack: + path = root / name + return LibraryTrack( + reference=name, + path=path, + relative_path=Path(name), + filename=path.name, + title=title, + duration_seconds=duration, + match_status=( + LibraryMatchStatus.MATCHED + if song_id is not None + else LibraryMatchStatus.UNMATCHED + ), + matched_title=title if song_id is not None else None, + lyric_status=( + LibraryLyricStatus.SYNCED + if path.suffix.casefold() == ".mp3" + else LibraryLyricStatus.PLAIN + ), + lrc_status=LibraryLrcStatus.PRESENT, + lrc_path=path.with_suffix(".lrc"), + state_status=LibraryStateStatus.CURRENT, + artist=artist, + album="Album", + media_format=path.suffix[1:].upper(), + content_sha256=digest, + catalogue_id=song_id, + ) + + +def _report(root: Path, *tracks: LibraryTrack, tolerance: float = 3.0): + return detect_library_duplicates( + LibrarySnapshot(root, True, tracks), + duration_tolerance=tolerance, + ) + + +def test_exact_duplicate_audio_uses_existing_sha_without_file_reads(tmp_path): + first = _track(tmp_path, "A/Song.mp3", digest="same", song_id=1) + second = _track( + tmp_path, + "B/Wrong tags.flac", + title="Different metadata (Live)", + artist="Someone Else", + duration=999.0, + digest="same", + song_id=2, + ) + + report = _report(tmp_path, first, second) + + assert len(report.groups) == 1 + assert report.groups[0].confidence is DuplicateConfidence.EXACT + assert "same SHA-256" in report.groups[0].evidence[0] + assert report.file_count == 2 + + +@pytest.mark.parametrize("suffix", [".mp3", ".flac", ".m4a"]) +def test_probable_same_catalogue_recording_is_format_neutral(tmp_path, suffix): + first = _track(tmp_path, f"One{suffix}", digest="one", song_id=94107) + second = _track(tmp_path, f"Two{suffix}", duration=181.0, digest="two", song_id=94107) + + group = _report(tmp_path, first, second).groups[0] + + assert group.confidence is DuplicateConfidence.PROBABLE + assert "Same catalogue identity (94107)" in group.evidence + assert "Durations within 1.00s" in group.evidence + + +def test_probable_metadata_match_requires_title_artist_and_close_duration(tmp_path): + first = _track( + tmp_path, + "Album/Bandit.flac", + title="Bandit (with YoungBoy Never Broke Again)", + artist="Juice WRLD, YoungBoy Never Broke Again", + digest="one", + ) + second = _track( + tmp_path, + "Singles/Bandit.m4a", + title="Bandit (feat. YoungBoy Never Broke Again)", + artist="YoungBoy Never Broke Again & Juice WRLD", + duration=181.5, + digest="two", + ) + + group = _report(tmp_path, first, second).groups[0] + + assert group.confidence is DuplicateConfidence.PROBABLE + assert "Compatible title and recording variant" in group.evidence + assert "Same artist metadata" in group.evidence + + +@pytest.mark.parametrize( + ("ordinary", "variant"), + [ + ("Song", "Song (v1)"), + ("Song (v1)", "Song (v2)"), + ("Song", "Song (Live)"), + ("Song", "Song Remix"), + ("Song", "Song (Recording Session)"), + ("Song", "Song Extended"), + ("Song", "Song (TV Mix)"), + ], +) +def test_distinct_versions_are_not_probable_duplicates_even_with_same_identity( + tmp_path, ordinary, variant +): + first = _track(tmp_path, "One.mp3", title=ordinary, digest="one", song_id=10) + second = _track(tmp_path, "Two.mp3", title=variant, digest="two", song_id=10) + + assert _report(tmp_path, first, second).groups == () + + +def test_conflicting_catalogue_ids_or_distant_duration_prevent_probable_group(tmp_path): + first = _track(tmp_path, "One.mp3", digest="one", song_id=10) + conflicting = _track(tmp_path, "Two.mp3", digest="two", song_id=11) + distant = _track(tmp_path, "Three.mp3", duration=190.0, digest="three", song_id=10) + + assert _report(tmp_path, first, conflicting).groups == () + assert _report(tmp_path, first, distant).groups == () + + +def test_unknown_duration_can_use_same_identity_but_not_metadata_alone(tmp_path): + known = _track(tmp_path, "Known.mp3", digest="one", song_id=10) + identity_unknown = _track( + tmp_path, "Identity.mp3", duration=None, digest="two", song_id=10 + ) + metadata_unknown = _track( + tmp_path, "Metadata.mp3", duration=None, digest="three", song_id=None + ) + + assert len(_report(tmp_path, known, identity_unknown).groups) == 1 + assert _report(tmp_path, known, metadata_unknown).groups == () + + +def test_all_members_must_be_pairwise_compatible_not_duration_chain(tmp_path): + tracks = ( + _track(tmp_path, "A.mp3", duration=180.0, digest="a"), + _track(tmp_path, "B.mp3", duration=182.5, digest="b"), + _track(tmp_path, "C.mp3", duration=185.0, digest="c"), + ) + + report = _report(tmp_path, *tracks, tolerance=3.0) + + assert len(report.groups) == 1 + assert len(report.groups[0].tracks) == 2 + + +def test_no_evidence_returns_empty_report_and_does_not_touch_files(tmp_path): + audio = tmp_path / "Unique.mp3" + sidecar = tmp_path / "Unique.lrc" + audio.write_bytes(b"audio") + sidecar.write_bytes(b"[00:01.00]keep") + track = _track(tmp_path, audio.name, title="Unique", digest=None) + + report = _report(tmp_path, track) + + assert report.groups == () + assert audio.read_bytes() == b"audio" + assert sidecar.read_bytes() == b"[00:01.00]keep" diff --git a/tests/test_library_identity.py b/tests/test_library_identity.py new file mode 100644 index 0000000..af2918a --- /dev/null +++ b/tests/test_library_identity.py @@ -0,0 +1,265 @@ +from __future__ import annotations + +import json +from dataclasses import replace +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.matching import choose_candidate +from juice_lyrics.services.library_identity import ( + IdentityBackfillDependencies, + backfill_catalogue_identities, +) +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibraryStateStatus, + LibraryTrack, +) + + +def _track(root: Path, relative: str, *, healthy: bool = False) -> LibraryTrack: + path = root / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(f"audio:{relative}".encode()) + if healthy: + path.with_suffix(".lrc").write_text("[00:05.77]Oh-oh\n", encoding="utf-8") + suffix = path.suffix.casefold() + lyric = ( + LibraryLyricStatus.SYNCED + if suffix == ".mp3" and healthy + else LibraryLyricStatus.PLAIN if healthy else LibraryLyricStatus.NONE + ) + return LibraryTrack( + reference=relative, + path=path, + relative_path=Path(relative), + filename=path.name, + title=path.stem, + duration_seconds=189.0, + match_status=LibraryMatchStatus.UNMATCHED, + matched_title=None, + lyric_status=lyric, + lrc_status=LibraryLrcStatus.PRESENT if healthy else LibraryLrcStatus.NONE, + lrc_path=path.with_suffix(".lrc") if healthy else None, + state_status=LibraryStateStatus.NEW, + media_format=suffix.removeprefix(".").upper(), + ) + + +def _candidate(title: str, *, song_id: int = 101, length: str = "3:09") -> dict: + return { + "id": song_id, + "name": title, + "length": length, + "category": "unreleased", + } + + +@pytest.mark.parametrize("relative", ["New.mp3", "Album/New.FLAC", "Album/New.M4A"]) +def test_new_supported_format_without_state_is_identified_and_persisted( + tmp_path, monkeypatch, relative +): + track = _track(tmp_path, relative) + state_file = tmp_path / "state.json" + calls = [] + monkeypatch.setattr("juice_lyrics.library.matching.local_duration", lambda path: 189.0) + monkeypatch.setattr("juice_lyrics.library.matching.local_album", lambda path: None) + monkeypatch.setattr("juice_lyrics.library.matching.tagged_matching_title", lambda path: "New") + dependencies = IdentityBackfillDependencies( + searcher=lambda settings, query, refresh=False: calls.append(query) or [_candidate("New")], + search_title=lambda path: "New", + ) + + result = backfill_catalogue_identities( + Settings(music_dir=tmp_path), + (track,), + state_file=state_file, + dependencies=dependencies, + ) + saved = json.loads(state_file.read_text(encoding="utf-8"))["files"][relative] + + assert result.identified == 1 + assert calls == ["New"] + assert saved["song_id"] == 101 + assert saved["api_name"] == "New" + assert saved["sha256"] + assert "lyric_type" not in saved + assert "lrc" not in saved + + +@pytest.mark.parametrize( + ("local_title", "query", "candidate_title", "length"), + [ + ( + "Bandit (with YoungBoy Never Broke Again)", + "Bandit", + "Bandit (feat. YoungBoy Never Broke Again)", + "3:09", + ), + ("10 Feet", "10 Feet", "10 Feet", "3:09"), + ], +) +def test_released_mainstream_fixture_is_identified_conservatively( + tmp_path, monkeypatch, local_title, query, candidate_title, length +): + track = _track(tmp_path, f"{local_title}.flac") + track = replace(track, title=local_title) + candidate = _candidate(candidate_title, length=length) + candidate["category"] = "released" + monkeypatch.setattr("juice_lyrics.library.matching.local_duration", lambda path: 189.32) + monkeypatch.setattr( + "juice_lyrics.library.matching.tagged_matching_title", + lambda path: local_title, + ) + dependencies = IdentityBackfillDependencies( + searcher=lambda settings, value, refresh=False: [candidate], + search_title=lambda path: query, + matcher=choose_candidate, + ) + + result = backfill_catalogue_identities( + Settings(music_dir=tmp_path), + (track,), + state_file=tmp_path / "state.json", + dependencies=dependencies, + ) + + assert result.identified == 1 + + +def test_persisted_identity_is_reused_without_search(tmp_path): + track = _track(tmp_path, "Nested/Song.m4a") + state_file = tmp_path / "state.json" + dependencies = IdentityBackfillDependencies( + searcher=lambda settings, query, refresh=False: [_candidate("Song")], + search_title=lambda path: "Song", + matcher=lambda *args: (_candidate("Song"), 100.0, [], []), + ) + first = backfill_catalogue_identities( + Settings(music_dir=tmp_path), (track,), state_file=state_file, dependencies=dependencies + ) + dependencies.searcher = lambda *args, **kwargs: (_ for _ in ()).throw( + AssertionError("catalogue searched again") + ) + second = backfill_catalogue_identities( + Settings(music_dir=tmp_path), (track,), state_file=state_file, dependencies=dependencies + ) + + assert first.identified == 1 + assert second.reused == 1 + assert second.identified == 0 + + +def test_changed_audio_does_not_reuse_old_catalogue_identity(tmp_path): + track = _track(tmp_path / "music", "Album/Song.flac") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"Album/Song.flac": { + "sha256": "old-audio-hash", "song_id": 7, "api_name": "Wrong Song", + "lyric_type": "FLAC_LYRICS_PLAIN", + }}}), encoding="utf-8") + searches = [] + dependencies = IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: searches.append(1) or [_candidate("Song", song_id=8)], + search_title=lambda path: "Song", + matcher=lambda *args: (_candidate("Song", song_id=8), 100.0, [], []), + ) + + result = backfill_catalogue_identities( + Settings(music_dir=tmp_path / "music"), (track,), + state_file=state_file, dependencies=dependencies, + ) + + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"]["Album/Song.flac"] + assert searches == [1] + assert result.reused == 0 + assert result.identified == 1 + assert entry["song_id"] == 8 + assert entry["lyric_type"] == "FLAC_LYRICS_PLAIN" + + +def test_backfill_does_not_overwrite_state_changed_during_search(tmp_path): + track = _track(tmp_path / "music", "Song.mp3") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"Other.mp3": {"lyric_type": "USLT"}}}), encoding="utf-8") + + def searcher(*args, **kwargs): + state_file.write_text(json.dumps({"files": { + "Other.mp3": {"lyric_type": "SYLT", "lrc": "Other.lrc"}, + }}), encoding="utf-8") + return [_candidate("Song")] + + dependencies = IdentityBackfillDependencies( + searcher=searcher, + search_title=lambda path: "Song", + matcher=lambda *args: (_candidate("Song"), 100.0, [], []), + ) + + with pytest.raises(RuntimeError, match="changed during catalogue identification"): + backfill_catalogue_identities( + Settings(music_dir=tmp_path / "music"), (track,), + state_file=state_file, dependencies=dependencies, + ) + saved = json.loads(state_file.read_text(encoding="utf-8"))["files"] + assert saved["Other.mp3"] == {"lyric_type": "SYLT", "lrc": "Other.lrc"} + assert "Song.mp3" not in saved + + +@pytest.mark.parametrize("ambiguous", [True, False]) +def test_ambiguous_or_duration_incompatible_candidate_remains_unknown( + tmp_path, monkeypatch, ambiguous +): + track = _track(tmp_path, "Song.flac") + monkeypatch.setattr("juice_lyrics.library.matching.local_duration", lambda path: 189.0) + monkeypatch.setattr("juice_lyrics.library.matching.tagged_matching_title", lambda path: "Song") + candidates = ( + [_candidate("Song", song_id=1), _candidate("Song", song_id=2)] + if ambiguous + else [_candidate("Song", length="4:30")] + ) + dependencies = IdentityBackfillDependencies( + searcher=lambda settings, query, refresh=False: candidates, + search_title=lambda path: "Song", + ) + state_file = tmp_path / "state.json" + + result = backfill_catalogue_identities( + Settings(music_dir=tmp_path), (track,), state_file=state_file, dependencies=dependencies + ) + + assert result.unknown == 1 + assert result.identified == 0 + assert not state_file.exists() + + +def test_api_failure_preserves_healthy_audio_lrc_and_other_configuration(tmp_path): + track = _track(tmp_path / "music", "Bandit.flac", healthy=True) + audio_before = track.path.read_bytes() + lrc_before = track.path.with_suffix(".lrc").read_bytes() + rmpc = tmp_path / "rmpc.ron" + rmpc.write_text("keep", encoding="utf-8") + dependencies = IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: (_ for _ in ()).throw(OSError("offline")), + search_title=lambda path: "Bandit", + ) + + result = backfill_catalogue_identities( + Settings(music_dir=tmp_path / "music"), + (track,), + state_file=tmp_path / "state.json", + dependencies=dependencies, + ) + + assert result.failed == 1 + assert track.fully_covered is True + assert track.needs_attention is False + assert track.path.read_bytes() == audio_before + assert track.path.with_suffix(".lrc").read_bytes() == lrc_before + assert rmpc.read_text(encoding="utf-8") == "keep" + assert not (tmp_path / "backups").exists() diff --git a/tests/test_library_index_sync.py b/tests/test_library_index_sync.py new file mode 100644 index 0000000..3af03cc --- /dev/null +++ b/tests/test_library_index_sync.py @@ -0,0 +1,433 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.media import AudioMetadata +from juice_lyrics.services.library_identity import IdentityBackfillDependencies +from juice_lyrics.services.library_index_sync import LibraryIndexSyncDependencies, sync_library_index +from juice_lyrics.services.library_status import LibraryLrcStatus, LibraryMatchStatus, get_library_snapshot +from juice_lyrics.state import sha256_file + + +def _dependencies(state_file, *, searcher, counts): + def snapshot(settings, *, previous_snapshot=None, state_file=state_file): + return get_library_snapshot( + settings, state_file=state_file, previous_snapshot=previous_snapshot, + verifier=lambda path: (False, "no lyrics"), + duration_reader=lambda path: 180.0, + metadata_reader=lambda path: _metadata(path, counts), + hasher=lambda path: _hash(path, counts), + ) + + def writer(path, state): + from juice_lyrics.state import write_state_file + counts["writes"] += 1 + write_state_file(path, state) + + return LibraryIndexSyncDependencies( + snapshot_provider=snapshot, + identity=IdentityBackfillDependencies( + searcher=searcher, + search_title=lambda path: path.stem, + matcher=lambda settings, path, results, query: ( + results[0] if len(results) == 1 else None, 100.0, [], [] + ), + hasher=lambda path: _hash(path, counts), + ), + state_writer=writer, + hasher=lambda path: _hash(path, counts), + ) + + +def _metadata(path, counts): + counts["metadata"] += 1 + return AudioMetadata(path.stem, "Juice WRLD", "Album", 180.0) + + +def _hash(path, counts): + counts["hashes"] += 1 + return sha256_file(path) + + +def _counts(): + return {"metadata": 0, "hashes": 0, "writes": 0, "searches": 0} + + +@pytest.mark.parametrize("suffix", [".mp3", ".FLAC", ".M4A"]) +def test_new_audio_is_discovered_identified_and_unchanged_repeat_skips_work(tmp_path, suffix): + music = tmp_path / "music" + path = music / "Nested" / f"Song{suffix}" + path.parent.mkdir(parents=True) + path.write_bytes(b"audio") + state_file = tmp_path / "state.json" + counts = _counts() + + def searcher(settings, query, refresh=False): + counts["searches"] += 1 + return [{"id": 101, "name": "Song"}] + + deps = _dependencies(state_file, searcher=searcher, counts=counts) + settings = Settings(music_dir=music) + first = sync_library_index(settings, state_file=state_file, dependencies=deps) + assert first.new == 1 and first.identified == 1 + assert first.snapshot.tracks[0].match_status is LibraryMatchStatus.MATCHED + assert json.loads(state_file.read_text(encoding="utf-8"))["files"][f"Nested/Song{suffix}"]["song_id"] == 101 + before = counts.copy() + + second = sync_library_index( + settings, previous_snapshot=first.snapshot, state_file=state_file, dependencies=deps + ) + + assert second.summary == "Local library is up to date" + assert counts == before + + saved = json.loads(state_file.read_text(encoding="utf-8")) + saved["unrelated_custom_state"] = {"keep": True} + state_file.write_text(json.dumps(saved), encoding="utf-8") + before_unrelated_change = counts.copy() + + third = sync_library_index( + settings, + previous_snapshot=second.snapshot, + state_file=state_file, + dependencies=deps, + ) + + assert third.summary == "Local library is up to date" + assert counts == before_unrelated_change + assert json.loads(state_file.read_text(encoding="utf-8"))["unrelated_custom_state"] == { + "keep": True + } + + +def test_changed_audio_replaces_stale_identity_and_ambiguous_stays_unknown(tmp_path): + music = tmp_path / "music" + music.mkdir() + path = music / "Song.mp3" + path.write_bytes(b"old audio") + state_file = tmp_path / "state.json" + counts = _counts() + candidates = [{"id": 1, "name": "Old"}] + deps = _dependencies(state_file, searcher=lambda *args, **kwargs: candidates, counts=counts) + settings = Settings(music_dir=music) + first = sync_library_index(settings, state_file=state_file, dependencies=deps) + old_state = json.loads(state_file.read_text(encoding="utf-8")) + old_state["files"]["Song.mp3"].update({ + "lyric_type": "USLT", + "lrc": "old.lrc", + "identity_source": "manual", + "identity_locked": True, + }) + state_file.write_text(json.dumps(old_state), encoding="utf-8") + path.write_bytes(b"new audio") + candidates[:] = [{"id": 2, "name": "New"}] + + changed = sync_library_index(settings, previous_snapshot=first.snapshot, state_file=state_file, dependencies=deps) + assert changed.changed == 1 and changed.identified == 1 + changed_entry = json.loads(state_file.read_text(encoding="utf-8"))["files"]["Song.mp3"] + assert changed_entry["song_id"] == 2 + assert "lyric_type" not in changed_entry and "lrc" not in changed_entry + assert "identity_source" not in changed_entry + assert "identity_locked" not in changed_entry + path.write_bytes(b"third audio") + candidates[:] = [{"id": 3, "name": "A"}, {"id": 4, "name": "B"}] + + ambiguous = sync_library_index(settings, previous_snapshot=changed.snapshot, state_file=state_file, dependencies=deps) + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"]["Song.mp3"] + assert ambiguous.changed == 1 and ambiguous.unknown == 1 + assert ambiguous.snapshot.tracks[0].match_status is LibraryMatchStatus.UNMATCHED + assert "song_id" not in entry and "api_name" not in entry + + +@pytest.mark.parametrize("after_restart", [False, True]) +def test_removed_active_entry_is_retired_but_historical_custom_state_survives(tmp_path, after_restart): + music = tmp_path / "music" + music.mkdir() + path = music / "Song.mp3" + path.write_bytes(b"audio") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"Old Historical.mp3": {"song_id": 9}}, "custom": 42}), encoding="utf-8") + deps = _dependencies(state_file, searcher=lambda *args, **kwargs: [{"id": 1, "name": "Song"}], counts=_counts()) + settings = Settings(music_dir=music) + first = sync_library_index(settings, state_file=state_file, dependencies=deps) + path.unlink() + + second = sync_library_index( + settings, + previous_snapshot=None if after_restart else first.snapshot, + state_file=state_file, + dependencies=deps, + ) + saved = json.loads(state_file.read_text(encoding="utf-8")) + assert second.removed == 1 and second.snapshot.total_track_count == 0 + assert saved["files"]["Song.mp3"]["library_removed_at"] + assert saved["files"]["Song.mp3"]["song_id"] == 1 + assert saved["library_sync_paths"] == [] + assert saved["files"]["Old Historical.mp3"] == {"song_id": 9} + assert saved["custom"] == 42 + + +def test_offline_sync_preserves_state_and_local_health(tmp_path): + music = tmp_path / "music" + music.mkdir() + path = music / "Song.mp3" + path.write_bytes(b"audio") + state_file = tmp_path / "state.json" + original = {"files": {"Song.mp3": {"sha256": "old", "song_id": 7, "api_name": "Old"}}, "custom": 42} + state_file.write_text(json.dumps(original), encoding="utf-8") + before = state_file.read_bytes() + deps = _dependencies( + state_file, + searcher=lambda *args, **kwargs: (_ for _ in ()).throw(OSError("offline")), + counts=_counts(), + ) + + result = sync_library_index(Settings(music_dir=music), state_file=state_file, dependencies=deps) + + assert result.error is not None and result.snapshot.total_track_count == 1 + assert "Catalogue identification unavailable" in result.summary + assert "1 changed pending" in result.summary + assert "1 catalogue unknown" in result.summary + assert result.snapshot.tracks[0].match_status is LibraryMatchStatus.UNMATCHED + assert state_file.read_bytes() == before + assert path.read_bytes() == b"audio" + + +def test_malformed_state_is_not_overwritten(tmp_path): + music = tmp_path / "music" + music.mkdir() + (music / "Song.mp3").write_bytes(b"audio") + state_file = tmp_path / "state.json" + state_file.write_text("{broken", encoding="utf-8") + before = state_file.read_bytes() + + with pytest.raises(RuntimeError, match="malformed"): + sync_library_index(Settings(music_dir=music), state_file=state_file) + assert state_file.read_bytes() == before + + +def test_empty_search_stays_unknown_and_is_not_repeated_within_cache_ttl(tmp_path): + music = tmp_path / "music" + music.mkdir() + path = music / "Unknown.flac" + path.write_bytes(b"audio") + state_file = tmp_path / "state.json" + counts = _counts() + + def searcher(*args, **kwargs): + counts["searches"] += 1 + return [] + + deps = _dependencies(state_file, searcher=searcher, counts=counts) + settings = Settings(music_dir=music) + first = sync_library_index(settings, state_file=state_file, dependencies=deps) + saved = json.loads(state_file.read_text(encoding="utf-8"))["files"]["Unknown.flac"] + assert first.unknown == 1 and "song_id" not in saved + assert saved["catalogue_checked_at"] + before = counts.copy() + + second = sync_library_index(settings, previous_snapshot=first.snapshot, state_file=state_file, dependencies=deps) + + assert second.unknown == 1 + assert second.summary == "Local library up to date · 1 catalogue unknown" + assert counts == before + assert path.read_bytes() == b"audio" + + +def test_normal_sync_preserves_valid_manual_lock_without_search(tmp_path): + music = tmp_path / "music" + music.mkdir() + path = music / "Manual.flac" + path.write_bytes(b"audio") + digest = sha256_file(path) + state_file = tmp_path / "state.json" + locked = { + "sha256": digest, + "song_id": 77, + "api_name": "User Choice", + "identity_source": "manual", + "identity_locked": True, + "lyric_type": "FLAC_LYRICS_PLAIN", + } + state_file.write_text( + json.dumps( + { + "files": {"Manual.flac": locked}, + "library_sync_paths": ["Manual.flac"], + } + ), + encoding="utf-8", + ) + counts = _counts() + deps = _dependencies( + state_file, + searcher=lambda *args, **kwargs: (_ for _ in ()).throw( + AssertionError("locked identity searched") + ), + counts=counts, + ) + + result = sync_library_index( + Settings(music_dir=music), + state_file=state_file, + dependencies=deps, + ) + + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"][ + "Manual.flac" + ] + assert result.snapshot.tracks[0].identity_locked is True + assert result.snapshot.tracks[0].matched_title == "User Choice" + assert entry == locked + assert counts["searches"] == 0 + + +def test_existing_unknown_is_backfilled_without_changing_audio_or_sidecar(tmp_path): + music = tmp_path / "music" + music.mkdir() + path = music / "Bandit.flac" + path.write_bytes(b"untouched audio") + sidecar = music / "Bandit.lrc" + sidecar.write_text("[00:01.00]Lyric\n", encoding="utf-8") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"Bandit.flac": { + "sha256": sha256_file(path), "lyric_type": "FLAC_LYRICS_PLAIN", + }}}), encoding="utf-8") + rmpc = tmp_path / "rmpc.ron" + rmpc.write_text("keep", encoding="utf-8") + counts = _counts() + deps = _dependencies( + state_file, + searcher=lambda *args, **kwargs: [{"id": 94107, "name": "Bandit"}], + counts=counts, + ) + + result = sync_library_index(Settings(music_dir=music), state_file=state_file, dependencies=deps) + + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"]["Bandit.flac"] + assert result.identified == 1 and result.new == 0 + assert entry["song_id"] == 94107 and entry["lyric_type"] == "FLAC_LYRICS_PLAIN" + assert path.read_bytes() == b"untouched audio" + assert sidecar.read_text(encoding="utf-8") == "[00:01.00]Lyric\n" + assert rmpc.read_text(encoding="utf-8") == "keep" + assert not (tmp_path / "backups").exists() + + +def test_concurrent_state_update_is_preserved(tmp_path): + music = tmp_path / "music" + music.mkdir() + (music / "Song.mp3").write_bytes(b"audio") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {}, "custom": "before"}), encoding="utf-8") + + def searcher(*args, **kwargs): + state_file.write_text(json.dumps({"files": {}, "custom": "newer"}), encoding="utf-8") + return [{"id": 1, "name": "Song"}] + + deps = _dependencies(state_file, searcher=searcher, counts=_counts()) + result = sync_library_index(Settings(music_dir=music), state_file=state_file, dependencies=deps) + + assert result.error and "State changed" in result.error + assert result.snapshot.total_track_count == 1 + assert json.loads(state_file.read_text(encoding="utf-8"))["custom"] == "newer" + + +def test_sidecar_change_rechecks_health_without_rehashing_unchanged_audio(tmp_path): + music = tmp_path / "music" + music.mkdir() + (music / "Song.mp3").write_bytes(b"audio") + sidecar = music / "Song.lrc" + sidecar.write_text("[00:01.00]Line\n", encoding="utf-8") + state_file = tmp_path / "state.json" + counts = _counts() + deps = _dependencies( + state_file, searcher=lambda *args, **kwargs: [{"id": 1, "name": "Song"}], + counts=counts, + ) + settings = Settings(music_dir=music) + first = sync_library_index(settings, state_file=state_file, dependencies=deps) + assert first.snapshot.tracks[0].lrc_status is LibraryLrcStatus.PRESENT + hashes_before = counts["hashes"] + sidecar.write_text("Untimed words\n", encoding="utf-8") + + second = sync_library_index(settings, previous_snapshot=first.snapshot, state_file=state_file, dependencies=deps) + + assert second.snapshot.tracks[0].lrc_status is LibraryLrcStatus.INVALID + assert counts["hashes"] == hashes_before + 1 + assert sidecar.read_text(encoding="utf-8") == "Untimed words\n" + + +def test_one_catalogue_failure_does_not_lose_other_safe_matches(tmp_path): + music = tmp_path / "music" + music.mkdir() + old = music / "Old.mp3" + old.write_bytes(b"changed audio") + (music / "New.mp3").write_bytes(b"new audio") + state_file = tmp_path / "state.json" + original_old = {"sha256": "old hash", "song_id": 7, "api_name": "Old match", "custom": 42} + state_file.write_text(json.dumps({"files": {"Old.mp3": original_old}}), encoding="utf-8") + + def searcher(settings, query, refresh=False): + if query == "Old": + raise OSError("one request failed") + return [{"id": 8, "name": "New"}] + + deps = _dependencies(state_file, searcher=searcher, counts=_counts()) + result = sync_library_index(Settings(music_dir=music), state_file=state_file, dependencies=deps) + saved = json.loads(state_file.read_text(encoding="utf-8"))["files"] + + assert result.identified == 1 and result.failed == 1 + assert saved["New.mp3"]["song_id"] == 8 + assert saved["Old.mp3"] == original_old + assert {track.filename: track.match_status for track in result.snapshot.tracks} == { + "New.mp3": LibraryMatchStatus.MATCHED, + "Old.mp3": LibraryMatchStatus.UNMATCHED, + } + + +@pytest.mark.parametrize( + "provider_error", + ( + "API returned HTTP 503: Service Unavailable", + "API returned HTTP 530: Origin DNS Error", + "Cloudflare Tunnel failure", + "The API returned invalid JSON", + ), +) +def test_provider_wide_failure_stops_repeated_catalogue_requests( + tmp_path, provider_error +): + music = tmp_path / "music" + music.mkdir() + for name in ("One.mp3", "Two.mp3", "Three.mp3"): + (music / name).write_bytes(name.encode()) + state_file = tmp_path / "state.json" + calls = [] + + def unavailable(settings, query, refresh=False): + calls.append(query) + raise RuntimeError(provider_error) + + result = sync_library_index( + Settings(music_dir=music), + state_file=state_file, + dependencies=_dependencies( + state_file, + searcher=unavailable, + counts=_counts(), + ), + ) + + assert calls == ["One"] + assert result.failed == 3 + assert result.unknown == 3 + assert "3 new pending" in result.summary + assert "3 catalogue unknown" in result.summary + assert not state_file.exists() diff --git a/tests/test_library_issues.py b/tests/test_library_issues.py new file mode 100644 index 0000000..819ea2b --- /dev/null +++ b/tests/test_library_issues.py @@ -0,0 +1,248 @@ +from __future__ import annotations + +from dataclasses import replace +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.services.library_issues import ( + LibraryIssueAction, + LibraryIssueCategory, + LibraryIssueSeverity, + get_library_health, +) +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, +) + + +def _track( + root: Path, + name: str = "Song.mp3", + *, + media_format: str = "MP3", + lyric_status: LibraryLyricStatus | None = None, + **changes, +) -> LibraryTrack: + path = root / name + default_lyrics = ( + LibraryLyricStatus.SYNCED + if media_format == "MP3" + else LibraryLyricStatus.PLAIN + ) + values = { + "reference": name, + "path": path, + "relative_path": Path(name), + "filename": path.name, + "title": path.stem, + "duration_seconds": 180.0, + "match_status": LibraryMatchStatus.MATCHED, + "matched_title": path.stem, + "lyric_status": lyric_status or default_lyrics, + "lrc_status": LibraryLrcStatus.PRESENT, + "lrc_path": path.with_suffix(".lrc"), + "state_status": LibraryStateStatus.CURRENT, + "artist": "Juice WRLD", + "album": "Album", + "media_format": media_format, + } + values.update(changes) + return LibraryTrack(**values) + + +def _health(root: Path, *tracks: LibraryTrack): + return get_library_health(LibrarySnapshot(root, True, tracks)) + + +@pytest.mark.parametrize( + ("suffix", "format_name"), + [(".mp3", "MP3"), (".flac", "FLAC"), (".m4a", "M4A")], +) +def test_format_appropriate_healthy_track_is_excluded(tmp_path, suffix, format_name): + health = _health(tmp_path, _track(tmp_path, f"Healthy{suffix}", media_format=format_name)) + + assert health.issue_count == 0 + assert health.healthy_count == 1 + + +def test_unknown_track_is_one_actionable_catalogue_issue(tmp_path): + track = _track( + tmp_path, + "Unknown.flac", + media_format="FLAC", + match_status=LibraryMatchStatus.UNMATCHED, + matched_title=None, + ) + + issue = _health(tmp_path, track).issues[0] + + assert issue.categories == (LibraryIssueCategory.CATALOGUE,) + assert issue.summary == "Catalogue match unknown" + assert issue.action is LibraryIssueAction.MANUAL_MATCH + + +@pytest.mark.parametrize( + "state_status", + (LibraryStateStatus.NEW, LibraryStateStatus.CHANGED), +) +def test_unknown_new_or_changed_track_tells_user_to_sync_first(tmp_path, state_status): + track = _track( + tmp_path, + "Pending.flac", + media_format="FLAC", + match_status=LibraryMatchStatus.UNMATCHED, + matched_title=None, + state_status=state_status, + ) + + issue = _health(tmp_path, track).issues[0] + + assert issue.categories == ( + LibraryIssueCategory.STATE, + LibraryIssueCategory.CATALOGUE, + ) + assert issue.action is LibraryIssueAction.SYNC + + +def test_valid_manual_lock_is_healthy_but_observed_unavailable_lock_is_issue(tmp_path): + locked = _track( + tmp_path, + "Locked.m4a", + media_format="M4A", + identity_source="manual", + identity_locked=True, + ) + assert _health(tmp_path, locked).issues == () + + unavailable = replace( + locked, + warning="The manually selected catalogue recording is unavailable.", + ) + issue = _health(tmp_path, unavailable).issues[0] + assert issue.summary == "Manual catalogue choice unavailable" + assert issue.action is LibraryIssueAction.MANUAL_MATCH + + +def test_missing_lyrics_invalid_lrc_and_verification_failure_are_single_rows(tmp_path): + missing = _track( + tmp_path, + "Missing.flac", + media_format="FLAC", + lyric_status=LibraryLyricStatus.NONE, + lrc_status=LibraryLrcStatus.NONE, + lrc_path=None, + verification_error="no embedded FLAC lyrics", + ) + invalid_lrc = _track( + tmp_path, + "Invalid.m4a", + media_format="M4A", + lrc_status=LibraryLrcStatus.INVALID, + warning="Adjacent LRC has no timestamped lyric lines.", + ) + corrupt = _track( + tmp_path, + "Broken.mp3", + lyric_status=LibraryLyricStatus.NONE, + lrc_status=LibraryLrcStatus.NONE, + lrc_path=None, + verification_error="could not read ID3 header", + warning="could not read ID3 header", + ) + + health = _health(tmp_path, missing, invalid_lrc, corrupt) + + assert len(health.issues) == 3 + assert health.issues[0].categories == (LibraryIssueCategory.LYRICS,) + assert health.issues[0].severity is LibraryIssueSeverity.WARNING + assert health.issues[0].summary == "Optional lyrics are not managed yet" + assert "does not mean the audio is damaged" in health.issues[0].details[0] + assert health.issues[1].categories == (LibraryIssueCategory.LYRICS,) + assert health.issues[2].categories == ( + LibraryIssueCategory.VERIFICATION, + LibraryIssueCategory.LYRICS, + ) + assert health.issues[2].severity is LibraryIssueSeverity.ERROR + + +def test_missing_expected_sidecar_and_metadata_block_are_actionable(tmp_path): + sidecar = _track( + tmp_path, + "Sidecar.mp3", + lrc_status=LibraryLrcStatus.MISSING, + lrc_path=tmp_path / "Sidecar.lrc", + ) + metadata = _track( + tmp_path, + "Metadata.flac", + media_format="FLAC", + match_status=LibraryMatchStatus.UNMATCHED, + matched_title=None, + artist=None, + warning="FLAC metadata is missing artist; track cannot be matched safely.", + ) + + issues = _health(tmp_path, sidecar, metadata).issues + + assert LibraryIssueCategory.LYRICS in issues[0].categories + assert issues[0].action is LibraryIssueAction.REFRESH_LYRICS + assert LibraryIssueCategory.METADATA in issues[1].categories + assert issues[1].action is LibraryIssueAction.MANUAL_MATCH + + +def test_new_changed_and_invalid_state_are_one_row_each_and_sync_actionable(tmp_path): + tracks = tuple( + _track(tmp_path, f"{status.value}.mp3", state_status=status) + for status in ( + LibraryStateStatus.NEW, + LibraryStateStatus.CHANGED, + LibraryStateStatus.INVALID, + ) + ) + + issues = _health(tmp_path, *tracks).issues + + assert len(issues) == 3 + assert all(LibraryIssueCategory.STATE in issue.categories for issue in issues) + assert all(issue.action is LibraryIssueAction.SYNC for issue in issues) + assert issues[-1].severity is LibraryIssueSeverity.ERROR + + +def test_health_recomputes_from_replacement_sync_snapshot(tmp_path): + unknown = _track( + tmp_path, + match_status=LibraryMatchStatus.UNMATCHED, + matched_title=None, + ) + before = _health(tmp_path, unknown) + after = _health( + tmp_path, + replace( + unknown, + match_status=LibraryMatchStatus.MATCHED, + matched_title="Song", + ), + ) + newly_broken = _health( + tmp_path, + replace( + unknown, + match_status=LibraryMatchStatus.MATCHED, + matched_title="Song", + lyric_status=LibraryLyricStatus.NONE, + verification_error="no managed lyrics frame", + ), + ) + + assert before.issue_count == 1 + assert after.issue_count == 0 + assert newly_broken.issue_count == 1 diff --git a/tests/test_library_status.py b/tests/test_library_status.py new file mode 100644 index 0000000..724b599 --- /dev/null +++ b/tests/test_library_status.py @@ -0,0 +1,451 @@ +import json +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.media import AudioMetadata +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibraryStateStatus, + LibraryStatus, + get_library_snapshot, + get_library_status, +) +from juice_lyrics.state import sha256_file + + +def test_empty_library_status_is_read_only(tmp_path): + library = tmp_path / "music" + library.mkdir() + state_file = tmp_path / "missing" / "state.json" + backup_dir = tmp_path / "missing" / "backups" + + status = get_library_status( + Settings(music_dir=library), + state_file=state_file, + backup_dir=backup_dir, + ) + + assert status == LibraryStatus( + library_path=library, + track_count=0, + embedded_synced_count=0, + embedded_plain_count=0, + missing_or_invalid_count=0, + rmpc_lrc_count=0, + new_or_changed_count=0, + backup_count=0, + ) + assert not state_file.parent.exists() + + +def test_library_status_counts_lyrics_changes_lrc_and_backups(tmp_path): + library = tmp_path / "music" + library.mkdir() + synced = library / "synced.mp3" + plain = library / "plain.mp3" + missing = library / "missing.mp3" + changed = library / "changed.mp3" + for path in (synced, plain, missing, changed): + path.write_bytes(path.stem.encode()) + + lrc = synced.with_suffix(".lrc") + lrc.write_text("[00:01.00] line\n", encoding="utf-8") + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + "synced.mp3": {"sha256": sha256_file(synced), "lrc": str(lrc)}, + "plain.mp3": {"sha256": sha256_file(plain), "lrc": None}, + "missing.mp3": {"sha256": sha256_file(missing), "lrc": None}, + "changed.mp3": {"sha256": "old-hash", "lrc": None}, + } + } + ), + encoding="utf-8", + ) + backup_dir = tmp_path / "backups" + for index, name in enumerate(("one", "two"), start=1): + root = backup_dir / name + root.mkdir(parents=True) + (root / "Track.mp3").write_bytes(b"backup") + (root / "manifest.json").write_text( + json.dumps({"created": f"2026-01-0{index}T00:00:00+00:00", "files": []}), + encoding="utf-8", + ) + (backup_dir / "not-a-backup.txt").write_text("ignored", encoding="utf-8") + + results = { + synced: (True, "SYLT (2 synced lines)"), + plain: (True, "USLT (ordinary lyrics)"), + missing: (False, "no managed lyrics frame"), + changed: (True, "USLT (ordinary lyrics)"), + } + status = get_library_status( + Settings(music_dir=library, lyrics_dir=tmp_path / "ignored-central"), + state_file=state_file, + backup_dir=backup_dir, + verifier=results.__getitem__, + ) + + assert status.library_path == library + assert status.track_count == 4 + assert status.embedded_synced_count == 1 + assert status.embedded_plain_count == 2 + assert status.missing_or_invalid_count == 1 + assert status.rmpc_lrc_count == 1 + assert status.new_or_changed_count == 1 + assert status.backup_count == 2 + assert status.warnings == () + + +def test_library_status_marks_new_supported_audio_files_for_sync(tmp_path): + mp3 = tmp_path / "new.mp3" + mp3.write_bytes(b"audio") + (tmp_path / "future.flac").write_bytes(b"audio") + + status = get_library_status( + Settings(music_dir=tmp_path), + state_file=tmp_path / "absent.json", + backup_dir=tmp_path / "absent-backups", + verifier=lambda path: (False, "invalid"), + ) + + assert status.track_count == 2 + assert status.missing_or_invalid_count == 2 + assert status.new_or_changed_count == 2 + + +def test_library_status_does_not_contact_api(tmp_path, monkeypatch): + import juice_lyrics.api.client as api_client + + monkeypatch.setattr( + api_client, + "api_get", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("API called")), + ) + + status = get_library_status( + Settings(music_dir=tmp_path), + state_file=tmp_path / "state.json", + backup_dir=tmp_path / "backups", + ) + + assert status.track_count == 0 + + +def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypatch): + import juice_lyrics.api.client as api_client + + library = tmp_path / "music" + library.mkdir() + synced = library / "A Synced.mp3" + plain = library / "B Plain.mp3" + missing = library / "C Missing.mp3" + for path in (synced, plain, missing): + path.write_bytes(path.name.encode()) + lrc = synced.with_suffix(".lrc") + lrc.write_text("[00:01.00] line\n", encoding="utf-8") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({ + "files": { + "A Synced.mp3": { + "sha256": sha256_file(synced), + "song_id": 1, + "api_name": "A Synced (v1)", + "lrc": str(lrc), + }, + "B Plain.mp3": { + "sha256": "old", + "song_id": 2, + "api_name": "B Plain", + "lrc": None, + }, + } + }), encoding="utf-8") + verification = { + synced: (True, "SYLT (2 synced lines)"), + plain: (True, "USLT (ordinary lyrics)"), + missing: (False, "no managed lyrics frame"), + } + monkeypatch.setattr( + api_client, + "api_get", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("API called")), + ) + + snapshot = get_library_snapshot( + Settings(music_dir=library, lyrics_dir=tmp_path / "ignored-central"), + state_file=state_file, + verifier=verification.__getitem__, + duration_reader=lambda path: {synced: 180.0, plain: 181.5, missing: None}[path], + ) + + assert [track.filename for track in snapshot.tracks] == [ + "A Synced.mp3", "B Plain.mp3", "C Missing.mp3" + ] + assert snapshot.total_track_count == 3 + assert snapshot.matched_count == 1 + assert snapshot.unmatched_count == 2 + assert snapshot.synced_count == 1 + assert snapshot.plain_count == 1 + assert snapshot.no_lyrics_count == 1 + assert snapshot.external_lrc_count == 1 + assert snapshot.needs_attention_count == 1 + assert snapshot.tracks[0].match_status is LibraryMatchStatus.MATCHED + assert snapshot.tracks[0].catalogue_id == 1 + assert snapshot.tracks[0].lyric_status is LibraryLyricStatus.SYNCED + assert snapshot.tracks[0].lrc_status is LibraryLrcStatus.PRESENT + assert snapshot.tracks[0].state_status is LibraryStateStatus.CURRENT + assert snapshot.tracks[1].state_status is LibraryStateStatus.CHANGED + assert snapshot.tracks[1].match_status is LibraryMatchStatus.UNMATCHED + assert snapshot.tracks[1].matched_title is None + assert snapshot.tracks[2].match_status is LibraryMatchStatus.UNMATCHED + assert snapshot.tracks[2].lyric_status is LibraryLyricStatus.NONE + assert snapshot.tracks[2].needs_attention is True + + +@pytest.mark.parametrize( + ("suffix", "verification", "format_name", "lyric_status"), + [ + (".mp3", "SYLT (61 synced lines)", "MP3", LibraryLyricStatus.SYNCED), + (".flac", "FLAC LYRICS (500 characters)", "FLAC", LibraryLyricStatus.PLAIN), + (".m4a", "M4A LYRICS (500 characters)", "M4A", LibraryLyricStatus.PLAIN), + ], +) +def test_unmatched_track_with_format_appropriate_lyrics_is_fully_covered( + tmp_path, suffix, verification, format_name, lyric_status +): + track = tmp_path / f"Bandit{suffix}" + track.write_bytes(b"audio") + track.with_suffix(".lrc").write_text( + "[ar:Juice WRLD]\n[00:05.77] Oh-oh\n[00:10.45] Yeah\n", + encoding="utf-8", + ) + + snapshot = get_library_snapshot( + Settings(music_dir=tmp_path), + state_file=tmp_path / "missing-state.json", + verifier=lambda path: (True, verification), + duration_reader=lambda path: 189.32, + metadata_reader=lambda path: AudioMetadata( + "Bandit (with YoungBoy Never Broke Again)", + "Juice WRLD, YoungBoy Never Broke Again", + "Death Race For Love (Bonus Track Version)", + 189.32, + ), + ) + + item = snapshot.tracks[0] + assert item.media_format == format_name + assert item.match_status is LibraryMatchStatus.UNMATCHED + assert item.lyric_status is lyric_status + assert item.lrc_status is LibraryLrcStatus.PRESENT + assert item.fully_covered is True + assert item.needs_attention is False + assert snapshot.fully_covered_count == 1 + assert snapshot.needs_attention_count == 0 + + +def test_existing_untimed_sidecar_is_invalid_and_needs_attention(tmp_path): + track = tmp_path / "Bandit.flac" + track.write_bytes(b"audio") + track.with_suffix(".lrc").write_text( + "[ar:Juice WRLD]\nThese are only plain lyrics.\n", + encoding="utf-8", + ) + snapshot = get_library_snapshot( + Settings(music_dir=tmp_path), + state_file=tmp_path / "missing-state.json", + verifier=lambda path: (True, "FLAC LYRICS (30 characters)"), + metadata_reader=lambda path: AudioMetadata("Bandit", "Juice WRLD", None, 189.32), + ) + + item = snapshot.tracks[0] + assert item.lrc_status is LibraryLrcStatus.INVALID + assert item.fully_covered is False + assert item.needs_attention is True + assert "no timestamped lyric lines" in (item.warning or "") + + +def test_matched_track_with_expected_synced_lyrics_and_missing_sidecar_needs_attention(tmp_path): + track = tmp_path / "Bandit.flac" + track.write_bytes(b"audio") + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + "Bandit.flac": { + "sha256": sha256_file(track), + "song_id": 1, + "api_name": "Bandit", + "lyric_type": "FLAC_LYRICS_SYNCED", + "lrc": str(track.with_suffix(".lrc")), + } + } + } + ), + encoding="utf-8", + ) + + snapshot = get_library_snapshot( + Settings(music_dir=tmp_path), + state_file=state_file, + verifier=lambda path: (True, "FLAC LYRICS (500 characters)"), + metadata_reader=lambda path: AudioMetadata("Bandit", "Juice WRLD", None, 189.32), + ) + + item = snapshot.tracks[0] + assert item.match_status is LibraryMatchStatus.MATCHED + assert item.lyric_status is LibraryLyricStatus.PLAIN + assert item.lrc_status is LibraryLrcStatus.MISSING + assert item.fully_covered is False + assert item.needs_attention is True + + +def test_library_snapshot_uses_adjacent_sidecar_not_config_or_historical_state_path(tmp_path): + library = tmp_path / "Music" / "Juice WRLD" / "Unreleased" + library.mkdir(parents=True) + track = library / "Rental.mp3" + track.write_bytes(b"audio") + legacy = tmp_path / "Music" / "Juice WRLD" / "lyrics" / "Rental.lrc" + configured = tmp_path / "Music" / "lyrics" + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({ + "files": { + "Rental.mp3": { + "sha256": sha256_file(track), + "song_id": 1, + "api_name": "Rental", + "lrc": str(legacy), + } + } + }), encoding="utf-8") + + snapshot = get_library_snapshot( + Settings(music_dir=library, lyrics_dir=configured), + state_file=state_file, + verifier=lambda path: (True, "SYLT (1 synced line)"), + duration_reader=lambda path: 180.0, + ) + + item = snapshot.tracks[0] + assert item.lrc_path == track.with_suffix(".lrc") + assert item.lrc_status is LibraryLrcStatus.MISSING + assert "Adjacent external LRC file is missing" in (item.warning or "") + assert not legacy.parent.exists() + assert not configured.exists() + + +def test_library_status_ignores_unrelated_centralized_lrc(tmp_path): + library = tmp_path / "music" + library.mkdir() + track = library / "Rental.mp3" + track.write_bytes(b"audio") + central = tmp_path / "lyrics" + central.mkdir() + (central / "Rental.lrc").write_text("[00:01.00] old\n", encoding="utf-8") + + status = get_library_status( + Settings(music_dir=library, lyrics_dir=central, lyrics_dir_explicit=True), + state_file=tmp_path / "missing-state.json", + backup_dir=tmp_path / "missing-backups", + verifier=lambda path: (True, "SYLT (1 synced line)"), + ) + + assert status.rmpc_lrc_count == 0 + assert not track.with_suffix(".lrc").exists() + + +def test_unambiguous_historical_basename_identity_remains_readable(tmp_path): + library = tmp_path / "music" + track = library / "Unreleased" / "24 Hours.mp3" + track.parent.mkdir(parents=True) + track.write_bytes(b"audio") + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + "24 Hours.mp3": { + "sha256": sha256_file(track), + "song_id": 94760, + "api_name": "24 Hours", + "lyric_type": "USLT", + "lrc": None, + }, + "/tmp/pytest-of-someone/pytest-2/test_case/Ghost.flac": { + "song_id": 1, + "api_name": "Ghost", + }, + } + } + ), + encoding="utf-8", + ) + + snapshot = get_library_snapshot( + Settings(music_dir=library), + state_file=state_file, + verifier=lambda path: (True, "USLT (ordinary lyrics)"), + duration_reader=lambda path: 180.0, + ) + + item = snapshot.tracks[0] + assert item.reference == "Unreleased/24 Hours.mp3" + assert item.match_status is LibraryMatchStatus.MATCHED + assert item.matched_title == "24 Hours" + assert snapshot.unmatched_count == 0 + + +def test_track_snapshot_handles_missing_library_and_malformed_state(tmp_path): + missing = tmp_path / "missing" + snapshot = get_library_snapshot(Settings(music_dir=missing), state_file=tmp_path / "state.json") + assert snapshot.directory_exists is False + assert snapshot.tracks == () + assert "does not exist" in snapshot.warnings[0] + + library = tmp_path / "music" + library.mkdir() + track = library / "Track.mp3" + track.write_bytes(b"audio") + state_file = tmp_path / "bad-state.json" + state_file.write_text("not-json", encoding="utf-8") + snapshot = get_library_snapshot( + Settings(music_dir=library), + state_file=state_file, + verifier=lambda path: (False, "unreadable tags"), + duration_reader=lambda path: None, + ) + assert snapshot.directory_exists is True + assert snapshot.warnings + assert snapshot.tracks[0].state_status is LibraryStateStatus.NEW + assert snapshot.tracks[0].warning == "unreadable tags" + + +def test_track_snapshot_is_read_only(tmp_path, monkeypatch): + library = tmp_path / "music" + library.mkdir() + track = library / "Track.mp3" + track.write_bytes(b"original") + state_file = tmp_path / "absent" / "state.json" + before = track.read_bytes() + + snapshot = get_library_snapshot( + Settings(music_dir=library), + state_file=state_file, + verifier=lambda path: (False, "no managed lyrics frame"), + duration_reader=lambda path: 100.0, + ) + + assert snapshot.total_track_count == 1 + assert track.read_bytes() == before + assert not state_file.parent.exists() diff --git a/tests/test_library_sync_service.py b/tests/test_library_sync_service.py new file mode 100644 index 0000000..be769e7 --- /dev/null +++ b/tests/test_library_sync_service.py @@ -0,0 +1,569 @@ +import json +from pathlib import Path +import shutil +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +import pytest + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.library_sync import ( + LibrarySyncDependencies, + LibrarySyncOptions, + MatchOutcome, + SyncEventKind, + SyncLyricType, + execute_library_sync, + execute_library_sync_preview, + get_library_sync_preview, + plan_library_sync, +) + + +def _candidate(kind="synced"): + return { + "id": 101, + "name": "Track", + "synced_lyrics": "[00:01.00] line" if kind == "synced" else "", + "lyrics": "plain line" if kind == "plain" else "", + } + + +def _dependencies(tmp_path, candidates=None): + candidates = candidates or {} + state = {"files": {}, "updated": None} + saved = [] + backup_root = tmp_path / "backups" / "run" + + def scanner(settings): + return sorted(Path(settings.music_dir).glob("*.mp3")) + + def searcher(settings, title, refresh=False): + value = candidates.get(title) + if isinstance(value, Exception): + raise value + return [] if value is None else [value] + + def matcher(settings, path, results, title): + candidate = results[0] if results else None + return candidate, 100.0 if candidate else 0.0, [], [] + + def make_backup_root(): + backup_root.mkdir(parents=True, exist_ok=True) + return backup_root + + def backup(path, root, base): + destination = root / path.relative_to(base) + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(path, destination) + return destination + + dependencies = LibrarySyncDependencies( + scanner=scanner, + searcher=searcher, + matcher=matcher, + search_title=lambda path: path.stem, + lyric_parser=lambda raw: [("line", 1000)] if raw else [], + backup_root_factory=make_backup_root, + backup_writer=backup, + restorer=lambda backup_path, path: shutil.copy2(backup_path, path), + manifest_writer=lambda root, entries: (root / "manifest.json").write_text(json.dumps(entries)), + state_loader=lambda: state, + state_saver=lambda value: saved.append(json.loads(json.dumps(value))), + hasher=lambda path: __import__("hashlib").sha256(path.read_bytes()).hexdigest(), + ) + return dependencies, state, saved, backup_root + + +def _options(tmp_path, **kwargs): + settings = Settings(music_dir=tmp_path) + return LibrarySyncOptions.from_settings(settings, **kwargs) + + +def test_empty_library_and_existing_state_are_supported(tmp_path): + deps, state, saved, _ = _dependencies(tmp_path) + state["legacy"] = "preserved" + plan = plan_library_sync(_options(tmp_path), dependencies=deps) + result = execute_library_sync(plan, dependencies=deps) + + assert plan.total_files == 0 + assert result.updated_files == 0 + assert saved[0]["legacy"] == "preserved" + + +def test_completely_unchanged_library_is_not_backed_up_or_modified(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"current") + deps, state, saved, backup_root = _dependencies(tmp_path, {"Track": _candidate()}) + state["files"]["Track.mp3"] = {"sha256": deps.hasher(path), "lyric_type": "USLT", "lrc": None} + deps.verifier = lambda path: (True, "USLT") + deps.embedder = lambda *args: (_ for _ in ()).throw(AssertionError("embed called")) + + plan = plan_library_sync(_options(tmp_path), dependencies=deps) + result = execute_library_sync(plan, dependencies=deps) + + assert plan.unchanged_files == 1 + assert result.tracks[0].outcome is MatchOutcome.UNCHANGED + assert not backup_root.exists() + assert path.read_bytes() == b"current" + + +def test_historical_central_lrc_state_cannot_redirect_or_invalidate_sidecar(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"current") + path.with_suffix(".lrc").write_text("[00:01.00] line\n", encoding="utf-8") + deps, state, _, backup_root = _dependencies(tmp_path, {"Track": _candidate()}) + state["files"]["Track.mp3"] = { + "sha256": deps.hasher(path), + "lyric_type": "SYLT", + "lrc": str(tmp_path / "old-central" / "Track.lrc"), + } + deps.verifier = lambda target: (True, "SYLT") + + plan = plan_library_sync( + _options(tmp_path, rmpc_enabled=True), + dependencies=deps, + ) + + assert plan.unchanged_files == 1 + assert not backup_root.exists() + assert not (tmp_path / "old-central").exists() + + +@pytest.mark.parametrize(("kind", "lyric_type"), [("synced", SyncLyricType.SYNCED), ("plain", SyncLyricType.PLAIN)]) +def test_new_synced_and_plain_files_are_backed_up_verified_and_saved(tmp_path, kind, lyric_type): + path = tmp_path / "Track.mp3" + original = b"original" + path.write_bytes(original) + deps, state, saved, backup_root = _dependencies(tmp_path, {"Track": _candidate(kind)}) + events = [] + + def embed(target, synced, plain): + assert (backup_root / "Track.mp3").read_bytes() == original + target.write_bytes(b"modified") + return lyric_type.value + + deps.embedder = embed + deps.verifier = lambda target: (True, "verified") + plan = plan_library_sync(_options(tmp_path), dependencies=deps, progress=events.append) + result = execute_library_sync(plan, dependencies=deps, progress=events.append) + + assert result.updated_files == 1 + assert result.tracks[-1].lyric_type is lyric_type + assert path.read_bytes() == b"modified" + assert saved[0]["files"]["Track.mp3"]["lyric_type"] == lyric_type.value + kinds = [event.kind for event in events] + assert kinds.index(SyncEventKind.BACKUP_CREATED) < kinds.index(SyncEventKind.LYRICS_EMBEDDED) + assert kinds.index(SyncEventKind.LYRICS_EMBEDDED) < kinds.index(SyncEventKind.VERIFICATION_SUCCEEDED) + assert kinds.index(SyncEventKind.STATE_UPDATED) < kinds.index(SyncEventKind.TRACK_COMPLETED) + + +def test_unresolved_no_lyrics_and_analysis_failure_are_structured(tmp_path): + for name in ("Unknown", "Empty", "Broken"): + (tmp_path / f"{name}.mp3").write_bytes(name.encode()) + deps, _, _, _ = _dependencies( + tmp_path, + {"Empty": _candidate("none"), "Broken": RuntimeError("API unavailable")}, + ) + plan = plan_library_sync(_options(tmp_path), dependencies=deps) + outcomes = {track.path.stem: track.outcome for track in plan.tracks} + + assert outcomes == { + "Broken": MatchOutcome.FAILED, + "Empty": MatchOutcome.NO_LYRICS, + "Unknown": MatchOutcome.UNRESOLVED, + } + assert plan.unresolved_files == 1 + assert plan.no_lyrics_files == 1 + assert plan.analysis_failures == 1 + + +def test_dry_run_and_refresh_are_non_mutating(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"original") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {}})) + before = state_file.read_bytes() + calls = [] + deps, _, saved, backup_root = _dependencies(tmp_path, {"Track": _candidate()}) + deps.state_loader = lambda: (_ for _ in ()).throw(AssertionError("mutating loader called")) + original_searcher = deps.searcher + deps.searcher = lambda settings, title, refresh=False: calls.append(refresh) or original_searcher(settings, title, refresh=refresh) + deps.embedder = lambda *args: (_ for _ in ()).throw(AssertionError("embed called")) + deps.rmpc_notifier = lambda paths: (_ for _ in ()).throw(AssertionError("rmpc called")) + options = _options( + tmp_path, + dry_run=True, + refresh=True, + rmpc_enabled=True, + lyrics_dir=tmp_path / "lyrics", + state_file=state_file, + ) + + plan = plan_library_sync(options, dependencies=deps) + result = execute_library_sync(plan, dependencies=deps) + + assert calls == [True] + assert result.updated_files == 0 + assert path.read_bytes() == b"original" + assert state_file.read_bytes() == before + assert saved == [] + assert not backup_root.exists() + assert not (tmp_path / "lyrics").exists() + + +def test_frontend_preview_helper_is_dry_run_and_non_mutating(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"original") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {}}), encoding="utf-8") + deps, _, saved, backup_root = _dependencies(tmp_path, {"Track": _candidate()}) + deps.state_loader = lambda: (_ for _ in ()).throw(AssertionError("mutating state loader called")) + deps.embedder = lambda *args: (_ for _ in ()).throw(AssertionError("embed called")) + + configured_lyrics = tmp_path / "central-lyrics" + plan = get_library_sync_preview( + Settings(music_dir=tmp_path, lyrics_dir=configured_lyrics), + rmpc_enabled=True, + state_file=state_file, + dependencies=deps, + ) + + assert plan.options.dry_run is True + assert plan.ready_files == 1 + assert plan.synced_files == 1 + assert plan.options.lyrics_dir is None + assert plan.tracks[0].lrc_path == path.with_suffix(".lrc") + assert saved == [] + assert path.read_bytes() == b"original" + assert not backup_root.exists() + assert not (tmp_path / "lyrics").exists() + + +def test_frontend_preview_can_scope_one_track_and_force_refresh(tmp_path): + selected = tmp_path / "Selected.mp3" + other = tmp_path / "Other.mp3" + selected.write_bytes(b"selected") + other.write_bytes(b"other") + calls = [] + deps, _, _, _ = _dependencies(tmp_path, {"Selected": _candidate(), "Other": _candidate()}) + original_searcher = deps.searcher + deps.searcher = lambda settings, title, refresh=False: calls.append((title, refresh)) or original_searcher(settings, title, refresh=refresh) + + plan = get_library_sync_preview( + Settings(music_dir=tmp_path), + rmpc_enabled=True, + state_file=tmp_path / "missing-state.json", + dependencies=deps, + refresh=True, + selected_paths=(selected,), + ) + + assert [track.path for track in plan.tracks] == [selected] + assert calls == [("Selected", True)] + + +def test_lyric_maintenance_uses_and_preserves_valid_manual_identity_lock(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"original") + deps, state, saved, _ = _dependencies(tmp_path) + locked = { + "sha256": deps.hasher(path), + "song_id": 77, + "api_name": "User Choice", + "identity_source": "manual", + "identity_locked": True, + "custom": "keep", + } + state["files"]["Track.mp3"] = locked + wrong = {**_candidate("plain"), "id": 88, "name": "Automatic Choice"} + chosen = {**_candidate("plain"), "id": 77, "name": "User Choice"} + deps.searcher = lambda *args, **kwargs: [wrong, chosen] + deps.matcher = lambda *args: (wrong, 100.0, [], []) + deps.embedder = lambda target, *_: target.write_bytes(b"updated") or "USLT" + deps.verifier = lambda target: (True, "USLT") + + plan = plan_library_sync( + _options(tmp_path, refresh=True), + dependencies=deps, + ) + assert plan.tracks[0].candidate["id"] == 77 + assert plan.tracks[0].identity_locked is True + + execute_library_sync(plan, dependencies=deps) + entry = saved[0]["files"]["Track.mp3"] + assert entry["song_id"] == 77 + assert entry["api_name"] == "User Choice" + assert entry["identity_source"] == "manual" + assert entry["identity_locked"] is True + assert entry["custom"] == "keep" + + +def test_missing_locked_catalogue_candidate_does_not_fall_back_or_change_state( + tmp_path, +): + path = tmp_path / "Track.mp3" + path.write_bytes(b"original") + deps, state, saved, backup_root = _dependencies(tmp_path) + locked = { + "sha256": deps.hasher(path), + "song_id": 77, + "api_name": "User Choice", + "identity_source": "manual", + "identity_locked": True, + } + state["files"]["Track.mp3"] = locked + wrong = {**_candidate("plain"), "id": 88, "name": "Automatic Choice"} + deps.searcher = lambda *args, **kwargs: [wrong] + deps.matcher = lambda *args: (wrong, 100.0, [], []) + + plan = plan_library_sync( + _options(tmp_path, refresh=True), + dependencies=deps, + ) + result = execute_library_sync(plan, dependencies=deps) + + assert plan.tracks[0].outcome is MatchOutcome.UNRESOLVED + assert "manually selected" in (plan.tracks[0].error or "") + assert result.updated_files == 0 + assert saved[0]["files"]["Track.mp3"] == locked + assert path.read_bytes() == b"original" + assert not backup_root.exists() + + +def test_frontend_preview_protects_locally_covered_unmatched_track(tmp_path): + path = tmp_path / "Bandit.mp3" + path.write_bytes(b"covered audio") + path.with_suffix(".lrc").write_text("[00:05.77]Oh-oh\n", encoding="utf-8") + deps, _, _, backup_root = _dependencies(tmp_path) + deps.searcher = lambda *args, **kwargs: (_ for _ in ()).throw( + AssertionError("covered track was searched") + ) + + plan = get_library_sync_preview( + Settings(music_dir=tmp_path), + rmpc_enabled=True, + state_file=tmp_path / "missing-state.json", + dependencies=deps, + protected_paths=(path,), + ) + + assert plan.unchanged_files == 1 + assert plan.tracks[0].outcome is MatchOutcome.UNCHANGED + assert path.read_bytes() == b"covered audio" + assert not backup_root.exists() + + +def test_explicit_refresh_of_unmatched_covered_track_preserves_existing_files(tmp_path): + path = tmp_path / "Bandit.mp3" + sidecar = path.with_suffix(".lrc") + path.write_bytes(b"covered audio") + sidecar.write_text("[00:05.77]Oh-oh\n", encoding="utf-8") + deps, _, saved, backup_root = _dependencies(tmp_path) + + preview = get_library_sync_preview( + Settings(music_dir=tmp_path), + rmpc_enabled=True, + state_file=tmp_path / "missing-state.json", + dependencies=deps, + refresh=True, + selected_paths=(path,), + ) + result = execute_library_sync_preview(preview, dependencies=deps) + + assert preview.tracks[0].outcome is MatchOutcome.UNRESOLVED + assert result.updated_files == 0 + assert path.read_bytes() == b"covered audio" + assert sidecar.read_text(encoding="utf-8") == "[00:05.77]Oh-oh\n" + assert not backup_root.exists() + assert saved + + +def test_current_synced_state_requires_a_parseable_timed_sidecar(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"current") + path.with_suffix(".lrc").write_text("plain lyrics only\n", encoding="utf-8") + deps, state, _, _ = _dependencies(tmp_path, {"Track": _candidate()}) + state["files"]["Track.mp3"] = { + "sha256": deps.hasher(path), + "lyric_type": "SYLT", + "lrc": str(path.with_suffix(".lrc")), + } + deps.verifier = lambda target: (True, "SYLT") + deps.lyric_parser = lambda raw: [("line", 1000)] if "[00:" in raw else [] + + plan = plan_library_sync(_options(tmp_path, rmpc_enabled=True), dependencies=deps) + + assert plan.ready_files == 1 + assert plan.tracks[0].outcome is MatchOutcome.MATCHED + + +def test_reviewed_preview_executes_through_existing_sync_engine(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"original") + deps, _, saved, backup_root = _dependencies(tmp_path, {"Track": _candidate("plain")}) + deps.embedder = lambda target, *_: target.write_bytes(b"updated") or "USLT" + deps.verifier = lambda target: (True, "USLT") + preview = get_library_sync_preview( + Settings(music_dir=tmp_path), + rmpc_enabled=False, + state_file=tmp_path / "missing-state.json", + dependencies=deps, + ) + + result = execute_library_sync_preview(preview, dependencies=deps) + + assert result.updated_files == 1 + assert path.read_bytes() == b"updated" + assert (backup_root / "Track.mp3").read_bytes() == b"original" + assert saved[0]["files"]["Track.mp3"]["lyric_type"] == "USLT" + + +def test_execution_boundary_rejects_unreviewed_live_plan(tmp_path): + deps, _, _, _ = _dependencies(tmp_path) + live = plan_library_sync(_options(tmp_path), dependencies=deps) + with pytest.raises(ValueError, match="dry-run preview"): + execute_library_sync_preview(live, dependencies=deps) + + +def test_no_rmpc_suppresses_lrc_and_notification_for_synced_track(tmp_path): + path = tmp_path / "Track.mp3" + path.write_bytes(b"original") + deps, _, _, _ = _dependencies(tmp_path, {"Track": _candidate()}) + deps.embedder = lambda target, *_: target.write_bytes(b"modified") and "SYLT" + deps.verifier = lambda target: (True, "verified") + deps.lrc_writer = lambda *args: (_ for _ in ()).throw(AssertionError("LRC called")) + deps.rmpc_notifier = lambda *args: (_ for _ in ()).throw(AssertionError("rmpc called")) + + result = execute_library_sync( + plan_library_sync(_options(tmp_path, rmpc_enabled=False), dependencies=deps), + dependencies=deps, + ) + assert result.lrc_files_generated == 0 + assert result.rmpc_notifications == 0 + + +def test_synced_generates_lrc_but_plain_never_does(tmp_path): + synced = tmp_path / "Synced.mp3" + plain = tmp_path / "Plain.mp3" + synced.write_bytes(b"synced") + plain.write_bytes(b"plain") + deps, _, _, _ = _dependencies(tmp_path, {"Synced": _candidate("synced"), "Plain": _candidate("plain")}) + deps.embedder = lambda target, synced_lines, plain_text: "SYLT" if synced_lines else "USLT" + deps.verifier = lambda target: (True, "verified") + lrc_calls = [] + + def write_lrc(path, synced_lines, candidate): + lrc_calls.append(path) + result = path.with_suffix(".lrc") + result.write_text("lrc") + return result + + deps.lrc_writer = write_lrc + deps.rmpc_notifier = lambda paths: len(paths) + configured_lyrics = tmp_path / "central-lyrics" + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path, lyrics_dir=configured_lyrics), + rmpc_enabled=True, + ) + result = execute_library_sync(plan_library_sync(options, dependencies=deps), dependencies=deps) + + assert lrc_calls == [synced] + assert synced.with_suffix(".lrc").is_file() + assert not configured_lyrics.exists() + assert result.lrc_files_generated == 1 + assert result.rmpc_notifications == 1 + + +@pytest.mark.parametrize("mode", ["verification", "embed"]) +def test_embedding_or_verification_failure_restores_original(tmp_path, mode): + path = tmp_path / "Track.mp3" + original = b"original bytes" + path.write_bytes(original) + deps, _, saved, _ = _dependencies(tmp_path, {"Track": _candidate("plain")}) + + def embed(target, synced, plain): + target.write_bytes(b"partial") + if mode == "embed": + raise RuntimeError("embed failed") + return "USLT" + + deps.embedder = embed + deps.verifier = lambda target: (False, "bad frame") + result = execute_library_sync(plan_library_sync(_options(tmp_path), dependencies=deps), dependencies=deps) + + assert result.processing_failed_files == 1 + assert path.read_bytes() == original + assert "Track.mp3" not in saved[0]["files"] + + +def test_restore_failure_is_structured_and_other_tracks_continue(tmp_path): + bad = tmp_path / "Bad.mp3" + good = tmp_path / "Good.mp3" + bad.write_bytes(b"bad original") + good.write_bytes(b"good original") + deps, _, _, _ = _dependencies(tmp_path, {"Bad": _candidate("plain"), "Good": _candidate("plain")}) + + def embed(target, synced, plain): + target.write_bytes(b"modified") + if target == bad: + raise RuntimeError("embed failed") + return "USLT" + + deps.embedder = embed + deps.verifier = lambda target: (True, "verified") + deps.restorer = lambda backup, target: (_ for _ in ()).throw(OSError("restore failed")) + result = execute_library_sync(plan_library_sync(_options(tmp_path), dependencies=deps), dependencies=deps) + + assert result.updated_files == 1 + assert result.processing_failed_files == 1 + failure = next(track for track in result.tracks if track.path == bad) + assert "restore failed" in (failure.error or "") + assert good.read_bytes() == b"modified" + + +def test_cli_sync_delegates_and_preserves_empty_output(tmp_path, monkeypatch, capsys): + import argparse + import juice_lyrics.cli as cli + + deps, _, _, _ = _dependencies(tmp_path) + plan = plan_library_sync(_options(tmp_path), dependencies=deps) + monkeypatch.setattr(cli, "plan_library_sync", lambda options, progress=None: plan) + monkeypatch.setattr(cli, "execute_library_sync", lambda service_plan, progress=None: execute_library_sync(service_plan, dependencies=deps)) + args = argparse.Namespace(no_rmpc=True, dry_run=False, refresh=False, yes=True) + + result = cli.command_sync(args, Settings(music_dir=tmp_path), False) + output = capsys.readouterr().out + + assert result == 0 + assert "Library Sync" in output + assert "Changed/new: 0" in output + assert "Nothing needs updating." in output + + +def test_cli_sync_dry_run_reports_exact_sidecar_destination(tmp_path, monkeypatch, capsys): + import argparse + import juice_lyrics.cli as cli + + path = tmp_path / "Rental (v1).mp3" + path.write_bytes(b"audio") + deps, _, _, _ = _dependencies(tmp_path, {path.stem: _candidate()}) + plan = plan_library_sync( + _options(tmp_path, dry_run=True, rmpc_enabled=True), + dependencies=deps, + ) + monkeypatch.setattr(cli, "plan_library_sync", lambda options, progress=None: plan) + monkeypatch.setattr(cli.shutil, "which", lambda name: "/usr/bin/rmpc") + monkeypatch.setattr(cli, "DEFAULT_RMPC_CONFIG", tmp_path / "rmpc.ron") + cli.DEFAULT_RMPC_CONFIG.write_text("()", encoding="utf-8") + + result = cli.command_sync( + argparse.Namespace(no_rmpc=False, dry_run=True, refresh=False, yes=False), + Settings(music_dir=tmp_path), + False, + ) + + assert result == 0 + assert f" - {path.with_suffix('.lrc')}" in capsys.readouterr().out + assert not path.with_suffix(".lrc").exists() diff --git a/tests/test_lrc_path_authority.py b/tests/test_lrc_path_authority.py new file mode 100644 index 0000000..4f454d7 --- /dev/null +++ b/tests/test_lrc_path_authority.py @@ -0,0 +1,155 @@ +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import ( + DEFAULT_LYRICS_DIR, + LEGACY_IMPLICIT_LYRICS_DIR, + Settings, + resolve_lyrics_dir, +) + + +def test_legacy_implicit_default_is_guarded_but_explicit_value_is_respected( + tmp_path, monkeypatch +): + import juice_lyrics.cli as cli + + stale = Settings(lyrics_dir=LEGACY_IMPLICIT_LYRICS_DIR) + assert resolve_lyrics_dir(stale) == DEFAULT_LYRICS_DIR + + config = tmp_path / "config.toml" + config.write_text( + f'lyrics_dir = "{LEGACY_IMPLICIT_LYRICS_DIR}"\n', + encoding="utf-8", + ) + monkeypatch.setattr(cli, "CONFIG_FILE", config) + configured = cli.load_settings() + assert configured.lyrics_dir_explicit is True + assert resolve_lyrics_dir(configured) == LEGACY_IMPLICIT_LYRICS_DIR + + +def test_acquisition_ignores_legacy_lrc_override_and_writes_sidecar( + tmp_path, monkeypatch +): + import juice_lyrics.acquisition.integration as integration + from juice_lyrics.acquisition.integration import integrate_downloaded_mp3 + from juice_lyrics.acquisition.models import AcquisitionItem + + music = tmp_path / "Music" / "Juice WRLD" + destination = music / "Rental.mp3" + destination.parent.mkdir(parents=True) + destination.write_bytes(b"pristine") + central = tmp_path / "Music" / "lyrics" + legacy = tmp_path / "Music" / "Juice WRLD" / "lyrics" + outputs: list[Path] = [] + + backup = tmp_path / "backup.mp3" + monkeypatch.setattr(integration, "make_backup_root", lambda: tmp_path / "backup") + monkeypatch.setattr( + integration, + "backup_file", + lambda source, root, base: backup, + ) + monkeypatch.setattr(integration, "write_manifest", lambda *args: None) + monkeypatch.setattr(integration, "embed_lyrics", lambda *args: "SYLT") + monkeypatch.setattr(integration, "verify_file", lambda path: (True, "verified")) + monkeypatch.setattr(integration, "sha256_file", lambda path: "hash") + + def writer(path, synced, song): + outputs.append(path) + result = path.with_suffix(".lrc") + result.write_text("[00:01.00] line\n", encoding="utf-8") + return result + + monkeypatch.setattr(integration, "write_lrc", writer) + item = AcquisitionItem("1", "Rental", "https://example.test/Rental.mp3", destination) + result = integrate_downloaded_mp3( + item, + song_fetcher=lambda _: { + "id": 1, + "name": "Rental", + "synced_lyrics": "[00:01.00] line", + "lyrics": "line", + }, + lyrics_dir=legacy, + settings=Settings(music_dir=music, lyrics_dir=central), + state={}, + notify_rmpc=False, + ) + + assert outputs == [destination] + assert result.lrc_path == destination.with_suffix(".lrc") + assert not central.exists() + assert not legacy.exists() + + +def test_current_cli_read_only_and_failed_write_flows_never_create_legacy_path( + tmp_path +): + home = tmp_path / "home" + env = os.environ.copy() + env.update( + HOME=str(home), + XDG_CONFIG_HOME=str(home / ".config"), + XDG_CACHE_HOME=str(home / ".cache"), + XDG_DATA_HOME=str(home / ".local" / "share"), + PYTHONPATH=str(Path(__file__).resolve().parents[1] / "src"), + ) + command = [sys.executable, "-m", "juice_lyrics.cli"] + legacy = home / "Music" / "Juice WRLD" / "lyrics" + central = home / "Music" / "lyrics" + + initialized = subprocess.run( + [*command, "config", "init"], env=env, text=True, capture_output=True + ) + assert initialized.returncode == 0 + for arguments in ( + ("config", "show"), + ("status",), + ("rmpc", "verify"), + ("rmpc", "sync"), + ): + subprocess.run([*command, *arguments], env=env, text=True, capture_output=True) + assert not legacy.exists(), arguments + + # No synchronized file was authorized, so even the configured destination + # remains absent throughout these inspection/error paths. + assert not central.exists() + + +def test_stale_rmpc_configuration_is_reported_but_cannot_redirect_output(tmp_path): + from juice_lyrics.services.settings_snapshot import ( + IntegrationStatus, + get_settings_snapshot, + ) + + legacy = tmp_path / "Music" / "Juice WRLD" / "lyrics" + central = tmp_path / "Music" / "lyrics" + rmpc = tmp_path / "config.ron" + rmpc.write_text( + f'(\nlyrics_dir: Some("{legacy}"),\n' + "enable_lyrics_index: true,\n" + "enable_lyrics_hot_reload: true,\n)", + encoding="utf-8", + ) + snapshot = get_settings_snapshot( + Settings(music_dir=tmp_path / "music", lyrics_dir=central), + config_path=tmp_path / "missing.toml", + cache_dir=tmp_path / "cache", + state_file=tmp_path / "state.json", + backup_dir=tmp_path / "backups", + jobs_file=tmp_path / "jobs.json", + rmpc_config_path=rmpc, + executable_finder=lambda name: "/usr/bin/rmpc", + ) + + assert snapshot.rmpc.status is IntegrationStatus.DETECTED_NOT_CONFIGURED + assert snapshot.rmpc.config_has_lyrics_support is False + assert not legacy.exists() + assert not central.exists() diff --git a/tests/test_m4a_support.py b/tests/test_m4a_support.py new file mode 100644 index 0000000..bbf946f --- /dev/null +++ b/tests/test_m4a_support.py @@ -0,0 +1,343 @@ +from __future__ import annotations + +import json +import struct +from pathlib import Path + +import pytest +from mutagen.mp4 import MP4 + +from juice_lyrics.backup.manager import backup_file, restore_backup, write_manifest +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.matching import choose_candidate, local_duration, search_title_for +from juice_lyrics.library.media import MediaMetadataError, read_m4a_metadata +from juice_lyrics.library.scanner import find_audio_files, find_mp3s +from juice_lyrics.lyrics.engine import embed_lyrics, verify_file +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + get_library_snapshot, + get_library_status, +) +from juice_lyrics.services.library_sync import ( + LibrarySyncDependencies, + LibrarySyncOptions, + MatchOutcome, + execute_library_sync, + plan_library_sync, +) +from juice_lyrics.state import sha256_file + + +_MEDIA_PAYLOAD = b"synthetic AAC payload remains untouched" + + +def _atom(name: bytes, payload: bytes) -> bytes: + return struct.pack(">I4s", len(payload) + 8, name) + payload + + +def _make_m4a( + path: Path, + *, + title: str | None = "All Life Long", + artist: str | None = "Juice WRLD", + album: str | None = "Unreleased", + track_number: tuple[int, int] | None = None, + duration: float = 2.0, +) -> Path: + """Create a tiny metadata-capable M4A container without external tools.""" + + path.parent.mkdir(parents=True, exist_ok=True) + timescale = 44_100 + movie_header = _atom( + b"mvhd", + b"\0\0\0\0" + + struct.pack(">IIII", 0, 0, timescale, int(timescale * duration)), + ) + path.write_bytes( + _atom(b"ftyp", b"M4A \0\0\0\0M4A mp42") + + _atom(b"moov", movie_header) + + _atom(b"mdat", _MEDIA_PAYLOAD) + ) + tags = MP4(path) + if any(value is not None for value in (title, artist, album, track_number)): + tags.add_tags() + for key, value in (("\xa9nam", title), ("\xa9ART", artist), ("\xa9alb", album)): + if value is not None: + tags[key] = [value] + if track_number is not None: + tags["trkn"] = [track_number] + tags.save() + return path + + +def _candidate(*, synced: bool = True) -> dict[str, object]: + return { + "id": 202, + "name": "All Life Long", + "credited_artists": "Juice WRLD", + "album": "Unreleased", + "length": "0:02", + "category": "unreleased", + "synced_lyrics": "[00:00.50] first\n[00:01.20] second" if synced else "", + "lyrics": "first\nsecond", + } + + +def test_recursive_m4a_discovery_is_case_insensitive_and_narrowly_scoped(tmp_path): + root = tmp_path / "Juice WRLD" + lower = _make_m4a(root / "Album (v2)" / "Légend's [Mix].m4a") + upper = _make_m4a(root / "Nested" / "Song.final.v2.M4A") + outside = _make_m4a(tmp_path / "outside.m4a") + (root / "ignore.mp4").write_bytes(b"video") + (root / "ignore.aac").write_bytes(b"audio") + + assert find_audio_files(root) == sorted([lower, upper], key=lambda path: str(path).casefold()) + assert find_mp3s(Settings(music_dir=root)) == find_audio_files(root) + assert outside not in find_audio_files(root) + + +def test_m4a_metadata_atoms_and_duration_are_read_natively(tmp_path): + path = _make_m4a( + tmp_path / "metadata.m4a", + title="All Life Long (v2)", + artist="Juice WRLD", + album="Test Album", + track_number=(7, 20), + duration=3.25, + ) + + metadata = read_m4a_metadata(path) + + assert metadata.title == "All Life Long (v2)" + assert metadata.artist == "Juice WRLD" + assert metadata.album == "Test Album" + assert metadata.track_number == "7/20" + assert metadata.duration_seconds == pytest.approx(3.25) + assert local_duration(path) == pytest.approx(3.25) + assert search_title_for(path) == "All Life Long" + + no_album = _make_m4a(tmp_path / "no album.m4a", album=None) + assert read_m4a_metadata(no_album).album is None + assert search_title_for(no_album) == "All Life Long" + + +def test_missing_m4a_matching_metadata_is_left_unresolved(tmp_path): + path = _make_m4a(tmp_path / "Do Not Guess.m4a", title=None, artist=None, album=None) + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path), + dry_run=True, + state_file=tmp_path / "missing-state.json", + ) + dependencies = LibrarySyncDependencies( + searcher=lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("API called")), + ) + + with pytest.raises(MediaMetadataError, match="missing title, artist"): + search_title_for(path) + assert verify_file(path) == (False, "no embedded M4A lyrics") + plan = plan_library_sync(options, dependencies=dependencies) + + assert plan.tracks[0].outcome is MatchOutcome.UNRESOLVED + assert "left unmatched" in (plan.tracks[0].error or "") + + +def test_malformed_m4a_is_left_unresolved_instead_of_guessed(tmp_path): + path = tmp_path / "Looks Like A Song.m4a" + path.write_bytes(b"not an MP4 container") + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path), + dry_run=True, + state_file=tmp_path / "missing-state.json", + ) + + plan = plan_library_sync(options, dependencies=LibrarySyncDependencies()) + + assert plan.tracks[0].path == path + assert plan.tracks[0].outcome is MatchOutcome.UNRESOLVED + assert "could not be read" in (plan.tracks[0].error or "") + + +def test_m4a_matching_reuses_normal_version_title_and_duration_scoring(tmp_path): + path = _make_m4a( + tmp_path / "opaque filename.m4a", + title="All Life Long (v2)", + duration=2.0, + ) + right = {**_candidate(), "name": "All Life Long (v2)"} + wrong = {**_candidate(), "name": "All Life Long (v1)"} + + chosen, score, reasons, _ = choose_candidate( + Settings(music_dir=tmp_path), + path, + [wrong, right], + search_title_for(path), + ) + + assert chosen is right + assert score >= 70 + assert "exact version v2" in reasons + assert any(reason.startswith("duration match") for reason in reasons) + + +def test_m4a_plain_embedding_preserves_unrelated_atoms_and_media_payload(tmp_path): + path = _make_m4a(tmp_path / "All Life Long.m4a") + audio = MP4(path) + audio["\xa9cmt"] = ["keep me"] + audio.save() + + result = embed_lyrics(path, [], "ordinary lyrics") + valid, message = verify_file(path) + updated = MP4(path) + + assert result == "M4A_LYRICS" + assert updated["\xa9lyr"] == ["ordinary lyrics"] + assert updated["\xa9cmt"] == ["keep me"] + assert _MEDIA_PAYLOAD in path.read_bytes() + assert valid is True + assert message.startswith("M4A LYRICS") + + +def test_synced_m4a_embeds_plain_text_without_nonstandard_timing(tmp_path): + path = _make_m4a(tmp_path / "All Life Long.m4a") + + embed_lyrics(path, [("first", 500), ("second", 1200)], "") + + assert MP4(path)["\xa9lyr"] == ["first\nsecond"] + assert not any("500" in value or "1200" in value for value in MP4(path)["\xa9lyr"]) + + +def test_m4a_sync_dry_run_writes_nothing(tmp_path): + path = _make_m4a(tmp_path / "Album" / "All Life Long.m4a") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {}}), encoding="utf-8") + before = path.read_bytes() + dependencies = LibrarySyncDependencies( + searcher=lambda settings, title, refresh=False: [_candidate()], + ) + options = LibrarySyncOptions.from_settings( + Settings(music_dir=tmp_path, lyrics_dir=tmp_path / "central"), + dry_run=True, + rmpc_enabled=True, + state_file=state_file, + ) + + plan = plan_library_sync(options, dependencies=dependencies) + result = execute_library_sync(plan, dependencies=dependencies) + + assert plan.ready_files == 1 + assert plan.tracks[0].lrc_path == path.with_suffix(".lrc") + assert result.updated_files == 0 + assert path.read_bytes() == before + assert not path.with_suffix(".lrc").exists() + assert not (tmp_path / "central").exists() + assert state_file.read_text(encoding="utf-8") == json.dumps({"files": {}}) + + +def test_m4a_sync_backs_up_before_mutation_writes_state_sidecar_and_notifies(tmp_path): + music = tmp_path / "music" + path = _make_m4a(music / "Album" / "All Life Long.m4a") + pristine = path.read_bytes() + backup_root = tmp_path / "backups" / "run" + state = {"files": {}} + saved: list[dict[str, object]] = [] + notified: list[list[Path]] = [] + + def make_backup_root() -> Path: + backup_root.mkdir(parents=True, exist_ok=True) + return backup_root + + def checked_embed(target: Path, synced, plain) -> str: + assert (backup_root / target.relative_to(music)).read_bytes() == pristine + return embed_lyrics(target, synced, plain) + + dependencies = LibrarySyncDependencies( + searcher=lambda settings, title, refresh=False: [_candidate()], + backup_root_factory=make_backup_root, + embedder=checked_embed, + state_loader=lambda: state, + state_saver=lambda value: saved.append(json.loads(json.dumps(value))), + rmpc_notifier=lambda paths: notified.append(list(paths)) or len(paths), + ) + options = LibrarySyncOptions.from_settings( + Settings(music_dir=music, lyrics_dir=tmp_path / "central"), + rmpc_enabled=True, + ) + + result = execute_library_sync( + plan_library_sync(options, dependencies=dependencies), + dependencies=dependencies, + ) + + sidecar = path.with_suffix(".lrc") + entry = saved[0]["files"]["Album/All Life Long.m4a"] + assert result.updated_files == 1 + assert result.lrc_files_generated == 1 + assert sidecar.is_file() + assert notified == [[sidecar]] + assert entry["lyric_type"] == "M4A_LYRICS_SYNCED" + assert entry["lrc"] == str(sidecar) + assert entry["sha256"] == sha256_file(path) + assert not (tmp_path / "central").exists() + assert (backup_root / "Album" / "All Life Long.m4a").read_bytes() == pristine + + +def test_m4a_status_distinguishes_embedded_lyrics_and_external_lrc(tmp_path): + music = tmp_path / "music" + path = _make_m4a(music / "All Life Long.m4a") + embed_lyrics(path, [("line", 500)], "plain representation") + sidecar = path.with_suffix(".lrc") + sidecar.write_text("[00:00.50] line\n", encoding="utf-8") + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"All Life Long.m4a": { + "sha256": sha256_file(path), + "song_id": 202, + "api_name": "All Life Long", + "lyric_type": "M4A_LYRICS_SYNCED", + "lrc": str(sidecar), + }}}), encoding="utf-8") + + snapshot = get_library_snapshot(Settings(music_dir=music), state_file=state_file) + track = snapshot.tracks[0] + + assert track.media_format == "M4A" + assert track.title == "All Life Long" + assert track.artist == "Juice WRLD" + assert track.album == "Unreleased" + assert track.match_status is LibraryMatchStatus.MATCHED + assert track.lyric_status is LibraryLyricStatus.PLAIN + assert track.lrc_status is LibraryLrcStatus.PRESENT + assert track.lrc_path == sidecar + assert track.warning is None + + status = get_library_status( + Settings(music_dir=music), + state_file=state_file, + backup_dir=tmp_path / "missing-backups", + ) + assert status.track_count == 1 + assert status.embedded_plain_count == 1 + assert status.embedded_synced_count == 0 + assert status.rmpc_lrc_count == 1 + + +def test_m4a_and_historical_mp3_flac_backups_restore_together(tmp_path): + music = tmp_path / "music" + m4a = _make_m4a(music / "Nested" / "Song.M4A") + mp3 = music / "Old.mp3" + flac = music / "Old.flac" + mp3.write_bytes(b"historical mp3") + flac.write_bytes(b"historical flac") + backup_root = tmp_path / "backups" / "historical" + for path in (m4a, mp3, flac): + backup_file(path, backup_root, music) + path.unlink() + write_manifest(backup_root, [{"file": str(mp3)}]) + + restored = restore_backup(backup_root, music) + + assert restored == 3 + assert MP4(m4a).get("\xa9nam") == ["All Life Long"] + assert mp3.read_bytes() == b"historical mp3" + assert flac.read_bytes() == b"historical flac" diff --git a/tests/test_manual_identity.py b/tests/test_manual_identity.py new file mode 100644 index 0000000..57b9c92 --- /dev/null +++ b/tests/test_manual_identity.py @@ -0,0 +1,334 @@ +from __future__ import annotations + +import json +from dataclasses import replace +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.media import AudioMetadata +from juice_lyrics.services.library_identity import ( + IdentityBackfillDependencies, + backfill_catalogue_identities, +) +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibraryStateStatus, + LibraryTrack, + get_library_snapshot, +) +from juice_lyrics.services.manual_identity import ( + ManualIdentityDependencies, + is_identity_locked, + set_manual_identity, + unlock_manual_identity, +) +from juice_lyrics.state import file_fingerprint, sha256_file + + +def _track(root: Path, name: str = "Album/Song.flac") -> LibraryTrack: + path = root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(b"audio") + return LibraryTrack( + reference=name, + path=path, + relative_path=Path(name), + filename=path.name, + title=path.stem, + duration_seconds=180.0, + match_status=LibraryMatchStatus.UNMATCHED, + matched_title=None, + lyric_status=LibraryLyricStatus.PLAIN, + lrc_status=LibraryLrcStatus.NONE, + lrc_path=None, + state_status=LibraryStateStatus.NEW, + artist="Juice WRLD", + album="Album", + media_format=path.suffix[1:].upper(), + content_fingerprint=file_fingerprint(path), + ) + + +def test_legacy_identity_is_automatic_and_unlocked() -> None: + assert not is_identity_locked({"song_id": 1, "api_name": "Song"}) + assert not is_identity_locked( + { + "song_id": 1, + "api_name": "Song", + "identity_source": "manual", + "identity_locked": False, + } + ) + + +def test_library_snapshot_restores_manual_lock_after_restart(tmp_path): + music = tmp_path / "music" + track = _track(music) + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + track.reference: { + "sha256": sha256_file(track.path), + "song_id": 77, + "api_name": "Chosen", + "identity_source": "manual", + "identity_locked": True, + } + } + } + ), + encoding="utf-8", + ) + snapshot = get_library_snapshot( + Settings(music_dir=music), + state_file=state_file, + verifier=lambda path: (True, "FLAC plain lyrics"), + metadata_reader=lambda path: AudioMetadata( + "Song", "Juice WRLD", "Album", 180.0 + ), + ) + restored = snapshot.tracks[0] + assert restored.match_status is LibraryMatchStatus.MATCHED + assert restored.matched_title == "Chosen" + assert restored.identity_source == "manual" + assert restored.identity_locked is True + + +def test_manual_match_is_atomic_file_bound_and_preserves_unrelated_state(tmp_path): + music = tmp_path / "music" + track = _track(music) + sidecar = track.path.with_suffix(".lrc") + sidecar.write_text("[00:01.00]keep\n", encoding="utf-8") + rmpc = tmp_path / "rmpc.ron" + rmpc.write_text("keep", encoding="utf-8") + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + track.reference: { + "song_id": 123, + "api_name": "Wrong Automatic Match", + "lyric_type": "FLAC_LYRICS_PLAIN", + "custom": {"keep": True}, + } + }, + "top": 42, + } + ), + encoding="utf-8", + ) + audio_before = track.path.read_bytes() + lrc_before = sidecar.read_bytes() + + result = set_manual_identity( + Settings(music_dir=music), + track, + song_id=777, + api_name="Chosen Recording", + state_file=state_file, + ) + + saved = json.loads(state_file.read_text(encoding="utf-8")) + entry = saved["files"][track.reference] + assert result.locked and result.song_id == 777 + assert entry["song_id"] == 777 + assert entry["api_name"] == "Chosen Recording" + assert entry["identity_source"] == "manual" + assert entry["identity_locked"] is True + assert entry["sha256"] == sha256_file(track.path) + assert entry["lyric_type"] == "FLAC_LYRICS_PLAIN" + assert entry["custom"] == {"keep": True} + assert saved["top"] == 42 + assert track.path.read_bytes() == audio_before + assert sidecar.read_bytes() == lrc_before + assert rmpc.read_text(encoding="utf-8") == "keep" + assert not (tmp_path / "backups").exists() + + +def test_locked_identity_is_reused_without_catalogue_search(tmp_path): + music = tmp_path / "music" + track = _track(music, "Song.mp3") + digest = sha256_file(track.path) + track = replace( + track, + content_sha256=digest, + state_status=LibraryStateStatus.CURRENT, + ) + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + track.reference: { + "sha256": digest, + "song_id": 7, + "api_name": "Manual", + "identity_source": "manual", + "identity_locked": True, + } + } + } + ), + encoding="utf-8", + ) + result = backfill_catalogue_identities( + Settings(music_dir=music), + (track,), + state_file=state_file, + dependencies=IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: (_ for _ in ()).throw( + AssertionError("locked identity searched") + ) + ), + ) + assert result.reused == 1 + assert json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ]["song_id"] == 7 + + +def test_changed_audio_recalculation_does_not_transfer_manual_lock(tmp_path): + music = tmp_path / "music" + track = _track(music) + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + track.reference: { + "sha256": "old", + "song_id": 1, + "api_name": "Old", + "identity_source": "manual", + "identity_locked": True, + } + } + } + ), + encoding="utf-8", + ) + candidate = {"id": 2, "name": "New"} + result = backfill_catalogue_identities( + Settings(music_dir=music), + (track,), + state_file=state_file, + dependencies=IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: [candidate], + matcher=lambda *args: (candidate, 100.0, [], []), + search_title=lambda path: "Song", + ), + ) + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ] + assert result.identified == 1 and entry["song_id"] == 2 + assert "identity_source" not in entry + assert "identity_locked" not in entry + + +def test_unlock_clears_identity_but_preserves_lyrics_and_custom_fields(tmp_path): + music = tmp_path / "music" + track = _track(music) + digest = sha256_file(track.path) + state_file = tmp_path / "state.json" + state_file.write_text( + json.dumps( + { + "files": { + track.reference: { + "sha256": digest, + "song_id": 5, + "api_name": "Manual", + "identity_source": "manual", + "identity_locked": True, + "lyric_type": "FLAC_LYRICS_PLAIN", + "custom": 9, + } + } + } + ), + encoding="utf-8", + ) + + result = unlock_manual_identity( + Settings(music_dir=music), track, state_file=state_file + ) + + entry = json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ] + assert result.changed and not result.locked + assert all( + field not in entry + for field in ("song_id", "api_name", "identity_source", "identity_locked") + ) + assert entry["lyric_type"] == "FLAC_LYRICS_PLAIN" + assert entry["custom"] == 9 + + candidate = {"id": 8, "name": "Automatic Later"} + backfill_catalogue_identities( + Settings(music_dir=music), + (track,), + state_file=state_file, + dependencies=IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: [candidate], + matcher=lambda *args: (candidate, 100.0, [], []), + search_title=lambda path: "Song", + ), + ) + reconsidered = json.loads(state_file.read_text(encoding="utf-8"))["files"][ + track.reference + ] + assert reconsidered["song_id"] == 8 + assert "identity_locked" not in reconsidered + + +def test_manual_match_rejects_state_conflict_and_changed_or_missing_audio(tmp_path): + music = tmp_path / "music" + track = _track(music) + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {}}), encoding="utf-8") + + def conflict_hash(path: Path) -> str: + state_file.write_text(json.dumps({"files": {}, "newer": True}), encoding="utf-8") + return sha256_file(path) + + with pytest.raises(RuntimeError, match="state changed"): + set_manual_identity( + Settings(music_dir=music), + track, + song_id=1, + api_name="Song", + state_file=state_file, + dependencies=ManualIdentityDependencies(hasher=conflict_hash), + ) + assert json.loads(state_file.read_text(encoding="utf-8"))["newer"] is True + + track.path.write_bytes(b"replacement") + with pytest.raises(RuntimeError, match="audio file changed"): + set_manual_identity( + Settings(music_dir=music), + track, + song_id=1, + api_name="Song", + state_file=state_file, + ) + track.path.unlink() + with pytest.raises(RuntimeError, match="outside the configured music library"): + set_manual_identity( + Settings(music_dir=music), + track, + song_id=1, + api_name="Song", + state_file=state_file, + ) diff --git a/tests/test_matching.py b/tests/test_matching.py new file mode 100644 index 0000000..41b719c --- /dev/null +++ b/tests/test_matching.py @@ -0,0 +1,307 @@ +from __future__ import annotations + +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library import matching + + +BANDIT_RESULTS = [ + {"id": 95074, "name": "Bandit (v1)", "category": "unreleased", "length": "3:33"}, + {"id": 95295, "name": "Bandit (v2)", "category": "unreleased", "length": "3:22"}, + { + "id": 96405, + "name": "Bandit (with YoungBoy Never Broke Again)", + "category": "recording_session", + "length": "", + }, + { + "id": 95296, + "name": "Bandit (with YoungBoy Never Broke Again) [v1]", + "category": "unreleased", + "length": "3:12", + }, + { + "id": 95297, + "name": "Bandit (with YoungBoy Never Broke Again) [v2]", + "category": "unreleased", + "length": "3:13", + }, + { + "id": 95845, + "name": "Bandit (with YoungBoy Never Broke Again) [v3]", + "category": "unsurfaced", + "length": "", + }, + { + "id": 95298, + "name": "Bandit (with YoungBoy Never Broke Again) [v4]", + "category": "unreleased", + "length": "3:12", + }, + { + "id": 94107, + "name": "Bandit (feat. YoungBoy Never Broke Again)", + "category": "released", + "length": "3:09", + "path": ( + "Compilation/1. Released Discography/15. Death Race For Love " + "(Bonus Track Version)/Bandit (with YoungBoy Never Broke Again).mp3" + ), + }, +] + +TEN_FEET_RESULTS = [ + { + "id": 94102, + "name": "10 Feet", + "category": "released", + "length": "3:36", + "path": "Compilation/1. Released Discography/11. Death Race For Love/10 Feet.mp3", + }, + {"id": 96383, "name": "10 Feet", "category": "recording_session", "length": ""}, + {"id": 95061, "name": "10 Feet (v1)", "category": "unreleased", "length": "3:38"}, + {"id": 95062, "name": "10 Feet (v3)", "category": "unreleased", "length": "3:36"}, + {"id": 94269, "name": "10 Feet (TV Mix) [v1]", "category": "released", "length": "3:36"}, +] + + +def _local(monkeypatch, *, title: str, duration: float, album: str | None) -> Path: + path = Path("opaque.flac") + monkeypatch.setattr(matching, "is_tagged_container", lambda value: True) + monkeypatch.setattr(matching, "tagged_matching_title", lambda value: title) + monkeypatch.setattr(matching, "local_duration", lambda value: duration) + monkeypatch.setattr(matching, "local_album", lambda value: album) + return path + + +def test_bandit_live_candidate_set_selects_released_recording(monkeypatch): + path = _local( + monkeypatch, + title="Bandit (with YoungBoy Never Broke Again)", + duration=189.322562, + album="Death Race For Love (Bonus Track Version)", + ) + + chosen, _, reasons, _ = matching.choose_candidate( + Settings(), path, BANDIT_RESULTS, "Bandit" + ) + diagnostics = matching.diagnose_candidates(Settings(), path, BANDIT_RESULTS, "Bandit") + by_id = {row.song_id: row for row in diagnostics} + + assert chosen is not None and chosen["id"] == 94107 + assert "released (+10)" in reasons + assert "album/path match (+35)" in reasons + assert by_id[96405].rejection == "lower-ranked candidate" + assert by_id[96405].reasons[-1] == "duration unknown (+0)" + assert by_id[95296].score < by_id[94107].score + assert by_id[95297].rejection == "known duration outside tolerance" + assert by_id[95298].score < by_id[94107].score + + +def test_bandit_feat_and_with_collaboration_forms_share_base_identity(): + assert matching.normalize(matching.strip_feature_credit("Bandit (with YoungBoy)")) == matching.normalize( + matching.strip_feature_credit("Bandit (feat. YoungBoy)") + ) + + +def test_ten_feet_live_candidate_set_selects_normal_album_recording(monkeypatch): + path = _local( + monkeypatch, + title="10 Feet", + duration=212.311927, + album="Death Race For Love (Bonus Track Version)", + ) + + chosen, _, reasons, _ = matching.choose_candidate( + Settings(), path, TEN_FEET_RESULTS, "10 Feet" + ) + diagnostics = matching.diagnose_candidates(Settings(), path, TEN_FEET_RESULTS, "10 Feet") + by_id = {row.song_id: row for row in diagnostics} + + assert chosen is not None and chosen["id"] == 94102 + assert any(reason.startswith("duration catalogue grace (3.688s delta") for reason in reasons) + assert "album edition/path match (+30)" in reasons + assert by_id[96383].reasons[-1] == "duration unknown (+0)" + assert by_id[96383].score < by_id[94102].score + assert by_id[95062].eligible is False + assert by_id[94269].eligible is False + assert any("candidate-only variant tv mix" in reason for reason in by_id[94269].reasons) + + +def test_normal_duration_match_scores_more_than_catalogue_grace(monkeypatch): + path = _local( + monkeypatch, + title="Album Song", + duration=212.311927, + album="Example Album (Deluxe Edition)", + ) + normal = { + "id": 1, + "name": "Album Song", + "category": "released", + "length": "3:35", + "album": "Example Album (Deluxe Edition)", + } + grace = {**normal, "id": 2, "length": "3:36"} + + normal_score, normal_reasons = matching.score_candidate(Settings(), path, normal, "Album Song") + grace_score, grace_reasons = matching.score_candidate(Settings(), path, grace, "Album Song") + + assert normal_score > grace_score + assert any(reason.startswith("duration match") for reason in normal_reasons) + assert any(reason.startswith("duration catalogue grace") for reason in grace_reasons) + + +@pytest.mark.parametrize( + "candidate", + [ + {"id": 1, "name": "Album Song (v3)", "category": "released", "length": "3:36", "album": "Example Album"}, + {"id": 2, "name": "Album Song (TV Mix)", "category": "released", "length": "3:36", "album": "Example Album"}, + {"id": 3, "name": "Album Song", "category": "released", "length": "3:36", "album": "Unrelated Album"}, + ], +) +def test_duration_grace_requires_unversioned_unvaried_album_corroboration(monkeypatch, candidate): + path = _local( + monkeypatch, + title="Album Song", + duration=212.311927, + album="Example Album (Bonus Track Version)", + ) + + chosen, _, reasons, _ = matching.choose_candidate(Settings(), path, [candidate], "Album Song") + + assert chosen is None + assert any(reason.startswith("duration mismatch") for reason in reasons) + + +def test_album_edition_compatibility_is_recognized_but_arbitrary_parentheticals_are_not(monkeypatch): + path = _local( + monkeypatch, + title="Album Song", + duration=212.311927, + album="Example Album (Anniversary Edition)", + ) + candidate = {"name": "Album Song", "album": "Example Album"} + + assert matching.album_match_kind(path, candidate) == "edition" + + monkeypatch.setattr(matching, "local_album", lambda value: "Example Album") + assert matching.album_match_kind( + path, {"name": "Album Song", "album": "Example Album (Deluxe Edition)"} + ) == "edition" + + monkeypatch.setattr(matching, "local_album", lambda value: "Example Album (Live in London)") + assert matching.album_match_kind(path, candidate) is None + + +@pytest.mark.parametrize("edition", ["5 Year Anniversary Edition", "5th Anniversary Edition"]) +def test_numbered_anniversary_album_beats_same_recording_in_singles(monkeypatch, edition): + path = _local( + monkeypatch, + title="Lucid Dreams", + duration=239.842, + album=f"Goodbye & Good Riddance ({edition})", + ) + candidates = [ + { + "id": 1, "name": "Lucid Dreams", "category": "released", "length": "3:59", + "path": "Compilation/1. Released Discography/24. Singles & Features/Lucid Dreams.mp3", + }, + { + "id": 2, "name": "Lucid Dreams", "category": "released", "length": "3:59", + "album": "Goodbye & Good Riddance", + "path": "Compilation/1. Released Discography/7. Goodbye & Good Riddance/Lucid Dreams.mp3", + }, + ] + + chosen, _, reasons, _ = matching.choose_candidate(Settings(), path, candidates, "Lucid Dreams") + + assert chosen is candidates[1] + assert "album edition/path match (+30)" in reasons + + +def test_extended_outro_does_not_ambiguous_normal_album_track(monkeypatch): + path = _local( + monkeypatch, title="Can't Die", duration=182.9285, + album="Legends Never Die (5 Year Anniversary Edition)", + ) + candidates = [ + { + "id": 1, "name": "Can't Die", "category": "released", "length": "3:02", + "path": "Compilation/1. Released Discography/12. Legends Never Die/Can't Die.mp3", + }, + { + "id": 2, "name": "Can't Die (Extended Outro)", "category": "released", "length": "3:05", + "album": "Legends Never Die (Extended Outro)", + "path": "Compilation/3. Misc. Discography/Can't Die (Extended Outro).mp3", + }, + ] + + chosen, _, _, _ = matching.choose_candidate(Settings(), path, candidates, "Can't Die") + diagnostics = matching.diagnose_candidates(Settings(), path, candidates, "Can't Die") + + assert chosen is candidates[0] + assert any("candidate-only variant extended outro" in reason for reason in diagnostics[1].reasons) + + +def test_unknown_duration_can_win_with_overwhelming_unopposed_evidence(monkeypatch): + path = _local(monkeypatch, title="Rental", duration=180.0, album=None) + candidate = { + "id": 1, + "name": "Rental", + "category": "recording_session", + "length": "", + "path": "opaque.flac", + } + + chosen, score, reasons, _ = matching.choose_candidate(Settings(), path, [candidate], "Rental") + + assert chosen is candidate + assert score >= matching.MATCH_THRESHOLD + assert "duration unknown (+0)" in reasons + + +def test_same_title_same_duration_candidates_remain_ambiguous(monkeypatch): + path = _local(monkeypatch, title="Song", duration=180.0, album=None) + candidates = [ + {"id": 1, "name": "Song", "category": "recording_session", "length": "3:00"}, + {"id": 2, "name": "Song", "category": "recording_session", "length": "3:00"}, + ] + + chosen, _, _, _ = matching.choose_candidate(Settings(), path, candidates, "Song") + diagnostics = matching.diagnose_candidates(Settings(), path, candidates, "Song") + + assert chosen is None + assert all(row.rejection == "ambiguous within safety margin" for row in diagnostics) + + +def test_known_duration_outside_tolerance_remains_ineligible(monkeypatch): + path = _local(monkeypatch, title="Song", duration=180.0, album=None) + candidate = {"id": 1, "name": "Song", "category": "released", "length": "4:00"} + + chosen, _, _, _ = matching.choose_candidate(Settings(), path, [candidate], "Song") + diagnostic = matching.diagnose_candidates(Settings(), path, [candidate], "Song")[0] + + assert chosen is None + assert diagnostic.eligible is False + assert diagnostic.rejection == "known duration outside tolerance" + + +@pytest.mark.parametrize("suffix", [".mp3", ".flac", ".m4a"]) +def test_supported_formats_share_identical_ranking_semantics(monkeypatch, suffix): + path = _local(monkeypatch, title="10 Feet", duration=216.0, album="Death Race For Love") + path = path.with_suffix(suffix) + + chosen, score, reasons, _ = matching.choose_candidate( + Settings(), path, TEN_FEET_RESULTS, "10 Feet" + ) + + assert chosen is not None and chosen["id"] == 94102 + assert score > 0 + assert "album/path match (+35)" in reasons diff --git a/tests/test_metadata_audit.py b/tests/test_metadata_audit.py new file mode 100644 index 0000000..041ce93 --- /dev/null +++ b/tests/test_metadata_audit.py @@ -0,0 +1,255 @@ +from __future__ import annotations + +from dataclasses import replace +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.media import AudioMetadata, read_mp3_metadata +from juice_lyrics.services.catalogue import LyricAvailability, SongDetails +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibraryStateStatus, + LibraryTrack, +) +from juice_lyrics.services.metadata_audit import ( + MetadataProposalConfidence, + audit_track_metadata, + build_metadata_audit, +) + + +def _track(path: Path, *, locked: bool = False, catalogue_id=42) -> LibraryTrack: + return LibraryTrack( + reference=path.name, + path=path, + relative_path=Path(path.name), + filename=path.name, + title=path.stem, + duration_seconds=212.3, + match_status=( + LibraryMatchStatus.MATCHED + if catalogue_id is not None + else LibraryMatchStatus.UNMATCHED + ), + matched_title="10 Feet" if catalogue_id is not None else None, + lyric_status=LibraryLyricStatus.PLAIN, + lrc_status=LibraryLrcStatus.PRESENT, + lrc_path=path.with_suffix(".lrc"), + state_status=LibraryStateStatus.CURRENT, + media_format=path.suffix[1:].upper(), + content_sha256="saved-hash", + identity_source="manual" if locked else "automatic", + identity_locked=locked, + catalogue_id=catalogue_id, + ) + + +def _details(**changes) -> SongDetails: + values = { + "selection_index": 1, + "song_id": 42, + "title": "10 Feet", + "category": "released", + "era": "DRFL", + "length": "3:32", + "artists": ("Juice WRLD",), + "producers": (), + "media_path": "Released/Death Race For Love/10 Feet.mp3", + "lyrics": LyricAvailability.SYNCED, + "synced_lyrics": None, + "plain_lyrics": None, + "downloadable": False, + "album": "Death Race For Love", + "track_number": "8", + } + values.update(changes) + return SongDetails(**values) + + +@pytest.mark.parametrize("suffix", (".mp3", ".flac", ".m4a")) +def test_missing_supported_fields_are_confident_for_all_formats(tmp_path, suffix): + path = tmp_path / f"track{suffix}" + path.write_bytes(b"unchanged audio") + track = _track(path, locked=True) + + audit = audit_track_metadata( + Settings(music_dir=tmp_path), + track, + metadata_reader=lambda path: AudioMetadata(None, None, None, 212.3, None), + details_provider=lambda settings, song_id: _details(), + ) + + assert {item.field for item in audit.proposals} == { + "title", "artist", "album", "track_number" + } + assert all( + item.confidence is MetadataProposalConfidence.CONFIDENT + for item in audit.proposals + ) + assert "selected and locked manually" in " ".join(audit.notes) + assert path.read_bytes() == b"unchanged audio" + + +def test_existing_valid_differences_require_review_not_replacement(tmp_path): + track = _track(tmp_path / "track.flac") + audit = build_metadata_audit( + track, + AudioMetadata("10 Feet", "Juice WRLD", "My DRFL Edition", 212.3, "08"), + _details(), + ) + + assert {item.field for item in audit.proposals} == {"album", "track_number"} + assert all( + item.confidence is MetadataProposalConfidence.REVIEW + for item in audit.proposals + ) + assert all("user review" in item.reason for item in audit.proposals) + + +@pytest.mark.parametrize( + "local_title", + ("Song (Live)", "Song (v2)", "Song (Recording Session)", "Song (Extended)"), +) +def test_version_sensitive_title_is_never_a_confident_repair(tmp_path, local_title): + audit = build_metadata_audit( + _track(tmp_path / "track.m4a"), + AudioMetadata(local_title, "Juice WRLD", None, 200.0), + _details(title="Song", album=None, track_number=None), + ) + + title = next(item for item in audit.proposals if item.field == "title") + assert title.confidence is MetadataProposalConfidence.REVIEW + assert "different recording/version markers" in title.reason + + +def test_file_change_during_preview_rejects_all_proposals(tmp_path): + path = tmp_path / "track.flac" + path.write_bytes(b"audio") + fingerprints = iter(((1, 1, 1, 1, 1), (2, 1, 1, 1, 1))) + + audit = audit_track_metadata( + Settings(music_dir=tmp_path), + _track(path), + metadata_reader=lambda path: AudioMetadata(None, None, None, 212.3), + details_provider=lambda settings, song_id: _details(), + fingerprint_reader=lambda path: next(fingerprints), + ) + + assert audit.proposals == () + assert audit.error == "Refresh the Library and try again." + + +def test_manual_lock_is_not_trusted_after_snapshot_fingerprint_changes(tmp_path): + path = tmp_path / "track.m4a" + path.write_bytes(b"replacement") + calls = [] + track = replace( + _track(path, locked=True), + content_fingerprint=(1, 1, 1, 1, 1), + ) + + audit = audit_track_metadata( + Settings(music_dir=tmp_path), + track, + metadata_reader=lambda path: calls.append("metadata"), + details_provider=lambda settings, song_id: calls.append("catalogue"), + fingerprint_reader=lambda path: (2, 1, 1, 1, 1), + ) + + assert audit.proposals == () + assert audit.error == "Sync Library and try again." + assert calls == [] + + +def test_unknown_identity_does_not_read_tags_or_call_catalogue(tmp_path): + calls = [] + audit = audit_track_metadata( + Settings(music_dir=tmp_path), + _track(tmp_path / "unknown.mp3", catalogue_id=None), + metadata_reader=lambda path: calls.append("metadata"), + details_provider=lambda settings, song_id: calls.append("catalogue"), + fingerprint_reader=lambda path: calls.append("fingerprint"), + ) + + assert audit.proposals == () + assert calls == [] + assert "not guessed" in " ".join(audit.notes) + + +def test_incomplete_or_inconsistent_catalogue_data_is_not_guessed(tmp_path): + path = tmp_path / "track.mp3" + path.write_bytes(b"unchanged") + local = AudioMetadata(None, None, None, 212.3, None) + incomplete = audit_track_metadata( + Settings(music_dir=tmp_path), + _track(path), + metadata_reader=lambda path: local, + details_provider=lambda settings, song_id: _details( + title="10 Feet", artists=(), album=None, track_number=None + ), + ) + inconsistent = audit_track_metadata( + Settings(music_dir=tmp_path), + _track(path), + metadata_reader=lambda path: local, + details_provider=lambda settings, song_id: _details(song_id=99), + ) + + assert [item.field for item in incomplete.proposals] == ["title"] + assert inconsistent.proposals == () + assert "inconsistent" in " ".join(inconsistent.notes) + + +def test_audit_is_read_only_for_media_state_lyrics_backups_and_rmpc(tmp_path): + media = tmp_path / "track.flac" + sidecar = tmp_path / "track.lrc" + state = tmp_path / "state.json" + backup = tmp_path / "backup.json" + rmpc = tmp_path / "rmpc.ron" + files = { + media: b"audio", + sidecar: b"[00:01.00]lyrics", + state: b'{"custom": true}', + backup: b"backup", + rmpc: b"config", + } + for path, data in files.items(): + path.write_bytes(data) + + audit = audit_track_metadata( + Settings(music_dir=tmp_path), + _track(media), + metadata_reader=lambda path: AudioMetadata(None, None, None, 212.3), + details_provider=lambda settings, song_id: _details(), + ) + + assert audit.confident_count == 4 + assert {path: path.read_bytes() for path in files} == files + + +def test_mp3_reader_exposes_supported_repair_fields(monkeypatch, tmp_path): + class Frame: + def __init__(self, value): + self.text = [value] + + class FakeMp3: + tags = { + "TIT2": Frame("Title"), + "TPE1": Frame("Artist"), + "TALB": Frame("Album"), + "TRCK": Frame("4/18"), + } + info = type("Info", (), {"length": 123.5})() + + monkeypatch.setattr("juice_lyrics.library.media.MP3", lambda path: FakeMp3()) + + metadata = read_mp3_metadata(tmp_path / "track.mp3") + + assert metadata == AudioMetadata("Title", "Artist", "Album", 123.5, "4/18") diff --git a/tests/test_metadata_repair.py b/tests/test_metadata_repair.py new file mode 100644 index 0000000..334436d --- /dev/null +++ b/tests/test_metadata_repair.py @@ -0,0 +1,569 @@ +from __future__ import annotations + +import json +import os +import struct +import sys +from dataclasses import replace +from pathlib import Path + +import pytest +from mutagen.flac import FLAC, Picture +from mutagen.id3 import APIC, ID3, TALB, TIT2, TXXX, USLT +from mutagen.mp4 import MP4, MP4Cover + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.backup.manager import backup_file, restore_file, write_manifest +from juice_lyrics.config.settings import Settings +from juice_lyrics.library.media import read_audio_metadata +from juice_lyrics.services.catalogue import LyricAvailability, SongDetails +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibraryStateStatus, + LibraryTrack, + get_library_snapshot, +) +from juice_lyrics.services.library_identity import IdentityBackfillDependencies +from juice_lyrics.services.library_index_sync import ( + LibraryIndexSyncDependencies, + sync_library_index, +) +from juice_lyrics.services.library_issues import ( + LibraryIssueCategory, + get_library_health, +) +from juice_lyrics.services.metadata_audit import build_metadata_audit +from juice_lyrics.services.metadata_repair import ( + MetadataRepairDependencies, + execute_metadata_repair, + inspect_media_preservation, + plan_metadata_repair, + write_metadata_fields, +) +from juice_lyrics.state import file_fingerprint, read_state_file, sha256_file, write_state_file + + +def _make_mp3(path: Path) -> Path: + path.parent.mkdir(parents=True, exist_ok=True) + frame = b"\xff\xfb\x90\x64" + b"\0" * 413 + path.write_bytes(frame * 12) + tags = ID3() + tags.add(TIT2(encoding=3, text=["Old title"])) + tags.add(TALB(encoding=3, text=["Album"])) + tags.add(USLT(encoding=3, lang="eng", desc="kept", text="embedded lyrics")) + tags.add(TXXX(encoding=3, desc="custom", text=["keep me"])) + tags.add(APIC(encoding=3, mime="image/jpeg", type=3, desc="cover", data=b"artwork")) + tags.save(path) + # Real-world files often retain ID3v1 alongside ID3v2. Selected common + # fields may legitimately change in both; unrelated v1 bytes must not. + id3v1 = ( + b"TAG" + + b"Old title".ljust(30, b"\0") + + b"Original artist".ljust(30, b"\0") + + b"Album".ljust(30, b"\0") + + b"2020" + + b"keep this comment".ljust(28, b"\0") + + b"\0\x01" + + b"\x0d" + ) + with path.open("ab") as handle: + handle.write(id3v1) + return path + + +def _make_flac(path: Path) -> Path: + path.parent.mkdir(parents=True, exist_ok=True) + sample_rate = 44_100 + total_samples = sample_rate * 2 + packed = (sample_rate << 44) | ((2 - 1) << 41) | ((16 - 1) << 36) | total_samples + stream_info = ( + struct.pack(">HH", 4096, 4096) + + b"\0" * 6 + + packed.to_bytes(8, "big") + + b"\0" * 16 + ) + path.write_bytes(b"fLaC" + b"\x80" + len(stream_info).to_bytes(3, "big") + stream_info) + audio = FLAC(path) + audio["TITLE"] = ["Old title"] + audio["ALBUM"] = ["Album"] + audio["LYRICS"] = ["embedded lyrics"] + audio["CUSTOM"] = ["keep me"] + picture = Picture() + picture.type = 3 + picture.mime = "image/jpeg" + picture.desc = "cover" + picture.data = b"artwork" + audio.add_picture(picture) + audio.save() + return path + + +def _atom(name: bytes, payload: bytes) -> bytes: + return struct.pack(">I4s", len(payload) + 8, name) + payload + + +def _make_m4a(path: Path) -> Path: + path.parent.mkdir(parents=True, exist_ok=True) + timescale = 44_100 + movie_header = _atom( + b"mvhd", + b"\0\0\0\0" + struct.pack(">IIII", 0, 0, timescale, timescale * 2), + ) + path.write_bytes( + _atom(b"ftyp", b"M4A \0\0\0\0M4A mp42") + + _atom(b"moov", movie_header) + + _atom(b"mdat", b"synthetic AAC payload") + ) + audio = MP4(path) + audio.add_tags() + audio["\xa9nam"] = ["Old title"] + audio["\xa9alb"] = ["Album"] + audio["\xa9lyr"] = ["embedded lyrics"] + audio["covr"] = [MP4Cover(b"artwork", imageformat=MP4Cover.FORMAT_JPEG)] + audio["----:com.apple.iTunes:custom"] = [b"keep me"] + audio.save() + return path + + +def _fixture(tmp_path: Path, suffix: str, *, locked: bool = True): + root = tmp_path / "music" + makers = {".mp3": _make_mp3, ".flac": _make_flac, ".m4a": _make_m4a} + path = makers[suffix](root / f"Album/track{suffix}") + sidecar = path.with_suffix(".lrc") + sidecar.write_bytes(b"[00:01.00]sidecar stays unchanged\n") + digest = sha256_file(path) + fingerprint = file_fingerprint(path) + reference = str(path.relative_to(root)) + entry = { + "sha256": digest, + "song_id": 42, + "api_name": "New title", + "lyric_type": "keep", + "lrc": str(sidecar), + "custom": {"preserve": True}, + } + if locked: + entry.update(identity_source="manual", identity_locked=True) + state_file = tmp_path / "data/state.json" + write_state_file(state_file, {"files": {reference: entry}, "top_custom": 9}) + track = LibraryTrack( + reference=reference, + path=path, + relative_path=path.relative_to(root), + filename=path.name, + title="Old title", + duration_seconds=2.0, + match_status=LibraryMatchStatus.MATCHED, + matched_title="New title", + lyric_status=LibraryLyricStatus.PLAIN, + lrc_status=LibraryLrcStatus.PRESENT, + lrc_path=sidecar, + state_status=LibraryStateStatus.CURRENT, + artist=None, + album="Album", + media_format=suffix[1:].upper(), + content_sha256=digest, + content_fingerprint=fingerprint, + identity_source="manual" if locked else "automatic", + identity_locked=locked, + catalogue_id=42, + ) + details = SongDetails( + 1, + 42, + "New title", + "released", + "DRFL", + "0:02", + ("Juice WRLD",), + (), + "Released/Album/New title.mp3", + LyricAvailability.PLAIN, + None, + None, + False, + album="Album", + track_number="2/20", + ) + audit = build_metadata_audit(track, read_audio_metadata(path), details) + return Settings(music_dir=root), track, audit, state_file, sidecar + + +def _dependencies(tmp_path: Path, **changes) -> MetadataRepairDependencies: + root = tmp_path / "backups/one" + values = dict( + backup_root_factory=lambda: root, + backup_writer=backup_file, + manifest_writer=write_manifest, + restorer=restore_file, + state_reader=read_state_file, + state_writer=write_state_file, + ) + values.update(changes) + return MetadataRepairDependencies(**values) + + +def _assert_unrelated_metadata_preserved(path: Path) -> None: + if path.suffix == ".mp3": + tags = ID3(path) + assert tags.getall("USLT")[0].text == "embedded lyrics" + assert tags.getall("APIC")[0].data == b"artwork" + assert tags.getall("TXXX")[0].text == ["keep me"] + id3v1 = path.read_bytes()[-128:] + assert id3v1[63:93].rstrip(b"\0") == b"Album" + assert id3v1[93:97] == b"2020" + assert id3v1[97:125].rstrip(b"\0") == b"keep this comment" + assert id3v1[127] == 0x0D + elif path.suffix == ".flac": + audio = FLAC(path) + assert audio["lyrics"] == ["embedded lyrics"] + assert audio["custom"] == ["keep me"] + assert audio.pictures[0].data == b"artwork" + else: + audio = MP4(path) + assert audio["\xa9lyr"] == ["embedded lyrics"] + assert bytes(audio["covr"][0]) == b"artwork" + assert audio["----:com.apple.iTunes:custom"] == [b"keep me"] + + +@pytest.mark.parametrize("suffix", (".mp3", ".flac", ".m4a")) +def test_safe_apply_repairs_selected_fields_and_preserves_everything_else(tmp_path, suffix): + settings, track, audit, state_file, sidecar = _fixture(tmp_path, suffix) + original = track.path.read_bytes() + sidecar_before = sidecar.read_bytes() + deps = _dependencies(tmp_path) + plan = plan_metadata_repair( + settings, + audit, + ("title", "artist", "track_number"), + state_file=state_file, + dependencies=deps, + ) + + result = execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + metadata = read_audio_metadata(track.path) + assert metadata.title == "New title" + assert metadata.artist == "Juice WRLD" + assert metadata.album == "Album" + assert metadata.track_number in {"2/20", "2"} or metadata.track_number.startswith("2/") + assert sidecar.read_bytes() == sidecar_before + assert result.sha256_before == sha256_file(result.backup_path) + assert result.sha256_after == sha256_file(track.path) + assert result.sha256_before != result.sha256_after + state = read_state_file(state_file) + entry = state["files"][track.reference] + assert entry["sha256"] == result.sha256_after + assert entry["song_id"] == 42 and entry["api_name"] == "New title" + assert entry["identity_source"] == "manual" and entry["identity_locked"] is True + assert entry["lyric_type"] == "keep" and entry["custom"] == {"preserve": True} + assert state["top_custom"] == 9 + assert result.identity_lock_preserved is True + _assert_unrelated_metadata_preserved(track.path) + assert json.loads((result.backup_root / "manifest.json").read_text())["files"][0]["operation"] == "metadata_repair" + assert original == result.backup_path.read_bytes() + + +def test_plan_requires_explicit_previewed_field_selection(tmp_path): + settings, _, audit, state_file, _ = _fixture(tmp_path, ".flac") + deps = _dependencies(tmp_path) + + with pytest.raises(RuntimeError, match="Select at least one"): + plan_metadata_repair(settings, audit, (), state_file=state_file, dependencies=deps) + with pytest.raises(RuntimeError, match="not present"): + plan_metadata_repair( + settings, audit, ("album",), state_file=state_file, dependencies=deps + ) + + +def test_track_number_write_preserves_id3v1_v10_comment(tmp_path): + path = _make_mp3(tmp_path / "track.mp3") + data = bytearray(path.read_bytes()) + comment = b"123456789012345678901234567890" + data[-31:-1] = comment + path.write_bytes(data) + before = inspect_media_preservation(path, frozenset({"track_number"})) + + write_metadata_fields(path, {"track_number": "2/20"}) + + assert inspect_media_preservation(path, frozenset({"track_number"})) == before + assert path.read_bytes()[-31:-1] == comment + + +def test_execution_requires_confirmation_and_creates_no_backup_without_it(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".m4a") + deps = _dependencies(tmp_path) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + before = track.path.read_bytes() + + with pytest.raises(RuntimeError, match="explicit confirmation"): + execute_metadata_repair(plan, dependencies=deps) + + assert track.path.read_bytes() == before + assert not (tmp_path / "backups").exists() + + +def test_backup_failure_stops_before_mutation(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".mp3") + before = track.path.read_bytes() + deps = _dependencies( + tmp_path, + backup_writer=lambda *args: (_ for _ in ()).throw(OSError("backup full")), + ) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(OSError, match="backup full"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + assert read_state_file(state_file)["files"][track.reference]["sha256"] == sha256_file(track.path) + + +def test_manifest_failure_stops_before_mutation_with_recoverable_copy(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".m4a") + before = track.path.read_bytes() + deps = _dependencies( + tmp_path, + manifest_writer=lambda *args: (_ for _ in ()).throw(OSError("manifest failed")), + ) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(OSError, match="manifest failed"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + assert (tmp_path / "backups/one/Album/track.m4a").read_bytes() == before + + +def test_interruption_while_editing_temporary_copy_leaves_original_unchanged(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".flac") + before = track.path.read_bytes() + deps = _dependencies( + tmp_path, + tag_writer=lambda *args: (_ for _ in ()).throw(KeyboardInterrupt()), + ) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(KeyboardInterrupt): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + assert not tuple(track.path.parent.glob(f".{track.path.name}.*{track.path.suffix}")) + + +def test_state_conflict_during_temporary_edit_aborts_before_replace(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".m4a") + before = track.path.read_bytes() + + def conflicting_writer(path, values): + write_metadata_fields(path, values) + state_file.write_text('{"files": {}, "concurrent": true}', encoding="utf-8") + + deps = _dependencies(tmp_path, tag_writer=conflicting_writer) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(RuntimeError, match="state changed"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + assert json.loads(state_file.read_text())["concurrent"] is True + + +def test_state_write_failure_rolls_back_replaced_audio_and_preserves_lock(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".mp3") + before = track.path.read_bytes() + state_before = state_file.read_bytes() + deps = _dependencies( + tmp_path, + state_writer=lambda *args: (_ for _ in ()).throw(OSError("state unavailable")), + ) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(OSError, match="state unavailable"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + assert state_file.read_bytes() == state_before + assert read_state_file(state_file)["files"][track.reference]["identity_locked"] is True + + +def test_rollback_failure_is_reported_and_backup_remains_recoverable(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".mp3") + deps = _dependencies( + tmp_path, + state_writer=lambda *args: (_ for _ in ()).throw(OSError("state unavailable")), + restorer=lambda *args: (_ for _ in ()).throw(OSError("restore unavailable")), + ) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(RuntimeError, match="automatic rollback failed"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + backup = tmp_path / "backups/one/Album/track.mp3" + assert sha256_file(backup) == plan.original_sha256 + assert read_state_file(state_file)["files"][track.reference]["sha256"] == plan.original_sha256 + + +def test_interruption_immediately_after_atomic_replace_rolls_back(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".m4a") + before = track.path.read_bytes() + + def replace_then_interrupt(source, destination): + os.replace(source, destination) + raise KeyboardInterrupt() + + deps = _dependencies(tmp_path, replacer=replace_then_interrupt) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(KeyboardInterrupt): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + assert read_state_file(state_file)["files"][track.reference]["sha256"] == plan.original_sha256 + + +def test_interruption_after_atomic_state_write_restores_state_and_audio(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".flac") + audio_before = track.path.read_bytes() + state_before = state_file.read_bytes() + + def write_then_interrupt(path, state): + write_state_file(path, state) + raise KeyboardInterrupt() + + deps = _dependencies(tmp_path, state_writer=write_then_interrupt) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(KeyboardInterrupt): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == audio_before + assert state_file.read_bytes() == state_before + + +def test_changed_audio_or_state_is_rejected_before_backup(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".flac") + deps = _dependencies(tmp_path) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + state_file.write_text('{"files": {}, "changed": true}', encoding="utf-8") + + with pytest.raises(RuntimeError, match="state changed"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert not (tmp_path / "backups").exists() + + settings2, track2, audit2, state_file2, _ = _fixture(tmp_path / "second", ".flac") + deps2 = _dependencies(tmp_path / "second") + plan2 = plan_metadata_repair( + settings2, audit2, ("title",), state_file=state_file2, dependencies=deps2 + ) + track2.path.write_bytes(track2.path.read_bytes() + b"changed") + with pytest.raises(RuntimeError, match="audio changed"): + execute_metadata_repair(plan2, confirmed=True, dependencies=deps2) + assert not (tmp_path / "second/backups").exists() + + +def test_unrelated_tag_change_on_working_copy_is_detected(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".flac") + before = track.path.read_bytes() + + def corrupting_writer(path, values): + write_metadata_fields(path, values) + audio = FLAC(path) + audio["LYRICS"] = ["damaged"] + audio.save() + + deps = _dependencies(tmp_path, tag_writer=corrupting_writer) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + with pytest.raises(RuntimeError, match="unrelated tags"): + execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + assert track.path.read_bytes() == before + + +def test_automatic_identity_remains_unlocked_after_verified_edit(tmp_path): + settings, track, audit, state_file, _ = _fixture(tmp_path, ".m4a", locked=False) + deps = _dependencies(tmp_path) + plan = plan_metadata_repair( + settings, audit, ("title",), state_file=state_file, dependencies=deps + ) + + result = execute_metadata_repair(plan, confirmed=True, dependencies=deps) + + entry = read_state_file(state_file)["files"][track.reference] + assert result.identity_lock_preserved is False + assert "identity_locked" not in entry and "identity_source" not in entry + + +@pytest.mark.parametrize("suffix", (".mp3", ".flac", ".m4a")) +def test_verified_repair_then_sync_preserves_lock_and_refreshes_health(tmp_path, suffix): + settings, track, audit, state_file, _ = _fixture(tmp_path, suffix) + repair_deps = _dependencies(tmp_path) + plan = plan_metadata_repair( + settings, + audit, + ("title", "artist"), + state_file=state_file, + dependencies=repair_deps, + ) + + repair = execute_metadata_repair( + plan, + confirmed=True, + dependencies=repair_deps, + ) + refreshed = get_library_snapshot(settings, state_file=state_file) + searches = [] + sync_deps = LibraryIndexSyncDependencies( + identity=IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: searches.append(args) or [], + ) + ) + synced = sync_library_index( + settings, + previous_snapshot=refreshed, + state_file=state_file, + dependencies=sync_deps, + ) + + updated_track = synced.snapshot.tracks[0] + entry = read_state_file(state_file)["files"][track.reference] + categories = { + category + for issue in get_library_health(synced.snapshot).issues + for category in issue.categories + } + assert repair.sha256_after == entry["sha256"] == updated_track.content_sha256 + assert entry["song_id"] == 42 and entry["identity_locked"] is True + assert updated_track.identity_locked is True + assert updated_track.catalogue_id == 42 + assert updated_track.state_status is LibraryStateStatus.CURRENT + assert LibraryIssueCategory.STATE not in categories + assert LibraryIssueCategory.CATALOGUE not in categories + assert searches == [] diff --git a/tests/test_missing_library.py b/tests/test_missing_library.py new file mode 100644 index 0000000..e0977bc --- /dev/null +++ b/tests/test_missing_library.py @@ -0,0 +1,126 @@ +from pathlib import Path +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.catalogue import CataloguePage, CatalogueSearchResult, LyricAvailability +from juice_lyrics.services.library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, +) +from juice_lyrics.services.missing_library import CatalogueCoverage, get_missing_library + + +def _result(song_id, title, *, category="released", path=None): + return CatalogueSearchResult( + 1, song_id, title, category, "DRFL", "3:20", ("Juice WRLD",), (), + path or f"Compilation/{title}.mp3", LyricAvailability.SYNCED, True, + ) + + +def _track(root: Path, name: str, song_id=None, *, media_format="MP3", locked=False): + path = root / name + return LibraryTrack( + name, path, Path(name), name, path.stem, 200.0, + LibraryMatchStatus.MATCHED if song_id is not None else LibraryMatchStatus.UNMATCHED, + path.stem if song_id is not None else None, + LibraryLyricStatus.PLAIN, LibraryLrcStatus.PRESENT, path.with_suffix(".lrc"), + LibraryStateStatus.CURRENT, media_format=media_format, + catalogue_id=song_id, identity_locked=locked, + identity_source="manual" if locked else "automatic", + ) + + +def _snapshot(root, *tracks): + return LibrarySnapshot(root, True, tracks) + + +def test_missing_library_compares_exact_recording_ids_across_pages_and_formats(tmp_path): + root = tmp_path / "music" + snapshot = _snapshot( + root, + _track(root, "Owned.mp3", 1), + _track(root, "Locked.flac", "2", media_format="FLAC", locked=True), + _track(root, "Unknown.m4a", None, media_format="M4A"), + ) + calls = [] + + def pages(settings, query, *, page, page_size, refresh): + calls.append((query, page, page_size, refresh)) + if page == 1: + return CataloguePage((_result(1, "Owned"), _result(2, "Locked")), 1, 2, 4, 2, None) + return CataloguePage((_result(3, "Missing"), _result(4, "Missing (v2)", category="unreleased")), 2, 2, 4, None, 1) + + report = get_missing_library(Settings(music_dir=root), snapshot, page_provider=pages, page_size=2) + + assert [item.song_id for item in report.recordings] == [3, 4] + assert report.owned_ids == {"1", "2"} + assert report.local_unknown_count == 1 + assert report.coverage is CatalogueCoverage.COMPLETE + assert calls == [("", 1, 2, False), ("", 2, 2, False)] + + +def test_duplicate_titles_and_versions_are_distinct_by_id(tmp_path): + root = tmp_path / "music" + page = CataloguePage( + (_result(10, "Song"), _result(11, "Song"), _result(12, "Song (Live)", category="released")), + 1, 100, 3, None, None, + ) + report = get_missing_library( + Settings(music_dir=root), _snapshot(root, _track(root, "Song.mp3", 10)), + page_provider=lambda *args, **kwargs: page, + ) + assert [(item.song_id, item.title) for item in report.recordings] == [(11, "Song"), (12, "Song (Live)")] + + +def test_partial_page_failure_never_claims_complete_catalogue(tmp_path): + root = tmp_path / "music" + + def pages(settings, query, *, page, **kwargs): + if page == 2: + raise RuntimeError("offline") + return CataloguePage((_result(1, "Visible"),), 1, 1, 2, 2, None) + + report = get_missing_library(Settings(music_dir=root), _snapshot(root), page_provider=pages) + assert report.coverage is CatalogueCoverage.PARTIAL + assert report.missing_count == 1 + assert report.error == "offline" + + +def test_offline_before_first_page_reports_unavailable(tmp_path): + root = tmp_path / "music" + + def unavailable(*args, **kwargs): + raise RuntimeError("network unavailable") + + report = get_missing_library(Settings(music_dir=root), _snapshot(root), page_provider=unavailable) + assert report.coverage is CatalogueCoverage.UNAVAILABLE + assert report.recordings == () + assert report.error == "network unavailable" + + +def test_malformed_identity_makes_coverage_partial_and_is_not_called_missing(tmp_path): + root = tmp_path / "music" + page = CataloguePage((_result(None, "No stable ID"), _result(3, "Missing")), 1, 100, 2, None, None) + report = get_missing_library( + Settings(music_dir=root), _snapshot(root), page_provider=lambda *args, **kwargs: page, + ) + assert [item.song_id for item in report.recordings] == [3] + assert report.unidentifiable_catalogue_count == 1 + assert report.coverage is CatalogueCoverage.PARTIAL + + +def test_repeated_catalogue_ids_are_deduplicated_without_title_matching(tmp_path): + root = tmp_path / "music" + page = CataloguePage((_result(7, "First"), _result(7, "Duplicate API row")), 1, 100, 2, None, None) + report = get_missing_library( + Settings(music_dir=root), _snapshot(root, _track(root, "First.flac", None, media_format="FLAC")), + page_provider=lambda *args, **kwargs: page, + ) + assert [item.song_id for item in report.recordings] == [7] + assert report.local_unknown_count == 1 diff --git a/tests/test_packaging.py b/tests/test_packaging.py new file mode 100644 index 0000000..9047fdd --- /dev/null +++ b/tests/test_packaging.py @@ -0,0 +1,80 @@ +from __future__ import annotations + +from pathlib import Path +import sys +import tomllib + +PROJECT_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(PROJECT_ROOT / "src")) + +from juice_lyrics import __version__ + + +def _pyproject() -> dict: + return tomllib.loads( + (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8") + ) + + +def test_distribution_metadata_has_one_version_authority_and_current_entry_points(): + project = _pyproject() + + assert project["project"]["name"] == "juice-wrld-lyrics" + assert project["project"]["dynamic"] == ["version"] + assert "version" not in project["project"] + assert project["tool"]["setuptools"]["dynamic"]["version"] == { + "attr": "juice_lyrics.__version__" + } + assert __version__ == "2.0.0b1" + assert project["project"]["scripts"] == { + "999": "juice_lyrics.cli:main", + "juice-lyrics": "juice_lyrics.cli:main", + } + + +def test_distribution_metadata_uses_current_license_and_bounded_dependencies(): + project = _pyproject() + + assert project["build-system"]["requires"] == ["setuptools>=77"] + assert project["project"]["license"] == "MIT" + assert project["project"]["license-files"] == ["LICENSE"] + assert project["project"]["dependencies"] == [ + "mutagen>=1.47,<2.0", + "textual>=1.0,<2.0", + ] + assert "Development Status :: 4 - Beta" in project["project"]["classifiers"] + + +def test_source_distribution_manifest_excludes_repository_only_material(): + manifest = (PROJECT_ROOT / "MANIFEST.in").read_text(encoding="utf-8") + + for required in ("LICENSE", "README.md", "pyproject.toml"): + assert f"include {required}" in manifest + assert "recursive-include src *.py" in manifest + for repository_only in ("docs", "tests"): + assert f"prune {repository_only}" in manifest + for handoff in ("AGENTS.md", "PROJECT_CONTEXT.md", ".gitignore"): + assert f"exclude {handoff}" in manifest + assert "global-exclude __pycache__" in manifest + assert "global-exclude *.py[cod]" in manifest + + +def test_every_python_package_is_under_the_configured_source_tree(): + project = _pyproject() + source_root = PROJECT_ROOT / project["tool"]["setuptools"]["package-dir"][""] + configured_root = project["tool"]["setuptools"]["packages"]["find"]["where"] + + assert configured_root == ["src"] + packages = { + path.parent.relative_to(source_root).as_posix().replace("/", ".") + for path in source_root.rglob("__init__.py") + } + assert "juice_lyrics" in packages + assert all(name == "juice_lyrics" or name.startswith("juice_lyrics.") for name in packages) + + +def test_runtime_sources_do_not_contain_a_checkout_specific_path(): + forbidden = "/home/nobloat/Downloads/juice-lyrics-codex" + + for source in (PROJECT_ROOT / "src" / "juice_lyrics").rglob("*.py"): + assert forbidden not in source.read_text(encoding="utf-8"), source diff --git a/tests/test_performance_regressions.py b/tests/test_performance_regressions.py new file mode 100644 index 0000000..7c5d86a --- /dev/null +++ b/tests/test_performance_regressions.py @@ -0,0 +1,153 @@ +"""Deterministic work-count checks; timing output is diagnostic, not an assertion.""" + +from __future__ import annotations + +import json +import os +import sys +from pathlib import Path +from time import perf_counter + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.library_identity import IdentityBackfillDependencies, backfill_catalogue_identities +from juice_lyrics.services.library_status import get_library_snapshot +from juice_lyrics.state import sha256_file +from juice_lyrics.library.media import AudioMetadata + + +def test_unchanged_snapshot_backfill_does_not_hash_audio_twice(tmp_path): + music = tmp_path / "music" + music.mkdir() + files = {} + for index in range(16): + path = music / f"Track {index:02}.mp3" + path.write_bytes(bytes([index]) * (1024 * 1024)) + files[path.name] = { + "sha256": sha256_file(path), "song_id": index + 1, + "api_name": f"Track {index:02}", + } + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": files}), encoding="utf-8") + hashes = 0 + + def counted_hash(path): + nonlocal hashes + hashes += 1 + return sha256_file(path) + + start = perf_counter() + snapshot = get_library_snapshot( + Settings(music_dir=music), state_file=state_file, + verifier=lambda path: (False, "no lyrics"), + duration_reader=lambda path: 180.0, hasher=counted_hash, + ) + scan_seconds = perf_counter() - start + assert hashes == len(files) + dependencies = IdentityBackfillDependencies( + hasher=counted_hash, + searcher=lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("known song searched")), + ) + + start = perf_counter() + result = backfill_catalogue_identities( + Settings(music_dir=music), snapshot.tracks, + state_file=state_file, dependencies=dependencies, + ) + backfill_seconds = perf_counter() - start + print(f"snapshot={scan_seconds:.4f}s backfill={backfill_seconds:.4f}s hashes={hashes}") + assert result.reused == len(files) + assert hashes == len(files) + + +def test_cached_hash_is_not_reused_after_same_size_replacement(tmp_path): + music = tmp_path / "music" + music.mkdir() + path = music / "Song.mp3" + path.write_bytes(b"old audio") + original_stat = path.stat() + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": {"Song.mp3": { + "sha256": sha256_file(path), "song_id": 1, "api_name": "Old song", + }}}), encoding="utf-8") + snapshot = get_library_snapshot( + Settings(music_dir=music), state_file=state_file, + verifier=lambda path: (False, "no lyrics"), duration_reader=lambda path: 180.0, + ) + replacement = music / "replacement.tmp" + replacement.write_bytes(b"new audio") + os.replace(replacement, path) + os.utime(path, ns=(original_stat.st_atime_ns, original_stat.st_mtime_ns)) + searches = [] + candidate = {"id": 2, "name": "New song"} + dependencies = IdentityBackfillDependencies( + searcher=lambda *args, **kwargs: searches.append(1) or [candidate], + matcher=lambda *args: (candidate, 100.0, [], []), + search_title=lambda path: "Song", + ) + + result = backfill_catalogue_identities( + Settings(music_dir=music), snapshot.tracks, + state_file=state_file, dependencies=dependencies, + ) + + assert result.reused == 0 + assert result.identified == 1 + assert searches == [1] + assert json.loads(state_file.read_text(encoding="utf-8"))["files"]["Song.mp3"]["song_id"] == 2 + + +def test_one_state_entry_change_only_rechecks_that_track(tmp_path): + music = tmp_path / "music" + music.mkdir() + files = {} + for index in range(8): + path = music / f"Track {index:02}.flac" + path.write_bytes(bytes([index]) * 4096) + files[path.name] = { + "sha256": sha256_file(path), + "song_id": index + 1, + "api_name": f"Track {index:02}", + } + state_file = tmp_path / "state.json" + state_file.write_text(json.dumps({"files": files}), encoding="utf-8") + counts = {"hashes": 0, "metadata": 0, "verification": 0} + + def counted_hash(path): + counts["hashes"] += 1 + return sha256_file(path) + + def metadata(path): + counts["metadata"] += 1 + return AudioMetadata(path.stem, "Juice WRLD", "Album", 180.0) + + def verify(path): + counts["verification"] += 1 + return False, "no lyrics" + + first = get_library_snapshot( + Settings(music_dir=music), + state_file=state_file, + verifier=verify, + metadata_reader=metadata, + hasher=counted_hash, + ) + baseline = counts.copy() + state = json.loads(state_file.read_text(encoding="utf-8")) + state["files"]["Track 00.flac"]["api_name"] = "Corrected title" + state_file.write_text(json.dumps(state), encoding="utf-8") + + second = get_library_snapshot( + Settings(music_dir=music), + state_file=state_file, + verifier=verify, + metadata_reader=metadata, + hasher=counted_hash, + previous_snapshot=first, + ) + + assert second.tracks[0].matched_title == "Corrected title" + assert counts["hashes"] - baseline["hashes"] == 1 + assert counts["metadata"] - baseline["metadata"] == 1 + assert counts["verification"] - baseline["verification"] == 1 diff --git a/tests/test_product_identity.py b/tests/test_product_identity.py new file mode 100644 index 0000000..25fe34b --- /dev/null +++ b/tests/test_product_identity.py @@ -0,0 +1,141 @@ +from __future__ import annotations + +import argparse +import tomllib +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics import cli +from juice_lyrics.config import settings as config_settings +from juice_lyrics.identity import ( + DIST_NAME, + LEGACY_COMMAND, + PRIMARY_COMMAND, + PRODUCT_NAME, + STORAGE_NAMESPACE, +) +from juice_lyrics.tui import JuiceLyricsApp + + +PROJECT_ROOT = Path(__file__).resolve().parents[1] + + +def _project_scripts() -> dict[str, str]: + data = tomllib.loads((PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8")) + return data["project"]["scripts"] + + +def test_primary_and_legacy_console_scripts_share_one_cli_implementation(): + scripts = _project_scripts() + + assert PRODUCT_NAME == PRIMARY_COMMAND == "999" + assert LEGACY_COMMAND == STORAGE_NAMESPACE == "juice-lyrics" + assert DIST_NAME == "juice-wrld-lyrics" + assert scripts[PRIMARY_COMMAND] == "juice_lyrics.cli:main" + assert scripts[LEGACY_COMMAND] == scripts[PRIMARY_COMMAND] + + +def test_999_help_is_clean_and_uses_primary_command(capsys): + with pytest.raises(SystemExit) as result: + cli.main(["--help"]) + + output = capsys.readouterr().out + assert result.value.code == 0 + assert output.startswith("usage: 999") + assert "Launch the 999 terminal interface" in output + assert "juice-lyrics" not in output + + +def test_tui_and_documentation_prefer_999_branding(): + assert JuiceLyricsApp.TITLE == "999" + for relative in ( + "README.md", + "docs/USER_GUIDE.md", + "docs/DEVELOPMENT.md", + "docs/PROJECT_STATE.md", + "docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md", + ): + text = (PROJECT_ROOT / relative).read_text(encoding="utf-8") + assert "999" in text + assert ".venv/bin/juice-lyrics" not in text + assert not any( + line.startswith("juice-lyrics ") for line in text.splitlines() + ) + + +def test_no_argument_first_run_opens_tui_without_writing_setup_paths(tmp_path, monkeypatch): + config = tmp_path / ".config" / STORAGE_NAMESPACE / "config.toml" + legacy_lyrics = tmp_path / "Music" / "lyrics" + rmpc_config = tmp_path / ".config" / "rmpc" / "config.ron" + rmpc_config.parent.mkdir(parents=True) + rmpc_config.write_text("unchanged", encoding="utf-8") + monkeypatch.setattr(cli, "CONFIG_FILE", config) + monkeypatch.setattr(cli, "DEFAULT_RMPC_CONFIG", rmpc_config) + first_run_settings = config_settings.Settings( + music_dir=tmp_path / "missing music", + lyrics_dir=legacy_lyrics, + ) + monkeypatch.setattr(cli, "Settings", lambda: first_run_settings) + monkeypatch.setattr( + cli, + "patch_rmpc_config", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("rmpc rewritten")), + ) + launched = [] + monkeypatch.setattr(cli, "command_tui", lambda settings: launched.append(settings) or 0) + + assert cli.main([]) == 0 + assert len(launched) == 1 + assert not config.exists() + assert not legacy_lyrics.exists() + assert rmpc_config.read_text(encoding="utf-8") == "unchanged" + + +def test_999_status_dispatch_works_with_an_isolated_empty_library(tmp_path, capsys): + music = tmp_path / "music" + music.mkdir() + + assert cli.main(["--path", str(music), "--no-color", "status"]) == 0 + output = capsys.readouterr().out + assert "Library Status" in output + assert f"Library: {music}" in output + assert "Audio files: 0" in output + + +def test_existing_juice_lyrics_config_and_storage_paths_remain_authoritative( + tmp_path, monkeypatch +): + config = tmp_path / ".config" / STORAGE_NAMESPACE / "config.toml" + music = tmp_path / "existing library" + config.parent.mkdir(parents=True) + config.write_text(f'music_dir = "{music}"\n', encoding="utf-8") + monkeypatch.setattr(cli, "CONFIG_FILE", config) + + loaded = cli.load_settings() + + assert loaded.music_dir == music + assert config_settings.CONFIG_FILE.parent.name == STORAGE_NAMESPACE + assert config_settings.CACHE_DIR.name == STORAGE_NAMESPACE + assert config_settings.DATA_DIR.name == STORAGE_NAMESPACE + assert config_settings.STATE_FILE == config_settings.DATA_DIR / "state.json" + assert config_settings.BACKUP_DIR == config_settings.DATA_DIR / "backups" + assert config_settings.ACQUISITION_JOBS_FILE == config_settings.DATA_DIR / "acquisition_jobs.json" + + +def test_setup_help_keeps_config_and_rmpc_responsibilities_explicit(): + parser = cli.build_parser() + + assert parser.parse_args(["config", "init"]) == argparse.Namespace( + path=None, + api_base=None, + no_color=False, + command="config", + action="init", + force=False, + ) + assert parser.parse_args(["rmpc", "setup"]).action == "setup" + assert parser.parse_args(["setup"]).command == "setup" diff --git a/tests/test_rmpc.py b/tests/test_rmpc.py index 7100c8f..fc2ba7b 100644 --- a/tests/test_rmpc.py +++ b/tests/test_rmpc.py @@ -1,10 +1,12 @@ from pathlib import Path +import argparse import sys import tempfile sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) from juice_lyrics.cli import write_lrc, command_rmpc_verify, parse_synced_lyrics +from juice_lyrics.config.settings import Settings def test_lrc_writer(tmp_path): @@ -22,3 +24,52 @@ def test_lrc_writer(tmp_path): } # write_lrc needs MP3 duration; use a fake local_duration impossible here, so just test parser shape separately. assert parse_synced_lyrics("[0:01.23] hello\n[0:04.56] world") == [("hello", 1230), ("world", 4560)] + + +def test_rmpc_verify_reads_adjacent_sidecars_only(tmp_path, capsys): + music = tmp_path / "music" + music.mkdir() + audio = music / "Rental.mp3" + audio.write_bytes(b"audio") + (music / "Rental.lrc").write_text( + "[ar:Juice WRLD]\n[ti:Rental]\n[length:01:00]\n[00:01.00] line\n", + encoding="utf-8", + ) + configured = tmp_path / "Music" / "lyrics" + configured.mkdir(parents=True) + (configured / "Ignored.lrc").write_text("invalid", encoding="utf-8") + old_derived = tmp_path / "Music" / "Juice WRLD" / "lyrics" + old_derived.mkdir(parents=True) + (old_derived / "Ignored.lrc").write_text("invalid", encoding="utf-8") + + result = command_rmpc_verify( + argparse.Namespace(lyrics_dir=None), + Settings(music_dir=music, lyrics_dir=configured), + False, + ) + + assert result == 0 + output = capsys.readouterr().out + assert "Rental.lrc" in output + assert "Ignored.lrc" not in output + assert "Valid: 1 Invalid: 0" in output + + +def test_rmpc_notification_receives_exact_sidecar_path(tmp_path, monkeypatch): + import juice_lyrics.rmpc.integration as rmpc + + sidecar = tmp_path / "Music" / "Juice WRLD" / "Rental.lrc" + calls = [] + + class Result: + returncode = 0 + + monkeypatch.setattr(rmpc, "rmpc_running", lambda: True) + monkeypatch.setattr( + rmpc.subprocess, + "run", + lambda command, **kwargs: calls.append(command) or Result(), + ) + + assert rmpc.notify_rmpc_index([sidecar]) == 1 + assert calls == [["rmpc", "remote", "indexlrc", "--path", str(sidecar)]] diff --git a/tests/test_settings_snapshot.py b/tests/test_settings_snapshot.py new file mode 100644 index 0000000..a696a02 --- /dev/null +++ b/tests/test_settings_snapshot.py @@ -0,0 +1,160 @@ +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.settings_snapshot import ( + IntegrationStatus, + SettingsSource, + get_settings_snapshot, +) + + +def _snapshot(tmp_path, settings=None, **kwargs): + effective_settings = settings or Settings( + music_dir=tmp_path / "music", + lyrics_dir=tmp_path / "lyrics", + ) + return get_settings_snapshot( + effective_settings, + config_path=kwargs.pop("config_path", tmp_path / "config" / "config.toml"), + cache_dir=tmp_path / "cache", + state_file=tmp_path / "data" / "state.json", + backup_dir=tmp_path / "data" / "backups", + jobs_file=tmp_path / "data" / "jobs.json", + rmpc_config_path=kwargs.pop("rmpc_config_path", tmp_path / "rmpc" / "config.ron"), + executable_finder=kwargs.pop("executable_finder", lambda name: None), + **kwargs, + ) + + +def test_missing_config_reports_effective_defaults_and_runtime_override_without_writes(tmp_path): + snapshot = _snapshot(tmp_path) + values = {item.key: item for item in snapshot.values} + + assert snapshot.config_exists is False + assert values["music_dir"].source is SettingsSource.RUNTIME_OVERRIDE + assert values["api_base"].source is SettingsSource.DEFAULT + assert values["timeout"].source is SettingsSource.DEFAULT + assert snapshot.rmpc.status is IntegrationStatus.NOT_DETECTED + assert all(not item.exists for item in snapshot.paths) + assert not list(tmp_path.rglob("*")) + + +def test_explicit_config_and_runtime_overrides_have_reliable_provenance(tmp_path): + config = tmp_path / "config.toml" + configured_music = tmp_path / "configured-music" + config.write_text( + f'music_dir = "{configured_music}"\n' + f'lyrics_dir = "{tmp_path / "configured-lyrics"}"\n' + 'api_base = "https://example.test/api/"\n' + "timeout = 30\n" + "delay = 0.25\n" + "duration_tolerance = 2.5\n" + "cache_ttl_hours = 12\n", + encoding="utf-8", + ) + settings = Settings( + music_dir=configured_music, + lyrics_dir=tmp_path / "configured-lyrics", + api_base="https://runtime.test/api", + timeout=30, + delay=0.25, + duration_tolerance=2.5, + cache_ttl_hours=12, + ) + snapshot = _snapshot(tmp_path, settings, config_path=config) + values = {item.key: item for item in snapshot.values} + + assert snapshot.config_exists is True + assert values["music_dir"].source is SettingsSource.CONFIG + assert values["lyrics_dir"].source is SettingsSource.CONFIG + assert values["timeout"].source is SettingsSource.CONFIG + assert values["api_base"].source is SettingsSource.RUNTIME_OVERRIDE + + +@pytest.mark.parametrize( + ("executable", "config_text", "expected"), + [ + ("/usr/bin/rmpc", 'lyrics_dir: Some("{lyrics}"),\nenable_lyrics_index: true,\nenable_lyrics_hot_reload: true,', IntegrationStatus.DETECTED_CONFIGURED), + ("/usr/bin/rmpc", "cache_dir: Some(\"/cache\"),", IntegrationStatus.DETECTED_NOT_CONFIGURED), + (None, 'lyrics_dir: Some("/lyrics"),', IntegrationStatus.NOT_DETECTED), + ], +) +def test_rmpc_detection_and_configuration_states(tmp_path, executable, config_text, expected): + rmpc_config = tmp_path / "rmpc.ron" + rmpc_config.write_text(config_text.format(lyrics=tmp_path), encoding="utf-8") + snapshot = _snapshot( + tmp_path, + rmpc_config_path=rmpc_config, + executable_finder=lambda name: executable, + ) + + assert snapshot.rmpc.status is expected + assert snapshot.rmpc.config_exists is True + + +def test_malformed_config_raises_readable_error_without_rewriting(tmp_path): + config = tmp_path / "config.toml" + config.write_text("timeout = nope", encoding="utf-8") + before = config.read_bytes() + + with pytest.raises(RuntimeError, match="Could not read config"): + _snapshot(tmp_path, config_path=config) + + assert config.read_bytes() == before + + +def test_paths_and_limitations_are_typed_and_read_only(tmp_path): + music = tmp_path / "music" + music.mkdir() + snapshot = _snapshot(tmp_path, Settings(music_dir=music)) + paths = {item.key: item for item in snapshot.paths} + + assert paths["music"].exists is True + assert paths["cache"].exists is False + assert paths["state"].path == tmp_path / "data" / "state.json" + assert "MP3, FLAC, and M4A" in snapshot.limitations[0] + assert any("FLAC and M4A timing use adjacent LRC" in item for item in snapshot.limitations) + assert not (tmp_path / "cache").exists() + assert not (tmp_path / "data").exists() + + +def test_legacy_lyrics_directory_is_deprecated_metadata_and_not_a_runtime_path(tmp_path): + configured = tmp_path / "shared" / "lyrics" + settings = Settings( + music_dir=tmp_path / "music", + lyrics_dir=configured, + lyrics_dir_explicit=True, + ) + snapshot = get_settings_snapshot( + settings, + config_path=tmp_path / "config.toml", + cache_dir=tmp_path / "cache", + state_file=tmp_path / "state.json", + backup_dir=tmp_path / "backups", + jobs_file=tmp_path / "jobs.json", + rmpc_config_path=tmp_path / "rmpc.ron", + executable_finder=lambda name: None, + ) + + values = {item.key: item for item in snapshot.values} + paths = {item.key: item for item in snapshot.paths} + assert values["lyrics_dir"].value == configured + assert "deprecated" in values["lyrics_dir"].label.lower() + assert values["external_lyrics"].value == "Beside each song (.lrc)" + assert "lyrics" not in paths + assert not configured.exists() + + +def test_rmpc_inspection_failure_is_structured(tmp_path): + snapshot = _snapshot( + tmp_path, + executable_finder=lambda name: (_ for _ in ()).throw(PermissionError("PATH denied")), + ) + + assert snapshot.rmpc.status is IntegrationStatus.UNABLE_TO_INSPECT + assert "PATH denied" in snapshot.rmpc.detail diff --git a/tests/test_shell_completion.py b/tests/test_shell_completion.py new file mode 100644 index 0000000..183b53d --- /dev/null +++ b/tests/test_shell_completion.py @@ -0,0 +1,192 @@ +from __future__ import annotations + +import argparse +from pathlib import Path +import shutil +import subprocess +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics import cli +from juice_lyrics.services.shell_completion import completion_tree, generate_completion + + +EXPECTED_COMMAND_PATHS = { + ("setup",), + ("sync",), + ("status",), + ("scan",), + ("embed",), + ("verify",), + ("restore",), + ("doctor",), + ("completion",), + ("guide",), + ("tui",), + ("search",), + ("info",), + ("acquire",), + ("acquire", "search"), + ("acquire", "add"), + ("acquire", "manifest"), + ("acquire", "jobs"), + ("acquire", "run"), + ("acquire", "retry"), + ("acquire", "delete"), + ("rmpc",), + ("rmpc", "setup"), + ("rmpc", "sync"), + ("rmpc", "verify"), + ("config",), + ("config", "init"), + ("config", "show"), + ("cache",), + ("cache", "clear"), + ("state",), + ("state", "clean"), + ("state", "rebuild-identities"), +} + + +def _nodes(root): + yield root + for child in root.children: + yield from _nodes(child) + + +def _parser_options(parser: argparse.ArgumentParser) -> set[str]: + options: set[str] = set() + for action in parser._actions: + options.update(action.option_strings) + if isinstance(action, argparse._SubParsersAction): + for child in action.choices.values(): + options.update(_parser_options(child)) + return options + + +def test_completion_model_covers_the_current_argparse_command_tree(): + parser = cli.build_parser() + root = completion_tree(parser) + nodes = tuple(_nodes(root)) + + assert {node.path for node in nodes if node.path} == EXPECTED_COMMAND_PATHS + assert {name for node in nodes for option in node.options for name in option.names} == _parser_options(parser) + completion_node = next(node for node in nodes if node.path == ("completion",)) + assert completion_node.positional_choices == ("bash", "zsh", "fish") + + +@pytest.mark.parametrize("shell", ("bash", "zsh", "fish")) +def test_generated_completion_is_deterministic_and_covers_commands_and_options(shell): + parser = cli.build_parser() + + first = generate_completion(parser, shell) + second = generate_completion(parser, shell) + + assert first == second + assert first.endswith("\n") + for path in EXPECTED_COMMAND_PATHS: + for command in path: + assert command in first + for option in _parser_options(parser): + rendered = ( + f"-l {option[2:]}" if shell == "fish" and option.startswith("--") + else f"-s {option[1:]}" if shell == "fish" + else option + ) + assert rendered in first + expected_long_options = ( + ("-l support-report", "-l save-report", "-l include-locked", "-l dry-run") + if shell == "fish" + else ("--support-report", "--save-report", "--include-locked", "--dry-run") + ) + assert all(option in first for option in expected_long_options) + assert "--retry-all" not in first + assert "--force-match" not in first + assert "--cancel-download" not in first + + +@pytest.mark.parametrize("shell", ("bash", "zsh", "fish")) +def test_completion_command_skips_settings_state_and_catalogue(shell, tmp_path, monkeypatch, capsys): + monkeypatch.setattr( + cli, + "load_settings", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("settings loaded")), + ) + monkeypatch.setattr( + cli, + "api_get", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("catalogue accessed")), + ) + + assert cli.main(["completion", shell]) == 0 + + output = capsys.readouterr().out + assert output + assert list(tmp_path.iterdir()) == [] + + +@pytest.mark.parametrize( + ("shell", "binding"), + ( + ("bash", "complete -F _999_complete"), + ("zsh", "compdef _999"), + ("fish", "complete -c"), + ), +) +def test_completion_supports_primary_and_legacy_commands(shell, binding): + script = generate_completion(cli.build_parser(), shell) + + assert f"{binding} 999" in script + assert "juice-lyrics" in script + + +@pytest.mark.parametrize("shell", ("bash", "zsh", "fish")) +def test_generated_script_has_valid_syntax_when_shell_is_available(shell, tmp_path): + executable = shutil.which(shell) + if executable is None: + pytest.skip(f"{shell} is not installed") + script = tmp_path / f"999.{shell}" + script.write_text(generate_completion(cli.build_parser(), shell), encoding="utf-8") + + result = subprocess.run( + [executable, "-n", str(script)], + check=False, + capture_output=True, + text=True, + ) + + assert result.returncode == 0, result.stderr + + +def test_bash_completion_handles_global_options_and_nested_commands(tmp_path): + script = tmp_path / "999.bash" + script.write_text(generate_completion(cli.build_parser(), "bash"), encoding="utf-8") + probe = tmp_path / "probe.bash" + probe.write_text( + f'''source "{script}" +COMP_WORDS=(999 --no-color state "") +COMP_CWORD=3 +_999_complete +printf '%s\n' "${{COMPREPLY[@]}}" +printf '%s\n' --separator-- +COMP_WORDS=(999 state rebuild-identities --d) +COMP_CWORD=3 +_999_complete +printf '%s\n' "${{COMPREPLY[@]}}" +''', + encoding="utf-8", + ) + + result = subprocess.run( + ["bash", str(probe)], + check=True, + capture_output=True, + text=True, + ) + + first, second = result.stdout.split("--separator--\n") + assert {"clean", "rebuild-identities"} <= set(first.splitlines()) + assert second.splitlines() == ["--details"] diff --git a/tests/test_sidecar_lrc.py b/tests/test_sidecar_lrc.py new file mode 100644 index 0000000..4b70487 --- /dev/null +++ b/tests/test_sidecar_lrc.py @@ -0,0 +1,93 @@ +from __future__ import annotations + +from pathlib import Path + +import pytest + +from juice_lyrics.lyrics import engine +from juice_lyrics.lyrics.sidecar import sidecar_lrc_path + + +@pytest.mark.parametrize( + ("filename", "expected"), + [ + ("song.mp3", "song.lrc"), + ("song.flac", "song.lrc"), + ("song.m4a", "song.lrc"), + ("song.final.v2.flac", "song.final.v2.lrc"), + ("Légend's [Mix] (v2).mp3", "Légend's [Mix] (v2).lrc"), + ], +) +def test_sidecar_path_uses_audio_basename(filename, expected, tmp_path): + assert sidecar_lrc_path(tmp_path / filename) == tmp_path / expected + + +def _metadata(*args, **kwargs): + return { + "artist": "Juice WRLD", + "title": "Rental", + "album": "", + "length": "03:00.00", + } + + +def test_lrc_writer_atomically_writes_beside_audio_and_reuses_identical_content( + tmp_path, monkeypatch +): + audio = tmp_path / "nested" / "Rental.mp3" + audio.parent.mkdir() + audio.write_bytes(b"audio") + monkeypatch.setattr(engine, "read_mp3_metadata", _metadata) + + result = engine.write_lrc(audio, [("line", 1000)], {}) + content = result.read_bytes() + monkeypatch.setattr( + engine.tempfile, + "mkstemp", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("rewritten")), + ) + + repeated = engine.write_lrc(audio, [("line", 1000)], {}) + + assert result == audio.with_suffix(".lrc") + assert repeated == result + assert repeated.read_bytes() == content + + +def test_failed_generation_leaves_existing_sidecar_untouched(tmp_path, monkeypatch): + audio = tmp_path / "Rental.mp3" + audio.write_bytes(b"audio") + sidecar = audio.with_suffix(".lrc") + sidecar.write_bytes(b"known-good") + monkeypatch.setattr( + engine, + "read_mp3_metadata", + lambda *args: (_ for _ in ()).throw(RuntimeError("metadata failed")), + ) + + with pytest.raises(RuntimeError, match="metadata failed"): + engine.write_lrc(audio, [("new", 1000)], {}) + + assert sidecar.read_bytes() == b"known-good" + + +def test_failed_atomic_replace_leaves_existing_sidecar_and_no_partial(tmp_path, monkeypatch): + audio = tmp_path / "Rental.mp3" + audio.write_bytes(b"audio") + sidecar = audio.with_suffix(".lrc") + sidecar.write_bytes(b"known-good") + monkeypatch.setattr(engine, "read_mp3_metadata", _metadata) + original_replace = Path.replace + + def fail_sidecar_replace(path: Path, target: Path): + if target == sidecar: + raise OSError("replace failed") + return original_replace(path, target) + + monkeypatch.setattr(Path, "replace", fail_sidecar_replace) + + with pytest.raises(OSError, match="replace failed"): + engine.write_lrc(audio, [("new", 2000)], {}) + + assert sidecar.read_bytes() == b"known-good" + assert not list(tmp_path.glob(".Rental.lrc.*.tmp")) diff --git a/tests/test_sidecar_queue_execution.py b/tests/test_sidecar_queue_execution.py new file mode 100644 index 0000000..f8c0062 --- /dev/null +++ b/tests/test_sidecar_queue_execution.py @@ -0,0 +1,205 @@ +from __future__ import annotations + +import hashlib +import shutil +from pathlib import Path + +import pytest + +from juice_lyrics.acquisition import integration as integration_module +from juice_lyrics.acquisition.integration import integrate_downloaded_mp3 +from juice_lyrics.acquisition.jobs import JobStore +from juice_lyrics.acquisition.models import ( + AcquisitionFailureStage, + AcquisitionItem, + AcquisitionResult, + AcquisitionState, +) +from juice_lyrics.acquisition.runner import AcquisitionRunSummary +from juice_lyrics.config.settings import Settings +from juice_lyrics.lyrics import engine +from juice_lyrics.services.download_queue import ( + DownloadExecutionStatus, + DownloadRetryAction, + DownloadRetryStatus, + execute_download_all, + execute_selected_download, + execute_selected_retry, + plan_download_all, + plan_download_execution, + plan_download_retry, +) + + +def _prepare_integration(monkeypatch, tmp_path): + counter = 0 + + def backup_root(): + nonlocal counter + counter += 1 + root = tmp_path / "backups" / str(counter) + root.mkdir(parents=True) + return root + + def backup_file(source, root, base): + target = root / source.name + shutil.copy2(source, target) + return target + + monkeypatch.setattr(integration_module, "make_backup_root", backup_root) + monkeypatch.setattr(integration_module, "backup_file", backup_file) + monkeypatch.setattr(integration_module, "write_manifest", lambda *args: None) + monkeypatch.setattr(integration_module, "embed_lyrics", lambda *args: "SYLT") + monkeypatch.setattr(integration_module, "verify_file", lambda path: (True, "verified")) + monkeypatch.setattr(integration_module, "notify_rmpc_index", lambda paths: len(paths)) + monkeypatch.setattr(integration_module, "load_state", lambda: {"files": {}}) + monkeypatch.setattr(integration_module, "save_state", lambda state: None) + monkeypatch.setattr( + engine, + "read_mp3_metadata", + lambda *args: { + "artist": "Juice WRLD", + "title": "Song", + "album": "", + "length": "03:00.00", + }, + ) + + +def _song_fetcher(settings, song_id): + return { + "id": song_id, + "name": "Song", + "synced_lyrics": "[00:01.00] line", + "lyrics": "line", + } + + +def _runner(job, store, *, postprocess, item_indexes, **kwargs): + completed = 0 + for index in sorted(item_indexes): + entry = job.items[index] + entry.item.destination.parent.mkdir(parents=True, exist_ok=True) + if not entry.item.destination.exists(): + entry.item.destination.write_bytes(b"downloaded") + result = AcquisitionResult( + entry.item, + AcquisitionState.COMPLETE, + destination=entry.item.destination, + bytes_written=entry.item.destination.stat().st_size, + ) + postprocess(result) + job.record_result(index, result) + completed += 1 + store.save(job) + return AcquisitionRunSummary(job.job_id, completed, 0, 0, len(item_indexes)) + + +def _settings(tmp_path): + return Settings( + music_dir=tmp_path / "music", + lyrics_dir=tmp_path / "legacy-central", + lyrics_dir_explicit=True, + ) + + +def test_download_selected_writes_adjacent_sidecar(tmp_path, monkeypatch): + _prepare_integration(monkeypatch, tmp_path) + jobs = tmp_path / "jobs.json" + destination = tmp_path / "music" / "Selected.mp3" + job = JobStore(jobs).create( + [AcquisitionItem("1", "Selected", "https://example.test/selected", destination)], + job_id="selected", + ) + plan = plan_download_execution(_settings(tmp_path), f"{job.job_id}:0", jobs_path=jobs).plan + assert plan is not None + + result = execute_selected_download( + _settings(tmp_path), + plan, + jobs_path=jobs, + runner=_runner, + integration=integrate_downloaded_mp3, + song_fetcher=_song_fetcher, + ) + + assert result.status is DownloadExecutionStatus.COMPLETED + assert destination.with_suffix(".lrc").is_file() + assert not _settings(tmp_path).lyrics_dir.exists() + + +@pytest.mark.parametrize("count", [1, 3]) +def test_download_all_writes_each_adjacent_sidecar(tmp_path, monkeypatch, count): + _prepare_integration(monkeypatch, tmp_path) + jobs = tmp_path / "jobs.json" + items = [ + AcquisitionItem( + str(index), + f"Song {index}", + f"https://example.test/{index}", + tmp_path / "music" / f"Song {index}.mp3", + ) + for index in range(count) + ] + JobStore(jobs).create(items, job_id="batch") + settings = _settings(tmp_path) + + result = execute_download_all( + settings, + plan_download_all(settings, jobs_path=jobs), + jobs_path=jobs, + runner=_runner, + integration=integrate_downloaded_mp3, + song_fetcher=_song_fetcher, + ) + + assert result.completed_count == count + assert all(item.destination.with_suffix(".lrc").is_file() for item in items) + assert not settings.lyrics_dir.exists() + + +@pytest.mark.parametrize( + ("stage", "existing_file", "expected_action"), + [ + (AcquisitionFailureStage.LYRICS, True, DownloadRetryAction.PROCESS_ONLY), + (AcquisitionFailureStage.TRANSPORT, False, DownloadRetryAction.DOWNLOAD_AGAIN), + ], +) +def test_retry_modes_write_adjacent_sidecar( + tmp_path, monkeypatch, stage, existing_file, expected_action +): + _prepare_integration(monkeypatch, tmp_path) + jobs = tmp_path / "jobs.json" + destination = tmp_path / "music" / "Retry.mp3" + if existing_file: + destination.parent.mkdir(parents=True) + destination.write_bytes(b"finalized") + job = JobStore(jobs).create( + [AcquisitionItem("9", "Retry", "https://example.test/retry", destination)], + job_id="retry", + ) + entry = job.items[0] + entry.state = AcquisitionState.FAILED + entry.failure_stage = stage + entry.error = "previous failure" + if existing_file: + entry.retry_file_size = destination.stat().st_size + entry.retry_file_sha256 = hashlib.sha256(destination.read_bytes()).hexdigest() + JobStore(jobs).save(job) + settings = _settings(tmp_path) + planned = plan_download_retry(settings, "retry:0", jobs_path=jobs) + assert planned.plan is not None + assert planned.plan.action is expected_action + + result = execute_selected_retry( + settings, + planned.plan, + jobs_path=jobs, + runner=_runner, + integration=integrate_downloaded_mp3, + song_fetcher=_song_fetcher, + ) + + assert result.status is DownloadRetryStatus.COMPLETED + assert destination.with_suffix(".lrc").is_file() + assert not settings.lyrics_dir.exists() diff --git a/tests/test_state_maintenance.py b/tests/test_state_maintenance.py new file mode 100644 index 0000000..8b8f8c4 --- /dev/null +++ b/tests/test_state_maintenance.py @@ -0,0 +1,120 @@ +from __future__ import annotations + +import json +from pathlib import Path +import sys + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services.state_maintenance import ( + execute_stale_state_cleanup, + plan_stale_state_cleanup, +) + + +def _write_state(path: Path, files: dict) -> bytes: + path.write_text( + json.dumps({"files": files, "updated": "historical", "custom": "preserve"}, indent=2), + encoding="utf-8", + ) + return path.read_bytes() + + +def test_cleanup_previews_and_removes_only_clearly_stale_external_records(tmp_path): + music = tmp_path / "Music" + real = music / "Unreleased" / "24 Hours.mp3" + real.parent.mkdir(parents=True) + real.write_bytes(b"real audio") + state_file = tmp_path / "state.json" + stale_absolute = "/tmp/pytest-of-someone/pytest-44/test_case/Bandit.flac" + stale_lrc = "/tmp/pytest-of-someone/pytest-45/test_case/Only LRC.lrc" + original = _write_state( + state_file, + { + "Unreleased/24 Hours.mp3": { + "sha256": "real", + "song_id": 94760, + "api_name": "24 Hours", + "lyric_type": "USLT", + "lrc": None, + }, + "Moved Song.mp3": {"song_id": 7, "api_name": "Moved Song", "lrc": None}, + stale_absolute: {"song_id": 1, "lrc": stale_absolute.removesuffix(".flac") + ".lrc"}, + "Temporary.mp3": {"song_id": 2, "lrc": stale_lrc}, + }, + ) + + plan = plan_stale_state_cleanup(Settings(music_dir=music), state_file=state_file) + + assert plan.stale_count == 2 + assert set(plan.stale_keys) == {stale_absolute, "Temporary.mp3"} + assert state_file.read_bytes() == original + + result = execute_stale_state_cleanup(plan) + cleaned = json.loads(state_file.read_text(encoding="utf-8")) + backup = json.loads(result.backup_path.read_text(encoding="utf-8")) + + assert result.removed_count == 2 + assert backup["files"]["Unreleased/24 Hours.mp3"]["song_id"] == 94760 + assert cleaned["files"]["Unreleased/24 Hours.mp3"]["song_id"] == 94760 + assert cleaned["files"]["Unreleased/24 Hours.mp3"]["api_name"] == "24 Hours" + assert "Moved Song.mp3" in cleaned["files"] + assert stale_absolute not in cleaned["files"] + assert "Temporary.mp3" not in cleaned["files"] + assert cleaned["custom"] == "preserve" + + +def test_cleanup_write_failure_preserves_original_and_safety_backup(tmp_path): + music = tmp_path / "Music" + music.mkdir() + state_file = tmp_path / "state.json" + stale = "/tmp/pytest-of-someone/pytest-99/test_case/Song.m4a" + original = _write_state(state_file, {stale: {"song_id": 1}}) + plan = plan_stale_state_cleanup(Settings(music_dir=music), state_file=state_file) + + with pytest.raises(OSError, match="disk full"): + execute_stale_state_cleanup( + plan, + writer=lambda path, state: (_ for _ in ()).throw(OSError("disk full")), + ) + + assert state_file.read_bytes() == original + backups = tuple(tmp_path.glob("state.json.pre-clean-*.bak")) + assert len(backups) == 1 + assert backups[0].read_bytes() == original + + +def test_cleanup_refuses_to_apply_a_stale_preview_after_state_changes(tmp_path): + music = tmp_path / "Music" + music.mkdir() + state_file = tmp_path / "state.json" + stale = "/tmp/pytest-of-someone/pytest-100/test_case/Song.mp3" + _write_state(state_file, {stale: {"song_id": 1}}) + plan = plan_stale_state_cleanup(Settings(music_dir=music), state_file=state_file) + state_file.write_text('{"files": {}, "new": true}', encoding="utf-8") + + with pytest.raises(RuntimeError, match="changed after the cleanup preview"): + execute_stale_state_cleanup(plan) + + assert not tuple(tmp_path.glob("state.json.pre-clean-*.bak")) + + +def test_existing_absolute_external_record_is_preserved(tmp_path): + music = tmp_path / "Music" + music.mkdir() + external = tmp_path / "external" / "Song.mp3" + external.parent.mkdir() + external.write_bytes(b"exists") + state_file = tmp_path / "state.json" + original = _write_state(state_file, {str(external): {"song_id": 1}}) + + plan = plan_stale_state_cleanup(Settings(music_dir=music), state_file=state_file) + result = execute_stale_state_cleanup(plan) + + assert plan.stale_count == 0 + assert result.removed_count == 0 + assert result.backup_path is None + assert state_file.read_bytes() == original diff --git a/tests/test_tui.py b/tests/test_tui.py new file mode 100644 index 0000000..966e28c --- /dev/null +++ b/tests/test_tui.py @@ -0,0 +1,471 @@ +import asyncio +from pathlib import Path +import re +import sys +from threading import Event +from time import perf_counter + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services import CatalogueFilterMetadata, LibraryStatus, QueueSnapshot +from juice_lyrics.tui import JuiceLyricsApp +from juice_lyrics.tui.screens.base import NavigationItem +from textual.widgets import Button, Static + + +def _library_status(tmp_path: Path, **changes) -> LibraryStatus: + values = { + "library_path": tmp_path / "music", + "track_count": 4, + "embedded_synced_count": 2, + "embedded_plain_count": 1, + "missing_or_invalid_count": 1, + "rmpc_lrc_count": 2, + "new_or_changed_count": 1, + "backup_count": 3, + "warnings": (), + } + values.update(changes) + return LibraryStatus(**values) + + +def _queue_snapshot(**changes) -> QueueSnapshot: + values = { + "jobs": (), + "total_job_count": 5, + "active_job_count": 1, + "pending_job_count": 1, + "completed_job_count": 2, + "failed_job_count": 1, + } + values.update(changes) + return QueueSnapshot(**values) + + +def _app(tmp_path: Path, *, library=None, queue=None) -> JuiceLyricsApp: + return JuiceLyricsApp( + Settings(music_dir=tmp_path / "music"), + library_status_provider=library or (lambda settings: _library_status(tmp_path)), + queue_snapshot_provider=queue or _queue_snapshot, + catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), + ) + + +def _rendered(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +def test_app_starts_renders_injected_snapshots_and_exits(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test(size=(80, 24)) as pilot: + await pilot.pause() + assert app.screen.id == "screen-dashboard" + library = _rendered(app, "#library-data") + queue = _rendered(app, "#queue-data") + assert str(tmp_path / "music") in library + assert "Audio tracks 4" in library + assert "Synced lyrics 2" in library + assert "Plain lyrics 1" in library + assert "Missing / invalid 1" in library + assert "New / changed 1" in library + assert "Backups 3" in library + assert "rmpc LRC files 2" in library + assert "1 song ready to download" in queue + assert "Press 4 to Downloads" in queue + assert "jobs" not in queue.lower() + + asyncio.run(scenario()) + + +def test_slow_dashboard_library_does_not_delay_queue_summary(tmp_path): + library_started = Event() + release_library = Event() + queue_called = Event() + + def slow_library(settings): + library_started.set() + assert release_library.wait(timeout=5) + return _library_status(tmp_path) + + def quick_queue(): + queue_called.set() + return _queue_snapshot() + + async def scenario(): + app = _app(tmp_path, library=slow_library, queue=quick_queue) + async with app.run_test() as pilot: + assert await asyncio.to_thread(library_started.wait, 2) + start = perf_counter() + ready = await asyncio.to_thread(queue_called.wait, 0.3) + print(f"dashboard queue-ready={perf_counter() - start:.4f}s ready={ready}") + assert ready + await pilot.pause() + assert "1 song ready to download" in _rendered(app, "#queue-data") + assert "Loading library status" in _rendered(app, "#library-data") + + try: + asyncio.run(scenario()) + finally: + release_library.set() + + +def test_dashboard_renders_empty_library_and_queue(tmp_path): + async def scenario(): + app = _app( + tmp_path, + library=lambda settings: _library_status( + tmp_path, + track_count=0, + embedded_synced_count=0, + embedded_plain_count=0, + missing_or_invalid_count=0, + rmpc_lrc_count=0, + new_or_changed_count=0, + backup_count=0, + ), + queue=lambda: _queue_snapshot( + total_job_count=0, + active_job_count=0, + pending_job_count=0, + completed_job_count=0, + failed_job_count=0, + ), + ) + async with app.run_test() as pilot: + await pilot.pause() + assert "Audio tracks 0" in _rendered(app, "#library-data") + assert "Search for songs in Browse" in _rendered(app, "#queue-data") + assert "Press 2 to Browse" in _rendered(app, "#queue-data") + + asyncio.run(scenario()) + + async def failed_scenario(): + app = _app( + tmp_path, + queue=lambda: _queue_snapshot( + total_job_count=1, + active_job_count=0, + pending_job_count=0, + completed_job_count=0, + failed_job_count=1, + ), + ) + async with app.run_test() as pilot: + await pilot.pause() + assert "1 song needs attention" in _rendered(app, "#queue-data") + assert "Press 4 to Downloads" in _rendered(app, "#queue-data") + + asyncio.run(failed_scenario()) + + +def test_refresh_calls_both_services_again(tmp_path): + calls = {"library": 0, "queue": 0} + + def library(settings): + calls["library"] += 1 + return _library_status(tmp_path, track_count=calls["library"]) + + def queue(): + calls["queue"] += 1 + return _queue_snapshot(total_job_count=calls["queue"]) + + async def scenario(): + app = _app(tmp_path, library=library, queue=queue) + async with app.run_test() as pilot: + await pilot.pause() + assert calls == {"library": 1, "queue": 1} + await pilot.press("r") + await pilot.pause() + assert calls == {"library": 2, "queue": 2} + assert "Audio tracks 2" in _rendered(app, "#library-data") + assert "1 song ready to download" in _rendered(app, "#queue-data") + + asyncio.run(scenario()) + + +def test_keyboard_navigation_reaches_all_functional_screens(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test() as pilot: + await pilot.pause() + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + assert app.query_one("#browse-query") is not None + await pilot.press("3") + await pilot.pause() + assert app.screen.id == "screen-library" + assert app.query_one("#library-tracks") is not None + await pilot.press("5") + await pilot.pause() + assert app.screen.id == "screen-settings" + assert app.query_one("#settings-configuration") is not None + await pilot.press("4") + await pilot.pause() + assert app.screen.id == "screen-downloads" + assert app.query_one("#download-queue") is not None + await pilot.press("1") + await pilot.pause() + assert app.screen.id == "screen-dashboard" + + asyncio.run(scenario()) + + +def test_navigation_buttons_are_excluded_from_tab_focus(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test() as pilot: + await pilot.pause() + await pilot.press("tab") + assert app.focused is None + assert all(not item.can_focus for item in app.query("#primary-navigation NavigationItem")) + + asyncio.run(scenario()) + + +def test_click_navigation_switches_and_active_indicator_follows_screen(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test() as pilot: + await pilot.pause() + assert app.query_one("#nav-dashboard").has_class("-current") + assert "[1 Dashboard]" in _rendered(app, "#nav-dashboard") + assert "2 Browse" in _rendered(app, "#nav-browse") + assert "[2 Browse]" not in _rendered(app, "#nav-browse") + await pilot.click("#nav-browse") + await pilot.pause() + assert app.screen.id == "screen-browse" + assert app.query_one("#nav-browse").has_class("-current") + assert not app.query_one("#nav-dashboard").has_class("-current") + assert "[2 Browse]" in _rendered(app, "#nav-browse") + assert "[1 Dashboard]" not in _rendered(app, "#nav-dashboard") + assert app.focused is None + await pilot.press("slash") + assert app.focused is app.query_one("#browse-query") + + asyncio.run(scenario()) + + +def test_initial_shell_and_navigation_are_responsive_during_slow_load(tmp_path): + started = Event() + release = Event() + + def slow_library(settings): + started.set() + assert release.wait(timeout=5) + return _library_status(tmp_path) + + async def scenario(): + app = _app(tmp_path, library=slow_library) + async with app.run_test() as pilot: + await asyncio.to_thread(started.wait, 2) + assert "Loading library status" in _rendered(app, "#library-data") + assert app.screen.id == "screen-dashboard" + + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + await pilot.press("1") + await pilot.pause() + assert app.screen.id == "screen-dashboard" + + worker = app.screen._refresh_worker + assert worker is not None and not worker.is_finished + release.set() + await worker.wait() + await pilot.pause() + assert "Audio tracks 4" in _rendered(app, "#library-data") + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_refresh_uses_background_worker_and_supersedes_loading_state(tmp_path): + refresh_started = Event() + release = Event() + calls = 0 + + def library(settings): + nonlocal calls + calls += 1 + if calls == 2: + refresh_started.set() + assert release.wait(timeout=5) + return _library_status(tmp_path, track_count=calls) + + async def scenario(): + app = _app(tmp_path, library=library) + async with app.run_test() as pilot: + await pilot.pause() + assert "Audio tracks 1" in _rendered(app, "#library-data") + await pilot.press("r") + await asyncio.to_thread(refresh_started.wait, 2) + assert "Loading library status" in _rendered(app, "#library-data") + await pilot.press("r") + current_worker = app.screen._refresh_worker + assert current_worker is not None + await current_worker.wait() + await pilot.pause() + assert "Audio tracks 3" in _rendered(app, "#library-data") + await pilot.press("4") + await pilot.pause() + assert app.screen.id == "screen-downloads" + await pilot.press("1") + release.set() + await pilot.pause() + assert "Audio tracks 3" in _rendered(app, "#library-data") + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_q_exits_while_dashboard_provider_is_still_loading(tmp_path): + started = Event() + release = Event() + + def slow_library(settings): + started.set() + release.wait(timeout=5) + return _library_status(tmp_path) + + async def scenario(): + app = _app(tmp_path, library=slow_library) + async with app.run_test() as pilot: + await asyncio.to_thread(started.wait, 2) + await pilot.press("q") + assert not app.is_running + release.set() + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_service_exceptions_are_visible_and_navigation_survives(tmp_path): + def broken_library(settings): + raise OSError("library directory is unavailable") + + def broken_queue(): + raise ValueError("queue data is malformed") + + async def scenario(): + app = _app(tmp_path, library=broken_library, queue=broken_queue) + async with app.run_test() as pilot: + await pilot.pause() + assert "library directory is unavailable" in _rendered(app, "#library-error") + assert "Press 5 for Settings" in _rendered(app, "#library-data") + assert "queue data is malformed" in _rendered(app, "#queue-error") + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + + asyncio.run(scenario()) + + +def test_q_exits(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test() as pilot: + await pilot.press("q") + await pilot.pause() + assert not app.is_running + + asyncio.run(scenario()) + + +def test_shell_is_read_only_and_does_not_contact_api(tmp_path, monkeypatch): + import juice_lyrics.api.client as api_client + + root = tmp_path / "isolated-xdg" + monkeypatch.setattr( + api_client, + "api_get", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("API request made")), + ) + + async def scenario(): + app = _app(tmp_path) + async with app.run_test() as pilot: + await pilot.pause() + await pilot.press("2", "3", "4", "5", "1", "r") + await pilot.pause() + + asyncio.run(scenario()) + assert not root.exists() + assert not list(tmp_path.rglob("*.mp3")) + assert not list(tmp_path.rglob("*.lrc")) + assert not list(tmp_path.rglob("*.json")) + assert not list(tmp_path.rglob("*.toml")) + + +def test_cli_parser_and_dispatch_accept_tui_without_changing_other_commands(monkeypatch): + import juice_lyrics.cli as cli + + assert cli.build_parser().parse_args(["tui"]).command == "tui" + assert cli.build_parser().parse_args(["status"]).command == "status" + acquire = cli.build_parser().parse_args(["acquire", "jobs"]) + assert (acquire.command, acquire.action) == ("acquire", "jobs") + + called = [] + monkeypatch.setattr(cli, "command_tui", lambda settings: called.append(settings) or 0) + assert cli.main(["--path", "/tmp/library", "tui"]) == 0 + assert called and called[0].music_dir == Path("/tmp/library") + + +def test_narrow_terminal_uses_single_column_dashboard(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test(size=(50, 20)) as pilot: + await pilot.pause() + assert "-narrow" in app.screen.classes + assert "Audio tracks 4" in _rendered(app, "#library-data") + await pilot.press("5") + await pilot.pause() + assert app.screen.id == "screen-settings" + + asyncio.run(scenario()) + + +def test_ansi_mode_and_tui_styles_avoid_forced_theme_colors(tmp_path): + app = _app(tmp_path) + css = app.CSS.lower() + + assert app.ansi_color is True + assert not re.search(r"#[0-9a-f]{3}(?:[0-9a-f]{3})?\\b", css) + assert "rgb(" not in css + assert "$primary" not in css + assert "$secondary" not in css + assert "$accent" not in css + + +def test_active_navigation_uses_plain_static_widget_and_ansi_text_only(tmp_path): + app = _app(tmp_path) + css = app.CSS.lower() + item_rule = css.split( + "#primary-navigation navigationitem {", 1 + )[1].split("}", 1)[0] + active_rule = css.split( + "#primary-navigation navigationitem.-current:hover", 1 + )[1].split("}", 1)[0] + + assert issubclass(NavigationItem, Static) + assert not issubclass(NavigationItem, Button) + assert NavigationItem.can_focus is False + assert "background: transparent" in item_rule + assert "border: none" in item_rule + assert "background" not in active_rule + assert "color: ansi_blue" in active_rule + assert "text-style: bold" in active_rule + assert "underline" not in css + assert "reverse" not in active_rule + assert "navigationitem:focus" not in css + assert "navigationitem:focus-within" not in css + assert "navigationitem.-selected" not in css + assert "navigationitem.-active" not in css diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py new file mode 100644 index 0000000..852f85c --- /dev/null +++ b/tests/test_tui_browse.py @@ -0,0 +1,1384 @@ +import asyncio +from pathlib import Path +import sys +from threading import Event + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from textual.containers import VerticalScroll +from textual.widgets import Input, Select + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services import LibraryStatus, QueueSnapshot +from juice_lyrics.services.catalogue import ( + CatalogueSearchResult, + CatalogueFilterMetadata, + CatalogueFilterOption, + CataloguePage, + LyricAvailability, + SongDetails, +) +from juice_lyrics.services.download_queue import ( + DownloadQueueItem, + DownloadQueueItemStatus, + DownloadQueueSnapshot, + PlannedQueueItem, + QueueAddPlan, + QueueAddResult, + QueueAddStatus, + QueueBatchAddItem, + QueueBatchAddItemStatus, + QueueBatchAddPlan, + QueueBatchAddResult, + QueueBatchAddStatus, +) +from juice_lyrics.acquisition.models import AcquisitionItem +from juice_lyrics.tui import JuiceLyricsApp +from juice_lyrics.tui.help import guide_text + + +def _result( + index: int, + title: str, + *, + lyrics: LyricAvailability = LyricAvailability.SYNCED, + downloadable: bool = True, +) -> CatalogueSearchResult: + return CatalogueSearchResult( + selection_index=index, + song_id=index, + title=title, + category="unreleased", + era="DRFL", + length="3:21", + artists=("Juice WRLD",), + producers=(f"Producer {index}",), + media_path=f"Tracks/{title}.mp3" if downloadable else None, + lyrics=lyrics, + downloadable=downloadable, + ) + + +def _details( + result: CatalogueSearchResult, + *, + synced: str | None = None, + plain: str | None = None, +) -> SongDetails: + return SongDetails( + selection_index=result.selection_index, + song_id=result.song_id, + title=result.title, + category=result.category, + era=result.era, + length=result.length, + artists=result.artists, + producers=result.producers, + media_path=result.media_path, + lyrics=result.lyrics, + synced_lyrics=synced, + plain_lyrics=plain, + downloadable=result.downloadable, + ) + + +def _app( + tmp_path: Path, + *, + search, + details=None, + filters=None, + queue_plan=None, + queue_add=None, + downloads=None, +) -> JuiceLyricsApp: + return JuiceLyricsApp( + Settings(music_dir=tmp_path / "music"), + library_status_provider=lambda settings: LibraryStatus( + tmp_path / "music", 0, 0, 0, 0, 0, 0, 0 + ), + queue_snapshot_provider=lambda: QueueSnapshot((), 0, 0, 0, 0, 0), + catalogue_search_provider=search, + catalogue_details_provider=details or (lambda *args, **kwargs: None), + catalogue_filters_provider=filters or (lambda *args, **kwargs: CatalogueFilterMetadata( + categories=( + CatalogueFilterOption("Released", "released"), + CatalogueFilterOption("Unreleased", "unreleased"), + ), + eras=( + CatalogueFilterOption("DRFL", "DRFL", 110), + CatalogueFilterOption("JW3", "JW3", 111), + ), + )), + queue_plan_provider=queue_plan or (lambda *args, **kwargs: QueueAddResult( + QueueAddStatus.INVALID_SELECTION, "Queue planning is not configured for this test." + )), + queue_add_provider=queue_add or (lambda plan: QueueAddResult( + QueueAddStatus.SAVE_FAILED, "Queue writing is not configured for this test." + )), + downloads_queue_provider=downloads or (lambda: DownloadQueueSnapshot((), 0, 0, 0, 0, 0)), + ) + + +def _text(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +def _queue_plan(tmp_path: Path, result: CatalogueSearchResult) -> QueueAddPlan: + item = AcquisitionItem( + identifier=str(result.song_id), + title=result.title or "Unknown", + url="https://example.invalid/song.mp3", + destination=tmp_path / "music" / f"{result.title}.mp3", + metadata={"artist": "Juice WRLD", "category": result.category or "", "era": result.era or ""}, + ) + return QueueAddPlan((PlannedQueueItem( + item=item, + song_id=str(result.song_id), + artist="Juice WRLD", + category=result.category, + era=result.era, + ),)) + + +def _batch_plan( + tmp_path: Path, + results: tuple[CatalogueSearchResult, ...], + *, + extra: tuple[QueueBatchAddItem, ...] = (), +) -> QueueBatchAddPlan: + items = [] + for result in results: + single = _queue_plan(tmp_path, result).items[0] + items.append(QueueBatchAddItem( + str(result.song_id), + result.title or "Unknown", + QueueBatchAddItemStatus.ELIGIBLE, + "Ready to add.", + single, + )) + return QueueBatchAddPlan(tuple(items) + extra) + + +async def _open_browse(app: JuiceLyricsApp, pilot): + await pilot.press("2") + await pilot.pause() + return app.screen + + +async def _wait_queue_add(browse, pilot): + worker = browse._queue_add_worker + if worker is not None: + await worker.wait() + await pilot.pause(0.2) + + +async def _submit(app: JuiceLyricsApp, pilot, query: str): + field = app.query_one("#browse-query", Input) + field.value = query + field.focus() + await pilot.press("enter") + await pilot.pause() + worker = app.screen._search_worker + if worker is not None: + await worker.wait() + await pilot.pause() + + +def test_browse_is_functional_slash_focuses_and_empty_query_does_not_search(tmp_path): + calls = [] + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: calls.append((args, kwargs)) or ()) + async with app.run_test() as pilot: + screen = await _open_browse(app, pilot) + assert screen.__class__.__name__ == "BrowseScreen" + assert app.query_one("#browse-results") is not None + await pilot.press("/") + assert app.focused is app.query_one("#browse-query") + await pilot.press("enter") + await pilot.pause() + assert calls == [] + assert "Enter a title or choose at least one filter" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +def test_filter_only_searches_forward_category_era_and_both_from_filter_fields(tmp_path): + calls = [] + + def search(settings, query, **kwargs): + calls.append((query, kwargs)) + return (_result(1, "Filtered Song"),) + + async def submit_from(app, pilot, selector): + field = app.query_one(selector, Select) + field.focus() + await pilot.pause() + worker = app.screen._search_worker + assert worker is not None + await worker.wait() + await pilot.pause() + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + + app.query_one("#browse-category", Select).value = "unreleased" + await submit_from(app, pilot, "#browse-category") + assert calls[-1] == ("", {"category": "unreleased", "era": None, "page": 1, "page_size": 50, "refresh": False}) + + app.query_one("#browse-category", Select).value = "" + app.query_one("#browse-era", Select).value = "DRFL" + await submit_from(app, pilot, "#browse-era") + assert calls[-1] == ("", {"category": None, "era": "DRFL", "page": 1, "page_size": 50, "refresh": False}) + + app.query_one("#browse-category", Select).value = "unreleased" + await submit_from(app, pilot, "#browse-category") + assert calls[-1] == ("", {"category": "unreleased", "era": "DRFL", "page": 1, "page_size": 50, "refresh": False}) + assert "Filtered Song" in _text(app, "#browse-results") + assert "Filters: category=unreleased, era=DRFL" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +def test_filter_only_loading_empty_and_error_states(tmp_path): + started = Event() + release = Event() + mode = "slow" + + def search(settings, query, **kwargs): + if mode == "slow": + started.set() + release.wait(timeout=5) + return (_result(1, "Era Song"),) + if mode == "empty": + return () + raise RuntimeError("filtered catalogue failed") + + async def submit_era(app, pilot): + field = app.query_one("#browse-era", Select) + field.value = "DRFL" + field.focus() + app.screen.submit_search(refresh=False) + await pilot.pause() + + async def scenario(): + nonlocal mode + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await submit_era(app, pilot) + await asyncio.to_thread(started.wait, 2) + assert "Searching: era=DRFL" in _text(app, "#browse-status") + release.set() + await app.screen._search_worker.wait() + await pilot.pause() + assert "Era Song" in _text(app, "#browse-results") + + mode = "empty" + await submit_era(app, pilot) + await app.screen._search_worker.wait() + await pilot.pause() + assert "No catalogue results found" in _text(app, "#browse-results") + assert "No results for filters: era=DRFL" in _text(app, "#browse-status") + + mode = "error" + await submit_era(app, pilot) + await app.screen._search_worker.wait() + await pilot.pause() + assert "filtered catalogue failed" in _text(app, "#browse-status") + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_filter_only_refresh_and_screen_switch_preserve_blank_title_and_state(tmp_path): + calls = [] + results = (_result(1, "One"), _result(2, "Two")) + + def search(settings, query, **kwargs): + calls.append((query, kwargs)) + return results + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + app.query_one("#browse-category", Select).value = "unreleased" + app.query_one("#browse-era", Select).value = "DRFL" + await pilot.pause() + await app.screen._search_worker.wait() + await pilot.pause() + await pilot.press("down", "3", "2") + await pilot.pause() + assert app.query_one("#browse-query", Input).value == "" + assert app.query_one("#browse-category", Select).value == "unreleased" + assert app.query_one("#browse-era", Select).value == "DRFL" + assert "> Two" in _text(app, "#browse-results") + + await pilot.press("r") + await app.screen._search_worker.wait() + await pilot.pause() + assert calls[-1] == ("", {"category": "unreleased", "era": "DRFL", "page": 1, "page_size": 50, "refresh": True}) + + asyncio.run(scenario()) + + +def test_new_filter_only_search_supersedes_stale_filter_results(tmp_path): + first_started = Event() + release_first = Event() + + def search(settings, query, **kwargs): + if kwargs["era"] == "DRFL": + first_started.set() + release_first.wait(timeout=5) + return (_result(1, "Stale Era"),) + return (_result(1, "Fresh Era"),) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + era = app.query_one("#browse-era", Select) + era.value = "DRFL" + era.focus() + await pilot.pause() + await asyncio.to_thread(first_started.wait, 2) + + era.value = "JW3" + era.focus() + await pilot.pause() + current = app.screen._search_worker + assert current is not None + await current.wait() + await pilot.pause() + assert "Fresh Era" in _text(app, "#browse-results") + + release_first.set() + await pilot.pause() + assert "Stale Era" not in _text(app, "#browse-results") + + try: + asyncio.run(scenario()) + finally: + release_first.set() + + +def test_search_forwards_filters_and_preserves_service_order(tmp_path): + calls = [] + expected = (_result(1, "First"), _result(2, "Second"), _result(3, "Third")) + + def search(settings, query, **kwargs): + calls.append((query, kwargs)) + return expected + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test(size=(120, 30)) as pilot: + await _open_browse(app, pilot) + app.query_one("#browse-category", Select).value = "unreleased" + app.query_one("#browse-era", Select).value = "DRFL" + await _submit(app, pilot, "rental") + + assert calls[-1] == ("rental", {"category": "unreleased", "era": "DRFL", "page": 1, "page_size": 50, "refresh": False}) + rendered = _text(app, "#browse-results") + assert rendered.index("First") < rendered.index("Second") < rendered.index("Third") + assert "Filters: category=unreleased, era=DRFL" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +def test_slow_search_shows_loading_and_navigation_remains_responsive(tmp_path): + started = Event() + release = Event() + + def search(*args, **kwargs): + started.set() + assert release.wait(timeout=5) + return (_result(1, "Rental"),) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + field = app.query_one("#browse-query", Input) + field.value = "rental" + field.focus() + await pilot.press("enter") + await asyncio.to_thread(started.wait, 2) + assert "Searching" in _text(app, "#browse-status") + assert "Searching" in _text(app, "#browse-results") + await pilot.press("3") + await pilot.pause() + assert app.screen.id == "screen-library" + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + release.set() + worker = app.screen._search_worker + assert worker is not None + await worker.wait() + await pilot.pause() + assert "Rental" in _text(app, "#browse-results") + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_q_exits_during_slow_search(tmp_path): + started = Event() + release = Event() + + def search(*args, **kwargs): + started.set() + release.wait(timeout=5) + return () + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + field = app.query_one("#browse-query", Input) + field.value = "slow" + field.focus() + await pilot.press("enter") + await asyncio.to_thread(started.wait, 2) + await pilot.press("q") + assert not app.is_running + release.set() + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_empty_results_and_provider_errors_are_safe(tmp_path): + calls = 0 + + def search(*args, **kwargs): + nonlocal calls + calls += 1 + if calls == 1: + return () + raise RuntimeError("catalogue is unavailable") + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "missing") + assert "No catalogue results found" in _text(app, "#browse-results") + await _submit(app, pilot, "broken") + assert "Search unavailable" in _text(app, "#browse-results") + assert "catalogue is unavailable" in _text(app, "#browse-status") + assert app.is_running + + asyncio.run(scenario()) + + +def test_new_search_supersedes_stale_worker_result(tmp_path): + first_started = Event() + release_first = Event() + + def search(settings, query, **kwargs): + if query == "first": + first_started.set() + release_first.wait(timeout=5) + return (_result(1, "Stale Result"),) + return (_result(1, "Fresh Result"),) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + field = app.query_one("#browse-query", Input) + field.value = "first" + field.focus() + await pilot.press("enter") + await asyncio.to_thread(first_started.wait, 2) + + field.value = "second" + field.focus() + await pilot.press("enter") + current = app.screen._search_worker + assert current is not None + await current.wait() + await pilot.pause() + assert "Fresh Result" in _text(app, "#browse-results") + + release_first.set() + await pilot.pause() + assert "Stale Result" not in _text(app, "#browse-results") + + try: + asyncio.run(scenario()) + finally: + release_first.set() + + +def test_arrow_jk_selection_updates_basic_details_and_enter_loads_full_details(tmp_path): + results = (_result(1, "One"), _result(2, "Two"), _result(3, "Three")) + detail_calls = [] + + def details(settings, query, **kwargs): + detail_calls.append((query, kwargs)) + selected = results[kwargs["selection_index"] - 1] + return _details(selected, synced="[00:01.00] selected lyric") + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: results, details=details) + async with app.run_test(size=(120, 30)) as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + assert "> One" in _text(app, "#browse-results") + await pilot.press("down") + await pilot.pause() + assert "> Two" in _text(app, "#browse-results") + assert "Producer 2" in _text(app, "#browse-details") + await pilot.press("j") + await pilot.pause() + assert "> Three" in _text(app, "#browse-results") + await pilot.press("k") + await pilot.pause() + assert "> Two" in _text(app, "#browse-results") + await pilot.press("enter") + worker = app.screen._details_worker + assert worker is not None + await worker.wait() + await pilot.pause() + assert detail_calls == [(2, {"selection_index": 2})] + assert "[00:01.00] selected lyric" in _text(app, "#browse-details") + + asyncio.run(scenario()) + + +def test_details_use_frontend_lyrics_terms_preview_limits_and_download_labels(tmp_path): + results = ( + _result(1, "Synced", lyrics=LyricAvailability.SYNCED), + _result(2, "Plain", lyrics=LyricAvailability.PLAIN), + _result(3, "Missing", lyrics=LyricAvailability.NONE, downloadable=False), + ) + synced = "\n".join(f"[00:0{i}.00] line {i}" for i in range(8)) + + def details(settings, query, **kwargs): + result = results[kwargs["selection_index"] - 1] + return _details( + result, + synced=synced if result.lyrics is LyricAvailability.SYNCED else None, + plain="ordinary plain lyrics" if result.lyrics is LyricAvailability.PLAIN else None, + ) + + async def load_current(app, pilot): + await pilot.press("enter") + await app.screen._details_worker.wait() + await pilot.pause() + return _text(app, "#browse-details") + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: results, details=details) + async with app.run_test(size=(120, 32)) as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "lyrics") + text = await load_current(app, pilot) + assert "Lyrics Synced" in text + assert "[00:05.00] line 5" in text + assert "[00:06.00] line 6" not in text + assert "…" in text + assert "Download Available" in text + + await pilot.press("down") + text = await load_current(app, pilot) + assert "Lyrics Plain" in text + assert "ordinary plain lyrics" in text + + await pilot.press("down") + text = await load_current(app, pilot) + assert "Lyrics None" in text + assert "No lyrics available" in text + assert "Download Unavailable" in text + assert "SYLT" not in text and "USLT" not in text + + asyncio.run(scenario()) + + +def test_refresh_forwards_refresh_and_state_survives_section_switch(tmp_path): + calls = [] + results = (_result(1, "One"), _result(2, "Two")) + + def search(settings, query, **kwargs): + calls.append((query, kwargs)) + return results + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "persist") + await pilot.press("down") + await pilot.press("3", "2") + await pilot.pause() + assert app.query_one("#browse-query", Input).value == "persist" + assert "> Two" in _text(app, "#browse-results") + await pilot.press("r") + worker = app.screen._search_worker + assert worker is not None + await worker.wait() + await pilot.pause() + assert calls[-1] == ("persist", {"category": None, "era": None, "page": 1, "page_size": 50, "refresh": True}) + + asyncio.run(scenario()) + + +def test_narrow_browse_stacks_layout_and_remains_usable(tmp_path): + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: (_result(1, "Narrow Song"),)) + async with app.run_test(size=(50, 24)) as pilot: + await _open_browse(app, pilot) + assert "-narrow" in app.screen.classes + await _submit(app, pilot, "narrow") + rendered = _text(app, "#browse-results") + assert "> Narrow Song" in rendered + assert "DRFL · unreleased · Synced · Available" in rendered + + asyncio.run(scenario()) + + +def test_browse_is_read_only_and_has_no_live_api_dependency(tmp_path, monkeypatch): + import juice_lyrics.api.client as api_client + + monkeypatch.setattr( + api_client, + "api_get", + lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("live API called")), + ) + calls = [] + + async def scenario(): + app = _app( + tmp_path, + search=lambda *args, **kwargs: calls.append("search") or (_result(1, "Offline"),), + details=lambda *args, **kwargs: calls.append("details") or _details(_result(1, "Offline")), + ) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "offline") + await pilot.press("enter") + await app.screen._details_worker.wait() + await pilot.pause() + + asyncio.run(scenario()) + assert calls == ["search", "details"] + assert not list(tmp_path.rglob("*.mp3")) + assert not list(tmp_path.rglob("*.flac")) + assert not list(tmp_path.rglob("*.json")) + assert not list(tmp_path.rglob("*.lrc")) + assert not list(tmp_path.rglob("*.toml")) + + +def test_pagination_next_previous_home_refresh_and_later_page_details(tmp_path): + calls = [] + detail_ids = [] + + def search(settings, query, **kwargs): + calls.append((query, kwargs)) + page = kwargs["page"] + if page == 1: + results = tuple(_result(index, f"Page One {index}") for index in range(1, 51)) + return CataloguePage(results, 1, 50, 75, 2, None) + results = tuple(_result(index, f"Page Two {index}") for index in range(51, 76)) + return CataloguePage(results, 2, 50, 75, None, 1) + + def details(settings, song_id, **kwargs): + detail_ids.append(song_id) + result = _result(song_id, f"Page Two {song_id}") + return _details(result, synced="[00:01.00] later page") + + async def scenario(): + app = _app(tmp_path, search=search, details=details) + async with app.run_test(size=(120, 32)) as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "page") + assert "Result 1 of 50 loaded" in _text(app, "#browse-status") + assert "Page 1 of 2 · Results 1–50 of 75" in _text(app, "#browse-page-position") + initial_calls = len(calls) + await pilot.press("p") + await pilot.pause() + assert len(calls) == initial_calls + + await pilot.press("n") + await app.screen._search_worker.wait() + await pilot.pause() + assert "Page 2 of 2 · Results 51–75 of 75" in _text(app, "#browse-page-position") + assert not app.query_one("#browse-next").available + assert "> Page Two 51" in _text(app, "#browse-results") + await pilot.press("enter") + await app.screen._details_worker.wait() + await pilot.pause() + assert detail_ids == [51] + assert "later page" in _text(app, "#browse-details") + + await pilot.press("r") + await app.screen._search_worker.wait() + assert calls[-1][1]["page"] == 2 and calls[-1][1]["refresh"] is True + + await pilot.press("p") + await app.screen._search_worker.wait() + await pilot.press("n") + await app.screen._search_worker.wait() + await pilot.press("home") + await pilot.pause() + assert app.screen.selected_index == 0 + assert "Page 2 of 2 · Results 51–75 of 75" in _text(app, "#browse-page-position") + + asyncio.run(scenario()) + + +def test_loaded_page_scrolls_all_fifty_results_and_supports_list_navigation(tmp_path): + calls = [] + + def search(settings, query, **kwargs): + calls.append(kwargs.copy()) + page = kwargs["page"] + start = (page - 1) * 50 + 1 + results = tuple(_result(index, f"Song {index}") for index in range(start, start + 50)) + return CataloguePage(results, page, 50, 1485, page + 1, page - 1 if page > 1 else None) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test(size=(80, 24)) as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + scroll = app.query_one("#browse-results-scroll", VerticalScroll) + rendered = _text(app, "#browse-results") + + assert len(app.screen.results) == 50 + assert "Song 1" in rendered and "Song 50" in rendered + assert scroll.max_scroll_y > 0 + assert app.query_one("#browse-pagination").region.height > 0 + assert app.query_one("#browse-pagination").region.bottom <= app.screen.region.bottom + assert "Page 1 of 30 · Results 1–50 of 1,485" in _text(app, "#browse-page-position") + assert not app.query_one("#browse-previous").available + assert "[p Previous]" in _text(app, "#browse-previous") + assert "[n Next]" in _text(app, "#browse-next") + assert "a add" in _text(app, "#browse-shortcuts").lower() + + for _ in range(34): + await pilot.press("down") + await pilot.pause() + assert app.screen.selected_index == 34 + assert "> Song 35" in _text(app, "#browse-results") + assert "Song 35" in _text(app, "#browse-details") + assert scroll.scroll_y <= 34 < scroll.scroll_y + scroll.size.height + + await pilot.press("end") + await pilot.pause() + assert app.screen.selected_index == 49 + assert "> Song 50" in _text(app, "#browse-results") + assert scroll.scroll_y <= 49 < scroll.scroll_y + scroll.size.height + + await pilot.press("home", "pagedown") + await pilot.pause() + page_step_index = app.screen.selected_index + assert 0 < page_step_index < 49 + assert len(calls) == 1 + await pilot.press("pageup") + await pilot.pause() + assert app.screen.selected_index == 0 + + await pilot.press("end") + await pilot.pause() + assert scroll.scroll_y > 0 + clicked = await pilot.click("#browse-next") + assert clicked, ( + app.query_one("#browse-next").region, + app.query_one("#browse-pagination").region, + ) + await pilot.pause() + await app.screen._search_worker.wait() + await pilot.pause() + assert calls[-1]["page"] == 2 + assert app.screen.selected_index == 0 + assert scroll.scroll_y == 0 + assert "Page 2 of 30 · Results 51–100 of 1,485" in _text(app, "#browse-page-position") + assert app.query_one("#browse-previous").available + + await pilot.click("#browse-previous") + await pilot.pause() + await app.screen._search_worker.wait() + await pilot.pause() + assert calls[-1]["page"] == 1 + + asyncio.run(scenario()) + + +def test_browse_help_distinguishes_loaded_result_scrolling_from_api_pages(tmp_path): + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: ()) + async with app.run_test(size=(80, 24)) as pilot: + await _open_browse(app, pilot) + await pilot.press("question_mark") + assert app.screen.__class__.__name__ == "HelpScreen" + help_text = _text(app, "#help-content") + assert "Next / previous catalogue page" in help_text + assert "Scroll loaded results" in help_text + assert "First / last result" in help_text + await pilot.press("escape") + assert app.screen.id == "screen-browse" + + asyncio.run(scenario()) + + +def test_global_help_covers_sections_scrolls_and_traps_navigation(tmp_path): + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: ()) + async with app.run_test(size=(70, 22)) as pilot: + for section in ("dashboard", "browse", "library", "downloads", "settings"): + if app.focused is not None and isinstance(app.focused, Input): + await pilot.press("escape") + await pilot.press(str(("dashboard", "browse", "library", "downloads", "settings").index(section) + 1)) + await pilot.press("question_mark") + assert app.screen.__class__.__name__ == "HelpScreen" + guide = _text(app, "#help-content") + for heading in ("Global", "Browse", "Library", "Downloads", "Settings", "Confirmations"): + assert heading in guide + scroll = app.query_one("#help-scroll", VerticalScroll) + assert scroll.max_scroll_y > 0 + await pilot.press("pagedown") + assert scroll.scroll_y > 0 + await pilot.press("2") + assert app.screen.__class__.__name__ == "HelpScreen" + await pilot.press("escape") + assert app.screen.id == f"screen-{section}" + + asyncio.run(scenario()) + + +def test_search_input_accepts_q_and_help_can_open_while_focused(tmp_path): + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: ()) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + field = app.query_one("#browse-query", Input) + field.focus() + await pilot.press("q", "1", "0") + assert field.value == "q10" + assert app.screen.id == "screen-browse" + await pilot.press("question_mark") + assert app.screen.__class__.__name__ == "HelpScreen" + await pilot.press("escape") + assert app.screen.id == "screen-browse" + await pilot.press("escape", "3") + assert app.screen.id == "screen-library" + + asyncio.run(scenario()) + + +def test_help_inventories_app_bindings_and_focus_palette(): + guide = guide_text() + for label in ("Switch sections", "Refresh current section", "Open Help", "Quit", + "Mark or unmark", "Download entire queue", "Preview and maintain", + "Open Library Issues", + "Review duplicate recordings", + "Review and apply selected metadata repairs", + "Choose and lock a catalogue match", "Unlock and clear a manual match", + "Inspect setting", "Confirm immediately"): + assert label in guide + assert "#browse-controls Input:focus" in JuiceLyricsApp.CSS + assert "#library-controls Input:focus" in JuiceLyricsApp.CSS + assert "SelectOverlay:focus" in JuiceLyricsApp.CSS + assert "background-tint: transparent" in JuiceLyricsApp.CSS + assert "#browse-controls Input > .input--cursor" in JuiceLyricsApp.CSS + + +def test_fifty_result_page_remains_scrollable_at_realistic_terminal_sizes(tmp_path): + results = tuple(_result(index, f"Visible Song {index}") for index in range(1, 51)) + + async def scenario(size): + app = _app( + tmp_path, + search=lambda settings, query, **kwargs: CataloguePage(results, 1, 50, 1485, 2, None), + ) + async with app.run_test(size=size) as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "visible") + scroll = app.query_one("#browse-results-scroll", VerticalScroll) + pagination = app.query_one("#browse-pagination") + assert len(app.screen.results) == 50 + assert 5 <= scroll.size.height < 50 + assert scroll.max_scroll_y > 0 + assert pagination.region.height > 0 + assert pagination.region.bottom <= app.screen.region.bottom + + for size in ((80, 24), (100, 30), (120, 40)): + asyncio.run(scenario(size)) + + +def test_filter_change_resets_pagination_to_first_page(tmp_path): + calls = [] + + def search(settings, query, **kwargs): + calls.append(kwargs.copy()) + result = (_result(1, "Result"),) + return CataloguePage(result, kwargs["page"], 50, 60, 2 if kwargs["page"] == 1 else None, 1 if kwargs["page"] > 1 else None) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "filter reset") + await pilot.press("n") + await app.screen._search_worker.wait() + assert calls[-1]["page"] == 2 + + app.query_one("#browse-era", Select).value = "DRFL" + await pilot.pause() + await app.screen._search_worker.wait() + assert calls[-1]["page"] == 1 + assert calls[-1]["era"] == "DRFL" + + asyncio.run(scenario()) + + +def test_stale_page_response_cannot_replace_new_first_page(tmp_path): + page_two_started = Event() + release_page_two = Event() + + def search(settings, query, **kwargs): + if kwargs["page"] == 2: + page_two_started.set() + release_page_two.wait(timeout=5) + return CataloguePage((_result(51, "Stale Page Two"),), 2, 50, 60, None, 1) + return CataloguePage((_result(1, f"Fresh {query}"),), 1, 50, 60, 2, None) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "old") + await pilot.press("n") + await asyncio.to_thread(page_two_started.wait, 2) + + field = app.query_one("#browse-query", Input) + field.value = "new" + field.focus() + await pilot.press("enter") + current = app.screen._search_worker + assert current is not None + await current.wait() + await pilot.pause() + assert "Fresh new" in _text(app, "#browse-results") + + release_page_two.set() + await pilot.pause() + assert "Stale Page Two" not in _text(app, "#browse-results") + + try: + asyncio.run(scenario()) + finally: + release_page_two.set() + + +def test_selector_keyboard_confirmation_uses_canonical_value(tmp_path): + calls = [] + + async def scenario(): + app = _app(tmp_path, search=lambda settings, query, **kwargs: calls.append(kwargs) or ()) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + category = app.query_one("#browse-category", Select) + category.focus() + await pilot.press("enter", "down", "down", "enter") + await pilot.pause() + worker = app.screen._search_worker + assert worker is not None + await worker.wait() + assert category.value == "unreleased" + assert calls[-1]["category"] == "unreleased" + + asyncio.run(scenario()) + + +def test_filter_metadata_failure_disables_selectors_but_title_search_survives(tmp_path): + calls = [] + + def broken_filters(*args, **kwargs): + raise RuntimeError("metadata endpoint unavailable") + + async def scenario(): + app = _app( + tmp_path, + search=lambda settings, query, **kwargs: calls.append(query) or (), + filters=broken_filters, + ) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + worker = app.screen._filters_worker + assert worker is not None + await worker.wait() + await pilot.pause() + assert app.query_one("#browse-category", Select).disabled + assert app.query_one("#browse-era", Select).disabled + assert "Filter metadata unavailable" in _text(app, "#browse-status") + await _submit(app, pilot, "Rental") + assert calls == ["Rental"] + + asyncio.run(scenario()) + + +def test_add_to_queue_is_immediate_and_does_not_download(tmp_path): + calls = [] + song = _result(1, "Rental") + + def planner(settings, selections): + calls.append(selections) + return QueueAddResult(QueueAddStatus.READY, "Ready", plan=_queue_plan(tmp_path, selections[0])) + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: (song,), queue_plan=planner) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "rental") + browse = app.screen + await pilot.press("a") + await browse._queue_plan_worker.wait() + await _wait_queue_add(browse, pilot) + assert app.screen.id == "screen-browse" + assert len(calls) == 1 + assert "not configured" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +def test_confirm_adds_once_preserves_browse_and_can_open_refreshed_downloads(tmp_path): + created = [] + song = _result(1, "Rental") + queued = DownloadQueueItem( + reference="internal:0", song_id="1", title="Rental", artist="Juice WRLD", + category="unreleased", era="DRFL", destination=tmp_path / "music" / "Rental.mp3", + status=DownloadQueueItemStatus.QUEUED, bytes_written=0, expected_bytes=None, + failure_stage=None, error=None, retryable=True, + queued_at="2026-08-30T12:00:00+00:00", + ) + + def planner(settings, selections): + return QueueAddResult(QueueAddStatus.READY, "Ready", plan=_queue_plan(tmp_path, selections[0])) + + def creator(plan): + created.append(plan) + return QueueAddResult(QueueAddStatus.ADDED, "Added 1 song to the download queue.", added_count=1) + + def downloads(): + items = (queued,) if created else () + return DownloadQueueSnapshot(items, len(items), 0, 0, 0, 0) + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: (song,), queue_plan=planner, + queue_add=creator, downloads=downloads) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "rental") + browse = app.screen + await pilot.press("a") + await browse._queue_plan_worker.wait() + await _wait_queue_add(browse, pilot) + assert len(created) == 1 + assert "not started" in _text(app, "#browse-status") + await pilot.press("4") + await pilot.pause() + if app.screen._refresh_worker is not None: + await app.screen._refresh_worker.wait() + await pilot.pause() + assert app.screen.id == "screen-downloads" + assert "Rental" in _text(app, "#download-queue") + await pilot.press("2") + await pilot.pause() + assert app.query_one("#browse-query", Input).value == "rental" + assert "> Rental" in _text(app, "#browse-results") + + asyncio.run(scenario()) + + +def test_add_to_queue_rejections_and_input_guard(tmp_path): + plan_calls = [] + available = _result(1, "Available") + unavailable = _result(2, "Unavailable", downloadable=False) + + def planner(settings, selections): + plan_calls.append(selections[0].title) + return QueueAddResult(QueueAddStatus.ALREADY_QUEUED, "Available is already in the queue.") + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: (available, unavailable), queue_plan=planner) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + field = app.query_one("#browse-query", Input) + field.focus() + await pilot.press("a") + assert plan_calls == [] + category = app.query_one("#browse-category", Select) + category.focus() + await pilot.press("enter") + assert category.expanded + await pilot.press("a") + assert plan_calls == [] + await pilot.press("escape") + app.screen.set_focus(None) + await pilot.press("a") + await app.screen._queue_plan_worker.wait() + await pilot.pause() + assert "already in the queue" in _text(app, "#browse-status") + await pilot.press("down", "a") + assert plan_calls == ["Available"] + assert "Media unavailable" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +def test_add_to_queue_store_failure_is_safe_and_slow_planning_does_not_block_navigation(tmp_path): + started = Event() + release = Event() + song = _result(1, "Rental") + + def slow_planner(settings, selections): + started.set() + release.wait(timeout=5) + return QueueAddResult(QueueAddStatus.READY, "Ready", plan=_queue_plan(tmp_path, selections[0])) + + async def navigation_scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: (song,), queue_plan=slow_planner) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "rental") + browse = app.screen + await pilot.press("a") + await asyncio.to_thread(started.wait, 2) + assert "Checking destination" in _text(app, "#browse-status") + await pilot.press("4") + assert app.screen.id == "screen-downloads" + release.set() + await browse._queue_plan_worker.wait() + await pilot.pause() + assert app.screen.id == "screen-downloads" + + async def failure_scenario(): + planner = lambda settings, selections: QueueAddResult( + QueueAddStatus.READY, "Ready", plan=_queue_plan(tmp_path, selections[0]) + ) + creator = lambda plan: QueueAddResult( + QueueAddStatus.SAVE_FAILED, "Unable to save the queue: permission denied." + ) + app = _app(tmp_path, search=lambda *args, **kwargs: (song,), queue_plan=planner, queue_add=creator) + async with app.run_test() as pilot: + await _open_browse(app, pilot) + await _submit(app, pilot, "rental") + browse = app.screen + await pilot.press("a") + await browse._queue_plan_worker.wait() + await _wait_queue_add(browse, pilot) + assert "permission denied" in _text(app, "#browse-status") + assert app.screen.id == "screen-browse" + + try: + asyncio.run(navigation_scenario()) + asyncio.run(failure_scenario()) + finally: + release.set() + + +def test_browse_marks_cursor_and_page_selection_are_independent(tmp_path): + songs = (_result(1, "First"), _result(2, "Second"), _result(3, "Unavailable", downloadable=False)) + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: songs) + async with app.run_test(size=(100, 30)) as pilot: + browse = await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + assert "[ ]" not in _text(app, "#browse-results") + assert "a Add" in _text(app, "#browse-shortcuts") + await pilot.press("space") + assert set(browse.marked) == {"1"} + assert "First" in _text(app, "#browse-results") and "[x]" in _text(app, "#browse-results") + assert "1 song marked" in _text(app, "#browse-results-title") + assert "a Add selected" in _text(app, "#browse-shortcuts") + await pilot.press("down") + assert set(browse.marked) == {"1"} + await pilot.press("space") + assert set(browse.marked) == {"1", "2"} + assert "2 songs marked" in _text(app, "#browse-results-title") + await pilot.press("M") + assert browse.marked == {} + await pilot.press("M") + assert set(browse.marked) == {"1", "2"} + await pilot.press("u") + assert browse.marked == {} + assert "Selection cleared" in _text(app, "#browse-status") + assert "[ ]" not in _text(app, "#browse-results") + assert "a Add" in _text(app, "#browse-shortcuts") + + asyncio.run(scenario()) + + +def test_marks_span_pages_but_search_and_filter_changes_clear_them(tmp_path): + first = _result(1, "Page One") + second = _result(51, "Page Two") + + def search(settings, query, **kwargs): + page = kwargs["page"] + return CataloguePage( + (first,) if page == 1 else (second,), + page, + 50, + 100, + page + 1 if page < 2 else None, + page - 1 if page > 1 else None, + ) + + async def scenario(): + app = _app(tmp_path, search=search) + async with app.run_test() as pilot: + browse = await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + await pilot.press("space") + await pilot.pause() + assert set(browse.marked) == {"1"} + await pilot.press("n") + await browse._search_worker.wait() + await pilot.pause() + await pilot.press("space") + assert set(browse.marked) == {"1", "51"} + await pilot.press("p") + await browse._search_worker.wait() + await pilot.pause() + assert set(browse.marked) == {"1", "51"} + query = app.query_one("#browse-query", Input) + query.value = "changed" + query.focus() + await pilot.press("enter") + await browse._search_worker.wait() + await pilot.pause() + assert browse.marked == {} + assert "Selection cleared because the search changed" in _text(app, "#browse-status") + + browse.set_focus(None) + await pilot.press("space") + assert browse.marked + category = app.query_one("#browse-category", Select) + category.value = "unreleased" + await pilot.pause() + await browse._search_worker.wait() + await pilot.pause() + assert browse.marked == {} + + asyncio.run(scenario()) + + +def test_batch_add_is_immediate_and_captures_stable_targets(tmp_path): + songs = (_result(1, "First"), _result(2, "Second"), _result(9, "Already there")) + created = [] + + def planner(settings, selections): + plan = _batch_plan(tmp_path, tuple(selections[:2]), extra=( + QueueBatchAddItem("9", "Already there", QueueBatchAddItemStatus.ALREADY_QUEUED, "Already queued."), + )) + return QueueBatchAddResult(QueueBatchAddStatus.READY, "Ready", plan=plan) + + def creator(plan): + created.append(plan) + return QueueBatchAddResult( + QueueBatchAddStatus.ADDED, + "Added 2 songs · 1 already queued", + plan=plan, + added_count=2, + added_song_ids=("1", "2"), + ) + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: songs, queue_plan=planner, queue_add=creator) + async with app.run_test(size=(80, 24)) as pilot: + browse = await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + await pilot.press("M", "a") + await browse._queue_plan_worker.wait() + await _wait_queue_add(browse, pilot) + assert app.screen is browse + assert len(created) == 1 + assert [item.song_id for item in created[0].eligible] == ["1", "2"] + assert "Added 2 songs" in _text(app, "#browse-status") + assert "1" not in browse.marked and "2" not in browse.marked + + asyncio.run(scenario()) + + +def test_browse_batch_help_shortcuts_and_unavailable_mark_guard(tmp_path): + songs = (_result(1, "Available"), _result(2, "Unavailable", downloadable=False)) + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: songs) + async with app.run_test(size=(80, 24)) as pilot: + browse = await _open_browse(app, pilot) + await _submit(app, pilot, "songs") + shortcuts = app.query_one("#browse-shortcuts") + assert shortcuts.region.height == 1 + shortcuts_text = _text(app, "#browse-shortcuts") + assert "a add" in shortcuts_text.lower() + assert "enter details" in shortcuts_text.lower() + assert "M" not in shortcuts_text and "u clear" not in shortcuts_text.lower() + results_scroll = app.query_one("#browse-results-scroll", VerticalScroll) + assert results_scroll.region.height >= 5 + await pilot.press("down", "space") + assert browse.marked == {} + assert "cannot be marked" in _text(app, "#browse-status") + await pilot.press("question_mark") + help_text = _text(app, "#help-content") + assert "Mark or unmark song" in help_text + assert "Toggle marks on this page" in help_text + assert "Add current or marked songs" in help_text + assert "Switch sections" in help_text + + asyncio.run(scenario()) + + +def test_disappeared_mark_is_revalidated_as_unavailable_not_replaced_by_row_index(tmp_path): + original = _result(1, "Original") + replacement = _result(2, "Replacement") + planned = [] + + def search(settings, query, **kwargs): + return (replacement,) if kwargs.get("refresh") else (original,) + + def planner(settings, selections): + planned.extend(selections) + plan = QueueBatchAddPlan((QueueBatchAddItem( + "1", "Original", QueueBatchAddItemStatus.UNAVAILABLE, "No longer available." + ),)) + return QueueBatchAddResult(QueueBatchAddStatus.NOTHING_TO_ADD, "No songs added · 1 unavailable", plan=plan) + + async def scenario(): + app = _app(tmp_path, search=search, queue_plan=planner) + async with app.run_test() as pilot: + browse = await _open_browse(app, pilot) + await _submit(app, pilot, "song") + await pilot.press("space") + await pilot.pause() + await pilot.press("r") + await browse._search_worker.wait() + await pilot.pause() + assert set(browse.marked) == {"1"} + assert browse.results[0].song_id == 2 + await pilot.press("a") + await browse._queue_plan_worker.wait() + await pilot.pause() + assert [item.song_id for item in planned] == [1] + assert not planned[0].downloadable + assert app.screen is browse + assert "unavailable" in _text(app, "#browse-status") + + asyncio.run(scenario()) diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py new file mode 100644 index 0000000..c18359f --- /dev/null +++ b/tests/test_tui_downloads.py @@ -0,0 +1,878 @@ +import asyncio +from pathlib import Path +import sys +from threading import Event + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from textual.containers import VerticalScroll + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services import ( + CatalogueFilterMetadata, + DownloadExecutionAction, + DownloadExecutionPlan, + DownloadExecutionResult, + DownloadExecutionStatus, + DownloadAllPlan, + DownloadAllResult, + DownloadBatchStatus, + DownloadProgress, + DownloadQueueItemStatus, + LibraryStatus, + QueueFailureStage, + QueueItem, + QueueJob, + QueueSnapshot, + QueueStatus, + QueueMutationResult, + QueueMutationStatus, +) +from juice_lyrics.services.download_queue import DownloadRetryAction, DownloadRetryPlan, DownloadRetryResult, DownloadRetryStatus +from juice_lyrics.tui import JuiceLyricsApp + + +_ACTIVE = { + QueueStatus.CHECKING_EXISTING, + QueueStatus.DOWNLOADING, + QueueStatus.VALIDATING, + QueueStatus.POST_PROCESSING, +} + + +def _item( + tmp_path: Path, + title: str, + status: QueueStatus, + *, + failure_stage: QueueFailureStage | None = None, + error: str | None = None, + postprocessing_retryable: bool = False, +) -> QueueItem: + return QueueItem( + title=title, + destination=tmp_path / f"{title}.mp3", + status=status, + stored_state=status.value, + bytes_written=100 if status in {QueueStatus.COMPLETED, QueueStatus.FAILED} else 25, + expected_bytes=100, + resumed=False, + error=error, + retryable=status not in {QueueStatus.COMPLETED, QueueStatus.SKIPPED, QueueStatus.UNKNOWN}, + failure_stage=failure_stage, + postprocessing_retryable=postprocessing_retryable, + ) + + +def _job( + number: int, + job_id: str, + items: tuple[QueueItem, ...], + *, + created_at: str = "2026-08-30T12:00:00+00:00", +) -> QueueJob: + statuses = tuple(item.status for item in items) + if QueueStatus.FAILED in statuses: + status = QueueStatus.FAILED + elif statuses and all(value in {QueueStatus.COMPLETED, QueueStatus.SKIPPED} for value in statuses): + status = QueueStatus.COMPLETED + elif any(value in _ACTIVE for value in statuses): + status = next(value for value in statuses if value in _ACTIVE) + elif not statuses: + status = QueueStatus.COMPLETED + else: + status = QueueStatus.PENDING + completed = sum(value in {QueueStatus.COMPLETED, QueueStatus.SKIPPED} for value in statuses) + return QueueJob( + display_number=number, + job_id=job_id, + label=items[0].title if len(items) == 1 else f"{items[0].title} + {len(items) - 1} more" if items else "Untitled job", + created_at=created_at, + destination=items[0].destination if len(items) == 1 else None, + total_item_count=len(items), + pending_item_count=sum(value in {QueueStatus.PENDING, QueueStatus.UNKNOWN} for value in statuses), + active_item_count=sum(value in _ACTIVE for value in statuses), + completed_item_count=completed, + failed_item_count=sum(value is QueueStatus.FAILED for value in statuses), + status=status, + stored_state=status.value, + retryable=any(item.retryable for item in items), + deletion_allowed=not any(value in _ACTIVE for value in statuses), + items=items, + updated_at="2026-08-30T12:05:00+00:00", + ) + + +def _snapshot(*jobs: QueueJob) -> QueueSnapshot: + return QueueSnapshot( + jobs=jobs, + total_job_count=len(jobs), + active_job_count=sum(job.status in _ACTIVE for job in jobs), + pending_job_count=sum(job.status in {QueueStatus.PENDING, QueueStatus.UNKNOWN} for job in jobs), + completed_job_count=sum(job.status is QueueStatus.COMPLETED for job in jobs), + failed_job_count=sum(job.status is QueueStatus.FAILED for job in jobs), + ) + + +def _app(tmp_path: Path, provider, *, plan=None, execute=None, batch_plan=None, batch_execute=None, history=None) -> JuiceLyricsApp: + empty = _snapshot() + plan = plan or (lambda settings, reference: DownloadExecutionResult( + DownloadExecutionStatus.NOT_ELIGIBLE, + "Not eligible", + )) + execute = execute or (lambda settings, plan, **kwargs: DownloadExecutionResult( + DownloadExecutionStatus.FAILED, + "Execution provider was not configured", + plan=plan, + )) + return JuiceLyricsApp( + Settings(music_dir=tmp_path / "music"), + library_status_provider=lambda settings: LibraryStatus( + settings.music_dir, 0, 0, 0, 0, 0, 0, 0, () + ), + queue_snapshot_provider=lambda: empty, + downloads_queue_provider=provider, + download_plan_provider=plan, + download_execution_provider=execute, + download_all_plan_provider=batch_plan or (lambda settings: DownloadAllPlan((), 0, 0, 0, 0)), + download_all_execution_provider=batch_execute or (lambda settings, plan, **kwargs: DownloadAllResult(DownloadBatchStatus.COMPLETED, "Download all finished")), + queue_history_provider=history or (lambda: None), + catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), + ) + + +def _text(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +def _execution_plan(tmp_path: Path, reference: str, title: str = "Queued Song"): + return DownloadExecutionPlan( + reference=reference, + job_id=reference.rpartition(":")[0], + item_index=int(reference.rpartition(":")[2]), + song_id="94902", + title=title, + artist="Juice WRLD", + destination=tmp_path / f"{title}.mp3", + current_status=DownloadQueueItemStatus.QUEUED, + action=DownloadExecutionAction.START, + ) + + +async def _open_downloads(app: JuiceLyricsApp, pilot): + await pilot.press("4") + await pilot.pause() + worker = app.screen._refresh_worker + if worker is not None: + await worker.wait() + await pilot.pause() + return app.screen + + +def test_downloads_replaces_placeholder_and_renders_empty_and_error_states(tmp_path): + async def empty_scenario(): + app = _app(tmp_path, _snapshot) + async with app.run_test() as pilot: + screen = await _open_downloads(app, pilot) + assert screen.__class__.__name__ == "DownloadsScreen" + assert "Nothing waiting to download" in _text(app, "#download-queue") + assert "Waiting 0 · Downloading 0 · Adding lyrics 0 · Failed 0 · Complete 0" in _text( + app, "#downloads-summary" + ) + + async def error_scenario(): + app = _app( + tmp_path, + lambda: (_ for _ in ()).throw(RuntimeError("job store is malformed")), + ) + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + assert "Queue unavailable: job store is malformed" in _text(app, "#downloads-status") + assert app.screen.id == "screen-downloads" + + async def empty_job_scenario(): + empty_job = _job(1, "empty-job", ()) + app = _app(tmp_path, lambda: _snapshot(empty_job)) + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + assert "No active queue item selected" in _text(app, "#download-details") + assert "Complete 0" in _text(app, "#downloads-summary") + + asyncio.run(empty_scenario()) + asyncio.run(error_scenario()) + asyncio.run(empty_job_scenario()) + + +def test_slow_queue_loading_does_not_block_navigation_or_quit(tmp_path): + started = Event() + release = Event() + + def provider(): + started.set() + release.wait(timeout=5) + return _snapshot() + + async def navigation_scenario(): + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + await pilot.press("4") + await asyncio.to_thread(started.wait, 2) + assert "Loading queue" in _text(app, "#download-queue") + downloads = app.screen + worker = downloads._refresh_worker + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + release.set() + await worker.wait() + await pilot.pause() + assert downloads._refresh_worker is None + await pilot.press("4") + await pilot.pause() + assert app.screen.id == "screen-downloads" + assert downloads._refresh_worker is not None + await downloads._refresh_worker.wait() + + async def quit_scenario(): + quit_started = Event() + quit_release = Event() + + def quit_provider(): + quit_started.set() + quit_release.wait(timeout=5) + return _snapshot() + + app = _app(tmp_path, quit_provider) + async with app.run_test() as pilot: + await pilot.press("4") + await asyncio.to_thread(quit_started.wait, 2) + await pilot.press("q") + assert not app.is_running + quit_release.set() + + try: + asyncio.run(navigation_scenario()) + asyncio.run(quit_scenario()) + finally: + release.set() + + +def test_queue_totals_order_navigation_details_failures_and_retry_information(tmp_path): + queued = _job(1, "queued-id", (_item(tmp_path, "Queued Song", QueueStatus.PENDING),)) + active = _job(2, "active-id", (_item(tmp_path, "Active Song", QueueStatus.DOWNLOADING),)) + completed = _job(3, "complete-id", (_item(tmp_path, "Done Song", QueueStatus.COMPLETED),)) + failed = _job( + 4, + "failed-id", + ( + _item(tmp_path, "Finished Track", QueueStatus.COMPLETED), + _item( + tmp_path, + "Lyrics Track", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.LYRICS, + error="Audio downloaded\nlyrics verification failed", + postprocessing_retryable=True, + ), + _item( + tmp_path, + "Transport Track", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.TRANSPORT, + error="connection reset", + ), + _item( + tmp_path, + "Validation Track", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.VALIDATION, + error="size mismatch", + ), + _item( + tmp_path, + "LRC Track", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.LRC, + error="lyrics directory unavailable", + ), + _item( + tmp_path, + "State Track", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.STATE, + error="state file unavailable", + ), + ), + ) + + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(queued, active, completed, failed)) + async with app.run_test(size=(100, 30)) as pilot: + await _open_downloads(app, pilot) + assert "Waiting 1 · Downloading 1 · Adding lyrics 0 · Failed 5 · Complete 2" in _text( + app, "#downloads-summary" + ) + rendered = _text(app, "#download-queue") + assert rendered.index("Queued Song") < rendered.index("Active Song") < rendered.index("Lyrics Track") + assert "Done Song" not in rendered + assert "> Waiting" in rendered + assert "queued-id" not in rendered and "failed-id" not in rendered + + await pilot.press("down", "j") + await pilot.pause() + assert app.screen.selected_item.title == "Lyrics Track" + assert "Lyrics Track" in _text(app, "#download-details") + await pilot.press("up", "k") + assert app.screen.selected_item.title == "Queued Song" + + await pilot.press("end") + await pilot.pause() + details = _text(app, "#download-details") + assert app.screen.selected_item.title == "State Track" + assert "Job ID" not in details + assert "Library update failed" in details + assert "Internal ref" in details + + await pilot.press("home") + assert app.screen.selected_item.title == "Queued Song" + + asyncio.run(scenario()) + + +def test_many_jobs_and_tracks_scroll_with_details_mode_at_80x24(tmp_path): + jobs = tuple( + _job(index, f"job-{index}", (_item(tmp_path, f"Song {index}", QueueStatus.PENDING),)) + for index in range(1, 21) + ) + track_job = _job( + 20, + "job-20", + tuple(_item(tmp_path, f"Track {index}", QueueStatus.PENDING) for index in range(1, 21)), + ) + jobs = (*jobs[:-1], track_job) + + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(*jobs)) + async with app.run_test(size=(80, 24)) as pilot: + await _open_downloads(app, pilot) + job_scroll = app.query_one("#download-queue-scroll", VerticalScroll) + assert "-downloads-narrow" in app.screen.classes + assert job_scroll.size.height >= 5 + assert job_scroll.max_scroll_y > 0 + assert app.query_one("#downloads-position").region.height == 1 + + await pilot.press("end") + await pilot.pause() + assert app.screen.selected_item.title == "Track 20" + assert job_scroll.scroll_y > 0 + assert job_scroll.scroll_y <= 38 < job_scroll.scroll_y + job_scroll.size.height + + await pilot.press("enter") + await pilot.pause() + assert app.screen.has_class("-details-mode") + details_scroll = app.query_one("#download-details-scroll", VerticalScroll) + await pilot.press("pagedown") + await pilot.pause() + assert details_scroll.scroll_y >= 0 + await pilot.press("escape") + assert not app.screen.has_class("-details-mode") + + await pilot.press("pageup") + await pilot.pause() + assert app.screen.selected_index < 38 + + asyncio.run(scenario()) + + +def test_downloads_shortcuts_and_context_guidance_are_visible(tmp_path): + queued = _job(1, "queued", (_item(tmp_path, "Queued", QueueStatus.PENDING),)) + failed = _job(2, "failed", (_item(tmp_path, "Failed", QueueStatus.FAILED, failure_stage=QueueFailureStage.TRANSPORT),)) + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(queued, failed)) + async with app.run_test(size=(120, 40)) as pilot: + await _open_downloads(app, pilot) + bar = _text(app, "#downloads-position") + assert "A Queue" in bar and "d Download" in bar and "Enter Details" in bar + assert "x Remove" not in bar and "c Clear" not in bar and "H Clear" not in bar + assert "Ready to download" in _text(app, "#downloads-status") + await pilot.press("down"); await pilot.pause() + assert "t Retry" in _text(app, "#downloads-position") + assert "Download failed" in _text(app, "#downloads-status") + await pilot.press("question_mark") + help_text = _text(app, "#help-content") + assert "Download entire queue" in help_text and "Clear completed history" in help_text + await pilot.press("escape") + await pilot.press("home", "x"); await pilot.pause() + assert app.screen.id == "screen-downloads" + asyncio.run(scenario()) + + +def test_one_song_download_all_cancel_then_confirm_runs_once(tmp_path): + queued = _job(1, "one-song", (_item(tmp_path, "Only Song", QueueStatus.PENDING),)) + execution_plan = _execution_plan(tmp_path, "one-song:0", "Only Song") + batch = DownloadAllPlan((execution_plan,), 0, 0, 0, 0) + calls = [] + snapshots = [_snapshot(queued), _snapshot(_job(1, "done", (_item(tmp_path, "Only Song", QueueStatus.COMPLETED),)))] + + def provider(): + return snapshots[0] if len(snapshots) == 1 else snapshots.pop(0) + + def execute_batch(settings, plan, **kwargs): + calls.append(len(plan.eligible)) + return DownloadAllResult(DownloadBatchStatus.COMPLETED, "Download all finished · 1 completed · 0 failed · 0 skipped", 1) + + async def scenario(): + app = _app(tmp_path, provider, batch_plan=lambda settings: batch, batch_execute=execute_batch) + async with app.run_test() as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("shift+a"); await pilot.pause() + if downloads._batch_plan_worker is not None: + await downloads._batch_plan_worker.wait(); await pilot.pause() + assert app.screen.__class__.__name__ == "DownloadAllDialog", (_text(app, "#downloads-status"), downloads._batch_plan_worker) + assert "Download 1 song?" in _text(app, "#download-confirm-body") + assert "Lyrics will be added automatically." in _text(app, "#download-confirm-body") + assert app.focused is not None and app.focused.id == "download-confirm-cancel" + await pilot.press("enter"); await pilot.pause() + assert calls == [] + await pilot.press("shift+a"); await pilot.pause() + if downloads._batch_plan_worker is not None: + await downloads._batch_plan_worker.wait(); await pilot.pause() + await pilot.press("2"); await pilot.pause() + assert app.screen.__class__.__name__ == "DownloadAllDialog" + await pilot.press("tab"); await pilot.pause() + assert app.focused is not None and app.focused.id == "download-confirm-download" + await pilot.press("shift+tab"); await pilot.pause() + assert app.focused is not None and app.focused.id == "download-confirm-cancel" + await pilot.press("tab"); await pilot.pause() + await pilot.press("enter"); await pilot.pause(0.2) + assert calls == [1] + assert "1 completed" in _text(app, "#downloads-status") + + asyncio.run(scenario()) + + +def test_download_all_y_confirms_once_without_enter(tmp_path): + queued = _job(1, "one-song", (_item(tmp_path, "Only Song", QueueStatus.PENDING),)) + plan = DownloadAllPlan((_execution_plan(tmp_path, "one-song:0", "Only Song"),), 0, 0, 0, 0) + calls = [] + + def execute(settings, batch, **kwargs): + calls.append(batch) + return DownloadAllResult(DownloadBatchStatus.COMPLETED, "Downloaded 1 song", 1) + + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(queued), batch_plan=lambda settings: plan, batch_execute=execute) + async with app.run_test() as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("shift+a") + if downloads._batch_plan_worker is not None: + await downloads._batch_plan_worker.wait() + await pilot.pause() + assert app.screen.__class__.__name__ == "DownloadAllDialog" + await pilot.press("2") + assert app.screen.__class__.__name__ == "DownloadAllDialog" + await pilot.press("y", "enter") + await pilot.pause(0.2) + assert len(calls) == 1 + + asyncio.run(scenario()) + + +def test_clear_history_is_immediate_and_preserves_downloaded_files(tmp_path): + completed = _job(1, "history", (_item(tmp_path, "Finished", QueueStatus.COMPLETED),)) + snapshots = [_snapshot(completed), _snapshot()] + calls = [] + audio = tmp_path / "Finished.mp3" + lrc = tmp_path / "Finished.lrc" + audio.write_bytes(b"audio") + lrc.write_text("lyrics", encoding="utf-8") + + def provider(): + return snapshots[0] if len(snapshots) == 1 else snapshots.pop(0) + + def clear_history(): + calls.append("clear") + return QueueMutationResult(QueueMutationStatus.COMPLETED, "Cleared 1 completed history entry.", removed_count=1) + + async def scenario(): + app = _app(tmp_path, provider, history=clear_history) + async with app.run_test(size=(80, 24)) as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("shift+h"); await pilot.pause() + await pilot.pause(0.2) + assert app.screen.id == "screen-downloads" + assert calls == ["clear"] + assert audio.read_bytes() == b"audio" + assert lrc.read_text(encoding="utf-8") == "lyrics" + + asyncio.run(scenario()) + + +def test_clear_history_does_not_need_confirmation_keys(tmp_path): + completed = _job(1, "history", (_item(tmp_path, "Finished", QueueStatus.COMPLETED),)) + + async def confirm_scenario(): + calls = [] + def clear(): + calls.append("clear") + return QueueMutationResult(QueueMutationStatus.COMPLETED, "Cleared history", removed_count=1) + app = _app(tmp_path, lambda: _snapshot(completed), history=clear) + async with app.run_test(size=(80, 24)) as pilot: + await _open_downloads(app, pilot) + await pilot.press("shift+h"); await pilot.pause(0.2) + await pilot.press("y", "enter"); await pilot.pause() + assert calls == ["clear"] + + asyncio.run(confirm_scenario()) + + +def test_refresh_preserves_or_safely_replaces_selection(tmp_path): + first = _job(1, "first", (_item(tmp_path, "First", QueueStatus.PENDING),)) + keep = _job(2, "keep", (_item(tmp_path, "Keep", QueueStatus.PENDING),)) + replacement = _job(1, "replacement", (_item(tmp_path, "Replacement", QueueStatus.COMPLETED),)) + responses = [_snapshot(first, keep), _snapshot(keep, replacement), _snapshot(replacement)] + + def provider(): + return responses.pop(0) + + async def scenario(): + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + await pilot.press("down") + assert app.screen.selected_item.title == "Keep" + + await pilot.press("r") + await app.screen._refresh_worker.wait() + await pilot.pause() + assert app.screen.selected_item.title == "Keep" + + await pilot.press("r") + await app.screen._refresh_worker.wait() + await pilot.pause() + assert app.screen.selected_item is None + + asyncio.run(scenario()) + + +def test_newer_refresh_supersedes_stale_queue_result(tmp_path): + stale_started = Event() + release_stale = Event() + calls = 0 + initial = _job(1, "initial", (_item(tmp_path, "Initial", QueueStatus.PENDING),)) + stale = _job(1, "stale", (_item(tmp_path, "Stale", QueueStatus.FAILED),)) + fresh = _job(1, "fresh", (_item(tmp_path, "Fresh", QueueStatus.COMPLETED),)) + + def provider(): + nonlocal calls + calls += 1 + if calls == 1: + return _snapshot(initial) + if calls == 2: + stale_started.set() + release_stale.wait(timeout=5) + return _snapshot(stale) + return _snapshot(fresh) + + async def scenario(): + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + await pilot.press("r") + await asyncio.to_thread(stale_started.wait, 2) + await pilot.press("r") + current = app.screen._refresh_worker + await current.wait() + await pilot.pause() + assert app.screen.selected_item is None + release_stale.set() + await pilot.pause() + assert "Stale" not in _text(app, "#download-queue") + + try: + asyncio.run(scenario()) + finally: + release_stale.set() + + +def test_downloads_screen_is_read_only_and_uses_no_live_dependencies(tmp_path, monkeypatch): + import juice_lyrics.acquisition.downloader as downloader + import juice_lyrics.acquisition.jobs as jobs_module + import juice_lyrics.acquisition.runner as runner + + def mutation(*args, **kwargs): + raise AssertionError("queue mutation attempted") + + monkeypatch.setattr(downloader, "download_to", mutation) + monkeypatch.setattr(runner, "run_job", mutation) + monkeypatch.setattr(jobs_module.JobStore, "save", mutation) + monkeypatch.setattr(jobs_module.JobStore, "create", mutation) + monkeypatch.setattr(jobs_module.JobStore, "delete", mutation) + view = _job(1, "read-only", (_item(tmp_path, "Read Only", QueueStatus.PENDING),)) + + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(view)) + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + await pilot.press("down", "up", "enter", "pagedown", "escape", "r") + await app.screen._refresh_worker.wait() + await pilot.pause() + + asyncio.run(scenario()) + assert not list(tmp_path.rglob("*.json")) + assert not list(tmp_path.rglob("*.part")) + assert not list(tmp_path.rglob("*.lrc")) + assert not list(tmp_path.rglob("*.mp3")) + + +def test_download_selected_starts_without_confirmation(tmp_path): + queued = _job(1, "queue-record", (_item(tmp_path, "Queued Song", QueueStatus.PENDING),)) + plan_calls = [] + execution_calls = [] + + def planner(settings, reference): + plan_calls.append(reference) + plan = _execution_plan(tmp_path, reference) + return DownloadExecutionResult(DownloadExecutionStatus.READY, "Ready", plan=plan) + + def execute(*args, **kwargs): + execution_calls.append(args) + return DownloadExecutionResult(DownloadExecutionStatus.COMPLETED, "finished") + + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(queued), plan=planner, execute=execute) + async with app.run_test() as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("d") + await pilot.pause(0.2) + assert app.screen.id == "screen-downloads" + assert len(execution_calls) == 1 + assert len(plan_calls) == 1 + + asyncio.run(scenario()) + + +def test_retry_failed_song_runs_once_without_confirmation(tmp_path): + failed = _job(1, "retry-job", (_item(tmp_path, "Broken Song", QueueStatus.FAILED, failure_stage=QueueFailureStage.TRANSPORT, error="network"),)) + calls = [] + plan = DownloadRetryPlan("retry-job:0", "retry-job", 0, "id", "Broken Song", tmp_path / "Broken Song.mp3", "Download failed", DownloadRetryAction.DOWNLOAD_AGAIN) + def planner(settings, reference): + return DownloadRetryResult(DownloadRetryStatus.READY, "Ready", plan=plan) + def executor(settings, retry_plan, **kwargs): + calls.append(retry_plan.reference) + return DownloadRetryResult(DownloadRetryStatus.COMPLETED, "Broken Song finished", plan=retry_plan) + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(failed)) + app.download_retry_plan_provider = planner + app.download_retry_execution_provider = executor + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + await pilot.press("t"); await pilot.pause(0.2) + assert app.screen.id == "screen-downloads" + assert calls == ["retry-job:0"] + asyncio.run(scenario()) + + +def test_confirm_download_once_shows_progress_then_removes_completed_track(tmp_path): + started = Event() + continue_to_processing = Event() + processing = Event() + finish = Event() + completed = False + calls = [] + queued = _job(1, "queue-record", (_item(tmp_path, "Queued Song", QueueStatus.PENDING),)) + done = _job(1, "queue-record", (_item(tmp_path, "Queued Song", QueueStatus.COMPLETED),)) + + def provider(): + return _snapshot(done if completed else queued) + + def planner(settings, reference): + return DownloadExecutionResult( + DownloadExecutionStatus.READY, + "Ready", + plan=_execution_plan(tmp_path, reference), + ) + + def execute(settings, plan, *, progress): + nonlocal completed + calls.append(plan.reference) + progress(DownloadProgress(plan.reference, DownloadExecutionStatus.DOWNLOADING, 25, 100, "Downloading…")) + started.set() + continue_to_processing.wait(timeout=5) + progress(DownloadProgress(plan.reference, DownloadExecutionStatus.PROCESSING, 100, 100, "Processing lyrics and library metadata…")) + processing.set() + finish.wait(timeout=5) + completed = True + return DownloadExecutionResult( + DownloadExecutionStatus.COMPLETED, + "Queued Song finished downloading.", + plan=plan, + ) + + async def scenario(): + app = _app(tmp_path, provider, plan=planner, execute=execute) + async with app.run_test() as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("d") + await pilot.pause() + await pilot.press("y", "y") + await asyncio.to_thread(started.wait, 2) + await pilot.pause() + assert calls == ["queue-record:0"] + assert "Downloading" in _text(app, "#download-queue") + assert "25%" in _text(app, "#download-details") + + continue_to_processing.set() + await asyncio.to_thread(processing.wait, 2) + await pilot.pause() + assert "Adding lyrics" in _text(app, "#download-queue") + + execution_worker = downloads._execution_worker + assert execution_worker is not None + finish.set() + await execution_worker.wait() + await pilot.pause() + refresh = downloads._refresh_worker + if refresh is not None: + await refresh.wait() + await pilot.pause() + assert "Nothing waiting to download" in _text(app, "#download-queue") + assert "Complete 1" in _text(app, "#downloads-summary") + assert "finished downloading" in _text(app, "#downloads-status") + assert app.get_screen("dashboard")._invalidated + assert app.get_screen("library").snapshot is None + + try: + asyncio.run(scenario()) + finally: + continue_to_processing.set() + finish.set() + + +def test_download_failure_stays_visible_and_ineligible_states_do_not_start(tmp_path): + failed_now = False + plan_calls = [] + execution_calls = [] + queued = _job(1, "queued", (_item(tmp_path, "Queued Song", QueueStatus.PENDING),)) + failed = _job( + 1, + "queued", + (_item( + tmp_path, + "Queued Song", + QueueStatus.FAILED, + failure_stage=QueueFailureStage.VALIDATION, + error="checksum mismatch", + ),), + ) + + def provider(): + return _snapshot(failed if failed_now else queued) + + def planner(settings, reference): + plan_calls.append(reference) + return DownloadExecutionResult( + DownloadExecutionStatus.READY, + "Ready", + plan=_execution_plan(tmp_path, reference), + ) + + def execute(settings, plan, *, progress): + nonlocal failed_now + execution_calls.append(plan.reference) + failed_now = True + return DownloadExecutionResult( + DownloadExecutionStatus.FAILED, + "File validation failed", + plan=plan, + failure_stage="File validation failed", + error="checksum mismatch", + ) + + async def failure_scenario(): + app = _app(tmp_path, provider, plan=planner, execute=execute) + async with app.run_test() as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("d") + await pilot.pause() + await pilot.press("y") + await pilot.pause() + if downloads._refresh_worker is not None: + await downloads._refresh_worker.wait() + await pilot.pause() + assert "Queued Song" in _text(app, "#download-queue") + assert "File validation failed: checksum mismatch" in _text(app, "#downloads-status") + await pilot.press("d") + assert "Press t to try again" in _text(app, "#downloads-status") + assert len(plan_calls) == 1 + assert execution_calls == ["queued:0"] + + async def active_scenario(): + active = _job(1, "active", (_item(tmp_path, "Moving", QueueStatus.DOWNLOADING),)) + app = _app(tmp_path, lambda: _snapshot(active), plan=planner, execute=execute) + async with app.run_test() as pilot: + await _open_downloads(app, pilot) + await pilot.press("d") + assert "already downloading or processing" in _text(app, "#downloads-status") + + asyncio.run(failure_scenario()) + asyncio.run(active_scenario()) + + +def test_confirmed_download_survives_screen_switch_and_reloads_authoritative_queue(tmp_path): + started = Event() + release = Event() + completed = False + queued = _job(1, "queue-record", (_item(tmp_path, "Queued Song", QueueStatus.PENDING),)) + done = _job(1, "queue-record", (_item(tmp_path, "Queued Song", QueueStatus.COMPLETED),)) + + def provider(): + return _snapshot(done if completed else queued) + + def planner(settings, reference): + return DownloadExecutionResult( + DownloadExecutionStatus.READY, + "Ready", + plan=_execution_plan(tmp_path, reference), + ) + + def execute(settings, plan, *, progress): + nonlocal completed + started.set() + release.wait(timeout=5) + completed = True + return DownloadExecutionResult( + DownloadExecutionStatus.COMPLETED, + "Queued Song finished downloading.", + plan=plan, + ) + + async def scenario(): + app = _app(tmp_path, provider, plan=planner, execute=execute) + async with app.run_test() as pilot: + downloads = await _open_downloads(app, pilot) + await pilot.press("d") + await pilot.pause() + await pilot.press("y") + await asyncio.to_thread(started.wait, 2) + execution_worker = downloads._execution_worker + assert execution_worker is not None + await pilot.press("2") + assert app.screen.id == "screen-browse" + release.set() + await execution_worker.wait() + await pilot.pause() + assert app.screen.id == "screen-browse" + await pilot.press("4") + await pilot.pause() + refresh = downloads._refresh_worker + if refresh is not None: + await refresh.wait() + await pilot.pause() + assert "Complete 1" in _text(app, "#downloads-summary") + assert "Nothing waiting to download" in _text(app, "#download-queue") + + try: + asyncio.run(scenario()) + finally: + release.set() diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py new file mode 100644 index 0000000..83a848c --- /dev/null +++ b/tests/test_tui_library.py @@ -0,0 +1,1794 @@ +import asyncio +from dataclasses import replace +from datetime import datetime, timezone +from pathlib import Path +import sys +from threading import Event, get_ident +from types import SimpleNamespace + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from textual.containers import VerticalScroll +from textual.widgets import Input, Select + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services import ( + CatalogueFilterMetadata, + CataloguePage, + CatalogueSearchResult, + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryStatus, + LibraryTrack, + IdentityBackfillResult, + IdentityChange, + IdentityRebuildPlan, + IdentityRebuildProgress, + IdentityRebuildResult, + LyricAvailability, + ManualIdentityResult, + QueueSnapshot, + SongDetails, +) +from juice_lyrics.library.media import AudioMetadata +from juice_lyrics.services.metadata_audit import build_metadata_audit +from juice_lyrics.services.missing_library import CatalogueCoverage, MissingLibraryReport +from juice_lyrics.services.library_sync import ( + LibrarySyncResult, + LibrarySyncOptions, + LibrarySyncPlan, + MatchOutcome, + SyncLyricType, + TrackSyncPlan, + TrackSyncResult, + SyncEvent, + SyncEventKind, +) +from juice_lyrics.backup.manager import BackupRecord +from juice_lyrics.services.library_index_sync import LibraryIndexSyncResult +from juice_lyrics.services.settings_snapshot import ( + IntegrationSnapshot, + IntegrationStatus, + SettingsSnapshot, +) +from juice_lyrics.tui import JuiceLyricsApp + + +def test_sync_library_is_immediate_single_worker_and_navigation_stays_live(tmp_path): + root = tmp_path / "music" + track = _track(root, "Song.mp3", matched=False) + started = Event() + release = Event() + calls = [] + ui_thread = get_ident() + + def sync(settings, *, previous_snapshot=None): + calls.append((previous_snapshot, get_ident())) + started.set() + assert release.wait(timeout=5) + return LibraryIndexSyncResult(_snapshot(root, track), new=1, identified=1) + + async def scenario(): + app = _app( + tmp_path, lambda settings: _snapshot(root, track), + library_index_sync_provider=sync, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + assert "s Sync Library" in _text(app, "#library-position") + await pilot.press("s", "s") + assert await asyncio.to_thread(started.wait, 2) + assert len(calls) == 1 and calls[0][1] != ui_thread + assert app.screen.id == "screen-library" + await pilot.press("question_mark") + assert app.screen is not screen + await pilot.press("escape", "4", "3") + assert app.screen.id == "screen-library" + release.set() + await screen._index_sync_worker.wait() + await pilot.pause() + assert "1 newly matched" in _text(app, "#library-status") + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def _track( + root: Path, + name: str, + *, + matched: bool = True, + lyric: LibraryLyricStatus = LibraryLyricStatus.SYNCED, + lrc: LibraryLrcStatus = LibraryLrcStatus.PRESENT, + state: LibraryStateStatus = LibraryStateStatus.CURRENT, + warning: str | None = None, + media_format: str = "MP3", + synchronized_source: bool = False, + identity_locked: bool = False, + identity_source: str | None = None, + verification_error: str | None = None, + content_sha256: str | None = None, + catalogue_id=None, +) -> LibraryTrack: + path = root / name + lrc_path = path.with_suffix(".lrc") if lrc is not LibraryLrcStatus.NONE else None + return LibraryTrack( + reference=name, + path=path, + relative_path=Path(name), + filename=name, + title=path.stem, + duration_seconds=183.4, + match_status=LibraryMatchStatus.MATCHED if matched else LibraryMatchStatus.UNMATCHED, + matched_title=f"{path.stem} (catalogue)" if matched else None, + lyric_status=lyric, + lrc_status=lrc, + lrc_path=lrc_path, + state_status=state, + warning=warning, + media_format=media_format, + synchronized_source=synchronized_source, + identity_locked=identity_locked, + identity_source=identity_source, + verification_error=verification_error, + content_sha256=content_sha256, + catalogue_id=catalogue_id, + ) + + +def _snapshot(root: Path, *tracks: LibraryTrack, exists: bool = True, warnings=()) -> LibrarySnapshot: + return LibrarySnapshot(root, exists, tracks, tuple(warnings)) + + +def _plan(settings: Settings, tracks: tuple[TrackSyncPlan, ...]) -> LibrarySyncPlan: + options = LibrarySyncOptions.from_settings( + settings, + dry_run=True, + rmpc_enabled=True, + lyrics_dir=None, + state_file=Path(settings.music_dir).parent / "state.json", + ) + return LibrarySyncPlan(options, tracks, {"files": {}}) + + +def _app(tmp_path: Path, snapshot_provider, preview_provider=None, **providers) -> JuiceLyricsApp: + settings = Settings(music_dir=tmp_path / "music") + status = LibraryStatus(settings.music_dir, 0, 0, 0, 0, 0, 0, 0, ()) + return JuiceLyricsApp( + settings, + library_status_provider=lambda settings: status, + queue_snapshot_provider=lambda: QueueSnapshot((), 0, 0, 0, 0, 0), + catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), + library_snapshot_provider=snapshot_provider, + library_identity_provider=providers.pop( + "library_identity_provider", + lambda settings, tracks: IdentityBackfillResult( + len(tracks), 0, 0, len(tracks), 0 + ), + ), + library_preview_provider=preview_provider or (lambda settings, **kwargs: _plan(settings, ())), + **providers, + ) + + +def _text(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +async def _open_library(app: JuiceLyricsApp, pilot): + await pilot.press("3") + await pilot.pause() + worker = app.screen._snapshot_worker + if worker is not None: + await worker.wait() + await pilot.pause() + return app.screen + + +def test_manual_match_search_navigation_lock_and_unlock_are_state_only(tmp_path): + root = tmp_path / "music" + base = _track(root, "Unknown.flac", matched=False, media_format="FLAC") + selected: list[tuple[object, str]] = [] + searches: list[str] = [] + unlocked: list[str] = [] + current = {"locked": False, "song_id": None, "name": None} + + def snapshot(settings): + return _snapshot( + root, + replace( + base, + match_status=( + LibraryMatchStatus.MATCHED + if current["song_id"] is not None + else LibraryMatchStatus.UNMATCHED + ), + matched_title=current["name"], + identity_locked=bool(current["locked"]), + identity_source="manual" if current["locked"] else None, + ), + ) + + candidates = ( + CatalogueSearchResult( + 1, 10, "Unknown (v1)", "unreleased", "DRFL", "3:20", + ("Juice WRLD",), (), None, LyricAvailability.NONE, False, + ), + CatalogueSearchResult( + 2, 20, "Unknown", "released", "DRFL", "3:00", + ("Juice WRLD",), (), "Released/Album/Unknown.mp3", + LyricAvailability.SYNCED, True, + ), + ) + + def search(settings, query, **kwargs): + searches.append(query) + return CataloguePage(candidates, 1, 50, 2, None, None) + + def save(settings, track, *, song_id, api_name): + selected.append((song_id, api_name)) + current.update(locked=True, song_id=song_id, name=api_name) + return ManualIdentityResult(track.reference, song_id, api_name, True, True) + + def unlock(settings, track): + unlocked.append(track.reference) + current.update(locked=False, song_id=None, name=None) + return ManualIdentityResult(track.reference, None, None, False, True) + + async def scenario(): + app = _app( + tmp_path, + snapshot, + catalogue_search_provider=search, + manual_identity_provider=save, + manual_unlock_provider=unlock, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("c") + await pilot.pause() + dialog = app.screen + worker = dialog._search_worker + if worker is not None: + await worker.wait() + await pilot.pause() + assert "recording for this local file" in _text(app, "#manual-match-context") + assert "Unknown (v1)" in _text(app, "#manual-match-results") + assert "released" in _text(app, "#manual-match-results") + + await pilot.press("slash") + query = app.query_one("#manual-match-query", Input) + query.value = "Refined Unknown" + await pilot.press("enter") + await pilot.pause() + worker = dialog._search_worker + if worker is not None: + await worker.wait() + await pilot.pause() + assert searches[-1] == "Refined Unknown" + + await pilot.press("down", "enter") + await pilot.pause() + worker = screen._manual_identity_worker + if worker is not None: + await worker.wait() + await pilot.pause() + if screen._snapshot_worker is not None: + await screen._snapshot_worker.wait() + await pilot.pause() + assert selected == [(20, "Unknown")] + assert "Manual (locked)" in _text(app, "#library-details") + assert "saved and locked" in _text(app, "#library-status") + + await pilot.press("u") + await pilot.pause() + worker = screen._manual_identity_worker + if worker is not None: + await worker.wait() + await pilot.pause() + if screen._snapshot_worker is not None: + await screen._snapshot_worker.wait() + await pilot.pause() + assert unlocked == ["Unknown.flac"] + assert "Not identified" in _text(app, "#library-details") + assert "unlocked and cleared" in _text(app, "#library-status") + + await pilot.press("c") + await pilot.pause() + await pilot.press("escape") + await pilot.pause() + assert app.screen is screen + assert selected == [(20, "Unknown")] + + asyncio.run(scenario()) + + +def test_manual_match_empty_or_offline_search_leaves_identity_unchanged(tmp_path): + root = tmp_path / "music" + track = _track(root, "Unknown.m4a", matched=False, media_format="M4A") + saves: list[object] = [] + + async def run_case(search): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + catalogue_search_provider=search, + manual_identity_provider=lambda *args, **kwargs: saves.append(kwargs), + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("c") + await pilot.pause() + dialog = app.screen + worker = dialog._search_worker + if worker is not None: + await worker.wait() + await pilot.pause() + text = _text(app, "#manual-match-results") + assert "No usable catalogue candidates" in text or "unavailable" in text + await pilot.press("enter", "escape") + await pilot.pause() + assert app.screen is screen + + asyncio.run( + run_case(lambda *args, **kwargs: CataloguePage((), 1, 50, 0, None, None)) + ) + asyncio.run( + run_case( + lambda *args, **kwargs: (_ for _ in ()).throw(OSError("offline")) + ) + ) + assert saves == [] + + +def test_issues_opens_from_snapshot_without_rescan_or_api_and_reaches_manual_match(tmp_path): + root = tmp_path / "music" + unknown = _track(root, "Unknown.flac", matched=False, media_format="FLAC") + invalid = _track( + root, + "Invalid.m4a", + media_format="M4A", + lrc=LibraryLrcStatus.INVALID, + warning="Adjacent LRC has no timestamped lyric lines.", + ) + snapshot_calls = [] + searches = [] + audio = tmp_path / "sentinel-audio" + sidecar = tmp_path / "sentinel-lrc" + audio.write_bytes(b"audio unchanged") + sidecar.write_bytes(b"lrc unchanged") + + def snapshot(settings): + snapshot_calls.append("snapshot") + return _snapshot(root, unknown, invalid) + + def search(settings, query, **kwargs): + searches.append(query) + return CataloguePage((), 1, 50, 0, None, None) + + async def scenario(): + app = _app(tmp_path, snapshot, catalogue_search_provider=search) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + assert "s Sync Library · a Issues" in _text(app, "#library-position") + await pilot.press("a") + await pilot.pause() + assert app.screen.__class__.__name__ == "LibraryIssuesDialog" + assert snapshot_calls == ["snapshot"] + assert searches == [] + assert "2 follow-ups" in _text(app, "#library-issues-summary") + assert "Catalogue" in _text(app, "#library-issues-list") + assert "Catalogue match unknown" in _text(app, "#library-issues-detail") + + await pilot.press("down") + assert "Synchronized LRC is invalid" in _text(app, "#library-issues-detail") + await pilot.press("up", "c") + await pilot.pause() + assert app.screen.__class__.__name__ == "ManualMatchDialog" + dialog = app.screen + if dialog._search_worker is not None: + await dialog._search_worker.wait() + await pilot.pause() + assert searches == ["Unknown"] + await pilot.press("escape") + await pilot.pause() + assert app.screen is screen + + asyncio.run(scenario()) + assert audio.read_bytes() == b"audio unchanged" + assert sidecar.read_bytes() == b"lrc unchanged" + + +def test_issues_empty_state_and_sync_replaces_health_immediately(tmp_path): + root = tmp_path / "music" + unknown = _track(root, "Song.mp3", matched=False) + healthy = replace( + unknown, + match_status=LibraryMatchStatus.MATCHED, + matched_title="Song", + ) + broken = replace( + healthy, + lyric_status=LibraryLyricStatus.NONE, + lrc_status=LibraryLrcStatus.NONE, + lrc_path=None, + verification_error="no managed lyrics frame", + ) + sync_results = iter( + ( + LibraryIndexSyncResult(_snapshot(root, healthy), identified=1), + LibraryIndexSyncResult(_snapshot(root, broken)), + ) + ) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, unknown), + library_index_sync_provider=lambda settings, **kwargs: next(sync_results), + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + assert "1 follow-ups" in _text(app, "#library-summary") + await pilot.press("s") + if screen._index_sync_worker is not None: + await screen._index_sync_worker.wait() + await pilot.pause() + assert "0 follow-ups · 0 errors" in _text(app, "#library-summary") + await pilot.press("a") + assert "No library issues found" in _text(app, "#library-issues-detail") + await pilot.press("escape", "s") + if screen._index_sync_worker is not None: + await screen._index_sync_worker.wait() + await pilot.pause() + assert "1 follow-ups · 0 errors" in _text(app, "#library-summary") + await pilot.press("a") + assert "Optional lyrics" in _text(app, "#library-issues-detail") + + asyncio.run(scenario()) + + +def test_duplicates_open_from_snapshot_without_rescan_api_or_mutation(tmp_path): + root = tmp_path / "music" + first = _track(root, "Album/Song.mp3", content_sha256="same", catalogue_id=1) + second = _track(root, "Copy/Song.flac", media_format="FLAC", content_sha256="same", catalogue_id=1) + snapshot_calls = [] + api_calls = [] + audio = tmp_path / "sentinel-audio" + sidecar = tmp_path / "sentinel-lrc" + audio.write_bytes(b"audio unchanged") + sidecar.write_bytes(b"lrc unchanged") + + def snapshot(settings): + snapshot_calls.append("snapshot") + return _snapshot(root, first, second) + + async def scenario(): + app = _app( + tmp_path, + snapshot, + catalogue_search_provider=lambda *args, **kwargs: api_calls.append(args), + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + assert "d Duplicates" in _text(app, "#library-position") + await pilot.press("d") + await pilot.pause() + assert app.screen.__class__.__name__ == "LibraryDuplicatesDialog" + assert snapshot_calls == ["snapshot"] + assert api_calls == [] + assert "1 duplicate group" in _text(app, "#library-duplicates-summary") + detail = _text(app, "#library-duplicates-detail") + assert "Exact duplicate audio" in detail + assert "same SHA-256" in detail + assert "Album/Song.mp3" in detail and "Copy/Song.flac" in detail + await pilot.press("question_mark") + await pilot.pause() + assert app.screen.__class__.__name__ == "HelpScreen" + await pilot.press("escape", "escape") + assert app.screen is screen + + asyncio.run(scenario()) + assert audio.read_bytes() == b"audio unchanged" + assert sidecar.read_bytes() == b"lrc unchanged" + + +def test_missing_library_loads_in_worker_filters_and_adds_to_existing_queue(tmp_path): + root = tmp_path / "music" + owned = _track(root, "Owned.mp3", catalogue_id=1) + unknown = _track(root, "Unknown.flac", matched=False, media_format="FLAC") + missing = CatalogueSearchResult( + 1, 2, "Missing (Live)", "released", "GBGR", "3:10", + ("Juice WRLD",), (), "Compilation/Missing (Live).mp3", + LyricAvailability.SYNCED, True, + ) + loaded = Event() + release = Event() + calls = [] + + def report(settings, snapshot): + calls.append((snapshot, get_ident())) + loaded.set() + assert release.wait(timeout=5) + return MissingLibraryReport( + (missing,), frozenset({"1"}), 1, 2, 2, 1, + CatalogueCoverage.COMPLETE, + ) + + planned = SimpleNamespace(plan=object(), message="Ready", ok=True) + added = SimpleNamespace(plan=None, message="Added 1 song to the download queue.", ok=True) + queue_calls = [] + + def plan(settings, selections): + queue_calls.append(("plan", selections)) + return planned + + def add(plan_value): + queue_calls.append(("add", plan_value)) + return added + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, owned, unknown), + missing_library_provider=report, + queue_plan_provider=plan, + queue_add_provider=add, + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + assert "g Missing" in _text(app, "#library-position") + await pilot.press("g") + assert await asyncio.to_thread(loaded.wait, 2) + await pilot.pause() + assert app.screen.__class__.__name__ == "MissingLibraryDialog" + assert calls[0][1] != get_ident() + assert "Loading catalogue" in _text(app, "#missing-library-summary") + release.set() + await app.screen._load_worker.wait() + await pilot.pause() + summary = _text(app, "#missing-library-summary") + assert "1 confirmed missing" in summary + assert "1 local Unknown" in summary + assert "Complete catalogue coverage" in summary + assert "Missing (Live)" in _text(app, "#missing-library-list") + await pilot.press("/"); await pilot.pause() + await pilot.press("l", "i", "v", "e", "enter") + assert "Missing (Live)" in _text(app, "#missing-library-list") + await pilot.press("a") + await app.screen._queue_worker.wait() + await pilot.pause() + assert queue_calls == [("plan", (missing,)), ("add", planned.plan)] + assert "Added 1 song" in _text(app, "#missing-library-summary") + await pilot.press("question_mark") + assert app.screen.__class__.__name__ == "HelpScreen" + await pilot.press("escape"); await pilot.pause(); await pilot.press("escape", "escape") + assert app.screen is screen + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_missing_library_partial_and_offline_states_do_not_claim_completeness(tmp_path): + root = tmp_path / "music" + reports = iter(( + MissingLibraryReport((), frozenset(), 1, 3, 10, 1, CatalogueCoverage.PARTIAL, error="offline"), + MissingLibraryReport((), frozenset(), 1, 0, None, 0, CatalogueCoverage.UNAVAILABLE, error="offline"), + )) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, _track(root, "Unknown.m4a", matched=False, media_format="M4A")), + missing_library_provider=lambda settings, snapshot: next(reports), + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("g") + await app.screen._load_worker.wait(); await pilot.pause() + assert "Partial catalogue coverage" in _text(app, "#missing-library-summary") + assert "No missing recordings can be confirmed" in _text(app, "#missing-library-list") + await pilot.press("escape", "g") + await app.screen._load_worker.wait(); await pilot.pause() + assert "Catalogue unavailable" in _text(app, "#missing-library-summary") + await pilot.press("escape") + assert app.screen is screen + + asyncio.run(scenario()) + + +def test_duplicate_navigation_probable_evidence_and_empty_state(tmp_path): + root = tmp_path / "music" + exact = ( + _track(root, "A/Exact.mp3", content_sha256="exact"), + _track(root, "B/Exact.mp3", content_sha256="exact"), + ) + probable = ( + _track(root, "A/Probable.flac", media_format="FLAC", content_sha256="a", catalogue_id=42), + _track(root, "B/Probable.m4a", media_format="M4A", content_sha256="b", catalogue_id=42), + ) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, *exact, *probable)) + async with app.run_test() as pilot: + await _open_library(app, pilot) + await pilot.press("d") + assert "Exact duplicate audio" in _text(app, "#library-duplicates-detail") + await pilot.press("down") + detail = _text(app, "#library-duplicates-detail") + assert "Probable duplicate recording" in detail + assert "Same catalogue identity (42)" in detail + await pilot.press("escape") + + empty = _app(tmp_path, lambda settings: _snapshot(root, exact[0])) + async with empty.run_test() as pilot: + await _open_library(empty, pilot) + await pilot.press("d") + assert "No duplicate recordings found" in _text( + empty, "#library-duplicates-list" + ) + + asyncio.run(scenario()) + + +def test_metadata_preview_is_backgrounded_cached_and_read_only(tmp_path): + root = tmp_path / "music" + track = _track(root, "Album/Track.flac", media_format="FLAC", catalogue_id=42) + track = replace(track, artist=None, album=None, identity_locked=True) + media = tmp_path / "sentinel-audio" + sidecar = tmp_path / "sentinel-lrc" + state = tmp_path / "sentinel-state" + for path, data in ( + (media, b"audio"), + (sidecar, b"lrc"), + (state, b"state"), + ): + path.write_bytes(data) + calls = [] + ui_thread = get_ident() + details = SongDetails( + 1, 42, "Track", "released", "DRFL", "3:03", + ("Juice WRLD",), (), "Released/Album/Track.mp3", + LyricAvailability.SYNCED, None, None, False, + album="Album", track_number="2", + ) + + def audit_provider(settings, selected, **kwargs): + calls.append(get_ident()) + return build_metadata_audit( + selected, + AudioMetadata("Track", None, None, 183.4, None), + details, + ) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + metadata_audit_provider=audit_provider, + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + assert "e Metadata" in _text(app, "#library-position") + await pilot.press("e") + worker = screen._metadata_audit_worker + if worker is not None: + await worker.wait() + await pilot.pause() + assert app.screen.__class__.__name__ == "MetadataAuditDialog" + content = _text(app, "#metadata-audit-content") + assert "Preview unavailable" not in content + assert "Artist" in content and "Juice WRLD" in content + assert "Track number" in content and "Confident" in content + assert "Manual lock" in content + await pilot.press("escape") + assert app.screen is screen + await pilot.press("e") + await pilot.pause() + assert app.screen.__class__.__name__ == "MetadataAuditDialog" + assert len(calls) == 1 + + asyncio.run(scenario()) + assert calls and calls[0] != ui_thread + assert media.read_bytes() == b"audio" + assert sidecar.read_bytes() == b"lrc" + assert state.read_bytes() == b"state" + + +def test_metadata_issue_opens_preview_and_help_lists_action(tmp_path): + root = tmp_path / "music" + track = _track( + root, + "Missing Tags.m4a", + matched=False, + media_format="M4A", + warning="M4A metadata is missing title, artist; track cannot be matched safely.", + catalogue_id=7, + ) + details = SongDetails( + 1, 7, "Missing Tags", "released", "GBGR", "3:00", + ("Juice WRLD",), (), None, LyricAvailability.PLAIN, + None, None, False, album=None, track_number=None, + ) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + metadata_audit_provider=lambda settings, selected, **kwargs: build_metadata_audit( + selected, + AudioMetadata(None, None, None, 180.0), + details, + ), + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + await pilot.press("a") + assert "e Metadata repair" in _text(app, "#library-issues-help") + await pilot.press("e") + worker = screen._metadata_audit_worker + if worker is not None: + await worker.wait() + await pilot.pause() + assert app.screen.__class__.__name__ == "MetadataAuditDialog" + assert "Missing Tags" in _text(app, "#metadata-audit-content") + await pilot.press("escape", "question_mark") + await pilot.pause() + assert "Review and apply selected metadata repairs" in _text(app, "#help-content") + + asyncio.run(scenario()) + + +def test_metadata_apply_requires_explicit_fields_and_cancel_is_default(tmp_path): + root = tmp_path / "music" + track = replace( + _track(root, "Album/Track.flac", media_format="FLAC", catalogue_id=42), + artist=None, + album="Local album", + ) + details = SongDetails( + 1, 42, "Track", "released", "DRFL", "3:03", + ("Juice WRLD",), (), "Released/Album/Track.mp3", + LyricAvailability.PLAIN, None, None, False, + album="Catalogue album", track_number=None, + ) + audit = build_metadata_audit( + track, + AudioMetadata("Track", None, "Local album", 183.4, None), + details, + ) + planned = [] + executed = [] + + def plan_provider(settings, selected_audit, fields): + planned.append(fields) + selected = tuple( + proposal for proposal in selected_audit.proposals if proposal.field in fields + ) + return SimpleNamespace(reference=track.reference, selected=selected) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + metadata_audit_provider=lambda *args, **kwargs: audit, + metadata_repair_plan_provider=plan_provider, + metadata_repair_execution_provider=lambda *args, **kwargs: executed.append(args), + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + await pilot.press("e") + if screen._metadata_audit_worker is not None: + await screen._metadata_audit_worker.wait() + await pilot.pause() + content = _text(app, "#metadata-audit-content") + assert "Confident recommendations" in content + assert "Review carefully" in content + assert "[ ] Artist" in content and "[ ] Album" in content + assert "(missing) → Juice WRLD" in content + + await pilot.press("a") + assert app.screen.__class__.__name__ == "MetadataAuditDialog" + assert "Select at least one field" in _text(app, "#metadata-audit-help") + assert planned == [] + + await pilot.press("enter", "a") + await pilot.pause() + if screen._metadata_repair_plan_worker is not None: + await screen._metadata_repair_plan_worker.wait() + await pilot.pause() + assert planned == [("artist",)] + assert app.screen.__class__.__name__ == "MetadataRepairConfirmationDialog" + confirmation = _text(app, "#library-dialog-body") + assert "Artist: (missing) → Juice WRLD" in confirmation + assert "complete audio backup" in confirmation + + await pilot.press("enter") + await pilot.pause() + assert app.screen is screen + assert executed == [] + assert "cancelled" in _text(app, "#library-status").lower() + + asyncio.run(scenario()) + + +def test_confirmed_metadata_apply_runs_once_in_background_and_refreshes(tmp_path): + root = tmp_path / "music" + track = replace( + _track(root, "Album/Track.m4a", media_format="M4A", catalogue_id=42), + artist=None, + ) + details = SongDetails( + 1, 42, "Track", "released", "DRFL", "3:03", + ("Juice WRLD",), (), None, LyricAvailability.PLAIN, + None, None, False, album=None, track_number=None, + ) + audit = build_metadata_audit( + track, AudioMetadata("Track", None, None, 183.4, None), details + ) + started = Event() + release = Event() + calls = [] + snapshot_calls = [] + ui_thread = get_ident() + + def snapshot_provider(settings): + snapshot_calls.append(1) + return _snapshot(root, track) + + def plan_provider(settings, selected_audit, fields): + return SimpleNamespace( + reference=track.reference, + selected=tuple( + proposal for proposal in selected_audit.proposals if proposal.field in fields + ), + ) + + def execute_provider(plan, *, confirmed=False): + calls.append((confirmed, get_ident())) + started.set() + assert release.wait(timeout=5) + return SimpleNamespace( + fields=tuple(proposal.field for proposal in plan.selected), + backup_path=tmp_path / "backups/track.m4a", + ) + + async def scenario(): + app = _app( + tmp_path, + snapshot_provider, + metadata_audit_provider=lambda *args, **kwargs: audit, + metadata_repair_plan_provider=plan_provider, + metadata_repair_execution_provider=execute_provider, + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + await pilot.press("e") + if screen._metadata_audit_worker is not None: + await screen._metadata_audit_worker.wait() + await pilot.pause() + await pilot.press("space", "a") + await pilot.pause() + if screen._metadata_repair_plan_worker is not None: + await screen._metadata_repair_plan_worker.wait() + await pilot.pause() + await pilot.press("y", "enter") + assert await asyncio.to_thread(started.wait, 2) + assert len(calls) == 1 + assert calls[0][0] is True and calls[0][1] != ui_thread + assert "Applying metadata repair" in _text(app, "#library-status") + await pilot.press("question_mark") + assert app.screen is not screen + await pilot.press("escape") + release.set() + if screen._metadata_repair_worker is not None: + await screen._metadata_repair_worker.wait() + await pilot.pause() + if screen._snapshot_worker is not None: + await screen._snapshot_worker.wait() + await pilot.pause() + assert len(calls) == 1 + assert len(snapshot_calls) >= 2 + status = _text(app, "#library-status") + assert "Metadata repaired" in status + assert "Backup:" in status + + try: + asyncio.run(scenario()) + finally: + release.set() + + +@pytest.mark.parametrize( + ("failure", "expected"), + ( + (OSError("backup full"), "failed safely"), + (RuntimeError("Library state changed during metadata repair."), "failed safely"), + ( + RuntimeError("Metadata repair failed and automatic rollback failed: disk"), + "needs recovery", + ), + (KeyboardInterrupt(), "failed safely"), + ), +) +def test_metadata_apply_failures_are_reported_without_refresh(tmp_path, failure, expected): + root = tmp_path / "music" + track = replace( + _track(root, "Track.mp3", catalogue_id=42), artist=None + ) + details = SongDetails( + 1, 42, "Track", "released", "DRFL", "3:03", + ("Juice WRLD",), (), None, LyricAvailability.PLAIN, + None, None, False, album=None, track_number=None, + ) + audit = build_metadata_audit( + track, AudioMetadata("Track", None, None, 183.4, None), details + ) + snapshot_calls = [] + + def snapshot_provider(settings): + snapshot_calls.append(1) + return _snapshot(root, track) + + def plan_provider(settings, selected_audit, fields): + return SimpleNamespace( + reference=track.reference, + selected=tuple(selected_audit.proposals), + ) + + def execute_provider(*args, **kwargs): + raise failure + + async def scenario(): + app = _app( + tmp_path, + snapshot_provider, + metadata_audit_provider=lambda *args, **kwargs: audit, + metadata_repair_plan_provider=plan_provider, + metadata_repair_execution_provider=execute_provider, + ) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + await pilot.press("e") + if screen._metadata_audit_worker is not None: + await screen._metadata_audit_worker.wait() + await pilot.pause() + await pilot.press("space", "a") + await pilot.pause() + if screen._metadata_repair_plan_worker is not None: + await screen._metadata_repair_plan_worker.wait() + await pilot.pause() + await pilot.press("y") + await pilot.pause() + if screen._metadata_repair_worker is not None: + await screen._metadata_repair_worker.wait() + await pilot.pause() + assert expected in _text(app, "#library-status").lower() + assert len(snapshot_calls) == 1 + + asyncio.run(scenario()) + + +def test_library_replaces_placeholder_and_renders_summary_details_and_states(tmp_path): + root = tmp_path / "music" + synced = _track(root, "A Synced.mp3") + plain = _track( + root, + "B Plain.mp3", + lyric=LibraryLyricStatus.PLAIN, + lrc=LibraryLrcStatus.NONE, + state=LibraryStateStatus.CHANGED, + ) + unmatched = _track( + root, + "C Unknown.mp3", + matched=False, + lyric=LibraryLyricStatus.NONE, + lrc=LibraryLrcStatus.MISSING, + state=LibraryStateStatus.NEW, + warning="Recorded LRC is missing.", + ) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, synced, plain, unmatched)) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + assert screen.__class__.__name__ == "LibraryScreen" + summary = _text(app, "#library-summary") + assert "3 tracks" in summary and "Catalogue unknown 1" in summary + assert "2 follow-ups" in summary and "0 errors" in summary + assert "MP3 3" in summary and "FLAC 0" in summary and "M4A 0" in summary + rows = _text(app, "#library-tracks") + assert "~" in rows and "!" not in rows + assert rows.index("A Synced") < rows.index("B Plain") < rows.index("C Unknown") + assert "Synced lyrics" in rows and "Plain lyrics" in rows and "No lyrics" in rows + assert "LRC Present" in rows and "LRC Missing" in rows + + await pilot.press("down", "j") + assert screen.selected_track.reference == unmatched.reference + details = _text(app, "#library-details") + assert "Catalogue match Unknown" in details and "No lyrics" in details + assert "Library state New" in details and "Library issue New track" in details + assert "Recorded LRC is missing" in details + assert "Lyric maintenance preview" in details + assert "Press l for this song or m for the library" in details + await pilot.press("up", "k", "end", "home") + assert screen.selected_track.reference == synced.reference + + asyncio.run(scenario()) + + +def test_loading_empty_missing_and_provider_error_states(tmp_path): + started = Event() + release = Event() + + def slow(settings): + started.set() + release.wait(timeout=5) + return _snapshot(Path(settings.music_dir)) + + async def loading_scenario(): + app = _app(tmp_path, slow) + async with app.run_test() as pilot: + await pilot.press("3") + await asyncio.to_thread(started.wait, 2) + assert "Loading tracks" in _text(app, "#library-tracks") + await pilot.press("4") + assert app.screen.id == "screen-downloads" + release.set() + + async def quit_scenario(): + quit_started = Event() + quit_release = Event() + + def provider(settings): + quit_started.set() + quit_release.wait(timeout=5) + return _snapshot(Path(settings.music_dir)) + + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + await pilot.press("3") + await asyncio.to_thread(quit_started.wait, 2) + # Search input keeps normal typing keys; leave it before quitting. + await pilot.press("escape", "q") + assert not app.is_running + quit_release.set() + + async def states_scenario(): + root = tmp_path / "music" + responses = [ + _snapshot(root), + _snapshot(root, exists=False, warnings=(f"Music directory does not exist: {root}",)), + ] + app = _app(tmp_path, lambda settings: responses.pop(0)) + async with app.run_test() as pilot: + await _open_library(app, pilot) + assert "No supported audio tracks found" in _text(app, "#library-tracks") + await pilot.press("r") + await app.screen._snapshot_worker.wait() + await pilot.pause() + assert "does not exist" in _text(app, "#library-status") + + broken = _app(tmp_path, lambda settings: (_ for _ in ()).throw(OSError("permission denied"))) + async with broken.run_test() as pilot: + await _open_library(broken, pilot) + assert "Library unavailable: permission denied" in _text(broken, "#library-status") + assert broken.screen.id == "screen-library" + + try: + asyncio.run(loading_scenario()) + asyncio.run(quit_scenario()) + asyncio.run(states_scenario()) + finally: + release.set() + + +def test_local_search_and_all_status_filters_do_not_rescan(tmp_path): + root = tmp_path / "music" + tracks = ( + _track(root, "Alpha Synced.mp3"), + _track(root, "Beta Plain.mp3", lyric=LibraryLyricStatus.PLAIN, lrc=LibraryLrcStatus.NONE), + _track(root, "Gamma None.mp3", matched=False, lyric=LibraryLyricStatus.NONE, lrc=LibraryLrcStatus.NONE), + ) + calls = 0 + + def provider(settings): + nonlocal calls + calls += 1 + return _snapshot(root, *tracks) + + async def scenario(): + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("/") + assert app.focused is app.query_one("#library-query", Input) + app.query_one("#library-query", Input).value = "beta" + await pilot.press("enter") + assert screen.filtered_tracks == (tracks[1],) + app.query_one("#library-query", Input).value = "" + + expected = { + "matched": 2, + "unmatched": 1, + "synced": 1, + "plain": 1, + "no_lyrics": 1, + "attention": 1, + "all": 3, + } + for value, count in expected.items(): + app.query_one("#library-filter", Select).value = value + await pilot.pause() + assert len(screen.filtered_tracks) == count + assert calls == 1 + + asyncio.run(scenario()) + + +def test_many_tracks_scroll_and_narrow_details_mode(tmp_path): + root = tmp_path / "music" + tracks = tuple(_track(root, f"Track {index:02}.mp3") for index in range(1, 31)) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, *tracks)) + async with app.run_test(size=(80, 24)) as pilot: + screen = await _open_library(app, pilot) + scroll = app.query_one("#library-tracks-scroll", VerticalScroll) + assert screen.has_class("-library-narrow") + assert scroll.size.height >= 5 + assert len(screen.filtered_tracks) == 30 and scroll.max_scroll_y > 0 + await pilot.press("end") + await pilot.pause() + assert screen.selected_track.reference == "Track 30.mp3" + assert scroll.scroll_y > 0 + assert "Track 30 of 30" in _text(app, "#library-position") + await pilot.press("home", "pagedown") + assert 0 < screen.selected_index < 29 + await pilot.press("pageup") + assert screen.selected_index == 0 + await pilot.press("enter") + assert screen.has_class("-details-mode") + await pilot.press("escape") + assert not screen.has_class("-details-mode") + + asyncio.run(scenario()) + + +def test_refresh_selection_stale_result_and_preview_invalidation(tmp_path): + root = tmp_path / "music" + first = _track(root, "First.mp3") + keep = _track(root, "Keep.mp3") + replacement = _track(root, "Replacement.mp3") + stale_started = Event() + release_stale = Event() + calls = 0 + + def provider(settings): + nonlocal calls + calls += 1 + if calls == 1: + return _snapshot(root, first, keep) + if calls == 2: + stale_started.set() + release_stale.wait(timeout=5) + return _snapshot(root, first) + if calls == 3: + return _snapshot(root, keep, replacement) + return _snapshot(root, replacement) + + async def scenario(): + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("down") + assert screen.selected_track.reference == keep.reference + screen.preview = _plan(app.settings, ()) + app.query_one("#library-preview").update("old preview") + + await pilot.press("r") + await asyncio.to_thread(stale_started.wait, 2) + await pilot.press("r") + current = screen._snapshot_worker + await current.wait() + await pilot.pause() + assert screen.selected_track.reference == keep.reference + assert "Sync Library" in _text(app, "#library-preview") + release_stale.set() + await pilot.pause() + assert "First.mp3" not in _text(app, "#library-tracks") + + await pilot.press("r") + await screen._snapshot_worker.wait() + await pilot.pause() + assert screen.selected_track.reference == replacement.reference + + try: + asyncio.run(scenario()) + finally: + release_stale.set() + + +def test_refresh_backfills_unknown_identity_off_event_loop_and_updates_display(tmp_path): + root = tmp_path / "music" + unknown = _track(root, "Bandit.flac", matched=False, lyric=LibraryLyricStatus.PLAIN, media_format="FLAC") + matched = _track(root, "Bandit.flac", matched=True, lyric=LibraryLyricStatus.PLAIN, media_format="FLAC") + started = Event() + release = Event() + snapshot_calls = 0 + + def snapshot(settings): + nonlocal snapshot_calls + snapshot_calls += 1 + return _snapshot(root, matched if snapshot_calls >= 3 else unknown) + + def identify(settings, tracks): + assert tracks == (unknown,) + started.set() + release.wait(timeout=5) + return IdentityBackfillResult(1, 0, 1, 0, 0) + + async def scenario(): + app = _app( + tmp_path, + snapshot, + library_identity_provider=identify, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("r") + await screen._snapshot_worker.wait(); await pilot.pause() + await asyncio.to_thread(started.wait, 2) + assert "Identifying 1 catalogue entry" in _text(app, "#library-status") + await pilot.press("4") + assert app.screen.id == "screen-downloads" + release.set() + await screen._identity_worker.wait(); await pilot.pause() + await pilot.press("3"); await pilot.pause() + if screen._snapshot_worker is not None: + await screen._snapshot_worker.wait(); await pilot.pause() + assert screen.selected_track.match_status is LibraryMatchStatus.MATCHED + assert "Catalogue identification complete · 1 song identified" in _text(app, "#library-status") + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_refresh_catalogue_failure_keeps_healthy_local_coverage_visible(tmp_path): + root = tmp_path / "music" + track = _track( + root, + "Bandit.flac", + matched=False, + lyric=LibraryLyricStatus.PLAIN, + media_format="FLAC", + ) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + library_identity_provider=lambda settings, tracks: IdentityBackfillResult( + 1, 0, 0, 0, 1, ("offline",) + ), + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("r") + await screen._snapshot_worker.wait(); await pilot.pause() + identity_worker = screen._identity_worker + if identity_worker is not None: + await identity_worker.wait() + await pilot.pause() + assert "Catalogue identification unavailable" in _text(app, "#library-status") + assert "Fully covered 1" in _text(app, "#library-summary") + assert "1 follow-ups" in _text(app, "#library-summary") + assert "Catalogue match Unknown" in _text(app, "#library-details") + + asyncio.run(scenario()) + + +def test_sync_preview_is_explicit_nonblocking_structured_and_handles_errors(tmp_path): + root = tmp_path / "music" + tracks = ( + _track(root, "Current.mp3"), + _track(root, "Synced.mp3", state=LibraryStateStatus.NEW), + _track(root, "Plain.mp3", lyric=LibraryLyricStatus.NONE, lrc=LibraryLrcStatus.NONE), + _track(root, "Unknown.mp3", matched=False, lyric=LibraryLyricStatus.NONE, lrc=LibraryLrcStatus.NONE), + ) + started = Event() + release = Event() + calls = 0 + + def preview(settings): + nonlocal calls + calls += 1 + started.set() + release.wait(timeout=5) + return _plan(settings, ( + TrackSyncPlan(tracks[0].path, MatchOutcome.UNCHANGED, SyncLyricType.NONE), + TrackSyncPlan(tracks[1].path, MatchOutcome.MATCHED, SyncLyricType.SYNCED, {"name": "Synced API"}), + TrackSyncPlan(tracks[2].path, MatchOutcome.MATCHED, SyncLyricType.PLAIN, {"name": "Plain API"}), + TrackSyncPlan(tracks[3].path, MatchOutcome.UNRESOLVED, SyncLyricType.NONE), + )) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, *tracks), preview) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + assert calls == 0 + screen.generate_preview() + await asyncio.to_thread(started.wait, 2) + assert "Checking library needs" in _text(app, "#library-preview") + await pilot.press("4") + assert app.screen.id == "screen-downloads" + await pilot.press("3") + release.set() + await screen._preview_worker.wait() + await pilot.pause() + preview_text = _text(app, "#library-preview") + assert "Preview only — no files changed" in preview_text + assert "Current 1" in preview_text and "Update 2" in preview_text + assert "Synced 1" in preview_text and "Plain 1" in preview_text and "LRC 1" in preview_text + assert "LRC beside each song" in preview_text + await pilot.press("down") + assert "Would update lyrics · Synced lyrics · Synced API" in _text(app, "#library-details") + + broken = _app( + tmp_path, + lambda settings: _snapshot(root, *tracks), + lambda settings: (_ for _ in ()).throw(RuntimeError("API unavailable")), + ) + async with broken.run_test() as pilot: + await _open_library(broken, pilot) + broken.screen.generate_preview() + await broken.screen._preview_worker.wait() + await pilot.pause() + assert "Preview failed: API unavailable" in _text(broken, "#library-preview") + assert broken.screen.id == "screen-library" + + try: + asyncio.run(scenario()) + finally: + release.set() + + +def test_newer_preview_supersedes_stale_and_empty_preview_is_clear(tmp_path): + root = tmp_path / "music" + track = _track(root, "Track.mp3") + stale_started = Event() + release_stale = Event() + calls = 0 + + def provider(settings): + nonlocal calls + calls += 1 + if calls == 1: + stale_started.set() + release_stale.wait(timeout=5) + return _plan(settings, (TrackSyncPlan(track.path, MatchOutcome.FAILED, SyncLyricType.NONE, error="stale"),)) + return _plan(settings, ()) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, track), provider) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + screen.generate_preview() + await asyncio.to_thread(stale_started.wait, 2) + screen.generate_preview() + current = screen._preview_worker + await current.wait() + await pilot.pause() + text = _text(app, "#library-preview") + assert "Current 0 · Update 0" in text + assert "Preview only — no files changed" in text + release_stale.set() + await pilot.pause() + assert "stale" not in _text(app, "#library-preview") + + try: + asyncio.run(scenario()) + finally: + release_stale.set() + + +def test_library_screen_never_calls_mutating_systems(tmp_path, monkeypatch): + import juice_lyrics.backup.manager as backup + import juice_lyrics.lyrics.engine as lyrics + import juice_lyrics.rmpc.integration as rmpc + import juice_lyrics.services.library_sync as sync_service + import juice_lyrics.state as state + + def mutation(*args, **kwargs): + raise AssertionError("mutation attempted") + + monkeypatch.setattr(sync_service, "execute_library_sync", mutation) + monkeypatch.setattr(lyrics, "embed_lyrics", mutation) + monkeypatch.setattr(backup, "backup_file", mutation) + monkeypatch.setattr(state, "save_state", mutation) + monkeypatch.setattr(rmpc, "notify_rmpc_index", mutation) + root = tmp_path / "music" + track = _track(root, "Read Only.mp3") + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + lambda settings: _plan(settings, (TrackSyncPlan(track.path, MatchOutcome.UNCHANGED, SyncLyricType.NONE),)), + ) + async with app.run_test() as pilot: + await _open_library(app, pilot) + await pilot.press("/", "enter", "down", "up") + app.screen.generate_preview() + await app.screen._preview_worker.wait() + await pilot.pause() + await pilot.press("r") + await app.screen._snapshot_worker.wait() + + asyncio.run(scenario()) + assert not list(tmp_path.rglob("*.mp3")) + assert not list(tmp_path.rglob("*.lrc")) + assert not list(tmp_path.rglob("*.json")) + + +def test_library_summary_is_format_aware_and_flac_m4a_can_be_fully_covered(tmp_path): + root = tmp_path / "music" + tracks = ( + _track(root, "One.mp3", synchronized_source=True), + _track(root, "Two.flac", lyric=LibraryLyricStatus.PLAIN, media_format="FLAC", synchronized_source=True), + _track(root, "Three.m4a", lyric=LibraryLyricStatus.PLAIN, media_format="M4A", synchronized_source=True), + ) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, *tracks)) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + summary = _text(app, "#library-summary") + assert "Fully covered 3" in summary + assert "0 follow-ups" in summary and "0 errors" in summary + assert "MP3 1" in summary and "FLAC 1" in summary and "M4A 1" in summary + await pilot.press("down") + assert "Coverage Fully covered" in _text(app, "#library-details") + assert screen.selected_track.media_format == "FLAC" + + asyncio.run(scenario()) + + +def test_healthy_unmatched_flac_is_covered_without_lyric_attention(tmp_path): + root = tmp_path / "music" + track = _track( + root, + "Bandit (with YoungBoy Never Broke Again).flac", + matched=False, + lyric=LibraryLyricStatus.PLAIN, + media_format="FLAC", + state=LibraryStateStatus.CURRENT, + ) + preview_calls = [] + + def preview(settings, **kwargs): + preview_calls.append(kwargs) + return _plan(settings, (TrackSyncPlan(track.path, MatchOutcome.UNCHANGED, SyncLyricType.NONE),)) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, track), preview) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_library(app, pilot) + summary = _text(app, "#library-summary") + assert "Fully covered 1" in summary + assert "1 follow-ups" in summary + assert "Catalogue unknown 1" in summary + details = _text(app, "#library-details") + assert "Catalogue match Unknown" in details + assert "External LRC Present" in details + assert "Coverage Fully covered" in details + assert "Library issue Catalogue match unknown" in details + assert "Automatic refresh requires a catalogue match" in details + + await pilot.press("m") + await screen._preview_worker.wait(); await pilot.pause() + assert preview_calls == [{"protected_paths": (track.path,)}] + assert "up to date" in _text(app, "#library-status") + + asyncio.run(scenario()) + + +def test_maintenance_preview_is_cancel_first_then_uses_shared_executor_with_progress(tmp_path): + root = tmp_path / "music" + track = _track(root, "Bandit.mp3", lyric=LibraryLyricStatus.NONE, lrc=LibraryLrcStatus.NONE) + plan = _plan( + Settings(music_dir=root), + (TrackSyncPlan(track.path, MatchOutcome.MATCHED, SyncLyricType.SYNCED, {"name": "Bandit"}),), + ) + executions = [] + + def execute(received, *, progress): + executions.append(received) + progress(SyncEvent(SyncEventKind.TRACK_COMPLETED, path=track.path)) + return LibrarySyncResult( + received, + (TrackSyncResult(track.path, MatchOutcome.MATCHED, SyncLyricType.SYNCED, updated=True),), + 1, 0, 0, 1, 1, tmp_path / "backup", + ) + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + lambda settings, **kwargs: plan, + library_execution_provider=execute, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("m") + await screen._preview_worker.wait(); await pilot.pause() + assert app.screen.__class__.__name__ == "MaintenanceDialog" + assert "No changes have been made" in _text(app, "#library-dialog-body") + await pilot.press("enter") + assert not executions + assert "cancelled" in _text(app, "#library-status") + + await pilot.press("m") + await screen._preview_worker.wait(); await pilot.pause() + await pilot.press("y") + await pilot.pause() + assert executions == [plan] + if screen._snapshot_worker is not None: + await screen._snapshot_worker.wait(); await pilot.pause() + assert "Library updated · 1 song updated" in _text(app, "#library-status") + + asyncio.run(scenario()) + + +def test_selected_lyric_refresh_scopes_preview_and_cancel_changes_nothing(tmp_path): + root = tmp_path / "music" + track = _track(root, "Selected.flac", lyric=LibraryLyricStatus.PLAIN, media_format="FLAC") + calls = [] + + def preview(settings, **kwargs): + calls.append(kwargs) + return _plan(settings, (TrackSyncPlan(track.path, MatchOutcome.MATCHED, SyncLyricType.PLAIN),)) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(root, track), preview) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("l") + await screen._preview_worker.wait(); await pilot.pause() + assert calls == [{"refresh": True, "selected_paths": (track.path,)}] + assert app.screen.__class__.__name__ == "MaintenanceDialog" + await pilot.press("escape") + assert "cancelled" in _text(app, "#library-status") + + asyncio.run(scenario()) + + +def test_verify_is_read_only_and_populates_attention_filter(tmp_path): + root = tmp_path / "music" + healthy = _track(root, "Healthy.mp3", synchronized_source=True) + problem = _track(root, "Problem.m4a", matched=False, lyric=LibraryLyricStatus.NONE, lrc=LibraryLrcStatus.NONE, media_format="M4A") + calls = 0 + + def snapshot(settings): + nonlocal calls + calls += 1 + return _snapshot(root, healthy, problem) + + async def scenario(): + app = _app(tmp_path, snapshot) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("v") + await screen._snapshot_worker.wait(); await pilot.pause() + assert calls == 2 + assert "Verification complete" in _text(app, "#library-status") + assert screen.filtered_tracks == (problem,) + assert not list(tmp_path.rglob("*.lrc")) + + asyncio.run(scenario()) + + +def test_backup_browser_orders_valid_records_and_restore_is_cancel_first(tmp_path): + root = tmp_path / "music" + old = tmp_path / "backups" / "old"; new = tmp_path / "backups" / "new" + old.mkdir(parents=True); new.mkdir(parents=True) + (old / "old.mp3").write_bytes(b"old"); (new / "new.flac").write_bytes(b"new") + records = ( + BackupRecord(old, datetime(2026, 1, 1, tzinfo=timezone.utc)), + BackupRecord(new, datetime(2026, 2, 1, tzinfo=timezone.utc)), + ) + restores = [] + + def restore(backup, music): + restores.append((backup, music)); return 1 + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root), + backup_provider=lambda: records, + restore_provider=restore, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("b"); await pilot.pause(0.1) + body = _text(app, "#library-dialog-body") + assert body.index("2026-02-01") < body.index("2026-01-01") + await pilot.press("r"); await pilot.pause() + assert app.screen.__class__.__name__ == "RestoreDialog" + await pilot.press("enter"); await pilot.pause(0.2) + assert not restores + assert screen._backup_worker is None + await pilot.press("b"); await pilot.pause(0.1) + assert app.screen.__class__.__name__ == "BackupBrowser" + await pilot.press("r"); await pilot.pause() + assert app.screen.__class__.__name__ == "RestoreDialog" + await pilot.press("y") + await pilot.pause(0.1) + assert app.screen.__class__.__name__ == "LibraryScreen" + assert restores == [(new, root)] + + asyncio.run(scenario()) + + +def test_rmpc_check_is_read_only_and_setup_requires_explicit_confirmation(tmp_path): + root = tmp_path / "music" + config = tmp_path / "rmpc.ron" + integration = IntegrationSnapshot( + IntegrationStatus.DETECTED_NOT_CONFIGURED, + Path("/usr/bin/rmpc"), + config, + True, + False, + "rmpc is detected, but sidecar lyrics are not configured.", + ) + settings_snapshot = SettingsSnapshot(config, False, (), (), integration, "1.4.0", ()) + setups = [] + + def setup(path, music): + setups.append((path, music)); return path.with_suffix(".bak") + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root), + settings_snapshot_provider=lambda settings: settings_snapshot, + rmpc_setup_provider=setup, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("p"); await pilot.pause(0.1) + assert "may update its configuration" in _text(app, "#library-dialog-body") + await pilot.press("enter"); await pilot.pause(0.2) + assert not setups + assert screen._rmpc_worker is None + await pilot.press("p"); await pilot.pause(0.1) + assert app.screen.__class__.__name__ == "RmpcDialog" + await pilot.press("y") + await pilot.pause(0.1) + assert app.screen.__class__.__name__ == "LibraryScreen" + assert setups == [(config, root)] + + asyncio.run(scenario()) + + +def test_restore_failure_is_reported_safely_without_refreshing_library(tmp_path): + root = tmp_path / "music" + backup = tmp_path / "backups" / "run" + backup.mkdir(parents=True) + (backup / "song.m4a").write_bytes(b"backup") + record = BackupRecord(backup, datetime(2026, 3, 1, tzinfo=timezone.utc)) + scans = 0 + + def snapshot(settings): + nonlocal scans + scans += 1 + return _snapshot(root) + + def fail_restore(*args): + raise OSError("destination is read-only") + + async def scenario(): + app = _app( + tmp_path, + snapshot, + backup_provider=lambda: (record,), + restore_provider=fail_restore, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("b"); await pilot.pause(0.1) + await pilot.press("r"); await pilot.pause() + await pilot.press("y"); await pilot.pause(0.1) + assert "Restore failed safely: destination is read-only" in _text(app, "#library-status") + assert scans == 1 + assert screen.snapshot is not None + + asyncio.run(scenario()) + + +def test_identity_rebuild_is_cancel_first_and_executes_off_event_loop(tmp_path): + root = tmp_path / "music" + track = _track(root, "10 Feet.flac", media_format="FLAC", lyric=LibraryLyricStatus.PLAIN) + settings = Settings(music_dir=root) + state_file = tmp_path / "state.json" + plan = IdentityRebuildPlan( + settings, + state_file, + "digest", + {"files": {track.reference: {"song_id": 96383, "api_name": "10 Feet"}}}, + (track,), + (), + 1, + ) + result = IdentityRebuildResult( + 1, + 1, + 0, + 1, + 0, + 0, + 0, + (IdentityChange(track.relative_path, 96383, "10 Feet", 94102, "10 Feet"),), + (), + tmp_path / "state.backup", + ) + main_thread = get_ident() + plan_threads = [] + execution_threads = [] + execution_release = Event() + + def prepare(settings): + plan_threads.append(get_ident()) + return plan + + def execute(value, *, progress): + execution_threads.append(get_ident()) + execution_release.wait(timeout=2) + progress(IdentityRebuildProgress(1, 1, track.path, "matched")) + return result + + async def scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot(root, track), + identity_rebuild_plan_provider=prepare, + identity_rebuild_execution_provider=execute, + ) + async with app.run_test() as pilot: + screen = await _open_library(app, pilot) + await pilot.press("i") + await pilot.pause(0.1) + assert app.screen.__class__.__name__ == "IdentityRebuildDialog" + assert "Audio and lyrics will not be modified" in _text(app, "#library-dialog-body") + await pilot.press("enter"); await pilot.pause() + assert app.screen is screen + assert not execution_threads + assert "cancelled" in _text(app, "#library-status") + + await pilot.press("i") + await pilot.pause(0.1) + await pilot.press("y"); await pilot.pause() + worker = screen._identity_rebuild_worker + assert worker is not None + execution_release.set() + await worker.wait(); await pilot.pause() + if screen._snapshot_worker is not None: + await screen._snapshot_worker.wait(); await pilot.pause() + assert "Catalogue rebuild complete" in _text(app, "#library-status") + + asyncio.run(scenario()) + assert plan_threads and all(thread != main_thread for thread in plan_threads) + assert execution_threads and all(thread != main_thread for thread in execution_threads) diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py new file mode 100644 index 0000000..96b3dd7 --- /dev/null +++ b/tests/test_tui_settings.py @@ -0,0 +1,308 @@ +import asyncio +from pathlib import Path +import sys +from threading import Event + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) + +from textual.containers import VerticalScroll + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services import ( + CatalogueFilterMetadata, + IntegrationSnapshot, + IntegrationStatus, + LibrarySnapshot, + LibraryStatus, + QueueSnapshot, + SettingValue, + SettingsPath, + SettingsSnapshot, + SettingsSource, +) +from juice_lyrics.tui import JuiceLyricsApp + + +def _snapshot( + tmp_path: Path, + *, + config_exists: bool = True, + integration: IntegrationStatus = IntegrationStatus.DETECTED_CONFIGURED, + suffix: str = "", +) -> SettingsSnapshot: + config = tmp_path / f"config{suffix}.toml" + music = tmp_path / f"music{suffix}" + values = ( + SettingValue("music_dir", "Music directory", music, Path("/default/music"), SettingsSource.CONFIG), + SettingValue("external_lyrics", "External lyrics", "Beside each song (.lrc)", "Beside each song (.lrc)", SettingsSource.DEFAULT), + SettingValue("lyrics_dir", "Legacy lyrics_dir (deprecated)", tmp_path / "lyrics", tmp_path / "lyrics", SettingsSource.CONFIG), + SettingValue("api_base", "API base URL", "https://api.example", "https://default.example", SettingsSource.DEFAULT), + SettingValue("timeout", "Request timeout", 20, 20, SettingsSource.DEFAULT), + SettingValue("delay", "Request delay", 0.15, 0.15, SettingsSource.CONFIG), + SettingValue("duration_tolerance", "Duration tolerance", 3.0, 3.0, SettingsSource.RUNTIME_OVERRIDE), + SettingValue("cache_ttl_hours", "Cache TTL", 24.0, 24.0, SettingsSource.DEFAULT), + ) + paths = ( + SettingsPath("music", "Music library", music, True), + SettingsPath("cache", "API cache", tmp_path / "cache", True), + SettingsPath("state", "Library state", tmp_path / "data" / "state.json", False), + SettingsPath("backups", "Backups", tmp_path / "data" / "backups", False), + SettingsPath("jobs", "Acquisition jobs", tmp_path / "data" / "jobs.json", True), + SettingsPath("config", "Application config", config, config_exists), + SettingsPath("rmpc_config", "rmpc config", tmp_path / "rmpc" / "config.ron", integration is IntegrationStatus.DETECTED_CONFIGURED), + ) + details = { + IntegrationStatus.DETECTED_CONFIGURED: "rmpc is detected and configured.", + IntegrationStatus.DETECTED_NOT_CONFIGURED: "rmpc is detected but not configured.", + IntegrationStatus.NOT_DETECTED: "rmpc was not found in PATH.", + IntegrationStatus.UNABLE_TO_INSPECT: "Unable to inspect rmpc.", + } + return SettingsSnapshot( + config_path=config, + config_exists=config_exists, + values=values, + paths=paths, + rmpc=IntegrationSnapshot( + integration, + Path("/usr/bin/rmpc") if integration in {IntegrationStatus.DETECTED_CONFIGURED, IntegrationStatus.DETECTED_NOT_CONFIGURED} else None, + tmp_path / "rmpc" / "config.ron", + integration is not IntegrationStatus.NOT_DETECTED, + integration is IntegrationStatus.DETECTED_CONFIGURED, + details[integration], + ), + application_version="1.4.0", + limitations=( + "Local library scanning supports MP3, FLAC, and M4A files.", + "FLAC and M4A timing use adjacent LRC; embedded lyrics are plain text.", + "Settings inspection remains read-only in the TUI.", + "Library sync execution remains CLI-only.", + "Configuration changes remain CLI-only.", + ), + ) + + +def _app(tmp_path: Path, provider) -> JuiceLyricsApp: + settings = Settings(music_dir=tmp_path / "music") + return JuiceLyricsApp( + settings, + library_status_provider=lambda settings: LibraryStatus(settings.music_dir, 0, 0, 0, 0, 0, 0, 0, ()), + queue_snapshot_provider=lambda: QueueSnapshot((), 0, 0, 0, 0, 0), + catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), + library_snapshot_provider=lambda settings: LibrarySnapshot(Path(settings.music_dir), False, ()), + settings_snapshot_provider=provider, + ) + + +def _text(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +async def _open_settings(app: JuiceLyricsApp, pilot): + await pilot.press("5") + await pilot.pause() + worker = app.screen._refresh_worker + if worker is not None: + await worker.wait() + await pilot.pause() + return app.screen + + +def test_settings_replaces_placeholder_and_renders_configuration_paths_and_limitations(tmp_path): + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(tmp_path)) + async with app.run_test(size=(120, 40)) as pilot: + screen = await _open_settings(app, pilot) + assert screen.__class__.__name__ == "SettingsScreen" + assert "Read-only settings — configuration changes use the 999 CLI" in _text(app, "#settings-warning") + paths = _text(app, "#settings-paths") + assert "Music folder" in paths and "Download location" in paths + assert "External lyrics" in paths + assert "Beside each song" in paths + assert str(tmp_path / "music") in _text(app, "#settings-detail") + configuration = _text(app, "#settings-configuration") + assert "config.toml" in configuration + assert "Music directory" not in configuration + assert "Legacy lyrics_dir (deprecated)" in configuration + assert "API base URL" in configuration and "[Default]" in configuration + assert "Duration tolerance" in configuration and "[Runtime override]" in configuration + assert "Detected and configured" in _text(app, "#settings-integrations") + capabilities = _text(app, "#settings-capabilities") + assert "MP3, FLAC, and M4A" in capabilities + assert "Library sync execution remains CLI-only" in capabilities + + await pilot.press("down", "j") + assert screen.selected_index == 2 + assert "External lyrics" in _text(app, "#settings-detail") + await pilot.press("end") + assert screen.selected_index == len(screen.rows) - 1 + await pilot.press("home") + assert screen.selected_index == 0 + + asyncio.run(scenario()) + + +def test_loading_is_responsive_and_quit_works(tmp_path): + started = Event() + release = Event() + + def slow(settings): + started.set() + release.wait(timeout=5) + return _snapshot(tmp_path) + + async def navigation_scenario(): + app = _app(tmp_path, slow) + async with app.run_test() as pilot: + await pilot.press("5") + await asyncio.to_thread(started.wait, 2) + assert "Loading" in _text(app, "#settings-configuration") + await pilot.press("2") + assert app.screen.id == "screen-browse" + release.set() + + async def quit_scenario(): + quit_started = Event() + quit_release = Event() + + def provider(settings): + quit_started.set() + quit_release.wait(timeout=5) + return _snapshot(tmp_path) + + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + await pilot.press("5") + await asyncio.to_thread(quit_started.wait, 2) + await pilot.press("q") + assert not app.is_running + quit_release.set() + + try: + asyncio.run(navigation_scenario()) + asyncio.run(quit_scenario()) + finally: + release.set() + + +def test_missing_config_integration_states_and_provider_errors(tmp_path): + async def missing_scenario(): + app = _app( + tmp_path, + lambda settings: _snapshot( + tmp_path, + config_exists=False, + integration=IntegrationStatus.NOT_DETECTED, + ), + ) + async with app.run_test() as pilot: + await _open_settings(app, pilot) + assert "No config file" in _text(app, "#settings-status") + await pilot.press("down", "down", "down", "down") + assert "Missing; defaults are in use" in _text(app, "#settings-detail") + assert "Not detected" in _text(app, "#settings-integrations") + + async def state_scenario(status, label): + app = _app(tmp_path, lambda settings: _snapshot(tmp_path, integration=status)) + async with app.run_test() as pilot: + await _open_settings(app, pilot) + assert label in _text(app, "#settings-integrations") + + async def error_scenario(message): + app = _app(tmp_path, lambda settings: (_ for _ in ()).throw(RuntimeError(message))) + async with app.run_test() as pilot: + await _open_settings(app, pilot) + assert f"Settings unavailable: {message}" in _text(app, "#settings-status") + assert app.screen.id == "screen-settings" + + asyncio.run(missing_scenario()) + asyncio.run(state_scenario(IntegrationStatus.DETECTED_NOT_CONFIGURED, "Detected but not configured")) + asyncio.run(state_scenario(IntegrationStatus.UNABLE_TO_INSPECT, "Unable to inspect")) + asyncio.run(error_scenario("Could not read config: invalid TOML")) + asyncio.run(error_scenario("permission denied")) + + +def test_refresh_supersedes_stale_snapshot_and_reloads_values(tmp_path): + stale_started = Event() + release_stale = Event() + calls = 0 + + def provider(settings): + nonlocal calls + calls += 1 + if calls == 1: + return _snapshot(tmp_path) + if calls == 2: + stale_started.set() + release_stale.wait(timeout=5) + return _snapshot(tmp_path, suffix="-stale") + return _snapshot(tmp_path, suffix="-fresh") + + async def scenario(): + app = _app(tmp_path, provider) + async with app.run_test() as pilot: + screen = await _open_settings(app, pilot) + await pilot.press("r") + await asyncio.to_thread(stale_started.wait, 2) + await pilot.press("r") + current = screen._refresh_worker + await current.wait() + await pilot.pause() + assert "config-fresh.toml" in _text(app, "#settings-configuration") + release_stale.set() + await pilot.pause() + assert "config-stale.toml" not in _text(app, "#settings-configuration") + + try: + asyncio.run(scenario()) + finally: + release_stale.set() + + +def test_long_settings_scroll_at_80x24_and_other_supported_sizes(tmp_path): + async def scenario(size): + app = _app(tmp_path, lambda settings: _snapshot(tmp_path)) + async with app.run_test(size=size) as pilot: + screen = await _open_settings(app, pilot) + scroll = app.query_one("#settings-scroll", VerticalScroll) + assert scroll.size.height >= 5 + assert scroll.max_scroll_y > 0 + await pilot.press("end") + await pilot.pause() + assert screen.selected_index == len(screen.rows) - 1 + if scroll.scroll_y == 0: + await pilot.press("pagedown") + await pilot.pause() + assert scroll.scroll_y > 0 + await pilot.press("pageup") + assert screen.selected_index < len(screen.rows) - 1 + assert "configuration changes use the 999 CLI" in _text(app, "#settings-warning") + + for size in ((80, 24), (100, 30), (120, 40)): + asyncio.run(scenario(size)) + + +def test_settings_screen_does_not_call_mutating_or_network_systems(tmp_path, monkeypatch): + import juice_lyrics.api.client as api + import juice_lyrics.cli as cli + import juice_lyrics.rmpc.integration as rmpc + + def mutation(*args, **kwargs): + raise AssertionError("mutation attempted") + + monkeypatch.setattr(cli, "write_default_config", mutation) + monkeypatch.setattr(cli, "command_setup", mutation) + monkeypatch.setattr(rmpc, "patch_rmpc_config", mutation) + monkeypatch.setattr(api, "api_get", mutation) + + async def scenario(): + app = _app(tmp_path, lambda settings: _snapshot(tmp_path)) + async with app.run_test() as pilot: + await _open_settings(app, pilot) + await pilot.press("down", "end", "home", "pagedown", "pageup", "r") + await app.screen._refresh_worker.wait() + await pilot.pause() + + asyncio.run(scenario()) + assert not list(tmp_path.rglob("*.toml")) + assert not list(tmp_path.rglob("*.json")) + assert not list(tmp_path.rglob("*.lrc"))