rubyn-code 0.1.0

data/skills/design_patterns/observer.md

@@ -0,0 +1,177 @@
+# Design Pattern: Observer
+
+## Pattern
+
+Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically. In Rails, this replaces scattered callbacks with explicit, decoupled event handling.
+
+```ruby
+# Simple Ruby observer using ActiveSupport::Notifications (Rails built-in)
+
+# PUBLISHER: fires events after key actions
+class Orders::CreateService
+  def call(params, user)
+    order = user.orders.create!(params)
+
+    # Publish event — doesn't know or care who's listening
+    ActiveSupport::Notifications.instrument("order.created", order: order)
+
+    Result.new(success: true, order: order)
+  rescue ActiveRecord::RecordInvalid => e
+    Result.new(success: false, order: e.record)
+  end
+end
+
+# SUBSCRIBERS: each handles one concern, registered independently
+
+# config/initializers/event_subscribers.rb
+ActiveSupport::Notifications.subscribe("order.created") do |*, payload|
+  order = payload[:order]
+  OrderMailer.confirmation(order).deliver_later
+end
+
+ActiveSupport::Notifications.subscribe("order.created") do |*, payload|
+  order = payload[:order]
+  WarehouseNotificationJob.perform_later(order.id)
+end
+
+ActiveSupport::Notifications.subscribe("order.created") do |*, payload|
+  order = payload[:order]
+  Analytics.track("order_created", order_id: order.id, total: order.total)
+end
+```
+
+Custom event system for more structure:
+
+```ruby
+# app/events/event_bus.rb
+module EventBus
+  SUBSCRIBERS = Hash.new { |h, k| h[k] = [] }
+
+  def self.subscribe(event_name, handler)
+    SUBSCRIBERS[event_name] << handler
+  end
+
+  def self.publish(event_name, **payload)
+    SUBSCRIBERS[event_name].each do |handler|
+      handler.call(**payload)
+    rescue StandardError => e
+      Rails.logger.error("EventBus: #{handler} failed for #{event_name}: #{e.message}")
+      # Don't let one subscriber failure block others
+    end
+  end
+end
+
+# Subscriber classes — focused, testable
+class OrderCreatedHandlers::SendConfirmation
+  def self.call(order:)
+    OrderMailer.confirmation(order).deliver_later
+  end
+end
+
+class OrderCreatedHandlers::NotifyWarehouse
+  def self.call(order:)
+    WarehouseNotificationJob.perform_later(order.id)
+  end
+end
+
+class OrderCreatedHandlers::TrackAnalytics
+  def self.call(order:)
+    Analytics.track("order_created", order_id: order.id, total: order.total)
+  end
+end
+
+# Registration
+EventBus.subscribe("order.created", OrderCreatedHandlers::SendConfirmation)
+EventBus.subscribe("order.created", OrderCreatedHandlers::NotifyWarehouse)
+EventBus.subscribe("order.created", OrderCreatedHandlers::TrackAnalytics)
+
+# Publisher — fires and forgets
+class Orders::CreateService
+  def call(params, user)
+    order = user.orders.create!(params)
+    EventBus.publish("order.created", order: order)
+    Result.new(success: true, order: order)
+  end
+end
+```
+
+## Why This Is Good
+
+- **Publisher doesn't know its subscribers.** `CreateService` publishes "order.created" and moves on. It doesn't import, reference, or depend on mailers, warehouses, or analytics.
+- **Adding new reactions doesn't modify existing code.** Sending a Slack notification on order creation? Add one subscriber. The publisher, the mailer subscriber, and the warehouse subscriber are untouched.
+- **Each subscriber is independently testable.** Test `SendConfirmation.call(order: order)` in isolation — no service, no other subscribers.
+- **Error isolation.** If analytics tracking fails, the email still sends and the warehouse still gets notified. One subscriber's failure doesn't cascade.
+- **Replaces callback chains.** Instead of 5 `after_create` callbacks on the model, there are 5 focused subscriber classes registered in one place.
+
+## Anti-Pattern
+
+Using model callbacks as an implicit observer pattern:
+
+```ruby
+class Order < ApplicationRecord
+  after_create :send_confirmation
+  after_create :notify_warehouse
+  after_create :track_analytics
+  after_create :update_inventory
+  after_create :award_loyalty_points
+
+  private
+
+  def send_confirmation
+    OrderMailer.confirmation(self).deliver_later
+  end
+
+  def notify_warehouse
+    WarehouseApi.notify(id: id)
+  end
+
+  # ... 30 more lines of callback methods
+end
+```
+
+## Why This Is Bad
+
+- **Tightly coupled.** Every subscriber is a method on the model. Adding a new reaction means modifying the model class.
+- **Hidden execution order.** Callbacks run in declaration order, but that's not obvious. Reordering lines changes behavior silently.
+- **Can't skip selectively.** Creating an order in seeds or tests triggers ALL callbacks. There's no way to say "create without notifications."
+- **Transaction danger.** `after_create` runs inside the transaction. If `notify_warehouse` raises, the entire order creation rolls back.
+
+## When To Apply
+
+- **Multiple side effects triggered by one action.** An order is created → send email, notify warehouse, track analytics, update inventory. Each side effect is a subscriber.
+- **Different teams own different reactions.** The billing team owns payment processing, the ops team owns warehouse notifications, the marketing team owns analytics. Each team's code is a separate subscriber.
+- **You want to add/remove reactions without touching the core flow.** Feature flags can enable/disable subscribers without modifying the publisher.
+
+## When NOT To Apply
+
+- **One or two simple side effects.** If creating an order only sends one email, a direct call in the service object is clearer than an event bus.
+- **Synchronous, transactional requirements.** If the side effect MUST succeed for the action to succeed (deducting credits must happen for the AI response to be valid), use direct calls within a transaction — not events.
+- **Don't build an event bus for 3 events.** The overhead of a custom event system isn't justified until you have 10+ events with multiple subscribers each.
+
+## Rails-Specific Alternatives
+
+**`after_commit` for job enqueueing:**
+If you want callback-style simplicity with event-style decoupling:
+
+```ruby
+class Order < ApplicationRecord
+  after_commit :publish_created_event, on: :create
+
+  private
+
+  def publish_created_event
+    OrderCreatedJob.perform_later(id)
+  end
+end
+
+# The job dispatches to handlers
+class OrderCreatedJob < ApplicationJob
+  def perform(order_id)
+    order = Order.find(order_id)
+    OrderCreatedHandlers::SendConfirmation.call(order: order)
+    OrderCreatedHandlers::NotifyWarehouse.call(order: order)
+  end
+end
+```
+
+This is pragmatic for small apps — it uses Rails conventions while keeping handlers extracted.

