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

An agent reads a pull's looks: GET …/pulls/:number/looks and MCP `pull` carry each picture with its width, line and URL #8227

Parked opened this
Closed without merging

scout/forge:scout/7915-an-agent-reads-a-pull-s-looks-get-pulls → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
9 files changed +166 −3
docs/APPS.md +3
@@ -1233,6 +1233,9 @@ that parses, nothing else), kept under the preview's folder at the pull's
12331233 head, and shown in the Look card beside the crew's, to the writers only.
12341234 It stays when the head moves on and goes with the preview when the pull
12351235 closes.
1236 An agent reads them back with `GET …/pulls/:number/looks` (`{items: [{id,
1237 width, says, by, commit, url, at}]}`, newest first, only what the reader may
1238 fetch) or the `looks` of MCP `pull`.
12361239
12371240
12381241 ## The crew
docs/MCP.md +1 −1
@@ -136,7 +136,7 @@ for a tunnel and a forge that sleeps.
136136 | `prompts` | (admin scope) `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes |
137137 | `proposal_tokens` | `{ repo, verb, child?, origin?, childRepo?, id? }`: give a child forge a propose-only credential: `mint` one (`child`, `origin`), `list` them, or `revoke` one by `id`; writers only | yes |
138138 | `propose_to_parent_forge` | `{ repo }`: offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers with that pull | yes |
139 | `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `next: { who, why }` (open only; who acts next: builder, reviewer, queue or person), and `comments` (the newest 50: author, body, at, `untrusted` on an outsider's), `commentsTotal` and `commentsNext` (older: `GET …/issues/:number/comments?cursor=`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment | |
139 | `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `next: { who, why }` (open only; who acts next: builder, reviewer, queue or person), and `comments` (the newest 50: author, body, at, `untrusted` on an outsider's), `commentsTotal` and `commentsNext` (older: `GET …/issues/:number/comments?cursor=`), and `looks` (the preview's pictures, newest first: `{ id, width, says, by, commit, url, at }`, as `GET …/pulls/:number/looks`; empty with no app), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment | |
140140 | `pulls` | `{ repo?, state?, limit?, cursor? }`: without `repo`, every open pull you may read, oldest first, as `{ pulls, next_cursor }` (limit 1-200, default 50): `repo`, `number`, `title`, `check`, `verdict` (approved, changes_requested or none) and `gate` (what holds it, or null; the `why` module's cause); with `repo`, a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs | |
141141 | `queue_gates` | `{ repo, limit? }`: the merge queue's recent gates, newest first (`limit` 1–100, default 20), as `GET …/queue/gates` answers: each gate's pulls, state, reason, counts and failing tests by name with their first error lines, a test red in two gates that share no pull flagged `flaky` | |
142142 | `quotas` | `{ key?, value?, dryRun? }` (forge admin): the per-account quotas `repositories`, `apps`, `storage` (MB), `previews`, `runs`, `checks`, each a number or null for none. `repositories` bounds repos on create, fork and copy; `apps` the apps made; `storage` the MB of repos plus app data, asked on push, create and fork; `previews` live previews; `runs` concurrent agent runs; `checks` concurrent checks. Each is asked before the thing is made or started and a forge admin is never limited; with `key` and `value` (`""` clears), planned first (`dryRun` is true unless `false`); applying needs an admin-scope token | yes |
src/contract/openapi/routes/getApiV1ReposOwnerNamePullsNumberLooks.ts added +8
@@ -0,0 +1,8 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: `${REPO}/pulls/{number}/looks`,
6 summary: "List a pull's looks, the pictures its page shows this reader, each with its width, line and URL",
7 auth: false,
8 };
src/contract/openapi/routes/index.ts +1
@@ -117,6 +117,7 @@ export { route as getApiV1ReposOwnerNamePrompts } from "./getApiV1ReposOwnerName
117117 export { route as getApiV1ReposOwnerNamePulls } from "./getApiV1ReposOwnerNamePulls.ts";
118118 export { route as getApiV1ReposOwnerNamePullsNumber } from "./getApiV1ReposOwnerNamePullsNumber.ts";
119119 export { route as getApiV1ReposOwnerNamePullsNumberChecks } from "./getApiV1ReposOwnerNamePullsNumberChecks.ts";
120 export { route as getApiV1ReposOwnerNamePullsNumberLooks } from "./getApiV1ReposOwnerNamePullsNumberLooks.ts";
120121 export { route as getApiV1ReposOwnerNamePullsNumberReviewStates } from "./getApiV1ReposOwnerNamePullsNumberReviewStates.ts";
121122 export { route as getApiV1ReposOwnerNamePullsNumberReviews } from "./getApiV1ReposOwnerNamePullsNumberReviews.ts";
122123 export { route as getApiV1ReposOwnerNamePullsNumberThreads } from "./getApiV1ReposOwnerNamePullsNumberThreads.ts";
src/http/api.ts +8
@@ -92,6 +92,7 @@ import {
9292 } from "../actions/pulls.ts";
9393 import { attachLook } from "../actions/attach_look.ts";
9494 import { lookUrl } from "../core/looks.ts";
95 import { pullLooks } from "../web/pages/looks.ts";
9596 import { holdPull, releasePull } from "../actions/holds.ts";
9697 import { getHold, type Hold } from "../core/holds.ts";
9798 import { watchMilestone } from "../actions/watches.ts";
@@ -2584,6 +2585,13 @@ export function apiRoutes(router: Router<Handler>): void {
25842585 },
25852586 );
25862587
2588 // The pictures of a pull, as the pull page shows them to this reader.
2589 router.add("GET", "/api/v1/repos/:owner/:name/pulls/:number/looks", (ctx) => {
2590 const found = loadPull(ctx);
2591 if ("error" in found) return found.error;
2592 return json({ items: pullLooks(ctx, found.repo, found.pull) });
2593 });
2594
25872595 // Attach a look: a picture a person took, at a stated width, with one line
25882596 // saying what it shows (`actions/attach_look.ts`). The picture is base64
25892597 // in the JSON body; the crew's own looks keep their path through the
src/http/mcp/tools/pull.ts +3 −1
@@ -10,11 +10,12 @@ import { appView } from "../../../actions/apps.ts";
1010 import { countThread, EMBEDDED_COMMENTS, listComments } from "../../../core/issues.ts";
1111 import { isCrew } from "../../../core/agents.ts";
1212 import { markReaders } from "../../../crew/direct.ts";
13 import { pullLooks } from "../../../web/pages/looks.ts";
1314 import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
1415
1516 export const tool: Tool = {
1617 name: "pull",
17 doc: "`{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `next: { who, why }` (open only; who acts next: builder, reviewer, queue or person), and `comments` (the newest 50: author, body, at, `untrusted` on an outsider's), `commentsTotal` and `commentsNext` (older: `GET …/issues/:number/comments?cursor=`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment",
18 doc: "`{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `next: { who, why }` (open only; who acts next: builder, reviewer, queue or person), and `comments` (the newest 50: author, body, at, `untrusted` on an outsider's), `commentsTotal` and `commentsNext` (older: `GET …/issues/:number/comments?cursor=`), and `looks` (the preview's pictures, newest first: `{ id, width, says, by, commit, url, at }`, as `GET …/pulls/:number/looks`; empty with no app), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment",
1819 description:
1920 "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `checkStale`, `check`.",
2021 inputSchema: {
@@ -58,6 +59,7 @@ export const tool: Tool = {
5859 })),
5960 commentsTotal: total,
6061 commentsNext: comments.length > 0 && comments.length < total ? comments[0]!.id : null,
62 looks: pullLooks(ctx, repo, pull),
6163 number: pull.number,
6264 title: pull.title,
6365 state: pull.mergedAt !== null ? "merged" : pull.state,
src/web/pages/looks.ts +22
@@ -133,6 +133,28 @@ export function mayFetchLook(
133133 return keepLook(ctx.app.config.dataDir, look);
134134 }
135135
136 /**
137 * A pull's pictures as an agent reads them (#7915): newest first, each at
138 * its width, with what it says and who attached it, only those this viewer
139 * may fetch (`mayFetchLook`) — nothing when the repository has no app.
140 */
141 export function pullLooks(ctx: Ctx, repo: Repo, pull: Pull) {
142 const record = getAppByRepo(ctx.app.db, repo.id);
143 if (!record) return [];
144 const base = repoBase(repo);
145 return looksForEnv(ctx.app.db, record.id, previewEnv(pull.number))
146 .filter((l) => l.kind !== "thumb" && l.error === null && mayFetchLook(ctx, repo, record, l))
147 .map((l) => ({
148 id: l.id,
149 width: l.kind,
150 says: l.note,
151 by: l.attachedBy,
152 commit: l.commitOid,
153 url: lookUrl(base, l),
154 at: l.createdAt,
155 }));
156 }
157
136158 /**
137159 * The Look card on a pull: phone and desktop side by side, the commit
138160 * they are of, and a word when the head has moved since — or, honestly,
test/openapi-oa-pull-review.test.ts +1 −1
@@ -16,5 +16,5 @@ test("review-states and looks are described with their method, auth and refusals
1616 expect(look?.requestBody).toBeDefined();
1717 expect(look?.responses?.["201"]).toBeDefined();
1818 expect(JSON.stringify(look)).toContain("not_open");
19 expect(paths[`${R}/looks`]?.get).toBeUndefined();
19 expect(paths[`${R}/looks`]?.get).toBeDefined();
2020 });
test/pull-looks-read.test.ts added +119
@@ -0,0 +1,119 @@
1 /**
2 * An agent reads a pull's looks (#7915): `GET …/pulls/:number/looks` and
3 * MCP `pull` list what was attached, newest first, with the POST's url; a
4 * pull with no app answers an empty list; a reader who may not read the
5 * repository gets 404.
6 */
7
8 import { afterAll, beforeAll, expect, test } from "bun:test";
9 import { mkdtemp, rm } from "node:fs/promises";
10 import { tmpdir } from "node:os";
11 import { join } from "node:path";
12 import { openPull } from "../src/actions/pulls.ts";
13 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
14 import { createApp, type App } from "../src/app.ts";
15 import { createApp as insertApp } from "../src/core/apps.ts";
16 import type { Pull } from "../src/core/pulls.ts";
17 import type { Repo } from "../src/core/repos.ts";
18 import { createToken } from "../src/core/tokens.ts";
19 import { createUser, type User } from "../src/core/users.ts";
20 import { encodePng } from "../src/design/image/png.ts";
21 import { serve, type Servers } from "../src/http/server.ts";
22 import { quietLogs } from "./helpers/globals.ts";
23
24 quietLogs();
25
26 const png = Buffer.from(encodePng(390, 844, new Uint8Array(390 * 844 * 4).fill(200))).toString("base64");
27
28 let dataDir: string;
29 let app: App;
30 let servers: Servers;
31 let alice: User;
32 const tokens: Record<string, string> = {};
33 const pulls: Record<string, Pull> = {};
34
35 async function pullIn(name: string, visibility: "public" | "private", withApp: boolean) {
36 const made = await createRepo(app, alice, { name, visibility });
37 if (!made.ok) throw new Error(String(made.error));
38 const repo: Repo = made.value;
39 await commitToBranch(app, alice, repo, { message: "seed", files: [{ path: "README.md", content: "# x\n" }] });
40 await commitToBranch(app, alice, repo, { branch: "one", base: "main", message: "one", files: [{ path: "one.md", content: "x\n" }] });
41 const opened = await openPull(app, alice, repo, { title: "One", body: "", baseBranch: "main", headBranch: "one" });
42 if (!opened.ok) throw new Error(String(opened.error));
43 if (withApp) insertApp(app.db, { repoId: repo.id, slug: name, access: visibility === "public" ? "public" : "private" });
44 pulls[name] = opened.value;
45 }
46
47 beforeAll(async () => {
48 dataDir = await mkdtemp(join(tmpdir(), "forge-pull-looks-"));
49 app = createApp({ dataDir, port: 0 });
50 const person = async (username: string): Promise<User> => {
51 const made = await createUser(app.db, {
52 origin: "seed", trusted: true, username, email: `${username}@forge.local`,
53 password: "a-good-passphrase", adminIfFirst: username === "alice",
54 });
55 if (!made.ok) throw new Error(made.error);
56 return made.value;
57 };
58 alice = await person("alice");
59 const bob = await person("bob");
60 await pullIn("garden", "public", true);
61 await pullIn("bare", "public", false);
62 await pullIn("vault", "private", true);
63 servers = await serve(app);
64 tokens["alice"] = createToken(app.db, alice.id, "t", "rw").token;
65 tokens["bob"] = createToken(app.db, bob.id, "t", "ro").token;
66 }, 30_000);
67
68 afterAll(async () => {
69 servers.stop();
70 app.close();
71 await rm(dataDir, { recursive: true, force: true });
72 });
73
74 const call = (token: string, repo: string, path = "", init: RequestInit = {}) =>
75 fetch(`${servers.url}/api/v1/repos/alice/${repo}/pulls/${pulls[repo]!.number}/${path}`, {
76 ...init,
77 headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
78 });
79
80 test("a look attached through the POST is listed by the GET and by MCP pull", async () => {
81 expect(await (await call(tokens["alice"]!, "garden", "looks")).json()).toEqual({ items: [] });
82 const posted = (await (
83 await call(tokens["alice"]!, "garden", "looks", {
84 method: "POST",
85 body: JSON.stringify({ width: "phone", says: "the garden", image: png }),
86 })
87 ).json()) as any;
88 const listed = (await (await call(tokens["alice"]!, "garden", "looks")).json()) as any;
89 expect(listed.items).toHaveLength(1);
90 expect(listed.items[0]).toMatchObject({
91 id: posted.id, width: "phone", says: "the garden", by: "alice", commit: posted.commit, url: posted.url,
92 });
93 expect(typeof listed.items[0].at).toBe("string");
94
95 const res = await fetch(`${servers.url}/mcp`, {
96 method: "POST",
97 headers: {
98 "content-type": "application/json",
99 accept: "application/json, text/event-stream",
100 authorization: `Bearer ${tokens["alice"]}`,
101 },
102 body: JSON.stringify({
103 jsonrpc: "2.0", id: 1, method: "tools/call",
104 params: { name: "pull", arguments: { repo: "alice/garden", number: pulls["garden"]!.number } },
105 }),
106 });
107 const body = (await res.json()) as any;
108 expect(JSON.parse(body.result.content[0].text).looks).toEqual(listed.items);
109 });
110
111 test("a pull with no app answers an empty list", async () => {
112 expect(await (await call(tokens["alice"]!, "bare", "looks")).json()).toEqual({ items: [] });
113 });
114
115 test("a reader who may not read the repository gets 404, and a reader sees no owner-only look", async () => {
116 expect((await call(tokens["bob"]!, "vault", "looks")).status).toBe(404);
117 // The attached look was taken as the owner: not for a public reader.
118 expect(await (await call(tokens["bob"]!, "garden", "looks")).json()).toEqual({ items: [] });
119 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs