kokopelli 0.6.0__tar.gz

kokopelli-0.6.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.3
+Name: kokopelli
+Version: 0.6.0
+Summary: Add your description here
+Author: Marvin8
+Author-email: Marvin8 <marvin8@tuta.io>
+Requires-Dist: async-lru~=2.3.0
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: loguru~=0.7.3
+Requires-Dist: rich~=15.0.0
+Requires-Dist: textual~=8.2.8
+Requires-Dist: typer~=0.26.8
+Requires-Dist: whenever~=0.10.2
+Requires-Python: >=3.11
+Project-URL: Issues, https://codeberg.org/marvin8/kokopelli/issues
+Project-URL: Source, https://codeberg.org/marvin8/kokopelli
+Project-URL: Changelog, https://codeberg.org/marvin8/kokopelli/src/branch/main/CHANGELOG.md
+Project-URL: Documentation, https://kokopelli.marvin8.zone/latest/

kokopelli-0.6.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["uv_build>=0.10.0,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "kokopelli"
+version = "0.6.0"
+description = "Add your description here"
+authors = [
+    { name = "Marvin8", email = "marvin8@tuta.io" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "async-lru~=2.3.0",
+    "httpx~=0.28.1",
+    "loguru~=0.7.3",
+    "rich~=15.0.0",
+    "textual~=8.2.8",
+    "typer~=0.26.8",
+    "whenever~=0.10.2",
+]
+
+[project.urls]
+Issues = "https://codeberg.org/marvin8/kokopelli/issues"
+Source = "https://codeberg.org/marvin8/kokopelli"
+Changelog = "https://codeberg.org/marvin8/kokopelli/src/branch/main/CHANGELOG.md"
+Documentation = "https://kokopelli.marvin8.zone/latest/"
+
+[dependency-groups]
+dev = [
+    "bump-my-version~=1.4.1",
+    "complexipy~=6.0.1",
+    "mike~=2.2.0",
+    "mkdocs~=1.6.1",
+    "mkdocs-material~=9.7.6",
+    "nox-uv~=0.8.0",
+    "prek~=0.4.8",
+    "pytest~=9.1.1",
+    "pytest-asyncio~=1.4.0",
+    "pytest-cov~=7.1.0",
+    "pytest-httpx~=0.36.2",
+    "ruff~=0.15.21",
+    "ty~=0.0.57",
+    "uv~=0.11.28",
+]
+
+
+[project.scripts]
+kokopelli = "kokopelli.tui:typer_shim"
+
+[tool.bumpversion]
+commit = true
+tag = true
+tag_name = "{new_version}"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+message = ":wrench: bump: version {current_version} → {new_version}"
+pre_commit_hooks = ["uv sync", "git add uv.lock"]
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+
+[tool.complexipy]
+paths = ["src"]
+
+[tool.deptry.per_rule_ignores]
+DEP002 = [
+    "h11",  # Addresses vulnerability in transient dependency GHSA-vqfr-h8mv-ghfj
+    "h2",  # Addresses vulnerability in transient dependency GHSA-847f-9342-265h
+]
+
+[tool.pysentry.ignore]
+while_no_fix = ["PYSEC-2026-89"]  # markdown — unfixable HIGH; transitive via docs toolchain, not in published package
+
+[tool.uv]
+constraint-dependencies = [
+    "idna>=3.15",  # GHSA-65pc-fj4g-8rjx — DoS via long inputs; fix in 3.15
+    "pydantic-settings>=2.14.2",  # Addresses vulnerability GHSA-4xgf-cpjx-pc3j
+    "pygments>=2.20.0",  # Addresses vulnerability GHSA-5239-wwwm-4pmq
+]
+
+[tool.zaojun]
+cache = true
+groups = true
+min-age = 7

kokopelli-0.6.0/src/kokopelli/__init__.py

@@ -0,0 +1 @@
+"""Provide cli functions to see recommendations for Movies and TV Shows."""

kokopelli-0.6.0/src/kokopelli/api_actions.py

@@ -0,0 +1,272 @@
+"""Definitions and methods for TRAKT API."""
+
+import json
+from time import sleep
+from typing import Final
+from typing import NamedTuple
+from typing import TypeAlias
+from typing import TypedDict
+
+from async_lru import alru_cache
+from httpx import AsyncClient
+from httpx import Client
+from rich import print
+
+from .credentials import CredentialsDict
+
+
+class MediaType(NamedTuple):
+    """Holding literals for use with API, URL buildin and screen display."""
+
+    api_multi: str
+    api_single: str
+    tmdb: str
+    display: str
+
+
+class TraktIds(TypedDict, total=False):
+    """Trakt media item identifier set."""
+
+    trakt: int
+    slug: str
+    imdb: str
+    tmdb: int
+    tvdb: int
+
+
+class TraktItem(TypedDict, total=False):
+    """A Trakt movie or TV show item as returned by the API."""
+
+    title: str
+    year: int
+    ids: TraktIds
+    overview: str
+    tagline: str
+    rating: float
+    country: str
+    genres: list[str]
+    status: str
+
+
+class WatchedEntry(TypedDict, total=False):
+    """A single entry from the watched history endpoint."""
+
+    movie: TraktItem
+    show: TraktItem
+    plays: int
+    last_watched_at: str
+
+
+class RatedEntry(TypedDict, total=False):
+    """A single entry from the ratings endpoint."""
+
+    movie: TraktItem
+    show: TraktItem
+    rating: int
+    rated_at: str
+
+
+class Person(TypedDict, total=False):
+    """A person (actor, director, etc.) as returned by the people endpoint."""
+
+    name: str
+
+
+class CastMember(TypedDict, total=False):
+    """A cast entry linking a person to their character."""
+
+    person: Person
+    character: str
+
+
+class PeopleResponse(TypedDict, total=False):
+    """Response from the people endpoint."""
+
+    cast: list[CastMember]
+
+
+class RecommendationsPage(NamedTuple):
+    """Paginated result from the recommendations endpoint."""
+
+    items: list[TraktItem]
+    has_more: bool
+
+
+HeadersDict: TypeAlias = dict[str, str]
+OauthDict: TypeAlias = dict[str, str | None]
+
+
+class TraktApi:
+    """Encapsulation of trakt.tv API interactions."""
+
+    MOVIES: Final[MediaType] = MediaType(api_multi="movies", api_single="movie", tmdb="movie", display="Movies")
+    TVSHOWS: Final[MediaType] = MediaType(api_multi="shows", api_single="show", tmdb="tv", display="TV Shows")
+
+    BASE_URL: Final = "https://trakt.tv"
+    API_BASE: Final = "https://api.trakt.tv/"
+
+    def __init__(self, headers: HeadersDict, limit: int = 20) -> None:
+        """Initialise the API client with Trakt authentication headers."""
+        self.headers = headers
+        self.limit = limit
+        self.client = AsyncClient(timeout=30.0)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self.client.aclose()
+
+    @alru_cache
+    async def get_watched(self, item_type: MediaType) -> list[WatchedEntry]:
+        """Get watched items of item_type."""
+        extended_info: str = "?extended=full"
+        if item_type == TraktApi.TVSHOWS:
+            extended_info += ",noseasons"
+        response = await self.client.get(
+            f"{TraktApi.API_BASE}/sync/watched/{item_type.api_multi}{extended_info}", headers=self.headers
+        )
+        response.raise_for_status()
+        return response.json()
+
+    @alru_cache
+    async def get_rated(self, item_type: MediaType) -> list[RatedEntry]:
+        """Get rated items of item_type."""
+        response = await self.client.get(
+            f"{TraktApi.API_BASE}/sync/ratings/{item_type.api_multi}", headers=self.headers
+        )
+        response.raise_for_status()
+        return response.json()
+
+    @alru_cache
+    async def get_recommendations(self, item_type: MediaType, page: int = 1) -> RecommendationsPage:
+        """Retrieve recommendations for the given page using a growing limit."""
+        total_limit = self.limit * page
+        response = await self.client.get(
+            f"{TraktApi.API_BASE}recommendations/{item_type.api_multi}?extended=full&limit={total_limit}",
+            headers=self.headers,
+        )
+        response.raise_for_status()
+        all_items: list[TraktItem] = response.json()
+        offset = self.limit * (page - 1)
+        page_items = all_items[offset : offset + self.limit]
+        has_more = len(all_items) == total_limit
+        return RecommendationsPage(items=page_items, has_more=has_more)
+
+    def invalidate_recommendations_cache(self) -> None:
+        """Clear the recommendations cache so the next fetch re-requests from the API."""
+        TraktApi.get_recommendations.cache_clear()
+
+    def invalidate_watched_cache(self) -> None:
+        """Clear the watched cache after add_seen mutations."""
+        TraktApi.get_watched.cache_clear()
+
+    def invalidate_rated_cache(self) -> None:
+        """Clear the ratings cache after rate_item mutations."""
+        TraktApi.get_rated.cache_clear()
+
+    async def add_seen(self, data: str, remove: bool = False) -> None:
+        """Add tv shows and movies to seen history."""
+        response = await self.client.post(
+            f"{TraktApi.API_BASE}sync/history{'/remove' if remove else ''}", content=data, headers=self.headers
+        )
+        response.raise_for_status()
+
+    @alru_cache
+    async def lookup_by_id(self, trakt_id: str, item_type: MediaType) -> TraktItem:
+        """Lookup an item by their TRAKT id."""
+        url = f"{TraktApi.API_BASE}search/trakt/{trakt_id}?type={item_type.api_single}&extended=full"
+        response = await self.client.get(url=url, headers=self.headers)
+        response.raise_for_status()
+        item = response.json()[0]
+        return item[item_type.api_single]
+
+    @alru_cache
+    async def get_people(self, trakt_id: str, item_type: MediaType) -> PeopleResponse:
+        """Retrieve list of people involved with a movie or show."""
+        url = f"{TraktApi.API_BASE}/{item_type.api_multi}/{trakt_id}/people"
+        response = await self.client.get(url=url, headers=self.headers)
+        response.raise_for_status()
+        return response.json()
+
+    async def hide_item(self, trakt_id: str, item_type: MediaType) -> None:
+        """Hides a trakt item from recommendations."""
+        response = await self.client.delete(
+            f"{TraktApi.API_BASE}recommendations/{item_type.api_multi}/{trakt_id}", headers=self.headers
+        )
+        response.raise_for_status()
+
+    async def rate_item(self, data: str) -> None:
+        """Send rating for a movie or show to Trakt.tv."""
+        response = await self.client.post(f"{TraktApi.API_BASE}sync/ratings", content=data, headers=self.headers)
+        response.raise_for_status()
+
+
+def get_access_token(oauth: OauthDict) -> CredentialsDict:
+    """Run the device-code OAuth flow and return the resulting credentials."""
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "trakt-api-version": "2",
+        "trakt-api-key": str(oauth.get("client_id") or ""),
+    }
+    with Client() as client:
+        data = json.dumps({"client_id": oauth.get("client_id", "")})
+        response = client.post(f"{TraktApi.API_BASE}oauth/device/code", content=data, headers=headers)
+        response.raise_for_status()
+        device_code = response.json()
+        print(f"Please go to {device_code.get('verification_url')}/{device_code.get('user_code')}")
+        interval = device_code.get("interval")
+        time_left = device_code.get("expires_in")
+        sleep(interval)
+        time_left -= interval
+        token_data = json.dumps(
+            {
+                "code": device_code.get("device_code"),
+                "client_id": oauth.get("client_id"),
+                "client_secret": oauth.get("client_secret"),
+            }
+        )
+        while time_left > 0:
+            response = client.post(f"{TraktApi.API_BASE}oauth/device/token", content=token_data, headers=headers)
+            if response.status_code == 200:
+                break
+            sleep(interval)
+            time_left -= interval
+
+    device_token = response.json()
+    return CredentialsDict(
+        client_id=str(oauth.get("client_id") or ""),
+        client_secret=str(oauth.get("client_secret") or ""),
+        access_token=str(device_token.get("access_token", "")),
+        refresh_token=str(device_token.get("refresh_token", "")),
+        expires_in=int(device_token.get("expires_in", 0)),
+        created_at=int(device_token.get("created_at", 0)),
+    )
+
+
+def renew_access_token(oauth: OauthDict) -> CredentialsDict:
+    """Refresh the access token using the refresh_token and return updated credentials."""
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "trakt-api-version": "2",
+        "trakt-api-key": str(oauth.get("client_id") or ""),
+    }
+    data = json.dumps(
+        {
+            "refresh_token": oauth.get("refresh_token"),
+            "client_id": oauth.get("client_id"),
+            "client_secret": oauth.get("client_secret"),
+            "grant_type": "refresh_token",
+        }
+    )
+
+    with Client() as client:
+        response = client.post(f"{TraktApi.API_BASE}oauth/token", headers=headers, content=data)
+
+    tokens = response.json()
+    return CredentialsDict(
+        client_id=str(oauth.get("client_id") or ""),
+        client_secret=str(oauth.get("client_secret") or ""),
+        access_token=str(tokens.get("access_token", "")),
+        refresh_token=str(tokens.get("refresh_token", "")),
+        expires_in=int(tokens.get("expires_in", 0)),
+        created_at=int(tokens.get("created_at", 0)),
+    )

