webspresso 0.0.58 → 0.0.60

package/README.md

@@ -1,5 +1,8 @@
 # Webspresso
 
+[![npm version](https://img.shields.io/npm/v/webspresso.svg?style=flat-square)](https://www.npmjs.com/package/webspresso)
+[![vulnerabilities](https://npmx.dev/api/registry/badge/vulnerabilities/webspresso?style=shieldsio)](https://npmx.dev/package/webspresso)
+
 A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 
 ## Features
@@ -12,7 +15,7 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **Lifecycle Hooks**: Global and route-level hooks for request processing
 - **Template Helpers**: Laravel-inspired helper functions available in templates
 - **Plugin System**: Extensible architecture with version control and inter-plugin communication
-- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics
+- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint
 
 ## Installation
 
@@ -1776,6 +1779,64 @@ const user = plugin.api.getModel('User');    // Single model
 const names = plugin.api.getModelNames();    // Model names
 ```
 
+### Health check plugin
+
+Exposes a lightweight **GET** endpoint for load balancers and orchestrators (Kubernetes, Docker healthcheck, etc.). **Enabled by default** in all environments; set `enabled: false` to turn it off.
+
+**Setup:**
+
+```javascript
+const { createApp, healthCheckPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    healthCheckPlugin({
+      path: '/health',              // default
+      verbose: true,                // timestamp, uptime, NODE_ENV, framework name/version
+      authorize: (req) => true,     // optional — restrict who can read the endpoint
+      checks: async ({ db }) => {
+        if (db) await db.knex.raw('select 1');
+        return { database: 'ok' };
+      },
+    }),
+  ],
+});
+```
+
+- **`checks`**: If this function throws, the handler responds with **503** and `{ status: 'unhealthy', error, ... }`. Return a plain object to merge into `checks` on success (e.g. dependency status).
+- Use a **custom `path`** if your app already serves `GET /health` from `pages/`.
+
+### Swagger / OpenAPI plugin
+
+Serves **OpenAPI 3** for file-based `pages/api` routes and optional [Zod](https://zod.dev) `schema` exports, plus a **Swagger UI** page. Defaults to **development only** (same idea as the schema explorer).
+
+**Setup:**
+
+```javascript
+const { createApp, swaggerPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    swaggerPlugin({
+      path: '/_swagger',           // UI: GET /_swagger, spec: GET /_swagger/openapi.json
+      enabled: true,               // default: true in development, false in production
+      title: 'My API',             // optional OpenAPI info.title
+      serverUrl: 'https://api.example.com', // optional servers[0].url (else BASE_URL or localhost)
+      includeOrmSchemas: false,    // merge ORM model schemas into components.schemas
+      ormExclude: ['Secret'],      // when includeOrmSchemas is true
+      authorize: (req) => true,  // optional gate for both UI and JSON
+    }),
+  ],
+});
+```
+
+**Endpoints:**
+
+- `GET /_swagger/openapi.json` — Full OpenAPI document (`paths` from API routes; request/response shapes from exported `schema({ z })` when present).
+- `GET /_swagger` — Swagger UI (loads the JSON above; requires network access for CDN assets).
+
+In production, keep the plugin disabled or protect it with `authorize` / your own middleware.
+
 ## Development
 
 ```bash

package/core/openapi/build-from-api-routes.js

