nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,153 @@
+import { type NamedEnvVarMeta } from "../config/defineEnv.js";
+/**
+ * Calcul PUR du rapport d'environnement — aucune I/O, aucun `process.env` lu ici.
+ *
+ * Pourquoi ce module existe séparé de la commande : la question « d'où vient
+ * cette valeur ? » ne se répond bien qu'en confrontant la cascade des fichiers à
+ * l'environnement réel, et cette confrontation doit être TESTABLE sans écrire un
+ * seul fichier sur disque. L'adaptateur (`cli/env.ts`) lit ; ce module conclut.
+ *
+ * Le calcul ne demande AUCUNE instrumentation de `loadEnv` : au moment où la
+ * commande s'exécute, `process.env` est déjà peuplé et l'on a perdu la trace de
+ * qui a posé quoi. On la reconstruit — pour chaque variable, le premier fichier
+ * de la cascade qui la définit avec la valeur effective EST son origine ; si
+ * aucun ne la définit ainsi, elle vient du shell, qui gagne toujours.
+ */
+/** Un niveau de la cascade — `process.env` ou un fichier `.env*`. */
+export interface IEnvLevel {
+    /** 1 = le plus prioritaire. */
+    rank: number;
+    /** `process.env` ou le nom du fichier (`.env.local`…). */
+    source: string;
+    /** Le niveau existe-t-il (fichier présent) ? */
+    exists: boolean;
+    /** Nombre de variables qu'il définit. */
+    count: number;
+    /** Pourquoi ce niveau ne s'applique pas (ex. environnement de déploiement non défini). */
+    skipped?: string;
+}
+/** Une variable, telle que le rapport la restitue. */
+export interface IEnvVarReport {
+    name: string;
+    /** Nature déclarée, ou `unknown` pour une variable présente hors catalogue. */
+    kind: string;
+    /** Déclarée par `env.ts` (catalogue `defineEnv`) ? */
+    declared: boolean;
+    /**
+     * Doit être présente DANS L'ENVIRONNEMENT ÉVALUÉ.
+     *
+     * Pas seulement « ni défaut ni `optional` » : une variable peut n'être requise
+     * qu'en production (`requiredIn`), et le rapport se lit alors sous l'angle de
+     * l'environnement visé — celui du poste par défaut, celui de `--env` sinon.
+     */
+    required: boolean;
+    /**
+     * Les environnements où sa déclaration l'exige — vide si elle l'est partout
+     * ou nulle part. C'est ce qui permet de dire « requise en production » sans
+     * le déduire, à tort, du seul fait qu'elle manque ici.
+     */
+    requiredIn?: readonly string[];
+    /** Nom sensible → la valeur n'est jamais rendue. */
+    secret: boolean;
+    description?: string;
+    /** Valeur effective, masquée si `secret`. `null` = absente. */
+    value: string | null;
+    /** D'où vient la valeur effective. `null` si absente. */
+    origin: string | null;
+    /** Défaut déclaré (si la variable est absente, c'est lui qui s'appliquera). */
+    default?: unknown;
+    /** Valeurs permises (énumération). */
+    values?: readonly string[];
+    /** Requise ET absente : l'application ne démarrera pas. */
+    missing: boolean;
+    /** Niveaux qui la définissent mais sont MASQUÉS par l'origine gagnante. */
+    shadowed: {
+        source: string;
+        value: string;
+    }[];
+}
+/** Une surcharge directe de configuration de module (`NF__<MODULE>__<CHEMIN>`). */
+export interface IEnvOverrideReport {
+    envKey: string;
+    module: string;
+    path: string[];
+    /** Masquée si le chemin porte un secret. */
+    value: string;
+    origin: string | null;
+}
+/** Rapport complet — la forme rendue par `--json`. */
+export interface IEnvReport {
+    /** Mode runtime (`NODE_ENV`). */
+    runtimeEnv: string;
+    /** Environnement de déploiement (`APP_ENV`/`NF_ENV`), s'il diffère. */
+    appEnv: string | null;
+    /**
+     * L'environnement sous lequel les exigences sont ÉVALUÉES, quand ce n'est pas
+     * celui d'ici — ce que demande `--env production` depuis un poste de
+     * développement. `null` = le rapport parle de la machine courante.
+     */
+    targetEnv: string | null;
+    /**
+     * Les étiquettes effectivement confrontées à `requiredIn` (mode d'exécution,
+     * et environnement de déploiement s'il diffère). Rendues parce qu'un verdict
+     * d'exigence est incompréhensible sans savoir sur quoi il a porté.
+     */
+    stages: readonly string[];
+    /** La cascade, du plus fort au plus faible. */
+    levels: IEnvLevel[];
+    /** Variables déclarées par l'application. */
+    vars: IEnvVarReport[];
+    /** Surcharges `NF__…` de configuration de module. */
+    overrides: IEnvOverrideReport[];
+    /** Variables présentes mais inconnues du catalogue (fautes de frappe probables). */
+    unknown: {
+        name: string;
+        origin: string | null;
+        suggestion?: string;
+    }[];
+    /**
+     * Variables posées par le FRAMEWORK lui-même (lanceur, mode de démarrage,
+     * grappe, jeton MCP). Elles ne relèvent pas de la configuration de
+     * l'application : les compter parmi les inconnues accusait l'utilisateur
+     * d'une faute de frappe qu'il n'avait pas commise.
+     */
+    reserved: {
+        name: string;
+        origin: string | null;
+        role: string;
+    }[];
+    /** Le catalogue de l'application a-t-il pu être lu ? */
+    catalogAvailable: boolean;
+    /** Ce que le rapport n'a pas pu établir, et pourquoi. */
+    notes: string[];
+}
+/** Un niveau de fichier tel que l'adaptateur le fournit (`vars: null` = absent). */
+export interface IEnvFileInput {
+    source: string;
+    vars: Record<string, string> | null;
+    skipped?: string;
+}
+/**
+ * Construit le rapport d'environnement.
+ *
+ * @param input.runtimeEnv - mode runtime (`NODE_ENV`).
+ * @param input.appEnv - environnement de déploiement, s'il diffère du mode.
+ * @param input.processEnv - l'environnement effectif, cascade déjà appliquée.
+ * @param input.files - les niveaux de fichiers, du PLUS fort au PLUS faible.
+ * @param input.catalog - les variables déclarées par l'app, ou `null` si illisible.
+ * @returns le rapport, sérialisable tel quel.
+ */
+export declare function buildEnvReport(input: {
+    runtimeEnv: string;
+    appEnv?: string | null;
+    processEnv: Record<string, string | undefined>;
+    files: IEnvFileInput[];
+    catalog: readonly NamedEnvVarMeta[] | null;
+    /**
+     * Environnement à ÉVALUER, s'il n'est pas celui d'ici — ce que demande
+     * `nodefony doctor --env production` depuis un poste de développement. Les
+     * valeurs restent celles de la machine : on ne simule pas un déploiement, on
+     * confronte l'environnement PRÉSENT aux exigences de celui qu'on VISE.
+     */
+    targetEnv?: string | null;
+}): IEnvReport;

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

