@silkweave/nestjs 1.11.0 → 1.12.0

package/.turbo/turbo-build.log

@@ -1,17 +1,16 @@
-$ tsdown
-ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
-ℹ config file: /Users/atomic/projects/silkweave/silkweave/packages/nestjs/tsdown.config.ts 
-ℹ entry: src/index.ts
-ℹ tsconfig: tsconfig.json
-ℹ Build start
-ℹ Cleaning 4 files
-ℹ Hint: consider adding deps.onlyBundle option to avoid unintended bundling of dependencies, or set deps.onlyBundle: false to disable this hint.
-See more at https://tsdown.dev/options/dependencies#deps-onlybundle
-Detected dependencies in bundle:
-- rxjs
-ℹ build/index.mjs        338.49 kB │ gzip: 49.77 kB
-ℹ build/index.mjs.map    577.61 kB │ gzip: 87.77 kB
-ℹ build/index.d.mts.map    2.99 kB │ gzip:  1.07 kB
-ℹ build/index.d.mts       16.35 kB │ gzip:  5.75 kB
-ℹ 4 files, total: 935.45 kB
-✔ Build complete in 742ms
+$ tsdown
+ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
+ℹ config file: /Users/atomic/projects/silkweave/silkweave/packages/nestjs/tsdown.config.ts 
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ Hint: consider adding deps.onlyBundle option to avoid unintended bundling of dependencies, or set deps.onlyBundle: false to disable this hint.
+See more at https://tsdown.dev/options/dependencies#deps-onlybundle
+Detected dependencies in bundle:
+- rxjs
+ℹ build/index.mjs        339.14 kB │ gzip: 49.99 kB
+ℹ build/index.mjs.map    579.22 kB │ gzip: 88.28 kB
+ℹ build/index.d.mts.map    3.06 kB │ gzip:  1.10 kB
+ℹ build/index.d.mts       17.08 kB │ gzip:  6.02 kB
+ℹ 4 files, total: 938.50 kB
+✔ Build complete in 1034ms

package/.turbo/turbo-prepack.log

@@ -1,5 +1,4 @@
-
-$ pnpm clean && pnpm build
+$ pnpm clean && pnpm build
 $ rimraf build
 $ tsdown
 ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
@@ -11,9 +10,9 @@
 See more at https://tsdown.dev/options/dependencies#deps-onlybundle
 Detected dependencies in bundle:
 - rxjs
-ℹ build/index.mjs        337.92 kB │ gzip: 49.52 kB
-ℹ build/index.mjs.map    576.49 kB │ gzip: 87.36 kB
-ℹ build/index.d.mts.map    2.98 kB │ gzip:  1.07 kB
-ℹ build/index.d.mts       15.96 kB │ gzip:  5.58 kB
-ℹ 4 files, total: 933.34 kB
-✔ Build complete in 828ms
+ℹ build/index.mjs        344.18 kB │ gzip: 51.78 kB
+ℹ build/index.mjs.map    589.05 kB │ gzip: 91.22 kB
+ℹ build/index.d.mts.map    3.45 kB │ gzip:  1.22 kB
+ℹ build/index.d.mts       20.10 kB │ gzip:  6.89 kB
+ℹ 4 files, total: 956.79 kB
+✔ Build complete in 822ms

package/README.md

@@ -93,7 +93,7 @@ await app.listen(8080)
 
 The `users.list` and `users.get` actions are now reachable via:
 
-- **REST:** `GET /api/users/list?activeOnly=true` and `GET /api/users/get?id=1`
+- **REST:** `GET /api/users/list?activeOnly=true` (query param) and `GET /api/users/1` (path param, via `path: 'users/:id'`)
 - **tRPC:** `client.usersList.query({ activeOnly: true })` and `client.usersGet.query({ id: '1' })`
 - **MCP:** tools `UsersList` and `UsersGet`
 
