kodi/rename-mvp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
rename-mvp/rename-mvp-codex-definitieve-instructie.md
T
kodi 4ab1f15f7a reparatie diverse bestanden
2026-03-07 13:22:52 +01:00

14 KiB
Raw Permalink Blame History

Rename-MVP — Definitieve Codex instructie en technisch ontwerp

Doel

Bouw verder aan een minimalistische webapplicatie als uitgeklede webversie van Rename My TV Series.

De applicatie moet:

  • draaien in een rootless Podman container
  • lokale mediabestanden kunnen hernoemen binnen expliciet toegestane videomappen
  • metadata ophalen via TheTVDB v4 API
  • een 4-panel interface hebben
  • altijd eerst een preview tonen voordat bestanden echt worden hernoemd
  • veilig omgaan met paden, tokens en bestandsoperaties
  • de serienaam inclusief jaartal gebruiken in de UI en in de bestandsnaam

Dit project heeft al een werkende baseline:

  • container build werkt
  • FastAPI health endpoint werkt
  • TVDB login werkt
  • JWT parsing werkt
  • token persistence werkt
  • auth-status endpoint werkt
  • TVDB search werkt
  • token_source werkt

Belangrijk: dit project is nu geen greenfield ontwerp meer, maar een bestaand werkend project dat gecontroleerd verder moet worden uitgebouwd.

1. Technische context

Hostomgeving

  • Host OS: Debian Trixie
  • Podman version: 5.4.2
  • Project root: /home/kodi/.config/rename-mvp

Runtime

  • Rootless Podman
  • FastAPI backend
  • SQLite voor app-state en logging
  • JSON voor TVDB auth state
  • TheTVDB API v4
  • Lokale tests via 127.0.0.1:8085

Bestaande paden

Auth state JSON

  • Host: /home/kodi/.config/rename-mvp/data/tvdb_auth.json
  • Container: /app/data/tvdb_auth.json

Werkende testscripts

  • /home/kodi/.config/rename-mvp/regression_tests.sh
  • /home/kodi/.config/rename-mvp/feature_test_template.sh

Governance-bestanden

  • /home/kodi/.config/rename-mvp/AGENTS.md
  • /home/kodi/.config/rename-mvp/CHANGE_POLICY.md
  • /home/kodi/.config/rename-mvp/SAFE_FILES.md
  • /home/kodi/.config/rename-mvp/docs/ARCHITECTURE.md
  • /home/kodi/.config/rename-mvp/contracts/API_GOLDEN.md

2. Niet-onderhandelbare regels

2.1 Geen contractbreuk

Je mag geen bestaande API endpoints of bestaande response-structuren breken.

Je mag:

  • nieuwe velden toevoegen
  • nieuwe endpoints toevoegen

Je mag niet:

  • bestaande veldnamen wijzigen
  • bestaande velden verwijderen
  • response-structuren wijzigen
  • bestaande endpoints hernoemen
  • bestaande endpoints verwijderen

contracts/API_GOLDEN.md is leidend.

2.2 Geen speculative improvements

Voer geen refactors, herstructureringen of “verbeteringen” uit die niet expliciet nodig zijn voor de gevraagde wijziging.

Als een wijziging niet strikt nodig is om het gevraagde doel te bereiken, doe die wijziging niet.

2.3 Safe files

De volgende bestanden zijn beschermd en mogen alleen gewijzigd worden als dat expliciet noodzakelijk is en als je het duidelijk benoemt:

  • app/services/tvdb_auth_service.py
  • container/Containerfile
  • requirements.txt
  • contracts/API_GOLDEN.md
  • AGENTS.md
  • CHANGE_POLICY.md
  • SAFE_FILES.md
  • docs/ARCHITECTURE.md

2.4 Scopebeperking

Werk alleen binnen deze repository:

Pad op de host: /home/kodi/.config/rename-mvp Pad in deze codex omgeving: /workspace/rename-mvp

Je mag niets aanpassen buiten deze projectscope.

2.5 Escalated execution

