@qwickapps/server 1.0.0

package/src/core/logging.ts

@@ -0,0 +1,234 @@
+/**
+ * Control Panel Logging Subsystem
+ *
+ * Provides centralized logging for the control panel and all plugins.
+ * Configures @qwickapps/logging to write to files that the LogsPage can display.
+ *
+ * Environment Variables:
+ *   LOG_LEVEL          - Minimum log level (debug, info, warn, error). Default: debug in dev, info in prod
+ *   LOG_DIR            - Directory for log files. Default: ./logs
+ *   LOG_FILE           - Enable file logging. Default: true
+ *   LOG_FILE_PATH      - Path to log file. Default: ./logs/app.log (used by pino if available)
+ *   LOG_CONSOLE        - Enable console output. Default: true
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { Logger as QwickLogger, getLogger, LogLevel, LogTransport } from '@qwickapps/logging';
+import type { Logger } from './types.js';
+
+export interface LoggingConfig {
+  /** Product namespace for log entries */
+  namespace?: string;
+  /** Minimum log level */
+  level?: LogLevel;
+  /** Directory for log files */
+  logDir?: string;
+  /** Enable file logging */
+  fileLogging?: boolean;
+  /** Enable console output */
+  consoleOutput?: boolean;
+}
+
+// Default configuration
+const DEFAULT_CONFIG: Required<LoggingConfig> = {
+  namespace: 'ControlPanel',
+  level: (process.env.LOG_LEVEL as LogLevel) || (process.env.NODE_ENV === 'production' ? 'info' : 'debug'),
+  logDir: process.env.LOG_DIR || './logs',
+  fileLogging: process.env.LOG_FILE !== 'false',
+  consoleOutput: process.env.LOG_CONSOLE !== 'false',
+};
+
+/**
+ * File transport for writing logs to disk
+ * Used when pino is not available or as additional transport
+ */
+class FileLogTransport implements LogTransport {
+  private logPath: string;
+  private errorLogPath: string;
+
+  constructor(logDir: string) {
+    this.logPath = resolve(logDir, 'app.log');
+    this.errorLogPath = resolve(logDir, 'error.log');
+    this.ensureLogDir(logDir);
+  }
+
+  private ensureLogDir(logDir: string): void {
+    const resolvedDir = resolve(logDir);
+    if (!existsSync(resolvedDir)) {
+      mkdirSync(resolvedDir, { recursive: true });
+    }
+  }
+
+  handle(level: LogLevel, namespace: string, message: string, context?: Record<string, any>): void {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      ns: namespace,
+      msg: message,
+      ...context,
+    };
+
+    const line = JSON.stringify(entry) + '\n';
+
+    try {
+      // Write to app.log
+      appendFileSync(this.logPath, line);
+
+      // Also write errors to error.log
+      if (level === 'error') {
+        appendFileSync(this.errorLogPath, line);
+      }
+    } catch {
+      // Silently fail - don't let logging errors break the application
+    }
+  }
+}
+
+/**
+ * Logging subsystem instance
+ */
+class LoggingSubsystem {
+  private config: Required<LoggingConfig>;
+  private rootLogger: QwickLogger;
+  private fileTransport: FileLogTransport | null = null;
+  private initialized = false;
+
+  constructor() {
+    this.config = { ...DEFAULT_CONFIG };
+    this.rootLogger = getLogger(this.config.namespace);
+  }
+
+  /**
+   * Initialize the logging subsystem with configuration
+   */
+  initialize(config: LoggingConfig = {}): void {
+    if (this.initialized) {
+      return;
+    }
+
+    this.config = { ...DEFAULT_CONFIG, ...config };
+
+    // Set up file transport if enabled
+    if (this.config.fileLogging) {
+      this.fileTransport = new FileLogTransport(this.config.logDir);
+
+      // Configure the root logger with file transport
+      this.rootLogger.setConfig({
+        level: this.config.level,
+        disableConsole: !this.config.consoleOutput,
+        transports: [this.fileTransport],
+      });
+
+      // Set LOG_FILE_PATH for pino (if available)
+      if (!process.env.LOG_FILE_PATH) {
+        process.env.LOG_FILE = 'true';
+        process.env.LOG_FILE_PATH = resolve(this.config.logDir, 'app.log');
+      }
+    } else {
+      this.rootLogger.setConfig({
+        level: this.config.level,
+        disableConsole: !this.config.consoleOutput,
+      });
+    }
+
+    this.initialized = true;
+    this.rootLogger.info('Logging subsystem initialized', {
+      logDir: this.config.logDir,
+      level: this.config.level,
+      fileLogging: this.config.fileLogging,
+      consoleOutput: this.config.consoleOutput,
+      usingPino: this.rootLogger.isUsingPino(),
+    });
+  }
+
+  /**
+   * Get a logger for a specific component/plugin
+   */
+  getLogger(namespace: string): Logger {
+    const childLogger = this.rootLogger.child(namespace);
+
+    // Return a Logger interface compatible with control-panel types
+    return {
+      debug: (message: string, data?: Record<string, unknown>) => {
+        childLogger.debug(message, data || {});
+      },
+      info: (message: string, data?: Record<string, unknown>) => {
+        childLogger.info(message, data || {});
+      },
+      warn: (message: string, data?: Record<string, unknown>) => {
+        childLogger.warn(message, data || {});
+      },
+      error: (message: string, data?: Record<string, unknown>) => {
+        childLogger.error(message, data || {});
+      },
+    };
+  }
+
+  /**
+   * Get the root logger
+   */
+  getRootLogger(): Logger {
+    return this.getLogger('Core');
+  }
+
+  /**
+   * Check if file logging is enabled and working
+   */
+  isFileLoggingEnabled(): boolean {
+    return this.config.fileLogging && this.fileTransport !== null;
+  }
+
+  /**
+   * Get the log directory path
+   */
+  getLogDir(): string {
+    return resolve(this.config.logDir);
+  }
+
+  /**
+   * Get the default log file paths
+   */
+  getLogPaths(): { appLog: string; errorLog: string } {
+    return {
+      appLog: resolve(this.config.logDir, 'app.log'),
+      errorLog: resolve(this.config.logDir, 'error.log'),
+    };
+  }
+}
+
+// Singleton instance
+let loggingSubsystem: LoggingSubsystem | null = null;
+
+/**
+ * Get or create the logging subsystem
+ */
+export function getLoggingSubsystem(): LoggingSubsystem {
+  if (!loggingSubsystem) {
+    loggingSubsystem = new LoggingSubsystem();
+  }
+  return loggingSubsystem;
+}
+
+/**
+ * Initialize the logging subsystem with configuration
+ */
+export function initializeLogging(config: LoggingConfig = {}): LoggingSubsystem {
+  const subsystem = getLoggingSubsystem();
+  subsystem.initialize(config);
+  return subsystem;
+}
+
+/**
+ * Get a logger for a specific namespace
+ */
+export function getControlPanelLogger(namespace: string): Logger {
+  return getLoggingSubsystem().getLogger(namespace);
+}
+
+/**
+ * Export for convenience
+ */
+export { LoggingSubsystem };

