rubyn-code 0.1.0

data/skills/rails/form_objects.md

@@ -0,0 +1,168 @@
+# Rails: Form Objects
+
+## Pattern
+
+Use form objects when a form doesn't map cleanly to a single ActiveRecord model. Form objects encapsulate validation, data transformation, and multi-model persistence behind an ActiveModel-compliant interface that works with Rails form helpers.
+
+```ruby
+# app/forms/registration_form.rb
+class RegistrationForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :email, :string
+  attribute :password, :string
+  attribute :password_confirmation, :string
+  attribute :company_name, :string
+  attribute :plan, :string, default: "free"
+  attribute :terms_accepted, :boolean
+
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :password, presence: true, length: { minimum: 8 }
+  validates :password_confirmation, presence: true
+  validates :company_name, presence: true
+  validates :terms_accepted, acceptance: true
+  validate :passwords_match
+  validate :email_not_taken
+
+  def save
+    return false unless valid?
+
+    ActiveRecord::Base.transaction do
+      company = Company.create!(name: company_name, plan: plan)
+      user = company.users.create!(email: email, password: password, role: :admin)
+      Onboarding::WelcomeService.call(user)
+    end
+
+    true
+  rescue ActiveRecord::RecordInvalid => e
+    errors.add(:base, e.message)
+    false
+  end
+
+  private
+
+  def passwords_match
+    errors.add(:password_confirmation, "doesn't match") unless password == password_confirmation
+  end
+
+  def email_not_taken
+    errors.add(:email, "is already registered") if User.exists?(email: email)
+  end
+end
+```
+
+The controller stays thin:
+
+```ruby
+# app/controllers/registrations_controller.rb
+class RegistrationsController < ApplicationController
+  def new
+    @form = RegistrationForm.new
+  end
+
+  def create
+    @form = RegistrationForm.new(registration_params)
+
+    if @form.save
+      redirect_to dashboard_path, notice: "Welcome!"
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def registration_params
+    params.require(:registration_form).permit(:email, :password, :password_confirmation, :company_name, :plan, :terms_accepted)
+  end
+end
+```
+
+The view works with standard form helpers:
+
+```erb
+<%= form_with model: @form, url: registrations_path do |f| %>
+  <%= f.text_field :email %>
+  <%= f.password_field :password %>
+  <%= f.password_field :password_confirmation %>
+  <%= f.text_field :company_name %>
+  <%= f.check_box :terms_accepted %>
+  <%= f.submit "Sign Up" %>
+<% end %>
+```
+
+## Why This Is Good
+
+- **Validates as a unit.** Cross-field validations (password confirmation, terms acceptance) and cross-model checks (email uniqueness) live together in one object rather than scattered across multiple models.
+- **Works with Rails forms.** Including `ActiveModel::Model` gives you `form_with` compatibility, error messages, and all the form helpers for free.
+- **Keeps models clean.** The User model doesn't need a `terms_accepted` virtual attribute or a `password_confirmation` validation that only applies during registration.
+- **Testable.** Instantiate the form with params, call `.save`, assert results. No HTTP, no controllers, no views.
+- **Transactional.** Multi-model persistence wraps in a transaction naturally within the `save` method.
+
+## Anti-Pattern
+
+Stuffing virtual attributes and context-specific validations into the model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  attr_accessor :company_name, :plan, :terms_accepted, :registering
+
+  validates :terms_accepted, acceptance: true, if: :registering
+  validates :password_confirmation, presence: true, if: :registering
+  validates :company_name, presence: true, if: :registering
+
+  after_create :create_company_and_onboard, if: :registering
+
+  private
+
+  def create_company_and_onboard
+    company = Company.create!(name: company_name, plan: plan)
+    self.update!(company: company, role: :admin)
+    Onboarding::WelcomeService.call(self)
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Conditional validations pollute the model.** Every `if: :registering` is a code smell. The model accumulates flags and conditionals for every context it's used in (registration, profile update, admin edit, API creation).
+- **Virtual attributes bloat the model.** `company_name`, `plan`, `terms_accepted` have nothing to do with the User model — they're registration-specific concerns.
+- **Callbacks hide side effects.** `after_create :create_company_and_onboard` runs silently whenever a user is created with the `registering` flag. Creating a user in the console, a seed file, or a test unexpectedly triggers company creation if someone accidentally sets the flag.
+- **Hard to test.** Testing registration requires setting `user.registering = true` and knowing about the hidden callback chain. The test is coupled to implementation details.
+
+## When To Apply
+
+Use a form object when ANY of these are true:
+
+- The form spans **multiple models** (registration creates a user AND a company)
+- The form has **virtual attributes** that don't exist on any model (terms acceptance, password confirmation for non-Devise setups, promotional codes)
+- **Validations are context-specific** — they apply during this form submission but not when the model is used elsewhere
+- The form requires **data transformation** before persistence (parsing dates, splitting full name into first/last, geocoding an address)
+- The form has **complex conditional logic** about which fields are required based on other field values
+
+## When NOT To Apply
+
+- The form maps **directly to one model** with no virtual attributes and no context-specific validations. Use the model directly — a form object adds a pointless layer.
+- The form is **read-only** (search, filter). Use a simple parameter object or a query object instead.
+- The **only difference** from the model is one extra validation. Add it to the model with a context (`validates :field, presence: true, on: :registration`) rather than creating an entire form object for one rule.
+
+## Edge Cases
+
+**The form needs to update existing records, not just create:**
+Add a constructor that accepts an existing record and populates attributes from it. The `save` method checks for `persisted?` and calls `update!` instead of `create!`.
+
+```ruby
+def initialize(user: nil, **attributes)
+  @user = user
+  super(**attributes)
+  self.email ||= @user&.email
+end
+```
+
+**The form has nested attributes (like line items on an order):**
+Form objects can include their own nested form objects or accept arrays. This is where form objects really shine over `accepts_nested_attributes_for`, which is brittle and hard to validate.
+
+**The team uses the `reform` or `dry-validation` gem:**
+Follow the team's existing pattern. If they use Reform, write a Reform form. Rubyn adapts to the project's conventions.

