@qwickapps/server 1.6.0 → 1.7.0

package/src/plugins/cms/cms-plugin.ts

@@ -0,0 +1,259 @@
+/**
+ * CMS Plugin
+ *
+ * Manages Payload CMS service integration, monitoring, and control.
+ * Provides dashboard widgets, restart capabilities, and seed management.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type { Express } from 'express';
+
+export interface CMSPluginConfig {
+  /** Payload CMS service URL (e.g., http://localhost:3301) */
+  serviceUrl: string;
+  /** Path to seed scripts directory */
+  seedsPath?: string;
+  /** Whether to show dashboard widget (default: true) */
+  showDashboardWidget?: boolean;
+  /** Whether to show maintenance widget (default: true) */
+  showMaintenanceWidget?: boolean;
+}
+
+/**
+ * Create a CMS plugin for Payload CMS service management
+ */
+export function createCMSPlugin(config: CMSPluginConfig): Plugin {
+  return {
+    id: 'cms',
+    name: 'CMS Plugin',
+    version: '1.0.0',
+
+    async onStart(pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      const logger = registry.getLogger('cms');
+      const app = registry.getApp() as Express;
+
+      logger.info('CMS Plugin starting...');
+      logger.debug(`Service URL: ${config.serviceUrl}`);
+
+      // Register health check for Payload CMS service
+      registry.registerHealthCheck({
+        name: 'payload-cms-service',
+        type: 'http',
+        url: `${config.serviceUrl}/api/health`,
+      });
+
+      // Register dashboard widget for CMS status
+      if (config.showDashboardWidget !== false) {
+        registry.addWidget({
+          id: 'cms-status',
+          title: 'Payload CMS',
+          component: 'CMSStatusWidget',
+          priority: 15, // After ServiceHealthWidget (10)
+          showByDefault: true,
+          pluginId: 'cms',
+        });
+      }
+
+      // Register maintenance widget for CMS operations
+      if (config.showMaintenanceWidget !== false) {
+        registry.addWidget({
+          id: 'cms-maintenance',
+          title: 'CMS Service Control',
+          component: 'CMSMaintenanceWidget',
+          priority: 10,
+          showByDefault: false, // Only shown on maintenance page
+          pluginId: 'cms',
+        });
+      }
+
+      // API Routes
+      /**
+       * GET /api/cms/status
+       * Get Payload CMS service status
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/status',
+        pluginId: 'cms',
+        handler: async (_req, res) => {
+          try {
+            const response = await fetch(`${config.serviceUrl}/api/health`, {
+              method: 'GET',
+              signal: AbortSignal.timeout(5000),
+            });
+
+            const health = await response.json();
+
+            res.json({
+              status: response.ok ? 'running' : 'unhealthy',
+              url: config.serviceUrl,
+              health,
+              timestamp: new Date().toISOString(),
+            });
+          } catch (error) {
+            logger.error('Failed to check CMS status:', error as Record<string, unknown>);
+            res.status(503).json({
+              status: 'down',
+              url: config.serviceUrl,
+              error: error instanceof Error ? error.message : 'Unknown error',
+              timestamp: new Date().toISOString(),
+            });
+          }
+        },
+      });
+
+      /**
+       * POST /api/cms/restart
+       * Restart Payload CMS service
+       *
+       * Note: This is a placeholder. Actual restart would require process management
+       * (PM2, systemd, Docker, etc.) and appropriate permissions.
+       */
+      registry.addRoute({
+        method: 'post',
+        path: '/restart',
+        pluginId: 'cms',
+        handler: async (_req, res) => {
+          logger.warn('CMS restart requested - not implemented');
+          res.status(501).json({
+            error: 'Not implemented',
+            message: 'CMS restart requires process manager integration (PM2, systemd, Docker, etc.)',
+            suggestion: 'Use your process manager to restart the Payload service',
+          });
+        },
+      });
+
+      /**
+       * GET /api/cms/seeds
+       * List available seed scripts
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/seeds',
+        pluginId: 'cms',
+        handler: async (_req, res) => {
+        try {
+          if (!config.seedsPath) {
+            return res.json({ seeds: [] });
+          }
+
+          const fs = await import('fs/promises');
+          const path = await import('path');
+
+          const files = await fs.readdir(config.seedsPath);
+          const seedFiles = files.filter(f =>
+            f.startsWith('seed-') && (f.endsWith('.mjs') || f.endsWith('.js'))
+          );
+
+          const seeds = seedFiles.map(file => ({
+            name: file.replace(/^seed-/, '').replace(/\.(m)?js$/, ''),
+            file,
+            path: path.join(config.seedsPath!, file),
+          }));
+
+          res.json({ seeds });
+        } catch (error) {
+          logger.error('Failed to list seeds:', error as Record<string, unknown>);
+          res.status(500).json({
+            error: 'Failed to list seeds',
+            message: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+        },
+      });
+
+      /**
+       * POST /api/cms/seeds/:seedName/execute
+       * Execute a seed script
+       */
+      registry.addRoute({
+        method: 'post',
+        path: '/seeds/:seedName/execute',
+        pluginId: 'cms',
+        handler: async (req, res) => {
+          const { seedName } = req.params;
+
+        logger.info(`Executing seed: ${seedName}`);
+
+        try {
+          if (!config.seedsPath) {
+            return res.status(400).json({
+              error: 'Seeds not configured',
+              message: 'seedsPath not provided in plugin configuration',
+            });
+          }
+
+          const path = await import('path');
+          const { spawn } = await import('child_process');
+
+          // Find the seed file
+          const seedFile = `seed-${seedName}.mjs`;
+          const seedPath = path.join(config.seedsPath, seedFile);
+
+          // Execute seed script
+          const child = spawn('node', [seedPath], {
+            cwd: process.cwd(),
+            env: process.env,
+          });
+
+          let stdout = '';
+          let stderr = '';
+
+          child.stdout.on('data', (data) => {
+            stdout += data.toString();
+          });
+
+          child.stderr.on('data', (data) => {
+            stderr += data.toString();
+          });
+
+          child.on('close', (code) => {
+            if (code === 0) {
+              logger.info(`Seed ${seedName} completed successfully`);
+              res.json({
+                success: true,
+                seedName,
+                output: stdout,
+                executedAt: new Date().toISOString(),
+              });
+            } else {
+              logger.error(`Seed ${seedName} failed with code ${code}`);
+              res.status(500).json({
+                success: false,
+                seedName,
+                error: `Seed script exited with code ${code}`,
+                output: stdout,
+                errorOutput: stderr,
+              });
+            }
+          });
+
+          child.on('error', (error) => {
+            logger.error(`Failed to execute seed ${seedName}:`, { error: error.message });
+            res.status(500).json({
+              success: false,
+              seedName,
+              error: error.message,
+            });
+          });
+        } catch (error) {
+          logger.error(`Failed to execute seed ${seedName}:`, error as Record<string, unknown>);
+          res.status(500).json({
+            success: false,
+            seedName,
+            error: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+        },
+      });
+
+      logger.info('CMS Plugin started successfully');
+    },
+
+    async onStop(): Promise<void> {
+      // Nothing to cleanup
+    },
+  };
+}

package/src/plugins/cms/index.ts

@@ -0,0 +1,8 @@
+/**
+ * CMS Plugin Exports
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { createCMSPlugin } from './cms-plugin.js';
+export type { CMSPluginConfig } from './cms-plugin.js';

package/src/plugins/config-plugin.ts

@@ -30,10 +30,10 @@ export function createConfigPlugin(config: ConfigPluginConfig): Plugin {
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       const logger = registry.getLogger('config');
 
-      // Register /config route
+      // Register root route (framework adds /config prefix automatically)
       registry.addRoute({
         method: 'get',
-        path: '/config',
+        path: '/',
         pluginId: 'config',
         handler: (_req: Request, res: Response) => {
           const envVars: Record<string, string> = {};
@@ -60,10 +60,10 @@ export function createConfigPlugin(config: ConfigPluginConfig): Plugin {
         },
       });
 
-      // Register /config/validate route
+      // Register /validate route (framework adds /config prefix automatically)
       registry.addRoute({
         method: 'get',
-        path: '/config/validate',
+        path: '/validate',
         pluginId: 'config',
         handler: (_req: Request, res: Response) => {
           const results: ConfigValidationResult[] = [];

package/src/plugins/core/index.ts

@@ -0,0 +1,164 @@
+/**
+ * Core Plugin - System Routes
+ *
+ * Registers core control panel routes (/info, /health, /ui-contributions, etc.)
+ * as a system plugin so they appear in the API client manifest.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type { HealthManager } from '../../core/health-manager.js';
+
+interface CorePluginDependencies {
+  config: {
+    productName: string;
+    logoName?: string;
+    logoIconUrl?: string;
+    version?: string;
+    links?: Array<{
+      label: string;
+      url: string;
+      icon?: string;
+      external?: boolean;
+      requiresHealth?: string;
+    }>;
+    branding?: Record<string, unknown>;
+  };
+  startTime: number;
+  healthManager: HealthManager;
+  getDiagnostics: () => unknown;
+}
+
+export function createCorePlugin(deps: CorePluginDependencies): Plugin {
+  const { config, startTime, healthManager, getDiagnostics } = deps;
+
+  return {
+    id: 'core',
+    name: 'Core',
+    version: '1.0.0',
+    type: 'system', // System plugin - no slug prefix
+
+    async onStart(_config: PluginConfig, registry: PluginRegistry): Promise<void> {
+      /**
+       * GET /api/health - Aggregated health status
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/health',
+        handler: (_req: Request, res: Response) => {
+          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
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/info',
+        handler: (_req: Request, res: Response) => {
+          res.json({
+            product: config.productName,
+            logoName: config.logoName || config.productName,
+            logoIconUrl: config.logoIconUrl,
+            version: config.version || 'unknown',
+            uptime: Date.now() - startTime,
+            links: config.links || [],
+            branding: config.branding || {},
+          });
+        },
+      });
+
+      /**
+       * GET /api/diagnostics - Full diagnostics for AI agents
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/diagnostics',
+        handler: (_req: Request, res: Response) => {
+          const report = getDiagnostics();
+          res.json(report);
+        },
+      });
+
+      /**
+       * GET /api/ui-contributions - UI contributions from all plugins
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/ui-contributions',
+        handler: (_req: Request, res: Response) => {
+          res.json({
+            menuItems: registry.getMenuItems(),
+            pages: registry.getPages(),
+            widgets: registry.getWidgets(),
+            plugins: registry.listPlugins(),
+          });
+        },
+      });
+
+      /**
+       * GET /api/plugins - List all registered plugins
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/plugins',
+        handler: (_req: Request, res: Response) => {
+          const plugins = registry.listPlugins().map((plugin) => {
+            const contributions = registry.getPluginContributions(plugin.id);
+            return {
+              ...plugin,
+              contributionCounts: {
+                routes: contributions.routes.length,
+                menuItems: contributions.menuItems.length,
+                pages: contributions.pages.length,
+                widgets: contributions.widgets.length,
+                hasConfig: !!contributions.config,
+              },
+            };
+          });
+          res.json({ plugins });
+        },
+      });
+
+      /**
+       * GET /api/plugins/:id - Get detailed plugin info
+       */
+      registry.addRoute({
+        method: 'get',
+        path: '/plugins/:id',
+        handler: (req: Request, res: Response) => {
+          const { id } = req.params;
+          const plugins = registry.listPlugins();
+          const plugin = plugins.find((p) => p.id === id);
+
+          if (!plugin) {
+            res.status(404).json({ error: `Plugin not found: ${id}` });
+            return;
+          }
+
+          const contributions = registry.getPluginContributions(id);
+          res.json({
+            ...plugin,
+            contributions,
+          });
+        },
+      });
+    },
+
+    async onStop(): Promise<void> {
+      // No cleanup needed
+    },
+  };
+}

