feat(control-plane): version all API routes under /api/v2

[leghadjeu-christian]

1. Summary

This PR changes:

• Extracts all serve-role routes from the flat app() into api_v2_router(), nested under /api/v2. Health probes (/healthz, /readyz) and /metrics stay at root — they are k8s/Alloy targets, not API consumers.
• ControlPlaneClient::new() and ApiClient::new() now strip trailing slashes from the base URL but no longer append /api/v2. The env var (CONTROL_PLANE_INTERNAL_URL, AUTH_BACKEND_URL, api_url) must carry the full versioned path. The companion chart PR ADORSYS-GIS/ai-helm#817 updates those values.
• Fixes two #[sqlx::test] helpers that passed 1001 as installation_id but configured projects with id 2001/2002, causing 404s.
• Adds ADR-0109.

It solves:

• Story [Story]: Migrate every route to /api/v2 #506 — Migrate every route to /api/v2
• Part of Epic [Epic]: Unify service domain under code-intelligence-api.ai.camer.digital #492

---

2. Intent

Version every control-plane API route under /api/v2. The prefix is no longer baked into clients at construction time — it belongs in the env var. The companion chart PR adds it there. Tests pass server.uri() directly and mock /internal/tasks/... without any prefix manipulation.

---

3. Scope

In Scope

• services/control-plane/src/main.rs — api_v2_router() extraction, .nest("/api/v2", ...)
• services/agent-clients/src/control_plane/mod.rs — trailing-slash trim only in ControlPlaneClient::new()
• clients/lci/src/api.rs — trailing-slash trim only in ApiClient::new()
• services/control-plane/src/http/webhook.rs — test fix: gitlab_webhook_body called with correct installation_id (2001/2002 not 1001)
• docs/adr/0109-api-v2-route-versioning.md — new ADR

Out of Scope

• URL env var values — updated in companion chart PR ADORSYS-GIS/ai-helm#817
• apps/web controlPlaneUrl() — already uses the env var as-is; no change needed
• All wiremock mock paths — no change needed since clients no longer add a prefix at construction time

---

4. Verification

Commands run:

cargo fmt --all
cargo clippy -p control-plane -p lci -p lci-agent-clients -p agent-runner -p lci-review-agent -p lci-open-agent -p lci-review-mcp -p lci-agent-testkit --all-targets --locked -- -D warnings
cargo test -p lci -p lci-agent-clients
cargo test -p agent-runner --lib
cargo test -p lci-review-agent --lib
cargo test -p lci-open-agent --lib
DATABASE_URL=postgres://lightbridge:lightbridge@127.0.0.1:5432/lightbridge cargo test -p control-plane

Results:

clippy:                         0 errors, 0 warnings
lci + agent-clients:            120 passed; 0 failed
agent-runner:                   80 passed; 0 failed
review-agent:                   152 passed; 0 failed
open-agent:                     23 passed; 0 failed
control-plane (with DATABASE_URL): 367 passed; 0 failed

---

5. Risk Assessment

• Low
• Medium
• High

