feat: staging-dir + clean import_album library helpers

worker/lyra_worker/library.py

@@ -1,4 +1,6 @@
+import os
 import re
+import shutil
 
 from lyra_worker.types import MBTarget
 
@@ -17,3 +19,46 @@ def album_dir(dest_root: str, target: MBTarget) -> str:
     if target.year:
         album = f"{album} ({target.year})"
     return f"{dest_root}/{safe_name(target.artist)}/{album}"
+
+
+_AUDIO_EXT = {".flac", ".mp3", ".m4a", ".opus", ".ogg", ".aac", ".wav"}
+_COVER_STEMS = {"cover", "folder", "front"}
+_COVER_EXT = {".jpg", ".jpeg", ".png"}
+
+
+def staging_dir(dest_root: str, job_id: str) -> str:
+    """A per-job download staging directory, on the same filesystem as the library."""
+    return f"{dest_root}/.staging/{job_id}"
+
+
+def clear_staging_root(dest_root: str) -> None:
+    """Remove every staging dir (called at worker startup to sweep crash orphans)."""
+    shutil.rmtree(f"{dest_root}/.staging", ignore_errors=True)
+
+
+def _find_cover(staging: str) -> str | None:
+    for root, _dirs, files in os.walk(staging):
+        for name in sorted(files):
+            stem, ext = os.path.splitext(name)
+            if ext.lower() in _COVER_EXT and stem.lower() in _COVER_STEMS:
+                return os.path.join(root, name)
+    return None
+
+
+def import_album(staging: str, final: str) -> str:
+    """Move the album's audio files (+ one cover image) from `staging` into a fresh `final`,
+    replacing any existing folder there. Non-audio artifacts and nested subfolders are left
+    behind (the caller removes `staging`). Tolerates a missing `staging`. Returns `final`."""
+    if os.path.isdir(final):
+        shutil.rmtree(final)
+    os.makedirs(final, exist_ok=True)
+    if not os.path.isdir(staging):
+        return final
+    for name in sorted(os.listdir(staging)):
+        src = os.path.join(staging, name)
+        if os.path.isfile(src) and os.path.splitext(name)[1].lower() in _AUDIO_EXT:
+            shutil.move(src, os.path.join(final, name))
+    cover = _find_cover(staging)
+    if cover is not None:
+        shutil.move(cover, os.path.join(final, "cover.jpg"))
+    return final

worker/tests/test_staging.py

@@ -0,0 +1,49 @@
+import os
+
+from lyra_worker.library import clear_staging_root, import_album, staging_dir
+
+
+def test_staging_dir_path():
+    assert staging_dir("/music", "job-1") == "/music/.staging/job-1"
+
+
+def test_import_album_moves_audio_and_cover_into_fresh_final(tmp_path):
+    staging = tmp_path / "stg"
+    (staging / "sub").mkdir(parents=True)
+    (staging / "01 A.flac").write_bytes(b"a")
+    (staging / "02 B.flac").write_bytes(b"b")
+    (staging / "sub" / "cover.jpg").write_bytes(b"img")  # streamrip leaves art in a subfolder
+    (staging / "notes.txt").write_text("junk")
+    final = tmp_path / "lib" / "Artist" / "Album"
+
+    result = import_album(str(staging), str(final))
+
+    assert result == str(final)
+    assert sorted(os.listdir(final)) == ["01 A.flac", "02 B.flac", "cover.jpg"]  # audio + cover only
+
+
+def test_import_album_replaces_existing_final(tmp_path):
+    final = tmp_path / "lib" / "Artist" / "Album"
+    final.mkdir(parents=True)
+    (final / "old.flac").write_bytes(b"old")  # a stale lower-quality copy
+    staging = tmp_path / "stg"
+    staging.mkdir()
+    (staging / "01 New.flac").write_bytes(b"new")
+
+    import_album(str(staging), str(final))
+
+    assert sorted(os.listdir(final)) == ["01 New.flac"]  # old copy fully replaced
+
+
+def test_import_album_tolerates_missing_staging(tmp_path):
+    final = tmp_path / "Artist" / "Album"
+    import_album(str(tmp_path / "does-not-exist"), str(final))
+    assert os.path.isdir(final) and os.listdir(final) == []
+
+
+def test_clear_staging_root_removes_staging(tmp_path):
+    stg = tmp_path / ".staging" / "j1"
+    stg.mkdir(parents=True)
+    (stg / "x").write_bytes(b"")
+    clear_staging_root(str(tmp_path))
+    assert not (tmp_path / ".staging").exists()