data/skills/design_patterns/proxy.md

@@ -0,0 +1,140 @@
+# Design Pattern: Proxy
+
+## Pattern
+
+Provide a surrogate or placeholder for another object to control access to it. Proxies add a layer between the client and the real object — for lazy loading, access control, logging, or caching — without the client knowing the difference.
+
+```ruby
+# Caching proxy — caches expensive API calls
+class CachingEmbeddingProxy
+  def initialize(real_client, cache: Rails.cache, ttl: 24.hours)
+    @real_client = real_client
+    @cache = cache
+    @ttl = ttl
+  end
+
+  def embed(texts)
+    cache_key = "embeddings:#{Digest::SHA256.hexdigest(texts.sort.join('|'))}"
+
+    @cache.fetch(cache_key, expires_in: @ttl) do
+      @real_client.embed(texts)
+    end
+  end
+
+  def embed_query(text)
+    # Queries are unique per request — don't cache
+    @real_client.embed_query(text)
+  end
+end
+
+# Usage — caller doesn't know it's a proxy
+client = Embeddings::HttpClient.new(base_url: ENV["EMBEDDING_URL"])
+client = CachingEmbeddingProxy.new(client)
+vectors = client.embed(["class Order; end"])  # Cached after first call
+```
+
+```ruby
+# Access control proxy — checks permissions before delegating
+class AuthorizingProjectProxy
+  def initialize(project, user)
+    @project = project
+    @user = user
+    @membership = project.project_memberships.find_by(user: user)
+  end
+
+  def code_embeddings
+    require_role!(:viewer)
+    @project.code_embeddings
+  end
+
+  def update!(attributes)
+    require_role!(:admin)
+    @project.update!(attributes)
+  end
+
+  def destroy!
+    require_role!(:owner)
+    @project.destroy!
+  end
+
+  def method_missing(method, ...)
+    require_role!(:viewer)
+    @project.public_send(method, ...)
+  end
+
+  def respond_to_missing?(method, include_private = false)
+    @project.respond_to?(method, include_private)
+  end
+
+  private
+
+  ROLE_HIERARCHY = { viewer: 0, member: 1, admin: 2, owner: 3 }.freeze
+
+  def require_role!(minimum)
+    current = ROLE_HIERARCHY[@membership&.role&.to_sym] || -1
+    required = ROLE_HIERARCHY[minimum]
+
+    raise Forbidden, "Requires #{minimum} role" if current < required
+  end
+end
+
+# Usage
+project = AuthorizingProjectProxy.new(project, current_user)
+project.code_embeddings   # Works for viewer+
+project.update!(name: "New Name")  # Only admin+
+project.destroy!           # Only owner
+```
+
+```ruby
+# Lazy loading proxy — defers expensive initialization
+class LazyModelProxy
+  def initialize(&loader)
+    @loader = loader
+    @loaded = false
+    @target = nil
+  end
+
+  def method_missing(method, ...)
+    load_target!
+    @target.public_send(method, ...)
+  end
+
+  def respond_to_missing?(method, include_private = false)
+    load_target!
+    @target.respond_to?(method, include_private)
+  end
+
+  private
+
+  def load_target!
+    unless @loaded
+      @target = @loader.call
+      @loaded = true
+    end
+  end
+end
+
+# Usage — the DB query only runs when you access the object
+expensive_report = LazyModelProxy.new { Report.generate_monthly(Date.current) }
+# No query yet...
+expensive_report.total  # NOW the query runs
+```
+
+## Why This Is Good
+
+- **Transparent to the caller.** The proxy responds to the same methods as the real object. Code that uses the real client works unchanged with the caching proxy.
+- **Separation of concerns.** Caching logic lives in the proxy, not in the client. Auth logic lives in the auth proxy, not in the model.
+- **Composable with other patterns.** A caching proxy can wrap a logging decorator which wraps the real client. Each layer adds one concern.
+
+## When To Apply
+
+- **Caching expensive operations.** API calls, database queries, computations.
+- **Access control.** Check permissions before allowing operations on a resource.
+- **Lazy loading.** Defer initialization of expensive objects until they're actually used.
+- **Remote objects.** Wrap a remote API to look like a local object.
+
+## When NOT To Apply
+
+- **Simple delegation.** If you're just forwarding calls without adding behavior, use `delegate` or `SimpleDelegator` — not a proxy.
+- **Decorator already fits.** Proxies control access. Decorators add behavior. If you're adding behavior (logging, metrics), use a decorator.
+- **The object is cheap to create.** Lazy loading a simple `User.new` adds complexity without benefit.

