fix(openapi): document /v1/opportunities/find + /v1/issue-rag/retrieve

[hurryup52]

Closes #9310

(Third attempt — #9423 and #9428 were both auto-closed by the gate for a base-branch conflict in the generated apps/loopover-ui/public/openapi.json. This area of the spec is being actively documented by several parallel PRs for other issues, each landing in quick succession and touching the same generated file/import blocks. This PR is rebased onto the current main tip with all conflicts resolved; no content changes from the prior attempts.)

What

/v1/opportunities/find (OPPORTUNITIES_FIND_PATH, backing the loopover_find_opportunities MCP tool) and /v1/issue-rag/retrieve (ISSUE_RAG_RETRIEVE_PATH, backing loopover_retrieve_issue_context) are fully implemented and access-gated in src/api/routes.ts, but were never registered with the OpenAPI generator — grep for opportunities/find/issue-rag in src/openapi/spec.ts previously returned nothing, so neither route appeared in GET /openapi.json or the committed apps/loopover-ui/public/openapi.json.

Changes

• src/openapi/schemas.ts: added FindOpportunitiesRequestSchema/FindOpportunitiesResponseSchema and IssueRagRetrieveRequestSchema/IssueRagRetrieveResponseSchema. Field shapes mirror the MCP tools' own Zod shapes verbatim (findOpportunitiesShape/findOpportunitiesOutputSchema and issueRagShape/issueRagOutputSchema in src/mcp/server.ts) so the contract can't silently drift from what the tools actually validate — reused the same MAX_FIND_OPPORTUNITIES_*/MAX_ISSUE_RAG_*/PREFLIGHT_LIMITS constants those shapes already use.
• src/openapi/spec.ts: registered both response schemas as named components (FindOpportunitiesResponse, IssueRagRetrieveResponse) and added two registerPath POST entries, following the same pattern used for GET /v1/repos/{owner}/{repo}/gate-config/effective (OpenAPI spec is missing GET /v1/repos/{owner}/{repo}/gate-config/effective (documented sibling: live-gate-thresholds) #6611) and the existing POST-with-body routes (e.g. the incident-reports pair). Response codes (400/401/403) are matched to each route handler's actual behavior in routes.ts.
• apps/loopover-ui/public/openapi.json: regenerated via npm run ui:openapi and committed. npm run ui:openapi:check passes.
• test/unit/openapi.test.ts: added assertions that both paths are defined, that both response schema components are registered, and that their fields (aiPolicyAllowed, retrievedPathCount) match the MCP output shapes — a regression guard against future drift between the two.

Verification

• npx vitest run test/unit/openapi.test.ts — 7/7 pass (merges cleanly alongside the other recently-landed OpenAPI-documentation tests in this file).
• npm run ui:openapi:check — passes.
• npm run typecheck — clean.
• Rebased directly onto current main tip immediately before opening this PR.

[superagent-security]

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

[loopover-orb]

This repository reviews pull requests one-shot: the PR must be correct as originally opened. Pushing an additional commit closes it automatically instead of restarting review — open a fresh pull request with every fix included.

[loopover-orb]

Important

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏳ LoopOver is waiting…

LoopOver has seen this pull request and is waiting on CI checks to finish before reviewing it. This comment will update once the review runs.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.68%. Comparing base (fb8e2eb) to head (780e8e2).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9439      +/-   ##
==========================================
+ Coverage   75.51%   75.68%   +0.17%     
==========================================
  Files         275      277       +2     
  Lines       58032    58464     +432     
  Branches     6209     6216       +7     
==========================================
+ Hits        43820    44251     +431     
  Misses      13942    13942              
- Partials      270      271       +1     

Flag	Coverage Δ
backend	99.76% <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.61% <100.00%> (ø)