source_monitor 0.2.0 → 0.3.0

data/.claude/skills/form-object-patterns/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: form-object-patterns
+description: Creates form objects for complex form handling with TDD. Use when building multi-model forms, search forms, wizard forms, or when user mentions form objects, complex forms, virtual models, or non-persisted forms.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Form Object Patterns for Rails 8
+
+## Overview
+
+Form objects encapsulate complex form logic:
+- Multi-model forms (user + profile + address)
+- Search/filter forms (non-persisted)
+- Wizard/multi-step forms
+- Virtual attributes with validation
+- Decoupled from ActiveRecord models
+
+## When to Use Form Objects
+
+| Scenario | Use Form Object? |
+|----------|-----------------|
+| Single model CRUD | No (use model) |
+| Multi-model creation | Yes |
+| Complex validations across models | Yes |
+| Search/filter forms | Yes |
+| Wizard/multi-step forms | Yes |
+| API params transformation | Yes |
+| Contact forms (no persistence) | Yes |
+
+## TDD Workflow
+
+```
+Form Object Progress:
+- [ ] Step 1: Define form requirements
+- [ ] Step 2: Write form object test (RED)
+- [ ] Step 3: Run test (fails)
+- [ ] Step 4: Create form object
+- [ ] Step 5: Run test (GREEN)
+- [ ] Step 6: Wire up controller
+- [ ] Step 7: Create view form
+```
+
+## Base Form Class
+
+```ruby
+# app/forms/application_form.rb
+class ApplicationForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+  include ActiveModel::Validations
+
+  def self.model_name
+    ActiveModel::Name.new(self, nil, name.chomp("Form"))
+  end
+
+  def persisted?
+    false
+  end
+
+  def save
+    return false unless valid?
+    persist!
+    true
+  rescue ActiveRecord::RecordInvalid => e
+    errors.add(:base, e.message)
+    false
+  end
+
+  private
+
+  def persist!
+    raise NotImplementedError
+  end
+end
+```
+
+## Pattern 1: Multi-Model Registration Form
+
+### Test First (RED)
+
+```ruby
+# test/forms/registration_form_test.rb
+require "test_helper"
+
+class RegistrationFormTest < ActiveSupport::TestCase
+  test "validates presence of email" do
+    form = RegistrationForm.new(email: "")
+    assert_not form.valid?
+    assert_includes form.errors[:email], "can't be blank"
+  end
+
+  test "validates presence of password" do
+    form = RegistrationForm.new(password: "")
+    assert_not form.valid?
+    assert_includes form.errors[:password], "can't be blank"
+  end
+
+  test "validates password minimum length" do
+    form = RegistrationForm.new(password: "short")
+    assert_not form.valid?
+    assert form.errors[:password].any? { |e| e.include?("too short") }
+  end
+
+  test "#save with valid params returns true" do
+    form = RegistrationForm.new(
+      email: "user@example.com",
+      password: "password123",
+      password_confirmation: "password123",
+      company_name: "Acme Inc"
+    )
+
+    assert form.save
+  end
+
+  test "#save creates a user" do
+    form = RegistrationForm.new(
+      email: "new-user@example.com",
+      password: "password123",
+      password_confirmation: "password123",
+      company_name: "Acme Inc"
+    )
+
+    assert_difference("User.count", 1) { form.save }
+  end
+
+  test "#save creates an account" do
+    form = RegistrationForm.new(
+      email: "new-account@example.com",
+      password: "password123",
+      password_confirmation: "password123",
+      company_name: "Acme Inc"
+    )
+
+    assert_difference("Account.count", 1) { form.save }
+  end
+
+  test "#save associates user with account" do
+    form = RegistrationForm.new(
+      email: "assoc@example.com",
+      password: "password123",
+      password_confirmation: "password123",
+      company_name: "Acme Inc"
+    )
+    form.save
+    assert_equal form.user.account, form.account
+  end
+
+  test "#save with invalid params returns false" do
+    form = RegistrationForm.new(email: "", password: "short")
+    assert_not form.save
+  end
+
+  test "#save with invalid params does not create records" do
+    form = RegistrationForm.new(email: "", password: "short")
+    assert_no_difference("User.count") { form.save }
+  end
+
+  test "#save with duplicate email returns false" do
+    existing = users(:one)
+    form = RegistrationForm.new(
+      email: existing.email_address,
+      password: "password123",
+      password_confirmation: "password123",
+      company_name: "Acme Inc"
+    )
+
+    assert_not form.save
+    assert_includes form.errors[:email], "has already been taken"
+  end
+end
+```
+
+### Implementation (GREEN)
+
+```ruby
+# app/forms/registration_form.rb
+class RegistrationForm < ApplicationForm
+  attribute :email, :string
+  attribute :password, :string
+  attribute :password_confirmation, :string
+  attribute :company_name, :string
+  attribute :phone, :string
+
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :password, presence: true, length: { minimum: 8 }
+  validates :password_confirmation, presence: true
+  validates :company_name, presence: true
+  validate :passwords_match
+  validate :email_unique
+
+  attr_reader :user, :account
+
+  private
+
+  def persist!
+    ActiveRecord::Base.transaction do
+      @account = Account.create!(name: company_name)
+      @user = User.create!(
+        email_address: email,
+        password: password,
+        account: @account,
+        phone: phone
+      )
+    end
+  end
+
+  def passwords_match
+    return if password == password_confirmation
+    errors.add(:password_confirmation, "doesn't match password")
+  end
+
+  def email_unique
+    return unless User.exists?(email_address: email&.downcase)
+    errors.add(:email, "has already been taken")
+  end
+end
+```
+
+## Pattern 2: Search/Filter Form
+
+### Test First
+
+```ruby
+# test/forms/event_search_form_test.rb
+require "test_helper"
+
+class EventSearchFormTest < ActiveSupport::TestCase
+  setup do
+    @account = accounts(:one)
+  end
+
+  test "#results returns all account events without filters" do
+    form = EventSearchForm.new(account: @account, params: {})
+    results = form.results
+
+    results.each do |event|
+      assert_equal @account.id, event.account_id
+    end
+  end
+
+  test "#results excludes other account events" do
+    form = EventSearchForm.new(account: @account, params: {})
+    other_event = events(:other_account)
+
+    assert_not_includes form.results, other_event
+  end
+
+  test "#results filters by event_type" do
+    form = EventSearchForm.new(account: @account, params: { event_type: "wedding" })
+    form.results.each do |event|
+      assert_equal "wedding", event.event_type
+    end
+  end
+
+  test "#any_filters? returns true with filters" do
+    form = EventSearchForm.new(account: @account, params: { query: "test" })
+    assert form.any_filters?
+  end
+
+  test "#any_filters? returns false without filters" do
+    form = EventSearchForm.new(account: @account, params: {})
+    assert_not form.any_filters?
+  end
+end
+```
+
+### Implementation
+
+```ruby
+# app/forms/event_search_form.rb
+class EventSearchForm < ApplicationForm
+  attribute :query, :string
+  attribute :event_type, :string
+  attribute :status, :string
+  attribute :start_date, :date
+  attribute :end_date, :date
+
+  attr_reader :account
+
+  def initialize(account:, params: {})
+    @account = account
+    super(params)
+  end
+
+  def results
+    scope = account.events
+    scope = apply_search(scope)
+    scope = apply_type_filter(scope)
+    scope = apply_status_filter(scope)
+    scope = apply_date_filter(scope)
+    scope.order(event_date: :desc)
+  end
+
+  def any_filters?
+    [query, event_type, status, start_date, end_date].any?(&:present?)
+  end
+
+  private
+
+  def apply_search(scope)
+    return scope if query.blank?
+    scope.where("name LIKE :q OR description LIKE :q", q: "%#{sanitize_like(query)}%")
+  end
+
+  def apply_type_filter(scope)
+    return scope if event_type.blank?
+    scope.where(event_type: event_type)
+  end
+
+  def apply_status_filter(scope)
+    return scope if status.blank?
+    scope.where(status: status)
+  end
+
+  def apply_date_filter(scope)
+    scope = scope.where("event_date >= ?", start_date) if start_date.present?
+    scope = scope.where("event_date <= ?", end_date) if end_date.present?
+    scope
+  end
+
+  def sanitize_like(term)
+    term.gsub(/[%_]/) { |x| "\\#{x}" }
+  end
+end
+```
+
+## Pattern 3: Wizard/Multi-Step Form
+
+```ruby
+# app/forms/wizard/base_form.rb
+module Wizard
+  class BaseForm < ApplicationForm
+    def self.steps
+      raise NotImplementedError
+    end
+
+    def current_step
+      raise NotImplementedError
+    end
+
+    def first_step?
+      current_step == self.class.steps.first
+    end
+
+    def last_step?
+      current_step == self.class.steps.last
+    end
+
+    def progress_percentage
+      steps = self.class.steps
+      ((steps.index(current_step) + 1).to_f / steps.size * 100).round
+    end
+  end
+end
+```
+
+## Controller Integration
+
+```ruby
+class RegistrationsController < ApplicationController
+  allow_unauthenticated_access
+
+  def new
+    @form = RegistrationForm.new
+  end
+
+  def create
+    @form = RegistrationForm.new(registration_params)
+
+    if @form.save
+      start_new_session_for(@form.user)
+      redirect_to dashboard_path, notice: t(".success")
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def registration_params
+    params.require(:registration).permit(
+      :email, :password, :password_confirmation,
+      :company_name, :phone
+    )
+  end
+end
+```
+
+## Checklist
+
+- [ ] Test written first (RED)
+- [ ] Extends `ApplicationForm` or includes `ActiveModel::Model`
+- [ ] Attributes declared with types
+- [ ] Validations defined
+- [ ] `#save` method with transaction (if multi-model)
+- [ ] Controller uses form object
+- [ ] View uses `form_with model: @form`
+- [ ] Error handling in place
+- [ ] All tests GREEN

