tasker-engine 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fde3286281cb8207b0ff8b4fd869af97c99694ce5cff7e81769bf43bee86cf3a
-  data.tar.gz: 3e89558b96d0888936ee09b4e3459c408bd16e76582a2b5e0d2195af26048498
+  metadata.gz: dd2231fa336087118193cb1ed54b98838f396210d88b44ff2eb994ebc12cc12f
+  data.tar.gz: 1e0f9172ccac70c3d712cdb038779158eb1edcd9e81e9402a3888a0ba12cb85c
 SHA512:
-  metadata.gz: 1a28755986bc08a1e9957e6ab5bbc8722c814351658181af811a8e72d5f0cfd13a0035e4b2eb7d68658695af1fef84375cf3f3380e86d9c483df32b77a121ec7
-  data.tar.gz: c63989cc7763b9218479ac73c01a7aab3cc7c61002dfd205efe4e0f516a8b2ee56811b3b7c717e28df1b83dd724fa74bc720b0fc08b061e9c1ce429356d83651
+  metadata.gz: 4cf9d080d61f3954b1d06749ee71f1a7508bd10272ca7be10476cfe45880d45048ea986fc5a510233ae9f92f549ba160f0ae93cf16a5e92fd3bcd4282deb69fa
+  data.tar.gz: c810d613f87f099bfb948f306fb7fc57e568427a7eb453acf2a0a602d270e31bd0f9e8e438e134f5d60e11ea3e63a7b00dc994ec76f664fa331a061453b0b4dc

data/README.md

@@ -28,7 +28,9 @@ Perfect for processes that involve multiple interdependent steps, require automa
 Add Tasker to your Rails app's `Gemfile`:
 
 ```ruby
-gem 'tasker-engine', '~> 0.1.0'
+source 'https://rubygems.pkg.github.com/tasker-systems' do
+  gem 'tasker-engine', '~> 1.0.0'
+end
 ```
 
 Install and run the migrations:
@@ -52,7 +54,7 @@ end
 bundle exec rails tasker:setup
 ```
 
-### Option 2: Generate Complete Application
+### Option 2: Generate Complete Application (v2.6.1)
 
 Create a production-ready Rails application with Tasker integration in one command:
 
@@ -123,7 +125,7 @@ This creates a complete workflow structure:
 ---
 name: order_process
 namespace_name: default
-version: 0.1.0
+version: 1.0.0
 task_handler_class: OrderProcess
 
 step_templates:
@@ -169,7 +171,7 @@ end
 task_request = Tasker::Types::TaskRequest.new(
   name: 'order_process',
   namespace: 'default',        # Optional - defaults to 'default'
-  version: '0.1.0',           # Optional - defaults to '0.1.0'
+  version: '1.0.0',           # Optional - defaults to '0.1.0'
   context: { order_id: 12345 }
 )
 
@@ -177,7 +179,7 @@ task_request = Tasker::Types::TaskRequest.new(
 handler = Tasker::HandlerFactory.instance.get(
   'order_process',
   namespace_name: 'default',   # Optional - defaults to 'default'
-  version: '0.1.0'            # Optional - defaults to '0.1.0'
+  version: '1.0.0'            # Optional - defaults to '0.1.0'
 )
 task = handler.initialize_task!(task_request)
 
@@ -192,7 +194,7 @@ Tasker includes enterprise-grade security that works with any Rails authenticati
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.auth do |auth|
     auth.authentication_enabled = true
     auth.authenticator_class = 'YourAuthenticator'
@@ -288,11 +290,11 @@ Built-in OpenTelemetry integration provides complete observability:
 
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.telemetry do |tel|
     tel.enabled = true
     tel.service_name = 'my-app-workflows'
-    tel.service_version = '0.1.0'
+    tel.service_version = '1.0.0'
   end
 end
 ```
