@silkweave/nestjs 2.4.0 → 2.6.0

package/README.md

@@ -1,16 +1,30 @@
 # @silkweave/nestjs
 
-NestJS adapter for [Silkweave](https://github.com/silkweave/silkweave). Expose your **existing NestJS controllers** as MCP (Model Context Protocol) tools by adding a single `@Mcp()` decorator to a route handler. The tool's name, description, and input schema are **reflected** from the route, the `@Param`/`@Query`/`@Body` decorators, and any `@nestjs/swagger` / `class-validator` metadata the method already carries - nothing is re-declared. On a tool call the validated input is split back into the method's positional arguments and the handler is invoked directly, with `@UseGuards()` guards applied first.
+NestJS adapter for [Silkweave](https://github.com/silkweave/silkweave). Expose your **existing NestJS controllers** as MCP (Model Context Protocol) tools by adding a single `@Mcp()` decorator to a route handler - or as **end-to-end-typed tRPC procedures** with the sibling `@Trpc()` decorator. The name, description, and input schema are **reflected** from the route, the `@Param`/`@Query`/`@Body` decorators, and any `@nestjs/swagger` / `class-validator` metadata the method already carries - nothing is re-declared. On a call the validated input is split back into the method's positional arguments and the handler is invoked directly, with `@UseGuards()` guards applied first.
 
-It is **additive**: controllers keep serving HTTP exactly as before, and removing `@Mcp()` fully reverts a method.
+It is **additive**: controllers keep serving HTTP exactly as before, and removing the decorator fully reverts a method. The same method can carry both `@Mcp()` (for agents) and `@Trpc()` (for your frontend) alongside `@UseGuards()`.
 
 ## Install
 
 ```bash
 pnpm add @silkweave/core @silkweave/nestjs @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata
+
+# then add only the adapter packages you use (each is an optional peer):
+pnpm add @silkweave/mcp        # if you use mcp()
+pnpm add @silkweave/trpc       # if you use trpc()
+pnpm add @silkweave/typegen    # if you use typegen()
+```
+
+The adapters live behind **subpath exports** and their stacks are **optional peer dependencies**, so an MCP-only app never pulls in `@trpc/server`, and a tRPC-only app never pulls in the MCP SDK / OAuth stack. The decorators and module come from the root; each adapter from its subpath:
+
+```ts
+import { Mcp, Trpc, SilkweaveModule } from '@silkweave/nestjs'
+import { mcp } from '@silkweave/nestjs/mcp'
+import { trpc } from '@silkweave/nestjs/trpc'
+import { typegen } from '@silkweave/nestjs/typegen'
 ```
 
-`@nestjs/swagger` and `class-validator` are **optional** peers - install whichever your DTOs already use; the reflector reads both and falls back to TypeScript `design:type` when neither is present.
+`@nestjs/swagger` and `class-validator` are **optional** peers too - install whichever your DTOs already use; the reflector reads both and falls back to TypeScript `design:type` when neither is present.
 
 > NestJS needs decorator-aware transforms with `emitDecoratorMetadata`. Use `@swc-node/register` (`node --import @swc-node/register/esm-register src/main.ts`) or the `nest start` CLI; plain `tsx` does not emit decorator metadata.
 
@@ -70,7 +84,8 @@ export class UsersController {
 ```ts
 // app.module.ts
 import { Module } from '@nestjs/common'
-import { mcp, SilkweaveModule } from '@silkweave/nestjs'
+import { SilkweaveModule } from '@silkweave/nestjs'
+import { mcp } from '@silkweave/nestjs/mcp'
 import { AdminGuard } from './admin.guard.js'
 import { UsersController } from './users.controller.js'
 
@@ -115,7 +130,7 @@ Exposes the decorated controller route as an MCP tool. Every option is optional.
 |--------|------|---------|-------------|
 | `name` | `string` | `${ControllerBase}${MethodName}` (e.g. `UsersGet`) | MCP tool name override |
 | `description` | `string` | `@ApiOperation` summary/description, else generated | Tool description |
-| `input` | `Record<string, z.ZodType>` | - | Zod raw-shape override merged over the reflected fields (per-field). The escape hatch for shapes reflection can't express - discriminated unions, custom validators, `@Transform` |
+| `input` | `Record<string, z.ZodType> \| z.ZodObject` | - | Zod override merged over the reflected fields (per-field). A raw shape (`{ field: z.string() }`) **or** a whole `z.object({ ... })` (its `.shape` is unwrapped). The escape hatch for shapes reflection can't express - discriminated unions, custom validators, `@Transform`. It **adds to** the reflected fields; it does not replace them (see the warning below) |
 | `pipes` | `'apply' \| 'skip'` | `'apply'` | Whether to run parameter-bound pipes (`@Param('id', ParseIntPipe)`) when re-binding |
 | `result` | `'json' \| 'smart'` | `'smart'` | Default MCP result format - `'json'` returns compact JSON text (`jsonToolResult`); `'smart'` inlines small payloads and offloads large ones to an embedded resource (`smartToolResult`). A client that sends `_meta.disposition` on the call overrides it |
 
@@ -141,7 +156,7 @@ For each `@Mcp` method the adapter builds **one flat Zod input object** by mergi
 2. `class-validator` decorators (`@IsString`, `@MinLength`, `@IsOptional`, `@IsEnum`, ...) - **optional** peer
 3. `@nestjs/swagger` decorators - `@ApiParam`/`@ApiQuery` for scalar path/query params, `@ApiProperty` for whole-DTO properties - **optional** peer
 4. An ingested OpenAPI document, matched by HTTP verb + path (`SilkweaveModule.forRoot({ openapi })`)
-5. `@Mcp({ input })` raw-shape override
+5. `@Mcp({ input })` override (a raw shape or a `z.object({ ... })`)
 
 Field sources are derived from the parameter decorators:
 
@@ -153,10 +168,17 @@ Field sources are derived from the parameter decorators:
 | `@Query() dto: ListDto` | each property of `ListDto`, flattened to top level |
 | `@Body('x') x` | scalar field `x` |
 | `@Body() dto: CreateDto` | each property of `CreateDto`, flattened to top level |
-| `@Req`/`@Res`/`@Headers`/`@Ip`/`@Session`/files | not exposed; bound at call time (headers/req from the MCP request stand-in, the rest `undefined`) |
+| `@Req`/`@Headers`/`@Ip`/`@Session`/files | not exposed; bound at call time (headers/req from the MCP request stand-in, the rest `undefined`) |
+| `@Res() res` | not exposed; bound to the **real Express response over tRPC** (so `@Res({ passthrough: true })` can set cookies/headers), `undefined` over MCP (no HTTP response) |
 
 On a tool call the validated input is split back into the handler's positional arguments per the same parameter map, parameter-bound pipes run (unless `pipes: 'skip'`), and the method is invoked directly.
 
+> **Unreflectable parameter warning.** A whole-DTO `@Body()`/`@Query()` whose type can't be reflected logs a `Silkweave` warning at boot naming the controller method and parameter. The usual cause is an **intersection/union** type (e.g. `@Body() input: CreateDto & z.infer<typeof Extra>`): TypeScript erases it to `Object` under `design:type`, so the DTO class reference is lost and **none** of its `@ApiProperty`/`class-validator` fields reflect. A `@Mcp`/`@Trpc({ input })` override on the same method does **not** silence this - the override *adds* fields, it doesn't recover the dropped ones. Fix it by using a single DTO class, or by declaring every field via `({ input })`.
+
+### Nullable fields
+
+`@ApiProperty({ nullable: true })` (and OpenAPI `nullable: true`) reflect to a `.nullable()` Zod field (`string | null`). `class-validator`'s `@IsOptional()` only yields `string | undefined` (optional, not nullable) - it has no `null` signal - so for a `string | null` field add `@ApiProperty({ nullable: true })` or override the field via `({ input })`.
+
 ### Optional OpenAPI ingestion
 
 Pass a pre-built OpenAPI document (e.g. a committed `openapi.json`, or one built in a two-phase bootstrap) to use it as the authoritative schema source. It is matched to each `@Mcp` method by verb + path and overrides decorator reflection for the fields it covers; unmatched operations/fields fall back to reflection.
@@ -183,9 +205,133 @@ Mounts the MCP Streamable HTTP transport directly at `basePath`, with sideload (
 | `sideloadResources` | `boolean` | `true` | Mount `{basePath}/resource/:id` |
 | `resourceDir` | `string` | `'resources'` | Directory the sideload route reads from |
 
+## tRPC
+
+`@Trpc()` is the tRPC sibling of `@Mcp()`. It exposes a controller route as a tRPC procedure, reflecting its key, input, and kind from exactly the same sources `@Mcp` uses - so a single method can serve REST, MCP, and tRPC at once. Two things differ because tRPC consumers need them: **precise output types** in the generated router, and **subscriptions** for `async *` routes.
+
+```ts
+import { Mcp, Trpc } from '@silkweave/nestjs'
+import { ApiOkResponse, ApiOperation } from '@nestjs/swagger'
+
+class ListUsersResponse {
+  @ApiProperty({ type: [UserDto] }) users!: UserDto[]
+}
+
+@Controller('users')
+export class UsersController {
+  @Get('list-by-space')
+  @ApiOperation({ summary: 'List the users in a space' })
+  @ApiOkResponse({ type: ListUsersResponse })   // ← drives the generated output type
+  @UseGuards(AuthGuard)                          // ← reads the real Express request (cookies/headers)
+  @Trpc()                                        // → query  `usersListBySpace`
+  @Mcp()                                         // → MCP tool `UsersListBySpace`
+  listBySpace(@Query() q: ListBySpaceQuery, @Req() req: AppRequest) {
+    return this.users.listForSpace(req.user, q.spaceId)
+  }
+}
+```
+
+### `@Trpc(options?)` (method decorator)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | `${ControllerBase}.${MethodName}` | Procedure-name override (before camelCasing) |
+| `description` | `string` | `@ApiOperation` summary/description, else generated | Procedure description |
+| `input` | `Record<string, z.ZodType> \| z.ZodObject` | - | Zod override merged over reflected fields - a raw shape or a `z.object({ ... })` (same as `@Mcp({ input })`) |
+| `output` | `z.ZodType \| DtoClass \| Record<string, z.ZodType>` | reflected from `@ApiOkResponse` | Explicit output schema driving the generated output type (wins over reflection) |
+| `chunk` | `z.ZodType \| DtoClass` | `unknown` | Element type for a subscription's `async *` stream |
+| `kind` | `'query' \| 'mutation' \| 'subscription'` | inferred | `@Get` ⇒ query, others ⇒ mutation, `async *` ⇒ subscription |
+| `pipes` | `'apply' \| 'skip'` | `'apply'` | Whether to run parameter-bound pipes when re-binding |
+
+### Naming & kind
+
+Procedure keys are `camelCase(`${ControllerBase}.${MethodName}`)` - `UsersController.listBySpace` → `usersListBySpace` - matching the dotted-name → camelCase convention of the core tRPC adapter. Pin any exception with `@Trpc({ name })`. `kind` is inferred from the HTTP verb (`@Get` ⇒ `query`, otherwise `mutation`) or the method body (`async *` ⇒ `subscription`); override with `@Trpc({ kind })`.
+
+### Output types (the precise part)
+
+tRPC carries output types end-to-end, so the generated `AppRouter` needs them. In preference order:
+
+1. **`@ApiOkResponse({ type: Dto })`** (or any 2xx `@ApiResponse`) - the response DTO is flattened like an input DTO into the procedure's output type.
+2. **`@Trpc({ output })`** - an explicit Zod schema, DTO class, or raw shape. Wins over reflection. Use it when the return shape can't be reflected losslessly (e.g. **nested** DTOs and `Dto[]` arrays degrade to `unknown`/`unknown[]` - reflection is one level deep). For a precise nested shape, hand `@Trpc({ output })` a Zod schema.
+
+When a reflected output field degrades to `unknown`/`unknown[]`, the adapter logs a `Silkweave` warning at boot naming the controller method and the field(s) - so a silently-`unknown` grid/list/report output is visible instead of surfacing only at the client. The warning fires only for **reflected** outputs; an explicit `@Trpc({ output })` Zod schema is your own typing and is never flagged.
+
+### zod v3 / v4 interop
+
+The reflector builds schemas with Zod v4 internally, but `@Trpc({ input })`/`@Trpc({ output })`/`@Trpc({ chunk })` (and the `@Mcp({ input })` override) accept a schema from **either** Zod v3 or v4 - including `zod/v4` schemas from an app already migrated off Zod v3. The generated `AppRouter` input/output types resolve correctly across the boundary. Override detection is duck-typed (`safeParse`/`.shape`), so it does not depend on a shared Zod instance.
+
+### Subscriptions (`async *` ⇒ SSE)
+
+An `async *` method is registered as a tRPC **subscription** served over SSE. It needs no HTTP verb - a verb-less `@Trpc({ kind: 'subscription', chunk })` exposes it over tRPC **without** creating a public REST route (see [tRPC/MCP without REST](#trpcmcp-without-a-public-rest-route)). Guards run before the first chunk.
+
+```ts
+@Trpc({ kind: 'subscription', chunk: BoardTick })   // → subscription `usersWatch`
+async *watch(@Query() q: WatchQuery, @Req() req: AppRequest): AsyncGenerator<BoardTick> {
+  for await (const tick of this.board.stream(req.user, q)) { yield tick }
+}
+```
+
+### `trpc(options?)` adapter
+
+Mounts a single tRPC HTTP handler (httpBatch for queries/mutations, SSE for subscriptions) on Nest's HTTP adapter at `basePath`, built from every `@Trpc` route.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `basePath` | `string` | `'/trpc'` | URL prefix the handler mounts on |
+| `cors` | `CorsOptions \| boolean` | `true` | CORS. For cookie auth pass `{ origin: '<spa-origin>', credentials: true }` |
+| `auth` | `AuthConfig` | - | Optional transport-edge bearer validation. Usually omitted - `@Trpc` routes authenticate via their own `@UseGuards()` |
+
+**Guards + cookie auth, no separate config.** Each procedure runs the method's `@UseGuards()` first, with the guard receiving a real `ExecutionContext` whose `switchToHttp().getRequest()` is the **actual Express request** (cookies, headers, `req.user`). So an `AuthGuard` reading an HttpOnly session cookie works with no auth config - the client just sends `credentials: 'include'` / `withCredentials`. A denying guard surfaces to the client as a `TRPCError` whose `data.httpStatus` is the guard's HTTP status (e.g. `401`/`403`), so a `splitLink`/`errorLink` can react.
+
+Reach the authenticated principal + silkweave context from a handler with `@Req() req` (read `req.user`, set by the guard - works identically over REST, tRPC, and MCP).
+
+### `typegen(options?)` adapter
+
+On bootstrap, writes a `.ts` file containing the tRPC `AppRouter` type covering every `@Trpc` procedure - the exact `TRPCBuiltRouter` contract `createTRPCClient<AppRouter>()` and `inferRouterInputs`/`inferRouterOutputs` consume. It only sees `@Trpc` actions (MCP tools are gated out), so the emitted router matches what `trpc()` serves.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | `string` | - | Output file path (resolved against `process.cwd()`; parent dirs created) |
+| `format` | `'trpc-router' \| 'interfaces' \| 'all'` | `'trpc-router'` | `'trpc-router'` emits `AppRouter`; `'interfaces'` emits `{Name}Input`/`{Name}Output`; `'all'` both |
+
+```ts
+// app.module.ts
+import { SilkweaveModule } from '@silkweave/nestjs'
+import { mcp } from '@silkweave/nestjs/mcp'
+import { trpc } from '@silkweave/nestjs/trpc'
+import { typegen } from '@silkweave/nestjs/typegen'
+
+SilkweaveModule.forRoot({
+  silkweave: { name: 'my-app', description: 'My App', version: '1.0.0' },
+  adapters: [
+    mcp({ basePath: '/mcp', auth: mcpAuth }),         // @Mcp methods → MCP tools (bearer/OAuth)
+    trpc({ basePath: '/trpc' }),                      // @Trpc methods → tRPC procedures (cookie/guard auth)
+    typegen({ path: '../app/src/types/appRouter.ts' })// @Trpc procedures → AppRouter type
+  ]
+})
+```
+
+```ts
+// client - the emitted AppRouter is the only import you need
+import { createTRPCClient, httpBatchLink, httpSubscriptionLink, splitLink } from '@trpc/client'
+import type { AppRouter } from './types/appRouter.js'
+
+export const trpc = createTRPCClient<AppRouter>({
+  links: [splitLink({
+    condition: (op) => op.type === 'subscription',
+    true: httpSubscriptionLink({ url: '/trpc' }),               // SSE, withCredentials for cookies
+    false: httpBatchLink({ url: '/trpc', fetch: (u, o) => fetch(u, { ...o, credentials: 'include' }) })
+  })]
+})
+```
+
+### tRPC/MCP without a public REST route
+
+A `@Get`/`@Post` is inherently a public REST route. To expose a method over **tRPC and/or MCP only**, omit the HTTP-verb decorator: Nest never maps it as REST, and `@Trpc({ kind })` (or `@Mcp()`) still picks it up. This is how subscriptions (which are verb-less `async *` methods) and any internal-only procedure stay off the public REST surface.
+
 ## Guards & DI
 
-Native NestJS `@UseGuards()` on `@Mcp` methods run before the handler is invoked. Guards receive an `ExecutionContext` with the request in `switchToHttp().getRequest()`, and the `Reflector` is wired up so guards can read custom metadata.
+Native NestJS `@UseGuards()` on `@Mcp`/`@Trpc` methods run before the handler is invoked. Guards receive an `ExecutionContext` with the request in `switchToHttp().getRequest()`, and the `Reflector` is wired up so guards can read custom metadata.
 
 **Headers over MCP.** The inbound tool-call request is surfaced as a stand-in `{ headers, url, params, query }` object built from the MCP SDK's `extra.requestInfo`, so a header-based guard - e.g. one reading `getRequest().headers['x-api-key']` - works unchanged. `ExecutionContext.getType()` is `'http'` whenever a request is available (and `'rpc'` for transports with none, e.g. MCP stdio). Caveats:
 
@@ -217,7 +363,7 @@ Because the handler is invoked directly (not through Nest's HTTP request pipelin
 
 ## Notes
 
-- **Opt-in.** Only methods carrying `@Mcp()` are exposed - controllers are never auto-published.
+- **Opt-in.** Only methods carrying `@Mcp()`/`@Trpc()` are exposed - controllers are never auto-published.
 - **Express only by default.** `@nestjs/platform-fastify` requires `@fastify/express` registered upfront.
 - **`reflect-metadata`** must be imported once at the top of your entry file.
 

package/build/index-C1W-O7EX.d.mts

@@ -0,0 +1,46 @@
+import { SilkweaveContext } from "@silkweave/core";
+
+//#region ../auth/build/index.d.mts
+//#endregion
+//#region src/provider/types.d.ts
+interface AuthInfo {
+  token: string;
+  clientId?: string;
+  scopes?: string[];
+  expiresAt?: number;
+  [key: string]: unknown;
+}
+interface OAuthRequest {
+  method: string;
+  url: URL;
+  headers: Record<string, string | undefined>;
+  body?: Record<string, string>;
+}
+interface OAuthResponse {
+  status: number;
+  headers: Record<string, string>;
+  body?: string | Record<string, unknown>;
+}
+interface OAuthProvider {
+  authorize(req: OAuthRequest): Promise<OAuthResponse>;
+  callback(req: OAuthRequest): Promise<OAuthResponse>;
+  token(req: OAuthRequest): Promise<OAuthResponse>;
+  register(req: OAuthRequest): Promise<OAuthResponse>;
+  metadata(): OAuthResponse;
+  verifyToken(token: string): Promise<AuthInfo | undefined>;
+} //#endregion
+//#region src/types.d.ts
+type VerifyToken = (token: string, context: SilkweaveContext) => Promise<AuthInfo | undefined>;
+interface AuthConfig {
+  verifyToken: VerifyToken;
+  required?: boolean;
+  resourceUrl?: string;
+  authorizationServers?: string[];
+  requiredScopes?: string[];
+  provider?: OAuthProvider;
+  callbackPath?: string;
+} //#endregion
+//#region src/provider/store.d.ts
+//#endregion
+export { AuthConfig as t };
+//# sourceMappingURL=index-C1W-O7EX.d.mts.map

package/build/index-C1W-O7EX.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-C1W-O7EX.d.mts","names":["SilkweaveContext","AuthError","Error","code","statusCode","constructor","message","invalidToken","insufficientScope","extractBearerToken","header","buildWWWAuthenticate","error","description","resourceMetadataUrl","ProtectedResourceMetadata","resource","authorization_servers","scopes_supported","bearer_methods_supported","generateProtectedResourceMetadata","resourceUrl","authorizationServers","AuthInfo","token","clientId","scopes","expiresAt","key","OAuthRequest","URL","Record","method","url","headers","body","OAuthResponse","status","OAuthProvider","Promise","authorize","req","callback","register","metadata","verifyToken","VerifyToken","context","AuthConfig","required","requiredScopes","provider","callbackPath","AuthCodeData","redirectUri","codeChallenge","codeChallengeMethod","upstreamAccessToken","upstreamIdToken","email","sub","PendingAuthData","scope","clientState","ClientRegistration","clientSecret","redirectUris","clientName","createdAt","RefreshTokenData","OAuthStore","saveAuthCode","data","getAuthCode","deleteAuthCode","savePendingAuth","state","getPendingAuth","deletePendingAuth","savePkceVerifier","verifier","getPkceVerifier","deletePkceVerifier","saveClient","getClient","saveRefreshToken","getRefreshToken","deleteRefreshToken","GoogleOAuthOptions","signingKey","tokenTtl","store","google","options","OAuthProxyConfig","authorizeUrl","tokenUrl","userinfoUrl","createOAuthProxy","config","matchRedirectUri","uri","patterns","createJsonStore","path","createMemoryStore","RedisClient","get","set","value","ex","del","RedisStoreOptions","client","prefix","createRedisStore","ValidateResult","auth","error_description","validateToken","authorizationHeader"],"sources":["../../auth/build/index.d.mts"],"mappings":";;;;;UAyBUuB,QAAAA;EACRC,KAAAA;EACAC,QAAAA;EACAC,MAAAA;EACAC,SAAAA;EAAAA,CACCC,GAAAA;AAAAA;AAAAA,UAEOC,YAAAA;EACRG,MAAAA;EACAC,GAAAA,EAAKH,GAAAA;EACLI,OAAAA,EAASH,MAAAA;EACTI,IAAAA,GAAOJ,MAAAA;AAAAA;AAAAA,UAECK,aAAAA;EACRC,MAAAA;EACAH,OAAAA,EAASH,MAAAA;EACTI,IAAAA,YAAgBJ,MAAAA;AAAAA;AAAAA,UAERO,aAAAA;EACRE,SAAAA,CAAUC,GAAAA,EAAKZ,YAAAA,GAAeU,OAAAA,CAAQH,aAAAA;EACtCM,QAAAA,CAASD,GAAAA,EAAKZ,YAAAA,GAAeU,OAAAA,CAAQH,aAAAA;EACrCZ,KAAAA,CAAMiB,GAAAA,EAAKZ,YAAAA,GAAeU,OAAAA,CAAQH,aAAAA;EAClCO,QAAAA,CAASF,GAAAA,EAAKZ,YAAAA,GAAeU,OAAAA,CAAQH,aAAAA;EACrCQ,QAAAA,IAAYR,aAAAA;EACZS,WAAAA,CAAYrB,KAAAA,WAAgBe,OAAAA,CAAQhB,QAAAA;AAAAA;AAAAA;AAAAA,KAIjCuB,WAAAA,IAAetB,KAAAA,UAAeuB,OAAAA,EAAS/C,gBAAAA,KAAqBuC,OAAAA,CAAQhB,QAAAA;AAAAA,UAC/DyB,UAAAA;EACRH,WAAAA,EAAaC,WAAAA;EACbG,QAAAA;EACA5B,WAAAA;EACAC,oBAAAA;EACA4B,cAAAA;EACAC,QAAAA,GAAWb,aAAAA;EACXc,YAAAA;AAAAA;AAAAA"}