ts-procedures 5.4.1 → 5.5.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:

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,92 @@ 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)
+
+---
+
 ## 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

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`

package/agent_config/copilot/copilot-instructions.md

@@ -38,6 +38,10 @@ import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
 // Hono API (REST-style)
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIInput } from 'ts-procedures/hono-api'
+
+// Doc Registry — compose route docs from multiple builders
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
 ```
 
 ## Architecture Rules

package/agent_config/cursor/cursorrules

@@ -38,6 +38,10 @@ import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
 // Hono API (REST-style)
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIInput } from 'ts-procedures/hono-api'
+
+// Doc Registry — compose route docs from multiple builders
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
 ```
 
 ## Architecture Rules

package/build/implementations/http/doc-registry.d.ts

@@ -0,0 +1,12 @@
+import type { AnyHttpRouteDoc, DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, DocSource, ErrorDoc } from '../types.js';
+export type { AnyHttpRouteDoc, DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, DocSource, ErrorDoc, HeaderDoc, } from '../types.js';
+export declare class DocRegistry {
+    private readonly basePath;
+    private readonly headers;
+    private readonly errors;
+    private readonly sources;
+    constructor(config?: DocRegistryConfig);
+    from(source: DocSource<AnyHttpRouteDoc>): this;
+    toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T;
+    static defaultErrors(): ErrorDoc[];
+}

package/build/implementations/http/doc-registry.js

@@ -0,0 +1,114 @@
+export class DocRegistry {
+    basePath;
+    headers;
+    errors;
+    sources = [];
+    constructor(config) {
+        this.basePath = config?.basePath ?? '';
+        this.headers = config?.headers ?? [];
+        this.errors = config?.errors ?? [];
+    }
+    from(source) {
+        this.sources.push(source);
+        return this;
+    }
+    toJSON(options) {
+        let routes = this.sources.flatMap((source) => source.docs);
+        if (options?.filter) {
+            routes = routes.filter(options.filter);
+        }
+        const envelope = {
+            basePath: this.basePath,
+            headers: [...this.headers],
+            errors: [...this.errors],
+            routes,
+        };
+        if (options?.transform) {
+            return options.transform(envelope);
+        }
+        return envelope;
+    }
+    // Keep in sync with src/errors.ts
+    static defaultErrors() {
+        return [
+            {
+                name: 'ProcedureError',
+                statusCode: 500,
+                description: 'An error thrown from within a procedure handler via ctx.error().',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                        meta: { type: 'object' },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+            {
+                name: 'ProcedureValidationError',
+                statusCode: 400,
+                description: 'Schema validation failed for the procedure input parameters.',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureValidationError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                        errors: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    instancePath: { type: 'string' },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+            {
+                name: 'ProcedureYieldValidationError',
+                statusCode: 500,
+                description: 'Schema validation failed for a yielded value in a streaming procedure.',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureYieldValidationError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                        errors: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    instancePath: { type: 'string' },
+                                    message: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+            {
+                name: 'ProcedureRegistrationError',
+                statusCode: 500,
+                description: 'An invalid schema or configuration was detected at procedure registration time.',
+                schema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', const: 'ProcedureRegistrationError' },
+                        procedureName: { type: 'string' },
+                        message: { type: 'string' },
+                    },
+                    required: ['name', 'procedureName', 'message'],
+                },
+            },
+        ];
+    }
+}
+//# sourceMappingURL=doc-registry.js.map

package/build/implementations/http/doc-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-registry.js","sourceRoot":"","sources":["../../../src/implementations/http/doc-registry.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,WAAW;IACL,QAAQ,CAAQ;IAChB,OAAO,CAAa;IACpB,MAAM,CAAY;IAClB,OAAO,GAAiC,EAAE,CAAA;IAE3D,YAAY,MAA0B;QACpC,IAAI,CAAC,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAA;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,CAAA;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,EAAE,CAAA;IACpC,CAAC;IAED,IAAI,CAAC,MAAkC;QACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,CAAkB,OAAqC;QAC3D,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAE1D,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACxC,CAAC;QAED,MAAM,QAAQ,GAAgB;YAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YAC1B,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACxB,MAAM;SACP,CAAA;QAED,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QACpC,CAAC;QAED,OAAO,QAAa,CAAA;IACtB,CAAC;IAED,kCAAkC;IAClC,MAAM,CAAC,aAAa;QAClB,OAAO;YACL;gBACE,IAAI,EAAE,gBAAgB;gBACtB,UAAU,EAAE,GAAG;gBACf,WAAW,EAAE,kEAAkE;gBAC/E,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE;wBACjD,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACjC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qBACzB;oBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,CAAC;iBAC/C;aACF;YACD;gBACE,IAAI,EAAE,0BAA0B;gBAChC,UAAU,EAAE,GAAG;gBACf,WAAW,EAAE,8DAA8D;gBAC3E,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,0BAA0B,EAAE;wBAC3D,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACjC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC3B,MAAM,EAAE;4BACN,IAAI,EAAE,OAAO;4BACb,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,UAAU,EAAE;oCACV,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oCAChC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iCAC5B;6BACF;yBACF;qBACF;oBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,CAAC;iBAC/C;aACF;YACD;gBACE,IAAI,EAAE,+BAA+B;gBACrC,UAAU,EAAE,GAAG;gBACf,WAAW,EACT,wEAAwE;gBAC1E,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,+BAA+B,EAAE;wBAChE,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACjC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBAC3B,MAAM,EAAE;4BACN,IAAI,EAAE,OAAO;4BACb,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,UAAU,EAAE;oCACV,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oCAChC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iCAC5B;6BACF;yBACF;qBACF;oBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,CAAC;iBAC/C;aACF;YACD;gBACE,IAAI,EAAE,4BAA4B;gBAClC,UAAU,EAAE,GAAG;gBACf,WAAW,EACT,iFAAiF;gBACnF,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,4BAA4B,EAAE;wBAC7D,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACjC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;qBAC5B;oBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,CAAC;iBAC/C;aACF;SACF,CAAA;IACH,CAAC;CACF"}

package/build/implementations/http/doc-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/implementations/http/doc-registry.test.js

@@ -0,0 +1,321 @@
+import { describe, expect, test } from 'vitest';
+import { v } from 'suretype';
+import { Procedures } from '../../index.js';
+import { HonoRPCAppBuilder } from './hono-rpc/index.js';
+import { DocRegistry } from './doc-registry.js';
+// ---------------------------------------------------------------------------
+// Helpers — minimal doc fixtures
+// ---------------------------------------------------------------------------
+const rpcDoc = {
+    name: 'Echo',
+    path: '/echo/1',
+    method: 'post',
+    scope: 'echo',
+    version: 1,
+    jsonSchema: { body: { type: 'object' } },
+};
+const apiDoc = {
+    name: 'GetUser',
+    path: '/users/:id',
+    method: 'get',
+    fullPath: '/api/users/:id',
+    jsonSchema: { pathParams: { type: 'object' } },
+};
+const streamDoc = {
+    name: 'Feed',
+    path: '/feed/1',
+    methods: ['get'],
+    streamMode: 'sse',
+    scope: 'feed',
+    version: 1,
+    jsonSchema: { yieldType: { type: 'object' } },
+};
+function makeSource(docs) {
+    return { docs };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('DocRegistry', () => {
+    // --------------------------------------------------------------------------
+    // Constructor
+    // --------------------------------------------------------------------------
+    describe('constructor', () => {
+        test('uses defaults when no config provided', () => {
+            const registry = new DocRegistry();
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('');
+            expect(out.headers).toEqual([]);
+            expect(out.errors).toEqual([]);
+        });
+        test('accepts partial config', () => {
+            const registry = new DocRegistry({ basePath: '/v1' });
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/v1');
+            expect(out.headers).toEqual([]);
+            expect(out.errors).toEqual([]);
+        });
+        test('accepts full config', () => {
+            const headers = [{ name: 'Authorization', description: 'Bearer token', required: true }];
+            const errors = [{ name: 'Unauthorized', statusCode: 401, description: 'Missing token' }];
+            const registry = new DocRegistry({ basePath: '/api', headers, errors });
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/api');
+            expect(out.headers).toEqual(headers);
+            expect(out.errors).toEqual(errors);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // from()
+    // --------------------------------------------------------------------------
+    describe('from()', () => {
+        test('returns this for chaining', () => {
+            const registry = new DocRegistry();
+            const result = registry.from(makeSource([rpcDoc]));
+            expect(result).toBe(registry);
+        });
+        test('accepts RPC builder source', () => {
+            const registry = new DocRegistry().from(makeSource([rpcDoc]));
+            expect(registry.toJSON().routes).toEqual([rpcDoc]);
+        });
+        test('accepts API builder source', () => {
+            const registry = new DocRegistry().from(makeSource([apiDoc]));
+            expect(registry.toJSON().routes).toEqual([apiDoc]);
+        });
+        test('accepts Stream builder source', () => {
+            const registry = new DocRegistry().from(makeSource([streamDoc]));
+            expect(registry.toJSON().routes).toEqual([streamDoc]);
+        });
+        test('accepts plain { docs } object', () => {
+            const plain = { docs: [rpcDoc, apiDoc] };
+            const registry = new DocRegistry().from(plain);
+            expect(registry.toJSON().routes).toHaveLength(2);
+        });
+        test('builder not yet built returns empty routes', () => {
+            const emptySource = makeSource([]);
+            const registry = new DocRegistry().from(emptySource);
+            expect(registry.toJSON().routes).toEqual([]);
+        });
+        test('same builder twice duplicates routes', () => {
+            const source = makeSource([rpcDoc]);
+            const registry = new DocRegistry().from(source).from(source);
+            expect(registry.toJSON().routes).toHaveLength(2);
+            expect(registry.toJSON().routes[0]).toEqual(registry.toJSON().routes[1]);
+        });
+        test('reads docs lazily at toJSON() time', () => {
+            const mutableDocs = [];
+            const source = { get docs() { return mutableDocs; } };
+            const registry = new DocRegistry().from(source);
+            expect(registry.toJSON().routes).toHaveLength(0);
+            mutableDocs.push(rpcDoc);
+            expect(registry.toJSON().routes).toHaveLength(1);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // toJSON()
+    // --------------------------------------------------------------------------
+    describe('toJSON()', () => {
+        test('returns correct DocEnvelope shape', () => {
+            const registry = new DocRegistry({ basePath: '/api' });
+            const out = registry.toJSON();
+            expect(out).toHaveProperty('basePath');
+            expect(out).toHaveProperty('headers');
+            expect(out).toHaveProperty('errors');
+            expect(out).toHaveProperty('routes');
+        });
+        test('collects routes from all sources', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]))
+                .from(makeSource([streamDoc]));
+            const out = registry.toJSON();
+            expect(out.routes).toHaveLength(3);
+            expect(out.routes).toEqual([rpcDoc, apiDoc, streamDoc]);
+        });
+        test('empty when no sources', () => {
+            const out = new DocRegistry().toJSON();
+            expect(out.routes).toEqual([]);
+        });
+        test('headers and errors are copies', () => {
+            const headers = [{ name: 'X-Custom' }];
+            const errors = [{ name: 'E', statusCode: 500, description: 'd' }];
+            const registry = new DocRegistry({ headers, errors });
+            const out = registry.toJSON();
+            expect(out.headers).toEqual(headers);
+            expect(out.headers).not.toBe(headers);
+            expect(out.errors).toEqual(errors);
+            expect(out.errors).not.toBe(errors);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // toJSON() filter
+    // --------------------------------------------------------------------------
+    describe('toJSON() filter', () => {
+        test('excludes routes by name', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON({ filter: (r) => r.name !== 'Echo' });
+            expect(out.routes).toHaveLength(1);
+            expect(out.routes[0].name).toBe('GetUser');
+        });
+        test('excludes routes by type field', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON({
+                filter: (r) => 'method' in r && r.method === 'post' && 'scope' in r,
+            });
+            expect(out.routes).toHaveLength(1);
+            expect(out.routes[0].name).toBe('Echo');
+        });
+        test('all filtered returns empty routes array', () => {
+            const registry = new DocRegistry().from(makeSource([rpcDoc]));
+            const out = registry.toJSON({ filter: () => false });
+            expect(out.routes).toEqual([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // toJSON() transform
+    // --------------------------------------------------------------------------
+    describe('toJSON() transform', () => {
+        test('adds fields', () => {
+            const registry = new DocRegistry({ basePath: '/api' }).from(makeSource([rpcDoc]));
+            const out = registry.toJSON({
+                transform: (envelope) => ({ ...envelope, version: '2.0' }),
+            });
+            expect(out.version).toBe('2.0');
+            expect(out.basePath).toBe('/api');
+        });
+        test('reshapes envelope', () => {
+            const registry = new DocRegistry().from(makeSource([rpcDoc]));
+            const out = registry.toJSON({
+                transform: (envelope) => ({ count: envelope.routes.length }),
+            });
+            expect(out).toEqual({ count: 1 });
+        });
+        test('runs after filter', () => {
+            const registry = new DocRegistry()
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON({
+                filter: (r) => r.name === 'Echo',
+                transform: (envelope) => ({ ...envelope, filteredCount: envelope.routes.length }),
+            });
+            expect(out.filteredCount).toBe(1);
+            expect(out.routes).toHaveLength(1);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // defaultErrors()
+    // --------------------------------------------------------------------------
+    describe('defaultErrors()', () => {
+        test('returns 4 entries', () => {
+            const errors = DocRegistry.defaultErrors();
+            expect(errors).toHaveLength(4);
+        });
+        test('has correct error names', () => {
+            const names = DocRegistry.defaultErrors().map((e) => e.name);
+            expect(names).toEqual([
+                'ProcedureError',
+                'ProcedureValidationError',
+                'ProcedureYieldValidationError',
+                'ProcedureRegistrationError',
+            ]);
+        });
+        test('has correct status codes', () => {
+            const errors = DocRegistry.defaultErrors();
+            expect(errors[0].statusCode).toBe(500); // ProcedureError
+            expect(errors[1].statusCode).toBe(400); // ProcedureValidationError
+            expect(errors[2].statusCode).toBe(500); // ProcedureYieldValidationError
+            expect(errors[3].statusCode).toBe(500); // ProcedureRegistrationError
+        });
+        test('each entry has schema', () => {
+            for (const err of DocRegistry.defaultErrors()) {
+                expect(err.schema).toBeDefined();
+                expect(err.schema.type).toBe('object');
+            }
+        });
+        test('returns a new array each call', () => {
+            const a = DocRegistry.defaultErrors();
+            const b = DocRegistry.defaultErrors();
+            expect(a).not.toBe(b);
+            expect(a).toEqual(b);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Integration
+    // --------------------------------------------------------------------------
+    describe('integration', () => {
+        test('multiple builder types composed', () => {
+            const registry = new DocRegistry({
+                basePath: '/api',
+                headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+                errors: DocRegistry.defaultErrors(),
+            })
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]))
+                .from(makeSource([streamDoc]));
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/api');
+            expect(out.headers).toHaveLength(1);
+            expect(out.errors).toHaveLength(4);
+            expect(out.routes).toHaveLength(3);
+        });
+        test('filter + transform combined', () => {
+            const registry = new DocRegistry({
+                basePath: '/api',
+                errors: DocRegistry.defaultErrors(),
+            })
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]))
+                .from(makeSource([streamDoc]));
+            const out = registry.toJSON({
+                filter: (r) => r.name !== 'Feed',
+                transform: (envelope) => ({
+                    ...envelope,
+                    generatedAt: '2026-01-01',
+                }),
+            });
+            expect(out.routes).toHaveLength(2);
+            expect(out.routes.map((r) => r.name)).toEqual(['Echo', 'GetUser']);
+            expect(out.generatedAt).toBe('2026-01-01');
+        });
+        test('output is JSON.stringify-safe', () => {
+            const registry = new DocRegistry({
+                basePath: '/api',
+                headers: [{ name: 'X-Request-Id', example: 'abc-123' }],
+                errors: DocRegistry.defaultErrors(),
+            })
+                .from(makeSource([rpcDoc]))
+                .from(makeSource([apiDoc]));
+            const out = registry.toJSON();
+            const str = JSON.stringify(out);
+            expect(() => JSON.parse(str)).not.toThrow();
+            expect(JSON.parse(str)).toEqual(out);
+        });
+        test('JSON.stringify(registry) produces default envelope', () => {
+            const registry = new DocRegistry({ basePath: '/api' })
+                .from(makeSource([rpcDoc]));
+            const str = JSON.stringify(registry);
+            const parsed = JSON.parse(str);
+            expect(parsed.basePath).toBe('/api');
+            expect(parsed.routes).toHaveLength(1);
+            expect(parsed.routes[0].name).toBe('Echo');
+        });
+        test('accepts a real HonoRPCAppBuilder as source', () => {
+            const RPC = Procedures();
+            RPC.Create('Ping', { scope: 'ping', version: 1, schema: { params: v.object({ msg: v.string() }) } }, async (_ctx, params) => params);
+            const builder = new HonoRPCAppBuilder();
+            builder.register(RPC, () => ({ userId: '123' }));
+            builder.build();
+            const registry = new DocRegistry({ basePath: '/rpc' }).from(builder);
+            const out = registry.toJSON();
+            expect(out.basePath).toBe('/rpc');
+            expect(out.routes).toHaveLength(1);
+            expect(out.routes[0].name).toBe('Ping');
+            expect(out.routes[0]).toHaveProperty('jsonSchema');
+        });
+    });
+});
+//# sourceMappingURL=doc-registry.test.js.map

package/build/implementations/http/doc-registry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-registry.test.js","sourceRoot":"","sources":["../../../src/implementations/http/doc-registry.test.ts"],"names":[],"mappings":"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"}

package/build/implementations/types.d.ts

@@ -104,3 +104,34 @@ export type ProceduresFactory = {
     Create: (...args: any[]) => any;
     CreateStream?: (...args: any[]) => any;
 };
+export type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc;
+export interface DocSource<T = AnyHttpRouteDoc> {
+    readonly docs: T[];
+}
+export interface HeaderDoc {
+    name: string;
+    description?: string;
+    required?: boolean;
+    example?: string;
+}
+export interface ErrorDoc {
+    name: string;
+    statusCode: number;
+    description: string;
+    schema?: Record<string, unknown>;
+}
+export interface DocRegistryConfig {
+    basePath?: string;
+    headers?: HeaderDoc[];
+    errors?: ErrorDoc[];
+}
+export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {
+    filter?: (route: AnyHttpRouteDoc) => boolean;
+    transform?: (envelope: DocEnvelope) => TEnvelope;
+}
+export interface DocEnvelope {
+    basePath: string;
+    headers: HeaderDoc[];
+    errors: ErrorDoc[];
+    routes: AnyHttpRouteDoc[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
@@ -39,6 +39,10 @@
     "./hono-api": {
       "types": "./build/implementations/http/hono-api/index.d.ts",
       "import": "./build/implementations/http/hono-api/index.js"
+    },
+    "./http-docs": {
+      "types": "./build/implementations/http/doc-registry.d.ts",
+      "import": "./build/implementations/http/doc-registry.js"
     }
   },
   "author": "coryrobinson42@gmail.com",