nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,238 @@
+/**
+ * Champs d'entité : de la syntaxe `title:string` au code Drizzle du dialecte visé.
+ *
+ * Module **pur** (aucune I/O, aucun template) : c'est lui qui porte la traduction
+ * « vocabulaire Nodefony → colonne Drizzle native », donc c'est lui qu'on teste.
+ *
+ * Vocabulaire volontairement restreint — le scaffold doit produire du code qu'un
+ * humain relit et étend, pas couvrir toute la surface SQL. Un besoin exotique
+ * (`numeric(12,4)`, `citext`, tableau PG…) s'écrit à la main dans la table générée :
+ * c'est du Drizzle natif, il n'y a rien à contourner.
+ */
+/** Dialectes SQL supportés par le scaffold (ceux de `@nodefony/drizzle`). */
+export declare const ENTITY_DIALECTS: readonly ["sqlite", "postgres", "mysql"];
+export type TEntityDialect = (typeof ENTITY_DIALECTS)[number];
+/** Stratégies de clé primaire. */
+export declare const ENTITY_ID_KINDS: readonly ["uuid7", "uuid4", "serial"];
+export type TEntityIdKind = (typeof ENTITY_ID_KINDS)[number];
+/** Types de champ du vocabulaire Nodefony (jamais le vocabulaire Drizzle). */
+export declare const ENTITY_FIELD_TYPES: readonly ["string", "text", "int", "float", "bool", "json", "date", "uuid", "enum", "char", "decimal"];
+export type TEntityFieldType = (typeof ENTITY_FIELD_TYPES)[number];
+/** Un champ déclaré, après analyse de `title:string!` ou `author:ref:User`. */
+export interface IEntityField {
+    /** Nom de la propriété (camelCase). */
+    name: string;
+    /** Type Nodefony, ou `ref` pour une clé étrangère. */
+    type: TEntityFieldType | "ref";
+    /** Entité cible quand `type === "ref"`. */
+    target?: string;
+    /** Valeurs admises quand `type === "enum"` (`status:enum(draft,published)`). */
+    values?: string[];
+    /**
+     * Longueur déclarée d'une chaîne (`title:string(200)`, `country:char(2)`).
+     *
+     * Absente pour `string`, la colonne retombe sur 255 — la valeur par défaut
+     * historique. Un schéma réel dimensionne ses colonnes (onze longueurs
+     * distinctes chez Umami) : la place perdue se paie en octets par ligne, et
+     * l'absence de borne laisse passer des valeurs qu'aucune règle ne veut.
+     */
+    length?: number;
+    /** Chiffres significatifs d'un décimal exact (`price:decimal(12,2)` → 12). */
+    precision?: number;
+    /** Chiffres après la virgule d'un décimal exact (`price:decimal(12,2)` → 2). */
+    scale?: number;
+    /**
+     * Valeur par défaut littérale, telle qu'écrite (`price:float=0` → `"0"`).
+     *
+     * Conservée en texte : c'est le générateur qui sait la traduire en littéral du
+     * bon type, et lui seul connaît le dialecte visé.
+     */
+    defaultValue?: string;
+    /** `true` si `?` — la colonne accepte `NULL`. Non-null par DÉFAUT. */
+    nullable: boolean;
+    /** `true` si `!` — contrainte d'unicité. */
+    unique: boolean;
+    /** `true` si `:index`. */
+    indexed: boolean;
+    /**
+     * Horodatage posé à l'insertion (`new Date()`), sans `DEFAULT` SQL.
+     *
+     * La grammaire de champs ne peut pas l'exprimer — « maintenant » n'est pas une
+     * valeur littérale —, et pourtant le contrat utilisateur en porte deux. Sans
+     * cette propriété, ces colonnes seraient écrites à la main quelque part, donc
+     * en double.
+     */
+    defaultNow?: boolean;
+    /** Horodatage RÉÉCRIT à chaque mise à jour (`$onUpdateFn`). */
+    refreshedOnWrite?: boolean;
+}
+/**
+ * Casses de nom de colonne SQL proposées — la propriété TypeScript ne bouge jamais.
+ *
+ * `camel` reproduit la propriété telle quelle (défaut historique) ; `snake` émet
+ * `site_id` là où la propriété reste `siteId`. Drizzle porte nativement cette
+ * dissociation — le premier argument d'un constructeur de colonne EST le nom SQL.
+ *
+ * Une seule option couvre l'écrasante majorité des schémas existants : sur les 134
+ * renommages qu'exige le schéma d'Umami, **115 sont ce passage mécanique** au
+ * `snake_case`. Les nommer un par un aurait demandé un dictionnaire ; ils tiennent
+ * dans un choix.
+ */
+export declare const COLUMN_CASES: readonly ["camel", "snake"];
+export type TColumnCase = (typeof COLUMN_CASES)[number];
+/** `BlogPost` / `blog-post` / `siteId` → `blog_post` / `site_id`. */
+export declare function toSnakeCase(name: string): string;
+/**
+ * Nom SQL d'une colonne, dérivé de sa propriété TypeScript.
+ *
+ * @param property - nom de la propriété (`siteId`).
+ * @param columnCase - casse demandée ; `camel` rend la propriété inchangée.
+ */
+export declare function sqlColumn(property: string, columnCase: TColumnCase): string;
+/** Erreur de syntaxe dans la déclaration d'un champ — message actionnable. */
+export declare class EntityFieldError extends Error {
+}
+/**
+ * Analyse la déclaration textuelle des champs.
+ *
+ * Grammaire : `nom:type[?][!][=defaut][:index]` · `nom:ref:Entité[?][!][:index]`
+ * - `?` → nullable (sinon **NOT NULL** : une colonne nullable est une décision, pas un oubli) ;
+ * - `!` → unique ;
+ * - `=valeur` → valeur par défaut (`price:float=0`, `status:enum(draft,published)=draft`) ;
+ * - `:index` → index simple.
+ *
+ * Le type `enum` porte ses valeurs entre parenthèses : `status:enum(draft,published)`.
+ *
+ * @param input - `"title:string! content:text? views:int=0 author:ref:User"`.
+ * @returns les champs, dans l'ordre de déclaration.
+ * @throws EntityFieldError si un champ est mal formé (le mot « invalide » est attendu
+ *   par le routeur d'erreurs du CLI pour sortir en `EX_USAGE`).
+ */
+export declare function parseEntityFields(input: string): IEntityField[];
+/**
+ * Index portant sur PLUSIEURS colonnes, déclaré au niveau de la table.
+ *
+ * Un index composite n'appartient à aucune colonne en particulier — il décrit une
+ * façon d'interroger la table (« les événements de ce site, du plus récent au plus
+ * ancien »). C'est pourquoi il se déclare à part de la grammaire de champs, et non
+ * par un modificateur : il n'y aurait pas de champ légitime où l'accrocher.
+ *
+ * L'ORDRE des colonnes est significatif et se conserve : un index sur `(site, date)`
+ * sert les requêtes qui filtrent sur le site, celles qui ne filtrent que sur la date
+ * ne le verront pas.
+ */
+export interface IEntityIndex {
+    /** Colonnes indexées, dans l'ordre déclaré. */
+    columns: string[];
+    /** `true` pour une contrainte d'unicité portant sur la combinaison. */
+    unique: boolean;
+}
+/**
+ * Analyse les index de table déclarés par `--index` / `--unique`.
+ *
+ * Chaque valeur est une liste de colonnes séparées par des virgules
+ * (`"websiteId,createdAt"`). Toute colonne citée doit exister : sans ce contrôle, on
+ * écrirait une entité qui ne compile pas, et l'erreur tomberait chez l'utilisateur
+ * sous la forme d'une propriété inconnue — loin de la commande qui l'a causée.
+ *
+ * @param specs - valeurs brutes des options, dans l'ordre de la ligne de commande.
+ * @param fields - champs déjà analysés, qui fournissent les noms légitimes.
+ * @param options - présence des colonnes implicites (horodatages, suppression douce).
+ * @param unique - `true` quand ces valeurs viennent de `--unique`.
+ * @returns les index analysés, doublons retirés.
+ * @throws {EntityFieldError} colonne inconnue, liste vide, ou colonne répétée.
+ */
+export declare function parseEntityIndexes(specs: readonly string[], fields: readonly IEntityField[], options: {
+    timestamps: boolean;
+    softDelete: boolean;
+}, unique?: boolean): IEntityIndex[];
+/**
+ * Ce que chaque type de champ devient, dans chaque moteur.
+ *
+ * Montrer la traduction plutôt que la promettre : `json` devient `jsonb` en
+ * PostgreSQL et une colonne texte en SQLite, `string` un `varchar(255)` ici et un
+ * `text` là. C'est une information dont dépend le choix de celui qui modélise, et
+ * elle n'est déductible d'aucune documentation générique.
+ *
+ * Dérivé de la table de traduction elle-même : impossible que ce catalogue
+ * dérive de ce que le générateur produit réellement.
+ *
+ * @returns un descripteur par type, avec sa colonne Drizzle par dialecte.
+ */
+export declare function describeColumnTypes(): Array<{
+    type: string;
+    byDialect: Record<string, string>;
+}>;
+/** Fonction de table Drizzle du dialecte (`sqliteTable`…) et son import. */
+export declare const TABLE_FN: Record<TEntityDialect, {
+    fn: string;
+    module: string;
+}>;
+/** Tout ce dont les templates ont besoin pour rendre une entité. */
+export interface IEntityCodegen {
+    /** Corps de la table (lignes `nom: colonne,`). */
+    columns: string;
+    /** Import Drizzle du dialecte (`import { text, integer } from "drizzle-orm/sqlite-core";`). */
+    drizzleImport: string;
+    /** Fonction de table (`sqliteTable`). */
+    tableFn: string;
+    /** Propriétés de l'interface de ligne. */
+    rowProps: string;
+    /** Corps du schéma Zod de création. */
+    zodProps: string;
+    /**
+     * Troisième argument de la table Drizzle — les index déclarés par `:index`.
+     *
+     * Chaîne vide quand aucun index n'est demandé : la table garde alors sa forme
+     * à deux arguments.
+     */
+    tableExtras: string;
+    /** `true` si la clé primaire est générée côté JS (le template importe `Nodefony`). */
+    needsNodefony: boolean;
+    /** Type TS de la clé primaire. */
+    idType: string;
+}
+/**
+ * Produit le code des colonnes, de l'interface de ligne et du schéma Zod.
+ *
+ * Les horodatages sont posés **côté JS** (`$defaultFn`/`$onUpdateFn`) et non en SQL :
+ * le DDL dérivé du mode dev n'émet pas les `DEFAULT` — un défaut SQL serait donc
+ * silencieusement absent des tables créées au boot.
+ *
+ * @param fields - champs analysés par {@link parseEntityFields}.
+ * @param options - dialecte, stratégie d'identifiant, horodatages, suppression douce.
+ */
+export declare function buildEntityCodegen(fields: IEntityField[], options: {
+    dialect: TEntityDialect;
+    id: TEntityIdKind;
+    timestamps: boolean;
+    softDelete: boolean;
+    /**
+     * Nom de la table — sert à préfixer les noms d'index.
+     *
+     * Requis : en PostgreSQL comme en SQLite, un nom d'index est unique pour
+     * TOUTE la base. Deux entités qui indexeraient chacune un `title` se
+     * marcheraient dessus au premier boot.
+     */
+    table: string;
+    /**
+     * Index de TABLE, portant une ou plusieurs colonnes ({@link parseEntityIndexes}).
+     *
+     * Fusionnés avec ceux que les champs déclarent par `:index` — un même jeu de
+     * colonnes n'est émis qu'une fois, quelle que soit la voie empruntée.
+     */
+    indexes?: IEntityIndex[];
+    /**
+     * Casse des noms de COLONNES SQL — les propriétés TypeScript n'en dépendent pas.
+     *
+     * Défaut `camel` : le comportement historique, où la colonne porte le nom de la
+     * propriété. Une application existante impose presque toujours `snake`.
+     */
+    columnCase?: TColumnCase;
+    /**
+     * Nom SQL de la colonne de clé primaire (défaut `id`).
+     *
+     * La propriété reste `id` quoi qu'il arrive — cf {@link primaryKeyColumn}.
+     */
+    idName?: string;
+}): IEntityCodegen;

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

