fix(hardening): corrections found by running against a real Tunarr and Plex

The previous three commits were verified by tests only. Running them against a
live 156-channel Tunarr (v1.3.13) and a real Plex found two things tests could
not have caught, because both depend on the shape of actual data and on how a
real Plex server is configured.

Backups were 151 MB each
  A real snapshot of 156 channels is 20,567 programs of full metadata — 151 MB
  uncompressed. At the retention of 10 I'd picked, that's 1.5 GB quietly
  accumulating in a user's data directory, which on a NAS is a genuine problem
  and precisely the kind of thing a "safety net" should not cause.

  Backups are now gzipped: 151 MB -> 12 MB (10.2x) in about 1.4s of compression,
  and retention drops from 10 to 3. ~36 MB total instead of 1.5 GB. The measured
  numbers are recorded in the code comment and CLAUDE.md so nobody raises either
  value without re-measuring. Dropped the indent= while here — the file is read
  by a restore, not a human.

  Verified end to end against the live server: 156 channels, 20,567 programs,
  12.0 MB, reads back cleanly from gzip with all programming intact.

A wrong Plex token passed the connection test
  check_plex reported ok:True for the literal token "garbage". Not a code bug —
  this Plex has "Allow unauthenticated access on the local network" enabled, so
  every local request succeeds even with NO token at all. That's a common
  self-hosted configuration, which makes it a common false green: onboarding
  would bless a wrong token and the user would hit the failure much later.

  check_plex now does one extra tokenless request when the first succeeds. If
  that also succeeds, the token was not the reason we got in, and the result
  carries token_unverified + an explanatory note. The onboarding alert renders
  yellow rather than green in that case. Programmarr can still read the library
  either way, so this is a caveat, not a failure — but claiming the token was
  validated when it demonstrably wasn't is the kind of small dishonesty that
  costs trust later.

