# NestCraftX — Générateur de Clean Architecture pour NestJS

[![Version NPM](https://img.shields.io/npm/v/nestcraftx?style=flat-square&color=CB3837)](https://www.npmjs.com/package/nestcraftx)
[![Téléchargements](https://img.shields.io/npm/dm/nestcraftx?style=flat-square&color=51a2da)](https://www.npmjs.com/package/nestcraftx)
[![Licence: MIT](https://img.shields.io/badge/Licence-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Version Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-4dc71f?style=flat-square)](https://nodejs.org)

**ORMs:**
![Prisma](https://img.shields.io/badge/Prisma-2D3748?style=flat-square&logo=prisma&logoColor=white)
![TypeORM](https://img.shields.io/badge/TypeORM-FE0803?style=flat-square&logo=typeorm&logoColor=white)
![Mongoose](https://img.shields.io/badge/Mongoose-880000?style=flat-square&logo=mongodb&logoColor=green)

**NestCraftX** est un CLI Node.js moderne et puissant pour générer automatiquement des projets NestJS avec une architecture propre, maintenable et prête pour la production.

Il échafaude tout ce dont vous avez besoin pour démarrer :

- **Modules, Controllers & Services** (Entièrement typés)
- **Repositories & Mappers** (Pour un flux de données propre et une séparation des responsabilités)
- **DTOs** (Avec validation intégrée via class-validator)
- **Entités / Schémas** (Prisma, TypeORM, ou Mongoose)
- **Authentification** (JWT avec Refresh Tokens & génération automatique des secrets)
- **Prêt pour le DevOps** (Docker, Docker-Compose & Swagger UI)

NestCraftX implémente les meilleures pratiques modernes : **Clean Architecture**, **Domain-Driven Design (DDD)**, **Validation stricte**, **Sécurité pré-configurée** et bien plus encore.

### Fonctionnalités Clés :

- **Architecture Double :** Choisissez entre le mode _Light_ (idéal pour les MVPs) ou _Full_ (Clean Architecture / DDD).
- **Relations Interactives :** Définissez vos relations 1-N ou N-N directement depuis votre terminal.
- **Configuration Intelligente :** Décorateurs Swagger automatiques, fichiers .env auto-documentés et connexions aux bases de données pré-configurées.

> **Version 1.0.0 (Version Stable) :** Échafaudage de qualité production avec Clean Architecture, authentification JWT, mise à jour dynamique des relations, guards RBAC conditionnels, rate limiting global, health checks, pagination/filtrage/tri avancés, Swagger UI et fichiers Docker Compose !

---

## Sommaire

- [Nouveautés v1.0.0](#nouveautes-v100-version-stable)
- [Objectif du projet](#objectif-du-projet)
- [Prérequis](#prérequis)
- [Installation](#installation)
- [Commandes disponibles](#commandes-disponibles)
- [Fonctionnalités](#fonctionnalités)
- [Architecture générée](#architecture-générée)
- [Démo complète](#démo-complète)
- [Guide d'utilisation](#guide-dutilisation)
- [Roadmap](#roadmap)
- [Contribuer](#contribuer)
- [Licence](#licence)

---

## Nouveautés v1.0.0 (Version Stable)

### 🔗 Commande de Relation Autonome (`nestcraftx g relation`)
- Créez des relations 1-n, n-1, 1-1, ou n-n entre des **modules existants** à tout moment.
- Met automatiquement à jour les entités de domaine (champs FK et getters), les DTOs (Create et Update) et les mappers de données.
- Synchronise les schémas de base de données (exécution de format, génération du client et migrations dev pour Prisma ; injection de références ObjectId pour Mongoose).

### 🛡️ Guards RBAC Conditionnels & Intégration Swagger
- Les endpoints de mutation (`POST`, `PATCH`, `DELETE`) sont protégés par `JwtAuthGuard` et `RolesGuard` (`@Roles('ADMIN')`) uniquement si l'authentification est active.
- Les endpoints de lecture (`GET`, `GET :id`) sont décorés de `@Public()`.
- Génère une documentation API complète avec `@ApiBearerAuth()` et des réponses d'erreur standardisées lorsque Swagger est activé.

### 🚦 Rate Limiting Global (Module Throttler)
- Intégration du package officiel `@nestjs/throttler` avec des politiques de rate limiting globales pré-configurées (par défaut : 10 requêtes par minute).
- Configurable via les prompts interactifs ou via le flag CLI `--throttler`.

### 🏥 Endpoint de Health Check (`/health`)
- Expose une route native `/health` renvoyant le statut global (`ok`), le timestamp et l'uptime de l'application (`process.uptime()`).
- Entièrement documenté dans Swagger, optimisé sans package tiers lourd pour une compilation ultra-rapide et une sécurité maximale.

### 🚀 Paramètres de Requête Avancés (Pagination, Filtrage, Tri)
- Injection automatique des fonctionnalités de récupération paginée (ex: `?page=1&limit=10&search=...&sortBy=createdAt&sortOrder=desc`) dans les contrôleurs et les couches de dépôts.
- Mappe les paramètres de requête de manière fluide vers les requêtes Prisma, TypeORM ou Mongoose.

### 📋 Rapport de Génération Interactif
- Affichage automatique d'un rapport CLI enrichi encadré en ASCII après chaque génération de module, listant les fichiers générés, les schémas DB mis à jour, les relations établies et les étapes suivantes.

### Exemples Rapides

```bash
# Projet LIGHT avec Prisma et Auth
nestcraftx new mon-api --light --orm=prisma --auth

# Projet FULL avec TypeORM et Swagger
nestcraftx new mon-projet --full --orm=typeorm --swagger

# Projet MongoDB minimal
nestcraftx new mon-api --light --orm=mongoose
```

---

## Objectif du projet

Ne perdez plus de temps à configurer votre architecture backend. NestCraftX vous permet de :

- ✅ Démarrer un projet en quelques minutes au lieu de quelques jours
- ✅ Avoir une architecture Clean dès le départ
- ✅ Uniformiser vos projets avec les mêmes bonnes pratiques
- ✅ Configuration automatiser de BD-ORM et autres modules (decorateur, authentification, dockerisation)
- ✅ Vous concentrer sur la logique métier
- ✅ Choisir entre configuration rapide (Light) ou complète (Full)

## Prérequis

Assurez-vous d'avoir :

- **Node.js** v14 ou supérieur
- **npm** ou **yarn**
- **Nest CLI** (optionnel, sera utilisé via npx)
- **Docker** (optionnel, pour la containerisation)
- **Git** (optionnel, pour la gestion de version)

Vérifiez votre environnement avec :

```bash
nestcraftx test
```

---

## Installation

### Via npx (recommandé)

Utilisez NestCraftX sans installation globale :

```bash
npx nestcraftx new my-app
```

### Installation globale

Pour une utilisation fréquente :

```bash
npm install -g nestcraftx
nestcraftx new my-app
```

### Installation pour développement

```bash
git clone https://github.com/august-dev-pro/NestCraftX.git
cd NestCraftX
npm install
npm link
```

### Exécuter les tests

Nous utilisons Jest pour exécuter les tests unitaires et les tests d'intégration E2E du compilateur :

```bash
# Lancer les tests unitaires (rapides)
npm run test:unit

# Lancer les tests d'intégration E2E (génère un projet, exécute npm install & tsc)
npm run test:e2e

# Lancer tous les tests
npm test
```

---

## Commandes disponibles

### `nestcraftx new <project-name> [options]`

Crée un nouveau projet NestJS avec Clean Architecture.

**Options :**

- `--light` : Mode configuration rapide
- `--orm <prisma|typeorm|mongoose>` : Choix de l'ORM
- `--auth` : Ajouter l'authentification JWT
- `--swagger` : Ajouter Swagger UI
- `--docker` : Générer les fichiers Docker

**Exemples :**

```bash
# Mode interactif complet
nestcraftx new my-app

# Mode rapide avec options
nestcraftx new blog-api --light --orm=prisma --auth --swagger

# Configuration personnalisée
nestcraftx new shop --orm=typeorm --auth
```

### `nestcraftx demo [options]`

Génère un projet de démonstration complet (blog-demo) avec :

- 3 entités (User, Post, Comment) avec relations 1-n
- Auth JWT intégrée
- Swagger activé
- Docker configuré

**Options :**

- `--light` : Mode architecture simplifiée
- `--docker` : Activer Docker (défaut: true)
- `--auth` : Activer Auth JWT (défaut: true)
- `--swagger` : Activer Swagger (défaut: true)
- `--orm <prisma|typeorm|mongoose>` : Choix de l'ORM (défaut: prisma)

**Exemples :**

```bash
# Mode interactif (posera les questions)
nestcraftx demo

# Mode LIGHT avec Mongoose
nestcraftx demo --light --orm=mongoose

# Mode FULL avec TypeORM
nestcraftx demo --orm=typeorm --auth --swagger

# Démarrer rapidement
nestcraftx demo --light --orm=prisma
```

**Résultat :**

Un projet blog fonctionnel avec :

- Blog-demo créé
- 3 entités complètes
- Relations entre User → Post → Comment
- Endpoints auth, users, posts, comments prêts
- Documentation Swagger interactive

### `nestcraftx test`

Vérifie que votre environnement est prêt :

```bash
nestcraftx test
```

Affiche le statut de Node, npm, Nest CLI, Docker, Git, etc.

### `nestcraftx info`

Affiche les informations sur le CLI :

```bash
nestcraftx info
```

---

## Fonctionnalités

### Architecture

✅ **Clean Architecture** avec séparation domain/application/infrastructure/presentation
✅ **Domain-Driven Design** avec entités, use cases et repositories
✅ **Repository Pattern** pour l'abstraction de la persistance
✅ **Use Cases Pattern** pour la logique métier isolée
✅ **Mapper Pattern** pour la transformation des données

### Base de données

✅ **Prisma ➡️ (PostgreSQL)** - ORM moderne et type-safe (recommandé)

✅ **TypeORM ➡️ (PostgreSQL)** - ORM complet avec decorateurs

✅ **Mongoose ➡️ (MongoDB)** - ODM pour MongoDB

✅ Configuration automatique du schéma

✅ Support PostgreSQL et MongoDB

### Sécurité

✅ **JWT Authentication** avec guards et strategies

✅ **Role-based Access Control** (RBAC)

✅ **Password hashing** avec bcrypt

✅ **Public routes** avec decorators

### Documentation

✅ **Swagger UI** automatique

✅ Décorateurs ApiProperty sur les DTOs

✅ Documentation des endpoints

✅ Interface interactive d'API

### DevOps

✅ **Docker** et **Docker Compose**

✅ Configuration des variables d'environnement

✅ Logging structuré

✅ Error handling centralisé

### Qualité du code

✅ Validation des DTOs avec class-validator

✅ Transformation des données avec class-transformer

✅ Intercepteurs de réponse standardisés

✅ Filtres d'exceptions globaux

---

## Generated Architecture

### Mode Light (MVP)

```
src
├── auth
│   ├── controllers
│   │   └── auth.controller.ts
│   ├── dtos
│   │   ├── create-session.dto.ts
│   │   ├── forgotPassword.dto.ts
│   │   ├── loginCredential.dto.ts
│   │   ├── refreshToken.dto.ts
│   │   ├── resetPassword.dto.ts
│   │   ├── sendOtp.dto.ts
│   │   └── verifyOtp.dto.ts
│   ├── entities
│   │   └── session.entity.ts
│   ├── guards
│   │   ├── jwt-auth.guard.ts
│   │   └── role.guard.ts
│   ├── mappers
│   │   └── session.mapper.ts
│   ├── persistence
│   │   └── session.repository.ts
│   ├── services
│   │   ├── auth.service.ts
│   │   └── session.service.ts
│   ├── strategies
│   │   └── jwt.strategy.ts
│   └── auth.module.ts
│
├── common
│   ├── decorators
│   │   ├── current-user.decorator.ts
│   │   ├── public.decorator.ts
│   │   └── role.decorator.ts
│   ├── enums
│   │   └── role.enum.ts
│   ├── filters
│   │   └── all-exceptions.filter.ts
│   ├── interceptors
│   │   └── response.interceptor.ts
│   └── middlewares
│       └── logger.middleware.ts
│
├── prisma
│   ├── prisma.module.ts
│   └── prisma.service.ts
│
├── user
│   ├── controllers
│   │   └── user.controller.ts
│   ├── dtos
│   │   └── user.dto.ts
│   ├── entities
│   │   └── user.entity.ts
│   ├── repositories
│   │   └── user.repository.ts
│   ├── services
│   │   └── user.service.ts
│   └── user.module.ts
│
├── app.controller.spec.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts
```

### Mode Full (Clean Architecture)

```
src
├── auth
│   ├── application
│   │   ├── dtos
│   │   │   ├── create-session.dto.ts
│   │   │   ├── forgotPassword.dto.ts
│   │   │   ├── loginCredential.dto.ts
│   │   │   ├── refreshToken.dto.ts
│   │   │   ├── resetPassword.dto.ts
│   │   │   ├── sendOtp.dto.ts
│   │   │   └── verifyOtp.dto.ts
│   │   └── services
│   │       ├── auth.service.ts
│   │       └── session.service.ts
│   ├── domain
│   │   ├── entities
│   │   │   └── session.entity.ts
│   │   └── interfaces
│   │       └── session.repository.interface.ts
│   ├── infrastructure
│   │   ├── guards
│   │   │   ├── jwt-auth.guard.ts
│   │   │   └── role.guard.ts
│   │   ├── mappers
│   │   │   └── session.mapper.ts
│   │   ├── persistence
│   │   │   └── session.repository.ts
│   │   └── strategies
│   │       └── jwt.strategy.ts
│   ├── presentation
│   │   └── controllers
│   │       └── auth.controller.ts
│   └── auth.module.ts
│
├── common
│   ├── decorators
│   │   ├── current-user.decorator.ts
│   │   ├── public.decorator.ts
│   │   └── role.decorator.ts
│   ├── filters
│   │   └── all-exceptions.filter.ts
│   ├── interceptors
│   │   └── response.interceptor.ts
│   └── middlewares
│       └── logger.middleware.ts
│
├── prisma
│   ├── prisma.module.ts
│   └── prisma.service.ts
│
├── user
│   ├── application
│   │   ├── dtos
│   │   │   └── user.dto.ts
│   │   ├── services
│   │   │   └── user.service.ts
│   │   └── use-cases
│   │       ├── create-user.use-case.ts
│   │       ├── delete-user.use-case.ts
│   │       ├── getAll-user.use-case.ts
│   │       ├── getById-user.use-case.ts
│   │       └── update-user.use-case.ts
│   ├── domain
│   │   ├── entities
│   │   │   └── user.entity.ts
│   │   ├── enums
│   │   │   └── role.enum.ts
│   │   └── interfaces
│   │       └── user.repository.interface.ts
│   ├── infrastructure
│   │   ├── adapters
│   │   │   └── user.adapter.ts
│   │   ├── mappers
│   │   │   └── user.mapper.ts
│   │   └── repositories
│   │       └── user.repository.ts
│   ├── presentation
│   │   └── controllers
│   │       └── user.controller.ts
│   └── user.module.ts
│
├── app.controller.spec.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts
```

## Démo complète

🔥 Une démo prête à exécuter, incluant 3 entités liées, Auth JWT, Swagger, Docker et ORM configurable.

👉 Voir la documentation complète : [Documentation Demo](./DEMO.md)

## Guide d'utilisation

### Démarrage rapide (Mode Light)

```bash
# 1. Créer un projet simple
npx nestcraftx new my-api --light --orm prisma

# 2. Naviguer dans le projet
cd my-api

# 3. Démarrer l'application
npm run start:dev
```

### Configuration complète (Mode Full)

```bash
# 1. Lancer la création avec interface interactive
npx nestcraftx new my-project

# 2. Répondre aux questions :
#    - Nom du projet
#    - Choix de la base de données
#    - Configuration ORM
#    - Entités et relations
#    - Auth et Swagger

# 3. Démarrer
cd my-project
npm run start:dev
```

### Projet de démonstration

```bash
# Générer un projet blog complet (mode interactif)
nestcraftx demo

# Ou avec options directes
nestcraftx demo --light --orm prisma --auth --swagger

# Naviguer et démarrer
cd blog-demo
npm run start:dev

# Accéder à Swagger UI
open http://localhost:3000/api/docs
```

**Qu'inclut le projet demo :**

- Architecture Clean complète (ou LIGHT selon l'option)
- 3 entités pré-configurées : User, Post, Comment
- Relations entre entités (User → Post, Post ↔ Comment)
- Auth JWT avec endpoints /auth/register et /auth/login
- Endpoints métier : /users, /posts, /comments
- Documentation Swagger automatique
- Docker & Docker Compose configurés
- Configuration ORM de votre choix (Prisma, TypeORM, Mongoose)

---

## Feuille de Route (Roadmap)

### Version 0.3.0 — Stabilisation & UX (Terminé)
- [x] Unification du module system CommonJS.
- [x] Version d'aide dynamique et validation interactive des flags.
- [x] Configuration dynamique du package manager.

### Version 0.4.0 — Refactorisation d'Architecture (Terminé)
- [x] Découpage du fichier monolithique utils.js en générateurs spécialisés.
- [x] EntityBuilder interactif basé sur un state avec révision et corrections de champs.
- [x] Mode simulation globale (`--dry-run`).

### Version 0.5.0 — Qualité & Sécurité (Terminé)
- [x] Stockage persistant en DB pour les OTPs et tokens de réinitialisation de mot de passe.
- [x] Pinning strict des versions de dépendances installées par les setups.
- [x] Descriptions Swagger sémantiques contextuelles et saisie optionnelle de descriptions manuelles.

### Version 0.6.0 — Tests & CI/CD (Terminé)
- [x] Couverture de tests unitaires via Jest.
- [x] Tests de compilation E2E du projet généré et résolution des conflits peer deps (NestJS 11).
- [x] Pipeline CI/CD GitHub Actions multi-OS pour Node.js.

### Version 0.7.0 - 0.9.0 — Fonctionnalités Manquantes (En cours)
- [ ] Commande `generate auth` interactive et mode non-interactif complet.
- [ ] Pagination, filtres de requêtes, rate limiting et guards RBAC.
- [ ] Support de MySQL et SQLite.

### Version 1.0.0 — Version Stable
- [ ] Site officiel de documentation.
- [ ] Audit final de production et garanties de support LTS.

## Contribuer

Vous voulez améliorer NestCraftX ? Les contributions sont les bienvenues !

### Comment contribuer

1. Fork le projet
2. Créez une branche pour votre fonctionnalité (`git checkout -b feature/AmazingFeature`)
3. Committez vos changements (`git commit -m 'Add some AmazingFeature'`)
4. Push vers la branche (`git push origin feature/AmazingFeature`)
5. Ouvrez une Pull Request

### Ouvrir une issue

Des bugs ? Des idées ? Ouvrez une issue sur GitHub !

### Développeurs

Pour développer localement :

```bash
git clone https://github.com/august-dev-pro/NestCraftX.git
cd NestCraftX
npm install
npm link
```

---

## Licence

MIT © [Ablanhou Augustin Selete](https://github.com/august-dev-pro)

Libre d'usage pour projets personnels et commerciaux.

---

## Remerciements

Merci à tous les contributeurs et à la communauté NestJS !

**Fait avec ❤️ pour la communauté des développeurs backend**

---

## Contact & Support

- 📧 GitHub Issues : [Ouvrir une issue](https://github.com/august-dev-pro/NestCraftX/issues)
- 🌐 Repository : [NestCraftX sur GitHub](https://github.com/august-dev-pro/NestCraftX)
- ⭐ Si ce projet vous aide, pensez à lui donner une étoile !

---

**NestCraftX v0.6.0** - Clean Architecture Made Simple

Pour plus d'informations:

- [Guide d'utilisation complet](./CLI_USAGE.md)
- [Guide de migration](./MIGRATION_GUIDE.md)
- [Changelog detaille](./CHANGELOG.md)