@silkweave/nestjs 1.9.0

package/src/lib/executionContext.ts

@@ -0,0 +1,76 @@
+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: string = '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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,64 @@
+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 moduleRef.get(ref, { strict: false })
+    } catch {
+      return moduleRef.create(ref)
+    }
+  }
+  return ref
+}
+
+/**
+ * Run the configured guards against an HTTP 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`.
+ */
+export async function runGuards(
+  guards: GuardRef[],
+  moduleRef: ModuleRef,
+  reflector: Reflector,
+  classRef: Type<unknown>,
+  handler: (...args: unknown[]) => unknown,
+  request: unknown,
+  response: unknown
+): Promise<void> {
+  if (guards.length === 0) { return }
+  const context = new SilkweaveExecutionContext([request, response], classRef, handler, 'http')
+  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

@@ -0,0 +1,45 @@
+import { type Action, type ActionKind, 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> {
+  /** 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> }
+  /** `'query'` (GET in REST, `.query()` in tRPC) or `'mutation'` (POST in REST, `.mutation()` in tRPC). Default: `'mutation'`. */
+  kind?: ActionKind
+  /** 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/silkweave.module.ts

@@ -0,0 +1,52 @@
+import { Module, type DynamicModule } from '@nestjs/common'
+import { DiscoveryModule } from '@nestjs/core'
+import { ActionDiscovery } from './discovery.js'
+import { SilkweaveService } from './silkweave.service.js'
+import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.js'
+
+/**
+ * Root module for `@silkweave/nestjs`.
+ *
+ * Discovers every `@Action`-decorated method across the Nest app via
+ * `DiscoveryService`, builds core `Action` objects from them, and mounts the
+ * configured adapters (`rest()`, `trpc()`, `mcp()`) onto Nest's running HTTP
+ * server during `OnApplicationBootstrap`.
+ *
+ * @example
+ * ```ts
+ * import { Module } from '@nestjs/common'
+ * import { SilkweaveModule, rest, trpc, mcp } from '@silkweave/nestjs'
+ * import { UsersModule } from './users.module.js'
+ *
+ * @Module({
+ *   imports: [
+ *     SilkweaveModule.forRoot({
+ *       silkweave: { name: 'app', description: 'My App', version: '1.0.0' },
+ *       adapters: [
+ *         rest({ basePath: '/api' }),
+ *         trpc({ basePath: '/trpc' }),
+ *         mcp({ basePath: '/mcp' })
+ *       ]
+ *     }),
+ *     UsersModule
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
+@Module({})
+export class SilkweaveModule {
+  static forRoot(options: SilkweaveModuleOptions): DynamicModule {
+    return {
+      module: SilkweaveModule,
+      global: true,
+      imports: [DiscoveryModule],
+      providers: [
+        { provide: SILKWEAVE_MODULE_OPTIONS, useValue: options },
+        ActionDiscovery,
+        SilkweaveService
+      ],
+      exports: [SilkweaveService]
+    }
+  }
+}

package/src/lib/silkweave.service.ts

@@ -0,0 +1,58 @@
+import { Inject, Injectable, type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleInit } from '@nestjs/common'
+import { HttpAdapterHost } from '@nestjs/core'
+import { type AdapterGenerator, silkweave as createSilkweave, type Silkweave } from '@silkweave/core'
+import { ActionDiscovery } from './discovery.js'
+import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.js'
+
+/**
+ * Coordinates the Nest lifecycle for `@silkweave/nestjs`:
+ *
+ * - `onModuleInit`: each configured adapter calls `install(host)` to reserve a
+ *   placeholder middleware slot at its base path. This must happen here, not
+ *   in `onApplicationBootstrap`, because Nest installs its 404 catch-all later
+ *   during `init()` — routes registered after the catch-all are unreachable.
+ *
+ * - `onApplicationBootstrap`: discovers every `@Action` method, then drives the
+ *   standard `silkweave().adapter(...).actions(...).start()` flow, which calls
+ *   each adapter's `start(actions)` to populate the slot reserved earlier.
+ */
+@Injectable()
+export class SilkweaveService implements OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown {
+  private builder?: Silkweave
+  private readonly generators: AdapterGenerator[] = []
+
+  constructor(
+    @Inject(SILKWEAVE_MODULE_OPTIONS) private readonly options: SilkweaveModuleOptions,
+    private readonly discovery: ActionDiscovery,
+    private readonly httpAdapterHost: HttpAdapterHost
+  ) {}
+
+  onModuleInit(): void {
+    for (const adapter of this.options.adapters) {
+      this.generators.push(adapter.install(this.httpAdapterHost))
+    }
+  }
+
+  async onApplicationBootstrap(): Promise<void> {
+    const actions = this.discovery.discover()
+    const builder = createSilkweave(this.options.silkweave)
+    for (const [key, value] of Object.entries(this.options.context ?? {})) {
+      builder.set(key, value)
+    }
+    for (const gen of this.generators) {
+      builder.adapter(gen)
+    }
+    builder.actions(actions)
+    await builder.start()
+    this.builder = builder
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    this.builder = undefined
+  }
+
+  /** Access the underlying silkweave builder once bootstrap has completed. */
+  getBuilder(): Silkweave | undefined {
+    return this.builder
+  }
+}

package/src/lib/slot.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from 'http'
+
+export type NodeMiddleware = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  next?: (err?: unknown) => void
+) => unknown
+
+/**
+ * A mountable middleware slot that delegates to a settable handler. Used to
+ * reserve a path on Nest's HTTP server *before* its 404 catch-all is
+ * installed, then populate the real handler later in `OnApplicationBootstrap`.
+ *
+ * Before `set()` is called, the slot responds with HTTP 503.
+ */
+export interface MiddlewareSlot {
+  middleware: NodeMiddleware
+  set(handler: NodeMiddleware): void
+}
+
+export function createMiddlewareSlot(label: string): MiddlewareSlot {
+  let handler: NodeMiddleware = (_req, res) => {
+    res.statusCode = 503
+    res.setHeader('Content-Type', 'application/json')
+    res.end(JSON.stringify({ error: 'not_ready', message: `${label} adapter has not started yet` }))
+  }
+  return {
+    middleware: (req, res, next) => handler(req, res, next),
+    set: (h) => { handler = h }
+  }
+}
+
+interface HttpAdapterUseLike {
+  use(path: string, handler: NodeMiddleware): unknown
+}
+
+/**
+ * Mount a middleware slot at the given base path on Nest's HTTP adapter and
+ * return the slot's `set()` callback. The slot middleware is installed
+ * synchronously so it sits in the Express stack before Nest's later-installed
+ * 404 catch-all.
+ */
+export function reserveSlot(
+  httpAdapter: HttpAdapterUseLike,
+  basePath: string,
+  label: string
+): (handler: NodeMiddleware) => void {
+  const slot = createMiddlewareSlot(label)
+  httpAdapter.use(basePath, slot.middleware)
+  return slot.set
+}

package/src/lib/types.ts

@@ -0,0 +1,37 @@
+import type { HttpAdapterHost } from '@nestjs/core'
+import type { AdapterGenerator, SilkweaveOptions } from '@silkweave/core'
+
+/**
+ * A Silkweave NestJS adapter. Each transport (REST, tRPC, MCP) implements this
+ * shape: given a Nest `HttpAdapterHost`, it (a) immediately mounts a
+ * placeholder middleware slot on Nest's running HTTP server during
+ * `OnModuleInit` — which is critical because Nest installs its 404 catch-all
+ * later in `init()`, before `OnApplicationBootstrap` fires; routes registered
+ * after the catch-all are unreachable — and (b) returns a core
+ * `AdapterGenerator` whose `start(actions)` populates that slot with the real
+ * handler.
+ *
+ * Adapters mount onto Nest's HTTP server instead of owning their own, so Nest
+ * middleware, lifecycle hooks, and request scoping remain coherent.
+ */
+export interface NestSilkweaveAdapter {
+  /** Adapter discriminator — set on the silkweave context as `ctx.get('adapter')`. */
+  readonly name: 'rest' | 'trpc' | 'mcp'
+  /**
+   * Reserve the adapter's route prefix on the Nest HTTP server *now* (before
+   * Nest's 404 catch-all is installed) and return the core `AdapterGenerator`
+   * that will populate the slot during `silkweave().start()`.
+   */
+  install(host: HttpAdapterHost): AdapterGenerator
+}
+
+export interface SilkweaveModuleOptions {
+  /** Identity for the silkweave instance — surfaced to MCP clients, OpenAPI, etc. */
+  silkweave: SilkweaveOptions
+  /** Adapters to mount. Examples: `rest()`, `trpc()`, `mcp()`. */
+  adapters: NestSilkweaveAdapter[]
+  /** Initial context keys (equivalent to chaining `.set(key, value)` on the builder). */
+  context?: Record<string, unknown>
+}
+
+export const SILKWEAVE_MODULE_OPTIONS = '__silkweave_module_options__'

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "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"]
+}