source_monitor 0.2.0 → 0.3.0

data/.claude/skills/caching-strategies/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: caching-strategies
+description: Implements Rails caching patterns for performance optimization. Use when adding fragment caching, Russian doll caching, low-level caching, HTTP caching with ETags, cache invalidation, or when user mentions caching, performance, cache keys, or Solid Cache.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Caching Strategies for Rails 8
+
+## Overview
+
+Rails provides multiple caching layers:
+- **HTTP caching**: ETags and `fresh_when` for 304 Not Modified
+- **Fragment caching**: Cache view partials
+- **Russian doll caching**: Nested cache fragments with `touch: true`
+- **Low-level caching**: Cache arbitrary data with `Rails.cache.fetch`
+- **Collection caching**: Efficient cached rendering of collections
+- **Solid Cache**: Database-backed caching (Rails 8 default, no Redis)
+
+## Cache Store Options
+
+| Store | Use Case |
+|-------|----------|
+| `:memory_store` | Development |
+| `:solid_cache_store` | Production (Rails 8 default) |
+| `:redis_cache_store` | Production (if Redis available) |
+| `:null_store` | Testing |
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :solid_cache_store
+
+# config/environments/development.rb
+config.cache_store = :memory_store
+```
+
+Enable caching in development:
+```bash
+bin/rails dev:cache
+```
+
+## HTTP Caching (ETags / fresh_when)
+
+Use conditional GET to send 304 Not Modified when content has not changed.
+
+```ruby
+class EventsController < ApplicationController
+  def show
+    @event = current_account.events.find(params[:id])
+    fresh_when @event
+  end
+
+  def index
+    @events = current_account.events.recent
+    fresh_when @events
+  end
+end
+```
+
+### Composite ETags
+
+```ruby
+def show
+  @event = current_account.events.find(params[:id])
+  fresh_when [@event, Current.user]
+end
+```
+
+### With stale? for JSON
+
+```ruby
+class Api::EventsController < Api::BaseController
+  def show
+    @event = current_account.events.find(params[:id])
+    if stale?(@event)
+      render json: @event
+    end
+  end
+end
+```
+
+## Fragment Caching
+
+```erb
+<%# app/views/events/_event.html.erb %>
+<% cache event do %>
+  <article class="event-card">
+    <h3><%= event.name %></h3>
+    <p><%= event.description %></p>
+    <time><%= l(event.event_date, format: :long) %></time>
+  </article>
+<% end %>
+```
+
+### Custom Cache Keys
+
+```erb
+<% cache [event, "v2"] do %>
+  ...
+<% end %>
+
+<% cache [event, current_user] do %>
+  ...
+<% end %>
+```
+
+## Russian Doll Caching
+
+Nested caches with automatic invalidation through `touch: true`:
+
+```ruby
+# app/models/comment.rb
+class Comment < ApplicationRecord
+  belongs_to :event, touch: true
+end
+```
+
+```erb
+<% cache @event do %>
+  <h1><%= @event.name %></h1>
+  <% @event.comments.each do |comment| %>
+    <% cache comment do %>
+      <%= render comment %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+When a comment is updated, `touch: true` cascades up through `updated_at` timestamps, invalidating all parent caches automatically.
+
+## Collection Caching
+
+```erb
+<%# Caches each item individually, multi-read from cache store %>
+<%= render partial: "events/event", collection: @events, cached: true %>
+```
+
+## Low-Level Caching
+
+```ruby
+Rails.cache.fetch("stats/#{Date.current}", expires_in: 1.hour) do
+  { total_events: Event.count, total_revenue: Order.sum(:total_cents) }
+end
+```
+
+### In Models
+
+```ruby
+class Board < ApplicationRecord
+  def statistics
+    Rails.cache.fetch([self, "statistics"], expires_in: 1.hour) do
+      {
+        total_cards: cards.count,
+        completed_cards: cards.joins(:closure).count,
+        total_comments: cards.joins(:comments).count
+      }
+    end
+  end
+end
+```
+
+### With Race Condition Protection
+
+```ruby
+Rails.cache.fetch([self, "stats"], expires_in: 1.hour, race_condition_ttl: 10.seconds) do
+  expensive_operation
+end
+```
+
+## Cache Invalidation
+
+### Key-Based (Automatic)
+
+Cache keys include `updated_at`, so updates automatically expire old entries.
+
+### Touch Cascade
+
+```ruby
+class Card < ApplicationRecord
+  belongs_to :board, touch: true  # Updates board.updated_at
+end
+
+class Comment < ApplicationRecord
+  belongs_to :card, touch: true   # Updates card.updated_at -> board.updated_at
+end
+```
+
+### Manual Invalidation
+
+```ruby
+class Event < ApplicationRecord
+  after_commit :invalidate_caches
+
+  private
+
+  def invalidate_caches
+    Rails.cache.delete([self, "statistics"])
+    Rails.cache.delete("featured_events")
+  end
+end
+```
+
+### Sweeper Pattern
+
+```ruby
+class CacheSweeper
+  def self.clear_board_caches(board)
+    Rails.cache.delete([board, "statistics"])
+    Rails.cache.delete([board, "card_distribution"])
+  end
+end
+```
+
+## Counter Caching
+
+```ruby
+# Migration
+add_column :events, :vendors_count, :integer, default: 0, null: false
+
+# Model
+class Vendor < ApplicationRecord
+  belongs_to :event, counter_cache: true
+end
+
+# Usage (no query needed)
+event.vendors_count
+```
+
+## Cache Warming
+
+```ruby
+class CacheWarmerJob < ApplicationJob
+  queue_as :low
+
+  def perform(account)
+    account.boards.find_each do |board|
+      board.statistics
+      board.card_distribution
+    end
+  end
+end
+```
+
+## Testing Caching
+
+```ruby
+# test/test_helper.rb (enable caching for specific tests)
+class ActiveSupport::TestCase
+  def with_caching(&block)
+    caching = ActionController::Base.perform_caching
+    ActionController::Base.perform_caching = true
+    Rails.cache.clear
+    yield
+  ensure
+    ActionController::Base.perform_caching = caching
+  end
+end
+```
+
+### Testing Touch Cascade
+
+```ruby
+# test/models/card_test.rb
+require "test_helper"
+
+class CardCachingTest < ActiveSupport::TestCase
+  test "touching card updates board updated_at" do
+    board = boards(:one)
+    card = cards(:one)
+
+    assert_changes -> { board.reload.updated_at } do
+      card.touch
+    end
+  end
+end
+```
+
+### Testing HTTP Caching
+
+```ruby
+# test/controllers/boards_controller_test.rb
+require "test_helper"
+
+class BoardsControllerCachingTest < ActionDispatch::IntegrationTest
+  setup do
+    sign_in users(:one)
+    @board = boards(:one)
+  end
+
+  test "returns 304 when board unchanged" do
+    get board_url(@board)
+    assert_response :success
+    etag = response.headers["ETag"]
+
+    get board_url(@board), headers: { "If-None-Match" => etag }
+    assert_response :not_modified
+  end
+
+  test "returns 200 when board updated" do
+    get board_url(@board)
+    etag = response.headers["ETag"]
+
+    @board.touch
+
+    get board_url(@board), headers: { "If-None-Match" => etag }
+    assert_response :success
+  end
+end
+```
+
+### Testing Cache Invalidation
+
+```ruby
+# test/models/board_test.rb
+require "test_helper"
+
+class BoardCacheInvalidationTest < ActiveSupport::TestCase
+  test "statistics cache is cleared after card update" do
+    board = boards(:one)
+    card = cards(:one)
+
+    board.statistics # Warm cache
+
+    card.update!(title: "New title")
+
+    assert_nil Rails.cache.read([board, "statistics"])
+  end
+end
+```
+
+## Memoization
+
+```ruby
+class EventPresenter < BasePresenter
+  def vendor_count
+    @vendor_count ||= event.vendors.count
+  end
+end
+```
+
+## Checklist
+
+- [ ] Cache store configured for environment
+- [ ] `fresh_when` on show/index actions
+- [ ] `touch: true` on belongs_to for Russian doll
+- [ ] Collection caching with `cached: true`
+- [ ] Low-level caching for expensive queries
+- [ ] Cache invalidation strategy defined
+- [ ] Counter caches for counts
+- [ ] Cache warming jobs for cold starts
+- [ ] All tests GREEN

