From a7307d70ee529827c52af4d4ace5a7448dba9033 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:15:07 +0100 Subject: [PATCH 01/62] Add v2 design and architecture decision notes --- docs/DECISIONS.md | 0 docs/V2_DESIGN.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/DECISIONS.md create mode 100644 docs/V2_DESIGN.md diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/V2_DESIGN.md b/docs/V2_DESIGN.md new file mode 100644 index 0000000..e69de29 From 1eaa7291f59f2244ecb5c96248c759d2fb034751 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:16:51 +0100 Subject: [PATCH 02/62] Document lyrics and architecture decisions --- docs/DECISIONS.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index e69de29..589f840 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -0,0 +1,138 @@ +# 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 are the primary source of truth + +The application should always preserve lyrics inside the MP3 file 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. + +--- + +# LRC Files and rmpc + +rmpc does not read embedded ID3 lyrics. + +rmpc currently relies on external `.lrc` lyric files. + +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 + +The backend can remain technical while the user interface becomes friendly. + +--- + +# 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. From 2a843c230e39e784d4d41bb336f911abf1e0f2e7 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:17:40 +0100 Subject: [PATCH 03/62] Add initial v2 design proposal --- docs/V2_DESIGN.md | 527 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 527 insertions(+) diff --git a/docs/V2_DESIGN.md b/docs/V2_DESIGN.md index e69de29..fa80471 100644 --- a/docs/V2_DESIGN.md +++ b/docs/V2_DESIGN.md @@ -0,0 +1,527 @@ +# juice-lyrics v2 Design Proposal + +## Vision + +juice-lyrics has grown beyond a simple lyrics tagging tool. + +The project is becoming a complete Juice WRLD music management application for Linux: + +- Discover music from the Juice WRLD API catalogue. +- Manage a local music library. +- Embed lyrics into MP3 files. +- Generate compatibility files for players like rmpc. +- Acquire and organize tracks. +- Provide a clean, beautiful terminal experience. + +Version 2 should transform the project from a powerful developer tool into a polished application. + +--- + +# New Identity + +## Problem + +The name "juice-lyrics" no longer represents the full application. + +The project now includes: + +- Music discovery. +- Library management. +- Downloads. +- Metadata. +- Player integration. +- Terminal UI. + +A new name should represent a complete Juice WRLD music hub rather than only lyrics. + +--- + +# Possible Names + +## 999 + +Concept: + +Juice WRLD's iconic "999" philosophy. + +Advantages: + +- Instantly recognizable to fans. +- Short command. +- Easy to remember. +- Fits a Linux CLI aesthetic. + +Possible command: + + +999 + + +or: + + +999 search "Rental" +999 sync +999 get "Rental" + + +--- + +## Abyss + +Concept: + +Inspired by Juice WRLD themes and darker aesthetics. + +Advantages: + +- Professional sounding. +- Fits terminal applications. +- Unique identity. + +Possible command: + + +abyss + + +--- + +## JuiceBox + +Concept: + +A friendly music library hub. + +Advantages: + +- Easy to understand. +- More approachable. + +Possible command: + + +jbox + + +--- + +# Recommended Direction + +999 is currently the strongest candidate. + +Final naming decision should happen after exploring branding, logo ideas, and command usability. + +--- + +# User Experience Goals + +## Current Problem + +The current application is powerful but technical. + +Example: + +Current workflow: + + +juice-lyrics acquire search "Rental" + +juice-lyrics acquire add "Rental" --index 1 + +juice-lyrics acquire run + + +This works, but it feels like developer tooling. + +--- + +## v2 Goal + +The user should think: + +"I want this song." + +Not: + +"I need to understand acquisition jobs." + +--- + +# New CLI Philosophy + +The CLI should support two levels: + +## Simple commands + +For normal users: + + +999 search "Rental" + +999 get "Rental" + +999 sync + +999 status + + +--- + +## Advanced commands + +For power users: + + +999 queue + +999 doctor + +999 restore + +999 config + + +The powerful backend should remain available without forcing complexity on beginners. + +--- + +# Proposed Command Structure + +## Open Application + + +999 + + +Launches the interactive TUI. + +--- + +## Search Catalogue + + +999 search "Rental" + + +Shows: + +- Song title. +- Era. +- Category. +- Lyrics availability. +- Download availability. + +Example: + + +Rental (v1) + +Era: DRFL +Lyrics: Synced +Download: Available + +[d] Download +[i] Info +[l] Lyrics + + +--- + +## Download Music + +Simple: + + +999 get "Rental" + + +Should: + +1. Search catalogue. +2. Select best match. +3. Download. +4. Validate file. +5. Embed lyrics. +6. Generate LRC if possible. +7. Add to library. + +--- + +## Library Sync + + +999 sync + + +Should: + +- Scan music folder. +- Find new files. +- Match metadata. +- Embed lyrics. +- Update rmpc files. + +--- + +## Library Status + + +999 status + + +Example: + + +Library + +Tracks: 250 + +Lyrics: +Synced: 180 +Plain: 50 +Missing: 20 + +rmpc: +LRC files: 180 + + +--- + +# TUI Vision + +The main interface should be a terminal dashboard. + +Goals: + +- Fast. +- Keyboard driven. +- Beautiful. +- Linux friendly. + +--- + +# Main Screens + +## 1. Browse + +Purpose: + +Discover songs. + +Features: + +- Search. +- Filters. +- Era selection. +- Lyrics preview. +- Download button. + +Example: + + +999 — Browse + +Search: rental + +Rental v1 +DRFL +Synced Lyrics +Download Available + +Rental v2 +POST +No Lyrics + + +--- + +## 2. Library + +Purpose: + +Manage local music. + +Shows: + +- Track list. +- Lyrics status. +- Sync status. +- Missing metadata. + +--- + +## 3. Downloads + +Purpose: + +Manage acquisition queue. + +Shows: + +- Active downloads. +- Completed downloads. +- Failed downloads. +- Retry options. + +Avoid exposing raw UUID job IDs. + +Use: + + +Download #1 +Download #2 + + +--- + +## 4. Song Details + +Shows: + +- Title. +- Era. +- Producers. +- Metadata. +- Lyrics preview. +- File information. + +--- + +# Lyrics Design + +The application must preserve the existing philosophy. + +## Embedded lyrics + +Primary source. + +Used for: + +- Android players. +- Portable files. +- Long-term storage. + +Formats: + +- SYLT for synced lyrics. +- USLT for plain lyrics. + +--- + +## LRC + +Compatibility layer. + +Used for: + +- rmpc. +- External lyric players. + +Rules: + +- Only generate from timestamped lyrics. +- Never invent timestamps. + +--- + +# Visual Style + +The application should fit Linux terminal workflows. + +Design goals: + +- Minimal. +- Fast. +- Keyboard focused. +- Customizable. + +Influences: + +- rmpc. +- lazygit. +- terminal file managers. +- modern TUI applications. + +--- + +# Technical Rules + +The v2 interface must remain separate from the backend. + +The TUI should not: + +- Modify ID3 tags directly. +- Handle API requests directly. +- Manage downloads directly. + +Instead: + +UI + | + v +Backend services + | + v +Files/API/Players + +--- + +# Development Order + +## Phase 1 + +Design: + +- Final name. +- Branding. +- CLI commands. +- TUI layout. + +## Phase 2 + +Migration: + +- New command. +- Backwards compatibility. +- Data migration. + +## Phase 3 + +CLI improvements: + +- Friendly commands. +- Better output. +- Simplified workflows. + +## Phase 4 + +TUI: + +- Browse. +- Library. +- Queue. +- Settings. + +## Phase 5 + +Release: + +- Version 2.0. +- Documentation. +- Packaging. + +--- + +# Current Status + +Backend is considered stable. + +Before v2 implementation: + +- 80 tests passing. +- Acquisition verified. +- Lyrics engine verified. +- rmpc integration verified. + +The next major milestone is turning the stable engine into a polished user experience. From 88f3bc5317868d6dcf25e8cc7915f64bc228a337 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:19:23 +0100 Subject: [PATCH 04/62] Add v2 development roadmap --- docs/ROADMAP_V2.md | 255 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 docs/ROADMAP_V2.md diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md new file mode 100644 index 0000000..75fd0fc --- /dev/null +++ b/docs/ROADMAP_V2.md @@ -0,0 +1,255 @@ +# v2 Development Roadmap + +This document defines the order of work for transforming juice-lyrics into a polished Juice WRLD music management application. + +The existing backend is considered stable and should be preserved. + +--- + +# Guiding Principles + +## Do not rewrite working systems + +The following are considered mature: + +- Lyrics engine +- ID3 embedding +- Backup system +- API client +- Track matching +- Downloader +- Acquisition jobs +- rmpc integration + +Future work should improve usability around these systems. + +--- + +# Phase 0 — Planning (Current) + +Status: In Progress + +Goals: + +- Preserve stable backend. +- Document architecture. +- Decide product direction. +- Prepare rename strategy. + +Completed: + +- GitHub repository created. +- Backend milestone saved. +- v2 design document created. +- Architecture decisions documented. + +--- + +# Phase 1 — Cleanup and Preparation + +Goal: + +Make the codebase ready for a major frontend redesign. + +Tasks: + +- Remove unused legacy CLI code. +- Simplify CLI entrypoint. +- Improve internal interfaces. +- Review documentation. +- Add missing regression tests. + +Important: + +Do not change user-facing behaviour unless necessary. + +--- + +# Phase 2 — Identity and Migration + +Goal: + +Introduce the new application identity. + +Tasks: + +- Choose final name. +- Update package metadata. +- Create new CLI command. +- Add migration from old configuration paths. +- Preserve juice-lyrics compatibility. + +Example: + +Old: + + +juice-lyrics sync + + +New: + + +999 sync + + +Both should work during transition. + +--- + +# Phase 3 — CLI Experience + +Goal: + +Make common actions simple. + +Current: + + +acquire search +acquire add +acquire run + + +Future: + + +999 get "Rental" + + +Improvements: + +- Friendly output. +- Remove unnecessary technical terms. +- Better error messages. +- Human-readable download queue. +- Better help screens. + +--- + +# Phase 4 — Interactive TUI + +Goal: + +Create the main application interface. + +Screens: + +## Browse + +Features: + +- Catalogue search. +- Filters. +- Song details. +- Lyrics preview. +- Download actions. + +--- + +## Library + +Features: + +- Local tracks. +- Lyrics status. +- Sync state. +- Metadata. + +--- + +## Downloads + +Features: + +- Active downloads. +- Progress. +- Completed items. +- Retry. + +--- + +## Settings + +Features: + +- Music directory. +- rmpc settings. +- API settings. + +--- + +# Phase 5 — Advanced Features + +Possible future improvements: + +## Lyrics Improvements + +- Better lyrics previews. +- Search within lyrics. +- More player integrations. + +## Library Improvements + +- Duplicate cleanup. +- Better sorting. +- Album/era organization. + +## Acquisition Improvements + +- Better batch workflows. +- Playlist-style downloads. +- Download history. + +## TUI Improvements + +- Themes. +- Custom keybindings. +- More customization. + +--- + +# Features NOT Planned + +Avoid feature creep. + +The project should not become: + +- A full music player replacement. +- A streaming service. +- A general-purpose downloader. +- A cloud music service. + +The goal is: + +"A beautiful Juice WRLD music management tool for Linux." + +--- + +# Release Goals + +## Version 2.0 + +Should include: + +- New identity. +- Better CLI. +- Interactive TUI. +- Migration support. +- Stable backend. + +--- + +# Success Criteria + +The application succeeds when a user can: + +1. Install it. +2. Open it. +3. Browse songs. +4. Download music. +5. Have lyrics embedded. +6. Play with rmpc. +7. Understand what is happening without reading documentation. + +The technology should disappear behind the experience. From 1a67909cf6e53e3436ef6fe2c3c03433a8d179f3 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:30:52 +0100 Subject: [PATCH 05/62] Add v2 project continuity brief --- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 556 +++++++++++++++++++++++++ 1 file changed, 556 insertions(+) create mode 100644 docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md new file mode 100644 index 0000000..91fe095 --- /dev/null +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -0,0 +1,556 @@ +# Juice WRLD TUI Project Continuity Brief (v2) + +## Purpose + +This document exists as a handoff/context file for continuing development of the Juice WRLD music management application after a chat reset. + +It describes: +- current project state +- architectural decisions +- future direction +- UX goals +- important constraints + +--- + +# Current Project Identity + +The project started as: + +`juice-lyrics` + +Originally it was a CLI tool for: + +- finding Juice WRLD lyrics through the Juice WRLD API +- embedding lyrics into MP3 ID3 tags +- generating rmpc-compatible LRC files +- syncing local music libraries + +It has evolved into a much larger application: + +A Juice WRLD music management hub containing: + +- catalogue search +- metadata browsing +- local library management +- lyric management +- acquisition/download workflows +- rmpc integration +- backup and recovery systems + +The current name no longer fully represents the project scope. + +--- + +# Current Backend Status + +The backend is considered stable. + +Milestone reached: + +## 80 automated tests passing + +Verified systems: + +- API client +- search +- metadata lookup +- track matching +- lyric parsing +- ID3 SYLT embedding +- ID3 USLT embedding +- LRC generation +- rmpc integration +- backups +- restore system +- downloader +- resume support +- persistent acquisition jobs +- duplicate detection +- CLI workflows + +Live API acquisition was tested successfully. + +The project has reached the point where the backend should be frozen before major redesign. + +--- + +# Important Architecture Rule + +DO NOT rewrite the backend during v2 redesign. + +The backend already works. + +The future TUI must be a presentation layer only. + +The architecture should remain: + + +Textual TUI +| +| +Application services +| +| +Backend modules +| +| +API / Files / MP3 / rmpc + + +The UI should call existing systems. + +The UI should NOT: +- edit ID3 tags directly +- handle downloads itself +- contain matching logic +- contain API logic + +--- + +# Current Repository State + +GitHub repository exists. + +Current branch: + +`v2-redesign` + +Important files: + + +PROJECT_CONTEXT.md + +docs/ +├── V2_DESIGN.md +├── DECISIONS.md +└── this file + + +The project is currently in the design/planning stage. + +--- + +# v2 Vision + +The goal is to transform the project from: + +"lyrics downloader/tagger" + +into: + +"A polished Juice WRLD music hub for Linux" + +The application should feel like a real Linux application. + +Inspired by: + +- rmpc +- superfile +- modern terminal applications + +--- + +# TUI Technology + +Preferred framework: + +## Textual + +Reasons: + +- modern Python ecosystem +- proper widgets +- colors +- keyboard navigation +- layouts +- dialogs +- responsive terminal UI +- feels like a real application + +The goal is NOT a menu-driven CLI. + +The goal is a proper TUI. + +--- + +# UX Philosophy + +The user should not need to understand technical internals. + +Avoid exposing: + +- SYLT +- USLT +- job UUIDs +- API paths +- complicated flags + +Prefer: + +- Synced Lyrics +- Plain Lyrics +- Downloads +- Queue +- Library +- Songs + +The application should feel approachable. + +--- + +# Proposed Screens + +## 1. Dashboard + +Purpose: + +The home screen. + +Shows: + +- library size +- lyric coverage +- rmpc status +- download status +- quick actions + + +Example: + + +999 Music Hub + +Library +39 Tracks + +Lyrics +19 Synced +20 Plain +0 Missing + +Downloads +1 Active + +[Browse] +[Sync] +[Queue] +[Settings] + + +--- + +## 2. Browse/Search + +Purpose: + +Discover songs. + +Features: + +- search bar +- live filtering +- eras: + - GBGR + - WOD + - DRFL + - JW3 + - POST + +Categories: + +- Released +- Unreleased +- Sessions + +Results show: + + +Rental (v1) + +Era: +DRFL + +Lyrics: +Synced + +Download: +Available + + +Actions: + +- open details +- download +- preview lyrics + +--- + +## 3. Library + +Purpose: + +Manage local music. + +Shows: + +- songs +- lyric status +- sync status +- missing metadata + +Actions: + +- sync +- verify +- open details + +--- + +## 4. Download Queue + +Purpose: + +Replace confusing job management. + +Instead of: + + +job-id: +2fc704cce61b4774868... + + +Use: + + +Downloads + +Rental +Downloading 65% +Lemon Glow +Complete + +Actions: + +- retry +- cancel +- remove + +--- + +## 5. Song Details + +Shows: + +- title +- era +- category +- producers +- lyrics status +- lyrics preview + +Actions: + +- download +- add lyrics +- view metadata + +--- + +## 6. Settings + +Controls: + +- music directory +- API settings +- rmpc settings +- backup settings + +--- + +# rmpc Important Information + +Current situation: + +rmpc only supports external LRC files. + +It does NOT read embedded lyrics. + +Therefore: + +## Synced lyrics + +Do: + +1. Embed SYLT into MP3 +2. Generate LRC +3. Put LRC into lyrics directory +4. rmpc displays lyrics + +## Plain lyrics + +Do: + +1. Embed USLT into MP3 + +Do NOT: + +- invent timestamps +- generate fake LRC + +Result: + +Android players can read embedded lyrics. + +rmpc cannot display them. + +This is accepted as a player limitation. + +--- + +# Future CLI Direction + +The CLI should become simpler. + +Current: + + +juice-lyrics acquire search Rental + +juice-lyrics acquire add Rental --index 1 + +juice-lyrics acquire run UUID + + +Future: + + +999 search Rental + +999 get Rental + + +The old commands can remain as compatibility commands. + +--- + +# Possible Rename + +The application probably needs a new name. + +Current favourite ideas: + +## 999 + +Pros: +- Juice WRLD connection +- memorable +- short command +- fits terminal culture + +Possible command: + + +999 + + +or: + + +999 search Rental + + +Other possibilities: + +- Abyss +- JuiceBox + +No final decision yet. + +--- + +# Development Order + +Do not immediately code. + +Recommended order: + +## Phase 1 +Design + +- branding +- naming +- screens +- user flows +- terminology + + +## Phase 2 +Migration + +- new package name +- new command +- compatibility layer +- preserve old data + + +## Phase 3 +CLI improvements + +Add: + +- simpler commands +- friendly queue system +- better output + + +## Phase 4 +Textual TUI + +Build: + +- dashboard +- browser +- library +- queue +- settings + + +## Phase 5 + +Release v2. + +--- + +# Development Rules + +Always: + +- preserve backend +- keep tests passing +- make reversible changes +- document decisions + +Never: + +- rewrite working systems +- mix UI and business logic +- remove features without discussion + +--- + +# User Preferences + +The user wants: + +- a real TUI, not a fake CLI menu +- a polished Arch Linux style application +- something that fits a rice setup +- keyboard-driven workflow +- modern terminal aesthetics + +The user is not a programmer. + +Instructions should be clear and guided. + +The goal is to create something that feels like a finished Linux application, not just a script. From 968559a62534a5eb2a65945591b0c3ad012c5cc1 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:39:12 +0100 Subject: [PATCH 06/62] Add initial v2 TUI design specification --- docs/UI_DESIGN.md | 419 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 docs/UI_DESIGN.md diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md new file mode 100644 index 0000000..2cb260a --- /dev/null +++ b/docs/UI_DESIGN.md @@ -0,0 +1,419 @@ +# 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 │ +└──────────────────────────────────────┘ + + +Questions: + +- Should dashboard open by default? +- Should recent songs/downloads appear? +- Should it show rmpc status? + +--- + +# Browse Screen + +Purpose: + +Discover songs from the Juice WRLD catalogue. + +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 + +[d] Download +[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: + + +My Library + +Rental.mp3 + +Lyrics: +Synced + +rmpc: +Ready + +Robbery.mp3 + +Lyrics: +Plain + +rmpc: +Unavailable + + +Actions: + + +s Sync +v Verify +enter Details + + +--- + +# Downloads Screen + +Purpose: + +Replace technical job management. + +The user should never need UUIDs. + +Example: + + +Downloads + +✓ Rental +Complete + +↓ Lemon Glow +Downloading 54% + +! Track +Failed + +Retry + + +Actions: + + +r Retry +d Delete +enter Details + + +--- + +# Settings Screen + +Purpose: + +Manage configuration. + +Example: + + +Settings + +Music Directory + +~/Music/Juice WRLD + +Lyrics Directory + +~/Music/Juice WRLD/lyrics + +Player + +rmpc detected ✓ + + +--- + +# Keybindings + +## Global + + +q Quit +esc Back +? Help +/ Search + + +## Lists + + +↑ ↓ Navigate +enter Select + + +## Browse + + +d Download +l Lyrics + + +## Library + + +s Sync +v Verify + + +## Downloads + + +r Retry +d Remove + + +--- + +# Future Screens + +Possible later additions: + +- lyrics viewer +- playlist manager +- statistics +- album/era explorer +- advanced metadata editor + +These are not required for the first release. + +--- + +# First Release Priority + +The first usable TUI version should contain: + +1. Dashboard +2. Browse/Search +3. Song Details +4. Download Queue +5. Library View + +Settings and advanced tools can follow. From ba3a534f30506f998ba49fe5597c6506350ba140 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 25 Aug 2026 19:39:58 +0100 Subject: [PATCH 07/62] Add v2 user flow specification --- docs/USER_FLOWS.md | 609 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 609 insertions(+) create mode 100644 docs/USER_FLOWS.md diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md new file mode 100644 index 0000000..51c69aa --- /dev/null +++ b/docs/USER_FLOWS.md @@ -0,0 +1,609 @@ +# 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. + +Current problem: + +The old CLI requires understanding setup, configuration, directories, and integrations. + +v2 goal: + +The application should guide the user. + +--- + +## Experience + +User runs: + + +999 + + +Application checks: + +- configuration exists +- music directory exists +- rmpc availability +- existing library + +--- + +Example: + + +Welcome to 999 + +First-time setup detected. + +Music folder: +~/Music/Juice WRLD + +rmpc: +Detected ✓ + +Existing tracks: +39 + +Would you like to continue? + +[Enter] Setup +[Esc] Exit + + +--- + +After setup: + + +Setup complete. + +Library: +39 tracks + +Lyrics: +39 processed + +Ready. + +Press Enter to continue. + + +--- + +# 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: + +User selects: + + +Rental (v1) + + +Presses: + + +d + + +--- + +Application: + + +Download Rental (v1)? + +Destination: + +~/Music/Juice WRLD/Unreleased + +[Enter] Confirm +[Esc] Cancel + + +--- + +After confirming: + + +Downloads + +Rental (v1) + +Downloading... + +████████░░ 80% + +Lyrics: +Synced + +After completion: + +✓ Added to library +✓ Lyrics embedded +✓ rmpc lyrics ready + + +--- + +# 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 their own collection. + +--- + +Library view: + + +My Library + +Rental.mp3 +Synced Lyrics ✓ + +Robbery.mp3 +Plain Lyrics + +Unknown Track +Missing Lyrics + + +--- + +Actions: + + +s Sync Library + +v Verify Lyrics + +enter Details + + +--- + +# Flow 7: Syncing Library + +## Goal + +Update new or changed files. + +--- + +User: + + +Press s + + +--- + +Confirmation: + + +Sync library? + +Found: + +12 new files + +Continue? + +[Enter] + + +--- + +Progress: + + +Syncing... + +Rental.mp3 +Matching... + +Lyrics found ✓ + +Embedding... + +Complete + + +--- + +Summary: + + +Sync Complete + +Updated: +12 + +Synced Lyrics: +8 + +Plain Lyrics: +4 + +Failed: +0 + + +--- + +# Flow 8: Managing Downloads + +## Goal + +Replace job management with a friendly queue. + +--- + +Downloads screen: + + +Queue + +✓ Rental + +Complete + +↓ Lemon Glow + +Downloading 52% + +! Track + +Failed + + +--- + +Actions: + + +r Retry + +d Remove + +enter Details + + +--- + +# 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 + +--- + +# Future User Flows + +Possible later additions: + +- playlists +- favourites +- statistics +- automatic library monitoring +- album/era exploration +- lyrics-only mode + +These are not required for the first v2 release. From 5c4dd508321a7483b8f9478edbf0067351d3ee3a Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 28 Aug 2026 23:21:18 +0100 Subject: [PATCH 08/62] Add current project state document --- docs/PROJECT_STATE.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/PROJECT_STATE.md diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md new file mode 100644 index 0000000..3754ba8 --- /dev/null +++ b/docs/PROJECT_STATE.md @@ -0,0 +1,40 @@ +# 999 Project State + +## Current Status +Backend frozen. +80 tests passing. +GitHub backup complete. + +## Current Branch +v2-redesign + +## What Exists +- API client +- lyrics engine +- acquisition +- downloader +- rmpc integration +- CLI + +## What Is Planned +- rename to 999 +- Textual TUI +- UX redesign +- migration system + +## Important Decisions +- Keep embedded lyrics +- Keep LRC generation for rmpc +- Use terminal-native colours +- Use Textual +- Keep backend separate from UI + +## Current Problem +Not installed globally. +Still development venv. + +## Next Steps +1. Finish design docs +2. Design TUI +3. Implement v2 +4. Package/install properly From 4be741ccf4e572a36fb71fcbe1ed56dd5a02bd2c Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 28 Aug 2026 23:30:16 +0100 Subject: [PATCH 09/62] Extract read-only library status service --- src/juice_lyrics/cli.py | 44 +++---- src/juice_lyrics/services/__init__.py | 5 + src/juice_lyrics/services/library_status.py | 93 +++++++++++++++ tests/test_library_status.py | 125 ++++++++++++++++++++ 4 files changed, 239 insertions(+), 28 deletions(-) create mode 100644 src/juice_lyrics/services/__init__.py create mode 100644 src/juice_lyrics/services/library_status.py create mode 100644 tests/test_library_status.py diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index d21bc40..70f7480 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -703,6 +703,7 @@ 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 def search_api(settings: Settings, title: str, refresh: bool = False) -> list[dict[str, Any]]: @@ -803,35 +804,22 @@ def command_sync(args: argparse.Namespace, settings: Settings, use_color: bool) 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(f"MP3 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: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py new file mode 100644 index 0000000..f86eb02 --- /dev/null +++ b/src/juice_lyrics/services/__init__.py @@ -0,0 +1,5 @@ +"""Application services shared by command-line and interactive frontends.""" + +from .library_status import LibraryStatus, get_library_status + +__all__ = ["LibraryStatus", "get_library_status"] diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py new file mode 100644 index 0000000..2c07ee0 --- /dev/null +++ b/src/juice_lyrics/services/library_status.py @@ -0,0 +1,93 @@ +from __future__ import annotations + +import json +from collections.abc import Callable +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from ..config.settings import BACKUP_DIR, STATE_FILE, Settings +from ..library.scanner import find_mp3s +from ..lyrics.engine import verify_file +from ..state import sha256_file + +LyricsVerifier = Callable[[Path], tuple[bool, str]] + + +@dataclass(frozen=True, slots=True) +class LibraryStatus: + """Read-only snapshot of the application's MP3 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 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 + 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 = state_files.get(relative) + if not isinstance(entry, dict) or entry.get("sha256") != sha256_file(path): + new_or_changed += 1 + if isinstance(entry, dict) and entry.get("lrc") and Path(entry["lrc"]).is_file(): + lrc += 1 + + backup_path = Path(backup_dir) + backup_count = ( + len([path for path in backup_path.iterdir() if path.is_dir()]) + if backup_path.exists() + else 0 + ) + 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/tests/test_library_status.py b/tests/test_library_status.py new file mode 100644 index 0000000..a314d17 --- /dev/null +++ b/tests/test_library_status.py @@ -0,0 +1,125 @@ +import json +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.library_status import LibraryStatus, 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 = tmp_path / "lyrics" / "synced.lrc" + lrc.parent.mkdir() + 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" + (backup_dir / "one").mkdir(parents=True) + (backup_dir / "two").mkdir() + (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), + 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_file_for_sync_and_ignores_non_mp3(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 == 1 + assert status.missing_or_invalid_count == 1 + assert status.new_or_changed_count == 1 + + +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 From 7e44ecb9f672d990392d5dc6586937a6b8128205 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 28 Aug 2026 23:43:52 +0100 Subject: [PATCH 10/62] Add typed catalogue query service --- src/juice_lyrics/cli.py | 68 ++++---- src/juice_lyrics/services/__init__.py | 17 +- src/juice_lyrics/services/catalogue.py | 207 +++++++++++++++++++++++++ tests/test_catalogue_service.py | 176 +++++++++++++++++++++ 4 files changed, 431 insertions(+), 37 deletions(-) create mode 100644 src/juice_lyrics/services/catalogue.py create mode 100644 tests/test_catalogue_service.py diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 70f7480..30c9353 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -704,6 +704,7 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: 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 def search_api(settings: Settings, title: str, refresh: bool = False) -> list[dict[str, Any]]: @@ -851,8 +852,14 @@ def command_scan(args: argparse.Namespace, settings: Settings, use_color: bool) 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 = [] @@ -862,47 +869,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, ""): diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index f86eb02..545a14b 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -1,5 +1,20 @@ """Application services shared by command-line and interactive frontends.""" +from .catalogue import ( + CatalogueSearchResult, + LyricAvailability, + SongDetails, + get_song_details, + search_catalogue, +) from .library_status import LibraryStatus, get_library_status -__all__ = ["LibraryStatus", "get_library_status"] +__all__ = [ + "CatalogueSearchResult", + "LibraryStatus", + "LyricAvailability", + "SongDetails", + "get_library_status", + "get_song_details", + "search_catalogue", +] diff --git a/src/juice_lyrics/services/catalogue.py b/src/juice_lyrics/services/catalogue.py new file mode 100644 index 0000000..3e998c0 --- /dev/null +++ b/src/juice_lyrics/services/catalogue.py @@ -0,0 +1,207 @@ +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass +from enum import Enum +from pathlib import Path +from typing import Any + +from ..acquisition.resolver import ResourceResolutionError, resolve_resource +from ..api.client import 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]] +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 + + +@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 + + +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 _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), + } + + +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.""" + + response = searcher( + settings, + query, + category=category, + era=era, + refresh=refresh, + ) + raw_results = response.get("results", []) if isinstance(response, Mapping) else [] + if not isinstance(raw_results, Sequence) or isinstance(raw_results, (str, bytes, bytearray)): + return () + + 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)) + return tuple(results) + + +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/tests/test_catalogue_service.py b/tests/test_catalogue_service.py new file mode 100644 index 0000000..2d0c9f1 --- /dev/null +++ b/tests/test_catalogue_service.py @@ -0,0 +1,176 @@ +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 ( + LyricAvailability, + get_song_details, + search_catalogue, +) + + +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", "refresh": True})] + + +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_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, + } + + 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.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 From a82aac16a23b4e428f7af91d39277ef337bd127e Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 28 Aug 2026 23:50:01 +0100 Subject: [PATCH 11/62] Add read-only acquisition queue service --- src/juice_lyrics/cli.py | 13 +- src/juice_lyrics/services/__init__.py | 16 ++ .../services/acquisition_queue.py | 267 ++++++++++++++++++ tests/test_acquisition_queue_service.py | 196 +++++++++++++ 4 files changed, 486 insertions(+), 6 deletions(-) create mode 100644 src/juice_lyrics/services/acquisition_queue.py create mode 100644 tests/test_acquisition_queue_service.py diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 30c9353..96e4a8c 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -705,6 +705,7 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: 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 def search_api(settings: Settings, title: str, refresh: bool = False) -> list[dict[str, Any]]: @@ -1313,15 +1314,15 @@ def command_acquire_manifest(args: argparse.Namespace, settings: Settings, use_c 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 diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 545a14b..502088d 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -1,5 +1,14 @@ """Application services shared by command-line and interactive frontends.""" +from .acquisition_queue import ( + QueueItem, + QueueJob, + QueueReferenceError, + QueueSnapshot, + QueueStatus, + get_queue_snapshot, + resolve_queue_reference, +) from .catalogue import ( CatalogueSearchResult, LyricAvailability, @@ -13,8 +22,15 @@ "CatalogueSearchResult", "LibraryStatus", "LyricAvailability", + "QueueItem", + "QueueJob", + "QueueReferenceError", + "QueueSnapshot", + "QueueStatus", "SongDetails", + "get_queue_snapshot", "get_library_status", "get_song_details", "search_catalogue", + "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..77bffc8 --- /dev/null +++ b/src/juice_lyrics/services/acquisition_queue.py @@ -0,0 +1,267 @@ +from __future__ import annotations + +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 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" + + +@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 + + +@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, ...] + + +@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 _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")) + expected = _optional_nonnegative_int(item_record.get("expected_size")) + error = _text(record.get("error")) + return QueueItem( + title=_text(item_record.get("title")), + destination=Path(destination_text) if destination_text else None, + 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, + ) + + +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, + ) + ) + + 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/tests/test_acquisition_queue_service.py b/tests/test_acquisition_queue_service.py new file mode 100644 index 0000000..15c3574 --- /dev/null +++ b/tests/test_acquisition_queue_service.py @@ -0,0 +1,196 @@ +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 AcquisitionItem, AcquisitionState +from juice_lyrics.services.acquisition_queue import ( + 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_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 From d0d5aefc0a88fcd9d8eec3aaa079a97cf86336c1 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 11:43:35 +0100 Subject: [PATCH 12/62] Add safe acquisition post-processing rollback --- src/juice_lyrics/acquisition/integration.py | 80 ++++- src/juice_lyrics/backup/manager.py | 3 + tests/test_acquisition_integration_safety.py | 298 +++++++++++++++++++ 3 files changed, 372 insertions(+), 9 deletions(-) create mode 100644 tests/test_acquisition_integration_safety.py diff --git a/src/juice_lyrics/acquisition/integration.py b/src/juice_lyrics/acquisition/integration.py index 3f537c4..97435ab 100644 --- a/src/juice_lyrics/acquisition/integration.py +++ b/src/juice_lyrics/acquisition/integration.py @@ -4,7 +4,13 @@ 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 @@ -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( @@ -53,24 +60,72 @@ 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}") + 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 RuntimeError( + 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 RuntimeError( + 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." + ) from restore_exc + raise RuntimeError( + 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 and lyrics_dir is not None: - lrc_path = write_lrc(path, synced, song, Path(lyrics_dir)) + try: + lrc_path = write_lrc(path, synced, song, Path(lyrics_dir)) + except Exception as exc: + raise RuntimeError( + 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 +150,25 @@ 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 RuntimeError( + 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/backup/manager.py b/src/juice_lyrics/backup/manager.py index c7deba0..81d1317 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -15,6 +15,9 @@ def make_backup_root(): ensure_data_dirs(); root=BACKUP_DIR/datetime.now().strft 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 +def restore_file(backup:Path,destination:Path)->None: + destination.parent.mkdir(parents=True,exist_ok=True); shutil.copy2(backup,destination) + 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") diff --git a/tests/test_acquisition_integration_safety.py b/tests/test_acquisition_integration_safety.py new file mode 100644 index 0000000..4875ce1 --- /dev/null +++ b/tests/test_acquisition_integration_safety.py @@ -0,0 +1,298 @@ +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 + + +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() + + +@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 From 24a709ee5d9f27dae0a1b32e5828d08a7f0ace9a Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 11:51:08 +0100 Subject: [PATCH 13/62] Support safe acquisition post-processing retries --- src/juice_lyrics/acquisition/__init__.py | 10 +- src/juice_lyrics/acquisition/downloader.py | 8 +- src/juice_lyrics/acquisition/integration.py | 20 +- src/juice_lyrics/acquisition/jobs.py | 28 +- src/juice_lyrics/acquisition/models.py | 29 ++ src/juice_lyrics/acquisition/runner.py | 111 ++++++- src/juice_lyrics/cli.py | 2 + tests/test_acquisition_postprocess_retry.py | 327 ++++++++++++++++++++ 8 files changed, 522 insertions(+), 13 deletions(-) create mode 100644 tests/test_acquisition_postprocess_retry.py 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 97435ab..e4ded8d 100644 --- a/src/juice_lyrics/acquisition/integration.py +++ b/src/juice_lyrics/acquisition/integration.py @@ -14,7 +14,7 @@ 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) @@ -88,7 +88,8 @@ def integrate_downloaded_mp3( }], ) except Exception as exc: - raise RuntimeError( + raise AcquisitionPostProcessingError( + AcquisitionFailureStage.LYRICS, f"Audio download completed, but lyric backup failed before metadata modification: {exc}. " "The downloaded file was not modified." ) from exc @@ -102,12 +103,15 @@ def integrate_downloaded_mp3( try: restore_file(backup_path, path) except Exception as restore_exc: - raise RuntimeError( + 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." + f"The pristine backup remains at {backup_path}; the downloaded file may be partially modified.", + reuse_finalized_file=False, ) from restore_exc - raise RuntimeError( + 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 @@ -116,7 +120,8 @@ def integrate_downloaded_mp3( try: lrc_path = write_lrc(path, synced, song, Path(lyrics_dir)) except Exception as exc: - raise RuntimeError( + 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 @@ -151,7 +156,8 @@ def integrate_downloaded_mp3( save_state(current_state) except Exception as exc: processed = " and lyric processing succeeded" if lyric_type != "NONE" else "" - raise RuntimeError( + 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." 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..b53f1f6 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, @@ -54,7 +104,41 @@ def report(index: int, written: int, remote_total: int | None) -> None: 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 +150,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 +171,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/cli.py b/src/juice_lyrics/cli.py index 96e4a8c..45706ca 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -1333,6 +1333,8 @@ 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), 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 From e5ffa41c9363e01884b8c579840546129f215b6b Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 11:59:31 +0100 Subject: [PATCH 14/62] Extract typed library sync service --- src/juice_lyrics/cli.py | 90 ++++- src/juice_lyrics/services/__init__.py | 26 ++ src/juice_lyrics/services/library_sync.py | 428 ++++++++++++++++++++++ tests/test_library_sync_service.py | 299 +++++++++++++++ 4 files changed, 834 insertions(+), 9 deletions(-) create mode 100644 src/juice_lyrics/services/library_sync.py create mode 100644 tests/test_library_sync_service.py diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 45706ca..0f6c25a 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -706,6 +706,13 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: 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, +) def search_api(settings: Settings, title: str, refresh: bool = False) -> list[dict[str, Any]]: @@ -792,17 +799,82 @@ def command_setup(args: argparse.Namespace, settings: Settings, use_color: bool) 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=DEFAULT_RMPC_LYRICS_DIR if rmpc_enabled else 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: + 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 MP3(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: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 502088d..64a6260 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -17,20 +17,46 @@ search_catalogue, ) from .library_status import LibraryStatus, get_library_status +from .library_sync import ( + LibrarySyncDependencies, + LibrarySyncOptions, + LibrarySyncPlan, + LibrarySyncResult, + MatchOutcome, + SyncEvent, + SyncEventKind, + SyncLyricType, + TrackSyncPlan, + TrackSyncResult, + execute_library_sync, + plan_library_sync, +) __all__ = [ "CatalogueSearchResult", "LibraryStatus", + "LibrarySyncDependencies", + "LibrarySyncOptions", + "LibrarySyncPlan", + "LibrarySyncResult", "LyricAvailability", + "MatchOutcome", "QueueItem", "QueueJob", "QueueReferenceError", "QueueSnapshot", "QueueStatus", "SongDetails", + "SyncEvent", + "SyncEventKind", + "SyncLyricType", + "TrackSyncPlan", + "TrackSyncResult", + "execute_library_sync", "get_queue_snapshot", "get_library_status", "get_song_details", + "plan_library_sync", "search_catalogue", "resolve_queue_reference", ] diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py new file mode 100644 index 0000000..aed206d --- /dev/null +++ b/src/juice_lyrics/services/library_sync.py @@ -0,0 +1,428 @@ +from __future__ import annotations + +import json +from collections.abc import Callable, Mapping +from dataclasses import dataclass, field +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, DEFAULT_RMPC_LYRICS_DIR, STATE_FILE, Settings +from ..library.matching import choose_candidate, search_title_for +from ..library.scanner import find_mp3s +from ..lyrics.engine import embed_lyrics, parse_synced_lyrics, verify_file, write_lrc +from ..rmpc.integration import notify_rmpc_index, patch_rmpc_config +from ..state import load_state, save_state, sha256_file +from ..backup.manager import now_iso + + +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 + + @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, + ) -> "LibrarySyncOptions": + return cls( + settings=settings, + music_dir=Path(settings.music_dir), + dry_run=dry_run, + refresh=refresh, + rmpc_enabled=rmpc_enabled, + lyrics_dir=Path(lyrics_dir) if lyrics_dir is not None else 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), + ) + + +@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 + + +@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], 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, +) -> bool: + entry = state.get("files", {}).get(str(path.relative_to(options.music_dir))) + 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") == SyncLyricType.SYNCED.value: + lrc = Path(str(entry.get("lrc") or "")) + if not lrc.is_file(): + return False + return True + + +def plan_library_sync( + options: LibrarySyncOptions, + *, + dependencies: LibrarySyncDependencies | None = None, + progress: ProgressCallback | None = None, +) -> LibrarySyncPlan: + dependencies = dependencies or LibrarySyncDependencies() + files = dependencies.scanner(options.settings) + state = _read_state(options.state_file) if options.dry_run else dependencies.state_loader() + tracks: list[TrackSyncPlan] = [] + _emit(progress, SyncEventKind.SCAN_STARTED, total=len(files)) + for index, path in enumerate(files, start=1): + if not options.refresh and _state_is_current(state, path, options, dependencies): + _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) + candidate, _, _, _ = dependencies.matcher(options.settings, path, results, title) + if candidate is None: + tracks.append(TrackSyncPlan(path, MatchOutcome.UNRESOLVED, SyncLyricType.NONE)) + _emit(progress, SyncEventKind.UNRESOLVED, path=path) + 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)) + _emit(progress, SyncEventKind.MATCH_FOUND, path=path, message=lyric_type.value) + 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 _state_entry( + state: dict[str, Any], + track: TrackSyncPlan, + options: LibrarySyncOptions, + lrc_path: Path | None, + dependencies: LibrarySyncDependencies, +) -> None: + candidate = track.candidate or {} + state.setdefault("files", {})[str(track.path.relative_to(options.music_dir))] = { + "sha256": dependencies.hasher(track.path), + "song_id": candidate.get("id"), + "api_name": candidate.get("name"), + "lyric_type": track.lyric_type.value, + "lrc": str(lrc_path) if lrc_path else None, + "updated": now_iso(), + } + + +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 + ) + + if options.rmpc_enabled and options.lyrics_dir is not None: + if options.rmpc_config_path is not None: + text = options.rmpc_config_path.read_text(encoding="utf-8") + if str(options.lyrics_dir) not in text: + dependencies.rmpc_configurer(options.rmpc_config_path, options.lyrics_dir) + options.lyrics_dir.mkdir(parents=True, exist_ok=True) + + 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 and options.lyrics_dir is not None: + lrc_path = dependencies.lrc_writer( + track.path, + list(track.synced_lyrics), + dict(track.candidate or {}), + options.lyrics_dir, + ) + 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/tests/test_library_sync_service.py b/tests/test_library_sync_service.py new file mode 100644 index 0000000..464f0fd --- /dev/null +++ b/tests/test_library_sync_service.py @@ -0,0 +1,299 @@ +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, + 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" + + +@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_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, output): + lrc_calls.append(path) + result = output / f"{path.stem}.lrc" + result.parent.mkdir(parents=True, exist_ok=True) + result.write_text("lrc") + return result + + deps.lrc_writer = write_lrc + deps.rmpc_notifier = lambda paths: len(paths) + options = _options(tmp_path, rmpc_enabled=True, lyrics_dir=tmp_path / "lyrics") + result = execute_library_sync(plan_library_sync(options, dependencies=deps), dependencies=deps) + + assert lrc_calls == [synced] + 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 From c5b165f8a80cdd66edf3c7003a6d890df58fe77f Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 12:08:39 +0100 Subject: [PATCH 15/62] Add initial read-only Textual TUI shell --- docs/DEVELOPMENT.md | 11 + pyproject.toml | 5 +- src/juice_lyrics/cli.py | 11 + src/juice_lyrics/tui/__init__.py | 5 + src/juice_lyrics/tui/app.py | 194 ++++++++++++++++ src/juice_lyrics/tui/screens/__init__.py | 6 + src/juice_lyrics/tui/screens/base.py | 46 ++++ src/juice_lyrics/tui/screens/dashboard.py | 86 +++++++ src/juice_lyrics/tui/screens/placeholder.py | 22 ++ tests/test_tui.py | 243 ++++++++++++++++++++ 10 files changed, 628 insertions(+), 1 deletion(-) create mode 100644 src/juice_lyrics/tui/__init__.py create mode 100644 src/juice_lyrics/tui/app.py create mode 100644 src/juice_lyrics/tui/screens/__init__.py create mode 100644 src/juice_lyrics/tui/screens/base.py create mode 100644 src/juice_lyrics/tui/screens/dashboard.py create mode 100644 src/juice_lyrics/tui/screens/placeholder.py create mode 100644 tests/test_tui.py diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 6e423e1..afc70b0 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -52,6 +52,17 @@ The project uses `pyproject.toml` and exposes the `juice-lyrics` console script. Keep the runtime dependency set small. +### Experimental Textual interface + +From an editable installation, launch the early read-only TUI shell with: + +```bash +juice-lyrics tui +``` + +This milestone provides a dashboard and navigation placeholders only. It does +not download media, sync lyrics, edit settings, or modify the local library. + ## Source of truth and Git workflow 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. diff --git a/pyproject.toml b/pyproject.toml index ebcb982..a4693d8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,10 @@ version = "1.4.0" description = "Manage local lyrics metadata and rmpc LRC files for MP3 libraries" readme = "README.md" requires-python = ">=3.11" -dependencies = ["mutagen>=1.47"] +dependencies = [ + "mutagen>=1.47", + "textual>=1.0,<2.0", +] license = { text = "MIT" } authors = [ { name = "juice-wrld-lyrics contributors" } diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 0f6c25a..23b12c6 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -1502,6 +1502,14 @@ 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 experimental Textual frontend without affecting CLI startup.""" + + 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.add_argument("--version", action="version", version=f"{APP_NAME} {__version__}") @@ -1540,6 +1548,8 @@ def build_parser() -> argparse.ArgumentParser: guide = sub.add_parser("guide", help="Show the built-in quick guide.") + sub.add_parser("tui", help="Launch the experimental read-only Textual interface.") + search = sub.add_parser("search", help="Search the public Juice WRLD song catalogue.") search.add_argument("query") search.add_argument("--category") @@ -1617,6 +1627,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) diff --git a/src/juice_lyrics/tui/__init__.py b/src/juice_lyrics/tui/__init__.py new file mode 100644 index 0000000..be0197d --- /dev/null +++ b/src/juice_lyrics/tui/__init__.py @@ -0,0 +1,5 @@ +"""Experimental read-only 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..5e191d9 --- /dev/null +++ b/src/juice_lyrics/tui/app.py @@ -0,0 +1,194 @@ +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.widgets import Button + +from ..services import LibraryStatus, QueueSnapshot, get_library_status, get_queue_snapshot +from .screens.dashboard import DashboardScreen +from .screens.placeholder import PlaceholderScreen + +LibraryStatusProvider = Callable[[Any], LibraryStatus] +QueueSnapshotProvider = Callable[[], QueueSnapshot] + + +class JuiceLyricsApp(App[None]): + """The first read-only application shell for the planned 999 interface.""" + + 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), + Binding("q", "quit", "Quit", show=False, priority=True), + ] + + CSS = """ + Screen { + background: transparent; + } + + #brand { + height: 3; + padding: 0 2; + text-style: bold; + border-bottom: solid ansi_blue; + } + + #primary-navigation { + height: 3; + padding: 0 1; + align-horizontal: center; + } + + #primary-navigation Button { + min-width: 12; + height: 3; + margin: 0 1; + background: transparent; + border: none; + } + + #primary-navigation Button:hover, + #primary-navigation Button:focus, + #primary-navigation Button.-active { + background: ansi_blue; + color: ansi_bright_white; + text-style: bold; + } + + #screen-content { + height: 1fr; + padding: 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_blue; + padding: 1 2; + height: auto; + min-height: 12; + } + + .panel-title { + text-style: bold; + height: 2; + } + + .panel-error { + color: ansi_red; + height: auto; + } + + #placeholder-panel { + border: round ansi_blue; + padding: 2 3; + height: auto; + max-width: 72; + } + + #status-footer { + height: 2; + padding: 0 2; + border-top: solid ansi_blue; + } + + Screen.-narrow #primary-navigation Button { + min-width: 7; + margin: 0; + } + + Screen.-narrow #dashboard-panels { + grid-size: 1 2; + overflow-y: auto; + } + + Screen.-narrow #screen-content { + padding: 1; + } + """ + + def __init__( + self, + settings: Any, + *, + library_status_provider: LibraryStatusProvider = get_library_status, + queue_snapshot_provider: QueueSnapshotProvider = get_queue_snapshot, + ) -> None: + super().__init__() + self.settings = settings + self.library_status_provider = library_status_provider + self.queue_snapshot_provider = queue_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( + PlaceholderScreen("Browse", "Catalogue search and song details are planned for a later milestone."), + "browse", + ) + self.install_screen( + PlaceholderScreen("Library", "Local track browsing and sync actions are planned for a later milestone."), + "library", + ) + self.install_screen( + PlaceholderScreen("Downloads", "Queue details and acquisition actions are planned for a later milestone."), + "downloads", + ) + self.install_screen( + PlaceholderScreen("Settings", "Configuration viewing and editing are planned for a later milestone."), + "settings", + ) + self.push_screen("dashboard") + + def action_show_section(self, section: str) -> None: + if self.screen.name == section: + return + self.switch_screen(section) + + 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: + self.notify("1–5 navigate • Tab changes focus • r refreshes Dashboard • q quits", timeout=5) + + def on_button_pressed(self, event: Button.Pressed) -> None: + if event.button.id and event.button.id.startswith("nav-"): + self.action_show_section(event.button.id.removeprefix("nav-")) + + +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/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py new file mode 100644 index 0000000..2e72a38 --- /dev/null +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -0,0 +1,6 @@ +"""Screens for the experimental Textual frontend.""" + +from .dashboard import DashboardScreen +from .placeholder import PlaceholderScreen + +__all__ = ["DashboardScreen", "PlaceholderScreen"] diff --git a/src/juice_lyrics/tui/screens/base.py b/src/juice_lyrics/tui/screens/base.py new file mode 100644 index 0000000..725885f --- /dev/null +++ b/src/juice_lyrics/tui/screens/base.py @@ -0,0 +1,46 @@ +from __future__ import annotations + +from collections.abc import Iterable + +from textual.app import ComposeResult +from textual.containers import Container, Horizontal +from textual.events import Resize +from textual.screen import Screen +from textual.widget import Widget +from textual.widgets import Button, Static + +_SECTIONS = ( + ("dashboard", "1 Dashboard"), + ("browse", "2 Browse"), + ("library", "3 Library"), + ("downloads", "4 Downloads"), + ("settings", "5 Settings"), +) + + +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\nJuice WRLD Music Hub", id="brand") + with Horizontal(id="primary-navigation"): + for section, label in _SECTIONS: + button = Button(label, id=f"nav-{section}") + if section == self.section: + button.add_class("-active") + yield button + with Container(id="screen-content"): + yield Static(self.title, id="screen-title") + yield from self.compose_content() + yield Static("1–5 Navigate Tab Focus r Refresh ? Help q Quit", id="status-footer") + + def on_resize(self, event: Resize) -> None: + self.set_class(event.size.width < 70, "-narrow") diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py new file mode 100644 index 0000000..64eabac --- /dev/null +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -0,0 +1,86 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from typing import Any + +from textual.containers import Container, Grid +from textual.widget import Widget +from textual.widgets import Static + +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 + + 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 refresh_snapshot(self) -> None: + self._refresh_library() + self._refresh_queue() + + def _refresh_library(self) -> None: + error = self.query_one("#library-error", Static) + try: + status = self._library_status_provider(self.settings) + except Exception as exc: + self.query_one("#library-data", Static).update("Library data unavailable") + error.update(f"Warning: {exc}") + return + + lines = ( + f"Path {status.library_path}", + f"MP3 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 _refresh_queue(self) -> None: + error = self.query_one("#queue-error", Static) + try: + snapshot = self._queue_snapshot_provider() + except Exception as exc: + self.query_one("#queue-data", Static).update("Queue data unavailable") + error.update(f"Warning: {exc}") + return + + lines = ( + f"Total jobs {snapshot.total_job_count}", + f"Pending {snapshot.pending_job_count}", + f"Active {snapshot.active_job_count}", + f"Completed {snapshot.completed_job_count}", + f"Failed {snapshot.failed_job_count}", + ) + self.query_one("#queue-data", Static).update("\n".join(lines)) + error.update("") 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/tests/test_tui.py b/tests/test_tui.py new file mode 100644 index 0000000..ef9946c --- /dev/null +++ b/tests/test_tui.py @@ -0,0 +1,243 @@ +import asyncio +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 import LibraryStatus, QueueSnapshot +from juice_lyrics.tui import JuiceLyricsApp + + +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, + ) + + +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 "MP3 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 "Total jobs 5" in queue + assert "Pending 1" in queue + assert "Active 1" in queue + assert "Completed 2" in queue + assert "Failed 1" in queue + + asyncio.run(scenario()) + + +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 "MP3 tracks 0" in _rendered(app, "#library-data") + assert "Total jobs 0" in _rendered(app, "#queue-data") + + asyncio.run(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 "MP3 tracks 2" in _rendered(app, "#library-data") + assert "Total jobs 2" in _rendered(app, "#queue-data") + + asyncio.run(scenario()) + + +def test_keyboard_navigation_reaches_all_placeholder_screens(tmp_path): + async def scenario(): + app = _app(tmp_path) + async with app.run_test() as pilot: + await pilot.pause() + for key, section in zip("2345", ("browse", "library", "downloads", "settings")): + await pilot.press(key) + await pilot.pause() + assert app.screen.id == f"screen-{section}" + assert "planned for a later milestone" in _rendered(app, "#placeholder-message") + await pilot.press("1") + await pilot.pause() + assert app.screen.id == "screen-dashboard" + + asyncio.run(scenario()) + + +def test_navigation_buttons_are_keyboard_focusable(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 not None + assert app.focused.id and app.focused.id.startswith("nav-") + + asyncio.run(scenario()) + + +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 "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 "MP3 tracks 4" in _rendered(app, "#library-data") + await pilot.press("5") + await pilot.pause() + assert app.screen.id == "screen-settings" + + asyncio.run(scenario()) From 7a1303e73b4614b1848195b6d8ef2f070f9416b2 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 12:18:26 +0100 Subject: [PATCH 16/62] Add responsive terminal-native Textual shell --- docs/DEVELOPMENT.md | 3 + src/juice_lyrics/tui/app.py | 46 +++++--- src/juice_lyrics/tui/screens/base.py | 12 +- src/juice_lyrics/tui/screens/dashboard.py | 65 +++++++++-- tests/test_tui.py | 136 +++++++++++++++++++++- 5 files changed, 226 insertions(+), 36 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index afc70b0..7bc3811 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -62,6 +62,9 @@ juice-lyrics tui This milestone provides a dashboard and navigation placeholders only. It does not download media, 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. ## Source of truth and Git workflow diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 5e191d9..b58e7ef 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -7,7 +7,8 @@ from textual.binding import Binding from textual.widgets import Button -from ..services import LibraryStatus, QueueSnapshot, get_library_status, get_queue_snapshot +from ..services.acquisition_queue import QueueSnapshot, get_queue_snapshot +from ..services.library_status import LibraryStatus, get_library_status from .screens.dashboard import DashboardScreen from .screens.placeholder import PlaceholderScreen @@ -38,37 +39,43 @@ class JuiceLyricsApp(App[None]): } #brand { - height: 3; - padding: 0 2; + height: 2; + padding: 0 1; text-style: bold; - border-bottom: solid ansi_blue; + border-bottom: solid ansi_cyan; } #primary-navigation { height: 3; - padding: 0 1; + padding: 0; align-horizontal: center; } - #primary-navigation Button { + #primary-navigation NavigationButton { min-width: 12; height: 3; margin: 0 1; background: transparent; + color: ansi_default; border: none; } - #primary-navigation Button:hover, - #primary-navigation Button:focus, - #primary-navigation Button.-active { - background: ansi_blue; - color: ansi_bright_white; - text-style: bold; + #primary-navigation NavigationButton:hover { + background: transparent; + color: ansi_default; + text-style: underline; + } + + #primary-navigation NavigationButton.-active, + #primary-navigation NavigationButton.-active:hover { + background: ansi_default; + color: ansi_default; + text-style: bold reverse; } #screen-content { height: 1fr; - padding: 1 2; + padding: 0 2 1 2; } #screen-title { @@ -84,7 +91,7 @@ class JuiceLyricsApp(App[None]): } .dashboard-panel { - border: round ansi_blue; + border: round ansi_cyan; padding: 1 2; height: auto; min-height: 12; @@ -101,7 +108,7 @@ class JuiceLyricsApp(App[None]): } #placeholder-panel { - border: round ansi_blue; + border: round ansi_cyan; padding: 2 3; height: auto; max-width: 72; @@ -110,10 +117,11 @@ class JuiceLyricsApp(App[None]): #status-footer { height: 2; padding: 0 2; - border-top: solid ansi_blue; + border-top: solid ansi_cyan; + text-style: dim; } - Screen.-narrow #primary-navigation Button { + Screen.-narrow #primary-navigation NavigationButton { min-width: 7; margin: 0; } @@ -135,7 +143,7 @@ def __init__( library_status_provider: LibraryStatusProvider = get_library_status, queue_snapshot_provider: QueueSnapshotProvider = get_queue_snapshot, ) -> None: - super().__init__() + super().__init__(ansi_color=True) self.settings = settings self.library_status_provider = library_status_provider self.queue_snapshot_provider = queue_snapshot_provider @@ -180,7 +188,7 @@ def action_refresh_active(self) -> None: self.notify(f"{self.screen.title or 'This section'} has no data to refresh yet.") def action_show_help(self) -> None: - self.notify("1–5 navigate • Tab changes focus • r refreshes Dashboard • q quits", timeout=5) + self.notify("1–5 switch sections • r refreshes Dashboard • q quits", timeout=5) def on_button_pressed(self, event: Button.Pressed) -> None: if event.button.id and event.button.id.startswith("nav-"): diff --git a/src/juice_lyrics/tui/screens/base.py b/src/juice_lyrics/tui/screens/base.py index 725885f..d969826 100644 --- a/src/juice_lyrics/tui/screens/base.py +++ b/src/juice_lyrics/tui/screens/base.py @@ -18,6 +18,12 @@ ) +class NavigationButton(Button): + """Mouse-operable primary navigation excluded from the Tab focus chain.""" + + can_focus = False + + class HubScreen(Screen[None]): """Shared persistent application chrome for primary screens.""" @@ -30,17 +36,17 @@ def compose_content(self) -> Iterable[Widget]: return () def compose(self) -> ComposeResult: - yield Static("999\nJuice WRLD Music Hub", id="brand") + yield Static("999 · Juice WRLD Music Hub", id="brand") with Horizontal(id="primary-navigation"): for section, label in _SECTIONS: - button = Button(label, id=f"nav-{section}") + button = NavigationButton(label, id=f"nav-{section}") if section == self.section: button.add_class("-active") yield button with Container(id="screen-content"): yield Static(self.title, id="screen-title") yield from self.compose_content() - yield Static("1–5 Navigate Tab Focus r Refresh ? Help q Quit", id="status-footer") + 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") diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py index 64eabac..cc33939 100644 --- a/src/juice_lyrics/tui/screens/dashboard.py +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -1,16 +1,27 @@ from __future__ import annotations from collections.abc import Callable, Iterable +from dataclasses import dataclass from typing import Any +from textual import work from textual.containers import Container, Grid 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 +@dataclass(frozen=True, slots=True) +class DashboardSnapshot: + library: LibraryStatus | None + queue: QueueSnapshot | None + library_error: str | None = None + queue_error: str | None = None + + class DashboardScreen(HubScreen): """Read-only summary assembled exclusively from application services.""" @@ -25,6 +36,7 @@ def __init__( self.settings = settings self._library_status_provider = library_status_provider self._queue_snapshot_provider = queue_snapshot_provider + self._refresh_worker: Worker[DashboardSnapshot] | None = None def compose_content(self) -> Iterable[Widget]: with Grid(id="dashboard-panels"): @@ -41,16 +53,49 @@ def on_mount(self) -> None: self.refresh_snapshot() def refresh_snapshot(self) -> None: - self._refresh_library() - self._refresh_queue() + 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_snapshot() - def _refresh_library(self) -> None: - error = self.query_one("#library-error", Static) + @work( + thread=True, + exclusive=True, + group="dashboard-snapshot", + exit_on_error=False, + ) + def _load_snapshot(self) -> DashboardSnapshot: + library = queue = None + library_error = queue_error = None try: - status = self._library_status_provider(self.settings) + library = self._library_status_provider(self.settings) except Exception as exc: + library_error = str(exc) or type(exc).__name__ + try: + queue = self._queue_snapshot_provider() + except Exception as exc: + queue_error = str(exc) or type(exc).__name__ + return DashboardSnapshot(library, queue, library_error, queue_error) + + 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: + self._apply_snapshot(event.worker.result) + elif event.state is WorkerState.ERROR: + message = str(event.worker.error) if event.worker.error else "Unknown worker error" + self._apply_snapshot(DashboardSnapshot(None, None, message, message)) + + def _apply_snapshot(self, snapshot: DashboardSnapshot) -> None: + self._render_library(snapshot.library, snapshot.library_error) + self._render_queue(snapshot.queue, snapshot.queue_error) + + 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") - error.update(f"Warning: {exc}") + error.update(f"Warning: {failure or 'Unknown library status error'}") return lines = ( @@ -66,13 +111,11 @@ def _refresh_library(self) -> None: self.query_one("#library-data", Static).update("\n".join(lines)) error.update("\n".join(status.warnings)) - def _refresh_queue(self) -> None: + def _render_queue(self, snapshot: QueueSnapshot | None, failure: str | None) -> None: error = self.query_one("#queue-error", Static) - try: - snapshot = self._queue_snapshot_provider() - except Exception as exc: + if snapshot is None: self.query_one("#queue-data", Static).update("Queue data unavailable") - error.update(f"Warning: {exc}") + error.update(f"Warning: {failure or 'Unknown queue status error'}") return lines = ( diff --git a/tests/test_tui.py b/tests/test_tui.py index ef9946c..0654925 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -1,6 +1,8 @@ import asyncio from pathlib import Path +import re import sys +from threading import Event sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) @@ -147,18 +149,134 @@ async def scenario(): asyncio.run(scenario()) -def test_navigation_buttons_are_keyboard_focusable(tmp_path): +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 not None - assert app.focused.id and app.focused.id.startswith("nav-") + assert app.focused is None + assert all(not button.can_focus for button in app.query("#primary-navigation Button")) 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("-active") + await pilot.click("#nav-browse") + await pilot.pause() + assert app.screen.id == "screen-browse" + assert app.query_one("#nav-browse").has_class("-active") + assert not app.query_one("#nav-dashboard").has_class("-active") + assert app.focused is None + + 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 "MP3 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 "MP3 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 "MP3 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 "MP3 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") @@ -241,3 +359,15 @@ async def scenario(): 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 From 57d528040995adb86806ffc5d6e54159d0788eec Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 12:35:14 +0100 Subject: [PATCH 17/62] Add responsive terminal-native Textual shell --- src/juice_lyrics/tui/app.py | 28 +++++++++---------- src/juice_lyrics/tui/screens/base.py | 30 ++++++++++++++------ tests/test_tui.py | 41 +++++++++++++++++++++++++--- 3 files changed, 73 insertions(+), 26 deletions(-) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index b58e7ef..4323ec1 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -5,10 +5,10 @@ from textual.app import App from textual.binding import Binding -from textual.widgets import Button from ..services.acquisition_queue import QueueSnapshot, get_queue_snapshot from ..services.library_status import LibraryStatus, get_library_status +from .screens.base import NavigationItem from .screens.dashboard import DashboardScreen from .screens.placeholder import PlaceholderScreen @@ -51,26 +51,27 @@ class JuiceLyricsApp(App[None]): align-horizontal: center; } - #primary-navigation NavigationButton { + #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 NavigationButton:hover { - background: transparent; + #primary-navigation NavigationItem:hover { color: ansi_default; - text-style: underline; + text-style: bold; } - #primary-navigation NavigationButton.-active, - #primary-navigation NavigationButton.-active:hover { - background: ansi_default; - color: ansi_default; - text-style: bold reverse; + #primary-navigation NavigationItem.-current, + #primary-navigation NavigationItem.-current:hover { + color: ansi_blue; + text-style: bold; } #screen-content { @@ -121,7 +122,7 @@ class JuiceLyricsApp(App[None]): text-style: dim; } - Screen.-narrow #primary-navigation NavigationButton { + Screen.-narrow #primary-navigation NavigationItem { min-width: 7; margin: 0; } @@ -190,9 +191,8 @@ def action_refresh_active(self) -> None: def action_show_help(self) -> None: self.notify("1–5 switch sections • r refreshes Dashboard • q quits", timeout=5) - def on_button_pressed(self, event: Button.Pressed) -> None: - if event.button.id and event.button.id.startswith("nav-"): - self.action_show_section(event.button.id.removeprefix("nav-")) + def on_navigation_item_activated(self, event: NavigationItem.Activated) -> None: + self.action_show_section(event.item.section) def run_tui(settings: Any) -> int: diff --git a/src/juice_lyrics/tui/screens/base.py b/src/juice_lyrics/tui/screens/base.py index d969826..f7579f3 100644 --- a/src/juice_lyrics/tui/screens/base.py +++ b/src/juice_lyrics/tui/screens/base.py @@ -4,10 +4,11 @@ from textual.app import ComposeResult from textual.containers import Container, Horizontal -from textual.events import Resize +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 Button, Static +from textual.widgets import Static _SECTIONS = ( ("dashboard", "1 Dashboard"), @@ -18,11 +19,23 @@ ) -class NavigationButton(Button): - """Mouse-operable primary navigation excluded from the Tab focus chain.""" +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.""" @@ -39,10 +52,11 @@ def compose(self) -> ComposeResult: yield Static("999 · Juice WRLD Music Hub", id="brand") with Horizontal(id="primary-navigation"): for section, label in _SECTIONS: - button = NavigationButton(label, id=f"nav-{section}") - if section == self.section: - button.add_class("-active") - yield button + 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() diff --git a/tests/test_tui.py b/tests/test_tui.py index 0654925..b246259 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -9,6 +9,8 @@ from juice_lyrics.config.settings import Settings from juice_lyrics.services import 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: @@ -156,7 +158,7 @@ async def scenario(): await pilot.pause() await pilot.press("tab") assert app.focused is None - assert all(not button.can_focus for button in app.query("#primary-navigation Button")) + assert all(not item.can_focus for item in app.query("#primary-navigation NavigationItem")) asyncio.run(scenario()) @@ -166,12 +168,17 @@ 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("-active") + 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("-active") - assert not app.query_one("#nav-dashboard").has_class("-active") + 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 asyncio.run(scenario()) @@ -371,3 +378,29 @@ def test_ansi_mode_and_tui_styles_avoid_forced_theme_colors(tmp_path): 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 ":focus" not in css + assert "focus-within" not in css + assert "selected" not in css + assert ".-active" not in css From ab5e34e22250a41b69a632b65152dd88f0022b0f Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 29 Aug 2026 12:56:43 +0100 Subject: [PATCH 18/62] Add read-only catalogue Browse screen --- docs/DEVELOPMENT.md | 9 +- src/juice_lyrics/tui/app.py | 115 +++++- src/juice_lyrics/tui/screens/__init__.py | 3 +- src/juice_lyrics/tui/screens/browse.py | 355 +++++++++++++++++++ tests/test_tui.py | 16 +- tests/test_tui_browse.py | 429 +++++++++++++++++++++++ 6 files changed, 911 insertions(+), 16 deletions(-) create mode 100644 src/juice_lyrics/tui/screens/browse.py create mode 100644 tests/test_tui_browse.py diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 7bc3811..585daa3 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -60,8 +60,13 @@ From an editable installation, launch the early read-only TUI shell with: juice-lyrics tui ``` -This milestone provides a dashboard and navigation placeholders only. It does -not download media, sync lyrics, edit settings, or modify the local library. +The experimental shell provides a read-only Dashboard and a functional +read-only Browse screen. Press `/` to focus catalogue search and Enter to +submit. Category and era fields accept API filter values; leave either blank +for All. Use arrows or `j`/`k` to select results and Enter to load full details +and a lyric preview. Global keys remain `1`–`5` for sections, `?` for help, and +`q` to quit. Browse does not download media, create jobs, 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. diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 4323ec1..7eb537f 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -7,13 +7,22 @@ from textual.binding import Binding from ..services.acquisition_queue import QueueSnapshot, get_queue_snapshot +from ..services.catalogue import ( + CatalogueSearchResult, + SongDetails, + get_song_details, + search_catalogue, +) from ..services.library_status import LibraryStatus, get_library_status from .screens.base import NavigationItem +from .screens.browse import BrowseScreen from .screens.dashboard import DashboardScreen from .screens.placeholder import PlaceholderScreen LibraryStatusProvider = Callable[[Any], LibraryStatus] QueueSnapshotProvider = Callable[[], QueueSnapshot] +CatalogueSearchProvider = Callable[..., tuple[CatalogueSearchResult, ...]] +CatalogueDetailsProvider = Callable[..., SongDetails | None] class JuiceLyricsApp(App[None]): @@ -23,11 +32,11 @@ class JuiceLyricsApp(App[None]): 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("1", "show_section('dashboard')", "Dashboard", show=False, priority=True), + Binding("2", "show_section('browse')", "Browse", show=False, priority=True), + Binding("3", "show_section('library')", "Library", show=False, priority=True), + Binding("4", "show_section('downloads')", "Downloads", show=False, priority=True), + Binding("5", "show_section('settings')", "Settings", show=False, priority=True), Binding("r", "refresh_active", "Refresh", show=False), Binding("question_mark", "show_help", "Help", show=False), Binding("q", "quit", "Quit", show=False, priority=True), @@ -108,6 +117,73 @@ class JuiceLyricsApp(App[None]): 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 { + background: transparent; + color: ansi_default; + border: tall ansi_default; + background-tint: transparent; + padding: 0 1; + } + + #browse-controls Input:focus { + background: transparent; + border: tall ansi_blue; + background-tint: transparent; + } + + .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, + #browse-details { + height: auto; + background: transparent; + } + #placeholder-panel { border: round ansi_cyan; padding: 2 3; @@ -135,6 +211,19 @@ class JuiceLyricsApp(App[None]): Screen.-narrow #screen-content { padding: 1; } + + Screen.-narrow #browse-controls { + grid-size: 1 3; + grid-columns: 1fr; + grid-rows: 4 4 4; + overflow-y: auto; + } + + Screen.-narrow #browse-main { + grid-size: 1 2; + grid-columns: 1fr; + grid-rows: 1fr 1fr; + } """ def __init__( @@ -143,11 +232,15 @@ def __init__( *, library_status_provider: LibraryStatusProvider = get_library_status, queue_snapshot_provider: QueueSnapshotProvider = get_queue_snapshot, + catalogue_search_provider: CatalogueSearchProvider = search_catalogue, + catalogue_details_provider: CatalogueDetailsProvider = get_song_details, ) -> 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 def on_mount(self) -> None: self.install_screen( @@ -159,7 +252,11 @@ def on_mount(self) -> None: "dashboard", ) self.install_screen( - PlaceholderScreen("Browse", "Catalogue search and song details are planned for a later milestone."), + BrowseScreen( + self.settings, + search_provider=self.catalogue_search_provider, + details_provider=self.catalogue_details_provider, + ), "browse", ) self.install_screen( @@ -189,7 +286,11 @@ def action_refresh_active(self) -> None: self.notify(f"{self.screen.title or 'This section'} has no data to refresh yet.") def action_show_help(self) -> None: - self.notify("1–5 switch sections • r refreshes Dashboard • q quits", timeout=5) + if self.screen.name == "browse": + message = "/ search • ↑/↓ or j/k select • Enter details • r rerun • 1–5 sections • q quit" + else: + message = "1–5 switch sections • r refreshes Dashboard • q quits" + self.notify(message, timeout=5) def on_navigation_item_activated(self, event: NavigationItem.Activated) -> None: self.action_show_section(event.item.section) diff --git a/src/juice_lyrics/tui/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py index 2e72a38..265901d 100644 --- a/src/juice_lyrics/tui/screens/__init__.py +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -1,6 +1,7 @@ """Screens for the experimental Textual frontend.""" +from .browse import BrowseScreen from .dashboard import DashboardScreen from .placeholder import PlaceholderScreen -__all__ = ["DashboardScreen", "PlaceholderScreen"] +__all__ = ["BrowseScreen", "DashboardScreen", "PlaceholderScreen"] diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py new file mode 100644 index 0000000..cc2d12e --- /dev/null +++ b/src/juice_lyrics/tui/screens/browse.py @@ -0,0 +1,355 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass +from typing import Any + +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 Key, Resize, ScreenResume +from textual.widget import Widget +from textual.widgets import Input, Static +from textual.worker import Worker, WorkerState + +from ...services.catalogue import CatalogueSearchResult, LyricAvailability, SongDetails +from .base import HubScreen + +SearchProvider = Callable[..., tuple[CatalogueSearchResult, ...]] +DetailsProvider = Callable[..., SongDetails | None] +_PREVIEW_LINES = 6 + + +class BrowseInput(Input): + """Filter input that preserves the shell's global numeric navigation.""" + + def on_key(self, event: Key) -> None: + 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 SearchRequest: + query: str + category: str | None + era: str | None + refresh: bool + + +@dataclass(frozen=True, slots=True) +class SearchOutcome: + request: SearchRequest + results: tuple[CatalogueSearchResult, ...] = () + error: str | None = None + + +@dataclass(frozen=True, slots=True) +class DetailsOutcome: + result: CatalogueSearchResult + details: SongDetails | None = None + error: str | None = None + + +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, + ) -> None: + super().__init__("browse", "Browse") + self.settings = settings + self._search_provider = search_provider + self._details_provider = details_provider + self.results: tuple[CatalogueSearchResult, ...] = () + self.selected_index = 0 + self.last_request: SearchRequest | None = None + self._search_worker: Worker[SearchOutcome] | None = None + self._details_worker: Worker[DetailsOutcome] | 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="Song title", id="browse-query") + with Vertical(classes="browse-filter"): + yield Static("Category (All when blank)", classes="filter-label") + yield BrowseInput(placeholder="All", id="browse-category") + with Vertical(classes="browse-filter"): + yield Static("Era (All when blank)", classes="filter-label") + yield BrowseInput(placeholder="All", id="browse-era") + yield Static("Enter a song title and press Enter.", id="browse-status", markup=False) + with Grid(id="browse-main"): + with Container(classes="browse-panel", id="browse-results-panel"): + yield Static("Results", classes="panel-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) + + 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) + + def on_screen_resume(self, event: ScreenResume) -> None: + if self.results: + self.call_after_refresh(self.set_focus, None) + + def submit_search(self, *, refresh: bool) -> None: + query = self.query_one("#browse-query", Input).value.strip() + category = self.query_one("#browse-category", Input).value.strip() or None + era = self.query_one("#browse-era", Input).value.strip() or None + if not query: + self._set_status("Enter a song title before searching.", error=True) + return + + request = SearchRequest(query, category, era, refresh) + self.last_request = request + self.set_focus(None) + self.results = () + self.selected_index = 0 + self.query_one("#browse-results", Static).update("Searching…") + self.query_one("#browse-details", Static).update("Waiting for results…") + self._set_status(self._loading_status(request)) + self._search_worker = self._run_search(request) + + 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", Input).value = self.last_request.category or "" + self.query_one("#browse-era", Input).value = self.last_request.era or "" + self.submit_search(refresh=True) + + @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, + refresh=request.refresh, + ) + return SearchOutcome(request, tuple(results)) + 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") + try: + details = self._details_provider( + self.settings, + request.query, + selection_index=result.selection_index, + refresh=False, + ) + return DetailsOutcome(result, details) + except Exception as exc: + return DetailsOutcome(result, error=str(exc) or type(exc).__name__) + + def on_worker_state_changed(self, event: Worker.StateChanged) -> None: + if 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, False), error="Search worker failed")) + 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.") + + def _apply_search(self, outcome: SearchOutcome) -> None: + if outcome.error: + self.results = () + self.query_one("#browse-results", Static).update("Search unavailable.") + self.query_one("#browse-details", Static).update("No song selected.") + self._set_status(f"Search failed: {outcome.error}", error=True) + return + + self.results = outcome.results + self.selected_index = 0 + if not self.results: + self.query_one("#browse-results", Static).update("No catalogue results found.") + self.query_one("#browse-details", Static).update("Try another title or filter.") + self._set_status(f'No results for "{outcome.request.query}".') + return + + self._render_results() + self._render_summary(self.results[0]) + self._set_status(self._result_status(outcome.request, len(self.results))) + + 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 isinstance(self.app.focused, Input): + 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() + else: + return + event.prevent_default() + event.stop() + + def _move_selection(self, amount: int) -> None: + if not self.results: + return + self.selected_index = max(0, min(len(self.results) - 1, self.selected_index + amount)) + self._render_results() + self._render_summary(self.results[self.selected_index]) + + 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 " " + 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: + lines.extend((f"{marker} {title}", f" {era} · {category} · {lyrics} · {available}")) + else: + length = result.length or "?" + lines.append( + f"{marker} {title[:26]:26} {era[:10]:10} {category[:12]:12} " + f"{length[:7]:7} {lyrics:6} {available}" + ) + self.query_one("#browse-results", Static).update("\n".join(lines)) + + 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.", + ) + 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") + + @staticmethod + def _loading_status(request: SearchRequest) -> str: + filters = _filter_text(request.category, request.era) + return f'Searching for "{request.query}"…{filters}' + + @staticmethod + def _result_status(request: SearchRequest, count: int) -> str: + filters = _filter_text(request.category, request.era) + return f"{count} result(s).{filters} ↑/↓ or j/k select · Enter details" + + def on_resize(self, event: Resize) -> None: + super().on_resize(event) + if self.results: + self._render_results() + + +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 = [] + if category: + values.append(f"category={category}") + if era: + values.append(f"era={era}") + return f" Filters: {', '.join(values)}." if values else " Filters: All." + + +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/tests/test_tui.py b/tests/test_tui.py index b246259..13b5abb 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -139,7 +139,11 @@ async def scenario(): app = _app(tmp_path) async with app.run_test() as pilot: await pilot.pause() - for key, section in zip("2345", ("browse", "library", "downloads", "settings")): + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + assert app.query_one("#browse-query") is not None + for key, section in zip("345", ("library", "downloads", "settings")): await pilot.press(key) await pilot.pause() assert app.screen.id == f"screen-{section}" @@ -179,7 +183,7 @@ async def scenario(): 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 + assert app.focused is app.query_one("#browse-query") asyncio.run(scenario()) @@ -400,7 +404,7 @@ def test_active_navigation_uses_plain_static_widget_and_ansi_text_only(tmp_path) assert "text-style: bold" in active_rule assert "underline" not in css assert "reverse" not in active_rule - assert ":focus" not in css - assert "focus-within" not in css - assert "selected" not in css - assert ".-active" not in css + 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..a84ec3b --- /dev/null +++ b/tests/test_tui_browse.py @@ -0,0 +1,429 @@ +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.widgets import Input + +from juice_lyrics.config.settings import Settings +from juice_lyrics.services import LibraryStatus, QueueSnapshot +from juice_lyrics.services.catalogue import ( + CatalogueSearchResult, + LyricAvailability, + SongDetails, +) +from juice_lyrics.tui import JuiceLyricsApp + + +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) -> 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), + ) + + +def _text(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +async def _open_browse(app: JuiceLyricsApp, pilot): + await pilot.press("2") + await pilot.pause() + return app.screen + + +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 song title" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +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", Input).value = "unreleased" + app.query_one("#browse-era", Input).value = "DRFL" + await _submit(app, pilot, "rental") + + assert calls == [("rental", {"category": "unreleased", "era": "DRFL", "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 == [("songs", {"selection_index": 2, "refresh": False})] + 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, "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")) From d0cc2d33b7e85b5ba103e278e79dc69ab6f507ce Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 00:47:41 +0100 Subject: [PATCH 19/62] Fix catalogue filters and add Browse pagination --- docs/DEVELOPMENT.md | 13 +- src/juice_lyrics/api/client.py | 92 ++++- src/juice_lyrics/cli.py | 16 +- src/juice_lyrics/services/__init__.py | 12 + src/juice_lyrics/services/catalogue.py | 141 ++++++- src/juice_lyrics/tui/app.py | 42 ++- src/juice_lyrics/tui/screens/browse.py | 218 +++++++++-- tests/fixtures/catalogue/categories.json | 8 + tests/fixtures/catalogue/eras_page_1.json | 19 + tests/fixtures/catalogue/eras_page_2.json | 13 + .../songs_unreleased_drfl_page_2.json | 24 ++ tests/test_api_catalogue.py | 95 +++++ tests/test_catalogue_service.py | 111 +++++- tests/test_tui.py | 3 +- tests/test_tui_browse.py | 357 +++++++++++++++++- 15 files changed, 1085 insertions(+), 79 deletions(-) create mode 100644 tests/fixtures/catalogue/categories.json create mode 100644 tests/fixtures/catalogue/eras_page_1.json create mode 100644 tests/fixtures/catalogue/eras_page_2.json create mode 100644 tests/fixtures/catalogue/songs_unreleased_drfl_page_2.json create mode 100644 tests/test_api_catalogue.py diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 585daa3..eee7f57 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -62,11 +62,14 @@ juice-lyrics tui The experimental shell provides a read-only Dashboard and a functional read-only Browse screen. Press `/` to focus catalogue search and Enter to -submit. Category and era fields accept API filter values; leave either blank -for All. Use arrows or `j`/`k` to select results and Enter to load full details -and a lyric preview. Global keys remain `1`–`5` for sections, `?` for help, and -`q` to quit. Browse does not download media, create jobs, sync lyrics, edit -settings, or modify the local library. +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 the visible range and total. Use `n` or +PageDown for the next page, `p` or PageUp for the previous page, and Home for +page one. Arrows or `j`/`k` select results, Enter loads full details and a lyric +preview, and `r` refreshes the current page. Global keys remain `1`–`5` for +sections, `?` for help, and `q` to quit. Browse does not download media, create +jobs, 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. 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/cli.py b/src/juice_lyrics/cli.py index 23b12c6..c92cb06 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -232,8 +232,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: @@ -719,8 +719,16 @@ def search_api(settings: Settings, title: str, refresh: bool = False) -> list[di 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]: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 64a6260..f33d472 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -10,11 +10,17 @@ 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 .library_status import LibraryStatus, get_library_status from .library_sync import ( @@ -34,6 +40,9 @@ __all__ = [ "CatalogueSearchResult", + "CatalogueFilterMetadata", + "CatalogueFilterOption", + "CataloguePage", "LibraryStatus", "LibrarySyncDependencies", "LibrarySyncOptions", @@ -53,10 +62,13 @@ "TrackSyncPlan", "TrackSyncResult", "execute_library_sync", + "get_catalogue_filters", "get_queue_snapshot", "get_library_status", "get_song_details", + "get_song_details_by_id", "plan_library_sync", "search_catalogue", + "search_catalogue_page", "resolve_queue_reference", ] diff --git a/src/juice_lyrics/services/catalogue.py b/src/juice_lyrics/services/catalogue.py index 3e998c0..0a08b91 100644 --- a/src/juice_lyrics/services/catalogue.py +++ b/src/juice_lyrics/services/catalogue.py @@ -7,13 +7,21 @@ from typing import Any from ..acquisition.resolver import ResourceResolutionError, resolve_resource -from ..api.client import get_song, search_song_names, search_songs +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 @@ -38,6 +46,37 @@ class CatalogueSearchResult: downloadable: bool +@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 @@ -147,16 +186,42 @@ def search_catalogue( ) -> 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, ) - raw_results = response.get("results", []) if isinstance(response, Mapping) else [] + 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)): - return () + raw_results = () results: list[CatalogueSearchResult] = [] for index, record in enumerate(raw_results, start=1): @@ -166,7 +231,75 @@ def search_catalogue( fields.pop("synced_lyrics") fields.pop("plain_lyrics") results.append(CatalogueSearchResult(selection_index=index, **fields)) - return tuple(results) + 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( diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 7eb537f..dee66cb 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -8,10 +8,12 @@ from ..services.acquisition_queue import QueueSnapshot, get_queue_snapshot from ..services.catalogue import ( - CatalogueSearchResult, + CatalogueFilterMetadata, + CataloguePage, SongDetails, - get_song_details, - search_catalogue, + get_catalogue_filters, + get_song_details_by_id, + search_catalogue_page, ) from ..services.library_status import LibraryStatus, get_library_status from .screens.base import NavigationItem @@ -21,8 +23,9 @@ LibraryStatusProvider = Callable[[Any], LibraryStatus] QueueSnapshotProvider = Callable[[], QueueSnapshot] -CatalogueSearchProvider = Callable[..., tuple[CatalogueSearchResult, ...]] +CatalogueSearchProvider = Callable[..., CataloguePage] CatalogueDetailsProvider = Callable[..., SongDetails | None] +CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] class JuiceLyricsApp(App[None]): @@ -130,7 +133,8 @@ class JuiceLyricsApp(App[None]): height: 4; } - #browse-controls Input { + #browse-controls Input, + #browse-controls SelectCurrent { background: transparent; color: ansi_default; border: tall ansi_default; @@ -138,12 +142,29 @@ class JuiceLyricsApp(App[None]): padding: 0 1; } - #browse-controls Input:focus { + #browse-controls Input:focus, + #browse-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 .option-list--option-highlighted { + background: transparent; + color: ansi_blue; + text-style: bold; + } + .filter-label { height: 1; text-style: dim; @@ -232,8 +253,9 @@ def __init__( *, library_status_provider: LibraryStatusProvider = get_library_status, queue_snapshot_provider: QueueSnapshotProvider = get_queue_snapshot, - catalogue_search_provider: CatalogueSearchProvider = search_catalogue, - catalogue_details_provider: CatalogueDetailsProvider = get_song_details, + catalogue_search_provider: CatalogueSearchProvider = search_catalogue_page, + catalogue_details_provider: CatalogueDetailsProvider = get_song_details_by_id, + catalogue_filters_provider: CatalogueFiltersProvider = get_catalogue_filters, ) -> None: super().__init__(ansi_color=True) self.settings = settings @@ -241,6 +263,7 @@ def __init__( 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 def on_mount(self) -> None: self.install_screen( @@ -256,6 +279,7 @@ def on_mount(self) -> None: self.settings, search_provider=self.catalogue_search_provider, details_provider=self.catalogue_details_provider, + filters_provider=self.catalogue_filters_provider, ), "browse", ) @@ -287,7 +311,7 @@ def action_refresh_active(self) -> None: def action_show_help(self) -> None: if self.screen.name == "browse": - message = "/ search • ↑/↓ or j/k select • Enter details • r rerun • 1–5 sections • q quit" + message = "/ search • ↑/↓ select • Enter details • n/p pages • r refresh • 1–5 sections • q quit" else: message = "1–5 switch sections • r refreshes Dashboard • q quits" self.notify(message, timeout=5) diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py index cc2d12e..0195c24 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -10,15 +10,23 @@ from textual.containers import Container, Grid, Vertical, VerticalScroll from textual.events import Key, Resize, ScreenResume from textual.widget import Widget -from textual.widgets import Input, Static +from textual.widgets import Input, Select, Static from textual.worker import Worker, WorkerState -from ...services.catalogue import CatalogueSearchResult, LyricAvailability, SongDetails +from ...services.catalogue import ( + CatalogueFilterMetadata, + CataloguePage, + CatalogueSearchResult, + LyricAvailability, + SongDetails, +) from .base import HubScreen -SearchProvider = Callable[..., tuple[CatalogueSearchResult, ...]] +SearchProvider = Callable[..., CataloguePage | tuple[CatalogueSearchResult, ...]] DetailsProvider = Callable[..., SongDetails | None] +FiltersProvider = Callable[..., CatalogueFilterMetadata] _PREVIEW_LINES = 6 +_PAGE_SIZE = 50 class BrowseInput(Input): @@ -37,18 +45,35 @@ def on_key(self, event: Key) -> None: event.stop() +class BrowseSelect(Select[str]): + """Catalogue selector that preserves global section shortcuts.""" + + def on_key(self, event: Key) -> None: + 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 SearchRequest: query: str category: str | None era: str | None + page: int refresh: bool @dataclass(frozen=True, slots=True) class SearchOutcome: request: SearchRequest - results: tuple[CatalogueSearchResult, ...] = () + page: CataloguePage | None = None error: str | None = None @@ -59,6 +84,12 @@ class DetailsOutcome: error: str | None = None +@dataclass(frozen=True, slots=True) +class FiltersOutcome: + metadata: CatalogueFilterMetadata | None = None + error: str | None = None + + class BrowseScreen(HubScreen): """Interactive, read-only catalogue search and song-details screen.""" @@ -70,29 +101,34 @@ def __init__( *, search_provider: SearchProvider, details_provider: DetailsProvider, + filters_provider: FiltersProvider, ) -> None: super().__init__("browse", "Browse") self.settings = settings self._search_provider = search_provider self._details_provider = details_provider + self._filters_provider = filters_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._applying_filters = False 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="Song title", id="browse-query") + yield BrowseInput(placeholder="Optional song title", id="browse-query") with Vertical(classes="browse-filter"): - yield Static("Category (All when blank)", classes="filter-label") - yield BrowseInput(placeholder="All", id="browse-category") + 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 (All when blank)", classes="filter-label") - yield BrowseInput(placeholder="All", id="browse-era") - yield Static("Enter a song title and press Enter.", id="browse-status", markup=False) + 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", classes="panel-title") @@ -109,22 +145,32 @@ def action_focus_search(self) -> None: def on_input_submitted(self, event: Input.Submitted) -> None: self.submit_search(refresh=False) + 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() if self.results: self.call_after_refresh(self.set_focus, None) def submit_search(self, *, refresh: bool) -> None: query = self.query_one("#browse-query", Input).value.strip() - category = self.query_one("#browse-category", Input).value.strip() or None - era = self.query_one("#browse-era", Input).value.strip() or None - if not query: - self._set_status("Enter a song title before searching.", error=True) + 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, refresh) + request = SearchRequest(query, category, era, 1, refresh) + self._start_search(request) + + def _start_search(self, request: SearchRequest) -> None: 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-details", Static).update("Waiting for results…") @@ -136,9 +182,22 @@ def refresh_snapshot(self) -> None: self.submit_search(refresh=True) return self.query_one("#browse-query", Input).value = self.last_request.query - self.query_one("#browse-category", Input).value = self.last_request.category or "" - self.query_one("#browse-era", Input).value = self.last_request.era or "" - self.submit_search(refresh=True) + 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: @@ -148,9 +207,16 @@ def _run_search(self, request: SearchRequest) -> SearchOutcome: request.query, category=request.category, era=request.era, + page=request.page, + page_size=_PAGE_SIZE, refresh=request.refresh, ) - return SearchOutcome(request, tuple(results)) + 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__) @@ -159,23 +225,32 @@ 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, - request.query, + result.song_id, selection_index=result.selection_index, - refresh=False, ) return DetailsOutcome(result, details) except Exception as exc: return DetailsOutcome(result, error=str(exc) or type(exc).__name__) def on_worker_state_changed(self, event: Worker.StateChanged) -> None: - if event.worker is self._search_worker: + 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 metadata worker failed")) + 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, False), error="Search worker failed")) + self._apply_search(SearchOutcome( + self.last_request or SearchRequest("", None, None, 1, False), + error="Search worker failed", + )) elif event.worker is self._details_worker: if event.state is WorkerState.SUCCESS: self._apply_details(event.worker.result) @@ -185,22 +260,47 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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-details", Static).update("No song selected.") self._set_status(f"Search failed: {outcome.error}", error=True) return - self.results = outcome.results + 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 if not self.results: self.query_one("#browse-results", Static).update("No catalogue results found.") - self.query_one("#browse-details", Static).update("Try another title or filter.") - self._set_status(f'No results for "{outcome.request.query}".') + 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(_empty_result_status(outcome.request)) return self._render_results() self._render_summary(self.results[0]) - self._set_status(self._result_status(outcome.request, len(self.results))) + self._set_status(self._result_status(outcome.request, page)) + + 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: @@ -213,7 +313,9 @@ def _apply_details(self, outcome: DetailsOutcome) -> None: self.query_one("#browse-details", Static).update(self._details_text(outcome.details)) def on_key(self, event: Key) -> None: - if isinstance(self.app.focused, Input): + 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) @@ -221,11 +323,43 @@ def on_key(self, event: Key) -> None: self._move_selection(-1) elif event.key == "enter": self._load_selected_details() + elif event.key in ("n", "pagedown"): + self._change_page(next_page=True) + elif event.key in ("p", "pageup"): + self._change_page(next_page=False) + elif event.key == "home": + self._first_page() else: return event.prevent_default() event.stop() + 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 _first_page(self) -> None: + if self.last_request is None or self.last_request.page == 1: + return + self._start_search(SearchRequest( + self.last_request.query, + self.last_request.category, + self.last_request.era, + 1, + False, + )) + def _move_selection(self, amount: int) -> None: if not self.results: return @@ -310,13 +444,15 @@ def _set_status(self, message: str, *, error: bool = False) -> None: @staticmethod def _loading_status(request: SearchRequest) -> str: - filters = _filter_text(request.category, request.era) - return f'Searching for "{request.query}"…{filters}' + if request.query: + return f'Searching for "{request.query}"…{_filter_text(request.category, request.era)}' + return f"Searching: {_filter_values(request.category, request.era)}…" @staticmethod - def _result_status(request: SearchRequest, count: int) -> str: + def _result_status(request: SearchRequest, page: CataloguePage) -> str: filters = _filter_text(request.category, request.era) - return f"{count} result(s).{filters} ↑/↓ or j/k select · Enter details" + location = f"Page {page.page} · Showing {page.range_start}–{page.range_end} of {page.total_count}" + return f"{location}.{filters} ↑/↓ select · n/p pages · Enter details" def on_resize(self, event: Resize) -> None: super().on_resize(event) @@ -333,12 +469,28 @@ def _lyrics_label(value: LyricAvailability) -> str: 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 f" Filters: {', '.join(values)}." if values else " Filters: All." + 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: 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_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_catalogue_service.py b/tests/test_catalogue_service.py index 2d0c9f1..bca9159 100644 --- a/tests/test_catalogue_service.py +++ b/tests/test_catalogue_service.py @@ -1,3 +1,4 @@ +import json from pathlib import Path import sys @@ -7,9 +8,14 @@ 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, ) @@ -30,7 +36,38 @@ def searcher(settings, query, **kwargs): ) assert results == () - assert calls == [("rental", {"category": "unreleased", "era": "DRFL", "refresh": True})] + 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): @@ -80,6 +117,78 @@ def test_search_normalizes_shapes_lyrics_and_downloadability(tmp_path): 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_search_handles_malformed_optional_metadata_without_writes(tmp_path): settings = Settings(music_dir=tmp_path / "does-not-exist") record = { diff --git a/tests/test_tui.py b/tests/test_tui.py index 13b5abb..41e2313 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -7,7 +7,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) from juice_lyrics.config.settings import Settings -from juice_lyrics.services import LibraryStatus, QueueSnapshot +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 @@ -47,6 +47,7 @@ def _app(tmp_path: Path, *, library=None, queue=None) -> 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((), ()), ) diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index a84ec3b..77eca48 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -5,12 +5,15 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) -from textual.widgets import Input +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, ) @@ -62,7 +65,7 @@ def _details( ) -def _app(tmp_path: Path, *, search, details=None) -> JuiceLyricsApp: +def _app(tmp_path: Path, *, search, details=None, filters=None) -> JuiceLyricsApp: return JuiceLyricsApp( Settings(music_dir=tmp_path / "music"), library_status_provider=lambda settings: LibraryStatus( @@ -71,6 +74,16 @@ def _app(tmp_path: Path, *, search, details=None) -> JuiceLyricsApp: 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), + ), + )), ) @@ -110,11 +123,175 @@ async def scenario(): await pilot.press("enter") await pilot.pause() assert calls == [] - assert "Enter a song title" in _text(app, "#browse-status") + 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")) @@ -127,11 +304,11 @@ 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", Input).value = "unreleased" - app.query_one("#browse-era", Input).value = "DRFL" + app.query_one("#browse-category", Select).value = "unreleased" + app.query_one("#browse-era", Select).value = "DRFL" await _submit(app, pilot, "rental") - assert calls == [("rental", {"category": "unreleased", "era": "DRFL", "refresh": False})] + 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") @@ -300,7 +477,7 @@ async def scenario(): assert worker is not None await worker.wait() await pilot.pause() - assert detail_calls == [("songs", {"selection_index": 2, "refresh": False})] + assert detail_calls == [(2, {"selection_index": 2})] assert "[00:01.00] selected lyric" in _text(app, "#browse-details") asyncio.run(scenario()) @@ -378,7 +555,7 @@ async def scenario(): assert worker is not None await worker.wait() await pilot.pause() - assert calls[-1] == ("persist", {"category": None, "era": None, "refresh": True}) + assert calls[-1] == ("persist", {"category": None, "era": None, "page": 1, "page_size": 50, "refresh": True}) asyncio.run(scenario()) @@ -427,3 +604,167 @@ async def scenario(): 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 "Page 1 · Showing 1–50 of 75" in _text(app, "#browse-status") + + await pilot.press("n") + await app.screen._search_worker.wait() + await pilot.pause() + assert "Page 2 · Showing 51–75 of 75" in _text(app, "#browse-status") + 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 app.screen._search_worker.wait() + await pilot.pause() + assert "Page 1 · Showing 1–50 of 75" in _text(app, "#browse-status") + + asyncio.run(scenario()) + + +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()) From fecfc83ebd9ac7a4b5c416566e9fa13d7d684ea9 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 01:07:38 +0100 Subject: [PATCH 20/62] Add paginated catalogue Browse screen --- docs/DEVELOPMENT.md | 14 +-- src/juice_lyrics/tui/app.py | 72 +++++++++++-- src/juice_lyrics/tui/screens/base.py | 1 + src/juice_lyrics/tui/screens/browse.py | 136 +++++++++++++++++++++---- tests/test_tui_browse.py | 111 +++++++++++++++++++- 5 files changed, 298 insertions(+), 36 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index eee7f57..efb6e4a 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -64,12 +64,14 @@ The experimental shell provides a read-only Dashboard and a functional read-only Browse screen. 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 the visible range and total. Use `n` or -PageDown for the next page, `p` or PageUp for the previous page, and Home for -page one. Arrows or `j`/`k` select results, Enter loads full details and a lyric -preview, and `r` refreshes the current page. Global keys remain `1`–`5` for -sections, `?` for help, and `q` to quit. Browse does not download media, create -jobs, sync lyrics, edit settings, or modify the local library. +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. Global keys remain `1`–`5` for sections, `?` for help, and `q` +to quit. Browse does not download media, create jobs, 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. diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index dee66cb..63c3988 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -199,12 +199,59 @@ class JuiceLyricsApp(App[None]): 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-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; + } + #placeholder-panel { border: round ansi_cyan; padding: 2 3; @@ -234,16 +281,29 @@ class JuiceLyricsApp(App[None]): } Screen.-narrow #browse-controls { - grid-size: 1 3; - grid-columns: 1fr; - grid-rows: 4 4 4; - overflow-y: auto; + 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: 1fr 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; } """ @@ -311,7 +371,7 @@ def action_refresh_active(self) -> None: def action_show_help(self) -> None: if self.screen.name == "browse": - message = "/ search • ↑/↓ select • Enter details • n/p pages • r refresh • 1–5 sections • q quit" + message = "/ search • ↑/↓ or j/k select • PgUp/PgDn list • Home/End • n/p pages • r refresh" else: message = "1–5 switch sections • r refreshes Dashboard • q quits" self.notify(message, timeout=5) diff --git a/src/juice_lyrics/tui/screens/base.py b/src/juice_lyrics/tui/screens/base.py index f7579f3..d1dd4f1 100644 --- a/src/juice_lyrics/tui/screens/base.py +++ b/src/juice_lyrics/tui/screens/base.py @@ -64,3 +64,4 @@ def compose(self) -> ComposeResult: 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 index 0195c24..090f745 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -2,13 +2,17 @@ from collections.abc import Callable, Iterable from dataclasses import dataclass +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 Key, Resize, ScreenResume +from textual.events import Click, Key, Resize, ScreenResume +from textual.geometry import Region +from textual.message import Message from textual.widget import Widget from textual.widgets import Input, Select, Static from textual.worker import Worker, WorkerState @@ -61,6 +65,33 @@ def on_key(self, event: Key) -> None: 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(f"[{self.label}]" if available else 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 @@ -131,13 +162,17 @@ def compose_content(self) -> Iterable[Widget]: 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", classes="panel-title") + 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") def action_focus_search(self) -> None: self.query_one("#browse-query", Input).focus() @@ -173,7 +208,10 @@ def _start_search(self, request: SearchRequest) -> None: 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) self._set_status(self._loading_status(request)) self._search_worker = self._run_search(request) @@ -262,7 +300,9 @@ def _apply_search(self, outcome: SearchOutcome) -> None: 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 @@ -270,6 +310,8 @@ def _apply_search(self, outcome: SearchOutcome) -> None: self.current_page = page self.results = page.results self.selected_index = 0 + self.query_one("#browse-results-title", Static).update(f"Results · {len(self.results)} loaded") + self._update_pagination(page) if not self.results: self.query_one("#browse-results", Static).update("No catalogue results found.") if outcome.request.page > 1: @@ -283,6 +325,7 @@ def _apply_search(self, outcome: SearchOutcome) -> None: self._render_results() self._render_summary(self.results[0]) self._set_status(self._result_status(outcome.request, page)) + self.call_after_refresh(self._scroll_selection_into_view) def _apply_filters(self, outcome: FiltersOutcome) -> None: category = self.query_one("#browse-category", Select) @@ -323,12 +366,18 @@ def on_key(self, event: Key) -> None: self._move_selection(-1) elif event.key == "enter": self._load_selected_details() - elif event.key in ("n", "pagedown"): + elif event.key == "n": self._change_page(next_page=True) - elif event.key in ("p", "pageup"): + 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._first_page() + self._select_index(0) + elif event.key == "end": + self._select_index(len(self.results) - 1) else: return event.prevent_default() @@ -349,23 +398,42 @@ def _change_page(self, *, next_page: bool) -> None: False, )) - def _first_page(self) -> None: - if self.last_request is None or self.last_request.page == 1: - return - self._start_search(SearchRequest( - self.last_request.query, - self.last_request.category, - self.last_request.era, - 1, - 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.selected_index = max(0, min(len(self.results) - 1, self.selected_index + amount)) + 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]) + 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: @@ -392,7 +460,33 @@ def _render_results(self) -> None: f"{marker} {title[:26]:26} {era[:10]:10} {category[:12]:12} " f"{length[:7]:7} {lyrics:6} {available}" ) - self.query_one("#browse-results", Static).update("\n".join(lines)) + 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" @@ -448,16 +542,16 @@ def _loading_status(request: SearchRequest) -> str: return f'Searching for "{request.query}"…{_filter_text(request.category, request.era)}' return f"Searching: {_filter_values(request.category, request.era)}…" - @staticmethod - def _result_status(request: SearchRequest, page: CataloguePage) -> str: + def _result_status(self, request: SearchRequest, page: CataloguePage) -> str: filters = _filter_text(request.category, request.era) - location = f"Page {page.page} · Showing {page.range_start}–{page.range_end} of {page.total_count}" - return f"{location}.{filters} ↑/↓ select · n/p pages · Enter details" + selected = min(len(page.results), self.selected_index + 1) + return f"Result {selected} of {len(page.results)} loaded.{filters} ↑/↓ select · Enter details" def on_resize(self, event: Resize) -> None: super().on_resize(event) if self.results: self._render_results() + self.call_after_refresh(self._scroll_selection_into_view) def _lyrics_label(value: LyricAvailability) -> str: diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index 77eca48..c03287c 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -5,6 +5,7 @@ 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 @@ -629,12 +630,18 @@ async def scenario(): async with app.run_test(size=(120, 32)) as pilot: await _open_browse(app, pilot) await _submit(app, pilot, "page") - assert "Page 1 · Showing 1–50 of 75" in _text(app, "#browse-status") + 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 · Showing 51–75 of 75" in _text(app, "#browse-status") + 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() @@ -651,13 +658,111 @@ async def scenario(): 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 + + 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 "Page 1 · Showing 1–50 of 75" in _text(app, "#browse-status") + 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_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 = [] From 1c38e180b6610b3733534e34f638ed8b5a698f3d Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 01:12:57 +0100 Subject: [PATCH 21/62] Add paginated catalogue Browse screen --- src/juice_lyrics/tui/app.py | 8 ++++++-- src/juice_lyrics/tui/screens/browse.py | 7 +++++-- tests/test_tui_browse.py | 22 ++++++++++++++++++++++ 3 files changed, 33 insertions(+), 4 deletions(-) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 63c3988..81c0249 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -370,8 +370,12 @@ def action_refresh_active(self) -> None: self.notify(f"{self.screen.title or 'This section'} has no data to refresh yet.") def action_show_help(self) -> None: - if self.screen.name == "browse": - message = "/ search • ↑/↓ or j/k select • PgUp/PgDn list • Home/End • n/p pages • r refresh" + if getattr(self.screen, "section", None) == "browse": + message = ( + "n next catalogue page • p previous catalogue page • " + "PageDown/PageUp scroll the loaded results • " + "Home/End first/last loaded result • j/k select • Enter details" + ) else: message = "1–5 switch sections • r refreshes Dashboard • q quits" self.notify(message, timeout=5) diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py index 090f745..0975e68 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -85,7 +85,7 @@ def set_available(self, available: bool) -> None: self.available = available self.set_class(available, "-available") self.set_class(not available, "-unavailable") - self.update(f"[{self.label}]" if available else self.label) + self.update(Text(f"[{self.label}]")) def on_click(self, event: Click) -> None: if self.available: @@ -545,7 +545,10 @@ def _loading_status(request: SearchRequest) -> str: 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) - return f"Result {selected} of {len(page.results)} loaded.{filters} ↑/↓ select · Enter details" + return ( + f"Result {selected} of {len(page.results)} loaded · n/p pages · " + f"j/k select · PgUp/PgDn scroll · Enter details.{filters}" + ) def on_resize(self, event: Resize) -> None: super().on_resize(event) diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index c03287c..ae4a948 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -690,6 +690,9 @@ async def scenario(): 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 "n/p pages" in _text(app, "#browse-status") for _ in range(34): await pilot.press("down") @@ -740,6 +743,25 @@ async def scenario(): asyncio.run(scenario()) +def test_browse_help_distinguishes_loaded_result_scrolling_from_api_pages(tmp_path): + messages = [] + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: ()) + app.notify = lambda message, **kwargs: messages.append(message) + async with app.run_test(size=(80, 24)) as pilot: + await _open_browse(app, pilot) + app.action_show_help() + assert messages + help_text = messages[-1] + assert "n next catalogue page" in help_text + assert "p previous catalogue page" in help_text + assert "PageDown/PageUp scroll the loaded results" in help_text + assert "Home/End first/last loaded result" in help_text + + asyncio.run(scenario()) + + 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)) From 093fabeb88b7c3b9178265ff47c3f82748b9a690 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 01:39:00 +0100 Subject: [PATCH 22/62] Add read-only Downloads screen --- docs/DEVELOPMENT.md | 10 +- src/juice_lyrics/services/__init__.py | 2 + .../services/acquisition_queue.py | 74 ++- src/juice_lyrics/tui/app.py | 83 +++- src/juice_lyrics/tui/screens/__init__.py | 3 +- src/juice_lyrics/tui/screens/downloads.py | 343 ++++++++++++++ tests/test_acquisition_queue_service.py | 26 +- tests/test_tui.py | 8 +- tests/test_tui_downloads.py | 440 ++++++++++++++++++ 9 files changed, 979 insertions(+), 10 deletions(-) create mode 100644 src/juice_lyrics/tui/screens/downloads.py create mode 100644 tests/test_tui_downloads.py diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index efb6e4a..7d5cd70 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -60,8 +60,8 @@ From an editable installation, launch the early read-only TUI shell with: juice-lyrics tui ``` -The experimental shell provides a read-only Dashboard and a functional -read-only Browse screen. Press `/` to focus catalogue search and Enter to +The experimental shell provides a read-only Dashboard plus functional, +read-only Browse and Downloads screens. 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 @@ -76,6 +76,12 @@ 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, use arrows or `j`/`k` to select a job, Home/End for the first or +last job, and PageUp/PageDown to move through longer job lists. Enter opens the +selected job's scrollable track details and Escape returns to the job list. +Press `r` to refresh the read-only queue snapshot. Run, Retry, Delete, Cancel, +and Download actions are intentionally unavailable in this milestone. + ## Source of truth and Git workflow 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. diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index f33d472..11ce32c 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -1,6 +1,7 @@ """Application services shared by command-line and interactive frontends.""" from .acquisition_queue import ( + QueueFailureStage, QueueItem, QueueJob, QueueReferenceError, @@ -51,6 +52,7 @@ "LyricAvailability", "MatchOutcome", "QueueItem", + "QueueFailureStage", "QueueJob", "QueueReferenceError", "QueueSnapshot", diff --git a/src/juice_lyrics/services/acquisition_queue.py b/src/juice_lyrics/services/acquisition_queue.py index 77bffc8..e860b76 100644 --- a/src/juice_lyrics/services/acquisition_queue.py +++ b/src/juice_lyrics/services/acquisition_queue.py @@ -1,5 +1,6 @@ from __future__ import annotations +import hashlib import json from collections.abc import Mapping, Sequence from dataclasses import dataclass @@ -8,7 +9,7 @@ from typing import Any from ..acquisition.jobs import DEFAULT_JOBS_FILE, JobStoreError -from ..acquisition.models import AcquisitionState +from ..acquisition.models import AcquisitionFailureStage, AcquisitionState class QueueStatus(str, Enum): @@ -23,6 +24,15 @@ class QueueStatus(str, Enum): 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 @@ -34,6 +44,8 @@ class QueueItem: resumed: bool error: str | None retryable: bool + failure_stage: QueueFailureStage | None = None + postprocessing_retryable: bool = False @dataclass(frozen=True, slots=True) @@ -53,6 +65,7 @@ class QueueJob: retryable: bool deletion_allowed: bool items: tuple[QueueItem, ...] + updated_at: str | None = None @dataclass(frozen=True, slots=True) @@ -125,17 +138,66 @@ def _item_status(value: Any) -> tuple[QueueStatus, str]: 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=Path(destination_text) if destination_text else None, + destination=destination, status=status, stored_state=stored_state, bytes_written=_nonnegative_int(record.get("bytes_written")), @@ -143,6 +205,13 @@ def _queue_item(raw: Any) -> QueueItem: 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, + ), ) @@ -234,6 +303,7 @@ def get_queue_snapshot(path: Path = DEFAULT_JOBS_FILE) -> QueueSnapshot: item.stored_state in _DELETE_BLOCKING_STORED_STATES for item in items ), items=items, + updated_at=_text(raw.get("updated_at")), ) ) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 81c0249..80fd1bf 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -19,6 +19,7 @@ from .screens.base import NavigationItem from .screens.browse import BrowseScreen from .screens.dashboard import DashboardScreen +from .screens.downloads import DownloadsScreen from .screens.placeholder import PlaceholderScreen LibraryStatusProvider = Callable[[Any], LibraryStatus] @@ -252,6 +253,54 @@ class JuiceLyricsApp(App[None]): color: ansi_default; } + #downloads-summary { + height: 2; + padding: 0 1; + text-style: bold; + } + + #downloads-status, + #downloads-position { + height: 2; + padding: 0 1; + } + + #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-jobs-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-jobs, + #download-details { + height: auto; + background: transparent; + } + #placeholder-panel { border: round ansi_cyan; padding: 2 3; @@ -305,6 +354,28 @@ class JuiceLyricsApp(App[None]): 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-jobs-panel { + display: none; + } + + Screen.-short #downloads-summary, + Screen.-short #downloads-status, + Screen.-short #downloads-position, + Screen.-short .downloads-panel .panel-title { + height: 1; + } """ def __init__( @@ -316,6 +387,7 @@ def __init__( 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: QueueSnapshotProvider | None = None, ) -> None: super().__init__(ansi_color=True) self.settings = settings @@ -324,6 +396,7 @@ def __init__( self.catalogue_search_provider = catalogue_search_provider self.catalogue_details_provider = catalogue_details_provider self.catalogue_filters_provider = catalogue_filters_provider + self.downloads_queue_provider = downloads_queue_provider or queue_snapshot_provider def on_mount(self) -> None: self.install_screen( @@ -348,7 +421,7 @@ def on_mount(self) -> None: "library", ) self.install_screen( - PlaceholderScreen("Downloads", "Queue details and acquisition actions are planned for a later milestone."), + DownloadsScreen(queue_provider=self.downloads_queue_provider), "downloads", ) self.install_screen( @@ -370,12 +443,18 @@ def action_refresh_active(self) -> None: self.notify(f"{self.screen.title or 'This section'} has no data to refresh yet.") def action_show_help(self) -> None: - if getattr(self.screen, "section", None) == "browse": + section = getattr(self.screen, "section", None) + if section == "browse": message = ( "n next catalogue page • p previous catalogue page • " "PageDown/PageUp scroll the loaded results • " "Home/End first/last loaded result • j/k select • Enter details" ) + elif section == "downloads": + message = ( + "↑/↓ or j/k select jobs • Home/End first/last job • " + "PgUp/PgDn move jobs • Enter track details • Esc job list • r refresh" + ) else: message = "1–5 switch sections • r refreshes Dashboard • q quits" self.notify(message, timeout=5) diff --git a/src/juice_lyrics/tui/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py index 265901d..8f967b9 100644 --- a/src/juice_lyrics/tui/screens/__init__.py +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -2,6 +2,7 @@ from .browse import BrowseScreen from .dashboard import DashboardScreen +from .downloads import DownloadsScreen from .placeholder import PlaceholderScreen -__all__ = ["BrowseScreen", "DashboardScreen", "PlaceholderScreen"] +__all__ = ["BrowseScreen", "DashboardScreen", "DownloadsScreen", "PlaceholderScreen"] diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py new file mode 100644 index 0000000..1955363 --- /dev/null +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -0,0 +1,343 @@ +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.containers import Container, Grid, VerticalScroll +from textual.events import Key, Resize, ScreenResume +from textual.geometry import Region +from textual.widget import Widget +from textual.widgets import Static +from textual.worker import Worker, WorkerState + +from ...services.acquisition_queue import ( + QueueFailureStage, + QueueItem, + QueueJob, + QueueSnapshot, + QueueStatus, +) +from .base import HubScreen + +QueueProvider = Callable[[], QueueSnapshot] + + +@dataclass(frozen=True, slots=True) +class QueueLoadOutcome: + snapshot: QueueSnapshot | None = None + error: str | None = None + + +class DownloadsScreen(HubScreen): + """Read-only persistent acquisition queue browser.""" + + def __init__(self, *, queue_provider: QueueProvider) -> None: + super().__init__("downloads", "Downloads") + self._queue_provider = queue_provider + self.snapshot: QueueSnapshot | None = None + self.jobs: tuple[QueueJob, ...] = () + self.selected_index = 0 + self._details_mode = False + self._refresh_worker: Worker[QueueLoadOutcome] | None = None + + def compose_content(self) -> Iterable[Widget]: + yield Static( + "Jobs 0 · Pending 0 · Active 0 · Completed 0 · Failed 0", + id="downloads-summary", + markup=False, + ) + yield Static("Loading acquisition queue…", id="downloads-status", markup=False) + with Grid(id="downloads-main"): + with Container(classes="downloads-panel", id="download-jobs-panel"): + yield Static("Jobs · loading", classes="panel-title", id="download-jobs-title") + with VerticalScroll(id="download-jobs-scroll"): + yield Static("Loading queue…", id="download-jobs", markup=False) + with Container(classes="downloads-panel", id="download-details-panel"): + yield Static("Job details", classes="panel-title") + with VerticalScroll(id="download-details-scroll"): + yield Static("Select a job to inspect its tracks.", id="download-details", markup=False) + yield Static("r refresh · Enter details", 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 refresh_snapshot(self) -> None: + if self.snapshot is None: + self.query_one("#download-jobs", Static).update("Loading queue…") + self.query_one("#download-details", Static).update("Waiting for queue data…") + self.query_one("#downloads-status", Static).update("Refreshing queue…") + self.query_one("#downloads-status", Static).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 not self._refresh_worker: + 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 "Unknown worker error" + 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.jobs = () + self.query_one("#download-jobs-title", Static).update("Jobs · unavailable") + self.query_one("#download-jobs", Static).update("Unable to load acquisition jobs.") + self.query_one("#download-details", Static).update("Queue details are unavailable.") + self.query_one("#downloads-position", Static).update("r retry refresh") + return + + previous_id = self.selected_job.job_id if self.selected_job is not None else None + self.snapshot = outcome.snapshot + self.jobs = outcome.snapshot.jobs + if previous_id is not None: + self.selected_index = next( + (index for index, job in enumerate(self.jobs) if job.job_id == previous_id), + 0, + ) + else: + self.selected_index = 0 + self._details_mode = False + self.remove_class("-details-mode") + self._render_summary() + self._render_jobs() + self._render_selected_details() + if self.jobs: + status.update("Read-only queue · no Run, Retry, or Delete actions") + self._update_position() + self.call_after_refresh(self._scroll_selected_job_into_view) + else: + status.update("No acquisition jobs yet.") + self.query_one("#downloads-position", Static).update("r refresh · Queue is empty") + + @property + def selected_job(self) -> QueueJob | None: + if not self.jobs: + return None + return self.jobs[self.selected_index] + + def _render_summary(self) -> None: + snapshot = self.snapshot + if snapshot is None: + return + self.query_one("#downloads-summary", Static).update( + f"Jobs {snapshot.total_job_count} · Pending {snapshot.pending_job_count} · " + f"Active {snapshot.active_job_count} · Completed {snapshot.completed_job_count} · " + f"Failed {snapshot.failed_job_count}" + ) + + def _render_jobs(self) -> None: + self.query_one("#download-jobs-title", Static).update(f"Jobs · {len(self.jobs)}") + if not self.jobs: + self.query_one("#download-jobs", Static).update("No acquisition jobs.") + return + lines = [] + for index, job in enumerate(self.jobs): + marker = ">" if index == self.selected_index else " " + status = _status_label(job.status) + summary = f"{job.completed_item_count} done" + if job.failed_item_count: + summary += f" · {job.failed_item_count} failed" + lines.append( + f"{marker} {job.display_number:>2} {status:<18} " + f"{job.label[:28]:28} · {job.total_item_count} tracks · {summary}" + ) + self.query_one("#download-jobs", Static).update( + Text("\n".join(lines), no_wrap=True, overflow="ellipsis") + ) + + def _render_selected_details(self) -> None: + job = self.selected_job + details = self.query_one("#download-details", Static) + scroll = self.query_one("#download-details-scroll", VerticalScroll) + scroll.scroll_home(animate=False, immediate=True) + if job is None: + details.update("No job selected.") + return + destination = str(job.destination) if job.destination is not None else "See track destinations" + lines = [ + job.label, + "", + f"Reference {job.display_number}", + f"Job ID {job.job_id}", + f"Status {_status_label(job.status)}", + f"Destination {destination}", + f"Created {_timestamp(job.created_at)}", + f"Updated {_timestamp(job.updated_at)}", + f"Tracks {job.total_item_count}", + f"Progress {job.completed_item_count} completed · {job.failed_item_count} failed · " + f"{job.pending_item_count} pending · {job.active_item_count} active", + f"Retry {_job_retry_label(job)}", + "", + "Tracks", + ] + if not job.items: + lines.append(" No tracks stored in this job.") + for index, item in enumerate(job.items, start=1): + lines.extend(_item_lines(index, item)) + details.update(Text("\n".join(lines), overflow="ellipsis")) + + def _update_position(self) -> None: + if not self.jobs: + return + suffix = "Esc job list · PgUp/PgDn details" if self._details_mode else "Enter details · r refresh" + self.query_one("#downloads-position", Static).update( + f"Job {self.selected_index + 1} of {len(self.jobs)} · {suffix}" + ) + + 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_job 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 in ("pagedown", "pageup") and self._details_mode: + scroll = self.query_one("#download-details-scroll", VerticalScroll) + if event.key == "pagedown": + scroll.scroll_page_down(animate=False) + else: + scroll.scroll_page_up(animate=False) + elif event.key in ("down", "j"): + self._select_job(self.selected_index + 1) + elif event.key in ("up", "k"): + self._select_job(self.selected_index - 1) + elif event.key == "home": + self._select_job(0) + elif event.key == "end": + self._select_job(len(self.jobs) - 1) + elif event.key in ("pagedown", "pageup"): + scroll = self.query_one("#download-jobs-scroll", VerticalScroll) + step = max(1, scroll.size.height - 1) + self._select_job(self.selected_index + (step if event.key == "pagedown" else -step)) + else: + return + event.prevent_default() + event.stop() + + def _select_job(self, index: int) -> None: + if not self.jobs: + return + self.selected_index = max(0, min(len(self.jobs) - 1, index)) + self._render_jobs() + self._render_selected_details() + self._update_position() + self.call_after_refresh(self._scroll_selected_job_into_view) + + def _scroll_selected_job_into_view(self) -> None: + if not self.jobs: + return + scroll = self.query_one("#download-jobs-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.jobs: + self.call_after_refresh(self._scroll_selected_job_into_view) + + +def _status_label(status: QueueStatus) -> str: + return { + QueueStatus.PENDING: "Queued", + QueueStatus.CHECKING_EXISTING: "Checking existing", + QueueStatus.DOWNLOADING: "Downloading", + QueueStatus.VALIDATING: "Validating", + QueueStatus.POST_PROCESSING: "Processing lyrics", + QueueStatus.COMPLETED: "Completed", + QueueStatus.SKIPPED: "Skipped", + QueueStatus.FAILED: "Failed", + QueueStatus.UNKNOWN: "Unknown", + }[status] + + +def _failure_label(stage: QueueFailureStage | None) -> str: + return { + QueueFailureStage.TRANSPORT: "Download failed", + QueueFailureStage.VALIDATION: "Validation failed", + QueueFailureStage.LYRICS: "Lyrics processing failed", + QueueFailureStage.LRC: "LRC creation failed", + QueueFailureStage.STATE: "Library-state update failed", + QueueFailureStage.UNKNOWN: "Processing failed (unknown stage)", + None: "Failure stage unavailable", + }[stage] + + +def _item_retry_label(item: QueueItem) -> str: + if item.postprocessing_retryable: + return "Retry available from verified downloaded file" + if item.status is QueueStatus.FAILED and item.retryable: + return "Full download retry required" + return "Not retryable" + + +def _job_retry_label(job: QueueJob) -> str: + if job.status is not QueueStatus.FAILED: + return "Not applicable" + if any(item.postprocessing_retryable for item in job.items): + return "Safe post-processing retry available" + if job.retryable: + return "Full download retry may be required" + return "Not retryable" + + +def _item_lines(index: int, item: QueueItem) -> list[str]: + title = item.title or "Untitled track" + destination = str(item.destination) if item.destination is not None else "Unavailable" + lines = [ + "", + f" {index}. {title}", + f" Status {_status_label(item.status)}", + f" Destination {destination}", + ] + if item.expected_bytes is not None or item.bytes_written: + expected = str(item.expected_bytes) if item.expected_bytes is not None else "unknown" + lines.append(f" Progress {item.bytes_written} / {expected} bytes") + if item.status is QueueStatus.FAILED: + lines.append(f" Failure {_failure_label(item.failure_stage)}") + if item.error: + lines.append(f" Error {_concise_error(item.error)}") + lines.append(f" Retry {_item_retry_label(item)}") + return lines + + +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/tests/test_acquisition_queue_service.py b/tests/test_acquisition_queue_service.py index 15c3574..de40089 100644 --- a/tests/test_acquisition_queue_service.py +++ b/tests/test_acquisition_queue_service.py @@ -1,3 +1,4 @@ +import hashlib import json from pathlib import Path import sys @@ -7,8 +8,9 @@ import pytest from juice_lyrics.acquisition.jobs import JobStore -from juice_lyrics.acquisition.models import AcquisitionItem, AcquisitionState +from juice_lyrics.acquisition.models import AcquisitionFailureStage, AcquisitionItem, AcquisitionState from juice_lyrics.services.acquisition_queue import ( + QueueFailureStage, QueueReferenceError, QueueStatus, get_queue_snapshot, @@ -180,6 +182,28 @@ def test_view_does_not_recover_or_rewrite_store(tmp_path): 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 diff --git a/tests/test_tui.py b/tests/test_tui.py index 41e2313..50a6b00 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -135,7 +135,7 @@ async def scenario(): asyncio.run(scenario()) -def test_keyboard_navigation_reaches_all_placeholder_screens(tmp_path): +def test_keyboard_navigation_reaches_functional_and_placeholder_screens(tmp_path): async def scenario(): app = _app(tmp_path) async with app.run_test() as pilot: @@ -144,11 +144,15 @@ async def scenario(): await pilot.pause() assert app.screen.id == "screen-browse" assert app.query_one("#browse-query") is not None - for key, section in zip("345", ("library", "downloads", "settings")): + for key, section in zip("35", ("library", "settings")): await pilot.press(key) await pilot.pause() assert app.screen.id == f"screen-{section}" assert "planned for a later milestone" in _rendered(app, "#placeholder-message") + await pilot.press("4") + await pilot.pause() + assert app.screen.id == "screen-downloads" + assert app.query_one("#download-jobs") is not None await pilot.press("1") await pilot.pause() assert app.screen.id == "screen-dashboard" diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py new file mode 100644 index 0000000..53b8bcc --- /dev/null +++ b/tests/test_tui_downloads.py @@ -0,0 +1,440 @@ +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, + LibraryStatus, + QueueFailureStage, + QueueItem, + QueueJob, + QueueSnapshot, + QueueStatus, +) +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) -> JuiceLyricsApp: + empty = _snapshot() + 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, + catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), + ) + + +def _text(app: JuiceLyricsApp, selector: str) -> str: + return str(app.query_one(selector).render()) + + +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 "No acquisition jobs" in _text(app, "#download-jobs") + assert "Jobs 0 · Pending 0 · Active 0 · Completed 0 · Failed 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 tracks stored in this job" in _text(app, "#download-details") + assert "Status Completed" in _text(app, "#download-details") + + 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-jobs") + await pilot.press("2") + await pilot.pause() + assert app.screen.id == "screen-browse" + release.set() + + 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 "Jobs 4 · Pending 1 · Active 1 · Completed 1 · Failed 1" in _text( + app, "#downloads-summary" + ) + rendered = _text(app, "#download-jobs") + assert rendered.index("Queued Song") < rendered.index("Active Song") < rendered.index("Done Song") + assert "> 1 Queued" in rendered + + await pilot.press("down", "j") + await pilot.pause() + assert app.screen.selected_job.job_id == "complete-id" + assert "Done Song" in _text(app, "#download-details") + await pilot.press("up", "k") + assert app.screen.selected_job.job_id == "queued-id" + + await pilot.press("end") + await pilot.pause() + details = _text(app, "#download-details") + assert app.screen.selected_job.job_id == "failed-id" + assert "Job ID failed-id" in details + assert "Finished Track" in details and "Completed" in details + assert "Lyrics processing failed" in details + assert "Audio downloaded lyrics verification failed" in details + assert "Retry available from verified downloaded file" in details + assert "Download failed" in details + assert "Validation failed" in details + assert "LRC creation failed" in details + assert "Library-state update failed" in details + assert "Full download retry required" in details + assert "Retry Safe post-processing retry available" in details + + await pilot.press("home") + assert app.screen.selected_job.job_id == "queued-id" + + 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-jobs-scroll", VerticalScroll) + assert "-downloads-narrow" in app.screen.classes + assert job_scroll.size.height >= 5 + assert job_scroll.max_scroll_y > 0 + assert "r refresh" in _text(app, "#downloads-position") + + await pilot.press("end") + await pilot.pause() + assert app.screen.selected_job.job_id == "job-20" + assert job_scroll.scroll_y > 0 + assert job_scroll.scroll_y <= 19 < 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) + assert details_scroll.max_scroll_y > 0 + 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 < 19 + + asyncio.run(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_job.job_id == "keep" + + await pilot.press("r") + await app.screen._refresh_worker.wait() + await pilot.pause() + assert app.screen.selected_job.job_id == "keep" + + await pilot.press("r") + await app.screen._refresh_worker.wait() + await pilot.pause() + assert app.screen.selected_job.job_id == "replacement" + + 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_job.job_id == "fresh" + release_stale.set() + await pilot.pause() + assert "Stale" not in _text(app, "#download-jobs") + + 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")) From dbb85fa3c512c09c8b70102e3f0cec461b4d36f6 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 01:42:58 +0100 Subject: [PATCH 23/62] Update v2 development checkpoint --- PROJECT_CONTEXT.md | 27 ++++++++++- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 40 ++++++++++----- docs/PROJECT_STATE.md | 67 +++++++++++++++++--------- docs/ROADMAP_V2.md | 29 ++++++++++- 4 files changed, 125 insertions(+), 38 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index b4f5c9a..169721f 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -273,7 +273,32 @@ The latest development checkpoint reports: * 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 +* responsive terminal-native Textual shell with `ansi_color=True` +* functional read-only Dashboard, Browse, and Downloads screens +* canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour +* server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details +* queue summaries, job navigation, track details, structured failure stages, and retry eligibility +* Library and Settings remain placeholders; TUI queue mutations and Browse download actions are not implemented +* legacy CLI remains the way to download, delete jobs, and sync +* 185 automated tests passing across the suite + +The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` +on branch `v2-redesign`. The planned product and executable name remains `999`, +but no rename or migration has been performed. Native FLAC support remains +planned. + +Recommended next milestones are: read-only Library, Settings, Browse-to-download +job creation, Downloads Run/Retry/Delete actions, Library sync actions, the `999` +naming migration, native FLAC support, then beta polish and release testing. + +To resume: + +```bash +cd /home/nobloat/Downloads/juice-lyrics-codex +git switch v2-redesign +.venv/bin/pytest -q +.venv/bin/juice-lyrics tui +``` ## Development rules diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 91fe095..0cb53e0 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -48,7 +48,13 @@ The backend is considered stable. Milestone reached: -## 80 automated tests passing +## Current verified checkpoint + +The current development branch is `v2-redesign` in +`/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has +185 passing tests. + +Completed and integrated: Verified systems: @@ -69,6 +75,19 @@ Verified systems: - duplicate detection - CLI workflows +The v2 frontend now also includes a responsive terminal-native Textual shell, +functional read-only Dashboard and Browse screens, canonical Category and Era +selectors, correct case-sensitive API cache behavior, server-side catalogue +pagination with scrollable 50-result pages, stable ID-based song details, and a +read-only Downloads screen with queue summaries, job navigation, track details, +failure stages, and retry eligibility. + +Library and Settings remain placeholders. Browse download actions and TUI queue +mutations are not implemented. The legacy CLI remains the way to download, +delete jobs, and sync. Native FLAC support remains planned. The planned +product/executable name remains `999`; package, distribution, and data paths +have not been renamed. + Live API acquisition was tested successfully. The project has reached the point where the backend should be frozen before major redesign. @@ -127,7 +146,8 @@ docs/ └── this file -The project is currently in the design/planning stage. +The project is in incremental v2 implementation. The backend remains stable and +the TUI is intentionally read-only. --- @@ -278,11 +298,9 @@ Download: Available -Actions: - -- open details -- download -- preview lyrics +The current Browse implementation supports result selection, details, lyrics +previews, canonical filters, and pagination. Download actions are not yet +implemented. --- @@ -330,11 +348,9 @@ Downloading 65% Lemon Glow Complete -Actions: - -- retry -- cancel -- remove +The current Downloads implementation is read-only. It shows queue totals, +jobs, tracks, structured failures, and retry eligibility. Retry, cancel, remove, +and other queue mutations are not yet implemented. --- diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 3754ba8..e1320cd 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,26 +1,37 @@ # 999 Project State ## Current Status -Backend frozen. -80 tests passing. -GitHub backup complete. +Backend services remain stable and the experimental Textual frontend is +integrated as a read-only presentation layer. The current checkpoint has 185 +passing tests. ## Current Branch v2-redesign -## What Exists -- API client -- lyrics engine -- acquisition -- downloader -- rmpc integration -- CLI +## Repository -## What Is Planned -- rename to 999 -- Textual TUI -- UX redesign -- migration system +`/home/nobloat/Downloads/juice-lyrics-codex` + +## Completed and integrated + +- Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. +- Responsive terminal-native Textual shell with functional read-only Dashboard, Browse, and Downloads screens. +- Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. +- Downloads queue summaries, job navigation, track details, structured failure stages, and retry eligibility. +- Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. + +## Available through the CLI + +The legacy CLI remains the supported way to download, delete acquisition jobs, +and sync the library. + +## Current limitations + +- Library and Settings remain placeholders. +- TUI queue mutations and Browse download actions are not implemented. +- Native FLAC support remains planned; lyric post-processing is currently MP3-only. +- The planned executable/product name remains `999`; package, distribution, and + data paths remain named `juice-lyrics`. ## Important Decisions - Keep embedded lyrics @@ -29,12 +40,22 @@ v2-redesign - Use Textual - Keep backend separate from UI -## Current Problem -Not installed globally. -Still development venv. +## Recommended next milestones + +1. Read-only Library screen +2. Settings screen +3. Browse-to-download job creation +4. Downloads Run/Retry/Delete actions +5. Library sync actions +6. `999` command and naming migration +7. Native FLAC support +8. Beta polish, packaging, and release testing + +## Resume development -## Next Steps -1. Finish design docs -2. Design TUI -3. Implement v2 -4. Package/install properly +```bash +cd /home/nobloat/Downloads/juice-lyrics-codex +git switch v2-redesign +.venv/bin/pytest -q +.venv/bin/juice-lyrics tui +``` diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 75fd0fc..e1cfb74 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -25,9 +25,9 @@ Future work should improve usability around these systems. --- -# Phase 0 — Planning (Current) +# Phase 0 — Planning (Complete) -Status: In Progress +Status: Complete Goals: @@ -133,6 +133,10 @@ Goal: Create the main application interface. +Status: In progress. The responsive terminal-native shell, Dashboard, Browse, +and read-only Downloads screen are integrated. Library and Settings remain +placeholders, and the TUI remains read-only. + Screens: ## Browse @@ -145,6 +149,9 @@ Features: - Lyrics preview. - Download actions. +Status: Read-only functionality complete, including server-side pagination and +scrollable 50-result pages. Download actions remain planned. + --- ## Library @@ -156,6 +163,8 @@ Features: - Sync state. - Metadata. +Status: Placeholder; planned next read-only screen. + --- ## Downloads @@ -167,6 +176,9 @@ Features: - Completed items. - Retry. +Status: Read-only queue view complete. Run, Retry, Delete, and Cancel actions +remain planned. + --- ## Settings @@ -177,10 +189,23 @@ Features: - rmpc settings. - API settings. +Status: Placeholder. + --- # Phase 5 — Advanced Features +Recommended implementation order after the current checkpoint: + +1. Read-only Library screen +2. Settings screen +3. Browse-to-download job creation +4. Downloads Run/Retry/Delete actions +5. Library sync actions +6. `999` command and naming migration +7. Native FLAC support +8. Beta polish, packaging, and release testing + Possible future improvements: ## Lyrics Improvements From 8d3a0c6f3acec15589fce33b85a5bf384297f622 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 10:36:15 +0100 Subject: [PATCH 24/62] Add read-only Library screen and sync preview --- PROJECT_CONTEXT.md | 11 +- docs/DEVELOPMENT.md | 14 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 11 +- docs/PROJECT_STATE.md | 22 +- docs/ROADMAP_V2.md | 23 +- src/juice_lyrics/services/__init__.py | 21 +- src/juice_lyrics/services/library_status.py | 216 ++++++++ src/juice_lyrics/services/library_sync.py | 26 + src/juice_lyrics/tui/app.py | 152 +++++- src/juice_lyrics/tui/screens/__init__.py | 3 +- src/juice_lyrics/tui/screens/library.py | 537 ++++++++++++++++++++ tests/test_library_status.py | 123 ++++- tests/test_library_sync_service.py | 27 + tests/test_tui.py | 13 +- tests/test_tui_library.py | 479 +++++++++++++++++ 15 files changed, 1635 insertions(+), 43 deletions(-) create mode 100644 src/juice_lyrics/tui/screens/library.py create mode 100644 tests/test_tui_library.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 169721f..9b407ee 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -274,21 +274,22 @@ The latest development checkpoint reports: * MP3 post-processing with ID3 SYLT/USLT and rmpc LRC integration verified * Settings / Path CLI compatibility verified * responsive terminal-native Textual shell with `ansi_color=True` -* functional read-only Dashboard, Browse, and Downloads screens +* functional read-only Dashboard, Browse, Library, and Downloads screens * canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details * queue summaries, job navigation, track details, structured failure stages, and retry eligibility -* Library and Settings remain placeholders; TUI queue mutations and Browse download actions are not implemented +* Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews +* Settings remains a placeholder; TUI queue mutations, Browse download actions, and sync execution are not implemented * legacy CLI remains the way to download, delete jobs, and sync -* 185 automated tests passing across the suite +* 197 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, but no rename or migration has been performed. Native FLAC support remains planned. -Recommended next milestones are: read-only Library, Settings, Browse-to-download -job creation, Downloads Run/Retry/Delete actions, Library sync actions, the `999` +Recommended next milestones are: Settings, Browse-to-download job creation, +Downloads Run/Retry/Delete actions, Library sync actions, the `999` naming migration, native FLAC support, then beta polish and release testing. To resume: diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 7d5cd70..f98e128 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -61,7 +61,7 @@ juice-lyrics tui ``` The experimental shell provides a read-only Dashboard plus functional, -read-only Browse and Downloads screens. Press `/` to focus catalogue search and Enter to +read-only Browse, Library, and Downloads screens. 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 @@ -82,6 +82,18 @@ selected job's scrollable track details and Escape returns to the job list. Press `r` to refresh the read-only queue snapshot. Run, Retry, Delete, Cancel, and Download actions are intentionally unavailable in this milestone. +In Library, arrows or `j`/`k` select local MP3 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 `juice-lyrics sync`. The +scanner is currently MP3-focused; native FLAC support remains planned. + ## Source of truth and Git workflow 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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 0cb53e0..bc3248c 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -52,7 +52,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -185 passing tests. +197 passing tests. Completed and integrated: @@ -80,11 +80,12 @@ functional read-only Dashboard and Browse screens, canonical Category and Era selectors, correct case-sensitive API cache behavior, server-side catalogue pagination with scrollable 50-result pages, stable ID-based song details, and a read-only Downloads screen with queue summaries, job navigation, track details, -failure stages, and retry eligibility. +failure stages, and retry eligibility, plus a read-only Library screen with +local track browsing, filters, details, and explicit sync previews. -Library and Settings remain placeholders. Browse download actions and TUI queue -mutations are not implemented. The legacy CLI remains the way to download, -delete jobs, and sync. Native FLAC support remains planned. The planned +Settings remains a placeholder. Browse download actions, TUI queue mutations, +and sync execution are not implemented. The legacy CLI remains the way to +download, delete jobs, and sync. Native FLAC support remains planned. The planned product/executable name remains `999`; package, distribution, and data paths have not been renamed. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index e1320cd..3381011 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -2,7 +2,7 @@ ## Current Status Backend services remain stable and the experimental Textual frontend is -integrated as a read-only presentation layer. The current checkpoint has 185 +integrated as a read-only presentation layer. The current checkpoint has 197 passing tests. ## Current Branch @@ -15,9 +15,10 @@ v2-redesign ## Completed and integrated - Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. -- Responsive terminal-native Textual shell with functional read-only Dashboard, Browse, and Downloads screens. +- Responsive terminal-native Textual shell with functional read-only Dashboard, Browse, Library, and Downloads screens. - Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. - Downloads queue summaries, job navigation, track details, structured failure stages, and retry eligibility. +- Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. ## Available through the CLI @@ -27,7 +28,7 @@ and sync the library. ## Current limitations -- Library and Settings remain placeholders. +- Settings remains a placeholder. - TUI queue mutations and Browse download actions are not implemented. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and @@ -42,14 +43,13 @@ and sync the library. ## Recommended next milestones -1. Read-only Library screen -2. Settings screen -3. Browse-to-download job creation -4. Downloads Run/Retry/Delete actions -5. Library sync actions -6. `999` command and naming migration -7. Native FLAC support -8. Beta polish, packaging, and release testing +1. Settings screen +2. Browse-to-download job creation +3. Downloads Run/Retry/Delete actions +4. Library sync actions +5. `999` command and naming migration +6. Native FLAC support +7. Beta polish, packaging, and release testing ## Resume development diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index e1cfb74..2f3b089 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -134,8 +134,8 @@ Goal: Create the main application interface. Status: In progress. The responsive terminal-native shell, Dashboard, Browse, -and read-only Downloads screen are integrated. Library and Settings remain -placeholders, and the TUI remains read-only. +Library, and read-only Downloads screen are integrated. Settings remains a +placeholder, and the TUI remains read-only. Screens: @@ -163,7 +163,9 @@ Features: - Sync state. - Metadata. -Status: Placeholder; planned next read-only screen. +Status: Read-only functionality complete, including local search and status +filters, track details, and explicit non-mutating sync previews. Sync execution +remains planned. --- @@ -197,14 +199,13 @@ Status: Placeholder. Recommended implementation order after the current checkpoint: -1. Read-only Library screen -2. Settings screen -3. Browse-to-download job creation -4. Downloads Run/Retry/Delete actions -5. Library sync actions -6. `999` command and naming migration -7. Native FLAC support -8. Beta polish, packaging, and release testing +1. Settings screen +2. Browse-to-download job creation +3. Downloads Run/Retry/Delete actions +4. Library sync actions +5. `999` command and naming migration +6. Native FLAC support +7. Beta polish, packaging, and release testing Possible future improvements: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 11ce32c..9e5aeb2 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -23,7 +23,17 @@ search_catalogue, search_catalogue_page, ) -from .library_status import LibraryStatus, get_library_status +from .library_status import ( + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryStatus, + LibraryTrack, + get_library_snapshot, + get_library_status, +) from .library_sync import ( LibrarySyncDependencies, LibrarySyncOptions, @@ -36,6 +46,7 @@ TrackSyncPlan, TrackSyncResult, execute_library_sync, + get_library_sync_preview, plan_library_sync, ) @@ -45,6 +56,12 @@ "CatalogueFilterOption", "CataloguePage", "LibraryStatus", + "LibraryLrcStatus", + "LibraryLyricStatus", + "LibraryMatchStatus", + "LibrarySnapshot", + "LibraryStateStatus", + "LibraryTrack", "LibrarySyncDependencies", "LibrarySyncOptions", "LibrarySyncPlan", @@ -64,9 +81,11 @@ "TrackSyncPlan", "TrackSyncResult", "execute_library_sync", + "get_library_sync_preview", "get_catalogue_filters", "get_queue_snapshot", "get_library_status", + "get_library_snapshot", "get_song_details", "get_song_details_by_id", "plan_library_sync", diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 2c07ee0..1e248c7 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -3,15 +3,113 @@ import json from collections.abc import Callable from dataclasses import dataclass +from enum import Enum from pathlib import Path from typing import Any from ..config.settings import BACKUP_DIR, STATE_FILE, Settings from ..library.scanner import find_mp3s +from ..library.matching import local_duration from ..lyrics.engine import verify_file from ..state import sha256_file 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" + 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 MP3.""" + + 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 + + @property + def needs_attention(self) -> bool: + return ( + self.match_status is LibraryMatchStatus.UNMATCHED + or self.lyric_status is LibraryLyricStatus.NONE + or self.lrc_status is LibraryLrcStatus.MISSING + or self.state_status is not LibraryStateStatus.CURRENT + or self.warning is not None + ) + + +@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, ...] = () + + @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) @dataclass(frozen=True, slots=True) @@ -41,6 +139,124 @@ def _read_state(path: Path) -> dict[str, Any]: 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 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, +) -> LibrarySnapshot: + """Inspect local MP3s and state without contacting APIs or writing files.""" + + 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)) + state_files = state.get("files", {}) + tracks: list[LibraryTrack] = [] + for path in find_mp3s(settings): + relative_path = path.relative_to(library_path) + reference = str(relative_path) + raw_entry = state_files.get(reference) + entry = raw_entry if isinstance(raw_entry, dict) else None + track_warnings: list[str] = [] + + 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 + elif entry is None: + state_status = LibraryStateStatus.INVALID + track_warnings.append("Stored library state is malformed.") + else: + try: + state_status = ( + LibraryStateStatus.CURRENT + if entry.get("sha256") == hasher(path) + 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: + candidate_title = entry.get("api_name") + if candidate_title is not None and str(candidate_title).strip(): + matched_title = str(candidate_title).strip() + matched = bool(matched_title or (entry is not None and entry.get("song_id") is not None)) + + lrc_path = None + if entry is not None and entry.get("lrc"): + lrc_path = Path(str(entry["lrc"])) + if lrc_path is None: + lrc_status = LibraryLrcStatus.NONE + elif lrc_path.is_file(): + lrc_status = LibraryLrcStatus.PRESENT + else: + lrc_status = LibraryLrcStatus.MISSING + track_warnings.append("Recorded external LRC file is missing.") + + try: + duration = 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=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, + warning=" ".join(track_warnings) or None, + ) + ) + return LibrarySnapshot(library_path, True, tuple(tracks), warnings) + + def get_library_status( settings: Settings, *, diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index aed206d..4c2af03 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -1,6 +1,7 @@ from __future__ import annotations import json +import shutil from collections.abc import Callable, Mapping from dataclasses import dataclass, field from enum import Enum @@ -287,6 +288,31 @@ def plan_library_sync( 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, +) -> 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() + if rmpc_enabled and lyrics_dir is None: + lyrics_dir = DEFAULT_RMPC_LYRICS_DIR + options = LibrarySyncOptions.from_settings( + settings, + dry_run=True, + rmpc_enabled=rmpc_enabled, + lyrics_dir=lyrics_dir, + state_file=state_file, + ) + return plan_library_sync(options, dependencies=dependencies, progress=progress) + + def _state_entry( state: dict[str, Any], track: TrackSyncPlan, diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 80fd1bf..e295fee 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -15,11 +15,13 @@ get_song_details_by_id, search_catalogue_page, ) -from ..services.library_status import LibraryStatus, get_library_status +from ..services.library_status import LibrarySnapshot, LibraryStatus, get_library_snapshot, get_library_status +from ..services.library_sync import LibrarySyncPlan, get_library_sync_preview from .screens.base import NavigationItem from .screens.browse import BrowseScreen from .screens.dashboard import DashboardScreen from .screens.downloads import DownloadsScreen +from .screens.library import LibraryScreen from .screens.placeholder import PlaceholderScreen LibraryStatusProvider = Callable[[Any], LibraryStatus] @@ -27,6 +29,8 @@ CatalogueSearchProvider = Callable[..., CataloguePage] CatalogueDetailsProvider = Callable[..., SongDetails | None] CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] +LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] +LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] class JuiceLyricsApp(App[None]): @@ -301,6 +305,99 @@ class JuiceLyricsApp(App[None]): 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 Input, + #library-controls SelectCurrent { + background: transparent; + color: ansi_default; + border: tall ansi_default; + background-tint: transparent; + padding: 0 1; + } + + #library-controls Input:focus, + #library-controls Select:focus > SelectCurrent { + background: transparent; + border: tall ansi_blue; + background-tint: transparent; + } + + #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; + } + #placeholder-panel { border: round ansi_cyan; padding: 2 3; @@ -376,6 +473,44 @@ class JuiceLyricsApp(App[None]): 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; + } """ def __init__( @@ -388,6 +523,8 @@ def __init__( catalogue_details_provider: CatalogueDetailsProvider = get_song_details_by_id, catalogue_filters_provider: CatalogueFiltersProvider = get_catalogue_filters, downloads_queue_provider: QueueSnapshotProvider | None = None, + library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, + library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, ) -> None: super().__init__(ansi_color=True) self.settings = settings @@ -397,6 +534,8 @@ def __init__( self.catalogue_details_provider = catalogue_details_provider self.catalogue_filters_provider = catalogue_filters_provider self.downloads_queue_provider = downloads_queue_provider or queue_snapshot_provider + self.library_snapshot_provider = library_snapshot_provider + self.library_preview_provider = library_preview_provider def on_mount(self) -> None: self.install_screen( @@ -417,7 +556,11 @@ def on_mount(self) -> None: "browse", ) self.install_screen( - PlaceholderScreen("Library", "Local track browsing and sync actions are planned for a later milestone."), + LibraryScreen( + self.settings, + snapshot_provider=self.library_snapshot_provider, + preview_provider=self.library_preview_provider, + ), "library", ) self.install_screen( @@ -455,6 +598,11 @@ def action_show_help(self) -> None: "↑/↓ or j/k select jobs • Home/End first/last job • " "PgUp/PgDn move jobs • Enter track details • Esc job list • r refresh" ) + elif section == "library": + message = ( + "↑/↓ or j/k select tracks • / local search • Home/End first/last • " + "PgUp/PgDn move tracks • Enter details • s read-only sync preview • r refresh" + ) else: message = "1–5 switch sections • r refreshes Dashboard • q quits" self.notify(message, timeout=5) diff --git a/src/juice_lyrics/tui/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py index 8f967b9..a1f2d53 100644 --- a/src/juice_lyrics/tui/screens/__init__.py +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -3,6 +3,7 @@ from .browse import BrowseScreen from .dashboard import DashboardScreen from .downloads import DownloadsScreen +from .library import LibraryScreen from .placeholder import PlaceholderScreen -__all__ = ["BrowseScreen", "DashboardScreen", "DownloadsScreen", "PlaceholderScreen"] +__all__ = ["BrowseScreen", "DashboardScreen", "DownloadsScreen", "LibraryScreen", "PlaceholderScreen"] diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py new file mode 100644 index 0000000..4655ba9 --- /dev/null +++ b/src/juice_lyrics/tui/screens/library.py @@ -0,0 +1,537 @@ +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass +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 Key, Resize, ScreenResume +from textual.geometry import Region +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_sync import LibrarySyncPlan, MatchOutcome, SyncLyricType +from .base import HubScreen + +SnapshotProvider = Callable[[Any], LibrarySnapshot] +PreviewProvider = Callable[[Any], LibrarySyncPlan] + + +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), + ("Needs attention", LibraryFilter.ATTENTION.value), +) + + +class LibraryInput(Input): + """Local search input that preserves global section shortcuts.""" + + def on_key(self, event: Key) -> None: + if event.key == "q": + self.app.exit() + 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 LibrarySelect(Select[str]): + """Local status selector that preserves global section shortcuts.""" + + def on_key(self, event: Key) -> None: + if event.key == "q": + self.app.exit() + 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 PreviewOutcome: + plan: LibrarySyncPlan | None = None + error: str | None = None + + +class LibraryScreen(HubScreen): + """Read-only local MP3 library browser and sync-plan preview.""" + + BINDINGS = [Binding("/", "focus_search", "Search", show=False)] + + def __init__( + self, + settings: Any, + *, + snapshot_provider: SnapshotProvider, + preview_provider: PreviewProvider, + ) -> None: + super().__init__("library", "Library") + self.settings = settings + self._snapshot_provider = snapshot_provider + self._preview_provider = preview_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._preview_worker: Worker[PreviewOutcome] | None = None + self._pending_snapshot: SnapshotOutcome | None = None + self._pending_preview: PreviewOutcome | None = None + + def compose_content(self) -> Iterable[Widget]: + yield Static( + "MP3 tracks 0 · Matched 0 · Unmatched 0 · Synced 0 · Plain 0 · No lyrics 0 · LRC 0 · Attention 0", + id="library-summary", + markup=False, + ) + yield Static("Loading local MP3 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("Preview not generated · press s · Preview only — no files changed", id="library-preview", markup=False) + yield Static("r refresh · s preview · / search", 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: + 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() + elif self.filtered_tracks: + self.call_after_refresh(self.set_focus, None) + if self._pending_preview is not None: + outcome, self._pending_preview = self._pending_preview, None + self._apply_preview(outcome) + + def refresh_snapshot(self) -> None: + 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( + "Preview not generated · press s · Preview only — no files changed" + ) + self._set_status("Refreshing local MP3 library…") + self._snapshot_worker = self._load_snapshot() + + @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) -> None: + if self.snapshot is None: + self._set_status("Load the library before generating a sync preview.", error=True) + return + self.query_one("#library-preview", Static).update( + "Generating sync preview… · Preview only — no files changed" + ) + self._preview_worker = self._load_preview() + + @work(thread=True, exclusive=True, group="library-preview", exit_on_error=False) + def _load_preview(self) -> PreviewOutcome: + try: + return PreviewOutcome(self._preview_provider(self.settings)) + 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._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 snapshot worker failed") + if self._can_render(): + self._apply_snapshot(outcome) + else: + self._pending_snapshot = outcome + 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="Sync preview worker failed") + if self._can_render(): + self._apply_preview(outcome) + else: + self._pending_preview = outcome + + 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) + 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 tracks found. Native FLAC support is planned.") + elif outcome.snapshot.warnings: + self._set_status(" ".join(outcome.snapshot.warnings), error=True) + else: + self._set_status(f"Local MP3 library · {outcome.snapshot.library_path}") + + 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("Sync preview unavailable.", error=True) + self._render_details() + return + self.preview = outcome.plan + plan = outcome.plan + lrc = plan.synced_files if plan.options.rmpc_enabled else 0 + 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}" + ) + self._set_status("Sync preview complete. No files were changed.") + self._render_details() + + @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 + self.query_one("#library-summary", Static).update( + f"MP3 tracks {snapshot.total_track_count} · Matched {snapshot.matched_count} · " + f"Unmatched {snapshot.unmatched_count} · Synced {snapshot.synced_count} · " + f"Plain {snapshot.plain_count} · No lyrics {snapshot.no_lyrics_count} · " + f"LRC {snapshot.external_lrc_count} · Attention {snapshot.needs_attention_count}" + ) + + 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 {self.snapshot.total_track_count if self.snapshot else 0}" + ) + if not self.filtered_tracks: + message = "No tracks match the local search or filter." if self.snapshot and self.snapshot.tracks else "No MP3 tracks found." + self.query_one("#library-tracks", Static).update(message) + return + lines = [] + for index, track in enumerate(self.filtered_tracks): + marker = ">" if index == self.selected_index else " " + attention = "!" if track.needs_attention 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 + lines = [ + track.title, + "", + f"Filename {track.filename}", + f"Relative path {track.relative_path}", + f"Full path {track.path}", + f"Matched {track.matched_title or _match_label(track)}", + 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"Attention {'Yes' if track.needs_attention else 'No'}", + ] + if track.warning: + lines.extend(("", f"Warning {track.warning}")) + lines.extend(("", "Sync 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("r refresh · s preview · / search") + return + suffix = "Esc track list · PgUp/PgDn details" if self._details_mode else "Enter details · r refresh · s preview · / search" + 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.generate_preview() + 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 _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 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 "Unmatched" + + +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.NONE: "None", + }[status] + + +def _state_label(status: LibraryStateStatus) -> str: + return { + LibraryStateStatus.CURRENT: "Current", + LibraryStateStatus.NEW: "New", + LibraryStateStatus.CHANGED: "Changed", + LibraryStateStatus.INVALID: "Invalid", + }[status] + + +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 s for a read-only preview." + 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.error: + text += f" · {track.error}" + return text diff --git a/tests/test_library_status.py b/tests/test_library_status.py index a314d17..faed53f 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -5,7 +5,15 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) from juice_lyrics.config.settings import Settings -from juice_lyrics.services.library_status import LibraryStatus, get_library_status +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 @@ -123,3 +131,116 @@ def test_library_status_does_not_contact_api(tmp_path, monkeypatch): ) 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 = tmp_path / "lyrics" / "A Synced.lrc" + lrc.parent.mkdir() + 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), + 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 == 2 + assert snapshot.unmatched_count == 1 + 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 == 2 + assert snapshot.tracks[0].match_status is LibraryMatchStatus.MATCHED + 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[2].match_status is LibraryMatchStatus.UNMATCHED + assert snapshot.tracks[2].lyric_status is LibraryLyricStatus.NONE + + +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 index 464f0fd..eb38872 100644 --- a/tests/test_library_sync_service.py +++ b/tests/test_library_sync_service.py @@ -15,6 +15,7 @@ SyncEventKind, SyncLyricType, execute_library_sync, + get_library_sync_preview, plan_library_sync, ) @@ -189,6 +190,32 @@ def test_dry_run_and_refresh_are_non_mutating(tmp_path): 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")) + + plan = get_library_sync_preview( + Settings(music_dir=tmp_path), + rmpc_enabled=True, + lyrics_dir=tmp_path / "lyrics", + state_file=state_file, + dependencies=deps, + ) + + assert plan.options.dry_run is True + assert plan.ready_files == 1 + assert plan.synced_files == 1 + assert saved == [] + assert path.read_bytes() == b"original" + assert not backup_root.exists() + assert not (tmp_path / "lyrics").exists() + + def test_no_rmpc_suppresses_lrc_and_notification_for_synced_track(tmp_path): path = tmp_path / "Track.mp3" path.write_bytes(b"original") diff --git a/tests/test_tui.py b/tests/test_tui.py index 50a6b00..6c9f689 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -144,11 +144,14 @@ async def scenario(): await pilot.pause() assert app.screen.id == "screen-browse" assert app.query_one("#browse-query") is not None - for key, section in zip("35", ("library", "settings")): - await pilot.press(key) - await pilot.pause() - assert app.screen.id == f"screen-{section}" - assert "planned for a later milestone" in _rendered(app, "#placeholder-message") + 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 "planned for a later milestone" in _rendered(app, "#placeholder-message") await pilot.press("4") await pilot.pause() assert app.screen.id == "screen-downloads" diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py new file mode 100644 index 0000000..e7f2465 --- /dev/null +++ b/tests/test_tui_library.py @@ -0,0 +1,479 @@ +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 ( + CatalogueFilterMetadata, + LibraryLrcStatus, + LibraryLyricStatus, + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryStatus, + LibraryTrack, + QueueSnapshot, +) +from juice_lyrics.services.library_sync import ( + LibrarySyncOptions, + LibrarySyncPlan, + MatchOutcome, + SyncLyricType, + TrackSyncPlan, +) +from juice_lyrics.tui import JuiceLyricsApp + + +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, +) -> LibraryTrack: + path = root / name + lrc_path = root.parent / "lyrics" / f"{path.stem}.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, + ) + + +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=Path(settings.music_dir).parent / "lyrics", + state_file=Path(settings.music_dir).parent / "state.json", + ) + return LibrarySyncPlan(options, tracks, {"files": {}}) + + +def _app(tmp_path: Path, snapshot_provider, preview_provider=None) -> 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_preview_provider=preview_provider or (lambda settings: _plan(settings, ())), + ) + + +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_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 "MP3 tracks 3" in summary and "Matched 2" in summary and "Unmatched 1" in summary + assert "Synced 1" in summary and "Plain 1" in summary and "No lyrics 1" in summary + assert "LRC 1" in summary and "Attention 2" in summary + rows = _text(app, "#library-tracks") + 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 "Unmatched" in details and "No lyrics" in details + assert "Library state New" in details and "Attention Yes" in details + assert "Recorded LRC is missing" 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) + await pilot.press("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 MP3 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 "Preview not generated" 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_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 + await pilot.press("s") + await asyncio.to_thread(started.wait, 2) + assert "Generating sync preview" 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 + 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) + await pilot.press("s") + 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) + await pilot.press("s") + 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", "s") + 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")) From 6ded0dfb3a928c9831270a293c39795a0ff4f9f2 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 30 Aug 2026 10:54:32 +0100 Subject: [PATCH 25/62] Add read-only Settings screen --- PROJECT_CONTEXT.md | 11 +- docs/DEVELOPMENT.md | 12 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 12 +- docs/PROJECT_STATE.md | 20 +- docs/ROADMAP_V2.md | 22 +- src/juice_lyrics/services/__init__.py | 16 + .../services/settings_snapshot.py | 243 +++++++++++++ src/juice_lyrics/tui/app.py | 92 ++++- src/juice_lyrics/tui/screens/__init__.py | 3 +- src/juice_lyrics/tui/screens/settings.py | 329 ++++++++++++++++++ tests/test_core.py | 41 +++ tests/test_settings_snapshot.py | 127 +++++++ tests/test_tui.py | 4 +- tests/test_tui_settings.py | 304 ++++++++++++++++ 14 files changed, 1198 insertions(+), 38 deletions(-) create mode 100644 src/juice_lyrics/services/settings_snapshot.py create mode 100644 src/juice_lyrics/tui/screens/settings.py create mode 100644 tests/test_settings_snapshot.py create mode 100644 tests/test_tui_settings.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 9b407ee..cb1795a 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -274,22 +274,23 @@ The latest development checkpoint reports: * MP3 post-processing with ID3 SYLT/USLT and rmpc LRC integration verified * Settings / Path CLI compatibility verified * responsive terminal-native Textual shell with `ansi_color=True` -* functional read-only Dashboard, Browse, Library, and Downloads screens +* all five main TUI sections are functional and read-only: Dashboard, Browse, Library, Downloads, and Settings * canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details * queue summaries, job navigation, track details, structured failure stages, and retry eligibility * Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews -* Settings remains a placeholder; TUI queue mutations, Browse download actions, and sync execution are not implemented +* Settings reports effective configuration, provenance where reliable, application paths, and rmpc integration without creating or changing files +* TUI queue mutations, Browse download actions, configuration editing, and sync execution are not implemented * legacy CLI remains the way to download, delete jobs, and sync -* 197 automated tests passing across the suite +* 213 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, but no rename or migration has been performed. Native FLAC support remains planned. -Recommended next milestones are: Settings, Browse-to-download job creation, -Downloads Run/Retry/Delete actions, Library sync actions, the `999` +Recommended next milestones are: Browse-to-download job creation, Downloads +Run/Retry/Delete actions, Library sync actions, the `999` naming migration, native FLAC support, then beta polish and release testing. To resume: diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index f98e128..701a261 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -60,8 +60,8 @@ From an editable installation, launch the early read-only TUI shell with: juice-lyrics tui ``` -The experimental shell provides a read-only Dashboard plus functional, -read-only Browse, Library, and Downloads screens. Press `/` to focus catalogue search and Enter to +The experimental shell provides functional read-only Dashboard, Browse, +Library, Downloads, and Settings screens. 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 @@ -94,6 +94,14 @@ rmpc changes are made. The existing API cache may be updated by that explicit preview. Actual library sync remains CLI-only via `juice-lyrics sync`. The scanner is currently MP3-focused; native FLAC support remains planned. +In Settings, arrows or `j`/`k` inspect effective configuration values, paths, +and environment details; Home/End and PageUp/PageDown navigate longer content. +The view reports the active config file, reliable default/config/runtime source +labels, path existence, and whether rmpc is detected and configured. Press `r` +to refresh. The screen is strictly read-only: configuration changes and setup +remain CLI-only, no missing XDG paths are created, the scanner remains MP3-only, +and native FLAC support remains planned. + ## Source of truth and Git workflow 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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index bc3248c..a31506b 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -52,7 +52,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -197 passing tests. +213 passing tests. Completed and integrated: @@ -80,11 +80,13 @@ functional read-only Dashboard and Browse screens, canonical Category and Era selectors, correct case-sensitive API cache behavior, server-side catalogue pagination with scrollable 50-result pages, stable ID-based song details, and a read-only Downloads screen with queue summaries, job navigation, track details, -failure stages, and retry eligibility, plus a read-only Library screen with -local track browsing, filters, details, and explicit sync previews. +failure stages, and retry eligibility, a read-only Library screen with local +track browsing, filters, details, and explicit sync previews, and a read-only +Settings screen with effective configuration, paths, provenance, and rmpc state. -Settings remains a placeholder. Browse download actions, TUI queue mutations, -and sync execution are not implemented. The legacy CLI remains the way to +All five primary TUI sections are functional and read-only. Browse download +actions, TUI queue mutations, configuration editing, and sync execution are not +implemented. The legacy CLI remains the way to download, delete jobs, and sync. Native FLAC support remains planned. The planned product/executable name remains `999`; package, distribution, and data paths have not been renamed. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 3381011..113c598 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -2,7 +2,7 @@ ## Current Status Backend services remain stable and the experimental Textual frontend is -integrated as a read-only presentation layer. The current checkpoint has 197 +integrated as a read-only presentation layer. The current checkpoint has 213 passing tests. ## Current Branch @@ -15,10 +15,11 @@ v2-redesign ## Completed and integrated - Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. -- Responsive terminal-native Textual shell with functional read-only Dashboard, Browse, Library, and Downloads screens. +- Responsive terminal-native Textual shell with all five main sections functional and read-only: Dashboard, Browse, Library, Downloads, and Settings. - Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. - Downloads queue summaries, job navigation, track details, structured failure stages, and retry eligibility. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. +- Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. ## Available through the CLI @@ -28,7 +29,7 @@ and sync the library. ## Current limitations -- Settings remains a placeholder. +- Configuration editing remains CLI-only. - TUI queue mutations and Browse download actions are not implemented. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and @@ -43,13 +44,12 @@ and sync the library. ## Recommended next milestones -1. Settings screen -2. Browse-to-download job creation -3. Downloads Run/Retry/Delete actions -4. Library sync actions -5. `999` command and naming migration -6. Native FLAC support -7. Beta polish, packaging, and release testing +1. Browse-to-download job creation +2. Downloads Run/Retry/Delete actions +3. Library sync actions +4. `999` command and naming migration +5. Native FLAC support +6. Beta polish, packaging, and release testing ## Resume development diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 2f3b089..0a3ab0a 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -133,9 +133,8 @@ Goal: Create the main application interface. -Status: In progress. The responsive terminal-native shell, Dashboard, Browse, -Library, and read-only Downloads screen are integrated. Settings remains a -placeholder, and the TUI remains read-only. +Status: In progress. The responsive terminal-native shell and all five primary +sections are integrated as read-only screens. Mutating workflows remain CLI-only. Screens: @@ -191,7 +190,9 @@ Features: - rmpc settings. - API settings. -Status: Placeholder. +Status: Read-only functionality complete, including effective configuration, +path existence, provenance where reliable, rmpc integration state, and current +capability limitations. Editing remains planned. --- @@ -199,13 +200,12 @@ Status: Placeholder. Recommended implementation order after the current checkpoint: -1. Settings screen -2. Browse-to-download job creation -3. Downloads Run/Retry/Delete actions -4. Library sync actions -5. `999` command and naming migration -6. Native FLAC support -7. Beta polish, packaging, and release testing +1. Browse-to-download job creation +2. Downloads Run/Retry/Delete actions +3. Library sync actions +4. `999` command and naming migration +5. Native FLAC support +6. Beta polish, packaging, and release testing Possible future improvements: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 9e5aeb2..6af03ac 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -49,6 +49,15 @@ get_library_sync_preview, plan_library_sync, ) +from .settings_snapshot import ( + IntegrationSnapshot, + IntegrationStatus, + SettingValue, + SettingsPath, + SettingsSnapshot, + SettingsSource, + get_settings_snapshot, +) __all__ = [ "CatalogueSearchResult", @@ -62,6 +71,8 @@ "LibrarySnapshot", "LibraryStateStatus", "LibraryTrack", + "IntegrationSnapshot", + "IntegrationStatus", "LibrarySyncDependencies", "LibrarySyncOptions", "LibrarySyncPlan", @@ -74,6 +85,10 @@ "QueueReferenceError", "QueueSnapshot", "QueueStatus", + "SettingValue", + "SettingsPath", + "SettingsSnapshot", + "SettingsSource", "SongDetails", "SyncEvent", "SyncEventKind", @@ -86,6 +101,7 @@ "get_queue_snapshot", "get_library_status", "get_library_snapshot", + "get_settings_snapshot", "get_song_details", "get_song_details_by_id", "plan_library_sync", diff --git a/src/juice_lyrics/services/settings_snapshot.py b/src/juice_lyrics/services/settings_snapshot.py new file mode 100644 index 0000000..78669d7 --- /dev/null +++ b/src/juice_lyrics/services/settings_snapshot.py @@ -0,0 +1,243 @@ +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_RMPC_LYRICS_DIR, + 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) -> bool: + return ( + re.search(r"(?im)^\s*lyrics_dir\s*:\s*some\s*\(", text) is not None + 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, + 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")) + 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 its lyrics integration is configured." + else: + status = IntegrationStatus.DETECTED_NOT_CONFIGURED + detail = "rmpc is detected, but lyrics integration is not configured." + 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, + lyrics_dir: Path = DEFAULT_RMPC_LYRICS_DIR, + 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 + + values = tuple( + SettingValue( + key, + label, + getattr(settings, key), + default, + _source_for(key, getattr(settings, key), default, config), + ) + for key, label, default in _SETTING_SPECS + ) + paths = tuple( + _inspect_path(key, label, Path(path)) + for key, label, path in ( + ("music", "Music library", settings.music_dir), + ("lyrics", "rmpc lyrics", lyrics_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), executable_finder), + application_version=__version__, + limitations=( + "Local library scanning currently supports MP3 files only.", + "Native FLAC support is planned but not implemented.", + "Browse and Downloads remain read-only in the TUI.", + "Library sync execution remains CLI-only.", + "Configuration changes remain CLI-only.", + ), + warnings=warnings, + ) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index e295fee..de8e486 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -17,12 +17,13 @@ ) from ..services.library_status import LibrarySnapshot, LibraryStatus, get_library_snapshot, get_library_status from ..services.library_sync import LibrarySyncPlan, 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 LibraryScreen -from .screens.placeholder import PlaceholderScreen +from .screens.settings import SettingsScreen LibraryStatusProvider = Callable[[Any], LibraryStatus] QueueSnapshotProvider = Callable[[], QueueSnapshot] @@ -31,6 +32,7 @@ CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] +SettingsSnapshotProvider = Callable[[Any], SettingsSnapshot] class JuiceLyricsApp(App[None]): @@ -398,6 +400,66 @@ class JuiceLyricsApp(App[None]): 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; @@ -511,6 +573,22 @@ class JuiceLyricsApp(App[None]): 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__( @@ -525,6 +603,7 @@ def __init__( downloads_queue_provider: QueueSnapshotProvider | None = None, library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, + settings_snapshot_provider: SettingsSnapshotProvider = get_settings_snapshot, ) -> None: super().__init__(ansi_color=True) self.settings = settings @@ -536,6 +615,7 @@ def __init__( self.downloads_queue_provider = downloads_queue_provider or queue_snapshot_provider self.library_snapshot_provider = library_snapshot_provider self.library_preview_provider = library_preview_provider + self.settings_snapshot_provider = settings_snapshot_provider def on_mount(self) -> None: self.install_screen( @@ -568,7 +648,10 @@ def on_mount(self) -> None: "downloads", ) self.install_screen( - PlaceholderScreen("Settings", "Configuration viewing and editing are planned for a later milestone."), + SettingsScreen( + self.settings, + snapshot_provider=self.settings_snapshot_provider, + ), "settings", ) self.push_screen("dashboard") @@ -603,6 +686,11 @@ def action_show_help(self) -> None: "↑/↓ or j/k select tracks • / local search • Home/End first/last • " "PgUp/PgDn move tracks • Enter details • s read-only sync preview • r refresh" ) + elif section == "settings": + message = ( + "↑/↓ or j/k inspect settings • Home/End first/last • " + "PgUp/PgDn scroll • r refresh • read-only; configuration changes remain CLI-only" + ) else: message = "1–5 switch sections • r refreshes Dashboard • q quits" self.notify(message, timeout=5) diff --git a/src/juice_lyrics/tui/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py index a1f2d53..e503bcb 100644 --- a/src/juice_lyrics/tui/screens/__init__.py +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -4,6 +4,7 @@ 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"] +__all__ = ["BrowseScreen", "DashboardScreen", "DownloadsScreen", "LibraryScreen", "PlaceholderScreen", "SettingsScreen"] diff --git a/src/juice_lyrics/tui/screens/settings.py b/src/juice_lyrics/tui/screens/settings.py new file mode 100644 index 0000000..63426d5 --- /dev/null +++ b/src/juice_lyrics/tui/screens/settings.py @@ -0,0 +1,329 @@ +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 view — configuration changes remain CLI-only", + 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-configuration-panel"): + yield Static("Configuration", classes="panel-title") + yield Static("Loading…", id="settings-configuration", markup=False) + with Container(classes="settings-panel", id="settings-paths-panel"): + yield Static("Paths", classes="panel-title") + yield Static("Loading…", id="settings-paths", markup=False) + with Container(classes="settings-panel", id="settings-integrations-panel"): + yield Static("Integrations", classes="panel-title") + yield Static("Loading…", id="settings-integrations", 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("r refresh · ↑/↓ or j/k inspect · PgUp/PgDn scroll", 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 snapshot worker failed") + 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)} · r refresh · PgUp/PgDn scroll" + ) + + 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, ...]: + config_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, + ), + ] + config_rows.extend(_value_row(item) for item in snapshot.values) + path_rows = [_path_row(item) for item in snapshot.paths] + integration_rows = [ + SettingsRow( + "integrations", + "rmpc status", + _integration_label(snapshot.rmpc.status), + snapshot.rmpc.detail, + ), + SettingsRow( + "integrations", + "rmpc executable", + str(snapshot.rmpc.executable or "Not detected"), + str(snapshot.rmpc.executable or "rmpc was not found in PATH."), + ), + SettingsRow( + "integrations", + "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) + ] + return tuple((*config_rows, *path_rows, *integration_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) -> SettingsRow: + state = "Exists" if item.exists else "Missing" + warning = f" · Inspection warning: {item.warning}" if item.warning else "" + return SettingsRow( + "paths", + 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/test_core.py b/tests/test_core.py index 2d52bbe..fc846b0 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -2,6 +2,8 @@ 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 @@ -155,3 +157,42 @@ def test_command_guide(capsys): assert "juice-lyrics quick guide" in out assert "juice-lyrics acquire search" in out assert "juice-lyrics sync" 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 + assert capsys.readouterr().out == content + "\n" + + +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() diff --git a/tests/test_settings_snapshot.py b/tests/test_settings_snapshot.py new file mode 100644 index 0000000..8a2327e --- /dev/null +++ b/tests/test_settings_snapshot.py @@ -0,0 +1,127 @@ +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): + return get_settings_snapshot( + settings or Settings(music_dir=tmp_path / "music"), + 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", + lyrics_dir=tmp_path / "lyrics", + 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' + '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, + 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["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, 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 files only" in snapshot.limitations[0] + assert any("FLAC" in item for item in snapshot.limitations) + assert not (tmp_path / "cache").exists() + assert not (tmp_path / "data").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_tui.py b/tests/test_tui.py index 6c9f689..52291bd 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -135,7 +135,7 @@ async def scenario(): asyncio.run(scenario()) -def test_keyboard_navigation_reaches_functional_and_placeholder_screens(tmp_path): +def test_keyboard_navigation_reaches_all_functional_screens(tmp_path): async def scenario(): app = _app(tmp_path) async with app.run_test() as pilot: @@ -151,7 +151,7 @@ async def scenario(): await pilot.press("5") await pilot.pause() assert app.screen.id == "screen-settings" - assert "planned for a later milestone" in _rendered(app, "#placeholder-message") + assert app.query_one("#settings-configuration") is not None await pilot.press("4") await pilot.pause() assert app.screen.id == "screen-downloads" diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py new file mode 100644 index 0000000..27ffc80 --- /dev/null +++ b/tests/test_tui_settings.py @@ -0,0 +1,304 @@ +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("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("lyrics", "rmpc lyrics", tmp_path / "lyrics", False), + 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 currently supports MP3 files only.", + "Native FLAC support is planned but not implemented.", + "Browse and Downloads remain 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 view — configuration changes remain CLI-only" in _text(app, "#settings-warning") + configuration = _text(app, "#settings-configuration") + assert "config.toml" in configuration + assert str(tmp_path / "config.toml") in _text(app, "#settings-detail") + assert "Music directory" in configuration and "[Config file]" in configuration + assert "API base URL" in configuration and "[Default]" in configuration + assert "Duration tolerance" in configuration and "[Runtime override]" in configuration + paths = _text(app, "#settings-paths") + assert "Music library" in paths and "[Exists]" in paths + assert "rmpc lyrics" in paths and "[Missing]" in paths + assert "Detected and configured" in _text(app, "#settings-integrations") + capabilities = _text(app, "#settings-capabilities") + assert "MP3 files only" in capabilities and "FLAC support is planned" in capabilities + assert "Library sync execution remains CLI-only" in capabilities + + await pilot.press("down", "j") + assert screen.selected_index == 2 + assert "Music directory" 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") + 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 "Read-only settings view" 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")) From 37bf048e7c31681a4a2dffa7bf5e920354adaab4 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 31 Aug 2026 12:02:18 +0100 Subject: [PATCH 26/62] Add user-facing download queue --- PROJECT_CONTEXT.md | 18 +- docs/DECISIONS.md | 15 + docs/DEVELOPMENT.md | 25 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 27 +- docs/PROJECT_STATE.md | 22 +- docs/ROADMAP_V2.md | 13 +- docs/UI_DESIGN.md | 10 + docs/USER_FLOWS.md | 16 + src/juice_lyrics/services/__init__.py | 26 ++ .../services/acquisition_queue.py | 11 + src/juice_lyrics/services/download_queue.py | 314 ++++++++++++++++++ src/juice_lyrics/tui/app.py | 96 +++++- src/juice_lyrics/tui/screens/browse.py | 219 +++++++++++- src/juice_lyrics/tui/screens/downloads.py | 296 ++++++----------- tests/test_download_queue_service.py | 176 ++++++++++ tests/test_tui.py | 2 +- tests/test_tui_browse.py | 230 ++++++++++++- tests/test_tui_downloads.py | 75 +++-- 18 files changed, 1312 insertions(+), 279 deletions(-) create mode 100644 src/juice_lyrics/services/download_queue.py create mode 100644 tests/test_download_queue_service.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index cb1795a..8eb4af6 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -223,6 +223,12 @@ The job system should: * recover interrupted states * avoid losing successful completed items when another item fails +Persistent jobs are an internal durability and execution mechanism. The normal +product model is a flat download queue of songs; UUIDs should stay out of common +workflows. Browse can explicitly add one selected song to this queue without +starting it. Completed items remain stored but are hidden from the active queue, +and failed items remain visible for future retry or removal. + ## Acquisition → lyrics integration After successful MP3 acquisition, an optional post-processing hook uses the existing lyrics engine. @@ -274,23 +280,23 @@ The latest development checkpoint reports: * MP3 post-processing with ID3 SYLT/USLT and rmpc LRC integration verified * Settings / Path CLI compatibility verified * responsive terminal-native Textual shell with `ansi_color=True` -* all five main TUI sections are functional and read-only: Dashboard, Browse, Library, Downloads, and Settings +* all five main TUI sections are functional; Browse can explicitly add one selected song to the queue * canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details -* queue summaries, job navigation, track details, structured failure stages, and retry eligibility +* flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility * Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews * Settings reports effective configuration, provenance where reliable, application paths, and rmpc integration without creating or changing files -* TUI queue mutations, Browse download actions, configuration editing, and sync execution are not implemented +* TUI download execution, remove, clear, retry, cancel, configuration editing, and sync execution are not implemented * legacy CLI remains the way to download, delete jobs, and sync -* 213 automated tests passing across the suite +* 220 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, but no rename or migration has been performed. Native FLAC support remains planned. -Recommended next milestones are: Browse-to-download job creation, Downloads -Run/Retry/Delete actions, Library sync actions, the `999` +Recommended next milestones are: Downloads Download selected / Download all, +Remove / Clear / Retry actions, Library sync actions, the `999` naming migration, native FLAC support, then beta polish and release testing. To resume: diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 589f840..ec2d149 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -117,6 +117,21 @@ Prefer: - 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. + +The planned queue actions are Download selected, Download all, Remove, Clear, +Retry, and Cancel. Each mutating action requires its own explicit safe workflow. + The backend can remain technical while the user interface becomes friendly. --- diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 701a261..5b399b7 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -60,8 +60,9 @@ From an editable installation, launch the early read-only TUI shell with: juice-lyrics tui ``` -The experimental shell provides functional read-only Dashboard, Browse, -Library, Downloads, and Settings screens. Press `/` to focus catalogue search and Enter to +The experimental shell provides functional Dashboard, Browse, Library, +Downloads, and Settings screens. Inspection remains read-only; Browse has one +explicit Add to queue action. 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 @@ -69,18 +70,22 @@ 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. Global keys remain `1`–`5` for sections, `?` for help, and `q` -to quit. Browse does not download media, create jobs, sync lyrics, edit settings, -or modify the local library. +current API page. Press `a` on a downloadable result to review its resolved +destination and explicitly add it to the download queue. The cancel-first dialog +states that adding 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, use arrows or `j`/`k` to select a job, Home/End for the first or -last job, and PageUp/PageDown to move through longer job lists. Enter opens the -selected job's scrollable track details and Escape returns to the job list. -Press `r` to refresh the read-only queue snapshot. Run, Retry, Delete, Cancel, -and Download actions are intentionally unavailable in this milestone. +In Downloads, 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. Download selected, Download all, Remove, Clear, Retry, and +Cancel are intentionally unavailable in this milestone. Existing queued songs +must still be run through the CLI. In Library, arrows or `j`/`k` select local MP3 tracks, Home/End select the first or last track, and PageUp/PageDown move through longer lists. Press `/` for a diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index a31506b..3d3eba7 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -52,7 +52,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -213 passing tests. +220 passing tests. Completed and integrated: @@ -76,18 +76,21 @@ Verified systems: - CLI workflows The v2 frontend now also includes a responsive terminal-native Textual shell, -functional read-only Dashboard and Browse screens, canonical Category and Era +functional Dashboard and Browse screens, canonical Category and Era selectors, correct case-sensitive API cache behavior, server-side catalogue pagination with scrollable 50-result pages, stable ID-based song details, and a -read-only Downloads screen with queue summaries, job navigation, track details, -failure stages, and retry eligibility, a read-only Library screen with local +Downloads screen with a flat track queue, song navigation, details, failure +stages, retry eligibility, and an explicit Browse Add to queue flow that never +starts a download, a read-only Library screen with local track browsing, filters, details, and explicit sync previews, and a read-only Settings screen with effective configuration, paths, provenance, and rmpc state. -All five primary TUI sections are functional and read-only. Browse download -actions, TUI queue mutations, configuration editing, and sync execution are not -implemented. The legacy CLI remains the way to -download, delete jobs, and sync. Native FLAC support remains planned. The planned +All five primary TUI sections are functional. Browse may add one explicitly +confirmed song to the queue; Downloads execution, retry, remove, clear, and +cancel actions, configuration editing, and sync execution are not implemented. +Durable jobs remain an internal backend detail and completed entries are hidden +from the active track queue. The legacy CLI remains the way to run downloads, +delete jobs, and sync. Native FLAC support remains planned. The planned product/executable name remains `999`; package, distribution, and data paths have not been renamed. @@ -351,9 +354,11 @@ Downloading 65% Lemon Glow Complete -The current Downloads implementation is read-only. It shows queue totals, -jobs, tracks, structured failures, and retry eligibility. Retry, cancel, remove, -and other queue mutations are not yet implemented. +The current Downloads implementation is a read-only flat track queue. It shows +queue totals, individual songs, structured failures, and retry eligibility; +internal jobs are hidden except for optional troubleshooting references. Browse +can add one explicitly confirmed song without starting it. Download execution, +retry, cancel, remove, clear, and other queue mutations are not yet implemented. --- diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 113c598..d288d83 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,9 +1,9 @@ # 999 Project State ## Current Status -Backend services remain stable and the experimental Textual frontend is -integrated as a read-only presentation layer. The current checkpoint has 213 -passing tests. +Backend services remain stable. The experimental Textual frontend remains +read-only except for one explicit, confirmed Add to queue action. The current +checkpoint has 220 passing tests. ## Current Branch v2-redesign @@ -15,22 +15,24 @@ v2-redesign ## Completed and integrated - Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. -- Responsive terminal-native Textual shell with all five main sections functional and read-only: Dashboard, Browse, Library, Downloads, and Settings. +- Responsive terminal-native Textual shell with all five main sections functional; inspection remains read-only and Browse has one explicit Add to queue mutation. - Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. -- Downloads queue summaries, job navigation, track details, structured failure stages, and retry eligibility. +- Track-oriented Downloads queue summaries, song navigation, details, structured failures, and retry eligibility; durable jobs are hidden as an internal mechanism. +- Explicit cancel-first Browse Add to queue flow; adding persists one queued song but never starts downloading. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. - Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. ## Available through the CLI -The legacy CLI remains the supported way to download, delete acquisition jobs, -and sync the library. +The legacy CLI remains the supported way to run downloads, delete durable +acquisition records, and sync the library. ## Current limitations - Configuration editing remains CLI-only. -- TUI queue mutations and Browse download actions are not implemented. +- TUI Download, Remove, Clear, Retry, and Cancel actions are not implemented. +- Browse currently adds one song at a time; multi-select remains planned. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and data paths remain named `juice-lyrics`. @@ -44,8 +46,8 @@ and sync the library. ## Recommended next milestones -1. Browse-to-download job creation -2. Downloads Run/Retry/Delete actions +1. Downloads Download selected / Download all execution +2. Downloads Remove / Clear / Retry actions 3. Library sync actions 4. `999` command and naming migration 5. Native FLAC support diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 0a3ab0a..25b5d23 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -134,7 +134,8 @@ Goal: Create the main application interface. Status: In progress. The responsive terminal-native shell and all five primary -sections are integrated as read-only screens. Mutating workflows remain CLI-only. +sections are integrated. Browse has an explicit confirmed Add to queue action; +download execution and other mutations remain CLI-only. Screens: @@ -177,8 +178,10 @@ Features: - Completed items. - Retry. -Status: Read-only queue view complete. Run, Retry, Delete, and Cancel actions -remain planned. +Status: Track-oriented queue projection and Browse Add to queue are complete. +Durable jobs remain internal, completed entries are hidden from the active +queue, and failed entries remain visible. Download selected, Download all, +Remove, Clear, Retry, and Cancel remain planned. --- @@ -200,8 +203,8 @@ capability limitations. Editing remains planned. Recommended implementation order after the current checkpoint: -1. Browse-to-download job creation -2. Downloads Run/Retry/Delete actions +1. Downloads Download selected / Download all execution +2. Downloads Remove / Clear / Retry actions 3. Library sync actions 4. `999` command and naming migration 5. Native FLAC support diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 2cb260a..3011165 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -298,6 +298,16 @@ 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 `a` to open an explicit Add to queue confirmation. The dialog shows +the resolved destination and states that adding will not start a download. +Future queue actions are Download selected, Download all, Remove, Clear, Retry, +and Cancel. + Example: diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 51c69aa..f470a58 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -254,6 +254,22 @@ Too technical. --- +v2 user-facing model: + +Browse → select a song → press `a` → review destination → Add to 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. + +Planned follow-up interactions include Space to toggle multiple selections, +`a` to add selected songs, and a bounded explicitly confirmed `A` action. The +application will not bulk-fetch an unbounded catalogue merely to fill a queue. + +Future queue actions are Download selected, Download all, Remove, Clear queue, +Retry failed, and Cancel active download. + v2: User selects: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 6af03ac..22bd1d9 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -23,6 +23,20 @@ search_catalogue, search_catalogue_page, ) +from .download_queue import ( + DownloadQueueItem, + DownloadQueueItemStatus, + DownloadQueueSnapshot, + PlannedQueueItem, + QueueAddPlan, + QueueAddResult, + QueueAddStatus, + QueueDuplicateReason, + add_to_download_queue, + get_download_queue_snapshot, + plan_queue_additions, + project_download_queue, +) from .library_status import ( LibraryLrcStatus, LibraryLyricStatus, @@ -64,6 +78,9 @@ "CatalogueFilterMetadata", "CatalogueFilterOption", "CataloguePage", + "DownloadQueueItem", + "DownloadQueueItemStatus", + "DownloadQueueSnapshot", "LibraryStatus", "LibraryLrcStatus", "LibraryLyricStatus", @@ -80,6 +97,11 @@ "LyricAvailability", "MatchOutcome", "QueueItem", + "PlannedQueueItem", + "QueueAddPlan", + "QueueAddResult", + "QueueAddStatus", + "QueueDuplicateReason", "QueueFailureStage", "QueueJob", "QueueReferenceError", @@ -98,6 +120,7 @@ "execute_library_sync", "get_library_sync_preview", "get_catalogue_filters", + "get_download_queue_snapshot", "get_queue_snapshot", "get_library_status", "get_library_snapshot", @@ -105,6 +128,9 @@ "get_song_details", "get_song_details_by_id", "plan_library_sync", + "plan_queue_additions", + "project_download_queue", + "add_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 index e860b76..5185144 100644 --- a/src/juice_lyrics/services/acquisition_queue.py +++ b/src/juice_lyrics/services/acquisition_queue.py @@ -46,6 +46,8 @@ class QueueItem: 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) @@ -212,6 +214,15 @@ def _queue_item(raw: Any) -> QueueItem: 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 () + ) + ), ) diff --git a/src/juice_lyrics/services/download_queue.py b/src/juice_lyrics/services/download_queue.py new file mode 100644 index 0000000..09a6a84 --- /dev/null +++ b/src/juice_lyrics/services/download_queue.py @@ -0,0 +1,314 @@ +from __future__ import annotations + +from collections.abc import Callable, Sequence +from dataclasses import dataclass +from enum import Enum +from pathlib import Path + +from ..acquisition.duplicates import DuplicateMatch, find_duplicate +from ..acquisition.jobs import DEFAULT_JOBS_FILE, AcquisitionJob, JobStore, JobStoreError +from ..acquisition.models import AcquisitionItem +from ..acquisition.resolver import ResourceResolutionError, resolve_resource +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" + + +@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} + + +QueueReader = Callable[[Path], QueueSnapshot] +Resolver = Callable[..., AcquisitionItem] +DuplicateFinder = Callable[..., DuplicateMatch | None] +StoreFactory = Callable[[Path], JobStore] + + +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, + ) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index de8e486..bb3a9d1 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -15,6 +15,13 @@ get_song_details_by_id, search_catalogue_page, ) +from ..services.download_queue import ( + DownloadQueueSnapshot, + QueueAddResult, + add_to_download_queue, + plan_queue_additions, + project_download_queue, +) from ..services.library_status import LibrarySnapshot, LibraryStatus, get_library_snapshot, get_library_status from ..services.library_sync import LibrarySyncPlan, get_library_sync_preview from ..services.settings_snapshot import SettingsSnapshot, get_settings_snapshot @@ -27,6 +34,9 @@ LibraryStatusProvider = Callable[[Any], LibraryStatus] QueueSnapshotProvider = Callable[[], QueueSnapshot] +DownloadQueueProvider = Callable[[], DownloadQueueSnapshot] +QueuePlanProvider = Callable[..., QueueAddResult] +QueueAddProvider = Callable[..., QueueAddResult] CatalogueSearchProvider = Callable[..., CataloguePage] CatalogueDetailsProvider = Callable[..., SongDetails | None] CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] @@ -259,6 +269,55 @@ class JuiceLyricsApp(App[None]): color: ansi_default; } + AddToQueueDialog { + align: center middle; + background: transparent; + } + + #queue-confirm-dialog { + width: 72; + max-width: 92%; + height: auto; + 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; + } + #downloads-summary { height: 2; padding: 0 1; @@ -289,7 +348,7 @@ class JuiceLyricsApp(App[None]): padding: 0 1; } - #download-jobs-scroll, + #download-queue-scroll, #download-details-scroll { height: 1fr; overflow-y: scroll; @@ -301,7 +360,7 @@ class JuiceLyricsApp(App[None]): scrollbar-corner-color: transparent; } - #download-jobs, + #download-queue, #download-details { height: auto; background: transparent; @@ -525,7 +584,7 @@ class JuiceLyricsApp(App[None]): grid-rows: 1fr; } - Screen.-downloads-narrow.-details-mode #download-jobs-panel { + Screen.-downloads-narrow.-details-mode #download-queue-panel { display: none; } @@ -600,7 +659,9 @@ def __init__( 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: QueueSnapshotProvider | None = None, + downloads_queue_provider: DownloadQueueProvider | None = None, + queue_plan_provider: QueuePlanProvider = plan_queue_additions, + queue_add_provider: QueueAddProvider = add_to_download_queue, library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, settings_snapshot_provider: SettingsSnapshotProvider = get_settings_snapshot, @@ -612,7 +673,17 @@ def __init__( self.catalogue_search_provider = catalogue_search_provider self.catalogue_details_provider = catalogue_details_provider self.catalogue_filters_provider = catalogue_filters_provider - self.downloads_queue_provider = downloads_queue_provider or queue_snapshot_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.library_snapshot_provider = library_snapshot_provider self.library_preview_provider = library_preview_provider self.settings_snapshot_provider = settings_snapshot_provider @@ -632,6 +703,8 @@ def on_mount(self) -> None: 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", ) @@ -661,6 +734,12 @@ def action_show_section(self, section: str) -> None: return self.switch_screen(section) + def invalidate_download_queue(self) -> None: + downloads = self.get_screen("downloads") + invalidate = getattr(downloads, "invalidate_snapshot", None) + if callable(invalidate): + invalidate() + def action_refresh_active(self) -> None: refresh = getattr(self.screen, "refresh_snapshot", None) if callable(refresh): @@ -674,12 +753,13 @@ def action_show_help(self) -> None: message = ( "n next catalogue page • p previous catalogue page • " "PageDown/PageUp scroll the loaded results • " - "Home/End first/last loaded result • j/k select • Enter details" + "Home/End first/last loaded result • j/k select • Enter details • " + "a add selected song to queue" ) elif section == "downloads": message = ( - "↑/↓ or j/k select jobs • Home/End first/last job • " - "PgUp/PgDn move jobs • Enter track details • Esc job list • r refresh" + "↑/↓ or j/k select songs • Home/End first/last song • " + "PgUp/PgDn move queue • Enter track details • Esc queue • r refresh" ) elif section == "library": message = ( diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py index 0975e68..a58cc0e 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -13,6 +13,7 @@ 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 @@ -24,11 +25,14 @@ LyricAvailability, SongDetails, ) +from ...services.download_queue import QueueAddPlan, QueueAddResult, QueueAddStatus from .base import HubScreen SearchProvider = Callable[..., CataloguePage | tuple[CatalogueSearchResult, ...]] DetailsProvider = Callable[..., SongDetails | None] FiltersProvider = Callable[..., CatalogueFilterMetadata] +QueuePlanProvider = Callable[..., QueueAddResult] +QueueAddProvider = Callable[[QueueAddPlan], QueueAddResult] _PREVIEW_LINES = 6 _PAGE_SIZE = 50 @@ -121,6 +125,165 @@ class FiltersOutcome: error: str | None = None +@dataclass(frozen=True, slots=True) +class QueuePlanOutcome: + selection: CatalogueSearchResult + result: QueueAddResult | None = None + error: str | None = None + + +class QueueDialogAction(Static): + can_focus = False + + 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[QueueAddResult | None]): + """Explicit, cancel-first confirmation for one durable queue addition.""" + + def __init__(self, plan: QueueAddPlan, creator: QueueAddProvider) -> None: + super().__init__() + self.plan = plan + self._creator = creator + self._choice = "cancel" + self._creating = False + self._created_result: QueueAddResult | None = None + self._worker: Worker[QueueAddResult] | None = None + + def compose(self) -> ComposeResult: + planned = self.plan.items[0] + item = planned.item + with Container(id="queue-confirm-dialog"): + yield Static("Add to download queue", id="queue-confirm-title") + yield Static( + "\n".join(( + f"Song {item.title}", + f"Artist {planned.artist or 'Unknown'}", + f"Category {planned.category or 'Unknown'}", + f"Era {planned.era or 'Unknown'}", + f"Destination {item.destination}", + "Availability Available", + "", + "This adds the song to your download queue. It will not start downloading yet.", + )), + 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("Add to queue", "confirm", id="queue-confirm-add") + yield QueueDialogAction("Cancel", "cancel", id="queue-confirm-cancel") + + def on_mount(self) -> None: + self._render_choice() + + 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 = "[Add to queue]" if self._choice == "confirm" else "Add to queue" + 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() + 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) -> QueueAddResult: + try: + return self._creator(self.plan) + except Exception as exc: + 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 = QueueAddResult(QueueAddStatus.SAVE_FAILED, "Unable to save the queue.") + else: + return + self._creating = False + if result.status is QueueAddStatus.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.""" @@ -133,12 +296,16 @@ def __init__( 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 @@ -146,6 +313,7 @@ def __init__( 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._applying_filters = False def compose_content(self) -> Iterable[Widget]: @@ -275,6 +443,14 @@ def _run_details(self, result: CatalogueSearchResult) -> DetailsOutcome: 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, selection: CatalogueSearchResult) -> QueuePlanOutcome: + try: + result = self._queue_plan_provider(self.settings, (selection,)) + return QueuePlanOutcome(selection, result) + except Exception as exc: + return QueuePlanOutcome(selection, 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: @@ -294,6 +470,32 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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) + + def _apply_queue_plan(self, outcome: QueuePlanOutcome) -> None: + if self.app.screen is not self: + return + if not self.results or self.results[self.selected_index] != outcome.selection: + 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 + if outcome.result.status is not QueueAddStatus.READY or outcome.result.plan is None: + self._set_status(outcome.result.message, error=True) + return + self.app.push_screen( + AddToQueueDialog(outcome.result.plan, self._queue_add_provider), + self._queue_dialog_closed, + ) + + def _queue_dialog_closed(self, result: QueueAddResult | None) -> None: + if result is not None and result.status is QueueAddStatus.ADDED: + self._set_status(f"{result.message} It has not started. Press 4 to view Downloads.") def _apply_search(self, outcome: SearchOutcome) -> None: if outcome.error: @@ -366,6 +568,8 @@ def on_key(self, event: Key) -> None: self._move_selection(-1) elif event.key == "enter": self._load_selected_details() + elif event.key == "a": + self._add_selected_to_queue() elif event.key == "n": self._change_page(next_page=True) elif event.key == "p": @@ -383,6 +587,17 @@ def on_key(self, event: Key) -> None: event.prevent_default() event.stop() + def _add_selected_to_queue(self) -> None: + if not self.results: + self._set_status("Select a downloadable song first.", error=True) + return + selection = self.results[self.selected_index] + if not selection.downloadable: + self._set_status("Media unavailable; this song cannot be added to the queue.", error=True) + return + self._set_status("Checking destination and download queue…") + self._queue_plan_worker = self._plan_queue_add(selection) + def _change_page(self, *, next_page: bool) -> None: if self.current_page is None or self.last_request is None: return @@ -508,6 +723,7 @@ def _render_summary(self, result: CatalogueSearchResult) -> None: f"Path {path}", "", "Press Enter for full details and lyric preview.", + "Press a to add this song to the download queue." if result.downloadable else "Media unavailable.", ) self.query_one("#browse-details", Static).update("\n".join(lines)) @@ -547,7 +763,8 @@ def _result_status(self, request: SearchRequest, page: CataloguePage) -> str: selected = min(len(page.results), self.selected_index + 1) return ( f"Result {selected} of {len(page.results)} loaded · n/p pages · " - f"j/k select · PgUp/PgDn scroll · Enter details.{filters}" + f"j/k select · PgUp/PgDn scroll · Enter details" + f"{' · a add to queue' if self.results and self.results[self.selected_index].downloadable else ''}.{filters}" ) def on_resize(self, event: Resize) -> None: diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py index 1955363..edf4de2 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -13,64 +13,59 @@ from textual.widgets import Static from textual.worker import Worker, WorkerState -from ...services.acquisition_queue import ( - QueueFailureStage, - QueueItem, - QueueJob, - QueueSnapshot, - QueueStatus, -) +from ...services.download_queue import DownloadQueueItem, DownloadQueueItemStatus, DownloadQueueSnapshot from .base import HubScreen -QueueProvider = Callable[[], QueueSnapshot] +QueueProvider = Callable[[], DownloadQueueSnapshot] @dataclass(frozen=True, slots=True) class QueueLoadOutcome: - snapshot: QueueSnapshot | None = None + snapshot: DownloadQueueSnapshot | None = None error: str | None = None class DownloadsScreen(HubScreen): - """Read-only persistent acquisition queue browser.""" + """Track-oriented view over the durable acquisition queue.""" def __init__(self, *, queue_provider: QueueProvider) -> None: super().__init__("downloads", "Downloads") self._queue_provider = queue_provider - self.snapshot: QueueSnapshot | None = None - self.jobs: tuple[QueueJob, ...] = () + self.snapshot: DownloadQueueSnapshot | None = None + self.items: tuple[DownloadQueueItem, ...] = () self.selected_index = 0 self._details_mode = False self._refresh_worker: Worker[QueueLoadOutcome] | None = None def compose_content(self) -> Iterable[Widget]: - yield Static( - "Jobs 0 · Pending 0 · Active 0 · Completed 0 · Failed 0", - id="downloads-summary", - markup=False, - ) - yield Static("Loading acquisition queue…", id="downloads-status", markup=False) + yield Static("Queued 0 · Downloading 0 · Processing 0 · Failed 0 · Completed 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-jobs-panel"): - yield Static("Jobs · loading", classes="panel-title", id="download-jobs-title") - with VerticalScroll(id="download-jobs-scroll"): - yield Static("Loading queue…", id="download-jobs", markup=False) + 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("Job details", classes="panel-title") + yield Static("Track details", classes="panel-title") with VerticalScroll(id="download-details-scroll"): - yield Static("Select a job to inspect its tracks.", id="download-details", markup=False) + yield Static("Select a queued song to inspect it.", id="download-details", markup=False) yield Static("r refresh · Enter details", 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.snapshot is None: - self.query_one("#download-jobs", Static).update("Loading queue…") + self.query_one("#download-queue", Static).update("Loading queue…") self.query_one("#download-details", Static).update("Waiting for queue data…") - self.query_one("#downloads-status", Static).update("Refreshing queue…") - self.query_one("#downloads-status", Static).remove_class("-error") + 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) @@ -83,6 +78,11 @@ def _load_queue(self) -> QueueLoadOutcome: def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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: @@ -95,236 +95,152 @@ def _apply_queue(self, outcome: QueueLoadOutcome) -> None: status.update(f"Queue unavailable: {outcome.error or 'Unknown queue error'}") status.add_class("-error") if self.snapshot is None: - self.jobs = () - self.query_one("#download-jobs-title", Static).update("Jobs · unavailable") - self.query_one("#download-jobs", Static).update("Unable to load acquisition jobs.") + 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("r retry refresh") return - previous_id = self.selected_job.job_id if self.selected_job is not None else None + previous = self.selected_item.reference if self.selected_item is not None else None self.snapshot = outcome.snapshot - self.jobs = outcome.snapshot.jobs - if previous_id is not None: - self.selected_index = next( - (index for index, job in enumerate(self.jobs) if job.job_id == previous_id), - 0, - ) - else: - self.selected_index = 0 + 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_jobs() + self._render_items() self._render_selected_details() - if self.jobs: - status.update("Read-only queue · no Run, Retry, or Delete actions") + if self.items: + status.update("Download queue · actions coming next") self._update_position() - self.call_after_refresh(self._scroll_selected_job_into_view) + self.call_after_refresh(self._scroll_selected_into_view) else: - status.update("No acquisition jobs yet.") - self.query_one("#downloads-position", Static).update("r refresh · Queue is empty") + status.update("The active download queue is empty.") + self.query_one("#downloads-position", Static).update("r refresh · Completed items stay in history") @property - def selected_job(self) -> QueueJob | None: - if not self.jobs: - return None - return self.jobs[self.selected_index] + def selected_item(self) -> DownloadQueueItem | None: + return self.items[self.selected_index] if self.items else None def _render_summary(self) -> None: - snapshot = self.snapshot - if snapshot is None: + if self.snapshot is None: return + snapshot = self.snapshot self.query_one("#downloads-summary", Static).update( - f"Jobs {snapshot.total_job_count} · Pending {snapshot.pending_job_count} · " - f"Active {snapshot.active_job_count} · Completed {snapshot.completed_job_count} · " - f"Failed {snapshot.failed_job_count}" + f"Queued {snapshot.queued_count} · Downloading {snapshot.downloading_count} · Processing {snapshot.processing_count} · Failed {snapshot.failed_count} · Completed {snapshot.completed_count}" ) - def _render_jobs(self) -> None: - self.query_one("#download-jobs-title", Static).update(f"Jobs · {len(self.jobs)}") - if not self.jobs: - self.query_one("#download-jobs", Static).update("No acquisition jobs.") + def _render_items(self) -> None: + self.query_one("#download-queue-title", Static).update(f"Queue · {len(self.items)} active") + if not self.items: + self.query_one("#download-queue", Static).update("No queued or failed songs.") return lines = [] - for index, job in enumerate(self.jobs): + for index, item in enumerate(self.items): marker = ">" if index == self.selected_index else " " - status = _status_label(job.status) - summary = f"{job.completed_item_count} done" - if job.failed_item_count: - summary += f" · {job.failed_item_count} failed" - lines.append( - f"{marker} {job.display_number:>2} {status:<18} " - f"{job.label[:28]:28} · {job.total_item_count} tracks · {summary}" - ) - self.query_one("#download-jobs", Static).update( - Text("\n".join(lines), no_wrap=True, overflow="ellipsis") - ) + error = " · error" if item.status in {DownloadQueueItemStatus.FAILED, DownloadQueueItemStatus.NEEDS_ATTENTION} else "" + lines.append(f"{marker} {_status_label(item.status):<15} {item.title[:32]:32} {_progress_label(item)}{error}") + self.query_one("#download-queue", Static).update(Text("\n".join(lines), no_wrap=True, overflow="ellipsis")) def _render_selected_details(self) -> None: - job = self.selected_job + item = self.selected_item details = self.query_one("#download-details", Static) - scroll = self.query_one("#download-details-scroll", VerticalScroll) - scroll.scroll_home(animate=False, immediate=True) - if job is None: - details.update("No job selected.") + 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 - destination = str(job.destination) if job.destination is not None else "See track destinations" lines = [ - job.label, - "", - f"Reference {job.display_number}", - f"Job ID {job.job_id}", - f"Status {_status_label(job.status)}", - f"Destination {destination}", - f"Created {_timestamp(job.created_at)}", - f"Updated {_timestamp(job.updated_at)}", - f"Tracks {job.total_item_count}", - f"Progress {job.completed_item_count} completed · {job.failed_item_count} failed · " - f"{job.pending_item_count} pending · {job.active_item_count} active", - f"Retry {_job_retry_label(job)}", - "", - "Tracks", + 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(item.status)}", + f"Progress {_progress_label(item)}", + f"Queued {_timestamp(item.queued_at)}", + f"Retry {'Available' if item.retryable else 'Not available'}", ] - if not job.items: - lines.append(" No tracks stored in this job.") - for index, item in enumerate(job.items, start=1): - lines.extend(_item_lines(index, item)) + 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 not self.jobs: - return - suffix = "Esc job list · PgUp/PgDn details" if self._details_mode else "Enter details · r refresh" - self.query_one("#downloads-position", Static).update( - f"Job {self.selected_index + 1} of {len(self.jobs)} · {suffix}" - ) + if self.items: + suffix = "Esc queue · PgUp/PgDn details" if self._details_mode else "Enter details · r refresh" + self.query_one("#downloads-position", Static).update(f"Track {self.selected_index + 1} of {len(self.items)} · {suffix}") 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_job is not None: + 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.query_one("#download-details-scroll", VerticalScroll).scroll_home(animate=False, immediate=True) self._update_position() elif event.key in ("pagedown", "pageup") and self._details_mode: scroll = self.query_one("#download-details-scroll", VerticalScroll) - if event.key == "pagedown": - scroll.scroll_page_down(animate=False) - else: - scroll.scroll_page_up(animate=False) + (scroll.scroll_page_down if event.key == "pagedown" else scroll.scroll_page_up)(animate=False) elif event.key in ("down", "j"): - self._select_job(self.selected_index + 1) + self._select_item(self.selected_index + 1) elif event.key in ("up", "k"): - self._select_job(self.selected_index - 1) + self._select_item(self.selected_index - 1) elif event.key == "home": - self._select_job(0) + self._select_item(0) elif event.key == "end": - self._select_job(len(self.jobs) - 1) + self._select_item(len(self.items) - 1) elif event.key in ("pagedown", "pageup"): - scroll = self.query_one("#download-jobs-scroll", VerticalScroll) + scroll = self.query_one("#download-queue-scroll", VerticalScroll) step = max(1, scroll.size.height - 1) - self._select_job(self.selected_index + (step if event.key == "pagedown" else -step)) + self._select_item(self.selected_index + (step if event.key == "pagedown" else -step)) else: return event.prevent_default() event.stop() - def _select_job(self, index: int) -> None: - if not self.jobs: + def _select_item(self, index: int) -> None: + if not self.items: return - self.selected_index = max(0, min(len(self.jobs) - 1, index)) - self._render_jobs() + self.selected_index = max(0, min(len(self.items) - 1, index)) + self._render_items() self._render_selected_details() self._update_position() - self.call_after_refresh(self._scroll_selected_job_into_view) + self.call_after_refresh(self._scroll_selected_into_view) - def _scroll_selected_job_into_view(self) -> None: - if not self.jobs: - return - scroll = self.query_one("#download-jobs-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 _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.jobs: - self.call_after_refresh(self._scroll_selected_job_into_view) + if self.items: + self.call_after_refresh(self._scroll_selected_into_view) -def _status_label(status: QueueStatus) -> str: +def _status_label(status: DownloadQueueItemStatus) -> str: return { - QueueStatus.PENDING: "Queued", - QueueStatus.CHECKING_EXISTING: "Checking existing", - QueueStatus.DOWNLOADING: "Downloading", - QueueStatus.VALIDATING: "Validating", - QueueStatus.POST_PROCESSING: "Processing lyrics", - QueueStatus.COMPLETED: "Completed", - QueueStatus.SKIPPED: "Skipped", - QueueStatus.FAILED: "Failed", - QueueStatus.UNKNOWN: "Unknown", + DownloadQueueItemStatus.QUEUED: "Queued", + DownloadQueueItemStatus.DOWNLOADING: "Downloading", + DownloadQueueItemStatus.PROCESSING: "Processing", + DownloadQueueItemStatus.COMPLETED: "Completed", + DownloadQueueItemStatus.FAILED: "Failed", + DownloadQueueItemStatus.NEEDS_ATTENTION: "Needs attention", }[status] -def _failure_label(stage: QueueFailureStage | None) -> str: - return { - QueueFailureStage.TRANSPORT: "Download failed", - QueueFailureStage.VALIDATION: "Validation failed", - QueueFailureStage.LYRICS: "Lyrics processing failed", - QueueFailureStage.LRC: "LRC creation failed", - QueueFailureStage.STATE: "Library-state update failed", - QueueFailureStage.UNKNOWN: "Processing failed (unknown stage)", - None: "Failure stage unavailable", - }[stage] - - -def _item_retry_label(item: QueueItem) -> str: - if item.postprocessing_retryable: - return "Retry available from verified downloaded file" - if item.status is QueueStatus.FAILED and item.retryable: - return "Full download retry required" - return "Not retryable" - - -def _job_retry_label(job: QueueJob) -> str: - if job.status is not QueueStatus.FAILED: - return "Not applicable" - if any(item.postprocessing_retryable for item in job.items): - return "Safe post-processing retry available" - if job.retryable: - return "Full download retry may be required" - return "Not retryable" - - -def _item_lines(index: int, item: QueueItem) -> list[str]: - title = item.title or "Untitled track" - destination = str(item.destination) if item.destination is not None else "Unavailable" - lines = [ - "", - f" {index}. {title}", - f" Status {_status_label(item.status)}", - f" Destination {destination}", - ] - if item.expected_bytes is not None or item.bytes_written: - expected = str(item.expected_bytes) if item.expected_bytes is not None else "unknown" - lines.append(f" Progress {item.bytes_written} / {expected} bytes") - if item.status is QueueStatus.FAILED: - lines.append(f" Failure {_failure_label(item.failure_stage)}") - if item.error: - lines.append(f" Error {_concise_error(item.error)}") - lines.append(f" Retry {_item_retry_label(item)}") - return lines +def _progress_label(item: DownloadQueueItem) -> str: + 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 _concise_error(error: str, limit: int = 240) -> str: diff --git a/tests/test_download_queue_service.py b/tests/test_download_queue_service.py new file mode 100644 index 0000000..0114751 --- /dev/null +++ b/tests/test_download_queue_service.py @@ -0,0 +1,176 @@ +from pathlib import Path + +from juice_lyrics.acquisition.jobs import JobStore +from juice_lyrics.acquisition.models import AcquisitionItem, AcquisitionState +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 ( + DownloadQueueItemStatus, + QueueAddStatus, + add_to_download_queue, + get_download_queue_snapshot, + plan_queue_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) -> CatalogueSearchResult: + return CatalogueSearchResult( + selection_index=1, + song_id=94902, + title="Lemon Glow", + category="unreleased", + era="DRFL", + length="3:12", + artists=("Juice WRLD",), + producers=(), + media_path="Compilation/DRFL/Lemon Glow.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_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_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 diff --git a/tests/test_tui.py b/tests/test_tui.py index 52291bd..cee9bfb 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -155,7 +155,7 @@ async def scenario(): await pilot.press("4") await pilot.pause() assert app.screen.id == "screen-downloads" - assert app.query_one("#download-jobs") is not None + assert app.query_one("#download-queue") is not None await pilot.press("1") await pilot.pause() assert app.screen.id == "screen-dashboard" diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index ae4a948..81b1387 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -18,6 +18,16 @@ LyricAvailability, SongDetails, ) +from juice_lyrics.services.download_queue import ( + DownloadQueueItem, + DownloadQueueItemStatus, + DownloadQueueSnapshot, + PlannedQueueItem, + QueueAddPlan, + QueueAddResult, + QueueAddStatus, +) +from juice_lyrics.acquisition.models import AcquisitionItem from juice_lyrics.tui import JuiceLyricsApp @@ -66,7 +76,16 @@ def _details( ) -def _app(tmp_path: Path, *, search, details=None, filters=None) -> JuiceLyricsApp: +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( @@ -85,6 +104,13 @@ def _app(tmp_path: Path, *, search, details=None, filters=None) -> JuiceLyricsAp 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)), ) @@ -92,6 +118,23 @@ 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, + ),)) + + async def _open_browse(app: JuiceLyricsApp, pilot): await pilot.press("2") await pilot.pause() @@ -895,3 +938,188 @@ async def scenario(): assert calls == ["Rental"] asyncio.run(scenario()) + + +def test_add_to_queue_confirmation_is_cancel_first_and_uses_queue_wording(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 pilot.pause() + assert app.screen.__class__.__name__ == "AddToQueueDialog" + body = _text(app, "#queue-confirm-body") + assert "Song Rental" in body + assert str(tmp_path / "music" / "Rental.mp3") in body + assert "download queue" in body + assert "will not start downloading" in body + assert "job" not in body.lower() + assert "[Cancel]" in _text(app, "#queue-confirm-cancel") + await pilot.press("enter") + await pilot.pause() + assert app.screen.id == "screen-browse" + assert len(calls) == 1 + await pilot.press("a") + await browse._queue_plan_worker.wait() + await pilot.pause() + await pilot.press("escape") + await pilot.pause() + assert app.screen.id == "screen-browse" + assert len(calls) == 2 + + 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 pilot.pause() + await pilot.press("y") + await app.screen._worker.wait() + await pilot.pause() + assert len(created) == 1 + assert "Nothing has started" in _text(app, "#queue-confirm-status") + await pilot.press("y") + assert len(created) == 1 + await pilot.press("v") + 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 pilot.pause() + await pilot.press("y") + await app.screen._worker.wait() + await pilot.pause() + assert "permission denied" in _text(app, "#queue-confirm-status") + assert app.screen.__class__.__name__ == "AddToQueueDialog" + + try: + asyncio.run(navigation_scenario()) + asyncio.run(failure_scenario()) + finally: + release.set() diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py index 53b8bcc..e0a44c3 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -135,8 +135,8 @@ async def empty_scenario(): async with app.run_test() as pilot: screen = await _open_downloads(app, pilot) assert screen.__class__.__name__ == "DownloadsScreen" - assert "No acquisition jobs" in _text(app, "#download-jobs") - assert "Jobs 0 · Pending 0 · Active 0 · Completed 0 · Failed 0" in _text( + assert "No queued or failed songs" in _text(app, "#download-queue") + assert "Queued 0 · Downloading 0 · Processing 0 · Failed 0 · Completed 0" in _text( app, "#downloads-summary" ) @@ -155,8 +155,8 @@ async def empty_job_scenario(): app = _app(tmp_path, lambda: _snapshot(empty_job)) async with app.run_test() as pilot: await _open_downloads(app, pilot) - assert "No tracks stored in this job" in _text(app, "#download-details") - assert "Status Completed" in _text(app, "#download-details") + assert "No active queue item selected" in _text(app, "#download-details") + assert "Completed 0" in _text(app, "#downloads-summary") asyncio.run(empty_scenario()) asyncio.run(error_scenario()) @@ -177,11 +177,21 @@ async def navigation_scenario(): 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-jobs") + 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() @@ -259,38 +269,32 @@ 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 "Jobs 4 · Pending 1 · Active 1 · Completed 1 · Failed 1" in _text( + assert "Queued 1 · Downloading 1 · Processing 0 · Failed 5 · Completed 2" in _text( app, "#downloads-summary" ) - rendered = _text(app, "#download-jobs") - assert rendered.index("Queued Song") < rendered.index("Active Song") < rendered.index("Done Song") - assert "> 1 Queued" in rendered + 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 "> Queued" 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_job.job_id == "complete-id" - assert "Done Song" in _text(app, "#download-details") + 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_job.job_id == "queued-id" + assert app.screen.selected_item.title == "Queued Song" await pilot.press("end") await pilot.pause() details = _text(app, "#download-details") - assert app.screen.selected_job.job_id == "failed-id" - assert "Job ID failed-id" in details - assert "Finished Track" in details and "Completed" in details - assert "Lyrics processing failed" in details - assert "Audio downloaded lyrics verification failed" in details - assert "Retry available from verified downloaded file" in details - assert "Download failed" in details - assert "Validation failed" in details - assert "LRC creation failed" in details - assert "Library-state update failed" in details - assert "Full download retry required" in details - assert "Retry Safe post-processing retry available" in 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_job.job_id == "queued-id" + assert app.screen.selected_item.title == "Queued Song" asyncio.run(scenario()) @@ -311,7 +315,7 @@ 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-jobs-scroll", VerticalScroll) + 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 @@ -319,24 +323,23 @@ async def scenario(): await pilot.press("end") await pilot.pause() - assert app.screen.selected_job.job_id == "job-20" + assert app.screen.selected_item.title == "Track 20" assert job_scroll.scroll_y > 0 - assert job_scroll.scroll_y <= 19 < job_scroll.scroll_y + job_scroll.size.height + 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) - assert details_scroll.max_scroll_y > 0 await pilot.press("pagedown") await pilot.pause() - assert details_scroll.scroll_y > 0 + 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 < 19 + assert app.screen.selected_index < 38 asyncio.run(scenario()) @@ -355,17 +358,17 @@ async def scenario(): async with app.run_test() as pilot: await _open_downloads(app, pilot) await pilot.press("down") - assert app.screen.selected_job.job_id == "keep" + assert app.screen.selected_item.title == "Keep" await pilot.press("r") await app.screen._refresh_worker.wait() await pilot.pause() - assert app.screen.selected_job.job_id == "keep" + assert app.screen.selected_item.title == "Keep" await pilot.press("r") await app.screen._refresh_worker.wait() await pilot.pause() - assert app.screen.selected_job.job_id == "replacement" + assert app.screen.selected_item is None asyncio.run(scenario()) @@ -399,10 +402,10 @@ async def scenario(): current = app.screen._refresh_worker await current.wait() await pilot.pause() - assert app.screen.selected_job.job_id == "fresh" + assert app.screen.selected_item is None release_stale.set() await pilot.pause() - assert "Stale" not in _text(app, "#download-jobs") + assert "Stale" not in _text(app, "#download-queue") try: asyncio.run(scenario()) From 928f0c7dfe7863760469b218a9676c76521c83ec Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 31 Aug 2026 21:51:38 +0100 Subject: [PATCH 27/62] Add configurable central LRC directory --- PROJECT_CONTEXT.md | 17 +- docs/DECISIONS.md | 11 +- docs/DEVELOPMENT.md | 24 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 12 +- docs/PROJECT_STATE.md | 16 +- docs/ROADMAP_V2.md | 10 +- docs/UI_DESIGN.md | 2 +- docs/USER_FLOWS.md | 20 +- docs/USER_GUIDE.md | 30 +- src/juice_lyrics/acquisition/integration.py | 2 + src/juice_lyrics/acquisition/runner.py | 3 + src/juice_lyrics/cli.py | 46 ++- src/juice_lyrics/config/settings.py | 3 +- src/juice_lyrics/rmpc/integration.py | 2 - src/juice_lyrics/services/__init__.py | 14 + src/juice_lyrics/services/download_queue.py | 294 +++++++++++++++- src/juice_lyrics/services/library_status.py | 25 +- src/juice_lyrics/services/library_sync.py | 34 +- .../services/settings_snapshot.py | 36 +- src/juice_lyrics/tui/app.py | 70 +++- src/juice_lyrics/tui/screens/dashboard.py | 10 + src/juice_lyrics/tui/screens/downloads.py | 325 +++++++++++++++++- src/juice_lyrics/tui/screens/library.py | 14 + tests/test_acquisition.py | 37 +- tests/test_acquisition_integration_safety.py | 36 ++ tests/test_core.py | 74 +++- tests/test_download_queue_service.py | 182 +++++++++- tests/test_library_status.py | 39 ++- tests/test_library_sync_service.py | 13 +- tests/test_rmpc.py | 26 ++ tests/test_settings_snapshot.py | 36 +- tests/test_tui_downloads.py | 282 ++++++++++++++- tests/test_tui_library.py | 1 + tests/test_tui_settings.py | 8 +- 34 files changed, 1629 insertions(+), 125 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 8eb4af6..6715c75 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -19,7 +19,7 @@ Default local library: Default rmpc lyric directory: -`~/Music/Juice WRLD/lyrics` +`~/Music/lyrics` These paths are defaults only and must remain configurable and portable. @@ -53,7 +53,11 @@ Keep MPD + rmpc as the primary playback setup. Default lyrics directory: -`~/Music/Juice WRLD/lyrics` +`~/Music/lyrics` + +This is the application `lyrics_dir` setting and is intentionally shared across +artists. Embedded lyrics remain in audio files; only synchronized external LRC +files use this directory. Preserve unrelated rmpc configuration when modifying configuration files. @@ -281,21 +285,22 @@ The latest development checkpoint reports: * Settings / Path CLI compatibility verified * responsive terminal-native Textual shell with `ansi_color=True` * all five main TUI sections are functional; Browse can explicitly add one selected song to the queue +* Downloads can explicitly run one selected queued song after a cancel-first confirmation * canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details * flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility * Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews * Settings reports effective configuration, provenance where reliable, application paths, and rmpc integration without creating or changing files -* TUI download execution, remove, clear, retry, cancel, configuration editing, and sync execution are not implemented -* legacy CLI remains the way to download, delete jobs, and sync -* 220 automated tests passing across the suite +* TUI Download all, remove, clear, retry, cancel, configuration editing, and sync execution are not implemented +* legacy CLI remains the way to run whole acquisition records, retry, delete jobs, and sync +* 235 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, but no rename or migration has been performed. Native FLAC support remains planned. -Recommended next milestones are: Downloads Download selected / Download all, +Recommended next milestones are: Downloads Download all, Remove / Clear / Retry actions, Library sync actions, the `999` naming migration, native FLAC support, then beta polish and release testing. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index ec2d149..8367175 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -37,6 +37,11 @@ rmpc does not read embedded ID3 lyrics. rmpc currently relies on external `.lrc` lyric files. +All external synchronized LRC operations use the typed `lyrics_dir` setting. +Its default is the artist-independent central directory `~/Music/lyrics`, while +embedded lyrics remain inside the audio files. Loading settings never creates +this directory; an explicit LRC-writing workflow may create it. + Therefore: - SYLT lyrics should generate `.lrc` files. @@ -129,8 +134,10 @@ 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. -The planned queue actions are Download selected, Download all, Remove, Clear, -Retry, and Cancel. Each mutating action requires its own explicit safe workflow. +Download selected is the first implemented queue execution action and requires +a cancel-first confirmation for one eligible song. Download all, Remove, Clear, +Retry, and Cancel remain planned. Each mutating action requires its own explicit +safe workflow. The backend can remain technical while the user interface becomes friendly. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 5b399b7..b2cb142 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -61,8 +61,8 @@ juice-lyrics tui ``` The experimental shell provides functional Dashboard, Browse, Library, -Downloads, and Settings screens. Inspection remains read-only; Browse has one -explicit Add to queue action. Press `/` to focus catalogue search and Enter to +Downloads, and Settings screens. Browse has one explicit Add to queue action, +and Downloads can explicitly run one selected queued song. 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 @@ -83,9 +83,11 @@ In Downloads, 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. Download selected, Download all, Remove, Clear, Retry, and -Cancel are intentionally unavailable in this milestone. Existing queued songs -must still be run through the CLI. +songs remain visible. Press `d` to review a cancel-first confirmation for the +selected queued song. Confirming runs the existing download, validation, lyric, +LRC, state, backup, and rmpc pipeline; no download starts before confirmation. +Download all, Remove, Clear, Retry, and Cancel remain unavailable. The CLI is +still required for those existing acquisition-management workflows. In Library, arrows or `j`/`k` select local MP3 tracks, Home/End select the first or last track, and PageUp/PageDown move through longer lists. Press `/` for a @@ -102,11 +104,21 @@ scanner is currently MP3-focused; native FLAC support remains planned. In Settings, arrows or `j`/`k` inspect effective configuration values, paths, and environment details; Home/End and PageUp/PageDown navigate longer content. The view reports the active config file, reliable default/config/runtime source -labels, path existence, and whether rmpc is detected and configured. Press `r` +labels, the effective central `lyrics_dir` (default `~/Music/lyrics`), path +existence, and whether rmpc points at that directory. Press `r` to refresh. The screen is strictly read-only: configuration changes and setup remain CLI-only, no missing XDG paths are created, the scanner remains MP3-only, and native FLAC support remains planned. +External synchronized LRC files are shared across artists in `lyrics_dir`; +embedded synchronized/plain lyrics remain in the MP3. To migrate files created +under the previous default without overwriting existing names: + +```bash +mkdir -p ~/Music/lyrics +find ~/Music/Juice\ WRLD/lyrics -maxdepth 1 -type f -iname '*.lrc' -exec mv -n -t ~/Music/lyrics -- {} + +``` + ## Source of truth and Git workflow 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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 3d3eba7..2afcec8 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -52,7 +52,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -220 passing tests. +235 passing tests. Completed and integrated: @@ -80,14 +80,16 @@ functional Dashboard and Browse screens, canonical Category and Era selectors, correct case-sensitive API cache behavior, server-side catalogue pagination with scrollable 50-result pages, stable ID-based song details, and a Downloads screen with a flat track queue, song navigation, details, failure -stages, retry eligibility, and an explicit Browse Add to queue flow that never -starts a download, a read-only Library screen with local +stages, retry eligibility, an explicit Browse Add to queue flow that never +starts a download, and an explicitly confirmed Download selected action for one +eligible queued song, a read-only Library screen with local track browsing, filters, details, and explicit sync previews, and a read-only Settings screen with effective configuration, paths, provenance, and rmpc state. All five primary TUI sections are functional. Browse may add one explicitly -confirmed song to the queue; Downloads execution, retry, remove, clear, and -cancel actions, configuration editing, and sync execution are not implemented. +confirmed song to the queue; Downloads can execute one confirmed selected song. +Download all, retry, remove, clear, and cancel actions, configuration editing, +and sync execution are not implemented. Durable jobs remain an internal backend detail and completed entries are hidden from the active track queue. The legacy CLI remains the way to run downloads, delete jobs, and sync. Native FLAC support remains planned. The planned diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index d288d83..45aa61e 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,9 +1,9 @@ # 999 Project State ## Current Status -Backend services remain stable. The experimental Textual frontend remains -read-only except for one explicit, confirmed Add to queue action. The current -checkpoint has 220 passing tests. +Backend services remain stable. The experimental Textual frontend supports one +explicit confirmed Browse Add to queue action and one explicit confirmed +Download selected action. The current checkpoint has 235 passing tests. ## Current Branch v2-redesign @@ -19,19 +19,21 @@ v2-redesign - Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. - Track-oriented Downloads queue summaries, song navigation, details, structured failures, and retry eligibility; durable jobs are hidden as an internal mechanism. - Explicit cancel-first Browse Add to queue flow; adding persists one queued song but never starts downloading. +- Explicit cancel-first Downloads `d` flow for one eligible queued song, delegated to the existing acquisition runner with responsive Downloading and Processing states. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. - Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. +- External synchronized LRC files use the authoritative `lyrics_dir` setting, defaulting to the shared `~/Music/lyrics` directory. ## Available through the CLI -The legacy CLI remains the supported way to run downloads, delete durable -acquisition records, and sync the library. +The legacy CLI remains the supported way to run whole acquisition records, +retry failures, delete durable acquisition records, and sync the library. ## Current limitations - Configuration editing remains CLI-only. -- TUI Download, Remove, Clear, Retry, and Cancel actions are not implemented. +- TUI Download all, Remove, Clear, Retry, and Cancel actions are not implemented. - Browse currently adds one song at a time; multi-select remains planned. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and @@ -46,7 +48,7 @@ acquisition records, and sync the library. ## Recommended next milestones -1. Downloads Download selected / Download all execution +1. Downloads Download all execution 2. Downloads Remove / Clear / Retry actions 3. Library sync actions 4. `999` command and naming migration diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 25b5d23..7a0b2b5 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -178,10 +178,10 @@ Features: - Completed items. - Retry. -Status: Track-oriented queue projection and Browse Add to queue are complete. -Durable jobs remain internal, completed entries are hidden from the active -queue, and failed entries remain visible. Download selected, Download all, -Remove, Clear, Retry, and Cancel remain planned. +Status: Track-oriented queue projection, Browse Add to queue, and explicitly +confirmed Download selected are complete. Durable jobs remain internal, +completed entries are hidden from the active queue, and failed entries remain +visible. Download all, Remove, Clear, Retry, and Cancel remain planned. --- @@ -203,7 +203,7 @@ capability limitations. Editing remains planned. Recommended implementation order after the current checkpoint: -1. Downloads Download selected / Download all execution +1. Downloads Download all execution 2. Downloads Remove / Clear / Retry actions 3. Library sync actions 4. `999` command and naming migration diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 3011165..55b10f6 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -352,7 +352,7 @@ Music Directory Lyrics Directory -~/Music/Juice WRLD/lyrics +~/Music/lyrics Player diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index f470a58..0a2947a 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -267,8 +267,8 @@ Planned follow-up interactions include Space to toggle multiple selections, `a` to add selected songs, and a bounded explicitly confirmed `A` action. The application will not bulk-fetch an unbounded catalogue merely to fill a queue. -Future queue actions are Download selected, Download all, Remove, Clear queue, -Retry failed, and Cancel active download. +Download selected is implemented for one queued song. Download all, Remove, +Clear queue, Retry failed, and Cancel active download remain future actions. v2: @@ -295,7 +295,7 @@ Destination: ~/Music/Juice WRLD/Unreleased -[Enter] Confirm +[Download] Confirm [Esc] Cancel @@ -321,6 +321,11 @@ After completion: ✓ Lyrics embedded ✓ rmpc 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. + --- @@ -500,16 +505,17 @@ Failed --- -Actions: - +Current actions: -r Retry -d Remove +d Download selected queued song enter Details +Planned actions: Download all, Remove, Clear, Retry, and Cancel. + + --- # Flow 9: Lyrics Viewing diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 1bbdd82..6243731 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -8,7 +8,23 @@ Run: juice-lyrics setup ``` -This creates/updates configuration and, when rmpc is detected, prepares the lyric directory and relevant rmpc settings. +When rmpc is detected, setup generates synchronized LRC files and updates the +rmpc lyrics setting after its normal confirmation. Merely loading configuration +does not create the lyrics directory. + +## Configuration + +The application configuration is `~/.config/juice-lyrics/config.toml`. Embedded +lyrics remain inside each audio file. External synchronized LRC files use one +central directory shared across artists: + +```toml +lyrics_dir = "~/Music/lyrics" +``` + +The default is `~/Music/lyrics`; an explicit `lyrics_dir` overrides it. Inspect +the effective value with `juice-lyrics config show`. Native FLAC support remains +planned separately. ## Normal day-to-day use @@ -129,10 +145,18 @@ Default local library: ~/Music/Juice WRLD/Unreleased ``` -Default rmpc lyrics directory: +Default external synchronized LRC directory: ```text -~/Music/Juice WRLD/lyrics +~/Music/lyrics ``` Both should remain configurable. + +Existing LRC files from the previous default are not moved automatically. A +safe no-overwrite manual migration is: + +```bash +mkdir -p ~/Music/lyrics +find ~/Music/Juice\ WRLD/lyrics -maxdepth 1 -type f -iname '*.lrc' -exec mv -n -t ~/Music/lyrics -- {} + +``` diff --git a/src/juice_lyrics/acquisition/integration.py b/src/juice_lyrics/acquisition/integration.py index e4ded8d..c09617f 100644 --- a/src/juice_lyrics/acquisition/integration.py +++ b/src/juice_lyrics/acquisition/integration.py @@ -47,6 +47,8 @@ def integrate_downloaded_mp3( """ path = item.destination + if lyrics_dir is None and settings is not None: + lyrics_dir = getattr(settings, "lyrics_dir", None) if path.suffix.lower() != ".mp3": return IntegrationResult(path=path, message="not an MP3; lyrics integration skipped") diff --git a/src/juice_lyrics/acquisition/runner.py b/src/juice_lyrics/acquisition/runner.py index b53f1f6..5c383f3 100644 --- a/src/juice_lyrics/acquisition/runner.py +++ b/src/juice_lyrics/acquisition/runner.py @@ -85,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. @@ -101,6 +102,8 @@ 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 diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index c92cb06..670ed3b 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -21,6 +21,7 @@ from mutagen.mp3 import MP3 from . import __version__ +from .config.settings import DEFAULT_LYRICS_DIR APP_NAME = "juice-lyrics" DEFAULT_API_BASE = "https://juicewrldapi.com/juicewrld" @@ -63,13 +64,13 @@ def xdg_dir(name: str, fallback: Path) -> Path: DATA_DIR = DATA_HOME / APP_NAME 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 +104,8 @@ 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.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)) @@ -121,7 +124,7 @@ def write_default_config(force: bool = False) -> None: CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True) if CONFIG_FILE.exists() and not force: raise RuntimeError(f"Config already exists: {CONFIG_FILE} (use --force to replace it)") - content = f'''# {APP_NAME} configuration\n\nmusic_dir = "{DEFAULT_MUSIC_DIR}"\napi_base = "{DEFAULT_API_BASE}"\ntimeout = {DEFAULT_TIMEOUT}\ndelay = {DEFAULT_DELAY}\nduration_tolerance = {DEFAULT_DURATION_TOLERANCE}\ncache_ttl_hours = {DEFAULT_CACHE_TTL_HOURS}\n''' + content = f'''# {APP_NAME} configuration\n\nmusic_dir = "{DEFAULT_MUSIC_DIR}"\nlyrics_dir = "{DEFAULT_LYRICS_DIR}"\napi_base = "{DEFAULT_API_BASE}"\ntimeout = {DEFAULT_TIMEOUT}\ndelay = {DEFAULT_DELAY}\nduration_tolerance = {DEFAULT_DURATION_TOLERANCE}\ncache_ttl_hours = {DEFAULT_CACHE_TTL_HOURS}\n''' CONFIG_FILE.write_text(content, encoding="utf-8") @@ -548,8 +551,8 @@ def notify_rmpc_index(paths: list[Path]) -> int: return count -def configured_rmpc_lyrics_dir() -> Path: - return DEFAULT_RMPC_LYRICS_DIR +def configured_rmpc_lyrics_dir(settings: Settings) -> Path: + return settings.lyrics_dir def write_state_entry(state: dict[str, Any], path: Path, settings: Settings, analysis: dict[str, Any], lrc_path: Path | None) -> None: @@ -579,14 +582,15 @@ def state_is_current(state: dict[str, Any], path: Path, settings: Settings, want return False if want_rmpc and entry.get("lyric_type") == "SYLT": lrc = Path(entry.get("lrc") or "") - if not lrc.is_file(): + expected_lrc = settings.lyrics_dir / f"{path.stem}.lrc" + if lrc != expected_lrc or not expected_lrc.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 + lyric_dir = configured_rmpc_lyrics_dir(settings) if with_rmpc else None work: list[dict[str, Any]] = [] skipped_unchanged = 0 for index, path in enumerate(files, 1): @@ -771,6 +775,8 @@ 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.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)) @@ -800,8 +806,7 @@ def command_setup(args: argparse.Namespace, settings: Settings, use_color: bool) 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) + patch_rmpc_config(DEFAULT_RMPC_CONFIG, settings.lyrics_dir) files = find_mp3s(settings) return embed_batch(settings, files, use_color, args.refresh, False, True, rmpc_available) @@ -815,7 +820,7 @@ def command_sync(args: argparse.Namespace, settings: Settings, use_color: bool) dry_run=args.dry_run, refresh=args.refresh, rmpc_enabled=rmpc_enabled, - lyrics_dir=DEFAULT_RMPC_LYRICS_DIR if rmpc_enabled else None, + lyrics_dir=settings.lyrics_dir if rmpc_enabled else None, rmpc_config_path=DEFAULT_RMPC_CONFIG if rmpc_enabled else None, state_file=STATE_FILE, ) @@ -894,6 +899,7 @@ def command_status(settings: Settings, use_color: bool) -> int: ) print_header("Library Status", use_color) print(f"Library: {status.library_path}") + print(f"External LRC dir: {settings.lyrics_dir}") print(f"MP3 files: {status.track_count}") print(f"Embedded synced: {status.embedded_synced_count}") print(f"Embedded plain: {status.embedded_plain_count}") @@ -1081,12 +1087,16 @@ def command_doctor(args: argparse.Namespace, settings: Settings, use_color: bool return 1 if problems else 0 -def command_config(args: argparse.Namespace) -> int: +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}") + print(f"Effective lyrics_dir: {effective.lyrics_dir}") return 0 raise RuntimeError("Unknown config action") @@ -1100,7 +1110,7 @@ def command_cache(args: argparse.Namespace) -> int: 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 + lyrics_dir = Path(args.lyrics_dir).expanduser() if args.lyrics_dir else settings.lyrics_dir if not lyrics_dir.is_absolute(): lyrics_dir = lyrics_dir.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}") @@ -1110,7 +1120,6 @@ def command_rmpc_setup(args: argparse.Namespace, settings: Settings, use_color: 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): @@ -1131,8 +1140,7 @@ def command_rmpc_setup(args: argparse.Namespace, settings: Settings, use_color: 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) + lyrics_dir = Path(args.lyrics_dir).expanduser() if args.lyrics_dir else settings.lyrics_dir generated = [] for path in find_mp3s(settings): a = analyse(settings, path, args.refresh) @@ -1144,7 +1152,7 @@ def command_rmpc_sync(args: argparse.Namespace, settings: Settings, use_color: b 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 + lyrics_dir = Path(args.lyrics_dir).expanduser() if args.lyrics_dir else settings.lyrics_dir files = sorted(lyrics_dir.glob("*.lrc")) if lyrics_dir.is_dir() else [] good = bad = 0 for path in files: @@ -1418,7 +1426,7 @@ def postprocess(result): integration = integrate_downloaded_mp3( result.item, song_fetcher=lambda song_id: _api_get_song(settings, song_id), - lyrics_dir=configured_rmpc_lyrics_dir(), + lyrics_dir=configured_rmpc_lyrics_dir(settings), settings=settings, ) if integration.message: @@ -1643,7 +1651,7 @@ 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) parser.error("Unknown command") except KeyboardInterrupt: diff --git a/src/juice_lyrics/config/settings.py b/src/juice_lyrics/config/settings.py index 8970b6e..fec84d0 100644 --- a/src/juice_lyrics/config/settings.py +++ b/src/juice_lyrics/config/settings.py @@ -11,6 +11,7 @@ DEFAULT_DELAY = 0.15 DEFAULT_DURATION_TOLERANCE = 3.0 DEFAULT_CACHE_TTL_HOURS = 24 +DEFAULT_LYRICS_DIR = Path.home() / "Music" / "lyrics" def xdg_dir(name: str, fallback: Path) -> Path: @@ -26,12 +27,12 @@ def xdg_dir(name: str, fallback: Path) -> Path: 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 diff --git a/src/juice_lyrics/rmpc/integration.py b/src/juice_lyrics/rmpc/integration.py index 2bd1c63..1a5adf9 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 diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 22bd1d9..fc2e38d 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -24,6 +24,11 @@ search_catalogue_page, ) from .download_queue import ( + DownloadExecutionAction, + DownloadExecutionPlan, + DownloadExecutionResult, + DownloadExecutionStatus, + DownloadProgress, DownloadQueueItem, DownloadQueueItemStatus, DownloadQueueSnapshot, @@ -33,8 +38,10 @@ QueueAddStatus, QueueDuplicateReason, add_to_download_queue, + execute_selected_download, get_download_queue_snapshot, plan_queue_additions, + plan_download_execution, project_download_queue, ) from .library_status import ( @@ -81,6 +88,11 @@ "DownloadQueueItem", "DownloadQueueItemStatus", "DownloadQueueSnapshot", + "DownloadExecutionAction", + "DownloadExecutionPlan", + "DownloadExecutionResult", + "DownloadExecutionStatus", + "DownloadProgress", "LibraryStatus", "LibraryLrcStatus", "LibraryLyricStatus", @@ -118,6 +130,7 @@ "TrackSyncPlan", "TrackSyncResult", "execute_library_sync", + "execute_selected_download", "get_library_sync_preview", "get_catalogue_filters", "get_download_queue_snapshot", @@ -128,6 +141,7 @@ "get_song_details", "get_song_details_by_id", "plan_library_sync", + "plan_download_execution", "plan_queue_additions", "project_download_queue", "add_to_download_queue", diff --git a/src/juice_lyrics/services/download_queue.py b/src/juice_lyrics/services/download_queue.py index 09a6a84..4b1011a 100644 --- a/src/juice_lyrics/services/download_queue.py +++ b/src/juice_lyrics/services/download_queue.py @@ -4,11 +4,21 @@ from dataclasses import dataclass from enum import Enum 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.models import AcquisitionItem +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, @@ -45,6 +55,24 @@ class QueueAddStatus(str, Enum): 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" + + @dataclass(frozen=True, slots=True) class DownloadQueueItem: reference: str @@ -112,10 +140,58 @@ def ok(self) -> bool: return self.status in {QueueAddStatus.READY, QueueAddStatus.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} + + 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() def _metadata(item: QueueItem) -> dict[str, str]: @@ -312,3 +388,219 @@ def add_to_download_queue( added_count=len(plan.items), queue_references=references, ) + + +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 _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 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, +) -> 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: + 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: + 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) + 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), + lyrics_dir=Path(lyrics_dir) if lyrics_dir is not None else settings.lyrics_dir, + settings=settings, + ) + + runner( + job, + store, + policy=DownloadPolicy(), + progress=report, + postprocess=postprocess, + item_indexes={plan.item_index}, + ) + authoritative = store.get(plan.job_id) + except PermissionError: + return _execution_failure(DownloadExecutionStatus.STORE_FAILED, "Unable to update the download queue: permission denied.") + except (JobStoreError, OSError) as exc: + return _execution_failure(DownloadExecutionStatus.STORE_FAILED, f"Unable to update the download queue: {exc}") + except Exception as exc: + 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, + ) + + 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.", + ) diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 1e248c7..ff1eed4 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -218,16 +218,27 @@ def get_library_snapshot( matched_title = str(candidate_title).strip() matched = bool(matched_title or (entry is not None and entry.get("song_id") is not None)) - lrc_path = None - if entry is not None and entry.get("lrc"): - lrc_path = Path(str(entry["lrc"])) + recorded_lrc = ( + Path(str(entry["lrc"])) + if entry is not None and entry.get("lrc") + else None + ) + lrc_path = ( + Path(settings.lyrics_dir) / f"{path.stem}.lrc" + if lyric_status is LibraryLyricStatus.SYNCED + else None + ) if lrc_path is None: lrc_status = LibraryLrcStatus.NONE elif lrc_path.is_file(): lrc_status = LibraryLrcStatus.PRESENT else: lrc_status = LibraryLrcStatus.MISSING - track_warnings.append("Recorded external LRC file is missing.") + track_warnings.append("External LRC file is missing from the configured directory.") + if recorded_lrc is not None and lrc_path is not None and recorded_lrc != lrc_path: + track_warnings.append( + f"Library state records an LRC outside the configured directory: {recorded_lrc}" + ) try: duration = duration_reader(path) @@ -288,7 +299,11 @@ def get_library_status( entry = state_files.get(relative) if not isinstance(entry, dict) or entry.get("sha256") != sha256_file(path): new_or_changed += 1 - if isinstance(entry, dict) and entry.get("lrc") and Path(entry["lrc"]).is_file(): + if ( + valid + and message.startswith("SYLT") + and (Path(settings.lyrics_dir) / f"{path.stem}.lrc").is_file() + ): lrc += 1 backup_path = Path(backup_dir) diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index 4c2af03..44b8db2 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -10,7 +10,7 @@ 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, DEFAULT_RMPC_LYRICS_DIR, STATE_FILE, Settings +from ..config.settings import DEFAULT_RMPC_CONFIG, STATE_FILE, Settings from ..library.matching import choose_candidate, search_title_for from ..library.scanner import find_mp3s from ..lyrics.engine import embed_lyrics, parse_synced_lyrics, verify_file, write_lrc @@ -79,7 +79,11 @@ def from_settings( dry_run=dry_run, refresh=refresh, rmpc_enabled=rmpc_enabled, - lyrics_dir=Path(lyrics_dir) if lyrics_dir is not None else None, + lyrics_dir=( + Path(lyrics_dir) + if lyrics_dir is not None + else (Path(settings.lyrics_dir) if rmpc_enabled else 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), @@ -233,7 +237,12 @@ def _state_is_current( return False if options.rmpc_enabled and entry.get("lyric_type") == SyncLyricType.SYNCED.value: lrc = Path(str(entry.get("lrc") or "")) - if not lrc.is_file(): + expected_lrc = ( + options.lyrics_dir / f"{path.stem}.lrc" + if options.lyrics_dir is not None + else None + ) + if expected_lrc is None or lrc != expected_lrc or not expected_lrc.is_file(): return False return True @@ -301,8 +310,6 @@ def get_library_sync_preview( if rmpc_enabled is None: rmpc_enabled = shutil.which("rmpc") is not None and DEFAULT_RMPC_CONFIG.exists() - if rmpc_enabled and lyrics_dir is None: - lyrics_dir = DEFAULT_RMPC_LYRICS_DIR options = LibrarySyncOptions.from_settings( settings, dry_run=True, @@ -349,13 +356,6 @@ def execute_library_sync( plan, tuple(initial_results), 0, plan.analysis_failures, 0, 0, 0, None ) - if options.rmpc_enabled and options.lyrics_dir is not None: - if options.rmpc_config_path is not None: - text = options.rmpc_config_path.read_text(encoding="utf-8") - if str(options.lyrics_dir) not in text: - dependencies.rmpc_configurer(options.rmpc_config_path, options.lyrics_dir) - options.lyrics_dir.mkdir(parents=True, exist_ok=True) - ready = [track for track in plan.tracks if track.outcome is MatchOutcome.MATCHED] if not ready: dependencies.state_saver(plan.state) @@ -363,6 +363,16 @@ def execute_library_sync( plan, tuple(initial_results), 0, plan.analysis_failures, 0, 0, 0, None ) + if ( + options.rmpc_enabled + and options.lyrics_dir is not None + and any(track.lyric_type is SyncLyricType.SYNCED for track in ready) + and options.rmpc_config_path is not None + ): + text = options.rmpc_config_path.read_text(encoding="utf-8") + if str(options.lyrics_dir) not in text: + dependencies.rmpc_configurer(options.rmpc_config_path, options.lyrics_dir) + backup_root = dependencies.backup_root_factory() manifest: list[dict[str, Any]] = [] generated_lrc: list[Path] = [] diff --git a/src/juice_lyrics/services/settings_snapshot.py b/src/juice_lyrics/services/settings_snapshot.py index 78669d7..f77a1a0 100644 --- a/src/juice_lyrics/services/settings_snapshot.py +++ b/src/juice_lyrics/services/settings_snapshot.py @@ -19,9 +19,9 @@ DEFAULT_CACHE_TTL_HOURS, DEFAULT_DELAY, DEFAULT_DURATION_TOLERANCE, + DEFAULT_LYRICS_DIR, DEFAULT_MUSIC_DIR, DEFAULT_RMPC_CONFIG, - DEFAULT_RMPC_LYRICS_DIR, DEFAULT_TIMEOUT, STATE_FILE, Settings, @@ -86,6 +86,7 @@ class SettingsSnapshot: _SETTING_SPECS = ( ("music_dir", "Music directory", DEFAULT_MUSIC_DIR), + ("lyrics_dir", "External LRC directory", DEFAULT_LYRICS_DIR), ("api_base", "API base URL", DEFAULT_API_BASE), ("timeout", "Request timeout", DEFAULT_TIMEOUT), ("delay", "Request delay", DEFAULT_DELAY), @@ -95,7 +96,7 @@ class SettingsSnapshot: def _normalized_config_value(key: str, value: object) -> SettingScalar: - if key == "music_dir": + if key in {"music_dir", "lyrics_dir"}: return Path(str(value)).expanduser() if key == "api_base": return str(value).rstrip("/") @@ -130,9 +131,18 @@ def _inspect_path(key: str, label: str, path: Path) -> SettingsPath: return SettingsPath(key, label, path, exists, warning) -def _rmpc_configured(text: str) -> bool: +def _rmpc_configured(text: str, lyrics_dir: 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 + ) return ( - re.search(r"(?im)^\s*lyrics_dir\s*:\s*some\s*\(", text) is not None + configured_directory == lyrics_dir.expanduser() 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 ) @@ -140,6 +150,7 @@ def _rmpc_configured(text: str) -> bool: def _inspect_rmpc( config_path: Path, + lyrics_dir: Path, executable_finder: ExecutableFinder, ) -> IntegrationSnapshot: try: @@ -148,7 +159,10 @@ def _inspect_rmpc( config_exists = config_path.exists() configured = False if config_exists: - configured = _rmpc_configured(config_path.read_text(encoding="utf-8")) + configured = _rmpc_configured( + config_path.read_text(encoding="utf-8"), + lyrics_dir, + ) except Exception as exc: return IntegrationSnapshot( IntegrationStatus.UNABLE_TO_INSPECT, @@ -178,13 +192,13 @@ def get_settings_snapshot( state_file: Path = STATE_FILE, backup_dir: Path = BACKUP_DIR, jobs_file: Path = ACQUISITION_JOBS_FILE, - lyrics_dir: Path = DEFAULT_RMPC_LYRICS_DIR, 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) + effective_lyrics_dir = Path(settings.lyrics_dir) config: dict[str, object] = {} try: config_exists = config_path.exists() @@ -213,7 +227,7 @@ def get_settings_snapshot( _inspect_path(key, label, Path(path)) for key, label, path in ( ("music", "Music library", settings.music_dir), - ("lyrics", "rmpc lyrics", lyrics_dir), + ("lyrics", "External synchronized LRC files", effective_lyrics_dir), ("cache", "API cache", cache_dir), ("state", "Library state", state_file), ("backups", "Backups", backup_dir), @@ -230,12 +244,16 @@ def get_settings_snapshot( config_exists=config_exists, values=values, paths=paths, - rmpc=_inspect_rmpc(Path(rmpc_config_path), executable_finder), + rmpc=_inspect_rmpc( + Path(rmpc_config_path), + effective_lyrics_dir, + executable_finder, + ), application_version=__version__, limitations=( "Local library scanning currently supports MP3 files only.", "Native FLAC support is planned but not implemented.", - "Browse and Downloads remain read-only in the TUI.", + "Settings inspection remains read-only in the TUI.", "Library sync execution remains CLI-only.", "Configuration changes remain CLI-only.", ), diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index bb3a9d1..da824df 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -16,9 +16,12 @@ search_catalogue_page, ) from ..services.download_queue import ( + DownloadExecutionResult, DownloadQueueSnapshot, QueueAddResult, add_to_download_queue, + execute_selected_download, + plan_download_execution, plan_queue_additions, project_download_queue, ) @@ -37,6 +40,8 @@ DownloadQueueProvider = Callable[[], DownloadQueueSnapshot] QueuePlanProvider = Callable[..., QueueAddResult] QueueAddProvider = Callable[..., QueueAddResult] +DownloadPlanProvider = Callable[..., DownloadExecutionResult] +DownloadExecutionProvider = Callable[..., DownloadExecutionResult] CatalogueSearchProvider = Callable[..., CataloguePage] CatalogueDetailsProvider = Callable[..., SongDetails | None] CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] @@ -318,6 +323,50 @@ class JuiceLyricsApp(App[None]): text-style: bold; } + DownloadSelectedDialog { + align: center middle; + background: transparent; + } + + #download-confirm-dialog { + width: 76; + max-width: 92%; + 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; @@ -662,6 +711,8 @@ def __init__( downloads_queue_provider: DownloadQueueProvider | None = None, queue_plan_provider: QueuePlanProvider = plan_queue_additions, queue_add_provider: QueueAddProvider = add_to_download_queue, + download_plan_provider: DownloadPlanProvider = plan_download_execution, + download_execution_provider: DownloadExecutionProvider = execute_selected_download, library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, settings_snapshot_provider: SettingsSnapshotProvider = get_settings_snapshot, @@ -684,6 +735,8 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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.library_snapshot_provider = library_snapshot_provider self.library_preview_provider = library_preview_provider self.settings_snapshot_provider = settings_snapshot_provider @@ -717,7 +770,12 @@ def on_mount(self) -> None: "library", ) self.install_screen( - DownloadsScreen(queue_provider=self.downloads_queue_provider), + DownloadsScreen( + self.settings, + queue_provider=self.downloads_queue_provider, + plan_provider=self.download_plan_provider, + execution_provider=self.download_execution_provider, + ), "downloads", ) self.install_screen( @@ -740,6 +798,13 @@ def invalidate_download_queue(self) -> 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): @@ -759,7 +824,8 @@ def action_show_help(self) -> None: elif section == "downloads": message = ( "↑/↓ or j/k select songs • Home/End first/last song • " - "PgUp/PgDn move queue • Enter track details • Esc queue • r refresh" + "PgUp/PgDn move queue • Enter track details • d Download selected • " + "Esc queue • r refresh" ) elif section == "library": message = ( diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py index cc33939..eebb809 100644 --- a/src/juice_lyrics/tui/screens/dashboard.py +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -6,6 +6,7 @@ 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 @@ -37,6 +38,7 @@ def __init__( self._library_status_provider = library_status_provider self._queue_snapshot_provider = queue_snapshot_provider self._refresh_worker: Worker[DashboardSnapshot] | None = None + self._invalidated = False def compose_content(self) -> Iterable[Widget]: with Grid(id="dashboard-panels"): @@ -52,13 +54,21 @@ def compose_content(self) -> Iterable[Widget]: 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_snapshot() + def invalidate_snapshot(self) -> None: + self._invalidated = True + @work( thread=True, exclusive=True, diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py index edf4de2..21107a8 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -6,17 +6,31 @@ 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 Key, Resize, ScreenResume +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 DownloadQueueItem, DownloadQueueItemStatus, DownloadQueueSnapshot +from ...services.download_queue import ( + DownloadExecutionAction, + DownloadExecutionPlan, + DownloadExecutionResult, + DownloadExecutionStatus, + DownloadProgress, + DownloadQueueItem, + DownloadQueueItemStatus, + DownloadQueueSnapshot, +) from .base import HubScreen QueueProvider = Callable[[], DownloadQueueSnapshot] +PlanProvider = Callable[..., DownloadExecutionResult] +ExecutionProvider = Callable[..., DownloadExecutionResult] @dataclass(frozen=True, slots=True) @@ -25,17 +39,132 @@ class QueueLoadOutcome: 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 = False + + 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 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: + action = "Resume download" if self.plan.action is DownloadExecutionAction.RESUME else "Start download" + with Container(id="download-confirm-dialog"): + yield Static("Download selected", id="download-confirm-title") + yield Static( + "\n".join(( + f"Song {self.plan.title}", + f"Artist {self.plan.artist or 'Unknown'}", + f"Destination {self.plan.destination}", + f"Status {_status_label(self.plan.current_status)}", + f"Action {action}", + "", + "This will write the media file and may embed lyrics, create an LRC file, " + "update library state, and notify rmpc according to your configuration.", + )), + 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() + + 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() + 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 DownloadsScreen(HubScreen): """Track-oriented view over the durable acquisition queue.""" - def __init__(self, *, queue_provider: QueueProvider) -> None: + def __init__( + self, + settings: object, + *, + queue_provider: QueueProvider, + plan_provider: PlanProvider, + execution_provider: ExecutionProvider, + ) -> None: super().__init__("downloads", "Downloads") + self.settings = settings self._queue_provider = queue_provider + self._plan_provider = plan_provider + self._execution_provider = 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._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("Queued 0 · Downloading 0 · Processing 0 · Failed 0 · Completed 0", id="downloads-summary", markup=False) @@ -49,7 +178,7 @@ def compose_content(self) -> Iterable[Widget]: 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("r refresh · Enter details", id="downloads-position", markup=False) + yield Static("d Download selected · r refresh · Enter details", id="downloads-position", markup=False) def on_screen_resume(self, event: ScreenResume) -> None: if self.snapshot is None and self._refresh_worker is None: @@ -60,6 +189,9 @@ def invalidate_snapshot(self) -> 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…") @@ -76,6 +208,22 @@ def _load_queue(self) -> QueueLoadOutcome: 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._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: @@ -112,12 +260,16 @@ def _apply_queue(self, outcome: QueueLoadOutcome) -> None: self._render_items() self._render_selected_details() if self.items: - status.update("Download queue · actions coming next") + status.update("Download queue · d Download selected") self._update_position() self.call_after_refresh(self._scroll_selected_into_view) else: status.update("The active download queue is empty.") self.query_one("#downloads-position", Static).update("r refresh · Completed items stay in history") + 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: @@ -139,8 +291,10 @@ def _render_items(self) -> None: lines = [] for index, item in enumerate(self.items): marker = ">" if index == self.selected_index else " " - error = " · error" if item.status in {DownloadQueueItemStatus.FAILED, DownloadQueueItemStatus.NEEDS_ATTENTION} else "" - lines.append(f"{marker} {_status_label(item.status):<15} {item.title[:32]:32} {_progress_label(item)}{error}") + 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: @@ -156,8 +310,8 @@ def _render_selected_details(self) -> None: f"Category {item.category or 'Unknown'}", f"Era {item.era or 'Unknown'}", f"Destination {item.destination or 'Unavailable'}", - f"Status {_status_label(item.status)}", - f"Progress {_progress_label(item)}", + 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"Queued {_timestamp(item.queued_at)}", f"Retry {'Available' if item.retryable else 'Not available'}", ] @@ -171,7 +325,7 @@ def _render_selected_details(self) -> None: def _update_position(self) -> None: if self.items: - suffix = "Esc queue · PgUp/PgDn details" if self._details_mode else "Enter details · r refresh" + suffix = "Esc queue · PgUp/PgDn details" if self._details_mode else "d Download selected · Enter details · r refresh" self.query_one("#downloads-position", Static).update(f"Track {self.selected_index + 1} of {len(self.items)} · {suffix}") def on_key(self, event: Key) -> None: @@ -184,6 +338,8 @@ def on_key(self, event: Key) -> None: 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 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) @@ -204,6 +360,122 @@ def on_key(self, event: Key) -> None: event.prevent_default() event.stop() + 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 failed song requires the future Retry action.", 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.app.push_screen(DownloadSelectedDialog(outcome.result.plan), self._download_dialog_closed) + + 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() + self._set_status(progress.message or _execution_status_label(progress.status)) + + 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 @@ -236,13 +508,44 @@ def _status_label(status: DownloadQueueItemStatus) -> str: }[status] -def _progress_label(item: DownloadQueueItem) -> str: +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: "Processing", + DownloadExecutionStatus.COMPLETED: "Completed", + 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] + "…" diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 4655ba9..e904d08 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -184,6 +184,14 @@ def refresh_snapshot(self) -> None: self._set_status("Refreshing local MP3 library…") self._snapshot_worker = self._load_snapshot() + def invalidate_snapshot(self) -> None: + self.snapshot = None + self.preview = None + self._snapshot_worker = None + self._preview_worker = None + self._pending_snapshot = None + self._pending_preview = None + @work(thread=True, exclusive=True, group="library-snapshot", exit_on_error=False) def _load_snapshot(self) -> SnapshotOutcome: try: @@ -282,10 +290,16 @@ def _apply_preview(self, outcome: PreviewOutcome) -> None: self.preview = outcome.plan plan = outcome.plan lrc = plan.synced_files if plan.options.rmpc_enabled else 0 + lrc_destination = ( + f" · LRC dir {plan.options.lyrics_dir}" + if lrc and plan.options.lyrics_dir is not None + 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("Sync preview complete. No files were changed.") self._render_details() diff --git a/tests/test_acquisition.py b/tests/test_acquisition.py index f975227..b7b645f 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 @@ -1073,7 +1103,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: { @@ -1113,7 +1143,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: { @@ -1240,6 +1270,3 @@ def failing_postprocess(result): 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 index 4875ce1..a015748 100644 --- a/tests/test_acquisition_integration_safety.py +++ b/tests/test_acquisition_integration_safety.py @@ -9,6 +9,7 @@ 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: @@ -83,6 +84,41 @@ def embed(target, synced, plain): assert (root / "manifest.json").is_file() +def test_acquisition_uses_configured_central_lrc_directory(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, output): + output.mkdir(parents=True, exist_ok=True) + result = output / f"{target.stem}.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 == configured_lyrics / "Rental.lrc" + assert result.lrc_path.is_file() + 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 diff --git a/tests/test_core.py b/tests/test_core.py index fc846b0..ed9ad68 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -58,12 +58,13 @@ 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 f"External LRC dir: {tmp_path / 'central-lyrics'}" in out assert "MP3 files: 0" in out # Status with an MP3 file @@ -175,7 +176,76 @@ def test_config_show_preserves_missing_and_existing_cli_behavior(tmp_path, monke content = 'music_dir = "/music"\ntimeout = 20\n' config.write_text(content, encoding="utf-8") assert cli.command_config(args) == 0 - assert capsys.readouterr().out == content + "\n" + shown = capsys.readouterr().out + assert content.strip() in shown + assert f"Effective lyrics_dir: {Path.home() / 'Music' / 'lyrics'}" in shown + + +def test_lyrics_directory_default_config_override_and_unknown_keys(tmp_path, monkeypatch): + 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') + + 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 f'lyrics_dir = "{DEFAULT_LYRICS_DIR}"' in config.read_text(encoding="utf-8") + + +def test_rmpc_setup_uses_configured_lyrics_directory_without_read_time_creation( + 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, configured_lyrics)] + assert not configured_lyrics.exists() def test_config_init_and_missing_library_setup_dispatch_remain_compatible(tmp_path, monkeypatch): diff --git a/tests/test_download_queue_service.py b/tests/test_download_queue_service.py index 0114751..b82262e 100644 --- a/tests/test_download_queue_service.py +++ b/tests/test_download_queue_service.py @@ -1,7 +1,14 @@ from pathlib import Path from juice_lyrics.acquisition.jobs import JobStore -from juice_lyrics.acquisition.models import AcquisitionItem, AcquisitionState +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 ( @@ -13,10 +20,14 @@ ) from juice_lyrics.services.catalogue import CatalogueSearchResult, LyricAvailability from juice_lyrics.services.download_queue import ( + DownloadExecutionAction, + DownloadExecutionStatus, DownloadQueueItemStatus, QueueAddStatus, add_to_download_queue, + execute_selected_download, get_download_queue_snapshot, + plan_download_execution, plan_queue_additions, project_download_queue, ) @@ -174,3 +185,172 @@ def create(self, items): ) 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_library_status.py b/tests/test_library_status.py index faed53f..809fd39 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -81,7 +81,7 @@ def test_library_status_counts_lyrics_changes_lrc_and_backups(tmp_path): changed: (True, "USLT (ordinary lyrics)"), } status = get_library_status( - Settings(music_dir=library), + Settings(music_dir=library, lyrics_dir=lrc.parent), state_file=state_file, backup_dir=backup_dir, verifier=results.__getitem__, @@ -175,7 +175,7 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa ) snapshot = get_library_snapshot( - Settings(music_dir=library), + Settings(music_dir=library, lyrics_dir=lrc.parent), state_file=state_file, verifier=verification.__getitem__, duration_reader=lambda path: {synced: 180.0, plain: 181.5, missing: None}[path], @@ -201,6 +201,41 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa assert snapshot.tracks[2].lyric_status is LibraryLyricStatus.NONE +def test_library_snapshot_uses_configured_lrc_directory_not_legacy_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" + legacy.parent.mkdir(parents=True) + legacy.write_text("[00:01.00] old\n", encoding="utf-8") + 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 == configured / "Rental.lrc" + assert item.lrc_status is LibraryLrcStatus.MISSING + assert str(legacy) in (item.warning or "") + assert not configured.exists() + + 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") diff --git a/tests/test_library_sync_service.py b/tests/test_library_sync_service.py index eb38872..9f1d87e 100644 --- a/tests/test_library_sync_service.py +++ b/tests/test_library_sync_service.py @@ -199,10 +199,10 @@ def test_frontend_preview_helper_is_dry_run_and_non_mutating(tmp_path): 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), + Settings(music_dir=tmp_path, lyrics_dir=configured_lyrics), rmpc_enabled=True, - lyrics_dir=tmp_path / "lyrics", state_file=state_file, dependencies=deps, ) @@ -210,6 +210,7 @@ def test_frontend_preview_helper_is_dry_run_and_non_mutating(tmp_path): assert plan.options.dry_run is True assert plan.ready_files == 1 assert plan.synced_files == 1 + assert plan.options.lyrics_dir == configured_lyrics assert saved == [] assert path.read_bytes() == b"original" assert not backup_root.exists() @@ -252,10 +253,16 @@ def write_lrc(path, synced_lines, candidate, output): deps.lrc_writer = write_lrc deps.rmpc_notifier = lambda paths: len(paths) - options = _options(tmp_path, rmpc_enabled=True, lyrics_dir=tmp_path / "lyrics") + 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 (configured_lyrics / "Synced.lrc").is_file() + assert not (tmp_path / "lyrics").exists() assert result.lrc_files_generated == 1 assert result.rmpc_notifications == 1 diff --git a/tests/test_rmpc.py b/tests/test_rmpc.py index 7100c8f..9b2aa86 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,27 @@ 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_the_configured_central_directory(tmp_path, capsys): + configured = tmp_path / "Music" / "lyrics" + configured.mkdir(parents=True) + (configured / "Rental.lrc").write_text( + "[ar:Juice WRLD]\n[ti:Rental]\n[length:01:00]\n[00:01.00] line\n", + 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=tmp_path / "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 diff --git a/tests/test_settings_snapshot.py b/tests/test_settings_snapshot.py index 8a2327e..518ebab 100644 --- a/tests/test_settings_snapshot.py +++ b/tests/test_settings_snapshot.py @@ -14,14 +14,17 @@ 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( - settings or Settings(music_dir=tmp_path / "music"), + 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", - lyrics_dir=tmp_path / "lyrics", rmpc_config_path=kwargs.pop("rmpc_config_path", tmp_path / "rmpc" / "config.ron"), executable_finder=kwargs.pop("executable_finder", lambda name: None), **kwargs, @@ -46,6 +49,7 @@ def test_explicit_config_and_runtime_overrides_have_reliable_provenance(tmp_path 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" @@ -55,6 +59,7 @@ def test_explicit_config_and_runtime_overrides_have_reliable_provenance(tmp_path ) settings = Settings( music_dir=configured_music, + lyrics_dir=tmp_path / "configured-lyrics", api_base="https://runtime.test/api", timeout=30, delay=0.25, @@ -66,6 +71,7 @@ def test_explicit_config_and_runtime_overrides_have_reliable_provenance(tmp_path 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 @@ -73,14 +79,14 @@ def test_explicit_config_and_runtime_overrides_have_reliable_provenance(tmp_path @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", '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, encoding="utf-8") + rmpc_config.write_text(config_text.format(lyrics=tmp_path / "lyrics"), encoding="utf-8") snapshot = _snapshot( tmp_path, rmpc_config_path=rmpc_config, @@ -117,6 +123,28 @@ def test_paths_and_limitations_are_typed_and_read_only(tmp_path): assert not (tmp_path / "data").exists() +def test_effective_lyrics_directory_is_a_typed_value_and_read_only_path(tmp_path): + configured = tmp_path / "shared" / "lyrics" + settings = Settings(music_dir=tmp_path / "music", lyrics_dir=configured) + 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 values["lyrics_dir"].source is SettingsSource.RUNTIME_OVERRIDE + assert paths["lyrics"].path == configured + assert not configured.exists() + + def test_rmpc_inspection_failure_is_structured(tmp_path): snapshot = _snapshot( tmp_path, diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py index e0a44c3..d4637da 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -10,6 +10,12 @@ from juice_lyrics.config.settings import Settings from juice_lyrics.services import ( CatalogueFilterMetadata, + DownloadExecutionAction, + DownloadExecutionPlan, + DownloadExecutionResult, + DownloadExecutionStatus, + DownloadProgress, + DownloadQueueItemStatus, LibraryStatus, QueueFailureStage, QueueItem, @@ -102,8 +108,17 @@ def _snapshot(*jobs: QueueJob) -> QueueSnapshot: ) -def _app(tmp_path: Path, provider) -> JuiceLyricsApp: +def _app(tmp_path: Path, provider, *, plan=None, execute=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( @@ -111,6 +126,8 @@ def _app(tmp_path: Path, provider) -> JuiceLyricsApp: ), queue_snapshot_provider=lambda: empty, downloads_queue_provider=provider, + download_plan_provider=plan, + download_execution_provider=execute, catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), ) @@ -119,6 +136,20 @@ 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() @@ -441,3 +472,252 @@ async def scenario(): 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_confirmation_is_cancel_first_and_escape_is_safe(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() + assert app.screen.__class__.__name__ == "DownloadSelectedDialog" + body = _text(app, "#download-confirm-body") + assert "Song Queued Song" in body + assert str(tmp_path / "Queued Song.mp3") in body + assert "write the media file" in body + assert "embed lyrics" in body + assert "job" not in body.lower() + assert "[Cancel]" in _text(app, "#download-confirm-cancel") + await pilot.press("enter") + await pilot.pause() + assert app.screen.id == "screen-downloads" + assert execution_calls == [] + + await pilot.press("d") + await pilot.pause() + await pilot.press("escape") + await pilot.pause() + assert app.screen.id == "screen-downloads" + assert execution_calls == [] + assert len(plan_calls) == 2 + + 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 "Processing" 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 "No queued or failed songs" in _text(app, "#download-queue") + assert "Completed 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 "future Retry action" 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 "Completed 1" in _text(app, "#downloads-summary") + assert "No queued or failed songs" 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 index e7f2465..b117a24 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -380,6 +380,7 @@ async def scenario(): 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 f"LRC dir {screen.preview.options.lyrics_dir}" in preview_text await pilot.press("down") assert "Would update lyrics · Synced lyrics · Synced API" in _text(app, "#library-details") diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py index 27ffc80..71d10ca 100644 --- a/tests/test_tui_settings.py +++ b/tests/test_tui_settings.py @@ -34,6 +34,7 @@ def _snapshot( music = tmp_path / f"music{suffix}" values = ( SettingValue("music_dir", "Music directory", music, Path("/default/music"), SettingsSource.CONFIG), + SettingValue("lyrics_dir", "External LRC directory", tmp_path / "lyrics", Path("/default/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), @@ -42,7 +43,7 @@ def _snapshot( ) paths = ( SettingsPath("music", "Music library", music, True), - SettingsPath("lyrics", "rmpc lyrics", tmp_path / "lyrics", False), + SettingsPath("lyrics", "External synchronized LRC files", tmp_path / "lyrics", False), 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), @@ -73,7 +74,7 @@ def _snapshot( limitations=( "Local library scanning currently supports MP3 files only.", "Native FLAC support is planned but not implemented.", - "Browse and Downloads remain read-only in the TUI.", + "Settings inspection remains read-only in the TUI.", "Library sync execution remains CLI-only.", "Configuration changes remain CLI-only.", ), @@ -117,11 +118,12 @@ async def scenario(): assert "config.toml" in configuration assert str(tmp_path / "config.toml") in _text(app, "#settings-detail") assert "Music directory" in configuration and "[Config file]" in configuration + assert "External LRC directory" in configuration and "[Config file]" in configuration assert "API base URL" in configuration and "[Default]" in configuration assert "Duration tolerance" in configuration and "[Runtime override]" in configuration paths = _text(app, "#settings-paths") assert "Music library" in paths and "[Exists]" in paths - assert "rmpc lyrics" in paths and "[Missing]" in paths + assert "External synchronized LRC files" in paths and "[Missing]" in paths assert "Detected and configured" in _text(app, "#settings-integrations") capabilities = _text(app, "#settings-capabilities") assert "MP3 files only" in capabilities and "FLAC support is planned" in capabilities From 69361d019da776ddca6fac8fe9dd92407333cbff Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 1 Sep 2026 11:15:11 +0100 Subject: [PATCH 28/62] Add selected download retry --- docs/DEVELOPMENT.md | 7 +- docs/PROJECT_STATE.md | 5 +- src/juice_lyrics/services/__init__.py | 6 + src/juice_lyrics/services/download_queue.py | 200 +++++++++++++++++--- src/juice_lyrics/tui/app.py | 10 +- src/juice_lyrics/tui/screens/downloads.py | 88 +++++++++ tests/test_download_queue_service.py | 40 ++++ tests/test_tui_downloads.py | 26 +++ 8 files changed, 347 insertions(+), 35 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index b2cb142..5ef4f8c 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -86,8 +86,11 @@ Completed backend records are counted but hidden from the active queue; failed songs remain visible. Press `d` to review a cancel-first confirmation for the selected queued song. Confirming runs the existing download, validation, lyric, LRC, state, backup, and rmpc pipeline; no download starts before confirmation. -Download all, Remove, Clear, Retry, and Cancel remain unavailable. The CLI is -still required for those existing acquisition-management workflows. +Press `t` on a failed song for a cancel-first Retry confirmation. A verified +finalized file may use processing-only retry; otherwise the existing downloader +resume/redownload path is used. Download all, Remove, Clear, and Cancel remain +unavailable. The CLI is still required for those acquisition-management +workflows. In Library, arrows or `j`/`k` select local MP3 tracks, Home/End select the first or last track, and PageUp/PageDown move through longer lists. Press `/` for a diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 45aa61e..e1131f6 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -33,7 +33,8 @@ retry failures, delete durable acquisition records, and sync the library. ## Current limitations - Configuration editing remains CLI-only. -- TUI Download all, Remove, Clear, Retry, and Cancel actions are not implemented. +- TUI Download all, Remove, Clear, and Cancel actions are not implemented; one + failed selected song can be retried explicitly with `t`. - Browse currently adds one song at a time; multi-select remains planned. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and @@ -49,7 +50,7 @@ retry failures, delete durable acquisition records, and sync the library. ## Recommended next milestones 1. Downloads Download all execution -2. Downloads Remove / Clear / Retry actions +2. Downloads Remove / Clear / Cancel actions 3. Library sync actions 4. `999` command and naming migration 5. Native FLAC support diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index fc2e38d..13f4426 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -28,6 +28,10 @@ DownloadExecutionPlan, DownloadExecutionResult, DownloadExecutionStatus, + DownloadRetryAction, + DownloadRetryPlan, + DownloadRetryResult, + DownloadRetryStatus, DownloadProgress, DownloadQueueItem, DownloadQueueItemStatus, @@ -39,9 +43,11 @@ QueueDuplicateReason, add_to_download_queue, execute_selected_download, + execute_selected_retry, get_download_queue_snapshot, plan_queue_additions, plan_download_execution, + plan_download_retry, project_download_queue, ) from .library_status import ( diff --git a/src/juice_lyrics/services/download_queue.py b/src/juice_lyrics/services/download_queue.py index 4b1011a..e53727c 100644 --- a/src/juice_lyrics/services/download_queue.py +++ b/src/juice_lyrics/services/download_queue.py @@ -3,6 +3,7 @@ from collections.abc import Callable, Sequence from dataclasses import dataclass from enum import Enum +import hashlib from pathlib import Path from threading import Lock @@ -73,6 +74,22 @@ class DownloadExecutionStatus(str, Enum): 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 @@ -181,6 +198,31 @@ 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} + + QueueReader = Callable[[Path], QueueSnapshot] Resolver = Callable[..., AcquisitionItem] DuplicateFinder = Callable[..., DuplicateMatch | None] @@ -192,6 +234,7 @@ def ok(self) -> bool: _EXECUTION_CLAIM_LOCK = Lock() +_ACTIVE_EXECUTIONS: set[str] = set() def _metadata(item: QueueItem) -> dict[str, str]: @@ -465,6 +508,56 @@ def plan_download_execution( ) +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, @@ -476,6 +569,7 @@ def execute_selected_download( 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.""" @@ -485,6 +579,8 @@ def execute_selected_download( # 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.") @@ -494,7 +590,7 @@ def execute_selected_download( 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: + 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.") @@ -508,6 +604,7 @@ def execute_selected_download( entry.failure_stage = None job.touch() store.save(job) + _ACTIVE_EXECUTIONS.add(plan.reference) if progress: progress(DownloadProgress(plan.reference, DownloadExecutionStatus.DOWNLOADING, message="Downloading…")) @@ -547,10 +644,13 @@ def postprocess(result: AcquisitionResult) -> IntegrationResult: ) 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) @@ -575,32 +675,72 @@ def postprocess(result: AcquisitionResult) -> IntegrationResult: error=error, ) - 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.", - ) + 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), lyrics_dir=Path(lyrics_dir) if lyrics_dir is not None else settings.lyrics_dir, 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/tui/app.py b/src/juice_lyrics/tui/app.py index da824df..8ccba3e 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -21,7 +21,9 @@ QueueAddResult, add_to_download_queue, execute_selected_download, + execute_selected_retry, plan_download_execution, + plan_download_retry, plan_queue_additions, project_download_queue, ) @@ -713,6 +715,8 @@ def __init__( queue_add_provider: QueueAddProvider = add_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, library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, settings_snapshot_provider: SettingsSnapshotProvider = get_settings_snapshot, @@ -737,6 +741,8 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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.library_snapshot_provider = library_snapshot_provider self.library_preview_provider = library_preview_provider self.settings_snapshot_provider = settings_snapshot_provider @@ -775,6 +781,8 @@ def on_mount(self) -> None: 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, ), "downloads", ) @@ -825,7 +833,7 @@ def action_show_help(self) -> None: message = ( "↑/↓ or j/k select songs • Home/End first/last song • " "PgUp/PgDn move queue • Enter track details • d Download selected • " - "Esc queue • r refresh" + "t Retry failed • Esc queue • r refresh" ) elif section == "library": message = ( diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py index 21107a8..fc34266 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -22,6 +22,9 @@ DownloadExecutionResult, DownloadExecutionStatus, DownloadProgress, + DownloadRetryPlan, + DownloadRetryResult, + DownloadRetryStatus, DownloadQueueItem, DownloadQueueItemStatus, DownloadQueueSnapshot, @@ -31,6 +34,8 @@ QueueProvider = Callable[[], DownloadQueueSnapshot] PlanProvider = Callable[..., DownloadExecutionResult] ExecutionProvider = Callable[..., DownloadExecutionResult] +RetryPlanProvider = Callable[..., DownloadRetryResult] +RetryExecutionProvider = Callable[..., DownloadRetryResult] @dataclass(frozen=True, slots=True) @@ -139,6 +144,35 @@ def _activate(self) -> None: self.dismiss(self.plan) +class RetryFailedDialog(ModalScreen[DownloadRetryPlan | None]): + def __init__(self, plan: DownloadRetryPlan) -> None: + super().__init__(); self.plan = plan; self._confirmed = False + def compose(self) -> ComposeResult: + action = {"process_only": "Retry processing only", "resume_download": "Resume download", "download_again": "Download again"}[self.plan.action.value] + with Container(id="download-confirm-dialog"): + yield Static("Retry failed song", id="download-confirm-title") + yield Static("\n".join((f"Song {self.plan.title}", f"Destination {self.plan.destination}", f"Previous {self.plan.previous_failure}", f"Action {action}", "", "This may write media and metadata. Retry is explicit and will not affect other songs.")), 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 on_mount(self) -> None: + self.query_one("#download-confirm-download", Static).update("Retry") + self.query_one("#download-confirm-cancel", Static).update("[Cancel]") + def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: + if event.action == "cancel": self.dismiss(None) + elif not self._confirmed: self._confirmed = True; self.dismiss(self.plan) + def on_key(self, event: Key) -> None: + if event.key in {"escape", "n"}: self.dismiss(None) + elif event.key == "y": self._confirmed = True; self.dismiss(self.plan) + elif event.key == "enter": + if not self._confirmed: + self.dismiss(None) + else: + return + else: return + event.prevent_default(); event.stop() + + class DownloadsScreen(HubScreen): """Track-oriented view over the durable acquisition queue.""" @@ -149,12 +183,16 @@ def __init__( queue_provider: QueueProvider, plan_provider: PlanProvider, execution_provider: ExecutionProvider, + retry_plan_provider: RetryPlanProvider, + retry_execution_provider: RetryExecutionProvider, ) -> 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.snapshot: DownloadQueueSnapshot | None = None self.items: tuple[DownloadQueueItem, ...] = () self.selected_index = 0 @@ -162,6 +200,8 @@ def __init__( 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._active_reference: str | None = None self._live_progress: DownloadProgress | None = None self._completion_message: tuple[str, bool] | None = None @@ -214,6 +254,14 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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._execution_worker: if event.state is WorkerState.SUCCESS: self._apply_execution_result(event.worker.result) @@ -340,6 +388,8 @@ def on_key(self, event: Key) -> None: self._update_position() elif event.key == "d": self._download_selected() + elif event.key == "t": + self._retry_selected() 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) @@ -360,6 +410,44 @@ def on_key(self, event: Key) -> None: 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) + + @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.app.push_screen(RetryFailedDialog(result.plan), self._retry_dialog_closed) + + 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) diff --git a/tests/test_download_queue_service.py b/tests/test_download_queue_service.py index b82262e..047294d 100644 --- a/tests/test_download_queue_service.py +++ b/tests/test_download_queue_service.py @@ -22,12 +22,15 @@ from juice_lyrics.services.download_queue import ( DownloadExecutionAction, DownloadExecutionStatus, + DownloadRetryAction, + DownloadRetryStatus, DownloadQueueItemStatus, QueueAddStatus, add_to_download_queue, execute_selected_download, get_download_queue_snapshot, plan_download_execution, + plan_download_retry, plan_queue_additions, project_download_queue, ) @@ -116,6 +119,43 @@ def test_internal_jobs_flatten_into_tracks_and_completed_stays_out_of_active_que 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_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 diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py index d4637da..cabb301 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -23,6 +23,7 @@ QueueSnapshot, QueueStatus, ) +from juice_lyrics.services.download_queue import DownloadRetryAction, DownloadRetryPlan, DownloadRetryResult, DownloadRetryStatus from juice_lyrics.tui import JuiceLyricsApp @@ -518,6 +519,31 @@ async def scenario(): asyncio.run(scenario()) +def test_retry_failed_song_requires_confirmation_and_runs_once(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() + assert app.screen.__class__.__name__ == "RetryFailedDialog" + assert "Retry failed song" in _text(app, "#download-confirm-title") + await pilot.press("escape"); await pilot.pause() + assert calls == [] + await pilot.press("t"); await pilot.pause(); await pilot.press("y"); await pilot.pause(0.2) + 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() From 0deafc81864b202bbe37cdb5b78434144119f11c Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 1 Sep 2026 11:43:52 +0100 Subject: [PATCH 29/62] Add batch downloads and visible keybind help --- docs/DEVELOPMENT.md | 6 + docs/PROJECT_STATE.md | 10 +- src/juice_lyrics/services/__init__.py | 13 ++ src/juice_lyrics/services/download_queue.py | 214 ++++++++++++++++++++ src/juice_lyrics/tui/app.py | 31 ++- src/juice_lyrics/tui/screens/browse.py | 2 +- src/juice_lyrics/tui/screens/downloads.py | 206 ++++++++++++++++++- tests/test_download_queue_service.py | 45 ++++ tests/test_tui_downloads.py | 22 ++ 9 files changed, 534 insertions(+), 15 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 5ef4f8c..4b207e4 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -91,6 +91,12 @@ finalized file may use processing-only retry; otherwise the existing downloader resume/redownload path is used. Download all, Remove, Clear, and Cancel remain unavailable. The CLI is still required for those acquisition-management workflows. +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. +Press `A` to review and sequentially download all eligible waiting songs. +Failed and active entries are skipped and remain available for their explicit +actions. In Library, arrows or `j`/`k` select local MP3 tracks, Home/End select the first or last track, and PageUp/PageDown move through longer lists. Press `/` for a diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index e1131f6..dc469ed 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -3,7 +3,7 @@ ## Current Status Backend services remain stable. The experimental Textual frontend supports one explicit confirmed Browse Add to queue action and one explicit confirmed -Download selected action. The current checkpoint has 235 passing tests. +Download selected action. The current checkpoint has 242 passing tests. ## Current Branch v2-redesign @@ -20,6 +20,7 @@ v2-redesign - Track-oriented Downloads queue summaries, song navigation, details, structured failures, and retry eligibility; durable jobs are hidden as an internal mechanism. - Explicit cancel-first Browse Add to queue flow; adding persists one queued song but never starts downloading. - Explicit cancel-first Downloads `d` flow for one eligible queued song, delegated to the existing acquisition runner with responsive Downloading and Processing states. +- Explicit cancel-first Downloads `A` flow for sequentially downloading all eligible queued songs; failed and active entries are skipped. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. - Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. @@ -33,8 +34,9 @@ retry failures, delete durable acquisition records, and sync the library. ## Current limitations - Configuration editing remains CLI-only. -- TUI Download all, Remove, Clear, and Cancel actions are not implemented; one - failed selected song can be retried explicitly with `t`. +- TUI Cancel and multi-select remain unimplemented; `x` removes + a waiting/failed song, `c` clears waiting/failed records, and `H` clears + completed history without deleting downloaded files. - Browse currently adds one song at a time; multi-select remains planned. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and @@ -50,7 +52,7 @@ retry failures, delete durable acquisition records, and sync the library. ## Recommended next milestones 1. Downloads Download all execution -2. Downloads Remove / Clear / Cancel actions +2. Downloads Download all, Cancel, and multi-select actions 3. Library sync actions 4. `999` command and naming migration 5. Native FLAC support diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 13f4426..5122127 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -32,6 +32,14 @@ DownloadRetryPlan, DownloadRetryResult, DownloadRetryStatus, + DownloadAllPlan, + DownloadAllResult, + DownloadBatchItemResult, + DownloadBatchProgress, + DownloadBatchStatus, + QueueMutationPlan, + QueueMutationResult, + QueueMutationStatus, DownloadProgress, DownloadQueueItem, DownloadQueueItemStatus, @@ -48,6 +56,11 @@ plan_queue_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 ( diff --git a/src/juice_lyrics/services/download_queue.py b/src/juice_lyrics/services/download_queue.py index e53727c..bdab3a8 100644 --- a/src/juice_lyrics/services/download_queue.py +++ b/src/juice_lyrics/services/download_queue.py @@ -223,6 +223,73 @@ 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] @@ -440,6 +507,94 @@ def _parse_queue_reference(reference: str) -> tuple[str, int] | 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, @@ -508,6 +663,65 @@ def plan_download_execution( ) +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, lyrics_dir=lyrics_dir, 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: diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 8ccba3e..bd233ed 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -22,6 +22,11 @@ add_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_additions, @@ -379,6 +384,7 @@ class JuiceLyricsApp(App[None]): #downloads-position { height: 2; padding: 0 1; + overflow: hidden; } #downloads-status.-error { @@ -717,6 +723,11 @@ def __init__( 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_preview_provider: LibraryPreviewProvider = get_library_sync_preview, settings_snapshot_provider: SettingsSnapshotProvider = get_settings_snapshot, @@ -743,6 +754,11 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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_preview_provider = library_preview_provider self.settings_snapshot_provider = settings_snapshot_provider @@ -783,6 +799,11 @@ def on_mount(self) -> None: 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", ) @@ -827,13 +848,15 @@ def action_show_help(self) -> None: "n next catalogue page • p previous catalogue page • " "PageDown/PageUp scroll the loaded results • " "Home/End first/last loaded result • j/k select • Enter details • " - "a add selected song to queue" + "a Add to queue (does not start downloading) · 4 Downloads" ) elif section == "downloads": message = ( - "↑/↓ or j/k select songs • Home/End first/last song • " - "PgUp/PgDn move queue • Enter track details • d Download selected • " - "t Retry failed • Esc queue • r refresh" + "Navigation: 1–5 sections · ↑/↓ or j/k select · PageUp/PageDown queue · Home/End first/last · Enter details · Escape return/cancel\n" + "Download actions: d Download selected · A Download all eligible queued songs · t Retry failed\n" + "Queue management: x Remove selected · c Clear queue · H Clear completed history · r Refresh\n" + "General: ? Help · q Quit. Download selected and Download all differ; failed songs require Retry. " + "Completed songs are hidden from the active queue; cleanup never deletes downloaded music or lyrics. Jobs are internal." ) elif section == "library": message = ( diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py index a58cc0e..83dea0f 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -764,7 +764,7 @@ def _result_status(self, request: SearchRequest, page: CataloguePage) -> str: return ( f"Result {selected} of {len(page.results)} loaded · n/p pages · " f"j/k select · PgUp/PgDn scroll · Enter details" - f"{' · a add to queue' if self.results and self.results[self.selected_index].downloadable else ''}.{filters}" + f"{' · a Add to queue' if self.results and self.results[self.selected_index].downloadable else ''}.{filters}" ) def on_resize(self, event: Resize) -> None: diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py index fc34266..c0955ca 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -25,6 +25,16 @@ 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, @@ -36,6 +46,9 @@ ExecutionProvider = Callable[..., DownloadExecutionResult] RetryPlanProvider = Callable[..., DownloadRetryResult] RetryExecutionProvider = Callable[..., DownloadRetryResult] +MutationProvider = Callable[..., QueueMutationResult] +BatchPlanProvider = Callable[..., DownloadAllPlan | DownloadAllResult] +BatchExecutionProvider = Callable[..., DownloadAllResult] @dataclass(frozen=True, slots=True) @@ -173,6 +186,55 @@ def on_key(self, event: Key) -> None: event.prevent_default(); event.stop() +class QueueCleanupDialog(ModalScreen[str | None]): + def __init__(self, action: str, body: str) -> None: + super().__init__(); self.action_name = action; self.body = body; 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.query_one("#download-confirm-download", Static).update(self.action_name) + self.query_one("#download-confirm-cancel", Static).update("[Cancel]") + def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: + if event.action == "cancel": self.dismiss(None) + elif not self._confirmed: self._confirmed = True; self.dismiss(self.action_name) + def on_key(self, event: Key) -> None: + if event.key in {"escape", "n", "enter"}: self.dismiss(None) + elif event.key == "y" and not self._confirmed: self._confirmed = True; self.dismiss(self.action_name) + else: return + event.prevent_default(); event.stop() + + +class DownloadAllDialog(ModalScreen[DownloadAllPlan | None]): + def __init__(self, plan: DownloadAllPlan) -> None: + super().__init__(); self.plan = plan; self.confirmed = False + def compose(self) -> ComposeResult: + titles = "\n".join(f" {item.title}" for item in self.plan.eligible[:8]) + if len(self.plan.eligible) > 8: titles += f"\n … and {len(self.plan.eligible) - 8} more" + body = f"{len(self.plan.eligible)} song(s) will download sequentially.\n\n{titles}\n\nFailed left for Retry: {self.plan.failed_count}\nActive left alone: {self.plan.active_count}\nCompleted history: {self.plan.completed_count}\n\nThis will write media and metadata." + with Container(id="download-confirm-dialog"): + yield Static("Download all", id="download-confirm-title") + yield Static(body, id="download-confirm-body", markup=False) + with Grid(id="download-confirm-actions"): + yield DownloadDialogAction("Download all", "confirm", id="download-confirm-download") + yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") + def on_mount(self) -> None: + self.query_one("#download-confirm-download", Static).update("Download all") + self.query_one("#download-confirm-cancel", Static).update("[Cancel]") + def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: + if event.action == "cancel": self.dismiss(None) + elif not self.confirmed: self.confirmed = True; self.dismiss(self.plan) + def on_key(self, event: Key) -> None: + if event.key in {"escape", "n", "enter"}: self.dismiss(None) + elif event.key == "y" and not self.confirmed: self.confirmed = True; self.dismiss(self.plan) + else: return + event.prevent_default(); event.stop() + + class DownloadsScreen(HubScreen): """Track-oriented view over the durable acquisition queue.""" @@ -185,6 +247,11 @@ def __init__( 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 @@ -193,6 +260,11 @@ def __init__( 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 @@ -202,6 +274,9 @@ def __init__( 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 @@ -218,7 +293,7 @@ def compose_content(self) -> Iterable[Widget]: 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("d Download selected · r refresh · Enter details", id="downloads-position", markup=False) + yield Static("d selected · A all · t retry · x remove · c clear · H history · r refresh · ? 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: @@ -262,6 +337,21 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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: + 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: + self._batch_plan_worker = None + if event.state is WorkerState.SUCCESS: self._apply_batch_plan(event.worker.result) + else: self._set_status("Unable to prepare Download all.", error=True) + return + if event.worker is self._batch_worker: + self._batch_worker = None + if event.state is WorkerState.SUCCESS: self._apply_batch_result(event.worker.result) + else: self._set_status("Download all 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) @@ -308,12 +398,12 @@ def _apply_queue(self, outcome: QueueLoadOutcome) -> None: self._render_items() self._render_selected_details() if self.items: - status.update("Download queue · d Download selected") + self._update_context_status() self._update_position() self.call_after_refresh(self._scroll_selected_into_view) else: - status.update("The active download queue is empty.") - self.query_one("#downloads-position", Static).update("r refresh · Completed items stay in history") + status.update("Add songs from Browse with a") + self.query_one("#downloads-position", Static).update("a Browse add to queue · r refresh · ? help") if self._completion_message is not None: message, error = self._completion_message self._set_status(message, error=error) @@ -373,8 +463,30 @@ def _render_selected_details(self) -> None: def _update_position(self) -> None: if self.items: - suffix = "Esc queue · PgUp/PgDn details" if self._details_mode else "d Download selected · Enter details · r refresh" - self.query_one("#downloads-position", Static).update(f"Track {self.selected_index + 1} of {len(self.items)} · {suffix}") + item = self.selected_item + compact = self.size.width < 100 + if compact: + actions = "d selected · A all · t retry · x remove · r refresh · ? help" + elif item and item.status is DownloadQueueItemStatus.FAILED: + actions = "t Retry failed · x Remove · A Download all · c Clear queue · H Clear history · r Refresh · ? Help" + else: + actions = "d Download selected · A Download all · x Remove · c Clear queue · H Clear history · r Refresh · ? Help" + self.query_one("#downloads-position", Static).update(f"Track {self.selected_index + 1} of {len(self.items)} · {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("Add songs from Browse with a") + elif item.status is DownloadQueueItemStatus.QUEUED: + self._set_status("Ready to download · d selected · A all") + elif item.status is DownloadQueueItemStatus.FAILED: + self._set_status("Download failed · t retry · x remove", 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("Processing lyrics and library metadata") def on_key(self, event: Key) -> None: if event.key == "escape" and self._details_mode: @@ -390,6 +502,14 @@ def on_key(self, event: Key) -> None: 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 == "H": + self._confirm_clear_history() + elif event.key == "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) @@ -418,6 +538,79 @@ def _retry_selected(self) -> None: 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 + body = f"Song {item.title}\nStatus {_status_label(item.status)}\nDestination {item.destination or 'Unavailable'}\n\nThis removes the song from the queue. Downloaded music and lyrics will not be deleted." + self.app.push_screen(QueueCleanupDialog("Remove", body), self._cleanup_closed) + + 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 Download all…") + 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 + body = f"Queued entries {self.snapshot.queued_count}\nFailed entries {self.snapshot.failed_count}\nActive retained {active}\n\nThis clears waiting and failed queue entries. Downloaded 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 + self.app.push_screen(QueueCleanupDialog("Clear history", f"Completed history {self.snapshot.completed_count}\n\nThis removes completed download records only. Downloaded music and lyrics will remain."), self._cleanup_closed) + + 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) @@ -570,6 +763,7 @@ def _select_item(self, index: int) -> None: 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) diff --git a/tests/test_download_queue_service.py b/tests/test_download_queue_service.py index 047294d..4a4513d 100644 --- a/tests/test_download_queue_service.py +++ b/tests/test_download_queue_service.py @@ -22,6 +22,7 @@ from juice_lyrics.services.download_queue import ( DownloadExecutionAction, DownloadExecutionStatus, + DownloadAllResult, DownloadRetryAction, DownloadRetryStatus, DownloadQueueItemStatus, @@ -31,6 +32,10 @@ get_download_queue_snapshot, plan_download_execution, plan_download_retry, + plan_download_all, + remove_queue_item, + clear_download_queue, + clear_completed_history, plan_queue_additions, project_download_queue, ) @@ -156,6 +161,46 @@ def test_retry_plan_chooses_resume_or_download_again_for_transport_failure(tmp_p 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_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 diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py index cabb301..be34328 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -376,6 +376,28 @@ async def scenario(): 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),)) + messages = [] + async def scenario(): + app = _app(tmp_path, lambda: _snapshot(queued, failed)) + app.notify = lambda message, **kwargs: messages.append(message) + async with app.run_test(size=(120, 40)) as pilot: + await _open_downloads(app, pilot) + bar = _text(app, "#downloads-position") + assert "d Download selected" in bar and "A Download all" in bar and "x Remove" in bar + assert "Ready to download" in _text(app, "#downloads-status") + await pilot.press("down"); await pilot.pause() + assert "t Retry failed" in _text(app, "#downloads-position") + assert "Download failed" in _text(app, "#downloads-status") + app.action_show_help() + help_text = messages[-1] + assert "A Download all" in help_text and "H Clear completed history" in help_text + assert "cleanup never deletes downloaded music or lyrics" in help_text + asyncio.run(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),)) From c5697b42dcf2ded273d64561cd39d2dfae5c937f Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 1 Sep 2026 15:09:03 +0100 Subject: [PATCH 30/62] Harden LRC path handling and isolate tests --- PROJECT_CONTEXT.md | 8 +- README.md | 19 ++- docs/DECISIONS.md | 3 + docs/DEVELOPMENT.md | 15 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 2 +- docs/PROJECT_STATE.md | 5 +- docs/USER_GUIDE.md | 4 + src/juice_lyrics/acquisition/integration.py | 10 +- src/juice_lyrics/cli.py | 22 +-- src/juice_lyrics/config/settings.py | 30 ++++ src/juice_lyrics/services/download_queue.py | 6 +- src/juice_lyrics/services/library_status.py | 6 +- src/juice_lyrics/services/library_sync.py | 14 +- .../services/settings_snapshot.py | 11 +- src/juice_lyrics/tui/app.py | 9 +- src/juice_lyrics/tui/screens/downloads.py | 83 ++++++++-- tests/conftest.py | 28 ++++ tests/test_download_queue_service.py | 27 ++++ tests/test_library_status.py | 3 +- tests/test_lrc_path_authority.py | 152 ++++++++++++++++++ tests/test_tui_downloads.py | 120 +++++++++++++- 21 files changed, 524 insertions(+), 53 deletions(-) create mode 100644 tests/conftest.py create mode 100644 tests/test_lrc_path_authority.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 6715c75..82781f9 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -59,6 +59,12 @@ This is the application `lyrics_dir` setting and is intentionally shared across artists. Embedded lyrics remain in audio files; only synchronized external LRC files use this directory. +The resolved setting is the sole write authority. Read-only inspection and +planning do not create the directory; rmpc configuration and historical state +paths cannot redirect new output. During development use the repository entry +point (`.venv/bin/juice-lyrics`) so a stale separately installed package is not +mistaken for the current working tree. + Preserve unrelated rmpc configuration when modifying configuration files. Advanced commands: @@ -293,7 +299,7 @@ The latest development checkpoint reports: * Settings reports effective configuration, provenance where reliable, application paths, and rmpc integration without creating or changing files * TUI Download all, remove, clear, retry, cancel, configuration editing, and sync execution are not implemented * legacy CLI remains the way to run whole acquisition records, retry, delete jobs, and sync -* 235 automated tests passing across the suite +* 250 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, diff --git a/README.md b/README.md index fd9c483..28c18c7 100644 --- a/README.md +++ b/README.md @@ -142,13 +142,15 @@ This prevents common version mix-ups such as selecting `Starstruck (v1)` for `St ## rmpc -The normal `setup`/`sync` workflow uses: +External synchronized LRC files use the configured `lyrics_dir`. Its default is: ```text -~/Music/Juice WRLD/lyrics +~/Music/lyrics ``` -and safely patches the relevant rmpc lyrics settings while preserving the rest of the user's `config.ron`. +This central directory is shared across artists. Read-only commands do not create +it; it is created only when an explicitly requested operation writes an LRC. +rmpc configuration is not used as the application's output-path authority. The advanced commands remain available: @@ -191,6 +193,17 @@ python -m venv .venv pip install -e . ``` +For development checkpoints, invoke the repository environment explicitly: + +```bash +.venv/bin/juice-lyrics tui +``` + +If `command -v juice-lyrics` points at an older pipx installation, that command +will not contain current uncommitted source changes. Reinstall it deliberately or +keep using `.venv/bin/juice-lyrics`; changing the repository cannot update an +already installed copy. + ## Development Run the test suite with: diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 8367175..0957857 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -38,6 +38,9 @@ rmpc does not read embedded ID3 lyrics. rmpc currently relies on external `.lrc` lyric files. All external synchronized LRC operations use the typed `lyrics_dir` setting. +The resolved setting is the only write authority: rmpc configuration and +historical state or queue records may be inspected but cannot redirect new LRC +output. Read-only operations and plans never create the directory. Its default is the artist-independent central directory `~/Music/lyrics`, while embedded lyrics remain inside the audio files. Loading settings never creates this directory; an explicit LRC-writing workflow may create it. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 4b207e4..04f11d8 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -54,12 +54,17 @@ Keep the runtime dependency set small. ### Experimental Textual interface -From an editable installation, launch the early read-only TUI shell with: +From the repository's editable installation, launch the TUI with: ```bash -juice-lyrics tui +.venv/bin/juice-lyrics tui ``` +Use `command -v juice-lyrics` 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. + The experimental shell provides functional Dashboard, Browse, Library, Downloads, and Settings screens. Browse has one explicit Add to queue action, and Downloads can explicitly run one selected queued song. Press `/` to focus catalogue search and Enter to @@ -128,6 +133,12 @@ mkdir -p ~/Music/lyrics find ~/Music/Juice\ WRLD/lyrics -maxdepth 1 -type f -iname '*.lrc' -exec mv -n -t ~/Music/lyrics -- {} + ``` +`lyrics_dir` is the sole application destination for new LRC output. Its default +is `~/Music/lyrics`. Configuration loading, status, verification, TUI screens, +and planning do not create it; an authorized LRC write creates it immediately +before output. rmpc's configured path and historical state/job metadata are +inspection data only and cannot redirect new application output. + ## Source of truth and Git workflow 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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 2afcec8..563fe66 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -52,7 +52,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -235 passing tests. +250 passing tests. Completed and integrated: diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index dc469ed..3a40f55 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -3,7 +3,8 @@ ## Current Status Backend services remain stable. The experimental Textual frontend supports one explicit confirmed Browse Add to queue action and one explicit confirmed -Download selected action. The current checkpoint has 242 passing tests. +Download selected action. The current working-tree checkpoint has 250 passing +tests. ## Current Branch v2-redesign @@ -25,6 +26,8 @@ v2-redesign - Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. - External synchronized LRC files use the authoritative `lyrics_dir` setting, defaulting to the shared `~/Music/lyrics` directory. +- Historical state paths and rmpc configuration cannot redirect new LRC output; + read-only operations do not create either the central or legacy directory. ## Available through the CLI diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 6243731..552195e 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -26,6 +26,10 @@ The default is `~/Music/lyrics`; an explicit `lyrics_dir` overrides it. Inspect the effective value with `juice-lyrics config show`. Native FLAC support remains planned separately. +This setting is the sole destination for new external LRC files. Read-only +commands do not create the directory, rmpc configuration is not treated as an +output-path override, and historical state records cannot redirect a new write. + ## Normal day-to-day use After adding or changing local songs: diff --git a/src/juice_lyrics/acquisition/integration.py b/src/juice_lyrics/acquisition/integration.py index c09617f..8ff2aca 100644 --- a/src/juice_lyrics/acquisition/integration.py +++ b/src/juice_lyrics/acquisition/integration.py @@ -11,6 +11,7 @@ restore_file, write_manifest, ) +from ..config.settings import resolve_lyrics_dir 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 @@ -47,8 +48,13 @@ def integrate_downloaded_mp3( """ path = item.destination - if lyrics_dir is None and settings is not None: - lyrics_dir = getattr(settings, "lyrics_dir", None) + # Current settings are authoritative. The optional argument remains for + # compatibility with lower-level callers that do not have a Settings + # object, but it may not override configured output during acquisition. + if settings is not None: + lyrics_dir = resolve_lyrics_dir(settings) + elif lyrics_dir is not None: + lyrics_dir = Path(lyrics_dir).expanduser() if path.suffix.lower() != ".mp3": return IntegrationResult(path=path, message="not an MP3; lyrics integration skipped") diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 670ed3b..9873275 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -21,7 +21,7 @@ from mutagen.mp3 import MP3 from . import __version__ -from .config.settings import DEFAULT_LYRICS_DIR +from .config.settings import DEFAULT_LYRICS_DIR, resolve_lyrics_dir APP_NAME = "juice-lyrics" DEFAULT_API_BASE = "https://juicewrldapi.com/juicewrld" @@ -106,6 +106,7 @@ def load_settings(path_override: str | None = None, api_override: str | None = N 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)) @@ -552,7 +553,7 @@ def notify_rmpc_index(paths: list[Path]) -> int: def configured_rmpc_lyrics_dir(settings: Settings) -> Path: - return settings.lyrics_dir + return resolve_lyrics_dir(settings) def write_state_entry(state: dict[str, Any], path: Path, settings: Settings, analysis: dict[str, Any], lrc_path: Path | None) -> None: @@ -582,7 +583,7 @@ def state_is_current(state: dict[str, Any], path: Path, settings: Settings, want return False if want_rmpc and entry.get("lyric_type") == "SYLT": lrc = Path(entry.get("lrc") or "") - expected_lrc = settings.lyrics_dir / f"{path.stem}.lrc" + expected_lrc = resolve_lyrics_dir(settings) / f"{path.stem}.lrc" if lrc != expected_lrc or not expected_lrc.is_file(): return False return True @@ -777,6 +778,7 @@ def load_settings(path_override: str | None = None, api_override: str | None = N 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)) @@ -806,7 +808,7 @@ def command_setup(args: argparse.Namespace, settings: Settings, use_color: bool) print("Cancelled.") return 0 if rmpc_available: - patch_rmpc_config(DEFAULT_RMPC_CONFIG, settings.lyrics_dir) + patch_rmpc_config(DEFAULT_RMPC_CONFIG, resolve_lyrics_dir(settings)) files = find_mp3s(settings) return embed_batch(settings, files, use_color, args.refresh, False, True, rmpc_available) @@ -820,7 +822,7 @@ def command_sync(args: argparse.Namespace, settings: Settings, use_color: bool) dry_run=args.dry_run, refresh=args.refresh, rmpc_enabled=rmpc_enabled, - lyrics_dir=settings.lyrics_dir if rmpc_enabled else None, + lyrics_dir=resolve_lyrics_dir(settings) if rmpc_enabled else None, rmpc_config_path=DEFAULT_RMPC_CONFIG if rmpc_enabled else None, state_file=STATE_FILE, ) @@ -899,7 +901,7 @@ def command_status(settings: Settings, use_color: bool) -> int: ) print_header("Library Status", use_color) print(f"Library: {status.library_path}") - print(f"External LRC dir: {settings.lyrics_dir}") + print(f"External LRC dir: {resolve_lyrics_dir(settings)}") print(f"MP3 files: {status.track_count}") print(f"Embedded synced: {status.embedded_synced_count}") print(f"Embedded plain: {status.embedded_plain_count}") @@ -1096,7 +1098,7 @@ def command_config(args: argparse.Namespace, settings: Settings | None = None) - print(CONFIG_FILE.read_text(encoding="utf-8").rstrip()) else: print(f"No config. Defaults are in use.\n{CONFIG_FILE}") - print(f"Effective lyrics_dir: {effective.lyrics_dir}") + print(f"Effective lyrics_dir: {resolve_lyrics_dir(effective)}") return 0 raise RuntimeError("Unknown config action") @@ -1110,7 +1112,7 @@ def command_cache(args: argparse.Namespace) -> int: 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 settings.lyrics_dir + lyrics_dir = resolve_lyrics_dir(settings, explicit_override=args.lyrics_dir) if not lyrics_dir.is_absolute(): lyrics_dir = lyrics_dir.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}") @@ -1140,7 +1142,7 @@ def command_rmpc_setup(args: argparse.Namespace, settings: Settings, use_color: 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 settings.lyrics_dir + lyrics_dir = resolve_lyrics_dir(settings, explicit_override=args.lyrics_dir) generated = [] for path in find_mp3s(settings): a = analyse(settings, path, args.refresh) @@ -1152,7 +1154,7 @@ def command_rmpc_sync(args: argparse.Namespace, settings: Settings, use_color: b 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 settings.lyrics_dir + lyrics_dir = resolve_lyrics_dir(settings, explicit_override=args.lyrics_dir) files = sorted(lyrics_dir.glob("*.lrc")) if lyrics_dir.is_dir() else [] good = bad = 0 for path in files: diff --git a/src/juice_lyrics/config/settings.py b/src/juice_lyrics/config/settings.py index fec84d0..d26184a 100644 --- a/src/juice_lyrics/config/settings.py +++ b/src/juice_lyrics/config/settings.py @@ -12,6 +12,8 @@ DEFAULT_DURATION_TOLERANCE = 3.0 DEFAULT_CACHE_TTL_HOURS = 24 DEFAULT_LYRICS_DIR = Path.home() / "Music" / "lyrics" +# Historical compatibility sentinel only; never use this as an output default. +LEGACY_IMPLICIT_LYRICS_DIR = Path.home() / "Music" / "Juice WRLD" / "lyrics" def xdg_dir(name: str, fallback: Path) -> Path: @@ -38,7 +40,35 @@ class Settings: delay: float = DEFAULT_DELAY duration_tolerance: float = DEFAULT_DURATION_TOLERANCE cache_ttl_hours: float = DEFAULT_CACHE_TTL_HOURS + # Set by configuration loading when lyrics_dir was deliberately supplied. + # It lets the compatibility guard distinguish an intentional legacy path + # from the pre-lyrics_dir implicit default. + 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 sole destination for newly written external LRC files. + + The old application default was derived from ``DEFAULT_MUSIC_DIR``. A + stale in-memory settings object using that implicit value must not recreate + the old artist-specific directory. An explicit TOML value (or an explicit + advanced-command override) remains respected, including that exact 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/services/download_queue.py b/src/juice_lyrics/services/download_queue.py index bdab3a8..bec6bc2 100644 --- a/src/juice_lyrics/services/download_queue.py +++ b/src/juice_lyrics/services/download_queue.py @@ -20,7 +20,7 @@ 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 ..config.settings import Settings, resolve_lyrics_dir from .acquisition_queue import ( QueueFailureStage, QueueItem, @@ -844,7 +844,7 @@ def postprocess(result: AcquisitionResult) -> IntegrationResult: return integration( entry.item, song_fetcher=lambda song_id: song_fetcher(settings, song_id), - lyrics_dir=Path(lyrics_dir) if lyrics_dir is not None else settings.lyrics_dir, + lyrics_dir=resolve_lyrics_dir(settings), settings=settings, ) @@ -946,7 +946,7 @@ def report(index: int, total: int, written: int, remote_total: int | None) -> No 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), lyrics_dir=Path(lyrics_dir) if lyrics_dir is not None else settings.lyrics_dir, settings=settings) + return integration(entry.item, song_fetcher=lambda song_id: song_fetcher(settings, song_id), lyrics_dir=resolve_lyrics_dir(settings), 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 diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index ff1eed4..3ef0d2e 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -7,7 +7,7 @@ from pathlib import Path from typing import Any -from ..config.settings import BACKUP_DIR, STATE_FILE, Settings +from ..config.settings import BACKUP_DIR, STATE_FILE, Settings, resolve_lyrics_dir from ..library.scanner import find_mp3s from ..library.matching import local_duration from ..lyrics.engine import verify_file @@ -224,7 +224,7 @@ def get_library_snapshot( else None ) lrc_path = ( - Path(settings.lyrics_dir) / f"{path.stem}.lrc" + resolve_lyrics_dir(settings) / f"{path.stem}.lrc" if lyric_status is LibraryLyricStatus.SYNCED else None ) @@ -302,7 +302,7 @@ def get_library_status( if ( valid and message.startswith("SYLT") - and (Path(settings.lyrics_dir) / f"{path.stem}.lrc").is_file() + and (resolve_lyrics_dir(settings) / f"{path.stem}.lrc").is_file() ): lrc += 1 diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index 44b8db2..9b4c169 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -10,7 +10,7 @@ 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 ..config.settings import DEFAULT_RMPC_CONFIG, STATE_FILE, Settings, resolve_lyrics_dir from ..library.matching import choose_candidate, search_title_for from ..library.scanner import find_mp3s from ..lyrics.engine import embed_lyrics, parse_synced_lyrics, verify_file, write_lrc @@ -61,6 +61,12 @@ class LibrarySyncOptions: duration_tolerance: float = 3.0 state_file: Path = STATE_FILE + def __post_init__(self) -> None: + # A plan may contain historical state paths, but all new LRC output is + # derived from current settings at the application boundary. + authoritative = resolve_lyrics_dir(self.settings) if self.rmpc_enabled else None + object.__setattr__(self, "lyrics_dir", authoritative) + @classmethod def from_settings( cls, @@ -79,11 +85,7 @@ def from_settings( dry_run=dry_run, refresh=refresh, rmpc_enabled=rmpc_enabled, - lyrics_dir=( - Path(lyrics_dir) - if lyrics_dir is not None - else (Path(settings.lyrics_dir) if rmpc_enabled else None) - ), + lyrics_dir=resolve_lyrics_dir(settings) if rmpc_enabled else 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), diff --git a/src/juice_lyrics/services/settings_snapshot.py b/src/juice_lyrics/services/settings_snapshot.py index f77a1a0..3dda1aa 100644 --- a/src/juice_lyrics/services/settings_snapshot.py +++ b/src/juice_lyrics/services/settings_snapshot.py @@ -25,6 +25,7 @@ DEFAULT_TIMEOUT, STATE_FILE, Settings, + resolve_lyrics_dir, ) SettingScalar: TypeAlias = str | int | float | Path @@ -198,7 +199,7 @@ def get_settings_snapshot( """Inspect effective settings and environment without creating or changing files.""" config_path = Path(config_path) - effective_lyrics_dir = Path(settings.lyrics_dir) + effective_lyrics_dir = resolve_lyrics_dir(settings) config: dict[str, object] = {} try: config_exists = config_path.exists() @@ -213,13 +214,17 @@ def get_settings_snapshot( except Exception as exc: raise RuntimeError(f"Could not read config {config_path}: {exc}") from exc + effective_values = { + key: (effective_lyrics_dir if key == "lyrics_dir" else getattr(settings, key)) + for key, _, _ in _SETTING_SPECS + } values = tuple( SettingValue( key, label, - getattr(settings, key), + effective_values[key], default, - _source_for(key, getattr(settings, key), default, config), + _source_for(key, effective_values[key], default, config), ) for key, label, default in _SETTING_SPECS ) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index bd233ed..655d9d8 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -5,6 +5,7 @@ from textual.app import App from textual.binding import Binding +from textual.screen import ModalScreen from ..services.acquisition_queue import QueueSnapshot, get_queue_snapshot from ..services.catalogue import ( @@ -330,7 +331,10 @@ class JuiceLyricsApp(App[None]): text-style: bold; } - DownloadSelectedDialog { + DownloadSelectedDialog, + RetryFailedDialog, + QueueCleanupDialog, + DownloadAllDialog { align: center middle; background: transparent; } @@ -338,6 +342,7 @@ class JuiceLyricsApp(App[None]): #download-confirm-dialog { width: 76; max-width: 92%; + max-height: 88%; height: auto; padding: 1 2; border: round ansi_cyan; @@ -817,6 +822,8 @@ def on_mount(self) -> None: 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) diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py index c0955ca..63b9d10 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -65,7 +65,7 @@ class ExecutionPlanOutcome: class DownloadDialogAction(Static): - can_focus = False + can_focus = True class Activated(Message): def __init__(self, action: str) -> None: @@ -113,6 +113,8 @@ def compose(self) -> ComposeResult: 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" @@ -141,6 +143,8 @@ def on_key(self, event: Key) -> None: 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: @@ -188,7 +192,11 @@ def on_key(self, event: Key) -> None: class QueueCleanupDialog(ModalScreen[str | None]): def __init__(self, action: str, body: str) -> None: - super().__init__(); self.action_name = action; self.body = body; self._confirmed = False + 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") @@ -197,16 +205,54 @@ def compose(self) -> ComposeResult: yield DownloadDialogAction(self.action_name, "confirm", id="download-confirm-download") yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") def on_mount(self) -> None: - self.query_one("#download-confirm-download", Static).update(self.action_name) - self.query_one("#download-confirm-cancel", Static).update("[Cancel]") + 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 event.action == "cancel": self.dismiss(None) - elif not self._confirmed: self._confirmed = True; self.dismiss(self.action_name) + if self._confirmed: + return + self._choice = event.action + self._render_choice() + self._activate() + def on_key(self, event: Key) -> None: - if event.key in {"escape", "n", "enter"}: self.dismiss(None) - elif event.key == "y" and not self._confirmed: self._confirmed = True; self.dismiss(self.action_name) - else: return - event.prevent_default(); event.stop() + 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() + 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.dismiss(None) + elif not self._confirmed: + self._confirmed = True + self.dismiss(self.action_name) class DownloadAllDialog(ModalScreen[DownloadAllPlan | None]): @@ -215,7 +261,8 @@ def __init__(self, plan: DownloadAllPlan) -> None: def compose(self) -> ComposeResult: titles = "\n".join(f" {item.title}" for item in self.plan.eligible[:8]) if len(self.plan.eligible) > 8: titles += f"\n … and {len(self.plan.eligible) - 8} more" - body = f"{len(self.plan.eligible)} song(s) will download sequentially.\n\n{titles}\n\nFailed left for Retry: {self.plan.failed_count}\nActive left alone: {self.plan.active_count}\nCompleted history: {self.plan.completed_count}\n\nThis will write media and metadata." + count = len(self.plan.eligible) + body = f"{count} {'song' if count == 1 else 'songs'} will download sequentially.\n\n{titles}\n\nFailed left for Retry: {self.plan.failed_count}\nActive left alone: {self.plan.active_count}\nCompleted history: {self.plan.completed_count}\n\nThis will write media and metadata." with Container(id="download-confirm-dialog"): yield Static("Download all", id="download-confirm-title") yield Static(body, id="download-confirm-body", markup=False) @@ -338,16 +385,24 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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: self._set_status("Unable to prepare Download all.", error=True) + else: + detail = str(event.worker.error) if event.worker.error else "Unknown planning error" + self._set_status(f"Unable to prepare Download all: {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("Download all failed safely.", error=True) @@ -506,9 +561,9 @@ def on_key(self, event: Key) -> None: self._remove_selected() elif event.key == "c": self._confirm_clear_queue() - elif event.key == "H": + elif event.key in {"H", "shift+h"}: self._confirm_clear_history() - elif event.key == "A": + 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) 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/test_download_queue_service.py b/tests/test_download_queue_service.py index 4a4513d..034965a 100644 --- a/tests/test_download_queue_service.py +++ b/tests/test_download_queue_service.py @@ -23,6 +23,7 @@ DownloadExecutionAction, DownloadExecutionStatus, DownloadAllResult, + DownloadAllPlan, DownloadRetryAction, DownloadRetryStatus, DownloadQueueItemStatus, @@ -33,6 +34,7 @@ plan_download_execution, plan_download_retry, plan_download_all, + execute_download_all, remove_queue_item, clear_download_queue, clear_completed_history, @@ -201,6 +203,31 @@ def test_download_all_plan_includes_only_waiting_songs(tmp_path): 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 diff --git a/tests/test_library_status.py b/tests/test_library_status.py index 809fd39..0fbcca8 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -207,8 +207,6 @@ def test_library_snapshot_uses_configured_lrc_directory_not_legacy_state_path(tm track = library / "Rental.mp3" track.write_bytes(b"audio") legacy = tmp_path / "Music" / "Juice WRLD" / "lyrics" / "Rental.lrc" - legacy.parent.mkdir(parents=True) - legacy.write_text("[00:01.00] old\n", encoding="utf-8") configured = tmp_path / "Music" / "lyrics" state_file = tmp_path / "state.json" state_file.write_text(json.dumps({ @@ -233,6 +231,7 @@ def test_library_snapshot_uses_configured_lrc_directory_not_legacy_state_path(tm assert item.lrc_path == configured / "Rental.lrc" assert item.lrc_status is LibraryLrcStatus.MISSING assert str(legacy) in (item.warning or "") + assert not legacy.parent.exists() assert not configured.exists() diff --git a/tests/test_lrc_path_authority.py b/tests/test_lrc_path_authority.py new file mode 100644 index 0000000..39d18d7 --- /dev/null +++ b/tests/test_lrc_path_authority.py @@ -0,0 +1,152 @@ +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +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_stale_lrc_override_when_settings_are_available( + 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, output): + outputs.append(output) + output.mkdir(parents=True, exist_ok=True) + result = output / "Rental.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 == [central] + assert result.lrc_path == central / "Rental.lrc" + 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"), + ) + 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_tui_downloads.py b/tests/test_tui_downloads.py index be34328..5dfed81 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -14,6 +14,9 @@ DownloadExecutionPlan, DownloadExecutionResult, DownloadExecutionStatus, + DownloadAllPlan, + DownloadAllResult, + DownloadBatchStatus, DownloadProgress, DownloadQueueItemStatus, LibraryStatus, @@ -22,6 +25,8 @@ QueueJob, QueueSnapshot, QueueStatus, + QueueMutationResult, + QueueMutationStatus, ) from juice_lyrics.services.download_queue import DownloadRetryAction, DownloadRetryPlan, DownloadRetryResult, DownloadRetryStatus from juice_lyrics.tui import JuiceLyricsApp @@ -109,7 +114,7 @@ def _snapshot(*jobs: QueueJob) -> QueueSnapshot: ) -def _app(tmp_path: Path, provider, *, plan=None, execute=None) -> JuiceLyricsApp: +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, @@ -129,6 +134,9 @@ def _app(tmp_path: Path, provider, *, plan=None, execute=None) -> JuiceLyricsApp 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((), ()), ) @@ -398,6 +406,116 @@ async def scenario(): 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 "1 song will download sequentially" in _text(app, "#download-confirm-body") + 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("y"); await pilot.pause(0.2) + assert calls == [1] + assert "1 completed" in _text(app, "#downloads-status") + + asyncio.run(scenario()) + + +def test_clear_history_modal_is_centered_cancel_first_and_keyboard_confirmable(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) + shortcut = downloads.query_one("#downloads-position") + await pilot.press("shift+h"); await pilot.pause() + assert app.screen.__class__.__name__ == "QueueCleanupDialog" + dialog = app.query_one("#download-confirm-dialog") + assert abs(dialog.region.center[0] - 40) <= 1 + assert abs(dialog.region.center[1] - 12) <= 1 + assert dialog.region.bottom <= shortcut.region.y + assert app.focused is not None and app.focused.id == "download-confirm-cancel" + assert "Downloaded music and lyrics will remain" in _text(app, "#download-confirm-body") + assert "Clear history" in _text(app, "#download-confirm-download") + await pilot.press("enter"); await pilot.pause() + assert calls == [] and app.screen.id == "screen-downloads" + + await pilot.press("shift+h"); await pilot.pause() + await pilot.press("2"); await pilot.pause() + assert app.screen.__class__.__name__ == "QueueCleanupDialog" + await pilot.press("tab"); await pilot.pause() + assert app.focused is not None and app.focused.id == "download-confirm-download" + await pilot.press("enter"); await pilot.pause(0.2) + assert calls == ["clear"] + assert audio.read_bytes() == b"audio" + assert lrc.read_text(encoding="utf-8") == "lyrics" + + asyncio.run(scenario()) + + +def test_clear_history_escape_n_and_y_are_safe_and_exactly_once(tmp_path): + completed = _job(1, "history", (_item(tmp_path, "Finished", QueueStatus.COMPLETED),)) + + async def cancel_scenario(key): + calls = [] + app = _app(tmp_path, lambda: _snapshot(completed), history=lambda: calls.append("clear")) + async with app.run_test(size=(80, 24)) as pilot: + await _open_downloads(app, pilot) + await pilot.press("shift+h"); await pilot.pause() + await pilot.press(key); await pilot.pause() + assert app.screen.id == "screen-downloads" and calls == [] + + 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() + await pilot.press("y", "y"); await pilot.pause(0.2) + assert calls == ["clear"] + + asyncio.run(cancel_scenario("escape")) + asyncio.run(cancel_scenario("n")) + 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),)) From b09c186a2e69f8addc3d55e52ca56d9dbc193345 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 1 Sep 2026 23:56:24 +0100 Subject: [PATCH 31/62] Add Browse multi-select and batch queue addition --- PROJECT_CONTEXT.md | 11 +- docs/DECISIONS.md | 14 +- docs/DEVELOPMENT.md | 9 +- docs/PROJECT_STATE.md | 14 +- docs/ROADMAP_V2.md | 19 +- docs/UI_DESIGN.md | 10 +- docs/USER_FLOWS.md | 11 +- src/juice_lyrics/services/__init__.py | 14 + src/juice_lyrics/services/download_queue.py | 209 ++++++++++++ src/juice_lyrics/tui/app.py | 34 +- src/juice_lyrics/tui/screens/browse.py | 346 ++++++++++++++++---- tests/test_download_queue_service.py | 98 +++++- tests/test_tui_browse.py | 236 +++++++++++++ 13 files changed, 919 insertions(+), 106 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 82781f9..177c98d 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -235,8 +235,9 @@ The job system should: Persistent jobs are an internal durability and execution mechanism. The normal product model is a flat download queue of songs; UUIDs should stay out of common -workflows. Browse can explicitly add one selected song to this queue without -starting it. Completed items remain stored but are hidden from the active queue, +workflows. Browse can mark stable song IDs across pages of one search and +explicitly add the marked set (or the current song) without starting it. +Completed items remain stored but are hidden from the active queue, and failed items remain visible for future retry or removal. ## Acquisition → lyrics integration @@ -290,16 +291,16 @@ The latest development checkpoint reports: * MP3 post-processing with ID3 SYLT/USLT and rmpc LRC integration verified * Settings / Path CLI compatibility verified * responsive terminal-native Textual shell with `ansi_color=True` -* all five main TUI sections are functional; Browse can explicitly add one selected song to the queue +* all five main TUI sections are functional; Browse can explicitly add one or several stable-ID selections to the queue * Downloads can explicitly run one selected queued song after a cancel-first confirmation * canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details * flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility * Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews * Settings reports effective configuration, provenance where reliable, application paths, and rmpc integration without creating or changing files -* TUI Download all, remove, clear, retry, cancel, configuration editing, and sync execution are not implemented +* TUI active-download cancel, configuration editing, and sync execution are not implemented * legacy CLI remains the way to run whole acquisition records, retry, delete jobs, and sync -* 250 automated tests passing across the suite +* 258 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 0957857..4c1df74 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -137,10 +137,16 @@ 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. -Download selected is the first implemented queue execution action and requires -a cancel-first confirmation for one eligible song. Download all, Remove, Clear, -Retry, and Cancel remain planned. Each mutating action requires its own explicit -safe workflow. +Download selected, sequential Download all, Retry, Remove, Clear queue, and +Clear completed history each use an explicit cancel-first workflow. Active +download cancellation remains planned. + +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. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 04f11d8..b1858e9 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -66,7 +66,7 @@ tree; reinstall it deliberately after a checkpoint or use the explicit `.venv` command above. The experimental shell provides functional Dashboard, Browse, Library, -Downloads, and Settings screens. Browse has one explicit Add to queue action, +Downloads, and Settings screens. Browse has explicit single- and batch-selection Add to queue actions, and Downloads can explicitly run one selected queued song. 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 @@ -75,8 +75,11 @@ 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. Press `a` on a downloadable result to review its resolved -destination and explicitly add it to the download queue. The cancel-first dialog +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 review and add the marked songs, or the highlighted song when none +are marked. The cancel-first dialog reports eligible and skipped songs and states that adding 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. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 3a40f55..870eb1c 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,9 +1,9 @@ # 999 Project State ## Current Status -Backend services remain stable. The experimental Textual frontend supports one -explicit confirmed Browse Add to queue action and one explicit confirmed -Download selected action. The current working-tree checkpoint has 250 passing +Backend services remain stable. The experimental Textual frontend supports +explicit confirmed single- and multi-song Browse Add to queue actions and +Download selected action. The current working-tree checkpoint has 258 passing tests. ## Current Branch @@ -16,10 +16,11 @@ v2-redesign ## Completed and integrated - Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. -- Responsive terminal-native Textual shell with all five main sections functional; inspection remains read-only and Browse has one explicit Add to queue mutation. +- Responsive terminal-native Textual shell with all five main sections functional; Browse supports explicit single- and batch Add to queue mutations. - Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. - Track-oriented Downloads queue summaries, song navigation, details, structured failures, and retry eligibility; durable jobs are hidden as an internal mechanism. -- Explicit cancel-first Browse Add to queue flow; adding persists one queued song but never starts downloading. +- Stable-ID Browse marks span pages within one logical search; Space toggles a song, `M` toggles the page, `u` clears marks, and search/filter changes clear hidden marks. +- Explicit cancel-first Browse batch Add flow reports eligible and skipped songs, persists eligible songs atomically, and never starts downloading. - Explicit cancel-first Downloads `d` flow for one eligible queued song, delegated to the existing acquisition runner with responsive Downloading and Processing states. - Explicit cancel-first Downloads `A` flow for sequentially downloading all eligible queued songs; failed and active entries are skipped. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. @@ -37,10 +38,9 @@ retry failures, delete durable acquisition records, and sync the library. ## Current limitations - Configuration editing remains CLI-only. -- TUI Cancel and multi-select remain unimplemented; `x` removes +- Active-download Cancel remains unimplemented; `x` removes a waiting/failed song, `c` clears waiting/failed records, and `H` clears completed history without deleting downloaded files. -- Browse currently adds one song at a time; multi-select remains planned. - Native FLAC support remains planned; lyric post-processing is currently MP3-only. - The planned executable/product name remains `999`; package, distribution, and data paths remain named `juice-lyrics`. diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 7a0b2b5..4cd1591 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -134,8 +134,9 @@ Goal: Create the main application interface. Status: In progress. The responsive terminal-native shell and all five primary -sections are integrated. Browse has an explicit confirmed Add to queue action; -download execution and other mutations remain CLI-only. +sections are integrated. Browse supports explicitly confirmed single- and +multi-song Add to queue actions, and Downloads provides selected, sequential +all, retry, and record-only cleanup actions. Screens: @@ -149,8 +150,9 @@ Features: - Lyrics preview. - Download actions. -Status: Read-only functionality complete, including server-side pagination and -scrollable 50-result pages. Download actions remain planned. +Status: Catalogue functionality is complete, including server-side pagination, +scrollable 50-result pages, cross-page stable-ID marking, and explicitly +confirmed batch Add to queue. Adding does not start downloads. --- @@ -178,10 +180,11 @@ Features: - Completed items. - Retry. -Status: Track-oriented queue projection, Browse Add to queue, and explicitly -confirmed Download selected are complete. Durable jobs remain internal, -completed entries are hidden from the active queue, and failed entries remain -visible. Download all, Remove, Clear, Retry, and Cancel remain planned. +Status: Track-oriented queue projection, Browse batch Add, explicitly confirmed +Download selected, sequential Download all, Retry, and record-only cleanup are +complete. Durable jobs remain internal, completed entries are hidden from the +active queue, and failed entries remain visible. Active cancellation remains +planned. --- diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 55b10f6..58fab26 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -303,10 +303,12 @@ 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 `a` to open an explicit Add to queue confirmation. The dialog shows -the resolved destination and states that adding will not start a download. -Future queue actions are Download selected, Download all, Remove, Clear, Retry, -and Cancel. +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` opens an explicit confirmation +for the marked set, or the current song when nothing is marked. The dialog shows +eligible/skipped counts and destination information and states that adding will +not start a download. Example: diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 0a2947a..157a467 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -256,16 +256,19 @@ Too technical. v2 user-facing model: -Browse → select a song → press `a` → review destination → Add to queue +Browse → mark songs with Space → press `a` → review eligible/skipped songs → Add to 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. -Planned follow-up interactions include Space to toggle multiple selections, -`a` to add selected songs, and a bounded explicitly confirmed `A` action. The -application will not bulk-fetch an unbounded catalogue merely to fill a queue. +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` adds the +marked set, or the highlighted song when nothing is marked, through a +cancel-first confirmation. Adding never starts a download and the application +does not bulk-fetch an unbounded catalogue merely to fill the queue. Download selected is implemented for one queued song. Download all, Remove, Clear queue, Retry failed, and Cancel active download remain future actions. diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 5122127..c1ee02f 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -45,15 +45,22 @@ 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, @@ -132,6 +139,11 @@ "QueueAddPlan", "QueueAddResult", "QueueAddStatus", + "QueueBatchAddItem", + "QueueBatchAddItemStatus", + "QueueBatchAddPlan", + "QueueBatchAddResult", + "QueueBatchAddStatus", "QueueDuplicateReason", "QueueFailureStage", "QueueJob", @@ -162,8 +174,10 @@ "plan_library_sync", "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/download_queue.py b/src/juice_lyrics/services/download_queue.py index bec6bc2..a0d0fa5 100644 --- a/src/juice_lyrics/services/download_queue.py +++ b/src/juice_lyrics/services/download_queue.py @@ -56,6 +56,22 @@ class QueueAddStatus(str, Enum): 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" @@ -157,6 +173,53 @@ 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 @@ -500,6 +563,152 @@ def add_to_download_queue( ) +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(): diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 655d9d8..45c6073 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -20,7 +20,8 @@ DownloadExecutionResult, DownloadQueueSnapshot, QueueAddResult, - add_to_download_queue, + QueueBatchAddResult, + add_batch_to_download_queue, execute_selected_download, execute_selected_retry, remove_queue_item, @@ -30,7 +31,7 @@ execute_download_all, plan_download_execution, plan_download_retry, - plan_queue_additions, + plan_queue_batch_additions, project_download_queue, ) from ..services.library_status import LibrarySnapshot, LibraryStatus, get_library_snapshot, get_library_status @@ -46,8 +47,8 @@ LibraryStatusProvider = Callable[[Any], LibraryStatus] QueueSnapshotProvider = Callable[[], QueueSnapshot] DownloadQueueProvider = Callable[[], DownloadQueueSnapshot] -QueuePlanProvider = Callable[..., QueueAddResult] -QueueAddProvider = Callable[..., QueueAddResult] +QueuePlanProvider = Callable[..., QueueAddResult | QueueBatchAddResult] +QueueAddProvider = Callable[..., QueueAddResult | QueueBatchAddResult] DownloadPlanProvider = Callable[..., DownloadExecutionResult] DownloadExecutionProvider = Callable[..., DownloadExecutionResult] CatalogueSearchProvider = Callable[..., CataloguePage] @@ -252,6 +253,15 @@ class JuiceLyricsApp(App[None]): 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; @@ -291,6 +301,7 @@ class JuiceLyricsApp(App[None]): width: 72; max-width: 92%; height: auto; + max-height: 92%; padding: 1 2; border: round ansi_cyan; background: transparent; @@ -722,8 +733,8 @@ def __init__( 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_additions, - queue_add_provider: QueueAddProvider = add_to_download_queue, + 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, @@ -852,10 +863,13 @@ def action_show_help(self) -> None: section = getattr(self.screen, "section", None) if section == "browse": message = ( - "n next catalogue page • p previous catalogue page • " - "PageDown/PageUp scroll the loaded results • " - "Home/End first/last loaded result • j/k select • Enter details • " - "a Add to queue (does not start downloading) · 4 Downloads" + "Navigation: ↑/↓ or j/k move results · PageDown/PageUp scroll the loaded results · " + "n next catalogue page · p previous catalogue page · Home/End first/last loaded result · " + "Enter details · Escape close/cancel\n" + "Selection: Space mark/unmark · M toggle downloadable songs on this page · u clear all marks. " + "Marks may span pages of one search; changing search or filters clears them.\n" + "Queue: a Add marked songs, or the current song when none are marked · 4 Downloads. " + "Marking does not add songs; adding does not start downloading. Downloads handles actual downloads." ) elif section == "downloads": message = ( diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py index 83dea0f..30c857e 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -1,7 +1,7 @@ from __future__ import annotations from collections.abc import Callable, Iterable -from dataclasses import dataclass +from dataclasses import dataclass, replace from math import ceil from typing import Any @@ -25,14 +25,24 @@ LyricAvailability, SongDetails, ) -from ...services.download_queue import QueueAddPlan, QueueAddResult, QueueAddStatus +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] -QueuePlanProvider = Callable[..., QueueAddResult] -QueueAddProvider = Callable[[QueueAddPlan], QueueAddResult] +QueuePlanResult = QueueAddResult | QueueBatchAddResult +QueuePlan = QueueAddPlan | QueueBatchAddPlan +QueuePlanProvider = Callable[..., QueuePlanResult] +QueueAddProvider = Callable[[QueuePlan], QueuePlanResult] _PREVIEW_LINES = 6 _PAGE_SIZE = 50 @@ -127,13 +137,14 @@ class FiltersOutcome: @dataclass(frozen=True, slots=True) class QueuePlanOutcome: - selection: CatalogueSearchResult - result: QueueAddResult | None = None + selections: tuple[CatalogueSearchResult, ...] + result: QueuePlanResult | None = None + marked: bool = False error: str | None = None class QueueDialogAction(Static): - can_focus = False + can_focus = True class Activated(Message): def __init__(self, action: str) -> None: @@ -148,51 +159,89 @@ def on_click(self, event: Click) -> None: self.post_message(self.Activated(self.action)) -class AddToQueueDialog(ModalScreen[QueueAddResult | None]): - """Explicit, cancel-first confirmation for one durable queue addition.""" +class AddToQueueDialog(ModalScreen[QueuePlanResult | None]): + """Explicit, cancel-first confirmation for one or more queue additions.""" - def __init__(self, plan: QueueAddPlan, creator: QueueAddProvider) -> None: + 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: QueueAddResult | None = None - self._worker: Worker[QueueAddResult] | None = None + 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: - planned = self.plan.items[0] - item = planned.item with Container(id="queue-confirm-dialog"): - yield Static("Add to download queue", id="queue-confirm-title") - yield Static( - "\n".join(( - f"Song {item.title}", - f"Artist {planned.artist or 'Unknown'}", - f"Category {planned.category or 'Unknown'}", - f"Era {planned.era or 'Unknown'}", - f"Destination {item.destination}", - "Availability Available", - "", - "This adds the song to your download queue. It will not start downloading yet.", - )), - id="queue-confirm-body", - markup=False, - ) + 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("Add to queue", "confirm", id="queue-confirm-add") + 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 "\n".join(( + f"Song {item.title}", + f"Artist {planned.artist or 'Unknown'}", + f"Category {planned.category or 'Unknown'}", + f"Era {planned.era or 'Unknown'}", + f"Destination {item.destination}", + "Availability Available", + "", + "This adds the song to your download queue. It will not start downloading yet.", + )) + eligible = self.plan.eligible + 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) + destinations = {item.item.destination.parent for item in eligible} + destination = str(next(iter(destinations))) if len(destinations) == 1 else "Multiple configured destinations" + return "\n".join(( + f"Selected {self.plan.selected_count} · Eligible {self.plan.eligible_count}", + f"Skipped: {queued} queued · {unavailable + invalid} unavailable · {local} downloaded", + f"Destination: {destination}", + "", + *preview, + "", + ( + "This adds the song to Downloads. It does not start downloading." + if self.plan.selected_count == 1 + else "This adds songs to Downloads. It does not start downloading." + ), + )) + 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 = "[Add to queue]" if self._choice == "confirm" else "Add to queue" + 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) @@ -229,6 +278,10 @@ def on_key(self, event: Key) -> None: 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: @@ -247,10 +300,12 @@ def _activate_choice(self) -> None: self._worker = self._create_queue_item() @work(thread=True, exclusive=True, group="queue-add", exit_on_error=False) - def _create_queue_item(self) -> QueueAddResult: + 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: @@ -259,11 +314,15 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: if event.state is WorkerState.SUCCESS: result = event.worker.result elif event.state is WorkerState.ERROR: - result = QueueAddResult(QueueAddStatus.SAVE_FAILED, "Unable to save the queue.") + 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 is QueueAddStatus.ADDED: + if result.status in {QueueAddStatus.ADDED, QueueBatchAddStatus.ADDED}: self._created_result = result invalidate = getattr(self.app, "invalidate_download_queue", None) if callable(invalidate): @@ -315,6 +374,10 @@ def __init__( self._filters_worker: Worker[FiltersOutcome] | None = None self._queue_plan_worker: Worker[QueuePlanOutcome] | None = None self._applying_filters = False + self.marked: dict[str, CatalogueSearchResult] = {} + self._marked_pages: dict[str, int] = {} + self._pending_confirmation_ids: tuple[str, ...] = () + self._selection_notice: str | None = None def compose_content(self) -> Iterable[Widget]: with Grid(id="browse-controls"): @@ -341,6 +404,7 @@ def compose_content(self) -> Iterable[Widget]: 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("Space Mark · a Add current · M Mark page · u Clear · 4 Downloads · ? Help", id="browse-shortcuts", markup=False) def action_focus_search(self) -> None: self.query_one("#browse-query", Input).focus() @@ -357,6 +421,7 @@ def on_screen_resume(self, event: ScreenResume) -> None: self._filters_worker = self._load_filters() if self.results: 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() @@ -370,6 +435,13 @@ def submit_search(self, *, refresh: bool) -> None: 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 = () @@ -380,9 +452,15 @@ def _start_search(self, request: SearchRequest) -> None: 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) - self._set_status(self._loading_status(request)) + 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) @@ -444,12 +522,12 @@ def _run_details(self, result: CatalogueSearchResult) -> DetailsOutcome: 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, selection: CatalogueSearchResult) -> QueuePlanOutcome: + def _plan_queue_add(self, selections: tuple[CatalogueSearchResult, ...], marked: bool) -> QueuePlanOutcome: try: - result = self._queue_plan_provider(self.settings, (selection,)) - return QueuePlanOutcome(selection, result) + result = self._queue_plan_provider(self.settings, selections) + return QueuePlanOutcome(selections, result, marked) except Exception as exc: - return QueuePlanOutcome(selection, error=str(exc) or type(exc).__name__) + 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: @@ -479,23 +557,42 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: def _apply_queue_plan(self, outcome: QueuePlanOutcome) -> None: if self.app.screen is not self: return - if not self.results or self.results[self.selected_index] != outcome.selection: + 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 - if outcome.result.status is not QueueAddStatus.READY or outcome.result.plan is None: + 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 + self._pending_confirmation_ids = tuple( + str(selection.song_id) for selection in outcome.selections if selection.song_id is not None + ) self.app.push_screen( - AddToQueueDialog(outcome.result.plan, self._queue_add_provider), + AddToQueueDialog( + outcome.result.plan, + self._queue_add_provider, + batch=outcome.marked and isinstance(outcome.result.plan, QueueBatchAddPlan), + ), self._queue_dialog_closed, ) - def _queue_dialog_closed(self, result: QueueAddResult | None) -> None: - if result is not None and result.status is QueueAddStatus.ADDED: + def _queue_dialog_closed(self, result: QueuePlanResult | None) -> None: + if result is not None and result.status in {QueueAddStatus.ADDED, QueueBatchAddStatus.ADDED}: + for song_id in self._pending_confirmation_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.") + self._render_results() + self._update_shortcuts() + self._pending_confirmation_ids = () def _apply_search(self, outcome: SearchOutcome) -> None: if outcome.error: @@ -512,7 +609,19 @@ def _apply_search(self, outcome: SearchOutcome) -> None: self.current_page = page self.results = page.results self.selected_index = 0 - self.query_one("#browse-results-title", Static).update(f"Results · {len(self.results)} loaded") + 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.") @@ -521,12 +630,13 @@ def _apply_search(self, outcome: SearchOutcome) -> None: 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(_empty_result_status(outcome.request)) + 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._result_status(outcome.request, page)) + 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: @@ -570,6 +680,12 @@ def on_key(self, event: Key) -> None: 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": @@ -588,15 +704,81 @@ def on_key(self, event: Key) -> None: event.stop() def _add_selected_to_queue(self) -> None: - if not self.results: + 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 - selection = self.results[self.selected_index] - if not selection.downloadable: + if not marked and not selections[0].downloadable: self._set_status("Media unavailable; this song cannot be added to the queue.", error=True) return - self._set_status("Checking destination and download queue…") - self._queue_plan_worker = self._plan_queue_add(selection) + 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: @@ -633,6 +815,7 @@ def _select_index(self, index: int) -> None: 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) @@ -662,17 +845,19 @@ def _render_results(self) -> None: 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 "[ ]" 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: - lines.extend((f"{marker} {title}", f" {era} · {category} · {lyrics} · {available}")) + lines.extend((f"{marker} {title} {marked}", f" {era} · {category} · {lyrics} · {available}")) else: length = result.length or "?" lines.append( - f"{marker} {title[:26]:26} {era[:10]:10} {category[:12]:12} " + f"{marker} {title[:23]:23} {marked} {era[:10]:10} {category[:12]:12} " f"{length[:7]:7} {lyrics:6} {available}" ) self.query_one("#browse-results", Static).update( @@ -723,7 +908,11 @@ def _render_summary(self, result: CatalogueSearchResult) -> None: f"Path {path}", "", "Press Enter for full details and lyric preview.", - "Press a to add this song to the download queue." if result.downloadable else "Media unavailable.", + ( + 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)) @@ -752,6 +941,47 @@ def _set_status(self, message: str, *, error: bool = False) -> None: 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 {count} · M page · u clear · ? help" + if count + else "Space mark · a add current · M page · u clear · ? help" + ) + elif count: + text = ( + f"Space {toggle} · a Add {count} selected song{'s' if count != 1 else ''} · M Toggle page · " + f"u Clear {count} · 4 Downloads · ? Help" + ) + else: + text = "Space Mark · a Add current · M Mark page · u Clear · 4 Downloads · ? Help" + shortcuts.update(Text(text, no_wrap=True, overflow="ellipsis")) + @staticmethod def _loading_status(request: SearchRequest) -> str: if request.query: @@ -761,14 +991,16 @@ def _loading_status(request: SearchRequest) -> str: 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 · n/p pages · " - f"j/k select · PgUp/PgDn scroll · Enter details" - f"{' · a Add to queue' if self.results and self.results[self.selected_index].downloadable else ''}.{filters}" + f"j/k select · PgUp/PgDn scroll · Enter details{marked}" + f"{' · a Add selected' if self.marked else ' · a Add current' if self.results and self.results[self.selected_index].downloadable else ''}.{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) diff --git a/tests/test_download_queue_service.py b/tests/test_download_queue_service.py index 034965a..991ae93 100644 --- a/tests/test_download_queue_service.py +++ b/tests/test_download_queue_service.py @@ -28,6 +28,9 @@ DownloadRetryStatus, DownloadQueueItemStatus, QueueAddStatus, + QueueBatchAddItemStatus, + QueueBatchAddStatus, + add_batch_to_download_queue, add_to_download_queue, execute_selected_download, get_download_queue_snapshot, @@ -39,6 +42,7 @@ clear_download_queue, clear_completed_history, plan_queue_additions, + plan_queue_batch_additions, project_download_queue, ) @@ -80,17 +84,22 @@ def _job(number: int, job_id: str, items: tuple[QueueItem, ...]) -> QueueJob: ) -def _selection(*, downloadable: bool = True) -> CatalogueSearchResult: +def _selection( + *, + downloadable: bool = True, + song_id: int | None = 94902, + title: str = "Lemon Glow", +) -> CatalogueSearchResult: return CatalogueSearchResult( selection_index=1, - song_id=94902, - title="Lemon Glow", + song_id=song_id, + title=title, category="unreleased", era="DRFL", length="3:12", artists=("Juice WRLD",), producers=(), - media_path="Compilation/DRFL/Lemon Glow.mp3" if downloadable else None, + media_path=f"Compilation/DRFL/{title}.mp3" if downloadable else None, lyrics=LyricAvailability.SYNCED, downloadable=downloadable, ) @@ -254,6 +263,87 @@ def test_plan_and_confirm_adds_exactly_one_song_without_running_it(tmp_path, mon 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" diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index 81b1387..d12d702 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -26,6 +26,11 @@ QueueAddPlan, QueueAddResult, QueueAddStatus, + QueueBatchAddItem, + QueueBatchAddItemStatus, + QueueBatchAddPlan, + QueueBatchAddResult, + QueueBatchAddStatus, ) from juice_lyrics.acquisition.models import AcquisitionItem from juice_lyrics.tui import JuiceLyricsApp @@ -135,6 +140,25 @@ def _queue_plan(tmp_path: Path, result: CatalogueSearchResult) -> QueueAddPlan: ),)) +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() @@ -1123,3 +1147,215 @@ async def failure_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") + 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 1 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") + + 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_confirmation_is_cancel_first_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 pilot.pause() + assert app.screen.__class__.__name__ == "AddToQueueDialog" + body = _text(app, "#queue-confirm-body") + assert "Selected 3 · Eligible 2" in body + assert "Skipped: 1 queued" in body + assert "does not start downloading" in body + assert "[Cancel]" in _text(app, "#queue-confirm-cancel") + dialog = app.screen + assert dialog.query_one("#queue-confirm-dialog").region.y >= 0 + assert dialog.query_one("#queue-confirm-dialog").region.bottom <= 24 + await pilot.press("enter") + await pilot.pause() + assert app.screen is browse + assert set(browse.marked) == {"1", "2", "9"} + assert created == [] + + await pilot.press("a") + await browse._queue_plan_worker.wait() + await pilot.pause() + browse.selected_index = 1 + await pilot.press("tab", "enter") + await app.screen._worker.wait() + await pilot.pause() + assert len(created) == 1 + assert [item.song_id for item in created[0].eligible] == ["1", "2"] + assert "Added 2 songs" in _text(app, "#queue-confirm-status") + await pilot.press("y") + assert len(created) == 1 + await pilot.press("enter") + await pilot.pause() + assert browse.marked == {} + + asyncio.run(scenario()) + + +def test_browse_batch_help_shortcuts_and_unavailable_mark_guard(tmp_path): + messages = [] + songs = (_result(1, "Available"), _result(2, "Unavailable", downloadable=False)) + + async def scenario(): + app = _app(tmp_path, search=lambda *args, **kwargs: songs) + app.notify = lambda message, **kwargs: messages.append(str(message)) + 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 + assert "a add current" in _text(app, "#browse-shortcuts").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") + app.action_show_help() + help_text = messages[-1] + assert "Space mark/unmark" in help_text + assert "M toggle downloadable songs" in help_text + assert "marked songs" in help_text + assert "adding does not start downloading" in help_text + assert "4 Downloads" 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()) From f72df19dbb0aa014f1bd4c8f5a07cfef7a5a7f35 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Wed, 2 Sep 2026 12:41:18 +0100 Subject: [PATCH 32/62] Streamline and polish TUI workflow --- docs/DEVELOPMENT.md | 25 ++- docs/PROJECT_STATE.md | 8 +- docs/UI_DESIGN.md | 22 +- docs/USER_FLOWS.md | 20 +- src/juice_lyrics/tui/app.py | 23 +-- src/juice_lyrics/tui/screens/browse.py | 67 +++---- src/juice_lyrics/tui/screens/dashboard.py | 29 ++- src/juice_lyrics/tui/screens/downloads.py | 232 ++++++++++++++-------- src/juice_lyrics/tui/screens/settings.py | 52 +++-- tests/test_tui.py | 31 ++- tests/test_tui_browse.py | 36 ++-- tests/test_tui_downloads.py | 64 +++--- tests/test_tui_settings.py | 15 +- 13 files changed, 382 insertions(+), 242 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index b1858e9..cbc71b0 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -66,8 +66,10 @@ tree; reinstall it deliberately after a checkpoint or use the explicit `.venv` command above. The experimental shell provides functional Dashboard, Browse, Library, -Downloads, and Settings screens. Browse has explicit single- and batch-selection Add to queue actions, -and Downloads can explicitly run one selected queued song. Press `/` to focus catalogue search and Enter to +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 @@ -87,7 +89,8 @@ 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, use arrows or `j`/`k` to select an individual queued song, +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 @@ -95,16 +98,15 @@ songs remain visible. Press `d` to review a cancel-first confirmation for the selected queued song. Confirming runs the existing download, validation, lyric, LRC, state, backup, and rmpc pipeline; no download starts before confirmation. Press `t` on a failed song for a cancel-first Retry confirmation. A verified -finalized file may use processing-only retry; otherwise the existing downloader -resume/redownload path is used. Download all, Remove, Clear, and Cancel remain -unavailable. The CLI is still required for those acquisition-management -workflows. +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. -Press `A` to review and sequentially download all eligible waiting songs. Failed and active entries are skipped and remain available for their explicit -actions. +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 tracks, Home/End select the first or last track, and PageUp/PageDown move through longer lists. Press `/` for a @@ -118,8 +120,9 @@ rmpc changes are made. The existing API cache may be updated by that explicit preview. Actual library sync remains CLI-only via `juice-lyrics sync`. The scanner is currently MP3-focused; native FLAC support remains planned. -In Settings, arrows or `j`/`k` inspect effective configuration values, paths, -and environment details; Home/End and PageUp/PageDown navigate longer content. +In Settings, everyday Music, Lyrics, and Download folders plus 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, the effective central `lyrics_dir` (default `~/Music/lyrics`), path existence, and whether rmpc points at that directory. Press `r` diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 870eb1c..331722d 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -3,8 +3,9 @@ ## Current Status Backend services remain stable. The experimental Textual frontend supports explicit confirmed single- and multi-song Browse Add to queue actions and -Download selected action. The current working-tree checkpoint has 258 passing -tests. +selected or whole-queue downloads. The interface now prioritizes the streamlined +Browse → Add → Downloads → Download queue journey. The current working-tree +checkpoint has 258 passing tests. ## Current Branch v2-redesign @@ -23,6 +24,9 @@ v2-redesign - Explicit cancel-first Browse batch Add flow reports eligible and skipped songs, persists eligible songs atomically, and never starts downloading. - Explicit cancel-first Downloads `d` flow for one eligible queued song, delegated to the existing acquisition runner with responsive Downloading and Processing states. - Explicit cancel-first Downloads `A` flow for sequentially downloading all eligible queued songs; failed and active entries are skipped. +- Simplified primary shortcut bars, optional Browse selection indicators, + plain-language confirmations, Dashboard journey prompts, and Settings folders + before advanced diagnostics; all secondary queue actions remain available in Help. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. - Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 58fab26..b112af3 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -174,6 +174,11 @@ 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 @@ -209,7 +214,8 @@ Death Race For Love Producer: Seezyn -[d] Download +[a] Add to Downloads +[4] Open Downloads [enter] Details @@ -310,6 +316,10 @@ for the marked set, or the current song when nothing is marked. The dialog shows eligible/skipped counts and destination information and states that adding will not start a download. +The persistent Browse shortcut line is deliberately small: `a Add song · 4 +Downloads · ? Help`, or `a Add selected · Space Mark · u Clear · 4 Downloads · +? Help` while marks exist. + Example: @@ -329,10 +339,9 @@ Retry Actions: - -r Retry -d Delete -enter Details +`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. --- @@ -341,7 +350,8 @@ enter Details Purpose: -Manage configuration. +Inspect configuration, with everyday folders and rmpc status before advanced +cache, state, provenance, and diagnostic paths. Example: diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 157a467..7f05516 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -254,24 +254,25 @@ Too technical. --- -v2 user-facing model: +v2 primary user-facing model: -Browse → mark songs with Space → press `a` → review eligible/skipped songs → Add to queue +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. -Space toggles the highlighted song, `M` toggles downloadable songs on the +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` adds the marked set, or the highlighted song when nothing is marked, through a cancel-first confirmation. Adding never starts a download and the application does not bulk-fetch an unbounded catalogue merely to fill the queue. -Download selected is implemented for one queued song. Download all, Remove, -Clear queue, Retry failed, and Cancel active download remain future actions. +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: @@ -510,13 +511,16 @@ Failed Current actions: +`A` Download queue -d Download selected queued song +`d` Download selected queued song -enter Details +`t` Try selected failed song again +`?` Secondary queue management and help -Planned actions: Download all, Remove, Clear, Retry, and Cancel. +Completed history and cleanup are intentionally not part of the primary +journey. Active-download cancellation remains planned. --- diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 45c6073..a1f8e80 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -863,21 +863,20 @@ def action_show_help(self) -> None: section = getattr(self.screen, "section", None) if section == "browse": message = ( - "Navigation: ↑/↓ or j/k move results · PageDown/PageUp scroll the loaded results · " - "n next catalogue page · p previous catalogue page · Home/End first/last loaded result · " - "Enter details · Escape close/cancel\n" - "Selection: Space mark/unmark · M toggle downloadable songs on this page · u clear all marks. " - "Marks may span pages of one search; changing search or filters clears them.\n" - "Queue: a Add marked songs, or the current song when none are marked · 4 Downloads. " - "Marking does not add songs; adding does not start downloading. Downloads handles actual downloads." + "Main: a Add to Downloads · 4 Open Downloads\n" + "Selection actions: Space mark current · M toggle this page · u clear marks. " + "Marks may span pages; changing search or filters clears them.\n" + "Navigation: ↑/↓ or j/k move · n next catalogue page · p previous catalogue page · " + "PageDown/PageUp scroll the loaded results · Home/End first/last loaded result · Enter details. " + "Adding does not start downloading; Downloads handles the actual download." ) elif section == "downloads": message = ( - "Navigation: 1–5 sections · ↑/↓ or j/k select · PageUp/PageDown queue · Home/End first/last · Enter details · Escape return/cancel\n" - "Download actions: d Download selected · A Download all eligible queued songs · t Retry failed\n" - "Queue management: x Remove selected · c Clear queue · H Clear completed history · r Refresh\n" - "General: ? Help · q Quit. Download selected and Download all differ; failed songs require Retry. " - "Completed songs are hidden from the active queue; cleanup never deletes downloaded music or lyrics. Jobs are internal." + "Main: A Download queue · d Download selected\n" + "Queue actions: x Remove selected · c Clear waiting songs · H Clear completed history · r Refresh\n" + "Troubleshooting: t Try failed song again\n" + "Navigation: ↑/↓ or j/k select · PageUp/PageDown scroll · Home/End first/last · Enter details · Escape return/cancel. " + "Complete songs are hidden; cleanup never deletes downloaded music or lyrics." ) elif section == "library": message = ( diff --git a/src/juice_lyrics/tui/screens/browse.py b/src/juice_lyrics/tui/screens/browse.py index 30c857e..7ab3902 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -198,17 +198,7 @@ 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 "\n".join(( - f"Song {item.title}", - f"Artist {planned.artist or 'Unknown'}", - f"Category {planned.category or 'Unknown'}", - f"Era {planned.era or 'Unknown'}", - f"Destination {item.destination}", - "Availability Available", - "", - "This adds the song to your download queue. It will not start downloading yet.", - )) - eligible = self.plan.eligible + 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") @@ -216,21 +206,15 @@ def _body_text(self) -> str: unavailable = self.plan.count(QueueBatchAddItemStatus.UNAVAILABLE) + self.plan.count(QueueBatchAddItemStatus.STALE) local = self.plan.count(QueueBatchAddItemStatus.ALREADY_DOWNLOADED) invalid = self.plan.count(QueueBatchAddItemStatus.INVALID) - destinations = {item.item.destination.parent for item in eligible} - destination = str(next(iter(destinations))) if len(destinations) == 1 else "Multiple configured destinations" - return "\n".join(( - f"Selected {self.plan.selected_count} · Eligible {self.plan.eligible_count}", - f"Skipped: {queued} queued · {unavailable + invalid} unavailable · {local} downloaded", - f"Destination: {destination}", - "", - *preview, - "", - ( - "This adds the song to Downloads. It does not start downloading." - if self.plan.selected_count == 1 - else "This adds songs to Downloads. It does not start downloading." - ), - )) + 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() @@ -404,7 +388,7 @@ def compose_content(self) -> Iterable[Widget]: 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("Space Mark · a Add current · M Mark page · u Clear · 4 Downloads · ? Help", id="browse-shortcuts", markup=False) + yield Static("a Add song · 4 Downloads · ? Help", id="browse-shortcuts", markup=False) def action_focus_search(self) -> None: self.query_one("#browse-query", Input).focus() @@ -534,14 +518,14 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: if event.state is WorkerState.SUCCESS: self._apply_filters(event.worker.result) elif event.state is WorkerState.ERROR: - self._apply_filters(FiltersOutcome(error="Filter metadata worker failed")) + 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 worker failed", + error="Search stopped unexpectedly", )) elif event.worker is self._details_worker: if event.state is WorkerState.SUCCESS: @@ -846,18 +830,21 @@ def _render_results(self) -> None: 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 "[ ]" + 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: - lines.extend((f"{marker} {title} {marked}", f" {era} · {category} · {lyrics} · {available}")) + 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[:23]:23} {marked} {era[:10]:10} {category[:12]:12} " + 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( @@ -969,17 +956,14 @@ def _update_shortcuts(self) -> 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 {count} · M page · u clear · ? help" + f"a add selected · Space {toggle.lower()} · u clear · 4 downloads · ? help" if count - else "Space mark · a add current · M page · u clear · ? help" + else "a add song · 4 downloads · ? help" ) elif count: - text = ( - f"Space {toggle} · a Add {count} selected song{'s' if count != 1 else ''} · M Toggle page · " - f"u Clear {count} · 4 Downloads · ? Help" - ) + text = f"a Add selected · Space {toggle} · u Clear · 4 Downloads · ? Help" else: - text = "Space Mark · a Add current · M Mark page · u Clear · 4 Downloads · ? Help" + text = "a Add song · 4 Downloads · ? Help" shortcuts.update(Text(text, no_wrap=True, overflow="ellipsis")) @staticmethod @@ -993,9 +977,8 @@ def _result_status(self, request: SearchRequest, page: CataloguePage) -> str: 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 · n/p pages · " - f"j/k select · PgUp/PgDn scroll · Enter details{marked}" - f"{' · a Add selected' if self.marked else ' · a Add current' if self.results and self.results[self.selected_index].downloadable else ''}.{filters}" + f"Result {selected} of {len(page.results)} loaded{marked}." + f"{filters}" ) def on_resize(self, event: Resize) -> None: diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py index eebb809..360bc1b 100644 --- a/src/juice_lyrics/tui/screens/dashboard.py +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -94,7 +94,7 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: if event.state is WorkerState.SUCCESS: self._apply_snapshot(event.worker.result) elif event.state is WorkerState.ERROR: - message = str(event.worker.error) if event.worker.error else "Unknown worker error" + message = str(event.worker.error) if event.worker.error else "Unable to load dashboard data" self._apply_snapshot(DashboardSnapshot(None, None, message, message)) def _apply_snapshot(self, snapshot: DashboardSnapshot) -> None: @@ -128,12 +128,25 @@ def _render_queue(self, snapshot: QueueSnapshot | None, failure: str | None) -> error.update(f"Warning: {failure or 'Unknown queue status error'}") return - lines = ( - f"Total jobs {snapshot.total_job_count}", - f"Pending {snapshot.pending_job_count}", - f"Active {snapshot.active_job_count}", - f"Completed {snapshot.completed_job_count}", - f"Failed {snapshot.failed_job_count}", - ) + 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 index 63b9d10..ab9df4c 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -17,7 +17,6 @@ from textual.worker import Worker, WorkerState from ...services.download_queue import ( - DownloadExecutionAction, DownloadExecutionPlan, DownloadExecutionResult, DownloadExecutionStatus, @@ -80,6 +79,69 @@ 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.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.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.""" @@ -90,20 +152,10 @@ def __init__(self, plan: DownloadExecutionPlan) -> None: self._confirmed = False def compose(self) -> ComposeResult: - action = "Resume download" if self.plan.action is DownloadExecutionAction.RESUME else "Start download" with Container(id="download-confirm-dialog"): yield Static("Download selected", id="download-confirm-title") yield Static( - "\n".join(( - f"Song {self.plan.title}", - f"Artist {self.plan.artist or 'Unknown'}", - f"Destination {self.plan.destination}", - f"Status {_status_label(self.plan.current_status)}", - f"Action {action}", - "", - "This will write the media file and may embed lyrics, create an LRC file, " - "update library state, and notify rmpc according to your configuration.", - )), + f"Download {self.plan.title}?\n\nLyrics will be added automatically.", id="download-confirm-body", markup=False, ) @@ -161,33 +213,28 @@ def _activate(self) -> None: self.dismiss(self.plan) -class RetryFailedDialog(ModalScreen[DownloadRetryPlan | None]): +class RetryFailedDialog(_CancelFirstModal, ModalScreen[DownloadRetryPlan | None]): + confirm_label = "Retry" + def __init__(self, plan: DownloadRetryPlan) -> None: - super().__init__(); self.plan = plan; self._confirmed = False + super().__init__() + self.plan = plan + self._setup_cancel_first() + def compose(self) -> ComposeResult: - action = {"process_only": "Retry processing only", "resume_download": "Resume download", "download_again": "Download again"}[self.plan.action.value] with Container(id="download-confirm-dialog"): - yield Static("Retry failed song", id="download-confirm-title") - yield Static("\n".join((f"Song {self.plan.title}", f"Destination {self.plan.destination}", f"Previous {self.plan.previous_failure}", f"Action {action}", "", "This may write media and metadata. Retry is explicit and will not affect other songs.")), id="download-confirm-body", markup=False) + 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 on_mount(self) -> None: - self.query_one("#download-confirm-download", Static).update("Retry") - self.query_one("#download-confirm-cancel", Static).update("[Cancel]") - def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: - if event.action == "cancel": self.dismiss(None) - elif not self._confirmed: self._confirmed = True; self.dismiss(self.plan) - def on_key(self, event: Key) -> None: - if event.key in {"escape", "n"}: self.dismiss(None) - elif event.key == "y": self._confirmed = True; self.dismiss(self.plan) - elif event.key == "enter": - if not self._confirmed: - self.dismiss(None) - else: - return - else: return - event.prevent_default(); event.stop() + + def _confirmation_result(self) -> DownloadRetryPlan: + return self.plan class QueueCleanupDialog(ModalScreen[str | None]): @@ -255,31 +302,29 @@ def _activate(self) -> None: self.dismiss(self.action_name) -class DownloadAllDialog(ModalScreen[DownloadAllPlan | None]): +class DownloadAllDialog(_CancelFirstModal, ModalScreen[DownloadAllPlan | None]): + confirm_label = "Download" + def __init__(self, plan: DownloadAllPlan) -> None: - super().__init__(); self.plan = plan; self.confirmed = False + super().__init__() + self.plan = plan + self._setup_cancel_first() + def compose(self) -> ComposeResult: - titles = "\n".join(f" {item.title}" for item in self.plan.eligible[:8]) - if len(self.plan.eligible) > 8: titles += f"\n … and {len(self.plan.eligible) - 8} more" count = len(self.plan.eligible) - body = f"{count} {'song' if count == 1 else 'songs'} will download sequentially.\n\n{titles}\n\nFailed left for Retry: {self.plan.failed_count}\nActive left alone: {self.plan.active_count}\nCompleted history: {self.plan.completed_count}\n\nThis will write media and metadata." + 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 all", id="download-confirm-title") + 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 all", "confirm", id="download-confirm-download") + yield DownloadDialogAction("Download", "confirm", id="download-confirm-download") yield DownloadDialogAction("Cancel", "cancel", id="download-confirm-cancel") - def on_mount(self) -> None: - self.query_one("#download-confirm-download", Static).update("Download all") - self.query_one("#download-confirm-cancel", Static).update("[Cancel]") - def on_download_dialog_action_activated(self, event: DownloadDialogAction.Activated) -> None: - if event.action == "cancel": self.dismiss(None) - elif not self.confirmed: self.confirmed = True; self.dismiss(self.plan) - def on_key(self, event: Key) -> None: - if event.key in {"escape", "n", "enter"}: self.dismiss(None) - elif event.key == "y" and not self.confirmed: self.confirmed = True; self.dismiss(self.plan) - else: return - event.prevent_default(); event.stop() + + def _confirmation_result(self) -> DownloadAllPlan: + return self.plan class DownloadsScreen(HubScreen): @@ -329,7 +374,7 @@ def __init__( self._completion_message: tuple[str, bool] | None = None def compose_content(self) -> Iterable[Widget]: - yield Static("Queued 0 · Downloading 0 · Processing 0 · Failed 0 · Completed 0", id="downloads-summary", markup=False) + 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"): @@ -340,7 +385,7 @@ def compose_content(self) -> Iterable[Widget]: 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("d selected · A all · t retry · x remove · c clear · H history · r refresh · ? help", id="downloads-position", markup=False) + yield Static("2 Browse songs · ? 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: @@ -398,14 +443,14 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> 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 Download all: {detail}", error=True) + 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("Download all failed safely.", error=True) + 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: @@ -427,7 +472,7 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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 "Unknown worker 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: @@ -440,7 +485,7 @@ def _apply_queue(self, outcome: QueueLoadOutcome) -> None: 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("r retry refresh") + 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 @@ -457,8 +502,8 @@ def _apply_queue(self, outcome: QueueLoadOutcome) -> None: self._update_position() self.call_after_refresh(self._scroll_selected_into_view) else: - status.update("Add songs from Browse with a") - self.query_one("#downloads-position", Static).update("a Browse add to queue · r refresh · ? help") + 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) @@ -473,13 +518,14 @@ def _render_summary(self) -> None: return snapshot = self.snapshot self.query_one("#downloads-summary", Static).update( - f"Queued {snapshot.queued_count} · Downloading {snapshot.downloading_count} · Processing {snapshot.processing_count} · Failed {snapshot.failed_count} · Completed {snapshot.completed_count}" + 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: - self.query_one("#download-queue-title", Static).update(f"Queue · {len(self.items)} active") + 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("No queued or failed songs.") + self.query_one("#download-queue", Static).update("Nothing waiting to download.") return lines = [] for index, item in enumerate(self.items): @@ -505,8 +551,8 @@ def _render_selected_details(self) -> None: 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"Queued {_timestamp(item.queued_at)}", - f"Retry {'Available' if item.retryable else 'Not available'}", + 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}") @@ -519,29 +565,32 @@ def _render_selected_details(self) -> None: def _update_position(self) -> None: if self.items: item = self.selected_item - compact = self.size.width < 100 - if compact: - actions = "d selected · A all · t retry · x remove · r refresh · ? help" - elif item and item.status is DownloadQueueItemStatus.FAILED: - actions = "t Retry failed · x Remove · A Download all · c Clear queue · H Clear history · r Refresh · ? Help" + if item and item.status is DownloadQueueItemStatus.FAILED: + actions = "t Retry · A Download queue · ? More" + elif item and item.status is DownloadQueueItemStatus.QUEUED: + actions = "A Download queue · d Selected · ? More" + elif item and item.status is DownloadQueueItemStatus.DOWNLOADING: + actions = "Downloading · ? More" + elif item and item.status is DownloadQueueItemStatus.PROCESSING: + actions = "Adding lyrics · ? More" else: - actions = "d Download selected · A Download all · x Remove · c Clear queue · H Clear history · r Refresh · ? Help" - self.query_one("#downloads-position", Static).update(f"Track {self.selected_index + 1} of {len(self.items)} · {actions}") + actions = "? More" + 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("Add songs from Browse with a") + self._set_status("Search for songs in Browse · Press 2") elif item.status is DownloadQueueItemStatus.QUEUED: - self._set_status("Ready to download · d selected · A all") + self._set_status("Ready to download · A Download queue") elif item.status is DownloadQueueItemStatus.FAILED: - self._set_status("Download failed · t retry · x remove", error=True) + 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("Processing lyrics and library metadata") + self._set_status("Adding lyrics and updating your library") def on_key(self, event: Key) -> None: if event.key == "escape" and self._details_mode: @@ -597,13 +646,13 @@ 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 - body = f"Song {item.title}\nStatus {_status_label(item.status)}\nDestination {item.destination or 'Unavailable'}\n\nThis removes the song from the queue. Downloaded music and lyrics will not be deleted." + body = "Remove this song from Downloads?\n\nDownloaded music will not be deleted." self.app.push_screen(QueueCleanupDialog("Remove", body), self._cleanup_closed) 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 Download all…") + 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) @@ -640,13 +689,19 @@ 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 - body = f"Queued entries {self.snapshot.queued_count}\nFailed entries {self.snapshot.failed_count}\nActive retained {active}\n\nThis clears waiting and failed queue entries. Downloaded music and lyrics will not be deleted." + 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 - self.app.push_screen(QueueCleanupDialog("Clear history", f"Completed history {self.snapshot.completed_count}\n\nThis removes completed download records only. Downloaded music and lyrics will remain."), self._cleanup_closed) + count = self.snapshot.completed_count + body = f"Clear {count} completed entr{'y' if count == 1 else 'ies'}?\n\nDownloaded music and lyrics will remain." + self.app.push_screen(QueueCleanupDialog("Clear history", body), self._cleanup_closed) def _cleanup_closed(self, action: str | None) -> None: if action is None or self._mutation_worker is not None: return @@ -705,7 +760,7 @@ def _download_selected(self) -> None: self._set_status("Select a queued song first.", error=True) return if item.status is DownloadQueueItemStatus.FAILED: - self._set_status("This failed song requires the future Retry action.", error=True) + 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) @@ -783,7 +838,12 @@ def _apply_progress(self, progress: DownloadProgress) -> None: self._live_progress = progress self._render_items() self._render_selected_details() - self._set_status(progress.message or _execution_status_label(progress.status)) + 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 @@ -836,10 +896,10 @@ def on_resize(self, event: Resize) -> None: def _status_label(status: DownloadQueueItemStatus) -> str: return { - DownloadQueueItemStatus.QUEUED: "Queued", + DownloadQueueItemStatus.QUEUED: "Waiting", DownloadQueueItemStatus.DOWNLOADING: "Downloading", - DownloadQueueItemStatus.PROCESSING: "Processing", - DownloadQueueItemStatus.COMPLETED: "Completed", + DownloadQueueItemStatus.PROCESSING: "Adding lyrics", + DownloadQueueItemStatus.COMPLETED: "Complete", DownloadQueueItemStatus.FAILED: "Failed", DownloadQueueItemStatus.NEEDS_ATTENTION: "Needs attention", }[status] @@ -872,8 +932,8 @@ def _execution_status_label(status: DownloadExecutionStatus) -> str: return { DownloadExecutionStatus.READY: "Ready", DownloadExecutionStatus.DOWNLOADING: "Downloading", - DownloadExecutionStatus.PROCESSING: "Processing", - DownloadExecutionStatus.COMPLETED: "Completed", + DownloadExecutionStatus.PROCESSING: "Adding lyrics", + DownloadExecutionStatus.COMPLETED: "Complete", DownloadExecutionStatus.FAILED: "Failed", DownloadExecutionStatus.NOT_FOUND: "Not found", DownloadExecutionStatus.NOT_ELIGIBLE: "Not eligible", diff --git a/src/juice_lyrics/tui/screens/settings.py b/src/juice_lyrics/tui/screens/settings.py index 63426d5..5d2b0df 100644 --- a/src/juice_lyrics/tui/screens/settings.py +++ b/src/juice_lyrics/tui/screens/settings.py @@ -60,15 +60,15 @@ def compose_content(self) -> Iterable[Widget]: 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-configuration-panel"): - yield Static("Configuration", classes="panel-title") - yield Static("Loading…", id="settings-configuration", markup=False) with Container(classes="settings-panel", id="settings-paths-panel"): - yield Static("Paths", classes="panel-title") + 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("Integrations", classes="panel-title") + 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) @@ -107,7 +107,7 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: if event.state is WorkerState.SUCCESS: outcome = event.worker.result elif event.state is WorkerState.ERROR: - outcome = SettingsOutcome(error="Settings snapshot worker failed") + outcome = SettingsOutcome(error="Settings could not be loaded") else: return if self._can_render(): @@ -241,7 +241,16 @@ def on_resize(self, event: Resize) -> None: def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: - config_rows = [ + 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 "lyrics" in paths: + essential_rows.append(_path_row(paths["lyrics"], section="paths", label="Lyrics folder")) + if "music" in paths: + essential_rows.append(_path_row(paths["music"], section="paths", label="Download location")) + + advanced_rows = [ SettingsRow( "configuration", "Active config", @@ -255,8 +264,14 @@ def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: snapshot.application_version, ), ] - config_rows.extend(_value_row(item) for item in snapshot.values) - path_rows = [_path_row(item) for item in snapshot.paths] + advanced_rows.extend( + _value_row(item) for item in snapshot.values if item.key not in {"music_dir", "lyrics_dir"} + ) + advanced_rows.extend( + _path_row(item, section="configuration") + for item in snapshot.paths + if item.key not in {"music", "lyrics"} + ) integration_rows = [ SettingsRow( "integrations", @@ -265,13 +280,13 @@ def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: snapshot.rmpc.detail, ), SettingsRow( - "integrations", + "configuration", "rmpc executable", str(snapshot.rmpc.executable or "Not detected"), str(snapshot.rmpc.executable or "rmpc was not found in PATH."), ), SettingsRow( - "integrations", + "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'}", @@ -281,7 +296,9 @@ def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: SettingsRow("capabilities", f"Limitation {index}", value, value) for index, value in enumerate(snapshot.limitations, start=1) ] - return tuple((*config_rows, *path_rows, *integration_rows, *capability_rows)) + 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: @@ -305,12 +322,17 @@ def _value_row(item: SettingValue) -> SettingsRow: ) -def _path_row(item: SettingsPath) -> SettingsRow: +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( - "paths", - item.label, + section, + label or item.label, f"{item.path} [{state}]", f"{item.path} · {state}{warning}", ) diff --git a/tests/test_tui.py b/tests/test_tui.py index cee9bfb..d60e530 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -71,11 +71,9 @@ async def scenario(): assert "New / changed 1" in library assert "Backups 3" in library assert "rmpc LRC files 2" in library - assert "Total jobs 5" in queue - assert "Pending 1" in queue - assert "Active 1" in queue - assert "Completed 2" in queue - assert "Failed 1" in queue + assert "1 song ready to download" in queue + assert "Press 4 to Downloads" in queue + assert "jobs" not in queue.lower() asyncio.run(scenario()) @@ -105,10 +103,29 @@ async def scenario(): async with app.run_test() as pilot: await pilot.pause() assert "MP3 tracks 0" in _rendered(app, "#library-data") - assert "Total jobs 0" in _rendered(app, "#queue-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} @@ -130,7 +147,7 @@ async def scenario(): await pilot.pause() assert calls == {"library": 2, "queue": 2} assert "MP3 tracks 2" in _rendered(app, "#library-data") - assert "Total jobs 2" in _rendered(app, "#queue-data") + assert "1 song ready to download" in _rendered(app, "#queue-data") asyncio.run(scenario()) diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index d12d702..ae13801 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -759,7 +759,7 @@ async def scenario(): 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 "n/p pages" in _text(app, "#browse-status") + assert "a add song" in _text(app, "#browse-shortcuts").lower() for _ in range(34): await pilot.press("down") @@ -983,10 +983,9 @@ async def scenario(): await pilot.pause() assert app.screen.__class__.__name__ == "AddToQueueDialog" body = _text(app, "#queue-confirm-body") - assert "Song Rental" in body - assert str(tmp_path / "music" / "Rental.mp3") in body - assert "download queue" in body - assert "will not start downloading" in body + assert "Add this song to Downloads?" in body + assert "Rental" in body + assert "This does not start downloading." in body assert "job" not in body.lower() assert "[Cancel]" in _text(app, "#queue-confirm-cancel") await pilot.press("enter") @@ -1157,11 +1156,13 @@ async def scenario(): 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 song" 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 1 selected" in _text(app, "#browse-shortcuts") + assert "a Add selected" in _text(app, "#browse-shortcuts") await pilot.press("down") assert set(browse.marked) == {"1"} await pilot.press("space") @@ -1174,6 +1175,8 @@ async def scenario(): 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 song" in _text(app, "#browse-shortcuts") asyncio.run(scenario()) @@ -1262,9 +1265,9 @@ async def scenario(): await pilot.pause() assert app.screen.__class__.__name__ == "AddToQueueDialog" body = _text(app, "#queue-confirm-body") - assert "Selected 3 · Eligible 2" in body - assert "Skipped: 1 queued" in body - assert "does not start downloading" in body + assert "Add 2 songs to Downloads?" in body + assert "1 selected song will be skipped." in body + assert "This does not start downloading." in body assert "[Cancel]" in _text(app, "#queue-confirm-cancel") dialog = app.screen assert dialog.query_one("#queue-confirm-dialog").region.y >= 0 @@ -1306,7 +1309,10 @@ async def scenario(): await _submit(app, pilot, "songs") shortcuts = app.query_one("#browse-shortcuts") assert shortcuts.region.height == 1 - assert "a add current" in _text(app, "#browse-shortcuts").lower() + shortcuts_text = _text(app, "#browse-shortcuts") + assert "a add song" in shortcuts_text.lower() + assert "4 downloads" 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") @@ -1314,11 +1320,11 @@ async def scenario(): assert "cannot be marked" in _text(app, "#browse-status") app.action_show_help() help_text = messages[-1] - assert "Space mark/unmark" in help_text - assert "M toggle downloadable songs" in help_text - assert "marked songs" in help_text - assert "adding does not start downloading" in help_text - assert "4 Downloads" in help_text + assert "Space mark current" in help_text + assert "M toggle this page" in help_text + assert "changing search or filters clears them" in help_text + assert "Adding does not start downloading" in help_text + assert "4 Open Downloads" in help_text asyncio.run(scenario()) diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py index 5dfed81..38e2cc6 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -175,8 +175,8 @@ async def empty_scenario(): async with app.run_test() as pilot: screen = await _open_downloads(app, pilot) assert screen.__class__.__name__ == "DownloadsScreen" - assert "No queued or failed songs" in _text(app, "#download-queue") - assert "Queued 0 · Downloading 0 · Processing 0 · Failed 0 · Completed 0" in _text( + 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" ) @@ -196,7 +196,7 @@ async def empty_job_scenario(): async with app.run_test() as pilot: await _open_downloads(app, pilot) assert "No active queue item selected" in _text(app, "#download-details") - assert "Completed 0" in _text(app, "#downloads-summary") + assert "Complete 0" in _text(app, "#downloads-summary") asyncio.run(empty_scenario()) asyncio.run(error_scenario()) @@ -309,13 +309,13 @@ 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 "Queued 1 · Downloading 1 · Processing 0 · Failed 5 · Completed 2" in _text( + 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 "> Queued" in rendered + assert "> Waiting" in rendered assert "queued-id" not in rendered and "failed-id" not in rendered await pilot.press("down", "j") @@ -359,7 +359,7 @@ async def scenario(): assert "-downloads-narrow" in app.screen.classes assert job_scroll.size.height >= 5 assert job_scroll.max_scroll_y > 0 - assert "r refresh" in _text(app, "#downloads-position") + assert app.query_one("#downloads-position").region.height == 1 await pilot.press("end") await pilot.pause() @@ -394,15 +394,23 @@ async def scenario(): async with app.run_test(size=(120, 40)) as pilot: await _open_downloads(app, pilot) bar = _text(app, "#downloads-position") - assert "d Download selected" in bar and "A Download all" in bar and "x Remove" in bar + assert "A Download queue" in bar and "d Selected" 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 failed" in _text(app, "#downloads-position") + assert "t Retry" in _text(app, "#downloads-position") assert "Download failed" in _text(app, "#downloads-status") app.action_show_help() help_text = messages[-1] - assert "A Download all" in help_text and "H Clear completed history" in help_text + assert "A Download queue" in help_text and "H Clear completed history" in help_text assert "cleanup never deletes downloaded music or lyrics" in help_text + await pilot.press("home", "x"); await pilot.pause() + remove_text = _text(app, "#download-confirm-body") + assert "Remove this song from Downloads?" in remove_text + assert "Downloaded music will not be deleted." in remove_text + assert app.focused is not None and app.focused.id == "download-confirm-cancel" + await pilot.press("enter"); await pilot.pause() + assert app.screen.id == "screen-downloads" asyncio.run(scenario()) @@ -428,13 +436,19 @@ async def scenario(): 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 "1 song will download sequentially" in _text(app, "#download-confirm-body") + 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("y"); await pilot.pause(0.2) + 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("enter"); await pilot.pause(0.2) assert calls == [1] assert "1 completed" in _text(app, "#downloads-status") @@ -637,10 +651,8 @@ async def scenario(): await pilot.pause() assert app.screen.__class__.__name__ == "DownloadSelectedDialog" body = _text(app, "#download-confirm-body") - assert "Song Queued Song" in body - assert str(tmp_path / "Queued Song.mp3") in body - assert "write the media file" in body - assert "embed lyrics" in body + assert "Download Queued Song?" in body + assert "Lyrics will be added automatically." in body assert "job" not in body.lower() assert "[Cancel]" in _text(app, "#download-confirm-cancel") await pilot.press("enter") @@ -676,10 +688,16 @@ async def scenario(): await _open_downloads(app, pilot) await pilot.press("t"); await pilot.pause() assert app.screen.__class__.__name__ == "RetryFailedDialog" - assert "Retry failed song" in _text(app, "#download-confirm-title") + assert "Try again" in _text(app, "#download-confirm-title") + assert app.focused is not None and app.focused.id == "download-confirm-cancel" + await pilot.press("2"); await pilot.pause() + assert app.screen.__class__.__name__ == "RetryFailedDialog" await pilot.press("escape"); await pilot.pause() assert calls == [] - await pilot.press("t"); await pilot.pause(); await pilot.press("y"); await pilot.pause(0.2) + await pilot.press("t"); await pilot.pause() + await pilot.press("tab"); await pilot.pause() + assert app.focused is not None and app.focused.id == "download-confirm-download" + await pilot.press("enter"); await pilot.pause(0.2) assert calls == ["retry-job:0"] asyncio.run(scenario()) @@ -736,7 +754,7 @@ async def scenario(): continue_to_processing.set() await asyncio.to_thread(processing.wait, 2) await pilot.pause() - assert "Processing" in _text(app, "#download-queue") + assert "Adding lyrics" in _text(app, "#download-queue") execution_worker = downloads._execution_worker assert execution_worker is not None @@ -747,8 +765,8 @@ async def scenario(): if refresh is not None: await refresh.wait() await pilot.pause() - assert "No queued or failed songs" in _text(app, "#download-queue") - assert "Completed 1" in _text(app, "#downloads-summary") + 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 @@ -814,7 +832,7 @@ async def failure_scenario(): assert "Queued Song" in _text(app, "#download-queue") assert "File validation failed: checksum mismatch" in _text(app, "#downloads-status") await pilot.press("d") - assert "future Retry action" in _text(app, "#downloads-status") + assert "Press t to try again" in _text(app, "#downloads-status") assert len(plan_calls) == 1 assert execution_calls == ["queued:0"] @@ -880,8 +898,8 @@ async def scenario(): if refresh is not None: await refresh.wait() await pilot.pause() - assert "Completed 1" in _text(app, "#downloads-summary") - assert "No queued or failed songs" in _text(app, "#download-queue") + assert "Complete 1" in _text(app, "#downloads-summary") + assert "Nothing waiting to download" in _text(app, "#download-queue") try: asyncio.run(scenario()) diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py index 71d10ca..9d0412f 100644 --- a/tests/test_tui_settings.py +++ b/tests/test_tui_settings.py @@ -114,16 +114,16 @@ async def scenario(): screen = await _open_settings(app, pilot) assert screen.__class__.__name__ == "SettingsScreen" assert "Read-only settings view — configuration changes remain CLI-only" in _text(app, "#settings-warning") + paths = _text(app, "#settings-paths") + assert "Music folder" in paths and "Download location" in paths + assert "Lyrics folder" in paths + assert str(tmp_path / "music") in _text(app, "#settings-detail") configuration = _text(app, "#settings-configuration") assert "config.toml" in configuration - assert str(tmp_path / "config.toml") in _text(app, "#settings-detail") - assert "Music directory" in configuration and "[Config file]" in configuration - assert "External LRC directory" in configuration and "[Config file]" in configuration + assert "Music directory" not in configuration + assert "External LRC directory" not in configuration assert "API base URL" in configuration and "[Default]" in configuration assert "Duration tolerance" in configuration and "[Runtime override]" in configuration - paths = _text(app, "#settings-paths") - assert "Music library" in paths and "[Exists]" in paths - assert "External synchronized LRC files" in paths and "[Missing]" in paths assert "Detected and configured" in _text(app, "#settings-integrations") capabilities = _text(app, "#settings-capabilities") assert "MP3 files only" in capabilities and "FLAC support is planned" in capabilities @@ -131,7 +131,7 @@ async def scenario(): await pilot.press("down", "j") assert screen.selected_index == 2 - assert "Music directory" in _text(app, "#settings-detail") + assert "Download location" in _text(app, "#settings-detail") await pilot.press("end") assert screen.selected_index == len(screen.rows) - 1 await pilot.press("home") @@ -196,6 +196,7 @@ async def missing_scenario(): 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") From 7edc0ec612de11a584d04e349e8f60021631e1bc Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 4 Sep 2026 21:20:09 +0100 Subject: [PATCH 33/62] Add sidecar lyrics architecture and backup retention --- PROJECT_CONTEXT.md | 26 +- README.md | 20 +- docs/ARCHITECTURE.md | 9 +- docs/DECISIONS.md | 16 +- docs/DEVELOPMENT.md | 26 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 8 +- docs/PROJECT_STATE.md | 10 +- docs/UI_DESIGN.md | 10 +- docs/USER_FLOWS.md | 5 +- docs/USER_GUIDE.md | 45 ++-- docs/V2_DESIGN.md | 4 +- src/juice_lyrics/acquisition/integration.py | 14 +- src/juice_lyrics/backup/manager.py | 168 +++++++++++-- src/juice_lyrics/cli.py | 95 ++++---- src/juice_lyrics/config/settings.py | 14 +- src/juice_lyrics/lyrics/engine.py | 39 ++- src/juice_lyrics/lyrics/sidecar.py | 9 + src/juice_lyrics/rmpc/integration.py | 4 +- src/juice_lyrics/services/download_queue.py | 11 +- src/juice_lyrics/services/library_status.py | 26 +- src/juice_lyrics/services/library_sync.py | 52 ++-- .../services/settings_snapshot.py | 58 +++-- src/juice_lyrics/tui/screens/library.py | 8 +- src/juice_lyrics/tui/screens/settings.py | 21 +- tests/test_acquisition.py | 7 +- tests/test_acquisition_integration_safety.py | 10 +- tests/test_backup_retention.py | 226 ++++++++++++++++++ tests/test_core.py | 17 +- tests/test_library_status.py | 46 +++- tests/test_library_sync_service.py | 61 ++++- tests/test_lrc_path_authority.py | 14 +- tests/test_rmpc.py | 35 ++- tests/test_settings_snapshot.py | 15 +- tests/test_sidecar_lrc.py | 93 +++++++ tests/test_sidecar_queue_execution.py | 205 ++++++++++++++++ tests/test_tui_library.py | 6 +- tests/test_tui_settings.py | 11 +- 37 files changed, 1126 insertions(+), 318 deletions(-) create mode 100644 src/juice_lyrics/lyrics/sidecar.py create mode 100644 tests/test_backup_retention.py create mode 100644 tests/test_sidecar_lrc.py create mode 100644 tests/test_sidecar_queue_execution.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 177c98d..eec0289 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -17,11 +17,8 @@ Default local library: `~/Music/Juice WRLD/Unreleased` -Default rmpc lyric directory: - -`~/Music/lyrics` - -These paths are defaults only and must remain configurable and portable. +External synchronized lyrics use same-basename sidecars beside each song. The +music path remains configurable and portable. ## Existing proven behavior @@ -51,17 +48,12 @@ The existing lyrics workflow is proven and should not be unnecessarily redesigne Keep MPD + rmpc as the primary playback setup. -Default lyrics directory: - -`~/Music/lyrics` - -This is the application `lyrics_dir` setting and is intentionally shared across -artists. Embedded lyrics remain in audio files; only synchronized external LRC -files use this directory. - -The resolved setting is the sole write authority. Read-only inspection and -planning do not create the directory; rmpc configuration and historical state -paths cannot redirect new output. During development use the repository entry +Audio and external synchronized lyrics stay together: `song.mp3` maps to +`song.lrc` in the same directory. The finalized audio path is the sole write +authority. The legacy `lyrics_dir` key remains readable but is deprecated and +cannot redirect current output. Read-only inspection and planning create +nothing; rmpc configuration and historical state paths cannot redirect new +output. During development use the repository entry point (`.venv/bin/juice-lyrics`) so a stale separately installed package is not mistaken for the current working tree. @@ -297,7 +289,7 @@ The latest development checkpoint reports: * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details * flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility * Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews -* Settings reports effective configuration, provenance where reliable, application paths, and rmpc integration without creating or changing files +* Settings reports effective configuration, sidecar lyrics behavior, provenance where reliable, application paths, and rmpc integration without creating or changing files * TUI active-download cancel, configuration editing, and sync execution are not implemented * legacy CLI remains the way to run whole acquisition records, retry, delete jobs, and sync * 258 automated tests passing across the suite diff --git a/README.md b/README.md index 28c18c7..20ea4b4 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,10 @@ 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 @@ -142,15 +140,19 @@ This prevents common version mix-ups such as selecting `Starstruck (v1)` for `St ## rmpc -External synchronized LRC files use the configured `lyrics_dir`. Its default is: +Audio and external synchronized lyrics stay together. A synchronized song gets +a same-basename sidecar beside its audio file: ```text -~/Music/lyrics +song.mp3 +song.lrc ``` -This central directory is shared across artists. Read-only commands do not create -it; it is created only when an explicitly requested operation writes an LRC. -rmpc configuration is not used as the application's output-path authority. +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: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b38d2d9..2d61e00 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -68,12 +68,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: @@ -231,7 +236,7 @@ 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`. +Synced lyrics become ID3 SYLT and a same-basename `.lrc` beside the audio. Plain lyrics become ID3 USLT. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 4c1df74..54482ff 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -37,13 +37,15 @@ rmpc does not read embedded ID3 lyrics. rmpc currently relies on external `.lrc` lyric files. -All external synchronized LRC operations use the typed `lyrics_dir` setting. -The resolved setting is the only write authority: rmpc configuration and -historical state or queue records may be inspected but cannot redirect new LRC -output. Read-only operations and plans never create the directory. -Its default is the artist-independent central directory `~/Music/lyrics`, while -embedded lyrics remain inside the audio files. Loading settings never creates -this directory; an explicit LRC-writing workflow may create it. +Audio and external synchronized lyrics stay together. Every LRC destination is +derived from the finalized audio path (`song.mp3` -> `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: diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index cbc71b0..4c615a2 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -120,30 +120,22 @@ rmpc changes are made. The existing API cache may be updated by that explicit preview. Actual library sync remains CLI-only via `juice-lyrics sync`. The scanner is currently MP3-focused; native FLAC support remains planned. -In Settings, everyday Music, Lyrics, and Download folders plus rmpc status are +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, the effective central `lyrics_dir` (default `~/Music/lyrics`), path -existence, and whether rmpc points at that directory. Press `r` +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, no missing XDG paths are created, the scanner remains MP3-only, and native FLAC support remains planned. -External synchronized LRC files are shared across artists in `lyrics_dir`; -embedded synchronized/plain lyrics remain in the MP3. To migrate files created -under the previous default without overwriting existing names: - -```bash -mkdir -p ~/Music/lyrics -find ~/Music/Juice\ WRLD/lyrics -maxdepth 1 -type f -iname '*.lrc' -exec mv -n -t ~/Music/lyrics -- {} + -``` - -`lyrics_dir` is the sole application destination for new LRC output. Its default -is `~/Music/lyrics`. Configuration loading, status, verification, TUI screens, -and planning do not create it; an authorized LRC write creates it immediately -before output. rmpc's configured path and historical state/job metadata are -inspection data only and cannot redirect new application output. +External synchronized LRC files use the finalized audio path: `song.mp3` maps 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. ## Source of truth and Git workflow diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 563fe66..9505db9 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -402,6 +402,12 @@ rmpc only supports external LRC files. It does NOT read embedded lyrics. +Current application architecture keeps each same-basename LRC beside its audio +file. The finalized audio path is authoritative; the legacy centralized +`lyrics_dir` configuration is accepted only for compatibility and does not +direct new output. Existing centralized files require a separate explicit +migration and are never moved automatically by `juice-lyrics`. + Therefore: ## Synced lyrics @@ -410,7 +416,7 @@ Do: 1. Embed SYLT into MP3 2. Generate LRC -3. Put LRC into lyrics directory +3. Put the same-basename LRC beside the audio file 4. rmpc displays lyrics ## Plain lyrics diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 331722d..9b9e523 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -28,11 +28,13 @@ v2-redesign plain-language confirmations, Dashboard journey prompts, and Settings folders before advanced diagnostics; all secondary queue actions remain available in Help. - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. -- Settings configuration provenance, XDG/application paths, path-existence checks, rmpc integration status, and current capability limitations. +- Settings configuration provenance, XDG/application paths, sidecar external-lyrics behavior, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. -- External synchronized LRC files use the authoritative `lyrics_dir` setting, defaulting to the shared `~/Music/lyrics` directory. -- Historical state paths and rmpc configuration cannot redirect new LRC output; - read-only operations do not create either the central or legacy directory. +- External synchronized LRC files live beside each audio file with the same + basename; the finalized audio path is authoritative. +- The legacy `lyrics_dir` setting remains readable but deprecated. Historical + state paths and rmpc configuration cannot redirect new LRC output, and + read-only operations create no sidecars or directories. ## Available through the CLI diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index b112af3..c8e20ca 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -358,13 +358,17 @@ Example: Settings -Music Directory +Music folder ~/Music/Juice WRLD -Lyrics Directory +Download location -~/Music/lyrics +~/Music/Juice WRLD + +External lyrics + +Beside each song (.lrc) Player diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 7f05516..5bdcecf 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -323,12 +323,15 @@ After completion: ✓ Added to library ✓ Lyrics embedded -✓ rmpc lyrics ready +✓ 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. --- diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 552195e..7ef040a 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -8,27 +8,25 @@ Run: juice-lyrics setup ``` -When rmpc is detected, setup generates synchronized LRC files and updates the -rmpc lyrics setting after its normal confirmation. Merely loading configuration -does not create the lyrics directory. +When rmpc is detected, setup generates synchronized LRC sidecars and updates +rmpc to index the configured music tree after its normal confirmation. Merely +loading configuration creates no directories or files. ## Configuration The application configuration is `~/.config/juice-lyrics/config.toml`. Embedded -lyrics remain inside each audio file. External synchronized LRC files use one -central directory shared across artists: +lyrics remain inside each audio file. External synchronized lyrics are written +beside the audio with the same basename: -```toml -lyrics_dir = "~/Music/lyrics" +```text +song.mp3 +song.lrc ``` -The default is `~/Music/lyrics`; an explicit `lyrics_dir` overrides it. Inspect -the effective value with `juice-lyrics config show`. Native FLAC support remains -planned separately. - -This setting is the sole destination for new external LRC files. Read-only -commands do not create the directory, rmpc configuration is not treated as an -output-path override, and historical state records cannot redirect a new write. +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. Native FLAC library scanning remains planned +separately. ## Normal day-to-day use @@ -95,7 +93,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: @@ -149,18 +147,13 @@ Default local library: ~/Music/Juice WRLD/Unreleased ``` -Default external synchronized LRC directory: +External synchronized lyrics: ```text -~/Music/lyrics +song.mp3 +song.lrc ``` -Both should remain configurable. - -Existing LRC files from the previous default are not moved automatically. A -safe no-overwrite manual migration is: - -```bash -mkdir -p ~/Music/lyrics -find ~/Music/Juice\ WRLD/lyrics -maxdepth 1 -type f -iname '*.lrc' -exec mv -n -t ~/Music/lyrics -- {} + -``` +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. diff --git a/docs/V2_DESIGN.md b/docs/V2_DESIGN.md index fa80471..9c72bbb 100644 --- a/docs/V2_DESIGN.md +++ b/docs/V2_DESIGN.md @@ -243,7 +243,7 @@ Should: 3. Download. 4. Validate file. 5. Embed lyrics. -6. Generate LRC if possible. +6. Generate a same-basename LRC beside the audio if possible. 7. Add to library. --- @@ -422,6 +422,8 @@ Rules: - Only generate from timestamped lyrics. - Never invent timestamps. +- Keep each LRC beside its audio file with the same basename. +- Do not derive current output from the deprecated global `lyrics_dir` setting. --- diff --git a/src/juice_lyrics/acquisition/integration.py b/src/juice_lyrics/acquisition/integration.py index 8ff2aca..1d50fd3 100644 --- a/src/juice_lyrics/acquisition/integration.py +++ b/src/juice_lyrics/acquisition/integration.py @@ -11,7 +11,6 @@ restore_file, write_manifest, ) -from ..config.settings import resolve_lyrics_dir 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 @@ -48,13 +47,8 @@ def integrate_downloaded_mp3( """ path = item.destination - # Current settings are authoritative. The optional argument remains for - # compatibility with lower-level callers that do not have a Settings - # object, but it may not override configured output during acquisition. - if settings is not None: - lyrics_dir = resolve_lyrics_dir(settings) - elif lyrics_dir is not None: - lyrics_dir = Path(lyrics_dir).expanduser() + # ``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") @@ -124,9 +118,9 @@ def integrate_downloaded_mp3( "The original downloaded file was restored from backup; the failed item remains retryable." ) from exc - if synced and lyrics_dir is not None: + if synced: try: - lrc_path = write_lrc(path, synced, song, Path(lyrics_dir)) + lrc_path = write_lrc(path, synced, song) except Exception as exc: raise AcquisitionPostProcessingError( AcquisitionFailureStage.LRC, diff --git a/src/juice_lyrics/backup/manager.py b/src/juice_lyrics/backup/manager.py index 81d1317..3d1ce0c 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -1,28 +1,166 @@ from __future__ import annotations -import json, shutil + +import json +import logging +import shutil +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 + +logger = logging.getLogger(__name__) + + +@dataclass(frozen=True, slots=True) +class BackupRecord: + """A completed backup with an authoritative manifest timestamp.""" + + path: Path + created_at: datetime + + +@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() + root = BACKUP_DIR / datetime.now().strftime("%Y%m%d-%H%M%S") + root.mkdir(parents=True, exist_ok=True) + return root + + +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) + shutil.copy2(backup, destination) + + +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 any(root.rglob("*.mp3")): + 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] -def now_iso(): return datetime.now(timezone.utc).isoformat() + 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 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 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 +def write_manifest(root: Path, entries: list[dict[str, Any]]) -> None: + """Finalize a backup, then apply retention without invalidating that backup.""" -def restore_file(backup:Path,destination:Path)->None: - destination.parent.mkdir(parents=True,exist_ok=True); shutil.copy2(backup,destination) + (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 MP3 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 any(root.rglob("*.mp3")) + 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 root.rglob("*.mp3"): + destination = base / source.relative_to(root) + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(source, destination) + restored += 1 return restored diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 9873275..0ef7495 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -21,7 +21,8 @@ from mutagen.mp3 import MP3 from . import __version__ -from .config.settings import DEFAULT_LYRICS_DIR, resolve_lyrics_dir +from .config.settings import DEFAULT_LYRICS_DIR +from .lyrics.sidecar import sidecar_lrc_path APP_NAME = "juice-lyrics" DEFAULT_API_BASE = "https://juicewrldapi.com/juicewrld" @@ -125,7 +126,7 @@ def write_default_config(force: bool = False) -> None: CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True) if CONFIG_FILE.exists() and not force: raise RuntimeError(f"Config already exists: {CONFIG_FILE} (use --force to replace it)") - content = f'''# {APP_NAME} configuration\n\nmusic_dir = "{DEFAULT_MUSIC_DIR}"\nlyrics_dir = "{DEFAULT_LYRICS_DIR}"\napi_base = "{DEFAULT_API_BASE}"\ntimeout = {DEFAULT_TIMEOUT}\ndelay = {DEFAULT_DELAY}\nduration_tolerance = {DEFAULT_DURATION_TOLERANCE}\ncache_ttl_hours = {DEFAULT_CACHE_TTL_HOURS}\n''' + content = f'''# {APP_NAME} configuration\n\nmusic_dir = "{DEFAULT_MUSIC_DIR}"\napi_base = "{DEFAULT_API_BASE}"\ntimeout = {DEFAULT_TIMEOUT}\ndelay = {DEFAULT_DELAY}\nduration_tolerance = {DEFAULT_DURATION_TOLERANCE}\ncache_ttl_hours = {DEFAULT_CACHE_TTL_HOURS}\n''' CONFIG_FILE.write_text(content, encoding="utf-8") @@ -483,30 +484,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}") @@ -552,10 +529,6 @@ def notify_rmpc_index(paths: list[Path]) -> int: return count -def configured_rmpc_lyrics_dir(settings: Settings) -> Path: - return resolve_lyrics_dir(settings) - - 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] = { @@ -582,16 +555,13 @@ def state_is_current(state: dict[str, Any], path: Path, settings: Settings, want if not valid: return False if want_rmpc and entry.get("lyric_type") == "SYLT": - lrc = Path(entry.get("lrc") or "") - expected_lrc = resolve_lyrics_dir(settings) / f"{path.stem}.lrc" - if lrc != expected_lrc or not expected_lrc.is_file(): + 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(settings) if with_rmpc else None work: list[dict[str, Any]] = [] skipped_unchanged = 0 for index, path in enumerate(files, 1): @@ -662,7 +632,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}) @@ -764,8 +734,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: @@ -808,7 +784,7 @@ def command_setup(args: argparse.Namespace, settings: Settings, use_color: bool) print("Cancelled.") return 0 if rmpc_available: - patch_rmpc_config(DEFAULT_RMPC_CONFIG, resolve_lyrics_dir(settings)) + patch_rmpc_config(DEFAULT_RMPC_CONFIG, Path(settings.music_dir)) files = find_mp3s(settings) return embed_batch(settings, files, use_color, args.refresh, False, True, rmpc_available) @@ -822,7 +798,7 @@ def command_sync(args: argparse.Namespace, settings: Settings, use_color: bool) dry_run=args.dry_run, refresh=args.refresh, rmpc_enabled=rmpc_enabled, - lyrics_dir=resolve_lyrics_dir(settings) if rmpc_enabled else None, + lyrics_dir=None, rmpc_config_path=DEFAULT_RMPC_CONFIG if rmpc_enabled else None, state_file=STATE_FILE, ) @@ -859,6 +835,11 @@ def scan_progress(event): 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: @@ -901,7 +882,7 @@ def command_status(settings: Settings, use_color: bool) -> int: ) print_header("Library Status", use_color) print(f"Library: {status.library_path}") - print(f"External LRC dir: {resolve_lyrics_dir(settings)}") + print("External lyrics: Beside each song (.lrc)") print(f"MP3 files: {status.track_count}") print(f"Embedded synced: {status.embedded_synced_count}") print(f"Embedded plain: {status.embedded_plain_count}") @@ -1098,7 +1079,9 @@ def command_config(args: argparse.Namespace, settings: Settings | None = None) - print(CONFIG_FILE.read_text(encoding="utf-8").rstrip()) else: print(f"No config. Defaults are in use.\n{CONFIG_FILE}") - print(f"Effective lyrics_dir: {resolve_lyrics_dir(effective)}") + 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") @@ -1112,12 +1095,13 @@ def command_cache(args: argparse.Namespace) -> int: 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 = resolve_lyrics_dir(settings, explicit_override=args.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"}: @@ -1131,31 +1115,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 = resolve_lyrics_dir(settings, explicit_override=args.lyrics_dir) 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 = resolve_lyrics_dir(settings, explicit_override=args.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") @@ -1428,7 +1414,6 @@ def postprocess(result): 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=settings, ) if integration.message: @@ -1611,14 +1596,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) diff --git a/src/juice_lyrics/config/settings.py b/src/juice_lyrics/config/settings.py index d26184a..968f7f5 100644 --- a/src/juice_lyrics/config/settings.py +++ b/src/juice_lyrics/config/settings.py @@ -12,7 +12,7 @@ DEFAULT_DURATION_TOLERANCE = 3.0 DEFAULT_CACHE_TTL_HOURS = 24 DEFAULT_LYRICS_DIR = Path.home() / "Music" / "lyrics" -# Historical compatibility sentinel only; never use this as an output default. +# Historical compatibility values only; neither controls current LRC output. LEGACY_IMPLICIT_LYRICS_DIR = Path.home() / "Music" / "Juice WRLD" / "lyrics" @@ -40,9 +40,7 @@ class Settings: delay: float = DEFAULT_DELAY duration_tolerance: float = DEFAULT_DURATION_TOLERANCE cache_ttl_hours: float = DEFAULT_CACHE_TTL_HOURS - # Set by configuration loading when lyrics_dir was deliberately supplied. - # It lets the compatibility guard distinguish an intentional legacy path - # from the pre-lyrics_dir implicit default. + # Deprecated compatibility field. New LRC output is always beside audio. lyrics_dir_explicit: bool = False @property @@ -55,12 +53,10 @@ def resolve_lyrics_dir( *, explicit_override: str | Path | None = None, ) -> Path: - """Resolve the sole destination for newly written external LRC files. + """Resolve the deprecated centralized directory for compatibility tools. - The old application default was derived from ``DEFAULT_MUSIC_DIR``. A - stale in-memory settings object using that implicit value must not recreate - the old artist-specific directory. An explicit TOML value (or an explicit - advanced-command override) remains respected, including that exact path. + 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: diff --git a/src/juice_lyrics/lyrics/engine.py b/src/juice_lyrics/lyrics/engine.py index 54ee5cb..fbbd807 100644 --- a/src/juice_lyrics/lyrics/engine.py +++ b/src/juice_lyrics/lyrics/engine.py @@ -1,10 +1,13 @@ from __future__ import annotations +import os import re +import tempfile from pathlib import Path from typing import Any from mutagen.id3 import ID3, ID3NoHeaderError, SYLT, USLT, Encoding from ..library.matching import local_duration, parse_length +from .sidecar import sidecar_lrc_path DESCRIPTION = "Juice WRLD API" LANGUAGE = "eng" @@ -80,13 +83,43 @@ 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 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" + 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 1a5adf9..161b68f 100644 --- a/src/juice_lyrics/rmpc/integration.py +++ b/src/juice_lyrics/rmpc/integration.py @@ -17,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/download_queue.py b/src/juice_lyrics/services/download_queue.py index a0d0fa5..f3ea86c 100644 --- a/src/juice_lyrics/services/download_queue.py +++ b/src/juice_lyrics/services/download_queue.py @@ -20,7 +20,7 @@ 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, resolve_lyrics_dir +from ..config.settings import Settings from .acquisition_queue import ( QueueFailureStage, QueueItem, @@ -922,7 +922,7 @@ def execute_download_all( 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, lyrics_dir=lyrics_dir, progress=(lambda update, pos=position: progress(DownloadBatchProgress(pos, len(plan.eligible), execution_plan.reference, execution_plan.title, update.status)) if progress else None)) + 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: @@ -1053,7 +1053,6 @@ def postprocess(result: AcquisitionResult) -> IntegrationResult: return integration( entry.item, song_fetcher=lambda song_id: song_fetcher(settings, song_id), - lyrics_dir=resolve_lyrics_dir(settings), settings=settings, ) @@ -1155,7 +1154,11 @@ def report(index: int, total: int, written: int, remote_total: int | None) -> No 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), lyrics_dir=resolve_lyrics_dir(settings), settings=settings) + 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 diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 3ef0d2e..e843872 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -7,10 +7,12 @@ from pathlib import Path from typing import Any -from ..config.settings import BACKUP_DIR, STATE_FILE, Settings, resolve_lyrics_dir +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 ..lyrics.engine import verify_file +from ..lyrics.sidecar import sidecar_lrc_path from ..state import sha256_file LyricsVerifier = Callable[[Path], tuple[bool, str]] @@ -218,13 +220,8 @@ def get_library_snapshot( matched_title = str(candidate_title).strip() matched = bool(matched_title or (entry is not None and entry.get("song_id") is not None)) - recorded_lrc = ( - Path(str(entry["lrc"])) - if entry is not None and entry.get("lrc") - else None - ) lrc_path = ( - resolve_lyrics_dir(settings) / f"{path.stem}.lrc" + sidecar_lrc_path(path) if lyric_status is LibraryLyricStatus.SYNCED else None ) @@ -234,11 +231,7 @@ def get_library_snapshot( lrc_status = LibraryLrcStatus.PRESENT else: lrc_status = LibraryLrcStatus.MISSING - track_warnings.append("External LRC file is missing from the configured directory.") - if recorded_lrc is not None and lrc_path is not None and recorded_lrc != lrc_path: - track_warnings.append( - f"Library state records an LRC outside the configured directory: {recorded_lrc}" - ) + track_warnings.append("Adjacent external LRC file is missing.") try: duration = duration_reader(path) @@ -302,16 +295,11 @@ def get_library_status( if ( valid and message.startswith("SYLT") - and (resolve_lyrics_dir(settings) / f"{path.stem}.lrc").is_file() + and sidecar_lrc_path(path).is_file() ): lrc += 1 - backup_path = Path(backup_dir) - backup_count = ( - len([path for path in backup_path.iterdir() if path.is_dir()]) - if backup_path.exists() - else 0 - ) + backup_count = len(list_backups(Path(backup_dir))) return LibraryStatus( library_path=library_path, track_count=len(files), diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index 9b4c169..4aebb35 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -10,10 +10,11 @@ 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, resolve_lyrics_dir +from ..config.settings import DEFAULT_RMPC_CONFIG, STATE_FILE, Settings from ..library.matching import choose_candidate, search_title_for 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, save_state, sha256_file from ..backup.manager import now_iso @@ -62,10 +63,9 @@ class LibrarySyncOptions: state_file: Path = STATE_FILE def __post_init__(self) -> None: - # A plan may contain historical state paths, but all new LRC output is - # derived from current settings at the application boundary. - authoritative = resolve_lyrics_dir(self.settings) if self.rmpc_enabled else None - object.__setattr__(self, "lyrics_dir", authoritative) + # 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( @@ -85,7 +85,7 @@ def from_settings( dry_run=dry_run, refresh=refresh, rmpc_enabled=rmpc_enabled, - lyrics_dir=resolve_lyrics_dir(settings) if rmpc_enabled else None, + 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), @@ -110,6 +110,7 @@ class TrackSyncPlan: synced_lyrics: tuple[tuple[str, int], ...] = () plain_lyrics: str = "" error: str | None = None + lrc_path: Path | None = None @dataclass(frozen=True, slots=True) @@ -197,7 +198,7 @@ class LibrarySyncDependencies: 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], Path] = write_lrc + 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 @@ -238,13 +239,7 @@ def _state_is_current( if not valid: return False if options.rmpc_enabled and entry.get("lyric_type") == SyncLyricType.SYNCED.value: - lrc = Path(str(entry.get("lrc") or "")) - expected_lrc = ( - options.lyrics_dir / f"{path.stem}.lrc" - if options.lyrics_dir is not None - else None - ) - if expected_lrc is None or lrc != expected_lrc or not expected_lrc.is_file(): + if not sidecar_lrc_path(path).is_file(): return False return True @@ -290,7 +285,21 @@ def plan_library_sync( else: tracks.append(TrackSyncPlan(path, MatchOutcome.NO_LYRICS, SyncLyricType.NONE, candidate)) continue - tracks.append(TrackSyncPlan(path, MatchOutcome.MATCHED, lyric_type, candidate, synced, plain)) + 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 + ), + ) + ) _emit(progress, SyncEventKind.MATCH_FOUND, path=path, message=lyric_type.value) except Exception as exc: tracks.append(TrackSyncPlan(path, MatchOutcome.FAILED, SyncLyricType.NONE, error=str(exc))) @@ -365,16 +374,6 @@ def execute_library_sync( plan, tuple(initial_results), 0, plan.analysis_failures, 0, 0, 0, None ) - if ( - options.rmpc_enabled - and options.lyrics_dir is not None - and any(track.lyric_type is SyncLyricType.SYNCED for track in ready) - and options.rmpc_config_path is not None - ): - text = options.rmpc_config_path.read_text(encoding="utf-8") - if str(options.lyrics_dir) not in text: - dependencies.rmpc_configurer(options.rmpc_config_path, options.lyrics_dir) - backup_root = dependencies.backup_root_factory() manifest: list[dict[str, Any]] = [] generated_lrc: list[Path] = [] @@ -398,12 +397,11 @@ def execute_library_sync( raise lrc_path: Path | None = None - if options.rmpc_enabled and track.lyric_type is SyncLyricType.SYNCED and options.lyrics_dir is not 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 {}), - options.lyrics_dir, ) generated_lrc.append(lrc_path) _emit(progress, SyncEventKind.LRC_GENERATED, path=track.path, message=str(lrc_path)) diff --git a/src/juice_lyrics/services/settings_snapshot.py b/src/juice_lyrics/services/settings_snapshot.py index 3dda1aa..93684e9 100644 --- a/src/juice_lyrics/services/settings_snapshot.py +++ b/src/juice_lyrics/services/settings_snapshot.py @@ -19,13 +19,11 @@ DEFAULT_CACHE_TTL_HOURS, DEFAULT_DELAY, DEFAULT_DURATION_TOLERANCE, - DEFAULT_LYRICS_DIR, DEFAULT_MUSIC_DIR, DEFAULT_RMPC_CONFIG, DEFAULT_TIMEOUT, STATE_FILE, Settings, - resolve_lyrics_dir, ) SettingScalar: TypeAlias = str | int | float | Path @@ -87,7 +85,6 @@ class SettingsSnapshot: _SETTING_SPECS = ( ("music_dir", "Music directory", DEFAULT_MUSIC_DIR), - ("lyrics_dir", "External LRC directory", DEFAULT_LYRICS_DIR), ("api_base", "API base URL", DEFAULT_API_BASE), ("timeout", "Request timeout", DEFAULT_TIMEOUT), ("delay", "Request delay", DEFAULT_DELAY), @@ -97,7 +94,7 @@ class SettingsSnapshot: def _normalized_config_value(key: str, value: object) -> SettingScalar: - if key in {"music_dir", "lyrics_dir"}: + if key == "music_dir": return Path(str(value)).expanduser() if key == "api_base": return str(value).rstrip("/") @@ -132,7 +129,7 @@ def _inspect_path(key: str, label: str, path: Path) -> SettingsPath: return SettingsPath(key, label, path, exists, warning) -def _rmpc_configured(text: str, lyrics_dir: Path) -> bool: +def _rmpc_configured(text: str, music_root: Path) -> bool: directory = re.search( r'(?im)^\s*lyrics_dir\s*:\s*some\s*\(\s*"([^"]+)"\s*\)', text, @@ -142,16 +139,22 @@ def _rmpc_configured(text: str, lyrics_dir: Path) -> bool: if directory is not None else None ) - return ( - configured_directory == lyrics_dir.expanduser() - and re.search(r"(?im)^\s*enable_lyrics_index\s*:\s*true\s*,?", text) is not 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, - lyrics_dir: Path, + music_root: Path, executable_finder: ExecutableFinder, ) -> IntegrationSnapshot: try: @@ -162,7 +165,7 @@ def _inspect_rmpc( if config_exists: configured = _rmpc_configured( config_path.read_text(encoding="utf-8"), - lyrics_dir, + music_root, ) except Exception as exc: return IntegrationSnapshot( @@ -178,10 +181,10 @@ def _inspect_rmpc( detail = "rmpc was not found in PATH." elif configured: status = IntegrationStatus.DETECTED_CONFIGURED - detail = "rmpc is detected and its lyrics integration is configured." + detail = "rmpc is detected and indexes the music tree containing sidecar lyrics." else: status = IntegrationStatus.DETECTED_NOT_CONFIGURED - detail = "rmpc is detected, but lyrics integration is 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) @@ -199,7 +202,6 @@ def get_settings_snapshot( """Inspect effective settings and environment without creating or changing files.""" config_path = Path(config_path) - effective_lyrics_dir = resolve_lyrics_dir(settings) config: dict[str, object] = {} try: config_exists = config_path.exists() @@ -214,11 +216,8 @@ def get_settings_snapshot( except Exception as exc: raise RuntimeError(f"Could not read config {config_path}: {exc}") from exc - effective_values = { - key: (effective_lyrics_dir if key == "lyrics_dir" else getattr(settings, key)) - for key, _, _ in _SETTING_SPECS - } - values = tuple( + effective_values = {key: getattr(settings, key) for key, _, _ in _SETTING_SPECS} + values_list = [ SettingValue( key, label, @@ -227,12 +226,31 @@ def get_settings_snapshot( _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), - ("lyrics", "External synchronized LRC files", effective_lyrics_dir), ("cache", "API cache", cache_dir), ("state", "Library state", state_file), ("backups", "Backups", backup_dir), @@ -251,7 +269,7 @@ def get_settings_snapshot( paths=paths, rmpc=_inspect_rmpc( Path(rmpc_config_path), - effective_lyrics_dir, + Path(settings.music_dir), executable_finder, ), application_version=__version__, diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index e904d08..f2aa49f 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -290,11 +290,7 @@ def _apply_preview(self, outcome: PreviewOutcome) -> None: self.preview = outcome.plan plan = outcome.plan lrc = plan.synced_files if plan.options.rmpc_enabled else 0 - lrc_destination = ( - f" · LRC dir {plan.options.lyrics_dir}" - if lrc and plan.options.lyrics_dir is not None - else "" - ) + 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} · " @@ -546,6 +542,8 @@ def _track_preview_text(plan: LibrarySyncPlan | None, path: Path) -> str: 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/settings.py b/src/juice_lyrics/tui/screens/settings.py index 5d2b0df..44c5570 100644 --- a/src/juice_lyrics/tui/screens/settings.py +++ b/src/juice_lyrics/tui/screens/settings.py @@ -245,10 +245,21 @@ def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: essential_rows: list[SettingsRow] = [] if "music" in paths: essential_rows.append(_path_row(paths["music"], section="paths", label="Music folder")) - if "lyrics" in paths: - essential_rows.append(_path_row(paths["lyrics"], section="paths", label="Lyrics 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( @@ -265,12 +276,14 @@ def _rows_for(snapshot: SettingsSnapshot) -> tuple[SettingsRow, ...]: ), ] advanced_rows.extend( - _value_row(item) for item in snapshot.values if item.key not in {"music_dir", "lyrics_dir"} + _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 not in {"music", "lyrics"} + if item.key != "music" ) integration_rows = [ SettingsRow( diff --git a/tests/test_acquisition.py b/tests/test_acquisition.py index b7b645f..d24ae77 100644 --- a/tests/test_acquisition.py +++ b/tests/test_acquisition.py @@ -575,7 +575,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() @@ -1127,7 +1127,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): @@ -1197,7 +1197,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 @@ -1269,4 +1269,3 @@ def failing_postprocess(result): 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 index a015748..960cff8 100644 --- a/tests/test_acquisition_integration_safety.py +++ b/tests/test_acquisition_integration_safety.py @@ -84,7 +84,7 @@ def embed(target, synced, plain): assert (root / "manifest.json").is_file() -def test_acquisition_uses_configured_central_lrc_directory(tmp_path, monkeypatch): +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) @@ -98,9 +98,8 @@ def test_acquisition_uses_configured_central_lrc_directory(tmp_path, monkeypatch monkeypatch.setattr(integration, "embed_lyrics", lambda *args: "SYLT") monkeypatch.setattr(integration, "verify_file", lambda target: (True, "verified")) - def write_lrc(target, synced, song, output): - output.mkdir(parents=True, exist_ok=True) - result = output / f"{target.stem}.lrc" + def write_lrc(target, synced, song): + result = target.with_suffix(".lrc") result.write_text("[00:01.00] line\n", encoding="utf-8") return result @@ -114,8 +113,9 @@ def write_lrc(target, synced, song, output): notify_rmpc=False, ) - assert result.lrc_path == configured_lyrics / "Rental.lrc" + 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() diff --git a/tests/test_backup_retention.py b/tests/test_backup_retention.py new file mode 100644 index 0000000..062cfed --- /dev/null +++ b/tests/test_backup_retention.py @@ -0,0 +1,226 @@ +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) + ] + + +@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" diff --git a/tests/test_core.py b/tests/test_core.py index ed9ad68..53c8dab 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -1,4 +1,5 @@ from pathlib import Path +import argparse import sys import tempfile @@ -64,7 +65,7 @@ def test_command_status_with_settings(tmp_path, capsys, monkeypatch): assert rc == 0 out = capsys.readouterr().out assert "Library Status" in out - assert f"External LRC dir: {tmp_path / 'central-lyrics'}" in out + assert "External lyrics: Beside each song (.lrc)" in out assert "MP3 files: 0" in out # Status with an MP3 file @@ -178,10 +179,10 @@ def test_config_show_preserves_missing_and_existing_cli_behavior(tmp_path, monke assert cli.command_config(args) == 0 shown = capsys.readouterr().out assert content.strip() in shown - assert f"Effective lyrics_dir: {Path.home() / 'Music' / 'lyrics'}" in shown + assert "External lyrics: beside each song (.lrc)" in shown -def test_lyrics_directory_default_config_override_and_unknown_keys(tmp_path, monkeypatch): +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 @@ -203,6 +204,10 @@ def test_lyrics_directory_default_config_override_and_unknown_keys(tmp_path, mon 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") @@ -211,10 +216,10 @@ def test_lyrics_directory_default_config_override_and_unknown_keys(tmp_path, mon config.unlink() cli.write_default_config() - assert f'lyrics_dir = "{DEFAULT_LYRICS_DIR}"' in config.read_text(encoding="utf-8") + assert "lyrics_dir" not in config.read_text(encoding="utf-8") -def test_rmpc_setup_uses_configured_lyrics_directory_without_read_time_creation( +def test_rmpc_setup_indexes_music_tree_without_creating_legacy_lyrics_directory( tmp_path, monkeypatch ): import argparse @@ -244,7 +249,7 @@ def test_rmpc_setup_uses_configured_lyrics_directory_without_read_time_creation( ) assert result == 0 - assert configured == [(rmpc_config, configured_lyrics)] + assert configured == [(rmpc_config, tmp_path / "music")] assert not configured_lyrics.exists() diff --git a/tests/test_library_status.py b/tests/test_library_status.py index 0fbcca8..8f0e1e6 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -52,8 +52,7 @@ def test_library_status_counts_lyrics_changes_lrc_and_backups(tmp_path): for path in (synced, plain, missing, changed): path.write_bytes(path.stem.encode()) - lrc = tmp_path / "lyrics" / "synced.lrc" - lrc.parent.mkdir() + 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( @@ -70,8 +69,14 @@ def test_library_status_counts_lyrics_changes_lrc_and_backups(tmp_path): encoding="utf-8", ) backup_dir = tmp_path / "backups" - (backup_dir / "one").mkdir(parents=True) - (backup_dir / "two").mkdir() + 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 = { @@ -81,7 +86,7 @@ def test_library_status_counts_lyrics_changes_lrc_and_backups(tmp_path): changed: (True, "USLT (ordinary lyrics)"), } status = get_library_status( - Settings(music_dir=library, lyrics_dir=lrc.parent), + Settings(music_dir=library, lyrics_dir=tmp_path / "ignored-central"), state_file=state_file, backup_dir=backup_dir, verifier=results.__getitem__, @@ -143,8 +148,7 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa missing = library / "C Missing.mp3" for path in (synced, plain, missing): path.write_bytes(path.name.encode()) - lrc = tmp_path / "lyrics" / "A Synced.lrc" - lrc.parent.mkdir() + 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({ @@ -175,7 +179,7 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa ) snapshot = get_library_snapshot( - Settings(music_dir=library, lyrics_dir=lrc.parent), + 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], @@ -201,7 +205,7 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa assert snapshot.tracks[2].lyric_status is LibraryLyricStatus.NONE -def test_library_snapshot_uses_configured_lrc_directory_not_legacy_state_path(tmp_path): +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" @@ -228,13 +232,33 @@ def test_library_snapshot_uses_configured_lrc_directory_not_legacy_state_path(tm ) item = snapshot.tracks[0] - assert item.lrc_path == configured / "Rental.lrc" + assert item.lrc_path == track.with_suffix(".lrc") assert item.lrc_status is LibraryLrcStatus.MISSING - assert str(legacy) in (item.warning or "") + 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_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") diff --git a/tests/test_library_sync_service.py b/tests/test_library_sync_service.py index 9f1d87e..8b8e115 100644 --- a/tests/test_library_sync_service.py +++ b/tests/test_library_sync_service.py @@ -108,6 +108,28 @@ def test_completely_unchanged_library_is_not_backed_up_or_modified(tmp_path): 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" @@ -210,7 +232,8 @@ def test_frontend_preview_helper_is_dry_run_and_non_mutating(tmp_path): assert plan.options.dry_run is True assert plan.ready_files == 1 assert plan.synced_files == 1 - assert plan.options.lyrics_dir == configured_lyrics + 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() @@ -244,10 +267,9 @@ def test_synced_generates_lrc_but_plain_never_does(tmp_path): deps.verifier = lambda target: (True, "verified") lrc_calls = [] - def write_lrc(path, synced_lines, candidate, output): + def write_lrc(path, synced_lines, candidate): lrc_calls.append(path) - result = output / f"{path.stem}.lrc" - result.parent.mkdir(parents=True, exist_ok=True) + result = path.with_suffix(".lrc") result.write_text("lrc") return result @@ -261,8 +283,8 @@ def write_lrc(path, synced_lines, candidate, output): result = execute_library_sync(plan_library_sync(options, dependencies=deps), dependencies=deps) assert lrc_calls == [synced] - assert (configured_lyrics / "Synced.lrc").is_file() - assert not (tmp_path / "lyrics").exists() + assert synced.with_suffix(".lrc").is_file() + assert not configured_lyrics.exists() assert result.lrc_files_generated == 1 assert result.rmpc_notifications == 1 @@ -331,3 +353,30 @@ def test_cli_sync_delegates_and_preserves_empty_output(tmp_path, monkeypatch, ca 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 index 39d18d7..15c05ab 100644 --- a/tests/test_lrc_path_authority.py +++ b/tests/test_lrc_path_authority.py @@ -32,7 +32,7 @@ def test_legacy_implicit_default_is_guarded_but_explicit_value_is_respected( assert resolve_lyrics_dir(configured) == LEGACY_IMPLICIT_LYRICS_DIR -def test_acquisition_ignores_stale_lrc_override_when_settings_are_available( +def test_acquisition_ignores_legacy_lrc_override_and_writes_sidecar( tmp_path, monkeypatch ): import juice_lyrics.acquisition.integration as integration @@ -59,10 +59,9 @@ def test_acquisition_ignores_stale_lrc_override_when_settings_are_available( monkeypatch.setattr(integration, "verify_file", lambda path: (True, "verified")) monkeypatch.setattr(integration, "sha256_file", lambda path: "hash") - def writer(path, synced, song, output): - outputs.append(output) - output.mkdir(parents=True, exist_ok=True) - result = output / "Rental.lrc" + 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 @@ -82,8 +81,9 @@ def writer(path, synced, song, output): notify_rmpc=False, ) - assert outputs == [central] - assert result.lrc_path == central / "Rental.lrc" + assert outputs == [destination] + assert result.lrc_path == destination.with_suffix(".lrc") + assert not central.exists() assert not legacy.exists() diff --git a/tests/test_rmpc.py b/tests/test_rmpc.py index 9b2aa86..fc2ba7b 100644 --- a/tests/test_rmpc.py +++ b/tests/test_rmpc.py @@ -26,20 +26,25 @@ def test_lrc_writer(tmp_path): assert parse_synced_lyrics("[0:01.23] hello\n[0:04.56] world") == [("hello", 1230), ("world", 4560)] -def test_rmpc_verify_reads_the_configured_central_directory(tmp_path, capsys): - configured = tmp_path / "Music" / "lyrics" - configured.mkdir(parents=True) - (configured / "Rental.lrc").write_text( +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=tmp_path / "music", lyrics_dir=configured), + Settings(music_dir=music, lyrics_dir=configured), False, ) @@ -48,3 +53,23 @@ def test_rmpc_verify_reads_the_configured_central_directory(tmp_path, capsys): 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 index 518ebab..9475772 100644 --- a/tests/test_settings_snapshot.py +++ b/tests/test_settings_snapshot.py @@ -86,7 +86,7 @@ def test_explicit_config_and_runtime_overrides_have_reliable_provenance(tmp_path ) 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 / "lyrics"), encoding="utf-8") + rmpc_config.write_text(config_text.format(lyrics=tmp_path), encoding="utf-8") snapshot = _snapshot( tmp_path, rmpc_config_path=rmpc_config, @@ -123,9 +123,13 @@ def test_paths_and_limitations_are_typed_and_read_only(tmp_path): assert not (tmp_path / "data").exists() -def test_effective_lyrics_directory_is_a_typed_value_and_read_only_path(tmp_path): +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) + 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", @@ -140,8 +144,9 @@ def test_effective_lyrics_directory_is_a_typed_value_and_read_only_path(tmp_path 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 values["lyrics_dir"].source is SettingsSource.RUNTIME_OVERRIDE - assert paths["lyrics"].path == 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() 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_tui_library.py b/tests/test_tui_library.py index b117a24..443efca 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -41,7 +41,7 @@ def _track( warning: str | None = None, ) -> LibraryTrack: path = root / name - lrc_path = root.parent / "lyrics" / f"{path.stem}.lrc" if lrc is not LibraryLrcStatus.NONE else None + lrc_path = path.with_suffix(".lrc") if lrc is not LibraryLrcStatus.NONE else None return LibraryTrack( reference=name, path=path, @@ -68,7 +68,7 @@ def _plan(settings: Settings, tracks: tuple[TrackSyncPlan, ...]) -> LibrarySyncP settings, dry_run=True, rmpc_enabled=True, - lyrics_dir=Path(settings.music_dir).parent / "lyrics", + lyrics_dir=None, state_file=Path(settings.music_dir).parent / "state.json", ) return LibrarySyncPlan(options, tracks, {"files": {}}) @@ -380,7 +380,7 @@ async def scenario(): 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 f"LRC dir {screen.preview.options.lyrics_dir}" 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") diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py index 9d0412f..59256af 100644 --- a/tests/test_tui_settings.py +++ b/tests/test_tui_settings.py @@ -34,7 +34,8 @@ def _snapshot( music = tmp_path / f"music{suffix}" values = ( SettingValue("music_dir", "Music directory", music, Path("/default/music"), SettingsSource.CONFIG), - SettingValue("lyrics_dir", "External LRC directory", tmp_path / "lyrics", Path("/default/lyrics"), 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), @@ -43,7 +44,6 @@ def _snapshot( ) paths = ( SettingsPath("music", "Music library", music, True), - SettingsPath("lyrics", "External synchronized LRC files", tmp_path / "lyrics", False), 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), @@ -116,12 +116,13 @@ async def scenario(): assert "Read-only settings view — configuration changes remain CLI-only" in _text(app, "#settings-warning") paths = _text(app, "#settings-paths") assert "Music folder" in paths and "Download location" in paths - assert "Lyrics folder" 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 "External LRC 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") @@ -131,7 +132,7 @@ async def scenario(): await pilot.press("down", "j") assert screen.selected_index == 2 - assert "Download location" in _text(app, "#settings-detail") + assert "External lyrics" in _text(app, "#settings-detail") await pilot.press("end") assert screen.selected_index == len(screen.rows) - 1 await pilot.press("home") From 8b2315a32c06a1ade25ee600e4fa91a6a821d006 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 5 Sep 2026 12:27:15 +0100 Subject: [PATCH 34/62] Add native FLAC library support --- PROJECT_CONTEXT.md | 35 +- README.md | 26 +- docs/ARCHITECTURE.md | 21 +- docs/CHANGELOG.md | 31 ++ docs/DECISIONS.md | 20 +- docs/DEVELOPMENT.md | 19 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 48 ++- docs/PROJECT_STATE.md | 22 +- docs/ROADMAP_V2.md | 8 +- docs/USER_GUIDE.md | 16 +- pyproject.toml | 4 +- src/juice_lyrics/backup/manager.py | 17 +- src/juice_lyrics/cli.py | 38 +- src/juice_lyrics/library/matching.py | 8 +- src/juice_lyrics/library/media.py | 113 ++++++ src/juice_lyrics/library/scanner.py | 19 +- src/juice_lyrics/lyrics/engine.py | 69 +++- src/juice_lyrics/services/library_status.py | 69 +++- src/juice_lyrics/services/library_sync.py | 32 +- .../services/settings_snapshot.py | 4 +- src/juice_lyrics/tui/screens/dashboard.py | 2 +- src/juice_lyrics/tui/screens/library.py | 19 +- tests/test_backup_retention.py | 38 ++ tests/test_core.py | 4 +- tests/test_flac_support.py | 314 ++++++++++++++++ tests/test_library_status.py | 8 +- tests/test_m4a_support.py | 338 ++++++++++++++++++ tests/test_settings_snapshot.py | 4 +- tests/test_tui.py | 16 +- tests/test_tui_library.py | 4 +- tests/test_tui_settings.py | 6 +- 31 files changed, 1229 insertions(+), 143 deletions(-) create mode 100644 src/juice_lyrics/library/media.py create mode 100644 tests/test_flac_support.py create mode 100644 tests/test_m4a_support.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index eec0289..50b9c82 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -17,7 +17,7 @@ Default local library: `~/Music/Juice WRLD/Unreleased` -External synchronized lyrics use same-basename sidecars beside each song. The +External synchronized lyrics use same-basename sidecars beside each MP3, FLAC, or M4A song. The music path remains configurable and portable. ## Existing proven behavior @@ -38,9 +38,13 @@ The existing lyrics workflow is proven and should not be unnecessarily redesigne ## Lyrics behavior * Prefer API `synced_lyrics`. -* Synced lyrics are embedded as ID3 SYLT. +* Synced lyrics are embedded as ID3 SYLT in MP3 files. * Synced lyrics also produce `.lrc` files for rmpc. -* If only API `lyrics` exists, embed them as ID3 USLT. +* If only API `lyrics` exists, embed them as ID3 USLT in MP3 files. +* FLAC files store standard plain-text Vorbis `LYRICS`; synchronized timing + remains in the adjacent `.lrc` because FLAC has no interoperable SYLT equivalent. +* M4A files store standard plain-text MP4 `©lyr`; synchronized timing remains + in the adjacent `.lrc` rather than a proprietary tag. * Never invent timestamps or fake-sync plain lyrics. * Plain lyrics without timestamps do not generate timed `.lrc` files. @@ -48,8 +52,8 @@ The existing lyrics workflow is proven and should not be unnecessarily redesigne Keep MPD + rmpc as the primary playback setup. -Audio and external synchronized lyrics stay together: `song.mp3` maps to -`song.lrc` in the same directory. The finalized audio path is the sole write +Audio and external synchronized lyrics stay together: `song.mp3`, `song.flac`, or `song.m4a` +maps to `song.lrc` in the same directory. The finalized audio path is the sole write authority. The legacy `lyrics_dir` key remains readable but is deprecated and cannot redirect current output. Read-only inspection and planning create nothing; rmpc configuration and historical state paths cannot redirect new @@ -235,6 +239,7 @@ and failed items remain visible for future retry or removal. ## Acquisition → lyrics integration After successful MP3 acquisition, an optional post-processing hook uses the existing lyrics engine. +Acquisition remains MP3-focused; native FLAC and M4A support applies to existing local-library files. The existing behavior remains: @@ -256,7 +261,7 @@ A post-processing failure must be persisted as an item failure rather than repor ## File safety -Before modifying an MP3: +Before modifying an MP3, FLAC, or M4A file: * create a timestamped backup * write metadata safely @@ -281,6 +286,10 @@ The latest development checkpoint reports: * 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 +* native recursive FLAC discovery, metadata matching, Vorbis lyric embedding, + verification, backup/restore, state, adjacent LRC, and rmpc notification verified +* native recursive M4A discovery, MP4 metadata matching, standard `©lyr` + embedding, verification, backup/restore, state, adjacent LRC, and rmpc notification verified * Settings / Path CLI compatibility verified * responsive terminal-native Textual shell with `ansi_color=True` * all five main TUI sections are functional; Browse can explicitly add one or several stable-ID selections to the queue @@ -290,18 +299,18 @@ The latest development checkpoint reports: * flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility * Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews * Settings reports effective configuration, sidecar lyrics behavior, provenance where reliable, application paths, and rmpc integration without creating or changing files -* TUI active-download cancel, configuration editing, and sync execution are not implemented +* TUI Download selected, Download queue, Retry, Remove, Clear queue, and Clear + completed history are implemented; active-download cancel, configuration editing, + and library sync execution are not implemented * legacy CLI remains the way to run whole acquisition records, retry, delete jobs, and sync -* 258 automated tests passing across the suite +* 310 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The planned product and executable name remains `999`, -but no rename or migration has been performed. Native FLAC support remains -planned. +but no rename or migration has been performed. -Recommended next milestones are: Downloads Download all, -Remove / Clear / Retry actions, Library sync actions, the `999` -naming migration, native FLAC support, then beta polish and release testing. +Recommended next milestones are beta polish and release testing, followed by +the separately planned `999` naming migration when explicitly approved. To resume: diff --git a/README.md b/README.md index 20ea4b4..7adff1d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # juice-lyrics 1.4.0 -A small, cautious Linux CLI for managing lyrics metadata in local MP3 libraries and generating synced `.lrc` files for rmpc. +A small, cautious Linux CLI for managing lyrics metadata in local MP3, FLAC, and M4A libraries and generating synced `.lrc` files 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. @@ -51,14 +51,16 @@ juice-lyrics 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. @@ -99,8 +101,8 @@ Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/AR | `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 | +| `verify` | Validate supported MP3/FLAC/M4A embedded lyrics | +| `restore` | Restore a previous audio backup | | `doctor` | Diagnose Python, Mutagen, API, and paths | | `guide` | Show this workflow in the terminal | | `search` | Search the public song catalogue | @@ -112,7 +114,7 @@ Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/AR ## 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/ @@ -120,9 +122,13 @@ 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. -Only lyric frames created by this tool (`desc = "Juice WRLD API"`) are replaced. Other unrelated lyric frames are preserved. +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. ## Matching diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2d61e00..f77aa48 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -42,7 +42,7 @@ The API layer should not know about terminal prompts, MP3 tagging, or rmpc UI. Responsibilities: -* scan local MP3s +* scan local MP3, FLAC, and M4A files recursively * extract metadata * duration handling * fingerprints/state @@ -57,8 +57,10 @@ Matching must remain version-aware, alias-aware, and duration-aware. 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 @@ -226,7 +228,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 @@ -236,10 +238,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 a same-basename `.lrc` beside the audio. +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/CHANGELOG.md b/docs/CHANGELOG.md index 9256537..5f009d6 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,36 @@ # Changelog +## Unreleased — Native M4A library support + +* Added recursive, case-insensitive `.m4a` library discovery without broadening + support to other MP4-family extensions. +* Added native M4A title, artist, album, and duration reading through Mutagen. +* Reused the normal version/title/path/duration matcher and conservatively leaves + M4A files without title or artist metadata unmatched. +* Added standard plain-text MP4 `©lyr` embedding while preserving unrelated atoms, + the media payload, and the original audio format. +* Kept synchronized M4A timing in the authoritative adjacent `.lrc`; no + proprietary timing atom or conversion is used. +* Extended verification/status, state, backup/restore, retention recognition, + and rmpc sidecar notification to local M4A files. +* Verified 310 automated tests with isolated temporary HOME/XDG paths. + +## Unreleased — Native FLAC library support + +* Added recursive, case-insensitive MP3 and FLAC library discovery. +* Added native FLAC title, artist, album, and duration reading through Mutagen. +* Reused version/title/path/duration matching for FLAC and conservatively leaves + FLAC files without title or artist metadata unmatched. +* Added standard plain-text Vorbis `LYRICS` embedding while preserving unrelated + FLAC metadata and the audio stream; no audio conversion occurs. +* Kept synchronized FLAC timing in the authoritative adjacent `.lrc` because + FLAC/Vorbis comments have no interoperable ID3 SYLT equivalent. +* Extended library sync, verification/status, state, backup/restore, and rmpc + sidecar notification to local FLAC files. +* Generalized rolling backup recognition and restore for FLAC without changing + the newest-10 retention policy or invalidating historical MP3 manifests. +* Verified 298 automated tests with isolated temporary HOME/XDG paths. + ## Unreleased — 2026-08-25 ### Live API path resolution and backend polish diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 54482ff..a887d17 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -8,9 +8,9 @@ The purpose is to prevent future redesigns from accidentally removing important # Lyrics Architecture -## Embedded lyrics are the primary source of truth +## Embedded lyrics remain supported -The application should always preserve lyrics inside the MP3 file when possible. +The application should preserve lyrics inside MP3, FLAC, and M4A files when possible. Reasons: @@ -29,6 +29,20 @@ Supported embedded formats: - 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 @@ -38,7 +52,7 @@ 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.lrc`) rather than a +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. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 4c615a2..2516a4a 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -108,7 +108,7 @@ 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 tracks, Home/End select the first +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 @@ -118,7 +118,9 @@ 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 `juice-lyrics sync`. The -scanner is currently MP3-focused; native FLAC support remains planned. +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. @@ -127,16 +129,21 @@ 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, no missing XDG paths are created, the scanner remains MP3-only, -and native FLAC support remains planned. +remain CLI-only, and no missing XDG paths are created. -External synchronized LRC files use the finalized audio path: `song.mp3` maps to -`song.lrc` in the same directory. Content is generated before an atomic replace, +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 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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 9505db9..7e41600 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -52,7 +52,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -250 passing tests. +310 passing tests. Completed and integrated: @@ -65,6 +65,8 @@ Verified systems: - lyric parsing - ID3 SYLT embedding - ID3 USLT embedding +- native FLAC discovery, metadata matching, Vorbis lyric embedding, and verification +- native M4A discovery, MP4 metadata matching, standard `©lyr` embedding, and verification - LRC generation - rmpc integration - backups @@ -86,13 +88,15 @@ eligible queued song, a read-only Library screen with local track browsing, filters, details, and explicit sync previews, and a read-only Settings screen with effective configuration, paths, provenance, and rmpc state. -All five primary TUI sections are functional. Browse may add one explicitly -confirmed song to the queue; Downloads can execute one confirmed selected song. -Download all, retry, remove, clear, and cancel actions, configuration editing, -and sync execution are not implemented. +All five primary TUI sections are functional. Browse supports confirmed single +and batch queue additions. Downloads supports confirmed Download selected, +sequential Download queue, Retry, Remove, Clear queue, and Clear completed history. +Active-download cancellation, configuration editing, and library sync execution +are not implemented. Durable jobs remain an internal backend detail and completed entries are hidden from the active track queue. The legacy CLI remains the way to run downloads, -delete jobs, and sync. Native FLAC support remains planned. The planned +delete jobs, and sync. Existing local FLAC and M4A files are now first-class library +tracks; acquisition remains MP3-focused. The planned product/executable name remains `999`; package, distribution, and data paths have not been renamed. @@ -154,8 +158,9 @@ docs/ └── this file -The project is in incremental v2 implementation. The backend remains stable and -the TUI is intentionally read-only. +The project is in incremental v2 implementation. The backend remains stable. +Mutating TUI actions are explicit and cancel-first; Library and Settings remain +read-only views, with library sync execution available through the CLI. --- @@ -307,8 +312,8 @@ Available The current Browse implementation supports result selection, details, lyrics -previews, canonical filters, and pagination. Download actions are not yet -implemented. +previews, canonical filters, pagination, and confirmed single or marked Add to +queue actions. Adding never starts a download. --- @@ -356,11 +361,12 @@ Downloading 65% Lemon Glow Complete -The current Downloads implementation is a read-only flat track queue. It shows -queue totals, individual songs, structured failures, and retry eligibility; -internal jobs are hidden except for optional troubleshooting references. Browse -can add one explicitly confirmed song without starting it. Download execution, -retry, cancel, remove, clear, and other queue mutations are not yet implemented. +The Downloads implementation is a flat track queue. It shows queue totals, +individual songs, structured failures, and retry eligibility; internal jobs are +hidden except for optional troubleshooting references. Browse can add confirmed +single or marked songs without starting downloads. Downloads can run the selected +song or eligible queue sequentially, retry failures, and perform record-only +cleanup. Active-download cancellation remains unavailable. --- @@ -402,7 +408,7 @@ rmpc only supports external LRC files. It does NOT read embedded lyrics. -Current application architecture keeps each same-basename LRC beside its audio +Current application architecture keeps each same-basename LRC beside its MP3, FLAC, or M4A audio file. The finalized audio path is authoritative; the legacy centralized `lyrics_dir` configuration is accepted only for compatibility and does not direct new output. Existing centralized files require a separate explicit @@ -414,7 +420,7 @@ Therefore: Do: -1. Embed SYLT into MP3 +1. Embed SYLT into MP3, standard Vorbis `LYRICS` into FLAC, or standard MP4 `©lyr` into M4A 2. Generate LRC 3. Put the same-basename LRC beside the audio file 4. rmpc displays lyrics @@ -423,7 +429,7 @@ Do: Do: -1. Embed USLT into MP3 +1. Embed USLT into MP3, standard Vorbis `LYRICS` into FLAC, or standard MP4 `©lyr` into M4A Do NOT: @@ -434,7 +440,11 @@ Result: Android players can read embedded lyrics. -rmpc cannot display them. +rmpc cannot display them as timed lyrics. + +FLAC and M4A have no interoperable embedded equivalent to ID3 SYLT. The +application does not invent one: synchronized timing remains authoritative in +the adjacent `.lrc`, and audio is never converted. This is accepted as a player limitation. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 9b9e523..cc4e0d3 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -5,7 +5,7 @@ Backend services remain stable. The experimental Textual frontend supports explicit confirmed single- and multi-song Browse Add to queue actions and selected or whole-queue downloads. The interface now prioritizes the streamlined Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 258 passing tests. +checkpoint has 310 passing tests. ## Current Branch v2-redesign @@ -30,6 +30,15 @@ v2-redesign - Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. - Settings configuration provenance, XDG/application paths, sidecar external-lyrics behavior, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. +- Local FLAC files are recursively discovered and matched using native title, + artist, album, and duration metadata. FLAC lyric writes use standard Vorbis + `LYRICS`, preserve unrelated metadata, and are backed up before mutation. +- FLAC synchronized timing uses the adjacent `.lrc`; there is no proprietary + embedded timing format and no audio conversion. +- Local M4A files are recursively discovered and matched using native MP4 title, + artist, album, and duration metadata. Plain lyrics use standard `©lyr` metadata. +- M4A synchronized timing uses the adjacent `.lrc`; unrelated atoms and the + audio stream are preserved and no conversion occurs. - External synchronized LRC files live beside each audio file with the same basename; the finalized audio path is authoritative. - The legacy `lyrics_dir` setting remains readable but deprecated. Historical @@ -47,7 +56,8 @@ retry failures, delete durable acquisition records, and sync the library. - Active-download Cancel remains unimplemented; `x` removes a waiting/failed song, `c` clears waiting/failed records, and `H` clears completed history without deleting downloaded files. -- Native FLAC support remains planned; lyric post-processing is currently MP3-only. +- Acquisition post-processing remains MP3-only; native FLAC and M4A support + targets existing local-library files. - The planned executable/product name remains `999`; package, distribution, and data paths remain named `juice-lyrics`. @@ -60,12 +70,10 @@ retry failures, delete durable acquisition records, and sync the library. ## Recommended next milestones -1. Downloads Download all execution -2. Downloads Download all, Cancel, and multi-select actions -3. Library sync actions +1. Beta polish, packaging, and release testing +2. Active-download cancellation, if still desired +3. Library sync execution controls in the TUI, if explicitly approved 4. `999` command and naming migration -5. Native FLAC support -6. Beta polish, packaging, and release testing ## Resume development diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 4cd1591..2e353c2 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -206,12 +206,10 @@ capability limitations. Editing remains planned. Recommended implementation order after the current checkpoint: -1. Downloads Download all execution -2. Downloads Remove / Clear / Retry actions -3. Library sync actions +1. Beta polish, packaging, and release testing +2. Active-download cancellation, if still desired +3. Library sync execution controls, if explicitly approved 4. `999` command and naming migration -5. Native FLAC support -6. Beta polish, packaging, and release testing Possible future improvements: diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 7ef040a..c9f3373 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -21,12 +21,18 @@ beside the audio with the same basename: ```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. Native FLAC library scanning remains planned -separately. +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`. ## Normal day-to-day use @@ -127,7 +133,7 @@ juice-lyrics 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/ @@ -152,6 +158,10 @@ 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. diff --git a/pyproject.toml b/pyproject.toml index a4693d8..69db4bb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ 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" +description = "Manage local lyrics metadata and rmpc LRC files for MP3, FLAC, and M4A libraries" readme = "README.md" requires-python = ">=3.11" dependencies = [ @@ -16,7 +16,7 @@ license = { text = "MIT" } 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 = [ "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", diff --git a/src/juice_lyrics/backup/manager.py b/src/juice_lyrics/backup/manager.py index 3d1ce0c..402feef 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -12,10 +12,19 @@ from ..config.settings import BACKUP_DIR, DATA_DIR 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.""" @@ -71,7 +80,7 @@ def _manifest_created_at(root: Path) -> datetime | None: if not isinstance(raw_created, str): return None files = manifest.get("files") - if not (isinstance(files, list) and files) and not any(root.rglob("*.mp3")): + 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): @@ -140,12 +149,12 @@ def write_manifest(root: Path, entries: list[dict[str, Any]]) -> None: ), encoding="utf-8", ) - # Some batch failures occur after the pristine MP3 was copied but before + # 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 any(root.rglob("*.mp3")) + 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 @@ -158,7 +167,7 @@ def write_manifest(root: Path, entries: list[dict[str, Any]]) -> None: def restore_backup(root: Path, base: Path) -> int: restored = 0 - for source in root.rglob("*.mp3"): + for source in _backup_audio_files(root): destination = base / source.relative_to(root) destination.parent.mkdir(parents=True, exist_ok=True) shutil.copy2(source, destination) diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 0ef7495..908b463 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -535,7 +535,15 @@ def write_state_entry(state: dict[str, Any], path: Path, settings: Settings, ana "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(), } @@ -554,7 +562,11 @@ 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": + 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 @@ -612,7 +624,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() @@ -850,7 +862,7 @@ def scan_progress(event): 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 MP3(s)? [y/N] ").strip().lower() not in {"y", "yes"}: + 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 @@ -883,7 +895,7 @@ def command_status(settings: Settings, use_color: bool) -> int: print_header("Library Status", use_color) print(f"Library: {status.library_path}") print("External lyrics: Beside each song (.lrc)") - print(f"MP3 files: {status.track_count}") + 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}") @@ -1010,9 +1022,9 @@ def command_guide() -> int: juice-lyrics 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. @@ -1053,7 +1065,7 @@ 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 @@ -1514,9 +1526,9 @@ def command_tui(settings: Settings) -> int: 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) @@ -1536,14 +1548,14 @@ 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") diff --git a/src/juice_lyrics/library/matching.py b/src/juice_lyrics/library/matching.py index 8917ce2..faf35a1 100644 --- a/src/juice_lyrics/library/matching.py +++ b/src/juice_lyrics/library/matching.py @@ -7,6 +7,7 @@ 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", @@ -51,18 +52,21 @@ 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 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_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)) diff --git a/src/juice_lyrics/library/media.py b/src/juice_lyrics/library/media.py new file mode 100644 index 0000000..43dce79 --- /dev/null +++ b/src/juice_lyrics/library/media.py @@ -0,0 +1,113 @@ +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + +from mutagen.flac import FLAC +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 + + +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 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, + ) + + +def read_m4a_metadata(path: Path) -> AudioMetadata: + """Read standard MP4/M4A atoms without modifying the file.""" + + audio = MP4(path) + 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, + ) + + +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 fbbd807..613f5d6 100644 --- a/src/juice_lyrics/lyrics/engine.py +++ b/src/juice_lyrics/lyrics/engine.py @@ -5,8 +5,11 @@ 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" @@ -42,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" @@ -52,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: @@ -83,6 +131,22 @@ 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 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]], @@ -91,7 +155,10 @@ def write_lrc( """Atomically create or update synchronized lyrics beside ``path``.""" if not synced: raise ValueError("No synchronized lyrics available") - meta = read_mp3_metadata(path, fallback) + 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'])}]"] diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index e843872..41d47af 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -11,6 +11,12 @@ 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 verify_file from ..lyrics.sidecar import sidecar_lrc_path from ..state import sha256_file @@ -45,7 +51,7 @@ class LibraryStateStatus(str, Enum): @dataclass(frozen=True, slots=True) class LibraryTrack: - """Presentation-neutral read-only information about one local MP3.""" + """Presentation-neutral read-only information about one local audio file.""" reference: str path: Path @@ -60,6 +66,9 @@ class LibraryTrack: lrc_path: Path | None state_status: LibraryStateStatus warning: str | None = None + artist: str | None = None + album: str | None = None + media_format: str = "MP3" @property def needs_attention(self) -> bool: @@ -116,7 +125,7 @@ def needs_attention_count(self) -> int: @dataclass(frozen=True, slots=True) class LibraryStatus: - """Read-only snapshot of the application's MP3 library status.""" + """Read-only snapshot of the application's local audio library status.""" library_path: Path track_count: int @@ -162,8 +171,9 @@ def get_library_snapshot( verifier: LyricsVerifier = verify_file, duration_reader: DurationReader = local_duration, hasher: Callable[[Path], str] = sha256_file, + metadata_reader: Callable[[Path], AudioMetadata] = read_tagged_metadata, ) -> LibrarySnapshot: - """Inspect local MP3s and state without contacting APIs or writing files.""" + """Inspect local MP3, FLAC, and M4A files without APIs or writes.""" library_path = Path(settings.music_dir) if not library_path.is_dir(): @@ -183,6 +193,25 @@ def get_library_snapshot( raw_entry = state_files.get(reference) entry = raw_entry if isinstance(raw_entry, dict) else 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) @@ -218,11 +247,24 @@ def get_library_snapshot( candidate_title = entry.get("api_name") if candidate_title is not None and str(candidate_title).strip(): matched_title = str(candidate_title).strip() - matched = bool(matched_title or (entry is not None and entry.get("song_id") is not None)) + matched = metadata_safe_for_matching and bool( + matched_title or (entry is not None 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) lrc_path = ( - sidecar_lrc_path(path) + adjacent_lrc if lyric_status is LibraryLyricStatus.SYNCED + or expected_synced + or (is_tagged_container(path) and adjacent_lrc.is_file()) else None ) if lrc_path is None: @@ -234,7 +276,11 @@ def get_library_snapshot( track_warnings.append("Adjacent external LRC file is missing.") try: - duration = duration_reader(path) + 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}") @@ -245,7 +291,7 @@ def get_library_snapshot( path=path, relative_path=relative_path, filename=path.name, - title=path.stem, + 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 @@ -255,6 +301,9 @@ def get_library_snapshot( 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), warning=" ".join(track_warnings) or None, ) ) @@ -292,10 +341,8 @@ def get_library_status( entry = state_files.get(relative) if not isinstance(entry, dict) or entry.get("sha256") != sha256_file(path): new_or_changed += 1 - if ( - valid - and message.startswith("SYLT") - and sidecar_lrc_path(path).is_file() + if sidecar_lrc_path(path).is_file() and ( + (valid and message.startswith("SYLT")) or is_tagged_container(path) ): lrc += 1 diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index 4aebb35..4ac7877 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -12,6 +12,7 @@ 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 @@ -238,7 +239,11 @@ def _state_is_current( valid, _ = dependencies.verifier(path) if not valid: return False - if options.rmpc_enabled and entry.get("lyric_type") == SyncLyricType.SYNCED.value: + if options.rmpc_enabled and entry.get("lyric_type") in { + SyncLyricType.SYNCED.value, + "FLAC_LYRICS_SYNCED", + "M4A_LYRICS_SYNCED", + }: if not sidecar_lrc_path(path).is_file(): return False return True @@ -301,6 +306,16 @@ def plan_library_sync( ) ) _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)) @@ -339,11 +354,24 @@ def _state_entry( 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" + ) state.setdefault("files", {})[str(track.path.relative_to(options.music_dir))] = { "sha256": dependencies.hasher(track.path), "song_id": candidate.get("id"), "api_name": candidate.get("name"), - "lyric_type": track.lyric_type.value, + "lyric_type": lyric_type, "lrc": str(lrc_path) if lrc_path else None, "updated": now_iso(), } diff --git a/src/juice_lyrics/services/settings_snapshot.py b/src/juice_lyrics/services/settings_snapshot.py index 93684e9..582153e 100644 --- a/src/juice_lyrics/services/settings_snapshot.py +++ b/src/juice_lyrics/services/settings_snapshot.py @@ -274,8 +274,8 @@ def get_settings_snapshot( ), application_version=__version__, limitations=( - "Local library scanning currently supports MP3 files only.", - "Native FLAC support is planned but not implemented.", + "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.", diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py index 360bc1b..a59e402 100644 --- a/src/juice_lyrics/tui/screens/dashboard.py +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -110,7 +110,7 @@ def _render_library(self, status: LibraryStatus | None, failure: str | None) -> lines = ( f"Path {status.library_path}", - f"MP3 tracks {status.track_count}", + 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}", diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index f2aa49f..2a77309 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -107,7 +107,7 @@ class PreviewOutcome: class LibraryScreen(HubScreen): - """Read-only local MP3 library browser and sync-plan preview.""" + """Read-only local audio library browser and sync-plan preview.""" BINDINGS = [Binding("/", "focus_search", "Search", show=False)] @@ -134,11 +134,11 @@ def __init__( def compose_content(self) -> Iterable[Widget]: yield Static( - "MP3 tracks 0 · Matched 0 · Unmatched 0 · Synced 0 · Plain 0 · No lyrics 0 · LRC 0 · Attention 0", + "Audio tracks 0 · Matched 0 · Unmatched 0 · Synced 0 · Plain 0 · No lyrics 0 · LRC 0 · Attention 0", id="library-summary", markup=False, ) - yield Static("Loading local MP3 library…", id="library-status", 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") @@ -181,7 +181,7 @@ def refresh_snapshot(self) -> None: self.query_one("#library-preview", Static).update( "Preview not generated · press s · Preview only — no files changed" ) - self._set_status("Refreshing local MP3 library…") + self._set_status("Refreshing local audio library…") self._snapshot_worker = self._load_snapshot() def invalidate_snapshot(self) -> None: @@ -272,11 +272,11 @@ def _apply_snapshot(self, outcome: SnapshotOutcome) -> 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 tracks found. Native FLAC support is planned.") + self._set_status("No supported MP3, FLAC, or M4A tracks found.") elif outcome.snapshot.warnings: self._set_status(" ".join(outcome.snapshot.warnings), error=True) else: - self._set_status(f"Local MP3 library · {outcome.snapshot.library_path}") + self._set_status(f"Local audio library · {outcome.snapshot.library_path}") def _apply_preview(self, outcome: PreviewOutcome) -> None: if outcome.error or outcome.plan is None: @@ -311,7 +311,7 @@ def _render_summary(self) -> None: if snapshot is None: return self.query_one("#library-summary", Static).update( - f"MP3 tracks {snapshot.total_track_count} · Matched {snapshot.matched_count} · " + f"Audio tracks {snapshot.total_track_count} · Matched {snapshot.matched_count} · " f"Unmatched {snapshot.unmatched_count} · Synced {snapshot.synced_count} · " f"Plain {snapshot.plain_count} · No lyrics {snapshot.no_lyrics_count} · " f"LRC {snapshot.external_lrc_count} · Attention {snapshot.needs_attention_count}" @@ -353,7 +353,7 @@ def _render_tracks(self) -> None: f"Tracks · {len(self.filtered_tracks)} of {self.snapshot.total_track_count if self.snapshot else 0}" ) if not self.filtered_tracks: - message = "No tracks match the local search or filter." if self.snapshot and self.snapshot.tracks else "No MP3 tracks found." + 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 = [] @@ -379,6 +379,9 @@ def _render_details(self) -> None: 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"Matched {track.matched_title or _match_label(track)}", diff --git a/tests/test_backup_retention.py b/tests/test_backup_retention.py index 062cfed..5ca19fb 100644 --- a/tests/test_backup_retention.py +++ b/tests/test_backup_retention.py @@ -224,3 +224,41 @@ def test_retained_backup_can_still_be_restored(tmp_path): assert result.removed == (roots[0],) assert restored == 1 assert (target / "Track.mp3").read_bytes() == b"original audio" + + +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_core.py b/tests/test_core.py index 53c8dab..e151ae4 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -66,7 +66,7 @@ def test_command_status_with_settings(tmp_path, capsys, monkeypatch): out = capsys.readouterr().out assert "Library Status" in out assert "External lyrics: Beside each song (.lrc)" in out - assert "MP3 files: 0" in out + assert "Audio files: 0" in out # Status with an MP3 file mp3 = tmp_path / "track.mp3" @@ -75,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 diff --git a/tests/test_flac_support.py b/tests/test_flac_support.py new file mode 100644 index 0000000..467996e --- /dev/null +++ b/tests/test_flac_support.py @@ -0,0 +1,314 @@ +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", + 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)): + if value is not None: + tags[key] = [value] + if any(value is not None for value in (title, artist, album)): + 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", + 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.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_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_library_status.py b/tests/test_library_status.py index 8f0e1e6..bc2cc07 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -103,7 +103,7 @@ def test_library_status_counts_lyrics_changes_lrc_and_backups(tmp_path): assert status.warnings == () -def test_library_status_marks_new_file_for_sync_and_ignores_non_mp3(tmp_path): +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") @@ -115,9 +115,9 @@ def test_library_status_marks_new_file_for_sync_and_ignores_non_mp3(tmp_path): verifier=lambda path: (False, "invalid"), ) - assert status.track_count == 1 - assert status.missing_or_invalid_count == 1 - assert status.new_or_changed_count == 1 + 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): diff --git a/tests/test_m4a_support.py b/tests/test_m4a_support.py new file mode 100644 index 0000000..d67aea9 --- /dev/null +++ b/tests/test_m4a_support.py @@ -0,0 +1,338 @@ +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", + 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)): + tags.add_tags() + for key, value in (("\xa9nam", title), ("\xa9ART", artist), ("\xa9alb", album)): + if value is not None: + tags[key] = [value] + 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", + 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.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_settings_snapshot.py b/tests/test_settings_snapshot.py index 9475772..a696a02 100644 --- a/tests/test_settings_snapshot.py +++ b/tests/test_settings_snapshot.py @@ -117,8 +117,8 @@ def test_paths_and_limitations_are_typed_and_read_only(tmp_path): assert paths["music"].exists is True assert paths["cache"].exists is False assert paths["state"].path == tmp_path / "data" / "state.json" - assert "MP3 files only" in snapshot.limitations[0] - assert any("FLAC" in item for item in snapshot.limitations) + 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() diff --git a/tests/test_tui.py b/tests/test_tui.py index d60e530..6544901 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -64,7 +64,7 @@ async def scenario(): library = _rendered(app, "#library-data") queue = _rendered(app, "#queue-data") assert str(tmp_path / "music") in library - assert "MP3 tracks 4" 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 @@ -102,7 +102,7 @@ async def scenario(): ) async with app.run_test() as pilot: await pilot.pause() - assert "MP3 tracks 0" in _rendered(app, "#library-data") + 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") @@ -146,7 +146,7 @@ async def scenario(): await pilot.press("r") await pilot.pause() assert calls == {"library": 2, "queue": 2} - assert "MP3 tracks 2" in _rendered(app, "#library-data") + assert "Audio tracks 2" in _rendered(app, "#library-data") assert "1 song ready to download" in _rendered(app, "#queue-data") asyncio.run(scenario()) @@ -241,7 +241,7 @@ async def scenario(): release.set() await worker.wait() await pilot.pause() - assert "MP3 tracks 4" in _rendered(app, "#library-data") + assert "Audio tracks 4" in _rendered(app, "#library-data") try: asyncio.run(scenario()) @@ -266,7 +266,7 @@ async def scenario(): app = _app(tmp_path, library=library) async with app.run_test() as pilot: await pilot.pause() - assert "MP3 tracks 1" in _rendered(app, "#library-data") + 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") @@ -275,14 +275,14 @@ async def scenario(): assert current_worker is not None await current_worker.wait() await pilot.pause() - assert "MP3 tracks 3" in _rendered(app, "#library-data") + 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 "MP3 tracks 3" in _rendered(app, "#library-data") + assert "Audio tracks 3" in _rendered(app, "#library-data") try: asyncio.run(scenario()) @@ -389,7 +389,7 @@ async def scenario(): async with app.run_test(size=(50, 20)) as pilot: await pilot.pause() assert "-narrow" in app.screen.classes - assert "MP3 tracks 4" in _rendered(app, "#library-data") + assert "Audio tracks 4" in _rendered(app, "#library-data") await pilot.press("5") await pilot.pause() assert app.screen.id == "screen-settings" diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 443efca..5c2e522 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -127,7 +127,7 @@ async def scenario(): screen = await _open_library(app, pilot) assert screen.__class__.__name__ == "LibraryScreen" summary = _text(app, "#library-summary") - assert "MP3 tracks 3" in summary and "Matched 2" in summary and "Unmatched 1" in summary + assert "Audio tracks 3" in summary and "Matched 2" in summary and "Unmatched 1" in summary assert "Synced 1" in summary and "Plain 1" in summary and "No lyrics 1" in summary assert "LRC 1" in summary and "Attention 2" in summary rows = _text(app, "#library-tracks") @@ -192,7 +192,7 @@ async def states_scenario(): app = _app(tmp_path, lambda settings: responses.pop(0)) async with app.run_test() as pilot: await _open_library(app, pilot) - assert "No MP3 tracks found" in _text(app, "#library-tracks") + assert "No supported audio tracks found" in _text(app, "#library-tracks") await pilot.press("r") await app.screen._snapshot_worker.wait() await pilot.pause() diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py index 59256af..ede528f 100644 --- a/tests/test_tui_settings.py +++ b/tests/test_tui_settings.py @@ -72,8 +72,8 @@ def _snapshot( ), application_version="1.4.0", limitations=( - "Local library scanning currently supports MP3 files only.", - "Native FLAC support is planned but not implemented.", + "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.", @@ -127,7 +127,7 @@ async def scenario(): 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 files only" in capabilities and "FLAC support is planned" in capabilities + assert "MP3, FLAC, and M4A" in capabilities assert "Library sync execution remains CLI-only" in capabilities await pilot.press("down", "j") From d05db199134349baf5bfba1a4f882305e05d6a88 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 6 Sep 2026 11:32:17 +0100 Subject: [PATCH 35/62] Rename app to 999 and prepare beta packaging --- PROJECT_CONTEXT.md | 47 ++++---- README.md | 88 +++++++++----- docs/ARCHITECTURE.md | 5 + docs/CHANGELOG.md | 14 +++ docs/DECISIONS.md | 16 +++ docs/DEVELOPMENT.md | 24 +++- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 90 +++++--------- docs/PROJECT_STATE.md | 17 +-- docs/ROADMAP_V2.md | 18 +-- docs/USER_GUIDE.md | 61 ++++++---- docs/V2_DESIGN.md | 12 +- pyproject.toml | 3 +- src/juice_lyrics/cli.py | 73 ++++++------ src/juice_lyrics/config/settings.py | 12 +- src/juice_lyrics/identity.py | 7 ++ src/juice_lyrics/tui/__init__.py | 2 +- src/juice_lyrics/tui/app.py | 2 +- src/juice_lyrics/tui/screens/__init__.py | 2 +- src/juice_lyrics/tui/screens/dashboard.py | 4 +- src/juice_lyrics/tui/screens/settings.py | 2 +- tests/test_core.py | 42 ++++++- tests/test_product_identity.py | 138 ++++++++++++++++++++++ tests/test_tui.py | 1 + tests/test_tui_settings.py | 4 +- 24 files changed, 467 insertions(+), 217 deletions(-) create mode 100644 src/juice_lyrics/identity.py create mode 100644 tests/test_product_identity.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 50b9c82..8313e63 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -58,7 +58,7 @@ authority. The legacy `lyrics_dir` key remains readable but is deprecated and cannot redirect current output. Read-only inspection and planning create nothing; rmpc configuration and historical state paths cannot redirect new output. During development use the repository entry -point (`.venv/bin/juice-lyrics`) so a stale separately installed package is not +point (`.venv/bin/999`) so a stale separately installed package is not mistaken for the current working tree. Preserve unrelated rmpc configuration when modifying configuration files. @@ -66,9 +66,9 @@ Preserve unrelated rmpc configuration when modifying configuration files. Advanced commands: ```bash -juice-lyrics rmpc setup -juice-lyrics rmpc sync -juice-lyrics rmpc verify +999 rmpc setup +999 rmpc sync +999 rmpc verify ``` ## Matching @@ -87,26 +87,26 @@ This helps prevent version mix-ups such as selecting `Starstruck (v1)` for a loc ## Normal workflow -First-time setup: +Open the application: ```bash -juice-lyrics setup +999 ``` Normal maintenance: ```bash -juice-lyrics sync +999 sync ``` Useful commands: ```bash -juice-lyrics status -juice-lyrics search -juice-lyrics info -juice-lyrics guide -juice-lyrics doctor +999 status +999 search +999 info +999 guide +999 doctor ``` ## Project direction @@ -209,10 +209,10 @@ It should not: 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 +999 acquire search "rental" +999 acquire add "rental" --index 1 +999 acquire jobs +999 acquire run ``` The selection model must remain explicit. A search operation should not silently create acquisition jobs for every result. @@ -302,15 +302,16 @@ The latest development checkpoint reports: * TUI Download selected, Download queue, Retry, Remove, Clear queue, and Clear completed history are implemented; active-download cancel, configuration editing, and library sync execution are not implemented -* legacy CLI remains the way to run whole acquisition records, retry, delete jobs, and sync -* 310 automated tests passing across the suite +* advanced CLI remains the way to run whole acquisition records, retry, delete jobs, and sync +* 318 automated tests passing across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` -on branch `v2-redesign`. The planned product and executable name remains `999`, -but no rename or migration has been performed. +on branch `v2-redesign`. The product and primary executable are `999`. +`juice-lyrics` remains a legacy command alias; the internal `juice_lyrics` +package, `juice-wrld-lyrics` distribution, and existing `juice-lyrics` XDG +storage namespace remain stable for compatibility. -Recommended next milestones are beta polish and release testing, followed by -the separately planned `999` naming migration when explicitly approved. +Recommended next milestone is final beta polish and release testing. To resume: @@ -318,7 +319,7 @@ To resume: cd /home/nobloat/Downloads/juice-lyrics-codex git switch v2-redesign .venv/bin/pytest -q -.venv/bin/juice-lyrics tui +.venv/bin/999 ``` ## Development rules diff --git a/README.md b/README.md index 7adff1d..6f9158c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# juice-lyrics 1.4.0 +# 999 -A small, cautious Linux CLI for managing lyrics metadata in local MP3, FLAC, and M4A 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. @@ -9,10 +9,19 @@ It uses the Juice WRLD API as a metadata/lyrics source, prefers synchronized lyr ### 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: @@ -31,7 +40,7 @@ Your Juice WRLD folder is kept together: After adding or changing songs: ```bash -juice-lyrics sync +999 sync ``` `sync` remembers the files it has already processed. Unchanged, verified files are skipped, so normal updates are much faster than a full rescan. @@ -39,13 +48,13 @@ juice-lyrics sync Useful status command: ```bash -juice-lyrics status +999 status ``` Built-in guide: ```bash -juice-lyrics guide +999 guide ``` ## What `sync` does @@ -70,9 +79,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. @@ -96,7 +105,7 @@ Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/AR | 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 | @@ -108,7 +117,7 @@ Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/AR | `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` | Explicit advanced rmpc operations | | `config` | Manage persistent configuration | | `cache clear` | Clear cached API responses | @@ -163,9 +172,9 @@ 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 @@ -173,24 +182,36 @@ 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 editable install ```bash -pipx install . +pipx install --editable /absolute/path/to/juice-lyrics-codex +command -v 999 +999 --help +``` + +The distribution remains named `juice-wrld-lyrics` for update compatibility. +If pipx already has an older copy, replace it deliberately: + +```bash +pipx install --force --editable /absolute/path/to/juice-lyrics-codex +hash -r +command -v 999 +999 --help ``` ### Editable development install @@ -204,13 +225,16 @@ pip install -e . For development checkpoints, invoke the repository environment explicitly: ```bash -.venv/bin/juice-lyrics tui +.venv/bin/999 ``` -If `command -v juice-lyrics` points at an older pipx installation, that command -will not contain current uncommitted source changes. Reinstall it deliberately or -keep using `.venv/bin/juice-lyrics`; changing the repository cannot update an -already installed copy. +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. ## Development @@ -227,23 +251,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 f77aa48..2c62478 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -213,6 +213,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. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 5f009d6..ea17094 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## Unreleased — 999 beta identity and packaging + +* Made `999` the primary product name and console entry point while retaining + `juice-lyrics` as an alias to the same CLI implementation. +* Kept the internal `juice_lyrics` package, `juice-wrld-lyrics` distribution, + and `juice-lyrics` XDG storage namespace stable for compatibility. +* Made no-argument startup open the existing TUI and kept startup read-only with + respect to rmpc configuration and deprecated centralized lyrics paths. +* Clarified setup responsibilities: `config init` writes starter configuration, + `setup` synchronizes the library, and only explicit `rmpc setup` changes rmpc. +* Added isolated entry-point, first-run, storage compatibility, shell, and + editable-install verification. +* Verified 318 automated tests with isolated temporary HOME/XDG paths. + ## Unreleased — Native M4A library support * Added recursive, case-insensitive `.m4a` library discovery without broadening diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index a887d17..724b460 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -183,3 +183,19 @@ Major systems: - 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` may +do that. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 2516a4a..04612c2 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -48,7 +48,12 @@ 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. @@ -57,15 +62,24 @@ Keep the runtime dependency set small. From the repository's editable installation, launch the TUI with: ```bash -.venv/bin/juice-lyrics tui +.venv/bin/999 ``` -Use `command -v juice-lyrics` before manual regression testing. A separately +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. -The experimental shell provides functional Dashboard, Browse, Library, +For a deterministic editable pipx installation: + +```bash +pipx install --force --editable /absolute/path/to/juice-lyrics-codex +hash -r +command -v 999 +999 --help +``` + +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 @@ -117,7 +131,7 @@ 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 `juice-lyrics sync`. The +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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 7e41600..348f3cb 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -38,7 +38,8 @@ A Juice WRLD music management hub containing: - rmpc integration - backup and recovery systems -The current name no longer fully represents the project scope. +The product is now named `999`. The primary console command is `999`, while +`juice-lyrics` remains a legacy compatibility command. --- @@ -52,7 +53,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -310 passing tests. +318 passing tests. Completed and integrated: @@ -94,11 +95,11 @@ sequential Download queue, Retry, Remove, Clear queue, and Clear completed histo Active-download cancellation, configuration editing, and library sync execution are not implemented. Durable jobs remain an internal backend detail and completed entries are hidden -from the active track queue. The legacy CLI remains the way to run downloads, +from the active track queue. The advanced CLI remains the way to run downloads, delete jobs, and sync. Existing local FLAC and M4A files are now first-class library -tracks; acquisition remains MP3-focused. The planned -product/executable name remains `999`; package, distribution, and data paths -have not been renamed. +tracks; acquisition remains MP3-focused. The product and primary executable are +`999`; the internal package, distribution identifier, and XDG data namespace +remain compatible with existing installations. Live API acquisition was tested successfully. @@ -412,7 +413,7 @@ Current application architecture keeps each same-basename LRC beside its MP3, FL file. The finalized audio path is authoritative; the legacy centralized `lyrics_dir` configuration is accepted only for compatibility and does not direct new output. Existing centralized files require a separate explicit -migration and are never moved automatically by `juice-lyrics`. +migration and are never moved automatically by `999`. Therefore: @@ -450,64 +451,32 @@ This is accepted as a player limitation. --- -# Future CLI Direction - -The CLI should become simpler. - -Current: - - -juice-lyrics acquire search Rental - -juice-lyrics acquire add Rental --index 1 - -juice-lyrics acquire run UUID - - -Future: - - -999 search Rental - -999 get Rental - - -The old commands can remain as compatibility commands. - ---- - -# Possible Rename - -The application probably needs a new name. - -Current favourite ideas: - -## 999 - -Pros: -- Juice WRLD connection -- memorable -- short command -- fits terminal culture - -Possible command: +# Command Direction +The normal product entry point is simply: +```bash 999 +``` +Advanced compatibility commands remain available under `999 acquire`. +`juice-lyrics` is an executable alias to the same CLI implementation. -or: - - -999 search Rental +--- +# Product Identity -Other possibilities: +The naming decision for beta is: -- Abyss -- JuiceBox +- product: `999` +- primary command: `999` +- legacy command: `juice-lyrics` +- Python package: `juice_lyrics` +- distribution: `juice-wrld-lyrics` +- XDG storage namespace: `juice-lyrics` -No final decision yet. +These compatibility names avoid breaking imports, installed-package upgrades, +or existing config, state, queue, cache, and backup data. --- @@ -528,12 +497,11 @@ Design ## Phase 2 -Migration +Command compatibility -- new package name -- new command -- compatibility layer -- preserve old data +- primary `999` command +- legacy command alias +- preserve old data and internal package paths ## Phase 3 diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index cc4e0d3..b671b2d 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,11 +1,11 @@ # 999 Project State ## Current Status -Backend services remain stable. The experimental Textual frontend supports +Backend services remain stable. The `999` Textual interface supports explicit confirmed single- and multi-song Browse Add to queue actions and selected or whole-queue downloads. The interface now prioritizes the streamlined Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 310 passing tests. +checkpoint has 318 passing tests. ## Current Branch v2-redesign @@ -47,7 +47,7 @@ v2-redesign ## Available through the CLI -The legacy CLI remains the supported way to run whole acquisition records, +The advanced CLI remains the supported way to run whole acquisition records, retry failures, delete durable acquisition records, and sync the library. ## Current limitations @@ -58,8 +58,10 @@ retry failures, delete durable acquisition records, and sync the library. completed history without deleting downloaded files. - Acquisition post-processing remains MP3-only; native FLAC and M4A support targets existing local-library files. -- The planned executable/product name remains `999`; package, distribution, and - data paths remain named `juice-lyrics`. +- `999` is the primary product and executable name. `juice-lyrics` remains a + legacy compatibility command. The Python namespace remains `juice_lyrics`, + the distribution remains `juice-wrld-lyrics`, and existing XDG data remains + under `juice-lyrics` without migration. ## Important Decisions - Keep embedded lyrics @@ -70,10 +72,9 @@ retry failures, delete durable acquisition records, and sync the library. ## Recommended next milestones -1. Beta polish, packaging, and release testing +1. Final beta polish and release testing 2. Active-download cancellation, if still desired 3. Library sync execution controls in the TUI, if explicitly approved -4. `999` command and naming migration ## Resume development @@ -81,5 +82,5 @@ retry failures, delete durable acquisition records, and sync the library. cd /home/nobloat/Downloads/juice-lyrics-codex git switch v2-redesign .venv/bin/pytest -q -.venv/bin/juice-lyrics tui +.venv/bin/999 ``` diff --git a/docs/ROADMAP_V2.md b/docs/ROADMAP_V2.md index 2e353c2..afe7578 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -1,6 +1,6 @@ # v2 Development Roadmap -This document defines the order of work for transforming juice-lyrics into a polished Juice WRLD music management application. +This document defines the order of work for transforming the project into the polished `999` Juice WRLD music application. The existing backend is considered stable and should be preserved. @@ -67,6 +67,8 @@ Do not change user-facing behaviour unless necessary. # Phase 2 — Identity and Migration +Status: Complete for beta preparation. + Goal: Introduce the new application identity. @@ -76,24 +78,24 @@ Tasks: - Choose final name. - Update package metadata. - Create new CLI command. -- Add migration from old configuration paths. -- Preserve juice-lyrics compatibility. +- Keep existing configuration paths without creating a second data tree. +- Preserve the legacy `juice-lyrics` command and storage compatibility. Example: -Old: +Primary: -juice-lyrics sync +999 sync -New: +Legacy compatibility: -999 sync +juice-lyrics sync -Both should work during transition. +Both invoke the same CLI implementation during the transition. --- diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index c9f3373..e216a75 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -1,16 +1,21 @@ # User Guide -## First-time setup +## First run Run: ```bash -juice-lyrics setup +999 ``` -When rmpc is detected, setup generates synchronized LRC sidecars and updates -rmpc to index the configured music tree after its normal confirmation. Merely -loading configuration creates no directories or files. +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. + +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 @@ -39,7 +44,7 @@ adjacent `.lrc`. After adding or changing local songs: ```bash -juice-lyrics sync +999 sync ``` `sync` should be the main command to remember. @@ -49,7 +54,7 @@ It matches songs, fetches lyrics, embeds metadata, generates rmpc LRC files when ## Check health ```bash -juice-lyrics status +999 status ``` Use this when you simply want to know whether the library is up to date. @@ -57,8 +62,8 @@ Use this when you simply want to know whether the library is up to date. ## 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. @@ -71,25 +76,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. @@ -110,25 +115,25 @@ Those plain-only songs are still tagged correctly, but rmpc's synchronized Lyric ## Troubleshooting ```bash -juice-lyrics doctor +999 doctor ``` For detailed matching: ```bash -juice-lyrics scan +999 scan ``` For metadata verification: ```bash -juice-lyrics verify +999 verify ``` For rmpc-specific problems: ```bash -juice-lyrics rmpc verify +999 rmpc verify ``` ## Backups @@ -142,7 +147,7 @@ MP3, FLAC, and M4A metadata changes create timestamped backups under: Restore the most recent backup with: ```bash -juice-lyrics restore +999 restore ``` ## Paths @@ -167,3 +172,17 @@ 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 +~/.config/juice-lyrics/ +~/.cache/juice-lyrics/ +~/.local/share/juice-lyrics/ +``` + +No duplicate `999` data tree is created and no migration is required. diff --git a/docs/V2_DESIGN.md b/docs/V2_DESIGN.md index 9c72bbb..af839fc 100644 --- a/docs/V2_DESIGN.md +++ b/docs/V2_DESIGN.md @@ -1,8 +1,8 @@ -# juice-lyrics v2 Design Proposal +# 999 Design Proposal ## Vision -juice-lyrics has grown beyond a simple lyrics tagging tool. +The project has grown beyond the original `juice-lyrics` lyrics-tagging scope. The project is becoming a complete Juice WRLD music management application for Linux: @@ -21,7 +21,7 @@ Version 2 should transform the project from a powerful developer tool into a pol ## Problem -The name "juice-lyrics" no longer represents the full application. +The product is now named `999`; `juice-lyrics` remains a compatibility command. The project now includes: @@ -125,11 +125,11 @@ Example: Current workflow: -juice-lyrics acquire search "Rental" +999 acquire search "Rental" -juice-lyrics acquire add "Rental" --index 1 +999 acquire add "Rental" --index 1 -juice-lyrics acquire run +999 acquire run This works, but it feels like developer tooling. diff --git a/pyproject.toml b/pyproject.toml index 69db4bb..727f0c3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ 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, FLAC, and M4A libraries" +description = "999: a Juice WRLD music hub for Linux" readme = "README.md" requires-python = ">=3.11" dependencies = [ @@ -25,6 +25,7 @@ classifiers = [ ] [project.scripts] +999 = "juice_lyrics.cli:main" juice-lyrics = "juice_lyrics.cli:main" [project.urls] diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 908b463..1cc7caa 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -22,9 +22,10 @@ from . import __version__ from .config.settings import DEFAULT_LYRICS_DIR +from .identity import PRODUCT_NAME, STORAGE_NAMESPACE from .lyrics.sidecar import sidecar_lrc_path -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" @@ -60,9 +61,9 @@ 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_CONFIG = CONFIG_HOME / "rmpc" / "config.ron" @@ -781,7 +782,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}") @@ -791,12 +792,11 @@ 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, Path(settings.music_dir)) files = find_mp3s(settings) return embed_batch(settings, files, use_color, args.refresh, False, True, rmpc_available) @@ -991,35 +991,31 @@ 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 MP3, FLAC, and M4A files to the API. @@ -1070,7 +1066,7 @@ def command_restore(args: argparse.Namespace, settings: Settings, use_color: boo def command_doctor(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - print_header("juice-lyrics Doctor", use_color) + print_header("999 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)) @@ -1202,7 +1198,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 @@ -1326,7 +1322,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 @@ -1396,7 +1392,7 @@ 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 @@ -1519,7 +1515,7 @@ def command_acquire(args: argparse.Namespace, settings: Settings, use_color: boo def command_tui(settings: Settings) -> int: - """Launch the experimental Textual frontend without affecting CLI startup.""" + """Launch the 999 terminal interface.""" from .tui import run_tui @@ -1531,9 +1527,9 @@ def build_parser() -> argparse.ArgumentParser: 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") @@ -1563,7 +1559,7 @@ def build_parser() -> argparse.ArgumentParser: guide = sub.add_parser("guide", help="Show the built-in quick guide.") - sub.add_parser("tui", help="Launch the experimental read-only Textual interface.") + 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") @@ -1576,7 +1572,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") @@ -1633,6 +1629,7 @@ def main(argv: list[str] | None = None) -> int: use_color = not args.no_color and sys.stdout.isatty() try: settings = load_settings(getattr(args, "path", None), getattr(args, "api_base", None)) + 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) diff --git a/src/juice_lyrics/config/settings.py b/src/juice_lyrics/config/settings.py index 968f7f5..409b766 100644 --- a/src/juice_lyrics/config/settings.py +++ b/src/juice_lyrics/config/settings.py @@ -4,7 +4,11 @@ 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 @@ -23,9 +27,9 @@ 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" 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/tui/__init__.py b/src/juice_lyrics/tui/__init__.py index be0197d..3d9dec5 100644 --- a/src/juice_lyrics/tui/__init__.py +++ b/src/juice_lyrics/tui/__init__.py @@ -1,4 +1,4 @@ -"""Experimental read-only Textual frontend.""" +"""The 999 Textual frontend.""" from .app import JuiceLyricsApp, run_tui diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index a1f8e80..1eebf28 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -60,7 +60,7 @@ class JuiceLyricsApp(App[None]): - """The first read-only application shell for the planned 999 interface.""" + """The 999 terminal application.""" TITLE = "999" SUB_TITLE = "Juice WRLD Music Hub" diff --git a/src/juice_lyrics/tui/screens/__init__.py b/src/juice_lyrics/tui/screens/__init__.py index e503bcb..767259d 100644 --- a/src/juice_lyrics/tui/screens/__init__.py +++ b/src/juice_lyrics/tui/screens/__init__.py @@ -1,4 +1,4 @@ -"""Screens for the experimental Textual frontend.""" +"""Screens for the 999 Textual frontend.""" from .browse import BrowseScreen from .dashboard import DashboardScreen diff --git a/src/juice_lyrics/tui/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py index a59e402..d59d596 100644 --- a/src/juice_lyrics/tui/screens/dashboard.py +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -104,7 +104,9 @@ def _apply_snapshot(self, snapshot: DashboardSnapshot) -> None: 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") + 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 diff --git a/src/juice_lyrics/tui/screens/settings.py b/src/juice_lyrics/tui/screens/settings.py index 44c5570..3c33193 100644 --- a/src/juice_lyrics/tui/screens/settings.py +++ b/src/juice_lyrics/tui/screens/settings.py @@ -53,7 +53,7 @@ def __init__(self, settings: Any, *, snapshot_provider: SnapshotProvider) -> Non def compose_content(self) -> Iterable[Widget]: yield Static( - "Read-only settings view — configuration changes remain CLI-only", + "Read-only settings — configuration changes use the 999 CLI", id="settings-warning", markup=False, ) diff --git a/tests/test_core.py b/tests/test_core.py index e151ae4..eee49b3 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -156,9 +156,10 @@ 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): @@ -271,3 +272,38 @@ def test_config_init_and_missing_library_setup_dispatch_remain_compatible(tmp_pa 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" diff --git a/tests/test_product_identity.py b/tests/test_product_identity.py new file mode 100644 index 0000000..6b77c97 --- /dev/null +++ b/tests/test_product_identity.py @@ -0,0 +1,138 @@ +from __future__ import annotations + +import argparse +import tomllib +from pathlib import Path + +import pytest + +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_tui.py b/tests/test_tui.py index 6544901..b9f2856 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -325,6 +325,7 @@ async def scenario(): 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() diff --git a/tests/test_tui_settings.py b/tests/test_tui_settings.py index ede528f..96b3dd7 100644 --- a/tests/test_tui_settings.py +++ b/tests/test_tui_settings.py @@ -113,7 +113,7 @@ async def scenario(): 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 view — configuration changes remain CLI-only" in _text(app, "#settings-warning") + 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 @@ -275,7 +275,7 @@ async def scenario(size): assert scroll.scroll_y > 0 await pilot.press("pageup") assert screen.selected_index < len(screen.rows) - 1 - assert "Read-only settings view" in _text(app, "#settings-warning") + 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)) From 04ed49c343ad79d12a59cf1a1c2d481fc87b4000 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Wed, 9 Sep 2026 22:51:22 +0100 Subject: [PATCH 36/62] Add TUI library management --- PROJECT_CONTEXT.md | 13 +- README.md | 13 +- docs/ARCHITECTURE.md | 6 + docs/DECISIONS.md | 4 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 26 +- docs/PROJECT_STATE.md | 13 +- docs/UI_DESIGN.md | 33 +- docs/USER_FLOWS.md | 31 +- docs/USER_GUIDE.md | 22 +- src/juice_lyrics/backup/manager.py | 9 + src/juice_lyrics/services/__init__.py | 2 + src/juice_lyrics/services/library_status.py | 39 ++ src/juice_lyrics/services/library_sync.py | 30 +- src/juice_lyrics/tui/app.py | 80 ++- src/juice_lyrics/tui/screens/library.py | 532 +++++++++++++++++++- tests/test_library_sync_service.py | 52 ++ tests/test_lrc_path_authority.py | 3 + tests/test_product_identity.py | 3 + tests/test_tui_library.py | 265 +++++++++- 19 files changed, 1066 insertions(+), 110 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 8313e63..03220bc 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -297,13 +297,16 @@ The latest development checkpoint reports: * canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour * server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details * flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility -* Library provides local track browsing, local filters, metadata/lyric/LRC/state details, and explicit read-only sync previews +* Library provides local track browsing, format-aware coverage summaries, + read-only refresh/verification, confirmed lyric maintenance, selected-song + refresh, valid backup browsing/restore, and rmpc verification/setup * Settings reports effective configuration, sidecar lyrics behavior, provenance where reliable, application paths, and rmpc integration without creating or changing files * TUI Download selected, Download queue, Retry, Remove, Clear queue, and Clear - completed history are implemented; active-download cancel, configuration editing, - and library sync execution are not implemented -* advanced CLI remains the way to run whole acquisition records, retry, delete jobs, and sync -* 318 automated tests passing across the suite + completed history are implemented; active-download cancel and general + configuration editing are not implemented +* advanced CLI remains available for scripting, diagnostics, internal records, + and unusual recovery +* 328 automated tests pass across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The product and primary executable are `999`. diff --git a/README.md b/README.md index 6f9158c..d69796e 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,12 @@ Your Juice WRLD folder is kept together: ### Normal use -After adding or changing songs: +Open `999`, choose **Library**, then use **Refresh**, **Maintain lyrics**, +**Verify**, or **Backups**. Maintenance always shows a non-mutating preview and +a cancel-first confirmation before changing audio metadata or sidecars. -```bash -999 sync -``` - -`sync` remembers the files it has already processed. Unchanged, verified files are skipped, so normal updates are much faster than a full rescan. +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: @@ -117,7 +116,7 @@ Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/AR | `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` | Explicit advanced rmpc 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 | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2c62478..2be2288 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,6 +40,12 @@ 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 MP3, FLAC, and M4A files recursively diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 724b460..f888ead 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -197,5 +197,5 @@ Future redesigns should build on these systems rather than replacing them. 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` may -do that. +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/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 348f3cb..cc0c1ce 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -53,7 +53,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -318 passing tests. +328 passing tests. Completed and integrated: @@ -85,18 +85,18 @@ pagination with scrollable 50-result pages, stable ID-based song details, and a Downloads screen with a flat track queue, song navigation, details, failure stages, retry eligibility, an explicit Browse Add to queue flow that never starts a download, and an explicitly confirmed Download selected action for one -eligible queued song, a read-only Library screen with local -track browsing, filters, details, and explicit sync previews, and a read-only +eligible queued song, a Library maintenance centre with local track browsing, +filters, details, read-only refresh/verification, confirmed lyric maintenance, +backup/restore, and rmpc checks, and a read-only Settings screen with effective configuration, paths, provenance, and rmpc state. All five primary TUI sections are functional. Browse supports confirmed single and batch queue additions. Downloads supports confirmed Download selected, sequential Download queue, Retry, Remove, Clear queue, and Clear completed history. -Active-download cancellation, configuration editing, and library sync execution -are not implemented. +Active-download cancellation and general configuration editing are not implemented. Durable jobs remain an internal backend detail and completed entries are hidden -from the active track queue. The advanced CLI remains the way to run downloads, -delete jobs, and sync. Existing local FLAC and M4A files are now first-class library +from the active track queue. The CLI remains available for automation, +diagnostics, and internal job recovery. Existing local FLAC and M4A files are first-class library tracks; acquisition remains MP3-focused. The product and primary executable are `999`; the internal package, distribution identifier, and XDG data namespace remain compatible with existing installations. @@ -160,8 +160,8 @@ docs/ The project is in incremental v2 implementation. The backend remains stable. -Mutating TUI actions are explicit and cancel-first; Library and Settings remain -read-only views, with library sync execution available through the CLI. +Mutating TUI actions are explicit and cancel-first. Library uses shared services +for maintenance and restore; Settings remains read-only. --- @@ -333,9 +333,11 @@ Shows: Actions: -- sync -- verify -- open details +- refresh and verify without writes +- preview and confirm lyric maintenance +- open details and refresh one selected song +- browse and restore valid backups +- verify or explicitly configure rmpc --- diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index b671b2d..dd8b526 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -5,7 +5,7 @@ Backend services remain stable. The `999` Textual interface supports explicit confirmed single- and multi-song Browse Add to queue actions and selected or whole-queue downloads. The interface now prioritizes the streamlined Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 318 passing tests. +checkpoint has 328 passing tests. ## Current Branch v2-redesign @@ -27,7 +27,10 @@ v2-redesign - Simplified primary shortcut bars, optional Browse selection indicators, plain-language confirmations, Dashboard journey prompts, and Settings folders before advanced diagnostics; all secondary queue actions remain available in Help. -- Library summary, local track navigation, typed lyric/match/LRC/state details, local filters, and explicit read-only sync preview. +- Library is the normal maintenance centre: format-aware summary, track details, + read-only refresh/verification, non-mutating maintenance preview, confirmed + shared-service execution, selected-song refresh, backup browsing/restore, and + rmpc verification/setup. - Settings configuration provenance, XDG/application paths, sidecar external-lyrics behavior, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. - Local FLAC files are recursively discovered and matched using native title, @@ -47,8 +50,8 @@ v2-redesign ## Available through the CLI -The advanced CLI remains the supported way to run whole acquisition records, -retry failures, delete durable acquisition records, and sync the library. +The advanced CLI remains supported for scripting, whole acquisition records, +low-level recovery, diagnostics, and durable acquisition-record operations. ## Current limitations @@ -74,7 +77,7 @@ retry failures, delete durable acquisition records, and sync the library. 1. Final beta polish and release testing 2. Active-download cancellation, if still desired -3. Library sync execution controls in the TUI, if explicitly approved +3. Post-beta enhancements only after real-user feedback ## Resume development diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index c8e20ca..c5a09b4 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -267,31 +267,26 @@ Manage local files. Example: -My Library +Library -Rental.mp3 +315 songs · Fully covered 287 · Plain only 14 · Missing 8 · Unmatched 6 +Formats · MP3 170 · FLAC 85 · M4A 60 -Lyrics: -Synced - -rmpc: -Ready - -Robbery.mp3 - -Lyrics: -Plain - -rmpc: -Unavailable +Rental.flac +Catalogue match ✓ +Embedded lyrics ✓ +Synced LRC ✓ Actions: -s Sync +r Refresh +m Maintain lyrics v Verify -enter Details +b Backups +p Player integration +enter Details; l refresh selected lyrics --- @@ -405,8 +400,10 @@ l Lyrics ## Library -s Sync +r Refresh +m Maintain lyrics v Verify +b Backups ## Downloads diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 5bdcecf..0eb99c0 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -382,7 +382,7 @@ esc Back ## Goal -Users can inspect their own collection. +Users can inspect and safely maintain their own collection. --- @@ -406,11 +406,15 @@ Missing Lyrics Actions: -s Sync Library +r Refresh -v Verify Lyrics +m Maintain lyrics -enter Details +v Verify + +b Backups + +enter Details; l refresh selected lyrics --- @@ -419,14 +423,14 @@ enter Details ## Goal -Update new or changed files. +Preview and update new or changed files without memorizing a CLI command. --- User: -Press s +Press m --- @@ -434,15 +438,14 @@ Press s Confirmation: -Sync library? - -Found: +Library maintenance -12 new files +12 songs can be updated +2 songs need attention -Continue? +No changes have been made. -[Enter] +[Update 12 songs] [Cancel] --- @@ -450,7 +453,7 @@ Continue? Progress: -Syncing... +Maintaining library... Rental.mp3 Matching... @@ -467,7 +470,7 @@ Complete Summary: -Sync Complete +Library updated Updated: 12 diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index e216a75..4ee6d53 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -39,17 +39,18 @@ synchronized natively without conversion. FLAC embeds plain-text Vorbis `LYRICS`; M4A embeds standard MP4 `©lyr`; synchronized timing remains in the adjacent `.lrc`. -## Normal day-to-day use +## Manage your local library -After adding or changing local songs: +Open `999`, choose **Library**, and use: -```bash -999 sync -``` - -`sync` should be the main command to remember. +* **Refresh** to rescan MP3, FLAC, and M4A files without changing them; +* **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. -It matches songs, fetches lyrics, embeds metadata, generates rmpc LRC files when synchronized lyrics exist, verifies results, and updates state. +Select a song and press `l` to refresh lyrics for only that song. The CLI +equivalent, `999 sync`, remains useful for scripting and automation. ## Check health @@ -130,7 +131,7 @@ For metadata verification: 999 verify ``` -For rmpc-specific problems: +For advanced or scripted rmpc checks: ```bash 999 rmpc verify @@ -144,7 +145,8 @@ MP3, FLAC, and M4A metadata changes create timestamped backups under: ~/.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 999 restore diff --git a/src/juice_lyrics/backup/manager.py b/src/juice_lyrics/backup/manager.py index 402feef..aa8a7b4 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -32,6 +32,15 @@ class BackupRecord: 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: diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index c1ee02f..97a541d 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -93,6 +93,7 @@ TrackSyncPlan, TrackSyncResult, execute_library_sync, + execute_library_sync_preview, get_library_sync_preview, plan_library_sync, ) @@ -161,6 +162,7 @@ "TrackSyncPlan", "TrackSyncResult", "execute_library_sync", + "execute_library_sync_preview", "execute_selected_download", "get_library_sync_preview", "get_catalogue_filters", diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 41d47af..e932b10 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -69,6 +69,7 @@ class LibraryTrack: artist: str | None = None album: str | None = None media_format: str = "MP3" + synchronized_source: bool = False @property def needs_attention(self) -> bool: @@ -80,6 +81,19 @@ def needs_attention(self) -> bool: or self.warning is not None ) + @property + def fully_covered(self) -> bool: + """Whether format-appropriate embedded lyrics and a synced sidecar are healthy.""" + + return ( + self.match_status is LibraryMatchStatus.MATCHED + and self.state_status is LibraryStateStatus.CURRENT + and self.synchronized_source + and self.lrc_status is LibraryLrcStatus.PRESENT + and self.lyric_status is not LibraryLyricStatus.NONE + and self.warning is None + ) + @dataclass(frozen=True, slots=True) class LibrarySnapshot: @@ -122,6 +136,30 @@ def external_lrc_count(self) -> int: 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.match_status is LibraryMatchStatus.MATCHED + and 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.match_status is LibraryMatchStatus.MATCHED + and 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: @@ -304,6 +342,7 @@ def get_library_snapshot( 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, ) ) diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index 4ac7877..e8ba1b3 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -3,7 +3,7 @@ import json import shutil from collections.abc import Callable, Mapping -from dataclasses import dataclass, field +from dataclasses import dataclass, field, replace from enum import Enum from pathlib import Path from typing import Any @@ -62,6 +62,7 @@ class LibrarySyncOptions: rmpc_config_path: Path | None = None duration_tolerance: float = 3.0 state_file: Path = STATE_FILE + selected_paths: tuple[Path, ...] = () def __post_init__(self) -> None: # Kept as a constructor field for compatibility with older callers. @@ -79,6 +80,7 @@ def from_settings( lyrics_dir: Path | None = None, rmpc_config_path: Path | None = None, state_file: Path = STATE_FILE, + selected_paths: tuple[Path, ...] = (), ) -> "LibrarySyncOptions": return cls( settings=settings, @@ -90,6 +92,7 @@ def from_settings( 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), ) @@ -257,6 +260,9 @@ def plan_library_sync( ) -> 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] = [] _emit(progress, SyncEventKind.SCAN_STARTED, total=len(files)) @@ -331,6 +337,8 @@ def get_library_sync_preview( state_file: Path = STATE_FILE, dependencies: LibrarySyncDependencies | None = None, progress: ProgressCallback | None = None, + refresh: bool = False, + selected_paths: tuple[Path, ...] = (), ) -> LibrarySyncPlan: """Build a non-mutating sync plan suitable for read-only frontends.""" @@ -339,13 +347,33 @@ def get_library_sync_preview( 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, ) 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, diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 1eebf28..76a0620 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -7,6 +7,8 @@ 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, @@ -35,7 +37,12 @@ project_download_queue, ) from ..services.library_status import LibrarySnapshot, LibraryStatus, get_library_snapshot, get_library_status -from ..services.library_sync import LibrarySyncPlan, get_library_sync_preview +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 @@ -56,6 +63,7 @@ CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] +LibraryExecutionProvider = Callable[..., LibrarySyncResult] SettingsSnapshotProvider = Callable[[Any], SettingsSnapshot] @@ -76,6 +84,11 @@ class JuiceLyricsApp(App[None]): Binding("q", "quit", "Quit", show=False, priority=True), ] + def _get_dom_base(self): + """Keep application-level queries scoped to the visible section.""" + + return self.screen + CSS = """ Screen { background: transparent; @@ -350,6 +363,53 @@ class JuiceLyricsApp(App[None]): background: transparent; } + MaintenanceDialog, + BackupBrowser, + RestoreDialog, + RmpcDialog { + 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; + } + + #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%; @@ -746,6 +806,10 @@ def __init__( download_all_execution_provider: Callable[..., Any] = execute_download_all, library_snapshot_provider: LibrarySnapshotProvider = get_library_snapshot, library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, + library_execution_provider: LibraryExecutionProvider = execute_library_sync_preview, + 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) @@ -777,6 +841,10 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: self.download_all_execution_provider = download_all_execution_provider self.library_snapshot_provider = library_snapshot_provider self.library_preview_provider = library_preview_provider + self.library_execution_provider = library_execution_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: @@ -804,6 +872,11 @@ def on_mount(self) -> None: self.settings, snapshot_provider=self.library_snapshot_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, ), "library", ) @@ -880,8 +953,9 @@ def action_show_help(self) -> None: ) elif section == "library": message = ( - "↑/↓ or j/k select tracks • / local search • Home/End first/last • " - "PgUp/PgDn move tracks • Enter details • s read-only sync preview • r refresh" + "Main: r Refresh · m Maintain lyrics · v Verify · b Backups · p Player integration\n" + "Tracks: ↑/↓ or j/k select · / search · Enter details · l refresh selected lyrics. " + "Maintenance, restore, and player setup always show a cancel-first confirmation." ) elif section == "settings": message = ( diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 2a77309..290e646 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -10,8 +10,10 @@ from textual import work from textual.binding import Binding from textual.containers import Container, Grid, Vertical, VerticalScroll -from textual.events import Key, Resize, ScreenResume +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 @@ -25,10 +27,18 @@ LibraryTrack, ) 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] 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): @@ -106,8 +116,250 @@ class PreviewOutcome: 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 + + +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 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 + problems} song{'s' if count + problems != 1 else ''} need attention\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.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.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.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.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.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.dismiss(None) + elif self.can_setup and not self._confirmed: self._confirmed = True; self.dismiss(self.snapshot) + + class LibraryScreen(HubScreen): - """Read-only local audio library browser and sync-plan preview.""" + """Local library browser and safe maintenance centre.""" BINDINGS = [Binding("/", "focus_search", "Search", show=False)] @@ -117,11 +369,21 @@ def __init__( *, snapshot_provider: SnapshotProvider, preview_provider: PreviewProvider, + execution_provider: ExecutionProvider, + backup_provider: BackupProvider, + restore_provider: RestoreProvider, + rmpc_status_provider: RmpcStatusProvider, + rmpc_setup_provider: RmpcSetupProvider, ) -> None: super().__init__("library", "Library") self.settings = settings self._snapshot_provider = snapshot_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.snapshot: LibrarySnapshot | None = None self.filtered_tracks: tuple[LibraryTrack, ...] = () self.selected_index = 0 @@ -131,10 +393,20 @@ def __init__( self._preview_worker: Worker[PreviewOutcome] | None = None self._pending_snapshot: SnapshotOutcome | 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 def compose_content(self) -> Iterable[Widget]: yield Static( - "Audio tracks 0 · Matched 0 · Unmatched 0 · Synced 0 · Plain 0 · No lyrics 0 · LRC 0 · Attention 0", + "0 songs · Fully covered 0 · Plain only 0 · Missing 0 · Unmatched 0\nFormats · MP3 0 · FLAC 0 · M4A 0", id="library-summary", markup=False, ) @@ -155,8 +427,8 @@ def compose_content(self) -> Iterable[Widget]: 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("Preview not generated · press s · Preview only — no files changed", id="library-preview", markup=False) - yield Static("r refresh · s preview · / search", id="library-position", markup=False) + yield Static("Choose Maintain lyrics to preview changes safely.", id="library-preview", markup=False) + yield Static("r Refresh · m Maintain lyrics · v Verify · b Backups · p Player · ? Help", id="library-position", markup=False) def action_focus_search(self) -> None: self.query_one("#library-query", Input).focus() @@ -167,7 +439,7 @@ def on_screen_resume(self, event: ScreenResume) -> None: self._apply_snapshot(outcome) elif self.snapshot is None and self._snapshot_worker is None: self.refresh_snapshot() - elif self.filtered_tracks: + else: self.call_after_refresh(self.set_focus, None) if self._pending_preview is not None: outcome, self._pending_preview = self._pending_preview, None @@ -178,10 +450,8 @@ def refresh_snapshot(self) -> 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( - "Preview not generated · press s · Preview only — no files changed" - ) - self._set_status("Refreshing local audio library…") + self.query_one("#library-preview", Static).update("Choose Maintain lyrics to preview changes safely.") + self._set_status("Verifying library…" if self._snapshot_action == "verify" else "Scanning library…") self._snapshot_worker = self._load_snapshot() def invalidate_snapshot(self) -> None: @@ -199,19 +469,26 @@ def _load_snapshot(self) -> SnapshotOutcome: except Exception as exc: return SnapshotOutcome(error=str(exc) or type(exc).__name__) - def generate_preview(self) -> None: + 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.query_one("#library-preview", Static).update( - "Generating sync preview… · Preview only — no files changed" - ) - self._preview_worker = self._load_preview() + 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) -> PreviewOutcome: + def _load_preview(self, selected_path: Path | None = None) -> PreviewOutcome: try: - return PreviewOutcome(self._preview_provider(self.settings)) + if selected_path is None: + return PreviewOutcome(self._preview_provider(self.settings)) + 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__) @@ -224,7 +501,7 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: else: self._pending_snapshot = outcome elif event.state is WorkerState.ERROR: - outcome = SnapshotOutcome(error="Library snapshot worker failed") + outcome = SnapshotOutcome(error="Library scan stopped unexpectedly") if self._can_render(): self._apply_snapshot(outcome) else: @@ -237,11 +514,42 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: else: self._pending_preview = outcome elif event.state is WorkerState.ERROR: - outcome = PreviewOutcome(error="Sync preview worker failed") + 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")): @@ -269,14 +577,30 @@ def _apply_snapshot(self, outcome: SnapshotOutcome) -> None: 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": + healthy = outcome.snapshot.total_track_count - outcome.snapshot.needs_attention_count + self._set_status( + f"Verification complete · {healthy} healthy · " + f"{outcome.snapshot.needs_attention_count} need attention " + f"(including {outcome.snapshot.unmatched_count} unmatched)" + ) + if outcome.snapshot.needs_attention_count: + self.query_one("#library-filter", Select).value = LibraryFilter.ATTENTION.value else: - self._set_status(f"Local audio library · {outcome.snapshot.library_path}") + self._set_status( + f"Library refreshed · {outcome.snapshot.total_track_count} " + f"song{'s' if outcome.snapshot.total_track_count != 1 else ''} found" + ) def _apply_preview(self, outcome: PreviewOutcome) -> None: if outcome.error or outcome.plan is None: @@ -297,8 +621,14 @@ def _apply_preview(self, outcome: PreviewOutcome) -> None: f"Unresolved {plan.unresolved_files} · No lyrics {plan.no_lyrics_files} · Errors {plan.analysis_failures}" f"{lrc_destination}" ) - self._set_status("Sync preview complete. No files were changed.") + 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: @@ -311,10 +641,10 @@ def _render_summary(self) -> None: if snapshot is None: return self.query_one("#library-summary", Static).update( - f"Audio tracks {snapshot.total_track_count} · Matched {snapshot.matched_count} · " - f"Unmatched {snapshot.unmatched_count} · Synced {snapshot.synced_count} · " - f"Plain {snapshot.plain_count} · No lyrics {snapshot.no_lyrics_count} · " - f"LRC {snapshot.external_lrc_count} · Attention {snapshot.needs_attention_count}" + f"{snapshot.total_track_count} songs · Fully covered {snapshot.fully_covered_count} · " + f"Plain only {snapshot.plain_only_count} · Missing {snapshot.missing_lyrics_count} · " + f"Unmatched {snapshot.unmatched_count}\nFormats · 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: @@ -391,6 +721,7 @@ def _render_details(self) -> None: f"LRC path {track.lrc_path or 'Not recorded'}", f"Library state {_state_label(track.state_status)}", f"Attention {'Yes' if track.needs_attention else 'No'}", + f"Coverage {'Fully covered' if track.fully_covered else _coverage_label(track)}", ] if track.warning: lines.extend(("", f"Warning {track.warning}")) @@ -399,9 +730,9 @@ def _render_details(self) -> None: def _update_position(self) -> None: if not self.filtered_tracks: - self.query_one("#library-position", Static).update("r refresh · s preview · / search") + self.query_one("#library-position", Static).update("r Refresh · m Maintain lyrics · v Verify · b Backups · p Player · ? Help") return - suffix = "Esc track list · PgUp/PgDn details" if self._details_mode else "Enter details · r refresh · s preview · / search" + suffix = "Esc track list · l Refresh lyrics · PgUp/PgDn details" if self._details_mode else "Enter details · r Refresh · m Maintain · v Verify · b Backups" self.query_one("#library-position", Static).update( f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" ) @@ -413,6 +744,17 @@ def on_key(self, event: Key) -> None: return if event.key == "s": self.generate_preview() + 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 == "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") @@ -467,6 +809,130 @@ def _set_status(self, message: str, *, error: bool = False) -> None: 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) + + @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} still need attention" + 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() + + 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() + + 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") @@ -516,6 +982,18 @@ def _state_label(status: LibraryStateStatus) -> str: }[status] +def _coverage_label(track: LibraryTrack) -> str: + if track.match_status is LibraryMatchStatus.UNMATCHED: + return "Needs a catalogue match" + if track.lyric_status is LibraryLyricStatus.NONE: + return "Missing lyrics" + if track.lrc_status is LibraryLrcStatus.MISSING: + return "Missing synced LRC" + 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" diff --git a/tests/test_library_sync_service.py b/tests/test_library_sync_service.py index 8b8e115..b8155c5 100644 --- a/tests/test_library_sync_service.py +++ b/tests/test_library_sync_service.py @@ -15,6 +15,7 @@ SyncEventKind, SyncLyricType, execute_library_sync, + execute_library_sync_preview, get_library_sync_preview, plan_library_sync, ) @@ -240,6 +241,57 @@ def test_frontend_preview_helper_is_dry_run_and_non_mutating(tmp_path): 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_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") diff --git a/tests/test_lrc_path_authority.py b/tests/test_lrc_path_authority.py index 15c05ab..4f454d7 100644 --- a/tests/test_lrc_path_authority.py +++ b/tests/test_lrc_path_authority.py @@ -5,6 +5,8 @@ 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, @@ -97,6 +99,7 @@ def test_current_cli_read_only_and_failed_write_flows_never_create_legacy_path( 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" diff --git a/tests/test_product_identity.py b/tests/test_product_identity.py index 6b77c97..25fe34b 100644 --- a/tests/test_product_identity.py +++ b/tests/test_product_identity.py @@ -3,9 +3,12 @@ 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 ( diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 5c2e522..bf75346 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -1,4 +1,5 @@ import asyncio +from datetime import datetime, timezone from pathlib import Path import sys from threading import Event @@ -21,11 +22,21 @@ QueueSnapshot, ) 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.settings_snapshot import ( + IntegrationSnapshot, + IntegrationStatus, + SettingsSnapshot, ) from juice_lyrics.tui import JuiceLyricsApp @@ -39,6 +50,8 @@ def _track( lrc: LibraryLrcStatus = LibraryLrcStatus.PRESENT, state: LibraryStateStatus = LibraryStateStatus.CURRENT, warning: str | None = None, + media_format: str = "MP3", + synchronized_source: bool = False, ) -> LibraryTrack: path = root / name lrc_path = path.with_suffix(".lrc") if lrc is not LibraryLrcStatus.NONE else None @@ -56,6 +69,8 @@ def _track( lrc_path=lrc_path, state_status=state, warning=warning, + media_format=media_format, + synchronized_source=synchronized_source, ) @@ -74,7 +89,7 @@ def _plan(settings: Settings, tracks: tuple[TrackSyncPlan, ...]) -> LibrarySyncP return LibrarySyncPlan(options, tracks, {"files": {}}) -def _app(tmp_path: Path, snapshot_provider, preview_provider=None) -> JuiceLyricsApp: +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( @@ -84,6 +99,7 @@ def _app(tmp_path: Path, snapshot_provider, preview_provider=None) -> JuiceLyric catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), library_snapshot_provider=snapshot_provider, library_preview_provider=preview_provider or (lambda settings: _plan(settings, ())), + **providers, ) @@ -127,9 +143,9 @@ async def scenario(): screen = await _open_library(app, pilot) assert screen.__class__.__name__ == "LibraryScreen" summary = _text(app, "#library-summary") - assert "Audio tracks 3" in summary and "Matched 2" in summary and "Unmatched 1" in summary - assert "Synced 1" in summary and "Plain 1" in summary and "No lyrics 1" in summary - assert "LRC 1" in summary and "Attention 2" in summary + assert "3 songs" in summary and "Unmatched 1" in summary + assert "Plain only 1" in summary and "Missing 0" in summary + assert "MP3 3" in summary and "FLAC 0" in summary and "M4A 0" in summary rows = _text(app, "#library-tracks") 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 @@ -322,7 +338,7 @@ async def scenario(): await current.wait() await pilot.pause() assert screen.selected_track.reference == keep.reference - assert "Preview not generated" in _text(app, "#library-preview") + assert "Maintain lyrics" in _text(app, "#library-preview") release_stale.set() await pilot.pause() assert "First.mp3" not in _text(app, "#library-tracks") @@ -369,7 +385,7 @@ async def scenario(): assert calls == 0 await pilot.press("s") await asyncio.to_thread(started.wait, 2) - assert "Generating sync preview" in _text(app, "#library-preview") + assert "Checking library needs" in _text(app, "#library-preview") await pilot.press("4") assert app.screen.id == "screen-downloads" await pilot.press("3") @@ -478,3 +494,240 @@ async def 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 "Plain only 0" 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_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: 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()) From 6367abd150594d1f36ff5d75b43d14a37b285b38 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Thu, 10 Sep 2026 00:25:14 +0100 Subject: [PATCH 37/62] Fix library lyric coverage classification --- PROJECT_CONTEXT.md | 5 +- README.md | 3 + docs/ARCHITECTURE.md | 8 ++ docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 6 +- docs/PROJECT_STATE.md | 6 +- docs/USER_GUIDE.md | 12 +++ src/juice_lyrics/cli.py | 5 +- src/juice_lyrics/library/matching.py | 13 ++- src/juice_lyrics/services/library_status.py | 71 +++++++------ src/juice_lyrics/services/library_sync.py | 24 ++++- src/juice_lyrics/tui/screens/library.py | 33 ++++-- tests/test_flac_support.py | 55 ++++++++++ tests/test_library_status.py | 105 +++++++++++++++++++- tests/test_library_sync_service.py | 67 +++++++++++++ tests/test_tui_library.py | 50 +++++++++- 15 files changed, 412 insertions(+), 51 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 03220bc..b54d5c5 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -300,13 +300,16 @@ The latest development checkpoint reports: * Library provides local track browsing, format-aware coverage summaries, read-only refresh/verification, confirmed lyric maintenance, selected-song refresh, valid backup browsing/restore, and rmpc verification/setup +* local lyric health is classified independently from catalogue identity; + timestamped adjacent LRC content is validated rather than inferred from file + existence, and healthy unmatched tracks do not require maintenance * Settings reports effective configuration, sidecar lyrics behavior, provenance where reliable, application paths, and rmpc integration without creating or changing files * TUI Download selected, Download queue, Retry, Remove, Clear queue, and Clear completed history are implemented; active-download cancel and general configuration editing are not implemented * advanced CLI remains available for scripting, diagnostics, internal records, and unusual recovery -* 328 automated tests pass across the suite +* 339 automated tests pass across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The product and primary executable are `999`. diff --git a/README.md b/README.md index d69796e..8a4ba84 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,9 @@ Your Juice WRLD folder is kept together: Open `999`, choose **Library**, then use **Refresh**, **Maintain lyrics**, **Verify**, or **Backups**. Maintenance always shows a non-mutating preview and a cancel-first confirmation before changing audio metadata or sidecars. +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 CLI remains available for scripting and automation. `999 sync` remembers files it has already processed, so unchanged verified files are skipped. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2be2288..2ba98ff 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -58,6 +58,14 @@ 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. + ## Lyrics layer Responsibilities: diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index cc0c1ce..a3e19c4 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -53,7 +53,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -328 passing tests. +339 passing tests. Completed and integrated: @@ -162,6 +162,10 @@ docs/ The project is in incremental v2 implementation. The backend remains stable. Mutating TUI actions are explicit and cancel-first. Library uses shared services for maintenance and restore; Settings remains read-only. +Library lyric health is independent of catalogue identity: format-appropriate +embedded lyrics plus a parsed timestamped sidecar can be fully covered even +when catalogue matching is unknown. Catalogue uncertainty remains visible but +does not itself create lyric attention. --- diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index dd8b526..00d5ac9 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -5,7 +5,7 @@ Backend services remain stable. The `999` Textual interface supports explicit confirmed single- and multi-song Browse Add to queue actions and selected or whole-queue downloads. The interface now prioritizes the streamlined Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 328 passing tests. +checkpoint has 339 passing tests. ## Current Branch v2-redesign @@ -31,6 +31,10 @@ v2-redesign read-only refresh/verification, non-mutating maintenance preview, confirmed shared-service execution, selected-song refresh, backup browsing/restore, and rmpc verification/setup. +- Library lyric health is independent of catalogue identity: valid local + embedded lyrics plus a genuinely timestamped adjacent sidecar can be fully + covered even when the catalogue match is unknown. Catalogue-unmatched totals + remain visible separately and do not inflate lyric-attention totals. - Settings configuration provenance, XDG/application paths, sidecar external-lyrics behavior, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. - Local FLAC files are recursively discovered and matched using native title, diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 4ee6d53..ae43951 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -52,6 +52,14 @@ Open `999`, choose **Library**, and use: Select a song and press `l` to refresh lyrics for only that song. The CLI equivalent, `999 sync`, remains useful for scripting and automation. +**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 healthy track may still show **Catalogue match: +Unknown**; that only means automatic refresh cannot identify a safe catalogue +record yet. The Library shows that count separately from songs needing lyric +attention. + ## Check health ```bash @@ -60,6 +68,10 @@ equivalent, `999 sync`, remains useful for scripting and automation. Use this when you simply want to know whether the library is up to date. +`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. + ## Find songs in the API catalogue ```bash diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 1cc7caa..e1a08a7 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -929,7 +929,10 @@ 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 diff --git a/src/juice_lyrics/library/matching.py b/src/juice_lyrics/library/matching.py index faf35a1..3b45eae 100644 --- a/src/juice_lyrics/library/matching.py +++ b/src/juice_lyrics/library/matching.py @@ -36,6 +36,17 @@ 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 parse_length(value: str) -> float | None: if not value: return None @@ -61,7 +72,7 @@ def local_duration(path: Path) -> float | None: def search_title_for(path: Path) -> str: raw_title = tagged_matching_title(path) if is_tagged_container(path) else path.stem - stripped = strip_version(raw_title) + stripped = strip_feature_credit(strip_version(raw_title)) return CANONICAL_SEARCH.get(normalize(stripped), stripped) diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index e932b10..9627b2d 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -17,7 +17,7 @@ media_format, read_tagged_metadata, ) -from ..lyrics.engine import verify_file +from ..lyrics.engine import parse_synced_lyrics, verify_file from ..lyrics.sidecar import sidecar_lrc_path from ..state import sha256_file @@ -39,6 +39,7 @@ class LibraryMatchStatus(str, Enum): class LibraryLrcStatus(str, Enum): PRESENT = "present" MISSING = "missing" + INVALID = "invalid" NONE = "none" @@ -73,25 +74,29 @@ class LibraryTrack: @property def needs_attention(self) -> bool: - return ( - self.match_status is LibraryMatchStatus.UNMATCHED - or self.lyric_status is LibraryLyricStatus.NONE - or self.lrc_status is LibraryLrcStatus.MISSING - or self.state_status is not LibraryStateStatus.CURRENT - or self.warning is not None - ) + 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.match_status is LibraryMatchStatus.MATCHED - and self.state_status is LibraryStateStatus.CURRENT - and self.synchronized_source - and self.lrc_status is LibraryLrcStatus.PRESENT - and self.lyric_status is not LibraryLyricStatus.NONE - and self.warning is None + 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 + ) + ) ) @@ -143,19 +148,14 @@ def fully_covered_count(self) -> int: @property def plain_only_count(self) -> int: return sum( - track.match_status is LibraryMatchStatus.MATCHED - and track.lyric_status is LibraryLyricStatus.PLAIN + 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.match_status is LibraryMatchStatus.MATCHED - and track.lyric_status is LibraryLyricStatus.NONE - for track in self.tracks - ) + 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) @@ -202,6 +202,16 @@ def _read_state_snapshot(path: Path) -> tuple[dict[str, Any], tuple[str, ...]]: 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 get_library_snapshot( settings: Settings, *, @@ -298,17 +308,15 @@ def get_library_snapshot( } ) adjacent_lrc = sidecar_lrc_path(path) - lrc_path = ( - adjacent_lrc - if lyric_status is LibraryLyricStatus.SYNCED - or expected_synced - or (is_tagged_container(path) and adjacent_lrc.is_file()) - else None - ) + sidecar_exists = adjacent_lrc.is_file() + 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 lrc_path.is_file(): - lrc_status = LibraryLrcStatus.PRESENT + 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.") @@ -380,7 +388,8 @@ def get_library_status( entry = state_files.get(relative) if not isinstance(entry, dict) or entry.get("sha256") != sha256_file(path): new_or_changed += 1 - if sidecar_lrc_path(path).is_file() and ( + 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 diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index e8ba1b3..b7ed168 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -63,6 +63,7 @@ class LibrarySyncOptions: 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. @@ -81,6 +82,7 @@ def from_settings( rmpc_config_path: Path | None = None, state_file: Path = STATE_FILE, selected_paths: tuple[Path, ...] = (), + protected_paths: tuple[Path, ...] = (), ) -> "LibrarySyncOptions": return cls( settings=settings, @@ -93,6 +95,7 @@ def from_settings( 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), ) @@ -247,7 +250,12 @@ def _state_is_current( "FLAC_LYRICS_SYNCED", "M4A_LYRICS_SYNCED", }: - if not sidecar_lrc_path(path).is_file(): + 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 @@ -265,8 +273,20 @@ def plan_library_sync( 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} _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): _emit( progress, @@ -339,6 +359,7 @@ def get_library_sync_preview( 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.""" @@ -352,6 +373,7 @@ def get_library_sync_preview( 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) diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 290e646..c8e196c 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -481,7 +481,20 @@ def generate_preview(self, *, action: str = "preview", selected_path: Path | Non def _load_preview(self, selected_path: Path | None = None) -> PreviewOutcome: try: if selected_path is None: - return PreviewOutcome(self._preview_provider(self.settings)) + 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, @@ -643,7 +656,8 @@ def _render_summary(self) -> None: self.query_one("#library-summary", Static).update( f"{snapshot.total_track_count} songs · Fully covered {snapshot.fully_covered_count} · " f"Plain only {snapshot.plain_only_count} · Missing {snapshot.missing_lyrics_count} · " - f"Unmatched {snapshot.unmatched_count}\nFormats · MP3 {snapshot.format_count('MP3')} · " + f"Need attention {snapshot.needs_attention_count}\nCatalogue unmatched {snapshot.unmatched_count} · " + f"MP3 {snapshot.format_count('MP3')} · " f"FLAC {snapshot.format_count('FLAC')} · M4A {snapshot.format_count('M4A')}" ) @@ -714,7 +728,7 @@ def _render_details(self) -> None: f"Album {track.album or 'Not available'}", f"Relative path {track.relative_path}", f"Full path {track.path}", - f"Matched {track.matched_title or _match_label(track)}", + f"Catalogue match {track.matched_title or _match_label(track)}", f"Duration {_duration(track.duration_seconds)}", f"Lyrics {_lyric_label(track.lyric_status)}", f"External LRC {_lrc_label(track.lrc_status)}", @@ -725,6 +739,8 @@ def _render_details(self) -> None: ] 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(("", "Sync preview", _track_preview_text(self.preview, track.path))) details.update(Text("\n".join(lines), overflow="ellipsis")) @@ -954,7 +970,7 @@ def _matches_filter(track: LibraryTrack, selected: LibraryFilter) -> bool: def _match_label(track: LibraryTrack) -> str: - return "Matched" if track.match_status is LibraryMatchStatus.MATCHED else "Unmatched" + return "Matched" if track.match_status is LibraryMatchStatus.MATCHED else "Unknown" def _lyric_label(status: LibraryLyricStatus) -> str: @@ -969,6 +985,7 @@ def _lrc_label(status: LibraryLrcStatus) -> str: return { LibraryLrcStatus.PRESENT: "Present", LibraryLrcStatus.MISSING: "Missing", + LibraryLrcStatus.INVALID: "Invalid", LibraryLrcStatus.NONE: "None", }[status] @@ -983,12 +1000,12 @@ def _state_label(status: LibraryStateStatus) -> str: def _coverage_label(track: LibraryTrack) -> str: - if track.match_status is LibraryMatchStatus.UNMATCHED: - return "Needs a catalogue match" + if track.fully_covered: + return "Fully covered" if track.lyric_status is LibraryLyricStatus.NONE: return "Missing lyrics" - if track.lrc_status is LibraryLrcStatus.MISSING: - return "Missing synced LRC" + 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" diff --git a/tests/test_flac_support.py b/tests/test_flac_support.py index 467996e..6acb398 100644 --- a/tests/test_flac_support.py +++ b/tests/test_flac_support.py @@ -163,6 +163,61 @@ def test_flac_matching_reuses_normal_version_title_and_duration_scoring(tmp_path 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 diff --git a/tests/test_library_status.py b/tests/test_library_status.py index bc2cc07..d5ffaa0 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -2,9 +2,12 @@ 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, @@ -195,7 +198,7 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa assert snapshot.plain_count == 1 assert snapshot.no_lyrics_count == 1 assert snapshot.external_lrc_count == 1 - assert snapshot.needs_attention_count == 2 + assert snapshot.needs_attention_count == 1 assert snapshot.tracks[0].match_status is LibraryMatchStatus.MATCHED assert snapshot.tracks[0].lyric_status is LibraryLyricStatus.SYNCED assert snapshot.tracks[0].lrc_status is LibraryLrcStatus.PRESENT @@ -203,6 +206,106 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa assert snapshot.tracks[1].state_status is LibraryStateStatus.CHANGED 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): diff --git a/tests/test_library_sync_service.py b/tests/test_library_sync_service.py index b8155c5..39caa97 100644 --- a/tests/test_library_sync_service.py +++ b/tests/test_library_sync_service.py @@ -264,6 +264,73 @@ def test_frontend_preview_can_scope_one_track_and_force_refresh(tmp_path): assert calls == [("Selected", True)] +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") diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index bf75346..661a0ee 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -98,7 +98,7 @@ def _app(tmp_path: Path, snapshot_provider, preview_provider=None, **providers) queue_snapshot_provider=lambda: QueueSnapshot((), 0, 0, 0, 0, 0), catalogue_filters_provider=lambda *args, **kwargs: CatalogueFilterMetadata((), ()), library_snapshot_provider=snapshot_provider, - library_preview_provider=preview_provider or (lambda settings: _plan(settings, ())), + library_preview_provider=preview_provider or (lambda settings, **kwargs: _plan(settings, ())), **providers, ) @@ -143,8 +143,9 @@ async def scenario(): screen = await _open_library(app, pilot) assert screen.__class__.__name__ == "LibraryScreen" summary = _text(app, "#library-summary") - assert "3 songs" in summary and "Unmatched 1" in summary - assert "Plain only 1" in summary and "Missing 0" in summary + assert "3 songs" in summary and "Catalogue unmatched 1" in summary + assert "Plain only 1" in summary and "Missing 1" in summary + assert "Need attention 1" in summary assert "MP3 3" in summary and "FLAC 0" in summary and "M4A 0" in summary rows = _text(app, "#library-tracks") assert rows.index("A Synced") < rows.index("B Plain") < rows.index("C Unknown") @@ -154,7 +155,7 @@ async def scenario(): await pilot.press("down", "j") assert screen.selected_track.reference == unmatched.reference details = _text(app, "#library-details") - assert "Unmatched" in details and "No lyrics" in details + assert "Catalogue match Unknown" in details and "No lyrics" in details assert "Library state New" in details and "Attention Yes" in details assert "Recorded LRC is missing" in details await pilot.press("up", "k", "end", "home") @@ -519,6 +520,45 @@ async def scenario(): 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.NEW, + ) + 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 "Need attention 0" in summary + assert "Catalogue unmatched 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 "Attention No" 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) @@ -541,7 +581,7 @@ async def scenario(): app = _app( tmp_path, lambda settings: _snapshot(root, track), - lambda settings: plan, + lambda settings, **kwargs: plan, library_execution_provider=execute, ) async with app.run_test() as pilot: From a5de73b71b2936b6d747fc76aa7af2ed79fd0240 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 13 Sep 2026 12:10:55 +0100 Subject: [PATCH 38/62] Improve catalogue matching and identity rebuilding --- PROJECT_CONTEXT.md | 8 +- README.md | 28 +- docs/ARCHITECTURE.md | 20 + docs/DECISIONS.md | 23 ++ docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 4 +- docs/PROJECT_STATE.md | 12 +- docs/USER_GUIDE.md | 52 +++ src/juice_lyrics/cli.py | 77 ++++ src/juice_lyrics/library/matching.py | 281 ++++++++++++- src/juice_lyrics/services/__init__.py | 34 ++ src/juice_lyrics/services/identity_rebuild.py | 265 ++++++++++++ src/juice_lyrics/services/library_identity.py | 112 +++++ src/juice_lyrics/services/library_status.py | 18 +- src/juice_lyrics/services/library_sync.py | 21 +- .../services/state_maintenance.py | 144 +++++++ src/juice_lyrics/state.py | 118 +++++- src/juice_lyrics/tui/app.py | 22 +- src/juice_lyrics/tui/screens/library.py | 300 +++++++++++++- tests/test_core.py | 40 ++ tests/test_identity_rebuild.py | 389 ++++++++++++++++++ tests/test_library_identity.py | 211 ++++++++++ tests/test_library_status.py | 41 ++ tests/test_matching.py | 257 ++++++++++++ tests/test_state_maintenance.py | 120 ++++++ tests/test_tui_library.py | 169 +++++++- 25 files changed, 2721 insertions(+), 45 deletions(-) create mode 100644 src/juice_lyrics/services/identity_rebuild.py create mode 100644 src/juice_lyrics/services/library_identity.py create mode 100644 src/juice_lyrics/services/state_maintenance.py create mode 100644 tests/test_identity_rebuild.py create mode 100644 tests/test_library_identity.py create mode 100644 tests/test_matching.py create mode 100644 tests/test_state_maintenance.py diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index b54d5c5..787cd89 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -303,13 +303,19 @@ The latest development checkpoint reports: * local lyric health is classified independently from catalogue identity; timestamped adjacent LRC content is validated rather than inferred from file existence, and healthy unmatched tracks do not require maintenance +* Library Refresh can backfill confident catalogue identity for new MP3, FLAC, + and M4A files without changing media; state cleanup remains an explicit, + preview-first operation with a safety copy +* full catalogue identity rebuilding is preview-first, state-only, backed up, + and atomic; it is available through advanced Library help and CLI state + maintenance without changing audio or lyrics * Settings reports effective configuration, sidecar lyrics behavior, provenance where reliable, application paths, and rmpc integration without creating or changing files * TUI Download selected, Download queue, Retry, Remove, Clear queue, and Clear completed history are implemented; active-download cancel and general configuration editing are not implemented * advanced CLI remains available for scripting, diagnostics, internal records, and unusual recovery -* 339 automated tests pass across the suite +* 382 automated tests pass across the suite The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` on branch `v2-redesign`. The product and primary executable are `999`. diff --git a/README.md b/README.md index 8a4ba84..5d74604 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,9 @@ a cancel-first confirmation before changing audio metadata or sidecars. 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. +Library **Refresh** shows local health first, then identifies newly discovered +tracks in the background and saves only confident catalogue identities. It +does not rewrite audio, lyrics, backups, or rmpc configuration. The CLI remains available for scripting and automation. `999 sync` remembers files it has already processed, so unchanged verified files are skipped. @@ -122,6 +125,8 @@ Before major changes, read `PROJECT_CONTEXT.md`, `docs/ROADMAP.md`, and `docs/AR | `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 @@ -141,6 +146,19 @@ 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. + +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 The matcher intentionally uses several signals rather than trusting a title alone: @@ -151,9 +169,17 @@ 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 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2ba98ff..91f8293 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -66,6 +66,12 @@ 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. +Library Refresh uses a shared catalogue-identity backfill service after the +local snapshot is rendered. The service reuses compatible persisted identities, +uses the normal query preparation and conservative matcher for unknown MP3, +FLAC, and M4A files, and atomically merges only confident `song_id`/`api_name` +results into the existing state schema. It never infers lyric-processing state. + ## Lyrics layer Responsibilities: @@ -117,12 +123,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: diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index f888ead..4ddfe38 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -166,6 +166,29 @@ 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. Library Refresh 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. + +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. + +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 diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index a3e19c4..e328128 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -53,7 +53,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -339 passing tests. +382 passing tests. Completed and integrated: @@ -89,6 +89,8 @@ eligible queued song, a Library maintenance centre with local track browsing, filters, details, read-only refresh/verification, confirmed lyric maintenance, backup/restore, and rmpc checks, and a read-only Settings screen with effective configuration, paths, provenance, and rmpc state. +Library Help also exposes a cancel-first, state-only catalogue identity rebuild +for rerunning the latest matcher across current MP3, FLAC, and M4A files. All five primary TUI sections are functional. Browse supports confirmed single and batch queue additions. Downloads supports confirmed Download selected, diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 00d5ac9..19de416 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -5,7 +5,7 @@ Backend services remain stable. The `999` Textual interface supports explicit confirmed single- and multi-song Browse Add to queue actions and selected or whole-queue downloads. The interface now prioritizes the streamlined Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 339 passing tests. +checkpoint has 382 passing tests. ## Current Branch v2-redesign @@ -35,6 +35,16 @@ v2-redesign embedded lyrics plus a genuinely timestamped adjacent sidecar can be fully covered even when the catalogue match is unknown. Catalogue-unmatched totals remain visible separately and do not inflate lyric-attention totals. +- Library Refresh now backfills confident catalogue identities for newly + discovered MP3, FLAC, and M4A files through the shared conservative matcher, + without modifying audio or lyrics; offline failure leaves local health usable. +- `999 state clean` previews clearly stale external records, while explicit + `--yes` creates a timestamped state safety copy and atomically prunes only the + reviewed records. Valid relative history and ambiguous duplicates are kept. +- Catalogue identities can be rebuilt for all current tracks through an + explicit cancel-first Library action or `999 state rebuild-identities`. + Rebuilds preserve lyric state, audit changed IDs, back up state, and commit + atomically without touching media. - Settings configuration provenance, XDG/application paths, sidecar external-lyrics behavior, rmpc integration status, and current capability limitations. - Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. - Local FLAC files are recursively discovered and matched using native title, diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index ae43951..1eb1421 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -49,6 +49,17 @@ Open `999`, choose **Library**, and use: * **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. + +Refresh displays local lyric health immediately, then checks unknown tracks +against the catalogue in the background. Only confident identities are saved. +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**. + Select a song and press `l` to refresh lyrics for only that song. The CLI equivalent, `999 sync`, remains useful for scripting and automation. @@ -72,6 +83,47 @@ Use this when you simply want to know whether the library is up to date. uncertain** count means identity could not be established safely; it does not by itself mean that local lyrics are missing or broken. +## Clean clearly stale state records + +Preview first: + +```bash +999 state clean +``` + +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, ignores stale external records, makes a complete state +backup, and commits the result atomically. Ambiguous tracks become Unknown. +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 diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index e1a08a7..9147958 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -701,6 +701,14 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: 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, +) def search_api(settings: Settings, title: str, refresh: bool = False) -> list[dict[str, Any]]: @@ -1104,6 +1112,62 @@ 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"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) + 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 music_root = Path(settings.music_dir).expanduser() @@ -1623,6 +1687,18 @@ 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.") return parser @@ -1652,6 +1728,7 @@ def main(argv: list[str] | None = None) -> int: if args.action == "verify": return command_rmpc_verify(args, settings, use_color) 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/library/matching.py b/src/juice_lyrics/library/matching.py index 3b45eae..68f595e 100644 --- a/src/juice_lyrics/library/matching.py +++ b/src/juice_lyrics/library/matching.py @@ -1,6 +1,7 @@ from __future__ import annotations import re +from dataclasses import dataclass from pathlib import Path from typing import Any @@ -18,6 +19,45 @@ "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", + "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"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("’", "'") @@ -27,6 +67,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 @@ -47,6 +95,14 @@ def strip_feature_credit(text: str) -> str: ).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 @@ -70,6 +126,96 @@ def local_duration(path: Path) -> float | None: 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: raw_title = tagged_matching_title(path) if is_tagged_container(path) else path.stem stripped = strip_feature_credit(strip_version(raw_title)) @@ -84,6 +230,9 @@ def score_candidate(settings: Settings, path: Path, candidate: dict[str, Any], s 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: @@ -93,6 +242,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): @@ -100,25 +260,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 @@ -130,7 +329,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/services/__init__.py b/src/juice_lyrics/services/__init__.py index 97a541d..0b1562e 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -81,6 +81,20 @@ get_library_snapshot, get_library_status, ) +from .library_identity import ( + IdentityBackfillDependencies, + IdentityBackfillResult, + backfill_catalogue_identities, +) +from .identity_rebuild import ( + IdentityChange, + IdentityRebuildDependencies, + IdentityRebuildPlan, + IdentityRebuildProgress, + IdentityRebuildResult, + execute_catalogue_identity_rebuild, + plan_catalogue_identity_rebuild, +) from .library_sync import ( LibrarySyncDependencies, LibrarySyncOptions, @@ -106,6 +120,12 @@ SettingsSource, get_settings_snapshot, ) +from .state_maintenance import ( + StateCleanupResult, + StaleStatePlan, + execute_stale_state_cleanup, + plan_stale_state_cleanup, +) __all__ = [ "CatalogueSearchResult", @@ -121,6 +141,8 @@ "DownloadExecutionStatus", "DownloadProgress", "LibraryStatus", + "IdentityBackfillDependencies", + "IdentityBackfillResult", "LibraryLrcStatus", "LibraryLyricStatus", "LibraryMatchStatus", @@ -161,8 +183,18 @@ "SyncLyricType", "TrackSyncPlan", "TrackSyncResult", + "StateCleanupResult", + "StaleStatePlan", + "IdentityChange", + "IdentityRebuildDependencies", + "IdentityRebuildPlan", + "IdentityRebuildProgress", + "IdentityRebuildResult", + "backfill_catalogue_identities", "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", @@ -174,6 +206,8 @@ "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", diff --git a/src/juice_lyrics/services/identity_rebuild.py b/src/juice_lyrics/services/identity_rebuild.py new file mode 100644 index 0000000..8caa2ba --- /dev/null +++ b/src/juice_lyrics/services/identity_rebuild.py @@ -0,0 +1,265 @@ +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 .state_maintenance import plan_stale_state_cleanup + + +IDENTITY_FIELDS = ("song_id", "api_name") + + +@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 + + +@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, +) -> 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 {}) + 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_identity.py b/src/juice_lyrics/services/library_identity.py new file mode 100644 index 0000000..d364508 --- /dev/null +++ b/src/juice_lyrics/services/library_identity.py @@ -0,0 +1,112 @@ +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass +from pathlib import Path +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 read_state_file, resolve_state_entry, sha256_file, write_state_file +from .library_status import LibraryTrack + + +@dataclass(frozen=True, slots=True) +class IdentityBackfillResult: + inspected: int + reused: int + identified: int + unknown: int + failed: int + errors: 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 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) + state = dependencies.state_reader(state_path) + 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] = [] + + for track in tracks: + _, existing = resolve_state_entry(files, track.relative_path, relative_paths) + if _has_identity(existing): + reused += 1 + continue + try: + 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 + + reference = str(track.relative_path) + current = files.get(reference) + entry = dict(current) if isinstance(current, Mapping) else {} + entry.update( + { + "sha256": dependencies.hasher(track.path), + "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__}") + + if identified: + dependencies.state_writer(state_path, state) + return IdentityBackfillResult( + inspected=len(tracks), + reused=reused, + identified=identified, + unknown=unknown, + failed=failed, + errors=tuple(errors), + ) diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 9627b2d..455c94e 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -19,7 +19,7 @@ ) from ..lyrics.engine import parse_synced_lyrics, verify_file from ..lyrics.sidecar import sidecar_lrc_path -from ..state import sha256_file +from ..state import resolve_state_entry, sha256_file LyricsVerifier = Callable[[Path], tuple[bool, str]] DurationReader = Callable[[Path], float | None] @@ -234,12 +234,19 @@ def get_library_snapshot( state, warnings = _read_state_snapshot(Path(state_file)) state_files = state.get("files", {}) + discovered = find_mp3s(settings) + relative_paths = tuple(path.relative_to(library_path) for path in discovered) tracks: list[LibraryTrack] = [] - for path in find_mp3s(settings): + for path in discovered: relative_path = path.relative_to(library_path) reference = str(relative_path) - raw_entry = state_files.get(reference) - entry = raw_entry if isinstance(raw_entry, dict) else None + 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 = resolved_entry if isinstance(resolved_entry, dict) else None track_warnings: list[str] = [] metadata: AudioMetadata | None = None metadata_safe_for_matching = True @@ -374,6 +381,7 @@ def get_library_status( 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: @@ -385,7 +393,7 @@ def get_library_status( missing += 1 relative = str(path.relative_to(library_path)) - entry = state_files.get(relative) + _, 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) diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index b7ed168..27f6ac2 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -17,7 +17,7 @@ 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, save_state, sha256_file +from ..state import load_state, resolve_state_entry, save_state, sha256_file from ..backup.manager import now_iso @@ -233,8 +233,16 @@ def _state_is_current( path: Path, options: LibrarySyncOptions, dependencies: LibrarySyncDependencies, + library_relative_paths: tuple[Path, ...] = (), ) -> bool: - entry = state.get("files", {}).get(str(path.relative_to(options.music_dir))) + 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: @@ -274,6 +282,7 @@ def plan_library_sync( 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: @@ -287,7 +296,13 @@ def plan_library_sync( message="locally covered", ) continue - if not options.refresh and _state_is_current(state, path, options, dependencies): + if not options.refresh and _state_is_current( + state, + path, + options, + dependencies, + relative_paths, + ): _emit( progress, SyncEventKind.TRACK_INSPECTED, 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..76d66bc 100644 --- a/src/juice_lyrics/state.py +++ b/src/juice_lyrics/state.py @@ -1,22 +1,112 @@ 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: + 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: - 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} + 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 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 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() +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() diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 76a0620..6417701 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -37,6 +37,13 @@ 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.identity_rebuild import ( + IdentityRebuildPlan, + IdentityRebuildResult, + execute_catalogue_identity_rebuild, + plan_catalogue_identity_rebuild, +) from ..services.library_sync import ( LibrarySyncPlan, LibrarySyncResult, @@ -62,6 +69,9 @@ CatalogueDetailsProvider = Callable[..., SongDetails | None] CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] +LibraryIdentityProvider = Callable[..., IdentityBackfillResult] +IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] +IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] LibraryExecutionProvider = Callable[..., LibrarySyncResult] SettingsSnapshotProvider = Callable[[Any], SettingsSnapshot] @@ -805,6 +815,9 @@ def __init__( 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_identity_provider: LibraryIdentityProvider = backfill_catalogue_identities, + identity_rebuild_plan_provider: IdentityRebuildPlanProvider = plan_catalogue_identity_rebuild, + identity_rebuild_execution_provider: IdentityRebuildExecutionProvider = execute_catalogue_identity_rebuild, library_preview_provider: LibraryPreviewProvider = get_library_sync_preview, library_execution_provider: LibraryExecutionProvider = execute_library_sync_preview, backup_provider: Callable[[], tuple[BackupRecord, ...]] = list_backups, @@ -840,6 +853,9 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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_identity_provider = library_identity_provider + self.identity_rebuild_plan_provider = identity_rebuild_plan_provider + self.identity_rebuild_execution_provider = identity_rebuild_execution_provider self.library_preview_provider = library_preview_provider self.library_execution_provider = library_execution_provider self.backup_provider = backup_provider @@ -871,6 +887,9 @@ def on_mount(self) -> None: LibraryScreen( self.settings, snapshot_provider=self.library_snapshot_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, @@ -954,8 +973,9 @@ def action_show_help(self) -> None: elif section == "library": message = ( "Main: r Refresh · m Maintain lyrics · v Verify · b Backups · p Player integration\n" + "Advanced: i Rebuild catalogue matches\n" "Tracks: ↑/↓ or j/k select · / search · Enter details · l refresh selected lyrics. " - "Maintenance, restore, and player setup always show a cancel-first confirmation." + "Maintenance, identity rebuild, restore, and player setup always show a cancel-first confirmation." ) elif section == "settings": message = ( diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index c8e196c..2d81c57 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -26,6 +26,12 @@ LibraryStateStatus, LibraryTrack, ) +from ...services.library_identity import IdentityBackfillResult +from ...services.identity_rebuild import ( + IdentityRebuildPlan, + IdentityRebuildProgress, + IdentityRebuildResult, +) from ...services.library_sync import LibrarySyncPlan, MatchOutcome, SyncLyricType from ...services.library_sync import LibrarySyncResult, SyncEvent, SyncEventKind from ...backup.manager import BackupRecord @@ -33,6 +39,9 @@ from .base import HubScreen SnapshotProvider = Callable[[Any], LibrarySnapshot] +IdentityProvider = Callable[..., IdentityBackfillResult] +IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] +IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] PreviewProvider = Callable[[Any], LibrarySyncPlan] ExecutionProvider = Callable[..., LibrarySyncResult] BackupProvider = Callable[[], tuple[BackupRecord, ...]] @@ -110,6 +119,12 @@ class SnapshotOutcome: 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 @@ -128,6 +143,18 @@ class BackupOutcome: 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 + + class LibraryDialogAction(Static): can_focus = True @@ -218,6 +245,79 @@ def _activate(self) -> None: 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"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.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.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.""" @@ -368,6 +468,9 @@ def __init__( settings: Any, *, snapshot_provider: SnapshotProvider, + identity_provider: IdentityProvider, + identity_rebuild_plan_provider: IdentityRebuildPlanProvider, + identity_rebuild_execution_provider: IdentityRebuildExecutionProvider, preview_provider: PreviewProvider, execution_provider: ExecutionProvider, backup_provider: BackupProvider, @@ -378,6 +481,9 @@ def __init__( super().__init__("library", "Library") self.settings = settings self._snapshot_provider = snapshot_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 @@ -390,8 +496,12 @@ def __init__( self.preview: LibrarySyncPlan | None = None self._details_mode = False self._snapshot_worker: Worker[SnapshotOutcome] | None = None + self._identity_worker: Worker[IdentityOutcome] | 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 @@ -403,10 +513,13 @@ def __init__( 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 def compose_content(self) -> Iterable[Widget]: yield Static( - "0 songs · Fully covered 0 · Plain only 0 · Missing 0 · Unmatched 0\nFormats · MP3 0 · FLAC 0 · M4A 0", + "0 songs · Fully covered 0 · Plain only 0 · Missing 0 · Need attention 0\n" + "Catalogue unmatched 0 · MP3 0 · FLAC 0 · M4A 0", id="library-summary", markup=False, ) @@ -438,19 +551,23 @@ def on_screen_resume(self, event: ScreenResume) -> 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() + self.refresh_snapshot(identify=False) else: self.call_after_refresh(self.set_focus, None) 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) - def refresh_snapshot(self) -> None: + def refresh_snapshot(self, *, identify: bool = True) -> None: 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("Choose Maintain lyrics to preview changes safely.") + 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() @@ -458,8 +575,12 @@ 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._preview_worker = None self._pending_snapshot = None + self._pending_identity = None self._pending_preview = None @work(thread=True, exclusive=True, group="library-snapshot", exit_on_error=False) @@ -519,6 +640,33 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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.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.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._preview_worker: if event.state is WorkerState.SUCCESS: outcome = event.worker.result @@ -604,8 +752,8 @@ def _apply_snapshot(self, outcome: SnapshotOutcome) -> None: healthy = outcome.snapshot.total_track_count - outcome.snapshot.needs_attention_count self._set_status( f"Verification complete · {healthy} healthy · " - f"{outcome.snapshot.needs_attention_count} need attention " - f"(including {outcome.snapshot.unmatched_count} unmatched)" + f"{outcome.snapshot.needs_attention_count} need attention · " + f"{outcome.snapshot.unmatched_count} catalogue unknown" ) if outcome.snapshot.needs_attention_count: self.query_one("#library-filter", Select).value = LibraryFilter.ATTENTION.value @@ -614,6 +762,61 @@ def _apply_snapshot(self, outcome: SnapshotOutcome) -> None: 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: @@ -769,6 +972,8 @@ def on_key(self, event: Key) -> None: self._open_backups() elif event.key == "p": self._check_rmpc() + elif event.key == "i": + self._preview_identity_rebuild() 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: @@ -836,6 +1041,87 @@ def _maintenance_dialog_closed(self, plan: LibrarySyncPlan | None) -> None: 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: @@ -873,7 +1159,7 @@ def _apply_execution(self, outcome: ExecutionOutcome) -> None: self.snapshot = None self.preview = None self._snapshot_action = "scan" - self.refresh_snapshot() + self.refresh_snapshot(identify=False) def _open_backups(self) -> None: if self._backup_worker is None: @@ -924,7 +1210,7 @@ def _apply_restore(self, count: int | None, error: str | None) -> None: ) self.snapshot = None self._snapshot_action = "scan" - self.refresh_snapshot() + self.refresh_snapshot(identify=False) def _check_rmpc(self) -> None: if self._rmpc_worker is None: diff --git a/tests/test_core.py b/tests/test_core.py index eee49b3..7b9fbe5 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -307,3 +307,43 @@ def test_library_setup_never_rewrites_rmpc_configuration(tmp_path, monkeypatch): 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_identity_rebuild.py b/tests/test_identity_rebuild.py new file mode 100644 index 0000000..c216400 --- /dev/null +++ b/tests/test_identity_rebuild.py @@ -0,0 +1,389 @@ +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, +) + + +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(), + ) + + +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_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})] + assert "96383 (10 Feet) -> 94102 (10 Feet)" in output + assert "Audio, embedded lyrics, sidecars, and rmpc configuration were not changed" in output diff --git a/tests/test_library_identity.py b/tests/test_library_identity.py new file mode 100644 index 0000000..2ab8a00 --- /dev/null +++ b/tests/test_library_identity.py @@ -0,0 +1,211 @@ +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 + + +@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_status.py b/tests/test_library_status.py index d5ffaa0..c92e466 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -362,6 +362,47 @@ def test_library_status_ignores_unrelated_centralized_lrc(tmp_path): 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") diff --git a/tests/test_matching.py b/tests/test_matching.py new file mode 100644 index 0000000..56e4c41 --- /dev/null +++ b/tests/test_matching.py @@ -0,0 +1,257 @@ +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 + + +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_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_library.py b/tests/test_tui_library.py index 661a0ee..8ed0785 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -2,7 +2,7 @@ from datetime import datetime, timezone from pathlib import Path import sys -from threading import Event +from threading import Event, get_ident sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) @@ -19,6 +19,11 @@ LibraryStateStatus, LibraryStatus, LibraryTrack, + IdentityBackfillResult, + IdentityChange, + IdentityRebuildPlan, + IdentityRebuildProgress, + IdentityRebuildResult, QueueSnapshot, ) from juice_lyrics.services.library_sync import ( @@ -98,6 +103,12 @@ def _app(tmp_path: Path, snapshot_provider, preview_provider=None, **providers) 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, ) @@ -355,6 +366,87 @@ async def scenario(): 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 "Need attention 0" 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 = ( @@ -771,3 +863,78 @@ async def scenario(): 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) From 0941970a084662e61fbf8ca7d61edd1337e9bf52 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 13 Sep 2026 12:45:51 +0100 Subject: [PATCH 39/62] Polish TUI help and interactions --- README.md | 4 + docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 21 ++- docs/PROJECT_STATE.md | 15 +- docs/UI_DESIGN.md | 67 +++----- docs/USER_FLOWS.md | 6 +- docs/USER_GUIDE.md | 13 ++ src/juice_lyrics/tui/app.py | 154 +++++++++++------- src/juice_lyrics/tui/help.py | 74 +++++++++ src/juice_lyrics/tui/screens/browse.py | 79 +++++++--- src/juice_lyrics/tui/screens/downloads.py | 29 ++-- src/juice_lyrics/tui/screens/library.py | 39 ++--- src/juice_lyrics/tui/screens/settings.py | 4 +- tests/test_tui.py | 2 + tests/test_tui_browse.py | 183 ++++++++++++---------- tests/test_tui_downloads.py | 125 ++++++--------- tests/test_tui_library.py | 3 +- 16 files changed, 476 insertions(+), 342 deletions(-) create mode 100644 src/juice_lyrics/tui/help.py diff --git a/README.md b/README.md index 5d74604..9bec667 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,10 @@ Your Juice WRLD folder is kept together: Open `999`, choose **Library**, then use **Refresh**, **Maintain lyrics**, **Verify**, or **Backups**. Maintenance always 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 changes to audio, state, backups, 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. diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index e328128..48f4f75 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -53,7 +53,7 @@ Milestone reached: The current development branch is `v2-redesign` in `/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -382 passing tests. +386 passing tests. Completed and integrated: @@ -83,8 +83,8 @@ functional Dashboard and Browse screens, canonical Category and Era selectors, correct case-sensitive API cache behavior, server-side catalogue pagination with scrollable 50-result pages, stable ID-based song details, and a Downloads screen with a flat track queue, song navigation, details, failure -stages, retry eligibility, an explicit Browse Add to queue flow that never -starts a download, and an explicitly confirmed Download selected action for one +stages, retry eligibility, an immediate Browse Add to queue flow that never +starts a download, and Download selected for one eligible queued song, a Library maintenance centre with local track browsing, filters, details, read-only refresh/verification, confirmed lyric maintenance, backup/restore, and rmpc checks, and a read-only @@ -92,10 +92,14 @@ Settings screen with effective configuration, paths, provenance, and rmpc state. Library Help also exposes a cancel-first, state-only catalogue identity rebuild for rerunning the latest matcher across current MP3, FLAC, and M4A files. -All five primary TUI sections are functional. Browse supports confirmed single -and batch queue additions. Downloads supports confirmed Download selected, +All five primary TUI sections are functional. Browse supports immediate single +and batch queue additions. Downloads supports immediate Download selected, sequential Download queue, Retry, Remove, Clear queue, and Clear completed history. Active-download cancellation and general configuration editing are not implemented. +The global `?` key opens a scrollable guide to the implemented keymap. Common +movement, details, Add, maintenance, and Help actions remain visible in screen +shortcut lines. Harmless queue actions no longer prompt; bulk downloading, +maintenance apply, restore, catalogue rebuild, and rmpc setup remain confirmed. Durable jobs remain an internal backend detail and completed entries are hidden from the active track queue. The CLI remains available for automation, diagnostics, and internal job recovery. Existing local FLAC and M4A files are first-class library @@ -162,7 +166,8 @@ docs/ The project is in incremental v2 implementation. The backend remains stable. -Mutating TUI actions are explicit and cancel-first. Library uses shared services +High-impact TUI mutations are explicit and cancel-first; harmless queue actions +are immediate. Library uses shared services for maintenance and restore; Settings remains read-only. Library lyric health is independent of catalogue identity: format-appropriate embedded lyrics plus a parsed timestamped sidecar can be fully covered even @@ -319,7 +324,7 @@ Available The current Browse implementation supports result selection, details, lyrics -previews, canonical filters, pagination, and confirmed single or marked Add to +previews, canonical filters, pagination, and immediate single or marked Add to queue actions. Adding never starts a download. --- @@ -372,7 +377,7 @@ Complete The Downloads implementation is a flat track queue. It shows queue totals, individual songs, structured failures, and retry eligibility; internal jobs are -hidden except for optional troubleshooting references. Browse can add confirmed +hidden except for optional troubleshooting references. Browse can add single or marked songs without starting downloads. Downloads can run the selected song or eligible queue sequentially, retry failures, and perform record-only cleanup. Active-download cancellation remains unavailable. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 19de416..e0a2985 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -2,10 +2,10 @@ ## Current Status Backend services remain stable. The `999` Textual interface supports -explicit confirmed single- and multi-song Browse Add to queue actions and +immediate single- and multi-song Browse Add to queue actions and selected or whole-queue downloads. The interface now prioritizes the streamlined Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 382 passing tests. +checkpoint has 386 passing tests. ## Current Branch v2-redesign @@ -17,16 +17,17 @@ v2-redesign ## Completed and integrated - Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. -- Responsive terminal-native Textual shell with all five main sections functional; Browse supports explicit single- and batch Add to queue mutations. +- Responsive terminal-native Textual shell with all five main sections functional; Browse adds one or marked songs without a confirmation or starting a download. - Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. - Track-oriented Downloads queue summaries, song navigation, details, structured failures, and retry eligibility; durable jobs are hidden as an internal mechanism. - Stable-ID Browse marks span pages within one logical search; Space toggles a song, `M` toggles the page, `u` clears marks, and search/filter changes clear hidden marks. -- Explicit cancel-first Browse batch Add flow reports eligible and skipped songs, persists eligible songs atomically, and never starts downloading. -- Explicit cancel-first Downloads `d` flow for one eligible queued song, delegated to the existing acquisition runner with responsive Downloading and Processing states. +- Immediate Browse batch Add flow persists eligible songs atomically and never starts downloading. +- Downloads `d` starts one explicitly selected eligible queued song without an extra prompt, delegated to the existing acquisition runner with responsive Downloading and Processing states. - Explicit cancel-first Downloads `A` flow for sequentially downloading all eligible queued songs; failed and active entries are skipped. - Simplified primary shortcut bars, optional Browse selection indicators, - plain-language confirmations, Dashboard journey prompts, and Settings folders - before advanced diagnostics; all secondary queue actions remain available in Help. + Dashboard journey prompts, and Settings folders before advanced diagnostics. + A scrollable global `?` guide inventories all TUI actions; common actions stay + visible. Bulk/destructive/config-changing operations remain cancel-first. - Library is the normal maintenance centre: format-aware summary, track details, read-only refresh/verification, non-mutating maintenance preview, confirmed shared-service execution, selected-song refresh, backup browsing/restore, and diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index c5a09b4..462b41f 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -306,14 +306,15 @@ 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` opens an explicit confirmation -for the marked set, or the current song when nothing is marked. The dialog shows -eligible/skipped counts and destination information and states that adding will -not start a download. +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 is deliberately small: `a Add song · 4 -Downloads · ? Help`, or `a Add selected · Space Mark · u Clear · 4 Downloads · -? Help` while marks exist. +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: @@ -374,43 +375,21 @@ rmpc detected ✓ # Keybindings -## Global - - -q Quit -esc Back -? Help -/ Search - - -## Lists - - -↑ ↓ Navigate -enter Select - - -## Browse - - -d Download -l Lyrics - - -## Library - - -r Refresh -m Maintain lyrics -v Verify -b Backups - - -## Downloads - - -r Retry -d Remove +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, `r` refresh, `m` maintain, `v` verify, `b` backups, `p` player | +| 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. --- diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 0eb99c0..4a8da8f 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -265,9 +265,9 @@ 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` adds the -marked set, or the highlighted song when nothing is marked, through a -cancel-first confirmation. Adding never starts a download and the application +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, diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 1eb1421..664ff08 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -12,6 +12,19 @@ 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 refresh, verification, and maintenance +preview are read-only. 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 diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 6417701..5f6d314 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -57,6 +57,7 @@ from .screens.downloads import DownloadsScreen from .screens.library import LibraryScreen from .screens.settings import SettingsScreen +from .help import HelpScreen LibraryStatusProvider = Callable[[Any], LibraryStatus] QueueSnapshotProvider = Callable[[], QueueSnapshot] @@ -84,14 +85,14 @@ class JuiceLyricsApp(App[None]): SUB_TITLE = "Juice WRLD Music Hub" BINDINGS = [ - Binding("1", "show_section('dashboard')", "Dashboard", show=False, priority=True), - Binding("2", "show_section('browse')", "Browse", show=False, priority=True), - Binding("3", "show_section('library')", "Library", show=False, priority=True), - Binding("4", "show_section('downloads')", "Downloads", show=False, priority=True), - Binding("5", "show_section('settings')", "Settings", show=False, priority=True), + 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), - Binding("q", "quit", "Quit", show=False, priority=True), + Binding("question_mark", "show_help", "Help", show=False, priority=True), + Binding("q", "quit", "Quit", show=False), ] def _get_dom_base(self): @@ -104,6 +105,43 @@ def _get_dom_base(self): 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; @@ -188,7 +226,9 @@ def _get_dom_base(self): } #browse-controls Input, - #browse-controls SelectCurrent { + #browse-controls SelectCurrent, + #library-controls Input, + #library-controls SelectCurrent { background: transparent; color: ansi_default; border: tall ansi_default; @@ -197,7 +237,9 @@ def _get_dom_base(self): } #browse-controls Input:focus, - #browse-controls Select:focus > SelectCurrent { + #browse-controls Select:focus > SelectCurrent, + #library-controls Input:focus, + #library-controls Select:focus > SelectCurrent { background: transparent; border: tall ansi_blue; background-tint: transparent; @@ -213,6 +255,45 @@ def _get_dom_base(self): 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; @@ -538,22 +619,6 @@ def _get_dom_base(self): height: 4; } - #library-controls Input, - #library-controls SelectCurrent { - background: transparent; - color: ansi_default; - border: tall ansi_default; - background-tint: transparent; - padding: 0 1; - } - - #library-controls Input:focus, - #library-controls Select:focus > SelectCurrent { - background: transparent; - border: tall ansi_blue; - background-tint: transparent; - } - #library-controls Select, #library-controls SelectOverlay { background: transparent; @@ -931,6 +996,10 @@ def action_show_section(self, section: str) -> None: 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) @@ -952,39 +1021,8 @@ def action_refresh_active(self) -> None: self.notify(f"{self.screen.title or 'This section'} has no data to refresh yet.") def action_show_help(self) -> None: - section = getattr(self.screen, "section", None) - if section == "browse": - message = ( - "Main: a Add to Downloads · 4 Open Downloads\n" - "Selection actions: Space mark current · M toggle this page · u clear marks. " - "Marks may span pages; changing search or filters clears them.\n" - "Navigation: ↑/↓ or j/k move · n next catalogue page · p previous catalogue page · " - "PageDown/PageUp scroll the loaded results · Home/End first/last loaded result · Enter details. " - "Adding does not start downloading; Downloads handles the actual download." - ) - elif section == "downloads": - message = ( - "Main: A Download queue · d Download selected\n" - "Queue actions: x Remove selected · c Clear waiting songs · H Clear completed history · r Refresh\n" - "Troubleshooting: t Try failed song again\n" - "Navigation: ↑/↓ or j/k select · PageUp/PageDown scroll · Home/End first/last · Enter details · Escape return/cancel. " - "Complete songs are hidden; cleanup never deletes downloaded music or lyrics." - ) - elif section == "library": - message = ( - "Main: r Refresh · m Maintain lyrics · v Verify · b Backups · p Player integration\n" - "Advanced: i Rebuild catalogue matches\n" - "Tracks: ↑/↓ or j/k select · / search · Enter details · l refresh selected lyrics. " - "Maintenance, identity rebuild, restore, and player setup always show a cancel-first confirmation." - ) - elif section == "settings": - message = ( - "↑/↓ or j/k inspect settings • Home/End first/last • " - "PgUp/PgDn scroll • r refresh • read-only; configuration changes remain CLI-only" - ) - else: - message = "1–5 switch sections • r refreshes Dashboard • q quits" - self.notify(message, timeout=5) + if not isinstance(self.screen, ModalScreen): + self.push_screen(HelpScreen()) def on_navigation_item_activated(self, event: NavigationItem.Activated) -> None: self.action_show_section(event.item.section) diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py new file mode 100644 index 0000000..2d7881a --- /dev/null +++ b/src/juice_lyrics/tui/help.py @@ -0,0 +1,74 @@ +"""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"), ("r", "Refresh library"), + ("m", "Preview and maintain lyrics"), ("s", "Preview lyric maintenance"), + ("v", "Verify library"), ("b", "Browse backups"), + ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), + ("i", "Preview catalogue identity rebuild"), + ("PgUp/PgDn", "Scroll tracks or details"), ("Home/End", "First / last track"))), + ("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/browse.py b/src/juice_lyrics/tui/screens/browse.py index 7ab3902..111e435 100644 --- a/src/juice_lyrics/tui/screens/browse.py +++ b/src/juice_lyrics/tui/screens/browse.py @@ -51,22 +51,32 @@ class BrowseInput(Input): """Filter input that preserves the shell's global numeric navigation.""" def on_key(self, event: Key) -> None: - if event.key == "slash": - self.screen.action_focus_search() + if event.key == "escape": + self.screen.set_focus(None) 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]) + 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() @@ -357,10 +367,11 @@ def __init__( 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_confirmation_ids: tuple[str, ...] = () + self._pending_add_ids: tuple[str, ...] = () self._selection_notice: str | None = None def compose_content(self) -> Iterable[Widget]: @@ -388,13 +399,14 @@ def compose_content(self) -> Iterable[Widget]: 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("a Add song · 4 Downloads · ? Help", id="browse-shortcuts", markup=False) + 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: @@ -403,8 +415,7 @@ def on_select_changed(self, event: Select.Changed) -> None: def on_screen_resume(self, event: ScreenResume) -> None: if self._filters_worker is None: self._filters_worker = self._load_filters() - if self.results: - self.call_after_refresh(self.set_focus, None) + self.call_after_refresh(self.set_focus, None) self._update_shortcuts() def submit_search(self, *, refresh: bool) -> None: @@ -537,6 +548,13 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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: @@ -556,27 +574,33 @@ def _apply_queue_plan(self, outcome: QueuePlanOutcome) -> None: 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 - self._pending_confirmation_ids = tuple( + 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.app.push_screen( - AddToQueueDialog( - outcome.result.plan, - self._queue_add_provider, - batch=outcome.marked and isinstance(outcome.result.plan, QueueBatchAddPlan), - ), - self._queue_dialog_closed, - ) + 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_dialog_closed(self, result: QueuePlanResult | None) -> None: - if result is not None and result.status in {QueueAddStatus.ADDED, QueueBatchAddStatus.ADDED}: - for song_id in self._pending_confirmation_ids: + 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() - self._pending_confirmation_ids = () + else: + self._set_status(result.message, error=True) + self._pending_add_ids = () def _apply_search(self, outcome: SearchOutcome) -> None: if outcome.error: @@ -688,6 +712,9 @@ def on_key(self, event: Key) -> None: 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 @@ -956,14 +983,14 @@ def _update_shortcuts(self) -> None: toggle = "Unmark" if current_key is not None and current_key in self.marked else "Mark" if narrow: text = ( - f"a add selected · Space {toggle.lower()} · u clear · 4 downloads · ? help" + f"Space {toggle.lower()} · a add selected · ? help" if count - else "a add song · 4 downloads · ? help" + else "↑↓ move · Enter details · a add · ? help" ) elif count: - text = f"a Add selected · Space {toggle} · u Clear · 4 Downloads · ? Help" + text = f"↑↓ Move · Enter Details · Space {toggle} · a Add selected · ? Help" else: - text = "a Add song · 4 Downloads · ? Help" + text = "↑↓ Move · Enter Details · Space Mark · a Add · ? Help" shortcuts.update(Text(text, no_wrap=True, overflow="ellipsis")) @staticmethod diff --git a/src/juice_lyrics/tui/screens/downloads.py b/src/juice_lyrics/tui/screens/downloads.py index ab9df4c..0c463aa 100644 --- a/src/juice_lyrics/tui/screens/downloads.py +++ b/src/juice_lyrics/tui/screens/downloads.py @@ -115,6 +115,7 @@ def on_key(self, event: Key) -> None: event.stop() return if event.key in {"escape", "n"}: + self._confirmed = True self.dismiss(None) elif event.key == "y": self._choice = "confirm" @@ -136,6 +137,7 @@ def on_key(self, event: Key) -> None: def _activate_choice(self) -> None: if self._choice == "cancel": + self._confirmed = True self.dismiss(None) elif not self._confirmed: self._confirmed = True @@ -275,6 +277,7 @@ def on_key(self, event: Key) -> None: event.stop() return if event.key in {"escape", "n"}: + self._confirmed = True self.dismiss(None) elif event.key == "y": self._choice = "confirm" @@ -296,6 +299,7 @@ def on_key(self, event: Key) -> None: def _activate(self) -> None: if self._choice == "cancel": + self._confirmed = True self.dismiss(None) elif not self._confirmed: self._confirmed = True @@ -385,7 +389,7 @@ def compose_content(self) -> Iterable[Widget]: 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("2 Browse songs · ? Help", id="downloads-position", 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: @@ -566,15 +570,15 @@ def _update_position(self) -> None: if self.items: item = self.selected_item if item and item.status is DownloadQueueItemStatus.FAILED: - actions = "t Retry · A Download queue · ? More" + actions = "↑↓ Move · Enter Details · t Retry · A Download queue · ? Help" elif item and item.status is DownloadQueueItemStatus.QUEUED: - actions = "A Download queue · d Selected · ? More" + actions = "↑↓ Move · Enter Details · d Download · A Queue · ? Help" elif item and item.status is DownloadQueueItemStatus.DOWNLOADING: - actions = "Downloading · ? More" + actions = "Downloading · Enter Details · ? Help" elif item and item.status is DownloadQueueItemStatus.PROCESSING: - actions = "Adding lyrics · ? More" + actions = "Adding lyrics · Enter Details · ? Help" else: - actions = "? More" + actions = "↑↓ Move · Enter Details · ? Help" self.query_one("#downloads-position", Static).update(actions) def _update_context_status(self) -> None: @@ -646,8 +650,8 @@ 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 - body = "Remove this song from Downloads?\n\nDownloaded music will not be deleted." - self.app.push_screen(QueueCleanupDialog("Remove", body), self._cleanup_closed) + 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: @@ -699,9 +703,8 @@ def _confirm_clear_queue(self) -> None: 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 - count = self.snapshot.completed_count - body = f"Clear {count} completed entr{'y' if count == 1 else 'ies'}?\n\nDownloaded music and lyrics will remain." - self.app.push_screen(QueueCleanupDialog("Clear history", body), self._cleanup_closed) + 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 @@ -730,7 +733,7 @@ def _apply_retry_plan(self, result: DownloadRetryResult) -> 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.app.push_screen(RetryFailedDialog(result.plan), self._retry_dialog_closed) + 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 @@ -791,7 +794,7 @@ def _apply_execution_plan(self, outcome: ExecutionPlanOutcome) -> None: if outcome.result.status is not DownloadExecutionStatus.READY or outcome.result.plan is None: self._set_status(outcome.result.message, error=True) return - self.app.push_screen(DownloadSelectedDialog(outcome.result.plan), self._download_dialog_closed) + self._download_dialog_closed(outcome.result.plan) def _download_dialog_closed(self, plan: DownloadExecutionPlan | None) -> None: if plan is None: diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 2d81c57..61dc411 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -75,29 +75,29 @@ class LibraryInput(Input): """Local search input that preserves global section shortcuts.""" def on_key(self, event: Key) -> None: - if event.key == "q": - self.app.exit() + if event.key == "escape": + self.screen.set_focus(None) event.prevent_default() event.stop() return - if event.key == "slash": - self.screen.action_focus_search() + if event.key == "question_mark": + self.app.action_show_help() 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]) + 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 == "q": - self.app.exit() + if event.key == "question_mark": + self.app.action_show_help() event.prevent_default() event.stop() return @@ -221,6 +221,7 @@ 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() @@ -239,6 +240,7 @@ def on_key(self, event: Key) -> None: 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 @@ -294,6 +296,7 @@ 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() @@ -312,6 +315,7 @@ def on_key(self, event: Key) -> None: def _activate(self) -> None: if self._choice == "cancel": + self._confirmed = True self.dismiss(None) elif not self._confirmed: self._confirmed = True @@ -385,7 +389,7 @@ def on_library_dialog_action_activated(self, event: LibraryDialogAction.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) + 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() @@ -396,7 +400,7 @@ def on_key(self, event: Key) -> None: event.prevent_default(); event.stop() def _activate(self) -> None: - if self._choice == "cancel": self.dismiss(None) + if self._choice == "cancel": self._confirmed = True; self.dismiss(None) elif not self._confirmed: self._confirmed = True; self.dismiss(self.record) @@ -443,7 +447,7 @@ def on_library_dialog_action_activated(self, event: LibraryDialogAction.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) + 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() @@ -454,7 +458,7 @@ def on_key(self, event: Key) -> None: event.prevent_default(); event.stop() def _activate(self) -> None: - if self._choice == "cancel": self.dismiss(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) @@ -541,19 +545,18 @@ def compose_content(self) -> Iterable[Widget]: with VerticalScroll(id="library-details-scroll"): yield Static("Select a track to inspect it.", id="library-details", markup=False) yield Static("Choose Maintain lyrics to preview changes safely.", id="library-preview", markup=False) - yield Static("r Refresh · m Maintain lyrics · v Verify · b Backups · p Player · ? Help", id="library-position", markup=False) + yield Static("↑↓ Move · Enter Details · r Refresh · m Maintain · v Verify · ? 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_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) - else: - self.call_after_refresh(self.set_focus, None) if self._pending_preview is not None: outcome, self._pending_preview = self._pending_preview, None self._apply_preview(outcome) @@ -949,9 +952,9 @@ def _render_details(self) -> None: def _update_position(self) -> None: if not self.filtered_tracks: - self.query_one("#library-position", Static).update("r Refresh · m Maintain lyrics · v Verify · b Backups · p Player · ? Help") + self.query_one("#library-position", Static).update("r Refresh · m Maintain · v Verify · b Backups · ? Help") return - suffix = "Esc track list · l Refresh lyrics · PgUp/PgDn details" if self._details_mode else "Enter details · r Refresh · m Maintain · v Verify · b Backups" + suffix = "Esc Back · l Refresh lyrics · ? Help" if self._details_mode else "↑↓ Move · Enter Details · r Refresh · m Maintain · ? Help" self.query_one("#library-position", Static).update( f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" ) diff --git a/src/juice_lyrics/tui/screens/settings.py b/src/juice_lyrics/tui/screens/settings.py index 3c33193..63fc889 100644 --- a/src/juice_lyrics/tui/screens/settings.py +++ b/src/juice_lyrics/tui/screens/settings.py @@ -73,7 +73,7 @@ def compose_content(self) -> Iterable[Widget]: 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("r refresh · ↑/↓ or j/k inspect · PgUp/PgDn scroll", id="settings-position", 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: @@ -190,7 +190,7 @@ def _render_rows(self) -> None: f"{row.label}\n{row.detail}" ) self.query_one("#settings-position", Static).update( - f"Setting {self.selected_index + 1} of {len(self.rows)} · r refresh · PgUp/PgDn scroll" + f"Setting {self.selected_index + 1} of {len(self.rows)} · ↑↓ Inspect · r Refresh · ? Help" ) def on_key(self, event: Key) -> None: diff --git a/tests/test_tui.py b/tests/test_tui.py index b9f2856..6e8becc 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -208,6 +208,8 @@ async def scenario(): 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()) diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index ae13801..a3ab305 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -34,6 +34,7 @@ ) from juice_lyrics.acquisition.models import AcquisitionItem from juice_lyrics.tui import JuiceLyricsApp +from juice_lyrics.tui.help import guide_text def _result( @@ -165,6 +166,13 @@ async def _open_browse(app: JuiceLyricsApp, pilot): 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 @@ -759,7 +767,7 @@ async def scenario(): 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 song" in _text(app, "#browse-shortcuts").lower() + assert "a add" in _text(app, "#browse-shortcuts").lower() for _ in range(34): await pilot.press("down") @@ -811,24 +819,80 @@ async def scenario(): def test_browse_help_distinguishes_loaded_result_scrolling_from_api_pages(tmp_path): - messages = [] - async def scenario(): app = _app(tmp_path, search=lambda *args, **kwargs: ()) - app.notify = lambda message, **kwargs: messages.append(message) async with app.run_test(size=(80, 24)) as pilot: await _open_browse(app, pilot) - app.action_show_help() - assert messages - help_text = messages[-1] - assert "n next catalogue page" in help_text - assert "p previous catalogue page" in help_text - assert "PageDown/PageUp scroll the loaded results" in help_text - assert "Home/End first/last loaded result" in help_text + 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", + "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)) @@ -964,7 +1028,7 @@ async def scenario(): asyncio.run(scenario()) -def test_add_to_queue_confirmation_is_cancel_first_and_uses_queue_wording(tmp_path): +def test_add_to_queue_is_immediate_and_does_not_download(tmp_path): calls = [] song = _result(1, "Rental") @@ -980,25 +1044,10 @@ async def scenario(): browse = app.screen await pilot.press("a") await browse._queue_plan_worker.wait() - await pilot.pause() - assert app.screen.__class__.__name__ == "AddToQueueDialog" - body = _text(app, "#queue-confirm-body") - assert "Add this song to Downloads?" in body - assert "Rental" in body - assert "This does not start downloading." in body - assert "job" not in body.lower() - assert "[Cancel]" in _text(app, "#queue-confirm-cancel") - await pilot.press("enter") - await pilot.pause() + await _wait_queue_add(browse, pilot) assert app.screen.id == "screen-browse" assert len(calls) == 1 - await pilot.press("a") - await browse._queue_plan_worker.wait() - await pilot.pause() - await pilot.press("escape") - await pilot.pause() - assert app.screen.id == "screen-browse" - assert len(calls) == 2 + assert "not configured" in _text(app, "#browse-status") asyncio.run(scenario()) @@ -1034,15 +1083,10 @@ async def scenario(): browse = app.screen await pilot.press("a") await browse._queue_plan_worker.wait() - await pilot.pause() - await pilot.press("y") - await app.screen._worker.wait() - await pilot.pause() + await _wait_queue_add(browse, pilot) assert len(created) == 1 - assert "Nothing has started" in _text(app, "#queue-confirm-status") - await pilot.press("y") - assert len(created) == 1 - await pilot.press("v") + 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() @@ -1134,12 +1178,9 @@ async def failure_scenario(): browse = app.screen await pilot.press("a") await browse._queue_plan_worker.wait() - await pilot.pause() - await pilot.press("y") - await app.screen._worker.wait() - await pilot.pause() - assert "permission denied" in _text(app, "#queue-confirm-status") - assert app.screen.__class__.__name__ == "AddToQueueDialog" + 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()) @@ -1157,7 +1198,7 @@ async def scenario(): browse = await _open_browse(app, pilot) await _submit(app, pilot, "songs") assert "[ ]" not in _text(app, "#browse-results") - assert "a Add song" in _text(app, "#browse-shortcuts") + 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") @@ -1176,7 +1217,7 @@ async def scenario(): assert browse.marked == {} assert "Selection cleared" in _text(app, "#browse-status") assert "[ ]" not in _text(app, "#browse-results") - assert "a Add song" in _text(app, "#browse-shortcuts") + assert "a Add" in _text(app, "#browse-shortcuts") asyncio.run(scenario()) @@ -1235,7 +1276,7 @@ async def scenario(): asyncio.run(scenario()) -def test_batch_add_confirmation_is_cancel_first_and_captures_stable_targets(tmp_path): +def test_batch_add_is_immediate_and_captures_stable_targets(tmp_path): songs = (_result(1, "First"), _result(2, "Second"), _result(9, "Already there")) created = [] @@ -1262,69 +1303,41 @@ async def scenario(): await _submit(app, pilot, "songs") await pilot.press("M", "a") await browse._queue_plan_worker.wait() - await pilot.pause() - assert app.screen.__class__.__name__ == "AddToQueueDialog" - body = _text(app, "#queue-confirm-body") - assert "Add 2 songs to Downloads?" in body - assert "1 selected song will be skipped." in body - assert "This does not start downloading." in body - assert "[Cancel]" in _text(app, "#queue-confirm-cancel") - dialog = app.screen - assert dialog.query_one("#queue-confirm-dialog").region.y >= 0 - assert dialog.query_one("#queue-confirm-dialog").region.bottom <= 24 - await pilot.press("enter") - await pilot.pause() + await _wait_queue_add(browse, pilot) assert app.screen is browse - assert set(browse.marked) == {"1", "2", "9"} - assert created == [] - - await pilot.press("a") - await browse._queue_plan_worker.wait() - await pilot.pause() - browse.selected_index = 1 - await pilot.press("tab", "enter") - await app.screen._worker.wait() - await pilot.pause() assert len(created) == 1 assert [item.song_id for item in created[0].eligible] == ["1", "2"] - assert "Added 2 songs" in _text(app, "#queue-confirm-status") - await pilot.press("y") - assert len(created) == 1 - await pilot.press("enter") - await pilot.pause() - assert browse.marked == {} + 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): - messages = [] songs = (_result(1, "Available"), _result(2, "Unavailable", downloadable=False)) async def scenario(): app = _app(tmp_path, search=lambda *args, **kwargs: songs) - app.notify = lambda message, **kwargs: messages.append(str(message)) 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 song" in shortcuts_text.lower() - assert "4 downloads" in shortcuts_text.lower() + 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") - app.action_show_help() - help_text = messages[-1] - assert "Space mark current" in help_text - assert "M toggle this page" in help_text - assert "changing search or filters clears them" in help_text - assert "Adding does not start downloading" in help_text - assert "4 Open Downloads" in help_text + 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()) diff --git a/tests/test_tui_downloads.py b/tests/test_tui_downloads.py index 38e2cc6..c18359f 100644 --- a/tests/test_tui_downloads.py +++ b/tests/test_tui_downloads.py @@ -387,29 +387,22 @@ async def 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),)) - messages = [] async def scenario(): app = _app(tmp_path, lambda: _snapshot(queued, failed)) - app.notify = lambda message, **kwargs: messages.append(message) async with app.run_test(size=(120, 40)) as pilot: await _open_downloads(app, pilot) bar = _text(app, "#downloads-position") - assert "A Download queue" in bar and "d Selected" in bar + 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") - app.action_show_help() - help_text = messages[-1] - assert "A Download queue" in help_text and "H Clear completed history" in help_text - assert "cleanup never deletes downloaded music or lyrics" in help_text + 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() - remove_text = _text(app, "#download-confirm-body") - assert "Remove this song from Downloads?" in remove_text - assert "Downloaded music will not be deleted." in remove_text - assert app.focused is not None and app.focused.id == "download-confirm-cancel" - await pilot.press("enter"); await pilot.pause() assert app.screen.id == "screen-downloads" asyncio.run(scenario()) @@ -448,6 +441,9 @@ async def scenario(): 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") @@ -455,7 +451,34 @@ async def scenario(): asyncio.run(scenario()) -def test_clear_history_modal_is_centered_cancel_first_and_keyboard_confirmable(tmp_path): +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 = [] @@ -475,25 +498,9 @@ 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) - shortcut = downloads.query_one("#downloads-position") await pilot.press("shift+h"); await pilot.pause() - assert app.screen.__class__.__name__ == "QueueCleanupDialog" - dialog = app.query_one("#download-confirm-dialog") - assert abs(dialog.region.center[0] - 40) <= 1 - assert abs(dialog.region.center[1] - 12) <= 1 - assert dialog.region.bottom <= shortcut.region.y - assert app.focused is not None and app.focused.id == "download-confirm-cancel" - assert "Downloaded music and lyrics will remain" in _text(app, "#download-confirm-body") - assert "Clear history" in _text(app, "#download-confirm-download") - await pilot.press("enter"); await pilot.pause() - assert calls == [] and app.screen.id == "screen-downloads" - - await pilot.press("shift+h"); await pilot.pause() - await pilot.press("2"); await pilot.pause() - assert app.screen.__class__.__name__ == "QueueCleanupDialog" - await pilot.press("tab"); await pilot.pause() - assert app.focused is not None and app.focused.id == "download-confirm-download" - await pilot.press("enter"); await pilot.pause(0.2) + 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" @@ -501,18 +508,9 @@ async def scenario(): asyncio.run(scenario()) -def test_clear_history_escape_n_and_y_are_safe_and_exactly_once(tmp_path): +def test_clear_history_does_not_need_confirmation_keys(tmp_path): completed = _job(1, "history", (_item(tmp_path, "Finished", QueueStatus.COMPLETED),)) - async def cancel_scenario(key): - calls = [] - app = _app(tmp_path, lambda: _snapshot(completed), history=lambda: calls.append("clear")) - async with app.run_test(size=(80, 24)) as pilot: - await _open_downloads(app, pilot) - await pilot.press("shift+h"); await pilot.pause() - await pilot.press(key); await pilot.pause() - assert app.screen.id == "screen-downloads" and calls == [] - async def confirm_scenario(): calls = [] def clear(): @@ -521,12 +519,10 @@ def clear(): 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() - await pilot.press("y", "y"); await pilot.pause(0.2) + await pilot.press("shift+h"); await pilot.pause(0.2) + await pilot.press("y", "enter"); await pilot.pause() assert calls == ["clear"] - asyncio.run(cancel_scenario("escape")) - asyncio.run(cancel_scenario("n")) asyncio.run(confirm_scenario()) @@ -629,7 +625,7 @@ async def scenario(): assert not list(tmp_path.rglob("*.mp3")) -def test_download_selected_confirmation_is_cancel_first_and_escape_is_safe(tmp_path): +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 = [] @@ -648,30 +644,15 @@ async def scenario(): async with app.run_test() as pilot: downloads = await _open_downloads(app, pilot) await pilot.press("d") - await pilot.pause() - assert app.screen.__class__.__name__ == "DownloadSelectedDialog" - body = _text(app, "#download-confirm-body") - assert "Download Queued Song?" in body - assert "Lyrics will be added automatically." in body - assert "job" not in body.lower() - assert "[Cancel]" in _text(app, "#download-confirm-cancel") - await pilot.press("enter") - await pilot.pause() - assert app.screen.id == "screen-downloads" - assert execution_calls == [] - - await pilot.press("d") - await pilot.pause() - await pilot.press("escape") - await pilot.pause() + await pilot.pause(0.2) assert app.screen.id == "screen-downloads" - assert execution_calls == [] - assert len(plan_calls) == 2 + assert len(execution_calls) == 1 + assert len(plan_calls) == 1 asyncio.run(scenario()) -def test_retry_failed_song_requires_confirmation_and_runs_once(tmp_path): +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) @@ -686,18 +667,8 @@ async def scenario(): 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() - assert app.screen.__class__.__name__ == "RetryFailedDialog" - assert "Try again" in _text(app, "#download-confirm-title") - assert app.focused is not None and app.focused.id == "download-confirm-cancel" - await pilot.press("2"); await pilot.pause() - assert app.screen.__class__.__name__ == "RetryFailedDialog" - await pilot.press("escape"); await pilot.pause() - assert calls == [] - await pilot.press("t"); await pilot.pause() - await pilot.press("tab"); await pilot.pause() - assert app.focused is not None and app.focused.id == "download-confirm-download" - await pilot.press("enter"); await pilot.pause(0.2) + await pilot.press("t"); await pilot.pause(0.2) + assert app.screen.id == "screen-downloads" assert calls == ["retry-job:0"] asyncio.run(scenario()) diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 8ed0785..e790ec0 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -207,7 +207,8 @@ def provider(settings): async with app.run_test() as pilot: await pilot.press("3") await asyncio.to_thread(quit_started.wait, 2) - await pilot.press("q") + # Search input keeps normal typing keys; leave it before quitting. + await pilot.press("escape", "q") assert not app.is_running quit_release.set() From d40876f4205b215f5ff7ec14c238ccca2589ca77 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 14 Sep 2026 10:55:18 +0100 Subject: [PATCH 40/62] Harden library state and restore safety --- src/juice_lyrics/backup/manager.py | 16 ++++-- src/juice_lyrics/services/library_identity.py | 24 +++++++-- src/juice_lyrics/services/library_status.py | 9 +++- tests/test_backup_retention.py | 25 +++++++++ tests/test_library_identity.py | 54 +++++++++++++++++++ tests/test_library_status.py | 6 ++- 6 files changed, 123 insertions(+), 11 deletions(-) diff --git a/src/juice_lyrics/backup/manager.py b/src/juice_lyrics/backup/manager.py index aa8a7b4..ba6edf7 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -2,7 +2,9 @@ import json import logging +import os import shutil +import tempfile from collections.abc import Callable from dataclasses import dataclass from datetime import datetime, timezone @@ -75,7 +77,16 @@ def backup_file(path: Path, root: Path, base: Path) -> Path: def restore_file(backup: Path, destination: Path) -> None: destination.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(backup, destination) + 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: @@ -178,7 +189,6 @@ def restore_backup(root: Path, base: Path) -> int: restored = 0 for source in _backup_audio_files(root): destination = base / source.relative_to(root) - destination.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(source, destination) + restore_file(source, destination) restored += 1 return restored diff --git a/src/juice_lyrics/services/library_identity.py b/src/juice_lyrics/services/library_identity.py index d364508..497b926 100644 --- a/src/juice_lyrics/services/library_identity.py +++ b/src/juice_lyrics/services/library_identity.py @@ -44,6 +44,13 @@ def _has_identity(entry: Mapping[str, Any] | None) -> bool: 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 backfill_catalogue_identities( settings: Settings, tracks: Sequence[LibraryTrack], @@ -55,7 +62,10 @@ def backfill_catalogue_identities( 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 = {} @@ -67,10 +77,11 @@ def backfill_catalogue_identities( for track in tracks: _, existing = resolve_state_entry(files, track.relative_path, relative_paths) - if _has_identity(existing): - reused += 1 - continue try: + 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) @@ -83,12 +94,15 @@ def backfill_catalogue_identities( 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 {} entry.update( { - "sha256": dependencies.hasher(track.path), + "sha256": audio_hash, "song_id": song_id, "api_name": api_name, "updated": now_iso(), @@ -101,6 +115,8 @@ def backfill_catalogue_identities( errors.append(f"{track.filename}: {str(exc) or type(exc).__name__}") 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), diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 455c94e..4e8b4ba 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -298,12 +298,17 @@ def get_library_snapshot( track_warnings.append(f"Could not hash file: {exc}") matched_title = None - if entry is not 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 entry.get("song_id") is not None) + matched_title + or ( + entry is not None + and state_status is LibraryStateStatus.CURRENT + and entry.get("song_id") is not None + ) ) expected_synced = bool( diff --git a/tests/test_backup_retention.py b/tests/test_backup_retention.py index 5ca19fb..e694038 100644 --- a/tests/test_backup_retention.py +++ b/tests/test_backup_retention.py @@ -226,6 +226,31 @@ def test_retained_backup_can_still_be_restored(tmp_path): 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) diff --git a/tests/test_library_identity.py b/tests/test_library_identity.py index 2ab8a00..af2918a 100644 --- a/tests/test_library_identity.py +++ b/tests/test_library_identity.py @@ -157,6 +157,60 @@ def test_persisted_identity_is_reused_without_search(tmp_path): 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 diff --git a/tests/test_library_status.py b/tests/test_library_status.py index c92e466..f3e7053 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -192,8 +192,8 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa "A Synced.mp3", "B Plain.mp3", "C Missing.mp3" ] assert snapshot.total_track_count == 3 - assert snapshot.matched_count == 2 - assert snapshot.unmatched_count == 1 + 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 @@ -204,6 +204,8 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa 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 From 7d2d01645772ae9a533bc7c90e90b367ce0a8513 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 14 Sep 2026 11:08:59 +0100 Subject: [PATCH 41/62] Improve library and dashboard performance --- src/juice_lyrics/services/library_identity.py | 11 ++- src/juice_lyrics/services/library_status.py | 27 ++++-- src/juice_lyrics/state.py | 7 ++ src/juice_lyrics/tui/screens/dashboard.py | 56 +++++------ tests/test_performance_regressions.py | 97 +++++++++++++++++++ tests/test_tui.py | 33 +++++++ 6 files changed, 192 insertions(+), 39 deletions(-) create mode 100644 tests/test_performance_regressions.py diff --git a/src/juice_lyrics/services/library_identity.py b/src/juice_lyrics/services/library_identity.py index 497b926..fef7d3d 100644 --- a/src/juice_lyrics/services/library_identity.py +++ b/src/juice_lyrics/services/library_identity.py @@ -9,7 +9,7 @@ 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 read_state_file, resolve_state_entry, sha256_file, write_state_file +from ..state import file_fingerprint, read_state_file, resolve_state_entry, sha256_file, write_state_file from .library_status import LibraryTrack @@ -78,7 +78,14 @@ def backfill_catalogue_identities( for track in tracks: _, existing = resolve_state_entry(files, track.relative_path, relative_paths) try: - audio_hash = dependencies.hasher(track.path) + 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 diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 4e8b4ba..78814cb 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -19,7 +19,7 @@ ) from ..lyrics.engine import parse_synced_lyrics, verify_file from ..lyrics.sidecar import sidecar_lrc_path -from ..state import resolve_state_entry, sha256_file +from ..state import file_fingerprint, resolve_state_entry, sha256_file LyricsVerifier = Callable[[Path], tuple[bool, str]] DurationReader = Callable[[Path], float | None] @@ -71,6 +71,8 @@ class LibraryTrack: 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 @property def needs_attention(self) -> bool: @@ -247,6 +249,8 @@ def get_library_snapshot( ) raw_entry = state_files.get(state_key) if state_key is not None else None 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 @@ -288,11 +292,20 @@ def get_library_snapshot( track_warnings.append("Stored library state is malformed.") else: try: - state_status = ( - LibraryStateStatus.CURRENT - if entry.get("sha256") == hasher(path) - else LibraryStateStatus.CHANGED - ) + 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}") @@ -364,6 +377,8 @@ def get_library_snapshot( media_format=media_format(path), synchronized_source=expected_synced, warning=" ".join(track_warnings) or None, + content_sha256=content_sha256, + content_fingerprint=content_fingerprint, ) ) return LibrarySnapshot(library_path, True, tuple(tracks), warnings) diff --git a/src/juice_lyrics/state.py b/src/juice_lyrics/state.py index 76d66bc..19ec3c0 100644 --- a/src/juice_lyrics/state.py +++ b/src/juice_lyrics/state.py @@ -110,3 +110,10 @@ def sha256_file(path: Path) -> str: for chunk in iter(lambda: handle.read(1024 * 1024), b""): digest.update(chunk) return digest.hexdigest() + + +def file_fingerprint(path: Path) -> tuple[int, int, int, int, int]: + """Cheap in-process guard for reusing a hash, including replacement/in-place edits.""" + + 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/screens/dashboard.py b/src/juice_lyrics/tui/screens/dashboard.py index d59d596..b770361 100644 --- a/src/juice_lyrics/tui/screens/dashboard.py +++ b/src/juice_lyrics/tui/screens/dashboard.py @@ -1,7 +1,6 @@ from __future__ import annotations from collections.abc import Callable, Iterable -from dataclasses import dataclass from typing import Any from textual import work @@ -15,14 +14,6 @@ from .base import HubScreen -@dataclass(frozen=True, slots=True) -class DashboardSnapshot: - library: LibraryStatus | None - queue: QueueSnapshot | None - library_error: str | None = None - queue_error: str | None = None - - class DashboardScreen(HubScreen): """Read-only summary assembled exclusively from application services.""" @@ -37,7 +28,8 @@ def __init__( self.settings = settings self._library_status_provider = library_status_provider self._queue_snapshot_provider = queue_snapshot_provider - self._refresh_worker: Worker[DashboardSnapshot] | None = None + 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]: @@ -64,7 +56,8 @@ def refresh_snapshot(self) -> None: 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_snapshot() + self._refresh_worker = self._load_library() + self._queue_worker = self._load_queue() def invalidate_snapshot(self) -> None: self._invalidated = True @@ -72,34 +65,35 @@ def invalidate_snapshot(self) -> None: @work( thread=True, exclusive=True, - group="dashboard-snapshot", + group="dashboard-library", exit_on_error=False, ) - def _load_snapshot(self) -> DashboardSnapshot: - library = queue = None - library_error = queue_error = None + def _load_library(self) -> tuple[LibraryStatus | None, str | None]: try: - library = self._library_status_provider(self.settings) + return self._library_status_provider(self.settings), None except Exception as exc: - library_error = str(exc) or type(exc).__name__ + 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: - queue = self._queue_snapshot_provider() + return self._queue_snapshot_provider(), None except Exception as exc: - queue_error = str(exc) or type(exc).__name__ - return DashboardSnapshot(library, queue, library_error, queue_error) + return None, 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: - self._apply_snapshot(event.worker.result) - elif event.state is WorkerState.ERROR: - message = str(event.worker.error) if event.worker.error else "Unable to load dashboard data" - self._apply_snapshot(DashboardSnapshot(None, None, message, message)) - - def _apply_snapshot(self, snapshot: DashboardSnapshot) -> None: - self._render_library(snapshot.library, snapshot.library_error) - self._render_queue(snapshot.queue, snapshot.queue_error) + 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) diff --git a/tests/test_performance_regressions.py b/tests/test_performance_regressions.py new file mode 100644 index 0000000..ebb4eaf --- /dev/null +++ b/tests/test_performance_regressions.py @@ -0,0 +1,97 @@ +"""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 + + +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 diff --git a/tests/test_tui.py b/tests/test_tui.py index 6e8becc..966e28c 100644 --- a/tests/test_tui.py +++ b/tests/test_tui.py @@ -3,6 +3,7 @@ import re import sys from threading import Event +from time import perf_counter sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src")) @@ -78,6 +79,38 @@ async def scenario(): 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( From 47cb6a66b6ddc506985873deb8aad7d6e12401e2 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 14 Sep 2026 11:19:44 +0100 Subject: [PATCH 42/62] Harden catalogue matching for album editions --- src/juice_lyrics/library/matching.py | 3 +- tests/test_matching.py | 50 ++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/src/juice_lyrics/library/matching.py b/src/juice_lyrics/library/matching.py index 68f595e..91202b2 100644 --- a/src/juice_lyrics/library/matching.py +++ b/src/juice_lyrics/library/matching.py @@ -27,6 +27,7 @@ _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", @@ -40,7 +41,7 @@ r"\s*[\[(]\s*(?:" r"bonus\s+track\s+version|" r"deluxe(?:\s+edition)?|" - r"anniversary(?:\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*", diff --git a/tests/test_matching.py b/tests/test_matching.py index 56e4c41..41b719c 100644 --- a/tests/test_matching.py +++ b/tests/test_matching.py @@ -200,6 +200,56 @@ def test_album_edition_compatibility_is_recognized_but_arbitrary_parentheticals_ 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 = { From 31ebaf2ce964141622ec2cca92fbce62f74da0de Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 15 Sep 2026 18:31:10 +0100 Subject: [PATCH 43/62] Add one-button Library Sync --- README.md | 8 +- docs/USER_GUIDE.md | 8 +- src/juice_lyrics/services/library_identity.py | 4 + .../services/library_index_sync.py | 285 ++++++++++++++++ src/juice_lyrics/services/library_status.py | 44 ++- src/juice_lyrics/tui/app.py | 5 + src/juice_lyrics/tui/help.py | 4 +- src/juice_lyrics/tui/screens/library.py | 54 ++- tests/test_library_index_sync.py | 315 ++++++++++++++++++ tests/test_tui_library.py | 53 ++- 10 files changed, 759 insertions(+), 21 deletions(-) create mode 100644 src/juice_lyrics/services/library_index_sync.py create mode 100644 tests/test_library_index_sync.py diff --git a/README.md b/README.md index 9bec667..0970df5 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,15 @@ Your Juice WRLD folder is kept together: ### Normal use -Open `999`, choose **Library**, then use **Refresh**, **Maintain lyrics**, -**Verify**, or **Backups**. Maintenance always shows a non-mutating preview and +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. **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 changes to audio, state, backups, or player configuration. +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. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 664ff08..b29c890 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -56,7 +56,7 @@ adjacent `.lrc`. Open `999`, choose **Library**, and use: -* **Refresh** to rescan MP3, FLAC, and M4A files without changing them; +* **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; * **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; @@ -67,8 +67,10 @@ 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. -Refresh displays local lyric health immediately, then checks unknown tracks -against the catalogue in the background. Only confident identities are saved. +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**. diff --git a/src/juice_lyrics/services/library_identity.py b/src/juice_lyrics/services/library_identity.py index fef7d3d..ee697d6 100644 --- a/src/juice_lyrics/services/library_identity.py +++ b/src/juice_lyrics/services/library_identity.py @@ -21,6 +21,7 @@ class IdentityBackfillResult: unknown: int failed: int errors: tuple[str, ...] = () + failed_paths: tuple[str, ...] = () @property def changed(self) -> bool: @@ -74,6 +75,7 @@ def backfill_catalogue_identities( relative_paths = tuple(track.relative_path for track in tracks) reused = identified = unknown = failed = 0 errors: list[str] = [] + failed_paths: list[str] = [] for track in tracks: _, existing = resolve_state_entry(files, track.relative_path, relative_paths) @@ -120,6 +122,7 @@ def backfill_catalogue_identities( 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 identified: if _state_bytes(state_path) != original_state: @@ -132,4 +135,5 @@ def backfill_catalogue_identities( 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..cdae53f --- /dev/null +++ b/src/juice_lyrics/services/library_index_sync.py @@ -0,0 +1,285 @@ +"""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 .library_status import ( + LibraryMatchStatus, + LibrarySnapshot, + LibraryStateStatus, + LibraryTrack, + get_library_snapshot, +) + + +@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: + return f"Library scan complete · {self.error}" + if not (self.new or self.changed or self.removed or self.identified or self.failed): + return "Library is up to date" + parts = [f"Library synced · {self.snapshot.total_track_count} tracks"] + for count, label in ( + (self.new, "new"), (self.changed, "changed"), + (self.removed, "removed"), (self.identified, "newly matched"), + (self.failed, "could not be checked"), + ): + 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("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, + ) + 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_status.py b/src/juice_lyrics/services/library_status.py index 78814cb..ce24482 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -1,6 +1,7 @@ from __future__ import annotations import json +import hashlib from collections.abc import Callable from dataclasses import dataclass from enum import Enum @@ -73,6 +74,7 @@ class LibraryTrack: 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 @property def needs_attention(self) -> bool: @@ -110,6 +112,7 @@ class LibrarySnapshot: directory_exists: bool tracks: tuple[LibraryTrack, ...] warnings: tuple[str, ...] = () + state_signature: str | None = None @property def total_track_count(self) -> int: @@ -222,6 +225,7 @@ def get_library_snapshot( 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.""" @@ -235,12 +239,39 @@ def get_library_snapshot( ) 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 + and previous_snapshot.state_signature == state_signature + else {} + ) tracks: list[LibraryTrack] = [] for path in discovered: relative_path = path.relative_to(library_path) + 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 + ): + tracks.append(prior) + continue + except OSError: + pass reference = str(relative_path) state_key, resolved_entry = resolve_state_entry( state_files, @@ -287,6 +318,10 @@ def get_library_snapshot( 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.") @@ -334,6 +369,12 @@ def get_library_snapshot( ) 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 @@ -379,9 +420,10 @@ def get_library_snapshot( warning=" ".join(track_warnings) or None, content_sha256=content_sha256, content_fingerprint=content_fingerprint, + sidecar_fingerprint=sidecar_fingerprint, ) ) - return LibrarySnapshot(library_path, True, tuple(tracks), warnings) + return LibrarySnapshot(library_path, True, tuple(tracks), warnings, state_signature) def get_library_status( diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 5f6d314..493718f 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -38,6 +38,7 @@ ) 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.identity_rebuild import ( IdentityRebuildPlan, IdentityRebuildResult, @@ -71,6 +72,7 @@ CatalogueFiltersProvider = Callable[..., CatalogueFilterMetadata] LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] LibraryIdentityProvider = Callable[..., IdentityBackfillResult] +LibraryIndexSyncProvider = Callable[..., LibraryIndexSyncResult] IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] @@ -880,6 +882,7 @@ def __init__( 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, @@ -918,6 +921,7 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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 @@ -952,6 +956,7 @@ def on_mount(self) -> None: 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, diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index 2d7881a..f6c8bab 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -20,8 +20,8 @@ ("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"), ("r", "Refresh library"), - ("m", "Preview and maintain lyrics"), ("s", "Preview lyric maintenance"), + ("/", "Focus track search; Enter filters"), ("s", "Sync Library"), + ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), ("v", "Verify library"), ("b", "Browse backups"), ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), ("i", "Preview catalogue identity rebuild"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 61dc411..0821d40 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -27,6 +27,7 @@ LibraryTrack, ) from ...services.library_identity import IdentityBackfillResult +from ...services.library_index_sync import LibraryIndexSyncResult from ...services.identity_rebuild import ( IdentityRebuildPlan, IdentityRebuildProgress, @@ -40,6 +41,7 @@ SnapshotProvider = Callable[[Any], LibrarySnapshot] IdentityProvider = Callable[..., IdentityBackfillResult] +IndexSyncProvider = Callable[..., LibraryIndexSyncResult] IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] PreviewProvider = Callable[[Any], LibrarySyncPlan] @@ -472,6 +474,7 @@ def __init__( settings: Any, *, snapshot_provider: SnapshotProvider, + index_sync_provider: IndexSyncProvider, identity_provider: IdentityProvider, identity_rebuild_plan_provider: IdentityRebuildPlanProvider, identity_rebuild_execution_provider: IdentityRebuildExecutionProvider, @@ -485,6 +488,7 @@ def __init__( 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 @@ -501,6 +505,8 @@ def __init__( 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 @@ -544,14 +550,17 @@ def compose_content(self) -> Iterable[Widget]: 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("Choose Maintain lyrics to preview changes safely.", id="library-preview", markup=False) - yield Static("↑↓ Move · Enter Details · r Refresh · m Maintain · v Verify · ? Help", id="library-position", 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 · ↑↓ Move · Enter Details · m Maintain lyrics · ? 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) @@ -565,11 +574,14 @@ def on_screen_resume(self, event: ScreenResume) -> None: self._apply_identity(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("Choose Maintain lyrics to preview changes safely.") + 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() @@ -586,6 +598,25 @@ def invalidate_snapshot(self) -> 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: @@ -630,7 +661,16 @@ def _load_preview(self, selected_path: Path | None = None) -> PreviewOutcome: return PreviewOutcome(error=str(exc) or type(exc).__name__) def on_worker_state_changed(self, event: Worker.StateChanged) -> None: - if event.worker is self._snapshot_worker: + 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(): @@ -952,9 +992,9 @@ def _render_details(self) -> None: def _update_position(self) -> None: if not self.filtered_tracks: - self.query_one("#library-position", Static).update("r Refresh · m Maintain · v Verify · b Backups · ? Help") + self.query_one("#library-position", Static).update("s Sync Library · m Maintain lyrics · b Backups · ? Help") return - suffix = "Esc Back · l Refresh lyrics · ? Help" if self._details_mode else "↑↓ Move · Enter Details · r Refresh · m Maintain · ? Help" + suffix = "Esc Back · l Refresh lyrics · ? Help" if self._details_mode else "s Sync Library · ↑↓ Move · Enter Details · ? Help" self.query_one("#library-position", Static).update( f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" ) @@ -965,7 +1005,7 @@ def on_key(self, event: Key) -> None: if isinstance(self.app.focused, (Input, Select)): return if event.key == "s": - self.generate_preview() + self.sync_library() elif event.key == "m": self.generate_preview(action="maintain") elif event.key == "v": diff --git a/tests/test_library_index_sync.py b/tests/test_library_index_sync.py new file mode 100644 index 0000000..8899fed --- /dev/null +++ b/tests/test_library_index_sync.py @@ -0,0 +1,315 @@ +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 == "Library is up to date" + assert counts == before + + +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"}) + 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 + 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 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 and second.summary == "Library is up to date" + assert counts == before + assert path.read_bytes() == b"audio" + + +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, + } diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index e790ec0..f520d85 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -38,6 +38,7 @@ 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, @@ -46,6 +47,47 @@ 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, @@ -351,7 +393,7 @@ async def scenario(): await current.wait() await pilot.pause() assert screen.selected_track.reference == keep.reference - assert "Maintain lyrics" in _text(app, "#library-preview") + assert "Sync Library" in _text(app, "#library-preview") release_stale.set() await pilot.pause() assert "First.mp3" not in _text(app, "#library-tracks") @@ -477,7 +519,7 @@ async def scenario(): async with app.run_test() as pilot: screen = await _open_library(app, pilot) assert calls == 0 - await pilot.press("s") + screen.generate_preview() await asyncio.to_thread(started.wait, 2) assert "Checking library needs" in _text(app, "#library-preview") await pilot.press("4") @@ -501,7 +543,7 @@ async def scenario(): ) async with broken.run_test() as pilot: await _open_library(broken, pilot) - await pilot.press("s") + broken.screen.generate_preview() await broken.screen._preview_worker.wait() await pilot.pause() assert "Preview failed: API unavailable" in _text(broken, "#library-preview") @@ -533,7 +575,7 @@ 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) - await pilot.press("s") + screen.generate_preview() await asyncio.to_thread(stale_started.wait, 2) screen.generate_preview() current = screen._preview_worker @@ -578,7 +620,8 @@ async def scenario(): ) async with app.run_test() as pilot: await _open_library(app, pilot) - await pilot.press("/", "enter", "down", "up", "s") + await pilot.press("/", "enter", "down", "up") + app.screen.generate_preview() await app.screen._preview_worker.wait() await pilot.pause() await pilot.press("r") From 5d7fa50cee9bd214f925cef68817d34c3b44947d Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 15 Sep 2026 19:06:27 +0100 Subject: [PATCH 44/62] Maintain repository and refresh project handoff --- .gitignore | 10 + AGENTS.md | 81 ++++ PROJECT_CONTEXT.md | 384 ++-------------- README.md | 14 +- docs/ARCHITECTURE.md | 17 +- docs/CHANGELOG.md | 14 + docs/DECISIONS.md | 24 +- docs/DEVELOPMENT.md | 20 +- docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md | 596 ++----------------------- docs/PROJECT_STATE.md | 299 +++++++++---- docs/ROADMAP.md | 149 ++----- docs/ROADMAP_V2.md | 293 +----------- docs/UI_DESIGN.md | 39 +- docs/USER_FLOWS.md | 135 ++---- docs/USER_GUIDE.md | 9 +- docs/V2_DESIGN.md | 536 +--------------------- 16 files changed, 518 insertions(+), 2102 deletions(-) create mode 100644 AGENTS.md 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..934aae1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,81 @@ +# 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) +- 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. +- 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` +- 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 +``` + +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. + +## Roadmap discipline + +The current roadmap is in `docs/PROJECT_STATE.md` and `docs/ROADMAP.md`. Keep +normal Library UX centered on **Sync Library** and future **Issues**; keep +repair/recovery tools secondary. After substantial milestones, update +`docs/PROJECT_STATE.md` and any directly affected design/user documentation. diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 787cd89..e7aba5c 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -1,361 +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` -External synchronized lyrics use same-basename sidecars beside each MP3, FLAC, or M4A song. The -music path remains configurable and portable. +The internal and storage names intentionally remain stable. Do not create a +second `999` state tree or silently migrate user data. -## Existing proven behavior +## Product principles -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 in MP3 files. -* Synced lyrics also produce `.lrc` files for rmpc. -* If only API `lyrics` exists, embed them as ID3 USLT in MP3 files. -* FLAC files store standard plain-text Vorbis `LYRICS`; synchronized timing - remains in the adjacent `.lrc` because FLAC has no interoperable SYLT equivalent. -* M4A files store standard plain-text MP4 `©lyr`; synchronized timing remains - in the adjacent `.lrc` rather than a proprietary tag. -* 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. - -Audio and external synchronized lyrics stay together: `song.mp3`, `song.flac`, or `song.m4a` -maps to `song.lrc` in the same directory. The finalized audio path is the sole write -authority. The legacy `lyrics_dir` key remains readable but is deprecated and -cannot redirect current output. Read-only inspection and planning create -nothing; rmpc configuration and historical state paths cannot redirect new -output. During development use the repository entry -point (`.venv/bin/999`) so a stale separately installed package is not -mistaken for the current working tree. - -Preserve unrelated rmpc configuration when modifying configuration files. - -Advanced commands: - -```bash -999 rmpc setup -999 rmpc sync -999 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 - -Open the application: - -```bash -999 -``` - -Normal maintenance: - -```bash -999 sync -``` - -Useful commands: - -```bash -999 status -999 search -999 info -999 guide -999 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 -999 acquire search "rental" -999 acquire add "rental" --index 1 -999 acquire jobs -999 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 - -Persistent jobs are an internal durability and execution mechanism. The normal -product model is a flat download queue of songs; UUIDs should stay out of common -workflows. Browse can mark stable song IDs across pages of one search and -explicitly add the marked set (or the current song) without starting it. -Completed items remain stored but are hidden from the active queue, -and failed items remain visible for future retry or removal. - -## Acquisition → lyrics integration - -After successful MP3 acquisition, an optional post-processing hook uses the existing lyrics engine. -Acquisition remains MP3-focused; native FLAC and M4A support applies to existing local-library files. - -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, FLAC, or M4A file: - -* 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 -* native recursive FLAC discovery, metadata matching, Vorbis lyric embedding, - verification, backup/restore, state, adjacent LRC, and rmpc notification verified -* native recursive M4A discovery, MP4 metadata matching, standard `©lyr` - embedding, verification, backup/restore, state, adjacent LRC, and rmpc notification verified -* Settings / Path CLI compatibility verified -* responsive terminal-native Textual shell with `ansi_color=True` -* all five main TUI sections are functional; Browse can explicitly add one or several stable-ID selections to the queue -* Downloads can explicitly run one selected queued song after a cancel-first confirmation -* canonical Category and Era selectors, filter-only searches, and correct case-sensitive API cache behaviour -* server-side catalogue pagination with scrollable 50-result pages and stable ID-based song details -* flat track-queue summaries, song navigation, details, structured failure stages, and retry eligibility -* Library provides local track browsing, format-aware coverage summaries, - read-only refresh/verification, confirmed lyric maintenance, selected-song - refresh, valid backup browsing/restore, and rmpc verification/setup -* local lyric health is classified independently from catalogue identity; - timestamped adjacent LRC content is validated rather than inferred from file - existence, and healthy unmatched tracks do not require maintenance -* Library Refresh can backfill confident catalogue identity for new MP3, FLAC, - and M4A files without changing media; state cleanup remains an explicit, - preview-first operation with a safety copy -* full catalogue identity rebuilding is preview-first, state-only, backed up, - and atomic; it is available through advanced Library help and CLI state - maintenance without changing audio or lyrics -* Settings reports effective configuration, sidecar lyrics behavior, provenance where reliable, application paths, and rmpc integration without creating or changing files -* TUI Download selected, Download queue, Retry, Remove, Clear queue, and Clear - completed history are implemented; active-download cancel and general - configuration editing are not implemented -* advanced CLI remains available for scripting, diagnostics, internal records, - and unusual recovery -* 382 automated tests pass across the suite - -The repository for this checkpoint is `/home/nobloat/Downloads/juice-lyrics-codex` -on branch `v2-redesign`. The product and primary executable are `999`. -`juice-lyrics` remains a legacy command alias; the internal `juice_lyrics` -package, `juice-wrld-lyrics` distribution, and existing `juice-lyrics` XDG -storage namespace remain stable for compatibility. - -Recommended next milestone is final beta polish and release testing. - -To resume: - -```bash -cd /home/nobloat/Downloads/juice-lyrics-codex -git switch v2-redesign -.venv/bin/pytest -q -.venv/bin/999 -``` - -## 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 +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. -The latest transferred project archive is the current development source of truth. +## Durable safety decisions -The existing GitHub repository is not authoritative. +- 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. -When documentation conflicts with the actual implementation, inspect the code and tests and resolve the discrepancy deliberately. +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 0970df5..c1e96f3 100644 --- a/README.md +++ b/README.md @@ -49,9 +49,8 @@ downloads and high-impact changes to audio, backups, catalogue identities, or pl 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. -Library **Refresh** shows local health first, then identifies newly discovered -tracks in the background and saves only confident catalogue identities. It -does not rewrite audio, lyrics, backups, or rmpc configuration. +The separate Library **Refresh** action remains a read-only local rescan. +Routine discovery and safe identity backfill belong to **Sync Library**. The CLI remains available for scripting and automation. `999 sync` remembers files it has already processed, so unchanged verified files are skipped. @@ -103,14 +102,17 @@ 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 -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 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 91f8293..6e589bc 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -66,11 +66,18 @@ 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. -Library Refresh uses a shared catalogue-identity backfill service after the -local snapshot is rendered. The service reuses compatible persisted identities, -uses the normal query preparation and conservative matcher for unknown MP3, -FLAC, and M4A files, and atomically merges only confident `song_id`/`api_name` -results into the existing state schema. It never infers lyric-processing state. +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 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index ea17094..e9756ee 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## Unreleased — One-button Library Sync and safety hardening + +* Made Library `s` the normal background **Sync Library** action. +* Added incremental unchanged/new/changed/removed file classification, safe + catalogue backfill for Unknown tracks, changed-file identity invalidation, + removed-path retirement, cache-aware retries, and duplicate-run protection. +* Preserved conservative Bandit (`94107`) and 10 Feet (`94102`) matcher + regressions, state-conflict safety, atomic restore, and local lyric-health + classification independent of catalogue identity. +* Kept normal Sync state-only: it does not rewrite audio, sidecars, backups, + downloads, or rmpc configuration. +* Verified 410 automated tests and 14 isolated recovery smoke tests at commit + `31ebaf2`. + ## Unreleased — 999 beta identity and packaging * Made `999` the primary product name and console entry point while retaining diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 4ddfe38..6230de1 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -153,9 +153,10 @@ 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. -Download selected, sequential Download all, Retry, Remove, Clear queue, and -Clear completed history each use an explicit cancel-first workflow. Active -download cancellation remains planned. +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 @@ -169,11 +170,18 @@ 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. Library Refresh 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. +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 diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 04612c2..a1ff064 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -16,9 +16,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. @@ -94,9 +94,9 @@ 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 review and add the marked songs, or the highlighted song when none -are marked. The cancel-first dialog reports eligible and skipped songs and -states that adding does not start a download. Global keys remain `1`–`5` for +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 @@ -108,10 +108,10 @@ 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 review a cancel-first confirmation for the -selected queued song. Confirming runs the existing download, validation, lyric, -LRC, state, backup, and rmpc pipeline; no download starts before confirmation. -Press `t` on a failed song for a cancel-first Retry confirmation. A verified +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, diff --git a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md index 48f4f75..15e2759 100644 --- a/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md +++ b/docs/JUICE_WRLD_V2_CONTINUITY_BRIEF.md @@ -1,579 +1,33 @@ -# Juice WRLD TUI Project Continuity Brief (v2) +# 999 v2 continuity brief -## Purpose +This file is retained for old links and session prompts. It is no longer a +second full project-history document. -This document exists as a handoff/context file for continuing development of the Juice WRLD music management application after a chat reset. +Use this handoff order: -It describes: -- current project state -- architectural decisions -- future direction -- UX goals -- important constraints +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 -# Current Project Identity +`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`. -The project started as: +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`. -`juice-lyrics` +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. -Originally it was a CLI tool for: - -- finding Juice WRLD lyrics through the Juice WRLD API -- embedding lyrics into MP3 ID3 tags -- generating rmpc-compatible LRC files -- syncing local music libraries - -It has evolved into a much larger application: - -A Juice WRLD music management hub containing: - -- catalogue search -- metadata browsing -- local library management -- lyric management -- acquisition/download workflows -- rmpc integration -- backup and recovery systems - -The product is now named `999`. The primary console command is `999`, while -`juice-lyrics` remains a legacy compatibility command. - ---- - -# Current Backend Status - -The backend is considered stable. - -Milestone reached: - -## Current verified checkpoint - -The current development branch is `v2-redesign` in -`/home/nobloat/Downloads/juice-lyrics-codex`. The complete automated suite has -386 passing tests. - -Completed and integrated: - -Verified systems: - -- API client -- search -- metadata lookup -- track matching -- lyric parsing -- ID3 SYLT embedding -- ID3 USLT embedding -- native FLAC discovery, metadata matching, Vorbis lyric embedding, and verification -- native M4A discovery, MP4 metadata matching, standard `©lyr` embedding, and verification -- LRC generation -- rmpc integration -- backups -- restore system -- downloader -- resume support -- persistent acquisition jobs -- duplicate detection -- CLI workflows - -The v2 frontend now also includes a responsive terminal-native Textual shell, -functional Dashboard and Browse screens, canonical Category and Era -selectors, correct case-sensitive API cache behavior, server-side catalogue -pagination with scrollable 50-result pages, stable ID-based song details, and a -Downloads screen with a flat track queue, song navigation, details, failure -stages, retry eligibility, an immediate Browse Add to queue flow that never -starts a download, and Download selected for one -eligible queued song, a Library maintenance centre with local track browsing, -filters, details, read-only refresh/verification, confirmed lyric maintenance, -backup/restore, and rmpc checks, and a read-only -Settings screen with effective configuration, paths, provenance, and rmpc state. -Library Help also exposes a cancel-first, state-only catalogue identity rebuild -for rerunning the latest matcher across current MP3, FLAC, and M4A files. - -All five primary TUI sections are functional. Browse supports immediate single -and batch queue additions. Downloads supports immediate Download selected, -sequential Download queue, Retry, Remove, Clear queue, and Clear completed history. -Active-download cancellation and general configuration editing are not implemented. -The global `?` key opens a scrollable guide to the implemented keymap. Common -movement, details, Add, maintenance, and Help actions remain visible in screen -shortcut lines. Harmless queue actions no longer prompt; bulk downloading, -maintenance apply, restore, catalogue rebuild, and rmpc setup remain confirmed. -Durable jobs remain an internal backend detail and completed entries are hidden -from the active track queue. The CLI remains available for automation, -diagnostics, and internal job recovery. Existing local FLAC and M4A files are first-class library -tracks; acquisition remains MP3-focused. The product and primary executable are -`999`; the internal package, distribution identifier, and XDG data namespace -remain compatible with existing installations. - -Live API acquisition was tested successfully. - -The project has reached the point where the backend should be frozen before major redesign. - ---- - -# Important Architecture Rule - -DO NOT rewrite the backend during v2 redesign. - -The backend already works. - -The future TUI must be a presentation layer only. - -The architecture should remain: - - -Textual TUI -| -| -Application services -| -| -Backend modules -| -| -API / Files / MP3 / rmpc - - -The UI should call existing systems. - -The UI should NOT: -- edit ID3 tags directly -- handle downloads itself -- contain matching logic -- contain API logic - ---- - -# Current Repository State - -GitHub repository exists. - -Current branch: - -`v2-redesign` - -Important files: - - -PROJECT_CONTEXT.md - -docs/ -├── V2_DESIGN.md -├── DECISIONS.md -└── this file - - -The project is in incremental v2 implementation. The backend remains stable. -High-impact TUI mutations are explicit and cancel-first; harmless queue actions -are immediate. Library uses shared services -for maintenance and restore; Settings remains read-only. -Library lyric health is independent of catalogue identity: format-appropriate -embedded lyrics plus a parsed timestamped sidecar can be fully covered even -when catalogue matching is unknown. Catalogue uncertainty remains visible but -does not itself create lyric attention. - ---- - -# v2 Vision - -The goal is to transform the project from: - -"lyrics downloader/tagger" - -into: - -"A polished Juice WRLD music hub for Linux" - -The application should feel like a real Linux application. - -Inspired by: - -- rmpc -- superfile -- modern terminal applications - ---- - -# TUI Technology - -Preferred framework: - -## Textual - -Reasons: - -- modern Python ecosystem -- proper widgets -- colors -- keyboard navigation -- layouts -- dialogs -- responsive terminal UI -- feels like a real application - -The goal is NOT a menu-driven CLI. - -The goal is a proper TUI. - ---- - -# UX Philosophy - -The user should not need to understand technical internals. - -Avoid exposing: - -- SYLT -- USLT -- job UUIDs -- API paths -- complicated flags - -Prefer: - -- Synced Lyrics -- Plain Lyrics -- Downloads -- Queue -- Library -- Songs - -The application should feel approachable. - ---- - -# Proposed Screens - -## 1. Dashboard - -Purpose: - -The home screen. - -Shows: - -- library size -- lyric coverage -- rmpc status -- download status -- quick actions - - -Example: - - -999 Music Hub - -Library -39 Tracks - -Lyrics -19 Synced -20 Plain -0 Missing - -Downloads -1 Active - -[Browse] -[Sync] -[Queue] -[Settings] - - ---- - -## 2. Browse/Search - -Purpose: - -Discover songs. - -Features: - -- search bar -- live filtering -- eras: - - GBGR - - WOD - - DRFL - - JW3 - - POST - -Categories: - -- Released -- Unreleased -- Sessions - -Results show: - - -Rental (v1) - -Era: -DRFL - -Lyrics: -Synced - -Download: -Available - - -The current Browse implementation supports result selection, details, lyrics -previews, canonical filters, pagination, and immediate single or marked Add to -queue actions. Adding never starts a download. - ---- - -## 3. Library - -Purpose: - -Manage local music. - -Shows: - -- songs -- lyric status -- sync status -- missing metadata - -Actions: - -- refresh and verify without writes -- preview and confirm lyric maintenance -- open details and refresh one selected song -- browse and restore valid backups -- verify or explicitly configure rmpc - ---- - -## 4. Download Queue - -Purpose: - -Replace confusing job management. - -Instead of: - - -job-id: -2fc704cce61b4774868... - - -Use: - - -Downloads - -Rental -Downloading 65% -Lemon Glow -Complete - -The Downloads implementation is a flat track queue. It shows queue totals, -individual songs, structured failures, and retry eligibility; internal jobs are -hidden except for optional troubleshooting references. Browse can add -single or marked songs without starting downloads. Downloads can run the selected -song or eligible queue sequentially, retry failures, and perform record-only -cleanup. Active-download cancellation remains unavailable. - ---- - -## 5. Song Details - -Shows: - -- title -- era -- category -- producers -- lyrics status -- lyrics preview - -Actions: - -- download -- add lyrics -- view metadata - ---- - -## 6. Settings - -Controls: - -- music directory -- API settings -- rmpc settings -- backup settings - ---- - -# rmpc Important Information - -Current situation: - -rmpc only supports external LRC files. - -It does NOT read embedded lyrics. - -Current application architecture keeps each same-basename LRC beside its MP3, FLAC, or M4A audio -file. The finalized audio path is authoritative; the legacy centralized -`lyrics_dir` configuration is accepted only for compatibility and does not -direct new output. Existing centralized files require a separate explicit -migration and are never moved automatically by `999`. - -Therefore: - -## Synced lyrics - -Do: - -1. Embed SYLT into MP3, standard Vorbis `LYRICS` into FLAC, or standard MP4 `©lyr` into M4A -2. Generate LRC -3. Put the same-basename LRC beside the audio file -4. rmpc displays lyrics - -## Plain lyrics - -Do: - -1. Embed USLT into MP3, standard Vorbis `LYRICS` into FLAC, or standard MP4 `©lyr` into M4A - -Do NOT: - -- invent timestamps -- generate fake LRC - -Result: - -Android players can read embedded lyrics. - -rmpc cannot display them as timed lyrics. - -FLAC and M4A have no interoperable embedded equivalent to ID3 SYLT. The -application does not invent one: synchronized timing remains authoritative in -the adjacent `.lrc`, and audio is never converted. - -This is accepted as a player limitation. - ---- - -# Command Direction - -The normal product entry point is simply: - -```bash -999 -``` - -Advanced compatibility commands remain available under `999 acquire`. -`juice-lyrics` is an executable alias to the same CLI implementation. - ---- - -# Product Identity - -The naming decision for beta is: - -- product: `999` -- primary command: `999` -- legacy command: `juice-lyrics` -- Python package: `juice_lyrics` -- distribution: `juice-wrld-lyrics` -- XDG storage namespace: `juice-lyrics` - -These compatibility names avoid breaking imports, installed-package upgrades, -or existing config, state, queue, cache, and backup data. - ---- - -# Development Order - -Do not immediately code. - -Recommended order: - -## Phase 1 -Design - -- branding -- naming -- screens -- user flows -- terminology - - -## Phase 2 -Command compatibility - -- primary `999` command -- legacy command alias -- preserve old data and internal package paths - - -## Phase 3 -CLI improvements - -Add: - -- simpler commands -- friendly queue system -- better output - - -## Phase 4 -Textual TUI - -Build: - -- dashboard -- browser -- library -- queue -- settings - - -## Phase 5 - -Release v2. - ---- - -# Development Rules - -Always: - -- preserve backend -- keep tests passing -- make reversible changes -- document decisions - -Never: - -- rewrite working systems -- mix UI and business logic -- remove features without discussion - ---- - -# User Preferences - -The user wants: - -- a real TUI, not a fake CLI menu -- a polished Arch Linux style application -- something that fits a rice setup -- keyboard-driven workflow -- modern terminal aesthetics - -The user is not a programmer. - -Instructions should be clear and guided. - -The goal is to create something that feels like a finished Linux application, not just a script. +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/PROJECT_STATE.md b/docs/PROJECT_STATE.md index e0a2985..beca3ba 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,104 +1,207 @@ -# 999 Project State - -## Current Status -Backend services remain stable. The `999` Textual interface supports -immediate single- and multi-song Browse Add to queue actions and -selected or whole-queue downloads. The interface now prioritizes the streamlined -Browse → Add → Downloads → Download queue journey. The current working-tree -checkpoint has 386 passing tests. - -## Current Branch -v2-redesign - -## Repository - -`/home/nobloat/Downloads/juice-lyrics-codex` - -## Completed and integrated - -- Typed read-only library-status, catalogue, acquisition-queue, and library-sync services. -- Responsive terminal-native Textual shell with all five main sections functional; Browse adds one or marked songs without a confirmation or starting a download. -- Canonical Category and Era selectors, filter-only searches, correct case-sensitive API cache behavior, server-side catalogue pagination, scrollable 50-result pages, and stable ID-based song details. -- Track-oriented Downloads queue summaries, song navigation, details, structured failures, and retry eligibility; durable jobs are hidden as an internal mechanism. -- Stable-ID Browse marks span pages within one logical search; Space toggles a song, `M` toggles the page, `u` clears marks, and search/filter changes clear hidden marks. -- Immediate Browse batch Add flow persists eligible songs atomically and never starts downloading. -- Downloads `d` starts one explicitly selected eligible queued song without an extra prompt, delegated to the existing acquisition runner with responsive Downloading and Processing states. -- Explicit cancel-first Downloads `A` flow for sequentially downloading all eligible queued songs; failed and active entries are skipped. -- Simplified primary shortcut bars, optional Browse selection indicators, - Dashboard journey prompts, and Settings folders before advanced diagnostics. - A scrollable global `?` guide inventories all TUI actions; common actions stay - visible. Bulk/destructive/config-changing operations remain cancel-first. -- Library is the normal maintenance centre: format-aware summary, track details, - read-only refresh/verification, non-mutating maintenance preview, confirmed - shared-service execution, selected-song refresh, backup browsing/restore, and - rmpc verification/setup. -- Library lyric health is independent of catalogue identity: valid local - embedded lyrics plus a genuinely timestamped adjacent sidecar can be fully - covered even when the catalogue match is unknown. Catalogue-unmatched totals - remain visible separately and do not inflate lyric-attention totals. -- Library Refresh now backfills confident catalogue identities for newly - discovered MP3, FLAC, and M4A files through the shared conservative matcher, - without modifying audio or lyrics; offline failure leaves local health usable. -- `999 state clean` previews clearly stale external records, while explicit - `--yes` creates a timestamped state safety copy and atomically prunes only the - reviewed records. Valid relative history and ambiguous duplicates are kept. -- Catalogue identities can be rebuilt for all current tracks through an - explicit cancel-first Library action or `999 state rebuild-identities`. - Rebuilds preserve lyric state, audit changed IDs, back up state, and commit - atomically without touching media. -- Settings configuration provenance, XDG/application paths, sidecar external-lyrics behavior, rmpc integration status, and current capability limitations. -- Existing MP3 lyric embedding, verification, backup/restore, synchronized LRC generation, and rmpc integration remain supported. -- Local FLAC files are recursively discovered and matched using native title, - artist, album, and duration metadata. FLAC lyric writes use standard Vorbis - `LYRICS`, preserve unrelated metadata, and are backed up before mutation. -- FLAC synchronized timing uses the adjacent `.lrc`; there is no proprietary - embedded timing format and no audio conversion. -- Local M4A files are recursively discovered and matched using native MP4 title, - artist, album, and duration metadata. Plain lyrics use standard `©lyr` metadata. -- M4A synchronized timing uses the adjacent `.lrc`; unrelated atoms and the - audio stream are preserved and no conversion occurs. -- External synchronized LRC files live beside each audio file with the same - basename; the finalized audio path is authoritative. -- The legacy `lyrics_dir` setting remains readable but deprecated. Historical - state paths and rmpc configuration cannot redirect new LRC output, and - read-only operations create no sidecars or directories. - -## Available through the CLI - -The advanced CLI remains supported for scripting, whole acquisition records, -low-level recovery, diagnostics, and durable acquisition-record operations. - -## Current limitations - -- Configuration editing remains CLI-only. -- Active-download Cancel remains unimplemented; `x` removes - a waiting/failed song, `c` clears waiting/failed records, and `H` clears - completed history without deleting downloaded files. -- Acquisition post-processing remains MP3-only; native FLAC and M4A support - targets existing local-library files. -- `999` is the primary product and executable name. `juice-lyrics` remains a - legacy compatibility command. The Python namespace remains `juice_lyrics`, - the distribution remains `juice-wrld-lyrics`, and existing XDG data remains - under `juice-lyrics` without migration. - -## Important Decisions -- Keep embedded lyrics -- Keep LRC generation for rmpc -- Use terminal-native colours -- Use Textual -- Keep backend separate from UI - -## Recommended next milestones - -1. Final beta polish and release testing -2. Active-download cancellation, if still desired -3. Post-beta enhancements only after real-user feedback - -## Resume development +# 999 project state + +This is the canonical detailed handoff for the current application. It records +the repository state after `31ebaf2 Add one-button Library Sync`. 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` +- Last verified product commit: `31ebaf2` +- Verification at that commit: 410 tests passed; 14 isolated recovery smoke + tests passed; compileall and `git diff --check` passed. + +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 +``` + +`?` 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 healthy track +may be catalogue Unknown without needing lyric attention. An adjacent `.lrc` +counts as synchronized only when it contains genuine timestamped lyric lines. + +- 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. + +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. + +## Known limitations and risks + +- The conservative matcher intentionally leaves ambiguous/no-result songs + Unknown; manual match and identity locking are not implemented yet. +- Library has attention/details but not a consolidated Issues experience. +- 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. +- Packaging/install acceptance and public GitHub presentation still need a + final release pass. + +## 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 future **Issues**; +advanced repair/recovery must not overwhelm normal use. + +1. Manual catalogue match and identity locking +2. Library Issues / Health experience +3. Duplicate detector +4. Metadata repair +5. Missing Library +6. `999 doctor` / diagnostics +7. Shell completion +8. Final performance/reliability acceptance +9. Packaging and clean installation +10. GitHub presentation/distribution +11. Beta release + +## Resume safely ```bash cd /home/nobloat/Downloads/juice-lyrics-codex git switch v2-redesign -.venv/bin/pytest -q +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..8127a0d 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,121 +1,32 @@ # Roadmap -## Current baseline: 1.4.0 - -The project already provides a working local-library lyrics workflow: - -* 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 - -## Phase 1 — Safety net and architecture - -* 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. - -## Phase 2 — Acquisition foundation - -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 +The canonical current checkpoint is `PROJECT_STATE.md`. This file keeps +only the forward product sequence. + +## Product rule + +```text +common safe routine work → automatic/simple +ambiguous/destructive work → explicit user decision +``` + +Normal Library UX stays centered on **Sync Library** and future **Issues**. +Advanced repair and recovery remain available without crowding routine use. + +## Remaining sequence + +1. Manual catalogue match and identity locking +2. Library Issues / Health experience +3. Duplicate detector +4. Metadata repair +5. Missing Library +6. `999 doctor` / diagnostics +7. Shell completion +8. Final performance/reliability acceptance +9. Packaging and clean installation +10. GitHub presentation/distribution +11. Beta release + +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 index afe7578..34ce300 100644 --- a/docs/ROADMAP_V2.md +++ b/docs/ROADMAP_V2.md @@ -1,287 +1,12 @@ -# v2 Development Roadmap +# Historical v2 roadmap -This document defines the order of work for transforming the project into the polished `999` Juice WRLD music application. +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. -The existing backend is considered stable and should be preserved. +This filename remains for compatibility with old links. Do not maintain a +second roadmap here. See: ---- - -# Guiding Principles - -## Do not rewrite working systems - -The following are considered mature: - -- Lyrics engine -- ID3 embedding -- Backup system -- API client -- Track matching -- Downloader -- Acquisition jobs -- rmpc integration - -Future work should improve usability around these systems. - ---- - -# Phase 0 — Planning (Complete) - -Status: Complete - -Goals: - -- Preserve stable backend. -- Document architecture. -- Decide product direction. -- Prepare rename strategy. - -Completed: - -- GitHub repository created. -- Backend milestone saved. -- v2 design document created. -- Architecture decisions documented. - ---- - -# Phase 1 — Cleanup and Preparation - -Goal: - -Make the codebase ready for a major frontend redesign. - -Tasks: - -- Remove unused legacy CLI code. -- Simplify CLI entrypoint. -- Improve internal interfaces. -- Review documentation. -- Add missing regression tests. - -Important: - -Do not change user-facing behaviour unless necessary. - ---- - -# Phase 2 — Identity and Migration - -Status: Complete for beta preparation. - -Goal: - -Introduce the new application identity. - -Tasks: - -- Choose final name. -- Update package metadata. -- Create new CLI command. -- Keep existing configuration paths without creating a second data tree. -- Preserve the legacy `juice-lyrics` command and storage compatibility. - -Example: - -Primary: - - -999 sync - - -Legacy compatibility: - - -juice-lyrics sync - - -Both invoke the same CLI implementation during the transition. - ---- - -# Phase 3 — CLI Experience - -Goal: - -Make common actions simple. - -Current: - - -acquire search -acquire add -acquire run - - -Future: - - -999 get "Rental" - - -Improvements: - -- Friendly output. -- Remove unnecessary technical terms. -- Better error messages. -- Human-readable download queue. -- Better help screens. - ---- - -# Phase 4 — Interactive TUI - -Goal: - -Create the main application interface. - -Status: In progress. The responsive terminal-native shell and all five primary -sections are integrated. Browse supports explicitly confirmed single- and -multi-song Add to queue actions, and Downloads provides selected, sequential -all, retry, and record-only cleanup actions. - -Screens: - -## Browse - -Features: - -- Catalogue search. -- Filters. -- Song details. -- Lyrics preview. -- Download actions. - -Status: Catalogue functionality is complete, including server-side pagination, -scrollable 50-result pages, cross-page stable-ID marking, and explicitly -confirmed batch Add to queue. Adding does not start downloads. - ---- - -## Library - -Features: - -- Local tracks. -- Lyrics status. -- Sync state. -- Metadata. - -Status: Read-only functionality complete, including local search and status -filters, track details, and explicit non-mutating sync previews. Sync execution -remains planned. - ---- - -## Downloads - -Features: - -- Active downloads. -- Progress. -- Completed items. -- Retry. - -Status: Track-oriented queue projection, Browse batch Add, explicitly confirmed -Download selected, sequential Download all, Retry, and record-only cleanup are -complete. Durable jobs remain internal, completed entries are hidden from the -active queue, and failed entries remain visible. Active cancellation remains -planned. - ---- - -## Settings - -Features: - -- Music directory. -- rmpc settings. -- API settings. - -Status: Read-only functionality complete, including effective configuration, -path existence, provenance where reliable, rmpc integration state, and current -capability limitations. Editing remains planned. - ---- - -# Phase 5 — Advanced Features - -Recommended implementation order after the current checkpoint: - -1. Beta polish, packaging, and release testing -2. Active-download cancellation, if still desired -3. Library sync execution controls, if explicitly approved -4. `999` command and naming migration - -Possible future improvements: - -## Lyrics Improvements - -- Better lyrics previews. -- Search within lyrics. -- More player integrations. - -## Library Improvements - -- Duplicate cleanup. -- Better sorting. -- Album/era organization. - -## Acquisition Improvements - -- Better batch workflows. -- Playlist-style downloads. -- Download history. - -## TUI Improvements - -- Themes. -- Custom keybindings. -- More customization. - ---- - -# Features NOT Planned - -Avoid feature creep. - -The project should not become: - -- A full music player replacement. -- A streaming service. -- A general-purpose downloader. -- A cloud music service. - -The goal is: - -"A beautiful Juice WRLD music management tool for Linux." - ---- - -# Release Goals - -## Version 2.0 - -Should include: - -- New identity. -- Better CLI. -- Interactive TUI. -- Migration support. -- Stable backend. - ---- - -# Success Criteria - -The application succeeds when a user can: - -1. Install it. -2. Open it. -3. Browse songs. -4. Download music. -5. Have lyrics embedded. -6. Play with rmpc. -7. Understand what is happening without reading documentation. - -The technology should disappear behind the experience. +- `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 index 462b41f..b6da38e 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -160,11 +160,9 @@ Example: └──────────────────────────────────────┘ -Questions: - -- Should dashboard open by default? -- Should recent songs/downloads appear? -- Should it show rmpc status? +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. --- @@ -281,6 +279,7 @@ Synced LRC ✓ Actions: +s Sync Library r Refresh m Maintain lyrics v Verify @@ -383,7 +382,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `r` refresh, `m` maintain, `v` verify, `b` backups, `p` player | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `m` maintain; `r` local refresh, `v`, `b`, `p` are secondary | | Downloads | `↑`/`↓` move, `Enter` details, `d` selected download, `t` retry, `A` whole queue | | Settings | `↑`/`↓` inspect, `PgUp`/`PgDn` scroll, `r` refresh | @@ -394,28 +393,8 @@ movement, details, and the main action for each section. Core bindings: --- -# Future Screens - -Possible later additions: - -- lyrics viewer -- playlist manager -- statistics -- album/era explorer -- advanced metadata editor - -These are not required for the first release. - ---- - -# First Release Priority - -The first usable TUI version should contain: - -1. Dashboard -2. Browse/Search -3. Song Details -4. Download Queue -5. Library View +# Current scope -Settings and advanced tools can follow. +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 index 4a8da8f..9fcba2f 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -50,13 +50,8 @@ Maintain A new user opens 999 for the first time. -Current problem: - -The old CLI requires understanding setup, configuration, directories, and integrations. - -v2 goal: - -The application should guide the user. +The application must open safely even when configuration or the default library +is missing. --- @@ -68,53 +63,11 @@ User runs: 999 -Application checks: - -- configuration exists -- music directory exists -- rmpc availability -- existing library - ---- - -Example: - - -Welcome to 999 - -First-time setup detected. - -Music folder: -~/Music/Juice WRLD - -rmpc: -Detected ✓ - -Existing tracks: -39 - -Would you like to continue? - -[Enter] Setup -[Esc] Exit - - ---- - -After setup: - - -Setup complete. - -Library: -39 tracks - -Lyrics: -39 processed - -Ready. - -Press Enter to continue. +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. --- @@ -406,6 +359,8 @@ Missing Lyrics Actions: +s Sync Library + r Refresh m Maintain lyrics @@ -423,29 +378,15 @@ enter Details; l refresh selected lyrics ## Goal -Preview and update new or changed files without memorizing a CLI command. +Bring 999's view of the current library up to date without understanding scan, +backfill, verification, or state internals. --- User: -Press m - - ---- - -Confirmation: - - -Library maintenance - -12 songs can be updated -2 songs need attention - -No changes have been made. - -[Update 12 songs] [Cancel] +Press s --- @@ -453,16 +394,7 @@ No changes have been made. Progress: -Maintaining library... - -Rental.mp3 -Matching... - -Lyrics found ✓ - -Embedding... - -Complete +Syncing library... --- @@ -470,19 +402,26 @@ Complete Summary: -Library updated +Library synced + +181 tracks +4 new +1 changed +2 removed +37 newly matched +15 need attention -Updated: -12 -Synced Lyrics: -8 +--- -Plain Lyrics: -4 +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. -Failed: -0 +To change lyrics, the separate `m` action first presents a non-mutating +maintenance preview and uses cancel-first confirmation before applying changes. --- @@ -630,15 +569,9 @@ Ask only before: --- -# Future User Flows - -Possible later additions: - -- playlists -- favourites -- statistics -- automatic library monitoring -- album/era exploration -- lyrics-only mode +# Forward flows -These are not required for the first v2 release. +The next planned normal-user addition is an Issues/Health experience backed by +manual catalogue matching and identity locking. The ordered 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 b29c890..c0971d4 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -20,8 +20,9 @@ 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 refresh, verification, and maintenance -preview are read-only. Applying maintenance, restoring, rebuilding catalogue +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. @@ -76,7 +77,9 @@ changed. If the catalogue is unavailable, local health remains usable and the track stays **Unknown**. Select a song and press `l` to refresh lyrics for only that song. The CLI -equivalent, `999 sync`, remains useful for scripting and automation. +`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 diff --git a/docs/V2_DESIGN.md b/docs/V2_DESIGN.md index af839fc..7b42f37 100644 --- a/docs/V2_DESIGN.md +++ b/docs/V2_DESIGN.md @@ -1,529 +1,13 @@ -# 999 Design Proposal +# Historical v2 design -## Vision +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. -The project has grown beyond the original `juice-lyrics` lyrics-tagging scope. +This filename remains for historical links, but its prospective naming and +screen proposals are no longer authoritative. See: -The project is becoming a complete Juice WRLD music management application for Linux: - -- Discover music from the Juice WRLD API catalogue. -- Manage a local music library. -- Embed lyrics into MP3 files. -- Generate compatibility files for players like rmpc. -- Acquire and organize tracks. -- Provide a clean, beautiful terminal experience. - -Version 2 should transform the project from a powerful developer tool into a polished application. - ---- - -# New Identity - -## Problem - -The product is now named `999`; `juice-lyrics` remains a compatibility command. - -The project now includes: - -- Music discovery. -- Library management. -- Downloads. -- Metadata. -- Player integration. -- Terminal UI. - -A new name should represent a complete Juice WRLD music hub rather than only lyrics. - ---- - -# Possible Names - -## 999 - -Concept: - -Juice WRLD's iconic "999" philosophy. - -Advantages: - -- Instantly recognizable to fans. -- Short command. -- Easy to remember. -- Fits a Linux CLI aesthetic. - -Possible command: - - -999 - - -or: - - -999 search "Rental" -999 sync -999 get "Rental" - - ---- - -## Abyss - -Concept: - -Inspired by Juice WRLD themes and darker aesthetics. - -Advantages: - -- Professional sounding. -- Fits terminal applications. -- Unique identity. - -Possible command: - - -abyss - - ---- - -## JuiceBox - -Concept: - -A friendly music library hub. - -Advantages: - -- Easy to understand. -- More approachable. - -Possible command: - - -jbox - - ---- - -# Recommended Direction - -999 is currently the strongest candidate. - -Final naming decision should happen after exploring branding, logo ideas, and command usability. - ---- - -# User Experience Goals - -## Current Problem - -The current application is powerful but technical. - -Example: - -Current workflow: - - -999 acquire search "Rental" - -999 acquire add "Rental" --index 1 - -999 acquire run - - -This works, but it feels like developer tooling. - ---- - -## v2 Goal - -The user should think: - -"I want this song." - -Not: - -"I need to understand acquisition jobs." - ---- - -# New CLI Philosophy - -The CLI should support two levels: - -## Simple commands - -For normal users: - - -999 search "Rental" - -999 get "Rental" - -999 sync - -999 status - - ---- - -## Advanced commands - -For power users: - - -999 queue - -999 doctor - -999 restore - -999 config - - -The powerful backend should remain available without forcing complexity on beginners. - ---- - -# Proposed Command Structure - -## Open Application - - -999 - - -Launches the interactive TUI. - ---- - -## Search Catalogue - - -999 search "Rental" - - -Shows: - -- Song title. -- Era. -- Category. -- Lyrics availability. -- Download availability. - -Example: - - -Rental (v1) - -Era: DRFL -Lyrics: Synced -Download: Available - -[d] Download -[i] Info -[l] Lyrics - - ---- - -## Download Music - -Simple: - - -999 get "Rental" - - -Should: - -1. Search catalogue. -2. Select best match. -3. Download. -4. Validate file. -5. Embed lyrics. -6. Generate a same-basename LRC beside the audio if possible. -7. Add to library. - ---- - -## Library Sync - - -999 sync - - -Should: - -- Scan music folder. -- Find new files. -- Match metadata. -- Embed lyrics. -- Update rmpc files. - ---- - -## Library Status - - -999 status - - -Example: - - -Library - -Tracks: 250 - -Lyrics: -Synced: 180 -Plain: 50 -Missing: 20 - -rmpc: -LRC files: 180 - - ---- - -# TUI Vision - -The main interface should be a terminal dashboard. - -Goals: - -- Fast. -- Keyboard driven. -- Beautiful. -- Linux friendly. - ---- - -# Main Screens - -## 1. Browse - -Purpose: - -Discover songs. - -Features: - -- Search. -- Filters. -- Era selection. -- Lyrics preview. -- Download button. - -Example: - - -999 — Browse - -Search: rental - -Rental v1 -DRFL -Synced Lyrics -Download Available - -Rental v2 -POST -No Lyrics - - ---- - -## 2. Library - -Purpose: - -Manage local music. - -Shows: - -- Track list. -- Lyrics status. -- Sync status. -- Missing metadata. - ---- - -## 3. Downloads - -Purpose: - -Manage acquisition queue. - -Shows: - -- Active downloads. -- Completed downloads. -- Failed downloads. -- Retry options. - -Avoid exposing raw UUID job IDs. - -Use: - - -Download #1 -Download #2 - - ---- - -## 4. Song Details - -Shows: - -- Title. -- Era. -- Producers. -- Metadata. -- Lyrics preview. -- File information. - ---- - -# Lyrics Design - -The application must preserve the existing philosophy. - -## Embedded lyrics - -Primary source. - -Used for: - -- Android players. -- Portable files. -- Long-term storage. - -Formats: - -- SYLT for synced lyrics. -- USLT for plain lyrics. - ---- - -## LRC - -Compatibility layer. - -Used for: - -- rmpc. -- External lyric players. - -Rules: - -- Only generate from timestamped lyrics. -- Never invent timestamps. -- Keep each LRC beside its audio file with the same basename. -- Do not derive current output from the deprecated global `lyrics_dir` setting. - ---- - -# Visual Style - -The application should fit Linux terminal workflows. - -Design goals: - -- Minimal. -- Fast. -- Keyboard focused. -- Customizable. - -Influences: - -- rmpc. -- lazygit. -- terminal file managers. -- modern TUI applications. - ---- - -# Technical Rules - -The v2 interface must remain separate from the backend. - -The TUI should not: - -- Modify ID3 tags directly. -- Handle API requests directly. -- Manage downloads directly. - -Instead: - -UI - | - v -Backend services - | - v -Files/API/Players - ---- - -# Development Order - -## Phase 1 - -Design: - -- Final name. -- Branding. -- CLI commands. -- TUI layout. - -## Phase 2 - -Migration: - -- New command. -- Backwards compatibility. -- Data migration. - -## Phase 3 - -CLI improvements: - -- Friendly commands. -- Better output. -- Simplified workflows. - -## Phase 4 - -TUI: - -- Browse. -- Library. -- Queue. -- Settings. - -## Phase 5 - -Release: - -- Version 2.0. -- Documentation. -- Packaging. - ---- - -# Current Status - -Backend is considered stable. - -Before v2 implementation: - -- 80 tests passing. -- Acquisition verified. -- Lyrics engine verified. -- rmpc integration verified. - -The next major milestone is turning the stable engine into a polished user experience. +- `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. From 8a0e7235a541036588c06283761c831d5a212fba Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 15 Sep 2026 19:39:37 +0100 Subject: [PATCH 45/62] Add manual catalogue identity locking --- AGENTS.md | 2 + README.md | 4 + docs/DECISIONS.md | 7 + docs/PROJECT_STATE.md | 65 +++- docs/ROADMAP.md | 21 +- docs/UI_DESIGN.md | 4 +- docs/USER_FLOWS.md | 8 + docs/USER_GUIDE.md | 19 +- src/juice_lyrics/cli.py | 12 +- src/juice_lyrics/services/__init__.py | 12 + src/juice_lyrics/services/identity_rebuild.py | 39 +- src/juice_lyrics/services/library_identity.py | 5 + .../services/library_index_sync.py | 3 + src/juice_lyrics/services/library_status.py | 14 + src/juice_lyrics/services/library_sync.py | 93 ++++- src/juice_lyrics/services/manual_identity.py | 201 +++++++++++ src/juice_lyrics/tui/app.py | 53 ++- src/juice_lyrics/tui/help.py | 2 + src/juice_lyrics/tui/screens/library.py | 290 ++++++++++++++- tests/test_identity_rebuild.py | 101 +++++- tests/test_library_index_sync.py | 57 ++- tests/test_library_sync_service.py | 68 ++++ tests/test_manual_identity.py | 334 ++++++++++++++++++ tests/test_tui_browse.py | 1 + tests/test_tui_library.py | 165 +++++++++ 25 files changed, 1524 insertions(+), 56 deletions(-) create mode 100644 src/juice_lyrics/services/manual_identity.py create mode 100644 tests/test_manual_identity.py diff --git a/AGENTS.md b/AGENTS.md index 934aae1..012cd4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,8 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. - 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 diff --git a/README.md b/README.md index c1e96f3..b22a278 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,10 @@ 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. The CLI remains available for scripting and automation. `999 sync` remembers files it has already processed, so unchanged verified files are skipped. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 6230de1..92e30d6 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -190,6 +190,13 @@ 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 diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index beca3ba..08978f5 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,8 +1,9 @@ # 999 project state -This is the canonical detailed handoff for the current application. It records -the repository state after `31ebaf2 Add one-button Library Sync`. Read the code -and tests if a later working tree disagrees with this document. +This is the canonical detailed handoff for the current application. The +one-button Sync baseline is `31ebaf2`; manual catalogue matching and +file-bound identity locking are now integrated on top of it. Read the code and +tests if a later working tree disagrees with this document. ## Repository checkpoint @@ -14,9 +15,11 @@ and tests if a later working tree disagrees with this document. - Python package: `juice_lyrics` - Distribution: `juice-wrld-lyrics` - XDG storage namespace: `juice-lyrics` -- Last verified product commit: `31ebaf2` -- Verification at that commit: 410 tests passed; 14 isolated recovery smoke - tests passed; compileall and `git diff --check` passed. +- 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -115,6 +118,33 @@ Bandit → song_id 94107 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 @@ -150,8 +180,6 @@ real config, state, backups, queue, sidecars, or rmpc configuration. ## Known limitations and risks -- The conservative matcher intentionally leaves ambiguous/no-result songs - Unknown; manual match and identity locking are not implemented yet. - Library has attention/details but not a consolidated Issues experience. - Active download cancellation is not implemented. - Acquisition/post-processing remains MP3-focused; FLAC/M4A support is for @@ -181,17 +209,16 @@ ambiguous/destructive work → explicit user decision Keep normal Library UX centered on **Sync Library** and future **Issues**; advanced repair/recovery must not overwhelm normal use. -1. Manual catalogue match and identity locking -2. Library Issues / Health experience -3. Duplicate detector -4. Metadata repair -5. Missing Library -6. `999 doctor` / diagnostics -7. Shell completion -8. Final performance/reliability acceptance -9. Packaging and clean installation -10. GitHub presentation/distribution -11. Beta release +1. Library Issues / Health experience +2. Duplicate detector +3. Metadata repair +4. Missing Library +5. `999 doctor` / diagnostics +6. Shell completion +7. Final performance/reliability acceptance +8. Packaging and clean installation +9. GitHub presentation/distribution +10. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 8127a0d..a736a72 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,17 +15,16 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Manual catalogue match and identity locking -2. Library Issues / Health experience -3. Duplicate detector -4. Metadata repair -5. Missing Library -6. `999 doctor` / diagnostics -7. Shell completion -8. Final performance/reliability acceptance -9. Packaging and clean installation -10. GitHub presentation/distribution -11. Beta release +1. Library Issues / Health experience +2. Duplicate detector +3. Metadata repair +4. Missing Library +5. `999 doctor` / diagnostics +6. Shell completion +7. Final performance/reliability acceptance +8. Packaging and clean installation +9. GitHub presentation/distribution +10. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index b6da38e..f42c382 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -285,6 +285,8 @@ m Maintain lyrics v Verify b Backups p Player integration +c Match manually +u Unlock manual match enter Details; l refresh selected lyrics @@ -382,7 +384,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `m` maintain; `r` local refresh, `v`, `b`, `p` are secondary | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `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 | diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 9fcba2f..0e9ff1d 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -371,6 +371,8 @@ b Backups enter Details; l refresh selected lyrics +c Match manually; u unlock manual match + --- @@ -423,6 +425,12 @@ catalogue results remain Unknown without making the local Library unusable. 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. + --- diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index c0971d4..ca85feb 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -76,6 +76,19 @@ 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**. +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 @@ -137,8 +150,10 @@ Apply it only after reviewing the counts: 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, ignores stale external records, makes a complete state -backup, and commits the result atomically. Ambiguous tracks become Unknown. +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. diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 9147958..c492f32 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -1138,11 +1138,16 @@ def command_state(args: argparse.Namespace, settings: Settings, use_color: bool) 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) + 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 @@ -1699,6 +1704,11 @@ def build_parser() -> argparse.ArgumentParser: 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 diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 0b1562e..20a6553 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -86,6 +86,13 @@ IdentityBackfillResult, backfill_catalogue_identities, ) +from .manual_identity import ( + ManualIdentityDependencies, + ManualIdentityResult, + is_identity_locked, + set_manual_identity, + unlock_manual_identity, +) from .identity_rebuild import ( IdentityChange, IdentityRebuildDependencies, @@ -143,6 +150,8 @@ "LibraryStatus", "IdentityBackfillDependencies", "IdentityBackfillResult", + "ManualIdentityDependencies", + "ManualIdentityResult", "LibraryLrcStatus", "LibraryLyricStatus", "LibraryMatchStatus", @@ -191,6 +200,9 @@ "IdentityRebuildProgress", "IdentityRebuildResult", "backfill_catalogue_identities", + "is_identity_locked", + "set_manual_identity", + "unlock_manual_identity", "execute_library_sync", "execute_library_sync_preview", "execute_stale_state_cleanup", diff --git a/src/juice_lyrics/services/identity_rebuild.py b/src/juice_lyrics/services/identity_rebuild.py index 8caa2ba..c072e1d 100644 --- a/src/juice_lyrics/services/identity_rebuild.py +++ b/src/juice_lyrics/services/identity_rebuild.py @@ -13,10 +13,25 @@ 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_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) @@ -37,6 +52,19 @@ def current_tracks(self) -> int: 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: @@ -151,6 +179,7 @@ def execute_catalogue_identity_rebuild( 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.""" @@ -174,6 +203,14 @@ def execute_catalogue_identity_rebuild( 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) diff --git a/src/juice_lyrics/services/library_identity.py b/src/juice_lyrics/services/library_identity.py index ee697d6..2681ec5 100644 --- a/src/juice_lyrics/services/library_identity.py +++ b/src/juice_lyrics/services/library_identity.py @@ -11,6 +11,7 @@ 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) @@ -109,6 +110,10 @@ def backfill_catalogue_identities( 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, diff --git a/src/juice_lyrics/services/library_index_sync.py b/src/juice_lyrics/services/library_index_sync.py index cdae53f..e051efd 100644 --- a/src/juice_lyrics/services/library_index_sync.py +++ b/src/juice_lyrics/services/library_index_sync.py @@ -17,6 +17,7 @@ IdentityBackfillDependencies, backfill_catalogue_identities, ) +from .manual_identity import IDENTITY_LOCK_FIELD, IDENTITY_SOURCE_FIELD from .library_status import ( LibraryMatchStatus, LibrarySnapshot, @@ -224,6 +225,8 @@ def sync_library_index( 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) diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index ce24482..cb13f26 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -21,6 +21,7 @@ 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] @@ -75,6 +76,8 @@ class LibraryTrack: 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 @property def needs_attention(self) -> bool: @@ -421,6 +424,17 @@ def get_library_snapshot( 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) + ), ) ) return LibrarySnapshot(library_path, True, tuple(tracks), warnings, state_signature) diff --git a/src/juice_lyrics/services/library_sync.py b/src/juice_lyrics/services/library_sync.py index 27f6ac2..05f3f0a 100644 --- a/src/juice_lyrics/services/library_sync.py +++ b/src/juice_lyrics/services/library_sync.py @@ -19,6 +19,11 @@ 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): @@ -118,6 +123,7 @@ class TrackSyncPlan: plain_lyrics: str = "" error: str | None = None lrc_path: Path | None = None + identity_locked: bool = False @dataclass(frozen=True, slots=True) @@ -268,6 +274,31 @@ def _state_is_current( 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, *, @@ -317,10 +348,39 @@ def plan_library_sync( try: title = dependencies.search_title(path) results = dependencies.searcher(options.settings, title, refresh=options.refresh) - candidate, _, _, _ = dependencies.matcher(options.settings, path, results, title) + 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: - tracks.append(TrackSyncPlan(path, MatchOutcome.UNRESOLVED, SyncLyricType.NONE)) - _emit(progress, SyncEventKind.UNRESOLVED, path=path) + 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 "") @@ -344,6 +404,7 @@ def plan_library_sync( 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) @@ -432,14 +493,24 @@ def _state_entry( if track.lyric_type is SyncLyricType.SYNCED else "M4A_LYRICS_PLAIN" ) - state.setdefault("files", {})[str(track.path.relative_to(options.music_dir))] = { - "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(), - } + 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( 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/tui/app.py b/src/juice_lyrics/tui/app.py index 493718f..4a29347 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -39,6 +39,11 @@ 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.manual_identity import ( + ManualIdentityResult, + set_manual_identity, + unlock_manual_identity, +) from ..services.identity_rebuild import ( IdentityRebuildPlan, IdentityRebuildResult, @@ -56,7 +61,7 @@ from .screens.browse import BrowseScreen from .screens.dashboard import DashboardScreen from .screens.downloads import DownloadsScreen -from .screens.library import LibraryScreen +from .screens.library import LibraryScreen, ManualMatchDialog from .screens.settings import SettingsScreen from .help import HelpScreen @@ -73,6 +78,7 @@ LibrarySnapshotProvider = Callable[[Any], LibrarySnapshot] LibraryIdentityProvider = Callable[..., IdentityBackfillResult] LibraryIndexSyncProvider = Callable[..., LibraryIndexSyncResult] +ManualIdentityProvider = Callable[..., ManualIdentityResult] IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] @@ -459,7 +465,8 @@ def _get_dom_base(self): MaintenanceDialog, BackupBrowser, RestoreDialog, - RmpcDialog { + RmpcDialog, + ManualMatchDialog { align: center middle; background: transparent; } @@ -474,6 +481,41 @@ def _get_dom_base(self): 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-dialog-title { height: 2; text-style: bold; @@ -886,6 +928,8 @@ def __init__( 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, backup_provider: Callable[[], tuple[BackupRecord, ...]] = list_backups, @@ -925,6 +969,8 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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.backup_provider = backup_provider @@ -966,6 +1012,9 @@ def on_mount(self) -> None: 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, + manual_identity_provider=self.manual_identity_provider, + manual_unlock_provider=self.manual_unlock_provider, ), "library", ) diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index f6c8bab..8a67d2a 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -24,6 +24,8 @@ ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), ("v", "Verify library"), ("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"))), ("Downloads", (("↑/↓ or j/k", "Select queue item"), ("Enter", "Item details"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 0821d40..20344a7 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -28,11 +28,17 @@ ) from ...services.library_identity import IdentityBackfillResult from ...services.library_index_sync import LibraryIndexSyncResult +from ...services.catalogue import CataloguePage, CatalogueSearchResult 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 @@ -44,6 +50,8 @@ IndexSyncProvider = Callable[..., LibraryIndexSyncResult] IdentityRebuildPlanProvider = Callable[..., IdentityRebuildPlan] IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] +ManualSearchProvider = Callable[..., CataloguePage] +ManualIdentityProvider = Callable[..., ManualIdentityResult] PreviewProvider = Callable[[Any], LibrarySyncPlan] ExecutionProvider = Callable[..., LibrarySyncResult] BackupProvider = Callable[[], tuple[BackupRecord, ...]] @@ -157,6 +165,19 @@ class IdentityRebuildOutcome: 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" + + class LibraryDialogAction(Static): can_focus = True @@ -173,6 +194,160 @@ 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 MaintenanceDialog(ModalScreen[LibrarySyncPlan | None]): """Cancel-first confirmation for an already non-mutating maintenance preview.""" @@ -264,6 +439,7 @@ def compose(self) -> Iterable[Widget]: "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)}" ) @@ -484,6 +660,9 @@ def __init__( restore_provider: RestoreProvider, rmpc_status_provider: RmpcStatusProvider, rmpc_setup_provider: RmpcSetupProvider, + manual_search_provider: ManualSearchProvider, + manual_identity_provider: ManualIdentityProvider = set_manual_identity, + manual_unlock_provider: ManualIdentityProvider = unlock_manual_identity, ) -> None: super().__init__("library", "Library") self.settings = settings @@ -498,6 +677,9 @@ def __init__( 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._manual_identity_provider = manual_identity_provider + self._manual_unlock_provider = manual_unlock_provider self.snapshot: LibrarySnapshot | None = None self.filtered_tracks: tuple[LibraryTrack, ...] = () self.selected_index = 0 @@ -525,6 +707,8 @@ def __init__( 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 def compose_content(self) -> Iterable[Widget]: yield Static( @@ -593,6 +777,8 @@ def invalidate_snapshot(self) -> 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._preview_worker = None self._pending_snapshot = None self._pending_identity = None @@ -690,6 +876,12 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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) @@ -704,12 +896,13 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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: - outcome = IdentityOutcome(error="Catalogue identification stopped unexpectedly") - if self._can_render(): - self._apply_identity(outcome) - else: - self._pending_identity = outcome + self._apply_manual_identity( + ManualIdentityOutcome(error="Catalogue match update stopped safely.") + ) elif event.worker is self._preview_worker: if event.state is WorkerState.SUCCESS: outcome = event.worker.result @@ -975,6 +1168,7 @@ def _render_details(self) -> None: 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)}", @@ -994,7 +1188,7 @@ def _update_position(self) -> None: if not self.filtered_tracks: self.query_one("#library-position", Static).update("s Sync Library · m Maintain lyrics · b Backups · ? Help") return - suffix = "Esc Back · l Refresh lyrics · ? Help" if self._details_mode else "s Sync Library · ↑↓ Move · Enter Details · ? Help" + suffix = "Esc Back · c Match manually · u Unlock · l Refresh lyrics · ? Help" if self._details_mode else "s Sync Library · ↑↓ Move · Enter Details · c Match · ? Help" self.query_one("#library-position", Static).update( f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" ) @@ -1017,6 +1211,10 @@ def on_key(self, event: Key) -> None: 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: @@ -1048,6 +1246,86 @@ def on_key(self, event: Key) -> None: event.prevent_default() event.stop() + def _open_manual_match(self) -> None: + track = 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 diff --git a/tests/test_identity_rebuild.py b/tests/test_identity_rebuild.py index c216400..2c1cbc0 100644 --- a/tests/test_identity_rebuild.py +++ b/tests/test_identity_rebuild.py @@ -27,6 +27,7 @@ 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: @@ -54,6 +55,8 @@ def _track(root: Path, relative: str, *, title: str | None = None, album: str = artist="Juice WRLD", album=album, media_format=path.suffix[1:].upper(), + content_sha256=sha256_file(path), + content_fingerprint=file_fingerprint(path), ) @@ -109,6 +112,93 @@ def test_rebuild_preview_is_read_only_and_reports_current_identity_and_stale_cou 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( @@ -384,6 +474,15 @@ def test_cli_rebuild_preview_requires_yes_and_apply_reports_audit(tmp_path, monk ) assert cli.command_state(apply_args, plan.settings, False) == 0 output = capsys.readouterr().out - assert executions == [(plan, {"refresh": True})] + 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_index_sync.py b/tests/test_library_index_sync.py index 8899fed..b21534e 100644 --- a/tests/test_library_index_sync.py +++ b/tests/test_library_index_sync.py @@ -101,7 +101,12 @@ def test_changed_audio_replaces_stale_identity_and_ambiguous_stays_unknown(tmp_p 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"}) + 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"}] @@ -111,6 +116,8 @@ def test_changed_audio_replaces_stale_identity_and_ambiguous_stays_unknown(tmp_p 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"}] @@ -212,6 +219,54 @@ def searcher(*args, **kwargs): 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() diff --git a/tests/test_library_sync_service.py b/tests/test_library_sync_service.py index 39caa97..be769e7 100644 --- a/tests/test_library_sync_service.py +++ b/tests/test_library_sync_service.py @@ -264,6 +264,74 @@ def test_frontend_preview_can_scope_one_track_and_force_refresh(tmp_path): 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") 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_tui_browse.py b/tests/test_tui_browse.py index a3ab305..349610c 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -884,6 +884,7 @@ 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", + "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 diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index f520d85..2138a48 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -1,4 +1,5 @@ import asyncio +from dataclasses import replace from datetime import datetime, timezone from pathlib import Path import sys @@ -12,6 +13,8 @@ from juice_lyrics.config.settings import Settings from juice_lyrics.services import ( CatalogueFilterMetadata, + CataloguePage, + CatalogueSearchResult, LibraryLrcStatus, LibraryLyricStatus, LibraryMatchStatus, @@ -24,6 +27,8 @@ IdentityRebuildPlan, IdentityRebuildProgress, IdentityRebuildResult, + LyricAvailability, + ManualIdentityResult, QueueSnapshot, ) from juice_lyrics.services.library_sync import ( @@ -99,6 +104,8 @@ def _track( warning: str | None = None, media_format: str = "MP3", synchronized_source: bool = False, + identity_locked: bool = False, + identity_source: str | None = None, ) -> LibraryTrack: path = root / name lrc_path = path.with_suffix(".lrc") if lrc is not LibraryLrcStatus.NONE else None @@ -118,6 +125,8 @@ def _track( warning=warning, media_format=media_format, synchronized_source=synchronized_source, + identity_locked=identity_locked, + identity_source=identity_source, ) @@ -170,6 +179,162 @@ async def _open_library(app: JuiceLyricsApp, pilot): 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_library_replaces_placeholder_and_renders_summary_details_and_states(tmp_path): root = tmp_path / "music" synced = _track(root, "A Synced.mp3") From d72cad862576c8adbc5ee255cfff4f8c54e97501 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Thu, 17 Sep 2026 10:41:42 +0100 Subject: [PATCH 46/62] Add Library Issues health workflow --- AGENTS.md | 2 +- README.md | 4 +- docs/PROJECT_STATE.md | 49 ++-- docs/ROADMAP.md | 21 +- docs/UI_DESIGN.md | 7 +- docs/USER_FLOWS.md | 14 +- docs/USER_GUIDE.md | 14 +- src/juice_lyrics/services/__init__.py | 14 ++ src/juice_lyrics/services/library_issues.py | 185 ++++++++++++++ src/juice_lyrics/services/library_status.py | 2 + src/juice_lyrics/tui/app.py | 44 +++- src/juice_lyrics/tui/help.py | 1 + src/juice_lyrics/tui/screens/library.py | 254 ++++++++++++++++++-- tests/test_library_issues.py | 223 +++++++++++++++++ tests/test_tui_browse.py | 1 + tests/test_tui_library.py | 128 +++++++++- 16 files changed, 896 insertions(+), 67 deletions(-) create mode 100644 src/juice_lyrics/services/library_issues.py create mode 100644 tests/test_library_issues.py diff --git a/AGENTS.md b/AGENTS.md index 012cd4e..85bdddb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,6 +78,6 @@ ambiguous or destructive work requires an explicit user decision. ## Roadmap discipline The current roadmap is in `docs/PROJECT_STATE.md` and `docs/ROADMAP.md`. Keep -normal Library UX centered on **Sync Library** and future **Issues**; 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/README.md b/README.md index b22a278..468fb90 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,9 @@ Your Juice WRLD folder is kept together: 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. **Maintain lyrics** +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. **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. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 08978f5..86cd384 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,9 +1,9 @@ # 999 project state -This is the canonical detailed handoff for the current application. The -one-button Sync baseline is `31ebaf2`; manual catalogue matching and -file-bound identity locking are now integrated on top of it. Read the code and -tests if a later working tree disagrees with this document. +This is the canonical detailed handoff for the current application. One-button +Sync, manual catalogue locking, and the snapshot-backed Library Issues workflow +are integrated. Read the code and tests if a later working tree disagrees with +this document. ## Repository checkpoint @@ -20,6 +20,9 @@ tests if a later working tree disagrees with this document. - 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -41,6 +44,7 @@ Library is the maintenance centre. The primary routine action is: ```text s → Sync Library +a → Issues ``` `?` opens the complete scrollable key guide globally. Common actions remain in @@ -83,6 +87,21 @@ Catalogue identity and local lyric health are separate axes. A healthy 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, healthy tracks, and issue rows. `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. + - 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 @@ -180,7 +199,6 @@ real config, state, backups, queue, sidecars, or rmpc configuration. ## Known limitations and risks -- Library has attention/details but not a consolidated Issues experience. - Active download cancellation is not implemented. - Acquisition/post-processing remains MP3-focused; FLAC/M4A support is for existing local-library files. @@ -206,19 +224,18 @@ common safe routine work → automatic/simple ambiguous/destructive work → explicit user decision ``` -Keep normal Library UX centered on **Sync Library** and future **Issues**; +Keep normal Library UX centered on **Sync Library** and **Issues**; advanced repair/recovery must not overwhelm normal use. -1. Library Issues / Health experience -2. Duplicate detector -3. Metadata repair -4. Missing Library -5. `999 doctor` / diagnostics -6. Shell completion -7. Final performance/reliability acceptance -8. Packaging and clean installation -9. GitHub presentation/distribution -10. Beta release +1. Duplicate detector +2. Metadata repair +3. Missing Library +4. `999 doctor` / diagnostics +5. Shell completion +6. Final performance/reliability acceptance +7. Packaging and clean installation +8. GitHub presentation/distribution +9. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index a736a72..daddebc 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -10,21 +10,20 @@ common safe routine work → automatic/simple ambiguous/destructive work → explicit user decision ``` -Normal Library UX stays centered on **Sync Library** and future **Issues**. +Normal Library UX stays centered on **Sync Library** and **Issues**. Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Library Issues / Health experience -2. Duplicate detector -3. Metadata repair -4. Missing Library -5. `999 doctor` / diagnostics -6. Shell completion -7. Final performance/reliability acceptance -8. Packaging and clean installation -9. GitHub presentation/distribution -10. Beta release +1. Duplicate detector +2. Metadata repair +3. Missing Library +4. `999 doctor` / diagnostics +5. Shell completion +6. Final performance/reliability acceptance +7. Packaging and clean installation +8. GitHub presentation/distribution +9. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index f42c382..de91cdf 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -267,8 +267,8 @@ Example: Library -315 songs · Fully covered 287 · Plain only 14 · Missing 8 · Unmatched 6 -Formats · MP3 170 · FLAC 85 · M4A 60 +315 tracks · 300 healthy · 15 issues +Fully covered 287 · Catalogue unknown 6 · MP3 170 · FLAC 85 · M4A 60 Rental.flac Catalogue match ✓ @@ -280,6 +280,7 @@ Actions: s Sync Library +a Issues r Refresh m Maintain lyrics v Verify @@ -384,7 +385,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `c` manual match; `u` unlock, `m`, `r`, `v`, `b`, `p` are secondary | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `a` Issues, `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 | diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 0e9ff1d..59a3c89 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -361,6 +361,8 @@ Actions: s Sync Library +a Issues + r Refresh m Maintain lyrics @@ -431,6 +433,11 @@ 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. + --- @@ -579,7 +586,6 @@ Ask only before: # Forward flows -The next planned normal-user addition is an Issues/Health experience backed by -manual catalogue matching and identity locking. The ordered roadmap lives in -`PROJECT_STATE.md`; speculative screen lists are intentionally not duplicated -here. +Sync Library, Issues, and manual catalogue matching now 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 ca85feb..8429ad8 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -58,6 +58,7 @@ adjacent `.lrc`. 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; * **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; @@ -76,6 +77,15 @@ 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**. +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 healthy; 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 @@ -99,8 +109,8 @@ 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 healthy track may still show **Catalogue match: Unknown**; that only means automatic refresh cannot identify a safe catalogue -record yet. The Library shows that count separately from songs needing lyric -attention. +record yet. It appears in Issues as an identity decision, not as a claim that +the existing lyrics are broken. ## Check health diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 20a6553..f427cd3 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -86,6 +86,14 @@ IdentityBackfillResult, backfill_catalogue_identities, ) +from .library_issues import ( + LibraryHealth, + LibraryIssue, + LibraryIssueAction, + LibraryIssueCategory, + LibraryIssueSeverity, + get_library_health, +) from .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -148,6 +156,11 @@ "DownloadExecutionStatus", "DownloadProgress", "LibraryStatus", + "LibraryHealth", + "LibraryIssue", + "LibraryIssueAction", + "LibraryIssueCategory", + "LibraryIssueSeverity", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", @@ -200,6 +213,7 @@ "IdentityRebuildProgress", "IdentityRebuildResult", "backfill_catalogue_identities", + "get_library_health", "is_identity_locked", "set_manual_identity", "unlock_manual_identity", diff --git a/src/juice_lyrics/services/library_issues.py b/src/juice_lyrics/services/library_issues.py new file mode 100644 index 0000000..840e6e8 --- /dev/null +++ b/src/juice_lyrics/services/library_issues.py @@ -0,0 +1,185 @@ +"""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" + + +@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" + 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) + _append_once(details, "Supported embedded lyrics are missing or could not be read.") + if not verification_problem: + summary = summary or "Embedded lyrics missing" + 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 index cb13f26..96a5cbb 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -78,6 +78,7 @@ class LibraryTrack: sidecar_fingerprint: tuple[int, int, int, int, int] | None = None identity_source: str | None = None identity_locked: bool = False + verification_error: str | None = None @property def needs_attention(self) -> bool: @@ -435,6 +436,7 @@ def get_library_snapshot( state_status is LibraryStateStatus.CURRENT and is_identity_locked(entry) ), + verification_error=verification if not valid else None, ) ) return LibrarySnapshot(library_path, True, tuple(tracks), warnings, state_signature) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 4a29347..442d88a 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -61,7 +61,7 @@ from .screens.browse import BrowseScreen from .screens.dashboard import DashboardScreen from .screens.downloads import DownloadsScreen -from .screens.library import LibraryScreen, ManualMatchDialog +from .screens.library import LibraryIssuesDialog, LibraryScreen, ManualMatchDialog from .screens.settings import SettingsScreen from .help import HelpScreen @@ -466,7 +466,8 @@ def _get_dom_base(self): BackupBrowser, RestoreDialog, RmpcDialog, - ManualMatchDialog { + ManualMatchDialog, + LibraryIssuesDialog { align: center middle; background: transparent; } @@ -516,6 +517,45 @@ def _get_dom_base(self): 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-dialog-title { height: 2; text-style: bold; diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index 8a67d2a..03c0ca4 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -21,6 +21,7 @@ ("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 Library"), + ("a", "Open Library Issues"), ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), ("v", "Verify library"), ("b", "Browse backups"), ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 20344a7..51f8fde 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -1,7 +1,7 @@ from __future__ import annotations from collections.abc import Callable, Iterable -from dataclasses import dataclass +from dataclasses import dataclass, replace from enum import Enum from pathlib import Path from typing import Any @@ -28,6 +28,13 @@ ) from ...services.library_identity import IdentityBackfillResult from ...services.library_index_sync import LibraryIndexSyncResult +from ...services.library_issues import ( + LibraryHealth, + LibraryIssue, + LibraryIssueAction, + LibraryIssueCategory, + get_library_health, +) from ...services.catalogue import CataloguePage, CatalogueSearchResult from ...services.identity_rebuild import ( IdentityRebuildPlan, @@ -178,6 +185,12 @@ class ManualIdentityOutcome: action: str = "match" +@dataclass(frozen=True, slots=True) +class LibraryIssueChoice: + reference: str + action: LibraryIssueAction + + class LibraryDialogAction(Static): can_focus = True @@ -348,6 +361,139 @@ def on_key(self, event: Key) -> None: 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} healthy · {self.health.issue_count} issues" + ) + if not issues: + self.query_one("#library-issues-list", Static).update("Library is healthy") + 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.")) + 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.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 == "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 MaintenanceDialog(ModalScreen[LibrarySyncPlan | None]): """Cancel-first confirmation for an already non-mutating maintenance preview.""" @@ -712,8 +858,8 @@ def __init__( def compose_content(self) -> Iterable[Widget]: yield Static( - "0 songs · Fully covered 0 · Plain only 0 · Missing 0 · Need attention 0\n" - "Catalogue unmatched 0 · MP3 0 · FLAC 0 · M4A 0", + "0 tracks · 0 healthy · 0 issues\n" + "Fully covered 0 · Catalogue unknown 0 · MP3 0 · FLAC 0 · M4A 0", id="library-summary", markup=False, ) @@ -735,7 +881,7 @@ def compose_content(self) -> Iterable[Widget]: 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 · ↑↓ Move · Enter Details · m Maintain lyrics · ? Help", id="library-position", markup=False) + yield Static("s Sync Library · a Issues · ↑↓ Move · Enter Details · ? Help", id="library-position", markup=False) def action_focus_search(self) -> None: self.query_one("#library-query", Input).focus() @@ -985,11 +1131,10 @@ def _apply_snapshot(self, outcome: SnapshotOutcome) -> None: elif completion is not None: self._set_status(completion[0], error=completion[1]) elif action == "verify": - healthy = outcome.snapshot.total_track_count - outcome.snapshot.needs_attention_count + health = get_library_health(outcome.snapshot) self._set_status( - f"Verification complete · {healthy} healthy · " - f"{outcome.snapshot.needs_attention_count} need attention · " - f"{outcome.snapshot.unmatched_count} catalogue unknown" + f"Verification complete · {health.healthy_count} healthy · " + f"{health.issue_count} issues" ) if outcome.snapshot.needs_attention_count: self.query_one("#library-filter", Select).value = LibraryFilter.ATTENTION.value @@ -1065,6 +1210,33 @@ def _apply_preview(self, outcome: PreviewOutcome) -> None: 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( @@ -1092,10 +1264,11 @@ def _render_summary(self) -> None: snapshot = self.snapshot if snapshot is None: return + health = get_library_health(snapshot) self.query_one("#library-summary", Static).update( - f"{snapshot.total_track_count} songs · Fully covered {snapshot.fully_covered_count} · " - f"Plain only {snapshot.plain_only_count} · Missing {snapshot.missing_lyrics_count} · " - f"Need attention {snapshot.needs_attention_count}\nCatalogue unmatched {snapshot.unmatched_count} · " + f"{snapshot.total_track_count} tracks · {health.healthy_count} healthy · " + f"{health.issue_count} issues\nFully 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')}" ) @@ -1140,9 +1313,13 @@ def _render_tracks(self) -> None: self.query_one("#library-tracks", Static).update(message) return lines = [] + issue_references = { + issue.track.reference + for issue in get_library_health(self.snapshot).issues + } if self.snapshot is not None else set() for index, track in enumerate(self.filtered_tracks): marker = ">" if index == self.selected_index else " " - attention = "!" if track.needs_attention else " " + attention = "!" if track.reference in issue_references 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)}" @@ -1158,6 +1335,14 @@ def _render_details(self) -> None: 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, "", @@ -1174,7 +1359,7 @@ def _render_details(self) -> None: 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"Attention {'Yes' if track.needs_attention else 'No'}", + 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: @@ -1186,9 +1371,9 @@ def _render_details(self) -> None: def _update_position(self) -> None: if not self.filtered_tracks: - self.query_one("#library-position", Static).update("s Sync Library · m Maintain lyrics · b Backups · ? Help") + self.query_one("#library-position", Static).update("s Sync Library · a Issues · m Maintain lyrics · ? Help") return - suffix = "Esc Back · c Match manually · u Unlock · l Refresh lyrics · ? Help" if self._details_mode else "s Sync Library · ↑↓ Move · Enter Details · c Match · ? Help" + suffix = "Esc Back · a Issues · c Match · u Unlock · l Refresh lyrics · ? Help" if self._details_mode else "s Sync Library · a Issues · ↑↓ Move · Enter Details · ? Help" self.query_one("#library-position", Static).update( f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" ) @@ -1200,6 +1385,8 @@ def on_key(self, event: Key) -> None: return if event.key == "s": self.sync_library() + elif event.key == "a": + self._open_issues() elif event.key == "m": self.generate_preview(action="maintain") elif event.key == "v": @@ -1246,8 +1433,41 @@ def on_key(self, event: Key) -> None: event.prevent_default() event.stop() - def _open_manual_match(self) -> None: - track = self.selected_track + 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 _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) + + 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 diff --git a/tests/test_library_issues.py b/tests/test_library_issues.py new file mode 100644 index 0000000..1f4a04a --- /dev/null +++ b/tests/test_library_issues.py @@ -0,0 +1,223 @@ +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 + + +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[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_tui_browse.py b/tests/test_tui_browse.py index 349610c..1986f7b 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -884,6 +884,7 @@ 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", "Choose and lock a catalogue match", "Unlock and clear a manual match", "Inspect setting", "Confirm immediately"): assert label in guide diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 2138a48..5f8a205 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -106,6 +106,7 @@ def _track( synchronized_source: bool = False, identity_locked: bool = False, identity_source: str | None = None, + verification_error: str | None = None, ) -> LibraryTrack: path = root / name lrc_path = path.with_suffix(".lrc") if lrc is not LibraryLrcStatus.NONE else None @@ -127,6 +128,7 @@ def _track( synchronized_source=synchronized_source, identity_locked=identity_locked, identity_source=identity_source, + verification_error=verification_error, ) @@ -335,6 +337,113 @@ async def run_case(search): 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 issues" 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 issues" 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 "1 healthy · 0 issues" 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 "0 healthy · 1 issues" in _text(app, "#library-summary") + await pilot.press("a") + assert "Embedded lyrics" in _text(app, "#library-issues-detail") + + 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") @@ -361,9 +470,8 @@ async def scenario(): screen = await _open_library(app, pilot) assert screen.__class__.__name__ == "LibraryScreen" summary = _text(app, "#library-summary") - assert "3 songs" in summary and "Catalogue unmatched 1" in summary - assert "Plain only 1" in summary and "Missing 1" in summary - assert "Need attention 1" in summary + assert "3 tracks" in summary and "Catalogue unknown 1" in summary + assert "1 healthy" in summary and "2 issues" in summary assert "MP3 3" in summary and "FLAC 0" in summary and "M4A 0" in summary rows = _text(app, "#library-tracks") assert rows.index("A Synced") < rows.index("B Plain") < rows.index("C Unknown") @@ -374,7 +482,7 @@ async def scenario(): 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 "Attention Yes" in details + assert "Library state New" in details and "Library issue New track" in details assert "Recorded LRC is missing" in details await pilot.press("up", "k", "end", "home") assert screen.selected_track.reference == synced.reference @@ -649,7 +757,7 @@ async def scenario(): await pilot.pause() assert "Catalogue identification unavailable" in _text(app, "#library-status") assert "Fully covered 1" in _text(app, "#library-summary") - assert "Need attention 0" in _text(app, "#library-summary") + assert "1 issues" in _text(app, "#library-summary") assert "Catalogue match Unknown" in _text(app, "#library-details") asyncio.run(scenario()) @@ -812,7 +920,7 @@ async def scenario(): screen = await _open_library(app, pilot) summary = _text(app, "#library-summary") assert "Fully covered 3" in summary - assert "Plain only 0" in summary + assert "3 healthy" in summary and "0 issues" 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") @@ -829,7 +937,7 @@ def test_healthy_unmatched_flac_is_covered_without_lyric_attention(tmp_path): matched=False, lyric=LibraryLyricStatus.PLAIN, media_format="FLAC", - state=LibraryStateStatus.NEW, + state=LibraryStateStatus.CURRENT, ) preview_calls = [] @@ -843,13 +951,13 @@ async def scenario(): screen = await _open_library(app, pilot) summary = _text(app, "#library-summary") assert "Fully covered 1" in summary - assert "Need attention 0" in summary - assert "Catalogue unmatched 1" in summary + assert "1 issues" 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 "Attention No" in details + assert "Library issue Catalogue match unknown" in details assert "Automatic refresh requires a catalogue match" in details await pilot.press("m") From 84096ef28224a40a8dfc28ab572f684b42c453f2 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 19 Sep 2026 14:22:22 +0100 Subject: [PATCH 47/62] Add read-only Library duplicate detection --- AGENTS.md | 3 + README.md | 8 +- docs/PROJECT_STATE.md | 42 +++- docs/ROADMAP.md | 17 +- docs/UI_DESIGN.md | 3 +- docs/USER_FLOWS.md | 10 +- docs/USER_GUIDE.md | 9 + src/juice_lyrics/services/__init__.py | 10 + .../services/library_duplicates.py | 205 ++++++++++++++++++ src/juice_lyrics/services/library_status.py | 7 + src/juice_lyrics/tui/app.py | 53 ++++- src/juice_lyrics/tui/help.py | 1 + src/juice_lyrics/tui/screens/library.py | 132 ++++++++++- tests/test_library_duplicates.py | 194 +++++++++++++++++ tests/test_library_status.py | 1 + tests/test_tui_browse.py | 1 + tests/test_tui_library.py | 83 +++++++ 17 files changed, 749 insertions(+), 30 deletions(-) create mode 100644 src/juice_lyrics/services/library_duplicates.py create mode 100644 tests/test_library_duplicates.py diff --git a/AGENTS.md b/AGENTS.md index 85bdddb..4b99854 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,7 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. - 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` - Matching/identity: `src/juice_lyrics/library/matching.py` and `src/juice_lyrics/services/library_identity.py` - State: `src/juice_lyrics/state.py` @@ -74,6 +75,8 @@ git diff --check 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. ## Roadmap discipline diff --git a/README.md b/README.md index 468fb90..62e3c3d 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,9 @@ Open `999`, choose **Library**, then press `s` for **Sync Library**. It discover 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. **Maintain lyrics** +repair. Press `d` for a read-only **Duplicates** view showing exact file copies +and conservative probable-recording groups with their evidence and paths. +**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. @@ -58,6 +60,10 @@ 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. + The CLI remains available for scripting and automation. `999 sync` remembers files it has already processed, so unchanged verified files are skipped. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 86cd384..848637d 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,9 +1,9 @@ # 999 project state This is the canonical detailed handoff for the current application. One-button -Sync, manual catalogue locking, and the snapshot-backed Library Issues workflow -are integrated. Read the code and tests if a later working tree disagrees with -this document. +Sync, manual catalogue locking, snapshot-backed Library Issues, and read-only +duplicate review are integrated. Read the code and tests if a later working +tree disagrees with this document. ## Repository checkpoint @@ -23,6 +23,9 @@ this document. - 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -45,6 +48,7 @@ Library is the maintenance centre. The primary routine action is: ```text s → Sync Library a → Issues +d → Duplicates ``` `?` opens the complete scrollable key guide globally. Common actions remain in @@ -102,6 +106,21 @@ 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. + - 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 @@ -227,15 +246,14 @@ 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. Duplicate detector -2. Metadata repair -3. Missing Library -4. `999 doctor` / diagnostics -5. Shell completion -6. Final performance/reliability acceptance -7. Packaging and clean installation -8. GitHub presentation/distribution -9. Beta release +1. Metadata repair +2. Missing Library +3. `999 doctor` / diagnostics +4. Shell completion +5. Final performance/reliability acceptance +6. Packaging and clean installation +7. GitHub presentation/distribution +8. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index daddebc..00f6568 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,15 +15,14 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Duplicate detector -2. Metadata repair -3. Missing Library -4. `999 doctor` / diagnostics -5. Shell completion -6. Final performance/reliability acceptance -7. Packaging and clean installation -8. GitHub presentation/distribution -9. Beta release +1. Metadata repair +2. Missing Library +3. `999 doctor` / diagnostics +4. Shell completion +5. Final performance/reliability acceptance +6. Packaging and clean installation +7. GitHub presentation/distribution +8. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index de91cdf..6c95719 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -281,6 +281,7 @@ Actions: s Sync Library a Issues +d Duplicates r Refresh m Maintain lyrics v Verify @@ -385,7 +386,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `c` manual match; `u` unlock, `m`, `r`, `v`, `b`, `p` are secondary | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `a` Issues, `d` Duplicates, `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 | diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 59a3c89..504168a 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -363,6 +363,8 @@ s Sync Library a Issues +d Duplicates + r Refresh m Maintain lyrics @@ -438,6 +440,12 @@ 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. + --- @@ -586,6 +594,6 @@ Ask only before: # Forward flows -Sync Library, Issues, and manual catalogue matching now form the normal Library +Sync Library, Issues, 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 8429ad8..c3aeddb 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -59,6 +59,7 @@ 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; * **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; @@ -77,6 +78,14 @@ 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. + 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 diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index f427cd3..1504308 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -94,6 +94,12 @@ LibraryIssueSeverity, get_library_health, ) +from .library_duplicates import ( + DuplicateConfidence, + DuplicateGroup, + DuplicateReport, + detect_library_duplicates, +) from .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -161,6 +167,9 @@ "LibraryIssueAction", "LibraryIssueCategory", "LibraryIssueSeverity", + "DuplicateConfidence", + "DuplicateGroup", + "DuplicateReport", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", @@ -214,6 +223,7 @@ "IdentityRebuildResult", "backfill_catalogue_identities", "get_library_health", + "detect_library_duplicates", "is_identity_locked", "set_manual_identity", "unlock_manual_identity", 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_status.py b/src/juice_lyrics/services/library_status.py index 96a5cbb..9dd88d2 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -79,6 +79,7 @@ class LibraryTrack: identity_source: str | None = None identity_locked: bool = False verification_error: str | None = None + catalogue_id: Any | None = None @property def needs_attention(self) -> bool: @@ -437,6 +438,12 @@ def get_library_snapshot( 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 + ), ) ) return LibrarySnapshot(library_path, True, tuple(tracks), warnings, state_signature) diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index 442d88a..a9ee9b2 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -61,7 +61,12 @@ from .screens.browse import BrowseScreen from .screens.dashboard import DashboardScreen from .screens.downloads import DownloadsScreen -from .screens.library import LibraryIssuesDialog, LibraryScreen, ManualMatchDialog +from .screens.library import ( + LibraryDuplicatesDialog, + LibraryIssuesDialog, + LibraryScreen, + ManualMatchDialog, +) from .screens.settings import SettingsScreen from .help import HelpScreen @@ -467,7 +472,8 @@ def _get_dom_base(self): RestoreDialog, RmpcDialog, ManualMatchDialog, - LibraryIssuesDialog { + LibraryIssuesDialog, + LibraryDuplicatesDialog { align: center middle; background: transparent; } @@ -556,6 +562,45 @@ def _get_dom_base(self): 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; + } + #library-dialog-title { height: 2; text-style: bold; @@ -1115,7 +1160,9 @@ def action_refresh_active(self) -> None: 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): + if not isinstance(self.screen, ModalScreen) or isinstance( + self.screen, LibraryDuplicatesDialog + ): self.push_screen(HelpScreen()) def on_navigation_item_activated(self, event: NavigationItem.Activated) -> None: diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index 03c0ca4..c494875 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -22,6 +22,7 @@ ("Library", (("↑/↓ or j/k", "Select track"), ("Enter", "Track details"), ("/", "Focus track search; Enter filters"), ("s", "Sync Library"), ("a", "Open Library Issues"), + ("d", "Review duplicate recordings"), ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), ("v", "Verify library"), ("b", "Browse backups"), ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 51f8fde..27ca897 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -35,6 +35,12 @@ LibraryIssueCategory, get_library_health, ) +from ...services.library_duplicates import ( + DuplicateConfidence, + DuplicateGroup, + DuplicateReport, + detect_library_duplicates, +) from ...services.catalogue import CataloguePage, CatalogueSearchResult from ...services.identity_rebuild import ( IdentityRebuildPlan, @@ -494,6 +500,111 @@ def on_key(self, event: Key) -> None: 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 MaintenanceDialog(ModalScreen[LibrarySyncPlan | None]): """Cancel-first confirmation for an already non-mutating maintenance preview.""" @@ -881,7 +992,7 @@ def compose_content(self) -> Iterable[Widget]: 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 · ↑↓ Move · Enter Details · ? Help", id="library-position", markup=False) + yield Static("s Sync Library · a Issues · d Duplicates · ↑↓ Move · Enter Details · ? Help", id="library-position", markup=False) def action_focus_search(self) -> None: self.query_one("#library-query", Input).focus() @@ -1371,9 +1482,9 @@ def _render_details(self) -> None: def _update_position(self) -> None: if not self.filtered_tracks: - self.query_one("#library-position", Static).update("s Sync Library · a Issues · m Maintain lyrics · ? Help") + self.query_one("#library-position", Static).update("s Sync Library · a Issues · d Duplicates · ? Help") return - suffix = "Esc Back · a Issues · c Match · u Unlock · l Refresh lyrics · ? Help" if self._details_mode else "s Sync Library · a Issues · ↑↓ Move · Enter Details · ? Help" + suffix = "Esc Back · a Issues · d Duplicates · c Match · l Refresh · ? Help" if self._details_mode else "s Sync Library · a Issues · d Duplicates · ↑↓ Move · Enter Details · ? Help" self.query_one("#library-position", Static).update( f"Track {self.selected_index + 1} of {len(self.filtered_tracks)} · {suffix}" ) @@ -1387,6 +1498,8 @@ def on_key(self, event: Key) -> None: self.sync_library() elif event.key == "a": self._open_issues() + elif event.key == "d": + self._open_duplicates() elif event.key == "m": self.generate_preview(action="maintain") elif event.key == "v": @@ -1442,6 +1555,19 @@ def _open_issues(self) -> None: 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 _issue_action_selected(self, choice: LibraryIssueChoice | None) -> None: if choice is None: self._set_status("Issues closed. No files were changed.") 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_status.py b/tests/test_library_status.py index f3e7053..724b599 100644 --- a/tests/test_library_status.py +++ b/tests/test_library_status.py @@ -200,6 +200,7 @@ def test_track_snapshot_exposes_typed_local_state_without_api(tmp_path, monkeypa 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 diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index 1986f7b..e6c597a 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -885,6 +885,7 @@ def test_help_inventories_app_bindings_and_focus_palette(): 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", "Choose and lock a catalogue match", "Unlock and clear a manual match", "Inspect setting", "Confirm immediately"): assert label in guide diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 5f8a205..90548a9 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -107,6 +107,8 @@ def _track( 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 @@ -129,6 +131,8 @@ def _track( identity_locked=identity_locked, identity_source=identity_source, verification_error=verification_error, + content_sha256=content_sha256, + catalogue_id=catalogue_id, ) @@ -444,6 +448,85 @@ async def scenario(): 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_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_library_replaces_placeholder_and_renders_summary_details_and_states(tmp_path): root = tmp_path / "music" synced = _track(root, "A Synced.mp3") From 502117bb6fb3d9d5e41b303f639d0a2fb79e2414 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 19 Sep 2026 14:58:51 +0100 Subject: [PATCH 48/62] Add metadata repair audit and preview --- AGENTS.md | 3 + README.md | 5 + docs/METADATA_REPAIR_DESIGN.md | 68 ++++++ docs/PROJECT_STATE.md | 39 ++- docs/ROADMAP.md | 2 +- docs/UI_DESIGN.md | 3 +- docs/USER_FLOWS.md | 8 + docs/USER_GUIDE.md | 9 + src/juice_lyrics/library/media.py | 44 ++++ src/juice_lyrics/services/__init__.py | 12 + src/juice_lyrics/services/catalogue.py | 52 ++++ src/juice_lyrics/services/library_issues.py | 1 + src/juice_lyrics/services/metadata_audit.py | 232 ++++++++++++++++++ src/juice_lyrics/tui/app.py | 38 ++- src/juice_lyrics/tui/help.py | 1 + src/juice_lyrics/tui/screens/library.py | 172 ++++++++++++- tests/test_catalogue_service.py | 20 ++ tests/test_flac_support.py | 7 +- tests/test_m4a_support.py | 7 +- tests/test_metadata_audit.py | 255 ++++++++++++++++++++ tests/test_tui_browse.py | 1 + tests/test_tui_library.py | 111 +++++++++ 22 files changed, 1078 insertions(+), 12 deletions(-) create mode 100644 docs/METADATA_REPAIR_DESIGN.md create mode 100644 src/juice_lyrics/services/metadata_audit.py create mode 100644 tests/test_metadata_audit.py diff --git a/AGENTS.md b/AGENTS.md index 4b99854..e4d246e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,6 +54,7 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. - 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` - Matching/identity: `src/juice_lyrics/library/matching.py` and `src/juice_lyrics/services/library_identity.py` - State: `src/juice_lyrics/state.py` @@ -77,6 +78,8 @@ 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 preview-only until the apply transaction in +`docs/METADATA_REPAIR_DESIGN.md` is implemented and verified. ## Roadmap discipline diff --git a/README.md b/README.md index 62e3c3d..155d2cb 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,11 @@ 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` for a read-only metadata repair preview. Missing +title, artist, album, or track-number values are proposed only when its +confirmed catalogue record supplies trustworthy evidence. Existing values and +version differences are marked for review rather than replaced. Applying these +repairs is intentionally not implemented yet. The CLI remains available for scripting and automation. `999 sync` remembers files it has already processed, so unchanged verified files are skipped. diff --git a/docs/METADATA_REPAIR_DESIGN.md b/docs/METADATA_REPAIR_DESIGN.md new file mode 100644 index 0000000..58ae863 --- /dev/null +++ b/docs/METADATA_REPAIR_DESIGN.md @@ -0,0 +1,68 @@ +# Metadata repair safety design + +The current milestone is audit and preview only. It does not contain a metadata +writer or an Apply action. This document defines the minimum safety contract for +a later apply milestone. + +## 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. + +## 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. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 848637d..d10a8bb 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -1,9 +1,9 @@ # 999 project state This is the canonical detailed handoff for the current application. One-button -Sync, manual catalogue locking, snapshot-backed Library Issues, and read-only -duplicate review are integrated. Read the code and tests if a later working -tree disagrees with this document. +Sync, manual catalogue locking, snapshot-backed Library Issues, read-only +duplicate review, and metadata repair audit/preview are integrated. Read the +code and tests if a later working tree disagrees with this document. ## Repository checkpoint @@ -26,6 +26,9 @@ tree disagrees with this document. - 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -49,6 +52,7 @@ Library is the maintenance centre. The primary routine action is: s → Sync Library a → Issues d → Duplicates +e → Metadata repair preview for the selected track ``` `?` opens the complete scrollable key guide globally. Common actions remain in @@ -121,6 +125,31 @@ 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. +## Metadata repair audit and preview + +`e` prepares a read-only metadata repair preview 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 preview checks that the local file fingerprint did not change while it was +read and displays before/after evidence, identity provenance, format, and path. +It writes no audio, state, embedded lyrics, sidecars, backups, downloads, or +rmpc configuration. There is intentionally no Apply action in this milestone. +The required backup, temporary-copy verification, atomic replacement/rollback, +format-specific preservation, state-conflict, new-hash, and manual-lock rebinding +contract is recorded in `METADATA_REPAIR_DESIGN.md` for the apply milestone. + - 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 @@ -233,6 +262,8 @@ real config, state, backups, queue, sidecars, or rmpc configuration. historical centralized files. - Packaging/install acceptance and public GitHub presentation still need a final release pass. +- Metadata repair currently audits and previews only; safe writes remain a + separate milestone governed by `METADATA_REPAIR_DESIGN.md`. ## Roadmap @@ -246,7 +277,7 @@ 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. Metadata repair +1. Metadata repair apply (backed up, verified, and atomic) 2. Missing Library 3. `999 doctor` / diagnostics 4. Shell completion diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 00f6568..1d2d561 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,7 +15,7 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Metadata repair +1. Metadata repair apply (backed up, verified, and atomic) 2. Missing Library 3. `999 doctor` / diagnostics 4. Shell completion diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 6c95719..9b748df 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -282,6 +282,7 @@ Actions: s Sync Library a Issues d Duplicates +e Metadata preview r Refresh m Maintain lyrics v Verify @@ -386,7 +387,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `d` Duplicates, `c` manual match; `u` unlock, `m`, `r`, `v`, `b`, `p` are secondary | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `a` Issues, `d` Duplicates, `e` metadata preview, `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 | diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 504168a..8d04baa 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -365,6 +365,8 @@ a Issues d Duplicates +e Metadata repair preview + r Refresh m Maintain lyrics @@ -446,6 +448,12 @@ 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 only 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. Unknown +identities are not guessed. This milestone deliberately provides no Apply +action and changes no files or application state. + --- diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index c3aeddb..7a8d0b9 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -60,6 +60,7 @@ 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; +* **Metadata preview** (`e`) on the selected track to compare supported tags with its confirmed catalogue recording; * **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; @@ -86,6 +87,14 @@ 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. +Metadata preview 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. The current +milestone has no Apply action and changes no media, state, lyrics, sidecars, +backups, or player configuration. + 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 diff --git a/src/juice_lyrics/library/media.py b/src/juice_lyrics/library/media.py index 43dce79..6465fbf 100644 --- a/src/juice_lyrics/library/media.py +++ b/src/juice_lyrics/library/media.py @@ -4,6 +4,7 @@ from pathlib import Path from mutagen.flac import FLAC +from mutagen.mp3 import MP3 from mutagen.mp4 import MP4 @@ -20,6 +21,7 @@ class AudioMetadata: artist: str | None album: str | None duration_seconds: float | None + track_number: str | None = None def is_flac(path: Path) -> bool: @@ -45,6 +47,25 @@ def _first(values: object) -> str | None: 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.""" @@ -54,6 +75,7 @@ def read_flac_metadata(path: Path) -> AudioMetadata: 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")), ) @@ -61,14 +83,36 @@ 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) diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 1504308..7232c2d 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -100,6 +100,13 @@ DuplicateReport, detect_library_duplicates, ) +from .metadata_audit import ( + MetadataAudit, + MetadataProposal, + MetadataProposalConfidence, + audit_track_metadata, + build_metadata_audit, +) from .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -170,6 +177,9 @@ "DuplicateConfidence", "DuplicateGroup", "DuplicateReport", + "MetadataAudit", + "MetadataProposal", + "MetadataProposalConfidence", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", @@ -224,6 +234,8 @@ "backfill_catalogue_identities", "get_library_health", "detect_library_duplicates", + "audit_track_metadata", + "build_metadata_audit", "is_identity_locked", "set_manual_identity", "unlock_manual_identity", diff --git a/src/juice_lyrics/services/catalogue.py b/src/juice_lyrics/services/catalogue.py index 0a08b91..48c3841 100644 --- a/src/juice_lyrics/services/catalogue.py +++ b/src/juice_lyrics/services/catalogue.py @@ -4,6 +4,7 @@ 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 @@ -44,6 +45,8 @@ class CatalogueSearchResult: media_path: str | None lyrics: LyricAvailability downloadable: bool + album: str | None = None + track_number: str | None = None @dataclass(frozen=True, slots=True) @@ -92,6 +95,8 @@ class SongDetails: 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: @@ -127,6 +132,51 @@ def _era(value: Any) -> str | None: 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 @@ -172,6 +222,8 @@ def _common_fields(settings: Settings, record: Mapping[str, Any]) -> dict[str, A "synced_lyrics": synced, "plain_lyrics": plain, "downloadable": _is_downloadable(settings, record), + "album": _catalogue_album(record), + "track_number": _track_number(record), } diff --git a/src/juice_lyrics/services/library_issues.py b/src/juice_lyrics/services/library_issues.py index 840e6e8..9f60d40 100644 --- a/src/juice_lyrics/services/library_issues.py +++ b/src/juice_lyrics/services/library_issues.py @@ -33,6 +33,7 @@ class LibraryIssueAction(str, Enum): REFRESH_LYRICS = "refresh_lyrics" VERIFY = "verify" SYNC = "sync" + METADATA_AUDIT = "metadata_audit" @dataclass(frozen=True, slots=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/tui/app.py b/src/juice_lyrics/tui/app.py index a9ee9b2..fe68d04 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -39,6 +39,7 @@ 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.manual_identity import ( ManualIdentityResult, set_manual_identity, @@ -66,6 +67,7 @@ LibraryIssuesDialog, LibraryScreen, ManualMatchDialog, + MetadataAuditDialog, ) from .screens.settings import SettingsScreen from .help import HelpScreen @@ -89,6 +91,7 @@ LibraryPreviewProvider = Callable[[Any], LibrarySyncPlan] LibraryExecutionProvider = Callable[..., LibrarySyncResult] SettingsSnapshotProvider = Callable[[Any], SettingsSnapshot] +MetadataAuditProvider = Callable[..., MetadataAudit] class JuiceLyricsApp(App[None]): @@ -473,7 +476,8 @@ def _get_dom_base(self): RmpcDialog, ManualMatchDialog, LibraryIssuesDialog, - LibraryDuplicatesDialog { + LibraryDuplicatesDialog, + MetadataAuditDialog { align: center middle; background: transparent; } @@ -601,6 +605,34 @@ def _get_dom_base(self): 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; @@ -1017,6 +1049,7 @@ def __init__( 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, 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, @@ -1058,6 +1091,7 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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.backup_provider = backup_provider self.restore_provider = restore_provider self.rmpc_setup_provider = rmpc_setup_provider @@ -1098,6 +1132,8 @@ def on_mount(self) -> None: 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, manual_identity_provider=self.manual_identity_provider, manual_unlock_provider=self.manual_unlock_provider, ), diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index c494875..b8376e5 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -23,6 +23,7 @@ ("/", "Focus track search; Enter filters"), ("s", "Sync Library"), ("a", "Open Library Issues"), ("d", "Review duplicate recordings"), + ("e", "Preview metadata repairs for selected track"), ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), ("v", "Verify library"), ("b", "Browse backups"), ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 27ca897..3fb1a16 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -41,7 +41,17 @@ DuplicateReport, detect_library_duplicates, ) -from ...services.catalogue import CataloguePage, CatalogueSearchResult +from ...services.metadata_audit import ( + MetadataAudit, + MetadataProposalConfidence, + audit_track_metadata, +) +from ...services.catalogue import ( + CataloguePage, + CatalogueSearchResult, + SongDetails, + get_song_details_by_id, +) from ...services.identity_rebuild import ( IdentityRebuildPlan, IdentityRebuildProgress, @@ -65,6 +75,8 @@ IdentityRebuildExecutionProvider = Callable[..., IdentityRebuildResult] ManualSearchProvider = Callable[..., CataloguePage] ManualIdentityProvider = Callable[..., ManualIdentityResult] +MetadataAuditProvider = Callable[..., MetadataAudit] +CatalogueDetailsProvider = Callable[..., SongDetails | None] PreviewProvider = Callable[[Any], LibrarySyncPlan] ExecutionProvider = Callable[..., LibrarySyncResult] BackupProvider = Callable[[], tuple[BackupRecord, ...]] @@ -191,6 +203,13 @@ class ManualIdentityOutcome: 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 LibraryIssueChoice: reference: str @@ -440,12 +459,16 @@ def _render_issues(self) -> None: 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 inspect a read-only metadata repair preview.")) 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 preview") if LibraryIssueCategory.LYRICS in issue.categories: available.append("l Refresh lyrics") available.extend(("v Verify", "s Sync Library", "Esc Close", "? Help")) @@ -484,6 +507,8 @@ def on_key(self, event: Key) -> None: 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) @@ -605,6 +630,71 @@ def on_key(self, event: Key) -> None: event.stop() +class MetadataAuditDialog(ModalScreen[None]): + """Read-only before/after metadata proposal for one local track.""" + + def __init__(self, audit: MetadataAudit) -> None: + super().__init__() + self.audit = audit + + 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("Preview only · Esc Close", id="metadata-audit-help", markup=False) + + 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")) + if not audit.proposals: + lines.append("No metadata changes proposed") + for proposal in audit.proposals: + label = ( + "Confident" + if proposal.confidence is MetadataProposalConfidence.CONFIDENT + else "Review" + ) + lines.extend( + ( + f"{proposal.label}", + f" Before {proposal.before or '(missing)'}", + f" After {proposal.after}", + f" Assessment {label}", + f" Why {proposal.reason}", + ) + ) + if audit.notes: + lines.extend(("", "Notes", *(f"- {note}" for note in audit.notes))) + return Text("\n".join(lines), overflow="ellipsis") + + def on_key(self, event: Key) -> None: + if event.key in {"escape", "e"}: + self.dismiss(None) + event.prevent_default() + event.stop() + + class MaintenanceDialog(ModalScreen[LibrarySyncPlan | None]): """Cancel-first confirmation for an already non-mutating maintenance preview.""" @@ -918,6 +1008,8 @@ def __init__( 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, manual_identity_provider: ManualIdentityProvider = set_manual_identity, manual_unlock_provider: ManualIdentityProvider = unlock_manual_identity, ) -> None: @@ -935,6 +1027,8 @@ def __init__( 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._manual_identity_provider = manual_identity_provider self._manual_unlock_provider = manual_unlock_provider self.snapshot: LibrarySnapshot | None = None @@ -966,6 +1060,9 @@ def __init__( 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] = {} def compose_content(self) -> Iterable[Widget]: yield Static( @@ -1013,6 +1110,9 @@ def on_screen_resume(self, event: ScreenResume) -> None: 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: @@ -1036,6 +1136,9 @@ def invalidate_snapshot(self) -> 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._preview_worker = None self._pending_snapshot = None self._pending_identity = None @@ -1160,6 +1263,17 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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._preview_worker: if event.state is WorkerState.SUCCESS: outcome = event.worker.result @@ -1484,7 +1598,7 @@ def _update_position(self) -> None: if not self.filtered_tracks: self.query_one("#library-position", Static).update("s Sync Library · a Issues · d Duplicates · ? Help") return - suffix = "Esc Back · a Issues · d Duplicates · c Match · l Refresh · ? Help" if self._details_mode else "s Sync Library · a Issues · d Duplicates · ↑↓ Move · Enter Details · ? Help" + suffix = "Esc Back · e Metadata · c Match · l Refresh · ? Help" if self._details_mode else "s Sync Library · a Issues · 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}" ) @@ -1500,6 +1614,8 @@ def on_key(self, event: Key) -> None: self._open_issues() elif event.key == "d": self._open_duplicates() + 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": @@ -1591,6 +1707,58 @@ def _issue_action_selected(self, choice: LibraryIssueChoice | None) -> None: 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_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.app.push_screen(MetadataAuditDialog(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.app.push_screen(MetadataAuditDialog(outcome.audit)) def _open_manual_match(self, track: LibraryTrack | None = None) -> None: track = track or self.selected_track diff --git a/tests/test_catalogue_service.py b/tests/test_catalogue_service.py index bca9159..fe2c0d6 100644 --- a/tests/test_catalogue_service.py +++ b/tests/test_catalogue_service.py @@ -189,6 +189,24 @@ def test_details_by_id_uses_stable_selected_song_id(tmp_path): 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 = { @@ -198,6 +216,7 @@ def test_search_handles_malformed_optional_metadata_without_writes(tmp_path): "length": ["3:00"], "credited_artists": [{"unexpected": "shape"}, None], "producers": 42, + "album": 42, } result = search_catalogue( @@ -212,6 +231,7 @@ def test_search_handles_malformed_optional_metadata_without_writes(tmp_path): 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() diff --git a/tests/test_flac_support.py b/tests/test_flac_support.py index 6acb398..3cb6da5 100644 --- a/tests/test_flac_support.py +++ b/tests/test_flac_support.py @@ -35,6 +35,7 @@ def _make_flac( 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.""" @@ -56,10 +57,10 @@ def _make_flac( ) 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)): + 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)): + if any(value is not None for value in (title, artist, album, track_number)): tags.save() return path @@ -97,6 +98,7 @@ def test_flac_metadata_and_duration_are_read_natively(tmp_path): title="Rental (v2)", artist="Juice WRLD", album="Test Album", + track_number="7/20", duration=3.25, ) @@ -105,6 +107,7 @@ def test_flac_metadata_and_duration_are_read_natively(tmp_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" diff --git a/tests/test_m4a_support.py b/tests/test_m4a_support.py index d67aea9..bbf946f 100644 --- a/tests/test_m4a_support.py +++ b/tests/test_m4a_support.py @@ -43,6 +43,7 @@ def _make_m4a( 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.""" @@ -60,11 +61,13 @@ def _make_m4a( + _atom(b"mdat", _MEDIA_PAYLOAD) ) tags = MP4(path) - if any(value is not None for value in (title, artist, album)): + 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 @@ -101,6 +104,7 @@ def test_m4a_metadata_atoms_and_duration_are_read_natively(tmp_path): title="All Life Long (v2)", artist="Juice WRLD", album="Test Album", + track_number=(7, 20), duration=3.25, ) @@ -109,6 +113,7 @@ def test_m4a_metadata_atoms_and_duration_are_read_natively(tmp_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" 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_tui_browse.py b/tests/test_tui_browse.py index e6c597a..2ed1faa 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -886,6 +886,7 @@ def test_help_inventories_app_bindings_and_focus_palette(): "Mark or unmark", "Download entire queue", "Preview and maintain", "Open Library Issues", "Review duplicate recordings", + "Preview metadata repairs", "Choose and lock a catalogue match", "Unlock and clear a manual match", "Inspect setting", "Confirm immediately"): assert label in guide diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 90548a9..1e7da08 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -30,7 +30,10 @@ 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.library_sync import ( LibrarySyncResult, LibrarySyncOptions, @@ -527,6 +530,114 @@ async def scenario(): 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 preview" 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 "Preview metadata repairs" in _text(app, "#help-content") + + 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") From f3772cfc8d4cc47791d61ebaee961b06e2fbd44b Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sat, 19 Sep 2026 23:45:39 +0100 Subject: [PATCH 49/62] Add safe metadata repair foundation --- AGENTS.md | 6 +- docs/METADATA_REPAIR_DESIGN.md | 26 +- docs/PROJECT_STATE.md | 36 +- docs/ROADMAP.md | 2 +- src/juice_lyrics/services/__init__.py | 18 + src/juice_lyrics/services/metadata_repair.py | 549 +++++++++++++++++++ tests/test_metadata_repair.py | 477 ++++++++++++++++ 7 files changed, 1101 insertions(+), 13 deletions(-) create mode 100644 src/juice_lyrics/services/metadata_repair.py create mode 100644 tests/test_metadata_repair.py diff --git a/AGENTS.md b/AGENTS.md index e4d246e..4d86191 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,6 +55,7 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. `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` - Matching/identity: `src/juice_lyrics/library/matching.py` and `src/juice_lyrics/services/library_identity.py` - State: `src/juice_lyrics/state.py` @@ -78,8 +79,9 @@ 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 preview-only until the apply transaction in -`docs/METADATA_REPAIR_DESIGN.md` is implemented and verified. +Metadata repair has a tested backend transaction, but remains preview-only in +the normal TUI until selection/confirmation integration receives its own +acceptance pass. Never bypass `metadata_repair.py` with direct tag writes. ## Roadmap discipline diff --git a/docs/METADATA_REPAIR_DESIGN.md b/docs/METADATA_REPAIR_DESIGN.md index 58ae863..78d2888 100644 --- a/docs/METADATA_REPAIR_DESIGN.md +++ b/docs/METADATA_REPAIR_DESIGN.md @@ -1,8 +1,9 @@ # Metadata repair safety design -The current milestone is audit and preview only. It does not contain a metadata -writer or an Apply action. This document defines the minimum safety contract for -a later apply milestone. +The audit/preview UI still has no Apply action. The backend transaction in +`services/metadata_repair.py` now implements the safety foundation below for +MP3, FLAC, and M4A, but it is deliberately not exposed to normal users until a +separate field-selection/confirmation acceptance pass is complete. ## Evidence and user decision @@ -51,6 +52,14 @@ M4A `©lyr` and cover art, custom/free-form tags, and unknown metadata. Adjacent 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 @@ -66,3 +75,14 @@ true: 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. + +## Remaining UI integration + +- Add an explicit per-field selector to the existing preview. Review fields + must never be preselected merely because catalogue text differs. +- Add a cancel-first destructive confirmation summarizing the selected fields, + path, and backup behavior. +- Run the backend transaction in a worker, refresh the Library snapshot after + success, and provide the generated backup path on success/failure. +- Complete manual acceptance with representative real-world copies before + enabling Apply for normal libraries. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index d10a8bb..3daf319 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -29,6 +29,10 @@ code and tests if a later working tree disagrees with this document. - 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -145,10 +149,28 @@ normal released record; track number requires an explicit API value. The preview checks that the local file fingerprint did not change while it was read and displays before/after evidence, identity provenance, format, and path. It writes no audio, state, embedded lyrics, sidecars, backups, downloads, or -rmpc configuration. There is intentionally no Apply action in this milestone. -The required backup, temporary-copy verification, atomic replacement/rollback, -format-specific preservation, state-conflict, new-hash, and manual-lock rebinding -contract is recorded in `METADATA_REPAIR_DESIGN.md` for the apply milestone. +rmpc configuration. The normal TUI intentionally has no Apply action yet. +`METADATA_REPAIR_DESIGN.md` records the implemented backend safety contract and +the remaining UI/acceptance work. + +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. + +This backend is deliberately **not exposed by the TUI yet**. The existing `e` +workflow remains preview-only. Per-field controls, a cancel-first confirmation, +background execution/result UX, and real-copy acceptance are the next metadata +repair step; no incomplete Apply action is visible to normal users. - MP3 full coverage uses the existing format-aware ID3 requirements plus its synchronized sidecar behavior. @@ -262,8 +284,8 @@ real config, state, backups, queue, sidecars, or rmpc configuration. historical centralized files. - Packaging/install acceptance and public GitHub presentation still need a final release pass. -- Metadata repair currently audits and previews only; safe writes remain a - separate milestone governed by `METADATA_REPAIR_DESIGN.md`. +- Metadata repair remains preview-only in the TUI. Its backend transaction is + implemented, but selection/confirmation UI and real-copy acceptance remain. ## Roadmap @@ -277,7 +299,7 @@ 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. Metadata repair apply (backed up, verified, and atomic) +1. Metadata repair apply UI integration and real-copy acceptance 2. Missing Library 3. `999 doctor` / diagnostics 4. Shell completion diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 1d2d561..0c26618 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,7 +15,7 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Metadata repair apply (backed up, verified, and atomic) +1. Metadata repair apply UI integration and real-copy acceptance 2. Missing Library 3. `999 doctor` / diagnostics 4. Shell completion diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 7232c2d..4cafab7 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -107,6 +107,16 @@ 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 .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -180,6 +190,10 @@ "MetadataAudit", "MetadataProposal", "MetadataProposalConfidence", + "MediaPreservation", + "MetadataRepairDependencies", + "MetadataRepairPlan", + "MetadataRepairResult", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", @@ -236,6 +250,10 @@ "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", diff --git a/src/juice_lyrics/services/metadata_repair.py b/src/juice_lyrics/services/metadata_repair.py new file mode 100644 index 0000000..d5259a3 --- /dev/null +++ b/src/juice_lyrics/services/metadata_repair.py @@ -0,0 +1,549 @@ +"""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 = data[-128:] if len(data) >= 128 and data[-128:-125] == b"TAG" else b"" + return ("MP3", preserved, _freeze(id3v1)) + + +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 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 + 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) + + +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/tests/test_metadata_repair.py b/tests/test_metadata_repair.py new file mode 100644 index 0000000..a8bd9b9 --- /dev/null +++ b/tests/test_metadata_repair.py @@ -0,0 +1,477 @@ +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, +) +from juice_lyrics.services.metadata_audit import build_metadata_audit +from juice_lyrics.services.metadata_repair import ( + MetadataRepairDependencies, + execute_metadata_repair, + 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) + 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"] + 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_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 From ba594f9fd0c454b6c6380dbca490a797abc23add Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 20 Sep 2026 13:22:57 +0100 Subject: [PATCH 50/62] Add safe TUI metadata repair apply --- AGENTS.md | 6 +- README.md | 11 +- docs/METADATA_REPAIR_DESIGN.md | 31 ++- docs/PROJECT_STATE.md | 44 +-- docs/ROADMAP.md | 2 +- docs/UI_DESIGN.md | 4 +- docs/USER_FLOWS.md | 14 +- docs/USER_GUIDE.md | 15 +- src/juice_lyrics/tui/app.py | 18 +- src/juice_lyrics/tui/help.py | 2 +- src/juice_lyrics/tui/screens/library.py | 356 ++++++++++++++++++++++-- tests/test_tui_browse.py | 2 +- tests/test_tui_library.py | 237 +++++++++++++++- 13 files changed, 664 insertions(+), 78 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4d86191..3bfe7cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,9 +79,9 @@ 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 has a tested backend transaction, but remains preview-only in -the normal TUI until selection/confirmation integration receives its own -acceptance pass. Never bypass `metadata_repair.py` with direct tag writes. +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 diff --git a/README.md b/README.md index 155d2cb..914f0c9 100644 --- a/README.md +++ b/README.md @@ -63,11 +63,12 @@ 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` for a read-only metadata repair preview. Missing -title, artist, album, or track-number values are proposed only when its -confirmed catalogue record supplies trustworthy evidence. Existing values and -version differences are marked for review rather than replaced. Applying these -repairs is intentionally not implemented yet. +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. diff --git a/docs/METADATA_REPAIR_DESIGN.md b/docs/METADATA_REPAIR_DESIGN.md index 78d2888..4def316 100644 --- a/docs/METADATA_REPAIR_DESIGN.md +++ b/docs/METADATA_REPAIR_DESIGN.md @@ -1,9 +1,9 @@ # Metadata repair safety design -The audit/preview UI still has no Apply action. The backend transaction in -`services/metadata_repair.py` now implements the safety foundation below for -MP3, FLAC, and M4A, but it is deliberately not exposed to normal users until a -separate field-selection/confirmation acceptance pass is complete. +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 @@ -76,13 +76,16 @@ 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. -## Remaining UI integration - -- Add an explicit per-field selector to the existing preview. Review fields - must never be preselected merely because catalogue text differs. -- Add a cancel-first destructive confirmation summarizing the selected fields, - path, and backup behavior. -- Run the backend transaction in a worker, refresh the Library snapshot after - success, and provide the generated backup path on success/failure. -- Complete manual acceptance with representative real-world copies before - enabling Apply for normal libraries. +## 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. + Real-world copied-file acceptance remains advisable as a beta check because + no suitable repository media samples are available. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 3daf319..de3ce4f 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -2,7 +2,7 @@ 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 metadata repair audit/preview are integrated. Read the +duplicate review, and safe metadata repair are integrated. Read the code and tests if a later working tree disagrees with this document. ## Repository checkpoint @@ -33,6 +33,10 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -129,10 +133,10 @@ 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. -## Metadata repair audit and preview +## Metadata repair audit and safe apply -`e` prepares a read-only metadata repair preview for the selected MP3, FLAC, or -M4A in a background worker. Metadata Issues also expose the same action. The +`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 @@ -146,12 +150,12 @@ 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 preview checks that the local file fingerprint did not change while it was +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 writes no audio, state, embedded lyrics, sidecars, backups, downloads, or -rmpc configuration. The normal TUI intentionally has no Apply action yet. -`METADATA_REPAIR_DESIGN.md` records the implemented backend safety contract and -the remaining UI/acceptance work. +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 @@ -167,10 +171,18 @@ 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. -This backend is deliberately **not exposed by the TUI yet**. The existing `e` -workflow remains preview-only. Per-field controls, a cancel-first confirmation, -background execution/result UX, and real-copy acceptance are the next metadata -repair step; no incomplete Apply action is visible to normal users. +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. No suitable real media samples +are stored in the repository, so manual acceptance on temporary copies of +representative real files remains a beta-validation step. - MP3 full coverage uses the existing format-aware ID3 requirements plus its synchronized sidecar behavior. @@ -284,8 +296,8 @@ real config, state, backups, queue, sidecars, or rmpc configuration. historical centralized files. - Packaging/install acceptance and public GitHub presentation still need a final release pass. -- Metadata repair remains preview-only in the TUI. Its backend transaction is - implemented, but selection/confirmation UI and real-copy acceptance remain. +- Metadata repair has safe TUI selection/apply integration. Acceptance against + temporary copies of representative real-world files remains outstanding. ## Roadmap @@ -299,7 +311,7 @@ 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. Metadata repair apply UI integration and real-copy acceptance +1. Real-copy metadata repair acceptance 2. Missing Library 3. `999 doctor` / diagnostics 4. Shell completion diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0c26618..236a5c0 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,7 +15,7 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Metadata repair apply UI integration and real-copy acceptance +1. Real-copy metadata repair acceptance 2. Missing Library 3. `999 doctor` / diagnostics 4. Shell completion diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 9b748df..2d5ea9a 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -282,7 +282,7 @@ Actions: s Sync Library a Issues d Duplicates -e Metadata preview +e Metadata repair r Refresh m Maintain lyrics v Verify @@ -387,7 +387,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `d` Duplicates, `e` metadata preview, `c` manual match; `u` unlock, `m`, `r`, `v`, `b`, `p` are secondary | +| Library | `↑`/`↓` move, `Enter` details, `s` Sync Library, `a` Issues, `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 | diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 8d04baa..8c0d268 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -365,7 +365,7 @@ a Issues d Duplicates -e Metadata repair preview +e Metadata repair r Refresh @@ -448,11 +448,13 @@ 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 only 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. Unknown -identities are not guessed. This milestone deliberately provides no Apply -action and changes no files or application state. +`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. --- diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 7a8d0b9..a18bd82 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -60,7 +60,7 @@ 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; -* **Metadata preview** (`e`) on the selected track to compare supported tags with its confirmed catalogue 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; @@ -87,13 +87,18 @@ 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. -Metadata preview reads the selected MP3, FLAC, or M4A tags and its confirmed +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. The current -milestone has no Apply action and changes no media, state, lyrics, sidecars, -backups, or player configuration. +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 diff --git a/src/juice_lyrics/tui/app.py b/src/juice_lyrics/tui/app.py index fe68d04..0432261 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -40,6 +40,12 @@ 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.manual_identity import ( ManualIdentityResult, set_manual_identity, @@ -68,6 +74,7 @@ LibraryScreen, ManualMatchDialog, MetadataAuditDialog, + MetadataRepairConfirmationDialog, ) from .screens.settings import SettingsScreen from .help import HelpScreen @@ -92,6 +99,8 @@ LibraryExecutionProvider = Callable[..., LibrarySyncResult] SettingsSnapshotProvider = Callable[[Any], SettingsSnapshot] MetadataAuditProvider = Callable[..., MetadataAudit] +MetadataRepairPlanProvider = Callable[..., MetadataRepairPlan] +MetadataRepairExecutionProvider = Callable[..., MetadataRepairResult] class JuiceLyricsApp(App[None]): @@ -477,7 +486,8 @@ def _get_dom_base(self): ManualMatchDialog, LibraryIssuesDialog, LibraryDuplicatesDialog, - MetadataAuditDialog { + MetadataAuditDialog, + MetadataRepairConfirmationDialog { align: center middle; background: transparent; } @@ -1050,6 +1060,8 @@ def __init__( 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, 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, @@ -1092,6 +1104,8 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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.backup_provider = backup_provider self.restore_provider = restore_provider self.rmpc_setup_provider = rmpc_setup_provider @@ -1134,6 +1148,8 @@ def on_mount(self) -> None: 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, ), diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index b8376e5..cea20d2 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -23,7 +23,7 @@ ("/", "Focus track search; Enter filters"), ("s", "Sync Library"), ("a", "Open Library Issues"), ("d", "Review duplicate recordings"), - ("e", "Preview metadata repairs for selected track"), + ("e", "Review and apply selected metadata repairs"), ("m", "Preview and maintain lyrics"), ("r", "Refresh library"), ("v", "Verify library"), ("b", "Browse backups"), ("p", "Check player integration"), ("l", "Preview selected lyric refresh"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 3fb1a16..7ec9b98 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -46,6 +46,12 @@ MetadataProposalConfidence, audit_track_metadata, ) +from ...services.metadata_repair import ( + MetadataRepairPlan, + MetadataRepairResult, + execute_metadata_repair, + plan_metadata_repair, +) from ...services.catalogue import ( CataloguePage, CatalogueSearchResult, @@ -76,6 +82,8 @@ ManualSearchProvider = Callable[..., CataloguePage] ManualIdentityProvider = Callable[..., ManualIdentityResult] MetadataAuditProvider = Callable[..., MetadataAudit] +MetadataRepairPlanProvider = Callable[..., MetadataRepairPlan] +MetadataRepairExecutionProvider = Callable[..., MetadataRepairResult] CatalogueDetailsProvider = Callable[..., SongDetails | None] PreviewProvider = Callable[[Any], LibrarySyncPlan] ExecutionProvider = Callable[..., LibrarySyncResult] @@ -210,6 +218,18 @@ class MetadataAuditOutcome: 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 @@ -460,7 +480,7 @@ def _render_issues(self) -> None: 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 inspect a read-only metadata repair preview.")) + 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") ) @@ -468,7 +488,7 @@ def _render_issues(self) -> None: if LibraryIssueCategory.CATALOGUE in issue.categories: available.append("c Match manually") if LibraryIssueCategory.METADATA in issue.categories: - available.append("e Metadata preview") + 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")) @@ -630,19 +650,42 @@ def on_key(self, event: Key) -> None: event.stop() -class MetadataAuditDialog(ModalScreen[None]): - """Read-only before/after metadata proposal for one local track.""" +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("Preview only · Esc Close", id="metadata-audit-help", 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 @@ -666,33 +709,171 @@ def _text(self) -> Text: f"Duration {audit.catalogue.length or 'Not available'}", ) ) - lines.extend(("", "Proposed metadata")) + lines.extend(("", "Proposed metadata · nothing is selected by default")) if not audit.proposals: lines.append("No metadata changes proposed") - for proposal in audit.proposals: - label = ( - "Confident" - if proposal.confidence is MetadataProposalConfidence.CONFIDENT - else "Review" + 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 ) - lines.extend( - ( - f"{proposal.label}", - f" Before {proposal.before or '(missing)'}", - f" After {proposal.after}", - f" Assessment {label}", - f" Why {proposal.reason}", + 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]): @@ -1010,6 +1191,8 @@ def __init__( 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, ) -> None: @@ -1029,6 +1212,8 @@ def __init__( 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.snapshot: LibrarySnapshot | None = None @@ -1063,6 +1248,8 @@ def __init__( 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( @@ -1139,6 +1326,8 @@ def invalidate_snapshot(self) -> 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 @@ -1274,6 +1463,20 @@ def on_worker_state_changed(self, event: Worker.StateChanged) -> None: 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 @@ -1714,12 +1917,21 @@ 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.app.push_screen(MetadataAuditDialog(cached)) + 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) @@ -1758,7 +1970,109 @@ def _apply_metadata_audit(self, outcome: MetadataAuditOutcome) -> None: return self._metadata_audit_cache[self._metadata_cache_key(track)] = outcome.audit self._set_status("Metadata repair preview ready · No files were changed") - self.app.push_screen(MetadataAuditDialog(outcome.audit)) + 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 diff --git a/tests/test_tui_browse.py b/tests/test_tui_browse.py index 2ed1faa..852f85c 100644 --- a/tests/test_tui_browse.py +++ b/tests/test_tui_browse.py @@ -886,7 +886,7 @@ def test_help_inventories_app_bindings_and_focus_palette(): "Mark or unmark", "Download entire queue", "Preview and maintain", "Open Library Issues", "Review duplicate recordings", - "Preview metadata repairs", + "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 diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 1e7da08..9791f5e 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -4,6 +4,9 @@ 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")) @@ -623,7 +626,7 @@ async def scenario(): async with app.run_test(size=(120, 40)) as pilot: screen = await _open_library(app, pilot) await pilot.press("a") - assert "e Metadata preview" in _text(app, "#library-issues-help") + assert "e Metadata repair" in _text(app, "#library-issues-help") await pilot.press("e") worker = screen._metadata_audit_worker if worker is not None: @@ -633,7 +636,237 @@ async def scenario(): assert "Missing Tags" in _text(app, "#metadata-audit-content") await pilot.press("escape", "question_mark") await pilot.pause() - assert "Preview metadata repairs" in _text(app, "#help-content") + 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()) From 84ca1c62466f6c32d03cd3b0a7ea7c3dc5c39e9b Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Sun, 20 Sep 2026 13:43:58 +0100 Subject: [PATCH 51/62] Harden metadata repair from real-file acceptance --- docs/METADATA_REPAIR_DESIGN.md | 7 ++- docs/PROJECT_STATE.md | 42 +++++++++----- docs/ROADMAP.md | 15 +++-- src/juice_lyrics/backup/manager.py | 13 ++++- src/juice_lyrics/services/metadata_repair.py | 61 +++++++++++++++++++- tests/test_backup_retention.py | 22 +++++++ tests/test_metadata_repair.py | 34 +++++++++++ 7 files changed, 167 insertions(+), 27 deletions(-) diff --git a/docs/METADATA_REPAIR_DESIGN.md b/docs/METADATA_REPAIR_DESIGN.md index 4def316..d96aa5d 100644 --- a/docs/METADATA_REPAIR_DESIGN.md +++ b/docs/METADATA_REPAIR_DESIGN.md @@ -87,5 +87,8 @@ the normal changed-file safety rules. failure requiring recovery. - Generated MP3, FLAC, and M4A fixtures exercise audio, artwork, embedded lyric, custom-tag, sidecar, backup, interruption, conflict, and rollback guarantees. - Real-world copied-file acceptance remains advisable as a beta check because - no suitable repository media samples are available. +- 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 index de3ce4f..4f89e0f 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -37,6 +37,13 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -180,9 +187,18 @@ 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. No suitable real media samples -are stored in the repository, so manual acceptance on temporary copies of -representative real files remains a beta-validation step. +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. @@ -296,8 +312,9 @@ real config, state, backups, queue, sidecars, or rmpc configuration. historical centralized files. - Packaging/install acceptance and public GitHub presentation still need a final release pass. -- Metadata repair has safe TUI selection/apply integration. Acceptance against - temporary copies of representative real-world files remains outstanding. +- 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 @@ -311,14 +328,13 @@ 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. Real-copy metadata repair acceptance -2. Missing Library -3. `999 doctor` / diagnostics -4. Shell completion -5. Final performance/reliability acceptance -6. Packaging and clean installation -7. GitHub presentation/distribution -8. Beta release +1. Missing Library +2. `999 doctor` / diagnostics +3. Shell completion +4. Final performance/reliability acceptance +5. Packaging and clean installation +6. GitHub presentation/distribution +7. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 236a5c0..c86715f 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,14 +15,13 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Real-copy metadata repair acceptance -2. Missing Library -3. `999 doctor` / diagnostics -4. Shell completion -5. Final performance/reliability acceptance -6. Packaging and clean installation -7. GitHub presentation/distribution -8. Beta release +1. Missing Library +2. `999 doctor` / diagnostics +3. Shell completion +4. Final performance/reliability acceptance +5. Packaging and clean installation +6. GitHub presentation/distribution +7. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/src/juice_lyrics/backup/manager.py b/src/juice_lyrics/backup/manager.py index ba6edf7..76f6be7 100644 --- a/src/juice_lyrics/backup/manager.py +++ b/src/juice_lyrics/backup/manager.py @@ -63,9 +63,16 @@ def now_iso() -> str: def make_backup_root() -> Path: ensure_data_dirs() - root = BACKUP_DIR / datetime.now().strftime("%Y%m%d-%H%M%S") - root.mkdir(parents=True, exist_ok=True) - return root + 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: diff --git a/src/juice_lyrics/services/metadata_repair.py b/src/juice_lyrics/services/metadata_repair.py index d5259a3..d8463a8 100644 --- a/src/juice_lyrics/services/metadata_repair.py +++ b/src/juice_lyrics/services/metadata_repair.py @@ -248,10 +248,29 @@ def _unrelated_tags(path: Path, selected_fields: frozenset[str]) -> tuple[Any, . ) ) data = path.read_bytes() - id3v1 = data[-128:] if len(data) >= 128 and data[-128:-125] == b"TAG" else b"" + 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], @@ -274,6 +293,39 @@ def _parse_track_number(value: str) -> tuple[int, int]: 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.""" @@ -301,6 +353,12 @@ def write_metadata_fields(path: Path, values: Mapping[str, str]) -> None: 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: @@ -311,6 +369,7 @@ def write_metadata_fields(path: Path, values: Mapping[str, str]) -> None: 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]: diff --git a/tests/test_backup_retention.py b/tests/test_backup_retention.py index e694038..052cc97 100644 --- a/tests/test_backup_retention.py +++ b/tests/test_backup_retention.py @@ -41,6 +41,28 @@ def _backup_set(backup_dir: Path, count: int) -> list[Path]: ] +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" diff --git a/tests/test_metadata_repair.py b/tests/test_metadata_repair.py index a8bd9b9..5421915 100644 --- a/tests/test_metadata_repair.py +++ b/tests/test_metadata_repair.py @@ -29,6 +29,7 @@ from juice_lyrics.services.metadata_repair import ( MetadataRepairDependencies, execute_metadata_repair, + inspect_media_preservation, plan_metadata_repair, write_metadata_fields, ) @@ -46,6 +47,20 @@ def _make_mp3(path: Path) -> Path: 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 @@ -187,6 +202,11 @@ def _assert_unrelated_metadata_preserved(path: Path) -> None: 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"] @@ -249,6 +269,20 @@ def test_plan_requires_explicit_previewed_field_selection(tmp_path): ) +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) From c670a655cec35fe43cd00b507f06edcc966c6f59 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 21 Sep 2026 10:22:50 +0100 Subject: [PATCH 52/62] Add Missing Library catalogue view --- README.md | 4 + docs/PROJECT_STATE.md | 34 ++- docs/ROADMAP.md | 13 +- docs/UI_DESIGN.md | 3 +- docs/USER_FLOWS.md | 4 +- docs/USER_GUIDE.md | 9 + src/juice_lyrics/services/__init__.py | 8 + src/juice_lyrics/services/missing_library.py | 132 ++++++++++ src/juice_lyrics/tui/app.py | 60 ++++- src/juice_lyrics/tui/help.py | 5 + src/juice_lyrics/tui/screens/library.py | 241 ++++++++++++++++++- tests/test_missing_library.py | 126 ++++++++++ tests/test_tui_library.py | 107 ++++++++ 13 files changed, 726 insertions(+), 20 deletions(-) create mode 100644 src/juice_lyrics/services/missing_library.py create mode 100644 tests/test_missing_library.py diff --git a/README.md b/README.md index 914f0c9..e3870f7 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,10 @@ 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. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 4f89e0f..c545a27 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -44,6 +44,9 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -67,6 +70,7 @@ Library is the maintenance centre. The primary routine action is: s → Sync Library a → Issues d → Duplicates +g → Missing Library e → Metadata repair preview for the selected track ``` @@ -140,6 +144,23 @@ 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 @@ -328,13 +349,12 @@ 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. Missing Library -2. `999 doctor` / diagnostics -3. Shell completion -4. Final performance/reliability acceptance -5. Packaging and clean installation -6. GitHub presentation/distribution -7. Beta release +1. `999 doctor` / diagnostics +2. Shell completion +3. Final performance/reliability acceptance +4. Packaging and clean installation +5. GitHub presentation/distribution +6. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index c86715f..0cfe961 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,13 +15,12 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Missing Library -2. `999 doctor` / diagnostics -3. Shell completion -4. Final performance/reliability acceptance -5. Packaging and clean installation -6. GitHub presentation/distribution -7. Beta release +1. `999 doctor` / diagnostics +2. Shell completion +3. Final performance/reliability acceptance +4. Packaging and clean installation +5. GitHub presentation/distribution +6. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index 2d5ea9a..db8158a 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -281,6 +281,7 @@ Actions: s Sync Library a Issues +g Missing Library d Duplicates e Metadata repair r Refresh @@ -387,7 +388,7 @@ movement, details, and the main action for each section. Core bindings: | --- | --- | | 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, `d` Duplicates, `e` metadata repair, `c` manual match; `u` unlock, `m`, `r`, `v`, `b`, `p` are secondary | +| 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 | diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 8c0d268..e6b6d00 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -363,6 +363,8 @@ s Sync Library a Issues +g Missing Library + d Duplicates e Metadata repair @@ -604,6 +606,6 @@ Ask only before: # Forward flows -Sync Library, Issues, duplicate review, and manual catalogue matching form the normal Library +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 a18bd82..4224a3c 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -60,6 +60,7 @@ 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; @@ -87,6 +88,14 @@ 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 diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 4cafab7..e14e0a0 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -117,6 +117,11 @@ plan_metadata_repair, write_metadata_fields, ) +from .missing_library import ( + CatalogueCoverage, + MissingLibraryReport, + get_missing_library, +) from .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -194,6 +199,9 @@ "MetadataRepairDependencies", "MetadataRepairPlan", "MetadataRepairResult", + "CatalogueCoverage", + "MissingLibraryReport", + "get_missing_library", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", 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/tui/app.py b/src/juice_lyrics/tui/app.py index 0432261..49e3f91 100644 --- a/src/juice_lyrics/tui/app.py +++ b/src/juice_lyrics/tui/app.py @@ -46,6 +46,7 @@ execute_metadata_repair, plan_metadata_repair, ) +from ..services.missing_library import MissingLibraryReport, get_missing_library from ..services.manual_identity import ( ManualIdentityResult, set_manual_identity, @@ -73,6 +74,7 @@ LibraryIssuesDialog, LibraryScreen, ManualMatchDialog, + MissingLibraryDialog, MetadataAuditDialog, MetadataRepairConfirmationDialog, ) @@ -101,6 +103,7 @@ MetadataAuditProvider = Callable[..., MetadataAudit] MetadataRepairPlanProvider = Callable[..., MetadataRepairPlan] MetadataRepairExecutionProvider = Callable[..., MetadataRepairResult] +MissingLibraryProvider = Callable[..., MissingLibraryReport] class JuiceLyricsApp(App[None]): @@ -486,6 +489,7 @@ def _get_dom_base(self): ManualMatchDialog, LibraryIssuesDialog, LibraryDuplicatesDialog, + MissingLibraryDialog, MetadataAuditDialog, MetadataRepairConfirmationDialog { align: center middle; @@ -615,6 +619,55 @@ def _get_dom_base(self): 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%; @@ -1062,6 +1115,7 @@ def __init__( 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, @@ -1106,6 +1160,7 @@ def normalized_downloads_provider() -> DownloadQueueSnapshot: 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 @@ -1152,6 +1207,9 @@ def on_mount(self) -> None: 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", ) @@ -1213,7 +1271,7 @@ def action_refresh_active(self) -> None: def action_show_help(self) -> None: if not isinstance(self.screen, ModalScreen) or isinstance( - self.screen, LibraryDuplicatesDialog + self.screen, (LibraryDuplicatesDialog, MissingLibraryDialog) ): self.push_screen(HelpScreen()) diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index cea20d2..37e1dd6 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -22,6 +22,7 @@ ("Library", (("↑/↓ or j/k", "Select track"), ("Enter", "Track details"), ("/", "Focus track search; Enter filters"), ("s", "Sync Library"), ("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"), @@ -31,6 +32,10 @@ ("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)"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 7ec9b98..434f74b 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -41,6 +41,17 @@ 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, @@ -84,6 +95,9 @@ 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] @@ -650,6 +664,205 @@ def on_key(self, event: Key) -> None: 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.""" @@ -1195,6 +1408,9 @@ def __init__( 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 @@ -1216,6 +1432,9 @@ def __init__( 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 @@ -1276,7 +1495,7 @@ def compose_content(self) -> Iterable[Widget]: 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 · d Duplicates · ↑↓ Move · Enter Details · ? Help", id="library-position", 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() @@ -1799,9 +2018,9 @@ def _render_details(self) -> None: def _update_position(self) -> None: if not self.filtered_tracks: - self.query_one("#library-position", Static).update("s Sync Library · a Issues · d Duplicates · ? Help") + 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 · d Duplicates · e Metadata · ↑↓ Move · ? Help" + 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}" ) @@ -1817,6 +2036,8 @@ def on_key(self, event: Key) -> None: 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": @@ -1887,6 +2108,20 @@ def _open_duplicates(self) -> None: ) ) + 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.") 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_tui_library.py b/tests/test_tui_library.py index 9791f5e..96465ce 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -37,6 +37,7 @@ ) 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, @@ -499,6 +500,112 @@ async def scenario(): 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 = ( From 89b4e9d5f781e4a8a332ff19f15b2dc4c9cf5e04 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 21 Sep 2026 10:46:38 +0100 Subject: [PATCH 53/62] Add read-only Doctor diagnostics --- AGENTS.md | 1 + README.md | 10 +- docs/PROJECT_STATE.md | 31 +- docs/ROADMAP.md | 11 +- docs/USER_GUIDE.md | 18 ++ src/juice_lyrics/cli.py | 74 ++++- src/juice_lyrics/services/__init__.py | 16 ++ src/juice_lyrics/services/doctor.py | 389 ++++++++++++++++++++++++++ tests/test_doctor.py | 201 +++++++++++++ 9 files changed, 726 insertions(+), 25 deletions(-) create mode 100644 src/juice_lyrics/services/doctor.py create mode 100644 tests/test_doctor.py diff --git a/AGENTS.md b/AGENTS.md index 3bfe7cc..296aa62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,6 +56,7 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. - 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` - Matching/identity: `src/juice_lyrics/library/matching.py` and `src/juice_lyrics/services/library_identity.py` - State: `src/juice_lyrics/state.py` diff --git a/README.md b/README.md index e3870f7..ccfe881 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,14 @@ Useful status command: 999 status ``` +Read-only diagnostics and an optional sanitized support report: + +```bash +999 doctor +999 doctor --support-report +999 doctor --save-report ./999-support.json +``` + Built-in guide: ```bash @@ -147,7 +155,7 @@ relevant architecture or user document. | `embed` | Lower-level embed-only command | | `verify` | Validate supported MP3/FLAC/M4A embedded lyrics | | `restore` | Restore a previous audio backup | -| `doctor` | Diagnose Python, Mutagen, API, and paths | +| `doctor` | Bounded read-only health checks; optional sanitized support report | | `guide` | Show this workflow in the terminal | | `search` | Search the public song catalogue | | `info` | Inspect a song's API metadata | diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index c545a27..8be881a 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -47,6 +47,10 @@ code and tests if a later working tree disagrees with this document. - 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -316,6 +320,22 @@ 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. + ## Known limitations and risks - Active download cancellation is not implemented. @@ -349,12 +369,11 @@ 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. `999 doctor` / diagnostics -2. Shell completion -3. Final performance/reliability acceptance -4. Packaging and clean installation -5. GitHub presentation/distribution -6. Beta release +1. Shell completion +2. Final performance/reliability acceptance +3. Packaging and clean installation +4. GitHub presentation/distribution +5. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0cfe961..9cffc09 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,12 +15,11 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. `999 doctor` / diagnostics -2. Shell completion -3. Final performance/reliability acceptance -4. Packaging and clean installation -5. GitHub presentation/distribution -6. Beta release +1. Shell completion +2. Final performance/reliability acceptance +3. Packaging and clean installation +4. GitHub presentation/distribution +5. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 4224a3c..77f6a6e 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -258,6 +258,24 @@ Those plain-only songs are still tagged correctly, but rmpc's synchronized Lyric 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. + For detailed matching: ```bash diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index c492f32..23d4416 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 @@ -709,6 +710,11 @@ def embed_batch(settings: Settings, files: list[Path], use_color: bool, refresh: 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]]: @@ -1077,16 +1083,49 @@ def command_restore(args: argparse.Namespace, settings: Settings, use_color: boo def command_doctor(args: argparse.Namespace, settings: Settings, use_color: bool) -> int: - print_header("999 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 + 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: @@ -1627,7 +1666,9 @@ def build_parser() -> argparse.ArgumentParser: 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.") guide = sub.add_parser("guide", help="Show the built-in quick guide.") @@ -1717,7 +1758,16 @@ def main(argv: list[str] | None = None) -> int: args = parser.parse_args(argv) use_color = not args.no_color and sys.stdout.isatty() 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) diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index e14e0a0..99e4053 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -122,6 +122,15 @@ MissingLibraryReport, get_missing_library, ) +from .doctor import ( + DoctorCheck, + DoctorReport, + DoctorStatus, + render_support_report, + run_doctor, + sanitize_support_text, + support_report_data, +) from .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -202,6 +211,13 @@ "CatalogueCoverage", "MissingLibraryReport", "get_missing_library", + "DoctorCheck", + "DoctorReport", + "DoctorStatus", + "render_support_report", + "run_doctor", + "sanitize_support_text", + "support_report_data", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", diff --git a/src/juice_lyrics/services/doctor.py b/src/juice_lyrics/services/doctor.py new file mode 100644 index 0000000..9d62d3e --- /dev/null +++ b/src/juice_lyrics/services/doctor.py @@ -0,0 +1,389 @@ +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) -> DoctorCheck: + try: + executable = command_finder("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, +) -> 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)), + 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/tests/test_doctor.py b/tests/test_doctor.py new file mode 100644 index 0000000..e292045 --- /dev/null +++ b/tests/test_doctor.py @@ -0,0 +1,201 @@ +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_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 From a31f7ef3ec1b3bd089cd6cdf42c4a1198712bb4d Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Mon, 21 Sep 2026 11:04:24 +0100 Subject: [PATCH 54/62] Add generated shell completion --- AGENTS.md | 1 + README.md | 37 ++ docs/PROJECT_STATE.md | 27 +- docs/ROADMAP.md | 9 +- docs/USER_GUIDE.md | 34 ++ src/juice_lyrics/cli.py | 10 + src/juice_lyrics/services/__init__.py | 10 + src/juice_lyrics/services/shell_completion.py | 322 ++++++++++++++++++ tests/test_shell_completion.py | 192 +++++++++++ 9 files changed, 632 insertions(+), 10 deletions(-) create mode 100644 src/juice_lyrics/services/shell_completion.py create mode 100644 tests/test_shell_completion.py diff --git a/AGENTS.md b/AGENTS.md index 296aa62..3864912 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,6 +57,7 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. - 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` diff --git a/README.md b/README.md index ccfe881..952ba5c 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,7 @@ relevant architecture or user document. | `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 | @@ -302,6 +303,42 @@ contain current checkout changes. Reinstall it deliberately or keep using 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: diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 8be881a..964a2fa 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -51,6 +51,11 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -336,6 +341,19 @@ 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. + ## Known limitations and risks - Active download cancellation is not implemented. @@ -369,11 +387,10 @@ 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. Shell completion -2. Final performance/reliability acceptance -3. Packaging and clean installation -4. GitHub presentation/distribution -5. Beta release +1. Final performance/reliability acceptance +2. Packaging and clean installation +3. GitHub presentation/distribution +4. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 9cffc09..0b5ca9c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,11 +15,10 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Shell completion -2. Final performance/reliability acceptance -3. Packaging and clean installation -4. GitHub presentation/distribution -5. Beta release +1. Final performance/reliability acceptance +2. Packaging and clean installation +3. GitHub presentation/distribution +4. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 77f6a6e..cffe124 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -276,6 +276,40 @@ 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 diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 23d4416..31bab48 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -25,6 +25,7 @@ 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 = PRODUCT_NAME DEFAULT_API_BASE = "https://juicewrldapi.com/juicewrld" @@ -1670,6 +1671,12 @@ def build_parser() -> argparse.ArgumentParser: 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.") @@ -1757,6 +1764,9 @@ 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: try: settings = load_settings(getattr(args, "path", None), getattr(args, "api_base", None)) diff --git a/src/juice_lyrics/services/__init__.py b/src/juice_lyrics/services/__init__.py index 99e4053..bb42472 100644 --- a/src/juice_lyrics/services/__init__.py +++ b/src/juice_lyrics/services/__init__.py @@ -131,6 +131,12 @@ sanitize_support_text, support_report_data, ) +from .shell_completion import ( + CompletionNode, + CompletionOption, + completion_tree, + generate_completion, +) from .manual_identity import ( ManualIdentityDependencies, ManualIdentityResult, @@ -214,10 +220,14 @@ "DoctorCheck", "DoctorReport", "DoctorStatus", + "CompletionNode", + "CompletionOption", "render_support_report", "run_doctor", "sanitize_support_text", "support_report_data", + "completion_tree", + "generate_completion", "IdentityBackfillDependencies", "IdentityBackfillResult", "ManualIdentityDependencies", 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/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"] From 3d6fecbb630dc1405429efec20a7bb19e55e6ff8 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 22 Sep 2026 09:58:31 +0100 Subject: [PATCH 55/62] Complete final reliability acceptance --- docs/PROJECT_STATE.md | 34 +++++++++-- docs/ROADMAP.md | 7 +-- .../services/library_index_sync.py | 2 + src/juice_lyrics/services/library_status.py | 36 +++++++++--- tests/test_library_index_sync.py | 18 ++++++ tests/test_metadata_repair.py | 58 +++++++++++++++++++ tests/test_performance_regressions.py | 56 ++++++++++++++++++ 7 files changed, 196 insertions(+), 15 deletions(-) diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 964a2fa..c9f1d0c 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -56,6 +56,10 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -354,6 +358,29 @@ 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. +## 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. @@ -387,10 +414,9 @@ 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. Final performance/reliability acceptance -2. Packaging and clean installation -3. GitHub presentation/distribution -4. Beta release +1. Packaging and clean installation +2. GitHub presentation/distribution +3. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 0b5ca9c..c826cbf 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,10 +15,9 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Final performance/reliability acceptance -2. Packaging and clean installation -3. GitHub presentation/distribution -4. Beta release +1. Packaging and clean installation +2. GitHub presentation/distribution +3. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/src/juice_lyrics/services/library_index_sync.py b/src/juice_lyrics/services/library_index_sync.py index e051efd..f6d455e 100644 --- a/src/juice_lyrics/services/library_index_sync.py +++ b/src/juice_lyrics/services/library_index_sync.py @@ -24,6 +24,7 @@ LibraryStateStatus, LibraryTrack, get_library_snapshot, + state_entry_signature, ) @@ -261,6 +262,7 @@ def sync_library_index( 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 diff --git a/src/juice_lyrics/services/library_status.py b/src/juice_lyrics/services/library_status.py index 9dd88d2..2a11c20 100644 --- a/src/juice_lyrics/services/library_status.py +++ b/src/juice_lyrics/services/library_status.py @@ -80,6 +80,7 @@ class LibraryTrack: 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: @@ -222,6 +223,18 @@ def _has_timed_lrc(path: Path) -> tuple[bool, str | 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, *, @@ -258,12 +271,22 @@ def get_library_snapshot( if previous_snapshot is not None and not warnings and previous_snapshot.library_path == library_path - and previous_snapshot.state_signature == state_signature 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) @@ -272,18 +295,16 @@ def get_library_snapshot( 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) - 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 = resolved_entry if isinstance(resolved_entry, dict) else None content_sha256 = None content_fingerprint = None @@ -444,6 +465,7 @@ def get_library_snapshot( and state_status is LibraryStateStatus.CURRENT else None ), + state_entry_signature=entry_signature, ) ) return LibrarySnapshot(library_path, True, tuple(tracks), warnings, state_signature) diff --git a/tests/test_library_index_sync.py b/tests/test_library_index_sync.py index b21534e..5f2d274 100644 --- a/tests/test_library_index_sync.py +++ b/tests/test_library_index_sync.py @@ -88,6 +88,24 @@ def searcher(settings, query, refresh=False): assert second.summary == "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 == "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" diff --git a/tests/test_metadata_repair.py b/tests/test_metadata_repair.py index 5421915..334436d 100644 --- a/tests/test_metadata_repair.py +++ b/tests/test_metadata_repair.py @@ -24,6 +24,16 @@ 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 ( @@ -509,3 +519,51 @@ def test_automatic_identity_remains_unlocked_after_verified_edit(tmp_path): 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_performance_regressions.py b/tests/test_performance_regressions.py index ebb4eaf..7c5d86a 100644 --- a/tests/test_performance_regressions.py +++ b/tests/test_performance_regressions.py @@ -14,6 +14,7 @@ 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): @@ -95,3 +96,58 @@ def test_cached_hash_is_not_reused_after_same_size_replacement(tmp_path): 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 From b02c830ec7bdd6dcba5c53669b954055fd670b2a Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Tue, 22 Sep 2026 10:33:55 +0100 Subject: [PATCH 56/62] Validate packaging and clean installation --- AGENTS.md | 4 ++ MANIFEST.in | 11 ++++ README.md | 30 ++++++++--- docs/DEVELOPMENT.md | 24 +++++---- docs/PROJECT_STATE.md | 43 ++++++++++++++-- docs/ROADMAP.md | 5 +- pyproject.toml | 21 ++++++-- src/juice_lyrics/services/doctor.py | 19 +++++-- tests/test_doctor.py | 21 ++++++++ tests/test_packaging.py | 79 +++++++++++++++++++++++++++++ 10 files changed, 225 insertions(+), 32 deletions(-) create mode 100644 MANIFEST.in create mode 100644 tests/test_packaging.py diff --git a/AGENTS.md b/AGENTS.md index 3864912..8836f7a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,10 @@ 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. + 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. 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/README.md b/README.md index 952ba5c..40034d5 100644 --- a/README.md +++ b/README.md @@ -263,24 +263,42 @@ The tool follows XDG locations for its config, cache, state, and backups. ## Installation -### Recommended pipx editable install +### Recommended pipx install ```bash -pipx install --editable /absolute/path/to/juice-lyrics-codex +pipx install "git+https://github.com/NotAI-fr/juice-lyrics.git@v2-redesign" command -v 999 -999 --help +999 --version +999 doctor ``` The distribution remains named `juice-wrld-lyrics` for update compatibility. -If pipx already has an older copy, replace it deliberately: +Until a release is published, the command above installs the current +`v2-redesign` branch 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 --editable /absolute/path/to/juice-lyrics-codex +pipx install --force "git+https://github.com/NotAI-fr/juice-lyrics.git@v2-redesign" hash -r command -v 999 -999 --help +999 --version +999 doctor ``` +Repeating the `--force` command is the deterministic upgrade path while using +the development branch. Installing a locally built wheel is also supported: + +```bash +pipx install --force /absolute/path/to/juice_wrld_lyrics-1.4.0-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 diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index a1ff064..df94675 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -70,15 +70,22 @@ installed pipx copy is a frozen package snapshot and does not follow this workin tree; reinstall it deliberately after a checkpoint or use the explicit `.venv` command above. -For a deterministic editable pipx installation: +For a deterministic pipx installation that does not depend on the checkout +after installation: ```bash -pipx install --force --editable /absolute/path/to/juice-lyrics-codex +pipx install --force "git+https://github.com/NotAI-fr/juice-lyrics.git@v2-redesign" hash -r command -v 999 -999 --help +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 @@ -160,10 +167,7 @@ and restore support MP3, FLAC, and M4A. ## Source of truth and Git workflow -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. - -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. - -## Checkpoint 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/PROJECT_STATE.md b/docs/PROJECT_STATE.md index c9f1d0c..da05451 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -60,6 +60,12 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -358,6 +364,34 @@ 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. No beta version bump was made +as part of packaging acceptance. + +`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. + ## Final performance and reliability acceptance The normal launch/navigation, Browse and queue, Library Sync, manual identity, @@ -396,8 +430,8 @@ and stale State/Catalogue Issues do not remain after the controlled edit. 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. -- Packaging/install acceptance and public GitHub presentation still need a - final release pass. +- Public GitHub presentation and the beta release still need their dedicated + final passes. 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. @@ -414,9 +448,8 @@ 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. Packaging and clean installation -2. GitHub presentation/distribution -3. Beta release +1. GitHub presentation/distribution +2. Beta release ## Resume safely diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index c826cbf..651ab3f 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,9 +15,8 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. Packaging and clean installation -2. GitHub presentation/distribution -3. Beta release +1. GitHub presentation/distribution +2. Beta release Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/pyproject.toml b/pyproject.toml index 727f0c3..2fd102a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,18 +1,19 @@ [build-system] -requires = ["setuptools>=75"] +requires = ["setuptools>=77"] build-backend = "setuptools.build_meta" [project] name = "juice-wrld-lyrics" -version = "1.4.0" +dynamic = ["version"] description = "999: a Juice WRLD music hub for Linux" readme = "README.md" requires-python = ">=3.11" dependencies = [ - "mutagen>=1.47", + "mutagen>=1.47,<2.0", "textual>=1.0,<2.0", ] -license = { text = "MIT" } +license = "MIT" +license-files = ["LICENSE"] authors = [ { name = "juice-wrld-lyrics contributors" } ] @@ -20,6 +21,10 @@ keywords = ["juice-wrld", "lyrics", "mp3", "flac", "m4a", "id3", "sylt", "uslt", classifiers = [ "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", "Operating System :: POSIX :: Linux", ] @@ -29,10 +34,16 @@ classifiers = [ 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/services/doctor.py b/src/juice_lyrics/services/doctor.py index 9d62d3e..1b9ef72 100644 --- a/src/juice_lyrics/services/doctor.py +++ b/src/juice_lyrics/services/doctor.py @@ -68,9 +68,17 @@ def _nearest_existing(path: Path) -> Path | None: return candidate -def _check_runtime(command_finder: ExecutableFinder) -> DoctorCheck: +def _check_runtime( + command_finder: ExecutableFinder, + *, + invoked_command: str | None = None, +) -> DoctorCheck: try: - executable = command_finder("999") + 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'}" @@ -312,6 +320,7 @@ def run_doctor( 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.""" @@ -326,7 +335,11 @@ def safe(key: str, label: str, action: Callable[[], DoctorCheck]) -> DoctorCheck ) checks = [ - safe("runtime", "Runtime", lambda: _check_runtime(command_finder)), + 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))), diff --git a/tests/test_doctor.py b/tests/test_doctor.py index e292045..4356d59 100644 --- a/tests/test_doctor.py +++ b/tests/test_doctor.py @@ -87,6 +87,27 @@ def test_healthy_doctor_is_bounded_read_only_and_counts_supported_formats(tmp_pa 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") diff --git a/tests/test_packaging.py b/tests/test_packaging.py new file mode 100644 index 0000000..c132bc4 --- /dev/null +++ b/tests/test_packaging.py @@ -0,0 +1,79 @@ +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__ == "1.4.0" + 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", + ] + + +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 From 3b71f2036aa479d4fcc871b5842c86a525b01ebd Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Wed, 23 Sep 2026 09:47:22 +0100 Subject: [PATCH 57/62] Prepare GitHub presentation for beta --- .github/workflows/ci.yml | 33 ++++++ AGENTS.md | 3 + README.md | 28 ++++- docs/BETA_RELEASE_CHECKLIST.md | 106 +++++++++++++++++++ docs/CHANGELOG.md | 181 ++++++++++++++------------------- docs/DEVELOPMENT.md | 4 +- docs/PROJECT_STATE.md | 44 ++++++-- docs/ROADMAP.md | 5 +- docs/assets/999-dashboard.png | Bin 0 -> 78117 bytes pyproject.toml | 3 + src/juice_lyrics/__init__.py | 2 +- tests/test_packaging.py | 3 +- 12 files changed, 294 insertions(+), 118 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 docs/BETA_RELEASE_CHECKLIST.md create mode 100644 docs/assets/999-dashboard.png diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..aab80a5 --- /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-latest + strategy: + fail-fast: false + matrix: + python-version: ["3.11", "3.14"] + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + 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/AGENTS.md b/AGENTS.md index 8836f7a..4d591b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ the other `docs/` files for architecture, decisions, workflows, and UI detail. - 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. @@ -79,6 +80,8 @@ 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; diff --git a/README.md b/README.md index 40034d5..07eb030 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,29 @@ # 999 -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. +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 candidate:** `2.0.0b1` is prepared on `v2-redesign` for acceptance. +> Keep a separate backup of valuable media and review every confirmed repair. +> No release or package-registry publication has happened yet. + +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 @@ -140,6 +161,7 @@ The repository keeps its development and continuity context in version-controlle - `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 `AGENTS.md`, `docs/PROJECT_STATE.md`, and the relevant architecture or user document. @@ -290,7 +312,7 @@ Repeating the `--force` command is the deterministic upgrade path while using the development branch. Installing a locally built wheel is also supported: ```bash -pipx install --force /absolute/path/to/juice_wrld_lyrics-1.4.0-py3-none-any.whl +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 diff --git a/docs/BETA_RELEASE_CHECKLIST.md b/docs/BETA_RELEASE_CHECKLIST.md new file mode 100644 index 0000000..cf51f7a --- /dev/null +++ b/docs/BETA_RELEASE_CHECKLIST.md @@ -0,0 +1,106 @@ +# 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. + +## 1. Repository and metadata + +- [ ] `v2-redesign` is clean, pushed, and reviewed against `main`. +- [ ] `juice_lyrics.__version__`, `999 --version`, wheel metadata, and the + changelog all say `2.0.0b1`. +- [ ] The changelog heading has the actual release date instead of + `Unreleased`. +- [ ] 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. +- [ ] The synthetic screenshot contains no username, home path, token, state, + song list, or real-library data. +- [ ] 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 +``` + +- [ ] Full test suite passes with only understood environment skips. +- [ ] Wheel and sdist install independently in new environments outside the + checkout, with no source tree on `PYTHONPATH`. +- [ ] `999 --help`, `999 --version`, `juice-lyrics --version`, and + `999 doctor` work from both artifacts. +- [ ] TUI launches and exits from both artifacts. +- [ ] Bash/Zsh/Fish completion generation succeeds; syntax is checked where + the shell is installed. +- [ ] Force-reinstall, uninstall, and reinstall leave the commands and imports + in the expected state without touching application XDG data. +- [ ] 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. Manual beta acceptance + +Use an explicit backup and a small temporary copy of representative media +before testing any mutating workflow. + +- [ ] Launch, Help, navigation, Browse search/pagination/details, queue Add, + Downloads, Retry, and confirmed Download queue work. +- [ ] Sync Library handles unchanged/new/changed/removed files and remains + usable offline. +- [ ] Bandit identifies as `94107`; 10 Feet identifies as `94102`. +- [ ] Manual match/lock, unlock, Issues, Duplicates, and Missing Library behave + as documented. +- [ ] One copied MP3, FLAC, and M4A completes metadata preview/apply with its + audio payload, artwork, lyrics, unrelated tags, sidecar, backup, and lock + verified. +- [ ] Restore succeeds from a generated backup and does not delete the backup. +- [ ] rmpc verify works when installed; explicit setup is reviewed separately. +- [ ] `999 doctor --support-report` is manually reviewed for privacy before it + is attached to an issue. +- [ ] 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 e9756ee..a8410f4 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,106 +1,79 @@ # Changelog -## Unreleased — One-button Library Sync and safety hardening - -* Made Library `s` the normal background **Sync Library** action. -* Added incremental unchanged/new/changed/removed file classification, safe - catalogue backfill for Unknown tracks, changed-file identity invalidation, - removed-path retirement, cache-aware retries, and duplicate-run protection. -* Preserved conservative Bandit (`94107`) and 10 Feet (`94102`) matcher - regressions, state-conflict safety, atomic restore, and local lyric-health - classification independent of catalogue identity. -* Kept normal Sync state-only: it does not rewrite audio, sidecars, backups, - downloads, or rmpc configuration. -* Verified 410 automated tests and 14 isolated recovery smoke tests at commit - `31ebaf2`. - -## Unreleased — 999 beta identity and packaging - -* Made `999` the primary product name and console entry point while retaining - `juice-lyrics` as an alias to the same CLI implementation. -* Kept the internal `juice_lyrics` package, `juice-wrld-lyrics` distribution, - and `juice-lyrics` XDG storage namespace stable for compatibility. -* Made no-argument startup open the existing TUI and kept startup read-only with - respect to rmpc configuration and deprecated centralized lyrics paths. -* Clarified setup responsibilities: `config init` writes starter configuration, - `setup` synchronizes the library, and only explicit `rmpc setup` changes rmpc. -* Added isolated entry-point, first-run, storage compatibility, shell, and - editable-install verification. -* Verified 318 automated tests with isolated temporary HOME/XDG paths. - -## Unreleased — Native M4A library support - -* Added recursive, case-insensitive `.m4a` library discovery without broadening - support to other MP4-family extensions. -* Added native M4A title, artist, album, and duration reading through Mutagen. -* Reused the normal version/title/path/duration matcher and conservatively leaves - M4A files without title or artist metadata unmatched. -* Added standard plain-text MP4 `©lyr` embedding while preserving unrelated atoms, - the media payload, and the original audio format. -* Kept synchronized M4A timing in the authoritative adjacent `.lrc`; no - proprietary timing atom or conversion is used. -* Extended verification/status, state, backup/restore, retention recognition, - and rmpc sidecar notification to local M4A files. -* Verified 310 automated tests with isolated temporary HOME/XDG paths. - -## Unreleased — Native FLAC library support - -* Added recursive, case-insensitive MP3 and FLAC library discovery. -* Added native FLAC title, artist, album, and duration reading through Mutagen. -* Reused version/title/path/duration matching for FLAC and conservatively leaves - FLAC files without title or artist metadata unmatched. -* Added standard plain-text Vorbis `LYRICS` embedding while preserving unrelated - FLAC metadata and the audio stream; no audio conversion occurs. -* Kept synchronized FLAC timing in the authoritative adjacent `.lrc` because - FLAC/Vorbis comments have no interoperable ID3 SYLT equivalent. -* Extended library sync, verification/status, state, backup/restore, and rmpc - sidecar notification to local FLAC files. -* Generalized rolling backup recognition and restore for FLAC without changing - the newest-10 retention policy or invalidating historical MP3 manifests. -* Verified 298 automated tests with isolated temporary HOME/XDG paths. - -## 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] - Unreleased + +This is the first beta candidate for the redesigned `999` product. It is not a +published release yet. + +### 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/compare/v1.4.0-backend-complete...v2-redesign +[1.4.0]: https://github.com/NotAI-fr/juice-lyrics/releases/tag/v1.4.0-backend-complete diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index df94675..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: diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index da05451..d69eaf2 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -15,6 +15,7 @@ code and tests if a later working tree disagrees with this document. - 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 @@ -66,6 +67,13 @@ code and tests if a later working tree disagrees with this document. 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. + Publishing, tagging, and merging remain deliberately undone pending manual + acceptance and the new GitHub workflow result. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -370,8 +378,9 @@ 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. No beta version bump was made -as part of packaging acceptance. +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 @@ -392,6 +401,27 @@ 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, @@ -430,8 +460,9 @@ and stale State/Catalogue Issues do not remain after the controlled edit. 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. -- Public GitHub presentation and the beta release still need their dedicated - final passes. No package has been published and no release tag exists. +- 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. @@ -448,8 +479,9 @@ 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. GitHub presentation/distribution -2. Beta release +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 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 651ab3f..57e1ad3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -15,8 +15,9 @@ Advanced repair and recovery remain available without crowding routine use. ## Remaining sequence -1. GitHub presentation/distribution -2. Beta release +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 Do not force ambiguous tracks into identities. Do not combine these milestones into a broad rewrite. Each milestone should preserve the safety invariants in diff --git a/docs/assets/999-dashboard.png b/docs/assets/999-dashboard.png new file mode 100644 index 0000000000000000000000000000000000000000..77e12fae33644828638df6a5b30370ce7891e31b GIT binary patch literal 78117 zcmd43byQW|`!BlbF6jmX6eLBuK|rJgq)Sq|JC&3ak#3Og?(XjH?(RNwzu)+s``;aB z+;PWQI%xJOjpOI!wt=@im5$KOT~l2%E>QR*^_ii2neDG2ECYHCA`+J#JiP+1D<70Or4!9 zpGY)1Z^g^Da_mJ8{c6UH=vjwtM)HF7ifG_|{+}aFJ4Xys0SSEhtY>2q^(6yGj1*0n zbUgdQ@2Dt;PcAMlk8StN@HbRlEz~0`TVSlP{*)A5_P6PKw64?tygWzQ?5x`UVuNe%WP$n?#7l=YR%3K@baP{K6P0g)^S@W0mJ}5cv1WIB zzH>tp(enYa91#^oFo2N$pV0{j=(kNv;&zN;z2#Fz7cQ)jgO4}uw#qb6g7zcAjB-MKP zxW9E@ZErBJ994DuG-OGs)Meoqd^s>J`uIYSRTV`cf$Z3x)v|sZx#uT$Oy!hd+7^;6 zxQDdLz~I34BT5%+y2xIWyB&qB<3*mM79C~?r1iz~fP!ig!24LtsphB95U?f8+;XlWpDEn zcb1ujiIWG+KRSDqiPleeFz#@#`XfVFH@E7%s^xv^C%iRl!oj3`@wh74BnC%KV-7nwvydL&DE<~zOg;$ra^pX zH~@i2WXR7yH9yGZO$_f{DA_-x-F@BMSDmyc!8mu}YrNh^Gh3)f5KG7T?0%;^IM2oB z>sE}b> zU$m|q9%4dN?s_6?7wQ~1CPMtEkde{QyzBgtAj@U;$*cb6bH@|W+F!Rq6Cqxo({ZVh z6K0d4lc-iK%VYHXm*k1=kxu!m#y=3J5?O5Cgd)BmFMkrJ6^A!3&8JI5Ve5;r>LbWM+fm&^|%BFKR+eEbjKTj`D+9kAq=6jipG~ChoS*^*?Sk$8d0u;}T6A-tp{14d zn#odWYbL*N#w|NZODjA3wPl4&dX4NB+11}02ReMqX9fqeO6){TN^oTZ7hgN zu@!Y|TN@4`rN64QZ8EHv2BV0DMPaqX_`UBL4h2Q%qxA!e>tJM!Y+|Cpg7p-1thZ^# zb6`x0gVrcDMAoM;UwY4tq*Ar#VTfG2Cy*^!yB3OoliT6ujP9K*_*ue0sHv%)ZfA^+ zhhJc&XV!}4=WvXt*VdAdPFg}B@c!_68)dR(w($WW!wYM(gljFK=9MbkJo3-K; zu6Pv{llK2q7tNJf++W1gJjMp@># zPvdvY{x7IhS${D;dtKo|Z^8tHW<*+)CSv7A;0fo*^ZGkcT&^OWR17DM z7ne#wQIUUH**m3&9q0Rlqa(f6muCi&8P9NOWuNV#Bf|Zaf1~tZjlcMG3@2q$E0wCK zbBcGiqmYx6ooCv$^{+b1zCBKnZHoHIDyxW4QO3N_-~uB=#Wm+V&ffHjZFTS^OfI{F z#l%!xv4u8iCgQXfoRmB)qxt@Vnx2oo(Lu!?^iC{v5xrq5nB5KEUXe|;VSY|VTO{1jK{{)XdpudTWR&izLR-}Rj5uD z<|6T#l<#A`zLa>ScxnUlN0Y&=|Gq1F9CCaBrNI{Wgl!%LtG>dB1&$wq-%e zTXI6Hsj1wlg);TAS1Q zPoTsfw?3oIJ~$_W4y8!}&YUbKflZuW_jgdHT4ji2SmZ6gsApc4Ij$-y9uZvzo@FekrMRMb7l z7-hfUt(ZBo#tls}Z$J3>>}3Zs@&yZ0&ddjz{g3Z;7x)$8U6Lwaa;YKd|7m6WjMCl* zY0C7^D2CzGGNPy)O8TecW9AhViCcfRuA2H+r;B3T`Tjou<=oV8=lg7qZOXHMz6*V` zAVKuMeKykqiG)76e~xZU#BAsy``7XR8b#=M{m%*Yk>H@6=HCa;|JSF20+#Jg?1?HS zP%*7ngxTd4#u|$bu>$Z+W+n?Xx+JGl6yzU}h#sG-<15&KgURdp%s|XqiXi-QxA*2dtv9a#d~E z_Vzc3pt}ek>yW-yg)~k$j#U)5x_MqR3$_(eIy|G+z#TE7f%lh2iwti zdUp2t^XHM3IotLNt9v%jdv$)Mw_Ruujs6~?NUfveN5X|hBI^@th*ws!+RxS1Rm{qm zf8S;8r)b3N??T_5j#vDb4-U*L_&8_@j~ebMB-MP7H8o|MEswNN1v~`+T%UKmYDg@V zjg&+YVje=I4wpz#%HuI;(tKrY_dHW79u-`b!PUZ&$uz(9sAzC9C(Qfz@13r%uv(^u z2*U(!e54b5^o3`4#;)xSvXoMjMW5sB+2eEbo=mSPn~xnuEin1n4NOc-taQO46|cl& zWas2qpBK)ScZ_Z>F{xvMF&ar1*E_6NZ|{3NJ9=7fZhSbXO}wn72&L>>Tbe!7U0weu zK@txSaoQ@fTwDJcv9QSh?+LZbrOA$ztHIdyB8=Yz*8)~h&I+62sclVHw)-$Ut1u!u z-k*HVae1{PXu86db}*4=YD~H|H#e6K;zfllm!nuPnH?uwPr}piiQ(lllr%lv;?*5| ztE=PfdB0Y-gs^0082ThF6oWDBND?tSMryJmKB zii68YNFcjEqoiz+Gio*uBK+Fi40C*P(lTwmcHCBJz928F*`?3A0#FmT9r-7xH{lX; zU%uE6ydebje%$1JZeHGJZSAG-&9vNI$=AEPo2c&eBBcxsRO+Nj$<8#m$)1O#zG)q z4KOk?X6NVcuMqsZT8vECsd|wRP|zeT);gn|+MGckPdC>~Di4?104zT9dldj!#&)aNc#Y<7=3kWwtdA1S<-}vddCE)>K|Q?}qhq5d8-&_a9JE!MR~5CjlDr4I zyQoG+#1yWpERg0Cy{6?gPj~bRwFyO2(v-<@#TPvEq%*2BuNfFRY=??qA@N-Db6|LNr>2==x8V_a&F*3P{p~1ycTbOXHb!$K^*w+~Im?@yG>g%{GEUa@(0UGog4;9o(M`w3Oc~iC+*FLguY-;^YhCqD?il<7f^G~cm2o69T(p`TJ}oz0pen@Z5Mfbav>%s z$ILof#4Ga%0|Q=01L6gk*R1U1a}HXh66=SOZzs>YH*DT&*wHIBokX>nTN0-Lp(1e0 z-OW9pfHk+U)N{XEpH(WEMTFP$r1gXU+$g~SVbqSHB{rqqn!Rbrc8M#me4Z5KtLP8uP-EFHLHe35HL)>R(w> zQo7Z7z@efseI4Ka91s$M0O?P3M8kZtixIfS{?}sDGyqe6LQ^AHgL9>``=?wsfJp&ZYw zq%t5)N_JM%Ig*K(7#JAGXBQ$mziJ5ejg5`{lWAq-X(e7hgKT1#7NlxtBbue!K?CvZdTWlPFpwVcu+<3;EpLB+BvA5ju(7@7=P#wDh5kK-G}HTF z$J_j|^ltlijxR6$#L`<1K3O0^#wRD!%F7k^FO=2Q=NK*)a^Fa>CjZgMINrn=r5EK* zjQi~}aNNi0{}O^u#)b`;_Rp<{I9ORB?B$i6@Avg?{K^)kDt zsH>*G3^Y|i9i0@S*Ode*z51+9cTPcDL4kqCBmR`B)z#Cf4&{*=jD)gNQ>2CR&gQH& zWX{gc+Y@<&x_WnT5XnzwTY~nA=F$u@8A-xYX6S(JDe;y)1CVsO$&nIsU%;!jwifeX zX=E+y#ar89H76$*;q(!^*~c-NL;_jT5V5~m8G7s4;gEhlZ{q);HBIf>eAmp>LQKp0 zOYTq#uE5ziH6nDxgdR@s3Cntf8Y#qPUPogQ5s|8K$E-xq1&?L@!;_*yJ)id0ESeq$ zH}~J}9rM4n4TSZQQMQhhd>6SZ`B1#l_KS`E<2@P{){)#C05=_4dGa~9_4N&M@)~au zQ(y)*v&{JCm%u3FAz|IWF3i+YRP@O|+ak9RS63y_ht(;g3QyP2&}jEffQ5w{9v=1z zWWN`PE4zw$dho_NUi(hjLA@;`B&1Tm?oeNI%MdI@Hj(PU<8ogf-J{=%=IPP0d!%y8 z;(uvfpjW!VGQs;-`86Ix9~8HPBir9z6-%+1S9WD->8aU7{o9dTcD##i1$ts_ZDSqi zXl~~#0xs*7MI9f$YSrAEw3Lb#AHLt)-JD&SGyj%ND4RDibvQ8Pc9JERKcuZHMu@SQ4L=7vduvZmPiDw~`@@EE03|jS7#DTRI{YkoS$mhTt<*NZ=g(VtuZ)b1b2y8> zxqi%$Pxv_0Jn}*uCdO0W%BJ)n;BfndDpK+*8wvRTSxqgFsp0{8j+|P z;nIBMTTB{W7)$y7Wm0}KwnlS_U0<-_!9c!XevK_7BLnHDR=W3ssdhSf-W#vvhSX0# z9vvCg(l!QXQb7Vx;Lk)J2f?g7pX6jFzc8}zO#F9b##saO6-P@|lnR;Bz7Y|)ht+#B z@CZoMFZkd#Ha3P$Dv%ErNLyN3oURTWXD_Z*{662^-oQXmnKXqzICBA>54b_c%1yzA zV8v@Xy4IuxS7rdPf#&+PwH;-;(mq}~F{l**+*a`npa`LwJPvB+wl+4cb>Prmpoe~XrQ**!2&v0Fn&31H&^(p2TW(M^be@2m-6>7Ji^U?b>Tt|O_G$sB%Usl z6UrcP!S`Spo3*AC7BR$ z5D)-Ys>)5~Gh)viO88o4Q!7Q&CKARA-%Q5e2%yUA*RP@A4=AI4ca$oKLfF_ucmZ`D zccgU(OpJ`3wH15C>!Gi(;bGQjrJAo%aPv*#kjz3$;j^P|J}}`Ev;s&yn(+x46O&*s zH*X&)8*=>MNXlX}F7Y~2vOj?j%^#CO*uWs;O9z&*&ch_AP*Q6 z|6P){Z$}J*Bq}nCQ?P+z5=QuR|ATYAf_BeRKO{sfKC+jA-lOTVH}AD^iLRT8BpttI z-Jl7kn5Hl0)9rRLlrgd2IojKnp){$<=P3SquP(%Y^Nn@!W{(Fn@=DaeV6hi~)5>XR z=-NMkcByj_Z%NI^ut0;(M9NI(g1PnWH9hOqYwP;U)4b|mi3}Ebd3kNh+8(}?SmjSn|F&b&3Say`^pr;1 z5HUC`Sy`gpT{%@%=K<#2ygf@XwE_Z?0z|QNlnn!e)!nm8K&WM9WdX7Ttd()E19X{X zz<2=FEFEPfLifv?>|3{Sa;k3Y=|PFCl~nxlrKC!W!|L4Wmt@9ptx2j<&Syw zfhTiUPEbE1LwU957Zy_G=;SmMgKuwdO|`%Ot7!z(e$m%|$!<1{J(cmlc^@N1;jaV_ zCaM1sX8%=cnrQwz?ZL0^|Nkgt{GXl5SUvEt?#WSe0rTJ80!W-n?zM*siaQs4Hgo2v zat-zMwYB8`E~MaHfz2})3o7?`*l}eomzun}{{SkW4lk^b{a>#3{GScd|Lq#q|Alu& zeXxUwJrYu+{4IOJSwxc@6%}=V672^B%F_ikHOT=kyvOHdvgwDX2KDEypQ_z%N~H%hn;tMaUxu`l(I>Y6YnVHuVcZr}25S2# zVbH%*3kw(Sj2|B{AR!?k*?Y~8F0Ff(jWAfUSb65a1USCbew-CyC_Or&bPuSn=dC}^ zdfMB`EdMD*U_fn(vMp!t{E2 z$W7Xgq8>0$;1H+Hm|nkbPWARLUh_Xlyi85x_D}DU7KaBaz~a3#R5TH)W@Uz|VNiVe zXnqc&0{_Ya_%(V9?IvsA3sl$D0ex|FFFei#m8a5D+(F5~|5CO|20XWShJ(#9e_7;A z*;XBZ{x+~=*?L9VbaZT9e>@t*92e|#dLqDS#|NH`lT!@bOJxoY4aT?oR_fcg8(T;I z0uM{c)RB@r_erE=WWirNT^3E$&CMAG_4ReOLNz(vcNN9s=Qj9ny9AbZcM*ZC=!k{Y zpYXmcE8eb6rCy&!ER1+;*8q^l&>?|`{I)6<`&+jD7#29x4B>f0Hj?nz*q@${Yss&f z==YAzML&EHN}s5_K{6NL!$(CBcD?cweJ%u~5+E$6?ZJb$yX*jMWsmR3P4`BhbZ1NS zt20xstgI|dQh0iL_Qwlgp`f6sJZ!3yWA}K7&}A*1s+LON!8~+uMXVH8QX&W?m-d_QKme+AKv0;7h8r)t<*d(zcF|G! z+zx825o^a7Nr)ee39WqI`)_7u?O1aj#Wnk8n=_b4o~wU<0_PA0$T`IZeFT4^{sijL zfz7LTb`@_{36>)7>2$g#!SDB13sp-(%AbJ>fE7&fj-;@#5E&DtlkaLFsHyPrQ}mL@ zrx3Apkqep#y^ATH^u#+$Hj;3w0PI8Uz(bloD79M{wyt(U)Sizsd{p| zW_~PQ{Ro~fH9+7sTs2^vB{g4Fnl0*9n1g|A5Y){D zY-w=w9;;Db;EG?Uc$u(~l$dS}Qq-95YN3euKj-EqsdG4N1zd~Ayor!WqugcS?DVoz z1WUk&_?^-7E!{(m_xKnUiE8P7KogqM_Lz8eN6FzqCPjm*<#}O`M@Z<{V-E4Es#1=g zgwwH-6tyGQ1%3u!A+Sg1DlOXfxyr0h+dpbFx)F=`V;uaR<32sZ!CQ~_7e1J&ART(T z2?Mx4;D9oS|Es&zV**$I@#$&nF-{u}@F?cz7XZzaQ&RK0ujk#LuNk8=D?<(oXs$ld z!yzF-^_Blg=Z@doD;XXY6{`I^EHyj3dy_i^1B2){GkgS%te<}t5?ybf_3gQ_*=%*r zgfYS{hlO_B2bJ*-(ln9BUoA7&%f4wjg_K_KgNRqcU^~#WF^=BVDb_$ENW}Jw1LYD zZBM-`e@qCdcmbh5TZX@iq>f~N*3kF?8dzXa83A-c{Z$TdYApYY2bFp4?AXLYC=h_? z42+o)^F5{U$rx?IbsH{3T67_OQFt~r1``t#ITg78ZzQZ)^fr6_C!1I@TpH>2nSQAR zPLI}2en6G`lX#HuH#Vjx#%=G#)>l`-pe^~0|G@+PcA)~?c$8#d(8*%m(W-B>Ry(l# z&0!S*`}Rpi*`6w*R5Zbt{M7f$jg6RiXGb@rDvYD^<*SwT6WngI%iF0@ukUc!1Qel1 z>~2AReu&UQm?f`Z&3^V4$h$wY8$bW*(SQB+bu%zRQuBsq7L?U1G9CtQ?(Xy?TCuN@ z;01y63xpl8%+`Qdr0(8WQ(L1eCI9S)w>Ja=4EnEEg_;h@@gRD|$dAcVQgVE3C2oFT z@Fz0r`G!6!cvZ)VEj#7W?DyH@UmRv07x;LAsX&G*tEr*E3@j2KUw@Gd`Lw@(@dOS9 zyudV5o45!%MAFt4sCKPx>6;@3fv}h+tM6Z=&!#?!?-|%|84e^Fj5UIal$t;8F#CPc z{Z?mqS?Kz)E(CCZa87QV@85;8a|*@8#1JvbdB=C3xSq4ZwuuLO#mCdz)k@wwEkhqX zi|yrGvQPYmXN`YHzA*!02)d|HhCFnl_@WV7-AAvzW@55zdm$xiw+2OHQ@#c2mCpf- z2V<;aceiR$GY}Yv3T*(k7O`j$B4!|0rz~E~)nSw4>U}xd-1GyBomqEWqW)=dDZkMP zi-MKtN}#yk1XH>|DaflC(tde_1wLXDcxuhWXcI#hH#5t3T3lElZ@4=bl9R(;bidP# zzx}8{^MZ!GGnfA@FFHs!?FM<+NufsxRL`5RU@3Db!y_PkZSTfWdFWK{9%y)m%5CEr zN%tx(J-xuhmT^;OHh3rCz;mOKlaMora*>ch%jX1_R^{MsacRMEf~kdXfR)Lhuehd6 zh2YH_lS)V!FwCF7c(DRFSAh~*tdw8=nJO52{`!W7)Uh4Vw*&X{-?9i|9FPb4Q+N;+ zS`>B<^@&THW9aJYF&pgSxdCAaNED<{&r)~x+_-z7r^dvK+jjEp`o`8zm|V4jPTL^? zBqmEsMMXtH&^n&HAn24VWbStt9lIRL>YCaGBg%e);HnW12}fv8syjw(G)QEd9G!x{#{z8=%drRNlj!rFmdrfI3Yd zDh~pEPKRN6%ST68i8B79zvZuQZgjy&$FS>>EV`^QiyA`{$mS?N%;gpwR0RYE zwnoq=3xjxuQ9&B)UpToxz3}Xh*X5D_C-`@j+D1nl*vEY(dIgBt)D6PS=C^FXUejx7MHt?(1J&d?9UZjc zQ-7V7t8ch1Qc}Q{j^##x#!fmr#Wd=zKq2@pL6#Ws;Ce-EJg@TS&mWbB!pq$WG}%Ho zRA6HQeNEV08smqE@Gnk7HYjZvP}bHyW1)Fo8x95Mdp}YOW%hGMczyOw21Ei=mUT|f zCkNDVi12(sW!9)wgaVZXHf8u9eD;pnTYICl`I9=*$Dusk@)ygNJocibrnR72**y(u0+0mzqt2iDPiFR>Ln{H>u{ANp3Bt^ z90Up!@9nl}$H&J3bX#k@JHl-n)9dN_m6#Y3Gff1=!Fdy_j(vw+$w^P?*BOK1cj~{i zy+BccM>Sck=uZK~)%VxW4WK2+4fqHyjW?bU2!2m;~X~Rp2fo>hL2{ zxU5sZ)hZ>z$H!MWSx5a79VrA_lXd{;%ux)U5JptO`o~>U&IoHnFRpgC;}xWmcfHeB`Y^#!dn zhcA&guY@Aid}GTDg%4L@!NM6#;tL8s50=@%uQT0Ze5+-{qr}?)tL=XCKJ*ps+(Hr1 zgQ1aLKr622>W+R2TvylDf?7%00ZhHF*x+}ou3Npd$^lakb4yF&s;b0Fd}j#@m7HqY z3JTs+TFzg1J@0JK&yfE~o8$&tQc@BS94rbj0_4or$g|<4nqxl|~kUa6iFx&014Gq4nIWMtrc3 zsqv*pj;F~6s;JlpSO_dEtQqY1e!f}#?J50g@wJgMUyxQR&@CgOfutVs2o?a9zQwu7 zQatW3^WPp*ZaSFH1Ok>#0c}NmW|M4`w`fPZ*yyYUMygz^glMpITDDnFq2NWLNtY^Pb$Z7@thB}Ak&L1We zXeM;aa*{7FB8+B@$+Do)kck*9)M#xtRkBjEn^p{nHzI~lbTnb5`3#+37DO&%YHjTO zUh%H%klyHe4`-wc>W2>>04?$GDLd4V#Q4+{sBi1*3)Er2gF)4cf!WAYBVF4Lch!!Qr=)f!D% znB7~f6&Zf6gS*2DSb3v!7}Dsu z1i8lFfUn|t@|JF?-3b&wK{n@E2|wy}sV#&m(tXfyBLk7FK(v{KZy*C?(PWDPEPfC} ziKJ*+NG;6~Z`!c$7+S&tvq(brQ`K#12?)d|7u=!4Az`%oe8lab)I&u>U0&OxuXKKF zy*WNU_KJ?C1+UmTGeZn)8wuGm3T`H3*v7|I`n;*LgE^1p`kOOsBBJrbyR~n3FlT4= z8)s?YHRCxfJGJ`9-e+Z{G2dlm-F}q>KBf!(` z+hn-j8K#b3=KT5%*3HeW_z}d;8#e5@$s2F)Kk+`UI}^^^%R(o1 zAS4t@#{VOQ>MXjWIKYZU(Ej|f(r_WJVl{99kW~;!fb@$rzr8$~WAZBp#k?ylx%v=x zeERW$Wh;scz}qgz#Bnq^<cZt*V|3^NUPxGf)W3nN&; zS%LI-ef~tqs38cd@$Kav+E39R0Ez&mr)6qt9&UnlK^Qb2T|K=5xN*ZXWeOe#bP)D$ zPi(3|1Cs)z(W0mGiZiw|cU}bs1)60#Lm=)MizZ2uuuw=aJPZM#oRX3f8n*l1B6NM! z^;ENKZQa1>y!v;bQXwY`3c-CYF)K(@U^jisXN7YVp(|M}gy092Aa(*(L=RQCM83zl zwf++b-f;qnBAAG))uh@|%IxhQ$&72a2AmMG_s|e1wBS~7PdO-?5RZ$A#w;DFxnkrM z6nt<|BLNM`?C?umy#J3M!ss7~V4=nw5i%AQ7MPW(+IDOptCXBf2`^L}>s=*TR7IS* zG(C;npoLY@dD&1|KxXb~3*tc&0~nxb{^H^hnK)0fM8Ss%D2k@_C`ruYp{K8#U^htW z5&dY*LL-#`0a+5WnR9|Q$} zTGb!eIsYv+LH_s5+NNAZu!3APx~r7~q}T zH5dTu`TkcW>qG`YkOcx!Dn@^;qAu5?`Z?njVQ1%>f!sC#ADzxmx~zuWuL9dH)yGN+ zZET|uvU_{gJjwd{dY5;0P(bqo8sGZXMvyk%T~|jcR4n-&!Qy&I2EY@GAVW7(aqR;z zfrx_$m^u^GH+6wLe{KB)W46?|km;Yaal>XXs|b{viV60M@zqyTdEQ{STMUJ?okZa& z-0wf%Kc*s`YzaK>)Oyz2F=(|x1hd{*D&)OqkACl1p+^dV!kL|SnJ>y6vnMX|d^1D$ zJ%M^a6v>I2-W5#X`Sv4G90U}6eV(G3CI>K%P%ICicAl2w!iTx>^n%=8vJ_P@%jvuD z?$g=L-Ce)>d0wy|K!h%`6-3S+)^0(TPq#0V0UEVC2S7hb+E!+>3R%wHfq>CuuS7pA z{Q#-oR&yxfJ#KnLr%HoB@SM9}!-$Gj;PB6O#X4P~o6^D5o*m=PjALpETP zw^cHzhet+kEc5MaFnGGrGtzZ7@!!${Ry@F`Ao4?9^Y7Sapf;;iIgmFlUGsr-Y~aTT z+LaMning<%!e;{hAW{hjIlMiv+&>i0k#neK&@8xco;43c1NUwJjIRoG!3M3CyK;Tit`IKy&cQ)39&dZu?e-UGxiY>+7hS8e?S*Ec+UU8U5N zuT|h^Vj9PUI&tdet}v}^ncZYlqhaxdDMFLW^X7EJVQDFfgoFfaL0Q^0@H3oC%otRP zw%>BAntBHIocL3^!h>wTr~4k0=HlHDFOxA0*uFv)-FF~^uTy+h4eOP<<-XPj>Z+DChDjPJmK#Y$L)j^uQ9!7*GX zODPr4j}N7@F(n^W&U#45rmLPLzm7%Uynj+3Thku*Ea<0iqwE6d5ga0->C_JMTJQ0h z8N>LE>bgmdAZ4CPBn%24uv)}H*n$6g?vB%wAFVbJ70`uw+ocBGu&2vIO6IG^!QNis z)tHfMkF~4S-i;v7qPxr5^vF7+Gp4_9 ztZR#=S=`j*X`_9?RIwl8+0*D~*?89!(g+JnH+Qn{__!h)Fxj=G*j_R}9mgaak*Bb; zIY<|AiO*p{`l1B9rXNeD%Un62d9UBA&w!;Z1h$7fU~fSnI%-mEHOAEfOwS{kB`I`HGQ9*?JLk)8X5Y=mzo-4J4+H0f(@TKk#whgN50a2 zf(yFJ%T=Uyz25R1C<&E{V7rd4)4F@B^3v3*{iR1VomfTMRHpXTBjIS2Yzv^ah2l>bka%QXh}?y#BBF1FB%Ip6$nVq&F{eER#kBTAxhlZx}>^0VuR@9;==rb z+v9Qbjkx5eetQJzqOSlLK*O9+vK$PE}<3R1`cm>#5$y|D28P}`_NT;-4hJoy+ zp2}I%d!>p3=~r@-<7E?VZ3~;MSh7Q=kI1ST8o^-2cuSLVtegn&hW?D8(S2%kPb}rs zHG1Z`U)LE%aS$18^Y`!P{C@l?&wkR(3Xw-?{v) zSj*!A^9@?BPP9W`eBG9V?p0KA+H1`VO`?8Yi=!!^=@}59lSC;`Q#YF4^I>H)CrBO4 zP3lU|x1gC70fV8mN1#dNcB89U+E;Nxsn62a5Z5Z$zML%jZq) z$b^3mciR8iWpx8Ap{tlR+%`2WEh`NN3SEr`rmrxyg@DIBCveQe*&Om0 zC{*#0BXaa}Plpci9Z*N`VJIX;KFMredF#CnSr&y#` z7=S-|!^_{HI<>t_3uy=K(*xz9rc2ns67(a;^260)R|B9+yYm$XK+_FGqR_wu!a>NA z2d#{>HQfas5DWlNDj&dOeSCa`(qS2yP$ESFO**Jd2!t(ARDMMnK5A!VWu(ih5S6Pj z09M1p%hm*d9AH2tf7=~oMnC`j$v!ujzy$|lIv@i$TW^R?KIwwI7zeDO1PkuMcv;Qy z#QlcN9(~sKj;>TNE?Yy1d%x#G0|Q|pfBtCPeBM&AVTI_N{^`LyD$2}6w6L%+PrB?L zxh>RjE(|7n-@91~jMdrt>+Lxl?g!GU;$Cnkr(sma`Ie`GV1ern4p(&4*3xP^1h);~Y2 zB4rP-2QVHuS?Lp0)j5uZVPPD?uKvP6)YB@eQfpoTI~YJzoT$wYtL?z?ZOdU|ot%QY zH`qkKa>)~wGJ8`K^Pen0W#yy^{%LEgFld732UCP#-(1Hs`+*$^SPK)otMoz9^P#|V zl}VKJEfhuq2pp)|RBzv+10_MJ?V%53>Omg?);%s%MvZS;@<~Y0Kz@b-NFz1}6$Jph z(~SrI4gygefgri(2WIZyL>ZBfA5ln1NkCZ+feH*j6u!GU@GeZNs5u~8TU~uFGcqz- zm{`}I^8yeEuwNHAvEZ$|LDC&luBEo(uHCTmPHNHkTz?M ze?aK)GdMu_pscyHV82&q;qEw9QD>??S6ioKMwQJLjtPsBC@AdmqCwVhQ9u}zmB@mO$#S?iGpsJP9$%8GzZ(yiTN5w2i7)Duy@+P!p^5pm0Y^^~MBMFC0)q-_h z5!Tsl4{xPJhD9fICdz|%KjyN8mL zl=f5lhselCFeJM+ObZoxQ{OuKiR1W;Ds$=RD~yIHKra7{!K&yhEb`e+qbS~L(VV(5 zyX#?UFb+L)UE;X38QpDdB0K(b6kw-3qdt5#q!s}fU0HlY3kwVQBm^##SE^b{h4y=s z(ED{*nFg+W1z1Swj{ZeOMfpm3jX?R!pybc5JFJmRm=Z?8ogDP6Wrk+n?2Bvq%`}vt08F zaoNa-KA3EJ9GV)R9!>$P{2OqmI!{45xZymE@W4>p0{p#?kJdk1UH#^yHOf7oU^Lwi z-v9nPuW_dpW>}_rR+LbLpv+LLo)nRo4&tO8D=GrFRyiiQrff&2&b5|34-R`KrY09h zRZ9-n{a2rbJQ@uLYem->E00=?OH|G~dYQ;*$oJ?hEiLOx7}e*Bzk1`OEIOS@#{q6G z67TPMUVP$m5Le;A5f3)iU4(5t74jU_e6rmfcppW{;~+J}{}8N+eX~9$%RL`lV|2pT zxhL?j62@(Jyzb=EC!k&k1BYlbnNh~JH>&zOZfL-t((N_a2sRMQ(`BKaxZq)GI+;Jx zuNvKL#%{WXaDV;i_=bgLB&K-Kq=F92MSkr@4IsPOe5Hd zSMteeg%b1oH?XB2I%mtr+1C8zZ&&O+TgAIir{XLw{?DS72eu2srPrOV4+C zK9K5h#tn{JR;XQcnilOLRn4a%Q35Tp9&A(hd}wOg9!b6rYinF`I>2ytaWS6nSPM=j zl$Mru*$b)q1J>gq-~LmAsY&TK!1CjqC5L)JqN(9#v`@y8Cc(7pQ>baP*CPqPZuP<` zDB|v?BV7(0ceQ|^$peW9bBap-Y>cp|{yuP_WX_De;duT`&FMl|I*wHptisZwt7~ib zlG7metBXO;r@VjwWa&8Gp2Mw8+acaLL$BHJ%ZMzQ5owO4_2Zcj9E_}5Mq~rSmY!$T zWeUTEz*y%yTOX^vTdcExz@V*CRZvJbNM;zT@7v^Z>jWE_I2PT~+fEx?uXdZB9xbDH zAzo*(J%(kkhLQz5uUfp3WS2-F+&yOOdmYMJzhAl^KO(7J?iiU@o}HY0b{a}L0Fh-q zIzNB^zN`zWDy2L+dipO)N|T3r9xN;@fdRq4CQKA=SK8eABUT@ek93}&Q% z192=hsllaZXh=3B1OpTkWhJGkwzU}`!lUw@AZvd7_;UflU42h2YGPtCHzg&-xi$IP z3BeaWuR2@8AB)^!R*#N~O3?aY6{r?Pr>CqLlroOoT$18p9H4qpWJ$?PsDaHn@t(~t z&d$a<_kuS_@UQPwqCyj6%IPy@gZm9R@CgWr8eG)W-JW!TS|x*OYs~zM@|PU2oom1zRKmbLLRuy!CVV`+ z?d|Y%a}OpL@$;yxtY{E430X`B>ygF%R^m4ZN|3o!gJ=XD4UHJg_wTtyc?#CnKSK=+ zEANiFK*4*sy;1;9_FIA=;9vi-W=rqeIuTyq*~zK)utr5k|2<-&u8vrgMJ!a6>U>$yS}oL+JfS}adcD!;0bhWt`9Fjlgo7I zg!B*f*~Ul==(E0IXOzLgY4`$qA{-KCZf>bONXDUJqLkbv4o4nTF~<+wo@qa&tz~pw z)GggtF4$V7n%t;v?{8U&J3BeOe$G1Tq^+!+1^xsN=7QJh$;k-F$Ec7 zVV8SQRB{AxGwJv|Y=RF!cJN|*C3Q9Jc^z@XLJxWP9i<{@vZ%og)+A1fvM{-JoRqy=3vjqkF?u7@RJiIC-XNZELHrG~I}bf)Wm%3?TH89@qO1 z{qN#I^dwXs3_D2cebHV@sjt`A(BCS*yXyt7@_@vK1@l>5JufZoxq*>E)g5u!O#XDW zir)PkxE|2ix!st!XBU^A^otaX)I7t~XDON9SZ~+N*+^?@DQz-SScOsWu`%;&QKwSp z=4X$C<%CBmAn}PpBaK7LRda8$u*`HR&(ZSYaKX)7{mYjEuqoD`WeR3ln2?gP2xMz9 zUkM^u$y8vkYff1kIB zQ;e!x)@QuWQ%-(_gIK}D^6S+WHhm3Ga^0LMV_kUz(fFnYt4Ohebe#AzBhPq{0UOJp}o@YOMueJ8t%R-}xvqZo5Bwn2T9i2a5O=7gI zu2y2Y#}O^QHB2NBUa!xi!5pG><58f}Uc6hy=7OggPum?LCo^b$Dw~~sI~YUr)v!(LEB zp(?^qI}sY*l|OJyN2&!K*QS+IQc^A8W~9i;-C?F^ZEo(y+f`)aGBrv|?h{QPoK`wQ zM6^_~A|51yoNKtA9)XxQq(q#TAHIF)0RR~zFR9+>*jN(iy3#`Qj}XzqhZ7O~_Dsph zkcRt!<~&AJ>8Ozz8s|gQal%xS0?fkx{tS^HVg2{70{31Z=3>Z?!Ug2j$j=Kh$Y1{X z`F;F<`(ORDFnhEtGd}+6iIXR!gCUNoscQ}V*?0(#IU_@Giq~5cv~J`VC|RUg+1ZtB z zs-XnP$j^V)e2u|CscAw?D52d8AWwihNU!sv4L);RmKc!Ra zTZdw3=%P~aC1nU>+}_@uLwhcS4g7LxgnHoY`Lkadjb}T=pq-YSmX_Uhv)lEDjiqI9 z5AEd1lP86;6W+F(hBB67v99STSv=e!h@ejKJ8cYhI&q|D&srAnL2Rk6mKgiRqZL(F zNczvG|Mu#$q5osY!OySgURv7J@>6McL2ZAfuS!kQIQe?g_0TWT$spg84TdX3fBA5W zTEs0EWCBdmSNtBjm%8s5PRQ77nZ6!!k!KD8Wk_m9cPcBi7CzC}(#imdh(*ng9kkz1 zDh1&zaiQmOy4I+=CuU}D`PC)v?{3bm`&6R4#v14bb=c*#oyM-qKbD5*nFcU+p$E>g z;&8z;Upw2yCd8N7YQbc+r^?3%)Sz0~8W8-Ips?yV9i-zl>2~ToW&A06kB)^^=%jtu zMas~djT!k?d+hwSrjOKZ0Kz3LG)#eXwlMthx*R*Hy4>@T15qoc50`Kg>CyFVeGfD>YbM@ntu1t}dGj;Ly=~?yJ zLff9lZ(mZ&>K8{IDXPGefwOcSJWswMuuRcn%W~vU3mkZPyLQtZ#-e-EH(aJ}v$5e% zJ5!8QJ-J1u>K~iN;j9?JUD~?(@A}rAMlM1XDkYj69p5;%Fdt5FaRb6|%(ow}jsl6u z=B-pd$@P^BJ`29)bS76N&(R-e$m(h0_J8k_ehG=;5EmDJ*ig%I=Z-RB0W^7VbxPaQrM-PNV? zcJq86a-nNN`))H*LLd)%M@*AyaW}PjXh;w9%O%r$WjY84Jn76>t3YHz)!s-P4vZr7 zd}^-43byiUIxY>lNGW%qDN6`b_q`l1Rwt92hkch*7_nWR0tHXwCTIrHJn+0&<$RyvGrMv5!C8}J<+ z@lfYm9aipZyS3sT<#d5cd3wMsR`mg@V#wuP0HtlYeuZVx@cyE3a55bp!^Xp-23(sM z!TsMy%*g}SIQz%_xnat?`bSu2_yigH$SjZ{y1RQePIj;F_n4i}g2wqZ$N}-mhG5XSU|(BRQmAYgNqG-x)YO(lDa#8RKR=2Vlqn>jKxxZf4b0$wT|VC zL1k#5pJV{|Ud_p3qpYm|Y_qb_&;m0I1Zdi#&QVQJQW$BOyxnJ%CnvvIqnkrUz&RA}%g&xvV(#QLvh-PWR-F>Imjdj-KGKsuuf|vF#B6x`|wQ2pTtIccNUpv8q&3LEn;-B?AJky!Cw>v%cd?LX(<_ z)=w9;uz=&ZtK(S>Bk!qd&rQCdpfZcGN3CT}VJ)Twrg}oMCMG6L0?*YzKh0k+o1K-V zrfq2%9;j)#&`1rq*Xh7k(*o!Z_;y1okebY@s2^(<1W$rpx@>->8G$JPx@2NxHiy!< zZFJz@1GtR=&dv(sUUpv-5Z3iVoo`;QC@wcwv~&2tS?Zb4jpyioJMS zMg`jQ^->%k(&H0af)>oqYmo6F`O?gHD#_L2pt74~PRs(JvG^+PN zS5Yh*f+bb+?A+Y?pIwI8jGM7eLN5R2p7z)74pQ=Ft;QGUQ%yvn0Z-ok*#JbH*sW%=G@Ech-4MWWxUZ+jeCCvF(QIZ;n~A%gAzxI{ zQsmo6K2+JSAw~TSK$~s}G1tEhg+-?O1SuND+zwxN7h|CUr4Ht)bu&;=N#r;1QMJg( zn947|+Y5rSFVbYrW3BuETFKA#WotShFnptFQ7pv_4=l~?L=e(GAOKvRO~AYUG!Fjp z;|I?*riXsEy2%J5QDHkIh|YJsGF0+7Bu%ap{1pm4`)mOamk!R7mxn@`6HNk@bZ?a7aJT<(u!J398#AvjVqi9w8OT`}W%OOz4Wq=5iNt#OPZlTdG$^M#|IF9@rx`ThN&o#=b81fDP3blau=)oSM8gLWv zA_Tq_Q-|FXnz{)Pb(-FW7Ukd-u9MTzWrIRJTdSfBulpXhX>}|_ z9{`b4pk{d}`KY9fw&r*3@rYJaNLL1NDe$J%AHW(1wYu&>tU$?LP>QerGQ=-IOmZg7 zI8F}UAbz*8xjCHi#Hmx*lHd?X&`k24IF%>Y{(Wsc-S+nO%F@!OprD{kS%+`IkfV_lPir)daEx%~=OMXXy`oNy^HQnlZY5 z`_qv!Y#EUmAbdr(t=eD^S5kHv`LaosmHKnNS?U1JXUg6Iw+Ar)7{r;t|N70-=6gOD zzabGY*QdD2Ua1KkglJA!)INEnmzUPmoahPjk$8`0RIMwLA$1g&mGJ;E?RAEk?UhrIWaHfJ+3k0lQJ2qboM%%t=K(fH*Z2fn&n(`MQ z|4>uY4X^R?LS3e&o}J}}m)KKJJviBKbL_vz7B7TP`vmAn=@Z=?P6Beya;#o{=Xb>> z-JmY8HIRC!Jb3W>V0ZDbBwhyIAl?QNl1L#`WX%dx^j3XsF`Vh?HlQYm^qDv+tpa)i z4b*n%U%Z5Z`e={K8(&}WW1)}<1_ar1z^qwlZ{XsMN9I6VN_Rz^ZULOX-@$Q&;!e_M+sqo^|A1<_n@U_GpMO)7^Q)kkddRl&d<+J zC#~3bfZ7Oh0jm8L&-}P`J~WF%78edFad2=*4?mv<@%lOhSycrWSYv>gqYa{=>6iQx zb>h1nkI*X~XW$C{@dfxo+n4bAl)AqD@B|^sSY`43aBwn$64SQk;x**rDA#9kvcYPf z4C1r0vI3*;Bd2KFqwJNoA9($;V^9yh>2WY_K$Pf0|F4ly*G~?t$2h;!uMi)>_b?+WoFA2B+Z)( zLzy=Z_B7MtGP6O(#ztYjP+rO%p)h=Zq}-xF-+jhp?7j=wDpI>H3m74(Z4kYOr0XwK z+9fhFMcWQz6}ZgIA(eF1NJ`S!|{Q8t4K2-l@C>ohIvlgTS6*6e#zs;Lk?2}*y*nQ3i9#+`iE0igOxVeyq217RZ_9F_>;uc z#_T%wxKQn#@4ir221i9j)wrN5CoNl}oj7X8|gYA0x1~OpU#~nemoW{jW2i4ojW_fkQ>!%D!SG2dgD)Oa?cQ! ziFfn7O(_vNBSYC%0WA~65Z>d3Ic&;AtF3g5bK3YE9_+KSvIhf7@Q9V0wd={^++60t zu^m}UZ(|$9!B~YDC`ezN8vwQL?%m$?K6 zQFf^PVf%l}DwGR`+JWV79ghHF9$TGKm!X}ZV1ON{U1^nP&k}|X>`G=HF)=a0z3bQW zBvGLJHJPkThwI$YF*Y^+IVOn*UIt1h8lxXOTU*m@*hLld>Bh9AEBX~3oCpseQfJut zDidve_o}>{Tu;_OIQ1MXLv?K) z)3f8!fbp1N;A%3=oBnu06PBfWa55mGmaVh6;N&3johL{+#!2s!XIr&OBCP`FF**5_ znbnDAbrs!2Ktm=b$7L)R?(NLV=746faXR~|H24N|wPN-pf_W@^SW*@g2wfXh2Rl}J z?zqt4WQdV-W6?oO(v1&70?y$$qA-QqC08J(ZHBg*s=8}MfY8U7FN&Prke=s| z^P?!}2a=BBvqjd(l@Xsfz;#n!ydXjrikRCX3MflfMjpw7BdssT!S%pDYB(>?LC9nL zy@RO6CxfRLAE^4Exq2EV2B@p5hS*}qT*huCgFaYwJI7}6U!fP9w5 zroo@ih+R=eY#`Hl>>Y885CWQvoWf+m+{lg&$_;}W@CrOGF7`9CKO2A1_&mB7&6_jIe=w1It2Pk9h0*@k)oWM~krd?Lp z8VLp={(WRB%+tYI1(zu))1m(p@Wr8L=Y8M{n@ztQBt~lGqO-glSN!13$7!a(+%!49 z`YN^|KwDN;UR5j8ucjBsJ!Uz%PJrVfpyMW!z^tRd0(dXJ>6A zS}4ow5mhSq5#R&@lYaVSlHweZ-(o*EQgZet{AmW77>%o4Niw zyFzd*M<<-J zSW{GlK}l<4HjIOMV1;BJzBs6N(~07^faCdn`N(4OYw;XyDmdU{d+b$R)X z5P<<}zOlhvrr*}?<3k9SyR#0e*RI$e9>4(CXYdWvrCK_wncv99J{G5cLkrC{^bG7U z%>-f>dR}E-VPR*NgFuBSbdZAqR)Bk3jMbA6pql!l7|-_1fRhRc_YMJk7%SM;x}1veV2+`s>d@fILmFoNJCFl&qN zPfOoqShs66wK?2DvkB?=Kne`b71yMpBd=@GdsWA1r5kbzOCU`M#mef=+{a1IoGI3s znwhbXt951tR!AM{K;BFZHh1%U@ET00t(AoRijcB{aJ0jtD|`MEzM|(F`t%{BcgVjF z*k84$N~j+$gH}mq|zWOdxWGP~(9cml!+;eIl^+e*C37xQMi^s?y(CIiI2_Im3EFP-_ z=Xs62o79g6;t=7n4977lA%ALl4UL*_`;cd&iAp3au=pm~BqolakmaowB z@pMDOMBcS8-*>TPs4?2CUF~o^?+Do6V5M)Q$&VZ?L*UHAYu$evs_FrGk}~&hW?)2B zgL{+=a?}m7yTD!t`pr`r4%Zq6fk4>X+e6qA>DG!{Re+%U+o>W(mQ`y1j=p`fF z9#}?y_tJ9kC1PrkC;O+?T+>ssvgA&Y(00V%dyQnT275c<2%-VX3m)^O-+XfnqAvc- z^0CQ(F(UGe^78wTah_cq5YdMX=PcAK4)}%D@pQUz=obT^*mok9KDK_2#R z)ucRJyazPZ6 z{Y#Tii}Ui7@x?aI=BGecfEphgGjgRvGF4=Y0L9#g9+G0*xm418*A{s4r%W8&JJ~7 zFW^5NZ@yeMqCHT3`|cep4^PiC(Be0%sXK2pyoQX4f*y)VH4QaOVAcu6g8i27y6J>n zSXRGi-NP4vTRb=|Tdbza1CNmcehh5a?%ace0F&D-$n1}M^q;~y$vc7?Bs@AM5f4>)qitf`&u7qDHgOP*X z^zdM--_E);!hHbphlQ6{9mFoeUiEOp-cH5#0dK)$I!}q{MbK#d(o#Wfj7!YQ z>Iz}dXSJ2TskJq<$7@V47&Nh_n2{SZGp)PmoV#IhWp-wB+KN{OhaFss4i3xr8Q?gz z`d$6BX{I0I*>KYmG@e(>1YvuY*|89B+U@sUW{x3)d zm7wL9D?kv7drV)X&lV(Q2c!=YJWgqkQ7%RE#aK~J^l2g@FU|Y+AFTQKY!@JchOy61 znov6&O-YvPxj`yA|1UbV5PhV+p}}gVE9Jq=%a5F^>+7M7)*4N3oL$_9P&NjmqtS)vAI6>)d}-7j2wJ)uPEkEMQl8@Q$R2nhdg2O|Mpgx^V2@W0;a{K)Ps$xAoK=W|JB=A{)hP_`rk`> zGsGuhW0{|xn)-+@>Oa5~U#2|NhJWwnt#^Q3;(Gp1_wxU;693=9)IdgYu#_eaI?U>S z;jw$)@9osY9i)Tg0HDm0@h;i5{&t_q{~Ltte>k2WL%0+1V@Qn&;sucU{VfD#bzSqOPgamwof`3#*n$R7QOuT~fG# z2T;PLXwEdeAVZrXYzZiCaL=|?eLQ7g_j9KIEM5KMbyULj!HYo>s9qcL3glD(uZ0%; zH1*6%6&rbi)_|tDdAdl2NNCj99>v$Vs;Zs(`lj}g!>oC-YH6RXZU!dlQyYtYR)=1# zwnH|Uk<^#V%fZQU2U|BsoGrktru$1qE5$fa>w_iF#su+wzu$b{`Oblv9t#qi?eIp# z`ZIS;r`P-RyAM#i?J~q86U(v0a2#1K{3`X>h%f`WN4IGd=p{Mae;ko@MZ z#c%-VtPy+(Kw1(yAx3FLx98;a1)4fEnvyT?A1rqtUc+DP)Axyiy}ahv;O$+HKic8` zN3_PINSoJVp0Z+nQs+@MQho(c-_;iNSo<_EAE~Se`EJpCcl%}PE2%v_g^p!8&>_qQ zMX?3lFF?zJ5O}t`do>HUq({Fv&;g0hQtY3z#Kg|j@$ZiNvXq;Z+!5Z+s4_r=T36^( zLD<9Vu)?^%8mdY6YV5@e3HZv39h)5^?TYYCid+}7wkZRuNK7eEJuOcq&Y}-C00IY!oXnTrjbn@b!X(2+~YD z_K`A^Or)!$fHNiq?$q#G@}mfv@#6W|sS9Xu+*dqb@w{wVx4WyW z5L$?kPhk~mIxXJ*4vyN2{a*aa%39afmowCH-1p}CP^jKw((2EEjYZ-z>B7=dQb9Vy zT5i@}kk0`1CljeW6#RYH>llb@pQt7PH5}iGLpvw zT-ly}5D3VEs`-=j<;whg83>Y^_Mq(r#vq8E9`3&~$QQ8*@=&r|xnr!Zr-hCQy6r1JE|=(v1#)q{ye~FYH1#z4ZGYXa=oT zXHEj-b@7H&IvTA2$}Xp!U*N+7>xGSnQBAqC6C`nGMLUJd9?HvSZ!9?ca*?VM*Ta2Y z?H=#|fZwD*3ooiUJUk3cuq4Dlc*nVw&8h++PqFs8O=2Q@4_K|BWnl8FyROK!+n|wC zx|@$=we&rMNj6_w|~8w&$$ zq@=rd5+4Q8XE#q7B$&l|XoJ`-Unl%4k0k$)SIDr}n0&TgMg0?cTG}jMdiN*5)RXKU z7*0^^ELI&Fm2ZN)#m4p5LM}}6*l;DB{D^GHZB0%kP+ZN2ff!?2id3}AHmK$dnJTC> z(4Zz$z&oj#wYR%ElzSf>l&zwLc^NI@vuX0FAE&3Pw%-7+wTw@t}j?admqhVx}1P~AGi$d65`X0+n>O~$$ zpFxLfncH5S$E=;AR2+({2F588m zm(=sFn*jd^dd>CDkRz66bBq2!_w%|p8IPf04ypb@gX~Uc5JM;igGrtoIYBDE^=TQ) z3@s(lAD|wf2b;^N618wO>VX^ZS;{9FjuNIuf#ERJJ|RbO8p;`LB$BCu zwyL?rn?I@*lv3_O_P<}~VRy=ehTOUXSUEX6kw%@GJVY(IIgEJ%t!v+8k9>nRwu413 zpJE-pr@tj2#CN#G#e`-X9Ij}(*a)re&wLDwjce<@>$zb4@ZqCbU(&sfnM&yWMAq9n zRI<>>mp!xk6AxW==GRVaM|p98u-4IsF!OvR*D9Tc5cZH;bs}AXPp# zHs%bovZgC{7yH^7cC~zuwy8qKoROG#|K-cpYZg`B`+!&D`a9BJ0$dInv8Is`12{F( z2s4&^Q8F8(U_rgpQtO+#iY15aR!l-(Z|L{-f?_)MYmMKb;J>K zu+evO-rIX)y7K|DBo?c7WBI%aU{a1hR&f1V14k6N!I5^48V2I7otmM3WHZVlwF{w zrTUWrxdOfS+Qn^PUJ!%=SOky=ikTMLR!*Ekj(pLBxe>~#2GatIhCsT(eD?wXLV((p zgS;bB$mSce($N(QLeRa|c#XQ=pDuI2(KItX{c%qD+DB+wVuKV4^UFIE6YyoYtijecWNH1olTo3=yKJ@Y!g#bT)fy?4B zM@Zw^Aq+xSvhx*J-;;;3cI^_~trCC499TnijKzGoeRWIZ`C^3dqNqOd$CT*# zfPia!d~gJ|R91L8ILz$iG*^qEi2BRi{hU4AO-z`e)^^?o&FfKV1f>#0-u$`K8xtgwLQ4tw|Q4A;Lq z8RoN33@sH2p zHp85cwj#JY0Cxm_;U6L?HbDGyyPu}MPbiq43M`*lX4fh6KlJWduRDY9`t|Gl)0mx`Z%S_KehJfA zTsrcHk?AH3S|4s>8w^KXrK!+wC%6v3%!#v$vN19=V&UX0zI6*{*!`$klmKb*{KjAW zU8h;i#lWE1lQmQZHUI!o&-g|Aji2j!c13JqYrZjP2-04oq7X-H=>R*h+SGDbdvD^r zUM$82W-2h$DyD6vqeYeQ;eJBy!nt##X<)~M=7RkL`{T{fvH}G~0p#{@CzLaBy@ZR$ zZor^D)3N%t05L*Vo4z<*XT*U6bL^|T(w*^l&$RbHs}a!C^^c08Q8o+ya`N>{WHp`` zi8t!=F>@*s$L@NN-9O#Qw>{Z&B-T<9U`o;_kEBc%+KutO+15k(INLYrU@Zy8sEpUH z(Tn@|U^_)WqNkp+2-+CrmNO-Mn-1i^FiK(Dz98yP<3lBr5**4_Nhlse>laZMX}1>6 z%J{sB5y*%oo3rwB9+X&=IFqJ?)gYy1q90s5Sv-Ik2SK9w_Ggu3!qkVn4$l zBr=~HppZsz5`m>JDJ7Mp#!7YJ;`icg232L{w!$?FnBWlKnJ(!4>!4Z2!Ql>sDybuK zUwJ;mKFpiXOqr_if2EOGXUq*#TYdCLq)tD}b86IN*IOZfnh_Gs#~i?xQ~B}t?@E!w zb|2@Neg^NQYo-Me%1Kh61-L)M@wKwwv^byY<@t>xsjXe_S8m2S^Qhl}%jzxp$2O$b4J{W5>2iyuH1_X>9pd)xn?K*3vj~xZz+QPDV!; z5R?;Cb4t}R;3O<#fIxNjTet*Kk&rSB+87jg5Z8>o3*lyc3jyF51W*XFtu*|C{sma) ziJh6#X1fgoZrV+w$2VqP%cLM?8|;TWG|Y05KRfyzetoaJ8XSjQ_w3=(B$*9DiiEN6yi9;-M zBZO)SqIR6pjBK?eGfK%mU<&h$%+1Z8;(KjkynW0BW*N)`JS#cToJ4z@NrwW_#TvM` zZ@EA`20&uGL6tW=N_%i{Xkuf(p>Rr4GQQV5odv`2GBPf_eah?#yOp)I@#MUgTr|&T zNM|a$^9mb=hGN9-p;&%$O@H>l+~4a0uZ`83O>tz*C#yr~L z{H=Xp3oDDFX>fFOO#1fiBa?yGOm6GI`kk7Z8uu+s&{J#k-wn><&w-|EYGwmqtR+&^ z?~g+bL4TyDf5%J-r8h@f$i2CkR#NgcFFe3#{Tr@#W*10*Gt-~ClzOG!(Vd+K4t%lD z><_a4Gw076BmOC+r4Co;i1zQ_rxbExf$V5{-6P6p(uN$jlpX@bdm4 zJUyO>!MKKxR$Tz@7X0e>pu2<4qZ&LCFN1fF4{DZcJhr81z;$8Hs(nqd`TR#m_uax_ zaoAsAFOvKF8`~LD(uO)5IrK}3?QeyU#Hu$G@ls8C8Hl%SD4LDlVr8%GYY)Hon%z%| zPVo7gPsgs+-mE3NLVr@?K+w-4mMiAN;eQ?sb^6fHT{)HC9ry4;d>rSx3hT^y5?8w# zFMD0{I1_Jm{vWox1Tyz&wV{L zA>rlwm&ZBj>+d#y z9+;_KAcpEqkjS1HTQ8-XQ|qc@GHd9(F+O&j)J(A}RT3P$7sf zLT-F~91Q&xp=h$+01R2j$`oT-vqKEu<55cB^=o$!Qpkny3-`Ui(%`{s6LNR13e6}& z+vfV1^`QWbqPO=Eq3poiC3_N6Go34AtwJy0(}Z*bFc*A(c6a) zUziAG`T3cYAtxCB;p~;`*9Y~Z$6<4TCmy2hlLuq*vc%bUbtm3j7~&G|fX5ogZeXUAjOCa}mb~`bkPGk7=SFDL=agyVG_vdP?_BIDqs(JfGn{ z?l45$ha`QFu6$G+U{(_D7N1)6!dMUA*SDnyhmL1E{>?VQXb|+u#qbs3xNg&_t5{~p z(}_JL@@>;Te|=Y?czx4HDph--zw-4lty7N`q?x%{^KpEim6hT2#P4^`I=R?Xz-OH~ zbB&oVEE8S%apZ7>0p?_lzup{PRIAXv_Qny4$QK}K({AtnbS zUq4aj+HVZrM8C^u&}oWFpLkaW!u>*p)Fsy>8=YeAXFra2rKQ~k(>%C}&bf7%C-X{C{NPO{x^(c5Rn^{}EQnD{ zH+HNdz=I5^6&OLK?>T|9Mg3rZGfnSHLTA{pLC46*ytL-nuB5E|QXwq~jSeIo-hB~e zTiUq5n_-dB@)famd#q;@<9y^LXo0NgTCPBosIL3Ex_OaylzJq?Uh8XsFOekiE9w(i zuj9%V!HuZ4p)VYiFb9i4L0VGnkdHzYWTk-*6!53!c@OHq%B}fT5)MONqsjBYEj=s9 zhK&#SI;MHwv9cYLk?~>ba9zZ87vunOj~0& z`~0lE#lVIS!rO;+zoZMJd!U9jv)tjiqH9vM_;lmm!T#W!o=~NqUocFGy6xC2M@>zg zo|7q+RK!m22=ksQb+%*VccYC2%VCh%FQ?{Kk@dbRWQGS+Y!G!|&_^)Rf+Ab=8DocU z+hnT(8`fKU6Lvm%2eCG`wx%G8>s9uS2^i7x@g8*muQwZwT%VO3#m@fz$4~{sbll)p z%W+V2?aeV9j<#VJenZE28r&HOQ{X2D6D;5u(h8|18p+;^1sT0Po(|)tFOP;OicL)F*iQbDVn~H42;lgrkvRdwty8iJFAE&@1r_X%S&IOH-s>Bn z6`}ParFZ(}v9MF&CMhXBIGnT4ftI6b2p=EaD4LS3zex$?@VG5)Vu%a zQG;b&X-Ua#ZVN_WtcYkupT7a3D4}nTiqDHu*md5iMCpSH1B0F}(a^{$v^fM$jXSOQzulUkb{#0;JIraQt%ce44bc0Pg@QaQpwj>k9A4*>y8Kc9jhpNgJ3lvx+SiZxfKKYilR zQwNBa{!*i~p$&*&hVSY|2?TkR9vxFkO4vh|HYz6SEA)>*%#7cwFeX#Azx^Q57lt(IK`-!j^v|<+z>a)*F2zW`IeY^3v@xGvn*=2c6M51l$4g` zKifYU<B>{cBuNF6AR_rjfly}%4APbdZn^M z(GCyv@3FJ zsq*QfICzu7?TEd3@wlYCywBo$8=FJV3DImnFVrrT2<&;GEUYa@)s#QCnrZq4>Wjxr zSRXp^&}VDN-ZwnT91^iEzHdyZ0pZZe^OO<~AD+Ov?(gk356o4ipmcy#Cp1+EcE|l) z= zWMq_i<2>?94hPc2YVe!z>yqKEVA}|VbUrEV@16`pXahp>e;6zc4{@n(%D@TFvuJSi zf&J~Tt^SYS-@GOGp~$Ki$ku`GXJ_CosvZYRkpKPI`%YSr4c&sWH8RYypaN1x*wGXC z2{sRwe827+RjA`b5f6j7H%ykGqi4fj5?)lxrJ0lcau!nj+UnB)*2L{JdL=IxQK{IdUggAKYyR?wd>dkUk+lp zV8ln*aZ6I592R-|zSqsyejpR2dxhMrd%EWZtM#$(zXauQeYioUoS`O4_wnzoHh(QM z@o4m?-x8&J_xA(-{xO~6VME+AT#v(rLijwkgbSAiXiqF> zk>CEege`O;KqKfeWc2C=$P2x9cSrur&Nems85qK0GQ}G!i-T5!<4;#pTSaLE+FTzglur7#oKR_5Vm5T7g1G*94j1mfk7WXYjrx-4 zo0)LMQ&)GZk8GIDFLt_tj|r%rC3E@!2I)-7BWfu%8A9{rY(_;vRs_ZYRG~fUq|Rxz6}6&wq4L7v|hp(Y3d^*cWN z?)EmER0Gg(&+C5He!Alt;uH;m(_=ACGs$IR>pyqo%`}}c+!AE^K(<1|!G1&uOQ<9% zos6;C<$+Tq{e`k|u?jmA-P@a1IU#vmHKqoZ+N_#-j=T(qn?8IW$SN?gnK`AAB^Phl zJ30a$iwq^qCpE^`0o=7c*X>h)KWLvi0EjYL!$^}gR99^5IVX)ceFcUdfr~XzRUa8D z4~K<>(074GF}+{211*WKVKAmK_ws17pUvQ}s%fz~PXuyXoop{yu(GwCOxR^Wu##j& z#RgcpK+jyMTDpEJpB+U5DC?UKWRxPtx53Z<1sr3=w!=Tn;!uHk3Ew$6L5YL@${$p6 z(E-31A|)N2=0E~|`*#JYkW(Are#ULT1n2SCAk45^x9R0SfAJrOqo|#=Bh|*-Fi5xE zl}$6>q2`epR(b6@o2Hl5KGshbUq!D&uMguOu_%s12Fo`0>OU?2>tp}PzeVz1@o_ca zN}he3Ut}oIWs{bdE{zc`K^L!WI?hs8S9d<}kB4d8oYoCFbyo5!_wi@oIlg;$qrhyF z9!^aJgaT;Qr2zrj#TmRIFM61SLo)xJw`-09M^zG(>^DWvQC$>A2#QMW{NsSz|4e2? zm+!~`!0a{`z%M++1-uunu!p}9?F}0_>iUy6K&|Q6e;{FcCC+DuO5Z~iI{qZj`#;_I zH6SOeXx5zC8qIm@nM5to%JbE%oDbBOAKK@>1X;V|Y|kxST|Fu>F9BqPlK#g9v?C%OX>>ZbHZGH3R4b1E4PZ+m=NQN|X1=5MudoEU*tw!E4YOsgo z(SC2sL2Q3qb#`tRrj!EQ_x)?@q{3R_boL;PmaeL5&4vyBgW`L$Ut7&jFs2+tM)iSA z9_BnW-r7MB(AWOg8~ylb5got>AlOof7Px02eT(R(Vyv;Gm&oD%bd{b=WJ&+esW z0>fBdzQr_`S8O}b6yk$wLZhGysMT_rx+oGz7+QL9v1_pxmv6viLAIQ#oigX$pgHex zpa~3nrj-FEM#hFYvmS7X9sbzagn0Tz^ULaY&qZNt12r{CNX>}OUNwAre5N~Xwad>B zdhzWtbGAKZxWl}bQ{*o>wtmCyO@1D^5clbYMrP41BYVPnU!q2)`{58cSPlj8HOxN# zVF`EPmrDcT@;JrP=qgu#fIXdv@o6HigSit?b=WWtz21eqx;iMj3-Oc4P~1%1^O^wu zPk?TkhJ3j8;9c&Yv~^@!jGkEKeTVJC`pUC6h^S2$8Yd-eJElpQHX zq<%Cft1-=*{fvgqO-(Q$z%@LO_|uo@^VR&#m3afUd{Nsj+h>VX9tF&<>^ju}k4DF= z_+4dc{g*O$H%34u4uNfJYv&2Zsz^K0mn0=U{r$RlHbyussWYurzLjY0+)RV0-$Fup zmcP&bSR4?({YBZ?Mb@%ZpzC~D9p2x%-MvoKwUX;CgX&GiA!MQq0AZz z#qF<*K{RpwN$6oNJ^X$OCU5Ocd`LqK(2EHC23%&3op{cn%Yti@KWFLY1;+@xIAw%o zmAJ{rIS7L5&NW9L<~XmtJD)#)hHb8N9V zAoA~vK!qsn8EkDbuXN|^bdbfohHT-bxd+=H#%U5H|~Sc}P;u~AAWnn1BM z1)>N7y=-RpfK6sjP6PZzJ{FBirMVOZMgni%yh~JLB|LguhQ*F8EZAmC52`}@=M8?T z+6Dx8D7M4bW9_PBL2&In(qo}YC14*fzq{ihdwmd2#tcfBgVYR@=(cMXz1u7N7A8J! zuL`&=U1$iTw<)RsWN;UvPwOl%z*~2$HrQ>;x0#{AaLck$Q=tM=;#PN)8O9@TxzwGF zIy68)t(uv=4RY(Lvi#oMv%mKj;@e;~UFn*~B`E}nvl{6sZ;*|I$`B50p4 z$^3<#c*1f02FIDM6a$VT>DZ%`=TBlcK+qqSe>{85Ob4KF&Vn?xwsjWhgq{6=T~9FefG$sVcUf4l!RYbC;^MHaH*sX?X?}i3-qZ25q}oV4B?7JnPiNGy5kmxrt&~IW<--@% zM30zn0trkkZUcwfU9$z+C~cT%k8b(Od+bHP9KXvpiU{;DOB>7ehjMy-3rc!6TDhP; zYB1fc{`ojqC76JRj|FWS9CFYanvY*}VE*IGnbc`6|B5`0bux)mthT*92o_doYt=ak zDCn?#Y?sf%%%~w2LkFOPC;!w;_jK~%VH7*rO)Yd43_8|ZD)~=JdAhU0_-xfN81kB; zsC41~AnYr{s#>FN!A`J|R>39|5NQm;0u)q0K#=b4R#Xg96hulSm2Lq6krIh5(%s!H zeaG^6&iCE>=kDk6oJWbh_FC^d-#Nz^b4*$Y3@skM@9Wb<4R9SvA=bxrfQ|l3oJcU4 zd5==N-z`XD5}%x%ReXHw7lDLq#h!Dj$Sg&vQ`a^~PI zmk;_)w2xeH;I50i>vA_tL*+IznQVE0_=5-Jcka~g>*-HHvmY4+qfq&a-qUX#7tB{@ zeup&X=uwd|?dihQANvf`qm7M?t-q9M>x@)ZA1w$hW{WrCz_GBHwYIZM(J2t4U`%Iz zzgPU&FLve)MmcSKrz`;#Jrxm`xpSvzEGV1DrtZ-_YHDgkmH_^-EEn|60F*NzZE6kvhR+4c648{cV^7g3(omNk!QL(B5XxN@f-MA2TcQ5xL zI%m*{RmY<#)6&vL8q=U*T}M{8mKuDvyO={`=r(9p5~8!QiOB=wnO(%+f?MqXScrdr zq-OuG79i?>RRnDp_e4|7pd7W9^f*V|_zr?$wKE&4gjw7$eTmorWBywH=beOB3Klu7 zCsbZY1*s0cN@z%O*qoQUR)0Gr?JI<~U8pWqievqmqnJ5a9cUts9<`qzy~b_ORF0UC zq{B$3f2gzk!(B3qv@|+WX?}IJ%Y^ZDj$;t%AM0ZmS_<4-B6UV*N~BmS5TN^^^XL7} z-*>`2&Ng~70n#@j^W*cHvpS00jsj%B%k<^)+M14`06|&)m1AhyT9U#rK3+s*2U!OS zd5Lwi_y^Kjw{rPA&X>SWaI^rPcqinFfKA?w z^6a7`Ir1doSoxgdvCfyA|Epdae-9^-B(uKqM!SiQ{9unFG5bsFwvQ`)H)61UhO;%8 zLY#mGF7b2>_m^>!1k1Xp4j|@_1ygKxM$_smU+$-_4AzOL+x`R}gMkX(uhG#bd|Bi< zZs@+>_HR%kzPSFsg8$EN+_L#!)Z*{vrkH8kpbM-L+Ywmgtoez5!r4yuVlgQFKgP%F z=1p!i{WP%8m0~uYX6?^czqJ*4tv4SXB%?bC5}FZ`5pAxy|9%o|+wx~i`lC_TZTa@a z1P0Q5iqW&>+wte3sytpE-rS%k{{AWD!LJCkuqB)S?+5P%`DPzzlUPekM0pMq<>$0U zSxG1u|Geku=YyusIoy9Cm%kS;D6uE{&sYEcr}F{;il$~_&L|K$&jd<5KnxAODJxrF z{Xpr=M;)CO(_vP7xQWLqq@>G~JbV7UbJdk0v3Yf>%Ma80WT}`&2qI#9b%K9+{W{`c zzyLuM&mtt5Q*Th*S)kd1 z8+CaQaFV40O2HfQIy#ghJq^IXi4x3a==t$dUf=5KPCUxb8<3o@2h-j^1v!$;s7|XU zhd+<`z%HZJrHcDj1wR##o+bW%LIs_Nwe2TrNLND7Ubf?7AwvfOPz>?Vo4fYxIkL4z z`AmfLRnu!6m}3|&6(aOyx{e>aFZXgn&^fyU)mn;@7I*f~uPr)euR!5p_<2%nkNB~B zc^6>0ioBr`S|*%`1{uLG3FP4%m*xqC4592%ltuvg0ziFVg$#pIq|UAt(wwKoJC3R; zZz8QtE4NyYIm`F?CJw_GV-ifDf4B8 z;`>9D_AR{{H)_tO9l7~}^uAaaCKrhk1xKDLB0dJzC#x21yCxYT7E`-t56v|>>w}~(;8zX2Zu`Vq#@+oMJ{piDiKC7y_^BDtj6i{D%Q~sQ14(^cjJahiw z4q{AR#Vt{*R)_PK)t)9Bj`CTKH9TCm5#6Y6lGlq`m5Q(}t!BBf7-ud4KUW`X_mm!d z)Ykm+a8;EX{dwQRRhO;1q&(L?Xr4R$%sYrIumrT=*?U5-~(FF;4bBn_#uuTCBKp8bUXJ==J^Z11S z(mYXPDP(A=t9LN&`U<49MmNpv(*8@&u7mpB47u2oSuN}ZxaNvsdFZJ9`n{SxZg(cD zEgvEZLIeXdQcmmdUWS6{*CH?wCPu-tasO%G1Y|JleK{!2;@@6hoH2*fsO<7^rqjK7 zB3Jq_@3ldfAIbm6=xFWpHlJ>v@;|4=4ZZ=CLVPW^Oq4{COq?bTAE+W8Qy#p4vP79( z>8W4a%ha`W#*7KzvF%kr*ZGa6+}LwA+4lPzz7X z4;j;0_3yiIkOX;X!QA+5#YF3mHx%vH6Y4p2;AuKH#>CGb0J7-Ojz5~DZ<}|h)C}xH zfA|UZ1eJP^AXu51m+|7+;1e;s-C#b&u_wrn3TY8EeaR->#di~kCHg(wdx!h;i($89 zOtT)Ji>X)P;FY|j{A^ern018sp6JmNr&%%V7wsb<+&)Se8tan(6+$o~K)u-3{9ztN zdwHHIISg-;j)`7ga(yKv7zA+*e37NV2fW$;W(NpQBoJ;lB)gtC2^mfAyZ7<7DY!bH z*MS=@AU*<@VfLuuw4Kpra2z<#eYHM!WifdmSGgNn1p3CR(Hcqj0yYwP@)tgx;sT}7rE}+cNR_GJ?>OXDSQT#xKVfL?}?^&Cjf`_ zOq-{m@aLt=Czw6NERTM=&4-XPBIW>AF>al$zvZQT0fUGye+Z+tYUCjVzsmNjqJEWS z{;Lpn{6Xnd&VYWuSUR}p(WA=LJb@r5fh9^{bGioOU0vTkEICTt(BA>*rKh)#IGTpu za-lHFpdmf^98BEPcgzo)JRsjQtFWk_8W?Bjg^pjV--Dh){7Jlg&O02H*zk=l4UZxs zeE@EB`}edq66jx>&9DI+qc&jVR$r(q;}N9HNCcBpoN~$E^6DMKQKdf8jG3glMh<(1 zdwZW8=4m)au(7yxq6ziQvE~W&!+#+5xhy?`{C{L$=3a)*PD1te>y>n{!(#udjbYW& z3$<~1L;6&f?^0GW0oYrPCAQ2EvNcc~W^gu0hSFKcer-L9iHX_ih}fD}TN2{pdI$4X zS{E1f60&`_`W#EA_TgNi^x`|V6VZ8fp+&f~C9ge85CZ+X9izQ~Z24*o;SUGccXg@L ziLB(gETSNAi2?`8HWD&2JE5f>nRfvJnM3bl&aOAgnbfp;!uEJq*O6T`b&QG3llKU4 zt1M5R;_HW{1G{mY*0)=)FU!661JY&}3>PMmNcWhy&YbZ=apwbnoZyuuPC8-3t8Pyo zKc46)pfo|7#zeNbqn?b6`M1L7(0;5gH-zvwEOMz_ReUlxE_Hv5lw_WslS1G^?Z)fT z7-F9?LOYxu4{w0JbOn~@$%iiQl3JN%$G~HMR5t~kdSZp1DnQlMH8dxGl(8#_FBBIR z8^X%x^h79F)$s(DXH!onN+_z;v_2cvwaC_yS!IIob znreQdwU|$K;bK1N>UG4t<&Dz|%`#4DmElvATRI4y5o+03xukEJsVSU+qf*f3m#nRX zSft;5IS_g|bNu1b+dLHpj7W;LSSq~g^X$3%VT4}4`-(S|335puI8) z=`@=XJ+12O_H;Pz17|&IYh*Nb&zed~V3rwKblfpntX>(f5K@DQ+UTnjTbcHvdm;%U zPJ*`4o7%_nJcqGbPmn{Bq;tN}VK$P6u+c8DEwXU3yQ@N+bf2wn$& z-igMN5cro|A{gR1ghMj9Ec1^NrH_Dq7@t{EX{NVeFo!m^uA$+3vr(=FeJ@J6rok-f z$~j@VSGCTq1HD9VgvI=xpX}j`7!Rn@o6#OfhFtJ;pVCG2fmR5r=ox^@EKH6li>1^dv2El;uPs`bY}SJ2^@YSG zg9S>h+T%f_?LB{_vhVHv`+VrbsBn1JsNZKTDH-$pqE<7%9)N97|5KArYg!UBmg4Ku zIAJjY*1ju@QaJT0jpj(1N;hP1HeyB#7rM=S7g%nL!g9 zU`j<6RxP%EV$x|>`xbII7VMi};0Y~3a^>EiJD2A)V})#cf39OL zQ6UM;X5{Unrq-#q1g;0XaqnJQwbn5Zzd*a8qcE6t;XTb+W~gA3sc|X+pu6FAjt!yJ zgGlASYJN&$Vm*tqY7afV!E{M$0lhP7c)g|7l>)Mc6uperqejBM73#%;6$JwOvrGpo!mk#VHtpCRiyar$(M$6FoG!#rc^RCdlF$*hdPAb-lirGi?0u9D@K!6S^mYIpk1u(Q_vkCv@ zkGDC_aJ<5_92``mbK@;K&y9e&TzBc&8_nqlR0$6qH7#((Xy*c{xH|w|DPe7gP+_B9f2QD=8^$rJ#t6O|3ChB3e!) zgLxW<;s{yVf)TxStBl7W(vSJS1=l!I%$U0>5yk zF$@n6eXpp{Km*3@*BMZ=#@SIrMGM0AGiU+g0&Sa?zs$r$U?rKLCT7Vp+KrKd_IXqM z+=dMeLoPblWolzzPD6*7>YG1!6`c=MR8)Fh6N;>9WwUK<{i7=&{!sr1y@*Qu`s%{Y zZ9^`1qnPY3@PsUnt6@W7*gE>T-C-esRBzPdj(pXR*l0G7bz}NY#mAY?tV|7JifyC5 zu+=7ipmm6lz-8`wjt^v)EqwWNWH&KC90~_f0Ojvqv@`qj8?oWIjg`y&mX!wy9zeFU zmMuIGg`H$QdGvw$5nMjED2Y^8lfU~FtCXS=AJ2;__4FIFwm{!L#^?#2R1=7y(2|i! zDTqpJJ@=wo9$PvEN@Yt0mdZJ&mndHoamqd|*-0qe`k(;?uYdx-2())}bJt#~Ivfcf zKrD+qZvfaqu1;^er($l zvv#G*`hWJ(@vSwIKgv?}QP3mLf48xaeZrj3UQc*>~k0lhvI$KRx-nM?;F2>5~%hF%=pM* z2IM4>6gSQrNrBVd-@AW@8{L%<&RO@SU&%*SUVoI~Ghg-<^?D^9(V!1e1BxwEj;1lQ z+{J47%DFry^yvU*yjD^6vc({yrD-Sxffk98ypv(ol;|Oz&k3zbn?&Rehz@*|rY7mIwZ^OM&xe1oYySp4VTi^WnIDvpjWAn(uNmEoBxtiutZ7fUK%E|;!*;z!4taGdBJhXY)+5G6&v((#(!<18dLM6Ze7v$2o8G_#( z4650r=H`Hl^s#rEmHysDP_mbA=(AM+ib{gQ0p4e*U@ynr;uK)R;P2zNl$0va5~1KQ z`mR>*^Yj?MKaa_}&B@6lV&;}lancWKlzkq1I&3rG-97;mS>q%9JeuXcPkdEXt>=TR z;zsAk8q0EXmafq8zRDiIm8?0d3rom}+jgpF4qmx(Lmi0;>Ta?`zz0ZL%FE?BKgNAL zeERfucd>%-QlH7GAw}{9Go7@1T=!Tp;}`7J*W}L^b#$oT?B5STkHUe=JmTVu)fE*x z<0M^CJYwo#of?9(%pG}A(2=dxM)>!;F&Cq1JMH?eTFA-qNVrR2%QqH6rN5qt^h~-IeJVxw9ykT?fq2X8@e`hsN8^S3; zQSmh$ul)wVn&^ZqS2*K|s)U6o37J?aIQGClmQgzUE zJQwKObEJU}?85)8~&>rjN%#JW3R)>yKtT6f(k*fRgY?Jm zKYm;q{iyltbt#lWZ$UvA&stgRoq?C%>zP(SjJdbE5#L=tYB@Z<{R`=&Y-++Z4Cq^G1pUcip;Ne2V z&CF6-yW;$Q5MlI#7EsrnwY7H$E;Z^M8FZUpV47ojKA9B==|xeSjSi0<$)%giXB4Gs z&eEWj1}Ia{Q(B`$w9?$BLKq;THI6H4yG9RPh;J8vz8 zS6O^g(QYNJE-!@E6E)}i+94#8!=ve1nwm(-g$-u~L`YY!Np`_@Gqurj?%YiN5@Vua zMUy0b_95XA+55IcPlA8*_!lU%kjBwGHZsSSP1NBc}{s z2l8kXyZ%ujo%oFEzk04BHEZlk!)@WFj0^~n0DiWIpQSD`s8n5bMQT_+MK`U&Qmc9X zE`miyyL~|RcxC`me<9sW9kcr#>UuW#qn-TSdp|I0wamb(trBh;h6ZXJ{sdl$hQkLL zg=TYkI?&^k`LcCq8_7z`YAwC5YqUmQIw6pv-SCi;NlIZ=Xe`-e-~Rn+d^bbG(C)CQ z*n?ItV`aoH3eCxrz<#Yxt?qA+Rq6P8B~mir2Z(?2vfE40tna}-pDBxKP9;@V_T^Z$ z^)?MBsCDMd%ViMv4{}h`)}86|9sjO{6Xlv_BZ0hTa}1aQ7p0c8JH+ejH#@4SfXxi1 zpR>B2yuW>F5C9IwYM^(4hQ@8*z8>^>Y02vKD-wNxKwWJnayQ>oicpA3akFKC;5*+o5y*f38xfmX({Y<6$(rqcA zH;le`OG`J@S0QR{e*0FPb9ElNyzS`+X=zTJNMtvp9G%zlI=scoiqf@2==@xKVfT%- z`K{ZMW1oG35M1f=zUds{$_GVeEvqNSA!)moeL+$xvtonsZ58`vkTo zvU~)1x>e~R$4Lvzu)4K z`?*&;r4F_Slps5BY+yJwkTtaWVVtz|$8apIG6Lb98gVyMNh9vG?gvA)27~0`<*c%`l!S^&a|)$epwb5_1nV_`Ji^ zZ-7q<*e-mIiz`uB&B?W!$Z6Z#9O!lRxM-j?e~^*GwEb3EMBKE2l=xyw;@8Y@b=fYH z$hDWu4{WO-p$(JJQl!iL3B> zd!i(r6gOvJ5-CidW?@dDlIhe82mcCg@wIu|E?bnNCOTfC;gvo*)zx5l?AKQ2N6#M^ zeYLvpe+Wy#i(>CB!`?O=tkFG(5#8wRcnD6#$Iq_wZq}EYD^CAI?~SrHjr%4_N>9mJ{eP~NO46v3Je}o8t)AX{ zF;UT}j?0vxRob?EuPI<$h4c4%azemA7fZDn1Bn^z2M!2uxjFw__wSDDX&Z9>o z)JI9ooSfB>pX0!MfEhx+Kgvnih9keGhEIsyrCTx8Cey6G4O7$G8j@|yG8poh*m@TD zV$RQae*O)Z{uPJqKKSnaURZjduYE{3&-sq~n|yGKjg3_I4H_`tHQrEDXc@%T99lw`)sEsqpq=cgwJCOaHS z{r05(!1WT-ne7o9R~=W~Xau)qw@PY=9wiHX5V~Q*2IEz?X_&foK3O2iC@WKb&Hv_7 z?qr!eyu6(~%PZ4Q(O%3n<&Lb6PtfHXH@FryQv`bJ1zyu?Gg7d4($A#jXV{uO?PE6{ zsxUtWgK^k!Y~8j^wdJ=7L4Q*90pp2lZmFCELfLY%p976zmo8l*``#8@!C=(ljE)ZC z6}bD<`}A*MAKtEwn8lM!OiUD=x_5@}ka)1T&_CH2^^#xkxNAW^r_+i;l=8fOXg`y| z9r;@i<07A0wLAJnT=)Ii(6HsguMXxhr;aGabK|-h>ptbHbW|w|U9-0ru$v##n5~cT z=hchM_(g@e=XiN@ifpW@zNx5KewuwPKv-afnMuq|+lstao9kDKmK1ye6Prh0zj-5b z_g<5};_cLa!{icA`l!&*{4l{2C$^Y9^GDYj9mQrSh-U^GT`-0SPJ<$-)v~7yU+&GU zudTZU&655NPbwX^6Kb!G zv$IlFRn^wlCn&mKdq`Hsk9e6Me;#W+yD=d8Q?l{r=x69RmAQX8D<0ir!M{hx1)HqK zn<_A}kD5z+7cA4_+m)lLOTSSHe+Uir4jj=38OX=4@y|!zJ-Ff2`(VOj9a;puyMe4Q zYIY6ic|=4+KBtXCqV0Eo`8Y7`cy9DGNeQjI7H4$&y|QK|+0Fs` zr;K${78d7>SgeC)hwCyhyV@T3nx;F?yGH zO*w?G8`6Qg;fC;<09m?WtL=*cUsm{+Xk7QpOvBimkOspf#D{l)L0~mS!R7vyg^kU! zXeafnmQU++Z{FNB9TGI&H1cWS=590xD_U1QnPEKhUS?Y~nO<_8ajAwMht8C`=ei+y zC7STi;R?HTF`aPVzI|jrGmMnQJZMT2Yi>JE$CN0M9-z54{&%&Fke{;6MzJvOJmIx< z=({rNpBXniV15Zx+Q_WuN39a=W8V7u1hsZq^o*Pv3@nBCeWJ08bkB|RAm7Qu|E}!Y zh#!~qGvv?)`8;2nSwO%oJUpM+m@r#R>d8|M^42?WU>}F>j5abbCG7k(o9<(>lQWN9 zo;)FgmwZOdcslZi2cz%K-FPS9k2$v2^5pyB4B-b{45msIlWHaRM$}+bZ7BL{4iW26 zsL?ts&(;@Fth}~8Tgd#BOsI|W7A&LUnNA0>=gJDeADx;=Jo4cDFlzqKdK4+#e*1#K zlh2=d*m9OR>igA7JSH)hD0!e;3ejeCs9Brq)jQuG&%Bv%kQ`$XpmWLZxTjF7qQ91y z-Y51pxZ!rGHdlJ~TDn}WK5u`Z9h(oyzkF#thjQ6yarIq!tW0o-UqJJNOcBv@20XRC zk4BMhf{dM$uvr><5{Bb_McOflS>}daS%K5zqGmn~2KK~Po zpFN|Bc5d1RPr@%VUBcwJu(+nGoO2-LtvfNMHWIry*42>I&Be`q=ETY8*p%kq zE%cSNU#nMz9+?|yyu4Vr^Foy$=-V`Tng7kPHYxNr_`ULZ=s}0T&F9WVn1k#i7J-Ao>FST4;-*o zG6;u}AVvGwcthJLtR4d)E2H}iB*AGG!EQU#h5fQ;76MCuFDy=t`>nNB>0CSh((Of0 zK3G*;3f0=`k>;k%%A~)S5ZKCRwVM9<`Eb>G?R)jp*$~0jHx8P=V+}YjBY&&(@yym8 zSE(;y)5yoY&26uupxWPQ%tH{_LPAj)F1EN?eeg)I%no{Z)rF7e@}NEr6M>nD%a2`M zr#-1wi5X4*>+||=i@t9j`$eZ9oP7PJ&rOi|%0x=usNyy@rIf5swPfe zoLk=6T2fK{w`65Yp3c%jnclxhYxGt4&{vCcl`}sR^0ao_fu7p1X;W6(>_F9eVPWA< zr(!CtD^2@EN(v`Bm?(GC94MY9RcHYRZj-$Fcllh1A{!qJw+JZTzaO7$1HzvPXL>MU)Gw4p`lP zp6z4I?lqr1H%$cOpZS;NSPndLkzk$~eTgHXTJ&Yp+RY*~Q3qZ`lLXnk@IjME_-Jl8czfo9NxX!pL@Z~{%N0xM5T2$Ugt)xl}>|xUQ=M^NivF1R-s3m3= zU&XVG=?daWl8cpNIo=+Zje%&hW;Qmwd5$CXfmW+FGefm6F?78yPO0Qqg0IRpisJfu zs_SohQ^^1QIo4}bqY@y>i*V0z!QL5U|Lp$gb>_38tOx_6pt zBeS!w{TRc(EFWB&8=d}=TU|9~&vIb96k1^2XoZ7chn~dKyD1}c`J$r`HZ?>4TK5wt zgahL&tMR9ebdPFvH3nZr#NNw%5hm^tIFt2j7IPXN=KoYh5f&$|V3FoNq)UtW$%)f9 zG_WE6yxKmj)7=i?p4`NcUYrN1)u*|yN)!1}cTh&#oOVKN?969Ng(ahtt3N|88)Rjq z&pDk!g#Ud%ry;|N9Vc%^vHijVRnRK}Lsm|>S5zN!H;BU$8__O}X=(mfR+^rCMxB{p zmv0Z__v339R{gJD`F9C!h{<~_OpW<>SDTz>|7DyovB zeoEJnYGI7#yy@M)*L~#3@u-u_zjVej=Z`Z}++c?6hDfAVnmKvsJY+&n{QGTPN0ri@ z;iS7;2$>0>!!JQE%)KN+b~?ySMQY16@8zukaLMsE{0A$;S-$V0^W(FMCp%TsKZ zrJow-KcTYa-$~pE-X|%cn;JB>NB{d#jvQ&L(}dT^Hc$d)7Un(cQatT|l$^N#J_g zn+@)oa0`VH2~_*~dAroSGix?LQh#-2j^?!2q;eT%EgU=WCEfW=nQZD{ONuD;n}T*T zJrkV;U?&2(Dv=1jetlR(R9r?@;re8!Dkf)Q2ago$i~h4fdT!hzPunQ$FhNeXZEAX< z)yT2ma-^==kO@aJSw@R_N=YVGB3hc<#MJ!c3PNLgs~HCOa=x{y5D2#GYos{+KG>b4 zRUfY;V7w-E*8kDj&6|DBo^+XUbGsX4$K7V6wRQV;HKfcpgtRzdsPbiM>a=?N{n6c8 zTr~b?%{Bq#EL7*nq;JkM5}pomkPI{XdtJGkk&12%s1SpX@m6I1pFV9v@w3IYc)n0G z#b%$RBmo~;&(E-ko=bnYJG{)V;bq0F%KPm)BJqrLTVA^sH0TTpgE@DHiAIGaqKnm z%y=wkE!U@*>cD}i8OGobiHTl7n`M{s*2Xo6&Z5Mc2fsIOP)UdxcANS4IqtYcKD!UD z$RA^))vx?m+eQpQjYtiDts7IzS_k-ONy*B3X0mSBC|xf48r|FPnKF^P7#XF!PHu@Q zx_0p*xgJMKLy8tjrzGQC2y(bc$&ljfYrl`LEY7R_Nc{-5&xJ-|r`_C0r_U2cwUtUi zT6ZzD+<$|t7RqQ$etlJ*Ae#bb21om)I544G(b&m9n3GY9_Ei(UAoci4eJf?HsRiIg zV_E%dpJEJ_m)7pj4V0;zF^0qhBJqWi?M_zvUBbe`u9B`CxB0#cH6@JA-s3Z%V)A+8 z-xzOkPO5*t8cF8I>Zr3&4t`_$h9eY8p$99$k`hj{Z`MAyiQdpJKiN%5$J0^OXUxMR zt#~8DuyqT!|LqI={|S7&Wz;!A7i6gp9{f5t+I;X8$A++~XTTO+d^V>zELp-qqg9ob zhV~@iZ4oRT_nq!DBUL`AvL4+yuB>J%H*|)p=Feb4Ds%t7WYYxKp2cIS zr*q>L9*c{31qPM}zU(KIGdC4v3hF8p&@ropsYT1nRKg{YRE-8gl;IuIrzD|rbC&|Q zQD|(c+jaIlH$r5EH~PkOls!?YNL**Reb-Xt-ruO$B}((q zc3W<)BdSi{=RU{0f1W2t(F7M7P>kIzCuLexM=dO%gKv%}O~?C}yw;IX7;)-}_6FM# zyjb8vcXCzv)`Un>y5MA#59QY$vt!eRp1i#>bM zuw^=|26Ni>!dMeM<=>s+=sw*XZy`aBJZhmgfuZ{gb^r8W)JrKl5jBNzE97(GJLs>i zKD1x`T~m!LgbdGcVp>_i_8xDbgk*;EyPxMDVi>GkwDm&PrG3O}o7%5!v@*59|Hr*L&C3SpbG3?!e7ku6-EB zb9Kr~9iQP!kYD|4{ZV4wqI<-5;O#+BzT>)5H*PSaK8P)k)vV{5ot!*;_N@2h-eR-W za_aKHb3RZ4lXnc)+qe|l&FJ5=J;Z*#zFST_uYDYrOy75&Z@qGD(Y#PB6aKYqNRDD8bbGqV*@iX-oSYv@X_N1YI(b8IXN;o|VtM6EH~ ziv1^-L;Ik4vStO1=Wn;?)a9AhY`BI7eeP2pvY4uHoQo^9V9F>C$tt#DQlmaY3BoeJ zU`RYl3FF#YSvbY=V4M-@o96-B|GE4_sK|c-`g?0NdX6VZGC9L)WTuy}*By^=N}4F} zeCxPsL%1@gcIw~|&6D@(l~>o(vsXBmZrWOm$`SSE1Qy#t@8RKLt5+#al`3bvg1z&- zyO??`9^P_@a}XkPeMv#+4}mq zwa^EYXab$HW%gpp zJ+-$voqprzH{C~TG`0Asp43p;gqD^sv&8`d3roUe#(2>5H0@QGQ~+$n+;e!$gyq<= ztb%yX6FR#fGE$G9TOFvbhKZ@@l`C6-D0!jt{P5w!i1fCF5s?uf-Q^~l)@5LItBZ(e zMGQ+zOFyd8W=DeLZ4?|*!Uec8|BMeK7&)}N$n`gTPp}_VEMb^wa)Lq*{srt zG=8L`!rR_KP<#rr?vX7#gMcNwn-sn`yFw~Js5P!tn~THbS2#tsq^;N{>>Er3rWj7) zj8o1C#)*t-y$EW~k1;WNmQ1l?;xe5TgT~5K=Z+ltmi9na>&Jp-_$+UK@NgZ&zI}!0 z<0KYAF|KRWq8?3&`|9H5%dWHMhIf7Z=e~WP_v-7keDCG8i$J6Fxz#u}Rv$l1?mW5o z*v~L6sn`SCfi=>x2n_J`pU+#`iD%c-J6fchro!QW5atXZqoATK>ZUPxE*xavq>3Qv z&!Mr6dM_uGI3wRn2{rqSn|YUQVNjOKU6f~Tbmv};j5Z5eMj0g_mP#hdvGk~GaRT{( z6r4Dhz+*A78A&lHZaLpN#k9Iq_RD-_c91RQzX2@i z_Jz?4Ok(amS;Gm_+QL>p*2E@y8Nc_>=dA<{Pmi_Q9pu#9LG5!at4UY?oc(HJzkN%& z7}r1d>6>B3w4d;bKdmFoh>AVcE-h}54H?g!HcY8EjHyx+BN`I=bV(=2M=c^lNEsR$ zny~+=o0+~k2B&ye^wRrnXUpc@O6gp(Q=y>Eqr^{8;dWJ3a@-mu!h)YI@CopsGdW_s62-wz2g zt#{s-z-sJ%$@7KVhOZb75zZ73Qti(FN@fBj`+sJd^&65ZDrPO&3^7HfG{~yGlr-k# z{Nja2YgJAR4h{6P@1oiBqDVCqT8knH?IxObYCN^w-n;P}Q7PcLZ5jKr#I`#9!$~e@ zNH3w!G9BjGhxzzuT&gaVR_#g1Q_!Z#p1H;WYr#bgQH_|W=!|o@oLEs9 zHa2Xgs7Oh6%7cFX?lrAAY%LE4!J$#E7QhbmH5PwEyf@<>gCj?ySow}UO`JI6Nmz{$ zu1^vYJHc4YUef%#8jc*Hzsz*AH+6Qn-Vg2DXE$%(e)8l=pu2mhsY{_tgVRDsnyj*( zWeW4(U%cBpMbwY=JvTSEN=lSCZ<& zwm%1tD1LZwgQV+T6e$>efl~HkM!i~0lFk2BSf2NW*8C6)%j>D+DYm5N9>h-PB58B& z*-tNu^wKiBwRwIz>dJu=&5_7uU?Ym8klO zy}^;lRYD-bfbs%-Ipm&)$*zSRlll9_Nqo{wM z&V2$4xm2$CLG8oy@%@AvzSRSx3}B~r`B~#g#E4`&1XIu5UN9f$FKPbx%v>IUU(t3! z1K^wLwrx}YWi4Gt!OmPttGx#OflQRtwB;%KZ?ItpP=l`dr$wrh_)eud4OvBxf=(iZ z!0-C|qFS)!e;8l6kFFd|9widz*PeyvUxfrQ`%eGS8Hx8!YpcNOh|Wl~&+Bss3|r@| zt~_&dQ-{G6U=N=;P6Rn<5ReNP*%@tgHt8zmS^c1Yr726CdEMlc8!wW)yq(H2dlbWBjzZJ42C8e+a2S*pBGH)?DK7 zzwt-Hsg#^ruq_%eL3C_1vz?u#>&#|?GxfJCEn*lhynE-)WXclb#ED(7hMGjeeGU0s zJ&_~YCr_veDb0LT7}+nYl#j`oN@q8@kV8pQtJ=A+z@B)XowPq7kmE5yZ7q<5O72X@ z6AkakelS^r_<6KP*`wLcaE0B2U+ zCbf@m?LO|-53|&g_V)Juc9Ri)iMqX?svTNPpHjO|kPM6e)dGn1DOv5r>Ss|-4+MB0 zy!db2SZI?bPuuUdiRrX2YySt{6!;@XpdeV_3G?P3&+;jJ_}o5gK*o1@{-T>f4T}b%~I9 z*mEl7D9js@&5XB)K!fH&{AqKrUH>yjoQ}*j@6JtqPn4~l=6wA6i@9LBzco^I8S_{_ zSe=HK(wnI%(^IEUq4Ipt`{GSS$iQQ#FB4X zLWg{ZF%RLpUR^Aq9#_eX);DyRdXBLk*iN{FpG&6+lspdkI?ICYRx* z9ALk9L(-B$GRg<-#+WC;#BJ0xQe}jjMwG?f!^34-FNM|cTTziBOCmCL9%=jV3X($Q z7q~@glKd;0&glU)<)7X9H>6JGM6J_3jZzyh_HbS7Q9&kppVAurmgl>}X}R@b8kV`@ z<8+A8d3F8b`nA(9EQj0ZokI(rs;1q8q~*bPuYF`)UGKI<7r6!~)26awD^c?svfxM^ zP3%(A*JptxSI=0fflLVPdBbqP@^Ntk0k_hD*RuxG;{GFX!zX#K?vjmDH>cwK1aAxgn1HKW>eFYW8TU%F1}?Eh|ow|PE66#zVXjfL#OfAFKc6Ve-A&z zqO2_voklJRxr;Amo>PZQm8+EXu`-lM?OSu4`{{Cgl!>`;#|5zI=!-HRuH#x~F_8EG zO@f{9G4*y_`deDiC?h& z@Lu=K!Iq}WmoNKs7@T4f_c(Nlj|MI78Qtw$H^1+)ju3Bt9po?-WH93#dOnO4JL zAHIdfv5wD+jA0$V=ni&x^M*TbEY4cW)RY4>N+-gq?wr-7zcJPEEoy6*50^zpn$li= zME602|H(F?TnW9Sxu}M)Ke(D*i&RZk6zxC1ZD=@%c>WBB;!r{!TtJ+8sYplhKL|!l zK1ZuXj%(d`cSQ+JW_3mbUaMsFk+<9p6s6KC@7I6&jG}?TZdn!|6p%rfHi4 zTwp|FmS)hBSfz0CZ&CM$|tcwvzdbV)TtNry!=f;X3%zEj}bJylG5;tmvIk1>Yh3Pb(E!CNIUmo zrXa+X)#-6rxs@RAl*_J>so86g&|wG_Y_um2n*1L9xOzNwcIDnD77Ppf44`M14`>#*mL49JiX4Ed?=xq1{~wY z!1;7$#=K3hh~@=mYe8i0!)3h-V@LN&*PCvAD|qL-<@cDT5I*{0`kNOj%F38PcO$h@hl#0S$*WDrZ3;7H zSH{}&JRj$7-EsZ;Q9X;u<|L03WYO<(`t1HKQGhYymW9|>hs&Q zyg`z__GyoCnjCZ=^E86R(?0rBs;JJ-4u9LeWwmaTIQl#Sg}dz+XUF?>`Ijq-vGH6Q z(^7O~4kOhb3s!vP?u_}vw(!#aJfnXK{hW!MnMA+8SB@$bL8cf8~U~( z_%VPuKEd8&yW8vLvrUVxLAPSoUl{?5j0@G8_kr~@hZ?n8_OsJtB6D7&(~#~kv^&NQ z2mblE-i!y_F9`0GmzO7s2*ZtB+NVwkO=oC*9`$G@=F`5ln^Z*fzj*QD?}Y_0!-NHo z(qvJQL{Zh4N$bLL3Q1|y&T?E65N(H(XkGO=WV0|}r%#`u4Ah$VVYphBM{$u*TN!= z#d`J}_xY5;JK{K}IwGjnN~yrG{74K1UoN8{b9o_2ZKS0$*HLe5Opy3q)A=6T88dX} z9r&_Hv#_u+9wUp3jTqN<66CP#I3T|E3{QYPyAB+9+G-f}C3ZP=Y4dl*oOfSZ6rohP z3ZqWnPp8rinkBWhugH+k@{9JTe^GY6b6Pe@OG;)9qJ-OY!j&+ZPLzwQsjojD5M$07 z!g?Q-&-;H!JYpHJ6Lb`i4TfQ(;6$^2$p#zSe#d6;oi?fTu!sQ9o6bl2OLIE9&eXp8 z_U#fRbP8@Kp}TR~R*2x)0P*`sOi()OpgIjeN)CJCT5xieUHLB!)UhLB3cN`OuQxMt$h{Mfj z-G_{MzTXQfRWQo!EgJcIT!@69KEo4K8H#Pw8XVA^#+?F@$@?|uRrKA_XSa@xn)le1 z>vQkjzyAqup&On8ghhBv%{utDz;gh)seSp}a%}A26*7TpoM89O&3F8%&HqT6em#m; zTu+B6y`74Uu1=%=0vgM;Y6hx)FY0>524Yg?8?;SW_Kculk}3jI?9Gkx75)-ckHsI` z@$dHoyUM|0@%H~BUDKUuc2k$at9)X99$YE0ynn58auOz71mxtXPQ5RlXJ%!^H4?Y> z`^moy?_V|scW07&|4kAH0lh$q(I$z8*?(R=n?r}$*nVyV)pZ8lAsNJSOhRuQ`YZu- z1_f95%HAjcibu@9(sV?a8T^fpm)8ZPnqc(Ie|<)-bxbl?1a%W4HysO$`Yg0x4Z3`1 z75+XFUKt$C7jLQ@^1JUSpMr@ywA+Ohzb8jr=jT1Wo7V?X`>fWO;-1aN*4@0L!K*`l zj+@)p)oFDLMCfQe?(FU^fMVr_@VLP0?-|CEr&&kKYyKnSP(bhJkky*PKpeH1$-{;E zkxpG?@n5E{5e5W+4{l-0kM0u<4+0lC-{!=A^0F(^vBobtdzr*M^d|!`3&LH+?9AF? z|8-RwTxy?^cLt_3QNe&rrkXPuH z5+XrsN(&&27HggIRB!%ze_(s``aOFGeZ0Ox5+#qJ)-i(I+y|T=x@`J|I@lrq@8y{K zV&`++xqF-J=g*%Vb;009WFjRG>lp6=`%4C}r!GOMWNF;VIVZj{ECI?Cw#*r62mp5< zJh+96b$23!FbBS5y}wiR{bY3{$9z|&x)G_b*J*_jf!aSslVkdkJR!4!{MO{96zNL; zkC=omh$xPkSwt!{`$!3tX3A6^MoECJpo8ojBBn1%9XnYLyi^dz>5O?BreifHku>fE z3YFjapl@5Bq1Tzwc)cTb#{@#DcU@37Nc0uK$e8Eop3ux z{5Tgg$VvhE6hPUv~jl3+dFIu8f& z!(3di0jwgZa0|+K#}`5nXDvXG`%Ckqo8RT$_`KL;15R|_#Ij<-5Zv-Y+957Nai`6DKOK{0o3pzL$|5cnng>1iBF7&sn=leN3Aso)Vt$)U&kaQHC(F zAj#v|R-?s$=5|we>S72iGbJ_JW5wlHW_3MtCAk+zC@EMyxt5+ z23fHR8EtAi>u@-conbjw8`r9-m(}-qvYW4`>4?_Lug(|h+ZCZ4L7brm2a}>-Douvm z2a@}F%@=>~^e=L*b!q#FGpl4f)jA1LpEifZGcdIzuy3cOY30%~vyfuO{rg41H6ud+ zgIlC>W)EXKSL=Lp^I*EV~dPGVL9YRb0*5k~3u5*5z^L@X* z>->1<$8g!;$$s`;d#!uj>%K>~-ruQ_q=pv9!UVSami^p8;Kv0B4V^Su;H~p^g@JZ@ zR#?cEjC%d#XtdU?e?_^;^q-#Rp8;M8OjSW*B5M%xu%$DX%ZgO{GBZODFIMyWAid$c zF$dg63(?$u)!K#4UxtTsC_YcXSHq*UGu^4UXT!&_-I3{SZ=k>U2OywO_-Aai@ZcCq zZ&V_uc~Z)8C6J*)`V>v3^6yj*1OGGG$&d!Ql-Y#~JIa|@ePYPC6fjV~|3i}Tqi&y- zwKa@n2_Y@MmGH@zQEAF%i9$plF5 z+C{PG{PLwu-|MmqKe|P6*R4Sumj=qG*=wo>Xx3ukJ;*UN;GiPa`=ZVuP)OD&s0m(m z>fTK;gKYeFc&UgpE%3~dP3%w)l>hbX*FS*?r%364V$Dh8kLy2m{JeSRO~^RQ#>M$t zlOA`U+a-h<+|26!=Im84y)7u zWqi_XkIAi@Hw}1qe1?+XbT3_*=%~ucfBtpWgzjz|uC!{aOjePGL|&m?)Ey34$ha|f<^^`6;hVDMIj zaMXFXOWlLTuk}|8A0{W8+S|(lA)9kV9wfOZ7pH=%JmRuJHfQj{tR7$r{Q;cl{;XC~ ze8Q?j0o{knIWEpFC(Zns8^-%0GP5>IZ)JCBPgS!~o=}_S1LQLuMtXDc^%YI$a-8bg zUGw-tKu@FO^dsI4fg@gi!O}O#B=rw~+I#wnYaT!SC%p?;0{}z#)0}rJ>|0VOvyLgS zjzCTekln*-S2V2cVNwwvT%m_1*E?2vflY9G4+O)_`CMm`yRH!H`gnY~z32BlRZ?1cQe`*Z5Va z*>)HiY=o9LL)p5NCmk8E7Lc0zJG5di#@+pkfR{jef&-Po@7#(Dy_(N6N(8XmLDs_z z>GQ~oxO)(23zV)SGB@o3Ss5VfO2PiC#_Ip;lpw5t-$20$X0=gkh#H1)IMY%lWrIdW z03YngKYA8=$r?niOfie*22C@-6M;}UOd;|lQ4rEU;ftr)-$OaH(n^uXbcJt!cvv(1 zducY5O}=@89l%3fY+wViv~`R(HsSN5{7Mq?S*R}v(6Es&M(Be4@`_LZO1(UBZ z7O)uvwh(j}berB=O!L3*a?^gvn~zk3L667U_?>WjBKsUzg~h-Pha|?kkW47L19`i; z^QV(=nqJ!G$?Bd(xZgACwpJOrkyG26AFIQ(n&dnO#&0e+JiLqor>)lN=qZ{7bShx23H_SeEV-OOY6)(KN(J(`R{Ab{gc8%f*yC~KXrOW6e~R?O5p-b z)epY9eZu@)*vcWG!;Un>e6d^?341>*ebA9kOVuy5HPp#oNQh0}3nG#Kl?tg7b3jem z1!{W$AbqmuZ^cw8k@^jJ=$-H=?b>kT=Ghj;!Z43d_Lo?YLg=)en$kq#z{tE0-!x%W^Pl`uMZ;+$ZP4*|&o2-N_`@ zHW-tH{sO@~;PeJ0X3DDSO}06mI`sn#l~9fOk{mJy07$un@_>y>1nN`}E_Yke5_CtQ zAOJ{Y!->_9&On0VsjUq^z-P*M=zzKs)7l=z*c1K(3bd0E&4q_DR ze>en4Clh;QixbH~PqcSjx#Fu}CI_G-MhXqw=rvA+xxH|tUo#ld9JiGE zlnVb@4rdr_O^;ZX|BJPqZL;>9dpVpDgfUP+Z&OznjL$i#yNsQ#T@grL^%N@~bASW@ z`8bd}-CSnknE5ZcAIf=GC{VkhZcA-14L!$f{2_b(9Z>R3=nbzK^(1RY!deI%knnVT z(Y1EOZv|ry1T%JSv^KT9pBhHf1(73APVnJC;pJC4(*Pne>!w)(X;$&o(F5S)sy{+F zc8u^PdB8O7wODu-R2mAYbkREyA#} z5Owu7_0uT^cN-ekAGF%mm2X!MyfpJ9yDzVg!LSG%wuFd?P&jEl)z`MH+a!Brm_B+A z9=35H&J>cH(50`9z`_qr`?gI+8t`mtJ*DfLq605DLg|D|N&@)$qpat%yu1`3o?2eG(CrxpT%j%P zN*^_h(mr3@l5jv0+Am0VXShB(_=4jXHXvYkTip=5tD!v+~=72YdjaM_?aXIyg-IJ)tzB`0Uv; zxNQJC_sRA<3o!F8sJ2E%-ux92{?q2oNT$})=l^P1gqwo`8%8#uL93N$gF-+?V044} zsS`k??(aJ8fISvmq3|QdV%#9&*#Nr<6}rrB1tF1Zda@~K|L@>htamF`SKJ$Z-(-u; zLgQ{D(Uqrm=5UaadJ00S1XTYYKXx}fZv!#yLpRnbtn}>HA&zfQ%2LzO)~@V53*2PQ zoi=f$WA{gn;ApbZ&#YnA6Z&ukbm064Z#{#@hwV6Y5#{E82*^Az1PGZ$LTj>q-t}IM zTBYTF{+4Iy>A*>cH15z5-9-QFlx7(U^-a^La{m|p0{h*qXoF*r!b9ErsoN9IL^3?* z-8=U`{XC=5;#~NOpuO{fN?q0lImAde*BU?YqSh?yBFqXT2^IdjDF{OWdQDmN;?Bu+ zNMeM7MKP$Y-V6~TreNs3ks`ET(g z#!<+6L77Juy+r-<#_G-MW+$9P_n`eQS|OohfLe*@8p3_cnP3_XP9`NH8XFauv^`4t zGFNPs7DVd^P2t-ePMQa4^OvUmKR9agcZ0OrAMk66h@};!;BjCf9E2$t>BgjA(~w~M z_{c+`^?=xn{gl!ViCjLt<<}mV;ho`CSkE{LcskKKRWbDMfz6an4r^M(4gw+Vu-Dbw zqd+R6J1qAjRg78-F%3{vl-ZtZGeS1LrOHjd0_QiNU3!ZA7}4n^3OP=|48NUgxNqMH z{nFsWAj!HddUCBP5woQ&I&e7}D2>(EZmZYxM| zP5{h?u(X37_QrB1W@!`Y1dlbmqoq`Cc328jq3xS_9kt&VvW8;|uN} z9yW&nX61bj*TCn{tirZB4ug>~bkl_VE^OhAF+yjBw)qT|Bacih9Ny--3!ThTZm5%hnA?$$Kwz-Y_eu!ejNfQNowN&C+X;|7Ku`76FQc+9gfjgjT zKxePw%`GmD-czQacJ12rlH&up46cbCFi)pa8}R5FvhKA5?0<0qa5L0s$fFsgLD=XJ zsj<3$AbWHsdaLsJ`A(A9(6v9>yCM-N7NFP+Yx?@)q1nY3R$(=MR!Wz#JV>e2wQM~4 zvoeX+01!{Gfa?pLI(v^a+x%^?5>Ul^@7Yyr_;%qhK-Ez|sd?246{?b=;$Ofuui9!+ zqXPYaXdzD>rXfe`Lqru|pIFqXGX4J16(^=b9mN51n5cm+_yeYN%Daw5NCd_VCerGv%D{ zN5`g$Cf^5rIdZCc#%7A>B#7&uP&U>#1i%=3jtx`LFbC-lEnXaq1dAeq%hFVoa8JywwvvgBI zxpyHT7>2?CUNay|&9|K_ayx_TGh2V&l!Vk`&+YVwa(} z$4z3L_z#@a?6bTH0~u5&EH_@j6wgb|SI~(@R8glBT@61?n*Sb!oE|}Vft~7UDtyvhRM&SCesCPF$kl?O&GDro*t*cfOjIv ziLf93ntx@L(a!v0iGmF1x)_N2{js77mRr@&sO!8qo8H=-ObK~Ve5u4BNJYS5@`Wb9@p>X?Z4`Dcr8;Sf0<^^P{uB!W&l0;rBJM|X z8p*8+f=F~j+CY_>N2~p-LCc!`q-OS!c6C=rYmD`G>(*rpE*ye_)JO0^XZ`_or7nYA z?p2{;GQX5&NTOUsp->lXY3LSB>-VvHE%~2qt3$5A$dBKb_j7mMQb!4~mzVf<7q1S&~kIxA6zbQea*86x?6-GqABx!)9brIGzoq#>RMeP0QxsGy$aQLDh(yfRU@B)|l3ArT`lvX7-QFM2 zVa81tuNaf;En*E8?%qD^8&ywp3K4}%$^IltEoU}bS{Nk)KUOEWAB#!Dk0sv4g50Wj zueFoVj=M+^At8uY&1=eKPfRu643{jrG+YOa_h!rQ$dxI8mUnzSL#~UcJ80Cgd1XA8 z(m2Z=S^#71PdS#lcwUXS41gGCnIB=8ns?B{G2!xL(vfRlE>~7n?o*)(JEwXI@y2C? z1e_>aT(KJ+y3i);j*jI9ayr`EV^!?R$Drfd0`;*{m$+Qapr(Spm>Ye1KsRvw+!&*C zw3a_(2A$RVDhgctm7h8p79|UgMFA!WT58Qe?r3K&J4Ut#GqFl)wX@FC{Xv+B+ZL?b zOz|aiWTJS2LVrgU_=bjt&JPz)GZjI&+uX&{#e6ZP>Dh-!KfYY>2>bw3R%0BOM-AezFr{o+HV3Q2qKhZ#*{3mX1J_t`+*a`%@v-LAB!{mgW?Re;D;R34 z&oISQu_~CY(FT_L<8ae>id7)a4ksd`1?6luJF%o7S=*LcD;eg`bEX@bhi zw_Ia=y>^)RQUn~K0A@mOcWwTGMHQzhln3+_ zI~24;zfbj51-CP2q}oB+Dke_J{4~}f=Ufc% zS%8kKU#0eh{$5d9R<^}M->K?3PxXDp&5z)3y2o;f>uDSQ$-ybtgwTyf_ zxDW^I&xHgQHk0!qUV%IHt0%6}>rZ1qm&+#ue|3jlX=dALtm=ksC26)T=PKZi+6mV*>(%QiFelpuggN z*yzru6t5eV*M=hmsT8~lB+kVSKcG;oHdt{gr+o$*s53|ZmwvqnPih=h!it$Oj0Ng* zkLp^~b?7l5HZVMq5B=>u7hElq{B^!g#%C;;z*oqGTe!?r0`=JdE|+vXv)agI;ufHjA09lyV zo?D*4!lF<=|M=g0ef&=1s;0I5c7<&5cX#m zUwRkOqq+`t-TwlWfCs%Z7pxbH1_!n!NcY`MWGaS0yfmLT+6SKvY!T($1xaIH-&7~-{0TXx-_e}Si?z7ccQMc zg7uEq$zJ^_PRU}dTuf)u>W!8PJ-c72M{ZX$$$9k1*tj^PF}6ol3ibJq^r|ZUO|Yk< z(2HD6Emf5uo?_?1x6gM+%Om%?s(&~BOM*487-P^ z>rq{eLKQsL?OXT%xc2|uJNftT|Id5&-|O@5_4%J-+Q0Y5zxT(#_s4&K=l|c%$MedE z;lK)14Mxf(NMNBZcm(B*a$oHe)S{Dch+5kZxdQx`(t%#VQR6|DptY$??boBiXt4HB+lUJR#l%_zPLYC7T9Y2d9My=9FuNWbI;n?JL3g0{cWTVp5gd zrkQ!}Kqm3xF2IVAriW2qrrF%3Dq`-7I-{nD+qW?lv69Ol>lIE-3Ak}ta#Kf=SY(`c z!U5ha@X<~}%ly0VzEf@H)sR=CUK`U>Hk`?Q@xpH)kbzVMP;oXzE8sj&bX7rdXt46J zo~G+_`LZHYlrUBA>AyLW%4rppB1T|IRetImo{ESxH+DthMn;XU)#ty}D= zsaCKpi_J^lOSN1lv0rZ=cx;{-pO86B z33VJFW4LyXTai>|`OhzuT=~OY?aSA`3O!rU47JQAX!-b637@Z(9tA3GMEiuJt&!8SXn0Mb^H3a_*aDDw=InJ-sdDUQV{Pc7hn6&)bh{NBZJxWR%S2SVrZOODpS!*R@6@h1zdU$5ico|MdF}%Q( zBiD8t8XAUA*p-C*37TMj;1CSw{j!a}|M(ySGng|tD2opAZ1R9}2fndnUPMHmr$eHm zO|A2XW6gt#x`Z#s%u`+XF#Q9V91XxY&^1p5)IUI$eG-gtAGtP5ONMVhc;R7uzOto_ zO*~Rl%s%}?W7`gf&L_-=dkFv(V?tH};3&i|l`U=9xG~kA+uPe)QeX?jK_2`%vnJnA z$s+Bby*PYw2Hf&Kq)>`gF1*~OY-Q-vNoJi8{xrR0LUwNUA^jY*3MG@np~c3>DBgY3TP=(5p_Gx(5Xe} zw|AP^ocUa92r9hd#ijf$PnY6@3Rx4sr{JlGto(<2TWyL0++#D+hfnH71+*MvlK`@5 zx|aY>%0-Il>3iHgJet8xzSy&;2n;IBsv?tN3ui)rx-BJ_G{2_~_DH;0vJM8&Or*v_ zphV~imXwucfg+lmTwL_PN}>GDok{2D@jL-s7h_qvTc1QlMVbGVZE{xqop4>(r~7!U z^sCbn;~_`YsX-zvDHqT+p_I`>Kx;?hN!d#j9dFK9a!2J0t#9aGtY`l#bvQ7oB`rW? zoL|tbeeDn|T&!3uvr{swg5g&sp|HQ0ZXSAHQ<}d!lqp=syh%K?;)y0q7Q)O6vAqO3 zMhLE5G1^jA#}6|gOkR)|4yBU>4I>Hpc79-XnEmXTbNj;6H*XLqR^9b_0gNcCBG4kl ztw+tH&^LhpBZd#yAucQXuiv*&0 z>pVkh#*1kYbH)?6&@AS<@c@TOZsm?;^vY3?bxnnSy?tP()s_j1SRsFjHAfa)HWyz( zPRly^utUnW=iws3K+g*K=->&V>rqg9AoJ1uz)Tp%cETG#QAOPl*yh+#KV77ZhX7H0 zW$p_c&VztZSAdO`-|Xu*0S3IUj~M;%*>$f8-e-gsyl1IF{TlF^ppqB=u!_MyA~eFOfqR-mWoZK z=ElXvINMBZl`E$(7}k5ew6HIC4Hie@fFj%oc;|fKO^L$Tktsu5d(et+Y@x9&#Rg}V zh8<@^lyP=W1cw_FiZrg8JDi9n5*!KaQJ9H7gvaAS1*SPEw=1K@YkW^61XuUUxd_46 z+tFG1`6^&ZRWXrP)zRCVl&tO5BuTdr$23ON)xn#3!2bHR0a_yQmWGCKIvbuHkA(Kc zp}iYytGvCusl!pS`k|V1BaWw@zCOUsaWL7uhv7hUsI00|3V*o0_&@g1tj81($x1z} z9kJ}u4Pc9wle0f~z(08U6(?%LrVW>825T&rDgYN{a+k{eLHHeH=rLgWgn=Zarv&St zhFj{1)El#I0?Mpta)OAQO61-m3l_4Af~G1pRjxFF!)6@N|1$~-ri<46Zc2Jk+CKq^ zxu(#$fShg|J%(d)r{8lkZACf(ew__z(q z1rNr+9aQAPUz+T$-2+WDh~n7kDzON&igW`+@swC57+&dKNM{kp3znyDlPfwd$cHkt&fz1`SR&v{Au(HCAv9sa0 zf&lenn4U4~JpoNc7)1)j(V3MmKwaqB;?N3s8&%P(q9+&>3$U#7Ux^AhDtIHp;a3 z^dtf$BIrvfd=%O+T4X|C`%_breJZf0uG_+?RuF$JygPdd+&k0^#9>_pcDTlR@u?m1 z@@YF%@N=;rkWX8TV|2ehsL>M|B#7a6S>+bFbH<>_aXK_i>`Xzrl_o60$m#8JO0d8_ zUvW?Q`l%3Srb*XG98pa>L=6`K z^9@Rbu`O^?Y7JeF#zrnq>(7jw#NoVq11!6Ix*tOSQVF~e{J|nOd=i~|{2UYy=gSIC z0}$zeci0A*f~8@0k>BVAqC1#aK~Kj3Lro`{HYa+`gnBU6QjtjBPS|S#;4lmpsA3-d)+iR zRjMk=c4z;NAr(#1U3S-F{Zi^pDQAwk;K&N>sWB^E8UCx}sY5VEcZW)Cn4RenwpEJmwEg?;Vw1iKn= zelGsd(R0hqjDeh?S)sznG;W%f3UMF{?v#9;!4|u!!6x?8j<^J9FImLq*-=%Y`=xA; zF*9pDc3mAVQ2Q~mbPDv*{G|>Y9wfWq9R@N`r4-6cNC;Z-l8U7__JqA5fk0~*PPsNTrc?AVIx-3DG zMn|OWbAX1z9+JmVfmx8&sFnAJ!v3-`NS~O3eodrWH4?B!Ez!&D{t|2lWCZe`HMO3Ou9r}pw@(ZfYobDN9 z%DoK$nn)+`8(^yNbRzYc>v4EQaO+7Lso7P2PJK~BoSi?h16%RjjA) z{3UoFlzdrbWkJrnA}{ChuR~K7deNGYr@8z1n8wPw`&e-1$6$0Yt11_FLjHriw6q8N zyyZtdOn+Ncp&BXoJf(KT%TX275|BQ%B?KwBBF#?&>Ea5+ydpT9IWH<-GS_BRQMZR0 zsGaB=DuX0B&p~H#jtPsIcg5WV`nHu-7&S%Sq3#M7V^}voj*5=O59wL{LVI%!D~mSa z{H3$1Bm@aLZZ|tyq;lh{pT<}J-t{(k1l&H*TH-K8`=X4 zq1@E~aLX#!+Co*2oTb?AG z%Ip`v7P^C#n3va7_h;aPR1DS0d}D7wRP0&ovLlr|(4Xmrc2cb#d|#yGf&vNhIzLcw z&OUcwbRc-y{Gh&pK?<}(^Dd}&9UeQ$?>>5T%4-S+2U_7T{=i48#GgvE*3usLbv-`1 zZqxm1^CK5L7*JFY&MI7+QTPg(hJ&=6Tq~3xMczW*UBWPccI~~rdZUs2(K1-t3b!e( zL>-^O_a(4udGk#&yXzI;v1S%6jzDnFv#mJ*zK8EJ7A=B_ zY6~GzRS!8@u-yl$f-!B+j`x5V*0J?4aFL9guF`=*9w@1-6t>^ReO9Tu)UBEAt_mZr zAt6VQ+67qq{(T85TRO7+g{K)vy*pmWZn9Q(5+UqlQdJ^ze)v z)ZGd@UVHac27ZZIz;ec1AuY`YUTqbvn%sIEEU?v3r46<*C=BtdNu zcy(5D>tw*5i4Msc88%o3NE(ClKOrz&OMv+Xs;=0 ztS;Hxz{ij@!PySIlLjY_ z4hM7ogA>;o-Y0?>08};7rXZNj3)SPiw~$BJ#HnD4r{CDUy>+f$nH)Nwqug8n8Fo_< zcPtrtwMyTKK{LA*REo-|m4?}&`=X{^@l7->1_m3+&y48 zkuMM``M6)|{q$U#ELLGWxEKOHT} zvrqiCdOKxXV1}0SRZ5}eVBcVQu#dKP|6`9X$2izmnZpeiCSFC>5LD{|mX@6-D!O5l zJS)63xh@wzBmy2(lN{Xvh`TqafK;taJl9kj6bO$JiSl?RAKN$dPFjV;fx(?$ghC;5 z(?eYB-K0PR>Y?9gFmE?vqRf3y7oCRT$}Z2|>iy|^_T&`gGyWW`=CGFD7mbx%%lS<3^G^>TF|5%gZec ziX0Ba7eO;!D({k5BxK3vQ~)#$=r9z*34oI=EK9+(*V5et3MLmm>3C-@!a0HzIs-}x zxYk+$9g4d-v{6R;=d?JFt^%{zYTWttVTG`AU~H3+*_@DB;7x!F0{AkZ1@eXy@f(~7 zo6@URNq?i@<>hK}a&o$a$!=Y{Z4M2hwA?a|9Nkpc$&{qh+!U{DX=fK#J6H=E6BnCE z^UBu*YT0#JStTiKyi8Ne#Y`vlMri=+2x6w#0i!=`v& zszd4)34TwPed#`^xqE6nmLFla`_-y037SUcbYAuCD&IHp9-+Z2bx)h@)VW#<+vGljHZRjdqrPE*t7do5%%8d7_k zp5CPFw6OUU#tBH&5C+22r|LlY(hXbjg@b>2v?)F($y)20kA36c(CiJo`$T%8=im&Fc{VE~w)hg9ALR1t5=B{Z3@($dn#eDD)?WL<(_C2!mJ$lv$PQ~`Wa3N4r|CvbF#95HxN3L6tqS|+gd z?JDd=Go*ty^HRjwTMA)V5J8BvfVKv%^IJF7UIKa3RDy8MBJ9f+C-Jy7l}C&}l^HdM z&0JQqS0%BgdWtd4!_jEb2Y^TV{RAs>duwWHw5-c6BR~6kb1rD7`?A|J>(5ghg)scp z&k=idzZ`-G4&Y6?X03USQ6@ESG#QWmcB{Lu}9X# RU&tSr95+8!@cYG^{|9oZhJ644 literal 0 HcmV?d00001 diff --git a/pyproject.toml b/pyproject.toml index 2fd102a..0d05f2d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,7 @@ authors = [ ] 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", @@ -26,7 +27,9 @@ classifiers = [ "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] 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/tests/test_packaging.py b/tests/test_packaging.py index c132bc4..9047fdd 100644 --- a/tests/test_packaging.py +++ b/tests/test_packaging.py @@ -25,7 +25,7 @@ def test_distribution_metadata_has_one_version_authority_and_current_entry_point assert project["tool"]["setuptools"]["dynamic"]["version"] == { "attr": "juice_lyrics.__version__" } - assert __version__ == "1.4.0" + assert __version__ == "2.0.0b1" assert project["project"]["scripts"] == { "999": "juice_lyrics.cli:main", "juice-lyrics": "juice_lyrics.cli:main", @@ -42,6 +42,7 @@ def test_distribution_metadata_uses_current_license_and_bounded_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(): From 55b4b4b8cdb688abcb6884ec8fe34014a39c0d01 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Wed, 23 Sep 2026 09:52:09 +0100 Subject: [PATCH 58/62] Refresh beta verification workflow --- .github/workflows/ci.yml | 6 +++--- docs/PROJECT_STATE.md | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aab80a5..b9973c9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,15 +11,15 @@ permissions: jobs: test: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 strategy: fail-fast: false matrix: python-version: ["3.11", "3.14"] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@v7 + - uses: actions/setup-python@v7 with: python-version: ${{ matrix.python-version }} cache: pip diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index d69eaf2..ad22115 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -72,8 +72,9 @@ code and tests if a later working tree disagrees with this document. 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. - Publishing, tagging, and merging remain deliberately undone pending manual - acceptance and the new GitHub workflow result. + 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. From b3e740a2d5999c19c44fa0b91856c2da37de46b1 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Wed, 23 Sep 2026 10:25:33 +0100 Subject: [PATCH 59/62] Fix refreshed acquisition search and record beta acceptance --- docs/BETA_RELEASE_CHECKLIST.md | 72 ++++++++++++++++++++++++++++++---- docs/PROJECT_STATE.md | 10 +++++ src/juice_lyrics/cli.py | 8 +++- tests/test_acquisition.py | 36 ++++++++++++++++- 4 files changed, 116 insertions(+), 10 deletions(-) diff --git a/docs/BETA_RELEASE_CHECKLIST.md b/docs/BETA_RELEASE_CHECKLIST.md index cf51f7a..445cbe4 100644 --- a/docs/BETA_RELEASE_CHECKLIST.md +++ b/docs/BETA_RELEASE_CHECKLIST.md @@ -5,10 +5,66 @@ 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. +## 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`. -- [ ] `juice_lyrics.__version__`, `999 --version`, wheel metadata, and the +- [x] `juice_lyrics.__version__`, `999 --version`, wheel metadata, and the changelog all say `2.0.0b1`. - [ ] The changelog heading has the actual release date instead of `Unreleased`. @@ -16,9 +72,9 @@ or merging. `main` remains the stable v1.4 baseline until the beta is accepted. 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. -- [ ] The synthetic screenshot contains no username, home path, token, state, +- [x] The synthetic screenshot contains no username, home path, token, state, song list, or real-library data. -- [ ] Distribution contents contain the license, README, metadata, and every +- [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 @@ -32,15 +88,15 @@ git diff --check python -m build ``` -- [ ] Full test suite passes with only understood environment skips. -- [ ] Wheel and sdist install independently in new environments outside the +- [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`. -- [ ] `999 --help`, `999 --version`, `juice-lyrics --version`, and +- [x] `999 --help`, `999 --version`, `juice-lyrics --version`, and `999 doctor` work from both artifacts. - [ ] TUI launches and exits from both artifacts. -- [ ] Bash/Zsh/Fish completion generation succeeds; syntax is checked where +- [x] Bash/Zsh/Fish completion generation succeeds; syntax is checked where the shell is installed. -- [ ] Force-reinstall, uninstall, and reinstall leave the commands and imports +- [x] Force-reinstall, uninstall, and reinstall leave the commands and imports in the expected state without touching application XDG data. - [ ] The GitHub `Verify` workflow passes on supported oldest/current Python versions for the release pull request. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index ad22115..e402995 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -75,6 +75,16 @@ code and tests if a later working tree disagrees with this document. 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`. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. diff --git a/src/juice_lyrics/cli.py b/src/juice_lyrics/cli.py index 31bab48..83a1048 100644 --- a/src/juice_lyrics/cli.py +++ b/src/juice_lyrics/cli.py @@ -1287,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.") diff --git a/tests/test_acquisition.py b/tests/test_acquisition.py index d24ae77..22711e2 100644 --- a/tests/test_acquisition.py +++ b/tests/test_acquisition.py @@ -496,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 @@ -1268,4 +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 "") - From db1ef2c5b4f7235eb912ec2fa1c2fe633a910046 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Thu, 24 Sep 2026 10:55:03 +0100 Subject: [PATCH 60/62] Clarify library health and offline sync --- docs/BETA_RELEASE_CHECKLIST.md | 49 ++++++++++++++++ docs/PROJECT_STATE.md | 27 ++++++++- docs/UI_DESIGN.md | 4 +- docs/USER_FLOWS.md | 11 ++-- docs/USER_GUIDE.md | 5 +- src/juice_lyrics/services/library_identity.py | 33 ++++++++++- .../services/library_index_sync.py | 18 ++++-- src/juice_lyrics/services/library_issues.py | 13 ++++- src/juice_lyrics/tui/help.py | 6 +- src/juice_lyrics/tui/screens/library.py | 57 ++++++++++++------- tests/test_library_index_sync.py | 51 ++++++++++++++++- tests/test_library_issues.py | 25 ++++++++ tests/test_tui_library.py | 21 ++++--- 13 files changed, 268 insertions(+), 52 deletions(-) diff --git a/docs/BETA_RELEASE_CHECKLIST.md b/docs/BETA_RELEASE_CHECKLIST.md index 445cbe4..31d9e1b 100644 --- a/docs/BETA_RELEASE_CHECKLIST.md +++ b/docs/BETA_RELEASE_CHECKLIST.md @@ -5,6 +5,55 @@ 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. +## 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, diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index e402995..ef50b13 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -85,6 +85,27 @@ code and tests if a later working tree disagrees with this document. 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. Test totals are checkpoint evidence, not a permanent promise. Run the current suite before reporting a later code milestone. @@ -148,11 +169,13 @@ failure. ## Library health and maintenance -Catalogue identity and local lyric health are separate axes. A healthy track +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, healthy tracks, and issue rows. `a` +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 diff --git a/docs/UI_DESIGN.md b/docs/UI_DESIGN.md index db8158a..9f63bc3 100644 --- a/docs/UI_DESIGN.md +++ b/docs/UI_DESIGN.md @@ -267,8 +267,8 @@ Example: Library -315 tracks · 300 healthy · 15 issues -Fully covered 287 · Catalogue unknown 6 · MP3 170 · FLAC 85 · M4A 60 +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 ✓ diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index e6b6d00..65643ad 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -415,11 +415,11 @@ Summary: Library synced 181 tracks -4 new -1 changed +4 new recorded +1 changed refreshed 2 removed 37 newly matched -15 need attention +15 catalogue unknown --- @@ -428,7 +428,10 @@ 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. +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. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index cffe124..f446366 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -114,7 +114,8 @@ 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 healthy; if a catalogue-backed action later observes that its +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. @@ -139,7 +140,7 @@ 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 healthy track may still show **Catalogue match: +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. diff --git a/src/juice_lyrics/services/library_identity.py b/src/juice_lyrics/services/library_identity.py index 2681ec5..7e7d0c9 100644 --- a/src/juice_lyrics/services/library_identity.py +++ b/src/juice_lyrics/services/library_identity.py @@ -3,6 +3,7 @@ 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 @@ -53,6 +54,26 @@ def _state_bytes(path: Path) -> bytes | None: 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], @@ -78,7 +99,7 @@ def backfill_catalogue_identities( errors: list[str] = [] failed_paths: list[str] = [] - for track in tracks: + for index, track in enumerate(tracks): _, existing = resolve_state_entry(files, track.relative_path, relative_paths) try: if ( @@ -128,6 +149,16 @@ def backfill_catalogue_identities( 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: diff --git a/src/juice_lyrics/services/library_index_sync.py b/src/juice_lyrics/services/library_index_sync.py index f6d455e..53d6216 100644 --- a/src/juice_lyrics/services/library_index_sync.py +++ b/src/juice_lyrics/services/library_index_sync.py @@ -42,14 +42,24 @@ class LibraryIndexSyncResult: @property def summary(self) -> str: if self.error: - return f"Library scan complete · {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): - return "Library is up to date" + 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"), (self.changed, "changed"), + (self.new, "new recorded"), (self.changed, "changed refreshed"), (self.removed, "removed"), (self.identified, "newly matched"), - (self.failed, "could not be checked"), + (self.unknown, "catalogue unknown"), + (self.failed, "catalogue checks failed"), ): if count: parts.append(f"{count} {label}") diff --git a/src/juice_lyrics/services/library_issues.py b/src/juice_lyrics/services/library_issues.py index 9f60d40..ed90e57 100644 --- a/src/juice_lyrics/services/library_issues.py +++ b/src/juice_lyrics/services/library_issues.py @@ -113,7 +113,8 @@ def _issue_for_track(track: LibraryTrack) -> LibraryIssue | None: _append_once(details, "No catalogue identity has been established safely.") if summary is None: summary = "Catalogue match unknown" - action = LibraryIssueAction.MANUAL_MATCH + if action is None: + action = LibraryIssueAction.MANUAL_MATCH metadata_problem = ( "metadata is missing" in warning @@ -144,9 +145,15 @@ def _issue_for_track(track: LibraryTrack) -> LibraryIssue | None: if track.lyric_status is LibraryLyricStatus.NONE: categories.append(LibraryIssueCategory.LYRICS) - _append_once(details, "Supported embedded lyrics are missing or could not be read.") + 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 "Embedded lyrics missing" + 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: diff --git a/src/juice_lyrics/tui/help.py b/src/juice_lyrics/tui/help.py index 37e1dd6..1af1080 100644 --- a/src/juice_lyrics/tui/help.py +++ b/src/juice_lyrics/tui/help.py @@ -20,13 +20,15 @@ ("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 Library"), + ("/", "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", "Verify library"), ("b", "Browse backups"), + ("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"), diff --git a/src/juice_lyrics/tui/screens/library.py b/src/juice_lyrics/tui/screens/library.py index 434f74b..bd40d47 100644 --- a/src/juice_lyrics/tui/screens/library.py +++ b/src/juice_lyrics/tui/screens/library.py @@ -33,6 +33,7 @@ LibraryIssue, LibraryIssueAction, LibraryIssueCategory, + LibraryIssueSeverity, get_library_health, ) from ...services.library_duplicates import ( @@ -124,7 +125,7 @@ class LibraryFilter(str, Enum): ("Synced lyrics", LibraryFilter.SYNCED.value), ("Plain lyrics", LibraryFilter.PLAIN.value), ("No lyrics", LibraryFilter.NO_LYRICS.value), - ("Needs attention", LibraryFilter.ATTENTION.value), + ("Lyrics to improve", LibraryFilter.ATTENTION.value), ) @@ -452,10 +453,10 @@ 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} healthy · {self.health.issue_count} issues" + f"{self.health.healthy_count} issue-free · {self.health.issue_count} follow-ups" ) if not issues: - self.query_one("#library-issues-list", Static).update("Library is healthy") + 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." ) @@ -1102,7 +1103,8 @@ 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 + problems} song{'s' if count + problems != 1 else ''} need attention\n\n" + 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" @@ -1472,8 +1474,9 @@ def __init__( def compose_content(self) -> Iterable[Widget]: yield Static( - "0 tracks · 0 healthy · 0 issues\n" - "Fully covered 0 · Catalogue unknown 0 · MP3 0 · FLAC 0 · M4A 0", + "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, ) @@ -1779,9 +1782,13 @@ def _apply_snapshot(self, outcome: SnapshotOutcome) -> 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.healthy_count} healthy · " - f"{health.issue_count} issues" + 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 @@ -1852,7 +1859,7 @@ def _apply_preview(self, outcome: PreviewOutcome) -> 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("Sync preview unavailable.", error=True) + self._set_status("Maintenance preview unavailable.", error=True) self._render_details() return self.preview = outcome.plan @@ -1912,9 +1919,13 @@ def _render_summary(self) -> None: 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.healthy_count} healthy · " - f"{health.issue_count} issues\nFully covered {snapshot.fully_covered_count} · " + 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')}" @@ -1953,20 +1964,26 @@ def _apply_local_filter(self, *, preferred_reference: str | None = None) -> None def _render_tracks(self) -> None: self.query_one("#library-tracks-title", Static).update( - f"Tracks · {len(self.filtered_tracks)} of {self.snapshot.total_track_count if self.snapshot else 0}" + 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 = [] - issue_references = { - issue.track.reference + issues_by_reference = { + issue.track.reference: issue for issue in get_library_health(self.snapshot).issues - } if self.snapshot is not None else set() + } if self.snapshot is not None else {} for index, track in enumerate(self.filtered_tracks): marker = ">" if index == self.selected_index else " " - attention = "!" if track.reference in issue_references 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)}" @@ -2013,7 +2030,7 @@ def _render_details(self) -> None: lines.extend(("", f"Warning {track.warning}")) if track.match_status is LibraryMatchStatus.UNMATCHED: lines.extend(("", "Automatic refresh requires a catalogue match.")) - lines.extend(("", "Sync preview", _track_preview_text(self.preview, track.path))) + 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: @@ -2536,7 +2553,7 @@ def _apply_execution(self, outcome: ExecutionOutcome) -> None: 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} still need attention" + message += f" · {remaining} could not be updated" if result.warnings: message += f" · {result.warnings[0]}" self._completion_message = (message, bool(result.failed_files)) @@ -2673,7 +2690,7 @@ def _coverage_label(track: LibraryTrack) -> str: if track.fully_covered: return "Fully covered" if track.lyric_status is LibraryLyricStatus.NONE: - return "Missing lyrics" + 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: @@ -2690,7 +2707,7 @@ def _duration(seconds: float | None) -> str: def _track_preview_text(plan: LibrarySyncPlan | None, path: Path) -> str: if plan is None: - return " Not generated. Press s for a read-only preview." + 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." diff --git a/tests/test_library_index_sync.py b/tests/test_library_index_sync.py index 5f2d274..3af03cc 100644 --- a/tests/test_library_index_sync.py +++ b/tests/test_library_index_sync.py @@ -85,7 +85,7 @@ def searcher(settings, query, refresh=False): settings, previous_snapshot=first.snapshot, state_file=state_file, dependencies=deps ) - assert second.summary == "Library is up to date" + assert second.summary == "Local library is up to date" assert counts == before saved = json.loads(state_file.read_text(encoding="utf-8")) @@ -100,7 +100,7 @@ def searcher(settings, query, refresh=False): dependencies=deps, ) - assert third.summary == "Library is up to date" + 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 @@ -192,6 +192,9 @@ def test_offline_sync_preserves_state_and_local_health(tmp_path): 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" @@ -232,7 +235,8 @@ def searcher(*args, **kwargs): second = sync_library_index(settings, previous_snapshot=first.snapshot, state_file=state_file, dependencies=deps) - assert second.unknown == 1 and second.summary == "Library is up to date" + assert second.unknown == 1 + assert second.summary == "Local library up to date · 1 catalogue unknown" assert counts == before assert path.read_bytes() == b"audio" @@ -386,3 +390,44 @@ def searcher(settings, query, refresh=False): "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 index 1f4a04a..819ea2b 100644 --- a/tests/test_library_issues.py +++ b/tests/test_library_issues.py @@ -90,6 +90,29 @@ def test_unknown_track_is_one_actionable_catalogue_issue(tmp_path): 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, @@ -141,6 +164,8 @@ def test_missing_lyrics_invalid_lrc_and_verification_failure_are_single_rows(tmp 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, diff --git a/tests/test_tui_library.py b/tests/test_tui_library.py index 96465ce..83a848c 100644 --- a/tests/test_tui_library.py +++ b/tests/test_tui_library.py @@ -383,7 +383,7 @@ async def scenario(): assert app.screen.__class__.__name__ == "LibraryIssuesDialog" assert snapshot_calls == ["snapshot"] assert searches == [] - assert "2 issues" in _text(app, "#library-issues-summary") + 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") @@ -436,21 +436,21 @@ async def scenario(): ) async with app.run_test() as pilot: screen = await _open_library(app, pilot) - assert "1 issues" in _text(app, "#library-summary") + 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 "1 healthy · 0 issues" in _text(app, "#library-summary") + 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 "0 healthy · 1 issues" in _text(app, "#library-summary") + assert "1 follow-ups · 0 errors" in _text(app, "#library-summary") await pilot.press("a") - assert "Embedded lyrics" in _text(app, "#library-issues-detail") + assert "Optional lyrics" in _text(app, "#library-issues-detail") asyncio.run(scenario()) @@ -1005,9 +1005,10 @@ async def scenario(): assert screen.__class__.__name__ == "LibraryScreen" summary = _text(app, "#library-summary") assert "3 tracks" in summary and "Catalogue unknown 1" in summary - assert "1 healthy" in summary and "2 issues" 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 @@ -1018,6 +1019,8 @@ async def scenario(): 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 @@ -1291,7 +1294,7 @@ async def scenario(): await pilot.pause() assert "Catalogue identification unavailable" in _text(app, "#library-status") assert "Fully covered 1" in _text(app, "#library-summary") - assert "1 issues" 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()) @@ -1454,7 +1457,7 @@ async def scenario(): screen = await _open_library(app, pilot) summary = _text(app, "#library-summary") assert "Fully covered 3" in summary - assert "3 healthy" in summary and "0 issues" 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") @@ -1485,7 +1488,7 @@ async def scenario(): screen = await _open_library(app, pilot) summary = _text(app, "#library-summary") assert "Fully covered 1" in summary - assert "1 issues" 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 From 82580f77a16fbc034fd6159a494fd88ffe27f7f1 Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 25 Sep 2026 16:33:03 +0100 Subject: [PATCH 61/62] Record final beta acceptance --- docs/BETA_RELEASE_CHECKLIST.md | 94 ++++++++++++++++++++++++++++++---- docs/PROJECT_STATE.md | 26 ++++++++-- 2 files changed, 106 insertions(+), 14 deletions(-) diff --git a/docs/BETA_RELEASE_CHECKLIST.md b/docs/BETA_RELEASE_CHECKLIST.md index 31d9e1b..d96cc86 100644 --- a/docs/BETA_RELEASE_CHECKLIST.md +++ b/docs/BETA_RELEASE_CHECKLIST.md @@ -5,6 +5,76 @@ 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 @@ -142,12 +212,14 @@ python -m build checkout, with no source tree on `PYTHONPATH`. - [x] `999 --help`, `999 --version`, `juice-lyrics --version`, and `999 doctor` work from both artifacts. -- [ ] TUI launches and exits 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. -- [ ] The GitHub `Verify` workflow passes on supported oldest/current Python +- [x] The GitHub `Verify` workflow passes on supported oldest/current Python versions for the release pull request. ## 3. GitHub presentation settings @@ -163,25 +235,25 @@ python -m build public; do not change visibility as a side effect of release prep. - [ ] Preview README links and the synthetic screenshot on GitHub before merge. -## 4. Manual beta acceptance +## 4. Beta acceptance Use an explicit backup and a small temporary copy of representative media before testing any mutating workflow. -- [ ] Launch, Help, navigation, Browse search/pagination/details, queue Add, +- [x] Launch, Help, navigation, Browse search/pagination/details, queue Add, Downloads, Retry, and confirmed Download queue work. -- [ ] Sync Library handles unchanged/new/changed/removed files and remains +- [x] Sync Library handles unchanged/new/changed/removed files and remains usable offline. -- [ ] Bandit identifies as `94107`; 10 Feet identifies as `94102`. -- [ ] Manual match/lock, unlock, Issues, Duplicates, and Missing Library behave +- [x] Bandit identifies as `94107`; 10 Feet identifies as `94102`. +- [x] Manual match/lock, unlock, Issues, Duplicates, and Missing Library behave as documented. -- [ ] One copied MP3, FLAC, and M4A completes metadata preview/apply with its +- [x] One copied MP3, FLAC, and M4A completes metadata preview/apply with its audio payload, artwork, lyrics, unrelated tags, sidecar, backup, and lock verified. -- [ ] Restore succeeds from a generated backup and does not delete the backup. +- [x] Restore succeeds from a generated backup and does not delete the backup. - [ ] rmpc verify works when installed; explicit setup is reviewed separately. -- [ ] `999 doctor --support-report` is manually reviewed for privacy before it - is attached to an issue. +- [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. diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index ef50b13..4eef66e 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -87,7 +87,8 @@ code and tests if a later working tree disagrees with this document. 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 + 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 @@ -106,6 +107,25 @@ code and tests if a later working tree disagrees with this document. 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. @@ -169,8 +189,8 @@ 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` +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, From 92fe555747384429161bd1370bfac4c3996aad2c Mon Sep 17 00:00:00 2001 From: NotAI-fr Date: Fri, 25 Sep 2026 16:45:28 +0100 Subject: [PATCH 62/62] Finalize 2.0.0b1 release metadata --- README.md | 19 +++++++++---------- docs/BETA_RELEASE_CHECKLIST.md | 4 ++-- docs/CHANGELOG.md | 7 +++---- 3 files changed, 14 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 07eb030..1aac6b8 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ 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. -> **Beta candidate:** `2.0.0b1` is prepared on `v2-redesign` for acceptance. +> **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. -> No release or package-registry publication has happened yet. +> 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 @@ -288,28 +288,27 @@ The tool follows XDG locations for its config, cache, state, and backups. ### Recommended pipx install ```bash -pipx install "git+https://github.com/NotAI-fr/juice-lyrics.git@v2-redesign" +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. -Until a release is published, the command above installs the current -`v2-redesign` branch into pipx without depending on the source checkout after -installation. If pipx already has an older or stale copy, replace it -deliberately: +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-redesign" +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 path while using -the development branch. Installing a locally built wheel is also supported: +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 --force /absolute/path/to/juice_wrld_lyrics-2.0.0b1-py3-none-any.whl diff --git a/docs/BETA_RELEASE_CHECKLIST.md b/docs/BETA_RELEASE_CHECKLIST.md index d96cc86..17d88eb 100644 --- a/docs/BETA_RELEASE_CHECKLIST.md +++ b/docs/BETA_RELEASE_CHECKLIST.md @@ -185,9 +185,9 @@ Remaining manual acceptance: - [ ] `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`. -- [ ] The changelog heading has the actual release date instead of +- [x] The changelog heading has the actual release date instead of `Unreleased`. -- [ ] README installation commands point to the intended immutable tag or +- [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. diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index a8410f4..616832e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -4,10 +4,9 @@ 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] - Unreleased +## [2.0.0b1] - 2026-09-25 -This is the first beta candidate for the redesigned `999` product. It is not a -published release yet. +This is the first beta release of the redesigned `999` product. ### User experience @@ -75,5 +74,5 @@ published release yet. - 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/compare/v1.4.0-backend-complete...v2-redesign +[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