taski 0.3.1 → 0.4.1

data/examples/reexecution_demo.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Taski Re-execution Demo
+#
+# This example demonstrates cache control and re-execution:
+# - Default caching behavior
+# - Task.new for fresh instances
+# - Task.reset! for clearing all caches
+#
+# Run: ruby examples/reexecution_demo.rb
+
+require_relative "../lib/taski"
+
+puts "Taski Re-execution Demo"
+puts "=" * 40
+
+# Task that generates random values (to demonstrate caching)
+class RandomGenerator < Taski::Task
+  exports :value, :timestamp
+
+  def run
+    @value = rand(1000)
+    @timestamp = Time.now.strftime("%H:%M:%S.%L")
+    puts "  RandomGenerator.run called: value=#{@value}, time=#{@timestamp}"
+  end
+end
+
+# Task that depends on RandomGenerator
+class Consumer < Taski::Task
+  exports :result
+
+  def run
+    random_value = RandomGenerator.value
+    @result = "Consumed value: #{random_value}"
+    puts "  Consumer.run called: #{@result}"
+  end
+end
+
+puts "\n1. Default Caching Behavior"
+puts "-" * 40
+puts "First call to RandomGenerator.value:"
+value1 = RandomGenerator.value
+puts "  => #{value1}"
+
+puts "\nSecond call to RandomGenerator.value (cached, no run):"
+value2 = RandomGenerator.value
+puts "  => #{value2}"
+
+puts "\nValues are identical: #{value1 == value2}"
+
+puts "\n" + "=" * 40
+puts "\n2. Using Task.new for Fresh Instance"
+puts "-" * 40
+puts "Creating new instance with RandomGenerator.new:"
+
+instance1 = RandomGenerator.new
+instance1.run
+puts "  instance1.value = #{instance1.value}"
+
+instance2 = RandomGenerator.new
+instance2.run
+puts "  instance2.value = #{instance2.value}"
+
+puts "\nNote: Each .new creates independent instance"
+puts "Class-level cache unchanged: RandomGenerator.value = #{RandomGenerator.value}"
+
+puts "\n" + "=" * 40
+puts "\n3. Using reset! to Clear Cache"
+puts "-" * 40
+puts "Before reset!:"
+puts "  RandomGenerator.value = #{RandomGenerator.value}"
+
+puts "\nCalling RandomGenerator.reset!..."
+RandomGenerator.reset!
+
+puts "\nAfter reset! (fresh execution):"
+new_value = RandomGenerator.value
+puts "  RandomGenerator.value = #{new_value}"
+
+puts "\n" + "=" * 40
+puts "\n4. Dependency Chain with Re-execution"
+puts "-" * 40
+
+# Reset both tasks
+RandomGenerator.reset!
+Consumer.reset!
+
+puts "First Consumer execution:"
+result1 = Consumer.result
+puts "  => #{result1}"
+
+puts "\nSecond Consumer execution (cached):"
+result2 = Consumer.result
+puts "  => #{result2}"
+
+puts "\nReset Consumer and re-execute:"
+Consumer.reset!
+result3 = Consumer.result
+puts "  => #{result3}"
+puts "  (Dependencies are re-resolved when task is reset)"
+
+puts "\nReset both tasks:"
+RandomGenerator.reset!
+Consumer.reset!
+result4 = Consumer.result
+puts "  => #{result4}"
+puts "  (New random value because both were reset)"
+
+puts "\n" + "=" * 40
+puts "\n5. Use Cases Summary"
+puts "-" * 40
+puts <<~SUMMARY
+  TaskClass.run / TaskClass.value
+    => Normal execution with caching (recommended for dependency graphs)
+
+  TaskClass.new.run
+    => Re-execute only this task (dependencies still use cache)
+    => Useful for: testing, one-off executions
+
+  TaskClass.reset!
+    => Clear this task's cache, next call will re-execute
+    => Useful for: environment changes, refreshing data
+SUMMARY
+
+puts "\n" + "=" * 40
+puts "Re-execution demonstration complete!"