@@ -0,0 +1,172 @@
+/**
+ * Build OpenAPI 3 document from file-router API route metadata + Zod schemas
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { zodToJsonSchema } = require('zod-to-json-schema');
+const { compileSchema } = require('../compileSchema');
+const { generateOrmOpenApiSchemas } = require('./orm-components');
+
+/**
+ * Express route pattern → OpenAPI path (e.g. /users/:id → /users/{id})
+ * @param {string} expressPath
+ * @returns {string}
+ */
+function expressPathToOpenApi(expressPath) {
+  return String(expressPath)
+    .replace(/:([A-Za-z0-9_]+)/g, '{$1}')
+    .replace(/\*/g, '{wildcard}');
+}
+
+/**
+ * @param {import('zod').ZodObject<any>} zodObj
+ * @param {'path' | 'query'} where
+ * @returns {object[]}
+ */
+function expandZodObjectToParameters(zodObj, where) {
+  if (!zodObj || zodObj._def?.typeName !== 'ZodObject') return [];
+  const shape = zodObj.shape;
+  return Object.entries(shape).map(([name, zType]) => ({
+    name,
+    in: where,
+    required: where === 'path' ? true : !zType.isOptional(),
+    schema: zodToJsonSchema(zType, { target: 'openApi3', $refStrategy: 'none' }),
+  }));
+}
+
+/**
+ * @param {object} route - { type, method, pattern, file }
+ * @param {object|null} compiled - compileSchema result
+ * @returns {object} OpenAPI Operation Object
+ */
+function buildOperation(route, compiled) {
+  const filePath = route.file;
+  const method = route.method.toLowerCase();
+  const summary = `${method.toUpperCase()} ${filePath}`;
+
+  const op = {
+    tags: ['api'],
+    summary,
+    operationId: String(filePath)
+      .replace(/[^a-zA-Z0-9]+/g, '_')
+      .replace(/^_|_$/g, ''),
+    responses: {
+      200: {
+        description: 'OK',
+      },
+    },
+  };
+
+  if (compiled?.response) {
+    op.responses['200'] = {
+      description: 'OK',
+      content: {
+        'application/json': {
+          schema: zodToJsonSchema(compiled.response, { target: 'openApi3', $refStrategy: 'none' }),
+        },
+      },
+    };
+  }
+
+  const parameters = [
+    ...expandZodObjectToParameters(compiled?.params, 'path'),
+    ...expandZodObjectToParameters(compiled?.query, 'query'),
+  ];
+
+  if (parameters.length) {
+    op.parameters = parameters;
+  }
+
+  if (compiled?.body) {
+    op.requestBody = {
+      content: {
+        'application/json': {
+          schema: zodToJsonSchema(compiled.body, { target: 'openApi3', $refStrategy: 'none' }),
+        },
+      },
+    };
+  }
+
+  return op;
+}
+
+/**
+ * @param {object} opts
+ * @param {object[]} opts.routes - route metadata from mountPages
+ * @param {string} opts.pagesDir
+ * @param {boolean} [opts.includeOrmSchemas]
+ * @param {string[]} [opts.ormExclude]
+ * @param {object} [opts.info]
+ * @param {object[]} [opts.servers]
+ * @returns {object} OpenAPI 3.0.x document
+ */
+function buildOpenApiDocument(opts) {
+  const {
+    routes = [],
+    pagesDir,
+    includeOrmSchemas = false,
+    ormExclude = [],
+    info = {},
+    servers = [{ url: '/' }],
+  } = opts;
+
+  if (!pagesDir) {
+    throw new Error('buildOpenApiDocument: pagesDir is required');
+  }
+
+  const paths = {};
+  const apiRoutes = routes.filter((r) => r.type === 'api');
+  const absPages = path.resolve(pagesDir);
+
+  for (const route of apiRoutes) {
+    const fullPath = path.join(absPages, route.file);
+    if (!fs.existsSync(fullPath)) {
+      continue;
+    }
+
+    let mod;
+    try {
+      mod = require(fullPath);
+    } catch {
+      continue;
+    }
+
+    let compiled = null;
+    try {
+      compiled = compileSchema(fullPath, mod);
+    } catch {
+      compiled = null;
+    }
+
+    const openApiPath = expressPathToOpenApi(route.pattern);
+    const method = route.method.toLowerCase();
+
+    if (!paths[openApiPath]) {
+      paths[openApiPath] = {};
+    }
+
+    paths[openApiPath][method] = buildOperation(route, compiled);
+  }
+
+  const doc = {
+    openapi: '3.0.3',
+    info: {
+      title: info.title || 'API',
+      version: info.version || '1.0.0',
+      ...(info.description ? { description: info.description } : {}),
+    },
+    servers,
+    paths,
+    components: {
+      schemas: includeOrmSchemas ? generateOrmOpenApiSchemas({ exclude: ormExclude }) : {},
+    },
+  };
+
+  return doc;
+}
+
+module.exports = {
+  expressPathToOpenApi,
+  buildOpenApiDocument,
+};