@@ -0,0 +1,54 @@
+import path from "node:path";
+/**
+ * Lancer un exécutable de l'écosystème npm, sur les trois systèmes.
+ *
+ * ## Le défaut, et pourquoi il ne se voit jamais sur un poste de développement
+ *
+ * Sous Windows, `npm`, `npx`, `prettier` et compagnie ne sont pas des exécutables :
+ * ce sont des scripts `.cmd`. Depuis le correctif de CVE-2024-27980, Node REFUSE
+ * d'exécuter un `.cmd` sans `shell: true` — et il ne le dit pas en ces termes : il
+ * rend `spawnSync npm ENOENT`, qui se lit « npm n'est pas installé ». Sur une
+ * machine où npm vient de tourner, c'est un message qui envoie chercher très loin
+ * de la cause.
+ *
+ * Ce que cela coûtait EN PRODUIT, et pas seulement en outillage : `nodefony create
+ * module` installe le workspace npm qu'il vient d'écrire — c'est ce `npm install`
+ * qui crée le lien sans lequel le Kernel ne peut pas importer le module par son
+ * nom. Sous Windows il ne s'exécutait pas ; le module était écrit, construit,
+ * déclaré au manifeste — et introuvable au boot. L'application démarrait sans lui
+ * (fail-soft) et TOUTES ses routes rendaient 404.
+ *
+ * ## Une seule implémentation, dans le FRAMEWORK
+ *
+ * La règle a d'abord été écrite dans le banc qui mesure le framework, jamais dans
+ * le framework lui-même — si bien que l'outil de mesure était portable et que le
+ * produit ne l'était pas. C'est l'utilisateur qui subit la règle : c'est donc ici
+ * qu'elle vit, et le banc l'importe.
+ */
+/**
+ * Faut-il passer par le shell pour lancer cette commande ?
+ *
+ * Vrai sous Windows dans DEUX cas, et une première version n'en voyait qu'un :
+ *
+ *  1. la commande est cherchée dans le `PATH` (`npm`, `npx`) — elle s'y résout en
+ *     `.cmd` ;
+ *  2. la commande est un chemin ABSOLU qui désigne un script batch
+ *     (`…\node_modules\.bin\oxlint.cmd`).
+ *
+ * « Absolu donc exécutable réel » est une inférence, pas un constat : ce qui empêche
+ * Node de lancer la chose n'est pas l'endroit où elle est, c'est ce qu'elle EST.
+ *
+ * Ailleurs que sous Windows, `shell: true` est à éviter : il rouvre l'interprétation
+ * des métacaractères sur des arguments qui viennent parfois d'un décor.
+ *
+ * La plateforme et la grammaire de chemins sont INJECTÉES, et ce n'est pas de la
+ * coquetterie : une fonction qui lit `process.platform` ne peut être éprouvée que
+ * sur la plateforme qu'elle décrit — c'est-à-dire jamais, sur les postes de ce
+ * projet. Injectées, les deux branches se vérifient partout.
+ *
+ * @param command - ce qu'on s'apprête à lancer.
+ * @param plateforme - le système, injectable pour l'épreuve.
+ * @param grammar - `path.win32` ou `path.posix`, idem.
+ * @returns la valeur à donner à l'option `shell` de `spawn`/`spawnSync`.
+ */
+export declare function needsShell(command: string, plateforme?: NodeJS.Platform, grammar?: Pick<typeof path, "isAbsolute">): boolean;

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

