webspresso 0.0.96 → 0.0.98

package/plugins/schema-explorer/relations-graph.js

@@ -0,0 +1,205 @@
+/**
+ * Relations Graph & ER Diagram Utilities for Schema Explorer
+ * Analyzes ORM models, builds bidirectional relationship links, and generates Mermaid ER diagrams.
+ */
+
+'use strict';
+
+/**
+ * Extracts and unifies all relationships and foreign keys across all models
+ * @param {Array<Object>} models - Serialized models list
+ * @returns {Array<Object>} List of relationship edge descriptors
+ */
+function extractAllRelationships(models = []) {
+  const modelByName = new Map();
+  const modelByTable = new Map();
+
+  for (const m of models) {
+    if (m && m.name) {
+      modelByName.set(m.name, m);
+    }
+    if (m && m.table) {
+      modelByTable.set(m.table, m);
+    }
+  }
+
+  const relationships = [];
+  const seenKeys = new Set();
+
+  for (const model of models) {
+    if (!model) continue;
+
+    // 1. Process explicit ORM relations
+    const relations = model.relations || [];
+    for (const rel of relations) {
+      if (!rel || !rel.name) continue;
+
+      let targetModelName = rel.relatedModel || null;
+      let targetTableName = rel.relatedTable || null;
+
+      if (targetModelName && modelByName.has(targetModelName)) {
+        targetTableName = targetTableName || modelByName.get(targetModelName).table;
+      } else if (targetTableName && modelByTable.has(targetTableName)) {
+        targetModelName = targetModelName || modelByTable.get(targetTableName).name;
+      }
+
+      const key = `${model.name}:${rel.name}:${targetModelName || targetTableName}:${rel.foreignKey || ''}`;
+      if (seenKeys.has(key)) continue;
+      seenKeys.add(key);
+
+      relationships.push({
+        id: `rel-${model.name}-${rel.name}-${targetModelName || targetTableName || 'unknown'}`,
+        sourceModel: model.name,
+        sourceTable: model.table,
+        name: rel.name,
+        type: rel.type || 'belongsTo',
+        targetModel: targetModelName,
+        targetTable: targetTableName,
+        foreignKey: rel.foreignKey || null,
+        localKey: rel.localKey || 'id',
+        pivotTable: rel.pivotTable || null,
+        pivotForeignKey: rel.pivotForeignKey || null,
+        pivotRelatedForeignKey: rel.pivotRelatedForeignKey || null,
+        inferred: false,
+      });
+    }
+
+    // 2. Process column references (foreign keys defined directly on columns)
+    const columns = model.columns || [];
+    for (const col of columns) {
+      if (!col || !col.references) continue;
+
+      const targetTableName = col.references;
+      const targetModel = modelByTable.get(targetTableName);
+      const targetModelName = targetModel ? targetModel.name : targetTableName;
+
+      // Check if an explicit relation already covers this column
+      const alreadyCovered = relationships.some(
+        r => r.sourceModel === model.name && r.foreignKey === col.name
+      );
+
+      if (!alreadyCovered) {
+        const key = `${model.name}:col_fk:${targetTableName}:${col.name}`;
+        if (!seenKeys.has(key)) {
+          seenKeys.add(key);
+          relationships.push({
+            id: `col-fk-${model.name}-${col.name}-${targetTableName}`,
+            sourceModel: model.name,
+            sourceTable: model.table,
+            name: col.name.replace(/_id$/i, ''),
+            type: 'belongsTo',
+            targetModel: targetModelName,
+            targetTable: targetTableName,
+            foreignKey: col.name,
+            localKey: col.referenceColumn || 'id',
+            inferred: true,
+          });
+        }
+      }
+    }
+  }
+
+  return relationships;
+}
+
+/**
+ * Enriches model objects with incomingRelations, outgoingRelations, and connectedModels
+ * @param {Array<Object>} models - Serialized models list
+ * @param {Array<Object>} [relationships] - Precomputed relationships
+ * @returns {Array<Object>} Enriched models list
+ */
+function enrichModelsWithGraph(models = [], relationships = null) {
+  const rels = relationships || extractAllRelationships(models);
+
+  return models.map(model => {
+    const outgoing = rels.filter(r => r.sourceModel === model.name);
+    const incoming = rels.filter(r => r.targetModel === model.name);
+
+    const connectedSet = new Set();
+    for (const r of outgoing) {
+      if (r.targetModel && r.targetModel !== model.name) connectedSet.add(r.targetModel);
+    }
+    for (const r of incoming) {
+      if (r.sourceModel && r.sourceModel !== model.name) connectedSet.add(r.sourceModel);
+    }
+
+    return {
+      ...model,
+      outgoingRelations: outgoing,
+      incomingRelations: incoming,
+      connectedModels: Array.from(connectedSet),
+    };
+  });
+}
+
+/**
+ * Generates valid Mermaid ER diagram syntax from models and relationships
+ * @param {Array<Object>} models - Serialized models
+ * @param {Array<Object>} [relationships] - Precomputed relationships
+ * @returns {string} Mermaid erDiagram code
+ */
+function generateMermaidErDiagram(models = [], relationships = null) {
+  const rels = relationships || extractAllRelationships(models);
+  const lines = ['erDiagram'];
+
+  // 1. Entities & Attributes
+  for (const m of models) {
+    if (!m || !m.name) continue;
+    const safeModelName = m.name.replace(/[^a-zA-Z0-9_]/g, '_');
+    lines.push(`    ${safeModelName} {`);
+
+    const cols = m.columns || [];
+    for (const col of cols) {
+      const colName = (col.name || 'unnamed').replace(/[^a-zA-Z0-9_]/g, '_');
+      const colType = (col.type || 'string').replace(/[^a-zA-Z0-9_]/g, '_');
+
+      let marker = '';
+      if (col.primary) {
+        marker = ' PK';
+      } else if (col.references || rels.some(r => r.sourceModel === m.name && r.foreignKey === col.name)) {
+        marker = ' FK';
+      } else if (col.unique) {
+        marker = ' UK';
+      }
+
+      lines.push(`        ${colType} ${colName}${marker}`);
+    }
+
+    lines.push('    }');
+  }
+
+  // 2. Relations
+  const seenRelPairs = new Set();
+  for (const rel of rels) {
+    if (!rel.sourceModel || !rel.targetModel) continue;
+
+    const source = rel.sourceModel.replace(/[^a-zA-Z0-9_]/g, '_');
+    const target = rel.targetModel.replace(/[^a-zA-Z0-9_]/g, '_');
+    const pairKey = `${source}:${rel.type}:${target}:${rel.foreignKey || ''}`;
+
+    if (seenRelPairs.has(pairKey)) continue;
+    seenRelPairs.add(pairKey);
+
+    let symbol = '}o--||'; // default belongsTo
+    if (rel.type === 'hasMany') {
+      symbol = '||--o{';
+    } else if (rel.type === 'hasOne') {
+      symbol = '||--||';
+    } else if (rel.type === 'manyToMany') {
+      symbol = '}o--o{';
+    } else if (rel.type === 'belongsTo') {
+      symbol = '}o--||';
+    }
+
+    const label = (rel.name || rel.foreignKey || rel.type || 'relates').replace(/"/g, "'");
+    lines.push(`    ${source} ${symbol} ${target} : "${label}"`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  extractAllRelationships,
+  enrichModelsWithGraph,
+  generateMermaidErDiagram,
+};

package/plugins/schema-explorer.js

@@ -1,23 +1,41 @@
 /**
  * Schema Explorer Plugin
- * Exposes ORM model metadata via API endpoint
- * Useful for documentation, admin tools, and frontend code generation
+ * Exposes ORM model metadata via API endpoint and interactive Admin Panel SPA page.
+ * Useful for documentation, database architecture visualization, ER diagrams, and admin tools.
  */
 
+'use strict';
+
 const { getAllModels, getModel } = require('../core/orm/model');
 const { getColumnMeta } = require('../core/orm/schema-helpers');
 const { generateOrmOpenApiSchemas } = require('../core/openapi/orm-components');
+const {
+  extractAllRelationships,
+  enrichModelsWithGraph,
+  generateMermaidErDiagram,
+} = require('./schema-explorer/relations-graph');
+const {
+  generateSchemaExplorerAdminComponent,
+} = require('./schema-explorer/admin-component');
 
 /**
  * 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 {Object} [options] - Plugin options
+ * @param {string} [options.path='/_schema'] - Raw API endpoint path
+ * @param {boolean} [options.enabled] - Force enable/disable raw API (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
+ * @param {boolean} [options.admin=true] - Enable Admin Panel module when admin-panel plugin is present
+ * @param {string} [options.title] - Admin page title (default: menuLabel or 'Schema Explorer')
+ * @param {string} [options.adminTitle] - Admin page title alias
+ * @param {string} [options.adminPath='/schema'] - Path within admin panel
+ * @param {string} [options.menuLabel='Schema Explorer'] - Admin sidebar menu label
+ * @param {string} [options.menuIcon='database'] - Admin sidebar icon
+ * @param {number} [options.menuOrder=85] - Admin sidebar menu order
+ * @param {string} [options.apiPrefix='/schema'] - Admin API prefix under /_admin/api
  * @returns {Object} Plugin definition
  */
 function schemaExplorerPlugin(options = {}) {
@@ -29,13 +47,24 @@ function schemaExplorerPlugin(options = {}) {
     includeRelations = true,
     includeScopes = true,
     authorize,
+    admin = true,
+    adminPath = '/schema',
+    title,
+    adminTitle,
+    menuLabel = 'Schema Explorer',
+    menuIcon = 'database',
+    menuOrder = 85,
+    apiPrefix = '/schema',
   } = options;
 
+  const pageTitle = title || adminTitle || menuLabel;
+
   return {
     name: 'schema-explorer',
     version: '1.0.0',
+    description: 'Database schema, ER diagram & relation explorer for API and Admin Panel',
 
-    // Expose API for other plugins
+    // Expose API for other plugins & programmatic consumption
     api: {
       /**
        * Get all models metadata
@@ -45,6 +74,16 @@ function schemaExplorerPlugin(options = {}) {
         return serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
       },
 
+      /**
+       * Get all models enriched with incoming/outgoing relationships graph
+       * @returns {Object[]}
+       */
+      getEnrichedModels() {
+        const raw = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+        const rels = extractAllRelationships(raw);
+        return enrichModelsWithGraph(raw, rels);
+      },
+
       /**
        * Get single model metadata
        * @param {string} name - Model name
@@ -64,81 +103,217 @@ function schemaExplorerPlugin(options = {}) {
         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;
+      /**
+       * Get unified relationships graph
+       * @returns {Object[]}
+       */
+      getRelationships() {
+        const raw = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+        return extractAllRelationships(raw);
+      },
 
-      if (!isEnabled) {
-        return;
-      }
+      /**
+       * Generate Mermaid ER diagram syntax
+       * @returns {string}
+       */
+      getMermaid() {
+        const raw = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+        const rels = extractAllRelationships(raw);
+        return generateMermaidErDiagram(raw, rels);
+      },
 
-      // List all models
-      ctx.addRoute('get', path, (req, res) => {
-        // Check authorization
-        if (authorize && !authorize(req)) {
-          return res.status(403).json({ error: 'Forbidden' });
-        }
+      extractAllRelationships,
+      enrichModelsWithGraph,
+      generateMermaidErDiagram,
+    },
 
-        const models = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+    onRoutesReady(ctx) {
+      const isDev = process.env.NODE_ENV !== 'production';
+      const isRawEnabled = enabled !== undefined ? enabled : isDev;
+
+      // 1. Raw API Endpoints (if enabled or dev mode)
+      if (isRawEnabled) {
+        // List all models with schema metadata
+        ctx.addRoute('get', path, (req, res) => {
+          if (authorize && !authorize(req)) {
+            return res.status(403).json({ error: 'Forbidden' });
+          }
+
+          const rawModels = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+          const relationships = extractAllRelationships(rawModels);
+          const models = enrichModelsWithGraph(rawModels, relationships);
+
+          res.json({
+            meta: {
+              version: '1.0.0',
+              generatedAt: new Date().toISOString(),
+              modelCount: models.length,
+              relationCount: relationships.length,
+            },
+            models,
+            relationships,
+          });
+        });
 
-        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) => {
+          if (authorize && !authorize(req)) {
+            return res.status(403).json({ error: 'Forbidden' });
+          }
+
+          const openApiSchemas = generateOrmOpenApiSchemas({ exclude });
+
+          res.json({
+            openapi: '3.0.0',
+            info: {
+              title: 'Database Schema',
+              version: '1.0.0',
+            },
+            components: {
+              schemas: openApiSchemas,
+            },
+          });
         });
-      });
 
-      // 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' });
-        }
+        // Mermaid ER Diagram export
+        ctx.addRoute('get', `${path}/mermaid`, (req, res) => {
+          if (authorize && !authorize(req)) {
+            return res.status(403).json({ error: 'Forbidden' });
+          }
+
+          const rawModels = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+          const relationships = extractAllRelationships(rawModels);
+          const mermaid = generateMermaidErDiagram(rawModels, relationships);
+
+          if (req.accepts('text/plain') && !req.accepts('json')) {
+            res.type('text/plain').send(mermaid);
+          } else {
+            res.json({ mermaid });
+          }
+        });
 
-        const openApiSchemas = generateOrmOpenApiSchemas({ exclude });
-
-        res.json({
-          openapi: '3.0.0',
-          info: {
-            title: 'Database Schema',
-            version: '1.0.0',
-          },
-          components: {
-            schemas: openApiSchemas,
-          },
+        // Get single model by name
+        ctx.addRoute('get', `${path}/:modelName`, (req, res) => {
+          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 }),
+          });
         });
-      });
 
