lcp 0.1.0

data/lib/lcp_ruby/background_jobs/setup.rb

@@ -0,0 +1,145 @@
+module LcpRuby
+  module BackgroundJobs
+    module Setup
+      def self.apply!(loader)
+        Declarative::Registry.register_built_ins!
+
+        sources = []
+
+        # Static source always loads if job files exist
+        if loader.job_definitions.any?
+          sources << StaticSource.new(loader.job_definitions)
+        end
+
+        # Additional source based on configuration
+        config_source = LcpRuby.configuration.job_source
+        case config_source
+        when :model
+          model_src = setup_model!(loader)
+          sources << model_src if model_src
+        when :host
+          host_src = setup_host!
+          sources << host_src if host_src
+        end
+
+        return if sources.empty?
+
+        # Validate job execution model contract
+        validate_execution_model!(loader)
+
+        resolver = Resolver.new(sources)
+        Registry.set_resolver(resolver)
+        Registry.mark_available!
+
+        # Install event triggers
+        Triggers::TriggerInstaller.install!(resolver) if defined?(Triggers::TriggerInstaller)
+
+        # Sync schedules
+        sync_schedules!(resolver)
+      end
+
+      class << self
+        private
+
+        def setup_model!(loader)
+          config = LcpRuby.configuration
+          model_name = config.job_definition_model
+
+          model_def = loader.model_definitions[model_name]
+          unless model_def
+            message = "job_source is :model but job definition model '#{model_name}' is not defined. " \
+                      "Run: rails generate lcp_ruby:background_jobs"
+
+            if LcpRuby.generator_context?
+              log_warn(message)
+              return nil
+            end
+
+            raise MetadataError, message
+          end
+
+          # Install change handler and save-time validation
+          model_class = LcpRuby.registry.model_for(model_name)
+          ChangeHandler.install!(model_class)
+          install_env_var_validation!(model_class)
+
+          ModelSource.new
+        end
+
+        def setup_host!
+          adapter = LcpRuby.configuration.job_provider
+
+          unless adapter
+            message = "job_source is :host but no job_provider is configured"
+            if LcpRuby.generator_context?
+              log_warn(message)
+              return nil
+            end
+            raise MetadataError, message
+          end
+
+          %i[job_definitions job_definition_by_name].each do |method|
+            unless adapter.respond_to?(method)
+              raise MetadataError, "job_provider must respond to ##{method}"
+            end
+          end
+
+          HostSource.new(adapter)
+        end
+
+        def validate_execution_model!(loader)
+          config = LcpRuby.configuration
+          model_name = config.job_execution_model
+
+          model_def = loader.model_definitions[model_name]
+          unless model_def
+            message = "Background jobs enabled but job execution model '#{model_name}' is not defined. " \
+                      "Run: rails generate lcp_ruby:background_jobs"
+
+            if LcpRuby.generator_context?
+              log_warn(message)
+              return
+            end
+
+            raise MetadataError, message
+          end
+
+          result = ContractValidator.validate(model_def)
+          unless result.valid?
+            raise MetadataError, "JobExecution model '#{model_name}' does not satisfy the contract:\n" \
+                                 "#{result.errors.map { |e| "  - #{e}" }.join("\n")}"
+          end
+
+          result.warnings.each { |warning| log_warn(warning) }
+        end
+
+        def install_env_var_validation!(model_class)
+          fields = LcpRuby.configuration.job_definition_model_fields
+          config_field = fields[:handler_config]&.to_s || fields["handler_config"]&.to_s || "handler_config"
+
+          model_class.validate do |record|
+            value = record.respond_to?(config_field) ? record.send(config_field) : nil
+            raw = value.is_a?(String) ? value : value.to_json rescue "{}"
+            if raw.include?("${env:")
+              record.errors.add(config_field,
+                "cannot use ${env:} interpolation in DB-sourced definitions. " \
+                "Use literal values or configure a secrets API.")
+            end
+          end
+        end
+
+        def sync_schedules!(resolver)
+          adapter = LcpRuby.configuration.schedule_adapter
+          return unless adapter
+
+          scheduled = resolver.job_definitions.values.select(&:scheduled?)
+          adapter.sync_schedules!(scheduled) if scheduled.any?
+        end
+
+        def log_warn(message)
+          Rails.logger.warn("[LcpRuby::BackgroundJobs] #{message}") if defined?(Rails) && Rails.respond_to?(:logger)
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/static_source.rb

@@ -0,0 +1,19 @@
+module LcpRuby
+  module BackgroundJobs
+    class StaticSource
+      include Contract
+
+      def initialize(definitions)
+        @definitions = definitions || {}
+      end
+
+      def job_definitions
+        @definitions
+      end
+
+      def job_definition_by_name(name)
+        @definitions[name.to_s]
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/steps_executor.rb