Escalated execution is toegestaan binnen deze projectscope voor:

  • podman build
  • podman run
  • curl tests
  • lokale build- en testacties
  • bestanden aanmaken of aanpassen binnen dit project
  • dependency install binnen dit project

Niet toegestaan:

  • systeembrede wijzigingen
  • firewallwijzigingen
  • system upgrades
  • andere repositories
  • andere stacks of containers aanpassen
  • destructieve cleanup acties buiten deze projectscope

3. Bestaande baseline die behouden moet blijven

Deze functionaliteit werkt al en mag niet stuk:

3.1 Health endpoint

GET /api/health

Expected:

{"status":"ok"}

3.2 TVDB login endpoint

POST /api/tvdb/login

Doet een expliciete forced login en vraagt een nieuw token aan.

Deze endpoint is alleen voor debugging en handmatige auth-tests, niet voor regressietests.

3.3 TVDB auth-status endpoint

GET /api/tvdb/auth-status

Deze endpoint moet de actuele auth-status tonen inclusief:

  • configured
  • has_token
  • issued_at
  • expires_at
  • expires_at_unix
  • renew_after
  • renew_after_unix
  • is_expired
  • is_renewal_due
  • last_login_attempt_at
  • last_login_success_at
  • last_login_status
  • last_login_error
  • jwt_payload
  • token_source

3.4 TVDB search endpoint

GET /api/tvdb/search?q=elsbeth

Deze endpoint werkt al en moet series teruggeven met ten minste:

  • id
  • name
  • year
  • display_name

De UI en bestandsnaamopbouw moeten het jaartal van de serie gebruiken.

3.5 Token lifecycle

De TVDB bearer token is een JWT. Gebruik:

  • exp als primaire bron voor expiry
  • iat indien aanwezig
  • renew alleen wanneer nodig
  • niet onnodig opnieuw /login doen

De token mag niet continu vernieuwd worden.

3.6 token_source

De auth-state gebruikt:

  • none
  • login
  • cached
  • renewed

Dit gedrag moet behouden blijven.

4. Functioneel doel van de applicatie

De uiteindelijke webapp moet een minimalistische 4-panel interface hebben.

Paneel 1 — TVDB Search

Functie:

  • zoekterm invoeren
  • zoeken via backend naar TheTVDB
  • resultaten tonen
  • gekozen serie details tonen

Zoekresultaten moeten minimaal tonen:

  • serienaam
  • jaar
  • first aired indien beschikbaar
  • network indien beschikbaar
  • poster indien beschikbaar

De series moeten in de UI worden weergegeven als bijvoorbeeld:

  • Elsbeth (2024)
  • The Office (2005)

Paneel 2 — Episodes

Functie:

  • afleveringen van gekozen serie tonen
  • minimaal Aired Order ondersteunen
  • afleveringen per seizoen tonen
  • gebruiker kan willekeurige afleveringen selecteren

Afleveringen tonen bijvoorbeeld:

  • S02E03 - Devil's Night - 2025-03-13

Paneel 3 — Selected Episodes

Functie:

  • lijst van gekozen afleveringen voor de huidige sessie

Functionaliteit:

  • toevoegen
  • verwijderen
  • clear
  • reorder
  • move up / move down

Paneel 4 — Selected Files

Functie:

  • lijst van gekozen lokale videobestanden

Functionaliteit:

  • Add Files
  • Add Directory
  • Sort
  • Remove
  • Clear
  • Move Up / Move Down

Workflow

  1. user zoekt serie
  2. user kiest serie
  3. backend haalt afleveringen op
  4. user voegt afleveringen toe aan selected episodes
  5. user voegt bestanden toe aan selected files
  6. backend maakt een 1-op-1 mapping op basis van volgorde
  7. backend maakt preview
  8. user bevestigt
  9. backend voert rename uit

5. Bestandsnaamopbouw

De standaard bestandsnaam moet zijn:

{series} ({year}) - S{season:02}E{episode:02} - {title}{ext}

Voorbeeld:

Elsbeth (2024) - S02E03 - Devil's Night.mkv

Belangrijk:

  • het serienaam-jaartal is verplicht onderdeel van de naam
  • het jaartal komt uit TheTVDB serie metadata
  • de UI moet dit jaartal ook tonen

