@velajs/vela 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.15.0 (2026-07-04)
+
+Introspection seams for `@velajs/cli` (roadmap phase 3, CLI introspection):
+serializable, zero-instantiation views of the app the CLI renders instead of
+re-deriving framework internals.
+
+### Added
+
+- **`app.describeRoutes(): RouteDescription[]`** — every explicit controller
+  route exactly as `build()` registered it: method AS DECLARED (`@Head()`
+  reports HEAD even though Hono serves it under GET), fully composed path
+  (global prefix + version segment + controller prefix + route path),
+  controller name, handler name, version. Contributed routes
+  (`RouteContributor`/CRUD) mount directly on Hono and are observable via
+  `getHonoApp().routes`.
+- **`app.getGlobalPrefix()`** — the prefix in effect ('' when none); also
+  what `openapi` tooling threads into `createOpenApiDocument`.
+- **`Container.getModuleDescriptions(): ModuleDescription[]`** — the loaded
+  module graph (moduleId, imports, isGlobal, lazy, provider/export token
+  labels), load order plus the `__root__` bucket; reads registration state
+  only — safe pre/post bootstrap, never constructs, never claims lazy
+  modules.
+- **`describeToken(token)`** — the token-label helper vela's own errors use,
+  exported for tooling.
+
 ## 1.14.0 (2026-07-04)
 
 First-party `QueueModule` (roadmap phase 3, "the openness proof"): a whole

package/dist/application.d.ts

@@ -2,7 +2,7 @@ import type { Hono } from 'hono';
 import type { Container } from './container/container';
 import type { Token } from './container/types';
 import { EntrypointRegistry } from './entrypoint/entrypoint.registry';
