Public: anyone can read this; the crew can change it.

An outsider's offered pull on a public repository returns a receipt and a status link they can poll without an account #13179

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

An outsider's offer now comes back with a receipt and a status URL anyone can poll without an account. The new test/offer-receipt.test.ts passes, along with test/mcp-size.test.ts, test/mcp-table.test.ts, the guide and feature-orphan checks, scripts/gate.ts and tsc.

Notes

shipped production is serving it deploy 59903fa

opened this

An outsider's offer now comes back with a receipt and a status URL anyone can poll without an account. The new test/offer-receipt.test.ts passes, along with test/mcp-size.test.ts, test/mcp-table.test.ts, the guide and feature-orphan checks, scripts/gate.ts and tsc. I did not run the full suite; the forge's check does that on push.

What changed

  • Receipt: POST /api/v1/repos/:owner/:name/offers still answers 202. It now also returns receipt and status, which is GET /api/v1/offers/:receipt. The receipt is 128 random bits in hex, kept in a new offer_receipt table (migration 20261115110000-offer-receipt, already pinned). It is never derived from the pull number.
  • Status route: it answers only { receipt, state, reason }. A wrong id, a pull number or a malformed id is a 404.
  • State: received until someone leaves a review, then under review, landed when merged and declined when closed without a merge. reason is one fixed sentence per state (src/core/offer_receipt.ts).
  • MCP: no new tool. The existing offer tool returns the same receipt and status, and takes an optional receipt argument that reads the state back.
  • Docs: docs/MCP.md and its generated table are updated, and docs/features/offer.md has a new "The receipt" section.

Left out

  • The reason is a fixed sentence per state, not a maintainer's own words. That needs a place to store one, which this pull doesn't add.
  • There is no HTML status page, only the JSON endpoint.
  • Because offer now accepts a receipt instead of a patch, its schema no longer marks repo, title and patch as required. An offer missing them is still refused by the existing checks.
  • The route registration (offerStatusHandler in src/http/api.ts) is not covered by the OpenAPI contract tests I ran.

Try it POST a patch to a public repository's /offers, then GET the status URL from the answer. The state moves once a person reviews, merges or closes the pull.

🤖 Generated with Claude Code

Closes #13162

5 earlier comments · 1 event
commented

An outsider's offer now comes back with a receipt and a status URL anyone can poll without an account. The new test/offer-receipt.test.ts passes, along with test/mcp-size.test.ts, test/mcp-table.test.ts, the guide and feature-orphan checks, scripts/gate.ts and tsc. I did not run the full suite; the forge's check does that on push.

What changed

  • Receipt: POST /api/v1/repos/:owner/:name/offers still answers 202. It now also returns receipt and status, which is GET /api/v1/offers/:receipt. The receipt is 128 random bits in hex, kept in a new offer_receipt table (migration 20261115110000-offer-receipt, already pinned). It is never derived from the pull number.
  • Status route: it answers only { receipt, state, reason }. A wrong id, a pull number or a malformed id is a 404.
  • State: received until someone leaves a review, then under review, landed when merged and declined when closed without a merge. reason is one fixed sentence per state (src/core/offer_receipt.ts).
  • MCP: no new tool. The existing offer tool returns the same receipt and status, and takes an optional receipt argument that reads the state back.
  • Docs: docs/MCP.md and its generated table are updated, and docs/features/offer.md has a new "The receipt" section.

Left out

  • The reason is a fixed sentence per state, not a maintainer's own words. That needs a place to store one, which this pull doesn't add.
  • There is no HTML status page, only the JSON endpoint.
  • Because offer now accepts a receipt instead of a patch, its schema no longer marks repo, title and patch as required. An offer missing them is still refused by the existing checks.
  • The route registration (offerStatusHandler in src/http/api.ts) is not covered by the OpenAPI contract tests I ran.

Try it POST a patch to a public repository's /offers, then GET the status URL from the answer. The state moves once a person reviews, merges or closes the pull.

🤖 Generated with Claude Code

commented

An outsider's offer to a public repository now returns a random receipt and a status URL that answers that offer's state.

The failing check was a documentation-comment line in src/http/offer_routes.ts that ran to 102 columns. I rewrapped it to two lines and changed nothing else.

bun scripts/gate.ts and bun x tsc --noEmit are green. The 44 offer tests across 8 files pass. bun scripts/fast.ts exited 2 (the diff is too broad to name), so I ran every test file whose name mentions offers instead. The forge runs the full check on this push.

To try it: POST a patch to /api/v1/repos/OWNER/NAME/offers of a public repository, then GET the status URL in the answer.

commented

An outsider's offer to a public repository now returns a random receipt and a status URL that answers that offer's state. This push only fixes the second gate failure, a long comment line in src/http/api.ts.

  • Cause: the long comment line in src/http/api.ts arrived with main. It only showed up after I merged origin/main into the branch, so bun scripts/gate.ts --fix had nothing to change before that.
  • Change: I ran the merge, ran bun scripts/gate.ts --fix, and committed the rewrap.
  • Checks run: bun scripts/gate.ts and bun x tsc --noEmit pass. I ran the offer test files rather than the whole suite: 44 tests across 8 files, all passing. The forge runs the full check on this push.

To try it: POST a patch to /api/v1/repos/OWNER/NAME/offers of a public repository, then GET the status URL in the answer.

commented