data/.claude/skills/database-migrations/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: database-migrations
+description: Creates safe database migrations with proper indexes and rollback strategies. Use when creating tables, adding columns, creating indexes, handling zero-downtime migrations, or when user mentions migrations, schema changes, or database structure.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Database Migration Patterns for Rails 8
+
+## Overview
+
+Safe database migrations are critical for production stability:
+- Zero-downtime deployments
+- Reversible migrations
+- Proper indexing
+- Data integrity constraints
+
+## Quick Start
+
+```bash
+bin/rails generate migration AddStatusToEvents status:integer
+bin/rails db:migrate
+bin/rails db:rollback
+bin/rails db:migrate:status
+```
+
+## Safety Checklist
+
+```
+Migration Safety:
+- [ ] Migration is reversible (has down or uses change)
+- [ ] Large tables use batching for updates
+- [ ] Indexes added concurrently (if needed)
+- [ ] Foreign keys have indexes
+- [ ] NOT NULL added in two steps (for existing columns)
+- [ ] Default values don't lock table
+- [ ] Tested rollback locally
+```
+
+## Safe Migration Patterns
+
+### Pattern 1: Add Column (Safe)
+
+```ruby
+class AddStatusToEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_column :events, :status, :integer, default: 0, null: false
+  end
+end
+```
+
+### Pattern 2: Add Column with NOT NULL (Two-Step)
+
+For existing tables with data, add NOT NULL in two migrations:
+
+```ruby
+# Step 1: Add column with default (allows NULL temporarily)
+class AddPriorityToTasks < ActiveRecord::Migration[8.0]
+  def change
+    add_column :tasks, :priority, :integer, default: 0
+  end
+end
+
+# Step 2: Add NOT NULL constraint after backfill
+class AddNotNullToTasksPriority < ActiveRecord::Migration[8.0]
+  def change
+    change_column_null :tasks, :priority, false
+  end
+end
+```
+
+### Pattern 3: Add Index (Production Safe)
+
+```ruby
+class AddIndexToEventsStatus < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def change
+    add_index :events, :status, algorithm: :concurrently, if_not_exists: true
+  end
+end
+```
+
+### Pattern 4: Add Foreign Key with Index
+
+```ruby
+class AddAccountToEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :events, :account, null: false, foreign_key: true, index: true
+  end
+end
+```
+
+### Pattern 5: Rename Column
+
+```ruby
+class RenameNameToTitleOnEvents < ActiveRecord::Migration[8.0]
+  def change
+    rename_column :events, :name, :title
+  end
+end
+```
+
+### Pattern 6: Remove Column
+
+First remove references in code, then migrate:
+
+```ruby
+class RemoveLegacyFieldFromEvents < ActiveRecord::Migration[8.0]
+  def change
+    safety_assured { remove_column :events, :legacy_field, :string }
+  end
+end
+```
+
+### Pattern 7: Add Enum Column
+
+```ruby
+class AddStatusEnumToOrders < ActiveRecord::Migration[8.0]
+  def change
+    add_column :orders, :status, :integer, default: 0, null: false
+    add_index :orders, :status
+  end
+end
+```
+
+In model:
+```ruby
+class Order < ApplicationRecord
+  enum :status, { pending: 0, confirmed: 1, shipped: 2, delivered: 3, cancelled: 4 }
+end
+```
+
+### Pattern 8: Create Table with State Record
+
+For app-wide configuration (single-row tables):
+
+```ruby
+class CreateAppConfigs < ActiveRecord::Migration[8.0]
+  def change
+    create_table :app_configs do |t|
+      t.string :site_name, null: false, default: "My App"
+      t.boolean :maintenance_mode, null: false, default: false
+      t.text :settings
+      t.timestamps
+    end
+  end
+end
+```
+
+## Dangerous Operations (Avoid)
+
+### DON'T: Change Column Type Directly
+
+```ruby
+# DANGEROUS - can lose data or lock table
+change_column :events, :budget, :decimal  # DON'T DO THIS
+```
+
+### DO: Add New Column, Migrate Data, Remove Old
+
+```ruby
+# Step 1: Add new column
+class AddBudgetDecimalToEvents < ActiveRecord::Migration[8.0]
+  def change
+    add_column :events, :budget_decimal, :decimal, precision: 10, scale: 2
+  end
+end
+
+# Step 2: Backfill data
+class BackfillEventsBudget < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def up
+    Event.in_batches.update_all("budget_decimal = budget")
+  end
+
+  def down
+    # Data migration, no rollback needed
+  end
+end
+
+# Step 3: Remove old column (after code updated)
+class RemoveOldBudgetFromEvents < ActiveRecord::Migration[8.0]
+  def change
+    safety_assured { remove_column :events, :budget, :integer }
+    rename_column :events, :budget_decimal, :budget
+  end
+end
+```
+
+## Data Migrations
+
+### Safe Backfill Pattern
+
+```ruby
+class BackfillEventStatus < ActiveRecord::Migration[8.0]
+  disable_ddl_transaction!
+
+  def up
+    Event.unscoped.in_batches(of: 1000) do |batch|
+      batch.where(status: nil).update_all(status: 0)
+      sleep(0.1) # Reduce database load
+    end
+  end
+
+  def down
+    # No rollback for data migration
+  end
+end
+```
+
+## Index Strategies
+
+### Composite Indexes
+
+```ruby
+# For queries: WHERE account_id = ? AND status = ?
+add_index :events, [:account_id, :status]
+
+# Order matters! Left-to-right prefix matching:
+# Helps: WHERE account_id = ? AND status = ?
+# Helps: WHERE account_id = ?
+# Does NOT help: WHERE status = ?
+```
+
+### Partial Indexes
+
+```ruby
+# Index only active records
+add_index :events, :event_date, where: "status = 0", name: "index_events_on_date_active"
+
+# Index only non-null values
+add_index :users, :reset_token, where: "reset_token IS NOT NULL"
+```
+
+### Unique Indexes
+
+```ruby
+add_index :users, :email, unique: true
+add_index :event_vendors, [:event_id, :vendor_id], unique: true
+```
+
+## Foreign Keys
+
+```ruby
+class AddForeignKeys < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :events, :venue, foreign_key: true
+    add_foreign_key :events, :users, column: :organizer_id
+
+    # ON DELETE options
+    add_foreign_key :comments, :posts, on_delete: :cascade
+    add_foreign_key :posts, :users, column: :author_id, on_delete: :nullify
+  end
+end
+```
+
+## Testing Migrations
+
+### Schema Integrity Test
+
+```ruby
+# test/db/schema_test.rb
+require "test_helper"
+
+class SchemaTest < ActiveSupport::TestCase
+  test "all foreign keys have indexes" do
+    connection = ActiveRecord::Base.connection
+
+    connection.tables.each do |table|
+      foreign_keys = connection.foreign_keys(table)
+      indexes = connection.indexes(table)
+
+      foreign_keys.each do |fk|
+        indexed = indexes.any? { |idx| idx.columns.first == fk.column }
+        assert indexed, "Missing index for #{fk.column} on #{table}"
+      end
+    end
+  end
+end
+```
+
+### Rollback Test (CLI)
+
+```bash
+bin/rails db:migrate
+bin/rails db:rollback
+bin/rails db:migrate
+bin/rails db:migrate:status
+```
+
+## Reversible Migrations
+
+### Using up/down (Manual Reversal)
+
+```ruby
+class ChangeEventsStructure < ActiveRecord::Migration[8.0]
+  def up
+    execute <<-SQL
+      ALTER TABLE events ADD CONSTRAINT check_positive_budget
+      CHECK (budget_cents >= 0)
+    SQL
+  end
+
+  def down
+    execute <<-SQL
+      ALTER TABLE events DROP CONSTRAINT check_positive_budget
+    SQL
+  end
+end
+```
+
+### Irreversible Migrations
+
+```ruby
+class DropLegacyTable < ActiveRecord::Migration[8.0]
+  def up
+    drop_table :legacy_events
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Cannot restore dropped table"
+  end
+end
+```
+
+## Performance Tips
+
+```ruby
+# DON'T - Locks entire table
+add_index :large_table, :column
+
+# DO - Non-blocking
+disable_ddl_transaction!
+add_index :large_table, :column, algorithm: :concurrently
+
+# DON'T - Updates all at once
+Event.update_all(status: 0)
+
+# DO - Updates in batches
+Event.in_batches(of: 1000) do |batch|
+  batch.update_all(status: 0)
+end
+```
+
+## Checklist
+
+- [ ] Migration is reversible
+- [ ] Indexes on foreign keys
+- [ ] Concurrent index creation for large tables
+- [ ] NOT NULL added safely (two-step)
+- [ ] Data migrations use batching
+- [ ] Tested rollback locally
+- [ ] No table locks during deploy