nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/config/defineEnv.d.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+/** Nature coercée d'une variable d'env du catalogue. */
+export type EnvVarKind = "string" | "number" | "boolean" | "enum";
+/**
+ * Métadonnées INTROSPECTABLES d'une variable du catalogue — capturées à la
+ * déclaration (le défaut serait sinon piégé dans la closure `z.preprocess`).
+ * Portées par le schéma Zod (clé non-énumérable) puis agrégées par `defineEnv`
+ * sur l'objet `env` retourné → alimentent la génération de `.env.example`.
+ */
+export interface EnvVarMeta {
+    /** Nature coercée (`string`/`number`/`boolean`/`enum`). */
+    readonly kind: EnvVarKind;
+    /** La variable peut-elle être absente (→ `undefined`) ? */
+    readonly optional: boolean;
+    /** Valeur par défaut déclarée (`undefined` si aucune). */
+    readonly default?: unknown;
+    /** Doc (`.describe()`), reprise telle quelle dans `.env.example`. */
+    readonly description?: string;
+    /** Valeurs autorisées (enum uniquement). */
+    readonly values?: readonly string[];
+    /**
+     * Environnements où la variable est REQUISE, même déclarée `optional`.
+     *
+     * Une variable requise « en production seulement » n'existait pas dans cette
+     * grammaire : on la déclarait `optional` — vrai sur le poste de développement,
+     * faux là où ça compte — et rien ne le disait avant le déploiement. Le cas
+     * n'est pas théorique : les secrets absents sont GÉNÉRÉS à la volée en
+     * développement, si bien qu'un secret éphémère en cluster fait refuser par un
+     * pod le jeton qu'un autre vient d'émettre, sans le moindre message.
+     *
+     * Les noms sont libres (`"production"`, `"staging"`, un environnement maison) :
+     * ils se comparent aux étiquettes de l'environnement courant, cf
+     * {@link resolveEnvStages}.
+     */
+    readonly requiredIn?: readonly string[];
+}
+/** {@link EnvVarMeta} + le nom de la variable (clé du catalogue). */
+export interface NamedEnvVarMeta extends EnvVarMeta {
+    readonly name: string;
+}
+/**
+ * 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).
+ */
+export declare function getEnvCatalog(env: unknown): readonly NamedEnvVarMeta[];
+interface BaseOpts {
+    /** Doc de la variable (attachée via `.describe()` → introspection Studio). */
+    description?: string;
+    /**
+     * Environnements où la variable devient REQUISE (`["production"]`).
+     *
+     * Elle reste `optional` partout ailleurs : le poste de développement démarre
+     * sans elle, le déploiement visé refuse de démarrer sans elle, et
+     * `nodefony doctor --env production` la nomme avant qu'on y aille.
+     */
+    requiredIn?: readonly string[];
+}
+interface StrOpts extends BaseOpts {
+    /** Valeur par défaut si la variable est absente. */
+    default?: string;
+    /** Autorise l'absence (résultat `undefined`) — sinon variable requise. */
+    optional?: boolean;
+}
+interface NumOpts extends BaseOpts {
+    default?: number;
+    optional?: boolean;
+}
+interface BoolOpts extends BaseOpts {
+    /** Valeur par défaut si absente (défaut : `false`). */
+    default?: boolean;
+}
+interface EnumOpts<T extends string> extends BaseOpts {
+    default?: T;
+    optional?: boolean;
+}
+/**
+ * Variable d'env STRING. Avec `default` → toujours présente ; `optional:true` →
+ * `string | undefined` ; sinon requise (absente → erreur au boot).
+ */
+export declare function envString(opts: StrOpts & {
+    optional: true;
+}): z.ZodType<string | undefined>;
+export declare function envString(opts?: StrOpts): z.ZodType<string>;
+/**
+ * Variable d'env NUMBER (coercée). Valeur non numérique → erreur au boot.
+ */
+export declare function envNumber(opts: NumOpts & {
+    optional: true;
+}): z.ZodType<number | undefined>;
+export declare function envNumber(opts?: NumOpts): z.ZodType<number>;
+/**
+ * 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`).
+ */
+export declare function envBoolean(opts?: BoolOpts): z.ZodType<boolean>;
+/**
+ * Variable d'env ENUM (ensemble fermé). Valeur hors liste → erreur au boot.
+ * Le type littéral est préservé (`env.X` typé sur l'union exacte).
+ */
+export declare function envEnum<T extends readonly [string, ...string[]]>(values: T, opts: EnumOpts<T[number]> & {
+    optional: true;
+}): z.ZodType<T[number] | undefined>;
+export declare function envEnum<T extends readonly [string, ...string[]]>(values: T, opts?: EnumOpts<T[number]>): z.ZodType<T[number]>;
+/**
+ * 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"]`).
+ */
+export declare function resolveEnvStages(source: Record<string, string | undefined>): readonly string[];
+/**
+ * `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.
+ */
+export declare function isEnvVarRequired(meta: Pick<EnvVarMeta, "optional" | "default" | "requiredIn">, stages: readonly string[]): boolean;
+/**
+ * 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.
+ */
+export declare function isRequiredByStage(meta: Pick<EnvVarMeta, "requiredIn">, stages: readonly string[]): boolean;
+/**
+ * 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.
+ */
+export declare function defineEnv<M extends Record<string, z.ZodTypeAny>>(catalog: M, source?: Record<string, string | undefined>): {
+    readonly [K in keyof M]: z.infer<M[K]>;
+};
+export {};

