nestforge-generator 0.1.0

package/templates/typeorm/docker-compose.yml

@@ -0,0 +1,78 @@
+version: "3.9"
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: nestforge-api
+    ports:
+      - "3000:3000"
+    env_file:
+      - .env
+    depends_on:
+      # nestforge:feature:database:postgres
+      - postgres
+      # nestforge:feature:database:postgres:end
+      # nestforge:feature:database:mysql
+      - mysql
+      # nestforge:feature:database:mysql:end
+      - redis
+    volumes:
+      - ./src:/app/src
+    command: npm run start:dev
+
+  # nestforge:feature:database:postgres
+  postgres:
+    image: postgres:16-alpine
+    container_name: nestforge-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: nestforge
+      POSTGRES_PASSWORD: nestforge
+      POSTGRES_DB: nestforge
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+  # nestforge:feature:database:postgres:end
+
+  # nestforge:feature:database:mysql
+  mysql:
+    image: mysql:8
+    container_name: nestforge-mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_USER: nestforge
+      MYSQL_PASSWORD: nestforge
+      MYSQL_ROOT_PASSWORD: nestforge
+      MYSQL_DATABASE: nestforge
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+  # nestforge:feature:database:mysql:end
+
+  redis:
+    image: redis:7-alpine
+    container_name: nestforge-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: nestforge-mailpit
+    restart: unless-stopped
+    ports:
+      - "8025:8025" # UI
+      - "1025:1025" # SMTP
+
+  # nestforge:feature:database:postgres
+volumes:
+  postgres_data:
+  # nestforge:feature:database:postgres:end
+  # nestforge:feature:database:mysql
+volumes:
+  mysql_data:
+  # nestforge:feature:database:mysql:end

package/templates/typeorm/docs/adding-a-module.md

