@decohere/config 0.0.1-dev.125 → 0.0.1-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/config",
-  "version": "0.0.1-dev.125",
+  "version": "0.0.1-dev.5",
   "description": "Database ORM abstractions and repository patterns built on TypeORM",
   "keywords": [
     "typescript",
@@ -10,15 +10,6 @@
     "repository",
     "decohere"
   ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/config#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/config"
-  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -34,9 +25,9 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.125",
-    "@decohere/crucible": "0.0.1-dev.125",
-    "@decohere/http": "0.0.1-dev.125",
+    "@decohere/http": "0.0.1-dev.5",
+    "@decohere/di": "0.0.1-dev.5",
+    "@decohere/core": "0.0.1-dev.5",
     "yaml": "^2.9.1"
   },
   "devDependencies": {}

package/src/configuration-data-source.ts

@@ -0,0 +1,9 @@
+export interface IConfigurationDataSource {
+	readonly name: string;
+	getData(): Promise<Record<string, unknown>>;
+}
+
+export abstract class ConfigurationDataSource implements IConfigurationDataSource {
+	public abstract readonly name: string;
+	public abstract getData(): Promise<Record<string, unknown>>;
+}

package/src/configuration.extensions.ts

@@ -0,0 +1,39 @@
+import { Builder } from "@decohere/http";
+import {
+	ConfigurationServiceToken,
+	type IConfigurationService,
+} from "@decohere/core/configuration";
+import { extension } from "@decohere/core/extensibility";
+import type { Constructable } from "@decohere/core/reflection";
+import { ConfigurationService } from "./configuration.service.js";
+import type { ConfigurationDataSource } from "./configuration-data-source.js";
+import { ConfigurationDataSourceKey } from "./const.js";
+
+export type ConfigurationOptions = {
+	configurationService?: Constructable<IConfigurationService>;
+	dataSources?: Constructable<ConfigurationDataSource>[];
+};
+
+declare module "@decohere/http" {
+	interface Builder {
+		withConfiguration(...dataSources: Constructable<ConfigurationDataSource>[]): Builder;
+	}
+}
+
+export class BuilderExtensions {
+	@extension(Builder)
+	public static withConfiguration(
+		builder: Builder,
+		...dataSourceArgs: Constructable<ConfigurationDataSource>[]
+	) {
+		const dataSources: Constructable<ConfigurationDataSource>[] = dataSourceArgs ?? [];
+		builder.withServices((builder) => {
+			builder.registerSingleton(ConfigurationServiceToken, ConfigurationService);
+			for (const dataSource of dataSources) {
+				builder.registerSingleton(ConfigurationDataSourceKey, dataSource);
+			}
+		});
+
+		return builder;
+	}
+}

package/src/configuration.service.ts

@@ -0,0 +1,73 @@
+import { inject, injectable } from "@decohere/di/decorators";
+import { cache, memoize } from "@decohere/core/caching";
+import type { IConfigurationService } from "@decohere/core/configuration";
+import type { Constructable } from "@decohere/core/reflection";
+import { lowerCamelCase } from "@decohere/core/system";
+import type { ConfigurationDataSource } from "./configuration-data-source.js";
+import { ConfigurationDataSourceKey } from "./const.js";
+import { ConfigurationError } from "./errors.js";
+
+@injectable()
+export class ConfigurationService implements IConfigurationService {
+	protected data: Record<string, unknown> = {};
+	public readonly dataSources: readonly ConfigurationDataSource[] = [];
+	protected isInitialized = false;
+
+	public constructor(
+		@inject(ConfigurationDataSourceKey) dataSources: ConfigurationDataSource[] = [],
+	) {
+		this.dataSources = dataSources;
+	}
+
+	private async initialize(): Promise<void> {
+		if (this.isInitialized) {
+			return;
+		}
+
+		const records = await Promise.all(this.dataSources.map(async (d) => await d.getData()));
+		this.validateDataSources(records);
+		const entries = records.flatMap((r) => Object.entries(r));
+		this.data = Object.fromEntries(entries);
+		this.isInitialized = true;
+	}
+
+	public async get<T extends object>(typeOrString: Constructable<T> | string): Promise<T> {
+		await this.ensureInitialized();
+
+		const obj =
+			typeof typeOrString === "string"
+				? this.getStringKey<T>(typeOrString)
+				: this.getConstructable<T>(typeOrString);
+		return obj;
+	}
+
+	private async ensureInitialized(): Promise<void> {
+		if (this.isInitialized) return;
+		await this.initialize();
+	}
+
+	private validateDataSources(records: Record<string, unknown>[]) {
+		const keys = records.flatMap((record) => Object.keys(record));
+		const uniqueKeys = new Set(keys);
+		if (uniqueKeys.size < keys.length) {
+			throw new ConfigurationError(
+				`Cannot have duplicate data source names. The data sources are: ${keys.join(",")}`,
+			);
+		}
+	}
+
+	@memoize()
+	private getConstructable<T extends object>(type: Constructable<T>): T {
+		const key = lowerCamelCase(type?.name.replace(/configuration|config/i, ""));
+		const data = this.data[key];
+		const configObject = new type();
+		Object.assign(configObject, data);
+		return configObject as T;
+	}
+
+	@cache()
+	private getStringKey<T>(key: string): T {
+		const data = this.data[key];
+		return data as T;
+	}
+}

