nestforge-generator 0.1.0

package/templates/prisma/TESTING.md

@@ -0,0 +1,123 @@
+# Testing the Prisma template
+
+**English** | [Português](TESTING.pt-BR.md)
+
+This guide validates a project generated from the NestForge Prisma template.
+
+## Prerequisites
+
+* Node.js 20 or later
+* npm 10 or later
+* Docker when testing PostgreSQL, MySQL, Redis, or Mailpit
+
+SQLite can be tested without Docker.
+
+## Prepare the environment
+
+```bash
+npm install
+cp .env.example .env
+cp .env.example .env.test
+```
+
+Use different databases in `.env` and `.env.test`. Never run E2E tests against the development or production database.
+
+Generate Prisma Client:
+
+```bash
+npm run prisma:generate
+```
+
+## Apply the development schema
+
+```bash
+npm run prisma:migrate -- --name init
+```
+
+Run the seed when the generated project includes password authentication:
+
+```bash
+npm run prisma:seed
+```
+
+## Static validation
+
+```bash
+npm run build
+npm run lint
+```
+
+## Unit tests
+
+```bash
+npm test
+```
+
+For coverage:
+
+```bash
+npm run test:cov
+```
+
+Unit tests mock Prisma and Redis, so they do not require real services.
+
+## E2E tests
+
+```bash
+npm run test:e2e
+```
+
+The `pretest:e2e` script runs `prisma migrate deploy` with `.env.test` before the suite starts.
+
+Depending on the generated authentication strategy, the suite may cover:
+
+* registration and login;
+* refresh token rotation and logout;
+* Session/Cookies and CSRF;
+* user CRUD;
+* RBAC and permissions.
+
+## Database-specific checks
+
+### PostgreSQL
+
+```bash
+docker compose up -d postgres
+npm run prisma:migrate -- --name init
+```
+
+### MySQL
+
+```bash
+docker compose up -d mysql
+npm run prisma:migrate -- --name init
+```
+
+### SQLite
+
+Set the database URL to a local file:
+
+```dotenv
+DATABASE_URL="file:./dev.db"
+```
+
+Then run:
+
+```bash
+npm run prisma:migrate -- --name init
+npm run build
+npm test
+npm run test:e2e
+```
+
+## Final checklist
+
+* [ ] Dependencies install successfully
+* [ ] Prisma Client is generated
+* [ ] Migrations are applied
+* [ ] Seed runs when applicable
+* [ ] Build passes
+* [ ] Lint passes
+* [ ] Unit tests pass
+* [ ] E2E tests pass
+* [ ] `.env.test` uses an isolated database

package/templates/prisma/TESTING.pt-BR.md

@@ -0,0 +1,123 @@
+# Testando o template Prisma
+
+[English](TESTING.md) | **Português**
+
+Este guia valida um projeto gerado a partir do template Prisma do NestForge.
+
+## Pré-requisitos
+
+* Node.js 20 ou superior
+* npm 10 ou superior
+* Docker para testar PostgreSQL, MySQL, Redis ou Mailpit
+
+SQLite pode ser testado sem Docker.
+
+## Preparar o ambiente
+
+```bash
+npm install
+cp .env.example .env
+cp .env.example .env.test
+```
+
+Use bancos diferentes em `.env` e `.env.test`. Nunca execute testes E2E no banco de desenvolvimento ou produção.
+
+Gere o Prisma Client:
+
+```bash
+npm run prisma:generate
+```
+
+## Aplicar o schema de desenvolvimento
+
+```bash
+npm run prisma:migrate -- --name init
+```
+
+Execute o seed quando o projeto gerado incluir autenticação por senha:
+
+```bash
+npm run prisma:seed
+```
+
+## Validação estática
+
+```bash
+npm run build
+npm run lint
+```
+
+## Testes unitários
+
+```bash
+npm test
+```
+
+Para cobertura:
+
+```bash
+npm run test:cov
+```
+
+Os testes unitários simulam Prisma e Redis, portanto não exigem serviços reais.
+
+## Testes E2E
+
+```bash
+npm run test:e2e
+```
+
+O script `pretest:e2e` executa `prisma migrate deploy` com `.env.test` antes do início da suíte.
+
+Dependendo da estratégia de autenticação gerada, a suíte pode cobrir:
+
+* cadastro e login;
+* rotação de refresh token e logout;
+* Session/Cookies e CSRF;
+* CRUD de usuários;
+* RBAC e permissions.
+
+## Verificações específicas por banco
+
+### PostgreSQL
+
+```bash
+docker compose up -d postgres
+npm run prisma:migrate -- --name init
+```
+
+### MySQL
+
+```bash
+docker compose up -d mysql
+npm run prisma:migrate -- --name init
+```
+
+### SQLite
+
+Defina a URL do banco como um arquivo local:
+
+```dotenv
+DATABASE_URL="file:./dev.db"
+```
+
+Depois execute:
+
+```bash
+npm run prisma:migrate -- --name init
+npm run build
+npm test
+npm run test:e2e
+```
+
+## Checklist final
+
+* [ ] As dependências são instaladas corretamente
+* [ ] O Prisma Client é gerado
+* [ ] As migrations são aplicadas
+* [ ] O seed executa quando aplicável
+* [ ] O build passa
+* [ ] O lint passa
+* [ ] Os testes unitários passam
+* [ ] Os testes E2E passam
+* [ ] `.env.test` usa um banco isolado

package/templates/prisma/docker-compose.yml

@@ -0,0 +1,78 @@
+version: "3.9"
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: nestforge-api
+    ports:
+      - "3000:3000"
+    env_file:
+      - .env
+    depends_on:
+      # nestforge:feature:database:postgres
+      - postgres
+      # nestforge:feature:database:postgres:end
+      # nestforge:feature:database:mysql
+      - mysql
+      # nestforge:feature:database:mysql:end
+      - redis
+    volumes:
+      - ./src:/app/src
+    command: npm run start:dev
+
+  # nestforge:feature:database:postgres
+  postgres:
+    image: postgres:16-alpine
+    container_name: nestforge-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: nestforge
+      POSTGRES_PASSWORD: nestforge
+      POSTGRES_DB: nestforge
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+  # nestforge:feature:database:postgres:end
+
+  # nestforge:feature:database:mysql
+  mysql:
+    image: mysql:8
+    container_name: nestforge-mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_USER: nestforge
+      MYSQL_PASSWORD: nestforge
+      MYSQL_ROOT_PASSWORD: nestforge
+      MYSQL_DATABASE: nestforge
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+  # nestforge:feature:database:mysql:end
+
+  redis:
+    image: redis:7-alpine
+    container_name: nestforge-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: nestforge-mailpit
+    restart: unless-stopped
+    ports:
+      - "8025:8025" # UI
+      - "1025:1025" # SMTP
+
+  # nestforge:feature:database:postgres
+volumes:
+  postgres_data:
+  # nestforge:feature:database:postgres:end
+  # nestforge:feature:database:mysql
+volumes:
+  mysql_data:
+  # nestforge:feature:database:mysql:end

package/templates/prisma/docs/adding-a-module.md

