@velajs/vela 1.2.0 → 1.4.0

package/dist/factory.js

@@ -1,39 +1,8 @@
 import { VelaApplication } from "./application.js";
-import { Container } from "./container/container.js";
-import { ModuleRef } from "./container/module-ref.js";
-import { bindAppProviders } from "./pipeline/app-providers.js";
-import { RouteManager } from "./http/route.manager.js";
-import { ModuleLoader } from "./module/module-loader.js";
-import { ComponentManager } from "./pipeline/component.manager.js";
+import { bootstrap } from "./factory/bootstrap.js";
 export const VelaFactory = {
     async create (rootModule, options = {}) {
-        const container = new Container();
-        container.register({
-            provide: Container,
-            useValue: container
-        });
-        container.register({
-            provide: ModuleRef,
-            useFactory: (c)=>new ModuleRef(c),
-            inject: [
-                Container
-            ]
-        });
-        const routeManager = new RouteManager(container, options);
-        ComponentManager.init(container);
-        const loader = new ModuleLoader(container, routeManager);
-        loader.load(rootModule);
-        bindAppProviders(routeManager, container, loader);
-        routeManager.registerConsumerMiddleware(loader.getConsumerMiddlewareDefinitions());
-        if (options.globalPrefix) {
-            routeManager.setGlobalPrefix(options.globalPrefix);
-        }
-        for (const handler of options.middleware ?? []){
-            const mw = {
-                use: handler
-            };
-            routeManager.useGlobalMiddleware(mw);
-        }
+        const { container, routeManager, loader } = await bootstrap(rootModule, options);
         const app = new VelaApplication(container, routeManager);
         const instances = await loader.resolveAllInstances();
         app.setInstances(instances);

package/dist/http/request-context.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from 'hono';
+import { InjectionToken } from '../container/types';
+export interface RequestContext {
+    readonly id: string;
+    readonly receivedAt: Date;
+    readonly request: Request;
+    readonly hono: Context;
+    set<T>(key: string | symbol, value: T): void;
+    get<T>(key: string | symbol): T | undefined;
+    has(key: string | symbol): boolean;
+}
+export declare const REQUEST_CONTEXT: InjectionToken<RequestContext>;
+export declare function createRequestContext(c: Context): RequestContext;

package/dist/http/request-context.js

@@ -0,0 +1,22 @@
+import { InjectionToken } from "../container/types.js";
+export const REQUEST_CONTEXT = new InjectionToken('vela.RequestContext');
+export function createRequestContext(c) {
+    const bag = new Map();
+    const inboundId = c.req.raw.headers.get('x-request-id');
+    const id = inboundId && inboundId.length > 0 ? inboundId : crypto.randomUUID();
+    return {
+        id,
+        receivedAt: new Date(),
+        request: c.req.raw,
+        hono: c,
+        set (key, value) {
+            bag.set(key, value);
+        },
+        get (key) {
+            return bag.get(key);
+        },
+        has (key) {
+            return bag.has(key);
+        }
+    };
+}

package/dist/http/route.manager.js

@@ -4,6 +4,7 @@ import { HttpMethod, ParamType } from "../constants.js";
 import { getMetadata } from "../metadata.js";
 import { joinPaths } from "../registry/paths.js";
 import { buildExecutionContext } from "./execution-context.js";
+import { REQUEST_CONTEXT, createRequestContext } from "./request-context.js";
 import { ForbiddenException, HttpException } from "../errors/http-exception.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
 import { shouldFilterCatch } from "../pipeline/decorators.js";
@@ -206,6 +207,7 @@ export class RouteManager {
             return existing;
         }
         const child = this.container.createChild();
+        child.setRequestInstance(REQUEST_CONTEXT, createRequestContext(c));
         c.set('container', child);
         return child;
     }

package/dist/index.d.ts

@@ -2,12 +2,16 @@ import './metadata';
 export { defineMetadata, getMetadata } from './metadata';
 export { VelaFactory } from './factory';
 export { VelaApplication } from './application';
+export { bootstrap } from './factory/bootstrap';
+export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema, } from './openapi/index';
 export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from './container/index';
-export type { Type, Token, InjectableOptions, ProviderOptions, } from './container/index';
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, mixin, } from './container/index';
+export type { Type, Token, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, } from './http/index';
+export { REQUEST_CONTEXT } from './http/request-context';
+export type { RequestContext } from './http/request-context';
 export { Logger, LogLevel } from './services/index';
 export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
 export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';
