Files
ersatztv/docs
timothy f916695e15 fix(489): address adversarial review — enforce the local-Mixed invariant, handle blank CollectionType
Review verdict was MERGEABLE; these are the findings worth fixing before merge.

M1 (the one gating finding): LibraryMediaKind.Mixed was accepted by
POST /api/v1/libraries/local. That created a library with no scanner, which
then failed every scan forever and logged at ERROR on each scheduler tick.
The invariant was asserted in prose twice and enforced nowhere -- and hiding
it from the SPA dropdown is not enforcement, since machine clients are a
stated audience for /api/v1. Now validated in CreateLocalLibraryHandler.

M3: an empty or whitespace CollectionType did not match the `null` pattern
and fell through to None, so on Jellyfin versions that serialize it that way
the whole feature silently no-opped -- no library, no log line. Normalized
via IsNullOrWhiteSpace, covered by a TestCase for "" and "   ".

L4: the cancellation test asserted IsLeft but not that ScanCanceled reaches
the caller's info-log branch. That is the fragile bit -- folding it into an
aggregate BaseError would silently demote a user cancellation to an ERROR
log (#410). Now pinned in both directions.

Nit: reverted the show-guard message to match the byte-identical Plex/Emby
guards; the original wording is still accurate since the guard only fires
when the kind is neither Shows nor Mixed.

Also documented three accepted limitations in decisions.md (progress bar
resets per kind, one failing kind forces the others to rescan, and the fact
that the music-video scanner does no reconciliation at all -- which is why it
cannot cross-delete, but also means removals never propagate).

Negative controls: reverting the M1 validation fails its test; reverting the
projection/dispatch fails theirs.

Refs #489
2026-07-20 17:35:47 +02:00
..

docs/ — reading order

Purpose: index of docs/ so a fresh contributor/agent knows what to read and in what order. Update this doc in the same PR that adds, removes, or retitles a doc below.

Read in this order at session start:

  1. CLAUDE.md (repo root) — project intro: architecture, layout, dev commands, conventions.
  2. docs/contributing.md — established code patterns (CQRS/MediatR, LanguageExt, the ChicoryTV SPA, EF Core dual-provider migrations, FFmpeg pipeline, analyzers, testing). Read before any non-trivial change.
  3. docs/domain-model.md — what the app IS: entity glossary, channel→playout→schedule/block concept map, where each concept is edited in the SPA.
  4. docs/api-conventions.md — checklist for adding/changing a /api/* endpoint (controllers, DTOs, error mapping, auth, OpenAPI regen, tests).
  5. docs/spa-conventions.md — playbook for adding a screen to the ChicoryTV React SPA.
  6. docs/e2e-local.md (+ scripts/e2e-local.sh) — how to run a live local instance for manual or Playwright-MCP verification.
  7. docs/testing.md — testing map: what each *.Tests project / web suite covers, golden-file nets, the timezone-independence rule, how to run subsets, the per-PR verification gate.
  8. docs/blazor-route-parity.md — historical record of the completed #91 phase (b) cutover: the Blazor Server UI is removed and every legacy route now 302-redirects to its SPA equivalent (or falls through to the catch-all → /app). Read it for the full legacy→SPA route inventory.
  9. docs/decisions.md — append-only "why" log. Check here before challenging an existing convention. Start from its Index, which links the four topic files under docs/decisions/ (large same-topic clusters) and lists the remaining in-file entries.
  10. docs/ci-cd.md — build/test/release pipeline, versioning, dependency management.

Also present in docs/:

  • docs/rest-api.md — REST API design doc for ersatztv#2 (goals, conventions, per-slice plan). Largely superseded day-to-day by docs/api-conventions.md; read this for the original rationale.
  • docs/channels.md — Channel entity field reference.
  • docs/m3u-xmltv.md — M3U/XMLTV generation overview (ChannelPlaylist, GetChannelGuideHandler).
  • docs/fork-strategy.md — divergence policy vs upstream ErsatzTV.
  • docs/design-sync.md — Claude Design ↔ repo screen workflow (#92).
  • docs/endpoint-index.md — generated REST endpoint index (method/path/operationId/summary per OpenAPI tag). Do not edit by hand; regenerated by scripts/generate-endpoint-index.py / scripts/update-openapi.sh.
  • docs/handoffs/chicorytv-issue-queue.md — static session kickoff prompt + workflow lore. Queue state (goal, arc, what's in flight/next) lives in the pinned Gitea tracker ersatztv#237 — read that, not this file, for current state (protocol: decisions.md 2026-07-11).
  • docs/handoffs/rest-api.md — original handoff prompt for kicking off the REST API work (#2).