@silkweave/nestjs 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silkweave/nestjs",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Silkweave NestJS Adapter",
   "repository": {
     "type": "git",
@@ -11,7 +11,13 @@
   "main": "build/index.mjs",
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
-    "@nestjs/core": "^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"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/swagger": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@trpc/server": "^11.7.1",
@@ -19,17 +25,18 @@
     "cors": "^2.8.6",
     "express": "^5.2.1",
     "zod": "^3.25.0",
-    "@silkweave/auth": "1.10.0",
-    "@silkweave/core": "1.10.0",
-    "@silkweave/trpc": "1.10.0",
-    "@silkweave/mcp": "1.10.0",
-    "@silkweave/logger": "1.10.0",
-    "@silkweave/typegen": "1.10.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"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
+    "@nestjs/swagger": "^11.0.0",
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",

package/src/adapter/rest.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 import { HttpException } from '@nestjs/common'
 import { AuthConfig, AuthInfo, validateToken } from '@silkweave/auth'
-import { type Action, type SilkweaveContext, SilkweaveError } from '@silkweave/core'
+import { type Action, actionMethod, methodHasBody, resolveActionInput, type SilkweaveContext, SilkweaveError, validateActionRouting } from '@silkweave/core'
 import { buildLogLevels, type Logger, type LogLevel } from '@silkweave/logger'
 import type { IncomingMessage, ServerResponse } from 'http'
 import { z } from 'zod/v4'
@@ -28,7 +28,8 @@ export interface RestAdapterOptions {
 interface RequestLike {
   headers: Record<string, string | string[] | undefined>
   body?: unknown
-  query?: unknown
+  query?: Record<string, unknown>
+  params?: Record<string, string | undefined>
   url?: string
   method?: string
 }
@@ -116,9 +117,11 @@ function createActionHandler(
         }
         authInfo = result.auth
       }
-      const raw = action.kind === 'query'
-        ? (reqLike.query ?? parseQuery(req.url))
-        : (reqLike.body ?? await readJsonBody(req))
+      const query = reqLike.query ?? parseQuery(req.url)
+      const body = methodHasBody(actionMethod(action))
+        ? (reqLike.body ?? await readJsonBody(req))
+        : undefined
+      const raw = resolveActionInput(action, { params: reqLike.params, query, body })
       const input = action.input.parse(raw) as object
       const result = await action.run(input, context.fork({
         logger,
@@ -137,22 +140,31 @@ function createActionHandler(
  * REST adapter for `@silkweave/nestjs`. Registers each discovered `@Action`
  * as an individual route on Nest's HTTP adapter:
  *
- * - `kind: 'query'` → `GET ${basePath}/${actionName-with-slashes}` (input from query string)
- * - `kind: 'mutation'` → `POST ${basePath}/${actionName-with-slashes}` (input from JSON body)
+ * - HTTP verb comes from `method`, else `GET` for `kind: 'query'`, else `POST`.
+ * - Path comes from `path` (joined to `basePath`, may contain `:param`
+ *   placeholders), else `${basePath}/${actionName-with-slashes}`.
+ * - Input is merged from the request body, the `queryParams` query-string
+ *   fields, and any `:param` path placeholders (see `resolveActionInput`).
  *
- * Routes show up in Nest's `RoutesResolver` logger and are eligible for
- * `@nestjs/swagger` scanning. Works on `@nestjs/platform-express` out of the
- * box. For `@nestjs/platform-fastify`, register `@fastify/express` first.
+ * Routes show up in Nest's `RoutesResolver` logger. They are registered
+ * directly on the HTTP adapter (not as Nest controllers), so `@nestjs/swagger`'s
+ * controller scanner does not see them - use `addSilkweaveActions()` to add them
+ * to the OpenAPI document. Works on `@nestjs/platform-express` out of the box.
+ * For `@nestjs/platform-fastify`, register `@fastify/express` first.
  */
 export function rest(options: RestAdapterOptions = {}): NestSilkweaveAdapter {
+  const basePath = (options.basePath ?? '/api').replace(/\/$/, '')
   return {
     name: 'rest',
+    basePath,
     register({ httpAdapter, baseContext, actions }: NestAdapterRegisterContext): void {
-      const basePath = (options.basePath ?? '/api').replace(/\/$/, '')
       const logger = createRestLogger()
       for (const action of actions) {
-        const path = `${basePath}${actionNameToPath(action.name)}`
-        const method = action.kind === 'query' ? 'get' : 'post'
+        validateActionRouting(action)
+        const path = action.path
+          ? `${basePath}/${action.path.replace(/^\//, '')}`
+          : `${basePath}${actionNameToPath(action.name)}`
+        const method = actionMethod(action).toLowerCase()
         const handler = createActionHandler(action, baseContext, options.auth, logger)
           ; (httpAdapter as unknown as Record<string, (path: string, h: typeof handler) => unknown>)[method](path, handler)
       }

package/src/index.ts

@@ -8,5 +8,7 @@ export * from './lib/discovery.js'
 export * from './lib/filter.js'
 export * from './lib/guards.js'
 export * from './lib/metadata.js'
+export * from './lib/openapi.js'
 export * from './lib/silkweave.module.js'
+export * from './lib/swagger.js'
 export * from './lib/types.js'

package/src/lib/discovery.ts

@@ -30,9 +30,10 @@ export class ActionDiscovery {
    * a list of core `Action` objects ready to feed into `silkweave().actions()`.
    *
    * Action invocation is wrapped to (a) run `@UseGuards` guards declared on the
-   * method or its class against the incoming HTTP request (read from
-   * `ctx.get('request')`) and (b) bind `this` to the resolved Nest provider so
-   * DI-injected dependencies remain available.
+   * method or its class against the incoming request (read from
+   * `ctx.get('request')`, populated by REST/tRPC and by MCP-over-HTTP from the
+   * SDK's `extra.requestInfo`) and (b) bind `this` to the resolved Nest provider
+   * so DI-injected dependencies remain available.
    */
   discover(): Action[] {
     const discovered: DiscoveredAction[] = []
@@ -66,9 +67,16 @@ export class ActionDiscovery {
 
     const applyGuards = async (context: SilkweaveContext): Promise<void> => {
       if (guards.length === 0) { return }
+      // REST and tRPC populate `request`/`response`; MCP-over-HTTP populates
+      // `request` (a `{ headers, url, params, query }` stand-in built from the
+      // SDK's `extra.requestInfo`). Transports with no HTTP request at all (e.g.
+      // MCP stdio) get a header-less stand-in so guards reading `req.headers`
+      // degrade gracefully (deny) instead of dereferencing `undefined`.
       const request = context.getOptional<unknown>('request')
-      const response = context.getOptional<unknown>('response')
-      await runGuards(guards, moduleRef, reflector, d.classRef, d.method, request, response)
+      const response = context.getOptional<unknown>('response') ?? null
+      const hasRequest = request != null
+      const guardRequest = hasRequest ? request : { headers: {}, params: {}, query: {} }
+      await runGuards(guards, moduleRef, reflector, d.classRef, d.method, guardRequest, response, hasRequest ? 'http' : 'rpc')
     }
 
     // Cast at the createAction boundary to bridge dual-zod-version installs
@@ -88,6 +96,9 @@ export class ActionDiscovery {
         input: d.meta.input,
         chunk: d.meta.chunk,
         kind: d.meta.kind ?? 'mutation',
+        method: d.meta.method,
+        path: d.meta.path,
+        queryParams: d.meta.queryParams,
         args: d.meta.args,
         isEnabled,
         toolResult: d.meta.toolResult,
@@ -104,6 +115,9 @@ export class ActionDiscovery {
       input: d.meta.input,
       output: d.meta.output,
       kind: d.meta.kind ?? 'mutation',
+      method: d.meta.method,
+      path: d.meta.path,
+      queryParams: d.meta.queryParams,
       args: d.meta.args,
       isEnabled,
       toolResult: d.meta.toolResult,

package/src/lib/guards.ts

@@ -33,12 +33,17 @@ async function resolveGuard(ref: GuardRef, moduleRef: ModuleRef): Promise<CanAct
 }
 
 /**
- * Run the configured guards against an HTTP request. Throws `ForbiddenException`
+ * 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[],
@@ -47,10 +52,11 @@ export async function runGuards(
   classRef: Type<unknown>,
   handler: (...args: unknown[]) => unknown,
   request: unknown,
-  response: unknown
+  response: unknown,
+  contextType: 'http' | 'rpc' = 'http'
 ): Promise<void> {
   if (guards.length === 0) { return }
-  const context = new SilkweaveExecutionContext([request, response], classRef, handler, 'http')
+  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)

package/src/lib/metadata.ts

@@ -1,4 +1,4 @@
-import { type Action, type ActionKind, type SilkweaveContext } from '@silkweave/core'
+import { type Action, type ActionKind, type HttpMethod, type SilkweaveContext } from '@silkweave/core'
 import type z from 'zod/v4'
 
 export const ACTION_METADATA = '__silkweave_action__'
@@ -24,6 +24,12 @@ export interface ActionMetadata<I extends object = object, O extends object = ob
   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. */

package/src/lib/openapi.ts

@@ -0,0 +1,116 @@
+import { type Action, actionMethod, methodHasBody, pathParamNames } from '@silkweave/core'
+import { camelCase } from 'change-case'
+import { z } from 'zod/v4'
+
+export interface ActionPathsOptions {
+  /** URL prefix the `rest()` adapter mounts on. Default `'/api'`. */
+  basePath?: string
+  /** OpenAPI tag the actions are grouped under. Default `'Actions'`. */
+  tag?: string
+}
+
+interface JsonSchemaObject {
+  properties?: Record<string, unknown>
+  required?: string[]
+}
+
+/** Convert a route template's `:param` placeholders to OpenAPI `{param}` form. */
+function toOpenApiPath(template: string): string {
+  return template.replace(/:([A-Za-z0-9_]+)/g, '{$1}')
+}
+
+/** The OpenAPI path key for an action - mirrors the `rest()` adapter's routing. */
+function actionRoute(action: Action, basePath: string): string {
+  const sub = action.path ? action.path.replace(/^\//, '') : action.name.replace(/\./g, '/')
+  return toOpenApiPath(`${basePath}/${sub}`.replace(/\/{2,}/g, '/'))
+}
+
+/** `z.toJSONSchema` tags a top-level `$schema`; drop it for a tidy OpenAPI doc. */
+function toJsonSchema(schema: z.ZodType): Record<string, unknown> {
+  const { $schema: _schema, ...rest } = z.toJSONSchema(schema) as Record<string, unknown>
+  return rest
+}
+
+function responseSchema(action: Action): unknown {
+  if (action.output) { return toJsonSchema(action.output) }
+  if (action.chunk) { return { type: 'array', items: toJsonSchema(action.chunk) } }
+  return undefined
+}
+
+interface SourceSplit {
+  parameters: Array<Record<string, unknown>>
+  bodyProps: Record<string, unknown>
+  bodyRequired: string[]
+}
+
+/** Split an action's input fields into OpenAPI path/query parameters and a body, matching the `rest()` adapter. */
+function splitInputSources(action: Action, hasBody: boolean): SourceSplit {
+  const json = z.toJSONSchema(action.input) as JsonSchemaObject
+  const required = new Set(json.required ?? [])
+  const pathParams = new Set(pathParamNames(action.path))
+  const queryKeys = new Set((action.queryParams ?? []).map(String))
+
+  const split: SourceSplit = { parameters: [], bodyProps: {}, bodyRequired: [] }
+  for (const [key, schema] of Object.entries(json.properties ?? {})) {
+    if (pathParams.has(key)) {
+      split.parameters.push({ name: key, in: 'path', required: true, schema })
+    } else if (!hasBody || queryKeys.has(key)) {
+      split.parameters.push({ name: key, in: 'query', required: required.has(key), schema })
+    } else {
+      split.bodyProps[key] = schema
+      if (required.has(key)) { split.bodyRequired.push(key) }
+    }
+  }
+  return split
+}
+
+/** Build the OpenAPI operation object for a single action. */
+function buildOperation(action: Action, tag: string): Record<string, unknown> {
+  const hasBody = methodHasBody(actionMethod(action))
+  const { parameters, bodyProps, bodyRequired } = splitInputSources(action, hasBody)
+  const response = responseSchema(action)
+
+  const operation: Record<string, unknown> = {
+    tags: [tag],
+    summary: action.description,
+    operationId: camelCase(action.name),
+    responses: {
+      200: {
+        description: 'Successful response',
+        ...(response ? { content: { 'application/json': { schema: response } } } : {})
+      }
+    }
+  }
+  if (parameters.length) { operation.parameters = parameters }
+  if (hasBody && Object.keys(bodyProps).length) {
+    operation.requestBody = {
+      required: bodyRequired.length > 0,
+      content: { 'application/json': { schema: { type: 'object', properties: bodyProps, required: bodyRequired } } }
+    }
+  }
+  return operation
+}
+
+/**
+ * Build an OpenAPI `paths` fragment for a set of Silkweave actions, mirroring
+ * exactly how the `rest()` adapter routes them: the same HTTP verb (`method` ??
+ * `kind`), the same `path`/`name`-derived route, and the same path/query/body
+ * field split (`pathParamNames` + `queryParams`). Schemas are inlined from the
+ * Zod input/output via `z.toJSONSchema`; no shared components are emitted.
+ */
+export function buildActionPaths(
+  actions: Action[],
+  options: ActionPathsOptions = {}
+): Record<string, Record<string, unknown>> {
+  const basePath = (options.basePath ?? '/api').replace(/\/$/, '')
+  const tag = options.tag ?? 'Actions'
+  const paths: Record<string, Record<string, unknown>> = {}
+
+  for (const action of actions) {
+    const method = actionMethod(action).toLowerCase()
+    const route = actionRoute(action, basePath)
+    paths[route] = { ...(paths[route] ?? {}), [method]: buildOperation(action, tag) }
+  }
+
+  return paths
+}

package/src/lib/swagger.ts

@@ -0,0 +1,74 @@
+import { type INestApplication } from '@nestjs/common'
+import type { OpenAPIObject } from '@nestjs/swagger'
+import { type Action, createContext } from '@silkweave/core'
+import { ActionDiscovery } from './discovery.js'
+import { buildActionPaths } from './openapi.js'
+import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.js'
+
+export interface SilkweaveSwaggerOptions {
+  /**
+   * URL prefix the `rest()` adapter mounts on. Defaults to the configured
+   * `rest()` adapter's `basePath`, falling back to `'/api'`.
+   */
+  basePath?: string
+  /** OpenAPI tag the actions are grouped under. Default `'Actions'`. */
+  tag?: string
+  /**
+   * Include actions that are *not* enabled on the REST transport (gated out via
+   * `transports` / `isEnabled`). Default `false` - the document mirrors the
+   * routes the `rest()` adapter actually registers.
+   */
+  includeDisabled?: boolean
+}
+
+/**
+ * Merge every REST-exposed Silkweave `@Action` into a NestJS Swagger
+ * `OpenAPIObject`.
+ *
+ * `@nestjs/swagger` builds its document by scanning **controllers**, but
+ * Silkweave registers action routes directly on the HTTP adapter (so they sit
+ * ahead of controllers in the request pipeline) - which means the scanner never
+ * sees them. This helper closes that gap: it discovers the actions through the
+ * same `ActionDiscovery` provider the `rest()` adapter uses, builds OpenAPI
+ * paths with the same routing logic (`buildActionPaths`), and merges them into
+ * the document. The result stays in sync with the live routes without any
+ * dynamic controllers.
+ *
+ * Call it between `SwaggerModule.createDocument()` and `SwaggerModule.setup()`:
+ *
+ * @example
+ * ```ts
+ * const document = SwaggerModule.createDocument(app, config)
+ * addSilkweaveActions(app, document)
+ * SwaggerModule.setup('api/docs', app, document)
+ * ```
+ */
+export function addSilkweaveActions(
+  app: INestApplication,
+  document: OpenAPIObject,
+  options: SilkweaveSwaggerOptions = {}
+): OpenAPIObject {
+  const discovery = app.get(ActionDiscovery)
+  const moduleOptions = app.get<SilkweaveModuleOptions>(SILKWEAVE_MODULE_OPTIONS)
+  const restAdapter = moduleOptions.adapters.find((adapter) => adapter.name === 'rest')
+  const basePath = options.basePath ?? restAdapter?.basePath ?? '/api'
+
+  const allActions = discovery.discover()
+  const actions = options.includeDisabled
+    ? allActions
+    : allActions.filter((action) => isRestEnabled(action, moduleOptions))
+
+  const paths = buildActionPaths(actions, { basePath, tag: options.tag })
+
+  document.paths ??= {}
+  for (const [route, item] of Object.entries(paths)) {
+    document.paths[route] = { ...(document.paths[route] ?? {}), ...item }
+  }
+  return document
+}
+
+/** Whether an action would be registered by the `rest()` adapter (adapter: 'rest'). */
+function isRestEnabled(action: Action, moduleOptions: SilkweaveModuleOptions): boolean {
+  if (!action.isEnabled) { return true }
+  return action.isEnabled(createContext({ ...(moduleOptions.context ?? {}), adapter: 'rest' }))
+}

package/src/lib/types.ts

@@ -29,6 +29,12 @@ export interface NestAdapterRegisterContext {
 export interface NestSilkweaveAdapter {
   /** Adapter discriminator - set on the silkweave context as `ctx.get('adapter')`. */
   readonly name: 'rest' | 'trpc' | 'mcp' | 'typegen'
+  /**
+   * URL prefix the adapter mounts on (e.g. `'/api'`). Surfaced for introspection
+   * tooling such as `addSilkweaveActions()` (OpenAPI/Swagger), which reads it to
+   * keep generated docs aligned with the live routes.
+   */
+  readonly basePath?: string
   /**
    * When `true`, the adapter receives every discovered action regardless of
    * each action's `transports` allowlist / `isEnabled` gate. Used by