rubyn-code 0.1.0

data/skills/sinatra/middleware_and_deployment.md

@@ -0,0 +1,221 @@
+# Sinatra: Middleware, Configuration, and Deployment
+
+## Pattern
+
+Sinatra apps are Rack apps. Use Rack middleware for cross-cutting concerns, environment-specific configuration for different stages, and standard deployment patterns for production.
+
+### Middleware Stack
+
+```ruby
+# app/api.rb
+module MyApp
+  class Api < Sinatra::Base
+    # Request/Response middleware
+    use Rack::JSONBodyParser                    # Parse JSON bodies into params
+    use Rack::Cors do                            # CORS for API clients
+      allow do
+        origins "*"
+        resource "/api/*", headers: :any, methods: [:get, :post, :put, :delete]
+      end
+    end
+
+    # Custom middleware
+    use RequestLogger                            # Log every request
+    use RateLimiter, limit: 100, period: 60      # 100 req/min
+  end
+end
+```
+
+```ruby
+# app/middleware/request_logger.rb
+class RequestLogger
+  def initialize(app)
+    @app = app
+    @logger = Logger.new($stdout)
+  end
+
+  def call(env)
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    status, headers, body = @app.call(env)
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+    @logger.info("#{env['REQUEST_METHOD']} #{env['PATH_INFO']} → #{status} (#{(elapsed * 1000).round}ms)")
+
+    [status, headers, body]
+  end
+end
+```
+
+```ruby
+# app/middleware/rate_limiter.rb
+class RateLimiter
+  def initialize(app, limit: 60, period: 60)
+    @app = app
+    @limit = limit
+    @period = period
+    @store = {}  # Use Redis in production
+  end
+
+  def call(env)
+    key = client_key(env)
+    count = increment(key)
+
+    if count > @limit
+      [429, { "Content-Type" => "application/json", "Retry-After" => @period.to_s },
+       ['{"error":"Rate limited"}']]
+    else
+      @app.call(env)
+    end
+  end
+
+  private
+
+  def client_key(env)
+    ip = env["HTTP_X_FORWARDED_FOR"]&.split(",")&.first || env["REMOTE_ADDR"]
+    token = env["HTTP_AUTHORIZATION"]&.split(" ")&.last
+    "rate:#{token || ip}:#{(Time.now.to_i / @period)}"
+  end
+
+  def increment(key)
+    @store[key] = (@store[key] || 0) + 1
+  end
+end
+```
+
+### Environment Configuration
+
+```ruby
+# app/api.rb
+module MyApp
+  class Api < Sinatra::Base
+    configure do
+      set :root, File.dirname(__FILE__)
+      set :views, File.join(root, "views")
+      set :public_folder, File.join(root, "..", "public")
+
+      # Don't show raw errors to users
+      set :show_exceptions, false
+      set :raise_errors, false
+
+      enable :logging
+    end
+
+    configure :development do
+      set :show_exceptions, :after_handler
+      enable :reloader  # Reloads code on changes (with sinatra-contrib)
+    end
+
+    configure :test do
+      set :raise_errors, true  # Let errors propagate to tests
+    end
+
+    configure :production do
+      enable :logging
+
+      # Force SSL
+      use Rack::SslEnforcer if ENV["FORCE_SSL"]
+    end
+  end
+end
+```
+
+### Database Setup (ActiveRecord or Sequel)
+
+```ruby
+# With sinatra-activerecord gem
+# Gemfile
+gem "sinatra-activerecord"
+gem "pg"
+
+# config/database.yml
+development:
+  adapter: postgresql
+  database: my_app_development
+
+test:
+  adapter: postgresql
+  database: my_app_test
+
+production:
+  url: <%= ENV["DATABASE_URL"] %>
+
+# Rakefile
+require_relative "config/environment"
+require "sinatra/activerecord/rake"
+
+# Now you get: rake db:create, db:migrate, db:seed, etc.
+```
+
+```ruby
+# With Sequel (lightweight alternative)
+# Gemfile
+gem "sequel"
+gem "pg"
+
+# config/environment.rb
+DB = Sequel.connect(ENV.fetch("DATABASE_URL", "postgres://localhost/my_app_dev"))
+Sequel.extension :migration
+
+# db/migrate/001_create_orders.rb
+Sequel.migration do
+  change do
+    create_table(:orders) do
+      primary_key :id
+      String :reference, null: false, unique: true
+      Integer :total, null: false
+      String :status, default: "pending"
+      DateTime :created_at
+      DateTime :updated_at
+    end
+  end
+end
+```
+
+### Deployment (Puma)
+
+```ruby
+# config/puma.rb
+workers ENV.fetch("WEB_CONCURRENCY", 2).to_i
+threads_count = ENV.fetch("MAX_THREADS", 5).to_i
+threads threads_count, threads_count
+
+port ENV.fetch("PORT", 3000)
+environment ENV.fetch("RACK_ENV", "development")
+
+preload_app!
+```
+
+```ruby
+# Procfile (for Heroku/DigitalOcean App Platform)
+web: bundle exec puma -C config/puma.rb
+
+# Docker
+FROM ruby:3.3-slim
+WORKDIR /app
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --without development test
+COPY . .
+EXPOSE 3000
+CMD ["bundle", "exec", "puma", "-C", "config/puma.rb"]
+```
+
+## Why This Is Good
+
+- **Middleware is composable.** Each middleware handles one concern: logging, CORS, rate limiting, SSL. Stack them in any order.
+- **Same Rack ecosystem as Rails.** Rack::Cors, Rack::Attack, and other middleware work identically in Sinatra and Rails.
+- **Lightweight deployment.** A Sinatra app starts in milliseconds and uses ~30MB of RAM. Perfect for microservices and sidecar APIs.
+- **Standard tooling.** Puma, Procfile, Docker — the same deployment stack as Rails. No special Sinatra knowledge needed.
+
+## When To Choose Sinatra
+
+- **Focused API services** — webhook receivers, proxy APIs, embedding service wrappers
+- **Microservices** — small, single-purpose services with 5-15 endpoints
+- **Internal tools** — health dashboards, admin APIs, CLI backend services
+- **When boot time matters** — Lambda functions, short-lived containers
+
+## When To Choose Rails Instead
+
+- **Full-stack web apps** — forms, views, sessions, asset pipeline, mailers
+- **Complex data models** — 20+ tables with associations, migrations, seeds
+- **Team projects** — Rails conventions mean less decision-making and easier onboarding
+- **Rapid prototyping** — Rails generators and scaffolds are faster for CRUD

data/skills/sinatra/testing.md

@@ -0,0 +1,233 @@
+# Sinatra: Testing with Rack::Test
+
+## Pattern
+
+Test Sinatra apps using `rack-test`, which provides HTTP method helpers that hit your app directly (no real HTTP server needed). Tests are fast, isolated, and exercise the full Rack middleware stack.
+
+```ruby
+# Gemfile
+group :test do
+  gem "rack-test"
+  gem "minitest"
+  gem "database_cleaner-active_record"
+end
+```
+
+```ruby
+# test/test_helper.rb
+ENV["RACK_ENV"] = "test"
+
+require_relative "../config/environment"
+require "minitest/autorun"
+require "minitest/pride"
+require "rack/test"
+
+class Minitest::Test
+  include Rack::Test::Methods
+
+  def app
+    MyApp::Api
+  end
+
+  def json_body
+    JSON.parse(last_response.body, symbolize_names: true)
+  end
+
+  def auth_header(user)
+    { "HTTP_AUTHORIZATION" => "Bearer #{user.api_token}" }
+  end
+
+  def post_json(path, body, headers = {})
+    post path, body.to_json, headers.merge("CONTENT_TYPE" => "application/json")
+  end
+end
+```
+
+```ruby
+# test/routes/health_test.rb
+require "test_helper"
+
+class HealthTest < Minitest::Test
+  def test_returns_ok
+    get "/health"
+
+    assert_equal 200, last_response.status
+    assert_equal "ok", json_body[:status]
+  end
+end
+```
+
+```ruby
+# test/routes/orders_test.rb
+require "test_helper"
+
+class OrdersTest < Minitest::Test
+  def setup
+    @user = User.create!(email: "alice@example.com", name: "Alice", api_token: "test-token-123")
+    @order = Order.create!(user: @user, reference: "ORD-001", shipping_address: "123 Main", status: "pending", total: 50_00)
+  end
+
+  def teardown
+    DatabaseCleaner.clean
+  end
+
+  # INDEX
+  def test_index_returns_orders
+    get "/orders", {}, auth_header(@user)
+
+    assert_equal 200, last_response.status
+    assert_equal 1, json_body[:orders].length
+    assert_equal "ORD-001", json_body[:orders].first[:reference]
+  end
+
+  def test_index_requires_auth
+    get "/orders"
+
+    assert_equal 401, last_response.status
+    assert_equal "Unauthorized", json_body[:error]
+  end
+
+  def test_index_only_returns_current_users_orders
+    other_user = User.create!(email: "bob@example.com", name: "Bob", api_token: "bob-token")
+    Order.create!(user: other_user, reference: "ORD-002", shipping_address: "456 Oak", status: "pending", total: 25_00)
+
+    get "/orders", {}, auth_header(@user)
+
+    references = json_body[:orders].map { |o| o[:reference] }
+    assert_includes references, "ORD-001"
+    refute_includes references, "ORD-002"
+  end
+
+  # SHOW
+  def test_show_returns_order
+    get "/orders/#{@order.id}", {}, auth_header(@user)
+
+    assert_equal 200, last_response.status
+    assert_equal "ORD-001", json_body[:order][:reference]
+  end
+
+  def test_show_returns_404_for_missing_order
+    get "/orders/999999", {}, auth_header(@user)
+
+    assert_equal 404, last_response.status
+  end
+
+  # CREATE
+  def test_create_with_valid_params
+    post_json "/orders", {
+      shipping_address: "789 Elm St",
+      line_items: [{ product_id: 1, quantity: 2 }]
+    }, auth_header(@user)
+
+    assert_equal 201, last_response.status
+    assert json_body[:order][:id].present?
+    assert_equal "pending", json_body[:order][:status]
+  end
+
+  def test_create_with_invalid_params
+    post_json "/orders", { shipping_address: "" }, auth_header(@user)
+
+    assert_equal 422, last_response.status
+    assert json_body[:details].any?
+  end
+
+  def test_create_requires_auth
+    post_json "/orders", { shipping_address: "123 Main" }
+
+    assert_equal 401, last_response.status
+  end
+
+  # DELETE
+  def test_delete_removes_order
+    count_before = Order.count
+
+    delete "/orders/#{@order.id}", {}, auth_header(@user)
+
+    assert_equal 200, last_response.status
+    assert_equal count_before - 1, Order.count
+  end
+
+  def test_delete_cannot_remove_other_users_order
+    other_user = User.create!(email: "bob@example.com", name: "Bob", api_token: "bob-token")
+    bobs_order = Order.create!(user: other_user, reference: "ORD-BOB", shipping_address: "456", status: "pending", total: 10_00)
+
+    delete "/orders/#{bobs_order.id}", {}, auth_header(@user)
+
+    assert_equal 404, last_response.status
+    assert Order.exists?(bobs_order.id)  # Still exists
+  end
+end
+```
+
+Testing services (framework-independent):
+
+```ruby
+# test/services/orders/create_service_test.rb
+require "test_helper"
+
+class Orders::CreateServiceTest < Minitest::Test
+  def setup
+    @user = User.create!(email: "alice@example.com", name: "Alice", api_token: "token")
+  end
+
+  def test_creates_order_with_valid_params
+    result = Orders::CreateService.call({ shipping_address: "123 Main" }, @user)
+
+    assert result.success?
+    assert_instance_of Order, result.order
+    assert result.order.persisted?
+  end
+
+  def test_returns_failure_for_invalid_params
+    result = Orders::CreateService.call({ shipping_address: "" }, @user)
+
+    refute result.success?
+    assert result.order.errors[:shipping_address].any?
+  end
+
+  def teardown
+    DatabaseCleaner.clean
+  end
+end
+```
+
+## Why This Is Good
+
+- **No HTTP server needed.** `rack-test` calls the app directly through Rack. Tests run in milliseconds, not seconds.
+- **Full middleware stack.** Authentication middleware, JSON parsing, error handling — all exercised just like production.
+- **`last_response` gives you everything.** Status code, body, headers, content type. Assert on any of them.
+- **Service tests are framework-agnostic.** `Orders::CreateService.call(params, user)` is tested identically whether it's used in Sinatra, Rails, or a CLI tool.
+
+## Key Methods
+
+| Method | Purpose |
+|---|---|
+| `get "/path"` | GET request |
+| `post "/path", body, headers` | POST request |
+| `put "/path", body, headers` | PUT request |
+| `delete "/path"` | DELETE request |
+| `last_response.status` | HTTP status code |
+| `last_response.body` | Response body string |
+| `last_response.headers` | Response headers hash |
+| `last_response.ok?` | Status is 200? |
+| `last_response.redirect?` | Status is 3xx? |
+| `follow_redirect!` | Follow a redirect |
+
+## Anti-Pattern
+
+Testing by starting a real HTTP server:
+
+```ruby
+# BAD: Starting a server for tests
+def setup
+  @server = Thread.new { MyApp::Api.run! port: 4567 }
+  sleep 1  # Wait for server to start
+end
+
+def test_health
+  response = Net::HTTP.get(URI("http://localhost:4567/health"))
+  # Slow, flaky, port conflicts
+end
+```
+
+Use `rack-test` — it's faster, more reliable, and doesn't need network ports.

