First commit

Author: FirstGameLife

.dockerignore

@@ -0,0 +1,12 @@
+target/
+.git/
+.github/
+.idea/
+*.iml
+.mvn/
+mvnw
+mvnw.cmd
+docker-compose.yml
+README.md
+LICENSE
+.env

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+
+      - name: Build and test
+        run: |
+          chmod +x mvnw
+          ./mvnw -B verify
+
+      - name: Upload test reports on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: surefire-reports
+          path: target/surefire-reports/

.github/workflows/docker.yml

@@ -0,0 +1,44 @@
+name: Docker image
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            latest
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -0,0 +1,19 @@
+# Maven
+target/
+!.mvn/wrapper/maven-wrapper.jar
+
+# IDE
+.idea/
+*.iml
+.vscode/
+.settings/
+.classpath
+.project
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local environment (never commit secrets)
+.env
+*.local.yml

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,3 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip

Dockerfile

@@ -0,0 +1,22 @@
+# ---------- Build stage ----------
+FROM maven:3.9-eclipse-temurin-21 AS build
+WORKDIR /build
+
+# Cache dependencies separately from sources for fast rebuilds
+COPY pom.xml .
+RUN mvn -B -q dependency:go-offline
+
+COPY src ./src
+# Tests run in CI; the image build only packages
+RUN mvn -B -q package -DskipTests
+
+# ---------- Runtime stage ----------
+FROM eclipse-temurin:21-jre-alpine
+RUN addgroup -S cineseekerr && adduser -S cineseekerr -G cineseekerr
+USER cineseekerr
+WORKDIR /app
+
+COPY --from=build /build/target/cineseekerr-*.jar app.jar
+
+# Container-aware JVM sizing; the bot is tiny, keep the footprint small
+ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-jar", "app.jar"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emanuele Patruno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,161 @@
+# 🍿 CineSeekerr
+
+[![CI](https://github.com/Emanuele-Patruno/cineseekerr/actions/workflows/ci.yml/badge.svg)](https://github.com/Emanuele-Patruno/cineseekerr/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Java 21](https://img.shields.io/badge/Java-21-orange)
+![Spring Boot 3](https://img.shields.io/badge/Spring%20Boot-3.5-green)
+
+A self-hosted Telegram bot that turns *"hey, let's watch Dune tonight"* into a movie
+sitting in your Plex library — by chatting with it. It searches your
+[Prowlarr](https://prowlarr.com/) indexers, lets you pick quality/audio/subtitles through
+inline buttons, hands the torrent to [qBittorrent](https://www.qbittorrent.org/) and
+renames the finished download so [Plex](https://www.plex.tv/) matches it perfectly.
+
+No Radarr required — CineSeekerr talks Telegram instead of a web UI, in the same spirit as
+the `*arr` family (Radarr, Sonarr, Prowlarr) it plugs into. Designed for a small home NAS
+stack (built on a UGREEN DXP4800 Plus, but any Docker host works).
+
+<p align="center">
+  <img src="docs/screenshot-placeholder.png" alt="Bot conversation screenshot" width="380">
+  <br><em>(screenshot coming soon)</em>
+</p>
+
+## ✨ Features
+
+- **Movie disambiguation via TMDB** — type a title (even the localized one), pick the
+  right movie from up to 5 candidates with year and poster.
+- **Smart release parsing** — resolution, audio languages (incl. Italian scene tags like
+  `iTA-ENG`, `DLMux`, `BDMux`), subtitles (`SUB iTA`…), codec and source are extracted
+  from every release name.
+- **Dynamic filters, never a dead end** — filter buttons are built from the actual
+  results (`Quality: [1080p (14)] [2160p (6)] [720p (3)]`); an option leading to zero
+  results is never offered, and steps with a single option are skipped.
+- **MULTI-aware language filtering** — picking *ITA* also includes `MULTI`/`DUAL`
+  releases, which usually carry the Italian track.
+- **Top-5 by seeders** — with size, indexer and parsed details, one tap to download.
+- **Plex-ready renaming** — when the download completes the bot renames it to
+  `Title (Year)` *through the qBittorrent API*, so seeding continues and the bot needs no
+  access to the media volume.
+- **Private by default** — a chat-ID whitelist; anyone else is silently ignored.
+- **One clean message** — the bot edits a single message through the whole flow instead
+  of spamming the chat.
+
+## 🏗 Architecture
+
+```mermaid
+flowchart LR
+    U[Telegram user] <-->|long polling| B[CineSeekerr]
+    B -->|1. disambiguate| T[TMDB API]
+    B -->|2. search| P[Prowlarr]
+    P --> F[FlareSolverr]
+    B -->|3. add torrent + 5. rename| Q[qBittorrent]
+    Q -->|4. downloads to| M[/media/Film/]
+    X[Plex] -->|watches| M
+```
+
+The conversation is a per-chat state machine (`bot/`), external services live behind thin
+typed clients (`client/`), and the heart of the project is a pure, dependency-free release
+name parser (`parser/`) with an extensive test suite.
+
+```
+src/main/java/com/cineseekerr/bot/
+├── bot/        # state machine, filters, download watcher, Plex rename
+├── client/     # TMDB, Prowlarr, qBittorrent (Spring RestClient)
+├── config/     # typed configuration properties
+├── model/      # records: releases, torrents, parsed attributes
+└── parser/     # ReleaseNameParser — pure, no dependencies
+```
+
+## 🚀 Setup
+
+### Prerequisites
+
+A Docker host already running **Prowlarr** (with your indexers configured) and
+**qBittorrent**, sharing a Docker network. Plex and FlareSolverr fit the picture but the
+bot doesn't talk to them directly.
+
+### 1. Create the Telegram bot
+
+1. Open [@BotFather](https://t.me/BotFather) → `/newbot`, pick a name and username.
+2. Save the **token** (`123456789:AAF...`).
+3. Get your **chat ID** from [@userinfobot](https://t.me/userinfobot) (just send it any
+   message).
+
+### 2. Get the API keys
+
+- **TMDB**: create an account on [themoviedb.org](https://www.themoviedb.org/), then
+  *Settings → API*. Both the **v3 API Key** and the **v4 Read Access Token** work — the
+  bot auto-detects which one you gave it.
+- **Prowlarr**: *Settings → General → API Key*.
+
+### 3. Deploy
+
+Copy [docker-compose.yml](docker-compose.yml), fill in the environment variables, point
+the `networks` section at the Docker network your media stack uses, then:
+
+```bash
+docker compose up -d
+```
+
+Send `/start` to your bot. Done.
+
+## ⚙️ Configuration
+
+Everything is configured through environment variables:
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | ✅ | — | Bot token from BotFather |
+| `TELEGRAM_ALLOWED_CHAT_IDS` | ✅ | — | Comma-separated whitelist of chat IDs; all other chats are ignored |
+| `TMDB_API_KEY` | ✅ | — | TMDB v3 API key **or** v4 Read Access Token |
+| `TMDB_LANGUAGE` | | `it-IT` | Language for titles and plots shown in chat |
+| `TMDB_BASE_URL` | | `https://api.themoviedb.org/3` | Override for proxies |
+| `PROWLARR_URL` | ✅ | — | e.g. `http://prowlarr:9696` (container name on the shared network) |
+| `PROWLARR_API_KEY` | ✅ | — | Prowlarr API key |
+| `QBITTORRENT_URL` | ✅ | — | e.g. `http://qbittorrent:8080` |
+| `QBITTORRENT_USER` | ✅ | — | qBittorrent WebUI username |
+| `QBITTORRENT_PASS` | ✅ | — | qBittorrent WebUI password |
+| `MEDIA_ROOT_FOLDER` | | `/volume1/media/Film` | Save path **as seen by the qBittorrent container** |
+| `DOWNLOAD_POLL_INTERVAL` | | `PT30S` | How often to check for completed downloads (ISO-8601) |
+
+## 💬 Commands
+
+| Command | Effect |
+|---|---|
+| *any text* | Search that movie title |
+| `/cerca <title>` | Same as typing the title |
+| `/stato` | Progress of active downloads (%, speed, ETA), each with a button to stop it |
+| `/annulla` | Cancel the current operation |
+| `/help` | Command list |
+
+## 🛠 Development
+
+```bash
+./mvnw verify          # build + full test suite
+./mvnw spring-boot:run # run locally (reads the same env variables)
+docker build -t cineseekerr .
+```
+
+The project intentionally keeps the parser (`ReleaseNameParser`) pure and framework-free:
+if you want to improve scene-name coverage, that class plus its ~50-case test suite is
+the only place to touch.
+
+Notable test coverage: 130+ tests including the full conversation flow (mocked Telegram),
+qBittorrent session expiry/re-login, dynamic filter invariants ("never offer a
+zero-result option") and 45+ real-world release names.
+
+## 🗺 Roadmap
+
+- [ ] Redis-backed conversation state (interface already in place)
+- [ ] Persist pending downloads across restarts
+- [ ] TV series support
+- [ ] Disk space check before downloading
+- [ ] Optional per-user quality profiles
+- [ ] English UI translation
+
+## 📄 License
+
+[MIT](LICENSE) — do whatever you want, no warranty.
+
+> **Note**: this bot is a private automation tool for your own media stack. Make sure
+> whatever you download complies with the laws of your country.

docker-compose.yml

@@ -0,0 +1,61 @@
+# Example deployment for a NAS (UGREEN UGOS, Synology, ...) that already runs a media
+# stack. Only the bot service is defined here — Prowlarr, FlareSolverr, qBittorrent and
+# Plex are assumed to exist already; the bot just needs to share a Docker network with
+# Prowlarr and qBittorrent so it can reach them by container name.
+#
+# 1. Find the network your media stack uses:        docker network ls
+# 2. Adjust the `networks` section below accordingly.
+# 3. Fill in the environment variables (or use an .env file next to this compose file).
+# 4. docker compose up -d
+
+services:
+  cineseekerr:
+    # Use the prebuilt image...
+    image: ghcr.io/emanuele-patruno/cineseekerr:latest
+    # ...or build from source instead:
+    # build: .
+    container_name: cineseekerr
+    restart: unless-stopped
+    environment:
+      # --- Telegram ---
+      # Token from @BotFather
+      TELEGRAM_BOT_TOKEN: "123456789:AAF..."
+      # Comma-separated chat IDs allowed to use the bot (get yours from @userinfobot).
+      # Everyone else is silently ignored.
+      TELEGRAM_ALLOWED_CHAT_IDS: "123456789"
+
+      # --- TMDB (movie disambiguation) ---
+      # Either a v3 API key or a v4 Read Access Token, both work.
+      TMDB_API_KEY: "..."
+      # Language for titles/plots shown in chat (default it-IT)
+      # TMDB_LANGUAGE: "it-IT"
+
+      # --- Prowlarr (indexer search) ---
+      # Container name + internal port, NOT the NAS IP: the bot talks over the
+      # shared Docker network.
+      PROWLARR_URL: "http://prowlarr:9696"
+      # Prowlarr → Settings → General → API Key
+      PROWLARR_API_KEY: "..."
+
+      # --- qBittorrent (download) ---
+      QBITTORRENT_URL: "http://qbittorrent:8080"
+      QBITTORRENT_USER: "admin"
+      QBITTORRENT_PASS: "..."
+
+      # --- Media ---
+      # Save path AS SEEN BY THE QBITTORRENT CONTAINER. The bot never touches the
+      # filesystem itself (renames go through the qBittorrent API), so no volume
+      # mount is needed here.
+      MEDIA_ROOT_FOLDER: "/volume1/media/Film"
+
+      # How often to poll qBittorrent for completed downloads (ISO-8601, default PT30S)
+      # DOWNLOAD_POLL_INTERVAL: "PT30S"
+    networks:
+      - media
+
+networks:
+  # The pre-existing network shared with Prowlarr/qBittorrent. If your stack was
+  # created by another compose project, mark it external and use its real name
+  # (e.g. "mediastack_default").
+  media:
+    external: true