webspresso 0.0.45 → 0.0.47

package/README.md

@@ -254,6 +254,7 @@ Creates and configures the Express app.
 - `pagesDir` (required): Path to pages directory
 - `viewsDir` (optional): Path to views/layouts directory
 - `publicDir` (optional): Path to public/static directory
+- `db` (optional): Database instance — exposed as `ctx.db` in plugin hooks (`register`, `onRoutesReady`) and in page `load`/`meta` functions
 - `logging` (optional): Enable request logging (default: true in development)
 - `helmet` (optional): Helmet security configuration
   - `true` or `undefined`: Use default secure configuration
@@ -633,6 +634,11 @@ const myPlugin = {
     // Access Express app
     ctx.app.use((req, res, next) => next());
     
+    // Access database (when createApp({ db }) is used)
+    if (ctx.db) {
+      // Use ctx.db.getRepository('Model'), ctx.db.knex, etc.
+    }
+    
     // Add template helpers
     ctx.addHelper('myHelper', () => 'Hello!');
     
@@ -645,6 +651,7 @@ const myPlugin = {
   
   // Called after all routes are mounted
   onRoutesReady(ctx) {
+    // ctx.db available when createApp({ db }) is used
     // Access route metadata
     console.log('Routes:', ctx.routes);
     
@@ -777,6 +784,11 @@ module.exports = {
   
   // Load data for SSR
   async load(req, ctx) {
+    // ctx.db is available when createApp({ db }) is used
+    if (ctx.db) {
+      const posts = await ctx.db.getRepository('Post').query().limit(10);
+      return { posts };
+    }
     return { tools: await fetchTools() };
   },
   
@@ -1043,6 +1055,8 @@ const db = createDatabase({
 const UserRepo = db.getRepository('User');
 ```
 
+Pass `db` to `createApp({ db })` to expose it as `ctx.db` in plugin hooks and page `load`/`meta` functions.
+
 **Model File Structure:**
 - Place model files in `models/` directory (or custom path via `config.models`)
 - Each file should export a model defined with `defineModel()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "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": {

package/plugins/admin-panel/core/admin-module.js

@@ -0,0 +1,146 @@
+/**
+ * Admin Module Registration System
+ * Declarative API for registering admin pages, menu items, API routes, and widgets
+ * @module plugins/admin-panel/core/admin-module
+ */
+
+/**
+ * Register an admin module with all its components in a single declarative call
+ * @param {Object} config - Module configuration
+ * @param {string} config.id - Unique module identifier (required)
+ * @param {Array} [config.pages] - Custom admin pages
+ * @param {Array} [config.menu] - Sidebar menu items
+ * @param {Object} [config.menuGroups] - Menu group definitions
+ * @param {Object} [config.api] - API endpoint definitions
+ * @param {Array} [config.widgets] - Dashboard widgets
+ * @param {Object} deps - Internal dependencies injected by admin-panel
+ * @param {Object} deps.registry - AdminRegistry instance
+ * @param {string} deps.adminPath - Admin panel base path
+ * @param {Object} deps.ctx - Plugin context
+ * @param {Function} deps.requireAuth - Auth middleware
+ * @param {Function} deps.optionalAuth - Optional auth middleware
+ * @param {Function} deps.serveAdminPanel - SPA HTML handler
+ */
+function registerModule(config, deps) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('registerModule requires a config object');
+  }
+
+  if (!config.id || typeof config.id !== 'string') {
+    throw new Error('registerModule requires a string "id" field');
+  }
+
+  const { registry, adminPath, ctx, requireAuth, optionalAuth, serveAdminPanel } = deps;
+
+  if (config.menuGroups) {
+    registerMenuGroups(config.menuGroups, registry);
+  }
+
+  if (config.pages) {
+    registerPages(config.id, config.pages, { registry, adminPath, ctx, optionalAuth, serveAdminPanel });
+  }
+
+  if (config.menu) {
+    registerMenuItems(config.menu, registry);
+  }
+
+  if (config.api) {
+    registerApiRoutes(config.id, config.api, { adminPath, ctx, requireAuth, optionalAuth });
+  }
+
+  if (config.widgets) {
+    registerWidgets(config.widgets, registry);
+  }
+}
+
+function registerPages(moduleId, pages, deps) {
+  if (!Array.isArray(pages)) {
+    throw new Error(`Module "${moduleId}": pages must be an array`);
+  }
+
+  const { registry, adminPath, ctx, optionalAuth, serveAdminPanel } = deps;
+
+  for (const page of pages) {
+    const pageId = page.id || moduleId;
+
+    if (!page.title || !page.path) {
+      throw new Error(`Module "${moduleId}", page "${pageId}": requires title and path`);
+    }
+
+    registry.registerPage(pageId, {
+      title: page.title,
+      path: page.path,
+      icon: page.icon,
+      description: page.description,
+      permission: page.permission,
+    });
+
+    if (page.component) {
+      registry.registerClientComponent(pageId, page.component);
+    }
+
+    ctx.addRoute('get', `${adminPath}${page.path}`, optionalAuth, serveAdminPanel);
+  }
+}
+
+function registerMenuItems(menu, registry) {
+  if (!Array.isArray(menu)) {
+    throw new Error('menu must be an array');
+  }
+
+  for (const item of menu) {
+    registry.registerMenuItem(item);
+  }
+}
+
+function registerMenuGroups(menuGroups, registry) {
+  if (typeof menuGroups !== 'object' || Array.isArray(menuGroups)) {
+    throw new Error('menuGroups must be an object');
+  }
+
+  for (const [id, config] of Object.entries(menuGroups)) {
+    registry.registerMenuGroup(id, config);
+  }
+}
+
+function registerApiRoutes(moduleId, apiConfig, deps) {
+  if (typeof apiConfig !== 'object') {
+    throw new Error(`Module "${moduleId}": api must be an object`);
+  }
+
+  const { adminPath, ctx, requireAuth, optionalAuth } = deps;
+  const prefix = apiConfig.prefix || '';
+  const defaultAuth = apiConfig.auth !== false;
+
+  if (!Array.isArray(apiConfig.routes)) {
+    throw new Error(`Module "${moduleId}": api.routes must be an array`);
+  }
+
+  for (const route of apiConfig.routes) {
+    if (!route.path || typeof route.handler !== 'function') {
+      throw new Error(`Module "${moduleId}": each API route requires path and handler`);
+    }
+
+    const method = (route.method || 'get').toLowerCase();
+    const fullPath = `${adminPath}/api${prefix}${route.path}`;
+    const useAuth = route.auth !== undefined ? route.auth : defaultAuth;
+    const authMiddleware = useAuth ? requireAuth : optionalAuth;
+
+    ctx.addRoute(method, fullPath, authMiddleware, route.handler);
+  }
+}
+
+function registerWidgets(widgets, registry) {
+  if (!Array.isArray(widgets)) {
+    throw new Error('widgets must be an array');
+  }
+
+  for (const widget of widgets) {
+    if (!widget.id) {
+      throw new Error('Each widget requires an id');
+    }
+    registry.registerWidget(widget.id, widget);
+  }
+}
+
+module.exports = { registerModule };

package/plugins/admin-panel/index.js

@@ -15,6 +15,7 @@ const { registerDashboardWidgets, generateDashboardComponent } = require('./modu
 const { registerDefaultBulkActions, generateBulkActionsComponent } = require('./modules/bulk-actions');
 const { registerDefaultPages, createCustomPageApiHandlers, generateCustomPageComponent } = require('./modules/custom-pages');
 const { registerModelMenuItems, registerSystemMenuItems, generateMenuComponent } = require('./modules/menu');
+const { registerModule } = require('./core/admin-module');
 
 /**
  * Admin Panel Plugin Factory
@@ -64,10 +65,15 @@ function adminPanelPlugin(options = {}) {
     version: '2.0.0',
     description: 'Modular admin panel for Webspresso with extensions support',
     
-    // CSP requirements for Quill.js rich text editor
+    // CSP requirements for admin panel scripts
     csp: {
       styleSrc: ['https://cdn.quilljs.com'],
-      scriptSrc: ['https://cdn.quilljs.com'],
+      scriptSrc: [
+        'https://cdn.quilljs.com',
+        'https://unpkg.com',
+        'https://cdn.tailwindcss.com',
+      ],
+      connectSrc: ['https://unpkg.com', 'https://cdn.tailwindcss.com'],
     },
     enabled,
     registry, // Expose registry for external configuration
@@ -78,6 +84,20 @@ function adminPanelPlugin(options = {}) {
       serveAdminPanel,
       requireAuth,
       optionalAuth,
+      registerModule(config) {
+        if (!this._ctx) {
+          throw new Error('registerModule can only be called during or after onRoutesReady');
+        }
+        return registerModule(config, {
+          registry,
+          adminPath,
+          ctx: this._ctx,
+          requireAuth,
+          optionalAuth,
+          serveAdminPanel,
+        });
+      },
+      _ctx: null,
     },
 
     /**
@@ -101,6 +121,7 @@ function adminPanelPlugin(options = {}) {
         return;
       }
 
+      this.api._ctx = ctx;
       const { app } = ctx;
 
       // Create and register AdminUser model

package/plugins/site-analytics/index.js

@@ -37,6 +37,7 @@ function siteAnalyticsPlugin(options = {}) {
 
     csp: {
       scriptSrc: ['https://cdn.jsdelivr.net'],
+      connectSrc: ['https://cdn.jsdelivr.net'],
     },
 
     register(ctx) {
@@ -59,42 +60,40 @@ function siteAnalyticsPlugin(options = {}) {
         return;
       }
 
-      const registry = adminApi.getRegistry();
-      const adminPath = adminApi.getAdminPath();
-      const { requireAuth } = adminApi;
       const knex = db.knex || db;
-
-      // Register admin page
-      registry.registerPage('analytics', {
-        title: 'Analytics',
-        path: '/analytics',
-        icon: 'chart',
-      });
-
-      // Register menu item
-      registry.registerMenuItem({
-        id: 'analytics',
-        label: 'Analytics',
-        path: '/analytics',
-        icon: 'chart',
-        order: 2,
-      });
-
-      // Register client-side component
-      registry.registerClientComponent('analytics', generateAnalyticsComponent());
-
-      // API routes
       const handlers = createAnalyticsApiHandlers({ knex, tableName });
 
-      ctx.addRoute('get', `${adminPath}/api/analytics/stats`, requireAuth, handlers.getStats);
-      ctx.addRoute('get', `${adminPath}/api/analytics/views-over-time`, requireAuth, handlers.getViewsOverTime);
-      ctx.addRoute('get', `${adminPath}/api/analytics/top-pages`, requireAuth, handlers.getTopPages);
-      ctx.addRoute('get', `${adminPath}/api/analytics/bot-activity`, requireAuth, handlers.getBotActivity);
-      ctx.addRoute('get', `${adminPath}/api/analytics/countries`, requireAuth, handlers.getCountries);
-      ctx.addRoute('get', `${adminPath}/api/analytics/recent`, requireAuth, handlers.getRecent);
+      adminApi.registerModule({
+        id: 'analytics',
 
-      // Serve admin SPA for the analytics route
-      ctx.addRoute('get', `${adminPath}/analytics`, adminApi.optionalAuth, adminApi.serveAdminPanel);
+        pages: [{
+          id: 'analytics',
+          title: 'Analytics',
+          path: '/analytics',
+          icon: 'chart',
+          component: generateAnalyticsComponent(),
+        }],
+
+        menu: [{
+          id: 'analytics',
+          label: 'Analytics',
+          path: '/analytics',
+          icon: 'chart',
+          order: 2,
+        }],
+
+        api: {
+          prefix: '/analytics',
+          routes: [
+            { method: 'get', path: '/stats', handler: handlers.getStats },
+            { method: 'get', path: '/views-over-time', handler: handlers.getViewsOverTime },
+            { method: 'get', path: '/top-pages', handler: handlers.getTopPages },
+            { method: 'get', path: '/bot-activity', handler: handlers.getBotActivity },
+            { method: 'get', path: '/countries', handler: handlers.getCountries },
+            { method: 'get', path: '/recent', handler: handlers.getRecent },
+          ],
+        },
+      });
     },
   };
 }

package/src/file-router.js

@@ -312,10 +312,11 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
  * @param {Object} options.middlewares - Named middleware registry
  * @param {Object} options.pluginManager - Plugin manager instance
  * @param {boolean} options.silent - Suppress console output
+ * @param {Object} options.db - Database instance (exposed as ctx.db in load/meta)
  * @returns {Array} Route metadata for plugins
  */
 function mountPages(app, options) {
-  const { pagesDir, nunjucks, middlewares = {}, pluginManager = null, silent = false } = options;
+  const { pagesDir, nunjucks, middlewares = {}, pluginManager = null, silent = false, db = null } = options;
   const isDev = process.env.NODE_ENV !== 'production';
   const log = silent ? () => {} : console.log.bind(console);
   
@@ -453,6 +454,7 @@ function mountPages(app, options) {
         const ctx = {
           req,
           res,
+          db,
           path: route.routePath,
           file: route.file,
           routeDir: route.routeDir,

package/src/plugin-manager.js

@@ -351,6 +351,7 @@ class PluginManager {
       app: context.app,
       options: plugin._options || {},
       nunjucksEnv: context.nunjucksEnv,
+      db: context.options?.db ?? null,
 
       /**
        * Get another plugin's API

package/src/server.js

@@ -164,6 +164,7 @@ function haltOnTimedout(req, res, next) {
  * @param {Function|string} options.errorPages.timeout - Custom timeout handler or template path
  * @param {string|boolean} options.timeout - Request timeout (default: '30s', false to disable)
  * @param {Object} options.auth - Authentication manager instance (from createAuth)
+ * @param {Object} options.db - Database instance (exposed as ctx.db to plugins)
  * @returns {Object} { app, nunjucksEnv, pluginManager, authMiddleware }
  */
 function createApp(options = {}) {
@@ -340,7 +341,8 @@ function createApp(options = {}) {
     nunjucks: nunjucksEnv,
     middlewares,
     pluginManager,
-    silent: isTest
+    silent: isTest,
+    db: options.db ?? null
   });
   
   // Set route metadata in plugin manager
@@ -354,6 +356,7 @@ function createApp(options = {}) {
         app,
         nunjucksEnv,
         options,
+        db: options.db ?? null,
         routes: pluginManager.routes,
         usePlugin: (n) => pluginManager.getPluginAPI(n),
         addHelper: (n, fn) => pluginManager.registeredHelpers.set(n, fn),