@silkweave/nestjs 1.12.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silkweave/nestjs",
-  "version": "1.12.0",
+  "version": "2.0.0",
   "description": "Silkweave NestJS Adapter",
   "repository": {
     "type": "git",
@@ -12,25 +12,24 @@
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
-    "@nestjs/swagger": "^7.0.0 || ^8.0.0 || ^11.0.0"
+    "@nestjs/swagger": "^7.0.0 || ^8.0.0 || ^11.0.0",
+    "class-validator": "^0.14.0"
   },
   "peerDependenciesMeta": {
     "@nestjs/swagger": {
       "optional": true
+    },
+    "class-validator": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@trpc/server": "^11.7.1",
-    "change-case": "^5.4.4",
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "zod": "^3.25.0",
-    "@silkweave/auth": "1.12.0",
-    "@silkweave/core": "1.12.0",
-    "@silkweave/mcp": "1.12.0",
-    "@silkweave/trpc": "1.12.0",
-    "@silkweave/typegen": "1.12.0",
-    "@silkweave/logger": "1.12.0"
+    "@silkweave/auth": "2.0.0",
+    "@silkweave/core": "2.0.0",
+    "@silkweave/mcp": "2.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/decorator/mcp.ts

@@ -0,0 +1,39 @@
+import { SetMetadata } from '@nestjs/common'
+import { MCP_METADATA, type McpMetadata } from '../lib/metadata.js'
+
+/**
+ * Method decorator that exposes an existing NestJS controller route as an MCP
+ * tool. It is **additive** - the route keeps serving HTTP exactly as before;
+ * `@Mcp()` just opts the method into MCP discovery.
+ *
+ * The tool's name, description, and input schema are reflected from the
+ * method's own metadata:
+ * - **fields** from the parameter decorators (`@Param`/`@Query`/`@Body`) - a
+ *   `@Param('id')` becomes an `id` field; a whole-DTO `@Body() dto: CreateDto`
+ *   is flattened to its properties,
+ * - **types/constraints/descriptions** from `@nestjs/swagger`
+ *   (`@ApiParam`/`@ApiQuery`/`@ApiProperty`/`@ApiOperation`) and, when present,
+ *   `class-validator` decorators on the DTOs,
+ * - optionally refined by an OpenAPI document passed to `SilkweaveModule`.
+ *
+ * On a tool call the input is split back into the method's positional arguments
+ * and the method is invoked directly (with `@UseGuards` guards applied first).
+ *
+ * @example
+ * ```ts
+ * @Controller('sessions/:sessionId/channels')
+ * export class ChannelsController {
+ *   @Get(':channelId')
+ *   @ApiOperation({ summary: 'Get a specific channel by ID' })
+ *   @ApiParam({ name: 'sessionId', description: 'Session ID' })
+ *   @ApiParam({ name: 'channelId', description: 'Channel ID' })
+ *   @Mcp()
+ *   findOne(@Param('sessionId') sessionId: string, @Param('channelId') channelId: string) {
+ *     return this.service.get(sessionId, channelId)
+ *   }
+ * }
+ * ```
+ */
+export function Mcp(options: McpMetadata = {}): MethodDecorator {
+  return SetMetadata(MCP_METADATA, options)
+}

package/src/index.ts

@@ -1,14 +1,10 @@
 export * from './adapter/mcp.js'
-export * from './adapter/rest.js'
-export * from './adapter/trpc.js'
-export * from './adapter/typegen.js'
-export * from './decorator/action.js'
-export * from './decorator/actions.js'
-export * from './lib/discovery.js'
-export * from './lib/filter.js'
+export * from './decorator/mcp.js'
+export * from './lib/controllerDiscovery.js'
 export * from './lib/guards.js'
 export * from './lib/metadata.js'
-export * from './lib/openapi.js'
+export * from './lib/rebind.js'
 export * from './lib/silkweave.module.js'
-export * from './lib/swagger.js'
 export * from './lib/types.js'
+export * from './lib/reflect/openapi.js'
+export * from './lib/reflect/schema.js'

package/src/lib/controllerDiscovery.ts

@@ -0,0 +1,201 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+import { Injectable, type Type } from '@nestjs/common'
+import { DiscoveryService, MetadataScanner, ModuleRef, Reflector } from '@nestjs/core'
+import { createAction, type Action, type SilkweaveContext } from '@silkweave/core'
+import { z } from 'zod/v4'
+import { collectGuards, runGuards } from './guards.js'
+import { MCP_METADATA, type McpMetadata } from './metadata.js'
+import { invokeRebound, specialBinding, type Binding } from './rebind.js'
+import { buildOpenApiLookup, openApiFields, type OpenApiDocument, type OpenApiLookup } from './reflect/openapi.js'
+import { PARAMTYPE, type ParamSlot, readParamSlots } from './reflect/params.js'
+import { reflectRoute } from './reflect/route.js'
+import { type FieldDesc, fieldToZod, mergeField, reflectDtoFields } from './reflect/schema.js'
+import { reflectOperation } from './reflect/swagger.js'
+
+interface DiscoveredMcp {
+  instance: object
+  classRef: Type<unknown>
+  method: (...args: unknown[]) => unknown
+  methodName: string
+  meta: McpMetadata
+}
+
+interface BuiltInput {
+  shape: Record<string, z.ZodType>
+  bindings: Binding[]
+}
+
+@Injectable()
+export class ControllerDiscovery {
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly scanner: MetadataScanner,
+    private readonly reflector: Reflector,
+    private readonly moduleRef: ModuleRef
+  ) { }
+
+  /**
+   * Walk every Nest provider/controller, find methods annotated with `@Mcp`,
+   * and build a core `Action` per method whose input schema is reflected from
+   * the route + parameter decorators (+ optional OpenAPI document) and whose
+   * `run` re-binds the validated input back into the method's positional
+   * arguments (with `@UseGuards` guards applied first).
+   */
+  discover(openapi?: OpenApiDocument): Action[] {
+    const lookup = openapi ? buildOpenApiLookup(openapi) : undefined
+    const discovered: DiscoveredMcp[] = []
+    for (const wrapper of this.discovery.getProviders().concat(this.discovery.getControllers())) {
+      const { instance } = wrapper
+      if (!instance || typeof instance !== 'object') { continue }
+      const proto = Object.getPrototypeOf(instance) as object | null
+      if (!proto) { continue }
+      const classRef = instance.constructor as Type<unknown>
+      for (const methodName of this.scanner.getAllMethodNames(proto)) {
+        const method = (proto as Record<string, unknown>)[methodName] as ((...args: unknown[]) => unknown) | undefined
+        if (typeof method !== 'function') { continue }
+        const meta = this.reflector.get<McpMetadata>(MCP_METADATA, method)
+        if (!meta) { continue }
+        discovered.push({ instance, classRef, method, methodName, meta })
+      }
+    }
+    return discovered.map((d) => this.toAction(d, lookup))
+  }
+
+  private toAction(d: DiscoveredMcp, lookup: OpenApiLookup | undefined): Action {
+    const proto = Object.getPrototypeOf(d.instance) as object
+    const route = reflectRoute(d.classRef, d.method)
+    const slots = readParamSlots(d.classRef, d.methodName, proto)
+    const operation = reflectOperation(d.method)
+    const docFields = lookup ? openApiFields(lookup, route.method, route.openapiPath) : {}
+
+    const { shape, bindings } = this.buildInput(d, route.pathParams, slots, operation.params, docFields)
+
+    const base = d.classRef.name.replace(/Controller$/, '')
+    const name = d.meta.name ?? `${base}.${d.methodName}`
+    const description = d.meta.description ?? operation.description ?? `${d.methodName} (${route.method} /${route.path})`
+    const applyParamPipes = d.meta.pipes !== 'skip'
+
+    const guards = collectGuards(this.reflector, d.classRef, d.method)
+    const { moduleRef, reflector } = this
+    const classRef = d.classRef
+    const method = d.method
+    const instance = d.instance
+
+    const applyGuards = async (context: SilkweaveContext): Promise<void> => {
+      if (guards.length === 0) { return }
+      const request = context.getOptional<unknown>('request')
+      const response = context.getOptional<unknown>('response') ?? null
+      const hasRequest = request != null
+      const guardRequest = hasRequest ? request : { headers: {}, params: {}, query: {} }
+      await runGuards(guards, moduleRef, reflector, classRef, method, guardRequest, response, hasRequest ? 'http' : 'rpc')
+    }
+
+    return createAction({
+      name,
+      description,
+      input: z.object(shape),
+      // Only the MCP adapter exposes `@Mcp` methods; a future `@Trpc` decorator
+      // would tag its own actions for the tRPC adapter.
+      isEnabled: (ctx) => ctx.getOptional<string>('adapter') === 'mcp',
+      run: async (input: object, context: SilkweaveContext): Promise<object> => {
+        await applyGuards(context)
+        const request = context.getOptional<{ headers?: Record<string, unknown> }>('request')
+        const result = await invokeRebound(method, instance, input as Record<string, unknown>, bindings, request, applyParamPipes)
+        return (result ?? {})
+      }
+    }) as Action
+  }
+
+  /** Build the merged Zod input shape and the per-argument re-bind plan. */
+  private buildInput(
+    d: DiscoveredMcp,
+    pathParams: string[],
+    slots: ReturnType<typeof readParamSlots>,
+    operationParams: Record<string, FieldDesc>,
+    docFields: Record<string, FieldDesc>
+  ): BuiltInput {
+    const proto = Object.getPrototypeOf(d.instance) as object
+    const designTypes = (Reflect.getMetadata('design:paramtypes', proto, d.methodName) as unknown[] | undefined) ?? []
+    const fields: Record<string, FieldDesc> = {}
+    const maxIndex = slots.reduce((m, s) => Math.max(m, s.index), -1)
+    const bindings: Binding[] = Array.from({ length: maxIndex + 1 }, () => ({ kind: 'missing' as const }))
+
+    const addField = (name: string, desc: FieldDesc): void => {
+      fields[name] = name in fields ? mergeField(fields[name], desc) : desc
+    }
+
+    for (const slot of slots) {
+      const { binding, fields: contributed } = contributeSlot(slot, pathParams, designTypes)
+      bindings[slot.index] = binding
+      for (const [name, desc] of Object.entries(contributed)) { addField(name, desc) }
+    }
+
+    // Layer operation-level (`@ApiParam`/`@ApiQuery`) then OpenAPI-document
+    // metadata over the structural fields (later sources win per field).
+    for (const [name, desc] of Object.entries(operationParams)) {
+      if (name in fields) { fields[name] = mergeField(fields[name], desc) }
+    }
+    for (const [name, desc] of Object.entries(docFields)) {
+      if (name in fields) { fields[name] = mergeField(fields[name], desc) }
+    }
+
+    const shape: Record<string, z.ZodType> = {}
+    for (const [name, desc] of Object.entries(fields)) { shape[name] = fieldToZod(desc) }
+    // `@Mcp({ input })` raw-shape override wins per field.
+    Object.assign(shape, d.meta.input ?? {})
+
+    return { shape, bindings }
+  }
+}
+
+function designTypeAt(designTypes: unknown[], index: number): FieldDesc {
+  const ctor = designTypes[index]
+  if (ctor === String) { return { type: 'string' } }
+  if (ctor === Number) { return { type: 'number' } }
+  if (ctor === Boolean) { return { type: 'boolean' } }
+  return {}
+}
+
+interface SlotContribution {
+  binding: Binding
+  /** Input fields this slot contributes, keyed by field name. */
+  fields: Record<string, FieldDesc>
+}
+
+/** A `@Param('id')` scalar or a bare `@Param()` covering all path params. */
+function paramContribution(slot: ParamSlot, pathParams: string[]): SlotContribution {
+  if (slot.data) {
+    return {
+      binding: { kind: 'value', field: slot.data, source: 'path', metatype: slot.designType, pipes: slot.pipes },
+      fields: { [slot.data]: { type: 'string', required: true } }
+    }
+  }
+  const fields: Record<string, FieldDesc> = {}
+  for (const p of pathParams) { fields[p] = { type: 'string', required: true } }
+  return { binding: { kind: 'params', fields: pathParams }, fields }
+}
+
+/** A `@Query('x')`/`@Body('x')` scalar or a whole-DTO `@Query()`/`@Body()`. */
+function bodyOrQueryContribution(slot: ParamSlot, source: 'query' | 'body', requiredScalar: boolean, designTypes: unknown[]): SlotContribution {
+  if (slot.data) {
+    return {
+      binding: { kind: 'value', field: slot.data, source, metatype: slot.designType, pipes: slot.pipes },
+      fields: { [slot.data]: mergeField(designTypeAt(designTypes, slot.index), { required: requiredScalar }) }
+    }
+  }
+  const dtoFields = reflectDtoFields(slot.designType)
+  return {
+    binding: { kind: 'object', source, fields: Object.keys(dtoFields), metatype: slot.designType, pipes: slot.pipes },
+    fields: dtoFields
+  }
+}
+
+/** Map one parameter slot to its input-field contribution and re-bind instruction. */
+function contributeSlot(slot: ParamSlot, pathParams: string[], designTypes: unknown[]): SlotContribution {
+  switch (slot.paramtype) {
+    case PARAMTYPE.PARAM: return paramContribution(slot, pathParams)
+    case PARAMTYPE.QUERY: return bodyOrQueryContribution(slot, 'query', false, designTypes)
+    case PARAMTYPE.BODY: return bodyOrQueryContribution(slot, 'body', true, designTypes)
+    default: return { binding: specialBinding(slot.paramtype, slot.data) ?? { kind: 'missing' }, fields: {} }
+  }
+}

