lcp 0.1.0

data/lib/lcp_ruby/workflow/resolver.rb

@@ -0,0 +1,32 @@
+module LcpRuby
+  module Workflow
+    # Merges workflow definitions from all active sources.
+    # Priority: static > model > host (first match wins per model).
+    class Resolver
+      include Contract
+
+      def initialize(sources)
+        @sources = sources
+      end
+
+      def workflows_for(model_name)
+        all = @sources.flat_map { |source| source.workflows_for(model_name) }
+        # Deduplicate by name, preserving source priority order
+        seen = {}
+        all.each_with_object([]) do |wf, result|
+          next if seen.key?(wf.name)
+          seen[wf.name] = true
+          result << wf
+        end
+      end
+
+      def workflow_by_name(name)
+        @sources.each do |source|
+          wf = source.workflow_by_name(name)
+          return wf if wf
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/setup.rb

@@ -0,0 +1,135 @@
+module LcpRuby
+  module Workflow
+    module Setup
+      # Boot-time setup for the workflow subsystem.
+      # Called after models are built and groups/auditing are set up.
+      #
+      # @param loader [LcpRuby::Metadata::Loader] the metadata loader instance
+      def self.apply!(loader)
+        sources = []
+
+        # Static source always loads if workflow files exist
+        if loader.workflow_definitions.any?
+          sources << StaticSource.new(loader.workflow_definitions)
+        end
+
+        # Additional source based on configuration
+        config_source = LcpRuby.configuration.workflow_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?
+
+        resolver = Resolver.new(sources)
+        Registry.set_loader(resolver)
+        Registry.mark_available!
+
+        # Set up audit log if any workflow has audit_log: true
+        setup_audit_log!(loader)
+
+        # Set up approval engine if any workflow has approvals
+        Approval::Setup.apply!(loader)
+      end
+
+      class << self
+        private
+
+        def setup_model!(loader)
+          config = LcpRuby.configuration
+          model_name = config.workflow_model
+
+          model_def = loader.model_definitions[model_name]
+          unless model_def
+            message = "workflow_source is :model but workflow model '#{model_name}' is not defined. " \
+                      "Define it in your models YAML."
+
+            if LcpRuby.generator_context?
+              log_warn(message)
+              return nil
+            end
+
+            raise MetadataError, message
+          end
+
+          result = ContractValidator.validate(model_def)
+          unless result.valid?
+            raise MetadataError, "Workflow model '#{model_name}' does not satisfy the contract:\n" \
+                                 "#{result.errors.map { |e| "  - #{e}" }.join("\n")}"
+          end
+
+          log_warnings(result)
+
+          # Install change handler
+          model_class = LcpRuby.registry.model_for(model_name)
+          ChangeHandler.install!(model_class)
+
+          ModelSource.new
+        end
+
+        def setup_host!
+          adapter = LcpRuby.configuration.workflow_provider
+
+          unless adapter
+            message = "workflow_source is :host but no workflow_provider is configured"
+            if LcpRuby.generator_context?
+              log_warn(message)
+              return nil
+            end
+            raise MetadataError, message
+          end
+
+          %i[workflows_for workflow_by_name].each do |method|
+            unless adapter.respond_to?(method)
+              raise MetadataError, "workflow_provider must respond to ##{method}"
+            end
+          end
+
+          HostSource.new(adapter)
+        end
+
+        def setup_audit_log!(loader)
+          any_audit = loader.workflow_definitions.values.any?(&:audit_log)
+          return unless any_audit
+
+          audit_model_name = LcpRuby.configuration.workflow_audit_model
+
+          model_def = loader.model_definitions[audit_model_name]
+          unless model_def
+            message = "Workflow has audit_log: true but audit model '#{audit_model_name}' is not defined. " \
+                      "Run: rails generate lcp_ruby:workflow_audit_log"
+
+            if LcpRuby.generator_context?
+              log_warn(message)
+              return
+            end
+
+            raise MetadataError, message
+          end
+
+          result = AuditContractValidator.validate(model_def)
+          unless result.valid?
+            raise MetadataError, "Workflow audit model '#{audit_model_name}' does not satisfy the contract:\n" \
+                                 "#{result.errors.map { |e| "  - #{e}" }.join("\n")}"
+          end
+
+          log_warnings(result)
+          AuditRegistry.mark_available!
+        end
+
+        def log_warnings(result)
+          result.warnings.each { |warning| log_warn(warning) }
+        end
+
+        def log_warn(message)
+          Rails.logger.warn("[LcpRuby::Workflow] #{message}") if defined?(Rails) && Rails.respond_to?(:logger)
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/state_definition.rb

