nestforge-generator 0.1.0

package/templates/drizzle/ROADMAP.md

@@ -0,0 +1,143 @@
+# Roadmap
+
+**English** | [Português](ROADMAP.pt-BR.md)
+
+This roadmap presents the current state of the NestForge Drizzle ORM template and the areas that can still evolve.
+
+For large changes, open an issue before the pull request to align the implementation.
+
+## CLI and generation
+
+* [x] Project generation with Drizzle ORM
+* [x] TypeScript
+* [x] JavaScript generated from the TypeScript template
+* [x] PostgreSQL
+* [x] MySQL
+* [x] SQLite
+* [x] Removal of optional features through markers
+* [x] Removal of unused dependencies
+* [x] Final commands adapted to Drizzle
+* [x] Automated tests for generated combinations
+
+## Database
+
+* [x] Drizzle ORM
+* [x] PostgreSQL-specific schema
+* [x] MySQL-specific schema
+* [x] SQLite-specific schema
+* [x] Dynamic Drizzle Kit configuration
+* [x] Migration generation
+* [x] Migration execution
+* [x] Seed with users for the default roles
+* [x] Health check using the selected driver
+* [x] Transactions adapted to `better-sqlite3`
+* [x] Isolated database cleanup in E2E tests
+
+## Authentication
+
+* [x] JWT strategy
+* [x] Session/Cookies strategy
+* [x] OAuth-only strategy
+* [x] Project without authentication
+* [x] Login
+* [x] Registration
+* [x] Logout
+* [x] Access token
+* [x] Refresh token
+* [x] Refresh token revocation
+* [x] Password recovery
+* [x] Password reset
+* [x] Email verification
+* [x] Google OAuth
+* [x] GitHub OAuth
+* [x] Sessions persisted with `DrizzleSessionStore`
+* [x] CSRF protection for Session/Cookies
+
+## Users and authorization
+
+* [x] User CRUD
+* [x] Pagination
+* [x] Search and filters
+* [x] Avatar upload
+* [x] `ADMIN`, `MANAGER`, and `USER` roles
+* [x] Granular permissions
+* [x] Role and permission guards
+* [x] Optional RBAC removal through the CLI
+
+## Security
+
+* [x] Helmet
+* [x] Configurable CORS
+* [x] Rate limit
+* [x] Validation with Zod and `nestjs-zod`
+* [x] Response serialization
+* [x] CSRF protection for session authentication
+* [x] `httpOnly` cookies
+* [x] Secure cookies in production
+* [x] Environment variable validation
+
+## Optional features
+
+* [x] Docker and Docker Compose
+* [x] Swagger/OpenAPI
+* [x] Global validation
+* [x] Redis
+* [x] BullMQ
+* [x] Transactional email
+* [x] Mailpit for development
+* [x] RBAC and Permissions
+* [x] Optional `.env` file generation
+
+## Observability
+
+* [x] Structured logging with Pino
+* [x] Application health check
+* [x] Drizzle health check
+* [x] Redis health check
+* [x] Memory check
+* [x] Disk space check
+* [x] Prometheus-format metrics
+* [x] HTTP metrics
+
+## Tests
+
+* [x] Unit tests with Vitest
+* [x] E2E tests with Supertest
+* [x] JWT authentication tests
+* [x] Session/Cookies tests
+* [x] CSRF tests
+* [x] User tests
+* [x] RBAC tests
+* [x] Drizzle health check tests
+* [x] Separate test database
+* [x] Table cleanup between tests
+* [x] Smoke test with Drizzle, SQLite, and JWT
+* [x] Smoke test with Drizzle, SQLite, and Session/Cookies
+
+## CI and infrastructure
+
+* [x] GitHub Actions
+* [x] Reproducible installation with `npm ci`
+* [x] Migration generation and execution in CI
+* [x] Lint
+* [x] Build
+* [x] Unit tests
+* [x] E2E tests
+* [x] PostgreSQL, MySQL, and Redis services according to generation
+* [ ] Automated deployment example
+* [ ] Staging environment configuration example
+
+## Documentation
+
+* [x] Template README
+* [x] Architecture guide
+* [x] Guide for adding a module with Drizzle
+* [x] Feature marker guide
+* [x] Migration documentation
+* [x] Testing documentation
+* [x] Authentication documentation
+* [x] Observability documentation
+
+## Outside this template's scope
+
+MongoDB is not part of the current Drizzle template. MongoDB support belongs to the general CLI roadmap and will require its own persistence strategy.

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

@@ -0,0 +1,143 @@
+# Roadmap
+
+[English](ROADMAP.md) | **Português**
+
+Este roadmap apresenta o estado atual do template NestForge com Drizzle ORM e os pontos que ainda podem evoluir.
+
+Para mudanças grandes, abra uma issue antes do pull request para alinhar a implementação.
+
+## CLI e geração
+
+* [x] Geração de projetos com Drizzle ORM
+* [x] TypeScript
+* [x] JavaScript gerado a partir do template TypeScript
+* [x] PostgreSQL
+* [x] MySQL
+* [x] SQLite
+* [x] Remoção de recursos opcionais por marcadores
+* [x] Remoção de dependências não utilizadas
+* [x] Comandos finais adaptados ao Drizzle
+* [x] Testes automatizados das combinações geradas
+
+## Banco de dados
+
+* [x] Drizzle ORM
+* [x] Schema específico para PostgreSQL
+* [x] Schema específico para MySQL
+* [x] Schema específico para SQLite
+* [x] Configuração dinâmica do Drizzle Kit
+* [x] Geração de migrations
+* [x] Aplicação de migrations
+* [x] Seed com usuários para as roles padrão
+* [x] Health check usando o driver selecionado
+* [x] Transações adaptadas ao `better-sqlite3`
+* [x] Limpeza isolada do banco nos testes E2E
+
+## Autenticação
+
+* [x] Estratégia JWT
+* [x] Estratégia Session/Cookies
+* [x] Estratégia OAuth-only
+* [x] Projeto sem autenticação
+* [x] Login
+* [x] Cadastro
+* [x] Logout
+* [x] Access token
+* [x] Refresh token
+* [x] Revogação de refresh token
+* [x] Recuperação de senha
+* [x] Redefinição de senha
+* [x] Verificação de e-mail
+* [x] OAuth com Google
+* [x] OAuth com GitHub
+* [x] Sessões persistidas com `DrizzleSessionStore`
+* [x] Proteção CSRF para Session/Cookies
+
+## Usuários e autorização
+
+* [x] CRUD de usuários
+* [x] Paginação
+* [x] Busca e filtros
+* [x] Upload de avatar
+* [x] Roles `ADMIN`, `MANAGER` e `USER`
+* [x] Permissions granulares
+* [x] Guards de roles e permissions
+* [x] Remoção opcional de RBAC pela CLI
+
+## Segurança
+
+* [x] Helmet
+* [x] CORS configurável
+* [x] Rate limit
+* [x] Validação com Zod e `nestjs-zod`
+* [x] Serialização de respostas
+* [x] Proteção CSRF para autenticação por sessão
+* [x] Cookies `httpOnly`
+* [x] Cookies seguros em produção
+* [x] Validação das variáveis de ambiente
+
+## Recursos opcionais
+
+* [x] Docker e Docker Compose
+* [x] Swagger/OpenAPI
+* [x] Validação global
+* [x] Redis
+* [x] BullMQ
+* [x] E-mail transacional
+* [x] Mailpit para desenvolvimento
+* [x] RBAC e Permissions
+* [x] Geração opcional do arquivo `.env`
+
+## Observabilidade
+
+* [x] Logs estruturados com Pino
+* [x] Health check da aplicação
+* [x] Health check do Drizzle
+* [x] Health check do Redis
+* [x] Verificação de memória
+* [x] Verificação de espaço em disco
+* [x] Métricas no formato Prometheus
+* [x] Métricas HTTP
+
+## Testes
+
+* [x] Testes unitários com Vitest
+* [x] Testes E2E com Supertest
+* [x] Testes de autenticação JWT
+* [x] Testes de Session/Cookies
+* [x] Testes de CSRF
+* [x] Testes de usuários
+* [x] Testes de RBAC
+* [x] Testes do health check Drizzle
+* [x] Banco separado para testes
+* [x] Limpeza das tabelas entre testes
+* [x] Smoke test com Drizzle, SQLite e JWT
+* [x] Smoke test com Drizzle, SQLite e Session/Cookies
+
+## CI e infraestrutura
+
+* [x] GitHub Actions
+* [x] Instalação reproduzível com `npm ci`
+* [x] Geração e aplicação de migrations no CI
+* [x] Lint
+* [x] Build
+* [x] Testes unitários
+* [x] Testes E2E
+* [x] Serviços PostgreSQL, MySQL e Redis conforme a geração
+* [ ] Exemplo de deploy automatizado
+* [ ] Exemplo de configuração para ambiente de staging
+
+## Documentação
+
+* [x] README do template
+* [x] Guia de arquitetura
+* [x] Guia para adicionar um módulo com Drizzle
+* [x] Guia de marcadores de funcionalidades
+* [x] Documentação de migrations
+* [x] Documentação de testes
+* [x] Documentação de autenticação
+* [x] Documentação de observabilidade
+
+## Fora do escopo deste template
+
+MongoDB não faz parte do template Drizzle atual. O suporte a MongoDB pertence ao roadmap geral da CLI e exigirá uma estratégia de persistência própria.

