rubyn-code 0.1.0

data/skills/rails/security.md

@@ -0,0 +1,233 @@
+# Rails: Security
+
+## Pattern
+
+Security is not a feature — it's a property of every feature. Rails provides strong defaults, but you must use them correctly. This document covers the critical security practices for every Rails application.
+
+### Strong Parameters (Mass Assignment Protection)
+
+```ruby
+# GOOD: Explicitly permit only expected params
+class OrdersController < ApplicationController
+  private
+
+  def order_params
+    params.require(:order).permit(:shipping_address, :notes,
+      line_items_attributes: [:product_id, :quantity])
+  end
+end
+
+# BAD: Permitting everything
+def order_params
+  params.require(:order).permit!  # NEVER do this
+end
+
+# BAD: Permitting role or admin fields
+def user_params
+  params.require(:user).permit(:name, :email, :role, :admin)  # User can make themselves admin!
+end
+
+# GOOD: Separate param sets for different contexts
+def user_params
+  params.require(:user).permit(:name, :email)
+end
+
+def admin_user_params
+  params.require(:user).permit(:name, :email, :role, :admin)  # Only in admin controllers
+end
+```
+
+### SQL Injection Prevention
+
+```ruby
+# GOOD: Parameterized queries (Rails does this by default)
+User.where(email: params[:email])
+User.where("email = ?", params[:email])
+User.where("email = :email", email: params[:email])
+Order.where(status: params[:status], user_id: current_user.id)
+
+# BAD: String interpolation in SQL
+User.where("email = '#{params[:email]}'")         # SQL injection!
+Order.where("status = #{params[:status]}")          # SQL injection!
+User.order("#{params[:sort_column]} #{params[:sort_direction]}")  # SQL injection!
+
+# GOOD: Safe column sorting
+ALLOWED_SORT_COLUMNS = %w[created_at total status].freeze
+ALLOWED_DIRECTIONS = %w[asc desc].freeze
+
+def safe_order(scope)
+  column = ALLOWED_SORT_COLUMNS.include?(params[:sort]) ? params[:sort] : "created_at"
+  direction = ALLOWED_DIRECTIONS.include?(params[:dir]) ? params[:dir] : "desc"
+  scope.order(column => direction)
+end
+```
+
+### XSS (Cross-Site Scripting) Prevention
+
+```ruby
+# GOOD: Rails auto-escapes by default in ERB
+<%= user.name %>  <%# Automatically escaped — safe %>
+
+# BAD: raw/html_safe bypasses escaping
+<%= raw user.bio %>          # If bio contains <script>, it executes!
+<%= user.bio.html_safe %>    # Same vulnerability
+
+# GOOD: When you need HTML, sanitize it
+<%= sanitize user.bio, tags: %w[p br strong em a], attributes: %w[href] %>
+
+# GOOD: JSON in script tags (Rails 7+)
+<script>
+  const data = <%= raw json_escape(data.to_json) %>;
+</script>
+
+# Or better — use data attributes
+<div data-order="<%= order.to_json %>">
+```
+
+### CSRF Protection
+
+```ruby
+# Rails includes CSRF protection by default for HTML forms
+class ApplicationController < ActionController::Base
+  protect_from_forgery with: :exception
+end
+
+# API controllers skip CSRF (they use token auth instead)
+class Api::BaseController < ActionController::API
+  # No CSRF — API uses Bearer token authentication
+end
+```
+
+### Authentication Security
+
+```ruby
+# GOOD: Secure API key storage — hash the key, store the hash
+class ApiKey < ApplicationRecord
+  before_create :generate_key_pair
+
+  # Store only the hash — never the raw key
+  def self.find_by_token(raw_token)
+    hashed = Digest::SHA256.hexdigest(raw_token)
+    find_by(key_hash: hashed, revoked_at: nil)
+  end
+
+  private
+
+  def generate_key_pair
+    raw_key = SecureRandom.urlsafe_base64(32)
+    self.key_hash = Digest::SHA256.hexdigest(raw_key)
+    self.key_prefix = raw_key[0..7]  # For identification in UI
+
+    # Return the raw key ONCE — it's never stored
+    @raw_key = raw_key
+  end
+end
+
+# GOOD: Constant-time comparison to prevent timing attacks
+def authenticate_token(provided_token)
+  expected_hash = Digest::SHA256.hexdigest(provided_token)
+  api_key = ApiKey.find_by(key_prefix: provided_token[0..7])
+  return nil unless api_key
+
+  # Constant-time comparison
+  ActiveSupport::SecurityUtils.secure_compare(api_key.key_hash, expected_hash) ? api_key : nil
+end
+
+# GOOD: Password requirements with Devise
+class User < ApplicationRecord
+  devise :database_authenticatable, :registerable,
+         :recoverable, :rememberable, :validatable,
+         :lockable, :trackable
+
+  validates :password, length: { minimum: 8 }, if: :password_required?
+end
+```
+
+### Authorization (Scoping Queries)
+
+```ruby
+# GOOD: Always scope queries to the current user
+class OrdersController < ApplicationController
+  def show
+    @order = current_user.orders.find(params[:id])
+    # If the order doesn't belong to current_user, raises RecordNotFound (404)
+  end
+
+  def index
+    @orders = current_user.orders.recent
+    # Never see other users' orders
+  end
+end
+
+# BAD: Global lookup — any user can access any order
+class OrdersController < ApplicationController
+  def show
+    @order = Order.find(params[:id])  # IDOR vulnerability!
+  end
+end
+```
+
+### Secrets Management
+
+```ruby
+# GOOD: Use Rails credentials
+# Edit: rails credentials:edit
+# Access:
+Rails.application.credentials.anthropic_api_key
+Rails.application.credentials.dig(:database, :password)
+
+# GOOD: Environment variables for deployment
+ENV.fetch("ANTHROPIC_API_KEY")  # Fails loudly if missing
+ENV["OPTIONAL_KEY"]             # Returns nil if missing
+
+# BAD: Secrets in code
+ANTHROPIC_API_KEY = "sk-ant-abc123..."  # NEVER commit secrets
+
+# BAD: Secrets in database seeds
+User.create!(api_key: "real-production-key")
+```
+
+### Content Security Policy
+
+```ruby
+# config/initializers/content_security_policy.rb
+Rails.application.configure do
+  config.content_security_policy do |policy|
+    policy.default_src :self
+    policy.font_src    :self, "https://fonts.googleapis.com"
+    policy.img_src     :self, :data, "https://gravatar.com"
+    policy.script_src  :self
+    policy.style_src   :self, :unsafe_inline  # Required for some frameworks
+    policy.connect_src :self
+  end
+
+  config.content_security_policy_nonce_generator = ->(request) { request.session.id.to_s }
+  config.content_security_policy_nonce_directives = %w[script-src]
+end
+```
+
+### Rate Limiting (Rails 8+)
+
+```ruby
+class Api::V1::AiController < Api::V1::BaseController
+  rate_limit to: 20, within: 1.minute, by: -> { current_user.id }, with: -> {
+    render json: { error: "Rate limited. Try again in a moment." }, status: :too_many_requests
+  }
+end
+```
+
+## Security Checklist
+
+Every Rails app should verify:
+
+- [ ] Strong parameters on every controller action
+- [ ] No string interpolation in SQL queries
+- [ ] No `raw` or `html_safe` on user input
+- [ ] CSRF protection enabled for web controllers
+- [ ] API authentication via tokens (not cookies)
+- [ ] All queries scoped to `current_user` (no IDOR)
+- [ ] Secrets in credentials or ENV, never in code
+- [ ] `force_ssl` enabled in production
+- [ ] Dependencies updated regularly (`bundle audit`)
+- [ ] Rate limiting on expensive endpoints
+- [ ] CSP headers configured

