@qwickapps/server 1.0.0

package/dist/core/control-panel.js

@@ -0,0 +1,416 @@
+/**
+ * Control Panel Core
+ *
+ * Creates and manages the control panel Express application
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import express from 'express';
+import helmet from 'helmet';
+import cors from 'cors';
+import compression from 'compression';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { HealthManager } from './health-manager.js';
+import { initializeLogging, getControlPanelLogger } from './logging.js';
+// Get the package root directory for serving UI assets
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Handle both src/core and dist/core paths - go up to find package root
+const packageRoot = __dirname.includes('/src/')
+    ? join(__dirname, '..', '..')
+    : join(__dirname, '..', '..');
+const uiDistPath = join(packageRoot, 'dist-ui');
+/**
+ * Create a control panel instance
+ */
+export function createControlPanel(options) {
+    const { config, plugins = [], logging: loggingConfig } = options;
+    // Initialize logging subsystem
+    const loggingSubsystem = initializeLogging({
+        namespace: config.productName,
+        ...loggingConfig,
+    });
+    // Use provided logger or get one from the logging subsystem
+    const logger = options.logger || loggingSubsystem.getRootLogger();
+    const app = express();
+    const router = express.Router();
+    const healthManager = new HealthManager(logger);
+    const registeredPlugins = [];
+    let server = null;
+    const startTime = Date.now();
+    // Security middleware
+    app.use(helmet({
+        contentSecurityPolicy: false, // Allow inline scripts for simple UI
+    }));
+    // CORS
+    app.use(cors({
+        origin: config.cors?.origins || '*',
+        credentials: true,
+    }));
+    // Body parsing (skip for specified paths to allow proxy middleware to work)
+    const skipBodyParserPaths = config.skipBodyParserPaths || [];
+    if (skipBodyParserPaths.length > 0) {
+        app.use((req, res, next) => {
+            // Skip body parsing for specified paths (useful for proxy middleware)
+            if (skipBodyParserPaths.some(path => req.path.startsWith(path))) {
+                return next();
+            }
+            express.json()(req, res, next);
+        });
+    }
+    else {
+        app.use(express.json());
+    }
+    app.use(compression());
+    // Basic auth middleware if configured
+    if (config.auth?.enabled && config.auth.provider === 'basic' && config.auth.users) {
+        app.use((req, res, next) => {
+            const authHeader = req.headers.authorization;
+            if (!authHeader || !authHeader.startsWith('Basic ')) {
+                res.set('WWW-Authenticate', 'Basic realm="Control Panel"');
+                return res.status(401).json({ error: 'Authentication required' });
+            }
+            const base64Credentials = authHeader.substring(6);
+            const credentials = Buffer.from(base64Credentials, 'base64').toString('utf-8');
+            const [username, password] = credentials.split(':');
+            const validUser = config.auth.users.find((u) => u.username === username && u.password === password);
+            if (!validUser) {
+                return res.status(401).json({ error: 'Invalid credentials' });
+            }
+            next();
+        });
+    }
+    // Custom auth middleware
+    if (config.auth?.enabled && config.auth.provider === 'custom' && config.auth.customMiddleware) {
+        app.use(config.auth.customMiddleware);
+    }
+    // Request logging
+    app.use((req, _res, next) => {
+        logger.debug(`${req.method} ${req.path}`);
+        next();
+    });
+    // Mount router
+    app.use('/api', router);
+    // Built-in routes
+    /**
+     * GET /api/health - Aggregated health status
+     */
+    router.get('/health', (_req, res) => {
+        const results = healthManager.getResults();
+        const status = healthManager.getAggregatedStatus();
+        const uptime = Date.now() - startTime;
+        res.status(status === 'healthy' ? 200 : status === 'degraded' ? 200 : 503).json({
+            status,
+            timestamp: new Date().toISOString(),
+            uptime,
+            checks: results,
+        });
+    });
+    /**
+     * GET /api/info - Product information
+     */
+    router.get('/info', (_req, res) => {
+        res.json({
+            product: config.productName,
+            version: config.version || 'unknown',
+            uptime: Date.now() - startTime,
+            links: config.links || [],
+            branding: config.branding || {},
+        });
+    });
+    /**
+     * GET /api/diagnostics - Full diagnostics for AI agents
+     */
+    router.get('/diagnostics', (_req, res) => {
+        const report = getDiagnostics();
+        res.json(report);
+    });
+    /**
+     * Serve dashboard UI
+     *
+     * Priority:
+     * 1. If useRichUI is true and dist-ui exists, serve React SPA
+     * 2. Otherwise serve simple static HTML dashboard
+     */
+    if (!config.disableDashboard) {
+        // Use customUiPath if provided, otherwise fall back to package's dist-ui
+        const effectiveUiPath = config.customUiPath || uiDistPath;
+        const hasRichUI = existsSync(effectiveUiPath);
+        const useRichUI = config.useRichUI !== false && hasRichUI;
+        logger.debug(`Dashboard config: __dirname=${__dirname}, effectiveUiPath=${effectiveUiPath}, hasRichUI=${hasRichUI}, useRichUI=${useRichUI}`);
+        if (useRichUI) {
+            logger.info(`Serving rich React UI from ${effectiveUiPath}`);
+            // Serve static assets from dist-ui
+            app.use(express.static(effectiveUiPath));
+            // SPA fallback - serve index.html for all non-API routes
+            app.get('*', (req, res, next) => {
+                // Skip API routes (must check for /api/ with trailing slash to avoid matching /api-keys etc)
+                if (req.path.startsWith('/api/') || req.path === '/api') {
+                    return next();
+                }
+                res.sendFile(join(effectiveUiPath, 'index.html'));
+            });
+        }
+        else {
+            logger.info('Serving basic HTML dashboard');
+            app.get('/', (_req, res) => {
+                const html = generateDashboardHtml(config, healthManager.getResults());
+                res.type('html').send(html);
+            });
+        }
+    }
+    // Plugin context factory - creates context with plugin-specific logger
+    const createPluginContext = (pluginName) => ({
+        config,
+        app,
+        router,
+        logger: getControlPanelLogger(pluginName),
+        registerHealthCheck: (check) => healthManager.register(check),
+    });
+    // Register plugin
+    const registerPlugin = async (plugin) => {
+        logger.info(`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.info(`Plugin registered: ${plugin.name}`);
+    };
+    // Get diagnostics report
+    const getDiagnostics = () => {
+        const memUsage = process.memoryUsage();
+        return {
+            timestamp: new Date().toISOString(),
+            product: config.productName,
+            version: config.version,
+            uptime: Date.now() - startTime,
+            health: healthManager.getResults(),
+            system: {
+                nodeVersion: process.version,
+                platform: process.platform,
+                arch: process.arch,
+                memory: {
+                    total: memUsage.heapTotal,
+                    used: memUsage.heapUsed,
+                    free: memUsage.heapTotal - memUsage.heapUsed,
+                },
+                cpu: {
+                    usage: 0, // Would need os.cpus() for real measurement
+                },
+            },
+        };
+    };
+    // Start server
+    const start = async () => {
+        // Register initial plugins
+        for (const plugin of plugins) {
+            await registerPlugin(plugin);
+        }
+        return new Promise((resolve) => {
+            server = app.listen(config.port, () => {
+                logger.info(`Control panel started on port ${config.port}`);
+                logger.info(`Dashboard: http://localhost:${config.port}`);
+                logger.info(`Health: http://localhost:${config.port}/api/health`);
+                logger.info(`Diagnostics: http://localhost:${config.port}/api/diagnostics`);
+                resolve();
+            });
+        });
+    };
+    // Stop server
+    const stop = async () => {
+        // Shutdown plugins
+        for (const plugin of registeredPlugins) {
+            if (plugin.onShutdown) {
+                await plugin.onShutdown();
+            }
+        }
+        // Shutdown health manager
+        healthManager.shutdown();
+        // Close server
+        if (server) {
+            return new Promise((resolve) => {
+                server.close(() => {
+                    logger.info('Control panel stopped');
+                    resolve();
+                });
+            });
+        }
+    };
+    return {
+        app,
+        start,
+        stop,
+        registerPlugin,
+        getHealthStatus: () => healthManager.getResults(),
+        getDiagnostics,
+    };
+}
+/**
+ * Generate simple dashboard HTML
+ */
+function generateDashboardHtml(config, health) {
+    const healthEntries = Object.entries(health);
+    const overallStatus = healthEntries.every((e) => e[1].status === 'healthy')
+        ? 'healthy'
+        : healthEntries.some((e) => e[1].status === 'unhealthy')
+            ? 'unhealthy'
+            : 'degraded';
+    const statusColor = overallStatus === 'healthy' ? '#22c55e' : overallStatus === 'degraded' ? '#f59e0b' : '#ef4444';
+    const linksHtml = (config.links || [])
+        .map((link) => `<a href="${link.url}" ${link.external ? 'target="_blank"' : ''} class="link">${link.label}</a>`)
+        .join('');
+    const healthHtml = healthEntries
+        .map(([name, result]) => `
+      <div class="health-item">
+        <span class="status-dot" style="background-color: ${result.status === 'healthy' ? '#22c55e' : result.status === 'degraded' ? '#f59e0b' : '#ef4444'}"></span>
+        <span class="name">${name}</span>
+        <span class="latency">${result.latency ? `${result.latency}ms` : '-'}</span>
+      </div>
+    `)
+        .join('');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${config.productName} - Control Panel</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #0f172a;
+      color: #e2e8f0;
+      min-height: 100vh;
+      padding: 2rem;
+    }
+    .container { max-width: 1200px; margin: 0 auto; }
+    header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 2rem;
+      padding-bottom: 1rem;
+      border-bottom: 1px solid #334155;
+    }
+    h1 { font-size: 1.5rem; color: ${config.branding?.primaryColor || '#6366f1'}; }
+    .status-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5rem;
+      padding: 0.5rem 1rem;
+      border-radius: 9999px;
+      background: ${statusColor}20;
+      color: ${statusColor};
+      font-weight: 600;
+    }
+    .status-dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: currentColor;
+    }
+    .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1.5rem; }
+    .card {
+      background: #1e293b;
+      border-radius: 0.75rem;
+      padding: 1.5rem;
+      border: 1px solid #334155;
+    }
+    .card h2 {
+      font-size: 0.875rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: #94a3b8;
+      margin-bottom: 1rem;
+    }
+    .health-item {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      padding: 0.75rem 0;
+      border-bottom: 1px solid #334155;
+    }
+    .health-item:last-child { border-bottom: none; }
+    .health-item .name { flex: 1; }
+    .health-item .latency { color: #64748b; font-size: 0.875rem; }
+    .links { display: flex; flex-wrap: wrap; gap: 0.75rem; }
+    .link {
+      display: inline-block;
+      padding: 0.75rem 1.5rem;
+      background: #334155;
+      color: #e2e8f0;
+      text-decoration: none;
+      border-radius: 0.5rem;
+      transition: background 0.2s;
+    }
+    .link:hover { background: #475569; }
+    .api-links { margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #334155; }
+    .api-links a { color: #6366f1; margin-right: 1.5rem; text-decoration: none; }
+    .api-links a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>${config.productName} Control Panel</h1>
+      <div class="status-badge">
+        <span class="status-dot"></span>
+        ${overallStatus.charAt(0).toUpperCase() + overallStatus.slice(1)}
+      </div>
+    </header>
+
+    <div class="cards">
+      <div class="card">
+        <h2>Health Checks</h2>
+        ${healthHtml || '<p style="color: #64748b;">No health checks configured</p>'}
+      </div>
+
+      ${(config.links || []).length > 0
+        ? `
+      <div class="card">
+        <h2>Quick Links</h2>
+        <div class="links">${linksHtml}</div>
+      </div>
+      `
+        : ''}
+    </div>
+
+    <div class="api-links">
+      <strong>API:</strong>
+      <a href="/api/health">Health</a>
+      <a href="/api/info">Info</a>
+      <a href="/api/diagnostics">Diagnostics</a>
+    </div>
+  </div>
+
+  <script>
+    // Auto-refresh health status every 10 seconds
+    setTimeout(() => location.reload(), 10000);
+  </script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=control-panel.js.map

package/dist/core/control-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-panel.js","sourceRoot":"","sources":["../../src/core/control-panel.ts"],"names":[],"mappings":"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"}

package/dist/core/gateway.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Gateway Server for @qwickapps/server
+ *
+ * Provides a production-ready gateway pattern that:
+ * 1. Serves the control panel UI (always responsive)
+ * 2. Proxies API requests to an internal service
+ * 3. Provides health and diagnostics endpoints
+ *
+ * Architecture:
+ *   Internet → Gateway (GATEWAY_PORT, public) → Service (SERVICE_PORT, internal)
+ *
+ * The gateway is always responsive even if the internal service is down,
+ * allowing diagnostics and error visibility.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Application } from 'express';
+import type { Server } from 'http';
+import type { ControlPanelConfig, ControlPanelPlugin, Logger } from './types.js';
+import { createControlPanel } from './control-panel.js';
+import { type LoggingConfig } from './logging.js';
+/**
+ * Gateway configuration
+ */
+export interface GatewayConfig {
+    /** Port for the gateway (public-facing). Defaults to GATEWAY_PORT env or 3101 */
+    gatewayPort?: number;
+    /** Port for the internal service. Defaults to SERVICE_PORT env or 3100 */
+    servicePort?: number;
+    /** Product name for the control panel */
+    productName: string;
+    /** Product version */
+    version?: string;
+    /** Branding configuration */
+    branding?: ControlPanelConfig['branding'];
+    /** CORS origins */
+    corsOrigins?: string[];
+    /** Control panel plugins */
+    plugins?: ControlPanelPlugin[];
+    /** Quick links for the control panel */
+    links?: ControlPanelConfig['links'];
+    /** Path to custom React UI dist folder */
+    customUiPath?: string;
+    /**
+     * API paths to proxy to the internal service.
+     * Defaults to ['/api/v1'] if not specified.
+     * The gateway always proxies /health to the internal service.
+     */
+    proxyPaths?: string[];
+    /**
+     * Authentication mode for the control panel (not the API).
+     * - 'none': No authentication (not recommended for production)
+     * - 'basic': HTTP Basic Auth with username/password
+     * - 'auto': Auto-generate password on startup (default)
+     */
+    authMode?: 'none' | 'basic' | 'auto';
+    /** Basic auth username (defaults to 'admin') */
+    basicAuthUser?: string;
+    /** Basic auth password (required if authMode is 'basic') */
+    basicAuthPassword?: string;
+    /** Logger instance (deprecated: use logging config instead) */
+    logger?: Logger;
+    /** Logging configuration */
+    logging?: LoggingConfig;
+}
+/**
+ * Service factory function type
+ * Called with the service port, should return an object with:
+ * - app: Express application (or compatible)
+ * - server: HTTP server (created by calling listen)
+ * - shutdown: Async function to gracefully shut down the service
+ */
+export interface ServiceFactory {
+    (port: number): Promise<{
+        app: Application;
+        server: Server;
+        shutdown: () => Promise<void>;
+    }>;
+}
+/**
+ * Gateway instance returned by createGateway
+ */
+export interface GatewayInstance {
+    /** The control panel instance */
+    controlPanel: ReturnType<typeof createControlPanel>;
+    /** The internal service (if started) */
+    service: {
+        app: Application;
+        server: Server;
+        shutdown: () => Promise<void>;
+    } | null;
+    /** Start the gateway and internal service */
+    start: () => Promise<void>;
+    /** Stop everything gracefully */
+    stop: () => Promise<void>;
+    /** Gateway port */
+    gatewayPort: number;
+    /** Service port */
+    servicePort: number;
+}
+/**
+ * Create a gateway that proxies to an internal service
+ *
+ * @param config - Gateway configuration
+ * @param serviceFactory - Factory function to create the internal service
+ * @returns Gateway instance
+ *
+ * @example
+ * ```typescript
+ * import { createGateway } from '@qwickapps/server';
+ *
+ * const gateway = createGateway(
+ *   {
+ *     productName: 'My Service',
+ *     gatewayPort: 3101,
+ *     servicePort: 3100,
+ *   },
+ *   async (port) => {
+ *     const app = createMyApp();
+ *     const server = app.listen(port);
+ *     return {
+ *       app,
+ *       server,
+ *       shutdown: async () => { server.close(); },
+ *     };
+ *   }
+ * );
+ *
+ * await gateway.start();
+ * ```
+ */
+export declare function createGateway(config: GatewayConfig, serviceFactory: ServiceFactory): GatewayInstance;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/core/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/core/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAmC,MAAM,SAAS,CAAC;AAG5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAO5F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IAEpB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAE1C,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEpC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAErC,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACtB,GAAG,EAAE,WAAW,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,YAAY,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IAEpD,wCAAwC;IACxC,OAAO,EAAE;QACP,GAAG,EAAE,WAAW,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/B,GAAG,IAAI,CAAC;IAET,6CAA6C;IAC7C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B,iCAAiC;IACjC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;IAEpB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AA+DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,cAAc,GAC7B,eAAe,CAkMjB"}