Also:
  - .gitignore now covers tunarr_backup_* at the project ROOT. data/* already
    covered the Docker path, but CLI runs write to the working directory, so a
    12 MB snapshot was one `git add -A` away from being committed.
  - README gains a Backups section documenting where snapshots go, how big they
    are, how long they're kept, and how to unzip one. A safety net nobody knows
    how to use is not a safety net. States plainly there's no restore command
    yet, rather than implying one exists.

Verified against real infrastructure, all read-only (nothing deployed, nothing
deleted): Tunarr 1.3.13 detected via /api/version; all four required endpoints
answer 200; build_library_index returned 4100 movies + 401 shows across 4 Plex
sources; create.py --probe resolved all 59 channels with content.

345 tests pass. Still unproven: Tunarr basic auth end-to-end, since this Tunarr
has auth disabled — the header is sent, but nothing has enforced it.

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

Author: AlpineArchitecture

.gitignore

@@ -2,6 +2,10 @@
 config.json
 config*.json
 channels.json
+# Pre-delete Tunarr lineup snapshots. ~12 MB each on a 156-channel server, and
+# CLI runs write them to the project root (Docker writes them under data/).
+tunarr_backup_*.json
+tunarr_backup_*.json.gz
 channels*.json
 *.csv
 backup_*.json

CLAUDE.md

@@ -165,7 +165,7 @@ and the code — don't restate them here.
 - **`channel_blocks.py`** — shared, **pure, importable** channel-numbering logic (no `config.json`/argv). `assign_numbers(order, counts, start)` packs categories tight sequentially; `resolve_order(configured)` validates/fills the configured order against `CANONICAL_ORDER`. Single source of truth for compose, the LLM prompt, and `generate_no_ai`. **Must stay in the Dockerfile `COPY` line.**
 - **`generate_from_collections.py`** — one channel per Plex collection via `{"collection":"Name"}`. Manages the collection block (default ch 80+): keeps everything below `--base`, regenerates from `--base` up. Re-run any time Kometa changes collections.
 - **`channel_engine.py`** — shared, **pure, importable** resolution engine (no `config.json`/argv/`sys.exit`), so it's safe to import into the long-lived FastAPI process. Holds the resolution helpers, franchise `match_titles` (word-boundary), and the in-place live-channel updaters (`read_channel_programming`, `update_channel_in_place`). Imported by `create.py` at runtime and in-process by `recipes_router.py` — **must stay in the Dockerfile `COPY` line**. `build_library_index` indexes **all** enabled movie and shows libraries (not just the first — a Plex server can expose several, e.g. `TV Shows` + `Cartoons`), and indexes a show that appears in more than one library **once**, preferring the copy with the most playable (non-`missing`) episodes so a dead duplicate can't shadow the real one or inflate the live-diff into churn. Tunarr auth lives here as module state (`set_tunarr_auth` / `set_tunarr_auth_from_config` / `tunarr_headers`) rather than a parameter on ~20 functions — callers pass the values in, so the no-`config.json` rule still holds; **every** caller that loads a config must call `set_tunarr_auth_from_config(cfg)` before hitting Tunarr. `build_library_index` distinguishes a **failed** library fetch from an **empty** one: all libraries failing raises rather than returning an empty index (which would otherwise deploy channels with no content); a partial failure warns and continues.
-- **`create.py`** — thin CLI wrapper around `channel_engine`. Reads `channels.json`, indexes the Tunarr library (case-insensitive exact title match), and deploys (delete-then-create; `--from N` scopes, `--protect N1,N2` preserves specific channels). Builds 30-day rolling random schedules (no dead air). The delete/recreate path is **initial-deploy only** — never for live channels. Before any destructive delete it writes a timestamped `tunarr_backup_*.json` (channel + raw `/programming` payload, last 10 kept) — the only way back from a wipe of a lineup Programmarr didn't create. Probe runs never write one.
+- **`create.py`** — thin CLI wrapper around `channel_engine`. Reads `channels.json`, indexes the Tunarr library (case-insensitive exact title match), and deploys (delete-then-create; `--from N` scopes, `--protect N1,N2` preserves specific channels). Builds 30-day rolling random schedules (no dead air). The delete/recreate path is **initial-deploy only** — never for live channels. Before any destructive delete it writes a timestamped **gzipped** `tunarr_backup_*.json.gz` (channel + raw `/programming` payload, last **3** kept) — the only way back from a wipe of a lineup Programmarr didn't create. Probe runs never write one. **Measured on a real 156-channel Tunarr: 151 MB raw, 12 MB gzipped, ~20s** — that measurement is why it's compressed and why retention is 3, not 10; don't raise either without re-measuring.
 - **`fetch_images.py`** — sets every channel's Tunarr icon. Verified TMDB logos for
   solo-title/marathon/franchise/network/studio channels (the result's name must match the
   query after normalization — never `results[0]`); generated badge art for every other kind

README.md

@@ -64,8 +64,8 @@ First run shows an onboarding wizard — create a login, enter your Tunarr and P
 
 > **Heads up on your first deploy.** Programmarr's default deploy mode replaces the channels it
 > manages. If you already have a hand-built Tunarr lineup, use **Add/Edit** mode rather than
-> **Nuke**. Either way, Programmarr writes a `tunarr_backup_*.json` snapshot into your data
-> directory before deleting anything.
+> **Nuke**. Either way, Programmarr snapshots your existing lineup before deleting anything —
+> see [Backups](#backups) below.
 
 ### TrueNAS
 
@@ -228,6 +228,32 @@ It ships **off**. Turn it on in **Settings → Live Channels**, flip the **"Auto
 
 ---
 
+## Backups
+
+Before Programmarr deletes any Tunarr channel, it writes a compressed snapshot of everything
+it's about to remove — each channel plus its full programming — to your data directory:
+
+```
+data/tunarr_backup_20260819T195358Z.json.gz
+```
+
+On a 156-channel server that's about 12 MB and takes ~20 seconds. The **3 most recent** are
+kept; older ones are removed automatically. Probe/dry runs never write one.
+
+**This is a safety net, not a feature** — there's no restore button yet. If you need to go
+back, the file is plain JSON once unzipped, containing everything Tunarr's API needs:
+
+```bash
+gunzip -c data/tunarr_backup_20260819T195358Z.json.gz > lineup.json
+```
+
+Each entry has the original `channel` object (including its Tunarr `id`) and the raw
+`programming` payload. If you ever need to recover a lineup, open an
+[issue](https://github.com/AlpineArchitecture/programmarr/issues) with that file's structure
+and I'll help — and if it happens to anyone, a proper restore command moves to the top of the list.
+
+---
+
 ## Configuration
 
 Everything is set through the UI. Config is stored in `./data/config.json` (bind-mounted, never baked into the image).

backend/routers/status_router.py

@@ -116,9 +116,25 @@ def check_plex(url: str, token: str) -> dict:
         return {"ok": False, "error": "No Plex URL given"}
     if not token:
         return {"ok": False, "error": "No Plex token given"}
-    # /library/sections proves the token works AND that there's a library to read,
-    # which is what Programmarr actually needs — a bare / accepts any token.
+    # /library/sections proves we can read the library, which is what Programmarr
+    # actually needs — a bare / accepts any token.
     result = {**probe(f"{url}/library/sections?X-Plex-Token={token}"), "url": url}
+
+    if result.get("ok"):
+        # Many self-hosted Plex servers have "Allow unauthenticated access on the
+        # local network" on, which makes EVERY local request succeed — including
+        # one with a garbage token. Reporting that as "token valid" would be a
+        # false green. One extra request tells us whether the token was actually
+        # the reason we got in.
+        no_token = probe(f"{url}/library/sections")
+        if no_token.get("ok"):
+            result["token_unverified"] = True
+            result["note"] = (
+                "Your Plex allows unauthenticated access from this network, so the "
+                "token itself could not be verified. Programmarr can read your "
+                "library either way — but double-check the token if you later "
+                "restrict local access."
+            )
     return result
 
 

backend/tests/test_connection_check.py

@@ -115,3 +115,39 @@ def _f(req, timeout=None):
 
     sr.check_plex("http://plex:32400", "tok")
     assert "/library/sections" in seen["url"]
+
+
+# ── LAN-permissive Plex: a green result that can't vouch for the token ────────
+
+def test_lan_permissive_plex_flags_unverified_token(monkeypatch):
+    """Many self-hosted Plex servers allow unauthenticated local access, so EVERY
+    local request succeeds — including one with a garbage token. Found on a real
+    server: check_plex returned ok for the string 'garbage'. Reporting that as a
+    validated token is a false green."""
+    monkeypatch.setattr(sr.urllib.request, "urlopen", urlopen_returning(200))
+
+    out = sr.check_plex("http://plex:32400", "garbage")
+    assert out["ok"] is True          # Programmarr CAN read the library
+    assert out["token_unverified"] is True
+    assert "could not be verified" in out["note"]
+
+
+def test_locked_down_plex_does_verify_the_token(monkeypatch):
+    """When Plex actually enforces the token, a successful call means something —
+    no caveat should be attached."""
+    def _f(req, timeout=None):
+        if "X-Plex-Token" not in req.full_url:
+            raise http_error(401)
+        return FakeResp(200)
+    monkeypatch.setattr(sr.urllib.request, "urlopen", _f)
+
+    out = sr.check_plex("http://plex:32400", "good-token")
+    assert out["ok"] is True
+    assert "token_unverified" not in out
+    assert "note" not in out
+
+
+def test_bad_token_on_a_locked_down_plex_fails(monkeypatch):
+    monkeypatch.setattr(sr.urllib.request, "urlopen", urlopen_raising(http_error(401)))
+    out = sr.check_plex("http://plex:32400", "bad")
+    assert out["ok"] is False

backend/tests/test_delete_backup.py

@@ -7,6 +7,7 @@
 the first DELETE goes out. Probe runs must never write one.
 """
 
+import gzip
 import json
 import sys
 from pathlib import Path
@@ -48,10 +49,11 @@ def test_backup_written_before_delete(tmp_path, monkeypatch):
 
     create.delete_channels("http://tunarr", probe=False)
 
-    backups = list(tmp_path.glob("tunarr_backup_*.json"))
+    backups = list(tmp_path.glob("tunarr_backup_*.json.gz"))
     assert len(backups) == 1, "a destructive delete must leave exactly one snapshot"
 
-    data = json.loads(backups[0].read_text(encoding="utf-8"))
+    with gzip.open(backups[0], "rt", encoding="utf-8") as fh:
+        data = json.load(fh)
     assert len(data["channels"]) == 2
     names = {c["channel"]["name"] for c in data["channels"]}
     assert names == {"Sitcom Marathon", "80s Action"}
@@ -71,7 +73,7 @@ def test_probe_writes_no_backup(tmp_path, monkeypatch):
 
     create.delete_channels("http://tunarr", probe=True)
 
-    assert not list(tmp_path.glob("tunarr_backup_*.json"))
+    assert not list(tmp_path.glob("tunarr_backup_*.json.gz"))
     assert not [c for c in calls if c[0] == "DELETE"]
 
 
@@ -96,9 +98,9 @@ def test_rotation_keeps_last_n(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     monkeypatch.setattr(create, "BACKUP_KEEP", 3)
     for i in range(5):
-        (tmp_path / f"tunarr_backup_2020010{i}T000000Z.json").write_text("{}", encoding="utf-8")
+        (tmp_path / f"tunarr_backup_2020010{i}T000000Z.json.gz").write_text("{}", encoding="utf-8")
     monkeypatch.setattr(create, "api", fake_api([]))
 
     create.backup_channels("http://tunarr", CHANNELS)
 
-    assert len(list(tmp_path.glob("tunarr_backup_*.json"))) == 3
+    assert len(list(tmp_path.glob("tunarr_backup_*.json.gz"))) == 3

create.py

@@ -14,6 +14,7 @@
 
 import argparse
 import glob
+import gzip
 import json
 import os
 import sys
@@ -52,7 +53,12 @@ def load_config():
 
 # ── Destructive-op backup ──────────────────────────────────────────────────────
 
-BACKUP_KEEP = 10
+# Measured on a real 156-channel Tunarr: the uncompressed snapshot was 151 MB
+# (full program metadata for ~1000 programs per channel). Ten of those would put
+# 1.5 GB in a user's data directory, so backups are gzipped (10x, ~1.4s) and we
+# keep fewer of them. 3 x ~15 MB is a safety net; 10 x 151 MB is a disk problem.
+BACKUP_KEEP = 3
+BACKUP_GLOB = "tunarr_backup_*.json.gz"
 
 
 def backup_channels(tunarr_url, channels):
@@ -77,21 +83,23 @@ def backup_channels(tunarr_url, channels):
             snapshot.append(entry)
 
         ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-        path = f"tunarr_backup_{ts}.json"
-        with open(path, "w", encoding="utf-8") as f:
+        path = f"tunarr_backup_{ts}.json.gz"
+        # No indent: this file is read by a restore, not by a human, and pretty
+        # printing 150 MB of JSON buys nothing.
+        with gzip.open(path, "wt", encoding="utf-8") as f:
             json.dump({"saved_at": ts, "tunarr_url": tunarr_url,
-                       "channels": snapshot}, f, indent=2)
+                       "channels": snapshot}, f)
 
         # ponytail: keep the last N by filename (timestamps sort lexically); no
         # rotation config until someone asks for one.
-        old = sorted(glob.glob("tunarr_backup_*.json"))[:-BACKUP_KEEP]
-        for stale in old:
+        for stale in sorted(glob.glob(BACKUP_GLOB))[:-BACKUP_KEEP]:
             try:
                 os.remove(stale)
             except OSError:
                 pass
 
-        print(f"  Backed up {len(snapshot)} channels -> {os.path.abspath(path)}")
+        size_mb = os.path.getsize(path) / 1e6
+        print(f"  Backed up {len(snapshot)} channels ({size_mb:.1f} MB) -> {os.path.abspath(path)}")
         return path
     except Exception as e:
         print(f"  ! WARNING: could not write pre-delete backup: {e}")

docs/api.md

@@ -10,7 +10,7 @@ change; don't restate it back into `CLAUDE.md`.
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/status` | Connection status: `{tunarr:{ok,url,error?}, plex:{ok,url,error?}}` for the **saved** config. An HTTP error is `ok:false` — a 401 from an auth-protected Tunarr is a failure, not a healthy server |
-| POST | `/api/test-connection` | Body `{tunarr_url, tunarr_username, tunarr_password, plex_url, plex_token}`. Tests credentials the user has typed but has **not saved** — this is what lets Onboarding refuse to green-light a typo. Only the sides supplied are tested. A secret sent as the mask falls back to the stored value. Never leaves the tested credential applied to the process |
+| POST | `/api/test-connection` | Body `{tunarr_url, tunarr_username, tunarr_password, plex_url, plex_token}`. Tests credentials the user has typed but has **not saved** — this is what lets Onboarding refuse to green-light a typo. Only the sides supplied are tested. A secret sent as the mask falls back to the stored value. Never leaves the tested credential applied to the process. Plex results may carry `token_unverified: true` + a `note` when the server allows unauthenticated local access — the library is readable but the token itself was not proven |
 | GET | `/api/guide` | Fetch and parse Tunarr's XMLTV feed. Returns `{channels:[{number,name,icon?}], programmes:[{number,start,stop,title,episode?}], error?}`. Channels sorted by number; timestamps as ISO 8601. Never throws — returns `error` field on failure. |
 | GET | `/api/tunarr/channels` | Live channel list from Tunarr: `[{number,name,id?}]` |
 | GET | `/api/tunarr/filler-lists` | Filler lists in Tunarr: `[{id,name,contentCount}]` — powers the Commercials picker |

frontend/src/api/client.ts

@@ -172,7 +172,14 @@ export const api = {
 // ── Types ──────────────────────────────────────────────────────────────────────
 
 export interface PlexServer { name: string; url: string; token: string }
-export interface ConnStatus { ok: boolean; url: string; error?: string }
+export interface ConnStatus {
+  ok: boolean; url: string; error?: string;
+  version?: string | null;
+  // Set when Plex let us in WITHOUT a token (LAN-permissive server), so a
+  // green result does not actually vouch for the token.
+  token_unverified?: boolean;
+  note?: string;
+}
 export interface UpdateInfo {
   enabled: boolean;
   update_available?: boolean;

frontend/src/pages/Onboarding.tsx

@@ -313,7 +313,7 @@ export default function Onboarding({ onComplete }: Props) {
                     return (
                       <Alert
                         key={k}
-                        color={r.ok ? 'green' : 'red'}
+                        color={!r.ok ? 'red' : r.note ? 'yellow' : 'green'}
                         icon={r.ok ? <IconCheck size={16} /> : <IconAlertTriangle size={16} />}
                         p="xs"
                       >
@@ -323,6 +323,9 @@ export default function Onboarding({ onComplete }: Props) {
                         {!r.ok && r.error && (
                           <Text size="xs" c="dimmed">{r.error}</Text>
                         )}
+                        {r.ok && r.note && (
+                          <Text size="xs" c="dimmed">{r.note}</Text>
+                        )}
                       </Alert>
                     );
                   })}