nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/kernel/checks/runDoctor.d.ts

@@ -0,0 +1,361 @@
+import { checkPackageDeps } from "./packageDeps.js";
+import { checkWiring } from "./wiring.js";
+import type { ILastBoot } from "./lastBoot.js";
+import { type IReadinessResult } from "./readiness.js";
+import { type IFreshnessResult } from "./freshness.js";
+import { type ISurfaceResult } from "./surface.js";
+import { type IGuardResult } from "./guards.js";
+import { type DeepReporter, type IDeepProgress, type IDeepResult } from "./deep.js";
+import { type ILiveResult } from "./live.js";
+import { type IPalette, type DoctorFamily, type IExecution } from "./report.js";
+/** Ce que la ligne de commande demande. */
+export interface ICheckRequest {
+    json: boolean;
+    /** Dossier de DÉPART de la remontée vers la racine (défaut : le cwd). */
+    cwd: string;
+    /**
+     * `true` si un contrôle SAUTÉ doit faire échouer la commande.
+     *
+     * Même doctrine que les gates de test du dépôt (`vitest.gates.ts`) : devant
+     * un humain, un contrôle sauté est une information — il lit la section et
+     * décide. Dans une chaîne automatisée, personne ne lit : un angle mort
+     * silencieux y devient un quitus, et c'est ainsi qu'une passe « verte »
+     * n'exerce plus rien.
+     */
+    strict: boolean;
+    /**
+     * `true` si l'on veut DEMANDER à l'application, pas seulement à ses fichiers.
+     *
+     * Coûteux (un boot console, sans le moindre port ouvert) et pas toujours
+     * possible — c'est pourquoi il se demande. Le rapport statique reste rendu
+     * quoi qu'il arrive : un étage 2 en échec devient un constat lisible, jamais
+     * une exception qui emporterait le diagnostic dont on a précisément besoin
+     * quand l'application va mal.
+     */
+    live: boolean;
+    /**
+     * `true` si l'on veut LANCER ce que le projet déclare — étage 3.
+     *
+     * Les autres étages LISENT ; celui-ci exécute les scripts du projet
+     * (`typecheck`, `lint`, `test`) et interroge le registre npm. Il coûte donc
+     * des dizaines de secondes là où `doctor` en coûte moins d'une, et c'est
+     * exactement pourquoi il se demande : un diagnostic qui coûte une minute
+     * cesse d'être lancé, et un contrôle qu'on ne lance plus ne garde rien.
+     */
+    deep: boolean;
+    /** `true` si l'on demande seulement l'usage. */
+    help: boolean;
+    /**
+     * L'environnement dont on veut connaître les manques, s'il n'est pas celui
+     * d'ici (`--env production`).
+     *
+     * C'est la question qu'on se pose AVANT de déployer, et à laquelle rien ne
+     * répondait : une variable requise en production seulement est invisible sur
+     * un poste de développement, où elle est légitimement absente. Les valeurs
+     * restent celles de la machine — on ne simule pas un déploiement.
+     */
+    targetEnv: string | null;
+}
+/**
+ * L'usage, rendu avec le même soin que le rapport.
+ *
+ * Il se lit dans deux situations opposées : on découvre la commande, ou on
+ * vient de se tromper de drapeau. Il porte donc les deux réponses — ce que la
+ * commande FAIT, et ce que chaque option change — plus les codes de sortie,
+ * qu'aucune autre page ne donne et qu'un script doit connaître.
+ *
+ * @param p - la peinture en vigueur.
+ * @returns le texte complet, retour chariot final compris.
+ */
+export declare function usage(p: IPalette, width?: number): string;
+/**
+ * La distance d'édition entre deux mots, bornée.
+ *
+ * Bornée parce qu'on ne cherche pas à mesurer : on cherche à savoir si deux
+ * mots sont à une ou deux frappes l'un de l'autre. Au-delà, la réponse est
+ * « non » et le calcul ne sert plus à rien.
+ */
+export declare function editDistance(a: string, b: string, max?: number): number;
+/**
+ * Le mode connu dont cet environnement est visiblement une faute de frappe.
+ *
+ * 🔴 Vécu, et c'est le pire mode de défaillance d'un diagnostic : `doctor --env
+ * produntion` rendait un rapport COMPLET et plausible, verdict compris, sur un
+ * environnement qui n'existe nulle part — le mot inventé s'affichait tel quel
+ * dans chaque phrase. Un outil dont le rôle est de dire la vérité ne doit pas
+ * être le seul à ne pas la vérifier sur sa propre entrée.
+ *
+ * On ne refuse PAS tout inconnu : un environnement de déploiement est une
+ * chaîne libre, et refuser `preprod` rendrait l'option inutilisable là où elle
+ * sert. On refuse ce qui est à une ou deux frappes d'un mode connu, sans en
+ * être un — c'est la signature d'une faute, pas d'un choix.
+ *
+ * @param env - l'environnement demandé.
+ * @returns le mode dont il est probablement une coquille, sinon `null`.
+ */
+export declare function likelyTypo(env: string): string | null;
+export declare function resolveStrict(word: boolean | undefined, env: Record<string, string | undefined>): boolean;
+/**
+ * Parse l'argv après le mot `check` (ou son alias `doctor`).
+ *
+ * La borne est le mot de commande, pas la position : le fast-path passe
+ * `process.argv` entier (`node`, chemin du binaire, `check`, …) tandis que le
+ * filet de {@link Check.generate} ne passe que les options. Sans mot de
+ * commande, tout l'argv reçu est donc considéré comme des options.
+ */
+export declare function parseDoctorArgv(argv: string[]): ICheckRequest | {
+    error: string;
+};
+/**
+ * Lance le contrôle et écrit le rapport.
+ *
+ * **La cible est l'APPLICATION, pas le dossier courant.** On remonte donc au
+ * premier dossier qui porte `nodefony.config.ts` (`findProjectRoot`, la même
+ * définition de « où commence l'app » que le lanceur et les scaffolds). Sans
+ * cette remontée, un `check` lancé dans `modules/blog/` ne trouvait ni le
+ * manifeste, ni le bilan du dernier démarrage, et concluait « rien à
+ * signaler » — le pire mode de défaillance pour un outil de diagnostic :
+ * silencieux, et rassurant à tort.
+ *
+ * Hors de tout projet, on retombe sur le dossier de départ : ce dépôt-ci et
+ * n'importe quel dossier de paquets restent contrôlables tels quels.
+ *
+ * @param argv - ligne de commande (`--json`, `--cwd <path>`).
+ * @returns le code de sortie : 0 si rien à signaler, 1 sinon, 64 (`EX_USAGE`)
+ *          sur une option inconnue. La trace d'un démarrage échoué est
+ *          RAPPORTÉE mais ne pèse pas sur ce code.
+ */
+/**
+ * Rapport de diagnostic statique, tel que toutes les portes le lisent.
+ *
+ * C'est exactement le document que `check --json` imprime : la commande n'en
+ * possède aucune version privée. Ce qui compte, c'est qu'une deuxième porte
+ * (le serveur MCP) rende le MÊME objet — un diagnostic qui différerait selon
+ * l'outil qui le demande serait pire qu'aucun diagnostic.
+ */
+export interface IDoctorReport {
+    /** Racine de l'application effectivement contrôlée. */
+    root: string;
+    /** `nom version` tel que le manifeste le déclare — vide s'il ne dit rien. */
+    appName: string;
+    /** Nombre de paquets parcourus. */
+    scanned: number;
+    /** Manquements de dépendances. */
+    findings: ReturnType<typeof checkPackageDeps>["findings"];
+    /** Manquements de câblage, avec le nombre de classes contrôlées. */
+    wiring: {
+        scanned: number;
+        findings: ReturnType<typeof checkWiring>["findings"];
+    };
+    /** Ce qui manque ICI et maintenant (env, modules, deps, ports). */
+    readiness: IReadinessResult;
+    /** Écarts entre ce qui est ÉCRIT et ce qui s'EXÉCUTERA (build, plancher Node). */
+    freshness: IFreshnessResult;
+    /**
+     * Ce qui est atteignable SANS authentification, et les entités hors dialecte.
+     *
+     * L'inventaire des ouvertures est une INFORMATION : chacune est légitime
+     * prise isolément, et c'est de ne les voir jamais ENSEMBLE qu'une route de
+     * mise au point reste ouverte en production.
+     */
+    surface: ISurfaceResult;
+    /**
+     * Les filets du projet — sont-ils ARMÉS ?
+     *
+     * Aucune occurrence de code n'est signalée ici : le linter le fait déjà, et
+     * mieux. Ce qui manquait, c'est de constater que la garde EXISTE — un filet
+     * décroché ne fait pas de bruit.
+     */
+    guards: IGuardResult;
+    /**
+     * Étage 3 — ce que le projet DÉCLARE, réellement lancé (`--deep`).
+     *
+     * `null` quand l'étage n'a pas été demandé : l'absence de résultat et un
+     * résultat vide ne se confondent pas, et c'est l'état d'exécution qui le dit
+     * au lecteur plutôt qu'un silence.
+     *
+     * ## Ce qu'un appelant de `--json` y trouve
+     *
+     * ```json
+     * "deep": {
+     *   "steps": [
+     *     { "step": "typecheck", "outcome": "passed", "ms": 809 },
+     *     { "step": "lint", "outcome": "failed", "ms": 784,
+     *       "detail": "src/a.ts:1:1: warning no-unused-vars" }
+     *   ],
+     *   "outdated": { "packages": [], "ahead": [], "counts": { "major": 0, … } },
+     *   "outdatedReason": ""
+     * }
+     * ```
+     *
+     * - `outcome` vaut `passed` · `failed` · `timeout` · `absent`. **`absent`
+     *   n'est pas un échec** : le script n'est pas déclaré par le projet, et
+     *   c'est la famille `guards` qui en répond. **`timeout` non plus n'est pas
+     *   un succès** : le script a été tué par la borne de temps, et le lire
+     *   comme un `passed` est l'erreur que ce champ existe pour empêcher.
+     * - `detail` porte la PREMIÈRE LIGNE UTILE de la sortie, l'annonce de npm
+     *   sautée. Absent quand le script s'est tu.
+     * - `outdated` vaut `null` quand le registre n'a pas répondu ; `outdatedReason`
+     *   dit alors pourquoi. Un registre muet n'est PAS un défaut de
+     *   l'application, et rien n'en est déduit.
+     * - En `--json`, **aucune progression n'est émise sur aucun canal** : stdout
+     *   ne porte que ce document, stderr reste vide.
+     */
+    deep: IDeepResult | null;
+    /**
+     * Les bilans de démarrage disponibles — serveur d'abord, console ensuite.
+     *
+     * DEUX, et pas un : un `nodefony inspect` lancé POUR diagnostiquer une panne
+     * de serveur écrasait le bilan qu'il venait lire. Chacun dit désormais QUI a
+     * démarré (`profile`) et par quelle commande.
+     */
+    lastBoots: ILastBoot[];
+    /** Exceptions déclarées, comptées dans le rendu humain. */
+    exceptions: number;
+    /**
+     * Ce que l'application DÉMARRÉE a dit d'elle-même — absent sans `--live`.
+     *
+     * Séparé du reste parce qu'il n'a pas la même nature : tout ce qui précède
+     * se lit sur des fichiers et répond donc même quand l'application ne démarre
+     * plus. Ceci exige un boot, et son absence est ÉNONCÉE dans `execution`
+     * plutôt que devinée d'un champ manquant.
+     */
+    live?: ILiveResult;
+    /**
+     * Ce que chaque famille a pu — ou n'a PAS pu — regarder.
+     *
+     * Porté par le rapport lui-même, donc identique dans toutes les portes : un
+     * agent qui lit ce document par MCP voit les mêmes angles morts que l'humain
+     * devant son terminal. C'est la moitié du diagnostic que l'absence de
+     * manquements ne dit pas.
+     */
+    execution: Record<DoctorFamily, IExecution>;
+}
+/**
+ * Collecte le diagnostic — sans rien imprimer.
+ *
+ * Séparé du rendu pour la même raison que la table des sujets d'`inspect` :
+ * dès qu'une deuxième porte existe, une collecte enfouie dans une fonction qui
+ * écrit sur la sortie standard oblige à la réécrire, et les deux divergent.
+ *
+ * ⚠️ **La cible est l'APPLICATION, pas le dossier où l'on a tapé** : on remonte
+ * au premier dossier portant `nodefony.config.ts`. Hors projet, le dossier de
+ * départ reste la cible, et l'état d'installation n'est pas contrôlé (sans
+ * manifeste ni environnement, une sonde accuserait le premier serveur venu).
+ *
+ * @param start - dossier de départ de la remontée
+ * @returns le rapport complet, sans verdict ni code de sortie
+ */
+export declare function collectDoctorReport(start: string, targetEnv?: string | null, deepRequested?: boolean, report?: DeepReporter): Promise<IDoctorReport>;
+/**
+ * Nombre total de manquements d'un rapport — le verdict, en un endroit.
+ *
+ * Délègue à {@link countFindings} : le rendu compte par la même fonction, et
+ * le bilan chiffré ne peut donc plus contredire le sommaire qui le surmonte.
+ * Ce nom reste parce qu'il a voyagé (le serveur MCP le lit).
+ */
+export declare function countCheckFindings(report: IDoctorReport): number;
+/**
+ * La ligne d'annonce d'un évènement de l'étage profond, ou `null` s'il n'y a
+ * rien à dire.
+ *
+ * Fonction PURE, pour que ce qui s'affiche pendant une attente de plusieurs
+ * minutes s'éprouve sans attendre quoi que ce soit.
+ *
+ * @param e - l'évènement annoncé par l'étage profond.
+ * @param p - la palette (couleur ou non, selon le terminal).
+ * @returns la ligne à écrire, sans retour chariot, ou `null`.
+ */
+export declare function progressLine(e: IDeepProgress, p: IPalette): string | null;
+/**
+ * Le reporter à donner à l'étage profond — ou `undefined` quand personne ne lit.
+ *
+ * 🔴 **Deux décisions, et elles ne sont pas cosmétiques.**
+ *
+ * *Le canal* : la progression part sur la sortie d'ERREUR, jamais sur la sortie
+ * standard. Celle-ci porte le RAPPORT, que l'on redirige couramment vers un
+ * fichier (`nodefony doctor > diagnostic.txt`) ; une progression éphémère qui
+ * s'y glisserait salirait un document qu'on relit plus tard, et rendrait le
+ * `--json` inexploitable. C'est aussi la convention des outils qui annoncent
+ * leur travail — npm, cargo, docker écrivent tous leur progression sur stderr.
+ *
+ * *Le silence en `--json`* : rien n'est émis du tout, sur aucun canal. Un agent
+ * qui capture les deux flux (`2>&1`, ce que font la plupart des harnais) verrait
+ * sinon des lignes de décor tomber au milieu de son JSON. La règle est donc
+ * simple à documenter et sans exception : **`--json` n'émet aucune
+ * progression**.
+ *
+ * @param json - `true` si le rapport est demandé en JSON.
+ * @param write - où écrire (injecté : une fonction qui touche `process.stderr`
+ *   en dur ne s'éprouve que par capture globale, donc mal).
+ * @returns le reporter, ou `undefined` s'il ne faut rien annoncer.
+ */
+export declare function reporterProgression(json: boolean, write?: (line: string) => void, stream?: NodeJS.WriteStream): DeepReporter | undefined;
+export declare function runDoctorCommand(argv: string[]): Promise<number>;
+/**
+ * Greffe l'étage 2 sur un rapport statique.
+ *
+ * En UN endroit, parce que la fusion porte une règle : les deux familles de
+ * l'étage 2 sont REMPLACÉES, jamais complétées. `collectDoctorReport` les a
+ * posées à « non demandé » — les laisser à côté du vrai résultat afficherait
+ * deux états pour un seul contrôle, et le sommaire cesserait de dire la vérité.
+ *
+ * @param report - le rapport statique, tel que la lecture pure l'a produit
+ * @param live - ce que l'application démarrée a dit d'elle-même
+ * @returns un rapport neuf ; l'entrée n'est pas modifiée
+ */
+export declare function attachLive(report: IDoctorReport, live: ILiveResult): IDoctorReport;
+/**
+ * Rend le rapport et décide du code de sortie.
+ *
+ * Séparé de la collecte pour une raison précise : `doctor --live` boote, donc
+ * il compose son rapport en DEUX temps (les fichiers, puis l'application) et
+ * doit rendre le tout par le même chemin. Deux rendus pour un même document
+ * finiraient par diverger — et c'est le rendu qui porte la doctrine du verdict.
+ *
+ * @param report - le rapport complet, étage 2 greffé ou non
+ * @param parsed - la demande, telle que la ligne de commande l'a exprimée
+ * @returns le code de sortie : 0 si rien à signaler, 1 sinon
+ */
+export declare function renderDoctorReport(report: IDoctorReport, parsed: ICheckRequest, durationMs?: number): number;
+/**
+ * La commande demandée est-elle `doctor` ?
+ *
+ * L'alias historique `check` a été RETIRÉ : il ne disait pas ce qu'il vérifie,
+ * et il entrait en collision de sens avec les scripts `typecheck` et
+ * `format:check` d'une application. Aucun paquet `@nodefony/*` n'étant publié
+ * (#175), ce nom n'a jamais atteint une application installée.
+ *
+ * @param requested - le nom de commande lu sur la ligne de commande.
+ * @returns `true` pour `doctor`.
+ */
+export declare function isDoctorCommand(requested: string | null): boolean;
+/**
+ * L'invocation demande-t-elle l'étage 2 — celui qui exige un boot ?
+ *
+ * Une SEULE implémentation de la règle, parce qu'elle sert à deux endroits qui
+ * doivent s'accorder : le fast-path standalone (qui ne se prend PAS quand
+ * l'étage 2 est demandé) et le rattrapage d'un boot mort. Écrite deux fois,
+ * elle divergerait au premier drapeau ajouté — `--no-live` en est déjà un, que
+ * la lecture naïve de `argv` ignorait.
+ *
+ * @param requested - le nom de commande lu sur la ligne de commande.
+ * @param argv - la ligne de commande complète.
+ * @returns `true` si l'application doit être démarrée puis interrogée.
+ */
+export declare function wantsLiveDoctor(requested: string | null, argv: readonly string[]): boolean;
+/**
+ * Rend le rapport de `doctor` alors que l'application vient d'échouer à démarrer.
+ *
+ * 🔴 C'est le cas POUR lequel la commande existe. `--live` sort du fast-path et
+ * demande un boot : sans ce chemin, une application qui ne démarre plus rendait
+ * une pile brute et RIEN d'autre — moins que `doctor` nu. L'étage 2 devient
+ * alors un état d'exécution lisible (ce qui a manqué, et le geste), et l'étage
+ * 1 est rendu comme d'habitude, code de sortie compris.
+ *
+ * @param argv - la ligne de commande telle qu'elle a été tapée.
+ * @param reason - pourquoi l'application n'a pas pu répondre.
+ * @param unlock - le geste qui la rendrait interrogeable.
+ * @returns le code de sortie du rapport.
+ */
+export declare function runDoctorWithoutLive(argv: string[], reason: string, unlock?: string): Promise<number>;

