feat(api,frontend): add GET /api/recommendations/:id/detail + drawer wiring (closes #44)

[cristim]

Summary

Closes #44.

Adds GET /api/recommendations/:id/detail and wires it into the
Recommendations row-click drawer. The drawer previously rendered only
the columns from the listing payload + a client-side confidence
heuristic + a freshness-derived provenance line. After this change:

• Backend computes the confidence bucket (1:1 with the previous
  client-side thresholds, moved server-side so future provider tuning
  doesn't need a frontend deploy) and assembles a provenance note
  naming the collector + last-collected timestamp.
• Frontend fetches the per-id detail on first expand, memoises it
  per-id for the session, renders the server-supplied confidence
  badge + provenance, and renders an inline SVG sparkline of
  usage_history (two polylines, CPU + memory, no chart library).
• Empty usage_history renders a one-line "Usage history not yet
  available" placeholder rather than a broken empty chart — the
  documented default until the collector starts persisting
  time-series usage per recommendation (known_issues/28).

Decision: empty usage_history vs collector pipeline

usage_history is intentionally [] in this first pass. The
collector pipeline does not yet persist time-series utilisation per
recommendation, and standing up that pipeline is explicitly out of
scope per the issue. Surfacing the missing field as an empty slice
(rather than a 501 or omitting the field) keeps the drawer functional
today and means the day the collector starts populating it, the
frontend automatically picks it up — no follow-up frontend deploy
needed.

Security notes

• Auth/permission gate runs before id validation so an
  unauthenticated caller can't probe id-shape errors to learn the
  endpoint exists.
• Account-allow filter runs before the in-memory id lookup, so an
  id that exists but belongs to an account the caller can't see
  returns 404 (existence-disclosure-safe path matching
  handler_accounts.go's account lookup).
• Frontend encodeURIComponents the id in the URL.
• No innerHTML; the drawer uses replaceChildren + createElement /
  createElementNS for the sparkline.

Files changed

• internal/api/types.go — RecommendationDetailResponse, UsagePoint
• internal/api/handler_recommendations.go — new handler + helpers
  (confidenceBucketFor, provenanceNoteFor, providerDisplayName)
• internal/api/router.go — /api/recommendations/{id}/detail route
• internal/api/handler_recommendations_test.go — 4xx (empty id
  post-auth, unknown id) + 200 happy + degraded provenance + table
  test for the bucket thresholds
• frontend/src/api/recommendations.ts — getRecommendationDetail
  • types
• frontend/src/recommendations.ts — drawer fetch wiring + cache +
  inline SVG sparkline; removes the now-superseded client-side
  confidenceBucketFor shim
• frontend/src/__tests__/recommendations.test.ts — drawer fetches
  once per id, renders backend confidence + provenance, sparkline
  on non-empty usage_history, placeholder on empty, cache reuse on
  re-open

Test plan

• go test ./internal/api/... — full backend api suite green
• npx jest — full 1255-test frontend suite green
• npx tsc --noEmit — type-clean
• npm run build — webpack production build succeeds
• Post-merge: navigate the deployed dashboard, expand a
  recommendation row, confirm the new badge/provenance/usage
  placeholder render and that DevTools shows a single
  /api/recommendations/<id>/detail call per first-open

Summary by CodeRabbit

• New Features

  • Recommendation details now display server-provided confidence levels and provenance information.
  • Added visual usage history with CPU and memory sparklines when historical data is available.
  • Improved loading states and error handling in the details drawer.

• Tests

  • Added comprehensive test coverage for recommendation details endpoint and drawer functionality.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new /api/recommendations/{id}/detail endpoint is introduced to serve per-recommendation usage history, confidence bucket, and provenance information. The backend handler validates the recommendation id, filters results by account visibility, computes confidence buckets from savings/count thresholds, and derives provenance notes from freshness timestamps. The frontend calls this endpoint on drawer open, memoizes results per id, and conditionally renders sparklines when usage history data is available.

Changes

Cohort / File(s)	Summary
Backend Type Definitions internal/api/types.go	Adds UsagePoint and RecommendationDetailResponse types with timestamp, CPU/memory percentages, confidence bucket, and provenance note fields.
Backend Route Registration internal/api/router.go	Registers new GET /api/recommendations/{id}/detail route with parameter extraction and dispatch to handler.
Backend Detail Handler internal/api/handler_recommendations.go	Implements getRecommendationDetail handler that validates id, filters cached recommendations by account visibility, computes confidence bucket from savings/count thresholds, and derives RFC3339-formatted provenance note from freshness timestamp.
Backend Handler Tests internal/api/handler_recommendations_test.go	Adds unit tests for id validation (400 errors), not-found behavior (404), successful detail response shape, and table-driven tests for confidenceBucketFor logic across savings/count combinations.
Frontend API Layer frontend/src/api/recommendations.ts	Defines RecommendationUsagePoint and RecommendationDetail TypeScript types and exports getRecommendationDetail(id) function to fetch the detail endpoint with path encoding.
Frontend Drawer Implementation frontend/src/recommendations.ts	Replaces client-side confidence heuristic with server-provided confidence_bucket, fetches usage history from new endpoint with memoization per id, renders inline CPU/memory sparkline when history is non-empty, shows "Usage history not yet available." placeholder when empty, and exports clearRecommendationDetailCache() for test isolation.
Frontend Drawer Tests frontend/src/__tests__/recommendations.test.ts	Adds drawer-focused test block mocking getRecommendationDetail, validates single fetch-per-id caching across close/reopen cycles, asserts confidence/provenance rendering, verifies "Usage history not yet available." placeholder for empty history, and confirms inline SVG sparkline with two paths when history is present.

Sequence Diagram

sequenceDiagram
    actor User
    participant Frontend as Frontend<br/>(recommendations.ts)
    participant API as API Client<br/>(api/recommendations.ts)
    participant Handler as Backend Handler<br/>(handler_recommendations.go)
    participant Cache as Recommendation<br/>Cache & Freshness

    User->>Frontend: Click recommendation row to expand drawer
    Frontend->>Frontend: Check memoization cache
    alt Cache miss
        Frontend->>API: getRecommendationDetail(id)
        API->>Handler: GET /api/recommendations/{id}/detail
        Handler->>Cache: ListRecommendations()
        Cache-->>Handler: [recommendations with savings/count]
        Handler->>Handler: Filter by account visibility
        Handler->>Handler: Match recommendation by id
        Handler->>Cache: GetRecommendationsFreshness()
        Cache-->>Handler: freshness timestamp
        Handler->>Handler: Compute confidence_bucket from savings/count
        Handler->>Handler: Format provenance_note from freshness
        Handler-->>API: RecommendationDetailResponse{<br/>  id, usage_history[],<br/>  confidence_bucket,<br/>  provenance_note<br/>}
        API-->>Frontend: Typed RecommendationDetail object
        Frontend->>Frontend: Store in memoization cache
    else Cache hit
        Frontend->>Frontend: Use cached detail
    end
    Frontend->>Frontend: Render confidence badge from detail.confidence_bucket
    Frontend->>Frontend: Render provenance_note text
    alt usage_history is non-empty
        Frontend->>Frontend: Render CPU/memory sparkline (inline SVG)
    else usage_history is empty
        Frontend->>Frontend: Render "Usage history not yet available." placeholder
    end
    Frontend-->>User: Display populated drawer

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A sparkle of confidence in every row,
Bunny hops through detail endpoints below,
Histograms dancing, provenance clear,
No more guessing — the whole truth is here!
✨ Cache it, memoize it, draw with care!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(api,frontend): add GET /api/recommendations/:id/detail + drawer wiring' clearly and concisely describes the main changes (new endpoint and frontend integration), matching the primary objective in the PR.
Linked Issues check	✅ Passed	All objectives from issue #44 are met: endpoint returns id/usage_history/confidence_bucket/provenance_note [#44], confidence computed server-side [#44], usage history rendered in drawer [#44], memoization implemented [#44], and frontend integration complete [#44].
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #44 requirements: backend endpoint and types, frontend drawer wiring, and supporting tests. No out-of-scope additions like cross-recommendation UI or provider tuning are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/recommendations-detail-endpoint

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

frontend/src/__tests__/recommendations.test.ts (1)

509-510: Consider a flushPromises utility for more robust async waiting.

The double await Promise.resolve() pattern works but can become fragile if the implementation adds additional async layers. A utility like const flushPromises = () => new Promise(r => setTimeout(r, 0)) or @testing-library/react's waitFor would be more resilient to implementation changes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@frontend/src/__tests__/recommendations.test.ts` around lines 509 - 510,
Replace the fragile double `await Promise.resolve()` pattern with a resilient
async flush helper: add a `const flushPromises = () => new Promise(r =>
setTimeout(r, 0))` (or import `waitFor` from `@testing-library/react`) and
replace the two `await Promise.resolve()` calls with a single `await
flushPromises()` (or `await waitFor(() => {/* assertion-ready check */})`);
update the test in `recommendations.test.ts` to use `flushPromises` (or
`waitFor`) so it properly waits for queued micro/macro tasks before assertions.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@frontend/src/__tests__/recommendations.test.ts`:
- Around line 509-510: Replace the fragile double `await Promise.resolve()`
pattern with a resilient async flush helper: add a `const flushPromises = () =>
new Promise(r => setTimeout(r, 0))` (or import `waitFor` from
`@testing-library/react`) and replace the two `await Promise.resolve()` calls
with a single `await flushPromises()` (or `await waitFor(() => {/*
assertion-ready check */})`); update the test in `recommendations.test.ts` to
use `flushPromises` (or `waitFor`) so it properly waits for queued micro/macro
tasks before assertions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3cc808ea-27ef-4486-902d-db58901fa099

📥 Commits

Reviewing files that changed from the base of the PR and between 006b9d3 and 2ff8392.

📒 Files selected for processing (7)

• frontend/src/__tests__/recommendations.test.ts
• frontend/src/api/recommendations.ts
• frontend/src/recommendations.ts
• internal/api/handler_recommendations.go
• internal/api/handler_recommendations_test.go
• internal/api/router.go
• internal/api/types.go