@qwickapps/server 1.7.2 → 1.8.0

package/dist-ui-lib/src/dashboard/widgets/DatabaseOperationsWidget.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Database Operations Widget Component
+ * Displays database status and provides manual initialization/recreation controls
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import React from 'react';
+export interface DatabaseOperationsWidgetProps {
+}
+export declare const DatabaseOperationsWidget: React.FC<DatabaseOperationsWidgetProps>;
+export default DatabaseOperationsWidget;

package/dist-ui-lib/src/dashboard/widgets/SeedManagementWidget.d.ts

@@ -1,7 +1,7 @@
 /**
  * Seed Management Widget
  *
- * Displays available seed scripts and allows executing them.
+ * Displays available seed scripts grouped by folder and allows executing them.
  * Part of the maintenance plugin.
  *
  * Copyright (c) 2025 QwickApps.com. All rights reserved.

package/dist-ui-lib/src/dashboard/widgets/index.d.ts

@@ -13,5 +13,6 @@ export { SeedManagementWidget } from './SeedManagementWidget';
 export { ServiceControlWidget } from './ServiceControlWidget';
 export { EnvironmentConfigWidget } from './EnvironmentConfigWidget';
 export { DatabaseOpsWidget } from './DatabaseOpsWidget';
+export { DatabaseOperationsWidget } from './DatabaseOperationsWidget';
 export { LogsMaintenanceWidget } from './LogsMaintenanceWidget';
 export { CacheMaintenanceWidget } from './CacheMaintenanceWidget';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwickapps/server",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Plugin-based application server framework for building websites, APIs, admin dashboards, and full-stack products",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -68,7 +68,7 @@
     "@mui/material": "^7.2.0",
     "@mui/x-data-grid": "^7.29.12",
     "@playwright/test": "^1.57.0",
-    "@qwickapps/auth-client": "^1.1.0",
+    "@qwickapps/auth-client": "^1.2.0",
     "@qwickapps/react-framework": "^1.5.5",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^14.0.0",

package/src/core/control-panel.ts

@@ -39,14 +39,14 @@ import { bearerTokenAuth } from '../plugins/api-keys/index.js';
 import { createCorePlugin } from '../plugins/core/index.js';
 
 // Get the package root directory for serving UI assets
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const _filename = fileURLToPath(import.meta.url);
+const _dirname = dirname(_filename);
 // Handle both src/core and dist/src/core paths - go up to find package root
 // - src/core/control-panel.ts → go up 2 levels to package root
 // - dist/src/core/control-panel.js → go up 3 levels to package root
-const packageRoot = __dirname.includes('/dist/src/')
-  ? join(__dirname, '..', '..', '..') // dist/src/core → package root (3 levels)
-  : join(__dirname, '..', '..'); // src/core → package root (2 levels)
+const packageRoot = _dirname.includes('/dist/src/')
+  ? join(_dirname, '..', '..', '..') // dist/src/core → package root (3 levels)
+  : join(_dirname, '..', '..'); // src/core → package root (2 levels)
 const uiDistPath = join(packageRoot, 'dist-ui');
 
 // Read @qwickapps/server package version

package/src/core/gateway.ts

@@ -21,6 +21,7 @@
  */
 
 import type { Application } from 'express';
+import { createServer } from 'http';
 import type { IncomingMessage, ServerResponse, Server } from 'http';
 import type { Socket } from 'net';
 import type { Duplex } from 'stream';
