@silkweave/nestjs 1.12.0 → 2.2.0

package/src/index.ts

@@ -1,14 +0,0 @@
-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 './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

@@ -1,131 +0,0 @@
-/* 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 ActionKind, type SilkweaveContext, type StreamingActionInput } from '@silkweave/core'
-import { kebabCase } from 'change-case'
-import { buildIsEnabled } from './filter.js'
-import { collectGuards, runGuards } from './guards.js'
-import { ACTION_METADATA, ACTIONS_METADATA, type ActionMetadata, type ActionsClassMetadata } from './metadata.js'
-
-interface DiscoveredAction {
-  instance: object
-  classRef: Type<unknown>
-  method: (...args: unknown[]) => unknown
-  methodName: string
-  meta: ActionMetadata
-  classMeta: ActionsClassMetadata
-}
-
-@Injectable()
-export class ActionDiscovery {
-  constructor(
-    private readonly discovery: DiscoveryService,
-    private readonly scanner: MetadataScanner,
-    private readonly reflector: Reflector,
-    private readonly moduleRef: ModuleRef
-  ) { }
-
-  /**
-   * Walk every Nest provider, find methods annotated with `@Action`, and build
-   * 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 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[] = []
-    const wrappers = this.discovery.getProviders()
-    for (const wrapper of wrappers) {
-      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>
-      const classMeta = (this.reflector.get<ActionsClassMetadata>(ACTIONS_METADATA, classRef) ?? {})
-      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<ActionMetadata>(ACTION_METADATA, method)
-        if (!meta) { continue }
-        discovered.push({ instance, classRef, method, methodName, meta, classMeta })
-      }
-    }
-    return discovered.map((d) => this.toAction(d))
-  }
-
-  private toAction(d: DiscoveredAction): Action {
-    const baseName = d.meta.name ?? kebabCase(d.methodName)
-    const name = d.classMeta.prefix ? `${d.classMeta.prefix}.${baseName}` : baseName
-    const transports = d.meta.transports ?? d.classMeta.transports
-    const isEnabled = buildIsEnabled(transports, d.meta.isEnabled)
-    const guards = collectGuards(this.reflector, d.classRef, d.method)
-    const moduleRef = this.moduleRef
-    const reflector = this.reflector
-
-    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') ?? 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
-    // (zod@3.25 + zod@4.x can both be present transitively). Runtime is fine -
-    // they share the same /v4 surface - but the structural types are distinct.
-    const streaming = d.method.constructor?.name === 'AsyncGeneratorFunction'
-
-    if (streaming) {
-      if (!d.meta.chunk) {
-        throw new Error(`@Action "${name}" is an async generator but has no \`chunk\` schema`)
-      }
-      const method = d.method
-      const instance = d.instance
-      return createAction({
-        name,
-        description: d.meta.description,
-        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,
-        run: async function* (input: object, context: SilkweaveContext) {
-          await applyGuards(context)
-          yield* (method.call(instance, input, context) as AsyncGenerator<object, void, void>)
-        }
-      } as StreamingActionInput<object, unknown, string, ActionKind>) as Action
-    }
-
-    return createAction({
-      name,
-      description: d.meta.description,
-      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,
-      run: async (input: object, context: SilkweaveContext): Promise<object> => {
-        await applyGuards(context)
-        const result = await (d.method.call(d.instance, input, context) as Promise<object>)
-        return result
-      }
-    })
-  }
-}

package/src/lib/executionContext.ts

@@ -1,76 +0,0 @@
-import type { ArgumentsHost, ContextType, ExecutionContext, Type } from '@nestjs/common'
-
-/** Subset of `HttpArgumentsHost` we need - re-declared inline to avoid deep `@nestjs/common/interfaces` imports. */
-interface HttpHost {
-  getRequest<T = unknown>(): T
-  getResponse<T = unknown>(): T
-  getNext<T = unknown>(): T
-}
-
-interface RpcHost {
-  getData<T = unknown>(): T
-  getContext<T = unknown>(): T
-}
-
-interface WsHost {
-  getClient<T = unknown>(): T
-  getData<T = unknown>(): T
-  getPattern(): string
-}
-
-/**
- * Minimal `ExecutionContext` impl Nest guards can consume. We only need
- * `switchToHttp()` to work for our HTTP-backed transports; the RPC/WS shims are
- * stubbed so guards that introspect type can still call them without crashing.
- */
-export class SilkweaveExecutionContext implements ExecutionContext, ArgumentsHost {
-  constructor(
-    private readonly args: unknown[],
-    private readonly classRef: Type<unknown>,
-    private readonly handler: (...handlerArgs: unknown[]) => unknown,
-    private readonly contextType = 'http'
-  ) { }
-
-  getType<T extends string = ContextType>(): T {
-    return this.contextType as T
-  }
-
-  getClass<T = unknown>(): Type<T> {
-    return this.classRef as Type<T>
-  }
-
-  getHandler(): (...handlerArgs: unknown[]) => unknown {
-    return this.handler
-  }
-
-  getArgs<T extends unknown[] = unknown[]>(): T {
-    return this.args as T
-  }
-
-  getArgByIndex<T = unknown>(index: number): T {
-    return this.args[index] as T
-  }
-
-  switchToHttp(): HttpHost {
-    return {
-      getRequest: <T = unknown>(): T => this.args[0] as T,
-      getResponse: <T = unknown>(): T => this.args[1] as T,
-      getNext: <T = unknown>(): T => this.args[2] as T
-    }
-  }
-
-  switchToRpc(): RpcHost {
-    return {
-      getData: <T = unknown>(): T => this.args[0] as T,
-      getContext: <T = unknown>(): T => this.args[1] as T
-    }
-  }
-
-  switchToWs(): WsHost {
-    return {
-      getClient: <T = unknown>(): T => this.args[0] as T,
-      getData: <T = unknown>(): T => this.args[1] as T,
-      getPattern: (): string => ''
-    }
-  }
-}

