Public: anyone can read this; the crew can change it.
The boards list and the caller's board pins answer `{ items, next_cursor }` #5163
scout/forge:scout/5045-the-boards-list-and-the-caller-s-board-p → main 3 commits fork
7 files
changed +94
−8
README.md +2 −2
| @@ -1977,11 +1977,11 @@ work here. | ||
| 1977 | 1977 | Any panel has **Pin to home** / **Unpin** on its board page (a same-origin POST); pins are per admin, kept in `board_pin` (slug + panel title + position, `boards/pins.ts`), and home draws them under the KPI row in that person's order with Up, Down and Unpin beside each (`web/studio/pinned.ts`). A pin whose panel is gone is skipped, does not count toward the limit of 24, and is dropped at that person's next pin; nobody sees another's pins. All doors go through `actions/board-pins.ts` (an admin who is a person; anyone else gets not-found): |
| 1978 | 1978 | - the page (Pin to home / Unpin on `/boards/:slug`, Up / Down / Unpin on home); |
| 1979 | 1979 | - the terminal: on a board's screen `[` `]` mark a panel, `p` pins or unpins it, `<` `>` move a pinned one; the dashboard lists the pinned panels by title; |
| 1980 | - `GET /api/v1/boards/pins` (the list, in order) and `POST /api/v1/boards/pins` with `{"op":"pin|unpin|move","slug":"…","title":"…","by":-1|1}` (`by` for move only); | |
| 1980 | - `GET /api/v1/boards/pins` (the list, in order, as `{ items, next_cursor }` with `limit` 1–200, default 50, and `cursor`) and `POST /api/v1/boards/pins` with `{"op":"pin|unpin|move","slug":"…","title":"…","by":-1|1}` (`by` for move only); | |
| 1981 | 1981 | - the `board_pins` MCP tool (no `op` lists; `op` pin, unpin or move changes). `pins` is therefore not a board slug. |
| 1982 | 1982 | The first boot also writes the starting boards, **Usage**, **Serving**, **Crew**, **Releases**, **Apps**, **Security**, **Throughput**, **Reach** and **Forges**; Serving is the forge's event-loop lag p99 beside the checks and crew runs running, so checks' concurrency is raised on numbers. Apps' per-app panels show repo ids until a source exposes a safe name; Security (sign-ins, failed sign-ins, tokens by scope, admin actions, from the admin-only `signins`, `tokens` and `adminActions` sources and `usage`) shows no token text, hash, payload or IP; Throughput is items entering each stage from issue to live, per hour, from the `stages` source. Each is written once: `.offered` in that repo records them, so an edit stays and a deletion sticks. |
| 1983 | 1983 | A live board (any `refresh` but `off`; the form offers off or on, and `10s` and `1m` are still accepted and mean the same) redraws its grid when a run, pull, check, issue or usage event arrives, through the live-region swap |
| 1984 | (`/boards/:slug/live`, etag'd, one fetch per burst). The same doors are in the API: `GET /api/v1/boards`, `GET|PUT|DELETE /api/v1/boards/:slug`, and each panel's data as JSON or CSV at `GET /api/v1/boards/:slug/panels/:id?from=&to=&step=5m&format=csv`, bucketed in SQL to the step and never cut short (`docs/APPS.md`); each panel's card links `json` and `csv` (a plain download link) beside `explore` | |
| 1984 | (`/boards/:slug/live`, etag'd, one fetch per burst). The same doors are in the API: `GET /api/v1/boards` (`{ items, next_cursor }`, paged like the pins), `GET|PUT|DELETE /api/v1/boards/:slug`, and each panel's data as JSON or CSV at `GET /api/v1/boards/:slug/panels/:id?from=&to=&step=5m&format=csv`, bucketed in SQL to the step and never cut short (`docs/APPS.md`); each panel's card links `json` and `csv` (a plain download link) beside `explore` | |
| 1985 | 1985 | (an agent or anyone but an admin is 403; a panel whose query cannot run is refused with 422). The same four doors are MCP tools (`boards`, `board_write`, `board_delete`; `boards` with a `slug` reads one, and with a `panel` too that panel's data, with the same `from`, `to` and `step`) and, for the same person, a **Boards** screen in the terminal that lists boards and shows a board's panels as text, each with what its data holds now (a time panel's last bucket and step, another's row count). No dependency was added. |
| 1986 | 1986 | - **Issues** — labels, threaded comments, close/reopen, markdown. |
| 1987 | 1987 | - **Pull requests** — open from a branch, a **beautiful diff viewer** (syntax |
src/core/list_page.ts added +21
| @@ -0,0 +1,21 @@ | ||
| 1 | import { eventsLimit } from "./events_page.ts"; | |
| 2 | ||
| 3 | /** `?limit=&cursor=` for a short list kept whole in memory: the cursor is the offset of the next item. */ | |
| 4 | export type ListWindow = { limit: number; offset: number }; | |
| 5 | ||
| 6 | export function listWindow( | |
| 7 | limit: string | null, | |
| 8 | cursor: string | null, | |
| 9 | ): { ok: true; value: ListWindow } | { ok: false; error: "invalid_limit" | "invalid_cursor" } { | |
| 10 | const n = eventsLimit(limit ?? undefined); | |
| 11 | if (n === undefined) return { ok: false, error: "invalid_limit" }; | |
| 12 | if (cursor !== null && !/^[1-9]\d{0,5}$/.test(cursor)) return { ok: false, error: "invalid_cursor" }; | |
| 13 | return { ok: true, value: { limit: n, offset: cursor === null ? 0 : Number(cursor) } }; | |
| 14 | } | |
| 15 | ||
| 16 | /** One page of `all`: `{ items, next_cursor }`, the cursor null at the end. */ | |
| 17 | export function pageOf<T>(all: T[], w: ListWindow): { items: T[]; next_cursor: string | null } { | |
| 18 | const items = all.slice(w.offset, w.offset + w.limit); | |
| 19 | const end = w.offset + items.length; | |
| 20 | return { items, next_cursor: end < all.length ? String(end) : null }; | |
| 21 | } |
src/http/api.ts +16 −2
| @@ -179,6 +179,7 @@ import { | ||
| 179 | 179 | updateProfile, |
| 180 | 180 | } from "../actions/users.ts"; |
| 181 | 181 | import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts"; |
| 182 | import { listWindow, pageOf } from "../core/list_page.ts"; | |
| 182 | 183 | import { audienceFor } from "../core/audience.ts"; |
| 183 | 184 | import { |
| 184 | 185 | forkParentFor, |
| @@ -1553,14 +1554,25 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 1553 | 1554 | return apiError(e, e === "exists" || e === "branch_moved" ? 409 : 422, "that board could not be saved"); |
| 1554 | 1555 | }; |
| 1555 | 1556 | |
| 1557 | // `?limit=&cursor=` of the boards and pins lists, or the 422 that refuses them. | |
| 1558 | const boardsWindow = (ctx: Ctx) => { | |
| 1559 | const w = listWindow(ctx.url.searchParams.get("limit"), ctx.url.searchParams.get("cursor")); | |
| 1560 | if (w.ok) return w.value; | |
| 1561 | return w.error === "invalid_limit" | |
| 1562 | ? apiError("invalid_limit", 422, `limit is a whole number from 1 to ${LIST_LIMIT_MAX}`) | |
| 1563 | : apiError("invalid_cursor", 422, "cursor is the next_cursor of a page before"); | |
| 1564 | }; | |
| 1565 | ||
| 1556 | 1566 | router.add("GET", "/api/v1/boards", async (ctx) => { |
| 1557 | 1567 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 1558 | 1568 | const denied = boardsAdmin(ctx); |
| 1559 | 1569 | if (denied) return denied; |
| 1570 | const win = boardsWindow(ctx); | |
| 1571 | if (win instanceof Response) return win; | |
| 1560 | 1572 | const listed = await timePhaseAsync(ctx.request, "boards", () => listAllBoards(ctx.app, ctx.auth.user)); |
| 1561 | 1573 | return timePhase(ctx.request, "render", () => |
| 1562 | 1574 | listed.ok |
| 1563 | ? json({ boards: listed.value.map((b) => ({ slug: b.slug, ...b.board })) }) | |
| 1575 | ? json(pageOf(listed.value.map((b) => ({ slug: b.slug, ...b.board })), win)) | |
| 1564 | 1576 | : notFound()); |
| 1565 | 1577 | }); |
| 1566 | 1578 | |
| @@ -1570,9 +1582,11 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 1570 | 1582 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 1571 | 1583 | const denied = boardsAdmin(ctx); |
| 1572 | 1584 | if (denied) return denied; |
| 1585 | const win = boardsWindow(ctx); | |
| 1586 | if (win instanceof Response) return win; | |
| 1573 | 1587 | const listed = await timePhaseAsync(ctx.request, "boards", () => listPinnedPanels(ctx.app, ctx.auth.user)); |
| 1574 | 1588 | return timePhase(ctx.request, "render", () => |
| 1575 | listed.ok ? json({ pins: listed.value.map((p) => ({ slug: p.slug, title: p.title, panel: p.panel })) }) : notFound()); | |
| 1589 | listed.ok ? json(pageOf(listed.value.map((p) => ({ slug: p.slug, title: p.title, panel: p.panel })), win)) : notFound()); | |
| 1576 | 1590 | }); |
| 1577 | 1591 | |
| 1578 | 1592 | router.add("POST", "/api/v1/boards/pins", async (ctx) => { |
test/api-boards-timing.test.ts +1 −1
| @@ -53,7 +53,7 @@ test("each board read names session, boards, render in order", async () => { | ||
| 53 | 53 | expect(got.status).toBe(200); |
| 54 | 54 | expect(got.names).toEqual(["session", "boards", "render"]); |
| 55 | 55 | } |
| 56 | expect(JSON.parse((await phases("/api/v1/boards")).body).boards[0].slug).toBe("ops"); | |
| 56 | expect(JSON.parse((await phases("/api/v1/boards")).body).items[0].slug).toBe("ops"); | |
| 57 | 57 | }); |
| 58 | 58 | |
| 59 | 59 | test("a missing board still names its phases", async () => { |
test/board-pins.test.ts +16 −1
| @@ -124,7 +124,7 @@ describe("pinned panels", () => { | ||
| 124 | 124 | method, headers: { authorization: `Bearer ${tok[who]}`, "content-type": "application/json" }, |
| 125 | 125 | ...(body === undefined ? {} : { body: JSON.stringify(body) }), |
| 126 | 126 | }); |
| 127 | const titlesOf = async (who: string) => ((await (await api(who, "GET")).json()) as { pins: { title: string }[] }).pins.map((p) => p.title); | |
| 127 | const titlesOf = async (who: string) => ((await (await api(who, "GET")).json()) as { items: { title: string }[] }).items.map((p) => p.title); | |
| 128 | 128 | expect(await titlesOf("alice")).toEqual(["Pin A", "Pin B", "Pin C2"]); |
| 129 | 129 | expect((await api("alice", "POST", { op: "move", slug: "mine", title: "Pin C2", by: -1 })).status).toBe(200); |
| 130 | 130 | expect(await titlesOf("alice")).toEqual(["Pin A", "Pin C2", "Pin B"]); |
| @@ -133,6 +133,21 @@ describe("pinned panels", () => { | ||
| 133 | 133 | expect(await titlesOf("alice")).toEqual(["Pin C2", "Pin B", "Pin A"]); |
| 134 | 134 | expect((await api("alice", "POST", { op: "pin", slug: "mine", title: "nope" })).status).toBe(404); |
| 135 | 135 | expect((await api("alice", "POST", { op: "dance" })).status).toBe(422); |
| 136 | const get = async (q: string) => | |
| 137 | (await (await fetch(servers.url + "/api/v1/boards/pins" + q, { headers: { authorization: `Bearer ${tok["alice"]}` } })).json()) as | |
| 138 | { items: { title: string }[]; next_cursor: string | null }; | |
| 139 | const first = await get("?limit=2"); | |
| 140 | expect(first.items.map((p) => p.title)).toEqual(["Pin C2", "Pin B"]); | |
| 141 | expect(first.next_cursor).toBe("2"); | |
| 142 | const last = await get("?limit=2&cursor=2"); | |
| 143 | expect(last.items.map((p) => p.title)).toEqual(["Pin A"]); | |
| 144 | expect(last.next_cursor).toBeNull(); | |
| 145 | for (const q of ["?limit=0", "?limit=201", "?limit=x"]) { | |
| 146 | const bad = await fetch(servers.url + "/api/v1/boards/pins" + q, { headers: { authorization: `Bearer ${tok["alice"]}` } }); | |
| 147 | expect(bad.status).toBe(422); | |
| 148 | } | |
| 149 | const badCursor = await fetch(servers.url + "/api/v1/boards/pins?cursor=zz", { headers: { authorization: `Bearer ${tok["alice"]}` } }); | |
| 150 | expect(badCursor.status).toBe(422); | |
| 136 | 151 | expect((await api("bob", "GET")).status).toBe(403); |
| 137 | 152 | expect((await api("bob", "POST", { op: "pin", slug: "mine", title: "Pin A" })).status).toBe(403); |
| 138 | 153 | expect(await titlesOf("carol")).toEqual([]); // her "Pin C" was renamed away: not shown |
test/boards-store.test.ts +21 −2
| @@ -285,8 +285,9 @@ describe("/api/v1/boards", () => { | ||
| 285 | 285 | const put = await api("/api/v1/boards/api-board", tok.admin, { method: "PUT", body: JSON.stringify(mine) }); |
| 286 | 286 | expect(put.status).toBe(200); |
| 287 | 287 | expect((await readBoard(app.reposRoot, "api-board"))?.panels.length).toBe(3); |
| 288 | const list = (await (await api("/api/v1/boards", tok.admin)).json()) as { boards: { slug: string }[] }; | |
| 289 | expect(list.boards.map((b) => b.slug)).toContain("api-board"); | |
| 288 | const list = (await (await api("/api/v1/boards", tok.admin)).json()) as { items: { slug: string }[]; next_cursor: string | null }; | |
| 289 | expect(list.next_cursor).toBeNull(); | |
| 290 | expect(list.items.map((b) => b.slug)).toContain("api-board"); | |
| 290 | 291 | const one = (await (await api("/api/v1/boards/api-board", tok.admin)).json()) as { title: string; refresh: string }; |
| 291 | 292 | expect([one.title, one.refresh]).toEqual(["Api board", "1m"]); |
| 292 | 293 | const again = await api("/api/v1/boards/api-board", tok.admin, { method: "PUT", body: JSON.stringify({ ...mine, title: "Renamed" }) }); |
| @@ -294,6 +295,24 @@ describe("/api/v1/boards", () => { | ||
| 294 | 295 | expect((await readBoard(app.reposRoot, "api-board"))?.title).toBe("Renamed"); |
| 295 | 296 | }); |
| 296 | 297 | |
| 298 | test("the list pages with limit and next_cursor to the end, and refuses a bad limit", async () => { | |
| 299 | const all = (await (await api("/api/v1/boards", tok.admin)).json()) as { items: { slug: string }[] }; | |
| 300 | const seen: string[] = []; | |
| 301 | let cursor: string | null = null; | |
| 302 | let pages = 0; | |
| 303 | do { | |
| 304 | const res = await api("/api/v1/boards?limit=1" + (cursor ? `&cursor=${cursor}` : ""), tok.admin); | |
| 305 | const page = (await res.json()) as { items: { slug: string }[]; next_cursor: string | null }; | |
| 306 | expect(page.items.length).toBe(1); | |
| 307 | seen.push(page.items[0]!.slug); | |
| 308 | cursor = page.next_cursor; | |
| 309 | pages++; | |
| 310 | } while (cursor && pages < 100); | |
| 311 | expect(seen).toEqual(all.items.map((b) => b.slug)); | |
| 312 | for (const q of ["limit=0", "limit=201", "limit=abc", "cursor=x"]) | |
| 313 | expect((await api("/api/v1/boards?" + q, tok.admin)).status).toBe(422); | |
| 314 | }); | |
| 315 | ||
| 297 | 316 | test("a board failing parseQuery is refused on write and drawn as an error panel on read", async () => { |
| 298 | 317 | const bad = { ...mine, panels: [panel("Broken", { source: "runs", aggregate: "median" })] }; |
| 299 | 318 | const res = await api("/api/v1/boards/broken", tok.admin, { method: "PUT", body: JSON.stringify(bad) }); |
test/list_page.test.ts added +17
| @@ -0,0 +1,17 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { listWindow, pageOf } from "../src/core/list_page.ts"; | |
| 3 | ||
| 4 | test("a window defaults to 50 from the start and refuses what is not a page", () => { | |
| 5 | expect(listWindow(null, null)).toEqual({ ok: true, value: { limit: 50, offset: 0 } }); | |
| 6 | expect(listWindow("200", "7")).toEqual({ ok: true, value: { limit: 200, offset: 7 } }); | |
| 7 | expect(listWindow("0", null)).toEqual({ ok: false, error: "invalid_limit" }); | |
| 8 | expect(listWindow("201", null)).toEqual({ ok: false, error: "invalid_limit" }); | |
| 9 | expect(listWindow(null, "-1")).toEqual({ ok: false, error: "invalid_cursor" }); | |
| 10 | }); | |
| 11 | ||
| 12 | test("pages walk to a null cursor", () => { | |
| 13 | const all = [1, 2, 3]; | |
| 14 | expect(pageOf(all, { limit: 2, offset: 0 })).toEqual({ items: [1, 2], next_cursor: "2" }); | |
| 15 | expect(pageOf(all, { limit: 2, offset: 2 })).toEqual({ items: [3], next_cursor: null }); | |
| 16 | expect(pageOf(all, { limit: 2, offset: 9 })).toEqual({ items: [], next_cursor: null }); | |
| 17 | }); |
new above
offline