@@ -347,7 +349,7 @@ GET /tasker/health/status
 **Optional Authentication & Authorization**:
 ```ruby
 # config/initializers/tasker.rb
-Tasker::Configuration.configuration do |config|
+Tasker.configuration do |config|
   config.health do |health|
     health.status_requires_authentication = true  # Secure detailed status
   end
@@ -404,6 +406,7 @@ end
 ### 📚 Additional Resources
 - **[Application Generator](docs/APPLICATION_GENERATOR.md)** - One-line app creation with Docker support and validation
 - **[System Overview](docs/OVERVIEW.md)** - Architecture and configuration
+- **[Task Diagrams](docs/TASK_DIAGRAM.md)** - Visual workflow representation
 - **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
 
 ## Requirements & Dependencies

data/app/controllers/tasker/analytics_controller.rb

@@ -158,7 +158,7 @@ module Tasker
     #
     # @return [Boolean] True if authentication should be skipped
     def skip_authentication?
-      !Tasker::Configuration.configuration.telemetry.metrics_auth_required
+      !Tasker.configuration.telemetry.metrics_auth_required
     end
 
     # Override authorization check for analytics endpoint
@@ -166,7 +166,7 @@ module Tasker
     #
     # @return [Boolean] True if authorization should be skipped
     def skip_authorization?
-      !Tasker::Configuration.configuration.telemetry.metrics_auth_required
+      !Tasker.configuration.telemetry.metrics_auth_required
     end
 
     # Set appropriate cache control headers for analytics endpoints

data/app/controllers/tasker/graphql_controller.rb

@@ -68,7 +68,7 @@ module Tasker
     # Authorization methods for GraphQL operations
 
     def authorization_enabled?
-      Tasker::Configuration.configuration.auth.authorization_enabled
+      Tasker.configuration.auth.authorization_enabled
     end
 
     def authorize_graphql_operations!(query_string, operation_name)
@@ -173,10 +173,10 @@ module Tasker
     end
 
     def build_authorization_coordinator
-      coordinator_class = Tasker::Configuration.configuration.auth.authorization_coordinator_class.constantize
+      coordinator_class = Tasker.configuration.auth.authorization_coordinator_class.constantize
       coordinator_class.new(current_tasker_user)
     rescue NameError => e
-      coordinator_class_name = Tasker::Configuration.configuration.auth.authorization_coordinator_class
+      coordinator_class_name = Tasker.configuration.auth.authorization_coordinator_class
       raise Tasker::Authorization::ConfigurationError,
             "Authorization coordinator class '#{coordinator_class_name}' not found: #{e.message}"
     end

data/app/controllers/tasker/health_controller.rb

@@ -213,7 +213,7 @@ module Tasker
     def skip_authentication?
       case action_name
       when 'status'
-        !Tasker::Configuration.configuration.health.status_requires_authentication
+        !Tasker.configuration.health.status_requires_authentication
       else
         super
       end

data/app/controllers/tasker/metrics_controller.rb

@@ -62,7 +62,7 @@ module Tasker
     #
     # @return [Boolean] True if authentication should be skipped
     def skip_authentication?
-      !Tasker::Configuration.configuration.telemetry.metrics_auth_required
+      !Tasker.configuration.telemetry.metrics_auth_required
     end
 
     # Override authorization check for metrics endpoint
@@ -70,7 +70,7 @@ module Tasker
     #
     # @return [Boolean] True if authorization should be skipped
     def skip_authorization?
-      !Tasker::Configuration.configuration.telemetry.metrics_auth_required
+      !Tasker.configuration.telemetry.metrics_auth_required
     end
 
     # Export metrics using PrometheusExporter
@@ -87,7 +87,7 @@ module Tasker
     #
     # @return [Boolean] True if metrics are enabled
     def metrics_enabled?
-      Tasker::Configuration.configuration.telemetry.metrics_enabled
+      Tasker.configuration.telemetry.metrics_enabled
     end
 
     # Response when metrics are disabled

data/app/controllers/tasker/task_diagrams_controller.rb

@@ -0,0 +1,30 @@
+# typed: false
+# frozen_string_literal: true
+
+require_dependency 'tasker/application_controller'
+
+module Tasker
+  class TaskDiagramsController < ApplicationController
+    include ActionController::MimeResponds
+
+    before_action :set_full_task, only: %i[index]
+
+    # GET /tasks/1/task_diagrams
+    def index
+      respond_to do |format|
+        format.html { render(html: @task.diagram(request.base_url).to_html.html_safe) }
+        format.json { render(json: @task.diagram(request.base_url).to_json, status: :ok) }
+      end
+    end
+
+    private
+
+    def set_full_task
+      @task = query_base.find(params[:task_id])
+    end
+
+    def query_base
+      Tasker::Task.with_all_associated
+    end
+  end
+end

data/app/jobs/tasker/metrics_export_job.rb

@@ -134,7 +134,7 @@ module Tasker
     # @return [Integer] Timeout duration in seconds
     def job_timeout_duration
       prometheus_config = begin
-        Tasker::Configuration.configuration.telemetry.prometheus
+        Tasker.configuration.telemetry.prometheus
       rescue StandardError
         {}
       end

data/app/models/tasker/application_record.rb

@@ -9,12 +9,12 @@ module Tasker
   # When secondary database is enabled, it connects to a database named 'tasker' in database.yml.
   #
   # @example Basic usage with shared database (default)
-  #   Tasker::Configuration.configuration do |config|
+  #   Tasker.configuration do |config|
   #     config.database.enable_secondary_database = false
   #   end
   #
   # @example Using a dedicated Tasker database
-  #   Tasker::Configuration.configuration do |config|
+  #   Tasker.configuration do |config|
   #     config.database.enable_secondary_database = true
   #     config.database.name = :tasker
   #   end
@@ -35,13 +35,13 @@ module Tasker
     # This follows Rails multi-database conventions but only when database is actually available
     def self.configure_database_connections
       # Ensure Tasker configuration is available - fail fast if not
-      unless defined?(::Tasker::Configuration.configuration)
-        error_message = 'Tasker::Configuration.configuration is not available. This indicates a Rails initialization order issue. ' \
+      unless defined?(Tasker.configuration)
+        error_message = 'Tasker.configuration is not available. This indicates a Rails initialization order issue. ' \
                         'Ensure Tasker is properly initialized before models are loaded.'
         raise StandardError, error_message
       end
 
-      config = ::Tasker::Configuration.configuration.database
+      config = Tasker.configuration.database
       if config.enable_secondary_database && config.name.present?
         # Check if the database configuration actually exists before calling connects_to
         if database_configuration_exists?(config.name)

data/app/models/tasker/diagram/edge.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Diagram
+    # Represents an edge (connection) between nodes in a flowchart diagram
+    class Edge
+      # @return [String] The ID of the source node
+      attr_accessor :source_id
+
+      # @return [String] The ID of the target node
+      attr_accessor :target_id
+
+      # @return [String] The label to display on the edge
+      attr_accessor :label
+
+      # @return [String] The type of edge (e.g., 'solid', 'dashed')
+      attr_accessor :type
+
+      # @return [String] Direction of the arrow (e.g., 'forward', 'back', 'both', 'none')
+      attr_accessor :direction
+
+      # @return [Hash] Additional attributes for the edge
+      attr_accessor :attributes
+
+      # Define constants for style mappings
+      EDGE_STYLES = {
+        'dashed' => '--',
+        'thick' => '==',
+        'dotted' => '-.-',
+        'solid' => '--' # Default
+      }.freeze
+
+      ARROW_STYLES = {
+        'back' => '<',
+        'both' => '<>',
+        'none' => '',
+        'forward' => '>' # Default
+      }.freeze
+
+      # Creates a new diagram edge
+      #
+      # @param source_id [String] The ID of the source node
+      # @param target_id [String] The ID of the target node
+      # @param label [String] The label to display on the edge
+      # @param type [String] The type of edge (default: 'solid')
+      # @param direction [String] Direction of the arrow (default: 'forward')
+      # @param attributes [Hash] Additional attributes for the edge
+      # @return [Edge] A new diagram edge
+      def initialize(source_id:, target_id:, label: '', type: 'solid', direction: 'forward', attributes: {})
+        @source_id = source_id
+        @target_id = target_id
+        @label = label
+        @type = type
+        @direction = direction
+        @attributes = attributes
+      end
+
+      # Convert the edge to a hash representation
+      #
+      # @return [Hash] Hash representation of the edge
+      def to_h
+        {
+          source_id: source_id,
+          target_id: target_id,
+          label: label,
+          type: type,
+          direction: direction,
+          attributes: attributes
+        }.compact
+      end
+
+      # Convert the edge to a JSON string
+      #
+      # @return [String] JSON representation of the edge
+      def to_json(*)
+        to_h.to_json(*)
+      end
+
+      # Generate Mermaid diagram syntax for this edge
+      #
+      # @return [String] Mermaid syntax for the edge
+      def to_mermaid
+        # For labeled edges, use the |label| syntax instead of adding a separate text label
+        if label&.present? # rubocop:disable Lint/RedundantSafeNavigation
+          "#{source_id} -->|\"#{escape_mermaid_text(label)}\"| #{target_id}"
+        else
+          "#{source_id} --> #{target_id}"
+        end
+      end
+
+      private
+
+      # Escape special characters in Mermaid text
+      #
+      # @param text [String] The text to escape
+      # @return [String] Escaped text safe for Mermaid diagrams
+      def escape_mermaid_text(text)
+        # Handle nil values
+        return '' if text.nil?
+
+        # Replace instances of " with ' to avoid breaking the Mermaid syntax
+        text.to_s.tr('"', "'")
+      end
+    end
+  end
+end

data/app/models/tasker/diagram/flowchart.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Diagram
+    # Represents a flowchart diagram with nodes and edges
+    class Flowchart
+      # @return [Array<Tasker::Diagram::Node>] The nodes in the flowchart
+      attr_accessor :nodes
+
+      # @return [Array<Tasker::Diagram::Edge>] The edges in the flowchart
+      attr_accessor :edges
+
+      # @return [String] The direction of the flowchart (TD: top-down, LR: left-right, etc.)
+      attr_accessor :direction
+
+      # @return [String] The title of the flowchart
+      attr_accessor :title
+
+      # @return [Hash] Additional attributes for the flowchart
+      attr_accessor :attributes
+
+      # Creates a new flowchart diagram
+      #
+      # @param nodes [Array<Tasker::Diagram::Node>] The nodes in the flowchart
+      # @param edges [Array<Tasker::Diagram::Edge>] The edges in the flowchart
+      # @param direction [String] The direction of the flowchart (default: 'TD')
+      # @param title [String, nil] The title of the flowchart
+      # @param attributes [Hash] Additional attributes for the flowchart
+      # @return [Flowchart] A new flowchart diagram
+      def initialize(nodes: [], edges: [], direction: 'TD', title: nil, attributes: {})
+        @nodes = nodes
+        @edges = edges
+        @direction = direction
+        @title = title
+        @attributes = attributes
+      end
+
+      # Add a node to the flowchart
+      #
+      # @param node [Tasker::Diagram::Node] The node to add
+      # @return [Tasker::Diagram::Node] The added node
+      def add_node(node)
+        @nodes << node
+        node
+      end
+
+      # Add an edge to the flowchart
+      #
+      # @param edge [Tasker::Diagram::Edge] The edge to add
+      # @return [Tasker::Diagram::Edge] The added edge
+      def add_edge(edge)
+        @edges << edge
+        edge
+      end
+
+      # Find a node by its ID
+      #
+      # @param id [String] The ID of the node to find
+      # @return [Tasker::Diagram::Node, nil] The node with the given ID, or nil if not found
+      def find_node(id)
+        @nodes.find { |node| node.id == id }
+      end
+
+      # Find all edges connected to a node
+      #
+      # @param node_id [String] The ID of the node
+      # @param direction [Symbol] :outgoing, :incoming, or :both (default: :both)
+      # @return [Array<Tasker::Diagram::Edge>] The edges connected to the node
+      def find_edges_for_node(node_id, direction = :both)
+        case direction
+        when :outgoing
+          @edges.select { |edge| edge.source_id == node_id }
+        when :incoming
+          @edges.select { |edge| edge.target_id == node_id }
+        else
+          @edges.select { |edge| edge.source_id == node_id || edge.target_id == node_id }
+        end
+      end
+
+      # Convert the flowchart to a hash representation
+      #
+      # @return [Hash] Hash representation of the flowchart
+      def to_h
+        {
+          nodes: nodes.map(&:to_h),
+          edges: edges.map(&:to_h),
+          direction: direction,
+          title: title,
+          attributes: attributes
+        }.compact
+      end
+
+      # Convert the flowchart to a JSON string
+      #
+      # @return [String] JSON representation of the flowchart
+      def to_json(*)
+        to_h.to_json(*)
+      end
+
+      # Generate Mermaid diagram syntax for this flowchart
+      #
+      # @return [String] Mermaid syntax for the flowchart
+      def to_mermaid
+        lines = []
+
+        # Add the flowchart definition
+        lines << "graph #{direction}"
+
+        # Use a subgraph with title if title is present
+        if title
+          lines << "subgraph \"#{title}\""
+          indent = '  '
+        else
+          indent = ''
+        end
+
+        # Add all nodes
+        nodes.each do |node|
+          node.to_mermaid.each do |line|
+            lines << "#{indent}#{line}"
+          end
+        end
+
+        # Add all edges
+        edges.each do |edge|
+          lines << "#{indent}#{edge.to_mermaid}"
+        end
+
+        # Close the subgraph if we have a title
+        lines << 'end' if title
+
+        # Join all lines with newlines
+        lines.join("\n")
+      end
+    end
+  end
+end

data/app/models/tasker/diagram/node.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Tasker
+  module Diagram
+    # Represents a node in a flowchart diagram
+    class Node
+      # @return [String] The unique identifier for this node
+      attr_accessor :id
+
+      # @return [String] The display label for this node
+      attr_accessor :label
+
+      # @return [String] The shape of the node (e.g., 'box', 'circle', 'diamond')
+      attr_accessor :shape
+
+      # @return [String] CSS styling for the node
+      attr_accessor :style
+
+      # @return [String, nil] URL to link to when clicking the node
+      attr_accessor :url
+
+      # @return [Hash] Additional attributes for the node
+      attr_accessor :attributes
+
+      # Creates a new diagram node
+      #
+      # @param id [String] The unique identifier for this node
+      # @param label [String] The display label for this node
+      # @param shape [String] The shape of the node (default: 'box')
+      # @param style [String, nil] CSS styling for the node
+      # @param url [String, nil] URL to link to when clicking the node
+      # @param attributes [Hash] Additional attributes for the node
+      # @return [Node] A new diagram node
+      def initialize(id:, label:, shape: 'box', style: nil, url: nil, attributes: {})
+        @id = id
+        @label = label
+        @shape = shape
+        @style = style
+        @url = url
+        @attributes = attributes
+      end
+
+      # Convert the node to a hash representation
+      #
+      # @return [Hash] Hash representation of the node
+      def to_h
+        {
+          id: id,
+          label: label,
+          shape: shape,
+          style: style,
+          url: url,
+          attributes: attributes
+        }.compact
+      end
+
+      # Convert the node to a JSON string
+      #
+      # @return [String] JSON representation of the node
+      def to_json(*)
+        to_h.to_json(*)
+      end
+
+      # Generate Mermaid diagram syntax for this node
+      #
+      # @return [Array<String>] Array of Mermaid syntax lines for the node
+      def to_mermaid
+        # Use HTML line breaks in the label
+        formatted_label = escape_mermaid_text(label).gsub("\n", '<br/>')
+
+        # Basic node definition
+        node_def = "#{id}[\"#{formatted_label}\"]"
+
+        # Add URL link if present
+        click_def = url ? "click #{id} \"#{escape_mermaid_text(url)}\"" : nil
+
+        # Add style definition if present
+        style_def = style ? "style #{id} #{style}" : nil
+
+        # Return node definition and optional click and style definitions
+        [node_def, click_def, style_def].compact
+      end
+
+      private
+
+      # Escape special characters in Mermaid text
+      #
+      # @param text [String] The text to escape
+      # @return [String] Escaped text safe for Mermaid diagrams
+      def escape_mermaid_text(text)
+        # Handle nil values
+        return '' if text.nil?
+
+        # Replace instances of " with ' to avoid breaking the Mermaid syntax
+        text.to_s.tr('"', "'")
+      end
+    end
+  end
+end

data/app/models/tasker/task.rb

@@ -64,6 +64,7 @@ module Tasker
     validate :unique_identity_hash, on: :create
 
     delegate :name, to: :named_task
+    delegate :to_mermaid, to: :diagram
     delegate :workflow_summary, to: :task_execution_context
 
     # State machine integration
@@ -300,6 +301,14 @@ module Tasker
       workflow_steps.includes(:named_step).where(named_step: { name: name }).first
     end
 
+    # Gets or creates a diagram representation of this task
+    #
+    # @param base_url [String, nil] The base URL to use for links in the diagram, defaults to nil
+    # @return [Tasker::TaskDiagram] The diagram representation of this task
+    def diagram(base_url = nil)
+      @diagram ||= Tasker::TaskDiagram.new(self, base_url)
+    end
+
     def runtime_analyzer
       @runtime_analyzer ||= Tasker::Analysis::RuntimeGraphAnalyzer.new(task: self)
     end
@@ -326,6 +335,7 @@ module Tasker
     def reload
       super
       @task_execution_context = nil
+      @diagram = nil
     end
 
     delegate :namespace_name, to: :named_task
@@ -401,7 +411,7 @@ module Tasker
     #
     # @return [Object] The identity strategy instance
     def identity_strategy
-      @identity_strategy ||= Tasker::Configuration.configuration.engine.identity_strategy_instance
+      @identity_strategy ||= Tasker.configuration.engine.identity_strategy_instance
     end
 
     # Sets the identity hash for this task using the configured identity strategy