Public: anyone can read this; the crew can change it.
A repository's events page through the API and MCP `events`: `{ items, next_cursor }`, bounded, with the reader's view kept #4780
scout/forge:scout/4772-a-repository-s-events-page-through-the-a → main 2 commits fork
10 files
changed +161
−12
README.md +1 −1
| @@ -208,7 +208,7 @@ runs no check and no preview until a writer approves its head or lets it run | ||
| 208 | 208 | (**Let it run here**, which is not a review; a new push waits again), and a bare push to `child/…` starts none. A pull |
| 209 | 209 | opened with it says "proposed by child … from …" on every tab of the pull's |
| 210 | 210 | page, in the terminal's pull view, and as `proposal` in the pull's JSON |
| 211 | (`GET …/pulls/:number`, and MCP's `pull` tool). `GET …/pulls/:number?diff=0` reads the pull without its diff (and skips computing it); `diff` is `0` or `1`, default `1`, and anything else answers 422. `GET …/issues?fields=brief` lists issues with only number, kind, title, state, labels, assignee, author, originAuthor, authorIsAgent, createdAt and updatedAt (and `untrusted` where it applies); no bodies or comments. `fields` is `brief` or left out, and anything else answers 422 `invalid_fields`. | |
| 211 | (`GET …/pulls/:number`, and MCP's `pull` tool). `GET …/pulls/:number?diff=0` reads the pull without its diff (and skips computing it); `diff` is `0` or `1`, default `1`, and anything else answers 422. `GET …/issues?fields=brief` lists issues with only number, kind, title, state, labels, assignee, author, originAuthor, authorIsAgent, createdAt and updatedAt (and `untrusted` where it applies); no bodies or comments. `fields` is `brief` or left out, and anything else answers 422 `invalid_fields`. `GET …/repos/:owner/:name/events` answers `{ items, next_cursor }`, newest first, `limit` 1 to 200 (default 50) and `cursor` from `next_cursor` (anything else is a 422); it used to answer a bare array of every event, so a client that read the array reads `items` now. MCP's `events` tool answers the same. | |
| 212 | 212 | |
| 213 | 213 | ### Proposing to a parent forge |
| 214 | 214 |
docs/MCP.md +1
| @@ -46,6 +46,7 @@ for a tunnel and a forge that sleeps. | ||
| 46 | 46 | | `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes | |
| 47 | 47 | | `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes | |
| 48 | 48 | | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes | |
| 49 | | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | no | | |
| 49 | 50 | | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes | |
| 50 | 51 | | `branches` | `{ repo, name?, action?, from? }`: without `name`, lists the branches; with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes | |
| 51 | 52 | | `commits` | `{ repo, ref?, limit? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers | | |
src/contract/openapi.ts +1
| @@ -92,6 +92,7 @@ export const ROUTES: readonly Route[] = [ | ||
| 92 | 92 | auth: true, |
| 93 | 93 | body: { body: "string" }, |
| 94 | 94 | }, |
| 95 | { method: "get", path: `${REPO}/events`, summary: "Page through a repository's events as the caller may see them, newest first: {items, next_cursor}; limit 1 to 200 (default 50), cursor from next_cursor; a bad limit or cursor is a 422", auth: false, query: { limit: "integer", cursor: "string" } }, | |
| 95 | 96 | { method: "post", path: `${REPO}/forks`, summary: "Fork a repository", auth: true }, |
| 96 | 97 | { |
| 97 | 98 | method: "post", |
src/core/events.ts +11
| @@ -110,7 +110,14 @@ const afterEvent = (n: number): string => | ||
| 110 | 110 | THEN event.seq > (SELECT c.seq FROM event AS c WHERE c.id = ?${n}) |
| 111 | 111 | ELSE event.id > ?${n} END)`; |
| 112 | 112 | |
| 113 | const beforeEvent = (n: number): string => | |
| 114 | `(CASE WHEN EXISTS (SELECT 1 FROM event AS c WHERE c.id = ?${n}) | |
| 115 | THEN event.seq < (SELECT c.seq FROM event AS c WHERE c.id = ?${n}) | |
| 116 | ELSE event.id < ?${n} END)`; | |
| 117 | ||
| 113 | 118 | export interface ListEventsOptions { |
| 119 | /** Return events written before this one (exclusive; the next page of a newest-first read). */ | |
| 120 | beforeId?: string; | |
| 114 | 121 | repoId?: string; |
| 115 | 122 | /** Restrict to events of this kind. */ |
| 116 | 123 | kind?: string; |
| @@ -206,6 +213,10 @@ export function listEvents( | ||
| 206 | 213 | params.push(options.afterId); |
| 207 | 214 | clauses.push(afterEvent(params.length)); |
| 208 | 215 | } |
| 216 | if (options.beforeId !== undefined) { | |
| 217 | params.push(options.beforeId); | |
| 218 | clauses.push(beforeEvent(params.length)); | |
| 219 | } | |
| 209 | 220 | params.push(options.limit ?? 100); |
| 210 | 221 | const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : ""; |
| 211 | 222 | const limit = params.length; |
src/core/events_page.ts added +49
| @@ -0,0 +1,49 @@ | ||
| 1 | import type { Database } from "bun:sqlite"; | |
| 2 | import { audienceFilter, eventForReader } from "./event_audience.ts"; | |
| 3 | import { listEvents } from "./events.ts"; | |
| 4 | ||
| 5 | export const EVENTS_LIMIT_DEFAULT = 50; | |
| 6 | export const EVENTS_LIMIT_MAX = 200; | |
| 7 | ||
| 8 | /** Read a `limit` as the API and MCP both take it: a whole number, 1 to 200, or undefined. */ | |
| 9 | export function eventsLimit(raw: unknown): number | undefined { | |
| 10 | if (raw === undefined || raw === null) return EVENTS_LIMIT_DEFAULT; | |
| 11 | const n = typeof raw === "string" ? (/^\d{1,4}$/.test(raw) ? Number(raw) : 0) : Number(raw); | |
| 12 | return Number.isInteger(n) && n >= 1 && n <= EVENTS_LIMIT_MAX ? n : undefined; | |
| 13 | } | |
| 14 | ||
| 15 | /** A cursor is the id of the last event of the page before. */ | |
| 16 | export const validEventsCursor = (raw: string): boolean => /^[A-Za-z0-9_-]{1,64}$/.test(raw); | |
| 17 | ||
| 18 | /** | |
| 19 | * A repository's events as this reader is meant to see them, newest first, | |
| 20 | * one bounded page. The audience filter runs before the page is cut, so a | |
| 21 | * hidden event never shifts a page or leaks through the cursor. | |
| 22 | */ | |
| 23 | export function eventsPage( | |
| 24 | db: Database, | |
| 25 | repoId: string, | |
| 26 | viewer: Parameters<typeof audienceFilter>[1], | |
| 27 | limit: number, | |
| 28 | cursor?: string, | |
| 29 | ) { | |
| 30 | const visible = audienceFilter(db, viewer); | |
| 31 | const toReader = eventForReader(db, viewer); | |
| 32 | const found: ReturnType<typeof listEvents> = []; | |
| 33 | let before = cursor; | |
| 34 | while (found.length <= limit) { | |
| 35 | const batch = listEvents(db, { | |
| 36 | repoId, | |
| 37 | limit: EVENTS_LIMIT_MAX, | |
| 38 | ...(before === undefined ? {} : { beforeId: before }), | |
| 39 | }); | |
| 40 | for (const event of batch) if (visible(event)) found.push(event); | |
| 41 | if (batch.length < EVENTS_LIMIT_MAX) break; | |
| 42 | before = batch[batch.length - 1]!.id; | |
| 43 | } | |
| 44 | const page = found.slice(0, limit); | |
| 45 | return { | |
| 46 | items: page.map(toReader), | |
| 47 | next_cursor: found.length > limit ? page[page.length - 1]!.id : null, | |
| 48 | }; | |
| 49 | } |
src/http/api.ts +9 −5
| @@ -179,6 +179,7 @@ import { | ||
| 179 | 179 | updateProfile, |
| 180 | 180 | } from "../actions/users.ts"; |
| 181 | 181 | import { listEvents } from "../core/events.ts"; |
| 182 | import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts"; | |
| 182 | 183 | import { audienceFor } from "../core/audience.ts"; |
| 183 | 184 | import { audienceFilter, eventForReader } from "../core/event_audience.ts"; |
| 184 | 185 | import { |
| @@ -2478,11 +2479,14 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 2478 | 2479 | if (!repo) return notFound(); |
| 2479 | 2480 | // The outbox, as this reader is meant to see it: a webhook's URL and an |
| 2480 | 2481 | // app's variable names are the admins', not every reader's. |
| 2481 | return json( | |
| 2482 | listEvents(ctx.app.db, { repoId: repo.id }).filter( | |
| 2483 | audienceFilter(ctx.app.db, ctx.auth.user), | |
| 2484 | ).map(eventForReader(ctx.app.db, ctx.auth.user)), | |
| 2485 | ); | |
| 2482 | const q = ctx.url.searchParams; | |
| 2483 | const limit = eventsLimit(q.get("limit")); | |
| 2484 | if (limit === undefined) | |
| 2485 | return apiError("invalid_limit", 422, `limit is a whole number from 1 to ${EVENTS_LIMIT_MAX}`); | |
| 2486 | const cursor = q.get("cursor"); | |
| 2487 | if (cursor !== null && !validEventsCursor(cursor)) | |
| 2488 | return apiError("invalid_cursor", 422, "cursor is the next_cursor of a page before"); | |
| 2489 | return json(eventsPage(ctx.app.db, repo.id, ctx.auth.user, limit, cursor ?? undefined)); | |
| 2486 | 2490 | }); |
| 2487 | 2491 | |
| 2488 | 2492 | router.add("GET", "/api/v1/repos/:owner/:name/forks", (ctx) => { |
src/http/mcp.ts +25
| @@ -18,6 +18,7 @@ | ||
| 18 | 18 | */ |
| 19 | 19 | |
| 20 | 20 | import { showProvenance } from "../actions/provenance.ts"; |
| 21 | import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../core/events_page.ts"; | |
| 21 | 22 | import { getProvenance, provenanceFacts, trailFacts } from "../core/provenance.ts"; |
| 22 | 23 | import { upstreamPayload } from "../spawn/upstream.ts"; |
| 23 | 24 | import { NOT_A_MEMBER } from "../core/roles.ts"; |
| @@ -1757,6 +1758,30 @@ const TOOLS: readonly Tool[] = [ | ||
| 1757 | 1758 | }); |
| 1758 | 1759 | }, |
| 1759 | 1760 | }, |
| 1761 | { | |
| 1762 | name: "events", | |
| 1763 | description: "A repository's recent events, newest first: `{ items, next_cursor }`.", | |
| 1764 | inputSchema: { | |
| 1765 | type: "object", | |
| 1766 | properties: { | |
| 1767 | repo: REPO_ARG, | |
| 1768 | limit: { type: "integer", minimum: 1, maximum: EVENTS_LIMIT_MAX }, | |
| 1769 | cursor: { type: "string" }, | |
| 1770 | }, | |
| 1771 | required: ["repo"], | |
| 1772 | }, | |
| 1773 | writes: false, | |
| 1774 | run(ctx, user, args) { | |
| 1775 | const repo = repoArg(ctx, user, args); | |
| 1776 | if (isAnswer(repo)) return repo; | |
| 1777 | const limit = eventsLimit(args["limit"]); | |
| 1778 | if (limit === undefined) return bad("invalid", `limit is 1 to ${EVENTS_LIMIT_MAX}`); | |
| 1779 | const given = args["cursor"]; | |
| 1780 | if (given !== undefined && (typeof given !== "string" || !validEventsCursor(given))) | |
| 1781 | return bad("invalid", "that cursor was not issued here"); | |
| 1782 | return good(eventsPage(ctx.app.db, repo.id, user, limit, given)); | |
| 1783 | }, | |
| 1784 | }, | |
| 1760 | 1785 | { |
| 1761 | 1786 | name: "branches", |
| 1762 | 1787 | description: |
test/app.test.ts +3 −4
| @@ -186,10 +186,9 @@ describe("the forge, end to end", () => { | ||
| 186 | 186 | await shOk(["git", "push", "origin", "main"], dir); |
| 187 | 187 | |
| 188 | 188 | const events = await api("/api/v1/repos/alice/app/events"); |
| 189 | const list = (await events.json()) as { | |
| 190 | kind: string; | |
| 191 | payload: { updates?: { ref: string }[] }; | |
| 192 | }[]; | |
| 189 | const list = ((await events.json()) as { | |
| 190 | items: { kind: string; payload: { updates?: { ref: string }[] } }[]; | |
| 191 | }).items; | |
| 193 | 192 | const push = list.find((e) => e.kind === "push"); |
| 194 | 193 | expect(push).toBeDefined(); |
| 195 | 194 | expect(push?.payload.updates?.[0]?.ref).toBe("refs/heads/main"); |
test/event-audience.test.ts +60 −2
| @@ -187,8 +187,8 @@ describe("who an event is for", () => { | ||
| 187 | 187 | }); |
| 188 | 188 | const read = (headers: Record<string, string>) => |
| 189 | 189 | fetch(`${base}/api/v1/repos/alice/open/events`, { headers }) |
| 190 | .then((r) => r.json() as Promise<{ kind: string; payload: Record<string, unknown> }[]>) | |
| 191 | .then((all) => all.find((e) => e.kind === "run.finished")!); | |
| 190 | .then((r) => r.json() as Promise<{ items: { kind: string; payload: Record<string, unknown> }[] }>) | |
| 191 | .then((all) => all.items.find((e) => e.kind === "run.finished")!); | |
| 192 | 192 | for (const headers of [{}, { authorization: `Bearer ${bobToken}` }]) { |
| 193 | 193 | const seen = await read(headers); |
| 194 | 194 | expect(seen.payload["runId"]).toBe("r1"); |
| @@ -203,6 +203,64 @@ describe("who an event is for", () => { | ||
| 203 | 203 | expect(owner.payload["node"]).toBe("vx-secret-node"); |
| 204 | 204 | }); |
| 205 | 205 | |
| 206 | test("MCP `events` keeps the reader's view: no webhook URL or variable name for a reader, all for an admin", async () => { | |
| 207 | const call = async (token: string, args: unknown) => { | |
| 208 | const res = await fetch(`${base}/mcp`, { | |
| 209 | method: "POST", | |
| 210 | headers: { | |
| 211 | "content-type": "application/json", | |
| 212 | accept: "application/json, text/event-stream", | |
| 213 | authorization: `Bearer ${token}`, | |
| 214 | }, | |
| 215 | body: JSON.stringify({ | |
| 216 | jsonrpc: "2.0", | |
| 217 | id: 1, | |
| 218 | method: "tools/call", | |
| 219 | params: { name: "events", arguments: args }, | |
| 220 | }), | |
| 221 | }); | |
| 222 | return ((await res.json()) as any).result as { isError?: boolean; content: { text: string }[] }; | |
| 223 | }; | |
| 224 | const reader = await call(bobToken, { repo: "alice/open" }); | |
| 225 | expect(reader.isError).not.toBe(true); | |
| 226 | const text = reader.content[0]!.text; | |
| 227 | expect(text).toContain('"push"'); | |
| 228 | expect(text).toContain("next_cursor"); | |
| 229 | expect(text).not.toContain("hooks.example.test"); | |
| 230 | expect(text).not.toContain("STRIPE_SECRET_KEY"); | |
| 231 | const admin = (await call(aliceToken, { repo: "alice/open" })).content[0]!.text; | |
| 232 | expect(admin).toContain("webhook.created"); | |
| 233 | expect(admin).toContain("app.env_set"); | |
| 234 | expect((await call(bobToken, { repo: "alice/open", limit: 0 })).isError).toBe(true); | |
| 235 | expect((await call(bobToken, { repo: "alice/open", limit: 201 })).isError).toBe(true); | |
| 236 | }); | |
| 237 | ||
| 238 | test("the API pages events: limit cuts, next_cursor reaches the end, a bad limit is a 422", async () => { | |
| 239 | const get = (qs: string) => | |
| 240 | fetch(`${base}/api/v1/repos/alice/open/events${qs}`, { | |
| 241 | headers: { authorization: `Bearer ${aliceToken}` }, | |
| 242 | }); | |
| 243 | type Page = { items: { id: string }[]; next_cursor: string | null }; | |
| 244 | const everything = (await (await get("")).json()) as Page; | |
| 245 | expect(everything.next_cursor).toBeNull(); | |
| 246 | expect(everything.items.length).toBeGreaterThan(3); | |
| 247 | const seen: string[] = []; | |
| 248 | let cursor: string | null = null; | |
| 249 | let pages = 0; | |
| 250 | do { | |
| 251 | const page = (await (await get(`?limit=2${cursor ? `&cursor=${cursor}` : ""}`)).json()) as Page; | |
| 252 | expect(page.items.length).toBeLessThanOrEqual(2); | |
| 253 | seen.push(...page.items.map((e) => e.id)); | |
| 254 | cursor = page.next_cursor; | |
| 255 | pages++; | |
| 256 | } while (cursor !== null && pages < 100); | |
| 257 | expect(cursor).toBeNull(); | |
| 258 | expect(pages).toBeGreaterThan(1); | |
| 259 | expect(seen).toEqual(everything.items.map((e) => e.id)); | |
| 260 | for (const bad of ["limit=0", "limit=201", "limit=abc", "limit=1.5", "cursor=a%20b"]) | |
| 261 | expect((await get(`?${bad}`)).status).toBe(422); | |
| 262 | }); | |
| 263 | ||
| 206 | 264 | test("the activity rail on the front page says nothing of it to a visitor", async () => { |
| 207 | 265 | const page = await fetch(`${base}/`, { |
| 208 | 266 | headers: { accept: "text/html" }, |
test/mcp.test.ts +1
| @@ -206,6 +206,7 @@ describe("the forge over MCP", () => { | ||
| 206 | 206 | "decisions_by", |
| 207 | 207 | "archive", |
| 208 | 208 | "trail", |
| 209 | "events", | |
| 209 | 210 | "branches", |
| 210 | 211 | "commits", |
| 211 | 212 | "probe", |
new above
offline