Public: anyone can read this; the crew can change it.
A repository's reports and milestones answer `{ items, next_cursor }` #5075
scout/forge:scout/5044-a-repository-s-reports-and-milestones-an → main 9 commits fork 3 threads · 3 unresolved
10 files
changed +112
−17
docs/MCP.md +1 −1
| @@ -83,7 +83,7 @@ for a tunnel and a forge that sleeps. | ||
| 83 | 83 | | `front_page` | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes | |
| 84 | 84 | | `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes | |
| 85 | 85 | | `map` | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card | | |
| 86 | | `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) | | | |
| 86 | | `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights (as `{ repo, items, next_cursor }`), or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) | | | |
| 87 | 87 | | `limb` | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes | |
| 88 | 88 | | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes | |
| 89 | 89 | | `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them | | |
src/contract/openapi.ts +2 −1
| @@ -195,6 +195,8 @@ export const ROUTES: readonly Route[] = [ | ||
| 195 | 195 | auth: false, |
| 196 | 196 | body: { title: "string", body: "string", page: "string" }, |
| 197 | 197 | }, |
| 198 | { method: "get", path: `${REPO}/reports`, summary: "List the reports waiting for a writer, as { items, next_cursor }; limit is 1 to 200 (default 50), anything else a 422 invalid_limit", auth: true, query: { limit: "integer", cursor: "string" } }, | |
| 199 | { method: "get", path: `${REPO}/milestones`, summary: "List the plan's limbs as { repo, items, next_cursor }; limit is 1 to 200 (default 50), anything else a 422 invalid_limit; a private repository needs a token", auth: false, query: { limit: "integer", cursor: "string" } }, | |
| 198 | 200 | { |
| 199 | 201 | method: "get", |
| 200 | 202 | path: "/api/v1/admin/settings", |
| @@ -297,7 +299,6 @@ export const ROUTES: readonly Route[] = [ | ||
| 297 | 299 | { method: "get", path: `${REPO}/commits/{oid}`, summary: "Read one commit (a full or abbreviated id, or a ref) as { oid, parents, author, email, date, subject, body, diff: { files, additions, deletions } }; a private repository needs a token", auth: false }, |
| 298 | 300 | { method: "get", path: `${REPO}/contents`, summary: "Read the tree or a file at `ref` (default: the default branch); no `path` or a directory answers { type: \"dir\", ref, path, entries }, a file answers { type: \"file\", ref, path, size, encoding: \"utf-8\" | \"base64\", content }, a file over 5 MB is a 413 { type: \"file\", tooLarge: true, size }; a private repository needs a token", auth: false, query: { path: "string", ref: "string" } }, |
| 299 | 301 | { method: "get", path: `${REPO}/labels`, summary: "List a repository's labels by name as a bare array of { id, name, color }; a private repository needs a token", auth: false }, |
| 300 | { method: "get", path: `${REPO}/milestones`, summary: "Read the plan: { repo: { owner, name }, limbs }, one limb per milestone with its weights (and askToLive for a pillar's umbrella); a private repository needs a token", auth: false }, | |
| 301 | 302 | { method: "get", path: `${REPO}/milestones/{number}`, summary: "Read one milestone (a 404 for an issue that waits for nothing) as { repo, ...milestone, askToLive?, watching? }; watching is present only for a signed-in user; a private repository needs a token", auth: false }, |
| 302 | 303 | { |
| 303 | 304 | method: "post", |
src/http/api.ts +12 −2
| @@ -3313,6 +3313,8 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 3313 | 3313 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 3314 | 3314 | const denied = requireScope(ctx, "rw"); |
| 3315 | 3315 | if (denied) return denied; |
| 3316 | const query = offsetQuery(ctx.url.searchParams); | |
| 3317 | if ("error" in query) return offsetRefused(query.error); | |
| 3316 | 3318 | const repo = loadRepo(ctx); |
| 3317 | 3319 | if (!repo) return notFound(); |
| 3318 | 3320 | const waiting = timePhase(ctx.request, "reports", () => |
| @@ -3320,7 +3322,13 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 3320 | 3322 | ); |
| 3321 | 3323 | if (!waiting.ok) return respondAccess(waiting.error, 403); |
| 3322 | 3324 | return timePhase(ctx.request, "render", () => |
| 3323 | json({ items: waiting.value.map((r) => ({ ...r, from: "outside" })) }), | |
| 3325 | json( | |
| 3326 | offsetPage( | |
| 3327 | waiting.value.map((r) => ({ ...r, from: "outside" })), | |
| 3328 | query.limit, | |
| 3329 | query.offset, | |
| 3330 | ), | |
| 3331 | ), | |
| 3324 | 3332 | ); |
| 3325 | 3333 | }); |
| 3326 | 3334 | |
| @@ -3620,10 +3628,12 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 3620 | 3628 | // milestone opened. The same numbers as the pages. |
| 3621 | 3629 | router.add("GET", "/api/v1/repos/:owner/:name/milestones", async (ctx) => { |
| 3622 | 3630 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 3631 | const query = offsetQuery(ctx.url.searchParams); | |
| 3632 | if ("error" in query) return offsetRefused(query.error); | |
| 3623 | 3633 | const repo = loadRepo(ctx); |
| 3624 | 3634 | if (!repo) return notFound(); |
| 3625 | 3635 | const data = await timePhaseAsync(ctx.request, "read", () => |
| 3626 | milestonesJson(ctx, repo), | |
| 3636 | milestonesJson(ctx, repo, query), | |
| 3627 | 3637 | ); |
| 3628 | 3638 | return timePhase(ctx.request, "render", () => json(data)); |
| 3629 | 3639 | }); |
src/web/pages/milestones.ts +7 −4
| @@ -10,6 +10,7 @@ | ||
| 10 | 10 | * Read-only: the page, the API and the MCP tool give the same numbers. |
| 11 | 11 | */ |
| 12 | 12 | |
| 13 | import { offsetPage } from "../../http/offset_page.ts"; | |
| 13 | 14 | import { |
| 14 | 15 | limbJson, |
| 15 | 16 | milestoneJson, |
| @@ -606,17 +607,19 @@ export async function milestoneWatch(ctx: Ctx): Promise<Response> { | ||
| 606 | 607 | export async function milestonesJson( |
| 607 | 608 | ctx: Ctx, |
| 608 | 609 | repo: Repo, |
| 610 | page: { limit: number; offset: number } = { limit: Infinity, offset: 0 }, | |
| 609 | 611 | ): Promise<Record<string, unknown>> { |
| 610 | 612 | const plan = readPlan(ctx.app.db, repo, { |
| 611 | 613 | spend: canSeeOwnerFacts(ctx.app.db, repo, ctx.auth.user), |
| 612 | 614 | }); |
| 613 | 615 | const ask = askByUmbrella(ctx, repo); |
| 616 | const limbs = plan.limbs.map((limb) => ({ | |
| 617 | ...limbJson(limb), | |
| 618 | ...askOf(ask, limb.issue.number), | |
| 619 | })); | |
| 614 | 620 | return { |
| 615 | 621 | repo: { owner: repo.ownerName, name: repo.name }, |
| 616 | limbs: plan.limbs.map((limb) => ({ | |
| 617 | ...limbJson(limb), | |
| 618 | ...askOf(ask, limb.issue.number), | |
| 619 | })), | |
| 622 | ...offsetPage(limbs, page.limit, page.offset), | |
| 620 | 623 | }; |
| 621 | 624 | } |
| 622 | 625 |
src/web/studio/cards.ts +1 −1
| @@ -179,7 +179,7 @@ export function cardFor(tool: string, value: unknown, origin = ""): Card | undef | ||
| 179 | 179 | }); |
| 180 | 180 | } |
| 181 | 181 | } else { |
| 182 | const limbs = list(obj(value)["limbs"]).map(obj); | |
| 182 | const limbs = list(obj(value)["items"]).map(obj); | |
| 183 | 183 | const repo = obj(obj(value)["repo"]); |
| 184 | 184 | status = `${text(repo["owner"])}/${text(repo["name"])}`.replace(/^\/$/, ""); |
| 185 | 185 | for (const l of limbs.slice(0, LIMIT)) |
test/api-milestones-timing.test.ts +1 −1
| @@ -82,7 +82,7 @@ test("the proposals read names session, read, render", async () => { | ||
| 82 | 82 | |
| 83 | 83 | test("one milestone names session, read, render; a miss names session and read", async () => { |
| 84 | 84 | const list = JSON.parse((await phases("/api/v1/repos/alice/r/milestones")).body); |
| 85 | expect(list.limbs.length).toBeGreaterThan(0); | |
| 85 | expect(list.items.length).toBeGreaterThan(0); | |
| 86 | 86 | const got = await phases(`/api/v1/repos/alice/r/milestones/${umbrella}`); |
| 87 | 87 | expect(got.status).toBe(200); |
| 88 | 88 | expect(got.names).toEqual(["session", "read", "render"]); |
test/mcp.test.ts +25
| @@ -1160,6 +1160,31 @@ describe("the forge over MCP", () => { | ||
| 1160 | 1160 | expect(asks.body.result.structuredContent.card.kind).toBe("decision"); |
| 1161 | 1161 | }); |
| 1162 | 1162 | |
| 1163 | test("the milestones card draws one row per limb of the plan", async () => { | |
| 1164 | const open = (title: string) => { | |
| 1165 | const made = createIssue(app.db, { repoId: game.id, authorId: alice.id, title }); | |
| 1166 | if (!made.ok) throw new Error(String(made.error)); | |
| 1167 | return made.value; | |
| 1168 | }; | |
| 1169 | const limb = open("P0 Trust: agents contained"); | |
| 1170 | const later = open("Later: work that serves no pillar now"); | |
| 1171 | const gate = open("Later gate: nothing behind this starts"); | |
| 1172 | const step = open("a step"); | |
| 1173 | for (const [on, under] of [[limb, step], [gate, limb], [later, gate]] as const) { | |
| 1174 | const linked = addDependency(app.db, on, under, alice.id); | |
| 1175 | if (!linked.ok) throw new Error(String(linked.error)); | |
| 1176 | } | |
| 1177 | const { body } = await call(rw, "tools/call", { name: "milestones", arguments: { app: "alice/game" } }); | |
| 1178 | if (body.result.isError) throw new Error(body.result.content[0].text); | |
| 1179 | const card = body.result.structuredContent.card; | |
| 1180 | expect(card.kind).toBe("wave"); | |
| 1181 | expect(card.status).toBe("alice/game"); | |
| 1182 | const row = card.rows.find((r: any) => r.label.includes("P0 Trust")); | |
| 1183 | expect(row).toBeDefined(); | |
| 1184 | expect(row.label).toBe(`#${limb.number} P0 Trust`); | |
| 1185 | expect(row.value).toStartWith("0/1 done"); | |
| 1186 | }); | |
| 1187 | ||
| 1163 | 1188 | test("ship and close card actions never apply at once and always meet the target tool's required fields", async () => { |
| 1164 | 1189 | const { cardFor } = await import("../src/web/studio/cards.ts"); |
| 1165 | 1190 | const tools = (await call(rw, "tools/list")).body.result.tools; |
test/milestones.test.ts +30 −4
| @@ -434,16 +434,42 @@ describe("milestones", () => { | ||
| 434 | 434 | } |
| 435 | 435 | }); |
| 436 | 436 | |
| 437 | test("the milestones list pages with limit and next_cursor, and refuses a bad one", async () => { | |
| 438 | const all = (await (await api("/api/v1/repos/alice/engine/milestones")).json()) as { | |
| 439 | items: Record<string, unknown>[]; | |
| 440 | next_cursor: string | null; | |
| 441 | }; | |
| 442 | expect(all.next_cursor).toBeNull(); | |
| 443 | expect(all.items.length).toBeGreaterThan(1); | |
| 444 | const seen: unknown[] = []; | |
| 445 | let cursor: string | null = null; | |
| 446 | do { | |
| 447 | const page = (await ( | |
| 448 | await api(`/api/v1/repos/alice/engine/milestones?limit=1${cursor === null ? "" : `&cursor=${cursor}`}`) | |
| 449 | ).json()) as { items: Record<string, unknown>[]; next_cursor: string | null }; | |
| 450 | expect(page.items.length).toBe(1); | |
| 451 | seen.push(page.items[0]!["number"]); | |
| 452 | cursor = page.next_cursor; | |
| 453 | } while (cursor !== null); | |
| 454 | expect(seen).toEqual(all.items.map((l) => l["number"])); | |
| 455 | for (const bad of ["limit=0", "limit=201", "limit=x"]) { | |
| 456 | const res = await api(`/api/v1/repos/alice/engine/milestones?${bad}`); | |
| 457 | expect(res.status).toBe(422); | |
| 458 | expect(((await res.json()) as any).error).toBe("invalid_limit"); | |
| 459 | } | |
| 460 | expect((await api("/api/v1/repos/alice/engine/milestones?cursor=-1")).status).toBe(422); | |
| 461 | }); | |
Minor: this checks only the status. Also check that |
||
| 462 | ||
| 437 | 463 | test("the API and the MCP's `milestones` return the same numbers", async () => { |
| 438 | 464 | const limbs = (await ( |
| 439 | 465 | await api("/api/v1/repos/alice/engine/milestones") |
| 440 | ).json()) as { limbs: Record<string, unknown>[] }; | |
| 441 | expect(limbs.limbs.map((l) => l["name"])).toEqual([ | |
| 466 | ).json()) as { items: Record<string, unknown>[] }; | |
| 467 | expect(limbs.items.map((l) => l["name"])).toEqual([ | |
| 442 | 468 | "P0 Trust", |
| 443 | 469 | "P1 Feed", |
| 444 | 470 | "Later", |
| 445 | 471 | ]); |
| 446 | expect(limbs.limbs[0]).toMatchObject({ | |
| 472 | expect(limbs.items[0]).toMatchObject({ | |
| 447 | 473 | number: trust.number, |
| 448 | 474 | done: 1, |
| 449 | 475 | total: 5, |
| @@ -453,7 +479,7 @@ describe("milestones", () => { | ||
| 453 | 479 | spentUsd: 1.5, |
| 454 | 480 | deferred: false, |
| 455 | 481 | }); |
| 456 | expect(limbs.limbs[1]).toMatchObject({ | |
| 482 | expect(limbs.items[1]).toMatchObject({ | |
| 457 | 483 | trim: "12 open and nobody building", |
| 458 | 484 | }); |
| 459 | 485 | expect((await tool({ app: "alice/engine" })).value).toEqual(limbs); |
test/pillars.test.ts +3 −3
| @@ -553,10 +553,10 @@ describe("pillars", () => { | ||
| 553 | 553 | const mcp = await tool("map", { app: "alice/engine" }); |
| 554 | 554 | expect(mcp.value.mergedByPillar).toEqual(data.mergedByPillar); |
| 555 | 555 | const limbs = await tool("milestones", { app: "alice/engine" }); |
| 556 | const limb = limbs.value.limbs.find((l: any) => l.number === trust.number); | |
| 556 | const limb = limbs.value.items.find((l: any) => l.number === trust.number); | |
| 557 | 557 | expect(limb.askToLive).toEqual(counts[0].askToLive); |
| 558 | 558 | expect( |
| 559 | limbs.value.limbs.find((l: any) => l.number === feed.number).askToLive, | |
| 559 | limbs.value.items.find((l: any) => l.number === feed.number).askToLive, | |
| 560 | 560 | ).toBeNull(); |
| 561 | 561 | |
| 562 | 562 | const page = await get("/alice/engine/map"); |
| @@ -606,7 +606,7 @@ describe("pillars", () => { | ||
| 606 | 606 | expect(viaMcp.mergedByPillar).toEqual(data.mergedByPillar); |
| 607 | 607 | const limbs = await bobTool("milestones"); |
| 608 | 608 | expect( |
| 609 | limbs.limbs.find((l: any) => l.number === trust.number).askToLive.slowest.number, | |
| 609 | limbs.items.find((l: any) => l.number === trust.number).askToLive.slowest.number, | |
| 610 | 610 | ).toBe(parts[0]!.number); |
| 611 | 611 | // A writer still sees it. |
| 612 | 612 | expect(await get("/alice/engine/map")).toContain(sealedLink); |
test/reports.test.ts +30
| @@ -297,6 +297,36 @@ describe("reports from outside", () => { | ||
| 297 | 297 | expect(await bot.text()).not.toContain("SECRET-PHRASE"); |
| 298 | 298 | }); |
| 299 | 299 | |
| 300 | test("the list pages with limit and next_cursor to the end, and refuses a bad one", async () => { | |
| 301 | for (const n of [1, 2, 3]) | |
| 302 | expect((await report("alice/game", { title: `Paged ${n}`, body: "b" })).status).toBe(202); | |
| 303 | const seen: string[] = []; | |
| 304 | let cursor: string | null = null; | |
| 305 | let pages = 0; | |
| 306 | do { | |
| 307 | const res = await as( | |
| 308 | aliceToken, | |
| 309 | `/api/v1/repos/alice/game/reports?limit=2${cursor === null ? "" : `&cursor=${cursor}`}`, | |
| 310 | ); | |
| 311 | const page = (await res.json()) as { items: any[]; next_cursor: string | null }; | |
| 312 | expect(page.items.length).toBeLessThanOrEqual(2); | |
| 313 | expect(page.items.every((r) => r.from === "outside")).toBe(true); | |
| 314 | seen.push(...page.items.map((r) => r.id)); | |
| 315 | cursor = page.next_cursor; | |
| 316 | pages++; | |
| 317 | } while (cursor !== null); | |
| 318 | const all = (await (await as(aliceToken, "/api/v1/repos/alice/game/reports")).json()) as any; | |
| 319 | expect(all.next_cursor).toBeNull(); | |
| 320 | expect(seen).toEqual(all.items.map((r: any) => r.id)); | |
| 321 | expect(pages).toBeGreaterThan(1); | |
| 322 | for (const bad of ["limit=0", "limit=201", "limit=x", "limit=-1"]) { | |
| 323 | const res = await as(aliceToken, `/api/v1/repos/alice/game/reports?${bad}`); | |
| 324 | expect(res.status).toBe(422); | |
| 325 | expect(((await res.json()) as any).error).toBe("invalid_limit"); | |
| 326 | } | |
| 327 | expect((await as(aliceToken, "/api/v1/repos/alice/game/reports?cursor=x!")).status).toBe(422); | |
| 328 | }); | |
| 329 | ||
| 300 | 330 | test("accepting makes an ordinary issue by the person, the text fenced as unchecked", async () => { |
| 301 | 331 | const listed = await as(aliceToken, "/api/v1/repos/alice/game/reports"); |
| 302 | 332 | expect(listed.status).toBe(200); |
new above
offline
This drops
limbs, butsrc/web/studio/cards.ts:182still readsvalue.limbsto draw the MCP milestones card, so the card now renders empty. Change it to readitemsand add a test for the card's rows.