Hard cutover — old flat paths (e.g. GET /tasks) return 404 after deployment. The env vars must be updated in the same deploy window (see companion chart PR). Deploy order: server (#534) first, then chart (#817).

---

6. AI Usage Declaration

AI was used for:

• Understanding existing code
• Generating code
• Refactoring
• Reviewing the diff

Human verification:

• I understand every meaningful change in this PR
• I checked generated code manually
• I checked generated tests manually
• I removed unsupported AI assumptions
• I accept responsibility for this PR

---

7. Reviewer Focus

• Correctness
• Architecture
• Tests

Specific ask: confirm CONTROL_PLANE_INTERNAL_URL and AUTH_BACKEND_URL carrying /api/v2 in the chart (ADORSYS-GIS/ai-helm#817) is correct and covers all deployment paths.

Source of truth: #506, #492, ADR-0109

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2870332

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

✅ AI Governance check passed

This PR declares AI usage, references a source of truth, and provides verification evidence. Thank you.

[stephane-segning]

@lightbridge-assistant review

[lightbridge-assistant]

Lightbridge review

After re-verifying both "never sent/never set" P1s against upstream transport/config layers I had not opened (next.config.ts has no rewrites or env injection; graph search confirms controlPlaneUrl has exactly two definitions consumed by direct fetch with no interceptor; the server TaskContextResponse quoted directly shows preset/entry_point with no serde rename/alias), all three P1 findings hold, plus a confirmed cross-client env conflict: the web client only reaches /api/v2 if the operator puts it in the env value, while the Rust clients append it themselves — so no single CONTROL_PLANE_URL value satisfies both, and ADR-0109's "bare origin" prescription breaks the web app outright. (1) apps/web/lib/server/api.ts (+ mirror in admin.ts) omits /api/v2 when CONTROL_PLANE_URL/AUTH_BACKEND_URL is set — every prod web fetch 404s. (2) services/agent-clients/src/control_plane/mod.rs renames preset/entry_point→tier on the client only; the unchanged server still emits preset with no tier, so the client always defaults to deep, silently upgrading every fast auto-review. (3) services/control-plane/src/main.rs nested the back-compat /github/webhook route under /api/v2, so every registered GitHub/GitLab webhook URL now 404s — the "kept during the transition" comment is self-defeating. I also opened and reviewed services/agent-clients/src/control_plane/durable_step.rs: its only diff updates three wiremock path matchers to /api/v2/internal/..., consistent with the base_url baking in ControlPlaneClient::new; no findings. SAST ran clean and no new security surface was introduced; the construction-time prefix design is sound and just needs mirroring in the TS side and a matching server-side tier change.

Notes on changed files

Findings on this PR's changes that couldn't be pinned to a diff line.

• 

  Legacy webhook back-compat route nested under /api/v2 defeats it — services/control-plane/src/main.rs:320

  The /webhook and legacy /github/webhook routes were moved into api_v2_router(), which app() nests under /api/v2 (main.rs:431). So the legacy route now lives at /api/v2/github/webhook, meaning the existing GitHub App webhook configurations the comment claims to preserve — e.g. the smee proxy target http://localhost:8080/github/webhook documented in docs/local-setup.md (~line 107), and any prod GitHub/GitLab webhook URL registered to .../github/webhook or .../webhook — now 404. External platform webhooks are ingress points referenced by URL in forge settings; versioning them under a programmatic-API prefix breaks every registered webhook on upgrade and there is no back-compat. Either keep the webhook routes at the router root (outside the .nest("/api/v2", ...)), or if moving them is intentional, drop the "Kept during the transition so existing configurations don't break" comment and update the docs/webhook registration runbooks in this same PR.

  Evidence: .route("/github/webhook", ...) is declared inside api_v2_router() (main.rs:319-322) with the comment "Kept during the transition so existing webhook configurations don't break" (main.rs:317-318); app() nests that router under /api/v2 (main.rs:431). docs/local-setup.md smee target is http://localhost:8080/github/webhook.

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).

[stephane-segning]

@lightbridge-assistant review

[lightbridge-assistant]

Lightbridge review

Opened both previously-unreviewed files in full. durable_step.rs: three wiremock path matchers correctly updated to /api/v2/internal/..., self-consistent with the base_url baking; no findings. main.rs: faithful route split — healthz/readyz/metrics/webhooks stay at root, all other routes nest under /api/v2; auth extractors unaffected by nesting, no routes dropped, no new security surface; no findings. SAST ran clean. All three prior P1s remain retracted (web /api/v2 append is unconditional; no tier field exists; webhooks are at root). The one surviving P1 — cross-crate consumer tests (review-agent/src/tools/record.rs, review-agent/tests/golden_parity.rs, agent-runner/tests/sast_tool.rs, agent-runner/src/review/tool_surface.rs) mock unversioned wiremock paths and will 404-and-fail under cargo test --workspace — held up against a disconfirming pass: traced the exact path from ControlPlaneClient::new's prefix bake through review.rs:35's URL construction to wiremock's exact path matcher to the .error_for_status() failure to the assert_eq!(ToolOutcome::Continue(...)) assertion. Fix is mechanical — prepend /api/v2 to those consumer mock paths. Not deeply reviewed (low signal): Cargo.lock and docs/adr/0109-api-v2-route-versioning.md; the ADR's "bare origin" prescription is now consistent across all clients (Rust + TS each append /api/v2) and the server.

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).

[stephane-segning]

@lightbridge-assistant review

[lightbridge-assistant]

Lightbridge review