data/skills/solid/dependency_inversion.md

@@ -0,0 +1,195 @@
+# SOLID: Dependency Inversion Principle (DIP)
+
+## Pattern
+
+High-level modules should not depend on low-level modules. Both should depend on abstractions. In Ruby, this means: depend on duck-typed interfaces (what an object *does*), not on concrete classes (what an object *is*). Inject dependencies rather than hardcoding them.
+
+```ruby
+# GOOD: High-level service depends on an injected abstraction, not a concrete class
+
+class Ai::CompletionService
+  # Depends on: any object that responds to .complete(messages, model:, max_tokens:)
+  # Does NOT depend on: Anthropic::Client specifically
+  def initialize(client:)
+    @client = client
+  end
+
+  def call(prompt, context:)
+    messages = build_messages(prompt, context)
+    response = @client.complete(messages, model: "claude-haiku-4-5-20251001", max_tokens: 4096)
+
+    Result.new(
+      content: response.content,
+      input_tokens: response.input_tokens,
+      output_tokens: response.output_tokens
+    )
+  end
+
+  private
+
+  def build_messages(prompt, context)
+    [
+      { role: "system", content: context },
+      { role: "user", content: prompt }
+    ]
+  end
+end
+
+# Production: real Anthropic client
+client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+service = Ai::CompletionService.new(client: client)
+
+# Tests: fake client — no HTTP, no API key needed
+fake_client = FakeCompletionClient.new(response: "Here is your refactored code...")
+service = Ai::CompletionService.new(client: fake_client)
+
+# Future: OpenAI, Ollama, or any LLM that implements .complete
+ollama_client = Ollama::Client.new(base_url: "http://localhost:11434")
+service = Ai::CompletionService.new(client: ollama_client)
+```
+
+Configuring dependencies at the application level:
+
+```ruby
+# config/initializers/dependencies.rb
+Rails.application.config.after_initialize do
+  # Wire up production dependencies
+  embedding_client = Embeddings::HttpClient.new(
+    base_url: ENV.fetch("EMBEDDING_SERVICE_URL")
+  )
+
+  Rails.application.config.x.embedding_client = embedding_client
+  Rails.application.config.x.ai_client = Anthropic::Client.new(
+    api_key: ENV.fetch("ANTHROPIC_API_KEY")
+  )
+end
+
+# Services pull from config or accept injection
+class Embeddings::IndexService
+  def initialize(client: Rails.application.config.x.embedding_client)
+    @client = client
+  end
+
+  def call(project, files)
+    files.each do |path, content|
+      vectors = @client.embed([content])
+      project.code_embeddings.create!(file_path: path, embedding: vectors.first)
+    end
+  end
+end
+```
+
+DIP with Ruby blocks — the lightest-weight dependency injection:
+
+```ruby
+class Orders::ExportService
+  # The formatter is an injected dependency via block
+  def call(orders, &formatter)
+    formatter ||= method(:default_format)
+    orders.map { |order| formatter.call(order) }
+  end
+
+  private
+
+  def default_format(order)
+    "#{order.reference}: $#{order.total}"
+  end
+end
+
+# Different formats without modifying ExportService
+Orders::ExportService.new.call(orders) { |o| o.to_json }
+Orders::ExportService.new.call(orders) { |o| [o.reference, o.total].join(",") }
+Orders::ExportService.new.call(orders)  # Uses default
+```
+
+## Why This Is Good
+
+- **Swappable dependencies.** Production uses Anthropic, tests use a fake, future uses Ollama — `CompletionService` never changes. The high-level business logic is isolated from low-level API details.
+- **Testable without infrastructure.** Tests inject fakes or doubles. No HTTP calls, no API keys, no external services. Tests run in milliseconds.
+- **Framework-independent business logic.** `CompletionService` doesn't know about Rails, HTTP, or JSON parsing. It knows about messages and responses. The concrete client handles the transport.
+- **Default injection balances convenience and flexibility.** `client: Rails.application.config.x.embedding_client` provides a sensible default while allowing test overrides. Production code doesn't need to specify the client every time.
+
+## Anti-Pattern
+
+Hardcoded dependencies — high-level logic directly instantiates low-level classes:
+
+```ruby
+class Ai::CompletionService
+  def call(prompt, context:)
+    # HARDCODED: directly creates the concrete client
+    client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+
+    messages = build_messages(prompt, context)
+    response = client.messages.create(
+      model: "claude-haiku-4-5-20251001",
+      max_tokens: 4096,
+      messages: messages
+    )
+
+    Result.new(
+      content: response.content.first.text,
+      input_tokens: response.usage.input_tokens,
+      output_tokens: response.usage.output_tokens
+    )
+  end
+end
+```
+
+```ruby
+# Another violation: service directly calls a specific external API
+class Embeddings::IndexService
+  def call(project, files)
+    files.each do |path, content|
+      # HARDCODED: knows the exact URL, HTTP method, headers, and response format
+      response = Faraday.post(
+        "http://embedding-service:8000/embed",
+        { texts: [content] }.to_json,
+        "Content-Type" => "application/json"
+      )
+      vector = JSON.parse(response.body)["embeddings"].first
+      project.code_embeddings.create!(file_path: path, embedding: vector)
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Can't swap the provider.** Moving from Anthropic to OpenAI requires rewriting `CompletionService`. The business logic (building messages, processing responses) is tangled with the transport (HTTP client, API format).
+- **Can't test without the real service.** Testing `CompletionService` requires either a running Anthropic API (slow, expensive, flaky) or complex WebMock stubs that mirror the exact API format. A fake client is simpler.
+- **URL, headers, and JSON parsing inside business logic.** `IndexService` knows about Faraday, URLs, JSON parsing, and response structure. These are transport concerns that belong in a client class, not in the indexing logic.
+- **Environment coupling.** `ENV["ANTHROPIC_API_KEY"]` is read every time the service is called. In tests, you must set the environment variable or the service breaks. With injection, tests pass a fake and never touch ENV.
+
+## When To Apply
+
+- **External services.** API clients, email services, payment gateways, embedding services — always inject these. They're the most common source of hard-to-test, hard-to-swap dependencies.
+- **Cross-cutting concerns.** Logging, caching, metrics — inject them so you can swap implementations (stdout logger vs CloudWatch vs null logger for tests).
+- **Strategy selection.** When behavior varies at runtime (different AI models, different export formats, different notification channels), inject the strategy.
+- **Configuration that varies by environment.** Database connections, API URLs, feature flags — inject via Rails config or environment, not hardcoded values.
+
+## When NOT To Apply
+
+- **Don't inject Ruby standard library classes.** `Array.new`, `Hash.new`, `Time.current` — these are stable, universal dependencies. Injecting them adds ceremony with no benefit.
+- **Don't inject ActiveRecord models.** `User.find(id)` is fine. You don't need to inject a "UserRepository" in Rails — that's Java-style over-abstraction.
+- **Don't inject everything.** Inject *boundaries* — the edges where your code meets external systems. Internal collaborators (one service calling another within your app) can be directly referenced if they're stable.
+
+## Edge Cases
+
+**Circular dependencies:**
+If ServiceA depends on ServiceB and ServiceB depends on ServiceA, you have a design problem. Extract the shared logic into a third class that both depend on.
+
+**Default values vs mandatory injection:**
+Use default values for production dependencies, mandatory injection for things that should always be explicit:
+
+```ruby
+# Default for convenience — production always uses the real client
+def initialize(client: Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"]))
+
+# Mandatory — caller must choose a strategy
+def initialize(processor:)
+  raise ArgumentError, "processor is required" unless processor
+end
+```
+
+**Rails' built-in DIP mechanisms:**
+Rails already uses DIP in many places: `config.active_job.queue_adapter`, `config.cache_store`, `config.active_storage.service`. These are configuration-based dependency injection. Follow the same pattern for your own services.