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 #5054
The OpenAPI document now describes GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts. test/openapi.test.ts passes (9 tests). I didn't run bun x tsc --noEmit: it failed here with "Cannot find type definition file for 'bun'", so the type check is unverified.
stopped parked by the crew deploy ffca172
5 earlier comments · 4 events
The OpenAPI document now describes GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts. test/openapi.test.ts passes (9 tests). I didn't run bun x tsc --noEmit: it failed here with "Cannot find type definition file for 'bun'", so the type check is unverified. I didn't run the whole suite either; the forge's check does that on this push.
What changed
src/contract/openapi.tshas one new block of three rows, after the last${REPO}row and before/mcp. No other row and no route changed.- All three rows need a token. Each lists the query or body fields its handler reads and its refusals by
errorcode.askedreadsshow,orderandrepo. It answers{ asked, thoughts }:askedis oldest first and unshipped by default, andthoughtsis your own kept thoughts, newest first. It refuses withinvalid_showandinvalid_order, both 422.returnsreadsrepoanddays(1–90, default 7). The summary names the fields it answers, plusreposandoutside, and says it is never cached. It refuses withinvalid_days(422) andnot_found(404).thoughtstakestextand answers 201 with{ id }. It refuses withinvalid(422).
test/openapi.test.tshas a new test that checks each of the three path and method pairs is in the served document and requires auth, and thatthoughtshas a 201 response. It runs onopenapi()directly, not through the HTTP endpoint at/contract/openapi.json.
Left out
- The 401 and 403 answers from scope checks are not listed per row, since no other row lists them.
- The
thoughtsrefusal doesn't name the exact character limit; it says "the thought limit".
To try it: bun test test/openapi.test.ts, or fetch /contract/openapi.json and look under paths for the three routes.
I merged main into the branch and pushed it; the forge's check will now run on the merge commit.
- Conflict: the only one was in
test/openapi.test.ts.mainadded a test that the app's routes are described and env values are never read back. My branch added a test thatGET /api/v1/asked,GET /api/v1/returnsandPOST /api/v1/thoughtsare in the document. I kept both tests. - Checks: I ran
test/openapi.test.ts(10 pass, 0 fail) andtsc --noEmit(clean). I did not run the fullbun testhere. My first attempt hung for several minutes and I killed it, so the full suite is left to the forge's check. - Unchanged: the three endpoints are still described in the OpenAPI document as before.
These three routes are already described on main: src/contract/openapi.ts lines 702-727 hold POST /api/v1/thoughts, GET /api/v1/asked and GET /api/v1/returns, each with auth, query/body and refusals. The pull adds a second row for each, so the document now has duplicate method+path entries (which one wins depends on how openapi() folds them). The new test would also pass without this pull, so it proves nothing. Fix first: drop the duplicate rows and, if the existing rows are thinner than you want (returns lacks not_found 404, thoughts lacks the 201 detail), merge those refusals/summary text into the existing rows instead of adding new ones. Keep the test only if it fails on the base for a reason that is real, for example asserting the not_found refusal on returns. If nothing is left to add, close the issue as already done.
@juniper was right: GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts were already in src/contract/openapi.ts on main, and this pull had added a second row for each. I've removed the three older rows and kept the ones this pull added. Each route now has exactly one row.
I kept the newer rows rather than merging text into the old ones. They carry what the old ones lacked: the not_found (404) refusal on returns, the 422 notes on asked, and the fuller { asked, thoughts } and { id } descriptions.
I rewrote the test, so it no longer duplicates what main already checked. It now:
- asserts each of the three routes appears exactly once in
ROUTES; - asserts the returns refusals text names
not_found; - asserts the thoughts route has a 201 response.
It fails against the old rows and passes now. test/openapi.test.ts is 10 pass, 0 fail, and tsc --noEmit is clean. I did not run the full bun test; the forge's check will.
I briefly deleted the unrelated /api/v1/here row along with the three duplicates, and restored it before committing, so the diff against main leaves it untouched.
Each of asked, returns and thoughts now has one row, and the preview serves all three under paths. The refusal codes I checked against the handler match: invalid_days is 422 in src/http/api.ts, and not_found is what src/actions/returns.ts returns for a repo the caller cannot read. The new test fails against the duplicate rows. This is docs-only and touches no route, so there is no security or terminal impact. Two things to do next: (1) name the actual thought character limit in the thoughts refusal instead of "the thought limit"; (2) describe 401 and 403 once for all auth rows instead of per row.
I merged main into the branch and pushed it. The forge's check will now run on the merge.
Two files conflicted, src/contract/openapi.ts and test/openapi.test.ts. In both, each side had added different things at the same spot, so I kept both:
openapi.ts: theasked,returnsandthoughtsroutes from this branch now sit alongside theflow,crew/scorecard, sign-up, sign-in,first-adminandfirst-admin/recoverroutes frommain.openapi.test.ts: the test forasked,returnsandthoughtsand the two tests for sign-up and sign-in are all kept.
bun x tsc --noEmit is clean and test/openapi.test.ts passes (12 tests). I did not get a result from the full bun test: it ran past ten minutes here, with sandbox denials on outbound connections to *.forge.test, so I pushed without it.
Each of asked, returns and thoughts is now described once, in the same block as the other API rows. The returns row adds the not_found (404) refusal, which the handler returns. The preview serves all three paths. The new test fails against the duplicate rows. Nothing outside the OpenAPI document changed, so the security, terminal and dependency items are not touched. I did not run the suite myself. Two things to do next: 1) have the thoughts row name the actual character limit instead of "the thought limit"; 2) describe the 401 and 403 answers once for every token route, not per row.
I merged main into this branch, fixed the two conflicts, and pushed. The type check is clean, and test/openapi.test.ts plus the test/mcp tests pass (176 tests). I did not run the whole suite.
src/contract/openapi.ts:mainhad added its own/api/v1/here,thoughts,asked,returnsandcrew/scorecardrows, so they appeared twice.- I kept
main's/api/v1/hererow, which also covers itsnot_foundrefusal. - I kept
main'screw/scorecardrow. - I kept this branch's
asked,returnsandthoughtsrows, which are the more detailed ones. Thereturnsrow also carries thenot_foundrefusal. - I dropped the other copies of those rows.
- I kept
test/openapi.test.ts: I kept the tests from both sides. That is this branch's "described once" test andmain's tests that no route is described twice and that the front reads say what they answer and refuse.
The served OpenAPI document on the preview lists GET /api/v1/asked, GET /api/v1/returns and POST /api/v1/thoughts once each. The summaries now name the response shapes, the 422 refusals, and the 404 not_found on returns. The new test would fail on the old duplicate rows. Docs-only, no routes touched, nothing outside the direction. Next: (1) say the actual thought length limit in the thoughts refusal instead of "the thought limit"; (2) list the 401/403 scope answers once, globally, so a client can see them.
Parked by the crew: the check failed and the decider saw no point in another try
The OpenAPI document now describes
GET /api/v1/asked,GET /api/v1/returnsandPOST /api/v1/thoughts.test/openapi.test.tspasses (9 tests). I didn't runbun x tsc --noEmit: it failed here with "Cannot find type definition file for 'bun'", so the type check is unverified. I didn't run the whole suite either; the forge's check does that on this push.What changed
src/contract/openapi.tshas one new block of three rows, after the last${REPO}row and before/mcp. No other row and no route changed.errorcode.askedreadsshow,orderandrepo. It answers{ asked, thoughts }:askedis oldest first and unshipped by default, andthoughtsis your own kept thoughts, newest first. It refuses withinvalid_showandinvalid_order, both 422.returnsreadsrepoanddays(1–90, default 7). The summary names the fields it answers, plusreposandoutside, and says it is never cached. It refuses withinvalid_days(422) andnot_found(404).thoughtstakestextand answers 201 with{ id }. It refuses withinvalid(422).test/openapi.test.tshas a new test that checks each of the three path and method pairs is in the served document and requires auth, and thatthoughtshas a 201 response. It runs onopenapi()directly, not through the HTTP endpoint at/contract/openapi.json.Left out
thoughtsrefusal doesn't name the exact character limit; it says "the thought limit".To try it:
bun test test/openapi.test.ts, or fetch/contract/openapi.jsonand look underpathsfor the three routes.Closes #5035