package/dist/types/config/envExample.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Générateur de `.env.example` depuis le catalogue introspectable `defineEnv`
+ * (ADR-0006 — une seule source de vérité). Pur : prend les métadonnées
+ * ({@link NamedEnvVarMeta} via `getEnvCatalog`) et rend le modèle d'onboarding —
+ * toutes les variables COMMENTÉES (un `.example` ne pose rien, il documente).
+ *
+ * Anti-dérive : `env.ts` (le catalogue) est la SEULE liste de variables,
+ * `.env.example` en est DÉRIVÉ. La commande `nodefony env --example` écrit le
+ * fichier (en-tête curé possible : `.env.example.head`) ; son `--check` échoue
+ * si le fichier diverge du catalogue — pre-commit, CI.
+ */
+import type { NamedEnvVarMeta } from "./defineEnv.js";
+/**
+ * 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).
+ */
+export declare function renderEnvExample(catalog: readonly NamedEnvVarMeta[], opts?: {
+    header?: string;
+}): string;

package/dist/types/config/envOverride.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Override générique de configuration par variable d'environnement (ADR-0006 D3).
+ *
+ * Forme : `NF__<MODULE>__<CHEMIN…>=valeur`. Le **double underscore `__`** sépare
+ * les niveaux (choix .NET Core / Docker — explicite, sans ambiguïté avec le
+ * camelCase). Le 1ᵉʳ segment = le module (`SECURITY` → `@nodefony/security`), les
+ * suivants = le chemin dans sa config. Les segments sont **insensibles à la casse**
+ * et résolus contre les clés RÉELLES de la config (`ACCESSTTLS` → `accessTtlS`).
+ *
+ * Précédence (cf ADR-0006 D5) : appliqué APRÈS le merge de l'app (`use()` /
+ * `module-<name>`) et AVANT la validation Zod du module → le schéma valide/rejette
+ * la valeur surchargée (fail-closed). Résolu **1× au boot** (hors hot path).
+ *
+ * @example
+ * ```bash
+ * NF__SECURITY__JWT__ACCESSTTLS=300
+ * NF__HTTP__SERVERS__HTTPS__PORT=8443
+ * NF__SECURITY__CORS__ORIGINS=https://a.com,https://b.com   # CSV → array
+ * ```
+ */
+/** Un override d'environnement résolu (issu d'une variable `NF__…`). */
+export interface NfEnvOverride {
+    /** Variable d'env d'origine (ex. `NF__SECURITY__JWT__ACCESSTTLS`). */
+    readonly envKey: string;
+    /** Segment module normalisé minuscule (ex. `security`). */
+    readonly moduleSeg: string;
+    /** Chemin dans la config du module, segments minuscules (ex. `["jwt","accessttls"]`). */
+    readonly path: string[];
+    /** Valeur coercée (booléen / nombre / tableau CSV / objet JSON / chaîne). */
+    readonly value: unknown;
+    /**
+     * La chaîne BRUTE, telle que l'environnement la porte.
+     *
+     * Gardée parce que {@link coerceEnvValue} devine le type sans connaître la
+     * cible : au moment d'APPLIQUER l'override, la config remplacée révèle le type
+     * attendu, et seule la chaîne d'origine permet alors de convertir juste
+     * ({@link coerceEnvValueLike}). Sans elle, `"1"` était perdu en `Number(1)`
+     * avant même qu'on sache qu'une clé booléenne l'attendait.
+     */
+    readonly raw: string;
+}
+/**
+ * Coerce une valeur d'environnement (toujours une chaîne) vers son type probable.
+ *
+ * Coercion **explicite** (le piège `z.coerce.boolean("false") === true` est évité) :
+ * `"true"/"false"` → booléen ; entier/décimal → nombre ; `[…]`/`{…}` → JSON ;
+ * une chaîne contenant `,` → tableau de chaînes (CSV) ; sinon la chaîne brute.
+ *
+ * @param raw - valeur brute de la variable d'environnement.
+ * @returns la valeur typée.
+ */
+export declare function coerceEnvValue(raw: string): unknown;
+/**
+ * Scanne `env` et extrait tous les overrides `NF__<MODULE>__<CHEMIN…>`.
+ *
+ * Ignore les clés sans au moins un module + un champ (`NF__X` seul), et les
+ * valeurs `undefined`. Ne touche PAS `env` (lecture seule).
+ *
+ * @param env - source d'environnement (typiquement `process.env`).
+ * @returns la liste des overrides résolus (vide si aucun).
+ */
+export declare function parseNfEnvOverrides(env: NodeJS.ProcessEnv): NfEnvOverride[];
+/**
+ * La valeur d'environnement convertie vers le type de ce qu'elle REMPLACE.
+ *
+ * Une variable d'environnement est toujours une chaîne ; seul le schéma sait ce
+ * qu'il attend. {@link coerceEnvValue} devine sans lui, et sa devinette rendait
+ * un type FAUX que la validation Zod refusait ensuite : `NF__HTTP__TRUSTPROXY=1`
+ * donnait `Number(1)`, qu'aucun membre de `z.union([boolean, string, array])`
+ * n'accepte — une variable DOCUMENTÉE faisait échouer le boot, à rebours du
+ * 12-factor que l'ADR-0006 revendique.
+ *
+ * L'information manquante est pourtant à portée : la config porte déjà le
+ * DÉFAUT du schéma à cet endroit, et son type dit ce qui est attendu.
+ *
+ * ⚠️ **Le type existant ORIENTE, il ne décide pas.** Convertir aveuglément vers
+ * le type de la valeur remplacée serait une faille : `trustProxy` a pour défaut
+ * `false` mais accepte aussi une CIDR, et `10.0.0.0/8` deviendrait `true`,
+ * c'est-à-dire une confiance TOTALE envers les `X-Forwarded-*`. Seuls des
+ * littéraux booléens reconnus sont convertis ; tout le reste retombe sur la
+ * devinette, qui garde la chaîne.
+ *
+ * Les cibles NON ambiguës (nombre, tableau, objet, valeur absente) gardent la
+ * devinette : elle y est juste, et le CSV → tableau documenté en dépend.
+ *
+ * @param raw - la chaîne brute de la variable d'environnement.
+ * @param existing - la valeur actuellement en place (le défaut du schéma).
+ * @returns la valeur à poser.
+ */
+export declare function coerceEnvValueLike(raw: string, existing: unknown): unknown;
+/**
+ * Type déclaré par un JSON Schema pour un chemin — `null` si le chemin n'y est
+ * pas déclaré, ou si le schéma prend une forme que cette lecture ne comprend pas.
+ *
+ * **Le schéma dit ce que la VALEUR ignore.** Une clé optionnelle sans défaut
+ * n'existe pas dans l'objet de configuration : la résolution par les clés
+ * présentes la déclare donc « inconnue » et refuse la surcharge, pour une clé
+ * pourtant déclarée, documentée et lue par le code. Ce sont précisément les
+ * réglages dont l'ABSENCE est signifiante — ceux que le framework résout par
+ * environnement quand on ne les écrit pas — et donc ceux qu'un exploitant a le
+ * plus besoin de poser sur une image déjà construite.
+ *
+ * Le core n'importe PAS zod : chaque module publie son schéma en JSON pur
+ * (`Module.configSchema()`), et cette fonction n'y navigue que par `properties`.
+ * Toute autre forme — `anyOf`, `$ref`, union — rend `null` : on n'assouplit que
+ * ce qu'on COMPREND, et le refus d'aujourd'hui reste le comportement par défaut.
+ *
+ * @param schema - JSON Schema du module, tel que `Module.configSchema()` le rend.
+ * @param path - segments du chemin (minuscules).
+ * @returns le `type` JSON Schema de la feuille, `"unknown"` si déclarée sans type, ou `null`.
+ */
+export declare function declaredTypeAtPath(schema: unknown, path: string[]): string | null;
+/**
+ * Convertit une chaîne d'environnement vers le type que le SCHÉMA déclare.
+ *
+ * Sert quand la clé est absente de la valeur : il n'y a alors rien à imiter, et
+ * {@link coerceEnvValueLike} devinerait — `"1"` deviendrait le nombre `1` là où
+ * un booléen est attendu, et le parse du module refuserait une surcharge
+ * pourtant correcte.
+ *
+ * @param raw - la chaîne d'environnement.
+ * @param type - le `type` JSON Schema de la feuille.
+ * @returns la valeur convertie ; la devinette générique si le type est inconnu.
+ */
+export declare function coerceEnvValueForType(raw: string, type: string): unknown;
+/**
+ * Pose `value` dans `target` au `path` donné, en résolvant chaque segment contre
+ * les clés EXISTANTES (insensible à la casse). N'altère QUE des chemins déjà
+ * présents dans la config (= champs ayant un défaut) — un chemin inconnu n'est pas
+ * créé (évite une clé fantôme à la mauvaise casse que le Zod ignorerait
+ * silencieusement) : la fonction renvoie alors `false` pour signalement.
+ *
+ * Quand `raw` est fourni, la valeur posée est RECALCULÉE contre celle qu'elle
+ * remplace ({@link coerceEnvValueLike}) : c'est ici, et nulle part ailleurs,
+ * qu'on connaît à la fois la chaîne d'origine et le type attendu. Sans `raw`, le
+ * comportement est inchangé — aucun appelant existant ne bouge.
+ *
+ * Quand `schema` est fourni, un chemin ABSENT de la valeur mais DÉCLARÉ par le
+ * schéma est créé — c'est le cas d'une clé optionnelle sans défaut, dont
+ * l'absence est signifiante et que rien ne permettait de poser jusqu'ici. La
+ * garde reste entière pour ce qui n'est ni présent ni déclaré : c'est elle qui
+ * empêche une clé fantôme à la mauvaise casse, que le parse du module
+ * strippe ensuite SANS un mot.
+ *
+ * @param target - objet de config du module (muté en place).
+ * @param path - segments du chemin (minuscules).
+ * @param value - valeur à poser (devinée par {@link coerceEnvValue}).
+ * @param raw - la chaîne d'environnement d'origine, quand elle est connue.
+ * @param schema - JSON Schema du module ({@link declaredTypeAtPath}), s'il en publie un.
+ * @returns `true` si appliqué, `false` si le chemin n'est ni présent ni déclaré.
+ */
+export declare function applyResolvedPath(target: Record<string, unknown>, path: string[], value: unknown, raw?: string, schema?: unknown): boolean;
+/**
+ * Relit la valeur posée à `path` — la SYMÉTRIQUE de {@link applyResolvedPath}.
+ *
+ * Sert au journal du boot : depuis que la valeur est convertie contre le type
+ * attendu, ce qui est écrit dans la config n'est plus forcément ce que
+ * `coerceEnvValue` avait deviné. Journaliser la devinette afficherait
+ * `TRUSTPROXY = 1` sur une config qui porte `true` — le genre d'écart qu'on
+ * poursuit une heure avant de comprendre qu'il vient du journal.
+ *
+ * @param target - objet de config du module.
+ * @param path - segments du chemin (minuscules).
+ * @returns la valeur en place, ou `undefined` si le chemin ne résout pas.
+ */
+export declare function readResolvedPath(target: Record<string, unknown>, path: string[]): unknown;
+/** Heuristique : ce chemin porte-t-il un secret (à rédiger dans les logs) ? */
+export declare function pathLooksSecret(path: string[]): boolean;
+/**
+ * Distance d'édition de Levenshtein entre deux chaînes (2 lignes glissantes, pas
+ * de matrice complète). Sert au « did you mean » : proposer la clé la plus proche
+ * quand un segment d'override `NF__*` est mal orthographié.
+ *
+ * @param a - première chaîne.
+ * @param b - seconde chaîne.
+ * @returns le nombre minimal d'insertions/suppressions/substitutions.
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * Parmi `candidates`, renvoie le plus proche de `target` (insensible à la casse)
+ * SI la distance d'édition reste plausible (≤ 40 % de la plus longue, plancher 2)
+ * — sinon `null` (ne jamais suggérer une correspondance absurde). Calque le « the
+ * most similar command is » de git : aide au debug d'un nom de variable d'env mal tapé.
+ *
+ * @param target - segment fourni par l'utilisateur (issu d'un `NF__…`).
+ * @param candidates - clés réelles existantes à comparer.
+ * @returns la meilleure suggestion, ou `null` si trop éloignée.
+ */
+export declare function closestMatch(target: string, candidates: string[]): string | null;
+/** Échec de résolution d'un chemin d'override : où ça a cassé + ce qui existait. */
+export interface ResolveFailure {
+    /** Index (dans `path`) du segment qui n'a pas résolu. */
+    readonly index: number;
+    /** Segment fautif (minuscule, tel que fourni). */
+    readonly segment: string;
+    /** Clés réelles disponibles au niveau où la résolution a échoué. */
+    readonly available: string[];
+}
+/**
+ * Rejoue la résolution de `path` contre `target` pour DIAGNOSTIQUER un échec :
+ * renvoie le 1ᵉʳ segment qui ne correspond à aucune clé (ou qui traverse un
+ * non-objet) + les clés disponibles à ce niveau. `null` si tout résout (pas un
+ * échec). Miroir de lecture seule de {@link applyResolvedPath} — ne mute rien.
+ *
+ * @param target - objet de config du module (non muté).
+ * @param path - segments du chemin (minuscules).
+ * @returns le détail de l'échec, ou `null` si le chemin résout entièrement.
+ */
+export declare function diagnoseResolveFailure(target: Record<string, unknown>, path: string[]): ResolveFailure | null;
+/**
+ * Clés déclarées par le schéma au niveau `prefix` — vide si le schéma ne dit
+ * rien de ce niveau, ou s'il prend une forme que cette lecture ne comprend pas.
+ *
+ * @param schema - JSON Schema du module, ou `undefined`.
+ * @param prefix - segments déjà traversés (minuscules).
+ * @returns les noms de propriétés déclarés à ce niveau.
+ */
+export declare function declaredKeysAtPath(schema: unknown, prefix: string[]): string[];
+/**
+ * Construit le suffixe de message « did you mean » d'un chemin d'override qui n'a
+ * pas résolu contre `target` : nomme le segment fautif, propose la clé la plus
+ * proche et liste les clés disponibles. Chaîne vide si rien d'exploitable.
+ * Partagé par les overrides de MODULE (Kernel) et d'APP (defineConfig).
+ *
+ * **Les clés DÉCLARÉES comptent autant que les présentes.** Une clé optionnelle
+ * sans défaut n'existe pas dans la valeur : ne lister que celle-ci proposerait à
+ * l'utilisateur une liste amputée, et lui ferait chercher une faute de frappe
+ * dans un nom parfaitement écrit — l'inverse du service qu'un « did you mean »
+ * doit rendre.
+ *
+ * @param target - objet de config cible (lu seul, non muté).
+ * @param path - segments du chemin de l'override (minuscules).
+ * @param schema - JSON Schema du module, quand il en publie un.
+ * @returns un suffixe commençant par ` — …`, ou `""`.
+ */
+export declare function resolveFailureHint(target: Record<string, unknown>, path: string[], schema?: unknown): string;