package/src/lib/filter.ts

@@ -1,26 +0,0 @@
-import type { SilkweaveContext } from '@silkweave/core'
-import type { Transport } from './metadata.js'
-
-/**
- * Compile a `transports` allowlist + optional user `isEnabled` into a single
- * `(ctx) => boolean` callback compatible with `Action.isEnabled`.
- *
- * - If `transports` is omitted, the action runs on every adapter.
- * - If `transports` is set, the action is gated on `ctx.get<string>('adapter')`
- *   matching one of the listed transports. Each adapter in `@silkweave/nestjs`
- *   forks its context with `{ adapter: 'rest' | 'trpc' | 'mcp' }`.
- * - If both `transports` and `userIsEnabled` are set, they are AND-combined.
- */
-export function buildIsEnabled(
-  transports: Transport[] | undefined,
-  userIsEnabled: ((ctx: SilkweaveContext) => boolean) | undefined
-): ((ctx: SilkweaveContext) => boolean) | undefined {
-  if (!transports && !userIsEnabled) { return undefined }
-  return (ctx) => {
-    if (transports) {
-      const adapter = ctx.getOptional<string>('adapter')
-      if (adapter && !transports.includes(adapter as Transport)) { return false }
-    }
-    return userIsEnabled ? userIsEnabled(ctx) : true
-  }
-}

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,58 +0,0 @@
-import { type Action, type ActionKind, type HttpMethod, type SilkweaveContext } from '@silkweave/core'
-import type z from 'zod/v4'
-
-export const ACTION_METADATA = '__silkweave_action__'
-export const ACTIONS_METADATA = '__silkweave_actions__'
-
-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. */
-  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.
-   */
-  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']
-}
-
-export type AnyActionMetadata = ActionMetadata<object, object> & ResultToolResult<object>
-
-export const ACTION_RESPONSE_KEY = '__silkweave_response__'

package/src/lib/openapi.ts

@@ -1,116 +0,0 @@
-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/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 { ActionDiscovery } from './discovery.js'
-import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.js'
-
-/**
- * Root module for `@silkweave/nestjs`.
- *
- * Discovers every `@Action`-decorated method via `DiscoveryService` and
- * registers the configured adapters (`rest()`, `trpc()`, `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. There is
- * no slot middleware, no race with Nest's 404 catch-all, and every route
- * shows up in Nest's `RoutesResolver` logger.
- *
- * @example
- * ```ts
- * @Module({
- *   imports: [
- *     SilkweaveModule.forRoot({
- *       silkweave: { name: 'app', description: 'My App', version: '1.0.0' },
- *       adapters: [
- *         rest({ basePath: '/api' }),
- *         trpc({ basePath: '/trpc' }),
- *         mcp({ basePath: '/mcp' })
- *       ]
- *     })
- *   ]
- * })
- * export class AppModule {}
- * ```
- */
-@Module({})
-export class SilkweaveModule implements NestModule {
-  constructor(
-    @Inject(SILKWEAVE_MODULE_OPTIONS) private readonly options: SilkweaveModuleOptions,
-    private readonly discovery: ActionDiscovery,
-    private readonly httpAdapterHost: HttpAdapterHost
-  ) { }
-
-  static forRoot(options: SilkweaveModuleOptions): DynamicModule {
-    return {
-      module: SilkweaveModule,
-      global: true,
-      imports: [DiscoveryModule],
-      providers: [
-        { provide: SILKWEAVE_MODULE_OPTIONS, useValue: options },
-        ActionDiscovery
-      ],
-      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()
-    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/swagger.ts

@@ -1,74 +0,0 @@
-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' }))
-}