package/templates/drizzle/TESTING.md

@@ -0,0 +1,136 @@
+# Testing the Drizzle template
+
+**English** | [Português](TESTING.pt-BR.md)
+
+This guide validates a project generated from the NestForge Drizzle 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 migrations
+
+```bash
+npm run drizzle:generate
+npm run drizzle:migrate
+```
+
+Review the SQL files generated under `drizzle/` before applying them to shared or production environments.
+
+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 the Drizzle instance and Redis, so they do not require real services.
+
+## E2E tests
+
+Generate migrations at least once before the first E2E run:
+
+```bash
+npm run drizzle:generate
+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 drizzle:migrate
+```
+
+### MySQL
+
+```bash
+docker compose up -d mysql
+npm run drizzle:migrate
+```
+
+### SQLite
+
+Set the database URL to a local file:
+
+```dotenv
+DATABASE_URL="file:./dev.db"
+```
+
+Then run:
+
+```bash
+npm run drizzle:generate
+npm run drizzle:migrate
+npm run seed
+npm run build
+npm test
+npm run test:e2e
+```
+
+Check the dependencies and migration artifacts:
+
+```bash
+npm ls drizzle-orm drizzle-kit better-sqlite3
+```
+
+```powershell
+Get-ChildItem .\drizzle -Recurse
+```
+
+## SQLite transaction behavior
+
+`better-sqlite3` uses synchronous transactions. Transaction callbacks must not return a `Promise`, and write operations use methods such as `.run()`.
+
+PostgreSQL and MySQL use asynchronous transaction callbacks with `await`.
+
+## Final checklist
+
+* [ ] Dependencies install successfully
+* [ ] The correct database driver is installed
+* [ ] Migrations are 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/drizzle/TESTING.pt-BR.md

@@ -0,0 +1,136 @@
+# Testando o template Drizzle
+
+[English](TESTING.md) | **Português**
+
+Este guia valida um projeto gerado a partir do template Drizzle 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 migrations
+
+```bash
+npm run drizzle:generate
+npm run drizzle:migrate
+```
+
+Revise os arquivos SQL gerados em `drizzle/` antes de aplicá-los em ambientes compartilhados ou de produção.
+
+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 a instância do Drizzle e o Redis, portanto não exigem serviços reais.
+
+## Testes E2E
+
+Gere as migrations pelo menos uma vez antes da primeira execução E2E:
+
+```bash
+npm run drizzle:generate
+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 drizzle:migrate
+```
+
+### MySQL
+
+```bash
+docker compose up -d mysql
+npm run drizzle:migrate
+```
+
+### SQLite
+
+Defina a URL do banco como um arquivo local:
+
+```dotenv
+DATABASE_URL="file:./dev.db"
+```
+
+Depois execute:
+
+```bash
+npm run drizzle:generate
+npm run drizzle:migrate
+npm run seed
+npm run build
+npm test
+npm run test:e2e
+```
+
+Confira as dependências e os artefatos das migrations:
+
+```bash
+npm ls drizzle-orm drizzle-kit better-sqlite3
+```
+
+```powershell
+Get-ChildItem .\drizzle -Recurse
+```
+
+## Comportamento das transações SQLite
+
+O `better-sqlite3` usa transações síncronas. As callbacks de transação não podem retornar uma `Promise`, e as operações de escrita usam métodos como `.run()`.
+
+PostgreSQL e MySQL usam callbacks de transação assíncronas com `await`.
+
+## Checklist final
+
+* [ ] As dependências são instaladas corretamente
+* [ ] O driver correto do banco está instalado
+* [ ] As migrations são geradas e revisadas
+* [ ] 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/drizzle/docker-compose.yml

@@ -0,0 +1,82 @@
+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
+      # nestforge:feature:redis
+      - redis
+      # nestforge:feature:redis:end
+    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
+
+  # nestforge:feature:redis
+  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:redis:end
+
+  # nestforge:feature:database:postgres
+volumes:
+  postgres_data:
+  # nestforge:feature:database:postgres:end
+  # nestforge:feature:database:mysql
+volumes:
+  mysql_data:
+  # nestforge:feature:database:mysql:end