timothy/ersatztv
1
0
Fork 0
Code Issues 51 Pull Requests 5 Actions Packages Projects Releases 9 Wiki Activity
Files
83cd36e0dea7b827f34b2a1ac5de03c6c37f2eeb
ersatztv/CLAUDE.md
T
timothy fba5233caf
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 11s
Details
PR Gates / Docs update reminder (pull_request) Successful in 16s
Details
PR Gates / decisions lifecycle (pull_request) Failing after 23s
Details
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 1m17s
Details
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 1m29s
Details
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m5s
Details
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 16m5s
Details
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 17m6s
Details
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
Details
feat(610): split the decision corpus into one YAML-frontmatter file per record 
168 records -> docs/decisions/records/<area>/<topic>.md (163 active, 23 dirs) and
docs/decisions/archive/<area>/<topic>.md (5 archived). The filename IS the key,
so one-active-record-per-key becomes a filesystem property rather than a
validator check, and supersession becomes a `git mv`.

WHY: the monolith was a concurrency problem before an aesthetic one. A
3,900-line append target made parallel sessions collide -- PR #605 and PR #614
both hit append-vs-append conflicts during routine rebases, and hand-resolving
those inside the corpus is exactly the operation the rationale-rewrite guard
exists to police.

HOW IT IS VERIFIED: a ~170-file diff cannot be meaningfully read, so correctness
does not rest on reading it. The parser was taught BOTH formats first, so the
body-diff guard parses the old form at the merge-base and the new form at head --
the migration validates itself, no bypass. The proof is a field-level equivalence
harness: 168 records before and after, zero lost, zero gained, zero field
mismatches, zero rationale bodies differing. Reviewers should scrutinise the
harness; it is the actual evidence.

What measuring caught that reading would not have:

- ~500 lines sit OUTSIDE any record -- decisions.md's lifecycle schema and each
  topic file's preamble, mostly the only copy. Source files are kept and
  stripped, never deleted. They also cannot be filed per-area: topic files hold
  several areas and 4 of 23 areas span several files.
- Archive discovery was a non-recursive glob; after the split it found ZERO
  archived records, surfacing as four bogus "supersedes points to unknown key"
  errors rather than an obvious failure.
- ~32 live docs point into the corpus BY DATE, which the split dangles. Each
  stripped file now ends with a generated "Records formerly in this file" index,
  which also rescues the identical breadcrumbs in old issue comments.
- decisions.md's "In this file:" list was 97 same-file anchor bullets that the
  split makes WRONG, not merely stale. Dropped; the generated index replaces
  them with links that resolve.

The equivalence harness now runs against a checked-in FIXTURE, not the live
corpus. The earlier version migrated the real tree, which made it a one-shot:
the moment the migration landed there was nothing left to move and the tests
failed for reasons unrelated to the code. A fixture keeps them testing the
SCRIPT rather than the repo's current state.

Keys preserved verbatim, warts included: `sched` (12) and `scheduling` (1) remain
two directories for one concept. Renaming a key is not a move -- it changes
identity, breaks the equivalence proof, and invalidates MemPalace's per-key
drawers. Taxonomy normalisation is separate work.

refs #610
2026-07-25 19:45:09 +02:00

11 KiB
Raw Blame History

ErsatzTV Fork

Custom IPTV channel server for Jellyfin. Forked from ErsatzTV/ErsatzTV after upstream archival (Feb 2026, v26.3.0). Our fork lives on Gitea.

Architecture

  • UI: ChicoryTV React SPA (web/, Vite, served at /app) over the REST API — the ONLY UI. The legacy Blazor Server UI (MudBlazor) was removed in #91 phase (b); root / and every legacy route now 302 to /app, either via an explicit redirect in ErsatzTV/LegacyUiRedirects.cs or the Startup catch-all fallback (any unmatched non-/api//artwork//docs//openapi path → /app). Historical parity work: media detail pages + image folder browser landed via #141 (PR #183); scheduling parity #144/#162, #141/#158/#161/#180, #145, #151/#152/#153/#155, and the media-source write API/SPA #202 are all DONE.
  • Pattern: CQRS via MediatR — queries/commands in ErsatzTV.Application/
  • Database: EF Core (SQLite default, MySQL optional) — context in ErsatzTV.Infrastructure/Data/TvContext.cs