@@ -0,0 +1,230 @@
+# Como adicionar um novo módulo
+
+Este guia mostra o passo a passo pra adicionar um recurso novo seguindo as convenções do NestForge, usando um módulo `posts` (posts de blog) como exemplo. Adapte os nomes pro seu caso.
+
+## 1. Adicione o model no Prisma
+
+Em `prisma/schema.prisma`:
+
+```prisma
+model Post {
+  id        String   @id @default(uuid())
+  title     String
+  content   String
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("posts")
+}
+```
+
+Não esqueça de adicionar a relação inversa no `model User`:
+
+```prisma
+posts Post[]
+```
+
+Gere a migration:
+
+```bash
+npx prisma migrate dev --name add_posts
+```
+
+## 2. Crie a estrutura de pastas
+
+```
+src/posts/
+├── dto/
+│   ├── create-post.dto.ts
+│   └── update-post.dto.ts
+├── entities/
+│   └── post.entity.ts
+├── posts.controller.ts
+├── posts.service.ts
+└── posts.module.ts
+```
+
+## 3. DTOs com Zod
+
+`src/posts/dto/create-post.dto.ts`:
+
+```ts
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+
+export const createPostSchema = z.object({
+  title: z.string().min(3).describe('Título do post'),
+  content: z.string().min(10).describe('Conteúdo do post'),
+});
+
+export class CreatePostDto extends createZodDto(createPostSchema) {}
+```
+
+`src/posts/dto/update-post.dto.ts`:
+
+```ts
+import { createZodDto } from 'nestjs-zod';
+import { createPostSchema } from './create-post.dto';
+
+export const updatePostSchema = createPostSchema.partial();
+
+export class UpdatePostDto extends createZodDto(updatePostSchema) {}
+```
+
+## 4. Entity (o que a API expõe)
+
+`src/posts/entities/post.entity.ts` — mesmo se não houver nada sensível pra esconder agora, criar a entity já deixa o padrão pronto pra quando houver:
+
+```ts
+export class PostEntity {
+  id: string;
+  title: string;
+  content: string;
+  authorId: string;
+  createdAt: Date;
+  updatedAt: Date;
+
+  constructor(partial: Partial<PostEntity>) {
+    Object.assign(this, partial);
+  }
+}
+```
+
+## 5. Service (regra de negócio)
+
+`src/posts/posts.service.ts`:
+
+```ts
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { PrismaService } from '../database/prisma.service';
+import { CreatePostDto } from './dto/create-post.dto';
+import { UpdatePostDto } from './dto/update-post.dto';
+import { PostEntity } from './entities/post.entity';
+
+@Injectable()
+export class PostsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async create(authorId: string, dto: CreatePostDto) {
+    const post = await this.prisma.post.create({ data: { ...dto, authorId } });
+    return new PostEntity(post);
+  }
+
+  async findOne(id: string) {
+    const post = await this.prisma.post.findUnique({ where: { id } });
+    if (!post) throw new NotFoundException('Post não encontrado');
+    return new PostEntity(post);
+  }
+
+  async update(id: string, dto: UpdatePostDto) {
+    await this.findOne(id);
+    const post = await this.prisma.post.update({ where: { id }, data: dto });
+    return new PostEntity(post);
+  }
+
+  async remove(id: string) {
+    await this.findOne(id);
+    await this.prisma.post.delete({ where: { id } });
+    return { message: 'Post removido com sucesso' };
+  }
+}
+```
+
+## 6. Controller (guards + permissions)
+
+Se o recurso precisa de controle de acesso, adicione a permission em `src/common/constants/permissions.ts` e no mapeamento `src/common/constants/role-permissions.ts` antes de usar:
+
+```ts
+// permissions.ts
+export enum Permission {
+  // ...existentes
+  PostCreate = 'post:create',
+  PostDelete = 'post:delete',
+}
+```
+
+`src/posts/posts.controller.ts`:
+
+```ts
+import { Body, Controller, Delete, Get, Param, Patch, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { PostsService } from './posts.service';
+import { CreatePostDto } from './dto/create-post.dto';
+import { UpdatePostDto } from './dto/update-post.dto';
+import { Permissions } from '../common/decorators/permissions.decorator';
+import { Permission } from '../common/constants/permissions';
+import { CurrentUser } from '../common/decorators/current-user.decorator';
+
+@ApiTags('posts')
+@ApiBearerAuth()
+@Controller('posts')
+export class PostsController {
+  constructor(private readonly postsService: PostsService) {}
+
+  @Post()
+  @Permissions(Permission.PostCreate)
+  create(@CurrentUser() user: { id: string }, @Body() dto: CreatePostDto) {
+    return this.postsService.create(user.id, dto);
+  }
+
+  @Get(':id')
+  findOne(@Param('id') id: string) {
+    return this.postsService.findOne(id);
+  }
+
+  @Patch(':id')
+  update(@Param('id') id: string, @Body() dto: UpdatePostDto) {
+    return this.postsService.update(id, dto);
+  }
+
+  @Delete(':id')
+  @Permissions(Permission.PostDelete)
+  remove(@Param('id') id: string) {
+    return this.postsService.remove(id);
+  }
+}
+```
+
+## 7. Module
+
+`src/posts/posts.module.ts`:
+
+```ts
+import { Module } from '@nestjs/common';
+import { PostsService } from './posts.service';
+import { PostsController } from './posts.controller';
+
+@Module({
+  controllers: [PostsController],
+  providers: [PostsService],
+  exports: [PostsService],
+})
+export class PostsModule {}
+```
+
+Registre no `src/app.module.ts` (dentro do array `imports`):
+
+```ts
+import { PostsModule } from './posts/posts.module';
+// ...
+PostsModule,
+```
+
+## 8. Testes
+
+- **Unitário** (`src/posts/posts.service.spec.ts`): mocke o `PrismaService` como em `src/users/users.service.spec.ts` — sem banco real.
+- **E2e** (`test/posts.e2e-spec.ts`): use os helpers de `test/utils/e2e-setup.ts` e `test/utils/clean-database.ts` (adicione `prisma.post.deleteMany()` na limpeza) e siga o padrão de `test/users.e2e-spec.ts`.
+
+## Checklist rápido
+
+- [ ] Model no `schema.prisma` + migration
+- [ ] DTOs com Zod (`createZodDto`)
+- [ ] Entity (mesmo sem campo sensível ainda)
+- [ ] Service sem lógica no controller
+- [ ] Permissions novas cadastradas em `permissions.ts` e `role-permissions.ts`, se necessário
+- [ ] Module registrado no `AppModule`
+- [ ] Teste unitário do service
+- [ ] Teste e2e do fluxo principal
+- [ ] Atualizar `ROADMAP.md` se o módulo fechar um item do roadmap

package/templates/prisma/docs/features-markers.md

@@ -0,0 +1,50 @@
+# Marcadores de features (feature markers)
+
+O `templates/prisma` é usado tanto como projeto standalone quanto como fonte pra CLI (`packages/cli`) gerar projetos. Quando um recurso é **opcional** na CLI (ex: Swagger, Redis, RBAC), o código dele precisa ficar marcado no template, pra CLI saber o que remover quando o usuário responde "não" naquela pergunta.
+
+Se você está adicionando código ligado a um recurso que já existe como pergunta na CLI (ou propondo um recurso novo opcional), marque o trecho seguindo esta convenção.
+
+## Marcador de bloco
+
+Envolve um trecho de código (uma ou várias linhas) dentro de um arquivo que tem outras coisas não-opcionais também.
+
+```ts
+// nestforge:feature:swagger
+@ApiTags('users')
+// nestforge:feature:swagger:end
+@Controller('users')
+export class UsersController {
+```
+
+- Recurso **habilitado**: a CLI remove só as duas linhas de marcador, o `@ApiTags('users')` fica.
+- Recurso **desabilitado**: a CLI remove o bloco inteiro (marcador + `@ApiTags('users')`).
+
+O nome depois de `nestforge:feature:` tem que ser exatamente o mesmo nas duas linhas (abertura e `:end`), e bater com o nome usado no array `features` da CLI (`docker`, `swagger`, `validation`, `redis`, `rbac`).
+
+Funciona em qualquer arquivo cuja linguagem use `//` para comentário (`.ts`, `.js`). **Não funciona em JSON** (`package.json`) — pra dependências, ver a seção final deste documento.
+
+## Marcador de arquivo inteiro
+
+Quando o arquivo **inteiro** só faz sentido se o recurso estiver ligado (ex: `src/mail/mail.service.ts`, que só existe por causa do Redis/BullMQ), marque a primeira linha do arquivo:
+
+```ts
+// nestforge:feature-file:redis
+import { Injectable } from '@nestjs/common';
+// ...resto do arquivo normalmente
+```
+
+- Recurso **habilitado**: a CLI remove só essa primeira linha, o resto do arquivo fica intacto.
+- Recurso **desabilitado**: a CLI apaga o arquivo inteiro.
+
+Se, depois de remover arquivos, uma pasta ficar vazia (ex: `src/mail/` inteira desapareceu), a CLI remove a pasta também — não precisa se preocupar em limpar pasta manualmente.
+
+## Dependências no `package.json`
+
+JSON não aceita comentário, então marcador não funciona ali. Em vez disso, o mapeamento fica direto no código da CLI: `packages/cli/src/features/dependencies.ts`, no objeto `FEATURE_DEPENDENCIES`. Se seu recurso opcional adiciona uma dependência nova ao `package.json` do template, adicione ela nesse mapa também.
+
+## Checklist ao adicionar um recurso opcional novo
+
+- [ ] Todo trecho de código exclusivo do recurso está marcado (bloco ou arquivo inteiro)
+- [ ] O nome do marcador bate com o valor usado em `features` na CLI (`packages/cli/src/prompts.ts`)
+- [ ] Dependências novas do `package.json` estão em `FEATURE_DEPENDENCIES` (`packages/cli/src/features/dependencies.ts`)
+- [ ] Testado gerando o projeto com o recurso ligado **e** desligado — o projeto tem que compilar/rodar dos dois jeitos

package/templates/prisma/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/templates/prisma/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "nestforge",
+  "version": "0.1.0",
+  "description": "Production-ready NestJS starter with Prisma, Authentication, Docker, Testing, CI/CD and Clean Architecture.",
+  "license": "MIT",
+  "author": "Jeiel Alves <https://github.com/jeiel2013>",
+  "private": true,
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main.js",
+    "lint": "eslint \"{src,test}/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "pretest:e2e": "dotenv -e .env.test -- npx prisma migrate deploy",
+    "test:e2e": "dotenv -e .env.test -- vitest run --config ./vitest.e2e.config.ts",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev",
+    "prisma:deploy": "prisma migrate deploy",
+    "prisma:seed": "prisma db seed",
+    "prisma:studio": "prisma studio"
+  },
+  "prisma": {
+    "seed": "ts-node prisma/seed.ts"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/config": "^4.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/jwt": "^11.0.0",
+    "@nestjs/passport": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/swagger": "^11.0.0",
+    "@nestjs/throttler": "^6.5.0",
+    "@nestjs/bullmq": "^11.0.0",
+    "@nestjs/terminus": "^11.0.0",
+    "@prisma/client": "^6.0.0",
+    "@quixo3/prisma-session-store": "^3.1.21",
+    "express-session": "^1.19.0",
+    "bullmq": "^5.0.0",
+    "bcryptjs": "^2.4.3",
+    "class-transformer": "^0.5.1",
+    "helmet": "^8.0.0",
+    "ioredis": "^5.4.1",
+    "multer": "^1.4.5-lts.1",
+    "nestjs-pino": "^4.1.0",
+    "nestjs-zod": "^3.0.0",
+    "nodemailer": "^6.9.15",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.1",
+    "passport-google-oauth20": "^2.0.0",
+    "passport-github2": "^0.1.12",
+    "pino-http": "^10.3.0",
+    "prom-client": "^15.1.3",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/express-session": "^1.19.0",
+    "@types/multer": "^1.4.12",
+    "@types/node": "^22.0.0",
+    "@types/nodemailer": "^6.4.16",
+    "@types/passport-jwt": "^4.0.1",
+    "@types/passport-google-oauth20": "^2.0.16",
+    "@types/passport-github2": "^1.2.9",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "@swc/core": "^1.13.0",
+    "unplugin-swc": "^1.5.10",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.3.3",
+    "prisma": "^6.0.0",
+    "supertest": "^7.0.0",
+    "@types/supertest": "^6.0.2",
+    "dotenv-cli": "^7.4.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}