@@ -111,6 +111,9 @@ The `users.list` and `users.get` actions are now reachable via:
 | `output` | `z.ZodObject` | - | Optional output schema (used by tRPC type inference) |
 | `chunk` | `z.ZodType` | - | Schema for chunks yielded by a streaming (`async function*`) method. **Required** when the method is an async generator |
 | `kind` | `'query' \| 'mutation'` | `'mutation'` | `'query'` → GET in REST, `.query()` in tRPC. `'mutation'` → POST / `.mutation()` |
+| `method` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE'` | `POST` (or `GET` when `kind: 'query'`) | REST HTTP verb. Overrides the `kind`-derived default |
+| `path` | `string` | action name with dots as slashes | REST route, optionally with `:param` placeholders (e.g. `'spaces/:spaceId/users'`). Each placeholder must be a key of `input` and is resolved from the URL path |
+| `queryParams` | `(keyof input)[]` | - | Input fields read from the URL query string instead of the body (e.g. `['offset', 'limit']`). On a bodyless GET every non-path field is read from the query string automatically |
 | `transports` | `('rest' \| 'trpc' \| 'mcp')[]` | all | Allowlist of transports that expose this action |
 | `isEnabled` | `(ctx) => boolean` | - | Dynamic gate (AND-combined with `transports`) |
 | `toolResult` | `(response, ctx) => CallToolResult` | - | Custom MCP `CallToolResult` formatter |
@@ -140,12 +143,39 @@ Maps actions to REST routes on the Nest HTTP server.
 | `basePath` | `string` | `'/api'` | URL prefix joined to each action's path |
 | `auth` | `AuthConfig` | - | `@silkweave/auth` bearer-token config |
 
-Routes follow `{basePath}/{action-name-with-slashes}` where dots in action names become slashes:
+By default routes follow `{basePath}/{action-name-with-slashes}` where dots in action names become slashes, and the verb comes from `kind`:
 
 - `users.list` (query) → `GET /api/users/list`
 - `users.ban` (mutation) → `POST /api/users/ban`
 
