nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/command/Command.js

@@ -0,0 +1,348 @@
+import { extend } from "../Tools.js";
+import Service from "../Service.js";
+import { chargePrompts } from "../cli/prompts.js";
+import { tagUnboundedListener } from "../kernel/lifecycleTags.js";
+import { Argument, Command, Option } from "commander";
+//#region src/command/Command.ts
+const defaultCommandOptions = {
+	showBanner: true,
+	kernelEvent: "onRegister",
+	lifetime: "oneshot"
+};
+/**
+* Classe Command représente une commande dans l'application.
+*
+* @class
+* @extends Service
+*/
+/**
+* Les valeurs SUGGÉRÉES d'une option, pour la complétion du shell.
+*
+* Un registre à part plutôt qu'un champ posé sur l'objet de commander : ce sont
+* ses objets, et les muter ferait dépendre le produit d'un détail non
+* documenté. `WeakMap` parce qu'une option morte ne doit rien retenir.
+*/
+const OPTION_SUGGESTIONS = /* @__PURE__ */ new WeakMap();
+var Command$1 = class extends Service {
+	cli;
+	command;
+	program;
+	json = false;
+	debug = false;
+	interactive = false;
+	forceInteractive = false;
+	builder = null;
+	/**
+	* Namespace `@inquirer/prompts` — chargé LAZY via {@link loadPrompts} (import
+	* dynamique) uniquement pour les commandes interactives. Évite ~39 ms + ~7 MB
+	* d'import eager sur CHAQUE boot non-interactif (la quasi-totalité). Garanti peuplé
+	* avant tout usage (action() le charge si interactif ; Builder le charge défensivement).
+	*/
+	prompts;
+	response = {};
+	kernelEvent = "onRegister";
+	/** Durée de vie déclarée (cf {@link OptionsCommandInterface.lifetime}). */
+	lifetime = "oneshot";
+	/** Profil d'exécution déclaré (cf {@link OptionsCommandInterface.runProfile}) — `null` si non déclaré. */
+	runProfile = null;
+	/** Boot silencieux déclaré (cf {@link OptionsCommandInterface.quietBoot}). */
+	quietBoot = false;
+	currentCommand;
+	eventsRegistered = false;
+	/**
+	* Crée une instance de Command.
+	*
+	* @constructor
+	* @param {string} name - Nom de la commande.
+	* @param {string} [description] - Description de la commande.
+	* @param {Cli} cli - Instance de la classe Cli.
+	* @param {OptionsCommandInterface} [options] - Options spécifiques à la commande.
+	*/
+	constructor(name, description = "", cli, options) {
+		const container = cli.container;
+		const myoptions = extend({}, defaultCommandOptions, options);
+		super(name, container, null, myoptions);
+		this.cli = cli;
+		this.program = this.cli.commander;
+		this.kernelEvent = this.options.kernelEvent;
+		this.lifetime = this.options.lifetime ?? "oneshot";
+		this.runProfile = this.options.runProfile ?? null;
+		this.quietBoot = this.options.quietBoot === true;
+		this.command = this.createCommand(name, description);
+		this.command?.action((...args) => {
+			if (this.kernel) {
+				this.cli.resolveCommand(this, args);
+				return;
+			}
+			return this.action(...args);
+		});
+	}
+	setEvents(...args) {
+		if (this.kernel && !this.eventsRegistered) {
+			this.eventsRegistered = true;
+			if (this.onKernelPreStart) this.kernel.once("onPreStart", this.onKernelPreStart.bind(this, ...args));
+			if (this.onKernelStart) this.kernel.once("onStart", this.onKernelStart.bind(this, ...args));
+			if (this.onKernelPreRegister) this.kernel.once("onPreRegister", this.onKernelPreRegister.bind(this, ...args));
+			if (this.onKernelRegister) this.kernel.once("onRegister", this.onKernelRegister.bind(this, ...args));
+			if (this.onKernelPreBoot) this.kernel.once("onPreBoot", this.onKernelPreBoot.bind(this, ...args));
+			if (this.onKernelBoot) this.kernel.once("onBoot", this.onKernelBoot.bind(this, ...args));
+			if (this.onKernelReady) this.kernel.once("onReady", this.onKernelReady.bind(this, ...args));
+			if (this.onKernelServersReady) this.kernel.once("onServersReady", this.onKernelServersReady.bind(this, ...args));
+			if (this.onKernelPostReady) this.kernel.once("onPostReady", this.onKernelPostReady.bind(this, ...args));
+			if (this.onKernelTerminate) this.kernel.once("onTerminate", this.onKernelTerminate.bind(this, ...args));
+			this.kernel.once(this.kernelEvent, tagUnboundedListener(this.action.bind(this, ...args)));
+		}
+	}
+	isComplete() {
+		if (this.kernel) return this.kernel.isCommandComplete(this.kernel.Events[this.kernelEvent]);
+		throw new Error(`Kernel not found`);
+	}
+	description() {
+		return this.command.description();
+	}
+	/**
+	* Charge `@inquirer/prompts` à la demande (import dynamique, idempotent) et le pose
+	* sur {@link prompts}. Appelé pour les commandes interactives — garde l'import lourd
+	* (~39 ms / ~7 MB) HORS du boot des commandes non-interactives.
+	*/
+	async loadPrompts() {
+		if (!this.prompts) this.prompts = await chargePrompts();
+	}
+	/**
+	* Rend un argument : celui qu'on a reçu, ou celui qu'on DEMANDE.
+	*
+	* 🔴 Une commande qui exige un argument positionnel (`<identifier>`) refuse
+	* avant même d'exister : commander répond « error: missing required argument
+	* 'identifier' » et le kernel sort en 1. C'est juste quand on TAPE la ligne
+	* et qu'on a oublié un mot ; c'est absurde quand on a CHOISI la commande dans
+	* le menu — on n'a rien oublié, on ne savait pas. Vécu sur
+	* `security:user:add` : le menu propose le geste, la commande le refuse.
+	*
+	* La règle vit ICI et pas dans chaque commande : quatre commandes du dépôt
+	* attendent un argument, et quatre copies d'une même règle divergent. Pour en
+	* profiter, une commande déclare son argument OPTIONNEL (`[identifier]` —
+	* sinon commander refuse avant nous) puis passe ce qu'elle a reçu.
+	*
+	* **Hors terminal, on ne demande RIEN** : un pipeline sans TTY resterait
+	* suspendu sur une question que personne ne lit, jusqu'au timeout du job.
+	* L'échec reste un échec — mais il montre la ligne exacte à taper.
+	*
+	* @param value - ce que la ligne de commande a fourni (souvent `undefined`)
+	* @param spec - nom de l'argument, question posée, choix éventuels ; `isTTY`
+	*               est INJECTABLE pour que la règle s'éprouve sans terminal
+	* @returns la valeur, taillée
+	* @throws Si l'argument manque et qu'aucun terminal ne peut le demander
+	*/
+	async askArgument(value, spec) {
+		const trimmed = typeof value === "string" ? value.trim() : "";
+		if (trimmed.length > 0) return trimmed;
+		if (!(spec.isTTY ?? Boolean(process.stdin.isTTY))) {
+			const example = spec.choices?.length ? `<${spec.choices.join("|")}>` : `<${spec.name}>`;
+			throw new Error(`${spec.name} est requis — aucun terminal pour le demander : nodefony ${this.name} ${example}`);
+		}
+		await this.loadPrompts();
+		const answer = spec.choices?.length ? await this.prompts.select({
+			message: spec.message,
+			choices: spec.choices.map((c) => ({
+				name: c,
+				value: c
+			}))
+		}) : await this.prompts.input({
+			message: spec.message,
+			validate: (v) => v.trim().length > 0 || `${spec.name} est requis`
+		});
+		return String(answer).trim();
+	}
+	/**
+	* Méthode d'action de la commande.
+	*
+	* @private
+	* @param {...any} args - Arguments passés à la commande.
+	* @returns {Promise<any>} Promise résolue avec le résultat de l'action.
+	*/
+	async action(...args) {
+		const current = args[args.length - 1];
+		this.getCliOptions();
+		if (this.interactive || this.forceInteractive) await this.loadPrompts();
+		if (this.options.showBanner) await this.showBanner();
+		if (this.builder) await this.builder.run(...args);
+		const res = await this.run(...args);
+		this.currentCommand = current;
+		return res;
+	}
+	/**
+	* Méthode principale pour exécuter la commande.
+	*
+	* @public
+	* @param {...any} args - Arguments passés à la commande.
+	* @returns {Promise<any>} Promise résolue avec le résultat de l'exécution.
+	*/
+	async run(...args) {
+		if (this.kernel) this.kernel.command = this;
+		if (this.interactive || this.forceInteractive) {
+			const response = await this.interaction(...args);
+			return Array.isArray(response) ? this.generate(...response) : this.generate(response);
+		}
+		return this.generate(...args);
+	}
+	forceInteractiveMode() {
+		this.forceInteractive = true;
+	}
+	/**
+	* Méthode pour l'interaction avec l'utilisateur.
+	*
+	* @public
+	* @param {...any} args - Arguments passés à la commande.
+	* @returns {Promise<any>} Promise résolue avec le résultat de l'interaction.
+	*/
+	async interaction(...args) {
+		return Promise.resolve(args);
+	}
+	/**
+	* Méthode pour générer le résultat de la commande.
+	*
+	* @public
+	* @param {...any} args - Arguments passés à la commande.
+	* @returns {Promise<any>} Promise résolue avec le résultat généré.
+	*/
+	async generate(...args) {
+		return Promise.resolve(args);
+	}
+	getCliOptions() {
+		this.debug = this.cli?.commander?.opts().debug || false;
+		this.interactive = this.cli?.commander?.opts().interactive || false;
+	}
+	createCommand(name, description) {
+		const cmd = new Command(name);
+		if (description) cmd.description(description);
+		if (this.options?.helpGroup) cmd.helpGroup(this.options.helpGroup);
+		this.program.addCommand(cmd);
+		return cmd;
+	}
+	alias(name) {
+		return this.command?.alias(name);
+	}
+	addBuilder(builder) {
+		return this.builder = new builder(this);
+	}
+	/**
+	* Méthode pour analyser les arguments de la commande.
+	*
+	* @public
+	* @param {string[]} [argv] - Tableau d'arguments à analyser.
+	* @param {commander.ParseOptions|undefined} [options] - Options de l'analyseur.
+	* @returns {Cmd} Instance de la classe Commander.
+	* @throws {Error} Lance une erreur si Commander n'est pas prêt.
+	*/
+	parse(argv, options) {
+		if (this.program) return this.program?.parse(argv, options);
+		throw new Error(`program not found`);
+	}
+	parseAsync(argv, options) {
+		if (this.program) return this.program?.parseAsync(argv, options);
+		throw new Error(`program not found`);
+	}
+	/**
+	* Méthode pour effacer la commande actuelle.
+	*
+	* @private
+	*/
+	clearCommand() {
+		if (this.cli) this.cli.clearCommand();
+		else while (process.argv.length > 2) process.argv.pop();
+	}
+	/**
+	* Méthode pour exécuter une commande avec des arguments spécifiques.
+	*
+	* @public
+	* @param {string} cmd - Commande à exécuter.
+	* @param {any[]} [args=[]] - Arguments de la commande.
+	* @returns {Cmd} Instance de la classe Commander.
+	*/
+	runCommand(cmd, args = []) {
+		this.clearCommand();
+		if (cmd) process.argv.push(cmd);
+		return this.parse(process.argv.concat(args));
+	}
+	async runCommandAsync(cmd, args = []) {
+		this.clearCommand();
+		if (cmd) process.argv.push(cmd);
+		return this.parseAsync(process.argv.concat(args));
+	}
+	/**
+	* Méthode pour ajouter une option à la commande.
+	*
+	* @public
+	* @param {string} flags - Drapeaux de l'option.
+	* @param {string|undefined} [description] - Description de l'option.
+	* @returns {Option} Instance de la classe Option.
+	* @throws {Error} Lance une erreur si Commander n'est pas prêt.
+	*/
+	addOption(flags, description, suggestions) {
+		if (this.command) {
+			const opt = new Option(flags, description);
+			if (suggestions?.length) OPTION_SUGGESTIONS.set(opt, suggestions);
+			this.command.addOption(opt);
+			return opt;
+		}
+		throw new Error(`Commander not ready`);
+	}
+	/**
+	* Méthode pour ajouter un argument à la commande.
+	*
+	* @public
+	* @param {string} arg - Argument de la commande.
+	* @param {string|undefined} [description] - Description de l'argument.
+	* @returns {Argument} Instance de la classe Argument.
+	* @throws {Error} Lance une erreur si Commander n'est pas prêt.
+	*/
+	addArgument(arg, description) {
+		if (this.command) {
+			const Arg = new Argument(arg, description);
+			this.command.addArgument(Arg);
+			return Arg;
+		}
+		throw new Error(`Command not ready`);
+	}
+	/**
+	* Méthode pour afficher une bannière liée à la commande.
+	*
+	* @public
+	* @returns {Promise<string>} Promise résolue avec la bannière générée.
+	*/
+	async showBanner() {
+		if (this.cli) return this.cli.asciify(`      ${this.name}`).then((data) => {
+			if (this.json) return data;
+			if (this.cli) {
+				if (this.cli.options.clear) this.cli.clear();
+				const color = this.cli.clc.blueBright.bold;
+				console.log(color(data));
+				this.cli.blankLine();
+			}
+			return data;
+		}).catch((e) => e);
+		return Promise.resolve("");
+	}
+	/**
+	* Méthode pour gérer la journalisation de la commande.
+	*
+	* @public
+	* @param {any} pci - Informations du client.
+	* @param {Severity} severity - Sévérité du message.
+	* @param {Msgid} msgid - Identifiant du message.
+	* @param {Message} msg - Contenu du message.
+	*/
+	logger(pci, severity, msgid, msg) {
+		try {
+			if (!msgid) msgid = `COMMAND ${this.name}`;
+			return super.logger(pci, severity, msgid, msg);
+		} catch (e) {
+			console.log(e, "\n", pci);
+		}
+	}
+	async terminate(code) {
+		return this.cli?.terminate(code);
+	}
+};
+//#endregion
+export { OPTION_SUGGESTIONS, Command$1 as default };

