webspresso 0.0.97 → 0.0.98

package/plugins/swagger.js

@@ -1,5 +1,8 @@
+'use strict';
+
 /**
- * Swagger / OpenAPI plugin — HTTP API docs from file-based routes + Zod, optional ORM schemas
+ * Swagger / Scalar / OpenAPI plugin — HTTP API docs from file-based routes + Zod, optional ORM schemas
+ * @module plugins/swagger
  */
 
 const path = require('path');
@@ -9,17 +12,44 @@ const { buildOpenApiDocument } = require('../core/openapi/build-from-api-routes'
 const PKG = require(path.join(__dirname, '..', 'package.json'));
 
 /**
+ * HTML Escaping
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Generates Swagger UI HTML page
  * @param {string} specUrl - Absolute path on same origin (e.g. /_swagger/openapi.json)
+ * @param {Object} [options]
+ * @returns {string}
  */
-function buildSwaggerUiHtml(specUrl) {
+function buildSwaggerUiHtml(specUrl, options = {}) {
+  const title = escapeHtml(options.title || 'API Documentation');
+  const docExpansion = JSON.stringify(options.docExpansion || 'list');
+  const filter = JSON.stringify(options.filter !== false);
   const urlJson = JSON.stringify(specUrl);
+
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>API documentation</title>
+  <title>${title}</title>
   <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" crossorigin />
+  <style>
+    body { margin: 0; padding: 0; background: #fafafa; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+    .swagger-ui .topbar { display: none; }
+    .swagger-ui .information-container { margin-bottom: 20px; }
+  </style>
 </head>
 <body>
   <div id="swagger-ui"></div>
@@ -29,7 +59,11 @@ function buildSwaggerUiHtml(specUrl) {
       SwaggerUIBundle({
         url: ${urlJson},
         dom_id: '#swagger-ui',
-        deepLinking: true
+        deepLinking: true,
+        persistAuthorization: true,
+        displayRequestDuration: true,
+        docExpansion: ${docExpansion},
+        filter: ${filter}
       });
     };
   </script>
@@ -38,20 +72,140 @@ function buildSwaggerUiHtml(specUrl) {
 }
 
 /**
+ * Generates modern Scalar API Reference HTML page
+ * @param {string} specUrl - Absolute path on same origin (e.g. /_swagger/openapi.json)
+ * @param {Object} [options]
+ * @returns {string}
+ */
+function buildScalarUiHtml(specUrl, options = {}) {
+  const title = escapeHtml(options.title || 'API Reference');
+  const theme = options.theme || 'default';
+  const darkMode = options.darkMode !== false;
+  const layout = options.layout || 'modern';
+  const showSidebar = options.showSidebar !== false;
+  const scalarOptions = options.scalarOptions || {};
+
+  const configuration = {
+    spec: {
+      url: specUrl,
+    },
+    theme,
+    darkMode,
+    layout,
+    showSidebar,
+    ...scalarOptions,
+  };
+
+  if (options.proxyUrl) {
+    configuration.proxyUrl = options.proxyUrl;
+  }
+
+  const configJson = JSON.stringify(configuration).replace(/</g, '\\u003c');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+      height: 100vh;
+      overflow: hidden;
+    }
+  </style>
+</head>
+<body>
+  <script
+    id="api-reference"
+    type="application/json">
+    ${configJson}
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+}
+
+/**
+ * Generates Admin Panel client component to embed API docs
+ * @param {Object} opts
+ * @returns {string}
+ */
+function generateApiDocsAdminComponent({ uiPath, jsonPath, title }) {
+  const safeTitle = JSON.stringify(title || 'API Documentation');
+  const safeUi = JSON.stringify(uiPath);
+  const safeJson = JSON.stringify(jsonPath);
+
+  return `
+(function() {
+  var uiUrl = ${safeUi};
+  var jsonUrl = ${safeJson};
+  var pageTitle = ${safeTitle};
+
+  return {
+    view: function() {
+      return m('div.flex.flex-col', { style: { minHeight: 'calc(100vh - 140px)' } }, [
+        m('div.flex.items-center.justify-between.p-4.bg-white.border.border-gray-200.rounded-lg.mb-4.shadow-sm', [
+          m('div', [
+            m('h2.text-lg.font-bold.text-gray-900', pageTitle),
+            m('p.text-xs.text-gray-500', 'Interactive OpenAPI documentation & endpoint playground')
+          ]),
+          m('div.flex.items-center.space-x-2', [
+            m('a.inline-flex.items-center.px-3.py-1.5.text-xs.font-medium.rounded.border.border-gray-300.bg-white.text-gray-700.hover:bg-gray-50', {
+              href: jsonUrl,
+              target: '_blank',
+              rel: 'noopener noreferrer'
+            }, 'View OpenAPI JSON ↗'),
+            m('a.inline-flex.items-center.px-3.py-1.5.text-xs.font-medium.rounded.bg-indigo-600.text-white.hover:bg-indigo-700', {
+              href: uiUrl,
+              target: '_blank',
+              rel: 'noopener noreferrer'
+            }, 'Open Full Screen ↗')
+          ])
+        ]),
+        m('div.flex-1.bg-white.border.border-gray-200.rounded-lg.overflow-hidden.shadow-sm', {
+          style: { minHeight: '750px' }
+        }, [
+          m('iframe', {
+            src: uiUrl,
+            style: { width: '100%', height: '100%', minHeight: '750px', border: 'none' }
+          })
+        ])
+      ]);
+    }
+  };
+})();
+`;
+}
+
+/**
+ * Swagger / Scalar / OpenAPI Plugin
+ *
  * @param {Object} [options]
  * @param {string} [options.path='/_swagger'] - Base path; JSON at `{path}/openapi.json`, UI at `{path}`
+ * @param {'swagger'|'scalar'} [options.ui='swagger'] - Default UI playground engine ('scalar' or 'swagger')
  * @param {boolean} [options.enabled] - Default: development only
  * @param {Function} [options.authorize] - (req) => boolean
- * @param {boolean} [options.includeOrmSchemas] - Merge ORM components.schemas
+ * @param {boolean} [options.includeOrmSchemas=false] - Merge ORM components.schemas
  * @param {string[]} [options.ormExclude] - Model names to exclude when includeOrmSchemas
  * @param {string} [options.title] - OpenAPI info.title
  * @param {string} [options.version] - OpenAPI info.version
  * @param {string} [options.description] - OpenAPI info.description
  * @param {string} [options.serverUrl] - Override servers[0].url (default: BASE_URL or http://localhost:3000)
+ * @param {string} [options.theme='default'] - Theme for Scalar UI
+ * @param {boolean} [options.darkMode=true] - Dark mode default for Scalar UI
+ * @param {boolean} [options.admin=true] - Auto-register in Admin Panel if admin-panel plugin is present
+ * @param {string} [options.adminTitle='API Docs'] - Admin menu/page title
+ * @param {number} [options.adminOrder=92] - Admin menu sort order
+ * @param {Object} [options.scalarOptions] - Custom options passed to Scalar configuration
+ * @param {Object} [options.swaggerOptions] - Custom options passed to Swagger UI
  */
 function swaggerPlugin(options = {}) {
   const {
     path: basePath = '/_swagger',
+    ui = 'swagger',
     enabled,
     authorize,
     includeOrmSchemas = false,
@@ -60,15 +214,31 @@ function swaggerPlugin(options = {}) {
     version,
     description,
     serverUrl,
+    theme = 'default',
+    darkMode = true,
+    admin = true,
+    adminTitle,
+    adminOrder = 92,
+    scalarOptions = {},
+    swaggerOptions = {},
   } = options;
 
   const normalizedBase = `/${trimUrlPathSlashes(basePath)}`;
   const jsonPath = `${normalizedBase}/openapi.json`;
   const uiPath = normalizedBase;
+  const swaggerSubPath = `${normalizedBase}/swagger`;
+  const scalarSubPath = `${normalizedBase}/scalar`;
+
+  const docTitle = title || PKG.name || 'API';
+  const docVersion = version || PKG.version || '1.0.0';
+  const docDescription =
+    description || 'Generated from pages/api routes and optional Zod schema exports.';
+
+  const isScalarPrimary = String(ui).toLowerCase() === 'scalar';
 
   return {
     name: 'swagger',
-    version: '1.0.0',
+    version: '1.2.0',
 
     onRoutesReady(ctx) {
       const isDev = process.env.NODE_ENV !== 'production';
@@ -88,6 +258,7 @@ function swaggerPlugin(options = {}) {
 
       const server = serverUrl || process.env.BASE_URL || 'http://localhost:3000';
 
+      // 1. OpenAPI 3 JSON Endpoint
       ctx.addRoute('get', jsonPath, (req, res) => {
         if (forbid(req, res)) return;
         try {
@@ -97,11 +268,9 @@ function swaggerPlugin(options = {}) {
             includeOrmSchemas,
             ormExclude,
             info: {
-              title: title || PKG.name || 'API',
-              version: version || PKG.version || '1.0.0',
-              description:
-                description ||
-                'Generated from pages/api routes and optional Zod schema exports.',
+              title: docTitle,
+              version: docVersion,
+              description: docDescription,
             },
             servers: [{ url: server.replace(/\/$/, '') }],
           });
@@ -112,16 +281,95 @@ function swaggerPlugin(options = {}) {
         }
       });
 
+      // 2. Swagger UI Explicit Endpoint
+      ctx.addRoute('get', swaggerSubPath, (req, res) => {
+        if (forbid(req, res)) return;
+        res.type('html').send(
+          buildSwaggerUiHtml(jsonPath, {
+            title: `${docTitle} - Swagger UI`,
+            ...swaggerOptions,
+          })
+        );
+      });
+
+      // 3. Scalar UI Explicit Endpoint
+      ctx.addRoute('get', scalarSubPath, (req, res) => {
+        if (forbid(req, res)) return;
+        res.type('html').send(
+          buildScalarUiHtml(jsonPath, {
+            title: `${docTitle} - Scalar API Reference`,
+            theme,
+            darkMode,
+            scalarOptions,
+          })
+        );
+      });
+
+      // 4. Primary UI Endpoint (Swagger or Scalar based on options.ui)
       ctx.addRoute('get', uiPath, (req, res) => {
         if (forbid(req, res)) return;
-        res.type('html').send(buildSwaggerUiHtml(jsonPath));
+        if (isScalarPrimary) {
+          res.type('html').send(
+            buildScalarUiHtml(jsonPath, {
+              title: `${docTitle} - API Reference`,
+              theme,
+              darkMode,
+              scalarOptions,
+            })
+          );
+        } else {
+          res.type('html').send(
+            buildSwaggerUiHtml(jsonPath, {
+              title: `${docTitle} - API Documentation`,
+              ...swaggerOptions,
+            })
+          );
+        }
       });
 
+      // 5. Admin Panel Integration
+      const adminApi = typeof ctx.usePlugin === 'function' ? ctx.usePlugin('admin-panel') : null;
+      if (adminApi && admin !== false) {
+        const pageTitle = adminTitle || title || 'API Docs';
+        try {
+          adminApi.registerModule({
+            id: 'api-docs',
+            title: pageTitle,
+            pages: [{
+              id: 'api-docs',
+              title: pageTitle,
+              path: '/api-docs',
+              icon: 'tool',
+              component: generateApiDocsAdminComponent({
+                uiPath,
+                jsonPath,
+                title: pageTitle,
+              }),
+            }],
+            menu: [{
+              id: 'api-docs',
+              label: pageTitle,
+              path: '/api-docs',
+              icon: 'tool',
+              order: adminOrder,
+            }],
+          });
+        } catch (adminErr) {
+          console.warn('[swagger] Failed to register admin module:', adminErr.message);
+        }
+      }
+
       if (isDev) {
-        console.log(`  Swagger UI: ${uiPath} (OpenAPI: ${jsonPath})`);
+        const primaryEngine = isScalarPrimary ? 'Scalar' : 'Swagger';
+        console.log(`  API Docs (${primaryEngine}): ${uiPath} (OpenAPI: ${jsonPath})`);
       }
     },
   };
 }
 
 module.exports = swaggerPlugin;
+module.exports.swaggerPlugin = swaggerPlugin;
+module.exports.openapiPlugin = swaggerPlugin;
+module.exports.apiDocsPlugin = swaggerPlugin;
+module.exports.buildSwaggerUiHtml = buildSwaggerUiHtml;
+module.exports.buildScalarUiHtml = buildScalarUiHtml;

package/plugins/upload/index.js

@@ -126,6 +126,25 @@ function uploadPlugin(options = {}) {
     version: '1.0.0',
     description: 'Multipart file uploads with pluggable storage',
 
+    api: {
+      scanOrphanedUploads(opts = {}) {
+        const { scanOrphanedUploads } = require('./orphan-pruner');
+        return scanOrphanedUploads({
+          destDir: local?.destDir,
+          publicBasePath: local?.publicBasePath,
+          ...opts,
+        });
+      },
+      pruneOrphanedUploads(opts = {}) {
+        const { pruneOrphanedUploads } = require('./orphan-pruner');
+        return pruneOrphanedUploads({
+          destDir: local?.destDir,
+          publicBasePath: local?.publicBasePath,
+          ...opts,
+        });
+      },
+    },
+
     register(ctx) {
       if (ctx.app && ctx.app.serviceRegistry) {
         const { createMediaServices } = require('../../src/services/builtins/media');
@@ -221,7 +240,14 @@ function uploadPlugin(options = {}) {
   };
 }
 
+const {
+  scanOrphanedUploads,
+  pruneOrphanedUploads,
+} = require('./orphan-pruner');
+
 module.exports = {
   uploadPlugin,
   createLocalFileProvider,
+  scanOrphanedUploads,
+  pruneOrphanedUploads,
 };

package/plugins/upload/orphan-pruner.js

@@ -0,0 +1,292 @@
+'use strict';
+
+/**
+ * Orphaned Uploads Scanner & Pruner
+ * Identifies and deletes unreferenced uploaded files from disk.
+ * Zero external dependencies.
+ * @module plugins/upload/orphan-pruner
+ */
+
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const { normalizePublicBase } = require('./local-file-provider');
+
+/**
+ * Format bytes into human readable string
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+/**
+ * Recursively find all files in a directory
+ * @param {string} dir
+ * @param {string} [baseDir]
+ * @returns {Promise<Array<{ relativePath: string, absolutePath: string, size: number, mtime: Date }>>}
+ */
+async function scanDirectoryFiles(dir, baseDir = dir) {
+  const results = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue; // ignore hidden files
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const subFiles = await scanDirectoryFiles(fullPath, baseDir);
+        results.push(...subFiles);
+      } else if (entry.isFile()) {
+        try {
+          const st = await fs.stat(fullPath);
+          const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+          results.push({
+            relativePath,
+            absolutePath: fullPath,
+            size: st.size,
+            mtime: st.mtime,
+          });
+        } catch (e) {
+          // File might have been removed concurrently, ignore
+        }
+      }
+    }
+  } catch (e) {
+    // Directory not accessible, ignore
+  }
+  return results;
+}
+
+/**
+ * Extract all referenced file names and URL fragments from database
+ * @param {Object} db - Database instance (with knex and optional models)
+ * @returns {Promise<Set<string>>}
+ */
+async function extractDbFileReferences(db) {
+  const references = new Set();
+  if (!db || !db.knex) return references;
+
+  const { getAllModels } = require('../../core/orm/model');
+  const allModels = db.getAllModels ? db.getAllModels() : Array.from(getAllModels().values());
+  const modelList = Array.isArray(allModels) ? allModels : Array.from(allModels.values());
+
+  const tablesToScan = new Set();
+  for (const model of modelList) {
+    if (model.table) tablesToScan.add(model.table);
+  }
+
+  // Common additional tables
+  const extraTables = ['admin_users', 'files', 'media', 'attachments', 'content_items'];
+  for (const t of extraTables) {
+    try {
+      if (await db.knex.schema.hasTable(t)) {
+        tablesToScan.add(t);
+      }
+    } catch (e) {}
+  }
+
+  function addStringReference(val) {
+    if (typeof val !== 'string' || !val) return;
+    const str = val.trim();
+    if (!str) return;
+
+    // Direct path or filename
+    references.add(str);
+    references.add(path.basename(str));
+
+    // Normalized url without leading /
+    references.add(str.replace(/^\/+/, ''));
+
+    // Extract potential url/filename tokens inside rich-text or JSON
+    const matches = str.match(/[a-zA-Z0-9_\-\.\/]+\.[a-zA-Z0-9]{2,8}/g);
+    if (matches) {
+      for (const m of matches) {
+        references.add(m);
+        references.add(path.basename(m));
+        references.add(m.replace(/^\/+/, ''));
+      }
+    }
+  }
+
+  function scanValue(val) {
+    if (val == null) return;
+    if (typeof val === 'string') {
+      addStringReference(val);
+    } else if (Array.isArray(val)) {
+      for (const item of val) scanValue(item);
+    } else if (typeof val === 'object') {
+      for (const k of Object.keys(val)) {
+        scanValue(val[k]);
+      }
+    }
+  }
+
+  for (const table of tablesToScan) {
+    try {
+      const exists = await db.knex.schema.hasTable(table);
+      if (!exists) continue;
+
+      const rows = await db.knex(table).select();
+      for (const row of rows) {
+        if (!row || typeof row !== 'object') continue;
+        for (const [key, value] of Object.entries(row)) {
+          // If value is a JSON string, try to parse
+          if (typeof value === 'string' && (value.startsWith('{') || value.startsWith('['))) {
+            try {
+              const parsed = JSON.parse(value);
+              scanValue(parsed);
+            } catch (e) {
+              addStringReference(value);
+            }
+          } else {
+            scanValue(value);
+          }
+        }
+      }
+    } catch (e) {
+      // Table scan failed, ignore
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Scan for orphaned upload files
+ * @param {Object} options
+ * @param {Object} [options.db] - Database instance
+ * @param {string} [options.destDir] - Uploads directory on disk
+ * @param {string} [options.publicBasePath='/uploads'] - Public URL base path
+ * @returns {Promise<Object>}
+ */
+async function scanOrphanedUploads(options = {}) {
+  const { db, publicBasePath = '/uploads' } = options;
+  const destDir = path.resolve(
+    options.destDir || path.join(process.cwd(), 'public', 'uploads')
+  );
+
+  let diskFiles = [];
+  if (fsSync.existsSync(destDir)) {
+    diskFiles = await scanDirectoryFiles(destDir);
+  }
+
+  let totalBytes = 0;
+  for (const f of diskFiles) {
+    totalBytes += f.size;
+  }
+
+  const dbReferences = await extractDbFileReferences(db);
+  const normalizedBase = normalizePublicBase(publicBasePath);
+
+  const orphanedFiles = [];
+  const referencedFiles = [];
+
+  for (const file of diskFiles) {
+    const baseName = path.basename(file.relativePath);
+    const fullPublicUrl = `${normalizedBase}/${file.relativePath}`.replace(/\/{2,}/g, '/');
+
+    // Check if filename, relative path, or public url is referenced in DB
+    const isReferenced =
+      dbReferences.has(file.relativePath) ||
+      dbReferences.has(baseName) ||
+      dbReferences.has(fullPublicUrl) ||
+      dbReferences.has(fullPublicUrl.replace(/^\/+/, ''));
+
+    if (isReferenced) {
+      referencedFiles.push(file);
+    } else {
+      orphanedFiles.push({
+        ...file,
+        publicUrl: fullPublicUrl,
+      });
+    }
+  }
+
+  let orphanedBytes = 0;
+  for (const f of orphanedFiles) {
+    orphanedBytes += f.size;
+  }
+
+  return {
+    destDir,
+    totalFiles: diskFiles.length,
+    totalBytes,
+    totalBytesFormatted: formatBytes(totalBytes),
+    referencedCount: referencedFiles.length,
+    orphanedCount: orphanedFiles.length,
+    orphanedBytes,
+    orphanedBytesFormatted: formatBytes(orphanedBytes),
+    orphanedFiles,
+  };
+}
+
+/**
+ * Prune orphaned uploads from disk
+ * @param {Object} options
+ * @param {Object} [options.db] - Database instance
+ * @param {string} [options.destDir] - Uploads directory on disk
+ * @param {string} [options.publicBasePath='/uploads'] - Public URL base path
+ * @param {boolean} [options.dryRun=false] - Only scan without deleting
+ * @returns {Promise<Object>}
+ */
+async function pruneOrphanedUploads(options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const scan = await scanOrphanedUploads(options);
+
+  if (dryRun || scan.orphanedCount === 0) {
+    return {
+      ...scan,
+      dryRun,
+      deletedCount: 0,
+      deletedBytes: 0,
+      deletedBytesFormatted: formatBytes(0),
+      deletedFiles: [],
+    };
+  }
+
+  const deletedFiles = [];
+  let deletedBytes = 0;
+
+  for (const file of scan.orphanedFiles) {
+    try {
+      await fs.unlink(file.absolutePath);
+      deletedFiles.push(file.relativePath);
+      deletedBytes += file.size;
+
+      // Try to clean up empty parent directories
+      const parentDir = path.dirname(file.absolutePath);
+      if (parentDir !== scan.destDir) {
+        try {
+          const contents = await fs.readdir(parentDir);
+          if (contents.length === 0) {
+            await fs.rmdir(parentDir);
+          }
+        } catch (e) {}
+      }
+    } catch (e) {
+      // Deletion error, ignore
+    }
+  }
+
+  return {
+    ...scan,
+    dryRun: false,
+    deletedCount: deletedFiles.length,
+    deletedBytes,
+    deletedBytesFormatted: formatBytes(deletedBytes),
+    deletedFiles,
+  };
+}
+
+module.exports = {
+  formatBytes,
+  scanDirectoryFiles,
+  extractDbFileReferences,
+  scanOrphanedUploads,
+  pruneOrphanedUploads,
+};

package/src/api/api-loader.js

@@ -116,7 +116,9 @@ function createApiHandler(descriptor, context) {
           return next(loadErr);
         }
 
-        apiDef = typeof apiModule === 'function' ? { handler: apiModule } : apiModule.default || apiModule;
+        apiDef = typeof apiModule === 'function'
+          ? Object.assign({ handler: apiModule }, apiModule)
+          : (apiModule.default || apiModule);
         handlerFn = apiDef.handler || (typeof apiModule === 'function' ? apiModule : null);
 
         if (typeof handlerFn !== 'function') {