-Each action is registered as an individual route on Nest's HTTP adapter (not a sub-app). Input is parsed from `req.query` (queries) or `req.body` (mutations) and validated against the action's Zod schema; validation failures return HTTP 400 with the Zod issues.
+The action's `method`, `path`, and `queryParams` fields override this (see the `@Action` options table above):
+
+- `path: 'users/:id'`, `kind: 'query'` → `GET /api/users/:id` (`id` from the path)
+- `queryParams: ['activeOnly']`, `kind: 'query'` → `GET /api/users/list?activeOnly=true`
+
+Each action is registered as an individual route on Nest's HTTP adapter (not a sub-app). Input is merged from the request body, `queryParams` query-string fields, and `:param` path placeholders (path/query strings are coerced to the schema's primitive), then validated against the action's Zod schema; validation failures return HTTP 400 with the Zod issues.
+
+#### Swagger / OpenAPI
+
+`@nestjs/swagger` builds its document by scanning **controllers**, but Silkweave registers action routes directly on the HTTP adapter - so the scanner never sees them. `addSilkweaveActions(app, document, options?)` closes the gap: it discovers the actions through the same `ActionDiscovery` provider the `rest()` adapter uses, builds OpenAPI paths with the same routing logic, and merges them into the document. The result stays in sync with the live routes without any dynamic controllers. Call it between `createDocument()` and `setup()`:
+
+```ts
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
+import { addSilkweaveActions } from '@silkweave/nestjs'
+
+const config = new DocumentBuilder().setTitle('My API').setVersion('1.0.0').build()
+const document = SwaggerModule.createDocument(app, config)  // your controllers
+addSilkweaveActions(app, document)                          // + silkweave actions
+SwaggerModule.setup('api/docs', app, document)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `basePath` | `string` | the `rest()` adapter's `basePath`, else `'/api'` | URL prefix the action routes are mounted on |
+| `tag` | `string` | `'Actions'` | OpenAPI tag the actions are grouped under |
+| `includeDisabled` | `boolean` | `false` | Include actions gated off the REST transport (via `transports` / `isEnabled`) |
+
+`@nestjs/swagger` is an **optional** peer dependency - install it alongside `@silkweave/nestjs` to use this helper. Path params, `queryParams`, request bodies, and `output`/`chunk` response schemas are all derived from the action's Zod schemas.
 
 ### `trpc(options?)`
 

package/build/index.d.mts

@@ -1,11 +1,12 @@
-import { CanActivate, DynamicModule, MiddlewareConsumer, NestModule, Type } from "@nestjs/common";
+import { CanActivate, DynamicModule, INestApplication, MiddlewareConsumer, NestModule, Type } from "@nestjs/common";
 import { AuthConfig } from "@silkweave/auth";
-import { Action as Action$1, ActionKind, SilkweaveContext, SilkweaveOptions } from "@silkweave/core";
+import { Action as Action$1, ActionKind, HttpMethod, SilkweaveContext, SilkweaveOptions } from "@silkweave/core";
 import z$1 from "zod/v4";
 import { InferTrpcRouter } from "@silkweave/trpc";
 import { TypegenFormat } from "@silkweave/typegen";
 import { DiscoveryService, HttpAdapterHost, MetadataScanner, ModuleRef, Reflector } from "@nestjs/core";
 import { CorsOptions } from "cors";
+import { OpenAPIObject } from "@nestjs/swagger";
 
 //#region src/lib/types.d.ts
 /**
@@ -35,6 +36,12 @@ interface NestAdapterRegisterContext {
 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
@@ -95,12 +102,17 @@ interface RestAdapterOptions {
  * 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.
  */
 declare function rest(options?: RestAdapterOptions): NestSilkweaveAdapter;
 //#endregion
@@ -179,6 +191,12 @@ interface ActionMetadata<I extends object = object, O extends object = object, C
   chunk?: z$1.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. */
@@ -309,6 +327,22 @@ declare function collectGuards(reflector: Reflector, classRef: Type<unknown>, ha
  */
 declare function runGuards(guards: GuardRef[], moduleRef: ModuleRef, reflector: Reflector, classRef: Type<unknown>, handler: (...args: unknown[]) => unknown, request: unknown, response: unknown, contextType?: 'http' | 'rpc'): Promise<void>;
 //#endregion
+//#region src/lib/openapi.d.ts
+interface ActionPathsOptions {
+  /** URL prefix the `rest()` adapter mounts on. Default `'/api'`. */
+  basePath?: string;
+  /** OpenAPI tag the actions are grouped under. Default `'Actions'`. */
+  tag?: string;
+}
+/**
+ * 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.
+ */
+declare function buildActionPaths(actions: Action$1[], options?: ActionPathsOptions): Record<string, Record<string, unknown>>;
+//#endregion
 //#region src/lib/silkweave.module.d.ts
 /**
  * Root module for `@silkweave/nestjs`.
@@ -347,5 +381,45 @@ declare class SilkweaveModule implements NestModule {
   configure(_consumer: MiddlewareConsumer): void;
 }
 //#endregion
-export { ACTIONS_METADATA, ACTION_METADATA, ACTION_RESPONSE_KEY, Action, ActionDiscovery, ActionMetadata, Actions, type ActionsClassMetadata, AnyActionMetadata, type InferTrpcRouter, McpAdapterOptions, NestAdapterRegisterContext, NestSilkweaveAdapter, RestAdapterOptions, ResultToolResult, SILKWEAVE_MODULE_OPTIONS, SilkweaveModule, SilkweaveModuleOptions, type Transport, TrpcAdapterOptions, TypegenAdapterOptions, buildIsEnabled, collectGuards, mcp, rest, runGuards, trpc, typegen };
+//#region src/lib/swagger.d.ts
+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)
+ * ```
+ */
+declare function addSilkweaveActions(app: INestApplication, document: OpenAPIObject, options?: SilkweaveSwaggerOptions): OpenAPIObject;
+//#endregion
+export { ACTIONS_METADATA, ACTION_METADATA, ACTION_RESPONSE_KEY, Action, ActionDiscovery, ActionMetadata, ActionPathsOptions, Actions, type ActionsClassMetadata, AnyActionMetadata, type InferTrpcRouter, McpAdapterOptions, NestAdapterRegisterContext, NestSilkweaveAdapter, RestAdapterOptions, ResultToolResult, SILKWEAVE_MODULE_OPTIONS, SilkweaveModule, SilkweaveModuleOptions, SilkweaveSwaggerOptions, type Transport, TrpcAdapterOptions, TypegenAdapterOptions, addSilkweaveActions, buildActionPaths, buildIsEnabled, collectGuards, mcp, rest, runGuards, trpc, typegen };
 //# sourceMappingURL=index.d.mts.map

