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

[hurryup52]

Closes #9310

(Fifth attempt — prior attempts were each auto-closed by the gate for a base-branch conflict in the generated apps/loopover-ui/public/openapi.json, never a content/review problem. This area of the spec is being actively documented by several parallel contributor PRs for other issues, landing in quick succession. 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 — 9/9 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.

[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}

[superagent-security]

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

[hurryup52]

Closing — #9452 (andriypolanski) merged the same fix for #9310 first. No further action needed here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.69%. Comparing base (a4894da) to head (3aca579).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9454      +/-   ##
==========================================
+ Coverage   75.51%   75.69%   +0.18%     
==========================================
  Files         275      277       +2     
  Lines       58032    58480     +448     
  Branches     6209     6216       +7     
==========================================
+ Hits        43820    44267     +447     
  Misses      13942    13942              
- Partials      270      271       +1     

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