@silkweave/nestjs 1.11.0 → 2.0.0

package/.turbo/turbo-build.log

@@ -1,17 +1,16 @@
-$ tsdown
-ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
-ℹ config file: /Users/atomic/projects/silkweave/silkweave/packages/nestjs/tsdown.config.ts 
-ℹ entry: src/index.ts
-ℹ tsconfig: tsconfig.json
-ℹ Build start
-ℹ Cleaning 4 files
-ℹ Hint: consider adding deps.onlyBundle option to avoid unintended bundling of dependencies, or set deps.onlyBundle: false to disable this hint.
-See more at https://tsdown.dev/options/dependencies#deps-onlybundle
-Detected dependencies in bundle:
-- rxjs
-ℹ build/index.mjs        338.49 kB │ gzip: 49.77 kB
-ℹ build/index.mjs.map    577.61 kB │ gzip: 87.77 kB
-ℹ build/index.d.mts.map    2.99 kB │ gzip:  1.07 kB
-ℹ build/index.d.mts       16.35 kB │ gzip:  5.75 kB
-ℹ 4 files, total: 935.45 kB
-✔ Build complete in 742ms
+$ tsdown
+ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
+ℹ config file: /Users/atomic/projects/silkweave/silkweave/packages/nestjs/tsdown.config.ts 
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ Hint: consider adding deps.onlyBundle option to avoid unintended bundling of dependencies, or set deps.onlyBundle: false to disable this hint.
+See more at https://tsdown.dev/options/dependencies#deps-onlybundle
+Detected dependencies in bundle:
+- rxjs
+ℹ build/index.mjs        339.14 kB │ gzip: 49.99 kB
+ℹ build/index.mjs.map    579.22 kB │ gzip: 88.28 kB
+ℹ build/index.d.mts.map    3.06 kB │ gzip:  1.10 kB
+ℹ build/index.d.mts       17.08 kB │ gzip:  6.02 kB
+ℹ 4 files, total: 938.50 kB
+✔ Build complete in 1034ms

package/.turbo/turbo-prepack.log

@@ -1,5 +1,4 @@
-
-$ pnpm clean && pnpm build
+$ pnpm clean && pnpm build
 $ rimraf build
 $ tsdown
 ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
@@ -11,9 +10,9 @@
 See more at https://tsdown.dev/options/dependencies#deps-onlybundle
 Detected dependencies in bundle:
 - rxjs
-ℹ build/index.mjs        337.92 kB │ gzip: 49.52 kB
-ℹ build/index.mjs.map    576.49 kB │ gzip: 87.36 kB
-ℹ build/index.d.mts.map    2.98 kB │ gzip:  1.07 kB
-ℹ build/index.d.mts       15.96 kB │ gzip:  5.58 kB
-ℹ 4 files, total: 933.34 kB
-✔ Build complete in 828ms
+ℹ build/index.mjs        344.18 kB │ gzip: 51.78 kB
+ℹ build/index.mjs.map    589.05 kB │ gzip: 91.22 kB
+ℹ build/index.d.mts.map    3.45 kB │ gzip:  1.22 kB
+ℹ build/index.d.mts       20.10 kB │ gzip:  6.89 kB
+ℹ 4 files, total: 956.79 kB
+✔ Build complete in 822ms

package/README.md

@@ -1,6 +1,8 @@
 # @silkweave/nestjs
 
