rubyn-code 0.1.0

data/skills/gems/stripe.md

@@ -0,0 +1,224 @@
+# Gems: Stripe Integration
+
+## Pattern
+
+Wrap Stripe behind adapters and service objects. Never call Stripe directly from controllers. Handle webhooks idempotently. Use Stripe's test mode and fixtures for development.
+
+### Service Objects for Stripe Operations
+
+```ruby
+# app/services/billing/create_subscription_service.rb
+module Billing
+  class CreateSubscriptionService
+    def self.call(user, plan:)
+      new(user, plan: plan).call
+    end
+
+    def initialize(user, plan:)
+      @user = user
+      @plan = plan
+    end
+
+    def call
+      customer = find_or_create_customer
+      subscription = Stripe::Subscription.create(
+        customer: customer.id,
+        items: [{ price: price_id_for(@plan) }],
+        payment_behavior: "default_incomplete",
+        expand: ["latest_invoice.payment_intent"]
+      )
+
+      @user.update!(
+        stripe_customer_id: customer.id,
+        stripe_subscription_id: subscription.id,
+        plan: @plan
+      )
+
+      Result.new(success: true, subscription: subscription)
+    rescue Stripe::CardError => e
+      Result.new(success: false, error: "Payment failed: #{e.message}")
+    rescue Stripe::InvalidRequestError => e
+      Rails.logger.error("Stripe error: #{e.message}")
+      Result.new(success: false, error: "Unable to process. Please try again.")
+    end
+
+    private
+
+    def find_or_create_customer
+      if @user.stripe_customer_id.present?
+        Stripe::Customer.retrieve(@user.stripe_customer_id)
+      else
+        Stripe::Customer.create(email: @user.email, name: @user.name)
+      end
+    end
+
+    def price_id_for(plan)
+      {
+        "pro" => ENV.fetch("STRIPE_PRO_PRICE_ID"),
+        "team" => ENV.fetch("STRIPE_TEAM_PRICE_ID")
+      }.fetch(plan)
+    end
+  end
+end
+```
+
+### Webhook Handler
+
+```ruby
+# app/controllers/webhooks/stripe_controller.rb
+class Webhooks::StripeController < ApplicationController
+  skip_before_action :verify_authenticity_token
+  skip_before_action :authenticate_user!
+
+  def create
+    payload = request.body.read
+    sig_header = request.env["HTTP_STRIPE_SIGNATURE"]
+
+    begin
+      event = Stripe::Webhook.construct_event(
+        payload, sig_header, ENV.fetch("STRIPE_WEBHOOK_SECRET")
+      )
+    rescue JSON::ParserError, Stripe::SignatureVerificationError
+      head :bad_request
+      return
+    end
+
+    # Dispatch to handler — idempotently
+    Webhooks::StripeDispatcher.call(event)
+
+    head :ok
+  end
+end
+
+# app/services/webhooks/stripe_dispatcher.rb
+module Webhooks
+  class StripeDispatcher
+    HANDLERS = {
+      "checkout.session.completed" => Webhooks::Stripe::CheckoutCompleted,
+      "invoice.payment_succeeded" => Webhooks::Stripe::InvoicePaymentSucceeded,
+      "invoice.payment_failed" => Webhooks::Stripe::InvoicePaymentFailed,
+      "customer.subscription.updated" => Webhooks::Stripe::SubscriptionUpdated,
+      "customer.subscription.deleted" => Webhooks::Stripe::SubscriptionDeleted,
+    }.freeze
+
+    def self.call(event)
+      handler = HANDLERS[event.type]
+
+      if handler
+        handler.call(event)
+      else
+        Rails.logger.info("Unhandled Stripe webhook: #{event.type}")
+      end
+    end
+  end
+end
+
+# app/services/webhooks/stripe/invoice_payment_succeeded.rb
+module Webhooks
+  module Stripe
+    class InvoicePaymentSucceeded
+      def self.call(event)
+        invoice = event.data.object
+        customer_id = invoice.customer
+
+        user = User.find_by(stripe_customer_id: customer_id)
+        return unless user  # Idempotent — unknown customer is a no-op
+
+        # Idempotent — check if we already processed this invoice
+        return if user.credit_ledger_entries.exists?(stripe_invoice_id: invoice.id)
+
+        Credits::GrantService.call(
+          user: user,
+          amount: credits_for_plan(user.plan),
+          source: :subscription_grant,
+          description: "Monthly credit grant",
+          stripe_invoice_id: invoice.id
+        )
+      end
+
+      private_class_method def self.credits_for_plan(plan)
+        { "pro" => 1000, "team" => 5000 }.fetch(plan, 0)
+      end
+    end
+  end
+end
+```
+
+### Testing Stripe
+
+```ruby
+# spec/services/billing/create_subscription_service_spec.rb
+RSpec.describe Billing::CreateSubscriptionService do
+  let(:user) { create(:user, email: "alice@example.com") }
+
+  before do
+    # Stub Stripe API calls
+    stub_request(:post, "https://api.stripe.com/v1/customers")
+      .to_return(status: 200, body: { id: "cus_test123", email: "alice@example.com" }.to_json)
+
+    stub_request(:post, "https://api.stripe.com/v1/subscriptions")
+      .to_return(status: 200, body: {
+        id: "sub_test456",
+        status: "active",
+        latest_invoice: { payment_intent: { client_secret: "pi_secret" } }
+      }.to_json)
+  end
+
+  it "creates a subscription and updates user" do
+    result = described_class.call(user, plan: "pro")
+
+    expect(result).to be_success
+    expect(user.reload.stripe_customer_id).to eq("cus_test123")
+    expect(user.plan).to eq("pro")
+  end
+end
+
+# spec/requests/webhooks/stripe_spec.rb
+RSpec.describe "Stripe Webhooks", type: :request do
+  let(:payload) { { type: "invoice.payment_succeeded", data: { object: { customer: "cus_123", id: "inv_456" } } }.to_json }
+
+  before do
+    allow(Stripe::Webhook).to receive(:construct_event).and_return(
+      Stripe::Event.construct_from(JSON.parse(payload))
+    )
+  end
+
+  it "returns 200 and processes the event" do
+    user = create(:user, stripe_customer_id: "cus_123", plan: "pro")
+
+    post webhooks_stripe_path, params: payload, headers: { "Stripe-Signature" => "sig" }
+
+    expect(response).to have_http_status(:ok)
+    expect(user.credit_ledger_entries.count).to eq(1)
+  end
+
+  it "returns 200 for unknown event types" do
+    payload = { type: "unknown.event" }.to_json
+    allow(Stripe::Webhook).to receive(:construct_event).and_return(
+      Stripe::Event.construct_from(JSON.parse(payload))
+    )
+
+    post webhooks_stripe_path, params: payload, headers: { "Stripe-Signature" => "sig" }
+
+    expect(response).to have_http_status(:ok)
+  end
+end
+```
+
+## Why This Is Good
+
+- **Service objects wrap Stripe calls.** Controllers stay thin. Stripe-specific error handling is centralized.
+- **Webhook handlers are idempotent.** Stripe may send the same event multiple times. Checking for existing `stripe_invoice_id` prevents double-granting credits.
+- **Dispatcher pattern for webhooks.** New event types get a new handler class — existing handlers are untouched. Open/Closed principle.
+- **Signature verification prevents spoofing.** `construct_event` validates the webhook payload against Stripe's secret.
+- **WebMock for testing.** No real Stripe calls in tests. Stubbed responses are fast, deterministic, and free.
+
+## When To Apply
+
+- **Every Stripe integration.** Always use service objects, always verify webhook signatures, always handle idempotently.
+- **Credit systems.** Webhook-driven credit grants ensure credits are added when payment actually succeeds, not when the user clicks "subscribe."
+
+## When NOT To Apply
+
+- **Don't use Stripe Checkout for simple one-time charges.** Stripe Payment Links or a simple `Stripe::Charge.create` might be simpler for MVP.
+- **Don't build your own billing UI if Stripe's Customer Portal works.** Let Stripe handle plan changes, payment method updates, and invoice history.