Re-verified all three findings by actively hunting for, not just re-citing, disconfirming evidence — none of it overturned the claims, so all stand. P0 (mod.rs:183): runner sends bare /internal/tasks/{id} while the server now serves it only under /api/v2 (verified app() has no root /internal alias; RunnerConfig::from_env and the dispatcher default both pass a bare origin with no upstream /api/v2 append) → every Job 404s on context fetch. P0 (api.rs:184): lci CLI default DEFAULT_API_URL is a bare origin and Config::resolve only trims a slash → every TUI endpoint 404s. P1 (main.rs:454): the three /webhook/{forge} routes are nested under /api/v2, so existing GitHub/GitLab/Bitbucket webhook registrations silently 404 until re-registered out-of-band — a cutover gap the ADR's "every consumer updated in the same change" framing doesn't reach, and one it explicitly avoided for health probes for the same reason. The wiremock suites (durable_step.rs/sast_tool.rs/golden_parity.rs) stay green precisely because they mock bare paths against a bare-base client — masking the prod break — and I confirmed the current durable_step mocks are bare (not /api/v2/...), so I did not inherit the prior "updated to /api/v2" claim. SAST clean; no new security surface. Fix: append /api/v2 in both constructors (and update the consumer mock paths), and move the /webhook/* routes back to the root router or document their external re-registration in the cutover, before merge.

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).

[leghadjeu-christian]

@lightbridge-assistant review
Addressing your findings:

P0 — ControlPlaneClient::new and ApiClient::new not appending /api/v2: This is intentional by design. Both clients trim trailing slashes only; the /api/v2 prefix is the caller's responsibility via the env var. The companion Helm PR ADORSYS-GIS/ai-helm#817 adds /api/v2 to CONTROL_PLANE_INTERNAL_URL and AUTH_BACKEND_URL in the chart defaults. Both clients are symmetric — the env var is the single place where the prefix is configured. ADR-0109 has been updated in bdaddbe to document this explicitly.

P1 — Webhook routes nested under /api/v2: This is intentional. The path-scoped webhook routes (/api/v2/webhook/github, /api/v2/webhook/gitlab/{id}, /api/v2/webhook/bitbucket/{id}) are the final paths after this PR and the already-merged PR #547. Forge webhook configurations (GitHub App, GitLab project settings) must be repointed as part of the deployment rollout — this is documented in ADR-0110 and the rollout checklist. The ai-helm-values PR ADORSYS-GIS/ai-helm-values#161 adds installationId: 84291 to the GitLab project config to set the path segment for the new URL.

[lightbridge-assistant]

Lightbridge review

Re-verified the single P1 finding by actively hunting for disconfirming evidence — a transport interceptor, reqwest middleware, or upstream URL-rewriting layer that would inject /api/v2 before the lci CLI's requests — and found none: the http client is a plain reqwest::Client::builder() with only .user_agent + .timeout (main.rs:72-79, no reqwest_middleware), and Axum's .nest() 404s unmatched root paths rather than redirecting. The finding stands: the lci CLI's compiled-in DEFAULT_API_URL is still a bare origin the diff doesn't touch, so a default-configured operator 404s against the versioned server; the one-line fix is to bump it to …/api/v2. The prior review's three findings (runner/CLI constructor trim-only, webhooks at /api/v2/webhook/*) remain retracted as intentional per ADR-0109/0110 and the Helm rollout. SAST clean; no new security surface.

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).

[lightbridge-assistant]

lci CLI compiled-in default URL stays bare → /me 404s against /api/v2 server

The server now nests every consumer-facing route under /api/v2 (this .nest line), but the lci CLI's compiled-in default DEFAULT_API_URL (clients/lci/src/config.rs:23) is still the bare origin "https://code-intelligence-api.ai.camer.digital" with no /api/v2, and Config::resolve (clients/lci/src/config.rs:122-126 — flags → CONTROL_PLANE_URL → file.api_url → DEFAULT_API_URL, trailing-slash trim only) never appends it. After the prod control plane deploys this PR, a default-configured operator (no CONTROL_PLANE_URL, no config.toml) running lci login hits GET /me ⇒ 404, and every subsequent TUI call too.

The maintainer's reply addresses the Helm-chart-managed env vars (CONTROL_PLANE_INTERNAL_URL for the runner, AUTH_BACKEND_URL for apps/web) — both live in the chart and so the companion Helm PR can stamp /api/v2 into them. The lci CLI has no chart handhold: it ships as a binary, and the only place its default is set is the source constant in config.rs:23, unchanged by this diff. ADR-0109 writes "lci CLI's api_url must include /api/v2" — but never names DEFAULT_API_URL or tells the release to bump it, so the rollout continues to ship a default that no longer works server-side. Fix: bump DEFAULT_API_URL to "https://code-intelligence-api.ai.camer.digital/api/v2" (one-line change, no client-constructor change needed) so default-configured CLI users keep working; the env-var/"the env var is the single source of truth" framing is preserved for anyone who overrides it. P1 not P0 — no data loss / security, but a guaranteed regression on a realistic input (an existing lci user upgrading to the new server without overriding CONTROL_PLANE_URL).

Evidence: services/control-plane/src/main.rs:454 .nest("/api/v2", api_v2_router()) (new contract requiring /api/v2); clients/lci/src/config.rs:23 DEFAULT_API_URL = "https://code-intelligence-api.ai.camer.digital" (unchanged, bare origin); clients/lci/src/config.rs:122-126 Config::resolve precedence defaults to DEFAULT_API_URL with only trailing-slash trim.

Was this useful? React 👍/👎 to give us feedback