@qwickapps/server 1.5.2 → 1.6.1

package/src/plugins/maintenance-plugin.ts

@@ -0,0 +1,409 @@
+/**
+ * Maintenance Plugin
+ *
+ * Provides operational UI for Payload CMS-based applications:
+ * - Seed script management and execution
+ * - Service control (start/stop/restart)
+ * - Environment variable management
+ * - Database backup and restore operations
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { resolve } from 'path';
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../core/plugin-registry.js';
+import { SeedExecutor, validateScriptPath } from './maintenance/seed-executor.js';
+import { getPostgres, hasPostgres } from './postgres-plugin.js';
+
+export interface MaintenancePluginConfig {
+  /** Path to scripts directory (default: './scripts') */
+  scriptsPath?: string;
+
+  /** Path to .env file (default: './.env.local') */
+  envFilePath?: string;
+
+  /** Database connection URL (for backup/restore) */
+  databaseUrl?: string;
+
+  /** Backup storage path (default: './backups') */
+  backupsPath?: string;
+
+  /** Enable seed management (default: true) */
+  enableSeeds?: boolean;
+
+  /** Enable service control (default: true) */
+  enableServiceControl?: boolean;
+
+  /** Enable environment variable management (default: true) */
+  enableEnvManagement?: boolean;
+
+  /** Enable database operations (default: true) */
+  enableDatabaseOps?: boolean;
+}
+
+/**
+ * Create a maintenance plugin
+ */
+export function createMaintenancePlugin(config: MaintenancePluginConfig = {}): Plugin {
+  const scriptsPath = config.scriptsPath || './scripts';
+  const envFilePath = config.envFilePath || './.env.local';
+  const backupsPath = config.backupsPath || './backups';
+
+  return {
+    id: 'maintenance',
+    name: 'Maintenance Plugin',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      const logger = registry.getLogger('maintenance');
+      logger.info('Maintenance plugin starting...');
+
+      // Clean up orphaned executions from previous crashes
+      if (hasPostgres()) {
+        try {
+          const db = getPostgres();
+          const result = await db.queryRaw(
+            `UPDATE seed_executions
+             SET status = 'failed',
+                 error = 'Server interrupted during execution',
+                 completed_at = NOW(),
+                 updated_at = NOW()
+             WHERE status = 'running'`
+          );
+          if (result.rowCount && result.rowCount > 0) {
+            logger.warn(`Cleaned up ${result.rowCount} orphaned seed execution(s)`);
+          }
+        } catch (error) {
+          logger.error('Failed to clean up orphaned executions', { error });
+        }
+      }
+
+      // Register status endpoint
+      registry.addRoute({
+        method: 'get',
+        path: '/status',
+        pluginId: 'maintenance',
+        handler: (_req: Request, res: Response) => {
+          res.json({
+            status: 'ok',
+            features: {
+              seeds: config.enableSeeds !== false,
+              serviceControl: config.enableServiceControl !== false,
+              envManagement: config.enableEnvManagement !== false,
+              databaseOps: config.enableDatabaseOps !== false,
+            },
+            config: {
+              scriptsPath,
+              envFilePath,
+              backupsPath,
+            },
+          });
+        },
+      });
+
+      // Register seed management routes
+      if (config.enableSeeds !== false) {
+        logger.debug('Seed management enabled');
+
+        // Check PostgreSQL dependency for seed history
+        if (!hasPostgres()) {
+          logger.warn('Seed management requires PostgreSQL plugin for execution history');
+        }
+
+        // GET /seeds/discover - List available seed scripts
+        registry.addRoute({
+          method: 'get',
+          path: '/seeds/discover',
+          pluginId: 'maintenance',
+          handler: (_req: Request, res: Response) => {
+            try {
+              const resolvedPath = resolve(scriptsPath);
+              const files = readdirSync(resolvedPath);
+
+              // Filter for seed-*.mjs files
+              const seedFiles = files
+                .filter((file) => /^seed-[a-z0-9-]+\.mjs$/.test(file))
+                .map((file) => {
+                  const filePath = resolve(resolvedPath, file);
+                  const stats = statSync(filePath);
+                  return {
+                    name: file,
+                    path: filePath,
+                    size: stats.size,
+                    createdAt: stats.birthtime,
+                    modifiedAt: stats.mtime,
+                  };
+                })
+                .sort((a, b) => a.name.localeCompare(b.name));
+
+              res.json({ seeds: seedFiles });
+            } catch (error) {
+              logger.error('Failed to discover seed scripts', { error });
+              res.status(500).json({
+                error: 'Failed to discover seed scripts',
+                message: error instanceof Error ? error.message : String(error),
+              });
+            }
+          },
+        });
+
+        // POST /seeds/execute - Execute a seed script
+        registry.addRoute({
+          method: 'post',
+          path: '/seeds/execute',
+          pluginId: 'maintenance',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { name } = req.body;
+
+              if (!name || typeof name !== 'string') {
+                return res.status(400).json({ error: 'Script name is required' });
+              }
+
+              // Validate script path
+              const scriptPath = validateScriptPath(name, scriptsPath);
+              if (!scriptPath) {
+                return res.status(400).json({ error: 'Invalid script name or file not found' });
+              }
+
+              // Check for concurrent execution
+              if (hasPostgres()) {
+                const db = getPostgres();
+                const running = await db.queryOne(
+                  'SELECT id FROM seed_executions WHERE status = $1',
+                  ['running']
+                );
+
+                if (running) {
+                  return res.status(409).json({
+                    error: 'A seed is already running. Please wait for it to complete.',
+                  });
+                }
+              }
+
+              // Set SSE headers
+              res.setHeader('Content-Type', 'text/event-stream');
+              res.setHeader('Cache-Control', 'no-cache');
+              res.setHeader('Connection', 'keep-alive');
+              res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
+              res.setHeader('Content-Encoding', 'identity'); // Disable compression
+              res.flushHeaders();
+
+              // Create execution record in database
+              let executionId: string | null = null;
+              if (hasPostgres()) {
+                const db = getPostgres();
+                const result = await db.queryOne<{ id: string }>(
+                  `INSERT INTO seed_executions (name, status, started_at)
+                   VALUES ($1, $2, NOW())
+                   RETURNING id`,
+                  [name, 'running']
+                );
+                executionId = result?.id || null;
+              }
+
+              // Execute seed script
+              const executor = new SeedExecutor();
+              try {
+                const result = await executor.execute(scriptPath, res);
+
+                // Update execution record
+                if (hasPostgres() && executionId) {
+                  const db = getPostgres();
+                  await db.query(
+                    `UPDATE seed_executions
+                     SET status = $1, completed_at = NOW(), exit_code = $2,
+                         output = $3, error = $4, duration_ms = $5, updated_at = NOW()
+                     WHERE id = $6`,
+                    [
+                      result.exitCode === 0 ? 'completed' : 'failed',
+                      result.exitCode,
+                      result.output,
+                      result.error,
+                      result.duration,
+                      executionId,
+                    ]
+                  );
+                }
+
+                res.end();
+              } catch (error) {
+                logger.error('Seed execution failed', { name, error });
+
+                // Send error event via SSE to notify client
+                res.write(`data: ${JSON.stringify({
+                  type: 'error',
+                  data: error instanceof Error ? error.message : String(error),
+                  timestamp: new Date().toISOString()
+                })}\n\n`);
+
+                // Update execution record as failed
+                if (hasPostgres() && executionId) {
+                  const db = getPostgres();
+                  await db.query(
+                    `UPDATE seed_executions
+                     SET status = $1, completed_at = NOW(), error = $2, updated_at = NOW()
+                     WHERE id = $3`,
+                    ['failed', error instanceof Error ? error.message : String(error), executionId]
+                  );
+                }
+
+                res.end();
+              }
+            } catch (error) {
+              logger.error('Failed to start seed execution', { error });
+              res.status(500).json({
+                error: 'Failed to start seed execution',
+                message: error instanceof Error ? error.message : String(error),
+              });
+            }
+          },
+        });
+
+        // GET /seeds/history - List execution history
+        registry.addRoute({
+          method: 'get',
+          path: '/seeds/history',
+          pluginId: 'maintenance',
+          handler: async (req: Request, res: Response) => {
+            if (!hasPostgres()) {
+              return res.status(503).json({
+                error: 'PostgreSQL plugin required for execution history',
+              });
+            }
+
+            try {
+              const db = getPostgres();
+              const limit = Math.min(parseInt(req.query.limit as string) || 50, 100);
+              const offset = parseInt(req.query.offset as string) || 0;
+              const status = req.query.status as string;
+              const search = req.query.search as string;
+
+              // Build query
+              let whereClause = '';
+              const params: unknown[] = [];
+
+              if (status && ['running', 'completed', 'failed'].includes(status)) {
+                params.push(status);
+                whereClause = `WHERE status = $${params.length}`;
+              }
+
+              if (search) {
+                params.push(`%${search}%`);
+                whereClause += (whereClause ? ' AND' : 'WHERE') + ` name ILIKE $${params.length}`;
+              }
+
+              // Get total count
+              const countResult = await db.queryOne<{ count: string }>(
+                `SELECT COUNT(*) as count FROM seed_executions ${whereClause}`,
+                params
+              );
+              const total = parseInt(countResult?.count || '0', 10);
+
+              // Get executions
+              params.push(limit, offset);
+              const executions = await db.query(
+                `SELECT id, name, status, started_at, completed_at, exit_code, duration_ms,
+                        created_at, updated_at
+                 FROM seed_executions
+                 ${whereClause}
+                 ORDER BY started_at DESC
+                 LIMIT $${params.length - 1} OFFSET $${params.length}`,
+                params
+              );
+
+              res.json({ executions, total, limit, offset });
+            } catch (error) {
+              logger.error('Failed to get execution history', { error });
+              res.status(500).json({
+                error: 'Failed to get execution history',
+                message: error instanceof Error ? error.message : String(error),
+              });
+            }
+          },
+        });
+
+        // GET /seeds/history/:id - Get execution details
+        registry.addRoute({
+          method: 'get',
+          path: '/seeds/history/:id',
+          pluginId: 'maintenance',
+          handler: async (req: Request, res: Response) => {
+            if (!hasPostgres()) {
+              return res.status(503).json({
+                error: 'PostgreSQL plugin required for execution history',
+              });
+            }
+
+            try {
+              const db = getPostgres();
+              const { id } = req.params;
+
+              const execution = await db.queryOne(
+                'SELECT * FROM seed_executions WHERE id = $1',
+                [id]
+              );
+
+              if (!execution) {
+                return res.status(404).json({ error: 'Execution not found' });
+              }
+
+              res.json({ execution });
+            } catch (error) {
+              logger.error('Failed to get execution details', { error });
+              res.status(500).json({
+                error: 'Failed to get execution details',
+                message: error instanceof Error ? error.message : String(error),
+              });
+            }
+          },
+        });
+      }
+
+      // TODO: Register service control routes
+      if (config.enableServiceControl !== false) {
+        logger.debug('Service control enabled');
+        // Routes will be added in #703
+      }
+
+      // TODO: Register environment variable management routes
+      if (config.enableEnvManagement !== false) {
+        logger.debug('Environment variable management enabled');
+        // Routes will be added in #704
+      }
+
+      // TODO: Register database operation routes
+      if (config.enableDatabaseOps !== false) {
+        logger.debug('Database operations enabled');
+        // Routes will be added in #705
+      }
+
+      // Register UI page
+      registry.addPage({
+        id: 'maintenance',
+        route: '/maintenance',
+        component: 'MaintenanceManagementPage',
+        title: 'Maintenance',
+        pluginId: 'maintenance',
+      });
+
+      // Register menu contribution
+      registry.addMenuItem({
+        id: 'maintenance',
+        label: 'Maintenance',
+        route: '/maintenance',
+        icon: 'build',
+        pluginId: 'maintenance',
+        order: 900,
+      });
+
+      logger.info('Maintenance plugin started successfully');
+    },
+
+    async onStop(): Promise<void> {
+      // Cleanup if needed
+    },
+  };
+}