package/core/openapi/orm-components.js

@@ -0,0 +1,139 @@
+/**
+ * ORM column → OpenAPI schema fragments (shared by schema-explorer and swagger plugin)
+ */
+
+const { getAllModels } = require('../orm/model');
+
+/**
+ * Generate OpenAPI 3 components.schemas from registered ORM models
+ * @param {{ exclude?: string[] }} options
+ * @returns {Record<string, object>}
+ */
+function generateOrmOpenApiSchemas(options = {}) {
+  const { exclude = [] } = options;
+  const models = getAllModels();
+  const schemas = {};
+
+  for (const [name, model] of models) {
+    if (exclude.includes(name)) continue;
+
+    const properties = {};
+    const required = [];
+
+    if (model.columns) {
+      for (const [colName, meta] of model.columns) {
+        properties[colName] = columnToOpenApiType(meta);
+
+        if (!meta.nullable && !meta.autoIncrement && meta.default === undefined) {
+          required.push(colName);
+        }
+      }
+    }
+
+    schemas[name] = {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    };
+
+    const inputProperties = {};
+    const inputRequired = [];
+
+    if (model.columns) {
+      for (const [colName, meta] of model.columns) {
+        if (meta.autoIncrement || meta.auto) continue;
+
+        inputProperties[colName] = columnToOpenApiType(meta);
+
+        if (!meta.nullable && meta.default === undefined) {
+          inputRequired.push(colName);
+        }
+      }
+    }
+
+    schemas[`${name}Input`] = {
+      type: 'object',
+      properties: inputProperties,
+      required: inputRequired.length > 0 ? inputRequired : undefined,
+    };
+  }
+
+  return schemas;
+}
+
+/**
+ * @param {Object} meta - Column metadata
+ * @returns {Object}
+ */
+function columnToOpenApiType(meta) {
+  const result = {};
+
+  switch (meta.type) {
+    case 'bigint':
+    case 'integer':
+      result.type = 'integer';
+      if (meta.type === 'bigint') result.format = 'int64';
+      break;
+
+    case 'float':
+    case 'decimal':
+      result.type = 'number';
+      if (meta.type === 'decimal') result.format = 'double';
+      break;
+
+    case 'boolean':
+      result.type = 'boolean';
+      break;
+
+    case 'date':
+      result.type = 'string';
+      result.format = 'date';
+      break;
+
+    case 'datetime':
+    case 'timestamp':
+      result.type = 'string';
+      result.format = 'date-time';
+      break;
+
+    case 'uuid':
+      result.type = 'string';
+      result.format = 'uuid';
+      break;
+
+    case 'json':
+      result.type = 'object';
+      break;
+
+    case 'enum':
+      result.type = 'string';
+      if (meta.enumValues) {
+        result.enum = meta.enumValues;
+      }
+      break;
+
+    case 'text':
+    case 'string':
+    default:
+      result.type = 'string';
+      if (meta.maxLength) {
+        result.maxLength = meta.maxLength;
+      }
+      break;
+  }
+
+  if (meta.nullable) {
+    result.nullable = true;
+  }
+
+  if (meta.default !== undefined) {
+    result.default = meta.default;
+  }
+
+  return result;
+}
+
+module.exports = {
+  generateOrmOpenApiSchemas,
+  columnToOpenApiType,
+};

package/index.js

