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
torque/forge:torque/7915-an-agent-reads-a-pull-s-looks-get-pulls → main 3 commits fork
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 | ||
| 1259 | 1259 | that parses, nothing else), kept under the preview's folder at the pull's |
| 1260 | 1260 | head, and shown in the Look card beside the crew's, to the writers only. |
| 1261 | 1261 | 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 `[]`. | |
| 1263 | 1266 | |
| 1264 | 1267 | |
| 1265 | 1268 | ## 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 | ||
| 119 | 119 | export { route as getApiV1ReposOwnerNamePulls } from "./getApiV1ReposOwnerNamePulls.ts"; |
| 120 | 120 | export { route as getApiV1ReposOwnerNamePullsNumber } from "./getApiV1ReposOwnerNamePullsNumber.ts"; |
| 121 | 121 | export { route as getApiV1ReposOwnerNamePullsNumberChecks } from "./getApiV1ReposOwnerNamePullsNumberChecks.ts"; |
| 122 | export { route as getApiV1ReposOwnerNamePullsNumberLooks } from "./getApiV1ReposOwnerNamePullsNumberLooks.ts"; | |
| 122 | 123 | export { route as getApiV1ReposOwnerNamePullsNumberReviewStates } from "./getApiV1ReposOwnerNamePullsNumberReviewStates.ts"; |
| 123 | 124 | export { route as getApiV1ReposOwnerNamePullsNumberReviews } from "./getApiV1ReposOwnerNamePullsNumberReviews.ts"; |
| 124 | 125 | export { route as getApiV1ReposOwnerNamePullsNumberThreads } from "./getApiV1ReposOwnerNamePullsNumberThreads.ts"; |
src/http/api.ts +10
| @@ -92,6 +92,7 @@ import { | ||
| 92 | 92 | } from "../actions/pulls.ts"; |
| 93 | 93 | import { attachLook } from "../actions/attach_look.ts"; |
| 94 | 94 | import { lookUrl } from "../core/looks.ts"; |
| 95 | import { pullLooks } from "../web/pages/pull_looks.ts"; | |
| 95 | 96 | import { holdPull, releasePull } from "../actions/holds.ts"; |
| 96 | 97 | import { getHold, type Hold } from "../core/holds.ts"; |
| 97 | 98 | import { watchMilestone } from "../actions/watches.ts"; |
| @@ -2588,6 +2589,15 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 2588 | 2589 | }, |
| 2589 | 2590 | ); |
| 2590 | 2591 | |
| 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 | ||
| 2591 | 2601 | // Attach a look: a picture a person took, at a stated width, with one line |
| 2592 | 2602 | // saying what it shows (`actions/attach_look.ts`). The picture is base64 |
| 2593 | 2603 | // 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"; | ||
| 11 | 11 | import { countThread, EMBEDDED_COMMENTS, listComments } from "../../../core/issues.ts"; |
| 12 | 12 | import { isCrew } from "../../../core/agents.ts"; |
| 13 | 13 | import { markReaders } from "../../../crew/direct.ts"; |
| 14 | import { pullLooks } from "../../../web/pages/pull_looks.ts"; | |
| 14 | 15 | import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; |
| 15 | 16 | |
| 16 | 17 | export const tool: Tool = { |
| 17 | 18 | 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", | |
| 19 | 20 | description: |
| 20 | 21 | "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `checkStale`, `check`.", |
| 21 | 22 | inputSchema: { |
| @@ -57,6 +58,7 @@ export const tool: Tool = { | ||
| 57 | 58 | at: c.createdAt, |
| 58 | 59 | ...("untrusted" in c && c.untrusted !== undefined ? { untrusted: true } : {}), |
| 59 | 60 | })), |
| 61 | looks: pullLooks(ctx.app, user, repo, pull), | |
| 60 | 62 | commentsTotal: total, |
| 61 | 63 | commentsNext: comments.length > 0 && comments.length < total ? comments[0]!.id : null, |
| 62 | 64 | number: pull.number, |
src/web/pages/looks.ts +18 −5
| @@ -7,6 +7,8 @@ | ||
| 7 | 7 | * long as anyone likes and is never the wrong commit's. |
| 8 | 8 | */ |
| 9 | 9 | |
| 10 | import type { Database } from "bun:sqlite"; | |
| 11 | import type { User } from "../../core/users.ts"; | |
| 10 | 12 | import { sealedPreview } from "../../core/sealed.ts"; |
| 11 | 13 | import { closeSync, existsSync, openSync, readSync } from "node:fs"; |
| 12 | 14 | import { jpegHeader } from "../../design/image/jpeg.ts"; |
| @@ -120,17 +122,28 @@ export function mayFetchLook( | ||
| 120 | 122 | record: AppRecord, |
| 121 | 123 | look: Look, |
| 122 | 124 | ): 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; | |
| 125 | 138 | // 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; | |
| 127 | 140 | // A private app's pictures are for whoever may enter it (#620, #752): a |
| 128 | 141 | // 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; | |
| 130 | 143 | // Phone and desktop are a reader's only when taken as nobody — a public |
| 131 | 144 | // app's, since #738; one taken as the owner stays the writers' (#727). |
| 132 | 145 | if (look.kind !== "thumb") return look.takenAs === "nobody"; |
| 133 | return keepLook(ctx.app.config.dataDir, look); | |
| 146 | return keepLook(dataDir, look); | |
| 134 | 147 | } |
| 135 | 148 | |
| 136 | 149 | /** |
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 | ||
| 16 | 16 | expect(look?.requestBody).toBeDefined(); |
| 17 | 17 | expect(look?.responses?.["201"]).toBeDefined(); |
| 18 | 18 | expect(JSON.stringify(look)).toContain("not_open"); |
| 19 | expect(paths[`${R}/looks`]?.get).toBeUndefined(); | |
| 19 | expect(paths[`${R}/looks`]?.get).toBeDefined(); | |
| 20 | 20 | }); |
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 | }); |
new above
offline