package/src/errors.ts

@@ -0,0 +1 @@
+export class ConfigurationError extends Error {}

package/src/yaml-data-source.ts

@@ -0,0 +1,152 @@
+import { io } from "@decohere/core/io";
+import { parse } from "yaml";
+import { ConfigurationDataSource } from "./configuration-data-source.js";
+import { DEFAULT_CONFIG_DIR } from "./const.js";
+import { ConfigurationError } from "./errors.js";
+
+const CONFIG_FILE_NAME = "config";
+/** Unset NODE_ENV must not silently load config.dev.yaml (TypeORM synchronize, etc.). */
+const DEFAULT_ENV = "production";
+const FILE_EXT = "yaml";
+
+/** Resolve which env-specific config file to merge (e.g. config.dev.yaml). */
+export function resolveConfigEnv(nodeEnv?: string): string {
+	const env = nodeEnv ?? process.env.NODE_ENV;
+	if (env == null || env.trim() === "") {
+		return DEFAULT_ENV;
+	}
+	return env;
+}
+
+export type ConfigSource = {
+	/** Shown in errors, e.g. the file name. */
+	name: string;
+	text: string;
+};
+
+type Tree = Record<string, unknown>;
+type MissingVariable = { name: string; path: string };
+
+/** `${NAME}` or `${NAME:default}`. The default may be empty, and runs up to the first `}`. */
+const PLACEHOLDER = /\$\{(\w+)(?::([^}]*))?\}/g;
+
+function isTree(value: unknown): value is Tree {
+	return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Objects merge key by key; a list or a scalar in the later file replaces the earlier value. */
+function merge(base: Tree, override: Tree): Tree {
+	const merged: Tree = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		const existing = merged[key];
+		merged[key] = isTree(existing) && isTree(value) ? merge(existing, value) : value;
+	}
+	return merged;
+}
+
+function resolveString(
+	value: string,
+	path: string,
+	missing: MissingVariable[],
+): string | null {
+	let hasPlaceholder = false;
+	const resolved = value.replace(PLACEHOLDER, (_match, name: string, fallback?: string) => {
+		hasPlaceholder = true;
+		const fromEnv = process.env[name];
+		if (fromEnv !== undefined) {
+			return fromEnv;
+		}
+		if (fallback !== undefined) {
+			return fallback;
+		}
+		missing.push({ name, path });
+		return "";
+	});
+	// A variable set to the text "null" means no value.
+	return hasPlaceholder && resolved === "null" ? null : resolved;
+}
+
+function resolveValue(value: unknown, path: string, missing: MissingVariable[]): unknown {
+	if (typeof value === "string") {
+		return resolveString(value, path, missing);
+	}
+	if (Array.isArray(value)) {
+		return value.map((item, index) => resolveValue(item, `${path}[${index}]`, missing));
+	}
+	if (isTree(value)) {
+		const resolved: Tree = {};
+		for (const [key, item] of Object.entries(value)) {
+			resolved[key] = resolveValue(item, path === "" ? key : `${path}.${key}`, missing);
+		}
+		return resolved;
+	}
+	return value;
+}
+
+function parseSource({ name, text }: ConfigSource): Tree | undefined {
+	let parsed: unknown;
+	try {
+		parsed = parse(text);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new ConfigurationError(`Cannot parse config file ${name}: ${reason}`);
+	}
+	if (parsed == null) {
+		return undefined;
+	}
+	if (!isTree(parsed)) {
+		throw new ConfigurationError(
+			`Config file ${name} must contain a mapping at the top level`,
+		);
+	}
+	return parsed;
+}
+
+/**
+ * Merge config files in order (later files win), then resolve `${VAR}` placeholders on the
+ * merged result.
+ *
+ * Resolving after the merge means an environment file such as `config.dev.yaml` can replace a
+ * production `${VAR}` without that variable being set: a placeholder that was replaced is never
+ * looked up. Placeholders still unset after the merge fail together, naming every variable and
+ * the config path that used it. `${VAR:default}` keeps a default for optional values.
+ */
+export function resolveYamlConfig(sources: ConfigSource[]): Tree {
+	let merged: Tree = {};
+	for (const source of sources) {
+		const tree = parseSource(source);
+		if (tree !== undefined) {
+			merged = merge(merged, tree);
+		}
+	}
+
+	const missing: MissingVariable[] = [];
+	const resolved = resolveValue(merged, "", missing) as Tree;
+	if (missing.length > 0) {
+		const lines = missing.map(({ name, path }) => `  - ${name} (used at ${path})`);
+		throw new ConfigurationError(
+			`Config references ${missing.length} environment variable(s) that are not set:\n${lines.join("\n")}\n` +
+				"Set them, give the value a default with ${NAME:default}, or replace it in the environment's config file.",
+		);
+	}
+	return resolved;
+}
+
+export class YamlDataSource extends ConfigurationDataSource {
+	public name: string = YamlDataSource.name;
+	public async getData(): Promise<Record<string, unknown>> {
+		const configDir = process.env.CONFIG_DIR ?? DEFAULT_CONFIG_DIR;
+		const env = resolveConfigEnv();
+		const candidates = [
+			`${configDir}/${CONFIG_FILE_NAME}.${FILE_EXT}`,
+			`${configDir}/${CONFIG_FILE_NAME}.${env}.${FILE_EXT}`,
+		];
+		const sources: ConfigSource[] = [];
+		for (const filePath of candidates) {
+			if (await io.fileExists(filePath)) {
+				sources.push({ name: filePath, text: await io.readFile(filePath) });
+			}
+		}
+		return resolveYamlConfig(sources);
+	}
+}

