@codyswann/lisa 2.195.4 → 2.195.6

package/plugins/lisa-rails/.codex-plugin/skills/action-controller-best-practices/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: action-controller-best-practices
+description: "Build or Refactor large Rails…"
+---
+
+# 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/plugins/lisa-rails/.codex-plugin/skills/action-controller-best-practices/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Action Controller Best Practices"
+short_description: "Build or Refactor large Rails…"
+default_prompt:
+  - "Use $action-controller-best-practices: Build or Refactor large Rails…."

package/plugins/lisa-rails/.codex-plugin/skills/action-view-best-practices/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: action-view-best-practices
+description: "Build or Refactor Rails views…"
+---
+
+# 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.