@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/ide/cursor/.cursor/rules/skill-go-gin-api.mdc

@@ -0,0 +1,371 @@
+---
+description: Padrões DARE para APIs REST em Go + Gin (ou stdlib net/http) + sqlc + PostgreSQL. Handlers, services, repositories, middleware, validação via binding tags, JWT, rate limit, swag OpenAPI, testify + httptest.
+globs: **/*.go,go.mod,go.sum,sqlc.yaml,db/queries/*.sql
+alwaysApply: false
+---
+
+# Skill: Go/Gin API DARE
+
+Você é um desenvolvedor sênior Go especialista em APIs REST. Esta skill garante código **idiomático Go, com erros tipados, contexto sempre propagado, queries seguras via sqlc**, seguindo Layered Design DARE.
+
+## Stack canônica
+
+- **Go 1.22+** (`slog`, `errors.Is/As`, generics)
+- **Gin** (preferido) ou **stdlib net/http** (Go 1.22+ roteamento OK)
+- **sqlc** para queries seguras (gera código tipado de SQL)
+- **pgx v5** como driver Postgres
+- **go-playground/validator** (via Gin binding tags)
+- **golang-jwt/jwt v5**
+- **swaggo/swag** para OpenAPI
+- **testify** + **httptest**
+- **golangci-lint** + **govulncheck**
+
+---
+
+## Estrutura
+
+```
+.
+├── cmd/server/main.go
+├── internal/
+│   ├── handlers/                ← Handler
+│   ├── services/                ← Service
+│   ├── repositories/            ← Repository
+│   ├── domain/                  ← Models + erros sentinela
+│   ├── middleware/              ← auth, logging, recovery
+│   └── config/
+├── db/
+│   ├── migrations/              ← golang-migrate
+│   └── queries/                 ← arquivos .sql para sqlc
+├── sqlc.yaml
+└── docs/                        ← gerado pelo swag
+```
+
+---
+
+## Handlers
+
+```go
+package handlers
+
+import (
+    "errors"
+    "net/http"
+    "github.com/gin-gonic/gin"
+    "myapp/internal/domain"
+    "myapp/internal/services"
+)
+
+type UserHandler struct {
+    register *services.RegisterUser
+}
+
+func NewUserHandler(r *services.RegisterUser) *UserHandler {
+    return &UserHandler{register: r}
+}
+
+// @Summary Create user
+// @Tags users
+// @Accept json
+// @Produce json
+// @Param user body CreateUserDTO true "user payload"
+// @Success 201 {object} UserResponse
+// @Failure 409
+// @Router /users [post]
+func (h *UserHandler) Create(c *gin.Context) {
+    var dto CreateUserDTO
+    if err := c.ShouldBindJSON(&dto); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    user, err := h.register.Execute(c.Request.Context(), dto.ToService())
+    if err != nil {
+        if errors.Is(err, domain.ErrUserAlreadyExists) {
+            c.JSON(http.StatusConflict, gin.H{"error": "USER_EXISTS"})
+            return
+        }
+        c.JSON(http.StatusInternalServerError, gin.H{"error": "INTERNAL"})
+        return
+    }
+    c.JSON(http.StatusCreated, ToUserResponse(user))
+}
+```
+
+---
+
+## DTOs (binding tags)
+
+```go
+type CreateUserDTO struct {
+    Email    string `json:"email" binding:"required,email"`
+    Name     string `json:"name" binding:"required,min=1,max=255"`
+    Password string `json:"password" binding:"required,min=12"`
+}
+
+func (d CreateUserDTO) ToService() services.RegisterUserInput {
+    return services.RegisterUserInput{Email: d.Email, Name: d.Name, Password: d.Password}
+}
+
+type UserResponse struct {
+    ID        int64     `json:"id"`
+    Email     string    `json:"email"`
+    Name      string    `json:"name"`
+    CreatedAt time.Time `json:"createdAt"`
+}
+```
+
+---
+
+## Services
+
+```go
+type RegisterUser struct {
+    repo *repositories.UserRepository
+}
+
+type RegisterUserInput struct {
+    Email, Name, Password string
+}
+
+func (s *RegisterUser) Execute(ctx context.Context, in RegisterUserInput) (*domain.User, error) {
+    exists, err := s.repo.ExistsByEmail(ctx, in.Email)
+    if err != nil { return nil, err }
+    if exists { return nil, domain.ErrUserAlreadyExists }
+    return s.repo.Create(ctx, repositories.CreateUserParams{
+        Email: in.Email,
+        Name:  in.Name,
+        PasswordHash: hashPassword(in.Password),
+    })
+}
+```
+
+---
+
+## Repositories (sqlc)
+
+```sql
+-- db/queries/users.sql
+-- name: ExistsUserByEmail :one
+SELECT EXISTS(SELECT 1 FROM users WHERE email = $1);
+
+-- name: CreateUser :one
+INSERT INTO users (email, name, password_hash)
+VALUES ($1, $2, $3)
+RETURNING id, email, name, created_at;
+```
+
+```go
+type UserRepository struct {
+    q *sqlc.Queries
+}
+
+func (r *UserRepository) ExistsByEmail(ctx context.Context, email string) (bool, error) {
+    return r.q.ExistsUserByEmail(ctx, email)
+}
+```
+
+---
+
+## Domain
+
+```go
+package domain
+
+import (
+    "errors"
+    "time"
+)
+
+var (
+    ErrUserAlreadyExists = errors.New("user already exists")
+    ErrUserNotFound      = errors.New("user not found")
+)
+
+type User struct {
+    ID        int64
+    Email     string
+    Name      string
+    CreatedAt time.Time
+}
+```
+
+---
+
+## Middleware (JWT)
+
+```go
+func AuthRequired(secret []byte) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        tokenStr := strings.TrimPrefix(c.GetHeader("Authorization"), "Bearer ")
+        token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (any, error) { return secret, nil })
+        if err != nil || !token.Valid {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "Unauthorized"})
+            return
+        }
+        c.Set("user_id", token.Claims.(jwt.MapClaims)["sub"])
+        c.Next()
+    }
+}
+```
+
+---
+
+## Rate limiting
+
+```go
+import "github.com/gin-contrib/limit"
+
+router.Use(limit.MaxAllowed(20))   // global
+login := router.Group("/auth").Use(myRateLimiter("5/15m"))
+login.POST("/login", authHandler.Login)
+```
+
+---
+
+## OpenAPI (swag)
+
+```bash
+swag init -g cmd/server/main.go -o docs
+```
+
+```go
+// cmd/server/main.go
+// @title Projeto API
+// @version 1.0
+import _ "myapp/docs"
+import (
+    ginSwagger "github.com/swaggo/gin-swagger"
+    swaggerFiles "github.com/swaggo/files"
+)
+
+router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+router.GET("/openapi.json", func(c *gin.Context) {
+    c.File("docs/swagger.json")
+})
+```
+
+---
+
+## Config (env)
+
+```go
+type Config struct {
+    DatabaseURL string
+    JWTSecret   []byte
+}
+
+func Load() (*Config, error) {
+    return &Config{
+        DatabaseURL: os.Getenv("DATABASE_URL"),
+        JWTSecret:   []byte(os.Getenv("JWT_SECRET")),
+    }, nil
+}
+```
+
+---
+
+## Testes
+
+```go
+// Service unit
+func TestRegisterUser_DuplicateEmail(t *testing.T) {
+    repo := &mocks.UserRepository{}
+    repo.On("ExistsByEmail", mock.Anything, "jane@example.com").Return(true, nil)
+    svc := services.NewRegisterUser(repo)
+    _, err := svc.Execute(ctx, services.RegisterUserInput{Email: "jane@example.com"})
+    assert.ErrorIs(t, err, domain.ErrUserAlreadyExists)
+}
+
+// Handler via httptest
+func TestUserHandler_Create(t *testing.T) {
+    r := gin.New()
+    r.POST("/users", h.Create)
+    body := `{"email":"jane@example.com","name":"Jane","password":"longsecret123"}`
+    req := httptest.NewRequest("POST", "/users", strings.NewReader(body))
+    req.Header.Set("Content-Type", "application/json")
+    w := httptest.NewRecorder()
+    r.ServeHTTP(w, req)
+    assert.Equal(t, http.StatusCreated, w.Code)
+}
+```
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | `database/sql` no handler | Repository + sqlc |
+| AP-02 | Validação manual | `binding:` tags + validator |
+| AP-03 | Lógica no handler | Service |
+| AP-04 | Retornar `db.User` direto | `UserResponse` DTO |
+| AP-05 | Secret hardcoded | `os.Getenv` ou viper |
+| AP-06 | Sem rate limit em login | middleware |
+| AP-07 | `panic` em handler | recovery middleware |
+| AP-08 | Context não propagado | sempre `ctx context.Context` |
+| AP-09 | SQL com `fmt.Sprintf` | sqlc / parametrizado |
+| AP-10 | `errors.New` espalhado | sentinela em `domain/errors.go` |
+
+---
+
+## Segurança
+
+- Senhas: `argon2.IDKey` (`golang.org/x/crypto/argon2`)
+- JWT: HS256 secret ≥ 32 bytes, ou RS256 par de chaves
+- Headers: `secure` middleware
+- CORS: `github.com/gin-contrib/cors` com origens específicas
+- Rate limit em login (5/15min)
+
+---
+
+## CI
+
+```bash
+go vet ./...
+golangci-lint run
+go test ./... -race -cover
+govulncheck ./...
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Endpoints REST com método/path/auth
+- Schemas de input/output
+- Erros sentinela esperados
+
+### Blueprint
+- Estrutura `internal/{handlers,services,repositories,domain}`
+- `sqlc.yaml` configurado
+- Migrations `golang-migrate`
+
+### Tasks
+- Por feature: 5 tasks (Migration, sqlc query, Repository, Service, Handler+DTO)
+- Task de configuração middleware + swag + golangci-lint
+
+### Execute
+- Ralph Loop:
+  ```bash
+  go vet ./... && golangci-lint run && go test ./... -race && govulncheck ./...
+  ```
+
+---
+
+## Checklist final
+
+- [ ] Go 1.22+, golangci-lint configurado
+- [ ] sqlc gerando queries a partir de SQL
+- [ ] Handlers magros (apenas bind + chamada Service)
+- [ ] Services com `ctx context.Context` como 1º param
+- [ ] Erros sentinela em `domain/errors.go`
+- [ ] DTOs com `binding:` tags
+- [ ] JWT secret via env
+- [ ] Rate limit em login
+- [ ] OpenAPI gerado em `docs/swagger.json`
+- [ ] Cobertura ≥ 70%
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.

package/templates/ide/cursor/.cursor/rules/skill-layered-design.mdc

@@ -0,0 +1,266 @@
+---
+description: Layered Design — enforce arquitetura estrita Handler→Service→Repository→Model em todos os projetos DARE, independente de linguagem. Inspirado em "Layered Design for Ruby on Rails Applications" de Vladimir Dementyev (Evil Martians).
+globs: **/*.rb,**/*.php,**/*.py,**/*.ts,**/*.tsx,**/*.js,**/*.rs,**/*.go,DARE/BLUEPRINT.md,DARE/DESIGN.md
+alwaysApply: false
+---
+
+# Skill: Layered Design DARE
+
+Você é um arquiteto de software especialista em **Layered Design**. Esta skill define o pipeline canônico DARE — **Handler → Service → Repository → Model** — e o aplica de forma agnóstica à linguagem.
+
+## Por que Layered Design
+
+Em projetos legados, o problema **#1** não é falta de testes — é mistura de camadas. Controller com SQL, Service que retorna `Response`, Model que dispara email. Resultado: nada é testável sem subir o framework inteiro.
+
+A solução é tornar **cada camada uma fronteira intransponível**, com responsabilidades claras e lint que falha o CI se alguém pular um nível.
+
+---
+
+## As 4 camadas
+
+```
+┌────────────────────────────────────────────┐
+│  Handler  (HTTP, gRPC, CLI, queue worker)  │  ← entrada
+└────────────────────────────────────────────┘
+                  ↓ chama
+┌────────────────────────────────────────────┐
+│  Service  (1 operação de negócio)          │  ← coração
+└────────────────────────────────────────────┘
+                  ↓ usa
+┌────────────────────────────────────────────┐
+│  Repository  (acesso a dados)              │  ← I/O
+└────────────────────────────────────────────┘
+                  ↓ retorna
+┌────────────────────────────────────────────┐
+│  Model  (entidade do domínio)              │  ← núcleo
+└────────────────────────────────────────────┘
+```
+
+### Handler — responsabilidades
+
+| Faz | Não faz |
+|---|---|
+| Recebe request (HTTP/gRPC/CLI/queue) | Acessa Repository direto |
+| Valida input (FormRequest/Pydantic/Zod/serde) | Contém lógica de negócio |
+| Chama **um** Service | Faz SQL ou query inline |
+| Formata e retorna response | Instancia Service com `new` (use injeção) |
+
+### Service — responsabilidades
+
+| Faz | Não faz |
+|---|---|
+| Implementa **uma** operação (`RegisterUser`) | Conhece HTTP (status, headers) |
+| Orquestra Repositories | Conhece framework web |
+| Valida regras de negócio | Faz SQL inline |
+| Lança exceções de domínio (`UserAlreadyExists`) | É uma God Class com 30 métodos |
+
+### Repository — responsabilidades
+
+| Faz | Não faz |
+|---|---|
+| Abstrai persistência (DB, cache, API externa) | Retorna HTTP status code |
+| Retorna Model ou primitivo | Lança exceções de domínio (retorna `Option`/`null`) |
+| Esconde SQL/HTTP externo | Contém regra de negócio |
+
+### Model — responsabilidades
+
+| Faz | Não faz |
+|---|---|
+| Representa entidade do domínio | Conhece HTTP/DB/framework |
+| Carrega invariantes (`Email` válido, `Money` ≥ 0) | Importa de Service/Repository/Handler |
+
+---
+
+## Métricas (todas verificáveis em CI)
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% dos Services têm teste unitário (sem DB/HTTP real) | linter checa diretório `tests/services/` |
+| M-02 | 0% de chamadas Handler→Repository diretas | grep AST nos controllers |
+| M-03 | 100% dos Handlers usam injeção (sem `new Service()` inline) | grep nos controllers |
+| M-04 | 100% dos Repositories são agnósticos (não retornam HTTP status) | grep nos repositories |
+
+---
+
+## Antipatterns (CI falha se aparecer)
+
+| AP | Antipattern | Sinal | Correção |
+|---|---|---|---|
+| AP-01 | Handler→Repository direto | `controller.repo.find()` | Criar Service entre eles |
+| AP-02 | Service com SQL inline | `db.query("SELECT…")` em Service | Mover para Repository |
+| AP-03 | Repository lança exceção de domínio | `throw UserNotFound` em Repo | Retornar `null`/`Option`/`Maybe` |
+| AP-04 | Model importa Service | `Model.payment_service` | Refatorar — Service usa Model, não o inverso |
+| AP-05 | God Service (>20 métodos) | `UserService` com tudo | Quebrar em `RegisterUser`, `ResetPassword`, … |
+| AP-06 | Fat Controller (>100 linhas) | controller monstro | Mover lógica para Service |
+
+---
+
+## Tradução por linguagem/framework
+
+| Camada DARE | Laravel | NestJS | FastAPI | Rails | Rust/Axum | Go/Gin |
+|---|---|---|---|---|---|---|
+| Handler | `Http/Controllers/` | `*.controller.ts` | `routers/*.py` | `app/controllers/` | `handlers/*.rs` | `handlers/*.go` |
+| Service | `Services/` | `*.service.ts` | `services/*.py` | `app/services/` | `services/*.rs` | `services/*.go` |
+| Repository | `Repositories/` | `*.repository.ts` | `repositories/*.py` | `app/repositories/` | `repositories/*.rs` | `repositories/*.go` |
+| Model | `Models/` | `entities/*.ts` | `models/*.py` | `app/models/` | `domain/*.rs` | `models/*.go` |
+| Presenter (opcional) | `Resources/` | `dto/` | `schemas/` | `app/serializers/` | `presenters/*.rs` | `dto/*.go` |
+
+---
+
+## Exemplos por stack
+
+### Laravel
+
+```php
+// Handler
+class UserController {
+    public function __construct(private RegisterUser $service) {}
+
+    public function store(StoreUserRequest $req) {
+        $user = $this->service->execute($req->validated());
+        return new UserResource($user);
+    }
+}
+
+// Service
+class RegisterUser {
+    public function __construct(private UserRepository $repo) {}
+    public function execute(array $data): User {
+        if ($this->repo->existsByEmail($data['email'])) {
+            throw new UserAlreadyExistsException();
+        }
+        return $this->repo->create($data);
+    }
+}
+
+// Repository
+class UserRepository {
+    public function existsByEmail(string $email): bool { ... }
+    public function create(array $data): User { ... }
+}
+```
+
+### NestJS
+
+```typescript
+@Controller('users')
+export class UsersController {
+  constructor(private register: RegisterUser) {}
+
+  @Post()
+  async store(@Body() dto: CreateUserDto) {
+    return this.register.execute(dto);
+  }
+}
+
+@Injectable()
+export class RegisterUser {
+  constructor(private repo: UserRepository) {}
+
+  async execute(dto: CreateUserDto): Promise<User> {
+    if (await this.repo.existsByEmail(dto.email)) {
+      throw new UserAlreadyExistsError();
+    }
+    return this.repo.create(dto);
+  }
+}
+```
+
+### FastAPI
+
+```python
+# Handler
+@router.post("/users")
+async def store(payload: UserIn, service: RegisterUser = Depends()):
+    return await service.execute(payload)
+
+# Service
+class RegisterUser:
+    def __init__(self, repo: UserRepository = Depends()):
+        self.repo = repo
+    async def execute(self, payload: UserIn) -> User:
+        if await self.repo.exists_by_email(payload.email):
+            raise UserAlreadyExistsError()
+        return await self.repo.create(payload)
+```
+
+### Rust/Axum
+
+```rust
+// Handler
+async fn create_user(
+    State(svc): State<Arc<RegisterUser>>,
+    Json(input): Json<CreateUser>,
+) -> Result<Json<User>, AppError> {
+    let user = svc.execute(input).await?;
+    Ok(Json(user))
+}
+
+// Service
+pub struct RegisterUser {
+    repo: Arc<dyn UserRepository>,
+}
+impl RegisterUser {
+    pub async fn execute(&self, input: CreateUser) -> Result<User, DomainError> {
+        if self.repo.exists_by_email(&input.email).await? {
+            return Err(DomainError::UserAlreadyExists);
+        }
+        self.repo.create(input).await
+    }
+}
+```
+
+---
+
+## Cobertura de testes
+
+**Service = teste unitário rápido (mock do Repository):**
+
+```typescript
+describe('RegisterUser', () => {
+  it('falha se email já existe', async () => {
+    const repo = { existsByEmail: jest.fn().mockResolvedValue(true) };
+    const sut = new RegisterUser(repo as any);
+    await expect(sut.execute({email: 'x@y.com'})).rejects.toThrow();
+  });
+});
+```
+
+**Repository = teste de integração (subir Postgres real ou usar testcontainers).**
+
+**Handler = teste E2E HTTP (`supertest`, `httpx`, `reqwest`).**
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+
+DESIGN.md deve listar bounded contexts → cada um vira pasta de Services.
+
+### Blueprint
+
+BLUEPRINT.md deve ter diagrama das camadas com setas explícitas (Handler→Service→Repository→Model).
+
+### Tasks
+
+Cada feature gera 4 tasks mínimas: criar Model, criar Repository, criar Service (com teste unitário), criar Handler.
+
+### Execute
+
+Ralph Loop falha se grep detectar AP-01 a AP-06.
+
+---
+
+## Checklist final
+
+- [ ] Pastas mapeadas para as 4 camadas
+- [ ] Lint AP-01 a AP-06 no CI
+- [ ] Services 100% testados unitariamente (sem DB)
+- [ ] Repositories testados via integração (testcontainers)
+- [ ] Handlers magros (< 50 linhas)
+- [ ] Models sem dependência de framework
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.