@@ -0,0 +1,48 @@
+import { type IGitHooksPlan } from "./gitHooksReport.js";
+/**
+ * Analyse les arguments de `git:hooks`.
+ *
+ * @param argv - `process.argv` complet.
+ * @returns les options, ou une erreur d'usage.
+ */
+export declare function parseGitHooksArgv(argv: string[]): {
+    cwd: string;
+    json: boolean;
+    dryRun: boolean;
+    help: boolean;
+} | {
+    error: string;
+};
+/**
+ * Pose les hooks natifs dans un projet, et rend le plan de ce qui a été fait.
+ *
+ * Le geste ENTIER — lire, décider, écrire, configurer — en un exemplaire, pour
+ * ses appelants présents et futurs (la commande ; un jour `create app
+ * --git-hooks`). Tout refus (hook étranger, `core.hooksPath` géré autrement)
+ * interdit TOUT le geste : pas d'état à moitié posé.
+ *
+ * ⚠️ `core.hooksPath` RELATIF se résout depuis le TOPLEVEL du dépôt git, pas
+ * depuis l'application. Quand l'application n'est pas le toplevel (monorepo),
+ * la valeur posée est le chemin du dossier de hooks VU DU toplevel — calculée
+ * ici, écrite en `/` (elle voyage dans la config du clone).
+ *
+ * @param projectRoot - racine de l'application, DÉJÀ résolue.
+ * @param dryRun - `true` pour calculer sans rien écrire ni configurer.
+ * @returns le plan, ou `null` si `projectRoot` n'est dans aucun dépôt git.
+ */
+export declare function installGitHooks(projectRoot: string, dryRun?: boolean): IGitHooksPlan | null;
+/**
+ * Commande `nodefony git:hooks` — hooks git natifs (`core.hooksPath`), zéro
+ * dépendance.
+ *
+ * Standalone (0 boot) : elle écrit deux fichiers et une clé de config, et doit
+ * répondre dans un terminal qui n'a pas posé `NODE_ENV` — même famille que
+ * `ai:sync` et `ai:mcp`, mêmes raisons. Et comme eux, AUCUN `postinstall` ne
+ * l'appelle : la pose de hooks est un choix, pas un effet de bord d'un
+ * `npm install`.
+ *
+ * @param argv - `process.argv` complet.
+ * @returns exit code sémantique (`OK`, `USAGE`, `NOINPUT` hors projet,
+ *   `UNAVAILABLE` hors dépôt git, `CANTCREAT` sur refus d'écrasement).
+ */
+export declare function runGitHooksCommand(argv: string[]): number;

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

