webspresso 0.0.95 → 0.0.97

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

@@ -753,7 +753,9 @@ function detectLocale(req) {
     }
   }
 
-  const acceptLanguage = req.get('Accept-Language');
+  const acceptLanguage = typeof req.get === 'function'
+    ? req.get('Accept-Language')
+    : (req.headers && (req.headers['accept-language'] || req.headers['Accept-Language']));
   if (acceptLanguage) {
     const langPart = acceptLanguage.split(',')[0];
     const a = normalizeLocaleCandidate(langPart);
@@ -1026,6 +1028,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 +1139,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,
+};

package/src/pages/define-page.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Webspresso Page Definition Helper
+ * @module src/pages/define-page
+ */
+
+/**
+ * Defines a page route with load, head, and render lifecycle methods
+ * @param {Object} config
+ * @param {Array<string|Function>} [config.middleware] - Route-level middleware names or functions
+ * @param {Function} [config.load] - Async server data loader: async (ctx) => data
+ * @param {Function} [config.head] - Dynamic head metadata: (data, ctx) => ({ title, meta, ... })
+ * @param {Function} [config.render] - Component renderer (used for pure JS pages): (data, ctx) => string|Promise<string>
+ * @param {string|boolean} [config.layout] - Layout override
+ * @param {Object} [config.hooks] - Page lifecycle hooks
+ * @returns {Object}
+ */
+function definePage(config = {}) {
+  if (typeof config === 'function') {
+    // If a loader function is passed directly
+    return {
+      load: config,
+      __isWebspressoPage: true,
+    };
+  }
+
+  return {
+    ...config,
+    __isWebspressoPage: true,
+  };
+}
+
+module.exports = {
+  definePage,
+};