webspresso 0.0.94 → 0.0.96

package/src/discovery/file-route-parser.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * Webspresso File Route Parser
+ * Converts relative filesystem paths into Express route paths and HTTP methods
+ * @module src/discovery/file-route-parser
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SUPPORTED_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head']);
+const SUPPORTED_EXTENSIONS = new Set(['.js', '.njk']);
+const METHOD_SUFFIX_REGEX = /\.([a-zA-Z]+)\.js$/;
+const TEMPORARY_FILE_REGEX = /(?:~|\.swp|\.tmp|\.bak|\.DS_Store)$/;
+
+/**
+ * Safely scans a directory recursively for route files
+ * @param {string} dirPath - Absolute directory path
+ * @param {string} [baseDir=dirPath] - Base directory for computing relative paths
+ * @returns {Array<{ absolutePath: string, relativePath: string }>}
+ */
+function scanDirSafely(dirPath, baseDir = dirPath) {
+  const results = [];
+  if (!fs.existsSync(dirPath)) return results;
+
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const name = entry.name;
+      if (isPrivateOrIgnored(name)) continue;
+
+      const fullPath = path.join(dirPath, name);
+      const relPath = path.relative(baseDir, fullPath);
+
+      if (entry.isDirectory()) {
+        results.push(...scanDirSafely(fullPath, baseDir));
+      } else if (entry.isFile()) {
+        const ext = path.extname(name);
+        if (SUPPORTED_EXTENSIONS.has(ext)) {
+          results.push({
+            absolutePath: fullPath,
+            relativePath: relPath,
+          });
+        }
+      }
+    }
+  } catch (err) {
+    console.warn(`[webspresso] Failed to scan directory ${dirPath}:`, err.message);
+  }
+
+  return results;
+}
+
+/**
+ * Checks if a filename or directory name should be ignored (private or temporary)
+ * @param {string} name - File or directory basename
+ * @returns {boolean}
+ */
+function isPrivateOrIgnored(name) {
+  if (!name || typeof name !== 'string') return true;
+  // Hidden files/directories (.git, .DS_Store, .login.js.swp)
+  if (name.startsWith('.')) return true;
+  // Private files/directories (_components, _helpers, _private.js)
+  if (name.startsWith('_')) return true;
+  // Temporary editor files
+  if (TEMPORARY_FILE_REGEX.test(name)) return true;
+  return false;
+}
+
+/**
+ * Converts parameter markers [id] -> :id and catch-all [...path] -> *
+ * @param {string} segment
+ * @returns {string}
+ */
+function transformDynamicSegment(segment) {
+  if (!segment || typeof segment !== 'string') return segment || '';
+  if (segment.startsWith('[...') && segment.endsWith(']')) {
+    const paramName = segment.slice(4, -1).trim();
+    return paramName ? `*${paramName}` : '*';
+  }
+  if (segment.startsWith('[') && segment.endsWith(']')) {
+    const paramName = segment.slice(1, -1).trim();
+    return paramName ? `:${paramName}` : segment;
+  }
+  return segment;
+}
+
+/**
+ * Normalizes a URL prefix to have a leading slash and no trailing slash
+ * @param {string} [prefix='']
+ * @returns {string}
+ */
+function normalizePrefix(prefix = '') {
+  if (!prefix || typeof prefix !== 'string') return '';
+  let clean = prefix.trim().replace(/\\/g, '/');
+  clean = clean.replace(/\/+/g, '/');
+  if (clean === '/' || !clean) return '';
+  if (!clean.startsWith('/')) clean = '/' + clean;
+  if (clean.endsWith('/')) clean = clean.slice(0, -1);
+  return clean === '/' ? '' : clean;
+}
+
+/**
+ * Parses a relative file path for an API or Page route
+ * @param {string} relativePath - Relative path from directory root (e.g. 'users/[id].get.js' or 'blog/[slug].js')
+ * @param {Object} [options]
+ * @param {string} [options.type='page'] - 'page' | 'api'
+ * @param {string} [options.prefix=''] - Base prefix (e.g. '/api' or '/auth')
+ * @returns {{ path: string, method: string, isValid: boolean, isPrivate: boolean, originalMethodPart?: string }}
+ */
+function parseFileRoute(relativePath, options = {}) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    return { path: '', method: '', isValid: false, isPrivate: false };
+  }
+
+  const { type = 'page', prefix = '' } = options;
+
+  // Normalize path separators to forward slashes
+  const normalizedPath = relativePath.split(path.sep).join('/').replace(/\\/g, '/');
+  const segments = normalizedPath.split('/').filter(Boolean);
+
+  // Check if any segment is private or ignored
+  for (const seg of segments) {
+    if (isPrivateOrIgnored(seg)) {
+      return { path: '', method: '', isValid: false, isPrivate: true };
+    }
+  }
+
+  const filename = segments[segments.length - 1];
+  if (!filename) {
+    return { path: '', method: '', isValid: false, isPrivate: false };
+  }
+
+  let method = 'get';
+  let cleanFilename = filename;
+  let originalMethodPart = null;
+
+  // Check for HTTP method suffix: e.g. health.get.js, [id].patch.js
+  const methodMatch = filename.match(METHOD_SUFFIX_REGEX);
+  if (methodMatch) {
+    const rawMethod = methodMatch[1].toLowerCase();
+    originalMethodPart = rawMethod;
+    if (SUPPORTED_METHODS.has(rawMethod)) {
+      method = rawMethod;
+      cleanFilename = filename.replace(`.${methodMatch[1]}.js`, '');
+    } else {
+      // Invalid HTTP method in filename
+      return { path: '', method: rawMethod, isValid: false, isPrivate: false, invalidMethod: true };
+    }
+  } else if (filename.endsWith('.js')) {
+    cleanFilename = filename.slice(0, -3);
+  } else if (filename.endsWith('.njk')) {
+    cleanFilename = filename.slice(0, -4);
+  }
+
+  // Replace last segment with cleanFilename
+  const routeSegments = [...segments.slice(0, -1), cleanFilename];
+
+  // Process dynamic brackets in segments
+  const transformedSegments = routeSegments.map(transformDynamicSegment);
+
+  // Handle 'index' at the end of path
+  if (transformedSegments[transformedSegments.length - 1] === 'index') {
+    transformedSegments.pop();
+  }
+
+  let routePath = '/' + transformedSegments.join('/');
+  if (routePath === '//' || routePath === '') {
+    routePath = '/';
+  }
+
+  // Combine with prefix
+  const cleanPrefix = normalizePrefix(prefix);
+  if (cleanPrefix) {
+    if (routePath === '/') {
+      routePath = cleanPrefix;
+    } else {
+      routePath = `${cleanPrefix}${routePath}`;
+    }
+  }
+
+  return {
+    path: routePath,
+    method: method.toUpperCase(),
+    isValid: true,
+    isPrivate: false,
+    originalMethodPart,
+  };
+}
+
+module.exports = {
+  parseFileRoute,
+  isPrivateOrIgnored,
+  normalizePrefix,
+  transformDynamicSegment,
+  scanDirSafely,
+  SUPPORTED_METHODS,
+  SUPPORTED_EXTENSIONS,
+};

