Implement MediaShelf v1

The application the design describes: Flask + SQLite, Plex for library data,
Tautulli for watch history, report-only.

Structure follows the design's seams. providers/ splits MediaProvider from
HistoryProvider, because on this network library data and watch data live on
different machines and Jellyfin later will have no Tautulli equivalent.
scoring.py implements the reclaim score twice - as a SQL expression for the
live grid (weights change on every slider drag, so storing it would mean
rewriting thousands of rows per drag) and in Python for CSV export and tests,
with a property test over 500 generated rows asserting the two agree.
rules.py compiles saved views to parameterized SQL through a field/operator
whitelist; nothing user-supplied is ever interpolated.

Three properties are enforced by test rather than asserted in prose:

- Ingest is idempotent. Three consecutive full scans leave every count and
  every byte total unchanged. A scanner that double-counts produces a report
  that looks plausible and is wrong.
- Keep marks survive Plex reassigning every rating key in the library. They
  are keyed on content GUID, scoped per library so the Movies and 4K Movies
  copies of the same film mark independently.
- Every config variable the app reads is declared in docker-compose.yml, so
  a variable set in Portainer can never silently do nothing.

Also found and fixed while verifying against a fake Plex+Tautulli pair:
executescript() commits the pending transaction, so migrations needed their
BEGIN/COMMIT inside the script; replaceChildren() renders null as the literal
text "null"; a hash-only URL change does not reload the document, so deep
links needed a hashchange listener; and SQLite ROUND rounds half away from
zero where Python rounds half to even.

73 tests, no live server required.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVbG48GAXfCZatcmX123Ra

mediashelf/providers/plex.py

@@ -0,0 +1,294 @@
+"""Plex Media Server provider.
+
+Talks directly to the server on the LAN with a server token — no plex.tv round
+trip, so it works whether or not Plex's cloud is up. JSON throughout via the
+Accept header, which avoids XML parsing entirely (§4.1).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Iterator
+
+import requests
+
+from .base import (
+    Account,
+    AuthError,
+    Coverage,
+    Item,
+    Library,
+    Part,
+    ProviderError,
+    ServerInfo,
+    WatchEvent,
+)
+
+log = logging.getLogger(__name__)
+
+LIBTYPE_MOVIE = 1
+LIBTYPE_SHOW = 2
+LIBTYPE_SEASON = 3
+LIBTYPE_EPISODE = 4
+
+
+def _int(v, default=0):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return default
+
+
+def _opt_int(v):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+class PlexClient:
+    def __init__(self, base_url: str, token: str, *, timeout: int = 30,
+                 verify_ssl: bool = True, page_size: int = 500,
+                 request_delay_ms: int = 0, client_id: str = "mediashelf"):
+        if not base_url or not token:
+            raise ProviderError("Plex is not configured (PLEX_BASE_URL / PLEX_TOKEN)")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+        self.page_size = page_size
+        self.delay = request_delay_ms / 1000.0
+        self.session = requests.Session()
+        self.session.headers.update({
+            "X-Plex-Token": token,
+            "Accept": "application/json",
+            "X-Plex-Product": "MediaShelf",
+            "X-Plex-Client-Identifier": client_id,
+        })
+
+    def get(self, path: str, params: dict | None = None, *, headers: dict | None = None) -> dict:
+        url = self.base_url + path
+        last: Exception | None = None
+        for attempt in range(3):
+            try:
+                if self.delay:
+                    time.sleep(self.delay)
+                r = self.session.get(url, params=params, headers=headers,
+                                     timeout=self.timeout, verify=self.verify_ssl)
+                if r.status_code in (401, 403):
+                    raise AuthError("Plex rejected the token (HTTP %s)" % r.status_code)
+                r.raise_for_status()
+                return r.json().get("MediaContainer", {}) or {}
+            except AuthError:
+                raise  # never retried: a retry loop will not fix a bad token
+            except Exception as e:  # noqa: BLE001
+                last = e
+                if attempt < 2:
+                    time.sleep(2 ** attempt)
+        raise ProviderError("Plex request failed: %s (%s)" % (path, last))
+
+    def paged(self, path: str, params: dict | None = None) -> Iterator[dict]:
+        """Yield Metadata rows, paging with X-Plex-Container-* headers."""
+        start = 0
+        while True:
+            headers = {
+                "X-Plex-Container-Start": str(start),
+                "X-Plex-Container-Size": str(self.page_size),
+            }
+            mc = self.get(path, params, headers=headers)
+            batch = mc.get("Metadata") or []
+            if not batch:
+                return
+            for row in batch:
+                yield row
+            start += len(batch)
+            total = _int(mc.get("totalSize") or mc.get("size") or 0)
+            if start >= total:
+                return
+
+
+class PlexProvider:
+    """MediaProvider implementation."""
+
+    kind = "plex"
+
+    def __init__(self, client: PlexClient):
+        self.client = client
+
+    # ── identity ─────────────────────────────────────────────────────────
+
+    def server_info(self) -> ServerInfo:
+        mc = self.client.get("/identity")
+        return ServerInfo(
+            kind="plex",
+            name=mc.get("friendlyName") or "Plex",
+            version=mc.get("version") or "",
+            server_id=mc.get("machineIdentifier") or "",
+            base_url=self.client.base_url,
+        )
+
+    # ── libraries ────────────────────────────────────────────────────────
+
+    def libraries(self) -> list[Library]:
+        mc = self.client.get("/library/sections")
+        out = []
+        for d in mc.get("Directory") or []:
+            kind = d.get("type")
+            if kind not in ("movie", "show"):
+                continue          # music/photo/other are out of scope (§1.2)
+            out.append(Library(
+                provider_key=str(d.get("key")),
+                title=(d.get("title") or "").strip(),
+                kind=kind,
+                locations=[loc.get("path") for loc in (d.get("Location") or [])
+                           if loc.get("path")],
+            ))
+        return out
+
+    # ── items ────────────────────────────────────────────────────────────
+
+    def items(self, library: Library) -> Iterator[Item]:
+        libtype = LIBTYPE_MOVIE if library.kind == "movie" else LIBTYPE_EPISODE
+        path = "/library/sections/%s/all" % library.provider_key
+        for row in self.client.paged(path, {"type": libtype}):
+            item = self._to_item(row, library)
+            if item is not None:
+                yield item
+
+    def show_guids(self, library: Library) -> dict[str, str]:
+        """Map show ratingKey -> show guid.
+
+        Episodes carry grandparentRatingKey but not the show's guid, and keep
+        marks for seasons are keyed on the SHOW's guid (§6.6), so this mapping
+        has to be fetched separately — one cheap request per show library.
+        """
+        out: dict[str, str] = {}
+        path = "/library/sections/%s/all" % library.provider_key
+        for row in self.client.paged(path, {"type": LIBTYPE_SHOW}):
+            rk = row.get("ratingKey")
+            if rk is not None:
+                out[str(rk)] = row.get("guid") or ""
+        return out
+
+    @staticmethod
+    def _to_item(row: dict, library: Library) -> Item | None:
+        rk = row.get("ratingKey")
+        if rk is None:
+            return None
+
+        parts: list[Part] = []
+        resolution = video_codec = None
+        for media in row.get("Media") or []:
+            if resolution is None:
+                resolution = media.get("videoResolution")
+                video_codec = media.get("videoCodec")
+            for p in media.get("Part") or []:
+                if not p.get("file"):
+                    continue
+                parts.append(Part(
+                    file_path=p["file"],
+                    size_bytes=_int(p.get("size")),
+                    provider_part_id=str(p.get("id")) if p.get("id") is not None else None,
+                    container=p.get("container") or media.get("container"),
+                    resolution=media.get("videoResolution"),
+                    video_codec=media.get("videoCodec"),
+                    audio_codec=media.get("audioCodec"),
+                    bitrate=_opt_int(media.get("bitrate")),
+                ))
+
+        kind = "movie" if library.kind == "movie" else "episode"
+        return Item(
+            provider_item_id=str(rk),
+            kind=kind,
+            title=row.get("title") or "(untitled)",
+            library_key=library.provider_key,
+            guid=row.get("guid"),
+            sort_title=row.get("titleSort"),
+            year=_opt_int(row.get("year")),
+            added_at=_opt_int(row.get("addedAt")),
+            updated_at=_opt_int(row.get("updatedAt")),
+            duration_ms=_int(row.get("duration")),
+            view_count=_int(row.get("viewCount")),
+            last_viewed_at=_opt_int(row.get("lastViewedAt")),
+            resolution=resolution,
+            video_codec=video_codec,
+            parts=parts,
+            show_id=str(row["grandparentRatingKey"]) if row.get("grandparentRatingKey") is not None else None,
+            show_title=row.get("grandparentTitle"),
+            season_id=str(row["parentRatingKey"]) if row.get("parentRatingKey") is not None else None,
+            season_number=_opt_int(row.get("parentIndex")),
+            episode_number=_opt_int(row.get("index")),
+        )
+
+    def refresh_library(self, library: Library) -> None:
+        raise NotImplementedError("v1 never writes to Plex (§1.2)")
+
+
+class PlexHistoryProvider:
+    """Fallback HistoryProvider using /status/sessions/history/all.
+
+    Server-wide across accounts, which solves the token-scoping problem — but it
+    records only that a play happened, never how far it got. Everything it
+    returns is therefore treated as a completed view and the 'rejection' score
+    component drops out of the weighting (§4.11).
+    """
+
+    name = "plex"
+
+    def __init__(self, client: PlexClient):
+        self.client = client
+
+    @property
+    def has_completion_data(self) -> bool:
+        return False
+
+    def server_info(self) -> ServerInfo:
+        mc = self.client.get("/identity")
+        return ServerInfo(
+            kind="plex",
+            name=mc.get("friendlyName") or "Plex",
+            version=mc.get("version") or "",
+            server_id=mc.get("machineIdentifier") or "",
+            base_url=self.client.base_url,
+        )
+
+    def accounts(self) -> list[Account]:
+        try:
+            mc = self.client.get("/accounts")
+        except ProviderError:
+            return []
+        out = []
+        for a in mc.get("Account") or []:
+            if a.get("id") is None:
+                continue
+            out.append(Account(account_id=str(a["id"]), name=a.get("name")))
+        return out
+
+    def watch_events(self, since: int | None = None) -> Iterator[WatchEvent]:
+        params: dict = {"sort": "viewedAt:desc"}
+        for row in self.client.paged("/status/sessions/history/all", params):
+            viewed = _opt_int(row.get("viewedAt"))
+            rk = row.get("ratingKey")
+            if viewed is None or rk is None:
+                continue
+            if since is not None and viewed <= since:
+                return          # sorted desc: the watermark ends the walk
+            yield WatchEvent(
+                source="plex",
+                source_row_id=str(row.get("historyKey") or f"{rk}:{viewed}"),
+                provider_item_id=str(rk),
+                viewed_at=viewed,
+                account_id=str(row["accountID"]) if row.get("accountID") is not None else None,
+                media_type=row.get("type"),
+            )
+
+    def coverage(self) -> Coverage:
+        earliest = latest = None
+        count = 0
+        for ev in self.watch_events():
+            count += 1
+            if latest is None or ev.viewed_at > latest:
+                latest = ev.viewed_at
+            if earliest is None or ev.viewed_at < earliest:
+                earliest = ev.viewed_at
+        return Coverage(earliest, latest, count)