feat(config): allow dotenv options in framework config

AGENTS.md

@@ -71,6 +71,15 @@
 - Run commands on the docker container named `koalats-framework-container`.
 - Start the container if it's not running using the make file.
 
+## File and Module Renames
+
+- Treat the filesystem as case-sensitive when renaming files or directories.
+- Do not rely on case-only renames or mixed-case import paths.
+- Do not rely on module-local directory imports such as `@/feature` resolving through `feature/index.ts` during
+  internal refactors. Prefer explicit file imports such as `@/feature/specific-file`.
+- After renaming files or directories, clean generated build output and rerun the full validation pipeline to catch
+  stale artifact and path-casing issues before opening the PR.
+
 ## Refactorings
 
 - Refactorings MUST not introduce any breaking changes to the public API or types.

src/Testing/TestAgentFactory.ts

@@ -1,5 +1,5 @@
 import { create } from '@/application/create-application';
-import { type KoalaConfig } from '@/Config';
+import { type KoalaConfig } from '@/config/koala-config';
 import { type HttpMiddleware, type HttpScope, type NextMiddleware } from '@/Http';
 import { type User } from '@/Security/types';
 import supertest from 'supertest';

src/application/create-application.test.ts

@@ -1,5 +1,5 @@
 import { create } from '@/application/create-application';
-import { koalaDefaultConfig } from '@/Config';
+import { koalaDefaultConfig } from '@/config/default-config';
 import { Get, Route, RouteGroup } from '@/routing';
 import { exclusiveRoutingModeError } from '@/routing/verify-routing-mode';
 import { expect, test } from 'vitest';

src/application/create-application.ts

@@ -1,4 +1,4 @@
-import { type KoalaConfig } from '@/Config';
+import { type KoalaConfig } from '@/config/koala-config';
 import { initializeScope } from '@/Http';
 import { serveStaticFiles } from '@/Http/Files';
 import { applyConfiguredGlobalMiddleware } from '@/Http/middleware/apply-configured-global-middleware';

src/config/config-loader.test.ts