@@ -0,0 +1,101 @@
+/**
+ * Composition PURE de `nodefony git:hooks` — hooks git natifs, zéro dépendance.
+ *
+ * Reçoit un état déjà lu (contenu actuel des hooks, valeur de `core.hooksPath`)
+ * et conclut : que poser, que laisser, que REFUSER. Aucune lecture de disque,
+ * aucun `git config` — même séparation que `aiSyncReport.ts` / `aiSync.ts`.
+ *
+ * ## Pourquoi natif, et pas husky
+ *
+ * Depuis sa v9, husky n'est plus qu'un habillage de `git config core.hooksPath` :
+ * la fonctionnalité est dans git lui-même. Une dépendance + un script `prepare`
+ * pour ce que deux fichiers sh et une ligne de config font déjà, c'est une
+ * surface en trop — et un `postinstall` est exactement ce que `ai:sync` a
+ * refusé (`--ignore-scripts` courant, vecteur d'attaque connu). La pose est un
+ * GESTE EXPLICITE : cette commande, jamais un script d'installation.
+ *
+ * ## Pourquoi les hooks générés sont LÉGERS
+ *
+ * Le filet complet appartient à l'intégration continue — un hook local bloquant
+ * est un doublon qui ralentit chaque commit et se contourne d'un `--no-verify`.
+ * Qui opte pour les hooks reçoit donc le strict utile : typecheck + lint au
+ * commit (rapide), `verify` complet au push (le dernier rempart avant de
+ * partager).
+ */
+/** Dossier des hooks, relatif à la racine de l'application, écrit en `/`. */
+export declare const GIT_HOOKS_DIR = ".githooks";
+/**
+ * Marqueur d'APPARTENANCE, présent dans chaque hook généré.
+ *
+ * C'est lui qui sépare « à nous, remplaçable » de « écrit par quelqu'un » : un
+ * hook existant qui ne le porte pas n'est JAMAIS écrasé — effacer le travail
+ * d'un utilisateur n'est pas le rôle d'une commande de pose.
+ */
+export declare const GIT_HOOKS_MARKER = "pos\u00E9 par `nodefony git:hooks`";
+/** Les hooks que la commande sait poser, dans l'ordre d'affichage. */
+export declare const GIT_HOOK_NAMES: readonly ["pre-commit", "pre-push"];
+export type GitHookName = (typeof GIT_HOOK_NAMES)[number];
+/**
+ * Le contenu d'un hook.
+ *
+ * Sh POSIX strict : sous Windows, git exécute les hooks via le `sh.exe` de Git
+ * for Windows — un script simple passe partout, un bashisme non. Le `npx` est
+ * nécessaire : un hook git n'a pas `node_modules/.bin` dans son PATH.
+ *
+ * @param name - lequel des deux.
+ * @returns le script complet, marqueur compris.
+ */
+export declare function renderGitHook(name: GitHookName): string;
+/** Ce qu'il faut faire d'un hook, une fois comparé à l'existant. */
+export type GitHookAction = "pose" | "remplace" | "inchange" | "refus-etranger";
+/** Le geste décidé pour un hook. */
+export interface IPlannedGitHook {
+    name: GitHookName;
+    action: GitHookAction;
+    /** Chemin du hook, relatif à la racine de l'application, en `/`. */
+    target: string;
+    /** Contenu à écrire — celui de `renderGitHook`, tel quel. */
+    content: string;
+}
+/** Ce qu'il faut faire de `core.hooksPath`. */
+export type HooksPathAction = "pose" | "inchange" | "refus-autre";
+/**
+ * Le plan complet — hooks ET configuration, jugés ensemble.
+ *
+ * Un seul refus suffit à tout arrêter : poser la moitié d'un jeu de hooks
+ * laisse un état qu'il faut comprendre avant de corriger, alors qu'un refus
+ * franc se corrige d'un geste.
+ */
+export interface IGitHooksPlan {
+    directory: string;
+    hooks: IPlannedGitHook[];
+    hooksPath: {
+        /** Valeur actuelle de `core.hooksPath`, `null` si absente. */
+        current: string | null;
+        /** Valeur à poser (relative au TOPLEVEL git, en `/`). */
+        wanted: string;
+        action: HooksPathAction;
+    };
+    /** `true` dès qu'un refus interdit d'appliquer quoi que ce soit. */
+    refused: boolean;
+}
+/**
+ * Décide, pour chaque hook et pour `core.hooksPath`, le geste à faire.
+ *
+ * @param existing - contenu actuel de chaque hook, `null` si absent.
+ * @param currentHooksPath - valeur actuelle de `core.hooksPath`, `null` si absente.
+ * @param wantedHooksPath - valeur cible (relative au toplevel git, en `/`) —
+ *   l'appelant la calcule, car SEUL lui sait où est le toplevel : un chemin
+ *   relatif dans `core.hooksPath` se résout depuis la racine du dépôt git, pas
+ *   depuis l'application (cas réel : app dans un sous-dossier d'un monorepo).
+ * @returns le plan, applicable ou refusé.
+ */
+export declare function planGitHooks(existing: Record<string, string | null>, currentHooksPath: string | null, wantedHooksPath: string): IGitHooksPlan;
+/**
+ * Rend le plan pour un humain.
+ *
+ * @param plan - le plan calculé.
+ * @param applique - `false` quand rien n'a été écrit (`--dry-run` ou refus).
+ * @returns le texte à écrire sur la sortie standard.
+ */
+export declare function renderGitHooksPlan(plan: IGitHooksPlan, applique: boolean): string;

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

