statesman_scaffold 0.1.0

data/lib/statesman_scaffold/installer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module StatesmanScaffold
+  # Manages the Rails initializer file that configures Statesman to use the
+  # ActiveRecord adapter and auto-includes {StatesmanScaffold::Concern} into
+  # every ActiveRecord model via +ActiveSupport.on_load(:active_record)+.
+  #
+  # This class is intentionally decoupled from Rails so it can be exercised in
+  # unit tests without booting a full Rails application.
+  class Installer
+    # Path of the generated initializer, relative to the Rails root.
+    INITIALIZER_PATH = Pathname.new("config/initializers/statesman_scaffold.rb")
+
+    # Content written to the initializer file.
+    INITIALIZER_CONTENT = <<~RUBY
+      # frozen_string_literal: true
+
+      # Auto-include StatesmanScaffold::Concern into every ActiveRecord model
+      # so that the `with_state_machine` class macro is available application-wide.
+      #
+      # Generated by: rails statesman_scaffold:install
+      require "statesman"
+
+      Statesman.configure { storage_adapter(Statesman::Adapters::ActiveRecord) }
+
+      ActiveSupport.on_load(:active_record) do
+        include StatesmanScaffold::Concern
+      end
+    RUBY
+
+    # Creates the initializer file under +rails_root+.
+    #
+    # @param rails_root [Pathname, String] Root of the Rails application.
+    # @return [:created] when the file was written.
+    # @return [:skipped] when the file already exists.
+    def self.install!(rails_root)
+      target = Pathname(rails_root).join(INITIALIZER_PATH)
+      return :skipped if target.exist?
+
+      target.dirname.mkpath
+      target.write(INITIALIZER_CONTENT)
+      :created
+    end
+
+    # Removes the initializer file from +rails_root+.
+    #
+    # @param rails_root [Pathname, String] Root of the Rails application.
+    # @return [:removed] when the file was deleted.
+    # @return [:skipped] when the file did not exist.
+    def self.uninstall!(rails_root)
+      target = Pathname(rails_root).join(INITIALIZER_PATH)
+      return :skipped unless target.exist?
+
+      target.delete
+      :removed
+    end
+  end
+end

data/lib/statesman_scaffold/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module StatesmanScaffold
+  # Hooks StatesmanScaffold into a Rails application.
+  #
+  # When Rails loads, this Railtie exposes the +statesman_scaffold:install+,
+  # +statesman_scaffold:uninstall+, and +statesman_scaffold:generate+ rake tasks.
+  class Railtie < Rails::Railtie
+    railtie_name :statesman_scaffold
+
+    rake_tasks do
+      load File.expand_path("../tasks/statesman_scaffold.rake", __dir__)
+    end
+  end
+end

data/lib/statesman_scaffold/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StatesmanScaffold
+  VERSION = "0.1.0"
+end

data/lib/statesman_scaffold.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "statesman_scaffold/version"
+require_relative "statesman_scaffold/concern"
+require_relative "statesman_scaffold/generator"
+require_relative "statesman_scaffold/installer"
+
+module StatesmanScaffold
+  class Error < StandardError; end
+end
+
+require "statesman_scaffold/railtie" if defined?(Rails::Railtie)

