ts-procedures 5.4.1 → 5.6.0-beta.0

package/README.md

@@ -727,6 +727,27 @@ for (const config of procedures) {
 }
 ```
 
+### DocRegistry — Composing Docs from Multiple Builders
+
+Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+  errors: DocRegistry.defaultErrors(),
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+`from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
+
 ## Testing
 
 Procedures return handlers that can be called directly in tests:
@@ -859,6 +880,156 @@ import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APICon
 // Hono API (REST-style)
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod, QueryParser } from 'ts-procedures/hono-api'
+
+// Client Runtime
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+
+// Code Generation
+import { generateClient } from 'ts-procedures/codegen'
+```
+
+## Client Code Generation
+
+ts-procedures can generate type-safe client SDKs directly from your server's `DocRegistry` output. Generated files include TypeScript types and callable functions for every registered procedure, organized by scope — no manual type duplication required.
+
+### Quick Start
+
+**Step 1 — Serve your docs endpoint:**
+
+```typescript
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+**Step 2 — Generate the client:**
+
+```bash
+npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+```
+
+**Step 3 — Use the client:**
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
+      return ctx
+    },
+  },
+})
+
+// Fully typed — params and response inferred from server schemas
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+```
+
+### Generated File Structure
+
+Running the codegen command produces one file per scope, plus shared error types and a barrel export:
+
+```
+generated/
+  users.ts           # Types + callables for "users" scope
+  billing.ts         # Types + callables for "billing" scope
+  notifications.ts   # Types + callables for stream procedures
+  _errors.ts         # Typed error classes + ProcedureErrorUnion
+  index.ts           # Barrel exports + createScopeBindings
+```
+
+### CLI Reference
+
+| Flag | Description | Required |
+|------|-------------|----------|
+| `--url <url>` | Fetch DocEnvelope from URL | One of `--url` or `--file` |
+| `--file <path>` | Read DocEnvelope from JSON file | One of `--url` or `--file` |
+| `--out <dir>` | Output directory | Yes |
+| `--watch` | Poll for changes and regenerate | No |
+| `--interval <ms>` | Watch poll interval (default: 3000) | No |
+| `--dry-run` | Preview without writing files | No |
+| `--client-import-path <path>` | Override import path (default: `ts-procedures/client`) | No |
+| `--enum-style <union\|enum>` | TypeScript enum style | No |
+| `--depluralize` | Singularize array item type names | No |
+
+### Adapter Interface
+
+The client requires an adapter that handles the actual HTTP transport. A built-in fetch adapter is included, and you can implement your own for any HTTP library:
+
+```typescript
+import { createFetchAdapter } from 'ts-procedures/client'
+
+// Use the built-in fetch adapter
+const adapter = createFetchAdapter({ headers: { 'X-API-Key': 'my-key' } })
+
+// Or implement your own (e.g., for axios)
+const axiosAdapter: ClientAdapter = {
+  async request({ url, method, headers, body }) {
+    const res = await axios({ url, method, headers, data: body })
+    return { status: res.status, headers: res.headers, body: res.data }
+  },
+  async stream({ url, method, headers, body }) {
+    // Return AsyncIterable of SSE events
+  },
+}
+```
+
+### Hooks
+
+Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks override or extend them for a single invocation.
+
+```typescript
+// Global hooks (apply to all calls)
+const client = createClient({
+  adapter,
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) { /* add auth headers */ return ctx },
+    onAfterResponse(ctx) { /* handle errors, logging */ },
+    onError(ctx) { /* error reporting */ },
+  },
+})
+
+// Per-procedure hook override
+await client.users.GetUser({ pathParams: { id: '123' } }, {
+  onAfterResponse(ctx) {
+    const rateLimit = ctx.response.headers['x-rate-limit-remaining']
+  },
+})
+```
+
+### Streaming
+
+Stream procedures return a `TypedStream` — an async iterable for yield values, with a `.result` promise for the final return value:
+
+```typescript
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+for await (const event of stream) {
+  console.log(event) // typed as WatchNotificationsYield
+}
+
+const result = await stream.result // typed as WatchNotificationsReturn
+```
+
+### Programmatic API
+
+For build pipelines or custom tooling, `generateClient` can be called directly without the CLI:
+
+```typescript
+import { generateClient } from 'ts-procedures/codegen'
+
+await generateClient({
+  url: 'http://localhost:3000/docs',
+  outDir: './src/generated/api',
+  clientImportPath: '@my-app/procedures-client', // optional
+  dryRun: false, // optional
+})
 ```
 
 ## AI Agent Setup

package/agent_config/claude-code/skills/guide/SKILL.md

@@ -82,6 +82,7 @@ All errors include `definedAt` (file:line:column) and enhanced stack traces poin
 | `ExpressRPCAppBuilder` | `ts-procedures/express-rpc` | POST JSON |
 | `HonoRPCAppBuilder` | `ts-procedures/hono-rpc` | POST JSON |
 | `HonoStreamAppBuilder` | `ts-procedures/hono-stream` | SSE or newline-delimited JSON |
+| `DocRegistry` | `ts-procedures/http-docs` | Compose route docs from multiple builders |
 
 ### Route Path Format
 

package/agent_config/claude-code/skills/guide/anti-patterns.md

@@ -451,7 +451,40 @@ console.log(builder.docs)
 
 ---
 
-## 16. Using Async Context Factory Without Error Handling
+## 16. Manually Wiring a /docs Endpoint Instead of Using DocRegistry
+
+**Problem:** Building the docs JSON envelope by hand in every app — duplicating basePath, headers, errors, and route assembly.
+
+```typescript
+// BAD — repeated boilerplate in every app
+app.get('/docs', (c) => c.json({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token' }],
+  errors: [],
+  routes: [...rpcBuilder.docs, ...apiBuilder.docs, ...streamBuilder.docs],
+}))
+```
+
+**Fix:** Use `DocRegistry` to compose docs from builders.
+
+```typescript
+// GOOD — declarative, composable, typed
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token' }],
+  errors: DocRegistry.defaultErrors(),
+}).from(rpcBuilder).from(apiBuilder).from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+**Why:** `DocRegistry` provides a typed `DocEnvelope`, includes `defaultErrors()` with JSON Schemas for all 4 procedure error types, reads docs lazily (order-independent), and supports filtering and transformation via `toJSON()` options.
+
+---
+
+## 17. Using Async Context Factory Without Error Handling
 
 **Problem:** Async context factories that throw unhandled errors, crashing the request.
 