@@ -0,0 +1,78 @@
+/**
+ * Met en forme ce que le scaffold produit, avec le prettier DU PROJET.
+ *
+ * Pourquoi c'est ici et pas dans les gabarits : la forme canonique d'une ligne
+ * dépend souvent d'un identifiant que l'UTILISATEUR choisit.
+ * `export type ReportingMensuelConfigInput = z.input<…>` fait 87 colonnes ;
+ * le même gabarit nommé `blog` tient sous 80. Un gabarit rend UNE forme, donc
+ * aucune écriture de gabarit ne peut être juste pour tous les noms — ce n'est
+ * pas un cas particulier, c'est la règle, puisque presque tout ce qu'un
+ * générateur produit porte un nom dérivé. Mesuré : une application avec tous
+ * les générateurs rendait 16 fichiers que son propre `npm run format`
+ * réécrivait au premier passage.
+ *
+ * Le coût qui avait fait écarter cette solution — embarquer prettier dans le
+ * CLI, ~8 Mo dans chaque image de production — n'existe pas : l'application
+ * générée a DÉJÀ prettier en dépendance de développement. On emprunte le sien,
+ * et on ne fait rien s'il est absent.
+ *
+ * Trois règles, chacune tenant à une raison précise :
+ *
+ * 1. **Une CRÉATION est formatée, une RÉÉCRITURE seulement si le fichier
+ *    suivait déjà prettier.** Une réécriture touche du code que l'utilisateur a
+ *    écrit ; reformater en entier un fichier qui a son propre style produirait
+ *    un diff énorme et lui imposerait notre convention. `format(avant) ===
+ *    avant` répond exactement à « ce projet suit-il prettier ? ».
+ * 2. **Le formatage a lieu AVANT que le plan soit calculé**, jamais au vidage
+ *    de la transaction : sinon `--dry-run` annoncerait une forme que
+ *    l'exécution ne produirait pas. Une option dont le seul rôle est de dire ce
+ *    qui va se passer ne peut pas mentir.
+ * 3. **Un échec ne bloque jamais une génération.** Prettier absent, illisible,
+ *    ou qui refuse un fichier : on écrit le contenu tel quel. La mise en forme
+ *    est un confort, pas une garantie.
+ */
+import type { ScaffoldWriter } from "./writer.js";
+/** Ce que la mise en forme a fait — matière du récapitulatif du CLI. */
+export interface IFormatOutcome {
+    /** Fichiers effectivement remis en forme. */
+    formatted: number;
+    /**
+     * Fichiers formatables qu'on a laissés tels quels faute de prettier. Zéro
+     * quand il n'y avait rien à formater : le CLI ne parle que si ça compte.
+     */
+    pending: number;
+}
+/**
+ * Met en forme des fichiers DÉJÀ ÉCRITS, nommés un par un.
+ *
+ * La seconde porte, pour le seul cas que la transaction ne peut pas servir :
+ * `create app` écrit ses fichiers AVANT `npm install`, donc au moment du rendu
+ * le projet n'a aucun prettier à prêter. On repasse après l'installation.
+ *
+ * 🔴 **La liste est celle des fichiers que le scaffold a ÉCRITS, jamais un
+ * dossier.** Passer `.` à prettier reformaterait le projet ENTIER — le code que
+ * l'utilisateur a écrit compris, avec un diff qui déborde très loin de ce qu'on
+ * vient de générer. Un générateur met en forme ce qu'il produit, rien d'autre.
+ *
+ * Le prettier du projet est chargé comme MODULE, jamais lancé comme binaire :
+ * sous Windows le binaire est un `.cmd`, et depuis le correctif de
+ * CVE-2024-27980 Node refuse d'exécuter un `.cmd` sans `shell: true` (`EINVAL`).
+ * Passer par un shell demanderait ensuite d'échapper un chemin qui contient
+ * couramment des espaces. Le module n'a aucun de ces deux problèmes.
+ *
+ * @param files - chemins ABSOLUS des fichiers écrits par le scaffold.
+ * @param dest - dossier du projet, point de départ de la recherche de prettier.
+ * @returns ce qui a été mis en forme, et ce qui attend faute de prettier.
+ */
+export declare function formatFilesOnDisk(files: string[], dest: string): IFormatOutcome;
+/**
+ * Met en forme les écritures en attente, dans la transaction.
+ *
+ * Appelée par {@link runScaffold} AVANT la bifurcation dry-run / vidage, pour
+ * que le plan annoncé et le résultat écrit soient le même texte.
+ *
+ * @param writer - la transaction du scaffold racine.
+ * @param dest - dossier visé, point de départ de la recherche de prettier.
+ * @returns ce qui a été mis en forme, et ce qui attend faute de prettier.
+ */
+export declare function formatScaffoldOutput(writer: ScaffoldWriter, dest: string): IFormatOutcome;

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

