nestforge-generator 0.1.0

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

@@ -0,0 +1,457 @@
+# Marcadores de funcionalidades
+
+O template templates/drizzle funciona como projeto de referência e como fonte usada pela CLI para gerar projetos personalizados.
+
+Os marcadores permitem remover arquivos ou blocos de código conforme as opções selecionadas pelo usuário, como banco de dados, autenticação, Redis, Swagger e RBAC.
+
+## Marcador de bloco
+
+Use um marcador de bloco quando apenas uma parte do arquivo depender de uma funcionalidade.
+
+```ts
+// nestforge:feature:swagger
+@ApiTags('users')
+// nestforge:feature:swagger:end
+@Controller('users')
+export class UsersController {}
+```
+
+Quando swagger estiver habilitado, a CLI mantém o conteúdo e remove somente as linhas dos marcadores.
+
+Quando estiver desabilitado, a CLI remove todo o bloco:
+
+```ts
+@Controller('users')
+export class UsersController {}
+```
+
+O nome da abertura deve ser exatamente igual ao nome do fechamento:
+
+```ts
+// nestforge:feature:swagger
+// conteúdo opcional
+// nestforge:feature:swagger:end
+```
+
+Não deixe um marcador aberto. Um fechamento ausente pode fazer a CLI remover o restante do
+arquivo.
+
+## Marcador de arquivo inteiro
+
+Use um marcador de arquivo quando todo o arquivo depender de uma funcionalidade.
+
+O marcador deve ser a primeira linha não vazia:
+
+```ts
+// nestforge:feature-file:redis
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class MailService {}
+```
+
+Se redis estiver habilitado, somente a linha do marcador será removida.
+
+Se estiver desabilitado, o arquivo inteiro será excluído.
+
+Depois do processamento, a CLI também remove diretórios que ficarem vazios.
+
+## Marcadores com múltiplos requisitos
+
+Um marcador pode exigir mais de uma funcionalidade usando nomes separados por vírgula:
+
+```ts
+// nestforge:feature:redis,auth:password
+await this.mailService.sendPasswordResetEmail();
+// nestforge:feature:redis,auth:password:end
+```
+
+Nesse caso, todas as funcionalidades precisam estar habilitadas.
+
+O bloco acima somente será mantido quando:
+
+* Redis estiver habilitado;
+* a estratégia de autenticação usar senha.
+
+A mesma regra funciona para arquivos inteiros:
+
+```ts
+// nestforge:feature-file:auth:password,auth:session
+```
+
+Não use espaços entre os nomes no marcador. Prefira:
+
+```text
+redis,auth:password
+```
+
+## Prefixos de comentário aceitos
+
+Os marcadores aceitam comentários iniciados por //:
+
+```ts
+// nestforge:feature:swagger
+```
+
+Também aceitam comentários iniciados por #, usados em YAML e arquivos de ambiente:
+
+```yaml
+# nestforge:feature:redis
+redis:
+  image: redis:alpine
+# nestforge:feature:redis:end
+```
+
+Exemplo em .env.example:
+
+```dotenv
+# nestforge:feature:auth:session
+SESSION_SECRET=troque-este-segredo
+SESSION_MAX_AGE=604800000
+# nestforge:feature:auth:session:end
+```
+
+## Funcionalidades disponíveis
+
+### Funcionalidades selecionadas diretamente
+
+| Nome | Origem |
+| ━━━━━━━━━━━━ | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ |
+| docker | Pergunta sobre Docker |
+| ──────────── | ────────────────────────────────────── |
+| swagger | Pergunta sobre Swagger/OpenAPI |
+| ──────────── | ────────────────────────────────────── |
+| validation | Pergunta sobre validação global |
+| ──────────── | ────────────────────────────────────── |
+| redis | Pergunta sobre Redis, filas e e-mail |
+| ──────────── | ────────────────────────────────────── |
+| rbac | Pergunta sobre RBAC e Permissions |
+
+### Banco de dados
+
+A CLI habilita exatamente um marcador de banco:
+
+| Banco selecionado | Marcador |
+| ━━━━━━━━━━━━━━━━━━━ | ━━━━━━━━━━━━━━━━━━━ |
+| PostgreSQL | database:postgres |
+| ─────────────────── | ─────────────────── |
+| MySQL | database:mysql |
+| ─────────────────── | ─────────────────── |
+| SQLite | database:sqlite |
+
+Exemplo de arquivo exclusivo do PostgreSQL:
+
+```ts
+// nestforge:feature-file:database:postgres
+import type { Pool } from 'pg';
+```
+
+Exemplo de implementações diferentes dentro do mesmo arquivo:
+
+```ts
+// nestforge:feature:database:postgres
+await client.query('SELECT 1');
+// nestforge:feature:database:postgres:end
+
+// nestforge:feature:database:mysql
+await client.query('SELECT 1');
+// nestforge:feature:database:mysql:end
+
+// nestforge:feature:database:sqlite
+client.prepare('SELECT 1').get();
+// nestforge:feature:database:sqlite:end
+```
+
+Esses marcadores são importantes no template Drizzle porque cada driver possui tipos, configuração e comportamento de transação diferentes.
+
+### Autenticação
+
+A CLI cria marcadores internos de acordo com a estratégia escolhida:
+
+| Marcador | Quando é habilitado |
+| ━━━━━━━━━━━━━━━ | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ |
+| auth:enabled | JWT, OAuth-only ou Session/Cookies |
+| ─────────────── | ──────────────────────────────────── |
+| auth:password | JWT ou Session/Cookies |
+| ─────────────── | ──────────────────────────────────── |
+| auth:token | JWT ou OAuth-only |
+| ─────────────── | ──────────────────────────────────── |
+| auth:session | Session/Cookies |
+| ─────────────── | ──────────────────────────────────── |
+| auth:jwt | Estratégia JWT selecionada |
+| ─────────────── | ──────────────────────────────────── |
+| auth:oauth | Estratégia OAuth-only selecionada |
+| ─────────────── | ──────────────────────────────────── |
+| auth:none | Nenhuma autenticação selecionada |
+
+Na maior parte do template, devem ser usados os marcadores de capacidade:
+
+* auth:enabled para código compartilhado por qualquer autenticação;
+* auth:password para cadastro, login e senha;
+* auth:token para access token e refresh token;
+* auth:session para sessão persistente e cookies.
+
+Exemplo:
+
+```ts
+// nestforge:feature:auth:token
+import { TokenService } from './token.service';
+// nestforge:feature:auth:token:end
+```
+
+Exemplo de código compartilhado por JWT e Session/Cookies:
+
+```ts
+// nestforge:feature-file:auth:password
+import { LoginDto } from './login.dto';
+```
+
+## Marcadores específicos do Drizzle
+
+### Schemas por banco
+
+Cada schema pertence exclusivamente a um banco:
+
+```ts
+// nestforge:feature-file:database:postgres
+```
+
+```ts
+// nestforge:feature-file:database:mysql
+```
+
+```ts
+// nestforge:feature-file:database:sqlite
+```
+
+Depois da geração, somente o schema correspondente ao banco selecionado deve permanecer no projeto.
+
+O arquivo src/database/schema/index.ts também usa blocos para exportar somente o schema selecionado:
+
+```ts
+// nestforge:feature:database:postgres
+export * from './postgres.schema';
+// nestforge:feature:database:postgres:end
+```
+
+### Transações do SQLite
+
+PostgreSQL e MySQL usam callbacks assíncronos:
+
+```ts
+// nestforge:feature:database:postgres
+await database.transaction(
+  async (transaction) => {
+    await transaction.delete(users);
+  },
+);
+// nestforge:feature:database:postgres:end
+```
+
+SQLite com better-sqlite3 usa callback síncrono e .run():
+
+```ts
+// nestforge:feature:database:sqlite
+database.transaction((transaction) => {
+  transaction.delete(users).run();
+});
+// nestforge:feature:database:sqlite:end
+```
+
+Não coloque essas duas implementações no mesmo bloco, pois apenas uma deve permanecer no projeto gerado.
+
+### Tabelas opcionais
+
+Tabelas usadas somente por uma estratégia de autenticação também precisam de marcadores:
+
+```ts
+// nestforge:feature:auth:token
+export const refreshTokens = sqliteTable(
+  'refresh_tokens',
+  {
+    // colunas
+  },
+);
+// nestforge:feature:auth:token:end
+```
+
+Para Session/Cookies:
+
+```ts
+// nestforge:feature:auth:session
+export const sessions = sqliteTable(
+  'sessions',
+  {
+    // colunas
+  },
+);
+// nestforge:feature:auth:session:end
+```
+
+Os imports, tipos, services, testes e limpeza E2E relacionados à tabela também devem usar marcadores compatíveis.
+
+## Dependências do package.json
+
+JSON não aceita comentários. Portanto, não coloque marcadores dentro de package.json.
+
+A remoção de dependências opcionais é controlada por:
+
+packages/cli/src/features/dependencies.ts
+
+O objeto FEATURE_DEPENDENCIES associa cada funcionalidade às dependências que devem ser removidas quando ela estiver desabilitada.
+
+Exemplo conceitual:
+
+```ts
+export const FEATURE_DEPENDENCIES = {
+  'database:postgres': [
+    'pg',
+    '@types/pg',
+  ],
+  'database:mysql': [
+    'mysql2',
+  ],
+  'database:sqlite': [
+    'better-sqlite3',
+    '@types/better-sqlite3',
+  ],
+};
+```
+
+Ao adicionar uma dependência exclusiva de uma funcionalidade, atualize esse mapeamento.
+
+Dependências compartilhadas pelo template Drizzle, como drizzle-orm e drizzle-kit, não devem ser removidas junto com um driver específico.
+
+## Docker
+
+O Dockerfile e o docker-compose.yml são removidos diretamente pela CLI quando Docker está desabilitado.
+
+Dentro do docker-compose.yml, use marcadores para serviços opcionais:
+
+```yaml
+# nestforge:feature:redis
+redis:
+  image: redis:alpine
+# nestforge:feature:redis:end
+```
+
+Dependências entre serviços também precisam ser marcadas:
+
+```yaml
+depends_on:
+  # nestforge:feature:database:postgres
+  - postgres
+  # nestforge:feature:database:postgres:end
+```
+
+Depois da geração, confira se o YAML continua válido em todas as combinações.
+
+## Cuidados ao usar marcadores
+
+### Preserve imports relacionados
+
+Não marque apenas o uso de uma classe e deixe o import para trás.
+
+Incorreto:
+
+```ts
+import { TokenService } from './token.service';
+
+// nestforge:feature:auth:token
+constructor(
+  private readonly tokenService: TokenService,
+) {}
+// nestforge:feature:auth:token:end
+```
+
+Correto:
+
+```ts
+// nestforge:feature:auth:token
+import { TokenService } from './token.service';
+// nestforge:feature:auth:token:end
+
+// nestforge:feature:auth:token
+constructor(
+  private readonly tokenService: TokenService,
+) {}
+// nestforge:feature:auth:token:end
+```
+
+### Preserve a sintaxe do arquivo
+
+Ao remover um bloco, o código restante precisa continuar válido.
+
+Verifique especialmente:
+
+* vírgulas em arrays e objetos;
+* imports parcialmente removidos;
+* parâmetros de construtores;
+* itens em providers, imports e exports;
+* scripts e propriedades YAML;
+* chaves e parênteses;
+* blocos de transação;
+* exports do schema.
+
+### Evite blocos desnecessariamente grandes
+
+Marque somente o trecho exclusivo da funcionalidade. Blocos menores facilitam a revisão e reduzem o risco de remover código compartilhado.
+
+### Evite aninhar marcadores
+
+Prefira um único marcador com múltiplos requisitos:
+
+```ts
+// nestforge:feature:redis,auth:password
+// conteúdo
+// nestforge:feature:redis,auth:password:end
+```
+
+Isso é mais seguro do que colocar um marcador dentro de outro.
+
+## Como conferir os marcadores
+
+No PowerShell, liste todos os marcadores do template:
+
+```powershell
+Get-ChildItem `
+  .\templates\drizzle `
+  -Recurse `
+  -File |
+  Select-String -Pattern 'nestforge:feature'
+```
+
+Procure marcadores de abertura e fechamento:
+
+```powershell
+Get-ChildItem `
+  .\templates\drizzle `
+  -Recurse `
+  -File |
+  Select-String -Pattern 'nestforge:feature:|nestforge:feature-file:'
+```
+
+A conferência definitiva deve ser feita pelos testes do gerador:
+
+```powershell
+Set-Location .\packages\cli
+npm test
+```
+
+Os testes devem gerar combinações com as funcionalidades habilitadas e desabilitadas.
+
+## Checklist para uma funcionalidade nova
+
+* [ ] Blocos exclusivos possuem marcador de abertura e fechamento
+* [ ] Arquivos exclusivos possuem feature-file na primeira linha não vazia
+* [ ] Os nomes de abertura e fechamento são idênticos
+* [ ] Múltiplos requisitos usam uma lista separada por vírgula
+* [ ] Imports exclusivos também estão marcados
+* [ ] Providers e exports exclusivos também estão marcados
+* [ ] Tabelas e tipos opcionais do schema estão marcados
+* [ ] A limpeza E2E considera tabelas opcionais
+* [ ] Dependências opcionais foram adicionadas a FEATURE_DEPENDENCIES
+* [ ] PostgreSQL, MySQL e SQLite mantêm código válido
+* [ ] O projeto foi gerado com a funcionalidade ligada
+* [ ] O projeto foi gerado com a funcionalidade desligada
+* [ ] O projeto gerado executa build e testes

package/templates/drizzle/drizzle.config.ts

@@ -0,0 +1,49 @@
+import { defineConfig } from 'drizzle-kit';
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+    throw new Error('DATABASE_URL não foi definida');
+}
+
+// nestforge:feature:database:postgres
+export default defineConfig({
+    dialect: 'postgresql',
+    schema:
+        './src/database/schema/postgres.schema.ts',
+    out: './drizzle',
+    dbCredentials: {
+        url: databaseUrl,
+    },
+    verbose: true,
+    strict: true,
+});
+// nestforge:feature:database:postgres:end
+
+// nestforge:feature:database:mysql
+export default defineConfig({
+    dialect: 'mysql',
+    schema:
+        './src/database/schema/mysql.schema.ts',
+    out: './drizzle',
+    dbCredentials: {
+        url: databaseUrl,
+    },
+    verbose: true,
+    strict: true,
+});
+// nestforge:feature:database:mysql:end
+
+// nestforge:feature:database:sqlite
+export default defineConfig({
+    dialect: 'sqlite',
+    schema:
+        './src/database/schema/sqlite.schema.ts',
+    out: './drizzle',
+    dbCredentials: {
+        url: databaseUrl.replace(/^file:/, ''),
+    },
+    verbose: true,
+    strict: true,
+});
+// nestforge:feature:database:sqlite:end

