@qwickapps/server 1.8.1 → 1.9.0

package/dist-ui-lib/src/api/clientBuilder.d.ts

@@ -18,15 +18,15 @@ export interface RouteManifestEntry {
 /**
  * Build typed API client from server manifest
  *
- * Fetches the manifest from /api/client-manifest and generates a nested
+ * Fetches the manifest from /client-manifest (baseUrl already includes /qapi) and generates a nested
  * client object with methods for each route.
  *
- * @param baseUrl - Base URL of the server (e.g., 'http://localhost:3000')
+ * @param baseUrl - Base URL for QwickApps Server APIs (e.g., '/qapi' or 'http://localhost:3000/qapi')
  * @returns Promise resolving to the generated client
  *
  * @example
  * ```typescript
- * const client = await buildClientFromManifest<APIClient>('http://localhost:3000');
+ * const client = await buildClientFromManifest<APIClient>('/qapi');
  * const logs = await client.logs.query({ limit: 10 });
  * ```
  */

package/dist-ui-lib/src/dashboard/widgets/MigrationManagementWidget.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Migration Management Widget
+ *
+ * Allows executing Payload CMS database migrations from the control panel.
+ * Part of the maintenance plugin.
+ */
+export declare function MigrationManagementWidget(): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/src/dashboard/widgets/index.d.ts

@@ -10,6 +10,7 @@ export { NotificationsStatsWidget } from './NotificationsStatsWidget';
 export { CMSStatusWidget } from './CMSStatusWidget';
 export { CMSMaintenanceWidget } from './CMSMaintenanceWidget';
 export { SeedManagementWidget } from './SeedManagementWidget';
+export { MigrationManagementWidget } from './MigrationManagementWidget';
 export { ServiceControlWidget } from './ServiceControlWidget';
 export { EnvironmentConfigWidget } from './EnvironmentConfigWidget';
 export { DatabaseOpsWidget } from './DatabaseOpsWidget';

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@qwickapps/server",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Plugin-based application server framework for building websites, APIs, admin dashboards, and full-stack products",
+  "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "exports": {
@@ -59,6 +60,8 @@
     "express": "^4.18.2",
     "helmet": "^7.1.0",
     "http-proxy-middleware": "^3.0.3",
+    "prop-types": "^15.8.1",
+    "react-is": "^18.2.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {
@@ -90,7 +93,7 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-router-dom": "^6.30.1",
-    "supertokens-node": "^20.1.7",
+    "supertokens-node": "^18.0.0",
     "tsx": "^4.20.6",
     "typescript": "^5.3.3",
     "vite": "^6.0.0",

package/src/core/control-panel.ts

@@ -200,10 +200,11 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
     next();
   });
 
-  // CRITICAL: System APIs always mount at /api regardless of mountPath
-  // This ensures consistent API paths across all products
-  // See: ADR-012-QwickApps-Server-Routing-Architecture
-  app.use('/api', router);
+  // CRITICAL: QwickApps Server APIs always mount at /qapi regardless of mountPath
+  // This avoids conflicts with application-level APIs (e.g., Payload CMS uses /api)
+  // /qapi = QwickApps framework APIs (SuperTokens, health, postgres, cache, etc.)
+  // /api = Application/CMS APIs (Payload, custom app routes)
+  app.use('/qapi', router);
 
   // Built-in routes
 
@@ -238,7 +239,7 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
 
       manifest[key] = {
         method: route.method.toUpperCase(),
-        path: `/api${route.path}`,
+        path: route.path,
         auth: route.auth?.required || false,
       };
     }
@@ -284,8 +285,10 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
         const effectivePath = forwardedPrefix || mountPath;
         const normalizedPath = effectivePath === '/' ? '' : effectivePath;
 
-        // Inject base path as global variable before other scripts
-        const basePathScript = `<script>window.__APP_BASE_PATH__="${normalizedPath}";</script>`;
+        // Inject base paths as global variables before other scripts
+        // __APP_BASE_PATH__: UI mount path for routing (e.g., '/cpanel')
+        // __API_BASE_PATH__: Base URL for QwickApps Server APIs (always '/qapi')
+        const basePathScript = `<script>window.__APP_BASE_PATH__="${normalizedPath}";window.__API_BASE_PATH__="/qapi";</script>`;
         let html = indexHtmlTemplate.replace('<head>', `<head>\n    ${basePathScript}`);
 
         // Rewrite asset paths if mounted at a subpath

package/src/core/gateway.ts

