source_monitor 0.2.0 → 0.3.0

data/.claude/skills/install/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: install
+description: Sets up a new Rails 8 application with recommended defaults for TDD, authentication, multi-tenancy, and Hotwire. Use when creating a new Rails project, bootstrapping an app, or when user mentions new app, rails new, project setup, or initial setup.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Rails 8 Application Setup
+
+## Overview
+
+Bootstrap a new Rails 8 application with production-ready defaults:
+- Rails 8 with Solid Queue, Solid Cache, Solid Cable
+- Built-in authentication (has_secure_password)
+- Multi-tenancy via Account scoping
+- Hotwire (Turbo + Stimulus)
+- Minitest + fixtures for testing
+- Tailwind CSS for styling
+
+## Quick Start
+
+```bash
+rails new myapp --css tailwind --database sqlite3
+cd myapp
+```
+
+## Post-Generation Setup
+
+### 1. Generate Authentication
+
+```bash
+bin/rails generate authentication
+bin/rails db:migrate
+```
+
+This creates:
+- `User` model with `email_address` and `password_digest`
+- `Session` model with token-based sessions
+- `Current` model (CurrentAttributes)
+- `Authentication` concern
+- `SessionsController`
+
+### 2. Add Account Model (Multi-Tenancy)
+
+```bash
+bin/rails generate model Account name:string
+bin/rails generate migration AddAccountToUsers account:references
+bin/rails db:migrate
+```
+
+```ruby
+# app/models/account.rb
+class Account < ApplicationRecord
+  has_many :users, dependent: :destroy
+
+  validates :name, presence: true
+end
+```
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+  has_many :sessions, dependent: :destroy
+  belongs_to :account
+
+  normalizes :email_address, with: ->(e) { e.strip.downcase }
+
+  validates :email_address, presence: true,
+    uniqueness: true,
+    format: { with: URI::MailTo::EMAIL_REGEXP }
+end
+```
+
+### 3. Add Current Account
+
+```ruby
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session
+  attribute :user_agent, :ip_address
+
+  delegate :user, to: :session, allow_nil: true
+
+  def account
+    user&.account
+  end
+end
+```
+
+### 4. Configure Test Helper
+
+```ruby
+# test/test_helper.rb
+ENV["RAILS_ENV"] ||= "test"
+require_relative "../config/environment"
+require "rails/test_help"
+
+module ActiveSupport
+  class TestCase
+    parallelize(workers: :number_of_processors)
+    fixtures :all
+
+    private
+
+    def sign_in(user)
+      session = user.sessions.create!
+      cookies.signed.permanent[:session_token] = {
+        value: session.token,
+        httponly: true
+      }
+      Current.session = session
+    end
+
+    def sign_out
+      Current.session&.destroy
+      cookies.delete(:session_token)
+    end
+  end
+end
+```
+
+### 5. Create Fixtures
+
+```yaml
+# test/fixtures/accounts.yml
+one:
+  name: Acme Corp
+
+other:
+  name: Other Corp
+```
+
+```yaml
+# test/fixtures/users.yml
+one:
+  email_address: user@example.com
+  password_digest: <%= BCrypt::Password.create("password123") %>
+  account: one
+
+admin:
+  email_address: admin@example.com
+  password_digest: <%= BCrypt::Password.create("password123") %>
+  account: one
+
+other_account:
+  email_address: other@example.com
+  password_digest: <%= BCrypt::Password.create("password123") %>
+  account: other
+```
+
+```yaml
+# test/fixtures/sessions.yml
+one:
+  user: one
+  token: <%= SecureRandom.urlsafe_base64(32) %>
+```
+
+### 6. Configure Solid Queue
+
+```yaml
+# config/queue.yml (already generated by Rails 8)
+default: &default
+  dispatchers:
+    - polling_interval: 1
+      batch_size: 500
+  workers:
+    - queues: "*"
+      threads: 3
+      processes: 1
+      polling_interval: 0.1
+```
+
+```ruby
+# config/environments/production.rb
+config.active_job.queue_adapter = :solid_queue
+config.solid_queue.connects_to = { database: { writing: :queue } }
+```
+
+### 7. Configure Solid Cache
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :solid_cache_store
+config.solid_cache.connects_to = { database: { writing: :cache } }
+```
+
+### 8. Add Development Gems
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "debug", platforms: %i[mri windows], require: "debug/prelude"
+  gem "brakeman", require: false
+  gem "rubocop-rails-omakase", require: false
+  gem "bullet"
+end
+```
+
+```bash
+bundle install
+```
+
+### 9. Configure Bullet (N+1 Detection)
+
+```ruby
+# config/environments/development.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.alert = true
+  Bullet.bullet_logger = true
+  Bullet.console = true
+  Bullet.rails_logger = true
+end
+
+# config/environments/test.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.raise = true
+end
+```
+
+### 10. Add Application Layout Defaults
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= content_for(:title) || "MyApp" %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= stylesheet_link_tag "tailwind", "inter-font", "data-turbo-track": "reload" %>
+    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+    <%= javascript_importmap_tags %>
+  </head>
+  <body class="min-h-screen bg-white">
+    <div id="flash">
+      <% flash.each do |type, message| %>
+        <div class="flash flash-<%= type %>"><%= message %></div>
+      <% end %>
+    </div>
+
+    <main class="container mx-auto px-4 py-8">
+      <%= yield %>
+    </main>
+  </body>
+</html>
+```
+
+## Verification
+
+Run the test suite to confirm everything is wired up:
+
+```bash
+bin/rails test
+```
+
+### Smoke Test
+
+```ruby
+# test/models/user_test.rb
+require "test_helper"
+
+class UserTest < ActiveSupport::TestCase
+  test "fixture user is valid" do
+    user = users(:one)
+    assert user.valid?
+  end
+
+  test "requires email_address" do
+    user = User.new(password: "password123", account: accounts(:one))
+    assert_not user.valid?
+    assert user.errors[:email_address].any?
+  end
+
+  test "requires unique email_address" do
+    existing = users(:one)
+    user = User.new(
+      email_address: existing.email_address,
+      password: "password123",
+      account: accounts(:one)
+    )
+    assert_not user.valid?
+    assert user.errors[:email_address].any?
+  end
+end
+```
+
+```ruby
+# test/models/account_test.rb
+require "test_helper"
+
+class AccountTest < ActiveSupport::TestCase
+  test "fixture account is valid" do
+    account = accounts(:one)
+    assert account.valid?
+  end
+
+  test "requires name" do
+    account = Account.new
+    assert_not account.valid?
+    assert account.errors[:name].any?
+  end
+end
+```
+
+## Directory Structure After Setup
+
+```
+app/
+├── controllers/
+│   ├── application_controller.rb
+│   ├── concerns/
+│   │   └── authentication.rb
+│   └── sessions_controller.rb
+├── models/
+│   ├── account.rb
+│   ├── current.rb
+│   ├── session.rb
+│   └── user.rb
+├── views/
+│   └── layouts/
+│       └── application.html.erb
+config/
+├── database.yml
+├── queue.yml
+├── cable.yml
+└── environments/
+    ├── development.rb
+    ├── production.rb
+    └── test.rb
+test/
+├── test_helper.rb
+├── fixtures/
+│   ├── accounts.yml
+│   ├── users.yml
+│   └── sessions.yml
+└── models/
+    ├── user_test.rb
+    └── account_test.rb
+```
+
+## Rails 8 Defaults
+
+Rails 8 ships with these defaults already configured:
+- **Solid Queue** - Database-backed Active Job backend (replaces Redis/Sidekiq)
+- **Solid Cache** - Database-backed cache store (replaces Redis/Memcached)
+- **Solid Cable** - Database-backed Action Cable adapter
+- **Propshaft** - Asset pipeline (replaces Sprockets)
+- **Import Maps** - JavaScript without bundling
+- **Kamal** - Deployment
+- **Thruster** - HTTP/2 proxy with asset caching
+
+## Checklist
+
+- [ ] Rails app generated
+- [ ] Authentication generated and migrated
+- [ ] Account model created (multi-tenancy)
+- [ ] Current model configured with account
+- [ ] Test helper with sign_in/sign_out
+- [ ] Fixtures created (accounts, users, sessions)
+- [ ] Solid Queue configured
+- [ ] Solid Cache configured
+- [ ] Bullet configured for N+1 detection
+- [ ] Smoke tests pass
+- [ ] All tests GREEN

data/.claude/skills/performance-optimization/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: performance-optimization
+description: Identifies and fixes Rails performance issues including N+1 queries, slow queries, and memory problems. Use when optimizing queries, fixing N+1 issues, improving response times, or when user mentions performance, slow, optimization, or Bullet gem.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Performance Optimization for Rails 8
+
+## Overview
+
+Performance optimization focuses on:
+- N+1 query detection and prevention
+- Query optimization with eager loading
+- Database indexing
+- Memory management
+- Batch processing
+
+## Quick Start
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "bullet"             # N+1 detection
+  gem "rack-mini-profiler" # Request profiling
+end
+```
+
+## Bullet Configuration
+
+```ruby
+# config/environments/development.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.alert = true
+  Bullet.bullet_logger = true
+  Bullet.console = true
+  Bullet.rails_logger = true
+end
+
+# config/environments/test.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.raise = true  # Fail tests on N+1
+end
+```
+
+## N+1 Query Problems
+
+### The Problem
+
+```ruby
+# BAD: N+1 - 1 query for events, N queries for venues
+@events = Event.all
+@events.each { |e| e.venue.name }  # Query per event!
+```
+
+### The Solution
+
+```ruby
+# GOOD: 2 queries total
+@events = Event.includes(:venue)
+@events.each { |e| e.venue.name }  # No additional query
+```
+
+## Eager Loading Methods
+
+| Method | Use When |
+|--------|----------|
+| `includes` | Most cases (Rails chooses strategy) |
+| `preload` | Force separate queries, large datasets |
+| `eager_load` | Filtering on association, need LEFT JOIN |
+| `joins` | Only filtering, don't need association data |
+
+```ruby
+# Single association
+Event.includes(:venue)
+
+# Multiple
+Event.includes(:venue, :organizer)
+
+# Nested
+Event.includes(venue: :address)
+
+# Deep nesting
+Event.includes(
+  :venue, :organizer,
+  vendors: [:category, :reviews],
+  comments: :user
+)
+```
+
+## Query Optimization Patterns
+
+### Pattern 1: Scoped Eager Loading
+
+```ruby
+class Event < ApplicationRecord
+  scope :with_details, -> {
+    includes(:venue, :organizer, vendors: :category)
+  }
+end
+
+# Controller
+@events = Event.with_details.where(account: current_account)
+```
+
+### Pattern 2: Counter Caches
+
+```ruby
+# Migration
+add_column :events, :comments_count, :integer, default: 0, null: false
+
+# Model
+class Comment < ApplicationRecord
+  belongs_to :event, counter_cache: true
+end
+
+# Usage (no query)
+event.comments_count
+```
+
+### Pattern 3: Select Only Needed Columns
+
+```ruby
+# BAD
+User.all.map(&:name)
+
+# GOOD
+User.pluck(:name)
+
+# For objects with limited columns
+User.select(:id, :name, :email)
+```
+
+### Pattern 4: Batch Processing
+
+```ruby
+# BAD: Loads all records
+Event.all.each { |e| process(e) }
+
+# GOOD: Processes in batches
+Event.find_each(batch_size: 500) { |e| process(e) }
+
+# For updates
+Event.in_batches(of: 1000) do |batch|
+  batch.update_all(status: :archived)
+end
+```
+
+### Pattern 5: Exists? vs Present?
+
+```ruby
+# BAD: Loads all records
+if Event.where(status: :active).any?
+if Event.where(status: :active).present?
+
+# GOOD: SELECT 1 LIMIT 1
+if Event.where(status: :active).exists?
+```
+
+### Pattern 6: Size vs Count vs Length
+
+```ruby
+# count: Always queries database
+# size: Uses counter cache if available, else count
+# length: Loads collection if not loaded
+
+# Use size (handles both cases)
+events.size
+```
+
+## Database Indexing
+
+### When to Add Indexes
+
+| Add Index For | Example |
+|--------------|---------|
+| Foreign keys | `account_id`, `user_id` |
+| WHERE columns | `WHERE status = 'active'` |
+| ORDER BY columns | `ORDER BY created_at DESC` |
+| JOIN columns | `JOIN ON events.venue_id` |
+| Unique constraints | `email`, `uuid` |
+
+### Index Types
+
+```ruby
+add_index :events, :status                              # Single
+add_index :events, [:account_id, :status]              # Composite
+add_index :users, :email, unique: true                  # Unique
+add_index :events, :event_date, where: "status = 0"    # Partial
+```
+
+## Testing for Performance
+
+### N+1 Detection in Tests
+
+```ruby
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  setup do
+    Bullet.start_request if Bullet.enable?
+  end
+
+  teardown do
+    if Bullet.enable?
+      Bullet.perform_out_of_channel_notifications if Bullet.notification?
+      Bullet.end_request
+    end
+  end
+end
+```
+
+### Query Count Assertions
+
+```ruby
+# test/support/query_counter.rb
+module QueryCounter
+  def count_queries(&block)
+    count = 0
+    counter = ->(*, _) { count += 1 }
+    ActiveSupport::Notifications.subscribed(counter, "sql.active_record", &block)
+    count
+  end
+end
+
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  include QueryCounter
+end
+```
+
+```ruby
+# test/models/event_test.rb
+require "test_helper"
+
+class EventPerformanceTest < ActiveSupport::TestCase
+  test "with_details makes minimal queries" do
+    query_count = count_queries do
+      Event.with_details.where(account: accounts(:one)).each do |e|
+        e.venue&.name
+        e.organizer&.name
+      end
+    end
+
+    # events + venues + organizers = 3 queries max
+    assert query_count <= 3, "Expected <= 3 queries, got #{query_count}"
+  end
+end
+```
+
+### Missing Index Detection
+
+```ruby
+# test/db/schema_test.rb
+require "test_helper"
+
+class SchemaPerformanceTest < ActiveSupport::TestCase
+  test "all foreign keys have indexes" do
+    connection = ActiveRecord::Base.connection
+
+    connection.tables.each do |table|
+      columns = connection.columns(table)
+      fk_columns = columns.select { |c| c.name.end_with?("_id") }
+      indexes = connection.indexes(table)
+
+      fk_columns.each do |col|
+        indexed = indexes.any? { |idx| idx.columns.include?(col.name) }
+        assert indexed, "Missing index: #{table}.#{col.name}"
+      end
+    end
+  end
+end
+```
+
+## Memory Optimization
+
+```ruby
+# BAD: Builds large array
+Event.all.map(&:name).join(", ")
+
+# GOOD: Streams results
+Event.pluck(:name).join(", ")
+
+# BAD: Instantiates all AR objects
+Event.all.each { |e| e.update!(processed: true) }
+
+# GOOD: Direct SQL update in batches
+Event.in_batches.update_all(processed: true)
+```
+
+## Quick Fixes Reference
+
+| Problem | Solution |
+|---------|----------|
+| N+1 on belongs_to | `includes(:association)` |
+| N+1 on has_many | `includes(:association)` |
+| Slow COUNT | Add counter_cache |
+| Loading all columns | Use `select` or `pluck` |
+| Large dataset iteration | Use `find_each` |
+| Missing index on FK | Add index on `*_id` columns |
+| Slow WHERE clause | Add index on filtered column |
+
+## Checklist
+
+- [ ] Bullet enabled in development/test
+- [ ] No N+1 queries in critical paths
+- [ ] Foreign keys have indexes
+- [ ] Counter caches for frequent counts
+- [ ] Eager loading in controllers
+- [ ] Batch processing for large datasets
+- [ ] All tests GREEN