nestgen-cli 0.0.7 → 0.2.1

package/readme.md

@@ -1,175 +1,353 @@
-# NestGen
+# NestGen CLI
 
-<div align="center">
-  <img src="https://raw.githubusercontent.com/outis25/nestgen-js/main/assets/logo.png" alt="NestGen Logo" width="200" />
-  <h3>Générateur modulaire autonome pour projets NestJS</h3>
-  <p>Architecture DDD • CQRS • Hexagonal • Prisma/TypeORM • Docker/Swagger</p>
+[![npm](https://img.shields.io/npm/v/nestgen-cli?label=npm)](https://www.npmjs.com/package/nestgen-cli)
+[![CI](https://github.com/el-hack/nestgen-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/el-hack/nestgen-cli/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/nestgen-cli)](LICENSE)
 
-  ![npm](https://img.shields.io/npm/v/@outis25/nestgen?color=crimson&style=for-the-badge)
-  ![nestjs](https://img.shields.io/badge/NestJS-Scaffolded-red?style=for-the-badge&logo=nestjs)
-  ![standalone](https://img.shields.io/badge/100%25-Autonome-brightgreen?style=for-the-badge)
-  ![license](https://img.shields.io/npm/l/@outis25/nestgen?color=blue&style=for-the-badge)
-  ![downloads](https://img.shields.io/npm/dm/@outis25/nestgen?color=green&style=for-the-badge)
-</div>
+NestGen CLI generates NestJS project scaffolding and TypeORM or Prisma resources. The canonical package is [`nestgen-cli`](https://www.npmjs.com/package/nestgen-cli); the canonical repository is [`el-hack/nestgen-cli`](https://github.com/el-hack/nestgen-cli).
 
-## 📋 Table des matières
+## Published in 0.2.1 / Disponible dans 0.2.1
 
-- [Introduction](#-introduction)
-- [Fonctionnalités](#-fonctionnalités)
-- [Installation](#-installation)
-- [Guide d'utilisation](#-guide-dutilisation)
-- [Architecture générée](#-architecture-générée)
-- [Roadmap](#-roadmap)
-- [FAQ](#-faq)
-- [Contribuer](#-contribuer)
-- [Licence](#-licence)
+| Available now / Disponible maintenant                            | Evidence / Preuve                                                                                                                      |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Nest project, module and TypeORM or Prisma resource generation   | The commands are shipped by `nestgen-cli@0.2.1` and covered by the CLI contract tests.                                                 |
+| Declarative resource relations, safe updates and migration plans | The generated manifest protects manual edits; migrations remain explicitly reviewed and applied by the developer.                      |
+| Operational foundation and authorization metadata                | Both are optional extension points; NestGen does not configure an identity provider, a global guard or an external monitoring service. |
+| Store API example                                                | The package ships the [version-pinned example](examples/store-api/README.md), which CI reconstructs from its resource definitions.     |
 
-## 🚀 Introduction
+## Planned (not released) / Prévu (non publié)
 
-**NestGen** est un générateur de code 100% autonome pour NestJS qui vous permet de créer rapidement des projets et des modules respectant les principes d'architecture avancés. Ce package n'a aucune dépendance externe et embarque tous les templates nécessaires pour générer des applications NestJS suivant les modèles Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS) et l'architecture hexagonale.
+The [roadmap](roadmap.md) contains topics under consideration after 0.2.1. They have no release date and are not part of the npm contract until they appear in a versioned guide and `CHANGELOG.md`. La roadmap recense des pistes après 0.2.1 ; elles n’ont ni date de sortie ni engagement de compatibilité avant leur publication dans un guide versionné et le changelog.
 
-Idéal pour les développeurs qui souhaitent maintenir une architecture propre et évolutive, NestGen accélère la phase de setup et garantit la cohérence structurelle de votre application, le tout sans nécessiter d'installation ou de configuration supplémentaire.
+## Supported contract
 
-## ✨ Fonctionnalités
+- Node.js `>=24.15.0 <27` (24, 25 and 26), npm 11, pnpm 10 or Yarn Berry 4. Windows is supported through WSL2 because project generation requires Bash.
+- `init` creates a NestJS project interactively with TypeORM or Prisma.
+- `module <name>` adds the advanced module layout for TypeORM or Prisma.
+- `resource <name>` generates a TypeORM or Prisma REST CRUD: entity or model, DTOs, repository, controller, validation, pagination, `404` and unique-constraint `409`.
+- `doctor`, `--dry-run`, `--help`, `--version`, `--no-interactive` and `--quiet` are scriptable CLI features.
+- Existing Nest projects are supported when `nest-cli.json` declares a custom `sourceRoot`. In a workspace with several applications, pass `--application <name>` to target one application explicitly.
 
-- **100% autonome** - Aucune dépendance externe, tout est intégré
-- **Zéro configuration** - Fonctionne immédiatement après installation
-- **Génération complète** - Projets et modules prêts à l'emploi en quelques secondes
-- **Architecture avancée** - Support intégré pour DDD, CQRS et architecture hexagonale
-- **Templates embarqués** - Tous les templates sont inclus dans le package
-- **Support multiple d'ORM** - TypeORM et Prisma intégrés nativement
-- **DevOps ready** - Configurations Docker, Swagger et CI/CD incluses
-- **Mode interactif** - Interface CLI intuitive avec prompts pour une configuration guidée
+The repository CI executes generator contracts on the declared Node lines and on Linux and macOS. Windows users are supported through WSL2, whose Linux environment is covered by the Ubuntu runner. On Ubuntu/Node 24.15 it additionally validates Prisma, a TypeORM HTTP/PostgreSQL integration, generated Docker configurations, package-manager lockfile creation and locked reinstallation for npm, pnpm and Yarn, and the npm tarball. It does not publish releases or deploy applications. See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact coverage and exclusions.
 
-## 📦 Installation
+## Releases
+
+Create releases from an annotated `vX.Y.Z` tag that points to the commit containing the same version in `package.json` and `package-lock.json`, plus a matching `CHANGELOG.md` section. The tag triggers the release workflow, which builds the package, verifies the tag/commit/version/archive SHA-512 relationship, publishes with npm Trusted Publishing (GitHub OIDC, no npm token in the repository), checks the npm `latest` dist-tag and archive integrity, then installs and runs the published binary in a clean directory.
+
+Before the first release, configure `el-hack/nestgen-cli` as a Trusted Publisher in npm for the `Release` workflow. If publication fails before npm accepts the version, repair the release commit and replace the unpublished tag. If npm has accepted the version but a later registry check fails, do not republish that version: investigate the immutable tarball, correct the issue in a new SemVer version, then publish a new tag. The workflow creates the GitHub release only after the isolated install succeeds.
+
+## Outputs by ORM
+
+| Command                         | ORM     | Persistence output                                                                                                                   |
+| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `resource` (simple or advanced) | TypeORM | Entity and repository using TypeORM; `resource.json` records `orm: "typeorm"`. No Prisma file or import.                             |
+| `resource`                      | Prisma  | Prisma model, Nest module, DTOs, repository and REST controller; `resource.json` records `orm: "prisma"`. No TypeORM file or import. |
+| `module`                        | TypeORM | TypeORM entity and repository, registered with `TypeOrmModule.forFeature`. No Prisma runtime or schema change.                       |
+| `module`                        | Prisma  | Prisma repository, model added to `prisma/schema.prisma`, shared Prisma runtime if absent. No TypeORM file or import.                |
+
+For Prisma, run `npx prisma generate` and apply the schema with `npx prisma db push` or an explicit migration after generating a resource. Selecting an ORM does not convert an existing resource or remove files produced by older generator versions.
+
+## Public demo / Démonstration publique
+
+Install the announced release and verify the exact binary before generating anything. Installez la version annoncée et vérifiez le binaire exact avant toute génération.
 
 ```bash
-npm install -g @outis25/nestgen
+npm install --global nestgen-cli@0.2.1
+nestgen --version # 0.2.1
 ```
 
-C'est tout! Aucune configuration supplémentaire n'est nécessaire. Tous les templates et dépendances sont embarqués dans le package.
+Then follow the [Store API example](examples/store-api/README.md): it generates customers, products, orders and order items; starts PostgreSQL; creates an explicit migration; and runs generated tests. The versioned [guide](docs/versions/0.2.1.md) documents the commands and constraints used by the demo. Ensuite, suivez l’exemple Store API : il couvre la génération, PostgreSQL, une migration explicite, les tests générés et la documentation de la version.
+
+The CI verifies the public commands against the announced package version, reconstructs the example and installs the npm tarball in a clean consumer. It validates reproducibility of these flows, not a production certification / pas une certification de production.
 
-## 🔧 Guide d'utilisation
+## Quickstart — TypeORM resource
 
-### Initialiser un nouveau projet
+The following flow is the supported end-to-end TypeORM path. Prerequisites: Node.js `>=24.15.0 <27`, npm 11 and Docker with Compose. It uses Docker for PostgreSQL and creates an explicit migration.
 
 ```bash
+npm install --global nestgen-cli@0.2.1
+nestgen --version
 nestgen init
 ```
 
-Cette commande lance un assistant interactif qui vous guidera à travers les étapes de configuration :
-- Nom du projet
-- Répertoire d'installation
-- Sélection de l'ORM (TypeORM ou Prisma)
-- Modules à générer automatiquement
-- Options additionnelles (Git, Swagger, Docker, etc.)
+In the interactive prompts, choose `npm`, `typeorm`, Docker enabled, then name the project `store-api`. Continue in the generated project:
 
-### Générer un nouveau module
+```bash
+cd store-api
+nestgen doctor
+nestgen resource product \
+  --orm typeorm \
+  --fields sku:string!,price:number,published:boolean \
+  --route catalog/products \
+  --table catalog_products
+
+cp .env.example .env
+docker compose up --detach postgres
+npx typeorm-ts-node-commonjs migration:generate \
+  src/database/migrations/CreateProducts \
+  --dataSource src/database/data-source.ts
+npx typeorm-ts-node-commonjs migration:run \
+  --dataSource src/database/data-source.ts
+npm run start:dev
+```
+
+In another terminal, verify the generated endpoint:
 
 ```bash
-nestgen module <nom-du-module> [options]
+curl --request POST http://localhost:3000/catalog/products \
+  --header 'content-type: application/json' \
+  --data '{"sku":"sku-001","price":19.9,"published":true}'
+
+curl 'http://localhost:3000/catalog/products?page=1&limit=20'
+
+# Swagger UI, when selected during init
+open http://localhost:3000/api
+
+# Generated unit and database-backed REST tests
+npm test
+docker compose -f test/compose.e2e.yaml up -d --wait
+npm run test:e2e -- product.e2e-spec.ts
+docker compose -f test/compose.e2e.yaml down -v
+
+# Stop the development database when finished
+docker compose down -v
 ```
 
-Options disponibles :
-- `--orm=<typeorm|prisma>` - Spécifie l'ORM à utiliser pour ce module
-- `--crud` - Génère les opérations CRUD de base
-- `--path=<chemin>` - Définit un chemin personnalisé pour le module
+A duplicate `sku` returns HTTP `409`; a malformed `price` returns HTTP `400`; an unknown identifier returns HTTP `404`. The REST test database runs separately on `127.0.0.1:5433`, is reset during the test suite and is removed by the cleanup command. On Windows, open `http://localhost:3000/api` in a browser instead of using `open`.
+
+### English quickstart
+
+Install `nestgen-cli`, run `nestgen init`, choose **npm**, **typeorm** and Docker, then run the same commands above. `resource product --fields sku:string!,price:number,published:boolean` creates the TypeORM CRUD. Start PostgreSQL with `docker compose up -d postgres`, generate and run the migration through `typeorm-ts-node-commonjs`, start NestJS, then use the two `curl` commands to verify create and list operations.
+
+## Maintained Store API example
+
+The published package includes a version-pinned [Store API example](examples/store-api/README.md) with customers, products, orders and order items. Its resource definitions are rebuilt by the CLI in CI, including relation constraints and a migration plan, so the guide stays aligned with the distributed generator. Use it when you need a complete multi-resource starting point rather than the single-product quickstart.
+
+## Commands
+
+```text
+nestgen init
+nestgen module <name> [--orm typeorm|prisma] [--application name] [--dry-run]
+nestgen resource <name> --fields name:type[,name:type] [--route route] [--table table] [--profile simple|advanced] [--application name]
+nestgen config init [--orm typeorm|prisma] [--profile simple|advanced] [--package-manager npm|pnpm|yarn]
+nestgen config show
+nestgen doctor
+```
+
+Pour la CI, `init` accepte toutes les réponses interactives sous forme d’options :
 
-Exemples :
 ```bash
-nestgen module user --orm=typeorm
-nestgen module transaction --orm=prisma --crud
+nestgen init store-api --no-interactive --project-path ./generated --package-manager npm --orm typeorm --docker --swagger --git --modules user,product
 ```
 
-### Vérifier l'installation
+Utilisez `--no-docker`, `--no-swagger`, `--no-operations`, `--no-git` ou `--modules ''` pour les désactiver. En mode non interactif, une option manquante est signalée avant toute écriture ou installation.
+
+### Socle d’exploitation optionnel
+
+Ajoutez `--operations` à `init` pour générer un socle local d’exploitation, sans dépendance à un service tiers. Il expose `GET /health/live` pour la disponibilité du processus et `GET /health/ready` pour la disponibilité de PostgreSQL ; le second renvoie `503` avec l’état de la dépendance lorsque la base est indisponible. Le projet reçoit aussi un middleware `x-request-id`, un logger JSON qui masque les clés sensibles (`password`, `secret`, `token`, `authorization`, `cookie`, `apiKey`) et `enableShutdownHooks()` pour fermer proprement TypeORM ou Prisma sur `SIGTERM` et `SIGINT`. Le contrat et ses limites sont documentés dans `src/operations/README.md` du projet généré.
+
+### Points d’extension d’autorisation
+
+Chaque contrôleur de ressource porte désormais `@ResourceAction('create' | 'list' | 'read' | 'update' | 'delete')`, défini dans `src/app/<ressource>/authorization/resource-policy.ts`. Cette métadonnée est destinée à un guard d’application existant via `Reflector`; NestGen ne configure ni fournisseur d’identité, ni stratégie de connexion, ni guard global.
+
+Pour une règle de propriété, déclarez explicitement le propriétaire (`ownerId:uuid`) puis faites charger la ressource par votre guard avant les actions `read`, `update` et `delete`. Le guard compare l’identité déjà établie par votre application avec `resource.ownerId` et retourne `false` lorsqu’elles diffèrent : Nest renvoie alors `403`, y compris pour les accès inter-utilisateurs. Les actions et le nom de ressource restent disponibles dans `ResourcePolicyMetadata`, ce qui permet de centraliser une politique pour plusieurs ressources tout en conservant les conventions Nest standard.
+
+Fields accepted by `resource` are `string`, `number`, `integer`, `decimal(precision;scale)`, `enum(VALUE|VALUE)`, `boolean`, `date` and `uuid`. Add `?` for a nullable field and `!` for a unique field. A decimal uses a semicolon between precision and scale so a field list can still be separated by commas. Decimals are exposed as JSON strings to preserve their database precision; enums use uppercase values separated by `|`.
+
+`integer` maps to PostgreSQL `integer` / Prisma `Int` and is validated with `@IsInt()`. `decimal(precision;scale)` maps to PostgreSQL `numeric(precision, scale)` / Prisma `Decimal @db.Decimal(precision, scale)` and is validated as a decimal string. `enum(...)` maps to a PostgreSQL enum / a generated Prisma enum and is validated against its declared values.
+
+## Contraintes et index métier
+
+Ajoutez des contraintes après le type entre accolades, séparées par `;` : `length` pour une chaîne, `min` et `max` pour un nombre ou un entier, `default` pour une valeur par défaut compatible, et `index` pour un index simple. Les index composites sont déclarés avec `--indexes`, chaque colonne étant séparée par `+`.
 
 ```bash
-nestgen doctor
+nestgen resource product \
+  --fields sku:string{length=64;index}!,title:string{length=120},quantity:integer{min=0;max=100;default=0},status:enum(DRAFT|ACTIVE){default=DRAFT} \
+  --indexes sku+status
+```
+
+NestGen refuse les combinaisons incompatibles, les bornes inversées et les index qui ciblent un champ absent. Les contraintes sont reflétées dans les DTOs, OpenAPI lorsque Swagger est installé, et les schémas TypeORM ou Prisma. Les index reçoivent un nom déterministe fondé sur la table et leurs colonnes, y compris lorsque PostgreSQL impose une limite de longueur.
+
+## Définition de ressource dans un fichier
+
+`nestgen resource --file product.resource.json` lit un JSON versionné. La version actuelle est `1`. Les options de ligne de commande (`<name>`, `--fields`, `--route`, `--table`, `--orm`, `--profile`, `--indexes`) remplacent la valeur du fichier lorsqu’elles sont présentes. Ajoutez `uniqueIndexes` au fichier pour les contraintes d’unicité composites, par exemple `"uniqueIndexes": ["userId+roleId"]`.
+
+```json
+{
+    "version": 1,
+    "name": "product",
+    "route": "catalog/products",
+    "table": "catalog_products",
+    "orm": "prisma",
+    "profile": "advanced",
+    "fields": ["sku:string!", "status:enum(DRAFT|ACTIVE)"],
+    "indexes": ["sku+status"],
+    "relations": [{ "type": "belongsTo", "target": "category", "onDelete": "RESTRICT" }]
+}
+```
+
+Le fichier doit être situé dans le projet courant. Les diagnostics indiquent le fichier et le champ ou l’index concerné, et `--dry-run` produit le même plan que la définition équivalente en flags.
+
+### Filtres, recherche et tri contrôlés
+
+Ajoutez `list` à la définition pour autoriser explicitement les filtres et tris exposés par l’endpoint de liste. Les champs ou opérateurs absents de cette liste sont refusés avec `400`. Les paramètres de filtre sont convertis selon le type déclaré (`number`, `integer`, `boolean` et `date`) et les requêtes ORM restent paramétrées.
+
+```json
+{
+    "version": 1,
+    "name": "product",
+    "fields": ["sku:string!", "price:number", "published:boolean"],
+    "list": {
+        "filters": {
+            "sku": ["eq", "contains"],
+            "price": ["gte", "lt"],
+            "published": ["eq"]
+        },
+        "search": ["sku"],
+        "sort": ["sku", "price"]
+    }
+}
 ```
 
-Cette commande vérifie que :
-- Le package est correctement installé
-- Tous les templates embarqués sont disponibles
-- Aucune dépendance n'est manquante
+Les opérateurs autorisés dépendent du type : `eq` et `neq` pour tous les champs, `contains` pour les chaînes, et `gt`, `gte`, `lt`, `lte` pour les nombres, entiers, décimaux et dates. Une requête telle que `GET /products?skuContains=pro&priceGte=10&sort=price:desc` combine les filtres, applique un ordre déterministe (avec `id` comme brise-égalité) et respecte `page` et `limit`. `q` recherche sur les champs déclarés dans `search`.
+
+Ajoutez `"cursor": true` dans `list` pour inclure `nextCursor` dans les réponses. Reprenez la liste avec `?after=<nextCursor>` : le curseur opaque est validé et suit l’ordre stable `id:asc`, après application des mêmes filtres et de la même recherche. Un tri métier ne produit donc pas de curseur et ne peut pas être combiné avec `after`; ce choix évite les doublons ou omissions lors de la progression. Les changements concurrents peuvent toujours modifier les données restantes entre deux requêtes, comme avec toute pagination sans snapshot transactionnel.
+
+## Relations entre ressources
+
+Une relation est déclarée dans le fichier de définition de la ressource enfant. La ressource cible doit déjà avoir été générée avec le même ORM. `belongsTo` crée la clé étrangère, un index et la propriété inverse sur la cible pour former une relation un-à-plusieurs cohérente.
+
+```json
+{
+    "version": 1,
+    "name": "order",
+    "fields": ["reference:string!"],
+    "relations": [
+        {
+            "type": "belongsTo",
+            "target": "customer",
+            "field": "customer",
+            "inverse": "orders",
+            "nullable": false,
+            "onDelete": "RESTRICT"
+        }
+    ]
+}
+```
 
-## 📁 Architecture générée
+`field` et `inverse` sont optionnels : NestGen utilise le nom de la ressource cible et un pluriel du nom de la ressource enfant. `nullable` vaut `false` par défaut et `onDelete` vaut `RESTRICT`; les suppressions liées ne déclenchent donc aucune cascade implicite. `SET NULL` est accepté seulement avec `nullable: true`.
 
-NestGen génère une structure de projet suivant les meilleures pratiques d'architecture :
+`manyToMany` crée une table de liaison avec ses deux clés étrangères et une contrainte d’unicité sur la paire. La ressource qui déclare la relation en est propriétaire et reçoit les routes `POST /<ressource>/:id/<relation>/:targetId` et `DELETE /<ressource>/:id/<relation>/:targetId` pour associer et dissocier sans supprimer les deux entités.
 
+```json
+{
+    "version": 1,
+    "name": "user",
+    "fields": ["email:string!"],
+    "relations": [{ "type": "manyToMany", "target": "role", "field": "roles", "inverse": "users" }]
+}
 ```
-src/app/<module>/
-├── core/                   # Cœur du domaine métier
-│   ├── application/        # Cas d'utilisation
-│   │   ├── commands/       # Commandes CQRS
-│   │   ├── events/         # Événements domaine
-│   │   └── queries/        # Requêtes CQRS
-│   └── domain/             # Modèle du domaine
-│       ├── entities/       # Entités métier
-│       └── ports/          # Interfaces pour l'hexagonal
-├── infrastructure/         # Implémentations techniques
-│   ├── adapters/           # Adaptateurs pour l'hexagonal
-│   └── persistences/       # Couche de persistance
-│       └── repositories/   # Implémentations des repos
-└── interfaces/             # Points d'entrée de l'app
-    ├── controllers/        # Contrôleurs REST
-    └── dtos/               # Objets de transfert
+
+Lorsqu’une association porte ses propres données métier, générez-la comme ressource explicite avec deux relations `belongsTo`, puis protégez le couple de clés avec `uniqueIndexes`. Par exemple, une ressource `membership` peut définir `userId`, `roleId` et `grantedAt`, avec `"uniqueIndexes": ["userId+roleId"]`. Cette forme permet de versionner et valider les attributs de l’association, ce que la table de liaison implicite ne fait pas.
+
+On creation, non-nullable fields are required. On PATCH, omitted fields are preserved;
+`null` clears only nullable fields and is rejected for other fields. Values such as
+`false`, `0` and an empty string are preserved when valid for the field type.
+
+```bash
+nestgen resource invoice \
+  --fields number:string!,lineCount:integer,amount:decimal(12;2),status:enum(DRAFT|ISSUED),paid:boolean,dueAt:date? \
+  --route billing/invoices \
+  --table billing_invoices
 ```
 
-Cette structure facilite :
-- La séparation des préoccupations
-- Les tests unitaires et d'intégration
-- L'évolutivité du code
-- Le remplacement des composants techniques
+Use `nestgen --help` for the complete accepted option set. Do not rely on undocumented options such as `--crud` or `--path`.
+
+`--dry-run` emits a versioned JSON plan for `module` and `resource`. Each entry identifies the creation or replacement, and includes the exact unified diff that generation would apply. Conflicts are reported in `conflicts`; no file, dependency or installation is changed.
+
+Use `--json` in automation to receive one versioned result on stdout. Failures produce a versioned JSON error on stderr with a stable `USAGE`, `PROJECT_INVALID`, `CONFLICT` or `INTERNAL` code; `--json` also enables non-interactive, quiet and no-color behavior.
 
-## 🔮 Roadmap
+`nestgen doctor` is read-only. It reports version support, generator availability, Nest dependencies, ORM coherence, NestGen configuration, lockfile consistency and Nest integration. Every diagnostic has an identifier, severity, cause and concrete corrective action; use `nestgen doctor --json` for the same contract in automation.
 
-- ✅ Génération de projet complet
-- ✅ Génération de module modulaire (DDD, CQRS, Repo)
-- ✅ Support Prisma et TypeORM
-- ✅ Mode interactif
-- ✅ Docker, Swagger, Git
-- ✅ Templates intégrés
-- ✅ Package 100% autonome
-- ⬜ `nestgen resource <name>` (CRUD complet)
-- ⬜ `nestgen destroy module <name>`
-- ⬜ `nestgen preset ecommerce` (Templates d'applications)
-- ⬜ `nestgen --interactive` (menu CLI avancé)
-- ⬜ Support pour MongoDB et Mongoose
-- ⬜ Génération de tests unitaires et d'intégration
+## Generation metadata
 
-## ❓ FAQ
+Every successful `module` or `resource` generation updates `.nestgen/generation-manifest.json` in the same atomic transaction as the generated files. The versioned manifest records the generator version, a safe structural definition and SHA-256 fingerprints for each generated file. Paths are always project-relative; field default values are deliberately excluded so the manifest can be committed without copying secrets. Later tooling can compare these fingerprints to detect manual edits before proposing an update. An unknown manifest version stops generation before any write.
 
-**Q: NestGen nécessite-t-il des dépendances externes ?**  
-R: Non, NestGen est 100% autonome. Tous les templates et outils nécessaires sont embarqués dans le package.
+Use `resource <name> --update` to regenerate a resource after changing its fields, route, table or definition file. NestGen previews the same transaction with `--dry-run`; a generated file edited since its recorded generation is reported as a conflict and blocks all writes. Files not tracked by the resource manifest are left untouched, and the manifest is refreshed only after the complete update commits successfully.
 
-**Q: Puis-je utiliser NestGen avec un projet NestJS existant ?**  
-R: Oui, vous pouvez ajouter des modules générés par NestGen à un projet existant. La structure générée s'intègre parfaitement aux projets NestJS standards.
+Add `--migration-name <name>` to an update to prepare the matching migration command and schema-risk review. TypeORM uses `typeorm-ts-node-commonjs migration:generate`; Prisma uses `prisma migrate dev --create-only`. The CLI never runs this command or applies a migration: review the reported column removals, type changes, mandatory fields, unique constraints and relation removals, then run the printed command explicitly in the generated project.
 
-**Q: Comment puis-je personnaliser les templates générés ?**  
-R: Par défaut, NestGen utilise ses templates intégrés. Leurs structures sont optimisées pour les meilleures pratiques et ne nécessitent généralement pas de modifications.
+## Project configuration and profiles
 
-**Q: NestGen supporte-t-il les microservices ?**  
-R: Pas encore nativement, mais c'est prévu dans les prochaines versions. En attendant, vous pouvez adapter manuellement la structure générée.
+`nestgen config init` writes a versioned `nestgen.config.json` in the current project. For `resource`, the resolution order is flags, then the resource definition file, then configuration, then defaults. For `module`, `--orm` overrides configuration, then the default. `profile` is consumed by `resource`; `packageManager` is consumed by `init` and recorded for tooling, but neither `resource` nor `module` installs packages, so it has no runtime effect there. The generator resolves the effective source root from `nest-cli.json`; use `--application <name>` when a Nest workspace contains more than one application.
 
-## 👥 Contribuer
+```bash
+nestgen config init --orm typeorm --profile advanced --package-manager npm
+nestgen config show
+nestgen resource order --fields reference:string!,total:number
+```
 
-Les contributions sont les bienvenues ! Pour contribuer :
+The `simple` profile generates a direct CRUD. The `advanced` profile adds application contracts, a repository port and a framework-independent application service between HTTP and the TypeORM adapter.
 
-1. Forkez le dépôt
-2. Créez une branche pour votre fonctionnalité (`git checkout -b feature/amazing-feature`)
-3. Commitez vos changements (`git commit -m 'feat: add amazing feature'`)
-4. Poussez vers la branche (`git push origin feature/amazing-feature`)
-5. Ouvrez une Pull Request
+## OpenAPI when Swagger is enabled
 
-<!-- Veuillez consulter le fichier `CONTRIBUTING.md` pour plus de détails. -->
+If the project contains `@nestjs/swagger` (selected during `nestgen init`), generated resources enrich the OpenAPI document with DTO property schemas, examples, required and nullable fields, UUID/date formats, endpoint summaries, pagination parameters, and documented `400`, `404`, `409` and success responses. Projects without Swagger keep the same generated REST code and do not receive Swagger imports.
 
-## 📄 Licence
+## Tests generated with a resource
+
+Each generated resource includes a Jest unit test next to its implementation. In a standard project created by Nest, run the complete suite with `npm test`, or one resource with:
+
+```bash
+npm test -- product.repository.spec.ts
+npm test -- order.service.spec.ts
+```
+
+The simple profile test exercises persistence success, a missing record and a unique-constraint conflict. The advanced profile test exercises the application service output and the HTTP translation of application errors to `404` and `409`. The tests use in-memory doubles; each resource also has a generated REST test backed by PostgreSQL.
+
+## Generated REST tests on an isolated database
+
+The first generated resource adds `test/.env.e2e` and `test/compose.e2e.yaml`; every resource adds `test/<resource>.e2e-spec.ts`. The test assigns `DATABASE_NAME` from `DATABASE_TEST_NAME`, resets the schema before every scenario, and drops it when the suite ends. It therefore never targets the development or production database.
+
+```bash
+docker compose -f test/compose.e2e.yaml up -d --wait
+npm run test:e2e -- product.e2e-spec.ts
+docker compose -f test/compose.e2e.yaml down -v
+```
+
+The generated suite covers create, read, partial update, pagination and delete, plus invalid input, malformed UUIDs, missing resources, and duplicate values when the resource declares a unique field with `!`.
+
+## Docker generated by `init`
+
+When Docker is enabled, NestGen writes:
+
+- `compose.yaml` for local development, with PostgreSQL 16, a healthcheck and a code mount;
+- `Dockerfile` with a `development` target and a separate minimal `production` target;
+- `.dockerignore` and `.env.example` without overwriting existing environment examples.
+
+Use development with `docker compose up`. Build the deployable image independently:
+
+```bash
+docker build --target production --tag store-api:local .
+docker run --rm --env-file .env --publish 3000:3000 store-api:local
+```
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm run landing:check
+npm run format:check
+npm test
+npm run test:docker
+npm run test:prisma
+npm run test:typeorm
+npm run test:example
+npm run test:package
+```
 
-NestGen est distribué sous licence MIT. Voir le fichier `LICENSE` pour plus d'informations.
+See [COMPATIBILITY.md](COMPATIBILITY.md) for supported versions and [ARCHITECTURE.md](ARCHITECTURE.md) for generator design decisions.
 
----
+## Licence
 
-<div align="center">
-  <p>Développé avec ❤️ par <a href="https://github.com/el-hack">@el-hack</a></p>
-  <p>Si vous trouvez ce projet utile, n'hésitez pas à lui donner une ⭐️ sur GitHub !</p>
-</div>
+MIT. See [LICENSE](LICENSE).