package/src/plugins/notifications/NotificationsManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * NotificationsManagementPage Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { NotificationsManagementPage } from './NotificationsManagementPage';
+
+describe('NotificationsManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<NotificationsManagementPage apiPrefix="/api/notifications" />);
+
+    expect(screen.getByText('Notifications Management')).toBeInTheDocument();
+  });
+
+  it('fetches notifications and stats on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<NotificationsManagementPage apiPrefix="/api/notifications" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+
+  it('renders with custom apiPrefix', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<NotificationsManagementPage apiPrefix="/custom/notifications" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+});

package/src/plugins/notifications/NotificationsManagementPage.tsx

@@ -0,0 +1,128 @@
+/**
+ * Notifications Management Page Component
+ * Full notifications management with filtering and status tracking
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, StatCard, type Column } from '@qwickapps/react-framework';
+
+export interface NotificationsManagementPageProps {
+  apiPrefix?: string;
+}
+
+interface Notification {
+  id: string;
+  user_id: string;
+  type: string;
+  title: string;
+  message: string;
+  status: 'pending' | 'sent' | 'failed';
+  created_at: string;
+  sent_at?: string;
+}
+
+interface NotificationsStats {
+  totalNotifications: number;
+  pendingNotifications: number;
+  sentToday: number;
+  failedToday: number;
+}
+
+export const NotificationsManagementPage: React.FC<NotificationsManagementPageProps> = ({
+  apiPrefix = '/api/notifications',
+}) => {
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+  const [stats, setStats] = useState<NotificationsStats | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [statusFilter, setStatusFilter] = useState<string>('');
+
+  const fetchNotifications = async () => {
+    try {
+      const response = await fetch(`${apiPrefix}/list`);
+      if (!response.ok) throw new Error('Failed to fetch notifications');
+      const data = await response.json();
+      setNotifications(data);
+    } catch (error) {
+      console.error('Error fetching notifications:', error);
+    }
+  };
+
+  const fetchStats = async () => {
+    try {
+      const response = await fetch(`${apiPrefix}/stats`);
+      if (!response.ok) throw new Error('Failed to fetch stats');
+      const data = await response.json();
+      setStats(data);
+    } catch (error) {
+      console.error('Error fetching stats:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchNotifications();
+    fetchStats();
+  }, [apiPrefix]);
+
+  const columns: Column<Notification>[] = [
+    { key: 'title', label: 'Title' },
+    { key: 'type', label: 'Type' },
+    { key: 'status', label: 'Status' },
+    { key: 'created_at', label: 'Created' },
+  ];
+
+  const filteredNotifications = statusFilter
+    ? notifications.filter((n) => n.status === statusFilter)
+    : notifications;
+
+  return (
+    <PluginManagementPage title="Notifications Management">
+      <div className="grid grid-cols-1 md:grid-cols-4 gap-4 mb-6">
+        <StatCard
+            label="Total Notifications"
+          value={stats?.totalNotifications ?? 0}
+        />
+        <StatCard
+            label="Pending"
+          value={stats?.pendingNotifications ?? 0}
+          status="warning"
+        />
+        <StatCard
+            label="Sent Today"
+          value={stats?.sentToday ?? 0}
+          status="healthy"
+        />
+        <StatCard
+            label="Failed Today"
+          value={stats?.failedToday ?? 0}
+          status="error"
+        />
+      </div>
+
+      <div className="mb-4">
+        <select
+          value={statusFilter}
+          onChange={(e) => setStatusFilter(e.target.value)}
+          className="px-4 py-2 border rounded"
+        >
+          <option value="">All Statuses</option>
+          <option value="pending">Pending</option>
+          <option value="sent">Sent</option>
+          <option value="failed">Failed</option>
+        </select>
+      </div>
+
+      <DataTable
+        columns={columns}
+        data={filteredNotifications}
+        loading={loading}
+      />
+    </PluginManagementPage>
+  );
+};
+
+export default NotificationsManagementPage;

package/src/plugins/notifications/NotificationsStatusWidget.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * NotificationsStatusWidget Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { NotificationsStatusWidget } from './NotificationsStatusWidget';
+
+describe('NotificationsStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<NotificationsStatusWidget apiPrefix="/api/notifications" />);
+
+    expect(screen.getByText(/Notifications Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalNotifications: 1000,
+      pendingNotifications: 50,
+      sentToday: 200,
+      failedToday: 5,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<NotificationsStatusWidget apiPrefix="/api/notifications" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Notifications')).toBeInTheDocument();
+      expect(screen.getByText(/Total: 1000/)).toBeInTheDocument();
+      expect(screen.getByText(/Pending: 50/)).toBeInTheDocument();
+      expect(screen.getByText(/Sent Today: 200/)).toBeInTheDocument();
+      expect(screen.getByText(/Failed Today: 5/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/notifications/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Notifications service error')
+    );
+
+    render(<NotificationsStatusWidget apiPrefix="/api/notifications" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Notifications service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalNotifications: 500,
+      pendingNotifications: 25,
+      sentToday: 100,
+      failedToday: 2,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<NotificationsStatusWidget apiPrefix="/custom/notifications" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/notifications/stats');
+    });
+  });
+
+  it('displays all notification metrics correctly', async () => {
+    const mockStats = {
+      totalNotifications: 2000,
+      pendingNotifications: 100,
+      sentToday: 500,
+      failedToday: 10,
+      health: 'warning' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<NotificationsStatusWidget apiPrefix="/api/notifications" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total: 2000/)).toBeInTheDocument();
+      expect(screen.getByText(/Pending: 100/)).toBeInTheDocument();
+      expect(screen.getByText(/Sent Today: 500/)).toBeInTheDocument();
+      expect(screen.getByText(/Failed Today: 10/)).toBeInTheDocument();
+    });
+  });
+});