-      // 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' });
+        if (isDev) {
+          console.log(`  📋 Schema Explorer API: ${path}`);
         }
+      }
 
-        const { modelName } = req.params;
-        const model = getModel(modelName);
-
-        if (!model || exclude.includes(modelName)) {
-          return res.status(404).json({ error: `Model "${modelName}" not found` });
+      // 2. Admin Panel Integration (when adminPanelPlugin is present and admin !== false)
+      if (admin !== false && typeof ctx.usePlugin === 'function') {
+        const adminApi = ctx.usePlugin('admin-panel');
+        if (adminApi) {
+          const normAdminPath = adminPath.startsWith('/') ? adminPath : '/' + adminPath;
+
+          adminApi.registerModule({
+            id: 'schema-explorer',
+            title: pageTitle,
+            pages: [{
+              id: 'schema-explorer',
+              title: pageTitle,
+              path: normAdminPath,
+              icon: menuIcon,
+              component: generateSchemaExplorerAdminComponent({ apiPrefix }),
+            }],
+            menu: [{
+              id: 'schema-explorer',
+              label: menuLabel,
+              path: normAdminPath,
+              icon: menuIcon,
+              order: menuOrder,
+            }],
+            api: {
+              prefix: apiPrefix,
+              routes: [
+                {
+                  method: 'get',
+                  path: '',
+                  handler: (req, res) => {
+                    const rawModels = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+                    const relationships = extractAllRelationships(rawModels);
+                    const models = enrichModelsWithGraph(rawModels, relationships);
+                    const mermaid = generateMermaidErDiagram(rawModels, relationships);
+
+                    res.json({
+                      meta: {
+                        version: '1.0.0',
+                        generatedAt: new Date().toISOString(),
+                        modelCount: models.length,
+                        relationCount: relationships.length,
+                      },
+                      models,
+                      relationships,
+                      mermaid,
+                    });
+                  },
+                },
+                {
+                  method: 'get',
+                  path: '/relations',
+                  handler: (req, res) => {
+                    const rawModels = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+                    const relationships = extractAllRelationships(rawModels);
+                    res.json({ relationships });
+                  },
+                },
+                {
+                  method: 'get',
+                  path: '/mermaid',
+                  handler: (req, res) => {
+                    const rawModels = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+                    const relationships = extractAllRelationships(rawModels);
+                    const mermaid = generateMermaidErDiagram(rawModels, relationships);
+                    res.json({ mermaid });
+                  },
+                },
+                {
+                  method: 'get',
+                  path: '/models/:modelName',
+                  handler: (req, res) => {
+                    const { modelName } = req.params;
+                    const model = getModel(modelName);
+
+                    if (!model || exclude.includes(modelName)) {
+                      return res.status(404).json({ error: `Model "${modelName}" not found` });
+                    }
+
+                    const rawModels = serializeAllModels({ exclude, includeColumns, includeRelations, includeScopes });
+                    const relationships = extractAllRelationships(rawModels);
+                    const models = enrichModelsWithGraph(rawModels, relationships);
+                    const found = models.find(m => m.name === modelName);
+
+                    res.json({ model: found });
+                  },
+                },
+              ],
+            },
+          });
+
+          if (isDev) {
+            console.log(`  🗄️ Schema Explorer Admin: ${adminApi.getAdminPath ? adminApi.getAdminPath() : '/_admin'}${normAdminPath}`);
+          }
         }
-
-        res.json({
-          meta: {
-            version: '1.0.0',
-            generatedAt: new Date().toISOString(),
-          },
-          model: serializeModel(model, { includeColumns, includeRelations, includeScopes }),
-        });
-      });
-
-      if (isDev) {
-        console.log(`  📋 Schema Explorer: ${path}`);
       }
     },
   };
