nestforge-generator 0.1.0

package/templates/prisma/test/users.e2e-spec.ts

@@ -0,0 +1,106 @@
+// nestforge:feature-file:auth:password,auth:token
+import { INestApplication } from '@nestjs/common';
+import { PrismaClient, Role } from '@prisma/client';
+import * as bcrypt from 'bcryptjs';
+import request from 'supertest';
+import { createTestApp } from './utils/e2e-setup';
+import { cleanDatabase } from './utils/clean-database';
+
+describe('Users (e2e)', () => {
+    let app: INestApplication;
+    let prisma: PrismaClient;
+
+    async function createUserWithRole(email: string, password: string, role: Role) {
+        const passwordHash = await bcrypt.hash(password, 10);
+        await prisma.user.create({
+            data: { name: 'Usuário de teste', email, passwordHash, role, emailVerifiedAt: new Date() },
+        });
+    }
+
+    async function loginAndGetToken(email: string, password: string) {
+        const response = await request(app.getHttpServer())
+            .post('/auth/login')
+            .send({ email, password })
+            .expect(200);
+        return response.body.accessToken as string;
+    }
+
+    beforeAll(async () => {
+        app = await createTestApp();
+        prisma = new PrismaClient();
+    });
+
+    beforeEach(async () => {
+        await cleanDatabase(prisma);
+    });
+
+    afterAll(async () => {
+        await prisma.$disconnect();
+        await app.close();
+    });
+
+    it('rejeita acesso sem token', async () => {
+        await request(app.getHttpServer()).get('/users').expect(401);
+    });
+
+    it('ADMIN consegue criar, listar, atualizar e remover um usuário', async () => {
+        await createUserWithRole('admin.e2e@example.com', 'senhaForte123', Role.ADMIN);
+        const token = await loginAndGetToken('admin.e2e@example.com', 'senhaForte123');
+        const server = app.getHttpServer();
+
+        const createResponse = await request(server)
+            .post('/users')
+            .set('Authorization', `Bearer ${token}`)
+            .send({ name: 'Novo Usuário', email: 'novo.e2e@example.com', password: 'senhaForte123' })
+            .expect(201);
+
+        expect(createResponse.body).not.toHaveProperty('passwordHash');
+        const userId = createResponse.body.id;
+
+        const listResponse = await request(server)
+            .get('/users')
+            .set('Authorization', `Bearer ${token}`)
+            .expect(200);
+
+        expect(listResponse.body.meta.total).toBeGreaterThanOrEqual(1);
+
+        await request(server)
+            .patch(`/users/${userId}`)
+            .set('Authorization', `Bearer ${token}`)
+            .send({ name: 'Nome Atualizado' })
+            .expect(200);
+
+        await request(server)
+            .delete(`/users/${userId}`)
+            .set('Authorization', `Bearer ${token}`)
+            .expect(200);
+    });
+
+    // nestforge:feature:rbac
+    it('USER consegue ler mas não consegue criar usuário', async () => {
+        await createUserWithRole('user.e2e@example.com', 'senhaForte123', Role.USER);
+        const token = await loginAndGetToken('user.e2e@example.com', 'senhaForte123');
+        const server = app.getHttpServer();
+
+        await request(server).get('/users').set('Authorization', `Bearer ${token}`).expect(200);
+
+        await request(server)
+            .post('/users')
+            .set('Authorization', `Bearer ${token}`)
+            .send({ name: 'Não deveria criar', email: 'bloqueado.e2e@example.com', password: 'senhaForte123' })
+            .expect(403);
+    });
+    // nestforge:feature:rbac:end
+
+    it('GET /users/me retorna o usuário autenticado', async () => {
+        await createUserWithRole('me.e2e@example.com', 'senhaForte123', Role.USER);
+        const token = await loginAndGetToken('me.e2e@example.com', 'senhaForte123');
+
+        const response = await request(app.getHttpServer())
+            .get('/users/me')
+            .set('Authorization', `Bearer ${token}`)
+            .expect(200);
+
+        expect(response.body.email).toBe('me.e2e@example.com');
+    });
+});

package/templates/prisma/test/utils/clean-database.ts

@@ -0,0 +1,14 @@
+import { PrismaClient } from '@prisma/client';
+
+export async function cleanDatabase(prisma: PrismaClient) {
+    await prisma.$transaction([
+        // nestforge:feature:auth:session
+        prisma.session.deleteMany(),
+        // nestforge:feature:auth:session:end
+        prisma.refreshToken.deleteMany(),
+        prisma.passwordResetToken.deleteMany(),
+        prisma.emailVerificationToken.deleteMany(),
+        prisma.oAuthAccount.deleteMany(),
+        prisma.user.deleteMany(),
+    ]);
+}

package/templates/prisma/test/utils/e2e-setup.ts

@@ -0,0 +1,58 @@
+import { ClassSerializerInterceptor, INestApplication } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Test } from '@nestjs/testing';
+import { NestExpressApplication } from '@nestjs/platform-express';
+// nestforge:feature:validation
+import { ZodValidationPipe } from 'nestjs-zod';
+// nestforge:feature:validation:end
+import { AppModule } from '../../src/app.module';
+import { HttpExceptionFilter } from '../../src/common/filters/http-exception.filter';
+// nestforge:feature:auth:session
+import session from 'express-session';
+import { PrismaSessionStore } from '@quixo3/prisma-session-store';
+import { PrismaService } from '../../src/database/prisma.service';
+// nestforge:feature:auth:session:end
+
+export async function createTestApp(): Promise<INestApplication> {
+    const moduleRef = await Test.createTestingModule({
+        imports: [AppModule],
+    }).compile();
+
+    const app = moduleRef.createNestApplication<NestExpressApplication>();
+
+    // nestforge:feature:auth:session
+    const prisma = app.get(PrismaService);
+
+    app.use(
+        session({
+            name: 'nestforge.sid',
+            secret: process.env.SESSION_SECRET as string,
+            resave: false,
+            saveUninitialized: false,
+            store: new PrismaSessionStore(prisma, {
+                checkPeriod: 2 * 60 * 1000,
+                dbRecordIdIsSessionId: true,
+                dbRecordIdFunction: undefined,
+            }),
+            cookie: {
+                httpOnly: true,
+                secure: false,
+                sameSite: 'lax',
+                maxAge: Number(
+                    process.env.SESSION_MAX_AGE ?? 7 * 24 * 60 * 60 * 1000,
+                ),
+            },
+        }),
+    );
+    // nestforge:feature:auth:session:end
+
+    // mesmos pipes/filters/interceptors globais do main.ts, pra testar o comportamento real da API
+    // nestforge:feature:validation
+    app.useGlobalPipes(new ZodValidationPipe());
+    // nestforge:feature:validation:end
+    app.useGlobalFilters(new HttpExceptionFilter());
+    app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
+
+    await app.init();
+    return app;
+}

package/templates/prisma/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
+}

package/templates/prisma/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2022",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/templates/prisma/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+import swc from 'unplugin-swc';
+
+export default defineConfig({
+  plugins: [
+    swc.vite({
+      module: { type: 'es6' },
+    }),
+  ],
+  test: {
+    globals: true,
+    root: './',
+    environment: 'node',
+    include: ['src/**/*.spec.ts'],
+    coverage: {
+      reporter: ['text', 'html'],
+      exclude: ['**/*.module.ts', '**/main.ts'],
+    },
+  },
+});

package/templates/prisma/vitest.e2e.config.ts

@@ -0,0 +1,19 @@
+import swc from 'unplugin-swc';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    plugins: [
+        swc.vite({
+            module: { type: 'es6' },
+        }),
+    ],
+    test: {
+        globals: true,
+        root: './',
+        environment: 'node',
+        include: ['test/**/*.e2e-spec.ts'],
+        testTimeout: 30000,
+        hookTimeout: 30000,
+        fileParallelism: false,
+    },
+});

package/templates/typeorm/.env.example

@@ -0,0 +1,45 @@
+# App
+NODE_ENV=development
+PORT=3000
+APP_URL=http://localhost:3000
+CORS_ORIGINS=http://localhost:5173
+
+# Database
+DB_TYPE=postgres
+DATABASE_URL="postgresql://nestforge:nestforge@localhost:5432/nestforge"
+
+# JWT
+# nestforge:feature:auth:token
+JWT_ACCESS_SECRET=troque-este-segredo-em-producao
+JWT_ACCESS_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=troque-este-outro-segredo-em-producao
+JWT_REFRESH_EXPIRES_IN=7d
+# nestforge:feature:auth:token:end
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# Mail (Mailpit em dev)
+MAIL_HOST=localhost
+MAIL_PORT=1025
+MAIL_FROM="NestForge <no-reply@nestforge.dev>"
+
+# OAuth (opcional)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# Rate limit
+THROTTLE_TTL=60
+THROTTLE_LIMIT=100
+
+# nestforge:feature:auth:session
+# Session
+SESSION_SECRET=troque-este-segredo-de-sessao-em-producao
+SESSION_MAX_AGE=604800000
+
+# CSRF
+ENABLE_CSRF=true
+# nestforge:feature:auth:session:end

package/templates/typeorm/.env.test

