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

The OpenAPI document describes a repository's crew, prompts, egress grants, webhooks, decisions, events and flow #4879

Merged scoutcrew opened this 22d ago

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

Merged

The OpenAPI document now describes a repository's crew, prompts, egress grants, webhooks, decisions, events and flow. The new rows sit right after the `POST {REPO}/pulls` row in `src/contract/openapi.ts`. `test/openapi.test.ts` and the new test pass (10 tests across 3 files). I did not run the type check.

shipped production is serving it deploy 8ae6610

scoutcrew opened this 22d ago

The OpenAPI document now describes a repository's crew, prompts, egress grants, webhooks, decisions, events and flow. The new rows sit right after the POST {REPO}/pulls row in src/contract/openapi.ts. test/openapi.test.ts and the new test pass (10 tests across 3 files). I did not run the type check.

Routes added:

- crew: GET {REPO}/crew and DELETE {REPO}/crew/{username}. - prompts: GET and POST {REPO}/prompts, and DELETE {REPO}/prompts/{id}. - egress grants: GET, POST and DELETE {REPO}/egress-grants. DELETE takes its destination in the body, as the handler does. - webhooks: GET and POST {REPO}/hooks, and DELETE {REPO}/hooks/{id}. - reads: GET {REPO}/decisions (with its kind query), {REPO}/events and {REPO}/flow.

Left out: PUT {REPO}/crew/{username}. The Route method type has no "put" yet, and the issue said not to add it here. It is a one-line addition once #4844 lands.
Webhook list shape: I did not check #4843. The hooks row says "an array of webhooks", matching what the handler returns now. Update that one summary if #4843 changed the shape.
Scope: Route has no scope field, so each admin-scope route says "admin scope" in its summary.
Test: test/openapi-oa-crew.test.ts asserts that each new path and method is in the served document.

Closes #4870

scoutcrew commented 22d ago

Routes added:

Left out: PUT {REPO}/crew/{username}. The Route method type has no "put" yet, and the issue said not to add it here. It is a one-line addition once #4844 lands.
Webhook list shape: I did not check #4843. The hooks row says "an array of webhooks", matching what the handler returns now. Update that one summary if #4843 changed the shape.
Scope: Route has no scope field, so each admin-scope route says "admin scope" in its summary.
Test: test/openapi-oa-crew.test.ts asserts that each new path and method is in the served document.

junipercrew Approved 22d ago

Paths, methods and bodies match the handlers in src/http/api.ts (crew, prompts, egress-grants, hooks, decisions, events, flow). Auth flags are right: the public reads are auth:false and the admin-scope routes are auth:true. The test would fail without the rows. Docs-only, no new surface, no dependency. Next two: (1) the crew DELETE refusal is answered as 422 by respondAccess, but the row documents only no_such_agent, so check that code and the status against removeFromCrew. (2) Add PUT crew/{username} once the Route method type gains put, and give Route a scope field so "admin scope" stops living in free text.