nestcraftx 0.2.5 → 0.3.0

package/AUDIT_ROADMAP.md

@@ -0,0 +1,798 @@
+# 🔍 Audit Approfondi NestCraftX v0.2.6
+## Rapport complet & Roadmap vers la v1.0 Stable
+
+> **Dernière mise à jour :** 5 juin 2026 — Retours production intégrés
+
+---
+
+## 📊 Vue d'ensemble
+
+| Métrique | État |
+|---|---|
+| Version auditée | 0.2.6 |
+| Fichiers analysés | 40+ fichiers JS |
+| Bugs critiques | 12 (audit) + 5 (prod) = **17** |
+| Mauvaises pratiques majeures | 18 |
+| Manquements d'architecture | 9 |
+| Retours production | 5 confirmés |
+| Priorité globale | 🔴 Haute — Refactorisation avant v1.0 |
+
+---
+
+## 🔴 SECTION 1 — Bugs Critiques (Bloquants en production)
+
+### BUG-01 : Module System incohérent — `utils.js` utilise ESM, le reste CommonJS
+**Fichiers concernés :** [utils.js](file:///e:/packages/NestCraftX/utils/utils.js), [userInput.js](file:///e:/packages/NestCraftX/utils/userInput.js)
+
+```diff
+- import { logInfo } from "./loggers/logInfo.js";   // ESM (utils.js L1)
+- export async function generateEntityFileContent()  // ESM (utils.js L7)
++ const { logInfo } = require("./loggers/logInfo"); // CJS (partout ailleurs)
++ module.exports = { generateEntityFileContent }
+```
+
+> [!CAUTION]
+> `utils.js` et `userInput.js` utilisent `import/export` ESM alors que **TOUT** le reste du projet (shell.js, setupAuth.js, etc.) utilise `require/module.exports` CommonJS. C'est la cause de **crashes au runtime** selon les versions de Node. Le `package.json` n'a pas de `"type": "module"` donc Node traite tout en CJS par défaut → les fichiers ESM plantent à l'import.
+
+**Fix requis :** Migrer `utils.js` et `userInput.js` en CommonJS OU migrer tout le projet en ESM avec `"type": "module"` + `.mjs` extensions.
+
+---
+
+### BUG-02 : `handleAuthGeneration` — Fonction vide avec commentaire TODO
+**Fichier :** [generate.js](file:///e:/packages/NestCraftX/commands/generate.js#L86-L91)
+
+```javascript
+async function handleAuthGeneration(config) {
+  // On réutilisera ton script setupAuth corrigé
+  // await require('../utils/setups/setupAuth')(config);  ← COMMENTÉ
+  logInfo("🚀 Generating module auth...");
+}
+```
+
+> [!CAUTION]
+> La commande `nestcraftx g auth` **ne fait rien**. Elle affiche juste un log. Toute la logique est en commentaire. C'est une feature annoncée mais complètement non-fonctionnelle.
+
+---
+
+### BUG-03 : `hasAllLightModeFlags` / `hasAllFullModeFlags` — Logique inversée
+**Fichier :** [new.js](file:///e:/packages/NestCraftX/commands/new.js#L98-L104)
+
+```javascript
+function hasAllLightModeFlags(flags) {
+  if (!flags.interactive || flags.interactive === false) {
+    return false;  // ← RETOURNE false si PAS interactif = jamais de mode non-interactif
+  }
+  return true;
+}
+```
+
+> [!CAUTION]
+> La condition est **logiquement inversée**. Le flag `--interactive` n'existe pas dans le CLI — cette fonction retourne TOUJOURS `false`, ce qui signifie que `buildLightModeFromFlags()` et `buildFullModeFromFlags()` ne sont **jamais appelées**. Le mode non-interactif est donc **totalement cassé**. Même problème pour `hasAllFullModeFlags`.
+
+**Ce que ça devrait faire :** vérifier si tous les flags requis sont présents (`--orm`, etc.) pour éviter le mode interactif.
+
+---
+
+### BUG-04 : `createFile` ne protège pas les fichiers existants
+**Fichier :** [userInput.js](file:///e:/packages/NestCraftX/utils/userInput.js#L341-L352)
+
+```javascript
+export async function createFile(fileData) {
+  try {
+    if (!fs.existsSync(fileData.path)) {
+      fs.writeFileSync(`${fileData.path}`, `${fileData.contente}`);
+    } else {
+      console.log(`Existing file : ${fileData.path}`);
+      fs.writeFileSync(`${fileData.path}`, `${fileData.contente}`); // ← ÉCRASE QUAND MÊME
+    }
+  }
+```
+
+> [!CAUTION]
+> Le log dit "Existing file" mais **écrase quand même** le fichier. Lors d'un `nestcraftx g module`, les fichiers manuellement modifiés par l'utilisateur sont **silencieusement écrasés**.
+
+---
+
+### BUG-05 : `setupPrisma` — Double écriture du `.env` qui efface le contenu
+**Fichiers :** [setupPrisma.js](file:///e:/packages/NestCraftX/utils/setups/setupPrisma.js#L44-L57), [envGenerator.js](file:///e:/packages/NestCraftX/utils/envGenerator.js)
+
+Le flow est :
+1. `setupPrisma` crée un `.env` minimal avec juste `DATABASE_URL`
+2. Puis `generateEnvFile` + `writeEnvFile` **recrée** le `.env` complet
+
+→ L'ordre est bon dans `new.js` (`setupDatabase` avant `generateEnvFile`) MAIS dans `setupPrisma`, un `.env` minimal est créé à la ligne 49 qui sera de toute façon **écrasé** plus tard, créant de la confusion et des edge cases selon les ORMs.
+
+---
+
+### BUG-06 : `setupAuth` — Hardcode `npm install` ignorer `packageManager`
+**Fichier :** [setupAuth.js](file:///e:/packages/NestCraftX/utils/setups/setupAuth.js#L16-L23)
+
+```javascript
+await runCommand(
+  `npm install @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt uuid`,
+  "Erreur install deps auth",
+);
+```
+
+> [!CAUTION]
+> **Hardcodé en `npm`**. Si l'utilisateur a choisi `yarn` ou `pnpm`, les dépendances auth sont installées avec npm quand même → conflit lockfile, double installation.
+
+---
+
+### BUG-07 : `setupMongoose` — Surcharge du `.env` incompatible avec `envGenerator`
+**Fichier :** [setupMongoose.js](file:///e:/packages/NestCraftX/utils/setups/setupMongoose.js#L71-L75)
+
+```javascript
+const envContent = `
+MONGO_URI=${inputs.dbConfig.MONGO_URI}
+MONGO_DB=${inputs.dbConfig.MONGO_DB}
+`.trim();
+await createFile({ path: ".env", contente: envContent }); // ← Écrase TOUT le .env
+```
+
+> [!CAUTION]
+> `setupMongoose` écrase le `.env` complet avec seulement 2 variables, PUIS `envGenerator.writeEnvFile` va réécrire. Si l'ordre change, les variables JWT/PORT/NODE_ENV sont perdues.
+
+---
+
+### BUG-08 : `safeUpdateAppModule` — Regex fragile qui casse avec des modules complexes
+**Fichier :** [userInput.js](file:///e:/packages/NestCraftX/utils/userInput.js#L391-L410)
+
+```javascript
+const importsBlockRegex = /imports:\s*\[((.|\\n)*?)\]/m;
+```
+
+> [!WARNING]
+> Cette regex `(.|\\n)*?` avec le flag `m` est **non-greedy** et **arrête au premier `]`** trouvé. Si un module a `TypeOrmModule.forFeature([...])` dans son bloc `imports`, la regex s'arrête au `]` de `forFeature` et retourne un match partiel. Résultat : **imports corrompus** dans `app.module.ts`.
+
+---
+
+### BUG-09 : `setupCleanArchitecture` — `useCases.forEach` avec `async` non-attendu
+**Fichier :** [setupCleanArchitecture.js](file:///e:/packages/NestCraftX/utils/configs/setupCleanArchitecture.js#L131-L305)
+
+```javascript
+useCases.forEach(async (useCase) => {  // ← forEach N'ATTEND PAS les promises
+  // ... await createFile(...)
+});
+```
+
+> [!CAUTION]
+> `Array.forEach` **n'attend pas les Promises**. Les use cases sont écrits en parallèle de façon non contrôlée. Sur des systèmes lents ou avec beaucoup d'entités, certains fichiers peuvent ne pas être créés avant la suite du setup. **Doit être `for...of` avec await**.
+
+---
+
+### BUG-10 : `setupPrisma` — Regex non-échappée dans les remplacements
+**Fichier :** [setupPrisma.js](file:///e:/packages/NestCraftX/utils/setups/setupPrisma.js#L165-L187)
+
+```javascript
+schemaContent.replace(
+  new RegExp(`model ${from} \\{([\\s\\S]*?)\\n\\}`, "m"),
+  ...
+)
+```
+
+Le nom du modèle `from` est injecté directement dans la RegEx **sans échappement**. Si un modèle s'appelait `Order+Item`, cela causerait une RegEx invalide. Par ailleurs, les modèles Prisma sont **case-sensitive** (doivent commencer par une majuscule) mais `from` peut être minuscule.
+
+---
+
+### BUG-11 : `role.guard.ts` généré — `console.log` de debug laissés en production
+**Fichier :** [setupAuth.js](file:///e:/packages/NestCraftX/utils/setups/setupAuth.js#L776-L778)
+
+```typescript
+// Dans le fichier role.guard.ts généré :
+console.log('🔍 Required Roles:', requiredRoles);
+console.log('👤 User Role:', user?.role);
+```
+
+> [!WARNING]
+> Des `console.log` de debug sont générés dans le `RolesGuard` qui sera déployé en production. Fuite d'informations sensibles sur les rôles à chaque requête protégée.
+
+---
+
+### BUG-12 : `getMapper` généré avec commentaire erroné `PostMapper`
+**Fichier :** [utils.js](file:///e:/packages/NestCraftX/utils/utils.js#L165-L170)
+
+```typescript
+// Code généré dans le mapper de TOUTE entité :
+/**
+ * PostMapper transforms data between   ← "Post" hardcodé pour TOUTES les entités
+ * different layers...
+ */
+```
+
+Le commentaire JSDoc est hardcodé avec "PostMapper" pour toutes les entités générées.
+
+---
+
+## 🟠 SECTION 2 — Mauvaises Pratiques Majeures
+
+### MP-01 : `utils.js` — Fichier monolithique de 2198 lignes
+**Fichier :** [utils.js](file:///e:/packages/NestCraftX/utils/utils.js) (66 617 bytes)
+
+> [!WARNING]
+> Un seul fichier contient la logique de génération pour les entités, DTOs, controllers, services, mappers, middlewares, repositories, et les fonctions utilitaires. C'est **insoutenable** pour la maintenance. Doit être découpé en modules dédiés.
+
+**Découpage proposé :**
+- `generators/entity.generator.js`
+- `generators/dto.generator.js`
+- `generators/controller.generator.js`
+- `generators/mapper.generator.js`
+- `generators/repository.generator.js`
+- `generators/service.generator.js`
+
+---
+
+### MP-02 : Duplication massive de code entre `fullModeInput.js` et `lightModeInput.js`
+Les fonctions `addCustomEntities` et `addRelations` sont **dupliquées quasi-identiquement** dans les deux fichiers. La logique de validation des noms, des types de champs, et des relations est répétée.
+
+---
+
+### MP-03 : `generateDtox` vs `generateDto` — Deux versions de la même fonction
+**Fichier :** [utils.js](file:///e:/packages/NestCraftX/utils/utils.js#L214-L479)
+
+Il existe deux fonctions quasi-identiques (`generateDtox` L214 et `generateDto` L481) avec des différences mineures. La première semble être une version abandonnée mais non-supprimée. Confusion lors de la maintenance.
+
+---
+
+### MP-04 : `shell.js` — `process.exit(1)` dans une fonction utilitaire
+**Fichier :** [shell.js](file:///e:/packages/NestCraftX/utils/shell.js#L20)
+
+```javascript
+} catch (error) {
+  logError(errorMessage);
+  fs.appendFileSync("setup.log", ...);
+  process.exit(1);  // ← Force la sortie du processus
+}
+```
+
+Un utilitaire ne devrait **jamais** appeler `process.exit()`. Il doit lancer une exception que l'appelant peut gérer (rollback, cleanup, etc.). Actuellement, toute erreur de commande shell tue le processus sans cleanup.
+
+---
+
+### MP-05 : Absence totale de tests
+**Fichier :** [test.js](file:///e:/packages/NestCraftX/commands/test.js) (153 bytes — juste un stub)
+
+Le `package.json` a `"test": "nestcraftx test"` qui appelle la commande `test` du CLI qui... vérifie juste les outils système (Node, npm). Il n'y a **aucun test unitaire, aucun test d'intégration** sur le générateur lui-même.
+
+---
+
+### MP-06 : `setupAuth` — `inputs` non validé en entrée
+**Fichier :** [setupAuth.js](file:///e:/packages/NestCraftX/utils/setups/setupAuth.js#L7)
+
+La fonction assume que `inputs.dbConfig`, `inputs.useSwagger`, `inputs.mode` existent sans vérification. Un appel depuis `generate.js` avec un config incomplet provoque des erreurs cryptiques.
+
+---
+
+### MP-07 : Code commenté laissé dans le repo
+Présent dans plusieurs fichiers :
+- [cliParser.js](file:///e:/packages/NestCraftX/utils/cliParser.js#L1-L45) : ancienne version de `parseCliArgs` commentée (45 lignes)
+- [setupPrisma.js](file:///e:/packages/NestCraftX/utils/setups/setupPrisma.js#L756-L800) : ancienne version de `updatePrismaSchema` commentée (44 lignes)
+- [setupCleanArchitecture.js](file:///e:/packages/NestCraftX/utils/configs/setupCleanArchitecture.js#L36) : `// "domain/enums"` commenté
+
+---
+
+### MP-08 : `setupLogger.js` — Nom trompeur, ne configure pas un logger
+**Fichier :** [setupLogger.js](file:///e:/packages/NestCraftX/utils/setups/setupLogger.js)
+
+La fonction s'appelle `setupBootstrapLogger` mais elle modifie `main.ts` pour ajouter un bloc try/catch global, `ValidationPipe`, `ConfigService`, et le logger. C'est en réalité un `setupMainTs`. Et elle est appelée **seulement si `useSwagger` est faux** dans [new.js](file:///e:/packages/NestCraftX/commands/new.js#L256-L260), ce qui signifie que si Swagger est activé, le bootstrap logger **n'est pas configuré** — la logique de setup de `main.ts` est dans `setupSwagger.js` à la place.
+
+---
+
+### MP-09 : `generateConf.js` — Détection ORM incorrecte (ordre priorité)
+**Fichier :** [generateConf.js](file:///e:/packages/NestCraftX/commands/generateConf.js#L31-L38)
+
+```javascript
+let orm = "prisma"; // par défaut
+if (deps["@nestjs/mongoose"] || deps["mongoose"]) {
+  orm = "mongoose";
+} else if (deps["@nestjs/typeorm"] || deps["typeorm"]) {
+  orm = "typeorm";
+} else if (fs.existsSync(path.join(root, "prisma"))) {
+  orm = "prisma";
+}
+```
+
+Si un projet a à la fois `mongoose` ET `typeorm` installés (cas réel lors de migrations), la détection retourne `mongoose` même si le projet principal est TypeORM.
+
+---
+
+### MP-10 : `new.js` — Gestion incohérente sans `projectName`
+**Fichier :** [new.js](file:///e:/packages/NestCraftX/commands/new.js#L24-L54)
+
+Quand `projectName` est absent, la fonction appelle `getFullModeInputs` directement, ignorant `flags.light`. On ne peut jamais créer un projet LIGHT sans nom en argument.
+
+---
+
+### MP-11 : `configureDocker` appelé sans vérification du CWD
+**Fichier :** [configureDocker.js](file:///e:/packages/NestCraftX/utils/configs/configureDocker.js)
+
+Docker est configuré APRÈS `process.chdir(projectName)` dans `createProject`, mais si `createProject` échoue à mi-chemin (ex: npm install timeout), le CWD reste dans le dossier projet partiellement créé → les étapes suivantes écrivent dans un projet cassé.
+
+---
+
+### MP-12 : `help.js` — Version hardcodée `v0.2.5` au lieu de lire `package.json`
+**Fichier :** [help.js](file:///e:/packages/NestCraftX/commands/help.js#L5)
+
+```javascript
+║              🌟 NestCraftX CLI v0.2.5 🌟                  ║  // ← v0.2.5 alors que package.json = v0.2.6
+```
+
+La version dans `help.js` est différente de `package.json`. À chaque release, il faudra mettre à jour manuellement.
+
+---
+
+### MP-13 : `envGenerator.js` — JWT secrets générés même si `useAuth = false`
+**Fichier :** [envGenerator.js](file:///e:/packages/NestCraftX/utils/envGenerator.js#L9-L36)
+
+Les secrets JWT sont toujours générés dans le `.env` même si `inputs.useAuth = false`. Ça ne casse rien mais pollue la config.
+
+---
+
+### MP-14 : `fullModeInput.js` — `getPackageManager` importé de `utils.js` ESM
+**Fichier :** [fullModeInput.js](file:///e:/packages/NestCraftX/utils/fullModeInput.js#L6)
+
+```javascript
+const { getPackageManager } = require("./utils"); // ← utils.js est en ESM !
+```
+
+Cela devrait crasher à l'exécution sur Node sans flag `--experimental-require-module`.
+
+---
+
+### MP-15 : Adapter généré est un template générique inutile
+**Fichiers :** [setupCleanArchitecture.js](file:///e:/packages/NestCraftX/utils/configs/setupCleanArchitecture.js#L387-L415)
+
+L'adapter généré pour chaque entité est un template vide avec des propriétés génériques `name`, `description` qui n'ont aucun rapport avec l'entité réelle. C'est du boilerplate trompeur.
+
+---
+
+### MP-16 : `setupAuth` — OTP stocké en mémoire (`Map`)
+**Fichier :** [setupAuth.js](file:///e:/packages/NestCraftX/utils/setups/setupAuth.js#L263)
+
+```typescript
+// Généré dans auth.service.ts :
+private otps = new Map<string, string>();
+```
+
+Les OTPs sont stockés **en mémoire process**. En production avec plusieurs instances ou après un redémarrage, tous les OTPs sont perdus. C'est un antipattern pour de la production.
+
+---
+
+### MP-17 : `setupAuth` — Oubli du `resetPassword` — Token ignoré
+**Fichier :** [setupAuth.js](file:///e:/packages/NestCraftX/utils/setups/setupAuth.js#L372-L381)
+
+```typescript
+async resetPassword(dto: ResetPasswordDto) {
+  const existingUser = await this.userRepository.findByEmail(dto.email);
+  if (!existingUser) throw new UnauthorizedException('Invalid reset token');
+  // ← Le token de reset n'est JAMAIS validé, n'importe qui connaissant l'email peut reset
+```
+
+Le token de réinitialisation généré dans `forgotPassword` (un UUID en console) n'est **jamais stocké ni validé** dans `resetPassword`. N'importe qui avec l'email peut changer le mot de passe.
+
+---
+
+### MP-18 : `cleanModuleGenerator` — Condition de relation toujours vraie
+**Fichier :** [cleanModuleGenerator.js](file:///e:/packages/NestCraftX/utils/generators/cleanModuleGenerator.js#L87-L90)
+
+```javascript
+if (
+  entityData.relation &&
+  (entityData.relation.type != "1-n" || entityData.relation.type != "n-n")
+) {
+```
+
+La condition `(type != "1-n" || type != "n-n")` est **logiquement TOUJOURS vraie** (De Morgan). Pour `type = "1-n"` : `false || true = true`. Pour `type = "n-n"` : `true || false = true`. Donc tous les types de relations déclenchent le patch.
+
+---
+
+## 🟡 SECTION 3 — Manquements d'Architecture
+
+### MA-01 : Absence de système de rollback
+Si une étape échoue à mi-génération (ex: `setupAuth` après `setupCleanArchitecture`), le projet reste dans un état **partiellement généré et cassé**. Aucun rollback ni cleanup.
+
+### MA-02 : `process.chdir` dans `createProject` — Effet de bord global dangereux
+`process.chdir(inputs.projectName)` est un effet de bord permanent qui affecte **tout le process Node**. Si une fonction est appelée avant le `chdir` (race condition), elle opère dans le mauvais répertoire.
+
+### MA-03 : Pas de validation de l'état final du projet généré
+Après génération, aucune vérification que le projet compile (`tsc --noEmit`), que les imports sont valides, ou que les modules NestJS sont correctement câblés.
+
+### MA-04 : Mixage CJS/ESM sans `package.json` `"type"` défini
+Sans `"type": "module"`, Node traite tout en CJS. Les fichiers `.js` avec `import/export` plantent. Il faut décider et unifier.
+
+### MA-05 : `demo.js` duplique tout le code de `new.js`
+La commande `demo` répète le même flow que `new` (`createProject → setup → auth → swagger → docker → env`). Si ce flow change, il faut le maintenir dans 2 endroits.
+
+### MA-06 : Absence de gestion des versions dépendances générées
+Les dépendances installées dans les projets générés (NestJS, Prisma, TypeORM...) ne sont pas pinnées à des versions compatibles. Un projet généré aujourd'hui vs dans 6 mois peut avoir des incompatibilités majeures.
+
+### MA-07 : `userInput.js` mélange UI, logique, et I/O fichier
+`userInput.js` contient des fonctions d'entrée utilisateur (UI), de création de fichiers (I/O), des fonctions utilitaires (`capitalize`, `decapitalize`) et même des fonctions d'anciens flows (`getUserInputs2`). Violation du Principe de Responsabilité Unique.
+
+### MA-08 : Absence de mode `--dry-run`
+Impossible de voir ce que le CLI va générer sans réellement générer. Un `--dry-run` est essentiel pour tester et documenter.
+
+### MA-09 : Pas de gestion du timeout sur `execSync`
+`runCommand` utilise `execSync` sans timeout. Si `npm install` hang indefiniment (réseau lent, proxy), le CLI attend indéfiniment sans feedback.
+
+---
+
+## 🔥 SECTION 3.5 — Retours Production Confirmés (v0.2.6)
+
+> Ces 5 problèmes ont été rencontrés en utilisation réelle. Ils viennent renforcer et préciser certains bugs déjà listés, ou ajoutent des cas non couverts par l'audit statique.
+
+---
+
+### PROD-01 🔴 — Champs Prisma des relations mal générés + crash `prisma format` bloquant
+**Criticité : CRITIQUE — Phase 0**
+
+**Ce qui se passe :**
+- Les noms de modèles dans le schéma Prisma sont parfois en minuscules (ex: `model user`) alors que Prisma exige une **majuscule initiale** (`model User`). Les relations générées avec `from`/`to` en minuscule produisent un schema invalide.
+- Le champ FK (`userId String`) est parfois dupliqué dans le modèle target car la logique de déduplication de `addedFields` n'est appliquée qu'au premier pass, pas lors de l'injection des relations.
+- La relation inverse en n-n ajoute `${from}s` mais si le pluriel est déjà existant (user → sessions), on obtient `sessions sessions[]` au lieu de `Session[]`.
+
+**Ce qui crashe tout :**
+```javascript
+// setupPrisma.js L292
+await runCommand(`npx prisma format`, "❌ Failed to format prisma schema");
+// shell.js L20
+process.exit(1);  // ← Tout crash ici, rien ne continue
+```
+
+`prisma format` échoue si le schema est invalide → `runCommand` appelle `process.exit(1)` → **le projet reste à moitié généré**, sans message clair pour l'utilisateur.
+
+**Fix à apporter :**
+1. Forcer la capitalisation des noms de modèles dans le schema (`capitalize(from)`, `capitalize(to)`)
+2. Corriger la déduplication des FKs lors du 2e pass (injection relations)
+3. Remplacer le crash `process.exit` par une **dégradation gracieuse** : continuer la génération, écrire le schema tel quel, et afficher un avertissement `⚠️ Le schema Prisma contient des erreurs — lancez 'npx prisma format' manuellement`
+
+---
+
+### PROD-02 🟠 — Descriptions Swagger des DTOs trop génériques
+**Criticité : MAJEURE — Phase 2**
+
+**Ce qui se passe :**
+```typescript
+// Actuellement généré pour TOUS les champs non-reconnus :
+@ApiProperty({ example: 'title_val', description: 'The title of the post' })
+title!: string;
+```
+
+La fonction `getFieldDescription` dans `utils.js` (L237-L246) utilise des heuristiques basiques (`includes('email')`, `includes('password')`) et retourne `The ${f.name} of the ${entityName}` pour tout le reste — ce qui est redondant et inutile pour un consumer d'API.
+
+**Ce qui manque avant la v1 :**
+- Décrire le **format attendu** (longueur min/max, pattern, unité)
+- Indiquer si le champ est **requis ou optionnel** dans la description
+- Adapter la description selon le **contexte** (champ d'update vs création)
+- Permettre la **saisie manuelle** de la description pendant `getFullModeInputs` (option avancée)
+
+**Approche recommandée :**
+Système de **templates de description par catégorie sémantique** (détection plus fine) + prompt optionnel `"Description for field '${name}' [leave empty for auto]:"` dans le flow interactif.
+
+---
+
+### PROD-03 🔴 — Une erreur dans un module crashe toute la génération
+**Criticité : CRITIQUE — Phase 0**
+
+**Ce qui se passe :**
+Si par exemple la génération du repository de l'entité `Product` échoue (fichier corrompu, permission, ORM mal configuré), `process.exit(1)` dans `shell.js` tue tout le processus — les entités `User`, `Post` déjà générées restent en état partiel, et l'entité `Comment` n'est jamais générée.
+
+**Le problème fondamental :** `runCommand` dans `shell.js` est un point de défaillance unique pour TOUT le setup :
+```javascript
+// shell.js — appelé partout
+async function runCommand(command, errorMessage) {
+  try {
+    execSync(command, ...);
+  } catch (error) {
+    logError(errorMessage);
+    process.exit(1);  // ← NUCLEAR OPTION
+  }
+}
+```
+
+**Fix requis :**
+- Distinguer les erreurs **fatales** (npm install qui échoue) des erreurs **récupérables** (prisma format, migration)
+- Pour les erreurs récupérables : logger le warning, continuer, ajouter à un rapport final `setup.log`
+- Afficher en fin de génération un **résumé des warnings** : `⚠️ 2 étapes ont échoué — voir setup.log`
+- Ajouter un paramètre `{ critical: boolean }` à `runCommand`
+
+---
+
+### PROD-04 🟠 — Saisie des champs dans les inputs — Pas assez sécurisée ni flexible
+**Criticité : MAJEURE — Phase 1**
+
+**Ce qui se passe actuellement :**
+```javascript
+// fullModeInput.js L348
+let fname = readline.question("  Field name (leave empty to finish) : ");
+if (!fname) break;  // ← Quitter immédiatement
+// Si nom invalide → continue (recommence la boucle) mais perd le contexte
+```
+
+**Problèmes observés en prod :**
+1. **Validation trop stricte sans feedback clair** : L'utilisateur tape `user-name` (avec tiret) → erreur → recommence, mais ne voit pas clairement pourquoi
+2. **Pas de `unique` flag** : Impossible de marquer un champ comme `@unique` (ex: email) lors de la saisie — hardcodé uniquement pour `email` dans l'entité User
+3. **Pas de `nullable` flag** : Impossible de rendre un champ optionnel lors de la saisie
+4. **Pas de `default` value** : Impossible de définir une valeur par défaut (ex: `isActive` → `true`)
+5. **Saisie linéaire irréversible** : Une fois un champ ajouté, impossible de revenir en arrière pour le modifier ou le supprimer
+
+**Approche recommandée (Phase 1) :** Afficher un **résumé interactif des champs** après chaque ajout avec option de modification/suppression via Inquirer, et étendre les options de champ.
+
+---
+
+### PROD-05 🟠 — Impossible de modifier/supprimer/corriger un champ après confirmation
+**Criticité : MAJEURE — Phase 1**
+
+**Ce qui se passe :**
+Une fois qu'un champ est ajouté (ou qu'une entité est confirmée), il n'y a **aucun moyen de revenir en arrière** :
+- Mauvais nom de champ tapé → il faut relancer tout le CLI
+- Mauvais type sélectionné → idem
+- Champ ajouté en double par erreur → idem
+- Entité mal nommée → idem
+
+En production, cela signifie relancer le générateur entier à cause d'une faute de frappe.
+
+**Ce qui est attendu pour v1 :**
+Après chaque entité finalisée, afficher un **écran de révision interactif** :
+```
+✅ Entity "Product" — 4 fields:
+  1. name       : string
+  2. price      : number
+  3. isActive   : boolean
+  4. userId     : string
+
+? What do you want to do?
+  ❯ ✅ Confirm and continue
+    ✏️  Edit a field
+    ➕ Add another field
+    🗑️  Delete a field
+    ✏️  Rename the entity
+    ❌ Cancel this entity
+```
+
+Cela nécessite une refonte complète du flow d'input vers un **modèle basé sur un state** (pas de boucles while linéaires).
+
+---
+
+## 🟢 SECTION 4 — Points Positifs
+
+- ✅ **Architecture générale bien pensée** : séparation commands/utils/generators/setups
+- ✅ **Support multi-ORM** (Prisma, TypeORM, Mongoose) avec logique spécifique par ORM
+- ✅ **Génération JWT complète** (access + refresh token + session management)
+- ✅ **envGenerator** avec secrets crypto-générés automatiquement
+- ✅ **Mode Light vs Full** bien distincts
+- ✅ **Détection des fichiers existants** dans `generateConf`
+- ✅ **Relations entre entités** (1-1, 1-n, n-1, n-n) gérées dans le schéma Prisma
+- ✅ **Swagger auto-documenté** avec exemples dynamiques par type de champ
+- ✅ **Session-based auth** avec guard + stratégie JWT bien structurés
+- ✅ **Demo command** fonctionnelle pour onboarding rapide
+
+---
+
+## 🗺️ ROADMAP vers la v1.0 Stable
+
+### Phase 0 : Stabilisation d'urgence (v0.3.0) — 2-3 semaines
+> Corriger TOUS les bugs bloquants avant tout autre développement. Aucune nouvelle feature.
+
+#### 0A — Crash & Stabilité (les plus urgents)
+- [ ] **[PROD-03] Refactoriser `runCommand`** : Ajouter paramètre `{ critical: boolean }` — les erreurs non-critiques (prisma format, migrate) ne doivent plus appeler `process.exit(1)`. Logger dans `setup.log` et continuer.
+- [ ] **[PROD-01] Dégradation gracieuse Prisma** : Si `prisma format` ou `prisma generate` échouent → afficher `⚠️ Schema Prisma invalide — continuons la génération. Corrigez manuellement avec 'npx prisma format'` au lieu de crasher
+- [ ] **[PROD-01] Capitalisation modèles Prisma** : Forcer `capitalize(from)` et `capitalize(to)` dans toutes les regex de relations du schema pour respecter la convention Prisma
+- [ ] **[PROD-01] Déduplication FK** : Corriger le double pass de génération de champs FK pour éviter les doublons dans le schema (`userId` dupliqué)
+- [ ] **[BUG-09] `forEach` async → `for...of`** dans `setupCleanArchitecture` (use cases non attendus)
+- [ ] **[BUG-01] Unifier le module system** : Convertir `utils.js` + `userInput.js` en CommonJS (ou tout en ESM avec `"type": "module"`)
+
+#### 0B — Comportement incorrect
+- [ ] **[BUG-03] Fixer `hasAllLightModeFlags`/`hasAllFullModeFlags`** : Logique correcte — `return flags.orm !== undefined` (vérifier la présence des flags réels)
+- [ ] **[BUG-06] Fixer `setupAuth`** : Utiliser `inputs.packageManager` au lieu de `npm` hardcodé
+- [ ] **[BUG-07] Fixer `setupMongoose`** : Ne plus écraser le `.env` complet — utiliser `updateFile` pour ajouter seulement les variables manquantes
+- [ ] **[BUG-04] Fixer `createFile`** : L'option `overwrite: false` ne doit **vraiment pas** écraser — loguer et skipper proprement
+- [ ] **[BUG-08] Corriger la regex AppModule** dans `safeUpdateAppModule` (utiliser un parser AST ou une regex non-greedy correcte sur les imports)
+
+#### 0C — Nettoyage immédiat
+- [ ] **[BUG-12] Fixer `help.js`** : Lire la version depuis `package.json` dynamiquement
+- [ ] **[MP-07] Supprimer le code mort** : Code commenté dans `cliParser.js` (45 lignes) et `setupPrisma.js` (44 lignes)
+- [ ] **[BUG-02] `handleAuthGeneration`** : Soit implémenter, soit retourner un message clair `"nestcraftx g auth n'est pas encore disponible en v0.3 — prévu en v0.7"`
+- [ ] **[BUG-11] Retirer `console.log` debug** du `RolesGuard` généré
+- [ ] **[BUG-12b] Corriger le commentaire `PostMapper`** hardcodé dans le mapper généré
+
+---
+
+### Phase 1 : Refactorisation Architecture (v0.4.0) — 3-4 semaines
+> Rendre le code maintenable et testable. Fondations pour tout ce qui suit.
+
+#### 1A — Découpage des gros fichiers
+- [ ] **[MP-01] Éclater `utils.js`** (2198 lignes) en modules dédiés :
+  - `generators/entity.generator.js`
+  - `generators/dto.generator.js`
+  - `generators/controller.generator.js`
+  - `generators/mapper.generator.js`
+  - `generators/service.generator.js`
+  - `generators/module.generator.js`
+  - `utils/helpers.js` (capitalize, decapitalize, pluralize)
+- [ ] **[MP-07] Éclater `userInput.js`** :
+  - `utils/file-system.js` (createFile, createDirectory, updateFile)
+  - `utils/app-module.updater.js` (safeUpdateAppModule)
+  - `utils/string-utils.js` (capitalize, decapitalize)
+- [ ] **[MP-03] Supprimer `generateDtox`** (doublon de `generateDto`) et n'avoir qu'une seule fonction
+
+#### 1B — Refonte du flow d'input entités (PROD-04 + PROD-05)
+- [ ] **[PROD-04] Étendre le modèle de champ** : Ajouter `unique`, `nullable`, `default` aux options lors de la saisie interactive d'un champ
+  ```
+  ? Is this field unique? (y/N)
+  ? Is this field nullable/optional? (y/N)
+  ? Default value? (leave empty for none)
+  ```
+- [ ] **[PROD-05] Écran de révision d'entité** : Après saisie de tous les champs, afficher un menu de révision avec Inquirer :
+  - Modifier un champ existant (nom, type, options)
+  - Supprimer un champ
+  - Ajouter un champ supplémentaire
+  - Renommer l'entité
+  - Annuler cette entité
+- [ ] **[PROD-04/05] Refonte en modèle state-based** : Remplacer les boucles `while(true)` linéaires par un objet `EntityBuilder` avec état mutable et navigable
+- [ ] **[MP-02] Déduplication** : Extraire `addCustomEntities` et `addRelations` en fonctions communes partagées entre `fullModeInput.js` et `lightModeInput.js`
+
+#### 1C — Architecture générale
+- [ ] **[MA-05] Extraire le flow commun** de `demo.js` vers `new.js` (DRY — même pipeline `createProject → setup → auth → ...`)
+- [ ] **[MP-04] Remplacer `execSync` par `execa`** (ou `child_process.spawn`) avec timeout configurable et streaming output
+- [ ] **[MA-01] Créer un mécanisme de rapport final** : Au lieu de crasher, accumuler les warnings et les afficher en bloc en fin de génération
+- [ ] **[MA-02] Isoler `process.chdir`** : Ne l'appeler qu'une fois, vérifier le CWD avant chaque opération I/O
+- [ ] **Ajouter `--dry-run`** flag pour simuler sans écrire
+
+---
+
+### Phase 2 : Qualité & Sécurité (v0.5.0) — 2-3 semaines
+> Corriger les mauvaises pratiques, sécuriser le code généré, améliorer l'expérience
+
+#### 2A — Sécurité du code généré
+- [ ] **[MP-17] Corriger `resetPassword`** : Stocker et valider le token de reset (table `PasswordReset` ou cache Redis)
+- [ ] **[MP-16] Corriger les OTPs** : Utiliser la table DB ou Redis au lieu du `Map` en mémoire
+- [ ] **[MA-06] Pinning des versions** : Spécifier des ranges semver stricts pour les dépendances générées (NestJS, Prisma, etc.)
+
+#### 2B — Descriptions Swagger (PROD-02)
+- [ ] **[PROD-02] Système de descriptions sémantiques** : Remplacer les heuristiques basiques par un système de templates par catégorie :
+  - Champs de date → `"ISO 8601 date string (e.g. 2024-01-15T10:30:00Z)"`
+  - Champs de prix/montant → `"Decimal value in USD (e.g. 99.99)"`
+  - Champs `*Id` → `"UUID of the referenced ${entityName} (e.g. 550e8400...)"`
+  - Champs boolean → `"true/false flag — default: false"`
+- [ ] **[PROD-02] Description manuelle optionnelle** : Dans `getFullModeInputs`, ajouter un prompt optionnel par champ : `"Description [auto]: "` — si laissé vide, utiliser l'auto-description
+- [ ] **[PROD-02] Description contextuelle Create vs Update** : Le DTO de mise à jour doit indiquer que tous les champs sont optionnels dans la description de classe Swagger
+
+#### 2C — Autres corrections qualité
+- [ ] **[BUG-18] Corriger la condition De Morgan** dans `cleanModuleGenerator` (relation type check)
+- [ ] **[MP-09] Corriger détection ORM** dans `generateConf` (ordre de priorité + cas multi-ORM)
+- [ ] **[MP-13] `envGenerator`** : JWT vars conditionnelles à `useAuth`
+- [ ] **[MP-10] Corriger `new.js`** : Supporter le mode LIGHT sans nom de projet en argument
+- [ ] **Timeout `runCommand`** : Ajouter un timeout de 5 min sur `npm install` avec message d'erreur clair
+
+---
+
+### Phase 3 : Tests & CI/CD (v0.6.0) — 3-4 semaines
+> Zéro regression possible — valider que chaque correction reste correcte
+
+#### 3A — Tests unitaires (Jest)
+- [ ] **Generators** :
+  - `generateDto()` — vérifier output TypeScript valide pour chaque ORM
+  - `generateEntityFileContent()` — vérifier structure domaine
+  - `generateController()` — vérifier routes, guards, decorators
+  - `mapTypeToPrisma()` / `mapTypeToMongoose()` — tous les types (string, Date, enum, array, json)
+- [ ] **Schema Prisma** :
+  - Relations 1-n → vérifier FK, inverse, capitalisation des modèles
+  - Relations n-n → vérifier table pivot ou champs array
+  - Relations 1-1 → vérifier `@unique` sur FK
+  - Déduplication des champs
+- [ ] **CLI Parser** : tous les cas de flags (`--orm`, `--mode`, `--auth`, `-v`, etc.)
+- [ ] **`safeUpdateAppModule`** : différents états d'`app.module.ts` (modules imbriqués, tableau multi-lignes)
+
+#### 3B — Tests d'intégration (E2E Generator)
+- [ ] Générer `test-full-prisma` → vérifier `tsc --noEmit` passe
+- [ ] Générer `test-full-typeorm` → vérifier `tsc --noEmit` passe
+- [ ] Générer `test-full-mongoose` → vérifier `tsc --noEmit` passe
+- [ ] Générer `test-light-prisma` → vérifier `tsc --noEmit` passe
+- [ ] Générer avec auth → vérifier que `auth.module.ts` est correctement câblé
+- [ ] Générer avec relations 1-n → vérifier le schema Prisma résultant
+- [ ] **[PROD-03] Test de résilience** : Simuler une erreur de migration → vérifier que le reste est généré
+
+#### 3C — CI/CD GitHub Actions
+- [ ] Lint (ESLint) sur chaque PR
+- [ ] Tests sur Node 18, 20, 22 LTS
+- [ ] Test de génération sur Ubuntu + Windows (matrix)
+- [ ] Semantic Release automatique (version + CHANGELOG)
+- [ ] Publish automatique sur npm à chaque release
+
+---
+
+### Phase 4 : Features Manquantes (v0.7.0 → v0.9.0) — 4-6 semaines
+> Compléter les features pour être v1.0-ready
+
+#### 4A — Features CLI
+- [ ] **`nestcraftx g auth`** — Implémenter complètement (ajouter auth post-création dans un projet existant)
+- [ ] **Mode non-interactif complet** — Tous les flags documentés et fonctionnels (`--orm`, `--auth`, `--swagger`, `--docker`, `--db-user`, `--db-pass`, etc.)
+- [ ] **`nestcraftx update`** — Mettre à jour la CLI elle-même (`npm install -g nestcraftx@latest`)
+- [ ] **`nestcraftx list`** — Lister les entités/modules du projet courant (depuis `.nestcraftxrc`)
+- [ ] **`pnpm` support** — En plus de npm/yarn (déjà dans les menus demo mais pas implémenté)
+
+#### 4B — Qualité du code généré
+- [ ] **Pagination** dans les controllers et repositories générés (GET all avec `?page=1&limit=10`)
+- [ ] **Filtering & Sorting** params query sur les endpoints GET all
+- [ ] **Rate limiting** global (`@nestjs/throttler`) dans le projet généré
+- [ ] **Health check endpoint** (`/health`) avec `@nestjs/terminus`
+- [ ] **Exception filter global** typé (remplacer les erreurs 500 brutes)
+- [ ] **Guards RBAC** conditionnels sur les endpoints selon les roles détectés
+- [ ] **Support MySQL/SQLite** en plus de PostgreSQL pour Prisma/TypeORM
+
+#### 4C — Expérience développeur
+- [ ] **Téléchargement de templates** depuis GitHub pour permettre la personnalisation (`nestcraftx template use <url>`)
+- [ ] **`nestcraftx g relation`** — Ajouter une relation entre deux modules existants sans re-générer
+- [ ] **Rapport de génération** en fin de commande : tableau récapitulatif des fichiers créés, skippés, en erreur
+
+---
+
+### Phase 5 : Documentation & Site Web (v0.9.x → v1.0.0) — 3-4 semaines
+> Site de documentation officiel
+
+#### Site Documentation (Docusaurus ou VitePress recommandé)
+- [ ] **Création du site** `nestcraftx.dev` avec :
+  - **Getting Started** — Installation, premier projet en 5 minutes
+  - **CLI Reference** — Toutes les commandes avec tous les flags documentés
+  - **Architecture Guide** — Explication de la Clean Architecture générée
+  - **ORM Guide** — Différences Prisma vs TypeORM vs Mongoose
+  - **Auth Deep Dive** — JWT, sessions, guards, roles
+  - **Modes (Light vs Full)** — Quand utiliser quoi
+  - **`nestcraftx g module`** — Guide complet de génération post-projet
+  - **Troubleshooting** — Problèmes courants et solutions
+  - **Migration Guide** — De 0.2.x vers 1.0
+  - **Contributing** — Comment contribuer au projet
+- [ ] **Versioning de la doc** (Docusaurus supporte les versions)
+- [ ] **Playground interactif** — Simuler la génération dans le navigateur
+- [ ] **Dark/Light mode**
+
+---
+
+### Phase 6 : Préparation v1.0 stable (v1.0.0-rc.1) — 1-2 semaines
+> Release candidate
+
+- [ ] **Audit de sécurité** final (secrets, dépendances vulnérables)
+- [ ] **Test complet sur Windows + macOS + Linux**
+- [ ] **Revue de toutes les sorties CLI** (messages, formatage)
+- [ ] **README mis à jour** avec badges CI, version, etc.
+- [ ] **CHANGELOG complet** depuis v0.2.6
+- [ ] **Publication npm** avec tag `@stable`
+- [ ] **Annonce GitHub Release** avec notes détaillées
+
+---
+
+## 📋 Résumé Priorités (Mis à jour avec retours prod)
+
+| Priorité | Phase | Items clés | Durée estimée |
+|---|---|---|---|
+| 🔴 URGENT | Phase 0 — Stabilisation | Crash-proofing, ESM/CJS, relations Prisma, `forEach` async | 2-3 semaines |
+| 🟠 HAUTE | Phase 1 — Refactorisation | `utils.js` split, flow input state-based, révision entités | 3-4 semaines |
+| 🟠 HAUTE | Phase 2 — Qualité & Sécurité | Swagger sémantique, resetPassword, OTP, envGenerator | 2-3 semaines |
+| 🟡 MOYENNE | Phase 3 — Tests & CI/CD | Tests unitaires, E2E, GitHub Actions | 3-4 semaines |
+| 🟡 MOYENNE | Phase 4 — Features | `g auth`, pagination, non-interactif complet | 4-6 semaines |
+| 🟢 NORMALE | Phase 5 — Documentation | Site Docusaurus, CLI reference, guides ORM | 3-4 semaines |
+| 🟢 NORMALE | Phase 6 — Release v1.0 | Audit sécurité, test cross-platform, npm publish | 1-2 semaines |
+| **Total** | | | **~18-26 semaines** |
+
+---
+
+## 🔗 Mapping Retours Prod → Phases
+
+| Retour Prod | Criticité | Phase | Ticket |
+|---|---|---|---|
+| Champs Prisma relations mal générés | 🔴 Critique | Phase 0 | PROD-01 |
+| Crash `prisma format` bloque tout | 🔴 Critique | Phase 0 | PROD-01 |
+| Erreur d'un module crashe tout | 🔴 Critique | Phase 0 | PROD-03 |
+| Descriptions Swagger trop génériques | 🟠 Majeur | Phase 2 | PROD-02 |
+| Saisie champs pas assez flexible/sécurisée | 🟠 Majeur | Phase 1 | PROD-04 |
+| Impossible de modifier/supprimer un champ | 🟠 Majeur | Phase 1 | PROD-05 |
+
+---
+
+> [!NOTE]
+> Ce roadmap est évolutif. Chaque retour prod supplémentaire sera intégré avec sa criticité et placé dans la phase appropriée. L'objectif est de ne jamais bloquer une release pour une feature, mais de toujours corriger d'abord ce qui casse l'expérience utilisateur.
+
+---
+
+*Audit initial : 5 juin 2026 — Retours prod intégrés : 5 juin 2026 — NestCraftX v0.2.6*