package/tests/confguration.service.spec.ts

@@ -0,0 +1,101 @@
+import { ServiceContainerBuilder } from "@decohere/di";
+import { injectable } from "@decohere/di/decorators";
+import { ConfigurationServiceToken } from "@decohere/core/configuration";
+import { describe, expect, it, vi } from "vitest";
+import {
+	ConfigurationDataSource,
+	ConfigurationDataSourceKey,
+	ConfigurationService,
+} from "../src/index.js";
+
+describe("ConfigurationService", () => {
+	describe("lazy initialization", () => {
+		const mockData1 = { field1: "fieldData" };
+		const mockData2 = { field2: "fieldData" };
+
+		class MockDataSource1 extends ConfigurationDataSource {
+			public name: string = "";
+			public async getData(): Promise<Record<string, unknown>> {
+				return mockData1;
+			}
+		}
+
+		class MockDataSource2 extends ConfigurationDataSource {
+			public name: string = "";
+			public async getData(): Promise<Record<string, unknown>> {
+				return mockData2;
+			}
+		}
+
+		it("should initialize data sources when get() is called", async () => {
+			const dataSource1 = new MockDataSource1();
+			const dataSource2 = new MockDataSource2();
+			const getData1 = vi.spyOn(dataSource1, "getData");
+			const getData2 = vi.spyOn(dataSource2, "getData");
+			const configService = new ConfigurationService([dataSource1, dataSource2]);
+			await configService.get("field1");
+			expect(getData1).toHaveBeenCalled();
+			expect(getData2).toHaveBeenCalled();
+		});
+
+		it("should throw if duplicate named datasources exist when get() is called", async () => {
+			const dataSource1 = new MockDataSource1();
+			const dataSource2 = new MockDataSource1();
+			const configService = new ConfigurationService([dataSource1, dataSource2]);
+			const getCall = () => configService.get("field1");
+			await expect(getCall).rejects.toThrow(
+				"Cannot have duplicate data source names. The data sources are: field1,field1",
+			);
+		});
+	});
+
+	describe("get", () => {
+		class CustomObjectConfig {}
+		const customObject = { value: "value" };
+		class MockDataSource1 extends ConfigurationDataSource {
+			public name: string = "";
+			public async getData(): Promise<Record<string, unknown>> {
+				return {
+					stringKey: "value",
+					customObject,
+				};
+			}
+		}
+
+		it("should get data from ds with a string key", async () => {
+			const configurationService = new ConfigurationService([new MockDataSource1()]);
+
+			const data = await configurationService.get("stringKey");
+			expect(data).toEqual("value");
+		});
+
+		it("should get data from type key", async () => {
+			const configurationService = new ConfigurationService([new MockDataSource1()]);
+
+			const data = await configurationService.get(CustomObjectConfig);
+			expect(data).toEqual(customObject);
+		});
+	});
+
+	describe("injectable", () => {
+		const mockData = { field1: "fieldData" };
+
+		@injectable()
+		class MockDataSource extends ConfigurationDataSource {
+			public name: string = "";
+			public async getData(): Promise<Record<string, unknown>> {
+				return mockData;
+			}
+		}
+		it("should support injecting data source", async () => {
+			const containerBuiler = new ServiceContainerBuilder();
+			containerBuiler.registerSingleton(ConfigurationServiceToken, ConfigurationService);
+			containerBuiler.registerSingleton(ConfigurationDataSourceKey, MockDataSource);
+			const container = containerBuiler.build();
+			const configService = (await container.resolve(
+				ConfigurationServiceToken,
+			)) as ConfigurationService;
+			expect(configService.dataSources.at(0)).toBeInstanceOf(MockDataSource);
+		});
+	});
+});

