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/tautulli.py

@@ -0,0 +1,220 @@
+"""Tautulli history provider — the primary watch-data source (§4.8).
+
+Tautulli's database is independent of Plex's: clearing or pruning Plex history
+does not touch it, and unlike Plex it records how far into an item each play
+actually got. That last fact is the whole reason this is the primary source.
+
+Two things this module deliberately does NOT do:
+
+  * It never calls get_library_media_info for a show section. Measured against
+    the live server, that returns show-level rows with file_size 0 regardless of
+    the section_type parameter, so it cannot supply TV sizes (§4.11). Plex is the
+    only size authority.
+  * It never trusts an HTTP 200 as success. Tautulli returns 200 with
+    result:"error" in the body as its normal failure mode.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Iterator
+
+import requests
+
+from .base import (
+    Account,
+    AuthError,
+    Coverage,
+    ProviderError,
+    ServerInfo,
+    WatchEvent,
+)
+
+log = logging.getLogger(__name__)
+
+
+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 TautulliClient:
+    def __init__(self, base_url: str, api_key: str, *, timeout: int = 30,
+                 page_size: int = 1000):
+        if not base_url or not api_key:
+            raise ProviderError("Tautulli is not configured")
+        self.base_url = base_url.rstrip("/") + "/api/v2"
+        self.api_key = api_key
+        self.timeout = timeout
+        self.page_size = page_size
+        self.session = requests.Session()
+
+    def cmd(self, command: str, **params):
+        params["apikey"] = self.api_key
+        params["cmd"] = command
+        last: Exception | None = None
+        for attempt in range(3):
+            try:
+                r = self.session.get(self.base_url, params=params, timeout=self.timeout)
+                if r.status_code in (401, 403):
+                    raise AuthError("Tautulli rejected the API key (HTTP %s)" % r.status_code)
+                r.raise_for_status()
+                body = r.json()
+                resp = (body or {}).get("response") or {}
+                result = resp.get("result")
+                if result != "success":
+                    msg = resp.get("message") or "unknown error"
+                    # An invalid key surfaces here as a 200 with result:error.
+                    if "apikey" in str(msg).lower() or "auth" in str(msg).lower():
+                        raise AuthError("Tautulli: %s" % msg)
+                    raise ProviderError("Tautulli cmd=%s failed: %s" % (command, msg))
+                return resp.get("data")
+            except (AuthError, ProviderError):
+                raise
+            except Exception as e:  # noqa: BLE001
+                last = e
+                if attempt < 2:
+                    time.sleep(2 ** attempt)
+        raise ProviderError("Tautulli request failed: cmd=%s (%s)" % (command, last))
+
+
+class TautulliHistoryProvider:
+    """HistoryProvider implementation."""
+
+    name = "tautulli"
+
+    def __init__(self, client: TautulliClient):
+        self.client = client
+
+    @property
+    def has_completion_data(self) -> bool:
+        return True
+
+    def server_info(self) -> ServerInfo:
+        d = self.client.cmd("get_server_info") or {}
+        return ServerInfo(
+            kind="tautulli",
+            name=d.get("pms_name") or "Tautulli",
+            version="",
+            server_id=d.get("pms_identifier") or "",
+            base_url=self.client.base_url,
+        )
+
+    def accounts(self) -> list[Account]:
+        data = self.client.cmd("get_users") or []
+        out = []
+        for u in data:
+            uid = u.get("user_id")
+            if uid is None:
+                continue
+            out.append(Account(
+                account_id=str(uid),
+                name=u.get("username"),
+                friendly_name=u.get("friendly_name") or u.get("username"),
+            ))
+        return out
+
+    def _history_page(self, start: int, length: int, order_dir: str = "desc") -> tuple[list[dict], int]:
+        d = self.client.cmd(
+            "get_history",
+            grouping=0,           # raw events; MediaShelf does its own merging (§4.9)
+            order_column="date",
+            order_dir=order_dir,
+            start=start,
+            length=length,
+        ) or {}
+        rows = d.get("data") or []
+        total = _int(d.get("recordsFiltered") or d.get("recordsTotal") or 0)
+        return rows, total
+
+    def watch_events(self, since: int | None = None) -> Iterator[WatchEvent]:
+        """Walk history newest-first, stopping at the watermark."""
+        start = 0
+        while True:
+            rows, total = self._history_page(start, self.client.page_size)
+            if not rows:
+                return
+            for row in rows:
+                viewed = _opt_int(row.get("date"))
+                rk = row.get("rating_key")
+                if viewed is None or rk in (None, ""):
+                    continue
+                if since is not None and viewed <= since:
+                    return
+                yield self._to_event(row, viewed, rk)
+            start += len(rows)
+            if start >= total:
+                return
+
+    @staticmethod
+    def _to_event(row: dict, viewed: int, rk) -> WatchEvent:
+        row_id = row.get("row_id")
+        return WatchEvent(
+            source="tautulli",
+            source_row_id=str(row_id if row_id is not None else f"{rk}:{viewed}"),
+            provider_item_id=str(rk),
+            viewed_at=viewed,
+            account_id=str(row["user_id"]) if row.get("user_id") is not None else None,
+            reference_id=str(row["reference_id"]) if row.get("reference_id") is not None else None,
+            stopped_at=_opt_int(row.get("stopped")),
+            play_duration_s=_opt_int(row.get("play_duration")),
+            paused_counter_s=_opt_int(row.get("paused_counter")),
+            percent_complete=_opt_int(row.get("percent_complete")),
+            watched_status=_float_or_none(row.get("watched_status")),
+            media_type=row.get("media_type"),
+            platform=row.get("platform"),
+        )
+
+    def coverage(self) -> Coverage:
+        """Cheap: one row from each end plus the reported total."""
+        newest, total = self._history_page(0, 1, "desc")
+        oldest, _ = self._history_page(0, 1, "asc")
+        latest = _opt_int(newest[0].get("date")) if newest else None
+        earliest = _opt_int(oldest[0].get("date")) if oldest else None
+        return Coverage(earliest, latest, total)
+
+    # ── movie-only cross-check (§4.11) ───────────────────────────────────
+
+    def movie_media_info(self, section_id: str) -> list[dict]:
+        """Per-item size/play data for a MOVIE section only.
+
+        Never call this for a show section: it returns show-level rows with
+        file_size 0 whatever section_type is passed.
+        """
+        out: list[dict] = []
+        start = 0
+        while True:
+            d = self.client.cmd(
+                "get_library_media_info",
+                section_id=section_id,
+                start=start,
+                length=self.client.page_size,
+                order_column="file_size",
+                order_dir="desc",
+            ) or {}
+            rows = d.get("data") or []
+            if not rows:
+                break
+            out.extend(rows)
+            total = _int(d.get("recordsFiltered") or d.get("recordsTotal") or 0)
+            start += len(rows)
+            if start >= total:
+                break
+        return out
+
+
+def _float_or_none(v):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None