@@ -35,13 +36,13 @@ import { resolve, join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
 // Get QwickApps Server version from package.json
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const _filename = fileURLToPath(import.meta.url);
+const _dirname = dirname(_filename);
 
 // Find package.json by walking up directories
 // Recommended approach for libraries that work in both source and compiled contexts
 function findPackageJson(): string {
-  let currentDir = __dirname;
+  let currentDir = _dirname;
   // Walk up max 5 levels looking for the correct package.json
   for (let i = 0; i < 5; i++) {
     try {
@@ -1075,7 +1076,7 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
 
   const logger = config.logger || getControlPanelLogger('Gateway');
 
-  // Port configuration - new scheme: 3000 gateway, 3001 cpanel, 3002+ apps
+  // Port configuration - gateway with integrated control panel, apps on 3001+
   const gatewayPort = config.port || parseInt(process.env.GATEWAY_PORT || process.env.PORT || '3000', 10);
   const nodeEnv = process.env.NODE_ENV || 'development';
   const version = config.version || process.env.npm_package_version || '1.0.0';
@@ -1084,7 +1085,6 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
   const cpConfig = config.controlPanel ?? { enabled: true };
   const cpEnabled = cpConfig.enabled !== false;
   const cpPath = cpConfig.path || '/cpanel';
-  const cpPort = cpConfig.port || 3001;
 
   // Create gateway Express app
   const app = express();
@@ -1279,6 +1279,7 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
 
     // 1. Start internal control panel if enabled
     if (cpEnabled) {
+      const cpPort = parseInt(process.env.CPANEL_PORT || String(gatewayPort + 1), 10);
       logger.debug(`Starting control panel on port ${cpPort}...`);
 
       controlPanelInstance = createControlPanel({
@@ -1289,7 +1290,7 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
           logoIconUrl: config.logoIconUrl,
           branding: config.branding,
           cors: config.corsOrigins ? { origins: config.corsOrigins } : undefined,
-          mountPath: '/', // Control panel runs at / internally
+          mountPath: cpPath, // Control panel runs at same path as gateway mount (no path translation needed)
           guard: cpConfig.guard,
           customUiPath: cpConfig.customUiPath,
           links: cpConfig.links,
@@ -1300,20 +1301,132 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
 
       await controlPanelInstance.start();
       logger.debug(`Control panel started on port ${cpPort}`);
+
+      // Check if any plugins require maintenance
+      const pluginsNeedingMaintenance = controlPanelInstance.getPluginRegistry().getPluginsNeedingMaintenance();
+      if (pluginsNeedingMaintenance.length > 0) {
+        logger.warn(
+          `${pluginsNeedingMaintenance.length} plugin(s) require maintenance`,
+          { plugins: pluginsNeedingMaintenance.map(p => p.pluginId) }
+        );
+      }
+
+      // 2. Setup control panel proxies (BEFORE server.listen)
+      // Control panel runs at / internally with APIs at /api and UI at /
+      // We proxy both /api and /cpanel to the control panel
+
+      // Proxy control panel APIs at {cpPath}/api
+      // IMPORTANT: Express strips the API path prefix before passing to middleware,
+      // so we need pathRewrite to reconstruct the full path for the control panel
+      const cpApiPath = `${cpPath}/api`;
+      const apiProxy = createProxyMiddleware({
+        target: `http://localhost:${cpPort}`,
+        changeOrigin: true,
+        pathRewrite: (path) => `/api${path}`, // Express removed {cpPath}/api, add back just /api (control panel APIs are at /api/*)
+        on: {
+          proxyReq: (proxyReq, req) => {
+            // Set X-Forwarded-Prefix so control panel knows its public mount path
+            proxyReq.setHeader('X-Forwarded-Prefix', cpPath);
+            logger.debug(`[API Proxy] Forwarding ${req.method} ${req.url} to control panel`);
+          },
+          proxyRes: (proxyRes, req) => {
+            logger.debug(`[API Proxy] Response for ${req.url}: ${proxyRes.statusCode} ${proxyRes.headers['content-type']}`);
+          },
+          error: (err: Error, req: IncomingMessage, res: ServerResponse | Socket) => {
+            logger.error(`[API Proxy] Error for ${req.url}`, { error: err.message });
+            if (res && 'writeHead' in res && !res.headersSent) {
+              res.writeHead(503, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({
+                error: 'Service Unavailable',
+                message: 'The control panel API is currently unavailable.',
+                details: nodeEnv === 'development' ? err.message : undefined,
+              }));
+            }
+          },
+        },
+      });
+      app.use(cpApiPath, apiProxy);
+      logger.debug(`Setting up proxy: ${cpApiPath} -> http://localhost:${cpPort}/api`);
+      mountedApps.push({ path: cpApiPath, type: 'proxy', target: `http://localhost:${cpPort}` });
     }
 
-    // 2. Create HTTP server
-    server = app.listen(gatewayPort);
+    // 3. Create HTTP server (but don't listen yet - need server object for WS)
+    server = createServer(app);
 
-    // 3. Setup mounted apps (proxy and static)
+    // 4. Setup control panel UI proxy (needs server for WebSocket handling)
+    if (cpEnabled) {
+      const cpPort = parseInt(process.env.CPANEL_PORT || String(gatewayPort + 1), 10);
+
+      // Proxy /cpanel to control panel UI
+      // Express strips cpPath prefix, so we need custom proxy to add it back
+      const cpUiProxy = createProxyMiddleware({
+        target: `http://localhost:${cpPort}`,
+        changeOrigin: true,
+        ws: true,
+        pathRewrite: (path) => `${cpPath}${path}`, // Express removed cpPath, add it back
+        on: {
+          proxyReq: (proxyReq) => {
+            // Set X-Forwarded-Prefix so control panel knows its public mount path
+            proxyReq.setHeader('X-Forwarded-Prefix', cpPath);
+          },
+          error: (err: Error, req: IncomingMessage, res: ServerResponse | Socket) => {
+            logger.error(`[Control Panel UI Proxy] Error for ${req.url}`, { error: err.message });
+            if (res && 'writeHead' in res && !res.headersSent) {
+              res.writeHead(503, { 'Content-Type': 'text/html' });
+              res.end('<h1>Control Panel Unavailable</h1><p>The control panel service is not responding.</p>');
+            }
+          },
+        },
+      });
+      app.use(cpPath, cpUiProxy);
+
+      // WebSocket upgrade handling for control panel
+      server!.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+        if (req.url?.startsWith(cpPath)) {
+          cpUiProxy.upgrade?.(req, socket as Socket, head);
+        }
+      });
+
+      mountedApps.push({ path: cpPath, type: 'proxy', target: `http://localhost:${cpPort}` });
+    }
+
+    // 5. Setup mounted apps (proxy and static)
     const apps = config.apps || [];
 
-    // Add control panel as a proxy app if enabled
+    // If plugins need maintenance, add root-level maintenance page
+    // but keep /cpanel and /diagnostics accessible
     if (cpEnabled) {
-      setupProxyApp({
-        path: cpPath,
-        source: { type: 'proxy', target: `http://localhost:${cpPort}` },
-      }, server);
+      const pluginsNeedingMaintenance = controlPanelInstance!.getPluginRegistry().getPluginsNeedingMaintenance();
+      if (pluginsNeedingMaintenance.length > 0) {
+        logger.info('Adding maintenance page at root path due to plugin failures');
+
+        // Add middleware BEFORE frontend setup to intercept root requests
+        app.use((req, res, next) => {
+          // Allow access to control panel, API, and diagnostics
+          if (req.path.startsWith(cpPath) || req.path.startsWith('/api') || req.path.startsWith('/health') || req.path.startsWith('/ping')) {
+            return next();
+          }
+
+          // Show maintenance page for all other requests to root
+          if (req.path === '/' || (!req.path.startsWith(cpPath) && !req.path.startsWith('/api'))) {
+            const maintenanceConfig: MaintenanceConfig = {
+              enabled: true,
+              title: 'System Maintenance Required',
+              message: `${pluginsNeedingMaintenance.length} system component(s) require attention before the service can start normally.`,
+              contactUrl: `${cpPath}/diagnostics/maintenance`,
+            };
+            const html = generateMaintenancePageHtml(
+              config.productName,
+              maintenanceConfig,
+              config.productName
+            );
+            res.status(503).type('html').send(html);
+            return;
+          }
+
+          next();
+        });
+      }
     }
 
     // Setup additional apps
@@ -1325,9 +1438,16 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
       }
     }
 
-    // 4. Setup frontend app at root
+    // 6. Setup frontend app at root
     setupFrontendApp();
 
+    // 7. Start listening (LAST STEP - after all middleware is registered)
+    await new Promise<void>((resolve) => {
+      server!.listen(gatewayPort, () => {
+        resolve();
+      });
+    });
+
     // Log startup info
     const authInfo = cpConfig.guard?.type === 'basic'
       ? `(auth: ${cpConfig.guard.username})`

package/src/core/plugin-registry.ts

@@ -76,6 +76,48 @@ export interface PluginScope {
   category?: 'read' | 'write' | 'admin';
 }
 
+/**
+ * Result of running a maintenance action
+ */
+export interface MaintenanceActionResult {
+  /** Whether the action succeeded */
+  success: boolean;
+  /** Error message if action failed */
+  error?: string;
+  /** Optional message with additional details */
+  message?: string;
+}
+
+/**
+ * Maintenance action that can be executed to fix a plugin issue
+ */
+export interface MaintenanceAction {
+  /** Unique action identifier (e.g., 'truncate-table', 'migrate-data') */
+  id: string;
+  /** Human-readable action name */
+  name: string;
+  /** Description of what the action does */
+  description: string;
+  /** Whether this action is destructive (shows warning in UI) */
+  destructive?: boolean;
+  /** Handler function that performs the action */
+  handler: () => Promise<MaintenanceActionResult>;
+}
+
+/**
+ * Information about a plugin that requires maintenance
+ */
+export interface PluginMaintenanceInfo {
+  /** Plugin ID that needs maintenance */
+  pluginId: string;
+  /** Error message describing what's wrong */
+  error: string;
+  /** Available actions to fix the issue */
+  actions: MaintenanceAction[];
+  /** Optional suggestion for which action to run */
+  recommendedAction?: string;
+}
+
 /**
  * The Plugin interface - simple lifecycle with event handling
  */
@@ -364,6 +406,25 @@ export interface PluginRegistry {
   /** Register a health check */
   registerHealthCheck(check: HealthCheck): void;
 
+  // ---------------------------------------------------------------------------
+  // Maintenance actions
+  // ---------------------------------------------------------------------------
+
+  /** Register maintenance actions for a plugin that failed to start */
+  registerMaintenance(info: PluginMaintenanceInfo): void;
+
+  /** Get maintenance info for a plugin (if it needs maintenance) */
+  getMaintenanceInfo(pluginId: string): PluginMaintenanceInfo | undefined;
+
+  /** Get all plugins that need maintenance */
+  getPluginsNeedingMaintenance(): PluginMaintenanceInfo[];
+
+  /** Run a maintenance action for a plugin */
+  runMaintenanceAction(pluginId: string, actionId: string): Promise<MaintenanceActionResult>;
+
+  /** Clear maintenance state for a plugin (used after successful fix) */
+  clearMaintenance(pluginId: string): void;
+
   // ---------------------------------------------------------------------------
   // Express integration
   // ---------------------------------------------------------------------------
@@ -406,6 +467,7 @@ export class PluginRegistryImpl implements PluginRegistry {
   private pluginConfigs = new Map<string, PluginConfig>();
   private pluginSlugs = new Map<string, string>();  // pluginId -> slug
   private currentPlugin: string | null = null;  // Track plugin during onStart
+  private maintenanceActions = new Map<string, PluginMaintenanceInfo>();  // pluginId -> maintenance info
 
   private routes: RouteDefinition[] = [];
   private menuItems: MenuContribution[] = [];
@@ -829,6 +891,115 @@ export class PluginRegistryImpl implements PluginRegistry {
       await this.stopPlugin(pluginId);
     }
   }
+
+  // ---------------------------------------------------------------------------
+  // Maintenance actions
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register maintenance actions for a plugin that failed to start
+   */
+  registerMaintenance(info: PluginMaintenanceInfo): void {
+    this.maintenanceActions.set(info.pluginId, info);
+    this.logger.warn(
+      `Plugin ${info.pluginId} requires maintenance: ${info.error}`,
+      { availableActions: info.actions.map(a => a.id) }
+    );
+  }
+
+  /**
+   * Get maintenance info for a plugin (if it needs maintenance)
+   */
+  getMaintenanceInfo(pluginId: string): PluginMaintenanceInfo | undefined {
+    return this.maintenanceActions.get(pluginId);
+  }
+
+  /**
+   * Get all plugins that need maintenance
+   */
+  getPluginsNeedingMaintenance(): PluginMaintenanceInfo[] {
+    return Array.from(this.maintenanceActions.values());
+  }
+
+  /**
+   * Run a maintenance action for a plugin
+   */
+  async runMaintenanceAction(pluginId: string, actionId: string): Promise<MaintenanceActionResult> {
+    const maintenanceInfo = this.maintenanceActions.get(pluginId);
+
+    if (!maintenanceInfo) {
+      return {
+        success: false,
+        error: `Plugin ${pluginId} does not have any registered maintenance actions`,
+      };
+    }
+
+    const action = maintenanceInfo.actions.find(a => a.id === actionId);
+
+    if (!action) {
+      return {
+        success: false,
+        error: `Action ${actionId} not found for plugin ${pluginId}`,
+      };
+    }
+
+    this.logger.info(`Running maintenance action ${actionId} for plugin ${pluginId}`);
+
+    try {
+      const result = await action.handler();
+
+      if (result.success) {
+        this.logger.info(`Maintenance action ${actionId} succeeded for plugin ${pluginId}`);
+
+        // Try to restart the plugin after successful maintenance action
+        const plugin = this.plugins.get(pluginId);
+        const config = this.pluginConfigs.get(pluginId);
+
+        if (plugin && config) {
+          this.logger.info(`Attempting to restart plugin ${pluginId} after maintenance`);
+          const started = await this.startPlugin(plugin, config);
+
+          if (started) {
+            // Plugin started successfully, clear maintenance state
+            this.clearMaintenance(pluginId);
+            return {
+              success: true,
+              message: `${result.message || 'Action completed successfully'}. Plugin restarted successfully.`,
+            };
+          } else {
+            // Plugin still failed to start
+            const pluginInfo = this.listPlugins().find(p => p.id === pluginId);
+            return {
+              success: false,
+              error: `Action completed but plugin failed to restart: ${pluginInfo?.error || 'Unknown error'}`,
+            };
+          }
+        }
+
+        return result;
+      } else {
+        this.logger.error(`Maintenance action ${actionId} failed for plugin ${pluginId}`, { error: result.error });
+        return result;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Maintenance action ${actionId} threw exception for plugin ${pluginId}`, { error: errorMessage });
+      return {
+        success: false,
+        error: `Action threw exception: ${errorMessage}`,
+      };
+    }
+  }
+
+  /**
+   * Clear maintenance state for a plugin (used after successful fix)
+   */
+  clearMaintenance(pluginId: string): void {
+    const wasPresent = this.maintenanceActions.delete(pluginId);
+    if (wasPresent) {
+      this.logger.info(`Cleared maintenance state for plugin ${pluginId}`);
+    }
+  }
 }
 
 // =============================================================================

package/src/index.ts

@@ -310,6 +310,8 @@ export type {
   HealthPluginConfig,
   LogsPluginConfig,
   MaintenancePluginConfig,
+  SeedTask,
+  SeedTaskHandler,
   ConfigPluginConfig,
   DiagnosticsPluginConfig,
   FrontendAppPluginConfig,

package/src/plugins/api-keys/api-keys-plugin.ts

@@ -100,7 +100,64 @@ export function createApiKeysPlugin(config: Partial<ApiKeysPluginConfig> = {}):
       log('Starting API keys plugin');
 
       // Initialize the store (creates tables and RLS policies if needed)
-      await store.initialize();
+      const initResult = await store.initialize();
+
+      if (!initResult.success) {
+        logger.error('API keys store initialization failed', { error: initResult.error });
+
+        // If migration is required, register maintenance actions
+        if (initResult.requiresMaintenance) {
+          registry.registerMaintenance({
+            pluginId: 'api-keys',
+            error: initResult.error || 'Store initialization failed',
+            actions: [
+              {
+                id: 'truncate-api-keys-table',
+                name: 'Clear API Keys Table',
+                description: 'Delete all API keys from the database. This allows the migration to proceed by removing old data.',
+                destructive: true,
+                handler: async () => {
+                  try {
+                    const pool = getPostgres().getPool();
+                    await pool.query('TRUNCATE TABLE "public"."api_keys" CASCADE');
+                    logger.info('API keys table truncated successfully');
+                    return {
+                      success: true,
+                      message: 'API keys table cleared. Plugin will retry initialization.',
+                    };
+                  } catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error('Failed to truncate API keys table', { error: errorMessage });
+                    return {
+                      success: false,
+                      error: `Failed to truncate table: ${errorMessage}`,
+                    };
+                  }
+                },
+              },
+            ],
+            recommendedAction: 'truncate-api-keys-table',
+          });
+
+          logger.warn('API keys plugin requires maintenance - registered recovery actions');
+        }
+
+        // Register unhealthy health check
+        registry.registerHealthCheck({
+          name: 'api-keys-store',
+          type: 'custom',
+          check: async () => ({
+            healthy: false,
+            details: {
+              error: initResult.error || 'Initialization failed',
+              requiresMaintenance: initResult.requiresMaintenance,
+            },
+          }),
+        });
+
+        return;  // Don't continue startup
+      }
+
       log('API keys store initialized');
 
       // Initialize optional Phase 2 stores

package/src/plugins/api-keys/index.ts

@@ -31,6 +31,7 @@ export type {
   UpdateApiKeyParams,
   PostgresApiKeyStoreConfig,
   ApiKeysApiConfig,
+  StoreInitializationResult,
 } from './types.js';
 
 // Zod schemas