De eerste MVP hoeft airdate niet per se in de filename te zetten zolang het afgesproken template hierboven intact blijft.

6. TVDB authenticatie en tokenbeheer

6.1 Authflow

Gebruik de officiële TVDB v4 flow:

  • POST /login
  • body bevat apikey
  • pin alleen meesturen als aanwezig
  • response bevat bearer token

6.2 JWT verwerking

De token is een JWT.

Verplicht:

  • decodeer payload
  • lees exp
  • lees iat indien aanwezig
  • gebruik exp als primaire expiry-bron

6.3 Opslag

TVDB auth state wordt persistent opgeslagen in:

/app/data/tvdb_auth.json

Hostpad:

/home/kodi/.config/rename-mvp/data/tvdb_auth.json

In JSON mogen staan:

  • token
  • issued_at
  • expires_at
  • expires_at_unix
  • renew_after
  • renew_after_unix
  • last_login_attempt_at
  • last_login_success_at
  • last_login_status
  • last_login_error
  • jwt_payload
  • token_source

Niet in JSON:

  • TVDB_API_KEY
  • TVDB_PIN

Die moeten uit environment variables komen.

6.4 Renew-logica

Renew alleen wanneer:

  • now >= renew_after
  • of TVDB 401 teruggeeft

Niet continu nieuwe tokens opvragen.

POST /api/tvdb/login is geen regressietest en geen normale flow; het is een debug endpoint.

7. Toegestane videopaden

De container moet dezelfde videopaden gebruiken als de host.

Allowed media roots

  • /Volumes/8TB/Shared_Folders/TV_Shows
  • /Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows

Volume mappings

  • /Volumes/8TB/Shared_Folders/TV_Shows -> /Volumes/8TB/Shared_Folders/TV_Shows
  • /Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows -> /Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows
  • /home/kodi/.config/rename-mvp/data -> /app/data

De app mag alleen lezen/schrijven binnen een van de toegestane media roots.

8. Securitymodel

Bestandspaden

Nooit:

  • absolute clientpaden blind vertrouwen
  • .. toestaan
  • buiten allowed media roots resolven

Altijd:

  • path validation doen
  • binnen allowlist van media roots blijven
  • alleen toegestane extensies accepteren
  • preview afdwingen vóór rename

Allowed extensions MVP

  • .mkv
  • .mp4
  • .avi
  • .m4v
  • .srt

Logging

Nooit loggen:

  • API keys
  • bearer tokens
  • env secrets

9. Container en runtime

Containerfile

De bestaande werkende runtime moet behouden blijven.

Rootless Podman

De applicatie draait rootless.

Lokale test-URL

Gebruik voor runtime-tests de BASE_URL die bereikbaar is vanuit de huidige omgeving:

Gebruik niet automatisch localhost.

De testscripts moeten BASE_URL automatisch detecteren of expliciet meegegeven krijgen.

10. Verwachte repositorystructuur

Houd deze structuur aan. Geen onnodige nieuwe mappen toevoegen.

/home/kodi/.config/rename-mvp
├── AGENTS.md
├── CHANGE_POLICY.md
├── SAFE_FILES.md
├── regression_tests.sh
├── feature_test_template.sh
├── requirements.txt
├── .env
├── .env.example
├── README.md
├── app/
├── container/
├── data/
├── contracts/
│   └── API_GOLDEN.md
└── docs/
    └── ARCHITECTURE.md

11. API-contract dat behouden moet blijven

11.1 Health

GET /api/health

Response:

{"status":"ok"}

11.2 TVDB Login

POST /api/tvdb/login

Response bevat ten minste:

{
  "status": "ok",
  "issued_at": "...",
  "expires_at": "...",
  "renew_after": "..."
}

11.3 TVDB Auth Status

GET /api/tvdb/auth-status

Response bevat ten minste:

{
  "configured": true,
  "has_token": true,
  "expires_at": "...",
  "renew_after": "...",
  "token_source": "cached"
}

Meer velden zijn toegestaan, minder niet.

