fix(api): document /v1/contributors/:login/watches in OpenAPI spec

[nghetien]

Summary

• /v1/contributors/:login/watches (GET/POST/DELETE) was implemented and validated at runtime but missing from the OpenAPI spec, so apps/loopover-ui/public/openapi.json and generated clients had no record of it.
• Adds WatchSubscriptionSchema, WatchSubscriptionListSchema, WatchSubscriptionChangeSchema, and WatchSubscriptionRequestSchema to src/openapi/schemas.ts, mirroring the shape already validated by the MCP tool's watchIssuesOutputSchema (src/mcp/server.ts).
• Registers all three verbs in src/openapi/spec.ts following the pattern of the neighboring /v1/contributors/{login}/notifications and /notifications/read paths (same security scheme, same 400/403 documentation style).
• Regenerates and commits apps/loopover-ui/public/openapi.json via npm run ui:openapi.

Closes #9306

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (Closes #9306).

Validation

• git diff --check
• npm run actionlint (no workflow files changed; skipped)
• npm run typecheck (via engine/mcp/miner builds + vitest typecheck path)
• npm run test:coverage — ran targeted + vitest run --changed=upstream/main (134 files, 1723 tests passed); src/openapi/** changes are fully covered by the new/updated assertions in test/unit/openapi.test.ts
• npm run test:workers (not run this session; change does not touch Workers-specific code)
• npm run build:mcp (ran turbo run build --filter=@loopover/mcp directly instead — passed)
• npm run test:mcp-pack (not run this session; no MCP tool surface changed)
• npm run ui:openapi:check
• npm run ui:lint (not run; no UI source files changed, only the generated openapi.json)
• npm run ui:typecheck (not run; no UI source files changed)
• npm run ui:build (not run; no UI source files changed)
• npm audit --audit-level=moderate (not run this session)
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — added assertions in test/unit/openapi.test.ts pinning all three verbs and their response/request $ref schema names.

If any required check was skipped, explain why:

• This is a pure OpenAPI-documentation change (no route/handler behavior changed), so the UI build/lint/typecheck and mcp-pack/workers/actionlint checks were judged low-risk and not re-run locally in this pass; ui:openapi:check (the check that directly gates this diff) was run and passes.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no auth/session code changed.)
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — no UI source changed, only generated openapi.json.)
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots. (N/A — no visible UI/frontend change; this is a backend OpenAPI-spec-only documentation change.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (No changelog edit made.)

Notes

• No behavior change to the actual route handlers in src/api/routes.ts — they already implement and validate GET/POST/DELETE /v1/contributors/:login/watches correctly; this PR only adds the missing OpenAPI documentation layer.

[superagent-security]

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

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-27 16:52:44 UTC}

4 files · 1 AI reviewer · no blockers · readiness 95/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds pure OpenAPI documentation (schemas + path registrations) for the already-implemented /v1/contributors/{login}/watches endpoint (GET/POST/DELETE), mirroring the existing MCP watchIssuesOutputSchema shape and the neighboring notifications endpoint's spec pattern. The new WatchSubscriptionRequestSchema correctly marks labels as optional (matches the regenerated openapi.json's required array containing only repoFullName), and the new openapi.test.ts assertions pin all three verbs plus their $ref schema names. This is a narrow, mechanical, low-risk documentation-only change with no runtime code touched.

Nits — 4 non-blocking

• src/openapi/schemas.ts: WatchSubscriptionRequestSchema's min(3)/max(200)/max(50) bounds are unexplained magic numbers — a short comment noting they mirror the runtime validator (if that's the source) would help future readers confirm they stay in sync.
• The POST and DELETE paths in src/openapi/spec.ts share an identical request/response schema shape (WatchSubscriptionRequestSchema/WatchSubscriptionChangeSchema) — worth a one-line comment noting this is intentional (both mutate the same subscription list) rather than copy-paste drift.
• Confirm the numeric bounds (min 3 / max 200 for repoFullName, max 100 per label / max 50 labels) in src/openapi/schemas.ts:562-567 actually match the runtime route's validator, since a spec/runtime mismatch here would silently mislead API consumers.
• test/unit/openapi.test.ts's new test is a good pin — consider also asserting the GET response schema ref name (WatchSubscriptionList) the same way the POST/DELETE refs are asserted, for full parity.

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: 14 registered-repo PR(s), 7 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nghetien; Gittensor profile; 14 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: minor

Linked issue satisfaction

Addressed
The PR adds WatchSubscription/WatchSubscriptionList/WatchSubscriptionChange/WatchSubscriptionRequest schemas to schemas.ts, registers GET/POST/DELETE for /v1/contributors/{login}/watches in spec.ts mirroring the notifications pattern, regenerates openapi.json, and adds regression tests asserting all three verbs and matching response schema refs.

Review context

• Author: nghetien
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Dart, JavaScript, Python, CSS, C#, C++, TypeScript
• Official Gittensor activity: 14 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Triage stale or unlinked PRs.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.59%. Comparing base (b4064b6) to head (8fe39ad).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9410      +/-   ##
==========================================
+ Coverage   75.46%   75.59%   +0.13%     
==========================================
  Files         275      277       +2     
  Lines       58030    58361     +331     
  Branches     6199     6206       +7     
==========================================
+ Hits        43790    44120     +330     
  Misses      13970    13970              
- Partials      270      271       +1     

Flag	Coverage Δ
backend	99.69% <100.00%> (?)

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

Files with missing lines	Coverage Δ
src/openapi/schemas.ts	100.00% <100.00%> (ø)
src/openapi/spec.ts	99.49% <100.00%> (ø)

[loopover-orb]

This pull request changes UI/visual code but its screenshot evidence is incomplete. Every required viewport × theme combination needs its own before/after image pair in a labeled table row (e.g. "Desktop · Light | before | after"). Still missing: Desktop · Dark, Tablet · Dark, Mobile · Dark.

Please resubmit with the remaining rows filled in.

See https://github.com/JSONbored/loopover/blob/main/.claude/skills/contributing-to-loopover/SKILL.md for the exact format and examples. This is an automated maintenance action.

[JSONbored]

Re-opened to re-review, but merge conflicts so re-closing.

This branch has conflicts that must be resolved
Use the web editor or the command line to resolve conflicts before continuing.

apps/loopover-ui/public/openapi.json