whetrails/handoff/next-steps.md

Next Steps

Immediate: Rails Engine (browser UI)

Mount a UI at /whetrails inside the host Rails app. A developer adds the gem to their Gemfile, mounts the engine in config/routes.rb, starts the server, and visits /whetrails.

What the UI needs to show

• A list of all models in the app (left sidebar or index page)
• Click a model → full chain view (same data as CLI, but visual)
• Lifecycle timeline: each stage as a row, callbacks as nodes within it
• Source file/line as a clickable link (opens in editor via vscode:// URI scheme)
• Conditions rendered inline (if: :paid? shown as a badge)
• Callbacks from concerns/gems visually distinguished from model-defined ones

Technical approach for the engine

# lib/whetrails/engine.rb
module Whetrails
  class Engine < ::Rails::Engine
    isolate_namespace Whetrails
  end
end

Rails engine conventions:

• Routes go in config/routes.rb inside the gem
• Controllers in app/controllers/whetrails/
• Views in app/views/whetrails/
• The host app mounts it: mount Whetrails::Engine, at: "/whetrails"

The engine controllers call Whetrails::Inspector directly — no duplication of logic.

Model discovery

The engine index page needs to list all AR models in the host app:

Rails.application.eager_load!
models = ApplicationRecord.descendants  # or ActiveRecord::Base.descendants

After engine: Test Gap Analysis

Once the chain is extracted, gap analysis is:

1. Run the test suite with SimpleCov (or equivalent) to get line coverage data
2. For each callback method in the chain, check whether its source lines are covered
3. For each validator, check whether the validation path is exercised
4. Report: "these 3 callbacks have no test coverage"

The chain data structure (ModelChain) is already the right shape for this — each CallbackEntry has source_file and source_line, which can be cross-referenced against SimpleCov's coverage report.

Product / distribution

• Publish to RubyGems.org once the engine is working
• The gem should be dev/test-only (add to Gemfile under group :development)
• Pricing model TBD — could be open source with a paid cloud version, or MIT with a commercial license for teams

Environment notes

• Ruby 3.3.6 installed via rbenv (~/.rbenv/versions/3.3.6)
• rbenv init added to ~/.zshrc
• Rails 8.1.3
• Dev database: SQLite at storage/development.sqlite3
• Gitea running in Docker on localhost:3000 (container name: gitea)
• Gitea API token for bill: c2948775b80bcaa0ba65c6359658d0d48c340c4e