@koalarx/nest 1.18.21 → 1.19.0

package/README.md

@@ -12,9 +12,22 @@
 [![Bun](https://img.shields.io/badge/Bun-1.3%2B-black)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.1%2B-blue)](https://www.typescriptlang.org/)
 [![CLI](https://img.shields.io/badge/CLI-@koalarx/nest--cli-brightgreen)](https://www.npmjs.com/package/@koalarx/nest-cli)
+[![VS Code Extension](https://img.shields.io/badge/VS%20Code-MCP%20Extension-blue)](https://marketplace.visualstudio.com/items?itemName=koalarx.koala-libs-mcp-docs)
 
 </div>
 
+## 🤖 Extensão VS Code com MCP
+
+Acelere seu desenvolvimento com a **extensão oficial para VS Code**! Toda a documentação do Koala Nest integrada diretamente no GitHub Copilot através do Model Context Protocol.
+
+**[📦 Instalar Extensão](https://marketplace.visualstudio.com/items?itemName=koalarx.koala-libs-mcp-docs)**
+
+Basta instalar e perguntar ao Copilot sobre o Koala Nest - ele terá acesso instantâneo à documentação oficial!
+
+> 💡 **Exemplo:** "Como criar um controller CRUD no Koala Nest?" - O Copilot responderá com base na documentação atualizada.
+
+**[📖 Documentação da Extensão MCP](./docs/09-mcp-vscode-extension.md)**
+
 ## 🎯 O que você consegue fazer com @koalarx/nest
 
 - ✅ **Implementar APIs REST completas** com CRUD automático
@@ -41,6 +54,7 @@ Toda a documentação está organizada em arquivos separados para facilitar a na
 | [**Decoradores**](./docs/06-decoradores.md) | @IsPublic, @Upload, @Cookies e mais |
 | [**Guia Bun**](./docs/07-guia-bun.md) | Por que Bun e como usá-lo |
 | [**Prisma Client**](./docs/08-prisma-client.md) | Integração com Prisma |
+| [**🤖 Extensão MCP**](./docs/09-mcp-vscode-extension.md) | **Extensão VS Code com integração ao Copilot** |
 
 ## Quick Start
 

package/docs/00-cli-reference.md

@@ -0,0 +1,201 @@
+# CLI Reference - @koalarx/nest-cli
+
+A CLI oficial da biblioteca `@koalarx/nest` facilita a criação de novos projetos estruturados automaticamente.
+
+## Instalação da CLI
+
+```bash
+npm install -g @koalarx/nest-cli
+```
+
+**Requisitos:**
+- Node.js 20.18.0 ou superior
+
+## Comandos Disponíveis
+
+### Criar Novo Projeto
+
+```bash
+koala-nest new <nome-do-projeto>
+```
+
+**Exemplos:**
+
+```bash
+# Criar um projeto chamado "meu-app"
+koala-nest new meu-app
+
+# Entrar na pasta do projeto
+cd meu-app
+
+# Instalar dependências
+npm install
+
+# Iniciar em modo desenvolvimento
+npm run start:dev
+```
+
+## O que a CLI Configura Automaticamente
+
+Quando você cria um novo projeto com a CLI, ele inclui:
+
+### 📁 Estrutura de Pastas
+
+```
+src/
+├── host/                          # Camada de entrada
+│   ├── app.module.ts              # Módulo principal
+│   ├── main.ts                    # Ponto de entrada
+│   └── controllers/               # Controladores
+├── core/                          # Configuração central
+│   ├── env.ts                     # Variáveis de ambiente
+│   └── database/                  # Configuração do banco
+├── application/                   # Lógica de aplicação
+│   ├── handlers/                  # Command handlers
+│   └── mapping/                   # AutoMapper profiles
+├── domain/                        # Lógica de negócio
+│   ├── entities/                  # Entidades
+│   ├── repositories/              # Interfaces de repositório
+│   ├── dtos/                      # Data Transfer Objects
+│   └── services/                  # Serviços de domínio
+├── infra/                         # Implementação técnica
+│   ├── database/                  # Repositories concretos
+│   ├── services/                  # Serviços técnicos
+│   └── mappers/                   # Mapeadores
+└── test/                          # Utilitários de teste
+```
+
+### 🛠️ Configuração Incluída
+
+- ✅ **Módulo KoalaNest** - Configurado e pronto para uso
+- ✅ **Prisma ORM** - Integrado com PostgreSQL
+- ✅ **Redis** - Configurado para sincronização de background services
+- ✅ **Padrões de Autenticação** - Templates para implementar Guards com JWT ou API Key
+- ✅ **Documentação Swagger/Scalar** - API documentada automaticamente
+- ✅ **Tratamento de Erros** - Filtros de exceção configurados
+- ✅ **Validação com Zod** - Schema validation pronto
+- ✅ **Exemplo Prático** - Entidade de exemplo (Pessoa) para referência
+
+### 📦 Dependências Instaladas
+
+```bash
+# Core
+@koalarx/nest
+@nestjs/common
+@nestjs/core
+@nestjs/config
+@nestjs/platform-express
+
+# Banco de Dados
+@prisma/client
+prisma
+
+# Autenticação
+@nestjs/jwt
+@nestjs/passport
+passport-jwt
+
+# Validação
+zod
+
+# Documentação
+@nestjs/swagger
+@scalar/nestjs-api-reference
+
+# Utilitários
+ioredis
+dotenv
+reflect-metadata
+
+# Desenvolvimento
+typescript
+@types/node
+ts-node
+tsx
+```
+
+## Próximos Passos Após Criar o Projeto
+
+1. **Configure as variáveis de ambiente** (.env)
+   ```bash
+   # Edite o arquivo .env com seus valores
+   nano .env
+   ```
+
+2. **Inicie o banco de dados** (se usar PostgreSQL)
+   ```bash
+   # Crie as tabelas
+   npm run prisma:migrate:dev
+   ```
+
+3. **Inicie a aplicação**
+   ```bash
+   npm run start:dev
+   ```
+
+4. **Acesse a documentação**
+   - Scalar UI: `http://localhost:3000/doc`
+   - Swagger: `http://localhost:3000/api`
+
+## Exemplos de Uso
+
+### Criar um Projeto Simples
+
+```bash
+koala-nest new blog-api
+cd blog-api
+npm install
+npm run start:dev
+```
+
+Seu blog API estará rodando em `http://localhost:3000` com:
+- Exemplo de entidade (Pessoa)
+- Endpoints CRUD funcionais
+- Autenticação JWT configurada
+- Documentação interativa
+
+### Estrutura Gerada Exemplo
+
+O projeto criado inclui:
+- **PersonController** - Exemplo de controlador REST
+- **PersonService** - Exemplo de serviço de domínio
+- **PersonRepository** - Exemplo de repositório
+- **Migrations Prisma** - Schema de exemplo para rodar
+
+## Troubleshooting
+
+### Node.js Versão Incompatível
+
+```bash
+# Verifique sua versão
+node --version
+
+# Você precisa da versão 20.18.0 ou superior
+# Atualize node se necessário
+```
+
+### Problemas com Permissões no Linux/Mac
+
+```bash
+# Se receber erro de permissão, use sudo
+sudo npm install -g @koalarx/nest-cli
+```
+
+### Limpar Cache de Instalação
+
+```bash
+npm cache clean --force
+npm install -g @koalarx/nest-cli
+```
+
+## Repositório da CLI
+
+Para mais informações, contribuições ou reportar bugs:
+- **GitHub:** [koala-nest-cli](https://github.com/igordrangel/koala-nest-cli)
+- **NPM:** [@koalarx/nest-cli](https://www.npmjs.com/package/@koalarx/nest-cli)
+
+## Links Úteis
+
+- [Guia de Instalação](./01-guia-instalacao.md) - Mais detalhes sobre setup manual
+- [Configuração Inicial](./02-configuracao-inicial.md) - Entender a estrutura criada
+- [Exemplo Prático](./EXAMPLE.md) - Aprender com exemplos completos e funcionando

package/docs/01-guia-instalacao.md

@@ -0,0 +1,113 @@
+# Guia de Instalação
+
+## Introdução
+
+`@koalarx/nest` é uma abstração robusta baseada em NestJS que facilita a criação de aplicações escaláveis seguindo os princípios do Domain-Driven Design (DDD).
+
+## Forma Rápida: Usando a CLI
+
+A forma mais rápida de começar é usar a CLI oficial `@koalarx/nest-cli`:
+
+```bash
+# Instalar a CLI globalmente
+npm install -g @koalarx/nest-cli
+
+# Criar novo projeto
+koala-nest new meu-projeto
+
+# Entrar na pasta
+cd meu-projeto
+
+# Iniciar a aplicação
+npm run start:dev
+```
+
+**Pronto!** Seu projeto está estruturado com todas as best practices incluídas.
+
+## Instalação Manual
+
+Se preferir configurar manualmente, siga os passos abaixo.
+
+## Pré-requisitos
+
+- Node.js 20.18.0+ e npm 9+
+- Conhecimento básico de NestJS
+- PostgreSQL 12+ (para integração com banco de dados)
+
+## Instalação
+
+### 1. Instalar via NPM
+
+```bash
+npm install @koalarx/nest
+```
+
+### 2. Instalar Dependências Necessárias
+
+```bash
+npm install @nestjs/common @nestjs/core @nestjs/config @nestjs/platform-express
+npm install @nestjs/swagger reflect-metadata zod dotenv
+npm install @prisma/client @prisma/adapter-pg
+npm install ioredis
+```
+
+### 3. Configurar Ambiente
+
+Crie um arquivo `.env` na raiz do seu projeto:
+
+```env
+NODE_ENV=develop
+DATABASE_URL=postgresql://user:password@localhost:5432/database_name
+REDIS_URL=redis://localhost:6379
+SWAGGER_USERNAME=admin
+SWAGGER_PASSWORD=password123
+```
+
+### 4. Configurar TypeScript
+
+Atualize seu `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "typeRoots": ["./node_modules/@types"],
+    "baseUrl": "./",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Estrutura Básica do Projeto
+
+Recomenda-se seguir a estrutura DDD:
+
+```
+src/
+├── application/        # Lógica de aplicação (casos de uso, mapeadores)
+├── core/              # Configurações globais
+├── domain/            # Entidades, DTOs, repositórios, serviços
+├── host/              # Controladores, ponto de entrada
+├── infra/             # Implementações de infraestrutura
+└── main.ts            # Inicialização da aplicação
+```
+
+## Próximos Passos
+
+Consulte o [Guia de Configuração Inicial](./02-configuracao-inicial.md) para aprender como configurar sua primeira aplicação com Koala Nest.

package/docs/02-configuracao-inicial.md

@@ -0,0 +1,176 @@
+# Configuração Inicial
+
+## Usando a CLI (Recomendado)
+
+Se você usou a CLI para criar seu projeto (`koala-nest new`), toda a estrutura base já está configurada automaticamente. Você pode pular direto para a próxima seção de desenvolvimento.
+
+Se você fez instalação manual, siga os passos abaixo.
+
+## Estrutura de Módulos
+
+A biblioteca utiliza uma arquitetura modular centrada em dois módulos principais: `KoalaNestModule` para configuração do módulo e `KoalaApp` para inicialização da aplicação.
+
+## Setup do Módulo Principal
+
+### 1. Criar o Módulo da Aplicação
+
+```typescript
+// src/host/app.module.ts
+import { KoalaNestModule } from '@koalarx/nest/core/koala-nest.module'
+import { Module } from '@nestjs/common'
+import { env } from '../core/env'
+import { PersonModule } from './controllers/person/person.module'
+
+@Module({
+  imports: [
+    KoalaNestModule.register({
+      env,                              // Validação de variáveis de ambiente
+      controllers: [PersonModule],      // Módulos de controladores
+      cronJobs: [],                     // Jobs agendados
+      eventJobs: [],                    // Handlers de eventos
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+> **Nota sobre Autenticação**: Para implementar Guards de autenticação (JWT, API Key, etc.), veja padrões e exemplos em [Features Avançadas - Autenticação](./05-features-avancadas.md#3-autenticação-e-autorização).
+
+### 2. Configurar Variáveis de Ambiente
+
+A lib `@koalarx/nest` já possui um schema padrão com as variáveis essenciais. Estenda-o para adicionar as suas:
+
+```typescript
+// src/core/env.ts
+import { envSchema } from '@koalarx/nest/env/env'
+import { z } from 'zod'
+
+// Schema padrão da lib já inclui: PORT, NODE_ENV, DATABASE_URL, PRISMA_QUERY_LOG, etc
+// Faça merge para adicionar suas próprias variáveis
+export const env = envSchema.merge(z.object({
+  // Suas variáveis customizadas aqui
+  CUSTOM_VAR: z.string().optional(),
+}))
+
+export type Env = z.infer<typeof env>
+```
+
+**Variáveis padrão da lib (já validadas):**
+- `PORT` - Porta da aplicação (padrão: 3000)
+- `NODE_ENV` - Ambiente (test|develop|staging|production)
+- `DATABASE_URL` - String de conexão PostgreSQL (obrigatória)
+- `PRISMA_QUERY_LOG` - Log de queries SQL (opcional)
+- `SWAGGER_USERNAME` - Usuário para Swagger (opcional)
+- `SWAGGER_PASSWORD` - Senha para Swagger (opcional)
+- `REDIS_CONNECTION_STRING` - Conexão Redis (opcional)
+
+### 3. Inicializar a Aplicação
+
+```typescript
+// src/main.ts
+import 'dotenv/config'
+import { NestFactory } from '@nestjs/core'
+import { KoalaApp } from '@koalarx/nest/core/koala-app'
+import { AppModule } from './host/app.module'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  
+  await new KoalaApp(app)
+    .useDoc({
+      ui: 'scalar',           // ou 'swagger'
+      endpoint: '/doc',
+      title: 'My API',
+      version: '1.0.0',
+    })
+    .enableCors()
+    .setAppName('my-app')
+    .setInternalUserName('system.bot')
+    .buildAndServe()
+}
+
+bootstrap()
+```
+
+## Configurar Prisma (Obrigatório)
+
+> ⚠️ **Importante**: A abstração de banco de dados da biblioteca **requer obrigatoriamente o Prisma como ORM**. O `RepositoryBase` e toda a camada de acesso a dados são construídos sobre o Prisma.
+
+Prisma suporta múltiplos drivers de banco de dados. Exemplo com PostgreSQL:
+
+### 1. Instalar Prisma
+
+```bash
+npm install prisma @prisma/client
+npm install -D prisma
+# Para PostgreSQL, adicione:
+npm install @prisma/adapter-pg pg
+```
+
+**Outros drivers:**
+- MySQL/MariaDB: `npm install mysql2`
+- SQLite: Sem dependências adicionais
+- SQL Server: `npm install tedious`
+- MongoDB: `npm install mongodb`
+
+### 2. Inicializar Schema
+
+```bash
+npx prisma init
+```
+
+### 3. Configurar Database Adapter (Exemplo: PostgreSQL)
+
+```typescript
+// src/main.ts
+import 'dotenv/config'
+import { NestFactory } from '@nestjs/core'
+import { KoalaApp } from '@koalarx/nest/core/koala-app'
+import { setPrismaClientOptions } from '@koalarx/nest'
+import { PrismaPg } from '@prisma/adapter-pg'
+import { Pool } from 'pg'
+import { AppModule } from './host/app.module'
+
+async function bootstrap() {
+  // Configurar o adapter PostgreSQL antes de criar a aplicação
+  const pool = new Pool({
+    connectionString: process.env.DATABASE_URL,
+  })
+  const adapter = new PrismaPg(pool)
+  setPrismaClientOptions({ adapter })
+
+  const app = await NestFactory.create(AppModule)
+  
+  await new KoalaApp(app)
+    .useDoc({
+      ui: 'scalar',
+      endpoint: '/doc',
+      title: 'My API',
+      version: '1.0.0',
+    })
+    .buildAndServe()
+}
+
+bootstrap()
+```
+
+## Executar a Aplicação
+
+```bash
+# Desenvolvimento
+npm run start:dev
+
+# Debug
+npm run start:debug
+
+# Produção
+npm run build
+npm start
+```
+
+A aplicação estará disponível em `http://localhost:3000` e a documentação em `http://localhost:3000/doc`.
+
+## Próximos Passos
+
+- Veja [EXAMPLE.md](./EXAMPLE.md) para aprender a estruturar seus endpoints e implementar a aplicação completa
+- Consulte [Tratamento de Erros](./04-tratamento-erros.md) para implementar tratamento robusto de exceções