data/examples/{section_configuration.rb → section_demo.rb}

@@ -1,17 +1,12 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Section Configuration Example
-# This example demonstrates how to use Taski::Section for dynamic implementation
-# selection and dependency resolution with configuration management.
-#
-# Key Features Demonstrated:
-# 1. DRY Principle: No need to duplicate 'exports' declarations in nested Task classes
-#    - interface declaration automatically adds exports to nested Task classes
-# 2. Consistent API: impl must return Task classes - .build is called automatically
-# 3. Dynamic Implementation Selection: Different implementations based on environment
-# 4. Dependency Resolution: Sections are properly detected in dependency analysis
-# 5. Tree Visualization: Sections appear in dependency trees
+
+# Section API Basics Example
+# This example demonstrates runtime implementation selection with the Section API
+
+# Section API is perfect for:
+# - Environment-specific implementations (dev/staging/prod)
+# - Different service adapters (AWS/GCP/local)
+# - Clean abstraction with guaranteed interfaces
 
 require_relative "../lib/taski"
 
@@ -20,10 +15,10 @@ require_relative "../lib/taski"
 # for development and production environments
 class DatabaseSection < Taski::Section
   # Define the interface that implementations must provide
-  interface :host, :port, :username, :password, :database_name, :pool_size
+  interfaces :host, :port, :username, :password, :database_name, :pool_size
 
   # Select implementation based on environment
-  # Note: Must return a Task class - .build is automatically called
+  # Note: Must return a Task class - .run is automatically called
   # No 'self' needed - just define as instance method!
   def impl
     if ENV["RAILS_ENV"] == "production"
@@ -34,9 +29,9 @@ class DatabaseSection < Taski::Section
   end
 
   # Production implementation with secure settings
-  # Note: exports are automatically inherited from interface declaration
+  # No exports needed - automatically inherited from interfaces
   class Production < Taski::Task
-    def build
+    def run
       @host = "prod-db.example.com"
       @port = 5432
       @username = "app_user"
@@ -47,9 +42,8 @@ class DatabaseSection < Taski::Section
   end
 
   # Development implementation with local settings
-  # Note: exports are automatically inherited from interface declaration
   class Development < Taski::Task
-    def build
+    def run
       @host = "localhost"
       @port = 5432
       @username = "dev_user"
@@ -63,12 +57,12 @@ end
 # Example 2: API Configuration Section
 # This section provides API endpoints and credentials
 class ApiSection < Taski::Section
-  interface :base_url, :api_key, :timeout, :retry_count
+  interfaces :base_url, :api_key, :timeout, :retry_count
 
   # No 'self' needed - just define as instance method!
   def impl
     # Select based on feature flag
-    # Note: Must return a Task class - .build is automatically called
+    # Note: Must return a Task class - .run is automatically called
     if ENV["USE_STAGING_API"] == "true"
       Staging
     else
@@ -76,9 +70,8 @@ class ApiSection < Taski::Section
     end
   end
 
-  # Note: exports are automatically inherited from interface declaration - DRY principle!
   class Production < Taski::Task
-    def build
+    def run
       @base_url = "https://api.example.com/v1"
       @api_key = ENV["PROD_API_KEY"] || "prod-key-123"
       @timeout = 30
@@ -86,9 +79,8 @@ class ApiSection < Taski::Section
     end
   end
 
-  # Note: exports are automatically inherited from interface declaration - DRY principle!
   class Staging < Taski::Task
-    def build
+    def run
       @base_url = "https://staging-api.example.com/v1"
       @api_key = ENV["STAGING_API_KEY"] || "staging-key-456"
       @timeout = 60
@@ -101,7 +93,7 @@ end
 class ApplicationSetup < Taski::Task
   exports :config_summary
 
-  def build
+  def run
     puts "Setting up application with configuration:"
     puts "Database: #{DatabaseSection.host}:#{DatabaseSection.port}/#{DatabaseSection.database_name}"
     puts "API: #{ApiSection.base_url}"
