webspresso 0.0.8 → 0.0.10

package/plugins/schema-explorer.js

@@ -0,0 +1,398 @@
+/**
+ * Schema Explorer Plugin
+ * Exposes ORM model metadata via API endpoint
+ * Useful for documentation, admin tools, and frontend code generation
+ */
+
+const { getAllModels, getModel } = require('../core/orm/model');
+const { getColumnMeta } = require('../core/orm/schema-helpers');
+
+/**
+ * Create Schema Explorer plugin
+ * @param {Object} options - Plugin options
+ * @param {string} [options.path='/_schema'] - API endpoint path
+ * @param {boolean} [options.enabled] - Force enable/disable (default: auto based on NODE_ENV)
+ * @param {string[]} [options.exclude=[]] - Model names to exclude
+ * @param {boolean} [options.includeColumns=true] - Include column metadata
+ * @param {boolean} [options.includeRelations=true] - Include relation metadata
+ * @param {boolean} [options.includeScopes=true] - Include scope configuration
+ * @param {Function} [options.authorize] - Custom authorization function (req) => boolean
+ * @returns {Object} Plugin definition
+ */
+function schemaExplorerPlugin(options = {}) {
+  const {
+    path = '/_schema',
+    enabled,
+    exclude = [],
+    includeColumns = true,
+    includeRelations = true,
+    includeScopes = true,
+    authorize,
+  } = options;
+
+  return {
+    name: 'schema-explorer',
+    version: '1.0.0',
+
+    // Expose API for other plugins
+    api: {
+      /**
+       * Get all models metadata
+       * @returns {Object[]}
+       */
+      getModels() {
+        return serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+      },
+
+      /**
+       * Get single model metadata
+       * @param {string} name - Model name
+       * @returns {Object|null}
+       */
+      getModel(name) {
+        const model = getModel(name);
+        if (!model || exclude.includes(name)) return null;
+        return serializeModel(model, { includeColumns, includeRelations, includeScopes });
+      },
+
+      /**
+       * Get model names
+       * @returns {string[]}
+       */
+      getModelNames() {
+        const models = getAllModels();
+        return [...models.keys()].filter(name => !exclude.includes(name));
+      },
+    },
+
+    onRoutesReady(ctx) {
+      const isDev = process.env.NODE_ENV !== 'production';
+      const isEnabled = enabled !== undefined ? enabled : isDev;
+
+      if (!isEnabled) {
+        return;
+      }
+
+      // List all models
+      ctx.addRoute('get', path, (req, res) => {
+        // Check authorization
+        if (authorize && !authorize(req)) {
+          return res.status(403).json({ error: 'Forbidden' });
+        }
+
+        const models = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+
+        res.json({
+          meta: {
+            version: '1.0.0',
+            generatedAt: new Date().toISOString(),
+            modelCount: models.length,
+          },
+          models,
+        });
+      });
+
+      // OpenAPI/JSON Schema export (must be registered before :modelName route)
+      ctx.addRoute('get', `${path}/openapi`, (req, res) => {
+        // Check authorization
+        if (authorize && !authorize(req)) {
+          return res.status(403).json({ error: 'Forbidden' });
+        }
+
+        const openApiSchemas = generateOpenApiSchemas({ exclude });
+
+        res.json({
+          openapi: '3.0.0',
+          info: {
+            title: 'Database Schema',
+            version: '1.0.0',
+          },
+          components: {
+            schemas: openApiSchemas,
+          },
+        });
+      });
+
+      // Get single model by name (must be after /openapi to avoid matching "openapi" as modelName)
+      ctx.addRoute('get', `${path}/:modelName`, (req, res) => {
+        // Check authorization
+        if (authorize && !authorize(req)) {
+          return res.status(403).json({ error: 'Forbidden' });
+        }
+
+        const { modelName } = req.params;
+        const model = getModel(modelName);
+
+        if (!model || exclude.includes(modelName)) {
+          return res.status(404).json({ error: `Model "${modelName}" not found` });
+        }
+
+        res.json({
+          meta: {
+            version: '1.0.0',
+            generatedAt: new Date().toISOString(),
+          },
+          model: serializeModel(model, { includeColumns, includeRelations, includeScopes }),
+        });
+      });
+
+      if (isDev) {
+        console.log(`  📋 Schema Explorer: ${path}`);
+      }
+    },
+  };
+}
+
+/**
+ * Serialize all models
+ * @param {Object} options
+ * @returns {Object[]}
+ */
+function serializeAllModels(options) {
+  const { exclude, includeColumns, includeRelations, includeScopes } = options;
+  const models = getAllModels();
+  const result = [];
+
+  for (const [name, model] of models) {
+    if (exclude.includes(name)) continue;
+    result.push(serializeModel(model, { includeColumns, includeRelations, includeScopes }));
+  }
+
+  // Sort by name
+  result.sort((a, b) => a.name.localeCompare(b.name));
+
+  return result;
+}
+
+/**
+ * Serialize a single model
+ * @param {Object} model - Model definition
+ * @param {Object} options
+ * @returns {Object}
+ */
+function serializeModel(model, options) {
+  const { includeColumns, includeRelations, includeScopes } = options;
+
+  const serialized = {
+    name: model.name,
+    table: model.table,
+    primaryKey: model.primaryKey,
+  };
+
+  // Include columns
+  if (includeColumns && model.columns) {
+    serialized.columns = serializeColumns(model.columns);
+  }
+
+  // Include relations
+  if (includeRelations && model.relations) {
+    serialized.relations = serializeRelations(model.relations);
+  }
+
+  // Include scopes
+  if (includeScopes && model.scopes) {
+    serialized.scopes = {
+      softDelete: model.scopes.softDelete || false,
+      timestamps: model.scopes.timestamps || false,
+      tenant: model.scopes.tenant || null,
+    };
+  }
+
+  return serialized;
+}
+
+/**
+ * Serialize column metadata
+ * @param {Map} columns - Columns map
+ * @returns {Object[]}
+ */
+function serializeColumns(columns) {
+  const result = [];
+
+  for (const [name, meta] of columns) {
+    result.push({
+      name,
+      type: meta.type,
+      nullable: meta.nullable || false,
+      primary: meta.primary || false,
+      autoIncrement: meta.autoIncrement || false,
+      unique: meta.unique || false,
+      index: meta.index || false,
+      default: meta.default,
+      maxLength: meta.maxLength,
+      precision: meta.precision,
+      scale: meta.scale,
+      enumValues: meta.enumValues,
+      references: meta.references,
+      referenceColumn: meta.referenceColumn,
+      auto: meta.auto,
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Serialize relation metadata
+ * @param {Object} relations - Relations object
+ * @returns {Object[]}
+ */
+function serializeRelations(relations) {
+  const result = [];
+
+  for (const [name, relation] of Object.entries(relations)) {
+    // Resolve the model to get its name
+    let relatedModelName = null;
+    try {
+      const relatedModel = relation.model();
+      relatedModelName = relatedModel?.name || null;
+    } catch {
+      // Model not yet defined
+    }
+
+    result.push({
+      name,
+      type: relation.type,
+      relatedModel: relatedModelName,
+      foreignKey: relation.foreignKey,
+      localKey: relation.localKey || 'id',
+    });
+  }
+
+  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/sitemap.js

@@ -0,0 +1,221 @@
+/**
+ * Webspresso Sitemap Plugin
+ * Generates XML sitemap from registered routes
+ */
+
+const { matchPattern } = require('../src/plugin-manager');
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(str) {
+  if (!str) return '';
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Generate sitemap XML content
+ */
+function generateSitemapXml(urls, options = {}) {
+  const { hostname, defaultChangefreq = 'weekly', defaultPriority = 0.8 } = options;
+  
+  let xml = '<?xml version="1.0" encoding="UTF-8"?>\n';
+  xml += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
+  
+  // Add i18n namespace if needed
+  if (urls.some(u => u.alternates && u.alternates.length > 0)) {
+    xml += ' xmlns:xhtml="http://www.w3.org/1999/xhtml"';
+  }
+  xml += '>\n';
+  
+  for (const url of urls) {
+    xml += '  <url>\n';
+    xml += `    <loc>${escapeXml(url.loc)}</loc>\n`;
+    
+    if (url.lastmod) {
+      xml += `    <lastmod>${url.lastmod}</lastmod>\n`;
+    }
+    
+    xml += `    <changefreq>${url.changefreq || defaultChangefreq}</changefreq>\n`;
+    xml += `    <priority>${url.priority || defaultPriority}</priority>\n`;
+    
+    // Add hreflang alternates for i18n
+    if (url.alternates && url.alternates.length > 0) {
+      for (const alt of url.alternates) {
+        xml += `    <xhtml:link rel="alternate" hreflang="${escapeXml(alt.lang)}" href="${escapeXml(alt.href)}"/>\n`;
+      }
+    }
+    
+    xml += '  </url>\n';
+  }
+  
+  xml += '</urlset>';
+  return xml;
+}
+
+/**
+ * Generate robots.txt content
+ */
+function generateRobotsTxt(hostname, options = {}) {
+  const { sitemapPath = '/sitemap.xml', disallow = [] } = options;
+  
+  let txt = 'User-agent: *\n';
+  
+  for (const path of disallow) {
+    txt += `Disallow: ${path}\n`;
+  }
+  
+  txt += '\n';
+  txt += `Sitemap: ${hostname}${sitemapPath}\n`;
+  
+  return txt;
+}
+
+/**
+ * Create the sitemap plugin
+ * @param {Object} options - Plugin options
+ * @param {string} options.hostname - Base URL (e.g., 'https://example.com')
+ * @param {Array<string>} options.exclude - Patterns to exclude (e.g., ['/admin/*', '/api/*'])
+ * @param {string} options.changefreq - Default change frequency
+ * @param {number} options.priority - Default priority (0.0 - 1.0)
+ * @param {boolean} options.i18n - Enable i18n hreflang support
+ * @param {Array<string>} options.locales - Supported locales (defaults to env SUPPORTED_LOCALES)
+ * @param {boolean} options.robots - Generate robots.txt endpoint
+ * @param {Array<string>} options.robotsDisallow - Paths to disallow in robots.txt
+ */
+function sitemapPlugin(options = {}) {
+  const {
+    hostname = process.env.BASE_URL || 'http://localhost:3000',
+    exclude = ['/api/*'],
+    changefreq = 'weekly',
+    priority = 0.8,
+    i18n = false,
+    locales = (process.env.SUPPORTED_LOCALES || 'en').split(','),
+    robots = true,
+    robotsDisallow = []
+  } = options;
+  
+  // Storage for dynamic URLs and exclusions
+  const dynamicUrls = [];
+  const dynamicExclusions = [...exclude];
+  
+  return {
+    name: 'sitemap',
+    version: '1.0.0',
+    _options: options,
+    
+    /**
+     * Public API for other plugins
+     */
+    api: {
+      /**
+       * Add a URL to the sitemap
+       * @param {string} path - URL path
+       * @param {Object} opts - URL options (changefreq, priority, lastmod)
+       */
+      addUrl(path, opts = {}) {
+        dynamicUrls.push({ path, ...opts });
+      },
+      
+      /**
+       * Exclude a pattern from the sitemap
+       * @param {string} pattern - Glob pattern to exclude
+       */
+      exclude(pattern) {
+        dynamicExclusions.push(pattern);
+      },
+      
+      /**
+       * Get all sitemap URLs
+       */
+      getUrls() {
+        return [...dynamicUrls];
+      }
+    },
+    
+    /**
+     * Called after routes are mounted
+     */
+    onRoutesReady(ctx) {
+      // Filter routes for sitemap
+      const sitemapRoutes = ctx.routes
+        .filter(r => r.type === 'ssr')
+        .filter(r => !r.isDynamic) // Exclude dynamic routes
+        .filter(r => {
+          // Check exclusion patterns
+          for (const pattern of dynamicExclusions) {
+            if (matchPattern(r.pattern, pattern)) {
+              return false;
+            }
+          }
+          return true;
+        });
+      
+      // Build URLs
+      const urls = [];
+      
+      for (const route of sitemapRoutes) {
+        const baseUrl = `${hostname.replace(/\/$/, '')}${route.pattern}`;
+        
+        const urlEntry = {
+          loc: baseUrl,
+          changefreq,
+          priority
+        };
+        
+        // Add i18n alternates
+        if (i18n && locales.length > 1) {
+          urlEntry.alternates = locales.map(lang => ({
+            lang,
+            href: `${baseUrl}${baseUrl.includes('?') ? '&' : '?'}lang=${lang}`
+          }));
+        }
+        
+        urls.push(urlEntry);
+      }
+      
+      // Add dynamic URLs
+      for (const dynUrl of dynamicUrls) {
+        const urlEntry = {
+          loc: `${hostname.replace(/\/$/, '')}${dynUrl.path}`,
+          changefreq: dynUrl.changefreq || changefreq,
+          priority: dynUrl.priority || priority,
+          lastmod: dynUrl.lastmod
+        };
+        
+        if (i18n && locales.length > 1 && dynUrl.i18n !== false) {
+          urlEntry.alternates = locales.map(lang => ({
+            lang,
+            href: `${urlEntry.loc}${urlEntry.loc.includes('?') ? '&' : '?'}lang=${lang}`
+          }));
+        }
+        
+        urls.push(urlEntry);
+      }
+      
+      // Register sitemap route
+      ctx.addRoute('get', '/sitemap.xml', (req, res) => {
+        res.type('application/xml');
+        res.send(generateSitemapXml(urls, { hostname, defaultChangefreq: changefreq, defaultPriority: priority }));
+      });
+      
+      // Register robots.txt route
+      if (robots) {
+        ctx.addRoute('get', '/robots.txt', (req, res) => {
+          res.type('text/plain');
+          res.send(generateRobotsTxt(hostname, { disallow: robotsDisallow }));
+        });
+      }
+    }
+  };
+}
+
+module.exports = sitemapPlugin;
+
+
+