nestforge-generator 0.1.0

package/templates/typeorm/README.pt-BR.md

@@ -0,0 +1,266 @@
+# NestForge
+
+[English](README.md) | **Português**
+
+> Production-ready NestJS starter with TypeORM, Authentication, Docker, Testing, CI/CD and Clean Architecture.
+
+[![CI](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml/badge.svg)](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![NestJS](https://img.shields.io/badge/NestJS-11-red)](https://nestjs.com)
+
+NestForge é um boilerplate de NestJS pensado para acelerar o início de projetos backend sérios, com autenticação completa, arquitetura limpa, segurança e observabilidade já configuradas. A ideia é você clonar, rodar `docker compose up` e já ter uma API pronta para evoluir.
+
+## ✨ Features
+
+- 🔐 **Autenticação configurável** — JWT com access/refresh token, Session/Cookies persistida no TypeORM, OAuth-only ou nenhuma autenticação
+- 🌐 **OAuth** — Google e GitHub, integrado à estratégia de token ou sessão escolhida
+- 👥 **RBAC** — Roles (Admin, Manager, User) e Permissions granulares
+- 🛡️ **Segurança** — Helmet, CORS, Rate Limiting, validação e serialização com Zod
+- 🗄️ **Banco de dados** — TypeORM com PostgreSQL, MySQL ou SQLite
+- 📨 **E-mails** — filas com BullMQ + Redis, testado localmente com Mailpit
+- 📄 **Documentação automática** — Swagger
+- 🪵 **Logs estruturados** — Pino
+- ✅ **Testes** — unitários e de integração com Vitest
+- 🐳 **Docker** — ambiente completo com um comando
+- ⚙️ **CI/CD** — GitHub Actions (build, lint, test)
+
+## 🧱 Stack
+
+| Camada | Tecnologia |
+|---|---|
+| Framework | NestJS + TypeScript |
+| ORM | TypeORM |
+| Banco | PostgreSQL, MySQL ou SQLite |
+| Cache / Filas | Redis + BullMQ |
+| Autenticação | JWT, Session/Cookies ou OAuth com Passport |
+| Validação | Zod + nestjs-zod (schemas viram DTO + Swagger automaticamente) |
+| Docs | Swagger |
+| E-mail (dev) | Mailpit |
+| Testes | Vitest |
+| CI | GitHub Actions |
+
+## 📁 Estrutura de pastas
+
+```
+src/
+│
+├── auth/          # login, sessões/tokens, OAuth, guards e strategies
+├── users/         # CRUD de usuários
+├── common/        # decorators, filters, guards, interceptors, pipes, utils
+├── config/        # configuração tipada e validada (env)
+├── database/      # DataSource, configuração, migrations e seed
+├── modules/       # módulos de domínio adicionais
+├── shared/        # código compartilhado entre módulos
+├── jobs/          # filas e workers (BullMQ)
+├── mail/          # templates e envio de e-mail
+└── main.ts
+```
+
+## 🚀 Começando
+
+### Pré-requisitos
+
+- Node.js 20+
+- Docker e Docker Compose
+
+### Rodando com Docker (recomendado)
+
+```bash
+git clone https://github.com/jeiel2013/nestforge.git
+cd nestforge
+cp .env.example .env
+docker compose up
+```
+
+Isso sobe: API, PostgreSQL, Redis e Mailpit (interface de e-mail em `http://localhost:8025`).
+
+### Rodando localmente
+
+```bash
+npm install
+cp .env.example .env
+npm run migration:generate -- src/database/migrations/InitialSchema
+npm run migration:run
+npm run seed
+npm run start:dev
+```
+
+A documentação Swagger fica disponível em `http://localhost:3000/docs`.
+
+## 🔑 Roles & Permissions
+
+| Role | Descrição |
+|---|---|
+| `ADMIN` | acesso total ao sistema |
+| `MANAGER` | gerencia usuários e relatórios |
+| `USER` | acesso padrão |
+
+Permissions são granulares (`user:create`, `user:delete`, `report:read`, etc) e combinadas com roles via decorators (`@Roles()`, `@Permissions()`).
+
+## 🗺️ Roadmap
+
+- [x] Autenticação por JWT
+- [x] Autenticação por Session/Cookies
+- [x] OAuth Google/GitHub
+- [x] Estratégia OAuth-only
+- [x] Geração sem autenticação
+- [x] Refresh Token
+- [x] Docker
+- [x] CI (build, lint, test)
+- [x] OAuth (Google/GitHub)
+- [x] Upload de arquivos
+- [x] Filas (BullMQ)
+- [x] E-mails transacionais
+- [x] RBAC completo (permissions granulares)
+- [x] Testes de integração completos
+- [x] Documentação completa (Swagger + guia de arquitetura)
+
+Veja o [ROADMAP.pt-BR.md](ROADMAP.pt-BR.md) detalhado.
+
+### Configurando o login social (OAuth)
+
+Para habilitar login via Google e GitHub, crie um OAuth App em cada provedor e preencha no `.env`:
+
+```bash
+APP_URL=http://localhost:3000
+
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+```
+
+- **Google**: crie as credenciais no [Google Cloud Console](https://console.cloud.google.com/apis/credentials) e configure a URL de callback como `{APP_URL}/auth/google/callback`.
+- **GitHub**: crie um OAuth App em `Settings > Developer settings > OAuth Apps` e configure a mesma URL de callback, trocando para `{APP_URL}/auth/github/callback`.
+
+Depois é só acessar `GET /auth/google` ou `GET /auth/github`. No callback, a API emite access/refresh tokens ou estabelece uma sessão por cookie, conforme a estratégia escolhida. Se for o primeiro acesso, uma conta é criada e vinculada ao provedor.
+
+### Autenticação por Session/Cookies
+
+Quando o projeto é gerado com Session/Cookies, cadastro e login criam uma sessão persistida no banco por `connect-typeorm`. O identificador é enviado no cookie `nestforge.sid`, configurado com `httpOnly`, `sameSite=lax` e `secure` em produção.
+
+Configure no `.env`:
+
+```bash
+SESSION_SECRET=use-um-segredo-com-pelo-menos-32-caracteres
+SESSION_MAX_AGE=604800000
+```
+
+### Recuperação de senha e verificação de e-mail
+
+Todo cadastro (`POST /auth/register`) já dispara um e-mail de verificação automaticamente. Os e-mails são enfileirados com BullMQ/Redis e processados por um worker que envia via SMTP — em desenvolvimento, tudo cai no Mailpit (`http://localhost:8025`), então nada sai pra internet de verdade.
+
+| Rota | O que faz |
+|---|---|
+| `POST /auth/forgot-password` | Recebe um `email` e enfileira o envio do link de redefinição (resposta sempre genérica, não revela se o e-mail existe) |
+| `POST /auth/reset-password` | Recebe `token` + `password` e troca a senha; também revoga os refresh tokens ativos do usuário |
+| `GET /auth/verify-email?token=...` | Confirma o e-mail a partir do link recebido |
+
+Os tokens de reset e verificação expiram em 1 hora e 24 horas, respectivamente, e são de uso único.
+
+## 🔑 Roles & Permissions
+
+| Role | Descrição |
+|---|---|
+| `ADMIN` | acesso total ao sistema |
+| `MANAGER` | gerencia usuários e relatórios |
+| `USER` | acesso padrão |
+
+Cada role tem um conjunto fixo de permissões, mapeado em `src/common/constants/role-permissions.ts`:
+
+| Permission | ADMIN | MANAGER | USER |
+|---|:---:|:---:|:---:|
+| `user:create` | ✅ | ❌ | ❌ |
+| `user:read` | ✅ | ✅ | ✅ |
+| `user:update` | ✅ | ✅ | ❌ |
+| `user:delete` | ✅ | ❌ | ❌ |
+| `report:read` | ✅ | ✅ | ❌ |
+
+Nas rotas, use `@Permissions(Permission.UserCreate)` para exigir uma permissão específica, ou `@Roles(Role.ADMIN)` quando o controle por cargo já for suficiente. Os dois guards (`RolesGuard` e `PermissionsGuard`) rodam globalmente e só bloqueiam a rota se ela tiver o decorator correspondente.
+
+## 👥 Usuários: paginação, filtros e avatar
+
+`GET /users` aceita query params pra paginar e filtrar a listagem:
+
+```bash
+GET /users?page=2&limit=20&search=jeiel&role=ADMIN
+```
+
+| Parâmetro | Descrição |
+|---|---|
+| `page` | página atual (padrão: 1) |
+| `limit` | itens por página, até 100 (padrão: 10) |
+| `search` | busca por nome ou e-mail (case-insensitive) |
+| `role` | filtra por `ADMIN`, `MANAGER` ou `USER` |
+
+A resposta vem no formato `{ data, meta: { total, page, limit, totalPages } }`.
+
+Pra trocar o avatar do usuário autenticado:
+
+```bash
+curl -X POST http://localhost:3000/users/me/avatar \
+  -H "Authorization: Bearer <accessToken>" \
+  -F "file=@/caminho/da/foto.png"
+```
+
+Aceita PNG, JPEG e WEBP até 2MB; o arquivo fica salvo em `./uploads/avatars` e é servido em `/uploads/avatars/<arquivo>`.
+
+## 🛡️ Segurança: serialização e CSRF
+
+Toda validação de entrada (`body`, `query`) usa **Zod** via [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod): cada DTO é um `z.object({...})` transformado em classe com `createZodDto(schema)`, validado globalmente pelo `ZodValidationPipe`. O `patchNestJsSwagger()` no bootstrap ensina o Swagger a ler esses schemas automaticamente — não precisa duplicar validação (Zod) e documentação (`@ApiProperty`) como no `class-validator`. Os schemas exportados (ex.: `createUserSchema`) também podem ser reaproveitados/combinados (como o `updateUserSchema`, que é só um `createUserSchema.partial()`).
+
+- 🪵 **Observabilidade** — logs estruturados com Pino, health checks (`/health`) e métricas Prometheus (`/metrics`)
+
+O seed cria três contas de teste, uma por role:
+
+| E-mail | Senha | Role |
+|---|---|---|
+| `admin@nestforge.dev` | `admin123` | ADMIN |
+| `manager@nestforge.dev` | `manager123` | MANAGER |
+| `user@nestforge.dev` | `user1234` | USER |
+
+## 📈 Observabilidade
+
+`GET /health` retorna o status agregado da API — banco (TypeORM), Redis, memória (heap/RSS) e espaço em disco — usando `@nestjs/terminus`. Cada verificação aparece individualmente na resposta, então dá pra saber exatamente o que caiu.
+
+`GET /metrics` expõe métricas no formato do Prometheus (via `prom-client`): as métricas padrão de Node.js (CPU, memória, event loop) mais `http_request_duration_seconds` (histograma) e `http_requests_total` (contador), ambas com labels de `method`, `route` e `status_code`. Basta apontar um scrape job do Prometheus pra essa rota.
+
+## 🧪 Testes
+
+```bash
+npm run test          # unitários
+npm run test:e2e      # integração (e2e)
+npm run test:cov      # cobertura
+```
+
+Os testes e2e (`test/*.e2e-spec.ts`) sobem a aplicação real (Nest + TypeORM + Redis) e batem nos endpoints com `supertest`, usando um banco isolado (`.env.test`, banco `nestforge_test` — nunca o de desenvolvimento). Antes de rodar pela primeira vez:
+
+```bash
+createdb nestforge_test   # ou: psql -U nestforge -c "CREATE DATABASE nestforge_test;"
+docker compose up -d postgres redis
+npm run test:e2e
+```
+
+O script `pretest:e2e` já aplica as migrations nesse banco automaticamente antes de cada rodada. Cada teste limpa as tabelas antes de rodar (`test/utils/clean-database.ts`), então não precisa zerar nada manualmente entre execuções. Hoje cobrem o fluxo de autenticação completo (registro, login, refresh, logout, e-mail duplicado, credenciais inválidas) e o CRUD de usuários com RBAC (ADMIN consegue tudo, USER lê mas não cria, `/users/me`, acesso sem token).
+
+Os testes unitários (`src/**/*.spec.ts`) rodam isolados, com os repositories do TypeORM e o `ioredis` mockados (`vi.fn()` / `vi.mock()`) — não precisam de banco nem Redis de verdade. Hoje cobrem: `AuthService` (registro/login), `UsersService` (CRUD completo + paginação + confirmação de que o `passwordHash` não vaza na serialização via `instanceToPlain`), `RolesGuard`, `PermissionsGuard` e os indicadores de saúde (`TypeOrmHealthIndicator`, `RedisHealthIndicator`).
+
+## 📚 Documentação adicional
+
+- [ARCHITECTURE.pt-BR.md](ARCHITECTURE.pt-BR.md) — como o projeto é organizado e por que certas decisões de design foram tomadas (Zod vs. class-validator, permissions em código vs. banco, BullMQ, etc.)
+- [TESTING.pt-BR.md](TESTING.pt-BR.md) — como validar migrations, build, testes unitários e testes E2E
+- [docs/adding-a-module.md](docs/adding-a-module.md) — passo a passo pra adicionar um recurso novo seguindo as convenções do projeto
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Veja o [CONTRIBUTING.pt-BR.md](CONTRIBUTING.pt-BR.md) para o guia completo.
+
+## 📄 Licença
+
+Este projeto está sob a licença MIT — veja [LICENSE](LICENSE).
+
+---
+
+Feito por [Jeiel Alves](https://github.com/jeiel2013) · [jeieldev.com.br](https://jeieldev.com.br)

package/templates/typeorm/ROADMAP.md

@@ -0,0 +1,79 @@
+# Roadmap
+
+**English** | [Português](ROADMAP.pt-BR.md)
+
+This roadmap makes it clear what is ready and where contributions are possible. PRs for any open item are very welcome — open an issue first for large changes so the approach can be aligned.
+
+## Authentication
+
+- [x] Login
+- [x] Registration
+- [x] Logout
+- [x] Refresh Token
+- [x] Forgot Password
+- [x] Reset Password
+- [x] Email Verification
+- [x] Google OAuth
+- [x] GitHub OAuth
+
+## Users
+
+- [x] Basic CRUD
+- [x] Pagination and advanced filters
+- [x] Avatar upload
+
+## RBAC
+
+- [x] Roles (Admin, Manager, User)
+- [x] Granular permissions (`user:create`, `report:read`, etc.)
+- [x] Guard combining roles + permissions
+
+## Security
+
+- [x] Helmet
+- [x] CORS
+- [x] Rate Limit
+- [x] Validation (Zod + nestjs-zod, integrated with Swagger through `createZodDto`)
+- [x] Serialization (output interceptor)
+- [x] CSRF (when required)
+
+## Database
+
+- [x] TypeORM
+- [x] PostgreSQL
+- [x] MySQL
+- [x] SQLite
+- [x] Migrations
+- [x] Seed with users for the default roles
+
+## Infrastructure
+
+- [x] Docker / docker-compose (API, Postgres, Redis, Mailpit)
+- [x] GitHub Actions CI (build, lint, test)
+- [ ] Automated deployment (Railway/Fly.io example)
+
+## Observability
+
+- [x] Structured logging with Pino
+- [x] Health checks (`/health`)
+- [x] Metrics (optional Prometheus)
+
+## Jobs & Email
+
+- [x] BullMQ queue
+- [x] Transactional email delivery (Mailpit in development)
+- [x] Email templates
+
+## Tests
+
+- [x] Unit test structure (Vitest)
+- [x] Integration tests (auth + users)
+
+## Documentation
+
+- [x] Initial README
+- [x] Complete Swagger with request/response examples
+- [x] Architecture guide (ADR / design decisions)
+- [x] “How to add a new module” guide
+
+---

package/templates/typeorm/ROADMAP.pt-BR.md

@@ -0,0 +1,67 @@
+# Roadmap
+
+[English](ROADMAP.md) | **Português**
+
+Este roadmap existe para deixar claro o que já está pronto e onde dá pra contribuir. PRs para qualquer item em aberto são muito bem-vindos — abra uma issue antes se for algo grande, pra alinharmos a abordagem.
+
+## Autenticação
+- [x] Login
+- [x] Cadastro
+- [x] Logout
+- [x] Refresh Token
+- [x] Forgot Password
+- [x] Reset Password
+- [x] Email Verification
+- [x] OAuth Google
+- [x] OAuth GitHub
+
+## Usuários
+- [x] CRUD básico
+- [x] Paginação e filtros avançados
+- [x] Upload de avatar
+
+## RBAC
+- [x] Roles (Admin, Manager, User)
+- [x] Permissions granulares (`user:create`, `report:read`, etc)
+- [x] Guard combinando roles + permissions
+
+## Segurança
+- [x] Helmet
+- [x] CORS
+- [x] Rate Limit
+- [x] Validação (Zod + nestjs-zod, integrado ao Swagger via `createZodDto`)
+- [x] Serialização (interceptor de output)
+- [x] CSRF (quando necessário)
+
+## Banco de dados
+- [x] TypeORM
+- [x] PostgreSQL
+- [x] MySQL
+- [x] SQLite
+- [x] Migrations
+- [x] Seed com usuários para as roles padrão
+
+## Infra
+- [x] Docker / docker-compose (API, Postgres, Redis, Mailpit)
+- [x] GitHub Actions CI (build, lint, test)
+- [ ] Deploy automatizado (exemplo com Railway/Fly.io)
+
+## Observabilidade
+- [x] Logs estruturados com Pino
+- [x] Health checks (`/health`)
+- [x] Métricas (Prometheus opcional)
+
+## Jobs & E-mail
+- [x] Fila com BullMQ
+- [x] Envio de e-mail transacional (Mailpit em dev)
+- [x] Templates de e-mail
+
+## Testes
+- [x] Estrutura de testes unitários (Vitest)
+- [x] Testes de integração (auth + users)
+
+## Documentação
+- [x] README inicial
+- [x] Swagger completo com exemplos de request/response
+- [x] Guia de arquitetura (ADR / decisões de design)
+- [x] Guia "como adicionar um novo módulo"

package/templates/typeorm/TESTING.md

@@ -0,0 +1,114 @@
+# Testing the TypeORM template
+
+**English** | [Português](TESTING.pt-BR.md)
+
+This guide validates a project generated from the NestForge TypeORM 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. Make sure the installed `better-sqlite3` version supports your Node version.
+
+## Prepare the environment
+
+```bash
+npm install
+cp .env.example .env
+cp .env.example .env.test
+```
+
+Use different databases in `.env` and `.env.test`.
+
+## Generate and apply a migration
+
+```bash
+npm run migration:generate -- src/database/migrations/InitialSchema
+npm run migration:run
+```
+
+Run the seed when the generated project includes password authentication:
+
+```bash
+npm run 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 TypeORM repositories and Redis, so they do not require real services.
+
+## E2E tests
+
+```bash
+npm run test:e2e
+```
+
+The `pretest:e2e` script applies migrations using `.env.test` before the suite starts.
+
+Depending on the generated authentication strategy, the suite may cover JWT, Session/Cookies, CSRF, user CRUD, RBAC, and permissions.
+
+## Database-specific checks
+
+### PostgreSQL
+
+```bash
+docker compose up -d postgres
+npm run migration:run
+```
+
+### MySQL
+
+```bash
+docker compose up -d mysql
+npm run migration:run
+```
+
+### SQLite
+
+Set the database configuration to SQLite and run:
+
+```bash
+npm run migration:generate -- src/database/migrations/InitialSchema
+npm run migration:run
+npm run build
+npm test
+npm run test:e2e
+```
+
+Check the native driver when necessary:
+
+```bash
+npm ls better-sqlite3
+```
+
+## Final checklist
+
+* [ ] Dependencies install successfully
+* [ ] The correct database driver is installed
+* [ ] Migration is generated and reviewed
+* [ ] 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/typeorm/TESTING.pt-BR.md

@@ -0,0 +1,114 @@
+# Testando o template TypeORM
+
+[English](TESTING.md) | **Português**
+
+Este guia valida um projeto gerado a partir do template TypeORM 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. Confirme que a versão instalada do `better-sqlite3` oferece suporte à sua versão do Node.
+
+## Preparar o ambiente
+
+```bash
+npm install
+cp .env.example .env
+cp .env.example .env.test
+```
+
+Use bancos diferentes em `.env` e `.env.test`.
+
+## Gerar e aplicar uma migration
+
+```bash
+npm run migration:generate -- src/database/migrations/InitialSchema
+npm run migration:run
+```
+
+Execute o seed quando o projeto gerado incluir autenticação por senha:
+
+```bash
+npm run 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 os repositories do TypeORM e o Redis, portanto não exigem serviços reais.
+
+## Testes E2E
+
+```bash
+npm run test:e2e
+```
+
+O script `pretest:e2e` aplica as migrations usando `.env.test` antes do início da suíte.
+
+Dependendo da estratégia de autenticação gerada, a suíte pode cobrir JWT, Session/Cookies, CSRF, CRUD de usuários, RBAC e permissions.
+
+## Verificações específicas por banco
+
+### PostgreSQL
+
+```bash
+docker compose up -d postgres
+npm run migration:run
+```
+
+### MySQL
+
+```bash
+docker compose up -d mysql
+npm run migration:run
+```
+
+### SQLite
+
+Defina a configuração do banco como SQLite e execute:
+
+```bash
+npm run migration:generate -- src/database/migrations/InitialSchema
+npm run migration:run
+npm run build
+npm test
+npm run test:e2e
+```
+
+Confira o driver nativo quando necessário:
+
+```bash
+npm ls better-sqlite3
+```
+
+## Checklist final
+
+* [ ] As dependências são instaladas corretamente
+* [ ] O driver correto do banco está instalado
+* [ ] A migration é gerada e revisada
+* [ ] 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