@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/SyslogAdminApi.js

@@ -0,0 +1,466 @@
+import { SYSLOG_FILTERS, SYSLOG_SORTABLE } from "./syslogFilters.js";
+import path from "node:path";
+import { Syslog, getActiveLogDriver, getLogDriver, listLogDrivers, parseFilters, parsePageQuery, redactSecrets, setActiveLogDriver } from "nodefony";
+import fsp from "node:fs/promises";
+//#region nodefony/src/SyslogAdminApi.ts
+/** Plafond d'octets lus en queue de fichier (tail / fenêtre incrémentale). */
+const MAX_TAIL_BYTES = 262144;
+/**
+* Nom de fichier de log autorisé : basename simple terminant par `.log` (sink
+* texte LB.W) OU `.jsonl` (queryable LB.2/5). Anti path-traversal (pas de `/`,
+* pas de `..`). Couvre les deux familles écrites dans le répertoire des logs.
+*/
+const LOG_NAME = /^[A-Za-z0-9._-]+\.(log|jsonl)$/;
+/**
+* Producteur `IAdminApi` du **syslog** (core) — exposé sous
+* `/nodefony/syslog/api/*`. 4ᵉ et dernier producteur de P10.3.
+*
+* Le syslog vit dans `@nodefony/core` et ne peut pas importer framework →
+* framework le wrappe (comme le kernel) via `createSyslogAdminApi(syslog)`.
+* Lecture seule du ring buffer (`ISyslog.ringStack`, FIFO O(1)).
+*
+* Endpoints :
+*  - `GET /nodefony/syslog/api/logs` → Pdu récents (`?severity=ERROR&limit=N`)
+*  - `GET /nodefony/syslog/api/info` → compteurs (valid/invalid/missed/buffer)
+*
+* @param syslog - instance Syslog du kernel (`kernel.syslog`).
+* @param options - viewer de fichiers (DEV) : `logDir` + `enableFiles`.
+*/
+function createSyslogAdminApi(syslog, options = {}) {
+	const logDir = options.enableFiles && options.logDir ? path.resolve(options.logDir) : void 0;
+	const logDirPublic = (() => {
+		if (!logDir) return null;
+		const rel = path.relative(process.cwd(), logDir);
+		return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : path.basename(logDir);
+	})();
+	/** Lit un entier de query (`?limit=50`), borné, avec défaut. */
+	const intParam = (req, key, def, max) => {
+		const raw = req.query[key];
+		const v = Array.isArray(raw) ? raw[0] : raw;
+		const n = v !== void 0 ? Number.parseInt(v, 10) : NaN;
+		if (Number.isNaN(n) || n <= 0) return def;
+		return Math.min(n, max);
+	};
+	/** Première valeur d'un param de query (`?raw=1`). */
+	const oneParam = (req, key) => {
+		const raw = req.query[key];
+		return Array.isArray(raw) ? raw[0] : raw;
+	};
+	/**
+	* Construit un {@link ILogQueryCriteria} depuis la query string — la traduction
+	* HTTP→backplane partagée par `logs` (array, rétrocompat) et `logs/search`
+	* (paginé).
+	*
+	* Elle passe par les DEUX lecteurs du contrat de page : `parsePageQuery` pour
+	* la fenêtre, l'ordre et la recherche, `parseFilters` pour le vocabulaire de
+	* {@link SYSLOG_FILTERS}. Ce qu'ils remplacent n'était pas seulement une
+	* lecture à la main, c'était un **accepter puis jeter** systématique : chaque
+	* valeur invalide (`?severity=CRITICAL`, `?protocol=grpc`, `?flow=nimporte`)
+	* et chaque faute de frappe (`?severty=ERROR`) laissait le critère vide et
+	* rendait le journal ENTIER sous un `200`. Sur un journal d'exploitation,
+	* c'est la réponse qui se lit « rien à signaler ».
+	*
+	* @param req - la requête admin (query string déjà parsée).
+	* @param accepts - paramètres que l'appelant lit LUI-MÊME (`driver`, `scope`) ;
+	*   sans cette déclaration, le refus de l'inconnu les rejetterait à tort.
+	* @throws `PageQueryError` (400) sur un paramètre, une valeur ou un tri
+	*   qu'aucune partie de cet endpoint ne sait honorer.
+	*/
+	const buildCriteria = (req, accepts = []) => {
+		const page = parsePageQuery(req.query, {
+			defaultLimit: 200,
+			maxLimit: 1e3,
+			sortable: SYSLOG_SORTABLE,
+			searchable: true
+		});
+		const filters = parseFilters(req.query, SYSLOG_FILTERS, { accepts });
+		const criteria = {
+			limit: page.limit,
+			...filters
+		};
+		if (page.offset !== void 0 && page.offset > 0) criteria.offset = page.offset;
+		if (page.q !== void 0) criteria.text = page.q;
+		const dir = page.order?.[0]?.[1];
+		if (dir !== void 0) criteria.order = dir === "ASC" ? "asc" : "desc";
+		return criteria;
+	};
+	/**
+	* Driver de RELECTURE pour la TRACE par requestId (`?scope=trace`) — privilégie
+	* la rétention LONGUE. Le ring `memory` ne garde que ~`maxStack` entrées et
+	* churne vite sous le trafic data-plane de Studio (chaque page = ~12 logs) → la
+	* trace d'une requête vue il y a quelques minutes est souvent déjà évincée. Choix
+	* AGNOSTIQUE de l'env : (1) si le driver actif est persistant (loki/opensearch/
+	* file en prod 12-factor) on le garde ; (2) sinon, en dev, le JSONL du worker
+	* COURANT (`file` = 1 fichier `nodefony-<pid>.jsonl`, PAS `cluster-file` qui
+	* scannerait tous les pids du dossier) ; (3) à défaut, le driver actif (memory) —
+	* rétention courte mais jamais en erreur. Le front ne connaît donc pas l'infra.
+	*/
+	const resolveTraceDriver = () => {
+		const active = getActiveLogDriver();
+		if (active && active.name !== "memory" && active.query) return active;
+		const file = getLogDriver("file");
+		if (file?.query) return file;
+		return active;
+	};
+	/**
+	* Résout un nom de fichier de log en chemin absolu **sûr** dans `logDir`.
+	* Rejette tout nom hors `^[A-Za-z0-9._-]+\.log$` et tout chemin qui
+	* s'échapperait du répertoire (anti path-traversal). `null` = invalide.
+	*/
+	const resolveLogFile = (name) => {
+		if (!logDir || !LOG_NAME.test(name) || name.includes("..")) return null;
+		const resolved = path.resolve(logDir, name);
+		if (path.dirname(resolved) !== logDir) return null;
+		return resolved;
+	};
+	/**
+	* Lit la queue d'un fichier (octets `[start, size)`), ne renvoie que des
+	* **lignes complètes** (jusqu'au dernier `\n`) pour éviter les lignes coupées
+	* entre deux polls. `to` pointe sur la frontière de ligne → prochain `from`.
+	*/
+	const readTail = async (file, start, size) => {
+		if (start >= size) return {
+			text: "",
+			to: size
+		};
+		const len = size - start;
+		const buf = Buffer.alloc(len);
+		await using fh = await fsp.open(file, "r");
+		await fh.read(buf, 0, len, start);
+		const chunk = buf.toString("utf8");
+		const lastNl = chunk.lastIndexOf("\n");
+		if (lastNl === -1) return {
+			text: "",
+			to: start
+		};
+		return {
+			text: chunk.slice(0, lastNl),
+			to: start + Buffer.byteLength(chunk.slice(0, lastNl + 1), "utf8")
+		};
+	};
+	const descriptor = {
+		label: "Logs",
+		icon: "file-text",
+		order: 3
+	};
+	const endpoints = [
+		{
+			path: "logs",
+			summary: "Logs récents via le driver backplane actif — ?severity=&module=&requestId=&q=&limit=N (renvoie un ARRAY, rétrocompat).",
+			page: {
+				sortable: () => SYSLOG_SORTABLE,
+				filters: SYSLOG_FILTERS,
+				search: () => true
+			},
+			handler: async (request) => {
+				const driver = getActiveLogDriver();
+				if (!driver?.query) return [];
+				return (await driver.query(buildCriteria(request))).rows;
+			}
+		},
+		{
+			path: "logs/search",
+			summary: "Query paginée du backplane → { rows, total, truncated } (DataGrid Studio). Mêmes critères que logs + offset.",
+			page: {
+				sortable: () => SYSLOG_SORTABLE,
+				filters: SYSLOG_FILTERS,
+				search: () => true
+			},
+			handler: async (request) => {
+				const wanted = oneParam(request, "driver");
+				const driver = wanted ? getLogDriver(wanted) : oneParam(request, "scope") === "trace" ? resolveTraceDriver() : getActiveLogDriver();
+				if (!driver?.query) return {
+					status: 409,
+					body: {
+						queryable: false,
+						driver: driver?.name ?? wanted ?? null
+					}
+				};
+				return await driver.query(buildCriteria(request, ["driver", "scope"]));
+			}
+		},
+		{
+			path: "backplane",
+			summary: "Méta du Log Backplane — driver de relecture actif, drivers dispo, sink write (LB.W), compteurs syslog.",
+			handler: () => {
+				const driver = getActiveLogDriver();
+				return {
+					activeDriver: driver ? {
+						name: driver.name,
+						capabilities: driver.capabilities
+					} : null,
+					drivers: listLogDrivers(),
+					write: {
+						sink: Syslog.logSinkName,
+						sinkEnabled: Syslog.sinkEnabled,
+						transports: syslog.listTransports(),
+						ringEnabled: syslog.ringEnabled,
+						streamEnabled: syslog.streamEnabled,
+						logDir: logDirPublic
+					},
+					cluster: {
+						isCluster: process.env.NF_CLUSTER === "1",
+						pid: process.pid
+					},
+					counters: {
+						valid: syslog.valid,
+						invalid: syslog.invalid,
+						missed: syslog.missed,
+						errorTotal: syslog.errorTotal,
+						criticTotal: syslog.criticTotal,
+						buffered: syslog.ringStack.length,
+						bufferCapacity: syslog.bufferCapacity
+					},
+					environment: options.environment ?? null
+				};
+			}
+		},
+		{
+			path: "backplane/ping",
+			summary: "Sonde de santé de la destination — ?driver=<name> (défaut = actif). Renvoie { ok, latencyMs, detail?, info? }. Chemin FROID (réseau pour loki/opensearch).",
+			handler: async (request) => {
+				const name = oneParam(request, "driver");
+				const driver = name ? getLogDriver(name) : getActiveLogDriver();
+				if (!driver) return {
+					status: 404,
+					body: { error: name ? `unknown log driver "${name}"` : "no active log driver" }
+				};
+				if (!driver.probe) return {
+					ok: true,
+					latencyMs: 0,
+					info: {
+						driver: driver.name,
+						local: "destination locale (pas de réseau)"
+					}
+				};
+				return await driver.probe();
+			}
+		},
+		{
+			path: "backplane/driver",
+			method: "POST",
+			summary: "Switch du driver de relecture (DEV-only) — body { name }. Action de contrôle runtime.",
+			handler: (request) => {
+				if (options.environment !== "development") return {
+					status: 403,
+					body: { error: "log driver switch is development-only" }
+				};
+				const body = request.body ?? {};
+				const name = typeof body.name === "string" ? body.name : "";
+				if (!name) return {
+					status: 400,
+					body: { error: "missing driver name" }
+				};
+				try {
+					const d = setActiveLogDriver(name);
+					return {
+						active: d.name,
+						capabilities: d.capabilities
+					};
+				} catch {
+					return {
+						status: 404,
+						body: { error: `unknown log driver "${name}"` }
+					};
+				}
+			}
+		},
+		{
+			path: "backplane/transport",
+			method: "POST",
+			summary: "Active/désactive un transport d'écriture à chaud (DEV-only) — body { name, enabled }. Axe WRITE (fan-out).",
+			handler: (request) => {
+				if (options.environment !== "development") return {
+					status: 403,
+					body: { error: "transport toggle is development-only" }
+				};
+				const body = request.body ?? {};
+				const name = typeof body.name === "string" ? body.name : "";
+				if (!name) return {
+					status: 400,
+					body: { error: "missing transport name" }
+				};
+				if (typeof body.enabled !== "boolean") return {
+					status: 400,
+					body: { error: "missing enabled (boolean)" }
+				};
+				const changed = syslog.setTransportEnabled(name, body.enabled);
+				if (changed) syslog.log(`transport d'écriture « ${name} » ${body.enabled ? "activé" : "désactivé"}`, "NOTICE", "LOG-BACKPLANE");
+				return {
+					name,
+					enabled: body.enabled,
+					changed
+				};
+			}
+		},
+		{
+			path: "backplane/sink",
+			method: "POST",
+			summary: "Mute/démute le sink texte (console/fichier) à chaud (DEV-only) — body { enabled }.",
+			handler: (request) => {
+				if (options.environment !== "development") return {
+					status: 403,
+					body: { error: "sink toggle is development-only" }
+				};
+				const body = request.body ?? {};
+				if (typeof body.enabled !== "boolean") return {
+					status: 400,
+					body: { error: "missing enabled (boolean)" }
+				};
+				if (body.enabled === false) syslog.log(`sink texte « ${Syslog.logSinkName} » coupé (console/fichier)`, "NOTICE", "LOG-BACKPLANE");
+				const changed = Syslog.setSinkEnabled(body.enabled);
+				if (changed && body.enabled) syslog.log("sink texte rétabli", "NOTICE", "LOG-BACKPLANE");
+				return {
+					enabled: body.enabled,
+					sink: Syslog.logSinkName,
+					changed
+				};
+			}
+		},
+		{
+			path: "backplane/ring",
+			method: "POST",
+			summary: "Active/désactive le stockage mémoire (ring) à chaud (DEV-only) — body { enabled }.",
+			handler: (request) => {
+				if (options.environment !== "development") return {
+					status: 403,
+					body: { error: "ring toggle is development-only" }
+				};
+				const body = request.body ?? {};
+				if (typeof body.enabled !== "boolean") return {
+					status: 400,
+					body: { error: "missing enabled (boolean)" }
+				};
+				const changed = syslog.setRingEnabled(body.enabled);
+				if (changed) syslog.log(`stockage mémoire (ring) ${body.enabled ? "activé" : "désactivé"}`, "NOTICE", "LOG-BACKPLANE");
+				return {
+					enabled: body.enabled,
+					changed
+				};
+			}
+		},
+		{
+			path: "backplane/stream",
+			method: "POST",
+			summary: "Active/désactive la diffusion temps réel (nodefony:syslog / Live) à chaud (DEV-only) — body { enabled }.",
+			handler: (request) => {
+				if (options.environment !== "development") return {
+					status: 403,
+					body: { error: "stream toggle is development-only" }
+				};
+				const body = request.body ?? {};
+				if (typeof body.enabled !== "boolean") return {
+					status: 400,
+					body: { error: "missing enabled (boolean)" }
+				};
+				const changed = syslog.setStreamEnabled(body.enabled);
+				if (changed) syslog.log(`diffusion temps réel ${body.enabled ? "activée" : "coupée"}`, "NOTICE", "LOG-BACKPLANE");
+				return {
+					enabled: body.enabled,
+					changed
+				};
+			}
+		},
+		{
+			path: "info",
+			summary: "Syslog counters — valid, invalid, missed, buffered",
+			handler: () => ({
+				valid: syslog.valid,
+				invalid: syslog.invalid,
+				missed: syslog.missed,
+				buffered: syslog.ringStack.length
+			})
+		},
+		{
+			path: "files",
+			summary: "Fichiers de log du tmpDir (DEV) — name, size, mtime. Désactivé en prod.",
+			handler: async () => {
+				if (!logDir) return {
+					enabled: false,
+					reason: "Production : logs → stdout/stderr → collecteur (pas de fichiers).",
+					files: []
+				};
+				let names;
+				try {
+					names = await fsp.readdir(logDir);
+				} catch {
+					return {
+						enabled: true,
+						files: []
+					};
+				}
+				const files = [];
+				for (const name of names) {
+					if (!LOG_NAME.test(name)) continue;
+					try {
+						const st = await fsp.stat(path.join(logDir, name));
+						if (st.isFile()) files.push({
+							name,
+							size: st.size,
+							mtime: st.mtimeMs
+						});
+					} catch {}
+				}
+				files.sort((a, b) => b.mtime - a.mtime);
+				return {
+					enabled: true,
+					files
+				};
+			}
+		},
+		{
+			path: "files/{name}",
+			summary: "Tail d'un fichier de log (DEV) — ?from=<offset>&lines=N&raw=1. Sans from = N dernières lignes ; avec from = octets ajoutés (follow).",
+			handler: async (request) => {
+				const name = request.params.name ?? "";
+				const file = resolveLogFile(name);
+				if (!file) return {
+					status: 400,
+					body: { error: "invalid log file name" }
+				};
+				let size;
+				try {
+					const st = await fsp.stat(file);
+					if (!st.isFile()) return {
+						status: 400,
+						body: { error: "not a file" }
+					};
+					size = st.size;
+				} catch {
+					return {
+						status: 404,
+						body: { error: "log file not found" }
+					};
+				}
+				const fromStr = oneParam(request, "from");
+				const fromNum = fromStr !== void 0 ? Number.parseInt(fromStr, 10) : NaN;
+				const incremental = !Number.isNaN(fromNum) && fromNum >= 0 && fromNum <= size;
+				const reset = !Number.isNaN(fromNum) && fromNum > size;
+				const lines = intParam(request, "lines", 500, 5e3);
+				const start = incremental ? fromNum : Math.max(0, size - MAX_TAIL_BYTES);
+				const { text, to } = await readTail(file, start, size);
+				let out = text === "" ? [] : text.split("\n");
+				if (!incremental && start > 0 && out.length > 0) out.shift();
+				if (!incremental) out = out.slice(-lines);
+				const raw = oneParam(request, "raw") === "1";
+				if (!raw) out = out.map(redactSecrets);
+				return {
+					name,
+					size,
+					from: start,
+					to,
+					reset,
+					redacted: !raw,
+					lines: out
+				};
+			}
+		}
+	];
+	return {
+		adminNamespace: "syslog",
+		adminDescriptor: () => descriptor,
+		adminEndpoints: () => endpoints
+	};
+}
+//#endregion
+export { createSyslogAdminApi };

