# NestCraftX — Clean Architecture Generator for NestJS

[![NPM Version](https://img.shields.io/npm/v/nestcraftx?style=flat-square&color=CB3837)](https://www.npmjs.com/package/nestcraftx)
[![NPM Downloads](https://img.shields.io/npm/dm/nestcraftx?style=flat-square&color=51a2da)](https://www.npmjs.com/package/nestcraftx)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Node.js Version](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** is a modern and powerful Node.js CLI for automatically generating NestJS projects and content with a clean, maintainable, and production-ready architecture.

It scaffolds everything you need to get started:

- Modules, Controllers & Services (Fully typed)
- Repositories & Mappers (For clean data flow and separation of concerns)
- DTOs (With built-in validation)
- Entities / Schemas (Prisma, TypeORM, or Mongoose)
- Authentication (JWT with Refresh Tokens & auto-generated secrets)
- DevOps Ready (Docker, Docker-Compose & Swagger UI)

It implements modern best practices: **Clean Architecture**, **Domain-Driven Design (DDD)**, **Prisma/TypeORM/Mongoose**, **JWT Auth with auto-generated secrets**, **Swagger**, **Docker**, and much more.

Key Features:

- Dual-Architecture: Choose between Light (MVP) or Full (Clean Architecture / DDD).

- Interactive Relations: Define 1-N or N-N relationships directly in the terminal.

- Smart Config: Automated Swagger decorators, auto-documented .env files, and pre-configured database connections.

> **Version 1.0.0 (Stable Release):** Production-grade NestJS scaffolding with Clean Architecture, JWT authentication, relations updater, conditional RBAC guards, global rate limiting, health checks, advanced pagination/filtering/sorting, Swagger UI, and Docker compose files!

---

## Table of Contents

- [What's New in v1.0.0](#whats-new-in-v100-stable-release)
- [Project Objective](#project-objective)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Available Commands](#available-commands)
- [Features](#features)
- [Generated Architecture](#generated-architecture)
- [Complete Demo](#complete-demo)
- [Usage Guide](#usage-guide)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

## What's New in v1.0.0 (Stable Release)

### 🔗 Standalone Relation Command (`nestcraftx g relation`)
- Create 1-n, n-1, 1-1, or n-n relations between **existing modules** at any time.
- Automatically updates domain entities (FK fields and getters), DTOs (Create and Update), and data mappers.
- Syncs database schemas (runs format, client generation, and migrations dev for Prisma; injects ObjectId references for Mongoose).

### 🛡️ Conditional RBAC Guards & Swagger Integration
- Mutation endpoints (`POST`, `PATCH`, `DELETE`) are protected with `JwtAuthGuard` and `RolesGuard` (`@Roles('ADMIN')`) only if Auth is enabled.
- Read endpoints (`GET`, `GET :id`) are decorated with `@Public()`.
- Generates complete API documentation using `@ApiBearerAuth()` and standard error responses when Swagger is enabled.

### 🚦 Global Rate Limiting (Throttler Module)
- Integrated `@nestjs/throttler` package with preconfigured global rate limiting policies (default: 10 requests per minute).
- Configurable via interactive prompts or CLI flag `--throttler`.

### 🏥 Health Check Endpoint (`/health`)
- Exposes a native `/health` check route reporting global status (`ok`), timestamp, and application uptime (`process.uptime()`).
- Fully documented in Swagger UI, optimized with zero third-party packages for fast compilation and maximum safety.

### 🚀 Advanced Query Params (Pagination, Filtering, Sorting)
- Auto-injects paginated data retrieval (e.g. `?page=1&limit=10&search=...&sortBy=createdAt&sortOrder=desc`) into controllers and repository layers.
- Seamlessly maps incoming query params to Prisma, TypeORM, and Mongoose queries.

### 📋 Interactive Scaffolding Report
- Out-of-the-box CLI report with ASCII borders after each module generation summarizing files generated, database schema updates, relations established, and clear next steps.

### Quick Examples

```bash
# LIGHT project with Prisma and Auth
nestcraftx new my-api --light --orm=prisma --auth

# FULL project with TypeORM and Swagger
nestcraftx new my-project --full --orm=typeorm --swagger

# Minimal MongoDB project
nestcraftx new my-api --light --orm=mongoose
```

---

## Project Objective

Stop wasting time configuring your backend architecture. NestCraftX allows you to:

- ✅ Start a project in minutes instead of days
- ✅ Have a Clean Architecture from the start
- ✅ Standardize your projects with the same best practices
- ✅ Automatically configure DB-ORM and other modules (decorators, authentication, dockerization)
- ✅ Focus on business logic
- ✅ Choose between quick configuration (Light) or complete (Full)

## Prerequisites

Make sure you have:

- **Node.js** v14 or higher
- **npm** or **yarn**
- **Nest CLI** (optional, will be used via npx)
- **Docker** (optional, for containerization)
- **Git** (optional, for version control)

Verify your environment with:

```bash
nestcraftx test
```

---

## Installation

### Via npx (recommended)

Use NestCraftX without global installation:

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

### Global Installation

For frequent use:

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

### Installation for Development

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

### Running Tests

We use Jest to run unit tests and E2E generator compiler tests:

```bash
# Run unit tests (fast check)
npm run test:unit

# Run E2E integration tests (scaffolds project, runs npm install & tsc type checks)
npm run test:e2e

# Run all tests
npm test
```

---

## Available Commands

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

Creates a new NestJS project with Clean Architecture.

**Options:**

- `--light` : Quick configuration mode
- `--orm <prisma|typeorm|mongoose>` : ORM choice
- `--auth` : Add JWT authentication
- `--swagger` : Add Swagger UI
- `--docker` : Generate Docker files

**Examples:**

```bash
# Full interactive mode
nestcraftx new my-app

# Quick mode with options
nestcraftx new blog-api --light --orm=prisma --auth --swagger

# Custom configuration
nestcraftx new shop --orm=typeorm --auth
```

### `nestcraftx demo [options]`

Generates a complete demonstration project (blog-demo) with:

- 3 entities (User, Post, Comment) with 1-n relationships
- Integrated JWT Auth
- Swagger enabled
- Docker configured

**Options:**

- `--light` : Simplified architecture mode
- `--docker` : Enable Docker (default: true)
- `--auth` : Enable JWT Auth (default: true)
- `--swagger` : Enable Swagger (default: true)
- `--orm <prisma|typeorm|mongoose>` : ORM choice (default: prisma)

**Examples:**

```bash
# Interactive mode (will ask questions)
nestcraftx demo

# LIGHT mode with Mongoose
nestcraftx demo --light --orm=mongoose

# FULL mode with TypeORM
nestcraftx demo --orm=typeorm --auth --swagger

# Quick start
nestcraftx demo --light --orm=prisma
```

**Result:**

A functional blog project with:

- Blog-demo created
- 3 complete entities
- Relationships between User → Post → Comment
- Auth endpoints (register, login) ready
- Business endpoints: /users, /posts, /comments ready
- Automatic Swagger documentation
- Docker & Docker Compose configured
- ORM configuration of your choice (Prisma, TypeORM, Mongoose)

### `nestcraftx test`

Checks if your environment is ready:

```bash
nestcraftx test
```

Displays the status of Node, npm, Nest CLI, Docker, Git, etc.

### `nestcraftx info`

Displays CLI information:

```bash
nestcraftx info
```

---

## Features

### Architecture

✅ **Clean Architecture** with domain/application/infrastructure/presentation separation
✅ **Domain-Driven Design** with entities, use cases and repositories
✅ **Repository Pattern** for persistence abstraction
✅ **Use Cases Pattern** for isolated business logic
✅ **Mapper Pattern** for data transformation

### Database

✅ **Prisma ➡️ (PostgreSQL)** - Modern and type-safe ORM (recommended)

✅ **TypeORM ➡️ (PostgreSQL)** - Complete ORM with decorators

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

✅ Automatic schema configuration

✅ PostgreSQL and MongoDB support

### Security

✅ **JWT Authentication** with guards and strategies

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

✅ **Password hashing** with bcrypt

✅ **Public routes** with decorators

### Documentation

✅ **Swagger UI** automatic

✅ ApiProperty decorators on DTOs

✅ Endpoint documentation

✅ Interactive API interface

### DevOps

✅ **Docker** and **Docker Compose**

✅ Environment variables configuration

✅ Structured logging

✅ Centralized error handling

### Code Quality

✅ DTO validation with class-validator

✅ Data transformation with class-transformer

✅ Standardized response interceptors

✅ Global exception filters

---

## Generated Architecture

### Light Mode (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
```

### Full Mode (Clean Architecture)

```
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
```

## Complete Demo

🔥 A ready-to-run demo, including 3 linked entities, JWT Auth, Swagger, Docker and configurable ORM.

👉 See full documentation: [Demo Documentation](./DEMO.md)

## Usage Guide

### Quick Start (Light Mode)

```bash
# 1. Create a simple project
npx nestcraftx new my-api --light --orm prisma

# 2. Navigate to the project
cd my-api

# 3. Start the application
npm run start:dev
```

### Complete Configuration (Full Mode)

```bash
# 1. Launch with interactive interface
npx nestcraftx new my-project

# 2. Answer the questions:
#    - Project name
#    - Database choice
#    - ORM configuration
#    - Entities and relationships
#    - Auth and Swagger

# 3. Start
cd my-project
npm run start:dev
```

### Demonstration Project

```bash
# Generate a complete blog project (interactive mode)
nestcraftx demo

# Or with direct options
nestcraftx demo --light --orm prisma --auth --swagger

# Navigate and start
cd blog-demo
npm run start:dev

# Access Swagger UI
open http://localhost:3000/api/docs
```

**What the demo project includes:**

- Complete Clean Architecture (or LIGHT depending on option)
- 3 pre-configured entities: User, Post, Comment
- Relationships between entities (User → Post, Post ↔ Comment)
- JWT Auth with /auth/register and /auth/login endpoints
- Business endpoints: /users, /posts, /comments
- Automatic Swagger documentation
- Docker & Docker Compose configured
- ORM configuration of your choice (Prisma, TypeORM, Mongoose)

---

## Roadmap

### Version 0.3.0 — Stabilization & UX (Completed)
- [x] CommonJS module system unification
- [x] Dynamic helper versioning and interactive flags checks
- [x] Dynamic package manager setup

### Version 0.4.0 — Architecture Refactoring (Completed)
- [x] Split of monolithic files into dedicated generators
- [x] Interactive state-based `EntityBuilder` with revision menus
- [x] Dry-run simulation mode (`--dry-run`)

### Version 0.5.0 — Quality & Security (Completed)
- [x] Persistent DB storage for OTPs & password reset tokens
- [x] Strict package version pinning
- [x] Contextual semantic Swagger DTO descriptions

### Version 0.6.0 — Tests & CI/CD (Completed)
- [x] Unit test coverage using Jest
- [x] E2E compiler checks & resolution of upstream peer dependency conflicts
- [x] Multi-OS Node.js matrix GitHub Actions CI/CD pipeline

### Version 0.7.0 - 0.9.0 — Missing Features (In Progress)
- [ ] Interactive `generate auth` and complete non-interactive execution
- [ ] API Pagination, filtering, rate limiting, and RBAC guards
- [ ] MySQL/SQLite support

### Version 1.0.0 — Stable Release
- [ ] Official documentation website
- [ ] Production audit and LTS guarantees

---

## Contributing

Want to improve NestCraftX? Contributions are welcome!

### How to Contribute

1. Fork the project
2. Create a branch for your feature (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Open an Issue

Found bugs? Have ideas? Open an issue on GitHub!

### Developers

To develop locally:

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

---

## License

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

Free for personal and commercial use.

---

## Thanks

Thanks to all contributors and the NestJS community!

**Made with ❤️ for the backend developer community**

---

## Contact & Support

- 📧 GitHub Issues: [Open an issue](https://github.com/august-dev-pro/NestCraftX/issues)
- 🌐 Repository: [NestCraftX on GitHub](https://github.com/august-dev-pro/NestCraftX)
- ⭐ If this project helps you, please consider giving it a star!

---

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

For more information:

- [Complete Usage Guide](./CLI_USAGE.md)
- [Migration Guide](./MIGRATION_GUIDE.md)
- [Detailed Changelog](./CHANGELOG.md)