package/dist/types/config/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Barrel du moteur de configuration `defineConfig` (back-only, D1).
+ * Ré-exporté par le barrel node `src/index.ts` → `import { defineConfig } from "nodefony"`.
+ */
+export { defineConfig, isConfigDescriptor } from "./defineConfig.js";
+export type { AppConfigDescriptor } from "./defineConfig.js";
+export { use } from "./use.js";
+export type { NodefonyModuleConfig, ConfigOf, UseOptions } from "./use.js";
+export { defineEnv, envString, envNumber, envBoolean, envEnum, getEnvCatalog, } from "./defineEnv.js";
+export type { EnvVarKind, EnvVarMeta, NamedEnvVarMeta } from "./defineEnv.js";
+export { renderEnvExample } from "./envExample.js";
+export { defaultAppConfig } from "./defaults.js";
+export { parseNfEnvOverrides } from "./envOverride.js";
+export type { NfEnvOverride } from "./envOverride.js";
+export { computeConfigProvenance, extractJsonSchemaDefaults, } from "./configProvenance.js";
+export type { ConfigOrigin } from "./configProvenance.js";
+export { appConfigSchema, appConfigJsonSchema, validateAppConfig, } from "./schema.js";
+export type { AppConfig } from "./schema.js";
+export { resolveInfra, resolveAutoStore, readStoreLocation, parseDatabaseUrl, sqliteFilenameFromUrl, AUTO_STORE, EMPTY_INFRA, } from "./infra.js";
+export type { IInfra, IInfraDatabase, IInfraCache, IInfraLogs, IAutoStoreResolution, InfraSqlDialect, DatabaseFamily, StoreKind, InfraEnvSource, } from "./infra.js";
+export { configReactivity, getConfigReactivity } from "./reactivity.js";
+export type { Reactivity } from "./reactivity.js";
+export type { AppConfigInput, ResolvedAppConfig, ConfigInput, ConfigContext, KnownModule, ModuleEntryInput, ModuleManifestInput, AppMeta, ServersConfig, HttpServerConfig, HttpsServerConfig, LogConfig, LogFileConfig, LogDestinationConfig, } from "./types.js";