@@ -0,0 +1,48 @@
+/**
+ * Les options que le CLI déclare pour TOUTES ses commandes — et ce que les
+ * commandes autonomes doivent en faire.
+ *
+ * ## Le défaut que ce module ferme
+ *
+ * `nodefony --help` promet `-i, --interactive` et `-d, --debug` : ce sont des
+ * options POSÉES sur commander pour l'ensemble du CLI (`Cli.initCommander`).
+ * Mais les commandes qui répondent par le raccourci autonome — `create`,
+ * `doctor`, `env`, `card`, `symbols` — ne passent jamais par commander : elles
+ * lisent `process.argv` elles-mêmes, précisément pour répondre sans démarrer
+ * l'application. Elles refusaient donc, avec « option inconnue », ce que l'aide
+ * de la ligne au-dessus venait d'annoncer.
+ *
+ * C'est la faute la plus décourageante qu'un outil puisse commettre : l'aide dit
+ * une chose, la commande en dit une autre, et l'utilisateur n'a aucun moyen de
+ * savoir laquelle a raison. Vécu sur `nodefony create app --interactive`, la
+ * toute première commande qu'on tape.
+ *
+ * ## Pourquoi ici, et pas dans chaque parseur
+ *
+ * Cinq parseurs, cinq copies : la sixième commande autonome écrite demain
+ * rouvrirait le trou sans que personne le voie. La liste des options globales
+ * vit à UN endroit, et chaque parseur l'APPELLE.
+ *
+ * ## Ce que « accepter » veut dire
+ *
+ * Absorber, pas exécuter. Ces options n'ont aucun effet propre sur une commande
+ * qui ne pose aucune question et n'ouvre aucun journal de débogage — et c'est
+ * exactement ce que « mode interactif » signifie là où il n'y a rien à demander.
+ * Là où le mode interactif EXISTE (`create`), il est déjà le comportement par
+ * défaut en terminal : le drapeau confirme ce qui se produit déjà, il ne
+ * l'active pas.
+ *
+ * @module
+ */
+/** Ce mot est-il une option que le CLI déclare pour toutes ses commandes ? */
+export declare function isGlobalCliFlag(word: string): boolean;
+/**
+ * Retire d'un `argv` les options globales du CLI.
+ *
+ * À appeler par un parseur autonome AVANT sa propre lecture : ce qui reste est
+ * ce qui appartient en propre à la commande.
+ *
+ * @param argv - les mots de la ligne de commande.
+ * @returns les mots restants, dans l'ordre.
+ */
+export declare function stripGlobalCliFlags(argv: readonly string[]): string[];

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