@@ -30,7 +30,7 @@ const {
 const orm = require('./core/orm');
 
 // Built-in plugins
-const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlugin, recaptchaPlugin } = require('./plugins');
+const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlugin, recaptchaPlugin, swaggerPlugin, healthCheckPlugin } = require('./plugins');
 
 module.exports = {
   // Main API
@@ -72,4 +72,6 @@ module.exports = {
   siteAnalyticsPlugin,
   auditLogPlugin,
   recaptchaPlugin,
+  swaggerPlugin,
+  healthCheckPlugin,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/everytools/webspresso.git"
+    "url": "https://github.com/litepacks/webspresso.git"
   },
   "files": [
     "index.js",
@@ -54,7 +54,8 @@
     "knex": "^3.1.0",
     "nunjucks": "^3.2.4",
     "sharp": "^0.33.5",
-    "zod": "^3.23.0"
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
     "@faker-js/faker": ">=8.0.0",
@@ -83,15 +84,19 @@
   "devDependencies": {
     "@faker-js/faker": "^9.9.0",
     "@playwright/test": "^1.48.0",
-    "@vitest/coverage-v8": "^1.2.0",
+    "@vitest/coverage-v8": "^3.0.0",
     "better-sqlite3": "^11.10.0",
     "chokidar": "^3.5.3",
     "dotenv": "^16.3.1",
-    "release-it": "^17.11.0",
+    "release-it": "^19.0.0",
     "supertest": "^6.3.4",
-    "vitest": "^1.2.0"
+    "vitest": "^3.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "overrides": {
+    "tar": "^7.5.11",
+    "undici": "^6.24.0"
   }
 }

package/plugins/health-check.js

@@ -0,0 +1,84 @@
+/**
+ * Health check plugin — liveness/readiness style HTTP endpoint for load balancers and monitoring
+ */
+
+const pathMod = require('path');
+const PKG = require(pathMod.join(__dirname, '..', 'package.json'));
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.path='/health'] — GET endpoint path
+ * @param {boolean} [options.enabled=true] — Disable entirely when false
+ * @param {function} [options.authorize] — (req) => boolean; optional gate (e.g. internal network only)
+ * @param {boolean} [options.verbose=true] — Include timestamp, uptime, env, framework version
+ * @param {function} [options.checks] — async ({ req, db, options }) => Record<string, string> — custom checks; thrown error → 503
+ */
+function healthCheckPlugin(options = {}) {
+  const {
+    path: routePath = '/health',
+    enabled,
+    authorize,
+    verbose = true,
+    checks,
+  } = options;
+
+  const isEnabled = enabled !== undefined ? enabled : true;
+  const normalizedPath = routePath.startsWith('/') ? routePath : `/${routePath}`;
+
+  return {
+    name: 'health-check',
+    version: '1.0.0',
+    description: 'HTTP health endpoint for probes and monitoring',
+
+    onRoutesReady(ctx) {
+      if (!isEnabled) {
+        return;
+      }
+
+      ctx.addRoute('get', normalizedPath, async (req, res) => {
+        if (authorize && !authorize(req)) {
+          return res.status(403).json({ error: 'Forbidden' });
+        }
+
+        const body = {
+          status: 'ok',
+        };
+
+        if (verbose) {
+          body.timestamp = new Date().toISOString();
+          body.uptime = process.uptime();
+          body.env = process.env.NODE_ENV || 'development';
+          body.framework = {
+            name: PKG.name,
+            version: PKG.version,
+          };
+        }
+
+        if (typeof checks === 'function') {
+          try {
+            const result = await checks({
+              req,
+              db: ctx.db,
+              options: ctx.options,
+            });
+            if (result && typeof result === 'object') {
+              body.checks = result;
+            }
+          } catch (err) {
+            body.status = 'unhealthy';
+            body.error = err.message || String(err);
+            return res.status(503).json(body);
+          }
+        }
+
+        res.json(body);
+      });
+
+      if (process.env.NODE_ENV !== 'production') {
+        console.log(`  Health check: GET ${normalizedPath}`);
+      }
+    },
+  };
+}
+
+module.exports = healthCheckPlugin;

package/plugins/index.js

@@ -12,6 +12,8 @@ const seoCheckerPlugin = require('./seo-checker');
 const siteAnalyticsPlugin = require('./site-analytics');
 const auditLogPlugin = require('./audit-log');
 const recaptchaPlugin = require('./recaptcha');
