tasker-engine 1.0.0

data/app/models/tasker/task_diagram.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'pathname'
+
+module Tasker
+  class TaskDiagram
+    # Colors for different step statuses
+    STATUS_COLORS = {
+      Tasker::Constants::WorkflowStepStatuses::PENDING => 'lightblue',
+      Tasker::Constants::WorkflowStepStatuses::IN_PROGRESS => 'lightgreen',
+      Tasker::Constants::WorkflowStepStatuses::COMPLETE => 'green',
+      Tasker::Constants::WorkflowStepStatuses::ERROR => 'red',
+      Tasker::Constants::WorkflowStepStatuses::CANCELLED => 'gray'
+    }.freeze
+
+    # Create a new task diagram
+    #
+    # @param task [Tasker::Task] The task to create a diagram for
+    # @param base_url [String, nil] Optional base URL for REST endpoints
+    # @return [TaskDiagram] A new task diagram instance
+    def initialize(task, base_url = nil)
+      @task = task
+      @base_url = base_url
+    end
+
+    # Generate a Mermaid diagram string for the task
+    #
+    # @return [String] Mermaid flowchart diagram string
+    delegate :to_mermaid, to: :flowchart
+
+    # Generate a complete HTML document with embedded Mermaid diagram
+    #
+    # @return [String] HTML document with Mermaid diagram
+    def to_html
+      # Generate the mermaid diagram
+      @diagram = flowchart.to_mermaid
+
+      # Create binding with relevant variables
+      task = @task # Make task available to the template
+      diagram = @diagram # Make diagram available to the template
+
+      # Create a binding with the variables
+      b = binding
+
+      # Get the template path relative to this file
+      template_path = views_path.join('_diagram.html.erb')
+
+      # Load and render the template with ERB
+      begin
+        template = File.read(template_path)
+        ERB.new(template).result(b)
+      rescue Errno::ENOENT
+        raise TaskDiagramError, "Template file not found: #{template_path}"
+      rescue Errno::EACCES
+        raise TaskDiagramError, "Permission denied while accessing template file: #{template_path}"
+      end
+    end
+
+    def to_json(pretty: false)
+      flowchart.to_json(pretty: pretty)
+    end
+
+    private
+
+    def flowchart
+      return @flowchart if @flowchart
+
+      # Preload workflow steps with scenic view relationships for efficiency
+      workflow_steps = @task.workflow_steps.includes(:named_step, :step_dag_relationship)
+
+      # Create a new flowchart
+      @flowchart = Tasker::Diagram::Flowchart.new(
+        direction: 'TD',
+        title: "Task #{@task.task_id}: #{@task.name}"
+      )
+
+      # Add task info node
+      @flowchart.add_node(build_task_node)
+
+      # Build nodes for all workflow steps
+      workflow_steps.each do |step|
+        @flowchart.add_node(build_step_node(step))
+      end
+
+      # Build all edges efficiently using scenic view data
+      build_all_step_edges(workflow_steps).each do |edge|
+        @flowchart.add_edge(edge)
+      end
+
+      @flowchart
+    end
+
+    # Get the path to the view templates directory
+    #
+    # @return [Pathname] Path to view templates
+    def views_path
+      # Get the absolute path of the current file
+      current_file = Pathname.new(__FILE__)
+
+      # Navigate to the views directory relative to this file
+      # This file is in app/models/tasker/task_diagram.rb
+      # Views are in app/views/tasker/task/
+      current_file.dirname.parent.parent.parent.join('app', 'views', 'tasker', 'task')
+    end
+
+    # Build the task information node
+    #
+    # @return [Tasker::Diagram::Node] The task node
+    def build_task_node
+      Tasker::Diagram::Node.new(
+        id: "task_#{@task.task_id}",
+        label: "Task: #{@task.name}\nID: #{@task.task_id}\nStatus: #{@task.status}"
+      )
+    end
+
+    # Build a node for a workflow step
+    #
+    # @param step [Tasker::WorkflowStep] The workflow step
+    # @return [Tasker::Diagram::Node] The step node
+    def build_step_node(step)
+      node_id = "step_#{step.workflow_step_id}"
+      color = STATUS_COLORS[step.status] || 'lightgray'
+
+      # Create label with step details
+      label = build_step_label(step)
+
+      # Create clickable URL if base_url is provided
+      url = @base_url ? "#{@base_url}/tasks/#{@task.task_id}/workflow_steps/#{step.workflow_step_id}" : nil
+
+      # Create node with styling
+      Tasker::Diagram::Node.new(
+        id: node_id,
+        label: label.join("\n"),
+        shape: 'box',
+        style: "fill:#{color};",
+        url: url
+      )
+    end
+
+    # Build the label lines for a step node
+    #
+    # @param step [Tasker::WorkflowStep] The workflow step
+    # @return [Array<String>] Array of label lines
+    def build_step_label(step)
+      label = [
+        "Step: #{step.name}",
+        "Status: #{step.status}",
+        "Attempts: #{step.attempts || 0}"
+      ]
+
+      # Add error info if applicable
+      if step.status == Tasker::Constants::WorkflowStepStatuses::ERROR && step.results&.key?('error')
+        error_msg = step.results['error'].to_s
+        # Truncate long error messages
+        error_msg = "#{error_msg[0..27]}..." if error_msg.length > 30
+        label << "Error: #{error_msg}"
+      end
+
+      label
+    end
+
+    # Build an edge between two nodes
+    #
+    # @param source_id [String] The source node ID
+    # @param target_id [String] The target node ID
+    # @param label [String] The edge label
+    # @return [Tasker::Diagram::Edge] The edge
+    def build_edge(source_id, target_id, label = '')
+      Tasker::Diagram::Edge.new(
+        source_id: source_id,
+        target_id: target_id,
+        label: label
+      )
+    end
+
+    # Build all edges efficiently using scenic view data - eliminates N+1 queries
+    #
+    # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps for the task
+    # @return [Array<Tasker::Diagram::Edge>] All edges for the diagram
+    def build_all_step_edges(workflow_steps)
+      edges = []
+
+      # Add edges from task to root steps using dedicated builder
+      edges.concat(TaskToRootStepEdgeBuilder.build(@task, workflow_steps))
+
+      # Add edges between steps using dedicated builder
+      edges.concat(StepToStepEdgeBuilder.build(workflow_steps))
+
+      edges
+    end
+
+    # Service class to build edges from task to root steps
+    # Reduces complexity by organizing edge building logic
+    class TaskToRootStepEdgeBuilder
+      class << self
+        # Build edges from task node to root steps
+        #
+        # @param task [Tasker::Task] The task
+        # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps
+        # @return [Array<Tasker::Diagram::Edge>] Task to root step edges
+        def build(task, workflow_steps)
+          edges = []
+
+          workflow_steps.each do |step|
+            next unless step.step_dag_relationship&.is_root_step
+
+            edges << build_edge(
+              "task_#{task.task_id}",
+              "step_#{step.workflow_step_id}"
+            )
+          end
+
+          edges
+        end
+
+        private
+
+        # Build an edge between two nodes
+        #
+        # @param source_id [String] The source node ID
+        # @param target_id [String] The target node ID
+        # @param label [String] The edge label
+        # @return [Tasker::Diagram::Edge] The edge
+        def build_edge(source_id, target_id, label = '')
+          Tasker::Diagram::Edge.new(
+            source_id: source_id,
+            target_id: target_id,
+            label: label
+          )
+        end
+      end
+    end
+
+    # Service class to build edges between workflow steps
+    # Reduces complexity by organizing edge building logic
+    class StepToStepEdgeBuilder
+      class << self
+        # Build edges between workflow steps
+        #
+        # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps
+        # @return [Array<Tasker::Diagram::Edge>] Step to step edges
+        def build(workflow_steps)
+          edge_data = collect_edge_data(workflow_steps)
+          return [] if edge_data.empty?
+
+          edge_records = batch_load_edge_records(edge_data)
+          build_edges_from_data(edge_data, edge_records)
+        end
+
+        private
+
+        # Collect all edge relationships for efficient batch lookup
+        #
+        # @param workflow_steps [Array<Tasker::WorkflowStep>] All workflow steps
+        # @return [Array<Hash>] Edge data with from_step_id and to_step_id
+        def collect_edge_data(workflow_steps)
+          edge_data = []
+
+          workflow_steps.each do |step|
+            next unless step.step_dag_relationship
+
+            child_ids = step.step_dag_relationship.child_step_ids_array
+            child_ids.each do |child_id|
+              edge_data << {
+                from_step_id: step.workflow_step_id,
+                to_step_id: child_id
+              }
+            end
+          end
+
+          edge_data
+        end
+
+        # Batch load all WorkflowStepEdge records for edge labels
+        #
+        # @param edge_data [Array<Hash>] Edge data to load records for
+        # @return [Hash] Hash mapping edge keys to edge records
+        def batch_load_edge_records(edge_data)
+          edge_records = {}
+
+          conditions = edge_data.map do |data|
+            "(from_step_id = #{data[:from_step_id]} AND to_step_id = #{data[:to_step_id]})"
+          end
+
+          Tasker::WorkflowStepEdge.where(conditions.join(' OR ')).find_each do |edge_record|
+            key = "#{edge_record.from_step_id}_#{edge_record.to_step_id}"
+            edge_records[key] = edge_record
+          end
+
+          edge_records
+        end
+
+        # Build edges using pre-calculated data and records
+        #
+        # @param edge_data [Array<Hash>] Edge data with IDs
+        # @param edge_records [Hash] Loaded edge records for labels
+        # @return [Array<Tasker::Diagram::Edge>] Built edges
+        def build_edges_from_data(edge_data, edge_records)
+          edges = []
+
+          edge_data.each do |data|
+            source_id = "step_#{data[:from_step_id]}"
+            target_id = "step_#{data[:to_step_id]}"
+
+            # Find edge label from batch-loaded records
+            key = "#{data[:from_step_id]}_#{data[:to_step_id]}"
+            edge_label = edge_records[key]&.name || ''
+
+            edges << build_edge(source_id, target_id, edge_label)
+          end
+
+          edges
+        end
+
+        # Build an edge between two nodes
+        #
+        # @param source_id [String] The source node ID
+        # @param target_id [String] The target node ID
+        # @param label [String] The edge label
+        # @return [Tasker::Diagram::Edge] The edge
+        def build_edge(source_id, target_id, label = '')
+          Tasker::Diagram::Edge.new(
+            source_id: source_id,
+            target_id: target_id,
+            label: label
+          )
+        end
+      end
+    end
+  end
+end

