Keep only the newest 50 episodes of each podcast

A show that has published for years is unbounded: GEOlino Spezial alone is 358
episodes and 5.8 GB, and the device it syncs onto is a 30 GB SD card that also
holds the rest of the library. Nothing stopped the 6-hourly poll from eventually
filling it.

Cap each show's folder at general.podcast_episode_limit (default 50, null to
keep everything), pruning the oldest past that after each sync pass.

The same limit caps what is downloaded, and it has to be one number for both.
Prune to the newest N but keep fetching everything the feed offers, and every
poll would re-download exactly the episodes the previous one deleted - forever,
at full size, since missing_episodes() decides purely from what is on disk.
There is a test for that specific loop.

Pruning only touches files named the way this module names them
(YYYYMMDD - Title.ext), so feed.txt, folder.jpg, the failed-download record and
anything placed by hand are all left alone; a parse that fails means "not ours",
not "delete it". An episode's sidecar cover goes with it. A pass that only
deleted still reports a change, because the library needs the rescan just as
much as it does after a download.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

python-backend/tests/test_podcast_feeds.py

@@ -19,7 +19,9 @@ from musicmouse.library.podcast_feeds import (
     episode_filename,
     find_feed_shows,
     missing_episodes,
+    newest_episodes,
     parse_feed,
+    prune_show,
     resolve_episode_cover,
     sync_all_shows,
     sync_show,
@@ -630,3 +632,148 @@ async def test_sync_show_survives_a_corrupt_failure_record(tmp_path: Path) -> No
 
     assert changed is True
     assert (folder / "20250101 - Episode One.mp3").exists()
+
+
+# --------------------------------------------------------------- episode retention
+
+
+def _episode(day: int, *, title: str | None = None) -> Episode:
+    return Episode(
+        title=title or f"Episode {day}",
+        published=datetime(2025, 1, day, tzinfo=UTC),
+        enclosure_url=f"http://example.com/ep{day}.mp3",
+        enclosure_type="audio/mpeg",
+    )
+
+
+def _write_episode(folder: Path, name: str) -> Path:
+    path = folder / name
+    path.write_bytes(b"audio")
+    return path
+
+
+def test_newest_episodes_takes_the_most_recent_and_orders_them_newest_first() -> None:
+    episodes = [_episode(1), _episode(5), _episode(3)]
+    assert [e.published.day for e in newest_episodes(episodes, 2)] == [5, 3]
+
+
+def test_newest_episodes_keeps_everything_when_the_limit_is_none() -> None:
+    episodes = [_episode(1), _episode(5), _episode(3)]
+    assert len(newest_episodes(episodes, None)) == 3
+
+
+def test_prune_show_deletes_only_the_oldest_beyond_the_limit(tmp_path: Path) -> None:
+    folder = tmp_path / "show"
+    folder.mkdir()
+    for day in range(1, 6):
+        _write_episode(folder, f"2025010{day} - Episode {day}.mp3")
+
+    assert prune_show(folder, 2) == 3
+
+    remaining = sorted(path.name for path in folder.iterdir())
+    assert remaining == ["20250104 - Episode 4.mp3", "20250105 - Episode 5.mp3"]
+
+
+def test_prune_show_is_a_noop_below_the_limit(tmp_path: Path) -> None:
+    folder = tmp_path / "show"
+    folder.mkdir()
+    _write_episode(folder, "20250101 - Episode 1.mp3")
+    assert prune_show(folder, 50) == 0
+    assert prune_show(folder, None) == 0
+    assert (folder / "20250101 - Episode 1.mp3").exists()
+
+
+def test_prune_show_takes_the_sidecar_cover_with_the_episode(tmp_path: Path) -> None:
+    folder = tmp_path / "show"
+    folder.mkdir()
+    _write_episode(folder, "20250101 - Old.mp3")
+    (folder / "20250101 - Old.jpg").write_bytes(b"art")
+    _write_episode(folder, "20250102 - New.mp3")
+    (folder / "20250102 - New.jpg").write_bytes(b"art")
+
+    assert prune_show(folder, 1) == 1
+
+    assert not (folder / "20250101 - Old.jpg").exists()
+    assert (folder / "20250102 - New.jpg").exists()
+
+
+def test_prune_show_leaves_everything_it_did_not_name(tmp_path: Path) -> None:
+    """A folder holds more than episodes, and a hand-placed file is not ours to delete."""
+    folder = tmp_path / "show"
+    folder.mkdir()
+    for day in range(1, 4):
+        _write_episode(folder, f"2025010{day} - Episode {day}.mp3")
+    (folder / "feed.txt").write_text("http://example.com/feed.xml\n")
+    (folder / "folder.jpg").write_bytes(b"art")
+    (folder / ".failed-downloads.json").write_text("{}")
+    _write_episode(folder, "Grandpa's tape.mp3")
+
+    prune_show(folder, 1)
+
+    assert (folder / "feed.txt").exists()
+    assert (folder / "folder.jpg").exists()
+    assert (folder / ".failed-downloads.json").exists()
+    assert (folder / "Grandpa's tape.mp3").exists()
+
+
+@pytest.mark.asyncio
+async def test_sync_show_prunes_to_the_limit_after_downloading(tmp_path: Path) -> None:
+    folder = tmp_path / "show"
+    folder.mkdir()
+
+    def handler(request: httpx2.Request) -> httpx2.Response:
+        if str(request.url) == "http://example.com/feed.xml":
+            return httpx2.Response(200, content=_FEED)
+        return httpx2.Response(200, content=b"audio-bytes")
+
+    async with httpx2.AsyncClient(transport=httpx2.MockTransport(handler)) as client:
+        changed = await sync_show(client, folder, "http://example.com/feed.xml", keep=1)
+
+    assert changed is True
+    episodes = sorted(path.name for path in folder.iterdir() if path.suffix == ".mp3")
+    assert episodes == ["20250103 - Episode Two_ Special_Chars_.mp3"]
+
+
+@pytest.mark.asyncio
+async def test_sync_show_does_not_redownload_what_it_pruned(tmp_path: Path) -> None:
+    """The whole point of capping downloads as well as deletions.
+
+    Prune to the newest N but fetch everything the feed offers, and each poll would
+    re-download the episodes the previous one deleted - forever, at full size.
+    """
+    folder = tmp_path / "show"
+    folder.mkdir()
+    downloads: list[str] = []
+
+    def handler(request: httpx2.Request) -> httpx2.Response:
+        if str(request.url) == "http://example.com/feed.xml":
+            return httpx2.Response(200, content=_FEED)
+        downloads.append(str(request.url))
+        return httpx2.Response(200, content=b"audio-bytes")
+
+    async with httpx2.AsyncClient(transport=httpx2.MockTransport(handler)) as client:
+        await sync_show(client, folder, "http://example.com/feed.xml", keep=1)
+        first_pass = len(downloads)
+        changed_again = await sync_show(client, folder, "http://example.com/feed.xml", keep=1)
+
+    assert changed_again is False
+    assert len(downloads) == first_pass
+
+
+@pytest.mark.asyncio
+async def test_sync_show_reports_a_change_when_it_only_pruned(tmp_path: Path) -> None:
+    """A deletion needs a rescan as much as a download does, or the library goes on
+    offering tracks whose files are gone."""
+    folder = tmp_path / "show"
+    folder.mkdir()
+    _write_episode(folder, "20250101 - Episode One.mp3")
+    _write_episode(folder, "20250103 - Episode Two_ Special_Chars_.mp3")
+
+    def handler(request: httpx2.Request) -> httpx2.Response:
+        return httpx2.Response(200, content=_FEED)
+
+    async with httpx2.AsyncClient(transport=httpx2.MockTransport(handler)) as client:
+        changed = await sync_show(client, folder, "http://example.com/feed.xml", keep=1)
+
+    assert changed is True
+    assert not (folder / "20250101 - Episode One.mp3").exists()

python-backend/tests/test_podcast_service.py

@@ -32,7 +32,9 @@ async def test_run_checks_immediately_and_calls_on_change_only_when_something_ch
 ) -> None:
     calls = 0
 
-    async def fake_sync_all_shows(client: httpx2.AsyncClient, root: Path) -> bool:
+    async def fake_sync_all_shows(
+        client: httpx2.AsyncClient, root: Path, *, keep: int | None = None
+    ) -> bool:
         nonlocal calls
         calls += 1
         return calls == 1  # only the very first pass finds something new
@@ -63,7 +65,9 @@ async def test_run_survives_a_failing_pass(
 ) -> None:
     calls = 0
 
-    async def fake_sync_all_shows(client: httpx2.AsyncClient, root: Path) -> bool:
+    async def fake_sync_all_shows(
+        client: httpx2.AsyncClient, root: Path, *, keep: int | None = None
+    ) -> bool:
         nonlocal calls
         calls += 1
         if calls == 1: