webspresso 0.0.58 → 0.0.61

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
 
@@ -1237,6 +1240,7 @@ The `zdb` helpers wrap Zod schemas with database column metadata:
 |--------|-------------|---------|
 | `zdb.id()` | Primary key (bigint, auto-increment) | |
 | `zdb.uuid()` | UUID primary key | |
+| `zdb.nanoid(opts)` | Nanoid primary key (URL-safe string, stored as VARCHAR) | `maxLength` (default `21`) |
 | `zdb.string(opts)` | VARCHAR column | `maxLength`, `unique`, `index`, `nullable` |
 | `zdb.text(opts)` | TEXT column | `nullable` |
 | `zdb.integer(opts)` | INTEGER column | `nullable`, `default` |
@@ -1252,6 +1256,9 @@ The `zdb` helpers wrap Zod schemas with database column metadata:
 | `zdb.enum(values, opts)` | ENUM column | `default`, `nullable` |
 | `zdb.foreignKey(table, opts)` | Foreign key (bigint) | `referenceColumn`, `nullable` |
 | `zdb.foreignUuid(table, opts)` | Foreign key (uuid) | `referenceColumn`, `nullable` |
+| `zdb.foreignNanoid(table, opts)` | Foreign key (nanoid string) | `referenceColumn`, `nullable`, `maxLength` (must match referenced PK) |
+
+**Nanoid columns:** Migration scaffolding emits `table.string(column, maxLength)`. For a **nanoid primary key**, if you omit the primary key on `repository.create()`, Webspresso fills it with a cryptographically random ID using the same default alphabet as the [`nanoid`](https://github.com/ai/nanoid) package (implemented in-framework; no extra dependency). You can also call **`generateNanoid`** (exported from `webspresso`) anywhere you need the same generator.
 
 ### Model Definition
 
@@ -1776,6 +1783,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,146 @@
+/**
+ * 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 'nanoid':
+      result.type = 'string';
+      if (meta.maxLength) {
+        result.maxLength = meta.maxLength;
+      }
+      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/core/orm/index.js

@@ -14,6 +14,7 @@ const { createSeeder } = require('./seeder');
 const { createScopeContext } = require('./scopes');
 const { ModelEvents, Hooks, HookCancellationError, createEventContext } = require('./events');
 const { omitHiddenColumns, sanitizeForOutput } = require('./utils');
+const { generateNanoid } = require('./utils/nanoid');
 
 /**
  * Create a database instance
@@ -273,6 +274,7 @@ module.exports = {
   // Column utilities
   extractColumnsFromSchema,
   getColumnMeta,
+  generateNanoid,
   // Output sanitization (exclude hidden columns from API/templates)
   omitHiddenColumns,
   sanitizeForOutput,

package/core/orm/migrations/scaffold.js

@@ -164,6 +164,19 @@ function generateColumnLine(columnName, meta) {
       }
       break;
 
+    case 'nanoid': {
+      const nanoLen = meta.maxLength || 21;
+      if (meta.primary) {
+        parts.push(`table.string('${columnName}', ${nanoLen})`);
+      } else if (meta.references) {
+        parts.push(`table.string('${columnName}', ${nanoLen})`);
+        fkLine = `table.foreign('${columnName}').references('${meta.referenceColumn || 'id'}').inTable('${meta.references}');`;
+      } else {
+        parts.push(`table.string('${columnName}', ${nanoLen})`);
+      }
+      break;
+    }
+
     default:
       parts.push(`table.string('${columnName}')`);
   }

package/core/orm/schema-helpers.js

@@ -359,6 +359,30 @@ function createSchemaHelpers(z) {
       }, z);
     },
 
+    /**
+     * Nanoid primary key column (URL-safe string, default length 21)
+     * @param {Partial<import('./types').ColumnMeta>} [options={}]
+     * @returns {SchemaBuilder}
+     */
+    nanoid(options = {}) {
+      const { maxLength = 21, ...rest } = options;
+      const schema = z
+        .string()
+        .length(maxLength)
+        .regex(/^[A-Za-z0-9_-]+$/)
+        .optional();
+      return createSchemaBuilder(
+        schema,
+        {
+          type: 'nanoid',
+          primary: true,
+          maxLength,
+          ...rest,
+        },
+        z
+      );
+    },
+
     /**
      * String column (varchar)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
@@ -667,6 +691,36 @@ function createSchemaHelpers(z) {
         ...rest,
       }, z);
     },
+
+    /**
+     * Nanoid foreign key column
+     * @param {string} references - Referenced table name
+     * @param {Partial<import('./types').ColumnMeta>} [options={}]
+     * @returns {SchemaBuilder}
+     */
+    foreignNanoid(references, options = {}) {
+      const {
+        referenceColumn = 'id',
+        nullable = false,
+        maxLength = 21,
+        ...rest
+      } = options;
+      let schema = z
+        .string()
+        .length(maxLength)
+        .regex(/^[A-Za-z0-9_-]+$/);
+      if (nullable) {
+        schema = schema.nullable().optional();
+      }
+      return createSchemaBuilder(schema, {
+        type: 'nanoid',
+        references,
+        referenceColumn,
+        nullable,
+        maxLength,
+        ...rest,
+      }, z);
+    },
   };
 
   return helpers;

package/core/orm/scopes.js

@@ -4,6 +4,8 @@
  * @module core/orm/scopes
  */
 
+const { generateNanoid } = require('./utils/nanoid');
+
 /**
  * Apply soft delete scope to a query builder
  * @param {import('knex').Knex.QueryBuilder} qb - Knex query builder
@@ -115,6 +117,29 @@ function applyInsertTenant(data, context, model) {
   };
 }
 
+/**
+ * Generate nanoid primary key when missing on insert
+ * @param {Object} data - Data to insert
+ * @param {import('./types').ModelDefinition} model - Model definition
+ * @returns {Object}
+ */
+function applyInsertNanoidPrimary(data, model) {
+  const pk = model.primaryKey;
+  const meta = model.columns && model.columns.get(pk);
+  if (!meta || meta.type !== 'nanoid') {
+    return data;
+  }
+  const val = data[pk];
+  if (val !== undefined && val !== null && val !== '') {
+    return data;
+  }
+  const len = meta.maxLength || 21;
+  return {
+    ...data,
+    [pk]: generateNanoid(len),
+  };
+}
+
 /**
  * Get soft delete data (for UPDATE instead of DELETE)
  * @returns {Object} Soft delete update data
@@ -142,6 +167,7 @@ function applyInsertModifiers(data, context, model) {
   let modified = { ...data };
   modified = applyInsertTimestamps(modified, model);
   modified = applyInsertTenant(modified, context, model);
+  modified = applyInsertNanoidPrimary(modified, model);
   return modified;
 }
 
@@ -174,6 +200,7 @@ module.exports = {
   applyInsertTimestamps,
   applyUpdateTimestamps,
   applyInsertTenant,
+  applyInsertNanoidPrimary,
   applyInsertModifiers,
   applyUpdateModifiers,
   getSoftDeleteData,

package/core/orm/seeder.js

@@ -5,6 +5,7 @@
  */
 
 const { getModel, getAllModels } = require('./model');
+const { generateNanoid } = require('./utils/nanoid');
 
 /**
  * @typedef {Object} SeederOptions
@@ -189,6 +190,9 @@ function createSeeder(faker, knex) {
       case 'uuid':
         return faker.string.uuid();
 
+      case 'nanoid':
+        return generateNanoid(meta.maxLength || 21);
+
       case 'json':
         return { key: faker.lorem.word(), value: faker.lorem.sentence() };
 

package/core/orm/types.js

@@ -9,7 +9,7 @@
 // ============================================================================
 
 /**
- * @typedef {'id'|'string'|'text'|'integer'|'bigint'|'float'|'decimal'|'boolean'|'date'|'datetime'|'timestamp'|'json'|'array'|'enum'|'uuid'} ColumnType
+ * @typedef {'id'|'string'|'text'|'integer'|'bigint'|'float'|'decimal'|'boolean'|'date'|'datetime'|'timestamp'|'json'|'array'|'enum'|'uuid'|'nanoid'} ColumnType
  */
 
 /**

package/core/orm/utils/nanoid.js

@@ -0,0 +1,30 @@
+/**
+ * URL-safe ID generation compatible with the default nanoid alphabet/algorithm.
+ * @module core/orm/utils/nanoid
+ */
+
+const crypto = require('crypto');
+
+/** Same 64-char alphabet as npm `nanoid` default (URL-safe). */
+const URL_ALPHABET =
+  'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+
+/**
+ * @param {number} [size=21] - Id length (default matches nanoid)
+ * @returns {string}
+ */
+function generateNanoid(size = 21) {
+  const n = Math.max(1, Math.floor(size));
+  const bytes = new Uint8Array(n);
+  crypto.randomFillSync(bytes);
+  let id = '';
+  for (let i = 0; i < n; i++) {
+    id += URL_ALPHABET[bytes[i] & 63];
+  }
+  return id;
+}
+
+module.exports = {
+  generateNanoid,
+  URL_ALPHABET,
+};

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.61",
   "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/admin-panel/components.js

@@ -1083,6 +1083,7 @@ function getFieldRenderer(col, modelMeta) {
     json: 'json',
     array: 'array',
     uuid: 'string',
+    nanoid: 'string',
   };
   return FieldRenderers[typeMap[col.type] || 'string'];
 }

package/plugins/admin-panel/field-renderers/index.js

@@ -68,6 +68,7 @@ function initializeDefaultRenderers() {
   registerFieldRenderer('timestamp', basicRenderers.DateTimeField);
   registerFieldRenderer('enum', basicRenderers.SelectField);
   registerFieldRenderer('uuid', basicRenderers.TextField);
+  registerFieldRenderer('nanoid', basicRenderers.TextField);
   registerFieldRenderer('id', basicRenderers.NumberField);
   
   // Complex types

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;

package/templates/skills/webspresso-usage/SKILL.md

@@ -143,13 +143,14 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 ## 9. ORM overview
 
-**Define schema** with **`zdb`** (`zdb.id()`, `zdb.string({...})`, `zdb.foreignKey`, `zdb.timestamp`, `zdb.json`, …).
+**Define schema** with **`zdb`** (`zdb.id()`, `zdb.uuid()`, `zdb.nanoid()`, `zdb.string({...})`, `zdb.foreignKey`, `zdb.foreignUuid`, `zdb.foreignNanoid`, `zdb.timestamp`, `zdb.json`, …).
 
 **Define model** with **`defineModel({ name, table, schema, relations, scopes, hidden, admin })`**.
 
 - **Relations:** `belongsTo`, `hasMany`, `hasOne` with `model: () => OtherModel`.
 - **Scopes:** `softDelete`, `timestamps`, optional `tenant` column.
 - **`hidden`:** columns never exposed in admin/API (e.g. `password_hash`).
+- **Nanoid PK:** `zdb.nanoid()` / `zdb.nanoid({ maxLength: 12 })` — string primary key; migrations use `string(length)`. On **`create()`**, omitting the PK auto-fills a URL-safe id (built-in generator, same alphabet as `nanoid`). Use **`zdb.foreignNanoid('table', { maxLength })`** when the parent uses nanoid PKs; **`generateNanoid`** is exported from `webspresso` for manual ids.
 
 **Database:** `createDatabase({ client, connection, models: './models' })` — auto-loads `models/*.js` (ignore `_prefix`).