-import type { RouteManager } from './http/route.manager';
+import type { RouteDescription, RouteManager } from './http/route.manager';
 import type { MountOpenApiOptions } from './openapi/types';
 import type { FilterType, GuardType, InterceptorType, PipeType } from './registry/types';
 export declare class VelaApplication {
@@ -25,6 +25,15 @@ export declare class VelaApplication {
     setInstances(instances: unknown[]): void;
     get<T>(token: Token<T>): T;
     getHonoApp(): Hono;
+    /**
+     * Every explicit controller route as the framework registered it (fully
+     * composed paths — the `vela route list` seam). Requires built routes;
+     * contributed routes (`@velajs/crud`) mount directly on Hono and are
+     * observable via `getHonoApp().routes` instead.
+     */
+    describeRoutes(): RouteDescription[];
+    /** The global route prefix in effect ('' when none). */
+    getGlobalPrefix(): string;
     useGlobalPipes(...pipes: PipeType[]): this;
     useGlobalGuards(...guards: GuardType[]): this;
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;

package/dist/application.js

@@ -63,6 +63,18 @@ export class VelaApplication {
     getHonoApp() {
         return this.getApp();
     }
+    /**
+   * Every explicit controller route as the framework registered it (fully
+   * composed paths — the `vela route list` seam). Requires built routes;
+   * contributed routes (`@velajs/crud`) mount directly on Hono and are
+   * observable via `getHonoApp().routes` instead.
+   */ describeRoutes() {
+        this.getApp(); // same routes-not-built guard as every HTTP accessor
+        return this.routeManager.getRouteDescriptions();
+    }
+    /** The global route prefix in effect ('' when none). */ getGlobalPrefix() {
+        return this.routeManager.getGlobalPrefix();
+    }
     // Pipeline components — applied at request time, no rebuild needed
     useGlobalPipes(...pipes) {
         this.routeManager.useGlobalPipes(...pipes);

package/dist/container/container.d.ts

@@ -1,5 +1,5 @@
 import { Scope } from '../constants';
-import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleScope, ProviderOptions, Token, Type } from './types';
+import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleDescription, ModuleScope, ProviderOptions, Token, Type } from './types';
 /**
  * Per-module provider buckets. Each module instance owns its providers under
  * its `moduleId`; the same logical token can have distinct registrations in
@@ -95,6 +95,13 @@ export declare class Container {
      * binding module — so framework adapters can initialize all of them.
      */
     getUseValues(): unknown[];
+    /**
+     * Serializable description of every loaded module instance (load order),
+     * plus the `__root__` bucket (bootstrap primitives) when non-empty —
+     * the `vela module graph` seam. Reads registration state only: safe pre-
+     * and post-bootstrap, never constructs, never claims lazy modules.
+     */
+    getModuleDescriptions(): ModuleDescription[];
     /**
      * Compute request-scope bubbling for every registration (call once at
      * bootstrap, after all providers are registered). A provider whose declared

package/dist/container/container.js

@@ -1,7 +1,7 @@
 import { Scope } from "../constants.js";
 import { disposeInstance, isDisposable } from "./disposable.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
-import { ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
+import { describeToken, ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
 const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
 /**
  * Sentinel comparing a token to the bare `Object` class — `design:paramtypes`
@@ -415,6 +415,44 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         return out;
     }
     /**
+   * Serializable description of every loaded module instance (load order),
+   * plus the `__root__` bucket (bootstrap primitives) when non-empty —
+   * the `vela module graph` seam. Reads registration state only: safe pre-
+   * and post-bootstrap, never constructs, never claims lazy modules.
+   */ getModuleDescriptions() {
+        const out = [];
+        for (const scope of this.scopes.values()){
+            out.push({
+                moduleId: scope.moduleId,
+                imports: [
+                    ...scope.importedModules
+                ],
+                isGlobal: scope.isGlobal,
+                lazy: scope.lazy === true,
+                providers: [
+                    ...this.providers.get(scope.moduleId)?.keys() ?? []
+                ].map(describeToken),
+                exports: [
+                    ...scope.exportedTokens
+                ].map(describeToken)
+            });
+        }
+        const rootBucket = this.providers.get(ROOT_MODULE_ID);
+        if (rootBucket && rootBucket.size > 0) {
+            out.push({
+                moduleId: ROOT_MODULE_ID,
+                imports: [],
+                isGlobal: false,
+                lazy: false,
+                providers: [
+                    ...rootBucket.keys()
+                ].map(describeToken),
+                exports: []
+            });
+        }
+        return out;
+    }
+    /**
    * Compute request-scope bubbling for every registration (call once at
    * bootstrap, after all providers are registered). A provider whose declared
    * scope is not REQUEST but which (transitively) depends on a request-scoped

package/dist/container/index.d.ts

@@ -1,6 +1,6 @@
 export { Container } from './container';
 export { Injectable, Inject, Optional, isInjectable, getScope } from './decorators';
-export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, } from './types';
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, describeToken, } from './types';
 export { ModuleRef } from './module-ref';
 export { mixin } from './mixin';
-export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ContainerOptions, Diagnostics, } from './types';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './types';

package/dist/container/index.js

@@ -1,5 +1,5 @@
 export { Container } from "./container.js";
 export { Injectable, Inject, Optional, isInjectable, getScope } from "./decorators.js";
-export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, describeToken } from "./types.js";
 export { ModuleRef } from "./module-ref.js";
 export { mixin } from "./mixin.js";

package/dist/container/types.d.ts

@@ -117,6 +117,29 @@ export type Diagnostics = 'silent' | 'log' | 'throw';
 export interface ContainerOptions {
     diagnostics?: Diagnostics;
 }
+/**
+ * Human-readable token label — class name, `InjectionToken(desc)`, symbol
+ * string, or String() fallback. Public so introspection tooling (module
+ * graphs, entrypoint listings) renders tokens the same way vela's own errors
+ * do.
+ */
+export declare function describeToken(token: Token): string;
+/**
+ * One module instance in the loaded graph, serializable (strings only) —
+ * what `Container.getModuleDescriptions()` returns for introspection tooling
+ * (`vela module graph`). Reads registration state only; never constructs.
+ */
+export interface ModuleDescription {
+    moduleId: string;
+    /** moduleIds this instance imports. */
+    imports: string[];
+    isGlobal: boolean;
+    lazy: boolean;
+    /** Token labels registered in this instance's bucket (registration order). */
+    providers: string[];
+    /** Token labels this instance exports. */
+    exports: string[];
+}
 export declare class ModuleVisibilityError extends Error {
     readonly moduleId: string;
     readonly token: Token;

package/dist/container/types.js

@@ -18,7 +18,12 @@ export class ForwardRef {
 export function forwardRef(factory) {
     return new ForwardRef(factory);
 }
-function describeToken(token) {
+/**
+ * Human-readable token label — class name, `InjectionToken(desc)`, symbol
+ * string, or String() fallback. Public so introspection tooling (module
+ * graphs, entrypoint listings) renders tokens the same way vela's own errors
+ * do.
+ */ export function describeToken(token) {
     if (token instanceof InjectionToken) return token.toString();
     if (typeof token === 'function') return token.name;
     if (typeof token === 'symbol') return token.toString();

package/dist/http/route.manager.d.ts

@@ -5,6 +5,23 @@ import type { MiddlewareRouteDefinition } from '../module/middleware';
 import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from '../pipeline/types';
 import type { FilterType, GuardType, InterceptorType, MiddlewareType, PipeType } from '../registry/types';
 import type { ControllerRegistration } from './types';
+/**
+ * One explicit controller route as the framework registered it — recorded by
+ * `build()` with the SAME composed path handed to Hono (global prefix +
+ * version segment + controller prefix + route path), so introspection tooling
+ * (`vela route list`) never re-derives composition. Contributed routes
+ * (`RouteContributor`, e.g. `@velajs/crud`) mount directly on the Hono app
+ * and are not described here — diff `app.getHonoApp().routes` for those.
+ */
+export interface RouteDescription {
+    /** As declared on the handler — `@Head()` reports HEAD (Hono serves it under GET). */
+    method: string;
+    /** Fully composed path exactly as registered. */
+    path: string;
+    controller: string;
+    handler: string;
+    version?: number;
+}
 export interface RouteManagerOptions {
     getClientIp?: (c: Context) => string | null;
     middleware?: MiddlewareHandler[];
@@ -27,6 +44,7 @@ export declare class RouteManager {
     private globalFilters;
     private globalPrefix;
     private consumerMiddlewareDefinitions;
+    private routeDescriptions;
     private readonly handlerExecutor;
     private readonly ambientContainer;
     constructor(container: Container, options?: RouteManagerOptions);
@@ -59,6 +77,10 @@ export declare class RouteManager {
     private wrapMiddlewareWithFilters;
     private mapMiddlewareError;
     registerController(controller: Type): this;
+    /** The explicit controller routes recorded by the last `build()`. */
+    getRouteDescriptions(): RouteDescription[];
+    /** The global prefix in effect (set at bootstrap; '' when none). */
+    getGlobalPrefix(): string;
     build(): Promise<Hono>;
     private registerRoute;
     private buildVersionedPaths;

package/dist/http/route.manager.js

@@ -92,6 +92,7 @@ export class RouteManager {
     globalFilters = [];
     globalPrefix = '';
     consumerMiddlewareDefinitions = [];
+    routeDescriptions = [];
     handlerExecutor;
     ambientContainer;
     constructor(container, options = {}){
@@ -273,8 +274,17 @@ export class RouteManager {
         });
         return this;
     }
+    /** The explicit controller routes recorded by the last `build()`. */ getRouteDescriptions() {
+        return [
+            ...this.routeDescriptions
+        ];
+    }
+    /** The global prefix in effect (set at bootstrap; '' when none). */ getGlobalPrefix() {
+        return this.globalPrefix;
+    }
     async build() {
         const app = new Hono();
+        this.routeDescriptions = [];
         // Outermost: dispose the per-request child container once the request is
         // fully done. Fast-paths out when the child has no request-scoped
         // disposables (the common case → zero overhead / no behavior change).
@@ -353,11 +363,18 @@ export class RouteManager {
                 for (const route of routes){
                     const effectiveVersion = route.version ?? metadata.version;
                     const versionedPaths = this.buildVersionedPaths(this.globalPrefix, metadata.prefix, route.path, effectiveVersion);
+                    // Parallel to versionedPaths: buildVersionedPaths maps versions to
+                    // paths 1:1 in order, so index i of both arrays belongs together.
+                    const versionsForPaths = effectiveVersion === undefined ? [
+                        undefined
+                    ] : Array.isArray(effectiveVersion) ? effectiveVersion : [
+                        effectiveVersion
+                    ];
                     // Scoped (controller/handler) middleware only — global middleware is
                     // applied once by this manager's own global pass, never re-read here.
                     const middlewareItems = ComponentManager.getScopedComponents('middleware', controller, route.handlerName);
                     const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
-                    for (const fullPath of versionedPaths){
+                    for (const [pathIndex, fullPath] of versionedPaths.entries()){
                         for (const middlewareItem of middlewareItems){
                             app.use(fullPath, this.wrapMiddlewareWithFilters((c, next)=>{
                                 const requestContainer = this.getRequestContainer(c);
@@ -366,6 +383,13 @@ export class RouteManager {
                             }));
                         }
                         this.registerRoute(app, route.method, fullPath, handler);
+                        this.routeDescriptions.push({
+                            method: String(route.method),
+                            path: fullPath || '/',
+                            controller: controller.name,
+                            handler: String(route.handlerName),
+                            version: versionsForPaths[pathIndex]
+                        });
                     }
                 }
             }

package/dist/index.d.ts

@@ -6,8 +6,9 @@ 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, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, } from './container/index';
-export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ContainerOptions, Diagnostics, } from './container/index';
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, describeToken, } from './container/index';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, ProviderOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './container/index';
+export type { RouteDescription } from './http/route.manager';
 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, createLazyParamDecorator, applyDecorators, } from './http/index';
 export { REQUEST_CONTEXT } from './http/request-context';

package/dist/index.js

@@ -7,7 +7,7 @@ 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, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin } from "./container/index.js";
+export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, mixin, describeToken } from "./container/index.js";
 // Constants
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from "./constants.js";
 // HTTP Decorators

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",