-NestJS adapter for [Silkweave](https://github.com/silkweave/silkweave). Define actions as method decorators on Nest providers, then expose them simultaneously over REST, tRPC, and MCP Streamable HTTP - all mounted on the running Nest HTTP server so Nest middleware, guards, and lifecycle hooks stay coherent.
+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.
+
+It is **additive**: controllers keep serving HTTP exactly as before, and removing `@Mcp()` fully reverts a method.
 
 ## Install
 
@@ -8,52 +10,59 @@ NestJS adapter for [Silkweave](https://github.com/silkweave/silkweave). Define a
 pnpm add @silkweave/core @silkweave/nestjs @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata
 ```
 
-> NestJS dev workflows need decorator-aware transforms. Recommend `@swc-node/register` (`node --import @swc-node/register/esm-register src/main.ts`) or the standard `nest start` CLI; plain `tsx` doesn't emit decorator metadata.
+`@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 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.
 
 ## Usage
 
 ```ts
-// users.actions.ts
-import { Injectable, UseGuards } from '@nestjs/common'
-import { type SilkweaveContext } from '@silkweave/core'
-import { Action, Actions } from '@silkweave/nestjs'
-import z from 'zod/v4'
+// users.controller.ts
+import { Body, Controller, Get, NotFoundException, Param, Post, Query, UseGuards } from '@nestjs/common'
+import { ApiOperation, ApiParam, ApiProperty, ApiQuery } from '@nestjs/swagger'
+import { Mcp } from '@silkweave/nestjs'
+import { IsBoolean, IsOptional, IsString, MinLength } from 'class-validator'
 import { AdminGuard } from './admin.guard.js'
 
-const ListInput = z.object({ activeOnly: z.coerce.boolean().optional() })
-const GetInput = z.object({ id: z.string() })
-const BanInput = z.object({ id: z.string(), reason: z.string() })
+class BanUserDto {
+  @ApiProperty({ description: 'Reason for the ban' })
+  @IsString() @MinLength(3)
+  reason!: string
+
+  @ApiProperty({ description: 'Whether the ban is permanent', required: false })
+  @IsOptional() @IsBoolean()
+  permanent?: boolean
+}
 
-@Injectable()
-@Actions('users')
-export class UserActions {
+@Controller('users')
+export class UsersController {
   constructor(private readonly db: DbService) {}
 
-  @Action({
-    description: 'List users',
-    input: ListInput,
-    kind: 'query'
-  })
-  list(input: z.infer<typeof ListInput>, _ctx: SilkweaveContext) {
-    return this.db.listUsers(input.activeOnly)
+  @Get()
+  @ApiOperation({ summary: 'List users' })
+  @ApiQuery({ name: 'activeOnly', required: false, type: Boolean, description: 'Only active users' })
+  @Mcp()
+  list(@Query('activeOnly') activeOnly?: boolean) {
+    return this.db.listUsers(activeOnly)
   }
 
-  @Action({
-    description: 'Get a single user by ID',
-    input: GetInput,
-    kind: 'query'
-  })
-  get(input: z.infer<typeof GetInput>) {
-    return this.db.getUser(input.id)
+  @Get(':id')
+  @ApiOperation({ summary: 'Get a single user by ID' })
+  @ApiParam({ name: 'id', description: 'User ID' })
+  @Mcp()
+  get(@Param('id') id: string) {
+    const user = this.db.getUser(id)
+    if (!user) { throw new NotFoundException('user not found') }
+    return user
   }
 
-  @UseGuards(AdminGuard)            // guard reads the request header on every transport, MCP included
-  @Action({
-    description: 'Ban a user',
-    input: BanInput
-  })
-  ban(input: z.infer<typeof BanInput>) {
-    return this.db.banUser(input.id, input.reason)
+  @Post(':id/ban')
+  @ApiOperation({ summary: 'Ban a user' })
+  @ApiParam({ name: 'id', description: 'User ID' })
+  @UseGuards(AdminGuard)                 // runs on every transport, MCP included
+  @Mcp({ description: 'Ban a user (admin only).' })
+  ban(@Param('id') id: string, @Body() body: BanUserDto) {
+    return this.db.banUser(id, body.reason, body.permanent ?? false)
   }
 }
 ```
@@ -61,22 +70,19 @@ export class UserActions {
 ```ts
 // app.module.ts
 import { Module } from '@nestjs/common'
-import { mcp, rest, SilkweaveModule, trpc } from '@silkweave/nestjs'
+import { mcp, SilkweaveModule } from '@silkweave/nestjs'
 import { AdminGuard } from './admin.guard.js'
-import { UserActions } from './users.actions.js'
+import { UsersController } from './users.controller.js'
 
 @Module({
   imports: [
     SilkweaveModule.forRoot({
       silkweave: { name: 'my-app', description: 'My App', version: '1.0.0' },
-      adapters: [
-        rest({ basePath: '/api' }),
-        trpc({ basePath: '/trpc' }),
-        mcp({ basePath: '/mcp' })
-      ]
+      adapters: [mcp({ basePath: '/mcp' })]
     })
   ],
-  providers: [AdminGuard, UserActions]
+  controllers: [UsersController],
+  providers: [AdminGuard]
 })
 export class AppModule {}
 ```
@@ -91,90 +97,64 @@ const app = await NestFactory.create(AppModule)
 await app.listen(8080)
 ```
 
-The `users.list` and `users.get` actions are now reachable via:
-
-- **REST:** `GET /api/users/list?activeOnly=true` and `GET /api/users/get?id=1`
-- **tRPC:** `client.usersList.query({ activeOnly: true })` and `client.usersGet.query({ id: '1' })`
-- **MCP:** tools `UsersList` and `UsersGet`
-
-`users.ban` is guarded by `@UseGuards(AdminGuard)` on **every** transport - REST, tRPC, **and** MCP. The guard reads its credential from the request header (`switchToHttp().getRequest().headers`); over MCP the inbound tool-call headers are surfaced the same way (see [Guards & DI](#guards--di)).
-
-## Decorators
-
-### `@Action(options)` (method decorator)
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | kebab-cased method name | Override the action name. Joined with the class prefix via `.` |
-| `description` | `string` | *required* | Human-readable summary. Used as MCP tool description |
-| `input` | `z.ZodObject` | *required* | Zod object schema for the action's input |
-| `output` | `z.ZodObject` | - | Optional output schema (used by tRPC type inference) |
-| `chunk` | `z.ZodType` | - | Schema for chunks yielded by a streaming (`async function*`) method. **Required** when the method is an async generator |
-| `kind` | `'query' \| 'mutation'` | `'mutation'` | `'query'` → GET in REST, `.query()` in tRPC. `'mutation'` → POST / `.mutation()` |
-| `transports` | `('rest' \| 'trpc' \| 'mcp')[]` | all | Allowlist of transports that expose this action |
-| `isEnabled` | `(ctx) => boolean` | - | Dynamic gate (AND-combined with `transports`) |
-| `toolResult` | `(response, ctx) => CallToolResult` | - | Custom MCP `CallToolResult` formatter |
-
-### `@Actions(prefix?)` (class decorator)
+The MCP endpoint at `/mcp` now exposes three tools - `UsersList`, `UsersGet`, `UsersBan` - whose input schemas are reflected from the controllers:
 
-Groups a class's actions under a common prefix. Joined to method-level names with a dot.
+- `UsersGet` → `{ id: string }` (`id` required, described "User ID" from `@ApiParam`)
+- `UsersList` → `{ activeOnly?: boolean }` (optional, typed/described from `@ApiQuery`)
+- `UsersBan` → `{ id: string, reason: string (minLength 3), permanent?: boolean }` (flattened from the path param + `BanUserDto`, with `@ApiProperty` + `class-validator` merged)
 
-```ts
-@Actions('users')
-class UserActions {
-  @Action({ ... }) list(...) {}    // action name: 'users.list'
-  @Action({ name: 'top' }) ... {}  // action name: 'users.top'
-}
-```
+`UsersBan` is guarded by `@UseGuards(AdminGuard)`; over MCP the guard reads the inbound tool-call headers (see [Guards & DI](#guards--di)).
 
-Accepts either a string (shorthand) or `{ prefix, transports }` for a class-wide transport default.
+## Decorator
 
-## Adapters
+### `@Mcp(options?)` (method decorator)
 
-### `rest(options?)`
-
-Maps actions to REST routes on the Nest HTTP server.
+Exposes the decorated controller route as an MCP tool. Every option is optional.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `basePath` | `string` | `'/api'` | URL prefix joined to each action's path |
-| `auth` | `AuthConfig` | - | `@silkweave/auth` bearer-token config |
+| `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` |
+| `pipes` | `'apply' \| 'skip'` | `'apply'` | Whether to run parameter-bound pipes (`@Param('id', ParseIntPipe)`) when re-binding |
 
-Routes follow `{basePath}/{action-name-with-slashes}` where dots in action names become slashes:
+## How reflection works
 
-- `users.list` (query) → `GET /api/users/list`
-- `users.ban` (mutation) → `POST /api/users/ban`
+For each `@Mcp` method the adapter builds **one flat Zod input object** by merging, per field, in increasing precedence:
 
-Each action is registered as an individual route on Nest's HTTP adapter (not a sub-app). Input is parsed from `req.query` (queries) or `req.body` (mutations) and validated against the action's Zod schema; validation failures return HTTP 400 with the Zod issues.
+1. TypeScript `design:type` (the parameter/property constructor)
+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
 
-### `trpc(options?)`
+Field sources are derived from the parameter decorators:
 
-Mounts a tRPC HTTP handler built from `@silkweave/trpc`'s `buildRouter`.
+| Controller parameter | Tool input |
+|----------------------|-----------|
+| `@Param('id') id` | scalar field `id` |
+| `@Param() params` | one field per `:param` in the route |
+| `@Query('limit') limit` | scalar field `limit` |
+| `@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`) |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `basePath` | `string` | `'/trpc'` | URL prefix the tRPC handler listens on |
-| `auth` | `AuthConfig` | - | `@silkweave/auth` bearer-token config |
+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.
 
-Action names with dots (e.g. `users.list`) collapse to camelCase procedure keys (`usersList`) - flat router in v1.
+### Optional OpenAPI ingestion
 
-**Streaming.** An `@Action` method declared as an `async function*` (with a `chunk` schema) is registered as a tRPC **subscription** that streams each yielded chunk over SSE - exactly like a standalone `createAction({ chunk, run: async function*(){…} })`. `@UseGuards()` guards still run before the first chunk. This is what `useChat` + `@silkweave/ai`'s `silkweaveTransport()` consume.
+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.
 
 ```ts
-@Action({
-  description: 'Stream a countdown',
-  input: z.object({ from: z.number().int() }),
-  chunk: z.object({ n: z.number().int() })
+SilkweaveModule.forRoot({
+  silkweave: { name: 'my-app', description: 'My App', version: '1.0.0' },
+  adapters: [mcp()],
+  openapi: openApiDocument
 })
-async *countdown(input: { from: number }) {
-  for (let n = input.from; n >= 0; n -= 1) {
-    await new Promise((r) => setTimeout(r, 200))
-    yield { n }
-  }
-}
 ```
 
-Declaring an async-generator method without a `chunk` schema throws at discovery time - the schema is required for typegen/tRPC to expose the subscription.
+## Adapter
 
 ### `mcp(options?)`
 
@@ -190,46 +170,29 @@ Mounts the MCP Streamable HTTP transport directly at `basePath`, with sideload (
 
 ## Guards & DI
 
-Native NestJS `@UseGuards()` and `@UseInterceptors()` on `@Action` methods run for **every** transport - REST, tRPC, and MCP. Guards receive an `ExecutionContext` with the request in `switchToHttp().getRequest()`. The `Reflector` is also wired up so guards can read custom metadata.
+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.
 
-**Headers over MCP.** REST and tRPC pass the raw HTTP request to the guard. For MCP (Streamable HTTP), 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:
+**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:
 
-- Only **headers** (and the request `url`) cross the MCP boundary. There are no path `params` or `query` on an MCP tool call, so `getRequest().params` / `.query` are empty objects - guards relying on them degrade to "deny" rather than crash.
+- Only **headers** (and the request `url`) cross the MCP boundary - `getRequest().params`/`.query` are empty objects.
 - A guard that denies (returns `false` or throws) produces a clean MCP tool error (`ForbiddenException`), not an HTTP 500.
-- For OAuth 2.1 / bearer-token MCP auth, prefer `mcp({ auth })` and read the resolved identity from the silkweave context (`ctx.get('auth')`) inside the action; the header stand-in is for custom request-reading guards.
+- For OAuth 2.1 / bearer-token MCP auth, prefer `mcp({ auth })` and read the resolved identity from the silkweave context (`ctx.get('auth')`); the header stand-in is for custom request-reading guards.
 
-Action methods are normal Nest provider methods - inject services via the constructor as usual.
+Controllers are normal Nest providers - inject services via the constructor as usual.
 
-```ts
-@Injectable()
-class MyActions {
-  constructor(
-    private readonly db: DbService,
-    private readonly cache: CacheService
-  ) {}
-
-  @UseGuards(AuthGuard, RateLimitGuard)
-  @Action({ description: '...', input: z.object({...}) })
-  async myAction(input, ctx) {
-    return this.db.query(...)
-  }
-}
-```
+## What does *not* run
 
-## Action name → transport path
+Because the handler is invoked directly (not through Nest's HTTP request pipeline), the following do **not** apply on a tool call - only `@UseGuards()` and parameter-bound pipes do:
 
-| Action name | REST path | tRPC procedure | MCP tool |
-|-------------|-----------|----------------|----------|
-| `hello` | `/hello` | `hello` | `Hello` |
-| `users.list` | `/users/list` | `usersList` | `UsersList` |
-| `posts.get-by-id` | `/posts/get-by-id` | `postsGetById` | `PostsGetById` |
+- Globally-registered `ValidationPipe` / interceptors / exception filters (MCP input is instead validated against the reflected Zod schema).
+- DTO class instantiation - whole-DTO `@Body()`/`@Query()` arguments arrive as plain objects, so `@Transform` and DTO methods do not fire.
+- Discriminated-union / `@ValidateIf` XOR constraints can't be expressed as hard MCP schema constraints - document them in the tool `description` or supply `@Mcp({ input })`.
 
 ## Notes
 
-- **Lifecycle:** adapters mount their route slots in `OnModuleInit` (before Nest's 404 catch-all is installed) and populate the handlers in `OnApplicationBootstrap` after `@Action` discovery.
-- **Express only by default.** `@nestjs/platform-fastify` requires `@fastify/express` registered upfront so Nest can serve Express-style middleware (used by all three adapters internally).
-- **Query coercion for REST queries:** request query strings are always strings; use `z.coerce.boolean()` / `z.coerce.number()` in your Zod schemas for queries.
-- **`reflect-metadata`** must be imported once at the top of your entry file (typical Nest requirement).
+- **Opt-in.** Only methods carrying `@Mcp()` 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.
 
 ## License