rubyn-code 0.1.0

data/skills/rails/concerns_models.md

@@ -0,0 +1,280 @@
+# Rails: Model Concerns
+
+## Pattern
+
+Use model concerns for genuine, reusable behavior that multiple unrelated models need. A good concern adds one well-defined capability — slugging, soft deleting, auditing, searching. It has a clear contract and works without knowledge of the including model's specific attributes.
+
+```ruby
+# app/models/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :search, ->(query) {
+      return all if query.blank?
+
+      columns = searchable_columns.map { |col| "#{table_name}.#{col}" }
+      conditions = columns.map { |col| "#{col} ILIKE :query" }.join(" OR ")
+      where(conditions, query: "%#{sanitize_sql_like(query)}%")
+    }
+  end
+
+  class_methods do
+    def searchable_columns
+      raise NotImplementedError, "#{name} must define searchable_columns"
+    end
+  end
+end
+
+# Usage in models — each defines what's searchable
+class User < ApplicationRecord
+  include Searchable
+
+  def self.searchable_columns
+    %w[name email]
+  end
+end
+
+class Product < ApplicationRecord
+  include Searchable
+
+  def self.searchable_columns
+    %w[name description sku]
+  end
+end
+
+# Both work identically
+User.search("alice")
+Product.search("widget")
+```
+
+```ruby
+# app/models/concerns/soft_deletable.rb
+module SoftDeletable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :kept, -> { where(discarded_at: nil) }
+    scope :discarded, -> { where.not(discarded_at: nil) }
+
+    default_scope { kept }
+  end
+
+  def discard
+    update(discarded_at: Time.current)
+  end
+
+  def undiscard
+    update(discarded_at: nil)
+  end
+
+  def discarded?
+    discarded_at.present?
+  end
+end
+```
+
+```ruby
+# app/models/concerns/has_token.rb
+module HasToken
+  extend ActiveSupport::Concern
+
+  included do
+    before_create :generate_token
+  end
+
+  class_methods do
+    def token_column
+      :token
+    end
+
+    def find_by_token!(token)
+      find_by!(token_column => token)
+    end
+  end
+
+  private
+
+  def generate_token
+    column = self.class.token_column
+    loop do
+      self[column] = SecureRandom.urlsafe_base64(32)
+      break unless self.class.exists?(column => self[column])
+    end
+  end
+end
+```
+
+## Why This Is Good
+
+- **Genuinely reusable.** `Searchable`, `SoftDeletable`, and `HasToken` work on any model. They don't know or care about order-specific, user-specific, or product-specific logic.
+- **Clear contract.** `Searchable` requires the model to define `searchable_columns`. The concern raises `NotImplementedError` if the model forgets. The contract is explicit and enforced.
+- **Self-contained.** Including `SoftDeletable` gives you scopes, instance methods, and a default scope. The model doesn't need to configure anything — just include and add a `discarded_at` column.
+- **Tested independently.** You can write a shared example that tests the searchable behavior, then include it in User and Product specs. One test verifies the concern works; per-model tests verify the configuration.
+- **Namespace isolation.** The concern defines behavior. The model defines which columns/attributes to apply it to. Neither reaches into the other's internals.
+
+## Anti-Pattern
+
+Using concerns to split a fat model into multiple files without actually improving the design:
+
+```ruby
+# app/models/concerns/order_calculations.rb
+module OrderCalculations
+  extend ActiveSupport::Concern
+
+  def calculate_subtotal
+    line_items.sum { |li| li.quantity * li.unit_price }
+  end
+
+  def calculate_tax
+    subtotal * tax_rate
+  end
+
+  def calculate_shipping
+    return 0 if subtotal > 100
+    line_items.sum(&:weight) * 0.5
+  end
+
+  def calculate_total
+    calculate_subtotal + calculate_tax + calculate_shipping
+  end
+
+  def apply_discount(code)
+    discount = Discount.find_by(code: code)
+    self.discount_amount = discount&.calculate(calculate_subtotal) || 0
+  end
+end
+
+# app/models/concerns/order_status.rb
+module OrderStatus
+  extend ActiveSupport::Concern
+
+  included do
+    enum :status, { pending: 0, confirmed: 1, shipped: 2, delivered: 3, cancelled: 4 }
+
+    after_update :handle_status_change, if: :saved_change_to_status?
+  end
+
+  def can_cancel?
+    pending? || confirmed?
+  end
+
+  def can_ship?
+    confirmed? && line_items.all?(&:in_stock?)
+  end
+
+  private
+
+  def handle_status_change
+    case status
+    when "confirmed" then OrderMailer.confirmed(self).deliver_later
+    when "shipped" then OrderMailer.shipped(self).deliver_later
+    when "cancelled" then process_cancellation
+    end
+  end
+
+  def process_cancellation
+    line_items.each { |li| li.product.increment!(:stock, li.quantity) }
+    RefundService.call(self)
+  end
+end
+
+# app/models/order.rb
+class Order < ApplicationRecord
+  include OrderCalculations
+  include OrderStatus
+  include OrderNotifications
+  include OrderValidations
+  include OrderScopes
+
+  # Model is now 5 lines but still has 500 lines of responsibility
+end
+```
+
+## Why This Is Bad
+
+- **Same responsibilities, different files.** The Order model still has calculations, status management, email sending, inventory management, and refund processing — they're just scattered across 5 files instead of 1. The complexity hasn't been reduced.
+- **Not reusable.** `OrderCalculations` only works for orders. No other model can include it. It's not a shared capability — it's an order-specific feature hidden in a concern.
+- **Harder to navigate.** A developer looking at `Order` sees 5 includes and has to open 5 files to understand what the model does. In a single file, they can scroll. With concerns, they play file hopscotch.
+- **Hidden callbacks.** `OrderStatus` adds an `after_update` callback that sends emails and processes refunds. Including `OrderStatus` in the model gives you no indication that saving an order might trigger a refund.
+- **Business logic in concerns.** `process_cancellation` does inventory management and calls `RefundService`. This belongs in a service object (`Orders::CancelService`), not in a model concern.
+
+## When To Apply
+
+Use model concerns when ALL of these are true:
+
+1. **Multiple unrelated models** need the same behavior (at least 2, ideally 3+)
+2. The behavior is a **capability** ("searchable", "sluggable", "auditable"), not a **feature** ("order calculations")
+3. The concern is **self-contained** — it doesn't need to know the model's specific business logic
+4. The concern has a **clear contract** — the model must provide specific columns or methods, documented explicitly
+
+## When NOT To Apply
+
+- **Don't use concerns to split a fat model.** If the model is too big, extract service objects, form objects, and query objects. Moving code to a concern file doesn't reduce complexity.
+- **Don't create a concern used by one model.** That's just indirection. Keep the code in the model.
+- **Don't put business logic in concerns.** Calculations, status transitions, payment processing, and notification sending are business logic. They belong in service objects.
+- **Don't put callbacks with side effects in concerns.** If a concern adds `after_create :send_welcome_email`, every model that includes it gets that behavior — possibly unintentionally. Side-effect callbacks belong in service objects.
+
+## Edge Cases
+
+**Concern needs different configuration per model:**
+Use class methods that the model overrides:
+
+```ruby
+module Archivable
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def archive_after
+      30.days  # Default
+    end
+  end
+
+  included do
+    scope :archivable, -> { where(created_at: ..archive_after.ago) }
+  end
+end
+
+class Order < ApplicationRecord
+  include Archivable
+
+  def self.archive_after
+    90.days  # Override
+  end
+end
+```
+
+**Testing concerns:**
+Use shared examples that any including model can run:
+
+```ruby
+RSpec.shared_examples "a searchable model" do
+  describe ".search" do
+    it "finds records matching the query" do
+      matching = create(described_class.model_name.singular, name: "Rubyn Widget")
+      non_matching = create(described_class.model_name.singular, name: "Other Thing")
+
+      results = described_class.search("rubyn")
+      expect(results).to include(matching)
+      expect(results).not_to include(non_matching)
+    end
+
+    it "returns all records for blank query" do
+      create(described_class.model_name.singular)
+      expect(described_class.search("")).to eq(described_class.all)
+    end
+  end
+end
+
+# In each model spec
+RSpec.describe User do
+  it_behaves_like "a searchable model"
+end
+
+RSpec.describe Product do
+  it_behaves_like "a searchable model"
+end
+```
+
+**Concern vs STI (Single Table Inheritance):**
+Use STI when models share a database table and have an "is-a" relationship (AdminUser is a User). Use concerns when models share behavior but have separate tables and no inheritance relationship (both User and Product are searchable, but a User is not a Product).