package/dist/node/config/configProvenance.js

@@ -0,0 +1,101 @@
+//#region src/config/configProvenance.ts
+/** Objet « simple » (pas null, pas tableau, pas instance exotique). */
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+}
+/** Égalité structurelle suffisante pour des valeurs de config (JSON-sérialisables). */
+function valueEquals(a, b) {
+	if (a === b) return true;
+	try {
+		return JSON.stringify(a) === JSON.stringify(b);
+	} catch {
+		return false;
+	}
+}
+function originOf(pathLower, resolved, def, envPaths) {
+	if (envPaths.has(pathLower)) return "env";
+	if (!valueEquals(resolved, def)) return "app";
+	return "default";
+}
+function walk(resolved, defaults, prefix, envPaths, out) {
+	for (const key of Object.keys(resolved)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+		const rv = resolved[key];
+		const dv = defaults ? defaults[key] : void 0;
+		if (isPlainObject(rv) && isPlainObject(dv)) walk(rv, dv, path, envPaths, out);
+		else out[path] = originOf(path.toLowerCase(), rv, dv, envPaths);
+	}
+}
+/**
+* Calcule l'origine de chaque valeur feuille de la config résolue d'un module.
+*
+* @param resolved - config effective du module (ex. `module.options` résolu).
+* @param defaults - défauts purs du module (`schema.parse({})`).
+* @param envPaths - chemins surchargés par env, en **dot-notation minuscule**
+*   (ex. `"jwt.accessttls"`) — typiquement dérivés de `parseNfEnvOverrides`.
+* @returns map `{ "chemin.pointé": "default" | "app" | "env" }`.
+*/
+function computeConfigProvenance(resolved, defaults, envPaths = /* @__PURE__ */ new Set()) {
+	const out = {};
+	walk(resolved, defaults, "", envPaths, out);
+	return out;
+}
+/**
+* Reconstruit l'objet des défauts d'un module depuis son JSON Schema
+* (`z.toJSONSchema`, retourné par `Module.configSchema()`) — utile quand le schéma
+* Zod n'est pas accessible (côté data plane admin). Walk récursif des `properties` :
+* prend `default` quand présent (y compris pour un objet entier), sinon descend.
+*
+* @param jsonSchema - JSON Schema d'une config de module (ou `null`).
+* @returns objet des défauts (vide si pas de schéma exploitable).
+*/
+function extractJsonSchemaDefaults(jsonSchema) {
+	const out = {};
+	if (!isPlainObject(jsonSchema)) return out;
+	const props = jsonSchema.properties;
+	if (!isPlainObject(props)) return out;
+	for (const key of Object.keys(props)) {
+		const node = props[key];
+		if (!isPlainObject(node)) continue;
+		if ("default" in node) out[key] = node.default;
+		else if (isPlainObject(node.properties)) out[key] = extractJsonSchemaDefaults(node);
+	}
+	return out;
+}
+function walkReserved(schemaProps, resolved, prefix, out) {
+	for (const key of Object.keys(schemaProps)) {
+		const node = schemaProps[key];
+		if (!isPlainObject(node)) continue;
+		const path = prefix ? `${prefix}.${key}` : key;
+		const rv = resolved ? resolved[key] : void 0;
+		if (node.reserved === true) {
+			if (rv !== void 0 && !valueEquals(rv, node.default)) out.push({
+				path,
+				description: typeof node.description === "string" ? node.description : ""
+			});
+		} else if (isPlainObject(node.properties)) walkReserved(node.properties, isPlainObject(rv) ? rv : void 0, path, out);
+	}
+}
+/**
+* Trouve les clés `reserved` du JSON Schema d'un module que la config résolue a
+* fait DÉVIER de leur défaut — i.e. qu'une application a posées en croyant régler un
+* comportement, alors qu'elles sont inertes (le levier vit ailleurs). Le pendant, au
+* BOOT, du drapeau `reserved` que Studio se contente de griser : sans ce filet, une
+* clé réservée écrite reste un silence (contrairement à une clé inconnue, qui est
+* déjà signalée — {@link computeConfigProvenance} côté env). Chaque entrée porte la
+* `description` du champ, qui nomme la clé active de remplacement.
+*
+* @param jsonSchema - JSON Schema du module (`Module.configSchema()`), ou `null`.
+* @param resolved - config effective du module (`module.options` post-validation).
+* @returns les clés réservées posées à une valeur non-défaut (vide si aucune).
+*/
+function findSetReservedKeys(jsonSchema, resolved) {
+	const out = [];
+	if (!isPlainObject(jsonSchema)) return out;
+	const props = jsonSchema.properties;
+	if (!isPlainObject(props)) return out;
+	walkReserved(props, resolved, "", out);
+	return out;
+}
+//#endregion
+export { computeConfigProvenance, extractJsonSchemaDefaults, findSetReservedKeys };

