fix(meta): self-heal stale NFOs with ASCII-mangled original titles

Non-ASCII original titles (Malayalam/Tamil/Hindi scripts) were written as
a run of '?' by an earlier writer and never repaired: the enrichment
idempotency gate treated any existing NFO as cached and the movie/episode
NFO writes were guarded by os.path.exists. Now:

- nfo_needs_repair() flags any NFO whose originaltitle/original_name is a
run of '?'); such NFOs are excluded from the idempotency gate and are
rewritten on the next enrich pass
- movie/episode NFO writes are unconditional when a fresh detail was
fetched (self-healing), tvshow.nfo rewrites when malformed
- streamer launched with PYTHONUTF8=1 PYTHONIOENCODING=utf-8

apex/apex_stream/tmdb_meta.py

@@ -29,6 +29,24 @@ TPL_BASE = "https://image.tmdb.org/t/p"
 
 YEAR_RE = re.compile(r"\b(19|20)\d{2}\b")
 
+_NFO_BAD_TITLE_RE = re.compile(
+    r"<\s*(?:originaltitle|original_name)\s*>[^<]*\?{2,}[^<]*<", re.IGNORECASE
+)
+
+
+def nfo_needs_repair(nfo_path) -> bool:
+    """True when an existing NFO's original title looks malformed (non-ASCII
+    script collapsed into a run of '?'), so enrichment re-fetches and rewrites
+    it instead of treating the NFO as already-cached."""
+    if not nfo_path or not os.path.isfile(nfo_path):
+        return False
+    try:
+        with open(nfo_path, "r", encoding="utf-8", errors="replace") as fh:
+            text = fh.read(0x4000)
+    except OSError:
+        return False
+    return bool(_NFO_BAD_TITLE_RE.search(text))
+
 # TV patterns, in priority order. All return (show_name, season, episode) or None.
 _SX_E = re.compile(r"(?i)\bS(\d{1,2})\s*(?:\.|\s|_|-)+\s*E(\d{1,3})\b")
 _SX_EX = re.compile(r"(?i)\bS(\d{1,2})\s*E(\d{1,3})\b")

apex/combined-entrypoint.sh

@@ -185,7 +185,7 @@ sync_jellyfin_back &
 SYNC_PID=$!
 
 echo "[HEALTH] Telegram streamer starting in background..."
-python3 /opt/apex/tg_streamer.py &
+PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python3 /opt/apex/tg_streamer.py &
 TG_STREAMER_PID=$!
 
 echo "[HEALTH] FastAPI Gateway starting..."
@@ -213,7 +213,7 @@ while true; do
 
     if [ -n "$TG_STREAMER_PID" ] && ! kill -0 $TG_STREAMER_PID 2>/dev/null; then
         echo "[CRITICAL] TG Streamer process died! Restarting..."
-        python3 /opt/apex/tg_streamer.py &
+        PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python3 /opt/apex/tg_streamer.py &
         TG_STREAMER_PID=$!
     fi
 

apex/entrypoint.sh

@@ -153,7 +153,7 @@ sync_jellyfin_back &
 SYNC_PID=$!
 
 echo "[HEALTH] Telegram streamer starting in background..."
-python3 /tg_streamer.py &
+PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python3 /tg_streamer.py &
 TG_STREAMER_PID=$!
 
 echo "[HEALTH] FastAPI Gateway starting..."
@@ -181,7 +181,7 @@ while true; do
 
     if [ -n "$TG_STREAMER_PID" ] && ! kill -0 $TG_STREAMER_PID 2>/dev/null; then
         echo "[CRITICAL] TG Streamer process died! Restarting..."
-        python3 /tg_streamer.py &
+        PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python3 /tg_streamer.py &
         TG_STREAMER_PID=$!
     fi
 

apex/tests/test_tmdb_meta.py

@@ -7,6 +7,7 @@ from apex_stream.tmdb_meta import (
     build_episode_nfo,
     build_movie_nfo,
     build_tvshow_nfo,
+    nfo_needs_repair,
     parse_media_meta,
     tmdb_image_url,
 )
@@ -298,4 +299,33 @@ class TestNfoBuilders:
 
     def test_image_url(self):
         assert tmdb_image_url("/abc123.jpg") == "https://image.tmdb.org/t/p/w500/abc123.jpg"
-        assert tmdb_image_url(None) is None
+        assert tmdb_image_url(None) is None
+
+
+class TestNfoRepair:
+    def test_healthy_nfo_is_not_flagged(self, tmp_path):
+        nfo = tmp_path / "movie.nfo"
+        nfo.write_text(
+            '<movie><title>Mollywood Times</title><originaltitle>മോളിവുഡ് ടൈംസ്</originaltitle></movie>',
+            encoding="utf-8",
+        )
+        assert nfo_needs_repair(str(nfo)) is False
+
+    def test_malformed_originaltitle_is_flagged(self, tmp_path):
+        nfo = tmp_path / "movie.nfo"
+        nfo.write_text(
+            '<movie><title>Mollywood Times</title><originaltitle>?????</originaltitle></movie>',
+            encoding="utf-8",
+        )
+        assert nfo_needs_repair(str(nfo)) is True
+
+    def test_malformed_tvshow_original_name_is_flagged(self, tmp_path):
+        nfo = tmp_path / "tvshow.nfo"
+        nfo.write_text(
+            '<tvshow><name>Test</name><original_name>??????</original_name></tvshow>',
+            encoding="utf-8",
+        )
+        assert nfo_needs_repair(str(nfo)) is True
+
+    def test_missing_file_not_flagged(self, tmp_path):
+        assert nfo_needs_repair(str(tmp_path / "nope.nfo")) is False

