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 #8411

Parked opened this
Closed without merging

torque/forge:torque/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 +258 −8
docs/APPS.md +4 −1
@@ -1259,7 +1259,10 @@ at most 5 MB, or the MCP `attach_look`. It is read as bytes (a PNG or JPEG
12591259 that parses, nothing else), kept under the preview's folder at the pull's
12601260 head, and shown in the Look card beside the crew's, to the writers only.
12611261 It stays when the head moves on and goes with the preview when the pull
1262 closes.
1262 closes. An agent reads them back: `GET …/pulls/:number/looks` answers
1263 `{items: [{id, width, says, by, commit, url, at}]}`, newest first, and MCP
1264 `pull` carries the same as `looks` — only the pictures the reader may fetch;
1265 no app or none is `[]`.
12631266
12641267
12651268 ## The crew
src/contract/openapi/routes/getApiV1ReposOwnerNamePullsNumberLooks.ts added +9
@@ -0,0 +1,9 @@
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: "A pull's looks: the preview's pictures, newest first, only those the reader may fetch; answers { items } with id, width, says, by, commit, url, at",
7 auth: false,
8 reply: { items: "array" },
9 };
src/contract/openapi/routes/index.ts +1
@@ -119,6 +119,7 @@ export { route as getApiV1ReposOwnerNamePrompts } from "./getApiV1ReposOwnerName
119119 export { route as getApiV1ReposOwnerNamePulls } from "./getApiV1ReposOwnerNamePulls.ts";
120120 export { route as getApiV1ReposOwnerNamePullsNumber } from "./getApiV1ReposOwnerNamePullsNumber.ts";
121121 export { route as getApiV1ReposOwnerNamePullsNumberChecks } from "./getApiV1ReposOwnerNamePullsNumberChecks.ts";
122 export { route as getApiV1ReposOwnerNamePullsNumberLooks } from "./getApiV1ReposOwnerNamePullsNumberLooks.ts";
122123 export { route as getApiV1ReposOwnerNamePullsNumberReviewStates } from "./getApiV1ReposOwnerNamePullsNumberReviewStates.ts";
123124 export { route as getApiV1ReposOwnerNamePullsNumberReviews } from "./getApiV1ReposOwnerNamePullsNumberReviews.ts";
124125 export { route as getApiV1ReposOwnerNamePullsNumberThreads } from "./getApiV1ReposOwnerNamePullsNumberThreads.ts";
src/http/api.ts +10
@@ -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/pull_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";
@@ -2588,6 +2589,15 @@ export function apiRoutes(router: Router<Handler>): void {
25882589 },
25892590 );
25902591
2592 // The pull's pictures, as the page shows them to this reader.
2593 router.add("GET", "/api/v1/repos/:owner/:name/pulls/:number/looks", (ctx) => {
2594 const found = loadPull(ctx);
2595 if ("error" in found) return found.error;
2596 return json({
2597 items: pullLooks(ctx.app, ctx.auth.user, found.repo, found.pull),
2598 });
2599 });
2600
25912601 // Attach a look: a picture a person took, at a stated width, with one line
25922602 // saying what it shows (`actions/attach_look.ts`). The picture is base64
25932603 // in the JSON body; the crew's own looks keep their path through the
src/http/mcp/tools/pull.ts +3 −1
@@ -11,11 +11,12 @@ import { appView } from "../../../actions/apps.ts";
1111 import { countThread, EMBEDDED_COMMENTS, listComments } from "../../../core/issues.ts";
1212 import { isCrew } from "../../../core/agents.ts";
1313 import { markReaders } from "../../../crew/direct.ts";
14 import { pullLooks } from "../../../web/pages/pull_looks.ts";
1415 import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
1516
1617 export const tool: Tool = {
1718 name: "pull",
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), `step: { step, why, done }` (check, review, land or live; null once closed unlanded), 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",
19 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), `step: { step, why, done }` (check, review, land or live; null once closed unlanded), 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 pull's pictures, newest first: id, width, says, by, commit, url, at; the same as `GET …/pulls/:number/looks`), 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",
1920 description:
2021 "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `checkStale`, `check`.",
2122 inputSchema: {
@@ -57,6 +58,7 @@ export const tool: Tool = {
5758 at: c.createdAt,
5859 ...("untrusted" in c && c.untrusted !== undefined ? { untrusted: true } : {}),
5960 })),
61 looks: pullLooks(ctx.app, user, repo, pull),
6062 commentsTotal: total,
6163 commentsNext: comments.length > 0 && comments.length < total ? comments[0]!.id : null,
6264 number: pull.number,
src/web/pages/looks.ts +18 −5
@@ -7,6 +7,8 @@
77 * long as anyone likes and is never the wrong commit's.
88 */
99
10 import type { Database } from "bun:sqlite";
11 import type { User } from "../../core/users.ts";
1012 import { sealedPreview } from "../../core/sealed.ts";
1113 import { closeSync, existsSync, openSync, readSync } from "node:fs";
1214 import { jpegHeader } from "../../design/image/jpeg.ts";
@@ -120,17 +122,28 @@ export function mayFetchLook(
120122 record: AppRecord,
121123 look: Look,
122124 ): boolean {
123 const user = ctx.auth.user;
124 if (canSeeOwnerFacts(ctx.app.db, repo, user)) return true;
125 return mayFetchLookAs(ctx.app.db, ctx.app.config.dataDir, ctx.auth.user, repo, record, look);
126 }
127
128 /** `mayFetchLook` without a request: the MCP asks it as the caller. */
129 export function mayFetchLookAs(
130 db: Database,
131 dataDir: string,
132 user: User | undefined,
133 repo: Repo,
134 record: AppRecord,
135 look: Look,
136 ): boolean {
137 if (canSeeOwnerFacts(db, repo, user)) return true;
125138 // A sealed pull's pictures are the writers' (`core/sealed.ts`).
126 if (sealedPreview(ctx.app.db, repo.id, look.env)) return false;
139 if (sealedPreview(db, repo.id, look.env)) return false;
127140 // A private app's pictures are for whoever may enter it (#620, #752): a
128141 // person it names sees them; a reader who is not named does not.
129 if (!canEnterApp(ctx.app.db, repo, record, user)) return false;
142 if (!canEnterApp(db, repo, record, user)) return false;
130143 // Phone and desktop are a reader's only when taken as nobody — a public
131144 // app's, since #738; one taken as the owner stays the writers' (#727).
132145 if (look.kind !== "thumb") return look.takenAs === "nobody";
133 return keepLook(ctx.app.config.dataDir, look);
146 return keepLook(dataDir, look);
134147 }
135148
136149 /**
src/web/pages/pull_looks.ts added +53
@@ -0,0 +1,53 @@
1 /**
2 * The pictures of a pull, as data: what `GET …/pulls/:number/looks` and the
3 * MCP `pull` both answer. The pull's preview environment's light looks,
4 * newest first, only those this viewer may fetch (`mayFetchLookAs`, the
5 * rule that serves the picture) and that have a picture; no app or no
6 * looks is an empty list.
7 */
8
9 import type { App } from "../../app.ts";
10 import { previewEnv } from "../../apps/data.ts";
11 import { getAppByRepo } from "../../core/apps.ts";
12 import { looksForEnv, lookUrl } from "../../core/looks.ts";
13 import type { Pull } from "../../core/pulls.ts";
14 import type { Repo } from "../../core/repos.ts";
15 import type { User } from "../../core/users.ts";
16 import { mayFetchLookAs } from "./looks.ts";
17
18 export interface PullLook {
19 readonly id: string;
20 /** `phone`, `desktop` or `thumb`. */
21 readonly width: string;
22 readonly says: string | null;
23 readonly by: string | null;
24 readonly commit: string;
25 readonly url: string;
26 readonly at: string;
27 }
28
29 export function pullLooks(
30 app: App,
31 user: User | undefined,
32 repo: Repo,
33 pull: Pull,
34 ): PullLook[] {
35 const record = getAppByRepo(app.db, repo.id);
36 if (!record) return [];
37 const base = `/${repo.ownerName}/${repo.name}`;
38 return looksForEnv(app.db, record.id, previewEnv(pull.number))
39 .filter(
40 (l) =>
41 l.error === null &&
42 mayFetchLookAs(app.db, app.config.dataDir, user, repo, record, l),
43 )
44 .map((l) => ({
45 id: l.id,
46 width: l.kind,
47 says: l.note,
48 by: l.attachedBy,
49 commit: l.commitOid,
50 url: lookUrl(base, l),
51 at: l.createdAt,
52 }));
53 }
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.test.ts added +159
@@ -0,0 +1,159 @@
1 /**
2 * An agent reads a pull's looks (#7915): `GET …/pulls/:number/looks` and the
3 * MCP `pull` list what the POST attached, with the POST's own `url`, to
4 * whoever may fetch the picture; a pull with no app has none.
5 */
6
7 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { openPull } from "../src/actions/pulls.ts";
12 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
13 import { createApp, type App } from "../src/app.ts";
14 import { createApp as insertApp } from "../src/core/apps.ts";
15 import type { Pull } from "../src/core/pulls.ts";
16 import { createToken } from "../src/core/tokens.ts";
17 import { createUser, type User } from "../src/core/users.ts";
18 import { encodePng } from "../src/design/image/png.ts";
19 import { serve, type Servers } from "../src/http/server.ts";
20 import { quietLogs } from "./helpers/globals.ts";
21
22 quietLogs();
23
24 const PASSWORD = "a-good-passphrase";
25 const PHONE = Buffer.from(
26 encodePng(390, 844, new Uint8Array(390 * 844 * 4).fill(200)),
27 ).toString("base64");
28
29 describe("a pull's looks, read back", () => {
30 let dataDir: string;
31 let app: App;
32 let servers: Servers;
33 let base: string;
34 const tokens: Record<string, string> = {};
35 const pulls: Record<string, Pull> = {};
36
37 const auth = (t: string) => ({ authorization: `Bearer ${t}` });
38 const get = (repo: string, n: number, t: string) =>
39 fetch(`${base}/api/v1/repos/alice/${repo}/pulls/${n}/looks`, { headers: auth(t) });
40 const mcpPull = async (repo: string, n: number, t: string) => {
41 const res = await fetch(`${base}/mcp`, {
42 method: "POST",
43 headers: {
44 "content-type": "application/json",
45 accept: "application/json, text/event-stream",
46 ...auth(t),
47 },
48 body: JSON.stringify({
49 jsonrpc: "2.0",
50 id: 1,
51 method: "tools/call",
52 params: { name: "pull", arguments: { repo: `alice/${repo}`, number: n } },
53 }),
54 });
55 const body = (await res.json()) as any;
56 return JSON.parse(body.result.content[0].text);
57 };
58
59 beforeAll(async () => {
60 dataDir = await mkdtemp(join(tmpdir(), "forge-pull-looks-"));
61 app = createApp({ dataDir, port: 0 });
62 const person = async (username: string): Promise<User> => {
63 const made = await createUser(app.db, {
64 origin: "seed",
65 trusted: true,
66 username,
67 email: `${username}@forge.local`,
68 password: PASSWORD,
69 adminIfFirst: username === "alice",
70 });
71 if (!made.ok) throw new Error(made.error);
72 return made.value;
73 };
74 const alice = await person("alice");
75 const bob = await person("bob");
76 for (const [name, visibility, withApp] of [
77 ["garden", "public", true],
78 ["bare", "public", false],
79 ["vault", "private", true],
80 ] as const) {
81 const made = await createRepo(app, alice, { name, visibility });
82 if (!made.ok) throw new Error(String(made.error));
83 await commitToBranch(app, alice, made.value, {
84 message: "seed",
85 files: [{ path: "README.md", content: "# x\n" }],
86 });
87 await commitToBranch(app, alice, made.value, {
88 branch: "one",
89 base: "main",
90 message: "one",
91 files: [{ path: "one.md", content: "x\n" }],
92 });
93 const opened = await openPull(app, alice, made.value, {
94 title: "Change one",
95 body: "",
96 baseBranch: "main",
97 headBranch: "one",
98 });
99 if (!opened.ok) throw new Error(String(opened.error));
100 pulls[name] = opened.value;
101 if (withApp) {
102 const ins = insertApp(app.db, {
103 repoId: made.value.id,
104 slug: name,
105 access: visibility === "public" ? "public" : "private",
106 });
107 if (!ins.ok) throw new Error(ins.error);
108 }
109 }
110 servers = await serve(app);
111 base = servers.url;
112 tokens["alice"] = createToken(app.db, alice.id, "t", "rw").token;
113 tokens["bob"] = createToken(app.db, bob.id, "t", "rw").token;
114 }, 30_000);
115
116 afterAll(async () => {
117 servers.stop();
118 app.close();
119 await rm(dataDir, { recursive: true, force: true });
120 });
121
122 test("a look attached through the POST is listed by the GET and by MCP pull, with the POST's url", async () => {
123 const n = pulls["garden"]!.number;
124 expect(await (await get("garden", n, tokens["alice"]!)).json()).toEqual({ items: [] });
125 const posted = await fetch(`${base}/api/v1/repos/alice/garden/pulls/${n}/looks`, {
126 method: "POST",
127 headers: { "content-type": "application/json", ...auth(tokens["alice"]!) },
128 body: JSON.stringify({ width: "phone", says: "the empty garden", image: PHONE }),
129 });
130 expect(posted.status).toBe(201);
131 const made = (await posted.json()) as any;
132 const listed = (await (await get("garden", n, tokens["alice"]!)).json()) as any;
133 expect(listed.items).toHaveLength(1);
134 expect(listed.items[0]).toMatchObject({
135 id: made.id,
136 width: "phone",
137 says: "the empty garden",
138 by: "alice",
139 commit: made.commit,
140 url: made.url,
141 });
142 expect(typeof listed.items[0].at).toBe("string");
143 expect((await mcpPull("garden", n, tokens["alice"]!)).looks).toEqual(listed.items);
144 });
145
146 test("a reader who may not fetch the picture is not told of it", async () => {
147 const n = pulls["garden"]!.number;
148 expect(await (await get("garden", n, tokens["bob"]!)).json()).toEqual({ items: [] });
149 expect((await mcpPull("garden", n, tokens["bob"]!)).looks).toEqual([]);
150 });
151
152 test("a private repository answers 404 to a reader, and a pull with no app has no looks", async () => {
153 expect((await get("vault", pulls["vault"]!.number, tokens["bob"]!)).status).toBe(404);
154 expect(await (await get("bare", pulls["bare"]!.number, tokens["alice"]!)).json()).toEqual({
155 items: [],
156 });
157 expect((await mcpPull("bare", pulls["bare"]!.number, tokens["alice"]!)).looks).toEqual([]);
158 });
159 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs