nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/cli/scaffold/userContractSource.d.ts

@@ -0,0 +1,86 @@
+import type { IEntityField } from "./entityFields.js";
+/**
+ * Une colonne du contrat utilisateur, telle que `@nodefony/user` la publie.
+ *
+ * Le type est redéclaré ici — et c'est délibéré, ce n'est pas une copie du
+ * contrat. Le cœur ne dépend pas de `@nodefony/user` (c'est l'inverse : le
+ * module d'identité dépend du cœur), donc il ne peut pas en importer le type.
+ * Ce qui est décrit ici est la FORME LUE, pas la liste des colonnes — celle-là
+ * n'est jamais recopiée, elle est lue à l'exécution dans l'application cible.
+ */
+export interface IUserContractColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    readonly unique?: boolean;
+    readonly origin: "identity" | "column" | "audit";
+    readonly makeDefault?: () => unknown;
+    readonly refreshedOnWrite?: boolean;
+    readonly readers: readonly string[];
+    readonly description: string;
+}
+/**
+ * Lit le contrat de colonnes de l'utilisateur DANS l'application cible.
+ *
+ * La liste ne peut pas vivre dans le générateur : elle appartient à
+ * `@nodefony/user`, et une seconde copie ici divergerait — exactement ce que la
+ * source unique a supprimé. Elle est donc résolue depuis l'application, ce qui a
+ * un second mérite : c'est la version que CETTE application a installée qui est
+ * écrite dans son entité, jamais celle du dépôt qui a produit le générateur.
+ *
+ * @param appRoot - racine de l'application où l'entité sera écrite.
+ * @returns les colonnes du contrat, dans l'ordre où le module les publie.
+ * @throws Error si le module d'identité n'est pas installé — sans lui, il n'y a
+ *   pas d'utilisateur à générer, et deviner les colonnes serait le pire choix.
+ */
+export declare function readUserContract(appRoot: string): readonly IUserContractColumn[];
+/**
+ * Le nom de la table des utilisateurs, LU dans l'application cible.
+ *
+ * Il ne se déduit pas du nom de l'entité : l'utilisateur est la seule table que
+ * le framework interroge en SQL natif, sous un nom écrit en dur. Appliquer la
+ * règle du pluriel produirait `users` face à un SQL qui lit `User` — la
+ * recherche par compte externe ne trouverait plus rien, sans lever, et chaque
+ * connexion créerait un compte de plus.
+ *
+ * Lu depuis l'application, comme les colonnes : c'est la version installée LÀ
+ * qui décide, pas celle du dépôt qui a produit le générateur.
+ *
+ * @param appRoot - racine de l'application où l'entité sera écrite.
+ * @returns le nom de la table, tel que le contrat le publie.
+ * @throws Error si le module d'identité est absent ou trop ancien pour le
+ *   publier — deviner ce nom est le pire des choix possibles.
+ */
+export declare function userTableName(appRoot: string): string;
+/**
+ * Convertit les colonnes du contrat en champs du générateur.
+ *
+ * La clé primaire est écartée : le générateur la produit lui-même, et le contrat
+ * n'en dit que le type. Les horodatages passent par `defaultNow` — « maintenant »
+ * n'est pas une valeur littérale que la grammaire sache écrire.
+ *
+ * Les valeurs par défaut sont OBTENUES du contrat, pas devinées : la fabrique est
+ * appelée, et son résultat sérialisé. C'est ce qui garantit qu'un défaut ajouté
+ * au contrat apparaît dans les entités générées ensuite, sans toucher ici.
+ *
+ * @param columns - le contrat, tel que l'application l'a installé.
+ * @returns les champs, dans l'ordre du contrat.
+ */
+export declare function userContractFields(columns: readonly IUserContractColumn[]): IEntityField[];
+/**
+ * Refuse un champ métier obligatoire qui n'aurait aucune valeur par défaut.
+ *
+ * Le framework CRÉE des utilisateurs sans connaître ces champs — au semis d'un
+ * administrateur, à la première connexion par un fournisseur externe. Un champ
+ * obligatoire qu'il ne peut pas renseigner fait échouer ces chemins, et le
+ * prototype a montré comment : le semis échoue avec un **code de sortie 0**,
+ * l'application démarre, et il n'y a simplement aucun administrateur.
+ *
+ * Le même champ pose un second problème, plus tard : ajouté à une table déjà
+ * peuplée, un `ADD COLUMN … NOT NULL` sans défaut est refusé par le serveur.
+ * Une seule règle ferme les deux.
+ *
+ * @param fields - les champs demandés par l'utilisateur (hors contrat).
+ * @throws Error en nommant le champ et les deux façons de le rendre acceptable.
+ */
+export declare function assertUserFieldsAreFillable(fields: IEntityField[]): void;