data/lib/tasks/statesman_scaffold.rake

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+STATESMAN_SCAFFOLD_INITIALIZER_PATH = StatesmanScaffold::Installer::INITIALIZER_PATH.to_s
+
+namespace :statesman_scaffold do
+  desc "Install the StatesmanScaffold initializer (Statesman AR adapter + auto-include concern)"
+  task :install do
+    result = StatesmanScaffold::Installer.install!(Rails.root)
+    case result
+    when :created then puts "  #{"create".ljust(10)} #{STATESMAN_SCAFFOLD_INITIALIZER_PATH}"
+    when :skipped then puts "  #{"skip".ljust(10)} #{STATESMAN_SCAFFOLD_INITIALIZER_PATH} already exists"
+    end
+  end
+
+  desc "Remove the StatesmanScaffold initializer"
+  task :uninstall do
+    result = StatesmanScaffold::Installer.uninstall!(Rails.root)
+    case result
+    when :removed then puts "  #{"remove".ljust(10)} #{STATESMAN_SCAFFOLD_INITIALIZER_PATH}"
+    when :skipped then puts "  #{"skip".ljust(10)} #{STATESMAN_SCAFFOLD_INITIALIZER_PATH} not found"
+    end
+  end
+
+  desc "Generate StateMachine, Transition class, and migration for a model"
+  task :generate, [:model] => :environment do |_, args|
+    model = args[:model].to_s.camelize
+    abort "Model name required. Usage: rails \"statesman_scaffold:generate[ModelName]\"" if model.blank?
+
+    file_path = model.underscore
+    output_path = Rails.root.join("app/models", file_path)
+    migration_path = Rails.root.join("db/migrate")
+    version = ActiveRecord::Migration.current_version.to_s[0..2]
+
+    result = StatesmanScaffold::Generator.call(
+      model: model,
+      output_path: output_path,
+      migration_path: migration_path,
+      migration_version: version
+    )
+
+    puts "  #{"create".ljust(10)} #{result.state_machine_path.relative_path_from(Rails.root)}"
+    puts "  #{"create".ljust(10)} #{result.transition_path.relative_path_from(Rails.root)}"
+    puts "  #{"create".ljust(10)} #{result.migration_path.relative_path_from(Rails.root)}"
+    puts ""
+    puts "Don't forget to update your #{model} model by adding:"
+    puts ""
+    puts "  include StatesmanScaffold::Concern"
+    puts "  with_state_machine"
+    puts ""
+    puts "If you haven't already, run: rails statesman_scaffold:install"
+  end
+end

data/lib/templates/statesman/migration.rb.erb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+<% underscored_model = model.underscore.tr("/", "_") -%>
+<% demodulized_model = model.demodulize.underscore -%>
+
+class Create<%= class_name.gsub("::", "") %>Transitions < ActiveRecord::Migration[<%= version %>]
+  def change
+    # Instead of t.references with foreign_key: true, you can use:
+    # t.string :<%= demodulized_model %>_id, null: false
+    # And separately add foreign key:
+    # add_foreign_key :<%= underscored_model %>_transitions, :<%= demodulized_model %>s , column: :<%= demodulized_model %>_id, primary_key: :id
+
+    create_table :<%= underscored_model %>_transitions do |t|
+      t.references :<%= demodulized_model %>, null: false, foreign_key: <%= underscored_model == demodulized_model ? "true" : "{ to_table: :#{underscored_model.pluralize} }" %> # Use type when referencing model uses non-default primary key type. Example: type: :string
+      t.string :to_state, null: false
+      t.json :metadata, default: {}
+      t.boolean :most_recent, default: false
+      t.integer :sort_key, null: false
+      t.timestamps null: false
+    end
+
+    add_index(:<%= underscored_model %>_transitions,
+              %i[<%= demodulized_model %>_id sort_key],
+              unique: true,
+              name: "index_<%= underscored_model %>_transition_parent_sort")
+    add_index(:<%= underscored_model %>_transitions,
+              %i[<%= demodulized_model %>_id most_recent],
+              unique: true,
+              where: "most_recent",
+              name: "index_<%= underscored_model %>_transition_parent_most_recent")
+  end
+end