@@ -264,4 +439,8 @@ function serializeRelations(relations) {
 }
 
 module.exports = schemaExplorerPlugin;
-
+module.exports.schemaExplorerPlugin = schemaExplorerPlugin;
+module.exports.extractAllRelationships = extractAllRelationships;
+module.exports.enrichModelsWithGraph = enrichModelsWithGraph;
+module.exports.generateMermaidErDiagram = generateMermaidErDiagram;
+module.exports.generateSchemaExplorerAdminComponent = generateSchemaExplorerAdminComponent;

package/plugins/site-analytics/admin-component.js

@@ -203,12 +203,12 @@ var AnalyticsPage = {
     vnode.state.chartLoaded = false;
     vnode.state._stopPoll = null;
     vnode.state.chartDataVersion = 0;
-    this.loadData(vnode);
-    this.loadChartJs(vnode);
+    AnalyticsPage.loadData(vnode);
+    AnalyticsPage.loadChartJs(vnode);
     if (typeof runAdminAutoRefresh === 'function') {
       vnode.state._stopPoll = runAdminAutoRefresh(function() {
-        this.loadData(vnode);
-      }.bind(this));
+        AnalyticsPage.loadData(vnode);
+      });
     }
   },
 
@@ -270,12 +270,11 @@ var AnalyticsPage = {
   setDays: function(vnode, d) {
     vnode.state.days = d;
     if (chartInstance) { chartInstance.destroy(); chartInstance = null; }
-    this.loadData(vnode);
+    AnalyticsPage.loadData(vnode);
   },
 
   view: function(vnode) {
     var s = vnode.state;
-    var self = this;
 
     return m(Layout, [
       m(Breadcrumb, { items: [{ label: 'Analytics', href: '/analytics' }] }),
@@ -294,7 +293,7 @@ var AnalyticsPage = {
             ? m(RefreshIconButton, {
                 title: 'Refresh analytics',
                 spinning: s.loading,
-                onclick: function() { self.loadData(vnode); },
+                onclick: function() { AnalyticsPage.loadData(vnode); },
               })
             : null,
           // Day filter
@@ -303,9 +302,32 @@ var AnalyticsPage = {
               class: s.days === d
                 ? 'bg-white text-gray-900 shadow-sm dark:bg-slate-700 dark:text-slate-100'
                 : 'text-gray-500 hover:text-gray-700 dark:text-slate-400 dark:hover:text-slate-200',
-              onclick: function() { self.setDays(vnode, d); },
+              onclick: function() { AnalyticsPage.setDays(vnode, d); },
             }, 'Last ' + d + ' days');
           })),
+          // Purge old data button
+          m('button.px-3.py-1.5.text-sm.font-medium.rounded-md.border.border-gray-200.dark:border-slate-700.text-gray-600.dark:text-slate-300.hover:bg-gray-50.dark:hover:bg-slate-700.transition-colors.flex.items-center.gap-1.5', {
+            title: 'Purge analytics data older than 90 days and error logs older than 30 days',
+            disabled: s.purging,
+            onclick: function() {
+              if (!confirm('Are you sure you want to purge analytics data older than 90 days and error logs older than 30 days?')) return;
+              s.purging = true;
+              m.redraw();
+              api.post('/analytics/purge', { days: 90, errorDays: 30 })
+                .then(function(res) {
+                  s.purging = false;
+                  var views = (res && res.viewsDeleted != null) ? res.viewsDeleted : 0;
+                  var errs = (res && res.errorsDeleted != null) ? res.errorsDeleted : 0;
+                  alert('Purged ' + views + ' page views and ' + errs + ' client errors.');
+                  AnalyticsPage.loadData(vnode);
+                })
+                .catch(function(err) {
+                  s.purging = false;
+                  alert('Failed to purge analytics: ' + (err && err.message ? err.message : String(err)));
+                  m.redraw();
+                });
+            },
+          }, s.purging ? 'Purging...' : 'Purge Old Data'),
         ]),
       ]),