@@ -0,0 +1,110 @@
+/**
+ * Les groupes d'intention, dans l'ordre de la JOURNÉE de travail.
+ *
+ * On lance, on regarde ce qui cloche, on fait évoluer — puis viennent les
+ * domaines (base, comptes, front) et l'outillage. L'ordre est le contenu : il
+ * répond avant qu'on ait lu les titres.
+ */
+export declare const HELP_GROUPS: readonly string[];
+/**
+ * Le libellé de chaque intention DANS LE MENU interactif.
+ *
+ * 🔴 Une seule taxonomie, deux rendus. Le menu s'adresse à quelqu'un qui hésite
+ * (phrase, minuscules) et l'aide à quelqu'un qui balaie (titre, capitales) : les
+ * libellés diffèrent, le CLASSEMENT non. Écrits séparément, ils divergeaient
+ * déjà — une commande rangée sous « Comprendre » au menu et ailleurs dans
+ * l'aide apprend au lecteur à ne se fier ni à l'un ni à l'autre.
+ */
+export declare const MENU_GROUP_LABELS: Record<string, string>;
+/** Une commande, réduite à ce que l'aide doit en dire. */
+export interface IHelpCommand {
+    /** Le nom principal, tel qu'on le tape. */
+    name: string;
+    /** Ses alias, s'il en a — ils n'existent que si l'aide les montre. */
+    aliases: readonly string[];
+    /** Ce qu'elle fait, en une phrase. */
+    description: string;
+    /** Le groupe d'intention déclaré par la commande. */
+    group?: string;
+    /** Le module qui la porte, quand elle n'est pas intégrée. */
+    module?: string;
+    /**
+     * Ce que la commande ACCEPTE, rendu sous elle en sous-ligne.
+     *
+     * DÉRIVÉ des `choices()` de commander, jamais réécrit : c'est ce qu'un agent
+     * cherche (« quels sujets sait-il inspecter ? ») et ce qu'un humain devine
+     * mal. Une liste recopiée ici divergerait au premier sujet ajouté.
+     */
+    accepts?: {
+        label: string;
+        values: readonly string[];
+    };
+}
+/** Une option globale, telle que l'aide la montre. */
+export interface IHelpOption {
+    /** Les drapeaux, déjà composés (`-d, --debug`). */
+    flags: string;
+    description: string;
+}
+/** Tout ce que le rendu a besoin de savoir — et rien d'autre. */
+export interface IHelpModel {
+    /** La version affichée en tête, sans le `v`. */
+    version: string;
+    commands: readonly IHelpCommand[];
+    globalOptions: readonly IHelpOption[];
+    /** Les modules chargés, s'il y en a — absent hors d'une application. */
+    modules?: readonly string[];
+    /**
+     * Ce que l'aide doit DIRE de la situation, quand elle n'est pas nominale :
+     * hors d'une application, ou dans une application non installée.
+     */
+    note?: string;
+    /** Le geste qui suit cette note (une commande à taper). */
+    noteAction?: string;
+    /** Les commandes qui répondent en JSON — la phrase de pied pour un agent. */
+    jsonCommands?: readonly string[];
+}
+/** Le décor du rendu — tout ce que ce module refuse d'aller chercher. */
+export interface IHelpRenderOptions {
+    /** Largeur utile, déjà bornée. */
+    width: number;
+    /** `true` pour émettre des séquences ANSI. */
+    color: boolean;
+}
+/**
+ * La place qui reste pour une description, une fois la colonne des noms posée.
+ *
+ * 🔴 Exportée pour qu'un GATE puisse s'y adosser au lieu de recopier le calcul.
+ * La contrainte « une description tient sur une ligne » ne vaut que rapportée à
+ * la colonne du moment, et celle-ci se DÉRIVE des commandes présentes : une
+ * borne écrite en dur dans un test deviendrait fausse le jour où un nom plus
+ * long élargit la colonne — le test resterait vert pendant que la page se
+ * replie.
+ *
+ * @param commands - les commandes qui composent la page.
+ * @param width - la largeur utile du terminal.
+ * @returns le nombre de colonnes offertes à une description sur sa première ligne.
+ */
+export declare function descriptionWidth(commands: readonly IHelpCommand[], width: number): number;
+/**
+ * Range les commandes par groupe, dans l'ordre d'affichage.
+ *
+ * Les commandes sans groupe connu tombent sous leur MODULE — ce qui reste vrai
+ * pour un module tiers, dont personne ici ne peut deviner l'intention. Sans
+ * module ni groupe, elles ferment la marche sous « AUTRES ».
+ *
+ * @param commands - toutes les commandes connues.
+ * @returns les groupes non vides, dans l'ordre de lecture.
+ */
+export declare function groupCommands(commands: readonly IHelpCommand[]): {
+    title: string;
+    commands: IHelpCommand[];
+}[];
+/**
+ * L'aide complète, ligne par ligne, sans retour chariot final.
+ *
+ * @param model - ce qu'il y a à dire.
+ * @param opts - le décor (largeur, couleur).
+ * @returns les lignes à écrire, dans l'ordre.
+ */
+export declare function renderHelp(model: IHelpModel, opts: IHelpRenderOptions): string[];

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

