@silkweave/nestjs 2.0.0 → 2.2.0

package/src/lib/reflect/schema.ts

@@ -1,270 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any */
-import { z } from 'zod/v4'
-import { classValidatorMetas } from './classValidator.js'
-
-/** `@nestjs/swagger` reflect-metadata keys. Read directly so swagger stays an optional peer. */
-const API_MODEL_PROPERTIES = 'swagger/apiModelProperties'
-const API_MODEL_PROPERTIES_ARRAY = 'swagger/apiModelPropertiesArray'
-
-/**
- * A transport-neutral description of a single input field. Every metadata
- * source (swagger decorators, class-validator, an OpenAPI document, TypeScript
- * `design:type`) is mapped to this shape, the shapes are merged by precedence,
- * and the result is converted to Zod once. Keeping a single intermediate keeps
- * the per-source mappers small and the Zod construction in one place.
- */
-export interface FieldDesc {
-  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'unknown'
-  required?: boolean
-  description?: string
-  enum?: (string | number)[]
-  items?: FieldDesc
-  min?: number
-  max?: number
-  minLength?: number
-  maxLength?: number
-  format?: string
-  default?: unknown
-}
-
-/** Strip `undefined` values so a later source never clobbers an earlier one with a hole. */
-function defined<T extends object>(obj: T): Partial<T> {
-  const out: Record<string, unknown> = {}
-  for (const [k, v] of Object.entries(obj)) {
-    if (v !== undefined) { out[k] = v }
-  }
-  return out as Partial<T>
-}
-
-/** Merge `over` onto `base` - defined keys of `over` win. */
-export function mergeField(base: FieldDesc, over: FieldDesc): FieldDesc {
-  return { ...base, ...defined(over) }
-}
-
-function enumToZod(values: (string | number)[]): z.ZodType {
-  const strings = values.filter((v): v is string => typeof v === 'string')
-  if (strings.length === values.length && strings.length > 0) {
-    return z.enum(strings as [string, ...string[]])
-  }
-  const literals = values.map((v) => z.literal(v))
-  if (literals.length === 0) { return z.unknown() }
-  if (literals.length === 1) { return literals[0] }
-  return z.union(literals as unknown as [z.ZodType, z.ZodType, ...z.ZodType[]])
-}
-
-function baseToZod(d: FieldDesc): z.ZodType {
-  switch (d.type) {
-    case 'string': {
-      let s = z.string()
-      if (d.minLength != null) { s = s.min(d.minLength) }
-      if (d.maxLength != null) { s = s.max(d.maxLength) }
-      return s
-    }
-    case 'integer':
-    case 'number': {
-      let n = z.number()
-      if (d.type === 'integer') { n = n.int() }
-      if (d.min != null) { n = n.min(d.min) }
-      if (d.max != null) { n = n.max(d.max) }
-      return n
-    }
-    case 'boolean':
-      return z.boolean()
-    case 'array':
-      return z.array(d.items ? fieldToZod({ ...d.items, required: true }) : z.unknown())
-    case 'object':
-      return z.record(z.string(), z.unknown())
-    default:
-      return z.unknown()
-  }
-}
-
-/** Convert a merged {@link FieldDesc} to a Zod schema. */
-export function fieldToZod(d: FieldDesc): z.ZodType {
-  let schema = (d.enum?.length) ? enumToZod(d.enum) : baseToZod(d)
-  if (d.description) { schema = schema.describe(d.description) }
-  if (d.default !== undefined) {
-    schema = (schema as any).default(d.default)
-  } else if (d.required === false) {
-    schema = schema.optional()
-  }
-  return schema
-}
-
-// --- per-source mappers ---------------------------------------------------
-
-/** Normalise a TS-enum object or an array literal to a flat value list. */
-export function normalizeEnum(value: unknown): (string | number)[] | undefined {
-  if (Array.isArray(value)) {
-    return value.filter((v): v is string | number => typeof v === 'string' || typeof v === 'number')
-  }
-  if (value && typeof value === 'object') {
-    return Object.values(value).filter((v): v is string | number => typeof v === 'string' || typeof v === 'number')
-  }
-  return undefined
-}
-
-/** Map a swagger/`design:type` type token (constructor, `[Type]`, or string) to a base type. */
-export function typeTokenToBase(type: unknown): FieldDesc['type'] | undefined {
-  if (type == null) { return undefined }
-  if (type === String) { return 'string' }
-  if (type === Number) { return 'number' }
-  if (type === Boolean) { return 'boolean' }
-  if (type === Array) { return 'array' }
-  if (type === Date) { return 'string' }
-  if (Array.isArray(type)) { return 'array' }
-  if (typeof type === 'string') {
-    const t = type.toLowerCase()
-    if (t === 'string' || t === 'number' || t === 'integer' || t === 'boolean' || t === 'array' || t === 'object') {
-      return t
-    }
-  }
-  return undefined
-}
-
-/** From the constructor TypeScript emits via `emitDecoratorMetadata`. */
-export function designTypeToField(ctor: unknown): FieldDesc {
-  const type = typeTokenToBase(ctor)
-  const f: FieldDesc = {}
-  if (type) { f.type = type }
-  return f
-}
-
-/** From an `@ApiParam`/`@ApiQuery` entry stored under `swagger/apiParameters`. */
-export function swaggerParamToField(p: Record<string, any>): FieldDesc {
-  const f: FieldDesc = {}
-  if (p['description']) { f.description = p['description'] }
-  if (typeof p['required'] === 'boolean') { f.required = p['required'] }
-  const type = typeTokenToBase(p['type'])
-  if (type) { f.type = type }
-  if (p['isArray']) { f.type = 'array' }
-  const en = normalizeEnum(p['enum'])
-  if (en) { f.enum = en }
-  if (p['schema'] && typeof p['schema'] === 'object') {
-    return mergeField(f, openapiSchemaToField(p['schema']))
-  }
-  return f
-}
-
-/** From an `@ApiProperty` options object stored under `swagger/apiModelProperties`. */
-export function apiPropertyToField(o: Record<string, any>): FieldDesc {
-  const f: FieldDesc = {}
-  if (o['description']) { f.description = o['description'] }
-  if (typeof o['required'] === 'boolean') { f.required = o['required'] }
-  const type = typeTokenToBase(o['type'])
-  if (type) { f.type = type }
-  if (o['isArray']) {
-    f.items = { type: type && type !== 'array' ? type : 'unknown' }
-    f.type = 'array'
-  }
-  const en = normalizeEnum(o['enum'])
-  if (en) { f.enum = en }
-  if (o['minimum'] != null) { f.min = o['minimum'] }
-  if (o['maximum'] != null) { f.max = o['maximum'] }
-  if (o['minLength'] != null) { f.minLength = o['minLength'] }
-  if (o['maxLength'] != null) { f.maxLength = o['maxLength'] }
-  if (o['format']) { f.format = o['format'] }
-  if (o['default'] !== undefined) { f.default = o['default'] }
-  return f
-}
-
-/** `class-validator` decorator type → field base type. */
-const CV_TYPE: Record<string, FieldDesc['type']> = {
-  isString: 'string',
-  isInt: 'integer',
-  isBoolean: 'boolean',
-  isArray: 'array'
-}
-
-/** `class-validator` decorator type → numeric-constraint field key. */
-const CV_NUMERIC: Record<string, 'min' | 'max' | 'minLength' | 'maxLength'> = {
-  min: 'min',
-  max: 'max',
-  minLength: 'minLength',
-  maxLength: 'maxLength'
-}
-
-/**
- * Fold one `class-validator` metadata entry into the field descriptor. Built-in
- * validators record their identity in `name` (`isString`, `minLength`, ...) with
- * `type: 'customValidation'`; `@IsOptional` uses `name: 'isOptional'`. We key off
- * `name`, falling back to `type`.
- */
-function applyValidationMeta(f: FieldDesc, meta: { type?: string; name?: string; constraints?: unknown[] }): void {
-  const key = meta.name ?? meta.type
-  if (!key) { return }
-  if (key in CV_TYPE) { f.type = CV_TYPE[key]; return }
-  const c0 = meta.constraints?.[0]
-  if (key in CV_NUMERIC) {
-    if (typeof c0 === 'number') { f[CV_NUMERIC[key]] = c0 }
-    return
-  }
-  if (key === 'isNumber') { if (!f.type) { f.type = 'number' } return }
-  if (key === 'isEmail') { if (!f.type) { f.type = 'string' } f.format = 'email'; return }
-  if (key === 'isDate' || key === 'isDateString') { f.type = 'string'; f.format = 'date-time'; return }
-  if (key === 'isEnum') { const e = normalizeEnum(c0); if (e) { f.enum = e } return }
-  if (key === 'isOptional') { f.required = false }
-}
-
-/** From an array of `class-validator` validation-metadata entries for one property. */
-export function classValidatorToField(metas: Array<{ type?: string; name?: string; constraints?: unknown[] }>): FieldDesc {
-  const f: FieldDesc = {}
-  for (const meta of metas) { applyValidationMeta(f, meta) }
-  return f
-}
-
-/** From an OpenAPI Schema Object (used by both the doc and `@ApiParam({ schema })`). */
-export function openapiSchemaToField(schema: Record<string, any>): FieldDesc {
-  const f: FieldDesc = {}
-  const type = typeof schema['type'] === 'string' ? schema['type'].toLowerCase() : undefined
-  if (type === 'string' || type === 'number' || type === 'integer' || type === 'boolean' || type === 'array' || type === 'object') {
-    f.type = type
-  }
-  if (schema['description']) { f.description = schema['description'] }
-  const en = normalizeEnum(schema['enum'])
-  if (en) { f.enum = en }
-  if (schema['minimum'] != null) { f.min = schema['minimum'] }
-  if (schema['maximum'] != null) { f.max = schema['maximum'] }
-  if (schema['minLength'] != null) { f.minLength = schema['minLength'] }
-  if (schema['maxLength'] != null) { f.maxLength = schema['maxLength'] }
-  if (schema['format']) { f.format = schema['format'] }
-  if (schema['default'] !== undefined) { f.default = schema['default'] }
-  if (schema['items'] && typeof schema['items'] === 'object') {
-    f.items = openapiSchemaToField(schema['items'])
-  }
-  return f
-}
-
-/**
- * Reflect a whole-DTO class (`@Body() dto: CreateDto`) into per-property
- * {@link FieldDesc}s. Property names are the union of `@ApiProperty` and
- * `class-validator` decorated fields; each field merges `design:type` (base),
- * then `class-validator` constraints, then `@ApiProperty` (highest). Properties
- * default to required unless a source marks them optional.
- */
-export function reflectDtoFields(dtoType: any): Record<string, FieldDesc> {
-  const proto = dtoType?.prototype
-  if (!proto) { return {} }
-  const cvMetas = classValidatorMetas(dtoType)
-
-  const names = new Set<string>()
-  const swaggerArray = (Reflect.getMetadata(API_MODEL_PROPERTIES_ARRAY, proto) as string[] | undefined) ?? []
-  for (const entry of swaggerArray) { names.add(entry.replace(/^:/, '')) }
-  for (const name of Object.keys(cvMetas)) { names.add(name) }
-
-  const out: Record<string, FieldDesc> = {}
-  for (const name of names) {
-    let f = designTypeToField(Reflect.getMetadata('design:type', proto, name))
-    if (cvMetas[name]) { f = mergeField(f, classValidatorToField(cvMetas[name])) }
-    const apiProp = Reflect.getMetadata(API_MODEL_PROPERTIES, proto, name) as Record<string, any> | undefined
-    if (apiProp) {
-      const fromApi = apiPropertyToField(apiProp)
-      // `@ApiProperty` is required unless `required: false` is explicit.
-      if (fromApi.required === undefined && apiProp['required'] === undefined) { fromApi.required = true }
-      f = mergeField(f, fromApi)
-    }
-    if (f.required === undefined) { f.required = true }
-    out[name] = f
-  }
-  return out
-}

