@silkweave/nestjs 2.0.0 → 2.2.0

package/src/lib/guards.ts

@@ -1,70 +0,0 @@
-import { ForbiddenException, type CanActivate, type Type } from '@nestjs/common'
-import { GUARDS_METADATA } from '@nestjs/common/constants.js'
-import { ModuleRef, Reflector } from '@nestjs/core'
-import { isObservable, lastValueFrom } from 'rxjs'
-import { SilkweaveExecutionContext } from './executionContext.js'
-
-type GuardRef = Type<CanActivate> | CanActivate
-
-/**
- * Read `@UseGuards(...)` metadata for both the method and its class and merge
- * the two lists. Method-level guards run AFTER class-level guards (matching
- * Nest's own behavior).
- */
-export function collectGuards(
-  reflector: Reflector,
-  classRef: Type<unknown>,
-  handler: (...args: unknown[]) => unknown
-): GuardRef[] {
-  const classGuards = reflector.get<GuardRef[]>(GUARDS_METADATA, classRef) ?? []
-  const methodGuards = reflector.get<GuardRef[]>(GUARDS_METADATA, handler) ?? []
-  return [...classGuards, ...methodGuards]
-}
-
-async function resolveGuard(ref: GuardRef, moduleRef: ModuleRef): Promise<CanActivate> {
-  if (typeof ref === 'function') {
-    try {
-      return await moduleRef.get(ref, { strict: false })
-    } catch {
-      return moduleRef.create(ref)
-    }
-  }
-  return ref
-}
-
-/**
- * Run the configured guards against a request. Throws `ForbiddenException`
- * if any guard rejects, mirroring Nest's HTTP request-pipeline behavior.
- *
- * Pass `null` for `response` when running on top of a tRPC or MCP request that
- * doesn't surface a raw response object; guards that introspect the response
- * will receive `null`.
- *
- * `contextType` is reflected through `ExecutionContext.getType()` so guards can
- * branch on the transport. It is `'http'` for REST/tRPC and for MCP-over-HTTP
- * (where a header-bearing request stand-in is available); transports without any
- * HTTP request (e.g. MCP stdio) pass `'rpc'`.
- */
-export async function runGuards(
-  guards: GuardRef[],
-  moduleRef: ModuleRef,
-  reflector: Reflector,
-  classRef: Type<unknown>,
-  handler: (...args: unknown[]) => unknown,
-  request: unknown,
-  response: unknown,
-  contextType: 'http' | 'rpc' = 'http'
-): Promise<void> {
-  if (guards.length === 0) { return }
-  const context = new SilkweaveExecutionContext([request, response], classRef, handler, contextType)
-  for (const ref of guards) {
-    const guard = await resolveGuard(ref, moduleRef)
-    const result = guard.canActivate(context)
-    const allowed = isObservable(result) ? await lastValueFrom(result) : await Promise.resolve(result)
-    if (!allowed) {
-      throw new ForbiddenException('Forbidden resource')
-    }
-  }
-  // Reflector kept in the signature for future use (e.g., per-guard metadata) - unused here.
-  void reflector
-}

package/src/lib/metadata.ts

@@ -1,38 +0,0 @@
-import type { z } from 'zod/v4'
-
-/** Reflect-metadata key carrying `@Mcp` options on a controller method. */
-export const MCP_METADATA = '__silkweave_mcp__'
-
-/**
- * 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
-  /**
-   * Tool description override. When unset it falls back to the method's
-   * `@ApiOperation({ summary | description })`, then a generated default.
-   */
-  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'
-}

package/src/lib/rebind.ts

