nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/cli/cardReport.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Composition de la CARTE DE VISITE d'une application — module PUR.
+ *
+ * Deux portes la servent, et c'est tout l'intérêt de vivre ici :
+ * - la CLI (`nodefony card`, standalone 0-boot — `cli/card.ts`), qui répond même
+ *   sur une application NON CONSTRUITE ou lancée sans `NODE_ENV` ;
+ * - le module `@nodefony/devkit` (route HTTP + service), qui la dérive du Kernel
+ *   en marche et connaît alors les modules réellement CHARGÉS.
+ *
+ * Pourquoi au cœur et non dans le module : une capacité qui doit répondre
+ * **sans installation** ou **application cassée** ne peut pas dépendre d'un
+ * module, par construction — c'est la règle que `check`, `env` et `inspect`
+ * suivent déjà. Le module, lui, importe cette fonction : une seule composition,
+ * deux portes, aucune divergence possible.
+ */
+/** Identité de l'application qui répond. */
+export interface ICardAppInfo {
+    /** Nom de l'application. */
+    name: string;
+    /** Version déclarée par son `package.json`. */
+    version: string;
+    /** Environnement de run (`development`, `production`, `staging`…). */
+    environment: string;
+}
+/**
+ * Une PORTE : un endroit où aller chercher la suite.
+ *
+ * Volontairement plat et ORDONNÉ (un tableau, pas un objet indexé) : ce qui est
+ * lu en premier est ce qui compte, et un lecteur qui s'arrête au milieu garde le
+ * plus utile. Mesuré au banc : un agent lit la tête d'un fichier, pas sa fin.
+ */
+export interface ICardDoor {
+    /** Ce que la porte ouvre, en quelques mots. */
+    title: string;
+    /** URL servie, ou chemin de fichier relatif à la racine de l'application. */
+    where: string;
+    /** Pourquoi y aller — la raison, pas la description. */
+    why: string;
+}
+/**
+ * Un VERBE : une commande à lancer.
+ *
+ * ⚠️ Toujours préfixée `npx` — le binaire vit dans les `node_modules` de
+ * l'application, et `nodefony` nu rend 127.
+ */
+export interface ICardVerb {
+    /** Commande complète, prête à coller dans un terminal. */
+    command: string;
+    /** Ce qu'elle répond. */
+    why: string;
+}
+/**
+ * D'où vient la liste de modules — et donc ce que la carte a le droit d'affirmer.
+ *
+ * `runtime` : l'application tourne, ce sont les modules CHARGÉS (le gating
+ * `policy`/`when` a déjà eu lieu). `static` : rien n'a démarré, ce sont les
+ * modules INSTALLÉS lus dans le `package.json` — un module installé peut très
+ * bien ne pas être chargé. La distinction est rendue à l'écran : une carte qui
+ * présenterait les deux du même mot mentirait la moitié du temps.
+ */
+export type CardSource = "runtime" | "static";
+/** La carte de visite complète de l'application. */
+export interface ICard {
+    app: ICardAppInfo;
+    /** Version du framework qui sert cette application. */
+    nodefony: {
+        version: string;
+    };
+    /** Modules, triés — chargés ou installés selon {@link ICard.source}. */
+    modules: string[];
+    /** Ce que `modules` décrit réellement. */
+    source: CardSource;
+    /** Où aller, par valeur décroissante. */
+    doors: ICardDoor[];
+    /** Quoi lancer, par valeur décroissante. */
+    verbs: ICardVerb[];
+}
+/**
+ * État minimal dont {@link ICard} se dérive.
+ *
+ * INJECTÉ, jamais lu : c'est ce qui rend la construction de la carte éprouvable
+ * sans Kernel ni serveur, et ce qui l'empêche d'inventer quoi que ce soit.
+ */
+export interface ICardInput {
+    appName: string;
+    appVersion: string;
+    nodefonyVersion: string;
+    environment: string;
+    /** Noms courts des modules (la clé du conteneur, pas le nom npm). */
+    modules: string[];
+    /** Ce que `modules` décrit — défaut `runtime` (l'appel historique). */
+    source?: CardSource;
+}
+/**
+ * Construit la carte de visite d'une application à partir de son état.
+ *
+ * Fonction **PURE** : elle reçoit l'état, elle ne le lit pas. C'est ce qui la
+ * rend éprouvable sans Kernel ni serveur — et ce qui garantit qu'elle ne peut
+ * rien inventer : tout ce qu'elle rend vient de ce qu'on lui a passé.
+ *
+ * ## Pourquoi les commandes portent `npx`
+ *
+ * Le binaire `nodefony` vit dans les `node_modules` de l'application : `nodefony`
+ * nu rend 127. Mesuré sur agent réel — il recopie la FORME qu'on lui montre, pas
+ * la règle écrite à côté. Une seule commande nue suffit à l'envoyer dans le mur
+ * au premier geste.
+ *
+ * @param input - l'état de l'application (injecté, jamais lu ici).
+ * @returns la carte, prête à rendre en texte ({@link renderCard}) ou en JSON.
+ */
+export declare function buildCard(input: ICardInput): ICard;
+/**
+ * Rend la carte pour un HUMAIN (ou un agent qui lit un terminal).
+ *
+ * PURE : elle ne touche ni au kernel ni au système de fichiers, donc elle
+ * s'éprouve seule. Écrite sur `stdout` par ses appelants plutôt que par le
+ * journal — une carte de visite n'est pas un événement de log, et le préfixe
+ * horodaté rendrait le copier-coller inutilisable.
+ *
+ * La ligne des modules DIT sa provenance : « chargés » n'est vrai que si
+ * l'application tournait au moment de la lecture. Sans cette mention, une carte
+ * lue à froid ferait croire que le gating `policy`/`when` a déjà eu lieu.
+ *
+ * @param card - la carte composée par {@link buildCard}.
+ * @returns le texte complet, prêt à écrire tel quel.
+ */
+export declare function renderCard(card: ICard): string;

package/dist/types/cli/completion.d.ts

@@ -0,0 +1,154 @@
+import type { Command as CommanderCommand } from "commander";
+/**
+ * Complétion shell du CLI Nodefony (`nodefony completion <shell>` + requête
+ * `nodefony __complete -- <mots>`).
+ *
+ * Contrainte d'archi : les commandes de MODULE ne sont connues qu'après le chargement
+ * du manifeste `config.modules` (`onPreRegister`) — booter le kernel à chaque TAB est
+ * exclu (secondes). Solution : un **manifest cache** (`node_modules/.cache/nodefony/
+ * cli-manifest.json`) écrit à chaque boot DEV (commandes built-in + modules, extraites
+ * de commander), lu par le fast-path standalone `__complete` en millisecondes. Hors
+ * projet / manifest absent → fallback built-ins (fourni par l'appelant, sans boot).
+ *
+ * Pur outillage process (même famille que status/stop) : AUCUN boot kernel côté
+ * requête ; `__complete` sort TOUJOURS en `EX_OK` (une complétion qui échoue doit
+ * rendre une liste vide, jamais polluer le TAB du shell).
+ */
+/** Une commande du manifest de complétion. */
+export interface ICliManifestCommand {
+    name: string;
+    aliases: string[];
+    description: string;
+    /** Flags candidats (`-w`, `--workers`, …) — sans leurs placeholders `<arg>`. */
+    options: string[];
+    /**
+     * Choix des arguments POSITIONNELS, par position (`args[0]` = 1er argument).
+     * Rempli depuis les `.choices()` déclarés à commander (ex. `create <type>` →
+     * `[["app"]]`) ; `[]` = argument libre (rien à proposer). Absent sur les
+     * manifests cache antérieurs → traité comme libre (compat lecture).
+     */
+    args?: string[][];
+    /**
+     * Le groupe d'INTENTION déclaré par la commande (cf `HELP_GROUPS`).
+     *
+     * Porté par le manifeste parce que ses deux autres lecteurs en ont besoin
+     * et ne peuvent pas le retrouver : le menu interactif s'ouvre à `onStart`,
+     * trop tôt pour connaître les commandes de module, et la page de manuel se
+     * rend hors de tout boot. Sans lui, les deux rangeaient tout un pan du CLI
+     * dans un fourre-tout, là où l'aide le classe.
+     */
+    group?: string;
+    /**
+     * Les flags qui attendent une VALEUR, avec ce qu'on peut proposer.
+     *
+     * Un tableau vide dit « une valeur est attendue, mais je ne sais pas
+     * laquelle » — et c'est déjà l'essentiel : sans cela, le TAB proposait les
+     * AUTRES options juste après `--env`, ce qui laissait croire qu'aucun
+     * argument n'était requis. Absent des manifests antérieurs (compat lecture).
+     */
+    optionValues?: Record<string, string[]>;
+}
+/** Manifest de complétion (cache par projet). */
+export interface ICliManifest {
+    version: string;
+    /** Flags globaux du programme (`-d`, `--debug`, …). */
+    globalOptions: string[];
+    commands: ICliManifestCommand[];
+}
+/** Chemin du manifest cache — même dossier que le pidfile superviseur. */
+export declare function cliManifestFile(cwd: string): string;
+/** Extrait les flags candidats d'une chaîne commander (`"-w, --workers <number>"`). */
+export declare function extractFlags(flags: string): string[];
+/**
+ * Construit le manifest depuis l'état COURANT de commander — appelé après que les
+ * modules ont posé leurs commandes (`onPreRegister`) pour un manifest complet, ou
+ * avec les seuls built-ins pour le fallback sans boot.
+ */
+export declare function buildCliManifest(commander: CommanderCommand, version: string): ICliManifest;
+/**
+ * Écrit le manifest cache (mkdir -p + write async). Best-effort : l'appelant décide
+ * du fire-and-forget — un échec (FS read-only, pas de node_modules) ne doit JAMAIS
+ * impacter le boot.
+ */
+export declare function writeCliManifest(commander: CommanderCommand, cwd: string, version: string): Promise<void>;
+/** Lit le manifest cache — `null` si absent ou corrompu (jamais de throw). */
+export declare function readCliManifest(cwd: string): ICliManifest | null;
+/**
+ * Calcule les candidats de complétion pour les mots tapés.
+ *
+ * Protocole : `words` = tous les mots APRÈS le nom du binaire, dernier mot inclus
+ * même vide (les scripts shell le transmettent tel quel). Le DERNIER mot est celui
+ * en cours de frappe → la sélection de commande ne regarde que les mots VALIDÉS
+ * (`slice(0, -1)`), et le shell filtre les candidats par le préfixe courant.
+ *
+ * - commande déjà validée → les CHOIX de l'argument positionnel en cours (s'il
+ *   en déclare, ex. `create` → `app`) + ses options + les options globales ;
+ * - sinon → noms + alias de toutes les commandes.
+ */
+export declare function computeCompletions(manifest: ICliManifest, words: string[]): string[];
+/** Shells supportés par `nodefony completion <shell>`. */
+export declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish"];
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+/**
+ * Rend le script de complétion à sourcer pour un shell. Le script est STABLE (il
+ * délègue tout au binaire via `__complete`) : les commandes de module apparaissent
+ * sans jamais regénérer le script — seule la donnée (manifest cache) bouge.
+ */
+export declare function renderCompletionScript(shell: CompletionShell): string;
+/** Détecte le shell courant depuis `$SHELL` (fallback interactif du sous-commande nu). */
+export declare function detectShell(): CompletionShell | null;
+/** Cibles d'installation d'un shell : fichier script + rc à marquer (`null` = aucun). */
+export declare function completionInstallTargets(shell: CompletionShell, home: string): {
+    scriptFile: string;
+    rcFile: string | null;
+};
+/** Retire le bloc marqué (avec ses marqueurs) d'un contenu rc — no-op si absent. */
+export declare function removeBlock(content: string): string;
+/** Insère (ou remplace) le bloc marqué sourçant `scriptFile` — idempotent. */
+export declare function upsertBlock(content: string, scriptFile: string): string;
+/**
+ * Installe la complétion pour un shell : écrit le script (mkdir -p) et, si le shell
+ * en a besoin, upsert le bloc marqué dans son rc (créé s'il n'existe pas).
+ *
+ * @returns les chemins touchés (pour le rapport utilisateur).
+ */
+export declare function installCompletion(shell: CompletionShell, home: string): {
+    scriptFile: string;
+    rcFile: string | null;
+};
+/** Désinstalle : retire le bloc du rc et supprime le fichier script. */
+export declare function uninstallCompletion(shell: CompletionShell, home: string): {
+    scriptFile: string;
+    rcFile: string | null;
+};
+/**
+ * Fast-path `nodefony completion [install|uninstall] [shell]` — imprime le script,
+ * ou l'installe/désinstalle dans le rc du shell (bloc marqué idempotent).
+ *
+ * @returns exit code (`EX_OK`, ou `EX_USAGE` si shell inconnu et indétectable).
+ */
+export declare function runCompletionCommand(argv: string[]): number;
+/**
+ * Fusionne les commandes du **code courant** (built-ins, construits en mémoire) avec
+ * celles que seul le manifest cache connaît (les commandes de MODULE, posées à
+ * `onPreRegister` — impossible de les lister sans booter).
+ *
+ * Pourquoi cette asymétrie : le cache est écrit au boot dev et n'est jamais invalidé
+ * (sa clé est la version du paquet, identique d'un build à l'autre en développement).
+ * S'il faisait autorité sur les built-ins, la complétion resterait figée sur l'état du
+ * dernier boot — un `create` enrichi d'un nouveau type ne le proposerait jamais (vécu).
+ * Le binaire, lui, est toujours à jour par construction : il EST le code courant.
+ *
+ * Un module retiré peut donc survivre dans la liste jusqu'au prochain boot dev — un
+ * candidat en trop au TAB, sans conséquence, corrigé au boot suivant.
+ */
+export declare function mergeManifests(builtins: ICliManifest, cached: ICliManifest | null): ICliManifest;
+/**
+ * Fast-path `nodefony __complete -- <mots>` — imprime un candidat par ligne.
+ *
+ * Source : built-ins du binaire courant (`builtins`, construits en mémoire par le
+ * CliKernel, sans boot) + commandes de module lues dans le manifest cache. Sort
+ * TOUJOURS `EX_OK` : le pire résultat d'une complétion est une liste vide, jamais une
+ * erreur dans le TAB.
+ */
+export declare function runCompleteQuery(argv: string[], builtins: () => ICliManifest): number;

