rubyn-code 0.1.0

data/skills/rails/action_cable.md

@@ -0,0 +1,160 @@
+# Rails: ActionCable (WebSockets)
+
+## Pattern
+
+ActionCable integrates WebSockets into Rails for real-time features — live chat, notifications, live updates, and collaborative editing. Use channels for bi-directional communication and Turbo Streams for server-pushed HTML updates.
+
+```ruby
+# app/channels/application_cable/connection.rb
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = find_verified_user
+    end
+
+    private
+
+    def find_verified_user
+      if (user = User.find_by(id: cookies.encrypted[:user_id]))
+        user
+      else
+        reject_unauthorized_connection
+      end
+    end
+  end
+end
+```
+
+```ruby
+# app/channels/order_updates_channel.rb
+class OrderUpdatesChannel < ApplicationCable::Channel
+  def subscribed
+    order = current_user.orders.find(params[:order_id])
+    stream_for order
+  end
+
+  def unsubscribed
+    # Cleanup when client disconnects
+  end
+end
+
+# Broadcasting from anywhere in the app
+OrderUpdatesChannel.broadcast_to(order, {
+  type: "status_changed",
+  status: order.status,
+  updated_at: order.updated_at.iso8601
+})
+```
+
+### Turbo Streams over ActionCable (The Rails 7+ Way)
+
+```ruby
+# Model broadcasts — simplest approach
+class Order < ApplicationRecord
+  after_create_commit -> { broadcast_prepend_to "orders", target: "orders_list" }
+  after_update_commit -> { broadcast_replace_to "orders" }
+  after_destroy_commit -> { broadcast_remove_to "orders" }
+end
+
+# Or broadcast from a service object (preferred — keeps model clean)
+class Orders::ShipService
+  def call(order)
+    order.update!(status: :shipped, shipped_at: Time.current)
+
+    # Push update to all subscribers
+    Turbo::StreamsChannel.broadcast_replace_to(
+      "order_#{order.id}",
+      target: "order_#{order.id}",
+      partial: "orders/order",
+      locals: { order: order }
+    )
+
+    # Push to the orders list page too
+    Turbo::StreamsChannel.broadcast_replace_to(
+      "orders",
+      target: "order_#{order.id}",
+      partial: "orders/order_row",
+      locals: { order: order }
+    )
+  end
+end
+```
+
+```erb
+<%# View — subscribe to updates %>
+<%= turbo_stream_from "orders" %>
+
+<div id="orders_list">
+  <%= render @orders %>
+</div>
+
+<%# Individual order page %>
+<%= turbo_stream_from "order_#{@order.id}" %>
+
+<div id="order_<%= @order.id %>">
+  <%= render @order %>
+</div>
+```
+
+### Custom Channel for Interactive Features
+
+```ruby
+# app/channels/notifications_channel.rb
+class NotificationsChannel < ApplicationCable::Channel
+  def subscribed
+    stream_for current_user
+  end
+end
+
+# Send notifications from anywhere
+class NotificationService
+  def self.push(user, message:, type: :info)
+    NotificationsChannel.broadcast_to(user, {
+      type: type,
+      message: message,
+      timestamp: Time.current.iso8601
+    })
+  end
+end
+
+# Usage
+NotificationService.push(user, message: "Your order shipped!", type: :success)
+```
+
+```javascript
+// app/javascript/channels/notifications_channel.js
+import consumer from "./consumer"
+
+consumer.subscriptions.create("NotificationsChannel", {
+  received(data) {
+    const toast = document.createElement("div")
+    toast.className = `toast toast-${data.type}`
+    toast.textContent = data.message
+    document.getElementById("notifications").appendChild(toast)
+
+    setTimeout(() => toast.remove(), 5000)
+  }
+})
+```
+
+## Why This Is Good
+
+- **Turbo Streams over ActionCable is zero-JavaScript real-time.** Server pushes HTML, Turbo applies it. No custom JS for most use cases.
+- **`broadcast_to` uses the model as the channel key.** `stream_for order` and `broadcast_to(order, ...)` — the channel routing is automatic and scoped.
+- **Authentication via cookies.** The WebSocket connection inherits the user's session. No separate auth token needed for web apps.
+- **Scales with Redis.** In production, ActionCable uses Redis as the pub/sub backend. Multiple app servers share the same broadcast channel.
+
+## When To Apply
+
+- **Live updates** — order status changes, dashboard metrics, admin activity feeds.
+- **Notifications** — real-time toasts, badge counts, alert banners.
+- **Collaborative features** — shared editing, presence indicators, live cursors.
+- **Turbo Stream broadcasts** — the simplest path. Use this before building custom channels.
+
+## When NOT To Apply
+
+- **Polling works fine.** If data changes once per minute and freshness isn't critical, a 30-second poll is simpler than WebSockets.
+- **API-only apps without a frontend.** Use webhooks or SSE instead.
+- **High-frequency data streams** (stock tickers, game state at 60fps). ActionCable adds overhead per message — consider a dedicated WebSocket server.

data/skills/rails/active_record_basics.md

@@ -0,0 +1,174 @@
+# Rails: ActiveRecord Best Practices
+
+## Pattern
+
+Use scopes for reusable query fragments, `find_by` over `where.first`, `exists?` over loading records to check presence, and `pluck` when you only need column values. Keep models focused on data access and validation, not business logic.
+
+```ruby
+class Order < ApplicationRecord
+  # Scopes: named, chainable, readable
+  scope :recent, -> { where(created_at: 30.days.ago..) }
+  scope :pending, -> { where(status: :pending) }
+  scope :shipped, -> { where(status: :shipped) }
+  scope :for_user, ->(user) { where(user: user) }
+  scope :high_value, -> { where("total >= ?", 200) }
+  scope :by_newest, -> { order(created_at: :desc) }
+
+  # Scopes compose naturally
+  # Order.for_user(user).pending.recent.by_newest
+
+  # Efficient existence checks
+  def self.any_pending_for?(user)
+    for_user(user).pending.exists?
+  end
+
+  # Efficient counting
+  def self.total_revenue
+    sum(:total)
+  end
+
+  # Efficient value extraction
+  def self.recent_emails
+    recent.joins(:user).pluck("users.email")
+  end
+end
+```
+
+```ruby
+# CORRECT: Efficient queries
+user = User.find_by(email: "alice@example.com")    # Returns nil if not found
+user = User.find_by!(email: "alice@example.com")   # Raises RecordNotFound
+
+order_exists = Order.where(user: user).exists?      # SELECT 1 ... LIMIT 1
+order_count = user.orders.pending.count              # SELECT COUNT(*)
+totals = Order.pending.pluck(:total)                 # SELECT total — returns array of values
+
+# Batch processing for large datasets
+Order.pending.find_each(batch_size: 500) do |order|
+  Orders::ProcessService.call(order)
+end
+
+# Bulk operations without instantiating records
+Order.where(status: :draft, created_at: ..30.days.ago).delete_all
+Order.pending.update_all(status: :cancelled, cancelled_at: Time.current)
+
+# insert_all for bulk creation (Rails 6+)
+Order.insert_all([
+  { user_id: 1, total: 100, status: :pending, created_at: Time.current, updated_at: Time.current },
+  { user_id: 2, total: 200, status: :pending, created_at: Time.current, updated_at: Time.current }
+])
+```
+
+## Why This Is Good
+
+- **Scopes are chainable and composable.** `Order.pending.recent.high_value` reads like a sentence and generates a single SQL query. Each scope is a reusable building block.
+- **`exists?` runs `SELECT 1 LIMIT 1`.** It doesn't load records into memory. Checking if a user has pending orders costs one lightweight query regardless of how many orders exist.
+- **`pluck` skips model instantiation.** `Order.pluck(:total)` returns `[100, 200, 300]` without creating Order objects. For 10,000 records, this is dramatically faster and uses a fraction of the memory.
+- **`find_each` prevents memory bloat.** Loading 100,000 orders with `.all.each` allocates all of them simultaneously. `find_each` loads 1,000 at a time (configurable) and GCs between batches.
+- **`update_all` and `delete_all` execute single SQL statements.** No callbacks, no instantiation, no N individual UPDATE queries. For bulk operations on thousands of records, this is orders of magnitude faster.
+
+## Anti-Pattern
+
+Loading full records when you only need a check, a count, or a column value:
+
+```ruby
+# BAD: Loads ALL orders into memory to check if any exist
+if user.orders.where(status: :pending).to_a.any?
+  # ...
+end
+
+# BAD: Loads ALL records to count them
+total = Order.where(status: :pending).to_a.length
+
+# BAD: Loads full AR objects to get one column
+emails = User.where(active: true).map(&:email)
+
+# BAD: where().first instead of find_by
+user = User.where(email: "alice@example.com").first
+
+# BAD: Processing large datasets without batching
+Order.all.each do |order|
+  order.recalculate_total!
+end
+
+# BAD: N individual updates
+Order.pending.each do |order|
+  order.update(status: :cancelled)
+end
+
+# BAD: default_scope — almost always a mistake
+class Order < ApplicationRecord
+  default_scope { where(deleted: false) }
+end
+```
+
+## Why This Is Bad
+
+- **`.to_a.any?` loads every matching record.** 5,000 pending orders? That's 5,000 ActiveRecord objects instantiated, then thrown away after checking `any?`. `exists?` does the same check with zero objects loaded.
+- **`.to_a.length` vs `.count`.** Loading 10,000 records to count them uses ~100MB of memory. `COUNT(*)` uses zero Ruby memory and returns instantly.
+- **`.map(&:email)` instantiates every User.** For 50,000 users, that's 50,000 ActiveRecord objects in memory. `pluck(:email)` returns a simple array of strings with no model instantiation.
+- **`.where().first` generates `ORDER BY id LIMIT 1`.** `find_by` generates `LIMIT 1` without the sort. On large tables without an index on the filter column, the sort is expensive.
+- **Iterating without batching** loads the entire result set into memory at once. For large tables this can exhaust available RAM.
+- **N individual updates** execute N separate UPDATE statements. Updating 1,000 orders takes 1,000 round trips to the database. `update_all` does it in one.
+- **`default_scope` poisons every query.** Every `Order.find`, `Order.count`, `Order.joins` silently includes `WHERE deleted = false`. Forgetting to `unscope` it causes subtle bugs. Soft deletes should use explicit scopes or gems like `discard`.
+
+## When To Apply
+
+- **Every ActiveRecord query should be as efficient as possible.** Use the cheapest operation that satisfies the need: `exists?` > `count` > `pluck` > `select` > loading full records.
+- **Scopes for any query used in more than one place.** If two controllers filter by pending status, define `scope :pending`.
+- **`find_each` for any iteration over more than 100 records.**
+- **`update_all`/`delete_all` for bulk operations** where you don't need callbacks or validations.
+
+## When NOT To Apply
+
+- **Small datasets where clarity wins.** If you have 10 records and `.map(&:name)` is more readable than `.pluck(:name)` in context, the performance difference is negligible.
+- **When you need callbacks to fire.** `update_all` skips callbacks and validations. If the model's `after_update` callback must run, iterate and save individually (but consider whether the callback should be a service object instead).
+- **Don't over-scope.** A scope used in exactly one place adds indirection without reuse benefit. An inline `where` is fine for one-off queries.
+
+## Edge Cases
+
+**Scopes vs class methods:**
+Scopes always return a relation (even when the condition is nil). Class methods can return nil, breaking chains.
+
+```ruby
+# Scope: always chainable even when condition is nil
+scope :by_status, ->(status) { where(status: status) if status.present? }
+
+# Class method: can break the chain if it returns nil
+def self.by_status(status)
+  return none unless status.present?  # Must return a relation, not nil
+  where(status: status)
+end
+```
+
+**`select` vs `pluck`:**
+`select` returns ActiveRecord objects with limited attributes. `pluck` returns raw arrays. Use `select` when you need methods on the model. Use `pluck` when you just need values.
+
+```ruby
+Order.select(:id, :total).each { |o| o.total }  # AR objects, can call methods
+Order.pluck(:id, :total)                          # [[1, 100], [2, 200]] — raw arrays
+```
+
+**Counter caches for frequently counted associations:**
+
+```ruby
+# Migration
+add_column :users, :orders_count, :integer, default: 0
+
+# Model
+class Order < ApplicationRecord
+  belongs_to :user, counter_cache: true
+end
+
+# Now user.orders_count is a column read, not a COUNT(*) query
+```
+
+**`find_or_create_by` race conditions:**
+Use `create_or_find_by` (Rails 6+) with a unique database constraint to handle concurrency:
+
+```ruby
+# Safe under concurrency with a unique index on email
+user = User.create_or_find_by(email: "alice@example.com") do |u|
+  u.name = "Alice"
+end
+```