kokopelli-0.6.0/src/kokopelli/credentials.py

@@ -0,0 +1,76 @@
+"""Credential storage for kokopelli."""
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Final
+from typing import TypedDict
+
+
+class CredentialsDict(TypedDict, total=False):
+    """Trakt.tv OAuth credentials."""
+
+    client_id: str
+    client_secret: str
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    created_at: int
+
+
+CREDENTIALS_DIR: Final[Path] = (
+    Path(os.environ["XDG_CONFIG_HOME"]) / "kokopelli"
+    if "XDG_CONFIG_HOME" in os.environ
+    else Path.home() / ".config" / "kokopelli"
+)
+CREDENTIALS_PATH: Final[Path] = CREDENTIALS_DIR / "credentials.toml"
+
+_ENVRC_KEY_MAP: Final[dict[str, str]] = {
+    "TRAKT_CLIENT_ID": "client_id",
+    "TRAKT_CLIENT_SECRET": "client_secret",
+    "TRAKT_ACCESS_TOKEN": "access_token",
+    "TRAKT_REFRESH_TOKEN": "refresh_token",
+    "TRAKT_TOKEN_EXPIRES_IN": "expires_in",
+    "TRAKT_TOKEN_CREATED_AT": "created_at",
+}
+
+_INT_FIELDS: Final[frozenset[str]] = frozenset({"expires_in", "created_at"})
+
+
+def read_credentials() -> CredentialsDict:
+    """Read credentials from the XDG config file."""
+    if not CREDENTIALS_PATH.exists():
+        return CredentialsDict()
+    with CREDENTIALS_PATH.open("rb") as f:
+        data = tomllib.load(f)
+    return CredentialsDict(**data.get("credentials", {}))
+
+
+def write_credentials(creds: CredentialsDict) -> None:
+    """Write credentials to the XDG config file with owner-only permissions."""
+    CREDENTIALS_DIR.mkdir(parents=True, exist_ok=True)
+    lines = ["[credentials]\n"]
+    for key, value in creds.items():
+        if isinstance(value, int):
+            lines.append(f"{key} = {value}\n")
+        else:
+            lines.append(f'{key} = "{value}"\n')
+    CREDENTIALS_PATH.write_text("".join(lines), encoding="utf-8")
+    CREDENTIALS_PATH.chmod(0o600)
+
+
+def migrate_from_envrc(envrc_path: Path) -> CredentialsDict | None:
+    """Parse an .envrc file and return a CredentialsDict if credentials are found."""
+    if not envrc_path.exists():
+        return None
+    raw: dict[str, str | int] = {}
+    for line in envrc_path.read_text(encoding="utf-8").splitlines():
+        if not line.startswith("export "):
+            continue
+        _, _, assignment = line.partition(" ")
+        key, _, value = assignment.partition("=")
+        mapped = _ENVRC_KEY_MAP.get(key)
+        if mapped is None:
+            continue
+        raw[mapped] = int(value) if mapped in _INT_FIELDS else value
+    return CredentialsDict(**raw) if raw else None

kokopelli-0.6.0/src/kokopelli/tui.py

@@ -0,0 +1,771 @@
+"""Methods to control tui."""
+
+import asyncio
+import json
+import os
+import sys
+import webbrowser
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import ClassVar
+
+import httpx
+import typer
+from loguru import logger as log
+
+if TYPE_CHECKING:
+    from loguru import Logger
+    from loguru import Record
+from textual.app import App
+from textual.app import ComposeResult
+from textual.containers import Container
+from textual.containers import Horizontal
+from textual.containers import Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button
+from textual.widgets import DataTable
+from textual.widgets import Footer
+from textual.widgets import Header
+from textual.widgets import Label
+from textual.widgets import LoadingIndicator
+from textual.widgets import TextArea
+from textual.widgets.data_table import RowKey
+from whenever import Instant
+
+from .api_actions import HeadersDict
+from .api_actions import MediaType
+from .api_actions import OauthDict
+from .api_actions import RecommendationsPage
+from .api_actions import TraktApi
+from .api_actions import TraktItem
+from .api_actions import get_access_token
+from .api_actions import renew_access_token
+from .credentials import CREDENTIALS_PATH
+from .credentials import CredentialsDict
+from .credentials import migrate_from_envrc
+from .credentials import read_credentials
+from .credentials import write_credentials
+
+LOG_DIR: Path = (
+    Path(os.environ["XDG_STATE_HOME"]) / "kokopelli"
+    if "XDG_STATE_HOME" in os.environ
+    else Path.home() / ".local" / "state" / "kokopelli"
+)
+LOG_PATH: Path = LOG_DIR / "trakt.log"
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _log_format(record: "Record") -> str:
+    """Render extra fields as key=value pairs; omit the section when empty."""
+    extra = record["extra"]
+    extra_part = " | " + " ".join(f"{k}={v!r}" for k, v in sorted(extra.items())) if extra else ""
+    base = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<8} | {name}:{function}:{line}"
+    return base + extra_part + " | {message}\n{exception}"
+
+
+log.remove()
+log.add(sink=LOG_PATH, level="DEBUG", format=_log_format, colorize=False)
+log.add(sink=sys.stdout, level="ERROR", format=_log_format, colorize=False)
+
+
+def _error_message(exc: httpx.HTTPError) -> str:
+    """Return a human-readable message for an httpx error."""
+    if isinstance(exc, httpx.HTTPStatusError) and exc.response.status_code == 401:
+        return "Token expired — run `tui --configure`"
+    if isinstance(exc, httpx.ConnectError):
+        return "Network error — check your connection and retry"
+    if isinstance(exc, httpx.TimeoutException):
+        return "Request timed out — retry"
+    return str(exc)
+
+
+class LoadingScreen(ModalScreen):
+    """Loading screen to be usd while retrieving info from trakt."""
+
+    DEFAULT_CSS = """
+    LoadingScreen {
+        align: center middle;
+    }
+
+    LoadingScreen > Container {
+        min-width: 12;
+        min-height: 3;
+        border: thick $accent;
+        background: $surface;
+        padding: 1;
+    }"""
+
+    def compose(self) -> ComposeResult:
+        """Assemble widgets."""
+        with Container():
+            yield LoadingIndicator()
+
+
+class RatingsScreen(ModalScreen):
+    """Define modal screen to ask for rating."""
+
+    DEFAULT_CSS = """
+    RatingsScreen {
+        align: center middle;
+    }
+
+    RatingsScreen > Container {
+        width: auto;
+        height: auto;
+        border: thick $background 80%;
+        background: $surface;
+    }
+
+    RatingsScreen > Container > Label {
+        width: 100%;
+        content-align-horizontal: center;
+        margin-top: 1;
+    }
+
+    RatingsScreen > Container > Horizontal {
+        width: auto;
+        height: auto;
+    }
+
+    RatingsScreen > Container > Horizontal > Button {
+        margin: 2 4;
+    }
+
+    RatingsScreen > Container > Button {
+        margin: 2 4;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        """Assemble Widgets."""
+        with Container():
+            yield Label("How would you rate this?", id="rating")
+            with Horizontal():
+                yield Button("Weak Sauce :(", id="r1")
+                yield Button("Terrible", id="r2")
+                yield Button("Bad", id="r3")
+                yield Button("Poor", id="r4")
+                yield Button("Meh", id="r5")
+            with Horizontal():
+                yield Button("Fair", id="r6")
+                yield Button("Good", id="r7")
+                yield Button("Great", id="r8")
+                yield Button("Superb", id="r9")
+                yield Button("Totally Ninja!", id="r10")
+            yield Button("Cancel", id="cancel")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Process button press."""
+        if event.button.id == "cancel":
+            self.dismiss()
+
+        self.dismiss(str(event.button.id))
+
+
+class RecommendApp(App):
+    """Define behaviour of recommendations app."""
+
+    BINDINGS: ClassVar = [
+        ("m", "recommend_movies", "Recommend Movies"),
+        ("M", "unrated_watched_movies", "Rate watched movies"),
+        ("t", "recommend_shows", "Recommend TV-Shows"),
+        ("T", "unrated_watched_shows", "Rate watched TV-Shows"),
+        ("i", "open_info", "Open Info in Browser"),
+        ("I", "open_in_tmdb", "Open TMDB in Browser"),
+        ("r", "rate_seen", "Rate highlighted and mark as seen"),
+        ("R", "rate_hide", "Rate highlighted and hide"),
+        ("s", "seen", "Mark highlighted as Seen"),
+        ("h", "hide", "Hide highlighted"),
+        ("x", "exit", "Close app and exit"),
+    ]
+
+    def __init__(self, headers: HeadersDict, unrated_limit: int = 20):
+        """Initialise the app with Trakt API headers and default widget state."""
+        super().__init__()
+        self.api = TraktApi(headers=headers, limit=unrated_limit)
+        self.item_type = TraktApi.MOVIES
+        self.details = TextArea(read_only=True, name="Details")
+        self.actors: DataTable = DataTable(name="Actors", show_cursor=False)
+        self.items: DataTable = DataTable(cursor_type="row", name="items")
+        self.title = "Recommendations"
+        self.sub_title = self.item_type.display
+        self.row_key_highlighted: str | None = None
+        self.info: list[TraktItem] = []
+        self._bg_tasks: list[asyncio.Task[None]] = []
+        self.unrated_limit: int = unrated_limit
+        self.recommendation_page: int = 1
+        self._is_paginated_view: bool = True
+
+    def compose(self) -> ComposeResult:
+        """Assemble Widgets."""
+        yield Header()
+        with Vertical():
+            yield self.items
+            with Horizontal():
+                yield self.details
+                yield self.actors
+        yield Footer()
+
+    def _item_from_row_key(self, row_key: str) -> TraktItem | None:
+        """Return the TraktItem from self.info matching the given trakt ID string."""
+        for item in self.info:
+            if str((item.get("ids") or {}).get("trakt", "")) == row_key:
+                return item
+        return None
+
+    async def on_unmount(self) -> None:
+        """Drain in-flight background tasks then close the HTTP client."""
+        pending = [t for t in self._bg_tasks if not t.done()]
+        if pending:
+            await asyncio.gather(*pending, return_exceptions=True)
+        await self.api.close()
+
+    async def on_mount(self) -> None:
+        """Populate Movie Recommendations."""
+        self.items.add_columns("Title", "Year", "Rating", "Country")
+        self.actors.add_columns("Actor", "Role")
+        await self.push_screen(LoadingScreen())
+        await self.load_recommendations()
+        await self.pop_screen()
+        self._bg_tasks.append(asyncio.create_task(self._prewarm_caches()))
+
+    async def _populate_items_table(self, info: list[TraktItem], has_more: bool = False) -> None:
+        """Populate the items DataTable from a list of TraktItems."""
+        _log = log.bind(phase="populate_table", item_type=self.item_type.display)
+        self.info = info
+        self.sub_title = self.item_type.display
+        self.row_key_highlighted = None
+        self.items.clear()
+        row_keys: list[str | None] = []
+        for item in self.info:
+            ids = item.get("ids") or {}
+            trakt_id = ids.get("trakt")
+            trakt_id_str = str(trakt_id) if trakt_id is not None else None
+            rating = f"{float(item.get('rating') or 0.0):.2f}"
+            self.items.add_row(item.get("title"), item.get("year"), rating, item.get("country"), key=trakt_id_str)
+            row_keys.append(trakt_id_str)
+        if has_more:
+            self.items.add_row("...", None, None, None, key="__more__")
+        _log.debug(f"Table populated: {len(info)} items, row_keys={row_keys}")
+        if self.info:
+            self.items.move_cursor(row=0)
+        self._bg_tasks.append(asyncio.create_task(self._prefetch_people()))
+
+    async def _prefetch_people(self) -> None:
+        """Warm the people cache for all currently displayed items in parallel."""
+        _log = log.bind(phase="prefetch_people", item_type=self.item_type.display)
+        ids: list[str] = []
+        for item in self.info:
+            item_ids = item.get("ids") or {}
+            trakt_id = item_ids.get("trakt")
+            if trakt_id is not None:
+                ids.append(str(trakt_id))
+        _log.debug(f"Prefetching people for {len(ids)} items")
+        results = await asyncio.gather(
+            *(self.api.get_people(trakt_id=tid, item_type=self.item_type) for tid in ids),
+            return_exceptions=True,
+        )
+        errors = [r for r in results if isinstance(r, BaseException)]
+        if errors:
+            _log.warning(f"{len(errors)} people fetch(es) failed: {errors[0]}")
+        else:
+            _log.debug("People prefetch complete")
+
+    async def _prewarm_unrated(self, item_type: MediaType) -> None:
+        """Warm watched/rated/lookup caches for one item type."""
+        watched = await self.api.get_watched(item_type)
+        rated = await self.api.get_rated(item_type)
+        is_movie = item_type == TraktApi.MOVIES
+        rated_ids = self._collect_rated_ids(rated, is_movie)
+        await self._collect_unrated_items(watched, rated_ids, is_movie, item_type)
+
+    async def _prewarm_caches(self) -> None:
+        """Pre-fetch all non-current views into alru_cache in the background."""
+        _log = log.bind(phase="prewarm_caches")
+        _log.debug("Starting background cache pre-warm")
+        await asyncio.gather(
+            self.api.get_recommendations(TraktApi.TVSHOWS),
+            self._prewarm_unrated(TraktApi.MOVIES),
+            self._prewarm_unrated(TraktApi.TVSHOWS),
+            return_exceptions=True,
+        )
+        _log.debug("Cache pre-warm complete")
+
+    async def load_recommendations(self):
+        """Load recommendations from Trakt.tv."""
+        _log = log.bind(phase="load_recommendations", item_type=self.item_type.display)
+        _log.debug(f"Fetching recommendations page={self.recommendation_page}")
+        page_result: RecommendationsPage = await self.api.get_recommendations(
+            item_type=self.item_type, page=self.recommendation_page
+        )
+        _log.debug(f"Got {len(page_result.items)} recommendations has_more={page_result.has_more}")
+        await self._populate_items_table(page_result.items, has_more=page_result.has_more)
+
+    async def _refresh_details(self, row_key: str) -> None:
+        """Update the details text and actors table for the given trakt ID string."""
+        _log = log.bind(phase="refresh_details", row_key=row_key)
+        self.row_key_highlighted = row_key
+        display_item: TraktItem | None = self._item_from_row_key(row_key)
+        _log.debug(f"title={display_item.get('title')!r}" if display_item else "item not found in self.info")
+        detail_text = ""
+        if display_item:
+            tagline = display_item.get("tagline")
+            detail_text += tagline if tagline else ""
+            detail_text += "\n\n"
+            detail_text += f"{', '.join(display_item.get('genres') or [])}"
+            detail_text += "\n\n"
+            detail_text += display_item.get("overview") or ""
+            ids = display_item.get("ids") or {}
+            slug = ids.get("slug")
+            detail_text += f"\n\n{TraktApi.BASE_URL}/{self.item_type.api_multi}/{slug}" if slug else ""
+            detail_text += "\n\n"
+            detail_text += f"Status: {display_item.get('status', '')}"
+        self.details.text = detail_text
+        people = await self.api.get_people(trakt_id=row_key, item_type=self.item_type)
+        cast = people.get("cast") or []
+        self.actors.clear()
+        for actor in cast[:10]:
+            person = actor.get("person")
+            self.actors.add_row(person.get("name") if person else None, actor.get("character"))
+
+    async def on_data_table_row_highlighted(self, message: DataTable.RowHighlighted) -> None:
+        """Update Details widget when cursor has moved on recommendations list."""
+        if message.row_key is None or not message.row_key.value:
+            return
+        if message.row_key.value == "__more__":
+            self.row_key_highlighted = None
+            return
+        await self._refresh_details(message.row_key.value)
+
+    async def on_data_table_row_selected(self, message: DataTable.RowSelected) -> None:
+        """Load the next recommendations page when Enter is pressed on the sentinel row."""
+        if message.row_key.value == "__more__" and self._is_paginated_view:
+            self.recommendation_page += 1
+            await self.push_screen(LoadingScreen())
+            await self.load_recommendations()
+            await self.pop_screen()
+
+    async def action_recommend_movies(self) -> None:
+        """Load movie recommendations."""
+        await self.app.push_screen(LoadingScreen())
+
+        self.item_type = TraktApi.MOVIES
+        self.recommendation_page = 1
+        self._is_paginated_view = True
+        await self.load_recommendations()
+
+        await self.app.pop_screen()
+
+    async def action_unrated_watched_movies(self) -> None:
+        """Load watched movies that have not been rated."""
+        await self.app.push_screen(LoadingScreen())
+
+        self.item_type = TraktApi.MOVIES
+        self._is_paginated_view = False
+        await self.load_unrated_watched()
+
+        await self.app.pop_screen()
+
+    async def action_unrated_watched_shows(self) -> None:
+        """Load watched tv shows that have not been rated."""
+        await self.app.push_screen(LoadingScreen())
+
+        self.item_type = TraktApi.TVSHOWS
+        self._is_paginated_view = False
+        await self.load_unrated_watched()
+
+        await self.app.pop_screen()
+
+    def _collect_rated_ids(self, rated_items: list, is_movie: bool) -> set[int]:
+        """Extract the set of rated trakt IDs from a rated-items list."""
+        rated_ids: set[int] = set()
+        for rated_entry in rated_items:
+            rated_item = rated_entry.get("movie") if is_movie else rated_entry.get("show")
+            if rated_item:
+                ids = rated_item.get("ids") or {}
+                trakt_id = ids.get("trakt")
+                if trakt_id is not None:
+                    rated_ids.add(trakt_id)
+        return rated_ids
+
+    def _extract_unrated_ids(self, watched_items: list, rated_ids: set[int], is_movie: bool) -> tuple[list[str], bool]:
+        """Collect up to self.unrated_limit unrated trakt IDs; also report whether more exist."""
+        unrated_ids: list[str] = []
+        seen_ids: set[int] = set()
+        for entry in watched_items:
+            item = entry.get("movie") if is_movie else entry.get("show")
+            if not item:
+                continue
+            ids = item.get("ids") or {}
+            trakt_id = ids.get("trakt")
+            if trakt_id is None or trakt_id in seen_ids:
+                continue
+            if trakt_id not in rated_ids:
+                seen_ids.add(trakt_id)
+                unrated_ids.append(str(trakt_id))
+            if len(unrated_ids) > self.unrated_limit:
+                return unrated_ids[: self.unrated_limit], True
+        return unrated_ids, False
+
+    async def _collect_unrated_items(
+        self, watched_items: list, rated_ids: set[int], is_movie: bool, item_type: MediaType
+    ) -> tuple[list[TraktItem], bool]:
+        """Filter watched items to those not yet rated, up to self.unrated_limit items."""
+        unrated_ids, has_more = self._extract_unrated_ids(watched_items, rated_ids, is_movie)
+        results = await asyncio.gather(
+            *(self.api.lookup_by_id(trakt_id=tid, item_type=item_type) for tid in unrated_ids),
+            return_exceptions=True,
+        )
+        errors = [r for r in results if isinstance(r, BaseException)]
+        if errors:
+            log.bind(phase="collect_unrated_items", item_type=item_type.display).warning(
+                f"{len(errors)} lookup(s) failed: {errors[0]}"
+            )
+        return [r for r in results if isinstance(r, dict)], has_more
+
+    async def load_unrated_watched(self):
+        """Load unrated but watched items (movies or tv-shows)."""
+        _log = log.bind(phase="load_unrated_watched", item_type=self.item_type.display)
+        _log.debug("Fetching watched and rated lists")
+        watched_items = await self.api.get_watched(item_type=self.item_type)
+        rated_items = await self.api.get_rated(item_type=self.item_type)
+        _log.debug(f"{len(watched_items)=} {len(rated_items)=}")
+        is_movie = self.item_type == TraktApi.MOVIES
+        rated_ids = self._collect_rated_ids(rated_items, is_movie)
+        unrated_items, has_more = await self._collect_unrated_items(watched_items, rated_ids, is_movie, self.item_type)
+        _log.debug(f"{len(unrated_items)=}")
+        await self._populate_items_table(unrated_items, has_more=has_more)
+
+    async def action_recommend_shows(self) -> None:
+        """Load tv show recommendations."""
+        await self.app.push_screen(LoadingScreen())
+
+        self.item_type = TraktApi.TVSHOWS
+        self.recommendation_page = 1
+        self._is_paginated_view = True
+        await self.load_recommendations()
+
+        await self.app.pop_screen()
+
+    async def _remove_item_optimistically(self, row_key: str) -> None:
+        """Remove item from self.info and table; clear panels then repopulate for next row."""
+        self.info = [item for item in self.info if str((item.get("ids") or {}).get("trakt", "")) != row_key]
+        try:
+            self.items.remove_row(row_key=RowKey(row_key))
+        except Exception as exc:
+            log.bind(phase="remove_optimistic", row_key=row_key).error(f"Could not remove row: {exc}")
+        self.details.text = ""
+        self.actors.clear()
+        if self.items.row_count > 0:
+            new_key = self.items.ordered_rows[self.items.cursor_row].key.value
+            if new_key:
+                await self._refresh_details(new_key)
+        else:
+            self.row_key_highlighted = None
+
+    async def action_seen(self) -> None:
+        """Mark highlighted item as seen."""
+        if not self.row_key_highlighted:
+            return
+        row_key = self.row_key_highlighted
+        item_type = self.item_type
+        item = self._item_from_row_key(row_key)
+        if not item:
+            log.bind(phase="action_seen", row_key=row_key).warning("row_key not found in self.info")
+            return
+        data = json.dumps({item_type.api_multi: [item]})
+        self.api.invalidate_recommendations_cache()
+        self.api.invalidate_watched_cache()
+        await self._remove_item_optimistically(row_key)
+        self._bg_tasks.append(asyncio.create_task(self._add_seen_bg(data, row_key)))
+
+    async def _add_seen_bg(self, data: str, row_key: str) -> None:
+        """Send the add-to-history request to Trakt; notify on failure."""
+        _log = log.bind(phase="action_seen", row_key=row_key)
+        try:
+            await self.api.add_seen(data=data)
+            _log.debug("Marked as seen")
+        except httpx.HTTPError as exc:
+            _log.error(f"Network error marking seen: {exc}")
+            self.notify(f"Mark as seen failed: {_error_message(exc)}", severity="error")
+
+    async def action_hide(self) -> None:
+        """Hide item from recommendations."""
+        if not self.row_key_highlighted:
+            return
+        row_key = self.row_key_highlighted
+        item_type = self.item_type
+        self.api.invalidate_recommendations_cache()
+        await self._remove_item_optimistically(row_key)
+        self._bg_tasks.append(asyncio.create_task(self._hide_item_bg(row_key, item_type)))
+
+    async def _hide_item_bg(self, row_key: str, item_type: MediaType) -> None:
+        """Send the hide request to Trakt; notify on failure."""
+        _log = log.bind(phase="action_hide", row_key=row_key)
+        try:
+            await self.api.hide_item(trakt_id=row_key, item_type=item_type)
+            _log.debug("Hidden")
+        except httpx.HTTPError as exc:
+            _log.error(f"Network error hiding item: {exc}")
+            self.notify(f"Hide failed: {_error_message(exc)}", severity="error")
+
+    async def _do_rate_seen(self, row_key: str, rating: str) -> None:
+        """Optimistically remove item, then rate+seen in the background."""
+        _log = log.bind(phase="action_rate_seen", row_key=row_key, rating=rating)
+        source_item = self._item_from_row_key(row_key)
+        if not source_item:
+            _log.warning("row_key not found in self.info — cannot rate+seen")
+            return
+        item = dict(source_item)
+        item["rating"] = float(rating[1:])
+        _log.debug(f"Rating+seen: {item.get('title')!r} score={item.get('rating')}")
+        data = json.dumps({self.item_type.api_multi: [item]})
+        self.api.invalidate_rated_cache()
+        self.api.invalidate_watched_cache()
+        await self._remove_item_optimistically(row_key)
+        self._bg_tasks.append(asyncio.create_task(self._rate_seen_bg(data, _log)))
+
+    async def _rate_seen_bg(self, data: str, _log: "Logger") -> None:
+        """Send rate and add-to-history requests concurrently; notify on failure."""
+        try:
+            await asyncio.gather(self.api.rate_item(data=data), self.api.add_seen(data=data))
+            _log.debug("Rate+seen complete")
+        except httpx.HTTPError as exc:
+            _log.error(f"Network error rating+seen: {exc}")
+            self.notify(f"Rating failed: {_error_message(exc)}", severity="error")
+
+    async def action_rate_seen(self) -> None:
+        """Show modal rating screen; rate and mark the item as seen on confirmation."""
+        row_key = self.row_key_highlighted
+
+        async def check_rating(rating: str | None) -> None:
+            """Handle rating screen dismissal; proceed if a rating was selected."""
+            _log = log.bind(phase="action_rate_seen", row_key=row_key)
+            if rating and row_key:
+                await self._do_rate_seen(row_key, rating)
+            else:
+                _log.debug("Rating cancelled or no row selected")
+
+        await self.push_screen(RatingsScreen(), check_rating)
+
+    async def _do_rate_hide(self, row_key: str, rating: str) -> None:
+        """Optimistically remove item, then rate+hide in the background."""
+        _log = log.bind(phase="action_rate_hide", row_key=row_key, rating=rating)
+        source_item = self._item_from_row_key(row_key)
+        if not source_item:
+            _log.warning("row_key not found in self.info — cannot rate+hide")
+            return
+        item = dict(source_item)
+        item["rating"] = float(rating[1:])
+        _log.debug(f"Rating+hide: {item.get('title')!r} score={item.get('rating')}")
+        data = json.dumps({self.item_type.api_multi: [item]})
+        item_type = self.item_type
+        self.api.invalidate_recommendations_cache()
+        self.api.invalidate_rated_cache()
+        await self._remove_item_optimistically(row_key)
+        self._bg_tasks.append(asyncio.create_task(self._rate_hide_bg(data, row_key, item_type, _log)))
+
+    async def _rate_hide_bg(self, data: str, row_key: str, item_type: MediaType, _log: "Logger") -> None:
+        """Send rate and hide requests concurrently; notify on failure."""
+        try:
+            await asyncio.gather(
+                self.api.rate_item(data=data),
+                self.api.hide_item(trakt_id=row_key, item_type=item_type),
+            )
+            _log.debug("Rate+hide complete")
+        except httpx.HTTPError as exc:
+            _log.error(f"Network error rating+hide: {exc}")
+            self.notify(f"Rating+hide failed: {_error_message(exc)}", severity="error")
+
+    async def action_rate_hide(self) -> None:
+        """Show modal rating screen; rate and hide the item on confirmation."""
+        row_key = self.row_key_highlighted
+
+        async def check_rating(rating: str | None) -> None:
+            """Handle rating screen dismissal; proceed if a rating was selected."""
+            _log = log.bind(phase="action_rate_hide", row_key=row_key)
+            if rating and row_key:
+                await self._do_rate_hide(row_key, rating)
+            else:
+                _log.debug("Rating cancelled or no row selected")
+
+        await self.push_screen(RatingsScreen(), check_rating)
+
+    def action_open_info(self) -> None:
+        """Open the information URL in the default browser."""
+        if not self.row_key_highlighted:
+            return
+
+        display_item: TraktItem | None = None
+        for item in self.info:
+            ids = item.get("ids") or {}
+            if str(ids.get("trakt", "")) == self.row_key_highlighted:
+                display_item = item
+                break
+
+        if not display_item:
+            return
+
+        ids = display_item.get("ids") or {}
+        slug = ids.get("slug")
+        if not slug:
+            return
+
+        url = f"{TraktApi.BASE_URL}/{self.item_type.api_multi}/{slug}"
+        webbrowser.open(url, autoraise=True)
+
+    def action_open_in_tmdb(self) -> None:
+        """Open the TMDB about this in the default browser."""
+        if not self.row_key_highlighted:
+            return
+
+        display_item: TraktItem | None = None
+        for item in self.info:
+            ids = item.get("ids") or {}
+            if str(ids.get("trakt", "")) == self.row_key_highlighted:
+                display_item = item
+                break
+
+        if not display_item:
+            return
+
+        ids = display_item.get("ids") or {}
+        tmdb_id = ids.get("tmdb")
+        if not tmdb_id:
+            return
+
+        url = f"https://www.themoviedb.org/{self.item_type.tmdb}/{tmdb_id}"
+        webbrowser.open(url, autoraise=True)
+
+    def action_exit(self) -> None:
+        """Close and exit app."""
+        self.app.exit()
+
+
+def _migrate_credentials_if_needed() -> None:
+    """Migrate credentials from .envrc to the credentials file if needed."""
+    if not CREDENTIALS_PATH.exists():
+        migrated = migrate_from_envrc(Path(".envrc"))
+        if migrated:
+            write_credentials(migrated)
+            log.bind(phase="startup").info("Migrated credentials from .envrc to {}", CREDENTIALS_PATH)
+
+
+def _resolve_client_credentials(
+    configure: bool,
+    client_id: str | None,
+    client_secret: str | None,
+    creds: CredentialsDict,
+) -> tuple[str, str]:
+    """Return (client_id, client_secret) by prompting (configure) or from args/stored creds."""
+    if configure:
+        resolved_client_id: str = typer.prompt(
+            "Trakt Client ID",
+            default=client_id or creds.get("client_id"),
+        )
+        resolved_client_secret: str = typer.prompt(
+            "Trakt Client Secret",
+            default=client_secret or creds.get("client_secret"),
+            hide_input=True,
+        )
+        return resolved_client_id, resolved_client_secret
+
+    resolved_client_id = client_id or creds.get("client_id")
+    resolved_client_secret = client_secret or creds.get("client_secret")
+    if not resolved_client_id or not resolved_client_secret:
+        print("Provide TRAKT_CLIENT_ID and TRAKT_CLIENT_SECRET to authenticate.")
+        sys.exit(1)
+    return resolved_client_id, resolved_client_secret
+
+
+def _ensure_initial_credentials(
+    configure: bool,
+    client_id: str | None,
+    client_secret: str | None,
+) -> CredentialsDict:
+    """Handle .envrc migration, read credentials, and run OAuth flow when needed."""
+    _migrate_credentials_if_needed()
+    creds = read_credentials()
+
+    if configure or not creds.get("access_token"):
+        resolved_client_id, resolved_client_secret = _resolve_client_credentials(
+            configure, client_id, client_secret, creds
+        )
+        oauth: OauthDict = {
+            "client_id": resolved_client_id,
+            "client_secret": resolved_client_secret,
+            "oauth_token": None,
+            "oauth_refresh": None,
+            "refresh_token": None,
+        }
+        try:
+            creds = get_access_token(oauth=oauth)
+            write_credentials(creds)
+        except httpx.HTTPError as exc:
+            print(f"Authentication failed: {_error_message(exc)}", file=sys.stderr)
+            sys.exit(1)
+
+    return creds
+
+
+def _maybe_renew_token(creds: CredentialsDict) -> CredentialsDict:
+    """Renew the access token if it expires within 4 weeks; on failure keep existing creds."""
+    token_created_at = creds.get("created_at")
+    token_expires_in = creds.get("expires_in")
+    if not (token_created_at and token_expires_in):
+        return creds
+
+    now = Instant.now()
+    in_4_weeks = now.to_system_tz().add(weeks=4)
+    token_expires = Instant.from_timestamp(token_created_at + token_expires_in)
+    _log = log.bind(phase="startup")
+    _log.debug(f"token_expires={token_expires}")
+    if token_expires <= in_4_weeks:
+        _log.debug("Renewing auth token, expires in next 4 weeks")
+        oauth: OauthDict = {
+            "client_id": creds.get("client_id"),
+            "client_secret": creds.get("client_secret"),
+            "oauth_token": creds.get("access_token"),
+            "oauth_refresh": None,
+            "refresh_token": creds.get("refresh_token"),
+        }
+        try:
+            creds = renew_access_token(oauth=oauth)
+            write_credentials(creds)
+        except httpx.HTTPError as exc:
+            print(
+                f"Token renewal failed ({_error_message(exc)}) — continuing with existing token",
+                file=sys.stderr,
+            )
+    return creds
+
+
+def tui(
+    configure: bool = False,
+    client_id: str | None = typer.Option(envvar="TRAKT_CLIENT_ID", default=None),
+    client_secret: str | None = typer.Option(envvar="TRAKT_CLIENT_SECRET", default=None),
+    limit: int = typer.Option(default=20, envvar="TRAKT_UNRATED_LIMIT"),
+) -> None:
+    """Start the Trakt recommendations TUI."""
+    creds = _ensure_initial_credentials(configure, client_id, client_secret)
+
+    if not creds.get("access_token"):
+        print("No credentials found. Run with --configure to authenticate.")
+        sys.exit(1)
+
+    creds = _maybe_renew_token(creds)
+
+    headers: HeadersDict = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {creds.get('access_token', '')}",
+        "trakt-api-version": "2",
+        "trakt-api-key": creds.get("client_id", ""),
+    }
+
+    app = RecommendApp(headers=headers, unrated_limit=limit)
+    app.run()
+
+
+def typer_shim():
+    """Run Typer app."""
+    typer.run(tui)