Public: anyone can read this; the crew can change it.
An outsider's report filed untaught answers with a receipt: the issue number, its link, and what happens next in two lines #14168
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14158-an-outsider-s-report-filed-untaught-answ → main 2 commits fork
6 files
changed +53
−5
docs/MCP.md +1 −1
| @@ -254,7 +254,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`; | ||
| 254 | 254 | | `offer` | — | Offer a patch to a public repository, no account needed; a person reads it first | 362 | |
| 255 | 255 | <!-- mcp-tools:end --> |
| 256 | 256 | |
| 257 | `report` answers the receipt `POST …/reports` does (`id`, `state`, `issue`, `url`, `message`, `next`): `issue` is null until a person accepts the report, and `url` shows the number once there is one; never the filer's words. | |
| 257 | `report` answers the receipt `POST …/reports` does (`id`, `state`, `issue`, `number`, `url`, `message`, `next`; `next` is two lines, who reads it and that nothing acts before a writer adopts it): `issue` and `number` are null until a person accepts the report, and `url` shows the number once there is one; never the filer's words. | |
| 258 | 258 | |
| 259 | 259 | Five tools need no token, for the same reach as their HTTP doors: `report`, |
| 260 | 260 | `offer`, `start`, `explore` and `search` (`TOKEN_FREE_TOOLS` in `src/core/mcp_card.ts`). |
src/actions/report_words.ts +16 −2
| @@ -23,6 +23,20 @@ export const REPORT_WHERE_REPLY = "Sending gives you a link that shows whether a | ||
| 23 | 23 | export const reportTooFast = (seconds: number): string => |
| 24 | 24 | `Too many reports from here just now. Try again in ${seconds} seconds.`; |
| 25 | 25 | |
| 26 | /** What happens next, in one sentence, for the receipt a filed report returns. */ | |
| 26 | /** | |
| 27 | * What happens next, in two lines: who reads it, and that nothing acts before a writer adopts it. | |
| 28 | */ | |
| 27 | 29 | export const REPORT_NEXT_STEP = |
| 28 | "A person who maintains this repository will read it; open the url to see whether they have and which issue it became."; | |
| 30 | "A person who maintains this repository reads it first.\nNothing acts on it until a writer adopts it as an issue; open the url to see whether they have."; | |
| 31 | ||
| 32 | /** The field each refusal of a malformed report is about. */ | |
| 33 | export const REPORT_FIELD: Readonly<Record<string, "title" | "body" | "agent">> = { | |
| 34 | empty_title: "title", | |
| 35 | title_too_long: "title", | |
| 36 | body_too_long: "body", | |
| 37 | invalid_agent: "agent", | |
| 38 | }; | |
| 39 | ||
| 40 | /** A refused report's message: the field first, then the code's own cause. */ | |
| 41 | export const reportRefusal = (code: string): string => | |
| 42 | `${REPORT_FIELD[code] ?? "report"}: ${code.replace(/_/g, " ")}`; |
src/http/api/reports.ts +2 −1
| @@ -6,6 +6,7 @@ | ||
| 6 | 6 | * live in `actions/reports.ts`. |
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | import { reportRefusal } from "../../actions/report_words.ts"; | |
| 9 | 10 | import { REPORT_ALREADY_DECIDED } from "../../actions/origin_app_words.ts"; |
| 10 | 11 | import { |
| 11 | 12 | acceptReport, |
| @@ -74,7 +75,7 @@ export function reportRoutes(router: Router<Handler>): void { | ||
| 74 | 75 | return tryAgain("rate_limited", 429, "too many reports; wait and send again", refusal.retryAfter); |
| 75 | 76 | if (refusal.error === "queue_full") |
| 76 | 77 | return tryAgain("queue_full", 429, "this repository has many reports waiting; try again later", REPORT_QUEUE_RETRY); |
| 77 | return apiError(refusal.error, 422, REPORT_HINT); | |
| 78 | return json({ error: refusal.error, message: reportRefusal(refusal.error), hint: REPORT_HINT }, 422); | |
| 78 | 79 | } |
| 79 | 80 | const receipt = receiptOf(ctx, repo, filed.value); |
| 80 | 81 | if (wantsText(ctx)) |
src/http/mcp.ts +2 −1
| @@ -36,6 +36,7 @@ import { exploreRun, searchRun } from "./mcp/reads.ts"; | ||
| 36 | 36 | import { greppable, searchKind } from "../core/search.ts"; |
| 37 | 37 | import { strangerCodeSearch } from "./strangers.ts"; |
| 38 | 38 | import { hintForCode, retryAfterOf } from "./respond.ts"; |
| 39 | import { reportRefusal } from "../actions/report_words.ts"; | |
| 39 | 40 | import { proofOf, receiptOf } from "./report_filer.ts"; |
| 40 | 41 | import { fileReport } from "../actions/reports.ts"; |
| 41 | 42 | import { START_HINT, START_WORDS, startBuilding } from "../actions/start.ts"; |
| @@ -493,7 +494,7 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown { | ||
| 493 | 494 | ? "reports_closed: the people who keep this repository have closed reports from outside. Next: file nothing here; open the repository's page to reach its keepers." |
| 494 | 495 | : e.error === "rate_limited" |
| 495 | 496 | ? `rate_limited: try again in ${e.retryAfter} seconds. Next: wait, then call \`report\` again.` |
| 496 | : `${e.error}: plain text, a title of 1-${TITLE_MAX} characters, a body of at most ${BODY_MAX}, agent a name of letters, digits, . _ -. Next: call \`report\` again with \`repo\` and \`title\` fixed.`, | |
| 497 | : `${e.error}: ${reportRefusal(e.error)}. Plain text, a title of 1-${TITLE_MAX} characters, a body of at most ${BODY_MAX}, agent a name of letters, digits, . _ -. Next: call \`report\` again with \`repo\` and \`title\` fixed.`, | |
| 497 | 498 | true, |
| 498 | 499 | ); |
| 499 | 500 | } |
src/http/report_filer.ts +3
| @@ -35,6 +35,8 @@ export interface Receipt { | ||
| 35 | 35 | readonly state: Report["state"]; |
| 36 | 36 | readonly filedBy: Report["filedBy"]; |
| 37 | 37 | readonly issue: number | null; |
| 38 | /** The issue's number, the same as `issue`: null until a writer adopts the report. */ | |
| 39 | readonly number: number | null; | |
| 38 | 40 | readonly url: string; |
| 39 | 41 | readonly message: string; |
| 40 | 42 | readonly next: string; |
| @@ -56,6 +58,7 @@ export function receiptOf(ctx: Ctx, repo: Repo, report: Report): Receipt { | ||
| 56 | 58 | state: report.state, |
| 57 | 59 | filedBy: report.filedBy, |
| 58 | 60 | issue: null, |
| 61 | number: null, | |
| 59 | 62 | url: `${publicOrigin(ctx)}/${encodeURIComponent(repo.ownerName)}/${encodeURIComponent(repo.name)}/report?sent=${report.id}`, |
| 60 | 63 | message: REPORT_RECEIVED, |
| 61 | 64 | next: REPORT_NEXT_STEP, |
test/report-receipt.test.ts +29
| @@ -88,6 +88,34 @@ describe("a report's receipt", () => { | ||
| 88 | 88 | expect(closed.status).toBe(404); |
| 89 | 89 | expect((await file("shut", { title: "x" })).status).toBe(404); |
| 90 | 90 | }); |
| 91 | test("the receipt's next is two lines: who reads it, and not acted on until adopted", async () => { | |
| 92 | const r = (await (await file("open", { title: "Two lines" })).json()) as { number: null; next: string }; | |
| 93 | expect(r.number).toBeNull(); | |
| 94 | const lines = r.next.split("\n"); | |
| 95 | expect(lines).toHaveLength(2); | |
| 96 | expect(lines[0]).toContain("person who maintains"); | |
| 97 | expect(lines[1]).toContain("until a writer adopts it"); | |
| 98 | }); | |
| 99 | ||
| 100 | test("a malformed report is a 422 in {error,message,hint} naming the field, over HTTP and MCP", async () => { | |
| 101 | const res = await file("open", { title: "x".repeat(201) }); | |
| 102 | expect(res.status).toBe(422); | |
| 103 | const e = (await res.json()) as { error: string; message: string; hint: string }; | |
| 104 | expect(e.error).toBe("title_too_long"); | |
| 105 | expect(e.message).toStartWith("title:"); | |
| 106 | expect(e.hint).toContain("title of 1-"); | |
| 107 | const bad = await file("open", { title: "ok", agent: "bad agent!" }); | |
| 108 | expect(((await bad.json()) as { message: string }).message).toStartWith("agent:"); | |
| 109 | const mcp = await fetch(`${base}/mcp`, { | |
| 110 | method: "POST", | |
| 111 | headers: { "content-type": "application/json", accept: "application/json", ...from() }, | |
| 112 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", | |
| 113 | params: { name: "report", arguments: { repo: "alice/open", title: "" } } }), | |
| 114 | }); | |
| 115 | const out = (await mcp.json()) as { result: { isError?: boolean; content: { text: string }[] } }; | |
| 116 | expect(out.result.isError).toBe(true); | |
| 117 | expect(out.result.content[0]!.text).toContain("title: empty title"); | |
| 118 | }); | |
| 91 | 119 | }); |
| 92 | 120 | |
| 93 | 121 | import { publicOrigin } from "../src/http/report_filer.ts"; |
| @@ -101,4 +129,5 @@ describe("the receipt's link origin", () => { | ||
| 101 | 129 | test("falls back to the request's origin on an unconfigured forge", () => { |
| 102 | 130 | expect(publicOrigin(ctxOf(undefined, "localhost:3000"))).toBe("http://localhost:3000"); |
| 103 | 131 | }); |
| 132 | ||
| 104 | 133 | }); |
new above
offline