package/src/plugins/devices/API_ROUTES.md

@@ -0,0 +1,27 @@
+# Devices Plugin API Routes
+
+## Routes
+
+### GET /api/devices/stats
+Returns device statistics for the status widget.
+
+**Response:** `{ totalDevices, activeDevices, registeredToday, pendingApproval, health }`
+
+### GET /api/devices
+Returns paginated list of devices with optional filtering by status.
+
+**Query:** `limit, offset, status`
+
+**Response:** `{ devices: Array<{ id, userId, userEmail, deviceName, deviceType, platform, status, registeredAt, lastActiveAt }>, total }`
+
+### POST /api/devices
+Register a new device.
+
+### PATCH /api/devices/:id
+Update device (approve, deactivate).
+
+### DELETE /api/devices/:id
+Remove a device.
+
+---
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/devices/DevicesManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * DevicesManagementPage 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 { DevicesManagementPage } from './DevicesManagementPage';
+
+describe('DevicesManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<DevicesManagementPage apiPrefix="/api/devices" />);
+
+    expect(screen.getByText('Device Management')).toBeInTheDocument();
+  });
+
+  it('fetches devices on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<DevicesManagementPage apiPrefix="/api/devices" />);
+
+    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(<DevicesManagementPage apiPrefix="/custom/devices" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+});

