taski 0.4.2 → 0.7.0

data/examples/reexecution_demo.rb

@@ -1,21 +1,21 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Taski Re-execution Demo
+# Taski Scope-Based Execution Demo
 #
-# This example demonstrates cache control and re-execution:
-# - Default caching behavior
-# - Task.new for fresh instances
-# - Task.reset! for clearing all caches
+# This example demonstrates the execution model:
+# - Task.run / Task.value: Fresh execution every time
+# - Task.new.run: Instance-level caching
+# - Dependencies within same execution scope share results
 #
-# Run: ruby examples/reexecution_demo.rb
+# Run: TASKI_PROGRESS_DISABLE=1 ruby examples/reexecution_demo.rb
 
 require_relative "../lib/taski"
 
-puts "Taski Re-execution Demo"
-puts "=" * 40
+puts "Taski Scope-Based Execution Demo"
+puts "=" * 50
 
-# Task that generates random values (to demonstrate caching)
+# Task that generates random values (to demonstrate execution behavior)
 class RandomGenerator < Taski::Task
   exports :value, :timestamp
 
@@ -23,6 +23,7 @@ class RandomGenerator < Taski::Task
     @value = rand(1000)
     @timestamp = Time.now.strftime("%H:%M:%S.%L")
     puts "  RandomGenerator.run called: value=#{@value}, time=#{@timestamp}"
+    @value
   end
 end
 
@@ -32,96 +33,108 @@ class Consumer < Taski::Task
 
   def run
     random_value = RandomGenerator.value
-    @result = "Consumed value: #{random_value}"
-    puts "  Consumer.run called: #{@result}"
+    @result = "Consumed: #{random_value}"
+    puts "  Consumer.run called with RandomGenerator.value=#{random_value}"
+    @result
   end
 end
 
-puts "\n1. Default Caching Behavior"
-puts "-" * 40
-puts "First call to RandomGenerator.value:"
+# Task that accesses RandomGenerator twice
+class DoubleConsumer < Taski::Task
+  exports :first_value, :second_value
+
+  def run
+    @first_value = RandomGenerator.value
+    puts "  DoubleConsumer: first access = #{@first_value}"
+    @second_value = RandomGenerator.value
+    puts "  DoubleConsumer: second access = #{@second_value}"
+  end
+end
+
+puts "\n1. Class Method Calls: Fresh Execution Every Time"
+puts "-" * 50
+puts "Each Task.value call creates a NEW execution:"
+puts "\nFirst call:"
 value1 = RandomGenerator.value
 puts "  => #{value1}"
 
-puts "\nSecond call to RandomGenerator.value (cached, no run):"
+puts "\nSecond call (NEW execution, different value):"
 value2 = RandomGenerator.value
 puts "  => #{value2}"
 
-puts "\nValues are identical: #{value1 == value2}"
+puts "\nValues are different: #{value1 != value2}"
+
+puts "\n" + "=" * 50
+puts "\n2. Task.new: Instance-Level Caching"
+puts "-" * 50
+puts "Same instance caches the result:"
+
+instance = RandomGenerator.new
+puts "\nFirst run on instance:"
+result1 = instance.run
+puts "  instance.value = #{instance.value}"
+
+puts "\nSecond run on same instance (returns cached):"
+result2 = instance.run
+puts "  instance.value = #{instance.value}"
+
+puts "\nSame result: #{result1 == result2}"
 
-puts "\n" + "=" * 40
-puts "\n2. Using Task.new for Fresh Instance"
-puts "-" * 40
-puts "Creating new instance with RandomGenerator.new:"
+puts "\n" + "=" * 50
+puts "\n3. Different Instances: Independent Executions"
+puts "-" * 50
 
 instance1 = RandomGenerator.new
 instance1.run
-puts "  instance1.value = #{instance1.value}"
+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 "instance2.value = #{instance2.value}"
+
+puts "\nDifferent values: #{instance1.value != instance2.value}"
+
+puts "\n" + "=" * 50
+puts "\n4. Scope-Based Caching for Dependencies"
+puts "-" * 50
+puts "Within ONE execution, dependencies are cached:"
+
+puts "\nDoubleConsumer accesses RandomGenerator.value twice:"
+DoubleConsumer.run
+
+puts "\nNote: Both accesses return the SAME value!"
+puts "(Because they're in the same execution scope)"
+
+puts "\n" + "=" * 50
+puts "\n5. Dependency Chain with Fresh Execution"
+puts "-" * 50
+
+puts "Each Consumer.run creates fresh RandomGenerator:"
+puts "\nFirst Consumer.run:"
+Consumer.run
+
+puts "\nSecond Consumer.run (different RandomGenerator value):"
+Consumer.run
+
+puts "\n" + "=" * 50
+puts "\n6. Use Cases Summary"
+puts "-" * 50
 puts <<~SUMMARY
   TaskClass.run / TaskClass.value
-    => Normal execution with caching (recommended for dependency graphs)
+    => Fresh execution every time
+    => Dependencies within same execution are cached
+    => Use for: Independent executions, scripts
 
   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
+    => Instance caches results
+    => Multiple .run calls return cached value
+    => Use for: Re-execution control, testing
+
+  instance.reset!
+    => Clears instance cache
+    => Next .run will execute fresh
+    => Use for: Re-running same instance
 SUMMARY
 
-puts "\n" + "=" * 40
-puts "Re-execution demonstration complete!"
+puts "\n" + "=" * 50
+puts "Scope-Based Execution demonstration complete!"