11.4 TVDB Search

GET /api/tvdb/search?q=query

Response bevat ten minste:

{
  "items": [
    {
      "id": "...",
      "name": "...",
      "year": "...",
      "display_name": "..."
    }
  ]
}

12. Testbeleid

12.1 Verplichte regressietests na elke wijziging

Na iedere wijziging moet dit script worden uitgevoerd:

./regression_tests.sh

Dit script is verplicht.

Het valideert de bestaande baseline en mag geen nieuw TVDB-token forceren.

12.2 Verplichte feature tests

Na iedere wijziging moet je daarnaast drie tests uitvoeren voor de nieuwe of gewijzigde functionaliteit.

Gebruik hiervoor als basis:

./feature_test_template.sh

Deze template moet per feature worden aangepast zodat de nieuwe functionaliteit echt en mechanisch getest wordt.

12.3 Geen forced login in regressie

Verboden als standaard regressietest:

curl -X POST 127.0.0.1:8085/api/tvdb/login

Deze endpoint is alleen voor debugging.

13. Ontwikkelworkflow voor Codex

Bij iedere opdracht moet je dit proces volgen:

  1. lees eerst de bestaande governance-bestanden:

    • AGENTS.md
    • CHANGE_POLICY.md
    • SAFE_FILES.md
    • docs/ARCHITECTURE.md
    • contracts/API_GOLDEN.md

  2. vat kort samen wat je gaat wijzigen

  3. benoem welke bestanden je wilt aanpassen

  4. voer alleen de strikt noodzakelijke wijziging uit

  5. draai verplichte regressietests:

    • ./regression_tests.sh

  6. draai drie feature tests voor de nieuwe functionaliteit

  7. rapporteer:

    • welke bestanden zijn aangepast
    • welke regressietests zijn uitgevoerd
    • welke feature tests zijn uitgevoerd
    • welke risico’s of beperkingen er nog zijn

14. Eerste concrete opdracht aan Codex

Begin niet meteen met een brede refactor.

Begin met een gecontroleerde volgende stap.

Eerste aanbevolen fase

Bouw de volgende functionaliteit uit:

Doel

  • endpoint om afleveringen van een gekozen TVDB serie op te halen
  • minimaal ondersteuning voor aired order
  • seriegegevens inclusief year behouden
  • output geschikt maken voor paneel 2 van de UI

Verwachte richting

Bijvoorbeeld iets als:

GET /api/tvdb/series/{series_id}/episodes?order_type=aired

Maar:

  • breek geen bestaande endpoints
  • wijzig geen bestaande auth-logica
  • wijzig geen container setup
  • gebruik bestaande TVDB token lifecycle
  • voeg tests toe

Voor deze wijziging verplicht

  1. regressietests blijven slagen
  2. drie feature tests toevoegen/uitvoeren voor het nieuwe episodes endpoint
  3. output JSON valideren
  4. zoekresultaten en year-handling niet breken

15. Wat je uitdrukkelijk niet moet doen

  • geen speculative refactors
  • geen auth-systeem herschrijven
  • geen token lifecycle vereenvoudigen
  • geen nieuwe frameworkkeuzes introduceren
  • geen projectstructuur wijzigen
  • geen governance-bestanden wijzigen tenzij expliciet nodig en gemeld
  • geen forced login gebruiken als regressietest
  • geen container- of pathmodel veranderen

16. Samenvatting voor Codex

Dit project heeft al een werkende baseline.

Jouw taak is niet om het project opnieuw te ontwerpen, maar om het gecontroleerd uit te bouwen.

Belangrijkste regels:

  • behoud werkende baseline
  • breek geen API contract
  • gebruik JWT exp als expiry-bron
  • renew token alleen wanneer nodig
  • gebruik seriejaar in UI en filename
  • werk alleen binnen allowed media roots
  • draai altijd ./regression_tests.sh
  • draai altijd drie feature tests voor nieuwe functionaliteit
  • geen speculative improvements
  • escalated execution is toegestaan binnen alleen deze projectscope
Reference in New Issue View Git Blame Copy Permalink