@qwickapps/server 1.0.0

package/src/plugins/diagnostics-plugin.ts

@@ -0,0 +1,178 @@
+/**
+ * Diagnostics Plugin
+ *
+ * Provides AI-friendly diagnostic API for troubleshooting
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import type { Request, Response } from 'express';
+import type { ControlPanelPlugin, PluginContext } from '../core/types.js';
+
+export interface DiagnosticsPluginConfig {
+  include?: {
+    logs?: {
+      startup?: number; // Last N lines from startup log
+      app?: number; // Last N lines from app log
+    };
+    health?: boolean;
+    config?: boolean;
+    system?: boolean;
+  };
+  logPaths?: {
+    startup?: string;
+    app?: string;
+  };
+  endpoint?: string;
+}
+
+/**
+ * Create a diagnostics plugin for AI agents
+ */
+export function createDiagnosticsPlugin(config: DiagnosticsPluginConfig = {}): ControlPanelPlugin {
+  const {
+    include = { logs: { startup: 100, app: 200 }, health: true, config: true, system: true },
+    logPaths = { startup: './logs/startup.log', app: './logs/app.log' },
+    endpoint = '/diagnostics/full',
+  } = config;
+
+  return {
+    name: 'diagnostics',
+    order: 40,
+
+    routes: [
+      {
+        method: 'get',
+        path: endpoint,
+        handler: (_req: Request, res: Response) => {
+          try {
+            const report: Record<string, unknown> = {
+              timestamp: new Date().toISOString(),
+              generated_for: 'AI Agent Diagnostics',
+            };
+
+            // System info
+            if (include.system) {
+              const memUsage = process.memoryUsage();
+              report.system = {
+                nodeVersion: process.version,
+                platform: process.platform,
+                arch: process.arch,
+                pid: process.pid,
+                cwd: process.cwd(),
+                uptime: process.uptime(),
+                memory: {
+                  rss: formatBytes(memUsage.rss),
+                  heapTotal: formatBytes(memUsage.heapTotal),
+                  heapUsed: formatBytes(memUsage.heapUsed),
+                  external: formatBytes(memUsage.external),
+                },
+              };
+            }
+
+            // Environment check (not values, just presence)
+            if (include.config) {
+              const envCheck: Record<string, boolean> = {
+                NODE_ENV: !!process.env.NODE_ENV,
+                DATABASE_URI: !!process.env.DATABASE_URI,
+                PAYLOAD_SECRET: !!process.env.PAYLOAD_SECRET,
+                LOGFIRE_TOKEN: !!process.env.LOGFIRE_TOKEN,
+              };
+              report.envCheck = envCheck;
+            }
+
+            // Logs
+            if (include.logs) {
+              const logs: Record<string, string[]> = {};
+
+              if (include.logs.startup && logPaths.startup) {
+                logs.startup = readLastNLines(logPaths.startup, include.logs.startup);
+              }
+
+              if (include.logs.app && logPaths.app) {
+                logs.app = readLastNLines(logPaths.app, include.logs.app);
+              }
+
+              // Extract errors
+              const allLogs = [...(logs.startup || []), ...(logs.app || [])];
+              logs.errors = allLogs.filter((line) => {
+                const lower = line.toLowerCase();
+                return lower.includes('error') || lower.includes('fatal') || lower.includes('exception');
+              });
+
+              report.logs = logs;
+            }
+
+            res.json(report);
+          } catch (error) {
+            res.status(500).json({
+              error: 'Failed to generate diagnostics',
+              message: error instanceof Error ? error.message : String(error),
+            });
+          }
+        },
+      },
+      {
+        method: 'get',
+        path: '/diagnostics/summary',
+        handler: (_req: Request, res: Response) => {
+          try {
+            const memUsage = process.memoryUsage();
+
+            res.json({
+              status: 'ok',
+              timestamp: new Date().toISOString(),
+              uptime: process.uptime(),
+              memory: {
+                heapUsed: formatBytes(memUsage.heapUsed),
+                heapTotal: formatBytes(memUsage.heapTotal),
+              },
+              env: process.env.NODE_ENV || 'development',
+            });
+          } catch (error) {
+            res.status(500).json({
+              status: 'error',
+              message: error instanceof Error ? error.message : String(error),
+            });
+          }
+        },
+      },
+    ],
+
+    async onInit(context: PluginContext): Promise<void> {
+      context.logger.info('[DiagnosticsPlugin] Initialized');
+    },
+  };
+}
+
+/**
+ * Read last N lines from a file
+ */
+function readLastNLines(filePath: string, n: number): string[] {
+  const resolvedPath = resolve(filePath);
+
+  if (!existsSync(resolvedPath)) {
+    return [`File not found: ${filePath}`];
+  }
+
+  try {
+    const content = readFileSync(resolvedPath, 'utf-8');
+    const lines = content.split('\n').filter((line) => line.trim());
+    return lines.slice(-n);
+  } catch (error) {
+    return [`Error reading file: ${error instanceof Error ? error.message : String(error)}`];
+  }
+}
+
+/**
+ * Format bytes to human readable
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}

package/src/plugins/health-plugin.ts

@@ -0,0 +1,35 @@
+/**
+ * Health Plugin
+ *
+ * Provides health check monitoring capabilities
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { ControlPanelPlugin, HealthCheck, PluginContext } from '../core/types.js';
+
+export interface HealthPluginConfig {
+  checks: HealthCheck[];
+  aggregateEndpoint?: string;
+}
+
+/**
+ * Create a health check plugin
+ */
+export function createHealthPlugin(config: HealthPluginConfig): ControlPanelPlugin {
+  return {
+    name: 'health',
+    order: 10,
+
+    async onInit(context: PluginContext): Promise<void> {
+      const { registerHealthCheck, logger } = context;
+
+      // Register all health checks
+      for (const check of config.checks) {
+        registerHealthCheck(check);
+      }
+
+      logger.info(`[HealthPlugin] Registered ${config.checks.length} health checks`);
+    },
+  };
+}

package/src/plugins/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Built-in plugins for @qwickapps/server
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { createHealthPlugin } from './health-plugin.js';
+export type { HealthPluginConfig } from './health-plugin.js';
+
+export { createLogsPlugin } from './logs-plugin.js';
+export type { LogsPluginConfig } from './logs-plugin.js';
+
+export { createConfigPlugin } from './config-plugin.js';
+export type { ConfigPluginConfig } from './config-plugin.js';
+
+export { createDiagnosticsPlugin } from './diagnostics-plugin.js';
+export type { DiagnosticsPluginConfig } from './diagnostics-plugin.js';

package/src/plugins/logs-plugin.ts

@@ -0,0 +1,314 @@
+/**
+ * Logs Plugin
+ *
+ * Provides log viewing capabilities from various sources.
+ * If no sources are configured, automatically uses the logging subsystem's log paths.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { existsSync, readFileSync, statSync } from 'fs';
+import { resolve } from 'path';
+import type { Request, Response } from 'express';
+import type { ControlPanelPlugin, LogSource, PluginContext } from '../core/types.js';
+import { getLoggingSubsystem } from '../core/logging.js';
+
+export interface LogsPluginConfig {
+  /** Log sources to display. If empty, uses default sources from logging subsystem */
+  sources?: LogSource[];
+  retention?: {
+    maxLines?: number;
+    autoRefresh?: number;
+  };
+}
+
+interface LogEntry {
+  id: number;
+  level: string;
+  timestamp: string;
+  namespace: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+interface LogStats {
+  totalLogs: number;
+  byLevel: {
+    debug: number;
+    info: number;
+    warn: number;
+    error: number;
+  };
+  fileSize: number;
+  fileSizeFormatted: string;
+  oldestLog: string | null;
+  newestLog: string | null;
+}
+
+/**
+ * Get default log sources from the logging subsystem
+ */
+function getDefaultSources(): LogSource[] {
+  const loggingSubsystem = getLoggingSubsystem();
+  const logPaths = loggingSubsystem.getLogPaths();
+
+  return [
+    { name: 'app', type: 'file', path: logPaths.appLog },
+    { name: 'error', type: 'file', path: logPaths.errorLog },
+  ];
+}
+
+/**
+ * Create a logs plugin
+ */
+export function createLogsPlugin(config: LogsPluginConfig = {}): ControlPanelPlugin {
+  const maxLines = config.retention?.maxLines || 10000;
+
+  // Use provided sources or default to logging subsystem paths
+  const getSources = (): LogSource[] => {
+    if (config.sources && config.sources.length > 0) {
+      return config.sources;
+    }
+    return getDefaultSources();
+  };
+
+  return {
+    name: 'logs',
+    order: 20,
+
+    routes: [
+      {
+        method: 'get',
+        path: '/logs/sources',
+        handler: (_req: Request, res: Response) => {
+          const sources = getSources();
+          res.json({
+            sources: sources.map((s) => ({
+              name: s.name,
+              type: s.type,
+            })),
+          });
+        },
+      },
+      {
+        method: 'get',
+        path: '/logs',
+        handler: (req: Request, res: Response) => {
+          try {
+            const sources = getSources();
+            const sourceName = (req.query.source as string) || sources[0]?.name;
+            const limit = Math.min(parseInt(req.query.limit as string) || 100, maxLines);
+            const offset = parseInt(req.query.offset as string) || 0;
+            const level = req.query.level as string;
+            const search = req.query.search as string;
+            const order = (req.query.order as 'asc' | 'desc') || 'desc';
+
+            const source = sources.find((s) => s.name === sourceName);
+            if (!source) {
+              return res.status(404).json({ error: `Source "${sourceName}" not found` });
+            }
+
+            if (source.type === 'file' && source.path) {
+              const logs = readLogsFromFile(source.path, { limit, offset, level, search, order });
+              return res.json(logs);
+            } else if (source.type === 'api' && source.url) {
+              // Proxy to remote API
+              return res.status(501).json({ error: 'API source not yet implemented' });
+            }
+
+            return res.status(400).json({ error: 'Invalid source configuration' });
+          } catch (error) {
+            return res.status(500).json({
+              error: 'Failed to read logs',
+              message: error instanceof Error ? error.message : String(error),
+            });
+          }
+        },
+      },
+      {
+        method: 'get',
+        path: '/logs/stats',
+        handler: (req: Request, res: Response) => {
+          try {
+            const sources = getSources();
+            const sourceName = (req.query.source as string) || sources[0]?.name;
+            const source = sources.find((s) => s.name === sourceName);
+
+            if (!source) {
+              return res.status(404).json({ error: `Source "${sourceName}" not found` });
+            }
+
+            if (source.type === 'file' && source.path) {
+              const stats = getLogStats(source.path);
+              return res.json(stats);
+            }
+
+            return res.status(400).json({ error: 'Stats only available for file sources' });
+          } catch (error) {
+            return res.status(500).json({
+              error: 'Failed to get log stats',
+              message: error instanceof Error ? error.message : String(error),
+            });
+          }
+        },
+      },
+    ],
+
+    async onInit(context: PluginContext): Promise<void> {
+      const sources = getSources();
+      context.logger.info(`Initialized with ${sources.length} sources`, {
+        sources: sources.map((s) => ({ name: s.name, type: s.type, path: s.path })),
+      });
+    },
+  };
+}
+
+/**
+ * Read logs from a file
+ */
+function readLogsFromFile(
+  filePath: string,
+  options: {
+    limit: number;
+    offset: number;
+    level?: string;
+    search?: string;
+    order: 'asc' | 'desc';
+  }
+): { logs: LogEntry[]; total: number } {
+  const resolvedPath = resolve(filePath);
+
+  if (!existsSync(resolvedPath)) {
+    return { logs: [], total: 0 };
+  }
+
+  const content = readFileSync(resolvedPath, 'utf-8');
+  const lines = content.split('\n').filter((line) => line.trim());
+
+  let entries: LogEntry[] = [];
+  let id = 0;
+
+  for (const line of lines) {
+    // Try to parse as JSON log entry
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.msg || parsed.message) {
+        entries.push({
+          id: id++,
+          level: parsed.level || 'info',
+          timestamp: parsed.timestamp || parsed.time || new Date().toISOString(),
+          namespace: parsed.ns || parsed.name || 'unknown',
+          message: parsed.msg || parsed.message,
+          ...parsed,
+        });
+      }
+    } catch {
+      // Try to parse as simple log format: "LEVEL [namespace] message"
+      const match = line.match(/^(\d{2}:\d{2}:\d{2})\s+\[([^\]]+)\]\s+(.*)$/);
+      if (match) {
+        entries.push({
+          id: id++,
+          level: 'info',
+          timestamp: match[1],
+          namespace: match[2],
+          message: match[3],
+        });
+      }
+    }
+  }
+
+  // Filter by level
+  if (options.level && options.level !== 'all') {
+    entries = entries.filter((e) => e.level === options.level);
+  }
+
+  // Filter by search
+  if (options.search) {
+    const searchLower = options.search.toLowerCase();
+    entries = entries.filter(
+      (e) =>
+        e.message.toLowerCase().includes(searchLower) ||
+        e.namespace.toLowerCase().includes(searchLower)
+    );
+  }
+
+  const total = entries.length;
+
+  // Sort
+  if (options.order === 'desc') {
+    entries.reverse();
+  }
+
+  // Paginate
+  entries = entries.slice(options.offset, options.offset + options.limit);
+
+  return { logs: entries, total };
+}
+
+/**
+ * Get log statistics from a file
+ */
+function getLogStats(filePath: string): LogStats {
+  const resolvedPath = resolve(filePath);
+
+  if (!existsSync(resolvedPath)) {
+    return {
+      totalLogs: 0,
+      byLevel: { debug: 0, info: 0, warn: 0, error: 0 },
+      fileSize: 0,
+      fileSizeFormatted: '0 B',
+      oldestLog: null,
+      newestLog: null,
+    };
+  }
+
+  const stats = statSync(resolvedPath);
+  const content = readFileSync(resolvedPath, 'utf-8');
+  const lines = content.split('\n').filter((line) => line.trim());
+
+  const byLevel = { debug: 0, info: 0, warn: 0, error: 0 };
+  let oldestLog: string | null = null;
+  let newestLog: string | null = null;
+
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      const level = (parsed.level || 'info').toLowerCase();
+      if (level in byLevel) {
+        byLevel[level as keyof typeof byLevel]++;
+      }
+
+      const timestamp = parsed.timestamp || parsed.time;
+      if (timestamp) {
+        if (!oldestLog || timestamp < oldestLog) {
+          oldestLog = timestamp;
+        }
+        if (!newestLog || timestamp > newestLog) {
+          newestLog = timestamp;
+        }
+      }
+    } catch {
+      byLevel.info++; // Count non-JSON lines as info
+    }
+  }
+
+  return {
+    totalLogs: lines.length,
+    byLevel,
+    fileSize: stats.size,
+    fileSizeFormatted: formatBytes(stats.size),
+    oldestLog,
+    newestLog,
+  };
+}
+
+/**
+ * Format bytes to human readable
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}

package/ui/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Control Panel</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/ui/src/App.tsx

@@ -0,0 +1,65 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { QwickApp, ProductLogo, Text } from '@qwickapps/react-framework';
+import { Link, Box } from '@mui/material';
+import { defaultConfig } from './config/AppConfig';
+import { DashboardPage } from './pages/DashboardPage';
+import { HealthPage } from './pages/HealthPage';
+import { LogsPage } from './pages/LogsPage';
+import { ConfigPage } from './pages/ConfigPage';
+import { DiagnosticsPage } from './pages/DiagnosticsPage';
+import { NotFoundPage } from './pages/NotFoundPage';
+
+// Package version - injected at build time or fallback
+const SERVER_VERSION = '1.0.0';
+
+// Default logo - consumers can customize
+const logo = <ProductLogo name="Control Panel" />;
+
+// Default footer content with QwickApps Server branding
+const footerContent = (
+  <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'center', gap: 0.5, py: 2 }}>
+    <Text variant="caption" customColor="var(--theme-text-secondary)">
+      Built with{' '}
+      <Link
+        href="https://qwickapps.com/products/qwickapps-server"
+        target="_blank"
+        rel="noopener noreferrer"
+        sx={{ color: 'primary.main' }}
+      >
+        QwickApps Server
+      </Link>
+      {' '}v{SERVER_VERSION}
+    </Text>
+  </Box>
+);
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <QwickApp
+        config={defaultConfig}
+        logo={logo}
+        footerContent={footerContent}
+        enableScaffolding={true}
+        navigationItems={[
+          { id: 'dashboard', label: 'Dashboard', route: '/', icon: 'dashboard' },
+          { id: 'health', label: 'Health', route: '/health', icon: 'favorite' },
+          { id: 'logs', label: 'Logs', route: '/logs', icon: 'article' },
+          { id: 'config', label: 'Config', route: '/config', icon: 'settings' },
+          { id: 'diagnostics', label: 'Diagnostics', route: '/diagnostics', icon: 'bug_report' },
+        ]}
+        showThemeSwitcher={true}
+        showPaletteSwitcher={true}
+      >
+        <Routes>
+          <Route path="/" element={<DashboardPage />} />
+          <Route path="/health" element={<HealthPage />} />
+          <Route path="/logs" element={<LogsPage />} />
+          <Route path="/config" element={<ConfigPage />} />
+          <Route path="/diagnostics" element={<DiagnosticsPage />} />
+          <Route path="*" element={<NotFoundPage />} />
+        </Routes>
+      </QwickApp>
+    </BrowserRouter>
+  );
+}