@@ -0,0 +1,59 @@
+module LcpRuby
+  module Workflow
+    class StateDefinition
+      attr_reader :name, :category, :color, :icon, :readonly_fields,
+                  :on_entry, :on_exit, :description,
+                  :source_loc, :description_source_loc
+
+      def initialize(attrs = {})
+        @name = attrs[:name].to_s
+        @initial = attrs[:initial] == true
+        @category = attrs[:category]&.to_s
+        @color = attrs[:color]&.to_s
+        @icon = attrs[:icon]&.to_s
+        @all_readonly = (attrs[:readonly_fields].to_s == "all")
+        @readonly_fields = @all_readonly ? [] : Array(attrs[:readonly_fields]).map(&:to_s)
+        @on_entry = Array(attrs[:on_entry]).map(&:to_s)
+        @on_exit = Array(attrs[:on_exit]).map(&:to_s)
+        @description = attrs[:description]&.to_s
+        # i18n_check Phase 3a — captured by WorkflowBuilder#state from
+        # the DSL block. nil for YAML-loaded workflows (Pass 3 covers).
+        @source_loc = attrs[:source_loc]
+        @description_source_loc = attrs[:description_source_loc]
+      end
+
+      def self.from_hash(name, hash)
+        hash = (hash || {}).transform_keys(&:to_s)
+        new(
+          name: name,
+          initial: hash["initial"],
+          category: hash["category"],
+          color: hash["color"],
+          icon: hash["icon"],
+          readonly_fields: hash["readonly_fields"],
+          on_entry: hash["on_entry"],
+          on_exit: hash["on_exit"],
+          description: hash["description"],
+          source_loc: hash["_source_loc"],
+          description_source_loc: hash["_description_source_loc"]
+        )
+      end
+
+      def initial?
+        @initial == true
+      end
+
+      def terminal?
+        @category == "terminal"
+      end
+
+      def all_readonly?
+        @all_readonly == true
+      end
+
+      def readonly_field?(field_name)
+        @all_readonly || @readonly_fields.include?(field_name.to_s)
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/state_machine.rb

@@ -0,0 +1,78 @@
+module LcpRuby
+  module Workflow
+    class StateMachine
+      attr_reader :workflow_definition
+
+      def initialize(workflow_definition)
+        @workflow_definition = workflow_definition
+      end
+
+      # Returns transitions available for the given record, filtered by state, roles, and guard.
+      def available_transitions(record, user:, evaluator:)
+        current_state = record.send(@workflow_definition.field)&.to_s
+        return [] unless current_state
+
+        @workflow_definition.transitions_from(current_state).select do |transition|
+          transition_allowed?(transition, record, user: user, evaluator: evaluator)
+        end
+      end
+
+      def can_transition?(record, transition_name, user:, evaluator:)
+        transition = @workflow_definition.transition(transition_name)
+        return false unless transition
+
+        current_state = record.send(@workflow_definition.field)&.to_s
+        return false unless transition.available_from?(current_state)
+
+        transition_allowed?(transition, record, user: user, evaluator: evaluator)
+      end
+
+      def validate_transition!(record, transition_name, user:, evaluator:)
+        transition = @workflow_definition.transition(transition_name)
+        unless transition
+          raise TransitionDeniedError,
+            "Transition '#{transition_name}' is not defined in workflow '#{@workflow_definition.name}'"
+        end
+
+        current_state = record.send(@workflow_definition.field)&.to_s
+        unless transition.available_from?(current_state)
+          raise TransitionDeniedError,
+            "Transition '#{transition_name}' is not available from state '#{current_state}'"
+        end
+
+        unless role_allowed?(transition, evaluator)
+          raise TransitionDeniedError,
+            "Transition '#{transition_name}' is not permitted for the current user's role"
+        end
+
+        unless guard_passes?(transition, record, user: user)
+          raise TransitionDeniedError,
+            "Transition '#{transition_name}' guard condition is not satisfied"
+        end
+      end
+
+      private
+
+      def transition_allowed?(transition, record, user:, evaluator:)
+        role_allowed?(transition, evaluator) &&
+          guard_passes?(transition, record, user: user)
+      end
+
+      def role_allowed?(transition, evaluator)
+        return true if transition.roles.empty?
+
+        user_roles = evaluator.roles.map(&:to_s)
+        (transition.roles & user_roles).any?
+      end
+
+      def guard_passes?(transition, record, user:)
+        return true unless transition.guard
+
+        context = { current_user: user }
+        ConditionEvaluator.evaluate_any(record, transition.guard, context: context)
+      rescue ConditionError
+        false
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/static_source.rb

@@ -0,0 +1,20 @@
+module LcpRuby
+  module Workflow
+    class StaticSource
+      include Contract
+
+      def initialize(workflow_definitions)
+        @definitions = workflow_definitions || {}
+        @by_model = @definitions.values.group_by(&:model)
+      end
+
+      def workflows_for(model_name)
+        @by_model[model_name.to_s] || []
+      end
+
+      def workflow_by_name(name)
+        @definitions[name.to_s]
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/transition_action_builder.rb

@@ -0,0 +1,46 @@
+module LcpRuby
+  module Workflow
+    class TransitionActionBuilder
+      # Builds action hashes for transitions available on a record.
+      # Used by ActionSet to inject transition buttons on show/index pages.
+      #
+      # @param record [Object] the current record
+      # @param workflow_definition [WorkflowDefinition]
+      # @param user [Object] current user
+      # @param evaluator [Authorization::PermissionEvaluator]
+      # @param presenter_overrides [Hash] transition name => override hash (pre-built by ActionSet)
+      # @return [Array<Hash>] action hashes for rendering
+      def self.build_actions(record, workflow_definition:, user:, evaluator:, presenter_overrides: {}, state_machine: nil)
+        machine = state_machine || StateMachine.new(workflow_definition)
+        available = machine.available_transitions(record, user: user, evaluator: evaluator)
+
+        available.filter_map do |transition|
+          next if transition.system_only?
+
+          override = presenter_overrides[transition.name]
+          next if override && override["visible"] == false
+
+          label = resolve_label(workflow_definition, transition)
+
+          action = {
+            "name" => transition.name,
+            "type" => "transition",
+            "label" => label,
+            "icon" => override&.dig("icon") || transition.icon,
+            "style" => override&.dig("style") || transition.style,
+            "confirm" => transition.confirm,
+            "confirm_message" => transition.confirm_message,
+            "require_comment" => transition.require_comment
+          }.compact
+
+          action
+        end
+      end
+
+      def self.resolve_label(workflow_definition, transition)
+        TransitionLabelResolver.resolve(workflow_definition.name, transition)
+      end
+      private_class_method :resolve_label
+    end
+  end
+end

data/lib/lcp_ruby/workflow/transition_definition.rb

@@ -0,0 +1,70 @@
+module LcpRuby
+  module Workflow
+    class TransitionDefinition
+      attr_reader :name, :from, :to, :label, :icon, :style, :roles,
+                  :guard, :set_fields, :events, :confirm, :confirm_message,
+                  :trigger, :require_comment,
+                  :source_loc, :label_source_loc
+
+      def initialize(attrs = {})
+        @name = attrs[:name].to_s
+        @from = Array(attrs[:from]).map(&:to_s)
+        @to = attrs[:to].to_s
+        @label = attrs[:label]&.to_s
+        @icon = attrs[:icon]&.to_s
+        @style = attrs[:style]&.to_s
+        @roles = Array(attrs[:roles]).map(&:to_s)
+        @guard = attrs[:guard]
+        @set_fields = attrs[:set_fields] || {}
+        @events = Array(attrs[:events]).map(&:to_s)
+        @require_comment = attrs[:require_comment] == true
+        @confirm = attrs[:confirm]
+        @confirm_message = attrs[:confirm_message]&.to_s
+        @trigger = (attrs[:trigger] || "user").to_s
+        # i18n_check Phase 3a — populated by WorkflowBuilder#transition.
+        # `source_loc` points at the transition declaration; `label_source_loc`
+        # at the same line (label is captured from the same `transition(...)` call).
+        @source_loc = attrs[:source_loc]
+        @label_source_loc = attrs[:label_source_loc]
+      end
+
+      def self.from_hash(name, hash)
+        hash = (hash || {}).transform_keys(&:to_s)
+        new(
+          name: name,
+          from: hash["from"],
+          to: hash["to"],
+          label: hash["label"],
+          icon: hash["icon"],
+          style: hash["style"],
+          roles: hash["roles"],
+          guard: hash["guard"],
+          set_fields: hash["set_fields"],
+          events: hash["events"],
+          require_comment: hash["require_comment"],
+          confirm: hash["confirm"],
+          confirm_message: hash["confirm_message"],
+          trigger: hash["trigger"],
+          source_loc: hash["_source_loc"],
+          label_source_loc: hash["_label_source_loc"]
+        )
+      end
+
+      def user_triggered?
+        @trigger == "user" || @trigger == "both"
+      end
+
+      def system_only?
+        @trigger == "system"
+      end
+
+      def programmatic?
+        @trigger == "system" || @trigger == "both"
+      end
+
+      def available_from?(state)
+        @from.include?(state.to_s)
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/transition_executor.rb

@@ -0,0 +1,140 @@
+module LcpRuby
+  module Workflow
+    class TransitionExecutor
+      TRANSITION_ACTIVE_IVAR = :@_workflow_transition_active
+
+      def self.set_transition_active(record, value = true)
+        record.instance_variable_set(TRANSITION_ACTIVE_IVAR, value)
+      end
+
+      def self.reset_transition_flag(record)
+        record.instance_variable_set(TRANSITION_ACTIVE_IVAR, false)
+      end
+
+      # Executes a workflow transition on a record.
+      #
+      # @return [TransitionResult]
+      def self.execute(record, transition_name, user:, evaluator:, comment: nil, triggered_by: nil, defer_events: false)
+        workflow_def = resolve_workflow(record)
+        machine = StateMachine.new(workflow_def)
+
+        # 1. Early validation (fast-fail before locking)
+        machine.validate_transition!(record, transition_name, user: user, evaluator: evaluator)
+
+        transition = workflow_def.transition(transition_name)
+
+        # 2. Check require_comment (static check, doesn't need lock)
+        if transition.require_comment && (comment.nil? || comment.to_s.strip.empty?)
+          raise CommentRequiredError,
+            "Transition '#{transition_name}' requires a comment"
+        end
+
+        to_state = transition.to
+        from_state = nil
+        deferred = []
+
+        # Wrap entire execution in Current.set so Current.user is available
+        # for all downstream code (events, audit, userstamps) including system triggers.
+        LcpRuby::Current.set(user: user) do
+          # 3. Wrap in transaction with row lock
+          record.class.transaction do
+            # 3a. Acquire row lock and reload fresh data
+            record.lock!
+
+            from_state = record.send(workflow_def.field).to_s
+
+            # 3b. Re-validate after lock (state may have changed concurrently)
+            machine.validate_transition!(record, transition_name, user: user, evaluator: evaluator)
+
+            # 3c. Resolve and apply set_fields (after lock, with fresh record data)
+            transition.set_fields.each do |field_name, expression|
+              value = ValueResolver.resolve(expression, record: record, user: user)
+              if record.respond_to?("#{field_name}=")
+                record.send("#{field_name}=", value)
+              end
+            end
+
+            # 4. Assign workflow field
+            record.send("#{workflow_def.field}=", to_state)
+
+            # 5. Set flag to bypass before_save guard
+            set_transition_active(record)
+
+            # 6. Save
+            record.save!
+
+            # 7. Audit log
+            if AuditRegistry.available? && workflow_def.audit_log
+              AuditWriter.log(
+                record: record,
+                workflow_definition: workflow_def,
+                transition: transition,
+                from_state: from_state,
+                to_state: to_state,
+                user: user,
+                comment: comment,
+                metadata: { triggered_by: triggered_by }
+              )
+            end
+          end
+
+          # 8. Fire events or collect them for deferred dispatch
+          if defer_events
+            deferred = collect_events(workflow_def, record, transition, from_state, to_state)
+          else
+            dispatch_events(workflow_def, record, transition, from_state, to_state)
+            deferred = []
+          end
+        end
+
+        ActiveSupport::Notifications.instrument("workflow_transition.lcp_ruby", {
+          model: record.class.name.demodulize.underscore,
+          from_state: from_state,
+          to_state: to_state
+        })
+
+        TransitionResult.new(
+          success: true,
+          transition_name: transition_name,
+          from_state: from_state,
+          to_state: to_state,
+          record: record,
+          deferred_events: deferred
+        )
+      ensure
+        reset_transition_flag(record) if record
+      end
+
+      def self.resolve_workflow(record)
+        model_name = record.class.name.demodulize.underscore
+        return Registry.workflow_for_model(model_name) if Registry.available?
+
+        raise WorkflowError.new(:"lcp_ruby.workflow.errors.registry_unavailable")
+      end
+      private_class_method :resolve_workflow
+
+      def self.collect_events(workflow_def, record, transition, from_state, to_state)
+        changes = { workflow_def.field => [ from_state, to_state ] }
+
+        event_names = []
+        old_state_def = workflow_def.state(from_state)
+        event_names.concat(old_state_def.on_exit) if old_state_def
+        new_state_def = workflow_def.state(to_state)
+        event_names.concat(new_state_def.on_entry) if new_state_def
+        event_names.concat(transition.events)
+
+        event_names.map do |event_name|
+          { event_name: event_name, record: record, changes: changes }
+        end
+      end
+      private_class_method :collect_events
+
+      def self.dispatch_events(workflow_def, record, transition, from_state, to_state)
+        collect_events(workflow_def, record, transition, from_state, to_state).each do |event|
+          Events::Dispatcher.dispatch(**event)
+        end
+      end
+      private_class_method :dispatch_events
+    end
+  end
+end