@@ -1311,54 +1311,37 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
         );
       }
 
-      // 2. Setup control panel proxies (BEFORE server.listen)
-      // Control panel runs at / internally with APIs at /api and UI at /
-      // We proxy both /api and /cpanel to the control panel
-
-      // Proxy control panel APIs at {cpPath}/api
-      // IMPORTANT: Express strips the API path prefix before passing to middleware,
-      // so we need pathRewrite to reconstruct the full path for the control panel
-      const cpApiPath = `${cpPath}/api`;
-      const apiProxy = createProxyMiddleware({
+      // 2. Create HTTP server (but don't listen yet - need server object for WS)
+      server = createServer(app);
+
+      // 3. Setup mounted apps WITH QwickApps Server API proxy injected at the right position
+      // QwickApps Server APIs (/qapi/*) need to be registered BEFORE root path proxy
+      // to prevent being caught by frontend catch-all routing
+      const qwickAppsApiProxy = createProxyMiddleware({
         target: `http://localhost:${cpPort}`,
         changeOrigin: true,
-        pathRewrite: (path) => `/api${path}`, // Express removed {cpPath}/api, add back just /api (control panel APIs are at /api/*)
         on: {
           proxyReq: (proxyReq, req) => {
-            // Set X-Forwarded-Prefix so control panel knows its public mount path
-            proxyReq.setHeader('X-Forwarded-Prefix', cpPath);
-            logger.debug(`[API Proxy] Forwarding ${req.method} ${req.url} to control panel`);
+            logger.debug(`[QwickApps API] Forwarding ${req.method} ${req.url} to QwickApps Server`);
           },
           proxyRes: (proxyRes, req) => {
-            logger.debug(`[API Proxy] Response for ${req.url}: ${proxyRes.statusCode} ${proxyRes.headers['content-type']}`);
+            logger.debug(`[QwickApps API] Response for ${req.url}: ${proxyRes.statusCode}`);
           },
           error: (err: Error, req: IncomingMessage, res: ServerResponse | Socket) => {
-            logger.error(`[API Proxy] Error for ${req.url}`, { error: err.message });
+            logger.error(`[QwickApps API] Error for ${req.url}`, { error: err.message });
             if (res && 'writeHead' in res && !res.headersSent) {
               res.writeHead(503, { 'Content-Type': 'application/json' });
               res.end(JSON.stringify({
                 error: 'Service Unavailable',
-                message: 'The control panel API is currently unavailable.',
+                message: 'QwickApps Server APIs are currently unavailable.',
                 details: nodeEnv === 'development' ? err.message : undefined,
               }));
             }
           },
         },
       });
-      app.use(cpApiPath, apiProxy);
-      logger.debug(`Setting up proxy: ${cpApiPath} -> http://localhost:${cpPort}/api`);
-      mountedApps.push({ path: cpApiPath, type: 'proxy', target: `http://localhost:${cpPort}` });
-    }
-
-    // 3. Create HTTP server (but don't listen yet - need server object for WS)
-    server = createServer(app);
 
-    // 4. Setup control panel UI proxy (needs server for WebSocket handling)
-    if (cpEnabled) {
-      const cpPort = parseInt(process.env.CPANEL_PORT || String(gatewayPort + 1), 10);
-
-      // Proxy /cpanel to control panel UI
-      // Express strips cpPath prefix, so we need custom proxy to add it back
+      // Create control panel UI proxy (will be registered before root proxy)
       const cpUiProxy = createProxyMiddleware({
         target: `http://localhost:${cpPort}`,
         changeOrigin: true,
@@ -1378,23 +1361,46 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
           },
         },
       });
-      app.use(cpPath, cpUiProxy);
 
-      // WebSocket upgrade handling for control panel
-      server!.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
-        if (req.url?.startsWith(cpPath)) {
-          cpUiProxy.upgrade?.(req, socket as Socket, head);
+      const apps = config.apps || [];
+      for (const appConfig of apps) {
+        // IMPORTANT: Insert QwickApps Server and Control Panel proxies BEFORE root path proxy
+        // This ensures /qapi/* and /cpanel requests don't get caught by frontend catch-all routing
+        if (appConfig.path === '/') {
+          // 1. Register QwickApps Server API proxy at /qapi/* BEFORE the root proxy
+          //    These are framework APIs: SuperTokens auth, health checks, postgres, cache, etc.
+          //    Payload CMS uses natural Next.js /api/* path
+          app.use((req, res, next) => {
+            if (req.path.startsWith('/qapi/')) {
+              return qwickAppsApiProxy(req, res, next);
+            }
+            next();
+          });
+          logger.debug(`Setting up proxy: /qapi/* -> http://localhost:${cpPort} (QwickApps Server APIs)`);
+          mountedApps.push({ path: '/qapi', type: 'proxy', target: `http://localhost:${cpPort}` });
+
+          // 2. Register Control Panel UI proxy BEFORE the root proxy
+          app.use(cpPath, cpUiProxy);
+          mountedApps.push({ path: cpPath, type: 'proxy', target: `http://localhost:${cpPort}` });
+
+          // 3. Setup WebSocket upgrade handling for control panel UI
+          server!.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+            if (req.url?.startsWith(cpPath)) {
+              cpUiProxy.upgrade?.(req, socket as Socket, head);
+            }
+          });
         }
-      });
 
-      mountedApps.push({ path: cpPath, type: 'proxy', target: `http://localhost:${cpPort}` });
+        // Now register the app itself
+        if (appConfig.source.type === 'proxy') {
+          setupProxyApp(appConfig, server);
+        } else {
+          setupStaticApp(appConfig);
+        }
+      }
     }
 