@@ -0,0 +1,11 @@
+import type { Readable, Writable } from "node:stream";
+import type { IScaffoldTypeSpec } from "./spec.js";
+import type { IScaffoldCaps, IScaffoldContext, TScaffoldAnswers } from "./engine.js";
+/** Confirmation simple `[O/n]` — pour le récap final avant génération. */
+export declare function confirm(question: string, input?: Readable, output?: Writable): Promise<boolean>;
+/**
+ * Pose les questions de la spec NON déjà répondues (les flags argv gagnent —
+ * on ne redemande jamais ce que l'utilisateur a déjà dit) et retourne les
+ * réponses fusionnées. Les questions `askIf` non satisfaites sont sautées.
+ */
+export declare function askMissing(spec: IScaffoldTypeSpec, partial: TScaffoldAnswers, caps: IScaffoldCaps, input?: Readable, output?: Writable, context?: IScaffoldContext | null): Promise<TScaffoldAnswers>;

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

@@ -0,0 +1,69 @@
+/**
+ * OÙ les modules d'un dépôt vivent, et sous quel NOM ils naissent.
+ *
+ * ## Le problème que ça règle
+ *
+ * `create module` posait ses modules dans `modules/<nom>` en dur, avec un scope
+ * npm dérivé du nom de l'application. C'est juste pour une app générée — et faux
+ * pour un monorepo qui range ses paquets ailleurs, à commencer par le dépôt du
+ * framework lui-même (`src/packages/@nodefony/*`). Conséquence vécue : l'auteur
+ * du framework écrivait à la main le squelette que sa propre commande sait
+ * produire, et le squelette dérivait sans que rien ne le signale.
+ *
+ * ## La règle
+ *
+ * Le layout se **CONSTATE** dans les `workspaces` du `package.json` de la
+ * racine — jamais ne se déduit d'un nom de dépôt ni d'un chemin en dur. Une
+ * entrée de la forme `<prefixe>/@<scope>/*` déclare un dossier de **paquets
+ * scopés** : un module qui y naît est un paquet publiable, et prend ce scope.
+ * Sans une telle entrée, on est dans le layout d'une application : `modules/`,
+ * scope dérivé du nom de l'app.
+ *
+ * Tout est DÉRIVÉ de la déclaration : rien n'est écrit en dur ici, pas même
+ * `@nodefony` — le dépôt du framework n'est qu'un cas particulier de la règle.
+ *
+ * ⚠️ Les chemins rendus ici **voyagent** (messages, comparaisons, gabarits) :
+ * ils sont donc en `/`, jamais en séparateur natif. Pour OUVRIR, l'appelant
+ * recompose (`path.join(root, ...dir.split("/"))`).
+ */
+/** Manifeste racine, réduit à ce dont le layout dépend. */
+export interface IRootManifest {
+    name?: string;
+    workspaces?: string[];
+}
+/** Où poser un module, sous quel nom, et ce que le dépôt déclare déjà. */
+export interface IModuleLayout {
+    /**
+     * `packages` : dossier de paquets scopés déclaré en workspace → le module naît
+     * PUBLIABLE (exports, types, `files`, peerDependencies).
+     * `modules` : layout d'application → module local, privé.
+     */
+    kind: "packages" | "modules";
+    /** Dossier où créer un module neuf, relatif à la racine, en `/`. */
+    createDir: string;
+    /** Scope npm des modules créés, `@` compris. */
+    scope: string;
+    /** Dossiers à balayer pour lister les cibles existantes, en `/`. */
+    targetDirs: string[];
+    /**
+     * Le dépôt déclare-t-il DÉJÀ {@link createDir} en workspace npm ?
+     *
+     * `false` ⇒ l'appelant doit l'ajouter (sans le symlink de workspace, le Kernel
+     * ne peut pas importer le module par son nom). `true` ⇒ ne toucher à rien : un
+     * monorepo établi a ses propres scripts, et les chaîner par-dessus casserait sa
+     * chaîne de construction.
+     */
+    workspaceDeclared: boolean;
+}
+/**
+ * Déduit le layout des modules à partir du manifeste de la racine.
+ *
+ * Fonction PURE (aucun accès disque) : le manifeste est lu par l'appelant, ce
+ * qui la rend éprouvable sur des dépôts qu'on n'a pas.
+ *
+ * @param manifest - `package.json` de la racine du projet, déjà analysé.
+ * @param projectDirName - nom du dossier racine, repli quand le manifeste n'a
+ *   pas de `name` (le scope d'une app en dérive).
+ * @returns le layout à appliquer.
+ */
+export declare function resolveModuleLayout(manifest: IRootManifest, projectDirName: string): IModuleLayout;

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

@@ -0,0 +1,49 @@
+/**
+ * Noms d'entités que les modules du framework occupent déjà dans le registre ORM.
+ *
+ * Le registre d'entités est PLAT et partagé par toute l'application : deux entités
+ * du même nom ne cohabitent pas. Une application qui déclare la sienne écrase
+ * silencieusement celle d'un module, et l'échec ne se voit qu'au démarrage suivant,
+ * sous la forme d'une colonne inconnue dans une requête du module dépossédé — un
+ * message qui ne nomme ni le doublon, ni le fichier fautif. D'où le refus AVANT
+ * d'écrire, avec le nom du propriétaire et une porte de sortie.
+ *
+ * ⚠️ Cette table décrit le FRAMEWORK, pas les modules tiers : un module applicatif
+ * inconnu d'ici peut réserver un nom qu'elle ignore. Elle est tenue honnête par le
+ * gate `NF_RUN_CLI_BOOT=1` de `CliIntegration.test.ts`, qui la confronte à ce que
+ * `nodefony inspect entities --json` rapporte réellement sur ce dépôt.
+ */
+/** Entité du framework : le nom occupé et le module qui le porte. */
+export interface IReservedEntity {
+    /** Nom tel qu'il est enregistré au registre ORM. */
+    readonly name: string;
+    /** Module propriétaire (nom court, tel que rapporté par `inspect entities`). */
+    readonly module: string;
+    /** Ce que l'utilisateur devrait faire à la place. */
+    readonly advice: string;
+    /**
+     * `true` quand l'entité appartient à l'APPLICATION et non au framework.
+     *
+     * Le nom reste connu d'ici — un module le lit, et le registre reste plat —
+     * mais il n'est plus INTERDIT : le générateur écrit l'entité au lieu de la
+     * refuser, et le contrôle de câblage ne la dénonce plus. Sans cette
+     * distinction, les deux lieux qui consultent cette table auraient chacun leur
+     * exception, et elles auraient divergé.
+     */
+    readonly appOwned?: true;
+}
+export declare const RESERVED_ENTITY_NAMES: readonly IReservedEntity[];
+/**
+ * Cherche une collision de nom d'entité avec le framework.
+ *
+ * Comparaison INSENSIBLE À LA CASSE et aux séparateurs : `AccessToken`,
+ * `access_token` et `accesstoken` désignent la même table pour un humain comme
+ * pour la plupart des moteurs (MySQL et SQLite comparent les noms de table sans
+ * égard à la casse sur les systèmes de fichiers courants). Laisser passer
+ * `AccessToken` parce que le registre écrit `access_token` reviendrait à autoriser
+ * exactement la panne qu'on cherche à éviter.
+ *
+ * @param name - nom d'entité demandé (`create entity <Nom>`).
+ * @returns l'entrée réservée qui entre en conflit, ou `null` si le nom est libre.
+ */
+export declare function findReservedEntity(name: string): IReservedEntity | null;

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

