plex-tui 0.3.28__tar.gz → 0.3.35__tar.gz

{plex_tui-0.3.28 → plex_tui-0.3.35}/AGENTS.md

@@ -87,8 +87,8 @@ contracts for these durable areas:
   config/auth, mpv playback, and smoke entry points.
 - `tests/`: pytest coverage for app helpers/navigation, service mapping,
   config/auth/player/artwork behavior, and release workflow checks.
-- `scripts/`: release/package maintenance scripts used by checks and
-  post-release automation.
+- `scripts/`: release/package maintenance scripts used by checks, deterministic
+  release staging, and post-release automation.
 - `packaging/`: Homebrew and AUR notes plus source AUR metadata.
 - `docs/`: research notes and README visual assets.
 - Root docs and config examples: README, PACKAGING, RELEASE, ROADMAP,
@@ -126,6 +126,7 @@ make test          # run pytest
 make compile       # compile src and tests
 make build         # build sdist and wheel
 make check-package # build and validate package metadata
+make stage-release # stage version and changelog updates for next release
 make check         # smoke, tests, compile, and package validation
 ```
 
@@ -168,6 +169,11 @@ Git history uses short imperative subjects, such as `Speed up grid navigation`
 and `Polish settings and grid navigation`. Keep commits scoped to one logical
 change and include docs/tests with behavior changes.
 
+For behavior changes that users or future release notes should know about, add
+or update the `CHANGELOG.md` `Unreleased` section as part of the work. Do not
+leave release-note reconstruction to the release staging step unless the change
+is intentionally internal-only and that reason is clear in the PR.
+
 Pull requests should include:
 
 - A concise summary of user-visible behavior.
@@ -199,6 +205,14 @@ only local tags or the latest GitHub Release. Non-release PRs with `#patch`,
 `#minor`, or `#major` still create tags, so release prep files should match the
 tag that the release PR merge will create.
 
+Use `make stage-release BUMP=patch`, `BUMP=minor`, or `BUMP=major` to stage a
+planned release. Agents must use this script-backed target for normal release
+prep instead of hand-editing version files and moving changelog entries. The
+target fetches tags, chooses the next version from the latest semver tag, updates
+`pyproject.toml`, `src/plextui/__init__.py`, and `CHANGELOG.md`, and fails if
+`CHANGELOG.md` has no `Unreleased` notes to release. After staging, run
+`make check-release` and the relevant validation before opening the release PR.
+
 GitHub Release publishing is controlled by release markers in PR titles only:
 `#release`, `#publish`, or `#ship`. Keep those markers out of ordinary PR titles
 unless the merge should publish PyPI, Homebrew, and AUR. PR bodies may mention
@@ -220,3 +234,11 @@ GitHub CLI notes:
 Never commit real Plex tokens, account tokens, debug logs, or local config files.
 Use `config.example.toml` for examples. Logs should redact tokens; preserve that
 behavior when changing playback or request diagnostics.
+
+
+## Optional Local Tooling
+
+If `rtk` is installed, it can be used to reduce noisy command output while
+preserving command behavior, for example `rtk git status`, `rtk git diff`, or
+`rtk pytest tests/`. Do not require `rtk` for repository work; fall back to the
+normal command when it is unavailable or when raw debugging output is needed.

{plex_tui-0.3.28 → plex_tui-0.3.35}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.3.35 - 2026-06-15
+
+- Documented Homebrew 6 tap trust requirements for installing from the
+  `so1omon563/plex-tui` tap.
+- Verified Plex server reachability during browser login before saving a server
+  URL, so first-run auth no longer offers endpoints that cannot be reached from
+  the current machine.
+
+## 0.3.31 - 2026-06-15
+
+- Polished media type labels so list and grid rows describe Plex media kinds
+  more clearly.
+- Improved first-run Plex server selection by preferring usable local/private
+  connection URLs, labeling connection types, marking the recommended endpoint,
+  and adding relogin recovery guidance for unreachable saved URLs.
+
 ## 0.3.28 - 2026-06-13
 
 - Added a DOX-aligned project agent model and documented repository operating