apex/tg_streamer.py

@@ -48,6 +48,7 @@ from apex_stream.tmdb_meta import (
     build_episode_nfo,
     build_movie_nfo,
     build_tvshow_nfo,
+    nfo_needs_repair,
     parse_media_meta,
 )
 
@@ -1045,14 +1046,16 @@ async def _download_image(session, url, save_path):
     return False
 
 
+def _nfo_needs_repair(nfo_path):
+    """True when an existing NFO's original title looks malformed (non-ASCII
+    script collapsed into a run of '?'), so enrichment re-fetches and rewrites
+    it instead of treating the NFO as cached."""
+    return nfo_needs_repair(nfo_path)
+
+
 async def _enrich_media_metadata(entry):
     """Fetch full TMDB details for a cache entry and write nfo + poster/backdrop.
 
-    Writes:
-      - movies: <target_dir>/{strm_base}.nfo + poster.jpg + backdrop.jpg
-      - tv:     <show_root>/tvshow.nfo + <show_root>/poster.jpg + <show_root>/backdrop.jpg
-                + <target_dir>/{strm_base}.nfo (episodedetails)
-
     Idempotent: skips when the .nfo + poster already exist so restarts don't
     hammer the API. Updates the cache entry's tmdb_id/tmdb fields.
     """
@@ -1068,15 +1071,19 @@ async def _enrich_media_metadata(entry):
             return False
 
         # Idempotency gate: if the metadata is already on disk, avoid re-hitting
-        # the TMDB API on every restart.
+        # the TMDB API on every restart. A malformed NFO (e.g. non-ASCII
+        # original titles written as a run of '?') is NOT treated as cached so
+        # it gets re-fetched and repaired.
         if is_tv and show_root:
-            if os.path.exists(os.path.join(show_root, "tvshow.nfo")) and os.path.exists(os.path.join(show_root, "poster.jpg")):
+            tv_nfo = os.path.join(show_root, "tvshow.nfo")
+            if os.path.exists(tv_nfo) and os.path.exists(os.path.join(show_root, "poster.jpg")) and not _nfo_needs_repair(tv_nfo):
                 return True
         elif not is_tv:
             movie_nfo = os.path.join(
                 target_dir, f"{entry.get('strm_base', strm_base(entry))}.nfo"
             )
-            if os.path.exists(movie_nfo) and os.path.exists(os.path.join(target_dir, "poster.jpg")):
+            if (os.path.exists(movie_nfo) and os.path.exists(os.path.join(target_dir, "poster.jpg"))
+                    and not _nfo_needs_repair(movie_nfo)):
                 return True
 
         query = entry.get("search_title") or entry.get("show_name") or entry.get("title")
@@ -1259,7 +1266,7 @@ async def _enrich_media_metadata(entry):
                 nfo_path = os.path.join(show_root, "tvshow.nfo")
                 poster_path = os.path.join(show_root, "poster.jpg")
                 backdrop_path = os.path.join(show_root, "backdrop.jpg")
-                if not os.path.exists(nfo_path):
+                if not os.path.exists(nfo_path) or _nfo_needs_repair(nfo_path):
                     with open(nfo_path, "w", encoding="utf-8") as f:
                         f.write(build_tvshow_nfo(detail))
                 poster_url = _best_image("poster_path")
@@ -1288,16 +1295,14 @@ async def _enrich_media_metadata(entry):
                             break
                     if ep_detail:
                         ep_nfo = os.path.join(target_dir, f"{entry.get('strm_base', strm_base(entry))}.nfo")
-                        if not os.path.exists(ep_nfo):
-                            with open(ep_nfo, "w", encoding="utf-8") as f:
-                                f.write(build_episode_nfo(ep_detail))
+                        with open(ep_nfo, "w", encoding="utf-8") as f:
+                            f.write(build_episode_nfo(ep_detail))
             else:
                 nfo_path = os.path.join(
                     target_dir, f"{entry.get('strm_base', strm_base(entry))}.nfo"
                 )
-                if not os.path.exists(nfo_path):
-                    with open(nfo_path, "w", encoding="utf-8") as f:
-                        f.write(build_movie_nfo(detail))
+                with open(nfo_path, "w", encoding="utf-8") as f:
+                    f.write(build_movie_nfo(detail))
                 poster_url = _best_image("poster_path")
                 if poster_url and not os.path.exists(os.path.join(target_dir, "poster.jpg")):
                     await _download_image(session, _resize_tmdb_image(poster_url), os.path.join(target_dir, "poster.jpg"))