package/src/lib/metadata.ts

@@ -1,58 +1,38 @@
-import { type Action, type ActionKind, type HttpMethod, type SilkweaveContext } from '@silkweave/core'
-import type z from 'zod/v4'
+import type { z } from 'zod/v4'
 
-export const ACTION_METADATA = '__silkweave_action__'
-export const ACTIONS_METADATA = '__silkweave_actions__'
+/** Reflect-metadata key carrying `@Mcp` options on a controller method. */
+export const MCP_METADATA = '__silkweave_mcp__'
 
-export type Transport = 'rest' | 'trpc' | 'mcp'
-
-export interface ActionMetadata<I extends object = object, O extends object = object, C = unknown> {
-  /** Action name. Defaults to the kebab-cased method name. */
+/**
+ * Options for the `@Mcp()` method decorator. Every field is optional - an empty
+ * `@Mcp()` exposes the decorated controller route as an MCP tool with its name,
+ * description, and input schema fully reflected from the method's route
+ * (`@Get`/`@Post`/...), parameter decorators (`@Param`/`@Query`/`@Body`), and
+ * any `@nestjs/swagger` (`@ApiOperation`/`@ApiParam`/`@ApiProperty`) or
+ * `class-validator` metadata it carries.
+ */
+export interface McpMetadata {
+  /**
+   * MCP tool name override. When unset it is derived from the controller class
+   * and method name (e.g. `ChannelsController.findOne` → `ChannelsFindOne`).
+   */
   name?: string
-  /** Human-readable description. Becomes the MCP tool description and REST OpenAPI summary. */
-  description: string
-  /** Zod object schema for the action's input. */
-  input: z.ZodType<I> & { shape: Record<string, z.ZodTypeAny> }
-  /** Optional Zod object schema for the action's output (used by tRPC type inference). */
-  output?: z.ZodType<O> & { shape: Record<string, z.ZodTypeAny> }
   /**
-   * Zod schema for individual chunks yielded by a streaming (async-generator)
-   * action method. Required when the decorated method is an `async function*`.
-   * Mirrors `Action.chunk` in @silkweave/core; typegen/trpc use it to expose
-   * the action as a tRPC subscription.
+   * Tool description override. When unset it falls back to the method's
+   * `@ApiOperation({ summary | description })`, then a generated default.
    */
-  chunk?: z.ZodType<C>
-  /** `'query'` (GET in REST, `.query()` in tRPC) or `'mutation'` (POST in REST, `.mutation()` in tRPC). Default: `'mutation'`. */
-  kind?: ActionKind
-  /** HTTP verb for the REST route. Defaults to `POST` (or `GET` when `kind` is `'query'`). Overrides the `kind`-derived default. */
-  method?: HttpMethod
-  /** REST route path, optionally with `:param` placeholders (e.g. `'spaces/:spaceId/users'`). Each placeholder must be a key of `input`. Defaults to the action name with dots as slashes. */
-  path?: string
-  /** Input fields read from the URL query string instead of the request body (e.g. `['offset', 'limit']`). Each must be a key of `input`. */
-  queryParams?: (keyof I)[]
-  /** Allowlist of transports that should expose this action. Default: all registered transports. */
-  transports?: Transport[]
-  /** Dynamic enable check (in addition to `transports`). AND-combined with the transports filter. */
-  isEnabled?: (context: SilkweaveContext) => boolean
-  /** Custom MCP `CallToolResult` formatter. See `@silkweave/mcp`'s `smartToolResult`. */
-  toolResult?: Action<I, O>['toolResult']
-  /** CLI positional-argument keys (unused for HTTP-only adapters, kept for parity with `createAction`). */
-  args?: (keyof I)[]
-  /** Custom MCP tool name override. If unset, derived from action name as PascalCase. */
-  mcpToolName?: string
-}
-
-export interface ActionsClassMetadata {
-  /** Prefix joined to the method-level action name with a dot. e.g. `Actions('users')` + method `list` → `users.list`. */
-  prefix?: string
-  /** Class-level transports allowlist. Method-level `transports` overrides; otherwise inherits this. */
-  transports?: Transport[]
-}
-
-export interface ResultToolResult<O extends object = object> {
-  toolResult?: Action<object, O>['toolResult']
+  description?: string
+  /**
+   * Zod raw-shape override merged over the reflected input fields (override
+   * wins per field). The escape hatch for shapes reflection can't express
+   * losslessly - discriminated unions, custom validators, `@Transform`, etc.
+   */
+  input?: Record<string, z.ZodType>
+  /**
+   * Whether to apply the controller method's parameter-bound pipes
+   * (`@Param('id', ParseIntPipe)`) when re-binding the call. Default `'apply'`.
+   * Global/`ValidationPipe`, interceptors, and exception filters never run -
+   * the method is invoked directly, not through Nest's HTTP request pipeline.
+   */
+  pipes?: 'apply' | 'skip'
 }
-
-export type AnyActionMetadata = ActionMetadata<object, object> & ResultToolResult<object>
-
-export const ACTION_RESPONSE_KEY = '__silkweave_response__'

package/src/lib/rebind.ts

@@ -0,0 +1,117 @@
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment */
+import { PARAMTYPE } from './reflect/params.js'
+
+/**
+ * Instruction for reconstructing one positional handler argument from the flat
+ * MCP tool input. Built at discovery time, consumed by {@link invokeRebound}.
+ */
+export type Binding =
+  | { kind: 'value'; field: string; source: 'path' | 'query' | 'body'; metatype?: unknown; pipes?: unknown[] }
+  | { kind: 'object'; source: 'query' | 'body'; fields: string[]; metatype?: unknown; pipes?: unknown[] }
+  | { kind: 'params'; fields: string[] }
+  | { kind: 'request' }
+  | { kind: 'response' }
+  | { kind: 'headers'; data?: string }
+  | { kind: 'ip' }
+  | { kind: 'host'; data?: string }
+  | { kind: 'missing' }
+
+interface RequestLike {
+  headers?: Record<string, unknown>
+  ip?: unknown
+  hosts?: Record<string, unknown>
+}
+
+function newInstance(P: any): any | null {
+  try { return new P() } catch { return null }
+}
+
+async function applyPipes(value: unknown, pipes: unknown[] | undefined, metatype: unknown, type: 'param' | 'query' | 'body', data: string | undefined): Promise<unknown> {
+  if (!pipes || pipes.length === 0) { return value }
+  let current = value
+  for (const p of pipes) {
+    const pipe = typeof p === 'function' ? newInstance(p) : p
+    if (pipe && typeof (pipe).transform === 'function') {
+      current = await (pipe).transform(current, { type, metatype, data })
+    }
+  }
+  return current
+}
+
+/** Pick a subset of keys (skipping `undefined`) into a fresh object. */
+function pickFields(input: Record<string, unknown>, fields: string[]): Record<string, unknown> {
+  const obj: Record<string, unknown> = {}
+  for (const f of fields) {
+    if (input[f] !== undefined) { obj[f] = input[f] }
+  }
+  return obj
+}
+
+/** Resolve a single positional argument from one binding. */
+async function resolveArg(
+  b: Binding,
+  input: Record<string, unknown>,
+  request: RequestLike | undefined,
+  applyParamPipes: boolean
+): Promise<unknown> {
+  switch (b.kind) {
+    case 'value': {
+      const raw = input[b.field]
+      const type = b.source === 'path' ? 'param' : b.source
+      return applyParamPipes ? applyPipes(raw, b.pipes, b.metatype, type, b.field) : raw
+    }
+    case 'object': {
+      const obj = pickFields(input, b.fields)
+      return applyParamPipes ? applyPipes(obj, b.pipes, b.metatype, b.source, undefined) : obj
+    }
+    case 'params':
+      return pickFields(input, b.fields)
+    case 'headers':
+      return b.data ? request?.headers?.[b.data.toLowerCase()] : (request?.headers ?? {})
+    case 'request':
+      return request ?? { headers: {} }
+    case 'ip':
+      return request?.ip
+    case 'host':
+      return b.data ? request?.hosts?.[b.data] : request?.hosts
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Reconstruct the controller method's positional arguments from the validated
+ * tool `input` (and the request stand-in for `@Req`/`@Headers`/...), then call
+ * it. `applyParamPipes` controls whether parameter-bound pipes run.
+ */
+export async function invokeRebound(
+  method: (...args: any[]) => any,
+  instance: object,
+  input: Record<string, unknown>,
+  bindings: Binding[],
+  request: RequestLike | undefined,
+  applyParamPipes: boolean
+): Promise<unknown> {
+  const args: unknown[] = []
+  for (let i = 0; i < bindings.length; i += 1) {
+    args[i] = await resolveArg(bindings[i], input, request, applyParamPipes)
+  }
+  return await method.apply(instance, args)
+}
+
+/** Map a non-input parameter slot (`@Req`/`@Headers`/`@Ip`/...) to its runtime binding. */
+export function specialBinding(paramtype: number, data: string | undefined): Binding | null {
+  switch (paramtype) {
+    case PARAMTYPE.REQUEST: return { kind: 'request' }
+    case PARAMTYPE.RESPONSE:
+    case PARAMTYPE.NEXT: return { kind: 'response' }
+    case PARAMTYPE.HEADERS: return { kind: 'headers', data }
+    case PARAMTYPE.IP: return { kind: 'ip' }
+    case PARAMTYPE.HOST: return { kind: 'host', data }
+    case PARAMTYPE.SESSION:
+    case PARAMTYPE.FILE:
+    case PARAMTYPE.FILES:
+    case PARAMTYPE.RAW_BODY: return { kind: 'missing' }
+    default: return null
+  }
+}

package/src/lib/reflect/classValidator.ts

@@ -0,0 +1,56 @@
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment */
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+let cached: any | null | undefined
+
+/**
+ * Lazily resolve the optional `class-validator` peer; `null` when not installed.
+ * Resolution is attempted both from this package and from the app's working
+ * directory - the latter is what finds it in a pnpm install where the optional
+ * peer lives in the consumer app rather than alongside `@silkweave/nestjs`. A
+ * pnpm-deduped install shares one physical copy, so the metadata singleton the
+ * app's decorators wrote to is the same one we read.
+ */
+function loadClassValidator(): any | null {
+  if (cached !== undefined) { return cached }
+  for (const base of [import.meta.url, join(process.cwd(), 'noop.js')]) {
+    try {
+      cached = createRequire(base)('class-validator')
+      return cached
+    } catch { /* try the next resolution base */ }
+  }
+  cached = null
+  return cached
+}
+
+export interface ValidationMeta {
+  /** `ValidationTypes` discriminator (e.g. `customValidation`, `conditionalValidation`). */
+  type?: string
+  /** Validator name - the actionable identity for built-ins (`isString`, `minLength`, ...). */
+  name?: string
+  constraints?: unknown[]
+}
+
+/**
+ * Read `class-validator` metadata for a DTO class, grouped by property name.
+ * Returns an empty map when `class-validator` is not installed or the class
+ * carries no validation decorators - so callers degrade gracefully to swagger /
+ * `design:type` reflection.
+ */
+export function classValidatorMetas(dtoType: any): Record<string, ValidationMeta[]> {
+  const cv = loadClassValidator()
+  if (!cv?.getMetadataStorage) { return {} }
+  let metas: Array<{ propertyName?: string; type?: string; name?: string; constraints?: unknown[] }>
+  try {
+    metas = cv.getMetadataStorage().getTargetValidationMetadatas(dtoType, null, false, false)
+  } catch {
+    return {}
+  }
+  const out: Record<string, ValidationMeta[]> = {}
+  for (const m of metas) {
+    if (!m.propertyName) { continue }
+    (out[m.propertyName] ??= []).push({ type: m.type, name: m.name, constraints: m.constraints })
+  }
+  return out
+}

package/src/lib/reflect/openapi.ts

@@ -0,0 +1,87 @@
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment */
+import { type FieldDesc, mergeField, openapiSchemaToField } from './schema.js'
+
+/**
+ * A minimal view of an OpenAPI document - the subset we read. Matches the shape
+ * `SwaggerModule.createDocument()` returns, but typed loosely so callers can
+ * pass any compatible object without a hard `@nestjs/swagger` dependency.
+ */
+export interface OpenApiDocument {
+  paths?: Record<string, Record<string, any>>
+  components?: { schemas?: Record<string, any> }
+}
+
+export interface OpenApiLookup {
+  doc: OpenApiDocument
+  /** `${METHOD} ${path}` → operation object. */
+  operations: Map<string, any>
+}
+
+/** Index a document's operations by `${METHOD} ${path}` for fast matching. */
+export function buildOpenApiLookup(doc: OpenApiDocument): OpenApiLookup {
+  const operations = new Map<string, any>()
+  for (const [path, item] of Object.entries(doc.paths ?? {})) {
+    for (const [verb, op] of Object.entries(item ?? {})) {
+      operations.set(`${verb.toUpperCase()} ${path}`, op)
+    }
+  }
+  return { doc, operations }
+}
+
+/** Locate the operation for a route, tolerating a global path prefix on the document side. */
+function findOperation(lookup: OpenApiLookup, method: string, openapiPath: string): any | undefined {
+  const exact = lookup.operations.get(`${method} ${openapiPath}`)
+  if (exact) { return exact }
+  // Fall back to a suffix match so a `setGlobalPrefix('api')` document still resolves.
+  for (const [key, op] of lookup.operations) {
+    const [verb, path] = key.split(' ')
+    if (verb === method && (path.endsWith(openapiPath) || openapiPath.endsWith(path))) { return op }
+  }
+  return undefined
+}
+
+function resolveRef(doc: OpenApiDocument, schema: any): any {
+  let current = schema
+  let guard = 0
+  while (current && typeof current === 'object' && typeof current['$ref'] === 'string' && guard < 10) {
+    const match = /^#\/components\/schemas\/(.+)$/.exec(current['$ref'])
+    if (!match) { break }
+    current = doc.components?.schemas?.[match[1]]
+    guard += 1
+  }
+  return current
+}
+
+/**
+ * Resolve the per-field descriptors for a route from an ingested OpenAPI
+ * document. Merges `parameters` (path/query/header) and the JSON request-body
+ * schema's properties into a single field map. Returns `{}` when the operation
+ * isn't found - callers fall back to decorator reflection.
+ */
+export function openApiFields(lookup: OpenApiLookup, method: string, openapiPath: string): Record<string, FieldDesc> {
+  const op = findOperation(lookup, method, openapiPath)
+  if (!op) { return {} }
+  const out: Record<string, FieldDesc> = {}
+
+  for (const param of (op['parameters'] as Array<Record<string, any>> | undefined) ?? []) {
+    const name = typeof param['name'] === 'string' ? param['name'] : undefined
+    if (!name) { continue }
+    const schema = param['schema'] ? resolveRef(lookup.doc, param['schema']) : undefined
+    let field = schema ? openapiSchemaToField(schema) : {}
+    if (param['description']) { field = mergeField(field, { description: param['description'] }) }
+    if (typeof param['required'] === 'boolean') { field = mergeField(field, { required: param['required'] }) }
+    out[name] = field
+  }
+
+  const bodySchema = resolveRef(lookup.doc, op['requestBody']?.['content']?.['application/json']?.['schema'])
+  if (bodySchema && typeof bodySchema === 'object' && bodySchema['properties']) {
+    const required = new Set<string>(Array.isArray(bodySchema['required']) ? bodySchema['required'] : [])
+    for (const [name, propSchema] of Object.entries(bodySchema['properties'] as Record<string, any>)) {
+      const field = openapiSchemaToField(resolveRef(lookup.doc, propSchema))
+      field.required = required.has(name)
+      out[name] = field
+    }
+  }
+
+  return out
+}