@@ -128,7 +120,7 @@ end
 class DatabaseConnection < Taski::Task
   exports :connection
 
-  def build
+  def run
     puts "Connecting to database..."
     # Use section configuration to create connection
     connection_string = "postgresql://#{DatabaseSection.username}:#{DatabaseSection.password}@#{DatabaseSection.host}:#{DatabaseSection.port}/#{DatabaseSection.database_name}"
@@ -140,7 +132,7 @@ end
 class ApiClient < Taski::Task
   exports :client
 
-  def build
+  def run
     puts "Initializing API client..."
     @client = "API Client: #{ApiSection.base_url} (timeout: #{ApiSection.timeout}s, retries: #{ApiSection.retry_count})"
     puts @client
@@ -148,12 +140,12 @@ class ApiClient < Taski::Task
 end
 
 class Application < Taski::Task
-  def build
+  def run
     puts "\n=== Starting Application ==="
 
     # Dependencies are automatically resolved
-    # DatabaseConnection and ApiClient will be built first
-    # which triggers building of their respective sections
+    # DatabaseConnection and ApiClient will be executed first
+    # which triggers execution of their respective sections
 
     puts "\nDatabase ready: #{DatabaseConnection.connection}"
     puts "API ready: #{ApiClient.client}"
@@ -165,42 +157,39 @@ class Application < Taski::Task
   end
 end
 
-# Demo script
-if __FILE__ == $0
-  puts "Taski Section Configuration Example"
-  puts "=" * 50
+puts "Taski Section Configuration Example"
+puts "=" * 50
 
-  puts "\n1. Development Environment (default)"
-  ENV["RAILS_ENV"] = "development"
-  ENV["USE_STAGING_API"] = "false"
+puts "\n1. Development Environment (default)"
+ENV["RAILS_ENV"] = "development"
+ENV["USE_STAGING_API"] = "false"
 
-  # Reset all tasks to ensure fresh build
-  [DatabaseSection, ApiSection, ApplicationSetup, DatabaseConnection, ApiClient, Application].each(&:reset!)
+# Reset all tasks to ensure fresh build
+[DatabaseSection, ApiSection, ApplicationSetup, DatabaseConnection, ApiClient, Application].each(&:reset!)
 
-  Application.build
+Application.run
 
-  puts "\n" + "=" * 50
-  puts "\n2. Production Environment with Staging API"
-  ENV["RAILS_ENV"] = "production"
-  ENV["USE_STAGING_API"] = "true"
+puts "\n" + "=" * 50
+puts "\n2. Production Environment with Staging API"
+ENV["RAILS_ENV"] = "production"
+ENV["USE_STAGING_API"] = "true"
 
-  # Reset all tasks to see different configuration
-  [DatabaseSection, ApiSection, ApplicationSetup, DatabaseConnection, ApiClient, Application].each(&:reset!)
+# Reset all tasks to see different configuration
+[DatabaseSection, ApiSection, ApplicationSetup, DatabaseConnection, ApiClient, Application].each(&:reset!)
 
-  Application.build
+Application.run
 
-  puts "\n" + "=" * 50
-  puts "\n3. Dependency Tree Visualization"
-  puts "\nApplication dependency tree:"
-  puts Application.tree
+puts "\n" + "=" * 50
+puts "\n3. Dependency Tree Visualization"
+puts "\nApplication dependency tree:"
+puts Application.tree
 
-  puts "\nDatabaseConnection dependency tree:"
-  puts DatabaseConnection.tree
+puts "\nDatabaseConnection dependency tree:"
+puts DatabaseConnection.tree
 
-  puts "\nApiClient dependency tree:"
-  puts ApiClient.tree
+puts "\nApiClient dependency tree:"
+puts ApiClient.tree
 