+const swaggerPlugin = require('./swagger');
+const healthCheckPlugin = require('./health-check');
 
 module.exports = {
   sitemapPlugin,
@@ -23,5 +25,7 @@ module.exports = {
   siteAnalyticsPlugin,
   auditLogPlugin,
   recaptchaPlugin,
+  swaggerPlugin,
+  healthCheckPlugin,
 };
 

package/plugins/schema-explorer.js

@@ -6,6 +6,7 @@
 
 const { getAllModels, getModel } = require('../core/orm/model');
 const { getColumnMeta } = require('../core/orm/schema-helpers');
+const { generateOrmOpenApiSchemas } = require('../core/openapi/orm-components');
 
 /**
  * Create Schema Explorer plugin
@@ -99,7 +100,7 @@ function schemaExplorerPlugin(options = {}) {
           return res.status(403).json({ error: 'Forbidden' });
         }
 
-        const openApiSchemas = generateOpenApiSchemas({ exclude });
+        const openApiSchemas = generateOrmOpenApiSchemas({ exclude });
 
         res.json({
           openapi: '3.0.0',
@@ -262,137 +263,5 @@ function serializeRelations(relations) {
   return result;
 }
 
-/**
- * Generate OpenAPI schemas from models
- * @param {Object} options
- * @returns {Object}
- */
-function generateOpenApiSchemas(options) {
-  const { exclude } = options;
-  const models = getAllModels();
-  const schemas = {};
-
-  for (const [name, model] of models) {
-    if (exclude.includes(name)) continue;
-
-    const properties = {};
-    const required = [];
-
-    if (model.columns) {
-      for (const [colName, meta] of model.columns) {
-        properties[colName] = columnToOpenApiType(meta);
-        
-        if (!meta.nullable && !meta.autoIncrement && meta.default === undefined) {
-          required.push(colName);
-        }
-      }
-    }
-
-    schemas[name] = {
-      type: 'object',
-      properties,
-      required: required.length > 0 ? required : undefined,
-    };
-
-    // Add input schema (without auto fields)
-    const inputProperties = {};
-    const inputRequired = [];
-
-    if (model.columns) {
-      for (const [colName, meta] of model.columns) {
-        // Skip auto-generated fields for input
-        if (meta.autoIncrement || meta.auto) continue;
-
-        inputProperties[colName] = columnToOpenApiType(meta);
-        
-        if (!meta.nullable && meta.default === undefined) {
-          inputRequired.push(colName);
-        }
-      }
-    }
-
-    schemas[`${name}Input`] = {
-      type: 'object',
-      properties: inputProperties,
-      required: inputRequired.length > 0 ? inputRequired : undefined,
-    };
-  }
-
-  return schemas;
-}
-
-/**
- * Convert column metadata to OpenAPI type
- * @param {Object} meta - Column metadata
- * @returns {Object}
- */
-function columnToOpenApiType(meta) {
-  const result = {};
-
-  switch (meta.type) {
-    case 'bigint':
-    case 'integer':
-      result.type = 'integer';
-      if (meta.type === 'bigint') result.format = 'int64';
-      break;
-
-    case 'float':
-    case 'decimal':
-      result.type = 'number';
-      if (meta.type === 'decimal') result.format = 'double';
-      break;
-
-    case 'boolean':
-      result.type = 'boolean';
-      break;
-
-    case 'date':
-      result.type = 'string';
-      result.format = 'date';
-      break;
-
-    case 'datetime':
-    case 'timestamp':
-      result.type = 'string';
-      result.format = 'date-time';
-      break;
-
-    case 'uuid':
-      result.type = 'string';
-      result.format = 'uuid';
-      break;
-
-    case 'json':
-      result.type = 'object';
-      break;
-
-    case 'enum':
-      result.type = 'string';
-      if (meta.enumValues) {
-        result.enum = meta.enumValues;
-      }
-      break;
-
-    case 'text':
-    case 'string':
-    default:
-      result.type = 'string';
-      if (meta.maxLength) {
-        result.maxLength = meta.maxLength;
-      }
-      break;
-  }
-
-  if (meta.nullable) {
-    result.nullable = true;
-  }
-
-  if (meta.default !== undefined) {
-    result.default = meta.default;
-  }
-
-  return result;
-}
-
 module.exports = schemaExplorerPlugin;
 

package/plugins/swagger.js

@@ -0,0 +1,126 @@
+/**
+ * Swagger / OpenAPI plugin — HTTP API docs from file-based routes + Zod, optional ORM schemas
+ */
+
+const path = require('path');
+const { buildOpenApiDocument } = require('../core/openapi/build-from-api-routes');
+
+const PKG = require(path.join(__dirname, '..', 'package.json'));
+
+/**
+ * @param {string} specUrl - Absolute path on same origin (e.g. /_swagger/openapi.json)
+ */
+function buildSwaggerUiHtml(specUrl) {
+  const urlJson = JSON.stringify(specUrl);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>API documentation</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" crossorigin />
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
+  <script>
+    window.onload = function () {
+      SwaggerUIBundle({
+        url: ${urlJson},
+        dom_id: '#swagger-ui',
+        deepLinking: true
+      });
+    };
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.path='/_swagger'] - Base path; JSON at `{path}/openapi.json`, UI at `{path}`
+ * @param {boolean} [options.enabled] - Default: development only
+ * @param {Function} [options.authorize] - (req) => boolean
+ * @param {boolean} [options.includeOrmSchemas] - Merge ORM components.schemas
+ * @param {string[]} [options.ormExclude] - Model names to exclude when includeOrmSchemas
+ * @param {string} [options.title] - OpenAPI info.title
+ * @param {string} [options.version] - OpenAPI info.version
+ * @param {string} [options.description] - OpenAPI info.description
+ * @param {string} [options.serverUrl] - Override servers[0].url (default: BASE_URL or http://localhost:3000)
+ */
+function swaggerPlugin(options = {}) {
+  const {
+    path: basePath = '/_swagger',
+    enabled,
+    authorize,
+    includeOrmSchemas = false,
+    ormExclude = [],
+    title,
+    version,
+    description,
+    serverUrl,
+  } = options;
+
+  const normalizedBase = `/${String(basePath).replace(/^\/+|\/+$/g, '')}`;
+  const jsonPath = `${normalizedBase}/openapi.json`;
+  const uiPath = normalizedBase;
+
+  return {
+    name: 'swagger',
+    version: '1.0.0',
+
+    onRoutesReady(ctx) {
+      const isDev = process.env.NODE_ENV !== 'production';
+      const isEnabled = enabled !== undefined ? enabled : isDev;
+
+      if (!isEnabled) {
+        return;
+      }
+
+      const forbid = (req, res) => {
+        if (authorize && !authorize(req)) {
+          res.status(403).json({ error: 'Forbidden' });
+          return true;
+        }
+        return false;
+      };
+
+      const server = serverUrl || process.env.BASE_URL || 'http://localhost:3000';
+
+      ctx.addRoute('get', jsonPath, (req, res) => {
+        if (forbid(req, res)) return;
+        try {
+          const doc = buildOpenApiDocument({
+            routes: ctx.routes || [],
+            pagesDir: ctx.options.pagesDir,
+            includeOrmSchemas,
+            ormExclude,
+            info: {
+              title: title || PKG.name || 'API',
+              version: version || PKG.version || '1.0.0',
+              description:
+                description ||
+                'Generated from pages/api routes and optional Zod schema exports.',
+            },
+            servers: [{ url: server.replace(/\/$/, '') }],
+          });
+          res.json(doc);
+        } catch (err) {
+          console.warn('[swagger] OpenAPI generation failed:', err.message);
+          res.status(500).json({ error: 'OpenAPI generation failed', message: err.message });
+        }
+      });
+
+      ctx.addRoute('get', uiPath, (req, res) => {
+        if (forbid(req, res)) return;
+        res.type('html').send(buildSwaggerUiHtml(jsonPath));
+      });
+
+      if (isDev) {
+        console.log(`  Swagger UI: ${uiPath} (OpenAPI: ${jsonPath})`);
+      }
+    },
+  };
+}
+
+module.exports = swaggerPlugin;