@codyswann/lisa 1.36.0 → 1.38.0

package/rails/copy-overwrite/.claude/skills/action-controller-best-practices/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: action-controller-best-practices
+description: Build or Refactor large Rails controller files into clean, maintainable code. Use when a controller action exceeds ~10 lines, a controller has custom non-RESTful actions, or when the user asks to refactor, slim down, clean up, or organize a Rails controller. Applies patterns: service objects, query objects, form objects, controller concerns, presenters/decorators, and RESTful resource extraction.
+---
+
+# Rails Controller Refactoring
+
+Controllers should be thin traffic cops — they receive input via params, delegate to the appropriate object, and decide what to render or redirect. Each action should be roughly 5-10 lines. If an action is longer, logic needs to be extracted.
+
+## Decision Framework
+
+Read the controller and classify each block of code:
+
+| Code type                                               | Extract to             | Location                               |
+| ------------------------------------------------------- | ---------------------- | -------------------------------------- |
+| Business logic, multi-step operations, side effects     | Service object         | `app/services/`                        |
+| Complex queries, filtering, sorting, search             | Query object           | `app/queries/`                         |
+| Context-specific param validation and persistence       | Form object            | `app/forms/`                           |
+| Shared before_actions, auth, pagination, error handling | Controller concern     | `app/controllers/concerns/`            |
+| Complex view data assembly, formatting, display logic   | Presenter / Decorator  | `app/presenters/` or `app/decorators/` |
+| Non-RESTful custom actions on a different concept       | New RESTful controller | `app/controllers/`                     |
+| Simple CRUD, strong params, render/redirect             | Keep on controller     | —                                      |
+
+## Patterns
+
+### Service Objects
+
+Use for any business logic that goes beyond simple CRUD. A controller action should call one service at most.
+
+Before:
+
+```ruby
+def create
+  @player = Player.new(player_params)
+  @player.team = Team.find(params[:team_id])
+  @player.contract_start = Time.current
+  @player.status = :active
+
+  if @player.save
+    PlayerMailer.welcome(@player).deliver_later
+    Analytics.track("player_signed", player_id: @player.id)
+    NotifyScoutsJob.perform_later(@player.team_id)
+    redirect_to @player, notice: "Player signed"
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+After:
+
+```ruby
+# Controller
+def create
+  result = Players::SignPlayer.new(player_params, team_id: params[:team_id]).call
+
+  if result.success?
+    redirect_to result.player, notice: "Player signed"
+  else
+    @player = result.player
+    render :new, status: :unprocessable_entity
+  end
+end
+
+# app/services/players/sign_player.rb
+module Players
+  class SignPlayer
+    def initialize(params, team_id:)
+      @params = params
+      @team_id = team_id
+    end
+
+    def call
+      player = Player.new(@params)
+      player.team = Team.find(@team_id)
+      player.contract_start = Time.current
+      player.status = :active
+
+      if player.save
+        send_notifications(player)
+        Result.new(success: true, player: player)
+      else
+        Result.new(success: false, player: player)
+      end
+    end
+
+    private
+
+    def send_notifications(player)
+      PlayerMailer.welcome(player).deliver_later
+      Analytics.track("player_signed", player_id: player.id)
+      NotifyScoutsJob.perform_later(player.team_id)
+    end
+
+    Result = Struct.new(:success, :player, keyword_init: true) do
+      alias_method :success?, :success
+    end
+  end
+end
+```
+
+### Query Objects
+
+Use when index actions have complex filtering, sorting, or search logic.
+
+Before:
+
+```ruby
+def index
+  @players = Player.where(team_id: params[:team_id])
+  @players = @players.where(position: params[:position]) if params[:position].present?
+  @players = @players.where("age >= ?", params[:min_age]) if params[:min_age].present?
+  @players = @players.where(status: :active) unless params[:include_inactive]
+  @players = @players.joins(:stats).order("stats.war DESC")
+  @players = @players.page(params[:page]).per(25)
+end
+```
+
+After:
+
+```ruby
+# Controller
+def index
+  @players = Players::FilterQuery.new(params).call
+end
+
+# app/queries/players/filter_query.rb
+module Players
+  class FilterQuery
+    def initialize(params, relation: Player.all)
+      @params = params
+      @relation = relation
+    end
+
+    def call
+      filter_by_team
+      filter_by_position
+      filter_by_age
+      filter_by_status
+      sort_and_paginate
+      @relation
+    end
+
+    private
+
+    def filter_by_team
+      @relation = @relation.where(team_id: @params[:team_id]) if @params[:team_id].present?
+    end
+
+    def filter_by_position
+      @relation = @relation.where(position: @params[:position]) if @params[:position].present?
+    end
+
+    def filter_by_age
+      @relation = @relation.where("age >= ?", @params[:min_age]) if @params[:min_age].present?
+    end
+
+    def filter_by_status
+      @relation = @relation.where(status: :active) unless @params[:include_inactive]
+    end
+
+    def sort_and_paginate
+      @relation = @relation.joins(:stats).order("stats.war DESC").page(@params[:page]).per(25)
+    end
+  end
+end
+```
+
+### Controller Concerns
+
+Use for shared behavior across multiple controllers: authentication, authorization, pagination, error handling, locale setting.
+
+```ruby
+# app/controllers/concerns/paginatable.rb
+module Paginatable
+  extend ActiveSupport::Concern
+
+  private
+
+  def page
+    params[:page] || 1
+  end
+
+  def per_page
+    [params[:per_page].to_i, 100].min.nonzero? || 25
+  end
+end
+
+# app/controllers/concerns/error_handleable.rb
+module ErrorHandleable
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActionController::ParameterMissing, with: :bad_request
+  end
+
+  private
+
+  def not_found
+    render json: { error: "Not found" }, status: :not_found
+  end
+
+  def bad_request(exception)
+    render json: { error: exception.message }, status: :bad_request
+  end
+end
+```
+
+Guidelines for controller concerns:
+
+- Each concern should handle one cross-cutting aspect
+- Don't use concerns to just split a large controller into files — that hides complexity
+- Good candidates: auth, error handling, pagination, locale, current tenant scoping
+- Bad candidates: domain-specific business logic
+
+### Presenters / Decorators
+
+Use when an action assembles complex data for the view that isn't a direct model attribute. Keeps view logic out of the controller.
+
+```ruby
+# app/presenters/player_dashboard_presenter.rb
+class PlayerDashboardPresenter
+  def initialize(player)
+    @player = player
+  end
+
+  def career_stats
+    @career_stats ||= @player.stats.group(:season).sum(:war)
+  end
+
+  def contract_status_label
+    return "Free Agent" if @player.contract_end&.past?
+    "Under Contract (#{@player.contract_end&.year})"
+  end
+
+  def trade_value_rating
+    case @player.trade_value
+    when 90.. then "Elite"
+    when 70..89 then "High"
+    when 50..69 then "Average"
+    else "Low"
+    end
+  end
+end
+
+# Controller
+def show
+  @player = Player.find(params[:id])
+  @presenter = PlayerDashboardPresenter.new(@player)
+end
+```
+
+### RESTful Resource Extraction
+
+When a controller has custom non-RESTful actions, it usually means there's a hidden resource. Extract it into its own controller with standard CRUD actions.
+
+Before:
+
+```ruby
+class PlayersController < ApplicationController
+  def trade
+    # ...
+  end
+
+  def release
+    # ...
+  end
+
+  def promote_to_roster
+    # ...
+  end
+end
+```
+
+After:
+
+```ruby
+# config/routes.rb
+resources :players do
+  resource :trade, only: [:new, :create], controller: "players/trades"
+  resource :release, only: [:create], controller: "players/releases"
+  resource :roster_promotion, only: [:create], controller: "players/roster_promotions"
+end
+
+# app/controllers/players/trades_controller.rb
+module Players
+  class TradesController < ApplicationController
+    def new
+      @player = Player.find(params[:player_id])
+    end
+
+    def create
+      result = Players::TradePlayer.new(Player.find(params[:player_id]), trade_params).call
+      # ...
+    end
+  end
+end
+```
+
+Signs you need a new controller:
+
+- Action name is a verb that isn't a CRUD verb (trade, approve, archive, publish)
+- Action operates on a different concept than the controller's resource
+- Controller has more than the 7 RESTful actions
+
+## Refactoring Process
+
+1. **Read the entire controller** and identify every action, before_action, and private method.
+2. **Inline hidden code first.** Copy logic from before_actions, helper methods, and parent classes into each action so you can see the full picture.
+3. **Classify each block** using the decision framework table above.
+4. **Extract in order**: RESTful resource extraction first (new controllers), then service objects, query objects, form objects, presenters, and finally concerns.
+5. **Slim down each action** to: find/build the resource, call a service or query, render or redirect. Each action should be 5-10 lines.
+6. **Clean up strong params.** Each controller should have one `_params` method. If you need different permitted params per action, consider separate controllers or form objects.
+7. **Create or update tests** for each extracted class with its own spec file.
+
+## What the Controller Should Look Like After
+
+```ruby
+class PlayersController < ApplicationController
+  before_action :set_player, only: [:show, :edit, :update, :destroy]
+
+  def index
+    @players = Players::FilterQuery.new(params).call
+  end
+
+  def show
+    @presenter = PlayerDashboardPresenter.new(@player)
+  end
+
+  def create
+    result = Players::SignPlayer.new(player_params, team_id: params[:team_id]).call
+
+    if result.success?
+      redirect_to result.player, notice: "Player signed"
+    else
+      @player = result.player
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    if @player.update(player_params)
+      redirect_to @player, notice: "Player updated"
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @player.destroy
+    redirect_to players_path, notice: "Player removed"
+  end
+
+  private
+
+  def set_player
+    @player = Player.find(params[:id])
+  end
+
+  def player_params
+    params.require(:player).permit(:name, :position, :age, :team_id)
+  end
+end
+```
+
+## What NOT to Do
+
+- Don't put business logic in before_actions — they obscure the flow of an action.
+- Don't use instance variables to pass data between before_actions and actions in complex ways.
+- Don't rescue broad exceptions in individual actions — use a concern or `rescue_from`.
+- Don't add non-RESTful actions to a controller when a new controller would be clearer.
+- Don't create deeply nested service call chains — one service per action is the goal.
+- Don't move logic to private methods and call it refactored — private methods still live in the controller.

package/rails/copy-overwrite/.claude/skills/action-view-best-practices/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: action-view-best-practices
+description: Build or Refactor Rails views, partials, and templates into clean, maintainable code. Use when views have inline Ruby logic, deeply nested partials, jQuery or legacy JavaScript, helper methods returning HTML, or when the user asks to modernize, refactor, or clean up Rails views. Applies patterns - Turbo Frames, Turbo Streams, Stimulus controllers, ViewComponent, presenters, strict locals, and proper partial extraction.
+---
+
+# Rails View Refactoring
+
+Views should contain markup and minimal display logic. If a view has conditionals, calculations, query calls, or complex Ruby blocks, it needs refactoring. The modern Rails 8+ stack uses Hotwire (Turbo + Stimulus) for interactivity, Propshaft for assets, and Importmap for JavaScript — no build step required.
+
+## Decision Framework
+
+Read the view and classify each block of code:
+
+| Code type                                               | Extract to                      | Location                                   |
+| ------------------------------------------------------- | ------------------------------- | ------------------------------------------ |
+| Reusable UI patterns (buttons, cards, modals, badges)   | ViewComponent                   | `app/components/`                          |
+| Display logic (formatting, conditional CSS, label text) | Presenter or ViewComponent      | `app/presenters/` or `app/components/`     |
+| HTML-returning helper methods                           | ViewComponent                   | `app/components/`                          |
+| Inline `<script>` tags and jQuery                       | Stimulus controller             | `app/javascript/controllers/`              |
+| AJAX calls, remote forms, `$.ajax`                      | Turbo Frame or Turbo Stream     | ERB template + controller response         |
+| Partial page updates via JavaScript                     | Turbo Frame                     | Wrap in `turbo_frame_tag`                  |
+| Real-time broadcasts (chat, notifications)              | Turbo Stream                    | Model `broadcasts_to` or controller stream |
+| One-off page sections that are too long                 | Partial with strict locals      | `app/views/shared/` or alongside view      |
+| Complex data assembly for the view                      | Presenter                       | `app/presenters/`                          |
+| Repeated inline Ruby (loops with logic)                 | Collection partial or component | Partial or component                       |
+| Instance variables used across partials                 | Locals / strict locals          | Pass explicitly                            |
+
+## Modernizing to Hotwire
+
+### Replace jQuery AJAX with Turbo Frames
+
+Turbo Frames update a specific section of the page without a full reload. No JavaScript needed.
+
+```erb
+<%# Before — jQuery AJAX %>
+<div id="player-stats"></div>
+<script>
+  $.get('/players/<%= @player.id %>/stats', function(data) {
+    $('#player-stats').html(data);
+  });
+</script>
+
+<%# After — Turbo Frame %>
+<%= turbo_frame_tag "player_stats" do %>
+  <%= render partial: "players/stats", locals: { player: @player } %>
+<% end %>
+```
+
+The linked page just needs a matching `turbo_frame_tag` with the same ID and Turbo handles the rest.
+
+### Replace Remote Forms with Turbo
+
+Rails UJS `remote: true` forms are deprecated. Turbo handles forms natively.
+
+```erb
+<%# Before — Rails UJS %>
+<%= form_with model: @player, remote: true do |f| %>
+  ...
+<% end %>
+
+<%# After — Turbo (just remove remote: true, Turbo handles it) %>
+<%= form_with model: @player do |f| %>
+  ...
+<% end %>
+```
+
+Turbo intercepts all form submissions by default. For partial updates, wrap the form in a `turbo_frame_tag`. For multi-target updates, respond with a Turbo Stream:
+
+```erb
+<%# app/views/players/update.turbo_stream.erb %>
+<%= turbo_stream.replace "player_header" do %>
+  <%= render partial: "players/header", locals: { player: @player } %>
+<% end %>
+
+<%= turbo_stream.update "flash_messages" do %>
+  <%= render partial: "shared/flash" %>
+<% end %>
+```
+
+### Replace Inline JavaScript with Stimulus
+
+Any behavior attached to DOM elements (toggles, dropdowns, form validation, clipboard, modals) should be a Stimulus controller.
+
+```erb
+<%# Before — inline JS / jQuery %>
+<button onclick="document.getElementById('details').classList.toggle('hidden')">
+  Toggle
+</button>
+<div id="details" class="hidden">...</div>
+
+<%# After — Stimulus %>
+<div data-controller="toggle">
+  <button data-action="click->toggle#switch">Toggle</button>
+  <div data-toggle-target="content" class="hidden">...</div>
+</div>
+```
+
+```javascript
+// app/javascript/controllers/toggle_controller.js
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["content"];
+
+  switch() {
+    this.contentTarget.classList.toggle("hidden");
+  }
+}
+```
+
+Conventions:
+
+- One behavior per controller — keep them small and composable
+- Name controllers after what they do: `toggle`, `clipboard`, `dropdown`, `search-form`
+- Use `targets` for elements, `values` for data, `classes` for CSS class names
+- Never manipulate DOM outside the controller's element scope
+
+### Replace Polling with Turbo Streams
+
+For real-time updates, use Turbo Streams over WebSockets instead of JavaScript polling.
+
+```ruby
+# app/models/score.rb
+class Score < ApplicationRecord
+  broadcasts_to ->(score) { [score.game] }, inserts_by: :prepend
+end
+```
+
+```erb
+<%# Subscribe in the view %>
+<%= turbo_stream_from @game %>
+
+<div id="scores">
+  <%= render @game.scores %>
+</div>
+```
+
+New scores automatically appear without any JavaScript.
+
+## View Component Patterns
+
+### When to Use ViewComponent vs Partials
+
+Use **partials** for:
+
+- One-off page sections that won't be reused
+- Simple markup extraction to reduce file length
+- Layouts and structural wrappers
+
+Use **ViewComponent** for:
+
+- Reusable UI elements (buttons, cards, badges, modals, alerts)
+- Components with display logic or multiple variants
+- Anything you'd want to unit test in isolation
+- Complex components with slots for flexible content injection
+
+### ViewComponent Example
+
+```ruby
+# app/components/stat_card_component.rb
+class StatCardComponent < ViewComponent::Base
+  def initialize(label:, value:, trend: nil)
+    @label = label
+    @value = value
+    @trend = trend
+  end
+
+  def trend_class
+    case @trend
+    when :up then "text-green-600"
+    when :down then "text-red-600"
+    else "text-gray-500"
+    end
+  end
+end
+```
+
+```erb
+<%# app/components/stat_card_component.html.erb %>
+<div class="rounded-lg border p-4">
+  <dt class="text-sm text-gray-500"><%= @label %></dt>
+  <dd class="text-2xl font-semibold"><%= @value %></dd>
+  <% if @trend %>
+    <span class="<%= trend_class %>"><%= @trend == :up ? "↑" : "↓" %></span>
+  <% end %>
+</div>
+```
+
+```erb
+<%# Usage %>
+<%= render StatCardComponent.new(label: "Batting Avg", value: ".312", trend: :up) %>
+```
+
+## Partial Best Practices
+
+### Use Strict Locals
+
+Always declare expected locals at the top of partials. This was added in Rails 7.1 and prevents silent nil bugs.
+
+```erb
+<%# app/views/players/_card.html.erb %>
+<%# locals: (player:, show_stats: false) %>
+
+<div class="player-card">
+  <h3><%= player.name %></h3>
+  <% if show_stats %>
+    <%= render partial: "players/stats", locals: { player: player } %>
+  <% end %>
+</div>
+```
+
+### Use Collection Rendering
+
+Never loop and render partials manually.
+
+```erb
+<%# Before — slow, verbose %>
+<% @players.each do |player| %>
+  <%= render partial: "players/card", locals: { player: player } %>
+<% end %>
+
+<%# After — collection rendering (faster, cleaner) %>
+<%= render partial: "players/card", collection: @players, as: :player %>
+```
+
+### Avoid Deeply Nested Partials
+
+If partial A renders partial B which renders partial C, it's too deep. Flatten the structure or extract to a ViewComponent that composes its own sub-components.
+
+## Presenters for Complex View Logic
+
+When a view needs data from multiple sources or complex formatting, use a presenter instead of cramming logic into the template.
+
+```ruby
+# app/presenters/player_profile_presenter.rb
+class PlayerProfilePresenter
+  def initialize(player, current_user)
+    @player = player
+    @current_user = current_user
+  end
+
+  def display_name
+    "#{@player.first_name} #{@player.last_name}"
+  end
+
+  def contract_status_badge
+    if @player.free_agent?
+      { text: "Free Agent", color: "green" }
+    elsif @player.contract_years_remaining <= 1
+      { text: "Expiring", color: "yellow" }
+    else
+      { text: "Under Contract", color: "gray" }
+    end
+  end
+
+  def can_edit?
+    @current_user.admin? || @current_user.team == @player.team
+  end
+
+  def formatted_salary
+    ActiveSupport::NumberHelper.number_to_currency(@player.salary)
+  end
+end
+```
+
+```erb
+<%# Clean view %>
+<h1><%= @presenter.display_name %></h1>
+
+<% badge = @presenter.contract_status_badge %>
+<%= render BadgeComponent.new(text: badge[:text], color: badge[:color]) %>
+
+<%= @presenter.formatted_salary %>
+
+<% if @presenter.can_edit? %>
+  <%= link_to "Edit", edit_player_path(@player) %>
+<% end %>
+```
+
+## Eliminating Helper Abuse
+
+Rails helpers that return HTML are hard to test, hard to read, and hard to compose. Move them to ViewComponents.
+
+```ruby
+# Before — helper returning HTML (bad)
+module PlayersHelper
+  def player_avatar(player, size: :md)
+    sizes = { sm: "w-8 h-8", md: "w-12 h-12", lg: "w-16 h-16" }
+    if player.avatar.attached?
+      image_tag player.avatar, class: "rounded-full #{sizes[size]}"
+    else
+      content_tag :div, player.initials,
+        class: "rounded-full #{sizes[size]} bg-gray-300 flex items-center justify-center"
+    end
+  end
+end
+
+# After — ViewComponent (good)
+# app/components/avatar_component.rb
+class AvatarComponent < ViewComponent::Base
+  SIZES = { sm: "w-8 h-8", md: "w-12 h-12", lg: "w-16 h-16" }.freeze
+
+  def initialize(player:, size: :md)
+    @player = player
+    @size = size
+  end
+  # ... with its own template and tests
+end
+```
+
+Keep helpers for non-HTML formatting utilities only (number formatting, date formatting, text truncation).
+
+## Refactoring Process
+
+1. **Audit the view layer** — identify inline Ruby logic, jQuery, `remote: true` forms, helpers returning HTML, and deeply nested partials.
+2. **Remove jQuery and inline JS first** — replace with Stimulus controllers. This is the highest-impact change.
+3. **Replace `remote: true` and AJAX** — Turbo handles forms and links natively. Convert to Turbo Frames and Turbo Streams.
+4. **Add strict locals** to all existing partials.
+5. **Extract reusable UI patterns** into ViewComponents.
+6. **Move display logic** from views into presenters or component classes.
+7. **Move HTML-returning helpers** into components.
+8. **Flatten nested partials** — if nesting is deeper than 2 levels, restructure.
+9. **Add collection rendering** wherever loops render partials.
+10. **Remove all instance variables from partials** — pass data via locals only.
+
+## What NOT to Do
+
+- Don't put query calls in views — ever. Not even `count` or `any?`. Use the presenter or controller.
+- Don't use `content_for` for complex logic — it creates invisible dependencies between layouts and views.
+- Don't create Stimulus controllers that replicate what Turbo Frames already handle.
+- Don't mix jQuery and Stimulus in the same app — commit to full migration.
+- Don't render entire pages as ViewComponents — they are for reusable pieces, not whole pages.
+- Don't use `html_safe` or `raw` unless you are certain the content is sanitized.
+- Don't pass more than 3-4 locals to a partial — if you need more, it should be a component or presenter.
+- Don't use `render partial:` inside loops — use collection rendering instead.