61 lines
4.6 KiB
Markdown
61 lines
4.6 KiB
Markdown
# 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 ✅
|