statesman_scaffold 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cbb9daaf63b955b29f50bf88b2bd3289356982558e7fb850c1fb1d0848104a8
+  data.tar.gz: 403cf58478d56041e182c84b1d8cbd78d64ea86ca3543b36efb89ebe5f691f23
+SHA512:
+  metadata.gz: 1d574af74d46523405ce37bc80a8c1ba1b9dbc71a8e1025f1b29d9586f98fbb141c4d9ca14517298a91ac090eb8b634d0cb28fec186d28db0ac0e44abcad0326
+  data.tar.gz: 80e5402b96703129bf738d6b86fcfba25593d9f85048b9a6ba518f4426974973c8b0449768421ea227d08aa8c6ded8ed52e3af8b8c71a72f23630928b43d3a43

data/AGENTS.md

@@ -0,0 +1,180 @@
+# AGENTS.md — statesman_scaffold
+
+> Concise reference for AI coding agents working **on** the `statesman_scaffold`
+> gem or **with** it inside a host Rails application.
+>
+> For end-user documentation see `README.md`.
+> For LLM-optimised usage patterns see `llms/usage.md`.
+> For architecture details see `llms/overview.md`.
+
+---
+
+## What this gem does
+
+`statesman_scaffold` scaffolds [Statesman](https://github.com/gocardless/statesman)
+state machines for ActiveRecord models and provides a `with_state_machine`
+concern that wires up delegation, query scopes, and transition associations.
+
+```ruby
+# 1. Generate files
+# rails "statesman_scaffold:generate[Project]"
+
+# 2. Add to model
+class Project < ApplicationRecord
+  with_state_machine
+end
+
+# 3. Use
+project = Project.create!(name: "Demo")
+project.current_state           # => "pending"
+project.transition_to!(:active)
+project.in_state?(:active)      # => true
+```
+
+It is a **Rails-only** gem (depends on `activesupport >= 7`, `activerecord >= 7`,
+`railties >= 7`, `statesman >= 10`). Works only with
+`Statesman::Adapters::ActiveRecord`.
+
+---
+
+## Quick integration checklist (host app)
+
+```bash
+bundle add statesman_scaffold
+rails statesman_scaffold:install       # creates config/initializers/statesman_scaffold.rb
+rails "statesman_scaffold:generate[ModelName]"  # generates files
+```
+
+After `install` every model inherits the `with_state_machine` macro. No
+`include` needed.
+
+---
+
+## `with_state_machine` macro signature
+
+```ruby
+with_state_machine(
+  transition_suffix: "Transition",
+  state_machine_suffix: "StateMachine"
+)
+```
+
+| Parameter | Type | Default | Notes |
+|-----------|------|---------|-------|
+| `transition_suffix` | `String` | `"Transition"` | Suffix for the transition class |
+| `state_machine_suffix` | `String` | `"StateMachine"` | Suffix for the state machine class |
+
+The macro expects `Model::StateMachine` and `Model::Transition` to exist.
+Use the `generate` rake task to create them.
+
+---
+
+## Instance methods added by the concern
+
+| Method | Delegates to | Description |
+|--------|-------------|-------------|
+| `current_state` | `state_machine` | Returns the current state as a string |
+| `transition_to!(state)` | `state_machine` | Transitions to state; raises on failure |
+| `transition_to(state)` | `state_machine` | Transitions to state; returns `true`/`false` |
+| `can_transition_to?(state)` | `state_machine` | Checks if transition is valid |
+| `in_state?(*states)` | — | Returns `true` if current state matches any given state |
+| `not_in_state?(state)` | — | Returns `true` if current state does not match |
+
+Class-level scopes from `Statesman::Adapters::ActiveRecordQueries`:
+- `Model.in_state(:active, :pending)`
+- `Model.not_in_state(:cancelled)`
+
+---
+
+## Rules agents must follow
+
+### Always
+- Run `rails statesman_scaffold:install` before first use in a host app.
+- Call `with_state_machine` **after** any custom `has_many` declarations.
+- Define states, transitions, and callbacks in the generated `StateMachine` class.
+- Add an `after_transition` callback to sync the status column if you have one.
+- Run `rails db:migrate` after generating files.
+- The `statesman` gem must be in the host app's Gemfile.
+
+### Never
+- Manually create StateMachine/Transition classes without the generator (or follow the exact template patterns).
+- Call `with_state_machine` more than once on the same model.
+- Define a `has_many :transitions` on the model — `with_state_machine` does it.
+- Stub `Rails.root` in tests — use `Installer.install!(tmpdir)` or `Generator.call(...)` with real paths.
+
+---
+
+## Gem internals (working on the gem itself)
+
+### Module map
+
+| File | Responsibility |
+|------|----------------|
+| `lib/statesman_scaffold/concern.rb` | `with_state_machine` class macro + `in_state?`/`not_in_state?` |
+| `lib/statesman_scaffold/generator.rb` | ERB template rendering for StateMachine, Transition, migration |
+| `lib/statesman_scaffold/installer.rb` | Creates/removes `config/initializers/statesman_scaffold.rb` |
+| `lib/statesman_scaffold/railtie.rb` | Registers all `statesman_scaffold:*` rake tasks |
+| `lib/tasks/statesman_scaffold.rake` | Rake task implementations (install/uninstall/generate) |
+| `lib/templates/statesman/*.erb` | ERB templates for generated files |
+
+### Generated files (per model)
+
+| Template | Output | Description |
+|----------|--------|-------------|
+| `state_machine.rb.erb` | `app/models/<model>/state_machine.rb` | Statesman::Machine class with example states |
+| `transition.rb.erb` | `app/models/<model>/transition.rb` | Transition model with validations |
+| `migration.rb.erb` | `db/migrate/TIMESTAMP_create_<model>_transitions.rb` | Migration with indexes |
+
+### Test suite
+
+```bash
+bundle exec rake test     # Minitest with SQLite in-memory
+bundle exec rake          # default task
+```
+
+Tests live in `test/statesman_scaffold/`. Each test class uses `setup`/`teardown`
+to create and drop SQLite tables so tests are fully isolated.
+
+### Adding a new test
+
+1. Extend `Minitest::Test` inside the `StatesmanScaffold` module namespace.
+2. Name the file `test/statesman_scaffold/<feature>_test.rb`.
+3. Create tables in `setup`, drop them in `teardown`.
+4. Generator/Installer tests use `Dir.mktmpdir` for filesystem isolation.
+
+---
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `NameError: uninitialized constant Statesman` | Initializer runs before `statesman` gem is loaded | Ensure `gem "statesman"` is in Gemfile; re-run `rails statesman_scaffold:install` (initializer now includes `require "statesman"`) |
+| `NameError: uninitialized constant Model::StateMachine` | StateMachine class not generated or not loaded | Run `rails "statesman_scaffold:generate[Model]"` and ensure file is in autoload path |
+| `Statesman::TransitionFailedError` | Transition not allowed from current state | Check `StateMachine` class transition rules |
+| `ActiveRecord::StatementInvalid` (missing table) | Migration not run | Run `rails db:migrate` |
+| Transitions not persisted | Statesman not configured for AR adapter | Run `rails statesman_scaffold:install` |
+| Status column not updated after transition | No `after_transition` callback | Add `after_transition { |m, t| m.update!(status: t.to_state) }` to StateMachine |
+
+---
+
+## Dependencies
+
+| Gem | Version | Why |
+|-----|---------|-----|
+| `statesman` | `>= 10.0, < 13` | State machine engine |
+| `activerecord` | `>= 7.0, < 9` | AR integration (has_many, migrations) |
+| `activesupport` | `>= 7.0, < 9` | `Concern`, `camelize`, `underscore`, `on_load` |
+| `railties` | `>= 7.0, < 9` | `Rails::Railtie` for exposing rake tasks |
+| `sqlite3` | dev only | In-memory DB for tests |
+| `minitest` | dev only | Test framework |
+
+---
+
+## Test conventions
+
+- Use `Minitest::Test` (not `ActiveSupport::TestCase`)
+- AR schema is created in `setup` with `force: true` and dropped in `teardown`
+- `InstallerTest` and `GeneratorTest` use `Dir.mktmpdir` — always clean up in `teardown`
+- `assert` / `refute` preferred over `assert_equal true/false`
+- Group related tests with comment banners: `# --- install! ---`
+- Test method names describe the exact behaviour: `test_install_creates_the_initializer_file`

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-07
+
+### Added
+
+- `StatesmanScaffold::Concern` with the `with_state_machine` class macro
+- `in_state?` and `not_in_state?` instance methods for state checking
+- Delegation of `current_state`, `transition_to!`, `transition_to`, `can_transition_to?`
+- `Statesman::Adapters::ActiveRecordQueries` integration for query scopes
+- `StatesmanScaffold::Generator` for creating StateMachine, Transition, and migration files from ERB templates
+- `StatesmanScaffold::Installer` for creating/removing the Rails initializer
+- `StatesmanScaffold::Railtie` with `statesman_scaffold:install`, `statesman_scaffold:uninstall`, and `statesman_scaffold:generate` rake tasks
+- Support for namespaced models (e.g. `Admin::Order`)

data/CLAUDE.md

@@ -0,0 +1,126 @@
+# StatesmanScaffold -- Claude Project Context
+
+> Project-level instructions and context for Claude Code when working inside
+> the `statesman_scaffold` gem repository.
+
+## Project overview
+
+`statesman_scaffold` is a Ruby gem that scaffolds [Statesman](https://github.com/gocardless/statesman)
+state machines for ActiveRecord models. It generates StateMachine, Transition classes,
+and migrations via rake tasks, and provides a `with_state_machine` concern for wiring
+everything up with a single macro call.
+
+## Repository layout
+
+```
+lib/
+  statesman_scaffold.rb              # Entry point -- require this in host apps
+  statesman_scaffold/
+    concern.rb                       # Core: with_state_machine macro via ActiveSupport::Concern
+    generator.rb                     # ERB template renderer for state machine files
+    installer.rb                     # Manages config/initializers/statesman_scaffold.rb
+    railtie.rb                       # Rails integration, exposes rake tasks
+    version.rb                       # Version constant
+  templates/
+    statesman/
+      state_machine.rb.erb           # Template for StateMachine class
+      transition.rb.erb              # Template for Transition model
+      migration.rb.erb               # Template for migration file
+  tasks/
+    statesman_scaffold.rake          # install / uninstall / generate rake tasks
+test/
+  test_helper.rb                     # SQLite in-memory, Statesman AR adapter config
+  test_statesman_scaffold.rb         # Version number test
+  statesman_scaffold/
+    concern_test.rb                  # Tests for with_state_machine macro
+    generator_test.rb                # Tests for ERB template generation
+    installer_test.rb                # Tests for Installer class
+llms/
+  overview.md                        # Architecture deep-dive for LLMs
+  usage.md                           # Common patterns and recipes
+AGENTS.md                            # Concise guide for AI coding agents
+CLAUDE.md                            # This file
+```
+
+## Development workflow
+
+```bash
+bundle install
+bundle exec rake test      # run Minitest suite (SQLite in-memory)
+bundle exec rake           # tests (default)
+bin/console                # IRB with gem loaded
+```
+
+## Rake tasks (in host Rails apps)
+
+| Task | Description |
+|------|-------------|
+| `rails statesman_scaffold:install` | Create `config/initializers/statesman_scaffold.rb` |
+| `rails statesman_scaffold:uninstall` | Remove `config/initializers/statesman_scaffold.rb` |
+| `rails "statesman_scaffold:generate[ModelName]"` | Generate StateMachine, Transition, and migration |
+
+## Code style
+
+- **Double quotes** throughout (enforced by RuboCop).
+- Frozen string literals on every file.
+- Nested module/class syntax (`module StatesmanScaffold; class Concern`) preferred.
+- Test files use `module StatesmanScaffold; class XxxTest < Minitest::Test` nesting.
+- Metrics limits: `MethodLength: Max: 15`; test files are excluded from metrics.
+
+## Key design decisions
+
+1. **`with_state_machine` resolves class names dynamically** at call time using
+   the model's `name`. It expects `Model::StateMachine` and `Model::Transition`
+   to exist (generated via the rake task). Accepts optional `transition_suffix:`
+   and `state_machine_suffix:` keyword arguments.
+
+2. **Concern delegates** `current_state`, `transition_to!`, `transition_to`, and
+   `can_transition_to?` to a lazily-initialized state machine instance.
+
+3. **`in_state?` accepts multiple states** and compares via `.to_sym` for
+   symbol/string interoperability. `not_in_state?` accepts a single state.
+
+4. **Statesman::Adapters::ActiveRecordQueries** is auto-included by
+   `with_state_machine`, giving the model class-level `.in_state` and
+   `.not_in_state` query scopes.
+
+5. **Generator is decoupled from Rails**: `StatesmanScaffold::Generator` takes
+   `Pathname` arguments and never references `Rails.root`, making it unit-testable
+   with a `Dir.mktmpdir`. Returns a `Result` struct with all output paths.
+
+6. **Installer is decoupled from Rails**: `StatesmanScaffold::Installer` takes a
+   `Pathname` root and never references `Rails.root`, making it unit-testable
+   with a `Dir.mktmpdir`.
+
+7. **The generated initializer** does three things:
+   - `require "statesman"` (ensures the gem is loaded before configuring)
+   - `Statesman.configure { storage_adapter(Statesman::Adapters::ActiveRecord) }`
+   - `ActiveSupport.on_load(:active_record) { include StatesmanScaffold::Concern }`
+
+8. **Templates use ERB** with `trim_mode: "-"` and `result_with_hash` for clean
+   rendering without binding objects.
+
+## When adding features
+
+- State machine wiring logic belongs in `concern.rb`.
+- New public class-level DSL methods belong inside `class_methods do`.
+- Template changes go in `lib/templates/statesman/`.
+- Update `sig/statesman_scaffold.rbs` when adding or changing public method signatures.
+- Write Minitest tests in `test/statesman_scaffold/` before implementing (TDD).
+- Run `bundle exec rake` before committing -- must be fully green.
+
+## Dependency notes
+
+- `statesman` provides `Statesman::Machine`, `Statesman::Adapters::ActiveRecord`,
+  and `Statesman::Adapters::ActiveRecordQueries`.
+- `activerecord` provides `has_many`, `ActiveRecord::Base`, and migrations.
+- `activesupport` provides `ActiveSupport::Concern`, `String#camelize`,
+  `String#underscore`, `String#demodulize`, `String#deconstantize`.
+- `railties` provides `Rails::Railtie` for rake task integration.
+
+## Out of scope (do not add unless explicitly requested)
+
+- Custom transition metadata helpers.
+- State machine visualization or diagram generation.
+- Support for non-ActiveRecord ORMs.
+- Automatic state column management (users define their own status columns).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Pawel Niemczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# StatesmanScaffold
+
+Scaffold [Statesman](https://github.com/gocardless/statesman) state machines for ActiveRecord models. Generates StateMachine, Transition classes, and migrations with a single rake task, plus a `with_state_machine` concern that wires up delegation, query scopes, and transition associations.
+
+## Features
+
+* One rake task generates StateMachine class, Transition model, and migration
+* `with_state_machine` class macro wires up Statesman with a single line
+* Delegates `current_state`, `transition_to!`, `transition_to`, `can_transition_to?` to the state machine
+* Adds `in_state?` and `not_in_state?` convenience predicates
+* Includes `Statesman::Adapters::ActiveRecordQueries` for query scopes
+* Supports namespaced models (e.g. `Admin::Order`)
+* Rails installer that configures Statesman adapter and auto-includes the concern
+
+## Installation
+
+Add to your application's `Gemfile`:
+
+```ruby
+gem "statesman_scaffold"
+```
+
+Then run:
+
+```bash
+bundle install
+rails statesman_scaffold:install
+```
+
+The installer creates `config/initializers/statesman_scaffold.rb` which configures Statesman to use the ActiveRecord adapter and auto-includes `StatesmanScaffold::Concern` into every ActiveRecord model.
+
+## Usage
+
+### Generate state machine files
+
+```bash
+rails "statesman_scaffold:generate[Project]"
+```
+
+This creates three files:
+
+* `app/models/project/state_machine.rb` – the Statesman state machine class
+* `app/models/project/transition.rb` – the transition model
+* `db/migrate/TIMESTAMP_create_project_transitions.rb` – the migration
+
+### Configure your model
+
+```ruby
+class Project < ApplicationRecord
+  STATUSES = Project::StateMachine.states
+
+  with_state_machine
+
+  attribute :status, :string, default: Project::StateMachine.initial_state
+  validates :status, inclusion: { in: STATUSES }, allow_nil: true
+end
+```
+
+### Define states and transitions
+
+Edit the generated `app/models/project/state_machine.rb`:
+
+```ruby
+class Project::StateMachine
+  include Statesman::Machine
+
+  state :active, initial: true
+  state :pending
+  state :skipped
+  state :cancelled
+  state :done
+
+  transition from: :active, to: [:pending, :skipped, :cancelled, :done]
+  transition from: :pending, to: [:skipped, :cancelled, :done]
+  transition from: :skipped, to: [:pending]
+
+  after_transition do |model, transition|
+    model.update!(status: transition.to_state)
+  end
+end
+```
+
+### Use the state machine
+
+```ruby
+project = Project.create!(name: "Demo")
+
+project.current_state              # => "active"
+project.in_state?(:active)         # => true
+project.not_in_state?(:done)       # => true
+
+project.can_transition_to?(:pending) # => true
+project.transition_to!(:pending)
+project.current_state              # => "pending"
+project.status                     # => "pending"
+
+# Non-bang version returns true/false instead of raising
+project.transition_to(:done)       # => true
+
+# Query scopes (via Statesman::Adapters::ActiveRecordQueries)
+Project.in_state(:active)
+Project.not_in_state(:cancelled)
+```
+
+### Namespaced models
+
+```bash
+rails "statesman_scaffold:generate[Admin::Order]"
+```
+
+This generates `Admin::Order::StateMachine`, `Admin::Order::Transition`, and the corresponding migration with proper table names and foreign keys.
+
+## Rake tasks
+
+```bash
+rails statesman_scaffold:install    # create config/initializers/statesman_scaffold.rb
+rails statesman_scaffold:uninstall  # remove config/initializers/statesman_scaffold.rb
+rails "statesman_scaffold:generate[ModelName]"  # generate state machine files
+```
+
+## Manual include (without the Rails initializer)
+
+```ruby
+class Project < ApplicationRecord
+  include StatesmanScaffold::Concern
+  with_state_machine
+end
+```
+
+## Development
+
+```bash
+bin/setup         # install dependencies
+bundle exec rake  # run tests
+bin/console       # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pniemczyk/statesman_scaffold.
+
+## License
+
+MIT -- see [LICENSE.txt](LICENSE.txt).

data/lib/statesman_scaffold/concern.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module StatesmanScaffold
+  # ActiveSupport::Concern that provides the +with_state_machine+ class macro
+  # for wiring up Statesman state machines to ActiveRecord models.
+  #
+  # @example
+  #   class Project < ApplicationRecord
+  #     include StatesmanScaffold::Concern
+  #     with_state_machine
+  #   end
+  #
+  #   project = Project.create!(name: "Demo")
+  #   project.current_state          # => "pending"
+  #   project.can_transition_to?(:active) # => true/false
+  #   project.transition_to!(:active)
+  #   project.in_state?(:active)     # => true
+  #   project.not_in_state?(:pending) # => true
+  module Concern
+    extend ActiveSupport::Concern
+
+    included do
+      # Check if the model is currently in any of the given states.
+      #
+      # @param states [Array<String, Symbol>] one or more state names
+      # @return [Boolean]
+      def in_state?(*states)
+        states.any? { |s| current_state.to_sym == s.to_sym }
+      end
+
+      # Check if the model is NOT in the given state.
+      #
+      # @param state [String, Symbol] a state name
+      # @return [Boolean]
+      def not_in_state?(state)
+        !in_state?(state)
+      end
+
+      delegate :can_transition_to?, :transition_to!, :transition_to, :current_state, to: :state_machine
+    end
+
+    class_methods do
+      # Wires up the Statesman state machine for this model.
+      #
+      # Expects nested +StateMachine+ and +Transition+ classes to exist under
+      # the model's namespace (e.g. +Project::StateMachine+, +Project::Transition+).
+      #
+      # Use the +statesman_scaffold:generate+ rake task to create these classes
+      # and the corresponding migration.
+      #
+      # @param transition_suffix [String] suffix for the transition class (default: "Transition")
+      # @param state_machine_suffix [String] suffix for the state machine class (default: "StateMachine")
+      def with_state_machine(transition_suffix: "Transition", state_machine_suffix: "StateMachine")
+        model_name      = name
+        model_namespace = model_name.deconstantize
+        model_base      = model_name.demodulize
+
+        transition_class_name     = [model_namespace.presence, model_base, transition_suffix].compact.join("::")
+        state_machine_class_name  = [model_namespace.presence, model_base, state_machine_suffix].compact.join("::")
+
+        has_many :transitions,
+                 autosave: false,
+                 class_name: transition_class_name,
+                 dependent: :destroy
+
+        include ::Statesman::Adapters::ActiveRecordQueries[
+          transition_class: transition_class_name.constantize,
+          initial_state: state_machine_class_name.constantize.initial_state
+        ]
+
+        define_method(:state_machine) do
+          instance_variable_get(:@state_machine) ||
+            instance_variable_set(
+              :@state_machine,
+              state_machine_class_name.constantize.new(
+                self,
+                transition_class: transition_class_name.constantize,
+                association_name: :transitions
+              )
+            )
+        end
+      end
+    end
+  end
+end

data/lib/statesman_scaffold/generator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "erb"
+require "pathname"
+
+module StatesmanScaffold
+  # Generates StateMachine, Transition class files, and a migration from ERB
+  # templates. This class is intentionally decoupled from Rails so it can be
+  # tested without booting a full Rails application.
+  #
+  # @example
+  #   StatesmanScaffold::Generator.call(
+  #     model: "Project",
+  #     output_path: Pathname.new("app/models/project"),
+  #     migration_path: Pathname.new("db/migrate"),
+  #     migration_version: "8.0"
+  #   )
+  class Generator
+    TEMPLATE_DIR = Pathname.new(__dir__).join("..", "templates", "statesman").expand_path
+
+    Result = Struct.new(:state_machine_path, :transition_path, :migration_path, keyword_init: true) # rubocop:disable Style/RedundantStructKeywordInit
+
+    class << self
+      # Generate all three files for the given model.
+      #
+      # @param model [String] PascalCase model name (e.g. "Project", "Admin::Order")
+      # @param output_path [Pathname, String] directory for model files
+      # @param migration_path [Pathname, String] directory for migration file
+      # @param migration_version [String] ActiveRecord migration version (e.g. "8.0")
+      # @param timestamp [String, nil] migration timestamp (default: current UTC)
+      # @return [Result] paths of created files
+      def call(model:, output_path:, migration_path:, migration_version:, timestamp: nil)
+        model       = model.to_s.camelize
+        class_name  = model
+        output_path = Pathname(output_path)
+        migration_path = Pathname(migration_path)
+        timestamp ||= Time.now.utc.strftime("%Y%m%d%H%M%S")
+
+        output_path.mkpath
+        migration_path.mkpath
+
+        sm_path = render_template(
+          "state_machine.rb.erb",
+          output_path.join("state_machine.rb"),
+          model: model, class_name: class_name
+        )
+
+        tr_path = render_template(
+          "transition.rb.erb",
+          output_path.join("transition.rb"),
+          model: model, class_name: class_name
+        )
+
+        file_path = model.underscore.tr("/", "_")
+        mig_file = "#{timestamp}_create_#{file_path}_transitions.rb"
+        mig_path = render_template(
+          "migration.rb.erb",
+          migration_path.join(mig_file),
+          model: model, class_name: class_name, version: migration_version
+        )
+
+        Result.new(
+          state_machine_path: sm_path,
+          transition_path: tr_path,
+          migration_path: mig_path
+        )
+      end
+
+      private
+
+      def render_template(template_name, output_file, **locals)
+        template_path = TEMPLATE_DIR.join(template_name)
+        erb = ERB.new(template_path.read, trim_mode: "-")
+        content = erb.result_with_hash(locals)
+        output_file.write(content)
+        output_file
+      end
+    end
+  end
+end