@@ -480,7 +513,7 @@ new ExpressRPCAppBuilder({
 
 ---
 
-## 17. Using Both schema.params and schema.input
+## 18. Using Both schema.params and schema.input
 
 **Problem:** Defining both `schema.params` and `schema.input` on the same procedure.
 
@@ -523,7 +556,7 @@ Create('GetUser', {
 
 ---
 
-## 18. Mismatched Path Param Names in schema.input
+## 19. Mismatched Path Param Names in schema.input
 
 **Problem:** Path template param names don't match `schema.input.pathParams` property names.
 
@@ -559,7 +592,7 @@ Create('GetUser', {
 
 ---
 
-## 19. Forgetting build() is Async on HonoAPIAppBuilder
+## 20. Forgetting build() is Async on HonoAPIAppBuilder
 
 **Problem:** Not awaiting `build()` on `HonoAPIAppBuilder`.
 

package/agent_config/claude-code/skills/guide/api-reference.md

@@ -665,6 +665,269 @@ type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
 
 ---
 
+## DocRegistry
+
+Composes route documentation from any number of HTTP builders into a typed envelope. Eliminates boilerplate `/docs` endpoint wiring.
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, HeaderDoc, ErrorDoc, DocSource } from 'ts-procedures/http-docs'
+```
+
+```typescript
+class DocRegistry {
+  constructor(config?: {
+    basePath?: string
+    headers?: HeaderDoc[]
+    errors?: ErrorDoc[]
+  })
+
+  from(source: DocSource<AnyHttpRouteDoc>): this
+
+  toJSON<T = DocEnvelope>(options?: {
+    filter?: (route: AnyHttpRouteDoc) => boolean
+    transform?: (envelope: DocEnvelope) => T
+  }): T
+
+  static defaultErrors(): ErrorDoc[]
+}
+```
+
+### DocSource
+
+Any object with a `readonly docs` array. All four HTTP builders (`HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder`, `ExpressRPCAppBuilder`) satisfy this interface.
+
+```typescript
+interface DocSource<T = AnyHttpRouteDoc> {
+  readonly docs: T[]
+}
+```
+
+### HeaderDoc
+
+```typescript
+interface HeaderDoc {
+  name: string
+  description?: string
+  required?: boolean
+  example?: string
+}
+```
+
+### ErrorDoc
+
+```typescript
+interface ErrorDoc {
+  name: string
+  statusCode: number
+  description: string
+  schema?: Record<string, unknown>
+}
+```
+
+### DocEnvelope
+
+```typescript
+interface DocEnvelope {
+  basePath: string
+  headers: HeaderDoc[]
+  errors: ErrorDoc[]
+  routes: AnyHttpRouteDoc[]
+}
+```
+
+### AnyHttpRouteDoc
+
+```typescript
+type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc
+```
+
+### Key Behaviors
+
+- `from()` stores a **reference** to the builder — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`
+- `toJSON()` collects routes via `flatMap(source => source.docs)`, applies optional `filter`, builds envelope, then applies optional `transform`
+- `defaultErrors()` returns 4 `ErrorDoc` entries describing `ProcedureError` (500), `ProcedureValidationError` (400), `ProcedureYieldValidationError` (500), `ProcedureRegistrationError` (500) — each with a JSON Schema for the error response body shape
+- `JSON.stringify(registry)` works directly (calls `toJSON()` implicitly)
+
+---
+
+## createClient(config)
+
+Creates a typed client instance bound to generated scope bindings.
+
+```typescript
+function createClient<TScopes>(config: {
+  adapter: ClientAdapter
+  basePath: string
+  scopes: (client: ClientInstance) => TScopes
+  hooks?: ClientHooks
+}): TScopes
+```
+
+### Parameters
+
+- `config.adapter` — Transport adapter implementing `ClientAdapter`. Use `createFetchAdapter()` for fetch-based transport.
+- `config.basePath` — Base URL prepended to all request paths (e.g., `'http://localhost:3000'`).
+- `config.scopes` — Factory function that receives a raw `ClientInstance` and returns the typed scope object. Typically the `createScopeBindings` export from generated code.
+- `config.hooks` — Optional global hooks applied to every call. Can be overridden per call.
+
+### Return Value
+
+Returns the result of `config.scopes(clientInstance)` — a typed object where each key is a scope and each value is a record of callable procedure functions.
+
+### ClientHooks
+
+```typescript
+interface ClientHooks {
+  onBeforeRequest?: (ctx: { request: ClientRequest }) => { request: ClientRequest } | void
+  onAfterResponse?: (ctx: { request: ClientRequest; response: ClientResponse }) => void
+}
+```
+
+### Example
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
+      return ctx
+    },
+  },
+})
+
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+```
+
+---
+
+## createFetchAdapter()
+
+Creates a `ClientAdapter` using the global `fetch` API.
+
+```typescript
+function createFetchAdapter(options?: {
+  fetch?: typeof globalThis.fetch
+}): ClientAdapter
+```
+
+### Parameters
+
+- `options.fetch` — Optional custom fetch implementation. Defaults to `globalThis.fetch`.
+
+### Return Value
+
+A `ClientAdapter` that supports both request/response and SSE streaming.
+
+### Example
+
+```typescript
+import { createFetchAdapter } from 'ts-procedures/client'
+
+// Default (uses globalThis.fetch)
+const adapter = createFetchAdapter()
+
+// Custom fetch (e.g., node-fetch, undici)
+const adapter = createFetchAdapter({ fetch: customFetch })
+```
+
+---
+
+## generateClient(options)
+
+Build-time CLI and programmatic API for generating typed client files from a `DocEnvelope`.
+
+```typescript
+// CLI usage (preferred)
+// npx ts-procedures-codegen --url <url> --out <dir> [--fetch]
+
+// Programmatic
+async function generateClient(options: {
+  envelope: DocEnvelope
+  outDir: string
+}): Promise<void>
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--url <url>` | URL to fetch the `DocEnvelope` JSON from (e.g., `http://localhost:3000/docs`) |
+| `--out <dir>` | Output directory for generated files |
+| `--fetch` | Fetch the envelope at runtime rather than from a local file |
+
+### Generated Output
+
+- One `.ts` file per scope (e.g., `users.ts`, `events.ts`)
+- A root `index.ts` exporting `createScopeBindings`
+- Each scope file exports fully-typed callable functions and TypeScript types
+
+### Example
+
+```typescript
+// CLI
+// npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+
+// Programmatic
+import { generateClient } from 'ts-procedures/codegen'
+
+await generateClient({
+  envelope: await fetch('http://localhost:3000/docs').then(r => r.json()),
+  outDir: './src/generated/api',
+})
+```
+
+---
+
+## TypedStream\<TYield, TReturn\>
+
+Async iterable returned by stream procedure calls on the generated client. Yields typed values and exposes a `result` promise for the stream's final return value.
+
+```typescript
+interface TypedStream<TYield, TReturn> extends AsyncIterable<TYield> {
+  result: Promise<TReturn>
+  [Symbol.asyncIterator](): AsyncIterator<TYield>
+}
+```
+
+### Type Parameters
+
+- `TYield` — Type of each yielded value (from `schema.yieldType`)
+- `TReturn` — Type of the stream's return value (from `schema.returnType`). Sent as `event: 'return'` SSE message by `HonoStreamAppBuilder`.
+
+### Key Behavior
+
+- Iterating with `for await...of` yields each SSE data event as `TYield`
+- `stream.result` resolves when the stream closes with the final return value
+- If the stream has no return value, `TReturn` is `void` and `result` resolves to `undefined`
+
+### Example
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({ adapter: createFetchAdapter(), basePath: '...', scopes: createScopeBindings })
+
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+// Consume yielded values
+for await (const event of stream) {
+  console.log(event) // Typed as WatchNotificationsYield
+}
+
+// Access return value after iteration completes
+const summary = await stream.result // Typed as WatchNotificationsReturn
+```
+
+---
+
 ## Stack Utilities
 
 ### captureDefinitionInfo()

package/agent_config/claude-code/skills/guide/patterns.md

@@ -640,6 +640,39 @@ const openApiPaths = app.docs.map(doc => ({
 
 ---
 
+## DocRegistry — Composing Docs from Multiple Builders
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+// Compose docs from any combination of builders
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+  errors: DocRegistry.defaultErrors(),
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+// Serve as a /docs endpoint
+app.get('/docs', (c) => c.json(docs.toJSON()))
+
+// With filtering and transformation
+app.get('/docs', (c) => c.json(docs.toJSON({
+  filter: (route) => route.name !== 'InternalHealthCheck',
+  transform: (envelope) => ({ ...envelope, generatedAt: new Date().toISOString() }),
+})))
+```
+
+**Key points:**
+- `from()` stores a reference — register builders before or after `.build()`
+- `toJSON()` reads docs lazily, so late-registered procedures are included
+- `DocRegistry.defaultErrors()` provides error schemas for all 4 procedure error types
+- Accepts any object satisfying `{ readonly docs: AnyHttpRouteDoc[] }` — not limited to built-in builders
+
+---
+
 ## Testing Procedures
 
 ```typescript
@@ -725,3 +758,110 @@ onRequestStart → factoryContext() → params validation
                                   → onStreamStart → handler yields → onStreamEnd → onRequestEnd
                                                   → onMidStreamError (if throw) → onStreamEnd → onRequestEnd
 ```
+
+---
+
+## Client Code Generation Setup
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+// Server: serve docs endpoint
+const docs = new DocRegistry({
+  basePath: '/api',
+  headers: [{ name: 'Authorization', description: 'Bearer token' }],
+  errors: DocRegistry.defaultErrors(),
+})
+  .from(rpcBuilder)
+  .from(apiBuilder)
+  .from(streamBuilder)
+
+app.get('/docs', (c) => c.json(docs.toJSON()))
+
+// Then generate client:
+// npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+```
+
+---
+
+## Type-Safe Client Usage
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createScopeBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = {
+        ...ctx.request.headers,
+        Authorization: `Bearer ${getToken()}`,
+      }
+      return ctx
+    },
+    onAfterResponse(ctx) {
+      if (ctx.response.status === 401) {
+        redirect('/login')
+      }
+    },
+  },
+})
+
+// Fully typed — params and response inferred from server schemas
+const user = await client.users.GetUser({ pathParams: { id: '123' } })
+```
+
+---
+
+## Streaming Client Usage
+
+```typescript
+const stream = client.events.WatchNotifications({ filter: 'all' })
+
+for await (const event of stream) {
+  console.log(event) // Typed as WatchNotificationsYield
+}
+
+// Access the stream's return value
+const result = await stream.result // Typed as WatchNotificationsReturn
+```
+
+---
+
+## Per-Procedure Hook Override
+
+```typescript
+// Override hooks for a specific call
+await client.users.GetUser({ pathParams: { id: '123' } }, {
+  onAfterResponse(ctx) {
+    const rateLimit = ctx.response.headers['x-rate-limit-remaining']
+    console.log(`Rate limit remaining: ${rateLimit}`)
+  },
+})
+```
+
+---
+
+## Custom Client Adapter (Axios)
+
+```typescript
+import type { ClientAdapter } from 'ts-procedures/client'
+import axios from 'axios'
+
+const axiosAdapter: ClientAdapter = {
+  async request({ url, method, headers, body, signal }) {
+    const res = await axios({ url, method, headers, data: body, signal })
+    return {
+      status: res.status,
+      headers: Object.fromEntries(Object.entries(res.headers).filter(([, v]) => typeof v === 'string')) as Record<string, string>,
+      body: res.data,
+    }
+  },
+  async stream() {
+    throw new Error('Streaming not supported with axios adapter')
+  },
+}
+```

package/agent_config/claude-code/skills/review/checklist.md

@@ -72,6 +72,7 @@
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
+- [ ] Uses `DocRegistry` to compose docs from multiple builders instead of manual envelope assembly
 - [ ] Lifecycle hooks used for observability (logging, metrics)
 
 ---
@@ -110,6 +111,7 @@
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
+- [ ] Uses `DocRegistry` to compose docs across builders instead of manual assembly
 - [ ] Custom `queryParser` provided if complex query string formats needed
 - [ ] Lifecycle hooks used for observability (logging, metrics)
 

package/agent_config/claude-code/skills/scaffold/templates/hono-api.md

@@ -113,7 +113,7 @@ export const {{name}}App = await new HonoAPIAppBuilder({
 // POST   /api/{{name}}     → 201
 // DELETE /api/{{name}}/:id → 204
 
-// Documentation: builder.docs (access before .build() resolves)
+// Documentation: builder.docs or compose with DocRegistry from 'ts-procedures/http-docs'
 ```
 
 ## Test — `{{Name}}.api.test.ts`