rubyn-code 0.1.0

data/skills/ruby_project/rake_tasks.md

@@ -0,0 +1,146 @@
+# Ruby: Rake Tasks
+
+## Pattern
+
+Rake is Ruby's task runner. Organize tasks in namespaces, document them with descriptions, and keep task bodies thin by delegating to service objects or scripts.
+
+```ruby
+# Rakefile
+require_relative "config/environment"
+
+# Import tasks from lib/tasks/
+Dir[File.join(__dir__, "lib", "tasks", "**", "*.rake")].each { |f| load f }
+```
+
+```ruby
+# lib/tasks/db.rake
+namespace :db do
+  desc "Sync best practice documents to database and generate embeddings"
+  task sync_best_practices: :environment do
+    puts "Syncing best practices..."
+    result = BestPractices::SyncService.call
+    puts "Synced #{result.created} new, updated #{result.updated}, removed #{result.removed}"
+  end
+
+  desc "Backfill embeddings for documents missing them"
+  task backfill_embeddings: :environment do
+    documents = BestPracticeDocument.where(embedding: nil)
+    puts "Backfilling #{documents.count} documents..."
+
+    documents.find_each do |doc|
+      Embeddings::DocumentEmbedder.call(doc)
+      print "."
+    end
+
+    puts "\nDone!"
+  end
+
+  desc "Reset all embeddings (re-embed everything)"
+  task reset_embeddings: :environment do
+    abort("This will delete all embeddings. Run with CONFIRM=true") unless ENV["CONFIRM"] == "true"
+
+    CodeEmbedding.delete_all
+    BestPracticeDocument.update_all(embedding: nil, last_embedded_at: nil)
+    puts "All embeddings cleared. Run db:backfill_embeddings to regenerate."
+  end
+end
+```
+
+```ruby
+# lib/tasks/credits.rake
+namespace :credits do
+  desc "Report credit usage for the current month"
+  task monthly_report: :environment do
+    report = Credits::MonthlyReportService.call(Date.current)
+
+    puts "=== Credit Report: #{Date.current.strftime('%B %Y')} ==="
+    puts "Total users: #{report.active_users}"
+    puts "Total credits used: #{report.total_credits}"
+    puts "Total revenue: $#{format('%.2f', report.revenue / 100.0)}"
+    puts "Average credits/user: #{report.avg_per_user}"
+  end
+
+  desc "Grant credits to a user (usage: rake credits:grant USER_ID=1 AMOUNT=100)"
+  task grant: :environment do
+    user_id = ENV.fetch("USER_ID") { abort "USER_ID required" }
+    amount = ENV.fetch("AMOUNT") { abort "AMOUNT required" }.to_i
+    abort "AMOUNT must be positive" unless amount > 0
+
+    user = User.find(user_id)
+    user.credit_ledger_entries.create!(amount: amount, description: "Manual grant via rake")
+    puts "Granted #{amount} credits to #{user.email}. New balance: #{user.credit_balance}"
+  end
+end
+```
+
+```ruby
+# lib/tasks/data.rake
+namespace :data do
+  desc "Import orders from CSV (usage: rake data:import_orders FILE=orders.csv)"
+  task import_orders: :environment do
+    file = ENV.fetch("FILE") { abort "FILE required" }
+    abort "File not found: #{file}" unless File.exist?(file)
+
+    imported = 0
+    errors = 0
+
+    CSV.foreach(file, headers: true) do |row|
+      result = Orders::ImportService.call(row.to_h)
+      if result.success?
+        imported += 1
+      else
+        errors += 1
+        puts "Row #{$.}: #{result.error}"
+      end
+    end
+
+    puts "Imported: #{imported}, Errors: #{errors}"
+  end
+end
+```
+
+### Default Task and Test Task
+
+```ruby
+# Rakefile
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+```
+
+## Why This Is Good
+
+- **`desc` makes tasks discoverable.** `rake -T` lists all tasks with descriptions. Undocumented tasks are invisible.
+- **Namespaces organize tasks.** `rake db:sync_best_practices`, `rake credits:grant`, `rake data:import_orders` — clear, grouped, no collisions.
+- **ENV parameters for input.** `USER_ID=1 AMOUNT=100 rake credits:grant` is explicit and scriptable. No interactive prompts.
+- **Task bodies are thin.** The task calls a service object. The service contains the logic, is testable, and reusable outside of rake.
+- **Safety guards for destructive tasks.** `abort unless ENV["CONFIRM"]` prevents accidental data deletion.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Business logic inside the rake task
+task :process_orders do
+  Order.where(status: :pending).each do |order|
+    order.line_items.each do |item|
+      product = Product.find(item.product_id)
+      product.update!(stock: product.stock - item.quantity)
+    end
+    order.update!(status: :confirmed)
+    OrderMailer.confirmation(order).deliver_now
+  end
+end
+# 10 lines of untestable, unreusable business logic
+```
+
+## When To Apply
+
+- **Every operational task.** Data migrations, reporting, manual operations, maintenance scripts.
+- **One-off tasks stay in Rake.** Don't build an admin UI for a task you'll run once.
+- **Keep the body under 10 lines.** If it's longer, extract to a service object.

data/skills/ruby_project/structure.md

@@ -0,0 +1,261 @@
+# Ruby: Project Structure
+
+## Pattern
+
+Whether you're building a gem, a CLI tool, or a library, follow Ruby conventions for directory layout, naming, and require paths. Use Bundler's gem skeleton as the starting point.
+
+### Standard Ruby Gem / Library Layout
+
+```
+my_gem/
+├── lib/
+│   ├── my_gem.rb              # Main entry point, requires sub-files
+│   └── my_gem/
+│       ├── version.rb
+│       ├── configuration.rb
+│       ├── client.rb
+│       ├── models/
+│       │   ├── order.rb
+│       │   └── user.rb
+│       └── errors.rb
+├── test/                       # or spec/
+│   ├── test_helper.rb
+│   ├── my_gem/
+│   │   ├── client_test.rb
+│   │   └── models/
+│   │       └── order_test.rb
+│   └── integration/
+│       └── api_test.rb
+├── bin/
+│   └── my_gem                  # CLI executable (if applicable)
+├── Gemfile
+├── Rakefile
+├── my_gem.gemspec
+├── README.md
+├── LICENSE.txt
+└── CHANGELOG.md
+```
+
+### The Main Entry Point
+
+```ruby
+# lib/my_gem.rb
+require_relative "my_gem/version"
+require_relative "my_gem/configuration"
+require_relative "my_gem/errors"
+require_relative "my_gem/client"
+
+module MyGem
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def reset!
+      self.configuration = Configuration.new
+    end
+  end
+end
+```
+
+```ruby
+# lib/my_gem/version.rb
+module MyGem
+  VERSION = "1.0.0"
+end
+```
+
+```ruby
+# lib/my_gem/configuration.rb
+module MyGem
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :logger
+
+    def initialize
+      @base_url = "https://api.example.com"
+      @timeout = 30
+      @logger = Logger.new($stdout)
+    end
+  end
+end
+```
+
+```ruby
+# lib/my_gem/errors.rb
+module MyGem
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+  class ApiError < Error
+    attr_reader :status, :body
+    def initialize(message, status:, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+end
+```
+
+```ruby
+# lib/my_gem/client.rb
+require "faraday"
+require "json"
+
+module MyGem
+  class Client
+    def initialize(api_key: nil, base_url: nil)
+      config = MyGem.configuration || Configuration.new
+      @api_key = api_key || config.api_key
+      @base_url = base_url || config.base_url
+      @conn = build_connection
+    end
+
+    def get_order(id)
+      response = @conn.get("/orders/#{id}")
+      handle_response(response)
+    end
+
+    def create_order(params)
+      response = @conn.post("/orders", params.to_json)
+      handle_response(response)
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: @base_url) do |f|
+        f.request :json
+        f.response :json
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+        f.options.timeout = MyGem.configuration&.timeout || 30
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299 then response.body
+      when 401 then raise AuthenticationError, "Invalid API key"
+      when 429 then raise RateLimitError, "Rate limited"
+      else raise ApiError.new("API error", status: response.status, body: response.body)
+      end
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+# Configuration (once, at boot)
+MyGem.configure do |config|
+  config.api_key = ENV["MY_GEM_API_KEY"]
+  config.timeout = 60
+end
+
+# Usage
+client = MyGem::Client.new
+order = client.get_order(123)
+```
+
+### The Gemspec
+
+```ruby
+# my_gem.gemspec
+Gem::Specification.new do |spec|
+  spec.name          = "my_gem"
+  spec.version       = MyGem::VERSION
+  spec.authors       = ["Your Name"]
+  spec.email         = ["you@example.com"]
+  spec.summary       = "A Ruby client for the Example API"
+  spec.homepage      = "https://github.com/you/my_gem"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.files = Dir["lib/**/*", "LICENSE.txt", "README.md"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.0"
+
+  # Dev dependencies in Gemfile, not gemspec (modern convention)
+end
+```
+
+### Testing (Minitest)
+
+```ruby
+# test/test_helper.rb
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "my_gem"
+require "minitest/autorun"
+require "minitest/pride"
+require "webmock/minitest"
+
+# Configure for tests
+MyGem.configure do |config|
+  config.api_key = "test-key"
+  config.base_url = "https://api.example.com"
+end
+```
+
+```ruby
+# test/my_gem/client_test.rb
+require "test_helper"
+
+class MyGem::ClientTest < Minitest::Test
+  def setup
+    @client = MyGem::Client.new
+  end
+
+  def test_get_order
+    stub_request(:get, "https://api.example.com/orders/123")
+      .to_return(status: 200, body: { id: 123, status: "pending" }.to_json, headers: { "Content-Type" => "application/json" })
+
+    result = @client.get_order(123)
+
+    assert_equal 123, result["id"]
+    assert_equal "pending", result["status"]
+  end
+
+  def test_raises_on_auth_failure
+    stub_request(:get, "https://api.example.com/orders/123")
+      .to_return(status: 401)
+
+    assert_raises MyGem::AuthenticationError do
+      @client.get_order(123)
+    end
+  end
+
+  def test_raises_on_rate_limit
+    stub_request(:get, "https://api.example.com/orders/123")
+      .to_return(status: 429)
+
+    assert_raises MyGem::RateLimitError do
+      @client.get_order(123)
+    end
+  end
+end
+```
+
+## Why This Is Good
+
+- **Convention over configuration.** `lib/my_gem.rb` → `require "my_gem"`. `lib/my_gem/client.rb` → `MyGem::Client`. The directory structure maps to the module structure.
+- **Block configuration is idiomatic Ruby.** `MyGem.configure { |c| c.api_key = "..." }` is the pattern every Rubyist expects.
+- **Custom error hierarchy.** `rescue MyGem::Error` catches all gem errors. `rescue MyGem::RateLimitError` catches specific ones. Clean, selective handling.
+- **Dependency injection via constructor.** `Client.new(api_key: custom_key)` overrides config for testing. The default reads from global config for convenience.
+- **Development dependencies in Gemfile.** Modern convention keeps dev deps out of the gemspec, keeping the gem lightweight for consumers.
+
+## When To Apply
+
+- **Every Ruby library, gem, or standalone project.** This structure scales from 3 files to 300.
+- **CLI tools.** Add `exe/` or `bin/` directory with the executable script. Use `Thor` or `OptionParser` for argument parsing.
+- **Internal company gems.** Same structure as public gems. Publish to a private gem server (Gemfury, GitHub Packages).
+
+## When NOT To Apply
+
+- **Rails apps.** Rails has its own conventions (`app/`, `config/`, `db/`). Don't fight them.
+- **Single-file scripts.** A 50-line utility script doesn't need a gem structure. Just use `#!/usr/bin/env ruby` and run it.

data/skills/sinatra/application_structure.md

@@ -0,0 +1,241 @@
+# Sinatra: Application Structure
+
+## Pattern
+
+Sinatra apps should be structured for clarity and growth. Small apps can use a single file. Anything beyond a prototype should use the modular style (`Sinatra::Base` subclass) with extracted helpers, services, and a clear directory layout.
+
+### Single-File (Prototypes Only)
+
+```ruby
+# app.rb
+require "sinatra"
+require "json"
+
+get "/health" do
+  content_type :json
+  { status: "ok", timestamp: Time.now.iso8601 }.to_json
+end
+
+get "/orders/:id" do
+  order = Order.find(params[:id])
+  halt 404, { error: "Not found" }.to_json unless order
+
+  content_type :json
+  order.to_json
+end
+```
+
+### Modular Style (Recommended)
+
+```
+my_app/
+├── Gemfile
+├── config.ru
+├── config/
+│   ├── database.yml
+│   └── environment.rb
+├── app/
+│   ├── api.rb              # Main Sinatra app
+│   ├── routes/
+│   │   ├── orders.rb
+│   │   ├── users.rb
+│   │   └── health.rb
+│   ├── models/
+│   │   ├── order.rb
+│   │   └── user.rb
+│   ├── services/
+│   │   └── orders/
+│   │       └── create_service.rb
+│   └── helpers/
+│       ├── auth_helper.rb
+│       └── json_helper.rb
+├── db/
+│   └── migrate/
+├── test/
+│   ├── test_helper.rb
+│   ├── routes/
+│   │   └── orders_test.rb
+│   └── services/
+│       └── orders/
+│           └── create_service_test.rb
+└── Rakefile
+```
+
+```ruby
+# config.ru
+require_relative "config/environment"
+run MyApp::Api
+```
+
+```ruby
+# config/environment.rb
+require "bundler/setup"
+Bundler.require(:default, ENV.fetch("RACK_ENV", "development").to_sym)
+
+require "sinatra/base"
+require "sinatra/json"
+require "sinatra/activerecord"
+
+# Load app files
+Dir[File.join(__dir__, "..", "app", "models", "*.rb")].each { |f| require f }
+Dir[File.join(__dir__, "..", "app", "services", "**", "*.rb")].each { |f| require f }
+Dir[File.join(__dir__, "..", "app", "helpers", "*.rb")].each { |f| require f }
+
+require_relative "../app/api"
+Dir[File.join(__dir__, "..", "app", "routes", "*.rb")].each { |f| require f }
+```
+
+```ruby
+# app/api.rb
+module MyApp
+  class Api < Sinatra::Base
+    register Sinatra::ActiveRecordExtension
+
+    # Configuration
+    configure do
+      set :database_file, "config/database.yml"
+      set :show_exceptions, false
+    end
+
+    configure :development do
+      set :show_exceptions, :after_handler
+    end
+
+    # Middleware
+    use Rack::JSONBodyParser
+
+    # Global helpers
+    helpers AuthHelper
+    helpers JsonHelper
+
+    # Error handling
+    error ActiveRecord::RecordNotFound do
+      halt 404, json_error("Not found")
+    end
+
+    error ActiveRecord::RecordInvalid do |e|
+      halt 422, json_error("Validation failed", details: e.record.errors.full_messages)
+    end
+
+    error do |e|
+      logger.error("#{e.class}: #{e.message}")
+      halt 500, json_error("Internal server error")
+    end
+  end
+end
+```
+
+```ruby
+# app/helpers/auth_helper.rb
+module AuthHelper
+  def authenticate!
+    token = request.env["HTTP_AUTHORIZATION"]&.delete_prefix("Bearer ")
+    halt 401, json_error("Unauthorized") unless token
+
+    @current_user = User.find_by_api_token(token)
+    halt 401, json_error("Invalid token") unless @current_user
+  end
+
+  def current_user
+    @current_user
+  end
+end
+
+# app/helpers/json_helper.rb
+module JsonHelper
+  def json_response(data, status: 200)
+    content_type :json
+    halt status, data.to_json
+  end
+
+  def json_error(message, status: nil, details: nil)
+    content_type :json
+    body = { error: message }
+    body[:details] = details if details
+    body.to_json
+  end
+end
+```
+
+```ruby
+# app/routes/orders.rb
+module MyApp
+  class Api
+    # Routes grouped by resource
+    before "/orders*" do
+      authenticate!
+    end
+
+    get "/orders" do
+      orders = current_user.orders.order(created_at: :desc)
+      json_response(orders: orders.map(&:as_json))
+    end
+
+    get "/orders/:id" do
+      order = current_user.orders.find(params[:id])
+      json_response(order: order.as_json)
+    end
+
+    post "/orders" do
+      result = Orders::CreateService.call(parsed_body, current_user)
+
+      if result.success?
+        json_response({ order: result.order.as_json }, status: 201)
+      else
+        halt 422, json_error("Creation failed", details: result.errors)
+      end
+    end
+
+    delete "/orders/:id" do
+      order = current_user.orders.find(params[:id])
+      order.destroy!
+      json_response({ deleted: true })
+    end
+
+    private
+
+    def parsed_body
+      JSON.parse(request.body.read, symbolize_names: true)
+    rescue JSON::ParserError
+      halt 400, json_error("Invalid JSON")
+    end
+  end
+end
+```
+
+## Why This Is Good
+
+- **Modular `Sinatra::Base` subclass.** The app is a class, not a script. It can be tested, mounted in Rack, and composed with other apps.
+- **Routes in separate files.** Each resource has its own file. Adding a new resource means adding a new file, not editing a growing monolith.
+- **Extracted helpers.** Auth and JSON helpers are reusable modules, not inline code in every route.
+- **Centralized error handling.** `error ActiveRecord::RecordNotFound` handles 404s globally. No `begin/rescue` in every route.
+- **Same service object pattern as Rails.** `Orders::CreateService.call(params, user)` works identically whether it's called from a Sinatra route or a Rails controller.
+
+## Anti-Pattern
+
+A single-file Sinatra app that grows into a 500-line monster:
+
+```ruby
+# BAD: Everything in one file
+require "sinatra"
+require "json"
+
+# 50 lines of config
+# 30 lines of helpers
+# 100 lines of order routes
+# 100 lines of user routes
+# 80 lines of auth routes
+# 50 lines of error handling
+# 90 lines of inline business logic
+```
+
+## When To Apply
+
+- **Every Sinatra app beyond a prototype.** The modular structure takes 10 minutes to set up and prevents every future headache.
+- **API services.** Sinatra is excellent for focused, single-purpose APIs (webhook receivers, microservices, lightweight proxies).
+- **When Rails is too heavy.** Sinatra boots in milliseconds, has minimal dependencies, and is perfect for small services.
+
+## When NOT To Apply
+
+- **If you need forms, views, sessions, mailers, background jobs, and admin panels.** Use Rails. Sinatra can do all of these but you'll end up rebuilding half of Rails.
+- **If the app will grow to 50+ routes.** Sinatra's simplicity becomes a liability at scale. Consider Rails or Hanami.