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

A repository's reports and milestones answer `{ items, next_cursor }` #5075

Parked opened this
Closed without merging

scout/forge:scout/5044-a-repository-s-reports-and-milestones-an → main 9 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
10 files changed +112 −17
docs/MCP.md +1 −1
@@ -83,7 +83,7 @@ for a tunnel and a forge that sleeps.
8383 | `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 |
8484 | `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 |
8585 | `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) | |
8787 | `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 |
8888 | `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 |
8989 | `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[] = [
195195 auth: false,
196196 body: { title: "string", body: "string", page: "string" },
197197 },
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" } },
198200 {
199201 method: "get",
200202 path: "/api/v1/admin/settings",
@@ -297,7 +299,6 @@ export const ROUTES: readonly Route[] = [
297299 { 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 },
298300 { 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" } },
299301 { 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 },
301302 { 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 },
302303 {
303304 method: "post",
src/http/api.ts +12 −2
@@ -3313,6 +3313,8 @@ export function apiRoutes(router: Router<Handler>): void {
33133313 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
33143314 const denied = requireScope(ctx, "rw");
33153315 if (denied) return denied;
3316 const query = offsetQuery(ctx.url.searchParams);
3317 if ("error" in query) return offsetRefused(query.error);
33163318 const repo = loadRepo(ctx);
33173319 if (!repo) return notFound();
33183320 const waiting = timePhase(ctx.request, "reports", () =>
@@ -3320,7 +3322,13 @@ export function apiRoutes(router: Router<Handler>): void {
33203322 );
33213323 if (!waiting.ok) return respondAccess(waiting.error, 403);
33223324 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 ),
33243332 );
33253333 });
33263334
@@ -3620,10 +3628,12 @@ export function apiRoutes(router: Router<Handler>): void {
36203628 // milestone opened. The same numbers as the pages.
36213629 router.add("GET", "/api/v1/repos/:owner/:name/milestones", async (ctx) => {
36223630 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
3631 const query = offsetQuery(ctx.url.searchParams);
3632 if ("error" in query) return offsetRefused(query.error);
36233633 const repo = loadRepo(ctx);
36243634 if (!repo) return notFound();
36253635 const data = await timePhaseAsync(ctx.request, "read", () =>
3626 milestonesJson(ctx, repo),
3636 milestonesJson(ctx, repo, query),
36273637 );
36283638 return timePhase(ctx.request, "render", () => json(data));
36293639 });
src/web/pages/milestones.ts +7 −4
@@ -10,6 +10,7 @@
1010 * Read-only: the page, the API and the MCP tool give the same numbers.
1111 */
1212
13 import { offsetPage } from "../../http/offset_page.ts";
1314 import {
1415 limbJson,
1516 milestoneJson,
@@ -606,17 +607,19 @@ export async function milestoneWatch(ctx: Ctx): Promise<Response> {
606607 export async function milestonesJson(
607608 ctx: Ctx,
608609 repo: Repo,
610 page: { limit: number; offset: number } = { limit: Infinity, offset: 0 },
609611 ): Promise<Record<string, unknown>> {
610612 const plan = readPlan(ctx.app.db, repo, {
611613 spend: canSeeOwnerFacts(ctx.app.db, repo, ctx.auth.user),
612614 });
613615 const ask = askByUmbrella(ctx, repo);
616 const limbs = plan.limbs.map((limb) => ({
617 ...limbJson(limb),
618 ...askOf(ask, limb.issue.number),
619 }));
614620 return {
615621 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),

This drops limbs, but src/web/studio/cards.ts:182 still reads value.limbs to draw the MCP milestones card, so the card now renders empty. Change it to read items and add a test for the card's rows.

620623 };
621624 }
622625
src/web/studio/cards.ts +1 −1
@@ -179,7 +179,7 @@ export function cardFor(tool: string, value: unknown, origin = ""): Card | undef
179179 });
180180 }
181181 } else {
182 const limbs = list(obj(value)["limbs"]).map(obj);
182 const limbs = list(obj(value)["items"]).map(obj);
183183 const repo = obj(obj(value)["repo"]);
184184 status = `${text(repo["owner"])}/${text(repo["name"])}`.replace(/^\/$/, "");
185185 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 () => {
8282
8383 test("one milestone names session, read, render; a miss names session and read", async () => {
8484 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);
8686 const got = await phases(`/api/v1/repos/alice/r/milestones/${umbrella}`);
8787 expect(got.status).toBe(200);
8888 expect(got.names).toEqual(["session", "read", "render"]);
test/mcp.test.ts +25
@@ -1160,6 +1160,31 @@ describe("the forge over MCP", () => {
11601160 expect(asks.body.result.structuredContent.card.kind).toBe("decision");
11611161 });
11621162
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
11631188 test("ship and close card actions never apply at once and always meet the target tool's required fields", async () => {
11641189 const { cardFor } = await import("../src/web/studio/cards.ts");
11651190 const tools = (await call(rw, "tools/list")).body.result.tools;
test/milestones.test.ts +30 −4
@@ -434,16 +434,42 @@ describe("milestones", () => {
434434 }
435435 });
436436
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 error is invalid_cursor, so the refusal is tied to the cursor and can't pass as some other 422.

462
437463 test("the API and the MCP's `milestones` return the same numbers", async () => {
438464 const limbs = (await (
439465 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([
442468 "P0 Trust",
443469 "P1 Feed",
444470 "Later",
445471 ]);
446 expect(limbs.limbs[0]).toMatchObject({
472 expect(limbs.items[0]).toMatchObject({
447473 number: trust.number,
448474 done: 1,
449475 total: 5,
@@ -453,7 +479,7 @@ describe("milestones", () => {
453479 spentUsd: 1.5,
454480 deferred: false,
455481 });
456 expect(limbs.limbs[1]).toMatchObject({
482 expect(limbs.items[1]).toMatchObject({
457483 trim: "12 open and nobody building",
458484 });
459485 expect((await tool({ app: "alice/engine" })).value).toEqual(limbs);
test/pillars.test.ts +3 −3
@@ -553,10 +553,10 @@ describe("pillars", () => {
553553 const mcp = await tool("map", { app: "alice/engine" });
554554 expect(mcp.value.mergedByPillar).toEqual(data.mergedByPillar);
555555 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);
557557 expect(limb.askToLive).toEqual(counts[0].askToLive);
558558 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,
560560 ).toBeNull();
561561
562562 const page = await get("/alice/engine/map");
@@ -606,7 +606,7 @@ describe("pillars", () => {
606606 expect(viaMcp.mergedByPillar).toEqual(data.mergedByPillar);
607607 const limbs = await bobTool("milestones");
608608 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,
610610 ).toBe(parts[0]!.number);
611611 // A writer still sees it.
612612 expect(await get("/alice/engine/map")).toContain(sealedLink);
test/reports.test.ts +30
@@ -297,6 +297,36 @@ describe("reports from outside", () => {
297297 expect(await bot.text()).not.toContain("SECRET-PHRASE");
298298 });
299299
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
300330 test("accepting makes an ordinary issue by the person, the text fenced as unchecked", async () => {
301331 const listed = await as(aliceToken, "/api/v1/repos/alice/game/reports");
302332 expect(listed.status).toBe(200);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs