feat: Wave API v1 consolidation (/w1/* via TypeSpec)

[pditommaso]

Consolidates Wave's REST API into a stable v1 surface under the /w1/* prefix, with TypeSpec as the source of truth. New wave-api-v1 Gradle module hosts the TypeSpec spec; Micronaut OpenAPI plugin generates Java server interfaces and DTOs. All existing service-layer logic is reused unchanged; existing /v1alpha* and unversioned endpoints stay functional and carry Deprecation: true + Sunset headers.

What changed

• New module wave-api-v1 — TypeSpec source under wave-api-v1/spec/, generated OpenAPI YAML, and 7 server interfaces + 40+ generated DTOs committed under src/main/java/
• 7 v1 controllers (ServiceInfo, Credentials, Inspections, Builds, Mirrors, Scans, Containers) implementing the generated interfaces, delegating to existing services via thin mappers
• ContainerRequestHandler extracted from the 765-line ContainerController so both alpha and v1 controllers share the same logic (refactor only — zero behaviour change, all 42 existing tests still pass)
• AlphaDeprecationFilter stamps Deprecation: true + Sunset: Sat, 31 May 2027 23:59:59 GMT on responses from /v1alpha*, /container-token, /service-info, /validate-creds, /inspect, /scans
• One v1-new endpoint: POST /w1/scans for resource-shape symmetry (no alpha equivalent — scans previously only flowed through container provisioning)
• Docs: design spec (docs/superpowers/specs/2026-05-20-wave-api-v1-design.md), implementation plan (docs/superpowers/plans/2026-05-20-wave-api-v1.md), README + docs/api.md updated

v1 URL surface

Resource	Method	Path
Containers	POST / GET / DELETE	/w1/containers, /w1/containers/{id}, /w1/containers/{id}/status
Builds	GET	/w1/builds/{id}, /w1/builds/{id}/status, /w1/builds/{id}/logs, /w1/builds/{id}/condalock
Mirrors	GET	/w1/mirrors/{id}, /w1/mirrors/{id}/logs
Scans	POST / GET	/w1/scans, /w1/scans/{id}, /w1/scans/{id}/logs, /w1/scans/{id}/spdx
Inspections	POST	/w1/inspections
Credentials	POST	/w1/credentials/validate
Service info	GET	/w1/service-info

Test plan

Verified locally:

• ./gradlew clean :wave-api-v1:generateOpenApi :generateApiCode assemble — BUILD SUCCESSFUL
• 47 v1 tests pass (10 specs covering controllers, mappers, filter, parity, serialization)
• 73 existing alpha controller tests pass — zero regression
• Bundled openapi.yaml served at /openapi/openapi.yaml exposes 16 /w1/* paths; Swagger UI at /openapi/index.html

Reviewer checklist:

• Confirm /w1 URL prefix is acceptable (no Docker Registry collision concern)
• Confirm Sat, 31 May 2027 sunset date placeholder
• Field-shape divergences flagged during implementation:
  • WaveBuildRecord v1 missing 4 fields vs internal (compression, buildTemplate, buildChildIds, scanChildIds)
  • ContainerMirrorResponse v1 missing 5 fields vs internal (offsetId, userName, userEmail, userId, scanId)
  • These were left as-is and need a follow-up PR to extend the TypeSpec models if full alpha parity is required
• POST /w1/scans returns PENDING but the underlying scan job currently fails (workDir null at v1 layer) — needs follow-up to either require buildId/mirrorId or configure a standalone scan workspace before GA

Out of scope

• /v1alpha*/metrics/* (kept on alpha)
• Registry proxy /v2/* (Docker Registry protocol)
• Error envelope redesign (RFC 7807), pagination, status-enum cleanup — deferred to v1.x or v2

Generated with Claude Code