From 39d76080de77d2531f020562d5e9cccfb01888ff Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 4 Jul 2026 21:23:24 +0200 Subject: [PATCH] docs: advance ChicoryTV issue queue past #109 (PR #123); next prompt = #84 Channels screen (Codex) 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 --- docs/handoffs/chicorytv-issue-queue.md | 167 +++++++++++++------------ 1 file changed, 90 insertions(+), 77 deletions(-) diff --git a/docs/handoffs/chicorytv-issue-queue.md b/docs/handoffs/chicorytv-issue-queue.md index 457336bf8..1dfccaaaf 100644 --- a/docs/handoffs/chicorytv-issue-queue.md +++ b/docs/handoffs/chicorytv-issue-queue.md @@ -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 ` 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()` disambiguated by the generic ``. @@ -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//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.