data/skills/rails/hotwire.md

@@ -0,0 +1,229 @@
+# Rails: Hotwire (Turbo + Stimulus)
+
+## Pattern
+
+Hotwire delivers fast, reactive UIs by sending HTML over the wire instead of JSON. Turbo handles navigation and page updates without JavaScript. Stimulus adds sprinkles of JS behavior when needed. Together, they replace most SPA complexity.
+
+### Turbo Drive (Automatic)
+
+```ruby
+# Turbo Drive is automatic — every link click and form submission
+# is intercepted and fetched via fetch(), replacing the body.
+# No configuration needed. Just use standard Rails link and form helpers.
+
+# The key contract: return proper HTTP status codes
+class OrdersController < ApplicationController
+  def create
+    @order = current_user.orders.build(order_params)
+
+    if @order.save
+      redirect_to @order, notice: "Order created."  # 303 redirect → Turbo follows it
+    else
+      render :new, status: :unprocessable_entity  # 422 → Turbo replaces the page
+    end
+  end
+
+  def update
+    @order = current_user.orders.find(params[:id])
+
+    if @order.update(order_params)
+      redirect_to @order, notice: "Updated."
+    else
+      render :edit, status: :unprocessable_entity  # MUST return 422 for Turbo to re-render
+    end
+  end
+end
+```
+
+### Turbo Frames (Partial Page Updates)
+
+```erb
+<%# app/views/orders/index.html.erb %>
+<%# Only the content inside the turbo_frame is replaced on navigation %>
+<h1>Orders</h1>
+
+<%= turbo_frame_tag "orders_list" do %>
+  <%= render @orders %>
+
+  <%# Pagination links inside the frame only update the frame %>
+  <%= paginate @orders %>
+<% end %>
+
+<%# Search form targets the frame %>
+<%= form_with url: orders_path, method: :get, data: { turbo_frame: "orders_list" } do |f| %>
+  <%= f.search_field :q, placeholder: "Search orders..." %>
+  <%= f.submit "Search" %>
+<% end %>
+```
+
+```erb
+<%# app/views/orders/_order.html.erb %>
+<%= turbo_frame_tag dom_id(order) do %>
+  <div class="order-card">
+    <h3><%= order.reference %></h3>
+    <p><%= order.status %></p>
+    <%= link_to "Edit", edit_order_path(order) %>
+  </div>
+<% end %>
+
+<%# Clicking "Edit" loads the edit form INTO the frame — no full page load %>
+```
+
+```erb
+<%# app/views/orders/edit.html.erb %>
+<%= turbo_frame_tag dom_id(@order) do %>
+  <%= render "form", order: @order %>
+<% end %>
+```
+
+### Turbo Streams (Real-Time Updates)
+
+```ruby
+# After creating an order, broadcast updates to the page
+class Order < ApplicationRecord
+  after_create_commit -> {
+    broadcast_prepend_to "orders",
+      target: "orders_list",
+      partial: "orders/order",
+      locals: { order: self }
+  }
+
+  after_update_commit -> {
+    broadcast_replace_to "orders",
+      target: dom_id(self),
+      partial: "orders/order",
+      locals: { order: self }
+  }
+
+  after_destroy_commit -> {
+    broadcast_remove_to "orders", target: dom_id(self)
+  }
+end
+```
+
+```erb
+<%# app/views/orders/index.html.erb %>
+<%= turbo_stream_from "orders" %>
+
+<div id="orders_list">
+  <%= render @orders %>
+</div>
+```
+
+Inline Turbo Stream responses from controller actions:
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    @order = current_user.orders.build(order_params)
+
+    if @order.save
+      respond_to do |format|
+        format.turbo_stream {
+          render turbo_stream: turbo_stream.prepend("orders_list",
+            partial: "orders/order", locals: { order: @order })
+        }
+        format.html { redirect_to orders_path }
+      end
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @order = current_user.orders.find(params[:id])
+    @order.destroy!
+
+    respond_to do |format|
+      format.turbo_stream { render turbo_stream: turbo_stream.remove(dom_id(@order)) }
+      format.html { redirect_to orders_path }
+    end
+  end
+end
+```
+
+### Stimulus (Sprinkles of JavaScript)
+
+```javascript
+// app/javascript/controllers/toggle_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["content"]
+
+  toggle() {
+    this.contentTarget.classList.toggle("hidden")
+  }
+}
+```
+
+```erb
+<%# Usage in HTML — no inline JS, no jQuery %>
+<div data-controller="toggle">
+  <button data-action="click->toggle#toggle">Show Details</button>
+  <div data-toggle-target="content" class="hidden">
+    <p>Order details here...</p>
+  </div>
+</div>
+```
+
+```javascript
+// app/javascript/controllers/auto_submit_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["form"]
+
+  submit() {
+    clearTimeout(this.timeout)
+    this.timeout = setTimeout(() => {
+      this.formTarget.requestSubmit()
+    }, 300)
+  }
+}
+```
+
+```erb
+<%= form_with url: orders_path, method: :get,
+    data: { controller: "auto-submit", auto_submit_target: "form", turbo_frame: "orders_list" } do |f| %>
+  <%= f.search_field :q, data: { action: "input->auto-submit#submit" }, placeholder: "Search..." %>
+<% end %>
+```
+
+## Why This Is Good
+
+- **No JavaScript framework needed.** Turbo + Stimulus replaces 90% of what React/Vue do for typical CRUD apps, with far less code.
+- **Server-rendered HTML.** No JSON API, no serializers, no client-side state management. The server renders HTML and Turbo delivers it to the right place.
+- **Progressive enhancement.** Everything works without JavaScript (Turbo Drive degrades gracefully). Stimulus adds interactivity on top.
+- **Turbo Streams enable real-time.** WebSocket-powered live updates without a single line of custom JavaScript. New orders appear instantly for all users.
+- **Stimulus controllers are tiny.** 10-20 lines each, reusable across views, no build step complexity.
+
+## Anti-Pattern
+
+Disabling Turbo or fighting it:
+
+```erb
+<%# BAD: Disabling Turbo because forms don't work %>
+<%= form_with model: @order, data: { turbo: false } do |f| %>
+
+<%# The real fix: return the correct status code %>
+def create
+  if @order.save
+    redirect_to @order       # 303 — Turbo follows
+  else
+    render :new, status: :unprocessable_entity  # 422 — Turbo re-renders
+    # NOT: render :new (200 status makes Turbo think it succeeded)
+  end
+end
+```
+
+## When To Apply
+
+- **Every new Rails 7+ app.** Hotwire is the default. Use it.
+- **CRUD-heavy apps.** Forms, lists, search, pagination, inline editing — Hotwire handles all of these with minimal JavaScript.
+- **Real-time features.** Chat, notifications, live dashboards — Turbo Streams over WebSockets.
+
+## When NOT To Apply
+
+- **Complex client-side interactions.** Drag-and-drop editors, canvas drawing, real-time collaboration — these may need a JavaScript framework.
+- **Offline-first apps.** Turbo requires a server connection. PWAs with offline support need client-side state.

data/skills/rails/internationalization.md

@@ -0,0 +1,192 @@
+# Rails: Internationalization (i18n)
+
+## Pattern
+
+Use Rails i18n for all user-facing text, even in English-only apps. It centralizes copy, supports pluralization, enables future translation, and keeps views clean.
+
+### Basic Setup
+
+```yaml
+# config/locales/en.yml
+en:
+  orders:
+    index:
+      title: "Your Orders"
+      empty: "You haven't placed any orders yet."
+      count:
+        one: "%{count} order"
+        other: "%{count} orders"
+    show:
+      title: "Order %{reference}"
+      status:
+        pending: "Awaiting confirmation"
+        confirmed: "Processing"
+        shipped: "On its way"
+        delivered: "Delivered"
+        cancelled: "Cancelled"
+    create:
+      success: "Order placed successfully!"
+      failure: "Could not place order. Please check the errors below."
+  
+  shared:
+    actions:
+      edit: "Edit"
+      delete: "Delete"
+      cancel: "Cancel"
+      save: "Save Changes"
+      back: "Back"
+    confirmations:
+      delete: "Are you sure? This cannot be undone."
+```
+
+### Usage in Views
+
+```erb
+<%# Views use t() helper %>
+<h1><%= t(".title") %></h1>  <%# Lazy lookup — resolves to orders.index.title %>
+
+<% if @orders.empty? %>
+  <p><%= t(".empty") %></p>
+<% else %>
+  <p><%= t(".count", count: @orders.count) %></p>  <%# Pluralization %>
+<% end %>
+
+<%= link_to t("shared.actions.edit"), edit_order_path(@order) %>
+
+<%# Status with translation %>
+<span class="badge"><%= t("orders.show.status.#{@order.status}") %></span>
+```
+
+### Usage in Controllers
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    @order = current_user.orders.build(order_params)
+    if @order.save
+      redirect_to @order, notice: t(".success")
+    else
+      flash.now[:alert] = t(".failure")
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @order.destroy
+    redirect_to orders_path, notice: t("orders.destroy.success", reference: @order.reference)
+  end
+end
+```
+
+### Model Validations
+
+```yaml
+# config/locales/en.yml
+en:
+  activerecord:
+    errors:
+      models:
+        order:
+          attributes:
+            shipping_address:
+              blank: "is required for delivery"
+            total:
+              greater_than: "must be a positive amount"
+        user:
+          attributes:
+            email:
+              taken: "is already registered. Did you mean to sign in?"
+```
+
+```ruby
+# These override Rails' default validation messages automatically
+class Order < ApplicationRecord
+  validates :shipping_address, presence: true
+  # Error message: "Shipping address is required for delivery"
+end
+```
+
+### Organizing Locale Files
+
+```
+config/locales/
+├── en.yml                    # Shared/global translations
+├── models/
+│   ├── en.yml                # ActiveRecord model names and attributes
+│   └── errors/
+│       └── en.yml            # Validation error messages
+├── views/
+│   ├── orders.en.yml         # Order view translations
+│   ├── users.en.yml          # User view translations
+│   └── admin.en.yml          # Admin panel translations
+└── mailers/
+    └── en.yml                # Email subject lines and content
+```
+
+```ruby
+# config/application.rb
+config.i18n.load_path += Dir[Rails.root.join("config/locales/**/*.yml")]
+config.i18n.default_locale = :en
+config.i18n.fallbacks = true  # Fall back to :en if translation missing
+```
+
+### Date and Number Formatting
+
+```yaml
+# config/locales/en.yml
+en:
+  date:
+    formats:
+      short: "%b %d"          # "Mar 20"
+      long: "%B %d, %Y"       # "March 20, 2026"
+  time:
+    formats:
+      short: "%b %d, %I:%M %p"  # "Mar 20, 02:30 PM"
+  number:
+    currency:
+      format:
+        unit: "$"
+        precision: 2
+```
+
+```erb
+<%= l(@order.created_at, format: :long) %>   <%# March 20, 2026 %>
+<%= l(@order.created_at, format: :short) %>  <%# Mar 20 %>
+<%= number_to_currency(@order.total / 100.0) %>  <%# $25.00 %>
+```
+
+## Why This Is Good
+
+- **Single source of truth for copy.** Changing "Place Order" to "Complete Purchase" across the entire app means editing one YAML line, not grep-replacing across 15 files.
+- **Lazy lookup keeps views clean.** `t(".title")` in `orders/index.html.erb` automatically resolves to `en.orders.index.title`. No long key paths in views.
+- **Pluralization is handled.** `t(".count", count: 1)` → "1 order." `t(".count", count: 5)` → "5 orders." Works correctly for languages with complex pluralization rules.
+- **Validation messages are customizable per model.** "Email is already registered. Did you mean to sign in?" is more helpful than "Email has already been taken."
+- **Future-proofs for translation.** Even if you're English-only today, adding Spanish later means adding `es.yml` files — no code changes.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Hardcoded strings in views
+<h1>Your Orders</h1>
+<p>You have <%= @orders.count %> order<%= @orders.count == 1 ? "" : "s" %></p>
+
+# BAD: Hardcoded strings in controllers
+redirect_to @order, notice: "Order placed successfully!"
+flash[:alert] = "Something went wrong"
+
+# BAD: Hardcoded validation messages
+validates :email, uniqueness: { message: "is already taken" }
+# Use locale files instead — they're overridable per model
+```
+
+## When To Apply
+
+- **Every user-facing string.** Views, flash messages, mailer subject lines, validation messages, error pages.
+- **Even English-only apps.** Centralizing copy in YAML is valuable for consistency and maintainability regardless of language count.
+- **Date and number formatting.** Use `l()` for dates and `number_to_currency` for money — they respect locale settings.
+
+## When NOT To Apply
+
+- **Log messages.** Logs are for developers, not users. Log in English, always.
+- **Developer-facing text.** Rake task output, console messages, internal error classes. These stay as plain strings.
+- **API responses.** JSON APIs typically return machine-readable codes, not translated text. Error codes like `"insufficient_credits"` don't need i18n.