package/src/discovery/scan-routes.js

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * Webspresso Route Discovery Scanner
+ * Scans pages, api, and module directories to produce raw route descriptors
+ * @module src/discovery/scan-routes
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseFileRoute, isPrivateOrIgnored } = require('./file-route-parser');
+const { discoverModuleDetails } = require('../modules/module-discovery');
+
+const SUPPORTED_EXTENSIONS = new Set(['.js', '.njk']);
+
+/**
+ * Safely scans a directory recursively for route files
+ * @param {string} dirPath - Absolute directory path
+ * @param {string} [baseDir=dirPath] - Base directory for computing relative paths
+ * @returns {Array<{ absolutePath: string, relativePath: string }>}
+ */
+function scanDirSafely(dirPath, baseDir = dirPath) {
+  const results = [];
+  if (!fs.existsSync(dirPath)) return results;
+
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const name = entry.name;
+      if (isPrivateOrIgnored(name)) continue;
+
+      const fullPath = path.join(dirPath, name);
+      const relPath = path.relative(baseDir, fullPath);
+
+      if (entry.isDirectory()) {
+        results.push(...scanDirSafely(fullPath, baseDir));
+      } else if (entry.isFile()) {
+        const ext = path.extname(name);
+        if (SUPPORTED_EXTENSIONS.has(ext)) {
+          results.push({
+            absolutePath: fullPath,
+            relativePath: relPath,
+          });
+        }
+      }
+    }
+  } catch (err) {
+    console.warn(`[webspresso] Failed to scan directory ${dirPath}:`, err.message);
+  }
+
+  return results;
+}
+
+/**
+ * Scans configured pages, api, and module directories
+ * @param {Object} options
+ * @param {string} [options.rootDir=process.cwd()] - Project root directory
+ * @param {boolean|Object} [options.pages] - Pages configuration
+ * @param {boolean|Object} [options.api] - API configuration
+ * @param {boolean|Object} [options.modules] - Modules configuration
+ * @returns {Array<Object>} Discovered route descriptors
+ */
+function scanRoutes(options = {}) {
+  const rootDir = options.rootDir || process.cwd();
+  const descriptors = [];
+
+  // Helper to resolve directory paths
+  function resolveDirCandidate(candidates) {
+    for (const cand of candidates) {
+      const p = path.isAbsolute(cand) ? cand : path.join(rootDir, cand);
+      if (fs.existsSync(p)) return p;
+    }
+    return null;
+  }
+
+  // 1. Scan Global Pages
+  const pagesOpt = options.pages;
+  if (pagesOpt !== false) {
+    const explicitPagesDir = typeof pagesOpt === 'object' && pagesOpt.dir ? pagesOpt.dir : null;
+    const pagesPrefix = typeof pagesOpt === 'object' && pagesOpt.prefix ? pagesOpt.prefix : '';
+    const pagesDir = explicitPagesDir
+      ? (path.isAbsolute(explicitPagesDir) ? explicitPagesDir : path.join(rootDir, explicitPagesDir))
+      : resolveDirCandidate(['src/pages', 'pages']);
+
+    if (pagesDir && fs.existsSync(pagesDir)) {
+      const files = scanDirSafely(pagesDir);
+      const filesSet = new Set(files.map((f) => f.absolutePath));
+
+      for (const { absolutePath, relativePath } of files) {
+        // Skip .njk templates (handled by classic Nunjucks mountPages)
+        if (relativePath.endsWith('.njk')) {
+          continue;
+        }
+
+        // Skip non-js files
+        if (!relativePath.endsWith('.js')) {
+          continue;
+        }
+
+        // Skip api directory inside pages (handled by classic mountPages or explicit api scan)
+        const isUnderApi = relativePath.startsWith('api' + path.sep) || relativePath.startsWith('api/');
+        if (isUnderApi) {
+          continue;
+        }
+
+        // If a companion .njk file exists, this .js is a data loader for mountPages, not a standalone definePage route
+        const companionNjk = absolutePath.replace(/\.js$/, '.njk');
+        if (filesSet.has(companionNjk)) {
+          continue;
+        }
+
+        // Parse as standalone page route
+        const parsed = parseFileRoute(relativePath, {
+          type: 'page',
+          prefix: pagesPrefix,
+        });
+        if (parsed.isValid) {
+          descriptors.push({
+            type: 'page',
+            method: parsed.method,
+            path: parsed.path,
+            file: absolutePath,
+            source: path.relative(rootDir, absolutePath),
+            module: null,
+          });
+        }
+      }
+    }
+  }
+
+  // 2. Scan Global API (e.g. src/api or api)
+  const apiOpt = options.api;
+  if (apiOpt !== false) {
+    const explicitApiDir = typeof apiOpt === 'object' && apiOpt.dir ? apiOpt.dir : null;
+    const apiPrefix = typeof apiOpt === 'object' && apiOpt.prefix ? apiOpt.prefix : '/api';
+    const apiDir = explicitApiDir
+      ? (path.isAbsolute(explicitApiDir) ? explicitApiDir : path.join(rootDir, explicitApiDir))
+      : resolveDirCandidate(['src/api', 'api']);
+
+    if (apiDir && fs.existsSync(apiDir)) {
+      const files = scanDirSafely(apiDir);
+      for (const { absolutePath, relativePath } of files) {
+        const parsed = parseFileRoute(relativePath, {
+          type: 'api',
+          prefix: apiPrefix,
+        });
+        if (parsed.isValid) {
+          descriptors.push({
+            type: 'api',
+            method: parsed.method,
+            path: parsed.path,
+            file: absolutePath,
+            source: path.relative(rootDir, absolutePath),
+            module: null,
+          });
+        }
+      }
+    }
+  }
+
+  // 3. Scan Modules (e.g. src/modules or modules)
+  const modulesOpt = options.modules;
+  if (modulesOpt !== false) {
+    const explicitModulesDir = typeof modulesOpt === 'object' && modulesOpt.dir ? modulesOpt.dir : null;
+    const modulesDir = explicitModulesDir
+      ? (path.isAbsolute(explicitModulesDir) ? explicitModulesDir : path.join(rootDir, explicitModulesDir))
+      : resolveDirCandidate(['src/modules', 'modules']);
+
+    if (modulesDir && fs.existsSync(modulesDir)) {
+      const entries = fs.readdirSync(modulesDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory() || isPrivateOrIgnored(entry.name)) continue;
+
+        const moduleName = entry.name;
+        const modulePath = path.join(modulesDir, moduleName);
+
+        const details = discoverModuleDetails(modulePath, moduleName);
+        const moduleConfig = Object.assign({}, details.config, {
+          middlewares: details.middlewares,
+          services: details.services,
+        });
+
+        // Module Pages
+        const modPagesConfig = moduleConfig?.pages;
+        if (modPagesConfig !== false) {
+          const modPagesDirName = typeof modPagesConfig === 'object' && modPagesConfig.dir ? modPagesConfig.dir : 'pages';
+          const modPagesPrefix = typeof modPagesConfig === 'object' && modPagesConfig.prefix !== undefined
+            ? modPagesConfig.prefix
+            : `/${moduleName}`;
+          const modPagesDir = path.isAbsolute(modPagesDirName)
+            ? modPagesDirName
+            : path.join(modulePath, modPagesDirName);
+
+          if (fs.existsSync(modPagesDir)) {
+            const files = scanDirSafely(modPagesDir);
+            const modFilesSet = new Set(files.map((f) => f.absolutePath));
+
+            for (const { absolutePath, relativePath } of files) {
+              if (!relativePath.endsWith('.js')) continue;
+              if (modFilesSet.has(absolutePath.replace(/\.js$/, '.njk'))) continue;
+
+              const parsed = parseFileRoute(relativePath, {
+                type: 'page',
+                prefix: modPagesPrefix,
+              });
+              if (parsed.isValid) {
+                descriptors.push({
+                  type: 'page',
+                  method: parsed.method,
+                  path: parsed.path,
+                  file: absolutePath,
+                  source: path.relative(rootDir, absolutePath),
+                  module: moduleName,
+                  moduleConfig,
+                });
+              }
+            }
+          }
+        }
+
+        // Module API
+        const modApiConfig = moduleConfig?.api;
+        if (modApiConfig !== false) {
+          const modApiDirName = typeof modApiConfig === 'object' && modApiConfig.dir ? modApiConfig.dir : 'api';
+          const modApiPrefix = typeof modApiConfig === 'object' && modApiConfig.prefix !== undefined
+            ? modApiConfig.prefix
+            : `/api/${moduleName}`;
+          const modApiDir = path.isAbsolute(modApiDirName)
+            ? modApiDirName
+            : path.join(modulePath, modApiDirName);
+
+          if (fs.existsSync(modApiDir)) {
+            const files = scanDirSafely(modApiDir);
+            for (const { absolutePath, relativePath } of files) {
+              const parsed = parseFileRoute(relativePath, {
+                type: 'api',
+                prefix: modApiPrefix,
+              });
+              if (parsed.isValid) {
+                descriptors.push({
+                  type: 'api',
+                  method: parsed.method,
+                  path: parsed.path,
+                  file: absolutePath,
+                  source: path.relative(rootDir, absolutePath),
+                  module: moduleName,
+                  moduleConfig,
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return descriptors;
+}
+
+module.exports = {
+  scanRoutes,
+  scanDirSafely,
+};

package/src/file-router.js

@@ -1026,6 +1026,9 @@ function mountPages(app, options) {
   /** Register API routes (shared by static phase and dynamic phase). */
   const registerApiRoutes = (routes) => {
     for (const route of routes) {
+      if (options.skipExistingRoutes && options.skipExistingRoutes.has(route.method || 'GET', route.routePath)) {
+        continue;
+      }
       const handler = require(route.fullPath);
       const handlerFn = typeof handler === 'function' ? handler : handler.default || handler.handler;
       const routeMiddleware = handler.middleware;
@@ -1134,6 +1137,9 @@ function mountPages(app, options) {
   /** Register SSR GET routes (shared by static phase and dynamic phase). */
   const registerSsrRoutes = (routes) => {
     for (const route of routes) {
+      if (options.skipExistingRoutes && options.skipExistingRoutes.has('GET', route.routePath)) {
+        continue;
+      }
       const mountConfig = loadRouteConfig(route.configPath, isDev);
       const preResolvedPageMw = mountConfig?.middleware
         ? resolveMiddlewares(mountConfig.middleware, middlewares)

package/src/modules/define-module.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Webspresso Module Definition Helper
+ * Creates feature-oriented modules compatible with Webspresso PluginManager
+ * @module src/modules/define-module
+ */
+
+/**
+ * Defines a feature module with pages, api, services, middlewares, and lifecycle hooks
+ * @param {Object} config
+ * @param {string} config.name - Module unique name (e.g. 'auth', 'shop')
+ * @param {string} [config.version='1.0.0'] - Module version
+ * @param {string} [config.description] - Module description
+ * @param {Array<string>} [config.imports] - Dependent module names
+ * @param {Array<string>} [config.dependencies] - Alias for imports
+ * @param {boolean|Object} [config.pages] - Pages configuration ({ dir, prefix })
+ * @param {boolean|Object} [config.api] - API configuration ({ dir, prefix })
+ * @param {Object} [config.services] - Registered service definitions
+ * @param {Object} [config.middlewares] - Module-local named middleware functions
+ * @param {Object} [config.exports] - Public API methods
+ * @param {Object} [config.api] - Public API alias
+ * @param {Function} [config.onInit] - Initialization lifecycle hook
+ * @param {Function} [config.onDestroy] - Destruction lifecycle hook
+ * @returns {Function} Module factory function returning a Webspresso plugin object
+ */
+function defineModule(config = {}) {
+  const {
+    name,
+    version = '1.0.0',
+    description = '',
+    imports = [],
+    dependencies = [],
+    pages,
+    api: apiConfig,
+    services = {},
+    middlewares = {},
+    exports: publicExports = {},
+    onInit,
+    onDestroy,
+  } = config;
+
+  if (!name || typeof name !== 'string' || !name.trim()) {
+    throw new Error('defineModule requires a valid non-empty "name" string');
+  }
+
+  const combinedDeps = Array.from(new Set([...(imports || []), ...(dependencies || [])]));
+
+  return function moduleFactory(userOptions = {}) {
+    return {
+      name,
+      version,
+      description,
+      dependencies: combinedDeps,
+      __isWebspressoModule: true,
+      moduleConfig: {
+        ...config,
+        ...userOptions,
+      },
+      api: typeof publicExports === 'object' && publicExports !== null ? publicExports : {},
+
+      register(ctx) {
+        // 1. Register module services into serviceRegistry
+        if (ctx.app && ctx.app.serviceRegistry && services && typeof services === 'object') {
+          for (const [sName, sDef] of Object.entries(services)) {
+            const qualifiedName = sName.includes('.') ? sName : `${name}.${sName}`;
+            if (!ctx.app.serviceRegistry.has(qualifiedName)) {
+              ctx.app.serviceRegistry.register(qualifiedName, sDef);
+            }
+          }
+        }
+
+        // 2. Register module-local middlewares into context
+        if (ctx.middlewares && middlewares && typeof middlewares === 'object') {
+          for (const [mwName, mwFn] of Object.entries(middlewares)) {
+            // Register with module prefix as well
+            ctx.middlewares[`${name}.${mwName}`] = mwFn;
+          }
+        }
+
+        // 3. Run onInit lifecycle hook if provided
+        if (typeof onInit === 'function') {
+          onInit(ctx);
+        }
+
+        // 4. Register onDestroy hook with ShutdownManager if provided
+        if (typeof onDestroy === 'function' && ctx.shutdownManager) {
+          ctx.shutdownManager.registerDisposer(onDestroy, {
+            name: `module:${name}`,
+          });
+        }
+      },
+    };
+  };
+}
+
+module.exports = {
+  defineModule,
+};

package/src/modules/module-discovery.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * Webspresso Module Discovery Utilities
+ * Auto-discovers services and middlewares within feature module directories
+ * @module src/modules/module-discovery
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { scanDirSafely, isPrivateOrIgnored } = require('../discovery/file-route-parser');
+
+/**
+ * Converts a file path to camelCase or dot-separated identifier
+ * @param {string} str
+ * @returns {string}
+ */
+function toCamelCase(str) {
+  return str.replace(/[-_](\w)/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Discovers services, middlewares, and configuration for a module directory
+ * @param {string} modulePath - Absolute path to module folder (e.g. /app/modules/auth)
+ * @param {string} moduleName - Name of the module (e.g. 'auth')
+ * @returns {{ services: Record<string, any>, middlewares: Record<string, Function>, config: Object|null }}
+ */
+function discoverModuleDetails(modulePath, moduleName) {
+  const discovered = {
+    services: {},
+    middlewares: {},
+    config: null,
+  };
+
+  if (!fs.existsSync(modulePath)) return discovered;
+
+  // 1. Check for module configuration file
+  const configCandidates = [
+    path.join(modulePath, `${moduleName}.module.js`),
+    path.join(modulePath, 'module.js'),
+    path.join(modulePath, 'index.js'),
+  ];
+  for (const cf of configCandidates) {
+    if (fs.existsSync(cf)) {
+      try {
+        const loaded = require(cf);
+        const evaluated = typeof loaded === 'function' ? loaded() : loaded;
+        discovered.config = evaluated && evaluated.moduleConfig ? evaluated.moduleConfig : evaluated;
+      } catch (err) {
+        console.warn(`[webspresso] Error loading module config ${cf}:`, err.message);
+      }
+      break;
+    }
+  }
+
+  // 2. Discover Services in modules/{name}/services/
+  const servicesDir = path.join(modulePath, 'services');
+  if (fs.existsSync(servicesDir)) {
+    const serviceFiles = scanDirSafely(servicesDir);
+    for (const { absolutePath, relativePath } of serviceFiles) {
+      if (!relativePath.endsWith('.js')) continue;
+      const baseName = relativePath.slice(0, -3).split(path.sep).join('.');
+      const qualifiedName = `${moduleName}.${baseName}`;
+      try {
+        const serviceModule = require(absolutePath);
+        const serviceDef = serviceModule.default || serviceModule;
+        discovered.services[qualifiedName] = serviceDef;
+
+        // Also add camelCase alias if hyphenated
+        const camelAlias = `${moduleName}.${toCamelCase(baseName)}`;
+        if (camelAlias !== qualifiedName) {
+          discovered.services[camelAlias] = serviceDef;
+        }
+      } catch (err) {
+        console.warn(`[webspresso] Error loading module service ${absolutePath}:`, err.message);
+      }
+    }
+  }
+
+  // 3. Discover Middlewares in modules/{name}/middleware/ or middlewares/
+  const mwDirs = [path.join(modulePath, 'middleware'), path.join(modulePath, 'middlewares')];
+  for (const mwDir of mwDirs) {
+    if (fs.existsSync(mwDir)) {
+      const mwFiles = scanDirSafely(mwDir);
+      for (const { absolutePath, relativePath } of mwFiles) {
+        if (!relativePath.endsWith('.js')) continue;
+        const rawName = path.basename(relativePath, '.js');
+        try {
+          const mwModule = require(absolutePath);
+          const mwFn = mwModule.default || mwModule;
+          if (typeof mwFn === 'function') {
+            discovered.middlewares[rawName] = mwFn;
+            discovered.middlewares[toCamelCase(rawName)] = mwFn;
+          }
+        } catch (err) {
+          console.warn(`[webspresso] Error loading module middleware ${absolutePath}:`, err.message);
+        }
+      }
+    }
+  }
+
+  // Merge explicitly defined middlewares from module config
+  if (discovered.config?.middlewares && typeof discovered.config.middlewares === 'object') {
+    Object.assign(discovered.middlewares, discovered.config.middlewares);
+  }
+
+  // Merge explicitly defined services from module config
+  if (discovered.config?.services && typeof discovered.config.services === 'object') {
+    Object.assign(discovered.services, discovered.config.services);
+  }
+
+  return discovered;
+}
+
+module.exports = {
+  discoverModuleDetails,
+};