package/dist/types/cli/scaffold/versions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Catalogue UNIQUE des versions npm émises par les scaffolds (`create app`,
+ * `create front`, lots suivants) — la SEULE table à toucher quand une dep
+ * tierce bouge. Les paquets `nodefony`/`@nodefony/*` n'y figurent PAS : leurs
+ * versions sont dynamiques (`it.nodefonyVersion` = la version du paquet qui
+ * scaffolde) → une release du framework ne réécrit AUCUN template.
+ *
+ * Anti-dérive : `create.test.ts` compare ce catalogue aux versions RÉELLES du
+ * monorepo (racine + core) — bumper une dep du repo sans répercuter ici fait
+ * échouer le banc, jamais une divergence silencieuse.
+ */
+export declare const SCAFFOLD_VERSIONS: Record<string, string>;
+/** Sous-ensemble du catalogue (helper des tables par framework). */
+export declare function pick(...names: string[]): Record<string, string>;

package/dist/types/cli/scaffold/writer.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Écriture prévue par un scaffold, telle qu'un dry-run la restitue.
+ *
+ * `previous` n'est renseigné que pour un `overwrite` : c'est ce qui permet à un
+ * front (CLI `--dry-run`, préview Studio) de montrer un vrai diff plutôt qu'une
+ * liste de chemins.
+ */
+export interface IScaffoldChange {
+    /** Chemin absolu du fichier. */
+    path: string;
+    /** Le fichier n'existait pas (`create`) ou sera réécrit (`overwrite`). */
+    kind: "create" | "overwrite";
+    /** Contenu qui sera écrit. */
+    content: string;
+    /** Contenu actuel sur disque — seulement si `kind === "overwrite"`. */
+    previous?: string;
+}
+/** Une ligne d'un diff, telle que {@link diffLines} la classe. */
+export interface IDiffLine {
+    /** `keep` = inchangée, `add` = ajoutée, `remove` = retirée. */
+    kind: "keep" | "add" | "remove";
+    text: string;
+}
+/**
+ * Diff ligne à ligne de deux contenus (plus longue sous-séquence commune).
+ *
+ * Calculé au MOTEUR, et non dans chaque front : le CLI (`--dry-run`) et la
+ * préview Studio montrent le même changement, et un rendu qui diverge du plan
+ * réellement exécuté serait pire que pas de préview du tout.
+ *
+ * Au-delà de {@link DIFF_MAX_LINES} lignes, rend le remplacement en bloc —
+ * exact, mais sans détail.
+ */
+export declare function diffLines(before: string, after: string): IDiffLine[];
+/**
+ * Système de fichiers TRANSACTIONNEL du scaffold : toutes les écritures sont
+ * retenues en mémoire, et ne touchent le disque qu'au {@link ScaffoldWriter.commit}
+ * final.
+ *
+ * POURQUOI le moteur ne peut pas écrire au fil de l'eau : un scaffold est une
+ * suite d'étapes dont plusieurs peuvent REFUSER *après* les premières écritures
+ * — nom de classe déjà pris, `@controllers([...])` introuvable, tag eta résiduel,
+ * workspace de link manquant. Écrire puis lever laisse un projet à moitié
+ * modifié, alors que l'utilisateur lit un message d'erreur et croit
+ * légitimement que rien n'a bougé (il a perdu son fichier). En différant le
+ * disque, « refuser » redevient un non-événement : aucune garde n'a besoin
+ * d'être placée avant les rendus, et une garde ajoutée demain est
+ * automatiquement sûre.
+ *
+ * La transaction sert AUSSI de source du dry-run : ne pas committer, c'est
+ * exactement simuler — sans une seconde implémentation du moteur qui dériverait.
+ *
+ * Les LECTURES passent par la transaction (`read`/`exists`/`listDir`) : une
+ * étape doit voir ce que les précédentes ont produit. Sans cela, câbler deux
+ * décorateurs dans le même `index.ts` perdrait la première insertion, et le
+ * controller d'un module tout juste rendu ne trouverait pas sa cible.
+ *
+ * Portée : les fichiers du PROJET. Les templates et le paquet `nodefony`
+ * lui-même se lisent directement — ils sont en lecture seule.
+ */
+export declare class ScaffoldWriter {
+    #private;
+    /** Contenu à jour du fichier — écriture en attente d'abord, sinon disque. */
+    read(file: string): string;
+    /**
+     * Le chemin existe-t-il, une fois la transaction appliquée ? Vrai aussi pour
+     * un DOSSIER qui n'existe encore que par les fichiers en attente qu'il
+     * contient (`modules/blog/` pendant `create module`).
+     */
+    exists(file: string): boolean;
+    /**
+     * Entrées d'un dossier, disque et transaction fusionnés — la vue dont
+     * `listTargets` a besoin pour voir un module qui n'est pas encore committé.
+     */
+    listDir(dir: string): {
+        name: string;
+        isDirectory: boolean;
+    }[];
+    /** Retient une écriture. Rien ne touche le disque avant {@link commit}. */
+    write(file: string, content: string): void;
+    /**
+     * Écritures prévues, dans l'ordre — matière du dry-run et de la préview.
+     *
+     * L'état « existait déjà » est relu ICI (et non à `write`) : entre les deux,
+     * seule la transaction a pu changer, et elle est justement ce qu'on décrit.
+     */
+    changes(): IScaffoldChange[];
+    /** Nombre d'écritures en attente. */
+    get size(): number;
+    /**
+     * Applique la transaction sur le disque, dans l'ordre d'écriture.
+     *
+     * Ce n'est PAS atomique au sens du système de fichiers (aucune API portable
+     * ne l'offre pour un arbre) : une panne disque en cours de vidage laisse un
+     * résultat partiel. Ce que la transaction garantit, c'est qu'aucune décision
+     * du moteur — garde, validation, rendu cassé — ne peut plus produire ce
+     * résultat partiel, ce qui était le seul cas observé en pratique.
+     */
+    commit(): void;
+}

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

@@ -0,0 +1,195 @@
+/**
+ * Composition PURE du menu interactif `nodefony menu` — même patron que
+ * `envReport`/`cardReport`/`aiSyncReport` : ce fichier reçoit l'état (contexte,
+ * descriptions, commandes de module) et rend une structure neutre ; l'adaptateur
+ * (`MenuCommand`) la traduit en prompts inquirer. Zéro I/O, zéro import lourd :
+ * testable sans TTY et sans kernel.
+ *
+ * Deux règles tiennent ce menu :
+ * - le RÉSUMÉ d'une entrée vient de `command.description()` (source unique,
+ *   celle de `--help`) — jamais d'une copie locale qui divergerait ;
+ * - le menu n'ajoute que ce qui n'existe nulle part ailleurs : le CONSEIL
+ *   d'usage (`when`), affiché sous la liste pendant la navigation.
+ *
+ * Une commande absente de commander (retirée, renommée) sort du menu toute
+ * seule : `describe()` rend `null` et l'entrée n'est pas émise.
+ */
+/** Contexte de lancement : dans un projet Nodefony, ou hors de tout projet. */
+export type StartMenuContext = "project" | "outside";
+/**
+ * Item neutre du menu — champs BRUTS, aucun rendu. L'adaptateur compose
+ * l'affichage (alignement, couleurs, troncature à la largeur du terminal) :
+ * la composition décide QUOI montrer, jamais COMMENT.
+ */
+export type StartMenuItem = {
+    kind: "separator";
+    label: string;
+} | {
+    kind: "choice";
+    /** Ce que l'utilisateur choisit (colonne de gauche). */
+    label: string;
+    /** Résumé court (colonne de droite, tronquable). */
+    summary: string;
+    value: string;
+    /** Conseil d'usage, affiché sous la liste pendant la navigation. */
+    description: string;
+};
+/** Une commande de module lue du manifest cache de complétion. */
+export interface IStartMenuModuleCommand {
+    name: string;
+    description: string;
+    /**
+     * Le groupe d'intention de la commande, quand elle en déclare un.
+     *
+     * Sans lui, toutes les commandes de module tombaient dans un unique
+     * fourre-tout (« Commandes du projet »), pendant que l'aide les rangeait par
+     * intention. Le même CLI se présentait donc de deux façons selon la porte.
+     */
+    group?: string;
+}
+export interface IStartMenuInput {
+    /** Vrai si une application Nodefony est résolue ici (`kernel.trunk`). */
+    inProject: boolean;
+    /**
+     * Résumé d'une commande — `command.description()` de commander, ou `null`
+     * si la commande n'est pas enregistrée (elle est alors écartée du menu).
+     */
+    describe: (name: string) => string | null;
+    /**
+     * Commandes de MODULE (`security:user:add`, …) lues du manifest cache de
+     * complétion — elles ne sont pas encore posées dans commander à `onStart`
+     * (dispatch différé), mais le cache écrit au dernier boot dev les connaît.
+     */
+    moduleCommands?: IStartMenuModuleCommand[];
+    /**
+     * Toutes les commandes que commander connaît DÉJÀ (les intégrées), avec leur
+     * groupe d'intention et le nombre d'arguments qu'elles EXIGENT.
+     *
+     * 🔴 C'est ce qui remplace la liste blanche. Le menu ne proposait que les
+     * commandes inscrites à la main dans son catalogue : une commande neuve n'y
+     * entrait jamais, et personne ne s'en apercevait — le menu avait toujours
+     * l'air complet. Le catalogue ne sert plus qu'à ce qu'aucune dérivation ne
+     * peut donner : l'ORDRE de lecture et le CONSEIL d'usage.
+     *
+     * Une commande qui exige un argument est écartée : le menu la lancerait sans
+     * lui, et l'utilisateur recevrait une erreur d'usage au lieu d'un geste.
+     */
+    builtinCommands?: readonly {
+        name: string;
+        description: string;
+        group?: string;
+        requiredArgs?: number;
+    }[];
+    /**
+     * Noms des scripts présents dans le `package.json` du projet. Le menu n'en
+     * propose que ceux de son catalogue (`NPM_SCRIPT_CATALOG`) : les gestes
+     * qualité et infra qu'aucune commande nodefony ne porte. Un script absent
+     * du package.json n'est pas proposé — la présence fait foi, jamais le
+     * catalogue seul.
+     */
+    npmScripts?: string[];
+    /** Nom du projet, pour le message d'accueil. */
+    projectName?: string;
+}
+interface ICatalogEntry {
+    value: string;
+    contexts: StartMenuContext[];
+    /**
+     * Titre de groupe, par contexte (un même geste change de sens hors projet).
+     *
+     * 🔴 Dans un projet, il se DÉRIVE de l'intention déclarée par la commande —
+     * `menuGroupe()` traduit `HELP_GROUPS` en libellé de menu. Une seconde
+     * taxonomie écrite ici divergerait de l'aide au premier ajout, et le lecteur
+     * n'aurait plus aucune raison de croire l'une plutôt que l'autre.
+     */
+    group: Record<StartMenuContext, string | null>;
+    /** Le CONSEIL d'usage — la seule prose qui n'existe pas déjà ailleurs. */
+    when: string;
+}
+export declare const START_MENU_CATALOG: readonly ICatalogEntry[];
+/**
+ * Scripts npm que le menu sait proposer — les gestes qu'AUCUNE commande
+ * nodefony ne porte (qualité, infra docker). Un script n'apparaît que s'il
+ * existe dans le package.json du projet (`npmScripts`). La valeur émise est
+ * préfixée `npm:` — l'adaptateur la déplie en `npm run <script>`.
+ */
+export declare const NPM_SCRIPT_CATALOG: readonly {
+    script: string;
+    /** Résumé court (colonne de droite) — le geste, pas le pourquoi. */
+    summary: string;
+    group: string;
+    when: string;
+}[];
+/** Préfixe des valeurs « script npm » émises par le menu. */
+export declare const NPM_SCRIPT_PREFIX = "npm:";
+/** Titre du groupe des commandes de module (projet seulement). */
+export declare const MODULE_COMMANDS_GROUP = "Commandes du projet";
+/** Ce que le menu doit FAIRE d'un choix — décidé ici, exécuté par l'adaptateur. */
+export type MenuAction = 
+/** Script du projet : `npm run <script>`, sortie héritée. */
+{
+    kind: "npm";
+    script: string;
+}
+/** Commande intégrée : commander la connaît, on l'exécute dans CE process. */
+ | {
+    kind: "inline";
+    argv: string[];
+}
+/** Commande de MODULE : elle exige un process neuf (voir ci-dessous). */
+ | {
+    kind: "respawn";
+    argv: string[];
+};
+/**
+ * Le plan d'exécution d'un choix de menu.
+ *
+ * ⚠️ **Une commande de MODULE ne peut pas s'exécuter dans le process du menu.**
+ * Le menu s'ouvre à `onStart` pour rester instantané ; à cette phase, les
+ * commandes de module ne sont pas encore posées dans commander (elles le sont à
+ * `onPreRegister`, par le dispatch différé). Les exécuter par le re-parse
+ * commander donnait donc `unknown command 'http:network'` + CRITIC + exit 1 —
+ * un menu qui PROPOSE un geste puis le refuse. Elles se relancent dans un
+ * process neuf, exactement comme le menu le fait déjà pour un script npm : le
+ * boot complet a lieu, le dispatch différé fait son travail.
+ *
+ * La décision vit ici, PURE, parce qu'elle se teste : l'adaptateur ne fait plus
+ * que `spawnSync` ou appeler commander, gestes qu'aucun test unitaire n'observe.
+ *
+ * @param response - la valeur choisie dans le menu.
+ * @param isBuiltin - commander connaît-il cette commande à cet instant ?
+ */
+export declare function planMenuAction(response: string, isBuiltin: (name: string) => boolean): MenuAction;
+/**
+ * Construit le menu principal pour un contexte donné.
+ *
+ * @returns message d'accueil + items ordonnés (separators de groupe inclus).
+ */
+export declare function buildStartMenu(input: IStartMenuInput): {
+    message: string;
+    items: StartMenuItem[];
+};
+/**
+ * Sous-menu des sujets d'`inspect`, dérivé de la table SOURCE
+ * (`INSPECT_SUBJECTS`) : seuls les sujets SANS argument obligatoire sont
+ * proposés (un sujet à paramètre exigerait une saisie de plus — il reste
+ * accessible en ligne de commande, l'aide d'`inspect` les liste).
+ *
+ * @param subjects - la table `INSPECT_SUBJECTS` (injectée : ce fichier reste pur).
+ */
+export declare function buildInspectMenu(subjects: Record<string, {
+    summary: string;
+    param?: string;
+}>): {
+    message: string;
+    items: StartMenuItem[];
+};
+/**
+ * Filtre le menu à la frappe (prompt `search`) — la logique est ICI, pure et
+ * testée : normalisation (minuscules, accents retirés), chaque MOT du terme
+ * doit se retrouver dans le label, le résumé, le conseil OU le titre du groupe
+ * de l'entrée. Les titres de groupe suivent leurs entrées : un groupe dont
+ * rien ne survit disparaît AVEC son titre.
+ */
+export declare function filterStartMenu(items: StartMenuItem[], term: string): StartMenuItem[];
+export {};

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

