rubyn-code 0.1.0

data/skills/rails/logging.md

@@ -0,0 +1,198 @@
+# Rails: Logging and Instrumentation
+
+## Pattern
+
+Use structured logging for production observability, `ActiveSupport::Notifications` for custom instrumentation, and tagged logging for request-scoped context. Logs should answer: what happened, when, to whom, and how long it took.
+
+### Structured Logging with Lograge
+
+```ruby
+# Gemfile
+gem "lograge"
+
+# config/environments/production.rb
+config.lograge.enabled = true
+config.lograge.formatter = Lograge::Formatters::Json.new
+
+config.lograge.custom_options = lambda do |event|
+  {
+    user_id: event.payload[:user_id],
+    request_id: event.payload[:request_id],
+    ip: event.payload[:ip],
+    credits_used: event.payload[:credits_used]
+  }.compact
+end
+
+config.lograge.custom_payload do |controller|
+  {
+    user_id: controller.current_user&.id,
+    request_id: controller.request.request_id,
+    ip: controller.request.remote_ip
+  }
+end
+
+# Output per request:
+# {"method":"POST","path":"/api/v1/ai/refactor","format":"json","controller":"Api::V1::Ai::RefactorController",
+#  "action":"create","status":200,"duration":1245.3,"user_id":42,"request_id":"abc-123","credits_used":3}
+```
+
+### Tagged Logging
+
+```ruby
+# config/application.rb
+config.log_tags = [:request_id]  # Adds request ID to every log line
+
+# Custom tags
+config.log_tags = [
+  :request_id,
+  ->(request) { "user:#{request.cookie_jar.signed[:user_id]}" }
+]
+
+# Manual tagging in services
+Rails.logger.tagged("OrderService", "user:#{user.id}") do
+  Rails.logger.info("Creating order")
+  Rails.logger.info("Order created: #{order.id}")
+end
+# [abc-123] [OrderService] [user:42] Creating order
+# [abc-123] [OrderService] [user:42] Order created: 17
+```
+
+### Log Levels Done Right
+
+```ruby
+class Ai::CompletionService
+  def call(prompt, context:)
+    # DEBUG: Detailed info for development troubleshooting — never in production
+    Rails.logger.debug { "Prompt tokens estimate: #{estimate_tokens(prompt)}" }
+
+    # INFO: Normal operations that are useful for monitoring
+    Rails.logger.info("[AI] Request started model=#{@model} user=#{@user.id}")
+
+    response = @client.complete(messages, model: @model, max_tokens: 4096)
+
+    # INFO: Successful completion with metrics
+    Rails.logger.info(
+      "[AI] Request completed model=#{@model} " \
+      "input_tokens=#{response.input_tokens} output_tokens=#{response.output_tokens} " \
+      "duration_ms=#{elapsed_ms} cache_hit=#{response.cache_read_tokens > 0}"
+    )
+
+    response
+  rescue Faraday::TimeoutError => e
+    # WARN: Recoverable problem — retrying or degraded behavior
+    Rails.logger.warn("[AI] Timeout after #{elapsed_ms}ms, retrying (attempt #{retries}/3)")
+    retry if (retries += 1) <= 3
+    raise
+  rescue Anthropic::ApiError => e
+    # ERROR: Failure that needs attention but isn't crashing the app
+    Rails.logger.error("[AI] API error status=#{e.status} message=#{e.message} user=#{@user.id}")
+    raise
+  rescue StandardError => e
+    # FATAL: Unexpected failure — something is seriously wrong
+    Rails.logger.fatal("[AI] Unexpected error: #{e.class}: #{e.message}")
+    Rails.logger.fatal(e.backtrace.first(10).join("\n"))
+    raise
+  end
+end
+```
+
+### Custom Instrumentation with ActiveSupport::Notifications
+
+```ruby
+# Publishing events
+class Credits::DeductionService
+  def call(user, credits)
+    ActiveSupport::Notifications.instrument("credits.deducted", {
+      user_id: user.id,
+      credits: credits,
+      balance_after: user.credit_balance - credits
+    }) do
+      user.deduct_credits!(credits)
+    end
+  end
+end
+
+# Subscribing to events
+# config/initializers/instrumentation.rb
+ActiveSupport::Notifications.subscribe("credits.deducted") do |name, start, finish, id, payload|
+  duration = (finish - start) * 1000
+  Rails.logger.info(
+    "[Credits] Deducted #{payload[:credits]} from user=#{payload[:user_id]} " \
+    "balance=#{payload[:balance_after]} duration=#{duration.round(1)}ms"
+  )
+end
+
+ActiveSupport::Notifications.subscribe("credits.deducted") do |*, payload|
+  StatsD.increment("credits.deducted", tags: ["user:#{payload[:user_id]}"])
+  StatsD.gauge("credits.balance", payload[:balance_after], tags: ["user:#{payload[:user_id]}"])
+end
+
+# Subscribe to Rails built-in events
+ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+  if payload[:duration] > 100  # Log slow queries
+    Rails.logger.warn("[SlowQuery] #{payload[:duration].round(1)}ms: #{payload[:sql]}")
+  end
+end
+
+ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*, payload|
+  if payload[:duration] > 1000  # Log slow requests
+    Rails.logger.warn("[SlowRequest] #{payload[:path]} #{payload[:duration].round(0)}ms")
+  end
+end
+```
+
+### What to Log (and What Not To)
+
+```ruby
+# GOOD: Structured, searchable, useful
+Rails.logger.info("[Orders::Create] Created order=#{order.id} user=#{user.id} total=#{order.total} items=#{order.line_items.count}")
+
+# GOOD: Error with context
+Rails.logger.error("[Payments] Charge failed user=#{user.id} amount=#{amount} error=#{e.message}")
+
+# BAD: Unstructured, unsearchable
+Rails.logger.info("Order created successfully!")
+Rails.logger.info("Something went wrong: #{e}")
+
+# BAD: Logging sensitive data
+Rails.logger.info("User signed in with password: #{params[:password]}")
+Rails.logger.info("API key used: #{api_key}")
+Rails.logger.info("Credit card: #{card_number}")
+
+# BAD: Logging entire objects (huge, contains sensitive fields)
+Rails.logger.info("User: #{user.inspect}")
+Rails.logger.info("Params: #{params.inspect}")
+
+# GOOD: Log only what you need
+Rails.logger.info("[Auth] Sign in user=#{user.id} email=#{user.email} ip=#{request.remote_ip}")
+```
+
+## Why This Is Good
+
+- **Structured logs are searchable.** `user=42 model=haiku duration_ms=345` can be filtered and aggregated in any log platform (Datadog, Papertrail, CloudWatch). "Order created successfully!" can't.
+- **Tagged logging adds context automatically.** Every log line in a request includes the request ID and user ID — no manual threading of context.
+- **`ActiveSupport::Notifications` decouples events from reactions.** The service publishes "credits deducted." Logging subscribes. Metrics subscribes. Alerting subscribes. The service doesn't know about any of them.
+- **Log levels filter noise.** Production runs at `:info`. Development runs at `:debug`. Slow query warnings are `:warn` — they're visible in production without drowning in debug noise.
+
+## Anti-Pattern
+
+```ruby
+# BAD: puts in production code
+puts "Order created"
+
+# BAD: p for debugging left in committed code
+p user.attributes
+
+# BAD: Logging inside a loop (10,000 log lines for 10,000 records)
+users.each { |u| Rails.logger.info("Processing user #{u.id}") }
+
+# BETTER: Log the batch
+Rails.logger.info("[BatchProcess] Processing #{users.count} users")
+```
+
+## When To Apply
+
+- **Every service object** should log entry, exit, and errors with structured key=value pairs.
+- **Lograge in production** — always. Default Rails logging is verbose and unstructured.
+- **`ActiveSupport::Notifications`** for cross-cutting metrics (slow queries, credit usage, API latency).
+- **Never log passwords, API keys, tokens, or PII.**

data/skills/rails/mailers.md

@@ -0,0 +1,180 @@
+# Rails: Mailers
+
+## Pattern
+
+Mailers are the email equivalent of controllers — thin orchestrators that set up data and pick a template. Keep them simple, always deliver asynchronously, use previews for development, and test the envelope (to, from, subject) separately from the content.
+
+```ruby
+# app/mailers/application_mailer.rb
+class ApplicationMailer < ActionMailer::Base
+  default from: "Rubyn <noreply@rubyn.ai>"
+  layout "mailer"
+end
+
+# app/mailers/order_mailer.rb
+class OrderMailer < ApplicationMailer
+  def confirmation(order)
+    @order = order
+    @user = order.user
+
+    mail(
+      to: @user.email,
+      subject: "Order #{@order.reference} Confirmed"
+    )
+  end
+
+  def shipped(order)
+    @order = order
+    @user = order.user
+    @tracking_url = tracking_url(@order.tracking_number)
+
+    mail(
+      to: @user.email,
+      subject: "Your order has shipped!"
+    )
+  end
+
+  def receipt(order)
+    @order = order.includes(:line_items)
+    @user = order.user
+
+    attachments["receipt-#{@order.reference}.pdf"] = Orders::ReceiptPdfService.call(@order)
+
+    mail(
+      to: @user.email,
+      subject: "Receipt for Order #{@order.reference}"
+    )
+  end
+
+  private
+
+  def tracking_url(number)
+    "https://tracking.example.com/#{number}"
+  end
+end
+```
+
+### Always Deliver Asynchronously
+
+```ruby
+# GOOD: deliver_later — enqueues to Active Job (Sidekiq/etc)
+OrderMailer.confirmation(order).deliver_later
+
+# GOOD: deliver_later with delay
+OrderMailer.review_reminder(order).deliver_later(wait: 7.days)
+
+# BAD: deliver_now blocks the request
+OrderMailer.confirmation(order).deliver_now
+# User waits 1-3 seconds for SMTP handshake — terrible UX
+
+# EXCEPTION: deliver_now is fine inside a background job
+class OrderConfirmationJob < ApplicationJob
+  def perform(order_id)
+    order = Order.find(order_id)
+    OrderMailer.confirmation(order).deliver_now  # Already async — job handles the retry
+  end
+end
+```
+
+### Mailer Previews
+
+```ruby
+# test/mailers/previews/order_mailer_preview.rb (or spec/mailers/previews/)
+class OrderMailerPreview < ActionMailer::Preview
+  def confirmation
+    order = Order.first || FactoryBot.create(:order)
+    OrderMailer.confirmation(order)
+  end
+
+  def shipped
+    order = Order.shipped.first || FactoryBot.create(:order, :shipped, tracking_number: "1Z999AA10123456784")
+    OrderMailer.shipped(order)
+  end
+
+  def receipt
+    order = Order.includes(:line_items).first || FactoryBot.create(:order, :with_line_items)
+    OrderMailer.receipt(order)
+  end
+end
+
+# Visit http://localhost:3000/rails/mailers to see rendered previews
+# No actual email sent — just renders the template in the browser
+```
+
+### Views
+
+```erb
+<%# app/views/order_mailer/confirmation.html.erb %>
+<h1>Order Confirmed!</h1>
+<p>Hi <%= @user.name %>,</p>
+<p>Your order <strong><%= @order.reference %></strong> has been confirmed.</p>
+
+<table>
+  <% @order.line_items.each do |item| %>
+    <tr>
+      <td><%= item.product.name %></td>
+      <td><%= item.quantity %></td>
+      <td>$<%= format("%.2f", item.unit_price / 100.0) %></td>
+    </tr>
+  <% end %>
+</table>
+
+<p><strong>Total: $<%= format("%.2f", @order.total / 100.0) %></strong></p>
+<p>Shipping to: <%= @order.shipping_address %></p>
+
+<%= link_to "View Order", order_url(@order) %>
+```
+
+```erb
+<%# app/views/order_mailer/confirmation.text.erb — always provide a text version %>
+Order Confirmed!
+
+Hi <%= @user.name %>,
+
+Your order <%= @order.reference %> has been confirmed.
+
+<% @order.line_items.each do |item| %>
+- <%= item.product.name %> x<%= item.quantity %> — $<%= format("%.2f", item.unit_price / 100.0) %>
+<% end %>
+
+Total: $<%= format("%.2f", @order.total / 100.0) %>
+Shipping to: <%= @order.shipping_address %>
+
+View your order: <%= order_url(@order) %>
+```
+
+## Why This Is Good
+
+- **Thin mailers.** The mailer sets instance variables and calls `mail()`. No business logic, no formatting, no conditionals beyond what's needed for the template.
+- **`deliver_later` is non-blocking.** The user's request completes instantly. The email sends in a background job with automatic retries.
+- **Previews catch visual bugs.** See the rendered email in your browser without sending it. Catch broken layouts, missing data, and formatting issues before they reach users.
+- **Text + HTML versions.** Email clients that don't render HTML (or users who prefer plain text) get a readable version. Also improves spam score.
+- **Attachments via service objects.** PDF generation is delegated to a service, not done inline in the mailer.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Business logic in the mailer
+class OrderMailer < ApplicationMailer
+  def confirmation(order)
+    @order = order
+    @user = order.user
+    @discount = order.total > 100_00 ? "Use code SAVE10 for 10% off!" : nil
+    @recommendations = Product.where.not(id: order.line_items.pluck(:product_id)).limit(3)
+    @user.update!(last_emailed_at: Time.current)  # Side effect in a mailer!
+    mail(to: @user.email, subject: "Order Confirmed")
+  end
+end
+```
+
+## When To Apply
+
+- **Every email.** Use mailers for all outgoing email, even simple ones. Direct `Mail.deliver` bypasses Rails' template rendering, previews, and testing infrastructure.
+- **`deliver_later` always.** The only exception is inside a background job that's already async.
+- **Previews for every mailer.** Set them up once, save hours of "send test email, check inbox, repeat."
+- **Both HTML and text templates.** Plain text is required for accessibility and deliverability.
+
+## When NOT To Apply
+
+- **Transactional SMS or push notifications.** These aren't emails — use dedicated services, not ActionMailer.
+- **Don't put conditional sending logic in the mailer.** "Don't send if user has unsubscribed" belongs in the service that calls the mailer, not in the mailer itself.

data/skills/rails/migrations.md

@@ -0,0 +1,200 @@
+# Rails: Safe Migrations
+
+## Pattern
+
+Write migrations that are safe for zero-downtime deploys. Add indexes concurrently. Never remove columns without a two-step deploy. Use `strong_migrations` gem to catch unsafe operations automatically.
+
+```ruby
+# SAFE: Add a column with a default (Rails 5+ handles this without rewriting the table)
+class AddStatusToOrders < ActiveRecord::Migration[8.0]
+  def change
+    add_column :orders, :priority, :integer, default: 0, null: false
+  end
+end
+```
+
+```ruby
+# SAFE: Add an index concurrently (doesn't lock the table)
+class AddIndexOnOrdersStatus < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def change
+    add_index :orders, :status, algorithm: :concurrently
+  end
+end
+```
+
+```ruby
+# SAFE: Two-step column removal
+# Deploy 1: Stop using the column in code, add ignore
+class IgnoreDeletedAtOnOrders < ActiveRecord::Migration[8.0]
+  def change
+    safety_assured { remove_column :orders, :deleted_at, :datetime }
+  end
+end
+# But first: update the model to ignore the column
+# class Order < ApplicationRecord
+#   self.ignored_columns += ["deleted_at"]
+# end
+```
+
+```ruby
+# SAFE: Rename via add/copy/remove (not rename_column)
+# Step 1: Add new column
+class AddFullNameToUsers < ActiveRecord::Migration[8.0]
+  def change
+    add_column :users, :full_name, :string
+  end
+end
+
+# Step 2: Backfill data (in a separate migration or rake task)
+class BackfillFullName < ActiveRecord::Migration[8.0]
+  def up
+    User.in_batches.update_all("full_name = name")
+  end
+
+  def down
+    # no-op
+  end
+end
+
+# Step 3: (After deploy) Remove old column
+class RemoveNameFromUsers < ActiveRecord::Migration[8.0]
+  def change
+    safety_assured { remove_column :users, :name, :string }
+  end
+end
+```
+
+```ruby
+# SAFE: Add a foreign key constraint
+class AddForeignKeyOnOrders < ActiveRecord::Migration[8.0]
+  def change
+    add_foreign_key :orders, :users, validate: false
+  end
+end
+
+# Separate migration to validate (non-blocking)
+class ValidateForeignKeyOnOrders < ActiveRecord::Migration[8.0]
+  def change
+    validate_foreign_key :orders, :users
+  end
+end
+```
+
+Add `strong_migrations` to catch unsafe operations:
+
+```ruby
+# Gemfile
+gem 'strong_migrations'
+
+# config/initializers/strong_migrations.rb
+StrongMigrations.start_after = 20260101000000
+```
+
+## Why This Is Good
+
+- **Zero-downtime deploys.** The new code deploys while the migration runs. No maintenance window, no "please wait" page, no interruption to users.
+- **Concurrent indexes don't lock.** `algorithm: :concurrently` builds the index without locking the table for writes. A standard `add_index` on a 10-million-row table locks writes for minutes.
+- **Two-step column removal prevents errors.** If you remove a column while old code is still running (during deploy), queries referencing that column fail. Ignoring the column first ensures old code doesn't reference it.
+- **`strong_migrations` catches mistakes.** It raises an error if you try to run an unsafe migration in production, with a helpful message explaining the safe alternative.
+- **Separate validation of foreign keys.** Adding a FK with `validate: false` is instant. Validating it in a separate migration scans the table without blocking writes.
+
+## Anti-Pattern
+
+Migrations that lock tables, remove columns in one step, or change types without safety:
+
+```ruby
+# DANGEROUS: Locks the entire table while building the index
+class AddIndexOnOrdersEmail < ActiveRecord::Migration[8.0]
+  def change
+    add_index :orders, :email  # Blocks writes on large tables
+  end
+end
+```
+
+```ruby
+# DANGEROUS: Removes column while running code may still reference it
+class RemoveLegacyField < ActiveRecord::Migration[8.0]
+  def change
+    remove_column :orders, :old_status  # Active servers still querying old_status
+  end
+end
+```
+
+```ruby
+# DANGEROUS: Changes column type — rewrites entire table, locks it
+class ChangeOrderTotalType < ActiveRecord::Migration[8.0]
+  def change
+    change_column :orders, :total, :decimal, precision: 10, scale: 2
+  end
+end
+```
+
+```ruby
+# DANGEROUS: Data migration mixed with schema migration
+class AddAndBackfillStatus < ActiveRecord::Migration[8.0]
+  def change
+    add_column :orders, :status, :string, default: "pending"
+    Order.update_all(status: "pending")  # Locks table, runs in same transaction
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Table locks block writes.** A standard `add_index` acquires an exclusive lock on the table. On a 10-million-row orders table, this blocks all INSERT/UPDATE/DELETE for 5-30 minutes. Every request that touches orders hangs.
+- **Column removal during deploy breaks requests.** Rails caches the column list at boot. Old servers (still running during rolling deploy) try to SELECT the removed column and get a database error.
+- **Type changes rewrite the entire table.** Changing a column type on a 50-million-row table creates a new copy of the table with the new type, copies all data, then swaps. This locks the table for the entire duration.
+- **Data migrations in schema migrations are dangerous.** They run inside the migration transaction, hold locks longer, and can timeout. If they fail halfway, the schema migration rolls back too. Keep data migrations separate.
+
+## When To Apply
+
+- **Every migration in a production application.** Even if you're small now, building safe habits means you never have to relearn when your tables grow to millions of rows.
+- **`add_index` on any table with more than 10,000 rows** should use `algorithm: :concurrently`.
+- **Any column removal** should use the two-step process: ignore first, remove in a later deploy.
+- **Any column type change** should use the add-new/copy/remove-old pattern.
+- **Data backfills** should be separate from schema changes, use `in_batches`, and run outside the migration transaction.
+
+## When NOT To Apply
+
+- **Brand new tables** (no data yet) can have indexes added normally. No need for `concurrently` on an empty table.
+- **Development/test environments** don't need concurrent indexes or two-step removal. These safeguards are for production deploys.
+- **Tiny tables** (reference data with 100 rows) can be modified with standard migrations. The lock duration is negligible.
+
+## Edge Cases
+
+**Adding a NOT NULL column to an existing table:**
+Add the column as nullable first, backfill, then add the constraint:
+
+```ruby
+# Step 1
+add_column :orders, :region, :string
+
+# Step 2 (separate migration)
+Order.in_batches.update_all(region: "us")
+
+# Step 3 (separate migration)
+change_column_null :orders, :region, false
+```
+
+**Adding a column with a default on PostgreSQL:**
+Rails 5+ with PostgreSQL adds the default at the column metadata level, not by rewriting the table. This is safe and instant. But always verify your Rails and PostgreSQL versions support this.
+
+**`reversible` for complex migrations:**
+
+```ruby
+class AddStatusIndex < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def change
+    reversible do |dir|
+      dir.up { add_index :orders, :status, algorithm: :concurrently }
+      dir.down { remove_index :orders, :status }
+    end
+  end
+end
+```
+
+**Renaming tables:**
+Don't. Add a new table, migrate data, drop the old one. Or use a database view as an alias during the transition.