dexkit 0.7.0 → 0.8.0

data/lib/dex/operation/export.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Dex
+  class Operation
+    module Export
+      module_function
+
+      def build_hash(source, contract) # rubocop:disable Metrics/MethodLength
+        h = {}
+        h[:name] = source.name if source&.name
+        desc = source&.description
+        h[:description] = desc if desc
+        h[:params] = _serialize_params(source, contract.params)
+        h[:success] = TypeSerializer.to_string(contract.success) if contract.success
+        h[:errors] = contract.errors unless contract.errors.empty?
+        h[:guards] = contract.guards unless contract.guards.empty?
+        ctx = _serialize_context(source)
+        h[:context] = ctx unless ctx.empty?
+        h[:pipeline] = source.pipeline.steps.map(&:name) if source
+        h[:settings] = _serialize_settings(source) if source
+        h
+      end
+
+      def build_json_schema(source, contract, section: :params) # rubocop:disable Metrics/MethodLength
+        case section
+        when :params then _params_schema(source, contract)
+        when :success then _success_schema(source, contract)
+        when :errors then _errors_schema(source, contract)
+        when :full then _full_schema(source, contract)
+        else
+          raise ArgumentError,
+            "unknown section: #{section.inspect}. Known: :params, :success, :errors, :full"
+        end
+      end
+
+      def _serialize_params(source, params)
+        descs = source&.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        params.each_with_object({}) do |(name, type), hash|
+          entry = { type: TypeSerializer.to_string(type), required: _required?(source, name) }
+          entry[:desc] = descs[name] if descs[name]
+          hash[name] = entry
+        end
+      end
+
+      def _required?(source, prop_name)
+        return true unless source&.respond_to?(:literal_properties)
+
+        prop = source.literal_properties.find { |p| p.name == prop_name }
+        return true unless prop
+
+        prop.required?
+      end
+
+      def _serialize_context(source)
+        source&.respond_to?(:context_mappings) ? source.context_mappings.presence || {} : {}
+      end
+
+      def _serialize_settings(source) # rubocop:disable Metrics/MethodLength
+        settings = {}
+
+        record_s = source.settings_for(:record)
+        settings[:record] = {
+          enabled: record_s.fetch(:enabled, true),
+          params: record_s.fetch(:params, true),
+          result: record_s.fetch(:result, true)
+        }
+
+        tx_s = source.settings_for(:transaction)
+        settings[:transaction] = { enabled: tx_s.fetch(:enabled, true) }
+
+        once_s = source.settings_for(:once)
+        settings[:once] = { defined: once_s.fetch(:defined, false) }
+
+        settings
+      end
+
+      def _params_schema(source, contract) # rubocop:disable Metrics/MethodLength
+        descs = source&.respond_to?(:prop_descriptions) ? source.prop_descriptions : {}
+        properties = {}
+        required = []
+
+        contract.params.each do |name, type|
+          prop_desc = descs[name]
+          schema = TypeSerializer.to_json_schema(type, desc: prop_desc)
+          properties[name.to_s] = schema
+          required << name.to_s if _required?(source, name)
+        end
+
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }
+        result[:title] = source.name if source&.name
+        desc = source&.description
+        result[:description] = desc if desc
+        result[:properties] = properties unless properties.empty?
+        result[:required] = required unless required.empty?
+        result[:additionalProperties] = false
+        result
+      end
+
+      def _success_schema(source, contract)
+        return {} unless contract.success
+
+        schema = TypeSerializer.to_json_schema(contract.success)
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = "#{source&.name} success" if source&.name
+        result.merge(schema)
+      end
+
+      def _errors_schema(source, contract)
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = "#{source&.name} errors" if source&.name
+        result[:type] = "object"
+
+        properties = {}
+        contract.errors.each do |code|
+          properties[code.to_s] = {
+            type: "object",
+            properties: {
+              code: { const: code.to_s },
+              message: { type: "string" },
+              details: { type: "object" }
+            }
+          }
+        end
+        result[:properties] = properties unless properties.empty?
+        result
+      end
+
+      def _full_schema(source, contract)
+        result = { "$schema": "https://json-schema.org/draft/2020-12/schema" }
+        result[:title] = source.name if source&.name
+        result[:description] = "Operation contract"
+        result[:properties] = {
+          params: _params_schema(source, contract).except(:$schema),
+          success: _success_schema(source, contract).except(:$schema),
+          errors: _errors_schema(source, contract).except(:$schema)
+        }
+        result
+      end
+
+      private_class_method :_serialize_params, :_required?, :_serialize_context, :_serialize_settings,
+        :_params_schema, :_success_schema, :_errors_schema, :_full_schema
+    end
+  end
+end

data/lib/dex/operation/guard_wrapper.rb

@@ -107,16 +107,17 @@ module Dex
 
     private
 
-    def _guard_evaluate
+    def _guard_evaluate_all
       guards = self.class._guard_list
       return [] if guards.empty?
 
       blocked_names = Set.new
-      failures = []
+      results = []
 
       guards.each do |guard|
         if guard.requires.any? { |dep| blocked_names.include?(dep) }
           blocked_names << guard.name
+          results << { name: guard.name, passed: false, skipped: true }
           next
         end
 
@@ -128,11 +129,21 @@ module Dex
 
         if threat
           blocked_names << guard.name
-          failures << { guard: guard.name, message: guard.message || guard.name.to_s }
+          results << { name: guard.name, passed: false, message: guard.message || guard.name.to_s }
+        else
+          results << { name: guard.name, passed: true }
         end
       end
 
-      failures
+      results
+    end
+
+    def _guard_evaluate
+      _guard_evaluate_all.filter_map do |r|
+        next if r[:passed] || r[:skipped]
+
+        { guard: r[:name], message: r[:message] }
+      end
     end
   end
 end

data/lib/dex/operation/record_backend.rb

@@ -42,6 +42,10 @@ module Dex
           raise NotImplementedError
         end
 
+        def find_pending_once_key(key)
+          raise NotImplementedError
+        end
+
         def update_record_by_once_key(key, **attributes)
           raise NotImplementedError
         end
@@ -80,6 +84,10 @@ module Dex
             .first
         end
 
+        def find_pending_once_key(key)
+          record_class.where(once_key: key, status: %w[pending running]).first
+        end
+
         def update_record_by_once_key(key, **attributes)
           record = record_class.where(once_key: key, status: %w[completed error]).first
           record&.update!(safe_attributes(attributes))
@@ -119,6 +127,10 @@ module Dex
           ).first
         end
 
+        def find_pending_once_key(key)
+          record_class.where(:once_key => key, :status.in => %w[pending running]).first
+        end
+
         def update_record_by_once_key(key, **attributes)
           record = record_class.where(:once_key => key, :status.in => %w[completed error]).first
           record&.update!(safe_attributes(attributes))

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/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/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