@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/application/bootstrap.js

@@ -0,0 +1,805 @@
+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 BEFORE defineConfig() resolves.
+ *
+ * Call this at the top of your config file to ensure environment variables
+ * are available when defineConfig() runs.
+ *
+ * @param options - Environment file configuration
+ *
+ * @example
+ * ```typescript
+ * // config.ts
+ * import { defineConfig, Env, loadEnvSync } from "@expressots/core";
+ *
+ * // Load .env files first
+ * loadEnvSync({
+ *   files: {
+ *     development: ".env.dev",
+ *     production: ".env.prod",
+ *   },
+ * });
+ *
+ * // Now defineConfig() will read from loaded .env files
+ * export const appConfig = defineConfig({
+ *   server: {
+ *     port: Env.port("PORT", { default: 3000 }),
+ *   },
+ * });
+ * ```
+ *
+ * @public API
+ */
+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
+    const optionalFiles = [".env", ".env.local", `${envFileName}.local`];
+    for (const file of optionalFiles) {
+        try {
+            config({ path: file });
+            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 file
+        config({ path: envFileName });
+        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;
+    }
+}
+/**
+ * Bootstrap the ExpressoTS application with zero configuration.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept bootstrap
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * The simplest way to start your application:
+ * ```typescript
+ * await bootstrap(App);
+ * ```
+ *
+ * This function orchestrates 8 critical startup phases:
+ * 1. Environment detection (CI/CD vs local)
+ * 2. Smart .env loading with opt-in behavior
+ * 3. Port determination (priority chain)
+ * 4. Package.json metadata extraction
+ * 5. DI container initialization via AppFactory
+ * 6. Environment injection into app instance
+ * 7. API version detection from decorators
+ * 8. Server startup with graceful shutdown
+ *
+ * @param AppClass - Application class extending AppExpress
+ * @param options - Optional bootstrap configuration
+ * @returns Promise resolving to IWebServerPublic instance
+ *
+ * @example
+ * ```typescript
+ * // Simplest usage - zero config (no .env file loading)
+ * await bootstrap(App);
+ *
+ * // With overrides (still no .env file loading)
+ * await bootstrap(App, {
+ *   port: 4000,
+ *   appName: "My API",
+ *   appVersion: "2.0.0"
+ * });
+ *
+ * // Opt-in to .env file loading and auto-creation
+ * await bootstrap(App, {
+ *   currentEnvironment: "development",
+ *   envFileConfig: {
+ *     files: {
+ *       development: ".env.dev",
+ *       production: ".env.prod"
+ *     },
+ *     required: ["DATABASE_URL", "API_KEY"],
+ *     autoCreateTemplate: true,  // Explicitly enable file creation
+ *     validateValues: true
+ *   }
+ * });
+ *
+ * // Auto-assign port (useful for testing)
+ * await bootstrap(App, { port: 0 });
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Bootstrap orchestrates 8 critical steps:
+ * 1. Environment detection (CI/CD vs local)
+ * 2. Smart .env loading with opt-in behavior
+ * 3. Port determination (priority chain)
+ * 4. Package.json metadata extraction
+ * 5. DI container initialization via AppFactory
+ * 6. Environment injection into app instance
+ * 7. API version detection from decorators
+ * 8. Server startup with graceful shutdown
+ *
+ * **Design Decisions**
+ * - Opt-in .env loading prevents breaking changes for containerized deployments
+ * - Port 0 support enables parallel testing without conflicts
+ * - Early validation fails fast with actionable error messages
+ * - CI/CD auto-detection provides zero-config for containerized environments
+ *
+ * **Performance Characteristics**
+ * - Startup time: ~8-25ms typical (optimized)
+ * - Environment loading: ~2-5ms (file I/O)
+ * - Package.json read: ~1-2ms first call, cached thereafter
+ * - CI detection: cached after first call
+ * - App instantiation: ~5-10ms (DI container setup)
+ * - Logger instances: lazy initialization (only created when needed)
+ *
+ * @see {@link loadAndValidateEnvironment} for environment loading logic
+ * @see {@link AppFactory.create} for DI container initialization
+ * @see {@link determinePort} for port resolution logic
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Patterns**
+ *
+ * Multi-environment setup with validation:
+ * ```typescript
+ * await bootstrap(App, {
+ *   currentEnvironment: process.env.NODE_ENV || "development",
+ *   envFileConfig: {
+ *     files: {
+ *       development: ".env.dev",
+ *       staging: ".env.staging",
+ *       production: ".env.prod"
+ *     },
+ *     required: ["DATABASE_URL", "JWT_SECRET"],
+ *     autoCreateTemplate: true,
+ *     validateValues: process.env.NODE_ENV === "production"
+ *   }
+ * });
+ * ```
+ *
+ * Containerized deployment (Docker/K8s):
+ * ```typescript
+ * await bootstrap(App, {
+ *   envFileConfig: {
+ *     skipFileLoading: true,  // Use process.env only
+ *     required: ["DATABASE_URL", "REDIS_URL"]
+ *   }
+ * });
+ * ```
+ *
+ * Testing with dynamic ports:
+ * ```typescript
+ * const server = await bootstrap(App, { port: 0 });
+ * const actualPort = server.port;  // Use in tests
+ * ```
+ *
+ * @troubleshooting
+ * **Common Issues**
+ * - ❌ PORT not detected → Use options.port or envFileConfig
+ * - ❌ CI validation fails → Check platform secrets configuration
+ * - ❌ Template not created → Set autoCreateTemplate: true explicitly
+ * - ❌ Port already in use → Use port: 0 for testing
+ *
+ * @performance
+ * - Async initialization: ~5-15ms (typical)
+ * - Package.json read: ~2ms first call, cached thereafter
+ * - CI detection: cached after first call
+ * - Port binding: varies by OS
+ * - Total startup: ~8-25ms (optimized with caching)
+ *
+ * @public API
+ */
+/**
+ * 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,
+    };
+}
+/**
+ * Implementation.
+ */
+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
+        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;
+    }
+}