{plex_tui-0.3.28 → plex_tui-0.3.35}/Makefile

@@ -1,6 +1,7 @@
-.PHONY: install-dev run test compile smoke build check-package check-release check clean
+.PHONY: install-dev run test compile smoke build check-package check-release stage-release check clean
 
 PYTHON ?= .venv/bin/python
+BUMP ?= patch
 
 install-dev:
 	$(PYTHON) -m pip install -e ".[dev]"
@@ -26,6 +27,9 @@ check-package: build
 check-release:
 	$(PYTHON) scripts/check_release.py
 
+stage-release:
+	$(PYTHON) scripts/stage_release.py --bump $(BUMP)
+
 check: smoke test compile check-release check-package
 
 clean:

{plex_tui-0.3.28 → plex_tui-0.3.35}/PACKAGING.md

@@ -45,6 +45,7 @@ https://github.com/so1omon563/homebrew-plex-tui
 User install:
 
 ```bash
+brew trust --tap so1omon563/plex-tui
 brew tap so1omon563/plex-tui
 brew install plex-tui
 ```
@@ -52,6 +53,10 @@ brew install plex-tui
 The formula depends on `mpv` and `python@3.13`, then installs the Python app in
 a Homebrew-managed virtualenv. The first install can take several minutes
 because native Python resources such as `pillow` are built from source.
+Homebrew 6 requires non-official taps to be trusted before Homebrew loads
+formulae from them. The `plex-tui` formula only uses Homebrew/core formula
+dependencies, so users do not need to trust any additional taps for `mpv`,
+`python@3.13`, or the bundled Python resources.
 
 Validation commands:
 

