nestforge-generator 0.1.0

package/templates/drizzle/src/mail/mail.service.ts

@@ -0,0 +1,24 @@
+// nestforge:feature-file:redis
+import { Injectable } from '@nestjs/common';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+
+export const MAIL_QUEUE = 'mail';
+
+export enum MailJob {
+    VerifyEmail = 'verify-email',
+    ResetPassword = 'reset-password',
+}
+
+@Injectable()
+export class MailService {
+    constructor(@InjectQueue(MAIL_QUEUE) private readonly mailQueue: Queue) { }
+
+    queueVerificationEmail(to: string, name: string, token: string) {
+        return this.mailQueue.add(MailJob.VerifyEmail, { to, name, token });
+    }
+
+    queuePasswordResetEmail(to: string, name: string, token: string) {
+        return this.mailQueue.add(MailJob.ResetPassword, { to, name, token });
+    }
+}

package/templates/drizzle/src/mail/templates/email-templates.ts

@@ -0,0 +1,28 @@
+// nestforge:feature-file:redis
+const appUrl = process.env.APP_URL ?? 'http://localhost:3000';
+
+export function verifyEmailTemplate(name: string, token: string): string {
+    const link = `${appUrl}/auth/verify-email?token=${token}`;
+
+    return `
+    <div style="font-family: sans-serif; line-height: 1.5;">
+      <h2>Olá, ${name}!</h2>
+      <p>Confirme seu e-mail clicando no link abaixo:</p>
+      <p><a href="${link}">${link}</a></p>
+      <p>Esse link expira em 24 horas.</p>
+    </div>
+  `;
+}
+
+export function resetPasswordTemplate(name: string, token: string): string {
+    const link = `${appUrl}/auth/reset-password?token=${token}`;
+
+    return `
+    <div style="font-family: sans-serif; line-height: 1.5;">
+      <h2>Olá, ${name}!</h2>
+      <p>Recebemos um pedido para redefinir sua senha. Clique no link abaixo para continuar:</p>
+      <p><a href="${link}">${link}</a></p>
+      <p>Se você não pediu isso, pode ignorar este e-mail. O link expira em 1 hora.</p>
+    </div>
+  `;
+}

package/templates/drizzle/src/main.ts

@@ -0,0 +1,145 @@
+import {
+  ClassSerializerInterceptor,
+} from '@nestjs/common';
+import {
+  NestFactory,
+  Reflector,
+} from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { join } from 'node:path';
+import { Logger } from 'nestjs-pino';
+import helmet from 'helmet';
+
+// nestforge:feature:validation
+import { ZodValidationPipe } from 'nestjs-zod';
+// nestforge:feature:validation:end
+
+// nestforge:feature:swagger
+import { patchNestJsSwagger } from 'nestjs-zod';
+import {
+  DocumentBuilder,
+  SwaggerModule,
+} from '@nestjs/swagger';
+// nestforge:feature:swagger:end
+
+import { AppModule } from './app.module';
+import { HttpExceptionFilter } from './common/filters/http-exception.filter';
+
+// nestforge:feature:auth:session
+import session from 'express-session';
+import { DrizzleSessionStore } from './auth/drizzle-session.store';
+// nestforge:feature:auth:session:end
+
+async function bootstrap() {
+  const app =
+    await NestFactory.create<NestExpressApplication>(
+      AppModule,
+      {
+        bufferLogs: true,
+      },
+    );
+
+  app.useStaticAssets(
+    join(process.cwd(), 'uploads'),
+    {
+      prefix: '/uploads',
+    },
+  );
+
+  app.useLogger(app.get(Logger));
+  app.use(helmet());
+
+  // nestforge:feature:auth:session
+  const sessionStore = app.get(
+    DrizzleSessionStore,
+  );
+
+  const sessionMaxAge = Number(
+    process.env.SESSION_MAX_AGE ??
+    7 * 24 * 60 * 60 * 1000,
+  );
+
+  if (
+    process.env.NODE_ENV === 'production'
+  ) {
+    app.set('trust proxy', 1);
+  }
+
+  app.use(
+    session({
+      name: 'nestforge.sid',
+      secret:
+        process.env.SESSION_SECRET as string,
+      resave: false,
+      saveUninitialized: false,
+      store: sessionStore,
+      cookie: {
+        httpOnly: true,
+        secure:
+          process.env.NODE_ENV ===
+          'production',
+        sameSite: 'lax',
+        maxAge: sessionMaxAge,
+      },
+    }),
+  );
+  // nestforge:feature:auth:session:end
+
+  const corsOrigins = (
+    process.env.CORS_ORIGINS ??
+    'http://localhost:5173'
+  )
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+
+  app.enableCors({
+    origin: corsOrigins,
+    credentials: true,
+  });
+
+  // nestforge:feature:validation
+  app.useGlobalPipes(
+    new ZodValidationPipe(),
+  );
+  // nestforge:feature:validation:end
+
+  app.useGlobalFilters(
+    new HttpExceptionFilter(),
+  );
+
+  app.useGlobalInterceptors(
+    new ClassSerializerInterceptor(
+      app.get(Reflector),
+    ),
+  );
+
+  // nestforge:feature:swagger
+  patchNestJsSwagger();
+
+  const config = new DocumentBuilder()
+    .setTitle('NestForge API')
+    .setDescription(
+      'Production-ready NestJS starter API docs',
+    )
+    .setVersion('0.1.0')
+    .addBearerAuth()
+    .build();
+
+  const document =
+    SwaggerModule.createDocument(
+      app,
+      config,
+    );
+
+  SwaggerModule.setup(
+    'docs',
+    app,
+    document,
+  );
+  // nestforge:feature:swagger:end
+
+  const port = process.env.PORT ?? 3000;
+
+  await app.listen(port);
+}

package/templates/drizzle/src/metrics/metrics.controller.ts

@@ -0,0 +1,22 @@
+import { Controller, Get, Res } from '@nestjs/common';
+import { Response } from 'express';
+// nestforge:feature:swagger
+import { ApiExcludeController } from '@nestjs/swagger';
+// nestforge:feature:swagger:end
+import { Public } from '../common/decorators/public.decorator';
+import { MetricsService } from './metrics.service';
+
+// nestforge:feature:swagger
+@ApiExcludeController()
+// nestforge:feature:swagger:end
+@Controller('metrics')
+export class MetricsController {
+    constructor(private readonly metricsService: MetricsService) { }
+
+    @Public()
+    @Get()
+    async getMetrics(@Res() res: Response) {
+        res.set('Content-Type', this.metricsService.getContentType());
+        res.send(await this.metricsService.getMetrics());
+    }
+}

package/templates/drizzle/src/metrics/metrics.interceptor.ts

@@ -0,0 +1,30 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+import { MetricsService } from './metrics.service';
+
+@Injectable()
+export class MetricsInterceptor implements NestInterceptor {
+    constructor(private readonly metricsService: MetricsService) { }
+
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+        const request = context.switchToHttp().getRequest();
+        const response = context.switchToHttp().getResponse();
+        const start = process.hrtime();
+        const route = request.route?.path ?? request.url;
+
+        return next.handle().pipe(
+            tap(() => {
+                const [seconds, nanoseconds] = process.hrtime(start);
+                const duration = seconds + nanoseconds / 1e9;
+                const labels = {
+                    method: request.method,
+                    route,
+                    status_code: String(response.statusCode),
+                };
+
+                this.metricsService.httpRequestDuration.observe(labels, duration);
+                this.metricsService.httpRequestsTotal.inc(labels);
+            }),
+        );
+    }
+}

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

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { MetricsService } from './metrics.service';
+import { MetricsController } from './metrics.controller';
+import { MetricsInterceptor } from './metrics.interceptor';
+
+@Module({
+    controllers: [MetricsController],
+    providers: [MetricsService, { provide: APP_INTERCEPTOR, useClass: MetricsInterceptor }],
+    exports: [MetricsService],
+})
+export class MetricsModule { }