@@ -0,0 +1,84 @@
+/** Un symbole tel que le graphe le décrit (surface utile, pas le fichier entier). */
+export interface ISymbolEntry {
+    name: string;
+    kind: string;
+    /** Nom npm du paquet qui le porte (`@nodefony/http`, `@nodefony/core`). */
+    module: string;
+    /** Chemin du source, relatif à la racine du dépôt qui l'a produit. */
+    file: string;
+    line?: number;
+    exported?: boolean;
+    /** Première phrase du TSDoc — auto-suffisante par convention. */
+    description?: string;
+    extends?: string;
+    implements?: string[];
+}
+/** Ce que le graphe contient, réduit à ce que ses lecteurs utilisent. */
+export interface ISymbolsGraph {
+    generated?: string;
+    version?: string;
+    symbols: Record<string, ISymbolEntry>;
+    relations?: Record<string, Record<string, string[]>>;
+}
+/**
+ * Trouve le graphe symbolique utilisable depuis `from`.
+ *
+ * @param from - dossier de départ (typiquement le cwd).
+ * @returns le chemin du fichier, ou `null` si aucun graphe n'est atteignable.
+ */
+export declare function resolveSymbolsFile(from: string): string | null;
+/**
+ * Lit le graphe, ou `null` s'il est absent ou illisible.
+ *
+ * Ne lève jamais : un outil de découverte qui tombe sur un fichier corrompu doit
+ * le DIRE à son appelant, pas interrompre ce qu'il diagnostiquait.
+ *
+ * @param from - dossier de départ de la résolution.
+ */
+export declare function readSymbolsGraph(from: string): ISymbolsGraph | null;
+/**
+ * Trouve un symbole par son nom exact.
+ *
+ * Le graphe indexe par nom, sauf pour les **homonymes** qu'il range sous
+ * `Module:Nom` — d'où le second passage, qui les rattrape. Extrait ici parce
+ * que la commande n'est plus le seul lecteur : le serveur MCP interroge le même
+ * graphe, et deux résolutions d'homonymes finiraient par différer.
+ *
+ * @param graph - le graphe déjà lu
+ * @param name - nom exact recherché
+ * @returns l'entrée, ou `undefined`
+ */
+export declare function lookupSymbol(graph: ISymbolsGraph, name: string): ISymbolEntry | undefined;
+/** Ce que la ligne de commande demande. */
+interface ISymbolsRequest {
+    /** Nom exact d'un symbole, ou `null` pour un résumé. */
+    name: string | null;
+    json: boolean;
+    /** Filtre par paquet (`--module @nodefony/http`). */
+    module: string | null;
+    cwd: string;
+    /** `true` si l'on veut seulement la page d'aide. */
+    help: boolean;
+}
+/**
+ * Parse l'argv après le mot `symbols`.
+ *
+ * @param argv - `process.argv` complet.
+ * @returns la demande, ou le motif du refus.
+ */
+export declare function parseSymbolsArgv(argv: string[]): ISymbolsRequest | {
+    error: string;
+};
+/**
+ * Commande `nodefony symbols` — le graphe, sans boot et sans dépôt.
+ *
+ * Trois usages, du plus fréquent au plus rare : un nom (« qu'est-ce que
+ * `AbstractCrudService` ? »), un paquet (`--module @nodefony/http` : sa surface
+ * exportée), rien (le résumé — d'où vient le graphe, ce qu'il couvre).
+ *
+ * @param argv - `process.argv` complet.
+ * @returns exit code sémantique (`OK`, `USAGE`, `NOINPUT` si aucun graphe,
+ *   `DATAERR` si le symbole demandé est introuvable).
+ */
+export declare function runSymbolsCommand(argv: string[]): number;
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * Codes de sortie standardisés — convention BSD `sysexits.h` (FreeBSD
+ * `sysexits(3)`). Ce n'est PAS un RFC, mais le standard de facto Unix pour des
+ * exit codes porteurs de sens, au-delà du binaire POSIX `0`/non-zéro. Permet à un
+ * script appelant de distinguer un « mauvais usage » d'une « erreur interne » ou
+ * d'une « config invalide ».
+ *
+ * Nodefony n'utilise qu'un sous-ensemble pertinent côté CLI ; les valeurs sont
+ * celles de `sysexits.h` (ne pas les renuméroter).
+ */
+export declare enum SysExit {
+    /** Succès. */
+    OK = 0,
+    /** Mauvais usage : commande inconnue, arguments/options invalides. */
+    USAGE = 64,
+    /** Donnée d'entrée incorrecte (format/contenu). */
+    DATAERR = 65,
+    /** Entrée requise introuvable (fichier/ressource absent). */
+    NOINPUT = 66,
+    /** Service requis indisponible (dépendance non démarrée/enregistrée). */
+    UNAVAILABLE = 69,
+    /** Sortie impossible à créer (dossier cible existant non vide, droits). */
+    CANTCREAT = 73,
+    /** Erreur interne du logiciel (bug, exception non gérée au boot). */
+    SOFTWARE = 70,
+    /** Permission refusée : l'appelant est connu, son rôle ne suffit pas. */
+    NOPERM = 77,
+    /** Erreur de configuration. */
+    CONFIG = 78
+}
+export default SysExit;

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