@@ -29,6 +33,8 @@ export type { ThrottlerModuleOptions, ThrottleConfig, ThrottlerStore, ThrottlerS
 export { Global, Module, createModuleRef } from './module/index';
 export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport } from './module/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
+export type { Plugin } from './plugin/plugin';
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, ReflectableDecorator, CreateDecoratorOptions, } from './pipeline/index';
 export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, } from './registry/index';

package/dist/index.js

@@ -3,14 +3,17 @@ export { defineMetadata, getMetadata } from "./metadata.js";
 // Factory & Application
 export { VelaFactory } from "./factory.js";
 export { VelaApplication } from "./application.js";
+export { bootstrap } from "./factory/bootstrap.js";
 // OpenAPI
 export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
-export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from "./container/index.js";
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, mixin } from "./container/index.js";
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators } from "./http/index.js";
+// Request-scoped context primitive
+export { REQUEST_CONTEXT } from "./http/request-context.js";
 // Services
 export { Logger, LogLevel } from "./services/index.js";
 // Config
@@ -31,6 +34,8 @@ export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthInd
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA } from "./throttler/index.js";
 // Module
 export { Global, Module, createModuleRef } from "./module/index.js";
+// Plugin manifest + composer
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
 // Built-in Pipes

package/dist/internal.d.ts

@@ -1,5 +1,7 @@
 export { Container } from './container/container';
 export { ModuleRef } from './container/module-ref';
+export { ModuleVisibilityError } from './container/types';
+export type { ModuleScope, ContainerOptions, Diagnostics, } from './container/types';
 export { bindAppProviders } from './pipeline/app-providers';
 export { RouteManager } from './http/route.manager';
 export type { RouteManagerOptions } from './http/route.manager';
@@ -9,3 +11,7 @@ export { VelaApplication } from './application';
 export { MetadataRegistry } from './registry/metadata.registry';
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/tokens';
 export { getModuleMetadata, isModule } from './module/decorators';
+export { bootstrap } from './factory/bootstrap';
+export type { BootstrapOptions, BootstrapResult } from './factory/bootstrap';
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
+export type { Plugin } from './plugin/plugin';

package/dist/internal.js

@@ -3,6 +3,7 @@
 // to the same degree as the public surface (./index).
 export { Container } from "./container/container.js";
 export { ModuleRef } from "./container/module-ref.js";
+export { ModuleVisibilityError } from "./container/types.js";
 export { bindAppProviders } from "./pipeline/app-providers.js";
 export { RouteManager } from "./http/route.manager.js";
 export { ModuleLoader } from "./module/module-loader.js";
@@ -11,3 +12,8 @@ export { VelaApplication } from "./application.js";
 export { MetadataRegistry } from "./registry/metadata.registry.js";
 export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/tokens.js";
 export { getModuleMetadata, isModule } from "./module/decorators.js";
+// Bootstrap primitive — used by VelaFactory.create, @velajs/testing, and any
+// non-HTTP consumer (CLI tools, custom runtimes).
+export { bootstrap } from "./factory/bootstrap.js";
+// Plugin manifest + composer
+export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";

package/dist/module/module-loader.d.ts

