nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/config/defineEnv.js

@@ -0,0 +1,264 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+//#region src/config/defineEnv.ts
+/**
+* `defineEnv` — catalogue de variables d'environnement typé + validé (back-only, D1).
+*
+* SEUL point du framework qui lit `process.env` (12-factor). Chaque variable est
+* déclarée avec sa coercion (string/number/boolean/enum), son défaut et sa doc ;
+* `defineEnv` lit la source UNE fois, valide (zod), et retourne un objet **figé +
+* typé**. Le type inféré (`typeof env`) alimente `ConfigContext<E>` → `ctx.env.X`
+* auto-complété + typé dans `defineConfig` (pilier #1, niveau 4 ; pattern t3-env /
+* Adonis `Env.create`).
+*
+* **Fail-fast** : une valeur présente mais invalide (enum hors liste, nombre
+* malformé, requis manquant) lève au boot avec un message clair nommant la
+* variable — au lieu d'un fallback silencieux qui masque un bug de déploiement.
+* Une valeur ABSENTE (ou chaîne vide) prend le défaut déclaré.
+*
+* @example
+* ```ts
+* // env.ts
+* import { defineEnv, envEnum, envString, envBoolean } from "nodefony";
+* export const env = defineEnv({
+*   NF_LOG_DRIVER: envEnum(["stdout", "file", "null"], { default: "stdout" }),
+*   NF_LOG_FILE_SYNC: envBoolean({ default: false }),
+*   NF_LOKI_URL: envString({ optional: true }),
+* });
+* // env.NF_LOG_DRIVER : "stdout" | "file" | "null"
+* ```
+*/
+/** Clé non-énumérable des métadonnées posées sur un schéma d'env. */
+const ENV_META = Symbol("nodefony.envVarMeta");
+/** Clé non-énumérable du catalogue agrégé posé sur l'objet `env` retourné. */
+const ENV_CATALOG = Symbol("nodefony.envCatalog");
+/** Attache `meta` à `schema` (non-énumérable → invisible pour Zod/sérialisation). */
+function tagMeta(schema, meta) {
+	Object.defineProperty(schema, ENV_META, {
+		value: meta,
+		enumerable: false,
+		configurable: true
+	});
+	return schema;
+}
+/** Lit les métadonnées posées sur un schéma d'env (ou `null`). */
+function readMeta(schema) {
+	if (schema && typeof schema === "object" && ENV_META in schema) return schema[ENV_META] ?? null;
+	return null;
+}
+/**
+* Catalogue introspectable des variables déclarées par {@link defineEnv}, lu sur
+* l'objet `env` retourné. Source unique pour générer `.env.example` (anti-dérive).
+*
+* @param env - l'objet retourné par `defineEnv` (catalogue de l'app).
+* @returns la liste ordonnée des métadonnées par variable (vide si non reconnu).
+*/
+function getEnvCatalog(env) {
+	if (env && typeof env === "object" && ENV_CATALOG in env) return env[ENV_CATALOG] ?? [];
+	return [];
+}
+/**
+* Résout la valeur d'une variable, en honorant la convention `<KEY>_FILE`
+* (ADR-0006 D3) : si `KEY` est absente mais `KEY_FILE` pointe un fichier (Docker
+* secret, K8s, Vault), lit son contenu (newline final retiré). Lever si les deux
+* sont posés (ambiguïté) ou si le fichier est illisible (fail-fast au boot).
+*
+* @param key - nom de la variable du catalogue.
+* @param source - source d'environnement.
+* @returns la valeur (directe ou lue du fichier), ou `undefined` si absente.
+*/
+function resolveFileEnv(key, source) {
+	const direct = source[key];
+	const filePath = source[`${key}_FILE`];
+	if (filePath === void 0 || filePath === "") return direct;
+	if (direct !== void 0 && direct !== "") throw new Error(`[nodefony] ${key} ET ${key}_FILE sont tous deux définis — n'en garder qu'un (un secret monté = ${key}_FILE).`);
+	try {
+		return readFileSync(filePath, "utf8").replace(/\r?\n$/, "");
+	} catch (e) {
+		throw new Error(`[nodefony] ${key}_FILE : lecture de "${filePath}" impossible (${e.message}).`, { cause: e });
+	}
+}
+/** Ensembles 12-factor (insensibles à la casse) pour la coercion booléenne. */
+const TRUTHY = /* @__PURE__ */ new Set([
+	"1",
+	"true",
+	"yes",
+	"on"
+]);
+const FALSY = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"no",
+	"off"
+]);
+/** Une variable d'env absente = `undefined`, `null`, ou chaîne vide. */
+function isAbsent(v) {
+	return v === void 0 || v === null || v === "";
+}
+function withDoc(schema, description) {
+	return description ? schema.describe(description) : schema;
+}
+function envString(opts = {}) {
+	const { default: def, optional, description, requiredIn } = opts;
+	const inner = optional && def === void 0 ? z.string().optional() : z.string();
+	return tagMeta(withDoc(z.preprocess((v) => isAbsent(v) ? def : v, inner), description), {
+		kind: "string",
+		optional: Boolean(optional && def === void 0),
+		default: def,
+		description,
+		requiredIn
+	});
+}
+function envNumber(opts = {}) {
+	const { default: def, optional, description, requiredIn } = opts;
+	const inner = optional && def === void 0 ? z.number().optional() : z.number();
+	return tagMeta(withDoc(z.preprocess((v) => {
+		if (isAbsent(v)) return def;
+		const n = Number(v);
+		return Number.isNaN(n) ? v : n;
+	}, inner), description), {
+		kind: "number",
+		optional: Boolean(optional && def === void 0),
+		default: def,
+		description,
+		requiredIn
+	});
+}
+/**
+* Variable d'env BOOLEAN 12-factor : `1/true/yes/on` → true, `0/false/no/off` →
+* false (insensible à la casse). Absente → `default` (défaut `false`). Valeur hors
+* de ces ensembles → erreur au boot (typo détectée, ex. `tru`).
+*/
+function envBoolean(opts = {}) {
+	const { default: def = false, description, requiredIn } = opts;
+	return tagMeta(withDoc(z.preprocess((v) => {
+		if (isAbsent(v)) return def;
+		const s = String(v).trim().toLowerCase();
+		if (TRUTHY.has(s)) return true;
+		if (FALSY.has(s)) return false;
+		return v;
+	}, z.boolean()), description), {
+		kind: "boolean",
+		optional: false,
+		default: def,
+		description,
+		requiredIn
+	});
+}
+function envEnum(values, opts = {}) {
+	const { default: def, optional, description, requiredIn } = opts;
+	const base = z.enum(values);
+	const inner = optional && def === void 0 ? base.optional() : base;
+	return tagMeta(withDoc(z.preprocess((v) => isAbsent(v) ? def : v, inner), description), {
+		kind: "enum",
+		optional: Boolean(optional && def === void 0),
+		default: def,
+		description,
+		requiredIn,
+		values: [...values]
+	});
+}
+/**
+* Les ÉTIQUETTES de l'environnement décrit par une source de variables.
+*
+* Deux notions cohabitent et ne se confondent pas : le MODE d'exécution
+* (`NODE_ENV`, que Node et les outils lisent) et l'environnement de DÉPLOIEMENT
+* (`NF_ENV`, ou l'alias de plateforme `APP_ENV`), qui distingue une préproduction
+* d'une production alors que les deux tournent en `production`. Une variable
+* requise « en preprod » doit donc pouvoir viser l'un ou l'autre — on rend les
+* DEUX étiquettes plutôt que d'en élire une, et `requiredIn` mord si l'une
+* d'elles correspond.
+*
+* Fonction PURE : la source est injectée, jamais `process.env` lu ici — c'est ce
+* qui la rend éprouvable ailleurs que dans l'environnement où elle tourne.
+*
+* @param source - la source de variables (`process.env`, ou une source de test).
+* @returns les étiquettes, sans doublon (`["production"]`, `["production", "preprod"]`).
+*/
+function resolveEnvStages(source) {
+	const mode = source.NODE_ENV || "development";
+	const deployment = source.APP_ENV || source.NF_ENV || "";
+	return deployment && deployment !== mode ? [mode, deployment] : [mode];
+}
+/**
+* `true` si la variable est REQUISE dans l'environnement décrit par `stages`.
+*
+* Le « ou » est volontaire : une variable sans défaut et non optionnelle est
+* requise PARTOUT (grammaire d'origine) ; `requiredIn` n'ajoute une exigence
+* que là où elle est nommée.
+*
+* 🔴 Une seule implémentation, et c'est tout l'enjeu du ticket : le boot
+* (`defineEnv`), le rapport (`nodefony env`) et le diagnostic (`nodefony doctor
+* --env production`) lisent CETTE fonction. Deux copies de la règle
+* divergeraient au premier cas particulier, chacune en passant ses propres
+* tests — le défaut que ce dépôt a déjà payé plusieurs fois.
+*
+* @param meta - les métadonnées de la variable.
+* @param stages - les étiquettes de l'environnement visé (cf {@link resolveEnvStages}).
+* @returns `true` si son absence doit être signalée dans cet environnement.
+*/
+function isEnvVarRequired(meta, stages) {
+	if (!meta.optional && meta.default === void 0) return true;
+	return isRequiredByStage(meta, stages);
+}
+/**
+* L'exigence qui vient de `requiredIn` SEULE — sans la règle d'origine.
+*
+* Séparée parce que les deux exigences ne se rapportent pas de la même façon :
+* une variable requise partout absente est déjà rejetée par le schéma, avec le
+* bon message ; une variable requise par l'ENVIRONNEMENT mérite le sien, qui
+* nomme cet environnement. Les confondre ferait dire « requise en production »
+* d'une variable qui l'était de toute façon.
+*
+* @param meta - les métadonnées de la variable.
+* @param stages - les étiquettes de l'environnement visé.
+* @returns `true` si l'exigence vient de l'environnement.
+*/
+function isRequiredByStage(meta, stages) {
+	return Boolean(meta.requiredIn?.some((stage) => stages.includes(stage)));
+}
+/**
+* Lit + valide un catalogue de variables d'environnement, une fois, au boot.
+*
+* @typeParam M - map `{ NOM_VAR: <helper env> }`.
+* @param catalog - déclaration des variables (clé = nom de la variable d'env).
+* @param source - source des valeurs (défaut `process.env` ; injectable pour les tests).
+* @returns objet **figé** + typé : `{ [NOM]: valeur coercée }`.
+* @throws Error (message agrégé nommant chaque variable fautive) si invalide.
+*/
+function defineEnv(catalog, source = process.env) {
+	const shape = z.object(catalog);
+	const input = {};
+	for (const key of Object.keys(catalog)) input[key] = resolveFileEnv(key, source);
+	const stages = resolveEnvStages(source);
+	const missing = Object.keys(catalog).filter((key) => {
+		const meta = readMeta(catalog[key]);
+		return isAbsent(input[key]) && meta !== null && isRequiredByStage(meta, stages);
+	});
+	if (missing.length > 0) throw new Error(`[nodefony] Variables d'environnement requises en ${stages.join("/")} et ABSENTES : ${missing.join(", ")} — les poser dans l'environnement du déploiement (ou en .env.local en local). Une valeur générée à la volée ne survit pas au redémarrage, et diffère d'un exemplaire à l'autre en grappe.`);
+	const result = shape.safeParse(input);
+	if (!result.success) {
+		const issues = result.error.issues.map((i) => `${i.path.join(".") || "(env)"}: ${i.message}`).join(" · ");
+		throw new Error(`[nodefony] Variables d'environnement invalides : ${issues}`);
+	}
+	const catalogMeta = Object.keys(catalog).map((name) => {
+		const m = readMeta(catalog[name]);
+		return m ? {
+			name,
+			...m
+		} : {
+			name,
+			kind: "string",
+			optional: true
+		};
+	});
+	const data = result.data;
+	Object.defineProperty(data, ENV_CATALOG, {
+		value: Object.freeze(catalogMeta),
+		enumerable: false,
+		configurable: true
+	});
+	return Object.freeze(data);
+}
+//#endregion
+export { defineEnv, envBoolean, envEnum, envNumber, envString, getEnvCatalog, isEnvVarRequired, isRequiredByStage, resolveEnvStages };