data/skills/minitest/assertions.md

@@ -0,0 +1,185 @@
+# Minitest: Assertions
+
+## Pattern
+
+Minitest assertions are simple methods: `assert_*` for positive checks, `refute_*` for negative checks. Choose the most specific assertion for the clearest failure messages.
+
+### Core Assertions
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  # Equality
+  assert_equal 100, order.total                    # Expected vs actual
+  assert_equal "pending", order.status
+  refute_equal 0, order.total                      # Not equal
+
+  # Truthiness
+  assert order.valid?                              # Truthy
+  refute order.shipped?                            # Falsy
+  assert_nil order.cancelled_at                    # Exactly nil
+  refute_nil order.reference                       # Not nil
+
+  # Predicate methods (reads better)
+  assert_predicate order, :valid?                  # Same as assert order.valid?
+  assert_predicate order, :pending?
+  refute_predicate order, :shipped?
+
+  # Includes
+  assert_includes Order.recent, order              # Collection includes item
+  refute_includes Order.recent, old_order
+
+  # Type checking
+  assert_instance_of Order, result                 # Exact class
+  assert_kind_of ApplicationRecord, result         # Class or subclass
+
+  # Pattern matching
+  assert_match /ORD-\d{6}/, order.reference        # Regex match
+  refute_match /INVALID/, order.reference
+
+  # Numeric
+  assert_in_delta 10.5, calculated_tax, 0.01       # Float comparison with tolerance
+  assert_operator order.total, :>, 0               # order.total > 0
+
+  # Exceptions
+  assert_raises ActiveRecord::RecordInvalid do
+    Order.create!(shipping_address: nil)
+  end
+
+  error = assert_raises ArgumentError do
+    Money.new("not a number")
+  end
+  assert_match /invalid/, error.message
+
+  # Empty / present
+  assert_empty order.line_items                     # .empty? is true
+  refute_empty order.errors.full_messages
+
+  # Response assertions (Rails integration tests)
+  assert_response :success                          # 200
+  assert_response :redirect                         # 3xx
+  assert_response :not_found                        # 404
+  assert_response :unprocessable_entity             # 422
+  assert_redirected_to order_path(order)
+
+  # Difference assertions (Rails)
+  assert_difference "Order.count", 1 do
+    post orders_path, params: { order: valid_params }
+  end
+
+  assert_no_difference "Order.count" do
+    post orders_path, params: { order: invalid_params }
+  end
+
+  assert_difference -> { user.reload.credit_balance }, -10 do
+    Credits::DeductionService.call(user, 10)
+  end
+
+  # Multiple differences at once
+  assert_difference ["Order.count", "LineItem.count"], 1 do
+    post orders_path, params: { order: valid_params }
+  end
+
+  # Enqueued jobs
+  assert_enqueued_with(job: OrderConfirmationJob, args: [order.id]) do
+    Orders::CreateService.call(params, user)
+  end
+
+  assert_enqueued_jobs 1 do
+    order.confirm!
+  end
+
+  assert_no_enqueued_jobs do
+    order.update!(notes: "updated")
+  end
+
+  # Emails
+  assert_emails 1 do
+    Orders::CreateService.call(params, user)
+  end
+
+  assert_no_emails do
+    order.update!(shipping_address: "new address")
+  end
+end
+```
+
+### Custom Assertions
+
+```ruby
+# test/support/custom_assertions.rb
+module CustomAssertions
+  def assert_valid(record, msg = nil)
+    assert record.valid?, msg || "Expected #{record.class} to be valid, but got errors: #{record.errors.full_messages.join(', ')}"
+  end
+
+  def assert_invalid(record, *attributes)
+    refute record.valid?, "Expected #{record.class} to be invalid"
+    attributes.each do |attr|
+      assert record.errors[attr].any?, "Expected errors on #{attr}, but found none"
+    end
+  end
+
+  def assert_json_response(*keys)
+    json = JSON.parse(response.body)
+    keys.each do |key|
+      assert json.key?(key.to_s), "Expected JSON to include key '#{key}'"
+    end
+  end
+end
+
+# Include in test_helper.rb
+class ActiveSupport::TestCase
+  include CustomAssertions
+end
+
+# Usage
+test "order is valid with all required fields" do
+  order = Order.new(user: @user, shipping_address: "123 Main")
+  assert_valid order
+end
+
+test "order is invalid without address" do
+  order = Order.new(user: @user)
+  assert_invalid order, :shipping_address
+end
+```
+
+## Why This Is Good
+
+- **Specific assertions give specific failure messages.** `assert_equal 100, order.total` fails with `Expected: 100, Actual: 0`. A bare `assert order.total == 100` fails with `Expected false to be truthy` — useless.
+- **`assert_difference` is concise and safe.** It captures the before value, runs the block, then checks the after value. No manual before/after variables.
+- **`assert_raises` captures the exception.** You can assert on the exception message, not just that it was raised.
+- **Custom assertions DRY up common patterns.** `assert_invalid(order, :email)` is clearer than 3 lines of refute + assert_includes.
+
+## Anti-Pattern
+
+Using `assert` for everything:
+
+```ruby
+# BAD: Bare assert gives terrible failure messages
+assert order.total == 100           # "Expected false to be truthy"
+assert order.errors.any?            # "Expected false to be truthy"
+assert Order.recent.include?(order) # "Expected false to be truthy"
+
+# GOOD: Specific assertions
+assert_equal 100, order.total       # "Expected: 100, Actual: 0"
+refute_empty order.errors           # "Expected [] to not be empty"
+assert_includes Order.recent, order # "Expected [...] to include #<Order ...>"
+```
+
+## Assertion Cheat Sheet
+
+| Want to check... | Use |
+|---|---|
+| Two values are equal | `assert_equal expected, actual` |
+| Value is nil | `assert_nil value` |
+| Value is not nil | `refute_nil value` |
+| Boolean predicate | `assert_predicate obj, :method?` |
+| Collection contains item | `assert_includes collection, item` |
+| String matches pattern | `assert_match /regex/, string` |
+| Code raises exception | `assert_raises(ErrorClass) { code }` |
+| DB record count changes | `assert_difference "Model.count", N { code }` |
+| Floats are close enough | `assert_in_delta expected, actual, delta` |
+| Object is correct type | `assert_instance_of Klass, obj` |
+| Collection is empty | `assert_empty collection` |
+| Custom condition failed | `assert condition, "descriptive message"` |

data/skills/minitest/fixtures.md

@@ -0,0 +1,238 @@
+# Minitest: Fixtures
+
+## Pattern
+
+Rails fixtures are YAML files that define test data loaded once at suite start, wrapped in database transactions. They're fast, predictable, and the Minitest default. Use them as the primary test data strategy; reach for factories only when fixtures can't express what you need.
+
+```yaml
+# test/fixtures/users.yml
+alice:
+  email: alice@example.com
+  name: Alice Johnson
+  role: user
+  plan: pro
+  password_digest: <%= BCrypt::Password.create("password") %>
+
+bob:
+  email: bob@example.com
+  name: Bob Smith
+  role: user
+  plan: free
+  password_digest: <%= BCrypt::Password.create("password") %>
+
+admin:
+  email: admin@example.com
+  name: Admin User
+  role: admin
+  plan: pro
+  password_digest: <%= BCrypt::Password.create("password") %>
+```
+
+```yaml
+# test/fixtures/orders.yml
+pending_order:
+  user: alice
+  reference: ORD-000001
+  shipping_address: 123 Main St
+  status: pending
+  total: 50_00
+
+shipped_order:
+  user: alice
+  reference: ORD-000002
+  shipping_address: 123 Main St
+  status: shipped
+  total: 100_00
+  shipped_at: <%= 2.days.ago.to_fs(:db) %>
+
+bobs_order:
+  user: bob
+  reference: ORD-000003
+  shipping_address: 456 Oak Ave
+  status: pending
+  total: 25_00
+```
+
+```yaml
+# test/fixtures/products.yml
+widget:
+  name: Widget
+  price: 10_00
+  stock: 100
+  sku: WDG-001
+
+gadget:
+  name: Gadget
+  price: 25_00
+  stock: 50
+  sku: GDG-001
+```
+
+Using fixtures in tests:
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  test "scopes orders to user" do
+    alice_orders = Order.where(user: users(:alice))
+
+    assert_includes alice_orders, orders(:pending_order)
+    assert_includes alice_orders, orders(:shipped_order)
+    refute_includes alice_orders, orders(:bobs_order)
+  end
+
+  test ".pending returns only pending orders" do
+    pending = Order.pending
+
+    assert_includes pending, orders(:pending_order)
+    assert_includes pending, orders(:bobs_order)
+    refute_includes pending, orders(:shipped_order)
+  end
+
+  test "total is positive" do
+    assert_operator orders(:pending_order).total, :>, 0
+  end
+end
+```
+
+```ruby
+# Integration test with fixtures
+class OrdersControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    sign_in users(:alice)
+  end
+
+  test "index shows only current user's orders" do
+    get orders_path
+
+    assert_response :success
+    assert_match orders(:pending_order).reference, response.body
+    assert_no_match orders(:bobs_order).reference, response.body
+  end
+
+  test "create with valid params" do
+    assert_difference "Order.count", 1 do
+      post orders_path, params: {
+        order: { shipping_address: "789 Elm St", product_id: products(:widget).id, quantity: 1 }
+      }
+    end
+
+    assert_redirected_to Order.last
+  end
+
+  test "create with invalid params does not create order" do
+    assert_no_difference "Order.count" do
+      post orders_path, params: { order: { shipping_address: "" } }
+    end
+
+    assert_response :unprocessable_entity
+  end
+end
+```
+
+## Why This Is Good
+
+- **Loaded once per suite.** Fixtures are inserted into the database once before all tests run, then wrapped in transactions. Each test rolls back to the same state. Zero per-test INSERT cost.
+- **Predictable IDs.** `users(:alice).id` is the same every run. This makes debugging repeatable and assertions stable.
+- **Relationships via labels.** `user: alice` in the order fixture automatically resolves to `users(:alice).id`. No manual ID management.
+- **ERB support.** `<%= BCrypt::Password.create("password") %>` and `<%= 2.days.ago %>` — dynamic values at fixture load time.
+- **Fast.** A 500-test suite with fixtures runs 2-5x faster than the same suite with FactoryBot creates, because there are zero INSERTs per test.
+
+## When To Use Factories Instead
+
+Sometimes fixtures aren't enough. Use FactoryBot (or fabrication) alongside fixtures for:
+
+```ruby
+# test/test_helper.rb
+require "factory_bot_rails"
+
+class ActiveSupport::TestCase
+  include FactoryBot::Syntax::Methods
+end
+```
+
+```ruby
+# Use factories when you need MANY records with variations
+test "pagination with 50 orders" do
+  50.times { |i| create(:order, user: users(:alice), reference: "ORD-#{i.to_s.rjust(6, '0')}") }
+
+  get orders_path, params: { page: 1, per: 25 }
+
+  assert_response :success
+  assert_select ".order-row", count: 25
+end
+
+# Use factories when the variation is the point of the test
+test "discount tiers" do
+  small_order = create(:order, total: 50_00)
+  medium_order = create(:order, total: 200_00)
+  large_order = create(:order, total: 1000_00)
+
+  assert_equal 0, DiscountCalculator.call(small_order)
+  assert_equal 10_00, DiscountCalculator.call(medium_order)
+  assert_equal 100_00, DiscountCalculator.call(large_order)
+end
+```
+
+## The Hybrid Approach
+
+Use fixtures for stable reference data (users, products, roles, config) and factories for test-specific variations:
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  # Fixtures for the user (stable, referenced everywhere)
+  # Factory for the order (specific to this test's needs)
+
+  test "high-value orders require manager approval" do
+    order = create(:order, user: users(:alice), total: 10_000_00)
+
+    assert_predicate order, :requires_approval?
+  end
+
+  test "standard orders do not require approval" do
+    # Fixture order is $50 — no approval needed
+    refute_predicate orders(:pending_order), :requires_approval?
+  end
+end
+```
+
+## Anti-Pattern
+
+Fixtures that are fragile or hard to maintain:
+
+```yaml
+# BAD: 200 fixtures with unclear relationships
+order_1:
+  user_id: 1
+  status: pending
+  total: 100
+
+order_2:
+  user_id: 1
+  status: shipped
+  total: 200
+
+# ... 198 more
+```
+
+## Why This Is Bad
+
+- **Raw IDs instead of labels.** `user_id: 1` breaks if fixture loading order changes. Use `user: alice` instead.
+- **Too many fixtures.** If you need 200 orders for one test, use a factory loop. Fixtures are for stable reference data, not bulk test data.
+- **No naming convention.** `order_1` tells you nothing. `pending_order`, `shipped_order`, `bobs_cancelled_order` are self-documenting.
+
+## Fixture Naming Conventions
+
+Name fixtures by their distinguishing characteristic:
+
+```yaml
+# Good names — describe what makes this fixture special
+pending_order:    # Status-focused
+shipped_order:
+high_value_order: # Amount-focused
+expired_order:    # Time-focused
+
+# Bad names — meaningless
+order_1:
+order_2:
+test_order:
+```