package/dist/types/config/infra.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Résolution de l'INFRA DÉCLARÉE depuis l'environnement (modèle « infra déclarée »).
+ *
+ * L'utilisateur ne configure pas chaque brique : il déclare son infra via des
+ * URLs (pattern Rails/Django/Symfony) :
+ * - `NF_DATABASE_URL` (alias plateforme `DATABASE_URL`) → infra `database` (durable)
+ * - `NF_REDIS_URL` (alias plateforme `REDIS_URL`) → infra `cache` (éphémère partagé)
+ * - `NF_LOKI_URL` / `NF_OPENSEARCH_URL` → infra `logs` (relecture backplane)
+ *
+ * Les briques dont le store vaut `"auto"` sont résolues par l'infra déclarée
+ * ({@link resolveAutoStore}) ; une valeur explicite gagne toujours (moindre
+ * surprise, 12-factor). Aucune cascade runtime implicite : charger un module
+ * ne déplace jamais une brique — seule la déclaration d'infra le fait.
+ */
+/** Dialecte SQL déduit du scheme de l'URL du infra `database`. */
+export type InfraSqlDialect = "sqlite" | "postgres" | "mysql";
+/** Famille du infra `database` — pilote le choix de l'adapter (drizzle/mongoose). */
+export type DatabaseFamily = "sql" | "mongo";
+/** Infra `database` résolu depuis `NF_DATABASE_URL`/`DATABASE_URL`. */
+export interface IInfraDatabase {
+    /** URL déclarée telle quelle (peut porter des credentials — ne jamais logger brute). */
+    url: string;
+    /** Scheme normalisé en minuscules, sans `:` (ex. `postgres`, `sqlite`, `mongodb`). */
+    scheme: string;
+    family: DatabaseFamily;
+    /** Dialecte SQL (famille `sql`) — `null` pour la famille `mongo`. */
+    dialect: InfraSqlDialect | null;
+}
+/** Infra `cache` résolu depuis `NF_REDIS_URL`/`REDIS_URL`. */
+export interface IInfraCache {
+    /** URL redis déclarée (peut porter des credentials — ne jamais logger brute). */
+    url: string;
+}
+/** Infra `logs` (relecture backplane) — les DEUX URLs peuvent être présentes. */
+export interface IInfraLogs {
+    lokiUrl?: string;
+    opensearchUrl?: string;
+}
+/** L'infra déclarée — `null` = non déclarée. */
+export interface IInfra {
+    database: IInfraDatabase | null;
+    cache: IInfraCache | null;
+    logs: IInfraLogs | null;
+    /**
+     * Override GLOBAL de sélection de store (`NF_STORE`) — force TOUTE brique `auto`
+     * vers ce backend, en amont de toute préférence d'infra. Cas d'usage : `memory`
+     * pour un banc de CHARGE (mesurer le framework sans le goulot sqlite/disque), sans
+     * toucher aux configs par brique. `undefined`/`null` = pas d'override. N'affecte
+     * JAMAIS un store configuré EXPLICITEMENT (celui-ci ne passe pas par `auto`).
+     */
+    forceStore?: string | null;
+}
+/** Source d'environnement (forme de `process.env`) — injectable pour les tests. */
+export type InfraEnvSource = Record<string, string | undefined>;
+/**
+ * Parse l'URL du infra `database` : scheme → famille + dialecte.
+ *
+ * @throws Error si le scheme n'est pas supporté — fail-loud au boot : une URL
+ *   de base inconnue ne doit JAMAIS retomber silencieusement sur sqlite.
+ */
+export declare function parseDatabaseUrl(url: string): IInfraDatabase;
+/**
+ * Fichier SQLite d'une URL `sqlite:` du infra `database`.
+ * Formes acceptées : `sqlite::memory:`, `sqlite:./relatif.db`, `sqlite:/abs.db`,
+ * `sqlite:///abs.db`. URL vide après le scheme → `:memory:`.
+ */
+export declare function sqliteFilenameFromUrl(url: string): string;
+/**
+ * Résout les 3 infra déclarée depuis l'environnement. Fonction PURE
+ * (aucun kernel) : consommée par le Kernel (1 fois, mémoïsé), par le contexte
+ * `defineConfig` (`ctx.infra`) et par les builders de config des modules
+ * adapters (drizzle/mongoose/redis) dans leur couche env.
+ *
+ * @param env - source d'environnement (défaut `process.env`).
+ * @throws Error si l'URL du infra `database` a un scheme non supporté.
+ */
+export declare function resolveInfra(env?: InfraEnvSource): IInfra;
+/** Sentinelle des champs `store` : « laisser le framework choisir selon l'infra déclarée ». */
+export declare const AUTO_STORE = "auto";
+/** Infra vide (rien de déclaré) — fallback sûr quand le kernel est absent (tests). */
+export declare const EMPTY_INFRA: IInfra;
+/**
+ * Nature de la donnée d'une brique — pilote l'ordre de préférence des backends :
+ * - `durable` (tokens, passkeys, audit, webhooks, user) → infra database.
+ * - `ephemeral` (idempotence) → infra cache, sinon database.
+ * - `session` → cache, sinon database, sinon fallback fichier.
+ */
+export type StoreKind = "durable" | "ephemeral" | "session";
+/** Choix d'un backend pour `"auto"` + provenance lisible (log de boot, Studio). */
+export interface IAutoStoreResolution {
+    store: string;
+    reason: string;
+}
+/** Catégorie de provenance d'un store résolu (dérivée de la valeur configurée). */
+export type StoreProvenance = "infra" | "explicit";
+/**
+ * Résolution EFFECTIVE d'une brique de persistance, capturée au boot par le
+ * consommateur (au moment exact où il pose son store au container) et retenue
+ * dans le registre du Kernel ({@link IKernel.registerStoreResolution}). C'est la
+ * VÉRITÉ vécue — y compris les replis annoncés du lot 4 (session → `"files"` en
+ * dev) — pas une re-dérivation à la volée. Alimente l'écran Studio « Stores ».
+ */
+export interface IStoreResolution {
+    /** Identifiant de la brique (ex. `"tokens"`, `"session"`, `"audit"`). */
+    brick: string;
+    /** Nature de la donnée — pilote la durabilité affichée ({@link StoreKind}). */
+    nature: StoreKind;
+    /** Valeur configurée telle quelle : `"auto"` (sentinelle) ou un backend explicite. */
+    configured: string;
+    /** Backend effectivement résolu et posé au runtime. */
+    resolved: string;
+    /**
+     * Backends RÉELLEMENT enregistrés pour cette brique (`listXStores()`), capturés
+     * par le consommateur — évite à l'endpoint d'importer les registres (le cœur
+     * `@nodefony/framework` ne peut pas dépendre de `@nodefony/security`/`http`).
+     */
+    available: readonly string[];
+    /**
+     * Provenance : `"infra"` (résolu depuis l'infra déclarée, `configured === "auto"`)
+     * ou `"explicit"` (backend nommé dans la config/env de l'app).
+     */
+    provenance: StoreProvenance;
+    /** Raison lisible (FR) de la résolution — de `resolveAutoStore` ou construite. */
+    reason: string;
+    /** Chemin du champ de config (ex. `"security.tokenStore.store"`) — croise la provenance de champ Studio. */
+    configPath?: string;
+    /**
+     * Emplacement PHYSIQUE lisible du store, lu depuis l'instance au boot
+     * ({@link readStoreLocation}) — base SQLite pour `drizzle`. `undefined`
+     * pour un store `memory` (volatil) ou un backend réseau (l'emplacement = l'infra
+     * déclarée, déjà surfacée à part). Répond à « où sont écrites mes données ? » dans Studio.
+     */
+    location?: string;
+}
+/**
+ * Résout la sentinelle `"auto"` d'une brique en nom de backend, borné aux
+ * backends RÉELLEMENT enregistrés (`available` = `listXStores()` du registre —
+ * reflète l'auto-register des adapters chargés). Couverture partielle d'une infra
+ * (ex. audit sans impl mongoose) → repli `fallback` avec raison ANNONCÉE,
+ * jamais d'échec : le principe « fallback annoncé, pas de dégradation
+ * silencieuse » vit dans la raison retournée, que l'appelant DOIT logger.
+ *
+ * @param kind - nature de la donnée ({@link StoreKind}).
+ * @param infra - infra résolue ({@link resolveInfra}).
+ * @param available - backends enregistrés dans le registre de la brique.
+ * @param fallback - backend de repli (défaut `"memory"` — c'est aussi ce que passe
+ *   le service de session : aucun appelant ne demande un autre repli).
+ */
+export declare function resolveAutoStore(kind: StoreKind, infra: IInfra, available: readonly string[], fallback?: string): IAutoStoreResolution;
+/**
+ * Déduit le nom court du backend d'un store à partir de la classe concrète de
+ * son instance (convention de nommage `<Backend>XxxStore` → `drizzle`, `mongoose`,
+ * `redis`, `memory`, `file`). Sert à retrouver le backend RÉEL d'un adapter posé
+ * au container quand la brique a été résolue en `"auto"` (l'adapter court-circuite
+ * la fabrique nommée). Classe non reconnue → nom de classe brut (honnête).
+ *
+ * @param store - instance de store (lue défensivement — seul `constructor.name`).
+ * @returns nom court du backend, ou `"inconnu"` si l'instance n'expose pas de classe.
+ */
+export declare function deriveStoreBackend(store: unknown): string;
+/**
+ * Lit l'emplacement PHYSIQUE d'un store depuis son instance (getter public
+ * `location`), pour l'écran Studio « Stores » — répond à « où mes données sont-elles
+ * écrites ? ». Un store fichier (passkeys, TOTP, sessions) expose le chemin de son
+ * fichier/dossier ; un store `memory` ou un backend réseau (drizzle/redis/mongoose)
+ * n'expose rien → `undefined` (l'UI dérive « en mémoire » ou renvoie à l'infra).
+ *
+ * @param store - instance de store (lue défensivement — seul un getter `location` string).
+ * @returns chemin lisible, ou `undefined` si le store n'expose pas d'emplacement.
+ */
+export declare function readStoreLocation(store: unknown): string | undefined;

