@qwickapps/server 1.2.0 → 1.3.0

package/dist-ui-lib/pages/ConfigPage.d.ts

@@ -0,0 +1 @@
+export declare function ConfigPage(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/DashboardPage.d.ts

@@ -0,0 +1 @@
+export declare function DashboardPage(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/DiagnosticsPage.d.ts

@@ -0,0 +1 @@
+export declare function DiagnosticsPage(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/EntitlementsPage.d.ts

@@ -0,0 +1,17 @@
+/**
+ * EntitlementsPage Component
+ *
+ * Entitlement catalog management page. Allows viewing and managing available entitlements.
+ * Write operations (create, edit, delete) are only available when source is not readonly.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export interface EntitlementsPageProps {
+    /** Page title */
+    title?: string;
+    /** Page subtitle */
+    subtitle?: string;
+    /** Custom actions to render in the header */
+    headerActions?: React.ReactNode;
+}
+export declare function EntitlementsPage({ title, subtitle, headerActions, }: EntitlementsPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/LogsPage.d.ts

@@ -0,0 +1 @@
+export declare function LogsPage(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/NotFoundPage.d.ts

@@ -0,0 +1 @@
+export declare function NotFoundPage(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/PluginPage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * PluginPage Component
+ *
+ * A generic page component for plugin-contributed routes.
+ * Fetches and displays plugin-specific content from the API.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+interface PluginPageProps {
+    pluginId: string;
+    title: string;
+    route: string;
+}
+export declare function PluginPage({ pluginId, title, route }: PluginPageProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist-ui-lib/pages/SystemPage.d.ts

@@ -0,0 +1 @@
+export declare function SystemPage(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/UsersPage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * UsersPage Component
+ *
+ * Generic user management page that works with Users, Bans, and Entitlements plugins.
+ * All features are optional and auto-detected based on available plugins.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import { type User, type PluginFeatures } from '../api/controlPanelApi';
+export interface UsersPageProps {
+    /** Page title */
+    title?: string;
+    /** Page subtitle */
+    subtitle?: string;
+    /** Override automatic feature detection */
+    features?: Partial<PluginFeatures>;
+    /** Custom actions to render in the header */
+    headerActions?: React.ReactNode;
+    /** Callback when a user is selected */
+    onUserSelect?: (user: User) => void;
+}
+export declare function UsersPage({ title, subtitle, features: featureOverrides, headerActions, onUserSelect, }: UsersPageProps): import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwickapps/server",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Plugin-based application server framework for building websites, APIs, admin dashboards, and full-stack products",
   "type": "module",
   "main": "dist/index.js",
@@ -13,25 +13,35 @@
     "./plugins": {
       "types": "./dist/plugins/index.d.ts",
       "import": "./dist/plugins/index.js"
+    },
+    "./ui": {
+      "types": "./dist-ui-lib/components/index.d.ts",
+      "import": "./dist-ui-lib/index.js"
     }
   },
   "files": [
     "dist",
     "dist-ui",
+    "dist-ui-lib",
     "src",
     "ui"
   ],
   "scripts": {
-    "build": "npm run build:server && npm run build:ui",
+    "build": "npm run build:server && npm run build:ui && npm run build:ui-lib",
     "build:server": "tsc",
     "build:ui": "cd ui && vite build",
-    "build:clean": "rm -rf dist dist-ui && npm run build",
+    "build:ui-lib": "cd ui && vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json",
+    "build:clean": "rm -rf dist dist-ui dist-ui-lib && npm run build",
     "dev": "tsc --watch",
     "dev:ui": "cd ui && vite",
-    "clean": "rm -rf dist dist-ui node_modules",
+    "clean": "rm -rf dist dist-ui dist-ui-lib node_modules",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "demo": "npx tsx examples/demo-server.ts",
     "type-check": "tsc --noEmit",
     "type-check:ui": "cd ui && tsc --noEmit",
     "validate:clean-install": "./qa/clean-install/validate.sh",
@@ -50,6 +60,7 @@
     "@emotion/styled": "^11.14.0",
     "@mui/icons-material": "^7.2.0",
     "@mui/material": "^7.2.0",
+    "@playwright/test": "^1.57.0",
     "@qwickapps/react-framework": "^1.5.5",
     "@types/compression": "^1.7.5",
     "@types/cors": "^2.8.17",
@@ -57,14 +68,15 @@
     "@types/node": "^20.10.5",
     "@types/pg": "^8.11.0",
     "@types/react": "^18.2.0",
-    "ioredis": "^5.4.0",
-    "pg": "^8.13.0",
     "@types/react-dom": "^18.2.0",
     "@vitejs/plugin-react": "^4.3.4",
     "express-openid-connect": "^2.19.3",
+    "ioredis": "^5.4.0",
+    "pg": "^8.13.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-router-dom": "^6.30.1",
+    "tsx": "^4.20.6",
     "typescript": "^5.3.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0"

package/src/core/control-panel.ts

@@ -10,7 +10,7 @@ import express, { type Application, type Router, type Request, type Response } f
 import helmet from 'helmet';
 import cors from 'cors';
 import compression from 'compression';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { HealthManager } from './health-manager.js';
@@ -18,13 +18,17 @@ import { initializeLogging, getControlPanelLogger, type LoggingConfig } from './
 import { createRouteGuard } from './guards.js';
 import type {
   ControlPanelConfig,
-  ControlPanelPlugin,
   ControlPanelInstance,
-  PluginContext,
   DiagnosticsReport,
   HealthCheck,
   Logger,
 } from './types.js';
+import {
+  createPluginRegistry,
+  type Plugin,
+  type PluginConfig,
+  type PluginRegistryImpl,
+} from './plugin-registry.js';
 
 // Get the package root directory for serving UI assets
 const __filename = fileURLToPath(import.meta.url);
@@ -35,9 +39,22 @@ const packageRoot = __dirname.includes('/src/')
   : join(__dirname, '..', '..');
 const uiDistPath = join(packageRoot, 'dist-ui');
 
+// Read @qwickapps/server package version
+let frameworkVersion = '1.0.0';
+try {
+  const packageJsonPath = join(packageRoot, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    frameworkVersion = packageJson.version || '1.0.0';
+  }
+} catch {
+  // Keep default version if reading fails
+}
+
 export interface CreateControlPanelOptions {
   config: ControlPanelConfig;
-  plugins?: ControlPanelPlugin[];
+  /** Plugins to start with the control panel */
+  plugins?: Array<{ plugin: Plugin; config?: PluginConfig }>;
   logger?: Logger;
   /** Logging configuration */
   logging?: LoggingConfig;
@@ -61,10 +78,18 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
   const app: Application = express();
   const router: Router = express.Router();
   const healthManager = new HealthManager(logger);
-  const registeredPlugins: ControlPanelPlugin[] = [];
   let server: ReturnType<typeof app.listen> | null = null;
   const startTime = Date.now();
 
+  // Initialize the new plugin registry
+  const pluginRegistry = createPluginRegistry(
+    app,
+    router,
+    logger,
+    healthManager,
+    getControlPanelLogger
+  );
+
   // Security middleware
   app.use(
     helmet({
@@ -139,6 +164,8 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
   router.get('/info', (_req: Request, res: Response) => {
     res.json({
       product: config.productName,
+      logoName: config.logoName || config.productName,
+      logoIconUrl: config.logoIconUrl,
       version: config.version || 'unknown',
       uptime: Date.now() - startTime,
       links: config.links || [],
@@ -154,6 +181,30 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
     res.json(report);
   });
 
+  /**
+   * GET /api/ui-contributions - UI contributions from all plugins
+   *
+   * Returns menu items, pages, and widgets registered by plugins.
+   * Used by the React UI to build dynamic navigation and pages.
+   */
+  router.get('/ui-contributions', (_req: Request, res: Response) => {
+    res.json({
+      menuItems: pluginRegistry.getMenuItems(),
+      pages: pluginRegistry.getPages(),
+      widgets: pluginRegistry.getWidgets(),
+      plugins: pluginRegistry.listPlugins(),
+    });
+  });
+
+  /**
+   * GET /api/plugins - List all registered plugins
+   */
+  router.get('/plugins', (_req: Request, res: Response) => {
+    res.json({
+      plugins: pluginRegistry.listPlugins(),
+    });
+  });
+
   /**
    * Serve dashboard UI at the configured mount path
    *
@@ -171,22 +222,61 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
 
     if (useRichUI) {
       logger.debug(`Serving React UI from ${effectiveUiPath}`);
+
+      // Read index.html template
+      const indexHtmlPath = join(effectiveUiPath, 'index.html');
+      const indexHtmlTemplate = readFileSync(indexHtmlPath, 'utf-8');
+
+      /**
+       * Get index.html with the base path injected.
+       *
+       * The server injects the base path as window.__APP_BASE_PATH__ so the React app
+       * can read it at runtime without complex detection logic. This is the standard
+       * pattern used by frameworks like Next.js (__NEXT_DATA__).
+       *
+       * When served behind a gateway proxy, use X-Forwarded-Prefix to determine
+       * the public path for assets and the React Router basename.
+       */
+      const getIndexHtml = (req: Request): string => {
+        // Determine the effective public path:
+        // - If X-Forwarded-Prefix header is set (proxied), use that
+        // - Otherwise, use the configured mountPath
+        const forwardedPrefix = req.get('X-Forwarded-Prefix');
+        const effectivePath = forwardedPrefix || mountPath;
+        const normalizedPath = effectivePath === '/' ? '' : effectivePath;
+
+        // Inject base path as global variable before other scripts
+        const basePathScript = `<script>window.__APP_BASE_PATH__="${normalizedPath}";</script>`;
+        let html = indexHtmlTemplate.replace('<head>', `<head>\n    ${basePathScript}`);
+
+        // Rewrite asset paths if mounted at a subpath
+        if (normalizedPath) {
+          html = html.replace(/src="\/assets\//g, `src="${normalizedPath}/assets/`);
+          html = html.replace(/href="\/assets\//g, `href="${normalizedPath}/assets/`);
+        }
+
+        return html;
+      };
+
       // Serve static assets from dist-ui at the mount path
-      app.use(mountPath, express.static(effectiveUiPath));
+      // Disable index: false to prevent serving index.html automatically
+      // We handle index.html separately with rewritten asset paths
+      app.use(mountPath, express.static(effectiveUiPath, { index: false }));
 
       // SPA fallback - serve index.html for all non-API routes under the mount path
-      app.get(`${mountPath}/*`, (req: Request, res: Response, next) => {
+      const spaFallbackPath = mountPath === '/' ? '/*' : `${mountPath}/*`;
+      app.get(spaFallbackPath, (req: Request, res: Response, next) => {
         // Skip API routes
         if (req.path.startsWith(apiBasePath)) {
           return next();
         }
-        res.sendFile(join(effectiveUiPath, 'index.html'));
+        res.type('html').send(getIndexHtml(req));
       });
 
       // Also serve the mount path root
       if (mountPath !== '/') {
-        app.get(mountPath, (_req: Request, res: Response) => {
-          res.sendFile(join(effectiveUiPath, 'index.html'));
+        app.get(mountPath, (req: Request, res: Response) => {
+          res.type('html').send(getIndexHtml(req));
         });
       }
     } else {
@@ -199,47 +289,9 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
     }
   }
 
-  // Plugin context factory - creates context with plugin-specific logger
-  const createPluginContext = (pluginName: string): PluginContext => ({
-    config,
-    app,
-    router,
-    logger: getControlPanelLogger(pluginName),
-    registerHealthCheck: (check: HealthCheck) => healthManager.register(check),
-  });
-
-  // Register plugin
-  const registerPlugin = async (plugin: ControlPanelPlugin): Promise<void> => {
-    logger.debug(`Registering plugin: ${plugin.name}`);
-
-    // Register routes
-    if (plugin.routes) {
-      for (const route of plugin.routes) {
-        switch (route.method) {
-          case 'get':
-            router.get(route.path, route.handler);
-            break;
-          case 'post':
-            router.post(route.path, route.handler);
-            break;
-          case 'put':
-            router.put(route.path, route.handler);
-            break;
-          case 'delete':
-            router.delete(route.path, route.handler);
-            break;
-        }
-        logger.debug(`Registered route: ${route.method.toUpperCase()} ${route.path}`);
-      }
-    }
-
-    // Initialize plugin with plugin-specific logger
-    if (plugin.onInit) {
-      await plugin.onInit(createPluginContext(plugin.name));
-    }
-
-    registeredPlugins.push(plugin);
-    logger.debug(`Plugin registered: ${plugin.name}`);
+  // Start a plugin with the registry
+  const startPlugin = async (plugin: Plugin, pluginConfig: PluginConfig = {}): Promise<boolean> => {
+    return pluginRegistry.startPlugin(plugin, pluginConfig);
   };
 
   // Get diagnostics report
@@ -250,6 +302,7 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
       timestamp: new Date().toISOString(),
       product: config.productName,
       version: config.version,
+      frameworkVersion,
       uptime: Date.now() - startTime,
       health: healthManager.getResults(),
       system: {
@@ -270,9 +323,12 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
 
   // Start server
   const start = async (): Promise<void> => {
-    // Register initial plugins
-    for (const plugin of plugins) {
-      await registerPlugin(plugin);
+    // Start initial plugins via registry
+    for (const { plugin, config: pluginConfig } of plugins) {
+      const success = await pluginRegistry.startPlugin(plugin, pluginConfig || {});
+      if (!success) {
+        logger.error(`Failed to start plugin: ${plugin.id}`);
+      }
     }
 
     return new Promise((resolve) => {
@@ -285,12 +341,8 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
 
   // Stop server
   const stop = async (): Promise<void> => {
-    // Shutdown plugins
-    for (const plugin of registeredPlugins) {
-      if (plugin.onShutdown) {
-        await plugin.onShutdown();
-      }
-    }
+    // Stop all plugins via registry
+    await pluginRegistry.stopAllPlugins();
 
     // Shutdown health manager
     healthManager.shutdown();
@@ -310,9 +362,10 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
     app,
     start,
     stop,
-    registerPlugin,
+    startPlugin,
     getHealthStatus: () => healthManager.getResults(),
     getDiagnostics,
+    getPluginRegistry: () => pluginRegistry,
   };
 }