stitchkit 0.2.0 → 0.4.0

package/dist/server/multipart.d.ts

@@ -2,7 +2,8 @@ import type { ZodType } from 'zod';
 /** A parsed multipart request — the uploaded `file` and the validated `fields`. */
 export interface MultipartResult {
     file: File;
-    fields: Record<string, unknown>;
+    /** Validated when a `fieldsSchema` was given, else the raw decoded fields. */
+    fields: unknown;
 }
 /**
  * Parse a `multipart/form-data` request — extract the file at `fileField` and

package/dist/server/multipart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAGnC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAKD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,SAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CAkC1B"}
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AA0CD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,SAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CA6B1B"}

package/dist/server/node.d.ts

@@ -1,7 +1,16 @@
+import type { Server as HttpServer } from 'node:http';
 import type { HandlerConfig } from './types';
 export interface NodeServerConfig extends HandlerConfig {
     port?: number;
     hostname?: string;
+    /**
+     * A Socket.IO handle from `createSocketIOServer` — attached to the underlying
+     * `node:http.Server` (srvx `server.node.server`) once it is listening, so
+     * Socket.IO owns the HTTP `upgrade` event on the same port.
+     */
+    socket?: {
+        attach(server: HttpServer): void;
+    };
 }
 export interface NodeServerHandle {
     url: string;

package/dist/server/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/server/node.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBnF"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/server/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAGtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6BnF"}

package/dist/server/openapi.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OpenAPI 3.1 generation from contracts. A `defineContract` already carries the
+ * full type information — Zod `params` / `input` / `output`, `desc`, `method`,
+ * `path`, `scope` — so the spec is generated, not hand-maintained: the contract
+ * IS the spec. No decorators, no duplicated annotations. → ADR 0018.
+ *
+ * Schemas are converted through the same single `toJsonSchema` point the tool
+ * layer uses (and `jsonSchemaFields`, shared with the CLI `--help` walker), so
+ * the JSON Schema in the spec is the JSON Schema the rest of the framework
+ * emits — not a divergent code path. Schemas are inlined (valid OpenAPI);
+ * `$ref` de-duplication can come later if a spec grows unwieldy.
+ */
+import type { RawRoute, ServiceDef } from './types';
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+}
+export interface OpenApiServer {
+    url: string;
+    description?: string;
+}
+export interface OpenApiConfig {
+    info: OpenApiInfo;
+    /** Flat services, mounted at their own prefix. */
+    services?: ServiceDef[];
+    /** Grouped services, each mounted under a path prefix (mirrors `RouteGroup`). */
+    groups?: Array<{
+        pathPrefix?: string;
+        services: ServiceDef[];
+    }>;
+    /** `servers` block for the spec. */
+    servers?: OpenApiServer[];
+}
+export interface OpenApiDocument {
+    openapi: '3.1.0';
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    paths: Record<string, Record<string, unknown>>;
+}
+/**
+ * Generate an OpenAPI 3.1 document from contract services. Only methods exposed
+ * on HTTP are included — a method whose `expose` omits `'HTTP'` (an MCP/agent
+ * only tool) is skipped, matching the router's own route-building rule.
+ */
+export declare function generateOpenApiDocument(config: OpenApiConfig): OpenApiDocument;
+/**
+ * A `RawRoute` that serves a generated OpenAPI document as JSON — mount it
+ * alongside contract routes to expose `/openapi.json`.
+ */
+export declare function openApiRoute(path: string, document: OpenApiDocument): RawRoute;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/server/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAgH9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}

package/dist/server/rate-limit.d.ts