package/dist/types/config/reactivity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RÉACTIVITÉ déclarée de chaque champ de config (pilier #2 du chantier).
+ *
+ * Certaines options s'appliquent À CHAUD (sans redémarrer — niveau de log, format
+ * de requête, sources debug) ; d'autres sont FIGÉES AU BOOT (ports, protocole,
+ * liste modules, TLS, cluster). Le dev et Studio doivent le savoir sans deviner.
+ *
+ * Ce module porte la **vérité déclarée** (quel champ est `hot`), co-localisée au
+ * schéma et aussi taggée `@reactivity` en TSDoc sur {@link AppConfigInput} (hover
+ * éditeur). L'APPLICATION live (`Kernel.applyConfigPatch` + setters services + UI
+ * Studio avec badge `🔥 à chaud` / `🔒 redémarrage requis`) est un follow-up : ici
+ * on ne fait que CLASSER, pas appliquer.
+ *
+ * Défaut SÛR : un champ non listé = `boot` (conservateur — on ne prétend jamais
+ * `hot` par erreur).
+ */
+/** Réactivité d'un champ de config. */
+export type Reactivity = "hot" | "boot";
+/**
+ * Champs applicables À CHAUD (chemin en dot-notation). Tout champ absent est `boot`.
+ *
+ * `log.active` / `log.debug` / `log.requestFormat` = exactement le cadre de la
+ * « fenêtre d'audit » (élever la verbosité prod temporairement sans reboot).
+ */
+export declare const configReactivity: {
+    readonly "log.active": "hot";
+    readonly "log.debug": "hot";
+    readonly "log.requestFormat": "hot";
+};
+/**
+ * Réactivité d'un champ par son chemin dot-notation ; `boot` par défaut (sûr).
+ *
+ * @param path - chemin du champ, ex. `"log.debug"` ou `"servers.http.port"`.
+ * @returns `"hot"` si le champ peut s'appliquer à chaud, sinon `"boot"`.
+ */
+export declare function getConfigReactivity(path: string): Reactivity;