An outsider's offer to a public repository now returns a random receipt and a status URL, and GET /api/v1/offers/:receipt answers that offer's own state. An unknown receipt gets a 404. This push fixes the five red tests: the new GET route was not registered in the route inventories the repository keeps.

  • Route mark: /api/v1/offers is now marked open in src/http/route_marks.ts.
  • OpenAPI row: I added getApiV1OffersReceipt.ts and regenerated the route index with bun scripts/openapi-routes.ts.
  • Test lists: /api/v1/offers/:receipt goes in the UNSEEDED list of test/security-floor-routes.test.ts, with a reason: a receipt exists only once an offer is filed. For the same reason, MAX_UNFIXTURED in test/pages-budget.test.ts goes from 150 to 151. I raised the cap rather than add a fixture, to keep this change small. A fixture that files an offer and walks the real receipt would let the cap come back down, and I did not do it.

The four test files for those failures (pages-budget, security-floor-routes, route-marks, openapi-coverage) pass: 34 tests. The gate and bun x tsc --noEmit are clean. The full check runs on this push.

To try it: POST a patch to /api/v1/repos/OWNER/NAME/offers of a public repository, then GET the status URL in the answer.

commented

This push fixes the failed check: the gate rejected comment lines over 100 columns in src/http/route_marks.ts and test/pages-budget.test.ts.

I ran bun scripts/gate.ts --fix, which rewrapped those comments, and committed the result. Only comments changed, so the code is the same as before.

After the rewrap, bun scripts/gate.ts passes and bun x tsc --noEmit is clean. I did not rerun the tests, since no code changed. The forge's check will run them on this push.

The pull's description is unchanged: it still covers the offer status route (described, marked and listed).

Changes requested — before the latest push

The receipt works and is well built: 128 random bits, a strict hex check before the lookup, only that offer's own state is returned, wrong ids give 404, and the tests cover receipt, state change and wrong id. Three things to fix in one round:

  1. test/pages-budget.test.ts: MAX_UNFIXTURED goes 150 to 151. The file says to lower it as fixtures are added and never raise it silently. Add a fixture instead: file an offer in the test setup and map /api/v1/offers/:receipt to its real receipt. Then drop the cap bump and the UNSEEDED entry for it in test/security-floor-routes.test.ts.
  2. src/http/offer_routes.ts, offerStatusHandler: the status answer is polled and its state changes, but it has no cache header. Send cache-control: no-store so a shared cache never serves a stale state. Add a test for the header.
  3. src/http/mcp/offer.ts: required: [] drops repo, title and patch from the tool's schema. Clients can no longer tell what an offer needs, and tools/list grew from 362 to 424 bytes, which cuts against the tools/list size budget (#6217) in the direction. Keep required: ["repo","title","patch"] and give the state read a smaller door, or keep the schema honest some other way. Whichever you pick, state the byte cost in the pull.

Also check that issueReceipt cannot leave a filed pull with no receipt if its insert throws. Put it in the same transaction as the open, or say why it is safe.

Boxes 1, 2, 3 and 4 are met by this head. They are listed under left only because this review requests changes, and the verdict is not an approval.

commented

I've addressed all three points and the issueReceipt question; the changes are pushed to the same branch. tsc is clean and the offer-receipt, MCP-table, security-floor and pages-budget tests pass. I did not run the full suite. The bun scripts/fast.ts run reported 2198 of 3337 files for this diff, so I ran only those four files plus the earlier mcp* batch.

A person (or an outsider's agent) can offer a patch to a public repository and get back a receipt and a status link to poll without an account. It is POST /api/v1/repos/:owner/:name/offers, with the same receipt on the MCP offer tool's answer. GET /api/v1/offers/:receipt answers with that offer's own state and nothing else.

What changed in this round

  1. Fixtures: MAX_UNFIXTURED is back to 150. test/pages-budget.test.ts now issues a real receipt on its seeded pull and maps /api/v1/offers/:receipt to it. test/security-floor-routes.test.ts does the same: receipt is a seeded parameter and the UNSEEDED entry is gone.
  2. Cache header: offerStatusHandler sends cache-control: no-store, and test/offer-receipt.test.ts checks it.
  3. MCP schema: I removed the receipt argument from the offer tool, so required: ["repo","title","patch"] is back and the "read a state" mode is gone. tools/list for offer is 362 bytes again, the same as on main, with no growth. I regenerated docs/MCP.md with bun scripts/mcp-table.ts (that row goes from 424 to 362). A test asserts the required list and that receipt is not in the schema. The offer's answer, over MCP and HTTP, still carries receipt and a status URL, so a client polls over HTTP. That means an MCP client with no HTTP access can no longer read a state. I chose that over a second tool in tools/list.

issueReceipt after a failed insert: I did not change it. openPull awaits git, so the open and the receipt insert cannot share one SQLite transaction. The insert runs synchronously right after the open, with a fresh random id and a foreign key to a pull that exists. The only realistic failure is the database itself failing, and that would fail the open too. If it did throw, the caller would get a 500 and the pull would stay open for a maintainer to read, only without a receipt. I left that as it is.

Approved

Earlier asks are met: the fixtures replace the raised cap (MAX_UNFIXTURED back to 150), the status route sends no-store, and the MCP offer schema is back to required repo/title/patch with the receipt only in the reply. The issueReceipt failure path is a reasoned choice and I accept it. On the preview an unknown id answers 404. Non-blocking: an MCP client with no HTTP access cannot poll, which the pull states openly.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs