nestforge-generator 0.1.0

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

@@ -0,0 +1,119 @@
+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
+
+      # nestforge:feature:redis
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      # nestforge:feature:redis:end
+
+    env:
+      # nestforge:feature:database:postgres
+      DB_TYPE: postgres
+      DATABASE_URL: postgresql://nestforge:nestforge@localhost:5432/nestforge?schema=public
+      # nestforge:feature:database:postgres:end
+
+      # nestforge:feature:database:mysql
+      DB_TYPE: mysql
+      DATABASE_URL: mysql://nestforge:nestforge@localhost:3306/nestforge
+      # nestforge:feature:database:mysql:end
+
+      # nestforge:feature:database:sqlite
+      DB_TYPE: sqlite
+      DATABASE_URL: file:./ci-dev.db
+      # nestforge:feature:database:sqlite:end
+
+      # nestforge:feature:auth:token
+      JWT_ACCESS_SECRET: ci-access-secret-0123456789
+      JWT_REFRESH_SECRET: ci-refresh-secret-0123456789
+      # nestforge:feature:auth:token:end
+
+    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 migrations
+        run: npx drizzle-kit generate
+
+      - name: Rodar migrations
+        run: npx drizzle-kit migrate
+
+      - 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/drizzle/ARCHITECTURE.md