@@ -0,0 +1,159 @@
+/**
+ * Spec DÉCLARATIVE du scaffold — la source unique des choix de création.
+ *
+ * Les questions sont des DONNÉES (JSON-able, zéro fonction) : le même contrat
+ * alimente les TROIS fronts de création —
+ *   1. CLI rapide     : flags argv → réponses (`--preset minimal --frontend react`) ;
+ *   2. CLI interactif : `interactive.ts` rend chaque question en readline natif ;
+ *   3. Studio         : un endpoint data plane sert `getScaffoldSpec()` en JSON,
+ *      le formulaire React poste les réponses au MÊME moteur (`engine.ts`).
+ *
+ * ⚠️ **Deux fronts sur trois se servent seuls** : l'interactif et Studio LISENT
+ * cette spec, donc une question ajoutée y apparaît sans qu'on les touche. La
+ * voie FLAGS, elle, a une analyse écrite à la main (`parseCreateArgv`) : une
+ * question sans drapeau est servie à l'humain et REFUSÉE au script, sans un mot
+ * — c'est arrivé. Le drapeau se déduit de la clé (`maClé` → `--ma-cle`), sauf
+ * mention `flag` ; et un test du dépôt refuse toute question qu'aucun drapeau
+ * ne sert.
+ */
+export interface IScaffoldQuestion {
+    key: string;
+    /** Libellé montré tel quel par le CLI interactif et Studio. */
+    label: string;
+    /**
+     * `"list"` = plusieurs valeurs indépendantes, chacune conservée entière.
+     *
+     * Distinct de `"string"` pour une raison qui se paie cher autrement : les
+     * réponses sont normalisées en texte, et deux valeurs concaténées deviennent
+     * indiscernables d'une seule. Deux index de deux colonnes se fondraient ainsi en
+     * un index de quatre — du code qui compile et n'indexe pas ce qu'on croit.
+     */
+    type: "string" | "boolean" | "choice" | "list";
+    /** Choix ordonnés (type "choice") — le premier N'est PAS forcément le défaut. */
+    choices?: {
+        value: string;
+        label: string;
+        hint?: string;
+    }[];
+    default: string | boolean | string[];
+    /** Regex source (sans flags) que la valeur string doit satisfaire. */
+    pattern?: string;
+    /** Message d'aide affiché si la validation échoue. */
+    patternHint?: string;
+    /**
+     * Condition d'affichage par CAPACITÉ d'environnement (JSON-able — pas de
+     * fonction) : la question n'est posée que si le front la déclare vraie.
+     * `hasCheckout` = un checkout nodefony-core est résolvable (mode --link).
+     */
+    askIf?: "hasCheckout";
+    /**
+     * Condition d'affichage par RÉPONSE PRÉCÉDENTE (JSON-able) : la question n'est
+     * posée que si `key` a déjà pour valeur `equals`. Distinct d'`askIf`, qui
+     * interroge l'ENVIRONNEMENT (un checkout est-il là ?) là où celle-ci exprime
+     * une dépendance entre deux choix de la même création.
+     *
+     * Non satisfaite, la question n'est ni posée ni honorée : sa valeur retombe au
+     * DÉFAUT de la spec. Une réponse portant sur ce qui ne sera pas généré n'a pas
+     * de sens à conserver — `--database postgres --preset minimal` ne rend aucun
+     * `compose.yaml` où mettre un service.
+     *
+     * La question référencée doit précéder celle-ci : le moteur comme le dialogue
+     * résolvent les questions dans l'ordre de la spec.
+     */
+    askWhen?: {
+        key: string;
+        equals: string;
+    };
+    /**
+     * Source des choix RÉELS de cette question, dans le projet courant (JSON-able,
+     * même esprit qu'`askIf`).
+     *
+     * Certaines réponses ne sont connues que du projet : les connecteurs qu'il
+     * déclare, les entités qu'il contient déjà. Les écrire dans la spec serait
+     * faux le lendemain. La question désigne donc une clé de
+     * `getScaffoldContext()`, et chaque front l'hydrate à sa manière — Studio en
+     * liste déroulante, le terminal en choix numérotés, `--describe-json` en
+     * embarquant le contexte.
+     *
+     * Sans cela, `ref:` et `--connector` restent du texte libre : une faute de
+     * frappe passe le scaffold et ne se voit qu'au démarrage suivant.
+     */
+    optionsFrom?: "connectors" | "entities";
+    /**
+     * Réglage **avancé** : jamais posé en dialogue (son défaut est sûr), mais piloté par
+     * une option de la ligne de commande — et proposé par Studio dans un repli.
+     *
+     * Pourquoi ce drapeau plutôt que sortir la question de la spec : c'est la spec qui
+     * porte les défauts, la validation et les valeurs permises. Une option absente d'ici
+     * serait silencieusement ignorée par le moteur (`resolveAnswers` ne garde que les
+     * clés déclarées) — le pire des deux mondes.
+     */
+    advanced?: boolean;
+    /**
+     * Nom du drapeau de ligne de commande, quand il ne se DÉDUIT pas de la clé.
+     *
+     * La convention est `maClé` → `--ma-cle`, et elle couvre presque tout. Restent
+     * les cas où le drapeau dit l'inverse (`timestamps` se règle par
+     * `--no-timestamps` : le défaut est vrai, seul le retrait se nomme) ou porte
+     * un autre mot (`uniqueIndex` → `--unique`, répétable).
+     *
+     * 🔴 **Pourquoi ce champ existe plutôt qu'une table dans un test** : sans lui,
+     * rien ne relie une question à sa voie « script », et une question ajoutée
+     * sans drapeau est servie à l'humain, refusée au script — sans un mot. C'est
+     * arrivé (`agents`). Le déclarer ICI rend le contrôle possible depuis la spec
+     * elle-même, et l'affirmation de l'en-tête enfin vraie.
+     */
+    flag?: string;
+}
+/** Spec d'un type de scaffold (`app` aujourd'hui ; `module`/`controller`/`entity` suivent). */
+export interface IScaffoldTypeSpec {
+    type: string;
+    description: string;
+    questions: IScaffoldQuestion[];
+}
+/** Frameworks front supportés par `@nodefony/frontend` (builder Vite multi-framework). */
+export declare const FRONTEND_CHOICES: readonly ["none", "react", "vue", "angular", "svelte"];
+export type TFrontendChoice = (typeof FRONTEND_CHOICES)[number];
+/** Presets d'app : la vitrine complète (défaut) ou la base saine http+framework. */
+export declare const PRESET_CHOICES: readonly ["complete", "minimal"];
+export type TPresetChoice = (typeof PRESET_CHOICES)[number];
+/**
+ * Base SQL de développement — le dialecte que l'app vise, choisi À LA CRÉATION.
+ *
+ * `sqlite` reste le défaut : c'est le seul qui n'exige aucun service, et la
+ * promesse du framework est qu'une app fraîche démarre sans rien allumer. Les
+ * trois autres ne changent RIEN dans le code de l'app (l'ORM déduit le dialecte
+ * du scheme de `NF_DATABASE_URL`) — ils décident du service que l'infra de dev
+ * fournit, et de l'URL qui la joint.
+ */
+export declare const DATABASE_CHOICES: readonly ["sqlite", "postgres", "mariadb", "mysql"];
+export type TDatabaseChoice = (typeof DATABASE_CHOICES)[number];
+/** Saveurs de controller : le WS est TOUJOURS là (différenciateur Nodefony). */
+export declare const CONTROLLER_KIND_CHOICES: readonly ["hello", "rest", "duplex", "realtime", "example"];
+export type TControllerKindChoice = (typeof CONTROLLER_KIND_CHOICES)[number];
+/**
+ * Saveurs de controller posables AVEC le module — les mêmes que `create
+ * controller` (le scaffold module DÉLÈGUE, il ne duplique aucun template),
+ * plus `none` pour une coquille nue.
+ */
+export declare const MODULE_CONTROLLER_CHOICES: readonly ["none", "hello", "rest", "duplex", "realtime", "example"];
+export type TModuleControllerChoice = (typeof MODULE_CONTROLLER_CHOICES)[number];
+/**
+ * Phases de boot proposées comme point d'exécution d'une commande.
+ *
+ * C'est le `kernelEvent` de `OptionsCommandInterface` — le kernel s'ARRÊTE à
+ * cette phase. Trois valeurs suffisent à couvrir les usages réels ; les autres
+ * phases (`onPreBoot`, `onServersReady`…) restent atteignables en éditant le
+ * fichier généré, mais n'ont pas à être proposées à qui crée sa première
+ * commande.
+ */
+export declare const COMMAND_PHASE_CHOICES: readonly ["onReady", "onRegister", "onPostReady"];
+export type TCommandPhaseChoice = (typeof COMMAND_PHASE_CHOICES)[number];
+/** Stratégies de clé primaire proposées par `create entity`. */
+export declare const ENTITY_ID_CHOICES: readonly ["uuid7", "uuid4", "serial"];
+export type TEntityIdChoice = (typeof ENTITY_ID_CHOICES)[number];
+/**
+ * La spec complète du scaffold — contrat des trois fronts (CLI rapide,
+ * CLI interactif, Studio). Structure 100 % sérialisable en JSON.
+ */
+export declare function getScaffoldSpec(type?: string): IScaffoldTypeSpec[];

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

@@ -0,0 +1,24 @@
+/**
+ * Étapes qui SUIVENT l'écriture d'un scaffold.
+ *
+ * Le moteur (`engine.ts`) est pur : il écrit des fichiers et s'arrête là. Mais
+ * du code écrit n'est pas encore du code qui tourne — il reste à installer les
+ * dépendances, construire, vérifier les types. Ces étapes sont donc décrites
+ * ICI, une fois, et exécutées par chaque front à sa façon : le CLI hérite du
+ * terminal de l'utilisateur, Studio streame chaque ligne sur un canal temps
+ * réel. Les deux manières de LES MONTRER sont légitimement différentes ; ce qui
+ * ne doit pas diverger, c'est CE QU'ELLES SONT.
+ *
+ * La commande de chaque étape est figée côté serveur. Un front n'envoie jamais
+ * qu'un identifiant d'étape, jamais une ligne de commande : c'est ce qui sépare
+ * « piloter un générateur » de « exécuter du shell à distance ».
+ */
+/** Étapes possibles, dans leur ordre d'exécution naturel. */
+export declare const SCAFFOLD_STEPS: readonly ["install", "build", "typecheck"];
+export type TScaffoldStep = (typeof SCAFFOLD_STEPS)[number];
+/** Arguments passés à `npm` pour chaque étape. */
+export declare const SCAFFOLD_STEP_COMMANDS: Record<TScaffoldStep, readonly string[]>;
+/** Ce que chaque étape apporte — affiché avant de la lancer. */
+export declare const SCAFFOLD_STEP_LABELS: Record<TScaffoldStep, string>;
+/** Une étape connue ? (garde des entrées venues du réseau). */
+export declare function isScaffoldStep(value: unknown): value is TScaffoldStep;