data/lib/templates/statesman/state_machine.rb.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::StateMachine
+  include Statesman::Machine
+
+  state :pending, initial: true
+  # state :checking_out
+  # state :purchased
+  # state :shipped
+  # state :cancelled
+  # state :failed
+  # state :refunded
+  #
+  # transition from: :pending,      to: [:checking_out, :cancelled]
+  # transition from: :checking_out, to: [:purchased, :cancelled]
+  # transition from: :purchased,    to: [:shipped, :failed]
+  # transition from: :shipped,      to: :refunded
+  #
+  # after_transition do |model, transition|
+  #   model.update!(status: transition.to_state)
+  # end
+  #
+  # guard_transition(to: :checking_out) do |order|
+  #   order.products_in_stock?
+  # end
+  #
+  # before_transition(from: :checking_out, to: :cancelled) do |order, transition|
+  #   order.reallocate_stock
+  # end
+  #
+  # before_transition(to: :purchased) do |order, transition|
+  #   PaymentService.new(order).submit
+  # end
+  #
+  # after_transition(to: :purchased) do |order, transition|
+  #   MailerService.order_confirmation(order).deliver
+  # end
+end

data/lib/templates/statesman/transition.rb.erb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+<% underscored_model = model.underscore.tr("/", "_") -%>
+<% demodulized_model = model.demodulize.underscore -%>
+
+class <%= class_name %>::Transition < ApplicationRecord
+  self.table_name = "<%= underscored_model %>_transitions"
+
+  belongs_to :<%= demodulized_model %>, class_name: "<%= class_name %>"
+
+  attribute :most_recent, :boolean, default: false
+  attribute :to_state, :string
+  attribute :sort_key, :integer
+  attribute :metadata, :json, default: {}
+
+  validates :to_state, inclusion: { in: <%= class_name %>::StateMachine.states }
+end

data/llms/overview.md