@@ -0,0 +1,127 @@
+import dotenv from 'dotenv';
+import dotenvExpand from 'dotenv-expand';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { loadEnvConfig } from '@/config/config-loader';
+
+describe('load env config', () => {
+  const configSpy = vi.spyOn(dotenv, 'config');
+  const expandSpy = vi.spyOn(dotenvExpand, 'expand');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    configSpy.mockReturnValue({ parsed: {} });
+    expandSpy.mockReturnValue({ parsed: {} });
+  });
+
+  describe('file selection', () => {
+    test('loads environment files in development order', () => {
+      loadEnvConfig('development');
+
+      expect(configSpy).toHaveBeenNthCalledWith(1, {
+        path: expect.stringContaining('.env'),
+        override: true,
+        quiet: true,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(2, {
+        path: expect.stringContaining('.env.local'),
+        override: true,
+        quiet: true,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(3, {
+        path: expect.stringContaining('.env.development'),
+        override: true,
+        quiet: true,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(4, {
+        path: expect.stringContaining('.env.development.local'),
+        override: true,
+        quiet: true,
+      });
+    });
+
+    test('skips the shared local file in the test environment', () => {
+      loadEnvConfig('test');
+
+      expect(configSpy).toHaveBeenCalledTimes(3);
+
+      expect(configSpy).toHaveBeenNthCalledWith(1, {
+        path: expect.stringContaining('.env'),
+        override: true,
+        quiet: true,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(2, {
+        path: expect.stringContaining('.env.test'),
+        override: true,
+        quiet: true,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(3, {
+        path: expect.stringContaining('.env.test.local'),
+        override: true,
+        quiet: true,
+      });
+    });
+  });
+
+  describe('dotenv options', () => {
+    test('uses the provided dotenv options for every file', () => {
+      loadEnvConfig('development', {
+        debug: true,
+        encoding: 'latin1',
+        override: false,
+        quiet: false,
+      });
+
+      expect(configSpy).toHaveBeenCalledTimes(4);
+
+      expect(configSpy).toHaveBeenNthCalledWith(1, {
+        debug: true,
+        encoding: 'latin1',
+        override: false,
+        path: expect.stringContaining('.env'),
+        quiet: false,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(2, {
+        debug: true,
+        encoding: 'latin1',
+        override: false,
+        path: expect.stringContaining('.env.local'),
+        quiet: false,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(3, {
+        debug: true,
+        encoding: 'latin1',
+        override: false,
+        path: expect.stringContaining('.env.development'),
+        quiet: false,
+      });
+      expect(configSpy).toHaveBeenNthCalledWith(4, {
+        debug: true,
+        encoding: 'latin1',
+        override: false,
+        path: expect.stringContaining('.env.development.local'),
+        quiet: false,
+      });
+    });
+
+    test('preserves the framework defaults when dotenv options are omitted', () => {
+      loadEnvConfig('development');
+
+      expect(configSpy.mock.calls).toEqual([
+        [{ path: expect.stringContaining('.env'), override: true, quiet: true }],
+        [{ path: expect.stringContaining('.env.local'), override: true, quiet: true }],
+        [{ path: expect.stringContaining('.env.development'), override: true, quiet: true }],
+        [{ path: expect.stringContaining('.env.development.local'), override: true, quiet: true }],
+      ]);
+    });
+  });
+
+  test('expands variables after each file is loaded', () => {
+    loadEnvConfig('development');
+
+    expect(expandSpy).toHaveBeenCalledTimes(4);
+    expect(expandSpy).toHaveBeenNthCalledWith(1, { parsed: {} });
+    expect(expandSpy).toHaveBeenNthCalledWith(2, { parsed: {} });
+    expect(expandSpy).toHaveBeenNthCalledWith(3, { parsed: {} });
+    expect(expandSpy).toHaveBeenNthCalledWith(4, { parsed: {} });
+  });
+});

src/config/config-loader.ts

@@ -0,0 +1,34 @@
+import path from 'path';
+import dotenv from 'dotenv';
+import dotenvExpand from 'dotenv-expand';
+import type { KoalaDotenvOptions } from './koala-config';
+
+export function loadEnvConfig(env: string, dotenvOptions?: KoalaDotenvOptions): void {
+  const rootDir = process.cwd();
+
+  resolveEnvFileNames(env).forEach(fileName => {
+    loadEnvFile(path.resolve(rootDir, fileName), resolveDotenvOptions(dotenvOptions));
+  });
+}
+
+function resolveEnvFileNames(env: string): string[] {
+  if (env === 'test') {
+    return ['.env', `.env.${env}`, `.env.${env}.local`];
+  }
+
+  return ['.env', '.env.local', `.env.${env}`, `.env.${env}.local`];
+}
+
+function resolveDotenvOptions(dotenvOptions?: KoalaDotenvOptions): KoalaDotenvOptions {
+  return {
+    override: true,
+    quiet: true,
+    ...dotenvOptions,
+  };
+}
+
+function loadEnvFile(filePath: string, options: KoalaDotenvOptions): void {
+  const expandedOptions = dotenv.config({ path: filePath, ...options });
+
+  dotenvExpand.expand(expandedOptions);
+}

src/Config/DefaultConfig.ts → src/config/default-config.ts

@@ -1,4 +1,4 @@
-import { type KoalaConfig } from './types';
+import { type KoalaConfig } from './koala-config';
 
 export const koalaDefaultConfig: KoalaConfig = {
   controllers: [],

src/Config/types.ts → src/config/koala-config.ts

@@ -2,17 +2,23 @@ import { type HttpMiddleware } from '@/Http';
 import { type StaticFilesOptions } from '@/Http/Files';
 import { type EventSubscriber } from '@/Kernel';
 import type { RouteSource } from '@/routing';
+import type { DotenvConfigOptions } from 'dotenv';
 
 /**
  * @deprecated Use function-first routes from `@koala-ts/framework/routing` with `KoalaConfig.routes` instead.
  */
 export type Controller = new (...args: unknown[]) => unknown;
 
+export type KoalaDotenvOptions = Pick<DotenvConfigOptions, 'debug' | 'encoding' | 'override' | 'quiet'>;
+
 export interface KoalaConfig {
   /**
    * @deprecated Use `routes` with `Route` from `@koala-ts/framework/routing` instead.
    */
   controllers: Controller[];
+  environment?: {
+    dotenv?: KoalaDotenvOptions;
+  };
   routes?: RouteSource[];
   globalMiddleware?: HttpMiddleware[];
   staticFiles?: StaticFilesOptions;

src/index.ts

@@ -5,7 +5,9 @@ import { getLegacyRoutes, registerLegacyRoutes } from '@/routing/decorator/legac
 import type { RouteMetadata as LegacyRouteMetadata } from '@/routing/decorator/route-metadata';
 
 // Core modules
-export * from '@/Config';
+export type * from '@/config/koala-config';
+export * from '@/config/default-config';
+export * from '@/config/config-loader';
 export * from '@/Http';
 export * from '@/Kernel';
 

src/routing/verify-routing-mode.ts

@@ -1,4 +1,4 @@
-import type { KoalaConfig } from '@/Config';
+import type { KoalaConfig } from '@/config/koala-config';
 
 export const exclusiveRoutingModeError =
   'Koala routing mode is exclusive. Use either legacy controllers from @koala-ts/framework or routes from @koala-ts/framework/routing.';

tests/function-first-routing.e2e.test.ts

@@ -1,7 +1,7 @@
 import { text } from 'node:stream/consumers';
 import { describe, expect, test } from 'vitest';
 import { createTestAgent, type HttpRequest, type HttpScope, type UploadedFile } from '../src';
-import { koalaDefaultConfig } from '../src/Config';
+import { koalaDefaultConfig } from '../src/config/default-config';
 import { Any, Get, Route, RouteGroup } from '../src/routing';
 import { exclusiveRoutingModeError } from '../src/routing/verify-routing-mode';