SpecsCLIIP-97-effect-api-contract-boundary
Implementation Notes: IP-97 Shared Effect API Contract Boundary
Implementation Notes: IP-97 Shared Effect API Contract Boundary
Summary
Implemented the first Harness control-plane contract boundary across packages/contract, apps/api, and apps/cli.
Changes
packages/contractnow owns:HarnessApiEffect HttpApi definition.- baseline/channel and artifact metadata schemas.
- typed API errors for unauthorized, forbidden, baseline-not-found, and unavailable control-plane states.
- bearer-token security middleware declarations.
makeHarnessClient, the shared typed client factory.
apps/apinow implements the contract with EffectHttpApiBuildergroups and a Bun-compatible web handler.apps/clinow has an optional typed control-plane baseline metadata source gated byDP_CONTROL_PLANE_URLandDP_CONTROL_PLANE_TOKEN.- Existing CLI stable GitHub release lookup and bundled fallback behavior remains intact.
- Docs now describe the contract boundary and additive control-plane baseline path.
Validation Evidence
bun run check-types --filter=@punks/contractbun run test --filter=@punks/contractbun run check-types --filter=@punks/apibun run test --filter=@punks/apibun run build --filter=@punks/apibun run check-types --filter=@punks/clibun run test --filter=@punks/cli -- --run src/baseline/resolve.test.tsbun run checkbun run check-typesbun run testbun run buildgit diff --check
Manual Review Checklist
| Check | Result | Evidence |
|---|---|---|
| Typed client fallback preserved | Pass | Control-plane baseline metadata path is additive and existing GitHub/bundled fallback remains. |
| API contract surface implemented | Pass | packages/contract exports HarnessApi; apps/api implements it with Effect handlers. |
| Docs accuracy | Pass | docs/README.md and docs/runbooks/dp-cli-scaffolding.md describe the new boundary. |
| No raw control-plane HTTP | Pass | New CLI metadata calls use makeHarnessClient; raw fetch remains only for existing artifact/GitHub paths. |
Review Notes
- Hono was removed from the API implementation boundary for IP-97. The backend direction is now explicitly Effect HTTP router/layer.
- Backend artifact storage remains deferred; the API returns typed unavailable errors until a storage story configures real artifact metadata.
- Raw HTTP remains only for direct artifact downloads and existing GitHub fallback compatibility, not for new control-plane metadata calls.
- Review found and fixed a fallback regression where control-plane failures could skip GitHub stable lookup and jump directly to bundled fallback.