Key Files

  • M3U generation: ErsatzTV.Core/Iptv/ChannelPlaylist.cs → ToM3U()
  • XMLTV generation: ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs
  • IPTV controller: ErsatzTV/Controllers/IptvController.cs — /iptv/* routes
  • Logo generation: ErsatzTV.Core/Images/ChannelLogoGenerator.cs
  • Channel entities: ErsatzTV.Core/Domain/Channel.cs
  • DB context: ErsatzTV.Infrastructure/Data/TvContext.cs

Deployment

  • Docker host: jazz (192.168.1.29), container ersatztv, port 8409. Media transcoders (Jellyfin, ersatztv, ersatztv-test) moved here from bumblebee on 2026-07-20 (server-management#633); bumblebee (192.168.1.99) still hosts the CI runners and the rest of the stacks. Name-reuse trap: jazz was an earlier name for the .99 host, so pre-2026-07-20 docs/commits saying "jazz" mean today's bumblebee — go by the IP, not the name.
  • Config volume: ~/downloadswarm/ersatztv/ on jazz → /config in container
  • SQLite DB: /config/ersatztv.sqlite3 (WAL mode, root-owned)
  • Images (our fork, built by .gitea/workflows/docker-build.yml → 192.168.1.95:3000/timothy/ersatztv): push to main → :latest + :<sha> (test image); push v* tag → :prod + :<version> + :<sha>. Prod's Komodo GitOps stack — named jazz-media (the compose project is still media-servers; a dead media-servers stack lingers on bumblebee) — follows floating :prod; after the immutable :<version> candidate passes the release scans, manually DeployStack jazz-media. There is no auto-update fallback (auto_update: false) — promotion is manual. Both paths run the fail-closed pre-deploy backup and prod-copy migration smoke before recreation. Test tracks :latest. Pipeline details: docs/ci-cd.md.

Development

# Docker build
docker build -f docker/Dockerfile -t ersatztv:dev .

Conventions

  • Read docs/contributing.md before non-trivial changes — it documents the established patterns (layering, CQRS handlers, LanguageExt, the ChicoryTV SPA, EF Core + dual-provider migrations, the FFmpeg pipeline, analyzers, testing) and the deviation policy: match the established style; diverge only with a concrete, stated reason.

  • Docs-first is a HARD RULE — read before you explore: before ANY API / SPA / E2E / parity / scheduling work, read the docs/README.md task-signal map and only the sections it points to for your task — not the whole corpus. Do NOT reverse-engineer conventions from source (Grep/Read) before reading these — they exist precisely so you don't. Only recon the task-specific delta the docs deliberately don't freeze (a merged endpoint's exact DTO, a Blazor page's field list). This applies to delegated subagents too: tell each agent which doc section to read; never let one re-derive conventions from code. Decision/convention lookups start at the active catalog, docs/decisions/README.md — resolve by topic/key, never by chasing a file path named in a historical comment (the breadcrumb rule; see docs/README.md → "Knowledge retrieval").

  • Docs-update is part of "done" — same PR, never a follow-up: any PR that changes a convention, adds/migrates/redirects a route, adds/changes a /api/* endpoint, or reverses a decision MUST update the relevant doc in that same PR:

    Change Update in the same PR
    Migrate / add / redirect a route (new web/src/screens/*.tsx, LegacyUiRedirects.cs) docs/blazor-route-parity.md + docs/domain-model.md
    Add / change a /api/* endpoint docs/api-conventions.md checklist, then regenerate v1.json + endpoint-index.md via ./scripts/update-openapi.sh
    Change a SPA screen convention docs/spa-conventions.md
    Establish / reverse a convention or decision a new docs/decisions/records/<area>/<topic>.md (filename = key; lifecycle: add record, git mv predecessor to archive/<area>/) + regenerate the catalog + the affected doc
    Add / remove / retitle a doc docs/README.md index

    The docs-reminder CI job flags a screen/route change that skips blazor-route-parity.md, but it's a non-blocking nudge — the rule is on you, not the check.

  • Follow existing MediatR CQRS pattern for new features

  • Domain logic in ErsatzTV.Core, infrastructure in ErsatzTV.Infrastructure

  • Keep UI thin: the SPA talks to /api/* only; controllers delegate to MediatR handlers. All UI is in the SPA (web/)

  • Test with NUnit + Shouldly + NSubstitute (the existing *.Tests projects); xUnit is not used here

  • Dependencies use Central Package Management: versions live in the repo-root Directory.Packages.props; csproj reference packages by name only. Add/upgrade by editing the central <PackageVersion> — never put Version= back on a <PackageReference> (trips NU1008). See docs/ci-cd.md → Dependency management.

  • DB migrations target BOTH providers: a TvContext model change needs a migration in ErsatzTV.Infrastructure.Sqlite and ErsatzTV.Infrastructure.MySql — run scripts/add-migration.sh <Name> (does both). CI's migrations job enforces model-drift + apply-to-fresh-DB per provider. See docs/ci-cd.md → Migration integrity.

  • Renovate is live (.gitea/workflows/renovate.yml, weekly + workflow_dispatch): opens dependency-update + OSV vuln-fix PRs and a Dependency Dashboard issue; patch bumps to test/dev-only packages auto-merge once Build & test passes, the rest are manual. Cross-repo rollout: server-management#484. See docs/ci-cd.md → Dependency management.

  • Versioning: release tags are vYY.<release-seq>.<patch> (year · sequential release-within-year · patch) — inherited from upstream, not year.month. v26.3.1 = our infra rebuild of upstream 26.3.0 (no app changes); v26.4.0 is reserved for the first release with app changes. Never [skip ci] a commit you'll tag (it suppresses the release build). Full policy: docs/ci-cd.md → Versioning & releases.

  • Backlog tracked via Gitea Issues

Task Completion Protocol

Every task that closes a Gitea issue MUST complete ALL of these before it is considered done. Use /done <issue> to run through this automatically.

Merge-consent is derived from state, not asserted (## Done-when convention — ersatztv#303 H6 + H10). Any issue whose PR will merge to main should carry a ## Done-when section in its issue body — a checklist of completion criteria (always include an "adversarial review passed" box; add per-issue criteria like tests-green, docs-updated, live-E2E). Two hooks derive merge-consent from it so a premature merge is blocked by construction, not by memory:

  • pretooluse-merge-consent.sh (Claude PreToolUse on the Gitea merge tool) — auto-grants a merge (emits permissionDecision: allow, so no redundant mechanical prompt fires) only when the PR's CI is green and every ## Done-when box on the linked issue (fixes #N) is ticked and a Review-verdict: comment references the PR's current head sha (H10); denies on an unticked box, red CI, or a stale/negative review verdict; asks (falls back to a human prompt) when it can't derive state (no linked issue, no ## Done-when section, no Review-verdict: comment yet, no creds, Gitea down). On the auto-grant (satisfied) path the derived state is the consent — do not also ask conversationally to merge; a separate human confirmation is warranted only when the gate asks (ersatztv#314). The H10 review-verdict convention: after an adversarial/Codex review of a PR (or its latest fix commit), post a PR comment with a line Review-verdict: <MERGEABLE|APPROVED|BLOCKED> @ <head-sha> — this proves the latest commit was reviewed, not a stale earlier diff (ersatztv#242).
  • .husky/pre-push → prepush-donewhen.sh — a fail-open backstop that blocks a direct git push origin main whose commits fix #N an issue with unticked boxes.

Both need Gitea read creds in the env to enforce (ETV_GITEA_BASICAUTH=user:pass or ETV_GITEA_TOKEN; ETV_GITEA_URL overrides the base). Without them the merge hook asks and the push backstop is a no-op — the gate degrades to today's manual confirmation, never a silent pass. Docs-only PRs/pushes are exempt.

The 7 mandatory completion steps and the ## Closing record comment template live in the closing-an-issue skill (.claude/skills/closing-an-issue/SKILL.md) — invoke it (or /done) when finishing a task that closes an issue.

Project Boundaries

ersatztv OWNS: ErsatzTV fork code (C#/.NET), channel/collection/schedule management, M3U/XMLTV generation, the ErsatzTV skill in server-management.

ersatztv does NOT own:

  • Docker compose configs → server-management (~/downloadswarm/stacks/ersatztv/)
  • NFS mounts, Ansible, DNS, networking → server-management
  • Content sourcing (yt-dlp downloads, Sonarr/Radarr libraries) → media-management (planned)
  • Jellyfin skill → server-management (symlinked)

For infrastructure changes (Docker, NFS, ports, Authelia): open an issue in timothy/server-management.

For content/media sourcing questions (what goes into channels, yt-dlp pipelines): open an issue in timothy/media-management once it exists; for now, timothy/server-management.

For plan/audit reviews: open ~/adversarial-reviewer before significant architecture changes.

Full cross-project rules: ~/homelab-docs/Operations/Project Boundaries.md (https://docs.tblindustries.be). ErsatzTV docs: ~/homelab-docs/Docker/ErsatzTV.md + project-local docs/ (fork strategy, channels, M3U/XMLTV).

Reference in New Issue View Git Blame Copy Permalink