fix(openapi): document contributor watches GET/POST/DELETE (#9306)

[wondercreatemaster]

Summary

• Document GET/POST/DELETE /v1/contributors/{login}/watches in the OpenAPI contract — the REST mirror of loopover_watch_issues was live but missing from src/openapi/spec.ts / openapi.json.
• Add MCP-aligned ContributorWatchesResponseSchema (matching watchIssuesOutputSchema) and ContributorWatchRequestSchema (repoFullName + optional labels) for the mutating verbs.
• Regenerate apps/loopover-ui/public/openapi.json and add a field-parity regression test for all three verbs.

Test plan

• Single commit on latest main
• npm run ui:openapi + npm run ui:openapi:check
• npx vitest run test/unit/openapi.test.ts
• CI validate / codecov/patch on the PR

Fixes #9306

Made with Cursor

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-27 19:10:00 UTC}

5 files · 1 AI reviewer · no blockers · CI green · dirty

⏸️ Suggested Action - Manual Review

Review summary
This PR adds OpenAPI documentation for the three contributor-watches REST verbs (GET/POST/DELETE) that already exist as live routes but were undocumented, mirroring the MCP `loopover_watch_issues` tool schemas. It exports `watchIssuesOutputSchema` from src/mcp/server.ts so the new test can assert field parity with the OpenAPI response schema, and regenerates openapi.json plus adds a targeted parity regression test. The change is scoped, additive, and matches its stated intent (fixes #9306) — the request/response schemas correctly reuse the same shapes as the existing MCP tool.

Nits — 5 non-blocking

• The `magic numbers` (3, 200, 50, HTTP status codes) flagged by the external brief in src/openapi/schemas.ts:548-549 and src/openapi/spec.ts are consistent with existing repo convention (inline literal limits mirroring `watchIssuesShape` in src/mcp/server.ts) rather than a new pattern, so they're low-value nits at most.
• The `ContributorWatchesResponseSchema` marks both `watching` and `changed` as `.optional()`, so a malformed/empty response body would still pass validation — verify that's intentional parity with `watchIssuesOutputSchema` (src/openapi/schemas.ts) rather than an oversight.
• The GET verb registers no requestBody but the REST route presumably takes no body either — worth double-checking `src/api/routes.ts` GET handler doesn't accept query params that should also be documented as parameters.
• Consider adding a short JSDoc note on why `ContributorWatchRequestSchema` is duplicated instead of reusing `watchIssuesShape` from src/mcp/server.ts directly, since the two currently drift-risk each other despite the comment claiming parity.
• No migration or schema changes here, so nothing else to flag structurally — the PR is well-targeted to its stated issue.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9306
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 33 registered-repo PR(s), 21 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	wondercreatemaster; Gittensor profile; 33 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The PR adds ContributorWatchesResponseSchema and ContributorWatchRequestSchema in schemas.ts sourced from watchIssuesOutputSchema, registers all three GET/POST/DELETE paths for /v1/contributors/{login}/watches in spec.ts mirroring the notifications pattern, regenerates openapi.json, and adds a regression test verifying field parity with watchIssuesOutputSchema.

Review context

• Author: wondercreatemaster
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 33 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop	before /	after /	—
/	mobile	before / (mobile)	after / (mobile)	—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

Scroll preview

Route	Before (production)	After (this PR's preview)
/	before / (scroll)	after / (scroll)

A short scroll-through clip (desktop) — click either thumbnail to open the full animation. Evidence for scroll-linked behavior a single screenshot can't show.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.12%. Comparing base (fb8e2eb) to head (155a97f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #9446       +/-   ##
===========================================
- Coverage   89.54%   76.12%   -13.42%     
===========================================
  Files         843      278      -565     
  Lines      110011    59684    -50327     
  Branches    26184     6456    -19728     
===========================================
- Hits        98511    45436    -53075     
- Misses      10238    13955     +3717     
+ Partials     1262      293      -969     

Flag	Coverage Δ
backend	97.82% <100.00%> (+2.55%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/mcp/server.ts	97.13% <100.00%> (ø)
src/openapi/schemas.ts	100.00% <100.00%> (ø)
src/openapi/spec.ts	99.61% <100.00%> (+<0.01%)	⬆️

... and 703 files with indirect coverage changes

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (conflicts with the base branch — resolve and open a fresh PR). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.