package/dist/types/cli/create.d.ts

@@ -0,0 +1,177 @@
+import { SysExit } from "./sysexits.js";
+import { type TScaffoldAnswers } from "./scaffold/engine.js";
+import { type IScaffoldChange } from "./scaffold/writer.js";
+import { type IAgentTarget } from "./agentTargets.js";
+/**
+ * Adaptateur CLI du scaffold `nodefony create <type> [name]` — front n°1 et n°2
+ * du moteur (`scaffold/engine.ts`, partagé avec Studio) :
+ *
+ *   - **CLI rapide** : tout est dit en flags (`create app x --preset minimal
+ *     --frontend react --link`) → zéro question, scriptable.
+ *   - **CLI interactif** (défaut en TTY) : les questions de la spec NON couvertes
+ *     par les flags sont posées en readline natif, récap + confirmation.
+ *   - Hors TTY (CI, spawn de test) : les défauts de la spec s'appliquent —
+ *     comportement stable pour les scripts, `--yes` force la même chose en TTY.
+ *
+ * Pur outillage standalone (même famille que status/stop/completion) : AUCUN
+ * boot kernel — cas nominal HORS projet : `npx nodefony create app mon-app`.
+ */
+/** Types de scaffold disponibles. */
+export declare const CREATE_TYPES: readonly ["app", "module", "controller", "service", "front", "entity", "command"];
+export type TCreateType = (typeof CREATE_TYPES)[number];
+export interface ICreateRequest {
+    /** `true` si l'on veut seulement la page d'aide. */
+    help: boolean;
+    /** `undefined` seulement avec `--describe-json` (décrire TOUS les types). */
+    type?: TCreateType;
+    /** Réponses partielles issues des flags (le reste : interactif ou défauts). */
+    answers: TScaffoldAnswers;
+    /** Dossier cible (défaut : `./<name>` une fois le nom connu). */
+    dir?: string;
+    force: boolean;
+    /** `--yes` : accepter les défauts sans poser de question (même en TTY). */
+    yes: boolean;
+    /** `--no-install` : ne pas lancer `npm install` après la génération. */
+    install: boolean;
+    /** `--no-git` : ne pas faire `git init` + first commit après la génération. */
+    git: boolean;
+    /** `--dry-run` : montrer ce qui serait écrit, ne rien écrire. */
+    dryRun: boolean;
+    /** `--describe-json` : décrire le scaffold en JSON et sortir (mode machine). */
+    describeJson: boolean;
+    /** `--answers-json <fichier|->` : source des réponses (fichier, ou `-` = stdin). */
+    answersJson?: string;
+}
+/**
+ * Parse l'argv complet du process après le mot `create`. Ne valide QUE la forme
+ * des flags — les valeurs (nom, preset…) sont jugées par la spec du moteur.
+ *
+ * @returns la requête, ou un message d'usage si invalide
+ */
+export declare function parseCreateArgv(argv: string[]): ICreateRequest | {
+    error: string;
+};
+/**
+ * Rend le plan d'un `--dry-run` : ce qui serait créé, et surtout le DIFF de ce
+ * qui serait réécrit.
+ *
+ * Les créations sont listées à plat (leur contenu n'écrase rien, l'inventaire
+ * suffit) ; les réécritures sont les seules opérations qui touchent au travail
+ * existant — c'est là que la simulation a une valeur, donc c'est là qu'on
+ * dépense de la place.
+ */
+export declare function renderDryRun(changes: IScaffoldChange[], notes?: string[]): string;
+/**
+ * Le code de sortie de `create`, décidé à part — parce qu'il se teste.
+ *
+ * Le défaut qu'il ferme : la commande affichait « npm run build a échoué »
+ * puis rendait **0**. L'application existait bien, c'est vrai — mais elle
+ * n'était PAS utilisable, et aucun automate ne pouvait le savoir : ni une
+ * chaîne d'intégration continue, ni un banc, ni un agent qui enchaîne. C'est
+ * exactement ce qui a laissé le front d'une application générée ne pas se
+ * bâtir sans que rien ne tombe, le message se noyant dans la sortie.
+ *
+ * La règle : **ce qui est ÉCRIT reste écrit** (les fichiers ne sont pas
+ * retirés, les prochaines étapes sont affichées, `npm run build` y figure),
+ * mais le code de sortie DIT qu'il reste quelque chose à faire.
+ *
+ * L'installation sautée (`--no-install`) ne compte pas comme un échec : rien
+ * n'a été tenté, et la commande l'annonce dans ses prochaines étapes.
+ *
+ * 🔴 **Sautée et ratée sont deux états, pas un booléen.** Les deux étapes
+ * étaient rendues par `boolean`, où `false` disait à la fois « on ne l'a pas
+ * lancée » et « on l'a lancée et elle a échoué ». Une installation ratée
+ * tombait donc du bon côté : code 0. Or elle emporte TOUT ce qui la suit — le
+ * formatage, le build, la migration initiale — et l'utilisateur reçoit une
+ * application qui ne peut pas démarrer, sous un succès. Constaté sur le décor
+ * du banc de découvrabilité, dont l'application témoin n'avait jamais eu de
+ * `dist/` ni de `migrations/` : le manifeste pointait encore vers un registre
+ * où aucun paquet `@nodefony/*` n'est publié.
+ *
+ * @param install - l'installation des dépendances : sautée, réussie, échouée.
+ * @param build - `npm run build` : sauté (l'install n'a pas eu lieu), réussi,
+ *   échoué.
+ * @returns `OK`, ou `SOFTWARE` dès qu'une étape TENTÉE a échoué.
+ */
+export declare function createExitCode(install: CreateStepOutcome, build: CreateStepOutcome): SysExit;
+/**
+ * Ce qu'une étape de post-génération a fait : rien, ou réussi, ou échoué.
+ *
+ * Trois états parce que deux ne suffisent pas — cf {@link createExitCode}.
+ */
+export type CreateStepOutcome = "skipped" | "succeeded" | "failed";
+/**
+ * Un type manquant se DEMANDE-t-il, ou l'usage est-il la bonne réponse ? PURE.
+ *
+ * Trois conditions, et chacune dit quelque chose de différent :
+ * - l'erreur est bien « aucun type » — un type FAUTIF (`create ap`) se corrige,
+ *   il ne se remplace pas par une question qui masquerait la faute de frappe ;
+ * - un terminal répond en face — sans lui, une question est un blocage muet ;
+ * - `--yes` n'a pas été demandé : il dit « ne me demande rien », et le
+ *   respecter vaut mieux que de rendre service.
+ *
+ * @param error - le motif rendu par l'analyse de la ligne de commande.
+ * @param ctx - terminal disponible, et présence de `--yes`.
+ */
+export declare function shouldAskForType(error: string, ctx: {
+    isTTY: boolean;
+    yes: boolean;
+}): boolean;
+/**
+ * Décide si `create app` CÂBLE la porte MCP chez les agents choisis. PURE.
+ *
+ * Deux refus, deux raisons qui n'ont rien à voir :
+ * - **aucun agent choisi** — et c'est le DÉFAUT (la question de la spec part
+ *   vide). Déclarer une porte chez un agent ÉCRIT dans la configuration d'un
+ *   autre outil : rien de coché, rien d'écrit, en terminal comme ailleurs.
+ *   C'est le choix explicite qui autorise, pas la présence d'un humain — ce
+ *   qui rend le geste servable par Studio, qui n'est pas un terminal.
+ * - **app ni installée ni construite** (`--no-install`, ou une install en
+ *   échec) : `ai:mcp` enchaîne sur l'émission du jeton, qui DÉMARRE le kernel.
+ *   Sans `node_modules` ni `dist`, on provoquerait soi-même l'échec — le geste
+ *   est alors NOMMÉ plutôt que joué.
+ *
+ * @param ctx - nombre d'agents choisis, et état réel de l'app générée.
+ * @returns la proposition, ou le motif du refus (affiché tel quel).
+ */
+export declare function mcpWiringPlan(ctx: {
+    chosen: number;
+    installed: boolean;
+    built: boolean;
+}): {
+    propose: true;
+} | {
+    propose: false;
+    pattern: string;
+};
+/**
+ * Traduit le choix d'agents de développement en appel `ai:mcp` — PURE.
+ *
+ * ⭐ **Ce qui se choisit, c'est l'AGENT ; la porte MCP vient AVEC.** Demander
+ * « veux-tu déclarer une porte MCP ? » posait la question à l'envers : personne
+ * n'installe un protocole, on se sert d'un assistant — et c'est lui qui a besoin
+ * de la porte. Une seule question, dans les mots de celui qui répond.
+ *
+ * Deux familles d'agents, une seule liste : ceux qui se déclarent par LEUR CLI
+ * (`--agent <clés>`) et ceux qui lisent le `.mcp.json` du projet — pour ces
+ * derniers, écrire le fichier EST la déclaration, d'où `none` plutôt que rien :
+ * `--agent none` dit « n'appelle aucune CLI », pas « ne fais rien ».
+ *
+ * `--auth` : l'en-tête porte `${NF_MCP_TOKEN}`, jamais le jeton lui-même. Une
+ * app neuve naît avec sa porte fermée ; l'ouvrir sans authentification serait un
+ * défaut par défaut.
+ *
+ * @param chosen - clés cochées par l'utilisateur.
+ * @param detected - agents présents sur ce poste (source unique `AGENT_TARGETS`).
+ * @param dest - racine de l'app générée.
+ * @returns l'argv à passer à `ai:mcp`, ou `null` quand aucun agent n'est choisi
+ *   — coder seul est un choix, et rien ne doit alors être écrit.
+ */
+export declare function argvMcpWiring(chosen: readonly string[], detected: readonly IAgentTarget[], dest: string): string[] | null;
+/**
+ * Commande `nodefony create` — orchestre l'adaptateur : parse argv, complète en
+ * interactif si TTY, délègue au moteur, rend le récap.
+ *
+ * @returns exit code sémantique (`OK`, `USAGE`, `CANTCREAT`, `SOFTWARE`)
+ */
+export declare function runCreateCommand(argv: string[]): Promise<number>;

