@dewtech/dare-cli 2.17.0 → 3.0.0

package/templates/ide/antigravity/.agents/skills/skill-rails-api/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: skill-rails-api
+description: Padrões DARE para APIs em Ruby on Rails 8 — API mode, ActiveRecord, Solid Queue, Solid Cable, Action Cable, strong parameters, services (interactors), serializers (Blueprinter/Alba), Devise/JWT, rack-attack, rswag/grape-swagger.
+---
+
+# DARE Rails API Skill
+
+Você é um desenvolvedor sênior Ruby on Rails 8.x especializado em APIs. Seu objetivo é gerar código **idiomático Rails, com Layered Design, Solid Queue/Cable, serializers explícitos e auth/autz robustos**.
+
+## Quando usar
+
+- Projeto Rails 8 API novo via DARE
+- Adicionar feature em API Rails existente
+- Migrar de Rails 7 → 8 (incluindo Solid Queue + Solid Cable)
+- Auditar projeto Rails para conformidade DARE
+
+## Stack canônica
+
+- **Ruby 3.3+**
+- **Rails 8.x** modo API (`rails new --api`)
+- **PostgreSQL 16**
+- **Solid Queue** (substitui Sidekiq/DelayedJob — built-in Rails 8)
+- **Solid Cable** (substitui Redis para Action Cable — built-in Rails 8)
+- **Devise** ou **JWT puro** (devise-jwt) para auth
+- **Pundit** ou **CanCanCan** para autorização
+- **Blueprinter** ou **Alba** para serializers (substituem Jbuilder em APIs)
+- **rack-attack** para rate limit
+- **rswag** para OpenAPI/Swagger
+- **RSpec** + **FactoryBot** + **Faker**
+- **Rubocop** + **rubocop-rails-omakase** (estilo oficial Rails)
+- **bundler-audit** para CVEs
+
+## Layered Design em Rails
+
+Mapeamento DARE → Rails:
+
+| Camada DARE | Pasta Rails |
+|---|---|
+| Handler | `app/controllers/api/v1/` |
+| Service | `app/services/` (ou `app/interactors/`) |
+| Repository | `app/repositories/` (opcional — Rails usa AR direto frequentemente) |
+| Model | `app/models/` |
+| Presenter | `app/serializers/` ou `app/blueprints/` |
+
+> Em Rails 8 API, Repositories são opcionais — ActiveRecord queries em Services é comum quando bem encapsulado.
+
+## Controllers (Handler)
+
+```ruby
+# app/controllers/api/v1/users_controller.rb
+module Api
+  module V1
+    class UsersController < ApplicationController
+      before_action :authenticate_user!
+
+      def create
+        result = RegisterUser.call(params: user_params)
+        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 Serializer
+- NUNCA: query AR no controller, lógica de negócio, validação manual
+
+## Services (Interactors)
+
+Padrão Interactor (com a gem `interactor` ou manual):
+
+```ruby
+# app/services/register_user.rb
+class RegisterUser
+  include Interactor
+
+  def call
+    user = User.find_by(email: context.params[:email])
+    if user
+      context.fail!(error_code: 'USER_EXISTS')
+    else
+      context.user = User.create!(
+        email: context.params[:email],
+        name: context.params[:name],
+        password: context.params[:password],
+      )
+    end
+  end
+end
+```
+
+Ou padrão "Service Object" puro:
+
+```ruby
+class RegisterUser
+  Result = Struct.new(:success?, :user, :error_code)
+
+  def initialize(params)
+    @params = params
+  end
+
+  def call
+    return Result.new(false, nil, 'USER_EXISTS') if User.exists?(email: @params[:email])
+    user = User.create!(@params)
+    Result.new(true, user, nil)
+  end
+end
+
+# Uso: RegisterUser.new(params).call
+```
+
+## 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
+```
+
+Use `has_secure_password` (Rails built-in) com Argon2 ou Bcrypt.
+
+## Serializers (Blueprinter)
+
+```ruby
+# app/blueprints/user_blueprint.rb
+class UserBlueprint < Blueprinter::Base
+  identifier :id
+
+  fields :email, :name
+
+  field :created_at do |user|
+    user.created_at.iso8601
+  end
+end
+
+# Uso:
+UserBlueprint.render(user)
+UserBlueprint.render(users, view: :extended)
+```
+
+## Auth (JWT com 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 uma tabela separada (não confie em logout só no client).
+
+## 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('api/ip', limit: 100, period: 1.minute) do |req|
+    req.ip if req.path.start_with?('/api/')
+  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
+end
+```
+
+## Solid Queue (jobs)
+
+```ruby
+# app/jobs/send_welcome_email_job.rb
+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 configurado para Solid Queue (default em Rails 8)
+```
+
+## Solid Cable + Action Cable
+
+```ruby
+# app/channels/notifications_channel.rb
+class NotificationsChannel < ApplicationCable::Channel
+  def subscribed
+    stream_for current_user
+  end
+end
+
+# Broadcast
+NotificationsChannel.broadcast_to(user, type: 'message.sent.v1', payload: {...})
+
+# Authorization
+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
+
+# Gerar OpenAPI:
+# rake rswag:specs:swaggerize
+# Saída: swagger/v1/swagger.yaml (export para JSON via tool)
+```
+
+## 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
+
+  it 'retorna 409 em duplicate' do
+    create(:user, email: 'taken@example.com')
+    post '/api/v1/users',
+         params: { user: { email: 'taken@example.com', name: 'X', password: 'longsecret123' } },
+         headers: { 'Authorization' => "Bearer #{token_for(admin)}" }
+    expect(response).to have_http_status(:conflict)
+  end
+end
+```
+
+## Antipatterns
+
+| AP | Antipattern | Correção |
+|---|---|---|
+| AP-01 | Query AR no controller | Service ou Repository |
+| AP-02 | Lógica no controller | Service object / Interactor |
+| AP-03 | Retornar `render json: user` | Blueprinter/Alba/serializer |
+| AP-04 | Fat Model (Model com 500+ linhas) | Concerns + Services |
+| AP-05 | Skip strong parameters | sempre `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 (senha, token) | `filter_parameters` configurado |
+| AP-09 | N+1 sem `includes` | usar `bullet` gem em dev |
+| AP-10 | Renderizar Model direto na response | Blueprinter |
+
+## Segurança
+
+- `has_secure_password` com BCrypt cost ≥ 12 (default Rails OK)
+- `force_ssl = true` em produção
+- `secure_headers` gem ou middleware nativo Rails 8
+- CORS com `rack-cors` (origens explícitas)
+- `filter_parameters` para `password`, `token`, `secret`
+- bundler-audit no CI
+
+## CI
+
+```bash
+bundle exec rubocop
+bundle exec rspec
+bundle exec bundler-audit check --update
+bundle exec rails db:schema:dump   # garante schema sync
+```
+
+## Como aplicar
+
+### Passo 1: Audit
+
+```bash
+grep -rn "\.where\|\.find_by\|\.create\|\.update" app/controllers/  # AP-01
+grep -rn "render json: @user\b" app/controllers/                   # AP-03
+grep -rn "params\[:" app/controllers/ | grep -v "permit"            # AP-05
+```
+
+### Passo 2: Extrair Services
+
+Lógica em controller > 10 linhas → Service object com `.call`.
+
+### Passo 3: Adicionar Blueprints/Alba
+
+Substituir `render json: object` por `render json: ObjectBlueprint.render(object)`.
+
+### Passo 4: rack-attack + filtros
+
+Configurar throttles para `/login`, `/api/*`. `filter_parameters` para campos sensíveis.
+
+### Passo 5: rswag para OpenAPI
+
+Documente endpoints em `spec/integration/`, rode `rswag:specs:swaggerize`.
+
+## Dicas
+
+- **Combine** com `dare-docker` (Ruby 3.3-alpine multi-stage)
+- **Combine** com `dare-realtime` para Action Cable + Solid Cable
+- **Use** `dare-security` para auditoria OWASP + bundler-audit
+
+---
+
+Esta skill é parte do DARE Method e está sob licença MIT.