@@ -0,0 +1,52 @@
+module LcpRuby
+  module BackgroundJobs
+    class StepsExecutor < BaseHandler
+      def perform
+        total = definition.steps.size
+        on_error = definition.on_step_error
+
+        definition.steps.each_with_index do |step_config, index|
+          check_cancellation!
+
+          step_num = index + 1
+          action_name = step_config["action"]
+          log!("Step #{step_num}/#{total}: #{action_name}", level: :info)
+
+          action_class = Declarative::Registry.action_for(action_name)
+          unless action_class
+            message = "Declarative action '#{action_name}' not found (step #{step_num})"
+            if on_error == "continue"
+              log!(message, level: :error)
+              next
+            else
+              raise HandlerClassNotFoundError, message
+            end
+          end
+
+          step_definition = build_step_definition(step_config)
+          action = action_class.new(execution, step_definition)
+
+          begin
+            action.perform
+          rescue => e
+            log!("Step #{step_num}/#{total} failed: #{e.message}", level: :error)
+            raise unless on_error == "continue"
+          end
+
+          progress = (step_num * 100) / total
+          update_progress!(progress)
+        end
+      end
+
+      private
+
+      def build_step_definition(step_config)
+        Definition.new(
+          name: "#{definition.name}_step",
+          handler_type: "declarative",
+          handler_config: step_config
+        )
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/triggers/event_trigger.rb

@@ -0,0 +1,97 @@
+module LcpRuby
+  module BackgroundJobs
+    module Triggers
+      class EventTrigger
+        attr_reader :definition, :trigger_config
+
+        def initialize(definition, trigger_config)
+          @definition = definition
+          @trigger_config = trigger_config
+        end
+
+        def install!
+          event_name = trigger_config["event"]
+          model = trigger_config["model"]
+
+          handler_class = build_handler_class
+
+          if model
+            Events::HandlerRegistry.register(model, event_name, handler_class)
+          else
+            Events::HandlerRegistry.register("*", event_name, handler_class)
+          end
+        end
+
+        private
+
+        def build_handler_class
+          trigger = self
+
+          Class.new(Events::HandlerBase) do
+            define_method(:call) do
+              trigger.handle_event(context)
+            end
+          end
+        end
+
+        public
+
+        def handle_event(context)
+          record = context[:record]
+          conditions = trigger_config["conditions"]
+
+          if conditions && record
+            unless ConditionEvaluator.evaluate(conditions, record)
+              return
+            end
+          end
+
+          enqueue_params = build_params(context)
+          target_model = record ? infer_model_name(record) : nil
+          target_id = record&.id
+
+          BackgroundJobs.enqueue(
+            job_type: definition.name,
+            params: enqueue_params,
+            target_model: target_model,
+            target_id: target_id,
+            triggered_by: context[:current_user]
+          )
+        end
+
+        private
+
+        def build_params(context)
+          merged = {}
+
+          # 1. Job definition params (static defaults)
+          merged.merge!(definition.params) if definition.params.is_a?(Hash)
+
+          # 2. Event context
+          merged["event_name"] = context[:event_name].to_s if context[:event_name]
+          merged["changes"] = context[:changes] if context[:changes].is_a?(Hash) && context[:changes].any?
+
+          # 3. Trigger-level params
+          trigger_params = trigger_config["params"]
+          merged.merge!(trigger_params) if trigger_params.is_a?(Hash)
+
+          # 4. Pull specific fields from record
+          params_from_record = trigger_config["params_from_record"]
+          if params_from_record.is_a?(Array) && context[:record]
+            record = context[:record]
+            params_from_record.each do |field|
+              merged[field.to_s] = record.send(field) if record.respond_to?(field)
+            end
+          end
+
+          merged
+        end
+
+        def infer_model_name(record)
+          class_name = record.class.name
+          class_name.demodulize.underscore
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/triggers/trigger_installer.rb

@@ -0,0 +1,20 @@
+module LcpRuby
+  module BackgroundJobs
+    module Triggers
+      class TriggerInstaller
+        def self.install!(resolver)
+          resolver.job_definitions.each_value do |definition|
+            next unless definition.triggers.any?
+
+            definition.triggers.each do |trigger_config|
+              case trigger_config["type"]
+              when "event"
+                EventTrigger.new(definition, trigger_config).install!
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/background_jobs/unique_key_builder.rb

@@ -0,0 +1,31 @@
+require "digest"
+
+module LcpRuby
+  module BackgroundJobs
+    class UniqueKeyBuilder
+      def self.build(unique_by, attrs)
+        return nil unless unique_by.is_a?(Array) && unique_by.any?
+
+        pairs = unique_by.sort.map do |key|
+          value = resolve_value(key, attrs)
+          "#{key}=#{value.nil? ? 'nil' : value}"
+        end
+
+        Digest::SHA256.hexdigest(pairs.join("|"))
+      end
+
+      def self.resolve_value(key, attrs)
+        parts = key.to_s.split(".", 2)
+        if parts.length == 2
+          parent = attrs[parts[0]] || attrs[parts[0].to_sym]
+          if parent.is_a?(Hash)
+            parent[parts[1]] || parent[parts[1].to_sym]
+          end
+        else
+          attrs[key] || attrs[key.to_sym]
+        end
+      end
+      private_class_method :resolve_value
+    end
+  end
+end

data/lib/lcp_ruby/batch_actions/base_service.rb

@@ -0,0 +1,70 @@
+module LcpRuby
+  module BatchActions
+    class BaseService
+      attr_reader :records, :evaluator, :model_definition, :current_user, :progress, :batch_operation
+
+      def initialize(records:, evaluator:, model_definition:, current_user:, batch_operation: nil, &progress)
+        @records = records
+        @evaluator = evaluator
+        @model_definition = model_definition
+        @current_user = current_user
+        @batch_operation = batch_operation
+        @progress = progress
+      end
+
+      def call
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+
+      private
+
+      def each_record(&block)
+        if records.respond_to?(:find_each)
+          records.find_each.with_index(&block)
+        else
+          records.each_with_index(&block)
+        end
+      end
+
+      def log_item(record, action_taken, error_details: nil, record_changes: nil)
+        return unless @batch_operation
+
+        item_model = LcpRuby.registry.model_for("batch_operation_item")
+        item_model.create!(
+          batch_operation_id: @batch_operation.id,
+          record_type: record.class.name,
+          record_id: record.id,
+          action_taken: action_taken,
+          error_details: error_details,
+          record_changes: record_changes
+        )
+      end
+
+      def finalize_batch_operation(success_count, skipped_count, error_count)
+        return unless @batch_operation
+
+        total = success_count + skipped_count + error_count
+        @batch_operation.update!(
+          status: "completed",
+          total_count: total,
+          success_count: success_count,
+          skipped_count: skipped_count,
+          error_count: error_count
+        )
+      end
+
+      def build_message(primary_key, primary_count, denied_count)
+        message = I18n.t("lcp_ruby.batch.result.#{primary_key}",
+          count: primary_count,
+          model: model_definition.label.to_s.pluralize(primary_count),
+          default: "%{count} #{primary_key}.")
+        if denied_count > 0
+          message += " " + I18n.t("lcp_ruby.batch.result.denied",
+            count: denied_count,
+            default: "%{count} skipped (insufficient permissions).")
+        end
+        message
+      end
+    end
+  end
+end

data/lib/lcp_ruby/batch_actions/batch_action_handler.rb

