@silkweave/nestjs 1.9.0 → 1.10.0

package/src/lib/guards.ts

@@ -24,7 +24,7 @@ export function collectGuards(
 async function resolveGuard(ref: GuardRef, moduleRef: ModuleRef): Promise<CanActivate> {
   if (typeof ref === 'function') {
     try {
-      return moduleRef.get(ref, { strict: false })
+      return await moduleRef.get(ref, { strict: false })
     } catch {
       return moduleRef.create(ref)
     }
@@ -59,6 +59,6 @@ export async function runGuards(
       throw new ForbiddenException('Forbidden resource')
     }
   }
-  // Reflector kept in the signature for future use (e.g., per-guard metadata) — unused here.
+  // Reflector kept in the signature for future use (e.g., per-guard metadata) - unused here.
   void reflector
 }

package/src/lib/metadata.ts

@@ -6,7 +6,7 @@ export const ACTIONS_METADATA = '__silkweave_actions__'
 
 export type Transport = 'rest' | 'trpc' | 'mcp'
 
-export interface ActionMetadata<I extends object = object, O extends object = object> {
+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. */
@@ -15,6 +15,13 @@ export interface ActionMetadata<I extends object = object, O extends object = ob
   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
   /** Allowlist of transports that should expose this action. Default: all registered transports. */

package/src/lib/silkweave.module.ts

@@ -1,23 +1,22 @@
-import { Module, type DynamicModule } from '@nestjs/common'
-import { DiscoveryModule } from '@nestjs/core'
+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 { 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`.
+ * 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
- * import { Module } from '@nestjs/common'
- * import { SilkweaveModule, rest, trpc, mcp } from '@silkweave/nestjs'
- * import { UsersModule } from './users.module.js'
- *
  * @Module({
  *   imports: [
  *     SilkweaveModule.forRoot({
@@ -27,15 +26,20 @@ import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.j
  *         trpc({ basePath: '/trpc' }),
  *         mcp({ basePath: '/mcp' })
  *       ]
- *     }),
- *     UsersModule
+ *     })
  *   ]
  * })
  * export class AppModule {}
  * ```
  */
 @Module({})
-export class SilkweaveModule {
+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,
@@ -43,10 +47,29 @@ export class SilkweaveModule {
       imports: [DiscoveryModule],
       providers: [
         { provide: SILKWEAVE_MODULE_OPTIONS, useValue: options },
-        ActionDiscovery,
-        SilkweaveService
+        ActionDiscovery
       ],
-      exports: [SilkweaveService]
+      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/types.ts

@@ -1,36 +1,51 @@
 import type { HttpAdapterHost } from '@nestjs/core'
-import type { AdapterGenerator, SilkweaveOptions } from '@silkweave/core'
+import type { Action, SilkweaveContext, 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.
+ * 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: 'rest' | 'trpc' | 'mcp'
+  /** Adapter discriminator - set on the silkweave context as `ctx.get('adapter')`. */
+  readonly name: 'rest' | 'trpc' | 'mcp' | 'typegen'
   /**
-   * 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()`.
+   * When `true`, the adapter receives every discovered action regardless of
+   * each action's `transports` allowlist / `isEnabled` gate. Used by
+   * non-runtime adapters like `typegen()` that emit types for the entire
+   * action surface.
    */
-  install(host: HttpAdapterHost): AdapterGenerator
+  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. */
+  /** 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). */
+  /** Initial context keys merged into every adapter's `baseContext`. */
   context?: Record<string, unknown>
 }