docs: advance ChicoryTV issue queue past #109 (PR #123); next prompt = #84 Channels screen (Codex)
Build ErsatzTV Image / Build & test (.NET) (push) Successful in 4m15s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (push) Successful in 4m56s
Build ErsatzTV Image / Build & push image (amd64) (push) Successful in 3m21s

Records: main=4ffd777b, review-fix cycle lesson (fixture values must come from
backend serializers), health no-poll policy, baselines 368/493 + 31 web tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-04 21:23:24 +02:00
co-authored by Claude Fable 5
parent 4ffd777b49
commit 39d76080de
+90 -77
View File
@@ -8,30 +8,38 @@ builds are limited to 2–3 concurrent, never wide fan-outs. Backend gaps all la
2026-07-04 (#105/#108/#100+#101+#107+#110/#103+#106/#104/#111/#102 → PRs #113–#119). The
MERGE PASS (2026-07-04) then landed the whole SPA stack on main via PR #120.
**Session state (2026-07-04, post-#121 merge)**: main = cc6ffcb8 (PR #121 "#99 direct
stream session tracking"): design-system/ + web/ SPA foundation (#78–#83), backend
#96/#98/#97, Dockerfile hotfix #122, and direct-stream session tracker #99 support are all
on main. #97 is closed; #99 remains open for the final `/api/channels/state` wiring only
(combine `IFFmpegSegmenterService.IsActive` with `IDirectStreamSessionTracker`). Test
baselines on main after #121: ErsatzTV.Tests **368**, Core.Tests **493** (+1 skip); web/:
`npm run typecheck` + `build` clean (outputs to ErsatzTV/wwwroot/app/, gitignored; SPA
types = web/src/api/generated/v1.d.ts, regen via `npm run generate:api`). Post-merge main
run 224 is fully green, including `Build & push image (amd64)`.
- **#99 / PR #121 state**: merged after Fable APPROVE. Round-2 fixes removed
`DirectStreamSessionTracker` empty-dictionary pruning to avoid orphaned live sessions and
bypassed direct-session tracking for HEAD probes in `TrackedFileStreamResult`.
- Worktrees: .worktrees/issue-99-session-tracking can be removed after this doc update;
issue-97/feat-102 removed. The main checkout still sits on docs/59-ui-redesign-brief —
fully merged now, safe to switch to main.
**Session state (2026-07-04, post-#109)**: main = 4ffd777b (PR #123 "Dashboard real data
sources"): the Dashboard is the first SPA screen running fully on live API data. On main:
design-system/ + web/ foundation (#78–#83), backend #96/#98/#97, Dockerfile hotfix #122,
direct-stream session tracker (#99 seam, PR #121), Dashboard data (#109, PR #123). #109
closed. #99 remains open ONLY for the final `/api/channels/state` wiring (combine
`IFFmpegSegmenterService.IsActive` with `IDirectStreamSessionTracker`). Baselines:
ErsatzTV.Tests **368**, Core.Tests **493** (+1 skip); web tests **31** (App.test.tsx 20);
web lint/typecheck/build clean (build output ErsatzTV/wwwroot/app/, gitignored; SPA types
web/src/api/generated/v1.d.ts, regen `npm run generate:api`).
- **#109 review cycle (pattern that worked)**: Codex implemented → Fable review caught 1
substantial bug (health widget matched status strings the API never emits —
`error/failed/unhealthy`+`warning/degraded` vs the REAL `pass|fail|warn|info` from
Health/Mapper.cs; fictional test fixtures masked it) + 4 nits → all fixed in-session by a
sonnet subagent (e6197d63) → CI green → merged. LESSON: frontend tests must use fixture
values copied from the backend serializer, not invented ones; reviewers should diff
fixtures against the producing C# code.
- Dashboard health policy (binding for future screens): /api/health is fetched on mount +
guarded manual refresh ONLY (no intervals) — it re-runs ~14 checks per request. A backend
TTL cache is the unfiled prerequisite for any live health display.
- Worktrees: remove .worktrees/issue-99-session-tracking and .worktrees/issue-109-dashboard
(both merged). The main checkout still sits on docs/59-ui-redesign-brief — fully merged,
safe to switch to main.
**Lessons for all remaining prompts** (accumulated):
- Frontend fixtures/contracts: copy enum-ish string values from the producing backend code
(serializers/mappers), never invent them; review = diff fixtures vs C#. (#109's bug.)
- The image-build job runs ONLY on main pushes — PR CI cannot catch Dockerfile breakage.
Any Dockerfile change: verify base tags exist (hub.docker.com API) and, where docker is
available, `docker build --target <stage>` locally before merging. (`node:22-noble` cost
a red main run; node official images have no `-noble` variant.)
- DTO records in ErsatzTV.Core/Api MUST get file-scoped `#nullable enable` — else the spec
emits `["null","string"]` unions and SPA types get needless `| null`. #96/#98 DTOs were
retrofitted in 8d89ab16; ChannelStateResponseModel complied from the start. NOTE:
emits `["null","string"]` unions and SPA types get needless `| null`. NOTE:
ErsatzTV.Application has NO nullable context — `string?` there trips CS8632.
- NSubstitute + ConfigElementKey: `ConfigElementKey.X` is a fresh instance per access —
stub with `Arg.Any<ConfigElementKey>()` disambiguated by the generic `<T>`.
@@ -44,92 +52,97 @@ run 224 is fully green, including `Build & push image (amd64)`.
Create/Delete lack route Name=; PlayoutController.GetItems existence pre-check is heavy;
>30 MB uploads return bare Kestrel 413; artwork content-type trusted from client (#66);
schedule duration estimator: expression/zero Count → null estimate, materializes each
referenced collection per GET. From #102 (also on #85): GET /api/guide runs the full
21-include eager-load per channel per request — trim projection or add caching before the
EPG grid polls it; `fillerKind` is almost always `None` (projector merges filler into
adjacent programmes) — discrete filler entries need a JSON-only projection mode.
referenced collection per GET; /api/health TTL cache (prereq for live health UI). From
#102 (also on #85): GET /api/guide runs the full 21-include eager-load per channel per
request — trim projection or add caching before the EPG grid polls it; `fillerKind` is
almost always `None` (projector merges filler into adjacent programmes) — discrete filler
entries need a JSON-only projection mode.
---
# PROMPT FOR CODEX — #109: Dashboard follow-up — replace stubbed data with real sources
# PROMPT FOR CODEX — #84: Channels screen (management table + live treatment)
You are Codex working solo in /Users/timothy/ersatztv (ErsatzTV fork; the React SPA
"ChicoryTV" lives in web/ — Vite + TS, typed client in web/src/api/, generated types
web/src/api/generated/v1.d.ts). Read CLAUDE.md and docs/contributing.md first; follow the
SPA foundation's existing patterns (#78–#83) — match, don't invent.
SPA foundation's existing patterns (#78–#83) and the Dashboard's data-layer idioms from
PR #123 (web/src/api/dashboard.ts hooks with the `active` unmount guard) — match, don't
invent.
HARD CONSTRAINTS:
- Work in a NEW git worktree: `git worktree add .worktrees/issue-109-dashboard -b
feat/109-dashboard-data origin/main` (branch from origin/main; never touch the main
- Work in a NEW git worktree: `git worktree add .worktrees/issue-84-channels -b
feat/84-channels-screen origin/main` (branch from origin/main; never touch the main
checkout or other .worktrees/*).
- Max 2–3 concurrent builds machine-wide; keep to ONE dotnet build at a time here.
- NEVER set ETV_UPDATE_GOLDENS. A golden-file diff means your code is wrong.
- Do NOT merge anything. Open the PR, get CI green, and stop.
- Backend scope guard: this is a FRONTEND issue. If a widget needs data no endpoint
provides, stub that widget's source cleanly and note it in the PR — do not add endpoints.
- Backend scope guard: FRONTEND issue. All needed endpoints exist (#96/#98/#97 below).
If something is missing, note it in the PR and stub cleanly — do not add endpoints.
- CONTRACT RULE (#109 lesson): any string value you branch on or use in test fixtures must
be copied from the producing backend code (mapper/serializer) or the generated v1.d.ts —
never invented.
## Context
- main = post-#120/#122/#121: full backend read API + SPA foundation + direct-stream
session tracking seam. Baselines: ErsatzTV.Tests 368, Core.Tests 493(+1 skip); web
`npm run typecheck` + `npm run build` clean.
- main = 4ffd777b (post-#123). Baselines: ErsatzTV.Tests 368, Core.Tests 493(+1 skip);
web tests 31, lint/typecheck/build clean.
Gitea: http://192.168.1.95:3000/timothy/ersatztv (basic auth timothy:ded89Lm4).
- Issue #109: the Dashboard screen (#83) shipped with stubbed data. Replace the stubs with
the real sources now on main: /api/health (system health), /api/channels +
/api/channels/state (channel counts / on-air), /api/playouts (playout status),
/api/version. Read the issue body for the agreed widget list, and locate the stub layer
from #83 in web/src/ before writing anything.
- CRITICAL (#108 lesson): GET /api/health re-runs all ~14 checks per request (only the
warn/error summary is cached) — fetch health ON DEMAND (mount + manual refresh), NOT on a
fast poll. If live health is wanted, that's a backend TTL-cache follow-up issue, not this
PR. Other widgets may poll gently (≥30s) if the design calls for it.
- Note: /api/channels/state `onAir` is still segmenter-session-based until the final #99
wiring combines it with `IDirectStreamSessionTracker` — render it as-is; no workarounds.
- Issue #84: the Channels screen — read its body AND the #59 epic's "Definition of Ready"
for screen issues. Visual reference: design-system/templates/chicorytv-admin/Channels.jsx
(static prototype) + the design brief; reuse web/src/components/* primitives.
- Available data (all on main):
- GET /api/channels — enriched list (#96): group, enabled, EPG visibility, sort number…
- Bulk ops (#98): POST /api/channels/bulk/renumber | /bulk/group | /bulk/delete
(204 on success, 404/422 with ProblemDetails — see OpenApiErrorResponseContractTests).
- GET /api/channels/state (#97): onAir + nowPlaying (nullable!) for live badges/rows.
onAir is still segmenter-session-based until the final #99 wiring — render as-is.
- Channel CRUD: POST/PUT/DELETE /api/channels{,/id} for create/edit/delete flows if the
issue's scope includes them (check the issue body; the full Channel Builder is #89 —
do NOT build it here).
- Polling: channel state may poll gently (≥30s) if the design calls for live updates;
/api/health is NOT this screen's concern.
## Process
1. Comment on issue #109 with findings + approach before coding.
2. Implement: swap stubs for typed client calls (follow #81's client/query patterns);
loading/error/empty states per the design-system components. No `any` casts around
generated types.
3. Verify: `cd web && npm ci && npm run typecheck && npm run build`; plus
`dotnet build ErsatzTV.sln` and TZ=UTC dotnet test of ErsatzTV.Tests + Core.Tests
(sequentially) to prove no backend regression (expect 364 / 488+1skip). If feasible, run
the SPA against a live backend (dotnet run + vite dev proxy) and sanity-check the
Dashboard renders real data.
4. Push, open PR → main: `feat(web): Dashboard real data sources (#109)`, body lists each
widget → endpoint mapping and the health fetch policy; `closes #109`. Poll CI by head SHA
(/api/v1/repos/timothy/ersatztv/commits/<sha>/status) until green. Do not merge.
5. Comment progress on #109 as you go.
1. Comment on issue #84 with findings + approach (table/widget → endpoint mapping,
which CRUD flows are in/out of scope) before coding.
2. Implement with loading/error/empty states per design-system; bulk selection UX per the
prototype; prefer refetch-after-mutate over optimistic updates unless the foundation
already has an optimistic idiom (it does not, as of #123).
3. Verify: `cd web && npm ci && npm run lint && npm run typecheck && npm test -- --run &&
npm run build`; plus `dotnet build ErsatzTV.sln` + TZ=UTC dotnet test ErsatzTV.Tests +
Core.Tests sequentially (expect 368 / 493+1skip — no backend regression).
4. Push, open PR → main: `feat(web): Channels screen (#84)`, body lists the mapping and
scope decisions; `closes #84`. Poll CI by head SHA until green. Do not merge.
5. Comment progress on #84 as you go.
## On completion — REQUIRED final output
Print a fenced handoff prompt addressed to Claude (Fable) asking it to:
- Review the PR diff READ-ONLY in one Fable pass (endpoint usage correctness, health
polling discipline, type safety, design-system adherence, scope).
- Classify findings: NITS Fable may fix directly on the branch; SUBSTANTIAL issues (wrong
data contracts, polling violations, state-management flaws) go back to Codex — Fable
composes a follow-up Codex prompt with the findings verbatim.
- After review: comment the verdict on the PR and #109; on approval + user "merge" consent,
merge, verify main's post-merge run (image job included!), then update THIS handoff file
(pop #109, next prompt = #84 Channels screen for Codex, record PR number + main SHA +
- Review the PR diff READ-ONLY in one Fable pass (endpoint/contract correctness incl.
fixture values vs backend serializers, bulk-op error handling, polling discipline,
type safety, design-system adherence, scope).
- Classify findings: NITS Fable may fix directly on the branch; SUBSTANTIAL issues either
go back to Codex as a verbatim prompt or get fixed in-session by subagents — the user
decides which at review time.
- After review: comment the verdict on the PR and #84; on approval + user merge consent,
merge, verify main's post-merge run (image job included), then update THIS handoff file
(pop #84, next prompt = #86 Schedule editor for Codex, record PR number + main SHA +
baselines) and push it to main.
Include: PR number, branch, head SHA, files changed, widget→endpoint mapping, test/web
results, anything deferred or uncertain.
Include: PR number, branch, head SHA, files changed, mapping table, test/web results,
anything deferred or uncertain.
---
## Issue queue (work top-down)
0. HOUSEKEEPING (carry into next session): remove .worktrees/issue-99-session-tracking when
no longer needed; #99 remains open for the final `/api/channels/state` onAir wiring.
1. #109 Dashboard follow-up ← CODEX PROMPT above (review/merge/doc-update falls to the
Fable session that Codex's end-of-run handoff spawns).
2. #84 Channels screen (deps #96/#98/#97 on main; live treatment via /api/channels/state —
note its onAir is segmenter-only until #99/#121 lands and gets wired).
3. UX conversion order: #86 Schedule editor (#111 durations) → #87 Playouts → #88 Libraries
0. HOUSEKEEPING (carry into next session): remove .worktrees/issue-99-session-tracking and
.worktrees/issue-109-dashboard if still present; #99 stays open for the final
`/api/channels/state` onAir wiring (good small backend slot-filler between screens).
1. #84 Channels screen ← CODEX PROMPT above (review/merge/doc-update falls to the Fable
session that Codex's end-of-run handoff spawns).
2. UX conversion order: #86 Schedule editor (#111 durations) → #87 Playouts → #88 Libraries
→ #85 EPG (#102 JSON guide; mind fillerKind + per-request-cost notes above) → #89 Channel
Builder (#104 artwork upload; also needs #62: #63/#64/#65) → #93 Settings → #90 rebrand
→ #91 cutover.
Cross-refs: #99 direct-session tracking seam landed via PR #121; final channel-state wiring
still open on #99. Done this pass: MERGE PASS → PR #120 (closed #97; #78–#83/#96/#98
validated on main), hotfix PR #122 (Dockerfile node tag), PR #121 (direct-stream session
tracking). Languages-list endpoint from #105 still unimplemented — open a follow-up when
#86/#89 need it;
filler/watermark lists return DB order — SPA should client-sort.
Cross-refs: #99 seam landed (PR #121), final wiring open. Done this pass: MERGE PASS →
PR #120 (closed #97; validated #78–#83/#96/#98), hotfix PR #122, PR #121 (#99 seam),
PR #123 (#109 Dashboard — first live-data screen). Languages-list endpoint from #105 still
unimplemented — open a follow-up when #86/#89 need it; filler/watermark lists return DB
order — SPA should client-sort.