package/build/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/lib/types.ts","../src/adapter/mcp.ts","../src/adapter/rest.ts","../src/adapter/trpc.ts","../src/adapter/typegen.ts","../src/lib/metadata.ts","../src/decorator/action.ts","../src/decorator/actions.ts","../src/lib/discovery.ts","../src/lib/filter.ts","../src/lib/guards.ts","../src/lib/silkweave.module.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/lib/types.ts","../src/adapter/mcp.ts","../src/adapter/rest.ts","../src/adapter/trpc.ts","../src/adapter/typegen.ts","../src/lib/metadata.ts","../src/decorator/action.ts","../src/decorator/actions.ts","../src/lib/discovery.ts","../src/lib/filter.ts","../src/lib/guards.ts","../src/lib/openapi.ts","../src/lib/silkweave.module.ts","../src/lib/swagger.ts"],"mappings":"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"}

package/build/index.mjs

@@ -2,7 +2,7 @@ import { authMiddleware, mcpCors, mcpTransport, oauthRoutes, protectedResourceMe
 import express from "express";
 import { ForbiddenException, HttpException, Inject, Injectable, Module, SetMetadata } from "@nestjs/common";
 import { validateToken } from "@silkweave/auth";
-import { SilkweaveError, createAction, createContext } from "@silkweave/core";
+import { SilkweaveError, actionMethod, createAction, createContext, methodHasBody, pathParamNames, resolveActionInput, validateActionRouting } from "@silkweave/core";
 import { buildLogLevels } from "@silkweave/logger";
 import { z } from "zod/v4";
 import { buildRouter, createActionLogger, resolveAuth } from "@silkweave/trpc";
@@ -11,7 +11,7 @@ import { renderTypegen } from "@silkweave/typegen";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { DiscoveryModule, DiscoveryService, HttpAdapterHost, MetadataScanner, ModuleRef, Reflector } from "@nestjs/core";
-import { kebabCase } from "change-case";
+import { camelCase, kebabCase } from "change-case";
 import { GUARDS_METADATA } from "@nestjs/common/constants.js";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
@@ -167,7 +167,13 @@ function createActionHandler(action, context, auth, logger) {
 				}
 				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) : void 0;
