⚠️ Definition of Done: this issue must be completed in full, in a single PR. Do not split this
work across multiple PRs, and do not defer any Deliverable below to a follow-up issue. A PR that
satisfies only some of the Deliverables, stubs a required test, or leaves a checkbox
partially-done does NOT resolve this issue and will be closed.
⚠️ Required pattern: mirror how GET /v1/repos/{owner}/{repo}/gate-config/effective is documented
in src/openapi/spec.ts — issue #6611 fixed the exact same class of gap for that route.
Context
src/api/routes.ts exposes /v1/contributors/:login/watches across all three HTTP verbs — GET
(list), POST (watch), DELETE (unwatch) — as the REST mirror of the single MCP tool
loopover_watch_issues, whose action enum (per the route's own comment) "splits across the HTTP
verbs: GET=list, POST=watch, DELETE=unwatch." The tool's output shape, watchIssuesOutputSchema, is
already defined and validated in src/mcp/server.ts. None of the three verbs on this path appears
in src/openapi/spec.ts — grep for contributors/{login}/watches (and /watches generally)
returns nothing.
Requirements
- In
src/openapi/schemas.ts, define ContributorWatchesResponseSchema as a z.object({...})
schema using watchIssuesOutputSchema (the raw Zod shape already validated in
src/mcp/server.ts) as the field-level source of truth, plus a request-body schema for the
POST verb (repoFullName + labels, matching the REST route's body validation).
- In
src/openapi/spec.ts, registry.register the schema(s) as components, then add three
registerPath entries — GET, POST, DELETE — for /v1/contributors/{login}/watches, following the
pattern already used for the neighboring, already-documented
/v1/contributors/{login}/notifications and /v1/contributors/{login}/notifications/read paths.
- Schema is the contract — regenerate and commit. Run
npm run ui:openapi after the edits and
commit the regenerated apps/loopover-ui/public/openapi.json in this same PR. CI enforces this via
npm run ui:openapi:check (part of npm run test:ci).
Deliverables
All deliverables are required in this one PR — there is no follow-up issue.
Test Coverage Requirements
99%+ Codecov patch target (codecov/patch, unsharded via npm run test:coverage) on any new schema
helper code. Add a regression test asserting all three verbs appear in buildOpenApiSpec()'s output
for this path with response schemas whose keys match watchIssuesOutputSchema.
Expected Outcome
/v1/contributors/{login}/watches (all three verbs) is documented in GET /openapi.json /
apps/loopover-ui/public/openapi.json, matching what loopover_watch_issues already validates.
Links & Resources
Context
src/api/routes.tsexposes/v1/contributors/:login/watchesacross all three HTTP verbs — GET(list), POST (watch), DELETE (unwatch) — as the REST mirror of the single MCP tool
loopover_watch_issues, whoseactionenum (per the route's own comment) "splits across the HTTPverbs: GET=list, POST=watch, DELETE=unwatch." The tool's output shape,
watchIssuesOutputSchema, isalready defined and validated in
src/mcp/server.ts. None of the three verbs on this path appearsin
src/openapi/spec.ts— grep forcontributors/{login}/watches(and/watchesgenerally)returns nothing.
Requirements
src/openapi/schemas.ts, defineContributorWatchesResponseSchemaas az.object({...})schema using
watchIssuesOutputSchema(the raw Zod shape already validated insrc/mcp/server.ts) as the field-level source of truth, plus a request-body schema for thePOST verb (repoFullName + labels, matching the REST route's body validation).
src/openapi/spec.ts,registry.registerthe schema(s) as components, then add threeregisterPathentries — GET, POST, DELETE — for/v1/contributors/{login}/watches, following thepattern already used for the neighboring, already-documented
/v1/contributors/{login}/notificationsand/v1/contributors/{login}/notifications/readpaths.npm run ui:openapiafter the edits andcommit the regenerated
apps/loopover-ui/public/openapi.jsonin this same PR. CI enforces this vianpm run ui:openapi:check(part ofnpm run test:ci).Deliverables
ContributorWatchesResponseSchema(and a request-body schema for the POST verb) added tosrc/openapi/schemas.ts./v1/contributors/{login}/watchesinsrc/openapi/spec.ts.apps/loopover-ui/public/openapi.jsonregenerated vianpm run ui:openapiand committed.npm run ui:openapi:checkpasses in CI.All deliverables are required in this one PR — there is no follow-up issue.
Test Coverage Requirements
99%+ Codecov patch target (
codecov/patch, unsharded vianpm run test:coverage) on any new schemahelper code. Add a regression test asserting all three verbs appear in
buildOpenApiSpec()'s outputfor this path with response schemas whose keys match
watchIssuesOutputSchema.Expected Outcome
/v1/contributors/{login}/watches(all three verbs) is documented inGET /openapi.json/apps/loopover-ui/public/openapi.json, matching whatloopover_watch_issuesalready validates.Links & Resources
src/api/routes.ts:GET/POST/DELETE /v1/contributors/:login/watchessrc/mcp/server.ts:loopover_watch_issues,watchIssuesOutputSchemasrc/openapi/spec.ts:/v1/contributors/{login}/notificationsregistration (neighboring patternto mirror)