@@ -0,0 +1,44 @@
+/** Une ligne de données — les clés deviennent les colonnes. */
+export type TableRow = Record<string, unknown>;
+/** Le décor du rendu — tout ce que ce module refuse d'aller chercher. */
+export interface ITableOptions {
+    /** Largeur utile, déjà bornée. */
+    width: number;
+    /** `true` pour émettre des séquences ANSI. */
+    color: boolean;
+    /**
+     * Colonnes à rendre, dans cet ordre. Par défaut : l'union des clés
+     * rencontrées, dans l'ordre où elles apparaissent.
+     */
+    columns?: readonly string[];
+}
+/** Ce qu'une cellule doit à son lecteur : lisible, jamais du JSON brut. */
+export declare function formatCell(value: unknown): string;
+/**
+ * Les colonnes présentes dans les données, dans l'ordre de rencontre.
+ *
+ * @param rows - les lignes.
+ * @returns les noms de colonnes, sans doublon.
+ */
+export declare function columnsOf(rows: readonly TableRow[]): string[];
+/**
+ * Répartit la largeur disponible entre les colonnes.
+ *
+ * Chacune reçoit ce qu'elle demande tant que le total tient. Au-delà, on rogne
+ * les PLUS LARGES d'abord, par paliers : rogner uniformément punirait une
+ * colonne de six caractères autant qu'une de soixante, et c'est la première
+ * qu'on rend illisible.
+ *
+ * @param requested - largeur idéale de chaque colonne.
+ * @param available - place totale pour les contenus (séparateurs déduits).
+ * @returns la largeur retenue pour chaque colonne, dans le même ordre.
+ */
+export declare function repartir(requested: readonly number[], available: number): number[];
+/**
+ * Le tableau, ligne par ligne, sans retour chariot final.
+ *
+ * @param rows - les données ; une clé absente d'une ligne rend une cellule vide.
+ * @param opts - le décor (largeur, couleur, colonnes retenues).
+ * @returns les lignes à écrire, dans l'ordre.
+ */
+export declare function renderTable(rows: readonly TableRow[], opts: ITableOptions): string[];

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