data/skills/design_patterns/singleton.md

@@ -0,0 +1,124 @@
+# Design Pattern: Singleton
+
+## Pattern
+
+Ensure a class has only one instance and provide a global point of access to it. Ruby provides a built-in `Singleton` module, but in practice you should almost always use module-level state or class methods instead.
+
+### Ruby's Built-In Singleton
+
+```ruby
+require "singleton"
+
+class AppConfig
+  include Singleton
+
+  attr_accessor :api_key, :environment, :log_level
+
+  def initialize
+    @environment = ENV.fetch("RACK_ENV", "development")
+    @log_level = :info
+  end
+end
+
+# Usage
+AppConfig.instance.api_key = "sk-123"
+AppConfig.instance.log_level  # => :info
+
+# .new raises NoMethodError
+AppConfig.new  # => NoMethodError: private method 'new' called
+```
+
+### Better Alternative: Module with State
+
+```ruby
+# More idiomatic Ruby — module with class-level state
+module AppConfig
+  class << self
+    attr_accessor :api_key, :environment, :log_level
+
+    def configure
+      yield self if block_given?
+    end
+
+    def reset!
+      @api_key = nil
+      @environment = "development"
+      @log_level = :info
+    end
+  end
+
+  # Defaults
+  self.environment = ENV.fetch("RACK_ENV", "development")
+  self.log_level = :info
+end
+
+# Usage — cleaner, no .instance call
+AppConfig.configure do |config|
+  config.api_key = "sk-123"
+  config.log_level = :debug
+end
+
+AppConfig.api_key  # => "sk-123"
+```
+
+### Thread-Safe Singleton (When You Actually Need One)
+
+```ruby
+class ConnectionPool
+  include Singleton
+
+  def initialize
+    @mutex = Mutex.new
+    @connections = []
+    @max_size = 10
+  end
+
+  def checkout
+    @mutex.synchronize do
+      @connections.pop || create_connection
+    end
+  end
+
+  def checkin(conn)
+    @mutex.synchronize do
+      @connections.push(conn) if @connections.size < @max_size
+    end
+  end
+
+  private
+
+  def create_connection
+    DatabaseConnection.new
+  end
+end
+```
+
+## When To Apply
+
+- **Connection pools.** A single pool managing shared resources across threads.
+- **Configuration objects.** Global app configuration accessed everywhere (but prefer the module pattern above).
+- **Caches.** A single in-memory cache shared across the application.
+- **Logger instances.** One logger configured once, used everywhere.
+
+## When NOT To Apply (Most of the Time)
+
+- **Don't use Singleton as a global variable.** If you're using Singleton to share state between unrelated classes, you have a coupling problem. Pass dependencies explicitly.
+- **Don't use Singleton in Rails.** Rails has `Rails.application.config`, `Rails.cache`, `Rails.logger`. Use those instead of rolling your own singletons.
+- **Don't use Singleton for testability-killing global state.** Singletons persist across tests, causing test pollution. Module-level state with a `reset!` method is easier to test.
+- **Prefer dependency injection.** Instead of `AppConfig.instance.api_key` deep inside a service, pass the API key as a constructor argument. This makes the dependency explicit and testable.
+
+## Edge Cases
+
+**Singleton + Threads:**
+Ruby's `Singleton` module is thread-safe for instance creation. But the instance's mutable state is NOT thread-safe unless you add synchronization (`Mutex`).
+
+**Testing Singletons:**
+Always provide a `reset!` method:
+
+```ruby
+def teardown
+  AppConfig.reset!
+end
+```
+
+Without this, state leaks between tests and causes order-dependent failures.