data/examples/system_call_demo.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taski"
+
+# Demo: Subprocess output capture with system()
+#
+# This example demonstrates how Taski captures output from system() calls
+# and displays them in the progress spinner.
+# Run with: ruby examples/system_call_demo.rb
+
+class SlowOutputTask < Taski::Task
+  exports :success
+
+  def run
+    puts "Running command with streaming output..."
+    # Use a command that produces output over time
+    @success = system("for i in 1 2 3 4 5; do echo \"Processing step $i...\"; sleep 0.3; done")
+  end
+end
+
+class AnotherSlowTask < Taski::Task
+  exports :result
+
+  def run
+    puts "Running another slow command..."
+    @result = system("for i in A B C; do echo \"Stage $i complete\"; sleep 0.4; done")
+  end
+end
+
+class MainTask < Taski::Task
+  exports :summary
+
+  def run
+    puts "Starting main task..."
+    slow1 = SlowOutputTask.success
+    slow2 = AnotherSlowTask.result
+    @summary = {slow1: slow1, slow2: slow2}
+    puts "All done!"
+  end
+end
+
+puts "=" * 60
+puts "Subprocess Output Capture Demo"
+puts "Watch the spinner show system() output in real-time!"
+puts "=" * 60
+puts
+
+Taski.progress_display&.start
+result = MainTask.summary
+Taski.progress_display&.stop
+
+puts
+puts "=" * 60
+puts "Result: #{result.inspect}"
+puts "=" * 60

data/examples/tree_progress_demo.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taski"
+
+# Demo for tree-based progress display
+# Run with: ruby examples/tree_progress_demo.rb
+
+# Database configuration section with multiple impl candidates
+class DatabaseSection < Taski::Section
+  interfaces :connection_string
+
+  def impl
+    if ENV["USE_PROD_DB"] == "1"
+      ProductionDB
+    else
+      DevelopmentDB
+    end
+  end
+
+  class ProductionDB < Taski::Task
+    def run
+      puts "Connecting to production database..."
+      sleep(0.5)
+      puts "Production DB connected"
+      @connection_string = "postgresql://prod-server:5432/myapp"
+    end
+  end
+
+  class DevelopmentDB < Taski::Task
+    def run
+      puts "Connecting to development database..."
+      sleep(0.3)
+      puts "Development DB connected"
+      @connection_string = "postgresql://localhost:5432/myapp_dev"
+    end
+  end
+end
+
+# API section with multiple impl candidates
+class ApiSection < Taski::Section
+  interfaces :base_url
+
+  def impl
+    if ENV["USE_STAGING_API"] == "1"
+      StagingApi
+    else
+      ProductionApi
+    end
+  end
+
+  class ProductionApi < Taski::Task
+    def run
+      puts "Initializing production API..."
+      sleep(0.4)
+      @base_url = "https://api.example.com"
+    end
+  end
+
+  class StagingApi < Taski::Task
+    def run
+      puts "Initializing staging API..."
+      sleep(0.2)
+      @base_url = "https://staging.api.example.com"
+    end
+  end
+end
+
+# Task with stdout output
+class FetchUserData < Taski::Task
+  exports :users
+
+  def run
+    puts "Fetching users from database..."
+    sleep(0.3)
+    puts "Found 100 users"
+    sleep(0.2)
+    puts "Processing user records..."
+    sleep(0.3)
+    puts "User data ready"
+    @users = ["Alice", "Bob", "Charlie"]
+  end
+end
+
+class FetchProductData < Taski::Task
+  exports :products
+
+  def run
+    puts "Loading product catalog..."
+    sleep(0.4)
+    puts "Fetched 50 products"
+    sleep(0.2)
+    puts "Indexing products..."
+    sleep(0.3)
+    @products = ["Widget", "Gadget", "Thing"]
+  end
+end
+
+class BuildReport < Taski::Task
+  exports :report
+
+  def run
+    db = DatabaseSection.connection_string
+    api = ApiSection.base_url
+    users = FetchUserData.users
+    products = FetchProductData.products
+
+    puts "Building report..."
+    sleep(0.2)
+    puts "Aggregating data from #{users.size} users..."
+    sleep(0.3)
+    puts "Processing #{products.size} products..."
+    sleep(0.2)
+    puts "Report generated successfully"
+
+    @report = {
+      database: db,
+      api: api,
+      user_count: users.size,
+      product_count: products.size
+    }
+  end
+end
+
+class SendNotification < Taski::Task
+  exports :notification_sent
+
+  def run
+    BuildReport.report
+    puts "Sending notification..."
+    sleep(0.2)
+    puts "Email sent to admin@example.com"
+    @notification_sent = true
+  end
+end
+
+class Application < Taski::Task
+  exports :status
+
+  def run
+    notification = SendNotification.notification_sent
+    puts "Application startup complete"
+    @status = notification ? "success" : "failed"
+  end
+end
+
+# Show tree structure before execution
+puts "Task Tree Structure:"
+puts "=" * 60
+puts Application.tree
+puts "=" * 60
+puts
+
+# Reset for execution
+Application.reset!
+
+# Execute with tree progress display (start/stop handled automatically by Executor)
+result = Application.status
+
+puts "\n"
+puts "=" * 60
+puts "Execution completed!"
+puts "Status: #{result}"
+puts "Report: #{BuildReport.report.inspect}"

data/lib/taski/{context.rb → args.rb}

@@ -3,10 +3,10 @@
 require "monitor"
 
 module Taski
-  # Runtime context accessible from any task.
+  # Runtime arguments 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
+  # Args is immutable after creation - options cannot be modified during task execution.
+  class Args
     attr_reader :started_at, :working_directory, :root_task
 
     # @param options [Hash] User-defined options (immutable after creation)