railsmith 1.0.0

data/docs/legacy-adoption.md

@@ -0,0 +1,283 @@
+# Legacy Adoption Guide
+
+How to incrementally introduce Railsmith into an existing Rails application without a big-bang rewrite.
+
+---
+
+## Principles
+
+- **No forced migration.** Old code keeps working. Railsmith services live alongside existing code.
+- **Strangler fig.** Wrap old logic inside services one model at a time, then delete the old paths.
+- **Controller is the seam.** A controller action is the safest place to switch from inline model calls to a service call — the rest of the app stays unchanged.
+- **Ship continuously.** Each phase produces a releasable diff. Never accumulate more than one phase of unreleased work.
+
+---
+
+## Phase 0 — Install without touching existing code
+
+```bash
+bundle add railsmith
+rails generate railsmith:install
+```
+
+Commit only the initializer and empty directories. No behavior changes.
+
+```ruby
+# config/initializers/railsmith.rb
+Railsmith.configure do |config|
+  config.warn_on_cross_domain_calls = true
+  config.strict_mode = false
+  config.fail_on_arch_violations = false  # keep off until Phase 4
+end
+```
+
+Verify nothing is broken:
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## Phase 1 — Audit what you have
+
+Run the architecture checker in warn-only mode to see where models are accessed directly from controllers:
+
+```bash
+rake railsmith:arch_check
+```
+
+Save the output as a baseline. This list is your migration backlog. Prioritize by risk:
+- High-write models (frequently mutated, complex validations) → migrate first.
+- Read-only models → migrate last or skip.
+
+---
+
+## Phase 2 — Wrap one model at a time
+
+Pick the simplest model from your backlog (few validations, no callbacks). Generate its service:
+
+```bash
+rails generate railsmith:model_service Post
+```
+
+Open `app/services/operations/post_service.rb`. For now, leave it as generated — the default CRUD actions are enough for the first replacement.
+
+Find the controller that creates posts. Replace the inline model call:
+
+**Before:**
+
+```ruby
+# app/controllers/posts_controller.rb
+def create
+  @post = Post.new(post_params)
+  if @post.save
+    redirect_to @post
+  else
+    render :new
+  end
+end
+```
+
+**After:**
+
+```ruby
+def create
+  result = Operations::PostService.call(
+    action: :create,
+    params: { attributes: post_params.to_h },
+    context: {}
+  )
+
+  if result.success?
+    redirect_to result.value
+  else
+    @post = Post.new(post_params)  # re-build for form re-render
+    @post.errors.merge!(ActiveModel::Errors.new(@post)) # optional: surface errors
+    flash.now[:alert] = result.error.message
+    render :new
+  end
+end
+```
+
+Test the controller thoroughly. Merge and deploy.
+
+Repeat for `update` and `destroy` on the same model before moving to the next.
+
+---
+
+## Phase 3 — Move business logic into services
+
+Once a controller is routing through a service, move inline business logic (currently in the controller or model callbacks) into the service as custom actions.
+
+**Example — promoting to paid plan:**
+
+Old controller:
+
+```ruby
+def upgrade
+  @user = User.find(params[:id])
+  @user.update!(plan: "paid", upgraded_at: Time.current)
+  BillingMailer.upgraded(@user).deliver_later
+  redirect_to @user
+end
+```
+
+New service action:
+
+```ruby
+# app/services/operations/user_service.rb
+module Operations
+  class UserService < Railsmith::BaseService
+    model(User)
+
+    def upgrade
+      id = params[:id]
+      user = User.find_by(id: id)
+      return Result.failure(error: Errors.not_found(details: { id: id })) unless user
+
+      user.update!(plan: "paid", upgraded_at: Time.current)
+      BillingMailer.upgraded(user).deliver_later
+      Result.success(value: user)
+    end
+  end
+end
+```
+
+Controller:
+
+```ruby
+def upgrade
+  result = Operations::UserService.call(
+    action: :upgrade,
+    params: { id: params[:id] },
+    context: {}
+  )
+  result.success? ? redirect_to result.value : redirect_back(fallback_location: root_path)
+end
+```
+
+---
+
+## Phase 4 — Introduce domain boundaries (optional)
+
+Once several related models are wrapped, group them into a domain.
+
+```bash
+rails generate railsmith:domain Billing
+rails generate railsmith:model_service Billing::Invoice --domain=Billing
+rails generate railsmith:model_service Billing::Payment --domain=Billing
+```
+
+Move the service files from `app/services/operations/` to `app/domains/billing/services/` and add `service_domain`:
+
+```ruby
+module Billing
+  module Services
+    class InvoiceService < Railsmith::BaseService
+      model(Billing::Invoice)
+      service_domain :billing
+    end
+  end
+end
+```
+
+Update all callers to use the new namespace. The `warn_on_cross_domain_calls` flag will surface any places that call billing services from non-billing contexts, without breaking them.
+
+---
+
+## Phase 5 — Enable architecture enforcement in CI
+
+Once the migration is sufficiently complete, turn on the arch check in CI:
+
+```ruby
+# config/initializers/railsmith.rb
+Railsmith.configure do |config|
+  config.fail_on_arch_violations = true
+end
+```
+
+Or via environment variable in CI only:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Architecture check
+  run: RAILSMITH_FAIL_ON_ARCH_VIOLATIONS=true bundle exec rake railsmith:arch_check
+```
+
+This prevents new direct model access from being introduced into controllers.
+
+---
+
+## Migration checklist
+
+Use this checklist per model:
+
+- [ ] Generated service with `rails g railsmith:model_service`
+- [ ] Controller `create` replaced with service call
+- [ ] Controller `update` replaced with service call
+- [ ] Controller `destroy` replaced with service call
+- [ ] Custom controller actions moved to named service methods
+- [ ] Old model callbacks reviewed — move to service if business logic
+- [ ] Tests updated: service spec added, controller spec uses service double or real service
+- [ ] `rake railsmith:arch_check` shows no violations for this model
+
+---
+
+## Testing strategy during migration
+
+**For controllers under migration**, prefer integration tests that call the real service rather than stubbing it. This catches regressions where the controller and service disagree on the interface.
+
+**For services**, write isolated unit specs:
+
+```ruby
+# spec/services/operations/post_service_spec.rb
+RSpec.describe Operations::PostService do
+  describe "#create" do
+    it "creates a post" do
+      result = described_class.call(
+        action: :create,
+        params: { attributes: { title: "Hello", body: "World" } },
+        context: {}
+      )
+      expect(result).to be_success
+      expect(result.value).to be_a(Post)
+      expect(result.value.title).to eq("Hello")
+    end
+
+    it "returns validation_error when title is blank" do
+      result = described_class.call(
+        action: :create,
+        params: { attributes: { title: "", body: "World" } },
+        context: {}
+      )
+      expect(result).to be_failure
+      expect(result.code).to eq("validation_error")
+    end
+  end
+end
+```
+
+---
+
+## Common pitfalls
+
+**Returning the AR error object in failure results.**
+The default CRUD actions handle this automatically. In custom actions, build the error explicitly:
+
+```ruby
+# Correct
+return Result.failure(error: Errors.validation_error(
+  message: record.errors.full_messages.to_sentence,
+  details: { errors: record.errors.to_h }
+))
+```
+
+**Forgetting to forward `context:`.**
+When a service calls another service, always pass `context: context` so domain tracking propagates.
+
+**Wrapping service calls in rescue.**
+Don't. Services return `Result.failure` for all expected error conditions. Rescuing exceptions at the caller layer bypasses error mapping and loses structure.
+
+**Moving too much at once.**
+One model, one PR. Smaller diffs are easier to review and easier to revert.

data/docs/quickstart.md

@@ -0,0 +1,110 @@
+# Railsmith Quickstart
+
+## 1. Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem "railsmith"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+**Requirements**: Ruby >= 3.2.0, Rails 7.0–8.x.
+
+---
+
+## 2. Generate the Initializer
+
+```bash
+rails generate railsmith:install
+```
+
+This creates:
+
+- `config/initializers/railsmith.rb` — global configuration
+- `app/services/` and `app/services/operations/` — service directories
+
+The generated initializer:
+
+```ruby
+# config/initializers/railsmith.rb
+Railsmith.configure do |config|
+  config.warn_on_cross_domain_calls = true
+  config.strict_mode = false
+  config.fail_on_arch_violations = false
+end
+```
+
+---
+
+## 3. Generate Your First Service
+
+```bash
+rails generate railsmith:model_service User
+```
+
+Creates `app/services/operations/user_service.rb`:
+
+```ruby
+module Operations
+  class UserService < Railsmith::BaseService
+    model(User)
+  end
+end
+```
+
+The `model` declaration wires up the three default CRUD actions (`create`, `update`, `destroy`) and the three bulk actions (`bulk_create`, `bulk_update`, `bulk_destroy`) automatically — no extra code needed for standard cases.
+
+---
+
+## 4. Make Your First Call
+
+```ruby
+result = Operations::UserService.call(
+  action: :create,
+  params: { attributes: { name: "Alice", email: "alice@example.com" } },
+  context: {}
+)
+
+if result.success?
+  puts "Created user #{result.value.id}"
+else
+  puts "Failed: #{result.error.message}"
+  puts result.error.details.inspect
+end
+```
+
+Every service call returns a `Railsmith::Result`. You never rescue exceptions from service calls — failures surface as structured `Result` objects.
+
+---
+
+## 5. Result Contract at a Glance
+
+```ruby
+# Success
+result.success?  # => true
+result.value     # => the returned object (e.g., an ActiveRecord instance)
+result.meta      # => optional hash of metadata
+result.to_h
+# => { success: true, value: ..., meta: ... }
+
+# Failure
+result.failure?  # => true
+result.code      # => "not_found" | "validation_error" | "conflict" | "unauthorized" | "unexpected"
+result.error     # => Railsmith::Errors::ErrorPayload
+result.error.message   # => human-readable string
+result.error.details   # => structured hash (model errors, missing keys, etc.)
+result.error.to_h      # => { code: ..., message: ..., details: ... }
+```
+
+---
+
+## 6. Next Steps
+
+- **[Cookbook](cookbook.md)** — CRUD customization, bulk operations, domain context, error mapping, custom actions.
+- **[Legacy Adoption Guide](legacy-adoption.md)** — Incrementally migrate an existing Rails app to Railsmith.

data/lib/generators/railsmith/domain/domain_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Railsmith
+  module Generators
+    # Scaffolds a domain module skeleton under `app/domains`.
+    class DomainGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :output_path,
+                   type: :string,
+                   default: "app/domains",
+                   desc: "Base path where domains are generated"
+
+      def create_domain_module
+        return if skip_existing_file?(target_file)
+
+        create_domain_directories
+        template "domain.rb.tt", target_file
+      end
+
+      private
+
+      def skip_existing_file?(relative_path)
+        absolute = File.join(destination_root, relative_path)
+        return false unless File.exist?(absolute)
+        return false if options[:force]
+
+        say_status(
+          :skip,
+          "#{relative_path} already exists (use --force to overwrite)",
+          :yellow
+        )
+        true
+      end
+
+      def create_domain_directories
+        empty_directory domain_directory
+        empty_directory File.join(domain_directory, "operations")
+        empty_directory File.join(domain_directory, "services")
+      end
+
+      def target_file
+        File.join(options.fetch(:output_path), "#{file_path}.rb")
+      end
+
+      def domain_directory
+        File.join(options.fetch(:output_path), file_path)
+      end
+
+      def domain_modules
+        class_name.split("::")
+      end
+    end
+  end
+end

data/lib/generators/railsmith/domain/templates/domain.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+<% domain_modules.each do |mod| -%>
+module <%= mod %>
+<% end -%>
+  module Operations
+  end
+
+  module Services
+  end
+<% (domain_modules.length - 1).downto(0) do -%>
+end
+<% end -%>
+

data/lib/generators/railsmith/install/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Railsmith
+  module Generators
+    # Installs initializer and base service directories in host app.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "railsmith.rb", "config/initializers/railsmith.rb"
+      end
+
+      def create_service_directories
+        empty_directory "app/services"
+        empty_directory "app/services/operations"
+      end
+    end
+  end
+end

data/lib/generators/railsmith/install/templates/railsmith.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+Railsmith.configure do |config|
+  config.warn_on_cross_domain_calls = true
+  config.strict_mode = false
+  config.fail_on_arch_violations = false # set true (or use RAILSMITH_FAIL_ON_ARCH_VIOLATIONS) to fail CI on arch checks
+  # Approved context_domain → service_domain pairs, e.g.:
+  # config.cross_domain_allowlist = [{ from: :billing, to: :catalog }]
+  config.on_cross_domain_violation = nil # optional Proc, called on each violation when strict_mode is true
+end

data/lib/generators/railsmith/model_service/model_service_generator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "active_support/core_ext/string/inflections"
+
+module Railsmith
+  module Generators
+    # Scaffolds a service class for a given model constant.
+    #
+    # Default mode:
+    # - Generates into `app/services/operations`
+    # - Namespace becomes `Operations::<ModelNamespace>::<Model>Service`
+    #
+    # Domain mode (when --domain is provided):
+    # - Generates into `app/domains/<domain>/services`
+    # - Namespace becomes `<Domain>::Services::<ModelNamespaceWithoutDomain>::<Model>Service`
+    class ModelServiceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :output_path,
+                   type: :string,
+                   default: "app/services/operations",
+                   desc: "Base path where model services are generated"
+
+      class_option :domains_path,
+                   type: :string,
+                   default: "app/domains",
+                   desc: "Base path where domains live (used with --domain)"
+
+      class_option :domain,
+                   type: :string,
+                   default: nil,
+                   desc: "Domain module for domain-mode output (e.g. Billing or Admin::Billing)"
+
+      class_option :actions,
+                   type: :array,
+                   default: [],
+                   desc: "Optional action stubs to include (e.g. create update destroy)"
+
+      def create_model_service
+        if File.exist?(File.join(destination_root, target_file)) && !options[:force]
+          say_status(
+            :skip,
+            "#{target_file} already exists (use --force to overwrite)",
+            :yellow
+          )
+          return
+        end
+
+        template "model_service.rb.tt", target_file
+      end
+
+      private
+
+      def target_file
+        return File.join(options[:output_path], "#{file_path}_service.rb") unless domain_mode?
+
+        File.join(
+          options[:domains_path],
+          domain_file_path,
+          "services",
+          "#{model_file_path}_service.rb"
+        )
+      end
+
+      def service_class_name
+        "#{class_name}Service"
+      end
+
+      def enclosing_modules
+        return default_modules unless domain_mode?
+
+        domain_modules + ["Services"] + model_modules_without_domain
+      end
+
+      def default_modules
+        ["Operations", *model_modules]
+      end
+
+      def model_modules
+        class_name.split("::")[0...-1]
+      end
+
+      def domain_modules
+        options[:domain].to_s.strip.split("::")
+      end
+
+      def model_modules_without_domain
+        class_parts = class_name.split("::")
+        remaining = class_parts.drop(domain_modules.length)
+        remaining[0...-1]
+      end
+
+      def domain_file_path
+        domain_modules.map(&:underscore).join("/")
+      end
+
+      def model_file_path
+        class_parts = class_name.split("::")
+        remaining = class_parts.drop(domain_modules.length)
+        remaining.map(&:underscore).join("/")
+      end
+
+      def domain_mode?
+        !options[:domain].to_s.strip.empty?
+      end
+
+      def declared_actions
+        options
+          .fetch(:actions)
+          .map { |a| a.to_s.strip }
+          .reject(&:empty?)
+          .uniq
+      end
+
+      def stub_action?(action_name)
+        declared_actions.include?(action_name.to_s)
+      end
+    end
+  end
+end

data/lib/generators/railsmith/model_service/templates/model_service.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+<% enclosing_modules.each do |mod| -%>
+module <%= mod %>
+<% end -%>
+  class <%= service_class_name.split("::").last %> < Railsmith::BaseService
+    model(<%= class_name %>)
+
+<% if stub_action?("create") -%>
+    def create
+      super
+    end
+<% end -%>
+<% if stub_action?("update") -%>
+    def update
+      super
+    end
+<% end -%>
+<% if stub_action?("destroy") -%>
+    def destroy
+      super
+    end
+<% end -%>
+  end
+<% (enclosing_modules.length - 1).downto(0) do -%>
+end
+<% end -%>
+