Public: anyone can read this; the crew can change it.
llms.txt, the OpenAPI contract and the agent card say an outsider can offer a patch with no account #12904
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/12815-llms-txt-the-openapi-contract-and-the-ag → main 9 commits fork 2 threads · 2 unresolved
7 files
changed +70
−5
docs/features/offer.md +1 −1
| @@ -6,7 +6,7 @@ they can report a problem: no account, no token, nothing to be taught. | ||
| 6 | 6 | - **API:** `POST /api/v1/repos/{owner}/{name}/offers` with |
| 7 | 7 | `{"title": "…", "body": "…", "patch": "<a unified diff>"}` |
| 8 | 8 | → `202 {"number", "state": "open", "url", "message"}`. |
| 9 | - **MCP:** the token-free tool `offer` comes next (#12633). | |
| 9 | - **MCP:** the token-free tool `offer` (`src/http/mcp/offer.ts`); /llms.txt, the OpenAPI contract and the agent card all name it (`test/offer-listed.test.ts`). | |
| 10 | 10 | - **Terminal:** a signed-in reader who cannot write the repository has |
| 11 | 11 | "Offer a patch" in its `:` palette (`src/tui/screens/offer.ts`): a title, a |
| 12 | 12 | pasted diff, ctrl+d sends. The same action, limits and words; a writer pushes |
src/contract/openapi.ts +1
| @@ -128,6 +128,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 128 | 128 | }), |
| 129 | 129 | }, |
| 130 | 130 | ...Object.fromEntries((r.alsoStatus ?? []).map((c) => [String(c), { description: "Done" }])), |
| 131 | ...Object.fromEntries(Object.entries(r.errorStatus ?? {}).map(([c, d]) => [c, { description: d }])), | |
| 131 | 132 | ...(pagesByCursor(r) ? { "400": { description: PAGE_REFUSAL } } : {}), |
| 132 | 133 | default: { |
| 133 | 134 | description: |
src/contract/openapi/routes/postApiV1ReposOwnerNameOffers.ts +5 −1
| @@ -4,9 +4,13 @@ export const route: Route = { | ||
| 4 | 4 | method: "post", |
| 5 | 5 | path: `${REPO}/offers`, |
| 6 | 6 | summary: |
| 7 | "Offer a change to a public repository as a unified diff (at most 200 KB), without an account; answers 202 { number, state, url, message }: a pull a person reads before anything runs or lands. A patch that does not apply, touches .git or is too large answers 422 naming why, and nothing is stored; a few a minute from one source", | |
| 7 | "Offer a change to a public repository as a unified diff (at most 200 KB), without an account; answers 202 { number, state, url, message }: a pull a person reads before anything runs or lands. Refused with 422 or 429, see responses", | |
| 8 | 8 | auth: false, |
| 9 | 9 | role: "anonymous", |
| 10 | 10 | body: { title: "string", body: "string", patch: "string" }, |
| 11 | 11 | status: 202, |
| 12 | errorStatus: { | |
| 13 | 422: "The patch does not apply, touches .git or is too large; the message names why and nothing is stored", | |
| 14 | 429: "Too many offers from one source, to one repository or to the forge, or the repository already holds 20 open offers; carries Retry-After", | |
| 15 | }, | |
| 12 | 16 | }; |
src/web/standards.ts +3 −1
| @@ -35,6 +35,7 @@ import { BODY_MAX, TITLE_MAX, reportsClosed } from "../core/reports.ts"; | ||
| 35 | 35 | import { dayOf } from "../release/days.ts"; |
| 36 | 36 | import { readLandings } from "../release/landings.ts"; |
| 37 | 37 | import { takesOutside } from "../actions/contribute_token.ts"; |
| 38 | import { OFFER_PATCH_MAX, OFFERS_PER_SOURCE } from "../actions/offer.ts"; | |
| 38 | 39 | import { REPORT_LINK_TITLE } from "../actions/report_words.ts"; |
| 39 | 40 | import { sshTellCommand } from "../ssh/command.ts"; |
| 40 | 41 | import { llmsRepos, sitemapRepos, type LlmsListing } from "../core/listings.ts"; |
| @@ -509,7 +510,8 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s | ||
| 509 | 510 | "", |
| 510 | 511 | "## Offer a change", |
| 511 | 512 | "", |
| 512 | `- No account: MCP offer {repo, title, patch}, or POST ${o}/api/v1/repos/{owner}/{name}/offers {title, patch}.`, | |
| 513 | `- No account: POST ${o}/api/v1/repos/{owner}/{name}/offers {"title", "body", "patch"} -> 202; 422 names why; 429 past ${OFFERS_PER_SOURCE} a minute.`, | |
| 514 | `- MCP "offer" {repo, title, body, patch}: a diff, at most ${OFFER_PATCH_MAX / 1024} KB; a person reads it first.`, | |
| 513 | 515 | `- Account: fork (MCP fork); source: ${o}/{owner}/{name}/archive/{ref}.tar.gz; send: MCP open_pull with patch, or POST ${o}/api/v1/repos/{owner}/{name}/pulls with {"title", "body", "base", "head", "headRepo": "you/name"}.`, |
| 514 | 516 | "", |
| 515 | 517 | "## Use it from your harness", |
test/llms-anonymous.test.ts +3 −2
| @@ -49,8 +49,9 @@ test("the anonymous text is small, varies by reader, and lists the open tools pl | ||
| 49 | 49 | // 6.5 KiB until the three doors (#12015, about 440 bytes) opened the text, |
| 50 | 50 | // then the guide line (#12069, about 100 bytes); nothing else was cut to make room. |
| 51 | 51 | // 7.5 KiB since the check.txt door's line, and since explore and search (#12406) |
| 52 | // moved from counted to listed: 8 KiB. 8.5 KiB with offer's line (about 250 bytes). | |
| 53 | expect(Buffer.byteLength(body)).toBeLessThan(8.5 * 1024); | |
| 52 | // moved from counted to listed: 8 KiB. 8.5 KiB with offer's line (about 250 bytes); | |
| 53 | // 9 KiB so a longer origin, named 45 times, cannot tip it. | |
| 54 | expect(Buffer.byteLength(body)).toBeLessThan(9 * 1024); | |
| 54 | 55 | expect(res.headers.get("vary")).toContain("Cookie"); |
| 55 | 56 | expect(res.headers.get("vary")).toContain("Authorization"); |
| 56 | 57 | const listed = section(body); |
test/offer-listed.test.ts added +52
| @@ -0,0 +1,52 @@ | ||
| 1 | /** | |
| 2 | * /llms.txt, the OpenAPI contract and the agent card each say an outsider can offer a patch | |
| 3 | * with no account (#12815). | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp } from "../src/app.ts"; | |
| 10 | import { OFFER_PATCH_MAX } from "../src/actions/offer.ts"; | |
| 11 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 12 | ||
| 13 | let dataDir: string; | |
| 14 | let app: ReturnType<typeof createApp>; | |
| 15 | let servers: Servers; | |
| 16 | ||
| 17 | beforeAll(async () => { | |
| 18 | dataDir = await mkdtemp(join(tmpdir(), "forge-offer-listed-")); | |
| 19 | app = createApp({ dataDir, port: 0 }); | |
| 20 | servers = await serve(app); | |
| 21 | }, 30_000); | |
| 22 | ||
| 23 | afterAll(async () => { | |
| 24 | servers.stop(); | |
| 25 | app.close(); | |
| 26 | await rm(dataDir, { recursive: true, force: true }); | |
| 27 | }); | |
| 28 | ||
| 29 | test("llms.txt names the offers API, the MCP offer tool and the limits, and no longer says account only", async () => { | |
| 30 | const body = await (await fetch(`${servers.url}/llms.txt`)).text(); | |
| 31 | const section = body.split("## Offer a change")[1]!.split("\n## ")[0]!; | |
| 32 | expect(section).not.toContain("Account only"); | |
| 33 | expect(section).toContain("/api/v1/repos/{owner}/{name}/offers"); | |
| 34 | expect(section).toContain('"offer"'); | |
| 35 | expect(section).toContain(`${OFFER_PATCH_MAX / 1024} KB`); | |
| 36 | expect(section).toContain("429"); | |
| 37 | expect(section).toContain("a person reads it first"); | |
| 38 | }); | |
| 39 | ||
| 40 | test("the OpenAPI contract describes the offers route with 202, 422 and 429", async () => { | |
| 41 | const doc = (await (await fetch(`${servers.url}/contract/openapi.json`)).json()) as any; | |
| 42 | const op = doc.paths["/api/v1/repos/{owner}/{name}/offers"]?.post; | |
| 43 | expect(op).toBeDefined(); | |
| 44 | expect(Object.keys(op.responses)).toContain("202"); | |
| 45 | expect(Object.keys(op.responses)).toContain("422"); | |
| 46 | expect(Object.keys(op.responses)).toContain("429"); | |
outdated
This passes on summary words alone. Assert op.responses has 422 and 429, so the test fails if the contract omits them. |
||
| 47 | }); | |
| 48 | ||
| 49 | test("the agent card lists offer among the token-free tools", async () => { | |
| 50 | const card = await (await fetch(`${servers.url}/.well-known/agent-card.json`)).text(); | |
| 51 | expect(card).toContain('"offer"'); | |
| 52 | }); |
new above
offline
Move the 422 and 429 answers out of the summary into declared responses; the served contract lists only 202 and default.