Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
62 commits
Select commit Hold shift + click to select a range
a7307d7
Add v2 design and architecture decision notes
NotAI-fr Aug 25, 2026
1eaa729
Document lyrics and architecture decisions
NotAI-fr Aug 25, 2026
2a843c2
Add initial v2 design proposal
NotAI-fr Aug 25, 2026
88f3bc5
Add v2 development roadmap
NotAI-fr Aug 25, 2026
1a67909
Add v2 project continuity brief
NotAI-fr Aug 25, 2026
968559a
Add initial v2 TUI design specification
NotAI-fr Aug 25, 2026
ba3a534
Add v2 user flow specification
NotAI-fr Aug 25, 2026
5c4dd50
Add current project state document
NotAI-fr Aug 28, 2026
4be741c
Extract read-only library status service
NotAI-fr Aug 28, 2026
7e44ecb
Add typed catalogue query service
NotAI-fr Aug 28, 2026
a82aac1
Add read-only acquisition queue service
NotAI-fr Aug 28, 2026
d0d5aef
Add safe acquisition post-processing rollback
NotAI-fr Aug 29, 2026
24a709e
Support safe acquisition post-processing retries
NotAI-fr Aug 29, 2026
e5ffa41
Extract typed library sync service
NotAI-fr Aug 29, 2026
c5b165f
Add initial read-only Textual TUI shell
NotAI-fr Aug 29, 2026
7a1303e
Add responsive terminal-native Textual shell
NotAI-fr Aug 29, 2026
57d5280
Add responsive terminal-native Textual shell
NotAI-fr Aug 29, 2026
ab5e34e
Add read-only catalogue Browse screen
NotAI-fr Aug 29, 2026
d0cc2d3
Fix catalogue filters and add Browse pagination
NotAI-fr Aug 29, 2026
fecfc83
Add paginated catalogue Browse screen
NotAI-fr Aug 30, 2026
1c38e18
Add paginated catalogue Browse screen
NotAI-fr Aug 30, 2026
093fabe
Add read-only Downloads screen
NotAI-fr Aug 30, 2026
dbb85fa
Update v2 development checkpoint
NotAI-fr Aug 30, 2026
8d3a0c6
Add read-only Library screen and sync preview
NotAI-fr Aug 30, 2026
6ded0df
Add read-only Settings screen
NotAI-fr Aug 30, 2026
37bf048
Add user-facing download queue
NotAI-fr Aug 31, 2026
928f0c7
Add configurable central LRC directory
NotAI-fr Aug 31, 2026
69361d0
Add selected download retry
NotAI-fr Sep 1, 2026
0deafc8
Add batch downloads and visible keybind help
NotAI-fr Sep 1, 2026
c5697b4
Harden LRC path handling and isolate tests
NotAI-fr Sep 1, 2026
b09c186
Add Browse multi-select and batch queue addition
NotAI-fr Sep 1, 2026
f72df19
Streamline and polish TUI workflow
NotAI-fr Sep 2, 2026
7edc0ec
Add sidecar lyrics architecture and backup retention
NotAI-fr Sep 4, 2026
8b2315a
Add native FLAC library support
NotAI-fr Sep 5, 2026
d05db19
Rename app to 999 and prepare beta packaging
NotAI-fr Sep 6, 2026
04ed49c
Add TUI library management
NotAI-fr Sep 9, 2026
6367abd
Fix library lyric coverage classification
NotAI-fr Sep 9, 2026
a5de73b
Improve catalogue matching and identity rebuilding
NotAI-fr Sep 13, 2026
0941970
Polish TUI help and interactions
NotAI-fr Sep 13, 2026
d40876f
Harden library state and restore safety
NotAI-fr Sep 14, 2026
7d2d016
Improve library and dashboard performance
NotAI-fr Sep 14, 2026
47cb6a6
Harden catalogue matching for album editions
NotAI-fr Sep 14, 2026
31ebaf2
Add one-button Library Sync
NotAI-fr Sep 15, 2026
5d7fa50
Maintain repository and refresh project handoff
NotAI-fr Sep 15, 2026
8a0e723
Add manual catalogue identity locking
NotAI-fr Sep 15, 2026
d72cad8
Add Library Issues health workflow
NotAI-fr Sep 17, 2026
84096ef
Add read-only Library duplicate detection
NotAI-fr Sep 19, 2026
502117b
Add metadata repair audit and preview
NotAI-fr Sep 19, 2026
f3772cf
Add safe metadata repair foundation
NotAI-fr Sep 19, 2026
ba594f9
Add safe TUI metadata repair apply
NotAI-fr Sep 20, 2026
84ca1c6
Harden metadata repair from real-file acceptance
NotAI-fr Sep 20, 2026
c670a65
Add Missing Library catalogue view
NotAI-fr Sep 21, 2026
89b4e9d
Add read-only Doctor diagnostics
NotAI-fr Sep 21, 2026
a31f7ef
Add generated shell completion
NotAI-fr Sep 21, 2026
3d6fecb
Complete final reliability acceptance
NotAI-fr Sep 22, 2026
b02c830
Validate packaging and clean installation
NotAI-fr Sep 22, 2026
3b71f20
Prepare GitHub presentation for beta
NotAI-fr Sep 23, 2026
55b4b4b
Refresh beta verification workflow
NotAI-fr Sep 23, 2026
b3e740a
Fix refreshed acquisition search and record beta acceptance
NotAI-fr Sep 23, 2026
db1ef2c
Clarify library health and offline sync
NotAI-fr Sep 24, 2026
82580f7
Record final beta acceptance
NotAI-fr Sep 25, 2026
92fe555
Finalize 2.0.0b1 release metadata
NotAI-fr Sep 25, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Verify

"on":
push:
branches: [v2-redesign]
pull_request:
branches: [main]

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-24.04
strategy:
fail-fast: false
matrix:
python-version: ["3.11", "3.14"]

steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
with:
python-version: ${{ matrix.python-version }}
cache: pip
- name: Install project and test tools
run: python -m pip install --upgrade pip build pytest && python -m pip install -e .
- name: Run tests
run: pytest -q
- name: Compile sources
run: python -m compileall -q src
- name: Check distributable artifacts
run: python -m build
10 changes: 10 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
100 changes: 100 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# 999 agent handoff

Start with [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md). It is the canonical
current-state handoff. Use `PROJECT_CONTEXT.md` for durable product context and
the other `docs/` files for architecture, decisions, workflows, and UI detail.

## Identity and purpose

- Product and primary command: `999`
- Legacy command alias: `juice-lyrics`
- Python package: `juice_lyrics`
- Distribution: `juice-wrld-lyrics`
- XDG storage namespace: `juice-lyrics` (do not rename or duplicate it)
- Current beta candidate version: `2.0.0b1` (not yet released or tagged)
- Active development branch: `v2-redesign`
- Purpose: a Linux CLI/TUI for a local Juice WRLD library, catalogue browsing,
safe lyric maintenance, downloads, backups, and optional rmpc integration.

## Non-negotiable safety rules

- Never let automated tests touch the user's real music, config, state,
backups, queue, sidecars, or rmpc configuration.
- Tests that use application paths must isolate `HOME`, `XDG_CONFIG_HOME`,
`XDG_DATA_HOME`, and `XDG_CACHE_HOME`. Preserve the guard in
`tests/conftest.py`.
- Never run library operations against `/home/nobloat/Music` during automated
work.
- Preserve atomic state/LRC writes, backup-before-media-mutation, restore
rollback, state-conflict checks, and newest-10 valid backup retention.
- Wrong confident catalogue matches are worse than `Unknown`. Do not weaken
matcher thresholds, version/variant safeguards, duration rules, or ambiguity
handling without a reproduced generic bug and regression tests.
- Automatic Sync, backfill, refresh, cache changes, and ordinary identity
rebuilds must not overwrite a valid file-bound manual identity lock.
- Preserve downloader destination checks, `.part` handling, response/content
validation, checksums, resume safety, and atomic finalization.
- Do not make normal Sync modify audio, lyrics, backups, downloads, or rmpc
configuration.

## Supported media and lyrics

- MP3: native discovery/metadata, ID3 USLT/SYLT, adjacent timed `.lrc`.
- FLAC: native discovery/metadata, plain Vorbis `LYRICS`, adjacent timed `.lrc`.
- M4A: native discovery/metadata, plain MP4 `©lyr`, adjacent timed `.lrc`.
- No conversion occurs. `sidecar_lrc_path(audio_path)` is authoritative.
- The deprecated `lyrics_dir` may load for compatibility but cannot redirect
new output.

## Development entry points

- TUI/CLI: `.venv/bin/999`
- CLI: `src/juice_lyrics/cli.py`
- TUI: `src/juice_lyrics/tui/app.py`, `src/juice_lyrics/tui/screens/`
- Incremental Library Sync: `src/juice_lyrics/services/library_index_sync.py`
- Status/maintenance: `src/juice_lyrics/services/library_status.py` and
`library_sync.py`
- Read-only duplicate analysis: `src/juice_lyrics/services/library_duplicates.py`
- Read-only metadata proposals: `src/juice_lyrics/services/metadata_audit.py`
- Transactional metadata writer foundation: `src/juice_lyrics/services/metadata_repair.py`
- Read-only diagnostics/support reports: `src/juice_lyrics/services/doctor.py`
- Shell completion generation: `src/juice_lyrics/services/shell_completion.py`
- Matching/identity: `src/juice_lyrics/library/matching.py` and
`src/juice_lyrics/services/library_identity.py`
- State: `src/juice_lyrics/state.py`
- Media/sidecars/backups: `src/juice_lyrics/library/media.py`,
`src/juice_lyrics/lyrics/sidecar.py`, `src/juice_lyrics/backup/manager.py`

## Verification

Use focused tests while developing, then one full run before declaring a code
milestone complete:

```bash
pytest -q tests/test_library_index_sync.py tests/test_tui_library.py
pytest -q
python -m compileall -q src
git diff --check
```

For packaging milestones, build with `python -m build` and clean-install both
the wheel and sdist in temporary environments outside the checkout. Never test
installation by replacing the user's real pipx environment.
For release preparation, follow `docs/BETA_RELEASE_CHECKLIST.md`. Do not merge
to `main`, create a tag/release, or publish a package without explicit approval.

Normal Library use is `999` → Library → `s` (**Sync Library**). Press `?` for
the implemented key map. Common safe routine work should be automatic/simple;
ambiguous or destructive work requires an explicit user decision.
Duplicate findings are evidence for review only; never auto-delete, merge,
move, retag, or replace media.
Metadata repair is exposed only through explicit per-field selection and a
cancel-first confirmation. Never bypass `metadata_repair.py` with direct tag
writes or weaken its backup, preservation, conflict, rollback, and lock checks.

## Roadmap discipline

The current roadmap is in `docs/PROJECT_STATE.md` and `docs/ROADMAP.md`. Keep
normal Library UX centered on **Sync Library** and **Issues**; keep
repair/recovery tools secondary. After substantial milestones, update
`docs/PROJECT_STATE.md` and any directly affected design/user documentation.
11 changes: 11 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -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]
Loading