suaveplan/openspec/archive/2026-05-18-enterprise-api/tasks.md

Tasks — enterprise-api

1. Scaffold

• 1.1 Create packages/api/api/ with src/{app,builder,config,middleware,error-codes,types,event-integration}/ + tests/setup/ + tests/integration/
• 1.2 package.json v0.1.0. Deps: @suaveplan/error @suaveplan/api-plugin @suaveplan/api-tenant @suaveplan/api-openapi @suaveplan/api-migrations @suaveplan/events @suaveplan/types @suaveplan/utils tslib, hono @hono/zod-openapi @hono/swagger-ui (catalog:server), zod (catalog:forms), @opentelemetry/api. Dev: standard testing + @suaveplan/testing-integration-sqlite for the full-boot test.
• 1.3 ~10 subpath exports (one per feature module + root)
• 1.4 tsconfigs + vite + vitest (100/100/100/100, testTimeout 60000 for integration)
• 1.5 tests/setup/polyfills.ts

2. Implementation

• 2.1 src/error-codes.ts + .md + test — 5 API.* codes + ApiError
• 2.2 src/types/api.{ts,md,index.ts} — AppState, SuaveAppOptions, HealthRoutesOptions, RequestContext
• 2.3 src/config/config.{ts,test.ts,md,index.ts} — AppConfigSchema + sub-configs (server/database/cors/logging/openapi/plugins/migrations)
• 2.4 src/config/loader.{ts,test.ts,md} — ConfigLoader, multi-source merge, env-var parsing
• 2.5 src/config/validator.{ts,test.ts,md} — validateConfig, tryValidateConfig, validatePluginConfig, typed getter
• 2.6 src/middleware/chain.{ts,test.ts,md,index.ts} — MiddlewareChain + MiddlewareOrder constants + insert raises on missing target
• 2.7 src/middleware/cors.{ts,test.ts,md} — createCors with conditional rate-limit headers
• 2.8 src/middleware/logger.{ts,test.ts,md} — createLogger + formatters (default/json/detailed)
• 2.9 src/middleware/error-handler.{ts,test.ts,md} — createErrorHandler + createNotFoundHandler; full statusCode passthrough
• 2.10 src/middleware/request-id.{ts,test.ts,md} — createRequestId + 3 generator alternatives
• 2.11 src/middleware/composition.{ts,test.ts,md} — combineMiddleware, conditionalMiddleware, pathMiddleware, excludePathMiddleware
• 2.12 src/event-integration/event-bridge.{ts,test.ts,md,index.ts} — wires the @suaveplan/events typed EventBus into SuaveApp.events
• 2.13 src/app/app.{ts,test.ts,md,index.ts} — SuaveApp class, FSM, initialize/start/stop, optional ALS via RequestContext, configurable health routes
• 2.14 src/app/health-routes.{ts,test.ts,md} — configurable health route registration
• 2.15 src/app/request-context.{ts,test.ts,md} — single optional requestStorage ALS + getCurrentRequestContext
• 2.16 src/builder/builder.{ts,test.ts,md,index.ts} — AppBuilder, defineApp(), quickstart(); .tenant(resolver) actually wires middleware
• 2.17 src/index.ts — named re-exports (no global singletons)

3. Tests

• 3.1 Co-located *.test.ts per spec scenario
• 3.2 src/api.spec-conformance.test.ts — every API.* thrown; no global singleton exports; expectTypeOf on SuaveAppOptions
• 3.3 tests/integration/full-boot.test.ts — real PluginRegistry + 3 plugins (with deps) + real OpenAPIRegistry + real TenantResolver + real MigrationRunner against @sqlite.org/sqlite-wasm. Assert: state transitions, doc emission, tenant middleware wiring, migration ran before init.
• 3.4 tests/integration/builder-roundtrip.test.ts — defineApp().name().tenant(resolver).use(plugin).start() → assert tenant middleware in chain
• 3.5 tests/integration/config-precedence.test.ts — write fixture file + set env vars → assert load order
• 3.6 tests/property.test.ts — fast-check MiddlewareChain insertBefore/After invariant: insertion produces consistent ordering
• 3.7 tests/dep-graph.test.ts
• 3.8 Runner imports + timeouts

4. Documentation

• 4.1 Sibling .md per impl (≥200 words)
• 4.2 README.md — quickstart, AppBuilder fluent example, plugin wiring example, config file format, migration runner integration, ALS opt-in pattern

5. Gates (dependent sweep mandatory — this is the orchestrator)

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/api --force
• 5.2 Coverage 100/100/100/100
• 5.3 bun scripts/openspec-conformance.ts @suaveplan/api exit 0
• 5.4 Build green
• 5.5 bunx turbo test --filter=...@suaveplan/api --force — dependent sweep (the 40+ api-plugin-* packages, when they exist)
• 5.6 Banned-pattern + no export * + no direct runner imports

6. Archive

• 6.1 Fold spec → openspec/specs/api/spec.md
• 6.2 mv → archive
• 6.3 MANIFEST + STATUS refresh — flip @suaveplan/api to ✅