feat: refactor all apis in new path (CM-1236)

[ulemons]

Summary

Introduces /v1/akrites as the new unified public API path, consolidating the endpoints currently spread across /v1/ossprey, /v1/packages, and /v1/stewardships. The old paths are kept intact for backward compatibility and marked with TODO[deprecate] comments to track removal once consumers migrate.

Changes

• backend/src/api/public/v1/akrites/index.ts — new router that re-uses the existing handlers without duplicating logic; ossprey endpoints are promoted to the akrites root (no /ossprey sub-prefix), packages and stewardships keep their sub-paths
• backend/src/api/public/v1/index.ts — mounts akritesRouter() at /akrites with oauth2 middleware; adds TODO[deprecate] above the old route group
• backend/src/api/public/v1/{ossprey,packages,stewardships}/index.ts — each marked TODO[deprecate]: superseded by /v1/akrites/...
• services/libs/data-access-layer/src/osspckgs/api.ts — OsspreyMetrics interface and getOsspreyMetrics function marked TODO[deprecate]: rename to AkritesMetrics / getAkritesMetrics once /v1/ossprey is removed

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Performance improvement
• Chore / dependency update
• Documentation

JIRA ticket

ticket

---

Note

Medium Risk
Breaking JSON shape on /metrics (totalPackages removed) hits both legacy and akrites via the same handler; stewardship URL/method differences between old and new paths can break clients during migration.

Overview
Introduces /v1/akrites as the unified OAuth2-protected public API for OSSPREY dashboard reads and stewardship writes, mounted alongside existing /ossprey, /packages, and /stewardships routes (marked TODO[deprecate]). The new router reuses existing handlers and adds OpenAPI for the full surface, including lazy-load GET /packages/advisories and GET /packages/history, plus stewardship routes under /stewardships/open, /:id/assign, /:id/escalate, and PATCH /:id/status (different paths/methods than the legacy stewardships router).

Package detail responses are expanded: computed health score/band, richer repo and stewardship fields, mappingLabel, and history set to null (full history on the new history endpoint). Shared purlFieldSchema / purlQuerySchema centralize PURL validation; assign-steward accepts an optional note stored in activity metadata.

Data-layer changes affect shared behavior: dashboard getOsspreyMetrics drops totalPackages and redefines criticalPackages as the count of is_critical packages (coverage math uses that total). Scatter data no longer requires has_critical_vulnerability and is capped at 2000 rows. listPackageHistory backs the new history API.

^{Reviewed by Cursor Bugbot for commit f85e45b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

⚠️ Not ready to approve

One of the new deprecation notes points to an incorrect replacement route (/v1/akrites/ossprey) even though the new router exposes those endpoints at the /v1/akrites root.

Pull request overview

Adds a consolidated OAuth2-protected public API surface under /v1/akrites, reusing existing handlers from the legacy /v1/ossprey, /v1/packages, and /v1/stewardships routers while keeping the legacy paths in place for backward compatibility.

Changes:

• Introduces akritesRouter() that mounts former ossprey endpoints at the akrites root and nests packages/stewardships under /akrites/packages and /akrites/stewardships.
• Mounts /v1/akrites in the public v1 router with OAuth2 middleware, and marks legacy route groups with TODO[deprecate] notes.
• Adds DAL-level TODO[deprecate] notes for future renames of ossprey metrics types/functions.

File summaries

File	Description
backend/src/api/public/v1/akrites/index.ts	New consolidated router wiring existing ossprey/packages/stewardships handlers under /v1/akrites.
backend/src/api/public/v1/index.ts	Mounts /akrites with OAuth2 and adds deprecation note for legacy route groups.
backend/src/api/public/v1/ossprey/index.ts	Adds deprecation note indicating ossprey router is superseded by akrites.
backend/src/api/public/v1/packages/index.ts	Adds deprecation note indicating packages router is superseded by akrites.
backend/src/api/public/v1/stewardships/index.ts	Adds deprecation note indicating stewardships router is superseded by akrites.
services/libs/data-access-layer/src/osspckgs/api.ts	Adds deprecation notes for future renames of ossprey metrics types/functions.

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

⚠️ Not ready to approve

The new Akrites OpenAPI spec contains verified contract inaccuracies (notably the assign-steward response shape) that should be corrected before approval.

Copilot's findings

• Files reviewed: 7/7 changed files
• Comments generated: 3

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

[Copilot]

⚠️ Not ready to approve

The new OpenAPI spec contains a couple of contract mismatches and the new package-history DAL query should use deterministic ordering to avoid unstable results.

Copilot's findings

• Files reviewed: 13/13 changed files
• Comments generated: 3

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0a42480. Configure here.}

[Copilot]

⚠️ Not ready to approve

The Akrites OpenAPI spec and routing/limiting behavior currently diverge from the actual implementation (including rate-limit bucket separation and metrics/schema mismatches), and there’s an unresolved backward-compatibility break in the legacy metrics shape.

Copilot's findings

Comments suppressed due to low confidence (1)

services/libs/data-access-layer/src/osspckgs/api.ts:106

• getOsspreyMetrics should populate the (deprecated) totalPackages field if we keep it for legacy compatibility; otherwise the interface+implementation will diverge.

  const total = parseInt(counts.criticalPackages, 10)
  const covered = parseInt(counts.covered, 10)

  return {
    criticalPackages: total,
    coveragePercent: total > 0 ? Math.round((covered / total) * 1000) / 10 : 0,
    coverageTrend: null, // TODO: requires snapshot mechanism or stewardship_activity timestamp analysis
    activeStewards: parseInt(stewardRow.count, 10),
    unassignedCritical: parseInt(counts.unassignedCritical, 10),
    needsAttention: parseInt(counts.needsAttention, 10),
    escalated: parseInt(counts.escalated, 10),
  }

• Files reviewed: 14/14 changed files
• Comments generated: 8

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.