package/dist/types/kernel/checks/surface.d.ts

@@ -0,0 +1,148 @@
+/** Ce qui rend une route ou une zone atteignable sans authentification. */
+export type OpeningKind = "bypass-firewall" | "anonymous"
+/** `bypassFirewall: true` posé à la main dans une route programmatique. */
+ | "bypass-option" | "public-area";
+/** Un point d'entrée ouvert, tel qu'il s'affiche dans l'inventaire. */
+export interface IOpening {
+    kind: OpeningKind;
+    /**
+     * Ce qui est ouvert : un nom de méthode, le motif d'une zone — ou RIEN.
+     *
+     * Vide quand le nom n'est pas littéral : une route posée dans une boucle
+     * (`Router.createRoute(name, …)`) n'a pas de nom lisible dans le source, et
+     * en inventer un serait pire que de n'en donner aucun.
+     */
+    what: string;
+    /** Le fichier qui le déclare, relatif à la racine analysée. */
+    file: string;
+}
+/** Un manquement de surface ou de dialecte. */
+export interface ISurfaceFinding {
+    kind: "public-area-covers-all" | "entity-other-dialect";
+    message: string;
+    file: string;
+}
+/** Ce que le contrôle a relevé. */
+export interface ISurfaceResult {
+    findings: ISurfaceFinding[];
+    /** L'inventaire — une INFORMATION, jamais un verdict. */
+    openings: IOpening[];
+    /** Fichiers de source parcourus. */
+    scanned: number;
+    /** Le dialecte du connecteur, tel qu'on a pu le déterminer. */
+    dialect: SqlDialectName | null;
+    /** D'où vient ce dialecte, pour que le lecteur puisse le contredire. */
+    dialectFrom: string;
+    /** Entités relevées, tous dialectes confondus. */
+    entitiesScanned: number;
+}
+/** Les moteurs qu'une entité peut viser. */
+export type SqlDialectName = "sqlite" | "postgres" | "mysql";
+export interface ISurfaceCheckOptions {
+    /** Cibles à explorer : une application, et ses `modules/*`. */
+    roots: string[];
+    /** Racine servant à raccourcir les chemins affichés. */
+    cwd: string;
+    /** Racine du PROJET — c'est elle qui porte le manifeste. */
+    projectRoot?: string;
+    /**
+     * L'environnement, d'où l'on tire l'infrastructure déclarée.
+     *
+     * Injecté : une fonction qui lit `process.env` ne s'éprouve que dans
+     * l'environnement où elle tourne.
+     */
+    env: Record<string, string | undefined>;
+    /**
+     * Les chemins d'entités dont le dialecte divergent est ASSUMÉ.
+     *
+     * Déclarés par le projet (`package.json` → `nodefony.doctor.entityDialect`).
+     * Sans cette porte, un dépôt qui porte volontairement des entités
+     * multi-moteurs — un banc de portabilité, par exemple — ne peut jamais être
+     * vert, et c'est le contrôle entier qu'on finit par ignorer.
+     */
+    dialectExceptions?: readonly string[];
+}
+/**
+ * Ce motif de zone laisse-t-il passer TOUT l'espace d'URL ?
+ *
+ * CONSTATÉ, jamais listé : le motif est compilé et éprouvé exactement comme le
+ * firewall le fait (`SecuredArea.ts:25` — `new RegExp(pattern, "u")`, non
+ * ancré, `test(pathname)`), puis confronté à des chemins sans parenté. Une
+ * liste écrite à la main disait le contraire du produit dans les deux sens :
+ * elle CONDAMNAIT `^/api`, qui ne couvre que `/api…`, et laissait passer
+ * `^/.*`, `.*` et `^`, qui ouvrent réellement tout.
+ *
+ * @param pattern - le motif tel que le manifeste l'écrit.
+ * @returns `true` si aucune route ne peut échapper à cette zone.
+ */
+export declare function coversEverything(pattern: string): boolean;
+/**
+ * Le contenu d'un bloc d'accolades ÉQUILIBRÉES à partir d'une position.
+ *
+ * Une expression régulière ne sait pas compter les accolades : un bloc `areas`
+ * contenant une zone qui contient ses authentificateurs se ferait couper au
+ * premier `}` venu, et la moitié des zones deviendrait invisible — un contrôle
+ * de surface qui ne voit qu'une partie de la surface est pire qu'aucun.
+ *
+ * @param source - le texte à lire.
+ * @param open - l'index de l'accolade ouvrante.
+ * @returns le contenu entre les accolades, vide si elles ne se referment pas.
+ */
+export declare function balancedBlock(source: string, open: number): string;
+/**
+ * Les zones publiques déclarées dans un manifeste.
+ *
+ * Fonction PURE sur le TEXTE du manifeste : c'est ce qui la rend éprouvable
+ * sans écrire de fichier, et ce qui lui permet de répondre sur un manifeste que
+ * TypeScript refuserait de compiler.
+ *
+ * @param manifest - le contenu de `nodefony.config.ts`.
+ * @returns une entrée par zone `security: false`, avec son motif.
+ */
+export declare function publicAreas(manifest: string): {
+    pattern: string;
+}[];
+/**
+ * Le dialecte du connecteur, tel qu'on peut le déterminer SANS démarrer.
+ *
+ * Trois sources, dans l'ordre de précédence du produit : l'infrastructure
+ * déclarée gagne (un hébergeur pose l'URL), puis ce que le manifeste écrit,
+ * puis le défaut du module. La provenance est RENDUE avec la valeur : un
+ * dialecte affirmé sans dire d'où il vient ne se contredit pas.
+ *
+ * @param manifest - le contenu de `nodefony.config.ts`.
+ * @param env - l'environnement dans lequel le diagnostic tourne.
+ * @returns le dialecte et sa provenance, `null` si rien ne le dit.
+ */
+export declare function connectorDialect(manifest: string, env: Record<string, string | undefined>): {
+    dialect: SqlDialectName | null;
+    from: string;
+};
+/**
+ * Réécrit un chemin en séparateurs `/`, quelle que soit sa grammaire d'origine.
+ *
+ * 🔴 **Axiome 2 : normaliser AVANT de filtrer ou comparer.** Une exception de
+ * dialecte est un chemin qui VOYAGE — elle vient de la configuration du projet,
+ * écrite une fois et lue sur les trois systèmes, donc en `/`. Le chemin auquel
+ * on la compare sort de `path.relative` : sous Windows il porte des `\`. Le
+ * filtre ne mordait donc jamais là-bas, et une divergence pourtant DÉCLARÉE
+ * par le projet était accusée — forge Windows rouge, même passe verte ailleurs.
+ *
+ * Les DEUX séparateurs sont traités, pas seulement celui du poste : rien ne dit
+ * que l'exception n'a pas été écrite avec la grammaire de la machine où elle a
+ * été ajoutée.
+ *
+ * @param rawPath - le chemin à normaliser.
+ * @param sep - la grammaire à appliquer ; injectée pour que la règle
+ *   s'éprouve avec `path.win32.sep` depuis n'importe quel système — sans elle,
+ *   le cas Windows ne serait vérifiable que sous Windows.
+ * @returns le même chemin, en `/`.
+ */
+export declare function toPortablePath(rawPath: string, sep?: string): string;
+/**
+ * Relève la surface ouverte et les entités hors dialecte.
+ *
+ * @param options - cibles, racine du projet, environnement, exceptions.
+ * @returns l'inventaire, les manquements, et ce qui a été parcouru.
+ */
+export declare function checkSurface(options: ISurfaceCheckOptions): ISurfaceResult;

package/dist/types/kernel/checks/walk.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Les dossiers dans lesquels aucun contrôle n'entre.
+ *
+ * Trois familles, et chacune a son motif : ce qui est INSTALLÉ
+ * (`node_modules`), ce qui est PRODUIT (`dist`, `coverage`, `.turbo`, `tmp`,
+ * `var`), et ce qui n'est ni servi ni publié (`tests`, `test`, `__tests__`).
+ * Tout dossier commençant par un point est écarté en plus, par
+ * {@link isSkippedDir}.
+ */
+export declare const SKIPPED_DIRS: ReadonlySet<string>;
+/**
+ * Ce dossier est-il hors de portée de tout contrôle ?
+ *
+ * @param name - le nom du dossier, sans son chemin.
+ * @returns `true` s'il ne faut pas y entrer.
+ */
+export declare function isSkippedDir(name: string): boolean;
+/**
+ * Ce fichier est-il un test ?
+ *
+ * Reconnaît `x.test.ts` et `x.spec.ts`, dans toutes les extensions de source.
+ * Un test n'est ni servi, ni publié, ni bâti : aucun contrôle n'a de raison de
+ * le compter, et chacun en avait sa propre définition.
+ *
+ * @param name - le nom du fichier, ou un chemin.
+ * @returns `true` s'il s'agit d'un test.
+ */
+export declare function isTestFile(name: string): boolean;
+/** Ce que l'appelant choisit — le reste est commun à tous les contrôles. */
+export interface IWalkOptions {
+    /** Extensions retenues, point compris (ex. `[".ts", ".tsx"]`). */
+    extensions: readonly string[];
+    /** Sous-dossiers à explorer plutôt que la racine entière. */
+    subdirs?: readonly string[];
+    /** Profondeur maximale, à partir de la racine explorée. */
+    maxDepth?: number;
+}
+/**
+ * Les fichiers de source d'une cible, tests et dossiers produits exclus.
+ *
+ * @param root - racine à explorer.
+ * @param options - extensions retenues, et ce qui restreint le parcours.
+ * @returns les chemins absolus, dans l'ordre du système de fichiers.
+ */
+export declare function collectSources(root: string, options: IWalkOptions): string[];

package/dist/types/kernel/checks/wiring.d.ts

@@ -0,0 +1,54 @@
+/** Un câblage manquant, ou un nom qui dépossède un module du framework. */
+export interface IWiringFinding {
+    kind: "orphan-entity" | "orphan-controller" | "orphan-service" | "reserved-entity" | "missing-brick" | "route-colon-param" | "reponse-a-la-main" | "firewall-area-enumere" | "hook-lifecycle-inconnu";
+    /** Phrase lisible, déjà orientée vers la correction. */
+    message: string;
+    /** Fichier fautif, relatif à la racine analysée. */
+    file: string;
+}
+export interface IWiringCheckOptions {
+    /** Cibles à explorer : une application, et ses `modules/*`. */
+    roots: string[];
+    /** Racine servant à raccourcir les chemins affichés. */
+    cwd?: string;
+    /**
+     * Racine du PROJET — c'est elle qui porte le manifeste des modules.
+     *
+     * Distincte des cibles : un module vit dans `modules/blog`, mais la brique
+     * dont son code dépend se déclare dans le `nodefony.config.ts` de
+     * l'application. Absente, le contrôle des briques est simplement sauté.
+     */
+    projectRoot?: string;
+}
+export interface IWiringCheckResult {
+    findings: IWiringFinding[];
+    /** Nombre de fichiers d'entité et de controller réellement analysés. */
+    scanned: number;
+}
+/**
+ * Contrôle le câblage d'une application et de ses modules locaux.
+ *
+ * Trois manquements, tous invisibles à la compilation :
+ *
+ * - **entité orpheline** — le descripteur n'est nommé nulle part, donc aucun
+ *   `@entities([…])` ne l'enregistre : sa table ne sera pas créée ;
+ * - **controller orphelin** — la classe n'est nommée nulle part, donc aucune de
+ *   ses routes n'est montée ;
+ * - **service orphelin** — la classe porte `@injectable` mais n'apparaît dans
+ *   aucun `@services([…])` ni enregistrement impératif. Seul manquement dont
+ *   le critère n'est PAS « quelqu'un te nomme » : un service non déclaré est
+ *   presque toujours nommé — par le controller qui le reçoit en paramètre. Le
+ *   framework l'auto-résout alors depuis le registre des classes, ce qui donne
+ *   une application qui fonctionne et un service qui n'existe pour personne
+ *   d'autre : hors ordre de démarrage, hors rapport de boot, hors politique
+ *   d'erreur, hors introspection, construit à la première requête ;
+ * - **nom réservé** — l'entité porte le nom d'une entité d'un module du
+ *   framework (`User`, `session`…). Le registre ORM est PLAT : l'homonyme
+ *   dépossède le module, et l'application s'arrête au démarrage sur un message
+ *   qui parle d'une colonne inconnue, jamais du doublon. Le registre est celui
+ *   du scaffold ({@link findReservedEntity}), pas une seconde liste.
+ *
+ * @param options - cibles à explorer et racine d'affichage.
+ * @returns les manquements et le nombre de fichiers analysés.
+ */
+export declare function checkWiring(options: IWiringCheckOptions): IWiringCheckResult;

