@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/ide/cursor/.cursor/rules/skill-rails-api.mdc

@@ -0,0 +1,400 @@
+---
+description: Padrões DARE para APIs em Ruby on Rails 8 — API mode, ActiveRecord, Solid Queue, Solid Cable, Action Cable, strong parameters, services, serializers (Blueprinter/Alba), Devise/JWT, rack-attack, rswag/grape-swagger.
+globs: **/*.rb,Gemfile,Gemfile.lock,config/**/*.rb,db/**/*.rb,spec/**/*.rb,app/**/*.rb
+alwaysApply: false
+---
+
+# Skill: Rails 8 API DARE
+
+Você é um desenvolvedor sênior Ruby on Rails 8.x especializado em APIs. Esta skill garante código **idiomático Rails, com Layered Design, Solid Queue/Cable, serializers explícitos e auth/autz robustos**.
+
+## Stack canônica
+
+- **Ruby 3.3+**
+- **Rails 8.x** modo API (`rails new --api`)
+- **PostgreSQL 16**
+- **Solid Queue** — substitui Sidekiq, built-in Rails 8
+- **Solid Cable** — substitui Redis para Action Cable, built-in Rails 8
+- **Devise + devise-jwt** ou JWT puro
+- **Pundit** ou **CanCanCan**
+- **Blueprinter** ou **Alba** para serializers
+- **rack-attack** para rate limit
+- **rswag** para OpenAPI/Swagger
+- **RSpec + FactoryBot + Faker**
+- **Rubocop + rubocop-rails-omakase** (estilo oficial)
+- **bundler-audit**
+
+---
+
+## Layered Design em Rails
+
+| Camada DARE | Pasta Rails |
+|---|---|
+| Handler | `app/controllers/api/v1/` |
+| Service | `app/services/` (ou `app/interactors/`) |
+| Repository | `app/repositories/` (opcional em Rails) |
+| Model | `app/models/` |
+| Presenter | `app/blueprints/` ou `app/serializers/` |
+
+> Em Rails 8 API, Repositories são opcionais — ActiveRecord queries dentro de Services bem encapsulados é aceito.
+
+---
+
+## Controllers
+
+```ruby
+module Api
+  module V1
+    class UsersController < ApplicationController
+      before_action :authenticate_user!
+
+      def create
+        result = RegisterUser.new(user_params).call
+        if result.success?
+          render json: UserBlueprint.render(result.user), status: :created
+        else
+          render json: { error: result.error_code }, status: :conflict
+        end
+      end
+
+      private
+
+      def user_params
+        params.require(:user).permit(:email, :name, :password)
+      end
+    end
+  end
+end
+```
+
+Regras:
+- Apenas: autenticar → strong params → chamar Service → renderizar Blueprint
+- NUNCA: query AR no controller, lógica de negócio
+
+---
+
+## Services (Service Object)
+
+```ruby
+class RegisterUser
+  Result = Struct.new(:success?, :user, :error_code, keyword_init: true)
+
+  def initialize(params)
+    @params = params
+  end
+
+  def call
+    return Result.new(success?: false, error_code: 'USER_EXISTS') if User.exists?(email: @params[:email])
+    user = User.create!(@params)
+    Result.new(success?: true, user: user)
+  end
+end
+```
+
+Alternativa com gem `interactor`:
+
+```ruby
+class RegisterUser
+  include Interactor
+
+  def call
+    context.fail!(error_code: 'USER_EXISTS') if User.exists?(email: context.params[:email])
+    context.user = User.create!(context.params)
+  end
+end
+```
+
+---
+
+## Models
+
+```ruby
+class User < ApplicationRecord
+  has_secure_password
+
+  validates :email, presence: true, uniqueness: true, format: URI::MailTo::EMAIL_REGEXP
+  validates :name, presence: true
+  validates :password, length: { minimum: 12 }, if: :password_required?
+
+  has_many :sessions, dependent: :destroy
+  scope :active, -> { where(deleted_at: nil) }
+end
+```
+
+`has_secure_password` usa BCrypt (default). Para Argon2, troque para gem `argon2` + métodos customizados.
+
+---
+
+## Serializers (Blueprinter)
+
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :id
+  fields :email, :name
+
+  field :created_at do |user|
+    user.created_at.iso8601
+  end
+
+  view :extended do
+    fields :phone, :address
+  end
+end
+
+# Uso:
+UserBlueprint.render(user)
+UserBlueprint.render(users, view: :extended)
+```
+
+---
+
+## Auth (devise-jwt)
+
+```ruby
+# Gemfile
+gem 'devise'
+gem 'devise-jwt'
+
+# config/initializers/devise.rb
+config.jwt do |jwt|
+  jwt.secret = Rails.application.credentials.devise_jwt_secret_key!
+  jwt.dispatch_requests = [['POST', %r{^/api/v1/login$}]]
+  jwt.revocation_requests = [['DELETE', %r{^/api/v1/logout$}]]
+  jwt.expiration_time = 15.minutes.to_i
+end
+```
+
+Refresh token com rotação em tabela própria.
+
+---
+
+## Rate limit (rack-attack)
+
+```ruby
+# config/initializers/rack_attack.rb
+class Rack::Attack
+  throttle('login/ip', limit: 5, period: 15.minutes) do |req|
+    req.ip if req.path == '/api/v1/login' && req.post?
+  end
+
+  throttle('login/email', limit: 5, period: 15.minutes) do |req|
+    if req.path == '/api/v1/login' && req.post?
+      req.params['email'].to_s.downcase.gsub(/\s+/, '')
+    end
+  end
+
+  throttle('api/ip', limit: 100, period: 1.minute) do |req|
+    req.ip if req.path.start_with?('/api/')
+  end
+end
+```
+
+---
+
+## Solid Queue (jobs)
+
+```ruby
+class SendWelcomeEmailJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id)
+    user = User.find(user_id)
+    UserMailer.welcome(user).deliver_now
+  end
+end
+
+# config/queue.yml — Solid Queue default em Rails 8
+```
+
+---
+
+## Solid Cable + Action Cable
+
+```ruby
+class NotificationsChannel < ApplicationCable::Channel
+  def subscribed
+    stream_for current_user
+  end
+end
+
+# Broadcast em qualquer lugar
+NotificationsChannel.broadcast_to(user, type: 'message.sent.v1', payload: {...})
+
+# Connection auth
+class ApplicationCable::Connection < ActionCable::Connection::Base
+  identified_by :current_user
+
+  def connect
+    self.current_user = find_verified_user
+  end
+
+  private
+
+  def find_verified_user
+    if (user = decode_jwt(request.params[:token]))
+      user
+    else
+      reject_unauthorized_connection
+    end
+  end
+end
+```
+
+---
+
+## OpenAPI (rswag)
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem 'rswag-specs'
+end
+
+# spec/integration/users_spec.rb
+require 'swagger_helper'
+
+RSpec.describe 'Users API', type: :request do
+  path '/api/v1/users' do
+    post 'Creates a user' do
+      tags 'Users'
+      consumes 'application/json'
+      parameter name: :user, in: :body, schema: {
+        type: :object,
+        properties: {
+          email: { type: :string },
+          name: { type: :string },
+          password: { type: :string, minLength: 12 },
+        },
+        required: %w[email name password],
+      }
+      response '201', 'user created' do ... end
+      response '409', 'duplicate email' do ... end
+    end
+  end
+end
+
+# rake rswag:specs:swaggerize → swagger/v1/swagger.yaml
+```
+
+Exportar para JSON e expor em `/openapi.json`.
+
+---
+
+## Testes RSpec
+
+```ruby
+# spec/services/register_user_spec.rb
+RSpec.describe RegisterUser do
+  let(:params) { { email: 'jane@example.com', name: 'Jane', password: 'longsecret123' } }
+
+  it 'cria usuário com sucesso' do
+    result = described_class.new(params).call
+    expect(result.success?).to be true
+    expect(result.user.email).to eq 'jane@example.com'
+  end
+
+  it 'falha se email já existe' do
+    User.create!(params)
+    result = described_class.new(params).call
+    expect(result.success?).to be false
+    expect(result.error_code).to eq 'USER_EXISTS'
+  end
+end
+
+# spec/requests/api/v1/users_spec.rb
+RSpec.describe 'POST /api/v1/users', type: :request do
+  let(:admin) { create(:user, :admin) }
+
+  it 'cria com sucesso' do
+    post '/api/v1/users',
+         params: { user: { email: 'jane@example.com', name: 'Jane', password: 'longsecret123' } },
+         headers: { 'Authorization' => "Bearer #{token_for(admin)}" }
+    expect(response).to have_http_status(:created)
+  end
+end
+```
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | Query AR no controller | Service object |
+| AP-02 | Lógica no controller | Service object |
+| AP-03 | `render json: user` | Blueprinter/Alba |
+| AP-04 | Fat Model (>500 linhas) | Concerns + Services |
+| AP-05 | Skip strong params | `params.require(...).permit(...)` |
+| AP-06 | Sem rack-attack em login | rate limit obrigatório |
+| AP-07 | JWT secret em código | `Rails.application.credentials` |
+| AP-08 | Logs com PII | `filter_parameters` configurado |
+| AP-09 | N+1 sem `includes` | `bullet` gem em dev |
+| AP-10 | Sem `--api` no rails new | use modo API |
+
+---
+
+## Segurança
+
+- `has_secure_password` (BCrypt cost ≥ 12)
+- `force_ssl = true` em produção
+- `secure_headers` gem ou middleware nativo Rails 8
+- `rack-cors` com origens específicas
+- `filter_parameters` para `password`, `token`, `secret`, `ssn`
+- bundler-audit no CI
+
+---
+
+## CI
+
+```bash
+bundle exec rubocop
+bundle exec rspec
+bundle exec bundler-audit check --update
+bundle exec rails db:schema:dump
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Listar endpoints REST com tags + métodos
+- Definir strong params por controller
+- Auth strategy (Devise/JWT)
+
+### Blueprint
+- Estrutura `controllers/api/v1/`, `services/`, `blueprints/`
+- Schema do banco (migrations)
+- Strategy de jobs (Solid Queue) e realtime (Solid Cable)
+
+### Tasks
+- Por feature: Migration, Model, Service, Controller, Blueprint, RSpec
+- Task de configuração rack-attack + filter_parameters
+- Task de OpenAPI com rswag
+
+### Execute
+- Ralph Loop:
+  ```bash
+  bundle exec rubocop && bundle exec rspec && bundle exec bundler-audit check
+  ```
+
+---
+
+## Checklist final
+
+- [ ] Ruby 3.3+, Rails 8.x modo API
+- [ ] Rubocop + rails-omakase configurado
+- [ ] Strong parameters em todos os controllers
+- [ ] Lógica em Services (não em controllers)
+- [ ] Blueprinter/Alba (não `render json: object`)
+- [ ] rack-attack para login + APIs públicas
+- [ ] `has_secure_password` (não senha plaintext)
+- [ ] JWT secret via credentials.yml.enc
+- [ ] `filter_parameters` configurado
+- [ ] Solid Queue para jobs (default Rails 8)
+- [ ] OpenAPI exportado via rswag
+- [ ] bundler-audit no CI
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.

package/templates/ide/cursor/.cursor/rules/skill-realtime.mdc

@@ -0,0 +1,262 @@
+---
+description: Comunicação real-time (WebSocket, SSE) DARE-compliant — eventos tipados com JSON Schema, subscriptions autorizadas, reconexão com exponential backoff, e gerenciamento de subscriptions sem ghost listeners.
+globs: **/realtime/**,**/ws/**,**/socket*.ts,**/socket*.py,**/socket*.rs,**/cable/**,**/channels/**
+alwaysApply: false
+---
+
+# Skill: Realtime DARE
+
+Você é um especialista em comunicação real-time (WebSocket, SSE). Esta skill garante que toda integração real-time em projeto DARE seja **tipada, autorizada, reconectável e sem ghost listeners**.
+
+## Arquitetura recomendada
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Event Registry                                          │
+│  - Tipos de evento com schema JSON                       │
+│  - Versionamento (.v1, .v2…)                             │
+│  - Autorização declarada por evento                      │
+└─────────────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────────────┐
+│  Subscription Manager                                    │
+│  - Map<connection_id, Set<event_type>>                   │
+│  - Cleanup garantido on disconnect                       │
+└─────────────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────────────┐
+│  Reconnect Strategy                                      │
+│  - Exponential backoff (1s, 2s, 4s, 8s, max 30s)         │
+│  - Jitter para evitar thundering herd                    │
+│  - Resync de estado após reconectar                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Os 4 pilares
+
+### 1. Schema validation de eventos
+
+Todo evento WS/SSE tem schema JSON declarado:
+
+```typescript
+// src/realtime/event_registry.ts
+import { z } from 'zod';
+
+export const EventRegistry = {
+  'user.created.v1': {
+    schema: z.object({
+      id: z.string().uuid(),
+      email: z.string().email(),
+      createdAt: z.string().datetime(),
+    }),
+    requires: 'admin',
+  },
+  'message.sent.v1': {
+    schema: z.object({
+      conversationId: z.string().uuid(),
+      senderId: z.string().uuid(),
+      body: z.string().max(2000),
+      sentAt: z.string().datetime(),
+    }),
+    requires: 'participant',
+  },
+} as const;
+```
+
+Server valida antes de emitir, client valida antes de processar. Evento inválido = log + drop.
+
+### 2. Registro central de tipos
+
+Um único arquivo `event_registry.ts/py/rs`. Adicionar evento passa por PR explícito. Versionamento via sufixo `.v1`, `.v2`.
+
+### 3. Reconexão com exponential backoff
+
+```typescript
+export class ReconnectStrategy {
+  private attempt = 0;
+  constructor(private base = 1000, private max = 30_000) {}
+
+  next(): number {
+    const delay = Math.min(this.base * 2 ** this.attempt, this.max);
+    const jitter = Math.random() * 1000;
+    this.attempt++;
+    return delay + jitter;
+  }
+
+  reset() { this.attempt = 0; }
+}
+```
+
+Após reconectar, **resync de estado** — buscar eventos perdidos via REST ou pedir snapshot.
+
+### 4. Subscription manager (zero ghost listeners)
+
+```typescript
+export class SubscriptionManager {
+  private subs = new Map<string, Set<string>>();
+
+  subscribe(connId: string, event: string) {
+    if (!this.subs.has(connId)) this.subs.set(connId, new Set());
+    this.subs.get(connId)!.add(event);
+  }
+
+  unsubscribe(connId: string, event: string) {
+    this.subs.get(connId)?.delete(event);
+  }
+
+  // Cleanup SEMPRE on disconnect — sem exceção
+  onDisconnect(connId: string) {
+    this.subs.delete(connId);
+  }
+
+  metrics() {
+    return { connections: this.subs.size, totalSubs: [...this.subs.values()].reduce((s, set) => s + set.size, 0) };
+  }
+}
+```
+
+---
+
+## Métricas (verificáveis em CI/runtime)
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% de event types com JSON Schema | grep no registry — todo evento tem `schema:` |
+| M-02 | 100% de subscriptions autorizadas | grep por `authorize(` antes de `subscribe(` |
+| M-03 | 0 ghost listeners após desconexão | métrica runtime `subs.size === 0` após disconnect |
+| M-04 | Reconnect strategy configurada | grep por `ReconnectStrategy` ou backoff manual |
+
+---
+
+## Antipatterns
+
+| AP | Antipattern | Sinal | Correção |
+|---|---|---|---|
+| AP-01 | Evento sem schema | `socket.emit('foo', anything)` | Adicionar schema no registry |
+| AP-02 | `socket.on(...)` sem cleanup | listener vive após disconnect | Usar SubscriptionManager |
+| AP-03 | Reconexão sem backoff | reconecta imediatamente em loop | Exponential + jitter |
+| AP-04 | Sem autorização de subscription | usuário ouve eventos cross-tenant | `authorize(user, event)` antes de `subscribe()` |
+| AP-05 | Broadcast sem filtro | `io.emit()` para todos | Rooms/channels por tenant |
+| AP-06 | Estado não recuperado | UI mostra dados stale | Resync via REST ou snapshot WS |
+
+---
+
+## Stack recomendada
+
+| Stack | WebSocket | SSE |
+|---|---|---|
+| Node | `socket.io`, `ws` | endpoint custom + `EventSource` no client |
+| Rails | Action Cable + Solid Cable | Rack streaming |
+| Rust/Axum | `tokio-tungstenite`, `axum::extract::ws` | `axum::response::sse::Sse` |
+| FastAPI | `fastapi.WebSocket` | `sse-starlette` (`EventSourceResponse`) |
+| Go | `gorilla/websocket`, `melody` | stdlib `http.Flusher` |
+| NestJS | `@nestjs/websockets` (Socket.io ou ws) | endpoint custom |
+
+---
+
+## Exemplo completo — Socket.io (Node)
+
+```typescript
+// Server
+io.on('connection', (socket) => {
+  socket.on('subscribe', ({ eventType }) => {
+    const entry = EventRegistry[eventType];
+    if (!entry) return socket.emit('error', { code: 'UNKNOWN_EVENT' });
+    if (!authorize(socket.data.user, entry.requires)) {
+      return socket.emit('error', { code: 'FORBIDDEN' });
+    }
+    subMgr.subscribe(socket.id, eventType);
+    socket.join(`event:${eventType}`);
+  });
+
+  socket.on('disconnect', () => {
+    subMgr.onDisconnect(socket.id); // cleanup SEMPRE
+  });
+});
+
+// Quando emitir um evento (de qualquer lugar)
+export function emit<E extends keyof typeof EventRegistry>(eventType: E, payload: unknown) {
+  const entry = EventRegistry[eventType];
+  const valid = entry.schema.safeParse(payload);
+  if (!valid.success) { log.error('invalid event payload', valid.error); return; }
+  io.to(`event:${eventType}`).emit(eventType, valid.data);
+}
+```
+
+```typescript
+// Client
+const socket = io(url);
+const strategy = new ReconnectStrategy();
+
+socket.on('connect', () => {
+  strategy.reset();
+  resyncState();
+});
+
+socket.on('disconnect', () => {
+  setTimeout(() => socket.connect(), strategy.next());
+});
+
+socket.on('message.sent.v1', (payload) => {
+  const valid = EventRegistry['message.sent.v1'].schema.safeParse(payload);
+  if (!valid.success) return log.warn('invalid event received', valid.error);
+  handleMessage(valid.data);
+});
+```
+
+---
+
+## Aplicação por fase DARE
+
+### Design
+- Listar eventos WS/SSE necessários (formato `dominio.acao.vN`)
+- Autorização por evento
+- Estratégia de resync após reconect
+
+### Blueprint
+- Diagrama de event flow
+- Stack escolhida (WS lib + cliente)
+- Backoff configurado (base, max, jitter)
+
+### Tasks
+- Task: criar `event_registry.ts`
+- Task: implementar `SubscriptionManager`
+- Task: implementar `ReconnectStrategy`
+- Task: configurar autorização por evento
+- Task: instrumentar métrica de ghost listeners
+
+### Execute
+- Ralph Loop: grep falha se `socket.on` sem cleanup correspondente
+- Métrica runtime: `subMgr.metrics()` em endpoint `/internal/realtime/stats`
+
+---
+
+## Boas práticas
+
+1. **SSE para server→client unidirecional** — logs, métricas, dashboards
+2. **WebSocket para bidirectional** — chat, colaboração ao vivo
+3. **Heartbeat ping-pong** — detecta conexão zumbi (TCP OK, peer não responde)
+4. **Backpressure** — se client lento, drop eventos antigos para evitar OOM
+5. **Replay limitado** — guardar últimos N eventos por room (não histórico completo)
+6. **Versionar eventos** — `.v1`, `.v2` permite migração gradual
+7. **Logs estruturados** — emitir log por evento com tenant, user, eventType, success/fail
+
+---
+
+## Checklist final
+
+- [ ] `event_registry.ts/py/rs` com todos os event types
+- [ ] Cada evento tem schema JSON validado
+- [ ] Cada evento declara `requires:` (autorização)
+- [ ] `SubscriptionManager` com cleanup on disconnect
+- [ ] `ReconnectStrategy` no client com exponential backoff + jitter
+- [ ] Resync de estado pós-reconect (REST ou snapshot WS)
+- [ ] Validação de payload no server antes de emitir
+- [ ] Validação de payload no client antes de processar
+- [ ] Métrica de ghost listeners em endpoint `/internal/realtime/stats`
+
+---
+
+Skill licenciada MIT — parte do DARE Method v3.