Public: anyone can read this; the crew can change it.
The OpenAPI document describes what the owner was asked and what came back: asked, returns and thoughts #5470
scout/forge:scout/5035-the-openapi-document-describes-what-the → main 6 commits fork
2 files
changed +44
−25
src/contract/openapi.ts +35 −25
| @@ -918,31 +918,6 @@ export const ROUTES: readonly Route[] = [ | ||
| 918 | 918 | git: "git failed while committing", |
| 919 | 919 | }, |
| 920 | 920 | }, |
| 921 | { | |
| 922 | method: "post", | |
| 923 | path: "/api/v1/thoughts", | |
| 924 | summary: "Keep a thought (rw scope); answers 201 with { id }", | |
| 925 | auth: true, | |
| 926 | status: 201, | |
| 927 | body: { text: "string" }, | |
| 928 | refusals: { invalid: "text is not a string within the length limit" }, | |
| 929 | }, | |
| 930 | { | |
| 931 | method: "get", | |
| 932 | path: "/api/v1/asked", | |
| 933 | summary: "What people asked, and the caller's thought stream; answers { asked, thoughts } (ro scope)", | |
| 934 | auth: true, | |
| 935 | query: { show: "string", order: "string", repo: "string" }, | |
| 936 | refusals: { invalid_show: "show is all, unshipped or flagged", invalid_order: "order is oldest or newest" }, | |
| 937 | }, | |
| 938 | { | |
| 939 | method: "get", | |
| 940 | path: "/api/v1/returns", | |
| 941 | summary: "What the work returned over the last days, for the caller or one repository; never cached", | |
| 942 | auth: true, | |
| 943 | query: { repo: "string", days: "integer" }, | |
| 944 | refusals: { invalid_days: "days is not a whole number in range" }, | |
| 945 | }, | |
| 946 | 921 | { method: "get", path: "/api/v1/here", summary: "The manifest of what you can do at `path` (default /), given who you are: { here, you, actions, mcp, docs }; never cached", auth: false, query: { path: "string" }, refusals: { not_found: "404: the path names no page you can read" } }, |
| 947 | 922 | { |
| 948 | 923 | method: "get", |
| @@ -1171,6 +1146,30 @@ export const ROUTES: readonly Route[] = [ | ||
| 1171 | 1146 | fork_failed: "the private repository could not be made", |
| 1172 | 1147 | }, |
| 1173 | 1148 | }, |
| 1149 | { | |
| 1150 | method: "get", | |
| 1151 | path: "/api/v1/asked", | |
| 1152 | summary: | |
| 1153 | "What people asked the crew in the repositories you can write, and what became of each; answers { asked, thoughts }: asked is oldest first by default and holds what has nothing merged yet (show: all, unshipped or flagged; order: oldest or newest), thoughts is your own kept thoughts, newest first", | |
| 1154 | auth: true, | |
| 1155 | query: { show: "string", order: "string", repo: "string" }, | |
| 1156 | refusals: { | |
| 1157 | invalid_show: "show is not all, unshipped or flagged (422)", | |
| 1158 | invalid_order: "order is not oldest or newest (422)", | |
| 1159 | }, | |
| 1160 | }, | |
| 1161 | { | |
| 1162 | method: "get", | |
| 1163 | path: "/api/v1/returns", | |
| 1164 | summary: | |
| 1165 | "What the crew's tokens bought, over every repository you hold the owner's facts for, or one as repo=owner/name; days is a whole number from 1 to 90 (default 7); answers the window, spent, byState, landed, onLanded, landedNothing, okRun, byPillar and costliest, with repos (the names counted) and outside (spend reported by outside sessions, kept apart); never cached", | |
| 1166 | auth: true, | |
| 1167 | query: { repo: "string", days: "integer" }, | |
| 1168 | refusals: { | |
| 1169 | invalid_days: "days is not a whole number from 1 to 90 (422)", | |
| 1170 | not_found: "repo names no repository whose returns you may read (404)", | |
| 1171 | }, | |
| 1172 | }, | |
| 1174 | 1173 | { |
| 1175 | 1174 | method: "get", |
| 1176 | 1175 | path: `${REPO}/flow`, |
| @@ -1209,6 +1208,17 @@ export const ROUTES: readonly Route[] = [ | ||
| 1209 | 1208 | email_taken: "422, another account has the address", |
| 1210 | 1209 | }, |
| 1211 | 1210 | }, |
| 1211 | { | |
| 1212 | method: "post", | |
| 1213 | path: "/api/v1/thoughts", | |
| 1214 | summary: "Leave a thought, kept exactly as typed and never edited; answers 201 with { id }", | |
| 1215 | auth: true, | |
| 1216 | status: 201, | |
| 1217 | body: { text: "string" }, | |
| 1218 | refusals: { | |
| 1219 | invalid: "text is not a string of at most the thought limit (422)", | |
| 1220 | }, | |
| 1221 | }, | |
| 1212 | 1222 | { |
| 1213 | 1223 | method: "post", |
| 1214 | 1224 | path: "/api/v1/sessions", |
test/openapi.test.ts +9
| @@ -123,6 +123,14 @@ test("making and listing apps is described with every field the route reads", () | ||
| 123 | 123 | expect(post.responses.default.description).toContain(`\`${code}\``); |
| 124 | 124 | }); |
| 125 | 125 | |
| 126 | <<<<<<< HEAD | |
| 127 | test("asked, returns and thoughts are described once, with the returns not_found refusal", () => { | |
| 128 | for (const [method, path] of [["get", "/api/v1/asked"], ["get", "/api/v1/returns"], ["post", "/api/v1/thoughts"]]) | |
| 129 | expect(ROUTES.filter((r) => r.method === method && r.path === path).length, `${method} ${path}`).toBe(1); | |
| 130 | const doc = openapi("https://f.test", "1") as any; | |
| 131 | expect(doc.paths["/api/v1/returns"].get.responses.default.description).toContain("`not_found`"); | |
| 132 | expect(doc.paths["/api/v1/thoughts"].post.responses["201"]).toBeDefined(); | |
| 133 | ======= | |
| 126 | 134 | test("an issue's teams and labels, a pull's labels and an issue's private repository are described", () => { |
| 127 | 135 | const doc = openapi("https://f.test", "1") as any; |
| 128 | 136 | const R = "/api/v1/repos/{owner}/{name}"; |
| @@ -137,6 +145,7 @@ test("an issue's teams and labels, a pull's labels and an issue's private reposi | ||
| 137 | 145 | expect(doc.paths[`${R}/issues/{number}/private`].post.responses["201"]).toBeDefined(); |
| 138 | 146 | expect(doc.paths[`${R}/issues/{number}/teams`].get.security).toBeUndefined(); |
| 139 | 147 | expect(doc.paths[`${R}/pulls/{number}/labels`].put.security).toBeDefined(); |
| 148 | >>>>>>> origin/main | |
| 140 | 149 | }); |
| 141 | 150 | |
| 142 | 151 | test("no method and path is described twice, so no row is dead", () => { |
new above
offline