-  puts "\n" + "=" * 50
-  puts "\nSection dependency resolution successfully demonstrated!"
-  puts "Notice how sections appear in the dependency trees and logs."
-end
+puts "\n" + "=" * 50
+puts "\nSection dependency resolution successfully demonstrated!"
+puts "Notice how sections appear in the dependency trees and logs."

data/lib/taski/context.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Taski
+  # Runtime context accessible from any task.
+  # Holds user-defined options and execution metadata.
+  # Context is immutable after creation - options cannot be modified during task execution.
+  class Context
+    attr_reader :started_at, :working_directory, :root_task
+
+    # @param options [Hash] User-defined options (immutable after creation)
+    # @param root_task [Class] The root task class that initiated execution
+    def initialize(options:, root_task:)
+      @options = options.dup.freeze
+      @root_task = root_task
+      @started_at = Time.now
+      @working_directory = Dir.pwd
+    end
+
+    # Get a user-defined option value
+    # @param key [Symbol, String] The option key
+    # @return [Object, nil] The option value or nil if not set
+    def [](key)
+      @options[key]
+    end
+
+    # Get a user-defined option value with a default
+    # @param key [Symbol, String] The option key
+    # @param default [Object] Default value if key is not present
+    # @yield Block to compute default value if key is not present
+    # @return [Object] The option value or default
+    def fetch(key, default = nil, &block)
+      if @options.key?(key)
+        @options[key]
+      elsif block
+        block.call
+      else
+        default
+      end
+    end
+
+    # Check if a user-defined option key exists
+    # @param key [Symbol, String] The option key
+    # @return [Boolean] true if the key exists
+    def key?(key)
+      @options.key?(key)
+    end
+  end
+end

data/lib/taski/execution/coordinator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Taski
+  module Execution
+    class Coordinator
+      def initialize(registry:, analyzer:)
+        @registry = registry
+        @analyzer = analyzer
+      end
+
+      # @param task_class [Class] The task class whose dependencies should be started
+      def start_dependencies(task_class)
+        dependencies = get_dependencies(task_class)
+        return if dependencies.empty?
+
+        dependencies.each do |dep_class|
+          start_dependency_execution(dep_class)
+        end
+      end
+
+      # @param task_class [Class] The task class whose dependencies should be cleaned
+      def start_clean_dependencies(task_class)
+        dependencies = get_dependencies(task_class)
+        return if dependencies.empty?
+
+        dependencies.each do |dep_class|
+          start_dependency_clean(dep_class)
+        end
+      end
+
+      private
+
+      def get_dependencies(task_class)
+        if task_class.respond_to?(:cached_dependencies)
+          task_class.cached_dependencies
+        else
+          @analyzer.analyze(task_class)
+        end
+      end
+
+      def start_thread_with(&block)
+        thread = Thread.new(&block)
+        @registry.register_thread(thread)
+      end
+
+      def start_dependency_execution(dep_class)
+        exported_methods = dep_class.exported_methods
+
+        exported_methods.each do |method|
+          start_thread_with do
+            dep_class.public_send(method)
+          end
+        end
+      end
+
+      def start_dependency_clean(dep_class)
+        start_thread_with do
+          dep_class.public_send(:clean)
+        end
+      end
+    end
+  end
+end

