webspresso 0.0.101 → 0.0.102

package/src/file-router.js

@@ -5,9 +5,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { ZodError } = require('zod');
 const { compileSchema, invalidateSchema } = require('../core/compileSchema');
 const { applySchema } = require('../core/applySchema');
+const { translateValidationIssues, getTranslatorForRequest } = require('./api/validation-i18n');
 const { createHelpers, getAssetManager } = require('./helpers');
 const {
   loadNjkRouteTemplate,
@@ -494,15 +494,15 @@ function routeRegistrationMeta(routePath) {
  * @param {{ routePath: string }} b
  */
 function compareRouteRegistrationOrder(a, b) {
-  const ma = routeRegistrationMeta(a.routePath);
-  const mb = routeRegistrationMeta(b.routePath);
+  const ma = a._regMeta || (a._regMeta = routeRegistrationMeta(a.routePath));
+  const mb = b._regMeta || (b._regMeta = routeRegistrationMeta(b.routePath));
   if (ma.tier !== mb.tier) return ma.tier - mb.tier;
   if (ma.literalSegCount !== mb.literalSegCount) {
     return mb.literalSegCount - ma.literalSegCount;
   }
   if (ma.depth !== mb.depth) return mb.depth - ma.depth;
   if (ma.paramSegCount !== mb.paramSegCount) return ma.paramSegCount - mb.paramSegCount;
-  return ma.routePath.localeCompare(mb.routePath);
+  return ma.routePath < mb.routePath ? -1 : (ma.routePath > mb.routePath ? 1 : 0);
 }
 
 /**
@@ -1133,86 +1133,92 @@ function mountPages(app, options) {
   // Get absolute path to pages directory
   const absolutePagesDir = path.resolve(pagesDir);
 
-  // Routing and file-system checks at startup
-  function checkRoutesAtStartup() {
-    function getGenericSegment(name) {
-      if (name.startsWith('[') && name.endsWith(']')) {
-        const inner = name.slice(1, -1);
-        if (inner.startsWith('...')) return '*';
-        return ':param';
-      }
-      return name;
+  // Single-pass directory scanner with startup collision & case-sensitivity checks (0 statSync calls)
+  function getGenericSegment(name) {
+    if (name.startsWith('[') && name.endsWith(']')) {
+      const inner = name.slice(1, -1);
+      if (inner.startsWith('...')) return '*';
+      return ':param';
     }
+    return name;
+  }
 
-    function checkDir(dirPath, relativeDir = '', isApi = false) {
-      if (!fs.existsSync(dirPath)) return;
-      const children = fs.readdirSync(dirPath);
-      const kept = [];
-
-      for (const child of children) {
-        if (child.startsWith('_') || child === 'locales') continue;
-        const fullPath = path.join(dirPath, child);
-        const relPath = relativeDir ? path.join(relativeDir, child) : child;
-        const stats = fs.statSync(fullPath);
+  function scanAndCheckDir(dirPath, relativeDir = '', isApi = false) {
+    if (!fs.existsSync(dirPath)) return [];
+    let children;
+    try {
+      children = fs.readdirSync(dirPath, { withFileTypes: true });
+    } catch (_) {
+      return [];
+    }
+    const kept = [];
+    const files = [];
+
+    for (const entry of children) {
+      const child = entry.name;
+      if (child.startsWith('_') || child === 'locales') continue;
+      const fullPath = path.join(dirPath, child);
+      const relPath = relativeDir ? path.join(relativeDir, child) : child;
+
+      // 1. Check case-sensitivity issues
+      if (child !== child.toLowerCase()) {
+        console.warn(`[webspresso] WARNING: Path "pages/${relPath.split(path.sep).join('/')}" contains uppercase letters. Use lowercase to avoid routing issues on case-sensitive filesystems.`);
+      }
 
-        // 1. Check case-sensitivity issues
-        if (child !== child.toLowerCase()) {
-          console.warn(`[webspresso] WARNING: Path "pages/${relPath.split(path.sep).join('/')}" contains uppercase letters. Use lowercase to avoid routing issues on case-sensitive filesystems.`);
+      if (entry.isDirectory()) {
+        if (child === 'api' && relativeDir === '') {
+          files.push(...scanAndCheckDir(fullPath, relPath, true));
+        } else {
+          files.push(...scanAndCheckDir(fullPath, relPath, isApi));
+          if (!isApi) {
+            kept.push({ name: child, isDir: true, original: child });
+          }
         }
-
-        if (stats.isDirectory()) {
-          if (child === 'api' && relativeDir === '') {
-            checkDir(fullPath, relPath, true);
-          } else {
-            checkDir(fullPath, relPath, isApi);
-            if (!isApi) {
-              kept.push({ name: child, isDir: true, original: child });
-            }
+      } else if (entry.isFile()) {
+        files.push(relPath);
+        const ext = path.extname(child);
+        if (isApi) {
+          if (ext === '.js') {
+            const base = path.basename(child, ext);
+            kept.push({ name: base, isDir: false, original: child });
           }
         } else {
-          const ext = path.extname(child);
-          if (isApi) {
-            if (ext === '.js') {
-              const base = path.basename(child, ext);
-              kept.push({ name: base, isDir: false, original: child });
-            }
-          } else {
-            if (ext === '.njk') {
-              const base = path.basename(child, ext);
-              kept.push({ name: base, isDir: false, original: child });
-            }
+          if (ext === '.njk') {
+            const base = path.basename(child, ext);
+            kept.push({ name: base, isDir: false, original: child });
           }
         }
       }
+    }
 
-      // 2. Check dynamic route collisions
-      const groups = new Map();
-      for (const item of kept) {
-        const normalized = getGenericSegment(item.name);
-        if (!groups.has(normalized)) {
-          groups.set(normalized, []);
-        }
-        groups.get(normalized).push(item);
+    // 2. Check dynamic route collisions
+    const groups = new Map();
+    for (const item of kept) {
+      const normalized = getGenericSegment(item.name);
+      if (!groups.has(normalized)) {
+        groups.set(normalized, []);
       }
+      groups.get(normalized).push(item);
+    }
 
-      for (const [norm, items] of groups.entries()) {
-        if (items.length > 1) {
-          const namesList = items.map(item => `"${item.original}"`).join(' and ');
-          console.warn(`[webspresso] WARNING: Dynamic route collision in "pages/${relativeDir.split(path.sep).join('/')}": ${namesList} resolve to the same segment "${norm}" and will conflict at runtime.`);
-        }
+    for (const [norm, items] of groups.entries()) {
+      if (items.length > 1) {
+        const namesList = items.map(item => `"${item.original}"`).join(' and ');
+        console.warn(`[webspresso] WARNING: Dynamic route collision in "pages/${relativeDir.split(path.sep).join('/')}": ${namesList} resolve to the same segment "${norm}" and will conflict at runtime.`);
       }
     }
 
-    checkDir(absolutePagesDir, '');
+    return files;
   }
 
-  checkRoutesAtStartup();
-  
   // Load global hooks
   const globalHooks = loadGlobalHooks(absolutePagesDir, isDev);
   
-  // Scan for files
-  const files = scanDirectory(absolutePagesDir);
+  // Single-pass scan for files and checks (bypassed if pre-scanned files provided by discovery phase)
+  const files = (Array.isArray(options.scannedFiles) && options.scannedFiles.length >= 0)
+    ? options.scannedFiles
+    : scanAndCheckDir(absolutePagesDir, '');
+  const filesSet = new Set(files);
   
   // Separate SSR pages and API routes
   const ssrRoutes = [];
@@ -1239,7 +1245,9 @@ function mountPages(app, options) {
     } else if (ext === '.njk') {
       // SSR page
       const routePath = filePathToRoute(file, '.njk');
-      const configPath = path.join(absolutePagesDir, file.replace('.njk', '.js'));
+      const configRel = file.replace(/\.njk$/, '.js');
+      const hasCompanionConfig = filesSet.has(configRel);
+      const configPath = path.join(absolutePagesDir, configRel);
       const routeDir = path.dirname(path.join(absolutePagesDir, file));
       
       ssrRoutes.push({
@@ -1247,6 +1255,7 @@ function mountPages(app, options) {
         routePath,
         fullPath: path.join(absolutePagesDir, file),
         configPath,
+        hasCompanionConfig,
         routeDir
       });
     }
@@ -1280,21 +1289,27 @@ function mountPages(app, options) {
       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;
-
-      const preResolvedMw = routeMiddleware
-        ? resolveMiddlewares(routeMiddleware, middlewares)
-        : EMPTY_ARRAY;
-    
-      if (typeof handlerFn !== 'function') {
-        console.warn(`API route ${route.file} does not export a function`);
-        continue;
-      }
-
+      let handlerFn = null;
+      let preResolvedMw = null;
       let preCompiledSchema = null;
+
+      // In production, eager-load to compile schemas & fail fast at startup
       if (!isDev) {
+        let handler;
+        try {
+          handler = require(route.fullPath);
+        } catch (loadErr) {
+          console.error(`Failed to load API route ${route.file}:`, loadErr);
+          continue;
+        }
+        handlerFn = typeof handler === 'function' ? handler : handler.default || handler.handler;
+        if (typeof handlerFn !== 'function') {
+          console.warn(`API route ${route.file} does not export a function`);
+          continue;
+        }
+        preResolvedMw = handler.middleware
+          ? resolveMiddlewares(handler.middleware, middlewares)
+          : EMPTY_ARRAY;
         try {
           preCompiledSchema = compileSchema(route.fullPath, handler);
         } catch (schemaErr) {
@@ -1329,11 +1344,29 @@ function mountPages(app, options) {
             if (require.cache[require.resolve(route.fullPath)]) {
               delete require.cache[require.resolve(route.fullPath)];
             }
-            const currentHandler = require(route.fullPath);
+            let currentHandler;
+            try {
+              currentHandler = require(route.fullPath);
+            } catch (err) {
+              console.error(`Failed to load API route ${route.file}:`, err);
+              return res.status(500).json({ error: 'Internal Server Error', message: `Failed to load API route: ${err.message}` });
+            }
             fn = typeof currentHandler === 'function' 
               ? currentHandler 
               : currentHandler.default || currentHandler.handler;
 
+            if (typeof fn !== 'function') {
+              console.warn(`API route ${route.file} does not export a function`);
+              return res.status(500).json({ error: 'Internal Server Error', message: `Route ${route.file} does not export a valid handler function` });
+            }
+
+            // Stateful middlewares (e.g. rate limiters) must be resolved once and preserved across requests
+            if (preResolvedMw === null) {
+              preResolvedMw = currentHandler.middleware
+                ? resolveMiddlewares(currentHandler.middleware, middlewares)
+                : EMPTY_ARRAY;
+            }
+
             invalidateSchema(route.fullPath);
             try {
               compiledSchema = compileSchema(route.fullPath, currentHandler);
@@ -1344,13 +1377,21 @@ function mountPages(app, options) {
             }
           }
 
+          const routeMw = preResolvedMw || EMPTY_ARRAY;
+
           try {
             applySchema(req, compiledSchema);
           } catch (err) {
-            if (err instanceof ZodError) {
+            if (err && (err.name === 'ZodError' || Array.isArray(err.issues))) {
+              const translatedIssues = translateValidationIssues(err.issues, {
+                req,
+                pagesDir: absolutePagesDir,
+                routeDir: route.routeDir || (route.fullPath ? path.dirname(route.fullPath) : ''),
+                isDev,
+              });
               return res.status(400).json({
                 error: 'Validation Error',
-                issues: err.issues,
+                issues: translatedIssues,
               });
             }
             throw err;
@@ -1363,11 +1404,18 @@ function mountPages(app, options) {
             if (res.headersSent) return;
           }
 
-          // Run middleware if defined (resolved at route registration — required for stateful middleware like express-rate-limit)
-          if (preResolvedMw.length) {
-            await runMiddlewareChain(preResolvedMw, req, res);
+          // Run middleware if defined
+          if (routeMw.length) {
+            await runMiddlewareChain(routeMw, req, res);
             if (res.headersSent) return;
           }
+
+          const tr = getTranslatorForRequest(req, {
+            pagesDir: absolutePagesDir,
+            routeDir: route.routeDir || (route.fullPath ? path.dirname(route.fullPath) : ''),
+            isDev,
+          });
+
           const apiCtx = Object.assign((err) => next(err), {
             req,
             res,
@@ -1376,6 +1424,8 @@ function mountPages(app, options) {
             query: req.query || {},
             body: req.body || {},
             input: req.input,
+            locale: tr.locale,
+            t: tr.t,
             service: req.service,
             db,
             sse: res.sse,
@@ -1404,10 +1454,12 @@ function mountPages(app, options) {
       if (options.skipExistingRoutes && options.skipExistingRoutes.has('GET', route.routePath)) {
         continue;
       }
-      const mountConfig = loadRouteConfig(route.configPath, isDev);
-      const preResolvedPageMw = mountConfig?.middleware
+      const mountConfig = (!isDev && route.hasCompanionConfig)
+        ? loadRouteConfig(route.configPath, false)
+        : null;
+      let preResolvedPageMw = mountConfig?.middleware
         ? resolveMiddlewares(mountConfig.middleware, middlewares)
-        : EMPTY_ARRAY;
+        : (!isDev ? EMPTY_ARRAY : null);
       const staticRouteHooks = mountConfig?.hooks || EMPTY_OBJECT;
 
       app.get(route.routePath, async (req, res, next) => {
@@ -1455,8 +1507,16 @@ function mountPages(app, options) {
           }
           
           // Load route config
-          const config = isDev ? loadRouteConfig(route.configPath, true) : mountConfig;
+          const config = isDev
+            ? (route.hasCompanionConfig ? loadRouteConfig(route.configPath, true) : null)
+            : mountConfig;
           const routeHooks = isDev ? (config?.hooks || EMPTY_OBJECT) : staticRouteHooks;
+          if (preResolvedPageMw === null) {
+            preResolvedPageMw = config?.middleware
+              ? resolveMiddlewares(config.middleware, middlewares)
+              : EMPTY_ARRAY;
+          }
+          const pageMw = preResolvedPageMw;
         
         // Create context with plugin helpers merged
         const baseHelpers = createHelpers({ req, res, locale, t });
@@ -1521,9 +1581,9 @@ function mountPages(app, options) {
           if (res.headersSent) return;
         }
 
-        // Run route middleware (chain fixed at route registration; edit middleware in dev → restart)
-        if (preResolvedPageMw.length) {
-          await runMiddlewareChain(preResolvedPageMw, req, res);
+        // Run route middleware
+        if (pageMw.length) {
+          await runMiddlewareChain(pageMw, req, res);
           if (res.headersSent) return;
         }
         
@@ -1758,5 +1818,7 @@ module.exports = {
   clearCompiledStringTemplateCache,
   translatorCache,
   clearTranslatorCache,
+  translateValidationIssues,
+  getTranslatorForRequest,
 };
 

package/src/njk-frontmatter.js

@@ -4,7 +4,14 @@
  */
 
 const fs = require('fs');
-const { parse } = require('yaml');
+
+let _yamlParse = null;
+function getYamlParse() {
+  if (!_yamlParse) {
+    _yamlParse = require('yaml').parse;
+  }
+  return _yamlParse;
+}
 
 const FRONTMATTER_BLOCK = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
 
@@ -43,6 +50,7 @@ function parseNjkFrontmatter(content) {
     return { body, fm: {}, hasDelimiter: true };
   }
   try {
+    const parse = getYamlParse();
     const fm = parse(yamlText);
     return {
       body,
@@ -171,6 +179,13 @@ function clearNjkFrontmatterCaches() {
   }
 }
 
+function seedProdRouteCache(entries) {
+  if (!entries || typeof entries !== 'object') return;
+  for (const [absPath, val] of Object.entries(entries)) {
+    prodRouteCache.set(absPath, val);
+  }
+}
+
 module.exports = {
   parseNjkFrontmatter,
   frontmatterToPatches,
@@ -178,4 +193,5 @@ module.exports = {
   clearNjkFrontmatterCaches,
   registerClearHook,
   extractFrontmatterBlock,
+  seedProdRouteCache,
 };

package/src/plugin-manager.js

@@ -669,6 +669,18 @@ class PluginManager {
    * Get a plugin's API by name
    */
   getPluginAPI(name) {
+    const plugin = this.plugins.get(name);
+    if (plugin && plugin.isLazy && typeof plugin.hydrate === 'function' && !plugin.isHydrated) {
+      const real = plugin.hydrate();
+      if (real && real.api) {
+        const boundAPI = {};
+        for (const [key, value] of Object.entries(real.api)) {
+          boundAPI[key] = typeof value === 'function' ? value.bind(real) : value;
+        }
+        this.pluginAPIs.set(name, boundAPI);
+      }
+      return this.pluginAPIs.get(name) || (real && real.api) || plugin.api;
+    }
     return this.pluginAPIs.get(name);
   }
 

package/src/routing/route-table.js

@@ -63,7 +63,7 @@ function compareRouteOrder(a, b) {
   if (ma.literalSegCount !== mb.literalSegCount) return mb.literalSegCount - ma.literalSegCount;
   if (ma.depth !== mb.depth) return mb.depth - ma.depth;
   if (ma.paramSegCount !== mb.paramSegCount) return ma.paramSegCount - mb.paramSegCount;
-  return ma.routePath.localeCompare(mb.routePath);
+  return ma.routePath < mb.routePath ? -1 : (ma.routePath > mb.routePath ? 1 : 0);
 }
 
 /**

package/src/server.js

@@ -24,6 +24,8 @@ const { registerClearHook } = require('./njk-frontmatter');
 const { createPluginManager } = require('./plugin-manager');
 const { createServiceRegistry } = require('./services');
 const { scanRoutes } = require('./discovery/scan-routes');
+const { loadRouteManifest } = require('./discovery/route-manifest');
+const { loadPrecompiledTemplates } = require('./template/precompile');
 const { compileRouteTable } = require('./routing/route-table');
 const { mountDiscoveredRoutes } = require('./routing/mount-discovered-routes');
 const { discoverModuleDetails } = require('./modules/module-discovery');
@@ -106,6 +108,13 @@ function canonicalTemplateKey(name) {
 
 function configureSafeNunjucks(templateDirs, options = {}) {
   const env = nunjucks.configure(templateDirs, options);
+  if (options.precompiledLoader && Array.isArray(env.loaders)) {
+    options.precompiledLoader.cache = options.precompiledLoader.cache || {};
+    env.loaders.unshift(options.precompiledLoader);
+    if (typeof env._initLoaders === 'function') {
+      env._initLoaders();
+    }
+  }
   const origGetTemplate = env.getTemplate.bind(env);
   const origRender = env.render.bind(env);
   const origRenderString = env.renderString.bind(env);
@@ -699,6 +708,7 @@ function createApp(options = {}) {
   
   const app = express();
   app.serviceRegistry = serviceRegistry;
+  app.pluginManager = pluginManager;
   app.events = eventDispatcher;
   if (options.queue) {
     app.queue = options.queue;
@@ -1286,12 +1296,29 @@ function createApp(options = {}) {
     templateDirs.push(path.join(rootDir, 'pages'));
   }
   
+  // Load precompiled Nunjucks templates if enabled or available
+  let precompiledResult = null;
+  const usePrecompiled = options.precompiledTemplates === true ||
+    (typeof options.precompiledTemplates === 'string') ||
+    (options.precompiledTemplates !== false && !isDev);
+
+  if (usePrecompiled) {
+    precompiledResult = loadPrecompiledTemplates({
+      rootDir,
+      bundlePath: typeof options.precompiledTemplates === 'string' ? options.precompiledTemplates : undefined,
+    });
+    if (precompiledResult) {
+      app.precompiledTemplates = precompiledResult.bundle;
+    }
+  }
+
   const nunjucksOpts = options.nunjucks || {};
   const nunjucksEnv = configureSafeNunjucks(templateDirs, {
     autoescape: true,
     express: app,
     watch: isDev && !isTest,
     noCache: nunjucksOpts.noCache ?? (isDev || isTest),
+    precompiledLoader: precompiledResult ? precompiledResult.loader : null,
     ...nunjucksOpts,
   });
 
@@ -1381,13 +1408,35 @@ function createApp(options = {}) {
     app.use(profilerMiddleware);
   }
   
-  // 1. Scan and compile discovered routes (src/pages, src/api, modules/*)
-  const discoveredDescriptors = scanRoutes({
-    rootDir,
-    pages: options.pages !== undefined ? options.pages : (options.pagesDir ? { dir: options.pagesDir } : true),
-    api: options.api,
-    modules: options.modules,
-  });
+  // 1. Scan and compile discovered routes (AOT route manifest or disk scan)
+  let discoveredDescriptors = null;
+  let loadedManifest = null;
+
+  // In production (or when explicitly requested/enabled via options.routesManifest), attempt loading AOT manifest
+  const useManifest = options.routesManifest === true ||
+    (typeof options.routesManifest === 'string') ||
+    (options.routesManifest !== false && !isDev);
+
+  if (useManifest) {
+    const manifestResult = loadRouteManifest({
+      rootDir,
+      manifestPath: typeof options.routesManifest === 'string' ? options.routesManifest : undefined,
+    });
+    if (manifestResult) {
+      discoveredDescriptors = manifestResult.descriptors;
+      loadedManifest = manifestResult.manifest;
+      app.routesManifest = loadedManifest;
+    }
+  }
+
+  if (!discoveredDescriptors) {
+    discoveredDescriptors = scanRoutes({
+      rootDir,
+      pages: options.pages !== undefined ? options.pages : (options.pagesDir ? { dir: options.pagesDir } : true),
+      api: options.api,
+      modules: options.modules,
+    });
+  }
 
   const routeTable = compileRouteTable(discoveredDescriptors, {
     explicitRoutes: options.routes || [],
@@ -1495,12 +1544,18 @@ function createApp(options = {}) {
     options,
   });
 
-  // 2. Mount classic file-based routes for backwards compatibility
+  // 2. Mount classic file-based routes for backwards compatibility (reuses pre-scanned files from discovery)
   let classicRouteMeta = [];
   let registerDynamicFileRoutes = () => {};
   if (pagesDir && fs.existsSync(path.resolve(pagesDir))) {
+    const resolvedPagesDir = path.resolve(pagesDir);
+    const scannedFiles = (discoveredDescriptors && discoveredDescriptors.scannedPagesDir === resolvedPagesDir)
+      ? discoveredDescriptors.scannedPagesFiles
+      : null;
+
     const classicMount = mountPages(app, {
       pagesDir,
+      scannedFiles,
       nunjucks: nunjucksEnv,
       middlewares,
       pluginManager,

package/src/services/builtins/system.js

@@ -4,8 +4,6 @@
  */
 
 const os = require('os');
-const { z } = require('zod');
-const { cleanExpiredTokens, createKnexAuthTokensAdapter } = require('../../../core/auth/tokens');
 
 /**
  * Format memory usage bytes into human-readable MB
@@ -29,7 +27,7 @@ function createSystemServices(options = {}) {
 
   return {
     'system.health': {
-      schema: z.object({
+      schema: ({ z }) => z.object({
         detailed: z.boolean().default(false),
       }),
       async handler(input, ctx) {
@@ -81,7 +79,7 @@ function createSystemServices(options = {}) {
     },
 
     'system.cleanup': {
-      schema: z.object({
+      schema: ({ z }) => z.object({
         olderThanDays: z.number().int().positive().default(90),
         purgeAuthTokens: z.boolean().default(true),
         purgeAuditLogs: z.boolean().default(true),
@@ -138,7 +136,7 @@ function createSystemServices(options = {}) {
     },
 
     'system.cache-flush': {
-      schema: z.object({
+      schema: ({ z }) => z.object({
         scope: z.enum(['all', 'orm', 'services']).default('all'),
         model: z.string().optional(),
       }),
@@ -182,7 +180,7 @@ function createSystemServices(options = {}) {
     },
 
     'system.info': {
-      schema: z.object({}),
+      schema: ({ z }) => z.object({}),
       auth: 'admin',
       async handler(input, ctx) {
         const activeDb = ctx.db || db;

package/src/services/registry.js

@@ -125,12 +125,12 @@ class ServiceRegistry {
    * @param {Object|Function} definition - Service definition or handler function
    * @returns {ServiceRegistry}
    */
-  register(name, definition) {
+  register(name, definition, options = {}) {
     if (!name || typeof name !== 'string') {
       throw new WebspressoError('Service name must be a non-empty string');
     }
 
-    if (this.services.has(name)) {
+    if (this.services.has(name) && !options.overwrite) {
       throw new ConfigurationError(`Duplicate service registered: ${name}`);
     }
 
@@ -170,6 +170,16 @@ class ServiceRegistry {
     return this;
   }
 
+  /**
+   * Unregister a service by name
+   * @param {string} name - Service name
+   * @returns {boolean} Whether service was found and removed
+   */
+  unregister(name) {
+    if (!name || typeof name !== 'string') return false;
+    return this.services.delete(name);
+  }
+
   /**
    * Get a service definition by name or alias
    * @param {string} name - Service name