nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,545 @@
+import { findProjectRoot } from "../projectRoot.js";
+import { type TEntityDialect, type TEntityIdKind, type IEntityField } from "./entityFields.js";
+import { ScaffoldWriter, type IScaffoldChange } from "./writer.js";
+import { type IScaffoldTypeSpec, type TDatabaseChoice, type TFrontendChoice } from "./spec.js";
+/**
+ * Moteur de scaffold — PUR : réponses validées → fichiers écrits. Aucune I/O
+ * terminal, aucun kernel : le même moteur sert le CLI rapide (argv), le CLI
+ * interactif (readline) et Studio (endpoint data plane). Rendu par **eta**
+ * (dep runtime du core) : les choix (preset × frontend) exigent des
+ * conditionnels dans `package.json`/`nodefony.config.ts` — des overlays de
+ * fichiers entiers n'auraient pas tenu deux axes croisés.
+ */
+/**
+ * Réponses d'un scaffold, complétées et validées contre la spec.
+ *
+ * Le tableau de chaînes sert les questions de type `"list"` — plusieurs valeurs
+ * qui doivent rester DISTINCTES. Les fondre dans le type texte reviendrait à les
+ * concaténer, et deux index de deux colonnes deviendraient un index de quatre.
+ */
+export type TScaffoldAnswers = Record<string, string | boolean | string[]>;
+/** Capacités d'environnement évaluées par le front (cf `IScaffoldQuestion.askIf`). */
+export interface IScaffoldCaps {
+    hasCheckout: boolean;
+}
+export interface IScaffoldRequest {
+    type: string;
+    answers: TScaffoldAnswers;
+    /** Dossier cible complet (défaut : `./<name>` relatif au cwd de l'appelant). */
+    dir: string;
+    force: boolean;
+}
+export interface IScaffoldResult {
+    dest: string;
+    /** Chemins relatifs écrits (triés). */
+    files: string[];
+    /** Paquets nodefony câblés en `file:` (mode link). */
+    linked: string[];
+    /** Points d'entrée utiles du scaffold (routes, canaux…) — affichés tels quels. */
+    notes?: string[];
+    /**
+     * Dépendances AJOUTÉES au `package.json` du projet par cette génération.
+     *
+     * Le fait remonte plutôt que de rester dans une note en français : c'est lui
+     * qui décide s'il faut installer. Déclarer sans installer est un demi-geste —
+     * la commande suivante échoue alors sur un paquet que le manifeste annonce,
+     * et l'utilisateur répare à la main ce que le générateur savait faire.
+     */
+    depsAdded?: string[];
+    /**
+     * Écritures PRÉVUES, avec l'ancien contenu quand il y en a un — présent
+     * uniquement en dry-run (rien n'a touché le disque).
+     */
+    changes?: IScaffoldChange[];
+    /**
+     * Fichiers formatables laissés SANS mise en forme, faute de prettier dans le
+     * projet (cas courant : `--no-install`). Zéro dès qu'il est là — le CLI ne
+     * parle que quand ça compte.
+     */
+    unformatted?: number;
+}
+/** Options d'exécution d'un scaffold (cf {@link runScaffold}). */
+export interface IScaffoldRunOptions {
+    /**
+     * Ne rien écrire : le scaffold se déroule entièrement (gardes comprises) et
+     * rend son plan dans `result.changes`. Un refus reste un refus — c'est le but,
+     * une simulation qui ne validerait pas ne servirait à rien.
+     */
+    dryRun?: boolean;
+    /**
+     * Transaction déjà ouverte par un scaffold APPELANT (`create module` délègue
+     * à `controller`/`front`). Le sous-scaffold y écrit sans committer : la
+     * décision de vider sur disque appartient au scaffold racine, sinon la
+     * transaction serait coupée en morceaux et le refus tardif d'une étape
+     * laisserait les précédentes écrites.
+     */
+    writer?: ScaffoldWriter;
+}
+/**
+ * Paramètres frontend par framework — type registerEntry, entry, nœud de
+ * montage, ET les dépendances npm (SOURCE UNIQUE : consommée par le
+ * `package.json.tpl` de `create app` ET par `create front` qui les ajoute au
+ * package.json d'une cible existante — une version ne vit qu'ici).
+ *
+ * ⚠️ **Le framework front lui-même est une devDependency, et `deps` est vide.**
+ * Le test qui tranche est le même que pour la toolchain : *le paquet est-il
+ * importé au RUNTIME du serveur ?* Ici non — aucun fichier hors `frontend/`
+ * n'importe `react`/`vue`/`@angular/*` : Vite les inline dans le bundle
+ * navigateur, et c'est ce bundle que la production sert. Les déclarer en
+ * `dependencies` les faisait survivre au `npm prune --omit=dev` de l'image et
+ * embarquer un framework entier que rien ne charge (mesuré ailleurs : 26,6 Mo
+ * pour `vue` seul, y compris dans une app React).
+ *
+ * L'ordre du `Dockerfile` généré est ce qui rend la bascule sûre :
+ * `RUN npm run build && npm prune --omit=dev` — le build les a quand il en a
+ * besoin, le prune les retire ensuite. Toute recette qui élaguerait AVANT de
+ * construire casserait, et c'est vrai de n'importe quelle devDependency.
+ *
+ * `deps` reste dans le contrat : le jour où un rendu côté serveur importera
+ * vraiment le framework, c'est là que la déclaration devra revenir.
+ */
+export declare const FRONTEND_PARAMS: Record<Exclude<TFrontendChoice, "none">, {
+    type: string;
+    entry: string;
+    mountNode: string;
+    deps: Record<string, string>;
+    devDeps: Record<string, string>;
+}>;
+/**
+ * Paramètres de la base SQL retenue au scaffold — SOURCE UNIQUE du service
+ * docker, du port publié et de l'URL de connexion, consommée par les TROIS
+ * gabarits qui en parlent (`compose.yaml`, `.env`, `README.md`).
+ *
+ * Pourquoi ici plutôt que recopié en eta : ces valeurs doivent coïncider EXACTEMENT
+ * — l'URL du `.env` joint le port que le compose publie, et le README montre la
+ * même. Trois littéraux séparés divergent au premier réglage, et l'écart ne se
+ * voit qu'à la connexion refusée.
+ *
+ * ⚠️ **MySQL est publié sur 3306, pas 3307.** Le port décalé n'existait que pour
+ * faire cohabiter MySQL et MariaDB dans un compose qui portait les deux ; une
+ * app qui retient UN dialecte n'a plus rien avec quoi cohabiter, et un port
+ * inattendu est une friction gratuite.
+ */
+export declare const DATABASE_PARAMS: Record<Exclude<TDatabaseChoice, "sqlite">, {
+    /** Nom du service dans le compose (et suffixe du container_name). */
+    service: string;
+    /** Libellé humain — README et commentaires du compose. */
+    label: string;
+    /** Scheme de `NF_DATABASE_URL` : c'est LUI qui décide du dialecte de l'ORM. */
+    scheme: string;
+    /** Port publié sur 127.0.0.1 (l'app tourne sur l'hôte). */
+    port: number;
+    /**
+     * Image docker — SOURCE UNIQUE : consommée par `compose.yaml.tpl` ET par
+     * le `ci.yml.tpl` (service container GitHub). Écrite en dur dans chacun,
+     * elle divergerait au premier bump sans qu'aucun des deux ne le dise.
+     */
+    image: string;
+}>;
+/**
+ * Compose le bloc `db` offert aux gabarits — `null` pour sqlite, qui n'a ni
+ * service ni URL (le fichier vit dans `var/databases/`, l'ORM s'en charge seul).
+ */
+export declare function resolveDatabase(choice: TDatabaseChoice, appName: string): {
+    choice: string;
+    service: string;
+    label: string;
+    scheme: string;
+    port: number;
+    url: string;
+    database: string;
+    databaseE2e: string;
+    databaseScratch: string;
+    urlE2e: string;
+    urlScratch: string;
+} | null;
+/**
+ * Racine du paquet `nodefony` contenant `templates/` — remontée depuis CE fichier
+ * (source `src/cli/scaffold/`, bundle `dist/node/cli/scaffold/` : la remontée
+ * marche pour les deux sans dépendre de la profondeur).
+ */
+export declare function findPackageRoot(): string;
+/**
+ * Workspaces nodefony d'un CHECKOUT du repo (`src/nodefony` + `src/packages/@nodefony/*`),
+ * résolus depuis la racine du paquet `nodefony`. Un paquet INSTALLÉ (node_modules)
+ * n'a pas ce voisinage → `null` (le mode link n'a de sens que sur un checkout).
+ */
+export declare function resolveLocalWorkspaces(packageRoot: string): Record<string, string> | null;
+/**
+ * Mode link : réécrit dans le `package.json` GÉNÉRÉ toute dep `nodefony` /
+ * `@nodefony/*` en `file:<workspace>` — `npm install` symlinke le checkout local
+ * et installe ses deps transitives. Rend l'app contrôlable AVANT toute release
+ * npm (dev du framework) ; les deps publiques (zod, react…) restent au registre.
+ *
+ * @returns les noms de paquets liés (triés, pour le récap)
+ * @throws si une dep du scope nodefony n'existe pas dans le checkout
+ */
+export declare function linkLocalDeps(destDir: string, workspaces: Record<string, string>, writer: ScaffoldWriter): string[];
+/**
+ * Complète et VALIDE des réponses partielles contre la spec d'un type : défauts
+ * appliqués, patterns vérifiés, choix contraints à leur liste. Le contexte des
+ * templates est donc complet PAR CONSTRUCTION (eta ne rend jamais un `undefined`
+ * silencieux). Les questions `askIf` non satisfaites sont forcées à `false` ;
+ * celles dont l'`askWhen` n'est pas satisfait retombent à leur DÉFAUT — une
+ * réponse qui porte sur ce qui ne sera pas généré n'a rien à décider.
+ *
+ * L'ordre de la spec fait foi : une question `askWhen` lit la réponse DÉJÀ
+ * résolue de celle qu'elle désigne, donc cette dernière doit la précéder.
+ *
+ * @throws Error si une valeur viole la spec (message = libellé + attendu)
+ */
+export declare function resolveAnswers(spec: IScaffoldTypeSpec, partial: TScaffoldAnswers, caps: IScaffoldCaps): TScaffoldAnswers;
+/**
+ * Pose le fichier-POINTEUR d'instructions des agents donnés, s'il manque.
+ *
+ * Extrait de {@link renderProjectAgents} pour être appelable AILLEURS : c'est
+ * `nodefony ai:mcp --agent <clé>` qui câble un agent après la création de
+ * l'application, et c'est donc là que son pointeur doit apparaître. Sans cette
+ * fonction, filtrer les pointeurs à la création (pour ne plus déposer un
+ * `GEMINI.md` chez qui a demandé Claude) aurait privé de son fichier tout agent
+ * ajouté ensuite — on aurait remplacé un défaut par un autre.
+ *
+ * Un pointeur DÉJÀ présent n'est jamais réécrit : celui qu'un développeur a
+ * remplacé lui appartient.
+ *
+ * @param projectRoot - racine de l'application.
+ * @param keys - clés des agents concernés.
+ * @param appName - nom de l'application (rendu dans le gabarit).
+ * @returns les fichiers réellement écrits, relatifs à la racine.
+ */
+export declare function writeAgentPointers(projectRoot: string, keys: readonly string[], appName: string): string[];
+/**
+ * Racine du PROJET Nodefony courant — cible des scaffolds IN-PROJECT (controller,
+ * module, entity), par opposition à `create app` qui crée un dossier neuf.
+ *
+ * Ré-export : la définition vit dans `../projectRoot` (module sans dépendance),
+ * partagée avec le lanceur `bin/nodefony` qui s'en sert pour déléguer au CLI de
+ * l'app. Une seule définition de « où commence l'app ».
+ */
+export { findProjectRoot };
+/** Cible d'un scaffold in-project : l'app racine ou un module du projet. */
+export interface IScaffoldTarget {
+    kind: "app" | "module";
+    /** Nom affichable (package.json `name`). */
+    name: string;
+    /** Dossier du code (contient `index.ts` + `nodefony/`). */
+    dir: string;
+}
+/**
+ * Cibles de scaffold du projet : l'app racine + les modules locaux
+ * (`modules/<x>/` portant `package.json` + `index.ts` — le layout produit par
+ * `create module`). Consommée par le CLI (validation `--module`) et par le
+ * futur formulaire Studio (liste de choix dynamique par projet).
+ */
+/**
+ * Capacités de l'environnement, telles que le MOTEUR les voit.
+ *
+ * Sert aux questions conditionnelles (`askIf`) : `link` (créer une app branchée sur le
+ * checkout local du framework, au lieu des paquets npm publiés) n'a de sens que si un
+ * checkout est résolvable. Un front ne peut PAS le deviner — seul le serveur sait ce
+ * qu'il y a sur le disque. Le figer côté client à `false` reviendrait à supprimer
+ * l'option en silence.
+ *
+ * @returns les capacités passées à {@link resolveAnswers}.
+ */
+export declare function scaffoldCaps(): IScaffoldCaps;
+/**
+ * Ce que le PROJET RÉEL offre comme choix à un scaffold, sans démarrer le noyau.
+ *
+ * Une question dont les réponses valides dépendent du projet ne peut pas être
+ * décrite par la spec seule : les connecteurs déclarés, les entités déjà créées
+ * et les types de colonnes réellement disponibles varient d'une application à
+ * l'autre. Sans ce contexte, chaque front redemande la même chose en texte
+ * libre — et une faute de frappe ne se voit qu'au démarrage suivant.
+ *
+ * Le calcul vit ici, au moteur, et pas dans Studio : un formulaire intelligent
+ * écrit côté navigateur ne profiterait ni au terminal ni à un agent, et
+ * dériverait du projet réel à la première évolution.
+ */
+export interface IScaffoldContext {
+    /** Cibles possibles : l'application racine et ses modules locaux. */
+    targets: IScaffoldTarget[];
+    /** Connecteurs déclarés, avec le moteur SQL de chacun. */
+    connectors: IScaffoldConnector[];
+    /**
+     * Types de champ disponibles, et ce qu'ils deviennent dans CHAQUE moteur.
+     *
+     * La traduction est montrée plutôt que promise : `json` devient `jsonb` en
+     * PostgreSQL et une colonne texte en SQLite, et c'est une information dont
+     * dépend le choix de celui qui modélise.
+     */
+    columnTypes: Array<{
+        /** Nom du type dans le vocabulaire Nodefony. */
+        type: string;
+        /** Colonne Drizzle produite, par dialecte. */
+        byDialect: Record<string, string>;
+    }>;
+    /** Entités existantes par cible — ce que `ref:` peut viser. */
+    entities: Record<string, string[]>;
+    /** Stratégies de clé primaire proposées. */
+    idKinds: readonly string[];
+}
+/**
+ * Lit le contexte du projet contenant `dir`.
+ *
+ * @param dir - un dossier quelconque du projet (la racine est retrouvée seule).
+ * @param writer - accès fichiers (injectable pour les tests).
+ * @returns le contexte, ou `null` si `dir` n'est pas dans un projet Nodefony.
+ */
+export declare function getScaffoldContext(dir: string, writer?: ScaffoldWriter): IScaffoldContext | null;
+export declare function listTargets(projectRoot: string, writer?: ScaffoldWriter): IScaffoldTarget[];
+/** `blog-post` / `BlogPost` / `blogPost` → `BlogPost`. */
+export declare function toPascalCase(name: string): string;
+/** `BlogPost` / `blog_post` → `blog-post`. */
+export declare function toKebabCase(name: string): string;
+export declare function wireDecoratorList(indexPath: string, decorator: "controllers" | "entities" | "services", className: string, importPath: string, writer: ScaffoldWriter): void;
+/**
+ * Exécute un scaffold — point d'entrée UNIQUE des trois fronts (CLI rapide,
+ * CLI interactif, Studio), dispatché par type :
+ *  - `app` : projet NEUF dans `request.dir` (layers base/preset/frontend) ;
+ *  - `controller` : IN-PROJECT — `request.dir` est le point de départ de la
+ *    détection de racine (cwd de l'appelant), la cible réelle vient de
+ *    `answers.module` (vide = app racine).
+ *
+ * Toutes les écritures passent par une TRANSACTION ({@link ScaffoldWriter}) que
+ * seul le scaffold RACINE vide sur disque, une fois toutes les étapes passées :
+ * un refus, même tardif, ne laisse donc jamais de projet à moitié modifié. Et
+ * comme la simulation n'est que « la même exécution sans vidage », `dryRun`
+ * décrit exactement ce qui se passerait — pas ce qu'un second code de
+ * prévision croirait.
+ *
+ * @returns fichiers écrits + paquets liés — l'appelant décide du rendu (CLI ou JSON)
+ * @throws Error si réponses invalides, dossier non vide sans force, ou template cassé
+ */
+export declare function runScaffold(request: IScaffoldRequest, version: string, options?: IScaffoldRunOptions): IScaffoldResult;
+/**
+ * Déclare `modules/*` en workspaces npm de l'app et branche les scripts sur eux.
+ *
+ * POURQUOI c'est indispensable : le Kernel charge un module par son NOM
+ * (`import("@app/blog")`, cf `Kernel.loadModule`) — pas par un chemin. Sans le
+ * symlink que npm pose pour un workspace, le boot échoue sur « Cannot find
+ * package ». Les scripts sont chaînés dans la foulée, sinon le module ne serait
+ * ni construit (le bundler de l'app ne regarde que `index.ts` + `nodefony/**`),
+ * ni typé, ni testé : du code mort au premier jour.
+ *
+ * Idempotent — relancé pour le 2ᵉ module, il ne touche plus à rien.
+ *
+ * @returns true si le `package.json` de l'app a été modifié.
+ */
+export declare function ensureWorkspaces(projectRoot: string, writer: ScaffoldWriter): boolean;
+/**
+ * Ajoute le module au manifeste `modules` de `nodefony.config.ts` — c'est CE
+ * tableau qui décide de ce qui se charge, et dans quel ordre. Un module local
+ * vient à la fin : le socle (http, framework, security…) doit être debout avant.
+ *
+ * Édition textuelle GARDÉE (même doctrine que `wireDecoratorList`) : on n'écrit
+ * que si l'ancre est trouvée sans ambiguïté, sinon on rend une note actionnable —
+ * jamais un `nodefony.config.ts` corrompu, qui empêcherait l'app de booter.
+ *
+ * @param moduleDir - dossier où le module a été créé, relatif à la racine (en
+ *   `/`) — seulement pour NOMMER le bon endroit dans le commentaire inséré.
+ * @returns note à afficher si un geste manuel reste nécessaire, sinon `null`.
+ */
+export declare function wireModuleManifest(configPath: string, pkgName: string, writer: ScaffoldWriter, moduleDir?: string): string | null;
+/**
+ * Déclare un rôle applicatif sous `ROLE_ADMIN` dans la hiérarchie de l'app.
+ *
+ * ## Pourquoi la hiérarchie, et pas une liste de rôles sur l'action
+ *
+ * Deux gestes rendent la même réponse sur la route qu'on vient d'écrire — une
+ * hiérarchie, ou `@IsGranted(["ROLE_X", "ROLE_ADMIN"])`. Un seul GÉNÉRALISE :
+ * la hiérarchie vaut pour toute route future gardée par ce rôle, la liste
+ * s'arrête à cette action-là et devra être recopiée à chaque fois. Le troisième
+ * geste — attribuer le rôle à l'administrateur au semis — est pire encore : il
+ * ne se voit dans aucun diff de route et se perd au premier compte recréé.
+ *
+ * ## Ce que cette fonction n'invente pas
+ *
+ * Elle n'ajoute JAMAIS une clé `roleHierarchy` absente, ni un `ROLE_ADMIN`
+ * absent : composer un bloc de configuration à l'aveugle dans un fichier que
+ * l'utilisateur a pu réorganiser produirait un manifeste qui ne boote plus.
+ * Quand l'ancre manque, elle rend la note à taper — même doctrine que
+ * {@link wireModuleManifest} et `wireDecoratorList`.
+ *
+ * @param configPath - `nodefony.config.ts` de l'application.
+ * @param role - le rôle à déclarer (déjà validé par le schéma de la question).
+ * @param writer - écrivain du scaffold (respecte `--dry-run`).
+ * @returns note à afficher si un geste manuel reste nécessaire, sinon `null`.
+ */
+export declare function wireRoleHierarchy(configPath: string, role: string, writer: ScaffoldWriter): string | null;
+/**
+ * Câble `this.addCommand(<Classe>)` dans le constructeur du Module d'un
+ * `index.ts` : ajoute l'import après le dernier import, insère l'appel juste
+ * après le `super(…)` du constructeur.
+ *
+ * L'ancre est le `super(…)` et non l'accolade du constructeur : c'est la seule
+ * ligne dont l'existence est GARANTIE (un `Module` doit appeler `super`), et
+ * insérer après elle vaut pour un constructeur vide comme pour un constructeur
+ * déjà rempli. Édition textuelle gardée, même contrat que
+ * {@link wireDecoratorList} : toute ambiguïté = throw actionnable, jamais un
+ * fichier corrompu.
+ *
+ * @throws si la classe y est déjà, si aucun import n'ancre l'insertion, ou si
+ *   le `super(…)` du constructeur est introuvable (le message donne l'édition
+ *   manuelle exacte).
+ */
+export declare function wireCommandCall(indexPath: string, className: string, importPath: string, writer: ScaffoldWriter): void;
+/**
+ * Valeur d'exemple d'un champ — VALIDE au regard du schéma de l'entité.
+ *
+ * Un échantillon n'est pas une décoration : les tests générés s'en servent pour
+ * insérer, et la documentation pour montrer un appel qui marche. S'il viole le
+ * schéma, l'entité naît avec un test rouge, et la première impression du
+ * générateur est qu'il produit du code cassé.
+ *
+ * Ce piège s'est présenté trois fois, sur trois types ajoutés à trois moments
+ * différents — l'énumération, puis le décimal et le caractère fixe. Chaque fois,
+ * la valeur générique `nom-1` passait à côté d'une contrainte que le schéma, lui,
+ * faisait respecter. D'où cette fonction unique : tout type qui restreint ses
+ * valeurs doit dire ici ce qu'il accepte, sinon rien ne le rappellera.
+ *
+ * @param field - le champ à illustrer.
+ * @param id - stratégie de clé primaire (une référence vers une clé numérique
+ *   attend un nombre, pas une chaîne).
+ * @returns `fixed` pour le JSON de la documentation, `expr` pour la fabrique
+ *   paramétrée des tests (une expression TypeScript où `n` varie).
+ */
+/**
+ * Le filtre sur lequel le test généré peut prouver qu'un filtre FILTRE — ou
+ * `null` si aucun champ ne s'y prête.
+ *
+ * Prouver un refus (`?actf=x` → 400) et prouver un filtre sont deux choses
+ * différentes, et la seconde exige une ligne qui NE matche PAS. Sans elle,
+ * l'assertion « toutes les lignes rendues portent la valeur demandée » reste
+ * vraie quand le filtre est ignoré : tous les échantillons d'un booléen valent
+ * `true`, ceux d'une énumération valent sa première valeur ({@link sampleValue}).
+ * Le test serait vert sur un filtre débranché — exactement le défaut qu'il est
+ * censé attraper.
+ *
+ * D'où les deux seules natures retenues, celles qui offrent un contraire sûr et
+ * gratuit. Une clé étrangère en est écartée : poser une seconde valeur
+ * demanderait de créer l'entité visée, et le test parlerait d'autre chose.
+ *
+ * Deux écritures de chaque valeur, et ce n'est pas une redondance : `match` part
+ * dans l'URL (`?publie=true` — tout y est du texte), `matchJson` est la
+ * littérale TypeScript posée dans le corps envoyé (`publie: true`, un booléen —
+ * `"true"` y serait refusé par le schéma).
+ *
+ * @param fields - les champs déclarés de l'entité.
+ * @returns le nom du filtre et ses deux valeurs sous les deux écritures, ou
+ *   `null` si l'entité n'a aucun champ éprouvable.
+ */
+export declare function filterProbe(fields: readonly IEntityField[]): {
+    name: string;
+    match: string;
+    matchJson: string;
+    other: string;
+    otherJson: string;
+} | null;
+/**
+ * Le filtre sur lequel une valeur MAL FORMÉE existe, et de quoi la fabriquer —
+ * ou `null` si aucun filtre de l'entité ne peut en refuser une.
+ *
+ * Toutes les natures ne refusent pas : un filtre `"string"` accepte n'importe
+ * quelle chaîne, par construction. Le test généré visait pourtant le PREMIER
+ * filtre déclaré quel qu'il soit, et attendait un `400` — sur une entité dont
+ * le seul filtre est une clé étrangère à identifiant textuel
+ * (`author:ref:Author` avec des `uuid`), il exigeait donc le refus d'une valeur
+ * parfaitement valide, et échouait sur le générateur au lieu de l'éprouver.
+ *
+ * @param filters - le vocabulaire de filtre déjà calculé (nom → littérale de sa
+ *   nature, telle qu'elle sera écrite dans le gabarit).
+ * @returns le nom du filtre et une valeur qu'il doit refuser, ou `null`.
+ */
+export declare function malformedProbe(filters: readonly {
+    name: string;
+    def: string;
+}[]): {
+    name: string;
+    value: string;
+} | null;
+export declare function sampleValue(field: IEntityField, id: TEntityIdKind): {
+    fixed: unknown;
+    expr: string;
+};
+/** Un connecteur de base de données, tel que déclaré dans la configuration. */
+export interface IScaffoldConnector {
+    /** Nom sous lequel les entités le désignent (`default`, `analytics`…). */
+    name: string;
+    /** Moteur SQL visé — décide des types de colonnes générés. */
+    dialect: TEntityDialect;
+    /**
+     * Qui fabrique le schéma de ce connecteur, quand l'application l'ÉCRIT.
+     *
+     * `undefined` = la configuration ne le dit pas, et le mode sera résolu au
+     * démarrage depuis l'environnement (développement → `auto`, le reste →
+     * `none`). Le scaffold ne le devine pas : il ne sait pas dans quel mode
+     * l'application tournera, et affirmer « créée au prochain boot » à qui a
+     * écrit `none` serait faux.
+     */
+    ddl?: string;
+}
+/**
+ * Ajoute une entité au décorateur `@entities([...])` de la cible — **en le créant
+ * s'il n'existe pas encore**.
+ *
+ * Différence avec `wireDecoratorList` : une app n'a aucune raison de porter un
+ * `@entities([])` vide tant qu'elle n'a pas d'entité, et les apps déjà générées n'en
+ * ont pas. Plutôt que d'exiger une ancre (throw) ou de l'imposer à tous les templates,
+ * on **pose le décorateur au premier usage**, juste au-dessus de `@controllers` (ou de
+ * la déclaration de classe s'il n'y en a pas).
+ *
+ * Édition textuelle conservatrice : toute ambiguïté fait échouer avec un geste à
+ * appliquer à la main, plutôt que de corrompre le fichier.
+ *
+ * @param indexPath - `index.ts` de la cible.
+ * @param className - nom du descripteur (`PostEntity`).
+ * @param importPath - chemin relatif du descripteur.
+ * @throws si l'entité est déjà référencée, ou si aucun point d'insertion n'est trouvé.
+ */
+/**
+ * Position d'insertion devant la classe `… extends Module` — décorateurs de
+ * classe COMPRIS, puisque `@entities([…])` doit se poser au-dessus d'eux.
+ *
+ * Volontairement PAS une expression régulière. Le motif naturel
+ * (`(?:@\w+\([\s\S]*?\)\s*)*class …`) est ambigu — le contenu paresseux d'un
+ * décorateur peut se découper de plusieurs façons entre deux itérations — donc
+ * exponentiel au backtracking : mesuré ici, 26 décorateurs sans classe à trouver
+ * coûtaient 636 ms, et chaque paire supplémentaire multipliait par ~3,5. Or le
+ * pire cas EST le cas d'échec prévu par l'appelant (ancre introuvable) : la
+ * commande figeait au lieu de rendre son geste manuel.
+ *
+ * Le balayage ci-dessous remonte les décorateurs un par un en appariant les
+ * parenthèses — linéaire, et correct sur un décorateur qui en contient
+ * lui-même (`@entities([defineEntity(x)])`).
+ *
+ * @param source - contenu de l'`index.ts` de la cible.
+ * @returns l'index d'insertion, ou `undefined` si aucune classe `extends Module`.
+ */
+export declare function findModuleClassAnchor(source: string): number | undefined;
+/**
+ * Câble un descripteur d'entité au module de la cible.
+ *
+ * @param indexPath - `index.ts` de la cible (app racine ou module).
+ * @param className - nom exporté du descripteur.
+ * @param importPath - chemin d'import, en `/`.
+ * @param writer - écrivain du scaffold (respecte `--dry-run`).
+ * @param alreadyWiredIsNormal - `true` quand RÉGÉNÉRER l'entité est le geste
+ *   attendu, et non un doublon. C'est le cas de l'utilisateur : son fichier
+ *   PRESCRIT « relance la commande avec tes champs », et l'entité est déjà
+ *   câblée depuis la naissance de l'application. Le refus reste entier pour
+ *   toutes les autres : deux entités du même nom dans un registre PLAT font
+ *   échouer le démarrage.
+ * @throws Si le nom est déjà référencé hors de ce cas, ou si l'`index.ts` n'a
+ *   aucun import où s'accrocher.
+ */
+export declare function wireEntitiesDecorator(indexPath: string, className: string, importPath: string, writer: ScaffoldWriter, alreadyWiredIsNormal?: boolean): void;
+/**
+ * Câble un appel dans le hook `onKernelBoot()` de l'`index.ts` cible : import
+ * de la fonction + soit INSERTION d'un hook complet (s'il n'existe pas — le
+ * layout des index générés est connu), soit note actionnable (un hook existant
+ * n'est JAMAIS édité : on ne réécrit pas du code utilisateur).
+ *
+ * @returns note à afficher si un geste manuel reste nécessaire, sinon `null`.
+ */
+export declare function wireKernelBootCall(indexPath: string, fnName: string, importPath: string, writer: ScaffoldWriter): string | null;