package/tests/env-only.spec.ts

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// dotenv reads the real disk (it is not routed through the memfs mock), so use a real temp dir.
+const realFs = await vi.importActual<typeof import("node:fs")>("node:fs");
+const { tmpdir } = await vi.importActual<typeof import("node:os")>("node:os");
+
+describe("config reads configuration from the environment only (#576)", () => {
+	const sentinel = "DECOHERE_ENV_ONLY_SENTINEL";
+	const originalCwd = process.cwd();
+	let dir: string | undefined;
+
+	afterEach(() => {
+		process.chdir(originalCwd);
+		delete process.env[sentinel];
+		if (dir) realFs.rmSync(dir, { recursive: true, force: true });
+		dir = undefined;
+	});
+
+	it("does not load a .env file from the working directory on import", async () => {
+		dir = realFs.mkdtempSync(join(tmpdir(), "decohere-env-only-"));
+		realFs.writeFileSync(join(dir, ".env"), `${sentinel}=from-dotenv\n`);
+		process.chdir(dir);
+
+		vi.resetModules();
+		await import("../src/yaml-data-source.js");
+
+		expect(process.env[sentinel]).toBeUndefined();
+	});
+});

package/tests/yaml-config.spec.ts

@@ -0,0 +1,203 @@
+import { vol } from "memfs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ConfigurationError } from "../src/errors.js";
+import { resolveYamlConfig, YamlDataSource } from "../src/yaml-data-source.js";
+
+const file = (name: string, text: string) => ({ name, text });
+
+describe("YAML config: merge the files first, then resolve ${VAR} (#634)", () => {
+	const touched: string[] = [];
+
+	function setEnv(name: string, value: string | undefined) {
+		touched.push(name);
+		if (value === undefined) delete process.env[name];
+		else process.env[name] = value;
+	}
+
+	afterEach(() => {
+		for (const name of touched.splice(0)) delete process.env[name];
+	});
+
+	it("lets a later file replace a ${VAR} without that variable being set", () => {
+		setEnv("DB_HOST_634", undefined);
+
+		const config = resolveYamlConfig([
+			file("config.yaml", "database:\n  host: ${DB_HOST_634}\n  port: 5432\n"),
+			file("config.dev.yaml", "database:\n  host: postgres\n"),
+		]);
+
+		expect(config).toEqual({ database: { host: "postgres", port: 5432 } });
+	});
+
+	it("resolves a ${VAR} that no later file replaces", () => {
+		setEnv("DB_HOST_634", "db.internal");
+
+		const config = resolveYamlConfig([
+			file("config.yaml", "database:\n  host: ${DB_HOST_634}\n"),
+			file("config.dev.yaml", "database:\n  port: 5433\n"),
+		]);
+
+		expect(config).toEqual({ database: { host: "db.internal", port: 5433 } });
+	});
+
+	it("fails listing every missing variable and where it was used", () => {
+		setEnv("MISSING_A_634", undefined);
+		setEnv("MISSING_B_634", undefined);
+		setEnv("MISSING_C_634", undefined);
+		const base = [
+			"database:",
+			"  host: ${MISSING_A_634}",
+			"  password: ${MISSING_B_634}",
+			"auth:",
+			"  domain: ${MISSING_C_634}",
+			"",
+		].join("\n");
+
+		let failure: unknown;
+		try {
+			resolveYamlConfig([
+				file("config.yaml", base),
+				file("config.dev.yaml", "auth:\n  domain: dev.example.com\n"),
+			]);
+		} catch (error) {
+			failure = error;
+		}
+
+		expect(failure).toBeInstanceOf(ConfigurationError);
+		const message = (failure as Error).message;
+		expect(message).toContain("MISSING_A_634 (used at database.host)");
+		expect(message).toContain("MISSING_B_634 (used at database.password)");
+		// The dev file replaces auth.domain, so that one is not missing.
+		expect(message).not.toContain("MISSING_C_634");
+	});
+
+	it("names the path inside lists", () => {
+		setEnv("ORIGIN_634", undefined);
+
+		expect(() =>
+			resolveYamlConfig([file("config.yaml", "cors:\n  origins:\n    - ${ORIGIN_634}\n")]),
+		).toThrow(/ORIGIN_634 \(used at cors\.origins\[0\]\)/);
+	});
+
+	it("reports only the variable that is missing inside a longer value", () => {
+		setEnv("HOST_634", "db");
+		setEnv("PORT_634", undefined);
+
+		expect(() =>
+			resolveYamlConfig([
+				file("config.yaml", "url: postgres://${HOST_634}:${PORT_634}/app\n"),
+			]),
+		).toThrow(/PORT_634 \(used at url\)/);
+	});
+
+	it("substitutes into a longer value", () => {
+		setEnv("HOST_634", "db");
+		setEnv("PORT_634", "5432");
+
+		const config = resolveYamlConfig([
+			file("config.yaml", "url: postgres://${HOST_634}:${PORT_634}/app\n"),
+		]);
+
+		expect(config).toEqual({ url: "postgres://db:5432/app" });
+	});
+
+	it("keeps ${VAR:default} for optional values", () => {
+		setEnv("OPTIONAL_634", undefined);
+		setEnv("OVERRIDDEN_634", "from-env");
+
+		const config = resolveYamlConfig([
+			file(
+				"config.yaml",
+				"a: ${OPTIONAL_634:fallback}\nb: ${OVERRIDDEN_634:fallback}\nc: ${OPTIONAL_634:}\n",
+			),
+		]);
+
+		expect(config).toEqual({ a: "fallback", b: "from-env", c: "" });
+	});
+
+	it("treats a variable set to an empty string as set", () => {
+		setEnv("EMPTY_634", "");
+
+		expect(resolveYamlConfig([file("config.yaml", "token: ${EMPTY_634}\n")])).toEqual({
+			token: "",
+		});
+	});
+
+	it("turns a placeholder that resolves to the text null into null", () => {
+		setEnv("NOTHING_634", "null");
+
+		expect(resolveYamlConfig([file("config.yaml", "value: ${NOTHING_634}\n")])).toEqual({
+			value: null,
+		});
+	});
+
+	it("merges objects deeply and lets a later file replace lists and scalars", () => {
+		const config = resolveYamlConfig([
+			file("config.yaml", "a:\n  x: 1\n  y: 2\nlist: [1, 2, 3]\nkeep: base\n"),
+			file("config.dev.yaml", "a:\n  y: 20\nlist: [9]\n"),
+		]);
+
+		expect(config).toEqual({ a: { x: 1, y: 20 }, list: [9], keep: "base" });
+	});
+
+	it("skips an empty file and rejects one that is not a mapping", () => {
+		expect(
+			resolveYamlConfig([file("config.yaml", ""), file("config.dev.yaml", "a: 1\n")]),
+		).toEqual({
+			a: 1,
+		});
+		expect(() => resolveYamlConfig([file("config.yaml", "- just\n- a list\n")])).toThrow(
+			/config\.yaml.*mapping/,
+		);
+	});
+
+	it("says which file could not be parsed", () => {
+		expect(() => resolveYamlConfig([file("config.dev.yaml", "a: [unclosed\n")])).toThrow(
+			/config\.dev\.yaml/,
+		);
+	});
+});
+
+describe("YamlDataSource reads config.yaml then config.<env>.yaml (#634)", () => {
+	const saved = { CONFIG_DIR: process.env.CONFIG_DIR, NODE_ENV: process.env.NODE_ENV };
+
+	beforeEach(() => {
+		process.env.CONFIG_DIR = "/app/config";
+		delete process.env.CRYPTO_DB_HOST;
+	});
+
+	afterEach(() => {
+		vol.reset();
+		for (const [key, value] of Object.entries(saved)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	});
+
+	it("boots dev when config.dev.yaml replaces the production placeholder", async () => {
+		process.env.NODE_ENV = "dev";
+		vol.fromJSON({
+			"/app/config/config.yaml": "database:\n  host: ${CRYPTO_DB_HOST}\n",
+			"/app/config/config.dev.yaml": "database:\n  host: postgres\n",
+		});
+
+		expect(await new YamlDataSource().getData()).toEqual({ database: { host: "postgres" } });
+	});
+
+	it("still requires the variable in production, where nothing replaces it", async () => {
+		process.env.NODE_ENV = "production";
+		vol.fromJSON({
+			"/app/config/config.yaml": "database:\n  host: ${CRYPTO_DB_HOST}\n",
+			"/app/config/config.dev.yaml": "database:\n  host: postgres\n",
+		});
+
+		await expect(new YamlDataSource().getData()).rejects.toThrow(/CRYPTO_DB_HOST/);
+	});
+
+	it("reads only the base file when there is no file for the environment", async () => {
+		process.env.NODE_ENV = "staging";
+		vol.fromJSON({ "/app/config/config.yaml": "name: api\n" });
+
+		expect(await new YamlDataSource().getData()).toEqual({ name: "api" });
+	});
+});

package/tests/yaml-data-source.pentest.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+
+const { resolveConfigEnv } = await import("../src/yaml-data-source.js");
+
+describe("resolveConfigEnv CU-869eh25fu", () => {
+	it("defaults empty NODE_ENV to production (not dev)", () => {
+		expect(resolveConfigEnv("")).toBe("production");
+		expect(resolveConfigEnv("   ")).toBe("production");
+	});
+
+	it("defaults unset process.env.NODE_ENV to production", () => {
+		const prev = process.env.NODE_ENV;
+		delete process.env.NODE_ENV;
+		try {
+			expect(resolveConfigEnv()).toBe("production");
+		} finally {
+			if (prev === undefined) delete process.env.NODE_ENV;
+			else process.env.NODE_ENV = prev;
+		}
+	});
+
+	it("preserves explicit NODE_ENV values", () => {
+		expect(resolveConfigEnv("dev")).toBe("dev");
+		expect(resolveConfigEnv("production")).toBe("production");
+	});
+
+	it("would have loaded config.dev.yaml under the old default (dev)", () => {
+		// Documents the regression: `?? "dev"` merged synchronize:true from config.dev.yaml.
+		expect(resolveConfigEnv()).not.toBe("dev");
+	});
+});