railsmith 1.0.0 → 1.1.0

data/docs/cookbook.md

@@ -13,37 +13,37 @@ rails generate railsmith:model_service Post
 ```
 
 ```ruby
-# app/services/operations/post_service.rb
-module Operations
-  class PostService < Railsmith::BaseService
-    model(Post)
-  end
+# app/services/post_service.rb
+class PostService < Railsmith::BaseService
+  model(Post)
 end
 ```
 
-The three default actions work immediately:
+The five default actions work immediately (`context:` is optional on all calls):
 
 ```ruby
 # Create
-result = Operations::PostService.call(
+result = PostService.call(
   action: :create,
-  params: { attributes: { title: "Hello", body: "World" } },
-  context: {}
+  params: { attributes: { title: "Hello", body: "World" } }
 )
 
 # Update
-result = Operations::PostService.call(
+result = PostService.call(
   action: :update,
-  params: { id: 1, attributes: { title: "Updated" } },
-  context: {}
+  params: { id: 1, attributes: { title: "Updated" } }
 )
 
 # Destroy
-result = Operations::PostService.call(
-  action: :destroy,
-  params: { id: 1 },
-  context: {}
-)
+result = PostService.call(action: :destroy, params: { id: 1 })
+
+# Find a single record by ID
+result = PostService.call(action: :find, params: { id: 1 })
+result.value  # => <Post id=1>
+
+# List all records
+result = PostService.call(action: :list, params: {})
+result.value  # => [<Post>, ...]
 ```
 
 ---
@@ -53,15 +53,13 @@ result = Operations::PostService.call(
 Override `sanitize_attributes` to strip or transform attributes before the record is written:
 
 ```ruby
-module Operations
-  class PostService < Railsmith::BaseService
-    model(Post)
+class PostService < Railsmith::BaseService
+  model(Post)
 
-    private
+  private
 
-    def sanitize_attributes(attributes)
-      attributes.except(:admin_override, :internal_flag)
-    end
+  def sanitize_attributes(attributes)
+    attributes.except(:admin_override, :internal_flag)
   end
 end
 ```
@@ -79,15 +77,28 @@ end
 ### Custom finder logic
 
 ```ruby
-module Operations
-  class PostService < Railsmith::BaseService
-    model(Post)
+class PostService < Railsmith::BaseService
+  model(Post)
 
-    private
+  private
 
-    def find_record(model_klass, id)
-      model_klass.published.find_by(id: id)
-    end
+  def find_record(model_klass, id)
+    model_klass.published.find_by(id: id)
+  end
+end
+```
+
+### Filtering list results
+
+Override `list` to apply scopes or filters:
+
+```ruby
+class PostService < Railsmith::BaseService
+  model(Post)
+
+  def list
+    posts = Post.where(published: params[:published]).order(:created_at)
+    Result.success(value: posts)
   end
 end
 ```
@@ -99,22 +110,20 @@ end
 Define a method with the action name. Use `Result` and `Errors` directly:
 
 ```ruby
-module Operations
-  class PostService < Railsmith::BaseService
-    model(Post)
+class PostService < Railsmith::BaseService
+  model(Post)
 
-    def publish
-      id = params[:id]
-      return Result.failure(error: Errors.validation_error(details: { missing: ["id"] })) unless id
+  def publish
+    id = params[:id]
+    return Result.failure(error: Errors.validation_error(details: { missing: ["id"] })) unless id
 
-      post = Post.find_by(id: id)
-      return Result.failure(error: Errors.not_found(message: "Post not found", details: { id: id })) unless post
+    post = Post.find_by(id: id)
+    return Result.failure(error: Errors.not_found(message: "Post not found", details: { id: id })) unless post
 
-      return Result.failure(error: Errors.conflict(message: "Already published")) if post.published?
+    return Result.failure(error: Errors.conflict(message: "Already published")) if post.published?
 
-      post.update!(published_at: Time.current)
-      Result.success(value: post)
-    end
+    post.update!(published_at: Time.current)
+    Result.success(value: post)
   end
 end
 ```
@@ -122,11 +131,7 @@ end
 Call it the same way:
 
 ```ruby
-result = Operations::PostService.call(
-  action: :publish,
-  params: { id: 42 },
-  context: {}
-)
+result = PostService.call(action: :publish, params: { id: 42 })
 ```
 
 ---
@@ -136,30 +141,29 @@ result = Operations::PostService.call(
 Pass `context` through to preserve domain tracking:
 
 ```ruby
-module Operations
-  class OrderService < Railsmith::BaseService
-    model(Order)
-
-    def place
-      # Validate stock via another service
-      stock_result = Operations::InventoryService.call(
-        action: :reserve,
-        params: { sku: params[:sku], qty: params[:qty] },
-        context: context  # forward the same context
-      )
-      return stock_result if stock_result.failure?
-
-      result = Operations::OrderService.call(
-        action: :create,
-        params: { attributes: { sku: params[:sku], qty: params[:qty] } },
-        context: context
-      )
-      result
-    end
+class OrderService < Railsmith::BaseService
+  model(Order)
+
+  def place
+    # Validate stock via another service
+    stock_result = InventoryService.call(
+      action: :reserve,
+      params: { sku: params[:sku], qty: params[:qty] },
+      context: context  # forward the same context
+    )
+    return stock_result if stock_result.failure?
+
+    OrderService.call(
+      action: :create,
+      params: { attributes: { sku: params[:sku], qty: params[:qty] } },
+      context: context
+    )
   end
 end
 ```
 
+Alternatively, use thread-local context propagation (see [Thread-local context](#thread-local-context-propagation)) so you don't need to thread `context:` through every call.
+
 ---
 
 ## Bulk Operations
@@ -167,7 +171,7 @@ end
 ### bulk_create
 
 ```ruby
-result = Operations::UserService.call(
+result = UserService.call(
   action: :bulk_create,
   params: {
     items: [
@@ -197,7 +201,7 @@ end
 Each item must include an `id` key and an `attributes` key:
 
 ```ruby
-result = Operations::UserService.call(
+result = UserService.call(
   action: :bulk_update,
   params: {
     items: [
@@ -217,14 +221,14 @@ Pass IDs directly or as hashes:
 
 ```ruby
 # Array of IDs
-result = Operations::UserService.call(
+result = UserService.call(
   action: :bulk_destroy,
   params: { items: [1, 2, 3] },
   context: {}
 )
 
 # Array of hashes
-result = Operations::UserService.call(
+result = UserService.call(
   action: :bulk_destroy,
   params: { items: [{ id: 1 }, { id: 2 }] },
   context: {}
@@ -242,7 +246,7 @@ result = Operations::UserService.call(
 
 ```ruby
 # All-or-nothing import
-result = Operations::UserService.call(
+result = UserService.call(
   action: :bulk_create,
   params: {
     items: rows,
@@ -309,7 +313,7 @@ module Billing
   module Services
     class InvoiceService < Railsmith::BaseService
       model(Billing::Invoice)
-      service_domain :billing
+      domain :billing
     end
   end
 end
@@ -317,13 +321,16 @@ end
 
 ---
 
-### Pass domain context on every call
+### Pass domain context on a call
+
+Use `Railsmith::Context` to attach domain and tracing data. Extra keys (`actor_id`, `request_id`, etc.) are top-level — no nested `:meta` hash:
 
 ```ruby
-ctx = Railsmith::DomainContext.new(
-  current_domain: :billing,
-  meta: { request_id: "req-abc123", actor_id: current_user.id }
-).to_h
+ctx = Railsmith::Context.new(
+  domain: :billing,
+  actor_id: current_user.id
+  # request_id is auto-generated as a UUID when omitted
+)
 
 result = Billing::Services::InvoiceService.call(
   action: :create,
@@ -332,13 +339,45 @@ result = Billing::Services::InvoiceService.call(
 )
 ```
 
-`DomainContext#to_h` merges `current_domain` and all `meta` keys into one flat hash, which is what `context:` expects.
+To forward an existing request ID (e.g. from an HTTP header):
+
+```ruby
+ctx = Railsmith::Context.new(
+  domain: :billing,
+  request_id: request.headers["X-Request-Id"],
+  actor_id: current_user.id
+)
+```
+
+---
+
+### Thread-local context propagation
+
+Set context once at the edge of a request instead of threading it through every call:
+
+```ruby
+# app/controllers/application_controller.rb
+around_action do |_, block|
+  Railsmith::Context.with(domain: :web, actor_id: current_user&.id) { block.call }
+end
+```
+
+Services automatically inherit the thread-local context when no explicit `context:` is passed:
+
+```ruby
+# No context: needed — picked up from Context.with above
+UserService.call(action: :create, params: { attributes: { name: "Alice" } })
+```
+
+Resolution order: **explicit `context:` arg > `Context.current` > auto-built context**.
+
+`Context.with` restores the previous value after the block, making it safe for nested calls and concurrent requests.
 
 ---
 
 ### Cross-domain detection
 
-When `current_domain` in the context differs from a service's declared `service_domain`, Railsmith emits a warning. By default this is non-blocking.
+When the context domain differs from a service's declared `domain`, Railsmith emits a warning. By default this is non-blocking.
 
 ```ruby
 # context says :catalog, service declares :billing — warning fires
@@ -391,35 +430,39 @@ Allowlisted pairs do not emit warnings.
 rails generate railsmith:operation Billing::Invoices::Finalize
 ```
 
-Creates `app/domains/billing/operations/invoices/finalize.rb`:
+Creates `app/domains/billing/invoices/finalize.rb`:
 
 ```ruby
 module Billing
-  module Operations
-    module Invoices
-      class Finalize
-        def self.call(params: {}, context: {})
-          new(params:, context:).call
-        end
-
-        attr_reader :params, :context
-
-        def initialize(params:, context:)
-          @params  = Railsmith.deep_dup(params  || {})
-          @context = Railsmith.deep_dup(context || {})
-        end
-
-        def call
-          current_domain = Railsmith::DomainContext.normalize_current_domain(context[:current_domain])
-          # Your logic here
-          Railsmith::Result.success(value: { current_domain: current_domain })
-        end
+  module Invoices
+    class Finalize
+      def self.call(params: {}, context: {})
+        new(params:, context:).call
+      end
+
+      attr_reader :params, :context
+
+      def initialize(params:, context:)
+        @params = Railsmith.deep_dup(params || {})
+        @context = Railsmith::Context.build(context)
+      end
+
+      def call
+        Railsmith::Result.success(value: {})
       end
     end
   end
 end
 ```
 
+To keep the old `Operations` interstitial module:
+
+```bash
+rails generate railsmith:operation Billing::Invoices::Finalize --namespace=Operations
+# => app/domains/billing/operations/invoices/finalize.rb
+# => Billing::Operations::Invoices::Finalize
+```
+
 ---
 
 ## Error Mapping
@@ -494,10 +537,10 @@ The default `create`, `update`, and `destroy` actions catch and map these except
 ```ruby
 class UsersController < ApplicationController
   def create
-    result = Operations::UserService.call(
+    result = UserService.call(
       action: :create,
       params: { attributes: user_params },
-      context: { current_domain: :identity }
+      context: Railsmith::Context.new(domain: :identity)
     )
 
     if result.success?

data/docs/legacy-adoption.md

@@ -61,7 +61,7 @@ Pick the simplest model from your backlog (few validations, no callbacks). Gener
 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.
+Open `app/services/post_service.rb` (or `app/services/operations/post_service.rb` if you passed `--namespace=Operations`). 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:
 
@@ -83,10 +83,9 @@ end
 
 ```ruby
 def create
-  result = Operations::PostService.call(
+  result = PostService.call(
     action: :create,
-    params: { attributes: post_params.to_h },
-    context: {}
+    params: { attributes: post_params.to_h }
   )
 
   if result.success?
@@ -126,20 +125,18 @@ 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
+# app/services/user_service.rb
+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
 ```
@@ -148,10 +145,9 @@ Controller:
 
 ```ruby
 def upgrade
-  result = Operations::UserService.call(
+  result = UserService.call(
     action: :upgrade,
-    params: { id: params[:id] },
-    context: {}
+    params: { id: params[:id] }
   )
   result.success? ? redirect_to result.value : redirect_back(fallback_location: root_path)
 end
@@ -169,14 +165,14 @@ 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`:
+Move the service files from `app/services/` (or `app/services/operations/` if you used the old default) into `app/domains/billing/services/` and add `domain`:
 
 ```ruby
 module Billing
   module Services
     class InvoiceService < Railsmith::BaseService
       model(Billing::Invoice)
-      service_domain :billing
+      domain :billing
     end
   end
 end
@@ -231,14 +227,13 @@ Use this checklist per model:
 **For services**, write isolated unit specs:
 
 ```ruby
-# spec/services/operations/post_service_spec.rb
-RSpec.describe Operations::PostService do
+# spec/services/post_service_spec.rb
+RSpec.describe PostService do
   describe "#create" do
     it "creates a post" do
       result = described_class.call(
         action: :create,
-        params: { attributes: { title: "Hello", body: "World" } },
-        context: {}
+        params: { attributes: { title: "Hello", body: "World" } }
       )
       expect(result).to be_success
       expect(result.value).to be_a(Post)
@@ -248,8 +243,7 @@ RSpec.describe Operations::PostService do
     it "returns validation_error when title is blank" do
       result = described_class.call(
         action: :create,
-        params: { attributes: { title: "", body: "World" } },
-        context: {}
+        params: { attributes: { title: "", body: "World" } }
       )
       expect(result).to be_failure
       expect(result.code).to eq("validation_error")
@@ -274,7 +268,7 @@ return Result.failure(error: Errors.validation_error(
 ```
 
 **Forgetting to forward `context:`.**
-When a service calls another service, always pass `context: context` so domain tracking propagates.
+When a service calls another service, pass `context: context` unless you rely on thread-local `Railsmith::Context.with` at the controller edge — then nested calls inherit the same context automatically.
 
 **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.

data/docs/quickstart.md

@@ -14,7 +14,7 @@ Then:
 bundle install
 ```
 
-**Requirements**: Ruby >= 3.2.0, Rails 7.0–8.x.
+**Requirements**: Ruby >= 3.1.0, Rails 7.0–8.x.
 
 ---
 
@@ -48,27 +48,32 @@ end
 rails generate railsmith:model_service User
 ```
 
-Creates `app/services/operations/user_service.rb`:
+Creates `app/services/user_service.rb`:
 
 ```ruby
-module Operations
-  class UserService < Railsmith::BaseService
-    model(User)
-  end
+class UserService < Railsmith::BaseService
+  model(User)
 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.
+The `model` declaration wires up the default CRUD actions (`create`, `update`, `destroy`, `find`, `list`) and the three bulk actions (`bulk_create`, `bulk_update`, `bulk_destroy`) automatically — no extra code needed for standard cases.
+
+To generate under a namespace, pass `--namespace`:
+
+```bash
+rails generate railsmith:model_service User --namespace=Operations
+# => app/services/operations/user_service.rb
+# => module Operations; class UserService
+```
 
 ---
 
 ## 4. Make Your First Call
 
 ```ruby
-result = Operations::UserService.call(
+result = UserService.call(
   action: :create,
-  params: { attributes: { name: "Alice", email: "alice@example.com" } },
-  context: {}
+  params: { attributes: { name: "Alice", email: "alice@example.com" } }
 )
 
 if result.success?
@@ -81,6 +86,16 @@ end
 
 Every service call returns a `Railsmith::Result`. You never rescue exceptions from service calls — failures surface as structured `Result` objects.
 
+`context:` is optional. When omitted, Railsmith builds a context automatically (with an auto-generated `request_id`). Pass one explicitly to attach domain, actor, or tracing data:
+
+```ruby
+UserService.call(
+  action: :create,
+  params: { attributes: { name: "Alice", email: "alice@example.com" } },
+  context: Railsmith::Context.new(domain: :identity, actor_id: current_user.id)
+)
+```
+
 ---
 
 ## 5. Result Contract at a Glance
@@ -106,5 +121,6 @@ result.error.to_h      # => { code: ..., message: ..., details: ... }
 
 ## 6. Next Steps
 
-- **[Cookbook](cookbook.md)** — CRUD customization, bulk operations, domain context, error mapping, custom actions.
+- **[Cookbook](cookbook.md)** — CRUD customization, bulk operations, domain context, thread-local context, error mapping, custom actions.
 - **[Legacy Adoption Guide](legacy-adoption.md)** — Incrementally migrate an existing Rails app to Railsmith.
+- **[Migration Guide](../MIGRATION.md)** — Upgrade notes from 1.0.0 to 1.1.0.