@@ -6,8 +6,13 @@ export interface RateLimitConfig {
 /**
  * In-memory token-bucket rate limiter. `check(key, config)` consumes a token
  * and returns whether the request is allowed; `remaining(key, config)` reports
- * the count without consuming. Idle keys are swept on a 60-second timer;
- * `destroy()` stops it.
+ * the count without consuming. Idle keys are swept on a 60-second timer and the
+ * map is capped at `MAX_BUCKETS` (least-recently-used eviction); `destroy()`
+ * stops the timer.
+ *
+ * `config` is per-call — reusing one `key` with two different configs lets
+ * whichever call created the bucket fix its `max` / `window`. Key a bucket to
+ * one config (one limiter per limit) if that matters.
  */
 export declare function createRateLimiter(): {
     destroy: () => void;

package/dist/server/rate-limit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/server/rate-limit.ts"],"names":[],"mappings":"AAOA,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB;;eAQlB,MAAM,UAAU,eAAe,GAAG,OAAO;mBAiBrC,MAAM,UAAU,eAAe,GAAG,MAAM;EAO1D"}
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/server/rate-limit.ts"],"names":[],"mappings":"AAOA,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB;;eAQlB,MAAM,UAAU,eAAe,GAAG,OAAO;mBA6BrC,MAAM,UAAU,eAAe,GAAG,MAAM;EAO1D"}

package/dist/server/request.d.ts

@@ -2,7 +2,7 @@
  * HTTP request helpers — header parsing, client identification, trace ids.
  * Pure `Request → value` functions; no framework state.
  */
-/** Compact, time-sortable id — base36 timestamp + base36 random, ~14 chars. */
+/** Compact, time-sortable id — base36 timestamp + a cryptographic suffix. */
 export declare function generateTraceId(): string;
 /**
  * Trace id for a request: a trusted inbound `x-request-id` / `x-trace-id`
@@ -10,10 +10,33 @@ export declare function generateTraceId(): string;
  * Shared by the router, the logger and any consumer that wants the same id.
  */
 export declare function resolveTraceId(req: Request): string;
-/** Client IP from `x-forwarded-for` / `x-real-ip` (IPv4-mapped prefix stripped). */
-export declare function extractIp(req: Request): string;
+/**
+ * Resolve the real socket peer IP from the runtime — unspoofable, unlike a
+ * header. On Bun the server resolves it (`server.requestIP`); on Node / Deno
+ * the `srvx` adapter attaches `.ip` to the request. `undefined` when neither
+ * is available (the bare `createHandler` fetch with no server).
+ */
+export declare function resolveSocketIp(req: Request, server: unknown): string | undefined;
+/** Options for `extractIp` / `getClientInfo`. */
+export interface ClientIpOptions {
+    /**
+     * Trust `x-forwarded-for` / `x-real-ip` for the client IP. Enable only behind
+     * a proxy that overwrites them — they are client-controllable. Default
+     * `false`: the real socket IP (`socketIp`) is used instead.
+     */
+    trustProxy?: boolean;
+    /** The real socket peer IP — see `resolveSocketIp`. */
+    socketIp?: string;
+}
+/**
+ * The client IP for a request. With `trustProxy`, the `x-forwarded-for` /
+ * `x-real-ip` client wins (the server sits behind a proxy that rewrites them);
+ * otherwise the real, unspoofable socket peer (`socketIp`) is used. Returns
+ * `''` when nothing is known.
+ */
+export declare function extractIp(req: Request, options?: ClientIpOptions): string;
 /** Client identity — IP + user-agent. The one place projects derive both. */
-export declare function getClientInfo(req: Request): {
+export declare function getClientInfo(req: Request, options?: ClientIpOptions): {
     ipAddress?: string;
     userAgent?: string;
 };

package/dist/server/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CASnD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAM9C;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAKA;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAQ5E"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAejF;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAQ7E;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,eAAoB,GAC5B;IACD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAKA;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAU5E"}

package/dist/server/router.d.ts

@@ -34,8 +34,10 @@ export declare function matchRawRoute(rawRoutes: RawRoute[], httpMethod: string,
     params: Record<string, string>;
 } | null;
 /**
- * Build a `RawRoute` that serves files from `dir` under `prefix`.
- * Rejects path traversal (`..`); 404 for a missing file.
+ * Build a `RawRoute` that serves files from `dir` under `prefix`. Basic by
+ * design — no Range, no conditional requests; put a CDN in front for those.
+ * Rejects path traversal (including the percent-encoded form); 404 for a
+ * missing file. Uses `node:fs`, so it runs on both Bun and Node.
  */
 export declare function staticRoute(prefix: string, dir: string): RawRoute;
 export {};

package/dist/server/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAqCD,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAmCjE;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,IAAI,CAmBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc7E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAiBvD;AAID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,QAAQ,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAyB5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAuBjE"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAqCD,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAmCjE;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,IAAI,CAmBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc7E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAiBvD;AAID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,QAAQ,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAyB5D;AAoBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAmCjE"}

package/dist/server/socket-io.d.ts

@@ -1,20 +1,26 @@
 /**
- * Socket.IO server setup — the family WebSocket server boilerplate.
+ * Socket.IO server setup — the family WebSocket server boilerplate, runtime-aware.
  *
- * Every project repeats the same wiring: `new SocketIOServer(...)`, a
- * `@socket.io/bun-engine` instance, `io.bind(engine)`, `engine.handler()` for
- * the `Bun.serve` `websocket` field, and an `/socket.io/*` route delegating to
- * `engine.handleRequest`. `createSocketIOServer` is exactly that wiring.
+ * The engine differs per runtime, so the socket packages are loaded **lazily**
+ * (dynamic `import` inside the function) — a `type`-only import at the top would
+ * still be erased, but a top-level *value* import of `@socket.io/bun-engine`
+ * (Bun-only) would crash the whole `stitchkit/server` barrel on Node before any
+ * socket code runs. Lazy loading keeps the barrel Node-importable for apps that
+ * never use sockets.
  *
- * Connection handlers, rooms and handshake auth stay in the project — they are
- * domain logic. This helper owns only the transport plumbing: it returns the
- * typed `io` to attach handlers to, the `websocket` handler for `Bun.serve`,
- * and a ready-made `route` to drop into `createServer({ rawRoutes })`.
+ *  - **Bun** — `@socket.io/bun-engine` + `io.bind(engine)`; returns the
+ *    `websocket` handler for `Bun.serve` and a `/socket.io/*` route.
+ *  - **Node** — `io.attach(server)` onto the `node:http.Server` exposed by
+ *    `serveNode` (srvx `server.node.server`); Socket.IO owns the `upgrade` event.
+ *
+ * Connection handlers, rooms and handshake auth stay in the project.
  */
-import { Server as BunEngine } from '@socket.io/bun-engine';
-import { Server as SocketIOServer } from 'socket.io';
+import type { Server as HttpServer } from 'node:http';
+import type { Server as BunEngine } from '@socket.io/bun-engine';
+import type { Server as SocketIOServer } from 'socket.io';
 import type { SocketEventMap } from '../browser/socket-io';
 import type { RawRoute } from './types';
+import { type ComposedLane } from './websocket';
 export interface SocketIOServerConfig {
     /** CORS — the browser origin(s) allowed to open a socket. */
     cors: {
@@ -23,7 +29,13 @@ export interface SocketIOServerConfig {
     };
     /** Socket.IO endpoint path. Default `/socket.io/`. */
     path?: string;
-    /** Transports offered to clients. Default `['websocket', 'polling']`. */
+    /**
+     * Transports offered to clients. Default `['websocket', 'polling']` on Bun;
+     * on Node the default is `['websocket']` — Socket.IO shares the HTTP server
+     * with srvx there, so its polling request-handler would collide with srvx's;
+     * WebSocket uses the separate `upgrade` event and does not. Configure the
+     * client with `transports: ['websocket']` to match.
+     */
     transports?: Array<'websocket' | 'polling'>;
     /** Heartbeat: ms without a pong before the connection is dropped. Default `20000`. */
     pingTimeout?: number;
@@ -33,10 +45,43 @@ export interface SocketIOServerConfig {
 export interface SocketIOServerHandle<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap> {
     /** The typed Socket.IO server — attach `io.on('connection', ...)` handlers. */
     io: SocketIOServer<TClientEvents, TServerEvents>;
-    /** WebSocket handler for `Bun.serve({ websocket })`. */
+    /**
+     * WebSocket handler for `Bun.serve({ websocket })`. Real on Bun; on Node it is
+     * an inert no-op — sockets there are driven by the `node:http.Server`
+     * `upgrade` event via `serveNode({ socket })`, never by this field — so a Bun
+     * consumer can pass it unconditionally without a runtime guard.
+     */
     websocket: ReturnType<BunEngine['handler']>['websocket'];
-    /** Ready `/socket.io/*` route — drop into `createServer({ rawRoutes })`. */
+    /**
+     * `/socket.io/*` route for `createServer({ rawRoutes })`. Real on Bun; on Node
+     * it is unused (sockets attach to the http.Server via `serveNode({ socket })`)
+     * and throws if it is ever mounted — so it is safe to spread into `rawRoutes`
+     * unconditionally on either runtime.
+     */
     route: RawRoute;
+    /**
+     * Node only — attach the Socket.IO server to the `node:http.Server` from
+     * `serveNode`. A no-op on Bun (the engine + route handle transport there).
+     * `serveNode({ socket })` calls this for you.
+     */
+    attach(server: HttpServer): void;
 }
-export declare function createSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOServerConfig): SocketIOServerHandle<TServerEvents, TClientEvents>;
+export declare function createSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOServerConfig): Promise<SocketIOServerHandle<TServerEvents, TClientEvents>>;
+/**
+ * Wrap a Socket.IO handle's `websocket` as a catch-all {@link ComposedLane} for
+ * {@link composeWebSocketHandlers} — when a second, raw WebSocket lane shares
+ * the one `Bun.serve` websocket handler. It claims every socket no earlier
+ * (raw-marker) lane matched, so the engine owns whatever the raw lanes did not
+ * — and it never inspects the engine's opaque `ws.data`. Place it **last**.
+ *
+ * ```ts
+ * const ws = composeWebSocketHandlers([
+ *   webSocketLane({ match: isPcmSocket, handlers: pcmHandlers }),
+ *   socketIoLane(socket.websocket),
+ * ])
+ * ```
+ *
+ * Bun-only (so is the raw-lane composition it serves).
+ */
+export declare function socketIoLane(websocket: SocketIOServerHandle<SocketEventMap, SocketEventMap>['websocket']): ComposedLane;
 //# sourceMappingURL=socket-io.d.ts.map

package/dist/server/socket-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/server/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3D,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CACnC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,+EAA+E;IAC/E,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IACjD,wDAAwD;IACxD,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzD,4EAA4E;IAC5E,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,wBAAgB,oBAAoB,CAClC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,CAqClF"}
+{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/server/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3D,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CACnC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,+EAA+E;IAC/E,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IACjD;;;;;OAKG;IACH,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzD;;;;;OAKG;IACH,KAAK,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAOD,wBAAsB,oBAAoB,CACxC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CA8D3F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,oBAAoB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,WAAW,CAAC,GAC3E,YAAY,CAMd"}

package/dist/server/stream.d.ts

@@ -1,7 +1,9 @@
 /**
  * Turn an async generator into a Server-Sent Events `Response` — each yielded
  * value is one JSON `data:` event, the stream ends with a `[DONE]` sentinel,
- * and a thrown error is emitted as a final `{ error }` event.
+ * and a thrown error is emitted as a final error event. The error is
+ * normalised (`normalizeError`) so an internal failure never leaks its raw
+ * message into the stream.
  */
 export declare function streamSSE(generator: AsyncGenerator<unknown>): Response;
 /** Options for `parseSSE`. */

package/dist/server/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/server/stream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,QAAQ,CA2BtE;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,CAAC,CAAC,CAkCnB"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/server/stream.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,QAAQ,CA2BtE;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,CAAC,CAAC,CAmCnB"}

package/dist/server/types.d.ts

@@ -1,5 +1,5 @@
 import type { ZodType } from 'zod';
-import type { EndpointDef, HandlerContext, HttpMethod, RuntimeContext, Transport } from '../contract';
+import type { EndpointDef, EndpointToolAnnotations, EndpointUiMeta, HandlerContext, HttpMethod, RuntimeContext, Transport } from '../contract';
 import type { CorsConfig } from './middleware/cors';
 type Prop<T, K extends string> = K extends keyof T ? T[K] : undefined;
 type InferParams<E> = Prop<E, 'params'> extends ZodType<infer P> ? P : undefined;
@@ -22,6 +22,10 @@ export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknow
     inputSchema?: ZodType<TInput>;
     outputSchema?: ZodType<TOutput>;
     multipart?: string;
+    /** MCP Apps widget metadata — carried onto the MCP tool's `_meta.ui`. */
+    ui?: EndpointUiMeta;
+    /** MCP behavioural hints — carried onto the MCP tool's `annotations`. */
+    annotations?: EndpointToolAnnotations;
     handler: (ctx: RuntimeContext) => Promise<TOutput> | TOutput;
 }
 export interface ServiceDef {
@@ -61,6 +65,11 @@ export interface RawRouteContext {
      * Absent when the handler runs via the bare `createHandler` fetch.
      */
     server?: BunServer;
+    /**
+     * Client IP — the real socket peer, or the `x-forwarded-for` client when
+     * `trustProxy` is set. Resolved by the framework; never spoofable by default.
+     */
+    ipAddress?: string;
 }
 export interface RawRoute {
     method: HttpMethod | 'ALL';
@@ -91,6 +100,13 @@ export interface HandlerConfig {
     hooks?: LifecycleHooks;
     logging?: boolean | StitchLogger;
     traceId?: (req: Request) => string;
+    /**
+     * Trust the `x-forwarded-for` / `x-real-ip` headers for the client IP.
+     * These are client-controllable — enable only when the server runs behind a
+     * proxy that overwrites them. Default `false`: the IP a spoofable header
+     * carries never reaches `ctx.ipAddress`, a rate-limit key or an audit row.
+     */
+    trustProxy?: boolean;
 }
 type BunServeOptions = Parameters<typeof Bun.serve>[0];
 type BunWebSocketHandlers = BunServeOptions extends {

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,UAAU,EACV,cAAc,EACd,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;AACtE,KAAK,WAAW,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;AACjF,KAAK,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;AAC/E,KAAK,WAAW,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7E,MAAM,MAAM,QAAQ,CAClB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,IAAI,SAAS,cAAc,GAAG,cAAc,IAC1C;KACD,CAAC,IAAI,MAAM,CAAC,GAAG,CACd,GAAG,EAAE,IAAI,GAAG;QAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,KAC/D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,SAAS,OAAO,GACrC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC9C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,SAAS,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC/E,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC9D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC,CAAC;IACnF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,CACR,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,SAAS,KACjB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AAErD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,UAAU,GAAG,KAAK,CAAC;IAC3B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACjC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACnC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,eAAe,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AACxF,KAAK,SAAS,GAAG,eAAe,SAAS;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAC1E,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxC,CAAC"}

package/dist/server/websocket.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Compose one Bun `websocket` handler from several independent lanes.
+ *
+ * `Bun.serve` accepts a **single** `websocket` handler. `@socket.io/bun-engine`
+ * claims it (via `createSocketIOServer().websocket`). A project that also wants a
+ * second, truly-raw binary WebSocket lane on the same server — a high-frequency
+ * stream (PCM, video, large transfers) with no Socket.IO framing — has to
+ * hand-compose that one handler: route each socket to the engine or to its own
+ * raw handlers.
+ *
+ * The fragile part is the discriminator. Routing *to* Socket.IO means asking
+ * "is this an engine socket?", which forces inspecting the engine's opaque
+ * `ws.data` — a brittle guard, hard to keep cast-free. The fix here is to invert
+ * it: a raw lane stamps **its own** marker onto `ws.data` at upgrade time and is
+ * matched positively; Socket.IO is simply the **fallback** lane (matched last,
+ * `() => true`). The engine's data is therefore never inspected.
+ *
+ * Cast-free: each lane carries a type-predicate `match` that narrows
+ * `ServerWebSocket<unknown>` to its own data type, so the typed handlers are
+ * invoked without a single `as`.
+ *
+ * Bun-only. On Node, Socket.IO drives sockets through the `node:http.Server`
+ * `upgrade` event (`serveNode({ socket })`) — a different model, and a raw lane
+ * there would be a separate upgrade handler, not this composition.
+ */
+import type { ServerWebSocket, WebSocketHandler } from 'bun';
+/** One lane of a composed handler — a typed slice of the single Bun websocket. */
+export interface WebSocketLane<TData> {
+    /**
+     * Type-predicate selecting the sockets this lane owns — usually a check on
+     * `ws.data` set at upgrade. As a predicate it narrows `ws` to the lane's data
+     * type, which is what keeps the handler call cast-free.
+     */
+    match: (ws: ServerWebSocket<unknown>) => ws is ServerWebSocket<TData>;
+    /** Handlers for this lane's sockets — `ws.data` is fully typed as `TData`. */
+    handlers: WebSocketHandler<TData>;
+}
+/** A lane already bridged to the loose (`unknown`) data type, ready to compose. */
+export interface ComposedLane {
+    match: (ws: ServerWebSocket<unknown>) => boolean;
+    handlers: WebSocketHandler<unknown>;
+}
+/**
+ * Server-wide WebSocket tuning for the composed handler. Bun applies these to
+ * every socket on the server (they cannot be per-lane), so set them to the most
+ * permissive value across lanes — a raw binary lane typically needs a larger
+ * `maxPayloadLength` than Socket.IO's default (its `maxHttpBufferSize`, 1 MB).
+ */
+export type WebSocketComposeConfig = Omit<WebSocketHandler<unknown>, 'open' | 'message' | 'close' | 'drain' | 'ping' | 'pong'>;
+/**
+ * Build a `ComposedLane` from typed handlers. Each callback is wrapped so it
+ * fires only for sockets the lane's `match` predicate claims — narrowing `ws`
+ * to `ServerWebSocket<TData>` for the typed handler. This is the one bridge from
+ * Bun's single untyped `websocket` to a typed, per-lane handler, and it holds
+ * no casts.
+ */
+export declare function webSocketLane<TData>(lane: WebSocketLane<TData>): ComposedLane;
+/**
+ * Compose lanes into the single `websocket` handler for `createServer`. On each
+ * callback the first lane whose `match` claims the socket handles it — so put
+ * specific lanes (raw markers) first and the catch-all (Socket.IO,
+ * `socketIoLane`) last. `config` carries the server-wide tuning.
+ *
+ * ```ts
+ * const ws = composeWebSocketHandlers(
+ *   [webSocketLane({ match: isPcmSocket, handlers: pcmHandlers }), socketIoLane(socket.websocket)],
+ *   { maxPayloadLength: 16 * 1024 * 1024 },
+ * )
+ * createServer({ websocket: ws, rawRoutes: [socket.route, pcmUpgradeRoute] })
+ * ```
+ */
+export declare function composeWebSocketHandlers(lanes: ComposedLane[], config?: WebSocketComposeConfig): WebSocketHandler<unknown>;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/server/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/server/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAE7D,kFAAkF;AAClF,MAAM,WAAW,aAAa,CAAC,KAAK;IAClC;;;;OAIG;IACH,KAAK,EAAE,CAAC,EAAE,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IACtE,8EAA8E;IAC9E,QAAQ,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;CACnC;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,EAAE,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;IACjD,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,gBAAgB,CAAC,OAAO,CAAC,EACzB,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CACzD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,YAAY,CAyB7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,YAAY,EAAE,EACrB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,gBAAgB,CAAC,OAAO,CAAC,CAyB3B"}

package/dist/tools/cli-args.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Turn a CLI `argv` slice into the flat argument object `executeToolMethod`
+ * parses — the CLI transport's front half, the counterpart of how the HTTP
+ * transport slices a `Request`.
+ *
+ * Two jobs the other transports never face:
+ *  1. **Reserved options.** `--json`, `--wait`, `--output-dir`, … are CLI
+ *     behaviour, not tool arguments — they are stripped before the rest is read
+ *     as tool args.
+ *  2. **String → typed coercion.** Every argv token is a string; the tool's Zod
+ *     schema says what each field should be. We coerce primitives here
+ *     (`--count 5` → `5`, `--flag` → `true`) and leave array / object values as
+ *     strings for `executeToolMethod`'s `coerceJson` pass (the same path the MCP
+ *     transport uses for an LLM's double-serialized JSON).
+ *
+ * The advertised schema is never mutated — coercion operates on the arguments,
+ * so a CLI call validates against the exact same contract schema an HTTP or MCP
+ * call does (ADR 0014 parity).
+ */
+import { z } from 'zod';
+/** CLI-behaviour flags, parsed out of argv before the tool arguments. */
+export interface CliRunOptions {
+    /** `--json` — emit raw JSON on stdout for piping. */
+    json: boolean;
+    /** `--wait` — block-poll an async result to a terminal state. */
+    wait: boolean;
+    /** `--wait-timeout <seconds>` — override the poll timeout. */
+    waitTimeout?: number;
+    /** `--output-dir <dir>` — download result media into this directory. */
+    outputDir?: string;
+    /** `--quiet` — suppress non-essential stderr chatter. */
+    quiet: boolean;
+    /** `--dry-run` — print the resolved call instead of executing it. */
+    dryRun: boolean;
+    /** `--help` / `-h` — print usage for the command. */
+    help: boolean;
+}
+export interface ParsedCliArgs {
+    /** The flat tool-argument object handed to `executeToolMethod`. */
+    toolArgs: Record<string, unknown>;
+    /** The CLI-behaviour flags. */
+    options: CliRunOptions;
+}
+type FieldKind = 'boolean' | 'number' | 'bigint' | 'date' | 'string' | 'enum' | 'array' | 'object' | 'other';
+interface FieldInfo {
+    kind: FieldKind;
+    /** Element kind for an `array` field — drives per-element coercion. */
+    elementKind?: FieldKind;
+}
+/**
+ * Map a merged tool schema to per-field kind info — what each `--flag` should
+ * coerce to. A non-object schema (a union) yields an empty map: every value is
+ * left as a string and the schema validates it.
+ */
+export declare function describeSchemaFields(schema: z.ZodType | undefined): Map<string, FieldInfo>;
+/**
+ * Parse a command's argv slice (everything after the command name) against its
+ * merged tool schema.
+ *
+ * Supported forms:
+ *  - `--key value` / `--key=value` / `-` repeated for arrays
+ *  - `--flag` boolean presence, `--no-flag` to negate
+ *  - `--a.b=c` dotted path → nested object (loose-coerced leaf)
+ *  - positional args fill non-boolean fields in schema-declaration order
+ */
+export declare function parseCliArgs(argv: string[], schema: z.ZodType | undefined): ParsedCliArgs;
+export {};
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/tools/cli-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/tools/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,KAAK,SAAS,GACV,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,UAAU,SAAS;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AA6BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAa1F;AAmFD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,aAAa,CAkIzF"}

package/dist/tools/cli-format.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Render a `ToolResult` for the CLI surface and map it to a process exit code.
+ *
+ * Output is JSON — the CLI's audience is agents (Skills via Bash), scripts and
+ * `| jq`, for which structured JSON is the right shape, not a hand-formatted
+ * table. The default is pretty-printed (indented, the same shape an MCP tool
+ * returns); `--json` switches to a compact single line for piping.
+ *
+ * stdout is reserved for that result; an error goes to stderr as the same
+ * model-facing `{ error, details, _hint }` object the MCP / agent transports
+ * return (`formatToolError`), so a script can keep `2>/dev/null` clean while
+ * still parsing a success.
+ */
+import type { ToolResult } from './execute';
+/** Map a `ToolResult.code` to a process exit code. */
+export type ExitCodeMap = Record<string, number>;
+/**
+ * Conventional exit codes — `0` success, distinct non-zero per error class so a
+ * script can branch on `$?`. Merged under any `CliConfig.exitCodes` override.
+ */
+export declare const DEFAULT_EXIT_CODES: ExitCodeMap;
+export interface CliWriters {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export interface EmitOptions {
+    /** Compact single-line JSON (for `| jq` / scripts); otherwise pretty-printed. */
+    json: boolean;
+    toolName: string;
+    errorHint?: (toolName: string, errorCode: string) => string | null;
+    exitCodes?: ExitCodeMap;
+}
+/**
+ * Write a result to the right stream and return the exit code. Success → JSON
+ * on stdout (pretty by default, compact with `--json`), exit `0`. Failure → the
+ * error JSON on stderr, exit per the code map (unknown code → `1`).
+ */
+export declare function emitResult(result: ToolResult, writers: CliWriters, opts: EmitOptions): number;
+//# sourceMappingURL=cli-format.d.ts.map

package/dist/tools/cli-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-format.d.ts","sourceRoot":"","sources":["../../src/tools/cli-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAUhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnE,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR"}