@@ -0,0 +1,256 @@
+# StatesmanScaffold -- Architecture Overview
+
+> Intended audience: LLMs and AI agents that need a precise mental model of
+> the gem internals before generating code.
+
+---
+
+## Purpose
+
+`statesman_scaffold` provides two things for Rails applications using the
+[Statesman](https://github.com/gocardless/statesman) gem:
+
+1. **Code generation** — a rake task that creates StateMachine, Transition
+   classes, and a migration for any ActiveRecord model.
+2. **A concern** — `with_state_machine` class macro that wires up Statesman
+   delegation, `has_many :transitions`, query scopes, and convenience predicates.
+
+It works exclusively with `Statesman::Adapters::ActiveRecord`.
+
+---
+
+## Module structure
+
+```
+StatesmanScaffold                      (top-level namespace, lib/statesman_scaffold.rb)
+├── Concern                            (lib/statesman_scaffold/concern.rb)
+│   ├── included block
+│   │   ├── in_state?(*states)        → checks current state against multiple states
+│   │   ├── not_in_state?(state)      → negation of in_state?
+│   │   └── delegate :current_state, :transition_to!, :transition_to, :can_transition_to?
+│   └── class_methods
+│       └── with_state_machine(...)   → wires up has_many, ActiveRecordQueries, state_machine method
+├── Generator                          (lib/statesman_scaffold/generator.rb)
+│   ├── TEMPLATE_DIR                  → path to lib/templates/statesman/
+│   ├── Result                        → Struct(state_machine_path, transition_path, migration_path)
+│   └── .call(model:, output_path:, migration_path:, migration_version:, timestamp:)
+├── Installer                          (lib/statesman_scaffold/installer.rb)
+│   ├── INITIALIZER_PATH             → Pathname("config/initializers/statesman_scaffold.rb")
+│   ├── INITIALIZER_CONTENT          → the exact string written to disk
+│   ├── .install!(rails_root)        → :created or :skipped
+│   └── .uninstall!(rails_root)      → :removed or :skipped
+├── Railtie < Rails::Railtie          (lib/statesman_scaffold/railtie.rb)
+│   └── rake_tasks { load ... }      → exposes all statesman_scaffold:* rake tasks
+└── Error < StandardError
+```
+
+---
+
+## How `with_state_machine` works
+
+```ruby
+class Project < ApplicationRecord
+  with_state_machine
+end
+```
+
+When `with_state_machine` is called, it:
+
+1. **Resolves class names dynamically** from the model's `name`:
+   - `"Project"` → `"Project::StateMachine"` and `"Project::Transition"`
+   - `"Admin::Order"` → `"Admin::Order::StateMachine"` and `"Admin::Order::Transition"`
+
+2. **Adds `has_many :transitions`** with `autosave: false`, `dependent: :destroy`,
+   and the resolved `class_name`.
+
+3. **Includes `Statesman::Adapters::ActiveRecordQueries`** parameterised with
+   `transition_class` and `initial_state`, giving the model `.in_state` and
+   `.not_in_state` class-level scopes.
+
+4. **Defines a `state_machine` instance method** that lazily initialises and
+   caches a Statesman machine instance via `instance_variable_set(:@state_machine, ...)`.
+
+The `included` block adds `in_state?`, `not_in_state?`, and delegates
+`current_state`, `transition_to!`, `transition_to`, `can_transition_to?` to
+`state_machine`.
+
+### Class name resolution
+
+```ruby
+model_name      = name                          # e.g. "Admin::Order"
+model_namespace = model_name.deconstantize      # e.g. "Admin"
+model_base      = model_name.demodulize         # e.g. "Order"
+
+transition_class_name    = [model_namespace.presence, model_base, "Transition"].compact.join("::")
+state_machine_class_name = [model_namespace.presence, model_base, "StateMachine"].compact.join("::")
+```
+
+Both class names are constantised at call time (`constantize`), so the nested
+classes must already be defined (autoloaded) when the model is first used.
+
+### `in_state?` / `not_in_state?`
+
+```ruby
+def in_state?(*states)
+  states.any? { |s| current_state.to_sym == s.to_sym }
+end
+
+def not_in_state?(state)
+  !in_state?(state)
+end
+```
+
+Both accept symbols or strings. `in_state?` accepts multiple states (returns
+`true` if current state matches any). `not_in_state?` accepts a single state.
+
+---
+
+## Generator architecture
+
+`StatesmanScaffold::Generator` is a pure Ruby class with no Rails dependency.
+It reads ERB templates from `lib/templates/statesman/` and writes rendered
+output to caller-specified paths.
+
+### Templates
+
+**`state_machine.rb.erb`** — creates `Model::StateMachine` with
+`include Statesman::Machine`, an initial `:pending` state, and commented
+examples of states, transitions, guards, and callbacks.
+
+**`transition.rb.erb`** — creates `Model::Transition < ApplicationRecord` with:
+- `self.table_name` set to `"<underscored_model>_transitions"`
+- `belongs_to` the parent model
+- Attributes: `most_recent`, `to_state`, `sort_key`, `metadata`
+- Validates `to_state` inclusion against `Model::StateMachine.states`
+
+**`migration.rb.erb`** — creates a migration with:
+- `create_table` for `<underscored_model>_transitions`
+- `t.references` with foreign key (handles namespaced models with `to_table:`)
+- `to_state`, `metadata`, `most_recent`, `sort_key`, `timestamps`
+- Two unique indexes: `parent_sort` and `parent_most_recent` (with `WHERE most_recent`)
+
+### Template variables
+
+| Variable | Example | Source |
+|----------|---------|--------|
+| `model` | `"Admin::Order"` | Input parameter |
+| `class_name` | `"Admin::Order"` | Same as `model` (camelized) |
+| `underscored_model` | `"admin_order"` | `model.underscore.tr("/", "_")` |
+| `demodulized_model` | `"order"` | `model.demodulize.underscore` |
+| `version` | `"8.0"` | Migration version |
+
+### Namespaced model handling
+
+For `Admin::Order`:
+- Table name: `admin_order_transitions`
+- `belongs_to :order` (demodulized)
+- Foreign key: `{ to_table: :admin_orders }` (because `underscored_model != demodulized_model`)
+- Migration class: `CreateAdminOrderTransitions`
+
+---
+
+## Installer architecture
+
+```
+Rails app                    statesman_scaffold gem
+─────────────────            ──────────────────────────────────────────────────
+Gemfile ──requires──▶  lib/statesman_scaffold.rb
+                            └── lib/statesman_scaffold/railtie.rb  (only if Rails::Railtie defined)
+                                    └── rake_tasks { load 'lib/tasks/statesman_scaffold.rake' }
+
+$ rails statesman_scaffold:install
+                       ──▶  task :install
+                                └── StatesmanScaffold::Installer.install!(Rails.root)
+                                        └── writes config/initializers/statesman_scaffold.rb
+```
+
+**Why Installer is a separate class:** The rake task calls `Rails.root`, which is
+unavailable in tests without a full Rails boot. By pushing all logic into
+`Installer.install!(root)`, tests can pass any `Pathname` as the root — no
+stubbing, no Rake DSL needed.
+
+**The generated initializer** contains:
+
+```ruby
+require "statesman"
+
+Statesman.configure { storage_adapter(Statesman::Adapters::ActiveRecord) }
+
+ActiveSupport.on_load(:active_record) do
+  include StatesmanScaffold::Concern
+end
+```
+
+The `require "statesman"` ensures the Statesman constant is available when the
+initializer runs. Without it, if Statesman is autoloaded later, the initializer
+would fail with `NameError: uninitialized constant Statesman`.
+
+---
+
+## Rake tasks
+
+| Task | Depends on | Description |
+|------|-----------|-------------|
+| `statesman_scaffold:install` | — | Delegates to `Installer.install!(Rails.root)` |
+| `statesman_scaffold:uninstall` | — | Delegates to `Installer.uninstall!(Rails.root)` |
+| `statesman_scaffold:generate[Model]` | `:environment` | Delegates to `Generator.call(...)` |
+
+The `generate` task:
+1. Camelizes the model argument
+2. Computes `output_path` as `Rails.root.join("app/models", model.underscore)`
+3. Sets `migration_path` to `Rails.root.join("db/migrate")`
+4. Reads `migration_version` from `ActiveRecord::Migration.current_version`
+5. Calls `Generator.call` and prints relative paths of created files
+6. Prints a reminder to add `with_state_machine` to the model
+
+---
+
+## Testing architecture
+
+| Component | Tool | Isolation |
+|-----------|------|-----------|
+| Concern (with_state_machine) | Minitest | SQLite in-memory tables |
+| Generator | Minitest | `Dir.mktmpdir` filesystem |
+| Installer | Minitest | `Dir.mktmpdir` filesystem |
+
+`test_helper.rb` boots ActiveRecord against SQLite, configures Statesman with
+the AR adapter, and calls `ActiveSupport.on_load(:active_record) { include
+StatesmanScaffold::Concern }` to replicate what the Rails initializer does.
+
+### Concern test setup
+
+Test models are defined in a `SmTestModels` namespace with inline
+`StateMachine` and `Transition` classes. Tables are created in `setup` and
+dropped in `teardown`:
+
+- `sm_projects` — main model table
+- `sm_project_transitions` — transitions table
+
+This avoids polluting the global namespace and provides full test isolation.
+
+### Generator test setup
+
+Uses `Dir.mktmpdir` to create a temporary directory. Calls `Generator.call`
+with temporary paths. Asserts file existence, content patterns, and Ruby syntax
+validity (`ruby -c`).
+
+---
+
+## File inclusion in gem package
+
+```ruby
+spec.files = Dir[
+  "lib/**/*.rb",
+  "lib/templates/**/*.erb",
+  "lib/tasks/*.rake",
+  "llms/**/*.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "README.md",
+  "LICENSE.txt",
+  "CHANGELOG.md"
+]
+```
+
+LLM context files (`llms/`, `AGENTS.md`, `CLAUDE.md`) ship inside the released
+gem so that tools that install the gem can serve them as context to AI assistants.