@@ -0,0 +1,200 @@
+module LcpRuby
+  module BatchActions
+    def self.register_background_job!
+      return if @background_job_registered
+      return unless BackgroundJobs::Registry.available?
+      return if BackgroundJobs::Registry.definition_by_name("batch_action")
+
+      definition = BackgroundJobs::Definition.new(
+        name: "batch_action",
+        handler_type: "class",
+        handler_class: "LcpRuby::BatchActions::BatchActionHandler",
+        queue: "default",
+        retry_count: 0,
+        retry_interval: "fixed:0",
+        timeout: 0
+      )
+      BackgroundJobs::Registry.register_definition!(definition)
+      @background_job_registered = true
+    end
+
+    class BatchActionHandler < BackgroundJobs::BaseHandler
+      def perform
+        @action_name = params["action_name"]
+        @model_name = params["model_name"]
+        @user = load_user
+        @evaluator = build_evaluator
+        @model_def = resolve_model_definition
+        @records = resolve_records
+        @batch_op = load_batch_operation
+
+        log!("Starting batch #{@action_name} on #{@model_name}")
+        total = @records.count
+        log!("Record count: #{total}")
+
+        result = if built_in_action?(@action_name)
+          execute_built_in(total)
+        else
+          execute_custom
+        end
+
+        log!(result.message)
+        broadcast_model_change(@model_name)
+      end
+
+      private
+
+      def load_user
+        user_id = params["triggered_by_id"]
+        raise BackgroundJobs::JobError, "triggered_by_id is required for batch action jobs" unless user_id
+
+        user_class = LcpRuby.configuration.user_class.constantize
+        user = user_class.find_by(id: user_id)
+        raise BackgroundJobs::JobError, "User ##{user_id} not found" unless user
+
+        LcpRuby::Current.user = user
+        user
+      end
+
+      def build_evaluator
+        perm_def = LcpRuby.loader.permission_definition(@model_name)
+        Authorization::PermissionEvaluator.new(perm_def, @user, @model_name)
+      end
+
+      def resolve_model_definition
+        definition = LcpRuby.loader.model_definitions[@model_name]
+        raise BackgroundJobs::JobError, "Model definition '#{@model_name}' not found" unless definition
+
+        definition
+      end
+
+      def resolve_records
+        model_class = LcpRuby.registry.model_for(@model_name)
+        scope = apply_policy_scope(model_class)
+        scope = apply_soft_delete_scope(scope)
+
+        if params["selection_mode"] == "filter"
+          apply_filter_scope(scope, model_class)
+        else
+          ids = params["ids"] || []
+          scope.where(id: ids)
+        end
+      end
+
+      def apply_policy_scope(model_class)
+        policy_class = Authorization::PolicyFactory.policy_for(@model_name)
+        policy_class::Scope.new(@user, model_class).resolve
+      end
+
+      def apply_soft_delete_scope(scope)
+        return scope unless @model_def&.soft_delete?
+
+        presenter_scope = params["presenter_scope"]
+        case presenter_scope
+        when "discarded" then scope.discarded
+        when "with_discarded" then scope.with_discarded
+        else scope.kept
+        end
+      end
+
+      def apply_filter_scope(scope, model_class)
+        filter_params = params["filter_params"] || {}
+
+        # Apply Ransack filters
+        if filter_params["f"].present?
+          sanitized = Search::ParamSanitizer.sanitize(filter_params["f"])
+          ransack_params = Search::FilterParamBuilder.build(sanitized)
+          scope = scope.ransack(ransack_params).result
+        end
+
+        # Apply predefined filter scope
+        if filter_params["filter"].present?
+          scope_name = filter_params["filter"].to_sym
+          scope = scope.send(scope_name) if scope.respond_to?(scope_name)
+        end
+
+        # Apply quick search
+        if filter_params["qs"].present?
+          presenter_def = find_presenter_definition
+          searchable = presenter_def&.search_config&.dig("searchable_fields")
+          scope = Search::QuickSearch.apply(
+            scope, filter_params["qs"], model_class, @model_def,
+            searchable_field_names: searchable
+          )
+        end
+
+        # Apply custom field filters
+        if filter_params["cf"].present?
+          scope = Search::CustomFieldFilter.apply(scope, filter_params["cf"], @model_name)
+        end
+
+        scope
+      end
+
+      def find_presenter_definition
+        LcpRuby.loader.presenter_definitions.values.find do |p|
+          p.model == @model_name
+        end
+      end
+
+      def load_batch_operation
+        op_id = params["batch_operation_id"]
+        return nil unless op_id
+
+        batch_op_model = LcpRuby.registry.model_for("batch_operation")
+        batch_op_model.find_by(id: op_id)
+      rescue LcpRuby::Error
+        Rails.logger.warn("[LcpRuby] batch_operation model not registered, skipping batch operation log")
+        nil
+      end
+
+      def built_in_action?(name)
+        BUILT_IN_ACTIONS.include?(name.to_s)
+      end
+
+      def execute_built_in(total)
+        service_class = case @action_name.to_s
+        when "destroy" then DestroyService
+        when "restore" then RestoreService
+        when "permanently_destroy" then PermanentlyDestroyService
+        else
+          raise BackgroundJobs::JobError, "Unknown built-in batch action: #{@action_name}"
+        end
+
+        service_class.new(
+          records: @records,
+          evaluator: @evaluator,
+          model_definition: @model_def,
+          current_user: @user,
+          batch_operation: @batch_op
+        ) { |index|
+          update_progress!((index * 100.0 / [ total, 1 ].max).to_i)
+          check_cancellation!
+        }.call
+      end
+
+      def execute_custom
+        action_key = "#{@model_name}/#{@action_name}"
+        total = @records.count
+        CustomActionDispatcher.new(
+          action_key: action_key, records: @records,
+          current_user: @user, params: {},
+          model_class: LcpRuby.registry.model_for(@model_name),
+          model_definition: @model_def, batch_operation: @batch_op
+        ) { |index|
+          update_progress!((index * 100.0 / [ total, 1 ].max).to_i)
+          check_cancellation!
+        }.call
+      end
+
+      def broadcast_model_change(model_name)
+        return unless defined?(Turbo::StreamsChannel) && defined?(ActionCable)
+
+        Turbo::StreamsChannel.broadcast_refresh_to("lcp_model_#{model_name}")
+      rescue StandardError => e
+        raise unless Rails.env.production?
+        LcpRuby.record_error(e, subsystem: "broadcast", model: model_name.to_s, operation: "batch_action_refresh")
+      end
+    end
+  end
+end