package/templates/drizzle/src/metrics/metrics.service.ts

@@ -0,0 +1,34 @@
+import { Injectable } from '@nestjs/common';
+import * as client from 'prom-client';
+
+@Injectable()
+export class MetricsService {
+    readonly registry = new client.Registry();
+
+    readonly httpRequestDuration = new client.Histogram({
+        name: 'http_request_duration_seconds',
+        help: 'Duração das requisições HTTP em segundos',
+        labelNames: ['method', 'route', 'status_code'],
+        buckets: [0.05, 0.1, 0.3, 0.5, 1, 2, 5],
+        registers: [this.registry],
+    });
+
+    readonly httpRequestsTotal = new client.Counter({
+        name: 'http_requests_total',
+        help: 'Total de requisições HTTP recebidas',
+        labelNames: ['method', 'route', 'status_code'],
+        registers: [this.registry],
+    });
+
+    constructor() {
+        client.collectDefaultMetrics({ register: this.registry });
+    }
+
+    async getMetrics(): Promise<string> {
+        return this.registry.metrics();
+    }
+
+    getContentType(): string {
+        return this.registry.contentType;
+    }
+}

package/templates/drizzle/src/types/express-session.d.ts

@@ -0,0 +1,13 @@
+// nestforge:feature-file:auth:session
+import 'express-session';
+
+declare module 'express-session' {
+    interface SessionData {
+        user?: {
+            id: string;
+            email: string;
+            role: string;
+        };
+        csrfToken?: string;
+    }
+}

package/templates/drizzle/src/users/dto/create-user.dto.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+import { Role } from '../../common/constants/role.enum';
+
+export const createUserSchema = z.object({
+  name: z.string().min(2).describe('Nome completo'),
+  email: z.string().email().describe('E-mail do usuário'),
+  password: z.string().min(8).describe('Senha (mínimo 8 caracteres)'),
+  role: z.nativeEnum(Role).optional().describe('Role do usuário (padrão: USER)'),
+});
+
+export class CreateUserDto extends createZodDto(createUserSchema) { }

package/templates/drizzle/src/users/dto/find-users-query.dto.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+import { Role } from '../../common/constants/role.enum';
+
+export const findUsersQuerySchema = z.object({
+    page: z.coerce.number().int().min(1).default(1).describe('Página atual'),
+    limit: z.coerce.number().int().min(1).max(100).default(10).describe('Itens por página (máx. 100)'),
+    search: z.string().optional().describe('Busca por nome ou e-mail'),
+    role: z.nativeEnum(Role).optional().describe('Filtra por role'),
+});
+
+export class FindUsersQueryDto extends createZodDto(findUsersQuerySchema) { }

package/templates/drizzle/src/users/dto/update-user.dto.ts

@@ -0,0 +1,6 @@
+import { createZodDto } from 'nestjs-zod';
+import { createUserSchema } from './create-user.dto';
+
+export const updateUserSchema = createUserSchema.partial();
+
+export class UpdateUserDto extends createZodDto(updateUserSchema) { }

package/templates/drizzle/src/users/entities/user.entity.ts

@@ -0,0 +1,23 @@
+import { Exclude } from 'class-transformer';
+import type { User } from '../../database/schema';
+
+export class UserEntity {
+    id!: string;
+    name!: string;
+    email!: string;
+
+    @Exclude()
+    passwordHash!: string | null;
+
+    role!: User['role'];
+    avatarUrl!: string | null;
+    emailVerifiedAt!: Date | null;
+    createdAt!: Date;
+    updatedAt!: Date;
+
+    constructor(partial?: Partial<User>) {
+        if (partial) {
+            Object.assign(this, partial);
+        }
+    }
+}

package/templates/drizzle/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/drizzle/src/users/users.module.ts

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