data/skills/rails/controllers.md

@@ -0,0 +1,190 @@
+# Rails: Skinny Controllers
+
+## Pattern
+
+Controllers handle HTTP concerns only: receive params, delegate to a service or model, respond with the appropriate format and status code. Business logic, data transformation, and side effects live elsewhere.
+
+A well-structured controller action follows this shape:
+
+```ruby
+# app/controllers/orders_controller.rb
+class OrdersController < ApplicationController
+  before_action :set_order, only: [:show, :update, :destroy]
+
+  def index
+    @orders = Current.user.orders.recent.page(params[:page])
+  end
+
+  def show
+  end
+
+  def create
+    result = Orders::CreateService.call(order_params, current_user)
+
+    if result.success?
+      redirect_to result.order, notice: "Order placed."
+    else
+      @order = result.order
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    if @order.update(order_params)
+      redirect_to @order, notice: "Order updated."
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @order.destroy
+    redirect_to orders_path, notice: "Order deleted."
+  end
+
+  private
+
+  def set_order
+    @order = Current.user.orders.find(params[:id])
+  end
+
+  def order_params
+    params.require(:order).permit(:shipping_address, :notes)
+  end
+end
+```
+
+Key principles:
+- Each action is 1-5 lines of logic (excluding private methods)
+- `before_action` for shared record loading
+- Private methods only for param filtering and record lookup
+- No business logic, no conditional branching beyond success/failure
+- Delegate complex operations to service objects
+- Use `Current` attributes or scoped queries — never `Order.find(params[:id])` without scoping to the user
+
+When an action needs more than simple CRUD, add a new controller rather than a new action:
+
+```ruby
+# Instead of orders_controller#cancel, create:
+# app/controllers/order_cancellations_controller.rb
+class OrderCancellationsController < ApplicationController
+  def create
+    @order = Current.user.orders.find(params[:order_id])
+    result = Orders::CancelService.call(@order, current_user)
+
+    if result.success?
+      redirect_to @order, notice: "Order cancelled."
+    else
+      redirect_to @order, alert: result.error
+    end
+  end
+end
+
+# config/routes.rb
+resources :orders do
+  resource :cancellation, only: [:create]
+end
+```
+
+## Why This Is Good
+
+- **Readable at a glance.** A new developer can open any controller and understand what every endpoint does in seconds. There's no business logic to parse — just HTTP flow.
+- **Testable via request specs.** Thin controllers are tested through HTTP (request specs), which tests the real behavior. No need for brittle controller unit tests.
+- **Consistent across the team.** Every controller follows the same 5-line-action pattern. Code reviews are faster because the shape is predictable.
+- **RESTful by design.** Adding new controllers instead of new actions keeps the app RESTful. `OrderCancellationsController#create` is clearer than `OrdersController#cancel`.
+- **Forces good architecture.** When you can't put logic in the controller, you're forced to find the right home for it — service objects, models, form objects, or query objects.
+
+## Anti-Pattern
+
+A controller with business logic, conditional branching, direct mailer calls, and inline data transformations:
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    @order = Order.new(order_params)
+    @order.user = current_user
+
+    # Business logic in controller
+    @order.line_items.each do |item|
+      product = Product.find(item.product_id)
+      if product.stock < item.quantity
+        flash[:alert] = "#{product.name} only has #{product.stock} left"
+        render :new and return
+      end
+      item.unit_price = product.price
+      item.total = product.price * item.quantity
+    end
+
+    @order.subtotal = @order.line_items.sum(&:total)
+    @order.tax = @order.subtotal * 0.08
+    @order.total = @order.subtotal + @order.tax
+
+    if current_user.loyalty_points >= 100
+      discount = (@order.total * 0.1).round(2)
+      @order.discount = discount
+      @order.total -= discount
+      current_user.update(loyalty_points: current_user.loyalty_points - 100)
+    end
+
+    if @order.save
+      @order.line_items.each do |item|
+        product = Product.find(item.product_id)
+        product.update!(stock: product.stock - item.quantity)
+      end
+      OrderMailer.confirmation(@order).deliver_later
+      AdminMailer.new_order(@order).deliver_later if @order.total > 500
+      redirect_to @order, notice: "Order placed!"
+    else
+      render :new
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **50+ lines for one action.** A developer has to read the entire method to understand what creating an order involves. The HTTP concerns (params, render, redirect) are buried among price calculations and stock updates.
+- **Untestable in isolation.** To test order creation you must make HTTP requests, set up products with stock levels, loyalty points, and assert mailer deliveries — all in one test.
+- **Logic is trapped.** When you need to create orders from an API endpoint, a Sidekiq job, or the console, you can't. The logic is locked inside an HTTP controller action.
+- **Multiple responsibilities.** This action validates stock, calculates prices, applies discounts, manages loyalty points, updates inventory, and sends emails. Changing any one of these risks breaking the others.
+- **Missing status codes.** The failure case renders `:new` without `status: :unprocessable_entity`, which breaks Turbo and returns 200 on validation failure.
+
+## When To Apply
+
+Always. Every Rails controller should follow skinny principles. The question isn't "should this controller be skinny?" — it's "where does the extracted logic go?"
+
+- Simple CRUD (save one record, no side effects) → logic stays in the model
+- Complex creation/updates (multiple models, side effects) → service object
+- Complex validations (virtual attributes, multi-model validation) → form object
+- Complex queries (reporting, search, filtering) → query object
+- Shared controller behavior (auth, pagination, error handling) → controller concern
+
+## When NOT To Apply
+
+There is no case where a fat controller is the right choice. However, there are cases where extracting logic is premature:
+
+- A 3-line create action that saves a record and redirects does NOT need a service object. The controller is already skinny.
+- Simple `before_action` callbacks for setting records are fine in the controller. They don't need extraction.
+- Standard `params.require().permit()` belongs in the controller, not in a separate class (unless the params logic itself is complex — then use a form object).
+
+## Edge Cases
+
+**The action is 8 lines but all the logic is param handling:**
+That's a sign you need a form object, not a service object. If you're transforming, nesting, or conditionally including params, extract to a form object.
+
+**You need to return different formats (HTML, JSON, CSV):**
+Use `respond_to` blocks in the controller — format selection IS an HTTP concern. But keep the data preparation in a service or query object.
+
+```ruby
+def index
+  @orders = Orders::SearchQuery.call(search_params)
+  respond_to do |format|
+    format.html
+    format.json { render json: OrderSerializer.new(@orders) }
+    format.csv { send_data Orders::CsvExporter.call(@orders), filename: "orders.csv" }
+  end
+end
+```
+
+**The team uses `before_action` for everything:**
+Before actions are good for record loading and auth checks. They're bad for business logic. If a before action does more than `set_X` or `authorize_X`, it's hiding complexity in the wrong place.

data/skills/rails/engines.md

@@ -0,0 +1,201 @@
+# Rails: Engines
+
+## Pattern
+
+A Rails engine is a miniature Rails application that can be mounted inside a host app. Engines package controllers, models, views, routes, and assets into a self-contained, reusable component. Use them for features that are isolated from the host app's domain — admin panels, dev tools, billing dashboards, and embeddable widgets.
+
+```ruby
+# Generate a mountable engine
+# rails plugin new rubyn --mountable
+
+# lib/rubyn/engine.rb
+module Rubyn
+  class Engine < ::Rails::Engine
+    isolate_namespace Rubyn
+
+    # Engine-specific configuration
+    config.generators do |g|
+      g.test_framework :rspec
+      g.assets false  # Engine manages its own assets
+    end
+
+    # Initializers run when the host app boots
+    initializer "rubyn.assets" do |app|
+      app.config.assets.precompile += %w[rubyn/application.css rubyn/application.js] if app.config.respond_to?(:assets)
+    end
+  end
+end
+```
+
+```ruby
+# Engine routes — completely isolated from host app
+# config/routes.rb (inside the engine)
+Rubyn::Engine.routes.draw do
+  root to: "dashboard#show"
+
+  resources :files, only: [:index, :show]
+  resource :agent, only: [:show, :create]
+
+  namespace :ai do
+    post :refactor
+    post :review
+    post :spec
+  end
+
+  resource :settings, only: [:show, :update]
+end
+```
+
+```ruby
+# Host app mounts the engine
+# config/routes.rb (host app)
+Rails.application.routes.draw do
+  mount Rubyn::Engine => "/rubyn" if Rails.env.development?
+
+  # Host app's own routes
+  resources :orders
+end
+```
+
+### Engine Controllers
+
+```ruby
+# app/controllers/rubyn/application_controller.rb
+module Rubyn
+  class ApplicationController < ActionController::Base
+    layout "rubyn/application"  # Engine's own layout
+
+    before_action :verify_development_environment
+
+    private
+
+    def verify_development_environment
+      head :forbidden unless Rails.env.development?
+    end
+
+    # Engine reads credentials from the user's local config
+    def rubyn_api_key
+      @rubyn_api_key ||= Rubyn::Config.api_key
+    end
+  end
+end
+
+# app/controllers/rubyn/dashboard_controller.rb
+module Rubyn
+  class DashboardController < ApplicationController
+    def show
+      @project_info = Rubyn::ProjectScanner.scan(Rails.root)
+      @credit_balance = Rubyn::ApiClient.new(rubyn_api_key).balance
+      @recent_activity = Rubyn::ApiClient.new(rubyn_api_key).recent_interactions(limit: 10)
+    end
+  end
+end
+```
+
+### Engine Views (Self-Contained)
+
+```erb
+<%# app/views/layouts/rubyn/application.html.erb %>
+<%# Engine has its own layout — doesn't depend on host app's layout %>
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Rubyn</title>
+  <%= csrf_meta_tags %>
+  <%= stylesheet_link_tag "rubyn/application", media: "all" %>
+</head>
+<body class="rubyn-app">
+  <nav class="rubyn-nav">
+    <%= link_to "Dashboard", rubyn.root_path %>
+    <%= link_to "Files", rubyn.files_path %>
+    <%= link_to "Agent", rubyn.agent_path %>
+    <%= link_to "Settings", rubyn.settings_path %>
+  </nav>
+
+  <main>
+    <%= yield %>
+  </main>
+
+  <%= javascript_include_tag "rubyn/application" %>
+</body>
+</html>
+```
+
+### Namespace Isolation
+
+```ruby
+# isolate_namespace ensures the engine doesn't pollute the host app
+
+# Engine model — lives in rubyn_ prefixed tables
+module Rubyn
+  class Interaction < ApplicationRecord
+    # Table: rubyn_interactions (not interactions)
+  end
+end
+
+# Engine routes are namespaced
+rubyn.root_path        # => "/rubyn"
+rubyn.files_path       # => "/rubyn/files"
+main_app.orders_path   # => "/orders" (host app routes)
+
+# In engine views, explicitly reference host vs engine routes:
+<%= link_to "Back to app", main_app.root_path %>
+<%= link_to "Dashboard", rubyn.root_path %>
+```
+
+## Why This Is Good
+
+- **Complete isolation.** The engine has its own namespace, routes, views, assets, and optionally its own database tables. It can't accidentally conflict with the host app's controllers or styles.
+- **Mountable with one line.** `mount Rubyn::Engine => "/rubyn"` — the host app adds one line and gets a full-featured dev dashboard.
+- **Development-only by default.** `if Rails.env.development?` ensures the engine never accidentally runs in production.
+- **Self-contained assets.** The engine ships its own CSS and JavaScript. No dependency on the host app's Tailwind config, asset pipeline, or build tools.
+- **Shareable across projects.** Package the engine as a gem, install it in any Rails project, mount it — instant dev tools.
+
+## When To Apply
+
+- **Dev tools** — dashboards, profilers, debug panels, AI coding assistants. Features that help developers but shouldn't exist in production.
+- **Admin panels** — self-contained admin interfaces with their own auth, layout, and styles.
+- **Shared features across apps** — authentication, billing, notifications, CMS. Build once, mount in multiple apps.
+- **Rubyn itself** — the mountable web UI is an engine inside the `rubyn` gem.
+
+## When NOT To Apply
+
+- **Feature that's tightly coupled to the host app's domain.** If the feature needs to share models, validations, and business logic with the host app, it's not a good engine candidate — it's just part of the app.
+- **Simple shared code.** A few utility methods shared across apps should be a gem with modules, not an engine with controllers and views.
+- **One-off features.** Don't engine-ify something used in only one app. Engines add architectural overhead.
+
+## Edge Cases
+
+**Engine accessing host app's models:**
+```ruby
+# The engine can reference host app models if they exist
+class Rubyn::DashboardController < Rubyn::ApplicationController
+  def show
+    # Access host app's models — works but creates coupling
+    @user_count = ::User.count if defined?(::User)
+  end
+end
+```
+Minimize this — the engine should work without knowing the host app's models.
+
+**Testing engines:**
+```ruby
+# The engine includes a dummy Rails app for testing
+# test/dummy/ contains a minimal Rails app that mounts the engine
+# spec/dummy/ for RSpec
+
+# spec/requests/rubyn/dashboard_spec.rb
+RSpec.describe "Rubyn::Dashboard", type: :request do
+  it "shows the dashboard" do
+    get rubyn.root_path
+    expect(response).to have_http_status(:ok)
+  end
+end
+```
+
+**Engine migrations:**
+```bash
+# Copy engine migrations to host app
+rails rubyn:install:migrations
+rails db:migrate
+```