data/skills/design_patterns/state.md

@@ -0,0 +1,207 @@
+# Design Pattern: State
+
+## Pattern
+
+Allow an object to change its behavior when its internal state changes by delegating to state objects. Instead of `case` statements on a status field, each state is a class that defines the valid transitions and behavior for that state.
+
+```ruby
+# State classes — each defines what's possible in that state
+module OrderStates
+  class Pending
+    def confirm(order)
+      return Result.new(success: false, error: "No items") if order.line_items.empty?
+
+      order.update!(status: :confirmed, confirmed_at: Time.current)
+      OrderMailer.confirmed(order).deliver_later
+      Result.new(success: true)
+    end
+
+    def cancel(order, reason:)
+      order.update!(status: :cancelled, cancelled_at: Time.current, cancel_reason: reason)
+      Result.new(success: true)
+    end
+
+    def ship(_order) = Result.new(success: false, error: "Cannot ship a pending order")
+    def deliver(_order) = Result.new(success: false, error: "Cannot deliver a pending order")
+  end
+
+  class Confirmed
+    def confirm(_order) = Result.new(success: false, error: "Already confirmed")
+
+    def ship(order)
+      order.update!(status: :shipped, shipped_at: Time.current)
+      OrderMailer.shipped(order).deliver_later
+      Result.new(success: true)
+    end
+
+    def cancel(order, reason:)
+      order.update!(status: :cancelled, cancelled_at: Time.current, cancel_reason: reason)
+      Orders::RefundService.call(order)
+      Result.new(success: true)
+    end
+
+    def deliver(_order) = Result.new(success: false, error: "Must ship before delivering")
+  end
+
+  class Shipped
+    def confirm(_order) = Result.new(success: false, error: "Already shipped")
+    def ship(_order) = Result.new(success: false, error: "Already shipped")
+    def cancel(_order, reason: nil) = Result.new(success: false, error: "Cannot cancel shipped order")
+
+    def deliver(order)
+      order.update!(status: :delivered, delivered_at: Time.current)
+      OrderMailer.delivered(order).deliver_later
+      Result.new(success: true)
+    end
+  end
+
+  class Delivered
+    def confirm(_order) = Result.new(success: false, error: "Already delivered")
+    def ship(_order) = Result.new(success: false, error: "Already delivered")
+    def cancel(_order, reason: nil) = Result.new(success: false, error: "Cannot cancel delivered order")
+    def deliver(_order) = Result.new(success: false, error: "Already delivered")
+  end
+
+  class Cancelled
+    def confirm(_order) = Result.new(success: false, error: "Order is cancelled")
+    def ship(_order) = Result.new(success: false, error: "Order is cancelled")
+    def cancel(_order, reason: nil) = Result.new(success: false, error: "Already cancelled")
+    def deliver(_order) = Result.new(success: false, error: "Order is cancelled")
+  end
+
+  MAPPING = {
+    "pending" => Pending.new,
+    "confirmed" => Confirmed.new,
+    "shipped" => Shipped.new,
+    "delivered" => Delivered.new,
+    "cancelled" => Cancelled.new
+  }.freeze
+
+  def self.for(status)
+    MAPPING.fetch(status)
+  end
+end
+
+# The Order delegates state-dependent behavior
+class Order < ApplicationRecord
+  def current_state
+    OrderStates.for(status)
+  end
+
+  def confirm!
+    current_state.confirm(self)
+  end
+
+  def ship!
+    current_state.ship(self)
+  end
+
+  def cancel!(reason:)
+    current_state.cancel(self, reason: reason)
+  end
+
+  def deliver!
+    current_state.deliver(self)
+  end
+end
+
+# Usage is clean and safe
+order = Order.find(params[:id])
+result = order.confirm!           # Works when pending
+result = order.ship!              # Works when confirmed
+result = order.cancel!(reason: "changed mind")  # Invalid when shipped
+# result.success? => false, result.error => "Cannot cancel shipped order"
+```
+
+## Why This Is Good
+
+- **Invalid transitions return errors, not crashes.** Calling `ship!` on a pending order returns a descriptive error instead of silently doing nothing or raising an exception.
+- **Each state's rules are visible in one place.** Open `Confirmed` to see everything that can happen from the confirmed state. No scanning a 200-line model for scattered `if status == "confirmed"` checks.
+- **Adding a new state means adding one class.** A `Refunded` state is one new class with 4 methods. Existing states don't change.
+- **Testable per state.** Test `Pending#confirm` in isolation — does it update status, send email, return success? Test `Shipped#cancel` — does it return the right error?
+
+## Anti-Pattern
+
+A case/when on status scattered throughout the model:
+
+```ruby
+class Order < ApplicationRecord
+  def confirm!
+    case status
+    when "pending"
+      update!(status: :confirmed, confirmed_at: Time.current)
+      OrderMailer.confirmed(self).deliver_later
+    when "confirmed"
+      raise "Already confirmed"
+    when "shipped", "delivered"
+      raise "Cannot confirm — already #{status}"
+    when "cancelled"
+      raise "Cannot confirm cancelled order"
+    end
+  end
+
+  def ship!
+    case status
+    when "confirmed"
+      update!(status: :shipped, shipped_at: Time.current)
+    when "pending"
+      raise "Must confirm first"
+    # ... another 10 lines of case/when
+    end
+  end
+
+  def cancel!
+    case status
+    when "pending", "confirmed"
+      update!(status: :cancelled)
+      Orders::RefundService.call(self) if status == "confirmed"
+    when "shipped"
+      raise "Cannot cancel shipped order"
+    # ... more branching
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **N methods × M states = N×M branches.** 4 actions × 5 states = 20 case branches scattered across 4 methods. Adding a 6th state means editing all 4 methods.
+- **Rules for one state are split across multiple methods.** To understand "what can a confirmed order do?" you read `confirm!`, `ship!`, `cancel!`, and `deliver!` — scanning for `when "confirmed"` in each.
+- **Inconsistent error handling.** Some branches raise, some return nil, some silently do nothing. The State pattern enforces a consistent return type (`Result`).
+
+## When To Apply
+
+- **An object has 3+ states with different behavior.** Orders (pending/confirmed/shipped/delivered/cancelled), subscriptions (trialing/active/past_due/cancelled), projects (draft/active/archived).
+- **You find yourself writing `case status` or `if object.pending?` in multiple places.** That's the State pattern trying to emerge.
+- **State transitions have side effects.** Confirming sends an email, shipping notifies the warehouse, cancelling triggers a refund. Each state's transitions have different side effects.
+
+## When NOT To Apply
+
+- **Two states with simple behavior.** An `active`/`inactive` boolean with one behavior difference doesn't need state objects. A simple `if active?` is clearer.
+- **Status is display-only.** If the status field only affects what badge is shown in the UI, a helper method or enum is sufficient.
+- **The team uses `aasm` or `statesman` gems.** Follow existing conventions. These gems implement the State pattern with DSL sugar.
+
+## Edge Cases
+
+**State machine gems vs hand-rolled:**
+For simple state machines (3-5 states, clear transitions), hand-rolled state objects are clearer. For complex machines (10+ states, guards, audit trails), consider `statesman` or `aasm`.
+
+**Querying by state:**
+State objects handle behavior. Database queries use the status column directly:
+
+```ruby
+scope :actionable, -> { where(status: %w[pending confirmed]) }
+scope :completed, -> { where(status: %w[delivered cancelled]) }
+```
+
+**Persisting state transitions for audit:**
+
+```ruby
+class OrderStates::Confirmed
+  def ship(order)
+    order.update!(status: :shipped, shipped_at: Time.current)
+    order.state_transitions.create!(from: "confirmed", to: "shipped", actor: Current.user)
+    Result.new(success: true)
+  end
+end
+```