package/dist/types/cli/env.d.ts

@@ -0,0 +1,103 @@
+import { type NamedEnvVarMeta } from "../config/defineEnv.js";
+import { type IEnvReport } from "./envReport.js";
+/**
+ * `nodefony env [--json]` — dit TOUT de l'environnement d'une application :
+ * quels fichiers sont lus et dans quel ordre, quelles variables sont déclarées,
+ * quelle valeur est effective, d'OÙ elle vient, et ce qui est ignoré.
+ *
+ * Pourquoi une commande à part, et non un sujet d'`inspect` : `inspect`
+ * interroge une application BOOTÉE (routes, services, configuration résolue).
+ * Or on cherche une variable d'environnement précisément quand l'application
+ * NE démarre pas — variable requise manquante, valeur qui ne prend pas, fichier
+ * qu'on croit lu. Cette commande est donc standalone, comme `status` et `check` :
+ * elle ne lit que des fichiers, et répond même sur une application cassée.
+ *
+ * Ce qu'elle répare : la cascade `loadEnv` est correcte mais INVISIBLE — elle
+ * n'était écrite que dans un commentaire du framework. Un agent, comme un
+ * humain, ne pouvait que la deviner, et deviner produit toujours la même erreur :
+ * poser la variable dans un fichier de rang inférieur à celui qui la définit
+ * déjà, puis conclure que « ça ne marche pas ».
+ */
+/** Ce que la ligne de commande demande. */
+interface IEnvRequest {
+    json: boolean;
+    /** `--example` : générer/vérifier `.env.example` au lieu du rapport. */
+    example: boolean;
+    /** `--check` : ne rien écrire, échouer si `.env.example` diverge. */
+    check: boolean;
+    /** Racine de recherche (défaut : le cwd). */
+    cwd: string;
+    /**
+     * `--env <e>` : évaluer les exigences sous CET environnement plutôt que celui
+     * d'ici. Les valeurs restent celles de la machine — on ne simule pas un
+     * déploiement, on demande « qu'est-ce qui manquera là-bas ? ».
+     */
+    targetEnv: string | null;
+    /** `true` si l'on veut seulement la page d'aide. */
+    help: boolean;
+}
+/** Parse l'argv après le mot `env`. */
+export declare function parseEnvArgv(argv: string[]): IEnvRequest | {
+    error: string;
+};
+/**
+ * Commande `nodefony env` — orchestre : résout le projet, lit la cascade et le
+ * catalogue, délègue le calcul au module pur, rend.
+ *
+ * @returns exit code sémantique (`OK`, `USAGE`, `CONFIG` si une requise manque)
+ */
+/**
+ * Compose le rapport d'environnement d'un projet — la MÊME donnée pour tous ses
+ * lecteurs.
+ *
+ * Extraite de {@link runEnvCommand} pour que `nodefony doctor` puisse dire « il
+ * manque une variable REQUISE » sans réimplémenter la cascade : deux définitions
+ * de « quelle valeur est effective » divergeraient, et chacune passerait ses
+ * propres tests. Le second lecteur ne rend d'ailleurs pas le rapport, il n'en
+ * lit que les manquantes — raison de plus pour qu'il ne le RECALCULE pas.
+ *
+ * @param projectRoot - racine de l'application, ou `null` hors projet (le
+ *   catalogue des variables déclarées est alors inconnu : il se lit dans le
+ *   `dist/` de l'application).
+ * @param cwd - dossier de départ, utilisé comme racine hors projet.
+ * @returns le rapport complet (fichiers lus, variables, provenance, notes).
+ */
+export declare function buildProjectEnvReport(projectRoot: string | null, cwd: string, targetEnv?: string | null): Promise<IEnvReport>;
+/**
+ * Compose le contenu de `.env.example` d'une application — PUR.
+ *
+ * @param catalog - catalogue des variables (via `getEnvCatalog`).
+ * @returns le texte complet du fichier.
+ */
+export declare function composeEnvExample(catalog: readonly NamedEnvVarMeta[], customHeader?: string | null): string;
+/**
+ * L'en-tête curé du projet, s'il en a un — convention `.env.example.head` à la
+ * racine (versionné). Il PRIME sur l'en-tête générique : un projet qui a écrit
+ * son onboarding le garde, le corps reste dérivé du catalogue dans tous les
+ * cas. C'est ce qui a permis au dépôt self-hosted de MIGRER de son script
+ * `gen-env-example.ts` vers cette commande sans perdre sa prose.
+ *
+ * @param projectRoot - racine de l'application.
+ * @returns le contenu du fichier, ou `null` s'il n'existe pas.
+ */
+export declare function readExampleHeader(projectRoot: string): string | null;
+/**
+ * Applique (ou vérifie) le contenu sur le `.env.example` du projet — I/O seul,
+ * la composition appartient à {@link composeEnvExample}.
+ *
+ * Idempotence FORTE : un fichier déjà identique n'est pas réécrit — même
+ * doctrine qu'`ai:sync`, un outil qui salit l'horodatage est un outil qu'on
+ * hésite à lancer.
+ *
+ * @param projectRoot - racine de l'application.
+ * @param content - contenu attendu, composé en amont.
+ * @param check - `true` : ne rien écrire, seulement comparer.
+ * @returns `synced` : le fichier correspond (déjà, ou après écriture) ;
+ *   `wrote` : une écriture a eu lieu.
+ */
+export declare function applyEnvExample(projectRoot: string, content: string, check: boolean): {
+    synced: boolean;
+    wrote: boolean;
+};
+export declare function runEnvCommand(argv: string[]): Promise<number>;
+export {};