package/dist/node/config/envExample.js

@@ -0,0 +1,41 @@
+//#region src/config/envExample.ts
+/** Un nom de variable « sensible » (secret) → jamais de valeur d'exemple. */
+const SECRET_RE = /secret|password|key|token|credential/i;
+/** Rend une valeur par défaut en chaîne pour le modèle (objets/arrays en JSON). */
+function stringifyDefault(v) {
+	if (v === void 0) return "";
+	if (typeof v === "boolean" || typeof v === "number" || typeof v === "string") return String(v);
+	return JSON.stringify(v);
+}
+/** Bloc commenté d'UNE variable : doc (`.describe()`) + drapeaux + ligne `# NAME=val`. */
+function renderVar(v) {
+	const secret = SECRET_RE.test(v.name);
+	const out = [];
+	if (v.description) for (const dl of v.description.split("\n")) out.push(`# ${dl}`);
+	const flags = [];
+	if (v.values?.length) flags.push(`valeurs: ${v.values.join(" | ")}`);
+	if (v.default !== void 0) flags.push(`défaut: ${stringifyDefault(v.default)}`);
+	else if (v.optional) flags.push("optionnel");
+	else flags.push("REQUIS");
+	if (secret) flags.push("secret → .env.local, jamais committé");
+	out.push(`#   (${flags.join(" · ")})`);
+	out.push(`# ${v.name}=${secret ? "" : stringifyDefault(v.default)}`);
+	return out;
+}
+/**
+* Rend le contenu complet de `.env.example` depuis le catalogue.
+*
+* @param catalog - métadonnées des variables (via `getEnvCatalog(env)`).
+* @param opts.header - en-tête d'onboarding curé (préambule + précédence), placé en
+*   tête tel quel. Le corps (les variables) est, lui, entièrement dérivé.
+* @returns le texte du fichier (terminé par un seul saut de ligne).
+*/
+function renderEnvExample(catalog, opts = {}) {
+	const lines = [];
+	if (opts.header) lines.push(opts.header.trimEnd(), "");
+	for (const v of catalog) lines.push(...renderVar(v), "");
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+//#endregion
+export { renderEnvExample };