-    // 5. Setup mounted apps (proxy and static)
-    const apps = config.apps || [];
-
-    // If plugins need maintenance, add root-level maintenance page
-    // but keep /cpanel and /diagnostics accessible
+    // 6. Add maintenance page if needed (after all proxies are set up)
     if (cpEnabled) {
       const pluginsNeedingMaintenance = controlPanelInstance!.getPluginRegistry().getPluginsNeedingMaintenance();
       if (pluginsNeedingMaintenance.length > 0) {
@@ -1429,16 +1435,7 @@ export function createGateway(config: GatewayConfig): GatewayInstance {
       }
     }
 
-    // Setup additional apps
-    for (const appConfig of apps) {
-      if (appConfig.source.type === 'proxy') {
-        setupProxyApp(appConfig, server);
-      } else {
-        setupStaticApp(appConfig);
-      }
-    }
-
-    // 6. Setup frontend app at root
+    // 7. Setup frontend app at root
     setupFrontendApp();
 
     // 7. Start listening (LAST STEP - after all middleware is registered)

package/src/plugins/api-keys/ApiKeysManagementPage.tsx

@@ -24,7 +24,7 @@ interface ApiKey {
   usageCount: number;
 }
 
-export function ApiKeysManagementPage({ apiPrefix = '/api/api-keys' }: ApiKeysManagementPageProps) {
+export function ApiKeysManagementPage({ apiPrefix = '/qapi/api-keys' }: ApiKeysManagementPageProps) {
   const [activeTab, setActiveTab] = useState<'all' | 'active' | 'expired' | 'config'>('all');
   const [keys, setKeys] = useState<ApiKey[]>([]);
   const [loading, setLoading] = useState(true);

package/src/plugins/api-keys/ApiKeysStatusWidget.tsx

@@ -10,7 +10,7 @@ export interface ApiKeysStatusWidgetProps {
   apiPrefix?: string;
 }
 
-export function ApiKeysStatusWidget({ apiPrefix = '/api/api-keys' }: ApiKeysStatusWidgetProps) {
+export function ApiKeysStatusWidget({ apiPrefix = '/qapi/api-keys' }: ApiKeysStatusWidgetProps) {
   const [stats, setStats] = useState<{
     totalKeys: number;
     activeKeys: number;

package/src/plugins/auth/AuthManagementPage.tsx

@@ -30,7 +30,7 @@ interface AuthSession {
   ipAddress?: string;
 }
 
-export function AuthManagementPage({ apiPrefix = '/api/auth' }: AuthManagementPageProps) {
+export function AuthManagementPage({ apiPrefix = '/qapi/auth' }: AuthManagementPageProps) {
   const [activeTab, setActiveTab] = useState<'overview' | 'providers' | 'sessions' | 'config'>('overview');
   const [providers, setProviders] = useState<AuthProvider[]>([]);
   const [sessions, setSessions] = useState<AuthSession[]>([]);

package/src/plugins/auth/AuthStatusWidget.tsx

@@ -10,7 +10,7 @@ export interface AuthStatusWidgetProps {
   apiPrefix?: string;
 }
 
-export function AuthStatusWidget({ apiPrefix = '/api/auth' }: AuthStatusWidgetProps) {
+export function AuthStatusWidget({ apiPrefix = '/qapi/auth' }: AuthStatusWidgetProps) {
   const [stats, setStats] = useState<{
     totalProviders: number;
     activeProviders: number;

package/src/plugins/auth/adapters/supertokens-adapter.ts

@@ -47,14 +47,12 @@ export function supertokensAdapter(config: SupertokensAdapterConfig): AuthAdapte
         // Store response on request for later use in getUser()
         (req as SupertokensExtendedRequest)[REQUEST_RES_KEY] = res;
 
-        // Skip if already initialized with error
+        // Skip if already initialized with error — let auth-checking middleware
+        // decide whether to block the request based on authRequired config.
+        // Returning 500 here blocks ALL routes (including /auth/config/status)
+        // even when authRequired is false.
         if (initializationError) {
-          return res.status(500).json({
-            error: 'Auth Configuration Error',
-            message:
-              'Supertokens is not properly configured. Install supertokens-node package: npm install supertokens-node',
-            details: initializationError.message,
-          });
+          return next();
         }
 
         // Lazy initialize Supertokens
@@ -163,12 +161,10 @@ export function supertokensAdapter(config: SupertokensAdapterConfig): AuthAdapte
             initializationError =
               error instanceof Error ? error : new Error('Failed to initialize Supertokens');
             console.error('[SupertokensAdapter] Initialization error:', error);
-            return res.status(500).json({
-              error: 'Auth Configuration Error',
-              message:
-                'Supertokens is not properly configured. Install supertokens-node package: npm install supertokens-node',
-              details: initializationError.message,
-            });
+            // Let the auth-checking middleware decide whether to block this request.
+            // Non-auth routes (e.g. /auth/config/status) must remain accessible
+            // so the UI can display the configuration error state.
+            return next();
           }
         }
 

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

@@ -73,6 +73,16 @@ export function createAuthPlugin(config: AuthPluginConfig): Plugin {
         }
       }
 
+      // Register SuperTokens middleware on router for auth paths
+      // Uses config.apiBasePath so Gateway forwards requests to the correct path
+      // e.g. SUPERTOKENS_API_BASE_PATH=/qapi/auth → router.use('/qapi/auth', ...)
+      const authBasePath = config.apiBasePath ?? '/auth';
+      if (Array.isArray(primaryMiddleware)) {
+        router.use(authBasePath, ...primaryMiddleware);
+      } else {
+        router.use(authBasePath, primaryMiddleware);
+      }
+
       // Add the auth checking middleware to router (not app)
       // This ensures it processes requests to /api/* routes
       router.use(createAuthMiddleware());

package/src/plugins/auth/env-config.ts

@@ -402,6 +402,7 @@ export function createAuthPluginFromEnv(options?: AuthEnvPluginOptions): Plugin
     excludePaths,
     authRequired,
     debug,
+    apiBasePath: getEnv('SUPERTOKENS_API_BASE_PATH') ?? getEnv('AUTH_API_BASE_PATH'),
     onUnauthorized: options?.onUnauthorized,
     onAuthenticated: options?.onAuthenticated,
   };

package/src/plugins/auth/types.ts

@@ -180,6 +180,8 @@ export interface AuthPluginConfig {
   excludePaths?: string[];
   /** Whether auth is required for all routes (default: true) */
   authRequired?: boolean;
+  /** API base path for auth routes registered on the Express router (default: '/auth') */
+  apiBasePath?: string;
   /** Custom unauthorized handler */
   onUnauthorized?: (req: Request, res: Response) => void;
   /**

package/src/plugins/bans/BansManagementPage.tsx

@@ -23,7 +23,7 @@ interface Ban {
   createdBy?: string;
 }
 
-export function BansManagementPage({ apiPrefix = '/api/bans' }: BansManagementPageProps) {
+export function BansManagementPage({ apiPrefix = '/qapi/bans' }: BansManagementPageProps) {
   const [activeTab, setActiveTab] = useState<'all' | 'active' | 'expired' | 'config'>('all');
   const [bans, setBans] = useState<Ban[]>([]);
   const [loading, setLoading] = useState(true);

package/src/plugins/bans/BansStatusWidget.tsx

@@ -10,7 +10,7 @@ export interface BansStatusWidgetProps {
   apiPrefix?: string;
 }
 
-export function BansStatusWidget({ apiPrefix = '/api/bans' }: BansStatusWidgetProps) {
+export function BansStatusWidget({ apiPrefix = '/qapi/bans' }: BansStatusWidgetProps) {
   const [stats, setStats] = useState<{
     totalBans: number;
     activeBans: number;

package/src/plugins/cache/CacheManagementPage.tsx

@@ -32,7 +32,7 @@ interface CacheInfo {
 }
 
 export const CacheManagementPage: React.FC<CacheManagementPageProps> = ({
-  apiPrefix = '/api/plugins/cache',
+  apiPrefix = '/qapi/plugins/cache',
 }) => {
   const [keys, setKeys] = useState<CacheKey[]>([]);
   const [info, setInfo] = useState<CacheInfo | null>(null);

package/src/plugins/cache/CacheStatusWidget.tsx

@@ -26,7 +26,7 @@ interface CacheStats {
 }
 
 export const CacheStatusWidget: React.FC<CacheStatusWidgetProps> = ({
-  apiPrefix = '/api/plugins/cache',
+  apiPrefix = '/qapi/plugins/cache',
 }) => {
   const [stats, setStats] = useState<CacheStats | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/devices/DevicesManagementPage.tsx

@@ -23,7 +23,7 @@ interface Device {
   lastActiveAt?: string;
 }
 
-export function DevicesManagementPage({ apiPrefix = '/api/devices' }: DevicesManagementPageProps) {
+export function DevicesManagementPage({ apiPrefix = '/qapi/devices' }: DevicesManagementPageProps) {
   const [activeTab, setActiveTab] = useState<'all' | 'active' | 'pending' | 'config'>('all');
   const [devices, setDevices] = useState<Device[]>([]);
   const [loading, setLoading] = useState(true);

package/src/plugins/devices/DevicesStatusWidget.tsx

@@ -10,7 +10,7 @@ export interface DevicesStatusWidgetProps {
   apiPrefix?: string;
 }
 
-export function DevicesStatusWidget({ apiPrefix = '/api/devices' }: DevicesStatusWidgetProps) {
+export function DevicesStatusWidget({ apiPrefix = '/qapi/devices' }: DevicesStatusWidgetProps) {
   const [stats, setStats] = useState<{
     totalDevices: number;
     activeDevices: number;

package/src/plugins/diagnostics/DiagnosticsManagementPage.tsx

@@ -38,7 +38,7 @@ interface DiagnosticsReport {
 }
 
 export const DiagnosticsManagementPage: React.FC<DiagnosticsManagementPageProps> = ({
-  apiPrefix = '/api/plugins/diagnostics',
+  apiPrefix = '/qapi/plugins/diagnostics',
 }) => {
   const [report, setReport] = useState<DiagnosticsReport | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/diagnostics/DiagnosticsStatusWidget.tsx

@@ -26,7 +26,7 @@ interface DiagnosticsStats {
 }
 
 export const DiagnosticsStatusWidget: React.FC<DiagnosticsStatusWidgetProps> = ({
-  apiPrefix = '/api/plugins/diagnostics',
+  apiPrefix = '/qapi/plugins/diagnostics',
 }) => {
   const [stats, setStats] = useState<DiagnosticsStats | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/entitlements/EntitlementsManagementPage.tsx

@@ -22,7 +22,7 @@ interface Entitlement {
   grantedBy?: string;
 }
 
-export function EntitlementsManagementPage({ apiPrefix = '/api/entitlements' }: EntitlementsManagementPageProps) {
+export function EntitlementsManagementPage({ apiPrefix = '/qapi/entitlements' }: EntitlementsManagementPageProps) {
   const [activeTab, setActiveTab] = useState<'all' | 'active' | 'expired' | 'config'>('all');
   const [entitlements, setEntitlements] = useState<Entitlement[]>([]);
   const [loading, setLoading] = useState(true);

package/src/plugins/entitlements/EntitlementsStatusWidget.tsx

@@ -10,7 +10,7 @@ export interface EntitlementsStatusWidgetProps {
   apiPrefix?: string;
 }
 
-export function EntitlementsStatusWidget({ apiPrefix = '/api/entitlements' }: EntitlementsStatusWidgetProps) {
+export function EntitlementsStatusWidget({ apiPrefix = '/qapi/entitlements' }: EntitlementsStatusWidgetProps) {
   const [stats, setStats] = useState<{
     totalEntitlements: number;
     activeEntitlements: number;

package/src/plugins/health/HealthManagementPage.tsx

@@ -33,7 +33,7 @@ interface HealthSummary {
 }
 
 export const HealthManagementPage: React.FC<HealthManagementPageProps> = ({
-  apiPrefix = '/api/plugins/health',
+  apiPrefix = '/qapi/plugins/health',
 }) => {
   const [summary, setSummary] = useState<HealthSummary | null>(null);
   const [selectedCheck, setSelectedCheck] = useState<HealthCheckResult | null>(null);

package/src/plugins/health/HealthStatusWidget.tsx

@@ -33,7 +33,7 @@ interface HealthSummary {
 }
 
 export const HealthStatusWidget: React.FC<HealthStatusWidgetProps> = ({
-  apiPrefix = '/api/plugins/health',
+  apiPrefix = '/qapi/plugins/health',
 }) => {
   const [summary, setSummary] = useState<HealthSummary | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/logs/LogsManagementPage.tsx

@@ -42,7 +42,7 @@ interface LogStats {
 }
 
 export const LogsManagementPage: React.FC<LogsManagementPageProps> = ({
-  apiPrefix = '/api/plugins/logs',
+  apiPrefix = '/qapi/plugins/logs',
 }) => {
   const [logs, setLogs] = useState<LogEntry[]>([]);
   const [sources, setSources] = useState<LogSource[]>([]);

package/src/plugins/logs/LogsStatusWidget.tsx

@@ -28,7 +28,7 @@ interface LogStats {
 }
 
 export const LogsStatusWidget: React.FC<LogsStatusWidgetProps> = ({
-  apiPrefix = '/api/plugins/logs',
+  apiPrefix = '/qapi/plugins/logs',
 }) => {
   const [stats, setStats] = useState<LogStats | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/maintenance/MaintenanceManagementPage.tsx

@@ -30,7 +30,7 @@ interface MaintenanceStatus {
 }
 
 export const MaintenanceManagementPage: React.FC<MaintenanceManagementPageProps> = ({
-  apiPrefix = '/api/plugins/maintenance',
+  apiPrefix = '/qapi/plugins/maintenance',
 }) => {
   const [status, setStatus] = useState<MaintenanceStatus | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/maintenance/MaintenanceStatusWidget.tsx

@@ -26,7 +26,7 @@ interface MaintenanceStatus {
 }
 
 export const MaintenanceStatusWidget: React.FC<MaintenanceStatusWidgetProps> = ({
-  apiPrefix = '/api/plugins/maintenance',
+  apiPrefix = '/qapi/plugins/maintenance',
 }) => {
   const [status, setStatus] = useState<MaintenanceStatus | null>(null);
   const [loading, setLoading] = useState(true);

package/src/plugins/maintenance/SeedManagementPage.tsx

@@ -19,7 +19,7 @@ export interface SeedManagementPageProps {
 type Tab = 'list' | 'execute' | 'history';
 
 export const SeedManagementPage: React.FC<SeedManagementPageProps> = ({
-  apiPrefix = '/api/plugins/maintenance',
+  apiPrefix = '/qapi/plugins/maintenance',
 }) => {
   const [activeTab, setActiveTab] = useState<Tab>('list');
   const [selectedSeed, setSelectedSeed] = useState<string | null>(null);

package/src/plugins/maintenance/seed-executor.ts

@@ -45,8 +45,8 @@ const MAX_OUTPUT_SIZE = 100 * 1024;
  * @returns Resolved absolute path if valid, null if invalid
  */
 export function validateScriptPath(scriptPath: string, scriptsPath: string): string | null {
-  // Only allow .mjs files
-  if (!scriptPath.endsWith('.mjs')) {
+  // Only allow .mjs and .ts files
+  if (!scriptPath.endsWith('.mjs') && !scriptPath.endsWith('.ts')) {
     return null;
   }
 
@@ -106,11 +106,12 @@ export class SeedExecutor {
     this.outputSize = 0;
 
     return new Promise((resolvePromise, rejectPromise) => {
-      // Determine if we need tsx (for .ts/.mts files that import TS modules)
-      // Use tsx for .mjs files too since they might import from TS source
-      const needsTsx = scriptPath.match(/\.(mjs|ts|mts)$/);
+      // .ts/.mts files require tsx for TypeScript compilation.
+      // .mjs files are native ESM and run directly with node — tsx is not
+      // available in the system PATH in Docker production builds.
+      const needsTsx = scriptPath.match(/\.(ts|mts)$/);
       const execCommand = needsTsx ? 'tsx' : process.execPath;
-      const execArgs = needsTsx ? [scriptPath] : [scriptPath];
+      const execArgs = [scriptPath];
 
       // Spawn process with TypeScript support if needed
       this.child = spawn(execCommand, execArgs, {