+			const raw = resolveActionInput(action, {
+				params: reqLike.params,
+				query,
+				body
+			});
 			const input = action.input.parse(raw);
 			sendJson(res, await action.run(input, context.fork({
 				logger,
@@ -184,22 +190,29 @@ function createActionHandler(action, context, auth, logger) {
 * 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.
 */
 function rest(options = {}) {
+	const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
 	return {
 		name: "rest",
+		basePath,
 		register({ httpAdapter, baseContext, actions }) {
-			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[method](path, handler);
 			}
@@ -9144,6 +9157,9 @@ let ActionDiscovery = 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,
@@ -9159,6 +9175,9 @@ let ActionDiscovery = 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,
@@ -9176,6 +9195,103 @@ ActionDiscovery = __decorate([Injectable(), __decorateMetadata("design:paramtype
 	typeof (_ref4 = typeof ModuleRef !== "undefined" && ModuleRef) === "function" ? _ref4 : Object
 ])], ActionDiscovery);
 //#endregion
+//#region src/lib/openapi.ts
+/** Convert a route template's `:param` placeholders to OpenAPI `{param}` form. */
+function toOpenApiPath(template) {
+	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, basePath) {
+	return toOpenApiPath(`${basePath}/${action.path ? action.path.replace(/^\//, "") : action.name.replace(/\./g, "/")}`.replace(/\/{2,}/g, "/"));
+}
+/** `z.toJSONSchema` tags a top-level `$schema`; drop it for a tidy OpenAPI doc. */
+function toJsonSchema(schema) {
+	const { $schema: _schema, ...rest } = z.toJSONSchema(schema);
+	return rest;
+}
+function responseSchema(action) {
+	if (action.output) return toJsonSchema(action.output);
+	if (action.chunk) return {
+		type: "array",
+		items: toJsonSchema(action.chunk)
+	};
+}
+/** Split an action's input fields into OpenAPI path/query parameters and a body, matching the `rest()` adapter. */
+function splitInputSources(action, hasBody) {
+	const json = z.toJSONSchema(action.input);
+	const required = new Set(json.required ?? []);
+	const pathParams = new Set(pathParamNames(action.path));
+	const queryKeys = new Set((action.queryParams ?? []).map(String));
+	const split = {
+		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, tag) {
+	const hasBody = methodHasBody(actionMethod(action));
+	const { parameters, bodyProps, bodyRequired } = splitInputSources(action, hasBody);
+	const response = responseSchema(action);
+	const operation = {
+		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.
+*/
+function buildActionPaths(actions, options = {}) {
+	const basePath = (options.basePath ?? "/api").replace(/\/$/, "");
+	const tag = options.tag ?? "Actions";
+	const paths = {};
+	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;
+}
+//#endregion
 //#region src/lib/types.ts
 const SILKWEAVE_MODULE_OPTIONS = "__silkweave_module_options__";
 //#endregion
@@ -9235,6 +9351,55 @@ SilkweaveModule = _SilkweaveModule = __decorate([
 	])
 ], SilkweaveModule);
 //#endregion
-export { ACTIONS_METADATA, ACTION_METADATA, ACTION_RESPONSE_KEY, Action, ActionDiscovery, Actions, SILKWEAVE_MODULE_OPTIONS, SilkweaveModule, buildIsEnabled, collectGuards, mcp, rest, runGuards, trpc, typegen };
+//#region src/lib/swagger.ts
+/**
+* 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)
+* ```
+*/
+function addSilkweaveActions(app, document, options = {}) {
+	const discovery = app.get(ActionDiscovery);
+	const moduleOptions = app.get(SILKWEAVE_MODULE_OPTIONS);
+	const restAdapter = moduleOptions.adapters.find((adapter) => adapter.name === "rest");
+	const basePath = options.basePath ?? restAdapter?.basePath ?? "/api";
+	const allActions = discovery.discover();
+	const paths = buildActionPaths(options.includeDisabled ? allActions : allActions.filter((action) => isRestEnabled(action, moduleOptions)), {
+		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, moduleOptions) {
+	if (!action.isEnabled) return true;
+	return action.isEnabled(createContext({
+		...moduleOptions.context ?? {},
+		adapter: "rest"
+	}));
+}
+//#endregion
+export { ACTIONS_METADATA, ACTION_METADATA, ACTION_RESPONSE_KEY, Action, ActionDiscovery, Actions, SILKWEAVE_MODULE_OPTIONS, SilkweaveModule, addSilkweaveActions, buildActionPaths, buildIsEnabled, collectGuards, mcp, rest, runGuards, trpc, typegen };
 
 //# sourceMappingURL=index.mjs.map