@@ -0,0 +1,108 @@
+/**
+ * La page d'aide d'UNE commande — le socle que toutes les commandes partagent.
+ *
+ * **Pourquoi un socle.** Le pied de `nodefony --help` promet
+ * `nodefony <commande> --help`. Dix commandes ne tenaient pas cette promesse :
+ * sept répondaient « option inconnue : --help » avec le code 64, trois
+ * l'ignoraient et S'EXÉCUTAIENT — `nodefony stop --help` arrêtait réellement le
+ * serveur. Écrire dix pages à la main aurait rendu dix mises en page
+ * différentes, dont on n'aurait corrigé qu'une à chaque fois qu'un défaut y
+ * serait trouvé : l'aide de `doctor` avait déjà tout ce qu'il faut, et c'est
+ * elle qu'on a extraite ici plutôt que de la recopier.
+ *
+ * **Le rendu est PUR** ({@link renderUsage}) : la largeur et les couleurs lui
+ * sont DONNÉES. C'est ce qui le rend éprouvable ailleurs que dans le terminal
+ * où il tourne — donc en intégration continue, où il n'y en a pas.
+ *
+ * **Ce qu'une page doit dire**, et dans cet ordre : ce que la commande fait,
+ * comment on l'appelle, ce que chaque option change, au moins un exemple, et
+ * ses codes de sortie. Les deux derniers sont ceux qu'on oublie : un exemple
+ * répond plus vite qu'un paragraphe, et personne d'autre ne dit à un script
+ * comment lire le retour.
+ *
+ * @module
+ */
+import { type IPalette } from "../kernel/checks/report.js";
+/** Une ligne à deux colonnes : un terme, ce qu'il fait. */
+export interface IUsageEntry {
+    /** La colonne de gauche — un drapeau, un code, une commande d'exemple. */
+    term: string;
+    /** Ce qu'il change, en une phrase. */
+    text: string;
+}
+/**
+ * Une section libre, insérée entre l'en-tête et les options.
+ *
+ * Elle porte ce qu'aucune liste d'options ne dirait : ce que la commande
+ * regarde, ce qu'elle refuse de faire, la frontière de ce qu'elle sait.
+ */
+export interface IUsageSection {
+    title: string;
+    /** Un paragraphe, replié à la largeur. */
+    paragraph?: string;
+    /** Des lignes déjà composées (une énumération, par exemple). */
+    lines?: readonly string[];
+    /** Des entrées à deux colonnes. */
+    entries?: readonly IUsageEntry[];
+}
+/** Tout ce qu'une page d'aide a besoin de savoir — et rien d'autre. */
+export interface IUsagePage {
+    /** La commande telle qu'on la tape, `nodefony` compris. */
+    command: string;
+    /** Ce qu'elle fait, en une ligne — la même intention que sa description. */
+    tagline: string;
+    /** Ses alias, s'il en a. */
+    aliases?: readonly string[];
+    /**
+     * Les formes d'appel. Défaut : `<command> [options]`.
+     *
+     * Plusieurs lignes quand les formes s'excluent — `env --example` n'accepte
+     * pas les mêmes drapeaux que `env` seul, et une syntaxe unique le cacherait.
+     */
+    synopsis?: readonly string[];
+    /** Les sections propres à la commande, avant OPTIONS. */
+    sections?: readonly IUsageSection[];
+    options: readonly IUsageEntry[];
+    examples: readonly IUsageEntry[];
+    /**
+     * Les codes de sortie PROPRES à la commande.
+     *
+     * Les deux universels (0 et 64) sont ajoutés par le rendu : les redire dans
+     * chaque page, c'est prendre le risque qu'une seule les oublie.
+     */
+    exitCodes?: readonly IUsageEntry[];
+    /** Une dernière chose à savoir, repliée en pied de page. */
+    footer?: string;
+}
+/**
+ * Rend la page complète, retour chariot final compris.
+ *
+ * @param page - ce qu'il y a à dire.
+ * @param p - la peinture (une palette sans couleur rend du texte nu).
+ * @param width - la largeur utile, déjà bornée.
+ * @returns le texte de la page.
+ */
+export declare function renderUsage(page: IUsagePage, p: IPalette, width?: number): string;
+/**
+ * Écrit la page sur la sortie standard — la réponse à `--help`.
+ *
+ * Sur **stdout** et avec le code **0** : `--help` est une réponse, pas une
+ * erreur. Un `nodefony env --help | less` doit voir la page, et un script ne
+ * doit pas la lire comme un échec.
+ *
+ * @param page - la page à rendre.
+ * @returns le code de sortie, toujours 0.
+ */
+export declare function printUsage(page: IUsagePage): number;
+/**
+ * Écrit un refus PUIS la page, sur la sortie d'erreur.
+ *
+ * La page suit le refus parce que les deux questions arrivent ensemble : on
+ * vient de se tromper de drapeau, et ce qu'on veut lire tout de suite est la
+ * liste de ceux qui existent.
+ *
+ * @param page - la page à rendre.
+ * @param message - ce qui a été refusé, sans le nom de la commande.
+ * @returns le code de sortie, toujours 64 (EX_USAGE).
+ */
+export declare function printUsageError(page: IUsagePage, message: string): number;