nestforge-generator 0.1.0

package/templates/prisma/src/users/users.controller.ts

@@ -0,0 +1,165 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Patch,
+  Post,
+  Query,
+  UploadedFile,
+  UseInterceptors,
+} from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+// nestforge:feature:swagger
+import { ApiBearerAuth, ApiConsumes, ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
+// nestforge:feature:swagger:end
+import { UsersService } from './users.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { FindUsersQueryDto } from './dto/find-users-query.dto';
+// nestforge:feature:rbac
+import { Permissions } from '../common/decorators/permissions.decorator';
+import { Permission } from '../common/constants/permissions';
+// nestforge:feature:rbac:end
+import { CurrentUser } from '../common/decorators/current-user.decorator';
+import {
+  AVATAR_MAX_SIZE_BYTES,
+  avatarFileFilter,
+  avatarStorage,
+} from '../common/utils/avatar-storage.util';
+
+// nestforge:feature:swagger
+const USER_EXAMPLE = {
+  id: 'a1b2c3d4-e5f6-47a8-9b01-234567890abc',
+  name: 'Jeiel Alves',
+  email: 'jeiel@example.com',
+  role: 'USER',
+  avatarUrl: null,
+  emailVerifiedAt: '2026-01-15T12:00:00.000Z',
+  createdAt: '2026-01-10T09:30:00.000Z',
+  updatedAt: '2026-01-15T12:00:00.000Z',
+};
+
+const FORBIDDEN_EXAMPLE = { statusCode: 403, message: 'Forbidden resource' };
+// nestforge:feature:swagger:end
+
+// nestforge:feature:swagger
+@ApiTags('users')
+@ApiBearerAuth()
+// nestforge:feature:swagger:end
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) { }
+
+  @Post()
+  // nestforge:feature:rbac
+  @Permissions(Permission.UserCreate)
+  // nestforge:feature:rbac:end
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Cria um usuário (requer permissão user:create)' })
+  @ApiResponse({ status: 201, description: 'Usuário criado', schema: { example: USER_EXAMPLE } })
+  @ApiResponse({ status: 403, description: 'Sem a permissão user:create', schema: { example: FORBIDDEN_EXAMPLE } })
+  // nestforge:feature:swagger:end
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+
+  @Get()
+  // nestforge:feature:rbac
+  @Permissions(Permission.UserRead)
+  // nestforge:feature:rbac:end
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Lista usuários com paginação e filtros (requer permissão user:read)' })
+  @ApiResponse({
+    status: 200,
+    description: 'Lista paginada',
+    schema: {
+      example: {
+        data: [USER_EXAMPLE],
+        meta: { total: 1, page: 1, limit: 10, totalPages: 1 },
+      },
+    },
+  })
+  // nestforge:feature:swagger:end
+  findAll(@Query() query: FindUsersQueryDto) {
+    return this.usersService.findAll(query);
+  }
+
+  @Get('me')
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Retorna o usuário autenticado' })
+  @ApiResponse({ status: 200, description: 'Usuário autenticado', schema: { example: USER_EXAMPLE } })
+  // nestforge:feature:swagger:end
+  findMe(@CurrentUser() user: { id: string }) {
+    return this.usersService.findOne(user.id);
+  }
+
+  @Post('me/avatar')
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Faz upload do avatar do usuário autenticado' })
+  @ApiConsumes('multipart/form-data')
+  @ApiResponse({
+    status: 201,
+    description: 'Avatar atualizado',
+    schema: { example: { ...USER_EXAMPLE, avatarUrl: '/uploads/avatars/f47ac10b.png' } },
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Formato de imagem não suportado ou arquivo maior que 2MB',
+    schema: { example: { statusCode: 400, message: 'Formato de imagem não suportado (use PNG, JPEG ou WEBP)' } },
+  })
+  // nestforge:feature:swagger:end
+  @UseInterceptors(
+    FileInterceptor('file', {
+      storage: avatarStorage,
+      fileFilter: avatarFileFilter,
+      limits: { fileSize: AVATAR_MAX_SIZE_BYTES },
+    }),
+  )
+  uploadAvatar(
+    @CurrentUser() user: { id: string },
+    @UploadedFile() file: Express.Multer.File,
+  ) {
+    return this.usersService.updateAvatar(user.id, `/uploads/avatars/${file.filename}`);
+  }
+
+  @Get(':id')
+  // nestforge:feature:rbac
+  @Permissions(Permission.UserRead)
+  // nestforge:feature:rbac:end
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Busca um usuário por id (requer permissão user:read)' })
+  @ApiResponse({ status: 200, description: 'Usuário encontrado', schema: { example: USER_EXAMPLE } })
+  @ApiResponse({ status: 404, description: 'Usuário não encontrado', schema: { example: { statusCode: 404, message: 'Usuário não encontrado' } } })
+  // nestforge:feature:swagger:end
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(id);
+  }
+
+  @Patch(':id')
+  // nestforge:feature:rbac
+  @Permissions(Permission.UserUpdate)
+  // nestforge:feature:rbac:end
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Atualiza um usuário (requer permissão user:update)' })
+  @ApiResponse({ status: 200, description: 'Usuário atualizado', schema: { example: USER_EXAMPLE } })
+  @ApiResponse({ status: 403, description: 'Sem a permissão user:update', schema: { example: FORBIDDEN_EXAMPLE } })
+  // nestforge:feature:swagger:end
+  update(@Param('id') id: string, @Body() dto: UpdateUserDto) {
+    return this.usersService.update(id, dto);
+  }
+
+  @Delete(':id')
+  // nestforge:feature:rbac
+  @Permissions(Permission.UserDelete)
+  // nestforge:feature:rbac:end
+  // nestforge:feature:swagger
+  @ApiOperation({ summary: 'Remove um usuário (requer permissão user:delete)' })
+  @ApiResponse({ status: 200, description: 'Usuário removido', schema: { example: { message: 'Usuário removido com sucesso' } } })
+  @ApiResponse({ status: 403, description: 'Sem a permissão user:delete', schema: { example: FORBIDDEN_EXAMPLE } })
+  // nestforge:feature:swagger:end
+  remove(@Param('id') id: string) {
+    return this.usersService.remove(id);
+  }
+}

package/templates/prisma/src/users/users.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { UsersService } from './users.service';
+import { UsersController } from './users.controller';
+
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}

package/templates/prisma/src/users/users.service.spec.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { ConflictException, NotFoundException } from '@nestjs/common';
+import { instanceToPlain } from 'class-transformer';
+import { Role } from '@prisma/client';
+import { UsersService } from './users.service';
+import { PrismaService } from '../database/prisma.service';
+
+describe('UsersService', () => {
+    let usersService: UsersService;
+    let prisma: any;
+
+    const mockUser = {
+        id: 'user-1',
+        name: 'Jeiel',
+        email: 'jeiel@example.com',
+        passwordHash: 'hash-secreto',
+        role: Role.USER,
+        avatarUrl: null,
+        emailVerifiedAt: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+    };
+
+    beforeEach(() => {
+        prisma = {
+            user: {
+                findUnique: vi.fn(),
+                findMany: vi.fn(),
+                count: vi.fn(),
+                create: vi.fn(),
+                update: vi.fn(),
+                delete: vi.fn(),
+            },
+            $transaction: vi.fn((operations) => Promise.all(operations)),
+        };
+
+        usersService = new UsersService(prisma as PrismaService);
+    });
+
+    it('deve lançar ConflictException se o e-mail já existir ao criar', async () => {
+        prisma.user.findUnique.mockResolvedValue(mockUser);
+
+        await expect(
+            usersService.create({ name: 'Jeiel', email: 'jeiel@example.com', password: 'senhaForte123' }),
+        ).rejects.toBeInstanceOf(ConflictException);
+    });
+
+    it('deve criar um usuário e esconder o passwordHash na serialização', async () => {
+        prisma.user.findUnique.mockResolvedValue(null);
+        prisma.user.create.mockResolvedValue(mockUser);
+
+        const result = await usersService.create({
+            name: 'Jeiel',
+            email: 'jeiel@example.com',
+            password: 'senhaForte123',
+        });
+
+        expect(result.email).toBe('jeiel@example.com');
+        expect(instanceToPlain(result)).not.toHaveProperty('passwordHash');
+    });
+
+    it('deve lançar NotFoundException se o usuário não existir', async () => {
+        prisma.user.findUnique.mockResolvedValue(null);
+
+        await expect(usersService.findOne('id-invalido')).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('deve retornar dados paginados em findAll', async () => {
+        prisma.user.findMany.mockResolvedValue([mockUser]);
+        prisma.user.count.mockResolvedValue(1);
+
+        const result = await usersService.findAll({ page: 1, limit: 10 });
+
+        expect(result.meta).toEqual({ total: 1, page: 1, limit: 10, totalPages: 1 });
+        expect(result.data).toHaveLength(1);
+    });
+
+    it('deve atualizar um usuário existente', async () => {
+        prisma.user.findUnique.mockResolvedValue(mockUser);
+        prisma.user.update.mockResolvedValue({ ...mockUser, name: 'Novo Nome' });
+
+        const result = await usersService.update('user-1', { name: 'Novo Nome' });
+
+        expect(result.name).toBe('Novo Nome');
+    });
+
+    it('deve remover um usuário existente', async () => {
+        prisma.user.findUnique.mockResolvedValue(mockUser);
+        prisma.user.delete.mockResolvedValue(mockUser);
+
+        const result = await usersService.remove('user-1');
+
+        expect(result).toEqual({ message: 'Usuário removido com sucesso' });
+    });
+
+    it('deve atualizar o avatar de um usuário', async () => {
+        prisma.user.findUnique.mockResolvedValue(mockUser);
+        prisma.user.update.mockResolvedValue({ ...mockUser, avatarUrl: '/uploads/avatars/x.png' });
+
+        const result = await usersService.updateAvatar('user-1', '/uploads/avatars/x.png');
+
+        expect(result.avatarUrl).toBe('/uploads/avatars/x.png');
+    });
+});

package/templates/prisma/src/users/users.service.ts

@@ -0,0 +1,114 @@
+import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import * as bcrypt from 'bcryptjs';
+import { PrismaService } from '../database/prisma.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { FindUsersQueryDto } from './dto/find-users-query.dto';
+import { UserEntity } from './entities/user.entity';
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly prisma: PrismaService) { }
+
+  async create(dto: CreateUserDto) {
+    const existing = await this.prisma.user.findUnique({ where: { email: dto.email } });
+    if (existing) {
+      throw new ConflictException('E-mail já cadastrado');
+    }
+
+    const passwordHash = await bcrypt.hash(dto.password, 10);
+
+    const user = await this.prisma.user.create({
+      data: { name: dto.name, email: dto.email, passwordHash, role: dto.role },
+    });
+
+    return new UserEntity(user);
+  }
+
+  async findAll(query: FindUsersQueryDto) {
+    const { page = 1, limit = 10, search, role } = query;
+
+    const where: Prisma.UserWhereInput = {
+      ...(role ? { role } : {}),
+      ...(search
+        ? {
+          OR: [
+            {
+              name: {
+                contains: search,
+                // nestforge:feature:database:postgres
+                mode: Prisma.QueryMode.insensitive,
+                // nestforge:feature:database:postgres:end
+              },
+            },
+            {
+              email: {
+                contains: search,
+                // nestforge:feature:database:postgres
+                mode: Prisma.QueryMode.insensitive,
+                // nestforge:feature:database:postgres:end
+              },
+            },
+          ],
+        }
+        : {}),
+    };
+
+    const [users, total] = await this.prisma.$transaction([
+      this.prisma.user.findMany({
+        where,
+        orderBy: { createdAt: 'desc' },
+        skip: (page - 1) * limit,
+        take: limit,
+      }),
+      this.prisma.user.count({ where }),
+    ]);
+
+    return {
+      data: users.map((user) => new UserEntity(user)),
+      meta: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  async findOne(id: string) {
+    const user = await this.prisma.user.findUnique({ where: { id } });
+    if (!user) {
+      throw new NotFoundException('Usuário não encontrado');
+    }
+    return new UserEntity(user);
+  }
+
+  async update(id: string, dto: UpdateUserDto) {
+    await this.findOne(id);
+
+    const data: Record<string, unknown> = { ...dto };
+    if (dto.password) {
+      data.passwordHash = await bcrypt.hash(dto.password, 10);
+      delete data.password;
+    }
+
+    const user = await this.prisma.user.update({ where: { id }, data });
+    return new UserEntity(user);
+  }
+
+  async remove(id: string) {
+    await this.findOne(id);
+    await this.prisma.user.delete({ where: { id } });
+    return { message: 'Usuário removido com sucesso' };
+  }
+
+  async updateAvatar(id: string, avatarUrl: string) {
+    await this.findOne(id);
+    const user = await this.prisma.user.update({
+      where: { id },
+      data: { avatarUrl },
+    });
+    return new UserEntity(user);
+  }
+}

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

@@ -0,0 +1,75 @@
+// nestforge:feature-file:auth:password,auth:token
+import { INestApplication } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+import request from 'supertest';
+import { createTestApp } from './utils/e2e-setup';
+import { cleanDatabase } from './utils/clean-database';
+
+describe('Auth (e2e)', () => {
+    let app: INestApplication;
+    let prisma: PrismaClient;
+
+    beforeAll(async () => {
+        app = await createTestApp();
+        prisma = new PrismaClient();
+    });
+
+    beforeEach(async () => {
+        await cleanDatabase(prisma);
+    });
+
+    afterAll(async () => {
+        await prisma.$disconnect();
+        await app.close();
+    });
+
+    it('deve registrar, logar, renovar e revogar o token', async () => {
+        const server = app.getHttpServer();
+
+        const registerResponse = await request(server)
+            .post('/auth/register')
+            .send({ name: 'Jeiel', email: 'jeiel.e2e@example.com', password: 'senhaForte123' })
+            .expect(201);
+
+        expect(registerResponse.body).toHaveProperty('accessToken');
+        expect(registerResponse.body).toHaveProperty('refreshToken');
+
+        const loginResponse = await request(server)
+            .post('/auth/login')
+            .send({ email: 'jeiel.e2e@example.com', password: 'senhaForte123' })
+            .expect(200);
+
+        const refreshResponse = await request(server)
+            .post('/auth/refresh')
+            .send({ refreshToken: loginResponse.body.refreshToken })
+            .expect(200);
+
+        expect(refreshResponse.body).toHaveProperty('accessToken');
+
+        await request(server)
+            .post('/auth/logout')
+            .send({ refreshToken: refreshResponse.body.refreshToken })
+            .expect(200);
+
+        // o refresh token já foi revogado no logout, então não pode ser reutilizado
+        await request(server)
+            .post('/auth/refresh')
+            .send({ refreshToken: refreshResponse.body.refreshToken })
+            .expect(401);
+    });
+
+    it('não deve permitir cadastro com e-mail duplicado', async () => {
+        const server = app.getHttpServer();
+        const payload = { name: 'Jeiel', email: 'duplicado.e2e@example.com', password: 'senhaForte123' };
+
+        await request(server).post('/auth/register').send(payload).expect(201);
+        await request(server).post('/auth/register').send(payload).expect(409);
+    });
+
+    it('deve rejeitar login com credenciais inválidas', async () => {
+        await request(app.getHttpServer())
+            .post('/auth/login')
+            .send({ email: 'naoexiste.e2e@example.com', password: 'qualquerSenha123' })
+            .expect(401);
+    });
+});

package/templates/prisma/test/session-auth.e2e-spec.ts

@@ -0,0 +1,163 @@
+// nestforge:feature-file:auth:password,auth:session
+import { INestApplication } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+import request from 'supertest';
+import { createTestApp } from './utils/e2e-setup';
+import { cleanDatabase } from './utils/clean-database';
+
+describe('Session auth (e2e)', () => {
+    let app: INestApplication;
+    let prisma: PrismaClient;
+
+    beforeAll(async () => {
+        app = await createTestApp();
+        prisma = new PrismaClient();
+    });
+
+    beforeEach(async () => {
+        await cleanDatabase(prisma);
+    });
+
+    afterAll(async () => {
+        if (prisma) {
+            await prisma.$disconnect();
+        }
+
+        if (app) {
+            await app.close();
+        }
+    })
+
+    it('registra, autentica e encerra uma sessão protegida por CSRF', async () => {
+        const agent = request.agent(app.getHttpServer());
+
+        await agent
+            .get('/users/me')
+            .expect(401);
+
+        const csrfResponse = await agent
+            .get('/auth/csrf-token')
+            .expect(200);
+
+        const csrfToken = csrfResponse.body.csrfToken as string;
+
+        expect(csrfToken).toMatch(/^[a-f0-9]{64}$/);
+
+        // Requisições que alteram estado devem ser rejeitadas sem o token.
+        await agent
+            .post('/auth/register')
+            .send({
+                name: 'Jeiel',
+                email: 'jeiel.session@example.com',
+                password: 'senhaForte123',
+            })
+            .expect(403);
+
+        const registerResponse = await agent
+            .post('/auth/register')
+            .set('x-csrf-token', csrfToken)
+            .send({
+                name: 'Jeiel',
+                email: 'jeiel.session@example.com',
+                password: 'senhaForte123',
+            })
+            .expect(201);
+
+        expect(registerResponse.body.user).toMatchObject({
+            email: 'jeiel.session@example.com',
+        });
+
+        expect(registerResponse.headers['set-cookie']).toEqual(
+            expect.arrayContaining([
+                expect.stringContaining('nestforge.sid='),
+            ]),
+        );
+
+        const authenticatedCsrfToken =
+            registerResponse.body.csrfToken as string;
+
+        expect(authenticatedCsrfToken).toMatch(/^[a-f0-9]{64}$/);
+        expect(authenticatedCsrfToken).not.toBe(csrfToken);
+
+        const authenticatedResponse = await agent
+            .get('/users/me')
+            .expect(200);
+
+        expect(authenticatedResponse.body.email).toBe(
+            'jeiel.session@example.com',
+        );
+
+        await agent
+            .post('/auth/logout')
+            .set('x-csrf-token', authenticatedCsrfToken)
+            .expect(200);
+
+        await agent
+            .get('/users/me')
+            .expect(401);
+    });
+
+    it('realiza login e renova o token CSRF da sessão', async () => {
+        const registrationAgent = request.agent(
+            app.getHttpServer(),
+        );
+
+        const registrationCsrfResponse = await registrationAgent
+            .get('/auth/csrf-token')
+            .expect(200);
+
+        const registrationCsrfToken =
+            registrationCsrfResponse.body.csrfToken as string;
+
+        const registrationResponse = await registrationAgent
+            .post('/auth/register')
+            .set('x-csrf-token', registrationCsrfToken)
+            .send({
+                name: 'Usuário de sessão',
+                email: 'login.session@example.com',
+                password: 'senhaForte123',
+            })
+            .expect(201);
+
+        await registrationAgent
+            .post('/auth/logout')
+            .set(
+                'x-csrf-token',
+                registrationResponse.body.csrfToken,
+            )
+            .expect(200);
+
+        const loginAgent = request.agent(app.getHttpServer());
+
+        const loginCsrfResponse = await loginAgent
+            .get('/auth/csrf-token')
+            .expect(200);
+
+        const loginCsrfToken =
+            loginCsrfResponse.body.csrfToken as string;
+
+        const loginResponse = await loginAgent
+            .post('/auth/login')
+            .set('x-csrf-token', loginCsrfToken)
+            .send({
+                email: 'login.session@example.com',
+                password: 'senhaForte123',
+            })
+            .expect(200);
+
+        expect(loginResponse.body.user.email).toBe(
+            'login.session@example.com',
+        );
+
+        expect(loginResponse.body.csrfToken).toMatch(
+            /^[a-f0-9]{64}$/,
+        );
+        expect(loginResponse.body.csrfToken).not.toBe(
+            loginCsrfToken,
+        );
+
+        await loginAgent
+            .get('/users/me')
+            .expect(200);
+    });
+});