data/lib/lcp_ruby/workflow/transition_label_resolver.rb

@@ -0,0 +1,21 @@
+module LcpRuby
+  module Workflow
+    # Resolves a human-readable label for a workflow transition.
+    #
+    # Lookup order:
+    #   1. i18n key `lcp_ruby.workflows.<workflow>.transitions.<transition>`
+    #   2. transition.label (from workflow YAML/DSL), if a Transition object is given
+    #   3. transition_name.humanize
+    #
+    # Used by both the toolbar action builder (button label) and the controller
+    # success flash so a single override flows through both surfaces.
+    class TransitionLabelResolver
+      def self.resolve(workflow_name, transition)
+        transition_name = transition.respond_to?(:name) ? transition.name : transition.to_s
+        yaml_label = transition.respond_to?(:label) ? transition.label : nil
+        i18n_key = "lcp_ruby.workflows.#{workflow_name}.transitions.#{transition_name}"
+        I18n.t(i18n_key, default: yaml_label || transition_name.to_s.humanize)
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/transition_result.rb

@@ -0,0 +1,20 @@
+module LcpRuby
+  module Workflow
+    class TransitionResult
+      attr_reader :transition_name, :from_state, :to_state, :record, :deferred_events
+
+      def initialize(success:, transition_name:, from_state:, to_state:, record:, deferred_events: [])
+        @success = success
+        @transition_name = transition_name
+        @from_state = from_state
+        @to_state = to_state
+        @record = record
+        @deferred_events = deferred_events
+      end
+
+      def success?
+        @success == true
+      end
+    end
+  end
+end

data/lib/lcp_ruby/workflow/value_resolver.rb

@@ -0,0 +1,58 @@
+module LcpRuby
+  module Workflow
+    class ValueResolver
+      # Resolves a set_fields value expression to a concrete value.
+      #
+      # Supported shapes:
+      #   "current_user.id" / "record.title" / "current_date" / "current_datetime"
+      #     → routed through DynamicReferences::Resolver
+      #   { "value" => "literal" }   → string literal
+      #   { "value" => "null" }      → nil
+      #   { "value" => 42 }          → 42
+      #   :now / :today (symbol)     → migrated to "current_datetime" / "current_date"
+      #   anything else (string, number, true/false, nil) → itself
+      #
+      # Legacy hash forms ({date:}, {current_user:}, {field_ref:}) are no longer
+      # accepted — callers should use the dotted-string form.
+      def self.resolve(expression, record:, user:)
+        if expression.is_a?(Symbol) && %i[now today].include?(expression)
+          raise WorkflowError,
+            "set_fields: bare symbol :#{expression} is no longer supported. " \
+            "Use 'current_datetime' (for :now) or 'current_date' (for :today)."
+        end
+
+        if expression.is_a?(String) && DynamicReferences::Resolver.recognized?(expression)
+          return DynamicReferences::Resolver.resolve(
+            expression,
+            context: { user: user, record: record }
+          )
+        end
+
+        return expression unless expression.is_a?(Hash)
+
+        normalized = expression.transform_keys(&:to_s)
+
+        if normalized.key?("value")
+          resolve_literal(normalized["value"])
+        elsif normalized.key?("date") || normalized.key?("current_user") || normalized.key?("field_ref")
+          raise WorkflowError,
+            "set_fields: hash-form dynamic references ({date:}, {current_user:}, {field_ref:}) " \
+            "are no longer supported. Use the dotted string form — " \
+            "e.g. 'current_datetime', 'current_user.id', 'record.<field>'. Got: #{expression.inspect}"
+        else
+          expression
+        end
+      end
+
+      def self.resolve_literal(raw)
+        case raw.to_s
+        when "null", "nil"
+          nil
+        else
+          raw
+        end
+      end
+      private_class_method :resolve_literal
+    end
+  end
+end