package/src/core/types.ts

@@ -0,0 +1,218 @@
+/**
+ * Type definitions for @qwickapps/server
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Application, RequestHandler, Router } from 'express';
+
+/**
+ * Control Panel Configuration
+ */
+export interface ControlPanelConfig {
+  /** Product name displayed in the control panel */
+  productName: string;
+
+  /** Port to run the control panel on */
+  port: number;
+
+  /** Optional: Product version */
+  version?: string;
+
+  /** Optional: Branding configuration */
+  branding?: {
+    logo?: string;
+    primaryColor?: string;
+    favicon?: string;
+  };
+
+  /** Optional: Authentication configuration */
+  auth?: {
+    enabled: boolean;
+    provider: 'basic' | 'jwt' | 'custom';
+    users?: Array<{ username: string; password: string }>;
+    jwtSecret?: string;
+    customMiddleware?: RequestHandler;
+  };
+
+  /** Optional: CORS configuration */
+  cors?: {
+    origins: string[];
+  };
+
+  /** Optional: Quick links to display */
+  links?: Array<{
+    label: string;
+    url: string;
+    icon?: string;
+    external?: boolean;
+    requiresHealth?: string; // Only show when this health check passes
+  }>;
+
+  /** Optional: Paths to skip body parsing for (useful for proxy middleware) */
+  skipBodyParserPaths?: string[];
+
+  /** Optional: Disable the built-in dashboard HTML (set true when serving a custom React UI) */
+  disableDashboard?: boolean;
+
+  /** Optional: Use rich React UI instead of basic HTML (default: true if dist-ui exists) */
+  useRichUI?: boolean;
+
+  /** Optional: Custom path to a dist-ui folder for serving a custom React UI */
+  customUiPath?: string;
+}
+
+/**
+ * Plugin Context - passed to plugins during initialization
+ */
+export interface PluginContext {
+  config: ControlPanelConfig;
+  app: Application;
+  router: Router;
+  logger: Logger;
+  registerHealthCheck: (check: HealthCheck) => void;
+}
+
+/**
+ * Control Panel Plugin interface
+ */
+export interface ControlPanelPlugin {
+  /** Unique plugin name */
+  name: string;
+
+  /** Order for tab display (lower = first) */
+  order?: number;
+
+  /** API routes provided by this plugin */
+  routes?: Array<{
+    method: 'get' | 'post' | 'put' | 'delete';
+    path: string;
+    handler: RequestHandler;
+  }>;
+
+  /** Lifecycle: Initialize plugin */
+  onInit?: (context: PluginContext) => Promise<void>;
+
+  /** Lifecycle: Shutdown plugin */
+  onShutdown?: () => Promise<void>;
+}
+
+/**
+ * Health Check types
+ */
+export type HealthCheckType = 'http' | 'tcp' | 'custom';
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
+
+export interface HealthCheckResult {
+  status: HealthStatus;
+  latency?: number;
+  message?: string;
+  lastChecked: Date;
+  details?: Record<string, unknown>;
+}
+
+export interface HealthCheck {
+  name: string;
+  type: HealthCheckType;
+  /** For http checks */
+  url?: string;
+  /** For tcp checks */
+  host?: string;
+  port?: number;
+  /** Check interval in ms */
+  interval?: number;
+  /** Timeout in ms */
+  timeout?: number;
+  /** For custom checks */
+  check?: () => Promise<{ healthy: boolean; latency?: number; details?: Record<string, unknown> }>;
+}
+
+/**
+ * Log Source Configuration
+ */
+export interface LogSource {
+  name: string;
+  type: 'file' | 'api';
+  path?: string; // For file sources
+  url?: string; // For API sources
+}
+
+/**
+ * Config Display Configuration
+ */
+export interface ConfigDisplayOptions {
+  /** Environment variables to show */
+  show: string[];
+  /** Environment variables to mask */
+  mask: string[];
+  /** Validation rules */
+  validate?: Array<{
+    key: string;
+    required?: boolean;
+    pattern?: RegExp;
+    minLength?: number;
+  }>;
+}
+
+/**
+ * Simple logger interface
+ */
+export interface Logger {
+  debug: (message: string, data?: Record<string, unknown>) => void;
+  info: (message: string, data?: Record<string, unknown>) => void;
+  warn: (message: string, data?: Record<string, unknown>) => void;
+  error: (message: string, data?: Record<string, unknown>) => void;
+}
+
+/**
+ * Control Panel Instance
+ */
+export interface ControlPanelInstance {
+  /** Express application */
+  app: Application;
+
+  /** Start the control panel server */
+  start: () => Promise<void>;
+
+  /** Stop the control panel server */
+  stop: () => Promise<void>;
+
+  /** Register a plugin */
+  registerPlugin: (plugin: ControlPanelPlugin) => Promise<void>;
+
+  /** Get health check results */
+  getHealthStatus: () => Record<string, HealthCheckResult>;
+
+  /** Get diagnostics for AI agents */
+  getDiagnostics: () => DiagnosticsReport;
+}
+
+/**
+ * Diagnostics Report for AI agents
+ */
+export interface DiagnosticsReport {
+  timestamp: string;
+  product: string;
+  version?: string;
+  uptime: number;
+  health: Record<string, HealthCheckResult>;
+  system: {
+    nodeVersion: string;
+    platform: string;
+    arch: string;
+    memory: {
+      total: number;
+      used: number;
+      free: number;
+    };
+    cpu: {
+      usage: number;
+    };
+  };
+  config?: Record<string, string>;
+  logs?: {
+    startup: string[];
+    recent: string[];
+    errors: string[];
+  };
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @qwickapps/server
+ *
+ * Independent control panel and management UI for QwickApps services
+ * Runs on a separate port, provides health checks, logs, config, and diagnostics
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Core exports
+export { createControlPanel } from './core/control-panel.js';
+export { createGateway } from './core/gateway.js';
+export { HealthManager } from './core/health-manager.js';
+
+// Logging exports
+export {
+  initializeLogging,
+  getControlPanelLogger,
+  getLoggingSubsystem,
+} from './core/logging.js';
+export type { LoggingConfig } from './core/logging.js';
+
+export type {
+  ControlPanelConfig,
+  ControlPanelPlugin,
+  ControlPanelInstance,
+  PluginContext,
+  HealthCheck,
+  HealthCheckType,
+  HealthCheckResult,
+  HealthStatus,
+  LogSource,
+  ConfigDisplayOptions,
+  Logger,
+  DiagnosticsReport,
+} from './core/types.js';
+export type {
+  GatewayConfig,
+  GatewayInstance,
+  ServiceFactory,
+} from './core/gateway.js';
+
+// Built-in plugins
+export {
+  createHealthPlugin,
+  createLogsPlugin,
+  createConfigPlugin,
+  createDiagnosticsPlugin,
+} from './plugins/index.js';
+export type {
+  HealthPluginConfig,
+  LogsPluginConfig,
+  ConfigPluginConfig,
+  DiagnosticsPluginConfig,
+} from './plugins/index.js';

package/src/plugins/config-plugin.ts

@@ -0,0 +1,117 @@
+/**
+ * Config Plugin
+ *
+ * Displays configuration and environment variables with secret masking
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response } from 'express';
+import type { ControlPanelPlugin, ConfigDisplayOptions, PluginContext } from '../core/types.js';
+
+export interface ConfigPluginConfig extends ConfigDisplayOptions {}
+
+interface ConfigValidationResult {
+  key: string;
+  valid: boolean;
+  message?: string;
+}
+
+/**
+ * Create a config display plugin
+ */
+export function createConfigPlugin(config: ConfigPluginConfig): ControlPanelPlugin {
+  return {
+    name: 'config',
+    order: 30,
+
+    routes: [
+      {
+        method: 'get',
+        path: '/config',
+        handler: (_req: Request, res: Response) => {
+          const envVars: Record<string, string> = {};
+
+          // Get visible env vars
+          for (const key of config.show) {
+            const value = process.env[key];
+            if (value !== undefined) {
+              // Mask if in mask list
+              if (config.mask.some((m) => key.toLowerCase().includes(m.toLowerCase()))) {
+                envVars[key] = maskValue(value);
+              } else {
+                envVars[key] = value;
+              }
+            } else {
+              envVars[key] = '<not set>';
+            }
+          }
+
+          res.json({
+            environment: process.env.NODE_ENV || 'development',
+            config: envVars,
+          });
+        },
+      },
+      {
+        method: 'get',
+        path: '/config/validate',
+        handler: (_req: Request, res: Response) => {
+          const results: ConfigValidationResult[] = [];
+          let allValid = true;
+
+          if (config.validate) {
+            for (const rule of config.validate) {
+              const value = process.env[rule.key];
+              let valid = true;
+              let message: string | undefined;
+
+              // Required check
+              if (rule.required && !value) {
+                valid = false;
+                message = `Required environment variable "${rule.key}" is not set`;
+              }
+
+              // Pattern check
+              if (valid && value && rule.pattern && !rule.pattern.test(value)) {
+                valid = false;
+                message = `Environment variable "${rule.key}" does not match expected pattern`;
+              }
+
+              // Min length check
+              if (valid && value && rule.minLength && value.length < rule.minLength) {
+                valid = false;
+                message = `Environment variable "${rule.key}" is too short (min ${rule.minLength} chars)`;
+              }
+
+              if (!valid) {
+                allValid = false;
+              }
+
+              results.push({ key: rule.key, valid, message });
+            }
+          }
+
+          res.json({
+            valid: allValid,
+            results,
+          });
+        },
+      },
+    ],
+
+    async onInit(context: PluginContext): Promise<void> {
+      context.logger.info(`[ConfigPlugin] Initialized with ${config.show.length} visible vars`);
+    },
+  };
+}
+
+/**
+ * Mask a sensitive value
+ */
+function maskValue(value: string): string {
+  if (value.length <= 4) {
+    return '****';
+  }
+  return value.substring(0, 2) + '*'.repeat(value.length - 4) + value.substring(value.length - 2);
+}