package/dist/node/config/defaults.js

@@ -0,0 +1,39 @@
+//#region src/config/defaults.ts
+/**
+* Configuration framework par défaut, fusionnée sous la config de l'app au boot.
+* Ne JAMAIS muter à l'exécution (le merge `extend(true, {}, defaultAppConfig, …)`
+* clone ; l'invariant d'immutabilité est couvert par test).
+*/
+const defaultAppConfig = {
+	modules: [],
+	locale: "en_en",
+	templating: "eta",
+	packageManager: "npm",
+	shutdownDeadline: 15e3,
+	domain: "localhost",
+	servers: {
+		statics: true,
+		http: { port: 5151 },
+		https: {
+			port: 5152,
+			protocol: "2.0"
+		},
+		ws: {},
+		wss: {}
+	},
+	timing: {
+		enabled: null,
+		verbose: false
+	},
+	log: {
+		active: true,
+		debug: [],
+		requestFormat: "auto",
+		buffered: "auto",
+		driver: "stdout",
+		file: { sync: false },
+		queryDriver: "auto"
+	}
+};
+//#endregion
+export { defaultAppConfig };

package/dist/node/config/defineConfig.js

@@ -0,0 +1,129 @@
+import { extend } from "../Tools.js";
+import { applyResolvedPath, parseNfEnvOverrides, pathLooksSecret, resolveFailureHint } from "./envOverride.js";
+import { defaultAppConfig } from "./defaults.js";
+import { validateAppConfig } from "./schema.js";
+//#region src/config/defineConfig.ts
+/**
+* Moteur `defineConfig` — builder unique de la config d'application (back-only, D1).
+*
+* `nodefony.config.ts` exporte `default defineConfig(obj | (ctx) => obj)`. Le
+* builder porte TOUS les défauts (deep-merge user sur {@link defaultAppConfig}),
+* valide (Zod) au resolve, et retourne un DESCRIPTEUR que le Kernel résout au boot
+* avec le contexte d'environnement (`ctx`). La forme fonction permet de différencier
+* la config par environnement sans fichier `config.<env>.ts` parallèle (D3).
+*
+* @example
+* ```ts
+* // nodefony.config.ts
+* import { defineConfig } from "nodefony";
+* export default defineConfig((ctx) => ({
+*   domain: ctx.isProd ? "0.0.0.0" : "127.0.0.1",
+*   servers: { http: { port: 8080 } },
+*   modules: ["@nodefony/http", "@nodefony/framework"],
+* }));
+* ```
+*/
+/** Segment réservé adressant la config de l'APPLICATION (vs un module). */
+const APP_SEGMENT = "app";
+/** Clé non-énumérable où le rapport d'override app est rangé sur la config résolue. */
+const APP_ENV_REPORT = Symbol("nodefony.appEnvOverrideReport");
+/**
+* Applique les overrides `NF__APP__<CHEMIN…>` sur la config APP **fusionnée**,
+* AVANT sa validation Zod (fail-closed : une valeur invalide sera rejetée par
+* `validateAppConfig`). Pur (ne loggue pas) : renvoie un rapport que le Kernel
+* surface. `app` n'est pas un nom de module → 0 collision avec `NF__<MODULE>__*`.
+*
+* N'altère QUE des chemins déjà présents (= champs ayant un défaut framework, cf
+* `defaultAppConfig`) ; un champ opt-in SANS défaut (`domainCheck`, `domainAlias`)
+* doit être déclaré par l'app pour devenir surchargeable — sinon WARNING + « did
+* you mean ». Le schéma app étant non-strict, on ne crée jamais de clé fantôme.
+*
+* @param merged - config app fusionnée (mutée en place).
+* @param env - source d'environnement (typiquement `process.env`).
+* @returns le rapport (appliqués + warnings).
+*/
+function applyAppEnvOverrides(merged, env) {
+	const applied = [];
+	const warnings = [];
+	for (const ov of parseNfEnvOverrides(env)) {
+		if (ov.moduleSeg !== APP_SEGMENT) continue;
+		if (applyResolvedPath(merged, ov.path, ov.value)) applied.push({
+			path: ov.path,
+			secret: pathLooksSecret(ov.path)
+		});
+		else warnings.push(`Override env app ignoré : chemin "${ov.path.join(".")}" inconnu (${ov.envKey})` + resolveFailureHint(merged, ov.path));
+	}
+	return {
+		applied,
+		warnings
+	};
+}
+/**
+* Lit le rapport d'override `NF__APP__*` rangé sur une config résolue (clé
+* non-énumérable). `null` si absent (config legacy / pas un descripteur).
+*
+* @param config - config app résolue par {@link defineConfig}.
+* @returns le rapport, ou `null`.
+*/
+function readAppEnvOverrideReport(config) {
+	if (config && typeof config === "object" && APP_ENV_REPORT in config) return config[APP_ENV_REPORT];
+	return null;
+}
+/**
+* Marque de marque (brand) interne d'un descripteur de config. Symbole privé au
+* module : non exporté → un objet quelconque ne peut pas se faire passer pour un
+* descripteur, et le type public {@link AppConfigDescriptor} reste propre.
+*/
+const CONFIG_DESCRIPTOR = Symbol("nodefony.configDescriptor");
+/**
+* Deep-merge la config user sous les défauts framework, puis valide.
+*
+* Réutilise `extend(true, {}, …)` — le merge profond standard du framework (cf
+* `Module.readOverrideModuleConfig`, `Syslog`) : 1 seule sémantique de merge
+* partout. Cible `{}` fraîche → ne mute NI les défauts NI l'input. Coût négligeable
+* (boot unique, ~µs ; ce n'est pas un hot path — cf retrait de `extend` du pipeline
+* per-requête, commit 02c32c2, hors sujet ici).
+*
+* @param userInput - config écrite par l'app (déjà résolue si forme fonction).
+* @returns config fusionnée + validée.
+*/
+function mergeAndValidate(userInput) {
+	const merged = extend(true, {}, defaultAppConfig, userInput);
+	const report = applyAppEnvOverrides(merged, process.env);
+	validateAppConfig(merged);
+	Object.defineProperty(merged, APP_ENV_REPORT, {
+		value: report,
+		enumerable: false,
+		configurable: true
+	});
+	return merged;
+}
+/**
+* Builder unique de la config d'application.
+*
+* @typeParam E - forme du catalogue d'env typé (inféré de `defineEnv`, Lot 2) →
+*   `ctx.env` typé + auto-complété dans la forme fonction.
+* @param input - objet de config, ou fonction `(ctx) => objet` pour le par-env.
+* @returns un descripteur résolvable par le Kernel au boot.
+*/
+function defineConfig(input) {
+	return {
+		[CONFIG_DESCRIPTOR]: true,
+		resolve(ctx) {
+			return mergeAndValidate(typeof input === "function" ? input(ctx) : input);
+		}
+	};
+}
+/**
+* Garde de type : `value` est-il un descripteur produit par {@link defineConfig} ?
+* Utilisé par le Kernel (`loadApp`, Lot 4) pour distinguer une app moderne
+* (`export default defineConfig(…)`) d'une config objet legacy.
+*
+* @param value - valeur à tester (typiquement l'export `default` de l'app).
+* @returns `true` si c'est un descripteur de config.
+*/
+function isConfigDescriptor(value) {
+	return typeof value === "object" && value !== null && value[CONFIG_DESCRIPTOR] === true;
+}
+//#endregion
+export { applyAppEnvOverrides, defineConfig, isConfigDescriptor, readAppEnvOverrideReport };