@@ -0,0 +1,369 @@
+# Adicionando um módulo
+
+Este guia mostra como adicionar um módulo `posts` ao projeto usando NestJS, TypeORM e Zod.
+
+## 1. Crie a entidade
+
+Crie `src/posts/entities/post.entity.ts`:
+
+```ts
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  JoinColumn,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { UserEntity } from '../../users/entities/user.entity';
+
+@Entity({ name: 'posts' })
+export class PostEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id!: string;
+
+  @Column({
+    type: 'varchar',
+    length: 200,
+  })
+  title!: string;
+
+  @Column({
+    type: 'text',
+  })
+  content!: string;
+
+  @Column({
+    name: 'author_id',
+    type: 'varchar',
+    length: 36,
+  })
+  authorId!: string;
+
+  @ManyToOne(() => UserEntity, {
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn({
+    name: 'author_id',
+  })
+  author!: UserEntity;
+
+  @CreateDateColumn({
+    name: 'created_at',
+  })
+  createdAt!: Date;
+
+  @UpdateDateColumn({
+    name: 'updated_at',
+  })
+  updatedAt!: Date;
+
+  constructor(partial?: Partial<PostEntity>) {
+    if (partial) {
+      Object.assign(this, partial);
+    }
+  }
+}
+```
+
+## 2. Crie os DTOs
+
+Crie `src/posts/dto/create-post.dto.ts`:
+
+```ts
+import { z } from 'zod';
+import { createZodDto } from 'nestjs-zod';
+
+export const createPostSchema = z.object({
+  title: z
+    .string()
+    .min(3)
+    .max(200),
+  content: z.string().min(1),
+});
+
+export class CreatePostDto extends createZodDto(
+  createPostSchema,
+) {}
+```
+
+Crie `src/posts/dto/update-post.dto.ts`:
+
+```ts
+import { createZodDto } from 'nestjs-zod';
+import { createPostSchema } from './create-post.dto';
+
+export const updatePostSchema =
+  createPostSchema.partial();
+
+export class UpdatePostDto extends createZodDto(
+  updatePostSchema,
+) {}
+```
+
+## 3. Crie o service
+
+Crie `src/posts/posts.service.ts`:
+
+```ts
+import {
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { PostEntity } from './entities/post.entity';
+import { CreatePostDto } from './dto/create-post.dto';
+import { UpdatePostDto } from './dto/update-post.dto';
+
+@Injectable()
+export class PostsService {
+  constructor(
+    @InjectRepository(PostEntity)
+    private readonly postsRepository: Repository<PostEntity>,
+  ) {}
+
+  async create(
+    authorId: string,
+    dto: CreatePostDto,
+  ) {
+    const post = this.postsRepository.create({
+      ...dto,
+      authorId,
+    });
+
+    return this.postsRepository.save(post);
+  }
+
+  async findAll() {
+    return this.postsRepository.find({
+      relations: {
+        author: true,
+      },
+      order: {
+        createdAt: 'DESC',
+      },
+    });
+  }
+
+  async findOne(id: string) {
+    const post = await this.postsRepository.findOne({
+      where: { id },
+      relations: {
+        author: true,
+      },
+    });
+
+    if (!post) {
+      throw new NotFoundException(
+        'Post não encontrado',
+      );
+    }
+
+    return post;
+  }
+
+  async update(
+    id: string,
+    dto: UpdatePostDto,
+  ) {
+    const post = await this.findOne(id);
+
+    Object.assign(post, dto);
+
+    return this.postsRepository.save(post);
+  }
+
+  async remove(id: string) {
+    const post = await this.findOne(id);
+
+    await this.postsRepository.remove(post);
+
+    return {
+      message: 'Post removido com sucesso',
+    };
+  }
+}
+```
+
+## 4. Crie o controller
+
+Crie `src/posts/posts.controller.ts`:
+
+```ts
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Patch,
+  Post,
+  Req,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { PostsService } from './posts.service';
+import { CreatePostDto } from './dto/create-post.dto';
+import { UpdatePostDto } from './dto/update-post.dto';
+
+@Controller('posts')
+export class PostsController {
+  constructor(
+    private readonly postsService: PostsService,
+  ) {}
+
+  @Post()
+  create(
+    @Req() request: Request,
+    @Body() dto: CreatePostDto,
+  ) {
+    return this.postsService.create(
+      request.user.id,
+      dto,
+    );
+  }
+
+  @Get()
+  findAll() {
+    return this.postsService.findAll();
+  }
+
+  @Get(':id')
+  findOne(@Param('id') id: string) {
+    return this.postsService.findOne(id);
+  }
+
+  @Patch(':id')
+  update(
+    @Param('id') id: string,
+    @Body() dto: UpdatePostDto,
+  ) {
+    return this.postsService.update(id, dto);
+  }
+
+  @Delete(':id')
+  remove(@Param('id') id: string) {
+    return this.postsService.remove(id);
+  }
+}
+```
+
+Se o projeto não usa autenticação, remova `@Req()` e receba `authorId` de outra forma adequada ao domínio.
+
+## 5. Registre o repository no módulo
+
+Crie `src/posts/posts.module.ts`:
+
+```ts
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { PostEntity } from './entities/post.entity';
+import { PostsController } from './posts.controller';
+import { PostsService } from './posts.service';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      PostEntity,
+    ]),
+  ],
+  controllers: [PostsController],
+  providers: [PostsService],
+  exports: [PostsService],
+})
+export class PostsModule {}
+```
+
+Depois importe `PostsModule` em `src/app.module.ts`.
+
+## 6. Gere e aplique a migration
+
+```bash
+npm run migration:generate -- src/database/migrations/AddPosts
+npm run migration:run
+```
+
+Confira o arquivo gerado antes de executar a migration em produção.
+
+Para desfazer a última migration:
+
+```bash
+npm run migration:revert
+```
+
+## 7. Adicione testes unitários
+
+O teste unitário deve mockar o repository:
+
+```ts
+import { Repository } from 'typeorm';
+import { vi } from 'vitest';
+import { PostsService } from './posts.service';
+import { PostEntity } from './entities/post.entity';
+
+const postsRepository = {
+  findOne: vi.fn(),
+  find: vi.fn(),
+  create: vi.fn(),
+  save: vi.fn(),
+  remove: vi.fn(),
+};
+
+const postsService = new PostsService(
+  postsRepository as unknown as Repository<PostEntity>,
+);
+```
+
+Dessa forma, o teste não precisa iniciar o Nest nem conectar ao banco.
+
+## 8. Atualize a limpeza E2E
+
+Em `test/utils/clean-database.ts`, exclua posts antes de usuários:
+
+```ts
+await manager
+  .createQueryBuilder()
+  .delete()
+  .from(PostEntity)
+  .execute();
+```
+
+A ordem é importante por causa da chave estrangeira `posts.author_id`.
+
+## 9. Use transações quando necessário
+
+Quando várias operações precisarem ser atômicas, injete `DataSource`:
+
+```ts
+constructor(
+  private readonly dataSource: DataSource,
+) {}
+```
+
+E execute:
+
+```ts
+await this.dataSource.transaction(
+  async (manager) => {
+    await manager.save(...);
+    await manager.update(...);
+  },
+);
+```
+
+Se uma operação falhar, a transação inteira será revertida.
+
+## Checklist
+
+- [ ] Entidade criada
+- [ ] DTOs Zod criados
+- [ ] Service usa `Repository<Entity>`
+- [ ] Repository registrado com `TypeOrmModule.forFeature`
+- [ ] Controller criado
+- [ ] Módulo importado no `AppModule`
+- [ ] Migration gerada e revisada
+- [ ] Migration aplicada
+- [ ] Testes unitários adicionados
+- [ ] Limpeza dos testes E2E atualizada
+- [ ] Swagger e permissões adicionados, quando aplicáveis

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

@@ -0,0 +1,50 @@
+# Marcadores de features (feature markers)
+
+O `templates/typeorm` é usado tanto como projeto standalone quanto como fonte para a CLI (`packages/cli`) gerar projetos.
+
+Se você está adicionando código ligado a um recurso que já existe como pergunta na CLI (ou propondo um recurso novo opcional), marque o trecho seguindo esta convenção.
+
+## Marcador de bloco
+
+Envolve um trecho de código (uma ou várias linhas) dentro de um arquivo que tem outras coisas não-opcionais também.
+
+```ts
+// nestforge:feature:swagger
+@ApiTags('users')
+// nestforge:feature:swagger:end
+@Controller('users')
+export class UsersController {
+```
+
+- Recurso **habilitado**: a CLI remove só as duas linhas de marcador, o `@ApiTags('users')` fica.
+- Recurso **desabilitado**: a CLI remove o bloco inteiro (marcador + `@ApiTags('users')`).
+
+O nome depois de `nestforge:feature:` tem que ser exatamente o mesmo nas duas linhas (abertura e `:end`), e bater com o nome usado no array `features` da CLI (`docker`, `swagger`, `validation`, `redis`, `rbac`).
+
+Funciona em qualquer arquivo cuja linguagem use `//` para comentário (`.ts`, `.js`). **Não funciona em JSON** (`package.json`) — pra dependências, ver a seção final deste documento.
+
+## Marcador de arquivo inteiro
+
+Quando o arquivo **inteiro** só faz sentido se o recurso estiver ligado (ex: `src/mail/mail.service.ts`, que só existe por causa do Redis/BullMQ), marque a primeira linha do arquivo:
+
+```ts
+// nestforge:feature-file:redis
+import { Injectable } from '@nestjs/common';
+// ...resto do arquivo normalmente
+```
+
+- Recurso **habilitado**: a CLI remove só essa primeira linha, o resto do arquivo fica intacto.
+- Recurso **desabilitado**: a CLI apaga o arquivo inteiro.
+
+Se, depois de remover arquivos, uma pasta ficar vazia (ex: `src/mail/` inteira desapareceu), a CLI remove a pasta também — não precisa se preocupar em limpar pasta manualmente.
+
+## Dependências no `package.json`
+
+JSON não aceita comentário, então marcador não funciona ali. Em vez disso, o mapeamento fica direto no código da CLI: `packages/cli/src/features/dependencies.ts`, no objeto `FEATURE_DEPENDENCIES`. Se seu recurso opcional adiciona uma dependência nova ao `package.json` do template, adicione ela nesse mapa também.
+
+## Checklist ao adicionar um recurso opcional novo
+
+- [ ] Todo trecho de código exclusivo do recurso está marcado (bloco ou arquivo inteiro)
+- [ ] O nome do marcador bate com o valor usado em `features` na CLI (`packages/cli/src/prompts.ts`)
+- [ ] Dependências novas do `package.json` estão em `FEATURE_DEPENDENCIES` (`packages/cli/src/features/dependencies.ts`)
+- [ ] Testado gerando o projeto com o recurso ligado **e** desligado — o projeto tem que compilar/rodar dos dois jeitos

package/templates/typeorm/nest-cli.json

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

package/templates/typeorm/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "nestforge",
+  "version": "0.1.0",
+  "description": "Production-ready NestJS starter with TypeORM, 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",
+    "typeorm": "dotenv -e .env -- typeorm-ts-node-commonjs -d src/database/data-source.ts",
+    "migration:generate": "npm run typeorm -- migration:generate",
+    "migration:create": "typeorm migration:create",
+    "migration:run": "npm run typeorm -- migration:run",
+    "migration:revert": "npm run typeorm -- migration:revert",
+    "pretest:e2e": "dotenv -e .env.test -- typeorm-ts-node-commonjs -d src/database/data-source.ts migration:run",
+    "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",
+    "@nestjs/typeorm": "^11.0.0",
+    "typeorm": "^0.3.31",
+    "pg": "^8.23.0",
+    "mysql2": "^3.24.2",
+    "better-sqlite3": "^12.11.1",
+    "connect-typeorm": "^2.0.0"
+  },
+  "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",
+    "@types/pg": "^8.23.1",
+    "@types/better-sqlite3": "^7.6.13"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/typeorm/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
+  }
+}