data/app/models/tasker/task_execution_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tasker
+  # TaskExecutionContext now uses SQL functions for high-performance queries
+  # This class explicitly delegates to the function-based implementation for better maintainability
+  class TaskExecutionContext
+    # Explicit delegation of class methods to function-based implementation
+    def self.find(task_id)
+      Tasker::Functions::FunctionBasedTaskExecutionContext.find(task_id)
+    end
+
+    def self.for_tasks(task_ids)
+      Tasker::Functions::FunctionBasedTaskExecutionContext.for_tasks(task_ids)
+    end
+
+    # For backward compatibility, maintain the active method but point to function-based implementation
+    def self.active
+      Tasker::Functions::FunctionBasedTaskExecutionContext
+    end
+
+    def initialize(task_id)
+      @task_id = task_id
+    end
+
+    def workflow_summary
+      @workflow_summary ||= Tasker::Functions::FunctionBasedTaskExecutionContext.find(@task_id).workflow_summary
+    end
+  end
+end

data/app/models/tasker/task_namespace.rb

@@ -0,0 +1,41 @@
+# typed: false
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: tasker_task_namespaces
+#
+#  name                :string(64)       not null
+#  description         :string(255)
+#  created_at          :datetime         not null
+#  updated_at          :datetime         not null
+#  task_namespace_id   :integer          not null, primary key
+#
+# Indexes
+#
+#  task_namespaces_name_index   (name)
+#  task_namespaces_name_unique  (name) UNIQUE
+#
+module Tasker
+  class TaskNamespace < ApplicationRecord
+    self.primary_key = :task_namespace_id
+
+    has_many :named_tasks, dependent: :nullify
+
+    validates :name, presence: true, uniqueness: true, length: { maximum: 64 }
+    validates :description, length: { maximum: 255 }
+
+    # Find or create default namespace - always works even if not seeded
+    def self.default
+      find_or_create_by!(name: 'default')
+    end
+
+    # Scope for non-default namespaces
+    scope :custom, -> { where.not(name: 'default') }
+
+    # Check if this is the default namespace
+    def default?
+      name == 'default'
+    end
+  end
+end