data/skills/rails/serializers.md

@@ -0,0 +1,243 @@
+# Rails: Serializers
+
+## Pattern
+
+Serializers control the exact shape of your JSON API responses. They decouple the API surface from the database schema, prevent accidental exposure of internal fields, and provide a single place to manage field inclusion, formatting, and nested associations.
+
+### Manual Serializer (Simplest, No Gems)
+
+```ruby
+# app/serializers/order_serializer.rb
+class OrderSerializer
+  def initialize(order)
+    @order = order
+  end
+
+  def as_json(*)
+    {
+      id: @order.id,
+      reference: @order.reference,
+      status: @order.status,
+      total_cents: @order.total,
+      total_formatted: format_currency(@order.total),
+      shipping_address: @order.shipping_address,
+      line_items: serialize_line_items,
+      created_at: @order.created_at.iso8601,
+      updated_at: @order.updated_at.iso8601
+    }
+  end
+
+  private
+
+  def serialize_line_items
+    @order.line_items.map do |item|
+      {
+        id: item.id,
+        product_name: item.product.name,
+        quantity: item.quantity,
+        unit_price_cents: item.unit_price,
+        total_cents: item.quantity * item.unit_price
+      }
+    end
+  end
+
+  def format_currency(cents)
+    "$#{format('%.2f', cents / 100.0)}"
+  end
+end
+
+# Controller usage
+class Api::V1::OrdersController < Api::V1::BaseController
+  def show
+    order = current_user.orders.includes(line_items: :product).find(params[:id])
+    render json: { order: OrderSerializer.new(order).as_json }
+  end
+
+  def index
+    orders = current_user.orders.includes(line_items: :product).recent
+    render json: {
+      orders: orders.map { |o| OrderSerializer.new(o).as_json },
+      meta: pagination_meta(orders)
+    }
+  end
+end
+```
+
+### Collection Serializer Helper
+
+```ruby
+# app/serializers/base_serializer.rb
+class BaseSerializer
+  def initialize(object)
+    @object = object
+  end
+
+  def as_json(*)
+    raise NotImplementedError
+  end
+
+  # Class method for serializing collections
+  def self.collection(objects)
+    objects.map { |obj| new(obj).as_json }
+  end
+end
+
+class OrderSerializer < BaseSerializer
+  def as_json(*)
+    {
+      id: @object.id,
+      reference: @object.reference,
+      status: @object.status,
+      total_cents: @object.total,
+      created_at: @object.created_at.iso8601
+    }
+  end
+end
+
+# Usage
+render json: { orders: OrderSerializer.collection(orders) }
+```
+
+### Conditional Fields and Includes
+
+```ruby
+class OrderSerializer
+  def initialize(order, includes: [])
+    @order = order
+    @includes = includes.map(&:to_sym)
+  end
+
+  def as_json(*)
+    data = {
+      id: @order.id,
+      reference: @order.reference,
+      status: @order.status,
+      total_cents: @order.total,
+      created_at: @order.created_at.iso8601
+    }
+
+    data[:line_items] = serialize_line_items if include?(:line_items)
+    data[:user] = serialize_user if include?(:user)
+    data[:shipment] = serialize_shipment if include?(:shipment)
+
+    data
+  end
+
+  private
+
+  def include?(association)
+    @includes.include?(association)
+  end
+
+  def serialize_line_items
+    @order.line_items.map { |li| LineItemSerializer.new(li).as_json }
+  end
+
+  def serialize_user
+    UserSerializer.new(@order.user).as_json
+  end
+
+  def serialize_shipment
+    return nil unless @order.shipment
+    ShipmentSerializer.new(@order.shipment).as_json
+  end
+end
+
+# Controller — caller decides what to include
+def show
+  order = current_user.orders.find(params[:id])
+  includes = (params[:include] || "").split(",").map(&:strip)
+
+  # Preload only what's requested
+  order = preload_includes(order, includes)
+
+  render json: { order: OrderSerializer.new(order, includes: includes).as_json }
+end
+```
+
+### Jbuilder (Rails Built-In)
+
+```ruby
+# app/views/api/v1/orders/show.json.jbuilder
+json.order do
+  json.id @order.id
+  json.reference @order.reference
+  json.status @order.status
+  json.total_cents @order.total
+  json.total_formatted number_to_currency(@order.total / 100.0)
+  json.created_at @order.created_at.iso8601
+
+  json.line_items @order.line_items do |item|
+    json.id item.id
+    json.product_name item.product.name
+    json.quantity item.quantity
+    json.unit_price_cents item.unit_price
+  end
+end
+
+# app/views/api/v1/orders/index.json.jbuilder
+json.orders @orders do |order|
+  json.partial! "api/v1/orders/order", order: order
+end
+json.meta do
+  json.total_count @orders.total_count
+  json.current_page @orders.current_page
+end
+```
+
+## Why This Is Good
+
+- **API surface is explicit.** The serializer lists every field the API returns. Adding or removing a field is a one-line change in one file.
+- **No accidental exposure.** `render json: @order` would expose `password_digest`, `internal_notes`, `api_cost_usd`, and every other column. Serializers whitelist only the fields clients should see.
+- **Formatting is centralized.** Dates are always ISO8601, money is always in cents with a formatted version, statuses are always lowercase. Clients get consistent data shapes.
+- **Nested associations are controlled.** You decide how deep the nesting goes. Clients can request includes, but you control what's available.
+- **Testable.** `OrderSerializer.new(order).as_json` returns a hash you can assert on without HTTP.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Rendering the model directly
+render json: @order
+# Exposes EVERYTHING: password_digest, internal_notes, admin fields, timestamps you don't want
+
+# BAD: Inline hash construction in the controller
+render json: {
+  id: @order.id,
+  ref: @order.reference,  # Inconsistent naming
+  total: "$#{@order.total / 100.0}",  # Formatting in controller
+  items: @order.line_items.map { |li| { name: li.product.name, qty: li.quantity } }
+}
+# Repeated in every controller, inconsistent across endpoints
+
+# BAD: as_json override on the model
+class Order < ApplicationRecord
+  def as_json(options = {})
+    super(only: [:id, :reference, :status, :total], include: { line_items: { only: [:id, :quantity] } })
+  end
+end
+# Now EVERY json render uses this shape — can't have different shapes for different endpoints
+```
+
+## When To Apply
+
+- **Every JSON API endpoint.** No exceptions. Even a simple `{ id: 1, name: "test" }` should go through a serializer once you have more than 2 API endpoints.
+- **When different endpoints need different shapes.** A list endpoint shows `id, reference, status, total`. A detail endpoint adds `line_items, user, shipment`. Serializers with `includes:` handle this cleanly.
+- **When you need versioning.** `Api::V1::OrderSerializer` and `Api::V2::OrderSerializer` can coexist. Can't do that with `as_json` on the model.
+
+## When NOT To Apply
+
+- **HTML-only apps.** Views render HTML directly from models/presenters. Serializers are for JSON APIs.
+- **Single internal endpoint.** A health check returning `{ status: "ok" }` doesn't need a serializer class.
+- **GraphQL.** GraphQL types serve the same purpose as serializers. Don't layer serializers on top of GraphQL.
+
+## Gem Alternatives
+
+| Approach | Pros | Cons |
+|---|---|---|
+| Manual class | Zero dependencies, full control, simplest | More boilerplate for large APIs |
+| Jbuilder | Ships with Rails, template-based | Slower (renders views), harder to test |
+| `jsonapi-serializer` | JSON:API compliant, relationships, sparse fieldsets | Heavy for simple APIs |
+| `alba` | Fast, flexible, modern | Another dependency |
+| `blueprinter` | Declarative DSL, views, associations | Another dependency |
+
+**Recommendation:** Start with manual serializers. They're fast, testable, and dependency-free. Switch to a gem only when you have 20+ serializers and need features like sparse fieldsets or JSON:API compliance.

data/skills/rails/service_objects.md

@@ -0,0 +1,184 @@
+# Rails: Service Object Extraction
+
+## Pattern
+
+Extract business logic from controllers into service objects when the action does more than receive params and persist a single record.
+
+Service objects live in `app/services/`, namespaced by resource. They have a single public class method `.call` that returns a result object.
+
+```ruby
+# app/services/orders/create_service.rb
+module Orders
+  class CreateService
+    def self.call(params, user)
+      new(params, user).call
+    end
+
+    def initialize(params, user)
+      @params = params
+      @user = user
+    end
+
+    def call
+      order = @user.orders.build(@params)
+
+      unless inventory_available?(order)
+        order.errors.add(:base, "Insufficient inventory")
+        return Result.new(success: false, order: order)
+      end
+
+      if order.save
+        send_confirmation(order)
+        notify_warehouse(order)
+        Result.new(success: true, order: order)
+      else
+        Result.new(success: false, order: order)
+      end
+    end
+
+    private
+
+    def inventory_available?(order)
+      order.line_items.all? { |item| item.product.stock >= item.quantity }
+    end
+
+    def send_confirmation(order)
+      OrderMailer.confirmation(order).deliver_later
+    end
+
+    def notify_warehouse(order)
+      WarehouseNotificationJob.perform_later(order.id)
+    end
+
+    Result = Struct.new(:success, :order, keyword_init: true) do
+      alias_method :success?, :success
+    end
+  end
+end
+```
+
+The controller becomes a thin delegation layer:
+
+```ruby
+# app/controllers/orders_controller.rb
+class OrdersController < ApplicationController
+  def create
+    result = Orders::CreateService.call(order_params, current_user)
+
+    if result.success?
+      redirect_to result.order, notice: "Order placed successfully."
+    else
+      @order = result.order
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def order_params
+    params.require(:order).permit(:shipping_address, line_items_attributes: [:product_id, :quantity])
+  end
+end
+```
+
+## Why This Is Good
+
+- **Testable in isolation.** The service object can be tested without routing, request/response cycles, or controller setup. Pass in params and a user, assert the result.
+- **Single responsibility.** The controller handles HTTP concerns (params, redirects, status codes). The service handles business logic (validation, persistence, side effects).
+- **Reusable.** When the same order creation logic is needed from an API endpoint, a Sidekiq job, or a rake task, call the same service. No duplication.
+- **Readable.** A 5-line controller action tells you instantly what happens. The service object's private methods read like a checklist of the business process.
+- **Debuggable.** When order creation breaks, you look at one file — the service. Not a 40-line controller action mixed with HTTP logic.
+
+## Anti-Pattern
+
+A controller action that handles business logic, persistence, mailer calls, and external notifications directly:
+
+```ruby
+# app/controllers/orders_controller.rb
+class OrdersController < ApplicationController
+  def create
+    @order = current_user.orders.build(order_params)
+
+    @order.line_items.each do |item|
+      if item.product.stock < item.quantity
+        @order.errors.add(:base, "#{item.product.name} is out of stock")
+        render :new, status: :unprocessable_entity
+        return
+      end
+    end
+
+    if @order.save
+      @order.line_items.each do |item|
+        item.product.update!(stock: item.product.stock - item.quantity)
+      end
+
+      OrderMailer.confirmation(@order).deliver_later
+
+      payload = { order_id: @order.id, items: @order.line_items.map(&:id) }
+      WarehouseNotificationJob.perform_later(payload.to_json)
+
+      if @order.total > 1000
+        HighValueOrderNotificationJob.perform_later(@order.id)
+      end
+
+      redirect_to @order, notice: "Order placed successfully."
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Untestable without full stack.** Testing this requires building a request, setting up authentication, creating products with stock, and asserting redirects — all to test business logic that has nothing to do with HTTP.
+- **Impossible to reuse.** When you need to create orders from an API controller, you copy-paste this logic. When the logic changes, you update it in two places (or forget one).
+- **Hard to read.** A developer looking at this action has to mentally separate "what's HTTP" from "what's business logic" from "what's side effects." At 30+ lines, that takes real effort.
+- **Fragile.** Stock decrementation, mailer calls, and warehouse notifications are scattered in the controller. Missing one in a new code path causes inventory errors or silent failures.
+- **Violates SRP.** The controller is handling params, validation, persistence, stock management, email, background jobs, and conditional notifications. That's 7 responsibilities in one method.
+
+## When To Apply
+
+Extract to a service object when ANY of these are true:
+
+- The action exceeds **8 lines** of logic (excluding param handling and response rendering)
+- The action touches **2 or more models** (e.g., creates an order AND updates product stock)
+- The action has **side effects** beyond persistence — sending emails, enqueuing jobs, calling external APIs, publishing events
+- The **same business logic** is needed in more than one place (API controller, background job, rake task, console)
+- The action contains **conditional business logic** (if order > $1000, do X)
+
+## When NOT To Apply
+
+Do NOT extract to a service object when:
+
+- The action is **simple CRUD** — receives params, saves one record, responds. A 4-line create action does not need a service object. The overhead of an extra file and class adds complexity without benefit.
+- The action only **reads data** — index and show actions that query and render rarely need services. Use scopes on the model or query objects instead.
+- You're extracting **just to extract**. If the service object would contain 3 lines that mirror what the controller already does, it's not adding value.
+
+```ruby
+# This does NOT need a service object. Leave it in the controller.
+def create
+  @comment = @post.comments.build(comment_params)
+  @comment.user = current_user
+
+  if @comment.save
+    redirect_to @post, notice: "Comment added."
+  else
+    render :show, status: :unprocessable_entity
+  end
+end
+```
+
+## Edge Cases
+
+**The action is 10 lines but only touches one model:**
+Look at what those lines do. If it's complex validation logic, consider a form object instead. If it's complex querying, consider a query object. Service objects are best for multi-step processes with side effects.
+
+**The service object would only be called from one place:**
+That's fine. Single-use services are still valuable for testability and readability. The reuse benefit is a bonus, not a requirement.
+
+**The team uses `interactor` or `dry-transaction` gems:**
+Follow the team's established pattern. If they use interactors, write an interactor. Rubyn adapts to the project's conventions (detected via codebase memory), not the other way around.
+
+**The existing codebase has no `app/services/` directory:**
+Create it. This is a standard Rails convention even though Rails doesn't generate it by default. Place the service at `app/services/{resource}/{action}_service.rb`.