package/dist/nodefony/src/Template.js

@@ -0,0 +1,15 @@
+import { Service } from "nodefony";
+//#region nodefony/src/Template.ts
+var Template = class extends Service {
+	engine;
+	module;
+	cache = true;
+	constructor(name, engine, module, options = {}) {
+		super(name, module.container, module.notificationsCenter, options);
+		this.engine = engine;
+		this.module = module;
+		this.cache = module.kernel?.environment === "prod" || module.kernel?.environment === "production";
+	}
+};
+//#endregion
+export { Template as default };

package/dist/nodefony/src/configMutation.js

@@ -0,0 +1,186 @@
+//#region nodefony/src/configMutation.ts
+/** Narrowing défensif : `unknown` → nœud JSON Schema (ou `null` si non-objet). */
+function asNode(value) {
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) return value;
+	return null;
+}
+/**
+* Récupère la map `properties` d'un nœud — directement, ou dans la 1ʳᵉ branche
+* objet d'un `anyOf`/`oneOf` (cas d'un champ optionnel/nullable typé objet).
+*/
+function getProperties(node) {
+	if (node.properties && typeof node.properties === "object") return node.properties;
+	const variants = node.anyOf ?? node.oneOf;
+	if (Array.isArray(variants)) for (const v of variants) {
+		const vn = asNode(v);
+		if (vn?.properties) return vn.properties;
+	}
+	return null;
+}
+/** Résout un segment vers la clé réelle d'une map : exact d'abord, sinon insensible casse. */
+function resolveKeyCI(obj, seg) {
+	if (Object.prototype.hasOwnProperty.call(obj, seg)) return seg;
+	const lower = seg.toLowerCase();
+	for (const k of Object.keys(obj)) if (k.toLowerCase() === lower) return k;
+	return null;
+}
+/**
+* Descend dans un JSON Schema le long d'un chemin pointé (`upload.maxFileSize`)
+* et renvoie le nœud feuille, ou `null` si un segment ne résout pas.
+*
+* @param schema - JSON Schema racine du module (`mod.configSchema()`).
+* @param segments - segments du chemin (casse réelle ou insensible).
+* @returns le nœud feuille, ou `null` si le chemin est inconnu.
+*/
+function navigateSchemaNode(schema, segments) {
+	let node = asNode(schema);
+	for (const seg of segments) {
+		if (!node) return null;
+		const props = getProperties(node);
+		if (!props) return null;
+		const key = resolveKeyCI(props, seg);
+		if (key === null) return null;
+		node = asNode(props[key]);
+	}
+	return node;
+}
+/** Extrait les flags Nodefony d'un nœud (défaut `false` partout). */
+function nodeFlags(node) {
+	return {
+		runtimeMutable: node.runtimeMutable === true,
+		reserved: node.reserved === true,
+		kernelDerived: node.kernelDerived === true,
+		secret: node.secret === true
+	};
+}
+/** Type JS effectif d'une valeur, dans le vocabulaire JSON Schema. */
+function jsonTypeOf(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/** Une valeur satisfait-elle UN type JSON Schema (`integer` = number entier) ? */
+function matchesType(t, value) {
+	if (t === "integer") return typeof value === "number" && Number.isInteger(value);
+	return t === jsonTypeOf(value);
+}
+/**
+* Valide une valeur scalaire contre un nœud JSON Schema feuille (type(s), `enum`,
+* `anyOf`/`oneOf`, bornes numériques, longueur/pattern de chaîne). Fail-closed :
+* un nœud objet/array non scalaire est refusé (édition feuille uniquement).
+*
+* @param node - nœud JSON Schema cible.
+* @param value - valeur candidate (déjà typée — provient d'un body JSON).
+* @returns succès, ou échec avec message explicatif.
+*/
+function validateLeafValue(node, value) {
+	if (Array.isArray(node.enum)) return node.enum.includes(value) ? { ok: true } : {
+		ok: false,
+		message: `valeur attendue parmi : ${node.enum.map((e) => JSON.stringify(e)).join(", ")}`
+	};
+	const variants = node.anyOf ?? node.oneOf;
+	if (Array.isArray(variants) && variants.length > 0) {
+		for (const v of variants) {
+			const vn = asNode(v);
+			if (vn && validateLeafValue(vn, value).ok) return { ok: true };
+		}
+		return {
+			ok: false,
+			message: "ne correspond à aucune variante autorisée"
+		};
+	}
+	const types = Array.isArray(node.type) ? node.type : node.type ? [node.type] : [];
+	if (types.length > 0 && !types.some((t) => matchesType(t, value))) return {
+		ok: false,
+		message: `type attendu : ${types.join(" | ")}`
+	};
+	if (types.length === 0 && (value === null || typeof value !== "object")) {} else if (types.length === 0) return {
+		ok: false,
+		message: "édition d'objet/tableau non supportée"
+	};
+	if (typeof value === "number") {
+		if (node.minimum !== void 0 && value < node.minimum) return {
+			ok: false,
+			message: `doit être ≥ ${node.minimum}`
+		};
+		if (node.maximum !== void 0 && value > node.maximum) return {
+			ok: false,
+			message: `doit être ≤ ${node.maximum}`
+		};
+		if (node.exclusiveMinimum !== void 0 && value <= node.exclusiveMinimum) return {
+			ok: false,
+			message: `doit être > ${node.exclusiveMinimum}`
+		};
+		if (node.exclusiveMaximum !== void 0 && value >= node.exclusiveMaximum) return {
+			ok: false,
+			message: `doit être < ${node.exclusiveMaximum}`
+		};
+	}
+	if (typeof value === "string") {
+		if (node.minLength !== void 0 && value.length < node.minLength) return {
+			ok: false,
+			message: `longueur minimale ${node.minLength}`
+		};
+		if (node.maxLength !== void 0 && value.length > node.maxLength) return {
+			ok: false,
+			message: `longueur maximale ${node.maxLength}`
+		};
+		if (node.pattern) try {
+			if (!new RegExp(node.pattern).test(value)) return {
+				ok: false,
+				message: "format invalide"
+			};
+		} catch {}
+	}
+	return { ok: true };
+}
+/**
+* Décide si un champ est éditable à chaud. Ordre de refus : secret > réservé >
+* dérivé kernel > non-`runtimeMutable` (boot). `null` = éditable.
+*
+* @param flags - flags du nœud ({@link nodeFlags}).
+* @returns la raison du refus, ou `null` si éditable live.
+*/
+function notEditableReason(flags) {
+	if (flags.secret) return "secret";
+	if (flags.reserved) return "reserved";
+	if (flags.kernelDerived) return "kernel_derived";
+	if (!flags.runtimeMutable) return "boot_only";
+	return null;
+}
+/**
+* Construit la **recette** d'override à appliquer dans le déploiement pour un champ
+* non mutable à chaud (12-factor). Un secret passe par la variante `*_FILE` (jamais
+* la valeur en clair dans l'environnement).
+*
+* @param seg - segment d'adressage du module (`http`, `security`, `app`…).
+* @param segments - chemin pointé du champ.
+* @param isSecret - le champ porte-t-il le flag secret ?
+* @returns la ligne d'override prête à copier.
+*/
+function recipeFor(seg, segments, isSecret) {
+	const envKey = `NF__${seg.toUpperCase()}__${segments.map((s) => s.toUpperCase()).join("__")}`;
+	if (isSecret) return `${envKey}__FILE=/run/secrets/${segments.join("_").toLowerCase()}`;
+	return `${envKey}=<valeur>`;
+}
+/**
+* Lit la valeur courante d'une config à un chemin pointé (insensible à la casse) —
+* sert à journaliser l'ancienne valeur (`before`) avant mutation.
+*
+* @param obj - objet de config (`mod.options`).
+* @param segments - chemin pointé.
+* @returns la valeur, ou `undefined` si le chemin ne résout pas.
+*/
+function getResolvedPath(obj, segments) {
+	let cur = obj;
+	for (const seg of segments) {
+		if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return;
+		const rec = cur;
+		const key = resolveKeyCI(rec, seg);
+		if (key === null) return void 0;
+		cur = rec[key];
+	}
+	return cur;
+}
+//#endregion
+export { getResolvedPath, navigateSchemaNode, nodeFlags, notEditableReason, recipeFor, validateLeafValue };