package/src/lib/reflect/swagger.ts

@@ -1,39 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { FieldDesc } from './schema.js'
-import { swaggerParamToField } from './schema.js'
-
-/** `@nestjs/swagger` reflect-metadata keys (read directly - swagger is an optional peer). */
-const API_OPERATION = 'swagger/apiOperation'
-const API_PARAMETERS = 'swagger/apiParameters'
-
-export interface OperationMeta {
-  /** Tool-description candidate from `@ApiOperation({ summary | description })`. */
-  description?: string
-  /** Per-name `FieldDesc` reflected from `@ApiParam`/`@ApiQuery` entries. */
-  params: Record<string, FieldDesc>
-}
-
-/**
- * Read operation-level `@nestjs/swagger` metadata off a controller method:
- * `@ApiOperation` (summary/description) and the `@ApiParam`/`@ApiQuery` array
- * (each describing one path/query field). Returns empty data when swagger
- * decorators are absent.
- */
-export function reflectOperation(method: (...args: any[]) => any): OperationMeta {
-  const operation = Reflect.getMetadata(API_OPERATION, method) as Record<string, any> | undefined
-  const description = operation
-    ? (typeof operation['summary'] === 'string' && operation['summary']
-      ? operation['summary']
-      : (typeof operation['description'] === 'string' ? operation['description'] : undefined))
-    : undefined
-
-  const parameters = (Reflect.getMetadata(API_PARAMETERS, method) as Array<Record<string, any>> | undefined) ?? []
-  const params: Record<string, FieldDesc> = {}
-  for (const p of parameters) {
-    const name = typeof p['name'] === 'string' ? p['name'] : undefined
-    if (!name) { continue }
-    params[name] = swaggerParamToField(p)
-  }
-
-  return { description, params }
-}