package/src/plugins/devices/DevicesManagementPage.tsx

@@ -0,0 +1,124 @@
+/**
+ * DevicesManagementPage - Full management interface for devices
+ */
+
+import React, { useState, useEffect } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, Column } from '@qwickapps/react-framework';
+
+export interface DevicesManagementPageProps {
+  /** API endpoint prefix (default: '/api/devices') */
+  apiPrefix?: string;
+}
+
+interface Device {
+  id: string;
+  userId: string;
+  userEmail: string;
+  deviceName: string;
+  deviceType: 'mobile' | 'tablet' | 'desktop' | 'tv' | 'other';
+  platform: string;
+  status: 'active' | 'inactive' | 'pending';
+  registeredAt: string;
+  lastActiveAt?: string;
+}
+
+export function DevicesManagementPage({ apiPrefix = '/api/devices' }: DevicesManagementPageProps) {
+  const [activeTab, setActiveTab] = useState<'all' | 'active' | 'pending' | 'config'>('all');
+  const [devices, setDevices] = useState<Device[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const status = activeTab === 'all' ? undefined : activeTab;
+    const url = status ? `${apiPrefix}?status=${status}` : `${apiPrefix}`;
+
+    fetch(url)
+      .then((res) => res.json())
+      .then((data) => {
+        setDevices(data.devices || []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, [activeTab, apiPrefix]);
+
+  const columns: Column<Device>[] = [
+    { key: 'deviceName', label: 'Device Name', sortable: true },
+    { key: 'userEmail', label: 'User', sortable: true },
+    {
+      key: 'deviceType',
+      label: 'Type',
+      sortable: true,
+      render: (val) => (
+        <span className="px-2 py-1 rounded text-xs font-medium bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-100">
+          {String(val).toUpperCase()}
+        </span>
+      ),
+    },
+    { key: 'platform', label: 'Platform', sortable: true },
+    {
+      key: 'status',
+      label: 'Status',
+      sortable: true,
+      render: (val) => (
+        <span
+          className={`px-2 py-1 rounded text-xs font-medium ${
+            val === 'active'
+              ? 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-100'
+              : val === 'pending'
+              ? 'bg-yellow-100 dark:bg-yellow-900 text-yellow-800 dark:text-yellow-100'
+              : 'bg-gray-100 dark:bg-gray-700 text-gray-800 dark:text-gray-300'
+          }`}
+        >
+          {String(val)}
+        </span>
+      ),
+    },
+    { key: 'registeredAt', label: 'Registered', sortable: true },
+    { key: 'lastActiveAt', label: 'Last Active', sortable: true },
+  ];
+
+  const tabs = [
+    { id: 'all', label: 'All Devices' },
+    { id: 'active', label: 'Active' },
+    { id: 'pending', label: 'Pending' },
+    { id: 'config', label: 'Configuration' },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="Devices Management"
+      tabs={tabs}
+      activeTab={activeTab}
+      onTabChange={(tab) => setActiveTab(tab as typeof activeTab)}
+    >
+      {activeTab === 'config' ? (
+        <div className="space-y-4">
+          <div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+            <p className="text-sm text-blue-900 dark:text-blue-100">
+              Device registration policies and approval settings.
+            </p>
+          </div>
+        </div>
+      ) : (
+        <DataTable
+          columns={columns}
+          data={devices}
+          loading={loading}
+          emptyMessage="No devices found"
+          bulkActions={[
+            {
+              label: 'Approve Selected',
+              onClick: (rows) => console.log('Approve devices:', rows),
+              variant: 'primary',
+            },
+            {
+              label: 'Deactivate Selected',
+              onClick: (rows) => console.log('Deactivate devices:', rows),
+              variant: 'danger',
+            },
+          ]}
+        />
+      )}
+    </PluginManagementPage>
+  );
+}