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

Tasks — add-api-openapi

1. Scaffold

• 1.1 Create packages/api/api-openapi/ with src/{registry,route-factory,schema-registry,merger,plugin-integration,error-codes,types}/ + tests/setup/
• 1.2 package.json v0.1.0. Deps: @suaveplan/error @suaveplan/api-plugin @suaveplan/api-schemas @suaveplan/types tslib, hono @hono/zod-openapi (catalog:server), zod (catalog:forms), @opentelemetry/api. Dev: standard testing. ~8 subpath exports.
• 1.3 tsconfigs + vite + vitest (100/100/100/100) + polyfills

2. Implementation

• 2.1 src/error-codes.ts + .md + test — 3 OPENAPI.* codes + OpenAPIError
• 2.2 src/types/openapi.{ts,md,index.ts} — OpenAPIDocument, PathItem, Operation, OpenAPIInfo, OpenAPIServer, SecurityScheme, RegisteredRoute
• 2.3 src/registry/registry.{ts,test.ts,md,index.ts} — OpenAPIRegistry + buildDocument() + applyTo(app)
• 2.4 src/route-factory/route-factory.{ts,test.ts,md,index.ts} — RouteBuilder<TParams,TQuery,TBody,TResponse> + route/GET/POST/PUT/PATCH/DELETE + StandardResponses (widened) + ErrorResponseSchema (+ successResponse/paginatedResponse/errorResponse)
• 2.5 src/route-factory/route-factory.spec-conformance.test.ts — expectTypeOf end-to-end inference
• 2.6 src/schema-registry/schema-registry.{ts,test.ts,md,index.ts} — instance-based, no global; extend/partial/pick/omit on ZodObject
• 2.7 src/schema-registry/common-schemas.{ts,md} — CommonSchemas (uuid/email/url/datetime/positiveInt/nonNegativeInt/page/limit/sortOrder)
• 2.8 src/merger/merger.{ts,test.ts,md,index.ts} — mergeOpenAPIDocuments, prefixPaths, filterPathsByTag, removeInternalRoutes
• 2.9 src/plugin-integration/plugin-integration.{ts,test.ts,md,index.ts} — definePluginRoutes(routes, {app, registry, pluginName})
• 2.10 src/index.ts — named re-exports (incl. BearerAuthScheme, ApiKeyScheme)

3. Tests

• 3.1 Co-located *.test.ts per spec scenario
• 3.2 src/api-openapi.spec-conformance.test.ts — every OPENAPI.* thrown; no global singleton; expectTypeOf on RouteBuilder end-to-end
• 3.3 tests/integration/full-doc-roundtrip.test.ts — real OpenAPIHono + real registry + 3 plugins registering routes → assert merged doc shape
• 3.4 tests/property.test.ts — fast-check mergeOpenAPIDocuments associativity (merge(a, b, c) === merge(merge(a, b), c)) for arbitrary path sets
• 3.5 tests/dep-graph.test.ts
• 3.6 Runner imports + timeouts conventions

4. Documentation

• 4.1 Sibling .md per impl
• 4.2 README.md — RouteBuilder examples (basic + with auth + paginated), SchemaRegistry derivation patterns, mergeOpenAPIDocuments use cases, definePluginRoutes plugin pattern

5. Gates

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/api-openapi --force
• 5.2 Coverage 100/100/100/100
• 5.3 bun scripts/openspec-conformance.ts @suaveplan/api-openapi exit 0
• 5.4 Build green
• 5.5 Banned-pattern + no export * + no direct runner imports

6. Archive

• 6.1 Fold spec → openspec/specs/api-openapi/spec.md
• 6.2 mv change → archive
• 6.3 MANIFEST + STATUS refresh