package/src/lib/silkweave.module.ts

@@ -1,75 +0,0 @@
-import { Inject, Module, type DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common'
-import { DiscoveryModule, HttpAdapterHost } from '@nestjs/core'
-import { createContext } from '@silkweave/core'
-import { ControllerDiscovery } from './controllerDiscovery.js'
-import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.js'
-
-/**
- * Root module for `@silkweave/nestjs`.
- *
- * Discovers every `@Mcp`-decorated **controller method** via `DiscoveryService`,
- * reflects each into a Silkweave action (input schema from the route + parameter
- * decorators + optional OpenAPI document; invocation by re-binding the validated
- * input back into the method), and registers the configured adapter(s) - `mcp()` -
- * directly on Nest's HTTP adapter inside `configure()`.
- *
- * Because `configure()` runs during `registerModules` - before Nest's
- * `registerRouter()` step - Silkweave's routes always sit ahead of every
- * controller in the Express stack. The controllers keep serving HTTP exactly as
- * before; `@Mcp` is purely additive.
- *
- * @example
- * ```ts
- * @Module({
- *   imports: [
- *     SilkweaveModule.forRoot({
- *       silkweave: { name: 'app', description: 'My App', version: '1.0.0' },
- *       adapters: [mcp({ basePath: '/mcp' })]
- *     })
- *   ],
- *   controllers: [ChannelsController]
- * })
- * export class AppModule {}
- * ```
- */
-@Module({})
-export class SilkweaveModule implements NestModule {
-  constructor(
-    @Inject(SILKWEAVE_MODULE_OPTIONS) private readonly options: SilkweaveModuleOptions,
-    private readonly discovery: ControllerDiscovery,
-    private readonly httpAdapterHost: HttpAdapterHost
-  ) { }
-
-  static forRoot(options: SilkweaveModuleOptions): DynamicModule {
-    return {
-      module: SilkweaveModule,
-      global: true,
-      imports: [DiscoveryModule],
-      providers: [
-        { provide: SILKWEAVE_MODULE_OPTIONS, useValue: options },
-        ControllerDiscovery
-      ],
-      exports: []
-    }
-  }
-
-  configure(_consumer: MiddlewareConsumer): void {
-    const httpAdapter = this.httpAdapterHost.httpAdapter
-    if (!httpAdapter) {
-      throw new Error('@silkweave/nestjs: HttpAdapterHost.httpAdapter is not available.')
-    }
-    const allActions = this.discovery.discover(this.options.openapi)
-    for (const adapter of this.options.adapters) {
-      const baseContext = createContext({ ...(this.options.context ?? {}), adapter: adapter.name })
-      const actions = adapter.allActions
-        ? allActions
-        : allActions.filter((a) => !a.isEnabled || a.isEnabled(baseContext))
-      adapter.register({
-        httpAdapter,
-        silkweaveOptions: this.options.silkweave,
-        baseContext,
-        actions
-      })
-    }
-  }
-}

package/src/lib/types.ts

@@ -1,61 +0,0 @@
-import type { HttpAdapterHost } from '@nestjs/core'
-import type { Action, SilkweaveContext, SilkweaveOptions } from '@silkweave/core'
-import type { OpenApiDocument } from './reflect/openapi.js'
-
-/**
- * Context passed to a Nest Silkweave adapter when `SilkweaveModule` wires it
- * up. Adapters register their routes directly on `httpAdapter` (no
- * placeholder middleware, no `silkweave()` builder), so they only fire
- * `register()` once and own the rest of their lifecycle implicitly through
- * Nest.
- */
-export interface NestAdapterRegisterContext {
-  /** Nest's underlying HTTP adapter (Express or Fastify). */
-  httpAdapter: NonNullable<HttpAdapterHost['httpAdapter']>
-  /** Identity the adapter surfaces to clients (e.g. MCP server name). */
-  silkweaveOptions: SilkweaveOptions
-  /** Per-adapter context - already forked with `{ adapter: adapter.name, ...userContext }`. */
-  baseContext: SilkweaveContext
-  /** Actions filtered to those enabled on this adapter. */
-  actions: Action[]
-}
-
-/**
- * A Silkweave Nest adapter. Each transport (REST, tRPC, MCP) implements this
- * shape. `register()` is called from `SilkweaveModule.configure()` - which
- * runs *before* Nest's controller routes are mapped - so adapter routes
- * always sit ahead of any catch-all controllers in the framework's request
- * pipeline.
- */
-export interface NestSilkweaveAdapter {
-  /** Adapter discriminator - set on the silkweave context as `ctx.get('adapter')`. */
-  readonly name: 'mcp'
-  /** URL prefix the adapter mounts on (e.g. `'/mcp'`). Surfaced for introspection. */
-  readonly basePath?: string
-  /**
-   * When `true`, the adapter receives every discovered action regardless of
-   * each action's `isEnabled` gate. Reserved for non-runtime adapters that need
-   * the entire action surface.
-   */
-  readonly allActions?: boolean
-  /** Register this adapter's routes on Nest's HTTP server. */
-  register(ctx: NestAdapterRegisterContext): void
-}
-
-export interface SilkweaveModuleOptions {
-  /** Identity for the silkweave instance - surfaced to MCP clients, OpenAPI, etc. */
-  silkweave: SilkweaveOptions
-  /** Adapters to mount. Currently `mcp()`. */
-  adapters: NestSilkweaveAdapter[]
-  /** Initial context keys merged into every adapter's `baseContext`. */
-  context?: Record<string, unknown>
-  /**
-   * Optional OpenAPI document (e.g. from `SwaggerModule.createDocument(app, cfg)`)
-   * used as an authoritative source when reflecting `@Mcp` tool input schemas.
-   * Matched to each method by HTTP verb + path; falls back to decorator
-   * reflection when an operation or field isn't present.
-   */
-  openapi?: OpenApiDocument
-}
-
-export const SILKWEAVE_MODULE_OPTIONS = '__silkweave_module_options__'

package/tsconfig.json

@@ -1,25 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022"],
-    "outDir": "build",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "allowSyntheticDefaultImports": true,
-    "resolveJsonModule": true,
-    "composite": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "useDefineForClassFields": false
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "build"]
-}