dexkit 0.7.0 → 0.9.0

data/lib/dex/operation/transaction_wrapper.rb

@@ -7,10 +7,10 @@ module Dex
     DEFERRED_CALLBACKS_KEY = :_dex_after_commit_queue
 
     def _transaction_wrap
-      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      deferred = Fiber[DEFERRED_CALLBACKS_KEY]
       outermost = deferred.nil?
-      Thread.current[DEFERRED_CALLBACKS_KEY] = [] if outermost
-      snapshot = Thread.current[DEFERRED_CALLBACKS_KEY].length
+      Fiber[DEFERRED_CALLBACKS_KEY] = [] if outermost
+      snapshot = Fiber[DEFERRED_CALLBACKS_KEY].length
 
       result, interceptor = if _transaction_enabled?
         _transaction_run_adapter(snapshot) { yield }
@@ -23,16 +23,16 @@ module Dex
       interceptor&.rethrow!
       result
     rescue # rubocop:disable Style/RescueStandardError -- explicit for clarity
-      Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+      Fiber[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
       raise
     ensure
-      Thread.current[DEFERRED_CALLBACKS_KEY] = nil if outermost
+      Fiber[DEFERRED_CALLBACKS_KEY] = nil if outermost
     end
 
     def after_commit(&block)
       raise ArgumentError, "after_commit requires a block" unless block
 
-      deferred = Thread.current[DEFERRED_CALLBACKS_KEY]
+      deferred = Fiber[DEFERRED_CALLBACKS_KEY]
       if deferred
         deferred << block
       else
@@ -40,8 +40,6 @@ module Dex
       end
     end
 
-    TRANSACTION_KNOWN_ADAPTERS = %i[active_record mongoid].freeze
-
     module ClassMethods
       def transaction(enabled_or_options = nil, **options)
         validate_options!(options, %i[adapter], :transaction)
@@ -66,11 +64,7 @@ module Dex
       def _transaction_validate_adapter!(adapter)
         return if adapter.nil?
 
-        unless TransactionWrapper::TRANSACTION_KNOWN_ADAPTERS.include?(adapter.to_sym)
-          raise ArgumentError,
-            "unknown transaction adapter: #{adapter.inspect}. " \
-            "Known: #{TransactionWrapper::TRANSACTION_KNOWN_ADAPTERS.map(&:inspect).join(", ")}"
-        end
+        Operation::TransactionAdapter.normalize_name(adapter)
       end
     end
 
@@ -85,7 +79,7 @@ module Dex
       end
 
       if interceptor&.error?
-        Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+        Fiber[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
         interceptor.rethrow!
       end
 
@@ -96,7 +90,7 @@ module Dex
       interceptor = Operation::HaltInterceptor.new { yield }
 
       if interceptor.error?
-        Thread.current[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
+        Fiber[DEFERRED_CALLBACKS_KEY]&.slice!(snapshot..)
         interceptor.rethrow!
       end
 
@@ -117,7 +111,7 @@ module Dex
     end
 
     def _transaction_flush_deferred
-      callbacks = Thread.current[DEFERRED_CALLBACKS_KEY]
+      callbacks = Fiber[DEFERRED_CALLBACKS_KEY]
       return if callbacks.empty?
 
       flush = -> { callbacks.each(&:call) }

data/lib/dex/operation.rb

@@ -49,7 +49,32 @@ module Dex
     include TypeCoercion
     include ContextSetup
 
-    Contract = Data.define(:params, :success, :errors, :guards)
+    Contract = Data.define(:params, :success, :errors, :guards) do
+      attr_reader :source_class
+
+      def initialize(params:, success:, errors:, guards:, source_class: nil)
+        @source_class = source_class
+        super(params: params, success: success, errors: errors, guards: guards)
+      end
+
+      def to_h
+        if @source_class
+          Operation::Export.build_hash(@source_class, self)
+        else
+          super
+        end
+      end
+
+      def to_json_schema(**options)
+        unless @source_class
+          raise ArgumentError, "to_json_schema requires a source_class (use OperationClass.contract.to_json_schema)"
+        end
+
+        Operation::Export.build_json_schema(@source_class, self, **options)
+      end
+    end
+
+    extend Registry
 
     class << self
       def contract
@@ -57,10 +82,25 @@ module Dex
           params: _contract_params,
           success: _success_type,
           errors: _declared_errors,
-          guards: _contract_guards
+          guards: _contract_guards,
+          source_class: self
         )
       end
 
+      def export(format: :hash, **options)
+        unless %i[hash json_schema].include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect}. Known: :hash, :json_schema"
+        end
+
+        sorted = registry.sort_by(&:name)
+        sorted.map do |klass|
+          case format
+          when :hash then klass.contract.to_h
+          when :json_schema then klass.contract.to_json_schema(**options)
+          end
+        end
+      end
+
       private
 
       def _contract_params
@@ -116,6 +156,10 @@ require_relative "operation/async_proxy"
 require_relative "operation/record_backend"
 require_relative "operation/transaction_adapter"
 require_relative "operation/jobs"
+require_relative "operation/explain"
+require_relative "operation/export"
+
+Dex::Operation.extend(Dex::Operation::Explain)
 
 # Top-level aliases (depend on Operation::Ok/Err)
 require_relative "match"

data/lib/dex/props_setup.rb

@@ -17,10 +17,17 @@ module Dex
     end
 
     module ClassMethods
-      def prop(name, type, kind = :keyword, **options, &block)
+      def prop(name, type, kind = :keyword, desc: nil, **options, &block)
         if const_defined?(:RESERVED_PROP_NAMES) && self::RESERVED_PROP_NAMES.include?(name)
           raise ArgumentError, "Property :#{name} is reserved."
         end
+        if !desc.nil?
+          raise ArgumentError, "desc: must be a String, got #{desc.class}" unless desc.is_a?(String)
+
+          _prop_desc_own[name] = desc
+        elsif superclass.respond_to?(:prop_descriptions) && superclass.prop_descriptions.key?(name)
+          _prop_desc_own[name] = nil
+        end
         options[:reader] = :public unless options.key?(:reader)
         if type.is_a?(Dex::RefType) && !block
           ref = type
@@ -29,7 +36,12 @@ module Dex
         super(name, type, kind, **options, &block)
       end
 
-      def prop?(name, type, kind = :keyword, **options, &block)
+      def prop?(name, type, kind = :keyword, desc: nil, **options, &block)
+        if !desc.nil?
+          raise ArgumentError, "desc: must be a String, got #{desc.class}" unless desc.is_a?(String)
+
+          _prop_desc_own[name] = desc
+        end
         options[:reader] = :public unless options.key?(:reader)
         options[:default] = nil unless options.key?(:default)
         if type.is_a?(Dex::RefType) && !block
@@ -39,9 +51,20 @@ module Dex
         prop(name, _Nilable(type), kind, **options, &block)
       end
 
+      def prop_descriptions
+        parent = superclass.respond_to?(:prop_descriptions) ? superclass.prop_descriptions : {}
+        parent.merge(_prop_desc_own).compact
+      end
+
       def _Ref(model_class, lock: false) # rubocop:disable Naming/MethodName
         Dex::RefType.new(model_class, lock: lock)
       end
+
+      private
+
+      def _prop_desc_own
+        @_prop_desc_own ||= {}
+      end
     end
   end
 end

data/lib/dex/query/backend.rb

@@ -76,16 +76,29 @@ module Dex
       module_function
 
       def apply_strategy(scope, strategy, column, value)
+        scope = normalize_scope(scope)
         adapter_for(scope).apply(scope, strategy, column, value)
       end
 
       def adapter_for(scope)
+        scope = normalize_scope(scope)
+
         if defined?(Mongoid::Criteria) && scope.is_a?(Mongoid::Criteria)
           MongoidAdapter
         else
           ActiveRecordAdapter
         end
       end
+
+      def normalize_scope(scope)
+        return scope unless defined?(Mongoid::Criteria)
+        return scope if scope.is_a?(Mongoid::Criteria)
+
+        criteria = scope.criteria if scope.respond_to?(:criteria)
+        criteria.is_a?(Mongoid::Criteria) ? criteria : scope
+      rescue
+        scope
+      end
     end
   end
 end

data/lib/dex/query.rb

@@ -209,9 +209,10 @@ module Dex
     end
 
     def resolve
-      base = _evaluate_scope
+      base = Query::Backend.normalize_scope(_evaluate_scope)
       base = _merge_injected_scope(base)
       base = _apply_filters(base)
+      base = Query::Backend.normalize_scope(base)
       _apply_sort(base)
     end
 
@@ -253,19 +254,22 @@ module Dex
     def _merge_injected_scope(base)
       return base unless @_injected_scope
 
+      base = Query::Backend.normalize_scope(base)
+      injected_scope = Query::Backend.normalize_scope(@_injected_scope)
+
       unless base.respond_to?(:klass)
         raise ArgumentError, "Scope block must return a queryable scope (ActiveRecord relation or Mongoid criteria), got #{base.class}."
       end
 
-      unless @_injected_scope.respond_to?(:klass)
+      unless injected_scope.respond_to?(:klass)
         raise ArgumentError, "Injected scope must be a queryable scope (ActiveRecord relation or Mongoid criteria), got #{@_injected_scope.class}."
       end
 
-      unless base.klass == @_injected_scope.klass
-        raise ArgumentError, "Scope model mismatch: expected #{base.klass}, got #{@_injected_scope.klass}."
+      unless base.klass == injected_scope.klass
+        raise ArgumentError, "Scope model mismatch: expected #{base.klass}, got #{injected_scope.klass}."
       end
 
-      base.merge(@_injected_scope)
+      base.merge(injected_scope)
     end
   end
 end

data/lib/dex/railtie.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Dex
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      namespace :dex do
+        desc "Export operation/event/handler contracts (FORMAT=hash|json_schema SECTION=operations|events|handlers FILE=path)"
+        task export: :environment do
+          Rails.application.eager_load!
+
+          format = (ENV["FORMAT"] || "hash").to_sym
+          section = ENV["SECTION"] || "operations"
+          file = ENV["FILE"]
+
+          data = case section
+          when "operations" then Dex::Operation.export(format: format)
+          when "events" then Dex::Event.export(format: format)
+          when "handlers"
+            if format != :hash
+              raise "Handlers only support FORMAT=hash (got #{format})"
+            end
+
+            Dex::Event::Handler.export(format: format)
+          else
+            raise "Unknown SECTION=#{section}. Known: operations, events, handlers"
+          end
+
+          json = JSON.pretty_generate(data)
+
+          if file
+            File.write(file, json)
+            puts "Wrote #{data.size} #{section} to #{file}"
+          else
+            puts json
+          end
+        end
+
+        desc "Install LLM guides as AGENTS.md in app directories (FORCE=1 to overwrite app-owned files)"
+        task :guides do
+          gem_root = File.expand_path("../..", __dir__)
+          guide_dir = File.join(gem_root, "guides", "llm")
+          marker = "<!-- dexkit v#{Dex::VERSION} | Auto-generated by: rake dex:guides -->"
+          force = ENV["FORCE"] == "1"
+          written = 0
+
+          # [source_file, env_var, default_path]
+          mapping = [
+            ["OPERATION.md", "OPERATIONS_PATH", "app/operations"],
+            ["EVENT.md", "EVENTS_PATH", "app/events"],
+            ["EVENT.md", "EVENT_HANDLERS_PATH", "app/event_handlers"],
+            ["FORM.md", "FORMS_PATH", "app/forms"],
+            ["QUERY.md", "QUERIES_PATH", "app/queries"]
+          ]
+
+          mapping.each do |source_file, env_var, default_path|
+            target_dir = ENV[env_var] || default_path
+
+            unless File.directory?(target_dir)
+              puts "  #{target_dir}/AGENTS.md  (skipped — directory not found)"
+              next
+            end
+
+            target = File.join(target_dir, "AGENTS.md")
+
+            if File.exist?(target) && !force
+              first_line = File.open(target, &:readline).chomp rescue "" # rubocop:disable Style/RescueModifier
+              unless first_line.start_with?("<!-- dexkit v")
+                puts "  #{target}  (skipped — not generated by dexkit, use FORCE=1 to overwrite)"
+                next
+              end
+            end
+
+            source = File.join(guide_dir, source_file)
+            File.write(target, "#{marker}\n\n#{File.read(source)}")
+            written += 1
+            puts "  #{target}  ← #{source_file}"
+          end
+
+          puts "\n#{written} guide(s) installed."
+        end
+      end
+    end
+  end
+end

data/lib/dex/ref_type.rb

@@ -7,6 +7,10 @@ module Dex
     attr_reader :model_class, :lock
 
     def initialize(model_class, lock: false)
+      if lock && !model_class.respond_to?(:lock)
+        raise ArgumentError, "_Ref(lock: true) requires a model class that responds to .lock"
+      end
+
       @model_class = model_class
       @lock = lock
     end

data/lib/dex/registry.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Dex
+  module Registry
+    def self.extended(base)
+      base.instance_variable_set(:@_registry, Set.new)
+    end
+
+    def inherited(subclass)
+      super
+      _dex_registry.add(subclass)
+    end
+
+    def registry
+      live = _dex_registry.select { |k| k.name && _dex_reachable?(k) }
+      _dex_registry.replace(live)
+      live.to_set.freeze
+    end
+
+    def deregister(klass)
+      _dex_registry.delete(klass)
+    end
+
+    def clear!
+      _dex_registry.clear
+    end
+
+    def description(text = nil)
+      if !text.nil?
+        raise ArgumentError, "description must be a String" unless text.is_a?(String)
+
+        @_description = text
+      else
+        defined?(@_description) ? @_description : _dex_parent_description
+      end
+    end
+
+    private
+
+    def _dex_reachable?(klass)
+      Object.const_get(klass.name) == klass
+    rescue NameError
+      false
+    end
+
+    def _dex_registry
+      if instance_variable_defined?(:@_registry)
+        @_registry
+      elsif superclass.respond_to?(:_dex_registry, true)
+        superclass.send(:_dex_registry)
+      else
+        @_registry = Set.new
+      end
+    end
+
+    def _dex_parent_description
+      return nil unless superclass.respond_to?(:description)
+      return nil if superclass.instance_variable_defined?(:@_registry)
+
+      superclass.description
+    end
+  end
+end

data/lib/dex/test_helpers.rb

@@ -1,148 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "test_log"
+require_relative "operation/test_helpers"
+require_relative "event/test_helpers"
 
 module Dex
-  module TestWrapper
-    @_installed = false
-
-    class << self
-      def install!
-        return if @_installed
-
-        Dex::Operation.prepend(self)
-        @_installed = true
-      end
-
-      def installed?
-        @_installed
-      end
-
-      # Stub registry
-
-      def stubs
-        @_stubs ||= {}
-      end
-
-      def find_stub(klass)
-        stubs[klass]
-      end
-
-      def register_stub(klass, **options)
-        stubs[klass] = options
-      end
-
-      def clear_stub(klass)
-        stubs.delete(klass)
-      end
-
-      def clear_all_stubs!
-        stubs.clear
-      end
-    end
-
-    def call
-      stub = Dex::TestWrapper.find_stub(self.class)
-      return _test_apply_stub(stub) if stub
-
-      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = nil
-      err = nil
-
-      begin
-        result = super
-      rescue Exception => e # rubocop:disable Lint/RescueException
-        err = e
-        raise
-      ensure
-        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
-        _test_record_to_log(result, err, duration)
-      end
-
-      result
-    end
-
-    private
-
-    def _test_apply_stub(stub)
-      if stub[:error]
-        err_opts = stub[:error]
-        case err_opts
-        when Symbol
-          raise Dex::Error.new(err_opts)
-        when Hash
-          raise Dex::Error.new(err_opts[:code], err_opts[:message], details: err_opts[:details])
-        end
-      else
-        stub[:returns]
-      end
-    end
-
-    def _test_safe_params
-      respond_to?(:to_h) ? to_h : {}
-    rescue
-      {}
-    end
-
-    def _test_record_to_log(result, err, duration)
-      safe_result = if err
-        dex_err = if err.is_a?(Dex::Error)
-          err
-        else
-          Dex::Error.new(:exception, err.message, details: { exception_class: err.class.name })
-        end
-        Dex::Operation::Err.new(dex_err)
-      else
-        Dex::Operation::Ok.new(result)
-      end
-
-      entry = Dex::TestLog::Entry.new(
-        type: "Operation",
-        name: self.class.name || self.class.to_s,
-        operation_class: self.class,
-        params: _test_safe_params,
-        result: safe_result,
-        duration: duration,
-        caller_location: caller_locations(4, 1)&.first
-      )
-      Dex::TestLog.record(entry)
-    end
-  end
-
   module TestHelpers
-    extend Dex::Concern
-
     def self.included(base)
-      Dex::TestWrapper.install!
-      super
-    end
-
-    def setup
-      super
-      Dex::TestLog.clear!
-      Dex::TestWrapper.clear_all_stubs!
-    end
-
-    module ClassMethods
-      def testing(klass)
-        @_dex_test_subject = klass
-      end
-
-      def _dex_test_subject
-        return @_dex_test_subject if defined?(@_dex_test_subject) && @_dex_test_subject
-
-        superclass._dex_test_subject if superclass.respond_to?(:_dex_test_subject)
-      end
-    end
-
-    private
-
-    def _dex_test_subject
-      self.class._dex_test_subject
+      base.include(Dex::Operation::TestHelpers)
+      base.include(Dex::Event::TestHelpers)
     end
   end
 end
-
-require_relative "test_helpers/execution"
-require_relative "test_helpers/assertions"
-require_relative "test_helpers/stubbing"

data/lib/dex/tool.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Dex
+  module Tool
+    module_function
+
+    def from(operation_class)
+      _require_ruby_llm!
+      _build_tool(operation_class)
+    end
+
+    def all
+      _require_ruby_llm!
+      Operation.registry.sort_by(&:name).map { |klass| _build_tool(klass) }
+    end
+
+    def from_namespace(namespace)
+      _require_ruby_llm!
+      prefix = "#{namespace}::"
+      Operation.registry
+        .select { |op| op.name&.start_with?(prefix) }
+        .sort_by(&:name)
+        .map { |klass| _build_tool(klass) }
+    end
+
+    def explain_tool
+      _require_ruby_llm!
+      _build_explain_tool
+    end
+
+    def _require_ruby_llm!
+      require "ruby_llm"
+    rescue LoadError
+      raise LoadError,
+        "Dex::Tool requires the ruby-llm gem. Add `gem 'ruby_llm'` to your Gemfile."
+    end
+
+    def _build_tool(operation_class) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      op = operation_class
+      schema = op.contract.to_json_schema
+      tool_description = _tool_description(op)
+
+      Class.new(RubyLLM::Tool) do
+        define_method(:name) { "dex_#{op.name.gsub("::", "_").downcase}" }
+        define_method(:description) { tool_description }
+        define_method(:params_schema) { schema }
+
+        define_method(:execute) do |**params|
+          coerced = params.transform_keys(&:to_sym)
+          result = op.new(**coerced).safe.call
+          case result
+          when Dex::Operation::Ok
+            value = result.value
+            value.respond_to?(:as_json) ? value.as_json : value
+          when Dex::Operation::Err
+            { error: result.code, message: result.message, details: result.details }
+          end
+        end
+      end.new
+    end
+
+    def _tool_description(op)
+      parts = []
+      desc = op.description
+      parts << desc if desc
+      parts << op.name unless desc
+
+      guards = op.contract.guards
+      if guards.any?
+        messages = guards.map { |g| g[:message] || g[:name].to_s }
+        parts << "Preconditions: #{messages.join("; ")}."
+      end
+
+      errors = op.contract.errors
+      parts << "Errors: #{errors.join(", ")}." if errors.any?
+
+      parts.join("\n")
+    end
+
+    def _build_explain_tool # rubocop:disable Metrics/MethodLength
+      Class.new(RubyLLM::Tool) do
+        define_method(:name) { "dex_explain" }
+        define_method(:description) { "Check if an operation can be executed with given params, without running it." }
+        define_method(:params_schema) do
+          {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            type: "object",
+            properties: {
+              "operation" => { type: "string", description: "Operation class name (e.g. 'Order::Place')" },
+              "params" => { type: "object", description: "Params to check" }
+            },
+            required: ["operation"],
+            additionalProperties: false
+          }
+        end
+
+        define_method(:execute) do |operation:, params: {}|
+          op_class = Dex::Operation.registry.find { |klass| klass.name == operation }
+          return { error: "unknown_operation", message: "Operation '#{operation}' not found in registry" } unless op_class
+
+          coerced = params.transform_keys(&:to_sym)
+          info = op_class.explain(**coerced)
+          {
+            callable: info[:callable],
+            guards: info[:guards],
+            once: info[:once],
+            lock: info[:lock]
+          }
+        end
+      end.new
+    end
+
+    private_class_method :_require_ruby_llm!, :_build_tool, :_tool_description, :_build_explain_tool
+  end
+end