package/dist/types/kernel/commands/AiMcpCommand.d.ts

@@ -0,0 +1,39 @@
+import Command from "../../command/Command.js";
+import CliKernel from "../CliKernel.js";
+/**
+ * Commande `nodefony ai:mcp` — déclare le serveur MCP de cette application à
+ * l'agent (`.mcp.json`).
+ *
+ * **Exécutée en « standalone » (zéro boot).** L'enregistrement ici sert au help
+ * (`nodefony --help`) et à la complétion ; l'exécution réelle est interceptée
+ * par le fast-path de {@link CliKernel.start} — elle n'écrit qu'un fichier de
+ * câblage, le serveur MCP étant une ROUTE de l'application. Le `generate()`
+ * ci-dessous n'est qu'un FILET.
+ *
+ * @example
+ * ```bash
+ * nodefony ai:mcp             # écrit/actualise .mcp.json
+ * nodefony ai:mcp --dry-run   # le plan, sans rien écrire
+ * nodefony ai:mcp --auth      # mode authentifié (en-tête ${NF_MCP_TOKEN})
+ * nodefony ai:mcp --agent gemini,codex   # déclare AUSSI la porte via LEUR CLI
+ * nodefony ai:mcp --agent all --remove   # la retire partout
+ * ```
+ *
+ * `--agent` accepte `none` — et en interactif, ne rien cocher revient au même :
+ * coder sans agent est un choix, pas un oubli qu'il faudrait rattraper.
+ */
+declare class AiMcp extends Command {
+    constructor(cli: CliKernel);
+    generate(opts?: {
+        auth?: boolean;
+        noAuth?: boolean;
+        agent?: string;
+        remove?: boolean;
+        global?: boolean;
+        url?: string;
+        dryRun?: boolean;
+        json?: boolean;
+        cwd?: string;
+    }): Promise<this>;
+}
+export default AiMcp;