package/templates/drizzle/nest-cli.json

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

package/templates/drizzle/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "nestforge",
+  "version": "0.1.0",
+  "description": "Production-ready NestJS starter with Drizzle ORM, 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",
+    "test:e2e": "dotenv -e .env.test -- vitest run --config ./vitest.e2e.config.ts",
+    "drizzle:generate": "dotenv -e .env -- drizzle-kit generate",
+    "drizzle:migrate": "dotenv -e .env -- drizzle-kit migrate",
+    "drizzle:push": "dotenv -e .env -- drizzle-kit push",
+    "drizzle:studio": "dotenv -e .env -- drizzle-kit studio",
+    "pretest:e2e": "dotenv -e .env.test -- drizzle-kit migrate",
+    "seed": "dotenv -e .env -- ts-node src/database/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",
+    "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",
+    "drizzle-orm": "^0.45.2",
+    "pg": "^8.23.0",
+    "mysql2": "^3.24.2",
+    "better-sqlite3": "^13.0.3"
+  },
+  "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",
+    "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",
+    "drizzle-kit": "^0.31.10",
+    "@types/pg": "^8.23.1",
+    "@types/better-sqlite3": "^9.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/drizzle/src/app.module.ts

@@ -0,0 +1,72 @@
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ThrottlerModule } from '@nestjs/throttler';
+// nestforge:feature:redis
+import { BullModule } from '@nestjs/bullmq';
+// nestforge:feature:redis:end
+import { LoggerModule } from 'nestjs-pino';
+// nestforge:feature:auth:enabled
+import { AuthModule } from './auth/auth.module';
+import { UsersModule } from './users/users.module';
+// nestforge:feature:auth:enabled:end
+import { DatabaseModule } from './database/database.module';
+// nestforge:feature:redis
+import { MailModule } from './mail/mail.module';
+// nestforge:feature:redis:end
+import { HealthModule } from './health/health.module';
+import { MetricsModule } from './metrics/metrics.module';
+// nestforge:feature:auth:session
+import { CsrfMiddleware } from './common/middleware/csrf.middleware';
+// nestforge:feature:auth:session:end
+import { validateEnv } from './config/env.validation';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      validate: validateEnv,
+    }),
+    LoggerModule.forRoot({
+      pinoHttp: {
+        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+        transport:
+          process.env.NODE_ENV === 'development'
+            ? { target: 'pino-pretty', options: { singleLine: true } }
+            : undefined,
+      },
+    }),
+    ThrottlerModule.forRoot([
+      {
+        ttl: Number(process.env.THROTTLE_TTL ?? 60) * 1000,
+        limit: Number(process.env.THROTTLE_LIMIT ?? 100),
+      },
+    ]),
+    // nestforge:feature:redis
+    BullModule.forRoot({
+      connection: {
+        host: process.env.REDIS_HOST ?? 'localhost',
+        port: Number(process.env.REDIS_PORT ?? 6379),
+      },
+    }),
+    // nestforge:feature:redis:end
+    DatabaseModule,
+    // nestforge:feature:auth:enabled
+    AuthModule,
+    UsersModule,
+    // nestforge:feature:auth:enabled:end
+    // nestforge:feature:redis
+    MailModule,
+    // nestforge:feature:redis:end
+    HealthModule,
+    MetricsModule,
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // nestforge:feature:auth:session
+    if (process.env.ENABLE_CSRF === 'true') {
+      consumer.apply(CsrfMiddleware).forRoutes('*');
+    }
+    // nestforge:feature:auth:session:end
+  }
+}