6 Commits

Include renames

Author	SHA1	Message	Date
timothyandtimothy	9881d1ff81	fix(754,757): declare graphicsElementIds + padToNearestMinute, and pin every MCP tool to its OpenAPI contract (#760) ... Co-authored-by: Timothy <timothy@noreply.gitea.tblindustries.be>	2026-08-06 20:42:37 +00:00
timothyandClaude Opus 5	78ec997eae	docs(616): stop the record title and mcp.md from contradicting their own bodies ... Two LOWs from the re-review of af39123e. Both are the same defect I have already corrected twice on this branch: a universal claim that the corrected body right below it disproves. These read as normative, so a reader who stops at the title gets the false version. - The record was titled "...and every wrapper says so" while its own body admits the 12 OpenAPI pageNum parameters carry no description at all (tracked as #633). Retitled to state the target and name the exception. - docs/mcp.md led with "Rows that reference another entity carry that entity's id" — but PlayoutListItemResponseModel.ScheduleName ships with no schedule id. Restated as a rule about ACTIONABLE references, matching the wording the record already uses, with the known exception named. The two remaining LOWs are accepted deferrals, not fixed here: the >100 rerun collection truncation needs paging-to-completeness plus a multi-page fixture (#634), and the catalog test's forward-looking gap (it compares tool names, not PathTemplate against the paged-endpoint set) would need the MCP test project to reference the controllers to close properly. Docs only; catalog regenerated. No behaviour change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:51:14 +02:00
timothyandClaude Opus 5	af39123e8e	fix(616): fix a live 1-based SPA caller and un-cap two MCP playout tools ... Findings from the cold cross-family review of 8d35a279/5648f8e9. The review confirmed the three conclusions in 8d35a279 (the offset math is sound on all 12 paged endpoints; the list DTO really did already carry ChannelId; the new tests are non-vacuous) but found the previous commits had documented a convention without checking who actually violates it. HIGH — a live instance of this issue's own bug class, in the SPA. web/src/screens/SchedulesScreen.tsx asked for the rerun-collection picker with `pageNum: 1, pageSize: 1000`. pageNum is 0-based and pageSize clamps to 100, so the request skipped the first 100 rows: with <=100 rerun collections (the normal case) the picker was served an EMPTY page and silently offered no rerun collections at all; above 100 it dropped rows 1-100. Exactly the silent-short-set failure #616 is about, shipped in the UI. Now `pageNum: 0`, with a vitest that asserts the offset and is mutation-verified (restoring `pageNum: 1` fails it). Checked the rest of the SPA rather than assuming: every other pageNum caller is 0-based. CollectionsScreen's paging loop starts at 1 but only after fetching page 0 explicitly, so it is correct — verified before touching it. MEDIUM — two MCP tools wrapped paged endpoints while declaring no paging args. ersatztv_list_playouts and ersatztv_get_playout_items had no pageNum/pageSize, and ToolArgumentValidator rejects undeclared arguments, so an agent was hard capped at the first 100 rows with no way to ask for more and no error saying so. Both now take Page(). A catalog-wide sweep confirmed these were the only two: the other paged endpoints are not exposed as MCP tools at all. That same gap made the new ToolCatalog test vacuous in the direction that mattered — it filtered on tools that ALREADY declare pageNum, so a tool missing paging entirely escaped it. It now pins the expected set by name, so a new tool over a paged endpoint has to be added deliberately. Record corrections (these are read as normative, so over-broad claims are defects): "every wrapper says 0-based" was false for the OpenAPI surface, whose 12 pageNum parameters carry no description — named as a remaining gap instead of claimed as done. "Every controller floors with Math.Max" ignored SearchController's Math.Clamp. The ids-in-rows corollary was stated as an audit result when PlayoutListItemResponseModel.ScheduleName has no schedule id; restated as a rule about actionable ids. Verification: .NET 1900 + MCP 59 pass; web 996 pass across 105 files; tsc clean; eslint clean; format gate exit 0; no BOMs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:41:54 +02:00
timothyandClaude Opus 5	5648f8e92e	docs(616): scope the pageSize cap per endpoint — it is not one number ... Self-review of the previous commit caught an overclaim I introduced. I wrote the paging docs as if the pageSize cap were uniformly 100. It is not: most reads (collections, library browse, logs, playouts) Math.Clamp(.., 1, 100) GetAutoTuneChannelMembers pageSize <= 0 ? 100 : Min(.., 200) GET /api/v1/search/all-items default 500, cap 1000 That made a concrete example in docs/mcp.md simply false. It claimed `pageSize=500&pageNum=1` returns items 101-200 "not 501-1000" — but ersatztv_search_all_items also takes Page(), and 500 is UNDER its cap, so there page 1 really is items 501-1000. A caller following that example on the one tool most likely to be paged hard would have mis-derived its offsets, which is the same class of silent-short-set error this issue is about. The invariant that actually holds everywhere is the derivation, not any single cap: the offset comes from the EFFECTIVE (bounded) page size, never the requested one. Reworded to say that, in docs/mcp.md, the api.paging-zero-based record (rule + mechanics + body), and the ToolCatalog Page() comment. Catalog regenerated. The record's mechanics line no longer claims every controller uses Math.Clamp — ChannelController does not. No behaviour change; MCP suite still 59/59. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:24:40 +02:00
timothyandClaude Opus 5	8d35a2792f	fix(616): document paging as 0-based, expose channelId on playout detail ... #616 filed three MCP/API paging traps. Two were real; one was not, and one was already half-fixed on main. Verified each against the code before changing it. REAL — pageNum documented as 1-based. `ToolCatalog.Page()` described pageNum as "1-based page number" while every paged controller defaults it to 0, floors it with `Math.Max(0, pageNum)`, and skips `PageNum * PageSize`. A caller that trusted the description started at page 1 and silently lost the first page: no error, just a short set that reads as data loss rather than an off-by-one (it cost #487 a verification pass). Fixed in the description rather than by making the MCP layer 1-based: /api/v1 is additive-only post-freeze, 0-based is load-bearing in a dozen controllers and the SPA, and a 1-based wrapper over a 0-based API would make the same parameter name mean two different things on two surfaces a reader reads together. NOT REAL — "pageSize caps the page but the offset honors the requested value". Not reproducible on any endpoint. Every controller clamps before passing, every handler skips by the clamped size, and GetCollectionItemsHandler re-clamps defensively. The reported observation (pageSize=500&pageNum=2 on a 204-item collection returning 4 items) is exactly correct 0-based behaviour at the clamped width of 100 — page 2 is items 201-204. The issue's own trap-1 table states this. Pinned by test rather than "fixed". ALREADY FIXED — playout LIST rows gained channelId in #297 (2026-07-22), three days before #616 was filed; the report was measured against prod, which runs an older :prod image. The DETAIL response (PlayoutResponseModel) genuinely still lacked it, so channelId is added there (additive) and the reset_channel_playout argument now names the trap: the id spaces overlap numerically, so passing a playout id silently resets a different channel and returns a plausible 202. Tests, both mutation-verified (each fails when its fix is reverted): - ToolCatalogTests pins "0-based" on EVERY paged tool's pageNum description, with a non-empty guard so it can't pass vacuously over an empty tool set. - GetCollectionItemsHandlerTests pins 0-based page boundaries and proves the offset derives from the clamped pageSize (page 1 at pageSize=500 returns items 101-150; the mutation that honors 500 returns an empty page). Docs: new decision record api.paging-zero-based (catalog regenerated), the api-conventions paging bullet, and a Paging section in docs/mcp.md. OpenAPI v1.json + web/src/api/generated/v1.d.ts regenerated for the added field. fixes #616 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-25 23:16:00 +02:00
timothyandClaude Opus 4.8	a88240dcec	feat(#58): ErsatzTV.Mcp — read + cautious-write MCP server over /api/v1 ... Fresh stdio JSON-RPC MCP server wrapping the frozen /api/v1 surface, superseding the closed read-only PR #76. 26 read tools (six families + search/all-items & search/artists discovery) and cautious-write CRUD: collections (incl. idempotent membership adds for #487), smart collections, schedules, playouts, channels (create/update/delete/reset), and a Jellyfin-focused media-source sync/scan slice. Writes gated behind ERSATZTV_ALLOW_WRITES (default false, runtime-enforced). Security baseline carried forward from PR #76/#289: read-only backstop, JSON-RPC DoS guards + bounded stdin reader, per-request CTS over headers+body, response-size cap, arg validation vs InputSchema, reverse-proxy prefix preservation. Machine-key auth (X-Api-Key, CSRF-exempt). If-Match/ETag round-trip for the one replace-all PUT that honors it. Cold-review fixes folded in: - HIGH: reject control chars (CR/LF) in the ifMatch value before it reaches TryAddWithoutValidation — SocketsHttpHandler writes it verbatim, so a crafted value could smuggle headers onto the X-Api-Key request. - Cache the empty-args JsonDocument (no per-call pooled-doc leak). - Accept explicit JSON null for optional fields so a nullable API field (e.g. dailyRebuildTime) can be cleared as documented. Deferred (documented): the ~40-field replace-list writes and redesign workflow tools (#63-#68). Docs: docs/mcp.md, docs/README.md index, docs/decisions.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-21 00:42:00 +02:00