@@ -1,117 +0,0 @@
-/* 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

@@ -1,56 +0,0 @@
-/* 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

@@ -1,87 +0,0 @@
-/* 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
-}

package/src/lib/reflect/params.ts

@@ -1,63 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { ROUTE_ARGS_METADATA } from '@nestjs/common/constants.js'
-
-/**
- * `RouteParamtypes` numeric values from `@nestjs/common` (re-declared to avoid a
- * value import of an internal enum). These are how `@Param`/`@Query`/`@Body`/...
- * tag each handler argument in `ROUTE_ARGS_METADATA`.
- */
-export const PARAMTYPE = {
-  REQUEST: 0,
-  RESPONSE: 1,
-  NEXT: 2,
-  BODY: 3,
-  QUERY: 4,
-  PARAM: 5,
-  HEADERS: 6,
-  SESSION: 7,
-  FILE: 8,
-  FILES: 9,
-  HOST: 10,
-  IP: 11,
-  RAW_BODY: 12
-} as const
-
-export interface ParamSlot {
-  /** `PARAMTYPE` value - which decorator tagged this argument. */
-  paramtype: number
-  /** Handler argument position. */
-  index: number
-  /** Decorator sub-key: `@Param('id')` → `'id'`; a bare `@Body()` → `undefined`. */
-  data?: string
-  /** Parameter-bound pipes (`@Param('id', ParseIntPipe)`). */
-  pipes: unknown[]
-  /** TypeScript-emitted constructor at this position (e.g. `String`, `CreateDto`). */
-  designType?: unknown
-}
-
-/**
- * Read and normalise the route-argument metadata for a controller method.
- * Returns one {@link ParamSlot} per decorated handler argument, sorted by
- * argument index.
- */
-export function readParamSlots(classRef: any, methodName: string, proto: any): ParamSlot[] {
-  const raw = Reflect.getMetadata(ROUTE_ARGS_METADATA, classRef, methodName) as
-    Record<string, { index: number; data?: unknown; pipes?: unknown[] }> | undefined
-  if (!raw) { return [] }
-  const designTypes = (Reflect.getMetadata('design:paramtypes', proto, methodName) as unknown[] | undefined) ?? []
-
-  const slots: ParamSlot[] = []
-  for (const key of Object.keys(raw)) {
-    const entry = raw[key]
-    const paramtype = Number(key.split(':')[0])
-    if (Number.isNaN(paramtype)) { continue }
-    slots.push({
-      paramtype,
-      index: entry.index,
-      data: typeof entry.data === 'string' ? entry.data : undefined,
-      pipes: entry.pipes ?? [],
-      designType: designTypes[entry.index]
-    })
-  }
-  return slots.sort((a, b) => a.index - b.index)
-}

package/src/lib/reflect/route.ts

@@ -1,58 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { PATH_METADATA, METHOD_METADATA } from '@nestjs/common/constants.js'
-
-/**
- * `RequestMethod` numeric values (from `@nestjs/common`) mapped to verbs. We
- * map our own table rather than importing the enum to avoid pulling a value
- * import for a handful of constants.
- */
-const REQUEST_METHOD: Record<number, string> = {
-  0: 'GET',
-  1: 'POST',
-  2: 'PUT',
-  3: 'DELETE',
-  4: 'PATCH',
-  6: 'OPTIONS',
-  7: 'HEAD'
-}
-
-export interface RouteInfo {
-  /** HTTP verb (`GET`/`POST`/...). `PATCH` and others outside the REST set fall back to `POST`-ish handling by callers. */
-  method: string
-  /** Full route template in Nest form, e.g. `sessions/:sessionId/channels/:channelId` (no leading slash). */
-  path: string
-  /** Full route template in OpenAPI form, e.g. `/sessions/{sessionId}/channels/{channelId}`. */
-  openapiPath: string
-  /** Names of the `:param` placeholders across controller + method path. */
-  pathParams: string[]
-}
-
-function normalizeSegment(value: unknown): string {
-  if (typeof value !== 'string') { return '' }
-  return value.replace(/^\/+/, '').replace(/\/+$/, '')
-}
-
-function joinPath(...segments: string[]): string {
-  return segments.map(normalizeSegment).filter(Boolean).join('/')
-}
-
-/**
- * Resolve the composed route (controller prefix + method path), HTTP verb, and
- * path-param names for a decorated controller method, reading Nest's own
- * `PATH_METADATA`/`METHOD_METADATA` reflection.
- */
-export function reflectRoute(classRef: any, method: (...args: any[]) => any): RouteInfo {
-  const classPath = Reflect.getMetadata(PATH_METADATA, classRef) as string | string[] | undefined
-  const methodPath = Reflect.getMetadata(PATH_METADATA, method) as string | string[] | undefined
-  const verbCode = Reflect.getMetadata(METHOD_METADATA, method) as number | undefined
-
-  const classSeg = Array.isArray(classPath) ? (classPath[0] ?? '') : (classPath ?? '')
-  const methodSeg = Array.isArray(methodPath) ? (methodPath[0] ?? '') : (methodPath ?? '')
-  const path = joinPath(classSeg, methodSeg)
-  const httpMethod = REQUEST_METHOD[verbCode ?? 0] ?? 'GET'
-
-  const pathParams = [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1])
-  const openapiPath = `/${path.replace(/:([A-Za-z0-9_]+)/g, '{$1}')}`
-
-  return { method: httpMethod, path, openapiPath, pathParams }
-}