@silkweave/nestjs 1.11.0 → 2.0.0

package/src/adapter/rest.ts

@@ -1,161 +0,0 @@
-/* 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 { buildLogLevels, type Logger, type LogLevel } from '@silkweave/logger'
-import type { IncomingMessage, ServerResponse } from 'http'
-import { z } from 'zod/v4'
-import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
-
-const CONSOLE_LEVEL_MAP: Record<LogLevel, 'log' | 'info' | 'warn' | 'error'> = {
-  emergency: 'error',
-  alert: 'error',
-  critical: 'error',
-  error: 'error',
-  warning: 'warn',
-  notice: 'info',
-  info: 'info',
-  debug: 'log'
-}
-
-export interface RestAdapterOptions {
-  /** URL prefix joined to each action's path. e.g. `'/api'` → `POST /api/users/list`. Default: `'/api'`. */
-  basePath?: string
-  /** Optional bearer-token auth applied to every REST action. */
-  auth?: AuthConfig
-}
-
-interface RequestLike {
-  headers: Record<string, string | string[] | undefined>
-  body?: unknown
-  query?: unknown
-  url?: string
-  method?: string
-}
-
-function createRestLogger(): Logger {
-  return {
-    ...buildLogLevels((level, data) => { console[CONSOLE_LEVEL_MAP[level]](data) }),
-    progress: () => { /* progress notifications not supported on REST */ }
-  }
-}
-
-function actionNameToPath(name: string): string {
-  return `/${name.replace(/\./g, '/')}`
-}
-
-async function readJsonBody(req: IncomingMessage): Promise<unknown> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = []
-    req.on('data', (c: Buffer) => chunks.push(c))
-    req.on('end', () => {
-      if (chunks.length === 0) { return resolve({}) }
-      try {
-        resolve(JSON.parse(Buffer.concat(chunks).toString('utf-8')))
-      } catch (err) {
-        reject(err instanceof Error ? err : new Error('Unable to parse JSON body'))
-      }
-    })
-    req.on('error', reject)
-  })
-}
-
-function parseQuery(url: string | undefined): Record<string, string> {
-  if (!url) { return {} }
-  const qIndex = url.indexOf('?')
-  if (qIndex === -1) { return {} }
-  const params: Record<string, string> = {}
-  const search = new URLSearchParams(url.slice(qIndex + 1))
-  for (const [k, v] of search.entries()) { params[k] = v }
-  return params
-}
-
-function sendJson(res: ServerResponse, body: unknown, status: number): void {
-  if (res.headersSent) { return }
-  res.statusCode = status
-  res.setHeader('Content-Type', 'application/json')
-  res.end(JSON.stringify(body))
-}
-
-function handleRestError(err: unknown, res: ServerResponse): void {
-  if (err instanceof z.ZodError) {
-    sendJson(res, { error: 'validation_error', issues: err.issues }, 400)
-    return
-  }
-  if (err instanceof SilkweaveError) {
-    sendJson(res, { error: err.code, message: err.message }, err.statusCode)
-    return
-  }
-  if (err instanceof HttpException) {
-    const body = err.getResponse()
-    const payload = typeof body === 'string' ? { error: err.name, message: body } : body
-    sendJson(res, payload, err.getStatus())
-    return
-  }
-  console.error(err)
-  sendJson(res, { error: 'internal', message: 'Internal error' }, 500)
-}
-
-function createActionHandler(
-  action: Action,
-  context: SilkweaveContext,
-  auth: AuthConfig | undefined,
-  logger: Logger
-): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
-  return async (req, res) => {
-    try {
-      const reqLike = req as unknown as RequestLike
-      let authInfo: AuthInfo | undefined
-      if (auth) {
-        const authHeader = typeof reqLike.headers.authorization === 'string' ? reqLike.headers.authorization : undefined
-        const result = await validateToken(authHeader, auth, context.fork({ request: req }))
-        if (result.error) {
-          for (const [k, v] of Object.entries(result.error.headers)) { res.setHeader(k, v) }
-          sendJson(res, result.error.body, result.error.statusCode)
-          return
-        }
-        authInfo = result.auth
-      }
-      const raw = action.kind === 'query'
-        ? (reqLike.query ?? parseQuery(req.url))
-        : (reqLike.body ?? await readJsonBody(req))
-      const input = action.input.parse(raw) as object
-      const result = await action.run(input, context.fork({
-        logger,
-        request: req,
-        response: res,
-        ...(authInfo ? { auth: authInfo } : {})
-      }))
-      sendJson(res, result, 200)
-    } catch (err) {
-      handleRestError(err, res)
-    }
-  }
-}
-
-/**
- * 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)
- *
- * 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.
- */
-export function rest(options: RestAdapterOptions = {}): NestSilkweaveAdapter {
-  return {
-    name: 'rest',
-    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'
-        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/adapter/trpc.ts

@@ -1,58 +0,0 @@
-import { AuthConfig } from '@silkweave/auth'
-import { buildRouter, createActionLogger, resolveAuth, type TrpcHandlerContext } from '@silkweave/trpc'
-import { createExpressMiddleware } from '@trpc/server/adapters/express'
-import type { IncomingMessage, ServerResponse } from 'http'
-import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
-
-export interface TrpcAdapterOptions {
-  /** URL prefix at which the tRPC handler is mounted. Default `'/trpc'`. */
-  basePath?: string
-  /** Optional bearer-token auth applied to every tRPC procedure. */
-  auth?: AuthConfig
-}
-
-/**
- * tRPC adapter for `@silkweave/nestjs`. Builds a tRPC router from discovered
- * `@Action` methods and mounts the resulting express middleware at
- * `basePath` on Nest's HTTP adapter.
- *
- * Action names with dots (e.g. `users.list` from `@Actions('users')`) collapse
- * to camelCase procedure keys (`usersList`).
- *
- * Works on `@nestjs/platform-express`. On `@nestjs/platform-fastify`, register
- * `@fastify/express` first so Nest can serve Express-style middleware.
- */
-export function trpc(options: TrpcAdapterOptions = {}): NestSilkweaveAdapter {
-  return {
-    name: 'trpc',
-    register({ httpAdapter, baseContext, actions }: NestAdapterRegisterContext): void {
-      const basePath = (options.basePath ?? '/trpc').replace(/\/$/, '') || '/'
-      const router = buildRouter(actions)
-      const logger = createActionLogger()
-      const createContext = async (
-        opts: { req: IncomingMessage; res: ServerResponse }
-      ): Promise<TrpcHandlerContext> => {
-        const resolved = await resolveAuth(options.auth, opts.req.headers.authorization, baseContext.fork({ request: opts.req }))
-        if (resolved.kind === 'error') {
-          for (const [key, value] of Object.entries<string>(resolved.error.headers)) { opts.res.setHeader(key, value) }
-          opts.res.statusCode = resolved.error.statusCode
-          opts.res.setHeader('Content-Type', 'application/json')
-          opts.res.end(JSON.stringify(resolved.error.body))
-          throw new Error('Unauthorized')
-        }
-        return {
-          silkweaveContext: baseContext.fork({
-            logger,
-            request: opts.req,
-            response: opts.res,
-            ...(resolved.authInfo ? { auth: resolved.authInfo } : {})
-          })
-        }
-      }
-      const middleware = createExpressMiddleware({ router, createContext })
-      ;(httpAdapter as unknown as { use: (path: string, h: unknown) => unknown }).use(basePath, middleware)
-    }
-  }
-}
-
-export { type InferTrpcRouter } from '@silkweave/trpc'

package/src/adapter/typegen.ts

@@ -1,55 +0,0 @@
-import { renderTypegen, type TypegenFormat } from '@silkweave/typegen'
-import { mkdir, writeFile } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
-import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
-
-export interface TypegenAdapterOptions {
-  /** Output file path for the generated `.d.ts` file. Resolved against `process.cwd()`. Parent directories are created automatically. */
-  path: string
-  /**
-   * What to emit (default `'all'`):
-   * - `'interfaces'` - `{Name}Input` / `{Name}Output` interfaces per action
-   * - `'trpc-router'` - `AppRouter` type alias for `createTRPCClient<AppRouter>()`
-   * - `'all'` - both
-   */
-  format?: TypegenFormat
-  /**
-   * Whether to write the file at all. Default: `process.env.NODE_ENV !== 'production'`.
-   * Server processes generally shouldn't write to disk in production deploys -
-   * leave it on the default unless you know you want otherwise.
-   */
-  enabled?: boolean
-}
-
-/**
- * Typegen adapter for `@silkweave/nestjs`. Discovers every `@Action`-decorated
- * method (regardless of `transports` filtering) and writes a single `.d.ts`
- * file with REST input/output interfaces and/or a tRPC `AppRouter` type alias.
- *
- * Designed for the monorepo pattern where the server (this app) is the source
- * of truth for types and consumer apps import from `path` - e.g.
- * `path: '../app/src/types/silkweave.ts'`.
- */
-export function typegen(options: TypegenAdapterOptions): NestSilkweaveAdapter {
-  const enabled = options.enabled ?? (process.env['NODE_ENV'] !== 'production')
-  return {
-    name: 'typegen',
-    allActions: true,
-    register({ actions }: NestAdapterRegisterContext): void {
-      if (!enabled) { return }
-      const output = renderTypegen(actions, options.format ?? 'all')
-      const target = resolve(options.path)
-      // Fire-and-forget: we don't want to make `configure()` await disk IO and
-      // delay app startup. Errors are surfaced via console.
-      void (async () => {
-        try {
-          await mkdir(dirname(target), { recursive: true })
-          await writeFile(target, output, 'utf-8')
-          console.info(`@silkweave/nestjs typegen: wrote ${actions.length} action types to ${target}`)
-        } catch (err) {
-          console.error('@silkweave/nestjs typegen:', err)
-        }
-      })()
-    }
-  }
-}

package/src/decorator/action.ts

@@ -1,38 +0,0 @@
-import { SetMetadata } from '@nestjs/common'
-import { ACTION_METADATA, type ActionMetadata } from '../lib/metadata.js'
-
-/**
- * Method decorator that registers a Silkweave action.
- *
- * The decorated method becomes an Action and is exposed via every adapter
- * configured on `SilkweaveModule` (REST/tRPC/MCP), unless `transports` is
- * provided to restrict it.
- *
- * The method receives `(input, context)` where `input` is the parsed Zod input
- * and `context` is the `SilkweaveContext` (with `logger`, `request`, optional
- * `auth`). The class instance is a normal Nest provider, so other services can
- * be injected via the constructor.
- *
- * @example
- * ```ts
- * @Injectable()
- * @Actions('users')
- * export class UserActions {
- *   constructor(private db: DbService) {}
- *
- *   @Action({
- *     description: 'List users',
- *     input: z.object({ limit: z.number().optional() }),
- *     kind: 'query'
- *   })
- *   list(input: { limit?: number }, ctx: SilkweaveContext) {
- *     return this.db.listUsers(input.limit)
- *   }
- * }
- * ```
- */
-export function Action<I extends object = object, O extends object = object, C = unknown>(
-  options: ActionMetadata<I, O, C>
-): MethodDecorator {
-  return SetMetadata(ACTION_METADATA, options)
-}

package/src/decorator/actions.ts

@@ -1,25 +0,0 @@
-import { SetMetadata } from '@nestjs/common'
-import { ACTIONS_METADATA, type ActionsClassMetadata, type Transport } from '../lib/metadata.js'
-
-/**
- * Class decorator that groups a provider's `@Action` methods under a common
- * prefix. The prefix is joined to each method's action name with a dot
- * (e.g. `@Actions('users')` + method `list` → action name `users.list`).
- *
- * The class itself remains a normal Nest provider - add `@Injectable()`
- * separately so it can be resolved by the DI container.
- *
- * Accepts either a prefix string (shorthand) or a full options object:
- * ```ts
- * @Actions('users')
- * @Actions({ prefix: 'users', transports: ['rest', 'trpc'] })
- * ```
- */
-export function Actions(prefixOrOptions: string | ActionsClassMetadata = {}): ClassDecorator {
-  const options: ActionsClassMetadata = typeof prefixOrOptions === 'string'
-    ? { prefix: prefixOrOptions }
-    : prefixOrOptions
-  return SetMetadata(ACTIONS_METADATA, options)
-}
-
-export type { ActionsClassMetadata, Transport }

package/src/lib/discovery.ts

@@ -1,125 +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',
-        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',
-      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/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
-  }
-}