The OpenAPI document describes the caller's origins: list, add, connect by OAuth, sync, read repositories, remove #5167

The served OpenAPI document now describes the caller's origins, so an agent can bring code over from GitHub or Forgejo from the document alone. The OpenAPI tests pass (25 across 11 files). The type check did not run: tsc can't find the bun types in this sandbox, even after the install.

What changed

• src/contract/openapi.ts gets seven new rows, placed as one block directly after GET /api/v1/migrate/{job}. No other row changed.
• The rows are GET and POST /api/v1/user/origins, POST /api/v1/user/origins/oauth, GET /api/v1/user/origins/oauth/{id}, DELETE /api/v1/user/origins/{id}, POST /api/v1/user/origins/{id}/sync and GET /api/v1/user/origins/{id}/repos.
• Each row has auth and the body or query its handler reads. The two POSTs that create something carry status: 201.
• Each row lists its refusals by stable error code, taken from the handlers: unauthorized, forbidden, not_found, and the connect codes such as bad_token, already_connected, no_app, origin_unreachable and rate_limited.
• The summaries say these routes take the account only: a session, the password or an admin-scope token. The repos summary tells the agent to pass an item's fullName to POST /api/v1/migrate as { source: { originId, fullName } }.
• No row has an example, and the document never shows a token; the new test checks that it holds no token-shaped text.
• test/openapi.test.ts has a new test that asserts every new path and method is in the served document, and that the two POSTs that create something declare a 201.

Left out

• Response schemas. The existing rows describe responses in the summary text and I did the same.
• The /api/v1/user/origin-apps routes and the browse, mirror and fork routes under an origin, which the issue didn't list. This matters for OAuth: no_app points at /api/v1/user/origin-apps, and that route is still undocumented.

Closes #5151

The served OpenAPI document now describes the caller's origins, so an agent can bring code over from GitHub or Forgejo from the document alone. The OpenAPI tests pass (25 across 11 files). The type check did not run: tsc can't find the bun types in this sandbox, even after the install.

What changed

• src/contract/openapi.ts gets seven new rows, placed as one block directly after GET /api/v1/migrate/{job}. No other row changed.
• The rows are GET and POST /api/v1/user/origins, POST /api/v1/user/origins/oauth, GET /api/v1/user/origins/oauth/{id}, DELETE /api/v1/user/origins/{id}, POST /api/v1/user/origins/{id}/sync and GET /api/v1/user/origins/{id}/repos.
• Each row has auth and the body or query its handler reads. The two POSTs that create something carry status: 201.
• Each row lists its refusals by stable error code, taken from the handlers: unauthorized, forbidden, not_found, and the connect codes such as bad_token, already_connected, no_app, origin_unreachable and rate_limited.
• The summaries say these routes take the account only: a session, the password or an admin-scope token. The repos summary tells the agent to pass an item's fullName to POST /api/v1/migrate as { source: { originId, fullName } }.
• No row has an example, and the document never shows a token; the new test checks that it holds no token-shaped text.
• test/openapi.test.ts has a new test that asserts every new path and method is in the served document, and that the two POSTs that create something declare a 201.

Left out

• Response schemas. The existing rows describe responses in the summary text and I did the same.
• The /api/v1/user/origin-apps routes and the browse, mirror and fork routes under an origin, which the issue didn't list. This matters for OAuth: no_app points at /api/v1/user/origin-apps, and that route is still undocumented.

I merged main into this branch and pushed it. The only conflict was in test/openapi.test.ts, and I resolved it by keeping both sides' tests.

• What was in conflict: my origins test (list, add, OAuth connect, sync, read repositories, remove, and no token in the document) and the three tests main added. Those three cover a person's sign-ins and ending a session, a repository's branch and contents writes, and the contents refusals.
• Tests: bun test test/openapi.test.ts passes (17 tests). I did not run the full suite; the forge runs the whole check on the push.
• Type check: bun x tsc --noEmit didn't run. It stops with "Cannot find type definition file for 'bun'", and I didn't install dependencies, so the merge hasn't been type-checked.

src/contract/openapi.ts merged automatically with no conflict.

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

The OpenAPI document now describes the caller's origins again on the new layout, and I pushed it. The OpenAPI tests pass (274). I did not run tsc: in this sandbox it failed to resolve the bun types.

• Merge: I merged main. Main had split src/contract/openapi.ts into one file per route, so I took main's version of that file and put this pull's seven rows into their own route files under src/contract/openapi/routes/. I regenerated the route index with bun scripts/openapi-routes.ts.
• Routes covered:

- list origins (GET) - add by token (POST) - start OAuth (POST oauth) - poll OAuth (GET oauth/{id}) - remove (DELETE {id}) - sync (POST {id}/sync) - list repositories (GET {id}/repos, with refresh=1)

• Contents: The summaries, refusals and 201 statuses are unchanged from what sentinel approved.
• Origin-apps follow-up: Main has since documented /api/v1/user/origin-apps (GET, POST, DELETE {id}). The no_app refusal now points at routes the document does describe, so sentinel's follow-up is already done.
• Tests: In test/openapi.test.ts, both conflicting tests are kept, this pull's origins test and main's mirror/fork one. I removed the seven now-described routes from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts. The coverage test still reports 15 other entries that could be removed. They aren't from this pull and I left them.

No runtime code, MCP tool, dependency or secret changed.

Sentinel's review is an approval with no requested changes, so I changed nothing and pushed nothing new.

The pull is still the contract-only change Sentinel checked: seven route descriptions for the caller's origins, plus their tests.

I'm not disputing anything in the review. I did not re-run the tests or the type check in this turn.

Handed to a person by the crew: this pull is approved, but 2 runs to bring it up to date with main ended without a push, so no more start here. Conflicting files: src/contract/openapi/routes/index.ts, test/openapi-coverage.test.ts. Merge main into it, or say what to try and assign it back to the crew. (The forge posts this under your name; you did not write it.)

I merged main into the branch and pushed it. The two conflicts were in src/contract/openapi/routes/index.ts and test/openapi-coverage.test.ts.

• routes/index.ts: I kept both sides. The seven origins route exports from this pull sit beside main's new user, keys, pins and browse routes, in alphabetical order.
• openapi-coverage.test.ts: I removed the origins entries from NOT_YET_DESCRIBED (list, add, OAuth connect, sync, repos, delete), because this pull now describes them. I took main's removals of the other entries (boards, hold, share and the browse routes).
• Checks: bun test test/openapi passes, 338 tests. I did not get a type check: bun x tsc --noEmit fails here with "Cannot find type definition file for 'bun'", and I did not fix that. The forge's check on the push will run it.

The coverage test prints "44 NOT_YET_DESCRIBED entries could be removed". I didn't investigate it and left the list as main has it.