data/skills/rails/active_storage.md

@@ -0,0 +1,242 @@
+# Rails: Active Storage
+
+## Pattern
+
+Active Storage handles file uploads in Rails — attaching files to models, processing variants (thumbnails, resizes), and storing them on local disk, S3, GCS, or Azure. Configure it once, use it through a clean model API.
+
+```ruby
+# Setup
+# rails active_storage:install
+# rails db:migrate
+
+# config/storage.yml
+local:
+  service: Disk
+  root: <%= Rails.root.join("storage") %>
+
+amazon:
+  service: S3
+  access_key_id: <%= ENV["AWS_ACCESS_KEY_ID"] %>
+  secret_access_key: <%= ENV["AWS_SECRET_ACCESS_KEY"] %>
+  region: us-east-1
+  bucket: rubyn-uploads
+
+# config/environments/development.rb
+config.active_storage.service = :local
+
+# config/environments/production.rb
+config.active_storage.service = :amazon
+```
+
+### Model Attachments
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+  has_one_attached :resume
+
+  # Validations (use activestorage-validator gem or custom)
+  validate :avatar_format
+
+  private
+
+  def avatar_format
+    return unless avatar.attached?
+
+    unless avatar.content_type.in?(%w[image/png image/jpeg image/webp])
+      errors.add(:avatar, "must be PNG, JPEG, or WebP")
+    end
+
+    if avatar.byte_size > 5.megabytes
+      errors.add(:avatar, "must be under 5MB")
+    end
+  end
+end
+
+class Order < ApplicationRecord
+  has_many_attached :documents  # Multiple files
+
+  has_one_attached :invoice_pdf
+end
+```
+
+### Controller and Form
+
+```ruby
+class UsersController < ApplicationController
+  def update
+    @user = current_user
+
+    if @user.update(user_params)
+      redirect_to @user, notice: "Profile updated."
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :avatar)
+  end
+end
+```
+
+```erb
+<%# Form — standard file field, nothing special %>
+<%= form_with model: @user do |f| %>
+  <%= f.file_field :avatar, accept: "image/png,image/jpeg,image/webp" %>
+
+  <% if @user.avatar.attached? %>
+    <%= image_tag @user.avatar.variant(resize_to_limit: [200, 200]) %>
+    <%= button_to "Remove", purge_avatar_user_path(@user), method: :delete %>
+  <% end %>
+
+  <%= f.submit "Save" %>
+<% end %>
+```
+
+### Variants (Image Processing)
+
+```ruby
+# Requires: gem "image_processing", "~> 1.2"
+
+class User < ApplicationRecord
+  has_one_attached :avatar do |attachable|
+    attachable.variant :thumb, resize_to_fill: [100, 100]
+    attachable.variant :medium, resize_to_limit: [300, 300]
+    attachable.variant :large, resize_to_limit: [800, 800]
+  end
+end
+
+# Usage in views
+<%= image_tag @user.avatar.variant(:thumb) %>
+<%= image_tag @user.avatar.variant(:medium) %>
+
+# Custom one-off variant
+<%= image_tag @user.avatar.variant(resize_to_limit: [150, 150], format: :webp) %>
+
+# Check before rendering
+<% if @user.avatar.attached? %>
+  <%= image_tag @user.avatar.variant(:thumb) %>
+<% else %>
+  <%= image_tag "default_avatar.png" %>
+<% end %>
+```
+
+### Direct Uploads (Client-Side)
+
+```javascript
+// app/javascript/application.js
+import * as ActiveStorage from "@rails/activestorage"
+ActiveStorage.start()
+```
+
+```erb
+<%# Direct upload — file goes straight to storage, not through your server %>
+<%= form.file_field :avatar, direct_upload: true %>
+```
+
+Direct uploads send the file directly to S3/GCS from the browser. Your server only receives the signed blob ID, not the file bytes. This keeps your web server fast and avoids upload timeouts.
+
+### Service Objects for Complex Uploads
+
+```ruby
+# When upload involves processing, validation, or multiple steps
+class Documents::UploadService
+  def self.call(order, file)
+    new(order, file).call
+  end
+
+  def initialize(order, file)
+    @order = order
+    @file = file
+  end
+
+  def call
+    validate_file!
+    @order.documents.attach(@file)
+    process_document(@order.documents.last)
+    Result.new(success: true)
+  rescue ActiveStorage::IntegrityError => e
+    Result.new(success: false, error: "File corrupted: #{e.message}")
+  rescue DocumentTooLargeError => e
+    Result.new(success: false, error: e.message)
+  end
+
+  private
+
+  def validate_file!
+    raise DocumentTooLargeError, "File exceeds 25MB" if @file.size > 25.megabytes
+  end
+
+  def process_document(attachment)
+    # Extract text, generate preview, scan for viruses — async
+    DocumentProcessingJob.perform_later(attachment.id)
+  end
+end
+```
+
+## Why This Is Good
+
+- **One API for every storage backend.** Develop with local disk, deploy with S3. Change one line in config, not your code.
+- **Variants are lazy.** `variant(:thumb)` doesn't process the image until it's first requested. After that, the processed variant is cached.
+- **Direct uploads offload your server.** Large files go straight to S3 from the browser. Your Rails app never touches the bytes.
+- **Attachment validations on the model.** File type and size checks happen before save, with standard error messages on the model.
+- **Named variants are reusable.** Define `:thumb`, `:medium`, `:large` once on the model, use them everywhere in views.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Processing uploads in the controller
+def create
+  file = params[:document]
+  File.open(Rails.root.join("uploads", file.original_filename), "wb") do |f|
+    f.write(file.read)
+  end
+  # Manual file management, no cleanup, no variants, no cloud storage
+
+  # BAD: Synchronous processing on upload
+  @user.avatar.attach(params[:avatar])
+  ImageOptimizer.new(@user.avatar).optimize!  # Blocks the request for 5 seconds
+  ThumbnailGenerator.new(@user.avatar).generate!  # Another 3 seconds
+end
+```
+
+## When To Apply
+
+- **Every file upload in a Rails app.** Active Storage replaces CarrierWave, Paperclip, and Shrine for most use cases.
+- **User avatars, document uploads, image galleries.** Standard Active Storage with variants.
+- **Large files (>10MB).** Use direct uploads to avoid tying up web workers.
+
+## When NOT To Apply
+
+- **Extremely complex image processing pipelines.** If you need 20+ variant types, watermarking, face detection — consider Shrine or a dedicated image service.
+- **Non-Rails apps.** Active Storage is Rails-only. Use Shrine or direct S3 SDK calls for Sinatra/plain Ruby.
+- **Temporary file processing.** If you're processing a CSV and discarding it, don't attach it to a model. Just use `Tempfile`.
+
+## Edge Cases
+
+**Purging attachments:**
+```ruby
+@user.avatar.purge        # Deletes synchronously
+@user.avatar.purge_later  # Deletes via background job (preferred)
+```
+
+**Preloading to avoid N+1:**
+```ruby
+# BAD: N+1 on avatars
+users.each { |u| image_tag u.avatar } # Each avatar is a separate query
+
+# GOOD: Preload
+users = User.with_attached_avatar
+```
+
+**Attaching from a URL:**
+```ruby
+@user.avatar.attach(
+  io: URI.open("https://example.com/photo.jpg"),
+  filename: "photo.jpg",
+  content_type: "image/jpeg"
+)
+```