operandi 5.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5cf8967dddc57ff93d3e1d683b9415cbf0e02cfd3d3d195c0ca8f2e12c54213a
+  data.tar.gz: f7ae3f36279bd6fc766501bbd4e189bce375aca6e05822b98d3a08184ed04be3
+SHA512:
+  metadata.gz: d4dbda88f7a0ba6f3caebd978e45770a26471759ad2a9e2990409dc6c21711e102eef1de25dabbd990a39ea5555563ca133dfead3f666dce9c2afb5f374cc2d5
+  data.tar.gz: 9dcbc24eb7d4c955d90fbfaa3c019a1472c6c2119ef91c0fbc6a4114853c860f7a1f41e9b7f2ffc214e49f719e22d4626af2f3bbd9c0575040d70e7e8d0479cb

data/.cursor/rules/services/RULE.md

@@ -0,0 +1,269 @@
+---
+description: "Rules for managing Operandi - Ruby service objects with arguments, steps, and outputs"
+globs: "**/services/**/*.rb"
+alwaysApply: false
+---
+
+# Operandi Creation Rules
+
+When creating or modifying services that inherit from `Operandi::Base` or `ApplicationService`, follow these patterns.
+
+## Service Structure
+
+Always structure services in this order:
+1. Configuration (`config`) if needed
+2. Arguments (`arg`)
+3. Steps (`step`)
+4. Outputs (`output`)
+5. Private methods implementing steps
+
+```ruby
+class ModelName::ActionName < ApplicationService
+  # Arguments
+  arg :required_param, type: String
+  arg :optional_param, type: Integer, optional: true, default: 0
+
+  # Steps
+  step :validate
+  step :perform
+  step :cleanup, always: true
+
+  # Outputs
+  output :result, type: Hash
+
+  private
+
+  def validate
+    errors.add(:required_param, "can't be blank") if required_param.blank?
+  end
+
+  def perform
+    self.result = { success: true }
+  end
+
+  def cleanup
+    # Always runs
+  end
+end
+```
+
+## Naming Conventions
+
+- **Class name**: `ModelName::ActionVerb` (e.g., `User::Create`, `Order::Process`)
+- **File path**: `app/services/model_name/action_verb.rb`
+- **Step methods**: Use descriptive verbs (`validate`, `authorize`, `build_record`, `save`)
+
+## Arguments
+
+```ruby
+# Required with type
+arg :user_id, type: Integer
+
+# Optional with default
+arg :notify, type: [TrueClass, FalseClass], default: true
+
+# Context argument (auto-passed to child services)
+arg :current_user, type: User, optional: true, context: true
+
+# Multiple allowed types
+arg :id, type: [String, Integer]
+
+# Proc default (evaluated at runtime)
+arg :created_at, type: Time, default: -> { Time.current }
+```
+
+## Steps
+
+```ruby
+# Basic step
+step :process
+
+# Conditional execution
+step :send_email, if: :should_notify?
+step :skip_audit, unless: :production?
+
+# Always run (even after errors, unless stop! or stop_immediately! are called)
+step :cleanup, always: true
+
+# Insertion points (for inheritance)
+step :log_action, before: :save
+step :broadcast, after: :save
+```
+
+## Outputs
+
+```ruby
+# Required output
+output :user, type: User
+
+# Optional output
+output :metadata, type: Hash, optional: true
+
+# With default
+output :status, type: String, default: "completed"
+```
+
+## Error Handling
+
+```ruby
+# Add error (stops execution of next steps by default)
+errors.add(:email, "is invalid")
+
+# Add to base
+errors.add(:base, "Something went wrong")
+fail!("Something went wrong")  # Shorthand
+
+# Copy from ActiveRecord model
+errors.copy_from(user)
+
+# Stop next steps without error (commits transaction)
+stop!
+
+# Stop with rollback
+fail_immediately!("Critical error")
+```
+
+## Service Chaining
+
+```ruby
+# Run in same context (shared arguments, errors propagate, rollback propagate)
+ChildService.with(self).run(param: value)
+
+# Independent service (separate transaction)
+OtherService.run(param: value)
+```
+
+## Configuration
+
+```ruby
+config use_transactions: true      # Wrap in DB transaction (default)
+config raise_on_error: false       # Raise exception on error
+config break_on_error: true        # Stop on error (default)
+config rollback_on_error: true     # Rollback on error (default)
+```
+
+## Testing Pattern
+
+```ruby
+RSpec.describe ModelName::ActionName do
+  describe ".run" do
+    subject(:service) { described_class.run(params) }
+    let(:params) { { required_param: "value" } }
+
+    context "when successful" do
+      it { is_expected.to be_successful }
+      it { expect(service.result).to eq(expected) }
+    end
+
+    context "when validation fails" do
+      let(:params) { { required_param: "" } }
+
+      it { is_expected.to be_failed }
+      it { is_expected.to have_error_on(:required_param) }
+    end
+  end
+end
+```
+
+## Common Patterns
+
+### CRUD Create
+```ruby
+class User::Create < CreateRecordService
+  private
+
+  def entity_class
+    User
+  end
+
+  def filtered_params
+    params.slice(:name, :email, :role)
+  end
+end
+```
+
+### With Authorization
+```ruby
+step :authorize
+step :perform
+
+def authorize
+  fail!("Not authorized") unless current_user&.admin?
+end
+```
+
+### With Callbacks
+```ruby
+before_service_run :log_start
+after_service_run :log_finish
+on_service_failure :notify_error
+```
+
+## Using Sorbet Runtime Types
+
+Operandi supports [Sorbet runtime types](https://sorbet.org/docs/runtime) for type validation. Sorbet types **only validate** and do not coerce values.
+
+### Arguments with Sorbet Types
+
+```ruby
+require "sorbet-runtime"
+
+class User::Create < ApplicationService
+  # Basic types
+  arg :name, type: String
+  arg :age, type: Integer
+  
+  # Nilable types
+  arg :email, type: T.nilable(String), optional: true
+  
+  # Union types
+  arg :status, type: T.any(String, Symbol)
+  
+  # Typed arrays
+  arg :tags, type: T::Array[String], optional: true
+  
+  # Boolean type
+  arg :active, type: T::Boolean, default: true
+end
+```
+
+### Outputs with Sorbet Types
+
+```ruby
+class AI::Chat < ApplicationService
+  # Typed array
+  output :messages, type: T::Array[Hash]
+  
+  # Basic type
+  output :total_tokens, type: Integer
+  
+  # Nilable type
+  output :metadata, type: T.nilable(Hash), optional: true
+end
+```
+
+### Validation Behavior
+
+Sorbet types do NOT coerce values - they only validate:
+
+```ruby
+# This will RAISE an error (no coercion)
+service = User::Create.run(name: "John", age: "25")
+# => ArgTypeError: expected Integer, but got String
+
+# This works correctly
+service = User::Create.run(name: "John", age: 25)
+service.age # => 25 (Integer)
+```
+
+### Common Sorbet Type Patterns
+
+| Type | Description |
+|------|-------------|
+| `String` | Must be a String |
+| `Integer` | Must be an Integer |
+| `T.nilable(String)` | String or nil |
+| `T.any(String, Symbol)` | String or Symbol |
+| `T::Array[String]` | Array of Strings |
+| `T::Hash[Symbol, String]` | Hash with Symbol keys and String values |
+| `T::Boolean` | TrueClass or FalseClass |

data/.cursor/rules/services-rspec/RULE.md

@@ -0,0 +1,354 @@
+---
+description: "Rules for writing RSpec tests for Operandi - testing arguments, steps, outputs, and behavior"
+globs: "**/spec/services/*_spec.rb"
+alwaysApply: false
+---
+
+# Operandi RSpec Testing Rules
+
+When writing RSpec tests for services that inherit from `Operandi::Base` or `ApplicationService`, follow these patterns.
+
+## Setup
+
+Add to `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require "operandi/rspec"
+```
+
+## Test Structure
+
+Always structure test files in this order:
+1. Describe block with service class
+2. DSL definition tests (arguments, outputs, steps)
+3. Behavior tests (`.run` scenarios)
+4. Edge cases and error handling
+
+```ruby
+# spec/services/model_name/action_name_spec.rb
+RSpec.describe ModelName::ActionName do
+  # DSL Definition Tests
+  describe "arguments" do
+    it { expect(described_class).to define_argument(:required_param).with_type(String) }
+    it { expect(described_class).to define_argument(:optional_param).with_type(Integer).optional.with_default(0) }
+  end
+
+  describe "outputs" do
+    it { expect(described_class).to define_output(:result).with_type(Hash) }
+  end
+
+  describe "steps" do
+    it { expect(described_class).to define_steps_in_order(:validate, :perform, :cleanup) }
+    it { expect(described_class).to define_step(:cleanup).with_always(true) }
+  end
+
+  # Behavior Tests
+  describe ".run" do
+    subject(:service) { described_class.run(params) }
+    let(:params) { { required_param: "value" } }
+
+    context "when successful" do
+      it { is_expected.to be_successful }
+      it { expect(service.result).to eq(expected_result) }
+    end
+
+    context "when validation fails" do
+      let(:params) { { required_param: "" } }
+      it { is_expected.to be_failed }
+      it { is_expected.to have_error_on(:required_param) }
+    end
+  end
+end
+```
+
+## Naming Conventions
+
+- **File path**: `spec/services/model_name/action_name_spec.rb`
+- **Describe block**: Use the service class name directly
+- **Context blocks**: Start with "when" or "with" to describe conditions
+- **It blocks**: Be specific about what is being tested
+
+## DSL Matchers
+
+### Arguments
+
+```ruby
+# Basic argument
+it { expect(described_class).to define_argument(:id) }
+
+# With type (single or multiple)
+it { expect(described_class).to define_argument(:id).with_type([String, Integer]) }
+
+# Optional with default
+it { expect(described_class).to define_argument(:status).optional.with_default("pending") }
+
+# Context argument
+it { expect(described_class).to define_argument(:current_user).with_context }
+```
+
+### Outputs
+
+```ruby
+# Basic output
+it { expect(described_class).to define_output(:user) }
+
+# With type
+it { expect(described_class).to define_output(:user).with_type(User) }
+
+# Optional with default
+it { expect(described_class).to define_output(:count).optional.with_default(0) }
+```
+
+### Steps
+
+```ruby
+# Basic step
+it { expect(described_class).to define_step(:validate) }
+
+# With always flag
+it { expect(described_class).to define_step(:cleanup).with_always(true) }
+
+# Conditional steps
+it { expect(described_class).to define_step(:notify).with_if(:should_notify?) }
+it { expect(described_class).to define_step(:skip_audit).with_unless(:production?) }
+
+# Multiple steps in order
+it { expect(described_class).to define_steps_in_order(:validate, :process, :save) }
+```
+
+## Behavior Testing
+
+### Success Cases
+
+```ruby
+describe ".run" do
+  subject(:service) { described_class.run(params) }
+  let(:params) { { name: "John", email: "john@example.com" } }
+
+  it { is_expected.to be_successful }
+  it { expect(service.user).to be_persisted }
+  it { expect(service.user.name).to eq("John") }
+end
+```
+
+### Failure Cases
+
+```ruby
+context "when validation fails" do
+  let(:params) { { name: "", email: "" } }
+
+  it { is_expected.to be_failed }
+  it { is_expected.to have_error_on(:name) }
+  it { is_expected.to have_error_on(:email).with_message("can't be blank") }
+  it { is_expected.to have_errors_on(:name, :email) }
+end
+```
+
+### Warnings
+
+```ruby
+it { expect(service.warnings?).to be true }
+it { is_expected.to have_warning_on(:format).with_message("format is deprecated") }
+```
+
+### run! vs run
+
+```ruby
+# .run returns failed service
+it { expect(described_class.run(amount: -100)).to be_failed }
+
+# .run! raises exception
+it { expect { described_class.run!(amount: -100) }.to raise_error(Operandi::Error, /must be positive/) }
+```
+
+### Config Overrides
+
+```ruby
+# With raise_on_error
+expect { described_class.run({ invalid: true }, { raise_on_error: true }) }
+  .to raise_error(Operandi::Error)
+
+# With use_transactions: false
+service = described_class.with(use_transactions: false).run(params)
+```
+
+## Database Testing
+
+```ruby
+# Record creation
+expect { described_class.run(params) }.to change(User, :count).by(1)
+expect(service.user).to be_persisted
+
+# Transaction rollback on failure
+allow_any_instance_of(ChildService).to receive(:perform) do |svc|
+  svc.errors.add(:base, "Simulated failure")
+end
+expect { described_class.run(params) }.not_to change(Order, :count)
+```
+
+## Service Chaining
+
+```ruby
+# Verify context sharing
+expect(ChildService).to receive(:with).and_call_original
+described_class.run(current_user: current_user, data: data)
+
+# Error propagation from child
+allow_any_instance_of(ChildService).to receive(:validate) { |svc| svc.fail!("Child error") }
+expect(described_class.run(current_user: current_user, data: data))
+  .to have_error_on(:base).with_message("Child error")
+```
+
+## Conditional Steps
+
+```ruby
+# When condition is true
+expect { described_class.run(send_notification: true, email: "x@example.com") }
+  .to have_enqueued_mail(UserMailer, :notification)
+
+# When condition is false
+expect { described_class.run(send_notification: false, email: "x@example.com") }
+  .not_to have_enqueued_mail(UserMailer, :notification)
+```
+
+## Early Exit (stop!)
+
+```ruby
+existing_user = create(:user, email: "exists@example.com")
+service = described_class.run(email: existing_user.email)
+
+expect { service }.not_to change(User, :count)
+expect(service.user).to eq(existing_user)
+expect(service).to be_successful
+expect(service.stopped?).to be true
+```
+
+## Argument Validation
+
+```ruby
+# Required argument nil
+expect { described_class.run(name: nil) }.to raise_error(Operandi::ArgTypeError)
+
+# Wrong type
+expect { described_class.run(name: 123) }.to raise_error(Operandi::ArgTypeError, /must be a String/)
+
+# Optional accepts nil
+expect(described_class.run(name: "John", nickname: nil)).to be_successful
+
+# Default values
+expect(described_class.run(name: "John").status).to eq("pending")
+```
+
+## External Services
+
+```ruby
+let(:stripe_client) { instance_double(Stripe::PaymentIntent, id: "pi_123") }
+
+before { allow(Stripe::PaymentIntent).to receive(:create).and_return(stripe_client) }
+
+it "processes payment" do
+  service = described_class.run(amount: 1000, card_token: "tok_visa")
+  expect(service).to be_successful
+  expect(service.payment_intent_id).to eq("pi_123")
+end
+
+context "when external fails" do
+  before { allow(Stripe::PaymentIntent).to receive(:create).and_raise(Stripe::CardError.new("Card declined", nil, nil)) }
+
+  it { expect(service).to be_failed }
+  it { expect(service).to have_error_on(:payment).with_message("Card declined") }
+end
+```
+
+## Optional Tracking
+
+### Step Execution
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Operandi::Base
+  output :executed_steps, type: Array, default: -> { [] }
+  after_step_run { |service, step| service.executed_steps << step }
+end
+```
+
+### Callback Tracking
+
+```ruby
+class ApplicationService < Operandi::Base
+  output :callback_log, type: Array, default: -> { [] }
+  before_service_run { |s| s.callback_log << :before_service_run }
+  after_service_run  { |s| s.callback_log << :after_service_run }
+  on_service_success { |s| s.callback_log << :on_service_success }
+  on_service_failure { |s| s.callback_log << :on_service_failure }
+end
+```
+
+## Shared Examples
+
+### Create Service
+
+```ruby
+RSpec.shared_examples "a create service" do |model_class|
+  let(:valid_attributes) { attributes_for(model_class.name.underscore.to_sym) }
+  let(:current_user) { create(:user) }
+
+  it { expect { described_class.run(current_user: current_user, attributes: valid_attributes) }.to change(model_class, :count).by(1) }
+  it { expect(described_class.run(current_user: current_user, attributes: valid_attributes).record).to be_persisted }
+  it { expect(described_class.run(current_user: current_user, attributes: valid_attributes)).to be_successful }
+end
+```
+
+### Authorized Service
+
+```ruby
+RSpec.shared_examples "an authorized service" do
+  context "without current_user" do
+    let(:current_user) { nil }
+    it { is_expected.to be_failed }
+    it { is_expected.to have_error_on(:authorization) }
+  end
+
+  context "with unauthorized user" do
+    let(:current_user) { create(:user, role: :guest) }
+    it { is_expected.to be_failed }
+    it { is_expected.to have_error_on(:authorization) }
+  end
+end
+```
+
+## Test Helpers
+
+```ruby
+module ServiceHelpers
+  def expect_service_success(service)
+    expect(service).to be_successful, -> { "Expected success but got errors: #{service.errors.to_h}" }
+  end
+
+  def expect_service_failure(service, key = nil)
+    expect(service).to be_failed
+    expect(service.errors[key]).to be_present if key
+  end
+end
+
+RSpec.configure { |config| config.include ServiceHelpers, type: :service }
+```
+
+## Common Matchers Reference
+
+| Matcher | Description |
+|---------|-------------|
+| `be_successful` | Service completed without errors |
+| `be_failed` | Service has errors |
+| `have_error_on(:key)` | Has error on specific key |
+| `have_error_on(:key).with_message(msg)` | Error with specific message |
+| `have_errors_on(:key1, :key2)` | Has errors on multiple keys |
+| `have_warning_on(:key)` | Has warning on specific key |
+| `define_argument(:name)` | Service defines argument |
+| `define_output(:name)` | Service defines output |
+| `define_step(:name)` | Service defines step |
+| `define_steps(:a, :b, :c)` | Service defines all steps (any order) |
+| `define_steps_in_order(:a, :b, :c)` | Service defines steps in order |
+| `execute_step(:name)` | Step was executed (tracking required) |
+| `skip_step(:name)` | Step was skipped (tracking required) |
+| `trigger_callback(:name)` | Callback was triggered (tracking required) |

data/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  rspec:
+    name: RSpec (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.1", "3.2", "3.3", "3.4"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install SQLite
+        run: sudo apt-get install -y libsqlite3-dev
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run RSpec
+        run: bundle exec rspec
+
+  codecov:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install SQLite
+        run: sudo apt-get install -y libsqlite3-dev
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Run RSpec
+        run: bundle exec rspec
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage/coverage.xml
+          fail_ci_if_error: true