@@ -0,0 +1,38 @@
+NODE_ENV=test
+PORT=3000
+APP_URL=http://localhost:3000
+CORS_ORIGINS=http://localhost:5173
+
+# Banco isolado, nunca o de desenvolvimento
+DB_TYPE=postgres
+DATABASE_URL="postgresql://nestforge:nestforge@localhost:5432/nestforge_test"
+
+# 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/typeorm/.github/workflows/ci.yml

@@ -0,0 +1,116 @@
+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: Rodar migrations
+        run: npx typeorm-ts-node-commonjs -d src/database/data-source.ts migration:run
+
+      - 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/typeorm/ARCHITECTURE.md

@@ -0,0 +1,158 @@
+# Architecture
+
+**English** | [Português](ARCHITECTURE.pt-BR.md)
+
+This document explains how NestForge with TypeORM is organized and why certain design decisions were made.
+
+## Overview
+
+```text
+Request → main.ts (global pipes, filters, and interceptors)
+  → Authentication and authorization guards
+  → Controller (validates DTO and delegates)
+  → Service (business rules)
+  → TypeORM Repository
+  → PostgreSQL, MySQL, or SQLite
+  → ClassSerializerInterceptor
+  → Response
+```
+
+Each domain module follows the same structure:
+
+```text
+<module>/
+├── dto/                    # Zod schemas and DTOs
+├── entities/               # entities persisted by TypeORM
+├── <module>.controller.ts  # receives the request and calls the service
+├── <module>.service.ts     # business rules
+├── <module>.service.spec.ts
+└── <module>.module.ts      # dependencies, repositories, and exports
+```
+
+Controllers do not access repositories directly. Every operation goes through the service, keeping business rules centralized and testable.
+
+Modules register their entities with:
+
+TypeOrmModule.forFeature([
+    UserEntity,
+])
+
+Services receive repositories with:
+
+@InjectRepository(UserEntity) private readonly usersRepository: Repository<UserEntity>
+
+The global connection is located in src/database/database.module.ts. PostgreSQL-, MySQL-, and SQLite-specific options are located in src/database/typeorm-options.ts.
+
+## 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 TypeORM repositories directly?
+
+Repository<Entity> already provides a testable, typed persistence abstraction. Creating another generic repository layer on top would add indirection without benefiting this starter.
+
+Unit tests replace repositories with objects containing vi.fn(), without starting a database or the complete Nest application.
+
+An additional layer can be created later if the project requires complex persistence rules or multiple data sources.
+
+### Why is synchronize disabled?
+
+The template uses:
+
+synchronize: false
+
+Database changes must go through versioned migrations. This prevents automatic and potentially destructive schema changes, especially in production.
+
+Migrations are generated and run with:
+
+npm run migration:generate -- src/database/migrations/MigrationName
+npm run migration:run
+
+### 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 dynamically created roles, the map can be replaced with entities such as Role, Permission, and RolePermission.
+
+### 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 MailProcessor handles delivery and subsequent retries.
+
+### Why store refresh token hashes?
+
+A JWT cannot be revoked before it expires. Storing the hash enables:
+
+  - logout;
+  - refresh token rotation;
+  - invalidation after a password change;
+  - prevention of revoked token reuse.
+
+The original token is not persisted.
+
+### Why does UserEntity use @Exclude()?
+
+The repository needs to access passwordHash during operations such as login, but this field must never appear in an HTTP response.
+
+@Exclude() combined with ClassSerializerInterceptor creates a serialization barrier that prevents the hash from leaking.
+
+### Why does Session/Cookies use persistent storage?
+
+The Session/Cookies strategy uses express-session with connect-typeorm. Sessions are stored in the sessions table instead of process memory.
+
+This allows the application to restart or scale without losing all active sessions.
+
+### How does CSRF protection work?
+
+With Session/Cookies, the application uses a CSRF token associated with the session. Requests that change state must send this token through the header:
+
+x-csrf-token
+
+The middleware compares the received token with the token stored in the session.
+
+With JWT and a Bearer token, the browser does not automatically send the credential in a cookie, so 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 OAuthAccountEntity. If the email has not been registered yet, a user is created and associated with the provider.
+
+## Database and entities
+
+The main entities are:
+
+- UserEntity;
+- OAuthAccountEntity;
+- RefreshTokenEntity, when tokens are enabled;
+- SessionEntity, when Session/Cookies is enabled;
+- password recovery and email verification entities, when applicable.
+
+Conditional entities use generator markers so that only the required files and relationships remain in the final project.
+
+## Where to add a module
+
+To add a new domain, see docs/adding-a-module.md (docs/adding-a-module.md).
+
+---