ts-procedures 8.6.0 → 9.0.0

package/docs/superpowers/specs/2026-05-08-hono-app-builder-convergence-design.md

@@ -1,411 +0,0 @@
-# HonoAppBuilder Convergence — Design
-
-**Date:** 2026-05-08
-**Status:** Draft for review
-**Scope:** Hono only
-
-## Problem
-
-`ts-procedures` currently exposes three Hono builders — `HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder` — totaling ~1,580 lines of near-parallel code (constructor, `register()`, `build()`, error dispatch, factory iteration, doc emission). Each filters procedures by `kind` and warn-skips mismatches.
-
-Since v8, a single `Procedures<TContext>()` factory produces all four procedure kinds (`rpc`, `rpc-stream`, `http`, `http-stream`) from one call. Splitting registration across three builders is no longer a structural necessity — it's friction. A user wiring a typical app today does:
-
-```ts
-const rpc    = new HonoRPCAppBuilder({ app, errors }).register(F1, ctx1)
-const api    = new HonoAPIAppBuilder({ app, errors }).register(F2, ctx2)
-const stream = new HonoStreamAppBuilder({ app, errors, onMidStreamError }).register(F3, ctx3)
-rpc.build(); api.build(); stream.build()
-new DocRegistry().from(rpc).from(api).from(stream).toJSON()
-```
-
-…three constructors, three `errors` config objects, three `build()` calls, an explicit shared `app`, and a DocRegistry assembly step — to do what is conceptually one thing: "mount these procedures on this Hono server."
-
-## Goal
-
-A single `HonoAppBuilder` that accepts any `Procedures<>()` factory and mounts every procedure kind correctly, with the appropriate documentation surfaced for the codegen pipeline. The current four-builder surface is removed.
-
-## Non-Goals
-
-- **Removing or rewriting `DocRegistry`.** It remains the multi-app aggregation primitive.
-- **Changing per-procedure config.** `RPCConfig`, `APIConfig`, the `CreateHttp`/`CreateStream`/`CreateHttpStream` shapes are unchanged. The convergence is at the *builder* layer, not the procedure-definition layer.
-- **Path generation rule changes.** RPC/rpc-stream still use `pathPrefix + kebab(scope)/kebab(name)/version`. HTTP/http-stream still use `pathPrefix + config.path`.
-- **Error taxonomy semantics.** `defineErrorTaxonomy`, `resolveErrorResponse`, mid-stream error wire shape, and the `onRequestError` observer all keep their current behavior.
-
-## Decisions
-
-| Decision | Choice | Rationale |
-|---|---|---|
-| Convergence scope | Full collapse, remove old builders, no deprecation period | v8 has not been published; v8 is already a breaking release from v7. Bundling this convergence with the v8 break avoids a second migration. |
-| Config shape for kind-specific knobs | Stratified — top-level cross-cutting + nested `rpc`/`api`/`stream` blocks | Type-safe, discoverable; users who only register one kind don't see clutter from other kinds. |
-| Documentation | Builder gains `toDocEnvelope()` for single-app; `DocRegistry` stays for multi-app aggregation | Common case is one builder per app — `toDocEnvelope()` removes the registry boilerplate. Multi-app users keep the existing primitive. |
-| Builder name | `HonoAppBuilder` | Drops the kind suffix (RPC/API/Stream) since it now serves all kinds. |
-| Non-streaming hooks (`onSuccess`) placement | Inside stratified blocks (`rpc.onSuccess`, `api.onSuccess`) | Strict typing per kind; users wiring a unified metrics callback assign the same function to both blocks. Non-breaking to add a top-level `onSuccess` later if duplication is a real pain point. |
-| Shared error-dispatch module location | `src/implementations/http/error-dispatch.ts` (one level up from `hono/`) | Lives outside the framework-specific subdir so it can be reused by future framework adapters. |
-| Path-builder static method | `HonoAppBuilder.makeRoutePath({ procedure, prefix })` — handles all four kinds | Tooling consumers get one entry point regardless of kind. |
-
-## Public API
-
-```ts
-import { HonoAppBuilder } from 'ts-procedures/hono'
-
-const { Create, CreateStream, CreateHttp, CreateHttpStream } =
-  Procedures<AppCtx>()
-
-// ... define procedures with any combination of the four creators ...
-
-const builder = new HonoAppBuilder({
-  app,                             // optional pre-existing Hono
-  pathPrefix: '/api/v1',
-  errors: appErrors,               // ErrorTaxonomy, cross-cutting
-  unknownError,
-  onError,                         // imperative peer of `errors`
-  onRequestError,                  // observer
-  onRequestStart,
-  onRequestEnd,
-  rpc: {
-    onSuccess: (proc, c) => {},
-  },
-  api: {
-    queryParser: qs.parse,
-    onSuccess: (proc, c) => {},
-  },
-  stream: {
-    defaultStreamMode: 'sse',      // applies to rpc-stream + http-stream
-    onStreamStart, onStreamEnd,
-    onMidStreamError,
-  },
-})
-
-builder
-  .register(AppFactory, ctxResolver)
-  .register(InternalFactory, internalCtxResolver, {
-    streamMode: 'text',                  // optional per-factory override
-    extendProcedureDoc: ({ base }) => {
-      switch (base.kind) {
-        case 'rpc':         return { internal: true }
-        case 'api':         return { internal: true, group: 'admin' }
-        case 'stream':      return { internal: true }
-        case 'http-stream': return { internal: true }
-      }
-    },
-  })
-
-const honoApp = builder.build()             // returns Hono
-const docs = builder.docs                   // AnyHttpRouteDoc[] (lazy-cached)
-const envelope = builder.toDocEnvelope()    // DocEnvelope (single-app)
-```
-
-### Config Type
-
-```ts
-export type HonoAppBuilderConfig<TStreamErrorData = unknown> = {
-  // Cross-cutting
-  app?: Hono
-  pathPrefix?: string
-
-  errors?: ErrorTaxonomy
-  unknownError?: UnknownErrorConfig
-  onError?: (
-    procedure: AnyProcedureRegistration,
-    c: Context,
-    error: Error,
-  ) => Response | Promise<Response>
-  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
-
-  onRequestStart?: (c: Context) => void
-  onRequestEnd?: (c: Context) => void
-
-  // Kind-specific
-  rpc?: {
-    onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  }
-  api?: {
-    queryParser?: QueryParser
-    onSuccess?: (
-      procedure: THttpProcedureRegistration<any>,
-      c: Context,
-    ) => void
-  }
-  stream?: {
-    defaultStreamMode?: StreamMode
-    onStreamStart?: (
-      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
-      c: Context,
-      streamMode: StreamMode,
-    ) => void
-    onStreamEnd?: (
-      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
-      c: Context,
-      streamMode: StreamMode,
-    ) => void
-    onMidStreamError?: (
-      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
-      c: Context,
-      error: Error,
-    ) => MidStreamErrorResult<TStreamErrorData> | undefined
-  }
-}
-
-export type AnyProcedureRegistration =
-  | TProcedureRegistration
-  | TStreamProcedureRegistration
-  | THttpProcedureRegistration<any>
-  | THttpStreamProcedureRegistration<any>
-
-export type OnRequestErrorContext = {
-  err: unknown
-  procedure: AnyProcedureRegistration
-  raw: Context
-}
-```
-
-### `register()`
-
-```ts
-register<TFactory extends ProceduresFactory>(
-  factory: TFactory,
-  factoryContext:
-    | ExtractContext<TFactory>
-    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
-  options?: {
-    /** Per-factory override for stream.defaultStreamMode. */
-    streamMode?: StreamMode
-    /** Extend route docs. base is a kind-discriminated union. */
-    extendProcedureDoc?: (params: {
-      base: RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc | HttpStreamRouteDoc
-      procedure: AnyProcedureRegistration
-    }) => Record<string, unknown>
-  },
-): this
-```
-
-### `toDocEnvelope()`
-
-Mirrors `DocRegistry.toJSON()`'s option surface so the produced envelope is identical and the codegen pipeline reads either interchangeably:
-
-```ts
-toDocEnvelope(options?: {
-  basePath?: string
-  errors?: ErrorTaxonomy | ErrorDoc[]
-  includeDefaults?: boolean
-  filter?: (route: AnyHttpRouteDoc) => boolean
-  transform?: (route: AnyHttpRouteDoc) => AnyHttpRouteDoc
-}): DocEnvelope
-```
-
-`builder.docs` exposes the underlying array (lazy-computed on first read or on `build()`, whichever happens first; cached thereafter).
-
-### Static Path Builder
-
-```ts
-HonoAppBuilder.makeRoutePath({
-  procedure: AnyProcedureRegistration,
-  prefix?: string,
-}): string
-```
-
-- For `rpc` / `rpc-stream`: `{prefix}/{kebab(scope)}/{kebab(name)}/{version}`
-- For `http` / `http-stream`: `{prefix}{config.path}` (prefix normalized to leading `/`)
-
-## Internal Architecture
-
-```
-src/implementations/http/
-├── error-dispatch.ts                   # SHARED — pre-stream + mid-stream dispatchers
-├── error-taxonomy.ts                   # unchanged
-├── doc-registry.ts                     # unchanged
-├── hono/
-│   ├── index.ts                        # HonoAppBuilder (~200 lines)
-│   ├── path.ts                         # makeRoutePath, resolveFullPath
-│   ├── types.ts                        # HonoAppBuilderConfig, factory item
-│   ├── handlers/
-│   │   ├── rpc.ts                      # installRpcRoute(...)
-│   │   ├── http.ts                     # installHttpRoute(...)
-│   │   ├── stream.ts                   # installRpcStreamRoute(...)
-│   │   └── http-stream.ts              # installHttpStreamRoute(...)
-│   └── docs/
-│       ├── rpc-doc.ts                  # buildRpcRouteDoc
-│       ├── http-doc.ts                 # buildHttpRouteDoc
-│       ├── stream-doc.ts               # buildStreamRouteDoc
-│       └── http-stream-doc.ts          # buildHttpStreamRouteDoc
-```
-
-### `build()` Dispatch Loop
-
-```ts
-build(): Hono {
-  for (const item of this._factories) {
-    for (const procedure of item.factory.getProcedures().values()) {
-      switch (procedure.kind) {
-        case 'rpc':
-          installRpcRoute(this._app, procedure, item, this.config, this._docs)
-          break
-        case 'rpc-stream':
-          installRpcStreamRoute(this._app, procedure, item, this.config, this._docs)
-          break
-        case 'http':
-          installHttpRoute(this._app, procedure, item, this.config, this._docs)
-          break
-        case 'http-stream':
-          installHttpStreamRoute(this._app, procedure, item, this.config, this._docs)
-          break
-        default: {
-          const reason = `Unknown procedure kind "${(procedure as any).kind}"`
-          this._skipped.push({ name: procedure.name, reason })
-          console.warn(`[ts-procedures hono] ${reason}`)
-        }
-      }
-    }
-  }
-  return this._app
-}
-```
-
-### Shared Error Dispatch
-
-`src/implementations/http/error-dispatch.ts` exports two functions that consolidate the three current near-identical implementations:
-
-```ts
-// Used by rpc, http, and the pre-stream guards in stream / http-stream.
-// Returns a Response.
-export async function dispatchPreStreamError(args: {
-  err: unknown
-  procedure: AnyProcedureRegistration
-  raw: Context
-  cfg: {
-    errors?: ErrorTaxonomy
-    unknownError?: UnknownErrorConfig
-    onError?: HonoAppBuilderConfig['onError']
-    onRequestError?: HonoAppBuilderConfig['onRequestError']
-  }
-}): Promise<Response>
-
-// Used inside stream generator catch blocks. Returns the data to write
-// (plus optional SSE metadata + onCatch hook), not a full Response — the
-// HTTP status is already committed once streaming starts.
-export async function dispatchMidStreamError<TData = unknown>(args: {
-  err: unknown
-  procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>
-  raw: Context
-  cfg: {
-    errors?: ErrorTaxonomy
-    unknownError?: UnknownErrorConfig
-    onMidStreamError?: HonoAppBuilderConfig<TData>['stream']['onMidStreamError']
-    onRequestError?: HonoAppBuilderConfig['onRequestError']
-  }
-}): Promise<{
-  data: unknown
-  sseEvent?: string
-  sseId?: string
-  sseRetry?: number
-  runOnCatch?: () => Promise<void>
-}>
-```
-
-Both call the `onRequestError` observer first (swallowing observer throws) and then dispatch through taxonomy → onError/onMidStreamError → hard default — same order as today.
-
-### Per-Kind Handler Modules
-
-Each handler module is a small file (~80–180 lines) exporting one `install*Route` function. Their job:
-
-1. Build the route doc (`docs/<kind>-doc.ts`) and push to `_docs`.
-2. Resolve the route path (`path.ts`).
-3. Register the Hono handler that:
-   - Resolves the factory context (sync object | sync fn | async fn).
-   - Extracts and assembles params from the request (per kind: body for rpc; structured req for http/http-stream; query-or-body for rpc-stream).
-   - Invokes `procedure.handler({ ...ctx, signal: c.req.raw.signal }, params)`.
-   - For streams: forwards `isPrevalidated: true` after the pre-stream validation so core doesn't re-validate.
-   - Catches and routes through `dispatchPreStreamError`.
-   - For streams: forwards mid-stream throws through `dispatchMidStreamError` and writes the result via `streamSSE`/`streamText`.
-   - Calls the right kind-specific lifecycle hook (`rpc.onSuccess`, `api.onSuccess`, `stream.onStreamStart`/`onStreamEnd`).
-
-Module-level coupling: each handler imports only the slice of config it needs (e.g., `handlers/stream.ts` imports `stream.*` and the cross-cutting error config). The full `HonoAppBuilderConfig` type lives in `hono/types.ts`.
-
-### Lazy Doc Computation
-
-Today `_docs` is populated during `build()` — calling `builder.docs` before `build()` returns an empty array. New behavior: `docs` is a getter that runs the per-kind doc-builders (`docs/<kind>-doc.ts`) without touching route registration; the result is cached. `build()` reuses the cached array. This makes `toDocEnvelope()` usable in tests without spinning up handlers.
-
-## Migration Impact
-
-Since v8 is unpublished, there's no in-the-wild deprecation cycle — we update docs, templates, and tests and ship.
-
-### Deletions
-
-- `src/implementations/http/hono-rpc/` (entire directory)
-- `src/implementations/http/hono-api/` (entire directory)
-- `src/implementations/http/hono-stream/` (entire directory)
-- The corresponding `package.json#exports` entries: `./hono-rpc`, `./hono-api`, `./hono-stream`
-
-### Additions
-
-- `src/implementations/http/hono/` (per the layout above)
-- `package.json#exports` entry: `./hono`
-- `src/implementations/http/error-dispatch.ts` — shared dispatchers (replacing inline copies in three builders)
-
-### Re-exports From `ts-procedures/hono`
-
-`HonoAppBuilder`, `HonoAppBuilderConfig`, `OnRequestErrorContext`, `AnyProcedureRegistration`, `RPCConfig`, `RPCHttpRouteDoc`, `APIConfig`, `APIHttpRouteDoc`, `APIInput`, `StreamHttpRouteDoc`, `HttpStreamRouteDoc`, `StreamMode`, `HttpMethod`, `QueryParser`, `MidStreamErrorResult`, `sse`, `defineErrorTaxonomy`, `ErrorTaxonomy`, `ErrorTaxonomyEntry`, `UnknownErrorConfig`.
-
-`./http-errors` and `./http-docs` (DocRegistry) keep their current subpaths.
-
-### User-Facing Migration Table
-
-| Before (in-flight v8) | After |
-|---|---|
-| `import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'` | `import { HonoAppBuilder } from 'ts-procedures/hono'` |
-| `import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'` | same |
-| `import { HonoStreamAppBuilder } from 'ts-procedures/hono-stream'` | same |
-| `new HonoRPCAppBuilder({ errors, onSuccess })` | `new HonoAppBuilder({ errors, rpc: { onSuccess } })` |
-| `new HonoAPIAppBuilder({ errors, queryParser })` | `new HonoAppBuilder({ errors, api: { queryParser } })` |
-| `new HonoStreamAppBuilder({ errors, onMidStreamError, defaultStreamMode })` | `new HonoAppBuilder({ errors, stream: { onMidStreamError, defaultStreamMode } })` |
-| Three builders sharing `app: Hono` | One builder, no shared-`app` plumbing |
-| `new DocRegistry().from(rpc).from(api).from(stream).toJSON()` | `builder.toDocEnvelope()` for single-app; DocRegistry only for multi-app aggregation |
-
-### Edge Cases & Behavior Preservation
-
-1. **Mixed-kind factories work natively.** A single `Procedures<>()` factory with `Create`/`CreateStream`/`CreateHttp`/`CreateHttpStream` calls dispatches correctly under one builder.
-2. **`pathPrefix` is global to the builder.** Users who genuinely need different prefixes per kind (rare) instantiate two `HonoAppBuilder`s sharing the same `app`.
-3. **`extendProcedureDoc`** receives a discriminated union — switch on `base.kind`.
-4. **Per-factory `streamMode` override** stays via `register(factory, ctx, { streamMode })`. Applies to both rpc-stream and http-stream procedures within that factory.
-5. **`AbortSignal` injection, SSE `event: 'return'`, `isPrevalidated`, `noRuntimeValidation`** — all preserved.
-6. **`skippedProcedures`** stays on the public surface but is expected to always be empty post-convergence (defensive logging for future kinds).
-7. **`HonoAppBuilder` satisfies `DocSource`** — multi-app users continue to assemble via `DocRegistry`.
-
-### Tests
-
-Consolidated under `src/implementations/http/hono/`:
-
-- `index.test.ts` — public surface (constructor, register, build, docs, toDocEnvelope, makeRoutePath)
-- `handlers/rpc.test.ts`, `handlers/http.test.ts`, `handlers/stream.test.ts`, `handlers/http-stream.test.ts` — per-kind handler behavior, taking the place of the three separate `index.test.ts` files
-- `../error-dispatch.test.ts` — shared error dispatch (folds in `error-taxonomy.test.ts` content from each old builder)
-
-Top-level shared tests at `src/implementations/http/` stay: `error-taxonomy.test.ts`, `doc-registry.test.ts`, `on-request-error.test.ts`, `route-errors.test.ts`.
-
-Codegen e2e fixtures consume `DocEnvelope` JSON — unaffected.
-
-### Templates & Docs
-
-- `agent_config/claude-code/skills/ts-procedures-scaffold/templates/` — delete `hono-rpc.ts`, `hono-stream.ts`; rewrite `hono-api.ts` (or rename to `hono.ts`) demonstrating one builder serving all kinds.
-- `agent_config/claude-code/skills/ts-procedures/{SKILL.md, patterns.md, anti-patterns.md}` — replace per-builder examples with single-builder examples.
-- `agent_config/copilot/copilot-instructions.md` and `agent_config/cursor/cursorrules` — same updates (these mirror the Claude skill content).
-- `src/implementations/http/README.md` — rewrite around `HonoAppBuilder`. Drop the "RPC vs Streaming vs API builder" sectioning. Replace with one section + a "Which procedure kind to use" table.
-- `docs/http-integrations.md` — rewrite around the unified builder. Delete the "One Hono Server, Multiple Builders" section (no longer relevant).
-- README v8 changelog — update the convergence entry.
-
-## Test Plan
-
-1. **Public-surface contract** — constructor stores config; `register()` is chainable; `build()` returns `Hono`; `docs` is lazy and stable across multiple reads; `toDocEnvelope()` produces a DocEnvelope identical to a `DocRegistry({ basePath, errors }).from(builder).toJSON()` output for the same builder.
-2. **Per-kind dispatch** — register a single factory containing one procedure of each of the four kinds; verify each is mounted at the correct path with the correct method(s) and produces the correct doc shape.
-3. **Mixed factories** — register two factories with different `factoryContext` resolvers; verify each procedure receives the correct context and that the resolver runs once per request.
-4. **Stratified config** — `rpc.onSuccess` fires only for rpc; `api.onSuccess` fires only for http; `stream.onStreamStart`/`onStreamEnd`/`onMidStreamError` fire only for streaming kinds. Cross-cutting hooks (`onRequestStart`/`onRequestEnd`/`onRequestError`) fire for every kind.
-5. **Error dispatch parity** — port the existing taxonomy tests from each old builder. Pre-stream errors flow through `dispatchPreStreamError`; mid-stream errors flow through `dispatchMidStreamError` with status already committed. `onRequestError` observer fires before dispatch in both paths and its throws are swallowed.
-6. **Path generation** — `makeRoutePath` returns the expected URL for each kind; with and without `prefix`; with array vs. string `scope`.
-7. **Per-factory `streamMode` override** — registering with `{ streamMode: 'text' }` overrides `stream.defaultStreamMode` for that factory's stream procedures only.
-8. **`extendProcedureDoc`** — receives a kind-discriminated `base`; returned fields are merged onto the route doc; `kind` cannot be overwritten.
-9. **DocSource compatibility** — `new DocRegistry().from(builder).toJSON()` produces a valid envelope matching `builder.toDocEnvelope()` (modulo `basePath` if not specified).
-10. **Codegen end-to-end** — feed `builder.toDocEnvelope()` into `generateClient()` for the TS / Kotlin / Swift targets and verify the generated output compiles. Use the existing fixture envelope structure.
-
-## Out of Scope (Follow-ups)
-
-- **Top-level `onSuccess` shortcut** — if the duplicated `rpc.onSuccess` + `api.onSuccess` pattern shows up in real apps, add a top-level `onSuccess` that fans out to both. Non-breaking when added.
-- **Different `pathPrefix` per kind** — if users actually need this, add `rpc.pathPrefix` / `api.pathPrefix` / `stream.pathPrefix` overrides. Today the workaround (two builders sharing one `app`) is acceptable.