package/dist/types/kernel/commands/AiSyncCommand.d.ts

@@ -0,0 +1,28 @@
+import Command from "../../command/Command.js";
+import CliKernel from "../CliKernel.js";
+/**
+ * Commande `nodefony ai:sync` — pointeurs vers les skills d'agent livrés par
+ * les paquets installés.
+ *
+ * **Exécutée en « standalone » (zéro boot).** L'enregistrement ici sert au help
+ * (`nodefony --help`) et à la complétion ; l'exécution réelle est interceptée
+ * par le fast-path de {@link CliKernel.start} — portée par un module
+ * `policy: "dev"`, elle n'existerait pas dans un terminal sans `NODE_ENV`,
+ * et c'est exactement ce que le fast-path évite. Le `generate()` ci-dessous
+ * n'est qu'un FILET.
+ *
+ * @example
+ * ```bash
+ * nodefony ai:sync            # pose/rafraîchit .agents/skills + miroir .claude/skills
+ * nodefony ai:sync --dry-run  # le plan, sans rien écrire
+ * ```
+ */
+declare class AiSync extends Command {
+    constructor(cli: CliKernel);
+    generate(opts?: {
+        dryRun?: boolean;
+        json?: boolean;
+        cwd?: string;
+    }): Promise<this>;
+}
+export default AiSync;