@@ -0,0 +1,227 @@
+# Architecture
+
+**English** | [Português](ARCHITECTURE.pt-BR.md)
+
+This document explains how NestForge with Drizzle ORM is organized and why certain design decisions were made.
+
+## Overview
+
+```text
+Request → main.ts (global pipes, filters, and interceptors)
+  → Authentication and authorization guards
+  → Controller (receives a DTO and delegates)
+  → Service (business rules)
+  → DrizzleDatabase
+  → PostgreSQL, MySQL, or SQLite
+  → ClassSerializerInterceptor
+  → Response
+```
+
+Controllers do not access the database directly. Every operation goes through a service, keeping business rules centralized and testable.
+
+## Module structure
+
+A domain module normally follows this structure:
+
+```text
+<module>/
+├── dto/                    # Zod schemas and DTOs
+├── entities/               # response and serialization classes, when required
+├── <module>.controller.ts  # receives the request and calls the service
+├── <module>.service.ts     # business rules and Drizzle queries
+├── <module>.service.spec.ts
+└── <module>.module.ts      # controllers, providers, and exports
+```
+
+Tables are not located inside each module. They are defined in:
+
+```text
+src/database/schema/
+├── postgres.schema.ts
+├── mysql.schema.ts
+├── sqlite.schema.ts
+└── index.ts
+```
+
+During generation, the CLI keeps only the schema for the selected database.
+
+## Database connection
+
+The global connection is created by `DatabaseModule`.
+
+It provides two tokens:
+
+* `DATABASE_CLIENT`: the native database client;
+* `DRIZZLE_DATABASE`: the typed Drizzle instance.
+
+Services receive the database with:
+
+```ts
+constructor(
+  @InjectDatabase()
+  private readonly database: DrizzleDatabase,
+) {}
+```
+
+The `@InjectDatabase()` decorator centralizes the injection token and prevents domain modules from knowing details about how the connection is created.
+
+The native client is used only when the driver-specific API is required, such as in the health check and application shutdown.
+
+## Schemas by dialect
+
+PostgreSQL, MySQL, and SQLite differ in types, defaults, UUIDs, dates, and upsert commands.
+
+For this reason, the template keeps three schemas:
+
+* `postgres.schema.ts`, using `drizzle-orm/pg-core`;
+* `mysql.schema.ts`, using `drizzle-orm/mysql-core`;
+* `sqlite.schema.ts`, using `drizzle-orm/sqlite-core`.
+
+CLI markers remove schemas and imports for unselected databases. The generated project ends up with only one dialect and one driver.
+
+## Design decisions
+
+### Why Zod instead of class-validator?
+
+With Zod, the schema is the primary source for validation and documentation.
+
+`nestjs-zod` transforms schemas into DTOs, while `patchNestJsSwagger()` allows Swagger to interpret these schemas.
+
+This reduces duplication between validation and documentation decorators.
+
+### Why use Drizzle directly in services?
+
+Drizzle's query builder already provides typed queries that remain close to SQL.
+
+Creating an additional generic layer for every operation would add indirection without an immediate benefit for the starter.
+
+A custom persistence layer can still be created when the domain requires multiple data sources or complex access rules.
+
+In unit tests, the Drizzle instance is replaced with objects containing `vi.fn()`, without initializing a real database.
+
+### Why use versioned migrations?
+
+Schema changes must be recorded in SQL migrations so they can be reviewed and applied predictably.
+
+The main commands are:
+
+```bash
+npm run drizzle:generate
+npm run drizzle:migrate
+```
+
+The first compares the schemas with existing snapshots and generates files in `drizzle/`. The second applies pending migrations to the configured database.
+
+For rapid development, the following is also available:
+
+```bash
+npm run drizzle:push
+```
+
+`push` is useful for prototypes, but versioned migrations are preferable in shared projects and production.
+
+### Why are SQLite transactions different?
+
+PostgreSQL and MySQL use asynchronous drivers. Their transactions receive asynchronous callbacks and queries executed with `await`.
+
+`better-sqlite3` is synchronous. With this driver, the transaction callback cannot return a `Promise`, and operations are executed with methods such as `.run()`.
+
+The template uses database markers to generate the correct implementation for each driver.
+
+### Why are permissions a map in code?
+
+The `ROLE_PERMISSIONS` map is suitable for projects with a few fixed roles and makes permissions easy to audit.
+
+If the project needs dynamic roles, the map can be replaced with tables such as `roles`, `permissions`, and `role_permissions`.
+
+### Why BullMQ for email delivery?
+
+SMTP is an external operation that can fail or take time.
+
+Putting delivery in a queue allows the request to respond after the work is queued, while the worker processes delivery and subsequent retries.
+
+### Why store refresh token hashes?
+
+A JWT cannot be revoked before it expires. Storing its hash enables:
+
+* logout;
+* refresh token rotation;
+* invalidation after a password change;
+* prevention of revoked token reuse.
+
+The original token is not persisted. Each refresh token also receives a unique `jti` to prevent collisions when two tokens are issued in the same second.
+
+### Why does `UserEntity` still exist?
+
+In the Drizzle template, `UserEntity` is not a database entity.
+
+It is a response class used by `ClassSerializerInterceptor`. The `@Exclude()` decorator prevents `passwordHash` from being sent by the API.
+
+Tables and persistence types are located in the Drizzle schemas.
+
+### Why does Session/Cookies use persistent storage?
+
+The Session/Cookies strategy uses `express-session` with `DrizzleSessionStore`.
+
+Sessions are stored in the `sessions` table instead of process memory. This allows the application to restart or scale without losing all active sessions.
+
+The store implements reading, writing, updating, removal, and expiration using the selected database.
+
+### How does CSRF protection work?
+
+With Session/Cookies, the application uses a CSRF token associated with the session.
+
+Requests that change state must send it through the header:
+
+```http
+x-csrf-token: <token>
+```
+
+The middleware compares the received value with the token stored in the session.
+
+With JWT and a Bearer token, the browser does not automatically send the credential in a cookie. Therefore, this CSRF flow is not required.
+
+## Authentication strategies
+
+### JWT
+
+1. Registration or login validates the user.
+2. `TokenService` issues access and refresh tokens.
+3. The refresh token hash is stored in the database.
+4. `JwtAuthGuard` validates the Bearer token.
+5. Refresh revokes the previous token and issues a new pair.
+6. Logout revokes the refresh token.
+
+### Session/Cookies
+
+1. Registration or login validates the user.
+2. The session is regenerated to prevent session fixation.
+3. The user and CSRF token are stored in the session.
+4. The browser receives the `nestforge.sid` cookie.
+5. `SessionAuthGuard` protects the routes.
+6. Logout destroys the session.
+
+### OAuth
+
+Google and GitHub are linked through the `oauth_accounts` table.
+
+If the email has not been registered yet, a user is created and associated with the provider. The callback result follows the selected strategy: JWT tokens or a persistent session.
+
+## Main tables
+
+The schemas may include:
+
+* `users`;
+* `oauth_accounts`;
+* `refresh_tokens`, when token authentication is enabled;
+* `sessions`, when Session/Cookies is enabled;
+* `password_reset_tokens`, when password recovery is enabled;
+* `email_verification_tokens`, when email verification is enabled.
+
+Conditional tables use markers so that only the selected features remain in the generated project.
+
+## Where to add a module
+
+To add a new domain according to the template conventions, see [Adding a Module](docs/adding-a-module.md).
+
+---

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

@@ -0,0 +1,225 @@
+# Arquitetura
+
+[English](ARCHITECTURE.md) | **Português**
+
+Este documento explica como o NestForge com Drizzle ORM está organizado e por que determinadas decisões de design foram tomadas.
+
+## Visão geral
+
+```text
+Request → main.ts (pipes, filters e interceptors globais)
+  → Guards de autenticação e autorização
+  → Controller (recebe DTO e delega)
+  → Service (regra de negócio)
+  → DrizzleDatabase
+  → PostgreSQL, MySQL ou SQLite
+  → ClassSerializerInterceptor
+  → Response
+```
+
+Controllers não acessam o banco diretamente. Toda operação passa por um service, mantendo as regras de negócio centralizadas e testáveis.
+
+## Estrutura dos módulos
+
+Um módulo de domínio normalmente segue esta estrutura:
+
+```text
+<modulo>/
+├── dto/                    # schemas Zod e DTOs
+├── entities/               # classes de resposta e serialização, quando necessárias
+├── <modulo>.controller.ts  # recebe a request e chama o service
+├── <modulo>.service.ts     # regras de negócio e consultas Drizzle
+├── <modulo>.service.spec.ts
+└── <modulo>.module.ts      # controllers, providers e exports
+```
+
+As tabelas não ficam dentro de cada módulo. Elas são definidas em:
+
+```text
+src/database/schema/
+├── postgres.schema.ts
+├── mysql.schema.ts
+├── sqlite.schema.ts
+└── index.ts
+```
+
+Durante a geração, a CLI mantém somente o schema correspondente ao banco escolhido.
+
+## Conexão com o banco
+
+A conexão global é criada pelo `DatabaseModule`.
+
+Ele fornece dois tokens:
+
+* `DATABASE_CLIENT`: cliente nativo do banco;
+* `DRIZZLE_DATABASE`: instância tipada do Drizzle.
+
+Os services recebem o banco com:
+
+```ts
+constructor(
+  @InjectDatabase()
+  private readonly database: DrizzleDatabase,
+) {}
+```
+
+O decorator `@InjectDatabase()` centraliza o token de injeção e evita que os módulos de domínio conheçam detalhes da criação da conexão.
+
+O cliente nativo é usado apenas quando a API específica do driver é necessária, como no health check e no encerramento da aplicação.
+
+## Schemas por dialect
+
+PostgreSQL, MySQL e SQLite possuem diferenças em tipos, defaults, UUIDs, datas e comandos de upsert.
+
+Por isso o template mantém três schemas:
+
+* `postgres.schema.ts`, usando `drizzle-orm/pg-core`;
+* `mysql.schema.ts`, usando `drizzle-orm/mysql-core`;
+* `sqlite.schema.ts`, usando `drizzle-orm/sqlite-core`.
+
+Os marcadores da CLI removem os schemas e imports dos bancos não selecionados. O projeto gerado termina com apenas um dialect e um driver.
+
+## Decisões de design
+
+### Por que Zod em vez de class-validator?
+
+Com Zod, o schema é a fonte principal para validação e documentação.
+
+O `nestjs-zod` transforma schemas em DTOs, enquanto `patchNestJsSwagger()` permite que o Swagger interprete esses schemas.
+
+Isso reduz a duplicação entre decorators de validação e documentação.
+
+### Por que usar o Drizzle diretamente nos services?
+
+O query builder do Drizzle já oferece consultas tipadas e próximas do SQL.
+
+Criar uma camada genérica adicional para todas as operações aumentaria a indireção sem trazer benefício imediato para o boilerplate.
+
+Uma camada de persistência própria ainda pode ser criada quando o domínio exigir múltiplas fontes de dados ou regras complexas de acesso.
+
+Nos testes unitários, a instância do Drizzle é substituída por objetos com `vi.fn()`, sem inicializar um banco real.
+
+### Por que usar migrations versionadas?
+
+Alterações no schema devem ser registradas em migrations SQL para que possam ser revisadas e aplicadas de maneira previsível.
+
+Os comandos principais são:
+
+```bash
+npm run drizzle:generate
+npm run drizzle:migrate
+```
+
+O primeiro compara os schemas com os snapshots existentes e gera arquivos em `drizzle/`. O segundo aplica as migrations pendentes no banco configurado.
+
+Para desenvolvimento rápido também existe:
+
+```bash
+npm run drizzle:push
+```
+
+O uso de `push` é útil em protótipos, mas migrations versionadas são preferíveis em projetos compartilhados e produção.
+
+### Por que as transações SQLite são diferentes?
+
+PostgreSQL e MySQL usam drivers assíncronos. Suas transações recebem callbacks assíncronos e consultas executadas com `await`.
+
+O `better-sqlite3` é síncrono. Nesse driver, a callback da transação não pode retornar uma `Promise`, e as operações são executadas com métodos como `.run()`.
+
+O template usa marcadores de banco para gerar a implementação correta para cada driver.
+
+### Por que permissions são um mapa em código?
+
+O mapa `ROLE_PERMISSIONS` atende projetos com poucas roles fixas e deixa as permissões fáceis de auditar.
+
+Se o projeto precisar de roles dinâmicas, o mapa pode ser substituído por tabelas como `roles`, `permissions` e `role_permissions`.
+
+### Por que BullMQ para envio de e-mails?
+
+SMTP é uma operação externa que pode falhar ou demorar.
+
+Colocar o envio em uma fila permite responder à requisição depois de enfileirar o trabalho, enquanto o worker processa o envio e suas tentativas posteriores.
+
+### Por que armazenar o hash dos refresh tokens?
+
+Um JWT não pode ser revogado antes de expirar. Armazenar seu hash permite:
+
+* logout;
+* rotação do refresh token;
+* invalidação após troca de senha;
+* bloqueio da reutilização de tokens revogados.
+
+O token original não é persistido. Cada refresh token também recebe um `jti` único para impedir colisões quando duas emissões acontecem no mesmo segundo.
+
+### Por que `UserEntity` ainda existe?
+
+No template Drizzle, `UserEntity` não é uma entidade de banco.
+
+Ela é uma classe de resposta usada pelo `ClassSerializerInterceptor`. O decorator `@Exclude()` impede que `passwordHash` seja enviado pela API.
+
+As tabelas e os tipos de persistência ficam nos schemas Drizzle.
+
+### Por que Session/Cookies usa armazenamento persistente?
+
+A estratégia Session/Cookies usa `express-session` com o `DrizzleSessionStore`.
+
+As sessões ficam na tabela `sessions`, em vez da memória do processo. Isso permite reiniciar ou escalar a aplicação sem perder todas as sessões ativas.
+
+O store implementa leitura, escrita, atualização, remoção e expiração usando o banco escolhido.
+
+### Como funciona a proteção CSRF?
+
+Na estratégia Session/Cookies, a aplicação usa um token CSRF associado à sessão.
+
+Requisições que alteram estado precisam enviá-lo pelo header:
+
+```http
+x-csrf-token: <token>
+```
+
+O middleware compara o valor recebido com o token armazenado na sessão.
+
+Na estratégia JWT com Bearer token, o navegador não envia automaticamente a credencial em um cookie. Por isso esse fluxo CSRF não é necessário.
+
+## Estratégias de autenticação
+
+### JWT
+
+1. Cadastro ou login valida o usuário.
+2. `TokenService` emite access e refresh tokens.
+3. O hash do refresh token é armazenado no banco.
+4. `JwtAuthGuard` valida o Bearer token.
+5. O refresh revoga o token anterior e emite um novo par.
+6. O logout revoga o refresh token.
+
+### Session/Cookies
+
+1. Cadastro ou login valida o usuário.
+2. A sessão é regenerada para evitar session fixation.
+3. O usuário e o token CSRF são armazenados na sessão.
+4. O navegador recebe o cookie `nestforge.sid`.
+5. `SessionAuthGuard` protege as rotas.
+6. O logout destrói a sessão.
+
+### OAuth
+
+Google e GitHub são vinculados pela tabela `oauth_accounts`.
+
+Se o e-mail ainda não estiver cadastrado, um usuário é criado e associado ao provedor. O resultado do callback segue a estratégia escolhida: tokens JWT ou sessão persistente.
+
+## Principais tabelas
+
+Os schemas podem incluir:
+
+* `users`;
+* `oauth_accounts`;
+* `refresh_tokens`, quando autenticação por token estiver habilitada;
+* `sessions`, quando Session/Cookies estiver habilitada;
+* `password_reset_tokens`, quando recuperação de senha estiver habilitada;
+* `email_verification_tokens`, quando verificação de e-mail estiver habilitada.
+
+Tabelas condicionais usam marcadores para que apenas os recursos selecionados permaneçam no projeto gerado.
+
+## Onde adicionar um módulo
+
+Para adicionar um novo domínio seguindo as convenções do template, consulte [Adding a Module](docs/adding-a-module.md).

package/templates/drizzle/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/drizzle/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/drizzle/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).
+
+---