{plex_tui-0.3.28 → plex_tui-0.3.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plex-tui
-Version: 0.3.28
+Version: 0.3.35
 Summary: A small standalone Plex terminal UI.
 Project-URL: Homepage, https://github.com/so1omon563/plex-tui
 Project-URL: Issues, https://github.com/so1omon563/plex-tui/issues
@@ -101,6 +101,7 @@ or follow the pipx installation guide.
 ### Homebrew
 
 ```bash
+brew trust --tap so1omon563/plex-tui
 brew tap so1omon563/plex-tui
 brew install plex-tui
 plex-tui --smoke
@@ -109,6 +110,9 @@ plex-tui --smoke
 The Homebrew formula installs `mpv` automatically. The first install can take
 several minutes because native Python dependencies such as `pillow` are built
 from source.
+Homebrew 6 requires non-official taps to be trusted before Homebrew loads
+formulae from them. `plex-tui` only depends on formulae from Homebrew/core, so no
+additional tap trust is required for its dependencies.
 
 ### Arch Linux
 

{plex_tui-0.3.28 → plex_tui-0.3.35}/README.md

@@ -65,6 +65,7 @@ or follow the pipx installation guide.
 ### Homebrew
 
 ```bash
+brew trust --tap so1omon563/plex-tui
 brew tap so1omon563/plex-tui
 brew install plex-tui
 plex-tui --smoke
@@ -73,6 +74,9 @@ plex-tui --smoke
 The Homebrew formula installs `mpv` automatically. The first install can take
 several minutes because native Python dependencies such as `pillow` are built
 from source.
+Homebrew 6 requires non-official taps to be trusted before Homebrew loads
+formulae from them. `plex-tui` only depends on formulae from Homebrew/core, so no
+additional tap trust is required for its dependencies.
 
 ### Arch Linux
 

{plex_tui-0.3.28 → plex_tui-0.3.35}/RELEASE.md

@@ -20,9 +20,9 @@ make check
 
 Prepare a release PR:
 
-- Update `version` in `pyproject.toml`.
-- Update `src/plextui/__init__.py`.
-- Move `CHANGELOG.md` entries from `Unreleased` to the release version and date.
+- Confirm `CHANGELOG.md` has accurate `Unreleased` entries for the changes being
+  released. Add or revise those notes before staging the release.
+- Run `make stage-release BUMP=patch`, `BUMP=minor`, or `BUMP=major`.
 - Confirm `README.md`, `PACKAGING.md`, and `config.example.toml` match current behavior.
 - Confirm the Git remote points to `https://github.com/so1omon563/plex-tui`.
 - Make sure the PR title or body includes the right bump marker:
@@ -31,8 +31,11 @@ Prepare a release PR:
   GitHub Release and publish to PyPI.
 
 The semver bumper creates tags from merge metadata, but it does not edit project
-files. Keep the version files and changelog in the PR aligned with the tag the
-merge will create.
+files. `make stage-release` fetches tags, chooses the next version from the
+latest semver tag, updates `pyproject.toml` and `src/plextui/__init__.py`, and
+moves `CHANGELOG.md` `Unreleased` entries into a dated version section. It fails
+when `Unreleased` is empty so release notes are fixed before the release PR is
+opened. Keep the staged files aligned with the tag the merge will create.
 
 Do not update Homebrew or AUR checksums in the release PR. Those checksums depend
 on the tag or published artifact that does not exist until after merge. Handle

{plex_tui-0.3.28 → plex_tui-0.3.35}/packaging/aur/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = plex-tui
 	pkgdesc = Standalone Plex terminal UI with mpv playback
-	pkgver = 0.3.20
+	pkgver = 0.3.31
 	pkgrel = 1
 	url = https://github.com/so1omon563/plex-tui
 	arch = any
@@ -16,7 +16,7 @@ pkgbase = plex-tui
 	depends = python-plexapi
 	depends = python-rich
 	depends = python-textual
-	source = plex-tui-0.3.20.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.3.20.tar.gz
-	sha256sums = 2e550a37c89b958d6eb4744cbd847fa3bbc7b202dc15ed63d1f22c787767f9b9
+	source = plex-tui-0.3.31.tar.gz::https://github.com/so1omon563/plex-tui/archive/refs/tags/v0.3.31.tar.gz
+	sha256sums = 89cf8080c48c7d57a0bf9f4e6b273e9842fef7ecfdf783bf3add6c2425a30569
 
 pkgname = plex-tui

{plex_tui-0.3.28 → plex_tui-0.3.35}/packaging/aur/PKGBUILD

@@ -1,6 +1,6 @@
 # Maintainer: so1omon
 pkgname=plex-tui
-pkgver=0.3.20
+pkgver=0.3.31
 pkgrel=1
 pkgdesc="Standalone Plex terminal UI with mpv playback"
 arch=("any")
@@ -22,7 +22,7 @@ makedepends=(
   "python-wheel"
 )
 source=("$pkgname-$pkgver.tar.gz::$url/archive/refs/tags/v$pkgver.tar.gz")
-sha256sums=("2e550a37c89b958d6eb4744cbd847fa3bbc7b202dc15ed63d1f22c787767f9b9")
+sha256sums=("89cf8080c48c7d57a0bf9f4e6b273e9842fef7ecfdf783bf3add6c2425a30569")
 
 build() {
   cd "$pkgname-$pkgver"

{plex_tui-0.3.28 → plex_tui-0.3.35}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plex-tui"
-version = "0.3.28"
+version = "0.3.35"
 description = "A small standalone Plex terminal UI."
 readme = "README.md"
 license = "MIT"

plex_tui-0.3.35/scripts/stage_release.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Stage deterministic release metadata updates."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import subprocess
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$")
+
+
+@dataclass(frozen=True, order=True)
+class Version:
+    major: int
+    minor: int
+    patch: int
+
+    @classmethod
+    def parse(cls, value: str) -> Version:
+        if not VERSION_RE.fullmatch(value):
+            raise ValueError(f"invalid version {value!r}; expected X.Y.Z")
+        major, minor, patch = [int(part) for part in value.split(".")]
+        return cls(major, minor, patch)
+
+    @classmethod
+    def parse_tag(cls, value: str) -> Version | None:
+        match = TAG_RE.fullmatch(value)
+        if not match:
+            return None
+        major, minor, patch = [int(part) for part in match.groups()]
+        return cls(major, minor, patch)
+
+    def bump(self, kind: str) -> Version:
+        if kind == "major":
+            return Version(self.major + 1, 0, 0)
+        if kind == "minor":
+            return Version(self.major, self.minor + 1, 0)
+        if kind == "patch":
+            return Version(self.major, self.minor, self.patch + 1)
+        raise ValueError(f"unsupported bump kind {kind!r}")
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path.cwd(), help="repository root")
+    parser.add_argument("--bump", choices=["patch", "minor", "major"], default="patch", help="semver bump from latest tag")
+    parser.add_argument("--version", help="explicit X.Y.Z version to stage")
+    parser.add_argument("--date", default=dt.date.today().isoformat(), help="release date in YYYY-MM-DD format")
+    parser.add_argument("--no-fetch", action="store_true", help="use local tags without fetching origin first")
+    args = parser.parse_args(argv)
+
+    root = args.root.resolve()
+    try:
+        stage_release(root, args.bump, args.version, args.date, fetch_tags=not args.no_fetch)
+    except ReleaseStageError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+class ReleaseStageError(RuntimeError):
+    pass
+
+
+def stage_release(root: Path, bump: str, explicit_version: str | None, release_date: str, *, fetch_tags: bool) -> None:
+    validate_release_date(release_date)
+    ensure_clean_worktree(root)
+    if fetch_tags:
+        run_git(root, ["fetch", "--tags", "origin"])
+
+    latest = latest_tag_version(root)
+    if latest is None:
+        raise ReleaseStageError("no semver tags found; expected tags like v0.3.31")
+
+    version = Version.parse(explicit_version) if explicit_version else latest.bump(bump)
+    if version <= latest:
+        raise ReleaseStageError(f"target version {version} must be newer than latest tag v{latest}")
+    if tag_exists(root, version):
+        raise ReleaseStageError(f"tag v{version} already exists")
+
+    current = Version.parse(read_pyproject_version(root / "pyproject.toml"))
+    if current >= version:
+        raise ReleaseStageError(f"project metadata is {current}, but target release is {version}")
+
+    ensure_changelog_ready(root / "CHANGELOG.md")
+    update_pyproject_version(root / "pyproject.toml", version)
+    update_init_version(root / "src/plextui/__init__.py", version)
+    update_changelog(root / "CHANGELOG.md", version, release_date)
+
+    print(f"staged release {version}")
+    print(f"PR title: Prepare release {version} #{bump} #release")
+
+
+def validate_release_date(value: str) -> None:
+    try:
+        dt.date.fromisoformat(value)
+    except ValueError as exc:
+        raise ReleaseStageError(f"invalid release date {value!r}; expected YYYY-MM-DD") from exc
+
+
+def ensure_clean_worktree(root: Path) -> None:
+    completed = run_git(root, ["status", "--porcelain"], capture=True)
+    if completed.stdout.strip():
+        raise ReleaseStageError("working tree must be clean before staging a release")
+
+
+def latest_tag_version(root: Path) -> Version | None:
+    completed = run_git(root, ["tag", "--list", "v[0-9]*"], capture=True)
+    versions = [version for tag in completed.stdout.splitlines() if (version := Version.parse_tag(tag.strip()))]
+    if not versions:
+        return None
+    return max(versions)
+
+
+def tag_exists(root: Path, version: Version) -> bool:
+    completed = run_git(root, ["tag", "--list", f"v{version}"], capture=True)
+    return bool(completed.stdout.strip())
+
+
+def run_git(root: Path, args: list[str], *, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            ["git", *args],
+            cwd=root,
+            check=True,
+            capture_output=capture,
+            text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        output = ((exc.stdout or "") + (exc.stderr or "")).strip()
+        message = f"git {' '.join(args)} failed"
+        if output:
+            message = f"{message}: {output}"
+        raise ReleaseStageError(message) from exc
+
+
+def read_pyproject_version(path: Path) -> str:
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ReleaseStageError(f"read {path}: {exc}") from exc
+    version = data.get("project", {}).get("version")
+    if not isinstance(version, str) or not version:
+        raise ReleaseStageError(f"{path} missing project.version")
+    return version
+
+
+def update_pyproject_version(path: Path, version: Version) -> None:
+    text = read_text(path)
+    updated, count = re.subn(r'(?m)^version = "[^"]+"$', f'version = "{version}"', text, count=1)
+    if count != 1:
+        raise ReleaseStageError(f"{path} must contain exactly one project version assignment")
+    path.write_text(updated, encoding="utf-8")
+
+
+def update_init_version(path: Path, version: Version) -> None:
+    text = read_text(path)
+    updated, count = re.subn(r'(?m)^__version__ = "[^"]+"$', f'__version__ = "{version}"', text, count=1)
+    if count != 1:
+        raise ReleaseStageError(f"{path} must contain exactly one __version__ assignment")
+    path.write_text(updated, encoding="utf-8")
+
+
+def ensure_changelog_ready(path: Path) -> None:
+    read_unreleased_entries(path)
+
+
+def update_changelog(path: Path, version: Version, release_date: str) -> None:
+    text, content_start, next_start, unreleased = read_unreleased_entries(path)
+    before = text[: text.find("## Unreleased")]
+    after = text[next_start:]
+    section = f"## Unreleased\n\n## {version} - {release_date}\n\n{unreleased}\n\n"
+    path.write_text(before + section + after, encoding="utf-8")
+
+
+def read_unreleased_entries(path: Path) -> tuple[str, int, int, str]:
+    text = read_text(path)
+    header = "## Unreleased"
+    start = text.find(header)
+    if start == -1:
+        raise ReleaseStageError("CHANGELOG.md must contain an Unreleased section")
+
+    content_start = start + len(header)
+    next_match = re.search(r"(?m)^## \d+\.\d+\.\d+ - \d{4}-\d{2}-\d{2}$", text[content_start:])
+    if next_match is None:
+        raise ReleaseStageError("CHANGELOG.md must contain a dated release section after Unreleased")
+
+    next_start = content_start + next_match.start()
+    unreleased = text[content_start:next_start].strip()
+    if not unreleased:
+        raise ReleaseStageError("CHANGELOG.md Unreleased section is empty; add release notes before staging")
+    return text, content_start, next_start, unreleased
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ReleaseStageError(f"read {path}: {exc}") from exc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{plex_tui-0.3.28 → plex_tui-0.3.35}/src/plextui/__init__.py

@@ -1,3 +1,3 @@
 """Plex TUI prototype."""
 
-__version__ = "0.3.28"
+__version__ = "0.3.35"

{plex_tui-0.3.28 → plex_tui-0.3.35}/src/plextui/app.py

@@ -63,7 +63,7 @@ from .player import (
     subtitle_choices,
     transcode_quality_label,
 )
-from .plex_service import PlexService, media_details, row_progress_marker
+from .plex_service import PlexService, kind_label, media_details, row_progress_marker
 GRID_CARD_GAP = 2
 GRID_DENSITY_SPECS = {
     "compact": {"width": 18, "content_width": 15, "art_width": 14, "art_height": 7, "height": 10, "max_columns": 6},
@@ -125,7 +125,7 @@ class LibraryMenuRow(ListItem):
 class MediaRow(ListItem):
     def __init__(self, media: MediaItem) -> None:
         marker = "▶" if media.playable else "›"
-        subtitle = f" [{media.kind}] {media.subtitle}".rstrip()
+        subtitle = f" [{kind_label(media.kind)}] {media.subtitle}".rstrip()
         progress = row_progress_marker(media.raw)
         progress_text = f" {progress}" if progress else ""
         self.label_text = f"{marker} {media.title}{subtitle}{progress_text}"
@@ -286,8 +286,10 @@ class LoadMoreRow(ListItem):
 
 
 class ServerRow(ListItem):
-    def __init__(self, choice: ServerChoice) -> None:
-        super().__init__(Label(f"{choice.name}  {choice.uri}"))
+    def __init__(self, choice: ServerChoice, is_recommended: bool = False) -> None:
+        marker = "* " if is_recommended else "  "
+        suffix = " (recommended)" if is_recommended else ""
+        super().__init__(Label(f"{marker}{choice.name}  {choice.uri}  [{choice.row_label}]{suffix}"))
         self.choice = choice
 
 
@@ -668,11 +670,11 @@ class PlexTuiApp(App[None]):
             self.set_media_title("Select Server")
             view = self.show_media_list()
             view.clear()
-            for choice in choices:
-                view.append(ServerRow(choice))
+            for index, choice in enumerate(choices):
+                view.append(ServerRow(choice, is_recommended=index == 0))
             view.focus()
-            self.show_detail_text("Choose the connection you want this app to use.")
-            self.set_status("Select a Plex server connection and press Enter")
+            self.show_detail_text("Choose the reachable connection you want this app to use. The first option is the recommended starting point.")
+            self.set_status("Select a reachable Plex server connection and press Enter")
 
         self.call_from_thread(show_choices)
 
@@ -739,7 +741,17 @@ class PlexTuiApp(App[None]):
             self.set_status(context_hint(row))
         elif isinstance(row, ServerRow):
             mark_active_row(event.list_view, row)
-            self.show_detail_text(f"{row.choice.name}\n\n{row.choice.uri}\n\nSource: {row.choice.source}")
+            self.show_detail_text(
+                "\n".join(
+                    [
+                        row.choice.name,
+                        "",
+                        row.choice.uri,
+                        f"Type: {row.choice.connection_label}",
+                        f"Source: {row.choice.source}",
+                    ]
+                )
+            )
             self.set_status(context_hint(row))
         elif isinstance(row, StreamRow):
             mark_active_row(event.list_view, row)
@@ -2282,12 +2294,13 @@ class PlexTuiApp(App[None]):
 
     def show_error(self, text: str) -> None:
         config_hint = f"Config: {config_path()}"
+        recovery_hint = "Use Settings > Plex > Relogin with Plex to try another server URL."
         self.set_status(f"Error: {text}")
         self.set_media_title("Error")
         view = self.show_media_list()
         view.clear()
-        view.append(ListItem(Label(f"{text}\n{config_hint}")))
-        self.show_detail_text(config_hint)
+        view.append(ListItem(Label(f"{text}\n{config_hint}\n{recovery_hint}")))
+        self.show_detail_text(f"{config_hint}\n{recovery_hint}")
 
     def show_playback_error(self, text: str) -> None:
         self.detail_refresh_token += 1
@@ -2481,7 +2494,7 @@ def render_media_grid_card(
     title_style = "bold #e5a00d" if selected else "bold"
     card_width = grid_card_width(config)
     title = grid_card_text(media.title, config)
-    subtitle = grid_card_text("  ".join(bit for bit in (media.kind, media.subtitle) if bit), config)
+    subtitle = grid_card_text("  ".join(bit for bit in (kind_label(media.kind), media.subtitle) if bit), config)
     artwork = artwork_overrides.get(media.key) if artwork_overrides is not None else None
     artwork = copy_renderable(artwork)
     if artwork is None: