feat(sources): local_folder source backend + import pipeline

First ingest path beyond manual upload (plan §1C). Source abstraction +
the first concrete backend, so a homelab can index an existing library.

- domain: SourceBackend/IndexableSource ports + SourceInfo/SourceFile shapes
- infrastructure/sources: LocalFolderSource (walks a mounted dir, idempotent
  source_id = relative path) + registry built from settings
- application: LibraryImportService — batch sibling of UploadService; dedup on
  (source, source_id), copy into storage, minimal track (metadata_status=pending,
  enrichment fills the rest in 1D), per-file failures isolated
- workers: scan_local_folder arq task (registered) + enqueue helper (503 if
  Redis down)
- api: GET /sources, POST /sources/{source}/scan (admin, enqueues), /health
- config: LOCAL_MEDIA_IMPORT_PATH; README + .env.example documented
- tests: scanner, registry, import service (fakes) + DB-gated sources API path

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

app/infrastructure/sources/__init__.py

@@ -0,0 +1 @@
+"""Source backends — driven adapters that discover/fetch tracks."""

app/infrastructure/sources/local_folder.py

@@ -0,0 +1,60 @@
+"""``local`` source — indexes audio files from a mounted folder.
+
+Walks a configured root directory and yields each audio file as a
+:class:`SourceFile`. It does **not** parse tags or resolve artist/album — that's
+enrichment's job (plan §6.2); this stays a thin discovery layer. ``source_id``
+is the path relative to the root, so re-scans are idempotent.
+"""
+
+import os
+from collections.abc import Iterator
+from pathlib import Path
+
+from app.domain.sources import SourceFile, SourceInfo
+from app.infrastructure.db.models.enums import TrackSource
+
+# Extensions we treat as audio. Mirrors the formats StreamingService serves.
+_AUDIO_EXTENSIONS = frozenset(
+    {"mp3", "flac", "m4a", "aac", "ogg", "opus", "wav", "wma", "aiff", "aif", "alac"}
+)
+
+
+class LocalFolderSource:
+    """Implements :class:`app.domain.ports.IndexableSource`."""
+
+    name = TrackSource.LOCAL.value
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def info(self) -> SourceInfo:
+        return SourceInfo(
+            name=self.name,
+            label="Local folder",
+            kind="indexable",
+            available=self.is_available(),
+        )
+
+    def is_available(self) -> bool:
+        return self._root.is_dir()
+
+    def scan(self) -> Iterator[SourceFile]:
+        if not self.is_available():
+            return
+        for dirpath, _dirnames, filenames in os.walk(self._root):
+            for filename in sorted(filenames):
+                ext = Path(filename).suffix.lower().lstrip(".")
+                if ext not in _AUDIO_EXTENSIONS:
+                    continue
+                path = Path(dirpath) / filename
+                try:
+                    size = path.stat().st_size
+                except OSError:
+                    continue  # vanished/unreadable between walk and stat → skip
+                yield SourceFile(
+                    source_id=path.relative_to(self._root).as_posix(),
+                    path=path,
+                    suggested_title=path.stem or "Unknown",
+                    file_format=ext,
+                    file_size=size,
+                )

app/infrastructure/sources/registry.py

@@ -0,0 +1,41 @@
+"""Source registry — selection + enumeration of configured backends.
+
+Built from settings at the composition root. Only sources that are configured
+are registered (e.g. ``local`` appears only when ``LOCAL_MEDIA_IMPORT_PATH`` is
+set), so enumeration reflects what the instance can actually use.
+"""
+
+from typing import cast
+
+from app.core.config import Settings
+from app.domain.errors import NotFoundError, ValidationError
+from app.domain.ports import IndexableSource, SourceBackend
+from app.domain.sources import SourceInfo
+from app.infrastructure.sources.local_folder import LocalFolderSource
+
+
+class SourceRegistry:
+    def __init__(self, backends: list[SourceBackend]) -> None:
+        self._by_name = {backend.name: backend for backend in backends}
+
+    def get(self, name: str) -> SourceBackend:
+        backend = self._by_name.get(name)
+        if backend is None:
+            raise NotFoundError(f"Source {name!r} is not configured.")
+        return backend
+
+    def indexable(self, name: str) -> IndexableSource:
+        backend = self.get(name)
+        if not hasattr(backend, "scan"):
+            raise ValidationError(f"Source {name!r} cannot be indexed.")
+        return cast(IndexableSource, backend)
+
+    def infos(self) -> list[SourceInfo]:
+        return [backend.info() for backend in self._by_name.values()]
+
+
+def build_source_registry(settings: Settings) -> SourceRegistry:
+    backends: list[SourceBackend] = []
+    if settings.local_media_import_path is not None:
+        backends.append(LocalFolderSource(settings.local_media_import_path))
+    return SourceRegistry(backends)