data/lib/taski/execution/parallel_progress_display.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Taski
+  module Execution
+    class ParallelProgressDisplay
+      SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+      class TaskProgress
+        attr_accessor :state, :start_time, :end_time, :error, :duration
+
+        def initialize
+          @state = :pending
+          @start_time = nil
+          @end_time = nil
+          @error = nil
+          @duration = nil
+        end
+      end
+
+      def initialize(output: $stdout)
+        @output = output
+        @tasks = {}
+        @monitor = Monitor.new
+        @spinner_index = 0
+        @renderer_thread = nil
+        @running = false
+      end
+
+      # @param task_class [Class] The task class to register
+      def register_task(task_class)
+        @monitor.synchronize do
+          @tasks[task_class] = TaskProgress.new
+        end
+      end
+
+      # @param task_class [Class] The task class to check
+      # @return [Boolean] true if the task is registered
+      def task_registered?(task_class)
+        @monitor.synchronize do
+          @tasks.key?(task_class)
+        end
+      end
+
+      # @param task_class [Class] The task class to update
+      # @param state [Symbol] The new state (:pending, :running, :completed, :failed)
+      # @param duration [Float] Duration in milliseconds (for completed tasks)
+      # @param error [Exception] Error object (for failed tasks)
+      def update_task(task_class, state:, duration: nil, error: nil)
+        @monitor.synchronize do
+          progress = @tasks[task_class]
+          return unless progress
+
+          progress.state = state
+          progress.duration = duration if duration
+          progress.error = error if error
+
+          case state
+          when :running
+            progress.start_time = Time.now
+          when :completed, :failed
+            progress.end_time = Time.now
+          end
+        end
+      end
+
+      # @param task_class [Class] The task class
+      # @return [Symbol] The task state
+      def task_state(task_class)
+        @monitor.synchronize do
+          @tasks[task_class]&.state
+        end
+      end
+
+      def render
+        @monitor.synchronize do
+          @tasks.each do |task_class, progress|
+            line = format_task_line(task_class, progress)
+            @output.puts line
+          end
+        end
+      end
+
+      def start
+        return if @running
+
+        @running = true
+        @renderer_thread = Thread.new do
+          loop do
+            break unless @running
+            render_live
+            sleep 0.1
+          end
+        end
+      end
+
+      def stop
+        return unless @running
+
+        @running = false
+        @renderer_thread&.join
+        render_final
+      end
+
+      private
+
+      # @return [Array<String>] Array of formatted task lines
+      def collect_task_lines
+        @tasks.map do |task_class, progress|
+          format_task_line(task_class, progress)
+        end
+      end
+
+      def render_live
+        return unless @output.tty?
+
+        @monitor.synchronize do
+          @spinner_index += 1
+
+          lines = collect_task_lines
+
+          lines.each_with_index do |line, index|
+            @output.print "\r\e[K#{line}"
+            @output.print "\n" unless index == lines.length - 1
+          end
+
+          @output.print "\e[#{lines.length - 1}A" if lines.length > 1
+        end
+      end
+
+      def render_final
+        @monitor.synchronize do
+          lines = collect_task_lines
+
+          if @output.tty? && lines.length > 0
+            lines.each_with_index do |_, index|
+              @output.print "\r\e[K"
+              @output.print "\e[1B" unless index == lines.length - 1
+            end
+            @output.print "\e[#{lines.length - 1}A" if lines.length > 1
+          end
+
+          lines.each do |line|
+            @output.puts line
+          end
+        end
+      end
+
+      # @param task_class [Class] The task class
+      # @param progress [TaskProgress] The task progress
+      # @return [String] Formatted line
+      def format_task_line(task_class, progress)
+        icon = task_icon(progress.state)
+        name = task_class.name || "AnonymousTask"
+        details = task_details(progress)
+
+        "#{icon} #{name}#{details}"
+      end
+
+      # @param state [Symbol] The task state
+      # @return [String] The icon character
+      def task_icon(state)
+        case state
+        when :completed
+          "✅"
+        when :failed
+          "❌"
+        when :running
+          spinner_char
+        when :pending
+          "⏳"
+        else
+          "❓"
+        end
+      end
+
+      # @return [String] Current spinner frame
+      def spinner_char
+        SPINNER_FRAMES[@spinner_index % SPINNER_FRAMES.length]
+      end
+
+      # @param progress [TaskProgress] The task progress
+      # @return [String] Details string
+      def task_details(progress)
+        case progress.state
+        when :completed
+          " (#{progress.duration}ms)"
+        when :failed
+          " (failed)"
+        when :running
+          " (running)"
+        when :pending
+          " (pending)"
+        else
+          ""
+        end
+      end
+    end
+  end
+end