@expressots/adapter-express 3.0.0-beta.4.2 → 4.0.0-preview.1

package/lib/cjs/adapter-express/application-express.js

@@ -27,13 +27,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppExpress = void 0;
-const fs_1 = __importDefault(require("fs"));
-const process_1 = __importStar(require("process"));
+const express_1 = __importDefault(require("express"));
+const fs = __importStar(require("node:fs"));
+// Note: We use the global `process` object directly instead of importing it
+// because signal handlers (SIGTERM, SIGINT, etc.) don't work correctly when
+// process is imported as an ES module in CommonJS compiled code.
 const core_1 = require("@expressots/core");
+/**
+ * Metadata key used by `@provide` (and friends) in `@expressots/core`'s
+ * binding-decorator module. The constant lives at an internal path
+ * (`di/binding-decorator/constants`) so we hardcode the string here —
+ * it's part of the framework's stable runtime contract and is what
+ * `MetricsCollector` reads for its own `providers` count.
+ */
+const PROVIDE_METADATA_KEY = "inversify-binding-decorators:provide";
 const shared_1 = require("@expressots/shared");
-const http_status_middleware_1 = require("./express-utils/http-status-middleware");
-const inversify_express_server_1 = require("./express-utils/inversify-express-server");
-const engine_1 = require("./render/engine");
+const http_status_middleware_js_1 = require("./express-utils/http-status-middleware.js");
+const inversify_express_server_js_1 = require("./express-utils/inversify-express-server.js");
+const engine_js_1 = require("./render/engine.js");
+const utils_js_1 = require("./express-utils/utils.js");
+const index_js_1 = require("./studio/index.js");
 /**
  * The AppExpress class provides methods for configuring and running an Express application.
  * @class AppExpress
@@ -46,6 +59,124 @@ const engine_1 = require("./render/engine");
  * @method isDevelopment - Verifies if the current environment is development.
  */
 class AppExpress {
+    /**
+     * Disable log buffering. Called by micro() to restore normal console output
+     * since micro API doesn't use the banner system.
+     * @public API
+     */
+    static disableBuffering() {
+        AppExpress.stopBuffering();
+        // Clear any buffered logs since micro() doesn't need them
+        AppExpress.logBuffer = [];
+    }
+    /**
+     * Start buffering all console output.
+     * This captures both console.log and direct process.stdout.write calls.
+     * @private
+     */
+    static startLogBuffering() {
+        if (AppExpress.isBuffering)
+            return;
+        // Store original streams
+        AppExpress.originalStdoutWrite = process.stdout.write.bind(process.stdout);
+        AppExpress.originalStderrWrite = process.stderr.write.bind(process.stderr);
+        // Create wrapper functions that use fs.writeSync directly (always works
+        // in both CJS and ESM scope - hence the static `node:fs` import above).
+        const createOriginalConsoleMethod = (useStderr = false) => (...args) => {
+            const message = args
+                .map((a) => {
+                if (typeof a === "object" && a !== null) {
+                    try {
+                        return JSON.stringify(a, null, 2);
+                    }
+                    catch {
+                        return String(a);
+                    }
+                }
+                return String(a);
+            })
+                .join(" ") + "\n";
+            // Use fs.writeSync directly - this always works
+            fs.writeSync(useStderr ? 2 : 1, message);
+        };
+        AppExpress.originalGlobalConsole = {
+            log: createOriginalConsoleMethod(false),
+            info: createOriginalConsoleMethod(false),
+            warn: createOriginalConsoleMethod(true),
+            error: createOriginalConsoleMethod(true),
+            debug: createOriginalConsoleMethod(false),
+        };
+        AppExpress.logBuffer = [];
+        AppExpress.isBuffering = true;
+        // Create buffering functions for console methods
+        const bufferConsoleMethod = () => (...args) => {
+            const message = args
+                .map((a) => (typeof a === "object" && a !== null ? JSON.stringify(a) : String(a)))
+                .join(" ") + "\n";
+            AppExpress.logBuffer.push(message);
+        };
+        // Override console methods directly (not replacing the console object)
+        // This ensures even cached references to console.log will use the buffered version
+        console.log = bufferConsoleMethod();
+        console.info = bufferConsoleMethod();
+        console.warn = bufferConsoleMethod();
+        console.error = bufferConsoleMethod();
+        console.debug = bufferConsoleMethod();
+        // Also override process.stdout.write for direct writes (like our Logger)
+        const bufferWrite = (chunk) => {
+            const str = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString();
+            AppExpress.logBuffer.push(str);
+            return true;
+        };
+        // Use direct assignment for overriding
+        process.stdout.write = bufferWrite;
+        process.stderr.write = bufferWrite;
+    }
+    /**
+     * Stop buffering but keep the buffered logs for later flushing.
+     * This restores normal console/stdout output.
+     * @private
+     */
+    static stopBuffering() {
+        if (!AppExpress.isBuffering)
+            return;
+        // Restore original console methods using our wrapper functions
+        if (AppExpress.originalGlobalConsole) {
+            console.log = AppExpress.originalGlobalConsole.log;
+            console.info = AppExpress.originalGlobalConsole.info;
+            console.warn = AppExpress.originalGlobalConsole.warn;
+            console.error = AppExpress.originalGlobalConsole.error;
+            console.debug = AppExpress.originalGlobalConsole.debug;
+        }
+        // Restore original stdout/stderr by direct assignment
+        // (Object.defineProperty may not work correctly for stream.write)
+        if (AppExpress.originalStdoutWrite) {
+            process.stdout.write =
+                AppExpress.originalStdoutWrite;
+        }
+        if (AppExpress.originalStderrWrite) {
+            process.stderr.write =
+                AppExpress.originalStderrWrite;
+        }
+        AppExpress.isBuffering = false;
+    }
+    /**
+     * Flush all buffered logs to stdout.
+     * Should be called after stopBuffering() and after displaying the banner.
+     * @private
+     */
+    static flushBufferedLogs() {
+        const logs = AppExpress.logBuffer;
+        AppExpress.logBuffer = [];
+        for (const log of logs) {
+            if (AppExpress.originalStdoutWrite) {
+                AppExpress.originalStdoutWrite.call(process.stdout, log);
+            }
+            else {
+                process.stdout.write(log);
+            }
+        }
+    }
     constructor() {
         this.logger = new core_1.Logger();
         this.console = new core_1.Console();
@@ -53,56 +184,165 @@ class AppExpress {
         this.globalPrefix = "/";
         this.middlewares = [];
         this.renderOptions = {};
+        this.isShuttingDown = false;
+        this.bannerGenerator = null;
+        this.shutdownHandlers = new Map();
+        this.studioConfig = {};
+        /**
+         * Latest snapshot of application metrics produced by `MetricsCollector`
+         * during banner display. We cache it so that `reportStudioRuntimeInfo`
+         * can forward the *runtime* provider/interceptor counts (which match
+         * what the CLI banner shows) to the Studio Agent without recomputing.
+         */
+        this.lastApplicationMetrics = null;
+        /** Track active connections for force-close during shutdown */
+        this.activeConnections = new Set();
+        /** Timeout for force-closing connections during shutdown (ms) */
+        this.shutdownTimeout = 5000;
+        /** Number of retries when port is in use (for hot-reload scenarios) */
+        this.portRetryAttempts = 10;
+        /** Delay between port retry attempts (ms) */
+        this.portRetryDelay = 500;
+        // Buffering is already started via static initialization (initBuffering)
+        // This ensures ALL logs are captured from the very beginning
         this.globalConfiguration();
     }
+    /**
+     * Helper function to handle both sync and async method calls.
+     * If the result is a Promise, awaits it; otherwise returns immediately.
+     * @private
+     */
+    async handleSyncOrAsync(result) {
+        if (result instanceof Promise) {
+            return await result;
+        }
+    }
     /**
      * Implement this method to set up global configurations for the server.
-     * This method is called before any other server initialization methods.
-     * Use this method to configure global settings that apply to the entire
-     * server application. Supports asynchronous setup with a Promise.
+     * This method is called synchronously in the constructor before any other
+     * server initialization methods. Use this method to configure global settings
+     * that apply to the entire server application.
+     *
+     * Note: This method is synchronous and called during object construction.
+     * For asynchronous initialization, use `configureServices()` instead.
      *
      * @abstract
-     * @returns {void | Promise<void>}
+     * @returns {void}
      * @public API
      */
-    async globalConfiguration() { }
+    globalConfiguration() { }
     /**
      * Implement this method to set up required services or configurations before
      * the server starts. This is essential for initializing dependencies or settings
-     * necessary for server operation. Supports asynchronous setup with a Promise.
+     * necessary for server operation. Supports both synchronous and asynchronous setup.
      *
      * @abstract
      * @returns {void | Promise<void>}
      * @public API
      */
-    async configureServices() { }
+    configureServices() { }
     /**
      * Implement this method to execute actions or configurations after the server
      * has started. Use this for operations that need to run once the server is
-     * operational. Supports asynchronous execution with a Promise.
+     * operational. Supports both synchronous and asynchronous execution.
      *
      * @abstract
      * @returns {void | Promise<void>}
      * @public API
      */
-    async postServerInitialization() { }
+    postServerInitialization() { }
     /**
      * Implement this method to handle cleanup and final actions when the server
      * is shutting down. Ideal for closing resources, stopping tasks, or other
-     * cleanup procedures to ensure a graceful server shutdown. Supports asynchronous
-     * cleanup with a Promise.
+     * cleanup procedures to ensure a graceful server shutdown. Supports both
+     * synchronous and asynchronous cleanup.
+     *
+     * The signal parameter indicates what triggered the shutdown:
+     * - SIGTERM: Graceful termination (e.g., Kubernetes pod shutdown)
+     * - SIGINT: User interrupt (e.g., Ctrl+C)
+     * - SIGHUP: Terminal hangup
+     * - SIGQUIT: Quit with core dump
+     * - SIGBREAK: Windows break signal
      *
      * @abstract
+     * @param signal - The signal that triggered the shutdown (optional for backward compatibility)
      * @returns {void | Promise<void>}
      * @public API
      */
-    async serverShutdown() { }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    serverShutdown(signal) { }
+    /**
+     * Performs graceful shutdown of the application.
+     *
+     * Shutdown sequence:
+     * 1. Execute lifecycle shutdown hooks on all IShutdown providers
+     * 2. Call user's serverShutdown hook
+     * 3. Close the HTTP server to stop accepting new connections
+     *
+     * @param signal - The signal that triggered the shutdown
+     * @returns Promise that resolves when shutdown is complete
+     * @internal
+     */
+    async handleExit(signal) {
+        // 1. Stop Studio Agent if running
+        await (0, index_js_1.stopStudio)();
+        // 2. Execute lifecycle shutdown hooks on all IShutdown providers
+        if (this.lifecycleRegistry) {
+            await this.lifecycleRegistry.executeShutdown(signal);
+        }
+        // 3. Call user's serverShutdown hook
+        await this.handleSyncOrAsync(this.serverShutdown(signal));
+        // 4. Gracefully close the HTTP server with connection force-close
+        if (this.serverInstance) {
+            await new Promise((resolve) => {
+                // Set a timeout to force-destroy connections if graceful shutdown takes too long
+                const forceCloseTimeout = setTimeout(() => {
+                    console.log(`⚠️  Force-closing ${this.activeConnections.size} active connections after ${this.shutdownTimeout}ms timeout`);
+                    this.destroyAllConnections();
+                    resolve();
+                }, this.shutdownTimeout);
+                // Try graceful close first
+                this.serverInstance.close((err) => {
+                    clearTimeout(forceCloseTimeout);
+                    if (err) {
+                        // Don't fail on close error during shutdown - just log it
+                        console.log(`Note: Server close returned: ${err.message}`);
+                    }
+                    resolve();
+                });
+                // Immediately destroy idle connections (keep-alive connections with no pending requests)
+                // This speeds up shutdown significantly
+                this.serverInstance.closeIdleConnections?.();
+            });
+            // Clear all remaining connections
+            this.destroyAllConnections();
+        }
+    }
+    /**
+     * Destroy all active connections immediately.
+     * Used during forced shutdown.
+     * @private
+     */
+    destroyAllConnections() {
+        for (const socket of this.activeConnections) {
+            try {
+                socket.destroy();
+            }
+            catch {
+                // Ignore errors during connection destruction
+            }
+        }
+        this.activeConnections.clear();
+    }
     /**
-     * Handles process exit by calling serverShutdown and then exiting the process.
+     * Track a new connection for shutdown management.
+     * @private
      */
-    async handleExit() {
-        await this.serverShutdown();
-        process_1.default.exit(0);
+    trackConnection(socket) {
+        this.activeConnections.add(socket);
+        socket.once("close", () => {
+            this.activeConnections.delete(socket);
+        });
     }
     /**
      * Initialize the InversifyJS container with the provided modules and options.
@@ -123,9 +363,40 @@ class AppExpress {
         }
         this.appContainer.create(appModules);
         this.providerManager = new core_1.ProviderManager(this.appContainer.Container);
-        this.middlewareManager = new core_1.Middleware();
+        const baseMiddleware = new core_1.Middleware();
+        // Create a wrapper that automatically injects container for exception filters
+        this.middlewareManager = this.createMiddlewareWrapper(baseMiddleware);
+        // Initialize lifecycle registry and discover providers implementing IBootstrap/IShutdown
+        this.lifecycleRegistry = new core_1.LifecycleRegistry(this.appContainer.Container);
+        this.lifecycleRegistry.discover();
         return this.appContainer;
     }
+    /**
+     * Creates a middleware wrapper that automatically injects container when exception filters are enabled
+     * This allows users to simply set enableExceptionFilters: true without manually passing the container
+     */
+    createMiddlewareWrapper(baseMiddleware) {
+        const container = this.appContainer?.Container;
+        // Create a proxy that intercepts setErrorHandler calls
+        return new Proxy(baseMiddleware, {
+            get(target, prop) {
+                if (prop === "setErrorHandler") {
+                    return function (options) {
+                        // Automatically inject container if enableExceptionFilters is true and container is available
+                        const enhancedOptions = {
+                            ...options,
+                            container: options?.enableExceptionFilters && container ? container : options?.container,
+                        };
+                        target.setErrorHandler(enhancedOptions);
+                    };
+                }
+                // Forward all other property access to the base middleware
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const value = target[prop];
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        });
+    }
     /**
      * Get the ProviderManager instance.
      * @returns The ProviderManager instance.
@@ -163,16 +434,47 @@ class AppExpress {
                         }
                         else {
                             const middleware = mid;
-                            middleware.use = middleware.use.bind(middleware);
-                            app.use(pathGlobal, middleware.use);
+                            // Check if it's a BaseMiddleware instance (has handler method, not use)
+                            const middlewareRecord = middleware;
+                            if (middlewareRecord.handler && typeof middlewareRecord.handler === "function") {
+                                // BaseMiddleware instance - wrap handler method
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                const baseMiddleware = middleware;
+                                app.use(pathGlobal, (req, res, next) => {
+                                    baseMiddleware.handler(req, res, next);
+                                });
+                            }
+                            else if (middleware.use) {
+                                middleware.use = middleware.use.bind(middleware);
+                                app.use(pathGlobal, middleware.use);
+                            }
+                            else {
+                                this.logger.warn(`Middleware ${middleware.constructor?.name || "unknown"} does not have a 'use' or 'handler' method`, "application-express");
+                            }
                         }
                     }
                 }
             }
             else {
                 const middleware = entry;
-                middleware.use = middleware.use.bind(middleware);
-                app.use(middleware.use);
+                // Check if it's a BaseMiddleware instance (has handler method, not use)
+                // BaseMiddleware instances are handled specially in inversify-express-server
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                if (middleware.handler && typeof middleware.handler === "function") {
+                    // BaseMiddleware instance - wrap handler method
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const baseMiddleware = middleware;
+                    app.use((req, res, next) => {
+                        baseMiddleware.handler(req, res, next);
+                    });
+                }
+                else if (middleware.use) {
+                    middleware.use = middleware.use.bind(middleware);
+                    app.use(middleware.use);
+                }
+                else {
+                    this.logger.warn(`Middleware ${middleware.constructor?.name || "unknown"} does not have a 'use' or 'handler' method`, "application-express");
+                }
             }
         }
     }
@@ -185,17 +487,54 @@ class AppExpress {
     async init() {
         if (!this.appContainer) {
             this.logger.error("No container provided for application configuration", "adapter-express");
-            (0, process_1.exit)(1);
+            process.exit(1);
         }
-        await this.configureServices();
+        // Create Express app early so it's available during configureServices for render()
+        const tempApp = (0, express_1.default)();
+        this.Middleware.setExpressApp(tempApp);
+        // Initialize Studio Agent if available (adds middleware before user
+        // middlewares). At this point we already know the port the user asked
+        // us to listen on (set in `listen()` before `init()` is invoked) and
+        // the configured global prefix, so forward both — the agent uses them
+        // to populate the Studio Status page.
+        await (0, index_js_1.initializeStudio)(tempApp, {
+            ...this.studioConfig,
+            appPort: this.port,
+            globalPrefix: this.globalPrefix,
+        }, this.appContainer);
+        await this.handleSyncOrAsync(this.configureServices());
         const sortedMiddlewarePipeline = this.Middleware.getMiddlewarePipeline();
         const pipeline = sortedMiddlewarePipeline.map((entry) => entry.middleware);
         this.middlewares.push(...pipeline);
         /* Apply the status code to the response */
-        this.middlewares.unshift(new http_status_middleware_1.HttpStatusCodeMiddleware(this.globalPrefix));
-        const expressServer = new inversify_express_server_1.InversifyExpressServer(this.appContainer.Container, null, {
-            rootPath: this.globalPrefix,
-        });
+        this.middlewares.unshift(new http_status_middleware_js_1.HttpStatusCodeMiddleware(this.globalPrefix));
+        const expressServer = new inversify_express_server_js_1.InversifyExpressServer(this.appContainer.Container, null, { rootPath: this.globalPrefix }, tempApp);
+        // Pass ContentNegotiationService to InversifyExpressServer if available
+        const contentNegotiationService = this.Middleware.getContentNegotiationService();
+        if (contentNegotiationService) {
+            expressServer.setContentNegotiationService(contentNegotiationService);
+        }
+        // Pass ValidationService to InversifyExpressServer if validation is configured
+        const validationConfig = this.Middleware.getValidationConfig?.();
+        if (validationConfig) {
+            // `.js` extension required by NodeNext for ESM consumers; the
+            // CJS build accepts it unchanged.
+            const { ValidationService } = await Promise.resolve().then(() => __importStar(require("./express-utils/validation-service.js")));
+            const { ClassValidatorAdapter } = await Promise.resolve().then(() => __importStar(require("@expressots/core")));
+            const validationService = new ValidationService();
+            validationService.enable(validationConfig);
+            // Register ClassValidatorAdapter by default
+            const classValidatorAdapter = new ClassValidatorAdapter();
+            validationService.getRegistry().register(classValidatorAdapter);
+            // Register any additional adapters from config
+            if (validationConfig.adapters) {
+                for (const AdapterClass of validationConfig.adapters) {
+                    const adapter = new AdapterClass();
+                    validationService.getRegistry().register(adapter);
+                }
+            }
+            expressServer.setValidationService(validationService);
+        }
         expressServer.setConfig((app) => {
             this.configureMiddleware(app, this.middlewares);
         });
@@ -214,20 +553,153 @@ class AppExpress {
      * @public API
      */
     async listen(port, appInfo) {
-        await this.init();
-        await this.configEngine();
+        // Capture wall-clock start so we can report total boot duration to the
+        // Studio Status page once `app.listen()` resolves with the actual port.
+        const listenStartedAt = Date.now();
+        // Close existing server instance if it exists
+        if (this.serverInstance) {
+            this.logger.warn("Closing existing server instance before starting new one", "adapter-express");
+            await this.closeExistingServer();
+            this.logger.info("✓ Application reloaded", "adapter-express");
+        }
+        // Remove old signal handlers to prevent duplicates
+        this.removeShutdownHandlers();
+        // Reset shutdown flag
+        this.isShuttingDown = false;
+        // Resolve banner configuration with environment-specific overrides
+        const resolvedBannerConfig = (0, core_1.resolveBannerConfig)(this.bannerConfig, this.environment || "development");
+        // Initialize banner generator with resolved config
+        this.bannerGenerator = new core_1.BannerGenerator(resolvedBannerConfig);
         this.environment = this.environment || "development";
-        this.app.set("env", this.environment);
         this.port = typeof port === "string" ? parseInt(port, 10) : port;
+        try {
+            await this.init();
+            await this.configEngine();
+            this.app.set("env", this.environment);
+            // Stop buffering and restore normal output (but don't flush yet)
+            AppExpress.stopBuffering();
+            // Flush all buffered logs that were captured during initialization
+            AppExpress.flushBufferedLogs();
+        }
+        catch (error) {
+            // Ensure buffering is stopped and logs are flushed even on error
+            AppExpress.stopBuffering();
+            AppExpress.flushBufferedLogs();
+            throw error;
+        }
+        // Ensure port is available (handles hot-reload scenarios)
+        // This will kill the previous process if needed - safest approach for dev experience
+        const portAvailable = await this.ensurePortAvailable(this.port);
+        if (!portAvailable) {
+            const errorMessage = `Port ${this.port} is still in use and could not be freed`;
+            this.logger.error(errorMessage, "adapter-express");
+            this.logger.info("💡 Try manually killing the process:", "adapter-express");
+            this.logger.info(process.platform === "win32"
+                ? `   netstat -ano | findstr :${this.port} && taskkill /F /PID <pid>`
+                : `   lsof -ti:${this.port} | xargs kill -9`, "adapter-express");
+            throw new Error(errorMessage);
+        }
         return new Promise((resolve, reject) => {
             this.serverInstance = this.app.listen(this.port, async () => {
-                this.port = this.serverInstance?.address()?.port;
-                this.console.messageServer(this.port, this.environment, appInfo);
-                ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
-                    process_1.default.on(signal, this.handleExit.bind(this));
+                // Track all connections for graceful shutdown
+                // This enables force-closing connections during hot-reload
+                this.serverInstance.on("connection", (socket) => {
+                    this.trackConnection(socket);
+                });
+                // Update port with actual assigned port (important for port 0 auto-assign)
+                this.port = this.serverInstance?.address()?.port || this.port;
+                // Display startup banner AFTER server starts (so we have the correct port)
+                this.displayStartupBanner(appInfo);
+                // Push live runtime details to the Studio Agent so the Status
+                // page swaps "—" for real values. We forward the same numbers
+                // `MetricsCollector` produced for the CLI banner (providers,
+                // interceptors, middleware) — they come from DI metadata at
+                // runtime and include framework-registered items that the
+                // agent's static file scan can't see. We also forward the
+                // *names* of those items so the Studio drill-down can list
+                // them. No-op when Studio is disabled or when the installed
+                // agent is too old to support it.
+                (0, index_js_1.reportStudioRuntimeInfo)({
+                    appPort: this.port,
+                    globalPrefix: this.globalPrefix,
+                    startupMs: Date.now() - listenStartedAt,
+                    providerCount: this.lastApplicationMetrics?.providers,
+                    interceptorCount: this.lastApplicationMetrics?.interceptors,
+                    middlewareCount: this.lastApplicationMetrics?.middleware,
+                    runtimeItems: this.collectStudioRuntimeItems(),
                 });
+                // Setup signal handlers for graceful shutdown
+                // Supported signals:
+                // - SIGTERM: Standard termination (Kubernetes, Docker, process managers)
+                // - SIGINT: User interrupt (Ctrl+C)
+                // - SIGHUP: Terminal hangup
+                // - SIGQUIT: Quit with core dump request
+                // - SIGBREAK: Windows break signal (Ctrl+Break)
+                // - SIGUSR2: Used by nodemon for restart (not on Windows)
+                const shutdownSignals = [
+                    "SIGTERM",
+                    "SIGINT",
+                    "SIGHUP",
+                    "SIGQUIT",
+                    "SIGBREAK",
+                    ...(process.platform !== "win32" ? ["SIGUSR2"] : []),
+                ];
+                for (const signal of shutdownSignals) {
+                    // Skip if handler already registered (prevents duplicates)
+                    if (this.shutdownHandlers.has(signal)) {
+                        continue;
+                    }
+                    const handler = () => {
+                        // Prevent multiple shutdown attempts
+                        if (this.isShuttingDown) {
+                            return;
+                        }
+                        this.isShuttingDown = true;
+                        // Use console.log for shutdown messages - synchronous and guaranteed to write before exit
+                        console.log(`\n📡 Signal ${signal} received, initiating graceful shutdown...`);
+                        // Execute shutdown hooks and exit
+                        this.handleExit(signal)
+                            .then(() => {
+                            console.log("✅ Graceful shutdown completed");
+                            process.exit(0);
+                        })
+                            .catch((error) => {
+                            console.error(`❌ Error during shutdown: ${error.message}`);
+                            process.exit(1);
+                        });
+                    };
+                    // Store handler for later removal and register it
+                    this.shutdownHandlers.set(signal, handler);
+                    process.on(signal, handler);
+                }
+                // Setup exit handler to force-close connections immediately
+                // This is a last-resort handler for when signals don't arrive or complete in time
+                // (e.g., during hot-reload when the process is killed quickly)
+                const exitHandler = () => {
+                    if (this.serverInstance) {
+                        // Synchronously destroy all connections - this is our last chance
+                        this.destroyAllConnections();
+                        // Try to close the server synchronously (won't block but releases the port faster)
+                        try {
+                            this.serverInstance.close();
+                        }
+                        catch {
+                            // Ignore errors during exit
+                        }
+                    }
+                };
+                // Register exit handler (only once)
+                if (!this.shutdownHandlers.has("exit")) {
+                    this.shutdownHandlers.set("exit", exitHandler);
+                    process.once("exit", exitHandler);
+                }
                 try {
-                    await this.postServerInitialization();
+                    // Call user's postServerInitialization hook
+                    await this.handleSyncOrAsync(this.postServerInitialization());
+                    // Execute bootstrap lifecycle hooks on all IBootstrap providers
+                    if (this.lifecycleRegistry) {
+                        await this.lifecycleRegistry.executeBootstrap();
+                    }
                     resolve(this);
                 }
                 catch (error) {
@@ -236,11 +708,185 @@ class AppExpress {
                 }
             });
             this.serverInstance?.on("error", (error) => {
-                this.logger.error(`Error starting server: ${error.message}`, "adapter-express");
-                reject(error);
+                // Handle EADDRINUSE error with helpful suggestions
+                if (error.code === "EADDRINUSE") {
+                    const port = this.port;
+                    const errorMessage = `Port ${port} is already in use`;
+                    const suggestions = [
+                        `Try a different port: Set PORT environment variable to another value`,
+                        `Find and stop the process using port ${port}`,
+                        process.platform === "win32"
+                            ? `On Windows: netstat -ano | findstr :${port}`
+                            : `On Linux/Mac: lsof -ti:${port} | xargs kill`,
+                    ];
+                    this.logger.error(errorMessage, "adapter-express");
+                    this.logger.info("💡 Suggestions:", "adapter-express");
+                    suggestions.forEach((suggestion) => {
+                        this.logger.info(`   • ${suggestion}`, "adapter-express");
+                    });
+                    reject(new Error(`${errorMessage}. ${suggestions[0]}`));
+                }
+                else {
+                    this.logger.error(`Error starting server: ${error.message}`, "adapter-express");
+                    reject(error);
+                }
+            });
+        });
+    }
+    /**
+     * Close existing server instance if it exists.
+     * @private
+     */
+    async closeExistingServer() {
+        if (this.serverInstance) {
+            return new Promise((resolve) => {
+                this.serverInstance.close(() => {
+                    this.serverInstance = null;
+                    resolve();
+                });
+                // Force close after timeout
+                setTimeout(() => {
+                    if (this.serverInstance) {
+                        this.serverInstance = null;
+                        resolve();
+                    }
+                }, 1000);
+            });
+        }
+    }
+    /**
+     * Wait for a specified duration.
+     * @private
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Kill the process using a specific port.
+     * @private
+     */
+    async killProcessOnPort(port) {
+        const { exec } = await Promise.resolve().then(() => __importStar(require("child_process")));
+        const { promisify } = await Promise.resolve().then(() => __importStar(require("util")));
+        const execAsync = promisify(exec);
+        try {
+            if (process.platform === "win32") {
+                // Windows: Find PID using netstat and kill it
+                const { stdout } = await execAsync(`netstat -ano | findstr :${port} | findstr LISTENING`);
+                const lines = stdout.trim().split("\n");
+                for (const line of lines) {
+                    const parts = line.trim().split(/\s+/);
+                    const pid = parts[parts.length - 1];
+                    if (pid && pid !== String(process.pid) && /^\d+$/.test(pid)) {
+                        try {
+                            await execAsync(`taskkill /F /PID ${pid}`);
+                            return true;
+                        }
+                        catch {
+                            // Process might have already exited
+                        }
+                    }
+                }
+            }
+            else {
+                // Linux/Mac: Use lsof to find PID and kill it
+                try {
+                    const { stdout } = await execAsync(`lsof -ti:${port}`);
+                    const pids = stdout.trim().split("\n").filter(Boolean);
+                    for (const pid of pids) {
+                        if (pid !== String(process.pid)) {
+                            try {
+                                await execAsync(`kill -9 ${pid}`);
+                                return true;
+                            }
+                            catch {
+                                // Process might have already exited
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // No process found on port
+                }
+            }
+        }
+        catch {
+            // Command failed - port might already be free
+        }
+        return false;
+    }
+    /**
+     * Check if the port is available by attempting to bind to it.
+     * @private
+     */
+    async isPortAvailable(port) {
+        const net = await Promise.resolve().then(() => __importStar(require("net")));
+        return new Promise((resolve) => {
+            const testServer = net.createServer();
+            testServer.once("error", () => {
+                resolve(false);
+            });
+            testServer.once("listening", () => {
+                testServer.close(() => {
+                    resolve(true);
+                });
             });
+            testServer.listen(port);
         });
     }
+    /**
+     * Ensure the port is available, killing the existing process if needed.
+     * This is the safest approach for hot-reload scenarios.
+     * @private
+     */
+    async ensurePortAvailable(port) {
+        // First, check if port is already available
+        if (await this.isPortAvailable(port)) {
+            return true;
+        }
+        // Try to kill the process on the port
+        let killed = await this.killProcessOnPort(port);
+        if (killed) {
+            // Wait a moment for the port to be released
+            await this.delay(500);
+        }
+        // Retry multiple times to check if port is now available
+        // Hot reload scenarios may need more time for the old process to shut down
+        for (let attempt = 1; attempt <= this.portRetryAttempts; attempt++) {
+            if (await this.isPortAvailable(port)) {
+                return true;
+            }
+            // Try to kill again if still not available (process might be slow to release)
+            if (attempt % 3 === 0) {
+                killed = await this.killProcessOnPort(port);
+                if (killed) {
+                    await this.delay(300);
+                }
+            }
+            if (attempt < this.portRetryAttempts) {
+                await this.delay(this.portRetryDelay);
+            }
+        }
+        return false;
+    }
+    /**
+     * Remove existing shutdown signal handlers to prevent duplicates.
+     * @private
+     */
+    removeShutdownHandlers() {
+        this.shutdownHandlers.forEach((handler, signal) => {
+            // Handle "exit" event specially (it's not a signal but we track it the same way)
+            if (signal === "exit") {
+                process.removeListener("exit", handler);
+            }
+            else {
+                process.removeListener(signal, handler);
+            }
+        });
+        this.shutdownHandlers.clear();
+        // Also clear any tracked connections from previous runs
+        this.activeConnections.clear();
+    }
     /**
      * Sets the global route prefix for the application.
      * @method setGlobalRoutePrefix
@@ -257,13 +903,13 @@ class AppExpress {
         if (this.renderOptions.engine) {
             switch (this.renderOptions.engine) {
                 case shared_1.RenderEngine.Engine.HBS:
-                    await (0, engine_1.setEngineHandlebars)(this.app, this.renderOptions.options);
+                    await (0, engine_js_1.setEngineHandlebars)(this.app, this.renderOptions.options);
                     break;
                 case shared_1.RenderEngine.Engine.EJS:
-                    await (0, engine_1.setEngineEjs)(this.app, this.renderOptions.options);
+                    await (0, engine_js_1.setEngineEjs)(this.app, this.renderOptions.options);
                     break;
                 case shared_1.RenderEngine.Engine.PUG:
-                    await (0, engine_1.setEnginePug)(this.app, this.renderOptions.options);
+                    await (0, engine_js_1.setEnginePug)(this.app, this.renderOptions.options);
                     break;
                 default:
                     throw new Error("Unsupported engine type!");
@@ -279,8 +925,113 @@ class AppExpress {
      * @param {EngineOptions} [options] - The configuration options for the view engine
      * @public API
      */
+    /**
+     * Configure the startup banner display.
+     * Can be called in configureServices() or globalConfiguration().
+     *
+     * @param config - Banner configuration options
+     * @example
+     * ```typescript
+     * export class App extends AppExpress {
+     *   configureServices(): void {
+     *     this.setBanner({
+     *       style: "full",
+     *       showMetrics: true,
+     *       showFeatures: true,
+     *       showConfig: true,
+     *       showPerformance: true,
+     *       showResources: true,
+     *       // Environment-specific overrides
+     *       environment: {
+     *         production: {
+     *           style: "compact",
+     *           showConfig: false,
+     *           showResources: false,
+     *         },
+     *       },
+     *     });
+     *   }
+     * }
+     * ```
+     * @public API
+     */
+    setBanner(config) {
+        this.bannerConfig = config;
+    }
+    /**
+     * Configure ExpressoTS Studio integration.
+     * When enabled and @expressots/studio-agent is installed, automatically
+     * instruments the application for request recording and real-time monitoring.
+     *
+     * By default, Studio is auto-enabled in development if the package is installed.
+     * Use this method to customize behavior or enable in production.
+     *
+     * @param config - Studio configuration options
+     * @example
+     * ```typescript
+     * export class App extends AppExpress {
+     *   configureServices(): void {
+     *     this.setStudio({
+     *       enabled: true,    // Force enable (default: auto in dev)
+     *       port: 3334,       // WebSocket port for UI connection
+     *       serviceName: 'my-app', // Service name for tracing
+     *     });
+     *   }
+     * }
+     * ```
+     * @public API
+     */
+    setStudio(config) {
+        this.studioConfig = config;
+    }
+    /**
+     * Check if ExpressoTS Studio is currently enabled.
+     * @returns Boolean indicating if Studio Agent is running.
+     * @public API
+     */
+    isStudioEnabled() {
+        return (0, index_js_1.isStudioEnabled)();
+    }
+    /**
+     * Configure a view engine for server-side rendering.
+     *
+     * @deprecated Use `this.Middleware.render()` instead. Will be removed in v5.0.0.
+     *
+     * @example Migration
+     * ```typescript
+     * // Before (deprecated)
+     * this.setEngine(RenderEngine.Engine.EJS, { viewsDir: 'views' });
+     *
+     * // After (recommended)
+     * this.Middleware.render({ engine: 'ejs', viewsDir: 'views' });
+     *
+     * // Or with auto-detection
+     * this.Middleware.render();
+     * ```
+     *
+     * @param engine - The view engine to set
+     * @param options - The configuration options for the view engine
+     * @public API
+     */
     async setEngine(engine, options) {
+        this.logger.warn("setEngine() is deprecated. Use this.Middleware.render() instead. Will be removed in v5.0.0.", "adapter-express");
         try {
+            // Bridge to new render system
+            const engineMap = {
+                ejs: "ejs",
+                pug: "pug",
+                hbs: "hbs",
+            };
+            const engineName = engineMap[engine] || engine;
+            // Try to use the new render system
+            await this.Middleware.render({
+                engine: engineName,
+                viewsDir: options?.viewsDir,
+                partialsDir: options?.partialsDir,
+            });
+        }
+        catch {
+            // Fallback to old system if new system fails
             if (options) {
                 this.renderOptions = { engine, options };
             }
@@ -288,9 +1039,6 @@ class AppExpress {
                 this.renderOptions = { engine };
             }
         }
-        catch (error) {
-            this.logger.error(error.message, "adapter-express");
-        }
     }
     /**
      * Verifies if the current environment is development.
@@ -298,61 +1046,277 @@ class AppExpress {
      * @public API
      */
     async isDevelopment() {
+        // Check Express app environment first (most reliable)
         if (this.app) {
             return this.app.get("env") === "development";
         }
-        this.appContainer.Container.get(core_1.Logger).error("isDevelopment() method must be called on `PostServerInitialization`", "application");
+        // Fallback to this.environment (set by bootstrap())
+        if (this.environment) {
+            return this.environment === "development";
+        }
+        // Fallback to process.env.NODE_ENV
+        if (process.env.NODE_ENV) {
+            return process.env.NODE_ENV === "development";
+        }
+        // Default to false if nothing is set
         return false;
     }
     /**
-     * Load environment variables from the specified file based on the environment configuration.
-     * @param environment - The environment to load configuration for.
-     * @param options - The options to use for loading the environment configuration.
-     * @option env - The environment configuration options.
-     * @example
-     * ```typescript
-     * {
-              env: {
-                  development: ".env.development",
-                  production: ".env.production"
-              }
-          }
-      * ```
+     * Get the underlying HTTP server. (default: Express.js)
+     * @returns The underlying HTTP server after initialization.
+     * @public API
+     */
+    async getHttpServer() {
+        if (!this.serverInstance) {
+            this.logger.error("Server instance not initialized yet", "adapter-express");
+            throw new Error("Server instance not initialized yet");
+        }
+        return Promise.resolve(this.serverInstance);
+    }
+    /**
+     * Get the port the server is listening on.
+     * Useful for dynamic port assignment (port: 0) in testing scenarios.
+     * @returns The actual port number the server is bound to.
      * @public API
      */
-    async initEnvironment(environment, options) {
-        this.environment = environment;
-        if (options === undefined) {
-            (0, shared_1.config)({ path: ".env" });
+    async getPort() {
+        if (!this.serverInstance) {
+            this.logger.error("Server instance not initialized yet", "adapter-express");
+            throw new Error("Server instance not initialized yet");
+        }
+        const address = this.serverInstance.address();
+        if (address && typeof address === "object" && "port" in address) {
+            return Promise.resolve(address.port);
+        }
+        throw new Error("Unable to determine server port");
+    }
+    /**
+     * Detect API versions from @Version() decorators on controllers.
+     * @returns Array of unique API versions (e.g., ["v1", "v2"])
+     * @private
+     */
+    detectApiVersions() {
+        try {
+            const controllers = (0, utils_js_1.getControllersFromMetadata)();
+            const versions = new Set();
+            controllers.forEach((controllerTarget) => {
+                // Cast DecoratorTarget to NewableFunction for metadata access
+                const controllerConstructor = controllerTarget;
+                // Check controller-level version
+                const controllerMetadata = (0, utils_js_1.getControllerMetadata)(controllerConstructor);
+                if (controllerMetadata?.version) {
+                    const version = String(controllerMetadata.version);
+                    // Normalize version format (ensure "v" prefix)
+                    const normalizedVersion = version.startsWith("v") ? version : `v${version}`;
+                    versions.add(normalizedVersion);
+                }
+                // Check method-level versions
+                const methodMetadata = (0, utils_js_1.getControllerMethodMetadata)(controllerConstructor);
+                if (methodMetadata) {
+                    methodMetadata.forEach((method) => {
+                        if (method.version) {
+                            const version = String(method.version);
+                            const normalizedVersion = version.startsWith("v") ? version : `v${version}`;
+                            versions.add(normalizedVersion);
+                        }
+                    });
+                }
+            });
+            return Array.from(versions).sort();
         }
-        else {
-            if (!options.env[environment]) {
-                this.logger.error(`Environment configuration for [${environment}] does not exist.`, "adapter-express");
-                process_1.default.exit(1);
+        catch (error) {
+            // If metadata not available, return empty array
+            return [];
+        }
+    }
+    /**
+     * Harvest provider + interceptor *names* from DI metadata so the
+     * Studio Status page can drill down into the items behind the
+     * "Providers" / "Interceptors" counters.
+     *
+     * Reads the same metadata that {@link MetricsCollector} uses for the
+     * CLI banner — so what shows up here is the source of truth, not the
+     * agent's static file scan (which can't see framework-registered
+     * items like `Logger` or `LifecycleRegistry`).
+     *
+     * Returns `undefined` instead of an empty object so {@link
+     * reportStudioRuntimeInfo} can skip forwarding when nothing was
+     * harvested (keeps the WS payload small).
+     */
+    collectStudioRuntimeItems() {
+        try {
+            const providerMetadata = Reflect.getMetadata(PROVIDE_METADATA_KEY, Reflect) || [];
+            const providers = [];
+            for (const entry of providerMetadata) {
+                const name = entry?.implementationType?.name;
+                if (typeof name === "string" && name.length > 0) {
+                    providers.push({ name, source: "provide" });
+                }
             }
-            else {
-                const envFileName = options.env[environment];
-                if (!fs_1.default.existsSync(envFileName)) {
-                    this.logger.error(`Environment file [${envFileName}] does not exist.`, "adapter-express");
-                    process_1.default.exit(1);
+            const interceptorMetadata = Reflect.getMetadata(core_1.INTERCEPTOR_METADATA_KEY.interceptor, Reflect) || [];
+            const interceptors = [];
+            for (const entry of interceptorMetadata) {
+                const name = entry?.interceptor?.name;
+                if (typeof name === "string" && name.length > 0) {
+                    interceptors.push({
+                        name,
+                        priority: entry?.priority,
+                        source: "metadata",
+                    });
                 }
-                else {
-                    (0, shared_1.config)({ path: envFileName });
+            }
+            // Bail out if both lists are empty — nothing useful to forward.
+            if (providers.length === 0 && interceptors.length === 0) {
+                return undefined;
+            }
+            return { providers, interceptors };
+        }
+        catch {
+            // Metadata reads should never break boot. Status page just falls
+            // back to its static-scan list.
+            return undefined;
+        }
+    }
+    /**
+     * Display middleware startup logs after the banner.
+     * This makes startup logging transparent to the user - no need for manual code in postServerInitialization().
+     * @private
+     */
+    displayMiddlewareStartupLogs() {
+        const isDev = this.environment === "development";
+        if (!isDev)
+            return;
+        const startupLogs = this.Middleware.getStartupLogs();
+        if (startupLogs.length === 0)
+            return;
+        startupLogs.forEach((log) => {
+            if (log.type === "warn") {
+                this.logger.warn(log.message, "middleware");
+            }
+            else {
+                this.logger.info(log.message, "middleware");
+            }
+        });
+        this.Middleware.clearStartupLogs();
+    }
+    /**
+     * Display startup banner with application metrics.
+     * @param appInfo - Application info
+     * @private
+     */
+    displayStartupBanner(appInfo) {
+        if (!this.bannerGenerator) {
+            // Fallback to old console message if banner generator not initialized
+            this.console.messageServer(this.port, this.environment || "development", appInfo);
+            // Log CI detection after banner, before middleware logs
+            this.displayCIDetectionLogs(appInfo);
+            // Still display middleware startup logs even in fallback mode
+            this.displayMiddlewareStartupLogs();
+            return;
+        }
+        try {
+            let finalAppInfo = appInfo;
+            if (!finalAppInfo?.apiVersions || finalAppInfo.apiVersions.length === 0) {
+                const apiVersions = this.detectApiVersions();
+                if (apiVersions.length > 0) {
+                    finalAppInfo = {
+                        ...appInfo,
+                        appName: appInfo?.appName || "App",
+                        appVersion: appInfo?.appVersion || "not provided",
+                        apiVersions,
+                    };
                 }
             }
+            // Detect API versions from controllers
+            const detectedApiVersions = finalAppInfo?.apiVersions || [];
+            // Collect metrics. Cache the result on the instance so the Studio
+            // integration can forward the *runtime* counts (providers /
+            // interceptors / middleware) to the agent — those values come from
+            // DI metadata and registries, which our static file scanner can't
+            // see, so without this the Studio Status page would disagree with
+            // the CLI banner.
+            const { metrics, features } = core_1.MetricsCollector.collect(this.appContainer.Container, {
+                getControllersFromMetadata: () => (0, utils_js_1.getControllersFromMetadata)(),
+                getControllersFromContainer: () => (0, utils_js_1.getControllersFromContainer)(this.appContainer.Container, false),
+                getControllerMethodMetadata: (constructor) => (0, utils_js_1.getControllerMethodMetadata)(constructor),
+                getMiddlewareCount: () => this.Middleware.getMiddlewarePipeline().length,
+                hasContentNegotiation: () => !!this.Middleware.getContentNegotiationService(),
+                hasSmartValidation: () => !!this.Middleware.getValidationConfig(),
+                hasAuthorization: () => this.appContainer.Container.isBound("IGuardCache"),
+                hasExceptionFilters: () => !!this.Middleware.getErrorHandler(),
+                hasApiVersioning: () => detectedApiVersions.length > 0,
+                hasGlobalRoutePrefix: () => !!this.globalPrefix && this.globalPrefix !== "/",
+                hasErrorHandler: () => !!this.Middleware.getErrorHandler(),
+                hasRequestLogging: () => {
+                    // Check if any request logging middleware is in the pipeline
+                    const pipeline = this.Middleware.getPipelineInfo();
+                    return pipeline.entries.some((e) => e.category === "logging" || e.name.toLowerCase().includes("logging"));
+                },
+            });
+            // Persist the metrics so `reportStudioRuntimeInfo` (called from the
+            // listen callback) can forward live provider/interceptor counts.
+            this.lastApplicationMetrics = metrics;
+            // Discover providers for introspection
+            this.Provider.discover();
+            // Get middleware and provider views for banner
+            const middlewareView = this.Middleware.getFormattedView();
+            const providerView = this.Provider.getFormattedView();
+            // Prepare banner data with extended info
+            const bannerData = {
+                appInfo: finalAppInfo,
+                metrics,
+                features,
+                middlewareView,
+                providerView,
+            };
+            // Display banner
+            this.bannerGenerator.display(this.port, this.environment || "development", finalAppInfo, metrics, features, {
+                "Global Prefix": this.globalPrefix || "/",
+                "Node Version": process.version,
+                Platform: process.platform,
+            }, bannerData);
+            // Log CI detection after banner, before middleware logs
+            this.displayCIDetectionLogs(appInfo);
+            // Automatically display middleware startup logs after banner (transparent to user)
+            this.displayMiddlewareStartupLogs();
+        }
+        catch (error) {
+            // Fallback to old console message on error
+            this.logger.warn("Failed to display startup banner, using fallback", "adapter-express", error);
+            this.console.messageServer(this.port, this.environment || "development", appInfo);
+            // Log CI detection after banner, before middleware logs
+            this.displayCIDetectionLogs(appInfo);
+            // Still display middleware startup logs even in fallback mode
+            this.displayMiddlewareStartupLogs();
         }
     }
     /**
-     * Get the underlying HTTP server. (default: Express.js)
-     * @returns The underlying HTTP server after initialization.
-     * @public API
+     * Display CI detection logs after the banner but before middleware logs.
+     * @param appInfo - Application info containing CI detection data
+     * @private
      */
-    async getHttpServer() {
-        if (!this.serverInstance) {
-            this.logger.error("Server instance not initialized yet", "adapter-express");
-            throw new Error("Server instance not initialized yet");
+    displayCIDetectionLogs(appInfo) {
+        if (appInfo?.ciDetection?.detected) {
+            this.logger.info(`🔍 CI environment detected: ${appInfo.ciDetection.platform}`, "bootstrap");
+            this.logger.info(`✅ Skipping .env file loading (using process.env)`, "bootstrap");
         }
-        return Promise.resolve(this.serverInstance);
     }
 }
 exports.AppExpress = AppExpress;
+// Log buffering for banner-first display
+// IMPORTANT: All these properties must be declared BEFORE initBuffering!
+AppExpress.originalStdoutWrite = null;
+AppExpress.originalStderrWrite = null;
+AppExpress.logBuffer = [];
+AppExpress.isBuffering = false;
+AppExpress.bufferingInitialized = false;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+AppExpress.originalGlobalConsole = null;
+// Initialize buffering when AppExpress class is loaded (before any instances are created)
+// This ensures ALL logs are buffered from the very beginning for the full template.
+// The micro() function explicitly disables this buffering since it doesn't use the banner system.
+// This MUST be declared AFTER all the static properties it uses!
+AppExpress.initBuffering = (() => {
+    AppExpress.startLogBuffering();
+    return true;
+})();