@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/application/bootstrap.js

@@ -0,0 +1,709 @@
+import { config, parse } from "@expressots/shared";
+import { AppFactory } from "./application-factory.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import fs from "fs";
+import path from "path";
+/**
+ * Synchronously load `.env` files into `process.env`.
+ *
+ * Call this **before** `bootstrap()` or `defineConfig()` so that every
+ * environment variable is available when the rest of the application
+ * resolves configuration, binds services, or reads `Env.*` builders.
+ *
+ * ### How it works
+ *
+ * 1. Reads `process.env.NODE_ENV` (defaults to `"development"`).
+ * 2. Loads files in priority order (last file wins on conflicts):
+ *    `.env` → `.env.local` → `.env.{env}.local` → `.env.{env}`
+ * 3. If `options.files` maps the current environment to a custom name
+ *    (e.g. `{ production: ".env.prod" }`), that name replaces `.env.{env}`.
+ * 4. Missing files are silently skipped.
+ * 5. Sets `process.env._EXPRESSOTS_ENV_LOADED = "true"` so subsequent
+ *    calls are no-ops (unless `force: true`).
+ *
+ * ### Important
+ *
+ * `NODE_ENV` must already be set in the **shell** (or inherited from
+ * the process) before `loadEnvSync()` runs. The function reads
+ * `process.env.NODE_ENV` to decide which file to load; it does **not**
+ * derive the environment from file contents.
+ *
+ * @param options - See {@link LoadEnvSyncOptions} for all fields.
+ *
+ * @example Zero-config (recommended for most apps)
+ * ```typescript
+ * // src/main.ts
+ * import { bootstrap, loadEnvSync } from "@expressots/core";
+ * import { App } from "./app";
+ *
+ * loadEnvSync();          // .env + .env.development (or .env.production, etc.)
+ * void bootstrap(App);
+ * ```
+ *
+ * @example Custom file mapping
+ * ```typescript
+ * loadEnvSync({
+ *   files: {
+ *     development: ".env",
+ *     production:  ".env.prod",
+ *     staging:     ".env.staging",
+ *   },
+ * });
+ * // With NODE_ENV=production  -> .env + .env.prod
+ * // With NODE_ENV=development -> .env  (mapped to itself, so loaded once)
+ * ```
+ *
+ * @example With defineConfig()
+ * ```typescript
+ * // src/config.ts
+ * import { defineConfig, Env, loadEnvSync } from "@expressots/core";
+ *
+ * loadEnvSync({ files: { production: ".env.prod" } });
+ *
+ * export const appConfig = defineConfig({
+ *   server: { port: Env.port("PORT", { default: 3000 }) },
+ * });
+ * ```
+ *
+ * @example Force reload (hot-module replacement)
+ * ```typescript
+ * loadEnvSync({ force: true });
+ * ```
+ *
+ * @see {@link LoadEnvSyncOptions} for option details
+ * @see {@link BootstrapOptions.envFileConfig} for the bootstrap()-level alternative
+ * @public
+ */
+export function loadEnvSync(options) {
+    // Skip if already loaded (unless force reload)
+    if (process.env._EXPRESSOTS_ENV_LOADED === "true" && !options?.force) {
+        return;
+    }
+    // Determine current environment
+    const currentEnvironment = process.env.NODE_ENV ?? "development";
+    // Determine the file name for current environment
+    const envFileName = options?.files?.[currentEnvironment] ?? `.env.${currentEnvironment}`;
+    // Load optional base files first (they get overridden by environment-specific file)
+    // Use override: true to ensure new values overwrite existing ones (important for hot reload)
+    const optionalFiles = [".env", ".env.local", `${envFileName}.local`];
+    for (const file of optionalFiles) {
+        try {
+            if (fs.existsSync(file)) {
+                config({ path: file, override: true });
+            }
+        }
+        catch {
+            // Silently skip optional files
+        }
+    }
+    // Load the environment-specific file
+    if (fs.existsSync(envFileName)) {
+        config({ path: envFileName, override: true });
+    }
+    // Mark as loaded
+    process.env._EXPRESSOTS_ENV_LOADED = "true";
+}
+/**
+ * Cached CI environment detection result (immutable at runtime).
+ * @private
+ */
+let _isCI;
+/**
+ * Cached package.json data (immutable at runtime).
+ * @private
+ */
+let _packageCache;
+/**
+ * CI platform detection map for O(1) lookup.
+ * @private
+ */
+const CI_PLATFORM_MAP = new Map([
+    ["GITHUB_ACTIONS", "GitHub Actions"],
+    ["GITLAB_CI", "GitLab CI"],
+    ["JENKINS_URL", "Jenkins"],
+    ["CIRCLECI", "CircleCI"],
+    ["TRAVIS", "Travis CI"],
+    ["BUILDKITE", "Buildkite"],
+    ["AZURE_HTTP_USER_AGENT", "Azure DevOps"],
+    ["BAMBOO_BUILDKEY", "Bamboo"],
+    ["TEAMCITY_VERSION", "TeamCity"],
+]);
+/**
+ * Platform-specific hint generators (memoized functions).
+ * @private
+ */
+const PLATFORM_HINTS = new Map([
+    [
+        "GitHub Actions",
+        (missingVars) => `
+🔧 GitHub Actions Setup:
+   - Go to: Settings → Secrets and variables → Actions
+   - Add repository secrets for: ${missingVars}
+   - Use: \${{ secrets.VARIABLE_NAME }} in workflow files`,
+    ],
+    [
+        "GitLab CI",
+        (missingVars) => `
+🔧 GitLab CI Setup:
+   - Go to: Settings → CI/CD → Variables
+   - Add CI/CD variables for: ${missingVars}
+   - Use: $VARIABLE_NAME in .gitlab-ci.yml`,
+    ],
+    [
+        "Jenkins",
+        (missingVars) => `
+🔧 Jenkins Setup:
+   - Configure: Manage Jenkins → Credentials
+   - Add credentials for: ${missingVars}
+   - Use: env.VARIABLE_NAME in pipeline`,
+    ],
+]);
+/**
+ * Detect if running in CI/CD environment.
+ * Result is cached since CI environment doesn't change at runtime.
+ *
+ * @returns True if running in CI/CD
+ * @private
+ * @performance Cached result for O(1) subsequent calls
+ */
+function isCIEnvironment() {
+    if (_isCI === undefined) {
+        _isCI = !!((process.env.CI || // Generic CI flag
+            process.env.GITHUB_ACTIONS || // GitHub Actions
+            process.env.GITLAB_CI || // GitLab CI
+            process.env.JENKINS_URL || // Jenkins
+            process.env.CIRCLECI || // CircleCI
+            process.env.TRAVIS || // Travis CI
+            process.env.BUILDKITE || // Buildkite
+            process.env.AZURE_HTTP_USER_AGENT || // Azure DevOps
+            process.env.BAMBOO_BUILDKEY || // Bamboo
+            process.env.TEAMCITY_VERSION) // TeamCity
+        );
+    }
+    return _isCI;
+}
+/**
+ * Detect CI/CD platform name using optimized Map lookup.
+ *
+ * @returns Platform name or "CI Platform"
+ * @private
+ * @performance O(n) where n is number of platforms (typically 9), but uses Map for efficient iteration
+ */
+function detectCIPlatform() {
+    for (const [envKey, platformName] of CI_PLATFORM_MAP) {
+        if (process.env[envKey]) {
+            return platformName;
+        }
+    }
+    return "CI Platform";
+}
+/**
+ * Get platform-specific setup hints using memoized functions.
+ *
+ * @param platform - CI platform name
+ * @param missing - Missing variable names
+ * @returns Setup hint string
+ * @private
+ * @performance Uses pre-constructed Map for O(1) lookup
+ */
+function getPlatformHint(platform, missing) {
+    const missingVars = missing.join(", ");
+    const hintFn = PLATFORM_HINTS.get(platform);
+    return (hintFn?.(missingVars) ||
+        `Configure secrets in your CI/CD platform for: ${missingVars}`);
+}
+/**
+ * Custom error for missing environment file.
+ * @private
+ */
+class EnvFileNotFoundError extends Error {
+    constructor(fileName, environment) {
+        const template = getEnvTemplate(environment);
+        super(`
+❌ Missing required environment file: ${fileName}
+
+💡 Create ${fileName} with:
+${template}
+
+📖 Docs: https://expresso-ts.com/docs/env
+🔍 Check existing files: ls -la .env*
+    `.trim());
+        this.name = "EnvFileNotFoundError";
+    }
+}
+/**
+ * Custom error for CI/CD environment validation.
+ * @private
+ */
+class CIEnvValidationError extends Error {
+    constructor(missing, environment) {
+        const ciPlatform = detectCIPlatform();
+        const platformHint = getPlatformHint(ciPlatform, missing);
+        super(`
+❌ CI/CD Environment Validation Failed
+
+Missing required environment variables in ${environment}:
+${missing.map((key) => `   • ${key}`).join("\n")}
+
+${platformHint}
+
+💡 Action Required:
+   1. Add missing variables to your CI/CD platform secrets
+   2. Ensure variables are available in ${environment} environment
+   3. Check variable names match exactly (case-sensitive)
+
+📖 Docs: https://expresso-ts.com/docs/ci-cd
+    `.trim());
+        this.name = "CIEnvValidationError";
+    }
+}
+/**
+ * Custom error for environment variable validation.
+ * @private
+ */
+class EnvValidationError extends Error {
+    constructor(missing, fileName) {
+        super(`
+❌ Environment validation failed
+
+Missing values in ${fileName}:
+${missing.map((key) => `   • ${key} (required but empty)`).join("\n")}
+
+💡 Add values to ${fileName}:
+${missing.map((key) => `   ${key}=your-value-here`).join("\n")}
+
+📖 Docs: https://expresso-ts.com/docs/env
+    `.trim());
+        this.name = "EnvValidationError";
+    }
+}
+/**
+ * Get environment template content.
+ * @param environment - Environment name
+ * @returns Template string
+ * @private
+ */
+function getEnvTemplate(environment) {
+    return `PORT=3000
+NODE_ENV=${environment}
+# Add your environment variables here`;
+}
+/**
+ * Create environment file template.
+ * @param fileName - File name to create
+ * @param environment - Environment name (e.g., "development", "production")
+ * @param required - Required variable names
+ * @private
+ */
+async function createEnvTemplate(fileName, environment, required) {
+    const commonVars = [
+        "PORT=3000",
+        `NODE_ENV=${environment}`,
+        "# Add your environment variables below",
+    ];
+    const requiredVars = required?.map((key) => `${key}=`) || [];
+    const template = [...commonVars, ...requiredVars].join("\n");
+    await fs.promises.writeFile(fileName, template, "utf-8");
+}
+/**
+ * Validate environment variables from process.env.
+ * @param required - Required variable names
+ * @returns Validation result
+ * @private
+ */
+function validateEnvVariablesFromProcessEnv(required) {
+    const missing = [];
+    for (const key of required) {
+        const value = process.env[key];
+        if (!value || value.trim() === "") {
+            missing.push(key);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+/**
+ * Validate environment variables from file.
+ * @param fileName - Environment file name
+ * @param required - Required variable names (if empty, validates all in file)
+ * @returns Validation result
+ * @private
+ */
+function validateEnvVariablesFromFile(fileName, required) {
+    const missing = [];
+    if (!fs.existsSync(fileName)) {
+        return { valid: false, missing: required ? [...required] : [] };
+    }
+    try {
+        const fileContent = fs.readFileSync(fileName, "utf-8");
+        const parsed = parse(fileContent);
+        if (required && required.length > 0) {
+            // Validate only required variables
+            for (const key of required) {
+                const value = process.env[key];
+                if (!value || value.trim() === "") {
+                    missing.push(key);
+                }
+            }
+        }
+        else {
+            // Validate all variables in file
+            for (const key of Object.keys(parsed)) {
+                const value = process.env[key];
+                if (!value || value.trim() === "") {
+                    missing.push(key);
+                }
+            }
+        }
+    }
+    catch (error) {
+        // File exists but couldn't be parsed
+        throw new Error(`Failed to parse ${fileName}: ${error}`);
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+/**
+ * Load and validate environment files with smart defaults.
+ *
+ * **Important:** This function only runs if `envFileConfig` is explicitly provided.
+ * If `envFileConfig` is `undefined`, .env file loading is skipped entirely.
+ *
+ * @param currentEnvironment - Current environment name (e.g., "development", "production")
+ * @param envFileConfig - Environment file configuration from BootstrapOptions.envFileConfig
+ * @returns Environment loading result
+ * @private
+ */
+async function loadAndValidateEnvironment(currentEnvironment, envFileConfig) {
+    const result = {
+        loaded: [],
+        validated: false,
+        warnings: [],
+    };
+    // 🎯 OPT-OUT: If envFileConfig is not provided, skip .env file loading entirely
+    // Templates can opt-in by providing envFileConfig in their bootstrap calls
+    if (!envFileConfig) {
+        result.validated = true;
+        process.env._EXPRESSOTS_ENV_LOADED = "true";
+        return result;
+    }
+    const isCI = envFileConfig.ciMode ?? isCIEnvironment();
+    const skipFileLoading = envFileConfig.skipFileLoading ?? false;
+    // 🎯 CI/CD: Skip file loading, use process.env directly
+    if (isCI || skipFileLoading) {
+        if (isCI) {
+            // Store CI info for logging after banner is displayed
+            result.ciDetected = true;
+            result.ciPlatform = detectCIPlatform();
+        }
+        // Support .env.vault in CI/CD
+        if (process.env.DOTENV_KEY) {
+            try {
+                config({ path: ".env.vault" });
+                result.loaded.push(".env.vault (encrypted)");
+            }
+            catch (error) {
+                result.warnings.push(`Warning: Could not load .env.vault: ${error}`);
+            }
+        }
+        // Validate required variables from process.env
+        const validateValues = envFileConfig.validateValues ?? true; // Always validate in CI
+        const required = (envFileConfig.required || []);
+        if (validateValues || required.length > 0) {
+            const validationResult = validateEnvVariablesFromProcessEnv(required);
+            if (!validationResult.valid) {
+                throw new CIEnvValidationError(validationResult.missing, currentEnvironment);
+            }
+        }
+        result.validated = true;
+        process.env._EXPRESSOTS_ENV_LOADED = "true";
+        return result;
+    }
+    // 🎯 Local Development: Load from files
+    const validateFile = envFileConfig.validateFile ?? true;
+    const validateValues = envFileConfig.validateValues ?? currentEnvironment === "production";
+    // Only auto-create if explicitly enabled (default: false - opt-in behavior)
+    const autoCreate = envFileConfig.autoCreateTemplate ?? false;
+    // 🎯 STEP 1: Create templates for all mapped environments (if autoCreate is enabled)
+    // If files mapping is provided, create templates for ALL mapped environments
+    // This helps users set up their project with all necessary .env files
+    if (autoCreate && envFileConfig.files) {
+        const createdTemplates = [];
+        for (const [envName, fileName] of Object.entries(envFileConfig.files)) {
+            if (!fs.existsSync(fileName)) {
+                await createEnvTemplate(fileName, envName, envFileConfig.required);
+                createdTemplates.push(fileName);
+                // Load the newly created file
+                config({ path: fileName });
+                result.loaded.push(fileName);
+            }
+        }
+        if (createdTemplates.length > 0) {
+            result.createdTemplates = createdTemplates;
+            result.createdTemplate = createdTemplates[0]; // For backward compatibility
+        }
+    }
+    // 🎯 STEP 2: Determine and load the file for the current environment
+    // Only ONE file is loaded at runtime - the file for the current environment
+    const envFileName = envFileConfig.files?.[currentEnvironment] ?? `.env.${currentEnvironment}`;
+    // Load optional files silently (override: true so later files win)
+    const optionalFiles = [".env", ".env.local", `${envFileName}.local`];
+    for (const file of optionalFiles) {
+        try {
+            config({ path: file, override: true });
+            result.loaded.push(file);
+        }
+        catch {
+            // Silently skip optional files
+        }
+    }
+    // 🎯 STEP 3: Handle the required file for current environment
+    const requiredFileExists = fs.existsSync(envFileName);
+    if (!requiredFileExists) {
+        if (autoCreate) {
+            // Auto-create template file with correct environment value
+            // This handles the case where files mapping wasn't provided but autoCreate is true
+            await createEnvTemplate(envFileName, currentEnvironment, envFileConfig.required);
+            if (!result.createdTemplates) {
+                result.createdTemplates = [];
+            }
+            result.createdTemplates.push(envFileName);
+            result.createdTemplate = envFileName;
+            // Reload the newly created file
+            config({ path: envFileName });
+            result.loaded.push(envFileName);
+        }
+        else if (validateFile) {
+            // Throw helpful error - but only if autoCreate is false
+            // Provide helpful message about all missing files if files mapping exists
+            const missingFiles = envFileConfig.files
+                ? Object.entries(envFileConfig.files)
+                    .filter(([, fileName]) => !fs.existsSync(fileName))
+                    .map(([envName, fileName]) => `${fileName} (for ${envName})`)
+                : [envFileName];
+            if (missingFiles.length > 1) {
+                throw new Error(`❌ Missing required environment files:\n${missingFiles.map((f) => `   • ${f}`).join("\n")}\n\n💡 Create these files or set autoCreateTemplate: true to auto-generate them.\n📖 Docs: https://expresso-ts.com/docs/env`);
+            }
+            else {
+                throw new EnvFileNotFoundError(envFileName, currentEnvironment);
+            }
+        }
+        else {
+            result.warnings.push(`⚠️  ${envFileName} not found (optional)`);
+        }
+    }
+    else {
+        // Load the environment-specific file (highest priority, overrides all previous)
+        config({ path: envFileName, override: true });
+        result.loaded.push(envFileName);
+    }
+    // Validate variables have values
+    if (validateValues ||
+        (envFileConfig.required && envFileConfig.required.length > 0)) {
+        const validationResult = validateEnvVariablesFromFile(envFileName, envFileConfig.required);
+        if (!validationResult.valid) {
+            throw new EnvValidationError(validationResult.missing, envFileName);
+        }
+    }
+    result.validated = true;
+    process.env._EXPRESSOTS_ENV_LOADED = "true";
+    return result;
+}
+/**
+ * Determine port with priority: options.port > process.env.PORT > 3000
+ * @param options - Bootstrap options
+ * @returns Port number
+ * @private
+ */
+function determinePort(options) {
+    // Priority: options.port > process.env.PORT > 3000
+    if (options?.port !== undefined) {
+        return options.port;
+    }
+    const envPort = process.env.PORT;
+    if (envPort) {
+        const port = parseInt(envPort, 10);
+        if (isNaN(port)) {
+            throw new Error(`Invalid PORT in .env: "${envPort}". Must be a number.`);
+        }
+        return port;
+    }
+    return 3000; // Default
+}
+/**
+ * Read package.json to get app name and version.
+ * Result is cached since package.json doesn't change at runtime.
+ *
+ * @returns Package.json data
+ * @private
+ * @performance Cached result for O(1) subsequent calls after first read
+ */
+async function readPackageJson() {
+    if (_packageCache !== undefined) {
+        return _packageCache;
+    }
+    try {
+        const packagePath = path.resolve(process.cwd(), "package.json");
+        const packageContent = await fs.promises.readFile(packagePath, "utf-8");
+        const pkg = JSON.parse(packageContent);
+        _packageCache = {
+            name: pkg.name,
+            version: pkg.version,
+        };
+        return _packageCache;
+    }
+    catch (error) {
+        // Package.json not found or invalid - cache empty result
+        _packageCache = {};
+        return _packageCache;
+    }
+}
+/**
+ * Type guard to check if argument is BootstrapConfig.
+ * Detects config objects by checking for the required structure.
+ * @internal
+ */
+function isBootstrapConfig(arg) {
+    if (!arg || typeof arg !== "object")
+        return false;
+    // Check if it has BootstrapOptions properties (direct options)
+    if ("appName" in arg || "port" in arg || "currentEnvironment" in arg) {
+        // If it has BootstrapOptions properties but NOT config structure, it's BootstrapOptions
+        if (!("app" in arg && "server" in arg)) {
+            return false;
+        }
+    }
+    // Check for config structure
+    return ("app" in arg &&
+        "server" in arg &&
+        typeof arg.app === "object" &&
+        arg.app !== null &&
+        typeof arg.server === "object" &&
+        arg.server !== null &&
+        "name" in arg.app &&
+        "version" in arg.app &&
+        "environment" in arg.app &&
+        "port" in arg.server);
+}
+/**
+ * Transform BootstrapConfig to BootstrapOptions.
+ * @internal
+ */
+function transformConfigToOptions(config) {
+    return {
+        appName: config.app.name,
+        appVersion: config.app.version,
+        port: config.server.port,
+        currentEnvironment: config.app.environment,
+        envFileConfig: config.bootstrap?.envFileConfig,
+    };
+}
+/** @internal Implementation overload. */
+export async function bootstrap(AppClass, optionsOrConfig) {
+    let logger;
+    // Note: Path resolution is auto-initialized as a side effect when
+    // @expressots/core is imported (see core/src/index.ts).
+    // This happens BEFORE bootstrap() runs, ensuring path aliases work.
+    // STEP 0: Load .env files FIRST (before config resolution)
+    // This ensures config reads from .env files when it resolves
+    let envFileConfig;
+    let currentEnvironment;
+    let envResult;
+    if (isBootstrapConfig(optionsOrConfig)) {
+        // Extract envFileConfig from config structure (static values, no resolution needed)
+        envFileConfig = optionsOrConfig.bootstrap?.envFileConfig;
+        // Determine environment: Use NODE_ENV first, then fallback to config
+        // We load .env files first to minimize impact of config resolution
+        currentEnvironment = process.env.NODE_ENV ?? "development";
+        // Load .env files BEFORE config resolution
+        envResult = await loadAndValidateEnvironment(currentEnvironment, envFileConfig);
+        // Now transform config (it will read from loaded .env files)
+        // This may trigger config resolution, but .env files are already loaded
+    }
+    else {
+        // BootstrapOptions - no config to resolve
+        currentEnvironment =
+            optionsOrConfig?.currentEnvironment ??
+                process.env.NODE_ENV ??
+                "development";
+        envFileConfig = optionsOrConfig?.envFileConfig;
+        // Load .env files
+        envResult = await loadAndValidateEnvironment(currentEnvironment, envFileConfig);
+    }
+    // Transform config to BootstrapOptions if needed (after .env files are loaded)
+    const options = isBootstrapConfig(optionsOrConfig)
+        ? transformConfigToOptions(optionsOrConfig)
+        : optionsOrConfig;
+    try {
+        // Show helpful feedback
+        if (envResult.createdTemplates && envResult.createdTemplates.length > 0) {
+            if (envResult.createdTemplates.length === 1) {
+                console.log(`✨ Created ${envResult.createdTemplates[0]} template file`);
+            }
+            else {
+                console.log(`✨ Created ${envResult.createdTemplates.length} template files:`);
+                envResult.createdTemplates.forEach((file) => console.log(`   • ${file}`));
+            }
+        }
+        else if (envResult.createdTemplate) {
+            console.log(`✨ Created ${envResult.createdTemplate} template file`);
+        }
+        if (envResult.warnings.length > 0) {
+            envResult.warnings.forEach((w) => console.warn(w));
+        }
+        // STEP 3: Determine port with priority (PORT now available from .env)
+        const port = determinePort(options);
+        // STEP 4: Read package.json for app info
+        const pkg = await readPackageJson();
+        // STEP 5: Create app instance
+        // App's globalConfiguration() will run in constructor
+        // initEnvironment() can skip if .env already loaded
+        //
+        // Activate log buffering BEFORE constructing the app so any logs the
+        // application emits during construction (e.g. inside `globalConfiguration()`
+        // or `configureServices()`) are captured and replayed in the right order
+        // after the startup banner. AppClass extends AppExpress for the standard
+        // adapter, so the static method is inherited; we duck-type to avoid a
+        // hard dependency on adapter-express from core.
+        const appClassWithBuffering = AppClass;
+        if (typeof appClassWithBuffering.startLogBuffering === "function") {
+            appClassWithBuffering.startLogBuffering();
+        }
+        const app = await AppFactory.create(AppClass);
+        // Set environment on app instance (for this.environment access)
+        app.environment =
+            currentEnvironment;
+        // STEP 6: Prepare app info
+        // Note: API versions will be auto-detected in displayStartupBanner()
+        // where controllers are already registered and accessible
+        const appInfo = {
+            appName: options?.appName ?? pkg.name ?? "ExpressoTS App",
+            appVersion: options?.appVersion ?? pkg.version ?? "1.0.0",
+        };
+        // STEP 8: Add CI detection info to appInfo (logged after banner, before middleware)
+        if (envResult.ciDetected) {
+            appInfo.ciDetection = {
+                detected: true,
+                platform: envResult.ciPlatform,
+            };
+        }
+        // STEP 9: Listen (supports port 0 for auto-assign)
+        // Banner will be displayed inside listen() callback with correct port
+        // CI detection will be logged after banner, before middleware logs
+        // Graceful shutdown handlers are already set up in AppExpress.listen()
+        const webServer = await app.listen(port, appInfo);
+        return webServer;
+    }
+    catch (error) {
+        // Lazy logger initialization - only create if error occurs
+        if (!logger) {
+            logger = new Logger();
+        }
+        logger.error(`Bootstrap failed: ${error instanceof Error ? error.message : String(error)}`, "bootstrap");
+        throw error;
+    }
+}