@@ -14,8 +14,11 @@ export declare class ModuleLoader {
     private consumerMiddlewareDefinitions;
     private appProviderCounter;
     private appProviderTokens;
+    private moduleIdByClass;
+    private seenModuleIds;
     constructor(container: Container, router: RouteManager);
     load(rootModule: Type): void;
+    private getModuleId;
     private processModule;
     private registerProvider;
     private isAppToken;
@@ -25,4 +28,5 @@ export declare class ModuleLoader {
     getAppProviderTokens(token: Token): Token[];
     getConsumerMiddlewareDefinitions(): MiddlewareRouteDefinition[];
     resolveAllInstances(): Promise<unknown[]>;
+    private routeError;
 }

package/dist/module/module-loader.js

@@ -1,5 +1,5 @@
 import { Scope } from "../constants.js";
-import { ForwardRef, InjectionToken } from "../container/types.js";
+import { ForwardRef, InjectionToken, ModuleVisibilityError } from "../container/types.js";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { getOrCreateArray } from "../registry/util.js";
@@ -18,6 +18,9 @@ function isDynamicModule(value) {
 function implementsNestModule(cls) {
     return typeof cls.prototype?.configure === "function";
 }
+function tokenOfProvider(provider) {
+    return typeof provider === "function" ? provider : provider.provide;
+}
 export class ModuleLoader {
     container;
     router;
@@ -51,6 +54,8 @@ export class ModuleLoader {
             []
         ]
     ]);
+    moduleIdByClass = new Map();
+    seenModuleIds = new Set();
     constructor(container, router){
         this.container = container;
         this.router = router;
@@ -61,6 +66,19 @@ export class ModuleLoader {
             this.router.registerController(controller);
         }
     }
+    getModuleId(moduleClass) {
+        const cached = this.moduleIdByClass.get(moduleClass);
+        if (cached) return cached;
+        const baseName = moduleClass.name || "AnonModule";
+        let id = baseName;
+        let counter = 0;
+        while(this.seenModuleIds.has(id)){
+            id = `${baseName}#${++counter}`;
+        }
+        this.seenModuleIds.add(id);
+        this.moduleIdByClass.set(moduleClass, id);
+        return id;
+    }
     processModule(moduleClassOrDynamic) {
         // Handle dynamic modules ({ module, imports, controllers, providers })
         let moduleClass;
@@ -103,8 +121,12 @@ export class ModuleLoader {
             throw new Error(`Failed to get module metadata for ${moduleClass.name}`);
         }
         this.processingStack.add(moduleClass);
+        const moduleId = this.getModuleId(moduleClass);
         try {
             const importedProviders = new Set(this.globalExports);
+            // Determine importedModuleIds eagerly (before recursing) so child
+            // modules can be referenced in our scope's importedModules set.
+            const importedModuleIds = new Set();
             for (const entry of [
                 ...metadata.imports,
                 ...extraImports
@@ -113,6 +135,7 @@ export class ModuleLoader {
                 const isForwardRef = entry instanceof ForwardRef;
                 const importedModule = isForwardRef ? entry.factory() : entry;
                 const importedModuleClass = isDynamicModule(importedModule) ? importedModule.module : importedModule;
+                importedModuleIds.add(this.getModuleId(importedModuleClass));
                 // If this forwardRef-wrapped import is currently being processed, skip it to
                 // break the circular chain. Non-forwardRef circular imports still throw.
                 if (isForwardRef && this.processingStack.has(importedModuleClass)) {
@@ -123,19 +146,42 @@ export class ModuleLoader {
                     importedProviders.add(token);
                 }
             }
-            // Register metadata providers + dynamic module extra providers
             const allProviders = [
                 ...metadata.providers,
                 ...extraProviders
             ];
-            for (const provider of allProviders){
-                this.registerProvider(provider);
-            }
-            // Collect metadata controllers + dynamic module extra controllers
             const allControllers = [
                 ...metadata.controllers,
                 ...extraControllers
             ];
+            const allExports = [
+                ...metadata.exports,
+                ...extraExports
+            ];
+            // Build the ModuleScope BEFORE registering providers so the visibility
+            // check sees the local-provider set as we register.
+            const localProviders = new Set();
+            for (const provider of allProviders){
+                const tk = tokenOfProvider(provider);
+                if (tk !== undefined) localProviders.add(tk);
+            }
+            for (const controller of allControllers){
+                localProviders.add(controller);
+            }
+            // The module class itself can be DI-resolved (NestModule.configure path);
+            // include it in its own scope.
+            localProviders.add(moduleClass);
+            const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
+            this.container.registerScope({
+                moduleId,
+                localProviders,
+                importedModules: importedModuleIds,
+                exportedTokens: new Set(allExports),
+                isGlobal
+            });
+            for (const provider of allProviders){
+                this.registerProvider(provider, moduleId);
+            }
             for (const controller of allControllers){
                 this.collectedControllers.add(controller);
             }
@@ -144,13 +190,8 @@ export class ModuleLoader {
                 MetadataRegistry.propagateControllerComponents(moduleClass, controller);
             }
             this.processedModules.add(moduleClass);
-            const allExports = [
-                ...metadata.exports,
-                ...extraExports
-            ];
             const exports = this.buildExportSet(allExports, allProviders, importedProviders);
             this.moduleExportsCache.set(moduleClass, exports);
-            const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
             if (isGlobal) {
                 for (const token of exports){
                     this.globalExports.add(token);
@@ -160,9 +201,9 @@ export class ModuleLoader {
             // resolved through the container so it can have its own DI dependencies.
             if (implementsNestModule(moduleClass)) {
                 if (!this.container.has(moduleClass)) {
-                    this.container.register(moduleClass);
+                    this.container.register(moduleClass, moduleId);
                 }
-                const instance = this.container.resolve(moduleClass);
+                const instance = this.container.resolve(moduleClass, moduleId);
                 const builder = new MiddlewareBuilder();
                 instance.configure(builder);
                 this.consumerMiddlewareDefinitions.push(...builder.getDefinitions());
@@ -172,16 +213,16 @@ export class ModuleLoader {
             this.processingStack.delete(moduleClass);
         }
     }
-    registerProvider(provider) {
+    registerProvider(provider, moduleId) {
         if (typeof provider === "function") {
             if (!this.container.has(provider)) {
-                this.container.register(provider);
+                this.container.register(provider, moduleId);
                 this.registeredProviders.push(provider);
             }
         } else {
             const token = provider.provide;
             if (!token) {
-                this.container.register(provider);
+                this.container.register(provider, moduleId);
                 return;
             }
             if (this.isAppToken(token)) {
@@ -189,13 +230,16 @@ export class ModuleLoader {
                 this.container.register({
                     ...provider,
                     provide: syntheticToken
-                });
+                }, moduleId);
+                // Synthetic APP_* tokens are resolved at request time by RouteManager
+                // with no requester; mark them global so the visibility check passes.
+                this.container.markGlobalToken(syntheticToken);
                 this.registeredProviders.push(syntheticToken);
                 getOrCreateArray(this.appProviderTokens, token).push(syntheticToken);
                 return;
             }
             if (!this.container.has(token)) {
-                this.container.register(provider);
+                this.container.register(provider, moduleId);
                 this.registeredProviders.push(token);
             }
         }
@@ -207,7 +251,7 @@ export class ModuleLoader {
         const exportSet = new Set();
         const providerTokens = new Set();
         for (const p of providers){
-            const token = typeof p === "function" ? p : p.provide;
+            const token = tokenOfProvider(p);
             if (token !== undefined) providerTokens.add(token);
         }
         for (const exported of exports){
@@ -250,8 +294,11 @@ export class ModuleLoader {
                 }
                 const instance = await this.container.resolveAsync(token);
                 instanceSet.add(instance);
-            } catch  {
-            // Skip unresolvable tokens
+            } catch (err) {
+                // Module visibility errors must always propagate — they indicate a
+                // genuine wiring bug, not something to swallow as a discovery skip.
+                if (err instanceof ModuleVisibilityError) throw err;
+                this.routeError(err, `resolve provider`);
             }
         }
         for (const controller of this.collectedControllers){
@@ -261,12 +308,22 @@ export class ModuleLoader {
                 }
                 const instance = await this.container.resolveAsync(controller);
                 instanceSet.add(instance);
-            } catch  {
-            // Skip unresolvable controllers
+            } catch (err) {
+                if (err instanceof ModuleVisibilityError) throw err;
+                this.routeError(err, `resolve controller ${controller.name}`);
             }
         }
         return [
             ...instanceSet
         ];
     }
+    routeError(err, context) {
+        const mode = this.container.getDiagnostics();
+        if (mode === "silent") return;
+        if (mode === "throw") {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+        // 'log'
+        console.warn(`[vela] ${context} failed:`, err);
+    }
 }

package/dist/plugin/plugin.d.ts

@@ -0,0 +1,31 @@
+import { InjectionToken } from '../container/types';
+import type { Type } from '../container/types';
+import type { DynamicModule } from '../registry/types';
+export interface Plugin {
+    id: string;
+    version: string;
+    module: Type | DynamicModule;
+    dependsOn?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Freeze and validate a plugin manifest. Returns the same object so it can
+ * be used in `composePlugins([definePlugin(...), ...])`.
+ */
+export declare function definePlugin(plugin: Plugin): Plugin;
+export declare class PluginRegistry {
+    private byId;
+    constructor(plugins: readonly Plugin[]);
+    list(): Plugin[];
+    get(id: string): Plugin | undefined;
+    dependents(id: string): Plugin[];
+}
+export declare const PLUGIN_REGISTRY_TOKEN: InjectionToken<PluginRegistry>;
+export declare class PluginRootModule {
+}
+/**
+ * Compose a list of plugins into a single dynamic module that imports each
+ * plugin's module in dependency order, registers a `PluginRegistry`, and
+ * exposes it globally so any plugin can introspect peers.
+ */
+export declare function composePlugins(plugins: readonly Plugin[]): DynamicModule;

package/dist/plugin/plugin.js

@@ -0,0 +1,111 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { InjectionToken } from "../container/types.js";
+import { Module } from "../module/decorators.js";
+/**
+ * Freeze and validate a plugin manifest. Returns the same object so it can
+ * be used in `composePlugins([definePlugin(...), ...])`.
+ */ export function definePlugin(plugin) {
+    if (!plugin.id) throw new Error('Plugin requires an id');
+    if (!plugin.version) throw new Error('Plugin requires a version');
+    if (!plugin.module) throw new Error('Plugin requires a module');
+    return Object.freeze({
+        ...plugin
+    });
+}
+export class PluginRegistry {
+    byId;
+    constructor(plugins){
+        this.byId = new Map();
+        for (const p of plugins){
+            if (this.byId.has(p.id)) {
+                throw new Error(`Duplicate plugin id: '${p.id}'`);
+            }
+            this.byId.set(p.id, p);
+        }
+    }
+    list() {
+        return [
+            ...this.byId.values()
+        ];
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    dependents(id) {
+        return this.list().filter((p)=>p.dependsOn?.includes(id) ?? false);
+    }
+}
+export const PLUGIN_REGISTRY_TOKEN = new InjectionToken('PLUGIN_REGISTRY');
+export class PluginRootModule {
+}
+PluginRootModule = _ts_decorate([
+    Module({})
+], PluginRootModule);
+/**
+ * Topologically sort plugins so each plugin's dependencies appear first.
+ * Throws on missing dependencies and cycles.
+ */ function topologicalSort(plugins) {
+    const byId = new Map();
+    for (const p of plugins){
+        if (byId.has(p.id)) {
+            throw new Error(`Duplicate plugin id: '${p.id}'`);
+        }
+        byId.set(p.id, p);
+    }
+    const result = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (p, path)=>{
+        if (visited.has(p.id)) return;
+        if (visiting.has(p.id)) {
+            const cycle = [
+                ...path,
+                p.id
+            ].join(' -> ');
+            throw new Error(`Plugin cycle detected: ${cycle}`);
+        }
+        visiting.add(p.id);
+        for (const depId of p.dependsOn ?? []){
+            const dep = byId.get(depId);
+            if (!dep) {
+                throw new Error(`Plugin '${p.id}' depends on missing plugin '${depId}'`);
+            }
+            visit(dep, [
+                ...path,
+                p.id
+            ]);
+        }
+        visiting.delete(p.id);
+        visited.add(p.id);
+        result.push(p);
+    };
+    for (const p of plugins)visit(p, []);
+    return result;
+}
+/**
+ * Compose a list of plugins into a single dynamic module that imports each
+ * plugin's module in dependency order, registers a `PluginRegistry`, and
+ * exposes it globally so any plugin can introspect peers.
+ */ export function composePlugins(plugins) {
+    const sorted = topologicalSort(plugins);
+    const registry = new PluginRegistry(sorted);
+    return {
+        module: PluginRootModule,
+        imports: sorted.map((p)=>p.module),
+        providers: [
+            {
+                provide: PLUGIN_REGISTRY_TOKEN,
+                useValue: registry
+            }
+        ],
+        exports: [
+            PLUGIN_REGISTRY_TOKEN
+        ],
+        global: true
+    };
+}

package/dist/registry/metadata.registry.js

@@ -265,6 +265,5 @@ export class MetadataRegistry {
             this.handlerComponents[type].clear();
         }
         this.globalComponents = emptyComponentStore();
-    // reflectMeta is a WeakMap — entries die with their targets.
     }
 }

package/dist/schedule/schedule.registry.js

@@ -33,7 +33,12 @@ export class ScheduleRegistry {
             let instance;
             try {
                 instance = this.container.resolve(token);
-            } catch  {
+            } catch (err) {
+                const mode = this.container.getDiagnostics();
+                if (mode === 'throw') throw err;
+                if (mode === 'log') {
+                    console.warn(`[vela] schedule discovery: cannot resolve ${token.name || String(token)}:`, err);
+                }
                 continue;
             }
             if (cronMeta) {

package/dist/schedule-node/schedule.executor.d.ts

@@ -1,13 +1,15 @@
+import { Container } from '../container/container';
 import type { OnApplicationBootstrap, OnModuleDestroy } from '../lifecycle/index';
 import { ScheduleRegistry } from '../schedule/schedule.registry';
 export declare class ScheduleExecutor implements OnApplicationBootstrap, OnModuleDestroy {
     private registry;
+    private container;
     private intervalTimers;
     private cronTimers;
     private cronMatcherCache;
     private lastCronMinute;
     private running;
-    constructor(registry: ScheduleRegistry);
+    constructor(registry: ScheduleRegistry, container: Container);
     onApplicationBootstrap(): void;
     private scheduleInterval;
     private scheduleCron;