dexkit 0.6.0 → 0.8.0

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/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/assertions.rb

@@ -214,6 +214,29 @@ module Dex
         "Expected #{model_class.name} count to increase, but it stayed at #{count_before}"
     end
 
+    # --- Guard assertions ---
+
+    def assert_callable(*args, **params)
+      klass = _dex_resolve_subject(args)
+      result = klass.callable(**params)
+      assert result.ok?, "Expected operation to be callable, but guards failed:\n#{_dex_format_err(result)}"
+      result
+    end
+
+    def refute_callable(*args, **params)
+      klass_args, codes = _dex_split_class_and_symbols(args)
+      klass = _dex_resolve_subject(klass_args)
+      code = codes.first
+      result = klass.callable(**params)
+      refute result.ok?, "Expected operation to NOT be callable, but all guards passed"
+      if code
+        failed_codes = result.details.map { |f| f[:guard] }
+        assert_includes failed_codes, code,
+          "Expected guard :#{code} to fail, but it didn't.\n  Failed guards: #{failed_codes.inspect}"
+      end
+      result
+    end
+
     # --- Batch assertions ---
 
     def assert_all_succeed(*args, params_list:)

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

data/lib/dex/type_serializer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Dex
+  module TypeSerializer
+    module_function
+
+    # --- Human-readable string ---
+
+    def to_string(type)
+      case type
+      when Dex::RefType
+        "Ref(#{type.model_class.name})"
+      when Literal::Types::NilableType
+        "Nilable(#{to_string(type.type)})"
+      when Literal::Types::ArrayType
+        "Array(#{to_string(type.type)})"
+      when Literal::Types::UnionType
+        _union_string(type)
+      when Literal::Types::ConstraintType
+        _constraint_string(type)
+      when Literal::Types::BooleanType
+        "Boolean"
+      when Class
+        type.name || type.to_s
+      else
+        type.inspect
+      end
+    end
+
+    # --- JSON Schema ---
+
+    BIGDECIMAL_PATTERN = '^-?\d+\.?\d*$'
+
+    def to_json_schema(type, desc: nil)
+      schema = _type_to_schema(type)
+      schema[:description] = desc if desc
+      schema
+    end
+
+    def _type_to_schema(type) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity
+      case type
+      when Dex::RefType
+        { type: "string", description: "#{type.model_class.name} ID" }
+      when Literal::Types::NilableType
+        { oneOf: [_type_to_schema(type.type), { type: "null" }] }
+      when Literal::Types::ArrayType
+        { type: "array", items: _type_to_schema(type.type) }
+      when Literal::Types::UnionType
+        _union_schema(type)
+      when Literal::Types::ConstraintType
+        _constraint_schema(type)
+      when Literal::Types::BooleanType
+        { type: "boolean" }
+      when Class
+        _class_schema(type)
+      else
+        {}
+      end
+    end
+
+    def _union_string(type)
+      items = if type.primitives&.any?
+        type.primitives.map(&:inspect)
+      else
+        type.types.map { |t| to_string(t) }
+      end
+      "Union(#{items.join(", ")})"
+    end
+
+    def _constraint_string(type)
+      constraints = type.object_constraints
+      return "{}" if constraints.empty?
+
+      base = constraints.first
+      rest = constraints[1..]
+      base_str = base.is_a?(Class) ? (base.name || base.to_s) : base.inspect
+      if rest.empty?
+        base_str
+      else
+        "#{base_str}(#{rest.map(&:inspect).join(", ")})"
+      end
+    end
+
+    def _union_schema(type)
+      if type.primitives&.any?
+        { enum: type.primitives.to_a }
+      else
+        { oneOf: type.types.map { |t| _type_to_schema(t) } }
+      end
+    end
+
+    def _constraint_schema(type)
+      constraints = type.object_constraints
+      return {} if constraints.empty?
+
+      base = constraints.first
+      schema = base.is_a?(Class) ? _class_schema(base) : {}
+      _apply_range_constraints(schema, constraints[1..])
+      schema
+    end
+
+    def _apply_range_constraints(schema, constraints)
+      constraints.each do |c|
+        next unless c.is_a?(Range)
+
+        schema[:minimum] = c.begin if c.begin
+        if c.end
+          schema[c.exclude_end? ? :exclusiveMaximum : :maximum] = c.end
+        end
+      end
+    end
+
+    def _class_schema(type) # rubocop:disable Metrics/MethodLength
+      case type.name
+      when "String" then { type: "string" }
+      when "Integer" then { type: "integer" }
+      when "Float" then { type: "number" }
+      when "TrueClass", "FalseClass" then { type: "boolean" }
+      when "Symbol" then { type: "string" }
+      when "Hash" then { type: "object" }
+      when "Date" then { type: "string", format: "date" }
+      when "Time" then { type: "string", format: "date-time" }
+      when "DateTime" then { type: "string", format: "date-time" }
+      when "BigDecimal" then { type: "string", pattern: BIGDECIMAL_PATTERN }
+      else {}
+      end
+    end
+
+    private_class_method :_type_to_schema, :_union_string, :_constraint_string,
+      :_union_schema, :_constraint_schema, :_apply_range_constraints, :_class_schema
+  end
+end

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/dexkit.rb

@@ -14,12 +14,16 @@ require_relative "dex/concern"
 require_relative "dex/ref_type"
 require_relative "dex/type_coercion"
 require_relative "dex/props_setup"
+require_relative "dex/context_setup"
 require_relative "dex/error"
 require_relative "dex/settings"
 require_relative "dex/pipeline"
 require_relative "dex/executable"
+require_relative "dex/registry"
+require_relative "dex/type_serializer"
 require_relative "dex/operation"
 require_relative "dex/event"
+require_relative "dex/tool"
 require_relative "dex/form"
 require_relative "dex/query"
 
@@ -71,5 +75,22 @@ module Dex
     def transaction_adapter=(adapter)
       configuration.transaction_adapter = adapter
     end
+
+    CONTEXT_KEY = :_dex_context
+    EMPTY_CONTEXT = {}.freeze
+
+    def context
+      Fiber[CONTEXT_KEY] || EMPTY_CONTEXT
+    end
+
+    def with_context(**values)
+      previous = Fiber[CONTEXT_KEY]
+      Fiber[CONTEXT_KEY] = (previous || {}).merge(values)
+      yield
+    ensure
+      Fiber[CONTEXT_KEY] = previous
+    end
   end
 end
+
+require_relative "dex/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -166,10 +166,12 @@ files:
 - guides/llm/OPERATION.md
 - guides/llm/QUERY.md
 - lib/dex/concern.rb
+- lib/dex/context_setup.rb
 - lib/dex/error.rb
 - lib/dex/event.rb
 - lib/dex/event/bus.rb
 - lib/dex/event/execution_state.rb
+- lib/dex/event/export.rb
 - lib/dex/event/handler.rb
 - lib/dex/event/metadata.rb
 - lib/dex/event/processor.rb
@@ -186,8 +188,12 @@ files:
 - lib/dex/operation/async_proxy.rb
 - lib/dex/operation/async_wrapper.rb
 - lib/dex/operation/callback_wrapper.rb
+- lib/dex/operation/explain.rb
+- lib/dex/operation/export.rb
+- lib/dex/operation/guard_wrapper.rb
 - lib/dex/operation/jobs.rb
 - lib/dex/operation/lock_wrapper.rb
+- lib/dex/operation/once_wrapper.rb
 - lib/dex/operation/outcome.rb
 - lib/dex/operation/record_backend.rb
 - lib/dex/operation/record_wrapper.rb
@@ -202,14 +208,18 @@ files:
 - lib/dex/query/backend.rb
 - lib/dex/query/filtering.rb
 - lib/dex/query/sorting.rb
+- lib/dex/railtie.rb
 - lib/dex/ref_type.rb
+- lib/dex/registry.rb
 - lib/dex/settings.rb
 - lib/dex/test_helpers.rb
 - lib/dex/test_helpers/assertions.rb
 - lib/dex/test_helpers/execution.rb
 - lib/dex/test_helpers/stubbing.rb
 - lib/dex/test_log.rb
+- lib/dex/tool.rb
 - lib/dex/type_coercion.rb
+- lib/dex/type_serializer.rb
 - lib/dex/version.rb
 - lib/dexkit.rb
 homepage: https://dex.razorjack.net/