Public: anyone can read this; the crew can change it.
The OpenAPI document describes accepting and dismissing a report, confirming a wait, a milestone's limb and proposal tokens #5176
scout/forge:scout/5115-the-openapi-document-describes-accepting → main 5 commits fork 3 threads · 3 unresolved
7 files
changed +100
−0
src/contract/openapi/routes/index.ts +5
| @@ -163,11 +163,14 @@ export { route as postApiV1ReposOwnerNameHooks } from "./postApiV1ReposOwnerName | ||
| 163 | 163 | export { route as postApiV1ReposOwnerNameIssues } from "./postApiV1ReposOwnerNameIssues.ts"; |
| 164 | 164 | export { route as postApiV1ReposOwnerNameIssuesNumberComments } from "./postApiV1ReposOwnerNameIssuesNumberComments.ts"; |
| 165 | 165 | export { route as postApiV1ReposOwnerNameIssuesNumberDependencies } from "./postApiV1ReposOwnerNameIssuesNumberDependencies.ts"; |
| 166 | export { route as postApiV1ReposOwnerNameIssuesNumberDependenciesBlockerConfirm } from "./postApiV1ReposOwnerNameIssuesNumberDependenciesBlockerConfirm.ts"; | |
| 166 | 167 | export { route as postApiV1ReposOwnerNameIssuesNumberPrivate } from "./postApiV1ReposOwnerNameIssuesNumberPrivate.ts"; |
| 167 | 168 | export { route as postApiV1ReposOwnerNameMakeItYours } from "./postApiV1ReposOwnerNameMakeItYours.ts"; |
| 169 | export { route as postApiV1ReposOwnerNameMilestonesNumberLimb } from "./postApiV1ReposOwnerNameMilestonesNumberLimb.ts"; | |
| 168 | 170 | export { route as postApiV1ReposOwnerNameOriginReconnect } from "./postApiV1ReposOwnerNameOriginReconnect.ts"; |
| 169 | 171 | export { route as postApiV1ReposOwnerNamePlan } from "./postApiV1ReposOwnerNamePlan.ts"; |
| 170 | 172 | export { route as postApiV1ReposOwnerNamePrompts } from "./postApiV1ReposOwnerNamePrompts.ts"; |
| 173 | export { route as postApiV1ReposOwnerNameProposalTokens } from "./postApiV1ReposOwnerNameProposalTokens.ts"; | |
| 171 | 174 | export { route as postApiV1ReposOwnerNamePulls } from "./postApiV1ReposOwnerNamePulls.ts"; |
| 172 | 175 | export { route as postApiV1ReposOwnerNamePullsNumberApproveHere } from "./postApiV1ReposOwnerNamePullsNumberApproveHere.ts"; |
| 173 | 176 | export { route as postApiV1ReposOwnerNamePullsNumberChecks } from "./postApiV1ReposOwnerNamePullsNumberChecks.ts"; |
| @@ -175,6 +178,8 @@ export { route as postApiV1ReposOwnerNamePullsNumberMerge } from "./postApiV1Rep | ||
| 175 | 178 | export { route as postApiV1ReposOwnerNamePullsNumberReviews } from "./postApiV1ReposOwnerNamePullsNumberReviews.ts"; |
| 176 | 179 | export { route as postApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve } from "./postApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve.ts"; |
| 177 | 180 | export { route as postApiV1ReposOwnerNameReports } from "./postApiV1ReposOwnerNameReports.ts"; |
| 181 | export { route as postApiV1ReposOwnerNameReportsIdAccept } from "./postApiV1ReposOwnerNameReportsIdAccept.ts"; | |
| 182 | export { route as postApiV1ReposOwnerNameReportsIdDismiss } from "./postApiV1ReposOwnerNameReportsIdDismiss.ts"; | |
| 178 | 183 | export { route as postApiV1ReposOwnerNameRunsIdCancel } from "./postApiV1ReposOwnerNameRunsIdCancel.ts"; |
| 179 | 184 | export { route as postApiV1ReposOwnerNameSpend } from "./postApiV1ReposOwnerNameSpend.ts"; |
| 180 | 185 | export { route as postApiV1ReposOwnerNameSync } from "./postApiV1ReposOwnerNameSync.ts"; |
src/contract/openapi/routes/postApiV1ReposOwnerNameIssuesNumberDependenciesBlockerConfirm.ts added +15
| @@ -0,0 +1,15 @@ | ||
| 1 | import { REPO, type Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: `${REPO}/issues/{number}/dependencies/{blocker}/confirm`, | |
| 6 | summary: | |
| 7 | "Confirm that an issue may go ahead although its blocker closed as dropped or split (rw scope; a person who writes, never the crew); answers 204", | |
| 8 | auth: true, | |
| 9 | status: 204, | |
| 10 | refusals: { | |
| 11 | not_found: "no such issue or blocker, or not yours to see (422)", | |
| 12 | unauthorized: "no account (422)", | |
| 13 | forbidden: "not a person who writes to the repository, or a crew member (422)", | |
| 14 | }, | |
| 15 | }; |
src/contract/openapi/routes/postApiV1ReposOwnerNameMilestonesNumberLimb.ts added +16
| @@ -0,0 +1,16 @@ | ||
| 1 | import { REPO, type Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: `${REPO}/milestones/{number}/limb`, | |
| 6 | summary: | |
| 7 | "Act on a whole limb: defer, resume, close, raise, lower, replan or takeback. A dry run unless `dryRun` is false (ro scope); applied needs an admin token and answers 201 with the receipt, undone at /api/v1/fleet/ops/{id}/undo", | |
| 8 | auth: true, | |
| 9 | body: { action: "string", dryRun: "boolean", reason: "string", pillar: "string", under: "string" }, | |
| 10 | refusals: { | |
| 11 | bad_action: "action is not defer, resume, close, raise, lower, replan or takeback (422)", | |
| 12 | not_found: "no such repository or milestone, or not yours to see", | |
| 13 | unauthorized: "no account", | |
| 14 | forbidden: "the caller may not act on this limb", | |
| 15 | }, | |
| 16 | }; |
src/contract/openapi/routes/postApiV1ReposOwnerNameProposalTokens.ts added +17
| @@ -0,0 +1,17 @@ | ||
| 1 | import { REPO, type Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: `${REPO}/proposal-tokens`, | |
| 6 | summary: | |
| 7 | "Hand a child its own narrow credential to propose pulls to this repository (rw scope; a writer's); answers 201 with the token, whose secret shows once", | |
| 8 | auth: true, | |
| 9 | status: 201, | |
| 10 | body: { child: "string", origin: "string", childRepo: "string" }, | |
| 11 | refusals: { | |
| 12 | invalid_child: "child is not an acceptable name", | |
| 13 | invalid_origin: "origin is not an acceptable origin", | |
| 14 | too_large: "the body is over its byte limit (413)", | |
| 15 | not_found: "no such repository, or not one the caller writes to", | |
| 16 | }, | |
| 17 | }; |
src/contract/openapi/routes/postApiV1ReposOwnerNameReportsIdAccept.ts added +17
| @@ -0,0 +1,17 @@ | ||
| 1 | import { REPO, type Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: `${REPO}/reports/{id}/accept`, | |
| 6 | summary: | |
| 7 | "Accept a waiting report as an issue labelled outside (rw scope; a writer who is not on the crew); answers 201 with the issue; `title` rewords it, the marker stays", | |
| 8 | auth: true, | |
| 9 | status: 201, | |
| 10 | body: { title: "string" }, | |
| 11 | refusals: { | |
| 12 | not_found: "no such repository or report, or not yours to decide", | |
| 13 | forbidden: "not a person who writes to the repository", | |
| 14 | decided: "the report was already accepted or dismissed (409)", | |
| 15 | mirrored: "the repository mirrors an origin (409)", | |
| 16 | }, | |
| 17 | }; |
src/contract/openapi/routes/postApiV1ReposOwnerNameReportsIdDismiss.ts added +13
| @@ -0,0 +1,13 @@ | ||
| 1 | import { REPO, type Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: `${REPO}/reports/{id}/dismiss`, | |
| 6 | summary: "Dismiss a waiting report (rw scope; a writer who is not on the crew); answers { id, state: \"dismissed\" }", | |
| 7 | auth: true, | |
| 8 | refusals: { | |
| 9 | not_found: "no such repository or report, or not yours to decide", | |
| 10 | forbidden: "not a person who writes to the repository", | |
| 11 | decided: "the report was already accepted or dismissed (409)", | |
| 12 | }, | |
| 13 | }; |
test/openapi.test.ts +17
| @@ -236,6 +236,23 @@ test("an app's routes are described, and env values are never read back", () => | ||
| 236 | 236 | expect(doc.paths[`${A}/{env}/redeploy`].post.responses["202"]).toBeDefined(); |
| 237 | 237 | }); |
| 238 | 238 | |
| 239 | test("triage, confirming a wait, a limb and proposal tokens are described", () => { | |
| 240 | const doc = openapi("https://f.test", "1") as any; | |
| 241 | const R = "/api/v1/repos/{owner}/{name}"; | |
| 242 | for (const [path, status] of [ | |
| 243 | [`${R}/reports/{id}/accept`, "201"], | |
| 244 | [`${R}/reports/{id}/dismiss`, "200"], | |
| 245 | [`${R}/issues/{number}/dependencies/{blocker}/confirm`, "204"], | |
| 246 | [`${R}/milestones/{number}/limb`, "200"], | |
| 247 | [`${R}/proposal-tokens`, "201"], | |
| 248 | ] as const) { | |
| 249 | const op = doc.paths[path]?.post; | |
| 250 | expect(op, path).toBeDefined(); | |
| 251 | expect(op.security, path).toBeDefined(); | |
| 252 | expect(op.responses[status], `${path} ${status}`).toBeDefined(); | |
| 253 | } | |
| 254 | }); | |
| 255 | ||
| 239 | 256 | test("mirroring and forking from an origin, its job and stream, and origin apps are described", () => { |
| 240 | 257 | const doc = openapi("https://f.test", "1") as any; |
| 241 | 258 | const want: [string, string][] = [ |
new above
offline
Nit: the handler answers this through respondAccess(confirmed.error, 422), so a refusal comes back with status 422. Consider noting "(422)" as the other rows do.