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
scout/forge:scout/7915-an-agent-reads-a-pull-s-looks-get-pulls → main 3 commits fork
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 | ||
| 1233 | 1233 | head, and shown in the Look card beside the crew's, to the writers only. |
| 1234 | 1234 | It stays when the head moves on and goes with the preview when the pull |
| 1235 | 1235 | 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`. | |
| 1236 | 1239 | |
| 1237 | 1240 | |
| 1238 | 1241 | ## The crew |
docs/MCP.md +1 −1
| @@ -136,7 +136,7 @@ for a tunnel and a forge that sleeps. | ||
| 136 | 136 | | `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 | |
| 137 | 137 | | `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 | |
| 138 | 138 | | `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 | | | |
| 140 | 140 | | `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 | | |
| 141 | 141 | | `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` | | |
| 142 | 142 | | `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 | ||
| 117 | 117 | export { route as getApiV1ReposOwnerNamePulls } from "./getApiV1ReposOwnerNamePulls.ts"; |
| 118 | 118 | export { route as getApiV1ReposOwnerNamePullsNumber } from "./getApiV1ReposOwnerNamePullsNumber.ts"; |
| 119 | 119 | export { route as getApiV1ReposOwnerNamePullsNumberChecks } from "./getApiV1ReposOwnerNamePullsNumberChecks.ts"; |
| 120 | export { route as getApiV1ReposOwnerNamePullsNumberLooks } from "./getApiV1ReposOwnerNamePullsNumberLooks.ts"; | |
| 120 | 121 | export { route as getApiV1ReposOwnerNamePullsNumberReviewStates } from "./getApiV1ReposOwnerNamePullsNumberReviewStates.ts"; |
| 121 | 122 | export { route as getApiV1ReposOwnerNamePullsNumberReviews } from "./getApiV1ReposOwnerNamePullsNumberReviews.ts"; |
| 122 | 123 | export { route as getApiV1ReposOwnerNamePullsNumberThreads } from "./getApiV1ReposOwnerNamePullsNumberThreads.ts"; |
src/http/api.ts +8
| @@ -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/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"; |
| @@ -2584,6 +2585,13 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 2584 | 2585 | }, |
| 2585 | 2586 | ); |
| 2586 | 2587 | |
| 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 | ||
| 2587 | 2595 | // Attach a look: a picture a person took, at a stated width, with one line |
| 2588 | 2596 | // saying what it shows (`actions/attach_look.ts`). The picture is base64 |
| 2589 | 2597 | // 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"; | ||
| 10 | 10 | import { countThread, EMBEDDED_COMMENTS, listComments } from "../../../core/issues.ts"; |
| 11 | 11 | import { isCrew } from "../../../core/agents.ts"; |
| 12 | 12 | import { markReaders } from "../../../crew/direct.ts"; |
| 13 | import { pullLooks } from "../../../web/pages/looks.ts"; | |
| 13 | 14 | import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; |
| 14 | 15 | |
| 15 | 16 | export const tool: Tool = { |
| 16 | 17 | 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", | |
| 18 | 19 | description: |
| 19 | 20 | "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `checkStale`, `check`.", |
| 20 | 21 | inputSchema: { |
| @@ -58,6 +59,7 @@ export const tool: Tool = { | ||
| 58 | 59 | })), |
| 59 | 60 | commentsTotal: total, |
| 60 | 61 | commentsNext: comments.length > 0 && comments.length < total ? comments[0]!.id : null, |
| 62 | looks: pullLooks(ctx, repo, pull), | |
| 61 | 63 | number: pull.number, |
| 62 | 64 | title: pull.title, |
| 63 | 65 | state: pull.mergedAt !== null ? "merged" : pull.state, |
src/web/pages/looks.ts +22
| @@ -133,6 +133,28 @@ export function mayFetchLook( | ||
| 133 | 133 | return keepLook(ctx.app.config.dataDir, look); |
| 134 | 134 | } |
| 135 | 135 | |
| 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 | ||
| 136 | 158 | /** |
| 137 | 159 | * The Look card on a pull: phone and desktop side by side, the commit |
| 138 | 160 | * 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 | ||
| 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-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 | }); |
new above
offline