@@ -0,0 +1,21 @@
+import type { ICliManifest } from "./completion.js";
+/** Nom de la page, section 1 (commandes utilisateur). */
+export declare const MAN_PAGE_NAME = "nodefony.1";
+/**
+ * Échappe une chaîne pour roff.
+ *
+ * Trois pièges, tous silencieux — ils ne produisent pas d'erreur, seulement une
+ * page mal rendue : la contre-oblique introduit les séquences roff, le tiret nu
+ * devient un tiret TYPOGRAPHIQUE (illisible dans une option `--json`, et non
+ * copiable), et une ligne qui COMMENCE par un point ou une apostrophe est lue
+ * comme une directive.
+ */
+export declare function escapeRoff(text: string): string;
+/**
+ * Rend la page de manuel complète, en roff.
+ *
+ * @param manifest - le manifest des commandes INTÉGRÉES (extrait de commander).
+ * @param version - version du paquet, affichée dans l'en-tête et le pied.
+ * @returns le source roff, terminé par un saut de ligne.
+ */
+export declare function renderManPage(manifest: ICliManifest, version: string): string;

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

@@ -0,0 +1,45 @@
+/**
+ * Le chemin du lanceur `nodefony`, tel que CETTE installation l'a reçu.
+ *
+ * ## Pourquoi une fonction, et pas un chemin écrit à la main
+ *
+ * Un appelant qui doit démarrer l'application — une suite de tests, un shim de
+ * création d'application, un script de déploiement — écrivait jusqu'ici
+ * `node_modules/.bin/nodefony`. Trois choses lui donnent tort :
+ *
+ *  1. **Ce fichier n'existe pas sous Windows.** npm y écrit un `nodefony.cmd`,
+ *     et Node refuse d'exécuter un script batch sans passer par un shell
+ *     (correctif de CVE-2024-27980). Le symptôme est un `ENOENT` sur un chemin
+ *     qui semble pourtant présent — il désigne le fichier SANS extension.
+ *  2. **L'emplacement n'est pas garanti.** Hoisting npm, espaces de travail,
+ *     pnpm et son magasin : le paquet n'est pas toujours dans le
+ *     `node_modules` du dossier courant.
+ *  3. **Le nom du binaire appartient au framework**, pas à ses utilisateurs.
+ *     Écrit en dur chez chacun, il ne peut plus jamais changer.
+ *
+ * La résolution passe donc par le MANIFESTE : Node localise `nodefony` comme il
+ * localiserait n'importe quel import, et le champ `bin` dit où est le lanceur.
+ * Aucune extension à deviner, aucun shell à ouvrir, aucun chemin à supposer.
+ *
+ * ## Usage
+ *
+ * Le résultat se donne à `node`, jamais au système : c'est un script, pas un
+ * exécutable.
+ *
+ * ```ts
+ * import { execFileSync } from "node:child_process";
+ * import { nodefonyBin } from "nodefony";
+ *
+ * execFileSync(process.execPath, [nodefonyBin(), "production", "--detach", "--wait"]);
+ * ```
+ *
+ * @param since - d'où résoudre, si ce n'est pas depuis ce module (rare). Un
+ *                 appelant installé À CÔTÉ du framework — un shim `create-*`,
+ *                 par exemple — passe son propre `import.meta.url` pour que la
+ *                 résolution parte de SON arbre de dépendances.
+ * @returns Le chemin ABSOLU du script de lancement.
+ * @throws Si le paquet `nodefony` est introuvable depuis `depuis` — le message
+ *         dit alors que c'est l'INSTALLATION qui manque, pas le chemin qui est
+ *         faux.
+ */
+export declare function nodefonyBin(since?: string): string;