Add TV series support, stalled-download retry, and i18n

Movies and TV series are now searched together (or separately via /film and
/serie), with season/episode selection, dual-title indexer search (original
and localized title), and a manual override for shows TMDB miscounts.
Downloads stuck at 0 seeders for 2 hours are flagged with a button to stop
and retry. Bot messages are now bilingual (BOT_LANGUAGE=en/it) with English
aliases for every command, and MEDIA_ROOT_FOLDER/MEDIA_TV_ROOT_FOLDER are now
required instead of silently defaulting to a path that may not exist.

Author: FirstGameLife

src/main/java/com/cineseekerr/bot/bot/ConversationHandler.java

@@ -7,20 +7,29 @@
 import com.cineseekerr.bot.model.ReleaseSource;
 import com.cineseekerr.bot.model.Resolution;
 import com.cineseekerr.bot.model.SearchResult;
-import com.cineseekerr.bot.model.TmdbMovie;
+import com.cineseekerr.bot.model.TmdbTitle;
 import com.cineseekerr.bot.model.VideoCodec;
+import org.springframework.stereotype.Component;
 
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
 import java.util.stream.Collectors;
 
-/** Builds the HTML texts the bot sends. All user-controlled content goes through {@link #esc}. */
-public final class MessageFormatter {
+/**
+ * Builds the HTML texts the bot sends, in the language configured via
+ * {@link Messages}. All user-controlled content goes through {@link #esc}.
+ */
+@Component
+public class MessageFormatter {
 
     static final String[] NUMBER_EMOJI = {"1️⃣", "2️⃣", "3️⃣", "4️⃣", "5️⃣"};
 
-    private MessageFormatter() {
+    private final Messages messages;
+
+    public MessageFormatter(Messages messages) {
+        this.messages = messages;
     }
 
     public static String esc(String text) {
@@ -30,19 +39,25 @@ public static String esc(String text) {
                 .replace(">", ">");
     }
 
-    static String movieLabel(TmdbMovie movie) {
-        return movie.year() == null ? movie.title() : movie.title() + " (" + movie.year() + ")";
+    static String titleLabel(TmdbTitle title) {
+        return title.year() == null ? title.title() : title.title() + " (" + title.year() + ")";
+    }
+
+    /** 📺 for TV series, 🎬 for movies. */
+    static String icon(TmdbTitle title) {
+        return title.isTv() ? "📺" : "🎬";
     }
 
-    static String candidatesText(List<TmdbMovie> candidates) {
-        StringBuilder sb = new StringBuilder("🎬 <b>Quale film intendi?</b>\n\n");
+    String candidatesText(List<TmdbTitle> candidates) {
+        StringBuilder sb = new StringBuilder(messages.get("candidates.header")).append("\n\n");
         for (int i = 0; i < candidates.size(); i++) {
-            TmdbMovie movie = candidates.get(i);
-            sb.append(NUMBER_EMOJI[i]).append(' ').append("<b>").append(esc(movieLabel(movie))).append("</b>");
-            if (movie.posterUrl() != null) {
-                sb.append(" <a href=\"").append(movie.posterUrl()).append("\">🖼</a>");
+            TmdbTitle title = candidates.get(i);
+            sb.append(NUMBER_EMOJI[i]).append(' ').append(icon(title)).append(' ')
+                    .append("<b>").append(esc(titleLabel(title))).append("</b>");
+            if (title.posterUrl() != null) {
+                sb.append(" <a href=\"").append(title.posterUrl()).append("\">🖼</a>");
             }
-            String overview = movie.overview();
+            String overview = title.overview();
             if (overview != null && !overview.isBlank()) {
                 sb.append('\n').append("<i>").append(esc(truncate(overview, 120))).append("</i>");
             }
@@ -51,35 +66,43 @@ static String candidatesText(List<TmdbMovie> candidates) {
         return sb.toString().stripTrailing();
     }
 
-    static String qualityLabel(Resolution resolution) {
-        return resolution == Resolution.UNKNOWN ? "Altro" : resolution.label();
+    String qualityLabel(Resolution resolution) {
+        return resolution == Resolution.UNKNOWN ? messages.get("quality.other") : resolution.label();
     }
 
     static String subtitleLabel(Language language) {
         return "SUB " + language.label();
     }
 
-    /** e.g. {@code "2160p · ITA · SUB ITA"} or {@code "nessun filtro"}. */
-    static String filterRecap(ConversationState state) {
+    /** e.g. {@code "ITA · SUB ITA · 2160p"} (same order as the filter steps) or {@code "no filters"}. */
+    String filterRecap(ConversationState state) {
         List<String> parts = new ArrayList<>();
-        if (state.qualityFilter() != null) {
-            parts.add(qualityLabel(state.qualityFilter()));
-        }
         if (state.audioFilter() != null) {
             parts.add(state.audioFilter().label());
         }
         if (state.subtitleFilter() != null) {
             parts.add(subtitleLabel(state.subtitleFilter()));
         }
-        return parts.isEmpty() ? "nessun filtro" : String.join(" · ", parts);
+        if (state.qualityFilter() != null) {
+            parts.add(qualityLabel(state.qualityFilter()));
+        }
+        return parts.isEmpty() ? messages.get("recap.none") : String.join(" · ", parts);
     }
 
-    static String stepHeader(ConversationState state) {
-        return "🎬 <b>" + esc(movieLabel(state.movie())) + "</b> — "
-                + state.filtered().size() + " release (" + filterRecap(state) + ")\n\n";
+    String stepHeader(ConversationState state) {
+        String label = titleLabel(state.title());
+        if (state.season() != null) {
+            label += " — " + messages.get("recap.season", state.season());
+        }
+        if (state.episode() != null) {
+            label += " — " + messages.get("recap.episode", state.episode());
+        }
+        return icon(state.title()) + " <b>" + esc(label) + "</b> — "
+                + messages.get("step.header.releases", state.filtered().size(), filterRecap(state))
+                + "\n\n";
     }
 
-    static String releaseSummary(SearchResult result) {
+    String releaseSummary(SearchResult result) {
         ParsedRelease parsed = result.parsed();
         List<String> tech = new ArrayList<>();
         if (parsed.resolution() != Resolution.UNKNOWN) {
@@ -92,7 +115,7 @@ static String releaseSummary(SearchResult result) {
             tech.add(parsed.codec().label());
         }
         String audio = parsed.audioLanguages().isEmpty()
-                ? "audio ?"
+                ? messages.get("release.audio.unknown")
                 : parsed.audioLanguages().stream().map(Language::label).collect(Collectors.joining(" "));
         tech.add("🔊 " + audio);
         if (parsed.subtitled()) {
@@ -106,9 +129,9 @@ static String releaseSummary(SearchResult result) {
         return String.join(" · ", tech);
     }
 
-    static String shortlistText(ConversationState state) {
+    String shortlistText(ConversationState state) {
         StringBuilder sb = new StringBuilder(stepHeader(state))
-                .append("🎯 <b>Migliori release per seeders:</b>\n\n");
+                .append(messages.get("shortlist.header")).append("\n\n");
         List<SearchResult> shortlist = state.shortlist();
         for (int i = 0; i < shortlist.size(); i++) {
             SearchResult result = shortlist.get(i);
@@ -122,19 +145,19 @@ static String shortlistText(ConversationState state) {
                     .append("<code>").append(esc(truncate(result.release().title(), 80))).append("</code>")
                     .append("\n\n");
         }
-        sb.append("Quale scarico?");
+        sb.append(messages.get("shortlist.prompt"));
         return sb.toString();
     }
 
-    static String torrentStatusLine(QbtTorrent torrent) {
+    String torrentStatusLine(QbtTorrent torrent) {
         String name = truncate(torrent.name(), 60);
         if (torrent.isComplete()) {
-            return "✅ <b>" + esc(name) + "</b> — completato";
+            return messages.get("status.line.done", esc(name));
         }
         int percent = (int) Math.floor(torrent.progress() * 100);
         long speed = torrent.dlspeed() == null ? 0 : torrent.dlspeed();
-        return "⬇️ <b>" + esc(name) + "</b> — " + percent + "% ("
-                + humanSize(speed) + "/s, ETA " + humanEta(torrent.eta()) + ")";
+        return messages.get("status.line.progress", esc(name), String.valueOf(percent),
+                humanSize(speed), humanEta(torrent.eta()));
     }
 
     static String humanSize(long bytes) {
@@ -147,6 +170,14 @@ static String humanSize(long bytes) {
         return String.format(Locale.ROOT, "%.0f KB", bytes / 1024.0);
     }
 
+    /** e.g. {@code "2h 15m"} or {@code "40m"}. */
+    public static String humanDuration(Duration duration) {
+        long totalMinutes = Math.max(0, duration.toMinutes());
+        long hours = totalMinutes / 60;
+        long minutes = totalMinutes % 60;
+        return hours > 0 ? hours + "h " + minutes + "m" : minutes + "m";
+    }
+
     /** qBittorrent reports 8640000 seconds when the ETA is unknown. */
     static String humanEta(Long etaSeconds) {
         if (etaSeconds == null || etaSeconds >= 8_640_000L || etaSeconds < 0) {

src/main/java/com/cineseekerr/bot/bot/MessageFormatter.java

@@ -0,0 +1,37 @@
+package com.cineseekerr.bot.bot;
+
+import com.cineseekerr.bot.config.CineSeekerrProperties;
+import org.springframework.context.support.ResourceBundleMessageSource;
+import org.springframework.stereotype.Component;
+
+import java.util.Locale;
+
+/**
+ * Resolves the bot's user-facing texts from {@code messages*.properties} in the language
+ * configured via {@code BOT_LANGUAGE}. English ({@code messages.properties}) is the base
+ * bundle and the fallback for untranslated languages.
+ */
+@Component
+public class Messages {
+
+    private final ResourceBundleMessageSource source;
+    private final Locale locale;
+
+    public Messages(CineSeekerrProperties properties) {
+        this.source = new ResourceBundleMessageSource();
+        source.setBasename("messages");
+        source.setDefaultEncoding("UTF-8");
+        // never fall back to the JVM's locale: BOT_LANGUAGE is the only selector
+        source.setFallbackToSystemLocale(false);
+        this.locale = Locale.forLanguageTag(properties.language());
+    }
+
+    /**
+     * The text for {@code key}, with {@code {0}}-style placeholders replaced by
+     * {@code args}. Keys are static and kept in sync with the bundles, so a missing key is
+     * a programming error and throws.
+     */
+    public String get(String key, Object... args) {
+        return source.getMessage(key, args, locale);
+    }
+}

src/main/java/com/cineseekerr/bot/bot/Messages.java

@@ -1,5 +1,7 @@
 package com.cineseekerr.bot.bot.download;
 
+import com.cineseekerr.bot.model.TmdbTitle;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -13,6 +15,7 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
@@ -35,11 +38,18 @@ public class DownloadTracker {
     /**
      * @param chatId       chat to notify on completion
      * @param releaseTitle release name as reported by Prowlarr
-     * @param plexName     display name shown in notifications (e.g. "Title (Year)"); also
-     *                     the rename target
+     * @param plexName     display name shown in notifications (e.g. "Title (Year)" or
+     *                     "Show (Year) — Stagione 2"); also the rename target for movies
+     * @param tmdbTitle    the TMDB title this download is for, used to search again if the
+     *                     download stalls; {@code null} for entries tracked without one
+     * @param season       season number for a TV download; {@code null} for movies
+     * @param episode      episode number for a single-episode download; {@code null} for
+     *                     whole-season packs and movies
      * @param addedAt      when the download was queued, used to expire unmatched entries
      */
-    public record PendingDownload(long chatId, String releaseTitle, String plexName, Instant addedAt) {
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public record PendingDownload(long chatId, String releaseTitle, String plexName, TmdbTitle tmdbTitle,
+                                   Integer season, Integer episode, Instant addedAt) {
     }
 
     private final Map<String, PendingDownload> pending = new ConcurrentHashMap<>();
@@ -54,11 +64,22 @@ public DownloadTracker(ObjectMapper objectMapper,
     }
 
     public void track(long chatId, String releaseTitle, String plexName) {
-        track(chatId, releaseTitle, plexName, Instant.now());
+        track(chatId, releaseTitle, plexName, null, null, null, Instant.now());
     }
 
     public void track(long chatId, String releaseTitle, String plexName, Instant addedAt) {
-        pending.put(normalize(releaseTitle), new PendingDownload(chatId, releaseTitle, plexName, addedAt));
+        track(chatId, releaseTitle, plexName, null, null, null, addedAt);
+    }
+
+    public void track(long chatId, String releaseTitle, String plexName, TmdbTitle tmdbTitle, Integer season,
+                      Integer episode) {
+        track(chatId, releaseTitle, plexName, tmdbTitle, season, episode, Instant.now());
+    }
+
+    public void track(long chatId, String releaseTitle, String plexName, TmdbTitle tmdbTitle, Integer season,
+                      Integer episode, Instant addedAt) {
+        pending.put(normalize(releaseTitle),
+                new PendingDownload(chatId, releaseTitle, plexName, tmdbTitle, season, episode, addedAt));
         persist();
     }
 
@@ -71,6 +92,23 @@ public void remove(String key) {
         persist();
     }
 
+    /**
+     * Finds the pending download whose release title matches a qBittorrent torrent name —
+     * used to resolve the "retry search" button on a stalled-download notification, where
+     * only the torrent hash is available.
+     */
+    public Optional<Map.Entry<String, PendingDownload>> findByTorrentName(String torrentName) {
+        String normalized = normalize(torrentName);
+        if (normalized.isBlank()) {
+            return Optional.empty();
+        }
+        return pending.entrySet().stream()
+                .filter(e -> normalized.equals(e.getKey())
+                        || normalized.contains(e.getKey())
+                        || e.getKey().contains(normalized))
+                .findFirst();
+    }
+
     public boolean isEmpty() {
         return pending.isEmpty();
     }