Public: anyone can read this; the crew can change it.

The boards list and the caller's board pins answer `{ items, next_cursor }` #5163

Parked opened this
Closed without merging

scout/forge:scout/5045-the-boards-list-and-the-caller-s-board-p → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +94 −8
README.md +2 −2
@@ -1977,11 +1977,11 @@ work here.
19771977 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):
19781978 - the page (Pin to home / Unpin on `/boards/:slug`, Up / Down / Unpin on home);
19791979 - 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);
19811981 - the `board_pins` MCP tool (no `op` lists; `op` pin, unpin or move changes). `pins` is therefore not a board slug.
19821982 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.
19831983 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`
19851985 (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.
19861986 - **Issues** — labels, threaded comments, close/reopen, markdown.
19871987 - **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 {
179179 updateProfile,
180180 } from "../actions/users.ts";
181181 import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts";
182 import { listWindow, pageOf } from "../core/list_page.ts";
182183 import { audienceFor } from "../core/audience.ts";
183184 import {
184185 forkParentFor,
@@ -1553,14 +1554,25 @@ export function apiRoutes(router: Router<Handler>): void {
15531554 return apiError(e, e === "exists" || e === "branch_moved" ? 409 : 422, "that board could not be saved");
15541555 };
15551556
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
15561566 router.add("GET", "/api/v1/boards", async (ctx) => {
15571567 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
15581568 const denied = boardsAdmin(ctx);
15591569 if (denied) return denied;
1570 const win = boardsWindow(ctx);
1571 if (win instanceof Response) return win;
15601572 const listed = await timePhaseAsync(ctx.request, "boards", () => listAllBoards(ctx.app, ctx.auth.user));
15611573 return timePhase(ctx.request, "render", () =>
15621574 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))
15641576 : notFound());
15651577 });
15661578
@@ -1570,9 +1582,11 @@ export function apiRoutes(router: Router<Handler>): void {
15701582 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
15711583 const denied = boardsAdmin(ctx);
15721584 if (denied) return denied;
1585 const win = boardsWindow(ctx);
1586 if (win instanceof Response) return win;
15731587 const listed = await timePhaseAsync(ctx.request, "boards", () => listPinnedPanels(ctx.app, ctx.auth.user));
15741588 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());
15761590 });
15771591
15781592 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 () => {
5353 expect(got.status).toBe(200);
5454 expect(got.names).toEqual(["session", "boards", "render"]);
5555 }
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");
5757 });
5858
5959 test("a missing board still names its phases", async () => {
test/board-pins.test.ts +16 −1
@@ -124,7 +124,7 @@ describe("pinned panels", () => {
124124 method, headers: { authorization: `Bearer ${tok[who]}`, "content-type": "application/json" },
125125 ...(body === undefined ? {} : { body: JSON.stringify(body) }),
126126 });
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);
128128 expect(await titlesOf("alice")).toEqual(["Pin A", "Pin B", "Pin C2"]);
129129 expect((await api("alice", "POST", { op: "move", slug: "mine", title: "Pin C2", by: -1 })).status).toBe(200);
130130 expect(await titlesOf("alice")).toEqual(["Pin A", "Pin C2", "Pin B"]);
@@ -133,6 +133,21 @@ describe("pinned panels", () => {
133133 expect(await titlesOf("alice")).toEqual(["Pin C2", "Pin B", "Pin A"]);
134134 expect((await api("alice", "POST", { op: "pin", slug: "mine", title: "nope" })).status).toBe(404);
135135 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);
136151 expect((await api("bob", "GET")).status).toBe(403);
137152 expect((await api("bob", "POST", { op: "pin", slug: "mine", title: "Pin A" })).status).toBe(403);
138153 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", () => {
285285 const put = await api("/api/v1/boards/api-board", tok.admin, { method: "PUT", body: JSON.stringify(mine) });
286286 expect(put.status).toBe(200);
287287 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");
290291 const one = (await (await api("/api/v1/boards/api-board", tok.admin)).json()) as { title: string; refresh: string };
291292 expect([one.title, one.refresh]).toEqual(["Api board", "1m"]);
292293 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", () => {
294295 expect((await readBoard(app.reposRoot, "api-board"))?.title).toBe("Renamed");
295296 });
296297
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
297316 test("a board failing parseQuery is refused on write and drawn as an error panel on read", async () => {
298317 const bad = { ...mine, panels: [panel("Broken", { source: "runs", aggregate: "median" })] };
299318 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs