nestforge-generator 0.1.0

package/templates/prisma/.env.test

@@ -0,0 +1,37 @@
+NODE_ENV=test
+PORT=3000
+APP_URL=http://localhost:3000
+CORS_ORIGINS=http://localhost:5173
+
+# Banco isolado, nunca o de desenvolvimento
+DATABASE_URL="postgresql://nestforge:nestforge@localhost:5432/nestforge_test?schema=public"
+
+# nestforge:feature:auth:token
+JWT_ACCESS_SECRET=test-access-secret-0123456789
+JWT_ACCESS_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=test-refresh-secret-0123456789
+JWT_REFRESH_EXPIRES_IN=7d
+# nestforge:feature:auth:token:end
+
+GOOGLE_CLIENT_ID=test-google-client-id
+GOOGLE_CLIENT_SECRET=test-google-client-secret
+GITHUB_CLIENT_ID=test-github-client-id
+GITHUB_CLIENT_SECRET=test-github-client-secret
+
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+MAIL_HOST=localhost
+MAIL_PORT=1025
+MAIL_FROM="NestForge <no-reply@nestforge.dev>"
+
+# limite bem mais alto pra não interferir nos testes
+THROTTLE_TTL=60
+THROTTLE_LIMIT=1000
+
+# nestforge:feature:auth:session
+SESSION_SECRET=test-session-secret-01234567890123456789
+SESSION_MAX_AGE=604800000
+
+ENABLE_CSRF=true
+# nestforge:feature:auth:session:end

package/templates/prisma/.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-test-lint:
+    runs-on: ubuntu-latest
+
+    services:
+      # nestforge:feature:database:postgres
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: nestforge
+          POSTGRES_PASSWORD: nestforge
+          POSTGRES_DB: nestforge
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      # nestforge:feature:database:postgres:end
+
+      # nestforge:feature:database:mysql
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_USER: nestforge
+          MYSQL_PASSWORD: nestforge
+          MYSQL_ROOT_PASSWORD: nestforge
+          MYSQL_DATABASE: nestforge
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h localhost"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      # nestforge:feature:database:mysql:end
+
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      # nestforge:feature:database:postgres
+      DATABASE_URL: postgresql://nestforge:nestforge@localhost:5432/nestforge?schema=public
+      # nestforge:feature:database:postgres:end
+      # nestforge:feature:database:mysql
+      DATABASE_URL: mysql://nestforge:nestforge@localhost:3306/nestforge
+      # nestforge:feature:database:mysql:end
+      # nestforge:feature:database:sqlite
+      DATABASE_URL: file:./ci-dev.db
+      # nestforge:feature:database:sqlite:end
+      JWT_ACCESS_SECRET: ci-access-secret-0123456789
+      JWT_REFRESH_SECRET: ci-refresh-secret-0123456789
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Instalar dependências
+        run: npm ci
+
+      - name: Gerar Prisma Client
+        run: npx prisma generate
+
+      - name: Rodar migrations
+        run: npx prisma migrate deploy
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Testes
+        run: npm run test
+
+      # nestforge:feature:database:postgres
+      - name: Criar banco de teste
+        run: PGPASSWORD=nestforge psql -h localhost -U nestforge -d nestforge -c "CREATE DATABASE nestforge_test;"
+      # nestforge:feature:database:postgres:end
+
+      # nestforge:feature:database:mysql
+      - name: Criar banco de teste
+        run: mysql -h 127.0.0.1 -u root -pnestforge -e "CREATE DATABASE IF NOT EXISTS nestforge_test;"
+      # nestforge:feature:database:mysql:end
+
+      - name: Testes e2e
+        run: npm run test:e2e

package/templates/prisma/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+**English** | [Português](ARCHITECTURE.pt-BR.md)
+
+This document explains how NestForge is organized and why certain design decisions were made. The goal is for someone new to the project to understand the “why,” not only the “what.”
+
+## Overview
+
+```
+Request → main.ts (global pipes/filters/interceptors)
+        → Guards (JwtAuthGuard → RolesGuard → PermissionsGuard)
+        → Controller (validates through a Zod DTO, delegates to the service)
+        → Service (business rules, calls Prisma)
+        → Prisma → PostgreSQL
+        → Response (passes through ClassSerializerInterceptor before becoming JSON)
+```
+
+Each domain module (`auth`, `users`, `mail`, `health`, `metrics`) follows the same structure:
+
+```
+<module>/
+├── dto/                     # input — one Zod schema + createZodDto per DTO
+├── entities/                # output — classes with @Exclude() for sensitive fields
+├── <module>.controller.ts   # orchestrates only: receives request, calls service, returns
+├── <module>.service.ts      # actual business rules
+└── <module>.module.ts       # wires everything together and declares exports
+```
+
+Controllers never communicate with Prisma directly — they always go through the service. This keeps business logic testable without starting the entire application (which is why unit tests mock only Prisma, not all of Nest).
+
+## Design decisions (short ADR)
+
+### Why Zod (with `nestjs-zod`) instead of `class-validator`?
+
+`class-validator` requires duplicated information: validation decorators (`@IsEmail()`) and documentation decorators (`@ApiProperty()`) describe the same thing in two different ways, and one can easily become outdated relative to the other. With Zod, the schema is the single source of truth — `nestjs-zod` generates the DTO and Swagger documentation from it. See `src/*/dto/*.dto.ts` and `patchNestJsSwagger()` in `src/main.ts`.
+
+### Why Prisma without a repository layer on top?
+
+Prisma Client is effectively already a type-safe repository. Adding an abstraction layer on top merely to “follow the pattern” would add indirection without a real benefit in this project (there is no plan to replace the ORM). Services call `this.prisma.<model>` directly.
+
+### Why are permissions a fixed map in code (`ROLE_PERMISSIONS`) instead of a database table?
+
+A fully dynamic permission system (`roles`, `permissions`, and `role_permissions` tables) is overkill for a starter — most projects created from it will have 3–5 fixed roles. Keeping the mapping in `src/common/constants/role-permissions.ts` makes it explicitly auditable: the entire permission array for every role is visible in one file. If the project grows enough to require permissions configurable at runtime (for example, an administrator creating custom roles through the UI), then migrating to database tables becomes worthwhile.
+
+### Why BullMQ for email instead of sending it directly in the request?
+
+Sending email is a network operation (SMTP) that can fail or take time. If it happened inside `POST /auth/register`, instability in the email provider would make registration slow or show an error even when the account had been created. The queue decouples these operations: the request responds as soon as the job is queued, and `MailProcessor` handles delivery (with retries) in the background.
+
+### Why store hashed refresh tokens in the database instead of trusting only the JWT?
+
+A JWT cannot be revoked before it expires. Storing the refresh token hash in the database makes it possible to invalidate sessions properly (logout, password change, stolen refresh token) — this is why `resetPassword` revokes all active refresh tokens for the user.
+
+### Why use `UserEntity` + `ClassSerializerInterceptor` instead of only a Prisma `select`?
+
+Both intentionally coexist. The `select` avoids unnecessarily retrieving `passwordHash` from the database; `@Exclude()` on the entity is a second barrier — even if a future query forgets the `select`, the field does not escape into the HTTP response. This is defense in depth, not redundancy.
+
+### Why is CSRF disabled by default?
+
+The API uses a Bearer token in the `Authorization` header, not a session cookie. CSRF exploits the browser automatically sending cookies across origins, which does not apply here. The middleware is ready in `src/common/middleware/csrf.middleware.ts` for projects that adapt the starter to store the token in a cookie.
+
+## Authentication flow in detail
+
+1. `POST /auth/register` or `/login` → `AuthService` generates an `accessToken` (15 min) + `refreshToken` (7 days) pair and stores the refresh token hash in the database.
+2. Protected routes pass through `JwtAuthGuard`, which validates the `accessToken` and populates `req.user` with `{ id, email, role }` through `JwtStrategy`.
+3. `RolesGuard` and `PermissionsGuard` read `req.user.role` and decide whether to allow the route using its `@Roles()` / `@Permissions()` decorators.
+4. When the `accessToken` expires, the client calls `POST /auth/refresh` — the old refresh token is revoked and a new pair is issued (token rotation).
+
+## Where to add something new
+
+If you are adding a new feature (rather than only changing auth/users), see [`docs/adding-a-module.md`](docs/adding-a-module.md) — it is a step-by-step guide that applies the conventions above to a module built from scratch.

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

@@ -0,0 +1,63 @@
+# Arquitetura
+
+[English](ARCHITECTURE.md) | **Português**
+
+Este documento explica como o NestForge está organizado e por que certas decisões de design foram tomadas. O objetivo é que alguém novo no projeto consiga entender o "porquê", não só o "o quê".
+
+## Visão geral
+
+```
+Request → main.ts (pipes/filters/interceptors globais)
+        → Guards (JwtAuthGuard → RolesGuard → PermissionsGuard)
+        → Controller (valida via DTO Zod, delega pro service)
+        → Service (regra de negócio, chama o Prisma)
+        → Prisma → PostgreSQL
+        → Response (passa pelo ClassSerializerInterceptor antes de virar JSON)
+```
+
+Cada módulo de domínio (`auth`, `users`, `mail`, `health`, `metrics`) segue a mesma forma:
+
+```
+<modulo>/
+├── dto/              # entrada — um schema Zod + createZodDto por DTO
+├── entities/          # saída — classes com @Exclude() pra campos sensíveis
+├── <modulo>.controller.ts   # só orquestra: recebe request, chama o service, devolve
+├── <modulo>.service.ts      # regra de negócio de verdade
+└── <modulo>.module.ts       # amarra tudo e declara o que exporta
+```
+
+Controllers nunca falam com o Prisma diretamente — sempre passam pelo service. Isso mantém a lógica de negócio testável sem precisar subir a aplicação inteira (é por isso que os testes unitários mockam só o Prisma, não o Nest todo).
+
+## Decisões de design (ADR curto)
+
+### Por que Zod (com `nestjs-zod`) em vez de `class-validator`?
+`class-validator` obriga a duplicar informação: os decorators de validação (`@IsEmail()`) e os decorators de documentação (`@ApiProperty()`) descrevem a mesma coisa de duas formas diferentes, e é fácil um ficar desatualizado em relação ao outro. Com Zod, o schema é a única fonte de verdade — `nestjs-zod` gera o DTO e o Swagger a partir dele. Ver `src/*/dto/*.dto.ts` e `patchNestJsSwagger()` em `src/main.ts`.
+
+### Por que Prisma sem uma camada de "repository" por cima?
+Prisma Client já é, na prática, um repository type-safe — adicionar uma camada de abstração em cima dele só pra "seguir o padrão" adicionaria indireção sem trazer benefício real neste projeto (não há plano de trocar de ORM). Os services chamam `this.prisma.<model>` diretamente.
+
+### Por que permissions são um mapa fixo em código (`ROLE_PERMISSIONS`) e não uma tabela no banco?
+Um sistema de permissions 100% dinâmico (tabelas `roles`, `permissions`, `role_permissions`) é overkill pra um boilerplate — a maioria dos projetos que nascem daqui vai ter 3-5 roles fixas. Manter o mapeamento em `src/common/constants/role-permissions.ts` deixa auditável de forma explícita: dá pra ver o array inteiro de permissões de cada role em um arquivo só. Se o seu projeto crescer a ponto de precisar de permissions configuráveis em runtime (ex.: um admin criando roles customizadas pela UI), aí sim vale migrar pra tabela.
+
+### Por que BullMQ para e-mails, e não enviar direto na request?
+Enviar e-mail é uma chamada de rede (SMTP) que pode falhar ou demorar — se isso acontecesse dentro do `POST /auth/register`, uma instabilidade no provedor de e-mail deixaria o cadastro lento ou o usuário veria erro mesmo com a conta criada. A fila desacopla isso: a request responde assim que o job é enfileirado, e o `MailProcessor` cuida do envio (com retry) em segundo plano.
+
+### Por que refresh tokens ficam no banco (hasheados) em vez de só confiar no JWT?
+Um JWT sozinho não pode ser revogado antes de expirar. Guardar o hash do refresh token no banco permite invalidar sessões de verdade (logout, troca de senha, refresh token roubado) — é por isso que `resetPassword` revoga todos os refresh tokens ativos do usuário.
+
+### Por que `UserEntity` + `ClassSerializerInterceptor` em vez de só um `select` no Prisma?
+As duas coisas coexistem de propósito. O `select` evita trazer o `passwordHash` do banco desnecessariamente; o `@Exclude()` na entidade é uma segunda barreira — mesmo que uma query futura esqueça o `select`, o campo não escapa pra resposta HTTP. Defesa em profundidade, não redundância.
+
+### Por que CSRF vem desligado por padrão?
+A API usa Bearer token no header `Authorization`, não cookie de sessão. CSRF explora o fato do navegador enviar cookies automaticamente entre origens — isso não se aplica aqui. O middleware existe pronto (`src/common/middleware/csrf.middleware.ts`) pra quem adaptar o boilerplate pra guardar token em cookie.
+
+## Fluxo de autenticação, em detalhe
+
+1. `POST /auth/register` ou `/login` → `AuthService` gera um par `accessToken` (15min) + `refreshToken` (7 dias), e guarda o hash do refresh no banco.
+2. Rotas protegidas passam pelo `JwtAuthGuard`, que valida o `accessToken` e popula `req.user` com `{ id, email, role }` (via `JwtStrategy`).
+3. `RolesGuard` e `PermissionsGuard` leem `req.user.role` e decidem se a rota é liberada, usando os decorators `@Roles()` / `@Permissions()` da rota.
+4. Quando o `accessToken` expira, o client chama `POST /auth/refresh` — o refresh token antigo é revogado e um novo par é emitido (rotação de token).
+
+## Onde adicionar coisa nova
+
+Se você está adicionando um recurso novo (não só mexendo em auth/users), veja [`docs/adding-a-module.md`](docs/adding-a-module.md) — é um passo a passo praticando as convenções acima num módulo do zero.

package/templates/prisma/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+**English** | [Português](CODE_OF_CONDUCT.pt-BR.md)
+
+## Our commitment
+
+We, as members, contributors, and maintainers, pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Respecting different viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Offensive comments or personal/political attacks
+- Public or private harassment
+- Publishing other people's private information without permission
+
+## Enforcement
+
+Instances of abusive behavior may be reported by opening an issue marked as confidential or by contacting the project maintainer directly. All complaints will be reviewed and investigated.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

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

@@ -0,0 +1,27 @@
+# Código de Conduta
+
+[English](CODE_OF_CONDUCT.md) | **Português**
+
+## Nosso compromisso
+
+Nós, como membros, contribuintes e mantenedores, nos comprometemos a fazer da participação neste projeto uma experiência livre de assédio para todos, independentemente de idade, corpo, deficiência, etnia, identidade e expressão de gênero, nível de experiência, nacionalidade, aparência pessoal, raça, religião ou orientação sexual.
+
+## Nossos padrões
+
+Exemplos de comportamento que contribuem para um ambiente positivo:
+- Usar linguagem acolhedora e inclusiva
+- Respeitar pontos de vista e experiências diferentes
+- Aceitar críticas construtivas com elegância
+- Focar no que é melhor para a comunidade
+
+Exemplos de comportamento inaceitável:
+- Uso de linguagem ou imagens sexualizadas
+- Comentários ofensivos ou ataques pessoais/políticos
+- Assédio público ou privado
+- Publicar informações privadas de terceiros sem permissão
+
+## Aplicação
+
+Casos de comportamento abusivo podem ser reportados abrindo uma issue marcada como confidencial ou entrando em contato diretamente com o mantenedor do projeto. Todas as reclamações serão revisadas e investigadas.
+
+Este Código de Conduta é adaptado do [Contributor Covenant](https://www.contributor-covenant.org), versão 2.1.

package/templates/prisma/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to NestForge
+
+**English** | [Português](CONTRIBUTING.pt-BR.md)
+
+Thank you for considering contributing! 🎉
+
+## Getting started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/nestforge.git`
+3. Create a branch: `git checkout -b feat/feature-name`
+4. Start the environment: `docker compose up` (or `npm install` + `npm run start:dev`)
+5. Make your changes
+6. Run tests and lint before committing: `npm run test && npm run lint`
+7. Commit according to the convention below
+8. Open a Pull Request describing what was changed and why
+
+## Commit convention
+
+We use Portuguese commit messages following [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: adiciona autenticação via Google OAuth
+fix: corrige validação do refresh token
+docs: atualiza guia de instalação
+test: adiciona testes de integração para users
+refactor: extrai lógica de hash para utils
+chore: atualiza dependências
+```
+
+## Code standards
+
+- If your code is related to an optional CLI feature (Swagger, Redis, RBAC, etc.), mark it according to [`docs/feature-markers.md`](docs/feature-markers.md). Without this, the CLI cannot remove the code when someone disables the feature.
+- Strict TypeScript (no unjustified `any`)
+- Always validate input through Zod (DTOs)
+- No business logic in controllers — controllers only orchestrate, services handle the logic
+- Every new route requires Swagger decorators (`@ApiTags`, `@ApiOperation`, etc.)
+- Every new feature requires tests (at least unit tests)
+
+## Reporting bugs
+
+Open an issue containing:
+
+- A description of the problem
+- Steps to reproduce it
+- Expected versus actual behavior
+- Node version / environment (Docker or local)
+
+## Suggesting features
+
+Before implementing, open an issue with the `enhancement` label describing the problem the feature solves. This avoids rework if the approach needs to be discussed.
+
+## Code of Conduct
+
+By contributing, you agree to follow the project's [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---

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

@@ -0,0 +1,54 @@
+# Contribuindo com o NestForge
+
+[English](CONTRIBUTING.md) | **Português**
+
+Obrigado por considerar contribuir! 🎉
+
+## Como começar
+
+1. Faça um fork do repositório
+2. Clone o seu fork: `git clone https://github.com/SEU_USUARIO/nestforge.git`
+3. Crie uma branch: `git checkout -b feat/nome-da-feature`
+4. Suba o ambiente: `docker compose up` (ou `npm install` + `npm run start:dev`)
+5. Faça suas alterações
+6. Rode os testes e o lint antes de commitar: `npm run test && npm run lint`
+7. Commit seguindo o padrão abaixo
+8. Abra um Pull Request descrevendo o que foi feito e por quê
+
+## Padrão de commits
+
+Usamos commits em português, seguindo [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: adiciona autenticação via Google OAuth
+fix: corrige validação do refresh token
+docs: atualiza guia de instalação
+test: adiciona testes de integração para users
+refactor: extrai lógica de hash para utils
+chore: atualiza dependências
+```
+
+## Padrões de código
+
+- Se o seu código for ligado a um recurso opcional da CLI (Swagger, Redis, RBAC, etc.), marque ele seguindo [`docs/feature-markers.md`](docs/feature-markers.md) — sem isso, a CLI não consegue remover o trecho quando alguém desliga o recurso.
+- TypeScript estrito (sem `any` sem justificativa)
+- Validação de entrada sempre via Zod (DTOs)
+- Nada de lógica de negócio no controller — controller só orquestra, service resolve
+- Toda rota nova precisa de decorators de Swagger (`@ApiTags`, `@ApiOperation`, etc)
+- Toda feature nova precisa de teste (unitário no mínimo)
+
+## Reportando bugs
+
+Abra uma issue com:
+- Descrição do problema
+- Passos para reproduzir
+- Comportamento esperado vs. atual
+- Versão do Node / ambiente (Docker ou local)
+
+## Sugerindo features
+
+Abra uma issue com a tag `enhancement` descrevendo o problema que a feature resolve antes de sair implementando — isso evita retrabalho caso a abordagem precise ser discutida.
+
+## Código de conduta
+
+Ao contribuir, você concorda em seguir o [Código de Conduta](CODE_OF_CONDUCT.pt-BR.md) do projeto.

package/templates/prisma/Dockerfile

@@ -0,0 +1,33 @@
+# --- Base ---
+FROM node:20-alpine AS base
+WORKDIR /app
+COPY package*.json ./
+COPY prisma ./prisma
+
+# --- Dependencies ---
+FROM base AS deps
+RUN npm ci
+
+# --- Development ---
+FROM deps AS development
+COPY . .
+RUN npx prisma generate
+EXPOSE 3000
+CMD ["npm", "run", "start:dev"]
+
+# --- Build ---
+FROM deps AS build
+COPY . .
+RUN npx prisma generate
+RUN npm run build
+RUN npm prune --production
+
+# --- Production ---
+FROM node:20-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/prisma ./prisma
+EXPOSE 3000
+CMD ["node", "dist/main.js"]

package/templates/prisma/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeiel Jedson Leão Alves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.