data/.claude/skills/hotwire-patterns/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: hotwire-patterns
+description: Implements Hotwire patterns with Turbo Frames, Turbo Streams, and Stimulus controllers. Use when building interactive UIs, real-time updates, form handling, partial page updates, or when user mentions Turbo, Stimulus, or Hotwire.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Hotwire Patterns for Rails 8
+
+## Overview
+
+Hotwire = HTML Over The Wire. Build modern web apps without writing much JavaScript.
+
+| Component | Purpose | Use Case |
+|-----------|---------|----------|
+| **Turbo Drive** | SPA-like navigation | Automatic, no code needed |
+| **Turbo Frames** | Partial page updates | Inline editing, tabbed content |
+| **Turbo Streams** | Real-time DOM updates | Live updates, flash messages |
+| **Stimulus** | JavaScript sprinkles | Toggles, forms, interactions |
+
+## When to Use Each Pattern
+
+| Scenario | Pattern |
+|----------|---------|
+| Inline edit | Turbo Frame |
+| Form submission with multiple updates | Turbo Stream |
+| Real-time feed | Turbo Stream + ActionCable |
+| Toggle visibility | Stimulus |
+| Form validation | Stimulus |
+| Infinite scroll | Turbo Frame + lazy loading |
+| Modal dialogs | Turbo Frame |
+| Flash messages | Turbo Stream |
+
+## References
+
+- See [turbo-frames.md](reference/turbo-frames.md) for frame patterns
+- See [turbo-streams.md](reference/turbo-streams.md) for stream patterns
+- See [stimulus.md](reference/stimulus.md) for controller patterns
+- See [tailwind-integration.md](reference/tailwind-integration.md) for styling
+
+## Turbo Frames
+
+### Basic Frame
+
+```erb
+<%# app/views/posts/index.html.erb %>
+<%= turbo_frame_tag "posts" do %>
+  <%= render @posts %>
+  <%= link_to "Load More", posts_path(page: 2) %>
+<% end %>
+```
+
+### Inline Editing
+
+```erb
+<%# _post.html.erb %>
+<%= turbo_frame_tag dom_id(post) do %>
+  <article>
+    <h2><%= post.title %></h2>
+    <%= link_to "Edit", edit_post_path(post) %>
+  </article>
+<% end %>
+
+<%# edit.html.erb %>
+<%= turbo_frame_tag dom_id(@post) do %>
+  <%= form_with model: @post do |f| %>
+    <%= f.text_field :title %>
+    <%= f.submit "Save" %>
+    <%= link_to "Cancel", @post %>
+  <% end %>
+<% end %>
+```
+
+### Lazy Loading
+
+```erb
+<%= turbo_frame_tag "comments", src: post_comments_path(@post), loading: :lazy do %>
+  <p>Loading comments...</p>
+<% end %>
+```
+
+## Turbo Streams
+
+### From Controller
+
+```erb
+<%# app/views/posts/create.turbo_stream.erb %>
+<%= turbo_stream.prepend "posts", @post %>
+<%= turbo_stream.update "flash", partial: "shared/flash" %>
+```
+
+### Stream Actions
+
+```ruby
+turbo_stream.append "posts", @post           # Add to end
+turbo_stream.prepend "posts", @post          # Add to start
+turbo_stream.replace dom_id(@post), @post    # Replace element
+turbo_stream.update dom_id(@post), @post     # Replace inner HTML
+turbo_stream.remove dom_id(@post)            # Remove element
+```
+
+### Flash Messages with Streams
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  after_action :flash_to_turbo_stream, if: -> { request.format.turbo_stream? }
+
+  private
+
+  def flash_to_turbo_stream
+    flash.each do |type, message|
+      flash.now[type] = message
+    end
+  end
+end
+```
+
+## Stimulus Controllers
+
+### Basic Controller
+
+```javascript
+// app/javascript/controllers/toggle_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["content"]
+
+  toggle() {
+    this.contentTarget.classList.toggle("hidden")
+  }
+}
+```
+
+```erb
+<div data-controller="toggle">
+  <button data-action="toggle#toggle">Toggle</button>
+  <div data-toggle-target="content">Hidden content</div>
+</div>
+```
+
+### Form Controller
+
+```javascript
+// app/javascript/controllers/form_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["submit"]
+
+  enableSubmit() {
+    this.submitTarget.disabled = false
+  }
+
+  disableSubmit() {
+    this.submitTarget.disabled = true
+  }
+}
+```
+
+## Testing Hotwire
+
+### Turbo Stream Response Tests
+
+```ruby
+# test/controllers/posts_controller_test.rb
+require "test_helper"
+
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    sign_in users(:one)
+  end
+
+  test "create returns turbo stream response" do
+    post posts_path,
+      params: { post: { title: "Test" } },
+      headers: { "Accept" => "text/vnd.turbo-stream.html" }
+
+    assert_response :success
+    assert_equal "text/vnd.turbo-stream.html", response.media_type
+    assert_includes response.body, "turbo-stream"
+  end
+
+  test "create with HTML format redirects" do
+    post posts_path, params: { post: { title: "Test" } }
+
+    assert_redirected_to post_path(Post.last)
+  end
+end
+```
+
+### System Tests (with JavaScript)
+
+```ruby
+# test/system/posts_test.rb
+require "application_system_test_case"
+
+class PostsSystemTest < ApplicationSystemTestCase
+  setup do
+    @user = users(:one)
+    sign_in @user
+  end
+
+  test "updates post inline with Turbo Frame" do
+    post = posts(:one)
+
+    visit posts_path
+    within("#post_#{post.id}") do
+      click_link "Edit"
+      fill_in "Title", with: "Updated"
+      click_button "Save"
+    end
+
+    assert_text "Updated"
+    assert_no_text post.title
+  end
+
+  test "adds comment with Turbo Stream" do
+    post = posts(:one)
+
+    visit post_path(post)
+    fill_in "Comment", with: "Great post!"
+    click_button "Add Comment"
+
+    within("#comments") do
+      assert_text "Great post!"
+    end
+  end
+end
+```
+
+## Debugging Tips
+
+1. **Frame not updating?** Check frame IDs match exactly
+2. **Stream not working?** Verify `Accept` header includes turbo-stream
+3. **Stimulus not firing?** Check controller name matches file name
+4. **Events not working?** Use `data-action="event->controller#method"`
+
+## Checklist
+
+- [ ] Identify update scope (full page vs partial)
+- [ ] Choose pattern (Frame vs Stream vs Stimulus)
+- [ ] Implement server response
+- [ ] Add client-side markup
+- [ ] Test with and without JavaScript
+- [ ] Write system test for interactive behavior
+- [ ] All tests GREEN