data/app/models/tasker/task_transition.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Tasker
+  # TaskTransition represents state transitions for Task entities using Statesman
+  #
+  # This model stores the audit trail of all task state changes, providing
+  # a complete history of task lifecycle events with metadata and timestamps.
+  class TaskTransition < ApplicationRecord
+    # NOTE: We don't include Statesman::Adapters::ActiveRecordTransition
+    # because we're using PostgreSQL JSONB column for metadata
+
+    # Associations
+    belongs_to :task, inverse_of: :task_transitions
+
+    # Validations
+    validates :to_state, inclusion: {
+      in: %w[pending in_progress complete error cancelled resolved_manually],
+      message: 'is not a valid task state'
+    }
+
+    # Validate that the task exists before creating transition
+    validate :task_must_exist
+
+    validates :sort_key, presence: true, uniqueness: { scope: :task_id }
+    # Custom validation for metadata that allows empty hash but not nil
+    validate :metadata_must_be_hash
+
+    # Ensure metadata is always a hash
+    after_initialize :ensure_metadata_hash
+    # Ensure metadata defaults to empty hash if not provided
+    before_validation :ensure_metadata_presence
+
+    # Scopes
+    scope :recent, -> { order(sort_key: :desc) }
+    scope :to_state, ->(state) { where(to_state: state) }
+    scope :with_metadata_key, ->(key) { where('metadata ? :key', key: key.to_s) }
+
+    # Class methods for querying transitions
+    class << self
+      # Find the most recent transition to a specific state
+      #
+      # @param state [String, Symbol] The state to find the most recent transition to
+      # @return [TaskTransition, nil] The most recent transition to the given state
+      def most_recent_to_state(state)
+        to_state(state.to_s).order(sort_key: :desc).first
+      end
+
+      # Find all transitions that occurred within a time range
+      #
+      # @param start_time [Time] The start of the time range
+      # @param end_time [Time] The end of the time range
+      # @return [ActiveRecord::Relation] Transitions within the time range
+      def in_time_range(start_time, end_time)
+        where(created_at: start_time..end_time)
+      end
+
+      # Find transitions with specific metadata values
+      #
+      # @param key [String, Symbol] The metadata key to search for
+      # @param value [Object] The value to match
+      # @return [ActiveRecord::Relation] Transitions with matching metadata
+      def with_metadata_value(key, value)
+        where('metadata->:key = :value', key: key.to_s, value: value.to_json.delete('"'))
+      end
+
+      # Get transition statistics for analytics
+      #
+      # @return [Hash] Statistics about transitions
+      def statistics
+        {
+          total_transitions: count,
+          states: group(:to_state).count,
+          recent_activity: where(created_at: 24.hours.ago..Time.current).count,
+          average_time_between_transitions: average_time_between_transitions
+        }
+      end
+
+      private
+
+      # Calculate average time between transitions
+      #
+      # @return [Float, nil] Average seconds between transitions
+      def average_time_between_transitions
+        transitions = order(:created_at).pluck(:created_at)
+        return nil if transitions.size < 2
+
+        total_time = 0
+        (1...transitions.size).each do |i|
+          total_time += (transitions[i] - transitions[i - 1])
+        end
+
+        total_time / (transitions.size - 1)
+      end
+    end
+
+    # Instance methods
+
+    # Get the duration since the previous transition
+    #
+    # @return [Float, nil] Duration in seconds since previous transition
+    def duration_since_previous
+      previous_transition = self.class.where(task_id: task_id)
+                                .where(sort_key: ...sort_key)
+                                .order(sort_key: :desc)
+                                .first
+
+      return nil unless previous_transition
+
+      created_at - previous_transition.created_at
+    end
+
+    # Check if this transition represents an error state
+    #
+    # @return [Boolean] True if transitioning to an error state
+    def error_transition?
+      to_state == 'error'
+    end
+
+    # Check if this transition represents completion
+    #
+    # @return [Boolean] True if transitioning to a completion state
+    def completion_transition?
+      %w[complete resolved_manually].include?(to_state)
+    end
+
+    # Check if this transition represents cancellation
+    #
+    # @return [Boolean] True if transitioning to cancelled state
+    def cancellation_transition?
+      to_state == 'cancelled'
+    end
+
+    # Get human-readable description of the transition
+    #
+    # @return [String] Description of what this transition represents
+    def description
+      case to_state
+      when 'pending'
+        'Task initialized and ready for processing'
+      when 'in_progress'
+        'Task execution started'
+      when 'complete'
+        'Task completed successfully'
+      when 'error'
+        'Task encountered an error'
+      when 'cancelled'
+        'Task was cancelled'
+      when 'resolved_manually'
+        'Task was manually resolved'
+      else
+        "Task transitioned to #{to_state}"
+      end
+    end
+
+    # Get formatted metadata for display
+    #
+    # @return [Hash] Formatted metadata with additional computed fields
+    def formatted_metadata
+      base_metadata = metadata.dup
+
+      # Add computed fields
+      base_metadata['duration_since_previous'] = duration_since_previous
+      base_metadata['transition_description'] = description
+      base_metadata['transition_timestamp'] = created_at.iso8601
+
+      base_metadata
+    end
+
+    # Check if transition has specific metadata
+    #
+    # @param key [String, Symbol] The metadata key to check for
+    # @return [Boolean] True if the metadata contains the key
+    def has_metadata?(key)
+      metadata.key?(key.to_s)
+    end
+
+    # Get metadata value with default
+    #
+    # @param key [String, Symbol] The metadata key
+    # @param default [Object] Default value if key not found
+    # @return [Object] The metadata value or default
+    def get_metadata(key, default = nil)
+      metadata.fetch(key.to_s, default)
+    end
+
+    # Set metadata value
+    #
+    # @param key [String, Symbol] The metadata key
+    # @param value [Object] The value to set
+    # @return [Object] The set value
+    def set_metadata(key, value)
+      self.metadata = metadata.merge(key.to_s => value)
+      value
+    end
+
+    private
+
+    # Ensure metadata is always initialized as a hash
+    #
+    # @return [void]
+    def ensure_metadata_hash
+      self.metadata ||= {}
+    end
+
+    # Ensure metadata is present for validation
+    #
+    # @return [void]
+    def ensure_metadata_presence
+      self.metadata = {} if metadata.blank?
+    end
+
+    # Custom validation for metadata
+    #
+    # @return [void]
+    def metadata_must_be_hash
+      if metadata.nil?
+        self.metadata = {}
+      elsif !metadata.is_a?(Hash)
+        errors.add(:metadata, 'must be a hash')
+      end
+    end
+
+    # Validate that the task exists
+    #
+    # @return [void]
+    def task_must_exist
+      return if task_id.blank?
+
+      errors.add(:task, 'must exist before creating transition') unless Tasker::Task.exists?(task_id: task_id)
+    rescue ActiveRecord::StatementInvalid => e
+      # Handle cases where the table might not exist (e.g., during migrations)
+      Rails.logger.warn { "Could not validate task existence: #{e.message}" }
+    end
+  end
+end